retake-demos 0.2.2 → 0.4.0

package/dist/manifest.js

@@ -8,6 +8,7 @@
  *   - `outputs`  which artifacts to produce and how
  */
 import fs from "node:fs";
+import { createHmac } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { z } from "zod";
@@ -78,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(),
@@ -96,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
@@ -110,11 +135,26 @@ export const Step = z.discriminatedUnion("action", [
         json: z.unknown().optional(),
         from: z.string().optional(),
     }),
+    /** Point at something while the take holds: an animated ring and an optional
+        label, drawn at render time from the box recorded here. Sparingly — one
+        per scene at most; the captions carry the story. */
+    Base.extend({
+        action: z.literal("callout"),
+        selector: Selector.optional(),
+        at: Point.optional(),
+        label: z.string().max(60).optional(),
+        ms: z.number().positive().max(8000).default(2200),
+    }),
     /** A named beat. Timestamps go into the proof log; `caption` gets burned into
         the video from this moment until the next scene (or `holdMs`). */
     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
@@ -124,7 +164,7 @@ export const Step = z.discriminatedUnion("action", [
             .optional(),
     }),
 ]).superRefine((st, ctx) => {
-    if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
+    if ((st.action === "click" || st.action === "hover" || st.action === "callout") && !st.selector && !st.at) {
         ctx.addIssue({ code: "custom", message: `${st.action} needs either a selector or an \`at\` point` });
     }
 });
@@ -177,7 +217,60 @@ const ManifestShape = z.object({
     /** band (default): the site fills the frame, caption strip below · card: the recording framed on a soft canvas · overlay-*: caption over the video · none */
     layout: z.enum(["band", "card", "overlay-bottom", "overlay-top", "none"]).optional(),
     /** auto: each scene zooms toward the last element the demo touched · static: no camera moves. */
-    camera: z.union([z.literal("auto"), z.literal("static"), z.object({ zoom: z.number().min(1).max(3) })]).default("auto"),
+    /** Compress at render what nobody watches. A waitFor/navigate that made
+        the viewer sit through N seconds is shown as ~keepSeconds (real start,
+        then a fast-forward); a long typing run keeps its start and its finish
+        at real speed and accelerates the middle (every keystroke is a
+        round-trip, so a real sentence costs ~5s of video). The author's own
+        `wait` steps are pacing and are never touched. Off by default. */
+    compressIdle: z.union([z.boolean(), z.object({ keepSeconds: z.number().min(0.8).max(5).default(1.5) })]).default(false),
+    /** What this take is FOR, and it changes what is allowed to be in it.
+        `demo` (the default) proves an interaction: direct, legible, minimally
+        framed — a title card or music in a demo is noise. `launch` presents
+        the product, so cards, music, emphasis and a branded ending are
+        legitimate, and each one still has to earn the second it costs.
+        Retake never upgrades a demo to a launch on its own. */
+    mode: z.enum(["demo", "launch"]).default("demo"),
+    /** How typed text lands. `natural` is the per-step default (~80ms a key);
+        `brisk` is the launch rhythm — fast keys (~22ms), the pauses carrying
+        the meaning instead. A step's own `delay` always wins. */
+    typing: z.enum(["natural", "brisk"]).default("natural"),
+    /** The captions, read aloud (edge-tts). Each scene's caption is synthesized
+        and placed at the scene's start; music ducks under it. The captions are
+        the script — there is nothing separate to write. */
+    voiceover: z
+        .union([
+        z.boolean(),
+        z.object({
+            voice: z.string().default("en-US-JennyNeural"),
+            gainDb: z.number().min(-20).max(10).default(0),
+            /** One continuous script, synthesized as a single performance and
+                laid under the whole video — the only shape that keeps prosody.
+                Without it, narration is per-scene fragments: prosody resets at
+                every line and the read/wait rhythm follows scene boundaries
+                instead of speech. Fragments are refused unless `fragments: true`
+                says you know. */
+            script: z.string().optional(),
+            fragments: z.boolean().default(false),
+            /** A person has heard this voice and this script and approved them.
+                Synthesis succeeding is not approval. */
+            approved: z.boolean().default(false),
+        }),
+    ])
+        .default(false),
+    /** A music bed under the whole video, mixed at render time: looped or
+        trimmed to fit, faded out over the last moments. The person supplies the
+        file (CC0/licensed — it ships inside their video); Retake bundles none. */
+    music: z.union([z.string(), z.object({ file: z.string(), gainDb: z.number().min(-40).max(6).default(-14), fadeOutMs: z.number().positive().max(8000).default(1800) })]).optional(),
+    /** Title cards, rendered at render time (change them, re-render in seconds).
+        The intro's settled frame is also written as cover.png — the poster. */
+    intro: z.object({ title: z.string().max(60), subtitle: z.string().max(90).optional(), ms: z.number().positive().max(6000).default(2400) }).optional(),
+    outro: z.object({ title: z.string().max(60), subtitle: z.string().max(90).optional(), ms: z.number().positive().max(6000).default(2000) }).optional(),
+    /** Still by default. A zoom is something a person asks for after seeing a
+        take, never something that happens to them: a calm demo reads as real
+        and can never crop the wrong thing. `auto` eases toward the last thing
+        touched; a scene can override either way. */
+    camera: z.union([z.literal("auto"), z.literal("static"), z.object({ zoom: z.number().min(1).max(3) })]).default("static"),
     /** Seconds cut from the head/tail of the finished video. Render-only: change
         it and re-render, no re-recording. */
     trim: z.object({ head: z.number().nonnegative().default(0), tail: z.number().nonnegative().default(0) }).prefault({}),
@@ -248,6 +341,20 @@ const ManifestShape = z.object({
         .prefault({}),
 });
 export const Manifest = ManifestShape.superRefine((m, ctx) => {
+    // A synthetic voice is a claim on the person's taste. Retake will not put
+    // one in a deliverable until they have heard it and said yes — and will
+    // not read the captions as fragments at all, because that is the defect,
+    // not the voice: prosody resets every line and the rhythm follows scene
+    // boundaries instead of speech.
+    if (m.voiceover) {
+        const vo = m.voiceover === true ? { approved: false, script: undefined, fragments: false } : m.voiceover;
+        if (!vo.approved) {
+            ctx.addIssue({ code: "custom", path: ["voiceover"], message: "voiceover is not approved. Synthesize it, LISTEN to it with the person, and only then set `approved: true`. Successful synthesis is not approval; a silent cut beats an unapproved synthetic voice." });
+        }
+        if (!vo.script && !vo.fragments) {
+            ctx.addIssue({ code: "custom", path: ["voiceover"], message: "voiceover needs `script:` — one continuous script, synthesized as a single performance. Reading the captions line by line resets prosody at every scene and paces the speech off scene boundaries. Set `fragments: true` only if you have heard the fragmented read and want it." });
+        }
+    }
     [...m.steps, ...m.setup].forEach((st, i) => {
         if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
             ctx.addIssue({ code: "custom", path: ["steps", i], message: `${st.action} needs either a selector or an \`at\` point` });
@@ -305,6 +412,36 @@ export function loadManifest(file) {
 /** Things worth saying out loud before a run. Not errors — the run proceeds. */
 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)
+            w.push(`this is \`mode: demo\` but carries ${launchy.join(", ")} — a demo proves the interaction and wants nothing else in the frame. Set \`mode: launch\` if it is a launch video, or drop them.`);
+    }
     // Secrets typed during recorded steps end up in the video. In `setup` they do
     // not: setup runs before the camera and is trimmed off the front.
     const onCamera = m.steps.filter((s) => s.secret).length;
@@ -327,23 +464,53 @@ 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;
 }
 /** `${VAR}` substitution against process.env, like testreel. */
 export function expandEnv(s) {
-    return s.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => {
+    return s.replace(/\$\{(TOTP:)?([A-Z0-9_]+)\}/g, (_, fn, k) => {
         const v = process.env[k];
-        if (v === undefined)
-            throw new Error(`manifest references \${${k}} but it is not set`);
-        return v;
+        // `APP_USER=` with nothing after it is the template, not a value — a blank
+        // login that "succeeds" is worse than a loud stop.
+        if (v === undefined || v.trim() === "")
+            throw new Error(`manifest references \${${k}} but it is not set — add it to .env (a demo account, never a real one)`);
+        // ${TOTP:APP_TOTP_SECRET}: the six-digit code for right now, from an
+        // authenticator enrolment secret. Computed at fill time, so it is valid.
+        return fn ? totp(v) : v;
     });
 }
+/** RFC 6238 TOTP (SHA-1, 6 digits, 30s) from a base32 secret — what every
+    authenticator app enrols with. */
+export function totp(base32Secret, nowMs = Date.now()) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    const clean = base32Secret.toUpperCase().replace(/[^A-Z2-7]/g, "");
+    let bits = "";
+    for (const c of clean)
+        bits += alphabet.indexOf(c).toString(2).padStart(5, "0");
+    const key = Buffer.from((bits.match(/.{8}/g) ?? []).map((b) => parseInt(b, 2)));
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(Math.floor(nowMs / 30000)));
+    const h = createHmac("sha1", key).update(counter).digest();
+    const off = h[h.length - 1] & 0xf;
+    const code = ((h[off] & 0x7f) << 24 | h[off + 1] << 16 | h[off + 2] << 8 | h[off + 3]) % 1_000_000;
+    return String(code).padStart(6, "0");
+}
 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
@@ -361,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/run.js

@@ -44,6 +44,10 @@ export function brief(input) {
         "6. When it is good, run with preview=false once for the real quality, then done with one sentence.",
         "",
         "Rules:",
+        "- Every manifest carries `mode:`. `demo` is the default and covers almost everything — it proves how the thing works and keeps everything but the product out of the frame. `mode: launch` is only for a video that presents the product in public (a launch, a post, an ad); it is the one mode where title cards, music, a callout and a branded ending belong, and it must end with THEIR product, never Retake. Decide from the audience, not the subject: a client walkthrough is a demo. Never upgrade a demo to a launch on your own.",
+        "- A caption earns its place only by saying what the screen cannot. Do not narrate a visible click. Hold the payoff in ONE frame instead of touring its parts.",
+        "- `check: pass` proves the file is sound, not that the demo is good. Use `look` on the payoff and judge it as a viewer before `done`.",
+        "- Never add voiceover. It needs a continuous script and a person who has heard it.",
         "- Never type real passwords into a manifest; use ${ENV_VAR} and secret: true, and tell the person which variable to set.",
         "- Never invent selectors; use what scout/read_project returned.",
         "- Never accept a static manifest for an interactive request. It must perform the requested actions after setup, not merely describe them with scenes and waits.",

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";
@@ -27,6 +27,7 @@ import { scout, draftManifest, suggestIdeas, pickProvider, loadDotenv } from "..
 import { digest } from "../digest.js";
 import { startApp as reallyStartApp, listeningPorts as ports, waitForUrl as waitUrl } from "../appserver.js";
 import { applyEdits, receiptsFor } from "../edits.js";
+import { SECRET_NAME, missingSecrets, readEnvFile } from "../env.js";
 const ROOT = process.env.RETAKE_ROOT || process.cwd();
 const DEMOS = path.join(ROOT, "demos");
 const OUT = process.env.RETAKE_OUT ? path.resolve(process.env.RETAKE_OUT.replace(/^~/, os.homedir())) : path.join(ROOT, "outputs");
@@ -129,7 +130,63 @@ server.registerTool("start_app", {
     await tell(`Could not start it: ${r.why}`);
     return text(`FAILED: ${r.why}\nlog tail:\n${r.log.slice(-800)}`);
 });
-server.registerTool("ask", { description: "Ask the person ONE question and wait for the answer. Use only when genuinely blocked (which app, a credential name, a choice between two things). Keep it one sentence, with the evidence.", inputSchema: { question: z.string() }, annotations: RETAKE_WRITE }, async ({ question }) => {
+server.registerTool("secrets", {
+    description: [
+        "Get the person's demo-account credentials into place WITHOUT ever seeing them. Call this the moment a demo needs a login (read_project found sign-in fields, scout found a password field, or they said so): pass the variable NAMES you will use (APP_USER, APP_PASSWORD, and APP_TOTP_SECRET if the site asks for an authenticator code).",
+        "It returns at once with what to tell the person — ALWAYS relay it in full, with the link: assume they have never seen the Retake window and do not know it exists. They type the values into a form there (or into their terminal); the values go straight into the workspace .env; you only ever learn 'set'. When they say they are done, call this tool again with the same names.",
+        "Then the manifest references them as ${APP_USER} / ${APP_PASSWORD} with `secret: true`, inside auth.setup. Never ask for a password in chat, never put a literal credential in a manifest, never invent values. For logins a script cannot do (SMS code, SSO, captcha): `retake signin demos/<name>.yaml` — the person signs in once in a real window and Retake keeps the session.",
+    ].join(" "),
+    inputSchema: {
+        names: z.array(z.string().regex(SECRET_NAME, "UPPER_SNAKE names like APP_PASSWORD")).min(1).describe("the environment variable names the manifest will reference"),
+        why: z.string().describe("one sentence the person will read: what the login is for, e.g. 'The dashboard demo starts behind the admin sign-in.'"),
+    },
+    annotations: RETAKE_WRITE,
+}, async ({ names, why }) => {
+    const reload = () => { for (const [k, v] of Object.entries(readEnvFile(ROOT)))
+        if (v.trim())
+            process.env[k] = v; };
+    const how = `Reference them as ${names.map((n) => "${" + n + "}").join(", ")} with \`secret: true\` inside auth.setup${names.some((n) => /TOTP/.test(n)) ? ` (the authenticator one as ${"${TOTP:" + names.find((n) => /TOTP/.test(n)) + "}"} — Retake computes the current code)` : ""}. The values stay in .env; you never see them, and they are never on camera.`;
+    reload();
+    let missing = missingSecrets(ROOT, names);
+    if (!missing.length)
+        return text(`All set: ${names.join(", ")} are in the workspace .env. ${how} Continue.`);
+    const link = UI || "http://localhost:4310";
+    const list = missing.join(" and ");
+    // Is the window actually there? A dead URL must not leave the person
+    // staring at a link that does nothing.
+    const windowUp = UI ? await fetch(`${UI}/api/settings`).then((r) => r.ok).catch(() => false) : false;
+    if (windowUp) {
+        // One open form per set of names — calling again must not stack forms.
+        const pending = await fetch(`${UI}/api/secrets/pending`).then((r) => r.json()).catch(() => []);
+        let req = pending.find((r) => r.names.join() === missing.join());
+        if (req) {
+            // Second call: they said "done" (or we are checking). Give the form a
+            // short moment, then report — never sit here in silence.
+            const deadline = Date.now() + 20_000;
+            while (Date.now() < deadline) {
+                const st = await fetch(`${UI}/api/secrets/${req.id}`).then((x) => x.json()).catch(() => null);
+                if (st?.filled)
+                    break;
+                await new Promise((ok) => setTimeout(ok, 2000));
+            }
+            reload();
+            missing = missingSecrets(ROOT, names);
+            if (!missing.length)
+                return text(`Set: ${names.join(", ")} — saved to the workspace .env from the Retake window. ${how} Continue.`);
+            return text(`Not yet — ${missing.join(", ")} still empty. The form is still open in the Retake window. Tell them again, with the link: “Open ${link} — there is a form waiting for ${list}. Type the demo account's values, press Save to .env, and tell me when it's done.” Then call secrets again.`);
+        }
+        try {
+            const r = await fetch(`${UI}/api/secrets/request`, { method: "POST", body: JSON.stringify({ names: missing, why }) });
+            if (!r.ok)
+                throw new Error(String(r.status));
+            await tell(`Waiting for you: ${missing.join(", ")} — a form is open in the window.`);
+            return text(`A form is now open in the Retake window. Tell the person this, including the link: “Open ${link} in your browser — a form is waiting there for ${list}. Use a demo account for the app (the result is a video). What you type is saved to one local file on your computer and never sent to me or anywhere else. Press Save to .env, then tell me it's done.” When they say done, call secrets again with the same names.`);
+        }
+        catch { /* fall through to the terminal route */ }
+    }
+    return text(`The Retake window is not open. Tell the person this, exactly: “Retake needs a demo account for this app. Either run \`retake ui\` and open ${link} — I'll ask you there — or run \`retake secret ${missing.join(" ")}\` in your Retake workspace folder and type the values into the terminal (hidden, kept on your machine). If the sign-in needs a code from your phone, SSO or a captcha, run \`retake signin demos/<name>.yaml\` instead and log in once by hand. Tell me when it's done.” Then call secrets again with the same names.`);
+});
+server.registerTool("ask", { description: "Ask the person ONE question and wait for the answer. Use only when genuinely blocked (which app, a choice between two things). Keep it one sentence, with the evidence. NEVER for passwords or tokens — that is what `secrets` is for.", inputSchema: { question: z.string() }, annotations: RETAKE_WRITE }, async ({ question }) => {
     try {
         const a = await waitForHuman("question", question);
         return text(`They answered: ${a}`);
@@ -249,7 +306,7 @@ server.registerTool("read_manifest", { description: "The YAML of a demo.", input
         return text(`no demo "${name}"`);
     return text(fs.readFileSync(manifestPath(name), "utf8"));
 });
-server.registerTool("write_manifest", { description: "Create or replace a demo's YAML. It is validated; errors come back instead of being written. Prefer `edit` for small changes to an existing demo.", inputSchema: { name: z.string(), yaml: z.string() }, annotations: RETAKE_WRITE }, async ({ name, yaml }) => {
+server.registerTool("write_manifest", { description: "Create or replace a demo's YAML. It is validated; errors come back instead of being written. Prefer `edit` for small changes to an existing demo. ALWAYS set `mode:`. `mode: demo` (the default) proves how something works and keeps everything but the product out of the frame — a client walkthrough, a PR clip, a bug repro, a lesson, anything for someone who already wants to know how it works. `mode: launch` presents the product in public (a launch, a post, an ad, a landing page) and is the ONLY mode where intro/outro cards, music, callouts and a branded ending belong — and a launch cut ends with THEIR product, never with Retake. Decide from the AUDIENCE, not the subject, and never upgrade a demo to a launch yourself: if you are unsure, use demo and ask.", inputSchema: { name: z.string(), yaml: z.string() }, annotations: RETAKE_WRITE }, async ({ name, yaml }) => {
     LAST_DEMO = name;
     if (!safe(name))
         return text("name must be kebab-case");
@@ -269,7 +326,7 @@ server.registerTool("write_manifest", { description: "Create or replace a demo's
     await tell(`Wrote demos/${name}.yaml — ${r.data.steps.length} steps, ${r.data.steps.filter((s) => s.action === "scene").length} scenes`);
     return text(`written: demos/${name}.yaml (${r.data.steps.length} steps)`);
 });
-server.registerTool("draft", { description: "Let Retake draft a manifest from a sentence: scouts the URL (and reads the project if given) and writes demos/<name>.yaml. Then dry-run it.", inputSchema: { name: z.string(), url: z.string().url(), describe: z.string(), project: z.string().optional() }, annotations: RETAKE_WRITE }, async ({ name, url, describe, project }) => {
+server.registerTool("draft", { description: "Let Retake draft a manifest from a sentence: scouts the URL (and reads the project if given) and writes demos/<name>.yaml. Then dry-run it. Drafts are always `mode: demo` — nothing in the frame but the product. If this is a launch or a post, say so afterwards with edit (see write_manifest for what launch mode allows).", inputSchema: { name: z.string(), url: z.string().url(), describe: z.string(), project: z.string().optional() }, annotations: RETAKE_WRITE }, async ({ name, url, describe, project }) => {
     LAST_DEMO = name;
     if (!safe(name))
         return text("name must be kebab-case");
@@ -284,7 +341,7 @@ server.registerTool("draft", { description: "Let Retake draft a manifest from a
     await tell(`Drafted demos/${name}.yaml — ${m.steps.length} steps, ${m.steps.filter((s) => s.action === "scene").length} scenes`);
     return text(`drafted demos/${name}.yaml (${m.steps.length} steps). Next: dry.\n\n${d.yaml}`);
 });
-server.registerTool("edit", { description: "Make small structured changes to a demo without rewriting it: captions, camera, holds, trim, waits, selectors, text; delete_step; insert_step {after, step:{action,…}} to add one step; set_step {step, value:{action,…}} to replace one. Steps are validated. Keeps comments. Returns what changed and whether it needs re-recording. Prefer this over write_manifest — one verb costs a line, a rewrite costs the file.", inputSchema: { name: z.string(), edits: z.array(z.object({ op: z.string() }).passthrough()) }, annotations: RETAKE_WRITE }, async ({ name, edits }) => {
+server.registerTool("edit", { description: "Make small structured changes to a demo without rewriting it: captions, camera, holds, trim, waits, selectors, text; delete_step; insert_step {after, step:{action,…}} to add one step; set_step {step, value:{action,…}} to replace one. Steps are validated. Keeps comments. Returns what changed and whether it needs re-recording. Prefer this over write_manifest — one verb costs a line, a rewrite costs the file. Turning a demo into a launch cut is edits too: set mode: launch, then intro/outro cards, one callout at most, music (their file), compressIdle. Never do that unasked — a demo is the default and a client walkthrough is a demo.", inputSchema: { name: z.string(), edits: z.array(z.object({ op: z.string() }).passthrough()) }, annotations: RETAKE_WRITE }, async ({ name, edits }) => {
     LAST_DEMO = name;
     if (!safe(name) || !fs.existsSync(manifestPath(name)))
         return text(`no demo "${name}"`);
@@ -303,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.", 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);
@@ -326,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");
@@ -409,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/pace.js

@@ -0,0 +1,99 @@
+/**
+ * Idle compression: the app's dead time, shortened at render.
+ *
+ * The take's own timeline is the honest signal — a waitFor or navigate step
+ * records exactly how long the viewer sat looking at nothing changing. Each
+ * such stretch is shown as ~keepSeconds: the real start at 1×, then the rest
+ * fast-forwarded. The author's `wait` steps are pacing and are never touched;
+ * scene holds stay exactly as written.
+ *
+ * Implemented as a pre-pass: the source video is re-cut into a warped source
+ * and every clock in the take (timeline, trim, duration) is remapped through
+ * the same piecewise-linear warp, so captions, camera keys and stills land
+ * where they always did — the rest of the render pipeline never knows.
+ */
+import path from "node:path";
+/** The app made the viewer wait: show the start, fast-forward the rest. */
+const WAITING = new Set(["waitFor", "navigate"]);
+/** Only stretches meaningfully longer than what we would keep are worth a cut. */
+const SLACK = 0.6;
+/** Typing is not dead time — it is the person speaking — so it keeps its
+    start AND its finish at real speed and only accelerates the middle. Every
+    keystroke is a round-trip to the browser (~57ms whatever `delay` says), so
+    a real sentence costs five seconds nobody watches. */
+const TYPE_BUDGET = 2.4;
+const TYPE_HEAD = 0.8;
+const TYPE_TAIL = 0.7;
+/** Plan the warp: 1× everywhere except the tail of each long app-wait and the
+    middle of each long typing run. */
+export function planIdle(take, keepSeconds) {
+    const segs = [];
+    for (const e of take.timeline) {
+        if (!e.ok)
+            continue;
+        const dur = e.end - e.start;
+        if (WAITING.has(e.action)) {
+            if (dur < keepSeconds + SLACK)
+                continue;
+            // Head at real speed, tail fast-forwarded into the remaining budget.
+            const head = keepSeconds * 0.6;
+            const shownTail = keepSeconds * 0.4;
+            segs.push({ from: e.start + head, to: e.end, rate: (dur - head) / shownTail });
+        }
+        else if (e.action === "type" || e.action === "fill") {
+            if (dur < TYPE_BUDGET + SLACK)
+                continue;
+            const middle = dur - TYPE_HEAD - TYPE_TAIL;
+            const shownMiddle = Math.max(0.3, TYPE_BUDGET - TYPE_HEAD - TYPE_TAIL);
+            segs.push({ from: e.start + TYPE_HEAD, to: e.end - TYPE_TAIL, rate: middle / shownMiddle });
+        }
+    }
+    return segs.sort((a, b) => a.from - b.from);
+}
+/** Source time → warped time. */
+export function warpTime(segs, t) {
+    let out = t;
+    for (const s of segs) {
+        if (t <= s.from)
+            break;
+        const inSeg = Math.min(t, s.to) - s.from;
+        out -= inSeg - inSeg / s.rate;
+    }
+    return out;
+}
+/** The take with every clock remapped. */
+export function warpTake(take, segs) {
+    const w = (t) => warpTime(segs, t);
+    return {
+        ...take,
+        trimBefore: w(take.trimBefore),
+        duration: w(take.duration),
+        timeline: take.timeline.map((e) => ({ ...e, start: w(e.start), end: w(e.end) })),
+    };
+}
+/** ffmpeg args to cut the raw source into the warped source. */
+export function warpFilterArgs(src, segs, duration, out) {
+    // Alternating 1× and fast segments covering [0, duration].
+    const pieces = [];
+    let cur = 0;
+    for (const s of segs) {
+        if (s.from > cur)
+            pieces.push({ a: cur, b: s.from, rate: 1 });
+        pieces.push({ a: s.from, b: s.to, rate: s.rate });
+        cur = s.to;
+    }
+    if (cur < duration)
+        pieces.push({ a: cur, b: duration, rate: 1 });
+    const graph = pieces.map((p, i) => `[0:v]trim=start=${p.a.toFixed(3)}:end=${p.b.toFixed(3)},setpts=(PTS-STARTPTS)/${p.rate.toFixed(4)}[s${i}]`).join(";") +
+        ";" + pieces.map((_, i) => `[s${i}]`).join("") + `concat=n=${pieces.length}:v=1:a=0[out]`;
+    return ["-i", path.resolve(src), "-filter_complex", graph, "-map", "[out]", "-an", out];
+}
+/** Human line for the proof log. */
+export function describeIdle(take, segs) {
+    return segs.map((s) => {
+        const e = take.timeline.find((x) => x.start <= s.from && x.end >= s.to);
+        const real = e ? e.end - e.start : s.to - s.from;
+        const shown = real - (s.to - s.from) + (s.to - s.from) / s.rate;
+        return `${e ? e.summary.slice(0, 52) : "wait"}: ${real.toFixed(1)}s shown as ${shown.toFixed(1)}s`;
+    });
+}

package/dist/presets.js

@@ -34,26 +34,26 @@ export const PRESETS = {
         gif: false, layout: "band", cameraZoom: 1.25,
         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: 950, 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: 40, bandHeight: 130,
+        cursorSize: 60, captionFontSize: 36, bandHeight: 120,
         encoder: "x264", master: true,
-        description: "A true 1080×1080 (page 1080×950 + 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: 1750, 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: 44, bandHeight: 170,
+        cursorSize: 60, captionFontSize: 40, bandHeight: 120,
         encoder: "x264", master: true,
-        description: "A true 1080×1920 (page 1080×1750 + 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",