reelkit-cli 0.6.0 → 0.10.0

package/src/render/render.ts

@@ -1,74 +1,79 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { bundle } from "@remotion/bundler";
-import { ensureBrowser, renderMedia, renderStill, selectComposition } from "@remotion/renderer";
-import type { VideoProps } from "../remotion/types";
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, rm, writeFile, readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, basename } from "node:path";
+import { promisify } from "node:util";
+import { build } from "esbuild";
+import type { VideoProps } from "../hyperframes/types";
+import { fontFamilies } from "../hyperframes/fonts";
 import { packageDir } from "./deps";
-import { KIT_INDEX, ROOT_FILE } from "./validate";
+import { KIT_INDEX, PKG_ROOT } from "./validate";
 
-const ENTRY_SOURCE = `import { registerRoot } from "remotion";
-import { makeRoot } from "reelkit/root";
-import { Video } from "../../src/Video";
-
-registerRoot(makeRoot(Video));
-`;
-
-// The project folder has no node_modules. Each dependency is pinned to the one copy installed with this package, so the
-// kit, Root and the user's composition all share a single react and remotion (a second react breaks hooks).
+const run = promisify(execFile);
+const HOST = join(PKG_ROOT, "src/hyperframes/host.tsx");
+const FRAME = join(PKG_ROOT, "src/hyperframes/frame.tsx");
 export function dependencyAliases(): Record<string, string> {
-  return Object.fromEntries(["react", "react-dom", "remotion"].map((n) => [n, packageDir(n)]));
+  return Object.fromEntries(["react", "react-dom", "three", "@react-three/fiber"].map((name) => [name, packageDir(name)]));
 }
-
-// Writes the bundler's entry file into the project. The composition itself stays where the user's Claude wrote it.
 export async function writeEntry(projectDir: string): Promise<string> {
   const dir = join(projectDir, ".reelkit", "build");
-  await rm(dir, { recursive: true, force: true });
-  await mkdir(dir, { recursive: true });
+  await rm(dir, { recursive: true, force: true }); await mkdir(dir, { recursive: true });
   const entry = join(dir, "index.ts");
-  await writeFile(entry, ENTRY_SOURCE);
+  await writeFile(entry, 'import { mountVideo } from "reelkit/host";\nimport { Video } from "../../src/Video";\nmountVideo(Video);\n');
   return entry;
 }
-
-// Webpack's on-disk cache would only grow, by tens of megabytes per render. It is switched off, and each bundle
-// is deleted by disposeBundle once it has been used.
+// A self-contained HyperFrames page using the package's copies of React and Three.
 export async function bundleProject(entry: string): Promise<string> {
-  return bundle({
-    entryPoint: entry,
-    enableCaching: false,
-    webpackOverride: (config) => ({
-      ...config,
-      resolve: {
-        ...config.resolve,
-        alias: { ...(config.resolve?.alias as Record<string, string> | undefined), ...dependencyAliases(), "reelkit/kit": KIT_INDEX, "reelkit/root": ROOT_FILE },
-      },
-    }),
-  });
+  const dir = await mkdtemp(join(tmpdir(), "reelkit-hyperframes-"));
+  try {
+    await build({ entryPoints: [entry], bundle: true, outfile: join(dir, "composition.js"), platform: "browser", format: "iife", jsx: "automatic", logLevel: "silent", loader: { ".woff2": "file", ".woff": "file", ".ttf": "file" }, define: { "process.env.NODE_ENV": '"production"' }, alias: { ...dependencyAliases(), "reelkit/kit": KIT_INDEX, "reelkit/frame": FRAME, "reelkit/host": HOST } });
+    await mkdir(join(dir, "fonts"));
+    for (const slug of Object.values(fontFamilies)) {
+      const source = packageDir(`@fontsource/${slug}`);
+      await cp(join(source, "files"), join(dir, "fonts", "files"), { recursive: true });
+      const sheets = (await readdir(source)).filter((name) => /^\d+(?:-italic)?\.css$/.test(name));
+      await writeFile(join(dir, "fonts", `${slug}.css`), (await Promise.all(sheets.map((name) => readFile(join(source, name), "utf8")))).join("\n"));
+    }
+    await writeFile(join(dir, "index.html"), '<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;overflow:hidden}#stage{position:relative;overflow:hidden}</style></head><body><div id="stage"></div><script src="props.js"></script><script src="composition.js"></script></body></html>');
+    return dir;
+  } catch (error) { await rm(dir, { recursive: true, force: true }); throw error; }
 }
-
-export async function disposeBundle(serveUrl: string): Promise<void> {
-  // Only ever remove a folder that is one of Remotion's own temporary bundles.
-  if (/remotion-webpack-bundle-/.test(serveUrl)) await rm(serveUrl, { recursive: true, force: true });
+export async function disposeBundle(dir: string): Promise<void> {
+  if (dirname(dir) === tmpdir() && basename(dir).startsWith("reelkit-hyperframes-")) await rm(dir, { recursive: true, force: true });
 }
-
-// Makes sure Remotion's headless browser is installed. onDownload is called once, only when a download is about to begin.
-// Remotion's own progress bar is replaced because it writes to stdout, which --json keeps for the result alone.
 export type EnsureBrowser = (onDownload: () => void) => Promise<void>;
+export const GL_BACKEND = "software" as const;
+export type RenderOptions = { uses3D?: boolean; silent?: boolean; crf?: number };
+export function browserPath(): string | undefined {
+  if (process.env.REELKIT_CHROME_PATH) return process.env.REELKIT_CHROME_PATH;
+  const paths = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium"] : process.platform === "linux" ? ["/usr/bin/chromium", "/usr/bin/chromium-browser", "/usr/bin/google-chrome"] : [];
+  return paths.find(existsSync);
+}
 export const ensureRenderBrowser: EnsureBrowser = async (onDownload) => {
-  await ensureBrowser({ onBrowserDownload: () => { onDownload(); return { version: null, onProgress: () => {} }; } });
+  if (browserPath()) return;
+  const { resolveHeadlessShellPath } = await import("@hyperframes/engine");
+  const cached = resolveHeadlessShellPath({}) ?? resolveHeadlessShellPath({ chromePath: undefined });
+  if (cached) { process.env.REELKIT_CHROME_PATH = cached; return; }
+  const { install, Browser, resolveBuildId, detectBrowserPlatform, getInstalledBrowsers } = await import("@puppeteer/browsers");
+  const installed = (await getInstalledBrowsers({ cacheDir: join(PKG_ROOT, ".browser") })).find((b) => b.browser === Browser.CHROMEHEADLESSSHELL && existsSync(b.executablePath));
+  if (installed) { process.env.REELKIT_CHROME_PATH = installed.executablePath; return; }
+  const platform = detectBrowserPlatform(); if (!platform) throw new Error("No supported Chrome platform. Set REELKIT_CHROME_PATH.");
+  onDownload();
+  const browser = await install({ browser: Browser.CHROMEHEADLESSSHELL, buildId: await resolveBuildId(Browser.CHROMEHEADLESSSHELL, platform, "stable"), cacheDir: join(PKG_ROOT, ".browser"), platform });
+  process.env.REELKIT_CHROME_PATH = browser.executablePath;
 };
-
-const asInput = (props: VideoProps) => props as unknown as Record<string, unknown>;
-
-export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string) {
-  await mkdir(outDir, { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
-  for (const frame of frames) {
-    await renderStill({ composition, serveUrl, frame, output: join(outDir, `still-${frame}.png`), inputProps: asInput(props) });
-  }
+async function render(dir: string, props: VideoProps, mode: "stills" | "video", output: string, frames: number[], options?: RenderOptions) {
+  await ensureRenderBrowser(() => {});
+  await writeFile(join(dir, "props.js"), `window.__reelkitProps=${JSON.stringify(props).replace(/</g, "\\u003c")};`);
+  // Isolate engine diagnostics from the CLI's JSON stdout.
+  const request = join(dir, "render-request.json");
+  await writeFile(request, JSON.stringify({ dir, props, mode, output, frames, options, chromePath: browserPath() }));
+  await run(process.execPath, ["--import", join(packageDir("tsx"), "dist/loader.mjs"), join(PKG_ROOT, "src/render/worker.ts"), request], { maxBuffer: 16 * 1024 * 1024 });
 }
-
-export async function renderVideo(serveUrl: string, props: VideoProps, outPath: string) {
-  await mkdir(dirname(outPath), { recursive: true });
-  const composition = await selectComposition({ serveUrl, id: "Video", inputProps: asInput(props) });
-  await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: outPath, inputProps: asInput(props) });
+export async function renderStills(dir: string, props: VideoProps, frames: number[], outDir: string, options?: RenderOptions) {
+  await mkdir(outDir, { recursive: true }); await render(dir, props, "stills", outDir, frames, options);
+}
+export async function renderVideo(dir: string, props: VideoProps, outPath: string, options?: RenderOptions) {
+  await mkdir(dirname(outPath), { recursive: true }); await render(dir, props, "video", outPath, [], options);
 }

package/src/render/serve.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { createReadStream, statSync } from "node:fs";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { extname, resolve, sep } from "node:path";
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8", ".js": "application/javascript", ".css": "text/css",
+  ".json": "application/json", ".woff2": "font/woff2", ".woff": "font/woff", ".ttf": "font/ttf",
+  ".png": "image/png", ".jpg": "image/jpeg", ".svg": "image/svg+xml",
+};
+
+// Serve the generated composition only to localhost, under an unguessable per-render prefix.
+// The generic HyperFrames file server listens on all interfaces; project copy and media URLs stay private here.
+export async function serveComposition(dir: string): Promise<{ url: string; close(): Promise<void> }> {
+  const root = resolve(dir), prefix = `/${randomBytes(16).toString("hex")}/`;
+  const server = createServer((req, res) => {
+    let path: string;
+    try { path = decodeURIComponent((req.url ?? "").split("?")[0]!); } catch { res.writeHead(400).end(); return; }
+    if (!path.startsWith(prefix)) { res.writeHead(404).end(); return; }
+    const file = resolve(root, path.slice(prefix.length) || "index.html");
+    try {
+      if (!file.startsWith(root + sep) || !statSync(file).isFile()) { res.writeHead(404).end(); return; }
+      res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-store" });
+      const stream = createReadStream(file); stream.on("error", () => res.destroy()); stream.pipe(res);
+    } catch { res.writeHead(404).end(); }
+  });
+  await new Promise<void>((ready, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", ready); });
+  const port = (server.address() as AddressInfo).port;
+  return { url: `http://127.0.0.1:${port}${prefix}`, close: () => new Promise<void>((ready) => { server.closeAllConnections(); server.close(() => ready()); }) };
+}

package/src/render/sound-notes.ts

@@ -0,0 +1,106 @@
+import ts from "typescript";
+import { sourceFile } from "./static-check";
+
+// Advice about the sound of a film with no voice, read from the composition's source. It is a count of what the code places, never a
+// listening test: a sound that is computed, looped over or hidden behind a variable cannot be counted, so then nothing is said.
+export type SoundCount = {
+  // Sfx elements and literal SoundCues entries.
+  placed: number;
+  // True when some cue is computed (a map, a helper, a variable that is not a plain list), so that the count is only a lower bound.
+  uncertain: boolean;
+  music: boolean;
+  // True when a cue or an effect is placed before this frame; `unknownStart` when one has a start that is not a plain number.
+  early: boolean;
+  unknownStart: boolean;
+};
+
+const numberOf = (e: ts.Expression | undefined): number | undefined => {
+  if (!e) return undefined;
+  if (ts.isNumericLiteral(e)) return Number(e.text);
+  if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(e.operand)) return -Number(e.operand.text);
+  if (ts.isParenthesizedExpression(e)) return numberOf(e.expression);
+  return undefined;
+};
+
+const insideLoop = (node: ts.Node): boolean => {
+  for (let p = node.parent; p; p = p.parent) {
+    if (ts.isCallExpression(p) && ts.isPropertyAccessExpression(p.expression) && ["map", "forEach", "flatMap"].includes(p.expression.name.text)) return true;
+  }
+  return false;
+};
+
+// The value of a prop, looking through a name that the file declares as a constant.
+function propValue(attr: ts.JsxAttribute, sf: ts.SourceFile): ts.Expression | undefined {
+  const init = attr.initializer;
+  if (!init || !ts.isJsxExpression(init) || !init.expression) return undefined;
+  const e = init.expression;
+  if (!ts.isIdentifier(e)) return e;
+  let found: ts.Expression | undefined;
+  const visit = (n: ts.Node) => {
+    if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === e.text && n.initializer && !found) found = n.initializer;
+    ts.forEachChild(n, visit);
+  };
+  visit(sf);
+  return found ?? e;
+}
+
+export function countSounds(source: string, file: string, earlyFrames: number): SoundCount {
+  const sf = sourceFile(source, file);
+  const out: SoundCount = { placed: 0, uncertain: false, music: false, early: false, unknownStart: false };
+  const attr = (el: ts.JsxOpeningLikeElement, name: string) => el.attributes.properties.find((a): a is ts.JsxAttribute => ts.isJsxAttribute(a) && a.name.getText(sf) === name);
+  const atOf = (e: ts.Expression | undefined, absent: number | undefined) => {
+    const n = e === undefined ? absent : numberOf(e);
+    if (n === undefined) out.unknownStart = true;
+    else if (n < earlyFrames) out.early = true;
+  };
+  const visit = (node: ts.Node) => {
+    const el = ts.isJsxSelfClosingElement(node) ? node : ts.isJsxElement(node) ? node.openingElement : undefined;
+    if (el) {
+      const tag = el.tagName.getText(sf);
+      if (tag === "Music") out.music = true;
+      if (tag === "Sfx") {
+        out.placed += 1;
+        if (insideLoop(el)) out.uncertain = true;
+        const at = attr(el, "at");
+        if (!at) out.early = true;
+        else {
+          const v = at.initializer && ts.isJsxExpression(at.initializer) ? at.initializer.expression : undefined;
+          atOf(v, undefined);
+        }
+      }
+      if (tag === "SoundCues") {
+        const cues = attr(el, "cues");
+        const value = cues && propValue(cues, sf);
+        if (!value || !ts.isArrayLiteralExpression(value) || value.elements.some((c) => !ts.isObjectLiteralExpression(c)) || insideLoop(el)) out.uncertain = true;
+        else {
+          out.placed += value.elements.length;
+          for (const c of value.elements as ts.NodeArray<ts.ObjectLiteralExpression>) {
+            const at = c.properties.find((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && p.name.getText(sf) === "at");
+            atOf(at?.initializer, undefined);
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
+}
+
+// The notes for a film with no voice. `seconds` is the film's length, `musicSet` whether a track was pulled with --music.
+export function soundNotes(sources: { name: string; source: string }[], opts: { seconds: number; fps: number; musicSet: boolean }): string[] {
+  const earlyFrames = Math.round(opts.fps / 2);
+  const counts = sources.map((s) => countSounds(s.source, s.name, earlyFrames));
+  const placed = counts.reduce((n, c) => n + c.placed, 0);
+  const uncertain = counts.some((c) => c.uncertain);
+  const notes: string[] = [];
+  if (!opts.musicSet) notes.push("No music track is set. A film with no voice is carried by its music: choose one and pull it with `reelkit assets pull <id> --music` (see reference/launch-film.md).");
+  if (!uncertain && placed < opts.seconds / 2) {
+    notes.push(`The code places ${placed} sound cue${placed === 1 ? "" : "s"} (Sfx elements and SoundCues entries) in ${opts.seconds.toFixed(1)}s of film, fewer than one per two seconds. This is a count of what the composition places, not a listening test; a film with no voice usually has about one placed effect per second on top of the music (see reference/launch-film.md).`);
+  }
+  const startsAtOnce = counts.some((c) => c.music || c.early);
+  if (!startsAtOnce && !uncertain && !counts.some((c) => c.unknownStart)) {
+    notes.push("Nothing is placed in the first half second: the code has no Music, and no Sfx or SoundCues cue that starts there. This is a count of what the composition places, not a listening test; start a sound on the first frame (see reference/launch-film.md).");
+  }
+  return notes;
+}

package/src/render/static-check.ts

@@ -7,8 +7,19 @@ export const MAIN_FILE = "Video.tsx";
 export const FILE_NAME = /^[A-Z][A-Za-z0-9]*\.tsx$/;
 export const componentName = (file: string) => file.replace(/\.tsx$/, "");
 
+// Upgrade previously published library components without touching on-screen copy or comments.
+export function migrateFrameImports(source: string): string {
+  const parsed = sourceFile(source);
+  const edits: { start: number; end: number }[] = [];
+  for (const node of parsed.statements) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "remotion") edits.push({ start: node.moduleSpecifier.getStart(parsed), end: node.moduleSpecifier.getEnd() });
+  }
+  for (const edit of edits.reverse()) source = source.slice(0, edit.start) + '"reelkit/frame"' + source.slice(edit.end);
+  return source;
+}
+
 export const KIT = "reelkit/kit";
-const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
+const BASE_IMPORTS = new Set(["react", "reelkit/frame", KIT]);
 
 // This check keeps honest compositions deterministic and self-contained. It is NOT a security boundary:
 // code in src/ runs on the user's machine when it is bundled and rendered, and anyone determined can get around a list of names.
@@ -77,7 +88,7 @@ function inspectSource(source: string, file?: string): Finding {
     return Boolean(x && ts.isIdentifier(x) && x.text === name && !declared(x));
   };
   const flagMember = (object: ts.Expression | undefined, member: string | undefined) => {
-    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from remotion)");
+    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from reelkit/frame)");
     if (isGlobal(object, "Date") && member === "now") forbidden.add("the clock (Date)");
   };
   // The key a destructuring element reads: `random` in `{ random }` and in `{ random: r }`, "random" in `{ ["random"]: r }`.
@@ -140,8 +151,8 @@ export function staticCheck(source: string, file: string, siblings: string[]): s
     if (BASE_IMPORTS.has(s) || allowedSiblings.has(s)) continue;
     errors.push(
       isMain
-        ? `${file}: import not allowed: "${s}". Use react, remotion, ${KIT}, or a component file that exists ("./Name").`
-        : `${file}: import not allowed: "${s}". A component may only import react, remotion and ${KIT}.`,
+        ? `${file}: import not allowed: "${s}". Use react, reelkit/frame, ${KIT}, or a component file that exists ("./Name").`
+        : `${file}: import not allowed: "${s}". A component may only import react, reelkit/frame and ${KIT}.`,
     );
   }
   for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);

package/src/render/validate.ts

@@ -4,15 +4,15 @@ import ts from "typescript";
 import { packageDir } from "./deps";
 
 export const PKG_ROOT = fileURLToPath(new URL("../..", import.meta.url));
-export const KIT_INDEX = join(PKG_ROOT, "src", "remotion", "kit", "index.ts");
-export const ROOT_FILE = join(PKG_ROOT, "src", "remotion", "Root.tsx");
+export const KIT_INDEX = join(PKG_ROOT, "src", "hyperframes", "kit", "index.ts");
+export const ROOT_FILE = join(PKG_ROOT, "src", "hyperframes", "Root.tsx");
 
 // The static check lives in its own module, which a server can bundle; everything it exports is available from here as before.
 export { FILE_NAME, MAIN_FILE, componentName, importSpecifiers, staticCheck } from "./static-check";
 import { KIT, sourceFile, unwrap } from "./static-check";
 
 const typesReact = packageDir("@types/react");
-export const remotionDir = packageDir("remotion");
+export const frameFile = join(PKG_ROOT, "src", "hyperframes", "frame.tsx");
 
 export function typecheck(files: string[]): string[] {
   const program = ts.createProgram(files, {
@@ -30,7 +30,7 @@ export function typecheck(files: string[]): string[] {
       [KIT]: [KIT_INDEX],
       react: [typesReact],
       "react/*": [join(typesReact, "*")],
-      remotion: [remotionDir],
+      "reelkit/frame": [frameFile],
     },
   });
   const wanted = new Set(files);

package/src/render/word-check.ts

@@ -0,0 +1,181 @@
+// What a composition's source says statically about the spoken words it is timed to: which helper calls name a word, in which scene, and whether
+// the word is in that scene's narration. Pure text in, findings out (the TypeScript syntax tree, never regular expressions on code), so `check`
+// and `preview` can both use it.
+import ts from "typescript";
+import { normalizeWord, wordFrame, type WordScene } from "../hyperframes/kit/word-anchor";
+import { sourceFile, unwrap } from "./static-check";
+
+export const WORD_HELPERS = ["wordFrame", "wordFrames", "onWord", "onWordBeat"] as const;
+const isHelper = (n: string): n is (typeof WORD_HELPERS)[number] => (WORD_HELPERS as readonly string[]).includes(n);
+
+export type WordCall = {
+  fn: (typeof WORD_HELPERS)[number];
+  // The scene, when the call's first argument is a scene found by a literal id (sceneById(manifest, "id"), or manifest.scenes[2], or S.id and S["id"]).
+  sceneId?: string;
+  // One entry per literal word the call names; a word that is not a literal is left out.
+  words: { word: string; nth?: number }[];
+  line: number;
+};
+
+type PlanScene = { id: string; narration: string };
+
+const literalText = (e: ts.Expression | undefined): string | undefined => {
+  const x = e && unwrap(e);
+  return x && ts.isStringLiteralLike(x) ? x.text : undefined;
+};
+const literalNumber = (e: ts.Expression | undefined): number | undefined => {
+  const x = e && unwrap(e);
+  return x && ts.isNumericLiteral(x) ? Number(x.text) : undefined;
+};
+
+// Where a source says `<something>.scenes`: the manifest's list of scenes, however the manifest is called.
+const isScenesList = (e: ts.Expression): boolean => { const x = unwrap(e); return ts.isPropertyAccessExpression(x) && x.name.text === "scenes"; };
+
+// Calls of the word helpers in `source`. `ids` are the plan's scene ids in order, so that a scene reached by position or by `S.hook` can be named.
+export function wordCalls(source: string, ids: string[], file = "Video.tsx"): WordCall[] {
+  const sf = sourceFile(source, file);
+  // Every `const name = expression` and `const [a, b] = list` in the file, flat: the names a composition gives its scenes are not scoped carefully.
+  const consts = new Map<string, ts.Expression>();
+  const positions = new Map<string, number>();
+  const visitDecl = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && node.initializer) {
+      if (ts.isIdentifier(node.name)) consts.set(node.name.text, node.initializer);
+      else if (ts.isArrayBindingPattern(node.name) && isScenesList(node.initializer)) {
+        node.name.elements.forEach((el, i) => { if (ts.isBindingElement(el) && ts.isIdentifier(el.name)) positions.set(el.name.text, i); });
+      }
+    }
+    ts.forEachChild(node, visitDecl);
+  };
+  visitDecl(sf);
+
+  const resolve = (e: ts.Expression, depth = 0): string | undefined => {
+    if (depth > 6) return undefined;
+    const x = unwrap(e);
+    if (ts.isCallExpression(x) && ts.isIdentifier(x.expression) && x.expression.text === "sceneById") {
+      const id = literalText(x.arguments[1]);
+      return id !== undefined && ids.includes(id) ? id : undefined;
+    }
+    if (ts.isIdentifier(x)) {
+      const pos = positions.get(x.text);
+      if (pos !== undefined) return ids[pos];
+      const init = consts.get(x.text);
+      return init ? resolve(init, depth + 1) : undefined;
+    }
+    if (ts.isElementAccessExpression(x) && isScenesList(x.expression)) {
+      const i = literalNumber(x.argumentExpression);
+      return i !== undefined ? ids[i] : undefined;
+    }
+    // A record of scenes by id: `const S = Object.fromEntries(manifest.scenes.map(...))`, then S.hook or S["hook"].
+    if (ts.isPropertyAccessExpression(x) || ts.isElementAccessExpression(x)) {
+      const key = ts.isPropertyAccessExpression(x) ? x.name.text : literalText(x.argumentExpression);
+      const base = unwrap(x.expression);
+      if (key !== undefined && ids.includes(key) && ts.isIdentifier(base)) {
+        const init = consts.get(base.text);
+        if (init && init.getText(sf).includes("scenes")) return key;
+      }
+    }
+    return undefined;
+  };
+
+  const out: WordCall[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isHelper(node.expression.text)) {
+      const fn = node.expression.text;
+      const [scene, arg] = node.arguments;
+      const options = node.arguments.slice(2).map((a) => unwrap(a)).find((a): a is ts.ObjectLiteralExpression => ts.isObjectLiteralExpression(a));
+      const nthProp = options?.properties.find((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "nth");
+      const nth = literalNumber(nthProp?.initializer);
+      const named: string[] = [];
+      if (arg) {
+        const single = literalText(arg);
+        if (fn === "wordFrames") { const list = unwrap(arg); if (ts.isArrayLiteralExpression(list)) for (const el of list.elements) { const t = literalText(el); if (t !== undefined) named.push(t); } }
+        else if (single !== undefined) named.push(single);
+      }
+      out.push({
+        fn, ...(scene ? (() => { const id = resolve(scene); return id !== undefined ? { sceneId: id } : {}; })() : {}),
+        words: named.map((word) => ({ word, ...(nth !== undefined ? { nth } : {}) })),
+        line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
+}
+
+// Whether this narration says `word` (a word or a phrase of consecutive words, ignoring case and punctuation) at least `nth` times.
+export function narrationHas(narration: string, word: string, nth = 1): boolean {
+  const parts = word.split(/\s+/).map(normalizeWord).filter(Boolean);
+  if (!parts.length) return false;
+  const list = narration.split(/\s+/).map(normalizeWord).filter(Boolean);
+  let seen = 0;
+  for (let i = 0; i + parts.length <= list.length; i++) if (parts.every((p, k) => list[i + k] === p) && ++seen >= nth) return true;
+  return false;
+}
+
+// The errors: a literal word that the narration of a literally named scene does not contain.
+export function wordErrors(file: string, calls: WordCall[], scenes: PlanScene[]): string[] {
+  const errors: string[] = [];
+  for (const c of calls) {
+    const scene = c.sceneId ? scenes.find((s) => s.id === c.sceneId) : undefined;
+    if (!scene) continue;
+    for (const w of c.words) {
+      if (narrationHas(scene.narration, w.word, w.nth ?? 1)) continue;
+      errors.push(`${file} line ${c.line}: ${c.fn}(... "${w.word}"${w.nth && w.nth > 1 ? `, { nth: ${w.nth} }` : ""}) names a word that scene ${scene.id} never says. Its narration is: "${scene.narration}". The render would stop on it; use a word from the narration.`);
+    }
+  }
+  return errors;
+}
+
+// True when the file times anything to a spoken word: it calls a word helper, or reads a scene's `.words` for something other than the captions.
+export function usesWordTiming(source: string, file = "Video.tsx"): boolean {
+  const sf = sourceFile(source, file);
+  let used = false;
+  const visit = (node: ts.Node) => {
+    if (used) return;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isHelper(node.expression.text)) { used = true; return; }
+    if ((ts.isPropertyAccessExpression(node) && node.name.text === "words") || (ts.isElementAccessExpression(node) && literalText(node.argumentExpression) === "words")) {
+      // `words={s.words}` on <Captions> is not timing: it is the captions' own input.
+      let p: ts.Node | undefined = node.parent;
+      while (p && (ts.isParenthesizedExpression(p) || ts.isAsExpression(p) || ts.isNonNullExpression(p))) p = p.parent;
+      const inCaptions = p && ts.isJsxExpression(p) && ts.isJsxAttribute(p.parent) && p.parent.name.getText(sf) === "words"
+        && (() => { let q: ts.Node | undefined = p.parent.parent.parent; return Boolean(q && (ts.isJsxSelfClosingElement(q) || ts.isJsxOpeningElement(q)) && q.tagName.getText(sf) === "Captions"); })();
+      if (!inCaptions) used = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return used;
+}
+
+// How many frames after a word starts the preview looks: the thing the word names should already be there.
+export const WORD_FRAME_AFTER = 4;
+// At most this many word frames go on the contact sheet.
+export const MAX_WORD_FRAMES = 16;
+
+export type WordTarget = { sceneId: string; word: string; nth?: number; wordStart: number; frame: number; label: string };
+
+// The words the preview can look at: every literal word of a helper call whose scene is known, as the frame 4 frames after the word starts (kept
+// inside its scene), in film order, without repeats, at most `cap`. `skipped` counts what could not be shown: a word or a scene that is not a
+// literal (the code does not say which), and what was left out past the cap.
+export function wordTargets(calls: WordCall[], manifest: { scenes: (WordScene & { id: string; durationFrames: number })[] }, cap = MAX_WORD_FRAMES): { targets: WordTarget[]; skipped: number; undecidable: number; capped: number } {
+  const seen = new Set<string>();
+  const found: WordTarget[] = [];
+  let undecidable = 0;
+  for (const c of calls) {
+    const scene = c.sceneId ? manifest.scenes.find((s) => s.id === c.sceneId) : undefined;
+    if (!scene || !c.words.length) { undecidable += Math.max(1, c.words.length); continue; }
+    for (const w of c.words) {
+      const key = `${scene.id}|${normalizeWord(w.word) || w.word}|${w.nth ?? 1}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      let start: number;
+      try { start = wordFrame(scene, w.word, { nth: w.nth, absolute: true }); } catch { undecidable++; continue; }
+      const last = scene.startFrame + scene.durationFrames - 1;
+      found.push({ sceneId: scene.id, word: w.word, ...(w.nth && w.nth > 1 ? { nth: w.nth } : {}), wordStart: start, frame: Math.min(start + WORD_FRAME_AFTER, last), label: `${w.word}${w.nth && w.nth > 1 ? ` #${w.nth}` : ""} \u25B8 ${scene.id}` });
+    }
+  }
+  found.sort((a, b) => a.wordStart - b.wordStart);
+  const targets = found.slice(0, cap);
+  return { targets, skipped: undecidable + (found.length - targets.length), undecidable, capped: found.length - targets.length };
+}

package/src/render/worker.ts

@@ -0,0 +1,71 @@
+// Internal subprocess: HyperFrames owns capture, encoding and audio mixing.
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, extname } from "node:path";
+import { promisify } from "node:util";
+import { createCaptureSession, initializeSession, captureFrame, closeCaptureSession, encodeFramesFromDir, processCompositionAudio, muxVideoWithAudio, applyFaststart, type AudioElement } from "@hyperframes/engine";
+import { serveComposition } from "./serve";
+import type { VideoProps } from "../hyperframes/types";
+import type { AudioRecord } from "../hyperframes/frame";
+import type { RenderOptions } from "./render";
+
+const run = promisify(execFile);
+const input = JSON.parse(await readFile(process.argv[2]!, "utf8")) as { dir: string; props: VideoProps; mode: "stills" | "video"; output: string; frames: number[]; options?: RenderOptions; chromePath?: string };
+const m = input.props.manifest, fps = { num: m.fps, den: 1 };
+const work = await mkdtemp(join(tmpdir(), "reelkit-capture-"));
+const server = await serveComposition(input.dir);
+let session: Awaited<ReturnType<typeof createCaptureSession>> | undefined;
+try {
+  session = await createCaptureSession(server.url.replace(/\/$/, ""), work, { width: m.width, height: m.height, fps, format: "png", compositionDurationSeconds: m.totalFrames / m.fps }, async (page) => {
+    await page.evaluate(async () => { await (window as unknown as { __reelkitReady: Promise<void> }).__reelkitReady; });
+  }, { chromePath: input.chromePath, forceScreenshot: true, useDrawElement: false, staticFrameDedup: false, enableBrowserPool: false, browserGpuMode: input.options?.uses3D ? "software" : "auto" });
+  await initializeSession(session);
+  await session.page.evaluate(async () => { await (window as unknown as { __reelkitReady: Promise<void> }).__reelkitReady; });
+  const frames = input.mode === "stills" ? input.frames : Array.from({ length: m.totalFrames }, (_, i) => i);
+  for (const frame of frames) {
+    if (!Number.isInteger(frame) || frame < 0 || frame >= m.totalFrames) throw new Error(`Frame ${frame} is outside the composition.`);
+    const captured = await captureFrame(session, frame, frame / m.fps);
+    if (input.mode === "stills") await cp(captured.path, join(input.output, `still-${frame}.png`));
+  }
+  if (input.mode === "video") {
+    const silent = join(work, "silent.mp4");
+    const encoded = await encodeFramesFromDir(work, "frame_%06d.png", silent, { fps, width: m.width, height: m.height, codec: "h264", pixelFormat: "yuv420p", quality: input.options?.crf ?? 18, preset: "fast" });
+    if (!encoded.success) throw new Error(encoded.error ?? "HyperFrames encoding failed.");
+    const records = input.options?.silent ? [] : await session.page.evaluate(() => [...(window as unknown as { __reelkitAudio: Map<string, AudioRecord> }).__reelkitAudio.values()]);
+    const audio: AudioElement[] = [];
+    const localSources = new Map<string, string>();
+    for (const record of records) {
+      let src = localSources.get(record.src);
+      if (!src) {
+        const response = await fetch(record.src); if (!response.ok) throw new Error(`Audio source returned ${response.status}.`);
+        src = join(work, `source-${localSources.size}${extname(new URL(record.src).pathname) || ".media"}`);
+        await writeFile(src, new Uint8Array(await response.arrayBuffer())); localSources.set(record.src, src);
+      }
+      const info = JSON.parse((await run("ffprobe", ["-v", "error", "-show_format", "-of", "json", src])).stdout) as { format: { duration: string } };
+      let end = Math.min(record.end, record.start + Number(info.format.duration) - record.mediaStart);
+      if (record.loop) {
+        const looped = join(work, `loop-${audio.length}.wav`);
+        await run("ffmpeg", ["-y", "-v", "error", "-stream_loop", "-1", "-i", src, "-t", String(record.end - record.start + record.mediaStart), "-vn", looped]);
+        src = looped; end = record.end;
+      }
+      if (end <= record.start) continue;
+      const keys = [...new Map(record.volumeKeyframes.map((k) => [k.time, k])).values()].sort((a, b) => a.time - b.time);
+      audio.push({ ...record, src, end, volumeKeyframes: keys.length ? keys : undefined });
+    }
+    if (audio.length) {
+      const mixed = join(work, "audio.m4a");
+      const result = await processCompositionAudio(audio, work, join(work, "audio-work"), mixed, m.totalFrames / m.fps);
+      if (!result.success) throw new Error(result.error ?? "HyperFrames audio mixing failed.");
+      const muxed = await muxVideoWithAudio(silent, mixed, input.output, undefined, { audioCodec: "aac" });
+      if (!muxed.success) throw new Error(muxed.error ?? "HyperFrames audio mux failed.");
+    } else {
+      await mkdir(join(work, "faststart"));
+      const result = await applyFaststart(silent, input.output);
+      if (!result.success) throw new Error(result.error ?? "Faststart failed.");
+    }
+  }
+} finally {
+  if (session) await closeCaptureSession(session);
+  await server.close(); await rm(work, { recursive: true, force: true });
+}

package/src/testing/conformance.ts

@@ -356,6 +356,18 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         expect((await api("me", {})).quota.images.used).toBe(2);
       });
 
+      it("images: a request for format svg returns an svg, and a request with no format still returns a raster image", async () => {
+        const api = await as("user-gen00008");
+        const svg = await api("images", { prompt: "a red circle, transparent background", aspect: "1:1", shareable: false, tags: [], format: "svg" });
+        expect(svg.ext).toBe("svg");
+        expect(svg.contentType).toBe("image/svg+xml");
+        await download(svg.url, join(dest, "mark.svg"));
+        expect(readFileSync(join(dest, "mark.svg"), "utf8")).toMatch(/^\s*<svg/);
+        const raster = await api("images", { prompt: "a quiet lake", aspect: "16:9", shareable: false, tags: [] });
+        expect(raster.ext).not.toBe("svg");
+        expect((await api("me", {})).quota.images.used).toBe(2);
+      });
+
       it("a shared image's title is the first 60 characters of the prompt, cut on a code point, never inside an emoji", async () => {
         const api = await as("user-gen00007");
         const prompt = "\u{1F30B}".repeat(70);