retake-demos 0.2.2 → 0.4.0

package/dist/cards.js

@@ -0,0 +1,177 @@
+/**
+ * Motion pieces rendered from HTML — title cards and callout overlays.
+ *
+ * Chromium is the motion renderer: a template page defines `__seek(tMs)`
+ * which lays the frame out for that exact moment, and Node steps through
+ * the timeline one screenshot per video frame. Deterministic to the pixel —
+ * the same take renders the same twice — and styled with the same theme as
+ * the caption band, so cards look like Retake, not like a slide deck.
+ *
+ * All of it is render-time: change a title, `retake render`, seconds.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chromium } from "playwright";
+import { execFileSync } from "node:child_process";
+const AMBER = "#e8b04b";
+const ease = "t<0?0:t>1?1:t*t*(3-2*t)"; // smoothstep, in the page
+function cardHtml(w, h, theme, title, subtitle, ms) {
+    const titleSize = Math.round(Math.min(w * 0.055, h * 0.14));
+    const subSize = Math.round(titleSize * 0.4);
+    return `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:${theme.background}}
+  .wrap{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"SF Pro Display","Helvetica Neue",Arial,sans-serif}
+  .title{font-size:${titleSize}px;font-weight:700;letter-spacing:-.02em;color:${theme.ink};opacity:0}
+  .rule{height:${Math.max(3, Math.round(titleSize * 0.07))}px;background:${AMBER};border-radius:99px;margin:${Math.round(titleSize * 0.35)}px 0;width:0}
+  .sub{font-size:${subSize}px;color:${theme.ink};opacity:0;font-weight:400}
+  </style>
+  <div class="wrap"><div class="title"></div><div class="rule"></div><div class="sub"></div></div>
+  <script>
+  const T = document.querySelector(".title"), R = document.querySelector(".rule"), S = document.querySelector(".sub");
+  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
+    const v = Math.min(a, o);
+    T.style.opacity = v; T.style.transform = "translateY(" + (1 - a) * 14 + "px)";
+    R.style.width = (ez((ms - FADE * 0.4) / (FADE * 1.6)) * ${Math.round(titleSize * 3.2)}) * Math.min(1, o + 0.0) + "px";
+    R.style.opacity = Math.min(1, o + 0.2);
+    S.style.opacity = v; S.style.transform = "translateY(" + (1 - a) * 10 + "px)";
+    return true;
+  };
+  </script>`;
+}
+function calloutHtml(w, h, box, label, ms, fontSize, ink) {
+    const pad = 10;
+    const r = { x: box.x - pad, y: box.y - pad, w: box.width + 2 * pad, h: box.height + 2 * pad };
+    const below = r.y + r.h + 18 + fontSize * 2 < h; // label under the ring when there is room
+    return `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:transparent}
+  .ring{position:absolute;left:${r.x}px;top:${r.y}px;width:${r.w}px;height:${r.h}px;border:3px solid ${AMBER};border-radius:14px;box-shadow:0 0 0 3px rgba(0,0,0,.06);opacity:0}
+  .tag{position:absolute;left:${Math.max(8, Math.min(w - 8, r.x))}px;top:${below ? r.y + r.h + 12 : Math.max(8, r.y - fontSize * 1.9 - 12)}px;background:${ink};color:#f4f4ef;font-family:-apple-system,BlinkMacSystemFont,"SF Pro Text",Arial,sans-serif;font-size:${fontSize}px;font-weight:600;line-height:1;padding:${Math.round(fontSize * 0.55)}px ${Math.round(fontSize * 0.8)}px;border-radius:10px;opacity:0;max-width:${Math.round(w * 0.6)}px;white-space:nowrap}
+  </style>
+  <div class="ring"></div>${label ? '<div class="tag"></div>' : ""}
+  <script>
+  const ring = document.querySelector(".ring"), tag = document.querySelector(".tag");
+  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;
+    ring.style.transform = "scale(" + (1.12 - 0.12 * a) + ")";
+    if (tag) { tag.style.opacity = Math.min(ez((ms - IN * 0.6) / IN), o); tag.style.transform = "translateY(" + (1 - a) * 6 + "px)"; }
+    return true;
+  };
+  </script>`;
+}
+/** 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();
+    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();
+    }
+}
+/** 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. */
+export async function renderCard(ffmpeg, outDir, kind, spec, w, h, fps, theme) {
+    const dir = await renderFrames(cardHtml(w, h, theme, spec.title, spec.subtitle, spec.ms), w, h, spec.ms, fps, false);
+    const mp4 = path.join(outDir, `.card-${kind}.mp4`);
+    execFileSync(ffmpeg, ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "f%05d.png"), "-c:v", "libx264", "-crf", "17", "-preset", "veryfast", "-pix_fmt", "yuv420p", mp4], { stdio: "inherit" });
+    let cover;
+    if (kind === "intro") {
+        const frames = fs.readdirSync(dir).sort();
+        const settled = frames[Math.min(frames.length - 1, Math.round(frames.length * 0.55))];
+        cover = path.join(outDir, "cover.png");
+        fs.copyFileSync(path.join(dir, settled), cover);
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { mp4, cover };
+}
+/** A callout as a VP9 segment with alpha, overlaid onto the take at render. */
+export async function renderCalloutOverlay(ffmpeg, outDir, index, c, w, h, fps, fontSize, ink) {
+    const dir = await renderFrames(calloutHtml(w, h, c.box, c.label, c.ms, fontSize, ink), w, h, c.ms, fps, true);
+    const webm = path.join(outDir, `.callout-${index}.webm`);
+    execFileSync(ffmpeg, ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "f%05d.png"), "-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "0", "-crf", "28", webm], { stdio: "inherit" });
+    fs.rmSync(dir, { recursive: true, force: true });
+    return webm;
+}
+/** A cover built from a real frame of the video with the title laid over it —
+    a screenshot plus a few words, which is what actually stops a scroll. Not
+    a skin of the centred card: the product is the picture. */
+export async function renderTitledCover(ffmpeg, frame, out, spec, w, h, theme) {
+    const b64 = fs.readFileSync(frame).toString("base64");
+    const titleSize = Math.round(Math.min(w * 0.045, h * 0.1));
+    const subSize = Math.round(titleSize * 0.42);
+    const html = `<!doctype html><meta charset="utf-8"><style>
+  html,body{margin:0;width:${w}px;height:${h}px;overflow:hidden;background:${theme.background};font-family:-apple-system,BlinkMacSystemFont,"SF Pro Display","Helvetica Neue",Arial,sans-serif}
+  .shot{position:absolute;inset:0;background:url(data:image/png;base64,${b64}) center/cover no-repeat}
+  .veil{position:absolute;inset:0;background:linear-gradient(to bottom, rgba(0,0,0,0) 38%, rgba(0,0,0,.14) 58%, ${theme.background} 78%)}
+  .txt{position:absolute;left:0;right:0;bottom:${Math.round(h * 0.055)}px;text-align:center;padding:0 ${Math.round(w * 0.08)}px}
+  .t{font-size:${titleSize}px;font-weight:700;letter-spacing:-.02em;color:${theme.ink};margin:0}
+  .r{height:${Math.max(3, Math.round(titleSize * 0.08))}px;width:${Math.round(titleSize * 2.6)}px;background:${AMBER};border-radius:99px;margin:${Math.round(titleSize * 0.3)}px auto}
+  .s{font-size:${subSize}px;color:${theme.ink};margin:0;opacity:.75}
+  </style>
+  <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();
+    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,11 +24,13 @@ 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.
 // (`describe` and the UI used to do this individually, so a plain `run` from
 // the terminal silently saw empty values — which is how a whole take can fail
@@ -41,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")
@@ -53,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;
@@ -76,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 {
@@ -119,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")
@@ -127,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);
@@ -316,6 +474,118 @@ program
     say(`Keep ${o.ui} open while it works — the plan, the run and the video appear there.`);
     say("Retake will not start your app from outside its own window unless you add RETAKE_ALLOW_START=1 above.");
 });
+/** Read one line from stdin. On a terminal, `hide` switches to raw mode so the
+    characters are not echoed; on a pipe, lines are simply consumed in order. */
+let stdinBuf = "";
+function promptLine(label, hide) {
+    process.stdout.write(label);
+    const tty = !!process.stdin.isTTY;
+    const raw = hide && tty;
+    if (raw)
+        process.stdin.setRawMode(true);
+    process.stdin.resume();
+    return new Promise((resolve) => {
+        const finish = (line) => {
+            process.stdin.off("data", onData);
+            if (raw)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+            if (raw)
+                process.stdout.write("\n");
+            resolve(line.trim());
+        };
+        const take = () => {
+            const i = stdinBuf.search(/\r|\n/);
+            if (i < 0)
+                return false;
+            const line = stdinBuf.slice(0, i);
+            stdinBuf = stdinBuf.slice(i + 1).replace(/^\n/, "");
+            finish(line);
+            return true;
+        };
+        const onData = (d) => {
+            const sIn = d.toString();
+            if (raw) {
+                for (const ch of sIn) {
+                    if (ch === "\u0003") {
+                        process.stdout.write("\n");
+                        process.exit(130);
+                    }
+                    if (ch === "\u007f" || ch === "\b") {
+                        stdinBuf = stdinBuf.slice(0, -1);
+                        continue;
+                    }
+                    stdinBuf += ch;
+                }
+            }
+            else
+                stdinBuf += sIn;
+            take();
+        };
+        if (take())
+            return;
+        process.stdin.on("data", onData);
+    });
+}
+program
+    .command("secret")
+    .description("put a demo account into this workspace's .env without opening the file — typed here, hidden, kept on this machine only")
+    .argument("<names...>", "variable names, e.g. APP_USER APP_PASSWORD APP_TOTP_SECRET")
+    .action(async (names) => {
+    const bad = names.filter((n) => !SECRET_NAME.test(n));
+    if (bad.length)
+        throw new Error(`names look like APP_PASSWORD — not: ${bad.join(", ")}`);
+    say(`Stays on this computer: written to ${path.join(process.cwd(), ".env")} (readable by you only), never sent anywhere, never shown to an agent. Use a demo account.`);
+    const values = {};
+    for (const n of names) {
+        const v = await promptLine(`${n}${/PASS|SECRET|TOKEN|KEY|PIN|OTP/.test(n) ? " (hidden)" : ""}: `, /PASS|SECRET|TOKEN|KEY|PIN|OTP/.test(n));
+        if (v)
+            values[n] = v;
+    }
+    const set = writeEnvFile(process.cwd(), values);
+    if (!set.length) {
+        say("nothing saved");
+        return;
+    }
+    say(`✓ ${set.join(", ")} saved to ${path.join(process.cwd(), ".env")} (mode 600). A manifest references them as \${NAME} with secret: true — the values never go on camera.`);
+});
+program
+    .command("signin")
+    .description("sign in by hand once — 2FA, SSO, captcha, anything — and keep the session for every later take")
+    .argument("<manifest>", "the demo whose auth.storageState should be saved")
+    .action(async (file) => {
+    const { manifest, dir } = loadManifest(file);
+    if (!manifest.auth?.storageState)
+        throw new Error(`${file} has no auth.storageState — add:\n  auth:\n    storageState: .auth/${manifest.name}.json\n    maxAgeHours: 24`);
+    const { resolve, expandEnv } = await import("./manifest.js");
+    const { chromium } = await import("playwright");
+    const q = resolve(manifest);
+    const statePath = path.resolve(dir, expandEnv(manifest.auth.storageState));
+    const browser = await chromium.launch({ headless: false });
+    const context = await browser.newContext({ viewport: q.viewport });
+    const page = await context.newPage();
+    await page.goto(manifest.url, { waitUntil: "domcontentloaded" }).catch(() => { });
+    say(`A browser is open at ${manifest.url}.`);
+    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()); });
+    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);
+});
 program
     .command("dry")
     .description("run the manifest with no camera and report what would fail")
@@ -368,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")
@@ -384,12 +665,14 @@ program
     .description("list quality presets")
     .action(async () => {
     const { PRESETS } = await import("./presets.js");
-    say(`${"preset".padEnd(16)} ${"video".padEnd(11)} ${"page".padEnd(11)} fps  layout`);
+    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 video = p.layout === "card" ? `${p.width}×${p.height}` : `${p.width}×${p.height + (p.layout === "band" ? p.bandHeight : 0)}`;
-        say(`${p.name.padEnd(16)} ${video.padEnd(11)} ${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. A manifest's \`viewport\` replaces the page size (the video follows it).`);
+    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")
@@ -400,10 +683,12 @@ program
     const q = resolve(manifest);
     // The video is the page area plus the caption band, so say the real number
     // 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 outH = (q.layout === "card" ? q.height : q.viewport.height) + (q.layout === "band" ? q.bandHeight : 0);
+    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" ? ` (page ${q.viewport.width}×${q.viewport.height} + ${q.bandHeight}px caption 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}`);
 });