@litfamily/litopencode 1.0.31 → 1.0.32

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

@@ -7,16 +7,47 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { boxContrast } from "../contrast.mjs";
 import { linearLut } from "../flash.mjs";
+import { regionFill } from "../fill.mjs";
 import { decodePng } from "../png.mjs";
 import { readingFloor } from "../text.mjs";
-import { normalize, withoutQuotes } from "../treatment.mjs";
+import { LAYOUTS, ZONE_TOLERANCE, readStyle, scaleStep, styleFamilies, styleTextColors } from "../styles.mjs";
+import { assetUsed } from "../assets.mjs";
+import { normalize, registerOf, withoutQuotes } from "../treatment.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const qaPageSource = () => readFileSync(path.join(here, "qa-page.js"), "utf8");
-export const qaLimits = Object.freeze({ inkDelta: 2, minInkPixels: 12, visibleOpacity: 0.6, judgedOpacity: 0.95, settledPx: 2, decorShare: 0.25, presenceStd: 8 / 255, largeShare: 0.03, safeInset: 0.05, floorTolerance: 0.1 });
+export const qaLimits = Object.freeze({
+  inkDelta: 2, minInkPixels: 12, visibleOpacity: 0.6, judgedOpacity: 0.95, settledPx: 2, decorShare: 0.25, presenceStd: 8 / 255, largeShare: 0.03, safeInset: 0.05, floorTolerance: 0.1,
+  // The house-style rules: two visible runs overlap past this share of the smaller box; copy colour may
+  // sit this far (RGB distance) from a style text role; shot changes are sampled this far on each side.
+  overlapShare: 0.08, emptyRegion: 0.15, emptyRegionsMax: 2, colourDistance: 12, cutWindowSec: 0.4, cutStepSec: 1 / 15, settledAt: Object.freeze([0.35, 0.8])
+});
+export const TEXT_QA = qaLimits;
 const internalTerms = /(?<![\p{L}\p{N}])(?:path|preset|gate|beat|treatment)(?![\p{L}\p{N}])/iu;
 const fileName = /(?<![\p{L}\p{N}])[\w-]+\.(?:html?|json|mjs|js|css|png|jpe?g|webp|svg|wav|mp4|md)(?![\p{L}\p{N}])/iu;
 
+// The QA sample frames: each beat midpoint plus two settled frames, and a sample every 1/15 s within
+// 0.4 s of each cut (`cut: true`), where an outgoing and an incoming line can cross. The cut rows feed
+// only the text-over-text check; a line mid-transition is not judged for style or zone.
+export function qaSamples({ beats, fps, frameCount }) {
+  const clamp = (f) => Math.max(0, Math.min(frameCount - 1, Math.round(f)));
+  const rows = new Map();
+  beats.forEach((beat, i) => {
+    for (const q of qaLimits.settledAt) rows.set(clamp((beat.t0 + q * (beat.t1 - beat.t0)) * fps), { frame: clamp((beat.t0 + q * (beat.t1 - beat.t0)) * fps), beat: i, mid: false });
+  });
+  beats.forEach((beat, i) => {
+    const frame = clamp(((beat.t0 + beat.t1) / 2) * fps);
+    rows.set(frame, { frame, beat: i, mid: true });
+  });
+  const reach = Math.round(qaLimits.cutWindowSec * fps), step = Math.max(1, Math.round(qaLimits.cutStepSec * fps));
+  beats.forEach((beat, i) => {
+    if (i === 0) return;
+    const at = Math.round(beat.t0 * fps);
+    for (let f = clamp(at - reach); f <= clamp(at + reach); f += step) if (!rows.has(f)) rows.set(f, { frame: f, beat: f < at ? i - 1 : i, mid: false, cut: true });
+  });
+  return [...rows.values()].sort((a, b) => a.frame - b.frame);
+}
+
 export function titleSafeBox(width, height) {
   return [width * qaLimits.safeInset, height * qaLimits.safeInset, width * (1 - qaLimits.safeInset), height * (1 - qaLimits.safeInset)];
 }
@@ -39,10 +70,10 @@ const keyOf = (run, width, height) => {
 // Drives the QA browser; returns the raw samples and the 10 fps track for analyseQa().
 export async function captureQa(stage, context, frameCount) {
   const { fps, treatment } = context;
-  const clamp = (f) => Math.max(0, Math.min(frameCount - 1, Math.round(f)));
-  const mids = new Set(treatment.beats.map((b) => clamp(((b.t0 + b.t1) / 2) * fps)));
-  const settled = treatment.beats.flatMap((b) => [0.35, 0.8].map((q) => clamp((b.t0 + q * (b.t1 - b.t0)) * fps)));
-  const qaFrames = new Set([...mids, ...settled]);
+  const plan = qaSamples({ beats: treatment.beats, fps, frameCount });
+  const byFrame = new Map(plan.map((row) => [row.frame, row]));
+  const mids = new Set(plan.filter((row) => row.mid).map((row) => row.frame));
+  const qaFrames = new Set(plan.map((row) => row.frame));
   const trackStep = Math.max(1, Math.round(fps / 10));
   const page = stage.page, cdp = stage.cdp;
   await cdp.send("DOM.enable");
@@ -85,11 +116,99 @@ export async function captureQa(stage, context, frameCount) {
       fonts = marks.map((list) => [...new Set(list.flatMap((mark) => byMark.get(mark) ?? []))]);
       await page.evaluate(() => window.__litQa.unmarkFonts());
     }
-    samples.push({ frame, mid: mids.has(frame), runs, a, b, fonts });
+    const row = byFrame.get(frame);
+    samples.push({ frame, beat: row.beat, mid: row.mid, cut: row.cut === true, runs, a, b, fonts });
   }
   return { track, samples, trackStep, allowed: [...allowed], canvasTexts: [...canvasTexts] };
 }
 
+const inkIn = (diff, width, height, rects) => {
+  let n = 0;
+  for (const [x0, y0, x1, y1] of rects) {
+    for (let y = Math.max(0, Math.floor(y0)); y < Math.min(height, Math.ceil(y1)); y++) for (let x = Math.max(0, Math.floor(x0)); x < Math.min(width, Math.ceil(x1)); x++) if (diff[y * width + x]) n += 1;
+  }
+  return n;
+};
+
+// [r, g, b] of a CSS colour string (rgb(), rgba() or #hex), or null.
+export function parseCssColour(value) {
+  const text = String(value ?? "").trim();
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/u.exec(text);
+  if (rgb) return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+  const hex = /^#([0-9a-f]{6})$/iu.exec(text);
+  return hex ? [0, 2, 4].map((i) => Number.parseInt(hex[1].slice(i, i + 2), 16)) : null;
+}
+
+const area = (b) => Math.max(0, b[2] - b[0]) * Math.max(0, b[3] - b[1]);
+const overlapArea = (a, b) => area([Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.min(a[2], b[2]), Math.min(a[3], b[3])]);
+
+// The house-style rules on the collected samples, as gate rows. Text over text: any two visible,
+// non-decor runs sharing more than 8 % of the smaller box, at the QA samples and across the cuts. For
+// copy that is settled: the style's colours, faces and type scale, and the shot's type zone.
+// Each sample is { frame, beat, cut, runs: [{ text, kind, copy, decor, settled, color, family, fontSizePx, gradient, box }] }.
+export function judgeStyle({ treatment, width, height, samples }) {
+  const style = readStyle(treatment.style);
+  const format = width >= height ? "16:9" : "9:16";
+  const colours = styleTextColors(style).map(parseCssColour);
+  const families = styleFamilies(style);
+  const overlaps = [], offColour = [], offFace = [], offScale = [], offScaleOther = [], offZone = [];
+  const tolX = width * ZONE_TOLERANCE, tolY = height * ZONE_TOLERANCE;
+  for (const sample of samples) {
+    const visible = sample.runs.filter((run) => run.box && !run.decor);
+    for (let i = 0; i < visible.length; i++) for (let j = i + 1; j < visible.length; j++) {
+      const a = visible[i], b = visible[j];
+      if (overlapArea(a.box, b.box) > qaLimits.overlapShare * Math.min(area(a.box), area(b.box))) overlaps.push(`"${a.text.slice(0, 24)}" x "${b.text.slice(0, 24)}"@${sample.frame}${sample.cut ? " (cut)" : ""}`);
+    }
+    if (sample.cut) continue;
+    const beat = treatment.beats[sample.beat];
+    const layout = beat?.layout ? LAYOUTS[format][beat.layout] : null;
+    for (const run of sample.runs) {
+      if (run.kind === "canvas" || !run.settled || !run.box) continue;
+      const where = `"${run.text.slice(0, 32)}"@${sample.frame}`;
+      if (run.copy) {
+        const rgb = parseCssColour(run.color);
+        if (!run.gradient && rgb && !colours.some((c) => Math.hypot(c[0] - rgb[0], c[1] - rgb[1], c[2] - rgb[2]) <= qaLimits.colourDistance)) offColour.push(`${where} ${run.color}`);
+        if (run.family && !families.has(run.family)) offFace.push(`${where} ${run.family}`);
+      }
+      if (run.fontSizePx && !scaleStep(style, format, run.fontSizePx)) (run.copy ? offScale : offScaleOther).push(`${where} ${Math.round(run.fontSizePx)}px`);
+      if (run.copy && layout) {
+        const z = layout.type;
+        if (!z) offZone.push(`${where} in a full shot (no copy zone)`);
+        else {
+          const [zx, zy, zw, zh] = [z[0] * width, z[1] * height, z[2] * width, z[3] * height];
+          if (run.box[0] < zx - tolX || run.box[1] < zy - tolY || run.box[2] > zx + zw + tolX || run.box[3] > zy + zh + tolY) offZone.push(`${where} outside the ${beat.layout} type zone`);
+        }
+      }
+    }
+  }
+  const list = (items) => `${items.slice(0, 3).join(", ")}${items.length > 3 ? ` (+${items.length - 3} more)` : ""}`;
+  const steps = Object.entries(style.scale[format]).map(([k, v]) => `${k} ${v}`).join(", ");
+  const styleFails = [
+    offColour.length ? `colour off the ${style.id} text roles (${style.textRoles.join(", ")}): ${list(offColour)}` : null,
+    offFace.length ? `face outside the style (${[...families].join(", ")}): ${list(offFace)}` : null,
+    offScale.length ? `size off the type scale (${steps} px, +-4 %): ${list(offScale)}` : null
+  ].filter(Boolean);
+  return {
+    "TEXT-OVERLAP": overlaps.length ? { pass: false, detail: `text over text: ${list(overlaps)}` } : { pass: true, detail: `no two visible text runs overlap at the QA samples${samples.some((s) => s.cut) ? " or across the cuts" : ""}` },
+    "TEXT-ON-STYLE": styleFails.length ? { pass: false, detail: styleFails.join("; ") }
+      : offScaleOther.length ? { pass: false, warn: true, detail: `copy is on the ${style.id} style; other text off the scale: ${list(offScaleOther)}` }
+        : { pass: true, detail: `copy uses the ${style.id} colours, faces and type scale` },
+    "TEXT-ZONE": offZone.length ? { pass: false, detail: list(offZone) } : { pass: true, detail: "every settled copy run sits in its shot's type zone" }
+  };
+}
+
+// RICH-FILL: at each shot's midpoint the frame is cut into 4 x 3 regions, and a region under 0.15 busy
+// share is empty. A rich film leaves at most 2 of the 12 empty in all but one shot (the end card may
+// breathe). A minimal film is exempt: negative space is its point.
+export function richFill({ treatment, mids }) {
+  if (registerOf(treatment) === "minimal") return { pass: true, na: true, detail: "minimal register: negative space is the point" };
+  const measured = mids.filter((sample) => Array.isArray(sample.regions));
+  if (!measured.length) return { pass: true, na: true, detail: "region fill not measured" };
+  const thin = measured.map((sample) => ({ beat: sample.beat, empty: sample.regions.filter((value) => value < qaLimits.emptyRegion).length })).filter((shot) => shot.empty > qaLimits.emptyRegionsMax);
+  if (thin.length <= 1) return { pass: true, detail: `${measured.length - thin.length} of ${measured.length} shot midpoints fill the frame (at most ${qaLimits.emptyRegionsMax} of 12 regions empty${thin.length ? `; shot ${thin[0].beat + 1} may breathe` : ""})` };
+  return { pass: false, detail: `${thin.length} of ${measured.length} shot midpoints leave the frame empty: ${thin.map((shot) => `shot ${shot.beat + 1} has ${shot.empty} of 12 regions empty`).join(", ")} (a rich film fills the frame: more drawing, more labels, a layer behind the subject)` };
+}
+
 // Turns the captures into gate rows. Copy runs (their text holds a copy line) FAIL; decor runs WARN.
 export function analyseQa(raw, context) {
   const { width, height, fps, treatment } = context;
@@ -104,8 +223,11 @@ export function analyseQa(raw, context) {
   const trackByFrame = new Map(raw.track.map((entry) => [entry.frame, entry]));
   let presenceHits = 0, presenceMids = 0;
   const judged = [];
+  const styleSamples = [];
+  const fillSamples = [];
   for (const sample of raw.samples) {
     const A = rgbaOf(sample.a), B = rgbaOf(sample.b);
+    if (sample.mid) fillSamples.push({ beat: sample.beat, regions: regionFill(A, width, height) });
     const grow = (run) => Math.max(2, 0.2 * run.fontSize * run.scale);
     const textRects = sample.runs.flatMap((run) => run.rects.map(([x0, y0, x1, y1]) => [x0 - grow(run), y0 - grow(run), x1 + grow(run), y1 + grow(run)]));
     const inText = (x, y) => textRects.some(([x0, y0, x1, y1]) => x >= x0 && x < x1 && y >= y0 && y < y1);
@@ -117,6 +239,18 @@ export function analyseQa(raw, context) {
         if (!inText(p % width, Math.floor(p / width))) outside += 1;
       }
     }
+    if (sample.cut) {
+      // A shot change in flight: only the text-over-text check reads it (judgeStyle).
+      if (outside > 0) continue;
+      const runs = [];
+      for (const run of sample.runs) {
+        if (run.kind === "canvas" || run.decor || run.opacity < qaLimits.visibleOpacity || !onScreen(run.rects, width, height)) continue;
+        if (inkIn(diff, width, height, run.rects) < qaLimits.minInkPixels) continue;
+        runs.push({ text: run.text, kind: run.kind, copy: isCopy(run), decor: false, settled: false, box: union(run.rects) });
+      }
+      styleSamples.push({ frame: sample.frame, beat: sample.beat, cut: true, runs });
+      continue;
+    }
     if (sample.mid) {
       presenceMids += 1;
       let n = 0, sum = 0, sumSq = 0;
@@ -129,6 +263,7 @@ export function analyseQa(raw, context) {
     }
     if (outside > 0) { warns.moved.push(`frame ${sample.frame}: ${outside} pixels changed outside the text (state moved; sample discarded)`); continue; }
     let visibleArea = 0, decorArea = 0;
+    const styleRuns = [];
     sample.runs.forEach((run, index) => {
       if (run.kind === "canvas") { if (run.opacity >= qaLimits.visibleOpacity && onScreen(run.rects, width, height)) seenVisible.add(run.norm); return; }
       const mask = new Uint8Array(width * height);
@@ -162,6 +297,7 @@ export function analyseQa(raw, context) {
         const mine = union(run.rects), theirs = match ? union(match.rects) : null;
         return theirs && mine.every((v, k) => Math.abs(v - theirs[k]) < qaLimits.settledPx);
       });
+      styleRuns.push({ text: run.text, kind: run.kind, copy, decor: run.decor, settled, color: run.color, family: run.family, fontSizePx: run.fontSize * run.scale, gradient: run.gradient, box });
       if (!settled) return;
       const sizePx = run.fontSize * run.scale;
       const measured = boxContrast(A, mask, width, height, { bbox: box, capHeightPx: sizePx, fill: run.gradient ? "gradient" : "solid", fontSizePx: sizePx, weight: run.weight }, shortSide / 1080, sizePx >= qaLimits.largeShare * shortSide);
@@ -169,6 +305,7 @@ export function analyseQa(raw, context) {
       judged.push({ frame: sample.frame, text: run.text, ratio: Number(measured.ratio.toFixed(2)), floor: measured.floor, copy, decor: run.decor });
       if (measured.ratio < measured.floor) (copy && !run.decor ? fails.contrast : warns.contrast).push(`"${run.text}" at frame ${sample.frame}: ${measured.ratio.toFixed(2)}:1 < ${measured.floor}:1`);
     });
+    styleSamples.push({ frame: sample.frame, beat: sample.beat, cut: false, runs: styleRuns });
     if (visibleArea > 0 && decorArea / visibleArea > qaLimits.decorShare) fails.decor.push(`decor text covers ${Math.round((100 * decorArea) / visibleArea)} % of the visible text at frame ${sample.frame}`);
   }
   // The 1/10 s track: visible copy runs for the reading floor, and every run for the meta-label lint.
@@ -202,6 +339,10 @@ export function analyseQa(raw, context) {
     "TEXT-decor": row(fails.decor, "decor text carries no copy and stays under 25 % of the text"),
     "TEXT-fonts": row(fails.fonts, `copy draws only with ${raw.allowed.join(", ")}`)
   };
+  const used = context.stageDir ? assetUsed(treatment, context.stageDir) : null;
+  if (used) checks["ASSET-USED"] = used;
+  if (treatment.path === "stage") checks["RICH-FILL"] = richFill({ treatment, mids: fillSamples });
+  if (treatment.style) Object.assign(checks, judgeStyle({ treatment, width, height, samples: styleSamples }));
   for (const [id, value] of Object.entries({ "TEXT-decor-contrast": warnRow(warns.contrast, "decor contrast"), "TEXT-moved": warnRow(warns.moved, "samples discarded"), "TEXT-meta-labels": warnRow([...warns.meta], "request, idea, file name or internal term on screen"),
     "TEXT-canvas": warnRow(warns.canvas, "canvas text not measured"), "TEXT-decor-fonts": warnRow(warns.fonts, "decor fonts"), "TEXT-presence": warns.presence ? { pass: false, warn: true, detail: warns.presence } : null })) if (value) checks[id] = value;
   return { checks, missing, judged, samples: raw.samples.map((sample) => ({ frame: sample.frame, mid: sample.mid, runs: sample.runs.length })), trackFrames: raw.track.length, allowedFaces: raw.allowed };

package/skills/lit-typographic-motion/engine/stage/render.mjs

@@ -23,6 +23,9 @@ import { SOUND_EXIT, muxTrack, resolveTrack, soundChecks } from "../sound.mjs";
 import { frameSize, keepFirstTreatment, loadTreatment } from "../treatment.mjs";
 import { inspectWarmState, pins, skillRoot } from "../../runtime.mjs";
 import { previewEncoderRung } from "../../probe.mjs";
+import { addToStills, boardRules, writeBoard } from "../board.mjs";
+import { readStyle, styleCss, styleScript } from "../styles.mjs";
+import { requirePlate } from "../blender.mjs";
 import { openStage, stageFonts } from "./capture.mjs";
 import { analyseQa, captureQa, qaPageSource } from "./qa.mjs";
 import { StageError, scanStage, stageSha } from "./scan.mjs";
@@ -111,6 +114,7 @@ export function prepareStage(out) {
   const stageDir = path.join(out, "stage");
   if (!existsSync(path.join(stageDir, "index.html"))) throw new StageError(17, "STAGE_CONTRACT_ERROR", `no stage page at ${path.join(stageDir, "index.html")}; write it first (references/stage.md)`);
   const scan = scanStage(stageDir);
+  const plate = requirePlate(treatment, stageDir);
   const state = inspectWarmState();
   if (state.blocked) throw exit(state.blocked.exit, state.blocked.name, `${state.blocked.detail}; fix: ${state.fix}`);
   const chrome = findChrome();
@@ -118,19 +122,26 @@ export function prepareStage(out) {
   const { width, height } = frameSize(treatment);
   const fps = treatment.fps ?? 60;
   const seed = Number.isSafeInteger(treatment.seed) ? treatment.seed >>> 0 : fnv1a32(treatment.request);
-  return { treatment, stageDir, scan, state, chromePath: chrome.path, width, height, fps, seed, fonts: stageFonts(skillRoot, state, pins) };
+  const style = readStyle(treatment.style);
+  const styleFiles = { "/lit/style.css": styleCss(style, treatment.format), "/lit/style.js": styleScript(style, treatment.format, treatment) };
+  return { treatment, stageDir, scan, state, chromePath: chrome.path, width, height, fps, seed, fonts: stageFonts(skillRoot, state, pins), style, styleFiles, rung: stageRung(treatment), plate, notices: [] };
 }
 
-// Opens a stage browser, loads the page and checks its contract against the treatment.
-async function openChecked(chromium, context, profile, extraInit) {
-  const stage = await openStage(chromium, { chromePath: context.chromePath, profile, stageDir: context.stageDir, width: context.width, height: context.height, fps: context.fps, seed: context.seed, fonts: context.fonts, extraInit });
+// A three.js world asks for the GPU rung; every other film is on the software rung, a Blender film too:
+// its world is the plate, and the page only draws type over it.
+export const stageRung = (treatment) => (treatment.depth === "3d" && treatment.render3d !== "blender" ? "gpu" : "swiftshader");
+
+const fellBack = (why) => `the 3D route asked for the GPU rung and ${why}; rendered on the software rung (SwiftShader), slower, same frames`;
+
+// Opens one browser on `rung`, loads the page and checks its contract against the treatment.
+async function openOnRung(chromium, context, profile, extraInit, rung) {
+  const stage = await (context.opener ?? openStage)(chromium, { chromePath: context.chromePath, profile, stageDir: context.stageDir, width: context.width, height: context.height, fps: context.fps, seed: context.seed, fonts: context.fonts, extraInit, styleFiles: context.styleFiles, rung });
   try {
     const { definition, webgl } = await stage.load(context.scan.rasters.map((raster) => `/${raster.rel}`));
     if (!definition) throw new StageError(17, "STAGE_CONTRACT_ERROR", "the page never called LitStage.define({ width, height, fps, duration, render }) or set window.litStage");
     if (definition.width !== context.width || definition.height !== context.height) throw new StageError(17, "STAGE_CONTRACT_ERROR", `the page defines ${definition.width}x${definition.height}; the treatment's ${context.treatment.format} needs ${context.width}x${context.height}`);
     if ((definition.fps ?? 60) !== context.fps) throw new StageError(17, "STAGE_CONTRACT_ERROR", `the page defines ${definition.fps} fps; the treatment renders at ${context.fps}`);
     if (!(Number.isFinite(definition.duration) && definition.duration > 0)) throw new StageError(17, "STAGE_CONTRACT_ERROR", "the page's duration must be a positive number of seconds");
-    if (webgl.failed) throw exit(EXIT.BLOCKED_NO_WEBGL2, "BLOCKED_NO_WEBGL2", "the page asked for a WebGL context and the software renderer gave none; fix: check SwiftShader availability");
     return { stage, definition, webgl };
   } catch (error) {
     await stage.close();
@@ -138,6 +149,34 @@ async function openChecked(chromium, context, profile, extraInit) {
   }
 }
 
+// The GPU rung comes first when the context asks for it. When it cannot start, or gives the page no
+// WebGL, the whole round (every later browser too) takes the software rung and says so in a notice.
+// A page that breaks the stage contract is not retried: it would break the same way there.
+export async function openChecked(chromium, context, profile, extraInit) {
+  if (context.rung === "gpu") {
+    let opened;
+    try { opened = await openOnRung(chromium, context, profile, extraInit, "gpu"); }
+    catch (error) {
+      if (error?.exitCode !== undefined && error.exitCode !== EXIT.BLOCKED_NO_CHROME) throw error;
+      const line = String(error?.message ?? error).split("\n").find((part) => part.trim()) ?? "no detail";
+      context.rung = "swiftshader";
+      context.notices.push(fellBack(`it did not start (${line.slice(0, 160)})`));
+    }
+    if (opened) {
+      if (!opened.webgl.failed) return opened;
+      await opened.stage.close();
+      context.rung = "swiftshader";
+      context.notices.push(fellBack("the page got no WebGL there"));
+    }
+  }
+  const opened = await openOnRung(chromium, context, profile, extraInit, "swiftshader");
+  if (opened.webgl.failed) {
+    await opened.stage.close();
+    throw exit(EXIT.BLOCKED_NO_WEBGL2, "BLOCKED_NO_WEBGL2", "the page asked for a WebGL context and the software renderer gave none; fix: check SwiftShader availability");
+  }
+  return opened;
+}
+
 // Captures `frames` (sorted) in one browser by stepping every frame from 0. The stills round skips the
 // compositor wait and the capture on frames it does not keep. The determinism replay (`exact`) repeats
 // the master's own sequence instead, settling and capturing every frame and keeping only the samples:
@@ -205,7 +244,7 @@ async function captureMaster(context, stage, frameCount, keep, previewSources, r
     const result = await job.promise;
     const record = detector.push(result.cells);
     hashes.set(job.frame, result.hash);
-    writeSync(logFd, JSON.stringify({ frame: job.frame, rgbaSha256: result.hash, p995L: result.p995L, transitions: { up: record.up, down: record.down, redUp: record.redUp, redDown: record.redDown }, fullStep: record.fullStep }) + "\n");
+    writeSync(logFd, JSON.stringify({ frame: job.frame, rgbaSha256: result.hash, p995L: result.p995L, p005L: result.p005L, busy: result.busy, transitions: { up: record.up, down: record.down, redUp: record.redUp, redDown: record.redDown }, fullStep: record.fullStep }) + "\n");
     await write(master.child, Buffer.from(result.rgba.buffer, result.rgba.byteOffset, result.rgba.byteLength));
     if (result.previewPng) writeFileSync(path.join(pvDir, `f${job.frame}.png`), result.previewPng);
     consumed += 1;
@@ -288,6 +327,25 @@ function previewSourceFrames(fps, frameCount) {
   return sources;
 }
 
+// The board round: the layout check (the text QA replay) runs on the page before any film is encoded,
+// its rows go to stills/check.json, and the storyboard is drawn with the verdict on it. `qa` is the
+// finished QA result when the full render already ran it.
+async function boardRound(out, context, chromium, runDir, stills, { frameCount, qa = null }) {
+  let result = qa;
+  if (!result) {
+    const opened = await openChecked(chromium, context, path.join(runDir, "sq"), qaPageSource());
+    try { result = analyseQa(await captureQa(opened.stage, context, frameCount), context); } finally { await opened.stage.close(); }
+  }
+  const rules = boardRules(result.checks);
+  writeFileSync(path.join(out, "stills", "check.json"), JSON.stringify({ rules }, null, 2) + "\n");
+  const beats = stills.files.filter((entry) => entry.kind === "beat");
+  const file = await writeBoard({ out, context, chromium, treatment: context.treatment, beatFiles: beats.map((entry) => path.join(out, entry.file)), rules });
+  const entry = { file: "stills/board.png", kind: "board", frames: beats.map((beat) => beat.frame) };
+  addToStills(out, entry);
+  stills.files = JSON.parse(readFileSync(path.join(out, "stills", "stills.json"), "utf8")).files;
+  return { qa: result, rules, file, failed: rules.filter((rule) => rule.status === "FAIL") };
+}
+
 // Moves the previous round's exports aside so a new render never mixes with them.
 function clearExports(out, runDir) {
   const previous = path.join(runDir, "previous-round");
@@ -322,6 +380,8 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
       stills = writeStillsSet(out, { width: context.width, height: context.height, fps: context.fps, frames, plan, round, pathName: "stage", beats: context.treatment.beats });
       resolveTrack(out, context.treatment, { frameCount, fps: context.fps, cuts: stageCuts(context) });
       writeFileSync(path.join(runDir, "stills-timing.json"), JSON.stringify({ frames: plan.all.length, totalSec: Number(((performance.now() - began) / 1000).toFixed(1)) }) + "\n");
+      const board = stillsOnly ? await boardRound(out, context, chromium, runDir, stills, { frameCount }) : null;
+      if (board) return { stillsOnly: true, stills, frameCount, board };
       if (noFfmpeg) throw exit(EXIT.BLOCKED_NO_FFMPEG_FOR_VIDEO, "BLOCKED_NO_FFMPEG_FOR_VIDEO", "ffmpeg not found on PATH; the stills and contact sheet were written; fix: install ffmpeg, or keep working from `stage --stills-only`, which needs no ffmpeg");
       return { stillsOnly: true, stills, frameCount };
     }
@@ -361,6 +421,7 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
     if (qaResult.missing.length) throw new StageError(17, "STAGE_CONTRACT_ERROR", `copy line never found on screen: ${qaResult.missing.map((line) => `"${line}"`).join(", ")}`);
     const frames = new Map([...plan.all].map((frame) => [frame, decodeRgba(master.kept.get(frame))]));
     stills = writeStillsSet(out, { width: context.width, height: context.height, fps: context.fps, frames, plan, round, pathName: "stage", beats: context.treatment.beats });
+    await boardRound(out, context, chromium, runDir, stills, { frameCount, qa: qaResult });
     const poster = posterPng(decodeRgba(master.kept.get(posterFrame)), context.width, context.height);
     writeFileSync(path.join(runDir, "poster.png"), poster.png);
     writeFileSync(path.join(runDir, "reduced-motion.png"), encodePng(context.width, context.height, decodeRgba(master.kept.get(stillFrame)), 4, 9, true));
@@ -385,10 +446,11 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
     const manifest = {
       schemaVersion: 1, path: "stage", format: context.treatment.format, resolution: [context.width, context.height], fps: context.fps, frameCount,
       durationSec: frameCount / context.fps, targetDurationSec: context.treatment.durationSec, seed: context.seed, craftRound: round,
-      chromeFlags: stage.flags, webgl, previewEncoder: preview?.encoder ?? null,
+      chromeFlags: stage.flags, rung: context.rung, renderer: webgl.renderer ?? null, ...(context.notices.length ? { warnings: [...context.notices] } : {}), webgl, previewEncoder: preview?.encoder ?? null,
       preview: preview ? { width: preview.width, height: preview.height, fps: preview.fps, bytes: preview.bytes } : null,
       posterFrame, posterSize: [poster.width, poster.height], stillFrame, determinismFrames: samples,
       timing: { ...master.timing, totalSec: Number(((performance.now() - began) / 1000).toFixed(1)) },
+      ...(context.plate ? { plate: { blender: context.plate.blender, engine: context.plate.engine, device: context.plate.device, samples: context.plate.samples, fps: context.plate.fps, frames: context.plate.frames.length } } : {}),
       sound, qa: { file: ".run/qa.json", samples: qaResult.samples.length, trackFrames: qaResult.trackFrames, allowedFaces: qaResult.allowedFaces },
       treatmentSha256: sha256(readFileSync(path.join(out, "treatment.json"))), stageSha256: stageSha(context.stageDir),
       stillsSha256: sha256(readFileSync(path.join(out, "stills", "stills.json"))), pageErrors: stage.errors.slice(0, 5), missingAssets: stage.missing.slice(0, 5),

package/skills/lit-typographic-motion/engine/stage/scan.mjs

@@ -3,7 +3,7 @@
 // elements and APIs, flipbooks and animated rasters, and a raster budget overrun (exit 17). The same
 // rules also run live in the page (clock.js); this scan names the file and line first.
 import { createHash } from "node:crypto";
-import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 
 export const STAGE_CONTRACT = 17;
@@ -15,6 +15,22 @@ export const contentTypes = Object.freeze({
   ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
   ".gif": "image/gif", ".wav": "audio/wav", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf", ".json": "application/json"
 });
+// The Blender plate (stage/plate/, and the preview stills in stage/plate-preview/): frames the runner wrote
+// and plate.json lists by name and size. They are not page rasters. Returns { ...plate.json, dir } when every
+// listed frame is there as listed, else null.
+export function readPlate(stageDir, sub = "plate") {
+  const file = path.join(stageDir, sub, "plate.json");
+  if (!existsSync(file)) return null;
+  let plate;
+  try { plate = JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+  if (!Array.isArray(plate.frames)) return null;
+  const listed = plate.frames.every((f) => {
+    const full = path.join(stageDir, sub, String(f.name));
+    return path.basename(String(f.name)) === f.name && existsSync(full) && statSync(full).size === f.bytes;
+  });
+  return listed ? { ...plate, dir: sub } : null;
+}
+
 export const rasterLimits = Object.freeze({ files: 24, bytes: 8 * 1024 * 1024, sameSizeFlipbook: 10 });
 // XML namespace identifiers are names, not requests.
 const namespaceUris = /https?:\/\/www\.w3\.org\/(?:2000\/svg|1999\/xlink|1999\/xhtml|XML\/1998\/namespace|2000\/xmlns\/?|1998\/Math\/MathML)/gu;
@@ -113,9 +129,12 @@ export function scanStage(stageDir) {
   if (!files.includes("index.html")) throw contract("stage/index.html is missing");
   const rasters = [];
   let rasterBytes = 0;
+  const plates = ["plate", "plate-preview"].map((sub) => readPlate(stageDir, sub)).filter(Boolean);
+  const plated = new Set(plates.flatMap((plate) => plate.frames.map((f) => `${plate.dir}/${f.name}`)));
   for (const rel of files) {
     const ext = path.extname(rel).toLowerCase();
     const full = path.join(stageDir, rel);
+    if (rel === "scene.py" || plated.has(rel)) continue;
     if (!Object.hasOwn(contentTypes, ext)) throw contract(`${rel}: ${ext || "extensionless"} files are not served on the stage`);
     if (rasterExtensions.has(ext)) {
       const bytes = readFileSync(full);

package/skills/lit-typographic-motion/engine/stage/stage-kit.js

@@ -1,8 +1,9 @@
 // LitOpenCode stage kit, served at /lit/stage-kit.js. Motion primitives only: eases, a spring,
 // keyframes, timing helpers, a seeded random source, text splitting, SVG path drawing, a single-path
-// morph, mask and clip helpers, colour mixing and the text registration the QA replay reads. It ships
-// no scene, object, layout or copy; the page draws whatever its treatment calls for. Every function is
-// a pure function of its arguments and the time the renderer passes to render(t).
+// morph, mask and clip helpers, colour mixing, the shot and zone readers for the house style, and the
+// text registration the QA replay reads. It ships no scene, object or copy; the page draws whatever
+// its treatment calls for. Every function is a pure function of its arguments and the time the
+// renderer passes to render(t).
 (function () {
   "use strict";
 
@@ -289,6 +290,86 @@
     registered.push({ content: String(content), x, y, w, h, decor: Boolean(decor) });
   }
 
+  // ---- the house style and the shot timeline ----
+  // The renderer serves both as /lit/style.js (window.LitStyle, window.LitTimeline), written from the
+  // treatment, so the page and the gate read one timeline and one set of zones. Read lazily: the page
+  // may load style.js before or after this kit.
+  const styleData = () => {
+    if (!window.LitStyle) throw new Error("LitStage: load /lit/style.js before the style helpers");
+    return window.LitStyle;
+  };
+  const timelineData = () => {
+    if (!window.LitTimeline) throw new Error("LitStage: load /lit/style.js before the shot helpers");
+    return window.LitTimeline;
+  };
+  const tokenCache = new WeakMap();
+  // The style's motion tokens as functions: eases, durations, staggers and a spring per object class
+  // from its damping ratio and frequency.
+  function tokens() {
+    const style = styleData();
+    if (tokenCache.has(style)) return tokenCache.get(style);
+    const m = style.motion;
+    const springOf = ({ zeta, hz }) => {
+      const k = (2 * Math.PI * hz) ** 2;
+      return spring({ stiffness: k, damping: 2 * zeta * Math.sqrt(k), mass: 1 });
+    };
+    const value = Object.freeze({
+      ease: Object.freeze({ enter: bezier(...m.ease.enter), move: bezier(...m.ease.move), exit: bezier(...m.ease.exit) }),
+      dur: Object.freeze({ ...m.dur }), stagger: Object.freeze({ ...m.stagger }),
+      spring: Object.freeze(Object.fromEntries(Object.entries(m.spring).map(([k, v]) => [k, springOf(v)]))),
+      secondary: Object.freeze({ ...m.secondary }), ambient: Object.freeze({ ...m.ambient }), push: m.push
+    });
+    tokenCache.set(style, value);
+    return value;
+  }
+  // The shot at time t: index, beat, layout, local seconds and progress, plus an entrance and an exit
+  // on the style's eases (enter(delay, dur) rises 0 -> 1, exit(dur) rises 0 -> 1 at the shot's end).
+  function shot(t) {
+    const beats = timelineData().beats;
+    let i = beats.findIndex((b) => t >= b.t0 && t < b.t1);
+    if (i < 0) i = t < beats[0].t0 ? 0 : beats.length - 1;
+    const b = beats[i];
+    const length = b.t1 - b.t0;
+    const tk = tokens();
+    return {
+      index: i, beat: b, layout: b.layout, transition: b.transition, local: t - b.t0, length, p: clamp((t - b.t0) / length),
+      enter: (delay = 0, dur = tk.dur.hero) => at(t, b.t0 + delay, dur, tk.ease.enter),
+      exit: (dur = tk.dur.exit) => at(t, b.t1 - dur, dur, tk.ease.exit)
+    };
+  }
+  // A layout zone in pixels ({ x, y, w, h }) for this film's format, and placing an element in it.
+  function zone(layout, part = "type") {
+    const z = styleData().zones[layout];
+    if (!z) throw new Error(`LitStage.zone: unknown layout ${layout}`);
+    if (!z[part]) throw new Error(`LitStage.zone: the ${layout} layout has no ${part} zone`);
+    return { ...z[part] };
+  }
+  function place(el, layout, part = "type") {
+    const z = zone(layout, part);
+    Object.assign(el.style, { position: "absolute", left: `${z.x}px`, top: `${z.y}px`, width: `${z.w}px`, height: `${z.h}px`, boxSizing: "border-box" });
+    return z;
+  }
+
+  // The Blender plate (render3d: "blender"): a full-frame <img> behind the type showing the plate frame for t.
+  // The element is replaced when the frame changes, and the renderer waits for its decode before the capture.
+  // Returns update(t); call it from render(t).
+  function plate({ parent, fps = 30, count, dir = "plate" } = {}) {
+    if (!parent || !(count > 0)) throw new Error("LitStage.plate: needs { parent, count } (count: the frames in plate/plate.json)");
+    let shown = -1, el = null;
+    return (t) => {
+      const i = Math.min(count - 1, Math.max(0, Math.floor(t * fps + 1e-6)));
+      if (i === shown) return i;
+      const next = document.createElement("img");
+      next.src = `${dir}/${String(i + 1).padStart(6, "0")}.png`;
+      next.alt = "";
+      Object.assign(next.style, { position: "absolute", inset: "0", width: "100%", height: "100%", objectFit: "cover" });
+      if (el) el.replaceWith(next); else parent.prepend(next);
+      el = next;
+      shown = i;
+      return i;
+    };
+  }
+
   // ---- the stage contract ----
   let definition = null;
   function define(spec) {
@@ -301,7 +382,7 @@
   const seeded = typeof window.__litStage?.seed === "number" ? window.__litStage.seed : 1;
   window.LitStage = {
     define, get definition() { return definition ?? window.litStage ?? null; },
-    clamp, lerp, mapRange, ease, bezier, spring, kf, at, stagger, seq,
+    clamp, lerp, mapRange, ease, bezier, spring, kf, at, stagger, seq, shot, zone, place, plate, tokens,
     rand: Object.assign((seed) => rand(seed === undefined ? seeded : seed), { seed: seeded }),
     splitText, drawPath, morph, clip, mask, mix, text: Object.assign((arg, opts) => (arg instanceof Element ? text(arg, opts) : registerText(arg)), { registered }),
     get registeredText() { return registered; },

package/skills/lit-typographic-motion/engine/stills.mjs

@@ -18,7 +18,7 @@ export function stillsPlan({ beats, cuts, frameCount, fps }) {
   return { beatFrames, strips, sheet, all };
 }
 
-function tile(images, cols, tileW, tileH, gap) {
+export function tile(images, cols, tileW, tileH, gap) {
   const rows = Math.ceil(images.length / cols);
   const width = cols * tileW + (cols + 1) * gap, height = rows * tileH + (rows + 1) * gap;
   const out = Buffer.alloc(width * height * 4);