retake-demos 0.2.2 → 0.4.0

package/dist/record.js

@@ -11,7 +11,7 @@ import fs from "node:fs";
 import os from "node:os";
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { chromium } from "playwright";
 import { recordPage, moveCursorToPoint } from "testreel";
 import { expandEnv, resolve } from "./manifest.js";
@@ -33,6 +33,83 @@ export function captureHash(m) {
     h.update(JSON.stringify({ url: m.url, viewport: q.viewport, scale: q.scale, cursor: q.cursor, wait: m.waitForSelector, reduced: m.reducedMotion, auth: m.auth, seed: m.seed, stub: m.stub, setup: m.setup, steps, speed: m.speed, camera: m.camera, colorScheme: m.colorScheme }));
     return h.digest("hex").slice(0, 12);
 }
+/** The session a take should start from, and whether it is still good.
+    Shared so `dry` starts signed in exactly when `run` would — a dry run
+    against a logged-out app "proving" a manifest is a wasted take waiting
+    to happen. */
+export function authState(m, manifestDir) {
+    const p = m.auth ? path.resolve(manifestDir, expandEnv(m.auth.storageState)) : null;
+    const fresh = !!p && fs.existsSync(p) && (Date.now() - fs.statSync(p).mtimeMs) / 3.6e6 < (m.auth?.maxAgeHours ?? 72);
+    return { path: p, fresh };
+}
+/** Everything injected into a page before it loads.
+ *
+ * ONE function, called by both the recorder and the dry run, because the
+ * expensive failure in this tool is a green `dry` followed by a failed `run`
+ * — and every knob only one of them applied was a way for dry to prove a
+ * different app than run would film. A knob added here reaches both by
+ * construction; a knob added to one call site is the bug this replaces. */
+export async function applyPageSetup(context, m, q) {
+    // The page lays out at `scale`× (CSS zoom): the app sees a smaller viewport
+    // and renders crisp into the full canvas. Coordinates testreel/Playwright
+    // see are already video pixels, so cursor and clicks line up.
+    // Scale via a <style> tag, not an inline attribute: React hydration diffs
+    // element attributes against the server HTML, so style.zoom on <html> made
+    // every React app report a hydration mismatch — with a dev badge in shot.
+    if (q.scale !== 1)
+        await context.addInitScript(`document.addEventListener("DOMContentLoaded",()=>{const st=document.createElement("style");st.textContent="html{zoom:${q.scale}}";document.head.appendChild(st)})`);
+    // One page is what gets recorded, so keep the flow in it: window.open
+    // navigates in place, and target=_blank is stripped as it appears. A demo
+    // that spawned a second tab used to simply lose its subject.
+    if (m.keepInTab) {
+        await context.addInitScript(`
+      (() => {
+        const orig = window.open;
+        window.open = function (url) { if (url) { location.href = String(url); return window; } return orig.apply(window, arguments); };
+        const strip = (root) => { for (const a of root.querySelectorAll ? root.querySelectorAll('a[target="_blank"]') : []) a.removeAttribute('target'); };
+        addEventListener('DOMContentLoaded', () => {
+          strip(document);
+          new MutationObserver((ms) => { for (const m of ms) for (const n of m.addedNodes) if (n.nodeType === 1) strip(n); }).observe(document.documentElement, { childList: true, subtree: true });
+        });
+      })();
+    `);
+    }
+    // Dev servers decorate themselves — Next's issues badge, Vite's error
+    // overlay, webpack's. None of that belongs in a product video, and no
+    // manifest should have to know about it.
+    await context.addInitScript(`document.addEventListener("DOMContentLoaded",()=>{const st=document.createElement("style");st.textContent="nextjs-portal,#__next-build-watcher,vite-error-overlay,#webpack-dev-server-client-overlay,#react-refresh-overlay{display:none!important}";document.head.appendChild(st)})`);
+}
+/** The manifest's own readiness gate, with the wrong-app diagnosis attached.
+    Both the recorder and `dry` wait on it: a dry run that starts stepping
+    before the app has booted reports selector failures that are really a
+    race, and it should refuse a wrong build for the same reason run does. */
+export async function gateOnApp(page, m, outDir) {
+    if (m.waitForSelector) {
+        try {
+            await page.waitForSelector(m.waitForSelector, { timeout: 20_000 });
+        }
+        catch {
+            // Almost never a bad selector — almost always the wrong app on the
+            // port: a stale dev server, a different build, a login wall, a
+            // marketing page. Say THAT, with what is actually there.
+            let saw = "", title = "";
+            try {
+                title = await page.title();
+                saw = (await page.evaluate(() => document.body?.innerText ?? "")).replace(/\s+/g, " ").trim().slice(0, 200);
+            }
+            catch { /* page gone */ }
+            try {
+                await page.screenshot({ path: path.join(outDir, "not-the-app.png"), fullPage: true });
+            }
+            catch { /* ignore */ }
+            throw new Error(`the app at ${m.url} is not what this manifest expects: waited 20s for \`${m.waitForSelector}\` and it never appeared.\n` +
+                `  page title: ${title || "(none)"}\n` +
+                `  on screen: ${saw ? `“${saw}”` : "(nothing)"}\n` +
+                `  picture: ${path.relative(process.cwd(), path.join(outDir, "not-the-app.png"))}\n` +
+                `  Usually the port is serving a different build or mode — restart the app and check the URL in a browser before re-running.`);
+        }
+    }
+}
 const noop = () => { };
 /** The take's time ceiling: the manifest's own maxSeconds, else ≈10s per
     step plus explicit waits, never under 240s or over an hour. Used by the
@@ -43,6 +120,24 @@ export function capSecondsFor(m) {
     const waits = m.steps.reduce((n, st) => n + (st.action === "wait" ? st.ms / 1000 : 0) + (st.pauseAfter ?? 0) / 1000, 0);
     return Math.min(3600, Math.max(240, Math.round(m.steps.length * 10 + waits)));
 }
+/** What the LAST take of this demo actually cost, in seconds of wall clock.
+ *
+ * Measured, because estimating it does not work. Fitted against 31 real takes,
+ * step count predicts capture time with ~33% mean error and is wrong in both
+ * directions by 3x: an 11-step demo of a slow remote app took 221s while a
+ * 105-step local one took 116s. What the app does between the steps is the
+ * whole cost, and a manifest cannot know that. The previous take can. */
+export function lastCaptureSeconds(outDir) {
+    try {
+        const t = JSON.parse(fs.readFileSync(path.join(outDir, "take.json"), "utf8"));
+        return typeof t.captureSec === "number" && t.captureSec > 0 ? t.captureSec : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Long enough that a person should see a draft before the full take is spent. */
+export const EXPENSIVE_TAKE_SECONDS = 150;
 /** Roughly how many times the cursor will move on camera. */
 /** Cursor moves per take. testreel's nested-if overlay died at ~45 (ffmpeg's
     parser stops at 98 levels); scripts/patch-testreel.mjs flattens those
@@ -187,10 +282,13 @@ export async function record(m, opts) {
     const size = { ...q.viewport };
     // A saved session (auth.storageState) means the login already happened on an
     // earlier run: load it and the setup login steps can be skipped.
-    const statePath = m.auth ? path.resolve(opts.manifestDir, expandEnv(m.auth.storageState)) : null;
-    const stateFresh = !!statePath && fs.existsSync(statePath) && (Date.now() - fs.statSync(statePath).mtimeMs) / 3.6e6 < (m.auth?.maxAgeHours ?? 72);
+    const { path: statePath, fresh: stateFresh } = authState(m, opts.manifestDir);
     if (statePath)
         log(stateFresh ? `auth: reusing session ${path.relative(process.cwd(), statePath)}` : `auth: no fresh session — running setup to sign in`);
+    // No session and nothing that could create one: stop here rather than record
+    // a logged-out take that passes every check.
+    if (statePath && !stateFresh && !(m.auth?.setup?.length))
+        throw new Error(`no fresh session at ${path.relative(process.cwd(), statePath)} and no auth.setup to sign in with — run \`retake signin ${path.relative(process.cwd(), path.join(opts.manifestDir, m.name + ".yaml"))}\` and log in once by hand, or add the sign-in steps under auth.setup`);
     const context = await browser.newContext({
         viewport: size,
         colorScheme: m.colorScheme,
@@ -198,52 +296,33 @@ export async function record(m, opts) {
         recordVideo: { dir: rawDir, size },
         ...(stateFresh && statePath ? { storageState: statePath } : {}),
     });
-    // The page lays out at `scale`× (CSS zoom): the app sees a smaller viewport
-    // and renders crisp into the full canvas. Coordinates testreel/Playwright
-    // see are already video pixels, so cursor and clicks line up.
-    // Scale via a <style> tag, not an inline attribute: React hydration diffs
-    // element attributes against the server HTML, so style.zoom on <html> made
-    // every React app report a hydration mismatch — with a dev badge in shot.
-    if (q.scale !== 1)
-        await context.addInitScript(`document.addEventListener("DOMContentLoaded",()=>{const st=document.createElement("style");st.textContent="html{zoom:${q.scale}}";document.head.appendChild(st)})`);
-    // One page is what gets recorded, so keep the flow in it: window.open
-    // navigates in place, and target=_blank is stripped as it appears. A demo
-    // that spawned a second tab used to simply lose its subject.
-    if (m.keepInTab) {
-        await context.addInitScript(`
-      (() => {
-        const orig = window.open;
-        window.open = function (url) { if (url) { location.href = String(url); return window; } return orig.apply(window, arguments); };
-        const strip = (root) => { for (const a of root.querySelectorAll ? root.querySelectorAll('a[target="_blank"]') : []) a.removeAttribute('target'); };
-        addEventListener('DOMContentLoaded', () => {
-          strip(document);
-          new MutationObserver((ms) => { for (const m of ms) for (const n of m.addedNodes) if (n.nodeType === 1) strip(n); }).observe(document.documentElement, { childList: true, subtree: true });
-        });
-      })();
-    `);
-    }
-    // Dev servers decorate themselves — Next's issues badge, Vite's error
-    // overlay, webpack's. None of that belongs in a product video, and no
-    // manifest should have to know about it.
-    await context.addInitScript(`document.addEventListener("DOMContentLoaded",()=>{const st=document.createElement("style");st.textContent="nextjs-portal,#__next-build-watcher,vite-error-overlay,#webpack-dev-server-client-overlay,#react-refresh-overlay{display:none!important}";document.head.appendChild(st)})`);
+    await applyPageSetup(context, m, q);
     // Canned responses live in a map the route handler reads on every request, so
     // a `stub` step mid-demo swaps the answer without re-registering anything.
     // Keyed by method+url: a POST stub must not replace the GET stub on the same
     // path — they are different answers to different questions.
     const stubs = new Map();
     const stubbed = [];
+    // How many requests each stub actually answered. A stub that answered NONE
+    // is the quiet failure: the take passes, the screen looks plausible, and it
+    // is showing live data the demo was written to replace. Counting is free;
+    // not counting cost someone a morning of reading screenshots.
+    const stubHits = new Map();
     const armStub = async (d) => {
         const key = `${d.method ?? "ANY"} ${d.url}`;
         const fresh = !stubs.has(key);
         stubs.set(key, d);
         if (!stubbed.includes(key))
             stubbed.push(key);
+        if (!stubHits.has(key))
+            stubHits.set(key, 0);
         if (!fresh)
             return;
         await context.route(d.url, async (route, request) => {
             const cur = stubs.get(key);
             if (cur.method && request.method().toUpperCase() !== cur.method.toUpperCase())
                 return route.fallback();
+            stubHits.set(key, (stubHits.get(key) ?? 0) + 1);
             const body = cur.json !== undefined
                 ? JSON.stringify(cur.json)
                 : cur.from
@@ -256,8 +335,11 @@ export async function record(m, opts) {
     const ctx = { outDir: opts.outDir, manifestDir: opts.manifestDir, downloads: [], stub: armStub };
     let ok = true;
     let partial;
+    const pageErrors = [];
     let video;
     let screenshots = [];
+    let layoutWidth;
+    let contentWidth;
     let t0 = Date.now();
     let setupEnd = t0;
     let endMs = t0;
@@ -273,19 +355,37 @@ export async function record(m, opts) {
         const page = await context.newPage();
         if (process.env.RETAKE_PAGE_CONSOLE)
             page.on("console", (msg) => log(`  [page] ${msg.text().slice(0, 200)}`));
+        // What the app itself said went wrong, with the moment it said it. A take
+        // can pass every step and still END on "This page couldn\u2019t load" —
+        // one did, and only frame-by-frame review caught it. Timestamped so
+        // `check` can ask the only question that matters: was it still broken
+        // when the video stopped?
+        page.on("pageerror", (e) => pageErrors.push({ at: sec(Date.now() - t0), text: String(e.message ?? e).slice(0, 300) }));
+        page.on("console", (msg) => { if (msg.type() === "error")
+            pageErrors.push({ at: sec(Date.now() - t0), text: msg.text().slice(0, 300) }); });
         // --- setup phase (still inside the video; trimmed later by `trimBefore`) ---
         // Document first; idle only if it comes quickly. Busy public sites never
         // go network-idle, and the manifest's waitForSelector is the real gate.
         await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 60000 });
         await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
+        // Two different widths, and the difference is the whole trap.
+        //
+        // Measured, on a real navigation: under `html{zoom:2}` a width:100%
+        // element gets 960 CSS px of LAYOUT SPACE while media queries still
+        // report 1920. So a responsive app does not switch to its mobile layout —
+        // it renders its DESKTOP layout squeezed into half the room, which is
+        // why the result looks wrong in a way no breakpoint explains.
+        //
+        // Both numbers go in the proof log, because either one alone misleads.
+        layoutWidth = await page.evaluate(() => document.documentElement.clientWidth).catch(() => undefined);
+        contentWidth = Math.round((q.viewport.width) / q.scale);
         if (!opts.skipSeed) {
             for (const s of m.seed) {
                 if (s.kind === "evaluate")
                     await runEvaluateSeed(page, s, opts.manifestDir, log);
             }
         }
-        if (m.waitForSelector)
-            await page.waitForSelector(m.waitForSelector, { timeout: 20_000 });
+        await gateOnApp(page, m, opts.outDir);
         // Playwright's video begins at the first *painted* frame, not at newPage().
         // On a dev server that can be seconds later; if testreel's cursor overlay is
         // told the wrong start it draws every cursor move that many seconds late.
@@ -332,6 +432,10 @@ export async function record(m, opts) {
         if (statePath && !stateFresh && authOk) {
             fs.mkdirSync(path.dirname(statePath), { recursive: true });
             await context.storageState({ path: statePath });
+            try {
+                fs.chmodSync(statePath, 0o600);
+            }
+            catch { /* windows */ }
             log(`auth: saved session → ${path.relative(process.cwd(), statePath)}`);
         }
         else if (statePath && !stateFresh) {
@@ -346,7 +450,24 @@ export async function record(m, opts) {
         if (q.cursor !== false && moves > CURSOR_MOVE_LIMIT)
             log(`cursor: ~${moves} cursor moves — past ~${CURSOR_MOVE_LIMIT} the cursor filter no longer fits in one ffmpeg argument and the overlay may be MISSING. Split the demo (a viewer wants chapters anyway), or set cursor: false to be honest about it.`);
         let pastUntil = false;
+        // --from <scene>: everything before it still runs (the app must reach that
+        // state) but at full speed, and `trimBefore` moves to the moment it lands,
+        // so none of it is in the finished video. Re-recording only the tail.
+        let fastForward = !!opts.from && m.steps.some((st) => st.action === "scene" && st.label === opts.from);
+        if (opts.from && !fastForward)
+            throw new Error(`--from "${opts.from}": no scene with that label. Scenes here: ${m.steps.filter((st) => st.action === "scene").map((st) => st.label).join(", ") || "(none)"}`);
+        if (fastForward)
+            log(`fast-forwarding to scene "${opts.from}" — the steps before it run but are not in the video`);
         for (const [i, step] of m.steps.entries()) {
+            if (fastForward && step.action === "scene" && step.label === opts.from) {
+                fastForward = false;
+                setupEnd = Date.now(); // the take starts HERE
+                // A fragment, like --until: say so, or every check that judges a
+                // whole video (length, scene count) fails a take that is working
+                // exactly as asked.
+                partial = `recorded from scene "${opts.from}" (from) — a fragment for iteration, not a finished cut`;
+                log(`▶ recording from "${opts.from}"`);
+            }
             // --until <scene>: record that scene in full, stop at the next one.
             if (opts.until && step.action === "scene") {
                 if (pastUntil) {
@@ -357,6 +478,7 @@ export async function record(m, opts) {
                 if (step.label === opts.until)
                     pastUntil = true;
             }
+            ctx.fast = fastForward;
             const start = Date.now();
             const entry = {
                 index: i,
@@ -366,6 +488,15 @@ export async function record(m, opts) {
                 end: 0,
                 ok: true,
             };
+            if (step.action === "callout") {
+                // Resolve the box now; the ring itself is drawn at render time.
+                const target = step.selector ?? step.at;
+                const c = await resolvePoint(page, target, step.timeout ?? 10_000);
+                const half = typeof target === "string" || !("x" in target)
+                    ? await page.locator((typeof target === "string" ? target : target.selector)).first().evaluate((el) => { const r = el.getBoundingClientRect(); return { w: r.width, h: r.height }; }).catch(() => ({ w: 48, h: 48 }))
+                    : { w: 48, h: 48 };
+                entry.callout = { box: { x: c.x - half.w / 2, y: c.y - half.h / 2, width: half.w, height: half.h }, label: step.label, ms: step.ms };
+            }
             if (step.action === "scene") {
                 entry.label = step.label;
                 entry.caption = step.caption;
@@ -387,7 +518,27 @@ export async function record(m, opts) {
                     entry.screen = (await page.evaluate(() => document.body?.innerText ?? "")).replace(/\s+/g, " ").trim().slice(0, 240);
                 }
                 catch { /* page gone */ }
+                // A picture of the moment it broke. Every diagnosis anyone has made
+                // of a failed take came from pulling frames out of the video by hand;
+                // this is that, for free, at the exact instant.
+                let shot = "";
+                try {
+                    shot = path.join(opts.outDir, "failed-step.png");
+                    await page.screenshot({ path: shot, fullPage: true });
+                    entry.screenshot = "failed-step.png";
+                }
+                catch {
+                    shot = "";
+                }
+                try {
+                    entry.url = page.url();
+                }
+                catch { /* page gone */ }
                 log(`     ✗ ${entry.error}${entry.screen ? ` — on screen: “${entry.screen.slice(0, 120)}”` : ""}`);
+                if (entry.url)
+                    log(`       url: ${entry.url}`);
+                if (shot)
+                    log(`       picture of the failure: ${path.relative(process.cwd(), shot)}`);
                 entry.end = sec(Date.now() - t0);
                 timeline.push(entry);
                 if (m.onFail === "stop") {
@@ -481,17 +632,29 @@ export async function record(m, opts) {
     // calibrated to within ~0.2s of the first video frame on a warm route). The
     // real file length is authoritative for the end.
     const trimBefore = sec(setupEnd - t0);
-    const duration = video ? videoDuration(video) : sec(endMs - t0);
+    // The recording keeps rolling while the browser is torn down, so the raw
+    // video always has a tail of nothing after the last step. The take ends
+    // where the demo ends (plus a breath), never where the recorder stopped —
+    // otherwise every video ships with dead seconds at the end.
+    const GRACE = 0.4;
+    const videoSec = video ? videoDuration(video) : sec(endMs - t0);
     const last = timeline.at(-1);
-    if (last && Math.abs(duration - last.end) > 3) {
-        log(`note: video is ${duration.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
+    const duration = last && videoSec > last.end + GRACE + 0.1 ? last.end + GRACE : videoSec;
+    if (last && duration < videoSec - 0.05)
+        log(`trim: ${(videoSec - duration).toFixed(1)}s of tail after the last step dropped`);
+    if (last && videoSec < last.end - 0.5) {
+        log(`note: video is ${videoSec.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
     }
     const finishedAt = new Date().toISOString();
     const take = {
         video, screenshots, timeline, duration, startedAt, finishedAt, ok, trimBefore, partial,
         quality: { preset: q.name, width: q.viewport.width, height: q.viewport.height, scale: q.scale, fps: q.fps },
+        layoutWidth,
+        contentWidth,
+        pageErrors,
         downloads: ctx.downloads,
         stubbed,
+        stubHits: Object.fromEntries(stubHits),
         captureHash: captureHash(m),
         captureSec: Math.round((Date.parse(finishedAt) - Date.parse(startedAt)) / 100) / 10,
     };
@@ -537,6 +700,147 @@ async function resolveCamera(page, m, q, step, index) {
         return undefined;
     }
 }
+/** A previous take is not rubbish until a new one exists to replace it — and
+ *  even then it might have been the better one.
+ *
+ * Two separate problems, one mechanism.
+ *
+ * 1. `run` used to delete the output folder and THEN start the browser, so any
+ *    failure in between — a crash, a Ctrl-C, a closed pipe, a dev server
+ *    serving the wrong app — left the person with neither the new take nor the
+ *    old one. Losing a good recording to a FAILED attempt is the most
+ *    expensive thing this tool can do to someone.
+ * 2. Even a successful re-record threw the previous take away, and you cannot
+ *    tell whether the new one is better until you have watched it.
+ *
+ * So old artifacts move aside before recording and, on success, become
+ * history rather than rubbish.
+ *
+ * History is deliberately cheap. Measured across 37 real demos: 506 MB total,
+ * of which 345 MB is DERIVED — master.mp4, demo.mp4, stills, thumbnails all
+ * re-render from take.json plus the raw recording in seconds. So a kept
+ * version stores only those two. The largest demo here costs 41 MB a version
+ * instead of 139 MB, and stays fully recoverable.
+ */
+const STASH = ".previous";
+const HISTORY = ".history";
+/** How many previous takes of a demo to keep, and the ceiling on their total
+    size. Small on purpose: this runs on machines whose disks fill up. */
+export const KEEP_TAKES = 2;
+export const HISTORY_BUDGET_MB = 400;
+/** Put back a stash left by a run that died. Call before anything else. */
+export function restorePrevious(outDir) {
+    const stash = path.join(outDir, STASH);
+    if (!fs.existsSync(stash))
+        return false;
+    for (const f of fs.readdirSync(stash)) {
+        const to = path.join(outDir, f);
+        fs.rmSync(to, { recursive: true, force: true });
+        fs.renameSync(path.join(stash, f), to);
+    }
+    fs.rmSync(stash, { recursive: true, force: true });
+    return true;
+}
+/** Move the current artifacts aside, keeping the lock and the chosen poster. */
+export function stashPrevious(outDir) {
+    fs.mkdirSync(outDir, { recursive: true });
+    restorePrevious(outDir); // a stash from an earlier crash comes back first
+    const keep = new Set([".retake-lock", STASH, HISTORY, ".poster"]);
+    const files = fs.readdirSync(outDir).filter((f) => !keep.has(f));
+    if (!files.length)
+        return;
+    const stash = path.join(outDir, STASH);
+    fs.mkdirSync(stash, { recursive: true });
+    for (const f of files)
+        fs.renameSync(path.join(outDir, f), path.join(stash, f));
+}
+/** The kept versions of this demo, newest first. */
+export function keptTakes(outDir) {
+    const root = path.join(outDir, HISTORY);
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    for (const id of fs.readdirSync(root).sort().reverse()) {
+        const dir = path.join(root, id);
+        try {
+            const t = JSON.parse(fs.readFileSync(path.join(dir, "take.json"), "utf8"));
+            const vid = fs.readdirSync(dir).find((f) => f.endsWith(".webm"));
+            let bytes = 0;
+            for (const f of fs.readdirSync(dir))
+                bytes += fs.statSync(path.join(dir, f)).size;
+            out.push({
+                id, at: t.finishedAt ?? id, seconds: Math.round(t.duration - t.trimBefore),
+                steps: t.timeline?.length ?? 0, ok: !!t.ok, mb: Math.round(bytes / 1e5) / 10,
+                video: vid ? path.join(dir, vid) : null,
+            });
+        }
+        catch { /* an unreadable version is not worth keeping */ }
+    }
+    return out;
+}
+/** The new take is real. Keep the old one as a version — recording only, since
+    everything else re-renders — and prune to the budget. */
+export function keepPrevious(outDir, log) {
+    const stash = path.join(outDir, STASH);
+    if (!fs.existsSync(stash))
+        return;
+    try {
+        const takeFile = path.join(stash, "take.json");
+        const raw = fs.readdirSync(stash).find((f) => f.endsWith(".webm"));
+        const prev = fs.existsSync(takeFile) ? JSON.parse(fs.readFileSync(takeFile, "utf8")) : null;
+        // A failed take is not worth a version: nobody wants to go back to it.
+        if (prev?.ok && raw) {
+            const id = (prev.finishedAt ?? new Date().toISOString()).replace(/[:.]/g, "-").slice(0, 19);
+            const dir = path.join(outDir, HISTORY, id);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.renameSync(takeFile, path.join(dir, "take.json"));
+            fs.renameSync(path.join(stash, raw), path.join(dir, raw));
+            // take.json points at the raw video by absolute path; keep it findable.
+            const moved = JSON.parse(fs.readFileSync(path.join(dir, "take.json"), "utf8"));
+            moved.video = path.join(dir, raw);
+            fs.writeFileSync(path.join(dir, "take.json"), JSON.stringify(moved));
+            log?.(`kept the previous take as a version (${id})`);
+        }
+        pruneHistory(outDir, log);
+    }
+    catch { /* history is a courtesy; never fail a good take over it */ }
+    fs.rmSync(stash, { recursive: true, force: true });
+}
+/** Keep it small: the newest KEEP_TAKES, and under the size budget. */
+export function pruneHistory(outDir, log) {
+    let kept = keptTakes(outDir);
+    const drop = (k, why) => {
+        fs.rmSync(path.join(outDir, HISTORY, k.id), { recursive: true, force: true });
+        log?.(`dropped version ${k.id} (${why})`);
+    };
+    for (const k of kept.slice(KEEP_TAKES))
+        drop(k, `only the last ${KEEP_TAKES} are kept`);
+    kept = kept.slice(0, KEEP_TAKES);
+    let total = kept.reduce((n, k) => n + k.mb, 0);
+    while (kept.length && total > HISTORY_BUDGET_MB) {
+        const oldest = kept.pop();
+        drop(oldest, `history over ${HISTORY_BUDGET_MB} MB`);
+        total -= oldest.mb;
+    }
+}
+/** Bring a kept version back as the current take. The caller re-renders. */
+export function restoreKept(outDir, id) {
+    const dir = path.join(outDir, HISTORY, id);
+    if (!fs.existsSync(path.join(dir, "take.json")))
+        return false;
+    stashPrevious(outDir);
+    for (const f of fs.readdirSync(dir))
+        fs.copyFileSync(path.join(dir, f), path.join(outDir, f));
+    const tp = path.join(outDir, "take.json");
+    const t = JSON.parse(fs.readFileSync(tp, "utf8"));
+    const raw = fs.readdirSync(outDir).find((f) => f.endsWith(".webm"));
+    if (raw) {
+        t.video = path.join(outDir, raw);
+        fs.writeFileSync(tp, JSON.stringify(t));
+    }
+    fs.rmSync(path.join(outDir, STASH), { recursive: true, force: true });
+    return true;
+}
 /** One run per output dir at a time — record AND render. Two overlapping runs
     would wipe each other's files and die with ENOENT halfway. Throws if held. */
 export function acquireLock(outDir) {
@@ -596,26 +900,29 @@ async function runStep(rec, page, step, m, ctx) {
             await moveCursorToPoint(page, pt.x, pt.y, { style: q.cursor.style, size: q.cursor.size });
         if (step.action === "click")
             await page.mouse.click(pt.x, pt.y);
-        if (step.pauseAfter)
+        if (step.pauseAfter && !ctx.fast)
             await page.waitForTimeout(step.pauseAfter);
         return;
     }
     if (step.action === "drag") {
         await performDrag(page, step, q, timeout);
-        if (step.pauseAfter)
+        if (step.pauseAfter && !ctx.fast)
             await page.waitForTimeout(step.pauseAfter);
         return;
     }
-    const pause = step.pauseAfter;
+    const pause = ctx.fast ? undefined : step.pauseAfter;
     switch (step.action) {
         case "wait":
-            await rec.wait(step.ms);
+            // An author `wait` is pacing for the viewer; while replaying there is
+            // none, so it shrinks. Capped rather than dropped: some apps genuinely
+            // need a beat, and the state has to arrive intact.
+            await rec.wait(ctx.fast ? Math.min(step.ms, 250) : step.ms);
             return; // wait's own duration is the pause
         case "click":
             await rec.click(step.selector, { timeout, zoom: step.zoom });
             break;
         case "type":
-            await rec.type(step.selector, expandEnv(step.text), { delay: step.delay ?? 70, clear: step.clear, timeout });
+            await rec.type(step.selector, expandEnv(step.text), { delay: ctx.fast ? 0 : (step.delay ?? (m.typing === "brisk" ? 22 : 70)), clear: step.clear, timeout });
             break;
         case "fill":
             await rec.fill(step.selector, expandEnv(step.text), { timeout });
@@ -623,6 +930,21 @@ async function runStep(rec, page, step, m, ctx) {
         case "hover":
             await rec.hover(step.selector, { timeout });
             break;
+        case "select": {
+            /* Hover first so the cursor actually travels to the control — a value
+               that changes with nothing moving reads as a glitch rather than a
+               choice. Playwright takes the option by value or by visible label, and
+               a page may use either, so try one and fall back to the other. */
+            await rec.hover(step.selector, { timeout });
+            const target = page.locator(step.selector).first();
+            try {
+                await target.selectOption({ value: step.value }, { timeout });
+            }
+            catch {
+                await target.selectOption({ label: step.value }, { timeout });
+            }
+            break;
+        }
         case "scroll": {
             let dy = step.y;
             if (step.to === "top" || step.to === "bottom") {
@@ -686,15 +1008,65 @@ async function runStep(rec, page, step, m, ctx) {
             ctx.downloads.push(dest);
             break;
         }
-        case "waitFor":
-            await page.waitForSelector(step.selector, { timeout: step.timeout ?? 30_000 });
+        case "select": {
+            // The cursor travels to it on camera (testreel has no select of its
+            // own), then the option is chosen by value, falling back to its
+            // visible label — a manifest author should not have to know which
+            // one the page uses.
+            await rec.hover(step.selector, { timeout });
+            const sel = page.locator(step.selector).first();
+            try {
+                await sel.selectOption(step.value, { timeout });
+            }
+            catch {
+                await sel.selectOption({ label: step.value }, { timeout });
+            }
             break;
+        }
+        case "waitFor": {
+            const t = step.timeout ?? 30_000;
+            if (step.gone) {
+                await page.waitForSelector(step.selector, { state: "hidden", timeout: t });
+                break;
+            }
+            await page.waitForSelector(step.selector, { timeout: t });
+            if (step.minChars) {
+                await page.waitForFunction(([sel, n]) => (document.querySelector(sel)?.textContent ?? "").trim().length >= n, [step.selector, step.minChars], { timeout: t });
+            }
+            if (step.stableMs) {
+                // Quiet for this long, measured in the page: the only honest signal
+                // that a streamed or animating subtree has finished.
+                await page.waitForFunction(([sel, quiet]) => {
+                    const w = window;
+                    const el = document.querySelector(sel);
+                    if (!el)
+                        return false;
+                    w.__retakeStable ??= {};
+                    const key = sel;
+                    const now = Date.now();
+                    const snap = el.innerHTML.length + ":" + (el.textContent ?? "").length;
+                    const prev = w.__retakeSnap ??= {};
+                    if (prev[key] !== snap) {
+                        prev[key] = snap;
+                        w.__retakeStable[key] = now;
+                        return false;
+                    }
+                    return now - (w.__retakeStable[key] ?? now) >= quiet;
+                }, [step.selector, step.stableMs], { timeout: t, polling: 100 });
+            }
+            break;
+        }
         case "evaluate":
             await page.evaluate(step.script);
             break;
         case "stub":
             await ctx.stub({ url: step.url, method: step.method, status: step.status ?? 200, json: step.json, from: step.from, contentType: "application/json; charset=utf-8" });
             break;
+        case "callout":
+            // The box was resolved in the caller; on camera this is a hold while
+            // the (render-time) ring has the viewer's eye.
+            await page.waitForTimeout(step.ms / m.speed);
+            break;
         case "scene":
             // A marker only. Its timestamp is the point of the step.
             break;
@@ -723,6 +1095,8 @@ export function describe(step) {
             return `fill ${step.selector}${step.secret ? " ••••••" : ""}`;
         case "hover":
             return `hover ${step.selector ?? pointName(step.at)}`;
+        case "select":
+            return `select "${step.value}" in ${step.selector}`;
         case "scroll":
             return step.to ? `scroll to ${step.to} (${step.align})` : `scroll x=${step.x ?? 0} y=${step.y ?? 0}`;
         case "zoom":
@@ -738,11 +1112,13 @@ export function describe(step) {
         case "download":
             return `download${step.selector ? ` via ${step.selector}` : ""}${step.saveAs ? ` → ${step.saveAs}` : ""}`;
         case "waitFor":
-            return `wait for ${step.selector}`;
+            return `wait for ${step.selector}${step.gone ? " to go" : ""}${step.stableMs ? ` to settle (${step.stableMs}ms quiet)` : ""}${step.minChars ? ` to hold ${step.minChars}+ chars` : ""}`;
         case "evaluate":
             return `evaluate (${step.script.length} chars)`;
         case "stub":
             return `stub ${step.method ? step.method + " " : ""}${step.url}`;
+        case "callout":
+            return `callout ${step.selector ?? pointName(step.at)}${step.label ? ` “${step.label}”` : ""}`;
         case "scene":
             return `scene: ${step.label}`;
     }
@@ -799,10 +1175,63 @@ export async function runFileOrCommandSeed(s, dir, log) {
     }
     else if (s.kind === "command") {
         log(`seed: $ ${s.run}`);
-        execSync(expandEnv(s.run), { stdio: "inherit", cwd: dir });
+        await runSeedCommand(expandEnv(s.run), s.run, dir);
+    }
+}
+/** Anything that asks to outlive the command that started it. A seed's job is
+    to put data in place and exit; starting a server is `start_app`'s job, and
+    that one is gated on the person's say-so. Backgrounding here would walk
+    straight around that gate, so it is refused by name. */
+const BACKGROUNDING = [
+    // A lone `&` is backgrounding; `&&` is just "and then". Quoted spans are
+    // stripped before this runs, so a URL's query string is not mistaken for it.
+    [/(?<!&)&(?!&)/, "a bare `&`"],
+    [/\bnohup\b/, "nohup"],
+    [/\bdisown\b/, "disown"],
+    [/\b(?:screen|tmux)\s+(?:-\w+\s+)*(?:new|new-session|start)/, "screen/tmux"],
+    [/\bpm2\s+(?:start|restart)\b/, "pm2"],
+    [/\bforever\s+start\b/, "forever"],
+];
+/** A seed command runs to completion or it does not run. */
+export const SEED_TIMEOUT_MS = 120_000;
+export async function runSeedCommand(cmd, shown, dir, timeoutMs = SEED_TIMEOUT_MS) {
+    // Quoted arguments are data, not shell syntax: a URL's `?a=1&b=2` is not an
+    // attempt to background anything.
+    const bare = cmd.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
+    for (const [re, what] of BACKGROUNDING) {
+        if (re.test(bare)) {
+            throw new Error(`Refusing to run this seed command because it uses ${what}, which leaves a process running after the seed finishes:\n  ${shown}\n\n` +
+                `A seed puts data in place and exits. To start the app itself, use Retake's start_app — starting processes is something the person allows explicitly, and a seed must not become the way around that.`);
+        }
+    }
+    // `detached` puts the shell in its own process group so a timeout can kill
+    // what it spawned as well. spawnSync cannot do this, which is why the seed
+    // path is async: killing only the shell would orphan the very process this
+    // timeout exists to stop.
+    const child = spawn(cmd, [], { shell: true, stdio: "inherit", cwd: dir, detached: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+            if (child.pid)
+                process.kill(-child.pid, "SIGKILL");
+        }
+        catch {
+            child.kill("SIGKILL");
+        }
+    }, timeoutMs);
+    const status = await new Promise((done, fail) => {
+        child.once("error", (e) => { clearTimeout(timer); fail(e); });
+        child.once("close", (code) => { clearTimeout(timer); done(code); });
+    });
+    if (timedOut) {
+        throw new Error(`Seed command did not finish within ${Math.round(timeoutMs / 1000)}s and was stopped:\n  ${shown}\n\n` +
+            `If it is meant to start the app rather than seed it, use start_app instead — a seed has to exit before the take can begin.`);
     }
+    if (status !== 0)
+        throw new Error(`Seed command failed (exit ${status}):\n  ${shown}`);
 }
-async function runEvaluateSeed(page, s, dir, log) {
+export async function runEvaluateSeed(page, s, dir, log) {
     const data = s.from ? JSON.parse(fs.readFileSync(path.resolve(dir, s.from), "utf8")) : undefined;
     log(`seed: evaluate${s.from ? ` (${s.from})` : ""}`);
     await page.evaluate(async ({ script, data }) => {