Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { setCommandExitCode } from "../../utils/commandResult.js";
import { createWriteStream, existsSync, readFileSync, unlinkSync } from "node:fs";
import { resolve, join, basename } from "node:path";
import { c } from "../../ui/colors.js";
import { safeFetch } from "../../capture/assetDownloader.js";
import { ensureCaptureDirSync } from "../../capture/captureFile.js";
import { CAPTURE_USER_AGENT } from "../../capture/userAgent.js";
const MAX_VIDEO_BYTES = 250 * 1024 * 1024;
const VIDEO_CONTENT_TYPE_RE = /^(video\/|application\/(mp4|octet-stream|x-mpegurl))/i;
// fallow-ignore-next-line complexity
async function streamToFile(url: string, destPath: string): Promise<number> {
// safeFetch re-validates redirect hops; bare redirect:"follow" leaks to private hosts.
const r = await safeFetch(url, {
signal: AbortSignal.timeout(120_000),
headers: { "User-Agent": CAPTURE_USER_AGENT },
});
if (!r) {
throw new Error(
`fetch blocked or failed (private/metadata host, redirect chain, or network error): ${url}`,
);
}
if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText} for ${url}`);
const ct = r.headers.get("content-type") || "";
if (!VIDEO_CONTENT_TYPE_RE.test(ct)) {
throw new Error(
`unexpected content-type "${ct}" for ${url} — expected video/*. The URL probably doesn't point at a real video file.`,
);
}
const cl = r.headers.get("content-length");
if (cl && Number(cl) > MAX_VIDEO_BYTES) {
throw new Error(
`video too large (${Math.round(Number(cl) / 1024 / 1024)}MB > ${Math.round(MAX_VIDEO_BYTES / 1024 / 1024)}MB cap) for ${url}`,
);
}
if (!r.body) throw new Error(`empty response body for ${url}`);
// `flags: "wx"` = exclusive-create; throws EEXIST if destPath exists. Stream chunks
// and abort mid-transfer if cumulative bytes exceed the cap so a hostile CDN can't
// OOM the process by lying about content-length.
const file = createWriteStream(destPath, { flags: "wx" });
// Single shared error promise: avoids re-attaching `error` listeners per chunk (MaxListeners warning).
let streamError: Error | null = null;
const streamErrored = new Promise<never>((_, reject) => {
file.once("error", (e) => {
streamError = e;
reject(e);
});
});
let bytes = 0;
try {
await Promise.race([
streamErrored,
new Promise<void>((resolveOpen) => file.once("open", () => resolveOpen())),
]);
for await (const chunk of r.body as unknown as AsyncIterable<Uint8Array>) {
if (streamError) throw streamError;
bytes += chunk.byteLength;
if (bytes > MAX_VIDEO_BYTES) {
throw new Error(
`video exceeded ${Math.round(MAX_VIDEO_BYTES / 1024 / 1024)}MB cap mid-stream for ${url}`,
);
}
// lgtm[js/http-to-file-access] — manifest-vetted URL, content-type whitelist, 250MB cap with mid-stream abort, SSRF-safe fetch
if (!file.write(chunk)) {
await Promise.race([
streamErrored,
new Promise<void>((resolveDrain) => file.once("drain", () => resolveDrain())),
]);
}
}
await new Promise<void>((resolveEnd, rejectEnd) => {
file.end((err?: Error | null) => (err ? rejectEnd(err) : resolveEnd()));
});
return bytes;
} catch (e) {
file.destroy();
// EEXIST means destPath ALREADY existed before we wrote anything — leave it alone.
// Any other error means we created a partial file that the caller should not see.
if ((e as NodeJS.ErrnoException).code !== "EEXIST") {
try {
unlinkSync(destPath);
} catch {
/* partial file may not exist */
}
}
throw e;
}
}
export function safeFilename(name: string): string {
let decoded = name;
try {
decoded = decodeURIComponent(name);
} catch {
/* malformed percent-encoding */
}
return decoded.replace(/[^A-Za-z0-9._-]+/g, "_");
}
export { VIDEO_CONTENT_TYPE_RE, MAX_VIDEO_BYTES };
export interface ManifestEntry {
index: number;
url: string;
filename: string;
width: number;
height: number;
/** Intrinsic clip resolution (videoWidth/Height). Optional — absent in
* manifests written before source dims were recorded. Size off these, not
* the display box (width/height). */
sourceWidth?: number;
sourceHeight?: number;
heading: string;
caption: string;
ariaLabel: string;
preview: string;
}
export type PickResult =
| { ok: true; entry: ManifestEntry }
| {
ok: false;
code: "no-selector" | "bad-index" | "no-match-index" | "no-match-url";
message: string;
};
// Two manifest entries can produce the same safeFilename (URL-encoded variants of the same name
// collapse after decode). The wx exclusive-create + EEXIST handler would silently misreport the
// second as "already downloaded" while serving the first's bytes. Fail loudly instead.
export function findFilenameCollision(
manifest: ManifestEntry[],
selected: ManifestEntry,
): ManifestEntry[] {
const selectedName = safeFilename(selected.filename || basename(selected.url));
return manifest.filter(
(e) =>
e.index !== selected.index && safeFilename(e.filename || basename(e.url)) === selectedName,
);
}
// Looks up by `entry.index`, not array offset — captureVideoManifest leaves gaps when previews fail.
export function pickManifestEntry(
manifest: ManifestEntry[],
args: { index?: string | number | null; url?: string | null },
): PickResult {
if (args.index != null) {
const i = Number(args.index);
if (!Number.isInteger(i) || i < 0) {
return {
ok: false,
code: "bad-index",
message: `--index ${args.index} must be a non-negative integer`,
};
}
const found = manifest.find((e) => e.index === i);
if (!found) {
const available = manifest.map((e) => e.index).join(", ");
return {
ok: false,
code: "no-match-index",
message: `no manifest entry with index=${i} (available: ${available || "none"})`,
};
}
return { ok: true, entry: found };
}
if (args.url != null) {
const found = manifest.find((e) => e.url === args.url);
if (!found) {
return { ok: false, code: "no-match-url", message: `no manifest entry with url=${args.url}` };
}
return { ok: true, entry: found };
}
return {
ok: false,
code: "no-selector",
message: "specify --index <N> or --url <URL> (or --list to see what's in the manifest)",
};
}
export interface VideoModeArgs {
project: string;
index?: string | null;
url?: string | null;
list?: boolean;
}
// fallow-ignore-next-line complexity
export async function runVideoMode(args: VideoModeArgs): Promise<void> {
const projectDir = resolve(args.project);
// standalone capture writes `<dir>/extracted/…`; W2H project nests under `<dir>/capture/extracted/…`.
const directPath = join(projectDir, "extracted", "video-manifest.json");
const w2hPath = join(projectDir, "capture", "extracted", "video-manifest.json");
const manifestPath = existsSync(directPath) ? directPath : w2hPath;
const isW2hLayout = manifestPath === w2hPath;
if (!existsSync(manifestPath)) {
console.error(
`${c.error("✗")} no video-manifest.json at ${directPath} or ${w2hPath}\n` +
` Was this directory produced by \`hyperframes capture\`?`,
);
setCommandExitCode(1);
return;
}
let manifest: ManifestEntry[];
try {
manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
} catch (e) {
console.error(`${c.error("✗")} video-manifest.json is malformed: ${(e as Error).message}`);
setCommandExitCode(1);
return;
}
if (args.list) {
if (manifest.length === 0) {
console.log(c.dim("(manifest is empty — no <video> elements on the captured page)"));
return;
}
console.log(
`${manifest.length} video entr${manifest.length === 1 ? "y" : "ies"} in ${manifestPath}:`,
);
for (const e of manifest) {
console.log(
` ${c.bold(`[${e.index}]`)} ${e.filename} — ${e.sourceWidth || e.width}×${e.sourceHeight || e.height}` +
(e.heading ? `\n heading: "${e.heading}"` : "") +
`\n url: ${e.url}`,
);
}
return;
}
const pick = pickManifestEntry(manifest, args);
if (!pick.ok) {
console.error(
`${c.error("✗")} ${pick.message}` +
(pick.code === "no-match-url" ? `\n Run with --list to see what's available.` : ""),
);
setCommandExitCode(1);
return;
}
const entry = pick.entry;
const collisions = findFilenameCollision(manifest, entry);
if (collisions.length > 0) {
console.error(
`${c.error("✗")} filename "${safeFilename(entry.filename || basename(entry.url))}" ` +
`collides with manifest entr${collisions.length === 1 ? "y" : "ies"} ` +
`${collisions.map((co) => `[${co.index}]`).join(", ")}. ` +
`Refusing to download — the on-disk file's bytes would not match the requested entry.`,
);
setCommandExitCode(1);
return;
}
const outDir = isW2hLayout
? join(projectDir, "capture", "assets", "videos")
: join(projectDir, "assets", "videos");
try {
ensureCaptureDirSync(projectDir, outDir);
} catch (e) {
console.error(`${c.error("✗")} ${(e as Error).message}`);
setCommandExitCode(1);
return;
}
const fname = safeFilename(entry.filename || basename(entry.url));
const outPath = join(outDir, fname);
const relPath = isW2hLayout ? `capture/assets/videos/${fname}` : `assets/videos/${fname}`;
console.log(
`${c.accent("▸")} downloading [${entry.index}] ${entry.filename} (${entry.sourceWidth || entry.width}×${entry.sourceHeight || entry.height})`,
);
console.log(` from: ${entry.url}`);
try {
const bytes = await streamToFile(entry.url, outPath);
const sizeKb = Math.round(bytes / 1024);
const sizeStr = sizeKb > 1024 ? `${(sizeKb / 1024).toFixed(1)}MB` : `${sizeKb}KB`;
console.log(`${c.success("◇")} wrote ${relPath} (${sizeStr})`);
const snippetId = `video-${entry.index}`;
console.log(
` Reference it from a beat composition as:\n` +
` <video id="${snippetId}" src="${relPath}" data-start="0" data-duration="${(entry.sourceWidth || entry.width) === (entry.sourceHeight || entry.height) ? 5 : 4}" data-track-index="0" autoplay muted loop></video>`,
);
} catch (e) {
if ((e as NodeJS.ErrnoException).code === "EEXIST") {
console.log(`${c.warn("⚠")} already downloaded: ${relPath} (skipping)`);
console.log(` Delete the file and re-run to refetch.`);
return;
}
console.error(`${c.error("✗")} download failed: ${(e as Error).message}`);
setCommandExitCode(1);
}
}