retake-demos 0.3.0 → 0.4.0

package/dist/dryrun.js

@@ -8,13 +8,74 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { runFileOrCommandSeed, resolvePoint, dragPoints } from "./record.js";
+import { applyPageSetup, authState, dragPoints, gateOnApp, resolvePoint, runEvaluateSeed, runFileOrCommandSeed } from "./record.js";
 import { chromium } from "playwright";
 import { expandEnv, resolve } from "./manifest.js";
+async function elInfo(page, selector, timeout) {
+    try {
+        const h = await page.locator(selector).first().elementHandle({ timeout });
+        if (!h)
+            return null;
+        const info = await h.evaluate((el) => {
+            const e = el;
+            return {
+                tag: e.tagName.toLowerCase(),
+                type: (e.type ?? "").toLowerCase(),
+                disabled: !!e.disabled || e.getAttribute("aria-disabled") === "true",
+                readOnly: !!e.readOnly,
+                editable: e.isContentEditable,
+            };
+        });
+        await h.dispose();
+        return info;
+    }
+    catch {
+        return null;
+    }
+}
+/** Does this action make sense on this element? Returns the complaint, or null.
+ *
+ * This is the check that pays for itself: an action that cannot work on the
+ * element it names is knowable before a single frame is recorded, and finding
+ * it out during a take costs the whole take. So the message names the fix, not
+ * just the symptom — a report that says "use `action: select`" ends the
+ * problem, one that says "element is not an <input>" starts an investigation. */
+export function actionFits(action, el) {
+    const NOT_TEXT = new Set(["button", "submit", "reset", "checkbox", "radio", "file", "image", "range", "color"]);
+    const is = (t) => el.tag === t;
+    if (action === "type" || action === "fill") {
+        if (is("select"))
+            return `\`${action}\` cannot be used on a <select> — use \`action: select\` with \`value: "<the option>"\``;
+        if (is("input") && el.type === "file")
+            return `\`${action}\` cannot be used on a file input — use \`action: upload\` with \`file:\``;
+        if (is("input") && NOT_TEXT.has(el.type))
+            return `\`${action}\` cannot be used on <input type="${el.type}"> — it holds no text; \`action: click\` is probably what you mean`;
+        if (!is("input") && !is("textarea") && !el.editable)
+            return `\`${action}\` needs a text field, but this is a <${el.tag}> that is not editable — if it is a custom editor, target the inner element that accepts typing`;
+        if (el.disabled)
+            return `\`${action}\` cannot type into a disabled <${el.tag}> — something earlier has to enable it first`;
+        if (el.readOnly)
+            return `\`${action}\` cannot type into a read-only <${el.tag}>`;
+    }
+    if (action === "select" && !is("select")) {
+        return `\`select\` only works on a real <select>, and this is a <${el.tag}> — for a custom dropdown, \`click\` it and then \`click\` the option`;
+    }
+    if (action === "upload" && !(is("input") && el.type === "file")) {
+        return `\`upload\` needs <input type="file">, and this is a <${el.tag}>${el.type && el.type !== el.tag ? ` type="${el.type}"` : ""}`;
+    }
+    if (action === "click" && el.disabled) {
+        return `this <${el.tag}> is disabled right now — the click would do nothing; wait for whatever enables it (\`action: waitFor\`) before clicking`;
+    }
+    return null;
+}
 export async function dryRun(m, manifestDir, log, opts = {}) {
     const q = resolve(m);
     const lines = [];
     let failures = 0;
+    /** What the page actually laid out at — the width its breakpoints saw. */
+    let layoutWidth = null;
+    // Failure pictures land beside the demo's other output, not in the cwd.
+    const shotDir = path.join(opts.outRoot ?? "outputs", m.name);
     // Seeds run here too (file and command kinds — the cheap, out-of-page
     // ones). Without them dry checks a different app state than run will,
     // and a selector failure that is really a state difference looks like a
@@ -28,11 +89,23 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         log("dry: seeds skipped (--no-seed) — app state may not match what run will see");
     }
     const browser = await chromium.launch({ headless: true });
+    // Start from the same session run would. Without this, a demo behind a
+    // login was dry-run logged OUT — every selector "missing", or worse, a
+    // green dry against a marketing page and a failed take against the app.
+    const auth = authState(m, manifestDir);
+    if (auth.path)
+        log(auth.fresh ? `dry: reusing session ${path.relative(process.cwd(), auth.path)}` : `dry: no fresh session — auth.setup will have to sign in`);
     const context = await browser.newContext({
         viewport: q.viewport,
         colorScheme: m.colorScheme,
         ...(m.reducedMotion ? { reducedMotion: "reduce" } : {}),
+        ...(auth.fresh && auth.path ? { storageState: auth.path } : {}),
     });
+    // Whatever the recorder injects, dry injects — one function, so the two
+    // cannot drift apart again. (Measured, for the record: `html{zoom}` does
+    // NOT move an app's media queries, which is why the layout width reported
+    // below is asked of the page rather than computed as width÷scale.)
+    await applyPageSetup(context, m, q);
     const stubs = new Map();
     const arm = async (d) => {
         const key = `${d.method ?? "ANY"} ${d.url}`;
@@ -56,6 +129,20 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         // go network-idle, and the manifest's waitForSelector is the real gate.
         await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 60000 });
         await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
+        // `evaluate` seeds write into the page itself — the panel that only
+        // exists once some state is seeded. Dry skipped them, so dry and run were
+        // literally looking at different apps; that was one of three lost takes
+        // in the field report.
+        if (opts.seed !== false) {
+            for (const sd of m.seed)
+                if (sd.kind === "evaluate")
+                    await runEvaluateSeed(page, sd, manifestDir, log);
+        }
+        // The manifest's own readiness gate, with run's wrong-app diagnosis. A dry
+        // run that starts stepping before the app has booted reports selector
+        // failures that are really a race.
+        await gateOnApp(page, m, shotDir);
+        layoutWidth = await page.evaluate(() => document.documentElement.clientWidth).catch(() => null);
         for (const s of [...(m.auth?.setup ?? []), ...m.setup])
             await run(s, true);
         for (const [i, s] of m.steps.entries())
@@ -69,6 +156,16 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         const tag = isSetup ? "setup" : String(index).padStart(3, "0");
         const short = 8000; // long enough for a click that navigates, short enough to stay fast
         try {
+            // Before doing anything: does this action fit the element it names? A
+            // mismatch is the expensive kind of failure — the selector resolves, dry
+            // passes, and the take dies on it minutes into a recording.
+            const sel = step.selector;
+            if (sel && ["type", "fill", "select", "upload", "click"].includes(step.action)) {
+                const el = await elInfo(page, sel, short);
+                const complaint = el && actionFits(step.action, el);
+                if (complaint)
+                    throw new Error(complaint);
+            }
             // A point step (click/hover `at`, or a drag) is verified by resolving
             // its target's rect in the page — the same way the recorder will.
             const point = async (t) => {
@@ -117,7 +214,7 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                         await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
                         break;
                     case "waitFor":
-                        await page.waitForSelector(step.selector, { timeout: Math.min(step.timeout ?? 15000, 15000) });
+                        await page.waitForSelector(step.selector, { state: step.gone ? "hidden" : "visible", timeout: Math.min(step.timeout ?? 15000, 15000) });
                         break;
                     // noWaitAfter: a click that submits a form starts a navigation, and
                     // waiting for the element to settle afterwards reports a false failure
@@ -138,6 +235,19 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                     case "hover":
                         await page.locator(step.selector).first().hover({ timeout: short });
                         break;
+                    case "select": {
+                        // Resolving is not enough: an option that does not exist is the
+                        // whole failure mode, so dry proves the value is selectable.
+                        const sel = page.locator(step.selector).first();
+                        await sel.waitFor({ timeout: short });
+                        try {
+                            await sel.selectOption(step.value, { timeout: short });
+                        }
+                        catch {
+                            await sel.selectOption({ label: step.value }, { timeout: short });
+                        }
+                        break;
+                    }
                     case "scroll":
                         if (step.to)
                             await page.locator(step.to).first().boundingBox({ timeout: short });
@@ -179,6 +289,16 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                 where = `\n        on ${page.url()} — “${text}”`;
             }
             catch { /* page may be gone */ }
+            // Text alone cannot say "another element is covering the button" or
+            // "the layout is not what you think". A picture can, and dry is the
+            // cheap pass — it should hand over more than run's does, not less.
+            try {
+                const shot = path.join(shotDir, `dry-failed-${String(failures).padStart(2, "0")}.png`);
+                fs.mkdirSync(shotDir, { recursive: true });
+                await page.screenshot({ path: shot, fullPage: true });
+                where += `\n        picture: ${path.relative(process.cwd(), shot)}`;
+            }
+            catch { /* not fatal */ }
             const line = `✗ [${tag}] ${describe(step)} — ${why}${where}`;
             lines.push(line);
             log(line);
@@ -186,8 +306,68 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
     }
     const ok = failures === 0;
     log(ok ? `dry run: all ${m.steps.length} steps resolved` : `dry run: ${failures} step(s) would fail`);
+    // A preset's width is VIDEO pixels: at scale 2 a 1920 preset lays the page
+    // out at 960 CSS px, under most desktop breakpoints, so a responsive app
+    // quietly serves its MOBILE layout and the steps are looking for fields that
+    // are not there. It reads as a pile of broken selectors, and costs a whole
+    // take to work out. Only asked when something actually failed, and only
+    // reported when the wider page proves it.
+    if (!ok) {
+        // Measured, not computed: `zoom` does not move an app's media queries, so
+        // width÷scale is not the number the page's breakpoints saw. Ask the page.
+        const cssWidth = layoutWidth ?? q.viewport.width;
+        if (cssWidth < 1100) {
+            const missing = lines.map((l) => /✗ \[[^\]]+\] \w+ (.+?) —/.exec(l)?.[1]).filter((x) => !!x);
+            const found = await resolvesWiderThan(m, missing, cssWidth, manifestDir);
+            if (found.length) {
+                const note = `⚠ ${found.length} of these selector(s) DO exist when the page is 1280 CSS px wide, but not at ${cssWidth}px.\n` +
+                    `   This take lays the page out at ${cssWidth} CSS px, which is below this app's desktop breakpoint — you are filming its mobile layout.\n` +
+                    `   Fix: give the manifest a wider \`viewport\`, or write the steps against the layout you are actually filming.\n` +
+                    `   Resolved wider: ${found.slice(0, 4).join(", ")}${found.length > 4 ? ` … +${found.length - 4}` : ""}`;
+                lines.push(note);
+                log(note);
+            }
+        }
+    }
     return { ok, lines, failures };
 }
+/** Load the same page at a desktop width and report which of these selectors
+    resolve there. Proof, not a guess: it is only worth telling someone their
+    preset is filming the mobile layout if the wider page really does have the
+    thing they were looking for. */
+async function resolvesWiderThan(m, selectors, narrowPx, manifestDir) {
+    const unique = [...new Set(selectors)].filter((s) => s && !s.startsWith("http"));
+    if (!unique.length || narrowPx >= 1280)
+        return [];
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const ctx = await browser.newContext({ viewport: { width: 1280, height: 900 }, colorScheme: m.colorScheme });
+        const page = await ctx.newPage();
+        for (const d of m.stub) {
+            await ctx.route(d.url, async (route) => {
+                const body = d.json !== undefined ? JSON.stringify(d.json) : d.from ? fs.readFileSync(path.resolve(manifestDir, expandEnv(d.from)), "utf8") : "{}";
+                await route.fulfill({ status: d.status ?? 200, contentType: d.contentType, body });
+            });
+        }
+        await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 30000 });
+        await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => { });
+        const found = [];
+        for (const sel of unique) {
+            try {
+                if (await page.locator(sel).first().isVisible({ timeout: 1500 }))
+                    found.push(sel);
+            }
+            catch { /* still missing */ }
+        }
+        return found;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
 function describe(s) {
     if ("selector" in s && s.selector)
         return `${s.action} ${s.selector}`;

package/dist/manifest.js

@@ -79,6 +79,14 @@ export const Step = z.discriminatedUnion("action", [
             slow it down and the viewer can follow what went past. */
         speed: z.number().positive().max(4).optional(),
     }),
+    /** Choose an option in a <select>. A form-heavy app is mostly dropdowns, and
+        without this a demo of one has to fake them with evaluate. */
+    Base.extend({
+        action: z.literal("select"),
+        selector: Selector,
+        /** The option's value, or its visible label — whichever the page uses. */
+        value: z.string(),
+    }),
     Base.extend({
         action: z.literal("zoom"),
         selector: Selector.optional(),
@@ -97,7 +105,23 @@ export const Step = z.discriminatedUnion("action", [
     Base.extend({ action: z.literal("download"), selector: Selector.optional(), saveAs: z.string().optional(), expect: z.string().optional() }),
     /** Wait for a selector to appear (Retake extra; the thing testreel's JSON lacks
         for AI-driven apps whose next screen arrives whenever the model answers). */
-    Base.extend({ action: z.literal("waitFor"), selector: Selector }),
+    /** Wait for a real result. A bare selector resolves the instant the element
+        exists, which is the wrong moment three ways, all of them seen in the
+        field: the element is a shell that streams its text in afterwards; the
+        element is the PREVIOUS run\'s banner still on screen; the element is
+        there but the app is still busy. Hence: */
+    Base.extend({
+        action: z.literal("waitFor"),
+        selector: Selector,
+        /** Wait for it to go AWAY instead of appear — the fix for waiting on a
+            stale success banner from the previous action. */
+        gone: z.boolean().default(false),
+        /** Resolve only once the subtree has stopped changing for this long.
+            This is how you wait for a streamed reply to finish. */
+        stableMs: z.number().min(50).max(30_000).optional(),
+        /** Resolve only once it holds at least this much text. */
+        minChars: z.number().int().positive().optional(),
+    }),
     /** Run JS in the page (Retake extra). Used for seeding, hiding chrome, etc. */
     Base.extend({ action: z.literal("evaluate"), script: z.string().min(1) }),
     /** Change what a stubbed endpoint answers, mid-take. This is how a demo shows
@@ -126,6 +150,11 @@ export const Step = z.discriminatedUnion("action", [
     Base.extend({
         action: z.literal("scene"),
         label: z.string().min(1),
+        /** Move this scene's marker in the finished video, in milliseconds
+            (negative = earlier). RENDER-TIME: it shifts where the caption, the
+            still and the thumbnail land, and never costs a new recording. A
+            caption that arrives a beat late is a re-render, not a re-take. */
+        nudge: z.number().int().min(-60_000).max(60_000).optional(),
         caption: z.string().optional(),
         holdMs: z.number().positive().optional(),
         /** Where the camera looks during this scene. Omitted → the manifest's
@@ -385,6 +414,29 @@ export function warnings(m) {
     const w = [];
     // A demo proves an interaction; a launch presents the product. Launch
     // furniture in a demo is noise the viewer has to look past.
+    // A held opening frame is the point of a launch cut, not a mistake.
+    const launch = m.mode === "launch";
+    if (m.viewport) {
+        const p = PRESETS[m.preset] ?? PRESETS[DEFAULT_PRESET];
+        const band = m.captions === false ? 0 : p.bandHeight;
+        if (m.viewport.width !== p.width || m.viewport.height !== p.height - band) {
+            w.push(`\`viewport\` overrides the preset, so this video will be ${m.viewport.width}×${m.viewport.height + band} instead of ${p.name}'s ${p.width}×${p.height}. Two demos of the same app then come out different shapes and players letterbox them. Drop \`viewport\` unless the app genuinely needs it.`);
+        }
+    }
+    // A navigation that only changes the #fragment does not reload the document.
+    // An SPA keeps every bit of in-memory state, so a stub armed just before it
+    // is never fetched — and the screen looks plausible, just stale, which is
+    // the worst kind of wrong to debug. Knowable from the manifest alone.
+    {
+        const hops = [m.url, ...m.steps.flatMap((st) => (st.action === "navigate" ? [st.url] : []))];
+        for (let i = 1; i < hops.length; i++) {
+            const [a, b] = [hops[i - 1], hops[i]];
+            const strip = (u) => u.split("#")[0];
+            if (a !== b && strip(a) === strip(b) && b.includes("#")) {
+                w.push(`step ${i} navigates to \`${b}\` which differs from the previous URL ONLY by its #fragment — the browser will not reload the document. A single-page app keeps all of its in-memory state, so anything you armed just before this (a \`stub\`, a seed) is never re-fetched and the screen looks right but stale. Add a throwaway query param (\`?r=${i}\`) before the fragment to force a real load, or drive the change by clicking the app's own link.`);
+            }
+        }
+    }
     if (m.mode === "demo") {
         const launchy = [m.intro && "intro card", m.outro && "outro card", m.music && "music", m.steps.some((s) => s.action === "callout") && "callouts"].filter(Boolean);
         if (launchy.length)
@@ -412,7 +464,9 @@ export function warnings(m) {
         const nextScene = rest.findIndex((x) => x.action === "scene");
         const between = nextScene === -1 ? rest : rest.slice(0, nextScene);
         // A closing hold on the payoff is normal; only a waits-only scene *followed by another* is empty.
-        if (nextScene !== -1 && between.length && between.every((x) => x.action === "wait"))
+        // In a launch cut the opening scene IS a held frame — that is the shot.
+        const isFirstScene = m.steps.findIndex((x) => x.action === "scene") === i;
+        if (nextScene !== -1 && between.length && between.every((x) => x.action === "wait") && !(launch && isFirstScene))
             w.push(`scene "${st.label}" has only waits before the next scene — nothing happens on camera in it.`);
     });
     return w;
@@ -448,7 +502,15 @@ export function totp(base32Secret, nowMs = Date.now()) {
 }
 export function resolve(m) {
     const p = PRESETS[m.preset] ?? PRESETS[DEFAULT_PRESET];
-    const viewport = { width: m.viewport?.width ?? p.width, height: m.viewport?.height ?? p.height };
+    // The page is the canvas minus the caption strip, so the finished video is
+    // exactly the preset's size. A manifest may override it, and `warnings()`
+    // says out loud that doing so changes the output size.
+    // No captions anywhere (switched off, or no scene carries one) → no band
+    // to reserve: the page records at the full canvas and fills the frame.
+    const anyCaption = m.captions !== false && m.steps.some((st) => st.action === "scene" && Boolean(st.caption?.trim()));
+    const layout = m.layout ?? p.layout;
+    const band = anyCaption && (layout === "band" || layout === "card") ? p.bandHeight : 0;
+    const viewport = { width: m.viewport?.width ?? p.width, height: m.viewport?.height ?? p.height - band };
     const gifOverride = m.outputs.gif;
     /* `gif: true` means "yes, a GIF" on any preset. Only docs-gif carries GIF
        settings, so asking for one anywhere else used to resolve to the preset's
@@ -466,7 +528,8 @@ export function resolve(m) {
         scale: m.scale ?? p.scale,
         fps: m.fps ?? p.fps,
         crf: m.crf ?? p.crf,
-        layout: m.layout ?? p.layout,
+        layout,
+        bandHeight: band,
         cameraZoom: typeof m.camera === "object" ? m.camera.zoom : p.cameraZoom,
         gif,
         cursor,

package/dist/operator/tools.js

@@ -19,7 +19,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import YAML from "yaml";
 import { loadManifest } from "../manifest.js";
-import { record, captureHash, acquireLock, releaseLock } from "../record.js";
+import { record, captureHash, acquireLock, releaseLock, keepPrevious, restorePrevious, stashPrevious, EXPENSIVE_TAKE_SECONDS } from "../record.js";
 import { render, check, ffmpegBin } from "../render.js";
 import { execFileSync } from "node:child_process";
 import { dryRun } from "../dryrun.js";
@@ -360,20 +360,35 @@ server.registerTool("dry", { description: "Run a demo with no camera: every sele
     await tell(r.ok ? `Checked: all ${manifest.steps.length} steps resolve` : `${r.failures} step(s) would fail`);
     return text(r.ok ? `ok: all ${manifest.steps.length} steps resolve` : r.lines.join("\n"));
 });
-server.registerTool("run", { description: "Record the demo and render it. Slow (the demo is performed in real time). preview=true for a fast low-cost render to check the story. Returns the receipts. `check: pass` and healthy audio prove the FILE is sound, not that the demo is good — call `look` at the payoff scene and judge it: can a stranger state the promise from that frame, is the result legible at playback size, is any beat longer than what it tells you? If you cannot answer yes, fix the cut before calling done.", inputSchema: { name: z.string(), preview: z.boolean().default(true), until: z.string().optional().describe("record up to the end of this scene label, then stop — for iterating on one beat of a long demo") }, annotations: RETAKE_WRITE }, async ({ name, preview, until }) => {
+server.registerTool("run", { description: "Record the demo and render it. Slow (the demo is performed in real time). preview=true for a fast low-cost render to check the story — ALWAYS start there, and on a long demo show that draft to the person before spending the full take. Returns the receipts. SIZE IS NOT RECORDED: any take renders at any preset later (`render` with a preset), so never re-record to change the shape and never set `viewport` in a manifest — the preset owns the size and every take at a preset is identical. `check: pass` and healthy audio prove the FILE is sound, not that the demo is good — call `look` at the payoff scene and judge it: can a stranger state the promise from that frame, is the result legible at playback size, is any beat longer than what it tells you? If you cannot answer yes, fix the cut before calling done.", inputSchema: { name: z.string(), preview: z.boolean().default(true), until: z.string().optional().describe("record up to the end of this scene label, then stop — for iterating on one beat of a long demo"), from: z.string().optional().describe("start the take AT this scene: earlier steps still run, at full speed and off camera. When only the ending changed, this is the difference between re-recording 90 seconds and re-recording seven minutes") }, annotations: RETAKE_WRITE }, async ({ name, preview, until, from }) => {
     LAST_DEMO = name;
     if (!safe(name) || !fs.existsSync(manifestPath(name)))
         return text(`no demo "${name}"`);
     const loaded = loadManifest(manifestPath(name));
-    const manifest = preview ? { ...loaded.manifest, preset: "preview-fast" } : loaded.manifest;
+    // preview means "the fast shape", so a manifest that pins its own viewport
+    // must not win silently — that is how a draft ends up costing what the real
+    // take costs.
+    const { viewport: pinned, ...rest } = loaded.manifest;
+    const manifest = preview ? { ...rest, preset: "preview-fast" } : loaded.manifest;
+    if (preview && pinned)
+        await tell(`preview overrides the pinned ${pinned.width}×${pinned.height} viewport`);
     const outDir = path.join(OUT, name);
     acquireLock(outDir);
     try {
-        for (const f of fs.existsSync(outDir) ? fs.readdirSync(outDir) : [])
-            if (f !== ".retake-lock")
-                fs.rmSync(path.join(outDir, f), { recursive: true, force: true });
+        // Moved aside, not deleted: a failed recording must not cost the person
+        // the take they already had.
+        stashPrevious(outDir);
         await tell(`Recording ${name}${preview ? " (preview)" : ""}…`);
-        const take = await record(manifest, { outDir, manifestDir: DEMOS, locked: true, until, log: () => { } });
+        let take;
+        try {
+            take = await record(manifest, { outDir, manifestDir: DEMOS, locked: true, until, from, log: () => { } });
+        }
+        catch (e) {
+            if (restorePrevious(outDir))
+                await tell("Recording failed — your previous take has been put back.");
+            throw e;
+        }
+        keepPrevious(outDir, (l) => void tell(l));
         await tell(`Rendering…`);
         const a = await render(manifest, take, outDir, {});
         const c = check(outDir, manifest);
@@ -383,13 +398,24 @@ server.registerTool("run", { description: "Record the demo and render it. Slow (
         // the page showed, so even a small model gets a one-line repair.
         if (failed)
             return text(`FAILED at step ${failed.index} — ${failed.summary}: ${failed.error ?? "error"}${failed.screen ? `\nOn screen at that moment: “${failed.screen}”` : ""}\nThe camera stopped there (${(take.duration - take.trimBefore).toFixed(0)}s recorded). This is not a demo yet: edit the manifest, dry, run again. Do NOT call done on a failed take.\n\n${summariseTake(take)}`);
-        return text(`${summariseTake(take)}\nvideo: ${a.mp4 ?? "none"}\ncheck: ${c.ok ? "pass" : "FAIL"}\n${c.lines.filter((l) => l.startsWith("FAIL")).join("\n")}`);
+        // The gate: a person's eyes are the only check for whether this is the
+        // RIGHT video, and they are cheapest to apply to a draft. Say so here,
+        // where the agent is deciding what to do next, rather than after the
+        // expensive take has already been spent.
+        // Measured, not estimated: this draft just performed the same demo against
+        // the same app, so its own capture time is what the full take will cost.
+        const took = take.captureSec ?? 0;
+        const mins = took >= 120 ? `${Math.round(took / 60)} min` : `${Math.round(took)}s`;
+        const gate = preview && took >= EXPENSIVE_TAKE_SECONDS && c.ok
+            ? `\n\nTHIS DRAFT TOOK ${mins} TO RECORD, and the full take costs about the same again. Do not run it at full quality yet. Show this draft to the person — \`ask\` them, say how long it is and what it shows, and point them at the Retake window. Their answer is the one thing no check here can give you: whether this is the right video. If they cannot be reached, stop and say what is ready and what the full take would cost; do not spend it on their behalf.`
+            : "";
+        return text(`${summariseTake(take)}\nvideo: ${a.mp4 ?? "none"}\ncheck: ${c.ok ? "pass" : "FAIL"}\n${c.lines.filter((l) => l.startsWith("FAIL")).join("\n")}${gate}`);
     }
     finally {
         releaseLock(outDir);
     }
 });
-server.registerTool("render", { description: "Re-render the last recording of a demo with the current manifest (captions, camera, trim, format). No browser, seconds.", inputSchema: { name: z.string() }, annotations: RETAKE_WRITE }, async ({ name }) => {
+server.registerTool("render", { description: "Re-render the last recording with the current manifest. No browser, seconds. THIS, NOT `run`, IS THE ANSWER TO ALMOST EVERY CHANGE: size and shape and format, a caption's words, speed, zoom, cards, music, the poster, and WHERE a caption sits (`nudge: <ms>` on the scene moves its marker, and the still and thumbnail follow). Only a change to what the demo DOES needs the camera again — and even then, `run` with `from`/`until` records one end of it rather than all of it.", inputSchema: { name: z.string() }, annotations: RETAKE_WRITE }, async ({ name }) => {
     LAST_DEMO = name;
     const outDir = path.join(OUT, name);
     const tp = path.join(outDir, "take.json");
@@ -466,4 +492,19 @@ server.registerTool("done", { description: "Call when the demo is recorded and a
     return text("ok");
 });
 const transport = new StdioServerTransport();
+// Leave when the client does. Without this the server sat on a closed stdin
+// forever — a day of agent sessions left a row of them running, each holding a
+// Node runtime for a client that had long since exited.
+let leaving = false;
+const leave = () => {
+    if (leaving)
+        return;
+    leaving = true;
+    void server.close().catch(() => { }).finally(() => process.exit(0));
+};
+transport.onclose = leave;
+process.stdin.once("end", leave);
+process.stdin.once("close", leave);
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.once(sig, leave);
 await server.connect(transport);

package/dist/presets.js

@@ -8,7 +8,7 @@ export const PRESETS = {
         name: "draft",
         width: 960, height: 540, scale: 1, fps: 15, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 36, captionFontSize: 24, bandHeight: 76, bandFit: "text",
+        cursorSize: 36, captionFontSize: 24, bandHeight: 76,
         encoder: "videotoolbox", master: false,
         description: "Fastest. Same layout as the final at a quarter of the pixels — for iterating, never for shipping.",
     },
@@ -16,7 +16,7 @@ export const PRESETS = {
         name: "preview-fast",
         width: 1920, height: 1080, scale: 2, fps: 24, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
         encoder: "videotoolbox", master: false,
         description: "Same framing as post, hardware-encoded MP4 only. For checking timing and framing fast.",
     },
@@ -24,7 +24,7 @@ export const PRESETS = {
         name: "proof-fast",
         width: 960, height: 720, scale: 1, fps: 24, crf: 24,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 40, captionFontSize: 26, bandHeight: 84, bandFit: "text",
+        cursorSize: 40, captionFontSize: 26, bandHeight: 84,
         encoder: "videotoolbox", master: false,
         description: "Small, quick internal check.",
     },
@@ -32,34 +32,34 @@ export const PRESETS = {
         name: "post-landscape",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
         encoder: "x264", master: true,
-        description: "1080p, 30fps, CRF 17. The general-purpose demo. GIF on request.",
+        description: "A true 1920×1080, 30fps, CRF 17. The general-purpose demo. GIF on request.",
     },
     "post-square": {
         name: "post-square",
         /* The page area is the canvas minus the caption band, so the file really
            is 1080×1080 — a square preset that produced 1080×1210 got letterboxed
            by every feed. Landscape keeps its full-height page on purpose. */
-        width: 1080, height: 960, scale: 1.6, fps: 30, crf: 17,
+        width: 1080, height: 1080, scale: 1.6, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 60, captionFontSize: 36, bandHeight: 120, bandFit: "fill",
+        cursorSize: 60, captionFontSize: 36, bandHeight: 120,
         encoder: "x264", master: true,
-        description: "A true 1080×1080 (page 1080×960 + a fixed 120px caption band), feed-friendly.",
+        description: "1080×1080 for feeds. Page 1080×960 with a 120px caption band.",
     },
     "post-vertical": {
         name: "post-vertical",
-        width: 1080, height: 1800, scale: 2, fps: 30, crf: 17,
+        width: 1080, height: 1920, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.3,
-        cursorSize: 60, captionFontSize: 40, bandHeight: 120, bandFit: "fill",
+        cursorSize: 60, captionFontSize: 40, bandHeight: 120,
         encoder: "x264", master: true,
-        description: "A true 1080×1920 (page 1080×1800 + a fixed 120px caption band) for shorts/reels. Narrow-column apps suit it best.",
+        description: "1080×1920 for shorts and reels. Narrow-column apps suit it best.",
     },
     "docs-gif": {
         name: "docs-gif",
         width: 1440, height: 900, scale: 1.5, fps: 24, crf: 20,
         gif: { width: 900, fps: 15 }, layout: "band", cameraZoom: 1.2,
-        cursorSize: 48, captionFontSize: 32, bandHeight: 100, bandFit: "text",
+        cursorSize: 48, captionFontSize: 32, bandHeight: 100,
         encoder: "x264", master: false,
         description: "README/docs GIF, 900px wide.",
     },
@@ -67,7 +67,7 @@ export const PRESETS = {
         name: "master",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 12,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
         encoder: "x264", master: true,
         description: "Highest quality, slowest. Archive/source render.",
     },