retake-demos 0.3.0 → 0.4.1

package/AGENTS.md

@@ -14,6 +14,31 @@ clone of this repo the same commands run from source as `npm run retake -- …`.
 The MCP route is better than the CLI when it exists: `retake install` registers
 the tools and the skill with Claude Code, so the loop below becomes tool calls.
 
+## What a change costs
+
+Reaching for a new recording when a re-render would do is the one mistake
+that wastes real time. Almost nothing needs the camera twice.
+
+| You want to change | Do this | Cost |
+|---|---|---|
+| size, shape, format | `retake render <dir> --preset <other>` | seconds |
+| caption words, speed, zoom, cards, music | edit the manifest, `retake render` | seconds |
+| **where** a caption or still sits | `nudge: <ms>` on the scene, then render | seconds |
+| the ENDING of a demo | `retake run … --from <scene>` | the tail only |
+| one beat, while iterating | `retake run … --until <scene>` | the head only |
+| what the demo actually DOES | full `retake run` | the whole thing |
+
+`--from` runs the earlier steps at full speed and off camera so the app
+reaches the right state, then starts recording there. A seven-minute demo
+whose last third changed costs ninety seconds.
+
+Housekeeping, since outputs grow: `retake takes <dir>` lists the kept
+versions of a demo and `retake restore <dir> <id>` puts one back;
+`retake tidy` reports reclaimable disk and removes nothing without
+`--apply`. Neither ever touches a raw recording or a take.json — those are
+the only things a re-render cannot rebuild.
+
+
 ## Starting from nothing (the person pasted the repo link)
 
 ```
@@ -89,12 +114,36 @@ use Retake's drafting, or draft itself; both are fine.
 
 Full reference: `README.md` → "Demo-as-code". The short version:
 
+- **Wait for the RESULT, and know the three ways a bare selector lies.** It
+  resolves the moment the element exists, which is wrong when (a) the element
+  is the PREVIOUS action's banner still on screen — use
+  `{ action: waitFor, selector: ".landed", gone: true }` and wait for it to
+  leave; (b) the element is a shell that streams its text in — use
+  `minChars: 40`; (c) the element is there but still changing — use
+  `stableMs: 500`, which resolves when its subtree has been quiet that long.
+  Each of these cost a real take before it existed.
 - **Wait for results, not timers.** After any click that loads or computes
   something, `{ action: waitFor, selector: <thing that appears> }`. A fixed
   `wait` is for pacing only.
 - **Selectors must be unique.** Playwright runs strict: a selector matching two
   elements fails. Prefer ids, `data-testid`, `aria-label`, then
   `button:has-text("…")`; append `>> nth=0` only when duplicates are intended.
+- **`run --name <x>`** records into outputs/<x> without touching the
+  original; **`render <dir> --out <newdir>`** re-renders a copy and leaves
+  the published cut alone. Revising is never overwriting.
+- **A failed step writes `failed-step.png`** (full page, the exact moment)
+  and the failing URL into the log and take.json. Read the picture first.
+- **`manifest.used.yaml`** sits in every output — the exact manifest this
+  video came from, not whatever the file on disk says today.
+- **Size is a render-time choice.** One preset = one output size, always
+  (the caption band sits inside the canvas). Any take renders at any preset:
+  `retake render outputs/<name> --preset post-vertical`. Never re-record to
+  change a shape, and never set `viewport` — `validate` warns because it
+  makes one demo a different shape from the rest.
+- **`retake contact outputs/<name>`** — one timestamped grid of the whole
+  video. This is how you review a cut without pulling frames by hand, and
+  how you check a caption is still true in the middle of its own scene.
+  Launch cuts write `contact.png` automatically.
 - **The poster** is `thumbnail.png`. `outputs.thumbnail: { scene: <label> }` picks the scene; the person can override it in the window from any frame, a generated cover, or their own image (`POST /api/cover/<name>`). Launch mode also writes `cover.png` (the title card) and `cover-titled.png` (a real frame with the title on it) as candidates. Do not re-render to change a poster.
 - **`mode:`** — `demo` (default) proves the interaction: nothing in the frame
   but the product. A CLIENT WALKTHROUGH IS A DEMO. `launch` presents the
@@ -211,3 +260,18 @@ recording-relevant changed, and the UI's one button works this out for you.
   adds ~8s to every take and competes with the app being recorded. Ladder:
   `draft` while fixing, `preview-fast` to check final framing, a post preset to
   ship. Never ship a draft.
+
+## Every release gets a note a non-developer can read
+
+`site/releases.json` is the one list of what shipped. The landing page and the
+Retake window both read it — there is no second copy to update.
+
+When a release changes anything a person can see, add an entry: a version, a
+date, a headline, and a few lines. Write them for the person using Retake, not
+for whoever wrote the code. Name no files. Name no flag they will not type. Do
+not write "refactor", "regression", "schema" or "pipeline". If a line only
+makes sense to someone who has read the source, it is not a release note —
+it belongs in the commit message, which is where that audience already is.
+
+Good: "You choose the cover image. Click any frame to make it the one people
+see first." Bad: "Poster selection is now persisted via a marker file."

package/README.md

@@ -65,6 +65,7 @@ outputs/<name>/
   cover.png       launch mode: the title card, settled
   cover-titled.png launch mode: a real frame with the title over it
   proof-log.md    result, shot list, every step's timing, pass/fail, what was on screen when it failed
+  contact.png     launch cuts: one timestamped grid of the whole video (`retake contact`)
   take.json       the raw timeline the renderer reads
 ```
 
@@ -118,9 +119,11 @@ outputs:
 
 The full template is [`demos/example.yaml`](demos/example.yaml); `retake init` copies it into a new workspace.
 
-**Steps** — `click`, `type`, `fill`, `hover`, `drag`, `scroll`, `keyboard`, `navigate`, `wait`, `waitFor`, `evaluate`, `upload`, `download`, `screenshot`, `scene`. Every step takes `pauseAfter`, `waitFor`, `timeout`, `secret`. Targets are a selector, or a point — `{x, y}` or `{selector, dx, dy}` — for canvases and SVG editors. `${VAR}` expands from `.env` and fails loudly when unset.
+**Steps** — `click`, `type`, `fill`, `select`, `hover`, `drag`, `scroll`, `keyboard`, `navigate`, `wait`, `waitFor`, `evaluate`, `upload`, `download`, `screenshot`, `scene`. Every step takes `pauseAfter`, `waitFor`, `timeout`, `secret`. Targets are a selector, or a point — `{x, y}` or `{selector, dx, dy}` — for canvases and SVG editors. `${VAR}` expands from `.env` and fails loudly when unset.
 
-**Scenes** are the spine: `{ action: scene, label, caption }` at each beat. They take their timestamps from the actual run, so captions land on the frames they describe even when the app took 3 seconds this time and 11 the last.
+**Waits** take three modifiers, because a bare selector resolves the moment the element exists: `gone: true` waits for it to leave (the previous action's banner), `minChars: 40` waits for it to hold real text (a streamed reply), `stableMs: 500` waits for its subtree to stop changing.
+
+**Scenes** are the spine: `{ action: scene, label, caption }` at each beat. They take their timestamps from the actual run, so captions land on the frames they describe even when the app took 3 seconds this time and 11 the last. **Labels must be unique** — `thumbnail`, `until`, the stills and the proof log all address scenes by label, so two scenes called the same thing make every one of those ambiguous. `validate` rejects it.
 
 **Two kinds of take.** `mode: demo` (the default) proves how something works — a client walkthrough, a PR clip, a lesson — and keeps everything but the product out of the frame. `mode: launch` presents the product in public and may carry a title card, music, emphasis and a branded ending. `validate` warns if a demo is carrying launch furniture. **The launch cut.** `compressIdle: true` shows the app's long waits as ~1.5 s each (your own pacing `wait`s are never touched); `voiceover: true` reads the captions aloud (edge-tts, `pipx install edge-tts` once); `typing: brisk` makes typed text land fast with the pauses carrying the meaning. All render-time except typing. **Music.** `music: track.mp3` (or `{ file, gainDb, fadeOutMs }`) mixes a bed under the video at render time, looped or trimmed to fit and faded out at the end. Bring your own track — it ships inside your video, so it must be one you may use (CC0 or licensed). **Cards and callouts.** `intro:`/`outro:` add a title card in Retake's own look — rendered at render time, so changing a word is a re-render, and the intro's settled frame is written as `cover.png`, the poster. `{ action: callout, selector, label, ms }` draws an animated ring and label around an element while the take holds — recorded coordinates, drawn at render, moving with the camera. Sparingly: the captions carry the story.
 
@@ -132,15 +135,15 @@ Think in the publishing format, not the browser window.
 
 | Preset | Video | Page area | For |
 |---|---:|---:|---|
-| `draft` | 960×592 | 960×540 | iterating — the finals' layout at a quarter of the pixels, fastest |
-| `preview-fast` | 1920×1180 | 1920×1080 | checking timing and framing, hardware-encoded |
-| `post-landscape` *(default)* | 1920×1180 | 1920×1080 | the general-purpose demo, plus a CRF-14 master |
-| `post-square` | 1080×1080 | 1080×960 | feeds — a true square |
-| `post-vertical` | 1080×1920 | 1080×1800 | shorts and reels — a true 9:16 |
-| `docs-gif` | 1440×970 | 1440×900 | README and docs GIFs |
-| `master` | 1920×1180 | 1920×1080 | archive, CRF 12 |
-
-**The video is the page area plus the caption band, and the band fits the captions.** On landscape presets the page keeps its full 1920×1080 and the band under it is sized to the longest caption — about 100 px for one line, 160 for two, one height for the whole take (video sizes above are for one-line captions). The captions never cover the app. Square and vertical keep a fixed 120 px band inside the canvas, because a feed that wants 1:1 or 9:16 will letterbox anything else. `captions: false` → no band at all. A manifest's `viewport` replaces the page area and the video follows it, so a 1240×1080 viewport gives a 1240×1230 video. `retake presets` prints this table, and `retake validate` tells you the exact size of the video a manifest will produce before you record it.
+| `draft` | 960×540 | 960×464 | iterating — the finals' layout at a quarter of the pixels, fastest |
+| `preview-fast` | 1920×1080 | 1920×930 | checking timing and framing, hardware-encoded |
+| `post-landscape` *(default)* | 1920×1080 | 1920×930 | the general-purpose demo, plus a CRF-14 master |
+| `post-square` | 1080×1080 | 1080×960 | feeds |
+| `post-vertical` | 1080×1920 | 1080×1800 | shorts and reels |
+| `docs-gif` | 1440×900 | 1440×800 | README and docs GIFs |
+| `master` | 1920×1080 | 1920×930 | archive, CRF 12 |
+
+**One preset, one size — and size is not recorded.** The caption band sits inside the canvas, so `post-landscape` is always exactly 1920×1080 and two demos of the same app are never different shapes. Better still, the shape is decided at render: the take is fitted into whichever canvas you ask for, so `retake render outputs/x --preset post-vertical` gives you a 9:16 cut of a demo you recorded landscape — seconds, no browser, no re-record. Setting `viewport` in a manifest overrides the page and `validate` warns, because that is how one demo ends up a different shape from the rest.
 
 **Page scale** is what makes it crisp: the page lays out as if the viewport were smaller and every glyph is drawn at 2×, so 1080p text reads on a phone. **Camera** is still by default — a calm demo reads as real. `camera: auto` eases toward whatever the demo just touched, at render time, clamped so it can never crop the thing it points at; per scene: `camera: { focus: ".result", zoom: 1.3 }`. Zoom is something you ask for after seeing a take, not something that happens to you. Captions, camera, speed, trim, format and layout are all render-time: change them and `retake render` takes seconds, never touches the browser.
 

package/dist/captions.js

@@ -39,18 +39,17 @@ export function captionLines(texts, width, fontSize) {
 }
 /** The band's height for this take: fitted to the text, or the preset's
     fixed band when the canvas is the constraint. 0 when captions are off. */
-export function bandHeightFor(q, width, texts, pageHeight = q.height) {
+export function bandHeightFor(q, captionTexts) {
     if (q.layout !== "band" && q.layout !== "card")
         return 0;
     if (!q.captions)
         return 0;
-    // Fixed canvas: whatever the page turned out to be (an older take may have
-    // a different page height), the band fills the rest so the canvas is exact.
-    if (q.bandFit === "fill")
-        return Math.max(0, q.height + q.bandHeight - pageHeight);
-    const size = q.captions.fontSize;
-    const lines = captionLines(texts, width, size);
-    // glyph height ≈ 1.05 × size; line spacing 0.25 × size; breathing room above and below.
-    const h = size * 1.05 * lines + size * 0.25 * (lines - 1) + size * 1.1;
-    return Math.ceil(h / 2) * 2;
+    // A band with nothing to draw in it is an empty strip on the video: when
+    // the texts are known and none exist, the page gets the whole frame.
+    if (captionTexts && !captionTexts.some((t) => t && t.trim()))
+        return 0;
+    // Fixed per preset. The default page is the canvas minus this, so the
+    // finished video is exactly the preset's size — every take the same shape,
+    // and no player letterboxing it.
+    return q.bandHeight;
 }

package/dist/cards.js

@@ -32,6 +32,10 @@ function cardHtml(w, h, theme, title, subtitle, ms) {
   T.textContent = ${JSON.stringify(title)}; S.textContent = ${JSON.stringify(subtitle ?? "")};
   const DUR = ${ms}, FADE = Math.min(420, DUR * 0.22), OUT = Math.min(320, DUR * 0.18);
   const ez = (t) => (${ease});
+  // The window in which nothing moves. The rule keeps growing until FADE*2 —
+  // well past the title's own fade — so this cannot be guessed from the
+  // outside, and the renderer asks the template rather than assuming.
+  window.__still = [FADE * 2, DUR - OUT];
   window.__seek = (ms) => {
     const a = ez(ms / FADE);                          // entrance
     const o = ez((DUR - ms) / OUT);                   // exit
@@ -59,6 +63,8 @@ function calloutHtml(w, h, box, label, ms, fontSize, ink) {
   if (tag) tag.textContent = ${JSON.stringify(label ?? "")};
   const DUR = ${ms}, IN = Math.min(360, DUR * 0.25), OUT = Math.min(280, DUR * 0.2);
   const ez = (t) => (${ease});
+  // The tag lands last, at IN*1.6 — later than the ring's own entrance.
+  window.__still = [IN * 1.6, DUR - OUT];
   window.__seek = (ms) => {
     const a = ez(ms / IN), o = ez((DUR - ms) / OUT), v = Math.min(a, o);
     ring.style.opacity = v;
@@ -68,19 +74,49 @@ function calloutHtml(w, h, box, label, ms, fontSize, ink) {
   };
   </script>`;
 }
-/** Screenshot a __seek()-driven page at every frame; returns the frame dir. */
+/** Screenshot a __seek()-driven page at every frame; returns the frame dir.
+ *
+ * A card only MOVES at its ends: it eases in, holds, eases out. Photographing
+ * the held middle was paying ~250ms a frame for an unchanging picture — 30s of
+ * a launch cut's render, for two cards. So the held frames are copies of the
+ * settled one, at a millisecond each.
+ *
+ * Which frames those are is the template's business, not this function's. It
+ * publishes `__still = [from, to]`, because the answer is not guessable from
+ * outside: the card's rule keeps growing until twice the title's fade, and a
+ * renderer that assumed otherwise froze it half-drawn. A template with no
+ * `__still` gets every frame shot — the slow path is the safe default. */
 async function renderFrames(html, w, h, ms, fps, transparent) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "retake-frames-"));
     const browser = await chromium.launch();
-    const page = await browser.newPage({ viewport: { width: w, height: h } });
-    await page.setContent(html, { waitUntil: "load" });
-    const frames = Math.max(2, Math.round((ms / 1000) * fps));
-    for (let i = 0; i < frames; i++) {
-        await page.evaluate((t) => window.__seek(t), (i / fps) * 1000);
-        await page.screenshot({ path: path.join(dir, `f${String(i).padStart(5, "0")}.png`), omitBackground: transparent });
+    try {
+        const page = await browser.newPage({ viewport: { width: w, height: h } });
+        await page.setContent(html, { waitUntil: "load" });
+        const frames = Math.max(2, Math.round((ms / 1000) * fps));
+        const still = await page.evaluate(() => window.__still);
+        // One frame of margin at each end, so rounding never lands the copied
+        // frame on a moment the template was still moving.
+        const margin = 1000 / fps;
+        const held = (t) => !!still && still[1] - still[0] > 2 * margin && t * 1000 >= still[0] + margin && t * 1000 <= still[1] - margin;
+        let settled = "";
+        for (let i = 0; i < frames; i++) {
+            const t = i / fps;
+            const file = path.join(dir, `f${String(i).padStart(5, "0")}.png`);
+            if (!held(t) || !settled) {
+                await page.evaluate((ms2) => window.__seek(ms2), t * 1000);
+                await page.screenshot({ path: file, omitBackground: transparent });
+                if (held(t) && !settled)
+                    settled = file;
+            }
+            else {
+                fs.copyFileSync(settled, file);
+            }
+        }
+        return dir;
+    }
+    finally {
+        await browser.close();
     }
-    await browser.close();
-    return dir;
 }
 /** A title card as an H.264 segment at the final canvas size, plus (for the
     intro) the settled middle frame as cover.png — the poster. */
@@ -125,10 +161,17 @@ export async function renderTitledCover(ffmpeg, frame, out, spec, w, h, theme) {
   <div class="shot"></div><div class="veil"></div>
   <div class="txt"><p class="t">${escapeHtml(spec.title)}</p><div class="r"></div>${spec.subtitle ? `<p class="s">${escapeHtml(spec.subtitle)}</p>` : ""}</div>`;
     const browser = await chromium.launch();
-    const page = await browser.newPage({ viewport: { width: w, height: h } });
-    await page.setContent(html, { waitUntil: "load" });
-    await page.screenshot({ path: out });
-    await browser.close();
-    return out;
+    try {
+        const page = await browser.newPage({ viewport: { width: w, height: h } });
+        await page.setContent(html, { waitUntil: "load" });
+        await page.screenshot({ path: out });
+        return out;
+    }
+    finally {
+        await browser.close();
+    }
 }
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** @internal The card template, exported so test/cards.test.ts can prove the
+    frame-skipping is byte-identical to shooting every frame. */
+export const __test_cardHtml = cardHtml;

package/dist/cli.js

@@ -24,10 +24,11 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { Command } from "commander";
-import { loadManifest, warnings } from "./manifest.js";
-import { acquireLock, captureHash, record, releaseLock } from "./record.js";
+import { loadManifest, resolve, warnings } from "./manifest.js";
+import { acquireLock, captureHash, EXPENSIVE_TAKE_SECONDS, keepPrevious, keptTakes, lastCaptureSeconds, record, releaseLock, restoreKept, restorePrevious, stashPrevious } from "./record.js";
 import { check, render } from "./render.js";
 import { presetNames } from "./presets.js";
+import { applyTidy, mb, planTidy } from "./tidy.js";
 import { PKG_ROOT, VERSION, entry } from "./paths.js";
 import { SECRET_NAME, writeEnvFile } from "./env.js";
 // The manifest may reference ${VARS}; load .env before any command reads one.
@@ -42,6 +43,35 @@ catch { /* .env is optional */ }
 const program = new Command();
 program.name("retake").description("Rerun the demo instead of re-recording it.").version(VERSION);
 const say = (l) => process.stdout.write(l + "\n");
+/** Said once, before the camera rolls, when a take is long enough that the
+    cheaper ways of getting the same answer are worth knowing about.
+
+    A person who has already spent eight full-quality captures learning the
+    shape of a demo has paid for something `--preset draft` would have given
+    them in a quarter of the time. The tools existed; nothing said so at the
+    moment the cost was being incurred. This is that moment. */
+export function costHints(m, outDir, opts) {
+    const q = resolve(m);
+    // Only says a number it has actually seen. A demo nobody has recorded yet
+    // gets no estimate, because the honest one does not exist: step count
+    // predicts capture time with ~33% error over 31 real takes, and a confident
+    // wrong number is worse than none.
+    const last = lastCaptureSeconds(outDir);
+    if (last === null || last < EXPENSIVE_TAKE_SECONDS)
+        return [];
+    const draft = q.name === "draft" || opts.preset === "draft";
+    const mins = (n) => (n >= 120 ? `${Math.round(n / 60)} min` : `${Math.round(n)}s`);
+    const out = [`ℹ the last take of this demo took ${mins(last)} to record.`];
+    const ways = [];
+    if (!draft)
+        ways.push("`--preset draft` records the same layout and timing at a quarter of the pixels — use it while the demo is still changing, then run the real preset once");
+    if (!opts.until)
+        ways.push("`--until <scene>` stops after one beat, so fixing the ending does not re-record the beginning");
+    ways.push("captions, speed, zoom, cards, poster and SIZE are all re-renders — `retake render outputs/" + m.name + " --preset <other>` never needs the camera again");
+    for (const w of ways)
+        out.push(`  · ${w}`);
+    return out;
+}
 program
     .command("run")
     .argument("<manifest>", "demo .yaml / .json")
@@ -54,15 +84,30 @@ program
     .option("--reuse", "reuse the last raw recording if nothing that shapes it changed (re-render only)", false)
     .option("--gif", "also produce a GIF (overrides the manifest)", false)
     .option("--until <scene>", "record up to the end of this scene, then stop (iterate on one beat without paying for the whole take)")
+    .option("--from <scene>", "start the take at this scene — earlier steps still run, at full speed and off camera, so a demo whose ENDING changed stops costing its beginning")
+    .option("--name <name>", "write to outputs/<name> instead of the manifest's name — revise a cut without overwriting the published one")
     .action(async (file, opts) => {
     const loaded = loadManifest(file);
-    let manifest = opts.preset ? { ...loaded.manifest, preset: opts.preset } : loaded.manifest;
+    // Asking for a preset means asking for its SHAPE. A manifest that pins its
+    // own `viewport` used to win silently, so `--preset draft` recorded at
+    // full size and saved nothing — on the one demo where iterating cheaply
+    // mattered most, and with a failing "matches draft" check as the only
+    // hint. An explicit --preset now drops the pin.
+    let manifest = loaded.manifest;
+    if (opts.preset) {
+        const { viewport: pinned, ...rest } = loaded.manifest;
+        manifest = { ...rest, preset: opts.preset };
+        if (pinned)
+            say(`ℹ --preset ${opts.preset} overrides this manifest's viewport (${pinned.width}×${pinned.height}); recording at the preset's own size`);
+    }
     if (opts.gif)
         manifest = { ...manifest, outputs: { ...manifest.outputs, gif: true } };
     if (opts.preset && !presetNames().includes(opts.preset))
         throw new Error(`unknown preset ${opts.preset} — one of ${presetNames().join(", ")}`);
     const dir = loaded.dir;
-    const outDir = path.resolve(opts.out, manifest.name);
+    if (opts.name && !/^[a-z0-9-]+$/.test(opts.name))
+        throw new Error("--name must be kebab-case");
+    const outDir = path.resolve(opts.out, opts.name ?? manifest.name);
     acquireLock(outDir); // throws if another run owns this folder
     // Reuse: same capture hash + raw video present → skip the browser.
     let take;
@@ -77,21 +122,26 @@ program
     }
     for (const w of warnings(manifest))
         say(`⚠ ${w}`);
+    if (!take)
+        for (const l of costHints(manifest, outDir, opts))
+            say(l);
     say(`▶ ${manifest.title ?? manifest.name} → ${path.relative(process.cwd(), outDir)}${take ? " · reusing last recording" : ""}`);
     say(`[stage] capture ${take ? "skip" : "start"}`);
     const t0 = Date.now();
     if (!take) {
-        // Wipe everything except the lock.
-        for (const f of fs.readdirSync(outDir))
-            if (f !== ".retake-lock")
-                fs.rmSync(path.join(outDir, f), { recursive: true, force: true });
+        // The previous take is moved aside, not deleted: if this recording dies
+        // the person still has the one that worked. See stashPrevious.
+        stashPrevious(outDir);
         try {
-            take = await record(manifest, { until: opts.until, outDir, headed: opts.headed, skipSeed: opts.skipSeed, manifestDir: dir, log: say, locked: true });
+            take = await record(manifest, { until: opts.until, from: opts.from, outDir, headed: opts.headed, skipSeed: opts.skipSeed, manifestDir: dir, log: say, locked: true });
         }
         catch (e) {
+            if (restorePrevious(outDir))
+                say("↩ recording failed — your previous take has been put back");
             releaseLock(outDir);
             throw e;
         }
+        keepPrevious(outDir, say);
     }
     say(`■ take done in ${((Date.now() - t0) / 1000).toFixed(1)}s · ${take.ok ? "all steps ok" : "SOME STEPS FAILED"} · ${take.video ?? "no video"}`);
     try {
@@ -120,6 +170,83 @@ program
     if (!take.ok || !take.video)
         process.exitCode = 2;
 });
+program
+    .command("takes")
+    .description("the kept versions of a demo — previous recordings you can go back to")
+    .argument("<dir>", "an outputs/<name> dir")
+    .action((dir) => {
+    const kept = keptTakes(path.resolve(dir));
+    if (!kept.length) {
+        say(`no kept versions of ${path.basename(dir)} — the current take is the only one.`);
+        return;
+    }
+    say(`kept versions of ${path.basename(dir)} (newest first). Only the recording is stored; everything else re-renders.`);
+    for (const k of kept)
+        say(`  ${k.id}  ${k.seconds}s · ${k.steps} steps · ${k.mb} MB`);
+    say(`\nGo back to one:  retake restore ${path.relative(process.cwd(), dir)} <id>`);
+});
+program
+    .command("restore")
+    .description("make a kept version the current take again, and re-render it")
+    .argument("<dir>", "an outputs/<name> dir")
+    .argument("<id>", "a version id from `retake takes`")
+    .argument("[manifest]", "manifest to render with (default demos/<name>.yaml)")
+    .action(async (dir, id, manifestFile) => {
+    const outDir = path.resolve(dir);
+    const name = path.basename(outDir);
+    acquireLock(outDir);
+    try {
+        if (!restoreKept(outDir, id))
+            throw new Error(`no version "${id}" of ${name} — \`retake takes ${path.relative(process.cwd(), outDir)}\` lists them`);
+        say(`restored ${id} as the current take`);
+        const file = manifestFile ?? path.join("demos", `${name}.yaml`);
+        if (!fs.existsSync(file)) {
+            say(`re-render it with:  retake render ${path.relative(process.cwd(), outDir)} <manifest>`);
+            return;
+        }
+        const { manifest } = loadManifest(file);
+        const take = JSON.parse(fs.readFileSync(path.join(outDir, "take.json"), "utf8"));
+        const a = await render(manifest, take, outDir, { log: (l) => { if (!l.startsWith("$"))
+                say(l); } });
+        for (const f of [a.master, a.mp4, a.thumbnail, a.proofLog])
+            if (f)
+                say(`✓ ${path.relative(process.cwd(), f)}`);
+    }
+    finally {
+        releaseLock(outDir);
+    }
+});
+program
+    .command("tidy")
+    .description("reclaim disk from outputs — shows what it would remove; nothing goes without --apply")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--apply", "actually remove them", false)
+    .option("--deep", "also remove demo.mp4 (still re-renderable, but it is the deliverable)", false)
+    .option("--orphans", "also remove whole folders whose manifest is gone", false)
+    .action((opts) => {
+    const root = path.resolve(opts.out);
+    const plan = planTidy(root, { deep: opts.deep, orphans: opts.orphans, demosDir: path.resolve("demos") });
+    if (!plan.bytes) {
+        say(`nothing to reclaim in ${path.relative(process.cwd(), root)} — ${mb(plan.keptBytes)} of recordings and deliverables, all of it worth keeping.`);
+        return;
+    }
+    for (const g of plan.groups) {
+        say(`${mb(g.bytes).padStart(8)}  ${g.what} — ${g.why}`);
+        for (const f of g.files.slice(0, 4))
+            say(`          ${path.relative(root, f)}`);
+        if (g.files.length > 4)
+            say(`          … and ${g.files.length - 4} more`);
+    }
+    say(`${mb(plan.bytes).padStart(8)}  TOTAL reclaimable · ${mb(plan.keptBytes)} kept (raw recordings and take.json — the only things a re-render cannot rebuild)`);
+    if (!opts.apply) {
+        say(`\nNothing removed. Run again with --apply.`);
+        if (!opts.deep)
+            say(`--deep also drops demo.mp4 · --orphans also drops folders whose manifest is gone`);
+        return;
+    }
+    const freed = applyTidy(plan);
+    say(`\nfreed ${mb(freed)}. Every demo can still be rebuilt with \`retake render outputs/<name>\`.`);
+});
 program
     .command("render")
     .argument("<dir>", "an outputs/<name> dir containing take.json")
@@ -128,9 +255,39 @@ program
     .option("--scene <label>", "render just one scene to scene-<label>.mp4 (fast, hardware encode)")
     .option("--gif", "also produce a GIF", false)
     .option("--force", "ignore the render cache", false)
+    .option("--out <dir>", "write the render into a NEW directory, leaving the original untouched")
     .action(async (dir, manifestFile, opts) => {
     const takePath = path.join(dir, "take.json");
     const take = JSON.parse(fs.readFileSync(takePath, "utf8"));
+    // Revising a published cut should not destroy it. Copy the take (and the
+    // raw video it points at) into the new directory and render there.
+    if (opts.out) {
+        const dest = path.resolve(opts.out);
+        fs.mkdirSync(dest, { recursive: true });
+        for (const f of fs.readdirSync(path.resolve(dir))) {
+            if (/^(demo|master)\.mp4$|^demo\.gif$|\.png$|^proof-log\.md$|^facts\.json$|^stills$/.test(f))
+                continue;
+            const from = path.join(path.resolve(dir), f);
+            if (fs.statSync(from).isDirectory())
+                continue;
+            fs.copyFileSync(from, path.join(dest, f));
+        }
+        if (take.video) {
+            // The take points at its raw video by absolute path; a copied
+            // directory has to point at its own copy or it renders the original.
+            const base = path.basename(take.video);
+            const copied = path.join(dest, base);
+            if (fs.existsSync(copied))
+                take.video = copied;
+            else {
+                fs.copyFileSync(take.video, copied);
+                take.video = copied;
+            }
+            fs.writeFileSync(path.join(dest, "take.json"), JSON.stringify(take, null, 2));
+        }
+        say(`▶ rendering into ${path.relative(process.cwd(), dest)} — ${path.relative(process.cwd(), path.resolve(dir))} is untouched`);
+        dir = dest;
+    }
     const name = path.basename(path.resolve(dir));
     const mf = manifestFile ?? guessManifest(name);
     const loaded = loadManifest(mf);
@@ -412,10 +569,20 @@ program
     say(`Sign in there — codes, SSO, captcha, whatever it asks. When you can see the signed-in app, come back here and press Enter.`);
     say(`(Nothing is recorded. Only the session is kept, in ${path.relative(process.cwd(), statePath)}, good for ${manifest.auth.maxAgeHours}h.)`);
     await new Promise((ok) => { process.stdin.resume(); process.stdin.once("data", () => ok()); });
-    fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    await context.storageState({ path: statePath });
-    fs.chmodSync(statePath, 0o600);
-    await browser.close();
+    try {
+        fs.mkdirSync(path.dirname(statePath), { recursive: true });
+        await context.storageState({ path: statePath });
+        fs.chmodSync(statePath, 0o600);
+    }
+    catch (e) {
+        // Closing the window instead of pressing Enter is the usual way here:
+        // say so plainly rather than showing a stack, and leave no orphan.
+        const why = page.isClosed() ? "the browser window was closed before the session could be saved" : String(e.message ?? e);
+        throw new Error(`Could not save the session — ${why}.\nRun \`retake signin ${file}\` again, and this time leave the window open and press Enter here.`);
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
     say(`✓ session saved → ${path.relative(process.cwd(), statePath)}. Takes of ${manifest.name} now start signed in; run this again when it goes stale.`);
     process.exit(0);
 });
@@ -471,6 +638,17 @@ program
         say(`· ${i.title}${i.length ? ` (${i.length})` : ""}`);
     say(`✓ ${path.relative(process.cwd(), file)}`);
 });
+program
+    .command("contact")
+    .argument("<dir>", "an outputs/<name> dir")
+    .option("--every <seconds>", "seconds between frames", "2")
+    .option("-w, --width <px>", "width of each cell", "420")
+    .description("one timestamped contact sheet of the finished video — the artifact for signing a cut off")
+    .action(async (dir, opts) => {
+    const { contactSheet } = await import("./render.js");
+    const out = contactSheet(path.resolve(dir), Number(opts.every), Number(opts.width), say);
+    say(`✓ ${path.relative(process.cwd(), out)}`);
+});
 program
     .command("gif")
     .argument("<dir>", "an outputs/<name> dir")
@@ -490,12 +668,11 @@ program
     const { bandHeightFor } = await import("./captions.js");
     say(`${"preset".padEnd(16)} ${"video".padEnd(12)} ${"page".padEnd(11)} fps  layout`);
     for (const p of Object.values(PRESETS)) {
-        const q = { captions: { fontSize: p.captionFontSize }, layout: p.layout, bandHeight: p.bandHeight, bandFit: p.bandFit, height: p.height };
-        const one = bandHeightFor(q, p.width, ["one line"]), two = bandHeightFor(q, p.width, ["a caption long enough to wrap ".repeat(6)]);
-        const video = p.layout === "card" ? `${p.width}×${p.height}` : p.layout !== "band" ? `${p.width}×${p.height}` : one === two ? `${p.width}×${p.height + one}` : `${p.width}×${p.height + one}–${p.height + two}`;
-        say(`${p.name.padEnd(16)} ${video.padEnd(12)} ${String(p.width + "×" + p.height).padEnd(11)} ${String(p.fps).padEnd(4)} ${p.layout.padEnd(5)} — ${p.description}`);
+        const band = p.layout === "band" || p.layout === "card" ? p.bandHeight : 0;
+        const page = `${p.width}×${p.height - band}`;
+        say(`${p.name.padEnd(16)} ${String(p.width + "×" + p.height).padEnd(12)} ${page.padEnd(11)} ${String(p.fps).padEnd(4)} ${p.layout.padEnd(5)} — ${p.description}`);
     }
-    say(`\nvideo = page + caption band. On landscape presets the band fits the captions (one line, or two); square and vertical keep a fixed band so the canvas stays exact. A manifest's \`viewport\` replaces the page size (the video follows it). \`captions: false\` → no band.`);
+    say(`\nOne preset, one size: the caption band sits inside the canvas, so every take at a preset comes out identical and no player letterboxes it. A manifest's \`viewport\` overrides the page (validate warns). \`captions: false\` → the page fills the frame.`);
 });
 program
     .command("validate")
@@ -508,10 +685,10 @@ program
     // here rather than letting it surprise someone after a two-minute take.
     const { bandHeightFor } = await import("./captions.js");
     const outW = q.layout === "card" ? q.width : q.viewport.width;
-    const band = bandHeightFor(q, outW, manifest.steps.flatMap((s) => (s.action === "scene" && s.caption ? [s.caption] : [])), q.viewport.height);
+    const band = bandHeightFor(q, manifest.steps.flatMap((s) => (s.action === "scene" && s.caption ? [s.caption] : [])));
     const outH = (q.layout === "card" ? q.height : q.viewport.height) + (q.layout === "band" ? band : 0);
     say(`ok: ${manifest.name} · ${manifest.steps.length} steps · ${manifest.steps.filter((s) => s.action === "scene").length} scenes`);
-    say(`   ${q.name} · video ${outW}×${outH}${q.layout === "band" ? (band ? ` (page ${q.viewport.width}×${q.viewport.height} + ${band}px caption band${q.bandFit === "text" ? ", sized to the captions" : ""})` : " (captions off, no band)") : ""} @ ${q.fps}fps${q.gif ? ` · gif ${q.gif.width}px` : ""}`);
+    say(`   ${q.name} · video ${outW}×${outH}${q.layout === "band" ? (band ? ` (page ${q.viewport.width}×${q.viewport.height} + a ${band}px caption band)` : " (captions off — the page fills the frame)") : ""} @ ${q.fps}fps${q.gif ? ` · gif ${q.gif.width}px` : ""}`);
     for (const w of warnings(manifest))
         say(`⚠ ${w}`);
 });

package/dist/describe.js

@@ -313,10 +313,11 @@ const SCHEMA_DOC = `
 Manifest YAML fields:
   name (kebab-case), title, url, mode: demo, preset: post-landscape, waitForSelector (selector present when page is ready),
   camera: static, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
-  Do NOT set viewport, cursor, chrome, background, fps, crf or captions — the preset handles quality.
+  NEVER set viewport. The preset decides the size and every take at a preset comes out identical; setting viewport makes this demo a different shape from every other one and players letterbox it. Same for cursor, chrome, background, fps, crf and captions — the preset handles all of it.
   Always set mode: demo — this is a demo, so nothing goes in the frame but the product. Never emit intro or outro cards, music, callouts or voiceover: those belong to mode: launch, which only a person can ask for.
 Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: scene, label, caption, camera?: static | {focus: selector, zoom: 1.25}}   a named beat; caption is burned in until the next scene (under 60 chars). Set camera: static on every scene unless the thing being shown is genuinely too small to read at full frame — a calm, still demo reads as more real than a zooming one. If the person asked for zooms (or stillness), that wins.
+  {action: select, selector, value}   choose in a <select> — value or the visible label, whichever the page uses
   {action: wait, ms}
   {action: click, selector, zoom: 1.3}   zoom is optional
   {action: type, selector, text, delay: 30}