@litfamily/lithermes 1.0.29 → 1.0.30

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

@@ -270,6 +270,153 @@ export function buildBed({ out, treatment, fps, totalFrames, cuts }) {
   return { file, ...cueDoc };
 }
 
+// ---------------------------------------------------------------------------
+// Layered score DSP. The score engine (score.mjs) is built from these: cue
+// planning, wavetable synthesis, the mastering stage and the WAV writer.
+
+export const SOUND = Object.freeze({
+  sampleRate: 48000,
+  channels: 2,
+  bitsPerSample: 16,
+  targetLufs: -16,
+  lufsTolerance: 2,
+  bedPeakDbfs: -2,
+  gatePeakDbfs: -0.5,
+  silenceDbfs: -50,
+  silenceWindowSec: 0.05,
+  silenceMaxSec: 1.5,
+  silenceHeadSec: 3,
+  durationToleranceSec: 0.1,
+  fadeSec: 0.05,
+});
+
+// Sounds an on-screen event can make (treatment `sound.events`): a tap (a
+// small click with a pitched body), 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],
+  ['cadence', /\b(?:cadences?|resolves?|resolving|resolution|close|closing|ending|final chord)\b|종지|마무리|해결/iu],
+];
+
+// Cue kinds a beat's free-text `sound` field asks for; none when nothing matches.
+export function cueKindsFor(soundText) {
+  const text = String(soundText ?? '');
+  return CUE_WORDS.filter(([, re]) => re.test(text)).map(([kind]) => kind);
+}
+
+const nearest = (times, t, within) => {
+  let best = null;
+  for (const c of times) if (Math.abs(c - t) <= within && (best === null || Math.abs(c - t) < Math.abs(best - t))) best = c;
+  return best;
+};
+const round4 = (x) => Math.round(x * 10000) / 10000;
+
+// 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) => {
+    const t0 = clampT(Number(beat.t0));
+    const t1 = clampT(Number(beat.t1));
+    for (const kind of cueKindsFor(beat.sound)) {
+      if (kind === 'hit') {
+        const cut = nearest(cutTimes, t0, 0.5);
+        const target = cut ?? t0;
+        cues.push({ kind, t: round4(target), beatIndex, target: round4(target), delta: 0 });
+      } else if (kind === 'rise') {
+        const cut = nearest(cutTimes, t1, 0.5);
+        const end = cut ?? t1;
+        const start = Math.max(t0, end - 1.0);
+        cues.push({ kind, t: round4(end), start: round4(start), beatIndex, target: round4(end), delta: 0 });
+      } else {
+        const t = t0 + 0.6 * (t1 - t0);
+        cues.push({ kind, t: round4(t), beatIndex, target: round4(t), delta: 0, end: round4(beatIndex === beats.length - 1 ? durationSec : t1) });
+      }
+    }
+  });
+  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;
+}
+
+export function samplePeakDbfs(channels) {
+  let peak = 0;
+  for (const c of channels) for (let i = 0; i < c.length; i++) {
+    const v = Math.abs(c[i]);
+    if (v > peak) peak = v;
+  }
+  return dbfs(peak);
+}
+
+// The shared master stage: look-ahead limiting under the ceiling, then the
+// gain that lands the bus on the target LUFS.
+export function masterTo(L, R) {
+  const sampleCount = L.length;
+  const ceiling = 10 ** (-2.1 / 20);
+  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) => {
+    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);
+    let win = ahead;
+    for (let s = 0; s < sampleCount; s++) {
+      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];
+  };
+  const raw = integratedLoudness([Float32Array.from(L), Float32Array.from(R)]);
+  let gain = Number.isFinite(raw) ? 10 ** ((SOUND.targetLufs - raw) / 20) : 1;
+  let [left, right] = render(gain);
+  let lufs = integratedLoudness([left, right]);
+  for (let i = 0; i < 8 && Number.isFinite(lufs) && Math.abs(lufs - SOUND.targetLufs) > 0.2; i++) {
+    gain *= 10 ** ((SOUND.targetLufs - lufs) / 20);
+    [left, right] = render(gain);
+    lufs = integratedLoudness([left, right]);
+  }
+  return { left, right, gain, lufs };
+}
+
+// The score writer uses the same 16-bit stereo bytes as the bed writer.
+export const encodeWav = ({ left, right }) => wavBytes(left, right);
+
 // ---------------------------------------------------------------------------
 // Mux and gate.
 
@@ -338,6 +485,15 @@ export async function produceSound({ out, treatment, fps, totalFrames, cuts, vid
     return { summary: { mode, label: 'no sound (silence was asked for, or the channel plays muted)' }, rules: [{ id: 'sound-stream', status: 'PASS', detail: 'no sound planned' }] };
   }
   let track, bed = null;
+  if (mode === 'score') {
+    const { writeScore } = await import('./score.mjs');
+    const score = writeScore({ treatment, frameCount: totalFrames, fps, cutTimes: cuts, dir: out });
+    track = score.file;
+    const label = `score, ${score.genre} in ${score.key}, ${score.tempo} BPM, ${score.stems.filter((s) => s.kind !== 'return').length} stems; ${score.progression}; ${score.lufs.toFixed(1)} LUFS, peak ${score.peakDbfs.toFixed(1)} dBFS — labelled as generated`;
+    muxAudio({ video, track, output, durationSec });
+    const gate = soundGate({ file: output, mode });
+    return { summary: { mode, label, track, score: { sha256: score.sha256, loudnessLufs: score.lufs, peakDbfs: score.peakDbfs, genre: score.genre, key: score.key, tempo: score.tempo }, mux: { peakDbfs: gate.peakDbfs, audioSec: gate.audioSec, videoSec: gate.videoSec } }, rules: gate.rules };
+  }
   if (mode === 'generated') {
     bed = buildBed({ out, treatment, fps, totalFrames, cuts });
     track = bed.file;
@@ -360,6 +516,21 @@ export async function soundCommand(flags) {
   const out = resolve(flags.out || 'motion-output');
   try {
     const { treatment } = loadTreatment(out, EXIT.BLOCKED_TREATMENT_INVALID);
+    if (treatment.sound.mode === 'score') {
+      const { writeScore } = await import('./score.mjs');
+      const fps = treatment.fps === 30 ? 30 : 60;
+      const manifestFile = join(out, 'manifest.json');
+      const manifest = existsSync(manifestFile) ? JSON.parse(readFileSync(manifestFile, 'utf8')) : null;
+      const totalFrames = manifest?.totalFrames || Math.round((manifest?.durationSec || treatment.durationSec) * fps);
+      const cuts = manifest?.path === 'stage' && manifest.beats ? manifest.beats.slice(1).map((b) => b.first / fps)
+        : manifest?.timeline ? manifest.timeline.filter((u) => u.kind === 'line').slice(1).map((u) => u.start)
+          : treatment.beats.slice(1).map((b) => b.t0);
+      const score = writeScore({ treatment, frameCount: totalFrames, fps: manifest?.fps || fps, cutTimes: cuts, dir: out });
+      const sections = score.sections.map((s) => s.kind).join(' → ');
+      console.log(`sound: sound/score.wav (score, ${score.genre} in ${score.key}, ${score.tempo} BPM; ${score.progression}; ${sections}; sidechain ${score.sidechainDb.toFixed(1)} dB; ${score.lufs.toFixed(1)} LUFS, peak ${score.peakDbfs.toFixed(1)} dBFS; stems in sound/stems)`);
+      console.log(`cues: ${join(out, 'sound-cues.json')} (${score.cues.length} cues)`);
+      return 0;
+    }
     if (treatment.sound.mode !== 'generated') {
       console.log(`sound: the treatment's sound mode is ${treatment.sound.mode}; nothing to generate`);
       return 0;

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/stage-qa.mjs

@@ -131,6 +131,15 @@ const PAGE_QA = String(function install() {
   };
 });
 
+export function copyOverlaps(boxes) {
+  const hits = [];
+  for (let i = 0; i < boxes.length; i++) for (let j = i + 1; j < boxes.length; j++) {
+    const [ax0, ay0, ax1, ay1] = boxes[i], [bx0, by0, bx1, by1] = boxes[j];
+    if (Math.min(ax1, bx1) > Math.max(ax0, bx0) && Math.min(ay1, by1) > Math.max(ay0, by0)) hits.push([i, j]);
+  }
+  return hits;
+}
+
 function inkMask(a, b, width, height, rects) {
   const mask = Buffer.alloc(width * height);
   const inside = new Uint8Array(width * height);
@@ -191,7 +200,7 @@ export async function runTextQa(session) {
   const tenFps = Math.max(1, Math.round(fps / 10));
   const visibleSpans = new Map();
   const seenCopy = new Set();
-  const results = { contrast: [], safe: [], decorCopy: [], decorArea: [], meta: new Set(), fonts: [], moved: [], canvasUnmeasured: false, nonText: [], floors: [] };
+  const results = { contrast: [], safe: [], decorCopy: [], decorArea: [], meta: new Set(), fonts: [], moved: [], canvasUnmeasured: false, nonText: [], floors: [], overlap: [] };
   const stage = await session.open('q');
   const cdp = stage.cdp;
   const PNG = session.PNG;
@@ -215,7 +224,9 @@ export async function runTextQa(session) {
       const now = new Map();
       for (const run of runs) {
         const visible = run.opacity >= 0.6 && run.rects.length > 0;
-        const key = `${run.norm}|${run.bucket}`;
+        // The floor span is the copy line's, not its position bucket's: a line
+        // that slides (a push handoff moves its box) keeps one continuous span.
+        const key = run.norm;
         now.set(run.id, run);
         if (!visible || !run.norm) continue;
         if (isCopy(run.norm)) for (const c of copyLines) if (c.norm.includes(run.norm) || run.norm.includes(c.norm)) seenCopy.add(c.line);
@@ -268,6 +279,12 @@ export async function runTextQa(session) {
         }
         if (textArea > 0 && decorArea / textArea > 0.25) results.decorArea.push(`${Math.round((100 * decorArea) / textArea)} % at frame ${f}`);
         if (sample.kind === 'mid') results.nonText.push(lumStdOutside(b, W, H, visibleRuns.flatMap((r) => r.rects)));
+        if (sample.kind === 'settled') {
+          const settledCopy = visibleRuns.filter((r) => !r.decor && r.opacity >= 0.95 && isCopy(r.norm));
+          for (const [i, j] of copyOverlaps(settledCopy.map((r) => r.box))) {
+            results.overlap.push(`"${settledCopy[i].text.slice(0, 30)}" over "${settledCopy[j].text.slice(0, 30)}" at frame ${f}`);
+          }
+        }
       }
       prevRuns = now;
     }
@@ -287,7 +304,7 @@ export async function runTextQa(session) {
   if (missing.length) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: copy line not on screen: "${missing[0].line}"${missing.length > 1 ? ` (+${missing.length - 1} more)` : ''}; every copy.lines entry must appear as text the QA can read`);
 
   const rules = [];
-  const row = (id, status, detail) => rules.push({ id, status, detail });
+  const row = (id, status, detail) => { rules.push({ id, status, detail }); if (!QA_ROW_IDS.includes(id)) QA_ROW_IDS.push(id); };
   const lowCopy = results.contrast.filter((c) => !c.decor && c.ratio < c.floor);
   const lowDecor = results.contrast.filter((c) => c.decor && c.ratio < c.floor);
   const worst = results.contrast.reduce((m, c) => (m && m.ratio / m.floor <= c.ratio / c.floor ? m : c), null);
@@ -307,9 +324,12 @@ export async function runTextQa(session) {
   row('qa-samples', results.moved.length ? 'WARN' : 'PASS', results.moved.length ? `state moved while the text was hidden at frames ${results.moved.slice(0, 6).join(', ')}; those samples were discarded` : `${samples.size} samples measured`);
   const lively = results.nonText.filter((s) => s > 8 / 255).length;
   row('non-text-presence', results.nonText.length && lively * 2 >= results.nonText.length ? 'PASS' : 'WARN', `${lively} of ${results.nonText.length} beat midpoints show a non-text image (luminance spread over 8/255 outside the text)`);
+  row('text-overlap', results.overlap.length ? 'FAIL' : 'PASS', results.overlap.length ? `settled copy overlaps: ${results.overlap[0]}` : 'no two settled copy lines overlap');
   return { rules, summary: { samples: [...samples.keys()].sort((a, b) => a - b), contrast: results.contrast.length, copySeen: [...seenCopy], meta: [...results.meta] } };
 }
 
+export const QA_ROW_IDS = ['text-contrast', 'text-title-safe', 'text-reading-floor', 'copy-found', 'decor-copy', 'decor-area', 'meta-label', 'fonts', 'canvas-text', 'qa-samples', 'non-text-presence', 'text-overlap'];
+
 // The platform names of this product's verified faces, read from probe spans.
 async function faceNames(stage) {
   await stage.page.evaluate(() => {

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

@@ -8,20 +8,39 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSy
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Worker } from 'node:worker_threads';
-import { ALWAYS_FLAGS, EXIT, OUTPUT } from './constants.mjs';
+import { ALWAYS_FLAGS, EXIT, OUTPUT, chromeFlagLadder } from './constants.mjs';
 import { chromeExecutable, launchCause, profileSockets } from './browser.mjs';
 import { FlashDetector } from './flash.mjs';
 import { encodePreview, ffprobe, hasFfmpeg, pngEncode, startMaster } from './encode.mjs';
 import { FORMATS, loadTreatment } from './treatment.mjs';
+import { readPlate } from './blender.mjs';
 import { recordFirstTreatment, writeJson, writeRunState } from './director.mjs';
 import { stampStills, stillsPlan, writeStillsSet } from './stills.mjs';
 import { runStageGate, renderStageReport } from './stage-gate.mjs';
 import { produceSound, soundGate } from './sound.mjs';
 import { runTextQa } from './stage-qa.mjs';
+import { readStyle, styleCss, styleScript } from './styles.mjs';
+import { addToStills, writeBoard } from './board.mjs';
 import { FONT_FILES } from './frame.mjs';
+
 import { findCache, fontFile, fontState, hangulPath, runtimeRequire, WARM } from '../bin/runtime.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
+// The pinned three.js build and its two addons (engine/vendor/three, MIT),
+// served to stage pages at /lit/three/; anything else under that prefix is refused.
+const THREE_DIR = join(here, 'vendor', 'three');
+
+// Resolve a /lit/three/ request to a vendored file: only .js paths without ..
+// that exist under engine/vendor/three. Anything else is refused, never served.
+export function threeFile(pathname) {
+  const rel = String(pathname).slice('/lit/three/'.length);
+  if (rel.split('/').includes('..') || !rel.endsWith('.js')) return { status: 404, reason: `request for ${pathname} is not a vendored three.js file` };
+  let real = null;
+  try { real = realpathSync(join(THREE_DIR, rel)); } catch { return { status: 404, reason: `request for ${pathname} is not a vendored three.js file` }; }
+  const root = realpathSync(THREE_DIR);
+  if (real !== root && !real.startsWith(root + sep)) return { status: 404, reason: `request for ${pathname} is not a vendored three.js file` };
+  return { status: 200, file: real };
+}
 export const ORIGIN = 'http://lit.stage';
 const sha = (data) => createHash('sha256').update(data).digest('hex');
 const fail = (code, message, extra = {}) => Object.assign(new Error(message), { exitCode: code, ...extra });
@@ -39,6 +58,19 @@ export const RASTER_LIMITS = Object.freeze({ count: 24, bytes: 8 * 1024 * 1024,
 // The software rung only (SwiftShader, CPU raster): a mismatch between two
 // captures can then only come from the page. Plus the stage set and the two
 // keychain flags every Chrome launch carries.
+// The 3D route's flag set: the platform's GPU rung first, then the software
+// rung; the determinism flags after the rung are the same as the software rung's.
+export function gpuStageFlags({ width, height }, platform = process.platform) {
+  return [...chromeFlagLadder(platform)[0], ...stageFlags({ width, height }).slice(3)];
+}
+
+// The browser rung: a three.js world asks for the GPU; anything else (a 2D
+// film, or a Blender film that shows its path-traced plate under HTML type)
+// needs only the software rung.
+export function stageRung(treatment) {
+  return treatment?.depth === '3d' && treatment?.render3d !== 'blender' ? 'gpu' : 'software';
+}
+
 export function stageFlags({ width, height }) {
   return [
     '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--disable-gpu-rasterization',
@@ -221,25 +253,62 @@ export function stageFile(root, pathname) {
   return { status: 200, file: real, type };
 }
 
-export async function openStage({ runtime, stageDir, profileRoot, width, height, seed, fontCss, fontFiles, env = process.env }) {
+const webglProbe = () => {
+  const canvas = document.createElement('canvas');
+  const gl = canvas.getContext('webgl2');
+  if (!gl) return { webgl2: false, renderer: null };
+  const ext = gl.getExtension('WEBGL_debug_renderer_info');
+  return { webgl2: true, renderer: ext ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) : null };
+};
+
+export async function openStage({ runtime, stageDir, profileRoot, width, height, seed, fontCss, fontFiles, style = null, rung = 'software', platform = process.platform, env = process.env }) {
   const chrome = chromeExecutable(env);
   if (!chrome) throw fail(EXIT.BLOCKED_NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; install Chrome or set CHROME_PATH');
   const { chromium } = runtime('playwright-core');
-  const flags = stageFlags({ width, height });
   mkdirSync(profileRoot, { recursive: true });
   const profile = join(profileRoot, 'p');
+  const launch = (flags) => chromium.launchPersistentContext(profile, {
+    executablePath: chrome, headless: true, chromiumSandbox: true, args: flags, timeout: 30000,
+    viewport: { width, height }, deviceScaleFactor: 1, serviceWorkers: 'block',
+  });
+  const notices = [];
+  let flags = rung === 'gpu' ? gpuStageFlags({ width, height }, platform) : stageFlags({ width, height });
+  let used = rung;
   let context;
   try {
-    context = await chromium.launchPersistentContext(profile, {
-      executablePath: chrome, headless: true, chromiumSandbox: true, args: flags, timeout: 30000,
-      viewport: { width, height }, deviceScaleFactor: 1, serviceWorkers: 'block',
-    });
+    context = await launch(flags);
   } catch (error) {
-    rmSync(profile, { recursive: true, force: true });
-    throw fail(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: headless Chrome failed to launch on the software rung: ${launchCause(error)}`);
+    if (rung !== 'gpu') {
+      rmSync(profile, { recursive: true, force: true });
+      throw fail(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: headless Chrome failed to launch on the software rung: ${launchCause(error)}`);
+    }
+    notices.push(`the 3D route asked for the GPU rung and it did not start (${launchCause(error).slice(0, 120)}); rendered on the software rung (SwiftShader), slower, same frames`);
+    flags = stageFlags({ width, height });
+    used = 'software';
+    try {
+      context = await launch(flags);
+    } catch (retry) {
+      rmSync(profile, { recursive: true, force: true });
+      throw fail(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: headless Chrome failed to launch on both rungs: ${launchCause(retry)}`);
+    }
   }
-  const page = context.pages()[0] || await context.newPage();
+  let page = context.pages()[0] || await context.newPage();
   page.setDefaultTimeout(0);
+  const probe = await page.evaluate(webglProbe).catch(() => ({ webgl2: false, renderer: null }));
+  if (used === 'gpu' && !probe.webgl2) {
+    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');
+    await context.close().catch(() => {});
+    flags = stageFlags({ width, height });
+    used = 'software';
+    try {
+      context = await launch(flags);
+    } catch (error) {
+      rmSync(profile, { recursive: true, force: true });
+      throw fail(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: headless Chrome failed to launch on the software rung: ${launchCause(error)}`);
+    }
+    page = context.pages()[0] || await context.newPage();
+    page.setDefaultTimeout(0);
+  }
   const cdp = await context.newCDPSession(page);
   const root = realpathSync(stageDir);
   const kit = readFileSync(join(here, 'stage-kit.js'));
@@ -260,6 +329,16 @@ export async function openStage({ runtime, stageDir, profileRoot, width, height,
     const path = decodeURIComponent(url.pathname);
     if (path === '/lit/stage-kit.js') return reply(200, CONTENT_TYPES['.js'], kit);
     if (path === '/lit/fonts.css') return reply(200, CONTENT_TYPES['.css'], fontCss);
+    if (path === '/lit/style.css' && style) return reply(200, CONTENT_TYPES['.css'], style.css);
+    if (path === '/lit/style.js' && style) return reply(200, CONTENT_TYPES['.js'], style.js);
+    if (path.startsWith('/lit/three/')) {
+      const found = threeFile(path);
+      if (found.status !== 200) {
+        contract.push(found.reason);
+        return reply(404, 'text/plain', 'not found');
+      }
+      return reply(200, CONTENT_TYPES['.js'], readFileSync(found.file));
+    }
     if (fontFiles.has(path)) return reply(200, CONTENT_TYPES[extname(path).toLowerCase()] || 'font/ttf', readFileSync(fontFiles.get(path)));
     const found = stageFile(root, path);
     if (found.status === 403) { contract.push(found.reason); return reply(403, 'text/plain', 'forbidden'); }
@@ -272,7 +351,7 @@ export async function openStage({ runtime, stageDir, profileRoot, width, height,
   await page.addInitScript({ content: `try { ${init.trim()}(${JSON.stringify({ seed, epochMs: 1767225600000 })}); } catch (error) { window.__litStageInitError = String(error && error.stack || error); }` });
   const sockets = profileSockets(profile);
   return {
-    page, cdp, flags, blocked, contract, sockets,
+    page, cdp, flags, blocked, contract, sockets, rung: used, renderer: probe.renderer, notices,
     async load() {
       await page.goto(`${ORIGIN}/index.html`, { waitUntil: 'load', timeout: 120000 });
       return page.evaluate(() => {
@@ -437,12 +516,22 @@ class StageSession {
     this.PNG = this.require('pngjs').PNG;
     this.fonts = fontRoutes(this.cache);
     this.ffmpeg = hasFfmpeg();
+    const filmStyle = readStyle(this.treatment.style);
+    this.style = { css: styleCss(filmStyle, this.treatment.format), js: styleScript(filmStyle, this.treatment.format, this.treatment) };
+    this.rung = stageRung(this.treatment);
+    // A Blender film shows its path-traced plate under HTML type, so it shares the page's
+    // run with a 3-D-of-any-kind page: render the plate first, blender --out DIR --final
+    // (no Blender: set render3d to three and use the GPU rung).
+    if (this.treatment.depth === '3d' && this.treatment.render3d === 'blender' && !readPlate(this.stageDir)) {
+      throw fail(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 ${this.out} --final (no Blender: set render3d to three and use the GPU rung)`);
+    }
   }
 
-  open(tag) {
+  open(tag, { stageDir = this.stageDir, width = this.size[0], height = this.size[1] } = {}) {
     return openStage({
-      runtime: this.require, stageDir: this.stageDir, profileRoot: join(this.out, '.run', `${tag}${process.pid % 100000}`),
-      width: this.size[0], height: this.size[1], seed: this.seed, fontCss: this.fonts.css, fontFiles: this.fonts.routes,
+      runtime: this.require, stageDir, profileRoot: join(this.out, '.run', `${tag}${process.pid % 100000}`),
+      width, height, seed: this.seed, fontCss: this.fonts.css, fontFiles: this.fonts.routes, style: this.style,
+      rung: this.rung || 'software',
     });
   }
 
@@ -576,7 +665,10 @@ class StageSession {
       schemaVersion: 2, path: 'stage', format: this.treatment.format, fps: this.fps, resolution: [W, H], durationSec: this.durationSec,
       targetDurationSec: this.treatment.durationSec, totalFrames: this.totalFrames, round: this.round, mode: this.mode,
       treatment: { file: join(this.out, 'treatment.json'), sha256: sha(readFileSync(join(this.out, 'treatment.json'))) },
-      chromeFlags: this.stage?.flags || [], chromeSockets: this.stage?.sockets || [], renderer: 'SwiftShader (software rung)',
+      chromeFlags: this.stage?.flags || [], chromeSockets: this.stage?.sockets || [],
+      rung: this.stage?.rung || this.rung || 'software',
+      renderer: this.stage?.rung === 'gpu' ? (this.stage?.renderer || 'GPU rung') : 'SwiftShader (software rung)',
+      rungNotices: this.stage?.notices || [],
       faces: this.faces, scan: this.scan, beats: this.beats, stills: this.plan, determinism: this.determinismResult || null,
       frameTimeMs: { p50: pick(0.5), p95: pick(0.95), captured: timing.length }, masterSec: this.masterSec, warnings: this.warnings,
       generatedAt: new Date().toISOString(), ...extra,
@@ -597,9 +689,24 @@ export async function stageCommand(flags) {
       writeJson(join(session.out, 'manifest.json'), manifest);
       stampStills(session.out);
       if (!session.ffmpeg && !session.stillsOnly) throw fail(EXIT.BLOCKED_NO_FFMPEG_FOR_VIDEO, `BLOCKED_NO_FFMPEG_FOR_VIDEO: stills and the contact sheet are in ${session.out}; ffmpeg is not on PATH, so no film was encoded`);
+      // The board round: the text and style rules run on the board frames, the storyboard is
+      // drawn with the verdict on it, and a FAIL ends the round here (exit 13).
+      const qa = await runTextQa(session);
+      writeJson(join(session.out, 'stills', 'check.json'), { rules: qa.rules, summary: qa.summary });
+      const beatFiles = stills.files.filter((f) => f.kind === 'beat-mid').sort((a, b) => a.beat - b.beat).map((f) => join(session.out, f.file));
+      const boardFile = await writeBoard({
+        out: session.out, treatment: session.treatment, beatFiles, check: { rules: qa.rules },
+        open: (opts) => session.open('b', opts),
+      });
+      const boardSha = addToStills(session.out, { file: 'stills/board.png', kind: 'board', frames: session.beats.map((b) => b.index) }, { sha256: sha });
+      const failed = qa.rules.filter((rule) => rule.status === 'FAIL');
+      if (failed.length) {
+        writeRunState(session.out, { exitCode: EXIT.GATE_FAIL_QA, mode: session.mode, round: session.round, finished: false, failed: failed.map((r) => r.id), path: 'stage' });
+        throw fail(EXIT.GATE_FAIL_QA, `BOARD_CHECK_FAIL: ${failed.map((r) => `${r.id} ${r.detail}`).join('; ')}. Fix the page, render --stills-only again, then look at the board ${boardFile} and every file in ${join(session.out, 'stills')}`);
+      }
       writeRunState(session.out, { exitCode: 0, mode: session.mode, round: session.round, finished: true, failed: [], path: 'stage' });
-      console.log(`stills: ${stills.files.map((f) => join(session.out, f.file)).join(' ')}`);
-      console.log('View every still, strip and the contact sheet, then record the round with `look` before the full render.');
+      console.log(`stills: ${stills.files.map((f) => join(session.out, f.file)).join(' ')} board ${boardFile} (stills index ${boardSha.slice(0, 12)})`);
+      console.log(`STILLS ONLY: board check PASS; open the storyboard ${boardFile} and every file in ${join(session.out, 'stills')}, record the round with look --round ${session.round}, make the change, then render the film with --round ${session.round + 1} (no --stills-only).`);
       return 0;
     }
     await session.determinism();