playhead-cli 0.1.3 → 0.2.0

package/dist/index.js

@@ -9,10 +9,33 @@ import { z } from "zod";
 // src/spec/locators.ts
 var LocatorParseError = class extends Error {
 };
+function splitSegments(raw) {
+  const parts = [];
+  let cur = "";
+  let quote = null;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (quote) {
+      cur += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      cur += ch;
+    } else if (ch === ">" && raw[i + 1] === ">") {
+      parts.push(cur.trim());
+      cur = "";
+      i += 1;
+    } else {
+      cur += ch;
+    }
+  }
+  parts.push(cur.trim());
+  return parts;
+}
 function parseLocator(input) {
   const raw = input.trim();
   let nth;
-  const parts = raw.split(">>").map((p) => p.trim());
+  const parts = splitSegments(raw);
   const frames = [];
   while (parts.length > 0 && parts[0].startsWith("frame=")) {
     const sel = unquote(parts.shift().slice("frame=".length).trim());
@@ -122,7 +145,7 @@ var locatorString = z.string().min(1).superRefine((val, ctx2) => {
   }
 });
 var focusHint = z.union([z.literal("target"), z.literal("wide"), locatorString]);
-var EXTRA_KEYS = ["caption", "narration", "focus", "mask", "shot", "timeout"];
+var EXTRA_KEYS = ["caption", "narration", "focus", "mask", "shot", "timeout", "optional"];
 var stepExtras = {
   caption: z.string().optional(),
   /** The SPOKEN line for TTS narration — unconstrained by the caption card's size. Resolution:
@@ -134,7 +157,10 @@ var stepExtras = {
    *  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()
+  timeout: z.number().int().positive().optional(),
+  /** A failing optional step is SKIPPED (warned, unfilmed beat) instead of killing the whole
+   *  capture — for cookie banners, A/B'd tooltips, and other environment noise. */
+  optional: z.boolean().optional()
 };
 var targetOrShorthand = z.union([
   locatorString,
@@ -151,9 +177,15 @@ var typeStep = z.object({
   target: locatorString,
   text: z.string(),
   mask: z.boolean().default(false),
+  /** Select-all + overwrite instead of appending — editing a pre-filled field without this
+   *  produces "Janenew value". */
+  clear: z.boolean().default(false),
   ...stepExtras
 }).strict();
 var pressStep = z.object({ action: z.literal("press"), keys: z.string(), ...stepExtras }).strict();
+var rightclickStep = z.object({ action: z.literal("rightclick"), target: locatorString, ...stepExtras }).strict();
+var uploadStep = z.object({ action: z.literal("upload"), target: locatorString, file: z.string(), ...stepExtras }).strict();
+var dragStep = z.object({ action: z.literal("drag"), target: locatorString, to: locatorString, ...stepExtras }).strict();
 var selectStep = z.object({
   action: z.literal("select"),
   target: locatorString,
@@ -168,13 +200,24 @@ var scrollStep = z.object({
 }).strict();
 var expectStep = z.object({
   action: z.literal("expect"),
-  target: locatorString,
+  target: locatorString.optional(),
   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(),
+  /** Current page URL must CONTAIN this substring (or match when wrapped /like this/). */
+  url: z.string().optional(),
+  /** Form control's current value. */
+  value: z.string().optional(),
+  /** Element enabled/disabled and checked state. */
+  disabled: z.boolean().optional(),
+  checked: z.boolean().optional(),
   ...stepExtras
-}).strict();
+}).strict().refine((s) => s.target !== void 0 || s.url !== void 0, {
+  message: "expect needs a target locator (element assertions) and/or a url"
+}).refine((s) => s.target !== void 0 || s.visible === void 0 && s.text === void 0 && s.count === void 0 && s.value === void 0 && s.disabled === void 0 && s.checked === void 0, {
+  message: "element assertions (visible/text/count/value/disabled/checked) need a target"
+});
 var waitStep = z.object({
   action: z.literal("wait"),
   ms: z.number().int().positive().optional(),
@@ -189,12 +232,15 @@ var stepSchema = z.discriminatedUnion("action", [
   pointerStep,
   typeStep,
   pressStep,
+  rightclickStep,
+  uploadStep,
+  dragStep,
   selectStep,
   scrollStep,
   expectStep,
   waitStep
 ]);
-var ACTION_KEYS = ["goto", "click", "dblclick", "hover", "type", "press", "select", "scroll", "expect", "wait"];
+var ACTION_KEYS = ["goto", "click", "dblclick", "hover", "type", "press", "rightclick", "upload", "drag", "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) {
@@ -343,7 +389,10 @@ var specSchema = z.object({
     }).strict().refine(
       (a) => a.provider !== "kokoro" || a.voice === void 0 || ["heart", "af_heart", "michael", "am_michael"].includes(a.voice),
       { message: "kokoro voice must be 'heart' (default) or 'michael'", path: ["voice"] }
-    ).optional(),
+    ).refine((a) => a.provider !== "kokoro" || a.rate === void 0 || a.rate >= 80 && a.rate <= 140, {
+      message: "kokoro rate is playback speed \xD7100 (100 = normal, sensible range 80\u2013140) \u2014 a say-style words-per-minute value like 178 would speak absurdly fast",
+      path: ["rate"]
+    }).optional(),
     /** Closing card. When set, the video ends on a title-card-styled end card. */
     endCard: z.object({
       title: z.string().min(1),
@@ -362,13 +411,24 @@ var specSchema = z.object({
       style: z.enum(["solid", "blur"]).default("solid")
     }).strict()
   ).default([]),
+  /** Steps that run BEFORE recording starts and never appear on film — dismiss a cookie-consent
+   *  banner, close a first-run tour, prime app state. Same step grammar as scenes. */
+  setup: z.array(authoredStep.pipe(stepSchema)).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)
+  ).min(1).superRefine((scenes, ctx2) => {
+    const seen = /* @__PURE__ */ new Set();
+    scenes.forEach((s, i) => {
+      if (seen.has(s.id)) {
+        ctx2.addIssue({ code: "custom", path: [i, "id"], message: `duplicate scene id "${s.id}" \u2014 ids must be unique (check the extended base spec too)` });
+      }
+      seen.add(s.id);
+    });
+  })
 }).strict();
 var ASPECTS = {
   "16:9": { viewport: { w: 1280, h: 720 }, resolution: { w: 1920, h: 1080 } },
@@ -412,6 +472,7 @@ var KNOWN_KEYS = [
   "scenes",
   "vars",
   "extends",
+  "setup",
   "url",
   "viewport",
   "storageState",
@@ -482,7 +543,15 @@ var KNOWN_KEYS = [
   "for",
   "state",
   "x",
-  "y"
+  "y",
+  "optional",
+  "clear",
+  "to",
+  "disabled",
+  "checked",
+  "rightclick",
+  "upload",
+  "drag"
 ];
 function suggest(key) {
   let best = null;
@@ -514,7 +583,13 @@ async function loadSpec(path) {
   const text = await readFile(resolvePath(path), "utf8");
   const lineCounter = new LineCounter();
   const doc = parseDocument(text, { lineCounter });
-  return validateResolved(interpolate(merged, path), path, doc, lineCounter);
+  const leaf = doc.toJS() ?? {};
+  const arrLen = (v) => Array.isArray(v) ? v.length : 0;
+  const offsets = {
+    scenes: arrLen(merged.scenes) - arrLen(leaf.scenes),
+    masking: arrLen(merged.masking) - arrLen(leaf.masking)
+  };
+  return validateResolved(interpolate(merged, path), path, doc, lineCounter, offsets);
 }
 async function loadRaw(path, depth) {
   if (depth > 4) throw new SpecError(`${path}: extends chain deeper than 4 \u2014 check for a cycle`);
@@ -553,6 +628,28 @@ function interpolate(raw, sourcePath) {
   for (const [name, value] of Object.entries(varsIn)) {
     vars.set(name, resolveEnv(String(value), sourcePath));
   }
+  for (let pass = 0; pass < 6; pass++) {
+    let changed = false;
+    for (const [name, value] of vars) {
+      const next = value.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (m, ref) => {
+        if (ref === name) throw new SpecError(`${sourcePath}: variable {{${name}}} references itself`);
+        const v = vars.get(ref);
+        return v !== void 0 && !v.includes(`{{${name}}}`) ? v : m;
+      });
+      if (next !== value) {
+        vars.set(name, next);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+    if (pass === 5) throw new SpecError(`${sourcePath}: variable references did not resolve after 6 passes \u2014 circular vars?`);
+  }
+  for (const [name, value] of vars) {
+    const m = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/.exec(value);
+    if (m && vars.has(m[1])) {
+      throw new SpecError(`${sourcePath}: circular variable reference \u2014 {{${name}}} and {{${m[1]}}} depend on each other`);
+    }
+  }
   const doc = { ...raw };
   delete doc.vars;
   const seen = (s) => {
@@ -584,18 +681,18 @@ function resolveEnv(s, sourcePath) {
     throw new SpecError(`${sourcePath}: environment variable ${name} is not set and has no default (use \${env.${name}:-fallback})`);
   });
 }
-function validateResolved(resolved, sourcePath, doc, lineCounter) {
+function validateResolved(resolved, sourcePath, doc, lineCounter, offsets = { scenes: 0, masking: 0 }) {
   const result = specSchema.safeParse(resolved);
   if (!result.success) {
-    const issues = result.error.issues.map((iss) => formatIssue(iss, sourcePath, doc, lineCounter));
+    const issues = result.error.issues.map((iss) => formatIssue(iss, sourcePath, doc, lineCounter, offsets));
     throw new SpecError(`${sourcePath}: invalid spec
   - ${issues.join("\n  - ")}`, issues);
   }
   return result.data;
 }
-function formatIssue(iss, sourcePath, doc, lineCounter) {
+function formatIssue(iss, sourcePath, doc, lineCounter, offsets = { scenes: 0, masking: 0 }) {
   const where = iss.path.length ? humanPath(iss.path) : "spec";
-  const pos = positionOf(iss.path, doc, lineCounter);
+  const pos = positionOf(iss.path, doc, lineCounter, offsets);
   const at = pos ? `${sourcePath}:${pos.line}:${pos.col} ` : "";
   if (iss.code === "unrecognized_keys") {
     const keys = iss.keys;
@@ -604,7 +701,15 @@ function formatIssue(iss, sourcePath, doc, lineCounter) {
   }
   return `${at}${where}: ${iss.message}`;
 }
-function positionOf(path, doc, lineCounter) {
+function positionOf(path, doc, lineCounter, offsets = { scenes: 0, masking: 0 }) {
+  if ((path[0] === "scenes" || path[0] === "masking") && typeof path[1] === "number") {
+    const off = offsets[path[0]];
+    if (off > 0) {
+      const adjusted = path[1] - off;
+      if (adjusted < 0) return null;
+      path = [path[0], adjusted, ...path.slice(2)];
+    }
+  }
   for (let depth = path.length; depth > 0; depth--) {
     try {
       const node = doc.getIn(path.slice(0, depth), true);
@@ -622,7 +727,7 @@ function humanPath(path) {
 }
 
 // src/capture/executor.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 
 // src/capture/playwright-driver.ts
 import { chromium } from "playwright";
@@ -682,7 +787,23 @@ var log = {
   }
 };
 
+// src/shared/exit.ts
+var EXIT = {
+  OK: 0,
+  FLOW: 1,
+  QUALITY: 2,
+  INFRA: 3,
+  USAGE: 4
+};
+var FlowError = class extends Error {
+  exitCode = EXIT.FLOW;
+};
+var InfraError = class extends Error {
+  exitCode = EXIT.INFRA;
+};
+
 // src/capture/playwright-driver.ts
+import { access } from "fs/promises";
 var INPUT_TIMEOUT_MS = 5e3;
 var MASK_INIT_SCRIPT = `
 (() => {
@@ -725,11 +846,24 @@ var MASK_INIT_SCRIPT = `
   // 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;
+  // querySelectorAll does NOT pierce shadow roots \u2014 but Playwright's tagging does, so a masked
+  // element inside a web component (any design system) would be tagged yet never overlaid,
+  // filming the secret while masks.json claims coverage (round-2 audit). Walk shadow roots too.
+  const deepQuery = (sel) => {
+    const out = [];
+    const walk = (root) => {
+      try { for (const el of root.querySelectorAll(sel)) out.push(el); } catch (e) {}
+      const all = root.querySelectorAll('*');
+      for (const el of all) if (el.shadowRoot) walk(el.shadowRoot);
+    };
+    walk(document);
+    return out;
+  };
   const scanRules = () => {
     const rules = window.__playheadMaskCssRules || [];
     for (const r of rules) {
       try {
-        for (const el of document.querySelectorAll(r.css)) {
+        for (const el of deepQuery(r.css)) {
           if (!el.hasAttribute('data-playhead-mask')) el.setAttribute('data-playhead-mask', r.style);
         }
       } catch (e) {}
@@ -738,7 +872,7 @@ var MASK_INIT_SCRIPT = `
   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]'));
+      const tagged = new Set(deepQuery('[data-playhead-mask]'));
       for (const [el, box] of boxes) {
         if (!tagged.has(el) || !el.isConnected) { box.remove(); boxes.delete(el); }
       }
@@ -888,9 +1022,23 @@ var PlaywrightDriver = class _PlaywrightDriver {
   tagCounter = 0;
   typingMaskLoc = null;
   async launch(opts) {
+    try {
+      await access(chromium.executablePath());
+    } catch {
+      throw new InfraError(
+        "Chromium is not installed (one-time setup) \u2014 run: npx playwright install chromium"
+      );
+    }
     const env = opts.environment;
-    this.browser = await chromium.launch({ headless: opts.headless ?? true });
+    this.forcedDsf = opts.dpr > 1 && process.env.PLAYHEAD_CAPTURE !== "screenshot" ? opts.dpr : 1;
+    this.browser = await chromium.launch({
+      headless: opts.headless ?? true,
+      ...this.forcedDsf > 1 ? { args: [`--force-device-scale-factor=${this.forcedDsf}`] } : {}
+    });
+    const chromeMajor = this.browser.version().split(".")[0] ?? this.browser.version();
+    const uaPlatform = process.platform === "darwin" ? "Macintosh; Intel Mac OS X 10_15_7" : process.platform === "win32" ? "Windows NT 10.0; Win64; x64" : "X11; Linux x86_64";
     this.context = await this.browser.newContext({
+      userAgent: `Mozilla/5.0 (${uaPlatform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeMajor}.0.0.0 Safari/537.36`,
       viewport: { width: opts.viewport.w, height: opts.viewport.h },
       deviceScaleFactor: opts.dpr,
       colorScheme: env?.colorScheme ?? "light",
@@ -929,7 +1077,10 @@ var PlaywrightDriver = class _PlaywrightDriver {
     });
     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"));
+    this.page.on("crash", () => {
+      this.pushConsole("crash", "page crashed");
+      this.crashed = true;
+    });
     const dialogPolicy = opts.dialogs ?? "accept";
     this.page.on("dialog", (dialog) => {
       this.pushConsole("dialog", `${dialog.type()}("${dialog.message()}") \u2192 ${dialogPolicy}`);
@@ -946,6 +1097,12 @@ var PlaywrightDriver = class _PlaywrightDriver {
     await this.page.mouse.move(this.cursor.x, this.cursor.y);
   }
   consoleBuf = [];
+  /** Browser-level forced device scale (--force-device-scale-factor); 1 = not forced. */
+  forcedDsf = 1;
+  crashed = false;
+  assertAlive() {
+    if (this.crashed) throw new Error("page crashed \u2014 the browser renderer died (see console.json)");
+  }
   pushConsole(type, text) {
     this.consoleBuf.push({ t: Date.now(), type, text: text.slice(0, 500) });
     if (this.consoleBuf.length > 500) this.consoleBuf.shift();
@@ -1063,6 +1220,7 @@ var PlaywrightDriver = class _PlaywrightDriver {
     return l;
   }
   async resolveTarget(loc, timeoutMs) {
+    this.assertAlive();
     const locator = this.toLocator(loc);
     try {
       await locator.waitFor({ state: "visible", timeout: timeoutMs });
@@ -1126,6 +1284,8 @@ var PlaywrightDriver = class _PlaywrightDriver {
     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 };
+      const main = await withTimeout(this.page.evaluate(() => ({ x: window.scrollX, y: window.scrollY })), 2e3).catch(() => null);
+      if (main) geom.scroll = main;
     }
     let role = null;
     let name = null;
@@ -1217,12 +1377,69 @@ var PlaywrightDriver = class _PlaywrightDriver {
    * 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 setInputFiles(loc, filePath) {
+    await this.toLocator(loc).setInputFiles(filePath, { timeout: INPUT_TIMEOUT_MS * 2 });
+  }
+  /** Real drag: hover the source, press, glide to the destination in eased steps (recording
+   *  pressed-cursor waypoints for the film), release over the target's current position. */
+  async dragTo(from, to, timeoutMs) {
+    const src = this.toLocator(from);
+    const dst = this.toLocator(to);
+    await src.hover({ timeout: timeoutMs });
+    const a = await src.boundingBox();
+    if (!a) throw new Error(`drag source vanished: ${from.raw}`);
+    const start = { x: a.x + a.width / 2, y: a.y + a.height / 2 };
+    const tDown = Date.now();
+    await withTimeout(this.page.mouse.down(), INPUT_TIMEOUT_MS);
+    const path = [{ x: start.x, y: start.y, t: tDown }];
+    const b = await dst.boundingBox();
+    if (!b) {
+      await this.page.mouse.up().catch(() => {
+      });
+      throw new Error(`drag destination not found: ${to.raw}`);
+    }
+    const end = { x: b.x + b.width / 2, y: b.y + b.height / 2 };
+    const STEPS = 24;
+    for (let i = 1; i <= STEPS; i++) {
+      const u = minJerk(i / STEPS);
+      const p = { x: start.x + (end.x - start.x) * u, y: start.y + (end.y - start.y) * u };
+      await withTimeout(this.page.mouse.move(p.x, p.y), INPUT_TIMEOUT_MS);
+      path.push({ x: p.x, y: p.y, t: Date.now() });
+      await sleep(18);
+    }
+    const tUp = Date.now();
+    await withTimeout(this.page.mouse.up(), INPUT_TIMEOUT_MS);
+    this.cursor = end;
+    return { tDown, tUp, path };
+  }
   async actClick(loc, opts) {
     const locator = this.toLocator(loc);
-    const tDown = Date.now();
+    await locator.hover({ timeout: opts?.timeoutMs ?? 1e4 }).catch(() => {
+    });
+    await withTimeout(
+      this.page.evaluate(() => new Promise(requestAnimationFrame).then(() => new Promise(requestAnimationFrame))),
+      1200
+    ).catch(() => {
+    });
+    await this.captureNow();
+    const before = Date.now();
+    await locator.evaluate((el) => {
+      const w = el.ownerDocument.defaultView;
+      if (w) {
+        w.__phTDown = null;
+        el.addEventListener("pointerdown", () => w.__phTDown = Date.now(), { once: true, capture: true });
+      }
+    }).catch(() => {
+    });
     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() };
+    else await locator.click({ delay: 70, timeout: opts?.timeoutMs ?? 1e4, ...opts?.button ? { button: opts.button } : {} });
+    const tUp = Date.now();
+    const browserTDown = await withTimeout(
+      locator.evaluate((el) => el.ownerDocument.defaultView?.__phTDown ?? null),
+      1500
+    ).catch(() => null);
+    const tDown = typeof browserTDown === "number" ? browserTDown - this.clockOffset : Math.max(before, tUp - 90);
+    return { tDown, tUp };
   }
   async selectOption(loc, value) {
     const locator = this.toLocator(loc);
@@ -1231,8 +1448,6 @@ var PlaywrightDriver = class _PlaywrightDriver {
     } catch {
       await locator.selectOption(value);
     }
-    await withTimeout(this.page.keyboard.press("Escape"), INPUT_TIMEOUT_MS).catch(() => {
-    });
     await withTimeout(
       locator.evaluate((el) => el.blur?.()),
       2e3
@@ -1268,6 +1483,22 @@ var PlaywrightDriver = class _PlaywrightDriver {
     }
   }
   async expectState(loc, opts, timeoutMs) {
+    if (opts.url !== void 0) {
+      const want = opts.url;
+      const matches = (u) => {
+        const m = /^\/(.+)\/([a-z]*)$/.exec(want);
+        return m ? new RegExp(m[1], m[2]).test(u) : u.includes(want);
+      };
+      const deadlineUrl = Date.now() + timeoutMs;
+      while (!matches(this.page.url())) {
+        if (Date.now() > deadlineUrl) {
+          throw new Error(`Expectation not met for URL: expected ${want}, got ${this.page.url()}`);
+        }
+        await sleep(100);
+      }
+      if (!loc) return;
+    }
+    if (!loc) return;
     const locator = this.toLocator(loc);
     const deadline = Date.now() + timeoutMs;
     let lastErr = "condition not met";
@@ -1283,6 +1514,18 @@ var PlaywrightDriver = class _PlaywrightDriver {
         const visible = await locator.first().isVisible();
         if (opts.visible !== void 0 && visible !== opts.visible) {
           lastErr = `expected visible=${opts.visible}, got ${visible}`;
+        } else if (opts.value !== void 0) {
+          const v = await locator.inputValue({ timeout: 1e3 }).catch(() => null);
+          if (v === opts.value) return;
+          lastErr = `expected value ${JSON.stringify(opts.value)}, got ${JSON.stringify(v)}`;
+        } else if (opts.disabled !== void 0) {
+          const d = await locator.isDisabled({ timeout: 1e3 }).catch(() => null);
+          if (d === opts.disabled) return;
+          lastErr = `expected disabled=${opts.disabled}, got ${d}`;
+        } else if (opts.checked !== void 0) {
+          const c = await locator.isChecked({ timeout: 1e3 }).catch(() => null);
+          if (c === opts.checked) return;
+          lastErr = `expected checked=${opts.checked}, got ${c}`;
         } else if (opts.text !== void 0) {
           const content = visible ? await locator.first().innerText() : "";
           if (!content.includes(opts.text)) {
@@ -1324,6 +1567,7 @@ var PlaywrightDriver = class _PlaywrightDriver {
   }
   static LONG_REQUEST_MS = 2e3;
   async settle(opts) {
+    this.assertAlive();
     this.installNetTracking();
     const start = Date.now();
     let capped = true;
@@ -1366,7 +1610,20 @@ var PlaywrightDriver = class _PlaywrightDriver {
         })
       ),
       1800
-    ).catch(() => {
+    ).catch(async (e) => {
+      if (/context.*destroyed|navigat/i.test(e.message ?? "")) {
+        await this.page.waitForLoadState("load", { timeout: 5e3 }).catch(() => {
+        });
+        await withTimeout(
+          this.page.evaluate(
+            () => new Promise((resolve) => {
+              setTimeout(resolve, 400);
+            })
+          ),
+          1e3
+        ).catch(() => {
+        });
+      }
     });
     await this.nextFrame();
   }
@@ -1423,10 +1680,56 @@ var PlaywrightDriver = class _PlaywrightDriver {
   // 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).
+  screencastActive = false;
   async startCapture(onFrame, opts) {
     this.captureOnFrame = onFrame;
     this.captureOpts = opts;
     this.captureActive = true;
+    if (process.env.PLAYHEAD_CAPTURE !== "screenshot") {
+      try {
+        const vp = this.page.viewportSize() ?? { width: 1280, height: 720 };
+        const expectedW = Math.round(vp.width * opts.scale);
+        let sizeChecked = false;
+        this.captureCdp.on("Page.screencastFrame", (ev) => {
+          void this.captureCdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+          });
+          if (!this.captureActive || !this.captureOnFrame || !this.screencastActive) return;
+          const data = Buffer.from(ev.data, "base64");
+          if (!sizeChecked) {
+            sizeChecked = true;
+            const w = imageWidth(data, opts.format);
+            if (w !== null && w < expectedW * 0.9) {
+              log.warn(
+                `screencast emits ${w}px-wide frames (need ${expectedW} for zoom headroom) \u2014 reverting to the 2x screenshot loop`
+              );
+              this.screencastActive = false;
+              void withTimeout(this.captureCdp.send("Page.stopScreencast"), 2e3).catch(() => {
+              });
+              this.startScreenshotLoop(opts);
+              return;
+            }
+          }
+          const tNodeMs = ev.metadata?.timestamp ? ev.metadata.timestamp * 1e3 - this.clockOffset : Date.now();
+          this.lastFrameNodeMs = tNodeMs;
+          this.captureOnFrame({ data, tNodeMs });
+        });
+        await this.captureCdp.send("Page.startScreencast", {
+          format: opts.format,
+          quality: opts.quality,
+          maxWidth: expectedW,
+          maxHeight: Math.round(vp.height * opts.scale),
+          // Compositor paints at up to ~60; halve toward the requested rate.
+          everyNthFrame: Math.max(1, Math.round(60 / Math.max(15, opts.fps * 1.25)))
+        });
+        this.screencastActive = true;
+        return;
+      } catch (e) {
+        log.warn(`screencast unavailable (${e.message.split("\n")[0]}) \u2014 falling back to the paced screenshot loop`);
+      }
+    }
+    this.startScreenshotLoop(opts);
+  }
+  startScreenshotLoop(opts) {
     const intervalMs = 1e3 / opts.fps;
     this.captureLoop = (async () => {
       while (this.captureActive) {
@@ -1437,7 +1740,8 @@ var PlaywrightDriver = class _PlaywrightDriver {
       }
     })();
   }
-  /** Grab a frame, coalescing on any in-flight grab (so callers can await the current one). */
+  /** Grab a frame, coalescing on any in-flight grab (so callers can await the current one).
+   *  Resolves true iff a frame was actually stored. */
   grabFrame() {
     if (this.inflightGrab) return this.inflightGrab;
     this.inflightGrab = this.doGrab().finally(() => {
@@ -1447,7 +1751,7 @@ var PlaywrightDriver = class _PlaywrightDriver {
   }
   grabFailures = 0;
   async doGrab() {
-    if (!this.captureOpts || !this.captureOnFrame) return;
+    if (!this.captureOpts || !this.captureOnFrame) return false;
     try {
       const opts = this.captureOpts;
       const vp = this.page.viewportSize() ?? { width: 1280, height: 720 };
@@ -1456,7 +1760,9 @@ var PlaywrightDriver = class _PlaywrightDriver {
         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 },
+          // Under --force-device-scale-factor the surface is already scaled — divide it out
+          // or screenshots come back double-scaled (5120-wide).
+          clip: { x: scroll.x, y: scroll.y, width: vp.width, height: vp.height, scale: opts.scale / this.forcedDsf },
           captureBeyondViewport: false
         }),
         1500
@@ -1465,7 +1771,9 @@ var PlaywrightDriver = class _PlaywrightDriver {
       this.lastFrameNodeMs = tNodeMs;
       this.grabFailures = 0;
       this.captureOnFrame({ data: Buffer.from(shot.data, "base64"), tNodeMs });
-    } catch {
+      return true;
+    } catch (err) {
+      log.debug(`frame grab failed: ${err.message.split("\n")[0]}`);
       this.grabFailures += 1;
       if (this.grabFailures >= 2) {
         try {
@@ -1477,6 +1785,7 @@ var PlaywrightDriver = class _PlaywrightDriver {
         } catch {
         }
       }
+      return false;
     }
   }
   async readScroll() {
@@ -1490,6 +1799,11 @@ var PlaywrightDriver = class _PlaywrightDriver {
   }
   async stopCapture() {
     this.captureActive = false;
+    if (this.screencastActive) {
+      this.screencastActive = false;
+      await withTimeout(this.captureCdp.send("Page.stopScreencast"), 2e3).catch(() => {
+      });
+    }
     await this.captureLoop?.catch(() => {
     });
     this.captureLoop = null;
@@ -1498,9 +1812,12 @@ var PlaywrightDriver = class _PlaywrightDriver {
     return this.lastFrameNodeMs;
   }
   async captureNow() {
-    if (this.inflightGrab) await this.inflightGrab.catch(() => {
-    });
-    await this.grabFrame();
+    if (this.inflightGrab) await this.inflightGrab.catch(() => false);
+    for (let i = 0; i < 3; i++) {
+      if (await this.grabFrame()) return;
+      await sleep(120);
+    }
+    log.warn("captureNow: no frame stored after 3 attempts \u2014 footage may hold a stale state here");
   }
 };
 function toPw(m) {
@@ -1539,10 +1856,29 @@ function withTimeout(p, ms) {
     );
   });
 }
+function imageWidth(data, format) {
+  try {
+    if (format === "png") {
+      return data.length >= 24 ? data.readUInt32BE(16) : null;
+    }
+    let i = 2;
+    while (i + 9 < data.length) {
+      if (data[i] !== 255) return null;
+      const marker = data[i + 1];
+      if (marker >= 192 && marker <= 195) return data.readUInt16BE(i + 7);
+      const len = data.readUInt16BE(i + 2);
+      i += 2 + len;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 
 // src/bundle/writer.ts
 import { mkdir, writeFile } from "fs/promises";
-import { join } from "path";
+import { createHash as createHash2 } from "crypto";
+import { join as join2 } from "path";
 import sharp from "sharp";
 
 // src/bundle/hash.ts
@@ -1560,14 +1896,35 @@ function sha256File(path) {
 
 // src/shared/version.ts
 import { createRequire } from "module";
-var PLAYHEAD_VERSION = createRequire(import.meta.url)("../../package.json").version;
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join } from "path";
+import { existsSync, readFileSync } from "fs";
+function resolveOwnPackageJson() {
+  let dir = dirname2(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const p = join(dir, "package.json");
+    if (existsSync(p)) {
+      const pkg = JSON.parse(readFileSync(p, "utf8"));
+      if (pkg.name === "playhead-cli" || pkg.name === "playhead") return { version: pkg.version ?? "0.0.0" };
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  try {
+    return createRequire(import.meta.url)("../../package.json");
+  } catch {
+    return { version: "0.0.0" };
+  }
+}
+var PLAYHEAD_VERSION = resolveOwnPackageJson().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(() => {
+    this.ready = mkdir(join2(dir, "frames"), { recursive: true }).then(() => {
     });
   }
   dir;
@@ -1576,14 +1933,22 @@ var BundleWriter = class {
   pendingWrites = [];
   maskSamples = [];
   counter = 0;
+  failedFrames = /* @__PURE__ */ new Set();
+  writeError;
   ready;
-  /** Queue a frame write. `t` is capture-relative ms. */
+  /** Queue a frame write. `t` is capture-relative ms. Each frame's BYTES are hashed at write
+   *  time — the index entry carries the digest, so the framesIndex hash transitively covers
+   *  every pixel in the bundle. (Round-2 audit: filename+timestamp hashing left frame images
+   *  freely swappable under a passing attest.) */
   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.frames.push({ f: name, t: round1(t), h: createHash2("sha256").update(data).digest("hex") });
     this.pendingWrites.push(
-      this.ready.then(() => writeFile(join(this.dir, "frames", name), data))
+      this.ready.then(() => writeFile(join2(this.dir, "frames", name), data)).catch((e) => {
+        this.failedFrames.add(name);
+        this.writeError ??= e;
+      })
     );
   }
   addMaskSample(sample) {
@@ -1595,21 +1960,28 @@ var BundleWriter = class {
   async finish(meta) {
     await this.ready;
     await Promise.all(this.pendingWrites);
+    if (this.failedFrames.size > 0) {
+      this.frames = this.frames.filter((f) => !this.failedFrames.has(f.f));
+      log.warn(`${this.failedFrames.size} frame write(s) failed (${this.writeError?.message?.split("\n")[0]}) \u2014 those frames dropped from the index`);
+    }
     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();
+      const info = await sharp(join2(this.dir, "frames", first.f)).metadata();
       if (info.width && info.height) {
         frameW = info.width;
         frameH = info.height;
       }
     }
+    meta.events.meta.frameW = frameW;
+    meta.events.meta.frameH = frameH;
+    const spec = redactMaskedText(meta.spec);
     const manifest = {
       schema: "playhead/bundle@1",
       playheadVersion: PLAYHEAD_VERSION,
-      specHash: sha256Json(meta.spec),
+      specHash: sha256Json(spec),
       appUrl: meta.appUrl,
       viewport: meta.viewport,
       dpr: meta.dpr,
@@ -1628,15 +2000,24 @@ var BundleWriter = class {
       ...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))
+      writeFile(join2(this.dir, "frames", "index.json"), JSON.stringify(this.frames)),
+      writeFile(join2(this.dir, "events.json"), JSON.stringify(meta.events, null, 2)),
+      writeFile(join2(this.dir, "masks.json"), JSON.stringify(this.maskSamples, null, 2)),
+      writeFile(join2(this.dir, "spec.resolved.json"), JSON.stringify(spec, null, 2)),
+      writeFile(join2(this.dir, "manifest.json"), JSON.stringify(manifest, null, 2))
     ]);
     return manifest;
   }
 };
+function redactMaskedText(spec) {
+  const copy = JSON.parse(JSON.stringify(spec));
+  for (const scene of copy.scenes) {
+    for (const step of scene.steps) {
+      if (step.action === "type" && step.mask && step.text) step.text = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+    }
+  }
+  return copy;
+}
 function round1(n) {
   return Math.round(n * 10) / 10;
 }
@@ -1696,18 +2077,6 @@ function projectPoint(p, cam, plane2) {
   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;
@@ -1716,7 +2085,7 @@ 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 bundleDir = join3(opts.outDir, "capture");
   const driver = opts.driver ?? new PlaywrightDriver();
   const dpr = 2;
   const format = opts.captureFormat ?? "jpeg";
@@ -1750,18 +2119,20 @@ async function capture(spec, opts) {
   try {
     clockOffsetMs = await driver.measureClockOffset();
     t0 = Date.now();
+    let recordEvents = !opts.fromScene;
     driver.onNavigation((url, tNode) => {
-      events.push({ type: "navigation", url, t: rel(tNode) });
+      if (recordEvents) 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
+      // The screencast source delivers paint-driven frames up to ~30fps during motion; the
+      // paced screenshot fallback (PLAYHEAD_CAPTURE=screenshot) tops out ~20.
+      fps: 30
     });
-    if (!opts.fromScene) await startFilming();
+    const preRoll = spec.setup.length > 0 || Boolean(opts.fromScene);
+    if (!preRoll) await startFilming();
     await driver.installMaskRules(maskRules);
     await driver.goto(spec.app.url);
     await applyMasksAndSample(driver, maskRules, writer, now);
@@ -1773,7 +2144,15 @@ async function capture(spec, opts) {
         );
       });
     }
-    if (!opts.fromScene) await driver.captureNow();
+    if (!preRoll) await driver.captureNow();
+    if (spec.setup.length > 0) {
+      log.info(`running ${spec.setup.length} setup step(s) (state only, not filmed)`);
+      for (const [i, s] of spec.setup.entries()) {
+        currentStepRef = `setup/${i}`;
+        await fastForwardStep(driver, s);
+      }
+      currentStepRef = "";
+    }
     let steps = flattenSteps(spec);
     const totalSteps = steps.length;
     if (opts.fromScene) {
@@ -1786,7 +2165,10 @@ async function capture(spec, opts) {
       }
       currentStepRef = "";
       steps = steps.slice(idx);
+    }
+    if (preRoll) {
       await driver.settle(settleCfg);
+      recordEvents = true;
       await startFilming();
       await driver.captureNow();
     }
@@ -1796,11 +2178,20 @@ async function capture(spec, opts) {
         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
-      );
+      let event;
+      try {
+        event = await withStepBudget(
+          executeStep(driver, addressed, { rel, now }, spec.app.url),
+          STEP_BUDGET_MS,
+          currentStepRef
+        );
+      } catch (e) {
+        if (addressed.step.optional) {
+          log.warn(`optional step ${currentStepRef} skipped: ${e.message.split("\n")[0]}`);
+          continue;
+        }
+        throw e;
+      }
       await applyMasksAndSample(driver, maskRules, writer, now);
       await driver.settle(settleCfg);
       const focus = "focus" in addressed.step ? addressed.step.focus : void 0;
@@ -1838,10 +2229,10 @@ async function capture(spec, opts) {
       const url = driver.currentUrl();
       const { writeFile: writeFile6 } = await import("fs/promises");
       await writeFile6(
-        join2(bundleDir, "failure.json"),
+        join3(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);
+      if (aria) await writeFile6(join3(bundleDir, "failure-aria.txt"), aria);
     } catch {
     }
     throw new FlowError(
@@ -1856,7 +2247,7 @@ async function capture(spec, opts) {
       if (consoleLog.length > 0) {
         const { writeFile: writeFile6 } = await import("fs/promises");
         await writeFile6(
-          join2(bundleDir, "console.json"),
+          join3(bundleDir, "console.json"),
           JSON.stringify(consoleLog.map((c) => ({ ...c, t: rel(c.t) })), null, 2)
         );
       }
@@ -1908,13 +2299,15 @@ async function fastForwardStep(driver, step) {
       break;
     case "click":
     case "dblclick": {
-      const t = await driver.resolveTarget(parseLocator(step.target), T);
-      await driver.clickAt(rectCenter(t.bbox), { double: step.action === "dblclick" });
+      await driver.resolveTarget(parseLocator(step.target), T);
+      await driver.actClick(parseLocator(step.target), { double: step.action === "dblclick", timeoutMs: T });
       break;
     }
-    case "hover":
+    case "hover": {
+      const t = await driver.resolveTarget(parseLocator(step.target), T);
+      await driver.moveCursor(rectCenter(t.bbox), 60);
       break;
-    // no lasting state
+    }
     case "type": {
       const t = await driver.resolveTarget(parseLocator(step.target), T);
       await driver.clickAt(rectCenter(t.bbox));
@@ -1932,8 +2325,23 @@ async function fastForwardStep(driver, step) {
       else if (step.by) await driver.scrollBy(step.by);
       await driver.waitForScrollSettle(1500);
       break;
+    case "rightclick": {
+      await driver.resolveTarget(parseLocator(step.target), T);
+      await driver.actClick(parseLocator(step.target), { button: "right", timeoutMs: T });
+      break;
+    }
+    case "upload":
+      await driver.setInputFiles(parseLocator(step.target), step.file);
+      break;
+    case "drag":
+      await driver.dragTo(parseLocator(step.target), parseLocator(step.to), T);
+      break;
     case "expect":
-      await driver.expectState(parseLocator(step.target), { ...step.visible !== void 0 ? { visible: step.visible } : {} }, T).catch(() => {
+      await driver.expectState(
+        step.target ? parseLocator(step.target) : null,
+        { ...step.visible !== void 0 ? { visible: step.visible } : {}, ...step.url !== void 0 ? { url: step.url } : {} },
+        T
+      ).catch(() => {
       });
       break;
     case "wait":
@@ -2019,6 +2427,9 @@ async function executeStep(driver, addressed, clock, appUrl) {
       base.targetPre = pre;
       base.cursorPath = await moveToTarget(driver, pre, clock);
       await driver.actClick(loc, { timeoutMs: budgetMs });
+      if (step.clear) {
+        await driver.press("ControlOrMeta+A");
+      }
       if (step.mask) {
         await driver.setTypingMask(loc);
       }
@@ -2048,6 +2459,42 @@ async function executeStep(driver, addressed, clock, appUrl) {
       base.tActionEnd = clock.now();
       return base;
     }
+    case "rightclick": {
+      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);
+      const { tDown, tUp } = await driver.actClick(loc, { button: "right", timeoutMs: budgetMs });
+      base.tAction = clock.rel(tDown);
+      base.tActionEnd = clock.rel(tUp);
+      return base;
+    }
+    case "upload": {
+      base.locator = step.target;
+      const loc = parseLocator(step.target);
+      base.targetPre = await driver.tryMeasure(loc);
+      if (base.targetPre) base.cursorPath = await moveToTarget(driver, base.targetPre, clock);
+      base.tAction = clock.now();
+      await driver.setInputFiles(loc, step.file);
+      base.typedText = step.file.split(/[\\/]/).pop() ?? step.file;
+      base.tActionEnd = clock.now();
+      return base;
+    }
+    case "drag": {
+      base.locator = step.target;
+      const from = parseLocator(step.target);
+      const to = parseLocator(step.to);
+      const pre = await driver.resolveTarget(from, budgetMs);
+      base.targetPre = pre;
+      base.cursorPath = await moveToTarget(driver, pre, clock);
+      const { tDown, tUp, path } = await driver.dragTo(from, to, budgetMs);
+      base.cursorPath = [...base.cursorPath, ...path.map((w) => ({ ...w, t: clock.rel(w.t) }))];
+      base.tAction = clock.rel(tDown);
+      base.tActionEnd = clock.rel(tUp);
+      base.targetPost = await driver.tryMeasure(to);
+      return base;
+    }
     case "scroll": {
       base.tAction = clock.now();
       if (step.target) {
@@ -2064,14 +2511,22 @@ async function executeStep(driver, addressed, clock, appUrl) {
       return base;
     }
     case "expect": {
-      base.locator = step.target;
-      const loc = parseLocator(step.target);
+      base.locator = step.target ?? step.url ?? "";
+      const loc = step.target ? parseLocator(step.target) : null;
       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.visible !== void 0 ? { visible: step.visible } : {},
+          ...step.text !== void 0 ? { text: step.text } : {},
+          ...step.count !== void 0 ? { count: step.count } : {},
+          ...step.url !== void 0 ? { url: step.url } : {},
+          ...step.value !== void 0 ? { value: step.value } : {},
+          ...step.disabled !== void 0 ? { disabled: step.disabled } : {},
+          ...step.checked !== void 0 ? { checked: step.checked } : {}
+        },
         step.timeout ?? EXPECT_TIMEOUT_MS
       );
-      base.targetPre = await driver.tryMeasure(loc);
+      if (loc) base.targetPre = await driver.tryMeasure(loc);
       base.tAction = clock.now();
       base.tActionEnd = base.tAction;
       return base;
@@ -2097,6 +2552,7 @@ 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);
+  await driver.captureNow();
   return waypoints.map((w) => ({ x: round12(w.x), y: round12(w.y), t: round12(clock.rel(w.t)) }));
 }
 async function ensurePostActionFrame(driver, tAction, rel) {
@@ -2143,13 +2599,13 @@ function round12(n) {
 
 // src/bundle/reader.ts
 import { readFile as readFile2 } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } 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(() => "[]")
+    readFile2(join4(dir, "manifest.json"), "utf8"),
+    readFile2(join4(dir, "events.json"), "utf8"),
+    readFile2(join4(dir, "frames", "index.json"), "utf8"),
+    readFile2(join4(dir, "masks.json"), "utf8").catch(() => "[]")
   ]);
   const manifest = JSON.parse(manifestRaw);
   if (manifest.schema !== "playhead/bundle@1") {
@@ -2174,16 +2630,16 @@ function frameIndexForTime(frames, tMs) {
   return lo;
 }
 function framePath(bundle, index) {
-  return join3(bundle.dir, "frames", bundle.frames[index].f);
+  return join4(bundle.dir, "frames", bundle.frames[index].f);
 }
 
 // src/compose/index.ts
-import { join as join7 } from "path";
+import { join as join8 } 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 { existsSync as existsSync2 } from "fs";
+import { join as join5, dirname as dirname3 } from "path";
 import { createRequire as createRequire2 } from "module";
 import { GlobalFonts } from "@napi-rs/canvas";
 var DEFAULT_THEME = {
@@ -2217,7 +2673,7 @@ function registerFonts() {
   const require5 = createRequire2(import.meta.url);
   let pkgDir;
   try {
-    pkgDir = dirname2(require5.resolve("@expo-google-fonts/inter/package.json"));
+    pkgDir = dirname3(require5.resolve("@expo-google-fonts/inter/package.json"));
   } catch {
     throw new Error("Font package @expo-google-fonts/inter not found \u2014 run npm install");
   }
@@ -2228,8 +2684,8 @@ function registerFonts() {
     ["700Bold/Inter_700Bold.ttf", "Inter Bold"]
   ];
   for (const [rel, family] of faces) {
-    const p = join4(pkgDir, rel);
-    if (existsSync(p)) GlobalFonts.registerFromPath(p, family);
+    const p = join5(pkgDir, rel);
+    if (existsSync2(p)) GlobalFonts.registerFromPath(p, family);
   }
 }
 
@@ -2237,17 +2693,24 @@ function registerFonts() {
 function stageContent(profile) {
   return profile.stage?.content ?? { x: 0, y: 0, w: profile.width, h: profile.height };
 }
-function withStage(profile, chrome) {
+function withStage(profile, chrome, viewportAspect) {
   const { width, height } = profile;
+  const va = viewportAspect ?? width / height;
+  const ui = Math.min(width, height) / 1080;
   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 marginX = Math.round(width * 0.05);
+  const chromeH = chrome ? Math.round(44 * ui) : 0;
+  let contentH = height - 2 * marginY - chromeH;
+  let contentW = Math.round(contentH * va);
+  if (contentW > width - 2 * marginX) {
+    contentW = width - 2 * marginX;
+    contentH = Math.round(contentW / va);
+  }
   const x = Math.round((width - contentW) / 2);
-  const y = marginY + chromeH;
+  const y = Math.round((height - contentH - chromeH) / 2) + chromeH;
   return {
     ...profile,
-    stage: { content: { x, y, w: contentW, h: contentH }, chromeH, radius: Math.round(14 * (Math.min(width, height) / 1080)) }
+    stage: { content: { x, y, w: contentW, h: contentH }, chromeH, radius: Math.round(14 * ui) }
   };
 }
 var PROFILE_16x9 = {
@@ -2257,7 +2720,8 @@ var PROFILE_16x9 = {
   safeArea: { top: 54, right: 96, bottom: 160, left: 96 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 110,
-  captionMaxWidth: 1040
+  captionMaxWidth: 1040,
+  uiScale: 1
 };
 var PROFILE_9x16 = {
   width: 1080,
@@ -2266,7 +2730,8 @@ var PROFILE_9x16 = {
   safeArea: { top: 230, right: 56, bottom: 320, left: 56 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 96,
-  captionMaxWidth: 980
+  captionMaxWidth: 980,
+  uiScale: 1
 };
 var PROFILE_1x1 = {
   width: 1080,
@@ -2275,7 +2740,8 @@ var PROFILE_1x1 = {
   safeArea: { top: 80, right: 72, bottom: 200, left: 72 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 100,
-  captionMaxWidth: 940
+  captionMaxWidth: 940,
+  uiScale: 1
 };
 function profileForAspect(aspect, resolution, fps) {
   const base = aspect === "9:16" ? PROFILE_9x16 : aspect === "1:1" ? PROFILE_1x1 : PROFILE_16x9;
@@ -2292,7 +2758,8 @@ function profileForAspect(aspect, resolution, fps) {
       left: Math.round(base.safeArea.left * scaleX),
       right: Math.round(base.safeArea.right * scaleX)
     },
-    captionMaxWidth: Math.round(base.captionMaxWidth * scaleX)
+    captionMaxWidth: Math.round(base.captionMaxWidth * scaleX),
+    uiScale: Math.min(resolution.w, resolution.h) / 1080
   };
 }
 function actReactWindows(step) {
@@ -2380,6 +2847,9 @@ function pacingConfig(mode, kind) {
       type: 450 * factor,
       press: 450 * factor,
       select: 600 * factor,
+      rightclick: 700 * factor,
+      upload: 800 * factor,
+      drag: 700 * factor,
       scroll: 350 * factor,
       expect: 800 * factor,
       wait: 150
@@ -2404,10 +2874,37 @@ function buildTimeline(log2, cfg, audioMs) {
     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 outBeat;
+    if (e.kind === "type" && spanSrc > cfg.maxTypeOutMs) {
+      const HEAD_MS = 1200;
+      const TAIL_MS = 700;
+      const headSrc = Math.min(HEAD_MS, spanSrc * 0.4);
+      const tailSrc = Math.min(TAIL_MS, spanSrc * 0.25);
+      const midSrc = spanSrc - headSrc - tailSrc;
+      const midOut = Math.max(250, cfg.maxTypeOutMs - headSrc - tailSrc);
+      segments.push({ kind: "source", outStart: out, outEnd: out + headSrc, srcStart: e.tStart, srcEnd: e.tStart + headSrc });
+      segments.push({
+        kind: "source",
+        outStart: out + headSrc,
+        outEnd: out + headSrc + midOut,
+        srcStart: e.tStart + headSrc,
+        srcEnd: e.tStart + headSrc + midSrc
+      });
+      segments.push({
+        kind: "source",
+        outStart: out + headSrc + midOut,
+        outEnd: out + headSrc + midOut + tailSrc,
+        srcStart: srcEnd - tailSrc,
+        srcEnd
+      });
+      spanOut = headSrc + midOut + tailSrc;
+      outBeat = out + Math.min(e.tAction - e.tStart, headSrc);
+      out += spanOut;
+    } else {
+      segments.push({ kind: "source", outStart: out, outEnd: out + spanOut, srcStart: e.tStart, srcEnd });
+      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}`);
@@ -2436,6 +2933,7 @@ function buildTimeline(log2, cfg, audioMs) {
       ...e.focus ? { focus: e.focus } : {},
       ...e.shot ? { shot: e.shot } : {},
       ...e.focusTarget ? { focusRectVp: e.focusTarget.bbox } : {},
+      ...e.targetPre && !e.targetPost ? { targetGone: true } : {},
       outStart: stepOutStart,
       outBeat,
       outEnd: out,
@@ -2462,6 +2960,18 @@ function sampleSource(segments, tOut) {
     }
   }
 }
+function outTimeForSrc(segments, tSrc) {
+  for (const seg of segments) {
+    if (seg.kind === "source" && tSrc >= seg.srcStart && tSrc <= seg.srcEnd) {
+      const u = (tSrc - seg.srcStart) / Math.max(1e-6, seg.srcEnd - seg.srcStart);
+      return seg.outStart + u * (seg.outEnd - seg.outStart);
+    }
+    if (seg.kind === "freeze" && Math.abs(seg.srcAt - tSrc) < 400) {
+      return seg.outStart + (seg.outEnd - seg.outStart) / 2;
+    }
+  }
+  return null;
+}
 function segmentAt(segments, tOut) {
   let lo = 0;
   let hi = segments.length - 1;
@@ -2495,13 +3005,48 @@ function sampleCamera(keyframes, tOut) {
   }
   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)
-  };
+  const dt = Math.max(1e-6, b.tOut - a.tOut);
+  const u = (tOut - a.tOut) / dt;
+  if (sameState(a.state, b.state)) return { ...a.state };
+  const va = [a.state.cx, a.state.cy, Math.log(a.state.zoom)];
+  const vb = [b.state.cx, b.state.cy, Math.log(b.state.zoom)];
+  const TENSION = 0.5;
+  const ma = tangentAt(keyframes, lo, TENSION);
+  const mb = tangentAt(keyframes, hi, TENSION);
+  const isolated = ma.every((m) => m === 0) && mb.every((m) => m === 0);
+  if (isolated) {
+    const e = cubicBezier(b.ease, u);
+    return {
+      cx: va[0] + (vb[0] - va[0]) * e,
+      cy: va[1] + (vb[1] - va[1]) * e,
+      zoom: Math.exp(va[2] + (vb[2] - va[2]) * e)
+    };
+  }
+  const u2 = u * u;
+  const u3 = u2 * u;
+  const h00 = 2 * u3 - 3 * u2 + 1;
+  const h10 = u3 - 2 * u2 + u;
+  const h01 = -2 * u3 + 3 * u2;
+  const h11 = u3 - u2;
+  const out = [0, 0, 0];
+  for (let c = 0; c < 3; c++) {
+    out[c] = h00 * va[c] + h10 * dt * ma[c] + h01 * vb[c] + h11 * dt * mb[c];
+  }
+  return { cx: out[0], cy: out[1], zoom: Math.exp(out[2]) };
+}
+function tangentAt(keyframes, i, tension) {
+  const cur = keyframes[i];
+  const prev = i > 0 ? keyframes[i - 1] : null;
+  const next = i < keyframes.length - 1 ? keyframes[i + 1] : null;
+  if (!prev || !next) return [0, 0, 0];
+  if (sameState(prev.state, cur.state) || sameState(cur.state, next.state)) return [0, 0, 0];
+  const dt = Math.max(1e-6, next.tOut - prev.tOut);
+  const vp = [prev.state.cx, prev.state.cy, Math.log(prev.state.zoom)];
+  const vn = [next.state.cx, next.state.cy, Math.log(next.state.zoom)];
+  return [0, 1, 2].map((c) => tension * (vn[c] - vp[c]) / dt);
+}
+function sameState(a, b) {
+  return Math.abs(a.cx - b.cx) < 0.5 && Math.abs(a.cy - b.cy) < 0.5 && Math.abs(a.zoom - b.zoom) < 1e-3;
 }
 
 // src/compose/camera/planner.ts
@@ -2528,7 +3073,8 @@ function planCamera(steps, log2, profile, durationMs, opts) {
   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++) {
+  const maxAttempts = Math.max(8, shots.length * (quantums.length + 1));
+  for (let attempt = 0; attempt < maxAttempts; 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);
@@ -2545,7 +3091,9 @@ function planCamera(steps, log2, profile, durationMs, opts) {
       fallbacks.push(`${violation.stepRef}: reduced shot zoom to satisfy framing constraints`);
     }
   }
+  for (const shot of shots) shot.wide = true;
   for (const shot of shots) shot.state = shotState(shot, quantums, plane2, profile, emphasis);
+  fallbacks.push("camera planner exhausted its attempt budget \u2014 all shots forced wide (check for conflicting focus hints)");
   return { keyframes: emitKeyframes(shots, plane2, durationMs), fallbacks };
 }
 function groupShots(steps, navTimes, plane2, durationMs) {
@@ -2620,6 +3168,7 @@ function groupShots(steps, navTimes, plane2, durationMs) {
         continue;
       }
     }
+    const arriveBeat = step.kind === "goto" && rect ? Math.min(step.outEnd - 400, step.outBeat + Math.max(200, step.srcSettled - step.srcAction) + 150) : step.outBeat;
     current = {
       stepRefs: [step.stepRef],
       sceneId: step.sceneId,
@@ -2627,7 +3176,7 @@ function groupShots(steps, navTimes, plane2, durationMs) {
       minTargetDim: rect ? Math.min(rect.w, rect.h) : Math.min(plane2.vpW, plane2.vpH),
       wide,
       outStart: step.outStart,
-      firstBeat: step.outBeat,
+      firstBeat: arriveBeat,
       outEnd: step.outEnd,
       zoomIndex: Number.MAX_SAFE_INTEGER
       // resolved in shotState
@@ -2857,6 +3406,12 @@ function writeCaption(event, texts) {
       return label ? `Enter the ${lowerFirst(label)}` : "Enter a value";
     case "press":
       return `Press ${event.locator ?? "the key"}`;
+    case "rightclick":
+      return label ? `Right-click \u201C${label}\u201D` : "Right-click the element";
+    case "upload":
+      return label ? `Upload a file to ${lowerFirst(label)}` : "Upload the file";
+    case "drag":
+      return label ? `Drag \u201C${label}\u201D into place` : "Drag the item into place";
     case "select":
       return label && event.typedText ? `Choose \u201C${event.typedText}\u201D under ${label}` : label ? `Choose an option under ${label}` : "Choose an option";
     case "goto":
@@ -3001,29 +3556,46 @@ function buildOverlays(steps, log2, theme, profile, title, subtitle, titleCardEn
     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 ui = profile.uiScale;
+    const padX = Math.round(CARD_PAD_X * ui);
+    const padY = Math.round(CARD_PAD_Y * ui);
+    const badgeFontPx = Math.max(11, Math.round(15 * ui));
     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);
+    const badgeW = showBadge ? Math.ceil(measureText(badgeText, `600 ${badgeFontPx}px Inter SemiBold`)) + Math.round(20 * ui) : 0;
+    const badgeGap = showBadge ? Math.round(BADGE_GAP * ui) : 0;
+    const maxTextWidth = Math.min(profile.captionMaxWidth, profile.width - 2 * profile.safeArea.left) - padX * 2 - badgeW - badgeGap;
+    const wrap = wrapText(
+      text,
+      fontFor,
+      maxTextWidth,
+      Math.round(theme.captionFontPx * ui),
+      Math.round(theme.captionMinFontPx * ui),
+      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 cardW = padX * 2 + badgeW + badgeGap + Math.ceil(wrap.widest);
+    const cardH = padY * 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;
+    let y = theme.captionPosition === "bottom" ? profile.height - Math.round(CARD_BOTTOM_MARGIN * ui) - 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 content = stageContent(profile);
+      const capPlane = { vpW: log2.meta.viewport.w, vpH: log2.meta.viewport.h, outW: content.w, outH: content.h };
+      const capBox = { x, y, w: cardW, h: cardH };
+      const handoff = actReactWindows(step);
+      const probes = handoff ? [
+        { rect: handoff.act.rect, t: Math.min(step.outBeat + 250, handoff.act.to) },
+        { rect: handoff.react.rect, t: handoff.react.from + 50 }
+      ] : step.focusRectVp ?? step.targetRectVp ? [{ rect: step.focusRectVp ?? step.targetRectVp, t: Math.min(step.outBeat + 250, step.outEnd) }] : [];
+      for (const probe of probes) {
+        const cam = sampleCamera(camera, probe.t);
+        const proj = projectRect(probe.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;
+        if (overlaps(projFrame, capBox)) {
+          y = profile.safeArea.top;
+          break;
+        }
       }
     }
     const next = captioned[i + 1];
@@ -3151,19 +3723,38 @@ function drawOverlays(ctx2, overlays, tOut, theme, profile) {
   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);
+      const scrimH = Math.round(SCRIM_H * profile.uiScale);
+      const g = ctx2.createLinearGradient(0, profile.height - scrimH, 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);
+      ctx2.fillRect(0, profile.height - scrimH, profile.width, scrimH);
     }
   }
+  const activeCaps = overlays.filter(
+    (o) => o.kind === "caption" && tOut >= o.tStart && tOut <= o.tEnd && captionAlpha(o, tOut) > 0
+  );
+  if (activeCaps.length === 2 && activeCaps[0].box.y === activeCaps[1].box.y) {
+    const [a, b] = activeCaps[0].tStart <= activeCaps[1].tStart ? [activeCaps[0], activeCaps[1]] : [activeCaps[1], activeCaps[0]];
+    const u = captionAlpha(b, tOut);
+    const box = {
+      x: a.box.x + (b.box.x - a.box.x) * u,
+      y: a.box.y,
+      w: a.box.w + (b.box.w - a.box.w) * u,
+      h: Math.max(a.box.h, b.box.h)
+    };
+    drawCaptionCard(ctx2, box, 1, theme);
+    drawCaptionContent(ctx2, a, box, 1 - u, theme);
+    drawCaptionContent(ctx2, b, box, u, theme);
+  } else {
+    for (const o of activeCaps) drawCaption(ctx2, o, tOut, theme);
+  }
   for (const o of overlays) {
     if (tOut < o.tStart || tOut > o.tEnd) continue;
     switch (o.kind) {
       case "caption":
-        drawCaption(ctx2, o, tOut, theme);
         break;
+      // handled by the grouped pass above
       case "dip": {
         const u = (tOut - o.tStart) / Math.max(1, o.tEnd - o.tStart);
         ctx2.save();
@@ -3189,13 +3780,14 @@ 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";
+  const ui = profile.uiScale;
+  const font = `600 ${Math.round(26 * ui)}px 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 padX = 16 * ui;
+  const w = textW + padX * 2 + 30 * ui;
+  const h = 44 * ui;
   const x = profile.width - profile.safeArea.right - w;
   const y = profile.safeArea.top;
   ctx2.fillStyle = "rgba(18,22,31,0.82)";
@@ -3203,13 +3795,13 @@ function drawElapsedClock(ctx2, zeroAtMs, tOut, theme, profile) {
   ctx2.fill();
   ctx2.fillStyle = "#ef4444";
   ctx2.beginPath();
-  ctx2.arc(x + padX + 6, y + h / 2, 6, 0, Math.PI * 2);
+  ctx2.arc(x + padX + 6 * ui, y + h / 2, 6 * ui, 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.fillText(label, x + padX + 24 * ui, y + h / 2 + 1);
   ctx2.restore();
 }
 function drawChapterLabel(ctx2, o, tOut, theme, profile) {
@@ -3217,23 +3809,24 @@ function drawChapterLabel(ctx2, o, tOut, theme, profile) {
   if (alpha <= 0) return;
   ctx2.save();
   ctx2.globalAlpha = alpha;
-  const font = "700 30px Inter Bold";
+  const ui = profile.uiScale;
+  const font = `700 ${Math.round(30 * ui)}px Inter Bold`;
   ctx2.font = font;
   const textW = ctx2.measureText(o.title).width;
-  const barW = textW + 96;
-  const barH = 56;
+  const barW = textW + 96 * ui;
+  const barH = 56 * ui;
   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.font = `600 ${Math.round(16 * ui)}px Inter SemiBold`;
   ctx2.textAlign = "left";
   ctx2.textBaseline = "middle";
-  ctx2.fillText(String(o.ordinal), x + 22, y + barH / 2 + 1);
+  ctx2.fillText(String(o.ordinal), x + 22 * ui, y + barH / 2 + 1);
   ctx2.font = font;
-  ctx2.fillText(o.title, x + 48, y + barH / 2 + 1);
+  ctx2.fillText(o.title, x + 48 * ui, y + barH / 2 + 1);
   ctx2.restore();
 }
 function captionAlpha(o, tOut) {
@@ -3242,23 +3835,36 @@ function captionAlpha(o, tOut) {
 function drawCaption(ctx2, o, tOut, theme) {
   const alpha = captionAlpha(o, tOut);
   if (alpha <= 0) return;
+  ctx2.save();
+  ctx2.globalAlpha = alpha;
+  drawCaptionCard(ctx2, o.box, 1, theme);
+  ctx2.restore();
+  drawCaptionContent(ctx2, o, o.box, alpha, theme);
+}
+function drawCaptionCard(ctx2, box, alpha, theme) {
   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);
+  roundRect(ctx2, box.x, box.y, box.w, box.h, theme.radius);
   ctx2.fill();
-  ctx2.shadowColor = "transparent";
+  ctx2.restore();
+}
+function drawCaptionContent(ctx2, o, box, alpha, theme) {
+  if (alpha <= 0) return;
+  ctx2.save();
+  ctx2.globalAlpha = alpha;
   let badgeW = 0;
-  const bx = o.box.x + 26;
+  const bx = 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;
+    const bScale = o.fontPx / 36;
+    const badgeFont = `600 ${Math.max(11, Math.round(15 * bScale))}px Inter SemiBold`;
+    badgeW = Math.ceil(measureText(badgeText, badgeFont)) + Math.round(20 * bScale);
+    const badgeH = Math.round(26 * bScale);
+    const by = box.y + box.h / 2 - badgeH / 2;
     ctx2.fillStyle = theme.accent;
     roundRect(ctx2, bx, by, badgeW, badgeH, 13);
     ctx2.fill();
@@ -3270,7 +3876,7 @@ function drawCaption(ctx2, o, tOut, theme) {
   }
   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;
+  const textTop = box.y + (box.h - o.lines.length * lineH) / 2;
   ctx2.fillStyle = theme.onSurface;
   ctx2.font = `${o.fontPx}px Inter Medium`;
   ctx2.textAlign = "left";
@@ -3294,16 +3900,17 @@ function drawFailureCard(ctx2, card, tOut, theme, profile) {
   ctx2.fillStyle = "#ef4444";
   roundRect(ctx2, width / 2 - 32, height / 2 - 150, 64, 8, 4);
   ctx2.fill();
+  const uiF = profile.uiScale;
   ctx2.fillStyle = "#ffffff";
-  ctx2.font = `52px Inter Bold`;
+  ctx2.font = `${Math.round(52 * uiF)}px 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.font = `600 ${Math.round(30 * uiF)}px 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`;
+  ctx2.font = `${Math.round(24 * uiF)}px Inter`;
   const maxW = Math.min(1200, width - 200);
   const words = card.message.replace(/\s+/g, " ").split(" ");
   const lines = [];
@@ -3344,14 +3951,15 @@ function drawTitleCard(ctx2, card, tOut, theme, profile) {
   ctx2.fill();
   ctx2.globalAlpha = title.alpha;
   ctx2.fillStyle = "#ffffff";
-  ctx2.font = `56px Inter Bold`;
+  const uiT = profile.uiScale;
+  ctx2.font = `${Math.round(56 * uiT)}px 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.font = `${Math.round(26 * uiT)}px Inter`;
     ctx2.fillText(card.subtitle, width / 2, height / 2 + 44 + sub.rise);
   }
   ctx2.restore();
@@ -3371,7 +3979,8 @@ var FrameStore = class {
   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);
+    if (idx + 1 < this.bundle.frames.length) this.get(idx + 1).catch(() => {
+    });
     return canvas;
   }
   /**
@@ -3398,6 +4007,7 @@ var FrameStore = class {
       return hit;
     }
     const promise = this.decode(idx);
+    promise.catch(() => this.cache.delete(idx));
     this.cache.set(idx, promise);
     while (this.cache.size > LRU_SIZE) {
       const oldest = this.cache.keys().next().value;
@@ -3523,12 +4133,19 @@ var Encoder = class {
       this.child.on("error", reject);
       this.child.on("close", (code) => resolve(code ?? -1));
     });
+    this.child.stdin.on("error", () => {
+    });
   }
   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");
+      await Promise.race([
+        once(stdin, "drain"),
+        this.exit.then((code) => {
+          throw new Error(`ffmpeg exited (code ${code}) while the encoder awaited drain: ${this.stderrTail.join("")}`);
+        })
+      ]);
     }
   }
   async finish() {
@@ -3544,6 +4161,7 @@ var Encoder = class {
 var SPOTLIGHT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
 var SPOTLIGHT_LEAD_MS = 200;
 var SPOTLIGHT_TAIL_MS = 650;
+var SPOTLIGHT_TAIL_GONE_MS = 160;
 var SPOTLIGHT_MAX_DIM = 0.34;
 async function renderVideo(bundle, manifest, outPath) {
   registerFonts();
@@ -3575,7 +4193,7 @@ async function renderVideo(bundle, manifest, outPath) {
   );
   const transitions = manifest.transitions ?? [];
   const spotlightSteps = manifest.steps.filter(
-    (s) => SPOTLIGHT_KINDS.has(s.kind) && (s.focusRectVp ?? s.targetRectVp)
+    (s) => SPOTLIGHT_KINDS.has(s.kind) && (s.targetRectVp ?? s.focusRectVp)
   );
   const start = Date.now();
   for (let i = 0; i < manifest.totalFrames; i++) {
@@ -3616,7 +4234,8 @@ async function renderVideo(bundle, manifest, outPath) {
         ctx2.globalAlpha = 1;
       };
       const pair = await store.framePairForTime(srcAt);
-      if (segment.kind === "source" && pair.b && pair.mix > 0.12 && pair.gapMs < 400) {
+      const rate = segment.kind === "source" ? (segment.srcEnd - segment.srcStart) / Math.max(1, segment.outEnd - segment.outStart) : Infinity;
+      if (segment.kind === "source" && rate < 1.5 && pair.b && pair.mix > 0.12 && pair.gapMs < 400) {
         drawSrc(pair.a, 1);
         drawSrc(pair.b, pair.mix);
       } else {
@@ -3632,7 +4251,7 @@ async function renderVideo(bundle, manifest, outPath) {
       }
       const spot = activeSpotlight(spotlightSteps, tOut);
       if (spot) {
-        const rect = spot.step.focusRectVp ?? spot.step.targetRectVp;
+        const rect = spot.step.targetRectVp ?? spot.step.focusRectVp;
         const proj = projectRect(rect, cam, plane2);
         drawSpotlight(spotCtx, content, proj, spot.alpha);
         ctx2.drawImage(spotCanvas, content.x, content.y);
@@ -3728,11 +4347,12 @@ function displayUrl(appUrl) {
 }
 function activeSpotlight(steps, tOut) {
   for (const step of steps) {
+    const tail = step.targetGone ? SPOTLIGHT_TAIL_GONE_MS : SPOTLIGHT_TAIL_MS;
     const from = step.outBeat - SPOTLIGHT_LEAD_MS;
-    const to = step.outBeat + SPOTLIGHT_TAIL_MS;
+    const to = step.outBeat + tail;
     if (tOut < from || tOut > to) continue;
     const rampIn = clamp((tOut - from) / 180, 0, 1);
-    const rampOut = clamp((to - tOut) / 250, 0, 1);
+    const rampOut = clamp((to - tOut) / Math.min(250, tail), 0, 1);
     return { step, alpha: SPOTLIGHT_MAX_DIM * Math.min(rampIn, rampOut) };
   }
   return null;
@@ -3758,33 +4378,178 @@ function cursorGlyphAt(steps, tOut) {
   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]);
+// 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));
   }
-};
-var KokoroProvider = class {
-  constructor(voice, speed) {
+  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/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 existsSync3 } from "fs";
+import { join as join6 } from "path";
+import { createHash as createHash3 } 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]);
+  }
+};
+var KokoroProvider = class {
+  constructor(voice, speed) {
     this.voice = voice;
     this.speed = speed;
   }
@@ -3858,9 +4623,9 @@ async function synthesizeNarration(lines, opts, cacheDir) {
   const ext = provider.name === "kokoro" ? "wav" : "aiff";
   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}.${ext}`);
-    if (!existsSync2(file)) await provider.synth(text, file);
+    const key = createHash3("sha256").update(`${provider.name}|${voice}|${rate}|${text}`).digest("hex").slice(0, 16);
+    const file = join6(cacheDir, `${key}.${ext}`);
+    if (!existsSync3(file)) await provider.synth(text, file);
     out.set(stepRef, { stepRef, file, durationMs: await probeDurationMs(file) });
   }
   return out;
@@ -3870,8 +4635,8 @@ async function synthesizeNarration(lines, opts, cacheDir) {
 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 { existsSync as existsSync4 } from "fs";
+import { join as join7 } from "path";
 import { createRequire as createRequire5 } from "module";
 var require4 = createRequire5(import.meta.url);
 var ffmpegPath2 = require4("ffmpeg-static");
@@ -3879,8 +4644,9 @@ 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 keyBeats = opts.keyBeats ?? [];
   const hasMusic = !!opts.music;
-  if (placed.length === 0 && beats.length === 0 && !hasMusic) return [];
+  if (placed.length === 0 && beats.length === 0 && keyBeats.length === 0 && !hasMusic) return [];
   const durSec = (durationMs / 1e3).toFixed(3);
   const args = ["-y", "-loglevel", "error", "-i", videoPath];
   const inputs = [];
@@ -3918,6 +4684,21 @@ async function mixAudio(videoPath, steps, durationMs, opts) {
     filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0:duration=longest[sfx]`);
     inputs.push("[sfx]");
   }
+  if (keyBeats.length > 0) {
+    const key = await ensureKeySample(opts.cacheDir);
+    args.push("-i", key);
+    const idx = inputIdx++;
+    const splits = keyBeats.map((_, i) => `[k${i}]`).join("");
+    filters.push(`[${idx}]aformat=sample_rates=44100:channel_layouts=stereo,asplit=${keyBeats.length}${splits}`);
+    const labels = [];
+    keyBeats.forEach((t, i) => {
+      const at = Math.max(0, Math.round(t));
+      filters.push(`[k${i}]adelay=${at}|${at}[kk${i}]`);
+      labels.push(`[kk${i}]`);
+    });
+    filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0:duration=longest[keys]`);
+    inputs.push("[keys]");
+  }
   if (opts.music) {
     args.push("-stream_loop", "-1", "-i", opts.music.file);
     const idx = inputIdx++;
@@ -3961,10 +4742,28 @@ async function mixAudio(videoPath, steps, durationMs, opts) {
   await rename(tmp, videoPath);
   return placed.map((p) => ({ stepRef: p.clip.stepRef, tStart: p.start, durMs: p.clip.durationMs }));
 }
+async function ensureKeySample(cacheDir) {
+  await mkdir3(cacheDir, { recursive: true });
+  const file = join7(cacheDir, "key.wav");
+  if (existsSync4(file)) return file;
+  await exec2(ffmpegPath2, [
+    "-y",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    "sine=frequency=3400:duration=0.022",
+    "-filter_complex",
+    "[0]volume=0.12,afade=t=in:d=0.002,afade=t=out:st=0.008:d=0.014,aformat=sample_rates=44100:channel_layouts=stereo",
+    file
+  ]);
+  return file;
+}
 async function ensureClickSample(cacheDir) {
   await mkdir3(cacheDir, { recursive: true });
-  const file = join6(cacheDir, "click.wav");
-  if (existsSync3(file)) return file;
+  const file = join7(cacheDir, "click.wav");
+  if (existsSync4(file)) return file;
   await exec2(ffmpegPath2, [
     "-y",
     "-loglevel",
@@ -4003,7 +4802,7 @@ function plan(bundle, spec, theme, profile, audioMs) {
   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);
+  if (kind.stage && !prof.stage) prof = withStage(prof, true, bundle.manifest.viewport.w / bundle.manifest.viewport.h);
   const diagnostics = { overflows: [], cameraFallbacks: [], clockWarnings: [] };
   const cfg = pacingConfig(spec.output.pacing ?? kind.pacing, kind);
   const dwell = spec.output.dwellScale;
@@ -4014,7 +4813,7 @@ function plan(bundle, spec, theme, profile, audioMs) {
   }
   const timeline = buildTimeline(bundle.events, cfg, audioMs);
   const END_CARD_MS = 2400;
-  if (spec.output.endCard) {
+  if (spec.output.endCard && !bundle.manifest.partial) {
     const endStart = timeline.durationMs;
     timeline.segments.push({ kind: "card", outStart: endStart, outEnd: endStart + END_CARD_MS, cardId: "end" });
     timeline.durationMs += END_CARD_MS;
@@ -4041,8 +4840,9 @@ function plan(bundle, spec, theme, profile, audioMs) {
     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 tStart = prev.outEnd;
+      const tEnd = Math.min(cur.outStart + 120, tStart + 340);
+      transitions.push({ tStart, tEnd: Math.max(tEnd, tStart + 200), srcFrom: Math.max(0, prev.srcSettled - 1) });
     }
   }
   const subtitle = spec.subtitle ?? safeHost(bundle.manifest.appUrl);
@@ -4105,46 +4905,109 @@ function plan(bundle, spec, theme, profile, audioMs) {
     bundleHashes: bundle.manifest.hashes
   };
 }
+var BLINK_DIFF_MIN = 25;
+async function excludeTransientPreActionFrames(bundle) {
+  const notes = [];
+  const dpr = bundle.manifest.dpr;
+  const excluded = /* @__PURE__ */ new Set();
+  for (const e of actionEvents(bundle.events)) {
+    if (e.kind !== "click" && e.kind !== "dblclick") continue;
+    if (!e.targetPre || !e.cursorPath || e.cursorPath.length === 0) continue;
+    const tArrive = e.cursorPath[e.cursorPath.length - 1].t;
+    if (!(tArrive < e.tAction)) continue;
+    const iArrive = frameIndexForTime(bundle.frames, tArrive);
+    const iBeat = frameIndexForTime(bundle.frames, e.tAction);
+    if (iBeat <= iArrive) continue;
+    const b = e.targetPre.bbox;
+    const region = { x: b.x * dpr, y: b.y * dpr, w: b.w * dpr, h: b.h * dpr };
+    const ref = await sourceRegionGray(bundle, bundle.frames[iArrive].t, region);
+    if (!ref) continue;
+    for (let i = iArrive + 1; i <= iBeat; i++) {
+      const cand = await sourceRegionGray(bundle, bundle.frames[i].t, region);
+      if (!cand || cand.length !== ref.length) continue;
+      if (meanAbsDiff(ref, cand) > BLINK_DIFF_MIN) {
+        excluded.add(i);
+        notes.push(
+          `${e.sceneId}/${e.stepIndex}: frame ${bundle.frames[i].f} (t=${Math.round(bundle.frames[i].t)}) is a pre-click transient (target region contradicts the arrival frame) \u2014 excluded from composition`
+        );
+      }
+    }
+  }
+  if (excluded.size === 0) return { bundle, notes };
+  return { bundle: { ...bundle, frames: bundle.frames.filter((_, i) => !excluded.has(i)) }, notes };
+}
+var JUMP_DIFF_MIN = 18;
+var JUMP_DISSOLVE_MS = 360;
+async function smoothJumpCuts(bundle, manifest) {
+  for (const s of manifest.steps) {
+    if (s.kind !== "click" && s.kind !== "dblclick" && s.kind !== "press" && s.kind !== "select") continue;
+    const before = await sourceFrameGray(bundle, Math.max(0, s.srcAction - 30), 320);
+    const after = await sourceFrameGray(bundle, Math.min(s.srcAction + 700, s.srcSettled), 320);
+    if (after.frameT <= before.frameT || after.data.length !== before.data.length) continue;
+    if (meanAbsDiff(before.data, after.data) < JUMP_DIFF_MIN) continue;
+    const tStart = s.outBeat + 60;
+    const tEnd = Math.min(tStart + JUMP_DISSOLVE_MS, s.outEnd);
+    if ((manifest.transitions ?? []).some((w) => tStart <= w.tEnd && tEnd >= w.tStart)) continue;
+    manifest.transitions = manifest.transitions ?? [];
+    manifest.transitions.push({ tStart, tEnd, srcFrom: before.frameT });
+  }
+}
 async function compose(bundle, spec, opts) {
   const audioCfg = spec.output.audio;
   let narration;
   let audioMs;
+  let narrationDegraded;
+  const voiceLabel = audioCfg?.voice ?? (audioCfg?.provider === "kokoro" ? "heart" : "Samantha");
   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"})`);
+    log.info(`synthesizing narration: ${lines.length} lines (${audioCfg.provider}, voice ${voiceLabel})`);
     try {
-      narration = await synthesizeNarration(lines, audioCfg, join7(opts.outDir, "narration"));
+      narration = await synthesizeNarration(lines, audioCfg, join8(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`);
+      narrationDegraded = e.message.split("\n")[0] ?? "TTS unavailable";
+      log.warn(`narration unavailable on this host (${narrationDegraded}) \u2014 rendering WITHOUT voice; the audio check will FAIL`);
       narration = void 0;
       audioMs = void 0;
     }
   }
+  const transient = await excludeTransientPreActionFrames(bundle);
+  bundle = transient.bundle;
   const manifest = plan(bundle, spec, opts.theme, opts.profile, audioMs);
+  manifest.diagnostics.clockWarnings.push(...transient.notes);
+  await smoothJumpCuts(bundle, manifest);
   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");
+  const videoPath = join8(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 keyBeats = [];
+    if (audioCfg.sfx) {
+      for (const s of manifest.steps) {
+        if (s.kind !== "type") continue;
+        const headEnd = Math.min(s.outEnd, s.outBeat + 1150);
+        for (let t = s.outBeat + 40; t < headEnd; t += 78 + (t | 0) % 29) keyBeats.push(t);
+      }
+    }
     const clips = await mixAudio(videoPath, manifest.steps, manifest.durationMs, {
       ...narration ? { narration } : {},
       ...audioCfg.sfx ? { sfxBeats: manifest.ripples } : {},
+      ...keyBeats.length > 0 ? { keyBeats } : {},
       ...audioCfg.music ? { music: audioCfg.music } : {},
-      cacheDir: join7(opts.outDir, "narration")
+      cacheDir: join8(opts.outDir, "narration")
     });
     if (narration) {
       manifest.audio = {
         narrated: true,
         provider: audioCfg.provider,
-        voice: audioCfg.voice ?? "Samantha",
+        voice: voiceLabel,
         lines: clips.length,
         clips
       };
@@ -4153,8 +5016,19 @@ async function compose(bundle, spec, opts) {
       `\u2713 audio: ${clips.length} narration line(s)${audioCfg.sfx ? `, ${manifest.ripples.length} click(s)` : ""}${audioCfg.music ? ", music bed" : ""} \u2192 ${videoPath}`
     );
   }
+  if (narrationDegraded && !manifest.audio) {
+    manifest.audio = {
+      narrated: false,
+      provider: audioCfg?.provider ?? "say",
+      voice: voiceLabel,
+      lines: 0,
+      degraded: narrationDegraded
+    };
+  } else if (narrationDegraded && manifest.audio) {
+    manifest.audio.degraded = narrationDegraded;
+  }
   manifest.videoSha256 = await sha256File(videoPath);
-  const manifestPath = join7(opts.outDir, "compose-manifest.json");
+  const manifestPath = join8(opts.outDir, "compose-manifest.json");
   await writeFile3(manifestPath, JSON.stringify(manifest, null, 2));
   return { videoPath, manifestPath, manifest };
 }
@@ -4170,154 +5044,9 @@ function safeHost(url) {
 }
 
 // src/verify/runner.ts
-import { join as join8 } from "path";
+import { join as join9 } 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"]);
@@ -4397,7 +5126,47 @@ async function checkCursorOnTarget(ctx2) {
     }
   }
   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` };
+  if (evidence.length > 0)
+    return { id: "cursor-on-target", status: "fail", details: `${evidence.length}/${checked} clicks miss their target`, evidence };
+  const p = plane(ctx2);
+  const content = stageContent(ctx2.manifest.profile);
+  const frameScale = ctx2.bundle.manifest.frameW / ctx2.manifest.viewport.w;
+  const clickSteps = ctx2.manifest.steps.filter((s) => CLICK_KINDS2.has(s.kind) && s.targetRectVp);
+  let sampled = 0;
+  let present = 0;
+  for (const step of clickSteps.slice(0, 2)) {
+    const t = step.outBeat;
+    const pos = sampleCursor(cursorPlan, t);
+    const boxVp = { x: pos.x - 16, y: pos.y - 16, w: 32, h: 32 };
+    const cam = sampleCamera(ctx2.manifest.camera, t);
+    const proj = projectRect(boxVp, cam, p);
+    const projFrame = { x: proj.x + content.x, y: proj.y + content.y, w: proj.w, h: proj.h };
+    const { srcAt } = sampleSource(ctx2.manifest.segments, t);
+    if (srcAt === null) continue;
+    const outPng = await extractFrameAt(ctx2.videoPath, t).catch(() => null);
+    if (!outPng) continue;
+    const [outRegion, srcRegion] = await Promise.all([
+      regionGray48(outPng, projFrame),
+      regionGray48(framePath(ctx2.bundle, frameIndexForTime(ctx2.bundle.frames, srcAt)), {
+        x: boxVp.x * frameScale,
+        y: boxVp.y * frameScale,
+        w: boxVp.w * frameScale,
+        h: boxVp.h * frameScale
+      })
+    ]);
+    if (!outRegion || !srcRegion) continue;
+    sampled += 1;
+    if (meanAbsDiff(outRegion, srcRegion) > 6) present += 1;
+  }
+  if (sampled > 0 && present === 0) {
+    return {
+      id: "cursor-on-target",
+      status: "fail",
+      details: `cursor sprite NOT FOUND in the output pixels at ${sampled} sampled click beat(s) \u2014 the plan says it's there, the film disagrees`
+    };
+  }
+  const renderedNote = sampled > 0 ? `; sprite verified on film at ${present}/${sampled} sampled beat(s)` : "";
+  return { id: "cursor-on-target", status: "pass", details: `${checked}/${checked} clicks land on target${renderedNote}` };
 }
 async function checkActionEffect(ctx2) {
   const evidence = [];
@@ -4455,12 +5224,14 @@ async function checkActionEffect(ctx2) {
   }
   const maskedNote = skippedMasked > 0 ? ` (${skippedMasked} masked skipped)` : "";
   const inconcNote = inconclusive.length > 0 ? `, ${inconclusive.length} inconclusive (capture gap)` : "";
+  const coverage = { verified: checked - evidence.length - inconclusive.length, total: checked + skippedMasked };
   if (evidence.length > 0) {
     return {
       id: "action-effect",
       status: "fail",
       details: `${evidence.length}/${checked} actions show no visible effect${maskedNote}${inconcNote}`,
-      evidence: [...evidence, ...inconclusive]
+      evidence: [...evidence, ...inconclusive],
+      coverage
     };
   }
   if (inconclusive.length > 0) {
@@ -4468,10 +5239,11 @@ async function checkActionEffect(ctx2) {
       id: "action-effect",
       status: "warn",
       details: `${checked - inconclusive.length}/${checked} actions visibly effective; ${inconclusive.length} unverified (capture gap)${maskedNote}`,
-      evidence: inconclusive
+      evidence: inconclusive,
+      coverage
     };
   }
-  return { id: "action-effect", status: "pass", details: `${checked}/${checked} actions visibly effective${maskedNote}` };
+  return { id: "action-effect", status: "pass", details: `${checked}/${checked} actions visibly effective${maskedNote}`, coverage };
 }
 async function checkFrozenBlank(ctx2) {
   const { frames, intervalMs } = await extractGrayFrames(ctx2.videoPath, 2, 320, 180);
@@ -4479,11 +5251,23 @@ async function checkFrozenBlank(ctx2) {
   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);
+  const centerBlank = [];
+  const W = 320;
+  const H = 180;
   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` });
+      continue;
+    }
+    const f = frames[i];
+    const center = [];
+    for (let y = Math.floor(H * 0.3); y < Math.floor(H * 0.7); y++) {
+      for (let x = Math.floor(W * 0.25); x < Math.floor(W * 0.75); x++) center.push(f[y * W + x]);
+    }
+    if (variance(Buffer.from(center)) < 3) {
+      centerBlank.push({ t, note: `content region blank at ${(t / 1e3).toFixed(1)}s \u2014 still loading? Add a wait: { for: \u2026 } step so hydration never gets filmed` });
     }
   }
   const maskedWindows = ctx2.manifest.steps.filter((s) => s.masked).map((s) => ({ start: s.outStart, end: s.outEnd }));
@@ -4518,7 +5302,18 @@ async function checkFrozenBlank(ctx2) {
       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` };
+  if (evidence.length > 0) {
+    return { id: "frozen-blank", status: "fail", details: `${evidence.length} frozen/blank issue(s)`, evidence: [...evidence, ...centerBlank] };
+  }
+  if (centerBlank.length > 0) {
+    return {
+      id: "frozen-blank",
+      status: "warn",
+      details: `frames live, but ${centerBlank.length} sampled frame(s) have a blank content region (mid-hydration footage?)`,
+      evidence: centerBlank
+    };
+  }
+  return { id: "frozen-blank", status: "pass", details: `${frames.length} sampled output frames live and non-blank` };
 }
 async function checkCaptions(ctx2) {
   const evidence = [];
@@ -4529,7 +5324,7 @@ async function checkCaptions(ctx2) {
     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)
+    if (o.fontPx < Math.round(ctx2.manifest.theme.captionMinFontPx * ctx2.manifest.profile.uiScale))
       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;
@@ -4537,7 +5332,35 @@ async function checkCaptions(ctx2) {
   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` };
+  const caps = ctx2.manifest.overlays.filter((o) => o.kind === "caption");
+  const stride = Math.max(1, Math.floor(caps.length / 3));
+  let sampled = 0;
+  let drawn = 0;
+  for (let i = 0; i < caps.length && sampled < 3; i += stride) {
+    const c = caps[i];
+    const tOn = (c.tStart + c.tEnd) / 2;
+    const tOff = c.tEnd + 500;
+    const clashes = caps.some((o) => o !== c && tOff >= o.tStart - 100 && tOff <= o.tEnd + 100);
+    if (clashes || tOff >= ctx2.manifest.durationMs - 200) continue;
+    const [onPng, offPng] = await Promise.all([
+      extractFrameAt(ctx2.videoPath, tOn).catch(() => null),
+      extractFrameAt(ctx2.videoPath, tOff).catch(() => null)
+    ]);
+    if (!onPng || !offPng) continue;
+    const [ra, rb] = await Promise.all([regionGray48(onPng, c.box), regionGray48(offPng, c.box)]);
+    if (!ra || !rb) continue;
+    sampled += 1;
+    if (meanAbsDiff(ra, rb) > 4) drawn += 1;
+  }
+  if (sampled > 0 && drawn === 0) {
+    return {
+      id: "captions",
+      status: "fail",
+      details: `captions planned but NOT FOUND in the output pixels (${sampled} sampled boxes identical with and without caption)`
+    };
+  }
+  const renderedNote = sampled > 0 ? `; ${drawn}/${sampled} sampled on film` : "";
+  return warned > 0 ? { id: "captions", status: "warn", details: `${count} captions ok, ${warned} auto-shrunk to fit${renderedNote}` } : { id: "captions", status: "pass", details: `${count} captions fit at full size${renderedNote}` };
 }
 async function checkPacing(ctx2) {
   const evidence = [];
@@ -4553,7 +5376,20 @@ async function checkPacing(ctx2) {
   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" };
+  if (ctx2.manifest.audio?.degraded) {
+    return {
+      id: "audio",
+      status: "fail",
+      details: `narration was requested but degraded to silence: ${ctx2.manifest.audio.degraded}`
+    };
+  }
+  if (!ctx2.manifest.audio?.narrated) {
+    return {
+      id: "audio",
+      status: "skip",
+      details: "no narration \u2014 for a voice-over, set output.audio: { narration: tts } and re-compose"
+    };
+  }
   const evidence = [];
   const probe = await runBinary(ffprobePath(), [
     "-v",
@@ -4688,9 +5524,37 @@ async function checkMasks(ctx2) {
   if (evidence.length > 0) {
     return { id: "masks", status: "fail", details: `${evidence.length} mask violation(s)`, evidence };
   }
+  const p = plane(ctx2);
+  const content = stageContent(ctx2.manifest.profile);
+  const solidSamples = ctx2.bundle.maskSamples.flatMap((s) => s.rects.filter((r) => r.style === "solid").map((r) => ({ t: s.t, r }))).filter((_, i, arr) => i % Math.max(1, Math.floor(arr.length / 3)) === 0).slice(0, 3);
+  let outSampled = 0;
+  let outCovered = 0;
+  for (const s of solidSamples) {
+    const tOut = outTimeForSrc(ctx2.manifest.segments, s.t);
+    if (tOut === null || tOut >= ctx2.manifest.durationMs - 100) continue;
+    const cam = sampleCamera(ctx2.manifest.camera, tOut);
+    const rectVp = { x: s.r.x / frameScale, y: s.r.y / frameScale, w: s.r.w / frameScale, h: s.r.h / frameScale };
+    const proj = projectRect(rectVp, cam, p);
+    const projFrame = { x: proj.x + content.x + 4, y: proj.y + content.y + 4, w: proj.w - 8, h: proj.h - 8 };
+    if (projFrame.w < 12 || projFrame.h < 12) continue;
+    const png = await extractFrameAt(ctx2.videoPath, tOut).catch(() => null);
+    if (!png) continue;
+    const region = await regionGray48(png, projFrame);
+    if (!region) continue;
+    outSampled += 1;
+    if (Math.sqrt(variance(region)) < 16) outCovered += 1;
+  }
+  if (outSampled > 0 && outCovered === 0) {
+    return {
+      id: "masks",
+      status: "fail",
+      details: `masked regions verified in SOURCE frames but NOT covered in the delivered video (${outSampled} output sample(s) show content)`
+    };
+  }
   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`);
+  if (outSampled > 0) parts.push(`${outCovered}/${outSampled} re-verified in the output video`);
   return { id: "masks", status: "pass", details: `${parts.join(", ")}; log clean` };
 }
 function scaleRect(r, s) {
@@ -4748,7 +5612,7 @@ async function checkOutputPixels(ctx2) {
     }
   }
   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` };
+  return evidence.length > 0 ? { id: "output-pixels", status: "fail", details: `${evidence.length}/${checked} sampled regions diverge from the plan`, evidence, coverage: { verified: checked - evidence.length, total: checked } } : { id: "output-pixels", status: "pass", details: `${checked} sampled output regions match their planned source`, coverage: { verified: checked, total: checked } };
 }
 
 // src/verify/contact-sheet.ts
@@ -4896,13 +5760,17 @@ function extractJson(text) {
 }
 
 // src/verify/report.ts
-import { createHmac } from "crypto";
+import { createHmac, createHash as createHash4, sign as edSign, verify as edVerify, createPrivateKey, createPublicKey } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
 function signablePayload(v) {
   return JSON.stringify({
     schema: v.schema,
     verdict: v.verdict,
     videoSha256: v.video.sha256,
+    manifestHash: v.manifestHash,
+    contactSheetSha256: v.contactSheetSha256,
     bundleHashes: { events: v.bundleHashes.events, framesIndex: v.bundleHashes.framesIndex },
+    coverage: v.coverage,
     provenance: {
       playheadVersion: v.provenance.playheadVersion,
       specHash: v.provenance.specHash,
@@ -4911,22 +5779,53 @@ function signablePayload(v) {
       verifiedAt: v.provenance.verifiedAt,
       checkSuiteVersion: v.provenance.checkSuiteVersion,
       host: v.provenance.host,
-      partial: v.provenance.partial ?? false
+      partial: v.provenance.partial ?? false,
+      failure: v.provenance.failure ?? null
     },
-    checks: v.checks.map((c) => ({ id: c.id, status: c.status }))
+    checks: v.checks.map((c) => ({
+      id: c.id,
+      status: c.status,
+      details: c.details,
+      evidence: (c.evidence ?? []).map((e) => ({ stepRef: e.stepRef ?? null, t: e.t ?? null, note: e.note }))
+    })),
+    vision: v.vision
   });
 }
-function signVerdict(v, key = process.env.PLAYHEAD_SIGNING_KEY) {
-  if (!key) return null;
-  return createHmac("sha256", key).update(signablePayload(v)).digest("hex");
+function signVerdict(v, env = {
+  ...process.env.PLAYHEAD_SIGNING_KEY ? { hmacKey: process.env.PLAYHEAD_SIGNING_KEY } : {},
+  ...process.env.PLAYHEAD_SIGNING_KEY_FILE ? { keyFile: process.env.PLAYHEAD_SIGNING_KEY_FILE } : {}
+}) {
+  const payload = Buffer.from(signablePayload(v));
+  if (env.keyFile) {
+    const privateKey = createPrivateKey(readFileSync2(env.keyFile, "utf8"));
+    const publicKey = createPublicKey(privateKey);
+    const spki = publicKey.export({ type: "spki", format: "der" });
+    return {
+      alg: "Ed25519",
+      keyId: keyIdFor(spki),
+      publicKey: spki.toString("base64"),
+      value: edSign(null, payload, privateKey).toString("base64")
+    };
+  }
+  if (env.hmacKey) {
+    return {
+      alg: "HS256",
+      keyId: keyIdFor(Buffer.from(env.hmacKey)),
+      value: createHmac("sha256", env.hmacKey).update(payload).digest("hex")
+    };
+  }
+  return null;
+}
+function keyIdFor(material) {
+  return createHash4("sha256").update(material).digest("hex").slice(0, 16);
 }
 
 // src/verify/runner.ts
 import { platform, arch } from "os";
 import pc2 from "picocolors";
-var CHECK_SUITE_VERSION = "playhead/checks@2";
+var CHECK_SUITE_VERSION = "playhead/checks@3";
 async function verify(bundle, manifest, videoPath, opts) {
-  const verifyDir = join8(opts.outDir, "verify");
+  const verifyDir = join9(opts.outDir, "verify");
   await mkdir4(verifyDir, { recursive: true });
   const ctx2 = { bundle, manifest, videoPath, outDir: verifyDir };
   log.info("verifying output");
@@ -4950,7 +5849,7 @@ async function verify(bundle, manifest, videoPath, opts) {
     checks.push(result);
     report(result);
   }
-  const contactSheet = join8(verifyDir, "contact-sheet.png");
+  const contactSheet = join9(verifyDir, "contact-sheet.png");
   await renderContactSheet(manifest, videoPath, contactSheet);
   log.ok(`contact sheet \u2192 ${contactSheet}`);
   let vision = null;
@@ -4961,11 +5860,28 @@ async function verify(bundle, manifest, videoPath, opts) {
     vision = review;
   }
   const failed = checks.some((c) => c.status === "fail");
+  const effectCoverage = checks.find((c) => c.id === "action-effect")?.coverage;
+  const pixelCoverage = checks.find((c) => c.id === "output-pixels")?.coverage;
+  const coverage = {
+    actionsVerified: effectCoverage?.verified ?? 0,
+    actionsTotal: effectCoverage?.total ?? 0,
+    outputSamplesVerified: pixelCoverage?.verified ?? 0,
+    checksSkipped: checks.filter((c) => c.status === "skip").length,
+    checksWarned: checks.filter((c) => c.status === "warn").length
+  };
   const unsigned = {
-    schema: "playhead/verdict@2",
+    schema: "playhead/verdict@3",
     verdict: failed ? "not-publishable" : "publishable",
-    video: { path: videoPath, sha256: manifest.videoSha256 ?? await sha256File(videoPath) },
+    // ALWAYS hash the file the checks actually ran against — never trust the manifest's claim
+    // (an unauthenticated JSON from disk). Round-2 audit: a doctored manifest could bind the
+    // signed verdict to a video that was never verified.
+    video: { path: videoPath, sha256: await sha256File(videoPath) },
     bundleHashes: manifest.bundleHashes,
+    // The compose manifest is the oracle for the plan-side checks — hash it into the verdict
+    // so a doctored manifest can no longer mint passes undetected.
+    manifestHash: sha256Json(manifest),
+    contactSheetSha256: await sha256File(contactSheet),
+    coverage,
     provenance: {
       playheadVersion: PLAYHEAD_VERSION,
       specHash: bundle.manifest.specHash,
@@ -4983,9 +5899,10 @@ async function verify(bundle, manifest, videoPath, opts) {
   };
   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`);
+  await writeFile5(join9(verifyDir, "verdict.json"), JSON.stringify(verdict, null, 2));
+  const cov = coverage.actionsTotal > 0 ? ` (coverage: ${coverage.actionsVerified}/${coverage.actionsTotal} actions pixel-verified, ${coverage.outputSamplesVerified} output samples)` : " (coverage: no effectful actions)";
+  if (failed) log.error(`verdict: NOT PUBLISHABLE${cov}`);
+  else log.ok(`verdict: publishable${cov}`);
   return verdict;
 }
 function report(c) {