wicked-garden 12.41.0 → 12.42.0

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.41.0"}], "version": "12.41.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.42.0"}], "version": "12.42.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.41.0",
+  "version": "12.42.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [12.42.0] — 2026-10-03
+
+### Changed
+- **Demo recorder: encodes while it records; no frame file touches disk.** Before, `scripts/demo/stage.mjs` wrote every changed screencast frame as a JPEG (q95, 1920x1080: ~8 MB/s, about 5 GB per 10-minute take) and `postprocess.mjs` encoded them afterwards from an ffconcat list. Now a 30 fps ticker hands the newest screencast picture to an ffmpeg child over stdin (`-f image2pipe`), which writes the take's master `segments/<key>/capture.mp4` live: H.264 at a near-lossless CRF 12 with one-second fragments (`+frag_keyframe+empty_moov`), so a take that dies leaves a file that plays up to its last complete second. Master frame k is the picture at t0 + k/30, so wall clock → video time stays one line and `videoClock()` keeps its contract (`outAt`, the trim, the time-lapse spans). `buildVideo()` is now a cut of the master: `trim` for the opening, a `select` that keeps one frame in `factor` across every `Stage.fast()` span and re-times the rest back to back, the chapter markers, the final CRF 17 pass; no frame files are read. Each segment keeps `capture.mp4` + `timeline.json` (what `--reencode` re-cuts from) in place of `frames/`; a failed take's `failed-<take>/` keeps the master only when no video could be cut from it, as it kept the frames. The timeline is rewritten at every mark, so a recorder killed mid-take leaves a cuttable master and clock. A dead encoder fails the take at its next step (`encoder_failed`) instead of filming into nothing. `DEMO_KEEP_FRAMES=1` also dumps every screencast frame to `frames/` (with `timeline.json` `frames` timestamps) for debugging. Measured on one take against the 12.41.0 recipe run on the same frames: see `tests/demo/test_live_encode.py` (SSIM against the frames recipe and against a lossless build of the frames; the pipe's video is as close to the frames as the single-encode recipe was). `contact_sheet.py` already read the video. Timelines recorded by earlier versions (frames, no master) are not re-cut: re-record the segment.
+
 ## [12.41.0] — 2026-10-03
 
 ### Added
@@ -966,7 +971,8 @@ through `v9.2.18`. Major themes across that span:
 
 For each of those releases, see the corresponding tag in git history.
 
-[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...HEAD
+[12.42.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...v12.42.0
 [12.41.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.40.0...v12.41.0
 [12.40.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.39.0...v12.40.0
 [12.39.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.38.1...v12.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.41.0",
+  "version": "12.42.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/demo/postprocess.mjs

@@ -1,60 +1,91 @@
-// Part of the wicked-garden-demo skill. Turns a recorded timeline (frames + marks) into a 1080p H.264 MP4 with chapter markers.
+// Part of the wicked-garden-demo skill. Cuts a take's master (capture.mp4 + timeline.json) into a 1080p H.264 MP4
+// with chapter markers.
 //
-// Each screencast frame lasts until the next one; spans marked by Stage.fast() are compressed by their factor,
-// so long model waits play as a visible time-lapse while the on-screen badge states the real elapsed time.
+// The master is the take at a constant FPS, encoded live while it recorded (stage.mjs): frame k is the picture at
+// t0 + k/FPS, so wall clock and master time are the same line. The cut drops the opening trim, keeps one frame in
+// `factor` across every span marked by Stage.fast() and re-times what is left back to back, so long model waits play
+// as a visible time-lapse while the on-screen badge states the real elapsed time; the chapter marks land where
+// videoClock().outAt() says. No frame file is read or written.
 // Usage: wicked-garden run scripts/demo/postprocess.mjs <outDir> [output.mp4]
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
-const FPS = 30;
+/** The master's constant frame rate. */
+export const FPS = 30;
+/** The master's file name inside a take's directory. */
+export const CAPTURE = "capture.mp4";
+/** ffprobe beside a given ffmpeg binary (`FFMPEG=/path/to/ffmpeg` is honoured for both). */
+export const ffprobeOf = (ffmpeg) => ffmpeg.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1");
 
 /**
- * The video clock of a timeline: the frames buildVideo keeps, the time-lapse spans, and `outAt(t)`, the
- * position in the built video (seconds) of a wall-clock instant `t`. Throws when no frame is kept.
+ * The video clock of a timeline, in master frames so it agrees with the cut to the frame: `inFrame`, the first
+ * master frame kept; `spans`, the time-lapse spans as [a, b) frame ranges with their factor; `keptBefore(k)`, how many
+ * cut frames precede master frame k; and `outAt(t)`, the position in the cut video (seconds) of a wall-clock instant.
+ * Throws when a closed take says nothing was recorded past the trim; a timeline a killed take left (no frame count)
+ * is clocked from its t0 and the master is counted by buildVideo.
  */
 export function videoClock(tl, trimStart = 0) {
-  const frames = tl.frames.filter((f) => f.t >= tl.t0 + trimStart);
-  if (!frames.length) throw new Error("no frames recorded");
-  const speed = [...tl.marks.speed].sort((a, b) => a.start - b.start);
-
-  // Output time for a wall-clock instant: integrate 1/factor over the marked spans.
-  const origin = frames[0].t;
-  const outAt = (t) => {
-    let out = t - origin;
-    for (const s of speed) {
-      const a = Math.max(s.start, origin), b = Math.min(s.end, t);
-      if (b > a) out -= (b - a) * (1 - 1 / s.factor);
+  const fps = tl.capture?.fps ?? FPS;
+  const inFrame = Math.max(0, Math.ceil(trimStart * fps - 1e-9));
+  if (typeof tl.capture?.frames === "number" && tl.capture.frames <= inFrame) throw new Error("no frames recorded");
+  const toFrame = (t) => Math.round((t - tl.t0) * fps);
+  // Inside a span only frame a and every frame where floor((k - a) / factor) advances are kept: one in `factor`.
+  // Spans never overlap here: a later span starts where the one before it ends (a nested Stage.fast() counts once).
+  const spans = [];
+  for (const s of [...tl.marks.speed].sort((x, y) => x.start - y.start)) {
+    const a = Math.max(inFrame, toFrame(s.start), spans.length ? spans[spans.length - 1].b : 0), b = toFrame(s.end);
+    if (b > a && s.factor > 1) spans.push({ a, b, f: s.factor });
+  }
+  const keptIn = (a, b, f) => (b > a ? Math.floor((b - a - 1) / f) + 1 : 0);
+  const keptBefore = (k) => {
+    let kept = Math.max(0, k - inFrame);
+    for (const s of spans) {
+      const b = Math.min(s.b, k);
+      if (b > s.a) kept -= (b - s.a) - keptIn(s.a, b, s.f);
     }
-    return out;
+    return kept;
   };
-  return { frames, speed, outAt };
+  const outAt = (t) => keptBefore(toFrame(t)) / fps;
+  return { inFrame, fps, spans, keptIn, keptBefore, outAt, speed: tl.marks.speed };
+}
+
+/** Frames in the master, by demuxing it (exact for a master whose writer died: the complete packets count). */
+function countFrames(ffprobe, file) {
+  const r = spawnSync(ffprobe, ["-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", file],
+    { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${(r.error?.message ?? r.stderr ?? "").slice(-500)}`);
+  const n = Number(r.stdout.trim());
+  if (!Number.isInteger(n)) throw new Error(`ffprobe gave no frame count for ${file}: ${r.stdout.slice(0, 200)}`);
+  return n;
 }
 
 export function buildVideo(outDir, outFile, { ffmpeg = process.env.FFMPEG || "ffmpeg", tail = 0.2, trimStart = 0 } = {}) {
   const tl = JSON.parse(fs.readFileSync(path.join(outDir, "timeline.json"), "utf8"));
-  const { frames, speed, outAt } = videoClock(tl, trimStart);
-
-  // Resample to constant frame rate: output tick k shows the newest frame captured at or before k/FPS, and each
-  // run of identical picks becomes one concat entry lasting (run length / FPS). Bursts collapse, gaps hold.
-  const outTimes = frames.map((f) => outAt(f.t));
-  // The screencast only emits a frame when the picture changes, so a static hold at the end (a closing card, a final
-  // pause) has no frame of its own: end at the moment recording stopped, not at the last captured frame.
-  const total = Math.max(outTimes[outTimes.length - 1] + 1 / FPS, outAt(tl.tEnd ?? frames[frames.length - 1].t)) + tail;
-  const ticks = Math.ceil(total * FPS);
-  const runs = [];
-  for (let k = 0, i = 0; k < ticks; k++) {
-    while (i + 1 < frames.length && outTimes[i + 1] <= k / FPS) i++;
-    if (runs.length && runs[runs.length - 1].i === i) runs[runs.length - 1].n++;
-    else runs.push({ i, n: 1 });
+  const capture = path.join(outDir, tl.capture?.file ?? CAPTURE);
+  if (!fs.existsSync(capture)) {
+    throw new Error(tl.capture?.error ?? `${path.basename(capture)} not found in ${outDir}` +
+      (Array.isArray(tl.frames) && !tl.capture ? " (recorded from frames by an earlier version; re-record the segment)" : ""));
   }
-  const lines = ["ffconcat version 1.0"];
-  for (const r of runs) lines.push(`file 'frames/${frames[r.i].file}'`, `duration ${(r.n / FPS).toFixed(6)}`);
-  lines.push(`file 'frames/${frames[runs[runs.length - 1].i].file}'`); // concat demuxer needs the last file repeated
-  fs.writeFileSync(path.join(outDir, "frames.ffconcat"), lines.join("\n"));
+  const { inFrame, fps, spans, keptBefore, outAt, speed } = videoClock(tl, trimStart);
+  // What the master holds is what counts: an encoder that died late still left playable fragments to cut, and its
+  // failure is the explanation only when nothing can be.
+  let nFrames;
+  try { nFrames = countFrames(ffprobeOf(ffmpeg), capture); } catch (e) { throw new Error(tl.capture?.error ?? e.message); }
+  if (nFrames <= inFrame) throw new Error(tl.capture?.error ?? "no frames recorded");
+
+  // Master frame k is the picture at t0 + k/fps. Inside a marked span one frame in `factor` is kept; the kept frames
+  // are re-timed back to back at fps. In the select expression n counts frames after the trim (n = k - inFrame).
+  const keep = spans.filter((s) => s.a < nFrames).reduce((rest, s) => {
+    const a = s.a - inFrame, b = Math.min(s.b, nFrames) - inFrame - 1;
+    return `if(between(n\\,${a}\\,${b})\\,gt(floor((n-${a})/${s.f})\\,floor((n-${a}-1)/${s.f}))\\,${rest})`;
+  }, "1");
+  const kept = keptBefore(nFrames);
+  const total = kept / fps + tail;
 
-  const chapters = tl.marks.chapters.map((c) => ({ ...c, out: Math.max(0, outAt(c.t)) }));
+  // A chapter marked after the master's last frame (a take killed within the second) sits at the end, not past it.
+  const chapters = tl.marks.chapters.map((c) => ({ ...c, out: Math.min(Math.max(0, outAt(c.t)), kept / fps) }));
   const meta = [";FFMETADATA1", `title=${(tl.title || "Demo").replace(/[=;#\\\n]/g, " ")}`];
   chapters.forEach((c, i) => {
     const start = Math.round(c.out * 1000), end = Math.round((i + 1 < chapters.length ? chapters[i + 1].out : total) * 1000);
@@ -62,15 +93,18 @@ export function buildVideo(outDir, outFile, { ffmpeg = process.env.FFMPEG || "ff
   });
   fs.writeFileSync(path.join(outDir, "chapters.ffmeta"), meta.join("\n") + "\n");
 
-  const args = ["-y", "-f", "concat", "-safe", "0", "-i", "frames.ffconcat", "-i", "chapters.ffmeta", "-map_metadata", "1", "-map_chapters", "1",
-    "-t", total.toFixed(3), "-vf", `fps=${FPS},format=yuv420p`, "-c:v", "libx264", "-preset", "slow", "-crf", "17", "-tune", "stillimage", "-movflags", "+faststart", path.resolve(outFile)];
+  // tpad holds the last picture for `tail` (a static close has frames of its own in the master, but the cut
+  // should not end on the very tick recording stopped).
+  const vf = `trim=start_frame=${inFrame},select='${keep}',setpts=N/(${fps}*TB),tpad=stop_mode=clone:stop_duration=${tail.toFixed(3)},format=yuv420p`;
+  const args = ["-y", "-i", capture, "-i", "chapters.ffmeta", "-map_metadata", "1", "-map_chapters", "1", "-vf", vf, "-r", String(fps), "-fps_mode", "cfr",
+    "-c:v", "libx264", "-preset", "slow", "-crf", "17", "-tune", "stillimage", "-movflags", "+faststart", path.resolve(outFile)];
   const r = spawnSync(ffmpeg, args, { cwd: outDir, stdio: ["ignore", "ignore", "pipe"] });
-  if (r.status !== 0) throw new Error(`ffmpeg failed: ${r.stderr?.toString().slice(-2000)}`);
+  if (r.status !== 0) throw new Error(`ffmpeg failed: ${(r.error?.message ?? r.stderr?.toString() ?? "").slice(-2000)}`);
 
   const fmt = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
   const md = ["| Time | Chapter |", "|---|---|", ...chapters.map((c) => `| ${fmt(c.out)} | ${c.title} |`)];
   fs.writeFileSync(path.join(outDir, "chapters.md"), md.join("\n") + "\n");
-  return { seconds: total, chapters: chapters.map((c) => ({ at: fmt(c.out), title: c.title })), speedups: speed.length, frames: frames.length };
+  return { seconds: total, chapters: chapters.map((c) => ({ at: fmt(c.out), title: c.title })), speedups: speed.length, frames: nFrames - inFrame };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {

package/scripts/demo/record.mjs

@@ -10,14 +10,15 @@
 // segments/<key>/failed-<take>/ and is never stitched.
 //
 // Each non-intro segment opens on its own chapter slide (the storyline's beforeSegment hook runs behind it) and ends
-// on the plain stage background, so segments join with a clean cut. Frames and timelines are kept per segment, so a
-// segment can be re-recorded alone and the whole video re-encoded without recording again.
+// on the plain stage background, so segments join with a clean cut. Each segment keeps its master (capture.mp4,
+// encoded live while it recorded) and timeline.json, so a segment can be re-recorded alone and the whole video
+// re-cut (--reencode) without recording again. No frame files are written (DEMO_KEEP_FRAMES=1 dumps them for debugging).
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { Stage } from "./stage.mjs";
-import { buildVideo, videoClock } from "./postprocess.mjs";
+import { buildVideo, videoClock, CAPTURE, ffprobeOf } from "./postprocess.mjs";
 import { fixtureOrigin, sideEffectError } from "./readonly.mjs";
 
 // ---- module-level constants (used by exports) --------------------------------------------------
@@ -125,12 +126,15 @@ export function makeSegmentRecorder({
     let videoError = null;
     if (fs.existsSync(tlPath)) {
       fs.renameSync(tlPath, path.join(dir, "timeline.json"));
-      if (fs.existsSync(path.join(localSegDir(key), "frames"))) fs.renameSync(path.join(localSegDir(key), "frames"), path.join(dir, "frames"));
+      // The master (and the frames dump, if any) go with the timeline; they are dropped once a video is built from them.
+      for (const f of [CAPTURE, "frames"]) {
+        if (fs.existsSync(path.join(localSegDir(key), f))) fs.renameSync(path.join(localSegDir(key), f), path.join(dir, f));
+      }
       try {
         buildVideo(dir, path.join(dir, "segment.mp4"), { trimStart, ffmpeg: FFMPEG_BIN });
         video = "segment.mp4";
+        fs.rmSync(path.join(dir, CAPTURE), { force: true });
         fs.rmSync(path.join(dir, "frames"), { recursive: true, force: true });
-        fs.rmSync(path.join(dir, "frames.ffconcat"), { force: true });
       } catch (e) {
         videoError = e.message;
         fs.rmSync(path.join(dir, "segment.mp4"), { force: true });
@@ -159,14 +163,15 @@ export function makeSegmentRecorder({
     console.log(`● ${seg.key} (take ${take})`);
     const stage = new Stage({
       baseUrl, outDir: localSegDir(seg.key), chapters: CHAPTERS_LIST, brand,
-      stickyOffset: story.stickyOffset, headful: process.env.DEMO_HEADFUL === "1",
-      locale: story.locale, timezoneId: story.timezoneId, writableOrigin, consoleHandler,
+      stickyOffset: story.stickyOffset, headful: process.env.DEMO_HEADFUL === "1", keepFrames: process.env.DEMO_KEEP_FRAMES === "1",
+      locale: story.locale, timezoneId: story.timezoneId, writableOrigin, consoleHandler, ffmpeg: FFMPEG_BIN,
     });
     const timings = {};
     let ctx = makeCtx(stage, timings);
     fs.mkdirSync(localSegDir(seg.key), { recursive: true });
     fs.rmSync(localSegVideo(seg.key), { force: true });
     fs.rmSync(path.join(localSegDir(seg.key), "timeline.json"), { force: true });
+    fs.rmSync(path.join(localSegDir(seg.key), CAPTURE), { force: true });
     let failure = null;
     let failedAt = null;
     try {
@@ -203,7 +208,8 @@ export function makeSegmentRecorder({
     } finally {
       await stage.close().catch(() => {});
     }
-    let err = failure;
+    // An encoder that failed while close() drained it is a failed take too: its master may be short of the end.
+    let err = failure ?? stage.encoderError ?? null;
     if (stage.blocked.length) {
       err = sideEffectError(seg.key, stage.blocked);
       if (failure !== null) err.cause = failure;
@@ -235,7 +241,7 @@ export function makeSegmentRecorder({
 // ---- CLI entry point (only runs when invoked directly) -----------------------------------------
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const FFMPEG = process.env.FFMPEG || "ffmpeg";
-  const FFPROBE = FFMPEG.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1");
+  const FFPROBE = ffprobeOf(FFMPEG);
 
   function usage(msg) {
     if (msg) console.error(`error: ${msg}\n`);

package/scripts/demo/stage.mjs

@@ -2,14 +2,26 @@
 //
 // The app runs inside a 1600x900 browser-window frame on a 1920x1080 stage page; the lower-third caption band,
 // cursor, callouts and title cards are stage DOM, so captions never cover the product UI and everything is
-// rendered with real fonts and CSS transitions. Frames come from the Chrome DevTools screencast (JPEG q95,
-// wall-clock timestamps) instead of Playwright's built-in recorder, whose fixed ~1 Mbps VP8 blurs text at
-// 1080p. postprocess.mjs turns the frames into an H.264 MP4, time-lapsing the marked waits and embedding
-// chapter markers.
+// rendered with real fonts and CSS transitions. Pictures come from the Chrome DevTools screencast (JPEG q95, one
+// per change) instead of Playwright's built-in recorder, whose fixed ~1 Mbps VP8 blurs text at 1080p.
+//
+// Nothing raw touches disk. A 30 fps ticker hands the newest screencast picture to an ffmpeg child over stdin
+// (`-f image2pipe`), which encodes the master `capture.mp4` while the take runs: H.264 at a near-lossless CRF 12
+// (so the master is never the step that softens text; the final CRF 17 pass happens once, in the cut), one-second
+// fragments (a take that dies leaves a file that plays up to its last complete second). Master frame k is the
+// picture at t0 + k/30, so wall clock → master time is one straight line and postprocess.mjs cuts the master into
+// segment.mp4: the opening trim, the marked waits time-lapsed, chapter markers, and the clock videoClock() gives.
+// The ticker re-sends the current picture when nothing changed, which is the constant-frame-rate resampling the
+// cut used to do from timestamps ("the newest frame at or before each tick"), done live. Before this, every
+// changed frame was written as a JPEG and encoded afterwards: ~8 MB/s, about 5 GB per 10-minute take.
+// DEMO_KEEP_FRAMES=1 (keepFrames) also writes every screencast frame to frames/ with its timestamp in
+// timeline.json, for looking at what the screencast delivered; the master is still what gets cut.
 import { loadChromium } from "./_playwright.mjs";
 import { armGuard } from "./readonly.mjs";
+import { CAPTURE, FPS } from "./postprocess.mjs";
 import fs from "node:fs";
 import path from "node:path";
+import { spawn } from "node:child_process";
 
 // Served from the app's own origin (route interception), so the app iframe is same-origin with the stage.
 const STAGE_PATH = "/__demo_stage__";
@@ -130,6 +142,28 @@ window.__stage={
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+// The master: near-lossless, fast enough to keep up with 30 fps on a busy host, a keyframe (= a fragment) every second.
+const MASTER_ARGS = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-tune", "stillimage", "-g", String(FPS), "-keyint_min", String(FPS),
+  "-pix_fmt", "yuv420p", "-movflags", "+frag_keyframe+empty_moov+default_base_moof"];
+// Frames waiting on the encoder: above WARN the take says so when it closes; above FAIL (about half a minute of
+// 1080p pictures) the host cannot encode live and the take fails rather than grow without bound.
+const BACKLOG_WARN = 32 * 1024 * 1024;
+const BACKLOG_FAIL = 256 * 1024 * 1024;
+
+function encoderFailure(message) {
+  const e = new Error(message);
+  e.code = "encoder_failed";
+  return e;
+}
+
+function withTimeout(promise, ms, message) {
+  let timer;
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); }),
+  ]);
+}
+
 export class Stage {
   /**
    * @param {object} o
@@ -140,10 +174,15 @@ export class Stage {
    * @param {number} [o.stickyOffset=88]  px to leave above a tall element when scrolling it into view (app header)
    * @param {boolean} [o.headful=false]   show the browser window while recording
    * @param {string|null} [o.writableOrigin=null]  the fixture origin writes may go to (readonly.mjs fixtureOrigin); null = read-only
+   * @param {string} [o.ffmpeg]           ffmpeg binary for the live master (default FFMPEG env or "ffmpeg")
+   * @param {boolean} [o.keepFrames=false]  also write every screencast frame to frames/ (debugging; DEMO_KEEP_FRAMES=1)
    */
-  constructor({ baseUrl, outDir, chapters, brand, stickyOffset = 88, headful = false, locale = "en-US", timezoneId, writableOrigin = null, consoleHandler = null }) {
+  constructor({ baseUrl, outDir, chapters, brand, stickyOffset = 88, headful = false, locale = "en-US", timezoneId, writableOrigin = null, consoleHandler = null,
+    ffmpeg = process.env.FFMPEG || "ffmpeg", keepFrames = false }) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.outDir = outDir;
+    this.ffmpeg = ffmpeg;
+    this.keepFrames = keepFrames;
     this.brand = { name: brand?.name ?? "Demo", logoSvg: brand?.logoSvg ?? "", accent: brand?.accent ?? "#ee0000" };
     this.chapterNames = chapters;
     this.stickyOffset = stickyOffset;
@@ -155,13 +194,18 @@ export class Stage {
     this.blocked = [];
     this.consoleHandler = consoleHandler;
     this.marks = { chapters: [], speed: [], captions: [] };
-    this.frameCount = 0;
     this.chapterIndex = -1;
+    this.latest = null; // the newest screencast picture (JPEG bytes)
+    this.emitted = 0; // master frames handed to the encoder
+    this.maxBacklog = 0; // most bytes ever waiting on the encoder
+    this.encoderError = null;
   }
 
   async open(firstPath = "/") {
-    fs.mkdirSync(path.join(this.outDir, "frames"), { recursive: true });
-    for (const f of fs.readdirSync(path.join(this.outDir, "frames"))) fs.unlinkSync(path.join(this.outDir, "frames", f));
+    fs.mkdirSync(this.outDir, { recursive: true });
+    fs.rmSync(path.join(this.outDir, "frames"), { recursive: true, force: true });
+    fs.rmSync(path.join(this.outDir, CAPTURE), { force: true });
+    if (this.keepFrames) fs.mkdirSync(path.join(this.outDir, "frames"));
     this.frames = [];
     this.browser = await (await loadChromium()).launch({ headless: !this.headful, args: ["--force-color-profile=srgb", "--hide-scrollbars"] });
     // A service worker answers requests the context's routes never see, so a guarded recording runs without one.
@@ -184,23 +228,90 @@ export class Stage {
     this.app = this.page.frameLocator("#app");
     this.appFrame = await (await this.page.$("#app")).contentFrame();
     await this.appFrame.waitForLoadState("networkidle").catch(() => {});
-    // Screencast: every changed frame with its wall-clock timestamp (seconds).
+    // Screencast: every changed picture, kept as "the newest" for the ticker (and on disk only with keepFrames).
     this.cdp = await this.context.newCDPSession(this.page);
-    this.cdp.on("Page.screencastFrame", async (ev) => {
-      const name = `f${String(this.frameCount++).padStart(6, "0")}.jpg`;
-      fs.writeFileSync(path.join(this.outDir, "frames", name), Buffer.from(ev.data, "base64"));
-      this.frames.push({ file: name, t: ev.metadata.timestamp });
-      await this.cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {});
+    let gotFirst;
+    const first = new Promise((resolve) => { gotFirst = resolve; });
+    this.cdp.on("Page.screencastFrame", (ev) => {
+      // Frames due before this picture existed show the previous one: a change lands at its own time, never early.
+      if (this.ticker) this.emitUpTo(Math.min(ev.metadata.timestamp, this.now()));
+      this.latest = Buffer.from(ev.data, "base64");
+      if (this.keepFrames) {
+        const name = `f${String(this.frames.length).padStart(6, "0")}.jpg`;
+        fs.writeFileSync(path.join(this.outDir, "frames", name), this.latest);
+        this.frames.push({ file: name, t: ev.metadata.timestamp });
+      }
+      gotFirst();
+      this.cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {});
     });
     await this.cdp.send("Page.startScreencast", { format: "jpeg", quality: 95, maxWidth: W, maxHeight: H, everyNthFrame: 1 });
-    this.t0 = Date.now() / 1000;
+    await withTimeout(first, 15_000, "the screencast delivered no frame within 15 s");
+    // The master: frame k is the picture at t0 + k/FPS. Frames fall due with the clock; whatever is due is sent at
+    // each tick and before each new picture (so a late tick costs no time and shifts nothing earlier).
+    this.encoder = this.startEncoder();
+    this.t0 = this.now();
+    this.ticker = setInterval(() => this.emitUpTo(this.now()), 1000 / FPS);
+    this.emitUpTo(this.t0); // frame 0
+    this.writeTimeline(false);
     this.cursorAt = { x: FRAME.x + FRAME.w / 2, y: FRAME.y + FRAME.h / 2 };
     await this.stage((s, c) => s.cursor(c.x, c.y, false), this.cursorAt);
   }
 
+  startEncoder() {
+    const child = spawn(this.ffmpeg, ["-y", "-v", "error", "-f", "image2pipe", "-framerate", String(FPS), "-i", "-", ...MASTER_ARGS, path.join(this.outDir, CAPTURE)],
+      { stdio: ["pipe", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr = (stderr + d).slice(-2000); });
+    child.stdin.on("error", () => {}); // EPIPE once the encoder is gone: the exit handler reports why
+    const done = new Promise((resolve) => {
+      child.on("error", (e) => { this.encoderError ??= encoderFailure(`ffmpeg failed to start: ${e.message}`); resolve(); });
+      child.on("exit", (code, signal) => {
+        if (code !== 0) this.encoderError ??= encoderFailure(`ffmpeg failed (${signal ?? code}): ${stderr.trim()}`);
+        resolve();
+      });
+    });
+    return { child, done };
+  }
+
+  /** Hands the encoder every master frame due by wall-clock instant t, each showing the current picture. */
+  emitUpTo(t) {
+    if (this.encoderError || !this.latest) return;
+    const due = Math.floor((t - this.t0) * FPS) + 1 - this.emitted;
+    if (due <= 0) return;
+    const { stdin } = this.encoder.child;
+    for (let i = 0; i < due; i++) stdin.write(this.latest);
+    this.emitted += due;
+    this.maxBacklog = Math.max(this.maxBacklog, stdin.writableLength);
+    if (stdin.writableLength > BACKLOG_FAIL) {
+      this.encoderError = encoderFailure(`ffmpeg fell ${Math.round(stdin.writableLength / 1048576)} MB of frames behind real time: this host cannot encode 1080p at 30 fps live`);
+      this.encoder.child.kill("SIGKILL");
+    }
+  }
+
+  /** The take's clock and marks so far (tEnd and the frame count only once closed): a killed take still leaves what
+   *  the cut needs, and postprocess counts the master's frames itself. */
+  writeTimeline(final) {
+    const meta = {
+      t0: this.t0, tEnd: final ? this.tEnd : null,
+      capture: { file: CAPTURE, fps: FPS, ...(final ? { frames: this.emitted } : {}), maxBacklogBytes: this.maxBacklog, ...(this.encoderError ? { error: this.encoderError.message } : {}) },
+      marks: this.marks, size: { w: W, h: H },
+      ...(this.keepFrames ? { frames: this.frames } : {}),
+    };
+    fs.writeFileSync(path.join(this.outDir, "timeline.json"), JSON.stringify(meta, null, 1));
+    return meta;
+  }
+
+  mark(kind, m) {
+    this.marks[kind].push(m);
+    if (this.t0 !== undefined) this.writeTimeline(false);
+  }
+
+  /** A dead encoder fails the take at its next step instead of filming ten minutes into nothing. */
+  check() { if (this.encoderError) throw this.encoderError; }
+
   now() { return Date.now() / 1000; }
-  stage(fn, arg) { return this.page.evaluate(`(${fn.toString()})(window.__stage, ${JSON.stringify(arg ?? null)})`); }
-  hold(ms) { return sleep(ms); }
+  stage(fn, arg) { this.check(); return this.page.evaluate(`(${fn.toString()})(window.__stage, ${JSON.stringify(arg ?? null)})`); }
+  hold(ms) { this.check(); return sleep(ms); }
 
   async card(html, ms) {
     await this.stage((s, h) => s.card(h), html);
@@ -210,13 +321,13 @@ export class Stage {
 
   async chapter(i) {
     this.chapterIndex = i;
-    this.marks.chapters.push({ t: this.now(), title: this.chapterNames[i] });
+    this.mark("chapters", { t: this.now(), title: this.chapterNames[i] });
     await this.stage((s, a) => s.progress(a.n, a.i, a.label), { n: this.chapterNames.length, i, label: `Chapter ${i + 1} of ${this.chapterNames.length} · ${this.chapterNames[i]}` });
   }
 
   /** Lower-third caption. body may contain <em>. readMs is how long the viewer needs it (scaled by length when omitted). */
   async caption(kicker, title, body = "", readMs) {
-    this.marks.captions.push({ t: this.now(), kicker, title, body });
+    this.mark("captions", { t: this.now(), kicker, title, body });
     await this.stage((s, c) => s.caption(c), { kicker, title, body });
     await sleep(readMs ?? Math.min(9000, 2200 + (title.length + body.length) * 38));
   }
@@ -292,7 +403,7 @@ export class Stage {
     await sleep(600);
     const t = this.now();
     try { return await fn(); } finally {
-      this.marks.speed.push({ start: t, end: this.now(), factor, label });
+      this.mark("speed", { start: t, end: this.now(), factor, label });
       await sleep(400);
       await this.stage((s) => s.speed(false));
       await sleep(400);
@@ -302,15 +413,24 @@ export class Stage {
   async close() {
     // Also after an open() that failed part-way: close what was opened, and write a timeline only once recording began.
     let meta = null;
-    if (this.cdp) {
-      await sleep(600);
-      await this.cdp.send("Page.stopScreencast").catch(() => {});
-      await sleep(300);
+    if (this.ticker) {
+      await sleep(600); // the last picture settles before the master stops
+      clearInterval(this.ticker);
+      this.ticker = null;
+      this.tEnd = this.now();
+      this.emitUpTo(this.tEnd);
     }
-    if (this.t0 !== undefined) {
-      meta = { t0: this.t0, tEnd: this.now(), frames: this.frames, marks: this.marks, size: { w: W, h: H } };
-      fs.writeFileSync(path.join(this.outDir, "timeline.json"), JSON.stringify(meta, null, 1));
+    if (this.cdp) await this.cdp.send("Page.stopScreencast").catch(() => {});
+    if (this.encoder) {
+      // EOF, then the encoder writes what it still holds and closes the file.
+      this.encoder.child.stdin.end();
+      await withTimeout(this.encoder.done, 120_000, "ffmpeg did not finish").catch((e) => {
+        this.encoderError ??= encoderFailure(`${e.message}: killed`);
+        this.encoder.child.kill("SIGKILL");
+      });
+      if (this.maxBacklog > BACKLOG_WARN) console.warn(`  encoder fell behind real time (up to ${Math.round(this.maxBacklog / 1048576)} MB of frames waited); the master is complete`);
     }
+    if (this.t0 !== undefined) meta = this.writeTimeline(true);
     await this.context?.close().catch(() => {});
     await this.browser?.close().catch(() => {});
     return meta;

package/skills/demo/SKILL.md

@@ -6,8 +6,8 @@ description: |
   alternates, runs a live rehearsal with measured timings, and writes a
   presenter script with a chapter list ready for recording.
   record — records each chapter as its own captioned, chaptered segment via
-  Playwright + ffmpeg (DevTools frames at JPEG q95, H.264 CRF 17), then
-  stitches them into one MP4 with chapter markers.
+  Playwright + ffmpeg (DevTools screencast encoded live to H.264, no frame
+  files on disk, final CRF 17), then stitches them into one MP4 with chapters.
   review — generates labelled contact sheets of stills (at chapter slides,
   joins, and the end) and delivers a per-issue verdict: re-encode, re-record
   one segment, or fix the app.
@@ -192,12 +192,21 @@ wicked-garden run scripts/demo/record.mjs <storyline.mjs>              # record
 wicked-garden run scripts/demo/record.mjs <storyline.mjs> 03-search    # (re)record one segment, restitch
 wicked-garden run scripts/demo/record.mjs <storyline.mjs> --all        # re-record everything
 wicked-garden run scripts/demo/record.mjs <storyline.mjs> --stitch     # stitch existing segments only
-wicked-garden run scripts/demo/record.mjs <storyline.mjs> --reencode   # rebuild from saved frames, restitch
+wicked-garden run scripts/demo/record.mjs <storyline.mjs> --reencode   # re-cut from each segment's saved master, restitch
 wicked-garden run scripts/demo/record.mjs <storyline.mjs> --list       # which segments are recorded
 ```
 
 Options: `--out <dir>` (default `demo-video/` next to the storyline), `--fixture-origin <origin>` (see below).
-Environment: `FFMPEG`, `DEMO_BASE_URL`, `DEMO_HEADFUL=1`.
+Environment: `FFMPEG`, `DEMO_BASE_URL`, `DEMO_HEADFUL=1`, `DEMO_KEEP_FRAMES=1` (debugging only, see below).
+
+**Encoded while it records; no frame files.** The screencast is fed to ffmpeg at 30 fps as the take runs and lands
+as `segments/<key>/capture.mp4`, a near-lossless H.264 master (CRF 12, one-second fragments) whose frame k is the
+picture at t0 + k/30; the segment video is a cut of that master (opening trim, time-lapsed waits, chapters, CRF 17).
+A take leaves about two videos' worth of bytes, not a JPEG per frame (which was ~8 MB/s, ~5 GB per 10-minute take).
+A take that is killed still leaves a master that plays up to its last complete second, and the timeline written so
+far, so `--reencode` can cut it. `DEMO_KEEP_FRAMES=1` additionally writes every screencast frame to
+`segments/<key>/frames/` (with timestamps in `timeline.json`) to look at what the screencast delivered — use it on a
+short take only; the master is still what gets cut.
 
 **Read-only by default.** While it records, the browser sends no writes: every request that is not
 GET, HEAD or OPTIONS is aborted, and so is every WebSocket frame the page sends (frames the server pushes
@@ -214,7 +223,7 @@ switch. `recording.json` records how each stitched segment was recorded (`read-o
 `fixture-writable`), and each segment's `guard.json` names the origin.
 
 **A failed take keeps its evidence.** When a take fails (an error, or a blocked write), its timeline,
-a video built from the frames it has, and `failure.json` (the error, any blocked requests,
+a video cut from the master it has, and `failure.json` (the error, any blocked requests,
 `failed_at_sec`) are kept in `segments/<key>/failed-<take>/`. Nothing of it is left where a stitch could
 use it: the segment's old `segment.mp4` is deleted, and while any segment's last take failed, `--reencode`
 and `--stitch` refuse to run (`failed_take`, or `side_effect_blocked` for a blocked write). Re-record it

package/skills/demo/refs/gotchas.md

@@ -5,17 +5,24 @@ time; read this before the first long run.
 
 ## Capture and encoding
 
+**The disk fills while recording (gigabytes per take).**
+Cause: a screencast frame written to disk as a JPEG per change is ~8 MB/s at 1080p: about 5 GB per 10-minute take.
+Fix: encode while recording. The engine feeds the newest picture to ffmpeg at 30 fps and keeps only the H.264 master
+(`capture.mp4`, near-lossless) plus the cut; a take leaves about two videos' worth of bytes. `DEMO_KEEP_FRAMES=1`
+brings the frame files back for a short debugging take only.
+
 **The last seconds of a segment are missing (closing card cut off).**
 Cause: the Chrome screencast only emits a frame when the picture changes, so a static hold at the end has no frame.
-Fix: end each clip at the moment recording stopped, not at the last captured frame (the engine does this).
+Fix: the master is fed at a constant rate until the moment recording stops, so a hold is in the video (the engine does this).
 
 **The video runs longer than the recording, or plays in jerks.**
 Cause: bursts of frames with near-identical timestamps each padded to a minimum duration.
-Fix: resample to a constant frame rate: for each output tick, show the newest frame captured at or before it.
+Fix: a constant frame rate: at each tick, the newest picture (the engine's 30 fps ticker does exactly this, live).
 
 **Text is soft or smeared.**
 Cause: Playwright's built-in `recordVideo` encodes VP8 at a low fixed bitrate.
-Fix: capture DevTools screencast frames (JPEG q95) and encode H.264 yourself (CRF ~17, `yuv420p`, `+faststart`).
+Fix: take DevTools screencast pictures (JPEG q95) and encode H.264 yourself: a near-lossless master (CRF 12) while
+recording, then one CRF 17 pass for the cut (`yuv420p`, `+faststart`). The master is never the step that softens text.
 
 **The time-lapse compressed the wrong part.**
 Cause: speed marks and frame timestamps on different clocks.
@@ -85,7 +92,7 @@ Fix: create `ctx.waitForResponse(re, { method: "GET" })` before the action, then
 and time the whole thing with `ctx.time`.
 
 **The closing card shows an old number after re-recording one segment.**
-Cause: the closing card is baked into the last segment's frames when it is recorded.
+Cause: the closing card is baked into the last segment's master when it is recorded.
 Fix: the runner now re-records the last segment automatically whenever another segment is re-recorded (keep that
 segment short); `--keep-closing` opts out. Check the end of the video after every partial re-record.
 
@@ -107,7 +114,7 @@ Fix: record per segment; re-record only the one that failed. Test risky segments
 **Fonts differ between machines or render as a fallback offline.**
 Cause: the stage loads a web font from a CDN.
 Fix: record with network access, or vendor the font files next to the stage and reference them locally. The
-finished video is offline-safe either way: the fonts are baked into the frames.
+finished video is offline-safe either way: the fonts are baked into the picture.
 
 **Local storage or cookies behave oddly inside the frame.**
 Cause: a stage page on a different origin partitions the app's storage.

package/skills/demo/refs/review-checklist.md

@@ -15,8 +15,8 @@ Each item is **symptom → likely cause → fix** and a verdict: **[encode]** re
   re-apply the speed factors. [encode]
 - [ ] **Stutter, judder or variable frame rate** → frames encoded with their raw capture durations → resample to a
   constant 30 fps before encoding. [encode]
-- [ ] **Blurry text** → a low-bitrate recorder (browser automation built-in video is often ~1 Mbps VP8) → capture frames
-  as high-quality JPEG/PNG and encode H.264 at low CRF, `yuv420p`, `+faststart`. [encode]
+- [ ] **Blurry text** → a low-bitrate recorder (browser automation built-in video is often ~1 Mbps VP8) → take the
+  screencast as high-quality JPEG, encode a near-lossless H.264 master live, cut at low CRF, `yuv420p`, `+faststart`. [encode]
 
 ## Openings, joins and the end
 

package/skills/demo/refs/storyline-api.md

@@ -9,15 +9,17 @@ wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs              # r
 wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs 03-search    # (re)record one or more segments, restitch
 wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs --all        # re-record everything
 wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs --stitch     # only stitch what exists
-wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs --reencode   # rebuild every segment from saved frames, restitch
+wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs --reencode   # re-cut every segment from its saved master, restitch
 wicked-garden run scripts/demo/record.mjs path/to/storyline.mjs --list       # segments and whether each is recorded
 ```
 
 Options: `--out <dir>` (default: `demo-video/` next to the storyline), `--keep-closing` (see below). Environment: `FFMPEG` (path to ffmpeg; ffprobe
-is found next to it), `DEMO_BASE_URL` (overrides `baseUrl`), `DEMO_HEADFUL=1` (show the browser while recording).
+is found next to it), `DEMO_BASE_URL` (overrides `baseUrl`), `DEMO_HEADFUL=1` (show the browser while recording),
+`DEMO_KEEP_FRAMES=1` (also dump every screencast frame to `frames/`, for debugging a short take).
 
 Output in `<out>/`: `<slug>.mp4` (stitched, one chapter per segment), `chapters.md`, `timings.json`, and per segment
-`segments/<key>/segment.mp4` plus the raw capture (`frames/`, `timeline.json`) that `--reencode` rebuilds from.
+`segments/<key>/segment.mp4` plus the raw capture (`capture.mp4`, the 30 fps master encoded live while the take ran, and
+`timeline.json`) that `--reencode` re-cuts from. No frame files are written.
 The MP4 holds one video stream plus a small data stream: the chapter track ffmpeg writes for players that read
 QuickTime-style chapters. That is expected.