playhead-cli 0.1.3 → 0.2.0

package/dist/mcp/bin.js

@@ -76,8 +76,48 @@ 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
 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;
@@ -114,12 +154,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 = `
 (() => {
@@ -162,11 +221,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) {}
@@ -175,7 +247,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); }
       }
@@ -325,9 +397,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",
@@ -366,7 +452,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}`);
@@ -383,6 +472,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();
@@ -500,6 +595,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 });
@@ -563,6 +659,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;
@@ -654,12 +752,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);
@@ -668,8 +823,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
@@ -705,6 +858,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";
@@ -720,6 +889,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)) {
@@ -761,6 +942,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;
@@ -803,7 +985,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((resolve2) => {
+                  setTimeout(resolve2, 400);
+                })
+              ),
+              1e3
+            ).catch(() => {
+            });
+          }
         });
         await this.nextFrame();
       }
@@ -860,10 +1055,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) {
@@ -874,7 +1115,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(() => {
@@ -884,7 +1126,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 };
@@ -893,7 +1135,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
@@ -902,7 +1146,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 {
@@ -914,6 +1160,7 @@ var init_playwright_driver = __esm({
             } catch {
             }
           }
+          return false;
         }
       }
       async readScroll() {
@@ -927,6 +1174,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;
@@ -935,19 +1187,45 @@ 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");
       }
     };
   }
 });
 
 // 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());
@@ -1088,7 +1366,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}"`;
 }
@@ -1121,7 +1399,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;
@@ -1327,7 +1610,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";
@@ -1344,7 +1627,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:
@@ -1356,7 +1639,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,
@@ -1373,9 +1659,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,
@@ -1390,13 +1682,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(),
@@ -1411,12 +1714,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) {
@@ -1519,7 +1825,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),
@@ -1538,13 +1847,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 } },
@@ -1554,108 +1874,442 @@ var init_schema = __esm({
   }
 });
 
-// src/shared/exit.ts
-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/authoring/validate.ts
-var validate_exports = {};
-__export(validate_exports, {
-  formatValidateResult: () => formatValidateResult,
-  validateLive: () => validateLive
+// src/spec/parse.ts
+var parse_exports = {};
+__export(parse_exports, {
+  SpecError: () => SpecError,
+  loadSpec: () => loadSpec,
+  parseSpec: () => parseSpec
 });
-async function validateLive(spec, opts) {
-  const driver = opts?.driver ?? new PlaywrightDriver();
-  const owned = !opts?.driver;
-  const issues = [];
-  let checked = 0;
-  let stateDiverged = false;
-  if (owned) {
-    await driver.launch({
-      viewport: resolveViewport(spec),
-      dpr: 1,
-      headless: opts?.headless ?? true,
-      ...spec.app.storageState ? { storageStatePath: spec.app.storageState } : {}
-    });
+import { readFile } from "fs/promises";
+import { dirname as dirname2, resolve as resolvePath } from "path";
+import { parseDocument, LineCounter } from "yaml";
+function suggest(key) {
+  let best = null;
+  let bestD = 3;
+  for (const k of KNOWN_KEYS) {
+    const d = editDistance(key.toLowerCase(), k.toLowerCase());
+    if (d > 0 && d < bestD) {
+      bestD = d;
+      best = k;
+    }
   }
-  try {
-    await driver.goto(spec.app.url);
-    await driver.settle({ idleMs: 300, capMs: 5e3 });
-    for (const a of flattenSteps(spec)) {
-      const stepRef = `${a.sceneId}/${a.stepIndex}`;
-      const step = a.step;
-      const push = async (locator, severity, message) => {
-        issues.push({
-          stepRef,
-          step: step.action,
-          locator,
-          severity,
-          message: stateDiverged ? `${message} (after an earlier failure \u2014 state may have diverged)` : message,
-          suggestions: severity === "error" ? await suggestFor(driver, locator) : []
-        });
-      };
-      const locators = [];
-      if ("target" in step && step.target) locators.push({ value: step.target, 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" });
-      }
-      for (const l of locators) {
-        checked += 1;
-        const count = await driver.countMatches(parseLocator(l.value)).catch(() => 0);
-        if (count === 0 && l.kind === "target") {
-          await push(l.value, "error", "no matching element on the current screen");
-        } else if (count === 0 && l.kind !== "target") {
-          await push(l.value, "warn", `${l.kind} locator matches nothing yet (may appear after the action)`);
-        } else if (count > 1 && !l.value.includes(">> nth=")) {
-          await push(l.value, "warn", `ambiguous: ${count} matches \u2014 add '>> nth=N' to pick one`);
-        }
-      }
-      try {
-        await fastExecute(driver, step);
-      } catch (e) {
-        if ("target" in step && step.target) {
-          const already = issues.some((i) => i.stepRef === stepRef && i.severity === "error");
-          if (!already) await push(step.target ?? "(none)", "error", `step failed to execute: ${firstLine2(e.message)}`);
-        }
-        stateDiverged = true;
-      }
-      const focus = step.focus;
-      if (focus && focus !== "target" && focus !== "wide") {
-        const loc = parseLocator(focus);
-        let n = 0;
-        for (let i = 0; i < 8 && n === 0; i++) {
-          n = await driver.countMatches(loc).catch(() => 0);
-          if (n === 0) await sleep3(250);
-        }
-        if (n === 0) await push(focus, "error", "focus locator never appeared after the action");
-        if (n > 0) {
-          const idx = issues.findIndex((i) => i.stepRef === stepRef && i.locator === focus && i.severity === "warn");
-          if (idx >= 0) issues.splice(idx, 1);
-        }
-      }
+  return best;
+}
+function parseSpec(yamlText, sourcePath = "<inline>") {
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(yamlText, { lineCounter, keepSourceTokens: true });
+  if (doc.errors.length > 0) {
+    const first = doc.errors[0];
+    throw new SpecError(`${sourcePath}: not valid YAML \u2014 ${first.message}`);
+  }
+  const raw = doc.toJS();
+  if (raw && typeof raw === "object" && "extends" in raw) {
+    throw new SpecError(`${sourcePath}: "extends" needs a file on disk \u2014 load the spec with loadSpec/the CLI, not inline text`);
+  }
+  return validateResolved(interpolate(raw, sourcePath), sourcePath, doc, lineCounter);
+}
+async function loadSpec(path) {
+  const merged = await loadRaw(resolvePath(path), 0);
+  const text = await readFile(resolvePath(path), "utf8");
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter });
+  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`);
+  const text = await readFile(path, "utf8");
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) throw new SpecError(`${path}: not valid YAML \u2014 ${doc.errors[0].message}`);
+  const raw = doc.toJS() ?? {};
+  const base = raw.extends;
+  delete raw.extends;
+  if (base === void 0) return raw;
+  if (typeof base !== "string") throw new SpecError(`${path}: "extends" must be a path string`);
+  const baseObj = await loadRaw(resolvePath(dirname2(path), base), depth + 1);
+  return mergeSpecs(baseObj, raw);
+}
+function mergeSpecs(base, child) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(child)) {
+    const b = out[k];
+    if (Array.isArray(b) && Array.isArray(v) && (k === "masking" || k === "scenes")) {
+      out[k] = [...b, ...v];
+    } else if (isPlainObject(b) && isPlainObject(v)) {
+      out[k] = mergeSpecs(b, v);
+    } else {
+      out[k] = v;
     }
-  } finally {
-    if (owned) await driver.close();
   }
-  return { ok: !issues.some((i) => i.severity === "error"), checked, issues };
+  return out;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function interpolate(raw, sourcePath) {
+  if (!isPlainObject(raw)) return raw;
+  const varsIn = isPlainObject(raw.vars) ? raw.vars : {};
+  const vars = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(varsIn)) {
+    vars.set(name, resolveEnv(String(value), sourcePath));
+  }
+  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) => {
+    const withEnv = resolveEnv(s, sourcePath);
+    return withEnv.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_, name) => {
+      const v = vars.get(name);
+      if (v === void 0) {
+        const near = suggest(name) ?? [...vars.keys()].find((k) => editDistance(k, name) <= 2);
+        throw new SpecError(
+          `${sourcePath}: unknown variable {{${name}}}${near ? ` \u2014 did you mean {{${near}}}?` : ""} (declared vars: ${[...vars.keys()].join(", ") || "none"})`
+        );
+      }
+      return v;
+    });
+  };
+  const walk = (v) => {
+    if (typeof v === "string") return seen(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, walk(val)]));
+    return v;
+  };
+  return walk(doc);
+}
+function resolveEnv(s, sourcePath) {
+  return s.replace(/\$\{env\.([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, dflt) => {
+    const v = process.env[name];
+    if (v !== void 0) return v;
+    if (dflt !== void 0) return dflt;
+    throw new SpecError(`${sourcePath}: environment variable ${name} is not set and has no default (use \${env.${name}:-fallback})`);
+  });
+}
+function validateResolved(resolved, sourcePath, doc, lineCounter, 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, offsets));
+    throw new SpecError(`${sourcePath}: invalid spec
+  - ${issues.join("\n  - ")}`, issues);
+  }
+  return result.data;
+}
+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, offsets);
+  const at = pos ? `${sourcePath}:${pos.line}:${pos.col} ` : "";
+  if (iss.code === "unrecognized_keys") {
+    const keys = iss.keys;
+    const hints = keys.map((k) => ({ k, near: suggest(k) })).map((h) => h.near ? `"${h.k}" (did you mean "${h.near}"?)` : `"${h.k}"`).join(", ");
+    return `${at}${where}: unknown key${keys.length > 1 ? "s" : ""} ${hints}`;
+  }
+  return `${at}${where}: ${iss.message}`;
+}
+function positionOf(path, doc, lineCounter, 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);
+      if (node?.range) {
+        const pos = lineCounter.linePos(node.range[0]);
+        return { line: pos.line, col: pos.col };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function humanPath(path) {
+  return path.map((seg, i) => typeof seg === "number" ? `[${seg}]` : i === 0 ? String(seg) : `.${String(seg)}`).join("");
+}
+var SpecError, KNOWN_KEYS;
+var init_parse = __esm({
+  "src/spec/parse.ts"() {
+    "use strict";
+    init_schema();
+    SpecError = class extends Error {
+      constructor(message, issues = []) {
+        super(message);
+        this.issues = issues;
+      }
+      issues;
+    };
+    KNOWN_KEYS = [
+      "playhead",
+      "title",
+      "subtitle",
+      "app",
+      "output",
+      "theme",
+      "masking",
+      "scenes",
+      "vars",
+      "extends",
+      "setup",
+      "url",
+      "viewport",
+      "storageState",
+      "compareUrl",
+      "assertLoggedIn",
+      "environment",
+      "network",
+      "dialogs",
+      "settle",
+      "timezone",
+      "locale",
+      "colorScheme",
+      "fixedTime",
+      "reducedMotion",
+      "block",
+      "stub",
+      "har",
+      "status",
+      "body",
+      "contentType",
+      "idleMs",
+      "capMs",
+      "kind",
+      "aspect",
+      "resolution",
+      "fps",
+      "pacing",
+      "dwellScale",
+      "audio",
+      "endCard",
+      "narration",
+      "provider",
+      "voice",
+      "rate",
+      "sfx",
+      "music",
+      "file",
+      "gainDb",
+      "accent",
+      "captions",
+      "target",
+      "style",
+      "id",
+      "steps",
+      "shot",
+      "timeout",
+      "goto",
+      "click",
+      "dblclick",
+      "hover",
+      "type",
+      "press",
+      "select",
+      "scroll",
+      "expect",
+      "wait",
+      "caption",
+      "focus",
+      "mask",
+      "text",
+      "value",
+      "keys",
+      "ms",
+      "by",
+      "visible",
+      "hidden",
+      "count",
+      "for",
+      "state",
+      "x",
+      "y",
+      "optional",
+      "clear",
+      "to",
+      "disabled",
+      "checked",
+      "rightclick",
+      "upload",
+      "drag"
+    ];
+  }
+});
+
+// src/authoring/validate.ts
+var validate_exports = {};
+__export(validate_exports, {
+  formatValidateResult: () => formatValidateResult,
+  validateLive: () => validateLive
+});
+async function validateLive(spec, opts) {
+  const driver = opts?.driver ?? new PlaywrightDriver();
+  const owned = !opts?.driver;
+  const issues = [];
+  let checked = 0;
+  let stateDiverged = false;
+  if (owned) {
+    await driver.launch({
+      viewport: resolveViewport(spec),
+      dpr: 1,
+      headless: opts?.headless ?? true,
+      ...spec.app.storageState ? { storageStatePath: spec.app.storageState } : {},
+      ...spec.app.environment ? { environment: spec.app.environment } : {},
+      ...spec.app.network ? { network: spec.app.network } : {},
+      ...spec.app.dialogs ? { dialogs: spec.app.dialogs } : {}
+    });
+  }
+  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(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) => {
+        issues.push({
+          stepRef,
+          step: step.action,
+          locator,
+          severity,
+          message: stateDiverged ? `${message} (after an earlier failure \u2014 state may have diverged)` : message,
+          suggestions: severity === "error" ? await suggestFor(driver, locator) : []
+        });
+      };
+      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" });
+      }
+      for (const l of locators) {
+        checked += 1;
+        const count = await driver.countMatches(parseLocator(l.value)).catch(() => 0);
+        if (count === 0 && l.kind === "target") {
+          await push(l.value, "error", "no matching element on the current screen");
+        } else if (count === 0 && l.kind !== "target") {
+          await push(l.value, "warn", `${l.kind} locator matches nothing yet (may appear after the action)`);
+        } else if (count > 1 && !l.value.includes(">> nth=")) {
+          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) {
+        if ("target" in step && step.target) {
+          const already = issues.some((i) => i.stepRef === stepRef && i.severity === "error");
+          if (!already) await push(step.target ?? "(none)", "error", `step failed to execute: ${firstLine2(e.message)}`);
+        }
+        stateDiverged = true;
+      }
+      const focus = step.focus;
+      if (focus && focus !== "target" && focus !== "wide") {
+        const loc = parseLocator(focus);
+        let n = 0;
+        for (let i = 0; i < 8 && n === 0; i++) {
+          n = await driver.countMatches(loc).catch(() => 0);
+          if (n === 0) await sleep3(250);
+        }
+        if (n === 0) await push(focus, "error", "focus locator never appeared after the action");
+        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 {
+          }
+        }
+      }
+    }
+  } finally {
+    if (owned) await driver.close();
+  }
+  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;
@@ -1691,13 +2345,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
       );
@@ -1745,6 +2414,7 @@ function formatValidateResult(res) {
   );
   return lines.join("\n");
 }
+var FRAMED_ACTIONS;
 var init_validate = __esm({
   "src/authoring/validate.ts"() {
     "use strict";
@@ -1754,6 +2424,7 @@ var init_validate = __esm({
     init_schema();
     init_explore();
     init_geometry();
+    FRAMED_ACTIONS = /* @__PURE__ */ new Set(["click", "dblclick", "hover", "type", "select", "expect"]);
   }
 });
 
@@ -1769,8 +2440,8 @@ __export(jira_exports, {
   reportToJira: () => reportToJira
 });
 import { readFile as readFile5, stat } from "fs/promises";
-import { join as join9, basename } from "path";
-import { existsSync as existsSync4 } from "fs";
+import { join as join10, basename } from "path";
+import { existsSync as existsSync5 } from "fs";
 function jiraConfigFromEnv() {
   const baseUrl = process.env.JIRA_BASE_URL;
   const email = process.env.JIRA_EMAIL;
@@ -1834,17 +2505,17 @@ async function addComment(cfg, issueKey, adfBody) {
 }
 async function collectEvidence(outDir) {
   const candidates = [
-    join9(outDir, "out.mp4"),
-    join9(outDir, "failure.mp4"),
-    join9(outDir, "verify", "verdict.json"),
-    join9(outDir, "verify", "contact-sheet.png"),
-    join9(outDir, "junit.xml"),
-    join9(outDir, "capture", "failure.json"),
-    join9(outDir, "capture", "console.json")
+    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")
   ];
   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)`);
@@ -1856,11 +2527,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 = join9(outDir, "verify", "verdict.json");
-  if (existsSync4(verdictPath)) verdict = JSON.parse(await readFile5(verdictPath, "utf8"));
+  const verdictPath = join10(outDir, "verify", "verdict.json");
+  if (existsSync5(verdictPath)) verdict = JSON.parse(await readFile5(verdictPath, "utf8"));
   let failure;
-  const failurePath = join9(outDir, "capture", "failure.json");
-  if (existsSync4(failurePath)) failure = JSON.parse(await readFile5(failurePath, "utf8"));
+  const failurePath = join10(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 };
 }
@@ -1929,12 +2600,33 @@ import { mkdtemp, writeFile as writeFile7, mkdir as mkdir5, readFile as readFile
 
 // src/shared/version.ts
 import { createRequire } from "module";
-var PLAYHEAD_VERSION = createRequire(import.meta.url)("../../package.json").version;
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync, readFileSync } from "fs";
+function resolveOwnPackageJson() {
+  let dir = dirname(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 = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  try {
+    return createRequire(import.meta.url)("../../package.json");
+  } catch {
+    return { version: "0.0.0" };
+  }
+}
+var PLAYHEAD_VERSION = resolveOwnPackageJson().version;
 
 // src/mcp/server.ts
 init_explore();
 import { tmpdir } from "os";
-import { join as join10, resolve, isAbsolute } from "path";
+import { join as join11, 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";
@@ -2037,25 +2729,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(SETTLE);
+    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(SETTLE);
         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");
@@ -2063,11 +2776,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 writeFile(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 writeFile(opts.outPath, yaml);
+      throw new Error(`authored spec failed validation \u2014 written to ${opts.outPath} for inspection:
+${e.message}`);
+    }
+    await writeFile(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 {
@@ -2084,9 +2806,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}`,
@@ -2097,6 +2826,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");
@@ -2163,259 +2893,31 @@ function describe(s) {
       return `type "${s.mask ? "\u2022\u2022\u2022\u2022" : s.text}" into ${s.locator}`;
     case "select":
       return `select "${s.value}" in ${s.locator}`;
-    case "press":
-      return `press ${s.keys}`;
-    case "expect":
-      return `expect ${s.locator}`;
-    default:
-      return `${s.action} ${s.locator}`;
-  }
-}
-function capitalize(s) {
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}
-
-// src/spec/parse.ts
-init_schema();
-import { readFile } from "fs/promises";
-import { dirname, resolve as resolvePath } from "path";
-import { parseDocument, LineCounter } from "yaml";
-var SpecError = class extends Error {
-  constructor(message, issues = []) {
-    super(message);
-    this.issues = issues;
-  }
-  issues;
-};
-var KNOWN_KEYS = [
-  "playhead",
-  "title",
-  "subtitle",
-  "app",
-  "output",
-  "theme",
-  "masking",
-  "scenes",
-  "vars",
-  "extends",
-  "url",
-  "viewport",
-  "storageState",
-  "compareUrl",
-  "assertLoggedIn",
-  "environment",
-  "network",
-  "dialogs",
-  "settle",
-  "timezone",
-  "locale",
-  "colorScheme",
-  "fixedTime",
-  "reducedMotion",
-  "block",
-  "stub",
-  "har",
-  "status",
-  "body",
-  "contentType",
-  "idleMs",
-  "capMs",
-  "kind",
-  "aspect",
-  "resolution",
-  "fps",
-  "pacing",
-  "dwellScale",
-  "audio",
-  "endCard",
-  "narration",
-  "provider",
-  "voice",
-  "rate",
-  "sfx",
-  "music",
-  "file",
-  "gainDb",
-  "accent",
-  "captions",
-  "target",
-  "style",
-  "id",
-  "steps",
-  "shot",
-  "timeout",
-  "goto",
-  "click",
-  "dblclick",
-  "hover",
-  "type",
-  "press",
-  "select",
-  "scroll",
-  "expect",
-  "wait",
-  "caption",
-  "focus",
-  "mask",
-  "text",
-  "value",
-  "keys",
-  "ms",
-  "by",
-  "visible",
-  "hidden",
-  "count",
-  "for",
-  "state",
-  "x",
-  "y"
-];
-function suggest(key) {
-  let best = null;
-  let bestD = 3;
-  for (const k of KNOWN_KEYS) {
-    const d = editDistance(key.toLowerCase(), k.toLowerCase());
-    if (d > 0 && d < bestD) {
-      bestD = d;
-      best = k;
-    }
-  }
-  return best;
-}
-function parseSpec(yamlText, sourcePath = "<inline>") {
-  const lineCounter = new LineCounter();
-  const doc = parseDocument(yamlText, { lineCounter, keepSourceTokens: true });
-  if (doc.errors.length > 0) {
-    const first = doc.errors[0];
-    throw new SpecError(`${sourcePath}: not valid YAML \u2014 ${first.message}`);
-  }
-  const raw = doc.toJS();
-  if (raw && typeof raw === "object" && "extends" in raw) {
-    throw new SpecError(`${sourcePath}: "extends" needs a file on disk \u2014 load the spec with loadSpec/the CLI, not inline text`);
-  }
-  return validateResolved(interpolate(raw, sourcePath), sourcePath, doc, lineCounter);
-}
-async function loadSpec(path) {
-  const merged = await loadRaw(resolvePath(path), 0);
-  const text = await readFile(resolvePath(path), "utf8");
-  const lineCounter = new LineCounter();
-  const doc = parseDocument(text, { lineCounter });
-  return validateResolved(interpolate(merged, path), path, doc, lineCounter);
-}
-async function loadRaw(path, depth) {
-  if (depth > 4) throw new SpecError(`${path}: extends chain deeper than 4 \u2014 check for a cycle`);
-  const text = await readFile(path, "utf8");
-  const doc = parseDocument(text);
-  if (doc.errors.length > 0) throw new SpecError(`${path}: not valid YAML \u2014 ${doc.errors[0].message}`);
-  const raw = doc.toJS() ?? {};
-  const base = raw.extends;
-  delete raw.extends;
-  if (base === void 0) return raw;
-  if (typeof base !== "string") throw new SpecError(`${path}: "extends" must be a path string`);
-  const baseObj = await loadRaw(resolvePath(dirname(path), base), depth + 1);
-  return mergeSpecs(baseObj, raw);
-}
-function mergeSpecs(base, child) {
-  const out = { ...base };
-  for (const [k, v] of Object.entries(child)) {
-    const b = out[k];
-    if (Array.isArray(b) && Array.isArray(v) && (k === "masking" || k === "scenes")) {
-      out[k] = [...b, ...v];
-    } else if (isPlainObject(b) && isPlainObject(v)) {
-      out[k] = mergeSpecs(b, v);
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-function isPlainObject(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function interpolate(raw, sourcePath) {
-  if (!isPlainObject(raw)) return raw;
-  const varsIn = isPlainObject(raw.vars) ? raw.vars : {};
-  const vars = /* @__PURE__ */ new Map();
-  for (const [name, value] of Object.entries(varsIn)) {
-    vars.set(name, resolveEnv(String(value), sourcePath));
-  }
-  const doc = { ...raw };
-  delete doc.vars;
-  const seen = (s) => {
-    const withEnv = resolveEnv(s, sourcePath);
-    return withEnv.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_, name) => {
-      const v = vars.get(name);
-      if (v === void 0) {
-        const near = suggest(name) ?? [...vars.keys()].find((k) => editDistance(k, name) <= 2);
-        throw new SpecError(
-          `${sourcePath}: unknown variable {{${name}}}${near ? ` \u2014 did you mean {{${near}}}?` : ""} (declared vars: ${[...vars.keys()].join(", ") || "none"})`
-        );
-      }
-      return v;
-    });
-  };
-  const walk = (v) => {
-    if (typeof v === "string") return seen(v);
-    if (Array.isArray(v)) return v.map(walk);
-    if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, walk(val)]));
-    return v;
-  };
-  return walk(doc);
-}
-function resolveEnv(s, sourcePath) {
-  return s.replace(/\$\{env\.([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, dflt) => {
-    const v = process.env[name];
-    if (v !== void 0) return v;
-    if (dflt !== void 0) return dflt;
-    throw new SpecError(`${sourcePath}: environment variable ${name} is not set and has no default (use \${env.${name}:-fallback})`);
-  });
-}
-function validateResolved(resolved, sourcePath, doc, lineCounter) {
-  const result = specSchema.safeParse(resolved);
-  if (!result.success) {
-    const issues = result.error.issues.map((iss) => formatIssue(iss, sourcePath, doc, lineCounter));
-    throw new SpecError(`${sourcePath}: invalid spec
-  - ${issues.join("\n  - ")}`, issues);
-  }
-  return result.data;
-}
-function formatIssue(iss, sourcePath, doc, lineCounter) {
-  const where = iss.path.length ? humanPath(iss.path) : "spec";
-  const pos = positionOf(iss.path, doc, lineCounter);
-  const at = pos ? `${sourcePath}:${pos.line}:${pos.col} ` : "";
-  if (iss.code === "unrecognized_keys") {
-    const keys = iss.keys;
-    const hints = keys.map((k) => ({ k, near: suggest(k) })).map((h) => h.near ? `"${h.k}" (did you mean "${h.near}"?)` : `"${h.k}"`).join(", ");
-    return `${at}${where}: unknown key${keys.length > 1 ? "s" : ""} ${hints}`;
-  }
-  return `${at}${where}: ${iss.message}`;
-}
-function positionOf(path, doc, lineCounter) {
-  for (let depth = path.length; depth > 0; depth--) {
-    try {
-      const node = doc.getIn(path.slice(0, depth), true);
-      if (node?.range) {
-        const pos = lineCounter.linePos(node.range[0]);
-        return { line: pos.line, col: pos.col };
-      }
-    } catch {
-    }
+    case "press":
+      return `press ${s.keys}`;
+    case "expect":
+      return `expect ${s.locator}`;
+    default:
+      return `${s.action} ${s.locator}`;
   }
-  return null;
 }
-function humanPath(path) {
-  return path.map((seg, i) => typeof seg === "number" ? `[${seg}]` : i === 0 ? String(seg) : `.${String(seg)}`).join("");
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
+// src/mcp/server.ts
+init_parse();
+
 // src/capture/executor.ts
 init_schema();
 init_locators();
 init_playwright_driver();
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 
 // src/bundle/writer.ts
 import { mkdir, writeFile as writeFile2 } from "fs/promises";
-import { join } from "path";
+import { createHash as createHash2 } from "crypto";
+import { join as join2 } from "path";
 import sharp from "sharp";
 
 // src/bundle/hash.ts
@@ -2432,11 +2934,12 @@ function sha256File(path) {
 }
 
 // src/bundle/writer.ts
+init_log();
 var BundleWriter = class {
   constructor(dir, captureFormat) {
     this.dir = dir;
     this.captureFormat = captureFormat;
-    this.ready = mkdir(join(dir, "frames"), { recursive: true }).then(() => {
+    this.ready = mkdir(join2(dir, "frames"), { recursive: true }).then(() => {
     });
   }
   dir;
@@ -2445,14 +2948,22 @@ var BundleWriter = class {
   pendingWrites = [];
   maskSamples = [];
   counter = 0;
+  failedFrames = /* @__PURE__ */ new Set();
+  writeError;
   ready;
-  /** Queue a frame write. `t` is capture-relative ms. */
+  /** Queue a frame write. `t` is capture-relative ms. Each frame's BYTES are hashed at write
+   *  time — the index entry carries the digest, so the framesIndex hash transitively covers
+   *  every pixel in the bundle. (Round-2 audit: filename+timestamp hashing left frame images
+   *  freely swappable under a passing attest.) */
   addFrame(data, t) {
     this.counter += 1;
     const name = `${String(this.counter).padStart(6, "0")}.${this.captureFormat === "jpeg" ? "jpg" : "png"}`;
-    this.frames.push({ f: name, t: round1(t) });
+    this.frames.push({ f: name, t: round1(t), h: createHash2("sha256").update(data).digest("hex") });
     this.pendingWrites.push(
-      this.ready.then(() => writeFile2(join(this.dir, "frames", name), data))
+      this.ready.then(() => writeFile2(join2(this.dir, "frames", name), data)).catch((e) => {
+        this.failedFrames.add(name);
+        this.writeError ??= e;
+      })
     );
   }
   addMaskSample(sample) {
@@ -2464,21 +2975,28 @@ var BundleWriter = class {
   async finish(meta) {
     await this.ready;
     await Promise.all(this.pendingWrites);
+    if (this.failedFrames.size > 0) {
+      this.frames = this.frames.filter((f) => !this.failedFrames.has(f.f));
+      log.warn(`${this.failedFrames.size} frame write(s) failed (${this.writeError?.message?.split("\n")[0]}) \u2014 those frames dropped from the index`);
+    }
     this.frames.sort((a, b) => a.t - b.t);
     let frameW = meta.viewport.w * meta.dpr;
     let frameH = meta.viewport.h * meta.dpr;
     const first = this.frames[0];
     if (first) {
-      const info = await sharp(join(this.dir, "frames", first.f)).metadata();
+      const info = await sharp(join2(this.dir, "frames", first.f)).metadata();
       if (info.width && info.height) {
         frameW = info.width;
         frameH = info.height;
       }
     }
+    meta.events.meta.frameW = frameW;
+    meta.events.meta.frameH = frameH;
+    const spec = redactMaskedText(meta.spec);
     const manifest = {
       schema: "playhead/bundle@1",
       playheadVersion: PLAYHEAD_VERSION,
-      specHash: sha256Json(meta.spec),
+      specHash: sha256Json(spec),
       appUrl: meta.appUrl,
       viewport: meta.viewport,
       dpr: meta.dpr,
@@ -2497,15 +3015,24 @@ var BundleWriter = class {
       ...meta.failure ? { failure: meta.failure } : {}
     };
     await Promise.all([
-      writeFile2(join(this.dir, "frames", "index.json"), JSON.stringify(this.frames)),
-      writeFile2(join(this.dir, "events.json"), JSON.stringify(meta.events, null, 2)),
-      writeFile2(join(this.dir, "masks.json"), JSON.stringify(this.maskSamples, null, 2)),
-      writeFile2(join(this.dir, "spec.resolved.json"), JSON.stringify(meta.spec, null, 2)),
-      writeFile2(join(this.dir, "manifest.json"), JSON.stringify(manifest, null, 2))
+      writeFile2(join2(this.dir, "frames", "index.json"), JSON.stringify(this.frames)),
+      writeFile2(join2(this.dir, "events.json"), JSON.stringify(meta.events, null, 2)),
+      writeFile2(join2(this.dir, "masks.json"), JSON.stringify(this.maskSamples, null, 2)),
+      writeFile2(join2(this.dir, "spec.resolved.json"), JSON.stringify(spec, null, 2)),
+      writeFile2(join2(this.dir, "manifest.json"), JSON.stringify(manifest, null, 2))
     ]);
     return manifest;
   }
 };
+function redactMaskedText(spec) {
+  const copy = JSON.parse(JSON.stringify(spec));
+  for (const scene of copy.scenes) {
+    for (const step of scene.steps) {
+      if (step.action === "type" && step.mask && step.text) step.text = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+    }
+  }
+  return copy;
+}
 function round1(n) {
   return Math.round(n * 10) / 10;
 }
@@ -2521,7 +3048,7 @@ var TYPE_DELAY_MS = 45;
 var STEP_BUDGET_MS = 45e3;
 var CAPTURE_DEADLINE_MS = 10 * 6e4;
 async function capture(spec, opts) {
-  const bundleDir = join2(opts.outDir, "capture");
+  const bundleDir = join3(opts.outDir, "capture");
   const driver = opts.driver ?? new PlaywrightDriver();
   const dpr = 2;
   const format = opts.captureFormat ?? "jpeg";
@@ -2555,18 +3082,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);
@@ -2578,7 +3107,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) {
@@ -2591,7 +3128,10 @@ async function capture(spec, opts) {
       }
       currentStepRef = "";
       steps = steps.slice(idx);
+    }
+    if (preRoll) {
       await driver.settle(settleCfg);
+      recordEvents = true;
       await startFilming();
       await driver.captureNow();
     }
@@ -2601,11 +3141,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;
@@ -2643,10 +3192,10 @@ async function capture(spec, opts) {
       const url = driver.currentUrl();
       const { writeFile: writeFile8 } = await import("fs/promises");
       await writeFile8(
-        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 writeFile8(join2(bundleDir, "failure-aria.txt"), aria);
+      if (aria) await writeFile8(join3(bundleDir, "failure-aria.txt"), aria);
     } catch {
     }
     throw new FlowError(
@@ -2661,7 +3210,7 @@ async function capture(spec, opts) {
       if (consoleLog.length > 0) {
         const { writeFile: writeFile8 } = await import("fs/promises");
         await writeFile8(
-          join2(bundleDir, "console.json"),
+          join3(bundleDir, "console.json"),
           JSON.stringify(consoleLog.map((c) => ({ ...c, t: rel(c.t) })), null, 2)
         );
       }
@@ -2713,13 +3262,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));
@@ -2737,8 +3288,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":
@@ -2824,6 +3390,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);
       }
@@ -2853,6 +3422,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) {
@@ -2869,14 +3474,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;
@@ -2902,6 +3515,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) {
@@ -2948,13 +3562,13 @@ function round12(n) {
 
 // src/bundle/reader.ts
 import { readFile as readFile2 } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 async function openBundle(dir) {
   const [manifestRaw, eventsRaw, framesRaw, masksRaw] = await Promise.all([
-    readFile2(join3(dir, "manifest.json"), "utf8"),
-    readFile2(join3(dir, "events.json"), "utf8"),
-    readFile2(join3(dir, "frames", "index.json"), "utf8"),
-    readFile2(join3(dir, "masks.json"), "utf8").catch(() => "[]")
+    readFile2(join4(dir, "manifest.json"), "utf8"),
+    readFile2(join4(dir, "events.json"), "utf8"),
+    readFile2(join4(dir, "frames", "index.json"), "utf8"),
+    readFile2(join4(dir, "masks.json"), "utf8").catch(() => "[]")
   ]);
   const manifest = JSON.parse(manifestRaw);
   if (manifest.schema !== "playhead/bundle@1") {
@@ -2979,17 +3593,17 @@ function frameIndexForTime(frames, tMs) {
   return lo;
 }
 function framePath(bundle, index) {
-  return join3(bundle.dir, "frames", bundle.frames[index].f);
+  return join4(bundle.dir, "frames", bundle.frames[index].f);
 }
 
 // src/compose/index.ts
 init_schema();
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { writeFile as writeFile4 } from "fs/promises";
 
 // src/theme/index.ts
-import { existsSync } from "fs";
-import { join as join4, dirname as dirname2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { join as join5, dirname as dirname3 } from "path";
 import { createRequire as createRequire2 } from "module";
 import { GlobalFonts } from "@napi-rs/canvas";
 var DEFAULT_THEME = {
@@ -3023,7 +3637,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");
   }
@@ -3034,8 +3648,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);
   }
 }
 
@@ -3043,17 +3657,24 @@ function registerFonts() {
 function stageContent(profile) {
   return profile.stage?.content ?? { x: 0, y: 0, w: profile.width, h: profile.height };
 }
-function withStage(profile, chrome) {
+function withStage(profile, chrome, viewportAspect) {
   const { width, height } = profile;
+  const va = viewportAspect ?? width / height;
+  const ui = Math.min(width, height) / 1080;
   const marginY = Math.round(height * 0.055);
-  const chromeH = chrome ? Math.round(44 * (Math.min(width, height) / 1080)) : 0;
-  const contentH = height - 2 * marginY - chromeH;
-  const contentW = Math.round(contentH * (width / height));
+  const marginX = Math.round(width * 0.05);
+  const chromeH = chrome ? Math.round(44 * ui) : 0;
+  let contentH = height - 2 * marginY - chromeH;
+  let contentW = Math.round(contentH * va);
+  if (contentW > width - 2 * marginX) {
+    contentW = width - 2 * marginX;
+    contentH = Math.round(contentW / va);
+  }
   const x = Math.round((width - contentW) / 2);
-  const y = marginY + chromeH;
+  const y = Math.round((height - contentH - chromeH) / 2) + chromeH;
   return {
     ...profile,
-    stage: { content: { x, y, w: contentW, h: contentH }, chromeH, radius: Math.round(14 * (Math.min(width, height) / 1080)) }
+    stage: { content: { x, y, w: contentW, h: contentH }, chromeH, radius: Math.round(14 * ui) }
   };
 }
 var PROFILE_16x9 = {
@@ -3063,7 +3684,8 @@ var PROFILE_16x9 = {
   safeArea: { top: 54, right: 96, bottom: 160, left: 96 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 110,
-  captionMaxWidth: 1040
+  captionMaxWidth: 1040,
+  uiScale: 1
 };
 var PROFILE_9x16 = {
   width: 1080,
@@ -3072,7 +3694,8 @@ var PROFILE_9x16 = {
   safeArea: { top: 230, right: 56, bottom: 320, left: 56 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 96,
-  captionMaxWidth: 980
+  captionMaxWidth: 980,
+  uiScale: 1
 };
 var PROFILE_1x1 = {
   width: 1080,
@@ -3081,7 +3704,8 @@ var PROFILE_1x1 = {
   safeArea: { top: 80, right: 72, bottom: 200, left: 72 },
   zoomQuantums: [1, 1.15, 1.3, 1.5, 1.7, 2],
   minFocusPx: 100,
-  captionMaxWidth: 940
+  captionMaxWidth: 940,
+  uiScale: 1
 };
 function profileForAspect(aspect, resolution, fps) {
   const base = aspect === "9:16" ? PROFILE_9x16 : aspect === "1:1" ? PROFILE_1x1 : PROFILE_16x9;
@@ -3098,7 +3722,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) {
@@ -3186,6 +3811,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
@@ -3210,10 +3838,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}`);
@@ -3242,6 +3897,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,
@@ -3268,6 +3924,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;
@@ -3306,13 +3974,48 @@ function sampleCamera(keyframes, tOut) {
   }
   const a = keyframes[lo];
   const b = keyframes[hi];
-  const u = (tOut - a.tOut) / Math.max(1e-6, b.tOut - a.tOut);
-  const e = cubicBezier(b.ease, u);
-  return {
-    cx: a.state.cx + (b.state.cx - a.state.cx) * e,
-    cy: a.state.cy + (b.state.cy - a.state.cy) * e,
-    zoom: Math.exp(Math.log(a.state.zoom) + (Math.log(b.state.zoom) - Math.log(a.state.zoom)) * e)
-  };
+  const dt = Math.max(1e-6, b.tOut - a.tOut);
+  const u = (tOut - a.tOut) / dt;
+  if (sameState(a.state, b.state)) return { ...a.state };
+  const va = [a.state.cx, a.state.cy, Math.log(a.state.zoom)];
+  const vb = [b.state.cx, b.state.cy, Math.log(b.state.zoom)];
+  const TENSION = 0.5;
+  const ma = tangentAt(keyframes, lo, TENSION);
+  const mb = tangentAt(keyframes, hi, TENSION);
+  const isolated = ma.every((m) => m === 0) && mb.every((m) => m === 0);
+  if (isolated) {
+    const e = cubicBezier(b.ease, u);
+    return {
+      cx: va[0] + (vb[0] - va[0]) * e,
+      cy: va[1] + (vb[1] - va[1]) * e,
+      zoom: Math.exp(va[2] + (vb[2] - va[2]) * e)
+    };
+  }
+  const u2 = u * u;
+  const u3 = u2 * u;
+  const h00 = 2 * u3 - 3 * u2 + 1;
+  const h10 = u3 - 2 * u2 + u;
+  const h01 = -2 * u3 + 3 * u2;
+  const h11 = u3 - u2;
+  const out = [0, 0, 0];
+  for (let c = 0; c < 3; c++) {
+    out[c] = h00 * va[c] + h10 * dt * ma[c] + h01 * vb[c] + h11 * dt * mb[c];
+  }
+  return { cx: out[0], cy: out[1], zoom: Math.exp(out[2]) };
+}
+function tangentAt(keyframes, i, tension) {
+  const cur = keyframes[i];
+  const prev = i > 0 ? keyframes[i - 1] : null;
+  const next = i < keyframes.length - 1 ? keyframes[i + 1] : null;
+  if (!prev || !next) return [0, 0, 0];
+  if (sameState(prev.state, cur.state) || sameState(cur.state, next.state)) return [0, 0, 0];
+  const dt = Math.max(1e-6, next.tOut - prev.tOut);
+  const vp = [prev.state.cx, prev.state.cy, Math.log(prev.state.zoom)];
+  const vn = [next.state.cx, next.state.cy, Math.log(next.state.zoom)];
+  return [0, 1, 2].map((c) => tension * (vn[c] - vp[c]) / dt);
+}
+function sameState(a, b) {
+  return Math.abs(a.cx - b.cx) < 0.5 && Math.abs(a.cy - b.cy) < 0.5 && Math.abs(a.zoom - b.zoom) < 1e-3;
 }
 
 // src/compose/camera/planner.ts
@@ -3339,7 +4042,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);
@@ -3356,7 +4060,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) {
@@ -3431,6 +4137,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,
@@ -3438,7 +4145,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
@@ -3671,6 +4378,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":
@@ -3816,29 +4529,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];
@@ -3967,19 +4697,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();
@@ -4005,13 +4754,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)";
@@ -4019,13 +4769,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) {
@@ -4033,23 +4783,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) {
@@ -4058,23 +4809,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();
@@ -4086,7 +4850,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";
@@ -4110,16 +4874,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 = [];
@@ -4160,14 +4925,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();
@@ -4190,7 +4956,8 @@ var FrameStore = class {
   async frameForTime(tMs) {
     const idx = frameIndexForTime(this.bundle.frames, tMs);
     const canvas = await this.get(idx);
-    if (idx + 1 < this.bundle.frames.length) void this.get(idx + 1);
+    if (idx + 1 < this.bundle.frames.length) this.get(idx + 1).catch(() => {
+    });
     return canvas;
   }
   /**
@@ -4217,6 +4984,7 @@ var FrameStore = class {
       return hit;
     }
     const promise = this.decode(idx);
+    promise.catch(() => this.cache.delete(idx));
     this.cache.set(idx, promise);
     while (this.cache.size > LRU_SIZE) {
       const oldest = this.cache.keys().next().value;
@@ -4342,12 +5110,19 @@ var Encoder = class {
       this.child.on("error", reject);
       this.child.on("close", (code) => resolve2(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() {
@@ -4364,6 +5139,7 @@ init_log();
 var SPOTLIGHT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
 var SPOTLIGHT_LEAD_MS = 200;
 var SPOTLIGHT_TAIL_MS = 650;
+var SPOTLIGHT_TAIL_GONE_MS = 160;
 var SPOTLIGHT_MAX_DIM = 0.34;
 async function renderVideo(bundle, manifest, outPath) {
   registerFonts();
@@ -4395,7 +5171,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++) {
@@ -4436,7 +5212,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 {
@@ -4452,7 +5229,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);
@@ -4548,11 +5325,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;
@@ -4575,7 +5353,152 @@ function cursorGlyphAt(steps, tOut) {
   for (const s of steps) {
     if (s.kind === "type" && tOut >= s.outStart && tOut <= s.outEnd) return "ibeam";
   }
-  return "arrow";
+  return "arrow";
+}
+
+// src/verify/media.ts
+import sharp3 from "sharp";
+async function extractGrayFrames(videoPath, fps, w, h) {
+  const res = await runBinaryRaw(ffmpegPath(), [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-i",
+    videoPath,
+    "-vf",
+    `fps=${fps},scale=${w}:${h}`,
+    "-f",
+    "rawvideo",
+    "-pix_fmt",
+    "gray",
+    "pipe:1"
+  ]);
+  if (res.code !== 0) throw new Error(`frame extraction failed: ${res.stderr}`);
+  const frameSize = w * h;
+  const frames = [];
+  for (let off = 0; off + frameSize <= res.stdout.length; off += frameSize) {
+    frames.push(res.stdout.subarray(off, off + frameSize));
+  }
+  return { frames, intervalMs: 1e3 / fps };
+}
+async function extractFrameAt(videoPath, tMs) {
+  const res = await runBinaryRaw(ffmpegPath(), [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-ss",
+    (Math.max(0, tMs) / 1e3).toFixed(3),
+    "-i",
+    videoPath,
+    "-frames:v",
+    "1",
+    "-f",
+    "image2pipe",
+    "-vcodec",
+    "png",
+    "pipe:1"
+  ]);
+  if (res.code !== 0 || res.stdout.length === 0) {
+    throw new Error(`could not extract frame at ${tMs}ms: ${res.stderr}`);
+  }
+  return res.stdout;
+}
+async function probeVideo(videoPath) {
+  const res = await runBinary(ffprobePath(), [
+    "-v",
+    "error",
+    "-print_format",
+    "json",
+    "-show_format",
+    "-show_streams",
+    videoPath
+  ]);
+  if (res.code !== 0) throw new Error(`ffprobe failed: ${res.stderr}`);
+  const json = JSON.parse(res.stdout);
+  const v = json.streams?.find((s) => s.codec_type === "video");
+  if (!v) throw new Error("no video stream found");
+  const [num, den] = v.avg_frame_rate.split("/").map(Number);
+  return {
+    codec: v.codec_name,
+    width: v.width,
+    height: v.height,
+    durationSec: Number(json.format?.duration ?? 0),
+    fps: den ? num / den : 0
+  };
+}
+function meanAbsDiff(a, b) {
+  const n = Math.min(a.length, b.length);
+  let sum = 0;
+  for (let i = 0; i < n; i++) sum += Math.abs(a[i] - b[i]);
+  return sum / n;
+}
+function variance(a) {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += a[i];
+  const mean = sum / a.length;
+  let v = 0;
+  for (let i = 0; i < a.length; i++) v += (a[i] - mean) ** 2;
+  return v / a.length;
+}
+async function sourceFrameGray(bundle, tMs, width) {
+  const idx = frameIndexForTime(bundle.frames, tMs);
+  const { data, info } = await sharp3(framePath(bundle, idx)).resize({ width }).grayscale().raw().toBuffer({ resolveWithObject: true });
+  return { data, w: info.width, h: info.height, frameT: bundle.frames[idx].t };
+}
+async function sourceRegionGray(bundle, tMs, region, preferAfter = false, color = false) {
+  let idx = frameIndexForTime(bundle.frames, tMs);
+  if (preferAfter && idx + 1 < bundle.frames.length && bundle.frames[idx].t < tMs) idx += 1;
+  const meta = await sharp3(framePath(bundle, idx)).metadata();
+  const fw = meta.width ?? 0;
+  const fh = meta.height ?? 0;
+  const x = Math.max(0, Math.round(region.x));
+  const y = Math.max(0, Math.round(region.y));
+  const w = Math.min(Math.round(region.w), fw - x);
+  const h = Math.min(Math.round(region.h), fh - y);
+  if (w < 4 || h < 4) return null;
+  let img = sharp3(framePath(bundle, idx)).extract({ left: x, top: y, width: w, height: h });
+  if (!color) img = img.grayscale();
+  const { data } = await img.raw().toBuffer({ resolveWithObject: true });
+  return data;
+}
+async function regionGray48(input, rect) {
+  try {
+    const img = sharp3(input);
+    const meta = await img.metadata();
+    const W = meta.width ?? 0;
+    const H = meta.height ?? 0;
+    const left = Math.max(0, Math.round(rect.x));
+    const top = Math.max(0, Math.round(rect.y));
+    const width = Math.min(W - left, Math.round(rect.w));
+    const height = Math.min(H - top, Math.round(rect.h));
+    if (width < 8 || height < 8) return null;
+    return await sharp3(input).extract({ left, top, width, height }).grayscale().resize(48, 48, { fit: "fill" }).raw().toBuffer();
+  } catch {
+    return null;
+  }
+}
+function normalizedCorrelation(a, b) {
+  const n = Math.min(a.length, b.length);
+  let ma = 0;
+  let mb = 0;
+  for (let i = 0; i < n; i++) {
+    ma += a[i];
+    mb += b[i];
+  }
+  ma /= n;
+  mb /= n;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < n; i++) {
+    const xa = a[i] - ma;
+    const xb = b[i] - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  if (da < 1e-6 || db < 1e-6) return da < 1e-6 && db < 1e-6 ? 1 : 0;
+  return num / Math.sqrt(da * db);
 }
 
 // src/compose/index.ts
@@ -4586,9 +5509,9 @@ init_schema();
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { mkdir as mkdir2, writeFile as writeFile3 } 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";
 var require3 = createRequire4(import.meta.url);
 var ffprobePath2 = require3("ffprobe-static").path;
@@ -4682,9 +5605,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;
@@ -4694,8 +5617,8 @@ async function synthesizeNarration(lines, opts, cacheDir) {
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
 import { rename, mkdir as mkdir3 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { join as join7 } from "path";
 import { createRequire as createRequire5 } from "module";
 var require4 = createRequire5(import.meta.url);
 var ffmpegPath2 = require4("ffmpeg-static");
@@ -4703,8 +5626,9 @@ var exec2 = promisify2(execFile2);
 async function mixAudio(videoPath, steps, durationMs, opts) {
   const placed = (opts.narration ? steps : []).map((s) => ({ start: Math.round(s.outStart + AUDIO_LEAD_MS), clip: opts.narration.get(s.stepRef) })).filter((p) => p.clip !== void 0);
   const beats = opts.sfxBeats ?? [];
+  const keyBeats = opts.keyBeats ?? [];
   const hasMusic = !!opts.music;
-  if (placed.length === 0 && beats.length === 0 && !hasMusic) return [];
+  if (placed.length === 0 && beats.length === 0 && keyBeats.length === 0 && !hasMusic) return [];
   const durSec = (durationMs / 1e3).toFixed(3);
   const args = ["-y", "-loglevel", "error", "-i", videoPath];
   const inputs = [];
@@ -4742,6 +5666,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++;
@@ -4785,10 +5724,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",
@@ -4827,7 +5784,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;
@@ -4838,7 +5795,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;
@@ -4865,8 +5822,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);
@@ -4929,46 +5887,109 @@ function plan(bundle, spec, theme, profile, audioMs) {
     bundleHashes: bundle.manifest.hashes
   };
 }
+var BLINK_DIFF_MIN = 25;
+async function excludeTransientPreActionFrames(bundle) {
+  const notes = [];
+  const dpr = bundle.manifest.dpr;
+  const excluded = /* @__PURE__ */ new Set();
+  for (const e of actionEvents(bundle.events)) {
+    if (e.kind !== "click" && e.kind !== "dblclick") continue;
+    if (!e.targetPre || !e.cursorPath || e.cursorPath.length === 0) continue;
+    const tArrive = e.cursorPath[e.cursorPath.length - 1].t;
+    if (!(tArrive < e.tAction)) continue;
+    const iArrive = frameIndexForTime(bundle.frames, tArrive);
+    const iBeat = frameIndexForTime(bundle.frames, e.tAction);
+    if (iBeat <= iArrive) continue;
+    const b = e.targetPre.bbox;
+    const region = { x: b.x * dpr, y: b.y * dpr, w: b.w * dpr, h: b.h * dpr };
+    const ref = await sourceRegionGray(bundle, bundle.frames[iArrive].t, region);
+    if (!ref) continue;
+    for (let i = iArrive + 1; i <= iBeat; i++) {
+      const cand = await sourceRegionGray(bundle, bundle.frames[i].t, region);
+      if (!cand || cand.length !== ref.length) continue;
+      if (meanAbsDiff(ref, cand) > BLINK_DIFF_MIN) {
+        excluded.add(i);
+        notes.push(
+          `${e.sceneId}/${e.stepIndex}: frame ${bundle.frames[i].f} (t=${Math.round(bundle.frames[i].t)}) is a pre-click transient (target region contradicts the arrival frame) \u2014 excluded from composition`
+        );
+      }
+    }
+  }
+  if (excluded.size === 0) return { bundle, notes };
+  return { bundle: { ...bundle, frames: bundle.frames.filter((_, i) => !excluded.has(i)) }, notes };
+}
+var JUMP_DIFF_MIN = 18;
+var JUMP_DISSOLVE_MS = 360;
+async function smoothJumpCuts(bundle, manifest) {
+  for (const s of manifest.steps) {
+    if (s.kind !== "click" && s.kind !== "dblclick" && s.kind !== "press" && s.kind !== "select") continue;
+    const before = await sourceFrameGray(bundle, Math.max(0, s.srcAction - 30), 320);
+    const after = await sourceFrameGray(bundle, Math.min(s.srcAction + 700, s.srcSettled), 320);
+    if (after.frameT <= before.frameT || after.data.length !== before.data.length) continue;
+    if (meanAbsDiff(before.data, after.data) < JUMP_DIFF_MIN) continue;
+    const tStart = s.outBeat + 60;
+    const tEnd = Math.min(tStart + JUMP_DISSOLVE_MS, s.outEnd);
+    if ((manifest.transitions ?? []).some((w) => tStart <= w.tEnd && tEnd >= w.tStart)) continue;
+    manifest.transitions = manifest.transitions ?? [];
+    manifest.transitions.push({ tStart, tEnd, srcFrom: before.frameT });
+  }
+}
 async function compose(bundle, spec, opts) {
   const audioCfg = spec.output.audio;
   let narration;
   let audioMs;
+  let narrationDegraded;
+  const voiceLabel = audioCfg?.voice ?? (audioCfg?.provider === "kokoro" ? "heart" : "Samantha");
   if (audioCfg && audioCfg.narration === "tts") {
     const texts = specStepTexts(spec);
     const lines = actionEvents(bundle.events).map((e) => {
       const ref = `${e.sceneId}/${e.stepIndex}`;
       return { stepRef: ref, text: writeNarration(e, texts.get(ref)) };
     }).filter((l) => typeof l.text === "string" && l.text.length > 0);
-    log.info(`synthesizing narration: ${lines.length} lines (${audioCfg.provider}, voice ${audioCfg.voice ?? "Samantha"})`);
+    log.info(`synthesizing narration: ${lines.length} lines (${audioCfg.provider}, voice ${voiceLabel})`);
     try {
-      narration = await synthesizeNarration(lines, audioCfg, join7(opts.outDir, "narration"));
+      narration = await synthesizeNarration(lines, audioCfg, join8(opts.outDir, "narration"));
       audioMs = new Map([...narration].map(([k, v]) => [k, v.durationMs]));
     } catch (e) {
-      log.warn(`narration unavailable on this host (${e.message.split("\n")[0]}) \u2014 rendering WITHOUT voice`);
+      narrationDegraded = e.message.split("\n")[0] ?? "TTS unavailable";
+      log.warn(`narration unavailable on this host (${narrationDegraded}) \u2014 rendering WITHOUT voice; the audio check will FAIL`);
       narration = void 0;
       audioMs = void 0;
     }
   }
+  const transient = await excludeTransientPreActionFrames(bundle);
+  bundle = transient.bundle;
   const manifest = plan(bundle, spec, opts.theme, opts.profile, audioMs);
+  manifest.diagnostics.clockWarnings.push(...transient.notes);
+  await smoothJumpCuts(bundle, manifest);
   for (const w of manifest.diagnostics.clockWarnings) log.warn(w);
   for (const f of manifest.diagnostics.cameraFallbacks) log.warn(f);
-  const videoPath = join7(opts.outDir, opts.fileName ?? "out.mp4");
+  const videoPath = join8(opts.outDir, opts.fileName ?? "out.mp4");
   log.info(
     `composing ${(manifest.durationMs / 1e3).toFixed(1)}s (${manifest.totalFrames} frames @ ${manifest.profile.fps}fps, ${manifest.profile.width}x${manifest.profile.height})`
   );
   await renderVideo(bundle, manifest, videoPath);
   if (audioCfg && (narration || audioCfg.sfx || audioCfg.music)) {
+    const keyBeats = [];
+    if (audioCfg.sfx) {
+      for (const s of manifest.steps) {
+        if (s.kind !== "type") continue;
+        const headEnd = Math.min(s.outEnd, s.outBeat + 1150);
+        for (let t = s.outBeat + 40; t < headEnd; t += 78 + (t | 0) % 29) keyBeats.push(t);
+      }
+    }
     const clips = await mixAudio(videoPath, manifest.steps, manifest.durationMs, {
       ...narration ? { narration } : {},
       ...audioCfg.sfx ? { sfxBeats: manifest.ripples } : {},
+      ...keyBeats.length > 0 ? { keyBeats } : {},
       ...audioCfg.music ? { music: audioCfg.music } : {},
-      cacheDir: join7(opts.outDir, "narration")
+      cacheDir: join8(opts.outDir, "narration")
     });
     if (narration) {
       manifest.audio = {
         narrated: true,
         provider: audioCfg.provider,
-        voice: audioCfg.voice ?? "Samantha",
+        voice: voiceLabel,
         lines: clips.length,
         clips
       };
@@ -4977,8 +5998,19 @@ async function compose(bundle, spec, opts) {
       `\u2713 audio: ${clips.length} narration line(s)${audioCfg.sfx ? `, ${manifest.ripples.length} click(s)` : ""}${audioCfg.music ? ", music bed" : ""} \u2192 ${videoPath}`
     );
   }
+  if (narrationDegraded && !manifest.audio) {
+    manifest.audio = {
+      narrated: false,
+      provider: audioCfg?.provider ?? "say",
+      voice: voiceLabel,
+      lines: 0,
+      degraded: narrationDegraded
+    };
+  } else if (narrationDegraded && manifest.audio) {
+    manifest.audio.degraded = narrationDegraded;
+  }
   manifest.videoSha256 = await sha256File(videoPath);
-  const manifestPath = join7(opts.outDir, "compose-manifest.json");
+  const manifestPath = join8(opts.outDir, "compose-manifest.json");
   await writeFile4(manifestPath, JSON.stringify(manifest, null, 2));
   return { videoPath, manifestPath, manifest };
 }
@@ -4991,158 +6023,11 @@ function safeHost(url) {
 }
 
 // src/verify/runner.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { mkdir as mkdir4, writeFile as writeFile6, readFile as readFile4 } from "fs/promises";
 
 // src/verify/checks.ts
 init_geometry();
-
-// src/verify/media.ts
-import sharp3 from "sharp";
-async function extractGrayFrames(videoPath, fps, w, h) {
-  const res = await runBinaryRaw(ffmpegPath(), [
-    "-hide_banner",
-    "-loglevel",
-    "error",
-    "-i",
-    videoPath,
-    "-vf",
-    `fps=${fps},scale=${w}:${h}`,
-    "-f",
-    "rawvideo",
-    "-pix_fmt",
-    "gray",
-    "pipe:1"
-  ]);
-  if (res.code !== 0) throw new Error(`frame extraction failed: ${res.stderr}`);
-  const frameSize = w * h;
-  const frames = [];
-  for (let off = 0; off + frameSize <= res.stdout.length; off += frameSize) {
-    frames.push(res.stdout.subarray(off, off + frameSize));
-  }
-  return { frames, intervalMs: 1e3 / fps };
-}
-async function extractFrameAt(videoPath, tMs) {
-  const res = await runBinaryRaw(ffmpegPath(), [
-    "-hide_banner",
-    "-loglevel",
-    "error",
-    "-ss",
-    (Math.max(0, tMs) / 1e3).toFixed(3),
-    "-i",
-    videoPath,
-    "-frames:v",
-    "1",
-    "-f",
-    "image2pipe",
-    "-vcodec",
-    "png",
-    "pipe:1"
-  ]);
-  if (res.code !== 0 || res.stdout.length === 0) {
-    throw new Error(`could not extract frame at ${tMs}ms: ${res.stderr}`);
-  }
-  return res.stdout;
-}
-async function probeVideo(videoPath) {
-  const res = await runBinary(ffprobePath(), [
-    "-v",
-    "error",
-    "-print_format",
-    "json",
-    "-show_format",
-    "-show_streams",
-    videoPath
-  ]);
-  if (res.code !== 0) throw new Error(`ffprobe failed: ${res.stderr}`);
-  const json = JSON.parse(res.stdout);
-  const v = json.streams?.find((s) => s.codec_type === "video");
-  if (!v) throw new Error("no video stream found");
-  const [num, den] = v.avg_frame_rate.split("/").map(Number);
-  return {
-    codec: v.codec_name,
-    width: v.width,
-    height: v.height,
-    durationSec: Number(json.format?.duration ?? 0),
-    fps: den ? num / den : 0
-  };
-}
-function meanAbsDiff(a, b) {
-  const n = Math.min(a.length, b.length);
-  let sum = 0;
-  for (let i = 0; i < n; i++) sum += Math.abs(a[i] - b[i]);
-  return sum / n;
-}
-function variance(a) {
-  let sum = 0;
-  for (let i = 0; i < a.length; i++) sum += a[i];
-  const mean = sum / a.length;
-  let v = 0;
-  for (let i = 0; i < a.length; i++) v += (a[i] - mean) ** 2;
-  return v / a.length;
-}
-async function sourceFrameGray(bundle, tMs, width) {
-  const idx = frameIndexForTime(bundle.frames, tMs);
-  const { data, info } = await sharp3(framePath(bundle, idx)).resize({ width }).grayscale().raw().toBuffer({ resolveWithObject: true });
-  return { data, w: info.width, h: info.height, frameT: bundle.frames[idx].t };
-}
-async function sourceRegionGray(bundle, tMs, region, preferAfter = false, color = false) {
-  let idx = frameIndexForTime(bundle.frames, tMs);
-  if (preferAfter && idx + 1 < bundle.frames.length && bundle.frames[idx].t < tMs) idx += 1;
-  const meta = await sharp3(framePath(bundle, idx)).metadata();
-  const fw = meta.width ?? 0;
-  const fh = meta.height ?? 0;
-  const x = Math.max(0, Math.round(region.x));
-  const y = Math.max(0, Math.round(region.y));
-  const w = Math.min(Math.round(region.w), fw - x);
-  const h = Math.min(Math.round(region.h), fh - y);
-  if (w < 4 || h < 4) return null;
-  let img = sharp3(framePath(bundle, idx)).extract({ left: x, top: y, width: w, height: h });
-  if (!color) img = img.grayscale();
-  const { data } = await img.raw().toBuffer({ resolveWithObject: true });
-  return data;
-}
-async function regionGray48(input, rect) {
-  try {
-    const img = sharp3(input);
-    const meta = await img.metadata();
-    const W = meta.width ?? 0;
-    const H = meta.height ?? 0;
-    const left = Math.max(0, Math.round(rect.x));
-    const top = Math.max(0, Math.round(rect.y));
-    const width = Math.min(W - left, Math.round(rect.w));
-    const height = Math.min(H - top, Math.round(rect.h));
-    if (width < 8 || height < 8) return null;
-    return await sharp3(input).extract({ left, top, width, height }).grayscale().resize(48, 48, { fit: "fill" }).raw().toBuffer();
-  } catch {
-    return null;
-  }
-}
-function normalizedCorrelation(a, b) {
-  const n = Math.min(a.length, b.length);
-  let ma = 0;
-  let mb = 0;
-  for (let i = 0; i < n; i++) {
-    ma += a[i];
-    mb += b[i];
-  }
-  ma /= n;
-  mb /= n;
-  let num = 0;
-  let da = 0;
-  let db = 0;
-  for (let i = 0; i < n; i++) {
-    const xa = a[i] - ma;
-    const xb = b[i] - mb;
-    num += xa * xb;
-    da += xa * xa;
-    db += xb * xb;
-  }
-  if (da < 1e-6 || db < 1e-6) return da < 1e-6 && db < 1e-6 ? 1 : 0;
-  return num / Math.sqrt(da * db);
-}
-
-// src/verify/checks.ts
 var EFFECT_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "type", "select", "goto"]);
 var CLICK_KINDS2 = /* @__PURE__ */ new Set(["click", "dblclick", "select"]);
 function plane(ctx2) {
@@ -5221,7 +6106,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 = [];
@@ -5279,12 +6204,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) {
@@ -5292,10 +6219,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);
@@ -5303,11 +6231,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 }));
@@ -5342,7 +6282,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 = [];
@@ -5353,7 +6304,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;
@@ -5361,7 +6312,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 = [];
@@ -5377,7 +6356,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",
@@ -5512,9 +6504,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) {
@@ -5572,7 +6592,7 @@ async function checkOutputPixels(ctx2) {
     }
   }
   if (checked === 0) return { id: "output-pixels", status: "skip", details: "no comparable samples (captions overlapped or frames unavailable)" };
-  return evidence.length > 0 ? { id: "output-pixels", status: "fail", details: `${evidence.length}/${checked} sampled regions diverge from the plan`, evidence } : { id: "output-pixels", status: "pass", details: `${checked} sampled output regions match their planned source` };
+  return evidence.length > 0 ? { id: "output-pixels", status: "fail", details: `${evidence.length}/${checked} sampled regions diverge from the plan`, evidence, coverage: { verified: checked - evidence.length, total: checked } } : { id: "output-pixels", status: "pass", details: `${checked} sampled output regions match their planned source`, coverage: { verified: checked, total: checked } };
 }
 
 // src/verify/contact-sheet.ts
@@ -5721,13 +6741,17 @@ function extractJson(text) {
 }
 
 // src/verify/report.ts
-import { createHmac } from "crypto";
+import { createHmac, createHash as createHash4, sign as edSign, verify as edVerify, createPrivateKey, createPublicKey } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
 function signablePayload(v) {
   return JSON.stringify({
     schema: v.schema,
     verdict: v.verdict,
     videoSha256: v.video.sha256,
+    manifestHash: v.manifestHash,
+    contactSheetSha256: v.contactSheetSha256,
     bundleHashes: { events: v.bundleHashes.events, framesIndex: v.bundleHashes.framesIndex },
+    coverage: v.coverage,
     provenance: {
       playheadVersion: v.provenance.playheadVersion,
       specHash: v.provenance.specHash,
@@ -5736,23 +6760,54 @@ function signablePayload(v) {
       verifiedAt: v.provenance.verifiedAt,
       checkSuiteVersion: v.provenance.checkSuiteVersion,
       host: v.provenance.host,
-      partial: v.provenance.partial ?? false
+      partial: v.provenance.partial ?? false,
+      failure: v.provenance.failure ?? null
     },
-    checks: v.checks.map((c) => ({ id: c.id, status: c.status }))
+    checks: v.checks.map((c) => ({
+      id: c.id,
+      status: c.status,
+      details: c.details,
+      evidence: (c.evidence ?? []).map((e) => ({ stepRef: e.stepRef ?? null, t: e.t ?? null, note: e.note }))
+    })),
+    vision: v.vision
   });
 }
-function signVerdict(v, key = process.env.PLAYHEAD_SIGNING_KEY) {
-  if (!key) return null;
-  return createHmac("sha256", key).update(signablePayload(v)).digest("hex");
+function signVerdict(v, env = {
+  ...process.env.PLAYHEAD_SIGNING_KEY ? { hmacKey: process.env.PLAYHEAD_SIGNING_KEY } : {},
+  ...process.env.PLAYHEAD_SIGNING_KEY_FILE ? { keyFile: process.env.PLAYHEAD_SIGNING_KEY_FILE } : {}
+}) {
+  const payload = Buffer.from(signablePayload(v));
+  if (env.keyFile) {
+    const privateKey = createPrivateKey(readFileSync2(env.keyFile, "utf8"));
+    const publicKey = createPublicKey(privateKey);
+    const spki = publicKey.export({ type: "spki", format: "der" });
+    return {
+      alg: "Ed25519",
+      keyId: keyIdFor(spki),
+      publicKey: spki.toString("base64"),
+      value: edSign(null, payload, privateKey).toString("base64")
+    };
+  }
+  if (env.hmacKey) {
+    return {
+      alg: "HS256",
+      keyId: keyIdFor(Buffer.from(env.hmacKey)),
+      value: createHmac("sha256", env.hmacKey).update(payload).digest("hex")
+    };
+  }
+  return null;
+}
+function keyIdFor(material) {
+  return createHash4("sha256").update(material).digest("hex").slice(0, 16);
 }
 
 // src/verify/runner.ts
 init_log();
 import { platform, arch } from "os";
 import pc2 from "picocolors";
-var CHECK_SUITE_VERSION = "playhead/checks@2";
+var CHECK_SUITE_VERSION = "playhead/checks@3";
 async function verify(bundle, manifest, videoPath, opts) {
-  const verifyDir = join8(opts.outDir, "verify");
+  const verifyDir = join9(opts.outDir, "verify");
   await mkdir4(verifyDir, { recursive: true });
   const ctx2 = { bundle, manifest, videoPath, outDir: verifyDir };
   log.info("verifying output");
@@ -5776,7 +6831,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;
@@ -5787,11 +6842,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,
@@ -5809,9 +6881,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 writeFile6(join8(verifyDir, "verdict.json"), JSON.stringify(verdict, null, 2));
-  if (failed) log.error(`verdict: NOT PUBLISHABLE`);
-  else log.ok(`verdict: publishable`);
+  await writeFile6(join9(verifyDir, "verdict.json"), JSON.stringify(verdict, null, 2));
+  const cov = coverage.actionsTotal > 0 ? ` (coverage: ${coverage.actionsVerified}/${coverage.actionsTotal} actions pixel-verified, ${coverage.outputSamplesVerified} output samples)` : " (coverage: no effectful actions)";
+  if (failed) log.error(`verdict: NOT PUBLISHABLE${cov}`);
+  else log.ok(`verdict: publishable${cov}`);
   return verdict;
 }
 function report(c) {
@@ -5842,11 +6915,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) }] };
     }
   );
@@ -5859,10 +6937,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,
@@ -5870,7 +6949,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}
@@ -5926,21 +7006,48 @@ ${formatValidateResult2(res)}` }],
       await mkdir5(out, { recursive: true });
       let parsedSpec;
       if (spec) {
-        const tmp = await mkdtemp(join10(tmpdir(), "playhead-spec-"));
-        const p = join10(tmp, "spec.yaml");
+        const tmp = await mkdtemp(join11(tmpdir(), "playhead-spec-"));
+        const p = join11(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(join11(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(join11(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(