@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/scene/inspect/run.ts

@@ -0,0 +1,200 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { linesToBeats, scriptTemplate, validateScript, type ScriptFile } from "../../generate/script.js";
+import { ensureChrome } from "../../render/html-engine.js";
+import { sceneTimingFor } from "../audio.js";
+import { startNetGuard } from "../net-guard.js";
+import { GSAP_CDN, SCENE_FRAME } from "../render.js";
+import { checkScene, SceneError, storeScene } from "../scene.js";
+import { SUPPLY_DIR, writeSupply } from "../supply.js";
+import { COLLECT, HOOK, LOAD_SUBS } from "./page-scripts.js";
+import { buildReport, type InspectReport, type Raw, type SceneFile } from "./report.js";
+import { annotateHtml, parseRules, scanHtml, type Rule } from "./source.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface InspectOptions {
+  dir: string;
+  at: number;
+  selector?: string | null;
+  text?: string | null;
+  script?: ScriptFile;
+  env?: Env;
+  cwd?: string;
+  /** Most elements to describe when nothing narrows the query. */
+  limit?: number;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".mp4": "video/mp4",
+  ".wav": "audio/wav",
+  ".mp3": "audio/mpeg",
+};
+
+interface Sub {
+  src: string;
+  css: string;
+  scripts: Array<{ text: string; line: number; col: number; file: string }>;
+}
+
+/** The scene's own files, read once: positions of tags, style rules, and the blocks it mounts. */
+export async function readSceneFiles(dir: string): Promise<{ files: Map<string, SceneFile>; rules: Rule[]; subs: Sub[]; matchers: string[] }> {
+  const files = new Map<string, SceneFile>();
+  const rules: Rule[] = [];
+  const matchers: string[] = [];
+  const subs: Sub[] = [];
+  const load = async (rel: string): Promise<SceneFile | null> => {
+    const abs = path.resolve(dir, rel);
+    if (!abs.startsWith(`${dir}${path.sep}`)) return null;
+    const source = await readFile(abs, "utf8").catch(() => null);
+    if (source === null) return null;
+    const file = { label: rel, source, scan: scanHtml(source) };
+    files.set(rel, file);
+    return file;
+  };
+  const main = await load("index.html");
+  if (!main) throw new SceneError(`The scene folder ${dir} has no index.html.`, "write one, or run `npx vfrey scene init DIR`.", "scene_missing");
+  const addRules = (found: Rule[], scope: string | null) => {
+    for (const rule of found) {
+      const match = scope ? (/#root\b/.test(rule.selector) ? rule.selector.replace(/#root\b/g, scope) : null) : rule.selector;
+      if (match === null || (scope && rule.atrule)) continue;
+      rules.push(rule);
+      matchers.push(match);
+    }
+  };
+  const sheets = async (file: SceneFile, scope: string | null) => {
+    for (const block of file.scan.blocks) if (block.kind === "style") addRules(parseRules(block.text, file.label, block, rules.length), scope);
+    for (const tag of file.scan.tags) {
+      if (tag.name !== "link" || !/stylesheet/i.test(tag.attrs.rel ?? "") || !tag.attrs.href || /^[a-z]+:|^\/\//i.test(tag.attrs.href)) continue;
+      const rel = path.posix.normalize(path.posix.join(path.posix.dirname(file.label), tag.attrs.href));
+      if (rel.startsWith(`${SUPPLY_DIR}/`) || rel.startsWith("..")) continue;
+      const css = await readFile(path.resolve(dir, rel), "utf8").catch(() => null);
+      if (css !== null) addRules(parseRules(css, rel, { line: 1, col: 1 }, rules.length), scope);
+    }
+  };
+  await sheets(main, null);
+  for (const tag of main.scan.tags) {
+    const src = tag.attrs["data-composition-src"];
+    if (!src || /^[a-z]+:|^\//i.test(src)) continue;
+    const rel = path.posix.normalize(src);
+    const sub = await load(rel);
+    if (!sub) continue;
+    const name = sub.scan.tags.find((t) => t.attrs["data-composition-id"])?.attrs["data-composition-id"] ?? "";
+    const scope = `[data-composition-id="${name}"]`;
+    const before = rules.length;
+    await sheets(sub, scope);
+    const css = rules
+      .slice(before)
+      .map((r, i) => `${matchers[before + i]} { ${r.decls.map((d) => `${d.prop}: ${d.value}${d.important ? " !important" : ""}`).join("; ")} }`)
+      .join("\n");
+    const scripts = sub.scan.blocks.filter((b) => b.kind === "script" && !b.attrs.src).map((b) => ({ text: b.text, line: b.line, col: b.col, file: rel }));
+    subs.push({ src, css, scripts });
+  }
+  return { files, rules, subs, matchers };
+}
+
+async function serve(dir: string): Promise<{ origin: string; close: () => Promise<void> }> {
+  const server = http.createServer((req, res) => {
+    void (async () => {
+      const rel = decodeURIComponent((req.url ?? "/").split(/[?#]/)[0]!).replace(/^\/+/, "") || "index.html";
+      const abs = path.resolve(dir, rel);
+      if (!abs.startsWith(`${dir}${path.sep}`)) {
+        res.writeHead(403).end();
+        return;
+      }
+      try {
+        let body: Buffer | string = await readFile(abs);
+        const ext = path.extname(abs).toLowerCase();
+        if (ext === ".html") {
+          const original = body.toString("utf8");
+          body = annotateHtml(original, rel);
+          if (rel === "index.html") body = body.replace(GSAP_CDN, `<script src="${SUPPLY_DIR}/gsap.min.js"></script>`);
+        }
+        res.writeHead(200, { "content-type": TYPES[ext] ?? "application/octet-stream", "cache-control": "no-store" }).end(body);
+      } catch {
+        res.writeHead(404).end("not found");
+      }
+    })();
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  return { origin: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, close: () => new Promise<void>((resolve) => server.close(() => resolve())) };
+}
+
+/** Loads the scene in headless Chrome the way `render --frame` does (network blocked, vfrey's files supplied), seeks to `at`, and reports. */
+export async function inspectScene(options: InspectOptions): Promise<InspectReport> {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const dir = path.resolve(options.dir);
+  const info = await checkScene(dir, "vfrey-framey");
+  void info;
+  const work = await mkdtemp(path.join(os.tmpdir(), "vfrey-inspect-"));
+  const warnings: string[] = [];
+  let guard: Awaited<ReturnType<typeof startNetGuard>> | null = null;
+  let server: Awaited<ReturnType<typeof serve>> | null = null;
+  let browser: { close(): Promise<void> } | null = null;
+  try {
+    const script = options.script ?? (validateScript(scriptTemplate()) as { ok: true; script: ScriptFile }).script;
+    const stored = path.join(work, "scene");
+    for (const message of (await storeScene(dir, stored)).warnings) warnings.push(message);
+    const timing = await sceneTimingFor({ title: script.title, lines: script.lines, beats: linesToBeats(script.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption })) }, null, env);
+    await writeSupply({ dir: stored, timing, voiceFile: null, kind: "html", env });
+    const { files, rules, subs, matchers } = await readSceneFiles(stored);
+    const chrome = await ensureChrome(env, cwd);
+    guard = await startNetGuard(chrome, path.join(work, "guard"));
+    server = await serve(stored);
+    const puppeteer = (await import("puppeteer-core")).default;
+    const launched = await puppeteer.launch({
+      executablePath: guard.chrome,
+      headless: "shell",
+      defaultViewport: { width: SCENE_FRAME.width, height: SCENE_FRAME.height, deviceScaleFactor: 1 },
+      args: ["--no-sandbox", "--disable-gpu", "--hide-scrollbars", "--font-render-hinting=none"],
+    });
+    browser = launched;
+    const page = await launched.newPage();
+    await page.evaluateOnNewDocument(HOOK);
+    page.on("pageerror", (error) => warnings.push(`the scene threw: ${error instanceof Error ? error.message : String(error)}`));
+    await page.goto(`${server.origin}/index.html`, { waitUntil: "load", timeout: 30_000 });
+    await page.evaluate(`(${LOAD_SUBS})(${JSON.stringify(subs)})`);
+    await page.evaluate("document.fonts.ready.then(() => undefined)");
+    await page.evaluate("new Promise((resolve) => setTimeout(resolve, 100))");
+    await page.evaluate(COLLECT);
+    const limit = options.limit ?? 60;
+    const params = { at: options.at, selector: options.selector ?? null, text: options.text ?? null, limit, rules: matchers.map((sel, i) => ({ i, sel })) };
+    const raw = (await page.evaluate(`window.__vfCollect(${JSON.stringify(params)})`)) as Raw;
+    for (const host of guard.blocked()) warnings.push(`The scene tried to reach ${host} over the network. The network is blocked while a scene renders, so the request failed.`);
+    return buildReport({
+      raw,
+      files,
+      rules,
+      origin: server.origin,
+      scene: path.basename(dir),
+      at: options.at,
+      query: { selector: options.selector ?? null, text: options.text ?? null },
+      warnings,
+    });
+  } finally {
+    await browser?.close().catch(() => undefined);
+    await server?.close().catch(() => undefined);
+    await guard?.close().catch(() => undefined);
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/scene/inspect/source.ts

@@ -0,0 +1,236 @@
+/**
+ * Source positions for `vfrey scene inspect`: where an element, a CSS declaration or a GSAP call sits in the
+ * scene's files. HTML is scanned for tag positions (and annotated with `data-vfsrc` on the same line, so the browser
+ * can hand the position back), CSS is parsed with css-tree, and stack traces from the page are turned into file:line:col.
+ * The idea (runtime provenance: hook GSAP before the author's scripts and keep the stack of every call) is the one
+ * Framey's component inspector uses (packages/inspector at commit 9d89309, Apache-2.0 HeyGen-based). No code is copied from it: it is built
+ * for Bun, a bundled page and Framey's runtime, so this is a small independent implementation for vfrey's own scene files.
+ */
+import { generate, parse, walk } from "css-tree";
+
+export interface Pos {
+  file: string;
+  line: number;
+  col: number;
+}
+
+export interface Tag {
+  name: string;
+  /** Offset of `<`. */
+  at: number;
+  /** Offset just after the tag name, where an attribute can be inserted. */
+  nameEnd: number;
+  line: number;
+  col: number;
+  attrs: Record<string, string>;
+}
+
+export interface Block {
+  kind: "script" | "style";
+  text: string;
+  /** Position of the first character of `text`. */
+  line: number;
+  col: number;
+  attrs: Record<string, string>;
+}
+
+export interface Scan {
+  tags: Tag[];
+  blocks: Block[];
+}
+
+/** Line and column (both 1-based) of an offset. */
+export function lineCol(source: string, offset: number): { line: number; col: number } {
+  let line = 1;
+  let last = -1;
+  for (let i = source.indexOf("\n"); i !== -1 && i < offset; i = source.indexOf("\n", i + 1)) {
+    line += 1;
+    last = i;
+  }
+  return { line, col: offset - last };
+}
+
+function parseAttrs(text: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const re = /([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+  for (let m = re.exec(text); m; m = re.exec(text)) attrs[m[1]!.toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+  return attrs;
+}
+
+/** Every opening tag, script and style block of an HTML file, with positions. Comments and raw text are skipped. */
+export function scanHtml(source: string): Scan {
+  const tags: Tag[] = [];
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < source.length) {
+    const lt = source.indexOf("<", i);
+    if (lt === -1) break;
+    if (source.startsWith("<!--", lt)) {
+      const close = source.indexOf("-->", lt + 4);
+      i = close === -1 ? source.length : close + 3;
+      continue;
+    }
+    const open = /^<([a-zA-Z][\w:-]*)/.exec(source.slice(lt, lt + 80));
+    if (!open) {
+      const close = source.indexOf(">", lt);
+      i = close === -1 ? source.length : close + 1;
+      continue;
+    }
+    let j = lt + open[0].length;
+    let quote = "";
+    for (; j < source.length; j += 1) {
+      const c = source[j]!;
+      if (quote) {
+        if (c === quote) quote = "";
+      } else if (c === '"' || c === "'") quote = c;
+      else if (c === ">") break;
+    }
+    const name = open[1]!.toLowerCase();
+    const { line, col } = lineCol(source, lt);
+    const attrs = parseAttrs(source.slice(lt + open[0].length, j).replace(/\/\s*$/, ""));
+    tags.push({ name, at: lt, nameEnd: lt + open[0].length, line, col, attrs });
+    i = j + 1;
+    if (name === "script" || name === "style") {
+      const found = new RegExp(`</${name}\\s*>`, "i").exec(source.slice(i));
+      const stop = found ? i + found.index : source.length;
+      const start = lineCol(source, i);
+      blocks.push({ kind: name, text: source.slice(i, stop), line: start.line, col: start.col, attrs });
+      i = found ? stop + found[0].length : source.length;
+    }
+  }
+  return { tags, blocks };
+}
+
+/** The HTML with ` data-vfsrc="file:line:col"` added to every opening tag. No newline is added, so lines stay the same. */
+export function annotateHtml(source: string, file: string, scan: Scan = scanHtml(source)): string {
+  let out = "";
+  let last = 0;
+  for (const tag of scan.tags) {
+    if (tag.name === "script" || tag.name === "style" || tag.name === "html") continue;
+    out += `${source.slice(last, tag.nameEnd)} data-vfsrc="${file}:${tag.line}:${tag.col}"`;
+    last = tag.nameEnd;
+  }
+  return out + source.slice(last);
+}
+
+export interface Decl {
+  prop: string;
+  value: string;
+  important: boolean;
+  line: number;
+  col: number;
+}
+
+export interface Rule {
+  /** One selector of the rule's list. */
+  selector: string;
+  /** The whole selector list as written. */
+  selectorText: string;
+  /** `@media ...` and the like this rule sits inside. */
+  atrule: string | null;
+  file: string;
+  line: number;
+  col: number;
+  decls: Decl[];
+  /** Position in the stylesheets' order, for the cascade. */
+  order: number;
+}
+
+/** Rules of one stylesheet (the text of a `<style>` block or a CSS file), with positions in the file it came from. */
+export function parseRules(css: string, file: string, start: { line: number; col: number }, order0 = 0): Rule[] {
+  const rules: Rule[] = [];
+  let ast;
+  try {
+    ast = parse(css, { positions: true, line: start.line, column: start.col, parseValue: false });
+  } catch {
+    return rules;
+  }
+  let order = order0;
+  walk(ast, {
+    visit: "Rule",
+    enter(node: any) {
+      if (!node.loc) return;
+      const at = (this as any).atrule as { name: string; prelude: unknown } | null;
+      if (at && /keyframes$/i.test(at.name)) return;
+      const atrule = at ? `@${at.name}${at.prelude ? ` ${generate(at.prelude as never)}` : ""}` : null;
+      const decls: Decl[] = [];
+      for (let item = node.block.children.head; item; item = item.next) {
+        const d = item.data;
+        if (d.type === "Declaration" && d.loc) {
+          decls.push({ prop: String(d.property).toLowerCase(), value: generate(d.value).trim(), important: Boolean(d.important), line: d.loc.start.line, col: d.loc.start.column });
+        }
+      }
+      const selectorText = generate(node.prelude);
+      const selectors: string[] = [];
+      if (node.prelude.type === "SelectorList") for (let s = node.prelude.children.head; s; s = s.next) selectors.push(generate(s.data));
+      else selectors.push(selectorText);
+      order += 1;
+      for (const selector of selectors) rules.push({ selector, selectorText, atrule, file, line: node.loc.start.line, col: node.loc.start.column, decls, order });
+    },
+  });
+  return rules;
+}
+
+/** A selector's specificity as one comparable number (ids, then classes/attributes/pseudo-classes, then types). */
+export function specificity(selector: string): number {
+  const s = selector.replace(/"[^"]*"|'[^']*'/g, "").replace(/\[[^\]]*\]/g, ".a");
+  const ids = (s.match(/#[\w-]+/g) ?? []).length;
+  const classes = (s.match(/\.[\w-]+|:(?!:)[\w-]+/g) ?? []).length;
+  const bare = s.replace(/#[\w-]+|\.[\w-]+|::?[\w-]+(\([^)]*\))?/g, " ");
+  const types = (bare.match(/(^|[\s>+~(,])[a-zA-Z][\w-]*/g) ?? []).length;
+  return ids * 10000 + classes * 100 + types;
+}
+
+/** Declarations of a `style="..."` attribute as written. */
+export function inlineDecls(style: string, at: { line: number; col: number }): Decl[] {
+  const out: Decl[] = [];
+  for (const part of style.split(";")) {
+    const colon = part.indexOf(":");
+    if (colon <= 0) continue;
+    out.push({ prop: part.slice(0, colon).trim().toLowerCase(), value: part.slice(colon + 1).replace(/!important\s*$/i, "").trim(), important: /!important\s*$/i.test(part), line: at.line, col: at.col });
+  }
+  return out;
+}
+
+export interface Frame {
+  fn: string;
+  url: string;
+  line: number;
+  col: number;
+}
+
+/** The frames of a V8 stack string. */
+export function parseStack(stack: string): Frame[] {
+  const frames: Frame[] = [];
+  for (const raw of stack.split("\n")) {
+    const m = /^\s*at (?:(.*?) \()?(.*?):(\d+):(\d+)\)?\s*$/.exec(raw);
+    if (m) frames.push({ fn: m[1] ?? "", url: m[2]!, line: Number(m[3]), col: Number(m[4]) });
+  }
+  return frames;
+}
+
+export interface Mapped {
+  /** Where the call was written: the innermost frame in a scene file. */
+  site: Pos | null;
+  /** The vfrey cue (`vfrey.onLine`, `vfrey.at`, ...) that was running, and where the scene called it. */
+  cue: { name: string; site: Pos | null } | null;
+}
+
+const CUE = /\.(at|onWord|onLine|captions|block|transition)$/;
+
+/** Reads a stack into the creation site and the vfrey cue that ran it. `fileOf` turns a URL into a scene file name, or null. */
+export function mapStack(stack: string, fileOf: (url: string) => string | null): Mapped {
+  const frames = parseStack(stack).filter((f) => fileOf(f.url));
+  const scene = (f: Frame): Pos | null => {
+    const file = fileOf(f.url)!;
+    return file.startsWith("vfrey/") ? null : { file, line: f.line, col: f.col };
+  };
+  let site: Pos | null = null;
+  let cue: Mapped["cue"] = null;
+  frames.forEach((f, i) => {
+    const pos = scene(f);
+    if (pos && !site) site = pos;
+    if (!pos && CUE.test(f.fn)) cue = { name: `vfrey.${f.fn.split(".").pop()}`, site: frames.slice(i + 1).map(scene).find(Boolean) ?? null };
+  });
+  return { site, cue };
+}

package/src/scene/label.ts

@@ -0,0 +1,131 @@
+import { execFile } from "node:child_process";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { deflateSync, crc32 } from "node:zlib";
+
+export const LABEL_TEXT = "AI-GENERATED";
+
+type Env = Record<string, string | undefined>;
+
+/** A 5 by 7 pixel font for the letters the label uses. The overlay is drawn from these, so it needs no font file and no ffmpeg text filter. */
+const FONT: Record<string, string[]> = {
+  A: [".###.", "#...#", "#...#", "#####", "#...#", "#...#", "#...#"],
+  I: ["#####", "..#..", "..#..", "..#..", "..#..", "..#..", "#####"],
+  "-": [".....", ".....", ".....", "#####", ".....", ".....", "....."],
+  G: [".###.", "#...#", "#....", "#.###", "#...#", "#...#", ".###."],
+  E: ["#####", "#....", "#....", "####.", "#....", "#....", "#####"],
+  N: ["#...#", "##..#", "#.#.#", "#..##", "#...#", "#...#", "#...#"],
+  R: ["####.", "#...#", "#...#", "####.", "#.#..", "#..#.", "#...#"],
+  T: ["#####", "..#..", "..#..", "..#..", "..#..", "..#..", "..#.."],
+  D: ["####.", "#...#", "#...#", "#...#", "#...#", "#...#", "####."],
+};
+
+const SCALE = 4;
+const PAD_X = 16;
+const PAD_Y = 12;
+const BORDER = 3;
+const SKY: [number, number, number] = [0x90, 0xca, 0xf9];
+const ICE: [number, number, number] = [0xe3, 0xf2, 0xfd];
+
+/** Where the label sits: the bottom right corner, the same place the built-in templates put it. */
+export const LABEL_MARGIN = { right: 72, bottom: 56 } as const;
+
+export function labelSize(): { width: number; height: number } {
+  const textWidth = LABEL_TEXT.length * 6 * SCALE - SCALE;
+  return { width: textWidth + PAD_X * 2 + BORDER * 2, height: 7 * SCALE + PAD_Y * 2 + BORDER * 2 };
+}
+
+/** Top left corner of the label in a 1080 by 1920 frame. */
+export function labelPosition(): { x: number; y: number } {
+  const { width, height } = labelSize();
+  return { x: 1080 - LABEL_MARGIN.right - width, y: 1920 - LABEL_MARGIN.bottom - height };
+}
+
+/** The label as a PNG: black plate, light blue border, pale blue letters. */
+export function labelPng(): Buffer {
+  const { width, height } = labelSize();
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  const put = (x: number, y: number, rgb: [number, number, number]) => {
+    const at = y * (width * 4 + 1) + 1 + x * 4;
+    raw[at] = rgb[0];
+    raw[at + 1] = rgb[1];
+    raw[at + 2] = rgb[2];
+    raw[at + 3] = 255;
+  };
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const edge = x < BORDER || y < BORDER || x >= width - BORDER || y >= height - BORDER;
+      put(x, y, edge ? SKY : [0, 0, 0]);
+    }
+  }
+  [...LABEL_TEXT].forEach((char, index) => {
+    const glyph = FONT[char];
+    if (!glyph) return;
+    const left = BORDER + PAD_X + index * 6 * SCALE;
+    glyph.forEach((row, gy) => {
+      [...row].forEach((cell, gx) => {
+        if (cell !== "#") return;
+        for (let dy = 0; dy < SCALE; dy += 1) for (let dx = 0; dx < SCALE; dx += 1) put(left + gx * SCALE + dx, BORDER + PAD_Y + gy * SCALE + dy, ICE);
+      });
+    });
+  });
+  const chunk = (type: string, data: Buffer) => {
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const out = Buffer.alloc(body.length + 8);
+    out.writeUInt32BE(data.length, 0);
+    body.copy(out, 4);
+    out.writeUInt32BE(crc32(body) >>> 0, body.length + 4);
+    return out;
+  };
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", header), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}
+
+const run = promisify(execFile);
+
+/**
+ * The last pass over every scene render: the AI label is overlaid on the finished video with ffmpeg, so nothing the
+ * scene draws can hide it. The audio is copied untouched.
+ */
+export async function burnLabel(video: string, workDir: string, env: Env): Promise<void> {
+  await mkdir(workDir, { recursive: true });
+  const png = path.join(workDir, "ai-label.png");
+  const out = path.join(workDir, `labeled${path.extname(video) || ".mp4"}`);
+  await writeFile(png, labelPng());
+  const { x, y } = labelPosition();
+  try {
+    await run(
+      "ffmpeg",
+      ["-y", "-v", "error", "-i", video, "-i", png, "-filter_complex", `[0:v][1:v]overlay=${x}:${y}:format=auto,format=yuv420p[v]`, "-map", "[v]", "-map", "0:a?", "-c:v", "libx264", "-preset", "veryfast", "-crf", "17", "-c:a", "copy", "-movflags", "+faststart", out],
+      { env: env as NodeJS.ProcessEnv, timeout: 10 * 60_000, maxBuffer: 8 * 1024 * 1024 },
+    );
+    await rename(out, video);
+  } finally {
+    await rm(out, { force: true });
+    await rm(png, { force: true });
+  }
+}
+
+/** The same overlay on a single frame, for `render --frame`. */
+export async function burnLabelStill(image: string, workDir: string, env: Env): Promise<void> {
+  await mkdir(workDir, { recursive: true });
+  const png = path.join(workDir, "ai-label.png");
+  const out = path.join(workDir, `labeled${path.extname(image) || ".png"}`);
+  await writeFile(png, labelPng());
+  const { x, y } = labelPosition();
+  try {
+    await run("ffmpeg", ["-y", "-v", "error", "-i", image, "-i", png, "-filter_complex", `[0:v][1:v]overlay=${x}:${y}:format=auto`, "-frames:v", "1", out], {
+      env: env as NodeJS.ProcessEnv,
+      timeout: 60_000,
+    });
+    await rename(out, image);
+  } finally {
+    await rm(out, { force: true });
+    await rm(png, { force: true });
+  }
+}

package/src/scene/net-guard.ts

@@ -0,0 +1,74 @@
+import { chmod, mkdir, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import type { AddressInfo, Socket } from "node:net";
+import path from "node:path";
+
+/**
+ * Keeps a scene off the network while it renders. The headless Chrome that renders a scene is started through a
+ * small wrapper that points it at a proxy on this machine; the proxy answers every request with a refusal and
+ * remembers where the scene tried to go. Pages that vfrey serves are on localhost, which Chrome does not send
+ * through a proxy, so the scene itself loads as usual. A request that leaves the machine fails at once, so a scene
+ * that waits for one does not hang the render.
+ */
+export interface NetGuard {
+  /** The Chrome executable to hand the renderer in place of the real one. */
+  chrome: string;
+  /** Hosts the scene tried to reach, in the order first seen. */
+  blocked(): string[];
+  close(): Promise<void>;
+}
+
+export async function startNetGuard(realChrome: string, dir: string): Promise<NetGuard> {
+  const seen = new Map<string, number>();
+  const note = (host: string) => seen.set(host, (seen.get(host) ?? 0) + 1);
+  const sockets = new Set<Socket>();
+  const server = http.createServer((req, res) => {
+    try {
+      note(new URL(req.url ?? "", "http://unknown").host || "unknown");
+    } catch {
+      note("unknown");
+    }
+    res.writeHead(403, { "content-type": "text/plain", connection: "close" });
+    res.end("vfrey blocks the network while a scene renders.\n");
+  });
+  server.on("connect", (req, socket) => {
+    note((req.url ?? "unknown").replace(/:443$/, ""));
+    socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+  });
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    socket.on("error", () => undefined);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const port = (server.address() as AddressInfo).port;
+  await mkdir(dir, { recursive: true });
+  const wrapper = path.join(dir, "chrome-guard.sh");
+  const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+  await writeFile(
+    wrapper,
+    `#!/bin/sh
+# Drop any proxy flag the renderer passes (Remotion asks for no proxy), then force ours.
+for a in "$@"; do
+  shift
+  case "$a" in
+    --no-proxy-server|--proxy-server=*|--proxy-bypass-list=*) ;;
+    *) set -- "$@" "$a" ;;
+  esac
+done
+exec ${quote(realChrome)} "$@" --proxy-server=http://127.0.0.1:${port}
+`,  );
+  await chmod(wrapper, 0o755);
+  return {
+    chrome: wrapper,
+    blocked: () => [...seen.keys()],
+    async close() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}