@litfamily/lithermes 1.0.28 → 1.0.30

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

@@ -0,0 +1,154 @@
+// The offline Blender rung (references/depth.md): the runner (engine/blender/runner.py, in
+// Blender's own Python, no venv) renders the film's scene.py with Cycles on the GPU when it has
+// one, else the CPU, and writes receipt.json. Call it `motion.mjs blender --out <dir>` for one
+// still at every beat midpoint, `--final` for the plate sequence: preview first, compare with any
+// reference frames the user gave and with what the GPU rung built, then render the final plate.
+// The stage shows the plate under its type and treats a 3-D-of-any-kind page the same with or
+// without one. The run is sequenced (not parallel), and the same scene.py, receipt and frames
+// render exactly the same plate again: same seed, same Blender, same bytes.
+import { execSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, join, basename, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXIT } from './constants.mjs';
+import { FORMATS, loadTreatment } from './treatment.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fail = (code, message, extra = {}) => Object.assign(new Error(message), { exitCode: code, ...extra });
+
+export const BLENDER = Object.freeze({
+  // Preview: fast enough to compare against the GPU rung (CPU 32 spp renders a 100 % frame in
+  // seconds). Final: within 2 dB of a 1024-spp reference, seams included. Quality bands calibrated
+  // 2026-10-24 on this machine (Apple M3 Max): preview landed at 1.1 s median d, stills look right.
+  preview: Object.freeze({ percent: 50, samples: 32 }),
+  final: Object.freeze({ percent: 100, samples: 128 }),
+  runner: join(here, 'blender', 'runner.py'),
+  macApp: '/Applications/Blender.app/Contents/MacOS/Blender',
+  device: 'METAL',
+  plateFps: 30,
+});
+
+// Where Blender lives: a LITHERMES_BLENDER override first (pinned and never second-guessed), then
+// the macOS app, then `blender` on PATH. Returns { path, source } or null.
+export function findBlender({ env = process.env, exists = existsSync, platform = process.platform } = {}) {
+  if (env.LITHERMES_BLENDER) return exists(env.LITHERMES_BLENDER) ? { path: env.LITHERMES_BLENDER, source: 'LITHERMES_BLENDER' } : null;
+  if (platform === 'darwin' && exists(BLENDER.macApp)) return { path: BLENDER.macApp, source: 'app' };
+  for (const dir of String(env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    const file = join(dir, 'blender');
+    if (exists(file)) return { path: file, source: 'PATH' };
+  }
+  return null;
+}
+
+const plateFrames = (treatment) => Math.round(treatment.durationSec * BLENDER.plateFps);
+
+export function blenderArgs({ treatment, scene, out, quality }) {
+  const q = BLENDER[quality];
+  if (!q) throw new Error(`blenderArgs: quality is preview or final (got ${quality})`);
+  const [width, height] = FORMATS[treatment.format];
+  const seed = Number.isInteger(treatment.seed)
+    ? treatment.seed >>> 0
+    : parseInt(createHash('sha256').update(String(treatment.request)).digest('hex').slice(0, 8), 16) >>> 0;
+  const args = ['-b', '--factory-startup', '-P', BLENDER.runner, '--',
+    '--scene', scene, '--out', out, '--width', String(width), '--height', String(height),
+    '--percent', String(q.percent), '--samples', String(q.samples), '--device', BLENDER.device,
+    '--fps', String(BLENDER.plateFps), '--seed', String(seed % 2147483648)];
+  if (quality === 'preview') args.push('--stills', treatment.beats.map((b) => +((b.t0 + b.t1) / 2).toFixed(3)).join(','));
+  else args.push('--frames', `1-${plateFrames(treatment)}`);
+  return args;
+}
+
+const FALLBACK = (out) => [
+  'FALLBACK: no Blender found (LITHERMES_BLENDER, /Applications/Blender.app, blender on PATH), so nothing was rendered.',
+  `Set render3d to "three" in ${join(out, 'treatment.json')} and build the world in three.js on the GPU rung (references/depth.md),`,
+  'and say in the reply that the film used the GPU rung because Blender is not installed.',
+].join('\n');
+
+const listPngs = (dir) => (existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith('.png')).sort() : []);
+
+function runBlender({ bin, args, dir, expected, progress }) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '';
+    const keep = (chunk) => {
+      tail = (tail + chunk).slice(-4000);
+    };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = progress ? setInterval(() => progress(listPngs(dir).length, expected), 2000) : null;
+    child.on('close', (code) => {
+      if (timer) clearInterval(timer);
+      resolve({ code, tail });
+    });
+    child.on('error', (error) => {
+      if (timer) clearInterval(timer);
+      resolve({ code: -1, tail: error.message });
+    });
+  });
+}
+
+// `motion.mjs blender --out <dir> [--final]`. Preview: stills in stage/plate-preview/. Final: the
+// plate sequence in stage/plate/ plus plate.json naming every frame with its size, carrying the
+// device, samples and Blender version from the runner's receipt.
+export async function blenderCommand({ out, final = false, env = process.env, log = () => {}, progress = null }) {
+  const { treatment } = loadTreatment(out, EXIT.BLOCKED_TREATMENT_INVALID);
+  if (treatment.path !== 'stage') throw fail(EXIT.BLOCKED_TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID: field path: blender renders the stage path (this treatment takes the ${treatment.path} path)`);
+  if (treatment.render3d !== 'blender') throw fail(2, `blender renders a treatment with render3d "blender" (this one is ${treatment.render3d ?? 'three'})`);
+  const stageDir = join(out, 'stage');
+  const scene = join(stageDir, 'scene.py');
+  if (!existsSync(scene)) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${scene} is missing; write the Blender scene first (references/depth.md, the Blender rung)`);
+  const found = findBlender({ env });
+  if (!found) return { code: EXIT.OK, message: FALLBACK(out) };
+  const quality = final ? 'final' : 'preview';
+  const dir = join(stageDir, final ? 'plate' : 'plate-preview');
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const args = blenderArgs({ treatment, scene, out: dir, quality });
+  const expected = final ? plateFrames(treatment) : treatment.beats.length;
+  log(`blender ${quality}: ${found.path} (${found.source}), ${expected} ${final ? 'frames' : 'stills'}`);
+  const run = await runBlender({ bin: found.path, args, dir, expected, progress });
+  const receiptFile = join(dir, 'receipt.json');
+  if (run.code !== 0 || !existsSync(receiptFile)) {
+    throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: Blender ${quality} failed (exit ${run.code}); fix stage/scene.py and run it again. Last output: ${run.tail.trim().split('\n').slice(-8).join(' | ')}`);
+  }
+  const receipt = JSON.parse(readFileSync(receiptFile, 'utf8'));
+  const frames = receipt.files.map((name) => ({ name, bytes: statSync(join(dir, name)).size }));
+  if (frames.length !== expected) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: Blender wrote ${frames.length} of ${expected} ${final ? 'frames' : 'stills'}`);
+  const plate = { kind: quality, blender: receipt.blender, engine: receipt.engine, device: receipt.device, samples: receipt.samples, percent: receipt.percent, fps: BLENDER.plateFps, frames };
+  writeFileSync(join(dir, 'plate.json'), `${JSON.stringify(plate, null, 1)}\n`);
+  const label = `Blender ${receipt.blender}, ${receipt.engine} ${receipt.device}, ${receipt.samples} spp at ${receipt.percent} %`;
+  if (!final) {
+    return { code: EXIT.OK, message: `BLENDER preview: ${frames.length} stills at the beat midpoints in ${dir} (${label}). Open them, compare them with any reference frames the user gave, fix scene.py, then render the plate: blender --out ${out} --final` };
+  }
+  return { code: EXIT.OK, message: `BLENDER plate: ${frames.length} frames at ${BLENDER.plateFps} fps in ${dir} (${label}). Show it with LitStage.plate() under the type, then render the stage: stage --out ${out} --round N` };
+}
+
+// The plate a stage dir carries: { dir, frames, device, ... } when plate.json lists frames all present as listed, else null.
+export function readPlate(stageDir, sub = 'plate') {
+  const file = 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 ok = plate.frames.every((f) => {
+    const p = join(stageDir, sub, String(f.name));
+    return basename(String(f.name)) === f.name && existsSync(p) && statSync(p).size === f.bytes;
+  });
+  return ok ? { ...plate, dir: sub } : null;
+}
+
+// Blender's own version for the plate receipt (null when Blender is not installed here).
+export function blenderVersion({ env = process.env } = {}) {
+  const found = findBlender({ env });
+  if (!found) return null;
+  try {
+    return execSync(`"${found.path}" --version`, { encoding: 'utf8' }).split('\n')[0].trim() || null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,132 @@
+// The storyboard: `stills/board.png`, one page a person reads before the full render. One
+// keyframe per shot (the beat still) with number, time, layout and hand-off under it and its
+// hero move in words, the shot's type zone outlined on the frame; a header with the house style
+// (name, palette and type) plus format, length and sound; a footer with the layout check. It is
+// drawn as a page in the same headless Chrome the stage uses, so its type is the product's faces.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { LAYOUTS, readStyle } from './styles.mjs';
+import { ORIGIN, openStage } from './stage.mjs';
+
+export const BOARD = Object.freeze({ width: 1920, height: 1080, margin: 48, gap: 20, header: 150, footer: 56, caption: 104 });
+
+const esc = (text) => String(text ?? '').replace(/[&<>"]/gu, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[char]);
+const secs = (value) => `${Number(value).toFixed(1)}`;
+
+/** Tile geometry: columns and thumbnail size for n shots of a width x height film. */
+export function boardGrid(n, width, height) {
+  const usableW = BOARD.width - 2 * BOARD.margin;
+  const usableH = BOARD.height - BOARD.header - BOARD.footer - BOARD.margin;
+  const aspect = width / height;
+  const options = [];
+  for (let cols = 1; cols <= Math.max(1, n); cols++) {
+    const rows = Math.ceil(n / cols);
+    const tw = Math.floor((usableW - (cols - 1) * BOARD.gap) / cols);
+    const th = Math.min(Math.round(tw / aspect), Math.floor((usableH - (rows - 1) * BOARD.gap) / rows) - BOARD.caption);
+    if (th <= 0) continue;
+    options.push({ cols, rows, tw: Math.round(th * aspect), th, empty: rows * cols - n });
+  }
+  // The largest tiles win, unless a grid with fewer empty slots keeps 85 % of their area.
+  const largest = Math.max(...options.map((option) => option.tw * option.th));
+  return options.filter((option) => option.tw * option.th >= 0.85 * largest).sort((a, b) => a.empty - b.empty || b.tw * b.th - a.tw * a.th)[0];
+}
+
+/** The board page HTML for a treatment and its beat stills (names relative to the page). */
+export function boardHtml({ treatment, stills, check = null }) {
+  const style = treatment.style ? readStyle(treatment.style) : null;
+  const [width, height] = treatment.format === '9:16' ? [1080, 1920] : [1920, 1080];
+  const grid = boardGrid(stills.length, width, height);
+  const zones = LAYOUTS[treatment.format === '9:16' ? '9:16' : '16:9'];
+  const palette = style?.palette ?? {};
+  const chips = Object.entries(palette).filter(([key]) => ['ground', 'ink', 'muted', 'signal', 'accent'].includes(key))
+    .map(([key, value]) => `<span class="chip"><i style="background:${esc(value)}"></i>${esc(key)} ${esc(value)}</span>`).join('');
+  const tiles = stills.map((file, index) => {
+    const beat = treatment.beats[index] ?? {};
+    const zone = beat.layout && zones[beat.layout]?.type;
+    const guide = zone ? `<b class="zone" style="left:${(zone[0] * 100).toFixed(2)}%;top:${(zone[1] * 100).toFixed(2)}%;width:${(zone[2] * 100).toFixed(2)}%;height:${(zone[3] * 100).toFixed(2)}%"></b>` : '';
+    const meta = [String(index + 1).padStart(2, '0'), `${secs(beat.t0)}–${secs(beat.t1)} s`, beat.layout, beat.transition && beat.transition !== 'end' ? `→ ${beat.transition}` : beat.transition].filter(Boolean).map(esc).join('  ·  ');
+    return `<figure style="width:${grid.tw}px"><div class="frame" style="width:${grid.tw}px;height:${grid.th}px"><img src="${esc(file)}">${guide}</div>`
+      + `<figcaption><span class="meta">${meta}</span><span class="hero">${esc(beat.hero ?? beat.onScreen ?? '')}</span></figcaption></figure>`;
+  }).join('');
+  const failed = (check?.rules ?? []).filter((rule) => rule.status === 'FAIL');
+  const verdict = !check ? 'layout check: not run on this render'
+    : failed.length ? `layout check: FAIL — ${failed.map((rule) => rule.id).join(', ')}` : 'layout check: PASS';
+  const sound = treatment.sound?.mode === 'score' && treatment.style
+    ? `score (${readStyle(treatment.style).score.genre})` : treatment.sound?.mode ?? 'none';
+  const ground = palette.ground ?? '#101216';
+  return `<!doctype html>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<style>
+  html, body { margin: 0; width: ${BOARD.width}px; height: ${BOARD.height}px; overflow: hidden; background: #15171b; color: #e8e9e6; font-family: "Pretendard"; }
+  header { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; top: 36px; height: ${BOARD.header - 48}px; display: flex; justify-content: space-between; align-items: flex-start; }
+  h1 { margin: 0; font: 700 40px/1.1 "Pretendard"; }
+  .sub { margin-top: 10px; font: 400 20px/1.3 "MesloLGS NF"; color: #a8aba6; }
+  .style { text-align: right; }
+  .specimen { display: inline-block; padding: 6px 14px; margin-bottom: 10px; background: ${esc(ground)}; color: ${esc(palette.ink ?? '#fff')}; font: ${style?.faces.display.weight ?? 700} 34px/1.1 "${esc(style?.faces.display.family ?? 'Pretendard')}", "Pretendard"; }
+  .chips { display: flex; gap: 14px; justify-content: flex-end; font: 400 16px/1 "MesloLGS NF"; color: #a8aba6; }
+  .chip i { display: inline-block; width: 16px; height: 16px; margin-right: 6px; vertical-align: -3px; border: 1px solid #555; }
+  main { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; top: ${BOARD.header}px; display: flex; flex-wrap: wrap; gap: ${BOARD.gap}px; }
+  figure { margin: 0; }
+  .frame { position: relative; overflow: hidden; background: #000; }
+  .frame img { display: block; width: 100%; height: 100%; }
+  .zone { position: absolute; box-sizing: border-box; border: 2px dashed rgba(255, 196, 0, 0.75); }
+  figcaption { display: block; height: ${BOARD.caption - 8}px; padding-top: 8px; overflow: hidden; }
+  .meta { display: block; font: 400 16px/1.3 "MesloLGS NF"; color: #c9cbc6; }
+  .hero { display: block; margin-top: 4px; font: 400 18px/1.35 "Pretendard"; color: #e8e9e6; }
+  footer { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; bottom: 18px; font: 400 18px/1.2 "MesloLGS NF"; color: ${failed.length ? '#ff8a7a' : '#9fd3a4'}; }
+</style>
+<body>
+<header>
+  <div><h1>Storyboard · ${esc(treatment.subject?.name ?? '')}</h1>
+  <div class="sub">${esc(treatment.format)} · ${esc(treatment.durationSec)} s · ${treatment.beats.length} shots · ${esc(treatment.path)} path · sound: ${esc(sound)}</div></div>
+  <div class="style"><div class="specimen">${esc(style?.name ?? treatment.style ?? '')} Aa 가</div><div class="chips">${chips}</div></div>
+</header>
+<main>${tiles}</main>
+<footer>${esc(verdict)} · dashed box: the shot's type zone</footer>
+<script>window.__litBoard = true;</script>
+</body>
+`;
+}
+
+/**
+ * Render `<out>/stills/board.png` from the beat stills already written. Returns the file path.
+ * `open({ stageDir, width, height })` opens the stage renderer on a directory; `check` is the
+ * layout check ({ rules }) drawn with its verdict onto the board.
+ */
+export async function writeBoard({ out, treatment, beatFiles, check = null, open }) {
+  const dir = path.join(out, '.run', 'board');
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const names = beatFiles.map((file, index) => {
+    const name = `s${String(index + 1).padStart(2, '0')}.png`;
+    copyFileSync(file, path.join(dir, name));
+    return name;
+  });
+  writeFileSync(path.join(dir, 'index.html'), boardHtml({ treatment, stills: names, check }));
+  const browser = await open({ stageDir: dir, width: BOARD.width, height: BOARD.height });
+  try {
+    await browser.page.goto(`${ORIGIN}/index.html`, { waitUntil: 'load', timeout: 120000 });
+    await browser.page.waitForTimeout(900);
+    const png = await browser.capture();
+    const file = path.join(out, 'stills', 'board.png');
+    writeFileSync(file, png);
+    return file;
+  } finally {
+    await browser.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Add a file the renderer wrote after the stills set to `stills/stills.json`; returns the new set SHA-256. */
+export function addToStills(out, entry, { sha256 }) {
+  const indexFile = path.join(out, 'stills', 'stills.json');
+  const index = JSON.parse(readFileSync(indexFile, 'utf8'));
+  const file = path.join(out, entry.file);
+  if (!existsSync(file)) throw new Error(`addToStills: ${entry.file} was not written`);
+  const bytes = readFileSync(file);
+  index.files = [...index.files.filter((f) => f.file !== entry.file), { ...entry, sha256: sha256(bytes) }];
+  const out2 = Buffer.from(`${JSON.stringify(index, null, 2)}\n`);
+  writeFileSync(indexFile, out2);
+  return sha256(out2);
+}

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

@@ -10,14 +10,57 @@ import { join } from 'node:path';
 
 const ARTIFACTS = ['film.mp4', 'poster.png', 'reduced-motion.png'];
 const previewName = (dir) => ['preview.webp', 'preview.gif'].find((name) => existsSync(join(dir, name)));
-const no = (reason) => ({ done: false, reason });
+const no = (reason) => ({ done: false, reason, downgraded: [] });
+
+// Beats covered by the subject devices (the count the downgrade rule compares).
+const subjectBeats = (t) => new Set((t?.visualDevices ?? []).filter((d) => d?.role === 'subject').flatMap((d) => d?.beats ?? [])).size;
+
+// Downgrades from the first valid treatment to the final one. Recorded on the
+// result, never a reason to un-count the render.
+export function downgrades(first, final) {
+  if (!first || !final) return [];
+  const items = [];
+  if (final.durationSec < first.durationSec * 0.8) items.push(`the film was shortened from ${first.durationSec} s to ${final.durationSec} s`);
+  if (subjectBeats(final) < subjectBeats(first)) items.push(`the subject is on screen in fewer beats (${subjectBeats(first)} -> ${subjectBeats(final)})`);
+  if (final.sound?.mode === 'none' && first.sound?.mode !== 'none') items.push('the sound was switched to none');
+  if (first.path === 'stage' && final.path === 'type') items.push('the path moved from stage to type');
+  return items;
+}
+
+function downgraded(out) {
+  try {
+    const first = JSON.parse(readFileSync(join(out, '.run', 'treatment-first.json'), 'utf8'));
+    const final = JSON.parse(readFileSync(join(out, 'treatment.json'), 'utf8'));
+    return downgrades(first, final);
+  } catch { return []; }
+}
+
+const withDowngrades = (out, result) => {
+  const down = downgraded(out);
+  return { ...result, downgraded: down, reason: down.length ? `${result.reason}; downgraded: ${down.join('; ')}` : result.reason };
+};
 
 export function checkCompletion(out) {
   const statePath = join(out, 'run-state.json');
   if (!existsSync(statePath)) return no('no run-state.json: the render command never finished');
   const state = JSON.parse(readFileSync(statePath, 'utf8'));
   if (state.exitCode === null || state.exitCode === undefined || !state.finished) return no('the render command started but did not finish');
-  if (state.mode === 'stills-only' || state.mode === 'stills' || state.mode === 'sheet') return no('a stills-only look pass is not a delivered film');
+  if (state.mode === 'stills-only' || state.mode === 'stills' || state.mode === 'sheet') {
+    // A film whose treatment asks for a preview is done at its board: a
+    // stills-only render whose layout check passed, looked at, storyboard included.
+    if (state.exitCode === 0) {
+      try {
+        const treatment = JSON.parse(readFileSync(join(out, 'treatment.json'), 'utf8'));
+        if (treatment?.preview === true) {
+          const check = JSON.parse(readFileSync(join(out, 'stills', 'check.json'), 'utf8'));
+          const failed = (check.rules || []).filter((rule) => rule.status === 'FAIL');
+          if (!failed.length && existsSync(join(out, 'stills', 'board.png'))) return withDowngrades(out, { done: true, reason: 'preview film: board check passed' });
+          return no(`the preview board check did not pass (${failed.map((rule) => rule.id).join(', ') || 'no board'}); fix the page and render --stills-only again`);
+        }
+      } catch { /* fall through to the stills-only rule */ }
+    }
+    return no('a stills-only look pass is not a delivered film');
+  }
   if ([10, 11, 12, 14, 15].includes(state.exitCode)) return no(`BLOCKED exit ${state.exitCode}: fix the named prerequisite and rerun`);
   if (state.exitCode !== 0 && state.exitCode !== 13) return no(`the command exited ${state.exitCode}`);
   const manifestPath = join(out, 'manifest.json'), reportPath = join(out, 'gate-report.txt');
@@ -37,16 +80,16 @@ export function checkCompletion(out) {
   const withheld = ARTIFACTS.every((name) => existsSync(join(withheldDir, name))) && previewName(withheldDir);
   if (state.exitCode === 0) {
     if (!/QA gate: PASS/.test(report)) return no('exit 0 without a passing gate report');
-    return delivered ? { done: true, reason: 'gate passed; four artifacts delivered' } : no('gate passed but an artifact is missing from its deliverable name');
+    return delivered ? withDowngrades(out, { done: true, reason: 'gate passed; four artifacts delivered' }) : no('gate passed but an artifact is missing from its deliverable name');
   }
   if ((state.round ?? manifest.lithermes?.round ?? 1) < 3) return no(`gate failed in round ${state.round}; fix the named rules and rerun with --round ${(state.round || 1) + 1}`);
   if (flash) {
     if (delivered || ['film.mp4', 'poster.png', 'preview.webp', 'preview.gif'].some((name) => existsSync(join(out, name)))) return no('a flash-failing export sits at a deliverable name');
     if (!withheld) return no('flash failure without the exports in withheld/');
     if (!/WITHHELD/.test(report)) return no('the report does not say the render is withheld');
-    return { done: true, reason: 'round 3 flash failure: exports withheld pending a fix' };
+    return withDowngrades(out, { done: true, reason: 'round 3 flash failure: exports withheld pending a fix' });
   }
   if (!delivered) return no('round 3 failure but the artifacts are not at their deliverable names');
   if (!failed.length || !failed.every((id) => report.includes(id))) return no('the report does not name the failed rules');
-  return { done: true, reason: `round 3 ended with ${failed.join(', ')} failing; artifacts delivered with the report` };
+  return withDowngrades(out, { done: true, reason: `round 3 ended with ${failed.join(', ')} failing; artifacts delivered with the report` });
 }

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

@@ -429,6 +429,19 @@ const LABELS = {
 const MAIN_ORDER = ['MO-C-01', 'MO-C-02', 'MO-C-03', 'MO-C-04', 'MO-C-05', 'MO-C-06', 'MO-C-07/08', 'MO-C-09', 'MO-C-10/11/12', 'MO-C-13', 'MO-C-14',
   'MO-C-25', 'MO-C-26', 'MO-C-27', 'MO-C-29', 'MO-D-02', 'MO-D-03', 'MO-D-04'];
 
+export const GATE_IDS = Object.freeze([...MAIN_ORDER]);
+
+// Older notes name six text rules with no runtime of their own. Each names a
+// real check below; references/studio.md carries the same table for readers.
+export const DOC_GATES = Object.freeze({
+  'TEXT-OVERLAP': { kind: 'qa-row', id: 'text-overlap' },
+  'TEXT-ON-STYLE': { kind: 'qa-row', id: 'fonts' },
+  'TEXT-ZONE': { kind: 'qa-row', id: 'text-title-safe' },
+  'FLAT-FRAME': { kind: 'gate', id: 'MO-D-03' },
+  'DEAD-AIR': { kind: 'qa-row', id: 'non-text-presence' },
+  'RICH-FILL': { kind: 'treatment', id: 'palette' },
+});
+
 export function renderReport(manifest, gate, { outputs = {}, framesViewed = [], egress = 'websocket', withheld = false, preflight = false } = {}) {
   const lx = manifest.lithermes || {};
   const byId = new Map(gate.rules.map((r) => [r.id, r]));

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

@@ -0,0 +1,44 @@
+// The house file: `motion-house.json` beside a film's output folder, in the user's directory.
+// A full render that passes its gate writes it, or appends the film to it. While it exists,
+// the treatment validator holds every new film in that folder to its style unless the request
+// names another. It is validator input, so the second film inherits the first one's style
+// without anyone having to carry it over.
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { STYLE_IDS } from './styles.mjs';
+
+export const HOUSE_FILE = 'motion-house.json';
+export const HOUSE_SCHEMA = 'litfamily.motion-house/v1';
+const MAX_FILMS = 50;
+
+export const houseFileFor = (out) => path.join(path.dirname(path.resolve(out)), HOUSE_FILE);
+
+/** The house record for an output folder, or null when missing or unusable. */
+export function readHouse(out) {
+  const file = houseFileFor(out);
+  if (!existsSync(file)) return null;
+  try {
+    const house = JSON.parse(readFileSync(file, 'utf8'));
+    if (house?.schema !== HOUSE_SCHEMA || !STYLE_IDS.includes(house.style)) return null;
+    return house;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record a passed film. The first film fixes the house style; later films append. A film
+ * whose style the request named outright appends without moving the house style.
+ */
+export function recordHouse(out, { style, path: renderPath, format, durationSec, now = new Date() }) {
+  const file = houseFileFor(out);
+  const house = readHouse(out) ?? { schema: HOUSE_SCHEMA, style, createdAt: now.toISOString(), films: [] };
+  const dir = path.basename(path.resolve(out));
+  const films = (Array.isArray(house.films) ? house.films : []).filter((film) => film?.dir !== dir);
+  films.push({ dir, style, path: renderPath, format, durationSec, at: now.toISOString() });
+  const next = { ...house, films: films.slice(-MAX_FILMS) };
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, file);
+  return next;
+}