playhead-cli 0.1.3 → 0.2.0

package/dist/cli/index.js

@@ -10,10 +10,33 @@ var __export = (target, all) => {
 };
 
 // src/spec/locators.ts
+function splitSegments(raw) {
+  const parts = [];
+  let cur = "";
+  let quote2 = null;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (quote2) {
+      cur += ch;
+      if (ch === quote2) quote2 = null;
+    } else if (ch === '"' || ch === "'") {
+      quote2 = 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());
@@ -119,6 +142,16 @@ var init_locators = __esm({
 });
 
 // src/spec/schema.ts
+var schema_exports = {};
+__export(schema_exports, {
+  ASPECTS: () => ASPECTS,
+  editDistance: () => editDistance,
+  flattenSteps: () => flattenSteps,
+  resolveResolution: () => resolveResolution,
+  resolveViewport: () => resolveViewport,
+  specSchema: () => specSchema,
+  stepSchema: () => stepSchema
+});
 import { z } from "zod";
 function nearestAction(key) {
   let best = null;
@@ -183,7 +216,7 @@ function flattenSteps(spec) {
   });
   return out;
 }
-var dimensions, locatorString, focusHint, EXTRA_KEYS, stepExtras, targetOrShorthand, gotoStep, pointerStep, typeStep, pressStep, selectStep, scrollStep, expectStep, waitStep, stepSchema, ACTION_KEYS, authoredStep, specSchema, ASPECTS;
+var dimensions, locatorString, focusHint, EXTRA_KEYS, stepExtras, targetOrShorthand, gotoStep, pointerStep, typeStep, pressStep, rightclickStep, uploadStep, dragStep, selectStep, scrollStep, expectStep, waitStep, stepSchema, ACTION_KEYS, authoredStep, specSchema, ASPECTS;
 var init_schema = __esm({
   "src/spec/schema.ts"() {
     "use strict";
@@ -200,7 +233,7 @@ var init_schema = __esm({
       }
     });
     focusHint = z.union([z.literal("target"), z.literal("wide"), locatorString]);
-    EXTRA_KEYS = ["caption", "narration", "focus", "mask", "shot", "timeout"];
+    EXTRA_KEYS = ["caption", "narration", "focus", "mask", "shot", "timeout", "optional"];
     stepExtras = {
       caption: z.string().optional(),
       /** The SPOKEN line for TTS narration — unconstrained by the caption card's size. Resolution:
@@ -212,7 +245,10 @@ var init_schema = __esm({
        *  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()
     };
     targetOrShorthand = z.union([
       locatorString,
@@ -229,9 +265,15 @@ var init_schema = __esm({
       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();
     pressStep = z.object({ action: z.literal("press"), keys: z.string(), ...stepExtras }).strict();
+    rightclickStep = z.object({ action: z.literal("rightclick"), target: locatorString, ...stepExtras }).strict();
+    uploadStep = z.object({ action: z.literal("upload"), target: locatorString, file: z.string(), ...stepExtras }).strict();
+    dragStep = z.object({ action: z.literal("drag"), target: locatorString, to: locatorString, ...stepExtras }).strict();
     selectStep = z.object({
       action: z.literal("select"),
       target: locatorString,
@@ -246,13 +288,24 @@ var init_schema = __esm({
     }).strict();
     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"
+    });
     waitStep = z.object({
       action: z.literal("wait"),
       ms: z.number().int().positive().optional(),
@@ -267,12 +320,15 @@ var init_schema = __esm({
       pointerStep,
       typeStep,
       pressStep,
+      rightclickStep,
+      uploadStep,
+      dragStep,
       selectStep,
       scrollStep,
       expectStep,
       waitStep
     ]);
-    ACTION_KEYS = ["goto", "click", "dblclick", "hover", "type", "press", "select", "scroll", "expect", "wait"];
+    ACTION_KEYS = ["goto", "click", "dblclick", "hover", "type", "press", "rightclick", "upload", "drag", "select", "scroll", "expect", "wait"];
     authoredStep = z.record(z.string(), z.unknown()).superRefine((obj, ctx2) => {
       const actions = ACTION_KEYS.filter((k) => k in obj);
       if (actions.length !== 1) {
@@ -375,7 +431,10 @@ var init_schema = __esm({
         }).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),
@@ -394,13 +453,24 @@ var init_schema = __esm({
           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();
     ASPECTS = {
       "16:9": { viewport: { w: 1280, h: 720 }, resolution: { w: 1920, h: 1080 } },
@@ -411,6 +481,12 @@ var init_schema = __esm({
 });
 
 // src/spec/parse.ts
+var parse_exports = {};
+__export(parse_exports, {
+  SpecError: () => SpecError,
+  loadSpec: () => loadSpec,
+  parseSpec: () => parseSpec
+});
 import { readFile } from "fs/promises";
 import { dirname, resolve as resolvePath } from "path";
 import { parseDocument, LineCounter } from "yaml";
@@ -444,7 +520,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`);
@@ -483,6 +565,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) => {
@@ -514,18 +618,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;
@@ -534,7 +638,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);
@@ -573,6 +685,7 @@ var init_parse = __esm({
       "scenes",
       "vars",
       "extends",
+      "setup",
       "url",
       "viewport",
       "storageState",
@@ -643,7 +756,15 @@ var init_parse = __esm({
       "for",
       "state",
       "x",
-      "y"
+      "y",
+      "optional",
+      "clear",
+      "to",
+      "disabled",
+      "checked",
+      "rightclick",
+      "upload",
+      "drag"
     ];
   }
 });
@@ -718,12 +839,52 @@ var init_log = __esm({
   }
 });
 
+// src/shared/exit.ts
+var exit_exports = {};
+__export(exit_exports, {
+  EXIT: () => EXIT,
+  FlowError: () => FlowError,
+  InfraError: () => InfraError,
+  exitCodeFor: () => exitCodeFor
+});
+function exitCodeFor(e) {
+  if (e && typeof e === "object") {
+    if ("exitCode" in e && typeof e.exitCode === "number") {
+      return e.exitCode;
+    }
+    if (e.name === "SpecError" || e instanceof Object && e.constructor?.name === "SpecError") {
+      return EXIT.USAGE;
+    }
+  }
+  return EXIT.INFRA;
+}
+var EXIT, FlowError, InfraError;
+var init_exit = __esm({
+  "src/shared/exit.ts"() {
+    "use strict";
+    EXIT = {
+      OK: 0,
+      FLOW: 1,
+      QUALITY: 2,
+      INFRA: 3,
+      USAGE: 4
+    };
+    FlowError = class extends Error {
+      exitCode = EXIT.FLOW;
+    };
+    InfraError = class extends Error {
+      exitCode = EXIT.INFRA;
+    };
+  }
+});
+
 // src/capture/playwright-driver.ts
 var playwright_driver_exports = {};
 __export(playwright_driver_exports, {
   PlaywrightDriver: () => PlaywrightDriver
 });
 import { chromium } from "playwright";
+import { access } from "fs/promises";
 function toPw(m) {
   if ("exact" in m) return m.exact;
   if ("substring" in m) return m.substring;
@@ -760,12 +921,31 @@ 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;
+  }
+}
 var INPUT_TIMEOUT_MS, MASK_INIT_SCRIPT, FALLBACK_NAME_FN, COLLECT_INTERACTABLES_FN, PlaywrightDriver;
 var init_playwright_driver = __esm({
   "src/capture/playwright-driver.ts"() {
     "use strict";
     init_easing();
     init_log();
+    init_exit();
     INPUT_TIMEOUT_MS = 5e3;
     MASK_INIT_SCRIPT = `
 (() => {
@@ -808,11 +988,24 @@ var init_playwright_driver = __esm({
   // 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) {}
@@ -821,7 +1014,7 @@ var init_playwright_driver = __esm({
   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); }
       }
@@ -971,9 +1164,23 @@ var init_playwright_driver = __esm({
       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",
@@ -1012,7 +1219,10 @@ var init_playwright_driver = __esm({
         });
         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}`);
@@ -1029,6 +1239,12 @@ var init_playwright_driver = __esm({
         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();
@@ -1146,6 +1362,7 @@ var init_playwright_driver = __esm({
         return l;
       }
       async resolveTarget(loc, timeoutMs) {
+        this.assertAlive();
         const locator = this.toLocator(loc);
         try {
           await locator.waitFor({ state: "visible", timeout: timeoutMs });
@@ -1209,6 +1426,8 @@ var init_playwright_driver = __esm({
         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;
@@ -1300,12 +1519,69 @@ var init_playwright_driver = __esm({
        * 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);
@@ -1314,8 +1590,6 @@ var init_playwright_driver = __esm({
         } catch {
           await locator.selectOption(value);
         }
-        await withTimeout(this.page.keyboard.press("Escape"), INPUT_TIMEOUT_MS).catch(() => {
-        });
         await withTimeout(
           locator.evaluate((el) => el.blur?.()),
           2e3
@@ -1351,6 +1625,22 @@ var init_playwright_driver = __esm({
         }
       }
       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";
@@ -1366,6 +1656,18 @@ var init_playwright_driver = __esm({
             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)) {
@@ -1407,6 +1709,7 @@ var init_playwright_driver = __esm({
       }
       static LONG_REQUEST_MS = 2e3;
       async settle(opts) {
+        this.assertAlive();
         this.installNetTracking();
         const start = Date.now();
         let capped = true;
@@ -1449,7 +1752,20 @@ var init_playwright_driver = __esm({
             })
           ),
           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((resolve3) => {
+                  setTimeout(resolve3, 400);
+                })
+              ),
+              1e3
+            ).catch(() => {
+            });
+          }
         });
         await this.nextFrame();
       }
@@ -1506,10 +1822,56 @@ var init_playwright_driver = __esm({
       // 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) {
@@ -1520,7 +1882,8 @@ var init_playwright_driver = __esm({
           }
         })();
       }
-      /** 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(() => {
@@ -1530,7 +1893,7 @@ var init_playwright_driver = __esm({
       }
       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 };
@@ -1539,7 +1902,9 @@ var init_playwright_driver = __esm({
             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
@@ -1548,7 +1913,9 @@ var init_playwright_driver = __esm({
           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 {
@@ -1560,6 +1927,7 @@ var init_playwright_driver = __esm({
             } catch {
             }
           }
+          return false;
         }
       }
       async readScroll() {
@@ -1573,6 +1941,11 @@ var init_playwright_driver = __esm({
       }
       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;
@@ -1581,9 +1954,12 @@ var init_playwright_driver = __esm({
         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");
       }
     };
   }
@@ -1609,18 +1985,49 @@ var init_hash = __esm({
 
 // src/shared/version.ts
 import { createRequire } from "module";
+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;
 var init_version = __esm({
   "src/shared/version.ts"() {
     "use strict";
-    PLAYHEAD_VERSION = createRequire(import.meta.url)("../../package.json").version;
+    PLAYHEAD_VERSION = resolveOwnPackageJson().version;
   }
 });
 
 // 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";
+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;
 }
@@ -1630,11 +2037,12 @@ var init_writer = __esm({
     "use strict";
     init_hash();
     init_version();
+    init_log();
     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;
@@ -1643,14 +2051,22 @@ var init_writer = __esm({
       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) {
@@ -1662,21 +2078,28 @@ var init_writer = __esm({
       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,
@@ -1695,11 +2118,11 @@ var init_writer = __esm({
           ...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;
       }
@@ -1767,42 +2190,10 @@ var init_geometry = __esm({
   }
 });
 
-// src/shared/exit.ts
-function exitCodeFor(e) {
-  if (e && typeof e === "object") {
-    if ("exitCode" in e && typeof e.exitCode === "number") {
-      return e.exitCode;
-    }
-    if (e.name === "SpecError" || e instanceof Object && e.constructor?.name === "SpecError") {
-      return EXIT.USAGE;
-    }
-  }
-  return EXIT.INFRA;
-}
-var EXIT, FlowError, InfraError;
-var init_exit = __esm({
-  "src/shared/exit.ts"() {
-    "use strict";
-    EXIT = {
-      OK: 0,
-      FLOW: 1,
-      QUALITY: 2,
-      INFRA: 3,
-      USAGE: 4
-    };
-    FlowError = class extends Error {
-      exitCode = EXIT.FLOW;
-    };
-    InfraError = class extends Error {
-      exitCode = EXIT.INFRA;
-    };
-  }
-});
-
 // src/capture/executor.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 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";
@@ -1836,18 +2227,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);
@@ -1859,7 +2252,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) {
@@ -1872,7 +2273,10 @@ async function capture(spec, opts) {
       }
       currentStepRef = "";
       steps = steps.slice(idx);
+    }
+    if (preRoll) {
       await driver.settle(settleCfg);
+      recordEvents = true;
       await startFilming();
       await driver.captureNow();
     }
@@ -1882,11 +2286,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;
@@ -1924,10 +2337,10 @@ async function capture(spec, opts) {
       const url = driver.currentUrl();
       const { writeFile: writeFile9 } = await import("fs/promises");
       await writeFile9(
-        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 writeFile9(join2(bundleDir, "failure-aria.txt"), aria);
+      if (aria) await writeFile9(join3(bundleDir, "failure-aria.txt"), aria);
     } catch {
     }
     throw new FlowError(
@@ -1942,7 +2355,7 @@ async function capture(spec, opts) {
       if (consoleLog.length > 0) {
         const { writeFile: writeFile9 } = await import("fs/promises");
         await writeFile9(
-          join2(bundleDir, "console.json"),
+          join3(bundleDir, "console.json"),
           JSON.stringify(consoleLog.map((c) => ({ ...c, t: rel(c.t) })), null, 2)
         );
       }
@@ -1994,13 +2407,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));
@@ -2018,8 +2433,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":
@@ -2105,6 +2535,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);
       }
@@ -2134,6 +2567,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) {
@@ -2150,14 +2619,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;
@@ -2183,6 +2660,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) {
@@ -2248,13 +2726,13 @@ var init_executor = __esm({
 
 // 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") {
@@ -2279,7 +2757,7 @@ 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);
 }
 var init_reader = __esm({
   "src/bundle/reader.ts"() {
@@ -2293,8 +2771,8 @@ __export(theme_exports, {
   registerFonts: () => registerFonts,
   resolveTheme: () => resolveTheme
 });
-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";
 function resolveTheme(spec) {
@@ -2310,7 +2788,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");
   }
@@ -2321,8 +2799,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);
   }
 }
 var DEFAULT_THEME, fontsRegistered;
@@ -2351,20 +2829,37 @@ var init_theme = __esm({
 });
 
 // src/compose/types.ts
+var types_exports = {};
+__export(types_exports, {
+  PROFILE_16x9: () => PROFILE_16x9,
+  PROFILE_1x1: () => PROFILE_1x1,
+  PROFILE_9x16: () => PROFILE_9x16,
+  actReactWindows: () => actReactWindows,
+  profileForAspect: () => profileForAspect,
+  stageContent: () => stageContent,
+  withStage: () => withStage
+});
 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) }
   };
 }
 function profileForAspect(aspect, resolution, fps) {
@@ -2382,7 +2877,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) {
@@ -2405,7 +2901,8 @@ var init_types = __esm({
       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
     };
     PROFILE_9x16 = {
       width: 1080,
@@ -2414,7 +2911,8 @@ var init_types = __esm({
       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
     };
     PROFILE_1x1 = {
       width: 1080,
@@ -2423,7 +2921,8 @@ var init_types = __esm({
       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
     };
   }
 });
@@ -2520,6 +3019,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
@@ -2544,10 +3046,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}`);
@@ -2576,6 +3105,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,
@@ -2602,6 +3132,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;
@@ -2642,13 +3184,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;
 }
 var init_interpolate = __esm({
   "src/compose/camera/interpolate.ts"() {
@@ -2674,7 +3251,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);
@@ -2691,7 +3269,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) {
@@ -2766,6 +3346,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,
@@ -2773,7 +3354,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
@@ -3030,6 +3611,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":
@@ -3180,29 +3767,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];
@@ -3349,19 +3953,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();
@@ -3387,13 +4010,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)";
@@ -3401,13 +4025,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) {
@@ -3415,23 +4039,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) {
@@ -3440,23 +4065,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();
@@ -3468,7 +4106,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";
@@ -3492,16 +4130,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 = [];
@@ -3542,14 +4181,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();
@@ -3584,7 +4224,8 @@ var init_frameStore = __esm({
       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;
       }
       /**
@@ -3611,6 +4252,7 @@ var init_frameStore = __esm({
           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;
@@ -3664,10 +4306,10 @@ function runBinary(bin, args, stdin) {
 }
 async function concatVideos(inputs, outPath) {
   const { writeFile: writeFile9, mkdtemp: mkdtemp2, rm } = await import("fs/promises");
-  const { join: join13 } = await import("path");
+  const { join: join14 } = await import("path");
   const { tmpdir: tmpdir2 } = await import("os");
-  const dir = await mkdtemp2(join13(tmpdir2(), "playhead-concat-"));
-  const listPath = join13(dir, "list.txt");
+  const dir = await mkdtemp2(join14(tmpdir2(), "playhead-concat-"));
+  const listPath = join14(dir, "list.txt");
   await writeFile9(listPath, inputs.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join("\n"));
   try {
     const res = await runBinary(ffmpegPath(), [
@@ -3778,12 +4420,19 @@ var init_encoder = __esm({
           this.child.on("error", reject);
           this.child.on("close", (code) => resolve3(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() {
@@ -3829,7 +4478,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++) {
@@ -3870,7 +4519,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 {
@@ -3886,7 +4536,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);
@@ -3982,11 +4632,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;
@@ -4011,7 +4662,7 @@ function cursorGlyphAt(steps, tOut) {
   }
   return "arrow";
 }
-var SPOTLIGHT_KINDS, SPOTLIGHT_LEAD_MS, SPOTLIGHT_TAIL_MS, SPOTLIGHT_MAX_DIM;
+var SPOTLIGHT_KINDS, SPOTLIGHT_LEAD_MS, SPOTLIGHT_TAIL_MS, SPOTLIGHT_TAIL_GONE_MS, SPOTLIGHT_MAX_DIM;
 var init_renderer = __esm({
   "src/compose/render/renderer.ts"() {
     "use strict";
@@ -4030,17 +4681,170 @@ var init_renderer = __esm({
     SPOTLIGHT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
     SPOTLIGHT_LEAD_MS = 200;
     SPOTLIGHT_TAIL_MS = 650;
+    SPOTLIGHT_TAIL_GONE_MS = 160;
     SPOTLIGHT_MAX_DIM = 0.34;
   }
 });
 
-// src/audio/tts.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
+// 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);
+}
+var init_media = __esm({
+  "src/verify/media.ts"() {
+    "use strict";
+    init_ffmpeg();
+    init_reader();
+  }
+});
+
+// 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 { existsSync as existsSync3 } from "fs";
+import { join as join6 } from "path";
+import { createHash as createHash3 } from "crypto";
 import { createRequire as createRequire4 } from "module";
 function providerFor(opts) {
   switch (opts.provider) {
@@ -4084,9 +4888,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;
@@ -4152,14 +4956,15 @@ var init_tts = __esm({
 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";
 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 = [];
@@ -4197,6 +5002,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++;
@@ -4240,10 +5060,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",
@@ -4274,7 +5112,7 @@ var init_mux = __esm({
 });
 
 // src/compose/index.ts
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { writeFile as writeFile3 } from "fs/promises";
 function specStepTexts(spec) {
   const map = /* @__PURE__ */ new Map();
@@ -4294,7 +5132,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;
@@ -4305,7 +5143,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;
@@ -4332,8 +5170,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);
@@ -4396,238 +5235,163 @@ function plan(bundle, spec, theme, profile, audioMs) {
     bundleHashes: bundle.manifest.hashes
   };
 }
+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 };
+}
+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
       };
     }
     log.info(
       `\u2713 audio: ${clips.length} narration line(s)${audioCfg.sfx ? `, ${manifest.ripples.length} click(s)` : ""}${audioCfg.music ? ", music bed" : ""} \u2192 ${videoPath}`
-    );
-  }
-  manifest.videoSha256 = await sha256File(videoPath);
-  const manifestPath = join7(opts.outDir, "compose-manifest.json");
-  await writeFile3(manifestPath, JSON.stringify(manifest, null, 2));
-  return { videoPath, manifestPath, manifest };
-}
-function safeHost(url) {
-  try {
-    return new URL(url).host;
-  } catch {
-    return url;
-  }
-}
-var init_compose = __esm({
-  "src/compose/index.ts"() {
-    "use strict";
-    init_schema();
-    init_theme();
-    init_types();
-    init_kinds();
-    init_pacing();
-    init_planner();
-    init_path();
-    init_build();
-    init_renderer();
-    init_theme();
-    init_hash();
-    init_log();
-    init_events();
-    init_captions();
-    init_schema();
-    init_tts();
-    init_mux();
-  }
-});
-
-// 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];
+  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;
   }
-  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;
+  manifest.videoSha256 = await sha256File(videoPath);
+  const manifestPath = join8(opts.outDir, "compose-manifest.json");
+  await writeFile3(manifestPath, JSON.stringify(manifest, null, 2));
+  return { videoPath, manifestPath, manifest };
+}
+function safeHost(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
   }
-  if (da < 1e-6 || db < 1e-6) return da < 1e-6 && db < 1e-6 ? 1 : 0;
-  return num / Math.sqrt(da * db);
 }
-var init_media = __esm({
-  "src/verify/media.ts"() {
+var BLINK_DIFF_MIN, JUMP_DIFF_MIN, JUMP_DISSOLVE_MS;
+var init_compose = __esm({
+  "src/compose/index.ts"() {
     "use strict";
-    init_ffmpeg();
+    init_schema();
+    init_theme();
+    init_types();
+    init_kinds();
+    init_pacing();
+    init_planner();
+    init_path();
+    init_build();
+    init_renderer();
+    init_media();
     init_reader();
+    init_theme();
+    init_hash();
+    init_log();
+    init_events();
+    init_captions();
+    init_schema();
+    init_tts();
+    init_mux();
+    BLINK_DIFF_MIN = 25;
+    JUMP_DIFF_MIN = 18;
+    JUMP_DISSOLVE_MS = 360;
   }
 });
 
@@ -4708,7 +5472,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 = [];
@@ -4766,12 +5570,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) {
@@ -4779,10 +5585,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);
@@ -4790,11 +5597,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 }));
@@ -4829,7 +5648,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 = [];
@@ -4840,7 +5670,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;
@@ -4848,7 +5678,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 = [];
@@ -4864,7 +5722,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",
@@ -4999,9 +5870,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) {
@@ -5059,7 +5958,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 } };
 }
 var EFFECT_KINDS, CLICK_KINDS2;
 var init_checks = __esm({
@@ -5242,17 +6141,24 @@ var init_vision = __esm({
 // src/verify/report.ts
 var report_exports = {};
 __export(report_exports, {
+  flowFailureJUnit: () => flowFailureJUnit,
+  keyIdFor: () => keyIdFor,
   signVerdict: () => signVerdict,
   signablePayload: () => signablePayload,
-  toJUnit: () => toJUnit
+  toJUnit: () => toJUnit,
+  verifySignature: () => verifySignature
 });
-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,
@@ -5261,35 +6167,102 @@ 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 verifySignature(v, opts = {}) {
+  if (!v.signature) return { valid: false, reason: "verdict is unsigned" };
+  const payload = Buffer.from(signablePayload(stripSignature(v)));
+  if (v.signature.alg === "Ed25519") {
+    if (!v.signature.publicKey) return { valid: false, reason: "Ed25519 signature missing its public key" };
+    const key = createPublicKey({
+      key: Buffer.from(v.signature.publicKey, "base64"),
+      type: "spki",
+      format: "der"
+    });
+    const ok = edVerify(null, payload, key, Buffer.from(v.signature.value, "base64"));
+    return ok ? { valid: true, reason: `Ed25519 signature valid for key ${v.signature.keyId} \u2014 pin this key id to trust the producer` } : { valid: false, reason: "Ed25519 SIGNATURE MISMATCH \u2014 the verdict was modified after signing" };
+  }
+  if (v.signature.alg === "HS256") {
+    const key = opts.hmacKey ?? process.env.PLAYHEAD_SIGNING_KEY;
+    if (!key) return { valid: false, reason: "HS256 verdict but PLAYHEAD_SIGNING_KEY is not set \u2014 cannot check" };
+    const expect = createHmac("sha256", key).update(payload).digest("hex");
+    return expect === v.signature.value ? { valid: true, reason: `HS256 signature valid (key ${v.signature.keyId}) \u2014 note: symmetric, proves integrity within the key's trust domain only` } : { valid: false, reason: "HS256 SIGNATURE MISMATCH \u2014 the verdict was modified after signing (or a different key)" };
+  }
+  return { valid: false, reason: `unknown signature algorithm ${v.signature.alg}` };
+}
+function stripSignature(v) {
+  const { signature: _sig, ...rest } = v;
+  return rest;
+}
+function keyIdFor(material) {
+  return createHash4("sha256").update(material).digest("hex").slice(0, 16);
 }
 function toJUnit(v, suiteName = "playhead") {
   const failures = v.checks.filter((c) => c.status === "fail").length;
   const skipped = v.checks.filter((c) => c.status === "skip").length;
-  const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   const cases = v.checks.map((c) => {
     const body = c.status === "fail" ? `
-    <failure message="${esc(c.details)}">${esc(
+    <failure message="${escXml(c.details)}">${escXml(
       (c.evidence ?? []).map((e) => `${e.stepRef ?? ""}${e.t !== void 0 ? ` @${(e.t / 1e3).toFixed(1)}s` : ""} \u2014 ${e.note}`).join("\n")
     )}</failure>
   ` : c.status === "skip" ? `
-    <skipped message="${esc(c.details)}"/>
+    <skipped message="${escXml(c.details)}"/>
   ` : "";
-    return `  <testcase classname="${esc(suiteName)}" name="${esc(c.id)}">${body}</testcase>`;
+    return `  <testcase classname="${escXml(suiteName)}" name="${escXml(c.id)}">${body}</testcase>`;
   }).join("\n");
   return `<?xml version="1.0" encoding="UTF-8"?>
-<testsuite name="${esc(suiteName)}" tests="${v.checks.length}" failures="${failures}" skipped="${skipped}">
+<testsuite name="${escXml(suiteName)}" tests="${v.checks.length}" failures="${failures}" skipped="${skipped}">
 ${cases}
 </testsuite>
 `;
 }
+function flowFailureJUnit(failure, suiteName = "playhead") {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuite name="${escXml(suiteName)}" tests="1" failures="1" skipped="0">
+  <testcase classname="${escXml(suiteName)}" name="flow">
+    <failure message="${escXml(`flow failed at ${failure.stepRef}`)}">${escXml(failure.message)}</failure>
+  </testcase>
+</testsuite>
+`;
+}
+function escXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 var init_report = __esm({
   "src/verify/report.ts"() {
     "use strict";
@@ -5297,12 +6270,12 @@ var init_report = __esm({
 });
 
 // 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";
 import { platform, arch } from "os";
 import pc2 from "picocolors";
 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");
@@ -5326,7 +6299,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;
@@ -5337,11 +6310,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,
@@ -5359,9 +6349,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;
 }
 async function loadComposeManifest(path) {
@@ -5389,7 +6380,7 @@ var init_runner = __esm({
     init_report();
     init_version();
     init_log();
-    CHECK_SUITE_VERSION = "playhead/checks@2";
+    CHECK_SUITE_VERSION = "playhead/checks@3";
   }
 });
 
@@ -5398,14 +6389,14 @@ var beforeafter_exports = {};
 __export(beforeafter_exports, {
   renderBeforeAfter: () => renderBeforeAfter
 });
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import { mkdir as mkdir5 } from "fs/promises";
 async function renderBeforeAfter(spec, opts) {
   if (!spec.app.compareUrl) {
     throw new Error('before-after needs app.compareUrl (the "before" version) alongside app.url (the "after")');
   }
   const side = async (label, url) => {
-    const dir = join9(opts.outDir, label);
+    const dir = join10(opts.outDir, label);
     await mkdir5(dir, { recursive: true });
     const sideSpec = {
       ...spec,
@@ -5421,7 +6412,7 @@ async function renderBeforeAfter(spec, opts) {
   };
   const before = await side("before", spec.app.compareUrl);
   const after = await side("after", spec.app.url);
-  const videoPath = join9(opts.outDir, "before-after.mp4");
+  const videoPath = join10(opts.outDir, "before-after.mp4");
   await concatVideos([before.videoPath, after.videoPath], videoPath);
   const publishable = before.verdict.verdict === "publishable" && after.verdict.verdict === "publishable";
   log.info(`before/after \u2192 ${videoPath}`);
@@ -5456,8 +6447,8 @@ __export(jira_exports, {
   reportToJira: () => reportToJira
 });
 import { readFile as readFile5, stat } from "fs/promises";
-import { join as join10, basename } from "path";
-import { existsSync as existsSync4 } from "fs";
+import { join as join11, basename } from "path";
+import { existsSync as existsSync5 } from "fs";
 function jiraConfigFromEnv() {
   const baseUrl = process.env.JIRA_BASE_URL;
   const email = process.env.JIRA_EMAIL;
@@ -5521,17 +6512,17 @@ async function addComment(cfg, issueKey, adfBody) {
 }
 async function collectEvidence(outDir) {
   const candidates = [
-    join10(outDir, "out.mp4"),
-    join10(outDir, "failure.mp4"),
-    join10(outDir, "verify", "verdict.json"),
-    join10(outDir, "verify", "contact-sheet.png"),
-    join10(outDir, "junit.xml"),
-    join10(outDir, "capture", "failure.json"),
-    join10(outDir, "capture", "console.json")
+    join11(outDir, "out.mp4"),
+    join11(outDir, "failure.mp4"),
+    join11(outDir, "verify", "verdict.json"),
+    join11(outDir, "verify", "contact-sheet.png"),
+    join11(outDir, "junit.xml"),
+    join11(outDir, "capture", "failure.json"),
+    join11(outDir, "capture", "console.json")
   ];
   const files = [];
   for (const f of candidates) {
-    if (!existsSync4(f)) continue;
+    if (!existsSync5(f)) continue;
     const s = await stat(f);
     if (s.size > 95 * 1024 * 1024) {
       log.warn(`skipping ${basename(f)} (${(s.size / 1e6).toFixed(0)}MB \u2014 larger than Jira's usual attachment ceiling)`);
@@ -5543,11 +6534,11 @@ async function collectEvidence(outDir) {
     throw new InfraError(`no Playhead artifacts found under ${outDir} \u2014 expected out.mp4/failure.mp4, verify/verdict.json, \u2026`);
   }
   let verdict;
-  const verdictPath = join10(outDir, "verify", "verdict.json");
-  if (existsSync4(verdictPath)) verdict = JSON.parse(await readFile5(verdictPath, "utf8"));
+  const verdictPath = join11(outDir, "verify", "verdict.json");
+  if (existsSync5(verdictPath)) verdict = JSON.parse(await readFile5(verdictPath, "utf8"));
   let failure;
-  const failurePath = join10(outDir, "capture", "failure.json");
-  if (existsSync4(failurePath)) failure = JSON.parse(await readFile5(failurePath, "utf8"));
+  const failurePath = join11(outDir, "capture", "failure.json");
+  if (existsSync5(failurePath)) failure = JSON.parse(await readFile5(failurePath, "utf8"));
   const outcome = failure ? "flow-failed" : verdict?.verdict ?? "unknown";
   return { outcome, ...verdict ? { verdict } : {}, ...failure ? { failure } : {}, files };
 }
@@ -5647,7 +6638,7 @@ function kindOf(el) {
 function quote(s) {
   const clean = s.replace(/\s+/g, " ").trim();
   if (clean.includes('"')) {
-    return `/${escapeRegex(clean).replace(/\//g, "\\/")}/`;
+    return `/${escapeRegex(clean).replace(/\//g, "\\/").replace(/>/g, "\\x3e")}/`;
   }
   return `"${clean}"`;
 }
@@ -5686,7 +6677,12 @@ async function snapshotPage(driver) {
     let unique = false;
     let ambiguous = null;
     for (const cand of candidates) {
-      const count = await driver.countMatches(parseLocator(cand)).catch(() => 0);
+      let count = 0;
+      try {
+        count = await driver.countMatches(parseLocator(cand)).catch(() => 0);
+      } catch {
+        continue;
+      }
       if (count === 1) {
         chosen = cand;
         unique = true;
@@ -5784,13 +6780,54 @@ async function validateLive(spec, opts) {
       viewport: resolveViewport(spec),
       dpr: 1,
       headless: opts?.headless ?? true,
-      ...spec.app.storageState ? { storageStatePath: spec.app.storageState } : {}
+      ...spec.app.storageState ? { storageStatePath: spec.app.storageState } : {},
+      ...spec.app.environment ? { environment: spec.app.environment } : {},
+      ...spec.app.network ? { network: spec.app.network } : {},
+      ...spec.app.dialogs ? { dialogs: spec.app.dialogs } : {}
     });
   }
+  const settleCfg = { idleMs: spec.app.settle?.idleMs ?? 300, capMs: spec.app.settle?.capMs ?? 5e3 };
+  const vp = resolveViewport(spec);
+  const res = resolveResolution(spec);
+  const plane2 = { vpW: vp.w, vpH: vp.h, outW: res.w, outH: res.h };
   try {
     await driver.goto(spec.app.url);
-    await driver.settle({ idleMs: 300, capMs: 5e3 });
-    for (const a of flattenSteps(spec)) {
+    await driver.settle(settleCfg);
+    if (spec.app.assertLoggedIn) {
+      const n = await driver.countMatches(parseLocator(spec.app.assertLoggedIn)).catch(() => 0);
+      if (n === 0) {
+        issues.push({
+          stepRef: "(setup)",
+          step: "assertLoggedIn",
+          locator: spec.app.assertLoggedIn,
+          severity: "error",
+          message: "assertLoggedIn matches nothing \u2014 storageState stale? Re-run: playhead login",
+          suggestions: []
+        });
+      }
+    }
+    for (const m of spec.masking) {
+      checked += 1;
+      const n = await driver.countMatches(parseLocator(m.target)).catch(() => 0);
+      if (n === 0) {
+        issues.push({
+          stepRef: "(masking)",
+          step: "mask",
+          locator: m.target,
+          severity: "warn",
+          message: "masking rule matches nothing on the initial screen (fine if the element appears later \u2014 verify the render)",
+          suggestions: []
+        });
+      }
+    }
+    const setupSteps = spec.setup.map((step, i) => ({
+      sceneId: "setup",
+      sceneIndex: -1,
+      stepIndex: i,
+      ordinal: 0,
+      step
+    }));
+    for (const a of [...setupSteps, ...flattenSteps(spec)]) {
       const stepRef = `${a.sceneId}/${a.stepIndex}`;
       const step = a.step;
       const push = async (locator, severity, message) => {
@@ -5805,6 +6842,7 @@ async function validateLive(spec, opts) {
       };
       const locators = [];
       if ("target" in step && step.target) locators.push({ value: step.target, kind: "target" });
+      if (step.action === "drag") locators.push({ value: step.to, kind: "target" });
       if (step.action === "wait" && step.for) locators.push({ value: step.for, kind: "wait" });
       if (step.focus && step.focus !== "target" && step.focus !== "wide") {
         locators.push({ value: step.focus, kind: "focus" });
@@ -5820,6 +6858,14 @@ async function validateLive(spec, opts) {
           await push(l.value, "warn", `ambiguous: ${count} matches \u2014 add '>> nth=N' to pick one`);
         }
       }
+      if (a.sceneIndex >= 0 && "target" in step && step.target && FRAMED_ACTIONS.has(step.action)) {
+        try {
+          const t = await driver.resolveTarget(parseLocator(step.target), 3e3);
+          const violation = framingViolation(t.bbox, plane2);
+          if (violation) await push(step.target, "warn", violation);
+        } catch {
+        }
+      }
       try {
         await fastExecute(driver, step);
       } catch (e) {
@@ -5841,6 +6887,12 @@ async function validateLive(spec, opts) {
         if (n > 0) {
           const idx = issues.findIndex((i) => i.stepRef === stepRef && i.locator === focus && i.severity === "warn");
           if (idx >= 0) issues.splice(idx, 1);
+          try {
+            const t = await driver.resolveTarget(loc, 3e3);
+            const violation = framingViolation(t.bbox, plane2);
+            if (violation) await push(focus, "warn", violation);
+          } catch {
+          }
         }
       }
     }
@@ -5849,6 +6901,16 @@ async function validateLive(spec, opts) {
   }
   return { ok: !issues.some((i) => i.severity === "error"), checked, issues };
 }
+function framingViolation(bbox, plane2) {
+  const cam = clampCamera(
+    { cx: bbox.x + bbox.w / 2, cy: bbox.y + bbox.h / 2, zoom: minZoom(plane2) },
+    plane2
+  );
+  const proj = projectRect(bbox, cam, plane2);
+  if (rectContains({ x: 0, y: 0, w: plane2.outW, h: plane2.outH }, proj, 2)) return null;
+  const fullBleed = bbox.x <= 2 || bbox.y <= 2 || bbox.x + bbox.w >= plane2.vpW - 2 || bbox.y + bbox.h >= plane2.vpH - 2;
+  return fullBleed ? "full-bleed target (touches the viewport edge) \u2014 no camera can frame it with the 2px margin verification requires; target a smaller element inside it, or make this a scroll/wait step" : "target is larger than the widest camera view \u2014 verification's target-in-frame check will fail; use focus: on a smaller payoff element";
+}
 async function fastExecute(driver, step) {
   const FAST_TIMEOUT = step.timeout ?? 8e3;
   switch (step.action) {
@@ -5883,13 +6945,28 @@ async function fastExecute(driver, step) {
       else if (step.by) await driver.scrollBy(step.by);
       await driver.waitForScrollSettle(1500);
       break;
+    case "rightclick": {
+      await driver.resolveTarget(parseLocator(step.target), FAST_TIMEOUT);
+      await driver.actClick(parseLocator(step.target), { button: "right", timeoutMs: FAST_TIMEOUT });
+      break;
+    }
+    case "upload":
+      await driver.setInputFiles(parseLocator(step.target), step.file);
+      break;
+    case "drag":
+      await driver.dragTo(parseLocator(step.target), parseLocator(step.to), FAST_TIMEOUT);
+      break;
     case "expect":
       await driver.expectState(
-        parseLocator(step.target),
+        step.target ? parseLocator(step.target) : null,
         {
           ...step.visible !== void 0 ? { visible: step.visible } : {},
           ...step.text !== void 0 ? { text: step.text } : {},
-          ...step.count !== void 0 ? { count: step.count } : {}
+          ...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 } : {}
         },
         FAST_TIMEOUT
       );
@@ -5937,6 +7014,7 @@ function formatValidateResult(res) {
   );
   return lines.join("\n");
 }
+var FRAMED_ACTIONS;
 var init_validate = __esm({
   "src/authoring/validate.ts"() {
     "use strict";
@@ -5946,6 +7024,7 @@ var init_validate = __esm({
     init_schema();
     init_explore();
     init_geometry();
+    FRAMED_ACTIONS = /* @__PURE__ */ new Set(["click", "dblclick", "hover", "type", "select", "expect"]);
   }
 });
 
@@ -6018,25 +7097,46 @@ async function authorSpec(opts) {
   const owned = !opts.driver;
   const steps = [];
   log.info(`authoring "${opts.goal}" against ${opts.url}`);
-  if (owned) await driver.launch({ viewport: opts.viewport, dpr: 2, headless: opts.headless });
+  if (owned)
+    await driver.launch({
+      viewport: opts.viewport,
+      dpr: 2,
+      headless: opts.headless,
+      ...opts.storageStatePath ? { storageStatePath: opts.storageStatePath } : {}
+    });
   try {
     await driver.goto(opts.url);
     await driver.settle(SETTLE2);
+    let feedback;
+    let consecutiveFailures = 0;
     for (let i = 0; i < opts.maxSteps; i++) {
       const snap = await snapshotPage(driver);
-      const decision = await decide(opts.goal, snap, steps);
+      const decision = await decide(opts.goal, snap, steps, feedback);
       if (decision.done || !decision.action) {
-        log.ok(`agent finished: ${decision.reason ?? "goal shown"}`);
+        if (decision.done) log.ok(`agent finished: ${decision.reason ?? "goal shown"}`);
+        else log.warn(`agent returned no action (${decision.reason ?? "no reason"}) \u2014 stopping`);
         break;
       }
+      if (decision.locator && !snap.catalog.some((e) => e.locator === decision.locator)) {
+        feedback = `Your locator ${decision.locator} is NOT in the catalog \u2014 copy one verbatim from the list.`;
+        consecutiveFailures += 1;
+        log.warn(`agent invented a locator (${decision.locator}); asking it to pick from the catalog`);
+        if (consecutiveFailures >= 3) throw new Error("authoring stuck: 3 consecutive invalid steps \u2014 the goal may not be reachable from this screen");
+        continue;
+      }
       const step = toAuthoredStep(decision);
       log.step(`${steps.length + 1}. ${describe(step)}${decision.reason ? `  \u2014 ${decision.reason}` : ""}`);
       try {
         await perform(driver, step);
         await driver.settle(SETTLE2);
         steps.push(step);
+        feedback = void 0;
+        consecutiveFailures = 0;
       } catch (e) {
-        log.warn(`step failed (${e.message}); asking the agent to adjust`);
+        feedback = `Your last step FAILED: ${describe(step)} \u2014 ${e.message.split("\n")[0]}. Choose a different step.`;
+        consecutiveFailures += 1;
+        log.warn(`step failed (${e.message.split("\n")[0]}); feeding the failure back to the agent`);
+        if (consecutiveFailures >= 3) throw new Error(`authoring stuck: 3 consecutive step failures (last: ${describe(step)})`);
       }
     }
     if (steps.length === 0) throw new Error("authoring produced no steps \u2014 the goal may not be reachable from this URL");
@@ -6044,11 +7144,20 @@ async function authorSpec(opts) {
       title: opts.title ?? capitalize(opts.goal),
       url: opts.url,
       viewport: opts.viewport,
-      kind: "walkthrough",
+      kind: opts.kind ?? "walkthrough",
       steps
     };
-    await writeFile6(opts.outPath, serializeSpec(spec));
-    log.ok(`wrote ${steps.length}-step spec \u2192 ${opts.outPath}`);
+    const yaml = serializeSpec(spec);
+    const { parseSpec: parseSpec2 } = await Promise.resolve().then(() => (init_parse(), parse_exports));
+    try {
+      parseSpec2(yaml, opts.outPath);
+    } catch (e) {
+      await writeFile6(opts.outPath, yaml);
+      throw new Error(`authored spec failed validation \u2014 written to ${opts.outPath} for inspection:
+${e.message}`);
+    }
+    await writeFile6(opts.outPath, yaml);
+    log.ok(`wrote ${steps.length}-step spec \u2192 ${opts.outPath} (validated)`);
     log.info(`next: playhead render ${opts.outPath}`);
     return { specPath: opts.outPath, steps };
   } finally {
@@ -6065,9 +7174,16 @@ function claudeDecider() {
     if (!clientPromise) clientPromise = import("@anthropic-ai/sdk").then((m) => new m.default());
     return clientPromise;
   };
-  return async (goal, snap, soFar) => {
+  return async (goal, snap, soFar, feedback) => {
     const client = await getClient();
-    const catalog = snap.catalog.map((e) => `  ${e.locator}${e.options ? `   (options: ${e.options.join(" | ")})` : ""}${e.unique ? "" : "   [ambiguous]"}`).join("\n");
+    let catalog = snap.catalog.map((e) => `  ${e.locator}${e.options ? `   (options: ${e.options.join(" | ")})` : ""}${e.unique ? "" : "   [ambiguous]"}`).join("\n");
+    const CATALOG_CAP = 12e3;
+    if (catalog.length > CATALOG_CAP) {
+      const kept = catalog.slice(0, CATALOG_CAP);
+      const dropped = catalog.slice(CATALOG_CAP).split("\n").length;
+      catalog = kept + `
+  \u2026 (catalog truncated \u2014 ${dropped} more elements not shown)`;
+    }
     const history = soFar.length ? soFar.map((s, i) => `  ${i + 1}. ${describe(s)}`).join("\n") : "  (none yet)";
     const userMsg = [
       `GOAL: ${goal}`,
@@ -6078,6 +7194,7 @@ function claudeDecider() {
       ``,
       `STEPS SO FAR:`,
       history,
+      ...feedback ? [``, `IMPORTANT \u2014 PREVIOUS ATTEMPT: ${feedback}`] : [],
       ``,
       `Emit the next step (or done=true if the goal is fully shown).`
     ].join("\n");
@@ -6209,7 +7326,7 @@ __export(server_exports, {
 });
 import { mkdtemp, writeFile as writeFile7, mkdir as mkdir6, readFile as readFile6 } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join11, resolve, isAbsolute } from "path";
+import { join as join12, resolve, isAbsolute } from "path";
 import { z as z2 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -6232,11 +7349,16 @@ function buildServer() {
       description: "Launch the running web app and return a grounded catalog of addressable elements \u2014 each line is a Playhead locator validated to resolve uniquely against the real DOM. Use these locators verbatim when writing a spec. Only shows the CURRENT screen; call again after a navigation to see later screens.",
       inputSchema: {
         url: z2.string().describe("the running app URL, e.g. http://localhost:3000"),
-        viewport: dims.describe("viewport WxH")
+        viewport: dims.describe("viewport WxH"),
+        storageState: z2.string().optional().describe("session file from `playhead login` \u2014 REQUIRED for authenticated apps")
       }
     },
-    async ({ url, viewport }) => {
-      const snap = await exploreUrl(url, { viewport: parseDims(viewport), headless: true });
+    async ({ url, viewport, storageState }) => {
+      const snap = await exploreUrl(url, {
+        viewport: parseDims(viewport),
+        headless: true,
+        ...storageState ? { storageStatePath: resolve(storageState) } : {}
+      });
       return { content: [{ type: "text", text: formatCatalog(snap) }] };
     }
   );
@@ -6249,10 +7371,11 @@ function buildServer() {
         url: z2.string(),
         goal: z2.string().describe('what flow to demo, e.g. "create a new deal for Globex"'),
         outPath: z2.string().default("playhead.yaml").describe("where to write the spec"),
-        viewport: dims
+        viewport: dims,
+        storageState: z2.string().optional().describe("session file from `playhead login` for authenticated apps")
       }
     },
-    async ({ url, goal, outPath, viewport }) => {
+    async ({ url, goal, outPath, viewport, storageState }) => {
       const path = isAbsolute(outPath) ? outPath : resolve(outPath);
       const { steps } = await authorSpec({
         url,
@@ -6260,7 +7383,8 @@ function buildServer() {
         outPath: path,
         viewport: parseDims(viewport),
         maxSteps: 40,
-        headless: true
+        headless: true,
+        ...storageState ? { storageStatePath: resolve(storageState) } : {}
       });
       const yaml = await readFile6(path, "utf8");
       return { content: [{ type: "text", text: `Wrote ${steps.length}-step spec to ${path}
@@ -6316,21 +7440,48 @@ ${formatValidateResult2(res)}` }],
       await mkdir6(out, { recursive: true });
       let parsedSpec;
       if (spec) {
-        const tmp = await mkdtemp(join11(tmpdir(), "playhead-spec-"));
-        const p = join11(tmp, "spec.yaml");
+        const tmp = await mkdtemp(join12(tmpdir(), "playhead-spec-"));
+        const p = join12(tmp, "spec.yaml");
         await writeFile7(p, spec);
         parsedSpec = parseSpec(spec);
       } else {
         parsedSpec = await loadSpec(resolve(specPath));
       }
-      const { bundleDir } = await capture(parsedSpec, { outDir: out, headless: true });
-      const bundle = await openBundle(bundleDir);
-      const composed = await compose(bundle, parsedSpec, { outDir: out });
-      const verdict = await verify(bundle, composed.manifest, composed.videoPath, { outDir: out, vision });
-      return {
-        content: [{ type: "text", text: renderVerdictReport(verdict, composed.videoPath, composed.manifestPath) }],
-        isError: verdict.verdict !== "publishable"
-      };
+      try {
+        const { bundleDir } = await capture(parsedSpec, { outDir: out, headless: true });
+        const bundle = await openBundle(bundleDir);
+        const composed = await compose(bundle, parsedSpec, { outDir: out });
+        const verdict = await verify(bundle, composed.manifest, composed.videoPath, { outDir: out, vision });
+        return {
+          content: [{ type: "text", text: renderVerdictReport(verdict, composed.videoPath, composed.manifestPath) }],
+          isError: verdict.verdict !== "publishable"
+        };
+      } catch (e) {
+        const { FlowError: FlowError2 } = await Promise.resolve().then(() => (init_exit(), exit_exports));
+        if (e instanceof FlowError2) {
+          let clipLine = "";
+          try {
+            const bundle = await openBundle(join12(out, "capture"));
+            const clip = await compose(bundle, parsedSpec, { outDir: out, fileName: "failure.mp4" });
+            clipLine = `
+failure clip: ${clip.videoPath}  (watch the flow up to the break)`;
+          } catch {
+          }
+          const failure = await readFile6(join12(out, "capture", "failure.json"), "utf8").catch(() => null);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `FLOW FAILED \u2014 the app broke the scripted flow.
+${failure ?? e.message}${clipLine}
+Fix the spec (or the app) and render again.`
+              }
+            ],
+            isError: true
+          };
+        }
+        throw e;
+      }
     }
   );
   server.registerTool(
@@ -6414,9 +7565,35 @@ init_hash();
 init_exit();
 init_version();
 import { Command } from "commander";
-import { mkdir as mkdir7, writeFile as writeFile8, access } from "fs/promises";
-import { join as join12, resolve as resolve2 } from "path";
+import { mkdir as mkdir7, writeFile as writeFile8, access as access2 } from "fs/promises";
+import { join as join13, resolve as resolve2 } from "path";
 import pc3 from "picocolors";
+async function readFailureJson(bundleDir) {
+  return readJsonIfExists(join13(bundleDir, "failure.json"));
+}
+async function readJsonIfExists(path) {
+  try {
+    const { readFile: readFile7 } = await import("fs/promises");
+    return JSON.parse(await readFile7(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function exportGif(videoPath, width) {
+  const gifPath = videoPath.replace(/\.mp4$/i, ".gif");
+  const fps = 12;
+  await runBinary(ffmpegPath(), [
+    "-y",
+    "-loglevel",
+    "error",
+    "-i",
+    videoPath,
+    "-filter_complex",
+    `[0:v]fps=${fps},scale=${width}:-1:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle`,
+    gifPath
+  ]);
+  return gifPath;
+}
 async function emitReports(verdict, opts) {
   if (opts.json) console.log(JSON.stringify(verdict, null, 2));
   if (opts.junit) {
@@ -6430,13 +7607,96 @@ program.name("playhead").description("Product video as a build artifact: spec +
 program.hook("preAction", (cmd) => {
   if (cmd.opts().verbose) setVerbose(true);
 });
-program.command("render").description("capture \u2192 compose \u2192 verify; exit 0 only if every spec is publishable").argument("<specs...>", "spec YAML path(s) \u2014 multiple files render as a pool").option("-o, --out <dir>", "output directory (per-spec subdirs when rendering several)", "out").option("-w, --workers <n>", "concurrent renders when given multiple specs", "2").option("--vision", "run the Claude vision review (needs ANTHROPIC_API_KEY)").option("--json", "print the verdict JSON to stdout (human logs go to stderr)").option("--junit <path>", "write a JUnit XML report (one testcase per check)").option("--jira <issueKey>", "report the outcome (evidence + verdict comment) to an existing Jira issue \u2014 success OR flow failure").option("--headed", "show the browser while capturing").action(async (specPaths, opts) => {
-  const renderOne = async (specPath, outDir) => {
+program.addHelpText(
+  "after",
+  `
+Get started (first run):
+  npx playwright install chromium    one-time browser download (~100MB)
+  playhead explore <your-app-url>    see what's addressable \u2014 real locators to paste into a spec
+  playhead init demo.yaml            scaffold a spec, then paste those locators in
+  playhead validate demo.yaml        check every locator against the live app
+  playhead render demo.yaml -o out   \u2192 out/out.mp4 + out/verify/verdict.json
+
+Run ${pc3.bold("playhead guide")} for the full workflow, grouped by task, with examples.`
+);
+program.command("guide").description("the commands grouped by workflow \u2014 what to run, in what order, and why").action(() => {
+  const g = (s) => pc3.bold(pc3.cyan(s));
+  console.log(`
+${pc3.bold("Playhead \u2014 from install to a verified video")}
+
+The loop: ${pc3.bold("explore \u2192 spec \u2192 validate \u2192 render")}. Playhead films your real app, so every
+locator in a spec must name a real element \u2014 ${pc3.bold("explore")} is how you get those, not guesswork.
+
+${g("One-time setup")}
+  npx playwright install chromium    download the capture browser
+  playhead doctor                    check ffmpeg, browser, and fonts are ready
+
+${g("Author a spec")}
+  playhead explore <url>             START HERE \u2014 every addressable element on the current
+                                     screen, each with a validated, ready-to-paste locator
+  playhead init [path]               scaffold a starter spec to paste those locators into
+  playhead author <url> <goal>       or let an agent walk the app and write the spec for you
+                                     (needs ANTHROPIC_API_KEY)
+
+${g("Check before rendering")}
+  playhead validate <spec>           dry-run every locator against the live app in one pass,
+                                     with nearest-match suggestions \u2014 before any frame is filmed
+
+${g("Keep noise off the film")}
+  setup: steps (top-level in the spec) run BEFORE recording starts \u2014 dismiss the cookie-consent
+  banner, close a first-run tour \u2014 so the first filmed frame is already presentable.
+  Slow SPA? Give steps wait: { for: <locator> } so loading spinners never get filmed
+  (verify warns when a frame's content region is blank).
+
+${g("Make the video")}
+  playhead render <spec> -o out      capture \u2192 compose \u2192 verify; exit 0 only when publishable
+  playhead compose <bundle>          re-render from a capture with new text/theme/audio \u2014
+                                     no live app needed
+
+${g("Optional: add a voice")}
+  Videos are silent by default \u2014 usually right for a demo. To narrate, set
+  output.audio: { narration: tts } and give steps a narration: line, then re-run
+  ${pc3.bold("compose")} on the existing capture \u2014 a voice change never needs re-recording.
+  Providers: say (macOS built-in, zero setup) or kokoro (natural, offline,
+  cross-platform \u2014 if you want the quality, it's a one-time npm i -g kokoro-js, ~400MB).
+
+${g("Trust the output")}
+  playhead verify <bundle> <mp4>     re-run the verification suite on a rendered video
+  playhead attest <verify-dir>       prove a verdict describes exactly these files, unedited
+  playhead jira report <KEY>         attach the evidence to an existing Jira issue
+
+${g("Authed apps")}
+  playhead login <url>               log in yourself in a headed browser; the saved session
+                                     drives app.storageState (Playhead never sees credentials)
+
+${g("A complete first run")}
+  playhead explore http://localhost:3000
+  playhead init demo.yaml            ${pc3.dim("# edit: set app.url, paste explore's locators")}
+  playhead validate demo.yaml
+  playhead render demo.yaml -o out   ${pc3.dim("# \u2192 out/out.mp4, out/verify/verdict.json")}
+`);
+});
+program.command("render").description("capture \u2192 compose \u2192 verify; exit 0 only if every spec is publishable").argument("<specs...>", "spec YAML path(s) \u2014 multiple files render as a pool").option("-o, --out <dir>", "output directory (per-spec subdirs when rendering several)", "out").option("-w, --workers <n>", "concurrent renders when given multiple specs", "2").option("--vision", "run the Claude vision review (needs ANTHROPIC_API_KEY)").option("--json", "print the verdict JSON to stdout (human logs go to stderr)").option("--junit <path>", "write a JUnit XML report (one testcase per check)").option("--jira <issueKey>", "report the outcome (evidence + verdict comment) to an existing Jira issue \u2014 success OR flow failure").option("--gif [width]", "also export an embeddable GIF next to the MP4 (default width 960)").option("--headed", "show the browser while capturing").addHelpText(
+  "after",
+  `
+Examples:
+  playhead render demo.yaml -o out               one spec \u2192 out/out.mp4 + out/verify/verdict.json
+  playhead render specs/*.yaml -o out -w 4       a pool, four at a time, per-spec subdirs
+  playhead render demo.yaml --junit report.xml   CI: one testcase per verification check
+  playhead render demo.yaml --jira PROJ-123      attach the evidence to a Jira issue either way`
+).action(async (specPaths, opts) => {
+  const renderOne = async (specPath, outDir, reportOpts) => {
     const spec = await loadSpec(specPath);
     await mkdir7(outDir, { recursive: true });
     if (spec.output.kind === "before-after") {
       const { renderBeforeAfter: renderBeforeAfter2 } = await Promise.resolve().then(() => (init_beforeafter(), beforeafter_exports));
       const res = await renderBeforeAfter2(spec, { outDir, headless: !opts.headed, vision: opts.vision ?? false });
+      if (reportOpts.json) console.log(JSON.stringify({ schema: "playhead/before-after@1", ...res }, null, 2));
+      if (reportOpts.junit && res.after) {
+        const { toJUnit: toJUnit2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+        await writeFile8(resolve2(reportOpts.junit), toJUnit2(res.after.verdict, "playhead-before-after"));
+        log.ok(`junit \u2192 ${reportOpts.junit}`);
+      }
       return res.verdict === "publishable" ? EXIT.OK : EXIT.QUALITY;
     }
     try {
@@ -6447,25 +7707,43 @@ program.command("render").description("capture \u2192 compose \u2192 verify; exi
         outDir,
         vision: opts.vision ?? false
       });
-      await emitReports(verdict, opts);
+      await emitReports(verdict, reportOpts);
+      if (opts.gif) {
+        const gifW = typeof opts.gif === "string" ? Number(opts.gif) || 960 : 960;
+        log.ok(`gif \u2192 ${await exportGif(result.videoPath, gifW)}`);
+      }
       return verdict.verdict === "publishable" ? EXIT.OK : EXIT.QUALITY;
     } catch (e) {
       if (e instanceof FlowError) {
         log.error(e.message);
+        let failureClip;
         try {
-          const bundle = await openBundle(join12(outDir, "capture"));
+          const bundle = await openBundle(join13(outDir, "capture"));
           const result = await compose(bundle, spec, { outDir, fileName: "failure.mp4" });
+          failureClip = result.videoPath;
           log.ok(`failure clip \u2192 ${result.videoPath}`);
         } catch (clipErr) {
           log.warn(`could not render the failure clip: ${clipErr.message}`);
         }
+        const failure = await readFailureJson(join13(outDir, "capture")) ?? {
+          stepRef: "(unknown)",
+          message: e.message.split("\n")[0] ?? "flow failed"
+        };
+        if (reportOpts.json) {
+          console.log(JSON.stringify({ schema: "playhead/flow-failure@1", outcome: "flow-failed", failure, failureClip: failureClip ?? null, bundleDir: join13(outDir, "capture") }, null, 2));
+        }
+        if (reportOpts.junit) {
+          const { flowFailureJUnit: flowFailureJUnit2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+          await writeFile8(resolve2(reportOpts.junit), flowFailureJUnit2(failure));
+          log.ok(`junit \u2192 ${reportOpts.junit}`);
+        }
         return EXIT.FLOW;
       }
       throw e;
     }
   };
   if (specPaths.length === 1) {
-    const code = await renderOne(specPaths[0], resolve2(opts.out));
+    const code = await renderOne(specPaths[0], resolve2(opts.out), opts);
     if (opts.jira && code !== EXIT.INFRA && code !== EXIT.USAGE) {
       try {
         const { reportToJira: reportToJira2 } = await Promise.resolve().then(() => (init_jira(), jira_exports));
@@ -6480,20 +7758,38 @@ program.command("render").description("capture \u2192 compose \u2192 verify; exi
   if (opts.jira) log.warn("--jira is single-spec only for now \u2014 skipping the report for this multi-spec pool");
   const workers = Math.max(1, Number(opts.workers) || 2);
   log.info(`rendering ${specPaths.length} specs with ${workers} worker(s)`);
+  const names = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const path of specPaths) {
+    let name = (path.split(/[\\/]/).pop() ?? path).replace(/\.ya?ml$/, "");
+    let unique = name;
+    for (let i = 2; seen.has(unique); i++) unique = `${name}-${i}`;
+    seen.add(unique);
+    names.set(path, unique);
+  }
   const queue = [...specPaths];
   const results = /* @__PURE__ */ new Map();
+  const jsonDocs = [];
   await Promise.all(
     Array.from({ length: Math.min(workers, queue.length) }, async () => {
       for (let path = queue.shift(); path !== void 0; path = queue.shift()) {
-        const name = path.replace(/\.ya?ml$/, "").split("/").pop();
+        const name = names.get(path);
+        const junit = opts.junit ? opts.junit.replace(/\.xml$/, "") + `-${name}.xml` : void 0;
         try {
-          results.set(path, await renderOne(path, resolve2(join12(opts.out, name))));
+          const code = await renderOne(path, resolve2(join13(opts.out, name)), { ...junit ? { junit } : {} });
+          results.set(path, code);
+          if (opts.json) {
+            const v = await readJsonIfExists(join13(resolve2(opts.out), name, "verify", "verdict.json"));
+            jsonDocs.push({ spec: path, exitCode: code, verdict: v ?? null });
+          }
         } catch (e) {
           results.set(path, e);
+          if (opts.json) jsonDocs.push({ spec: path, exitCode: exitCodeFor(e), error: e.message.split("\n")[0] });
         }
       }
     })
   );
+  if (opts.json) console.log(JSON.stringify(jsonDocs, null, 2));
   let worst = EXIT.OK;
   for (const [path, res] of results) {
     if (res === EXIT.OK) log.ok(path);
@@ -6515,17 +7811,17 @@ program.command("capture").description("capture a live app into a re-renderable
 program.command("compose").description("re-render video from a capture bundle \u2014 no live app needed").argument("<bundle>", "path to a capture bundle directory").option("-o, --out <dir>", "output directory (default: bundle parent)").option(
   "--spec <file>",
   "compose with a LIVE spec file instead of the bundled snapshot \u2014 captions, narration, theme, audio, pacing all come from it, so text edits are a re-compose, never a re-capture"
-).option("--expect-sha <hex>", "assert the rendered MP4 hashes to this sha256 (determinism check: same bundle + spec \u2192 same video)").action(async (bundleDir, opts) => {
+).option("--expect-sha <hex>", "assert the rendered MP4 hashes to this sha256 (determinism check: same bundle + spec \u2192 same video)").option("--aspects <list>", 'ALSO render these aspects from the same bundle, e.g. "9:16,1:1" \u2014 footage becomes a correctly-proportioned card on each canvas (out-9x16.mp4, \u2026)').option("--gif [width]", "also export an embeddable GIF (default width 960) \u2014 the PR-comment format").action(async (bundleDir, opts) => {
   const bundle = await openBundle(resolve2(bundleDir));
   const spec = opts.spec ? await loadSpec(resolve2(opts.spec)) : JSON.parse(
-    await (await import("fs/promises")).readFile(join12(resolve2(bundleDir), "spec.resolved.json"), "utf8")
+    await (await import("fs/promises")).readFile(join13(resolve2(bundleDir), "spec.resolved.json"), "utf8")
   );
   if (opts.spec && sha256Json(spec.scenes.map((s) => s.id)) !== sha256Json(
-    JSON.parse(await (await import("fs/promises")).readFile(join12(resolve2(bundleDir), "spec.resolved.json"), "utf8")).scenes.map((s) => s.id)
+    JSON.parse(await (await import("fs/promises")).readFile(join13(resolve2(bundleDir), "spec.resolved.json"), "utf8")).scenes.map((s) => s.id)
   )) {
     log.warn("--spec scene ids differ from the captured spec \u2014 steps that moved will keep their captured footage positions");
   }
-  const outDir = resolve2(opts.out ?? join12(resolve2(bundleDir), ".."));
+  const outDir = resolve2(opts.out ?? join13(resolve2(bundleDir), ".."));
   await mkdir7(outDir, { recursive: true });
   const result = await compose(bundle, spec, { outDir, theme: resolveTheme(spec) });
   if (opts.expectSha) {
@@ -6537,8 +7833,33 @@ program.command("compose").description("re-render video from a capture bundle \u
       log.ok(`determinism check: sha256 matches (${got.slice(0, 16)}\u2026)`);
     }
   }
+  if (opts.aspects) {
+    const { profileForAspect: profileForAspect2, withStage: withStage2 } = await Promise.resolve().then(() => (init_types(), types_exports));
+    const { ASPECTS: ASPECTS2 } = await Promise.resolve().then(() => (init_schema(), schema_exports));
+    const va = bundle.manifest.viewport.w / bundle.manifest.viewport.h;
+    for (const a of opts.aspects.split(",").map((x) => x.trim())) {
+      if (a !== "16:9" && a !== "9:16" && a !== "1:1") {
+        log.warn(`unknown aspect "${a}" \u2014 expected 16:9, 9:16, or 1:1`);
+        continue;
+      }
+      const prof = withStage2(profileForAspect2(a, ASPECTS2[a].resolution, spec.output.fps ?? 30), true, va);
+      const fileName = `out-${a.replace(":", "x")}.mp4`;
+      await compose(bundle, spec, { outDir, theme: resolveTheme(spec), profile: prof, fileName });
+      log.ok(`${a} \u2192 ${join13(outDir, fileName)}`);
+    }
+  }
+  if (opts.gif) {
+    const gifW = typeof opts.gif === "string" ? Number(opts.gif) || 960 : 960;
+    const gifPath = await exportGif(result.videoPath, gifW);
+    log.ok(`gif \u2192 ${gifPath}`);
+  }
 });
-program.command("validate").description("preflight a spec against the LIVE app: every locator checked in one pass, all failures reported with suggestions \u2014 before a single frame is captured").argument("<spec>", "path to spec YAML").option("--headed", "show the browser").action(async (specPath, opts) => {
+program.command("validate").description("preflight a spec against the LIVE app: every locator checked in one pass, all failures reported with suggestions \u2014 before a single frame is captured").argument("<spec>", "path to spec YAML").option("--headed", "show the browser").addHelpText(
+  "after",
+  `
+Example:
+  playhead validate demo.yaml     seconds, not a render \u2014 run it after every spec edit`
+).action(async (specPath, opts) => {
   const spec = await loadSpec(specPath);
   const { validateLive: validateLive2, formatValidateResult: formatValidateResult2 } = await Promise.resolve().then(() => (init_validate(), validate_exports));
   log.info(`validating "${spec.title}" against ${spec.app.url}`);
@@ -6572,26 +7893,48 @@ program.command("jira").description("report render evidence to an EXISTING Jira
 });
 program.command("verify").description("run the verification suite against a rendered video").argument("<bundle>", "path to the capture bundle directory").argument("<video>", "path to the rendered MP4").option("-m, --manifest <path>", "compose manifest path (default: next to the video)").option("--vision", "run the Claude vision review").option("--json", "print the verdict JSON to stdout").option("--junit <path>", "write a JUnit XML report").action(async (bundleDir, videoPath, opts) => {
   const bundle = await openBundle(resolve2(bundleDir));
-  const manifestPath = opts.manifest ?? join12(resolve2(videoPath), "..", "compose-manifest.json");
+  const manifestPath = opts.manifest ?? join13(resolve2(videoPath), "..", "compose-manifest.json");
   const manifest = await loadComposeManifest(manifestPath);
   const verdict = await verify(bundle, manifest, resolve2(videoPath), {
-    outDir: join12(resolve2(videoPath), ".."),
+    outDir: join13(resolve2(videoPath), ".."),
     vision: opts.vision ?? false
   });
   await emitReports(verdict, opts);
   process.exitCode = verdict.verdict === "publishable" ? EXIT.OK : EXIT.QUALITY;
 });
-program.command("attest").description("re-verify a verdict.json: artifact hashes recomputed, signature checked (PLAYHEAD_SIGNING_KEY) \u2014 proves the verdict describes THESE files and was not edited").argument("<verdict>", "path to verdict.json (or the verify/ directory containing it)").option("--bundle <dir>", "also re-hash the capture bundle against the verdict").action(async (verdictPath, opts) => {
+program.command("attest").description("re-verify a verdict.json: video/manifest/contact-sheet/bundle hashes recomputed (frame BYTES included), signature checked (Ed25519 via keygen, or HMAC via PLAYHEAD_SIGNING_KEY)").argument("<verdict>", "path to verdict.json (or the verify/ directory containing it)").option("--bundle <dir>", "also re-hash the capture bundle \u2014 including every frame image").option("--allow-unsigned", "treat an unsigned verdict as acceptable (hash checks only)").action(async (verdictPath, opts) => {
   const { readFile: readFile7 } = await import("fs/promises");
-  const p = verdictPath.endsWith(".json") ? resolve2(verdictPath) : join12(resolve2(verdictPath), "verdict.json");
+  const p = verdictPath.endsWith(".json") ? resolve2(verdictPath) : join13(resolve2(verdictPath), "verdict.json");
+  const verifyDir = join13(p, "..");
   const verdict = JSON.parse(await readFile7(p, "utf8"));
   let ok = true;
+  if (verdict.schema !== "playhead/verdict@3") {
+    log.warn(`legacy verdict schema ${verdict.schema} \u2014 evidence text, manifest, and contact sheet are NOT covered by its signature; re-verify with a current playhead for full coverage`);
+  }
   const videoSha = await sha256File(verdict.video.path).catch(() => null);
   if (videoSha === verdict.video.sha256) log.ok(`video sha256 matches (${videoSha.slice(0, 12)}\u2026)`);
   else {
     ok = false;
     log.error(`video hash mismatch: verdict says ${verdict.video.sha256.slice(0, 12)}\u2026, file is ${videoSha ? videoSha.slice(0, 12) + "\u2026" : "missing"}`);
   }
+  if (verdict.contactSheetSha256) {
+    const sheetSha = await sha256File(join13(verifyDir, "contact-sheet.png")).catch(() => null);
+    if (sheetSha === verdict.contactSheetSha256) log.ok("contact sheet matches");
+    else if (sheetSha === null) log.warn("contact-sheet.png not found next to the verdict \u2014 hash not checkable");
+    else {
+      ok = false;
+      log.error("contact sheet hash mismatch \u2014 the sheet was replaced after verification");
+    }
+  }
+  if (verdict.manifestHash) {
+    const raw = await readFile7(join13(verifyDir, "..", "compose-manifest.json"), "utf8").catch(() => null);
+    if (raw === null) log.warn("compose-manifest.json not found \u2014 manifest hash not checkable");
+    else if (sha256Json(JSON.parse(raw)) === verdict.manifestHash) log.ok("compose manifest matches");
+    else {
+      ok = false;
+      log.error("compose manifest hash mismatch \u2014 the plan was modified after verification");
+    }
+  }
   if (opts.bundle) {
     const bundle = await openBundle(resolve2(opts.bundle));
     const events = sha256Json(bundle.events);
@@ -6602,35 +7945,129 @@ program.command("attest").description("re-verify a verdict.json: artifact hashes
       ok = false;
       log.error("bundle hash mismatch \u2014 the bundle is not the one this verdict describes");
     }
+    const withDigests = bundle.frames.filter((f) => f.h);
+    if (withDigests.length === 0) {
+      log.warn("bundle predates per-frame hashing \u2014 frame image bytes are NOT covered");
+    } else {
+      let bad = 0;
+      for (const f of withDigests) {
+        const actual = await sha256File(join13(resolve2(opts.bundle), "frames", f.f)).catch(() => null);
+        if (actual !== f.h) bad += 1;
+      }
+      if (bad === 0) log.ok(`frame bytes match (${withDigests.length} frames re-hashed)`);
+      else {
+        ok = false;
+        log.error(`${bad}/${withDigests.length} frame images do NOT match their recorded digests \u2014 footage was altered`);
+      }
+    }
   }
-  const { signVerdict: signVerdict2, signablePayload: signablePayload2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+  const { verifySignature: verifySignature2 } = await Promise.resolve().then(() => (init_report(), report_exports));
   if (!verdict.signature) {
-    log.warn("verdict is unsigned (no PLAYHEAD_SIGNING_KEY at verify time) \u2014 content integrity not attestable");
-  } else if (!process.env.PLAYHEAD_SIGNING_KEY) {
-    ok = false;
-    log.error("verdict is signed but PLAYHEAD_SIGNING_KEY is not set \u2014 cannot check the signature");
+    if (opts.allowUnsigned) {
+      log.warn("verdict is unsigned \u2014 accepted because --allow-unsigned was passed (hash checks only)");
+    } else {
+      ok = false;
+      log.error("verdict is UNSIGNED \u2014 a hand-written verdict.json is indistinguishable from a real one. Sign at verify time (playhead keygen + PLAYHEAD_SIGNING_KEY_FILE, or PLAYHEAD_SIGNING_KEY) or pass --allow-unsigned.");
+    }
   } else {
-    const { signature: _sig, ...unsigned } = verdict;
-    void signablePayload2;
-    const expect = signVerdict2(unsigned);
-    if (expect === verdict.signature) log.ok("signature valid \u2014 verdict content is untampered");
+    const res = verifySignature2(verdict);
+    if (res.valid) log.ok(res.reason);
     else {
       ok = false;
-      log.error("SIGNATURE MISMATCH \u2014 the verdict was modified after signing");
+      log.error(res.reason);
     }
   }
+  if (verdict.coverage) {
+    log.info(
+      `coverage: ${verdict.coverage.actionsVerified}/${verdict.coverage.actionsTotal} actions pixel-verified, ${verdict.coverage.outputSamplesVerified} output samples, ${verdict.coverage.checksSkipped} check(s) skipped`
+    );
+  }
   log.info(
     `provenance: playhead ${verdict.provenance.playheadVersion}, spec ${verdict.provenance.specHash.slice(0, 12)}\u2026, captured ${verdict.provenance.capturedAt}, ${verdict.provenance.host}`
   );
   process.exitCode = ok ? EXIT.OK : EXIT.QUALITY;
 });
-program.command("explore").description("inspect a live app and print a grounded catalog of addressable elements").argument("<url>", "the running app URL to explore").option("--viewport <wxh>", "viewport, e.g. 1280x720", "1280x720").option("--storage-state <file>", 'session file from "playhead login" for authed screens').option("--headed", "show the browser").action(async (url, opts) => {
+program.command("compare").description("compare two render outputs (baseline vs current): verdict drift, newly failing checks, coverage and per-step timing deltas \u2014 the regression story for CI").argument("<baseline>", "output dir of the BASELINE run (holds verify/verdict.json + compose-manifest.json)").argument("<current>", "output dir of the CURRENT run").action(async (baseDir, curDir) => {
+  const load = async (dir) => ({
+    verdict: await readJsonIfExists(join13(resolve2(dir), "verify", "verdict.json")),
+    manifest: await readJsonIfExists(join13(resolve2(dir), "compose-manifest.json"))
+  });
+  const a = await load(baseDir);
+  const b = await load(curDir);
+  if (!a.verdict || !b.verdict) {
+    log.error("both directories need verify/verdict.json (render them first)");
+    process.exitCode = EXIT.USAGE;
+    return;
+  }
+  let regressed = false;
+  log.info(`verdict: ${a.verdict.verdict} \u2192 ${b.verdict.verdict}`);
+  if (a.verdict.verdict === "publishable" && b.verdict.verdict !== "publishable") regressed = true;
+  const aFail = new Set(a.verdict.checks.filter((c) => c.status === "fail").map((c) => c.id));
+  for (const c of b.verdict.checks) {
+    if (c.status === "fail" && !aFail.has(c.id)) {
+      regressed = true;
+      log.error(`NEW failure: ${c.id} \u2014 ${c.details}`);
+    }
+    if (c.status !== "fail" && aFail.has(c.id)) log.ok(`fixed: ${c.id}`);
+  }
+  if (a.verdict.coverage && b.verdict.coverage) {
+    const ca = a.verdict.coverage;
+    const cb = b.verdict.coverage;
+    if (cb.actionsVerified < ca.actionsVerified) {
+      log.warn(`coverage dropped: ${ca.actionsVerified}/${ca.actionsTotal} \u2192 ${cb.actionsVerified}/${cb.actionsTotal} actions pixel-verified`);
+    } else {
+      log.info(`coverage: ${ca.actionsVerified}/${ca.actionsTotal} \u2192 ${cb.actionsVerified}/${cb.actionsTotal} actions pixel-verified`);
+    }
+  }
+  if (a.manifest && b.manifest) {
+    const dDur = b.manifest.durationMs - a.manifest.durationMs;
+    log.info(`duration: ${(a.manifest.durationMs / 1e3).toFixed(1)}s \u2192 ${(b.manifest.durationMs / 1e3).toFixed(1)}s (${dDur >= 0 ? "+" : ""}${(dDur / 1e3).toFixed(1)}s)`);
+    const aSteps = new Map(a.manifest.steps.map((s) => [s.stepRef, s.outEnd - s.outStart]));
+    for (const s of b.manifest.steps) {
+      const was = aSteps.get(s.stepRef);
+      if (was === void 0) {
+        log.info(`step ${s.stepRef}: new (not in baseline)`);
+        continue;
+      }
+      const now = s.outEnd - s.outStart;
+      if (now > was * 1.5 && now - was > 800) log.warn(`step ${s.stepRef} slowed: ${(was / 1e3).toFixed(1)}s \u2192 ${(now / 1e3).toFixed(1)}s`);
+    }
+    for (const ref of aSteps.keys()) {
+      if (!b.manifest.steps.some((s) => s.stepRef === ref)) log.warn(`step ${ref}: missing from current run`);
+    }
+  }
+  if (a.verdict.video.sha256 === b.verdict.video.sha256) log.info("video byte-identical to baseline");
+  process.exitCode = regressed ? EXIT.QUALITY : EXIT.OK;
+});
+program.command("keygen").description("generate an Ed25519 signing keypair: verdicts become third-party verifiable (consumers pin your key id) \u2014 stronger than the symmetric PLAYHEAD_SIGNING_KEY").option("-o, --out <file>", "private key output path (PEM)", "playhead-signing.pem").action(async (opts) => {
+  const { generateKeyPairSync } = await import("crypto");
+  const { writeFile: writeFile9 } = await import("fs/promises");
+  const { keyIdFor: keyIdFor2 } = await Promise.resolve().then(() => (init_report(), report_exports));
+  const outPath = resolve2(opts.out);
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  await writeFile9(outPath, privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 384 });
+  const spki = publicKey.export({ type: "spki", format: "der" });
+  log.ok(`private key \u2192 ${outPath}  (mode 600 \u2014 keep it out of git)`);
+  log.info(`key id: ${keyIdFor2(spki)}   (consumers pin this)`);
+  log.info(`public key (base64 SPKI): ${spki.toString("base64")}`);
+  log.info(`use it: export PLAYHEAD_SIGNING_KEY_FILE=${outPath}`);
+});
+program.command("explore").description("inspect a live app and print a grounded catalog of addressable elements").argument("<url>", "the running app URL to explore").option("--viewport <wxh>", "viewport, e.g. 1280x720", "1280x720").option("--storage-state <file>", 'session file from "playhead login" for authed screens').option("--headed", "show the browser").addHelpText(
+  "after",
+  `
+Examples:
+  playhead explore http://localhost:3000                        what can a spec address here?
+  playhead explore https://app.dev --storage-state session.json an authed screen (see: playhead login)
+
+Each line of the catalog is a locator to paste into a spec verbatim. Only the CURRENT screen is
+shown \u2014 explore again after a navigation.`
+).action(async (url, opts) => {
   const { exploreUrl: exploreUrl2, formatCatalog: formatCatalog2 } = await Promise.resolve().then(() => (init_explore(), explore_exports));
   const [w, h] = opts.viewport.split("x").map(Number);
   const snap = await exploreUrl2(url, { viewport: { w, h }, headless: !opts.headed, ...opts.storageState ? { storageStatePath: resolve2(opts.storageState) } : {} });
   console.log(formatCatalog2(snap));
 });
-program.command("author").description("agent-author a grounded, validated spec by exploring the app toward a goal").argument("<url>", "the running app URL").argument("<goal>", "natural-language description of the flow to demo").option("-o, --out <file>", "where to write the spec", "playhead.yaml").option("--title <title>", "video title (defaults to the goal)").option("--kind <kind>", "output kind", "walkthrough").option("--viewport <wxh>", "viewport", "1280x720").option("--max-steps <n>", "safety cap on authored steps", "40").option("--headed", "show the browser").action(async (url, goal, opts) => {
+program.command("author").description("agent-author a grounded, validated spec by exploring the app toward a goal").argument("<url>", "the running app URL").argument("<goal>", "natural-language description of the flow to demo").option("-o, --out <file>", "where to write the spec", "playhead.yaml").option("--title <title>", "video title (defaults to the goal)").option("--kind <kind>", "output kind", "walkthrough").option("--viewport <wxh>", "viewport", "1280x720").option("--max-steps <n>", "safety cap on authored steps", "40").option("--storage-state <file>", 'session file from "playhead login" for authed apps').option("--headed", "show the browser").action(async (url, goal, opts) => {
   const { authorSpec: authorSpec2 } = await Promise.resolve().then(() => (init_author(), author_exports));
   const [w, h] = opts.viewport.split("x").map(Number);
   await authorSpec2({
@@ -6640,19 +8077,25 @@ program.command("author").description("agent-author a grounded, validated spec b
     ...opts.title ? { title: opts.title } : {},
     viewport: { w, h },
     maxSteps: Number(opts.maxSteps),
-    headless: !opts.headed
+    headless: !opts.headed,
+    // --kind was accepted and silently ignored (round-2 audit) — now threaded through.
+    kind: opts.kind,
+    ...opts.storageState ? { storageStatePath: resolve2(opts.storageState) } : {}
   });
 });
 program.command("init").description("scaffold a starter spec").argument("[path]", "where to write it", "playhead.yaml").action(async (path) => {
   try {
-    await access(path);
+    await access2(path);
     log.error(`${path} already exists`);
     process.exitCode = 1;
     return;
   } catch {
   }
   await writeFile8(path, STARTER_SPEC);
-  log.ok(`wrote ${path} \u2014 edit it, then run: playhead render ${path}`);
+  log.ok(`wrote ${path}`);
+  console.error(`    next: playhead explore <your app url>   # real locators to paste into ${path}`);
+  console.error(`          playhead validate ${path}   # check every locator against the live app`);
+  console.error(`          playhead render ${path} -o out`);
 });
 program.command("mcp").description("run Playhead as an MCP server (stdio) so a coding agent can drive it").action(async () => {
   const { startMcpServer: startMcpServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
@@ -6660,16 +8103,18 @@ program.command("mcp").description("run Playhead as an MCP server (stdio) so a c
 });
 program.command("doctor").description("check that ffmpeg, the browser, and fonts are ready").option("--ci", "also check CI/container prerequisites (TTS, sandbox, shm)").action(async (opts) => {
   let ok = true;
-  if (opts.ci) {
+  {
     const { execFile: execFile3 } = await import("child_process");
     const { promisify: promisify3 } = await import("util");
     const which = promisify3(execFile3);
     const hasSay = await which("which", ["say"]).then(() => true).catch(() => false);
-    if (hasSay) log.ok("tts (say): macOS `say` available");
+    if (hasSay) log.ok("tts (say): macOS `say` available \u2014 output.audio: { narration: tts } speaks your steps");
     else log.info("tts (say): no `say` binary here \u2014 the `say` provider is macOS-only");
     const hasKokoro = await import("kokoro-js").then(() => true).catch(() => false);
     if (hasKokoro) log.ok("tts (kokoro): kokoro-js installed \u2014 the natural offline voice is available");
-    else log.warn("tts (kokoro): kokoro-js not installed \u2014 `provider: kokoro` needs `npm i -g kokoro-js` (~400MB, one time)");
+    else log.info("tts (kokoro): not installed (optional) \u2014 the natural voice needs `npm i -g kokoro-js` (~400MB, one time; your call)");
+  }
+  if (opts.ci) {
     if (process.platform === "linux") {
       log.info("linux: run chromium with a base image that provides fonts + sandbox deps (see Dockerfile), and give /dev/shm \u2265 512MB or pass --disable-dev-shm-usage");
     }
@@ -6693,7 +8138,7 @@ program.command("doctor").description("check that ffmpeg, the browser, and fonts
   try {
     const { chromium: chromium2 } = await import("playwright");
     const path = chromium2.executablePath();
-    await access(path);
+    await access2(path);
     log.ok(`chromium: ${path}`);
   } catch {
     ok = false;
@@ -6713,14 +8158,24 @@ program.command("doctor").description("check that ffmpeg, the browser, and fonts
 var STARTER_SPEC = `playhead: 1
 title: "My product walkthrough"
 app:
+  # Point this at your RUNNING app.
   url: http://localhost:3000
   viewport: 1280x720
 output:
   kind: walkthrough
   pacing: normal
+  # Optional voice-over \u2014 most demos don't need one, so it's off by default. Uncomment to
+  # speak each step's narration (or caption) line. Providers:
+  #   say    \u2014 macOS built-in voice, zero setup (robotic)
+  #   kokoro \u2014 natural neural voice, offline, cross-platform; YOUR call whether it's worth
+  #            the one-time "npm i -g kokoro-js" (~400MB + ~90MB model on first use)
+  # audio: { narration: tts, provider: say }
 scenes:
   - id: first-flow
     title: "Do the thing"
+    # These steps are PLACEHOLDERS \u2014 they name elements your app almost certainly doesn't have.
+    # Get real locators from your live app:      playhead explore <url>
+    # ...paste them here, then check them with:  playhead validate <this file>
     steps:
       - click: 'role=button[name="Get started"]'
       - type: { target: 'label=Name', text: "Ada Lovelace" }