@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/scene/studio-skin.ts

@@ -0,0 +1,59 @@
+/**
+ * vfrey's skin for Framey's studio. The studio is Framey's (Apache-2.0, see vendor/framey/LICENSE and NOTICE), built for
+ * HeyGen's HyperFrames product. vfrey does not ship their logo, their desktop-app upsell, or controls that need
+ * features vfrey does not have, so the front server adds this stylesheet and script to the studio page. They work on the
+ * rendered DOM, so a re-sync of a newer studio build stays clean without patching minified code.
+ *
+ * Hidden: the logo (replaced by a plain wordmark), "Install the desktop app", Export and the Renders panel (a render
+ * goes through `npx vfrey render --scene DIR`, which supplies the timing and voice and burns in the AI label, and
+ * the studio's own render would skip all three), the Catalog panel (it loads Framey's hosted block registry; vfrey's
+ * blocks are `npx vfrey scene add`), and "Describe a change to the agent" (a hand-off to their desktop app).
+ * Kept: Capture (a local PNG of the current frame), the preview, the timeline, the code editor, the inspector.
+ */
+export const SKIN_PATH = "/__vfrey/studio";
+
+export const SKIN_CSS = `
+svg[aria-label="Framey"] { display: none !important; }
+.vfrey-wordmark { font: 600 15px/1 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; letter-spacing: -0.01em; white-space: nowrap; }
+[data-testid="header-open-in-desktop"],
+[data-testid="header-export"],
+[role="tab"][data-tab-panel-id="catalog"],
+[role="tab"][data-tab-panel-id="renders"],
+.vfrey-hidden { display: none !important; }
+`;
+
+export const SKIN_JS = `(() => {
+  const WORD = "vfrey studio";
+  const apply = () => {
+    if (document.title !== WORD) document.title = WORD;
+    for (const logo of document.querySelectorAll('svg[aria-label="Framey"]')) {
+      if (!(logo.previousElementSibling && logo.previousElementSibling.classList.contains("vfrey-wordmark"))) {
+        const word = document.createElement("span");
+        word.className = "vfrey-wordmark";
+        word.textContent = WORD;
+        logo.before(word);
+      }
+    }
+    for (const el of document.querySelectorAll("span")) {
+      if (el.childElementCount <= 1 && el.textContent.trim().endsWith("Describe a change to the agent")) {
+        const row = el.parentElement;
+        if (row) row.classList.add("vfrey-hidden");
+      }
+    }
+  };
+  let queued = false;
+  const later = () => {
+    if (queued) return;
+    queued = true;
+    requestAnimationFrame(() => { queued = false; apply(); });
+  };
+  new MutationObserver(later).observe(document.documentElement, { childList: true, subtree: true });
+  apply();
+})();
+`;
+
+/** The studio page with the skin linked in. */
+export function skinHtml(html: string): string {
+  const tags = `<link rel="stylesheet" href="${SKIN_PATH}.css"><script src="${SKIN_PATH}.js" defer></script>`;
+  return /<\/head>/i.test(html) ? html.replace(/<\/head>/i, `${tags}</head>`) : `${tags}${html}`;
+}

package/src/scene/studio.ts

@@ -0,0 +1,337 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { copyFile, mkdtemp, readFile, rm } from "node:fs/promises";
+import http, { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { FRAMEY_ENTRY } from "../product/probes.js";
+import { resolveHeadlessShell } from "../render/chrome.js";
+import { linesToBeats, scriptTemplate } from "../generate/script.js";
+import { SceneError, storeScene } from "./scene.js";
+import { SUPPLY_DIR, writeSupply } from "./supply.js";
+import { estimateTiming, type SceneTiming } from "./timing.js";
+import { sceneTimingFor } from "./audio.js";
+import { SKIN_CSS, SKIN_JS, SKIN_PATH, skinHtml } from "./studio-skin.js";
+import type { BeatInput } from "./timing.js";
+
+type Env = Record<string, string | undefined>;
+
+/** Where a studio looks for a free port first. Away from the dashboard's range and from 3012. */
+export const STUDIO_PORT_START = 47000;
+const PORT_SCAN = 200;
+
+/** Ports a studio never picks by itself: the dev dashboard (3012) and the test dashboards (4300 to 4391). */
+export function reservedPort(port: number): boolean {
+  return port === 3012 || (port >= 4300 && port <= 4391);
+}
+
+/** The studio SPA Framey serves, put into the package by scripts/sync-framey-studio.mjs. */
+export const STUDIO_BUNDLE = path.join(path.dirname(FRAMEY_ENTRY), "..", "dist", "studio", "index.html");
+
+export interface StudioArgs {
+  dir: string;
+  port: number | null;
+  noBrowser: boolean;
+}
+
+export type StudioArgsResult = { ok: true; args: StudioArgs } | { ok: false; message: string; fix: string };
+
+/** `scene studio DIR [--port N] [--no-browser]`; `argv` is what follows `studio`. */
+export function parseStudioArgs(argv: string[]): StudioArgsResult {
+  let dir: string | null = null;
+  let port: number | null = null;
+  let noBrowser = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    if (arg === "--no-browser") noBrowser = true;
+    else if (arg === "--port" || arg.startsWith("--port=")) {
+      const raw = arg === "--port" ? argv[(i += 1)] : arg.slice("--port=".length);
+      if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1024 || Number(raw) > 65535) {
+        return { ok: false, message: `--port needs a number from 1024 to 65535, not "${raw ?? ""}".`, fix: "for example `--port 47123`, or leave it out and vfrey picks a free port." };
+      }
+      port = Number(raw);
+    } else if (arg.startsWith("--")) {
+      return { ok: false, message: `scene studio does not know ${arg}.`, fix: "use `npx vfrey scene studio DIR [--port N] [--no-browser]`." };
+    } else if (dir === null) dir = arg;
+    else return { ok: false, message: `scene studio takes one folder, and got a second: ${arg}.`, fix: "pass just the scene folder." };
+  }
+  if (dir === null) return { ok: false, message: "scene studio needs a scene folder.", fix: "run `npx vfrey scene studio my-scene` (`npx vfrey scene init my-scene` writes one)." };
+  return { ok: true, args: { dir: path.resolve(dir), port, noBrowser } };
+}
+
+function freeOn(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.unref();
+    probe.once("error", (error: NodeJS.ErrnoException) => resolve(error.code !== "EADDRINUSE" && error.code !== "EACCES"));
+    probe.listen({ port, host }, () => probe.close(() => resolve(true)));
+  });
+}
+
+/** The first free loopback port from `start`, never a reserved one. Null when none of the next 200 is free. */
+export async function pickStudioPort(start = STUDIO_PORT_START, isFree: (port: number) => Promise<boolean> = (p) => freeOn(p, "127.0.0.1")): Promise<number | null> {
+  for (let port = start; port < start + PORT_SCAN && port <= 65535; port += 1) {
+    if (reservedPort(port)) continue;
+    if (await isFree(port)) return port;
+  }
+  return null;
+}
+
+/**
+ * What the studio and the scene it shows may load: only this origin. No request leaves the machine, whatever the scene
+ * says (the same rule as the network block while a scene renders). `unsafe-inline` and `unsafe-eval` are for the
+ * scene's own scripts and the studio's code editor; `connect-src 'self'` and `default-src 'self'` are what keep a
+ * scene from calling out.
+ */
+export const STUDIO_CSP = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: blob:",
+  "media-src 'self' data: blob:",
+  "font-src 'self' data:",
+  "connect-src 'self'",
+  "frame-src 'self' blob:",
+  "worker-src 'self' blob:",
+  "object-src 'none'",
+  "base-uri 'self'",
+  "form-action 'none'",
+  "frame-ancestors 'self'",
+].join("; ");
+
+/** True when the Host header names this studio's own loopback address (a rebound hostname does not). */
+export function hostAllowed(host: string | undefined, port: number): boolean {
+  return host === `127.0.0.1:${port}` || host === `localhost:${port}`;
+}
+
+/** Writes are allowed from the studio page itself only: no foreign Origin, no cross-site fetch. */
+export function writeAllowed(headers: http.IncomingHttpHeaders, port: number): boolean {
+  const origin = headers.origin;
+  if (origin && origin !== `http://127.0.0.1:${port}` && origin !== `http://localhost:${port}`) return false;
+  const site = headers["sec-fetch-site"];
+  return !site || site === "same-origin" || site === "none";
+}
+
+function refuse(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { "content-type": "text/plain; charset=utf-8", "content-security-policy": STUDIO_CSP });
+  res.end(`${message}\n`);
+}
+
+/** The face of the studio: a loopback server that checks Host and Origin, adds the CSP, and passes everything to Framey. */
+export function frontServer(publicPort: number, innerPort: number): Server {
+  const server = http.createServer((req: IncomingMessage, res: ServerResponse) => {
+    if (!hostAllowed(req.headers.host, publicPort)) return refuse(res, 403, `Unknown host. Open the studio at http://127.0.0.1:${publicPort}.`);
+    const method = req.method ?? "GET";
+    if (method !== "GET" && method !== "HEAD" && !writeAllowed(req.headers, publicPort)) return refuse(res, 403, "Writes are accepted from the studio page only.");
+    const pathname = (req.url ?? "/").split("?")[0]!;
+    if (method === "GET" && (pathname === `${SKIN_PATH}.css` || pathname === `${SKIN_PATH}.js`)) {
+      const css = pathname.endsWith(".css");
+      res.writeHead(200, { "content-type": css ? "text/css; charset=utf-8" : "text/javascript; charset=utf-8", "content-security-policy": STUDIO_CSP, "cache-control": "no-store", "x-content-type-options": "nosniff" });
+      return void res.end(css ? SKIN_CSS : SKIN_JS);
+    }
+    const headers = { ...req.headers, host: `127.0.0.1:${innerPort}` };
+    if (headers.origin) headers.origin = `http://127.0.0.1:${innerPort}`;
+    delete headers.referer;
+    delete headers["accept-encoding"];
+    const upstream = http.request({ host: "127.0.0.1", port: innerPort, method, path: req.url, headers }, (back) => {
+      const out = { ...back.headers };
+      delete out["content-security-policy"];
+      out["content-security-policy"] = STUDIO_CSP;
+      out["x-content-type-options"] = "nosniff";
+      out["referrer-policy"] = "no-referrer";
+      // The studio's own page (not the scene's preview, which is under /api) gets vfrey's skin.
+      if (method === "GET" && !pathname.startsWith("/api/") && String(back.headers["content-type"] ?? "").startsWith("text/html")) {
+        const chunks: Buffer[] = [];
+        back.on("data", (c: Buffer) => chunks.push(c));
+        back.on("end", () => {
+          const html = skinHtml(Buffer.concat(chunks).toString("utf8"));
+          delete out["content-length"];
+          delete out["content-encoding"];
+          delete out.etag;
+          delete out["transfer-encoding"];
+          res.writeHead(back.statusCode ?? 502, { ...out, "content-length": String(Buffer.byteLength(html)) });
+          res.end(html);
+        });
+        return;
+      }
+      res.writeHead(back.statusCode ?? 502, out);
+      back.pipe(res);
+    });
+    upstream.on("error", () => (res.headersSent ? res.destroy() : refuse(res, 502, "The studio's editor process is not answering.")));
+    res.on("close", () => upstream.destroy());
+    req.pipe(upstream);
+  });
+  server.on("upgrade", (_req, socket) => socket.destroy());
+  return server;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitUntilUp(port: number, child: ChildProcess, output: () => string, timeoutMs: number): Promise<void> {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if (child.exitCode !== null) throw new Error(`the editor process stopped: ${output().trim().split("\n").slice(-3).join(" ").slice(0, 300) || `exit code ${child.exitCode}`}`);
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/projects`, { signal: AbortSignal.timeout(1500) });
+      if (res.ok) return;
+    } catch {
+      /* not listening yet */
+    }
+    await sleep(120);
+  }
+  throw new Error("the editor process did not start in time");
+}
+
+export interface StudioHandle {
+  /** The address to open: the studio page with the scene's project selected. */
+  url: string;
+  port: number;
+  dir: string;
+  close(): Promise<void>;
+}
+
+export interface StartStudioInput {
+  dir: string;
+  port?: number | null;
+  env?: Env;
+  /** Timing and voice to supply, when the scene belongs to a run. Without them the scene's own `vfrey/` files are kept. */
+  supply?: { title: string; lines: string[]; beats: BeatInput[]; voiceFile: string | null };
+  timeoutMs?: number;
+}
+
+/** The folder must be an HTML scene. A React scene or a folder without one is a ✗ with a Fix. */
+export async function checkStudioScene(dir: string): Promise<void> {
+  const info = (() => {
+    try {
+      return statSync(dir);
+    } catch {
+      return null;
+    }
+  })();
+  if (!info?.isDirectory()) {
+    throw new SceneError(`The scene folder ${dir} does not exist.`, `write ${path.join(dir, "index.html")}, or run \`npx vfrey scene init ${dir}\` for a starting point.`, "scene_missing");
+  }
+  if (!existsSync(path.join(dir, "index.html"))) {
+    if (existsSync(path.join(dir, "index.tsx"))) {
+      throw new SceneError(
+        `The scene in ${dir} is a Remotion scene (index.tsx). The studio edits HTML scenes only.`,
+        `edit index.tsx in your own editor and render it with \`npx vfrey render --scene ${dir} --engine remotion\`, or write an HTML scene (\`npx vfrey scene init DIR\`) to use the studio.`,
+        "scene_studio_remotion",
+      );
+    }
+    throw new SceneError(`The scene folder ${dir} has no index.html.`, `write ${path.join(dir, "index.html")}, or run \`npx vfrey scene init ${dir}\` for a starting point.`, "scene_missing");
+  }
+  if (!existsSync(STUDIO_BUNDLE)) {
+    throw new SceneError("The studio is missing from this install.", "reinstall vfrey (`npm i -g @vfrey/vfrey`), or run `npm run sync:framey-studio` in a source checkout.", "studio_missing");
+  }
+}
+
+/** Writes the files vfrey supplies at render time into the scene folder, so the HTML opens the way a render would see it. */
+export async function supplyForStudio(dir: string, input: StartStudioInput["supply"], env: Env): Promise<void> {
+  let timing: SceneTiming | null = null;
+  let voiceFile: string | null = null;
+  let keep: string | null = null;
+  try {
+    if (input) {
+      timing = await sceneTimingFor({ title: input.title, lines: input.lines, beats: input.beats }, input.voiceFile, env);
+      voiceFile = input.voiceFile;
+    } else {
+      try {
+        timing = JSON.parse(await readFile(path.join(dir, SUPPLY_DIR, "timing.json"), "utf8")) as SceneTiming;
+      } catch {
+        timing = null;
+      }
+      const own = path.join(dir, SUPPLY_DIR, "voice.wav");
+      if (existsSync(own)) {
+        keep = await mkdtemp(path.join(os.tmpdir(), "vfrey-studio-voice-"));
+        voiceFile = path.join(keep, "voice.wav");
+        await copyFile(own, voiceFile);
+      }
+    }
+    if (!timing) {
+      const sample = JSON.parse(scriptTemplate()) as { title: string; lines: string[] };
+      timing = estimateTiming({ title: sample.title, lines: sample.lines, beats: linesToBeats(sample.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption })) });
+    }
+    await writeSupply({ dir, timing, voiceFile, kind: "html", env });
+  } finally {
+    if (keep) await rm(keep, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Starts the studio for a scene folder: supplies the vfrey files, runs the vendored Framey editor on a private loopback
+ * port, and puts a guard in front of it on the port the person opens. Edits are saved by the editor straight into `dir`.
+ */
+export async function startStudio(input: StartStudioInput): Promise<StudioHandle> {
+  const env = input.env ?? process.env;
+  const dir = path.resolve(input.dir);
+  await checkStudioScene(dir);
+  await supplyForStudio(dir, input.supply, env);
+  const port = input.port ?? (await pickStudioPort());
+  if (port === null || port === undefined) throw new SceneError("No free port was found for the studio.", "free a port from 47000 up, or pass --port N.", "studio_no_port");
+  if (!(await freeOn(port, "127.0.0.1"))) throw new SceneError(`Port ${port} is in use.`, "pass another --port N, or leave it out and vfrey picks a free one.", "studio_port_busy");
+  const innerPort = await pickStudioPort(port + 1, (p) => freeOn(p, "127.0.0.1"));
+  if (innerPort === null) throw new SceneError("No free port was found for the studio's editor process.", "free a port from 47000 up.", "studio_no_port");
+  const chrome = resolveHeadlessShell(env, process.cwd());
+  const childEnv = {
+    ...env,
+    HYPERFRAMES_PREVIEW_HOST: "127.0.0.1",
+    HYPERFRAMES_NO_TELEMETRY: "1",
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+    DO_NOT_TRACK: "1",
+    ...(chrome ? { PRODUCER_HEADLESS_SHELL_PATH: chrome, HYPERFRAMES_BROWSER_PATH: chrome } : {}),
+  } as NodeJS.ProcessEnv;
+  const child = spawn(process.execPath, [FRAMEY_ENTRY, "preview", dir, "--port", String(innerPort), "--no-open", "--foreground", "--force-new"], { env: childEnv, cwd: dir, stdio: ["ignore", "pipe", "pipe"] });
+  let output = "";
+  const collect = (chunk: Buffer) => {
+    output = (output + chunk.toString()).slice(-4000);
+  };
+  child.stdout?.on("data", collect);
+  child.stderr?.on("data", collect);
+  // If vfrey itself ends without closing the studio, the editor process must not outlive it.
+  const killOnExit = () => child.kill("SIGKILL");
+  process.once("exit", killOnExit);
+  const stop = async () => {
+    process.off("exit", killOnExit);
+    if (child.exitCode !== null) return;
+    child.kill("SIGTERM");
+    await Promise.race([new Promise((resolve) => child.once("exit", resolve)), sleep(4000)]);
+    if (child.exitCode === null) child.kill("SIGKILL");
+  };
+  try {
+    await waitUntilUp(innerPort, child, () => output, input.timeoutMs ?? 40_000);
+  } catch (error) {
+    await stop();
+    throw new SceneError(`The studio did not start: ${error instanceof Error ? error.message : String(error)}.`, "run `npx vfrey doctor`, then try again.", "studio_start_failed");
+  }
+  const front = frontServer(port, innerPort);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      front.once("error", reject);
+      front.listen(port, "127.0.0.1", () => resolve());
+    });
+  } catch (error) {
+    await stop();
+    throw new SceneError(`The studio could not listen on port ${port}: ${error instanceof Error ? error.message : String(error)}.`, "pass another --port N.", "studio_port_busy");
+  }
+  const id = path.basename(dir);
+  return {
+    url: `http://127.0.0.1:${port}/#project/${encodeURIComponent(id)}`,
+    port,
+    dir,
+    close: async () => {
+      front.closeAllConnections();
+      await new Promise<void>((resolve) => front.close(() => resolve()));
+      await stop();
+    },
+  };
+}
+
+/** The edit copy of a run's stored scene: `<scenes>/<name>-edit`. An earlier copy, which holds earlier edits, is kept. */
+export async function prepareEditCopy(input: { storedDir: string; scenesRoot: string; name: string }): Promise<{ dir: string; copied: boolean; warnings: string[] }> {
+  const dir = path.join(input.scenesRoot, `${input.name}-edit`);
+  if (existsSync(path.join(dir, "index.html"))) return { dir, copied: false, warnings: [] };
+  const stored = await storeScene(input.storedDir, dir);
+  return { dir, copied: true, warnings: stored.warnings };
+}

package/src/scene/supply.ts

@@ -0,0 +1,111 @@
+import { execFile } from "node:child_process";
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { glyphSvg, GLYPH_NAMES } from "./glyphs.js";
+import { figureSvg, POSES } from "./figure.js";
+import type { SceneTiming } from "./timing.js";
+
+type Env = Record<string, string | undefined>;
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const assets = path.join(here, "assets");
+/** Framey's shader-transition runtime, synced by scripts/sync-framey-transitions.mjs. */
+export const TRANSITIONS_DIR = path.join(here, "transitions");
+const deskFonts = path.resolve(here, "../desk/fonts");
+const run = promisify(execFile);
+
+/** The folder inside a scene that vfrey writes at render time. Anything the scene put there is replaced. */
+export const SUPPLY_DIR = "vfrey";
+
+/** The font files vfrey supplies, and the family each one is. */
+export const SUPPLIED_FONTS = [
+  { family: "Titan One", file: "titan-one.woff2", from: path.join(assets, "fonts", "titan-one.woff2"), weight: 400 },
+  { family: "JetBrains Mono", file: "jetbrains-mono-medium.woff2", from: path.join(deskFonts, "jetbrains-mono-medium.woff2"), weight: 500 },
+  { family: "Google Sans Flex", file: "google-sans-flex-latin.woff2", from: path.join(deskFonts, "google-sans-flex-latin.woff2"), weight: 400 },
+] as const;
+
+const FONT_LICENSES = [
+  { file: "TitanOne-OFL.txt", from: path.join(assets, "fonts", "TitanOne-OFL.txt") },
+  { file: "JetBrainsMono-OFL.txt", from: path.join(deskFonts, "JetBrainsMono-OFL.txt") },
+];
+
+let helperCache: string | null = null;
+
+/** The browser helper, bundled from `runtime/browser.ts` to one classic script. */
+export async function helperSource(): Promise<string> {
+  if (helperCache) return helperCache;
+  const { build } = await import("esbuild");
+  const result = await build({
+    entryPoints: [path.join(here, "runtime", "browser.ts")],
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    target: "es2020",
+    write: false,
+    logLevel: "silent",
+  });
+  helperCache = result.outputFiles[0]!.text;
+  return helperCache;
+}
+
+export function fontsCss(): string {
+  return `${SUPPLIED_FONTS.map(
+    (f) => `@font-face { font-family: "${f.family}"; src: url("${f.file}") format("woff2"); font-weight: ${f.weight}; font-style: normal; }`,
+  ).join("\n")}\n`;
+}
+
+/** The voice as `voice.wav`: copied when it already is one, converted with ffmpeg otherwise. */
+export async function writeVoice(voiceFile: string, dest: string, env: Env): Promise<void> {
+  if (voiceFile.toLowerCase().endsWith(".wav")) {
+    await copyFile(voiceFile, dest);
+    return;
+  }
+  await run("ffmpeg", ["-y", "-v", "error", "-i", voiceFile, "-ar", "44100", "-ac", "1", dest], { env: env as NodeJS.ProcessEnv, timeout: 120_000 });
+}
+
+export interface SupplyInput {
+  /** The scene folder; `vfrey/` is written inside it. */
+  dir: string;
+  timing: SceneTiming;
+  /** The voice track, or null for a silent render or a preview. */
+  voiceFile: string | null;
+  /** `html` scenes get the helper and GSAP; `tsx` scenes get `@vfrey/scene` from the bundler instead. */
+  kind: "html" | "tsx";
+  env?: Env;
+}
+
+/** Writes everything vfrey supplies to a scene into `dir/vfrey/`. */
+export async function writeSupply(input: SupplyInput): Promise<void> {
+  const out = path.join(input.dir, SUPPLY_DIR);
+  await rm(out, { recursive: true, force: true });
+  await mkdir(path.join(out, "fonts"), { recursive: true });
+  await mkdir(path.join(out, "assets"), { recursive: true });
+  await writeFile(path.join(out, "timing.json"), `${JSON.stringify(input.timing, null, 2)}\n`);
+  if (input.voiceFile) await writeVoice(input.voiceFile, path.join(out, "voice.wav"), input.env ?? process.env);
+  for (const font of SUPPLIED_FONTS) await copyFile(font.from, path.join(out, "fonts", font.file));
+  for (const license of FONT_LICENSES) await copyFile(license.from, path.join(out, "fonts", license.file));
+  await writeFile(path.join(out, "fonts", "fonts.css"), fontsCss());
+  if (input.kind === "html") {
+    await copyFile(path.join(assets, "gsap", "gsap.min.js"), path.join(out, "gsap.min.js"));
+    await copyFile(path.join(assets, "gsap", "LICENSE.txt"), path.join(out, "GSAP-LICENSE.txt"));
+    await copyFile(path.join(TRANSITIONS_DIR, "transitions.global.js"), path.join(out, "transitions.js"));
+    await writeFile(path.join(out, "TRANSITIONS-LICENSE.txt"), `${await readFile(path.join(TRANSITIONS_DIR, "NOTICE"), "utf8")}\n${await readFile(path.join(TRANSITIONS_DIR, "LICENSE"), "utf8")}`);
+    await writeFile(path.join(out, "vfrey.js"), `window.__vfreyTiming = ${JSON.stringify(input.timing)};\n${await helperSource()}`);
+  }
+  for (const [file, svg] of Object.entries(assetLibrary())) await writeFile(path.join(out, "assets", file), svg);
+}
+
+/** The asset library: stick-figure poses and line glyphs, as `file name -> SVG`. */
+export function assetLibrary(): Record<string, string> {
+  const files: Record<string, string> = {};
+  for (const pose of POSES) files[`stick-${pose.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}.svg`] = figureSvg(pose);
+  for (const name of GLYPH_NAMES) files[`glyph-${name}.svg`] = glyphSvg(name);
+  return files;
+}
+
+/** Reads a supplied file back, for tests and the starter. */
+export async function readSupplied(dir: string, name: string): Promise<string> {
+  return readFile(path.join(dir, SUPPLY_DIR, name), "utf8");
+}