playhead-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,4963 @@
+// src/spec/parse.ts
+import { readFile } from "fs/promises";
+import { dirname, resolve as resolvePath } from "path";
+import { parseDocument, LineCounter } from "yaml";
+
+// src/spec/schema.ts
+import { z } from "zod";
+
+// src/spec/locators.ts
+var LocatorParseError = class extends Error {
+};
+function parseLocator(input) {
+  const raw = input.trim();
+  let nth;
+  const parts = raw.split(">>").map((p) => p.trim());
+  const frames = [];
+  while (parts.length > 0 && parts[0].startsWith("frame=")) {
+    const sel = unquote(parts.shift().slice("frame=".length).trim());
+    if (!sel) throw new LocatorParseError(`Empty frame selector in "${raw}"`);
+    frames.push(sel);
+  }
+  if (parts.length === 0) {
+    throw new LocatorParseError(`Locator "${raw}" has frames but no element \u2014 add a base like role=... after the frame chain`);
+  }
+  const body = parts.shift();
+  if (parts.length > 0) {
+    const tail = parts.join(" >> ");
+    const m = /^nth=(\d+)$/.exec(tail);
+    if (!m) throw new LocatorParseError(`Unsupported locator suffix "${tail}" in "${raw}" (only "nth=N" is supported)`);
+    nth = Number(m[1]);
+  }
+  const withFrames = (p) => frames.length > 0 ? { ...p, frames } : p;
+  const eq = body.indexOf("=");
+  if (eq === -1) {
+    throw new LocatorParseError(
+      `Locator "${raw}" is missing an engine prefix \u2014 expected role=, label=, text=, placeholder=, testid= or css=`
+    );
+  }
+  const engine = body.slice(0, eq).trim();
+  const rest = body.slice(eq + 1).trim();
+  switch (engine) {
+    case "role": {
+      const m = /^([\w-]+)(?:\[name=(.+)\])?$/.exec(rest);
+      if (!m) throw new LocatorParseError(`Malformed role locator "${raw}" \u2014 expected role=button[name="..."]`);
+      const base = { kind: "role", role: m[1] };
+      if (m[2] !== void 0) base.name = parseTextMatch(m[2], raw);
+      return withFrames({ base, nth, raw });
+    }
+    case "label":
+      return withFrames({ base: { kind: "label", match: parseTextMatch(rest, raw) }, nth, raw });
+    case "text":
+      return withFrames({ base: { kind: "text", match: parseTextMatch(rest, raw) }, nth, raw });
+    case "placeholder":
+      return withFrames({ base: { kind: "placeholder", match: parseTextMatch(rest, raw) }, nth, raw });
+    case "testid": {
+      if (!rest) throw new LocatorParseError(`Empty testid in locator "${raw}"`);
+      return withFrames({ base: { kind: "testid", value: unquote(rest) }, nth, raw });
+    }
+    case "css": {
+      if (!rest) throw new LocatorParseError(`Empty css selector in locator "${raw}"`);
+      return withFrames({ base: { kind: "css", selector: rest }, nth, raw });
+    }
+    default:
+      throw new LocatorParseError(
+        `Unknown locator engine "${engine}" in "${raw}" \u2014 expected role, label, text, placeholder, testid or css`
+      );
+  }
+}
+function parseTextMatch(s, context) {
+  const v = s.trim();
+  if (v.startsWith("/")) {
+    const m = /^\/(.+)\/([a-z]*)$/.exec(v);
+    if (!m) throw new LocatorParseError(`Malformed regex "${v}" in locator "${context}"`);
+    try {
+      new RegExp(m[1], m[2]);
+    } catch {
+      throw new LocatorParseError(`Invalid regex "${v}" in locator "${context}"`);
+    }
+    return { regex: { source: m[1], flags: m[2] } };
+  }
+  if (v.startsWith('"') && v.endsWith('"') && v.length >= 2 || v.startsWith("'") && v.endsWith("'") && v.length >= 2) {
+    return { exact: v.slice(1, -1) };
+  }
+  if (!v) throw new LocatorParseError(`Empty text match in locator "${context}"`);
+  return { substring: v };
+}
+function unquote(s) {
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1);
+  return s;
+}
+function locatorDisplayName(loc) {
+  const b = loc.base;
+  switch (b.kind) {
+    case "role":
+      return b.name ? textMatchDisplay(b.name) : b.role;
+    case "label":
+    case "text":
+    case "placeholder":
+      return textMatchDisplay(b.match);
+    case "testid":
+      return b.value;
+    case "css":
+      return b.selector;
+  }
+}
+function textMatchDisplay(m) {
+  if ("exact" in m) return m.exact;
+  if ("substring" in m) return m.substring;
+  return m.regex.source;
+}
+
+// src/spec/schema.ts
+var dimensions = z.string().regex(/^\d+x\d+$/, "expected WIDTHxHEIGHT, e.g. 1280x800").transform((s) => {
+  const [w, h] = s.split("x").map(Number);
+  return { w, h };
+});
+var locatorString = z.string().min(1).superRefine((val, ctx2) => {
+  try {
+    parseLocator(val);
+  } catch (e) {
+    ctx2.addIssue({ code: "custom", message: e.message });
+  }
+});
+var focusHint = z.union([z.literal("target"), z.literal("wide"), locatorString]);
+var EXTRA_KEYS = ["caption", "narration", "focus", "mask", "shot", "timeout"];
+var stepExtras = {
+  caption: z.string().optional(),
+  /** The SPOKEN line for TTS narration — unconstrained by the caption card's size. Resolution:
+   *  spoken = narration ?? caption ?? auto; on-screen card = caption ?? auto. */
+  narration: z.string().optional(),
+  focus: focusHint.optional(),
+  /** Camera-shot boundary control: 'cut' forces this step into its own shot; 'continue' merges
+   *  it into the previous shot even when the heuristic would split. Decouples camera cuts from
+   *  scene structure (scenes stay narrative). */
+  shot: z.enum(["cut", "continue"]).optional(),
+  /** Per-step budget override (ms) for finding the target / meeting the expectation. */
+  timeout: z.number().int().positive().optional()
+};
+var targetOrShorthand = z.union([
+  locatorString,
+  z.object({ target: locatorString, ...stepExtras })
+]);
+var gotoStep = z.object({ action: z.literal("goto"), url: z.string(), ...stepExtras }).strict();
+var pointerStep = z.object({
+  action: z.enum(["click", "dblclick", "hover"]),
+  target: locatorString,
+  ...stepExtras
+}).strict();
+var typeStep = z.object({
+  action: z.literal("type"),
+  target: locatorString,
+  text: z.string(),
+  mask: z.boolean().default(false),
+  ...stepExtras
+}).strict();
+var pressStep = z.object({ action: z.literal("press"), keys: z.string(), ...stepExtras }).strict();
+var selectStep = z.object({
+  action: z.literal("select"),
+  target: locatorString,
+  value: z.string(),
+  ...stepExtras
+}).strict();
+var scrollStep = z.object({
+  action: z.literal("scroll"),
+  target: locatorString.optional(),
+  by: z.object({ x: z.number().default(0), y: z.number() }).strict().optional(),
+  ...stepExtras
+}).strict();
+var expectStep = z.object({
+  action: z.literal("expect"),
+  target: locatorString,
+  visible: z.boolean().optional(),
+  text: z.string().optional(),
+  /** Exact number of matching elements (e.g. rows in a filtered table). */
+  count: z.number().int().min(0).optional(),
+  ...stepExtras
+}).strict();
+var waitStep = z.object({
+  action: z.literal("wait"),
+  ms: z.number().int().positive().optional(),
+  for: locatorString.optional(),
+  state: z.enum(["visible", "hidden"]).default("visible"),
+  ...stepExtras
+}).strict().refine((s) => s.ms !== void 0 !== (s.for !== void 0), {
+  message: "wait needs exactly one of `ms` (blind sleep, discouraged) or `for` (an element to wait on)"
+});
+var stepSchema = z.discriminatedUnion("action", [
+  gotoStep,
+  pointerStep,
+  typeStep,
+  pressStep,
+  selectStep,
+  scrollStep,
+  expectStep,
+  waitStep
+]);
+var ACTION_KEYS = ["goto", "click", "dblclick", "hover", "type", "press", "select", "scroll", "expect", "wait"];
+var authoredStep = z.record(z.string(), z.unknown()).superRefine((obj, ctx2) => {
+  const actions = ACTION_KEYS.filter((k) => k in obj);
+  if (actions.length !== 1) {
+    const unknown = Object.keys(obj).filter((k) => !EXTRA_KEYS.includes(k));
+    const hints = unknown.map((k) => ({ k, near: nearestAction(k) })).filter((h) => h.near !== null).map((h) => ` \u2014 did you mean "${h.near}" instead of "${h.k}"?`).join("");
+    ctx2.addIssue({
+      code: "custom",
+      message: actions.length === 0 ? `Step has no action (found: ${unknown.join(", ") || "nothing"})${hints || ` \u2014 expected one of: ${ACTION_KEYS.join(", ")}`}` : `Step has multiple actions (${actions.join(", ")}) \u2014 exactly one is allowed`
+    });
+    return;
+  }
+  const known = /* @__PURE__ */ new Set([...ACTION_KEYS, ...EXTRA_KEYS]);
+  for (const key of Object.keys(obj)) {
+    if (!known.has(key)) {
+      ctx2.addIssue({ code: "custom", message: `Unknown step field "${key}"` });
+    }
+  }
+}).transform((obj) => normalizeStep(obj));
+function nearestAction(key) {
+  let best = null;
+  let bestD = 3;
+  for (const a of ACTION_KEYS) {
+    const d = editDistance(key.toLowerCase(), a);
+    if (d < bestD) {
+      bestD = d;
+      best = a;
+    }
+  }
+  return best;
+}
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+  }
+  return dp[a.length][b.length];
+}
+function normalizeStep(obj) {
+  const action = ACTION_KEYS.find((k) => k in obj);
+  const payload = obj[action];
+  const extras = {};
+  for (const k of EXTRA_KEYS) {
+    if (k in obj) extras[k] = obj[k];
+  }
+  if (typeof payload === "string") {
+    if (action === "goto") return { action, url: payload, ...extras };
+    if (action === "press") return { action, keys: payload, ...extras };
+    return { action, target: payload, ...extras };
+  }
+  if (typeof payload === "number" && action === "wait") {
+    return { action, ms: payload, ...extras };
+  }
+  if (payload !== null && typeof payload === "object") {
+    return { action, ...payload, ...extras };
+  }
+  return { action, value: payload, ...extras };
+}
+var specSchema = z.object({
+  playhead: z.literal(1),
+  title: z.string().min(1),
+  /** Title-card subtitle. Defaults to the app's host — set this for anything shareable. */
+  subtitle: z.string().optional(),
+  app: z.object({
+    url: z.string().url(),
+    /** Capture viewport. When omitted it is derived from output.aspect so portrait/square
+     *  outputs are captured at a matching viewport (the app reflows natively, no cropping). */
+    viewport: dimensions.optional(),
+    storageState: z.string().optional(),
+    /** Fail fast when auth is stale: this locator must match after the initial load, or the
+     *  capture aborts — instead of confidently filming the login page. */
+    assertLoggedIn: locatorString.optional(),
+    /** For before/after: a second app to capture the same flow against (the "before"). */
+    compareUrl: z.string().url().optional(),
+    /** Determinism controls: same spec → same pixels regardless of where/when it runs. */
+    environment: z.object({
+      timezone: z.string().optional(),
+      locale: z.string().optional(),
+      colorScheme: z.enum(["light", "dark"]).optional(),
+      /** Freeze Date at this ISO timestamp — "3 minutes ago" stops drifting between runs. */
+      fixedTime: z.string().optional(),
+      reducedMotion: z.boolean().optional()
+    }).strict().optional(),
+    /** Request interception: block third-party noise, stub responses, replay a HAR. */
+    network: z.object({
+      block: z.array(z.string()).optional(),
+      stub: z.array(
+        z.object({
+          url: z.string(),
+          status: z.number().int().optional(),
+          body: z.string().optional(),
+          contentType: z.string().optional()
+        }).strict()
+      ).optional(),
+      har: z.string().optional()
+    }).strict().optional(),
+    /** window.confirm()/alert() policy. Default accept — the silent auto-dismiss films the
+     *  cancel branch of confirm-guarded flows. */
+    dialogs: z.enum(["accept", "dismiss"]).optional(),
+    /** Settle tuning for slow backends / chatty apps. */
+    settle: z.object({
+      idleMs: z.number().int().positive().optional(),
+      capMs: z.number().int().positive().optional()
+    }).strict().optional()
+  }).strict(),
+  output: z.object({
+    kind: z.enum(["walkthrough", "demo", "bug-repro", "before-after", "release", "social"]).default("walkthrough"),
+    aspect: z.enum(["16:9", "9:16", "1:1"]).default("16:9"),
+    /** Output resolution; when omitted it is derived from the aspect. */
+    resolution: dimensions.optional(),
+    fps: z.number().int().min(24).max(60).default(30),
+    pacing: z.enum(["relaxed", "normal", "brisk"]).optional(),
+    /**
+     * Multiplier on per-step dwell (min-step duration, post-action holds, outro).
+     * 1 = the pacing preset as-is. Raise it for long-form teaching walkthroughs
+     * where each screen should linger so a viewer can read and absorb it.
+     */
+    dwellScale: z.number().min(0.5).max(4).optional(),
+    /**
+     * Audio. `narration: tts` speaks each step's caption (pacing grows so every line finishes
+     * before its step ends). `sfx` adds a soft synthesized click at each click beat. `music`
+     * lays a user-supplied bed under everything, ducked beneath narration. Any audio work
+     * finishes with loudness normalization (EBU R128, I=-16).
+     */
+    audio: z.object({
+      narration: z.enum(["none", "tts"]).default("none"),
+      provider: z.enum(["say"]).default("say"),
+      voice: z.string().optional(),
+      rate: z.number().int().min(80).max(400).optional(),
+      /** Click sound effects at click/select beats. Defaults on when this block is present. */
+      sfx: z.boolean().default(true),
+      /** Music bed from a local audio file (no asset is bundled — bring your own licensed track). */
+      music: z.object({
+        file: z.string(),
+        gainDb: z.number().min(-40).max(6).default(-19)
+      }).strict().optional()
+    }).strict().optional(),
+    /** Closing card. When set, the video ends on a title-card-styled end card. */
+    endCard: z.object({
+      title: z.string().min(1),
+      subtitle: z.string().optional()
+    }).strict().optional()
+  }).strict().prefault({}),
+  // No `name` field: exactly one theme exists today, and a knob that is accepted but ignored is
+  // a lie. It returns when a theme registry does.
+  theme: z.object({
+    accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, "expected a #rrggbb hex color").optional(),
+    captions: z.enum(["bottom", "top", "off"]).default("bottom")
+  }).strict().prefault({}),
+  masking: z.array(
+    z.object({
+      target: locatorString,
+      style: z.enum(["solid", "blur"]).default("solid")
+    }).strict()
+  ).default([]),
+  scenes: z.array(
+    z.object({
+      id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "scene ids are lowercase kebab-case"),
+      title: z.string().optional(),
+      steps: z.array(authoredStep.pipe(stepSchema)).min(1)
+    }).strict()
+  ).min(1)
+}).strict();
+var ASPECTS = {
+  "16:9": { viewport: { w: 1280, h: 720 }, resolution: { w: 1920, h: 1080 } },
+  "9:16": { viewport: { w: 720, h: 1280 }, resolution: { w: 1080, h: 1920 } },
+  "1:1": { viewport: { w: 900, h: 900 }, resolution: { w: 1080, h: 1080 } }
+};
+function resolveViewport(spec) {
+  return spec.app.viewport ?? ASPECTS[spec.output.aspect].viewport;
+}
+function resolveResolution(spec) {
+  return spec.output.resolution ?? ASPECTS[spec.output.aspect].resolution;
+}
+function flattenSteps(spec) {
+  const out = [];
+  let ordinal = 0;
+  spec.scenes.forEach((scene, sceneIndex) => {
+    scene.steps.forEach((step, stepIndex) => {
+      ordinal += 1;
+      out.push({ sceneId: scene.id, sceneIndex, stepIndex, ordinal, step });
+    });
+  });
+  return out;
+}
+
+// src/spec/parse.ts
+var SpecError = class extends Error {
+  constructor(message, issues = []) {
+    super(message);
+    this.issues = issues;
+  }
+  issues;
+};
+var KNOWN_KEYS = [
+  "playhead",
+  "title",
+  "subtitle",
+  "app",
+  "output",
+  "theme",
+  "masking",
+  "scenes",
+  "vars",
+  "extends",
+  "url",
+  "viewport",
+  "storageState",
+  "compareUrl",
+  "assertLoggedIn",
+  "environment",
+  "network",
+  "dialogs",
+  "settle",
+  "timezone",
+  "locale",
+  "colorScheme",
+  "fixedTime",
+  "reducedMotion",
+  "block",
+  "stub",
+  "har",
+  "status",
+  "body",
+  "contentType",
+  "idleMs",
+  "capMs",
+  "kind",
+  "aspect",
+  "resolution",
+  "fps",
+  "pacing",
+  "dwellScale",
+  "audio",
+  "endCard",
+  "narration",
+  "provider",
+  "voice",
+  "rate",
+  "sfx",
+  "music",
+  "file",
+  "gainDb",
+  "accent",
+  "captions",
+  "target",
+  "style",
+  "id",
+  "steps",
+  "shot",
+  "timeout",
+  "goto",
+  "click",
+  "dblclick",
+  "hover",
+  "type",
+  "press",
+  "select",
+  "scroll",
+  "expect",
+  "wait",
+  "caption",
+  "focus",
+  "mask",
+  "text",
+  "value",
+  "keys",
+  "ms",
+  "by",
+  "visible",
+  "hidden",
+  "count",
+  "for",
+  "state",
+  "x",
+  "y"
+];
+function suggest(key) {
+  let best = null;
+  let bestD = 3;
+  for (const k of KNOWN_KEYS) {
+    const d = editDistance(key.toLowerCase(), k.toLowerCase());
+    if (d > 0 && d < bestD) {
+      bestD = d;
+      best = k;
+    }
+  }
+  return best;
+}
+function parseSpec(yamlText, sourcePath = "<inline>") {
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(yamlText, { lineCounter, keepSourceTokens: true });
+  if (doc.errors.length > 0) {
+    const first = doc.errors[0];
+    throw new SpecError(`${sourcePath}: not valid YAML \u2014 ${first.message}`);
+  }
+  const raw = doc.toJS();
+  if (raw && typeof raw === "object" && "extends" in raw) {
+    throw new SpecError(`${sourcePath}: "extends" needs a file on disk \u2014 load the spec with loadSpec/the CLI, not inline text`);
+  }
+  return validateResolved(interpolate(raw, sourcePath), sourcePath, doc, lineCounter);
+}
+async function loadSpec(path) {
+  const merged = await loadRaw(resolvePath(path), 0);
+  const text = await readFile(resolvePath(path), "utf8");
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter });
+  return validateResolved(interpolate(merged, path), path, doc, lineCounter);
+}
+async function loadRaw(path, depth) {
+  if (depth > 4) throw new SpecError(`${path}: extends chain deeper than 4 \u2014 check for a cycle`);
+  const text = await readFile(path, "utf8");
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) throw new SpecError(`${path}: not valid YAML \u2014 ${doc.errors[0].message}`);
+  const raw = doc.toJS() ?? {};
+  const base = raw.extends;
+  delete raw.extends;
+  if (base === void 0) return raw;
+  if (typeof base !== "string") throw new SpecError(`${path}: "extends" must be a path string`);
+  const baseObj = await loadRaw(resolvePath(dirname(path), base), depth + 1);
+  return mergeSpecs(baseObj, raw);
+}
+function mergeSpecs(base, child) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(child)) {
+    const b = out[k];
+    if (Array.isArray(b) && Array.isArray(v) && (k === "masking" || k === "scenes")) {
+      out[k] = [...b, ...v];
+    } else if (isPlainObject(b) && isPlainObject(v)) {
+      out[k] = mergeSpecs(b, v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function interpolate(raw, sourcePath) {
+  if (!isPlainObject(raw)) return raw;
+  const varsIn = isPlainObject(raw.vars) ? raw.vars : {};
+  const vars = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(varsIn)) {
+    vars.set(name, resolveEnv(String(value), sourcePath));
+  }
+  const doc = { ...raw };
+  delete doc.vars;
+  const seen = (s) => {
+    const withEnv = resolveEnv(s, sourcePath);
+    return withEnv.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_, name) => {
+      const v = vars.get(name);
+      if (v === void 0) {
+        const near = suggest(name) ?? [...vars.keys()].find((k) => editDistance(k, name) <= 2);
+        throw new SpecError(
+          `${sourcePath}: unknown variable {{${name}}}${near ? ` \u2014 did you mean {{${near}}}?` : ""} (declared vars: ${[...vars.keys()].join(", ") || "none"})`
+        );
+      }
+      return v;
+    });
+  };
+  const walk = (v) => {
+    if (typeof v === "string") return seen(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, walk(val)]));
+    return v;
+  };
+  return walk(doc);
+}
+function resolveEnv(s, sourcePath) {
+  return s.replace(/\$\{env\.([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, dflt) => {
+    const v = process.env[name];
+    if (v !== void 0) return v;
+    if (dflt !== void 0) return dflt;
+    throw new SpecError(`${sourcePath}: environment variable ${name} is not set and has no default (use \${env.${name}:-fallback})`);
+  });
+}
+function validateResolved(resolved, sourcePath, doc, lineCounter) {
+  const result = specSchema.safeParse(resolved);
+  if (!result.success) {
+    const issues = result.error.issues.map((iss) => formatIssue(iss, sourcePath, doc, lineCounter));
+    throw new SpecError(`${sourcePath}: invalid spec
+  - ${issues.join("\n  - ")}`, issues);
+  }
+  return result.data;
+}
+function formatIssue(iss, sourcePath, doc, lineCounter) {
+  const where = iss.path.length ? humanPath(iss.path) : "spec";
+  const pos = positionOf(iss.path, doc, lineCounter);
+  const at = pos ? `${sourcePath}:${pos.line}:${pos.col} ` : "";
+  if (iss.code === "unrecognized_keys") {
+    const keys = iss.keys;
+    const hints = keys.map((k) => ({ k, near: suggest(k) })).map((h) => h.near ? `"${h.k}" (did you mean "${h.near}"?)` : `"${h.k}"`).join(", ");
+    return `${at}${where}: unknown key${keys.length > 1 ? "s" : ""} ${hints}`;
+  }
+  return `${at}${where}: ${iss.message}`;
+}
+function positionOf(path, doc, lineCounter) {
+  for (let depth = path.length; depth > 0; depth--) {
+    try {
+      const node = doc.getIn(path.slice(0, depth), true);
+      if (node?.range) {
+        const pos = lineCounter.linePos(node.range[0]);
+        return { line: pos.line, col: pos.col };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function humanPath(path) {
+  return path.map((seg, i) => typeof seg === "number" ? `[${seg}]` : i === 0 ? String(seg) : `.${String(seg)}`).join("");
+}
+
+// src/capture/executor.ts
+import { join as join2 } from "path";
+
+// src/capture/playwright-driver.ts
+import { chromium } from "playwright";
+
+// src/shared/easing.ts
+var EASE_ZOOM = [0.4, 0, 0.2, 1];
+var EASE_PAN = [0.3, 0, 0.15, 1];
+function cubicBezier(p, t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  const [x1, y1, x2, y2] = p;
+  let u = t;
+  for (let i = 0; i < 8; i++) {
+    const x = bez(u, x1, x2) - t;
+    if (Math.abs(x) < 1e-6) break;
+    const dx = dbez(u, x1, x2);
+    if (Math.abs(dx) < 1e-6) break;
+    u -= x / dx;
+  }
+  return bez(Math.max(0, Math.min(1, u)), y1, y2);
+}
+function bez(u, a, b) {
+  const v = 1 - u;
+  return 3 * v * v * u * a + 3 * v * u * u * b + u * u * u;
+}
+function dbez(u, a, b) {
+  const v = 1 - u;
+  return 3 * v * v * a + 6 * v * u * (b - a) + 3 * u * u * (1 - b);
+}
+function minJerk(t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  return t * t * t * (10 - 15 * t + 6 * t * t);
+}
+
+// src/shared/log.ts
+import pc from "picocolors";
+var verbose = false;
+var log = {
+  info(msg) {
+    console.error(pc.dim("[playhead]") + " " + msg);
+  },
+  step(msg) {
+    console.error(pc.cyan("  \u25B8 ") + msg);
+  },
+  ok(msg) {
+    console.error(pc.green("  \u2713 ") + msg);
+  },
+  warn(msg) {
+    console.error(pc.yellow("  \u26A0 ") + msg);
+  },
+  error(msg) {
+    console.error(pc.red("  \u2717 ") + msg);
+  },
+  debug(msg) {
+    if (verbose) console.error(pc.dim("  \xB7 " + msg));
+  }
+};
+
+// src/capture/playwright-driver.ts
+var INPUT_TIMEOUT_MS = 5e3;
+var MASK_INIT_SCRIPT = `
+(() => {
+  if (window.__playheadMaskInstalled) return;
+  window.__playheadMaskInstalled = true;
+  // Each masked element gets its own overlay box parented into that element's own DOM subtree.
+  // This is what makes masking survive the top layer: an element inside a <dialog> modal (or a
+  // popover) paints above a document-level overlay, so the box must be a descendant of the same
+  // top-layer subtree to cover it. A position:fixed box stays out of flow, so parenting it into a
+  // flex/grid container does not disturb layout.
+  const boxes = new Map();
+  const base = (box) => {
+    box.setAttribute('aria-hidden', 'true');
+    box.style.position = 'fixed';
+    box.style.pointerEvents = 'none';
+    box.style.zIndex = '2147483647';
+    box.style.borderRadius = '5px';
+    box.style.margin = '0';
+  };
+  const sync = (box, el, style) => {
+    const r = el.getBoundingClientRect();
+    const pad = 3; // cover focus rings / borders just outside the element box
+    box.style.left = (r.left - pad) + 'px';
+    box.style.top = (r.top - pad) + 'px';
+    box.style.width = (r.width + pad * 2) + 'px';
+    box.style.height = (r.height + pad * 2) + 'px';
+    box.style.display = r.width > 0 && r.height > 0 ? 'block' : 'none';
+    if (style === 'blur') {
+      box.style.backdropFilter = 'blur(18px)';
+      box.style.webkitBackdropFilter = 'blur(18px)';
+      box.style.background = 'rgba(120,124,140,0.45)';
+    } else {
+      box.style.backdropFilter = '';
+      box.style.background = '#2a2f3a';
+    }
+  };
+  // In-page rule matching: CSS-expressible mask rules (testid=, css=) are pushed into
+  // window.__playheadMaskCssRules and re-scanned continuously, so an element that APPEARS
+  // MID-STEP (a token in a modal, an email in a toast, a row from the fetch settle waits on)
+  // is tagged the frame it appears \u2014 not seconds later at the next step boundary. Node-side
+  // tagging remains the backstop for rules needing Playwright semantics (role/label/text).
+  let scanTick = 0;
+  const scanRules = () => {
+    const rules = window.__playheadMaskCssRules || [];
+    for (const r of rules) {
+      try {
+        for (const el of document.querySelectorAll(r.css)) {
+          if (!el.hasAttribute('data-playhead-mask')) el.setAttribute('data-playhead-mask', r.style);
+        }
+      } catch (e) {}
+    }
+  };
+  const tick = () => {
+    try {
+      if (scanTick++ % 3 === 0) scanRules(); // every ~3 frames \u2014 cheap, and a 1-frame leak beats a 1-step leak
+      const tagged = new Set(document.querySelectorAll('[data-playhead-mask]'));
+      for (const [el, box] of boxes) {
+        if (!tagged.has(el) || !el.isConnected) { box.remove(); boxes.delete(el); }
+      }
+      for (const el of tagged) {
+        const parent = el.parentElement || document.body;
+        let box = boxes.get(el);
+        if (!box) {
+          box = document.createElement('div');
+          base(box);
+          parent.appendChild(box);
+          boxes.set(el, box);
+        } else if (box.parentElement !== parent) {
+          parent.appendChild(box);
+        }
+        sync(box, el, el.getAttribute('data-playhead-mask'));
+      }
+    } catch (e) {}
+    requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+})();
+`;
+var FALLBACK_NAME_FN = `(el) => {
+  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  const label = el.getAttribute('aria-label');
+  if (label) return norm(label);
+  const labelledBy = el.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    const parts = labelledBy.split(/\\s+/).map((id) => {
+      const ref = document.getElementById(id);
+      return ref ? ref.textContent : '';
+    });
+    const joined = norm(parts.join(' '));
+    if (joined) return joined;
+  }
+  if (el.labels && el.labels.length) return norm(el.labels[0].textContent);
+  if (el.alt) return norm(el.alt);
+  const text = norm(el.textContent);
+  if (text) return text.slice(0, 80);
+  if (el.placeholder) return norm(el.placeholder);
+  if (el.title) return norm(el.title);
+  return null;
+}`;
+var COLLECT_INTERACTABLES_FN = `() => {
+  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  // Accessible text = visible text excluding aria-hidden / hidden subtrees, matching how the
+  // ARIA name is computed (so a decorative icon inside a link doesn't leak into the name).
+  const accText = (el) => {
+    let t = '';
+    const walk = (node) => {
+      if (node.nodeType === 3) { t += node.textContent; return; }
+      if (node.nodeType !== 1) return;
+      if (node.getAttribute && (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden'))) return;
+      for (const c of node.childNodes) walk(c);
+    };
+    walk(el);
+    return norm(t);
+  };
+  const IMPLICIT = { A: 'link', BUTTON: 'button', SELECT: 'combobox', TEXTAREA: 'textbox', SUMMARY: 'button' };
+  const inputRole = (el) => {
+    const t = (el.getAttribute('type') || 'text').toLowerCase();
+    if (t === 'checkbox') return 'checkbox';
+    if (t === 'radio') return 'radio';
+    if (t === 'range') return 'slider';
+    if (t === 'button' || t === 'submit' || t === 'reset') return 'button';
+    if (t === 'search') return 'searchbox';
+    return 'textbox';
+  };
+  const accName = (el) => {
+    const al = el.getAttribute('aria-label'); if (al) return norm(al);
+    const lb = el.getAttribute('aria-labelledby');
+    if (lb) { const parts = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? r.textContent : ''; }); const j = norm(parts.join(' ')); if (j) return j; }
+    if (el.labels && el.labels.length) return accText(el.labels[0]);
+    if (el.alt) return norm(el.alt);
+    // NEVER walk a <select>'s subtree: that concatenates every <option> into a monster
+    // "Choose option...grayrednavy\u2026" pseudo-name that no human would write as a locator.
+    if (el.tagName === 'SELECT' || el.tagName === 'DATALIST') {
+      const sel = el.selectedOptions && el.selectedOptions[0];
+      return sel ? norm(sel.textContent) : null;
+    }
+    const txt = accText(el); if (txt) return txt.slice(0, 80);
+    if (el.placeholder) return norm(el.placeholder);
+    if (el.title) return norm(el.title);
+    return null;
+  };
+  // Landmark region for catalog grouping: which part of the page the element lives in.
+  const regionOf = (el) => {
+    const lm = el.closest('[role=dialog], dialog, nav, [role=navigation], header, [role=banner], aside, [role=complementary], footer, [role=contentinfo], main, [role=main]');
+    if (!lm) return 'page';
+    const tag = lm.tagName.toLowerCase();
+    const role = lm.getAttribute && lm.getAttribute('role');
+    if (tag === 'dialog' || role === 'dialog') return 'dialog';
+    if (tag === 'nav' || role === 'navigation') return 'nav';
+    if (tag === 'header' || role === 'banner') return 'header';
+    if (tag === 'aside' || role === 'complementary') return 'sidebar';
+    if (tag === 'footer' || role === 'contentinfo') return 'footer';
+    return 'main';
+  };
+  const sel = 'button, a[href], input, select, textarea, summary, [role=button], [role=link], [role=tab], [role=switch], [role=menuitem], [role=checkbox], [contenteditable=""], [contenteditable=true], h1, h2, h3';
+  const seen = new Set();
+  const out = [];
+  for (const el of document.querySelectorAll(sel)) {
+    if (seen.has(el)) continue; seen.add(el);
+    const r = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    const visible = r.width > 1 && r.height > 1 && style.visibility !== 'hidden' && style.display !== 'none' &&
+      r.bottom > 0 && r.top < innerHeight && r.right > 0 && r.left < innerWidth;
+    const tag = el.tagName;
+    const explicit = el.getAttribute('role');
+    const role = explicit || IMPLICIT[tag] || (tag === 'INPUT' ? inputRole(el) : (tag[0] === 'H' && tag.length === 2 ? 'heading' : null));
+    let label = null;
+    if (el.labels && el.labels.length) label = norm(el.labels[0].textContent);
+    const options = tag === 'SELECT' ? Array.from(el.options).map((o) => norm(o.textContent)) : undefined;
+    out.push({
+      tag, role,
+      accessibleName: accName(el),
+      label,
+      placeholder: el.getAttribute && el.getAttribute('placeholder') ? norm(el.getAttribute('placeholder')) : null,
+      testId: el.getAttribute && (el.getAttribute('data-testid') || el.getAttribute('data-test-id')) || null,
+      text: accText(el).slice(0, 80) || null,
+      bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+      visible,
+      inputType: tag === 'INPUT' ? (el.getAttribute('type') || 'text').toLowerCase() : (tag === 'SELECT' ? 'select' : null),
+      region: regionOf(el),
+      ...(options ? { options } : {}),
+    });
+  }
+  return out;
+}`;
+var PlaywrightDriver = class _PlaywrightDriver {
+  browser;
+  context;
+  page;
+  cdp;
+  /** Dedicated CDP session for the capture loop so its screenshots never contend with the
+   *  executor's accessibility/geometry lookups on the main session (which could deadlock). */
+  captureCdp;
+  cursor = { x: 0, y: 0 };
+  navCallbacks = [];
+  captureActive = false;
+  captureLoop = null;
+  captureOnFrame = null;
+  captureOpts = null;
+  inflightGrab = null;
+  lastFrameNodeMs = 0;
+  clockOffset = 0;
+  tagCounter = 0;
+  typingMaskLoc = null;
+  async launch(opts) {
+    const env = opts.environment;
+    this.browser = await chromium.launch({ headless: opts.headless ?? true });
+    this.context = await this.browser.newContext({
+      viewport: { width: opts.viewport.w, height: opts.viewport.h },
+      deviceScaleFactor: opts.dpr,
+      colorScheme: env?.colorScheme ?? "light",
+      ...env?.timezone ? { timezoneId: env.timezone } : {},
+      ...env?.locale ? { locale: env.locale } : {},
+      ...env?.reducedMotion ? { reducedMotion: "reduce" } : {},
+      ...opts.storageStatePath ? { storageState: opts.storageStatePath } : {}
+    });
+    this.context.setDefaultTimeout(1e4);
+    this.context.setDefaultNavigationTimeout(2e4);
+    const net = opts.network;
+    if (net?.har) await this.context.routeFromHAR(net.har, { notFound: "fallback" });
+    for (const glob of net?.block ?? []) {
+      await this.context.route(glob, (route) => route.fulfill({ status: 204, body: "" }));
+    }
+    for (const stub of net?.stub ?? []) {
+      await this.context.route(
+        stub.url,
+        (route) => route.fulfill({
+          status: stub.status ?? 200,
+          body: stub.body ?? "",
+          contentType: stub.contentType ?? "application/json"
+        })
+      );
+    }
+    this.page = await this.context.newPage();
+    if (env?.fixedTime) await this.page.clock.setFixedTime(new Date(env.fixedTime));
+    await this.page.addInitScript(MASK_INIT_SCRIPT);
+    this.cdp = await this.context.newCDPSession(this.page);
+    this.captureCdp = await this.context.newCDPSession(this.page);
+    this.page.on("framenavigated", (frame) => {
+      if (frame === this.page.mainFrame()) {
+        const t = Date.now();
+        for (const cb of this.navCallbacks) cb(frame.url(), t);
+      }
+    });
+    this.page.on("console", (msg) => this.pushConsole(msg.type(), msg.text()));
+    this.page.on("pageerror", (err) => this.pushConsole("pageerror", err.message));
+    this.page.on("crash", () => this.pushConsole("crash", "page crashed"));
+    const dialogPolicy = opts.dialogs ?? "accept";
+    this.page.on("dialog", (dialog) => {
+      this.pushConsole("dialog", `${dialog.type()}("${dialog.message()}") \u2192 ${dialogPolicy}`);
+      void (dialogPolicy === "accept" ? dialog.accept() : dialog.dismiss()).catch(() => {
+      });
+    });
+    this.context.on("page", (p) => {
+      if (p !== this.page) {
+        this.pushConsole("popup", `new tab/popup opened: ${p.url()} (not filmed \u2014 capture follows the main page)`);
+        log.warn(`popup opened (${p.url()}) \u2014 multi-tab capture is not yet supported; footage stays on the main page`);
+      }
+    });
+    this.cursor = { x: opts.viewport.w / 2, y: opts.viewport.h * 0.6 };
+    await this.page.mouse.move(this.cursor.x, this.cursor.y);
+  }
+  consoleBuf = [];
+  pushConsole(type, text) {
+    this.consoleBuf.push({ t: Date.now(), type, text: text.slice(0, 500) });
+    if (this.consoleBuf.length > 500) this.consoleBuf.shift();
+  }
+  consoleLog() {
+    return [...this.consoleBuf];
+  }
+  async close() {
+    if (!this.browser) return;
+    await withTimeout(this.browser.close(), 8e3).catch(() => {
+    });
+  }
+  async measureClockOffset() {
+    const samples = [];
+    for (let i = 0; i < 5; i++) {
+      const t0 = Date.now();
+      const browserNow = await withTimeout(this.page.evaluate(() => Date.now()), 2e3).catch(() => t0);
+      const t1 = Date.now();
+      samples.push(browserNow - (t0 + t1) / 2);
+    }
+    samples.sort((a, b) => a - b);
+    this.clockOffset = samples[2];
+    return this.clockOffset;
+  }
+  async goto(url) {
+    await this.page.goto(url, { waitUntil: "load" });
+    await withTimeout(
+      this.page.evaluate(
+        () => Promise.race([document.fonts?.ready, new Promise((r) => setTimeout(r, 2e3))])
+      ),
+      3e3
+    ).catch(() => {
+    });
+  }
+  onNavigation(cb) {
+    this.navCallbacks.push(cb);
+  }
+  currentUrl() {
+    return this.page.url();
+  }
+  async currentTitle() {
+    return this.page.title().catch(() => "");
+  }
+  async ariaSnapshot() {
+    return this.page.locator("body").ariaSnapshot().catch(() => "");
+  }
+  async countMatches(loc) {
+    try {
+      return await this.toLocator(loc).count();
+    } catch {
+      return 0;
+    }
+  }
+  async collectInteractables() {
+    const collect = new Function(`return (${COLLECT_INTERACTABLES_FN})()`);
+    const out = await withTimeout(this.page.evaluate(collect), 1e4).catch(() => []);
+    const handles = await this.page.$$("iframe").catch(() => []);
+    for (const h of handles) {
+      try {
+        const sel = await h.evaluate((el) => {
+          if (el.id) return `#${CSS.escape(el.id)}`;
+          const name = el.getAttribute("name");
+          if (name) return `iframe[name="${name}"]`;
+          const tid = el.getAttribute("data-testid");
+          if (tid) return `iframe[data-testid="${tid}"]`;
+          return null;
+        });
+        if (!sel) continue;
+        const frame = await h.contentFrame();
+        if (!frame) continue;
+        const rect = await h.boundingBox();
+        const inner = await withTimeout(
+          frame.evaluate(collect),
+          8e3
+        ).catch(() => []);
+        for (const e of inner) {
+          out.push({
+            ...e,
+            framePrefix: `frame=${sel}`,
+            bbox: rect ? { x: e.bbox.x + rect.x, y: e.bbox.y + rect.y, w: e.bbox.w, h: e.bbox.h } : e.bbox
+          });
+        }
+      } catch {
+      }
+    }
+    return out;
+  }
+  // ---------- locating & measuring ----------
+  toLocator(loc) {
+    let scope = this.page;
+    for (const sel of loc.frames ?? []) scope = scope.frameLocator(sel);
+    const b = loc.base;
+    let l;
+    switch (b.kind) {
+      case "role":
+        l = scope.getByRole(b.role, b.name ? { name: toPw(b.name), exact: isExact(b.name) } : {});
+        break;
+      case "label":
+        l = scope.getByLabel(toPw(b.match), { exact: isExact(b.match) });
+        break;
+      case "text":
+        l = scope.getByText(toPw(b.match), { exact: isExact(b.match) });
+        break;
+      case "placeholder":
+        l = scope.getByPlaceholder(toPw(b.match), { exact: isExact(b.match) });
+        break;
+      case "testid":
+        l = scope.getByTestId(b.value);
+        break;
+      case "css":
+        l = scope.locator(b.selector);
+        break;
+    }
+    if (loc.nth !== void 0) l = l.nth(loc.nth);
+    return l;
+  }
+  async resolveTarget(loc, timeoutMs) {
+    const locator = this.toLocator(loc);
+    try {
+      await locator.waitFor({ state: "visible", timeout: timeoutMs });
+    } catch (e) {
+      const msg = e.message ?? "";
+      if (/strict mode violation/i.test(msg)) {
+        const count2 = await locator.count().catch(() => -1);
+        throw new Error(
+          `Locator is ambiguous: ${loc.raw} matches ${count2 >= 0 ? count2 : "multiple"} elements \u2014 add '>> nth=N' to pick one`
+        );
+      }
+      const count = await this.countMatches(loc);
+      const reason = count === 0 ? "no matching element on the page" : `${count} match(es) present but none became visible`;
+      throw new Error(
+        `Target not resolvable: ${loc.raw} \u2014 ${reason} within ${timeoutMs}ms on ${this.page.url()} (${firstLine(msg)})`
+      );
+    }
+    await locator.scrollIntoViewIfNeeded().catch(() => {
+    });
+    const deadline = Date.now() + timeoutMs;
+    let prev = null;
+    while (Date.now() < deadline) {
+      const box = await locator.boundingBox();
+      const sig = box ? `${box.x},${box.y},${box.width},${box.height}` : null;
+      if (sig && sig === prev) break;
+      prev = sig;
+      await this.nextFrame();
+    }
+    const info = await this.measure(locator, loc);
+    if (!info) throw new Error(`Target disappeared while measuring: ${loc.raw}`);
+    return info;
+  }
+  /** Wait for the page to paint one frame, bounded — a concurrent screenshot must never let this hang. */
+  async nextFrame() {
+    await withTimeout(
+      this.page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)))),
+      1500
+    ).catch(() => {
+    });
+  }
+  async tryMeasure(loc) {
+    const locator = this.toLocator(loc);
+    try {
+      if (!await locator.isVisible()) return null;
+      return await this.measure(locator, loc);
+    } catch {
+      return null;
+    }
+  }
+  async measure(locator, loc) {
+    const tag = `ph-${++this.tagCounter}`;
+    const geom = await locator.evaluate((el, t) => {
+      el.setAttribute("data-playhead-t", t);
+      const r = el.getBoundingClientRect();
+      return {
+        bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+        scroll: { x: window.scrollX, y: window.scrollY }
+      };
+    }, tag).catch(() => null);
+    if (!geom) return null;
+    if (loc.frames && loc.frames.length > 0) {
+      const box = await withTimeout(locator.boundingBox(), 3e3).catch(() => null);
+      if (box) geom.bbox = { x: box.x, y: box.y, w: box.width, h: box.height };
+    }
+    let role = null;
+    let name = null;
+    try {
+      const evalRes = await withTimeout(
+        this.cdp.send("Runtime.evaluate", {
+          expression: `document.querySelector('[data-playhead-t="${tag}"]')`
+        }),
+        4e3
+      );
+      if (evalRes.result.objectId) {
+        const desc = await withTimeout(
+          this.cdp.send("DOM.describeNode", { objectId: evalRes.result.objectId }),
+          4e3
+        );
+        const ax = await withTimeout(
+          this.cdp.send("Accessibility.getPartialAXTree", {
+            backendNodeId: desc.node.backendNodeId,
+            fetchRelatives: false
+          }),
+          4e3
+        );
+        const node = ax.nodes?.[0];
+        if (node && !node.ignored) {
+          role = node.role?.value ?? null;
+          name = node.name?.value ?? null;
+        }
+        await this.cdp.send("Runtime.releaseObject", { objectId: evalRes.result.objectId }).catch(() => {
+        });
+      }
+    } catch (e) {
+      log.debug(`AX lookup failed for ${loc.raw}: ${e.message}`);
+    }
+    if (!name) {
+      name = await locator.evaluate(new Function("el", `return (${FALLBACK_NAME_FN})(el)`)).catch(() => null);
+    }
+    await locator.evaluate((el) => el.removeAttribute("data-playhead-t")).catch(() => {
+    });
+    return { role, accessibleName: name, bbox: geom.bbox, scroll: geom.scroll };
+  }
+  // ---------- input ----------
+  cursorPos() {
+    return { ...this.cursor };
+  }
+  async moveCursor(to, durationMs) {
+    const from = { ...this.cursor };
+    const waypoints = [{ x: from.x, y: from.y, t: Date.now() }];
+    const stepMs = 12;
+    const steps = Math.max(2, Math.round(durationMs / stepMs));
+    for (let i = 1; i <= steps; i++) {
+      const p = minJerk(i / steps);
+      const x = from.x + (to.x - from.x) * p;
+      const y = from.y + (to.y - from.y) * p;
+      await withTimeout(this.page.mouse.move(x, y), INPUT_TIMEOUT_MS);
+      waypoints.push({ x, y, t: Date.now() });
+      if (i < steps) await sleep(stepMs);
+    }
+    this.cursor = { ...to };
+    return waypoints;
+  }
+  async clickAt(p, opts) {
+    await withTimeout(this.page.mouse.move(p.x, p.y), INPUT_TIMEOUT_MS);
+    this.cursor = { ...p };
+    const tDown = Date.now();
+    await withTimeout(this.page.mouse.down(), INPUT_TIMEOUT_MS);
+    await sleep(70);
+    await withTimeout(this.page.mouse.up(), INPUT_TIMEOUT_MS);
+    if (opts?.double) {
+      await sleep(60);
+      await withTimeout(this.page.mouse.down({ clickCount: 2 }), INPUT_TIMEOUT_MS);
+      await sleep(60);
+      await withTimeout(this.page.mouse.up({ clickCount: 2 }), INPUT_TIMEOUT_MS);
+    }
+    return { tDown, tUp: Date.now() };
+  }
+  async typeText(text, delayMs) {
+    const tFirst = Date.now();
+    await withTimeout(this.page.keyboard.type(text, { delay: delayMs }), 1e4 + text.length * delayMs * 2);
+    return { tFirst, tLast: Date.now() };
+  }
+  async press(keys) {
+    const tDown = Date.now();
+    await withTimeout(this.page.keyboard.press(keys), INPUT_TIMEOUT_MS);
+    return { tDown };
+  }
+  /**
+   * The REAL click: Playwright's locator.click with actionability + hit-target verification and
+   * retry. The cosmetic cursor has already animated to the target; this dispatches the action
+   * through the checks a raw coordinate click bypasses (a toast/sticky header drifting under
+   * the point between measure and click silently redirects a coordinate click).
+   */
+  async actClick(loc, opts) {
+    const locator = this.toLocator(loc);
+    const tDown = Date.now();
+    if (opts?.double) await locator.dblclick({ delay: 60, timeout: opts?.timeoutMs ?? 1e4 });
+    else await locator.click({ delay: 70, timeout: opts?.timeoutMs ?? 1e4 });
+    return { tDown, tUp: Date.now() };
+  }
+  async selectOption(loc, value) {
+    const locator = this.toLocator(loc);
+    try {
+      await locator.selectOption({ label: value });
+    } catch {
+      await locator.selectOption(value);
+    }
+    await withTimeout(this.page.keyboard.press("Escape"), INPUT_TIMEOUT_MS).catch(() => {
+    });
+    await withTimeout(
+      locator.evaluate((el) => el.blur?.()),
+      2e3
+    ).catch(() => {
+    });
+  }
+  async scrollIntoView(loc) {
+    const locator = this.toLocator(loc);
+    await withTimeout(
+      locator.evaluate((el) => el.scrollIntoView({ behavior: "smooth", block: "center" })),
+      5e3
+    );
+  }
+  async scrollBy(by) {
+    await withTimeout(
+      this.page.evaluate(({ x, y }) => window.scrollBy({ left: x, top: y, behavior: "smooth" }), by),
+      5e3
+    );
+  }
+  async waitForScrollSettle(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let prev = Number.NaN;
+    let stable = 0;
+    while (Date.now() < deadline) {
+      const y = await withTimeout(this.page.evaluate(() => window.scrollY), 1500).catch(() => prev);
+      if (y === prev) {
+        if (++stable >= 2) return;
+      } else {
+        stable = 0;
+        prev = y;
+      }
+      await sleep(60);
+    }
+  }
+  async expectState(loc, opts, timeoutMs) {
+    const locator = this.toLocator(loc);
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "condition not met";
+    while (Date.now() < deadline) {
+      try {
+        if (opts.count !== void 0) {
+          const n = await locator.count();
+          if (n === opts.count) return;
+          lastErr = `expected ${opts.count} match(es), found ${n}`;
+          await sleep(100);
+          continue;
+        }
+        const visible = await locator.first().isVisible();
+        if (opts.visible !== void 0 && visible !== opts.visible) {
+          lastErr = `expected visible=${opts.visible}, got ${visible}`;
+        } else if (opts.text !== void 0) {
+          const content = visible ? await locator.first().innerText() : "";
+          if (!content.includes(opts.text)) {
+            lastErr = `expected text to include "${opts.text}"`;
+          } else {
+            return;
+          }
+        } else {
+          return;
+        }
+      } catch (e) {
+        lastErr = e.message;
+      }
+      await sleep(100);
+    }
+    throw new Error(`expect failed for ${loc.raw}: ${lastErr}`);
+  }
+  // ---------- settling ----------
+  /** Open requests → their start time. Long-lived streams (HMR sockets, SSE, long-polls) stop
+   *  counting after LONG_REQUEST_MS so a dev server can't pin the settle at its cap forever. */
+  pending = /* @__PURE__ */ new Map();
+  lastNetActivity = 0;
+  netTrackingInstalled = false;
+  installNetTracking() {
+    if (this.netTrackingInstalled) return;
+    this.netTrackingInstalled = true;
+    this.lastNetActivity = Date.now();
+    const IGNORED_TYPES = /* @__PURE__ */ new Set(["eventsource", "websocket", "ping"]);
+    this.page.on("request", (req) => {
+      if (IGNORED_TYPES.has(req.resourceType())) return;
+      this.pending.set(req, Date.now());
+      this.lastNetActivity = Date.now();
+    });
+    const done = (req) => {
+      if (this.pending.delete(req)) this.lastNetActivity = Date.now();
+    };
+    this.page.on("requestfinished", done);
+    this.page.on("requestfailed", done);
+  }
+  static LONG_REQUEST_MS = 2e3;
+  async settle(opts) {
+    this.installNetTracking();
+    const start = Date.now();
+    let capped = true;
+    while (Date.now() - start < opts.capMs) {
+      const now = Date.now();
+      let inflight = 0;
+      for (const t of this.pending.values()) {
+        if (now - t < _PlaywrightDriver.LONG_REQUEST_MS) inflight += 1;
+      }
+      if (inflight === 0 && now - this.lastNetActivity >= opts.idleMs) {
+        capped = false;
+        break;
+      }
+      await sleep(30);
+    }
+    if (capped) log.debug(`settle hit its ${opts.capMs}ms cap \u2014 footage may include in-flight loading`);
+    await withTimeout(
+      this.page.evaluate(
+        () => new Promise((resolve) => {
+          const done = () => {
+            obs.disconnect();
+            resolve();
+          };
+          let timer;
+          const arm = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+              const running = (document.getAnimations?.() ?? []).filter((a) => {
+                const t = a.effect?.getTiming?.();
+                return a.playState === "running" && t && t.iterations !== Infinity;
+              });
+              if (running.length === 0) done();
+              else arm();
+            }, 250);
+          };
+          const obs = new MutationObserver(() => arm());
+          obs.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+          arm();
+          setTimeout(done, 1500);
+        })
+      ),
+      1800
+    ).catch(() => {
+    });
+    await this.nextFrame();
+  }
+  async saveStorageState(path) {
+    await this.context.storageState({ path });
+  }
+  // ---------- masking ----------
+  /**
+   * Install CSS-expressible mask rules for continuous in-page tagging (see MASK_INIT_SCRIPT).
+   * Rules that can't be expressed as CSS (role/label/text) return false and stay Node-tagged.
+   */
+  async installMaskRules(rules) {
+    const cssRules = rules.map((r) => ({ css: maskRuleToCss(r.loc), style: r.style })).filter((r) => r.css !== null);
+    if (cssRules.length === 0) return;
+    const payload = JSON.stringify(cssRules);
+    await this.page.addInitScript(`window.__playheadMaskCssRules = ${payload};`);
+    await withTimeout(
+      this.page.evaluate((json) => window.__playheadMaskCssRules = JSON.parse(json), payload),
+      3e3
+    ).catch(() => {
+    });
+  }
+  async applyMasks(rules) {
+    const tagged = [];
+    for (const rule of rules) {
+      const locator = this.toLocator(rule.loc);
+      const all = await locator.all().catch(() => []);
+      for (const el of all) {
+        const box = await el.evaluate((node, style) => {
+          node.setAttribute("data-playhead-mask", style);
+          const r = node.getBoundingClientRect();
+          return { x: r.x, y: r.y, w: r.width, h: r.height };
+        }, rule.style).catch(() => null);
+        if (box && box.w > 0 && box.h > 0) tagged.push({ style: rule.style, ...box });
+      }
+    }
+    return tagged;
+  }
+  async setTypingMask(loc) {
+    if (loc) {
+      this.typingMaskLoc = loc;
+      const locator = this.toLocator(loc);
+      await locator.evaluate((el) => el.setAttribute("data-playhead-mask", "solid")).catch(() => {
+      });
+    } else if (this.typingMaskLoc) {
+      const locator = this.toLocator(this.typingMaskLoc);
+      await locator.evaluate((el) => el.removeAttribute("data-playhead-mask")).catch(() => {
+      });
+      this.typingMaskLoc = null;
+    }
+  }
+  // ---------- frame capture ----------
+  //
+  // Headless Chromium's CDP screencast is hard-locked to CSS-pixel resolution and ignores
+  // deviceScaleFactor, so a paced Page.captureScreenshot loop with clip.scale is what actually
+  // yields 2x frames (the zoom headroom the camera planner needs).
+  async startCapture(onFrame, opts) {
+    this.captureOnFrame = onFrame;
+    this.captureOpts = opts;
+    this.captureActive = true;
+    const intervalMs = 1e3 / opts.fps;
+    this.captureLoop = (async () => {
+      while (this.captureActive) {
+        const started = Date.now();
+        await this.grabFrame();
+        const elapsed = Date.now() - started;
+        if (elapsed < intervalMs) await sleep(intervalMs - elapsed);
+      }
+    })();
+  }
+  /** Grab a frame, coalescing on any in-flight grab (so callers can await the current one). */
+  grabFrame() {
+    if (this.inflightGrab) return this.inflightGrab;
+    this.inflightGrab = this.doGrab().finally(() => {
+      this.inflightGrab = null;
+    });
+    return this.inflightGrab;
+  }
+  grabFailures = 0;
+  async doGrab() {
+    if (!this.captureOpts || !this.captureOnFrame) return;
+    try {
+      const opts = this.captureOpts;
+      const vp = this.page.viewportSize() ?? { width: 1280, height: 720 };
+      const scroll = await this.readScroll();
+      const shot = await withTimeout(
+        this.captureCdp.send("Page.captureScreenshot", {
+          format: opts.format,
+          quality: opts.quality,
+          clip: { x: scroll.x, y: scroll.y, width: vp.width, height: vp.height, scale: opts.scale },
+          captureBeyondViewport: false
+        }),
+        1500
+      );
+      const tNodeMs = Date.now();
+      this.lastFrameNodeMs = tNodeMs;
+      this.grabFailures = 0;
+      this.captureOnFrame({ data: Buffer.from(shot.data, "base64"), tNodeMs });
+    } catch {
+      this.grabFailures += 1;
+      if (this.grabFailures >= 2) {
+        try {
+          await this.captureCdp.detach().catch(() => {
+          });
+          this.captureCdp = await this.context.newCDPSession(this.page);
+          log.warn("capture: recreated CDP session after stalled screenshots");
+          this.grabFailures = 0;
+        } catch {
+        }
+      }
+    }
+  }
+  async readScroll() {
+    try {
+      const m = await withTimeout(this.captureCdp.send("Page.getLayoutMetrics"), 1500);
+      const vv = m.cssVisualViewport ?? m.visualViewport;
+      return { x: Math.round(vv?.pageX ?? 0), y: Math.round(vv?.pageY ?? 0) };
+    } catch {
+      return { x: 0, y: 0 };
+    }
+  }
+  async stopCapture() {
+    this.captureActive = false;
+    await this.captureLoop?.catch(() => {
+    });
+    this.captureLoop = null;
+  }
+  lastFrameAt() {
+    return this.lastFrameNodeMs;
+  }
+  async captureNow() {
+    if (this.inflightGrab) await this.inflightGrab.catch(() => {
+    });
+    await this.grabFrame();
+  }
+};
+function toPw(m) {
+  if ("exact" in m) return m.exact;
+  if ("substring" in m) return m.substring;
+  return new RegExp(m.regex.source, m.regex.flags);
+}
+function isExact(m) {
+  return "exact" in m;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function maskRuleToCss(loc) {
+  const b = loc.base;
+  if (b.kind === "css") return b.selector;
+  if (b.kind === "testid") return `[data-testid=${JSON.stringify(b.value)}]`;
+  return null;
+}
+function firstLine(s) {
+  const line = s.split("\n")[0] ?? "";
+  return line.length > 160 ? `${line.slice(0, 159)}\u2026` : line;
+}
+function withTimeout(p, ms) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`operation timed out after ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+
+// src/bundle/writer.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import sharp from "sharp";
+
+// src/bundle/hash.ts
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+function sha256Json(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function sha256File(path) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(path).on("data", (d) => hash.update(d)).on("end", () => resolve(hash.digest("hex"))).on("error", reject);
+  });
+}
+
+// src/shared/version.ts
+import { createRequire } from "module";
+var PLAYHEAD_VERSION = createRequire(import.meta.url)("../../package.json").version;
+
+// src/bundle/writer.ts
+var BundleWriter = class {
+  constructor(dir, captureFormat) {
+    this.dir = dir;
+    this.captureFormat = captureFormat;
+    this.ready = mkdir(join(dir, "frames"), { recursive: true }).then(() => {
+    });
+  }
+  dir;
+  captureFormat;
+  frames = [];
+  pendingWrites = [];
+  maskSamples = [];
+  counter = 0;
+  ready;
+  /** Queue a frame write. `t` is capture-relative ms. */
+  addFrame(data, t) {
+    this.counter += 1;
+    const name = `${String(this.counter).padStart(6, "0")}.${this.captureFormat === "jpeg" ? "jpg" : "png"}`;
+    this.frames.push({ f: name, t: round1(t) });
+    this.pendingWrites.push(
+      this.ready.then(() => writeFile(join(this.dir, "frames", name), data))
+    );
+  }
+  addMaskSample(sample) {
+    this.maskSamples.push(sample);
+  }
+  frameCount() {
+    return this.counter;
+  }
+  async finish(meta) {
+    await this.ready;
+    await Promise.all(this.pendingWrites);
+    this.frames.sort((a, b) => a.t - b.t);
+    let frameW = meta.viewport.w * meta.dpr;
+    let frameH = meta.viewport.h * meta.dpr;
+    const first = this.frames[0];
+    if (first) {
+      const info = await sharp(join(this.dir, "frames", first.f)).metadata();
+      if (info.width && info.height) {
+        frameW = info.width;
+        frameH = info.height;
+      }
+    }
+    const manifest = {
+      schema: "playhead/bundle@1",
+      playheadVersion: PLAYHEAD_VERSION,
+      specHash: sha256Json(meta.spec),
+      appUrl: meta.appUrl,
+      viewport: meta.viewport,
+      dpr: meta.dpr,
+      frameW,
+      frameH,
+      clockOffsetMs: meta.clockOffsetMs,
+      frameCount: this.frames.length,
+      durationMs: round1(meta.durationMs),
+      createdAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+      captureFormat: this.captureFormat,
+      hashes: {
+        events: sha256Json(meta.events),
+        framesIndex: sha256Json(this.frames)
+      },
+      ...meta.partial ? { partial: true } : {},
+      ...meta.failure ? { failure: meta.failure } : {}
+    };
+    await Promise.all([
+      writeFile(join(this.dir, "frames", "index.json"), JSON.stringify(this.frames)),
+      writeFile(join(this.dir, "events.json"), JSON.stringify(meta.events, null, 2)),
+      writeFile(join(this.dir, "masks.json"), JSON.stringify(this.maskSamples, null, 2)),
+      writeFile(join(this.dir, "spec.resolved.json"), JSON.stringify(meta.spec, null, 2)),
+      writeFile(join(this.dir, "manifest.json"), JSON.stringify(manifest, null, 2))
+    ]);
+    return manifest;
+  }
+};
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+// src/shared/geometry.ts
+function rectCenter(r) {
+  return { x: r.x + r.w / 2, y: r.y + r.h / 2 };
+}
+function rectUnion(a, b) {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    w: Math.max(a.x + a.w, b.x + b.w) - x,
+    h: Math.max(a.y + a.h, b.y + b.h) - y
+  };
+}
+function padRect(r, pad) {
+  return { x: r.x - pad, y: r.y - pad, w: r.w + pad * 2, h: r.h + pad * 2 };
+}
+function rectContains(outer, inner, margin = 0) {
+  return inner.x >= outer.x + margin && inner.y >= outer.y + margin && inner.x + inner.w <= outer.x + outer.w - margin && inner.y + inner.h <= outer.y + outer.h - margin;
+}
+function clamp(v, min, max) {
+  return v < min ? min : v > max ? max : v;
+}
+function dist(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function visibleRect(cam, plane2) {
+  const w = plane2.vpW / cam.zoom;
+  const h = w * plane2.outH / plane2.outW;
+  return { x: cam.cx - w / 2, y: cam.cy - h / 2, w, h };
+}
+function minZoom(plane2) {
+  return Math.max(1, plane2.vpW / (plane2.vpH * plane2.outW / plane2.outH));
+}
+function clampCamera(cam, plane2) {
+  const zoom = Math.max(cam.zoom, minZoom(plane2));
+  const w = plane2.vpW / zoom;
+  const h = w * plane2.outH / plane2.outW;
+  return {
+    zoom,
+    cx: clamp(cam.cx, w / 2, plane2.vpW - w / 2),
+    cy: clamp(cam.cy, h / 2, plane2.vpH - h / 2)
+  };
+}
+function projectRect(r, cam, plane2) {
+  const vis = visibleRect(cam, plane2);
+  const s = plane2.outW / vis.w;
+  return { x: (r.x - vis.x) * s, y: (r.y - vis.y) * s, w: r.w * s, h: r.h * s };
+}
+function projectPoint(p, cam, plane2) {
+  const vis = visibleRect(cam, plane2);
+  const s = plane2.outW / vis.w;
+  return { x: (p.x - vis.x) * s, y: (p.y - vis.y) * s };
+}
+
+// src/shared/exit.ts
+var EXIT = {
+  OK: 0,
+  FLOW: 1,
+  QUALITY: 2,
+  INFRA: 3,
+  USAGE: 4
+};
+var FlowError = class extends Error {
+  exitCode = EXIT.FLOW;
+};
+
+// src/capture/executor.ts
+var SETTLE = { idleMs: 300, capMs: 5e3 };
+var TARGET_TIMEOUT_MS = 1e4;
+var EXPECT_TIMEOUT_MS = 1e4;
+var TYPE_DELAY_MS = 45;
+var STEP_BUDGET_MS = 45e3;
+var CAPTURE_DEADLINE_MS = 10 * 6e4;
+async function capture(spec, opts) {
+  const bundleDir = join2(opts.outDir, "capture");
+  const driver = opts.driver ?? new PlaywrightDriver();
+  const dpr = 2;
+  const format = opts.captureFormat ?? "jpeg";
+  const writer = new BundleWriter(bundleDir, format);
+  const events = [];
+  const maskRules = spec.masking.map((m) => ({
+    loc: parseLocator(m.target),
+    style: m.style
+  }));
+  const viewport = resolveViewport(spec);
+  const settleCfg = {
+    idleMs: spec.app.settle?.idleMs ?? SETTLE.idleMs,
+    capMs: spec.app.settle?.capMs ?? SETTLE.capMs
+  };
+  log.info(`capturing "${spec.title}" from ${spec.app.url}`);
+  await driver.launch({
+    viewport,
+    dpr,
+    headless: opts.headless ?? true,
+    ...spec.app.storageState ? { storageStatePath: spec.app.storageState } : {},
+    ...spec.app.environment ? { environment: spec.app.environment } : {},
+    ...spec.app.network ? { network: spec.app.network } : {},
+    ...spec.app.dialogs ? { dialogs: spec.app.dialogs } : {}
+  });
+  let t0 = Date.now();
+  const rel = (nodeMs) => nodeMs - t0;
+  const now = () => rel(Date.now());
+  let clockOffsetMs = 0;
+  let failure;
+  let currentStepRef = "";
+  try {
+    clockOffsetMs = await driver.measureClockOffset();
+    t0 = Date.now();
+    driver.onNavigation((url, tNode) => {
+      events.push({ type: "navigation", url, t: rel(tNode) });
+    });
+    const startFilming = () => driver.startCapture((frame) => writer.addFrame(frame.data, rel(frame.tNodeMs)), {
+      format,
+      quality: opts.quality ?? 82,
+      scale: dpr,
+      // 24 requested ≈ 20-22 achieved with the screenshot loop's ~25ms capture cost; frame
+      // blending at compose smooths the rest. (True 30+ needs the screencast source — planned.)
+      fps: 24
+    });
+    if (!opts.fromScene) await startFilming();
+    await driver.installMaskRules(maskRules);
+    await driver.goto(spec.app.url);
+    await applyMasksAndSample(driver, maskRules, writer, now);
+    await driver.settle(settleCfg);
+    if (spec.app.assertLoggedIn) {
+      await driver.expectState(parseLocator(spec.app.assertLoggedIn), { visible: true }, 8e3).catch(() => {
+        throw new Error(
+          `assertLoggedIn failed: ${spec.app.assertLoggedIn} not visible \u2014 storageState stale? Re-run: playhead login ${spec.app.url}`
+        );
+      });
+    }
+    if (!opts.fromScene) await driver.captureNow();
+    let steps = flattenSteps(spec);
+    const totalSteps = steps.length;
+    if (opts.fromScene) {
+      const idx = steps.findIndex((s) => s.sceneId === opts.fromScene);
+      if (idx < 0) throw new Error(`--from-scene: no scene with id "${opts.fromScene}" in the spec`);
+      log.info(`fast-forwarding ${idx} step(s) to scene "${opts.fromScene}" (state only, not filmed)`);
+      for (const pre of steps.slice(0, idx)) {
+        currentStepRef = `${pre.sceneId}/${pre.stepIndex} (fast-forward)`;
+        await fastForwardStep(driver, pre.step);
+      }
+      currentStepRef = "";
+      steps = steps.slice(idx);
+      await driver.settle(settleCfg);
+      await startFilming();
+      await driver.captureNow();
+    }
+    for (const addressed of steps) {
+      currentStepRef = `${addressed.sceneId}/${addressed.stepIndex}`;
+      if (now() > CAPTURE_DEADLINE_MS) {
+        throw new Error(`capture watchdog: exceeded ${CAPTURE_DEADLINE_MS / 6e4} minutes at step ${currentStepRef}`);
+      }
+      log.step(`${addressed.ordinal}/${totalSteps} ${describeStep(addressed)}`);
+      const event = await withStepBudget(
+        executeStep(driver, addressed, { rel, now }, spec.app.url),
+        STEP_BUDGET_MS,
+        currentStepRef
+      );
+      await applyMasksAndSample(driver, maskRules, writer, now);
+      await driver.settle(settleCfg);
+      const focus = "focus" in addressed.step ? addressed.step.focus : void 0;
+      if (focus && focus !== "target" && focus !== "wide") {
+        const loc = parseLocator(focus);
+        for (let i = 0; i < 10 && !event.focusTarget; i++) {
+          event.focusTarget = await driver.tryMeasure(loc);
+          if (!event.focusTarget) await sleep2(250);
+        }
+        if (!event.focusTarget) {
+          log.warn(`${addressed.sceneId}/${addressed.stepIndex}: focus locator never appeared: ${focus}`);
+        }
+      }
+      await ensurePostActionFrame(driver, event.tAction, rel);
+      event.tSettled = now();
+      if (event.targetPre && event.locator) {
+        event.targetPost = await driver.tryMeasure(parseLocator(event.locator));
+      }
+      if (addressed.step.action === "type" && addressed.step.mask && event.locator) {
+        const info = await driver.tryMeasure(parseLocator(event.locator));
+        if (info) writer.addMaskSample({ t: now(), rects: [{ style: "solid", ...info.bbox }] });
+      }
+      events.push(event);
+    }
+    currentStepRef = "";
+    await driver.settle(settleCfg);
+    await driver.captureNow();
+    await sleep2(400);
+    return { bundleDir };
+  } catch (e) {
+    const message = e.message;
+    failure = { stepRef: currentStepRef || "(setup)", message };
+    try {
+      const aria = await driver.ariaSnapshot();
+      const url = driver.currentUrl();
+      const { writeFile: writeFile6 } = await import("fs/promises");
+      await writeFile6(
+        join2(bundleDir, "failure.json"),
+        JSON.stringify({ stepRef: failure.stepRef, message, url, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+      );
+      if (aria) await writeFile6(join2(bundleDir, "failure-aria.txt"), aria);
+    } catch {
+    }
+    throw new FlowError(
+      `${message}
+  (partial bundle with ${writer.frameCount()} frames saved to ${bundleDir} \u2014 failure.json has the details)`
+    );
+  } finally {
+    await driver.stopCapture().catch(() => {
+    });
+    try {
+      const consoleLog = driver.consoleLog();
+      if (consoleLog.length > 0) {
+        const { writeFile: writeFile6 } = await import("fs/promises");
+        await writeFile6(
+          join2(bundleDir, "console.json"),
+          JSON.stringify(consoleLog.map((c) => ({ ...c, t: rel(c.t) })), null, 2)
+        );
+      }
+    } catch {
+    }
+    const durationMs = now();
+    const eventLog = {
+      schema: "playhead/events@1",
+      meta: {
+        viewport,
+        dpr,
+        frameW: 0,
+        // finalized by writer from the first frame's real dimensions
+        frameH: 0,
+        clockOffsetMs,
+        startedAtIso: new Date(t0).toISOString(),
+        durationMs,
+        appUrl: spec.app.url
+      },
+      events
+    };
+    try {
+      const manifest = await writer.finish({
+        spec,
+        events: eventLog,
+        appUrl: spec.app.url,
+        viewport,
+        dpr,
+        clockOffsetMs,
+        durationMs,
+        ...failure ? { partial: true, failure } : {}
+      });
+      if (!failure) {
+        log.ok(`bundle: ${manifest.frameCount} frames, ${(durationMs / 1e3).toFixed(1)}s \u2192 ${bundleDir}`);
+      } else {
+        log.warn(`partial bundle: ${manifest.frameCount} frames up to ${failure.stepRef} \u2192 ${bundleDir}`);
+      }
+    } catch (finishErr) {
+      log.warn(`could not finalize bundle: ${finishErr.message}`);
+    }
+    await driver.close();
+  }
+}
+async function fastForwardStep(driver, step) {
+  const T = step.timeout ?? 8e3;
+  switch (step.action) {
+    case "goto":
+      await driver.goto(step.url);
+      break;
+    case "click":
+    case "dblclick": {
+      const t = await driver.resolveTarget(parseLocator(step.target), T);
+      await driver.clickAt(rectCenter(t.bbox), { double: step.action === "dblclick" });
+      break;
+    }
+    case "hover":
+      break;
+    // no lasting state
+    case "type": {
+      const t = await driver.resolveTarget(parseLocator(step.target), T);
+      await driver.clickAt(rectCenter(t.bbox));
+      await driver.typeText(step.text, 0);
+      break;
+    }
+    case "press":
+      await driver.press(step.keys);
+      break;
+    case "select":
+      await driver.selectOption(parseLocator(step.target), step.value);
+      break;
+    case "scroll":
+      if (step.target) await driver.scrollIntoView(parseLocator(step.target));
+      else if (step.by) await driver.scrollBy(step.by);
+      await driver.waitForScrollSettle(1500);
+      break;
+    case "expect":
+      await driver.expectState(parseLocator(step.target), { ...step.visible !== void 0 ? { visible: step.visible } : {} }, T).catch(() => {
+      });
+      break;
+    case "wait":
+      if (step.for) {
+        await driver.expectState(parseLocator(step.for), { visible: step.state !== "hidden" }, T).catch(() => {
+        });
+      }
+      break;
+  }
+  await driver.settle({ idleMs: 200, capMs: 2500 });
+}
+function withStepBudget(p, ms, stepRef) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`step ${stepRef} exceeded its ${ms / 1e3}s budget`)),
+      ms
+    );
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+async function executeStep(driver, addressed, clock, appUrl) {
+  const { step, sceneId, stepIndex, ordinal } = addressed;
+  const base = {
+    type: "action",
+    kind: step.action,
+    sceneId,
+    stepIndex,
+    ordinal,
+    cursorPath: [],
+    tStart: clock.now(),
+    tAction: 0,
+    tActionEnd: 0,
+    tSettled: 0,
+    ...step.caption ? { caption: step.caption } : {},
+    ...step.narration ? { narration: step.narration } : {},
+    ...step.shot ? { shot: step.shot } : {},
+    ..."focus" in step && step.focus ? { focus: step.focus } : {}
+  };
+  const budgetMs = step.timeout ?? TARGET_TIMEOUT_MS;
+  switch (step.action) {
+    case "goto": {
+      const url = new URL(step.url, appUrl).href;
+      base.locator = url;
+      base.tAction = clock.now();
+      await driver.goto(url);
+      base.tActionEnd = clock.now();
+      return base;
+    }
+    case "click":
+    case "dblclick":
+    case "hover": {
+      base.locator = step.target;
+      const loc = parseLocator(step.target);
+      const pre = await driver.resolveTarget(loc, budgetMs);
+      base.targetPre = pre;
+      base.cursorPath = await moveToTarget(driver, pre, clock);
+      if (step.action === "hover") {
+        base.tAction = clock.now();
+        base.tActionEnd = base.tAction;
+      } else {
+        const { tDown, tUp } = await driver.actClick(loc, {
+          double: step.action === "dblclick",
+          timeoutMs: budgetMs
+        });
+        base.tAction = clock.rel(tDown);
+        base.tActionEnd = clock.rel(tUp);
+      }
+      return base;
+    }
+    case "type": {
+      base.locator = step.target;
+      const loc = parseLocator(step.target);
+      const pre = await driver.resolveTarget(loc, budgetMs);
+      base.targetPre = pre;
+      base.cursorPath = await moveToTarget(driver, pre, clock);
+      await driver.actClick(loc, { timeoutMs: budgetMs });
+      if (step.mask) {
+        await driver.setTypingMask(loc);
+      }
+      const { tFirst, tLast } = await driver.typeText(step.text, TYPE_DELAY_MS);
+      base.tAction = clock.rel(tFirst);
+      base.tActionEnd = clock.rel(tLast);
+      base.masked = step.mask;
+      base.typedText = step.mask ? "\u2022".repeat(Math.min(step.text.length, 8)) : step.text;
+      return base;
+    }
+    case "press": {
+      base.locator = step.keys;
+      const { tDown } = await driver.press(step.keys);
+      base.tAction = clock.rel(tDown);
+      base.tActionEnd = clock.now();
+      return base;
+    }
+    case "select": {
+      base.locator = step.target;
+      const loc = parseLocator(step.target);
+      const pre = await driver.resolveTarget(loc, budgetMs);
+      base.targetPre = pre;
+      base.cursorPath = await moveToTarget(driver, pre, clock);
+      base.tAction = clock.now();
+      await driver.selectOption(loc, step.value);
+      base.typedText = step.value;
+      base.tActionEnd = clock.now();
+      return base;
+    }
+    case "scroll": {
+      base.tAction = clock.now();
+      if (step.target) {
+        base.locator = step.target;
+        const loc = parseLocator(step.target);
+        await driver.scrollIntoView(loc);
+        await driver.waitForScrollSettle(2500);
+        base.targetPre = await driver.tryMeasure(loc);
+      } else if (step.by) {
+        await driver.scrollBy(step.by);
+        await driver.waitForScrollSettle(2500);
+      }
+      base.tActionEnd = clock.now();
+      return base;
+    }
+    case "expect": {
+      base.locator = step.target;
+      const loc = parseLocator(step.target);
+      await driver.expectState(
+        loc,
+        { ...step.visible !== void 0 ? { visible: step.visible } : {}, ...step.text !== void 0 ? { text: step.text } : {}, ...step.count !== void 0 ? { count: step.count } : {} },
+        step.timeout ?? EXPECT_TIMEOUT_MS
+      );
+      base.targetPre = await driver.tryMeasure(loc);
+      base.tAction = clock.now();
+      base.tActionEnd = base.tAction;
+      return base;
+    }
+    case "wait": {
+      base.tAction = clock.now();
+      if (step.for) {
+        base.locator = step.for;
+        await driver.expectState(
+          parseLocator(step.for),
+          { visible: step.state !== "hidden" },
+          step.timeout ?? EXPECT_TIMEOUT_MS
+        );
+      } else {
+        await sleep2(step.ms ?? 0);
+      }
+      base.tActionEnd = clock.now();
+      return base;
+    }
+  }
+}
+async function moveToTarget(driver, target, clock) {
+  const to = rectCenter(target.bbox);
+  const travel = clamp(250 + dist(driver.cursorPos(), to) * 0.5, 300, 700);
+  const waypoints = await driver.moveCursor(to, travel);
+  return waypoints.map((w) => ({ x: round12(w.x), y: round12(w.y), t: round12(clock.rel(w.t)) }));
+}
+async function ensurePostActionFrame(driver, tAction, rel) {
+  await sleep2(24);
+  await driver.captureNow();
+  if (rel(driver.lastFrameAt()) <= tAction) {
+    for (let i = 0; i < 2 && rel(driver.lastFrameAt()) <= tAction; i++) {
+      await sleep2(40);
+      await driver.captureNow();
+    }
+    if (rel(driver.lastFrameAt()) <= tAction) {
+      log.warn(`no captured frame after action at t=${tAction.toFixed(0)}ms \u2014 footage may hold a stale frame`);
+    }
+  }
+}
+async function applyMasksAndSample(driver, rules, writer, now) {
+  if (rules.length === 0) return;
+  const rects = await driver.applyMasks(rules);
+  if (rects.length > 0) writer.addMaskSample({ t: now(), rects });
+}
+function describeStep(a) {
+  const s = a.step;
+  switch (s.action) {
+    case "goto":
+      return `goto ${s.url}`;
+    case "type":
+      return `type into ${s.target}${s.mask ? " (masked)" : ""}`;
+    case "press":
+      return `press ${s.keys}`;
+    case "wait":
+      return `wait ${s.ms}ms`;
+    case "scroll":
+      return `scroll ${s.target ?? JSON.stringify(s.by)}`;
+    default:
+      return `${s.action} ${"target" in s ? s.target : ""}`;
+  }
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function round12(n) {
+  return Math.round(n * 10) / 10;
+}
+
+// src/bundle/reader.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join3 } from "path";
+async function openBundle(dir) {
+  const [manifestRaw, eventsRaw, framesRaw, masksRaw] = await Promise.all([
+    readFile2(join3(dir, "manifest.json"), "utf8"),
+    readFile2(join3(dir, "events.json"), "utf8"),
+    readFile2(join3(dir, "frames", "index.json"), "utf8"),
+    readFile2(join3(dir, "masks.json"), "utf8").catch(() => "[]")
+  ]);
+  const manifest = JSON.parse(manifestRaw);
+  if (manifest.schema !== "playhead/bundle@1") {
+    throw new Error(`Unsupported bundle schema "${manifest.schema}" in ${dir}`);
+  }
+  const events = JSON.parse(eventsRaw);
+  const frames = JSON.parse(framesRaw);
+  const maskSamples = JSON.parse(masksRaw);
+  if (frames.length === 0) throw new Error(`Bundle ${dir} contains no frames`);
+  return { dir, manifest, events, frames, maskSamples };
+}
+function frameIndexForTime(frames, tMs) {
+  let lo = 0;
+  let hi = frames.length - 1;
+  if (tMs <= frames[0].t) return 0;
+  if (tMs >= frames[hi].t) return hi;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >> 1;
+    if (frames[mid].t <= tMs) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+function framePath(bundle, index) {
+  return join3(bundle.dir, "frames", bundle.frames[index].f);
+}
+
+// src/compose/index.ts
+import { join as join7 } from "path";
+import { writeFile as writeFile3 } from "fs/promises";
+
+// src/theme/index.ts
+import { existsSync } from "fs";
+import { join as join4, dirname as dirname2 } from "path";
+import { createRequire as createRequire2 } from "module";
+import { GlobalFonts } from "@napi-rs/canvas";
+var DEFAULT_THEME = {
+  name: "default",
+  accent: "#5B8DEF",
+  bg: "#12161f",
+  bgSubtle: "#1a2029",
+  surface: "rgba(18, 22, 31, 0.92)",
+  onSurface: "#ffffff",
+  onSurfaceDim: "rgba(255,255,255,0.72)",
+  fontFamily: "Inter",
+  // Broadcast-subtitle scale: ~3.3% of a 1080p frame. At the old 26px the caption was the same
+  // size as the app's upscaled body copy and read as part of the UI, not narration above it.
+  captionFontPx: 36,
+  captionMinFontPx: 28,
+  captionMaxLines: 2,
+  captionPosition: "bottom",
+  radius: 12
+};
+function resolveTheme(spec) {
+  return {
+    ...DEFAULT_THEME,
+    ...spec.theme.accent ? { accent: spec.theme.accent } : {},
+    captionPosition: spec.theme.captions
+  };
+}
+var fontsRegistered = false;
+function registerFonts() {
+  if (fontsRegistered) return;
+  fontsRegistered = true;
+  const require5 = createRequire2(import.meta.url);
+  let pkgDir;
+  try {
+    pkgDir = dirname2(require5.resolve("@expo-google-fonts/inter/package.json"));
+  } catch {
+    throw new Error("Font package @expo-google-fonts/inter not found \u2014 run npm install");
+  }
+  const faces = [
+    ["400Regular/Inter_400Regular.ttf", "Inter"],
+    ["500Medium/Inter_500Medium.ttf", "Inter Medium"],
+    ["600SemiBold/Inter_600SemiBold.ttf", "Inter SemiBold"],
+    ["700Bold/Inter_700Bold.ttf", "Inter Bold"]
+  ];
+  for (const [rel, family] of faces) {
+    const p = join4(pkgDir, rel);
+    if (existsSync(p)) GlobalFonts.registerFromPath(p, family);
+  }
+}
+
+// src/compose/types.ts
+function stageContent(profile) {
+  return profile.stage?.content ?? { x: 0, y: 0, w: profile.width, h: profile.height };
+}
+function withStage(profile, chrome) {
+  const { width, height } = profile;
+  const marginY = Math.round(height * 0.055);
+  const chromeH = chrome ? Math.round(44 * (Math.min(width, height) / 1080)) : 0;
+  const contentH = height - 2 * marginY - chromeH;
+  const contentW = Math.round(contentH * (width / height));
+  const x = Math.round((width - contentW) / 2);
+  const y = marginY + chromeH;
+  return {
+    ...profile,
+    stage: { content: { x, y, w: contentW, h: contentH }, chromeH, radius: Math.round(14 * (Math.min(width, height) / 1080)) }
+  };
+}
+var PROFILE_16x9 = {
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  safeArea: { top: 54, right: 96, bottom: 160, left: 96 },
+  zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
+  minFocusPx: 110,
+  captionMaxWidth: 1040
+};
+var PROFILE_9x16 = {
+  width: 1080,
+  height: 1920,
+  fps: 30,
+  safeArea: { top: 230, right: 56, bottom: 320, left: 56 },
+  zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
+  minFocusPx: 96,
+  captionMaxWidth: 980
+};
+var PROFILE_1x1 = {
+  width: 1080,
+  height: 1080,
+  fps: 30,
+  safeArea: { top: 80, right: 72, bottom: 200, left: 72 },
+  zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
+  minFocusPx: 100,
+  captionMaxWidth: 940
+};
+function profileForAspect(aspect, resolution, fps) {
+  const base = aspect === "9:16" ? PROFILE_9x16 : aspect === "1:1" ? PROFILE_1x1 : PROFILE_16x9;
+  const scaleX = resolution.w / base.width;
+  const scaleY = resolution.h / base.height;
+  return {
+    ...base,
+    width: resolution.w,
+    height: resolution.h,
+    fps,
+    safeArea: {
+      top: Math.round(base.safeArea.top * scaleY),
+      bottom: Math.round(base.safeArea.bottom * scaleY),
+      left: Math.round(base.safeArea.left * scaleX),
+      right: Math.round(base.safeArea.right * scaleX)
+    },
+    captionMaxWidth: Math.round(base.captionMaxWidth * scaleX)
+  };
+}
+function actReactWindows(step) {
+  if (!step.focusRectVp || !step.targetRectVp) return null;
+  if (step.focus === "target" || step.focus === "wide") return null;
+  if (step.outEnd - step.outBeat < 1600) return null;
+  return {
+    act: { rect: step.targetRectVp, from: step.outBeat - 60, to: step.outBeat + 400 },
+    react: { rect: step.focusRectVp, from: step.outBeat + 1100, to: step.outEnd }
+  };
+}
+
+// src/compose/kinds.ts
+var BASE = {
+  pacing: "normal",
+  captionStyle: "instruction",
+  numberedCaptions: true,
+  elapsedClock: false,
+  chapterCards: false,
+  outroMs: 1600,
+  showTypedInput: true,
+  cameraEmphasis: true,
+  stage: true
+};
+var PROFILES = {
+  walkthrough: { kind: "walkthrough", ...BASE },
+  demo: {
+    kind: "demo",
+    ...BASE,
+    pacing: "relaxed",
+    captionStyle: "chapter",
+    numberedCaptions: false,
+    chapterCards: true,
+    outroMs: 2200
+  },
+  "bug-repro": {
+    kind: "bug-repro",
+    ...BASE,
+    pacing: "normal",
+    captionStyle: "factual",
+    numberedCaptions: true,
+    elapsedClock: true,
+    outroMs: 3e3,
+    // A repro is EVIDENCE: no directorial zoom, no spotlights, no matte — the literal screen.
+    cameraEmphasis: false,
+    stage: false
+  },
+  "before-after": { kind: "before-after", ...BASE, pacing: "normal", chapterCards: true, numberedCaptions: false },
+  release: { kind: "release", ...BASE, pacing: "brisk", numberedCaptions: false, outroMs: 1400 },
+  social: { kind: "social", ...BASE, pacing: "brisk", numberedCaptions: false, outroMs: 1400 }
+};
+function kindProfile(kind) {
+  return PROFILES[kind] ?? PROFILES.walkthrough;
+}
+
+// src/capture/events.ts
+function actionEvents(log2) {
+  return log2.events.filter((e) => e.type === "action");
+}
+function navigationEvents(log2) {
+  return log2.events.filter((e) => e.type === "navigation");
+}
+
+// src/audio/timing.ts
+var AUDIO_LEAD_MS = 150;
+var AUDIO_TAIL_MS = 450;
+
+// src/compose/timeline/pacing.ts
+function pacingConfig(mode, kind) {
+  const factor = mode === "relaxed" ? 1.25 : mode === "brisk" ? 0.8 : 1;
+  return {
+    factor,
+    titleCardMs: 2200,
+    introMaxMs: 1200,
+    outroMs: kind?.outroMs ?? 1600,
+    idleGapMaxMs: 1500,
+    idleGapOutMs: 400,
+    minStepMs: 1800 * factor,
+    maxTypeOutMs: 4500,
+    holds: {
+      goto: 1200 * factor,
+      click: 600 * factor,
+      dblclick: 600 * factor,
+      hover: 450 * factor,
+      type: 450 * factor,
+      press: 450 * factor,
+      select: 600 * factor,
+      scroll: 350 * factor,
+      expect: 800 * factor,
+      wait: 150
+    }
+  };
+}
+function buildTimeline(log2, cfg, audioMs) {
+  const events = actionEvents(log2);
+  const segments = [];
+  const steps = [];
+  segments.push({ kind: "card", outStart: 0, outEnd: cfg.titleCardMs, cardId: "title" });
+  let out = cfg.titleCardMs;
+  let src = events.length > 0 ? Math.max(0, events[0].tStart - cfg.introMaxMs) : 0;
+  for (const e of events) {
+    const gap = e.tStart - src;
+    if (gap > 1) {
+      const outDur = gap > cfg.idleGapMaxMs ? cfg.idleGapOutMs : gap;
+      segments.push({ kind: "source", outStart: out, outEnd: out + outDur, srcStart: src, srcEnd: e.tStart });
+      out += outDur;
+    }
+    const stepOutStart = out;
+    const srcEnd = Math.max(e.tSettled, e.tActionEnd, e.tStart + 1);
+    const spanSrc = srcEnd - e.tStart;
+    let spanOut = spanSrc;
+    if (e.kind === "type" && spanSrc > cfg.maxTypeOutMs) spanOut = cfg.maxTypeOutMs;
+    segments.push({ kind: "source", outStart: out, outEnd: out + spanOut, srcStart: e.tStart, srcEnd });
+    const outBeat = out + (e.tAction - e.tStart) * (spanOut / spanSrc);
+    out += spanOut;
+    let hold = cfg.holds[e.kind];
+    if (out + hold - stepOutStart < cfg.minStepMs) hold = cfg.minStepMs - (out - stepOutStart);
+    const aud = audioMs?.get(`${e.sceneId}/${e.stepIndex}`);
+    if (aud && aud > 0) {
+      const need = AUDIO_LEAD_MS + aud + AUDIO_TAIL_MS;
+      const have = out - stepOutStart + hold;
+      if (have < need) hold += need - have;
+    }
+    if (e.focusTarget && e.focus && e.focus !== "target" && e.focus !== "wide") {
+      const needAfterBeat = 2100;
+      const haveAfterBeat = out + hold - outBeat;
+      if (haveAfterBeat < needAfterBeat) hold += needAfterBeat - haveAfterBeat;
+    }
+    if (hold > 0.5) {
+      segments.push({ kind: "freeze", outStart: out, outEnd: out + hold, srcAt: srcEnd });
+      out += hold;
+    }
+    steps.push({
+      stepRef: `${e.sceneId}/${e.stepIndex}`,
+      sceneId: e.sceneId,
+      ordinal: e.ordinal,
+      kind: e.kind,
+      ...e.locator ? { locator: e.locator } : {},
+      ...e.masked ? { masked: true } : {},
+      ...e.targetPre ? { targetRectVp: e.targetPre.bbox } : {},
+      ...e.focus ? { focus: e.focus } : {},
+      ...e.shot ? { shot: e.shot } : {},
+      ...e.focusTarget ? { focusRectVp: e.focusTarget.bbox } : {},
+      outStart: stepOutStart,
+      outBeat,
+      outEnd: out,
+      srcAction: e.tAction,
+      srcSettled: srcEnd
+    });
+    src = srcEnd;
+  }
+  const lastSrc = Math.max(src, log2.meta.durationMs - 1);
+  segments.push({ kind: "freeze", outStart: out, outEnd: out + cfg.outroMs, srcAt: lastSrc });
+  out += cfg.outroMs;
+  return { segments, steps, durationMs: out };
+}
+function sampleSource(segments, tOut) {
+  const seg = segmentAt(segments, tOut);
+  switch (seg.kind) {
+    case "card":
+      return { srcAt: null, segment: seg };
+    case "freeze":
+      return { srcAt: seg.srcAt, segment: seg };
+    case "source": {
+      const u = (tOut - seg.outStart) / Math.max(1e-6, seg.outEnd - seg.outStart);
+      return { srcAt: seg.srcStart + u * (seg.srcEnd - seg.srcStart), segment: seg };
+    }
+  }
+}
+function segmentAt(segments, tOut) {
+  let lo = 0;
+  let hi = segments.length - 1;
+  if (tOut <= segments[0].outStart) return segments[0];
+  if (tOut >= segments[hi].outEnd) return segments[hi];
+  while (lo < hi) {
+    const mid = lo + hi >> 1;
+    if (segments[mid].outEnd <= tOut) lo = mid + 1;
+    else hi = mid;
+  }
+  return segments[lo];
+}
+function eventByStepRef(log2) {
+  const map = /* @__PURE__ */ new Map();
+  for (const e of actionEvents(log2)) map.set(`${e.sceneId}/${e.stepIndex}`, e);
+  return map;
+}
+
+// src/compose/camera/interpolate.ts
+function sampleCamera(keyframes, tOut) {
+  if (keyframes.length === 0) return { cx: 0, cy: 0, zoom: 1 };
+  if (tOut <= keyframes[0].tOut) return { ...keyframes[0].state };
+  const last = keyframes[keyframes.length - 1];
+  if (tOut >= last.tOut) return { ...last.state };
+  let lo = 0;
+  let hi = keyframes.length - 1;
+  while (lo < hi - 1) {
+    const mid = lo + hi >> 1;
+    if (keyframes[mid].tOut <= tOut) lo = mid;
+    else hi = mid;
+  }
+  const a = keyframes[lo];
+  const b = keyframes[hi];
+  const u = (tOut - a.tOut) / Math.max(1e-6, b.tOut - a.tOut);
+  const e = cubicBezier(b.ease, u);
+  return {
+    cx: a.state.cx + (b.state.cx - a.state.cx) * e,
+    cy: a.state.cy + (b.state.cy - a.state.cy) * e,
+    zoom: Math.exp(Math.log(a.state.zoom) + (Math.log(b.state.zoom) - Math.log(a.state.zoom)) * e)
+  };
+}
+
+// src/compose/camera/planner.ts
+var FOCUS_PAD_VP = 24;
+var SHOT_MAX_GAP_MS = 4e3;
+var PAN_DEADBAND_VP = 48;
+var TRAVEL_MIN_MS = 500;
+var TRAVEL_MAX_MS = 900;
+var ARRIVE_LEAD_MS = 80;
+var LEGIBLE_TARGET_PX = 34;
+function planCamera(steps, log2, profile, durationMs, opts) {
+  const content = stageContent(profile);
+  const plane2 = {
+    vpW: log2.meta.viewport.w,
+    vpH: log2.meta.viewport.h,
+    outW: content.w,
+    outH: content.h
+  };
+  const emphasis = opts?.emphasis ?? true;
+  const fallbacks = [];
+  const sharpZoom = log2.meta.frameW > 0 ? log2.meta.frameW / content.w : 1.3;
+  const zMaxAllowed = Math.max(minZoom(plane2), sharpZoom * 1.28);
+  const quantums = profile.zoomQuantums.filter((q) => q <= zMaxAllowed + 1e-6);
+  if (quantums.length === 0) quantums.push(1);
+  const navTimes = navigationEvents(log2).map((n) => n.t);
+  const shots = groupShots(steps, navTimes, plane2, durationMs);
+  for (let attempt = 0; attempt < 4; attempt++) {
+    for (const shot2 of shots) shot2.state = shotState(shot2, quantums, plane2, profile, emphasis);
+    const keyframes = emitKeyframes(shots, plane2, durationMs);
+    const violation = checkConstraints(keyframes, steps, plane2, profile);
+    if (!violation) return { keyframes, fallbacks };
+    const shot = shots.find(
+      (s) => s.stepRefs.includes(violation.stepRef) && violation.tOut >= s.outStart && violation.tOut <= s.outEnd
+    ) ?? shots.find((s) => s.stepRefs.includes(violation.stepRef));
+    if (!shot || shot.zoomIndex === 0 || shot.wide) {
+      fallbacks.push(`${violation.stepRef}: unresolvable framing violation \u2014 falling back to wide`);
+      if (shot) shot.wide = true;
+      else break;
+    } else {
+      shot.zoomIndex -= 1;
+      fallbacks.push(`${violation.stepRef}: reduced shot zoom to satisfy framing constraints`);
+    }
+  }
+  for (const shot of shots) shot.state = shotState(shot, quantums, plane2, profile, emphasis);
+  return { keyframes: emitKeyframes(shots, plane2, durationMs), fallbacks };
+}
+function groupShots(steps, navTimes, plane2, durationMs) {
+  const shots = [];
+  let current = null;
+  const navBetween = (a, b) => navTimes.some((t) => t > a && t <= b);
+  for (const step of steps) {
+    const handoff = actReactWindows(step);
+    if (handoff) {
+      const actFocus = padRect(handoff.act.rect, FOCUS_PAD_VP);
+      const reactFocus = padRect(handoff.react.rect, FOCUS_PAD_VP);
+      shots.push({
+        stepRefs: [step.stepRef],
+        sceneId: step.sceneId,
+        focus: actFocus,
+        minTargetDim: Math.min(handoff.act.rect.w, handoff.act.rect.h),
+        wide: false,
+        outStart: step.outStart,
+        firstBeat: step.outBeat,
+        outEnd: handoff.act.to,
+        zoomIndex: Number.MAX_SAFE_INTEGER
+      });
+      shots.push({
+        stepRefs: [step.stepRef],
+        sceneId: step.sceneId,
+        focus: reactFocus,
+        minTargetDim: Math.min(handoff.react.rect.w, handoff.react.rect.h),
+        wide: false,
+        outStart: handoff.act.to,
+        firstBeat: handoff.react.from,
+        // arrive by the react window's start
+        outEnd: step.outEnd,
+        zoomIndex: Number.MAX_SAFE_INTEGER
+      });
+      current = null;
+      continue;
+    }
+    let rect = step.kind === "goto" ? void 0 : step.targetRectVp;
+    let wide = !rect || step.kind === "goto" || step.kind === "scroll";
+    if (step.focus === "wide") {
+      wide = true;
+    } else if (step.focusRectVp) {
+      rect = step.focusRectVp;
+      wide = false;
+    } else if (step.focus === "target" && rect) {
+      wide = false;
+    }
+    if (step.shot === "cut") current = null;
+    const forceContinue = step.shot === "continue";
+    if (forceContinue && current && rect && current.sceneId === step.sceneId) {
+      current.stepRefs.push(step.stepRef);
+      current.focus = rectUnion(current.focus, padRect(rect, FOCUS_PAD_VP));
+      current.minTargetDim = Math.min(current.minTargetDim, Math.min(rect.w, rect.h));
+      current.outEnd = step.outEnd;
+      continue;
+    }
+    const noMerge = step.focus === "target" || step.focusRectVp !== void 0;
+    if (current && !noMerge && current.sceneId === step.sceneId && !current.wide && !wide && rect) {
+      const prevSrc = current.stepRefs.length > 0 ? steps.find((s) => s.stepRef === current.stepRefs[current.stepRefs.length - 1]).srcSettled : 0;
+      const union = rectUnion(current.focus, padRect(rect, FOCUS_PAD_VP));
+      const baseScale = plane2.outW / plane2.vpW;
+      const mergedMinDim = Math.min(current.minTargetDim, Math.min(rect.w, rect.h));
+      const zNeeded = Math.min(LEGIBLE_TARGET_PX / (mergedMinDim * baseScale), 1.6);
+      const zFitUnion = fitZoom(union, plane2) * 0.92;
+      const fitsTogether = fitZoom(union, plane2) >= 1.2 && zFitUnion >= zNeeded - 0.02;
+      const closeInTime = step.outStart - current.outEnd < SHOT_MAX_GAP_MS;
+      if (fitsTogether && closeInTime && !navBetween(prevSrc, step.srcAction)) {
+        current.stepRefs.push(step.stepRef);
+        current.focus = union;
+        current.minTargetDim = Math.min(current.minTargetDim, Math.min(rect.w, rect.h));
+        current.outEnd = step.outEnd;
+        continue;
+      }
+    }
+    current = {
+      stepRefs: [step.stepRef],
+      sceneId: step.sceneId,
+      focus: rect ? padRect(rect, FOCUS_PAD_VP) : { x: 0, y: 0, w: plane2.vpW, h: plane2.vpH },
+      minTargetDim: rect ? Math.min(rect.w, rect.h) : Math.min(plane2.vpW, plane2.vpH),
+      wide,
+      outStart: step.outStart,
+      firstBeat: step.outBeat,
+      outEnd: step.outEnd,
+      zoomIndex: Number.MAX_SAFE_INTEGER
+      // resolved in shotState
+    };
+    shots.push(current);
+  }
+  if (shots.length > 0) shots[shots.length - 1].outEnd = Math.min(shots[shots.length - 1].outEnd, durationMs);
+  return shots;
+}
+function fitZoom(rect, plane2) {
+  const zw = plane2.vpW / rect.w;
+  const zh = plane2.vpW * plane2.outH / plane2.outW / rect.h;
+  return Math.min(zw, zh);
+}
+var OCCUPANCY = 0.5;
+function shotState(shot, quantums, plane2, profile, emphasis) {
+  const zMin = minZoom(plane2);
+  if (shot.wide) {
+    return clampCamera({ cx: plane2.vpW / 2, cy: rectCenter(shot.focus).y, zoom: zMin }, plane2);
+  }
+  const baseScale = plane2.outW / plane2.vpW;
+  const minDim = Math.max(6, shot.minTargetDim);
+  const zLegibility = LEGIBLE_TARGET_PX / (minDim * baseScale);
+  const zFit = fitZoom(shot.focus, plane2) * 0.92;
+  const zComposition = emphasis ? OCCUPANCY * fitZoom(shot.focus, plane2) : 0;
+  const zWant = Math.max(zLegibility, zComposition);
+  const maxFit = Math.min(zFit, quantums[quantums.length - 1]);
+  let zoomIndex = 0;
+  let reachedWant = false;
+  for (let i = 0; i < quantums.length; i++) {
+    if (quantums[i] > maxFit + 1e-6) break;
+    zoomIndex = i;
+    if (!reachedWant && quantums[i] >= zWant - 1e-6) {
+      zoomIndex = i;
+      reachedWant = true;
+      break;
+    }
+  }
+  shot.zoomIndex = Math.min(shot.zoomIndex, zoomIndex);
+  const zoom = Math.max(quantums[shot.zoomIndex], zMin);
+  const center = rectCenter(shot.focus);
+  let state = clampCamera({ cx: center.x, cy: center.y, zoom }, plane2);
+  for (let i = 0; i < 3; i++) {
+    const proj = projectRect(shot.focus, state, plane2);
+    const safe = contentArea(profile);
+    let dyOut = 0;
+    if (proj.y + proj.h > safe.y + safe.h) dyOut = proj.y + proj.h - (safe.y + safe.h);
+    else if (proj.y < safe.y) dyOut = proj.y - safe.y;
+    let dxOut = 0;
+    if (proj.x + proj.w > safe.x + safe.w) dxOut = proj.x + proj.w - (safe.x + safe.w);
+    else if (proj.x < safe.x) dxOut = proj.x - safe.x;
+    if (Math.abs(dxOut) < 1 && Math.abs(dyOut) < 1) break;
+    const visW = plane2.vpW / state.zoom;
+    const scale = visW / plane2.outW;
+    state = clampCamera({ cx: state.cx + dxOut * scale, cy: state.cy + dyOut * scale, zoom: state.zoom }, plane2);
+  }
+  return state;
+}
+function contentArea(profile) {
+  const s = stageContent(profile);
+  const left = Math.max(profile.safeArea.left - s.x, 8);
+  const top = Math.max(profile.safeArea.top - s.y, 8);
+  const right = Math.min(s.w - 8, profile.width - profile.safeArea.right - s.x);
+  const bottom = Math.min(s.h - 8, profile.height - profile.safeArea.bottom - s.y);
+  return { x: left, y: top, w: Math.max(16, right - left), h: Math.max(16, bottom - top) };
+}
+function emitKeyframes(shots, plane2, durationMs) {
+  const kfs = [];
+  const wideState = clampCamera({ cx: plane2.vpW / 2, cy: plane2.vpH / 2, zoom: minZoom(plane2) }, plane2);
+  let prevState = wideState;
+  let prevEnd = 0;
+  kfs.push({ tOut: 0, state: wideState, ease: EASE_ZOOM });
+  for (const shot of shots) {
+    const target = shot.state;
+    const panDist = Math.hypot(target.cx - prevState.cx, target.cy - prevState.cy);
+    const zoomChanged = Math.abs(Math.log(target.zoom / prevState.zoom)) > 0.01;
+    if (panDist < PAN_DEADBAND_VP / 2 && !zoomChanged) {
+      prevEnd = shot.outEnd;
+      continue;
+    }
+    const viaWide = panDist > plane2.vpW * 0.6 && prevState.zoom > 1.15 && target.zoom > 1.15 ? wideState : null;
+    const arriveBy = Math.max(shot.firstBeat - ARRIVE_LEAD_MS, shot.outStart + 100);
+    const travel = clamp(300 + panDist * 0.8, TRAVEL_MIN_MS, TRAVEL_MAX_MS);
+    let moveStart = Math.max(prevEnd, arriveBy - travel);
+    if (viaWide) {
+      const mid = Math.max(prevEnd, moveStart - 350);
+      kfs.push({ tOut: mid, state: prevState, ease: EASE_PAN });
+      kfs.push({ tOut: Math.min(mid + 400, arriveBy - 200), state: viaWide, ease: EASE_ZOOM });
+      moveStart = Math.min(mid + 400, arriveBy - 200);
+    } else {
+      kfs.push({ tOut: moveStart, state: prevState, ease: EASE_PAN });
+    }
+    const moveEnd = Math.max(arriveBy, moveStart + 250);
+    kfs.push({ tOut: moveEnd, state: target, ease: zoomChanged ? EASE_ZOOM : EASE_PAN });
+    prevState = target;
+    prevEnd = shot.outEnd;
+  }
+  if (prevState.zoom > wideState.zoom + 0.01 || Math.hypot(prevState.cx - wideState.cx, prevState.cy - wideState.cy) > PAN_DEADBAND_VP) {
+    const start = Math.min(prevEnd + 100, durationMs - 900);
+    kfs.push({ tOut: start, state: prevState, ease: EASE_ZOOM });
+    kfs.push({ tOut: Math.min(start + 800, durationMs - 50), state: wideState, ease: EASE_ZOOM });
+  }
+  return dedupeSorted(kfs);
+}
+function dedupeSorted(kfs) {
+  kfs.sort((a, b) => a.tOut - b.tOut);
+  const out = [];
+  for (const kf of kfs) {
+    const last = out[out.length - 1];
+    if (last && kf.tOut - last.tOut < 1) {
+      out[out.length - 1] = kf;
+    } else {
+      out.push(kf);
+    }
+  }
+  return out;
+}
+function checkConstraints(keyframes, steps, plane2, profile) {
+  const content = stageContent(profile);
+  const frame = { x: 0, y: 0, w: content.w, h: content.h };
+  for (const step of steps) {
+    const handoff = actReactWindows(step);
+    const rect = step.focusRectVp ?? step.targetRectVp;
+    const windows = handoff ? [handoff.act, handoff.react] : rect ? [{ rect, from: Math.max(step.outStart, step.outBeat - 60), to: step.outEnd }] : [];
+    for (const w of windows) {
+      for (let t = w.from; t <= w.to; t += 100) {
+        const cam = sampleCamera(keyframes, t);
+        const proj = projectRect(w.rect, cam, plane2);
+        if (!rectContains(frame, proj, 2)) {
+          return { stepRef: step.stepRef, tOut: t };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// src/compose/cursor/path.ts
+var RESAMPLE_POINTS = 32;
+var CLICK_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
+var POINTER_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "hover", "type", "select"]);
+function planCursor(steps, log2) {
+  const events = eventByStepRef(log2);
+  const segments = [];
+  const ripples = [];
+  let rest = { x: log2.meta.viewport.w / 2, y: log2.meta.viewport.h * 0.6 };
+  const restStart = { ...rest };
+  for (const step of steps) {
+    if (!POINTER_KINDS.has(step.kind)) continue;
+    const event = events.get(step.stepRef);
+    if (!event || event.cursorPath.length < 2) continue;
+    const raw = event.cursorPath.map((w) => ({ x: w.x, y: w.y }));
+    raw[0] = { ...rest };
+    const path = resampleByArcLength(raw, RESAMPLE_POINTS);
+    const travelDist = dist(path[0], path[path.length - 1]);
+    const travel = clamp(300 + travelDist * 0.6, 300, 900);
+    const prevEnd = segments.length > 0 ? segments[segments.length - 1].tEnd : 0;
+    const tEnd = step.outBeat;
+    const tStart = Math.max(Math.min(step.outStart, tEnd - 100), tEnd - travel, prevEnd + 40);
+    if (tEnd - tStart > 30) {
+      segments.push({ tStart, tEnd, path, clickAtEnd: CLICK_KINDS.has(step.kind) });
+    }
+    rest = path[path.length - 1];
+    if (CLICK_KINDS.has(step.kind)) {
+      ripples.push({ tOut: step.outBeat, x: rest.x, y: rest.y });
+    }
+  }
+  return { segments, ripples, restStart };
+}
+function sampleCursor(plan2, tOut) {
+  const segs = plan2.segments;
+  if (segs.length === 0) return plan2.restStart;
+  if (tOut <= segs[0].tStart) return segs[0].path[0];
+  for (let i = 0; i < segs.length; i++) {
+    const s = segs[i];
+    if (tOut < s.tStart) return segs[i - 1].path[segs[i - 1].path.length - 1];
+    if (tOut <= s.tEnd) {
+      const u = minJerk((tOut - s.tStart) / Math.max(1e-6, s.tEnd - s.tStart));
+      const fi = u * (s.path.length - 1);
+      const i0 = Math.floor(fi);
+      const i1 = Math.min(i0 + 1, s.path.length - 1);
+      const f = fi - i0;
+      return {
+        x: s.path[i0].x + (s.path[i1].x - s.path[i0].x) * f,
+        y: s.path[i0].y + (s.path[i1].y - s.path[i0].y) * f
+      };
+    }
+  }
+  const last = segs[segs.length - 1];
+  return last.path[last.path.length - 1];
+}
+function resampleByArcLength(points, n) {
+  const cum = [0];
+  for (let i = 1; i < points.length; i++) {
+    cum.push(cum[i - 1] + dist(points[i - 1], points[i]));
+  }
+  const total = cum[cum.length - 1];
+  if (total < 1e-6) return Array.from({ length: n }, () => ({ ...points[0] }));
+  const out = [];
+  let j = 0;
+  for (let i = 0; i < n; i++) {
+    const target = i / (n - 1) * total;
+    while (j < cum.length - 2 && cum[j + 1] < target) j++;
+    const span = Math.max(1e-6, cum[j + 1] - cum[j]);
+    const f = (target - cum[j]) / span;
+    out.push({
+      x: points[j].x + (points[j + 1].x - points[j].x) * f,
+      y: points[j].y + (points[j + 1].y - points[j].y) * f
+    });
+  }
+  return out;
+}
+
+// src/compose/captions.ts
+function writeCaption(event, texts) {
+  if (texts?.caption) return texts.caption;
+  if (event.caption) return event.caption;
+  const label = bestLabel(event);
+  switch (event.kind) {
+    case "click":
+      return label ? `Click \u201C${label}\u201D` : "Click the highlighted element";
+    case "dblclick":
+      return label ? `Double-click \u201C${label}\u201D` : "Double-click the highlighted element";
+    case "hover":
+      return label ? `Hover over \u201C${label}\u201D` : "Hover over the highlighted element";
+    case "type":
+      return label ? `Enter the ${lowerFirst(label)}` : "Enter a value";
+    case "press":
+      return `Press ${event.locator ?? "the key"}`;
+    case "select":
+      return label && event.typedText ? `Choose \u201C${event.typedText}\u201D under ${label}` : label ? `Choose an option under ${label}` : "Choose an option";
+    case "goto":
+      return `Open ${prettyUrl(event.locator ?? "")}`;
+    case "scroll":
+      return label ? `Scroll to ${label}` : "Scroll down";
+    case "expect":
+    case "wait":
+      return null;
+  }
+}
+function writeNarration(event, texts) {
+  return texts?.narration ?? event.narration ?? writeCaption(event, texts);
+}
+function bestLabel(event) {
+  const name = event.targetPre?.accessibleName?.trim();
+  if (name) return truncate(name, 60);
+  if (event.locator) {
+    try {
+      return truncate(locatorDisplayName(parseLocator(event.locator)), 60);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function lowerFirst(s) {
+  if (s.length > 1 && s[1] === s[1].toUpperCase() && /[A-Z]/.test(s[1])) return s;
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function prettyUrl(url) {
+  try {
+    const u = new URL(url);
+    return u.host + (u.pathname !== "/" ? u.pathname : "");
+  } catch {
+    return url;
+  }
+}
+function truncate(s, max) {
+  return s.length <= max ? s : s.slice(0, max - 1) + "\u2026";
+}
+
+// src/compose/overlays/text.ts
+import { createCanvas } from "@napi-rs/canvas";
+var measureCtx = null;
+function ctx() {
+  if (!measureCtx) measureCtx = createCanvas(8, 8).getContext("2d");
+  return measureCtx;
+}
+function measureText(text, font) {
+  const c = ctx();
+  c.font = font;
+  return c.measureText(text).width;
+}
+function wrapText(text, fontFor, maxWidth, fontPx, minFontPx, maxLines) {
+  let attempt = wrapAt(text, fontFor(fontPx), maxWidth);
+  if (attempt.length <= maxLines) {
+    return { lines: attempt, fontPx, widest: widestOf(attempt, fontFor(fontPx)), shrunk: false, truncated: false };
+  }
+  attempt = wrapAt(text, fontFor(minFontPx), maxWidth);
+  if (attempt.length <= maxLines) {
+    return { lines: attempt, fontPx: minFontPx, widest: widestOf(attempt, fontFor(minFontPx)), shrunk: true, truncated: false };
+  }
+  const kept = attempt.slice(0, maxLines);
+  let last = kept[maxLines - 1];
+  const font = fontFor(minFontPx);
+  while (last.length > 1 && measureText(last + "\u2026", font) > maxWidth) {
+    last = last.slice(0, -1).trimEnd();
+  }
+  kept[maxLines - 1] = last + "\u2026";
+  return { lines: kept, fontPx: minFontPx, widest: widestOf(kept, font), shrunk: true, truncated: true };
+}
+function wrapAt(text, font, maxWidth) {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    const candidate = line ? line + " " + word : word;
+    if (line && measureText(candidate, font) > maxWidth) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.length > 0 ? lines : [""];
+}
+function widestOf(lines, font) {
+  return Math.max(...lines.map((l) => measureText(l, font)));
+}
+function roundRect(c, x, y, w, h, r) {
+  const rr = Math.min(r, w / 2, h / 2);
+  c.beginPath();
+  c.moveTo(x + rr, y);
+  c.arcTo(x + w, y, x + w, y + h, rr);
+  c.arcTo(x + w, y + h, x, y + h, rr);
+  c.arcTo(x, y + h, x, y, rr);
+  c.arcTo(x, y, x + w, y, rr);
+  c.closePath();
+}
+
+// src/compose/overlays/build.ts
+var CARD_PAD_X = 26;
+var CARD_PAD_Y = 16;
+var BADGE_GAP = 14;
+var CARD_BOTTOM_MARGIN = 44;
+var CHAPTER_LABEL_MS = 1800;
+var CAPTION_CROSSFADE_MS = 240;
+function overlaps(a, b) {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+function buildOverlays(steps, log2, theme, profile, title, subtitle, titleCardEndMs, diagnostics, kind, sceneTitles, camera, specTexts) {
+  const overlays = [];
+  overlays.push({ kind: "titleCard", cardId: "title", title, subtitle, tStart: 0, tEnd: titleCardEndMs });
+  overlays.push({ kind: "dip", tStart: titleCardEndMs, tEnd: titleCardEndMs + 400 });
+  const events = eventByStepRef(log2);
+  const captioned = steps.filter((s) => {
+    const e = events.get(s.stepRef);
+    return e && writeCaption(e, specTexts?.get(s.stepRef)) !== null;
+  });
+  const total = captioned.length;
+  let number = 0;
+  if (kind.chapterCards) {
+    const boundaries = sceneBoundaries(steps, sceneTitles);
+    let chapter = 0;
+    for (const b of boundaries) {
+      chapter += 1;
+      overlays.push({ kind: "chapterLabel", title: b.title, ordinal: chapter, tStart: b.outStart, tEnd: b.outStart + CHAPTER_LABEL_MS });
+    }
+  }
+  if (kind.elapsedClock) {
+    const firstBeat = captioned[0]?.outBeat ?? titleCardEndMs;
+    const last = steps[steps.length - 1];
+    overlays.push({ kind: "elapsedClock", tStart: titleCardEndMs, tEnd: last ? last.outEnd : titleCardEndMs, zeroAtMs: firstBeat });
+  }
+  for (let i = 0; theme.captionPosition !== "off" && i < captioned.length; i++) {
+    const step = captioned[i];
+    const event = events.get(step.stepRef);
+    const base = writeCaption(event, specTexts?.get(step.stepRef));
+    number += 1;
+    const text = kind.captionStyle === "factual" ? `Step ${number} \u2014 ${lowerFirst2(base)}` : base;
+    const fontFor = (px) => `${px}px Inter Medium`;
+    const showBadge = kind.numberedCaptions && kind.captionStyle !== "factual";
+    const badgeFontPx = 15;
+    const badgeText = `${number}/${total}`;
+    const badgeW = showBadge ? Math.ceil(measureText(badgeText, `600 ${badgeFontPx}px Inter SemiBold`)) + 20 : 0;
+    const badgeGap = showBadge ? BADGE_GAP : 0;
+    const maxTextWidth = Math.min(profile.captionMaxWidth, profile.width - 2 * profile.safeArea.left) - CARD_PAD_X * 2 - badgeW - badgeGap;
+    const wrap = wrapText(text, fontFor, maxTextWidth, theme.captionFontPx, theme.captionMinFontPx, theme.captionMaxLines);
+    if (wrap.truncated) diagnostics.overflows.push({ stepRef: step.stepRef, text, action: "truncated" });
+    else if (wrap.shrunk) diagnostics.overflows.push({ stepRef: step.stepRef, text, action: "shrunk" });
+    const lineH = Math.round(wrap.fontPx * 1.35);
+    const cardW = CARD_PAD_X * 2 + badgeW + badgeGap + Math.ceil(wrap.widest);
+    const cardH = CARD_PAD_Y * 2 + wrap.lines.length * lineH;
+    const x = (profile.width - cardW) / 2;
+    let y = theme.captionPosition === "bottom" ? profile.height - CARD_BOTTOM_MARGIN - cardH : profile.safeArea.top;
+    if (camera && theme.captionPosition === "bottom") {
+      const rect = step.focusRectVp ?? step.targetRectVp;
+      if (rect) {
+        const content = stageContent(profile);
+        const capPlane = { vpW: log2.meta.viewport.w, vpH: log2.meta.viewport.h, outW: content.w, outH: content.h };
+        const cam = sampleCamera(camera, Math.min(step.outBeat + 250, step.outEnd));
+        const proj = projectRect(rect, cam, capPlane);
+        const projFrame = { x: proj.x + content.x, y: proj.y + content.y, w: proj.w, h: proj.h };
+        const capBox = { x, y, w: cardW, h: cardH };
+        if (overlaps(projFrame, capBox)) y = profile.safeArea.top;
+      }
+    }
+    const next = captioned[i + 1];
+    const tEnd = next ? Math.min(step.outEnd, next.outStart + CAPTION_CROSSFADE_MS) : step.outEnd;
+    const overlay = {
+      kind: "caption",
+      stepRef: step.stepRef,
+      ordinal: number,
+      totalSteps: total,
+      showBadge,
+      text,
+      lines: wrap.lines,
+      fontPx: wrap.fontPx,
+      box: { x, y, w: cardW, h: cardH },
+      tStart: step.outStart,
+      tEnd,
+      shrunk: wrap.shrunk,
+      truncated: wrap.truncated
+    };
+    overlays.push(overlay);
+  }
+  return overlays;
+}
+function sceneBoundaries(steps, sceneTitles) {
+  const out = [];
+  let lastScene = "";
+  for (const s of steps) {
+    if (s.sceneId !== lastScene) {
+      lastScene = s.sceneId;
+      out.push({ title: sceneTitles?.get(s.sceneId) ?? titleFromSceneId(s.sceneId), outStart: s.outStart });
+    }
+  }
+  return out;
+}
+function titleFromSceneId(id) {
+  const t = id.replace(/-/g, " ");
+  return t.charAt(0).toUpperCase() + t.slice(1);
+}
+function lowerFirst2(s) {
+  if (s.length > 1 && s[1] === s[1].toUpperCase() && /[A-Z]/.test(s[1])) return s;
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+// src/compose/render/renderer.ts
+import { createCanvas as createCanvas3 } from "@napi-rs/canvas";
+
+// src/compose/cursor/render.ts
+var RIPPLE_MS = 350;
+var PRESS_DOWN_MS = 90;
+var PRESS_UP_MS = 120;
+function drawCursor(ctx2, p, zoom, tOut, ripples, rippleCenters, theme, baseScale = 1, glyph = "arrow") {
+  let scale = 1;
+  for (const r of ripples) {
+    const dt = tOut - r.tOut;
+    if (dt >= -PRESS_DOWN_MS && dt < 0) scale = 1 - 0.15 * (1 + dt / PRESS_DOWN_MS);
+    else if (dt >= 0 && dt <= PRESS_UP_MS) scale = 0.85 + 0.15 * (dt / PRESS_UP_MS);
+  }
+  for (let i = 0; i < ripples.length; i++) {
+    const r = ripples[i];
+    const dt = tOut - r.tOut;
+    if (dt < 0 || dt > RIPPLE_MS) continue;
+    const u = dt / RIPPLE_MS;
+    const c = rippleCenters[i];
+    ctx2.save();
+    ctx2.beginPath();
+    ctx2.arc(c.x, c.y, (6 + 42 * easeOut(u)) * baseScale, 0, Math.PI * 2);
+    ctx2.strokeStyle = theme.accent;
+    ctx2.globalAlpha = 0.6 * (1 - u);
+    ctx2.lineWidth = 3.5 * baseScale * (1 - u * 0.5);
+    ctx2.stroke();
+    ctx2.restore();
+  }
+  const size = 24 * baseScale * (1 + 0.15 * (zoom - 1)) * scale;
+  ctx2.save();
+  ctx2.translate(p.x, p.y);
+  ctx2.scale(size / 24, size / 24);
+  ctx2.shadowColor = "rgba(0,0,0,0.35)";
+  ctx2.shadowBlur = 5;
+  ctx2.shadowOffsetY = 1.5;
+  if (glyph === "ibeam") {
+    ctx2.beginPath();
+    ctx2.moveTo(-4, -9);
+    ctx2.lineTo(4, -9);
+    ctx2.moveTo(0, -9);
+    ctx2.lineTo(0, 9);
+    ctx2.moveTo(-4, 9);
+    ctx2.lineTo(4, 9);
+    ctx2.lineWidth = 2.4;
+    ctx2.strokeStyle = "#ffffff";
+    ctx2.stroke();
+    ctx2.shadowColor = "transparent";
+    ctx2.lineWidth = 1;
+    ctx2.strokeStyle = "rgba(20,24,34,0.9)";
+    ctx2.stroke();
+  } else {
+    ctx2.beginPath();
+    ctx2.moveTo(0, 0);
+    ctx2.lineTo(0, 17.5);
+    ctx2.lineTo(4.2, 13.6);
+    ctx2.lineTo(7.4, 20.6);
+    ctx2.lineTo(10.3, 19.2);
+    ctx2.lineTo(7.2, 12.4);
+    ctx2.lineTo(12.8, 12.2);
+    ctx2.closePath();
+    ctx2.fillStyle = "#ffffff";
+    ctx2.fill();
+    ctx2.shadowColor = "transparent";
+    ctx2.lineWidth = 1.4;
+    ctx2.strokeStyle = "rgba(20,24,34,0.9)";
+    ctx2.stroke();
+  }
+  ctx2.restore();
+}
+function easeOut(u) {
+  return 1 - (1 - u) * (1 - u);
+}
+
+// src/compose/overlays/draw.ts
+var FADE_MS = 200;
+var SCRIM_H = 210;
+function drawOverlays(ctx2, overlays, tOut, theme, profile) {
+  const bottomCaptions = overlays.filter(
+    (o) => o.kind === "caption" && tOut >= o.tStart && tOut <= o.tEnd && o.box.y > profile.height / 2
+  );
+  if (bottomCaptions.length > 0) {
+    const a = Math.max(...bottomCaptions.map((o) => captionAlpha(o, tOut)));
+    if (a > 0) {
+      const g = ctx2.createLinearGradient(0, profile.height - SCRIM_H, 0, profile.height);
+      g.addColorStop(0, "rgba(8,10,16,0)");
+      g.addColorStop(1, `rgba(8,10,16,${(0.55 * a).toFixed(3)})`);
+      ctx2.fillStyle = g;
+      ctx2.fillRect(0, profile.height - SCRIM_H, profile.width, SCRIM_H);
+    }
+  }
+  for (const o of overlays) {
+    if (tOut < o.tStart || tOut > o.tEnd) continue;
+    switch (o.kind) {
+      case "caption":
+        drawCaption(ctx2, o, tOut, theme);
+        break;
+      case "dip": {
+        const u = (tOut - o.tStart) / Math.max(1, o.tEnd - o.tStart);
+        ctx2.save();
+        ctx2.globalAlpha = o.direction === "out" ? u : 1 - u;
+        ctx2.fillStyle = theme.bg;
+        ctx2.fillRect(0, 0, profile.width, profile.height);
+        ctx2.restore();
+        break;
+      }
+      case "elapsedClock":
+        drawElapsedClock(ctx2, o.zeroAtMs, tOut, theme, profile);
+        break;
+      case "chapterLabel":
+        drawChapterLabel(ctx2, o, tOut, theme, profile);
+        break;
+      case "titleCard":
+      case "failureCard":
+        break;
+    }
+  }
+}
+function drawElapsedClock(ctx2, zeroAtMs, tOut, theme, profile) {
+  const ms = Math.max(0, tOut - zeroAtMs);
+  const s = Math.floor(ms / 1e3);
+  const label = `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}.${String(Math.floor(ms % 1e3 / 100))}`;
+  const font = "600 26px Inter SemiBold";
+  ctx2.save();
+  ctx2.font = font;
+  const textW = ctx2.measureText(label).width;
+  const padX = 16;
+  const w = textW + padX * 2 + 30;
+  const h = 44;
+  const x = profile.width - profile.safeArea.right - w;
+  const y = profile.safeArea.top;
+  ctx2.fillStyle = "rgba(18,22,31,0.82)";
+  roundRect(ctx2, x, y, w, h, 10);
+  ctx2.fill();
+  ctx2.fillStyle = "#ef4444";
+  ctx2.beginPath();
+  ctx2.arc(x + padX + 6, y + h / 2, 6, 0, Math.PI * 2);
+  ctx2.fill();
+  ctx2.fillStyle = "#ffffff";
+  ctx2.textAlign = "left";
+  ctx2.textBaseline = "middle";
+  ctx2.font = font;
+  ctx2.fillText(label, x + padX + 24, y + h / 2 + 1);
+  ctx2.restore();
+}
+function drawChapterLabel(ctx2, o, tOut, theme, profile) {
+  const alpha = clamp(Math.min((tOut - o.tStart) / 260, (o.tEnd - tOut) / 320), 0, 1);
+  if (alpha <= 0) return;
+  ctx2.save();
+  ctx2.globalAlpha = alpha;
+  const font = "700 30px Inter Bold";
+  ctx2.font = font;
+  const textW = ctx2.measureText(o.title).width;
+  const barW = textW + 96;
+  const barH = 56;
+  const x = (profile.width - barW) / 2;
+  const y = profile.stage ? profile.stage.content.y + 14 : profile.safeArea.top + 8;
+  ctx2.fillStyle = theme.accent;
+  roundRect(ctx2, x, y, barW, barH, 12);
+  ctx2.fill();
+  ctx2.fillStyle = "#ffffff";
+  ctx2.font = "600 16px Inter SemiBold";
+  ctx2.textAlign = "left";
+  ctx2.textBaseline = "middle";
+  ctx2.fillText(String(o.ordinal), x + 22, y + barH / 2 + 1);
+  ctx2.font = font;
+  ctx2.fillText(o.title, x + 48, y + barH / 2 + 1);
+  ctx2.restore();
+}
+function captionAlpha(o, tOut) {
+  return clamp(Math.min((tOut - o.tStart) / FADE_MS, (o.tEnd - tOut) / FADE_MS), 0, 1);
+}
+function drawCaption(ctx2, o, tOut, theme) {
+  const alpha = captionAlpha(o, tOut);
+  if (alpha <= 0) return;
+  ctx2.save();
+  ctx2.globalAlpha = alpha;
+  ctx2.shadowColor = "rgba(0,0,0,0.30)";
+  ctx2.shadowBlur = 18;
+  ctx2.shadowOffsetY = 4;
+  ctx2.fillStyle = theme.surface;
+  roundRect(ctx2, o.box.x, o.box.y, o.box.w, o.box.h, theme.radius);
+  ctx2.fill();
+  ctx2.shadowColor = "transparent";
+  let badgeW = 0;
+  const bx = o.box.x + 26;
+  if (o.showBadge) {
+    const badgeText = `${o.ordinal}/${o.totalSteps}`;
+    const badgeFont = `600 15px Inter SemiBold`;
+    badgeW = Math.ceil(measureText(badgeText, badgeFont)) + 20;
+    const badgeH = 26;
+    const by = o.box.y + o.box.h / 2 - badgeH / 2;
+    ctx2.fillStyle = theme.accent;
+    roundRect(ctx2, bx, by, badgeW, badgeH, 13);
+    ctx2.fill();
+    ctx2.fillStyle = "#ffffff";
+    ctx2.font = badgeFont;
+    ctx2.textBaseline = "middle";
+    ctx2.textAlign = "center";
+    ctx2.fillText(badgeText, bx + badgeW / 2, by + badgeH / 2 + 1);
+  }
+  const lineH = Math.round(o.fontPx * 1.35);
+  const textX = o.showBadge ? bx + badgeW + 14 : bx;
+  const textTop = o.box.y + (o.box.h - o.lines.length * lineH) / 2;
+  ctx2.fillStyle = theme.onSurface;
+  ctx2.font = `${o.fontPx}px Inter Medium`;
+  ctx2.textAlign = "left";
+  ctx2.textBaseline = "middle";
+  o.lines.forEach((line, i) => {
+    ctx2.fillText(line, textX, textTop + i * lineH + lineH / 2 + 1);
+  });
+  ctx2.restore();
+}
+function drawFailureCard(ctx2, card, tOut, theme, profile) {
+  const { width, height } = profile;
+  const g = ctx2.createLinearGradient(0, 0, 0, height);
+  g.addColorStop(0, "#1c1114");
+  g.addColorStop(1, "#12090b");
+  ctx2.fillStyle = g;
+  ctx2.fillRect(0, 0, width, height);
+  const t = tOut - card.tStart;
+  const a = clamp(t / 300, 0, 1);
+  ctx2.save();
+  ctx2.globalAlpha = a;
+  ctx2.fillStyle = "#ef4444";
+  roundRect(ctx2, width / 2 - 32, height / 2 - 150, 64, 8, 4);
+  ctx2.fill();
+  ctx2.fillStyle = "#ffffff";
+  ctx2.font = `52px Inter Bold`;
+  ctx2.textAlign = "center";
+  ctx2.textBaseline = "middle";
+  ctx2.fillText("Flow failed", width / 2, height / 2 - 70);
+  ctx2.fillStyle = "#fca5a5";
+  ctx2.font = `600 30px Inter SemiBold`;
+  ctx2.fillText(`at step ${card.stepRef}`, width / 2, height / 2 - 12);
+  ctx2.fillStyle = "rgba(255,255,255,0.75)";
+  ctx2.font = `24px Inter`;
+  const maxW = Math.min(1200, width - 200);
+  const words = card.message.replace(/\s+/g, " ").split(" ");
+  const lines = [];
+  let line = "";
+  for (const w of words) {
+    const probe = line ? `${line} ${w}` : w;
+    if (ctx2.measureText(probe).width > maxW && line) {
+      lines.push(line);
+      line = w;
+      if (lines.length >= 3) break;
+    } else line = probe;
+  }
+  if (lines.length < 3 && line) lines.push(line);
+  else if (line && lines.length >= 3) lines[2] = `${lines[2].slice(0, -1)}\u2026`;
+  lines.forEach((l, i) => ctx2.fillText(l, width / 2, height / 2 + 48 + i * 36));
+  ctx2.restore();
+}
+function drawTitleCard(ctx2, card, tOut, theme, profile) {
+  const { width, height } = profile;
+  const g = ctx2.createLinearGradient(0, 0, 0, height);
+  g.addColorStop(0, theme.bgSubtle);
+  g.addColorStop(1, theme.bg);
+  ctx2.fillStyle = g;
+  ctx2.fillRect(0, 0, width, height);
+  const t = tOut - card.tStart;
+  const enter = (delay) => {
+    const u = clamp((t - delay) / 380, 0, 1);
+    const e = 1 - (1 - u) * (1 - u) * (1 - u);
+    return { alpha: u, rise: 16 * (1 - e) };
+  };
+  const bar = enter(0);
+  const title = enter(130);
+  const sub = enter(240);
+  ctx2.save();
+  ctx2.globalAlpha = bar.alpha;
+  ctx2.fillStyle = theme.accent;
+  roundRect(ctx2, width / 2 - 32, height / 2 - 110 + bar.rise, 64, 8, 4);
+  ctx2.fill();
+  ctx2.globalAlpha = title.alpha;
+  ctx2.fillStyle = "#ffffff";
+  ctx2.font = `56px Inter Bold`;
+  ctx2.textAlign = "center";
+  ctx2.textBaseline = "middle";
+  ctx2.fillText(card.title, width / 2, height / 2 - 20 + title.rise);
+  if (card.subtitle) {
+    ctx2.globalAlpha = sub.alpha;
+    ctx2.fillStyle = theme.onSurfaceDim;
+    ctx2.font = `26px Inter`;
+    ctx2.fillText(card.subtitle, width / 2, height / 2 + 44 + sub.rise);
+  }
+  ctx2.restore();
+}
+
+// src/compose/render/frameStore.ts
+import sharp2 from "sharp";
+import { createCanvas as createCanvas2, ImageData } from "@napi-rs/canvas";
+var LRU_SIZE = 6;
+var FrameStore = class {
+  constructor(bundle) {
+    this.bundle = bundle;
+  }
+  bundle;
+  cache = /* @__PURE__ */ new Map();
+  /** Decoded canvas for the frame that should be on screen at capture-relative tMs. */
+  async frameForTime(tMs) {
+    const idx = frameIndexForTime(this.bundle.frames, tMs);
+    const canvas = await this.get(idx);
+    if (idx + 1 < this.bundle.frames.length) void this.get(idx + 1);
+    return canvas;
+  }
+  /**
+   * The frame at tMs plus its successor with a blend factor: the capture is ~20fps but output
+   * is 30fps, so nearest-frame playback holds each source frame in a 2-1-2-1 judder pattern.
+   * Blending adjacent frames during real motion smooths it without optical flow.
+   */
+  async framePairForTime(tMs) {
+    const idx = frameIndexForTime(this.bundle.frames, tMs);
+    const a = await this.get(idx);
+    if (idx + 1 >= this.bundle.frames.length) return { a, b: null, mix: 0, gapMs: Infinity };
+    const t0 = this.bundle.frames[idx].t;
+    const t1 = this.bundle.frames[idx + 1].t;
+    const gapMs = t1 - t0;
+    const mix = gapMs > 0 ? Math.min(1, Math.max(0, (tMs - t0) / gapMs)) : 0;
+    const b = await this.get(idx + 1);
+    return { a, b, mix, gapMs };
+  }
+  get(idx) {
+    const hit = this.cache.get(idx);
+    if (hit) {
+      this.cache.delete(idx);
+      this.cache.set(idx, hit);
+      return hit;
+    }
+    const promise = this.decode(idx);
+    this.cache.set(idx, promise);
+    while (this.cache.size > LRU_SIZE) {
+      const oldest = this.cache.keys().next().value;
+      this.cache.delete(oldest);
+    }
+    return promise;
+  }
+  async decode(idx) {
+    const { data, info } = await sharp2(framePath(this.bundle, idx)).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const canvas = createCanvas2(info.width, info.height);
+    const ctx2 = canvas.getContext("2d");
+    ctx2.putImageData(new ImageData(new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), info.width, info.height), 0, 0);
+    return canvas;
+  }
+};
+
+// src/compose/render/encoder.ts
+import { spawn as spawn2 } from "child_process";
+import { once } from "events";
+
+// src/shared/ffmpeg.ts
+import { spawn } from "child_process";
+import { createRequire as createRequire3 } from "module";
+var require2 = createRequire3(import.meta.url);
+function ffmpegPath() {
+  if (process.env.PLAYHEAD_FFMPEG) return process.env.PLAYHEAD_FFMPEG;
+  const p = require2("ffmpeg-static");
+  if (!p) throw new Error("ffmpeg-static did not provide a binary; set PLAYHEAD_FFMPEG");
+  return p;
+}
+function ffprobePath() {
+  if (process.env.PLAYHEAD_FFPROBE) return process.env.PLAYHEAD_FFPROBE;
+  const mod = require2("ffprobe-static");
+  return mod.path;
+}
+function runBinary(bin, args, stdin) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+    const out = [];
+    const err = [];
+    child.stdout.on("data", (d) => out.push(d));
+    child.stderr.on("data", (d) => err.push(d));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({
+        code: code ?? -1,
+        stdout: Buffer.concat(out).toString("utf8"),
+        stderr: Buffer.concat(err).toString("utf8")
+      });
+    });
+    if (stdin) child.stdin.end(stdin);
+    else child.stdin.end();
+  });
+}
+function runBinaryRaw(bin, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const out = [];
+    const err = [];
+    child.stdout.on("data", (d) => out.push(d));
+    child.stderr.on("data", (d) => err.push(d));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code: code ?? -1, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString("utf8") });
+    });
+  });
+}
+
+// src/compose/render/encoder.ts
+var Encoder = class {
+  child;
+  stderrTail = [];
+  exit;
+  constructor(outPath, width, height, fps) {
+    this.child = spawn2(
+      ffmpegPath(),
+      [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-f",
+        "rawvideo",
+        "-pix_fmt",
+        "rgba",
+        "-s",
+        `${width}x${height}`,
+        "-r",
+        String(fps),
+        "-i",
+        "pipe:0",
+        // A silent AAC track: some players/galleries refuse an audio-less MP4.
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=44100",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "medium",
+        "-crf",
+        "18",
+        "-pix_fmt",
+        "yuv420p",
+        "-profile:v",
+        "high",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "96k",
+        "-shortest",
+        "-movflags",
+        "+faststart",
+        "-y",
+        outPath
+      ],
+      { stdio: ["pipe", "ignore", "pipe"] }
+    );
+    this.child.stderr.on("data", (d) => {
+      this.stderrTail.push(d.toString("utf8"));
+      if (this.stderrTail.length > 40) this.stderrTail.shift();
+    });
+    this.exit = new Promise((resolve, reject) => {
+      this.child.on("error", reject);
+      this.child.on("close", (code) => resolve(code ?? -1));
+    });
+  }
+  async write(rgba) {
+    const stdin = this.child.stdin;
+    if (!stdin.writable) throw new Error(`ffmpeg closed early: ${this.stderrTail.join("")}`);
+    if (!stdin.write(rgba)) {
+      await once(stdin, "drain");
+    }
+  }
+  async finish() {
+    this.child.stdin.end();
+    const code = await this.exit;
+    if (code !== 0) {
+      throw new Error(`ffmpeg exited with code ${code}: ${this.stderrTail.join("")}`);
+    }
+  }
+};
+
+// src/compose/render/renderer.ts
+var SPOTLIGHT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
+var SPOTLIGHT_LEAD_MS = 200;
+var SPOTLIGHT_TAIL_MS = 650;
+var SPOTLIGHT_MAX_DIM = 0.34;
+async function renderVideo(bundle, manifest, outPath) {
+  registerFonts();
+  const { profile, theme } = manifest;
+  const { width, height, fps } = profile;
+  const content = stageContent(profile);
+  const plane2 = {
+    vpW: manifest.viewport.w,
+    vpH: manifest.viewport.h,
+    outW: content.w,
+    outH: content.h
+  };
+  const frameScale = bundle.manifest.frameW / manifest.viewport.w;
+  const store = new FrameStore(bundle);
+  const encoder = new Encoder(outPath, width, height, fps);
+  const canvas = createCanvas3(width, height);
+  const ctx2 = canvas.getContext("2d");
+  ctx2.imageSmoothingEnabled = true;
+  ctx2.imageSmoothingQuality = "high";
+  const spotCanvas = createCanvas3(content.w, content.h);
+  const spotCtx = spotCanvas.getContext("2d");
+  const cursorPlan = {
+    segments: manifest.cursor,
+    ripples: manifest.ripples,
+    restStart: manifest.cursor.length > 0 ? manifest.cursor[0].path[0] : { x: manifest.viewport.w / 2, y: manifest.viewport.h * 0.6 }
+  };
+  const cards = new Map(
+    manifest.overlays.filter((o) => o.kind === "titleCard").map((c) => [c.cardId, c])
+  );
+  const transitions = manifest.transitions ?? [];
+  const spotlightSteps = manifest.steps.filter(
+    (s) => SPOTLIGHT_KINDS.has(s.kind) && (s.focusRectVp ?? s.targetRectVp)
+  );
+  const start = Date.now();
+  for (let i = 0; i < manifest.totalFrames; i++) {
+    const tOut = i * 1e3 / fps;
+    const { srcAt, segment } = sampleSource(manifest.segments, tOut);
+    if (srcAt === null) {
+      const failCard = segment.kind === "card" && segment.cardId === "failure" ? manifest.overlays.find((o) => o.kind === "failureCard") : void 0;
+      const card = segment.kind === "card" ? cards.get(segment.cardId) : void 0;
+      if (failCard && failCard.kind === "failureCard") drawFailureCard(ctx2, failCard, tOut, theme, profile);
+      else if (card) drawTitleCard(ctx2, card, tOut, theme, profile);
+      else {
+        ctx2.fillStyle = theme.bg;
+        ctx2.fillRect(0, 0, width, height);
+      }
+    } else {
+      const cam = sampleCamera(manifest.camera, tOut);
+      const vis = visibleRect(cam, plane2);
+      paintStageBackdrop(ctx2, profile, theme);
+      ctx2.save();
+      if (profile.stage) {
+        paintStageCard(ctx2, profile, theme, bundle.manifest.appUrl);
+        roundRect(ctx2, content.x, content.y, content.w, content.h, 0);
+        ctx2.clip();
+      }
+      const drawSrc = (img, alpha) => {
+        ctx2.globalAlpha = alpha;
+        ctx2.drawImage(
+          img,
+          vis.x * frameScale,
+          vis.y * frameScale,
+          vis.w * frameScale,
+          vis.h * frameScale,
+          content.x,
+          content.y,
+          content.w,
+          content.h
+        );
+        ctx2.globalAlpha = 1;
+      };
+      const pair = await store.framePairForTime(srcAt);
+      if (segment.kind === "source" && pair.b && pair.mix > 0.12 && pair.gapMs < 400) {
+        drawSrc(pair.a, 1);
+        drawSrc(pair.b, pair.mix);
+      } else {
+        drawSrc(pair.a, 1);
+      }
+      const tr = transitions.find((w) => tOut >= w.tStart && tOut <= w.tEnd);
+      if (tr) {
+        const u = clamp((tOut - tr.tStart) / Math.max(1, tr.tEnd - tr.tStart), 0, 1);
+        if (u < 1) {
+          const from = await store.frameForTime(tr.srcFrom);
+          drawSrc(from, 1 - u);
+        }
+      }
+      const spot = activeSpotlight(spotlightSteps, tOut);
+      if (spot) {
+        const rect = spot.step.focusRectVp ?? spot.step.targetRectVp;
+        const proj = projectRect(rect, cam, plane2);
+        drawSpotlight(spotCtx, content, proj, spot.alpha);
+        ctx2.drawImage(spotCanvas, content.x, content.y);
+      }
+      const cursorVp = sampleCursor(cursorPlan, tOut);
+      const cursorOut = projectPoint(cursorVp, cam, plane2);
+      const rippleCenters = manifest.ripples.map((r) => {
+        const p = projectPoint({ x: r.x, y: r.y }, cam, plane2);
+        return { x: p.x + content.x, y: p.y + content.y };
+      });
+      const glyph = cursorGlyphAt(manifest.steps, tOut);
+      drawCursor(
+        ctx2,
+        { x: cursorOut.x + content.x, y: cursorOut.y + content.y },
+        cam.zoom,
+        tOut,
+        manifest.ripples,
+        rippleCenters,
+        theme,
+        plane2.outW / plane2.vpW,
+        glyph
+      );
+      ctx2.restore();
+    }
+    drawOverlays(ctx2, manifest.overlays, tOut, theme, profile);
+    await encoder.write(Buffer.from(ctx2.getImageData(0, 0, width, height).data.buffer));
+    if (i > 0 && i % 300 === 0) {
+      const fpsNow = i / ((Date.now() - start) / 1e3);
+      log.debug(`rendered ${i}/${manifest.totalFrames} frames (${fpsNow.toFixed(0)} fps)`);
+    }
+  }
+  await encoder.finish();
+  const elapsed = (Date.now() - start) / 1e3;
+  log.ok(
+    `rendered ${manifest.totalFrames} frames in ${elapsed.toFixed(1)}s (${(manifest.totalFrames / elapsed).toFixed(0)} fps) \u2192 ${outPath}`
+  );
+}
+function paintStageBackdrop(ctx2, profile, theme) {
+  const g = ctx2.createLinearGradient(0, 0, 0, profile.height);
+  g.addColorStop(0, theme.bgSubtle);
+  g.addColorStop(1, theme.bg);
+  ctx2.fillStyle = g;
+  ctx2.fillRect(0, 0, profile.width, profile.height);
+}
+function paintStageCard(ctx2, profile, theme, appUrl) {
+  const s = profile.stage;
+  const c = s.content;
+  const cardX = c.x;
+  const cardY = c.y - s.chromeH;
+  const cardW = c.w;
+  const cardH = c.h + s.chromeH;
+  ctx2.save();
+  ctx2.shadowColor = "rgba(0,0,0,0.45)";
+  ctx2.shadowBlur = 42;
+  ctx2.shadowOffsetY = 14;
+  ctx2.fillStyle = "#20242e";
+  roundRect(ctx2, cardX, cardY, cardW, cardH, s.radius);
+  ctx2.fill();
+  ctx2.restore();
+  if (s.chromeH > 0) {
+    const dotY = cardY + s.chromeH / 2;
+    const dotR = Math.max(5, Math.round(s.chromeH * 0.14));
+    const colors = ["#ff5f57", "#febc2e", "#28c840"];
+    colors.forEach((col, i) => {
+      ctx2.fillStyle = col;
+      ctx2.beginPath();
+      ctx2.arc(cardX + 24 + i * (dotR * 2 + 9), dotY, dotR, 0, Math.PI * 2);
+      ctx2.fill();
+    });
+    const url = displayUrl(appUrl);
+    const pillH = Math.round(s.chromeH * 0.62);
+    ctx2.font = `500 ${Math.round(pillH * 0.52)}px Inter Medium`;
+    const textW = ctx2.measureText(url).width;
+    const pillW = Math.min(cardW * 0.5, textW + 36);
+    const pillX = cardX + (cardW - pillW) / 2;
+    const pillY = cardY + (s.chromeH - pillH) / 2;
+    ctx2.fillStyle = "rgba(255,255,255,0.08)";
+    roundRect(ctx2, pillX, pillY, pillW, pillH, pillH / 2);
+    ctx2.fill();
+    ctx2.fillStyle = "rgba(255,255,255,0.55)";
+    ctx2.textAlign = "center";
+    ctx2.textBaseline = "middle";
+    ctx2.fillText(url, pillX + pillW / 2, pillY + pillH / 2 + 1, pillW - 24);
+  }
+}
+function displayUrl(appUrl) {
+  try {
+    const u = new URL(appUrl);
+    return u.host + (u.pathname !== "/" ? u.pathname : "");
+  } catch {
+    return appUrl;
+  }
+}
+function activeSpotlight(steps, tOut) {
+  for (const step of steps) {
+    const from = step.outBeat - SPOTLIGHT_LEAD_MS;
+    const to = step.outBeat + SPOTLIGHT_TAIL_MS;
+    if (tOut < from || tOut > to) continue;
+    const rampIn = clamp((tOut - from) / 180, 0, 1);
+    const rampOut = clamp((to - tOut) / 250, 0, 1);
+    return { step, alpha: SPOTLIGHT_MAX_DIM * Math.min(rampIn, rampOut) };
+  }
+  return null;
+}
+function drawSpotlight(sctx, content, proj, alpha) {
+  sctx.clearRect(0, 0, content.w, content.h);
+  sctx.fillStyle = `rgba(6,8,14,${alpha.toFixed(3)})`;
+  sctx.fillRect(0, 0, content.w, content.h);
+  const pad = 14;
+  sctx.save();
+  sctx.globalCompositeOperation = "destination-out";
+  sctx.shadowColor = "#ffffff";
+  sctx.shadowBlur = 30;
+  sctx.fillStyle = "#ffffff";
+  roundRect(sctx, proj.x - pad, proj.y - pad, proj.w + pad * 2, proj.h + pad * 2, 10);
+  sctx.fill();
+  sctx.restore();
+}
+function cursorGlyphAt(steps, tOut) {
+  for (const s of steps) {
+    if (s.kind === "type" && tOut >= s.outStart && tOut <= s.outEnd) return "ibeam";
+  }
+  return "arrow";
+}
+
+// src/audio/tts.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join as join5 } from "path";
+import { createHash as createHash2 } from "crypto";
+import { createRequire as createRequire4 } from "module";
+var require3 = createRequire4(import.meta.url);
+var ffprobePath2 = require3("ffprobe-static").path;
+var exec = promisify(execFile);
+var SayProvider = class {
+  constructor(voice, rate) {
+    this.voice = voice;
+    this.rate = rate;
+  }
+  voice;
+  rate;
+  name = "say";
+  async synth(text, outFile) {
+    const txt = `${outFile}.txt`;
+    await writeFile2(txt, text);
+    await exec("say", ["-v", this.voice, "-r", String(this.rate), "-f", txt, "-o", outFile]);
+  }
+};
+function providerFor(opts) {
+  const voice = opts.voice ?? "Samantha";
+  const rate = opts.rate ?? 178;
+  switch (opts.provider) {
+    case "say":
+      return { provider: new SayProvider(voice, rate), voice, rate };
+    default:
+      throw new Error(`unknown TTS provider: ${opts.provider}`);
+  }
+}
+async function probeDurationMs(file) {
+  const { stdout } = await exec(ffprobePath2, [
+    "-v",
+    "error",
+    "-show_entries",
+    "format=duration",
+    "-of",
+    "csv=p=0",
+    file
+  ]);
+  return Math.round(parseFloat(stdout.trim()) * 1e3);
+}
+async function synthesizeNarration(lines, opts, cacheDir) {
+  await mkdir2(cacheDir, { recursive: true });
+  const { provider, voice, rate } = providerFor(opts);
+  const out = /* @__PURE__ */ new Map();
+  for (const { stepRef, text } of lines) {
+    const key = createHash2("sha256").update(`${provider.name}|${voice}|${rate}|${text}`).digest("hex").slice(0, 16);
+    const file = join5(cacheDir, `${key}.aiff`);
+    if (!existsSync2(file)) await provider.synth(text, file);
+    out.set(stepRef, { stepRef, file, durationMs: await probeDurationMs(file) });
+  }
+  return out;
+}
+
+// src/audio/mux.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import { rename, mkdir as mkdir3 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { join as join6 } from "path";
+import { createRequire as createRequire5 } from "module";
+var require4 = createRequire5(import.meta.url);
+var ffmpegPath2 = require4("ffmpeg-static");
+var exec2 = promisify2(execFile2);
+async function mixAudio(videoPath, steps, durationMs, opts) {
+  const placed = (opts.narration ? steps : []).map((s) => ({ start: Math.round(s.outStart + AUDIO_LEAD_MS), clip: opts.narration.get(s.stepRef) })).filter((p) => p.clip !== void 0);
+  const beats = opts.sfxBeats ?? [];
+  const hasMusic = !!opts.music;
+  if (placed.length === 0 && beats.length === 0 && !hasMusic) return [];
+  const durSec = (durationMs / 1e3).toFixed(3);
+  const args = ["-y", "-loglevel", "error", "-i", videoPath];
+  const inputs = [];
+  const filters = [];
+  let inputIdx = 1;
+  args.push("-f", "lavfi", "-t", durSec, "-i", "anullsrc=r=44100:cl=stereo");
+  const baseIdx = inputIdx++;
+  inputs.push(`[${baseIdx}]`);
+  let voiceBus = null;
+  if (placed.length > 0) {
+    const labels = [];
+    placed.forEach((p, i) => {
+      args.push("-i", p.clip.file);
+      const idx = inputIdx++;
+      filters.push(
+        `[${idx}]aformat=sample_rates=44100:channel_layouts=stereo,adelay=${p.start}|${p.start}[v${i}]`
+      );
+      labels.push(`[v${i}]`);
+    });
+    filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0:duration=longest[voice]`);
+    voiceBus = "[voice]";
+  }
+  if (beats.length > 0) {
+    const click = await ensureClickSample(opts.cacheDir);
+    args.push("-i", click);
+    const idx = inputIdx++;
+    const splits = beats.map((_, i) => `[c${i}]`).join("");
+    filters.push(`[${idx}]aformat=sample_rates=44100:channel_layouts=stereo,asplit=${beats.length}${splits}`);
+    const labels = [];
+    beats.forEach((b, i) => {
+      const at = Math.max(0, Math.round(b.tOut));
+      filters.push(`[c${i}]adelay=${at}|${at}[ck${i}]`);
+      labels.push(`[ck${i}]`);
+    });
+    filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0:duration=longest[sfx]`);
+    inputs.push("[sfx]");
+  }
+  if (opts.music) {
+    args.push("-stream_loop", "-1", "-i", opts.music.file);
+    const idx = inputIdx++;
+    const fadeStart = Math.max(0, durationMs / 1e3 - 1.8).toFixed(2);
+    filters.push(
+      `[${idx}]aformat=sample_rates=44100:channel_layouts=stereo,atrim=0:${durSec},volume=${opts.music.gainDb}dB,afade=t=out:st=${fadeStart}:d=1.8[mraw]`
+    );
+    if (voiceBus) {
+      filters.push(`${voiceBus}asplit=2[vmain][vkey]`);
+      filters.push(`[mraw][vkey]sidechaincompress=threshold=0.02:ratio=8:attack=40:release=400[mduck]`);
+      inputs.push("[mduck]", "[vmain]");
+      voiceBus = null;
+    } else {
+      inputs.push("[mraw]");
+    }
+  }
+  if (voiceBus) inputs.push(voiceBus);
+  filters.push(
+    `${inputs.join("")}amix=inputs=${inputs.length}:normalize=0:duration=longest,loudnorm=I=-16:TP=-1.5:LRA=11[mix]`
+  );
+  const tmp = videoPath.replace(/\.mp4$/, ".audio.tmp.mp4");
+  args.push(
+    "-filter_complex",
+    filters.join(";"),
+    "-map",
+    "0:v:0",
+    "-map",
+    "[mix]",
+    "-c:v",
+    "copy",
+    "-c:a",
+    "aac",
+    "-b:a",
+    "160k",
+    "-shortest",
+    "-movflags",
+    "+faststart",
+    tmp
+  );
+  await exec2(ffmpegPath2, args, { maxBuffer: 1 << 24 });
+  await rename(tmp, videoPath);
+  return placed.map((p) => ({ stepRef: p.clip.stepRef, tStart: p.start, durMs: p.clip.durationMs }));
+}
+async function ensureClickSample(cacheDir) {
+  await mkdir3(cacheDir, { recursive: true });
+  const file = join6(cacheDir, "click.wav");
+  if (existsSync3(file)) return file;
+  await exec2(ffmpegPath2, [
+    "-y",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    "sine=frequency=1250:duration=0.05",
+    "-f",
+    "lavfi",
+    "-i",
+    "sine=frequency=2500:duration=0.03",
+    "-filter_complex",
+    "[0]volume=0.5[a];[1]volume=0.22[b];[a][b]amix=inputs=2:normalize=0,afade=t=in:d=0.004,afade=t=out:st=0.014:d=0.036,aformat=sample_rates=44100:channel_layouts=stereo",
+    file
+  ]);
+  return file;
+}
+
+// src/compose/index.ts
+function specStepTexts(spec) {
+  const map = /* @__PURE__ */ new Map();
+  for (const a of flattenSteps(spec)) {
+    const s = a.step;
+    if (s.caption || s.narration) {
+      map.set(`${a.sceneId}/${a.stepIndex}`, {
+        ...s.caption ? { caption: s.caption } : {},
+        ...s.narration ? { narration: s.narration } : {}
+      });
+    }
+  }
+  return map;
+}
+function plan(bundle, spec, theme, profile, audioMs) {
+  registerFonts();
+  const resolvedTheme = theme ?? resolveTheme(spec);
+  const kind = kindProfile(spec.output.kind);
+  let prof = profile ?? profileForAspect(spec.output.aspect, resolveResolution(spec), spec.output.fps);
+  if (kind.stage && !prof.stage) prof = withStage(prof, true);
+  const diagnostics = { overflows: [], cameraFallbacks: [], clockWarnings: [] };
+  const cfg = pacingConfig(spec.output.pacing ?? kind.pacing, kind);
+  const dwell = spec.output.dwellScale;
+  if (dwell && dwell !== 1) {
+    cfg.minStepMs *= dwell;
+    cfg.outroMs *= dwell;
+    for (const k of Object.keys(cfg.holds)) cfg.holds[k] *= dwell;
+  }
+  const timeline = buildTimeline(bundle.events, cfg, audioMs);
+  const END_CARD_MS = 2400;
+  if (spec.output.endCard) {
+    const endStart = timeline.durationMs;
+    timeline.segments.push({ kind: "card", outStart: endStart, outEnd: endStart + END_CARD_MS, cardId: "end" });
+    timeline.durationMs += END_CARD_MS;
+  }
+  const FAILURE_CARD_MS = 3200;
+  if (bundle.manifest.partial && bundle.manifest.failure) {
+    const failStart = timeline.durationMs;
+    timeline.segments.push({ kind: "card", outStart: failStart, outEnd: failStart + FAILURE_CARD_MS, cardId: "failure" });
+    timeline.durationMs += FAILURE_CARD_MS;
+  }
+  for (const step of timeline.steps) {
+    const hasFrame = bundle.frames.some((f) => f.t >= step.srcAction && f.t <= step.srcAction + 150);
+    if (!hasFrame && step.kind !== "wait" && step.kind !== "expect") {
+      diagnostics.clockWarnings.push(`${step.stepRef}: no source frame within 150ms after the action`);
+    }
+  }
+  const camera = planCamera(timeline.steps, bundle.events, prof, timeline.durationMs, {
+    emphasis: kind.cameraEmphasis
+  });
+  diagnostics.cameraFallbacks.push(...camera.fallbacks);
+  const cursor = planCursor(timeline.steps, bundle.events);
+  const transitions = [];
+  for (let i = 1; i < timeline.steps.length; i++) {
+    const prev = timeline.steps[i - 1];
+    const cur = timeline.steps[i];
+    if (cur.sceneId !== prev.sceneId) {
+      const tStart = cur.outStart;
+      transitions.push({ tStart, tEnd: tStart + 280, srcFrom: Math.max(0, prev.srcSettled - 1) });
+    }
+  }
+  const subtitle = spec.subtitle ?? safeHost(bundle.manifest.appUrl);
+  const sceneTitles = new Map(
+    spec.scenes.filter((s) => s.title).map((s) => [s.id, s.title])
+  );
+  const overlays = buildOverlays(
+    timeline.steps,
+    bundle.events,
+    resolvedTheme,
+    prof,
+    spec.title,
+    subtitle,
+    cfg.titleCardMs,
+    diagnostics,
+    kind,
+    sceneTitles,
+    camera.keyframes,
+    specStepTexts(spec)
+  );
+  if (spec.output.endCard && !bundle.manifest.partial) {
+    const endStart = timeline.durationMs - END_CARD_MS;
+    overlays.push({ kind: "dip", tStart: endStart - 350, tEnd: endStart, direction: "out" });
+    overlays.push({
+      kind: "titleCard",
+      cardId: "end",
+      title: spec.output.endCard.title,
+      ...spec.output.endCard.subtitle ? { subtitle: spec.output.endCard.subtitle } : {},
+      tStart: endStart,
+      tEnd: timeline.durationMs
+    });
+  }
+  if (bundle.manifest.partial && bundle.manifest.failure) {
+    const failStart = timeline.durationMs - FAILURE_CARD_MS;
+    overlays.push({ kind: "dip", tStart: failStart - 300, tEnd: failStart, direction: "out" });
+    overlays.push({
+      kind: "failureCard",
+      stepRef: bundle.manifest.failure.stepRef,
+      message: bundle.manifest.failure.message,
+      tStart: failStart,
+      tEnd: timeline.durationMs
+    });
+  }
+  const totalFrames = Math.ceil(timeline.durationMs / 1e3 * prof.fps);
+  return {
+    schema: "playhead/compose@1",
+    profile: prof,
+    viewport: bundle.manifest.viewport,
+    durationMs: timeline.durationMs,
+    totalFrames,
+    segments: timeline.segments,
+    camera: camera.keyframes,
+    cursor: cursor.segments,
+    ripples: cursor.ripples,
+    overlays,
+    ...transitions.length > 0 ? { transitions } : {},
+    steps: timeline.steps,
+    theme: resolvedTheme,
+    diagnostics,
+    bundleHashes: bundle.manifest.hashes
+  };
+}
+async function compose(bundle, spec, opts) {
+  const audioCfg = spec.output.audio;
+  let narration;
+  let audioMs;
+  if (audioCfg && audioCfg.narration === "tts") {
+    const texts = specStepTexts(spec);
+    const lines = actionEvents(bundle.events).map((e) => {
+      const ref = `${e.sceneId}/${e.stepIndex}`;
+      return { stepRef: ref, text: writeNarration(e, texts.get(ref)) };
+    }).filter((l) => typeof l.text === "string" && l.text.length > 0);
+    log.info(`synthesizing narration: ${lines.length} lines (${audioCfg.provider}, voice ${audioCfg.voice ?? "Samantha"})`);
+    try {
+      narration = await synthesizeNarration(lines, audioCfg, join7(opts.outDir, "narration"));
+      audioMs = new Map([...narration].map(([k, v]) => [k, v.durationMs]));
+    } catch (e) {
+      log.warn(`narration unavailable on this host (${e.message.split("\n")[0]}) \u2014 rendering WITHOUT voice`);
+      narration = void 0;
+      audioMs = void 0;
+    }
+  }
+  const manifest = plan(bundle, spec, opts.theme, opts.profile, audioMs);
+  for (const w of manifest.diagnostics.clockWarnings) log.warn(w);
+  for (const f of manifest.diagnostics.cameraFallbacks) log.warn(f);
+  const videoPath = join7(opts.outDir, opts.fileName ?? "out.mp4");
+  log.info(
+    `composing ${(manifest.durationMs / 1e3).toFixed(1)}s (${manifest.totalFrames} frames @ ${manifest.profile.fps}fps, ${manifest.profile.width}x${manifest.profile.height})`
+  );
+  await renderVideo(bundle, manifest, videoPath);
+  if (audioCfg && (narration || audioCfg.sfx || audioCfg.music)) {
+    const clips = await mixAudio(videoPath, manifest.steps, manifest.durationMs, {
+      ...narration ? { narration } : {},
+      ...audioCfg.sfx ? { sfxBeats: manifest.ripples } : {},
+      ...audioCfg.music ? { music: audioCfg.music } : {},
+      cacheDir: join7(opts.outDir, "narration")
+    });
+    if (narration) {
+      manifest.audio = {
+        narrated: true,
+        provider: audioCfg.provider,
+        voice: audioCfg.voice ?? "Samantha",
+        lines: clips.length,
+        clips
+      };
+    }
+    log.info(
+      `\u2713 audio: ${clips.length} narration line(s)${audioCfg.sfx ? `, ${manifest.ripples.length} click(s)` : ""}${audioCfg.music ? ", music bed" : ""} \u2192 ${videoPath}`
+    );
+  }
+  manifest.videoSha256 = await sha256File(videoPath);
+  const manifestPath = join7(opts.outDir, "compose-manifest.json");
+  await writeFile3(manifestPath, JSON.stringify(manifest, null, 2));
+  return { videoPath, manifestPath, manifest };
+}
+async function renderFromManifest(bundle, manifest, videoPath) {
+  await renderVideo(bundle, manifest, videoPath);
+}
+function safeHost(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+// src/verify/runner.ts
+import { join as join8 } from "path";
+import { mkdir as mkdir4, writeFile as writeFile5, readFile as readFile4 } from "fs/promises";
+
+// src/verify/media.ts
+import sharp3 from "sharp";
+async function extractGrayFrames(videoPath, fps, w, h) {
+  const res = await runBinaryRaw(ffmpegPath(), [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-i",
+    videoPath,
+    "-vf",
+    `fps=${fps},scale=${w}:${h}`,
+    "-f",
+    "rawvideo",
+    "-pix_fmt",
+    "gray",
+    "pipe:1"
+  ]);
+  if (res.code !== 0) throw new Error(`frame extraction failed: ${res.stderr}`);
+  const frameSize = w * h;
+  const frames = [];
+  for (let off = 0; off + frameSize <= res.stdout.length; off += frameSize) {
+    frames.push(res.stdout.subarray(off, off + frameSize));
+  }
+  return { frames, intervalMs: 1e3 / fps };
+}
+async function extractFrameAt(videoPath, tMs) {
+  const res = await runBinaryRaw(ffmpegPath(), [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-ss",
+    (Math.max(0, tMs) / 1e3).toFixed(3),
+    "-i",
+    videoPath,
+    "-frames:v",
+    "1",
+    "-f",
+    "image2pipe",
+    "-vcodec",
+    "png",
+    "pipe:1"
+  ]);
+  if (res.code !== 0 || res.stdout.length === 0) {
+    throw new Error(`could not extract frame at ${tMs}ms: ${res.stderr}`);
+  }
+  return res.stdout;
+}
+async function probeVideo(videoPath) {
+  const res = await runBinary(ffprobePath(), [
+    "-v",
+    "error",
+    "-print_format",
+    "json",
+    "-show_format",
+    "-show_streams",
+    videoPath
+  ]);
+  if (res.code !== 0) throw new Error(`ffprobe failed: ${res.stderr}`);
+  const json = JSON.parse(res.stdout);
+  const v = json.streams?.find((s) => s.codec_type === "video");
+  if (!v) throw new Error("no video stream found");
+  const [num, den] = v.avg_frame_rate.split("/").map(Number);
+  return {
+    codec: v.codec_name,
+    width: v.width,
+    height: v.height,
+    durationSec: Number(json.format?.duration ?? 0),
+    fps: den ? num / den : 0
+  };
+}
+function meanAbsDiff(a, b) {
+  const n = Math.min(a.length, b.length);
+  let sum = 0;
+  for (let i = 0; i < n; i++) sum += Math.abs(a[i] - b[i]);
+  return sum / n;
+}
+function variance(a) {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += a[i];
+  const mean = sum / a.length;
+  let v = 0;
+  for (let i = 0; i < a.length; i++) v += (a[i] - mean) ** 2;
+  return v / a.length;
+}
+async function sourceFrameGray(bundle, tMs, width) {
+  const idx = frameIndexForTime(bundle.frames, tMs);
+  const { data, info } = await sharp3(framePath(bundle, idx)).resize({ width }).grayscale().raw().toBuffer({ resolveWithObject: true });
+  return { data, w: info.width, h: info.height, frameT: bundle.frames[idx].t };
+}
+async function sourceRegionGray(bundle, tMs, region, preferAfter = false, color = false) {
+  let idx = frameIndexForTime(bundle.frames, tMs);
+  if (preferAfter && idx + 1 < bundle.frames.length && bundle.frames[idx].t < tMs) idx += 1;
+  const meta = await sharp3(framePath(bundle, idx)).metadata();
+  const fw = meta.width ?? 0;
+  const fh = meta.height ?? 0;
+  const x = Math.max(0, Math.round(region.x));
+  const y = Math.max(0, Math.round(region.y));
+  const w = Math.min(Math.round(region.w), fw - x);
+  const h = Math.min(Math.round(region.h), fh - y);
+  if (w < 4 || h < 4) return null;
+  let img = sharp3(framePath(bundle, idx)).extract({ left: x, top: y, width: w, height: h });
+  if (!color) img = img.grayscale();
+  const { data } = await img.raw().toBuffer({ resolveWithObject: true });
+  return data;
+}
+async function regionGray48(input, rect) {
+  try {
+    const img = sharp3(input);
+    const meta = await img.metadata();
+    const W = meta.width ?? 0;
+    const H = meta.height ?? 0;
+    const left = Math.max(0, Math.round(rect.x));
+    const top = Math.max(0, Math.round(rect.y));
+    const width = Math.min(W - left, Math.round(rect.w));
+    const height = Math.min(H - top, Math.round(rect.h));
+    if (width < 8 || height < 8) return null;
+    return await sharp3(input).extract({ left, top, width, height }).grayscale().resize(48, 48, { fit: "fill" }).raw().toBuffer();
+  } catch {
+    return null;
+  }
+}
+function normalizedCorrelation(a, b) {
+  const n = Math.min(a.length, b.length);
+  let ma = 0;
+  let mb = 0;
+  for (let i = 0; i < n; i++) {
+    ma += a[i];
+    mb += b[i];
+  }
+  ma /= n;
+  mb /= n;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < n; i++) {
+    const xa = a[i] - ma;
+    const xb = b[i] - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  if (da < 1e-6 || db < 1e-6) return da < 1e-6 && db < 1e-6 ? 1 : 0;
+  return num / Math.sqrt(da * db);
+}
+
+// src/verify/checks.ts
+var EFFECT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "type", "select", "goto"]);
+var CLICK_KINDS2 = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
+function plane(ctx2) {
+  const content = stageContent(ctx2.manifest.profile);
+  return {
+    vpW: ctx2.manifest.viewport.w,
+    vpH: ctx2.manifest.viewport.h,
+    outW: content.w,
+    outH: content.h
+  };
+}
+async function checkTargetInFrame(ctx2) {
+  const p = plane(ctx2);
+  const frame = { x: 0, y: 0, w: p.outW, h: p.outH };
+  const evidence = [];
+  let checked = 0;
+  let minHeight = Infinity;
+  const captions = ctx2.manifest.overlays.filter((o) => o.kind === "caption");
+  for (const step of ctx2.manifest.steps) {
+    const handoff = actReactWindows(step);
+    const rect = step.focusRectVp ?? step.targetRectVp;
+    const windows = handoff ? [handoff.act, handoff.react] : rect ? [{ rect, from: Math.max(step.outStart, step.outBeat - 60), to: step.outEnd }] : [];
+    if (windows.length === 0) continue;
+    checked += 1;
+    for (const w of windows)
+      for (let t = w.from; t <= w.to; t += 100) {
+        const rect2 = w.rect;
+        const cam = sampleCamera(ctx2.manifest.camera, t);
+        const proj = projectRect(rect2, cam, p);
+        minHeight = Math.min(minHeight, proj.h);
+        if (!rectContains(frame, proj, 2)) {
+          evidence.push({ stepRef: step.stepRef, t, note: `target cropped by frame edge (projected ${fmtRect(proj)})` });
+          break;
+        }
+        if (step.kind !== "scroll" && step.focus !== "wide" && proj.h < 28) {
+          evidence.push({ stepRef: step.stepRef, t, note: `target renders too small (${proj.h.toFixed(0)}px high)` });
+          break;
+        }
+        const content = stageContent(ctx2.manifest.profile);
+        const projFrame = { x: proj.x + content.x, y: proj.y + content.y, w: proj.w, h: proj.h };
+        const cap = captions.find((c) => t >= c.tStart + 150 && t <= c.tEnd - 150 && rectsOverlap(c.box, projFrame));
+        if (cap) {
+          evidence.push({ stepRef: step.stepRef, t, note: `caption "${cap.text}" overlaps the target` });
+          break;
+        }
+      }
+  }
+  if (checked === 0) return { id: "target-in-frame", status: "skip", details: "no steps with targets" };
+  return evidence.length > 0 ? { id: "target-in-frame", status: "fail", details: `${evidence.length}/${checked} targets violate framing`, evidence } : {
+    id: "target-in-frame",
+    status: "pass",
+    details: `${checked}/${checked} targets fully framed, min rendered height ${minHeight === Infinity ? "\u2014" : minHeight.toFixed(0) + "px"}`
+  };
+}
+async function checkCursorOnTarget(ctx2) {
+  const cursorPlan = {
+    segments: ctx2.manifest.cursor,
+    ripples: ctx2.manifest.ripples,
+    restStart: { x: ctx2.manifest.viewport.w / 2, y: ctx2.manifest.viewport.h * 0.6 }
+  };
+  const evidence = [];
+  let checked = 0;
+  for (const step of ctx2.manifest.steps) {
+    if (!CLICK_KINDS2.has(step.kind) || !step.targetRectVp) continue;
+    checked += 1;
+    const pos = sampleCursor(cursorPlan, step.outBeat);
+    const r = step.targetRectVp;
+    const pad = 4;
+    const inside = pos.x >= r.x - pad && pos.x <= r.x + r.w + pad && pos.y >= r.y - pad && pos.y <= r.y + r.h + pad;
+    if (!inside) {
+      evidence.push({
+        stepRef: step.stepRef,
+        t: step.outBeat,
+        note: `cursor at (${pos.x.toFixed(0)},${pos.y.toFixed(0)}) missed target ${fmtRect(r)}`
+      });
+    }
+  }
+  if (checked === 0) return { id: "cursor-on-target", status: "skip", details: "no click steps" };
+  return evidence.length > 0 ? { id: "cursor-on-target", status: "fail", details: `${evidence.length}/${checked} clicks miss their target`, evidence } : { id: "cursor-on-target", status: "pass", details: `${checked}/${checked} clicks land on target` };
+}
+async function checkActionEffect(ctx2) {
+  const evidence = [];
+  const inconclusive = [];
+  let checked = 0;
+  const frameScale = ctx2.bundle.manifest.frameW / ctx2.manifest.viewport.w;
+  const lastFrameT = ctx2.bundle.frames[ctx2.bundle.frames.length - 1].t;
+  const steps = ctx2.manifest.steps;
+  let skippedMasked = 0;
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!EFFECT_KINDS.has(step.kind)) continue;
+    if (step.masked) {
+      skippedMasked += 1;
+      continue;
+    }
+    checked += 1;
+    const nextAction = i + 1 < steps.length ? steps[i + 1].srcAction : lastFrameT;
+    const afterT = Math.max(step.srcSettled, nextAction - 60);
+    const before = await sourceFrameGray(ctx2.bundle, step.srcAction - 40, 320);
+    const after = await sourceFrameGray(ctx2.bundle, afterT, 320);
+    if (after.frameT <= before.frameT) {
+      inconclusive.push({ stepRef: step.stepRef, note: "no post-action frame captured to compare" });
+      continue;
+    }
+    if (before.frameT >= step.srcAction) {
+      inconclusive.push({ stepRef: step.stepRef, note: "no pre-action frame captured to compare" });
+      continue;
+    }
+    const overall = meanAbsDiff(before.data, after.data);
+    let regionDiff = 0;
+    const regions = [step.targetRectVp, step.focusRectVp].filter((r) => !!r);
+    for (const r of regions) {
+      const region = scaleRect(r, frameScale);
+      const [ra, rb] = await Promise.all([
+        sourceRegionGray(ctx2.bundle, step.srcAction - 40, region, false, true),
+        sourceRegionGray(ctx2.bundle, afterT, region, true, true)
+      ]);
+      if (ra && rb && ra.length === rb.length) regionDiff = Math.max(regionDiff, meanAbsDiff(ra, rb));
+    }
+    if (overall < 0.5 && regionDiff < 2) {
+      evidence.push({
+        stepRef: step.stepRef,
+        t: step.outBeat,
+        note: `no visible effect (frame diff ${overall.toFixed(2)}, target diff ${regionDiff.toFixed(2)})`
+      });
+    }
+  }
+  if (checked === 0) {
+    return {
+      id: "action-effect",
+      status: "skip",
+      details: skippedMasked > 0 ? `no verifiable actions (${skippedMasked} masked)` : "no effectful actions"
+    };
+  }
+  const maskedNote = skippedMasked > 0 ? ` (${skippedMasked} masked skipped)` : "";
+  const inconcNote = inconclusive.length > 0 ? `, ${inconclusive.length} inconclusive (capture gap)` : "";
+  if (evidence.length > 0) {
+    return {
+      id: "action-effect",
+      status: "fail",
+      details: `${evidence.length}/${checked} actions show no visible effect${maskedNote}${inconcNote}`,
+      evidence: [...evidence, ...inconclusive]
+    };
+  }
+  if (inconclusive.length > 0) {
+    return {
+      id: "action-effect",
+      status: "warn",
+      details: `${checked - inconclusive.length}/${checked} actions visibly effective; ${inconclusive.length} unverified (capture gap)${maskedNote}`,
+      evidence: inconclusive
+    };
+  }
+  return { id: "action-effect", status: "pass", details: `${checked}/${checked} actions visibly effective${maskedNote}` };
+}
+async function checkFrozenBlank(ctx2) {
+  const { frames, intervalMs } = await extractGrayFrames(ctx2.videoPath, 2, 320, 180);
+  if (frames.length < 2) return { id: "frozen-blank", status: "fail", details: "could not decode output frames" };
+  const evidence = [];
+  const dips = ctx2.manifest.overlays.filter((o) => o.kind === "dip");
+  const inTransition = (t) => segmentAt(ctx2.manifest.segments, t).kind === "card" || dips.some((d) => t >= d.tStart - 60 && t <= d.tEnd + 60);
+  for (let i = 0; i < frames.length; i++) {
+    const t = i * intervalMs;
+    if (inTransition(t)) continue;
+    if (variance(frames[i]) < 2) {
+      evidence.push({ t, note: `blank frame at ${(t / 1e3).toFixed(1)}s` });
+    }
+  }
+  const maskedWindows = ctx2.manifest.steps.filter((s) => s.masked).map((s) => ({ start: s.outStart, end: s.outEnd }));
+  const inMaskedWindow = (t0, t1) => maskedWindows.some((w) => t1 >= w.start - 200 && t0 <= w.end + 200);
+  const lastBeat = ctx2.manifest.steps.reduce((m, s) => Math.max(m, s.outBeat), 0);
+  const narrated = !!ctx2.manifest.audio?.narrated;
+  const clipWindows = (ctx2.manifest.audio?.clips ?? []).map((c) => ({
+    start: c.tStart - 300,
+    end: c.tStart + c.durMs + 1200
+    // clip + the tail-and-extend hold pacing grants it
+  }));
+  const voiceCovers = (t0, t1) => clipWindows.length === 0 ? narrated : clipWindows.some((w) => t0 >= w.start && t1 <= w.end);
+  let runStart = 0;
+  for (let i = 1; i <= frames.length; i++) {
+    const identical = i < frames.length && meanAbsDiff(frames[i], frames[i - 1]) < 0.15;
+    if (!identical) {
+      const runMs = (i - 1 - runStart) * intervalMs;
+      const t0 = runStart * intervalMs;
+      const t1 = (i - 1) * intervalMs;
+      const inFinalHold = t0 >= lastBeat - 800;
+      if (runMs > 2e3 && !inMaskedWindow(t0, t1) && !inFinalHold && !(narrated && voiceCovers(t0, t1))) {
+        const beatsInside = ctx2.manifest.steps.filter((s) => s.outBeat > t0 + 200 && s.outBeat < t1 - 200);
+        if (beatsInside.length >= 1 && runMs > 2500) {
+          evidence.push({
+            t: t0,
+            note: `frozen footage ${(runMs / 1e3).toFixed(1)}s spanning ${beatsInside.length} action beat(s)`
+          });
+        } else if (runMs > 8e3) {
+          evidence.push({ t: t0, note: `frozen footage for ${(runMs / 1e3).toFixed(1)}s` });
+        }
+      }
+      runStart = i;
+    }
+  }
+  return evidence.length > 0 ? { id: "frozen-blank", status: "fail", details: `${evidence.length} frozen/blank issue(s)`, evidence } : { id: "frozen-blank", status: "pass", details: `${frames.length} sampled output frames live and non-blank` };
+}
+async function checkCaptions(ctx2) {
+  const evidence = [];
+  let warned = 0;
+  let count = 0;
+  const out = { x: 0, y: 0, w: ctx2.manifest.profile.width, h: ctx2.manifest.profile.height };
+  for (const o of ctx2.manifest.overlays) {
+    if (o.kind !== "caption") continue;
+    count += 1;
+    if (o.truncated) evidence.push({ stepRef: o.stepRef, note: `caption truncated: "${o.text}"` });
+    if (o.fontPx < ctx2.manifest.theme.captionMinFontPx)
+      evidence.push({ stepRef: o.stepRef, note: `caption font ${o.fontPx}px below minimum` });
+    if (!rectContains(out, o.box, 24)) evidence.push({ stepRef: o.stepRef, note: "caption box outside safe bounds" });
+    if (o.shrunk && !o.truncated) warned += 1;
+  }
+  if (count === 0) return { id: "captions", status: "skip", details: "no captions" };
+  if (evidence.length > 0)
+    return { id: "captions", status: "fail", details: `${evidence.length} caption problem(s)`, evidence };
+  return warned > 0 ? { id: "captions", status: "warn", details: `${count} captions ok, ${warned} auto-shrunk to fit` } : { id: "captions", status: "pass", details: `${count} captions fit at full size` };
+}
+async function checkPacing(ctx2) {
+  const evidence = [];
+  for (const step of ctx2.manifest.steps) {
+    const dur = step.outEnd - step.outStart;
+    if (step.kind !== "wait" && dur < 1200) {
+      evidence.push({ stepRef: step.stepRef, note: `step on screen only ${(dur / 1e3).toFixed(1)}s` });
+    }
+  }
+  const total = ctx2.manifest.durationMs;
+  if (total < 3e3) evidence.push({ note: `video too short (${(total / 1e3).toFixed(1)}s)` });
+  if (total > 15 * 6e4) evidence.push({ note: `video too long (${(total / 6e4).toFixed(1)}min)` });
+  return evidence.length > 0 ? { id: "pacing", status: "fail", details: `${evidence.length} pacing violation(s)`, evidence } : { id: "pacing", status: "pass", details: `${ctx2.manifest.steps.length} steps paced \u22651.2s, total ${(total / 1e3).toFixed(1)}s` };
+}
+async function checkAudio(ctx2) {
+  if (!ctx2.manifest.audio?.narrated) return { id: "audio", status: "skip", details: "no narration" };
+  const evidence = [];
+  const probe = await runBinary(ffprobePath(), [
+    "-v",
+    "error",
+    "-select_streams",
+    "a",
+    "-show_entries",
+    "stream=codec_name,duration",
+    "-of",
+    "json",
+    ctx2.videoPath
+  ]);
+  const stream = JSON.parse(probe.stdout).streams?.[0];
+  if (!stream) return { id: "audio", status: "fail", details: "narration requested but the output has no audio stream" };
+  const vd = await runBinary(ffmpegPath(), ["-hide_banner", "-nostats", "-i", ctx2.videoPath, "-af", "volumedetect", "-f", "null", "-"]);
+  const mean = Number(/mean_volume:\s*(-?[\d.]+) dB/.exec(vd.stderr)?.[1] ?? "0");
+  if (mean <= -70) evidence.push({ note: `narration track is effectively silent (mean ${mean} dB)` });
+  const expectSec = ctx2.manifest.durationMs / 1e3;
+  const aDur = Number(stream.duration ?? 0);
+  if (aDur > 0 && Math.abs(aDur - expectSec) > Math.max(0.5, expectSec * 0.05))
+    evidence.push({ note: `audio ${aDur.toFixed(1)}s vs video ${expectSec.toFixed(1)}s` });
+  const clips = ctx2.manifest.audio.clips ?? [];
+  let loudness = null;
+  if (clips.length > 0) {
+    const det = await runBinary(ffmpegPath(), [
+      "-hide_banner",
+      "-nostats",
+      "-i",
+      ctx2.videoPath,
+      "-af",
+      "silencedetect=noise=-40dB:d=0.35,ebur128",
+      "-f",
+      "null",
+      "-"
+    ]);
+    const silences = [];
+    let open = null;
+    for (const m of det.stderr.matchAll(/silence_(start|end): ([\d.]+)/g)) {
+      if (m[1] === "start") open = parseFloat(m[2]) * 1e3;
+      else if (open !== null) {
+        silences.push({ start: open, end: parseFloat(m[2]) * 1e3 });
+        open = null;
+      }
+    }
+    if (open !== null) silences.push({ start: open, end: ctx2.manifest.durationMs });
+    for (const clip of clips) {
+      const w0 = clip.tStart;
+      const w1 = clip.tStart + clip.durMs;
+      let silent = 0;
+      for (const s of silences) {
+        silent += Math.max(0, Math.min(w1, s.end) - Math.max(w0, s.start));
+      }
+      const voiced = (w1 - w0 - silent) / Math.max(1, w1 - w0);
+      if (voiced < 0.45) {
+        evidence.push({
+          stepRef: clip.stepRef,
+          t: clip.tStart,
+          note: `narration line is mostly silent in its own window (${(voiced * 100).toFixed(0)}% voiced) \u2014 audio/video drift`
+        });
+      }
+    }
+    const lus = [...det.stderr.matchAll(/I:\s+(-?[\d.]+)\s+LUFS/g)];
+    const lu = lus[lus.length - 1];
+    if (lu) {
+      loudness = parseFloat(lu[1]);
+      if (loudness < -20 || loudness > -12) {
+        evidence.push({ note: `integrated loudness ${loudness.toFixed(1)} LUFS is outside the -16\xB14 target` });
+      }
+    }
+  }
+  return evidence.length ? { id: "audio", status: "fail", details: `${evidence.length} narration problem(s)`, evidence } : {
+    id: "audio",
+    status: "pass",
+    details: `${ctx2.manifest.audio.lines} lines audible in their windows, ${stream.codec_name}${loudness !== null ? `, ${loudness.toFixed(1)} LUFS` : `, mean ${mean.toFixed(0)} dB`}`
+  };
+}
+async function checkEncode(ctx2) {
+  let info;
+  try {
+    info = await probeVideo(ctx2.videoPath);
+  } catch (e) {
+    return { id: "encode", status: "fail", details: `unreadable video: ${e.message}` };
+  }
+  const problems = [];
+  if (info.codec !== "h264") problems.push(`codec ${info.codec}`);
+  if (info.width !== ctx2.manifest.profile.width || info.height !== ctx2.manifest.profile.height)
+    problems.push(`resolution ${info.width}x${info.height}`);
+  const expectSec = ctx2.manifest.durationMs / 1e3;
+  if (Math.abs(info.durationSec - expectSec) > Math.max(0.5, expectSec * 0.03))
+    problems.push(`duration ${info.durationSec.toFixed(1)}s vs planned ${expectSec.toFixed(1)}s`);
+  if (Math.abs(info.fps - ctx2.manifest.profile.fps) > 0.5) problems.push(`fps ${info.fps.toFixed(2)}`);
+  return problems.length > 0 ? { id: "encode", status: "fail", details: problems.join("; ") } : {
+    id: "encode",
+    status: "pass",
+    details: `h264 ${info.width}x${info.height} @ ${info.fps.toFixed(0)}fps, ${info.durationSec.toFixed(1)}s`
+  };
+}
+async function checkMasks(ctx2) {
+  const evidence = [];
+  const frameScale = ctx2.bundle.manifest.frameW / ctx2.manifest.viewport.w;
+  const buckets = /* @__PURE__ */ new Map();
+  const blurKeys = /* @__PURE__ */ new Set();
+  for (const sample of ctx2.bundle.maskSamples) {
+    for (const rect of sample.rects) {
+      const posKey = `${Math.round(rect.x / 24)}:${Math.round(rect.y / 24)}:${Math.round(rect.w / 24)}:${Math.round(rect.h / 24)}`;
+      if (rect.style === "blur") {
+        blurKeys.add(posKey);
+        continue;
+      }
+      const inset = scaleRect(shrinkRect(rect, Math.min(6, rect.w / 8, rect.h / 8)), frameScale);
+      const region = await sourceRegionGray(ctx2.bundle, sample.t + 60, inset, true);
+      if (!region) continue;
+      const sd = Math.sqrt(variance(region));
+      const key = posKey;
+      const prev = buckets.get(key);
+      if (!prev || sd < prev.minSd) buckets.set(key, { rect, minSd: sd, t: sample.t });
+    }
+  }
+  for (const b of buckets.values()) {
+    if (b.minSd > 16) {
+      evidence.push({ t: b.t, note: `solid mask at ${fmtRect(b.rect)} never verified opaque (best \u03C3=${b.minSd.toFixed(1)})` });
+    }
+  }
+  for (const e of actionEvents(ctx2.bundle.events)) {
+    if (e.masked && e.typedText && /[^•]/.test(e.typedText)) {
+      evidence.push({ stepRef: `${e.sceneId}/${e.stepIndex}`, note: "masked step leaked typed text into the event log" });
+    }
+  }
+  if (ctx2.bundle.maskSamples.length === 0) {
+    return { id: "masks", status: "skip", details: "no masking rules" };
+  }
+  if (evidence.length > 0) {
+    return { id: "masks", status: "fail", details: `${evidence.length} mask violation(s)`, evidence };
+  }
+  const parts = [];
+  if (buckets.size > 0) parts.push(`${buckets.size} solid region(s) verified opaque`);
+  if (blurKeys.size > 0) parts.push(`${blurKeys.size} blurred region(s) applied`);
+  return { id: "masks", status: "pass", details: `${parts.join(", ")}; log clean` };
+}
+function scaleRect(r, s) {
+  return { x: r.x * s, y: r.y * s, w: r.w * s, h: r.h * s };
+}
+function rectsOverlap(a, b) {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+function shrinkRect(r, by) {
+  return { x: r.x + by, y: r.y + by, w: Math.max(1, r.w - 2 * by), h: Math.max(1, r.h - 2 * by) };
+}
+function fmtRect(r) {
+  return `[${r.x.toFixed(0)},${r.y.toFixed(0)} ${r.w.toFixed(0)}x${r.h.toFixed(0)}]`;
+}
+async function checkOutputPixels(ctx2) {
+  const p = plane(ctx2);
+  const content = stageContent(ctx2.manifest.profile);
+  const frameScale = ctx2.bundle.manifest.frameW / ctx2.manifest.viewport.w;
+  const captions = ctx2.manifest.overlays.filter((o) => o.kind === "caption");
+  const candidates = ctx2.manifest.steps.filter((s) => !s.masked && (s.focusRectVp ?? s.targetRectVp));
+  const stride = Math.max(1, Math.floor(candidates.length / 6));
+  const sampled = candidates.filter((_, i) => i % stride === 0).slice(0, 6);
+  if (sampled.length === 0) return { id: "output-pixels", status: "skip", details: "no steps with targets" };
+  const evidence = [];
+  let checked = 0;
+  for (const step of sampled) {
+    const rect = step.focusRectVp ?? step.targetRectVp;
+    const tOut = Math.max(step.outBeat + 100, step.outEnd - 250);
+    const cam = sampleCamera(ctx2.manifest.camera, tOut);
+    const proj = projectRect(rect, cam, p);
+    const projFrame = { x: proj.x + content.x, y: proj.y + content.y, w: proj.w, h: proj.h };
+    if (captions.some((c) => tOut >= c.tStart && tOut <= c.tEnd && rectsOverlap(c.box, projFrame))) continue;
+    const { srcAt } = sampleSource(ctx2.manifest.segments, tOut);
+    if (srcAt === null) continue;
+    const outPng = await extractFrameAt(ctx2.videoPath, tOut).catch(() => null);
+    if (!outPng) continue;
+    const outRegion = await regionGray48(outPng, projFrame);
+    const srcFile = framePath(ctx2.bundle, frameIndexForTime(ctx2.bundle.frames, srcAt));
+    const srcRegion = await regionGray48(srcFile, {
+      x: rect.x * frameScale,
+      y: rect.y * frameScale,
+      w: rect.w * frameScale,
+      h: rect.h * frameScale
+    });
+    if (!outRegion || !srcRegion) continue;
+    if (variance(outRegion) < 4 || variance(srcRegion) < 4) continue;
+    checked += 1;
+    const corr = normalizedCorrelation(outRegion, srcRegion);
+    if (corr < 0.5) {
+      evidence.push({
+        stepRef: step.stepRef,
+        t: tOut,
+        note: `output region does not match the planned source region (correlation ${corr.toFixed(2)})`
+      });
+    }
+  }
+  if (checked === 0) return { id: "output-pixels", status: "skip", details: "no comparable samples (captions overlapped or frames unavailable)" };
+  return evidence.length > 0 ? { id: "output-pixels", status: "fail", details: `${evidence.length}/${checked} sampled regions diverge from the plan`, evidence } : { id: "output-pixels", status: "pass", details: `${checked} sampled output regions match their planned source` };
+}
+
+// src/verify/contact-sheet.ts
+import { writeFile as writeFile4 } from "fs/promises";
+import { createCanvas as createCanvas4, loadImage } from "@napi-rs/canvas";
+var TILE_W = 480;
+var LABEL_H = 42;
+var GUTTER = 16;
+var COLS = 3;
+async function renderContactSheet(manifest, videoPath, outPath) {
+  registerFonts();
+  const tileH = Math.round(TILE_W * manifest.profile.height / manifest.profile.width);
+  const captionsByStep = new Map(
+    manifest.overlays.filter((o) => o.kind === "caption").map((o) => [o.stepRef, o])
+  );
+  const moments = [
+    { t: manifest.overlays.find((o) => o.kind === "titleCard").tEnd / 2, label: "Title" }
+  ];
+  for (const step of manifest.steps) {
+    const caption = captionsByStep.get(step.stepRef);
+    const label = caption ? `${caption.ordinal}. ${caption.text}` : `${step.kind} (${step.stepRef})`;
+    const settled = Math.max(step.outBeat + 150, step.outEnd - 400);
+    moments.push({ t: Math.min(settled, step.outEnd - 50), label });
+  }
+  moments.push({ t: manifest.durationMs - 200, label: "Final state" });
+  const rows = Math.ceil(moments.length / COLS);
+  const width = GUTTER + COLS * (TILE_W + GUTTER);
+  const height = GUTTER + rows * (tileH + LABEL_H + GUTTER);
+  const canvas = createCanvas4(width, height);
+  const ctx2 = canvas.getContext("2d");
+  ctx2.fillStyle = "#14161d";
+  ctx2.fillRect(0, 0, width, height);
+  for (let i = 0; i < moments.length; i++) {
+    const m = moments[i];
+    const col = i % COLS;
+    const row = Math.floor(i / COLS);
+    const x = GUTTER + col * (TILE_W + GUTTER);
+    const y = GUTTER + row * (tileH + LABEL_H + GUTTER);
+    try {
+      const png = await extractFrameAt(videoPath, m.t);
+      const img = await loadImage(png);
+      ctx2.drawImage(img, x, y, TILE_W, tileH);
+    } catch {
+      ctx2.fillStyle = "#3a2030";
+      ctx2.fillRect(x, y, TILE_W, tileH);
+      ctx2.fillStyle = "#ffffff";
+      ctx2.font = "16px Inter Medium";
+      ctx2.textAlign = "center";
+      ctx2.fillText("frame unavailable", x + TILE_W / 2, y + tileH / 2);
+    }
+    ctx2.fillStyle = "#1e222c";
+    roundRect(ctx2, x, y + tileH + 4, TILE_W, LABEL_H - 8, 6);
+    ctx2.fill();
+    ctx2.fillStyle = "rgba(255,255,255,0.92)";
+    ctx2.font = "15px Inter Medium";
+    ctx2.textAlign = "left";
+    ctx2.textBaseline = "middle";
+    ctx2.fillText(truncate2(m.label, 58), x + 12, y + tileH + 4 + (LABEL_H - 8) / 2 + 1);
+    ctx2.fillStyle = "rgba(255,255,255,0.45)";
+    ctx2.font = "13px Inter";
+    ctx2.textAlign = "right";
+    ctx2.fillText(`${(m.t / 1e3).toFixed(1)}s`, x + TILE_W - 12, y + tileH + 4 + (LABEL_H - 8) / 2 + 1);
+  }
+  await writeFile4(outPath, await canvas.encode("png"));
+  return outPath;
+}
+function truncate2(s, n) {
+  return s.length <= n ? s : s.slice(0, n - 1) + "\u2026";
+}
+
+// src/verify/vision.ts
+import { readFile as readFile3 } from "fs/promises";
+var DEFAULT_MODEL = process.env.PLAYHEAD_VISION_MODEL ?? "claude-opus-5";
+async function visionReview(contactSheetPath, manifest) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    return {
+      check: { id: "vision-review", status: "skip", details: "ANTHROPIC_API_KEY not set" },
+      review: null
+    };
+  }
+  try {
+    const { default: Anthropic } = await import("@anthropic-ai/sdk");
+    const client = new Anthropic();
+    const png = await readFile3(contactSheetPath);
+    const captions = manifest.overlays.filter((o) => o.kind === "caption").map((o) => `${o.ordinal}. ${o.text}`).join("\n");
+    const response = await client.messages.create({
+      model: DEFAULT_MODEL,
+      max_tokens: 1200,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              source: { type: "base64", media_type: "image/png", data: png.toString("base64") }
+            },
+            {
+              type: "text",
+              text: [
+                "This is a contact sheet of key moments from an automatically produced product walkthrough video.",
+                "Each tile shows the output frame at one step, labeled with its instruction caption. The steps are:",
+                captions,
+                "",
+                "Review it as a demanding video editor. Report only real problems a viewer would notice:",
+                "illegible or clipped UI, captions that do not match what is on screen, awkward framing,",
+                "visual glitches, or anything unprofessional. Ignore the tile borders and labels themselves.",
+                'Respond with strict JSON: {"findings": [{"severity": "warn", "note": "..."}]} \u2014',
+                "an empty findings array if the video looks publishable."
+              ].join("\n")
+            }
+          ]
+        }
+      ]
+    });
+    const text = response.content.map((b) => b.type === "text" ? b.text : "").join("");
+    const parsed = extractJson(text);
+    const findings = Array.isArray(parsed?.findings) ? parsed.findings.filter((f) => !!f && typeof f === "object").map((f) => ({ severity: String(f.severity ?? "warn"), note: String(f.note ?? "") })) : [];
+    const review = { model: DEFAULT_MODEL, findings };
+    return {
+      check: {
+        id: "vision-review",
+        status: findings.length > 0 ? "warn" : "pass",
+        details: findings.length > 0 ? `${findings.length} advisory finding(s) from ${DEFAULT_MODEL}` : `no issues flagged by ${DEFAULT_MODEL}`,
+        ...findings.length > 0 ? { evidence: findings.map((f) => ({ note: f.note })) } : {}
+      },
+      review
+    };
+  } catch (e) {
+    log.warn(`vision review failed: ${e.message}`);
+    return {
+      check: { id: "vision-review", status: "skip", details: `vision review errored: ${e.message}` },
+      review: null
+    };
+  }
+}
+function extractJson(text) {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try {
+    return JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+
+// src/verify/report.ts
+import { createHmac } from "crypto";
+function signablePayload(v) {
+  return JSON.stringify({
+    schema: v.schema,
+    verdict: v.verdict,
+    videoSha256: v.video.sha256,
+    bundleHashes: { events: v.bundleHashes.events, framesIndex: v.bundleHashes.framesIndex },
+    provenance: {
+      playheadVersion: v.provenance.playheadVersion,
+      specHash: v.provenance.specHash,
+      appUrl: v.provenance.appUrl,
+      capturedAt: v.provenance.capturedAt,
+      verifiedAt: v.provenance.verifiedAt,
+      checkSuiteVersion: v.provenance.checkSuiteVersion,
+      host: v.provenance.host,
+      partial: v.provenance.partial ?? false
+    },
+    checks: v.checks.map((c) => ({ id: c.id, status: c.status }))
+  });
+}
+function signVerdict(v, key = process.env.PLAYHEAD_SIGNING_KEY) {
+  if (!key) return null;
+  return createHmac("sha256", key).update(signablePayload(v)).digest("hex");
+}
+
+// src/verify/runner.ts
+import { platform, arch } from "os";
+import pc2 from "picocolors";
+var CHECK_SUITE_VERSION = "playhead/checks@2";
+async function verify(bundle, manifest, videoPath, opts) {
+  const verifyDir = join8(opts.outDir, "verify");
+  await mkdir4(verifyDir, { recursive: true });
+  const ctx2 = { bundle, manifest, videoPath, outDir: verifyDir };
+  log.info("verifying output");
+  const checks = [];
+  const suite = [
+    checkEncode,
+    // fail fast on a broken file before decoding frames from it
+    checkTargetInFrame,
+    checkCursorOnTarget,
+    checkActionEffect,
+    checkOutputPixels,
+    // the delivered MP4, not the plan
+    checkFrozenBlank,
+    checkCaptions,
+    checkPacing,
+    checkMasks,
+    checkAudio
+  ];
+  for (const check of suite) {
+    const result = await check(ctx2);
+    checks.push(result);
+    report(result);
+  }
+  const contactSheet = join8(verifyDir, "contact-sheet.png");
+  await renderContactSheet(manifest, videoPath, contactSheet);
+  log.ok(`contact sheet \u2192 ${contactSheet}`);
+  let vision = null;
+  if (opts.vision) {
+    const { check, review } = await visionReview(contactSheet, manifest);
+    checks.push(check);
+    report(check);
+    vision = review;
+  }
+  const failed = checks.some((c) => c.status === "fail");
+  const unsigned = {
+    schema: "playhead/verdict@2",
+    verdict: failed ? "not-publishable" : "publishable",
+    video: { path: videoPath, sha256: manifest.videoSha256 ?? await sha256File(videoPath) },
+    bundleHashes: manifest.bundleHashes,
+    provenance: {
+      playheadVersion: PLAYHEAD_VERSION,
+      specHash: bundle.manifest.specHash,
+      appUrl: bundle.manifest.appUrl,
+      capturedAt: bundle.manifest.createdAtIso,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      checkSuiteVersion: CHECK_SUITE_VERSION,
+      host: `${platform()}-${arch()}`,
+      ...bundle.manifest.partial ? { partial: true } : {},
+      ...bundle.manifest.failure ? { failure: bundle.manifest.failure } : {}
+    },
+    checks,
+    contactSheet,
+    vision
+  };
+  const verdict = { ...unsigned, signature: signVerdict(unsigned) };
+  if (!verdict.signature) log.debug("verdict unsigned \u2014 set PLAYHEAD_SIGNING_KEY to sign");
+  await writeFile5(join8(verifyDir, "verdict.json"), JSON.stringify(verdict, null, 2));
+  if (failed) log.error(`verdict: NOT PUBLISHABLE`);
+  else log.ok(`verdict: publishable`);
+  return verdict;
+}
+function report(c) {
+  const label = c.status === "pass" ? pc2.green("pass") : c.status === "fail" ? pc2.red("FAIL") : c.status === "warn" ? pc2.yellow("warn") : pc2.dim("skip");
+  console.error(`    ${label}  ${c.id}: ${c.details}`);
+  for (const e of c.evidence ?? []) {
+    console.error(pc2.dim(`          ${e.stepRef ?? ""}${e.t !== void 0 ? ` @${(e.t / 1e3).toFixed(1)}s` : ""} \u2014 ${e.note}`));
+  }
+}
+export {
+  PROFILE_16x9,
+  SpecError,
+  capture,
+  compose,
+  flattenSteps,
+  loadSpec,
+  locatorDisplayName,
+  openBundle,
+  parseLocator,
+  parseSpec,
+  plan,
+  registerFonts,
+  renderFromManifest,
+  resolveTheme,
+  specSchema,
+  verify,
+  writeCaption
+};
+//# sourceMappingURL=index.js.map