@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/scene/command.ts

@@ -0,0 +1,272 @@
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { linesToBeats, scriptTemplate, validateScript } from "../generate/script.js";
+import { dataDirFor } from "../home.js";
+import { chooseEngine, readMachineEngine, readProjectEngine, unavailableMessage, failedMessage } from "../product/engine-choice.js";
+import { engineById, engineStatus, type EngineProbes } from "../product/engines.js";
+import { defaultProbes } from "../product/probes.js";
+import { configFile, productDir } from "../product/paths.js";
+import { readProductConfig } from "../product/config-file.js";
+import { forcedFailure } from "../render/html-engine.js";
+import { addBlock, blockCategories, blockIndex, listBlocks, type BlockInfo } from "./blocks.js";
+import { initScene } from "./init.js";
+import { runSceneStudio } from "./studio-command.js";
+import { transitionIndex } from "./transitions.js";
+import { formatText } from "./inspect/report.js";
+import { inspectScene } from "./inspect/run.js";
+import { renderScene, type SceneEngine } from "./render.js";
+import { checkScene, SceneError, storeScene } from "./scene.js";
+
+interface Io {
+  env: NodeJS.ProcessEnv;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  probes?: EngineProbes;
+}
+
+function flag(argv: string[], name: string): string | null {
+  const at = argv.indexOf(name);
+  if (at === -1) return null;
+  const value = argv[at + 1];
+  return value && !value.startsWith("--") ? value : null;
+}
+
+const ENGINE_ALIASES: Record<string, string> = { framey: "vfrey-framey", "vfrey-framey": "vfrey-framey", hyperframes: "hyperframes", remotion: "remotion" };
+
+const kb = (bytes: number) => `${(bytes / 1024).toFixed(1)} KB`;
+
+function blockRows(blocks: BlockInfo[]): string {
+  const width = Math.max(...blocks.map((b) => b.name.length));
+  const cat = Math.max(...blocks.map((b) => b.category.length));
+  return blocks
+    .map((b) => {
+      const text = b.description.length > 78 ? `${b.description.slice(0, 77).trimEnd()}…` : b.description;
+      return `${b.name.padEnd(width)}  ${b.category.padEnd(cat)}  ${kb(b.bytes).padStart(7)}  ${`${b.duration} s`.padStart(7)}  ${text}`;
+    })
+    .join("\n");
+}
+
+/** `vfrey scene blocks [--json] [--category X]`. */
+async function listCommand(argv: string[], io: Io): Promise<number> {
+  const category = flag(argv, "--category");
+  if (argv.includes("--category") && !category) {
+    io.stderr(`✗ --category needs a name.\nFix: choose one of ${(await blockCategories()).join(", ")}.\n`);
+    return 1;
+  }
+  const blocks = await listBlocks({ category: category ?? undefined });
+  if (category && blocks.length === 0) {
+    io.stderr(`✗ There is no block category "${category}".\nFix: choose one of ${(await blockCategories()).join(", ")}.\n`);
+    return 1;
+  }
+  if (argv.includes("--json")) {
+    const index = await blockIndex();
+    io.stdout(`${JSON.stringify({ source: index.source, commit: index.commit, count: blocks.length, blocks: blocks.map(({ files: _files, source: _source, ...rest }) => rest) }, null, 2)}\n`);
+    return 0;
+  }
+  const total = blocks.reduce((sum, b) => sum + b.bytes, 0);
+  io.stdout(`${blockRows(blocks)}\n\n${blocks.length} blocks, ${kb(total)}. Add one: npx vfrey scene add BLOCK DIR\n`);
+  return 0;
+}
+
+/** `vfrey scene transitions [--json]`. */
+async function transitionsCommand(argv: string[], io: Io): Promise<number> {
+  const index = await transitionIndex();
+  if (argv.includes("--json")) {
+    io.stdout(`${JSON.stringify({ ...index, count: index.transitions.length, engines: { "vfrey-framey": true, hyperframes: true, remotion: false } }, null, 2)}\n`);
+    return 0;
+  }
+  const width = Math.max(...index.transitions.map((t) => t.name.length));
+  const rows = index.transitions.map((t) => `${t.name.padEnd(width)}  ${(t.gpu ? "WebGL" : "no GPU").padEnd(6)}  ${t.look}`).join("\n");
+  io.stdout(
+    `${rows}\n\n${index.transitions.length} transitions. In an HTML scene (vfrey-framey or hyperframes; not Remotion):\n` +
+      `  <script src="vfrey/transitions.js"></script> before <script src="vfrey/vfrey.js"></script>, then\n` +
+      `  vfrey.transition("#shot-a", "#shot-b", { type: "${index.default}", at: 3.2, duration: ${index.defaultSeconds} });\n`,
+  );
+  return 0;
+}
+
+/** `vfrey scene inspect DIR [--at S] [--selector CSS | --text "..."] [--script FILE] [--json]`. */
+async function inspectCommand(argv: string[], io: Io): Promise<number> {
+  const fail = (message: string, fix: string) => {
+    io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+    return 1;
+  };
+  const valued = ["--at", "--selector", "--text", "--script"];
+  const dir = argv.slice(1).find((a, i) => !a.startsWith("--") && !valued.includes(argv[i] ?? ""));
+  if (!dir) return fail("scene inspect needs a scene folder.", 'run `npx vfrey scene inspect my-scene --text "visible words"`.');
+  const atRaw = flag(argv, "--at");
+  const at = atRaw === null ? 0 : Number(atRaw);
+  if (!Number.isFinite(at) || at < 0) return fail(`--at needs a time in seconds, not "${atRaw}".`, "for example `--at 2.5`.");
+  const selector = flag(argv, "--selector");
+  const text = flag(argv, "--text");
+  for (const name of ["--selector", "--text", "--script", "--at"]) {
+    if (argv.includes(name) && flag(argv, name) === null) return fail(`${name} needs a value.`, `for example ${name === "--text" ? '--text "Big title"' : name === "--selector" ? "--selector '#title'" : name === "--at" ? "--at 2.5" : "--script script.json"}.`);
+  }
+  if (selector && text) return fail("Use --selector or --text, not both.", "pick the one that names the element best.");
+  const abs = path.resolve(dir);
+  let script;
+  const scriptFile = flag(argv, "--script");
+  if (scriptFile) {
+    const raw = await readFile(path.resolve(scriptFile), "utf8").catch(() => null);
+    if (raw === null) return fail(`Cannot read the script file ${scriptFile}.`, "check the path.");
+    const checked = validateScript(raw);
+    if (!checked.ok) return fail(`${scriptFile}: ${checked.message}`, checked.fix);
+    script = checked.script;
+  }
+  try {
+    const kind = await Promise.all([stat(path.join(abs, "index.html")).then(() => true, () => false), stat(path.join(abs, "index.tsx")).then(() => true, () => false)]);
+    if (!kind[0] && kind[1]) {
+      return fail(
+        `The scene in ${dir} is a Remotion scene (index.tsx); scene inspect reads HTML scenes (vfrey-framey or hyperframes), because it traces elements, CSS rules and GSAP tweens.`,
+        `look at it with \`npx vfrey render --scene ${dir} --engine remotion --frame 2.5 out.png\` and edit the component in index.tsx.`,
+      );
+    }
+    const report = await inspectScene({ dir: abs, at, selector, text, script, env: io.env });
+    io.stdout(argv.includes("--json") ? `${JSON.stringify(report, null, 2)}\n` : formatText(report));
+    return 0;
+  } catch (error) {
+    if (error instanceof SceneError) return fail(error.message, error.fix);
+    return fail(error instanceof Error ? error.message : String(error), "run `npx vfrey doctor`, then try again.");
+  }
+}
+
+/** `vfrey scene add BLOCK DIR [--force] [--json]`. */
+async function addCommand(argv: string[], io: Io): Promise<number> {
+  const positional = argv.slice(1).filter((a) => !a.startsWith("--"));
+  const [name, dir] = positional;
+  if (!name || !dir) {
+    io.stderr("✗ scene add needs a block and a scene folder.\nFix: run `npx vfrey scene add lt-clean-bar my-scene`; `npx vfrey scene blocks` lists the blocks.\n");
+    return 1;
+  }
+  try {
+    const result = await addBlock(path.resolve(dir), name, { force: argv.includes("--force") });
+    if (argv.includes("--json")) {
+      io.stdout(`${JSON.stringify({ block: result.block.name, status: result.status, dest: result.dest, files: result.files, html: result.snippet.html, script: result.snippet.script }, null, 2)}\n`);
+      return 0;
+    }
+    const verb = result.status === "unchanged" ? "Already in the scene (unchanged)" : result.status === "replaced" ? "Replaced" : "Added";
+    io.stdout(`${verb}: ${path.relative(process.cwd(), result.dest) || result.dest} (${result.block.files.length} file, ${kb(result.block.bytes)})\n\n${result.snippet.text}`);
+    return 0;
+  } catch (error) {
+    if (error instanceof SceneError) {
+      io.stderr(`✗ ${error.message}\nFix: ${error.fix}\n`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+/** `vfrey scene init DIR [--engine framey|hyperframes|remotion]`, `scene blocks`, `scene add`. */
+export async function runSceneCommand(argv: string[], io: Io): Promise<number> {
+  const [action, dir] = argv;
+  if (action === "blocks") return listCommand(argv, io);
+  if (action === "add") return addCommand(argv, io);
+  if (action === "transitions") return transitionsCommand(argv, io);
+  if (action === "studio") return runSceneStudio(argv.slice(1), io);
+  if (action === "inspect") return inspectCommand(argv, io);
+  if (action !== "init") {
+    io.stderr(`✗ Unknown scene command "${action ?? ""}".\nFix: use \`npx vfrey scene init DIR [--engine framey|hyperframes|remotion]\`, \`scene blocks\`, \`scene add BLOCK DIR\`, or \`scene transitions\`.\n`);
+    return 1;
+  }
+  if (!dir || dir.startsWith("--")) {
+    io.stderr("✗ scene init needs a folder.\nFix: run `npx vfrey scene init my-scene`.\n");
+    return 1;
+  }
+  const asked = flag(argv, "--engine") ?? "framey";
+  const id = ENGINE_ALIASES[asked.toLowerCase()];
+  if (!id) {
+    io.stderr(`✗ "${asked}" is not an engine that renders scenes.\nFix: choose framey, hyperframes, or remotion.\n`);
+    return 1;
+  }
+  const kind = id === "remotion" ? "tsx" : "html";
+  try {
+    const written = await initScene(path.resolve(dir), kind, io.env);
+    io.stdout(`Scene written: ${written[0]}\nvfrey's files (timing, helper, fonts, GSAP, art) are in ${written[1]}; they are rewritten at render time.\nPreview a frame: npx vfrey render --scene ${dir} --engine ${id} --frame 2.5 out.png\n`);
+    return 0;
+  } catch (error) {
+    io.stderr(`✗ ${error instanceof Error ? error.message : String(error)}\nFix: pick a folder that has no scene yet, or edit the one that is there.\n`);
+    return 1;
+  }
+}
+
+/** `vfrey render --scene DIR [--engine id] [--script FILE] [--frame SECONDS OUT.png | --output OUT.mp4]`. */
+export async function runSceneRender(argv: string[], io: Io): Promise<number> {
+  const fail = (message: string, fix: string) => {
+    io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+    return 1;
+  };
+  const dir = path.resolve(flag(argv, "--scene")!);
+  const dataDir = dataDirFor(io.env);
+  const dir0 = productDir(io.env);
+  const config = await readProductConfig(configFile(dir0), dir0);
+  const requested = flag(argv, "--engine");
+  let engine;
+  try {
+    engine = chooseEngine({ command: requested, project: readProjectEngine(), machine: readMachineEngine(dataDir) ?? config.defaultEngine }).engine;
+  } catch {
+    return fail(`"${requested}" is not an engine.`, "choose remotion, hyperframes, or vfrey-framey.");
+  }
+  try {
+    await checkScene(dir, engine.id);
+  } catch (error) {
+    if (error instanceof SceneError) return fail(error.message, error.fix);
+    throw error;
+  }
+  const probes = io.probes ?? (await defaultProbes(io.env));
+  if (engineStatus(engine, probes).availability === "unavailable") {
+    const [what, fix] = unavailableMessage(engine, probes).split(" Fix: ");
+    return fail(what ?? "", fix ?? "run `npx vfrey doctor`.");
+  }
+  let script;
+  const scriptFile = flag(argv, "--script");
+  if (scriptFile) {
+    let text: string;
+    try {
+      text = await readFile(path.resolve(scriptFile), "utf8");
+    } catch {
+      return fail(`Cannot read the script file ${scriptFile}.`, "check the path.");
+    }
+    const checked = validateScript(text);
+    if (!checked.ok) return fail(`${scriptFile}: ${checked.message}`, checked.fix);
+    script = checked.script;
+  } else {
+    script = validateScript(scriptTemplate());
+    if (!script.ok) return fail("The sample script is broken.", "report this bug.");
+    script = script.script;
+  }
+  const frameAtRaw = flag(argv, "--frame");
+  const frameAt = frameAtRaw === null ? undefined : Number(frameAtRaw);
+  if (frameAt !== undefined && (!Number.isFinite(frameAt) || frameAt < 0)) return fail(`--frame needs a time in seconds, not "${frameAtRaw}".`, "for example `--frame 2.5 out.png`.");
+  const positional = argv.filter((a, i) => !a.startsWith("--") && !["--scene", "--engine", "--script", "--frame", "--output", "--subject"].includes(argv[i - 1] ?? ""))[0];
+  const output = path.resolve(flag(argv, "--output") ?? positional ?? (frameAt === undefined ? path.join(config.outputDir, `scene-${engine.id}.mp4`) : "scene-frame.png"));
+  const work = await mkdtemp(path.join(os.tmpdir(), "vfrey-scene-"));
+  try {
+    const forced = forcedFailure(engine.id, io.env);
+    if (forced) throw new Error(forced);
+    const stored = await storeScene(dir, path.join(work, "scene"));
+    for (const message of stored.warnings) io.stderr(`! ${message}\n`);
+    await renderScene({
+      engine: engine.id as SceneEngine,
+      sceneDir: path.join(work, "scene"),
+      title: script.title,
+      lines: script.lines,
+      beats: linesToBeats(script.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption })),
+      voiceoverPath: null,
+      outputPath: output,
+      workDir: path.join(work, "render"),
+      frameAt,
+      env: io.env,
+      warn: (message) => io.stderr(`! ${message}\n`),
+    });
+    io.stdout(`${output}\n`);
+    return 0;
+  } catch (error) {
+    const [what, fix] = failedMessage(engine, error, probes).split(" Fix: ");
+    return fail(what ?? "", fix ?? "run `npx vfrey doctor`.");
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+

package/src/scene/figure.ts

@@ -0,0 +1,181 @@
+export const POSES = ["shrug", "pointLeft", "pointRight", "idea"] as const;
+export type Pose = (typeof POSES)[number];
+
+/**
+ * The stick figure, drawn from scratch as a pen sketch: every stroke goes through a few jittered points and is
+ * inked twice, a heavy pass and a thin offset pass, so the line weight is uneven and the ends are round.
+ */
+
+type Pt = [number, number];
+
+function rng(seed: number): () => number {
+  let s = seed >>> 0 || 1;
+  return () => {
+    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+    return s / 4294967296 - 0.5;
+  };
+}
+
+/** How heavy the pen is: the reference figure is drawn with a thick marker line. */
+const HEAVY = 1.55;
+
+const r1 = (n: number) => Math.round(n * 10) / 10;
+
+function smooth(points: Pt[]): string {
+  if (points.length === 1) return `M${r1(points[0]![0])} ${r1(points[0]![1])}`;
+  let d = `M${r1(points[0]![0])} ${r1(points[0]![1])}`;
+  for (let i = 1; i < points.length - 1; i += 1) {
+    const [x, y] = points[i]!;
+    const [nx, ny] = points[i + 1]!;
+    d += `Q${r1(x)} ${r1(y)} ${r1((x + nx) / 2)} ${r1((y + ny) / 2)}`;
+  }
+  const end = points[points.length - 1]!;
+  return d + `L${r1(end[0])} ${r1(end[1])}`;
+}
+
+/** Adds a wobbling extra point on each long segment so a straight line is not ruler-straight. */
+function sketch(points: Pt[], rand: () => number, amount: number): Pt[] {
+  const out: Pt[] = [points[0]!];
+  for (let i = 1; i < points.length; i += 1) {
+    const [x0, y0] = points[i - 1]!;
+    const [x1, y1] = points[i]!;
+    const len = Math.hypot(x1 - x0, y1 - y0);
+    const extra = Math.min(3, Math.floor(len / 70));
+    for (let k = 1; k <= extra; k += 1) {
+      const t = k / (extra + 1);
+      out.push([x0 + (x1 - x0) * t + rand() * amount * 2, y0 + (y1 - y0) * t + rand() * amount * 2]);
+    }
+    out.push([x1 + (i === points.length - 1 ? 0 : rand() * amount), y1 + (i === points.length - 1 ? 0 : rand() * amount)]);
+  }
+  return out;
+}
+
+class Pen {
+  private parts: string[] = [];
+  private rand: () => number;
+  constructor(seed: number) {
+    this.rand = rng(seed);
+  }
+  stroke(points: Pt[], width0 = 13): this {
+    const width = Math.round(width0 * HEAVY);
+    const base = sketch(points, this.rand, 2.2);
+    this.parts.push(`<path d="${smooth(base)}" stroke-width="${width}"/>`);
+    const second = sketch(points.map(([x, y]): Pt => [x + 2.4, y - 1.6]), this.rand, 2.6);
+    this.parts.push(`<path d="${smooth(second)}" stroke-width="${Math.max(3, Math.round(width * 0.38))}"/>`);
+    return this;
+  }
+  dot(x: number, y: number, rx: number, ry: number, rot = 0): this {
+    this.parts.push(`<ellipse cx="${x}" cy="${y}" rx="${rx}" ry="${ry}" transform="rotate(${rot} ${x} ${y})" fill="#000" stroke-width="3"/>`);
+    return this;
+  }
+  /** A closed loop drawn by hand: the pen overshoots where it started. */
+  loop(cx: number, cy: number, rx: number, ry: number, width0 = 13, turn = 0): this {
+    const width = Math.round(width0 * HEAVY);
+    const pts: Pt[] = [];
+    const steps = 14;
+    for (let i = 0; i <= steps + 2; i += 1) {
+      const a = turn + (i / steps) * Math.PI * 2;
+      const wobble = 1 + this.rand() * 0.035 + (i > steps ? 0.045 : 0);
+      pts.push([cx + Math.cos(a) * rx * wobble, cy + Math.sin(a) * ry * wobble]);
+    }
+    this.parts.push(`<path d="${smooth(pts)}" stroke-width="${width}"/>`);
+    const again = pts.slice(2, 12).map(([x, y]): Pt => [x + 3, y - 2]);
+    this.parts.push(`<path d="${smooth(again)}" stroke-width="${Math.round(width * 0.38)}"/>`);
+    return this;
+  }
+  raw(svg: string): this {
+    this.parts.push(svg);
+    return this;
+  }
+  get svg(): string {
+    return this.parts.join("");
+  }
+}
+
+const HEAD: Pt = [300, 172];
+
+function open(hand: Pt, dir: 1 | -1, pen: Pen): void {
+  // An open palm, facing up: a flat leaf with a thumb.
+  const [x, y] = hand;
+  pen.stroke([[x, y], [x + dir * 40, y - 14], [x + dir * 82, y - 4], [x + dir * 44, y + 14], [x + dir * 6, y + 10]], 10);
+  pen.stroke([[x + dir * 30, y - 12], [x + dir * 34, y - 30]], 8);
+}
+
+function legs(pen: Pen): void {
+  pen.stroke([[300, 232], [300, 310], [297, 440]], 15);
+  pen.stroke([[297, 440], [262, 560], [226, 690]], 15);
+  pen.stroke([[297, 440], [338, 560], [372, 690]], 15);
+  pen.loop(206, 700, 36, 11, 9);
+  pen.loop(392, 700, 36, 11, 9);
+}
+
+function faceLook(pen: Pen, mood: "puzzled" | "happy", gaze: number): void {
+  const gx = gaze;
+  pen.loop(HEAD[0], HEAD[1], 80, 80, 14, -1.2);
+  pen.stroke([[238, 112], [250, 96], [243, 86]], 4); // a tuft of hair
+  pen.stroke([[256, 100], [272, 88]], 4);
+  pen.dot(268 + gx, 170, 8, 13, 8).dot(334 + gx, 168, 8, 13, -6);
+  if (mood === "puzzled") {
+    pen.stroke([[246 + gx, 152], [268 + gx, 146], [292 + gx, 150]], 5); // flat brow
+    pen.stroke([[322 + gx, 140], [345 + gx, 122], [372 + gx, 136]], 5); // raised brow
+    pen.loop(308 + gx, 210, 8, 11, 4);
+  } else {
+    pen.stroke([[250 + gx, 150], [268 + gx, 142], [290 + gx, 148]], 5);
+    pen.stroke([[322 + gx, 146], [340 + gx, 138], [360 + gx, 146]], 5);
+    pen.stroke([[272 + gx, 206], [300 + gx, 226], [338 + gx, 204]], 5);
+  }
+}
+
+function questionMark(pen: Pen): void {
+  pen.stroke([[388, 62], [402, 38], [430, 34], [448, 54], [434, 80], [414, 94], [412, 114]], 9);
+  pen.dot(412, 140, 6, 6);
+}
+
+function ticks(pen: Pen, cx: number, cy: number, dir: 1 | -1): void {
+  pen.stroke([[cx, cy], [cx + dir * 26, cy - 20]], 6);
+  pen.stroke([[cx - dir * 4, cy + 28], [cx + dir * 24, cy + 18]], 6);
+}
+
+function bulb(pen: Pen, x: number, y: number): void {
+  pen.raw(`<path d="M${x - 26} ${y + 30}a44 44 0 1 1 52 0c-10 8-12 18-12 28h-28c0-10-2-20-12-28z" fill="#E3F2FD" stroke-width="9"/>`);
+  pen.stroke([[x - 14, y + 72], [x + 14, y + 72]], 8);
+  pen.stroke([[x - 8, y + 88], [x + 8, y + 88]], 7);
+  pen.stroke([[x - 6, y + 40], [x - 2, y + 22], [x + 6, y + 40]], 5);
+  for (const [dx, dy, ex, ey] of [[0, -60, 0, -78], [-50, -34, -66, -46], [50, -34, 66, -46], [-64, 8, -84, 10], [64, 8, 84, 10]] as const) {
+    pen.stroke([[x + dx, y + dy], [x + ex, y + ey]], 7);
+  }
+}
+
+/** The figure, as one SVG document of 600 by 780 units. Stroke is black, fill is none unless a shape says so. */
+export function figureSvg(pose: Pose): string {
+  const pen = new Pen({ shrug: 11, pointLeft: 23, pointRight: 37, idea: 51 }[pose]);
+  legs(pen);
+  if (pose === "shrug") {
+    faceLook(pen, "puzzled", 0);
+    questionMark(pen);
+    pen.stroke([[300, 268], [226, 370], [150, 330]], 14);
+    pen.stroke([[300, 268], [374, 370], [450, 330]], 14);
+    open([142, 318], -1, pen);
+    open([458, 318], 1, pen);
+    ticks(pen, 88, 246, -1);
+    ticks(pen, 512, 246, 1);
+  } else if (pose === "pointLeft") {
+    faceLook(pen, "happy", -16);
+    pen.stroke([[300, 268], [226, 232], [136, 182]], 14);
+    pen.stroke([[136, 182], [96, 160], [52, 140]], 8); // the pointing finger
+    pen.stroke([[300, 268], [352, 352], [338, 438]], 14);
+  } else if (pose === "pointRight") {
+    faceLook(pen, "happy", 16);
+    pen.stroke([[300, 268], [374, 232], [464, 182]], 14);
+    pen.stroke([[464, 182], [504, 160], [548, 140]], 8);
+    pen.stroke([[300, 268], [248, 352], [262, 438]], 14);
+  } else {
+    faceLook(pen, "happy", 0);
+    pen.stroke([[300, 268], [236, 338], [262, 408]], 14);
+    pen.stroke([[300, 268], [380, 236], [424, 176]], 14);
+    pen.stroke([[424, 176], [430, 150]], 8);
+    bulb(pen, 470, 92);
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 780" fill="none" stroke="#000" stroke-linecap="round" stroke-linejoin="round">${pen.svg}</svg>`;
+}
+

package/src/scene/glyphs.ts

@@ -0,0 +1,107 @@
+/** Simple line glyphs a scene may use or ignore: common ideas in a thick marker line, 400 by 400 units. */
+
+export const GLYPH_NAMES = ["cpu", "threads", "lock", "database", "cloud", "server", "cache", "queue", "network", "file", "key", "gear", "arrow", "check", "cross", "question", "star", "clock", "bulb", "person", "chat", "globe"] as const;
+export type GlyphName = (typeof GLYPH_NAMES)[number];
+
+const INK = "#000000";
+const ICE = "#E3F2FD";
+const SKY = "#90CAF9";
+const BLUE = "#2196F3";
+const NAVY = "#0D47A1";
+
+const open = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" fill="none" stroke="${INK}" stroke-width="13" stroke-linecap="round" stroke-linejoin="round">`;
+
+const BODIES: Record<GlyphName, string> = {
+  cpu: `
+    <rect x="95" y="95" width="210" height="210" rx="24" fill="${ICE}"/>
+    <rect x="145" y="145" width="110" height="110" rx="14" fill="${BLUE}" stroke="${NAVY}"/>
+    <path d="M140 95V45M200 95V40M260 95V46M140 305v52M200 305v55M260 305v50M95 140H45M95 200H40M95 260h-50M305 140h52M305 200h55M305 260h50"/>`,
+  threads: `
+    <path d="M50 110C120 80 150 140 210 110S300 80 350 110" stroke="${BLUE}" stroke-width="16"/>
+    <path d="M50 200C110 170 160 230 215 200S300 170 350 200"/>
+    <path d="M50 290C130 260 150 320 210 290S300 262 350 290" stroke="${NAVY}"/>
+    <path d="M318 88l34 22-36 20M318 178l34 22-36 20M318 268l34 22-36 20" stroke-width="11"/>`,
+  lock: `
+    <path d="M130 175V130a70 70 0 0 1 140 0v45" stroke-width="18"/>
+    <rect x="85" y="170" width="230" height="180" rx="26" fill="${ICE}"/>
+    <circle cx="200" cy="248" r="24" fill="${BLUE}" stroke="${NAVY}"/>
+    <path d="M200 270v40"/>`,
+  database: `
+    <ellipse cx="200" cy="100" rx="120" ry="42" fill="${ICE}"/>
+    <path d="M80 100v200c0 24 54 42 120 42s120-18 120-42V100"/>
+    <path d="M80 200c0 24 54 42 120 42s120-18 120-42" stroke="${NAVY}"/>`,
+  cloud: `
+    <path d="M120 295a72 72 0 0 1-8-143 92 92 0 0 1 176 18 62 62 0 0 1 4 125z" fill="${ICE}"/>
+    <path d="M150 250c30-26 70-26 100 0" stroke="${BLUE}" stroke-width="15"/>
+    <path d="M200 228v-45m-26 22 26-26 26 26" stroke="${NAVY}" stroke-width="11"/>`,
+  server: `
+    <rect x="80" y="60" width="240" height="80" rx="16" fill="${ICE}"/>
+    <rect x="80" y="160" width="240" height="80" rx="16" fill="${ICE}"/>
+    <rect x="80" y="260" width="240" height="80" rx="16" fill="${ICE}"/>
+    <circle cx="125" cy="100" r="9" fill="${BLUE}" stroke="${BLUE}"/><circle cx="125" cy="200" r="9" fill="${BLUE}" stroke="${BLUE}"/><circle cx="125" cy="300" r="9" fill="${BLUE}" stroke="${BLUE}"/>
+    <path d="M190 100h95M190 200h95M190 300h95" stroke="${NAVY}"/>`,
+  cache: `
+    <path d="M232 40L120 215h72l-26 145 116-190h-74z" fill="${BLUE}" stroke="${NAVY}"/>
+    <path d="M60 130h50M40 200h60M65 270h45" stroke="${SKY}" stroke-width="12"/>`,
+  queue: `
+    <rect x="45" y="140" width="80" height="120" rx="12" fill="${ICE}"/>
+    <rect x="135" y="140" width="80" height="120" rx="12" fill="${ICE}"/>
+    <rect x="225" y="140" width="80" height="120" rx="12" fill="${BLUE}" stroke="${NAVY}"/>
+    <path d="M325 200h48m-20-22 22 22-22 22" stroke="${NAVY}"/>
+    <path d="M45 310h260" stroke="${SKY}" stroke-width="10"/>`,
+  network: `
+    <circle cx="200" cy="90" r="38" fill="${BLUE}" stroke="${NAVY}"/>
+    <circle cx="85" cy="300" r="38" fill="${ICE}"/>
+    <circle cx="315" cy="300" r="38" fill="${ICE}"/>
+    <path d="M178 124L108 270M222 124l70 146M123 300h154" stroke-width="11"/>`,
+  file: `
+    <path d="M100 50h130l80 80v220a8 8 0 0 1-8 8H100a8 8 0 0 1-8-8V58a8 8 0 0 1 8-8z" fill="${ICE}"/>
+    <path d="M230 50v80h80"/>
+    <path d="M135 200h135M135 245h135M135 290h90" stroke="${BLUE}" stroke-width="14"/>`,
+  key: `
+    <circle cx="125" cy="150" r="78" fill="${ICE}"/>
+    <circle cx="105" cy="130" r="18" fill="${BLUE}" stroke="${NAVY}"/>
+    <path d="M178 205L340 365M270 295l-34 34M310 335l-30 30"/>`,
+  gear: `
+    <path d="M170 40h60l10 42 36 15 38-22 42 42-22 38 15 36 42 10v60l-42 10-15 36 22 38-42 42-38-22-36 15-10 42h-60l-10-42-36-15-38 22-42-42 22-38-15-36-42-10v-60l42-10 15-36-22-38 42-42 38 22 36-15z" transform="translate(0 0) scale(.92) translate(17 17)" fill="${ICE}"/>
+    <circle cx="200" cy="200" r="52" fill="${BLUE}" stroke="${NAVY}"/>`,
+
+  arrow: `
+    <path d="M60 200h250m-100-100 100 100-100 100" stroke="${NAVY}" stroke-width="22"/>`,
+  check: `
+    <circle cx="200" cy="200" r="150" fill="${ICE}"/>
+    <path d="M120 205l55 55 105-120" stroke="${BLUE}" stroke-width="26"/>`,
+  cross: `
+    <circle cx="200" cy="200" r="150" fill="${ICE}"/>
+    <path d="M135 135l130 130M265 135L135 265" stroke="${NAVY}" stroke-width="26"/>`,
+  question: `
+    <circle cx="200" cy="200" r="150" fill="${ICE}"/>
+    <path d="M148 160c0-34 24-54 54-54s54 20 54 50c0 34-54 40-54 82" stroke="${BLUE}" stroke-width="22"/>
+    <circle cx="202" cy="296" r="11" fill="${NAVY}" stroke="${NAVY}"/>`,
+  star: `
+    <path d="M200 50l45 98 106 12-79 72 22 105-94-54-94 54 22-105-79-72 106-12z" fill="${ICE}"/>
+    <path d="M200 120l22 48 52 6-39 36 11 52-46-27-46 27 11-52-39-36 52-6z" fill="${BLUE}" stroke="${NAVY}" stroke-width="8"/>`,
+  clock: `
+    <circle cx="200" cy="200" r="150" fill="${ICE}"/>
+    <path d="M200 110v95l62 40" stroke="${NAVY}" stroke-width="20"/>
+    <circle cx="200" cy="200" r="10" fill="${BLUE}" stroke="${BLUE}"/>`,
+  bulb: `
+    <path d="M140 270a100 100 0 1 1 120 0c-14 12-18 26-18 42h-84c0-16-4-30-18-42z" fill="${ICE}"/>
+    <path d="M160 340h80M175 366h50" stroke="${NAVY}"/>
+    <path d="M185 240l15-40 15 40" stroke="${BLUE}" stroke-width="10"/>`,
+  person: `
+    <circle cx="200" cy="120" r="60" fill="${ICE}"/>
+    <path d="M70 350c0-85 55-130 130-130s130 45 130 130z" fill="${ICE}"/>`,
+  chat: `
+    <path d="M60 90h280a20 20 0 0 1 20 20v160a20 20 0 0 1-20 20H190l-70 60v-60H60a20 20 0 0 1-20-20V110a20 20 0 0 1 20-20z" fill="${ICE}"/>
+    <path d="M100 160h200M100 215h130" stroke="${BLUE}" stroke-width="14"/>`,
+  globe: `
+    <circle cx="200" cy="200" r="150" fill="${ICE}"/>
+    <ellipse cx="200" cy="200" rx="60" ry="150" stroke="${BLUE}"/>
+    <path d="M50 200h300M80 120h240M80 280h240" stroke="${NAVY}" stroke-width="9"/>`,
+};
+
+export function glyphSvg(name: GlyphName): string {
+  return `${open}${BODIES[name]}</svg>`;
+}
+

package/src/scene/init.ts

@@ -0,0 +1,86 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { linesToBeats, scriptTemplate, type ScriptFile } from "../generate/script.js";
+import { estimateTiming } from "./timing.js";
+import { writeSupply } from "./supply.js";
+
+export const STARTER_HTML = `<!doctype html>
+<!-- A vfrey scene: a HyperFrames composition. vfrey renders it at 1080x1920, 30 fps, for exactly as long as the
+     voice runs plus 0.3 s, and puts the AI-GENERATED label on top afterwards. Replace everything below. -->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <link rel="stylesheet" href="vfrey/fonts/fonts.css" />   <!-- Titan One, JetBrains Mono, Google Sans Flex -->
+    <script src="vfrey/gsap.min.js"></script>               <!-- local GSAP: scenes cannot load from a CDN -->
+    <script src="vfrey/vfrey.js"></script>                  <!-- vfrey.timing, vfrey.captions, vfrey.at, vfrey.onWord, vfrey.line -->
+    <style>
+      html, body { margin: 0; width: 1080px; height: 1920px; overflow: hidden; }
+      #root { position: relative; width: 1080px; height: 1920px; background: #ffffff; color: #111; font-family: "Titan One", sans-serif; }
+      #title { position: absolute; left: 60px; right: 60px; top: 220px; text-align: center; font-size: 92px; line-height: 1.05; }
+      #dot { position: absolute; left: 440px; top: 780px; width: 200px; height: 200px; border-radius: 50%; background: #2196f3; }
+      #captions { position: absolute; left: 50px; right: 50px; bottom: 220px; height: 250px; }  /* put captions anywhere */
+    </style>
+  </head>
+  <body>
+    <!-- No data-duration needed: vfrey sets it from the voice. -->
+    <div id="root" data-composition-id="main" data-start="0" data-width="1080" data-height="1920">
+      <div id="title"></div>
+      <div id="dot"></div>
+      <div id="captions"></div>
+    </div>
+    <script>
+      const tl = vfrey.timeline(); // one paused GSAP timeline; vfrey.at / vfrey.captions add to it
+      document.getElementById("title").textContent = vfrey.timing.title;
+      tl.from("#title", { y: 60, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.1);
+      // Cue an animation on the second line of the script, at the moment it is spoken.
+      vfrey.onLine(Math.min(1, vfrey.timing.lines.length - 1), (tl, t) => tl.to("#dot", { scale: 1.6, duration: 0.4, ease: "back.out(2)" }, t));
+      vfrey.captions("#captions", { style: "box" }); // style: box | color | underline | pop | plain
+    </script>
+  </body>
+</html>
+`;
+
+export const STARTER_TSX = `// A vfrey scene for Remotion. vfrey renders it at 1080x1920, 30 fps, for exactly as long as the voice runs plus
+// 0.3 s, plays the voice, and puts the AI-GENERATED label on top afterwards. Replace everything below.
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { AtLine, Captions, useTiming } from "@vfrey/scene"; // timing, captions and line cues from vfrey
+
+export default function Scene() {
+  const timing = useTiming(); // words, lines and beats with start and end times in seconds
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const pop = spring({ frame, fps, config: { damping: 12 } });
+  return (
+    <AbsoluteFill style={{ background: "#ffffff", color: "#111", fontFamily: '"Titan One", sans-serif' }}>
+      <div style={{ position: "absolute", left: 60, right: 60, top: 220, textAlign: "center", fontSize: 92, lineHeight: 1.05, opacity: interpolate(pop, [0, 1], [0, 1]) }}>
+        {timing.title}
+      </div>
+      {/* Shown while line 1 is spoken. */}
+      <AtLine i={Math.min(1, timing.lines.length - 1)}>
+        <div style={{ position: "absolute", left: 440, top: 780, width: 200, height: 200, borderRadius: "50%", background: "#2196f3" }} />
+      </AtLine>
+      {/* captionStyle: box | color | underline | pop | plain. Position the block anywhere. */}
+      <Captions captionStyle="box" style={{ position: "absolute", left: 50, right: 50, bottom: 220, height: 250 }} />
+    </AbsoluteFill>
+  );
+}
+`;
+
+function sampleScript(): ScriptFile {
+  return JSON.parse(scriptTemplate()) as ScriptFile;
+}
+
+/** Writes a starter scene into `dir`. The `vfrey/` folder is written too, so the HTML opens in a browser as it is. */
+export async function initScene(dir: string, kind: "html" | "tsx", env: Record<string, string | undefined> = process.env): Promise<string[]> {
+  const entry = path.join(dir, kind === "html" ? "index.html" : "index.tsx");
+  if (await stat(entry).then(() => true, () => false)) {
+    throw new Error(`${entry} already exists.`);
+  }
+  await mkdir(dir, { recursive: true });
+  await writeFile(entry, kind === "html" ? STARTER_HTML : STARTER_TSX);
+  const script = sampleScript();
+  const beats = linesToBeats(script.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption }));
+  await writeSupply({ dir, timing: estimateTiming({ title: script.title, lines: script.lines, beats }), voiceFile: null, kind, env });
+  return [entry, path.join(dir, "vfrey")];
+}

package/src/scene/inspect/css-tree.d.ts

@@ -0,0 +1,6 @@
+declare module "css-tree" {
+  export type CssNode = any;
+  export function parse(css: string, options?: Record<string, unknown>): CssNode;
+  export function generate(node: CssNode): string;
+  export function walk(node: CssNode, options: { visit?: string; enter?: (this: any, node: CssNode, item: any, list: any) => void }): void;
+}