@litfamily/litgrok 1.0.26 → 1.0.28

package/.grok/skills/lit-typographic-motion/scripts/lib/sound.mjs

@@ -372,3 +372,146 @@ export function audioGate({ mp4, videoDurationSec, mode, ffmpeg, ffprobe }) {
   const detail = `${mode} track ${stats.durationSec} s, peak ${stats.peakDbfs} dBFS, quiet opening ${stats.quietOpeningSec} s${problems.length ? `; ${problems.join('; ')}` : ''}`;
   return done(status, detail, exit20, stats);
 }
+
+// ---- layered score primitives ------------------------------------------------------------
+
+// A normalized single-cycle table of additive partials (TABLE + 1 samples, wrapped).
+const TABLE = 4096;
+export { TABLE as WAVETABLE_SIZE };
+export function wavetable(harmonics) {
+  const table = new Float32Array(TABLE + 1);
+  let peak = 0;
+  for (let i = 0; i < TABLE; i += 1) {
+    let v = 0;
+    harmonics.forEach((a, k) => { if (a) v += a * Math.sin((2 * Math.PI * (k + 1) * i) / TABLE); });
+    table[i] = v;
+    peak = Math.max(peak, Math.abs(v));
+  }
+  for (let i = 0; i < TABLE; i += 1) table[i] /= peak || 1;
+  table[TABLE] = table[0];
+  return table;
+}
+
+export function samplePeakDbfs(channels) {
+  let peak = 0;
+  for (const ch of channels) for (let i = 0; i < ch.length; i += 1) {
+    const v = Math.abs(ch[i]);
+    if (v > peak) peak = v;
+  }
+  return dbfs(peak);
+}
+
+// Sounds an on-screen event can make: a tap, a hit, a whoosh and a chime.
+export const EVENT_SOUNDS = Object.freeze(['tap', 'hit', 'whoosh', 'chime']);
+
+const CUE_WORDS = Object.freeze([
+  ['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],
+]);
+
+// Accent 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 nearestTime = (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 measured against the beat boundary or cut they serve, plus one `event` cue per
+// on-screen event at its own time (an event 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)), t1 = clampT(Number(beat.t1));
+    for (const kind of cueKindsFor(beat.sound)) {
+      if (kind === 'hit') {
+        const cut = nearestTime(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 = nearestTime(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 = nearestTime(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;
+}
+
+// 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. 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.
+export function masterTo(L, R) {
+  const sampleCount = L.length;
+  const ceiling = 10 ** (-2.1 / 20);
+  const ahead = Math.round(0.005 * SAMPLE_RATE);
+  const release = 1 - Math.exp(-1 / (0.08 * SAMPLE_RATE));
+  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.
+    const need = new Float32Array(sampleCount);
+    for (let s = 0; s < sampleCount; s += 1) {
+      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, tail = 0, next = 0;
+    for (let s = 0; s < sampleCount; s += 1) {
+      for (; next < Math.min(sampleCount, s + ahead + 1); next += 1) {
+        while (tail > head && need[deque[tail - 1]] >= need[next]) tail -= 1;
+        deque[tail] = next; tail += 1;
+      }
+      while (deque[head] < s) head += 1;
+      held[s] = need[deque[head]];
+    }
+    let env = 1;
+    const smooth = new Float32Array(sampleCount);
+    for (let s = 0; s < sampleCount; s += 1) {
+      env = Math.min(held[s], env + (1 - env) * release);
+      smooth[s] = env;
+    }
+    const left = new Float32Array(sampleCount), right = 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 += 1) {
+      win += smooth[s] - (s >= ahead ? smooth[s - ahead] : 1);
+      const g = win / ahead;
+      left[s] = q(Math.max(-ceiling, Math.min(ceiling, L[s] * gain * g)));
+      right[s] = q(Math.max(-ceiling, Math.min(ceiling, R[s] * gain * g)));
+    }
+    return [left, right];
+  };
+  const raw = integratedLoudness([Float32Array.from(L), Float32Array.from(R)]);
+  let gain = Number.isFinite(raw) ? 10 ** ((TARGET_LUFS - 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 - TARGET_LUFS) > 0.2; i += 1) {
+    gain *= 10 ** ((TARGET_LUFS - lufs) / 20);
+    [left, right] = render(gain);
+    lufs = integratedLoudness([left, right]);
+  }
+  return { left, right, gain, lufs };
+}

package/.grok/skills/lit-typographic-motion/scripts/lib/soundtrack.mjs

@@ -4,6 +4,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, sep } from 'node:path';
 import { findTool } from './render.mjs';
+import { writeScore } from './score.mjs';
 import { audioGate, prepareTrack, writeBed } from './sound.mjs';
 
 export function soundFile(out, treatment) {
@@ -14,6 +15,10 @@ export function soundFile(out, treatment) {
 export function prepareSound({ out, treatment, fps, frameCount, cutTimes = [], ffmpeg, tempo = null }) {
   const mode = treatment.sound.mode;
   if (mode === 'none') return null;
+  if (mode === 'score') {
+    const score = writeScore({ treatment, frameCount, fps, cutTimes, dir: out });
+    return { mode, path: score.file, score };
+  }
   if (mode === 'generated') {
     const bed = writeBed(out, treatment, { frameCount, fps, cutTimes, tempo });
     return { mode, path: bed.wavPath, bed };
@@ -30,8 +35,12 @@ export function prepareSound({ out, treatment, fps, frameCount, cutTimes = [], f
 
 export function muxGate({ mp4, durationSec, treatment, env = process.env, track }) {
   const mode = treatment.sound.mode;
-  const gate = audioGate({ mp4, videoDurationSec: durationSec, mode, ffmpeg: findTool('ffmpeg', env), ffprobe: findTool('ffprobe', env) });
-  const bed = track?.bed;
-  const summary = { mode, label: mode === 'generated' ? 'generated sound bed' : mode === 'none' ? 'silent by request' : `${mode} track`, ...(bed ? { timbre: bed.timbre, key: bed.key, tempo: bed.tempo, lufs: bed.lufs, peakDbfs: bed.peakDbfs, method: bed.method, sha256: bed.sha256 } : {}), ...(track?.prepared ? { sourceSec: track.prepared.sourceSec, padded: track.prepared.padded, trimmed: track.prepared.trimmed } : {}) };
+  // A score is built here to the loudness target like the generated bed: a quiet opening is a
+  // failure, not a warning.
+  const built = mode === 'score' ? 'generated' : mode;
+  const gate = audioGate({ mp4, videoDurationSec: durationSec, mode: built, ffmpeg: findTool('ffmpeg', env), ffprobe: findTool('ffprobe', env) });
+  const bed = track?.bed, score = track?.score;
+  const label = mode === 'score' && score ? `score, ${score.genre} in ${score.key}, ${score.tempo} BPM` : mode === 'generated' ? 'generated sound bed' : mode === 'none' ? 'silent by request' : `${mode} track`;
+  const summary = { mode, label, ...(bed ? { timbre: bed.timbre, key: bed.key, tempo: bed.tempo, lufs: bed.lufs, peakDbfs: bed.peakDbfs, method: bed.method, sha256: bed.sha256 } : {}), ...(score ? { genre: score.genre, key: score.key, tempo: score.tempo, lufs: score.lufs, peakDbfs: score.peakDbfs, method: score.loudnessMethod, sidechainDb: score.sidechainDb, sha256: score.sha256 } : {}), ...(track?.prepared ? { sourceSec: track.prepared.sourceSec, padded: track.prepared.padded, trimmed: track.prepared.trimmed } : {}) };
   return { results: gate.results, exit20: gate.exit20, stats: { ...gate.stats, ...summary }, summary };
 }

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-gate.mjs

@@ -13,6 +13,48 @@ const pass = (id, detail = '') => ({ id, status: 'PASS', detail });
 const fail = (id, detail) => ({ id, status: 'FAIL', detail });
 const warn = (id, detail) => ({ id, status: 'WARN', detail });
 
+// An empty frame of any colour: almost every pixel within 0.02 of one luminance (0.5-99.5 %).
+// A cream or white frame with nothing on it is as empty as a black one; MO-D-03 sees only black.
+const FLAT = Object.freeze({ spread: 0.02, holdSec: 1, edgeSec: 1 });
+// A near-empty frame: fewer than 2.5 % of its 48 px cells carry anything. A run longer than 0.5 s
+// fails; the opening may build from nothing for 0.4 s more, the close may fade for 0.6 s more.
+const DEAD = Object.freeze({ busy: 0.025, holdSec: 0.5, openSec: 0.4, closeSec: 0.6 });
+
+const worstRun = (flags, { limit, allowance }) => {
+  let worst = null;
+  let start = -1;
+  for (let f = 0; f <= flags.length; f++) {
+    if (f < flags.length && flags[f]) {
+      if (start < 0) start = f;
+      continue;
+    }
+    if (start >= 0) {
+      const length = f - start;
+      if (length > limit + allowance(start === 0, f === flags.length) && (!worst || length > worst.length)) worst = { length, from: start };
+      start = -1;
+    }
+  }
+  return worst;
+};
+
+export function checkFlatFrames(frames, fps) {
+  if (!frames.length || frames.some((f) => typeof f.lumP005 !== 'number' || typeof f.lumP995 !== 'number')) return { id: 'FLAT-FRAME', status: 'N/A', detail: 'per-frame spread not recorded' };
+  const flat = frames.map((f) => f.lumP995 - f.lumP005 < FLAT.spread);
+  const worst = worstRun(flat, { limit: FLAT.holdSec * fps, allowance: (atStart, atEnd) => (atStart || atEnd ? FLAT.edgeSec * fps : 0) });
+  return worst
+    ? fail('FLAT-FRAME', `${(worst.length / fps).toFixed(2)} s of empty frames from ${(worst.from / fps).toFixed(2)} s (nothing but one flat colour; limit ${FLAT.holdSec} s)`)
+    : pass('FLAT-FRAME', `no run of empty frames longer than ${FLAT.holdSec} s`);
+}
+
+export function checkDeadAir(frames, fps) {
+  if (!frames.length || frames.some((f) => typeof f.busy !== 'number')) return { id: 'DEAD-AIR', status: 'N/A', detail: 'per-frame busy share not recorded' };
+  const dead = frames.map((f) => f.busy < DEAD.busy);
+  const worst = worstRun(dead, { limit: DEAD.holdSec * fps, allowance: (atStart, atEnd) => (atStart ? DEAD.openSec * fps : 0) + (atEnd ? DEAD.closeSec * fps : 0) });
+  return worst
+    ? fail('DEAD-AIR', `${(worst.length / fps).toFixed(2)} s of near-empty frames from ${(worst.from / fps).toFixed(2)} s (under ${DEAD.busy * 100} % of the frame carries anything; limit ${DEAD.holdSec} s)`)
+    : pass('DEAD-AIR', `no near-empty run longer than ${DEAD.holdSec} s`);
+}
+
 function exportInfo(path) {
   return existsSync(path) ? { present: true, bytes: statSync(path).size, path, name: path.split('/').pop() } : { present: false };
 }
@@ -66,6 +108,8 @@ export function evaluateStage({ manifest, frames, previewRecords, determinism, p
   const still = exportInfo(join(exportsDir, 'reduced-motion.png'));
   results.push(still.present ? pass('MO-C-14', `present Y: the final beat's midpoint frame ${stillFrame}`) : fail('MO-C-14', 'present N: reduced-motion still missing'));
   results.push(checkDarkRuns({ fps: manifest.fps, bpm: manifest.sound?.tempo ?? 100, timeline: [] }, frames));
+  results.push(checkFlatFrames(frames, manifest.fps));
+  results.push(checkDeadAir(frames, manifest.fps));
   results.push(...(sound?.results ?? [fail('SOUND', 'sound gate not run')]));
   results.push(...(qa?.results ?? []));
   results.push(manifest.round >= 1 && manifest.round <= 3 ? pass('MO-C-15/16', `round ${manifest.round} of 3`) : fail('MO-C-15/16', `round ${manifest.round} outside 1..3`));

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-qa.mjs

@@ -8,11 +8,45 @@ import { join } from 'node:path';
 import { SKILL_ROOT } from './fonts.mjs';
 import { measureContrast } from './gate.mjs';
 import { measureFrame } from './frame-pool.mjs';
+import { LAYOUTS, ZONE_TOLERANCE, readStyle, scaleStep, styleFamilies, styleTextColors } from './styles.mjs';
+
+const readStyleSafe = (id) => {
+  try {
+    return readStyle(id);
+  } catch {
+    return null;
+  }
+};
 import { openStage } from './stage-session.mjs';
 import { readingFloor } from './text.mjs';
 import { normalize } from './treatment.mjs';
 
 export const INTERNAL_TERMS = Object.freeze(['path', 'preset', 'gate', 'beat', 'treatment']);
+
+// Thresholds for the text and fill rules: visible opacity, ink pixels, overlap share of the smaller
+// box, RGB distance for "the same colour", empty regions per beat midpoint.
+export const TEXT_QA = Object.freeze({ visibleOpacity: 0.6, minInkPx: 12, overlapShare: 0.08, colourDistance: 12, emptyRegion: 0.15, emptyRegionsMax: 2 });
+
+/** [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);
+  if (hex) return [0, 2, 4].map((i) => Number.parseInt(hex[1].slice(i, i + 2), 16));
+  return null;
+}
+
+/** Classify a run against the treatment's copy: "copy" | "other" (decor is never copy here). */
+export function runClass(run, copyNorms) {
+  const n = run.norm;
+  if (!n) return 'other';
+  return copyNorms.some((line) => line.includes(n) || n.includes(line)) ? 'copy' : 'other';
+}
+
+const boxArea = (b) => Math.max(0, b[2] - b[0]) * Math.max(0, b[3] - b[1]);
+const boxOverlap = (a, b) => boxArea([Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.min(a[2], b[2]), Math.min(a[3], b[3])]);
+const unionOf = (rects) => (rects.length ? [Math.min(...rects.map((r) => r[0])), Math.min(...rects.map((r) => r[1])), Math.max(...rects.map((r) => r[2])), Math.max(...rects.map((r) => r[3]))] : null);
 const QA_SCRIPT = join(SKILL_ROOT, 'scripts', 'stage', 'qa.js');
 const LUT = Float64Array.from({ length: 256 }, (_, v) => { const s = v / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
 const pass = (id, detail = '') => ({ id, status: 'PASS', detail });
@@ -107,11 +141,17 @@ function rgb3(rgba) {
   return out;
 }
 
-export async function runStageQa({ executable, out, stageDir, width, height, fps, seed, fonts, treatment, totalFrames, log = () => {}, stepOrThrow, captureChecked, stop = { aborted: false } }) {
+export async function runStageQa({ executable, out, stageDir, width, height, fps, seed, fonts, treatment, totalFrames, log = () => {}, stepOrThrow, captureChecked, rung = 'software', stop = { aborted: false } }) {
   const plan = qaPlan(treatment.beats, fps, totalFrames);
   const allowedFonts = new Set();
   for (const route of fonts.routes.values()) for (const name of fontNames(new Uint8Array(readFileSync(route.path)))) allowedFonts.add(name);
-  const session = await openStage({ executable, outDir: out, stageDir, width, height, fps, seed, fonts, label: 'q', log });
+  let style = null;
+  if (treatment.style) {
+    const { readStyle, styleCss, styleScript } = await import('./styles.mjs');
+    const declared = readStyle(treatment.style);
+    style = { css: styleCss(declared, treatment.format), js: styleScript(declared, treatment.format, treatment) };
+  }
+  const session = await openStage({ executable, outDir: out, stageDir, width, height, fps, seed, fonts, style, label: 'q', rung, log });
   const grid = [];
   const samples = [];
   let canvasTextCalls = 0;
@@ -157,7 +197,7 @@ export async function runStageQa({ executable, out, stageDir, width, height, fps
           } catch { /* the node left the document between reads */ }
         }
       }
-      samples.push({ frame: f, beat: sample.beat, kind: sample.kind, runs: measured, texts, moved: stats.moved, nonTextStd: stats.nonTextStd, fonts: fontsUsed });
+      samples.push({ frame: f, beat: sample.beat, kind: sample.kind, runs: measured, texts, moved: stats.moved, nonTextStd: stats.nonTextStd, fonts: fontsUsed, regions: a.regions ?? null });
     }
   } finally { await session.close().catch(() => {}); }
   const fileNames = ['index.html', 'treatment.json', 'stage-kit.js', 'fonts.css', 'gate-report.txt'];
@@ -166,6 +206,92 @@ export async function runStageQa({ executable, out, stageDir, width, height, fps
 
 function wordHit(text, term) { return new RegExp(`(?<![\\p{L}\\p{N}])${term}(?![\\p{L}\\p{N}])`, 'iu').test(text); }
 
+/**
+ * The text rules on the collected samples: text over text (any visible runs), and — when the
+ * treatment declares a house style — the style's colours, faces and type scale for copy, plus the
+ * shot's type zone for settled copy runs on beats that name a layout. Pure, so tests drive it.
+ */
+export function judgeTextRules({ treatment, width, height, samples, settled, copyNorms }) {
+  const format = width >= height ? '16:9' : '9:16';
+  const style = treatment.style ? readStyleSafe(treatment.style) : null;
+  const colours = style ? styleTextColors(style).map(parseCssColour) : [];
+  const families = style ? styleFamilies(style) : new Set();
+  const overlaps = [];
+  const offColour = [];
+  const offFace = [];
+  const offScale = [];
+  const offScaleOther = [];
+  const offZone = [];
+  const tolX = width * ZONE_TOLERANCE;
+  const tolY = height * ZONE_TOLERANCE;
+  for (const s of samples) {
+    const visible = s.runs
+      .map((run) => ({ run, box: unionOf(run.rects) }))
+      .filter(({ run, box }) => box && !run.decor && run.opacity >= TEXT_QA.visibleOpacity && run.ink >= TEXT_QA.minInkPx);
+    for (let i = 0; i < visible.length; i++) {
+      for (let j = i + 1; j < visible.length; j++) {
+        const a = visible[i];
+        const b = visible[j];
+        const shared = boxOverlap(a.box, b.box);
+        if (shared > TEXT_QA.overlapShare * Math.min(boxArea(a.box), boxArea(b.box))) overlaps.push(`"${a.run.text.slice(0, 24)}" × "${b.run.text.slice(0, 24)}"@${s.frame}`);
+      }
+    }
+    const beat = treatment.beats[s.beat];
+    const layout = beat?.layout ? LAYOUTS[format][beat.layout] : null;
+    for (const { run, box } of visible) {
+      if (!settled(s, run)) continue;
+      const copy = !run.decor && runClass(run, copyNorms) === 'copy';
+      const where = `"${run.text.slice(0, 32)}"@${s.frame}`;
+      if (copy && style) {
+        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]) <= TEXT_QA.colourDistance)) offColour.push(`${where} ${run.color}`);
+        if (run.family && ![...families].some((f) => run.family === f || run.family.startsWith(`${f} `))) offFace.push(`${where} ${run.family}`);
+      }
+      if (style) {
+        const fontPx = run.fontSizePx * (run.scale ?? 1);
+        if (!scaleStep(style, format, fontPx)) (copy ? offScale : offScaleOther).push(`${where} ${Math.round(fontPx)}px`);
+      }
+      if (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 (box[0] < zx - tolX || box[1] < zy - tolY || box[2] > zx + zw + tolX || box[3] > zy + zh + tolY) offZone.push(`${where} outside the ${beat.layout} type zone`);
+        }
+      }
+    }
+  }
+  const rules = [];
+  rules.push(overlaps.length ? fail('TEXT-OVERLAP', `text over text: ${overlaps.slice(0, 4).join(', ')}`) : pass('TEXT-OVERLAP', 'no two visible text runs overlap'));
+  if (style) {
+    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(', ')}): ${offColour.slice(0, 3).join(', ')}` : null,
+      offFace.length ? `face outside the style (${[...families].join(', ')}): ${offFace.slice(0, 3).join(', ')}` : null,
+      offScale.length ? `size off the type scale (${steps} px, ±4 %): ${offScale.slice(0, 3).join(', ')}` : null,
+    ].filter(Boolean);
+    rules.push(styleFails.length ? fail('TEXT-ON-STYLE', styleFails.join('; '))
+      : offScaleOther.length ? warn('TEXT-ON-STYLE', `copy is on the ${style.id} style; other text off the scale: ${offScaleOther.slice(0, 3).join(', ')}`)
+        : pass('TEXT-ON-STYLE', `copy uses the ${style.id} colours, faces and type scale`));
+  }
+  const zoned = samples.some((s) => treatment.beats[s.beat]?.layout);
+  if (zoned) rules.push(offZone.length ? fail('TEXT-ZONE', offZone.slice(0, 4).join(', ')) : pass('TEXT-ZONE', "every settled copy run sits in its shot's type zone"));
+  return rules;
+}
+
+// A rich film fills its frame the way a dense reference does: at each beat midpoint at most two of
+// the 12 regions may sit empty (busy share under 0.15). The end card may breathe, so one beat may miss.
+export function richFill({ treatment, samples }) {
+  if (treatment.register === 'minimal') return { id: 'RICH-FILL', status: 'N/A', detail: 'minimal register: negative space is the point' };
+  const mids = samples.filter((s) => s.kind === 'mid' && Array.isArray(s.regions));
+  if (!mids.length) return { id: 'RICH-FILL', status: 'N/A', detail: 'region fill not measured' };
+  const thin = mids
+    .map((s) => ({ beat: s.beat, empty: s.regions.filter((v) => v < TEXT_QA.emptyRegion).length }))
+    .filter((x) => x.empty > TEXT_QA.emptyRegionsMax);
+  if (thin.length <= 1) return { id: 'RICH-FILL', status: 'PASS', detail: `${mids.length - thin.length} of ${mids.length} beat midpoints fill the frame (at most ${TEXT_QA.emptyRegionsMax} of 12 regions empty)` };
+  return { id: 'RICH-FILL', status: 'FAIL', detail: `${thin.length} of ${mids.length} beat midpoints leave the frame empty: ${thin.map((x) => `beat ${x.beat + 1} has ${x.empty} of 12 regions empty`).join(', ')}` };
+}
+
 export function evaluateQa({ grid, samples, plan, treatment, width, height, fps, canvasTextCalls = 0, allowedFonts = new Set(), fileNames = [] }) {
   const copy = treatment.copy.lines.map(normalize).filter(Boolean);
   const isCopyText = (norm) => copy.some((line) => norm.includes(line) || line.includes(norm));
@@ -262,6 +388,9 @@ export function evaluateQa({ grid, samples, plan, treatment, width, height, fps,
   results.push(decorCopy || decorShare ? fail('QA-DECOR', decorCopy ?? decorShare) : pass('QA-DECOR', 'decor text carries no copy and stays under 25 % of the text area'));
   results.push(meta ? warn('QA-META', `a meta label may be on screen: ${meta}; the look must answer it`) : pass('QA-META', 'no request text, idea, file name or internal term on screen'));
   results.push(fontIssue ? (fontIssue.copy ? fail('QA-FONTS', `${fontIssue.text}; set copy in a product face`) : warn('QA-FONTS', fontIssue.text)) : pass('QA-FONTS', 'only product faces at beat midpoints'));
+  results.push(...judgeTextRules({ treatment, width, height, samples, settled, copyNorms: copy, families: null }));
+  const rich = richFill({ treatment, samples });
+  results.push(rich);
   const registered = grid.some((g) => g.texts.length);
   results.push(canvasTextCalls > 0 && !registered ? warn('QA-CANVAS', 'canvas text not measured: the page draws text on a canvas without LitStage.text registrations; the look must answer it') : pass('QA-CANVAS', registered ? 'canvas text registered' : 'no canvas text'));
   const drawn = presence.filter(Boolean).length;

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-session.mjs

@@ -1,7 +1,7 @@
 // One stage Chrome: the page is served from the synthetic origin http://lit.stage/ through CDP
 // Fetch interception (no listening socket), the host script virtualizes time before any page
 // script, and the renderer drives frames with step() + capture() (brief sections 6c-6e).
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { extname, join, sep } from 'node:path';
 import { STAGE } from './constants.mjs';
@@ -18,6 +18,37 @@ export const EPOCH_MS = Date.UTC(2026, 0, 1);
 export const KIT_PATH = join(SKILL_ROOT, 'scripts', 'stage', 'stage-kit.js');
 const HOST_PATH = join(SKILL_ROOT, 'scripts', 'stage', 'host.js');
 
+// The pinned three.js build and its two addons (scripts/lib/vendor/three, MIT), served at /lit/three/
+// for 3D films and 3D heroes; never a CDN. Any other path under /lit/three/ is a missing file.
+// The hashes below are the bytes of upstream three@0.170.0
+// (registry.npmjs.org/three/-/three-0.170.0.tgz: build/three.module.js and the two examples/jsm
+// files), checked byte for byte: a swapped vendored file and a regenerated notice cannot pass
+// together, because the pin lives in code and is rechecked every time a file is served.
+export const THREE_DIR = join(SKILL_ROOT, 'scripts', 'lib', 'vendor', 'three');
+export const THREE_HASHES = Object.freeze({
+  'three.module.js': 'ce1fa418de16a19495a9f72495580e3015d7745c296d3ce0485897f902ddedfb',
+  'addons/environments/RoomEnvironment.js': '85869bdd22f7cf0b22e68dcefe6cb710480af0f5c901a76f7a7764fd07fc8014',
+  'addons/geometries/RoundedBoxGeometry.js': 'd20aeaf7077c459a8d952d215738d7b44fba028440bb862d84b622a34f0c80bb',
+});
+
+/** Resolve a /lit/three/... path against the vendored build: { file, type }, { missing } or { refused }. */
+export function resolveThree(pathname) {
+  let decoded;
+  try { decoded = decodeURIComponent(pathname); } catch { return { refused: `undecodable path ${pathname}` }; }
+  const rel = decoded.slice('/lit/three/'.length);
+  if (rel.split('/').includes('..') || rel.includes('\\')) return { refused: `path traversal ${pathname}` };
+  if (!rel.endsWith('.js')) return { missing: rel };
+  const file = join(THREE_DIR, rel);
+  if (!existsSync(file)) return { missing: rel };
+  try {
+    const hash = createHash('sha256').update(readFileSync(file)).digest('hex');
+    if (THREE_HASHES[rel] !== hash) return { refused: `changed vendored file ${rel}` };
+  } catch {
+    return { refused: `unreadable vendored file ${rel}` };
+  }
+  return { file, type: CONTENT_TYPES['.js'] };
+}
+
 export function hostScript({ seed, fps }) {
   return readFileSync(HOST_PATH, 'utf8').replace('const CFG = __LIT_CFG__;', `const CFG = ${JSON.stringify({ seed: seed >>> 0, fps, epochMs: EPOCH_MS })};`);
 }
@@ -41,9 +72,9 @@ export function resolveStagePath(stageDir, pathname) {
   return { file: real, type };
 }
 
-export async function openStage({ executable, outDir, stageDir, width, height, fps, seed, fonts, label = 'm', log = () => {} }) {
+export async function openStage({ executable, outDir, stageDir, width, height, fps, seed, fonts, style = null, label = 'm', rung = 'software', log = () => {} }) {
   const profileDir = join(outDir, '.run', `s${label}-${randomBytes(3).toString('hex')}`);
-  const browser = await launchStage({ executable, profileDir, width, height });
+  const browser = await launchStage({ executable, profileDir, width, height, rung });
   const network = [];
   const refused = [];
   const served = new Set();
@@ -64,7 +95,23 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
       return;
     }
     if (url.pathname === '/lit/stage-kit.js') { served.add('/lit/stage-kit.js'); await respond(requestId, 200, kit, CONTENT_TYPES['.js']); return; }
+    if (url.pathname.startsWith('/lit/three/')) {
+      const resolved = resolveThree(url.pathname);
+      if (resolved.refused) { refused.push(resolved.refused); await respond(requestId, 403, 'refused'); return; }
+      if (resolved.missing) { await respond(requestId, 404, 'not a vendored three.js file'); return; }
+      served.add(url.pathname);
+      await respond(requestId, 200, readFileSync(resolved.file), resolved.type);
+      return;
+    }
     if (url.pathname === '/lit/fonts.css') { served.add('/lit/fonts.css'); await respond(requestId, 200, fonts.css, CONTENT_TYPES['.css']); return; }
+    if (url.pathname === '/lit/style.css') {
+      if (style) { served.add('/lit/style.css'); await respond(requestId, 200, style.css, CONTENT_TYPES['.css']); } else await respond(requestId, 404, 'no style bound');
+      return;
+    }
+    if (url.pathname === '/lit/style.js') {
+      if (style) { served.add('/lit/style.js'); await respond(requestId, 200, style.js, CONTENT_TYPES['.js']); } else await respond(requestId, 404, 'no style bound');
+      return;
+    }
     if (url.pathname.startsWith('/lit/fonts/')) {
       const route = fonts.routes.get(url.pathname);
       if (route) { served.add(url.pathname); await respond(requestId, 200, readFileSync(route.path), route.type); } else await respond(requestId, 404, 'no such face');
@@ -95,6 +142,7 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
 
   return {
     network, refused, served, args: browser.args, send, evaluate,
+    rung: browser.rung, renderer: browser.renderer, notice: browser.notice,
     async load() {
       const loaded = new Promise((resolve) => browser.on((message) => { if (message.method === 'Page.loadEventFired' && message.sessionId === browser.sessionId) resolve(); }));
       await send('Page.navigate', { url: `${STAGE.origin}/index.html` });