retake-demos 0.3.0 → 0.4.0

package/dist/render.js

@@ -16,8 +16,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { execFileSync, spawnSync } from "node:child_process";
-import { capSecondsFor } from "./record.js";
+import YAML from "yaml";
+import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { capSecondsFor, restorePrevious } from "./record.js";
 import { bandHeightFor, maxCharsFor, wrap } from "./captions.js";
 import { renderCard, renderCalloutOverlay, renderTitledCover } from "./cards.js";
 import { describeIdle, planIdle, warpFilterArgs, warpTake } from "./pace.js";
@@ -127,6 +128,45 @@ export function applyManifest(m, take) {
     const duration = Math.max(trimBefore + 1, take.duration - tail);
     return { ...take, timeline, trimBefore, duration };
 }
+/** Apply the manifest's render-time scene nudges to a take.
+ *
+ * Scene markers come out of the recording, so getting one in the wrong place
+ * used to mean recording the whole thing again — with a live model in the
+ * middle of it, at 2.3x the video's length. A nudge moves the marker instead,
+ * and everything downstream (captions, stills, the thumbnail) reads scene
+ * times through here, so all of it moves together for the price of a render.
+ *
+ * Order is preserved by clamping: a scene can never be pushed past its
+ * neighbours, because a timeline that crosses over itself would produce
+ * captions in the wrong sequence rather than an error anyone could see.
+ */
+export function nudgeScenes(take, m) {
+    const wanted = new Map();
+    for (const st of m?.steps ?? []) {
+        if (st.action === "scene" && st.nudge)
+            wanted.set(st.label, st.nudge);
+    }
+    if (!wanted.size)
+        return { take, applied: [] };
+    const applied = [];
+    const GAP = 0.1; // scenes stay strictly ordered
+    const sceneIdx = take.timeline.map((t, i) => (t.action === "scene" ? i : -1)).filter((i) => i >= 0);
+    const timeline = take.timeline.map((t) => ({ ...t }));
+    for (const [n, i] of sceneIdx.entries()) {
+        const want = wanted.get(timeline[i].label ?? "");
+        if (!want)
+            continue;
+        const prev = n > 0 ? timeline[sceneIdx[n - 1]].start + GAP : 0;
+        const next = n < sceneIdx.length - 1 ? timeline[sceneIdx[n + 1]].start - GAP : take.duration;
+        const target = timeline[i].start + want / 1000;
+        const to = Math.min(Math.max(target, prev), Math.max(prev, next));
+        const span = timeline[i].end - timeline[i].start;
+        applied.push({ label: timeline[i].label ?? "?", ms: want, clamped: Math.abs(to - target) > 0.01 });
+        timeline[i].start = to;
+        timeline[i].end = to + span;
+    }
+    return { take: { ...take, timeline }, applied };
+}
 export function scenes(take) {
     return take.timeline.filter((t) => t.action === "scene");
 }
@@ -244,12 +284,31 @@ async function renderCardFrame(file, W, H, g, bg) {
     }
 }
 // --- render ------------------------------------------------------------------
-export async function render(m, take, outDir, opts = {}) {
+export async function render(m, takeIn, outDir, opts = {}) {
+    let take = takeIn;
     const o = typeof opts === "function" ? { log: opts } : opts;
     const log = o.log;
     const q = resolve(m);
+    // Before anything reads a scene time: markers move at render, so captions,
+    // stills and the thumbnail all shift together and none of it costs a take.
+    {
+        const n = nudgeScenes(take, m);
+        take = n.take;
+        for (const a of n.applied) {
+            log?.(`scene "${a.label}" moved ${a.ms > 0 ? "+" : ""}${(a.ms / 1000).toFixed(1)}s${a.clamped ? " (clamped — it would have crossed a neighbouring scene)" : ""}`);
+        }
+    }
     const proofLog = path.join(outDir, "proof-log.md");
     const writeProof = (a) => fs.writeFileSync(proofLog, renderProof(m, take, q, a));
+    // An output directory that cannot say what produced it makes an audit
+    // guesswork: the manifest on disk today is not necessarily the one this
+    // was rendered from. Keep a copy beside the take.
+    if (!o.scene) {
+        try {
+            fs.writeFileSync(path.join(outDir, "manifest.used.yaml"), YAML.stringify(m));
+        }
+        catch { /* not fatal */ }
+    }
     if (!o.scene)
         writeProof({});
     if (!take.video)
@@ -317,8 +376,11 @@ export async function render(m, take, outDir, opts = {}) {
     const SH = take.quality?.height ?? q.viewport.height;
     // band/overlay/none: the canvas IS the recording (site fills the frame).
     // card: the preset canvas, with the recording framed inside it.
-    const W = q.layout === "card" ? q.width : SW;
-    const H = q.layout === "card" ? q.height : SH;
+    // The finished frame is ALWAYS the preset's canvas. Whatever page size the
+    // take was recorded at gets fitted into it below — so a size change is a
+    // re-render, never a re-record, and one preset always means one shape.
+    const W = q.width;
+    const H = q.height;
     const fps = q.fps;
     const bg = q.theme.background;
     const ink = q.theme.ink;
@@ -339,12 +401,17 @@ export async function render(m, take, outDir, opts = {}) {
     let geom = null;
     const capSize = q.captions ? q.captions.fontSize : 0;
     // One band height for the whole take, from its captions (see captions.ts).
-    const bandH = bandHeightFor(q, W, captionWindows(take).map((w) => w.text), H);
+    const bandH = bandHeightFor(q, captionWindows(take).map((w) => w.text));
     if (layout === "band") {
         // Site fills the frame; caption strip below it — none at all if captions are off.
+        // Fit the recording into the page area, letterboxing on the theme colour
+        // rather than black, then the caption strip underneath. A take recorded
+        // at 1440×1080 becomes a true 1920×1080, a 1080×1920, whatever is asked.
+        const pageH = H - bandH;
+        filters.push(`scale=${W}:${pageH}:force_original_aspect_ratio=decrease:flags=lanczos`, `pad=${W}:${pageH}:(ow-iw)/2:(oh-ih)/2:color=${bg}`);
         if (bandH) {
-            filters.push(`pad=${W}:${H + bandH}:0:0:color=${bg}`);
-            capY = `${H}+${bandH / 2}-th/2`;
+            filters.push(`pad=${W}:${H}:0:0:color=${bg}`);
+            capY = `${pageH}+${bandH / 2}-th/2`;
         }
     }
     else if (layout === "card") {
@@ -359,7 +426,10 @@ export async function render(m, take, outDir, opts = {}) {
         capColor = q.captions ? q.captions.color ?? "white" : "white";
         capBox = ":box=1:boxcolor=black@0.55:boxborderw=18";
     }
-    filters.push("format=yuv420p");
+    // Square pixels, explicitly. Playwright's webm arrives with a SAR of
+    // 1216:1215 — a half-percent stretch nobody notices until concat refuses
+    // to join it to a title card that is honestly 1:1.
+    filters.push("setsar=1", "format=yuv420p");
     const captionFilters = [];
     if (q.captions && layout !== "none") {
         const maxChars = maxCharsFor(W, capSize);
@@ -573,20 +643,48 @@ export async function render(m, take, outDir, opts = {}) {
             at = last ? last.start - take.trimBefore + 1.0 : Math.max(0, take.duration - take.trimBefore - 0.5);
         }
         thumbnail = path.join(outDir, "thumbnail.png");
-        ff(["-ss", Math.max(0, at + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", thumbnail], log);
+        // Clamp inside the file. The default is "last scene + 1s", which lands
+        // PAST the end whenever a take stops soon after its final scene — ffmpeg
+        // then writes nothing and the render died on the missing file, reported
+        // in the field as "all steps ok, but no video".
+        const seekable = Math.max(0, probe(mp4).duration - 0.25);
+        const seek = Math.min(Math.max(0, at + cardShift), seekable);
+        ff(["-ss", seek.toFixed(2), "-i", mp4, "-frames:v", "1", thumbnail], log);
+        if (!fs.existsSync(thumbnail)) {
+            log?.(`thumbnail: nothing at ${seek.toFixed(1)}s — taking the last frame instead`);
+            ff(["-sseof", "-0.3", "-i", mp4, "-frames:v", "1", thumbnail], log);
+        }
+        if (!fs.existsSync(thumbnail)) {
+            log?.("thumbnail: could not be taken — the video is fine, the poster is not");
+            thumbnail = undefined;
+        }
         // A launch cut gets a second candidate: this frame with the title on it.
         // The person picks between them (or any still, or their own file) in the
         // window; both are just PNGs, and the poster is whichever is thumbnail.png.
-        if (m.mode === "launch" && m.intro) {
+        if (m.mode === "launch" && m.intro && thumbnail) {
             const d = probe(mp4);
             await renderTitledCover(ffmpegBin(), thumbnail, path.join(outDir, "cover-titled.png"), m.intro, d.width, d.height, q.theme);
         }
         mark("thumbnail");
     }
+    // A launch cut is a thing someone signs off, so give them the artifact
+    // that makes signing off possible without ffmpeg by hand.
+    if (m.mode === "launch" && !o.scene && fs.existsSync(path.join(outDir, "demo.mp4"))) {
+        try {
+            contactSheet(outDir, 2, 420, undefined);
+            mark("contact");
+        }
+        catch (e) {
+            log?.(`contact sheet: ${e.message}`);
+        }
+    }
     // --- 5. scene stills -------------------------------------------------------
     // Every scene already carries its real timestamp, so one crisp frame per
     // scene is free — and a video usually ships with a picture next to it.
     let stills = [];
+    // Every still in ONE ffmpeg pass: a process launch and a fresh decode per
+    // frame cost more than the frames do (7 stills was 3s of pure overhead).
+    const shots = [];
     if (m.outputs.stills) {
         const dir = path.join(outDir, "stills");
         fs.rmSync(dir, { recursive: true, force: true });
@@ -601,17 +699,29 @@ export async function render(m, take, outDir, opts = {}) {
             const at = Math.min(Math.max(0, from + Math.max(0.8, (next - from) / 2)), Math.max(0, end - 0.2));
             const base = `${String(i + 1).padStart(2, "0")}-${(sce.label || "scene").replace(/[^a-z0-9-]+/gi, "-")}`;
             const file = path.join(dir, `${base}.png`);
-            ff(["-ss", (at + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", file], log);
+            shots.push({ at: at + cardShift, file });
             stills.push(file);
             // And the scene's last moment: the caption names what the scene
             // achieves, and that is usually on screen at the end, not the middle.
             const atEnd = Math.min(Math.max(from + 0.4, next - 0.6), Math.max(0, end - 0.2));
             if (atEnd - at > 0.5) {
                 const fe = path.join(dir, `${base}-end.png`);
-                ff(["-ss", (atEnd + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", fe], log);
+                shots.push({ at: atEnd + cardShift, file: fe });
                 stills.push(fe);
             }
         }
+        if (shots.length) {
+            // Each still is its own ffmpeg with an INPUT-side seek: `-ss` before
+            // `-i` jumps by keyframe, while one batched process with `-ss` after
+            // `-i` decodes sequentially to every timestamp and is far slower (it
+            // turned 3s of stills into 18s — measured, then reverted). The launches
+            // are independent, so they run at once instead of in a queue.
+            const bin = ffmpegBin();
+            await Promise.all(shots.map((s) => new Promise((done) => {
+                execFile(bin, ["-hide_banner", "-loglevel", "error", "-y", "-ss", s.at.toFixed(2), "-i", mp4, "-frames:v", "1", s.file], () => done());
+            })));
+            stills = stills.filter((f) => fs.existsSync(f));
+        }
         if (sc.length)
             mark(`stills ×${sc.length}`);
     }
@@ -620,8 +730,9 @@ export async function render(m, take, outDir, opts = {}) {
     const p = probe(mp4);
     const facts = {
         width: p.width, height: p.height, fps: p.fps || fps, duration: p.duration,
-        sizes: Object.fromEntries([master, mp4, gif, thumbnail].filter((f) => !!f).map((f) => [path.basename(f), fs.statSync(f).size])),
+        sizes: Object.fromEntries([master, mp4, gif, thumbnail].filter((f) => !!f && fs.existsSync(f)).map((f) => [path.basename(f), fs.statSync(f).size])),
         gifTool, layout, cameraScenes: cam.count, encoder: q.encoder, timings: t.marks, renderHash: hash, preset: q.name,
+        mode: m.mode,
     };
     const a = { master, mp4, gif, thumbnail, proofLog, facts };
     writeProof(a);
@@ -629,6 +740,38 @@ export async function render(m, take, outDir, opts = {}) {
     return a;
 }
 /** GIF straight from the finished demo.mp4 — no re-render, no browser. */
+/** One timestamped contact sheet of the finished video.
+ *
+ * Reviewing a take meant pulling frames out with ffmpeg by hand, a dozen
+ * timestamps at a time, eight videos deep. This is that, once: a grid with
+ * the playback time burned into every cell, so a still can be reasoned about
+ * as a moment rather than a picture. Per-scene stills cannot do this — they
+ * cannot show a caption going false *inside* a scene, and they carry no clock.
+ */
+export function contactSheet(outDir, everySec = 2, width = 420, log) {
+    const mp4 = path.join(outDir, "demo.mp4");
+    if (!fs.existsSync(mp4))
+        throw new Error(`no demo.mp4 in ${outDir} — render it first`);
+    const dur = probe(mp4).duration;
+    const cells = Math.max(1, Math.ceil(dur / everySec));
+    const cols = Math.min(4, Math.max(1, Math.ceil(Math.sqrt(cells))));
+    const rows = Math.ceil(cells / cols);
+    const fontFile = DEFAULT_FONTS.find((f) => fs.existsSync(f));
+    const font = fontFile ? `fontfile='${fontFile}':` : "";
+    const out = path.join(outDir, "contact.png");
+    // drawtext runs before tile, so each cell carries its own playback time.
+    const vf = [
+        `fps=1/${everySec}`,
+        `scale=${width}:-2`,
+        `drawtext=${font}text='%{pts\\:hms}':x=8:y=8:fontsize=${Math.round(width / 20)}:fontcolor=white:box=1:boxcolor=black@0.55:boxborderw=5`,
+        `tile=${cols}x${rows}:margin=8:padding=6:color=#e6e9e2`,
+    ].join(",");
+    ff(["-i", mp4, "-vf", vf, "-frames:v", "1", out], log);
+    if (!fs.existsSync(out))
+        throw new Error("ffmpeg produced no contact sheet");
+    log?.(`contact: ${cells} frames every ${everySec}s, ${cols}×${rows} → ${path.relative(process.cwd(), out)}`);
+    return out;
+}
 export function makeGif(outDir, width = 900, fps = 18, log) {
     const mp4 = path.join(outDir, "demo.mp4");
     if (!fs.existsSync(mp4))
@@ -668,9 +811,17 @@ export function check(outDir, m) {
     const say = (pass, text) => { lines.push(`${pass ? "pass" : "FAIL"}  ${text}`); if (!pass)
         ok = false; };
     const takePath = path.join(outDir, "take.json");
+    // A run killed outright (a signal, a closed pipe) leaves its predecessor in
+    // the stash with no catch block ever running. Anything that READS the folder
+    // puts it back, so a person looking at it never sees an empty directory and
+    // concludes their take is gone.
+    if (!fs.existsSync(takePath))
+        restorePrevious(outDir);
     if (!fs.existsSync(takePath))
         return { ok: false, lines: ["FAIL  no take.json"] };
-    const take = JSON.parse(fs.readFileSync(takePath, "utf8"));
+    // The same shift render applied, so a nudged scene is not reported as a
+    // stall or a caption in the wrong place by a check reading raw times.
+    const take = nudgeScenes(JSON.parse(fs.readFileSync(takePath, "utf8")), m).take;
     // The take knows which preset it was recorded with; a `--preset` on the run
     // must win over the manifest's default, or a draft fails for lacking a master.
     const q = m ? resolve(take.quality?.preset && take.quality.preset !== m.preset ? { ...m, preset: take.quality.preset } : m) : null;
@@ -678,17 +829,23 @@ export function check(outDir, m) {
     if (!fs.existsSync(mp4))
         return { ok: false, lines: ["FAIL  demo.mp4 missing"] };
     const p = probe(mp4);
-    const wantW = q ? (q.layout === "card" ? q.width : (take.quality?.width ?? q.viewport.width)) : undefined;
+    const wantW = q?.width;
     say(true, `resolution: ${p.width}×${p.height}`);
     if (wantW)
-        say(p.width === wantW, `matches expected width ${wantW}`);
+        say(p.width === wantW, `matches ${q?.name}: ${wantW}px wide`);
     say(p.width >= 960, `at least 960px wide`);
     say(true, `fps: ${p.fps}`);
     /* A take may legitimately run long — a full product walkthrough does.
        The manifest's own maxSeconds is the author's stated bound; a take
        inside it is not a runaway, so do not fail it for length. */
     const longest = m ? capSecondsFor(m) : 300;
-    say(p.duration >= 5 && p.duration <= longest, `duration: ${p.duration.toFixed(1)}s`);
+    // Whole-video judgements (is it long enough, does it have every scene) do
+    // not apply to a deliberate fragment.
+    const fragment = /\((?:from|until)\)/.test(take.partial ?? "");
+    if (fragment)
+        lines.push(`—     duration: ${p.duration.toFixed(1)}s (not judged — this is a fragment)`);
+    else
+        say(p.duration >= 5 && p.duration <= longest, `duration: ${p.duration.toFixed(1)}s`);
     if (p.duration > 60)
         lines.push(`—     ${p.duration.toFixed(0)}s is long for a social post (aim for 15–45s); fine for a walkthrough`);
     /* A step that stalls is not a failed step, so nothing above notices it — but
@@ -697,23 +854,76 @@ export function check(outDir, m) {
        other seven navigations took under four seconds; every check passed.
        `wait` and `scene` are excluded because their whole job is to take time. */
     const PATIENCE = 8;
-    const stalled = (take.timeline || [])
+    // Judge what shipped. compressIdle rewrites the timeline at render, so
+    // reading raw step durations here failed good videos for a stall the
+    // viewer never sees — and a check that cries wolf teaches you to skim
+    // past the one that matters.
+    const idleSegs = m?.compressIdle && take.video
+        ? planIdle(take, m.compressIdle === true ? 1.5 : m.compressIdle.keepSeconds)
+        : [];
+    const shownTake = idleSegs.length ? warpTake(take, idleSegs) : take;
+    const stalled = (shownTake.timeline || [])
         .filter((t) => t.action !== "wait" && t.action !== "scene" && t.action !== "stub")
         .map((t) => ({ ...t, took: t.end - t.start }))
         .filter((t) => t.took > PATIENCE)
         .sort((a, b) => b.took - a.took);
+    // Did the app break, and was it still broken when the video stopped? A
+    // take can pass every step and end on an error screen; one did, and only
+    // frame-by-frame review found it. An error in the last stretch is the
+    // shape that matters — earlier ones are usually recovered from.
+    const errs = take.pageErrors ?? [];
+    if (errs.length) {
+        const endsAt = take.duration;
+        const late = errs.filter((e) => e.at >= Math.max(0, endsAt - 6));
+        if (late.length) {
+            say(false, `the app reported an error in the last seconds and the video ends on it: “${late[0].text.slice(0, 120)}” at ${late[0].at.toFixed(1)}s — watch the final frames before shipping this`);
+        }
+        else {
+            lines.push(`—     the app reported ${errs.length} error${errs.length > 1 ? "s" : ""} during the take (earliest “${errs[0].text.slice(0, 80)}”), none in the last 6s`);
+        }
+    }
     if (stalled.length) {
         const worst = stalled[0];
+        // A timestamp says a stall happened; it cannot say why. The frame can —
+        // a spinner, a modal, an error, or the app simply sitting there are four
+        // different problems and "25.5s at 0:56" is the same sentence for all of
+        // them. Pulled from the finished video, so it costs a seek, not a take.
+        const shots = [];
+        const trim = shownTake.trimBefore ?? 0;
+        for (const [i, t] of stalled.slice(0, 3).entries()) {
+            // A third of the way in: past whatever triggered it, still inside the
+            // held stretch rather than on the frame that ends it.
+            const at = Math.max(0, t.start - trim + Math.min(t.took / 3, 4));
+            const file = path.join(outDir, `stalled-${String(i + 1).padStart(2, "0")}.png`);
+            try {
+                ff(["-ss", at.toFixed(2), "-i", mp4, "-frames:v", "1", "-y", file]);
+                if (fs.existsSync(file))
+                    shots.push(path.relative(process.cwd(), file));
+            }
+            catch { /* a picture is a bonus, never the reason a check fails */ }
+        }
         say(false, `${stalled.length} step${stalled.length > 1 ? "s" : ""} stalled over ${PATIENCE}s — ` +
             `the take holds a still frame there. Worst: ${worst.took.toFixed(1)}s at ` +
             `${Math.floor(worst.start / 60)}:${String(Math.floor(worst.start % 60)).padStart(2, "0")} — ${worst.summary}`);
-        for (const t of stalled.slice(1, 4)) {
-            lines.push(`—     also ${t.took.toFixed(1)}s: ${t.summary}`);
+        if (shots[0])
+            lines.push(`—     what the frame shows there: ${shots[0]} — open it; a spinner, a modal and an idle app are three different fixes`);
+        for (const [i, t] of stalled.slice(1, 4).entries()) {
+            lines.push(`—     also ${t.took.toFixed(1)}s: ${t.summary}${shots[i + 1] ? ` (${shots[i + 1]})` : ""}`);
         }
     }
     else {
         say(true, `no step stalled (nothing over ${PATIENCE}s)`);
     }
+    // A stub nobody asked for is a silent lie: the take passes and the screen
+    // shows live data where the demo promised canned. Worth a failed check, not
+    // a footnote — this is the one the reporter spent a morning on.
+    const dead = Object.entries(take.stubHits ?? {}).filter(([, n]) => !n).map(([k]) => k);
+    if (take.stubbed?.length) {
+        if (dead.length)
+            say(false, `${dead.length} stub${dead.length > 1 ? "s" : ""} never answered a request: ${dead.join(", ")} — those screens showed the app's real data. Check the URL pattern matches, and that the page actually re-fetched (a navigate that changes only the #fragment does not reload an SPA).`);
+        else
+            say(true, `all ${take.stubbed.length} stub${take.stubbed.length > 1 ? "s" : ""} answered at least one request`);
+    }
     const mb = (f) => (fs.statSync(f).size / 1e6).toFixed(1) + " MB";
     say(true, `demo.mp4: ${mb(mp4)}`);
     const master = path.join(outDir, "master.mp4");
@@ -732,7 +942,13 @@ export function check(outDir, m) {
         lines.push("—     thumbnail: not requested");
     say(fs.existsSync(path.join(outDir, "proof-log.md")), "proof log exists");
     say(take.ok, take.ok ? "all steps passed" : "some steps failed");
-    say(!take.partial, take.partial ? `partial: ${take.partial}` : "polished render (not fallback)");
+    // A fragment recorded on purpose (--from / --until) is not a defect. Saying
+    // FAIL about work that did exactly what was asked is how people learn to
+    // skim past checks, including the ones that matter.
+    if (fragment)
+        say(true, `fragment — ${take.partial}`);
+    else
+        say(!take.partial, take.partial ? `partial: ${take.partial}` : "polished render (not fallback)");
     if (take.partial && /NO CURSOR/.test(take.partial))
         say(false, "cursor overlay failed — the video has no cursor (split the demo or set cursor: false)");
     const sc = scenes(m ? applyManifest(m, take) : take);
@@ -763,11 +979,27 @@ function renderProof(m, take, q, a) {
         "",
         `- URL: ${m.url}`,
         `- Preset: ${q.name} · canvas ${q.width}×${q.height} · viewport ${take.quality?.width ?? q.viewport.width}×${take.quality?.height ?? q.viewport.height} @ ${q.fps}fps · page scale ${q.scale}× · layout ${q.layout}`,
+        // Measured during the take, not computed from the preset: `zoom` does not
+        // move an app's media queries, so width÷scale would be a plausible lie.
+        // Named outright because a responsive app serves a different layout below
+        // a breakpoint, and this is the number that explains which one you filmed.
+        ...(take.contentWidth && take.layoutWidth && take.contentWidth !== take.layoutWidth
+            ? [`- Page width: content had **${take.contentWidth} CSS px** of room (viewport ${take.layoutWidth} ÷ ${q.scale}× scale), while media queries read **${take.layoutWidth} px**. A responsive app therefore renders its DESKTOP layout squeezed into ${take.contentWidth}px rather than switching to mobile — if this take looks cramped, that is why, and \`scale: 1\` is the fix.`]
+            : take.layoutWidth ? [`- Page laid out at: **${take.layoutWidth} CSS px** wide.`] : []),
         `- Started: ${take.startedAt}`,
         `- Finished: ${take.finishedAt}`,
         `- Result: **${take.ok ? "all steps passed" : "some steps failed"}**${take.partial ? ` · **partial** — ${take.partial}` : ""}`,
         `- Setup trimmed: ${take.trimBefore.toFixed(1)}s · final length ≈ ${(take.duration - take.trimBefore).toFixed(1)}s`,
-        ...(take.stubbed?.length ? [`- **Stubbed data**: ${take.stubbed.join(", ")} — these screens were fed canned responses, not a live backend.`] : []),
+        // A nudged demo no longer matches raw step timing; say so, or the next
+        // person reads the timeline against the video and thinks one is wrong.
+        ...(() => {
+            const n = (m.steps ?? []).filter((st) => st.action === "scene" && st.nudge).map((st) => `${st.label} ${st.nudge > 0 ? "+" : ""}${(st.nudge / 1000).toFixed(1)}s`);
+            return n.length ? [`- **Scene markers moved at render**: ${n.join(", ")} — the captions and stills follow these, not the raw step times below.`] : [];
+        })(),
+        ...(take.stubbed?.length ? [`- **Stubbed data**: ${take.stubbed.map((k) => `${k}${take.stubHits ? ` (${take.stubHits[k] ?? 0} request${(take.stubHits[k] ?? 0) === 1 ? "" : "s"})` : ""}`).join(", ")} — these screens were fed canned responses, not a live backend.`] : []),
+        ...(take.stubHits && Object.entries(take.stubHits).some(([, n]) => !n)
+            ? [`- **Stubs that never fired**: ${Object.entries(take.stubHits).filter(([, n]) => !n).map(([k]) => k).join(", ")} — armed, but no request matched, so those screens showed whatever the app really returned. Usually the pattern does not match the real URL, or the page never re-fetched (a navigation that only changes the #fragment does not reload an SPA).`]
+            : []),
         "",
         "## Artifacts",
         "",

package/dist/tidy.js

@@ -0,0 +1,103 @@
+/**
+ * Reclaiming disk without losing anything you cannot get back.
+ *
+ * Measured across 37 real demos: 506 MB of outputs, of which 345 MB was
+ * DERIVED — master.mp4, demo.mp4, stills, thumbnails and gifs all re-render
+ * from `take.json` plus the raw recording, in seconds. Only the raw `.webm`
+ * and `take.json` are irreplaceable: lose those and the demo has to be
+ * performed again, which is the one cost this tool exists to avoid.
+ *
+ * So tidy never touches those two, reports before it removes anything, and
+ * separates "safe, re-renders in seconds" from "the whole take is rubbish".
+ */
+import fs from "node:fs";
+import path from "node:path";
+const bytesOf = (p) => {
+    try {
+        const st = fs.statSync(p);
+        if (!st.isDirectory())
+            return st.size;
+        let n = 0;
+        for (const f of fs.readdirSync(p))
+            n += bytesOf(path.join(p, f));
+        return n;
+    }
+    catch {
+        return 0;
+    }
+};
+export const mb = (n) => `${(n / 1e6).toFixed(0)} MB`;
+/** Derived files: every one of these comes back from a re-render. */
+const DERIVED = ["master.mp4", "thumbnail.png", "cover.png", "cover-titled.png", "contact.png", "stills"];
+const DERIVED_RE = [/\.gif$/, /^\.card-.*\.mp4$/, /^\.callout-.*\.webm$/, /^\.paced\.mp4$/, /^\.joined\.mp4$/, /^debug-filter\.txt$/, /^stalled-\d+\.png$/, /^dry-failed-\d+\.png$/, /^failed-step\.png$/, /^not-the-app\.png$/];
+export function planTidy(outRoot, o) {
+    const groups = [];
+    const add = (what, why, files) => {
+        if (!files.length)
+            return;
+        groups.push({ what, why, files, bytes: files.reduce((n, f) => n + bytesOf(f), 0) });
+    };
+    if (!fs.existsSync(outRoot))
+        return { groups: [], bytes: 0, keptBytes: 0 };
+    const failed = [], orphaned = [], derived = [], deliverables = [];
+    let keptBytes = 0;
+    for (const name of fs.readdirSync(outRoot)) {
+        const dir = path.join(outRoot, name);
+        if (!fs.statSync(dir).isDirectory())
+            continue;
+        const takePath = path.join(dir, "take.json");
+        const hasManifest = fs.existsSync(path.join(o.demosDir, `${name}.yaml`)) || fs.existsSync(path.join(o.demosDir, `${name}.json`));
+        // A whole folder with no manifest cannot be re-rendered or re-recorded
+        // from anything in this workspace — it is a leftover, not an asset.
+        if (!hasManifest) {
+            orphaned.push(dir);
+            continue;
+        }
+        let take = null;
+        try {
+            take = JSON.parse(fs.readFileSync(takePath, "utf8"));
+        }
+        catch { /* no take */ }
+        // A take whose steps failed is not something anyone goes back to.
+        if (take && take.ok === false) {
+            failed.push(dir);
+            continue;
+        }
+        for (const f of fs.readdirSync(dir)) {
+            const full = path.join(dir, f);
+            if (f === "take.json" || f.endsWith(".webm") || f === ".retake-lock" || f === ".poster" || f === ".history" || f === "manifest.used.yaml" || f === "proof-log.md" || f === "facts.json") {
+                keptBytes += bytesOf(full);
+                continue;
+            }
+            if (f === "demo.mp4") {
+                (o.deep ? deliverables : null)?.push(full);
+                if (!o.deep)
+                    keptBytes += bytesOf(full);
+                continue;
+            }
+            if (DERIVED.includes(f) || DERIVED_RE.some((re) => re.test(f))) {
+                derived.push(full);
+                continue;
+            }
+            keptBytes += bytesOf(full);
+        }
+    }
+    add("re-renderable", "master, stills, thumbnails, gifs, working files — all come back from `retake render`, in seconds", derived);
+    add("failed takes", "their steps did not pass; nobody goes back to a broken recording", failed);
+    if (o.orphans)
+        add("orphaned folders", "no manifest in demos/ — nothing here can be re-recorded or re-rendered", orphaned);
+    if (o.deep)
+        add("deliverables", "demo.mp4 — re-renders from the recording, but it IS the file you hand over", deliverables);
+    const bytes = groups.reduce((n, g) => n + g.bytes, 0);
+    return { groups, bytes, keptBytes };
+}
+export function applyTidy(plan) {
+    let freed = 0;
+    for (const g of plan.groups) {
+        for (const f of g.files) {
+            freed += bytesOf(f);
+            fs.rmSync(f, { recursive: true, force: true });
+        }
+    }
+    return freed;
+}