@litfamily/litgrok 1.0.26 → 1.0.28

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

@@ -12,6 +12,7 @@ import { FlashDetector } from './flash.mjs';
 import { FramePool, measureFrame } from './frame-pool.mjs';
 import { encodePng } from './png.mjs';
 import { CONTENT_TYPES, openStage } from './stage-session.mjs';
+import { readPlate } from './blender.mjs';
 import { stillsPlan, writeStills } from './stills.mjs';
 import { startEncode } from './encode.mjs';
 import { encodePreview, findTool, previewRung, promoteOrWithhold, clearDeliverables } from './render.mjs';
@@ -73,6 +74,10 @@ export function scanStage(stageDir) {
   const warnings = [];
   if (!existsSync(join(stageDir, 'index.html'))) return { contract: ['stage/index.html is missing'], network, warnings, files: [], rasters: [] };
   const files = walk(stageDir);
+  // A Blender plate and its preview stills are frames the runner wrote and plate.json lists by name
+  // and size; they are not page rasters. Anything not listed is held to the raster limits.
+  const plates = [readPlate(stageDir, 'plate'), readPlate(stageDir, 'plate-preview')].filter(Boolean);
+  const listed = new Set(plates.flatMap((p) => p.frames.map((f) => `${p.dir}/${String(f.name)}`)));
   const rasters = [];
   for (const file of files) {
     if (file.symlink) continue;
@@ -93,7 +98,7 @@ export function scanStage(stageDir) {
       const hint = text.match(/<link[^>]+rel\s*=\s*["']?(preconnect|prefetch|dns-prefetch|prerender)\b/i);
       if (hint) network.push(`stage/${file.rel}: <link rel=${hint[1]}>`);
     }
-    if (RASTER_EXT.has(ext)) {
+    if (RASTER_EXT.has(ext) && !listed.has(file.rel)) {
       const bytes = readFileSync(file.path);
       let info;
       try { info = rasterInfo(bytes, ext === '.jpeg' ? '.jpg' : ext); } catch { info = { width: 0, height: 0, animated: false }; }
@@ -244,18 +249,31 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
   if (scan.contract.length) fail(new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${scan.contract[0]}`));
   let fonts;
   try { fonts = stageFonts(treatment.typePlan.faces, env); } catch (error) { fail(error); }
+  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 executable = resolveChrome(env);
   if (!executable) fail(new BlockedError(EXIT.NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; set CHROME_PATH to a Chrome executable'));
+  // The browser rung: a three.js world asks for the GPU; a Blender film shows its path-traced
+  // plate under HTML type, so its page needs only the software rung.
+  const rung = stageRung(treatment);
   const ffmpeg = findTool('ffmpeg', env);
   const seed = Number.isInteger(treatment.seed) ? treatment.seed : fnv1a32(treatment.idea);
   const warnings = [...scan.warnings];
 
   const pool = new FramePool();
   let master = null;
+  // The rung the master page actually got (a GPU ask can fall back to software); the replay, the
+  // QA and the manifest reuse it, not the requested rung.
+  let masterRung = null, masterRenderer = null, masterArgs = null;
   let encoder = null;
   let abortReplays = () => {};
   try {
-    master = await openStage({ executable, outDir: out, stageDir, width, height, fps: 60, seed, fonts, label: 'm', log });
+    master = await openStage({ executable, outDir: out, stageDir, width, height, fps: 60, seed, fonts, style, label: 'm', rung, log });
+    if (master.notice) { warnings.push(master.notice); log(master.notice); }
     const prepared = await master.load();
     const contractError = contractCheck(prepared.contract, treatment, width, height);
     if (contractError) throw new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${contractError}`);
@@ -286,7 +304,8 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
     // The QA replay only reads layout between samples and settles before its own captures.
     const stop = { aborted: false };
     const replay = async () => {
-      const session = await openStage({ executable, outDir: out, stageDir, width, height, fps, seed, fonts, label: 'd', log });
+      // The replay shares the master's rung: a replay on another rung would flag the rung, not the page.
+      const session = await openStage({ executable, outDir: out, stageDir, width, height, fps, seed, fonts, style, label: 'd', rung: masterRung ?? rung, log });
       try {
         await session.load();
         const hashes = {};
@@ -309,7 +328,7 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
       const result = await job;
       if (!stillsOnly) {
         const flash = detector.push(result.grid);
-        frames.push({ frame: f, ink: 0, lumP995: Math.round(result.lumP995 * 10000) / 10000, flash: { general: flash.general, red: flash.red, ...(flash.general2 ? { general2: flash.general2 } : {}), ...(flash.red2 ? { red2: flash.red2 } : {}), stepArea: flash.stepArea }, rgbaSha256: result.sha256 });
+        frames.push({ frame: f, ink: 0, lumP995: Math.round(result.lumP995 * 10000) / 10000, lumP005: Math.round(result.lumP005 * 10000) / 10000, busy: Math.round(result.busy * 10000) / 10000, flash: { general: flash.general, red: flash.red, ...(flash.general2 ? { general2: flash.general2 } : {}), ...(flash.red2 ? { red2: flash.red2 } : {}), stepArea: flash.stepArea }, rgbaSha256: result.sha256 });
         await encoder?.write(result.rgba);
       }
       if (keep.has(f)) kept.get(f).rgba = result.rgba;
@@ -330,6 +349,9 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
     while (queue.length) await drain();
     const masterDone = Date.now();
     const pageReport = await master.report();
+    masterRung = master.rung;
+    masterRenderer = master.renderer;
+    masterArgs = master.args;
     await master.close();
     master = null;
     if (pageReport.errors.length) warnings.push(`the page logged ${pageReport.errors.length} error(s); first: ${pageReport.errors[0]}`);
@@ -340,8 +362,27 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
         record({ exitCode: EXIT.NO_FFMPEG_FOR_VIDEO, state: 'blocked', reason: 'no ffmpeg', stillsIndexSha256: stills.sha256 });
         throw new BlockedError(EXIT.NO_FFMPEG_FOR_VIDEO, 'BLOCKED_NO_FFMPEG_FOR_VIDEO: ffmpeg not found on PATH; the stills and the contact sheet were written, install ffmpeg for the film');
       }
+      // The board round: judge the page's text on a QA replay, draw the storyboard, and stop when
+      // copy overlaps, leaves the style, or leaves its zone — fix the page, not the gate.
+      const boardQa = await runStageQa({ executable, out, stageDir, width, height, fps, seed, fonts, treatment, totalFrames, log, stepOrThrow, captureChecked, rung: masterRung, stop });
+      const { writeBoard, addToStills } = await import('./board.mjs');
+      const { assetUsed } = await import('./assets.mjs');
+      const { createHash } = await import('node:crypto');
+      const pad2 = (n) => String(n).padStart(2, '0');
+      const beatFiles = plan.mids.map((m) => join(out, 'stills', `beat-${pad2(m.beat + 1)}-mid.png`));
+      const assetRule = assetUsed(treatment, stageDir);
+      const check = { schema: 1, path: 'stage', round, rules: [...boardQa.results.filter((r) => /^(TEXT-|RICH-FILL)/u.test(r.id)), ...(assetRule ? [assetRule] : [])] };
+      writeFileSync(join(stageDir, 'check.json'), `${JSON.stringify(check, null, 2)}\n`);
+      const boardFile = await writeBoard({ out, treatment, beatFiles, check, env, log });
+      const sha = (b) => createHash('sha256').update(b).digest('hex');
+      addToStills(out, { file: 'stills/board.png', kind: 'board', check: 'stills' }, { sha256: sha });
+      const failed = check.rules.filter((x) => x.status === 'FAIL');
+      if (failed.length) {
+        record({ exitCode: EXIT.GATE_FAIL_QA, state: 'check-fail', stillsIndexSha256: stills.sha256, frames: lastNeeded + 1, perf: { p50Ms: pct(times, 0.5), p95Ms: pct(times, 0.95), totalSec: (Date.now() - started) / 1000 } });
+        throw new BlockedError(EXIT.GATE_FAIL_QA, `BOARD_CHECK_FAIL: ${failed.map((x) => `${x.id} ${x.detail}`).join('; ')}. Fix the page, render --stills-only again, then look at ${boardFile ?? join(out, 'stills', 'board.png')}`);
+      }
       record({ exitCode: EXIT.OK, state: 'stills-only', stillsIndexSha256: stills.sha256, frames: lastNeeded + 1, perf: { p50Ms: pct(times, 0.5), p95Ms: pct(times, 0.95), totalSec: (Date.now() - started) / 1000 } });
-      log(`stills-only: ${stills.index.stills.length} files listed in ${join(out, 'stills', 'index.json')}; open every one, then record the look`);
+      log(`stills-only: board check PASS; open the storyboard ${boardFile ?? join(out, 'stills', 'board.png')} and every file in ${join(out, 'stills', 'index.json')}, record the look with look --round ${round}, make the change, then render the film with --round ${round + 1} (no --stills-only)`);
       return { exitCode: EXIT.OK, stillsOnly: true, stills };
     }
 
@@ -358,7 +399,7 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
     previewJob.catch(() => {});
     const [rerun, qa] = await Promise.all([
       replay(),
-      runStageQa({ executable, out, stageDir, width, height, fps, seed, fonts, treatment, totalFrames, log, stepOrThrow, captureChecked, stop }),
+      runStageQa({ executable, out, stageDir, width, height, fps, seed, fonts, treatment, totalFrames, log, stepOrThrow, captureChecked, rung: masterRung, stop }),
     ]);
     timings.replaysSec = (Date.now() - replayStart) / 1000;
     const masterHash = new Map(frames.map((frame) => [frame.frame, frame.rgbaSha256]));
@@ -371,13 +412,29 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
     if (qa.minCopyFontPx && qa.minCopyFontPx < 32) preview = await encodePreview({ runDir, master: join(runDir, 'film.mp4'), encoder: previewRung(env), minFontPx: qa.minCopyFontPx, env, log, frame: { width, height } });
     const previewRecords = preview.records ? preview.records.map((r) => ({ preview: { frame: r.frame, fps: preview.fps }, flash: { general: r.general, red: r.red, ...(r.general2 ? { general2: r.general2 } : {}), ...(r.red2 ? { red2: r.red2 } : {}) } })) : [];
     const sound = muxGate({ mp4: join(runDir, 'film.mp4'), durationSec: totalFrames / fps, treatment, env, track });
+    // A film about a named product shows its real assets; without a product there is no verdict.
+    const { assetUsed } = await import('./assets.mjs');
+    const assetRule = assetUsed(treatment, stageDir);
+    if (assetRule) qa.results.push(assetRule);
 
+    // The manifest names the rung the master page got and its renderer string, so the report and
+    // the determinism replay can be read against the same hardware.
+    const { isSoftwareRenderer } = await import('./chrome.mjs');
     const manifest = {
       schemaVersion: 1, path: 'stage', format: treatment.format, resolution: [width, height], fps, durationSec: totalFrames / fps, targetDurationSec: treatment.durationSec,
-      frames: totalFrames, seed, renderer: 'SwiftShader software rung (stage path)', softwareRenderer: true, chromeFlags: stageFlagsUsed(), previewEncoder: preview.encoder,
+      frames: totalFrames, seed, rung: masterRung, renderer: `${masterRenderer} on the ${masterRung} rung (stage path)`, softwareRenderer: masterRung === 'software' || isSoftwareRenderer(masterRenderer), chromeFlags: masterArgs.filter((arg) => !arg.startsWith('--user-data-dir') && !arg.startsWith('--window-size') && arg !== 'about:blank'), previewEncoder: preview.encoder,
       sound: sound.summary, round, warnings,
     };
     const stills = writeStills(out, { plan, frames: kept, width, height, path: 'stage', round, mode: 'full', poster: { bytes: posterBytes, frame: posterFrame }, treatmentSha256 });
+    // The final render ships its storyboard too: the done-check wants the board viewed on the final set.
+    const { writeBoard, addToStills } = await import('./board.mjs');
+    const { createHash } = await import('node:crypto');
+    const pad2 = (n) => String(n).padStart(2, '0');
+    const beatFiles = plan.mids.map((m) => join(out, 'stills', `beat-${pad2(m.beat + 1)}-mid.png`));
+    const boardCheck = { schema: 1, path: 'stage', round, rules: [...qa.results.filter((r) => /^(TEXT-|RICH-FILL)/u.test(r.id)), ...(assetRule ? [assetRule] : [])] };
+    await writeBoard({ out, treatment, beatFiles, check: boardCheck, env, log });
+    const sha = (b) => createHash('sha256').update(b).digest('hex');
+    stills.sha256 = addToStills(out, { file: 'stills/board.png', kind: 'board', check: 'stills' }, { sha256: sha });
     manifest.stillsIndexSha256 = stills.sha256;
     clearDeliverables(out);
     writeFileSync(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -415,8 +472,16 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
   }
 }
 
-export function stageFlagsUsed() {
-  return stageArgs({ profileDir: '<profile>', width: 0, height: 0 }).filter((arg) => !arg.startsWith('--user-data-dir') && !arg.startsWith('--window-size') && arg !== 'about:blank');
+// The browser rung for a treatment: a three.js world asks for the platform GPU rung, a Blender
+// film shows its path-traced plate under HTML type on the software rung, and anything else renders
+// on the software rung where a determinism mismatch is always a page leak.
+export function stageRung(treatment) {
+  if (treatment.render3d === 'blender') return 'software';
+  return treatment.depth === '3d' ? 'gpu' : 'software';
+}
+
+export function stageFlagsUsed(rung = 'software') {
+  return stageArgs({ profileDir: '<profile>', width: 0, height: 0, rung }).filter((arg) => !arg.startsWith('--user-data-dir') && !arg.startsWith('--window-size') && arg !== 'about:blank');
 }
 
 // `gate --out <dir>` on a stage render: re-evaluate the recorded facts against the exports where they

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

@@ -0,0 +1,224 @@
+// House styles as data. Four JSON documents under styles/ carry each style's palette, type
+// scale, motion tokens, transitions, ground, default bed, bed list and bans; this module loads,
+// validates and applies them. treatments name a style id; pickStyle() resolves one by rule.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const STYLE_SCHEMA = "litgrok.motion-style/v1";
+export const STYLE_IDS = Object.freeze(["swiss-signal", "tidal", "terminalcore", "paper"]);
+export const DEFAULT_STYLE = "swiss-signal";
+export const TYPE_ROLES = Object.freeze(["display", "headline", "body", "label"]);
+export const TRANSITIONS = Object.freeze(["cut", "match", "wipe", "push", "iris", "dissolve", "morph"]);
+// Copy may sit this far (share of frame side) outside its zone, and this far off a scale step.
+export const ZONE_TOLERANCE = 0.012;
+export const SIZE_TOLERANCE = 0.04;
+
+// [x, y, w, h] as frame fractions. `type` bounds copy; `subject` bounds the drawing.
+export const LAYOUTS = Object.freeze({
+  "16:9": Object.freeze({
+    title: { type: [0.08, 0.2, 0.84, 0.6], subject: [0, 0, 1, 1] },
+    split: { type: [0.08, 0.16, 0.36, 0.68], subject: [0.48, 0.08, 0.46, 0.84] },
+    "split-alt": { type: [0.56, 0.16, 0.36, 0.68], subject: [0.06, 0.08, 0.46, 0.84] },
+    stage: { type: [0.08, 0.75, 0.84, 0.18], subject: [0.06, 0.07, 0.88, 0.64] },
+    hero: { type: [0.08, 0.76, 0.84, 0.17], subject: [0.03, 0.03, 0.94, 0.94] },
+    full: { type: null, subject: [0, 0, 1, 1] },
+  }),
+  "9:16": Object.freeze({
+    title: { type: [0.09, 0.26, 0.82, 0.48], subject: [0, 0, 1, 1] },
+    split: { type: [0.09, 0.08, 0.82, 0.26], subject: [0.06, 0.36, 0.88, 0.56] },
+    "split-alt": { type: [0.09, 0.66, 0.82, 0.26], subject: [0.06, 0.06, 0.88, 0.56] },
+    stage: { type: [0.09, 0.79, 0.82, 0.13], subject: [0.06, 0.06, 0.88, 0.68] },
+    hero: { type: [0.09, 0.8, 0.82, 0.12], subject: [0.03, 0.03, 0.94, 0.94] },
+    full: { type: null, subject: [0, 0, 1, 1] },
+  }),
+});
+export const LAYOUT_IDS = Object.freeze(Object.keys(LAYOUTS["16:9"]));
+const FRAME = Object.freeze({ "16:9": [1920, 1080], "9:16": [1080, 1920] });
+
+// With no name, house file or keyword, the genre picks where one reads better: a warm legible
+// ground for explainers (stage only), the tidal flow for brand moods.
+export const GENRE_STYLE = Object.freeze({ explainer: "paper", "brand-mood": "tidal" });
+
+// Checked in order; the first row with a hit wins. A style the request names outright wins over
+// every row. Paper has no type-engine preset, so the type path skips its row.
+export const STYLE_PICK = Object.freeze([
+  { style: "terminalcore", korean: ["터미널", "CRT", "해커"], latin: ["terminal", "hacker", "crt"] },
+  { style: "tidal", korean: ["물결", "파도", "잔잔한", "흐름"], latin: ["gradient", "wave", "tide", "calm"] },
+  { style: "paper", korean: ["따뜻한", "밝은", "종이", "손그림", "포근한", "아기자기"], latin: ["warm", "cozy", "bright", "paper", "handmade", "hand-drawn"] },
+]);
+const NAMED = Object.freeze({
+  "swiss-signal": ["swiss-signal", "swiss signal", "스위스 시그널"],
+  tidal: ["tidal", "타이달"],
+  terminalcore: ["terminalcore", "터미널코어"],
+  paper: ["paper style", "paper look", "페이퍼 스타일", "페이퍼"],
+});
+
+export class StyleError extends Error {}
+
+const HEX = /^#[0-9a-f]{6}$/iu;
+const isText = (v) => typeof v === "string" && v.trim().length > 0;
+const linear = (hex) => [1, 3, 5].map((i) => {
+  const s = parseInt(hex.slice(i, i + 2), 16) / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+});
+const luminance = (hex) => {
+  const [r, g, b] = linear(hex);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+const ratio = (la, lb) => (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const keywordHit = (text, keyword, korean) => {
+  const pattern = korean
+    ? new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(keyword)}`, "u")
+    : new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(keyword)}(?![\\p{L}\\p{N}])`, "iu");
+  return pattern.test(text);
+};
+
+/** A style document is valid, or throws StyleError naming the first bad field. */
+export function validateStyle(style) {
+  const fail = (field, message) => {
+    throw new StyleError(`style ${style?.id ?? "?"}: ${field}: ${message}`);
+  };
+  if (!style || typeof style !== "object") fail("style", "must be an object");
+  if (style.schema !== STYLE_SCHEMA) fail("schema", `must be ${STYLE_SCHEMA}`);
+  if (!STYLE_IDS.includes(style.id)) fail("id", `must be one of ${STYLE_IDS.join(", ")}`);
+  for (const k of ["name", "summary"]) if (!isText(style[k])) fail(k, "must be a non-empty string");
+  const p = style.palette ?? {};
+  for (const role of ["ground", "surface", "ink", "muted", "signal", "line"]) if (!HEX.test(p[role] ?? "")) fail(`palette.${role}`, "must be #rrggbb");
+  if (!Array.isArray(style.textRoles) || style.textRoles.some((r) => !HEX.test(p[r] ?? ""))) fail("textRoles", "every text role names a palette colour");
+  const ground = luminance(p.ground);
+  if (ratio(luminance(p.ink), ground) < 7) fail("palette.ink", "ink on ground needs 7:1");
+  if (ratio(luminance(p.muted), ground) < 4.5) fail("palette.muted", "muted on ground needs 4.5:1");
+  for (const role of ["signal", "accent"]) if (p[role] && ratio(luminance(p[role]), ground) < 3) fail(`palette.${role}`, `${role} on ground needs 3:1 (large type)`);
+  if (!Array.isArray(style.accents) || style.accents.length < 3) fail("accents", "names at least three role accents a rich film may add");
+  style.accents.forEach((a, i) => {
+    if (!isText(a?.role)) fail(`accents[${i}].role`, "says what the colour marks");
+    if (!HEX.test(a?.color ?? "")) fail(`accents[${i}].color`, "must be #rrggbb");
+    if (ratio(luminance(a.color), ground) < 3) fail(`accents[${i}].color`, "an accent on ground needs 3:1 (large type)");
+  });
+  for (const role of TYPE_ROLES) if (!isText(style.faces?.[role]?.family)) fail(`faces.${role}`, "needs a family");
+  for (const format of Object.keys(FRAME)) {
+    const s = style.scale?.[format];
+    if (!s || TYPE_ROLES.some((r) => !(s[r] > 0))) fail(`scale.${format}`, "needs a size per type role");
+    if (!(s.display > s.headline && s.headline > s.body && s.body > s.label)) fail(`scale.${format}`, "steps must descend display > headline > body > label");
+  }
+  const m = style.motion ?? {};
+  for (const k of ["enter", "move", "exit"]) if (!Array.isArray(m.ease?.[k]) || m.ease[k].length !== 4) fail(`motion.ease.${k}`, "is a cubic-bezier [x1, y1, x2, y2]");
+  for (const k of ["micro", "move", "hero", "exit"]) if (!(m.dur?.[k] > 0)) fail(`motion.dur.${k}`, "seconds > 0");
+  if (!(m.dur.exit <= m.dur.hero)) fail("motion.dur.exit", "an exit is never longer than the hero move");
+  if (!Array.isArray(style.transitions) || !style.transitions.length || style.transitions.some((x) => !TRANSITIONS.includes(x))) fail("transitions", `a subset of ${TRANSITIONS.join(", ")}`);
+  if (!isText(style.score?.genre)) fail("score.genre", "names the genre a film's score takes by default");
+  if (!style.sound || !isText(style.sound.timbre)) fail("sound", "needs the generated bed's palette");
+  if (!Array.isArray(style.beds) || style.beds.length < 2 || style.beds.some((b) => !isText(b?.timbre) || !isText(b?.key) || !(b?.tempo > 0))) fail("beds", "lists at least two beds a film may pick, each { timbre, key, mode, tempo }");
+  const same = (a, b) => ["timbre", "key", "mode", "tempo"].every((k) => String(a[k]).toLowerCase() === String(b[k]).toLowerCase());
+  if (!style.beds.some((b) => same(b, style.sound))) fail("beds", "must include the default bed (sound)");
+  if (!Array.isArray(style.bans) || style.bans.length < 3) fail("bans", "names at least three defaults this style never uses");
+  return style;
+}
+
+const cache = new Map();
+/** A shipped style by id, validated and frozen. */
+export function readStyle(id) {
+  if (!STYLE_IDS.includes(id)) throw new StyleError(`unknown style: ${id} (choose ${STYLE_IDS.join(", ")})`);
+  if (!cache.has(id)) {
+    const url = new URL(`../../styles/${id}.json`, import.meta.url);
+    cache.set(id, Object.freeze(validateStyle(JSON.parse(readFileSync(fileURLToPath(url), "utf8")))));
+  }
+  return cache.get(id);
+}
+
+/** Every font family copy may use in this style (the role faces, the Hangul face, Pretendard). */
+export const styleFamilies = (style) => new Set([...TYPE_ROLES.map((r) => style.faces[r].family), style.hangul?.family ?? "Pretendard", "Pretendard"]);
+/** The hex colours copy may use. */
+export const styleTextColors = (style) => style.textRoles.map((r) => style.palette[r].toLowerCase());
+/** The beds a film in this style may pick from, the default first. */
+export const styleBeds = (style) => style.beds;
+/** The role accents a rich film may add to the core palette, each { role, color }. */
+export const styleAccents = (style) => style.accents;
+/** All palette colours of the style (what a stage treatment's palette may list); rich adds the accents. */
+export const styleColors = (style, { rich = false } = {}) => [...Object.values(style.palette), ...(rich ? style.accents.map((a) => a.color) : [])].map((c) => c.toLowerCase());
+
+/**
+ * Which style a film takes. A style the request names wins; then the project's house style; then
+ * the keyword auto-pick; then the genre's style; then the default. Returns { id, source, reason }.
+ */
+export function pickStyle({ request = "", copy = [], path = "stage", house = null, genre = null } = {}) {
+  const text = String(request);
+  for (const [id, names] of Object.entries(NAMED)) {
+    if (path === "type" && !readStyle(id).typePreset) continue;
+    const hit = names.find((n) => keywordHit(text, n, /[가-힣]/u.test(n)));
+    if (hit) return { id, source: "request", reason: `the request names the ${id} style ("${hit}")` };
+  }
+  if (house?.style && STYLE_IDS.includes(house.style) && (path !== "type" || readStyle(house.style).typePreset)) {
+    return { id: house.style, source: "house", reason: `the project's house style is ${house.style} (motion-house.json)` };
+  }
+  const haystack = [text, ...copy].join("\n");
+  for (const row of STYLE_PICK) {
+    if (path === "type" && !readStyle(row.style).typePreset) continue;
+    for (const k of row.korean) if (keywordHit(haystack, k, true)) return { id: row.style, source: "auto", reason: `the request mentions "${k}"` };
+    for (const k of row.latin) if (keywordHit(haystack, k, false)) return { id: row.style, source: "auto", reason: `the request mentions "${k}"` };
+  }
+  const byGenre = GENRE_STYLE[genre];
+  if (byGenre && (path !== "type" || readStyle(byGenre).typePreset)) return { id: byGenre, source: "genre", reason: `no style is named and no keyword picks one, and a ${genre} film takes ${byGenre}` };
+  return { id: DEFAULT_STYLE, source: "default", reason: `no style is named and no keyword picks one, so the default ${DEFAULT_STYLE}` };
+}
+
+/** A layout's zones in pixels for a format: { type: {x, y, w, h} | null, subject: {...} }. */
+export function zonesPx(format) {
+  const [W, H] = FRAME[format];
+  const px = (r) => (r ? { x: Math.round(r[0] * W), y: Math.round(r[1] * H), w: Math.round(r[2] * W), h: Math.round(r[3] * H) } : null);
+  return Object.fromEntries(Object.entries(LAYOUTS[format]).map(([id, z]) => [id, { type: px(z.type), subject: px(z.subject) }]));
+}
+
+/** The type step a rendered size sits on, or null when it is off the style's scale. */
+export function scaleStep(style, format, sizePx) {
+  for (const role of TYPE_ROLES) {
+    const step = style.scale[format][role];
+    if (Math.abs(sizePx - step) <= step * SIZE_TOLERANCE) return role;
+  }
+  return null;
+}
+
+const familyStack = (style, role) => {
+  const f = style.faces[role];
+  const hangul = style.hangul?.family ?? "Pretendard";
+  return [f.family, hangul, "Pretendard"].filter((x, i, a) => a.indexOf(x) === i).map((x) => `"${x}"`).join(", ");
+};
+
+/** /lit/style.css for one style and format: custom properties, type-role classes, colour classes. */
+export function styleCss(style, format) {
+  const s = style.scale[format];
+  const vars = [
+    ...Object.entries(style.palette).map(([k, v]) => `  --lit-${k}: ${v};`),
+    ...TYPE_ROLES.map((r) => `  --lit-size-${r}: ${s[r]}px;`),
+  ];
+  const roles = TYPE_ROLES.map((r) => {
+    const f = style.faces[r];
+    return `.lit-${r} { font-family: ${familyStack(style, r)}; font-size: ${s[r]}px; font-weight: ${f.weight}; ${f.stretch ? `font-stretch: ${f.stretch}; ` : ""}line-height: ${style.leading?.[r] ?? 1.3}; letter-spacing: 0; margin: 0; }`;
+  });
+  const colours = style.textRoles.map((r) => `.lit-${r === "ground" ? "knockout" : r} { color: var(--lit-${r}); }`);
+  return [
+    `/* lit-typographic-motion style: ${style.id} (${format}) */`,
+    `:root {\n${vars.join("\n")}\n}`,
+    // Korean breaks only between eojeol, never inside a word (type-craft.md, MO-A-13).
+    `html, body { margin: 0; overflow: hidden; background: var(--lit-ground); color: var(--lit-ink); font-family: ${familyStack(style, "body")}; word-break: keep-all; overflow-wrap: break-word; }`,
+    ...roles,
+    ...colours,
+    ".lit-zone { position: absolute; box-sizing: border-box; }",
+    "",
+  ].join("\n");
+}
+
+/** /lit/style.js: window.LitStyle (tokens and pixel zones) and window.LitTimeline (the treatment's shots). */
+export function styleScript(style, format, treatment) {
+  const timeline = {
+    format, fps: treatment.fps ?? 60, duration: treatment.durationSec,
+    beats: (treatment.beats ?? []).map((b, i) => ({ index: i, t0: b.t0, t1: b.t1, layout: b.layout ?? null, transition: b.transition ?? null })),
+  };
+  const data = {
+    id: style.id, name: style.name, format, palette: style.palette, textRoles: style.textRoles,
+    faces: style.faces, hangul: style.hangul ?? null, scale: style.scale[format], leading: style.leading ?? {},
+    motion: style.motion, transitions: style.transitions, ground: style.ground, zones: zonesPx(format),
+  };
+  return `window.LitStyle = Object.freeze(${JSON.stringify(data)});\nwindow.LitTimeline = Object.freeze(${JSON.stringify(timeline)});\n`;
+}