@litfamily/litmuse 0.1.0 → 0.1.2

package/plugin/skills/lit-typographic-motion/engine/node/sound-cli.mjs

@@ -1,12 +1,14 @@
-// `motion.mjs sound --out <dir>`: build the generated bed from <dir>/treatment.json so it can be
-// heard and its cues checked before the full render. The render rebuilds the same bed at the film's
-// exact frame count and cut times, so the muxed track always matches the picture.
+// `motion.mjs sound --out <dir>`: build the film's score (or a minimal film's generated bed) from
+// <dir>/treatment.json so it can be heard and its cues checked before the full render. The render
+// rebuilds the same track at the film's exact frame count and cut times, so the muxed track always
+// matches the picture.
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { EXIT } from "../core/constants.mjs";
 import { loadBrief, planFromBrief } from "./brief.mjs";
 import { BlockedError } from "./chrome.mjs";
 import { asBlocked } from "./pipeline.mjs";
+import { writeScore } from "./score.mjs";
 import { prepareTrack, writeBed } from "./sound.mjs";
 import { loadTreatment } from "./treatment.mjs";
 
@@ -21,8 +23,19 @@ export function soundTimeline(out, treatment) {
   return { fps, frameCount: Math.round(treatment.durationSec * fps), cutTimes: treatment.beats.slice(1).map((b) => b.t0) };
 }
 
+const scoreLabel = (score) => `score, ${score.genre} in ${score.key}, ${score.tempo} BPM, ${score.stems.filter((x) => x.kind !== "return").length} stems`;
+
 export async function soundCommand({ out }) {
   const treatment = asBlocked(() => loadTreatment(out));
+  if (treatment.sound.mode === "score") {
+    const { fps, frameCount, cutTimes } = soundTimeline(out, treatment);
+    const score = writeScore({ treatment, frameCount, fps, cutTimes, dir: out });
+    const sections = score.sections.map((x) => x.kind).join(" → ");
+    return {
+      code: EXIT.OK,
+      message: `SOUND: ${scoreLabel(score)} (${score.progression}; ${sections}; sidechain ${score.sidechainDb.toFixed(1)} dB; ${score.lufs.toFixed(1)} LUFS, peak ${score.peakDbfs.toFixed(1)} dBFS) in ${score.file}; stems in ${path.join(out, "sound", "stems")}; ${score.cues.length} cues in ${path.join(out, "sound-cues.json")}`,
+    };
+  }
   if (treatment.sound.mode !== "generated") {
     return { code: EXIT.OK, message: `SOUND: mode ${treatment.sound.mode}; nothing to generate (the render ${treatment.sound.mode === "none" ? "adds no track" : "prepares and muxes the track"})` };
   }
@@ -35,13 +48,17 @@ export async function soundCommand({ out }) {
 }
 
 /**
- * The film's track on either path: the generated bed at the film's exact frame count and cuts, a
+ * The film's track on either path: the score or the generated bed at the film's exact frame count and cuts, a
  * supplied or authored track padded or trimmed to the film, or none. Always muxed whatever the
  * audio-analysis tier's state (the Wave 1 renderer dropped a track when that tier was absent).
  */
 export function soundTrackFor({ treatment, out, stageDir = null, frameCount, fps, cutTimes, ffmpeg }) {
   const mode = treatment.sound.mode;
   if (mode === "none") return { mode, file: null, label: "none (asked for)" };
+  if (mode === "score") {
+    const score = writeScore({ treatment, frameCount, fps, cutTimes, dir: out });
+    return { mode, file: score.file, label: scoreLabel(score), bed: score };
+  }
   if (mode === "generated") {
     const bed = writeBed({ treatment, frameCount, fps, cutTimes, dir: out });
     return { mode, file: path.join(out, "sound", "bed.wav"), label: `generated bed, ${bed.timbre} in ${bed.key}, ${bed.tempo} BPM`, bed };

package/plugin/skills/lit-typographic-motion/engine/node/sound.mjs

@@ -28,6 +28,7 @@ export const SOUND = Object.freeze({
   fadeSec: 0.05,
 });
 
+export { TABLE as WAVETABLE_SIZE };
 export const TEMPO_RANGE = Object.freeze([60, 160]);
 const PITCH = { C: 0, "C#": 1, Db: 1, D: 2, "D#": 3, Eb: 3, E: 4, F: 5, "F#": 6, Gb: 6, G: 7, "G#": 8, Ab: 8, A: 9, "A#": 10, Bb: 10, B: 11 };
 export const KEYS = Object.freeze({ pitchClasses: Object.freeze(Object.keys(PITCH)), modes: Object.freeze(["major", "minor"]) });
@@ -86,6 +87,13 @@ export function normalizePalette(palette) {
   return { timbre, key, mode, tempo };
 }
 
+/**
+ * Sounds an on-screen event can make (treatment `sound.events`): a tap (a small click with a pitched
+ * body: a key, a latch, a drop landing), a hit (the cut hit), a whoosh (air ending on the event) and a
+ * chime (two notes of the key: something completes).
+ */
+export const EVENT_SOUNDS = Object.freeze(["tap", "hit", "whoosh", "chime"]);
+
 const CUE_WORDS = [
   ["hit", /\b(?:hits?|impacts?|cuts?|stabs?|accents?)\b|타격|히트|컷|강세/iu],
   ["rise", /\b(?:rises?|rising|risers?|swells?|swelling|builds?|building|build-?ups?|lifts?|lifting)\b|상승|고조|빌드업/iu],
@@ -104,8 +112,11 @@ const nearest = (times, t, within) => {
   return best;
 };
 
-/** Accent cues, each measured against the beat boundary or cut it serves. */
-export function planCues({ beats = [], durationSec, cutTimes = [] }) {
+/**
+ * Accent cues, each measured against the beat boundary or cut it serves, plus one `event` cue per
+ * on-screen event at its own time (it never snaps to a cut: it follows the picture).
+ */
+export function planCues({ beats = [], durationSec, cutTimes = [], events = [] }) {
   const cues = [];
   const clampT = (t) => Math.min(durationSec, Math.max(0, t));
   beats.forEach((beat, beatIndex) => {
@@ -127,6 +138,12 @@ export function planCues({ beats = [], durationSec, cutTimes = [] }) {
       }
     }
   });
+  for (const e of Array.isArray(events) ? events : []) {
+    if (!EVENT_SOUNDS.includes(e?.kind) || !(e.t >= 0 && e.t < durationSec)) continue;
+    const beatIndex = Math.max(0, beats.findIndex((b) => e.t >= Number(b.t0) && e.t < Number(b.t1)));
+    const cut = nearest(cutTimes, e.t, Infinity);
+    cues.push({ kind: "event", sound: e.kind, t: round4(e.t), beatIndex, target: round4(e.t), delta: 0, on: String(e.on ?? ""), fromCut: cut === null ? null : round4(Math.abs(e.t - cut)) });
+  }
   cues.sort((a, b) => a.t - b.t || a.beatIndex - b.beatIndex);
   return cues;
 }
@@ -264,7 +281,8 @@ export function decodeWav(buffer) {
 
 // ---- synthesis ----
 const TABLE = 4096;
-function wavetable(harmonics) {
+/** A normalized single-cycle table of additive partials (TABLE + 1 samples, wrapped). */
+export function wavetable(harmonics) {
   const t = new Float32Array(TABLE + 1);
   let peak = 0;
   for (let i = 0; i < TABLE; i++) {
@@ -316,7 +334,7 @@ export function buildBed({ treatment, frameCount, fps, cutTimes = [] }) {
   const sampleCount = Math.round((frameCount * sr) / fps);
   const durationSec = sampleCount / sr;
   const beats = Array.isArray(treatment?.beats) ? treatment.beats : [];
-  const cues = planCues({ beats, durationSec, cutTimes });
+  const cues = planCues({ beats, durationSec, cutTimes, events: treatment?.sound?.events });
   const rand = mulberry32(fnv1a32(`${treatment?.request ?? ""}|${palette.timbre}|${palette.key}|${palette.mode}|${palette.tempo}`));
   const L = new Float64Array(sampleCount);
   const R = new Float64Array(sampleCount);
@@ -445,22 +463,58 @@ export function buildBed({ treatment, frameCount, fps, cutTimes = [] }) {
       }
     }
   };
-  for (const cue of cues) {
-    if (cue.kind === "hit") {
-      const s0 = Math.round(cue.t * sr);
-      const len = Math.min(sampleCount - s0, Math.round(0.6 * sr));
+  // An on-screen event: a sound shaped like what the picture does at that frame.
+  const eventSound = (cue) => {
+    const s0 = Math.round(cue.t * sr);
+    if (cue.sound === "tap") {
+      const len = Math.min(sampleCount - s0, Math.round(0.3 * sr));
+      const hz = midiHz(tonic + 24 + (palette.mode === "major" ? 7 : 3));
       let f = 0;
-      const c = onePole(voice.accent.kind === "bell" ? 6000 : 1800, sr);
-      let ph = 0;
+      const c = onePole(4500, sr);
       for (let i = 0; i < len; i++) {
         const t = i / sr;
         f += c * (rand() * 2 - 1 - f);
-        ph += (2 * Math.PI * (50 + 90 * Math.exp(-t / 0.02))) / sr;
-        const v = 0.55 * Math.exp(-t / 0.12) * f + 0.5 * Math.exp(-t / 0.22) * Math.sin(ph);
+        const v = 1.2 * Math.exp(-t / 0.008) * f + 0.6 * Math.exp(-t / 0.07) * Math.sin(2 * Math.PI * hz * t);
         L[s0 + i] += v;
-        R[s0 + i] += v;
+        R[s0 + i] += v * 0.9;
+      }
+    } else if (cue.sound === "whoosh") {
+      const start = Math.max(0, s0 - Math.round(0.4 * sr));
+      const tail = Math.min(sampleCount, s0 + Math.round(0.08 * sr));
+      let f = 0;
+      for (let s = start; s < tail; s++) {
+        const u = s < s0 ? (s - start) / Math.max(1, s0 - start) : 1 - (s - s0) / Math.max(1, tail - s0);
+        f += onePole(300 + 3200 * u, sr) * (rand() * 2 - 1 - f);
+        const v = 0.5 * u * u * f;
+        L[s] += v * (1 - 0.4 * u);
+        R[s] += v * (0.6 + 0.4 * u);
       }
-      if (voice.accent.kind === "bell") strike(cue.t, [tonic + 12], 0.6, 0.12);
+    } else if (cue.sound === "chime") {
+      strike(cue.t, [tonic + 12], 1.2, 0.09);
+      strike(cue.t + 0.09, [tonic + 19], 1.2, 0.08);
+    } else {
+      hitAt(cue.t);
+    }
+  };
+  const hitAt = (t0) => {
+    const s0 = Math.round(t0 * sr);
+    const len = Math.min(sampleCount - s0, Math.round(0.6 * sr));
+    let f = 0;
+    const c = onePole(voice.accent.kind === "bell" ? 6000 : 1800, sr);
+    let ph = 0;
+    for (let i = 0; i < len; i++) {
+      const t = i / sr;
+      f += c * (rand() * 2 - 1 - f);
+      ph += (2 * Math.PI * (50 + 90 * Math.exp(-t / 0.02))) / sr;
+      const v = 0.55 * Math.exp(-t / 0.12) * f + 0.5 * Math.exp(-t / 0.22) * Math.sin(ph);
+      L[s0 + i] += v;
+      R[s0 + i] += v;
+    }
+    if (voice.accent.kind === "bell") strike(t0, [tonic + 12], 0.6, 0.12);
+  };
+  for (const cue of cues) {
+    if (cue.kind === "hit") {
+      hitAt(cue.t);
     } else if (cue.kind === "rise") {
       const s0 = Math.round(cue.start * sr);
       const s1 = Math.min(sampleCount, Math.round(cue.t * sr));
@@ -475,6 +529,8 @@ export function buildBed({ treatment, frameCount, fps, cutTimes = [] }) {
         L[s] += v * (1 - 0.3 * u);
         R[s] += v * (0.7 + 0.3 * u);
       }
+    } else if (cue.kind === "event") {
+      eventSound(cue);
     } else {
       const third = palette.mode === "major" ? 4 : 3;
       strike(cue.t, [tonic - 12, tonic, tonic + third, tonic + 7], voice.accent.decay, 0.1);
@@ -489,20 +545,61 @@ export function buildBed({ treatment, frameCount, fps, cutTimes = [] }) {
     R[sampleCount - 1 - i] *= g;
   }
 
-  // Loudness to -16 LUFS through a soft limiter under -2 dBFS; quantized as the WAV will be.
+  const { left, right, lufs } = masterTo(L, R);
+  return { left, right, sampleCount, palette, cues, lufs: +lufs.toFixed(2), peakDbfs: +samplePeakDbfs([left, right]).toFixed(2), loudnessMethod: "BS.1770-4" };
+}
+
+/**
+ * The master stage every built track ends in: loudness to -16 LUFS through a lookahead limiter under
+ * -2 dBFS, quantized as the WAV will be. Returns the channels, the gain applied and the loudness.
+ *
+ * The limiter turns the gain down smoothly before a peak (5 ms lookahead, both channels linked, 80 ms
+ * release) instead of bending the waveform. A waveshaper adds harmonics the AAC encode turns into
+ * overshoot: one film's score sat at -2.1 dBFS in the WAV and decoded at +0.4 dBFS from the mux.
+ */
+export function masterTo(L, R) {
+  const sampleCount = L.length;
   const ceiling = 10 ** (-2.1 / 20);
-  const knee = 0.5 * ceiling;
-  const limit = (x) => {
-    const a = Math.abs(x);
-    return a <= knee ? x : Math.sign(x) * (knee + (ceiling - knee) * Math.tanh((a - knee) / (ceiling - knee)));
-  };
+  const ahead = Math.round(0.005 * SOUND.sampleRate);
+  const release = 1 - Math.exp(-1 / (0.08 * SOUND.sampleRate));
   const q = (v) => Math.round(Math.max(-1, Math.min(1, v)) * 32767) / 32767;
   const render = (gain) => {
+    // need[s]: the gain that keeps sample s under the ceiling; held[s]: the lowest need in the next
+    // `ahead` samples (a monotonic deque); then the release lets it rise slowly; then a moving average
+    // over `ahead` samples reaches every held value before its peak, so the result never exceeds need.
+    const need = new Float32Array(sampleCount);
+    for (let s = 0; s < sampleCount; s++) {
+      const a = Math.max(Math.abs(L[s]), Math.abs(R[s])) * gain;
+      need[s] = a > ceiling ? ceiling / a : 1;
+    }
+    const held = new Float32Array(sampleCount);
+    const deque = new Int32Array(sampleCount + ahead + 1);
+    let head = 0;
+    let tail = 0;
+    let next = 0;
+    for (let s = 0; s < sampleCount; s++) {
+      for (; next < Math.min(sampleCount, s + ahead + 1); next++) {
+        while (tail > head && need[deque[tail - 1]] >= need[next]) tail--;
+        deque[tail++] = next;
+      }
+      while (deque[head] < s) head++;
+      held[s] = need[deque[head]];
+    }
+    let env = 1;
+    const smooth = new Float32Array(sampleCount);
+    for (let s = 0; s < sampleCount; s++) {
+      env = Math.min(held[s], env + (1 - env) * release);
+      smooth[s] = env;
+    }
     const l = new Float32Array(sampleCount);
     const r = new Float32Array(sampleCount);
+    // The averaging window starts full of unity gain; the hard ceiling below catches the first 5 ms.
+    let win = ahead;
     for (let s = 0; s < sampleCount; s++) {
-      l[s] = q(limit(L[s] * gain));
-      r[s] = q(limit(R[s] * gain));
+      win += smooth[s] - (s >= ahead ? smooth[s - ahead] : 1);
+      const g = win / ahead;
+      l[s] = q(Math.max(-ceiling, Math.min(ceiling, L[s] * gain * g)));
+      r[s] = q(Math.max(-ceiling, Math.min(ceiling, R[s] * gain * g)));
     }
     return [l, r];
   };
@@ -515,7 +612,7 @@ export function buildBed({ treatment, frameCount, fps, cutTimes = [] }) {
     [left, right] = render(gain);
     lufs = integratedLoudness([left, right]);
   }
-  return { left, right, sampleCount, palette, cues, lufs: +lufs.toFixed(2), peakDbfs: +samplePeakDbfs([left, right]).toFixed(2), loudnessMethod: "BS.1770-4" };
+  return { left, right, gain, lufs };
 }
 
 export function writeBed({ treatment, frameCount, fps, cutTimes = [], dir }) {
@@ -621,6 +718,8 @@ export function auditMuxed({ ffmpeg, ffprobe = null, film, videoDurationSec, mod
   const peak = samplePeakDbfs(channels);
   const head = rmsRuns(channels);
   const lufs = integratedLoudness(channels);
+  // A generated bed and a score are built here to the loudness target; a supplied track is only reported.
+  const built = mode === "generated" || mode === "score";
   const rules = [{ id: "SOUND-STREAM", status: "PASS", detail: `audio stream present (${mode})` }];
   const dd = Math.abs(duration - videoDurationSec);
   rules.push({ id: "SOUND-DURATION", status: dd <= SOUND.durationToleranceSec ? "PASS" : "FAIL", detail: `audio ${duration.toFixed(3)} s vs video ${Number(videoDurationSec).toFixed(3)} s (limit ±${SOUND.durationToleranceSec} s)` });
@@ -628,14 +727,14 @@ export function auditMuxed({ ffmpeg, ffprobe = null, film, videoDurationSec, mod
   const headBad = head > SOUND.silenceMaxSec;
   rules.push({
     id: "SOUND-HEAD",
-    status: headBad ? (mode === "generated" ? "FAIL" : "WARN") : "PASS",
+    status: headBad ? (built ? "FAIL" : "WARN") : "PASS",
     detail: `longest run below ${SOUND.silenceDbfs} dBFS RMS in the first ${SOUND.silenceHeadSec} s: ${head.toFixed(2)} s (limit ${SOUND.silenceMaxSec} s)`,
   });
   const inRange = Number.isFinite(lufs) && Math.abs(lufs - SOUND.targetLufs) <= SOUND.lufsTolerance;
   rules.push({
     id: "SOUND-LOUDNESS",
-    status: mode === "generated" ? (inRange ? "PASS" : "WARN") : "PASS",
-    detail: `integrated ${Number.isFinite(lufs) ? lufs.toFixed(2) : "-inf"} LUFS (BS.1770-4${mode === "generated" ? `, target ${SOUND.targetLufs} ± ${SOUND.lufsTolerance}` : ", reported"})`,
+    status: built ? (inRange ? "PASS" : "WARN") : "PASS",
+    detail: `integrated ${Number.isFinite(lufs) ? lufs.toFixed(2) : "-inf"} LUFS (BS.1770-4${built ? `, target ${SOUND.targetLufs} ± ${SOUND.lufsTolerance}` : ", reported"})`,
   });
-  return { rules, exitCode: headBad && mode === "generated" ? 20 : null };
+  return { rules, exitCode: headBad && built ? 20 : null };
 }

package/plugin/skills/lit-typographic-motion/engine/node/stage-serve.mjs

@@ -9,6 +9,11 @@ import { fileURLToPath } from "node:url";
 import { EXIT } from "../core/constants.mjs";
 import { BlockedError } from "./chrome.mjs";
 import { checkFont, fontLocation, fontsDir, loadFontManifest } from "./runtime.mjs";
+import { readPlate } from "./blender.mjs";
+
+// The pinned three.js build and its few addons (engine/vendor/three, MIT), served at /lit/three/
+// for the 3D route (references/depth.md). Pages import them through an import map; nothing is fetched.
+export const THREE_DIR = fileURLToPath(new URL("../vendor/three/", import.meta.url));
 
 export const STAGE_ORIGIN = "http://lit.stage";
 export const KIT_FILE = fileURLToPath(new URL("../stage/stage-kit.js", import.meta.url));
@@ -179,17 +184,22 @@ const NETWORK_API = /\bnew\s+(WebSocket|WebTransport|RTCPeerConnection|EventSour
 
 /**
  * Scan the stage dir before launch. Throws exit 17 (contract) or 19 (network) naming the file and
- * the thing found; returns { files, rasters, warnings } otherwise.
+ * the thing found; returns { files, rasters, warnings, plate } otherwise (plate: the Blender plate, or null).
  */
 export function scanStage(stageDir) {
   if (!existsSync(path.join(stageDir, "index.html"))) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${path.join(stageDir, "index.html")} is missing; write the stage page first (references/stage.md)`);
   const files = listStage(stageDir);
   const warnings = [];
   const rasters = [];
+  // A Blender plate and its preview stills are frames the runner wrote and plate.json lists by name
+  // and size; they are not page rasters. Anything not listed is held to the raster limits.
+  const plate = readPlate(stageDir, "plate");
+  const preview = readPlate(stageDir, "plate-preview");
+  const listed = new Set([plate, preview].filter(Boolean).flatMap((p) => p.frames.map((f) => path.join(p.dir, f.name))));
   for (const f of files) {
     const ext = path.extname(f.rel).toLowerCase();
-    if (!CONTENT_TYPES[ext]) warnings.push(`${f.rel}: not a servable type; the page cannot load it`);
-    if (RASTER.includes(ext)) {
+    if (!CONTENT_TYPES[ext] && f.rel !== "scene.py") warnings.push(`${f.rel}: not a servable type; the page cannot load it`);
+    if (RASTER.includes(ext) && !listed.has(f.rel)) {
       const info = rasterInfo(f.real);
       if (!info) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${f.rel} is not a readable ${ext.slice(1)} image`);
       if (info.animated) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${f.rel} is an animated image; rasters are textures and stills, never a frame sequence`);
@@ -225,14 +235,14 @@ export function scanStage(stageDir) {
   for (const [size, names] of bySize) {
     if (names.length >= RASTER_LIMITS.flipbook) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${names.length} rasters of ${size} look like a flipbook; animate the page, not a frame sequence`);
   }
-  return { files, rasters, warnings };
+  return { files, rasters, warnings, plate };
 }
 
 /**
  * The request router for one stage run. Returns { kind: "file", file, type } | { kind: "body", body,
  * type } | { kind: "blocked", reason } | { kind: "missing" }, and records every refusal.
  */
-export function stageRouter({ stageDir, faces }) {
+export function stageRouter({ stageDir, faces, style = null }) {
   const root = realpathSync(stageDir);
   const css = fontsCss(faces);
   const byRoute = new Map(faces.map((f) => [f.route, f.file]));
@@ -251,9 +261,23 @@ export function stageRouter({ stageDir, faces }) {
       return { kind: "blocked" };
     }
     const pathname = decodeURIComponent(parsed.pathname);
+    // Chrome asks for a favicon on its own; the page did not, so it is not a missing file of the page.
+    if (pathname === "/favicon.ico") return { kind: "missing" };
     if (pathname === "/lit/stage-kit.js") return { kind: "file", file: KIT_FILE, type: CONTENT_TYPES[".js"] };
     if (pathname === "/lit/loop-kit.js") return { kind: "file", file: LOOP_KIT_FILE, type: CONTENT_TYPES[".js"] };
     if (pathname === "/lit/fonts.css") return { kind: "body", body: css, type: CONTENT_TYPES[".css"] };
+    if (pathname.startsWith("/lit/three/")) {
+      const rel = pathname.slice("/lit/three/".length);
+      const file = path.join(THREE_DIR, rel);
+      if (rel.split("/").includes("..") || !rel.endsWith(".js") || !existsSync(file)) {
+        missing.push({ url, reason: "not a vendored three.js file" });
+        return { kind: "missing" };
+      }
+      return { kind: "file", file, type: CONTENT_TYPES[".js"] };
+    }
+    // The film's house style (references/studio.md): type, colour and zone tokens, and the shot timeline.
+    if (style && pathname === "/lit/style.css") return { kind: "body", body: style.css, type: CONTENT_TYPES[".css"] };
+    if (style && pathname === "/lit/style.js") return { kind: "body", body: style.js, type: CONTENT_TYPES[".js"] };
     if (byRoute.has(pathname)) return { kind: "file", file: byRoute.get(pathname), type: CONTENT_TYPES[path.extname(pathname)] };
     const rel = pathname === "/" ? "index.html" : pathname.replace(/^\/+/u, "");
     if (rel.split("/").includes("..")) {

package/plugin/skills/lit-typographic-motion/engine/node/stage.mjs

@@ -11,6 +11,9 @@ import path from "node:path";
 import { EXIT, GATE, PREVIEW } from "../core/constants.mjs";
 import { FlashDetector, cellsFromRgba, detectSequence, gridFor } from "../core/flash.mjs";
 import { areaDownscale } from "./analysis.mjs";
+import { assetUsed } from "./assets.mjs";
+import { BLENDER } from "./blender.mjs";
+import { addToStills, writeBoard } from "./board.mjs";
 import { BlockedError } from "./chrome.mjs";
 import { findFfmpeg, findFfprobe, findImg2webp, previewRungs, startMaster, encodePreview, probeVideo } from "./encode.mjs";
 import { resolveViewed, asBlocked } from "./pipeline.mjs";
@@ -21,6 +24,8 @@ import { StageBrowser, FramePool, analyzeChecked } from "./stage-capture.mjs";
 import { evaluateStageGate, formatStageReport } from "./stage-gate.mjs";
 import { textQaReplay } from "./stage-qa.mjs";
 import { treatmentSha } from "./done.mjs";
+import { recordHouse } from "./house.mjs";
+import { styleCss, styleScript, readStyle } from "./styles.mjs";
 import { scanStage, stageFonts } from "./stage-serve.mjs";
 import { beatCuts, stillsPlan, writeStills } from "./stills.mjs";
 import { FORMATS, loadTreatment } from "./treatment.mjs";
@@ -33,11 +38,19 @@ const writeJson = (file, value) => {
   writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 };
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** The house style the page is served (/lit/style.css, /lit/style.js) for this treatment and format. */
+export const styleAssets = (treatment) => {
+  const style = readStyle(treatment.style);
+  return { style, css: styleCss(style, treatment.format), js: styleScript(style, treatment.format, treatment) };
+};
 const percentile = (values, p) => {
   const sorted = [...values].sort((a, b) => a - b);
   return sorted.length ? +sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))].toFixed(1) : null;
 };
 
+/** The beat stills of a stills set, as absolute paths, in beat order. */
+export const beatStillFiles = (out, stills) => stills.index.files.filter((f) => f.kind === "beat").sort((a, b) => a.beat - b.beat).map((f) => path.join(out, f.file));
+
 /** Determinism samples: frame 0, the last frame, each beat's first frame, beat midpoints to 8, at most 16. */
 export function determinismFrames({ beats, fps, frameCount }) {
   const clamp = (f) => Math.max(0, Math.min(frameCount - 1, f));
@@ -83,10 +96,30 @@ function violationExit(state, router) {
   return null;
 }
 
-/** Open a stage browser and check the page's LitStage contract against the treatment. */
+/**
+ * Open a stage browser on the round's rung and check the page's LitStage contract. A 3D film asks for
+ * the GPU rung; when that rung cannot launch or gives the page no WebGL, the round falls back to the
+ * software rung for every browser (master and replays must share one rung) and records a notice.
+ */
 async function openChecked({ label, ctx }) {
+  if (ctx.rung === "gpu") {
+    try {
+      const browser = await openOnRung({ label, ctx });
+      if (!browser.state.webglMissing) return browser;
+      await browser.close();
+      ctx.notices.push("the 3D route asked for the GPU rung and the page got no WebGL there; rendered on the software rung (SwiftShader), slower, same frames");
+    } catch (error) {
+      if (error instanceof BlockedError) throw error;
+      ctx.notices.push(`the 3D route asked for the GPU rung and it did not start (${String(error.message).slice(0, 120)}); rendered on the software rung (SwiftShader), slower, same frames`);
+    }
+    ctx.rung = "software";
+  }
+  return openOnRung({ label, ctx });
+}
+
+async function openOnRung({ label, ctx }) {
   const { stageDir, faces, scan, width, height, treatment, runDir, env, log } = ctx;
-  const browser = await StageBrowser.open({ stageDir, faces, rasters: scan.rasters, width, height, seed: treatment.seed, profileDir: path.join(runDir, `c${process.pid % 100000}${label}`), env, log });
+  const browser = await StageBrowser.open({ stageDir, faces, style: ctx.style, rasters: scan.rasters, width, height, seed: treatment.seed, profileDir: path.join(runDir, `c${process.pid % 100000}${label}`), rung: ctx.rung, env, log });
   const state = browser.state;
   const fail = (message) => new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${message}`);
   const early = violationExit(state, browser.router);
@@ -97,9 +130,9 @@ async function openChecked({ label, ctx }) {
   else if (!error && spec.render !== "function") error = fail("LitStage.define needs render(t)");
   else if (!error && spec.fps !== (treatment.fps ?? 60)) error = fail(`the page runs at ${spec.fps} fps; the treatment asks for ${treatment.fps ?? 60} (30 only when the treatment says fps: 30)`);
   else if (!error && !(spec.duration > 0)) error = fail("the page's duration must be a positive number of seconds");
-  if (!error && state.webglMissing) error = new BlockedError(EXIT.BLOCKED_NO_WEBGL2, "BLOCKED_NO_WEBGL2: the page asked for a WebGL context and the software rung gave none");
+  if (!error && state.webglMissing) error = new BlockedError(EXIT.BLOCKED_NO_WEBGL2, `BLOCKED_NO_WEBGL2: the page asked for a WebGL context and the ${ctx.rung} rung gave none`);
   if (!error && browser.prepared?.failedFaces?.length) log(`warning: faces that did not load: ${browser.prepared.failedFaces.join(", ")}`);
-  if (error) {
+  if (error && !(ctx.rung === "gpu" && error.code === EXIT.BLOCKED_NO_WEBGL2)) {
     await browser.close();
     throw error;
   }
@@ -141,6 +174,18 @@ async function captureFrames({ browser, pool, fps, frames, width, height, asMast
   return out;
 }
 
+/**
+ * The browser rung: a three.js world asks for the GPU; a Blender film shows its path-traced plate
+ * under HTML type, so its page needs only the software rung, and it needs the plate, all of it.
+ */
+export function stageRung(treatment, scan, out) {
+  if (treatment.render3d !== "blender") return treatment.depth === "3d" ? "gpu" : "software";
+  const want = Math.round(treatment.durationSec * BLENDER.plateFps);
+  if (!scan.plate) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: render3d is blender but stage/plate/plate.json is missing or does not match its frames; render the plate first: blender --out ${out} --final (no Blender: set render3d to three and use the GPU rung)`);
+  if (scan.plate.frames.length !== want) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: the plate has ${scan.plate.frames.length} frames; a ${treatment.durationSec} s film needs ${want} at ${BLENDER.plateFps} fps (render it again: blender --out ${out} --final)`);
+  return "software";
+}
+
 function renderId(treatment, scan) {
   const h = createHash("sha256").update(JSON.stringify(treatment));
   for (const f of scan.files) h.update(f.rel).update(readFileSync(f.real));
@@ -213,7 +258,7 @@ export async function captureStageFrames({ out, frames, env = process.env, log =
   const faces = stageFonts(env);
   const runDir = path.join(out, ".run");
   mkdirSync(runDir, { recursive: true });
-  const ctx = { stageDir, faces, scan, width, height, treatment, runDir, env, log };
+  const ctx = { stageDir, faces, scan, width, height, treatment, runDir, env, log, style: styleAssets(treatment), rung: stageRung(treatment, scan, out), notices: [] };
   const browser = await openChecked({ label: "x", ctx });
   const pool = new FramePool(2);
   try {
@@ -285,7 +330,7 @@ export async function renderStage({ out, round = 1, stillsOnly = false, env = pr
   const runDir = path.join(out, ".run");
   mkdirSync(runDir, { recursive: true });
   const ffmpeg = findFfmpeg(env);
-  const ctx = { stageDir, faces, scan, width, height, treatment, runDir, env, log };
+  const ctx = { stageDir, faces, scan, width, height, treatment, runDir, env, log, style: styleAssets(treatment), rung: stageRung(treatment, scan, out), notices: [] };
   progress(out, { phase: "open", round, stillsOnly });
   const master = await openChecked({ label: "m", ctx });
   const spec = master.state.spec;
@@ -300,11 +345,30 @@ export async function renderStage({ out, round = 1, stillsOnly = false, env = pr
     if (stillsOnly) {
       const frames = await captureFrames({ browser: master, pool, fps, frames: plan.all, width, height });
       const stills = writeStills({ out, plan, frames: new Map([...frames].map(([f, a]) => [f, a.rgba])), width, height, fps, frameCount, round, stillsOnly: true, path: "stage" });
+      // The board round: the text and style rules run on the board frames before any film is encoded,
+      // and the storyboard is drawn with the verdict on it.
+      progress(out, { phase: "board-check", round, stillsOnly });
+      const replayQa = qa ?? textQaReplay({ pool, stageFiles: scan.files.map((f) => path.basename(f.rel)) });
+      const check = await replayQa({ ctx, fps, frameCount, plan, openBrowser: (label) => openChecked({ label, ctx }), stepChecked });
+      const assetRule = assetUsed(treatment, scan.files);
+      if (assetRule) check.rules.push(assetRule);
+      writeJson(path.join(out, "stills", "check.json"), { rules: check.rules });
+      const boardFile = await writeBoard({ out, treatment, beatFiles: beatStillFiles(out, stills), check, env, log });
+      stills.sha256 = addToStills(out, { file: "stills/board.png", kind: "board", frames: plan.beats }, { sha256 });
       progress(out, { phase: "done", round, stillsOnly });
+      const failed = check.rules.filter((x) => x.status === "FAIL");
+      if (check.exit) return { code: check.exit, message: `${check.message} (board check; the storyboard is ${boardFile})`, stills, renderId: id, check };
+      if (failed.length) {
+        return {
+          code: EXIT.GATE_FAIL_QA,
+          message: `BOARD_CHECK_FAIL: ${failed.map((x) => `${x.id} ${x.detail}`).join("; ")}. Fix the page, render --stills-only again, then look at the board ${boardFile} and every file in ${path.join(out, "stills")}`,
+          stills, renderId: id, check,
+        };
+      }
       return {
         code: EXIT.OK,
-        message: `STILLS_ONLY: look at every file in ${path.join(out, "stills")} (index.json lists them), record the round with look --round ${round}, make the change, then render the film with --round ${round + 1} (no --stills-only)`,
-        stills, renderId: id,
+        message: `STILLS_ONLY: board check PASS; open the storyboard ${boardFile} and every file in ${path.join(out, "stills")} (index.json lists them), record the round with look --round ${round}, make the change, then render the film with --round ${round + 1} (no --stills-only)`,
+        stills, renderId: id, check,
       };
     }
     if (!ffmpeg) {
@@ -350,7 +414,7 @@ export async function renderStage({ out, round = 1, stillsOnly = false, env = pr
       const a = await entry.analysis;
       await encoder.write(a.rgba);
       const flash = detector.push(a.cells);
-      lines.push({ frame: entry.f, artifact: "master", rgbaSha256: a.rgbaSha256, luminanceP995: a.luminanceP995, flash });
+      lines.push({ frame: entry.f, artifact: "master", rgbaSha256: a.rgbaSha256, luminanceP995: a.luminanceP995, luminanceP005: a.luminanceP005, busy: a.busy, flash });
       if (plan.all.has(entry.f)) kept.set(entry.f, a.rgba);
       if (detFrames.includes(entry.f)) detMaster.set(entry.f, a);
       if (entry.f % previewEvery === 0) {
@@ -401,23 +465,27 @@ export async function renderStage({ out, round = 1, stillsOnly = false, env = pr
     };
     const gate = evaluateStageGate({
       masterFlash: lines.map((l) => l.flash), previewFlash: preview.records ? { records: preview.records, fps: preview.rung.fps } : null, fps,
-      probe, width, height, treatment, exports, reducedFrame: plan.reduced, frames: lines, usesWebGL: finalState.usesWebGL, renderer: master.renderer,
-      determinism, extraRules: [...soundAudit.rules, ...(qaResult?.rules ?? [])],
+      probe, width, height, treatment, exports, reducedFrame: plan.reduced, frames: lines, usesWebGL: finalState.usesWebGL, renderer: finalState.webglRenderer, rung: ctx.rung,
+      determinism, extraRules: [...soundAudit.rules, ...(qaResult?.rules ?? []), assetUsed(treatment, scan.files)].filter(Boolean),
     });
     const promoted = promote(out, gate.flashFail);
     const loc = (name) => path.join(promoted.dir, name);
     const stills = writeStills({ out, plan, frames: kept, width, height, fps, frameCount, round, stillsOnly: false, path: "stage", posterFile: existsSync(loc("poster.png")) ? loc("poster.png") : null });
+    await writeBoard({ out, treatment, beatFiles: beatStillFiles(out, stills), check: qaResult, env, log });
+    stills.sha256 = addToStills(out, { file: "stills/board.png", kind: "board", frames: plan.beats }, { sha256 });
+    if (gate.pass && !promoted.withheld) recordHouse(out, { style: treatment.style, path: "stage", format: treatment.format, durationSec: treatment.durationSec });
     const totalSec = (Date.now() - t0) / 1000;
     const manifest = {
       schemaVersion: 1, path: "stage", renderId: id, round, treatmentSha256: treatmentSha(out), format: treatment.format, width, height, fps, durationSec: spec.duration, treatmentDurationSec: treatment.durationSec,
-      frameCount, seed: treatment.seed, renderer: "SwiftShader (software rung)", chromeFlags: master.flags, usesWebGL: finalState.usesWebGL,
+      frameCount, seed: treatment.seed, renderer: finalState.webglRenderer ?? "no WebGL", rung: ctx.rung, chromeFlags: master.flags, usesWebGL: finalState.usesWebGL,
       cuts, stills: { sha256: stills.sha256, poster: plan.poster, reduced: plan.reduced }, posterEncoding: poster,
       geometry: geometryFor(width, height),
+      plate: scan.plate ? { blender: scan.plate.blender, engine: scan.plate.engine, device: scan.plate.device, samples: scan.plate.samples, fps: scan.plate.fps, frames: scan.plate.frames.length } : null,
       sound: { mode: sound.mode, label: sound.label, file: sound.file ? path.relative(out, sound.file) : null, sha256: sound.file ? sha256(readFileSync(sound.file)) : null, lufs: sound.bed?.lufs ?? null },
       preview: { encoder: preview.encoder, rung: preview.rung, attempts: preview.attempts },
       pageErrors: finalState.errors, missingAssets: master.router.missing,
       timing: { frameP50Ms: percentile(frameMs, 0.5), frameP95Ms: percentile(frameMs, 0.95), masterSec: +masterSec.toFixed(1), totalSec: +totalSec.toFixed(1) },
-      warnings: [...scan.warnings, ...master.router.missing.map((m) => `the page asked for a missing file ${m.url} (${m.reason})`)],
+      warnings: [...ctx.notices, ...scan.warnings, ...master.router.missing.map((m) => `the page asked for a missing file ${m.url} (${m.reason})`)],
       generatedAt: new Date().toISOString(),
     };
     writeJson(path.join(out, "manifest.json"), manifest);
@@ -492,7 +560,7 @@ export async function renderStageDetached({ out, round, cli, mode = "stage", env
     }
     try {
       const p = JSON.parse(readFileSync(path.join(runDir, "progress.json"), "utf8"));
-      const phase = `${p.phase}${p.frame !== undefined && p.phase === "master" ? ` ${Math.floor((p.frame / p.frameCount) * 10) * 10}%` : ""}`;
+      const phase = `${p.phase}${p.frame !== undefined && (p.phase === "master" || p.phase === "plate") ? ` ${Math.floor((p.frame / p.frameCount) * 10) * 10}%` : ""}`;
       if (phase !== lastPhase) log(`render: ${phase}`);
       lastPhase = phase;
     } catch {