retake-demos 0.2.2 → 0.4.0

package/dist/render.js

@@ -16,11 +16,16 @@ 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";
+import { DEFAULT_VOICE, audioSeconds, synthesize } from "./voice.js";
 import { createRequire } from "node:module";
 import { chromium } from "playwright";
-import { resolve } from "./manifest.js";
+import { expandEnv, resolve } from "./manifest.js";
 /** What the render depends on: the raw take + everything in the manifest that
     shapes the picture. Same hash → same output → skip. */
 export function renderHash(m, take) {
@@ -28,7 +33,14 @@ export function renderHash(m, take) {
     const src = take.video && fs.existsSync(take.video) ? fs.statSync(take.video) : null;
     const h = createHash("sha1");
     const merged = applyManifest(m, take);
-    h.update(JSON.stringify({ q, tempo: m.tempo, cap: m.captions, theme: m.theme, camera: m.camera, gif: m.outputs.gif, thumb: m.outputs.thumbnail, stills: m.outputs.stills, video: src ? [src.size, Math.round(src.mtimeMs)] : null, tl: merged.timeline.map((t) => [t.start, t.end, t.label, t.caption, t.holdMs, t.camera]), trim: [merged.trimBefore, merged.duration] }));
+    h.update(JSON.stringify({ q, tempo: m.tempo, cap: m.captions, theme: m.theme, camera: m.camera, cards: [m.intro, m.outro], idle: m.compressIdle, vo: m.voiceover, music: m.music ? [m.music, (() => { try {
+                const f = typeof m.music === "string" ? m.music : m.music.file;
+                const st = fs.statSync(path.resolve(f));
+                return [st.size, Math.round(st.mtimeMs)];
+            }
+            catch {
+                return null;
+            } })()] : null, gif: m.outputs.gif, thumb: m.outputs.thumbnail, stills: m.outputs.stills, video: src ? [src.size, Math.round(src.mtimeMs)] : null, tl: merged.timeline.map((t) => [t.start, t.end, t.label, t.caption, t.holdMs, t.camera, t.callout]), trim: [merged.trimBefore, merged.duration] }));
     return h.digest("hex").slice(0, 12);
 }
 const require = createRequire(import.meta.url);
@@ -79,38 +91,6 @@ export function probe(file) {
     };
 }
 export const videoDuration = (file) => probe(file).duration;
-/** Word-wrap long captions; two-line captions break near the middle so no
-    word is left orphaned on the second line. */
-function wrap(text, max) {
-    if (text.length <= max)
-        return text;
-    const words = text.split(/\s+/);
-    if (text.length <= max * 2) {
-        let best = 1, bestDiff = Infinity;
-        for (let i = 1; i < words.length; i++) {
-            const a = words.slice(0, i).join(" ").length;
-            const b = words.slice(i).join(" ").length;
-            if (a <= max && b <= max && Math.abs(a - b) < bestDiff) {
-                best = i;
-                bestDiff = Math.abs(a - b);
-            }
-        }
-        return words.slice(0, best).join(" ") + "\n" + words.slice(best).join(" ");
-    }
-    const out = [];
-    let line = "";
-    for (const w of words) {
-        if (line && (line + " " + w).length > max) {
-            out.push(line);
-            line = w;
-        }
-        else
-            line = line ? line + " " + w : w;
-    }
-    if (line)
-        out.push(line);
-    return out.join("\n");
-}
 /** ffmpeg drawtext needs a few characters escaped inside the filter graph. */
 function esc(s) {
     return s.replace(/\\/g, "\\\\").replace(/'/g, "\u2019").replace(/:/g, "\\:").replace(/%/g, "\\%").replace(/,/g, "\\,");
@@ -148,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");
 }
@@ -265,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)
@@ -296,6 +334,21 @@ export async function render(m, take, outDir, opts = {}) {
     }
     // Captions, holds, camera zooms and trim come from the manifest as it is now.
     take = applyManifest(m, take);
+    // Idle compression: re-cut the source so the app's dead waits are shown
+    // short, and remap every clock in the take through the same warp.
+    let idleLines = [];
+    if (m.compressIdle && take.video) {
+        const keep = m.compressIdle === true ? 1.5 : m.compressIdle.keepSeconds;
+        const segs = planIdle(take, keep);
+        if (segs.length) {
+            const paced = path.join(outDir, ".paced.mp4");
+            ff([...warpFilterArgs(take.video, segs, take.duration, paced).slice(0, -1), "-r", String(resolve(m).fps), "-c:v", "libx264", "-crf", "14", "-preset", "veryfast", "-pix_fmt", "yuv420p", paced], log);
+            idleLines = describeIdle(take, segs);
+            for (const l of idleLines)
+                log?.(`idle: ${l}`);
+            take = { ...warpTake(take, segs), video: paced };
+        }
+    }
     // Tempo: the source is cut in its own time (-ss/-t below), then every
     // clock downstream — captions, camera keys, stills — runs in output time.
     const srcTake = take;
@@ -316,15 +369,18 @@ export async function render(m, take, outDir, opts = {}) {
         const to = sc[i + 1] ? sc[i + 1].start : take.duration;
         take = { ...take, trimBefore: from, duration: to };
     }
-    const src = path.resolve(srcVideo);
+    const src = path.resolve(take.video ?? srcVideo); // take.video may be the idle-warped re-cut
     // Source (recorded viewport) vs canvas (preset output). They differ when a
     // narrow app was recorded at its own aspect and gets centred on the canvas.
     const SW = take.quality?.width ?? q.viewport.width;
     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;
@@ -344,13 +400,22 @@ export async function render(m, take, outDir, opts = {}) {
     let frameInput = null;
     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, captionWindows(take).map((w) => w.text));
     if (layout === "band") {
-        // Site fills the frame; caption strip below it.
-        filters.push(`pad=${W}:${H + q.bandHeight}:0:0:color=${bg}`);
-        capY = `${H}+${q.bandHeight / 2}-th/2`;
+        // 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}:0:0:color=${bg}`);
+            capY = `${pageH}+${bandH / 2}-th/2`;
+        }
     }
     else if (layout === "card") {
-        geom = cardGeometry(W, H, SW, SH, q.bandHeight);
+        geom = cardGeometry(W, H, SW, SH, bandH);
         frameInput = path.join(outDir, ".frame.png");
         await renderCardFrame(frameInput, W, H, geom, bg);
         filters.push(`scale=${geom.vw}:${geom.vh}:flags=lanczos`, `pad=${W}:${H}:${geom.vx}:${geom.vy}:color=${bg}`);
@@ -361,19 +426,46 @@ 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 = Math.max(28, Math.round((W / capSize) * 1.55));
+        const maxChars = maxCharsFor(W, capSize);
         for (const w of captionWindows(take)) {
             captionFilters.push(`drawtext=${font}text='${esc(wrap(w.text, maxChars))}':fontsize=${capSize}:fontcolor=${capColor}${capBox}:line_spacing=${Math.round(capSize * 0.25)}` +
                 `:x=(w-tw)/2:y=${capY}:enable='between(t,${w.from.toFixed(2)},${w.to.toFixed(2)})'`);
         }
     }
-    const graph = frameInput
-        ? `[0:v]${filters.join(",")}[v];[v][1:v]overlay=0:0:format=auto${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
-        : `[0:v]${[...filters, ...captionFilters].join(",")}[out]`;
-    const inputs = ["-ss", srcTake.trimBefore.toFixed(3), "-t", (srcTake.duration - srcTake.trimBefore).toFixed(3), "-i", src, ...(frameInput ? ["-i", frameInput] : [])];
+    // Callouts: recorded boxes become animated overlays, applied in SOURCE
+    // coordinates (before the camera filter) so a moving camera carries them.
+    const callouts = take.timeline.filter((e) => e.callout && e.ok);
+    const calloutInputs = [];
+    let preCam = "";
+    if (callouts.length && !o.scene && !frameInput) {
+        const camIdx = cam.filter ? filters.indexOf(cam.filter) : filters.length;
+        const before = filters.slice(0, camIdx), after = filters.slice(camIdx);
+        let label = "b0";
+        let g = `[0:v]${before.join(",")}[${label}]`;
+        for (let i = 0; i < callouts.length; i++) {
+            const e = callouts[i];
+            const from = Math.max(0, e.start - take.trimBefore);
+            const webm = await renderCalloutOverlay(ffmpegBin(), outDir, i, e.callout, SW, SH, fps, Math.max(15, Math.round(q.captions ? q.captions.fontSize * 0.55 : 20)), ink);
+            calloutInputs.push(webm);
+            const inIdx = 1 + (frameInput ? 1 : 0) + i;
+            const next = `b${i + 1}`;
+            g += `;[${inIdx}:v]setpts=PTS+${from.toFixed(3)}/TB[c${i}];[${label}][c${i}]overlay=0:0:eof_action=pass[${next}]`;
+            label = next;
+        }
+        preCam = `${g};[${label}]${after.length ? after.join(",") : "null"}`;
+    }
+    const graph = preCam
+        ? `${preCam}${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
+        : frameInput
+            ? `[0:v]${filters.join(",")}[v];[v][1:v]overlay=0:0:format=auto${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
+            : `[0:v]${[...filters, ...captionFilters].join(",")}[out]`;
+    const inputs = ["-ss", srcTake.trimBefore.toFixed(3), "-t", (srcTake.duration - srcTake.trimBefore).toFixed(3), "-i", src, ...(frameInput ? ["-i", frameInput] : []), ...calloutInputs.flatMap((f) => ["-c:v", "libvpx-vp9", "-i", f])];
     const compose = ["-filter_complex", graph, "-map", "[out]", "-r", String(fps), "-an", "-pix_fmt", "yuv420p", "-movflags", "+faststart"];
     const x264 = (crf, preset) => ["-c:v", "libx264", "-crf", String(crf), "-preset", preset];
     // Hardware encode is a macOS thing; elsewhere the "fast" presets are a fast x264.
@@ -401,6 +493,98 @@ export async function render(m, take, outDir, opts = {}) {
     }
     if (frameInput)
         fs.rmSync(frameInput, { force: true });
+    for (const f of calloutInputs)
+        fs.rmSync(f, { force: true });
+    // Title cards: rendered at the finished frame size, spliced on. The intro's
+    // settled frame becomes cover.png — the poster.
+    let cover;
+    if ((m.intro || m.outro) && !o.scene) {
+        const dims = probe(mp4);
+        const segs = [];
+        if (m.intro) {
+            const c = await renderCard(ffmpegBin(), outDir, "intro", m.intro, dims.width, dims.height, fps, q.theme);
+            segs.push(c.mp4);
+            cover = c.cover;
+        }
+        segs.push(mp4);
+        if (m.outro)
+            segs.push((await renderCard(ffmpegBin(), outDir, "outro", m.outro, dims.width, dims.height, fps, q.theme)).mp4);
+        if (segs.length > 1) {
+            const joined = path.join(outDir, ".joined.mp4");
+            ff([...segs.flatMap((f) => ["-i", f]), "-filter_complex", `${segs.map((_, i) => `[${i}:v]`).join("")}concat=n=${segs.length}:v=1:a=0[out]`, "-map", "[out]", "-r", String(fps), "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-an", ...x264(q.crf, "medium"), joined], log);
+            fs.renameSync(joined, mp4);
+            for (const f of segs)
+                if (f !== mp4)
+                    fs.rmSync(f, { force: true });
+        }
+        mark("cards");
+    }
+    // Audio: the music bed and/or the captions read aloud, mixed in one pass.
+    // The deliverable gets it; the master stays a clean video-only source.
+    if ((m.music || m.voiceover) && !o.scene) {
+        const dur = probe(mp4).duration;
+        // Cards shift every scene: narration is placed in FINAL time.
+        const introShift = m.intro ? m.intro.ms / 1000 : 0;
+        const audioIn = [];
+        const chains = [];
+        const mixIns = [];
+        let idx = 1; // 0 is the video
+        if (m.music) {
+            const spec = typeof m.music === "string" ? { file: m.music, gainDb: -14, fadeOutMs: 1800 } : m.music;
+            const musicFile = path.resolve(expandEnv(spec.file));
+            if (!fs.existsSync(musicFile))
+                throw new Error(`music: no such file ${musicFile} — the track ships inside the video, so it must be one the person may use (CC0 or licensed)`);
+            const fadeStart = Math.max(0, dur - spec.fadeOutMs / 1000);
+            // Ducked a step further when a voice speaks over it.
+            const gain = spec.gainDb - (m.voiceover ? 7 : 0);
+            audioIn.push("-stream_loop", "-1", "-i", musicFile);
+            chains.push(`[${idx}:a]volume=${gain}dB,afade=t=in:st=0:d=0.6,afade=t=out:st=${fadeStart.toFixed(2)}:d=${(spec.fadeOutMs / 1000).toFixed(2)}[mus]`);
+            mixIns.push("[mus]");
+            idx++;
+        }
+        if (m.voiceover) {
+            const spec = m.voiceover === true ? { voice: DEFAULT_VOICE, gainDb: 0, script: undefined, fragments: true } : m.voiceover;
+            if (spec.script) {
+                // One script, one performance: prosody carries across the whole
+                // video the way a person reads. Starts after the title card.
+                const clip = path.join(outDir, ".vo-0.mp3");
+                synthesize(spec.script, spec.voice, clip);
+                const spoken = audioSeconds(ffmpegBin(), clip);
+                if (spoken > dur - introShift + 0.5)
+                    log?.(`voiceover: the script reads ${spoken.toFixed(1)}s but there are ${(dur - introShift).toFixed(1)}s of video after the title card — cut the script or lengthen the scenes, then re-render`);
+                audioIn.push("-i", clip);
+                chains.push(`[${idx}:a]volume=${spec.gainDb}dB,adelay=${Math.round(introShift * 1000)}:all=1[vo0]`);
+                mixIns.push("[vo0]");
+                idx++;
+            }
+            else {
+                // Explicitly-asked-for fragments: one clip per caption. Known to
+                // reset prosody at every line; the schema refuses it by default.
+                const wins = captionWindows(take);
+                for (let i = 0; i < wins.length; i++) {
+                    const w = wins[i];
+                    const clip = path.join(outDir, `.vo-${i}.mp3`);
+                    synthesize(w.text, spec.voice, clip);
+                    const spoken = audioSeconds(ffmpegBin(), clip);
+                    const at = w.from + introShift;
+                    if (spoken > w.to - w.from + 0.4)
+                        log?.(`voiceover: “${w.text.slice(0, 40)}…” runs ${spoken.toFixed(1)}s but its scene holds ${(w.to - w.from).toFixed(1)}s — lengthen the scene's holdMs or trailing wait and re-render`);
+                    audioIn.push("-i", clip);
+                    chains.push(`[${idx}:a]volume=${spec.gainDb}dB,adelay=${Math.round(at * 1000)}:all=1[vo${i}]`);
+                    mixIns.push(`[vo${i}]`);
+                    idx++;
+                }
+            }
+        }
+        const mixed = path.join(outDir, ".with-audio.mp4");
+        const graph = `${chains.join(";")};${mixIns.join("")}amix=inputs=${mixIns.length}:duration=longest:normalize=0,atrim=0:${dur.toFixed(2)}[a]`;
+        ff(["-i", mp4, ...audioIn, "-filter_complex", graph, "-map", "0:v", "-map", "[a]", "-c:v", "copy", "-c:a", "aac", "-b:a", "160k", "-movflags", "+faststart", "-shortest", mixed], log);
+        fs.renameSync(mixed, mp4);
+        for (const f of fs.readdirSync(outDir))
+            if (/^\.vo-\d+\.mp3$/.test(f))
+                fs.rmSync(path.join(outDir, f), { force: true });
+        mark("audio");
+    }
     if (o.scene)
         return { mp4, proofLog };
     // --- 3. GIF (secondary, opt-in) --------------------------------------------
@@ -429,9 +613,19 @@ export async function render(m, take, outDir, opts = {}) {
         }
         mark("gif");
     }
+    // Cards are spliced onto the front of the deliverable, so every timestamp
+    // in the take is that much later in the file frames are pulled from.
+    const cardShift = !o.scene && m.intro ? m.intro.ms / 1000 : 0;
     // --- 4. thumbnail ----------------------------------------------------------
+    // A person's chosen poster (the window's "Use this frame" / a still / an
+    // upload) outlives re-renders: the choice writes a .poster marker, and the
+    // scene-based default never overwrites a deliberate choice.
     let thumbnail;
-    if (m.outputs.thumbnail) {
+    if (m.outputs.thumbnail && fs.existsSync(path.join(outDir, ".poster")) && fs.existsSync(path.join(outDir, "thumbnail.png"))) {
+        thumbnail = path.join(outDir, "thumbnail.png");
+        log?.("thumbnail: keeping the poster you chose (delete .poster to go back to the scene default)");
+    }
+    else if (m.outputs.thumbnail) {
         const sc = scenes(take);
         let at;
         if (typeof m.outputs.thumbnail === "object") {
@@ -449,13 +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).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 && 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 });
@@ -470,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.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.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}`);
     }
@@ -489,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);
@@ -498,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))
@@ -537,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;
@@ -547,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
@@ -566,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");
@@ -601,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);
@@ -632,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",
         "",