@litfamily/litmuse 0.1.1 → 0.1.2

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

@@ -0,0 +1,144 @@
+// The offline Blender rung. A 3D film with `render3d: "blender"` writes its world as a Blender
+// Python scene (<out>/stage/scene.py); `motion.mjs blender` renders it headless with Cycles on the
+// GPU through the bundled runner: first preview stills at the beat midpoints (half size, few
+// samples) to look at, then with --final the full plate sequence in <out>/stage/plate/ with
+// plate.json, the receipt the stage trusts. The stage page shows the plate through
+// LitStage.plate() and draws its type and labels over it, so the page itself stays on the
+// software rung. Without Blender the command renders nothing and names the fallback: the
+// three.js world on the GPU rung.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT } from "../core/constants.mjs";
+import { BlockedError } from "./chrome.mjs";
+import { FORMATS, TreatmentError, loadTreatment } from "./treatment.mjs";
+
+export const BLENDER = Object.freeze({
+  macApp: "/Applications/Blender.app/Contents/MacOS/Blender",
+  runner: fileURLToPath(new URL("../blender/runner.py", import.meta.url)),
+  plateFps: 30,
+  device: "METAL",
+  preview: Object.freeze({ percent: 50, samples: 40 }),
+  final: Object.freeze({ percent: 100, samples: 160 }),
+});
+
+/**
+ * Where Blender is: an explicit LITMUSE_BLENDER path (used only when it exists; 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.LITMUSE_BLENDER) return exists(env.LITMUSE_BLENDER) ? { path: env.LITMUSE_BLENDER, source: "LITMUSE_BLENDER" } : null;
+  if (platform === "darwin" && exists(BLENDER.macApp)) return { path: BLENDER.macApp, source: "app" };
+  for (const dir of String(env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+    const file = path.join(dir, "blender");
+    if (exists(file)) return { path: file, source: "PATH" };
+  }
+  return null;
+}
+
+const plateFrames = (treatment) => Math.round(treatment.durationSec * BLENDER.plateFps);
+
+/** The headless command line: factory settings, the runner, and the runner's own arguments after `--`. */
+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 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(treatment.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 (LITMUSE_BLENDER, /Applications/Blender.app, blender on PATH), so nothing was rendered.",
+  `Set render3d to "three" in ${path.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 }) {
+  let treatment;
+  try {
+    treatment = loadTreatment(out, { pathName: "stage" });
+  } catch (error) {
+    if (error instanceof TreatmentError) throw new BlockedError(EXIT.BLOCKED_TREATMENT_INVALID, error.message);
+    throw error;
+  }
+  if (treatment.render3d !== "blender") throw new BlockedError(EXIT.USAGE, `blender renders a treatment with render3d "blender" (this one is ${treatment.render3d ?? "three"})`);
+  const stageDir = path.join(out, "stage");
+  const scene = path.join(stageDir, "scene.py");
+  if (!existsSync(scene)) throw new BlockedError(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 = path.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 = path.join(dir, "receipt.json");
+  if (run.code !== 0 || !existsSync(receiptFile)) {
+    throw new BlockedError(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(path.join(dir, name)).size }));
+  if (frames.length !== expected) throw new BlockedError(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(path.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 = 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 ok = plate.frames.every((f) => {
+    const p = path.join(stageDir, sub, String(f.name));
+    return path.basename(String(f.name)) === f.name && existsSync(p) && statSync(p).size === f.bytes;
+  });
+  return ok ? { ...plate, dir: sub } : null;
+}

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

@@ -0,0 +1,136 @@
+// 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, hand-off and hero move under
+// it, the shot's type zone outlined on the frame; a header with the house style (name,
+// palette, 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 { StageBrowser } from "./stage-capture.mjs";
+import { stageFonts } from "./stage-serve.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, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const secs = (v) => `${Number(v).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 byHeight = Math.floor((usableH - (rows - 1) * BOARD.gap) / rows) - BOARD.caption;
+    const th = Math.min(Math.round(tw / aspect), byHeight);
+    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((o) => o.tw * o.th));
+  return options.filter((o) => o.tw * o.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 pal = style?.palette ?? {};
+  const chips = Object.entries(pal).filter(([k]) => ["ground", "ink", "muted", "signal", "accent"].includes(k))
+    .map(([k, v]) => `<span class="chip"><i style="background:${esc(v)}"></i>${esc(k)} ${esc(v)}</span>`).join("");
+  const tiles = stills.map((file, i) => {
+    const b = treatment.beats[i] ?? {};
+    const z = b.layout && zones[b.layout]?.type;
+    const guide = z ? `<b class="zone" style="left:${(z[0] * 100).toFixed(2)}%;top:${(z[1] * 100).toFixed(2)}%;width:${(z[2] * 100).toFixed(2)}%;height:${(z[3] * 100).toFixed(2)}%"></b>` : "";
+    const meta = [String(i + 1).padStart(2, "0"), `${secs(b.t0)}–${secs(b.t1)} s`, b.layout, b.transition && b.transition !== "end" ? `→ ${b.transition}` : b.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(b.hero ?? b.onScreen ?? "")}</span></figcaption></figure>`;
+  }).join("");
+  const failed = (check?.rules ?? []).filter((x) => x.status === "FAIL");
+  const verdict = !check ? "layout check: not run on this render"
+    : failed.length ? `layout check: FAIL — ${failed.map((x) => x.id).join(", ")}` : "layout check: PASS";
+  const sound = treatment.sound?.mode === "generated" && treatment.sound.palette
+    ? `${treatment.sound.palette.timbre}, ${treatment.sound.palette.key} ${treatment.sound.palette.mode}, ${treatment.sound.palette.tempo} BPM`
+    : treatment.sound?.mode === "score" ? `score (${treatment.sound.genre ?? readStyle(treatment.style).score.genre})` : treatment.sound?.mode ?? "none";
+  const ground = pal.ground ?? "#101216";
+  return `<!doctype html>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/stage-kit.js"></script>
+<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(pal.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>LitStage.define({ width: ${BOARD.width}, height: ${BOARD.height}, fps: 30, duration: 1, render() {} });</script>
+</body>
+`;
+}
+
+/**
+ * Render `<out>/stills/board.png` from the beat stills already written. Returns the file path.
+ * `check` is the layout check ({ rules }) when one ran.
+ */
+export async function writeBoard({ out, treatment, beatFiles, check = null, env = process.env, log = () => {} }) {
+  const dir = path.join(out, ".run", "board");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const names = beatFiles.map((f, i) => {
+    const name = `s${String(i + 1).padStart(2, "0")}.png`;
+    copyFileSync(f, path.join(dir, name));
+    return name;
+  });
+  writeFileSync(path.join(dir, "index.html"), boardHtml({ treatment, stills: names, check }));
+  const browser = await StageBrowser.open({
+    stageDir: dir, faces: stageFonts(env), rasters: names.map((rel) => ({ rel })), width: BOARD.width, height: BOARD.height, seed: 1,
+    profileDir: path.join(out, ".run", `cb${process.pid % 100000}`), env, log,
+  });
+  try {
+    await browser.step(0, 30, { paint: true });
+    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/index.json`; returns the new index SHA-256. */
+export function addToStills(out, entry, { sha256 }) {
+  const indexFile = path.join(out, "stills", "index.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`);
+  index.files = [...index.files.filter((f) => f.file !== entry.file), { ...entry, sha256: sha256(readFileSync(file)) }];
+  const bytes = Buffer.from(`${JSON.stringify(index, null, 2)}\n`);
+  writeFileSync(indexFile, bytes);
+  return sha256(bytes);
+}

package/plugin/skills/lit-typographic-motion/engine/node/done.mjs

@@ -6,12 +6,14 @@
 // treatment with the first valid one and records any downgrade. A cover (treatment mode: cover) is
 // done on its own terms: the decoded cover reached every TARGET gate, and the last look round viewed
 // the contact sheet, the poster and the seam pair of that render. A generated asset in assets.json
-// becomes a label the reply has to carry.
+// becomes a label the reply has to carry. A film whose treatment asks for a preview (`preview: true`)
+// is done at its board: a stills-only render whose layout check passed, looked at, storyboard included.
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { generatedLabels } from "./cover-assets.mjs";
 import { validateCoverTreatment } from "./cover-treatment.mjs";
+import { readHouse } from "./house.mjs";
 import { readLook } from "./look.mjs";
 import { readStills } from "./stills.mjs";
 import { validateTreatment } from "./treatment.mjs";
@@ -49,10 +51,11 @@ export function evaluateDone({ out, viewedFiles = null }) {
   try {
     const raw = JSON.parse(readFileSync(tFile, "utf8"));
     if (raw?.mode === "cover") return evaluateCoverDone({ out, raw, viewedFiles });
-    treatment = validateTreatment(raw);
+    treatment = validateTreatment(raw, { house: readHouse(out) });
   } catch (error) {
     return notDone(`treatment.json is not valid: ${error.message}`);
   }
+  if (treatment.preview === true) return evaluatePreviewDone({ out, viewedFiles });
   const manifestFile = path.join(out, "manifest.json");
   const reportFile = path.join(out, "gate-report.txt");
   if (!existsSync(manifestFile) || !existsSync(reportFile)) return notDone("no full render has finished (manifest.json or gate-report.txt is missing)");
@@ -85,7 +88,7 @@ export function evaluateDone({ out, viewedFiles = null }) {
     if (stills && last.stillsSha256 !== stills.sha256) reasons.push("the last look round was recorded before the final render (its stills manifest differs); look again and record it");
     if (last.blocked === "no-vision-tool") unviewed = true;
     else if (stills) {
-      const required = stills.index.files.filter((f) => ["poster", "sheet", "beat", "strip"].includes(f.kind)).map((f) => f.file);
+      const required = stills.index.files.filter((f) => ["poster", "sheet", "beat", "strip", "board"].includes(f.kind)).map((f) => f.file);
       const missing = required.filter((f) => !last.viewed?.includes(f));
       if (missing.length) reasons.push(`the last look round did not view ${missing.slice(0, 4).join(", ")}${missing.length > 4 ? ` (+${missing.length - 4})` : ""}`);
       if (viewedFiles) {
@@ -110,6 +113,42 @@ export function evaluateDone({ out, viewedFiles = null }) {
   return { status: unviewed ? "DONE_UNVIEWED" : "DONE", reasons: [], downgraded, openItems };
 }
 
+/** A preview: the board round of a film is the deliverable; the full render waits for the user. */
+export function evaluatePreviewDone({ out, viewedFiles = null }) {
+  const reasons = [];
+  const stills = readStills(out);
+  if (!stills) return { status: "NOT_DONE", reasons: ["no board yet: render with --stills-only"], downgraded: [], openItems: [], preview: true };
+  const board = stills.index.files.find((f) => f.kind === "board");
+  if (!board) reasons.push("the stills set has no storyboard (stills/board.png); render with --stills-only again");
+  try {
+    const check = JSON.parse(readFileSync(path.join(out, "stills", "check.json"), "utf8"));
+    const failed = (check.rules ?? []).filter((x) => x.status === "FAIL").map((x) => x.id);
+    if (failed.length) reasons.push(`the board check failed (${failed.join(", ")}); fix the page and render the board again`);
+  } catch {
+    if (stills.index.path === "stage") reasons.push("the board check result (stills/check.json) is missing");
+  }
+  let look;
+  try {
+    look = readLook(out);
+  } catch {
+    return { status: "NOT_DONE", reasons: ["look.json is unreadable"], downgraded: [], openItems: [], preview: true };
+  }
+  const last = look.rounds[look.rounds.length - 1];
+  if (!last) reasons.push("no look round on the board: open the storyboard and the stills with read_file and record round 1");
+  else {
+    if (last.stillsSha256 !== stills.sha256) reasons.push("the look round was recorded before the latest board; look again and record it");
+    const required = stills.index.files.filter((f) => ["board", "sheet", "beat"].includes(f.kind)).map((f) => f.file);
+    const missing = required.filter((f) => !last.viewed?.includes(f));
+    if (missing.length) reasons.push(`the look round did not view ${missing.slice(0, 4).join(", ")}`);
+    if (viewedFiles) {
+      const unopened = (last.viewed ?? []).filter((f) => !viewedFiles.has(path.resolve(out, f)));
+      if (unopened.length) reasons.push(`these files are listed as viewed but were never opened with read_file: ${unopened.slice(0, 4).join(", ")}`);
+    }
+  }
+  if (reasons.length) return { status: "NOT_DONE", reasons, downgraded: [], openItems: [], preview: true };
+  return { status: last.blocked === "no-vision-tool" ? "DONE_UNVIEWED" : "DONE", reasons: [], downgraded: [], openItems: [], preview: true, labels: [`this is the storyboard preview (${path.join(out, "stills", "board.png")}); the film is not rendered yet, and the user can say go to render it`] };
+}
+
 /** The cover branch of the done-check (references/cover.md, Done). */
 export function evaluateCoverDone({ out, raw, viewedFiles = null }) {
   const notDone = (reason) => ({ status: "NOT_DONE", reasons: [reason], downgraded: [], openItems: [], mode: "cover" });

package/plugin/skills/lit-typographic-motion/engine/node/gallery.mjs

@@ -0,0 +1,120 @@
+// `motion.mjs styles --out <dir> [--format 16:9|9:16]`: the style gallery. One short demo
+// film, the same treatment and the same drawings, rendered as a board round in every house
+// style, so a person sees what each style looks like before asking for a film. Each style's
+// board lands in `<dir>/<style>/stills/board.png`, and `<dir>/styles.png` sets them side by
+// side. The demo also proves the styles and the scaffold pass the board check as shipped.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { EXIT } from "../core/constants.mjs";
+import { decodePng } from "./png.mjs";
+import { scaffoldHtml } from "./scaffold.mjs";
+import { renderStage } from "./stage.mjs";
+import { composeGrid } from "./stills.mjs";
+import { STYLE_IDS, readStyle } from "./styles.mjs";
+
+const COPY = ["작게 시작해서 끝까지", "One clock for every frame", "한 화면에 한 가지 생각", "Same house, every film"];
+
+/** The demo treatment for one style: four shots, one per text layout, 12 s. */
+export function demoTreatment(styleId, format = "16:9") {
+  const style = readStyle(styleId);
+  const hand = (i) => style.transitions[i % style.transitions.length];
+  const vertical = format === "9:16" ? " vertical" : "";
+  const beats = [
+    { t0: 0, t1: 3, layout: "title", hero: "The opening line lands while a ring draws itself behind it.", purpose: "Open on the promise.", onScreen: "A ring drawing on behind the opening line.", motion: "The ring draws on; the line rises in.", sound: "Pad opens with a hit on the first word." },
+    { t0: 3, t1: 6, layout: "split", hero: "Five bars rise in turn beside the line.", purpose: "Show the system.", onScreen: "Five bars rising beside one line.", motion: "Bars rise in stagger.", sound: "Hit on the cut." },
+    { t0: 6, t1: 9, layout: "split-alt", hero: "A dot travels a path from left to right.", purpose: "Show one idea per screen.", onScreen: "A dot crossing a drawn path.", motion: "The dot travels the path.", sound: "A rise into the close." },
+    { t0: 9, t1: 12, layout: "stage", hero: "A grid of squares settles above the closing line.", purpose: "Close on the house.", onScreen: "A settling grid of squares over a closing caption.", motion: "Squares settle in stagger.", sound: "Closing cadence." },
+  ].map((b, i, all) => ({ ...b, lines: [i], transition: i === all.length - 1 ? "end" : hand(i) }));
+  return {
+    // A calibration sheet, not a film: the same plain demo in every style, so styles compare.
+    request: `render a 12 s${vertical} simple demo film in the ${styleId} style`,
+    register: "minimal",
+    genre: "other", path: "stage", pathReason: "The demo draws shapes beside its type, which the type engine cannot draw.",
+    style: styleId,
+    idea: "Four screens, one per layout, so the house style can be judged before a film is made.",
+    audience: "Someone choosing a house style for their films.", channel: "A gallery sheet viewed before a film is made, played with sound.",
+    format, formatReason: format === "9:16" ? "The gallery shows the vertical layouts." : "The gallery shows the landscape layouts.",
+    durationSec: 12, beats,
+    story: { expect: "Four screens that each show a new shape.", turn: "The bars of the second screen become the path the dot travels on the third.", beat: 2, payoff: "Everything settles into one grid above the closing line." },
+    protagonist: { name: "the signal mark", kind: "object", look: "The style's signal colour as a ring, bars, a dot and one accent square.", acts: [{ beat: 0, action: "Draws itself as a ring." }, { beat: 1, action: "Rises as five bars." }, { beat: 2, action: "Travels the path as a dot." }, { beat: 3, action: "Lands as the accent square of the grid." }] },
+    subject: { name: "the style demo", source: "invented", specifics: ["Four screens with a ring, bars, a travelling dot and a grid.", "Each screen uses one layout of the house grid."] },
+    visualDevices: [{ kind: "shape", role: "subject", beats: [0, 1, 2, 3] }, { kind: "path", role: "support", beats: [2] }],
+    typePlan: { faces: [style.faces.headline.family], hierarchy: "One line per screen in the style's headline or display size.", maxWordsOnScreen: 6 },
+    sound: { mode: "generated", plan: "The style's own bed with a hit on the cuts and a closing cadence.", palette: { ...style.sound }, events: [{ t: 1.2, on: "The ring closes.", kind: "tap" }, { t: 4.4, on: "The last bar reaches its height.", kind: "tap" }, { t: 10.6, on: "The accent square lands in the grid.", kind: "chime" }] },
+    copy: { source: "invented", lines: COPY },
+    inventions: ["the style demo (its four screens)", "all four copy lines"],
+    ambition: "Each screen shows one layout cleanly so the style's type, colour and motion read at a glance.",
+  };
+}
+
+// The demo's drawings: generic shapes in the style's own colours, one per shot.
+const DEMO_DRAW = [
+  `(s, svg) => {
+      const z = LitStage.zone(s.layout, "subject");
+      const r = Math.min(z.w, z.h) * 0.34;
+      const len = 2 * Math.PI * r;
+      svg.innerHTML = \`<circle cx="\${z.w * 0.5}" cy="\${z.h * 0.5}" r="\${r}" fill="none" stroke="var(--lit-line)" stroke-width="6"/><circle cx="\${z.w * 0.5}" cy="\${z.h * 0.5}" r="\${r}" fill="none" stroke="var(--lit-signal)" stroke-width="6" stroke-dasharray="\${len}" stroke-dashoffset="\${len * (1 - s.enter(0, 1.6))}"/>\`;
+    },`,
+  `(s, svg) => {
+      const z = LitStage.zone(s.layout, "subject");
+      const w = z.w / 9;
+      svg.innerHTML = [0, 1, 2, 3, 4].map((k) => { const h = z.h * (0.3 + 0.12 * k) * s.enter(0.1 + k * T.stagger.item * 2, T.dur.hero); return \`<rect x="\${w * (1 + k * 1.6)}" y="\${z.h * 0.9 - h}" width="\${w}" height="\${h}" fill="\${k === 4 ? "var(--lit-accent, var(--lit-signal))" : "var(--lit-signal)"}"/>\`; }).join("");
+    },`,
+  `(s, svg) => {
+      const z = LitStage.zone(s.layout, "subject");
+      const x = z.w * (0.1 + 0.8 * T.ease.move(LitStage.clamp(s.local / (s.length * 0.8))));
+      svg.innerHTML = \`<path d="M\${z.w * 0.1} \${z.h * 0.6} C \${z.w * 0.35} \${z.h * 0.2}, \${z.w * 0.65} \${z.h * 0.9}, \${z.w * 0.9} \${z.h * 0.45}" fill="none" stroke="var(--lit-line)" stroke-width="5"/><circle cx="\${x}" cy="\${z.h * 0.55}" r="\${z.h * 0.06}" fill="var(--lit-signal)"/>\`;
+    },`,
+  `(s, svg) => {
+      const z = LitStage.zone(s.layout, "subject");
+      const n = 8;
+      const c = Math.min(z.w / (n + 2), z.h / 4);
+      const cells = [];
+      for (let k = 0; k < n * 2; k++) { const e = s.enter(0.05 * k, T.dur.move); cells.push(\`<rect x="\${c * (1 + (k % n)) + c * 0.1}" y="\${z.h * 0.3 + c * Math.floor(k / n) + (1 - e) * 30}" width="\${c * 0.8}" height="\${c * 0.8}" opacity="\${e}" fill="\${k === 11 ? "var(--lit-accent, var(--lit-signal))" : "var(--lit-muted)"}"/>\`); }
+      svg.innerHTML = cells.join("");
+    },`,
+];
+
+/** The demo page: the scaffold with the demo drawings in its DRAW slots. */
+export function demoPage(treatment) {
+  let k = 0;
+  return scaffoldHtml(treatment).replace(/ {4}\(s, svg, t\) => \{\},/gu, () => `    ${DEMO_DRAW[k++ % DEMO_DRAW.length]}`);
+}
+
+/** Render the gallery: a board round per style, then one sheet of the four boards. */
+export async function stylesCommand({ out, format = "16:9", env = process.env, log = () => {} }) {
+  if (!["16:9", "9:16"].includes(format)) return { code: EXIT.USAGE, message: "--format is 16:9 or 9:16" };
+  mkdirSync(out, { recursive: true });
+  const boards = [];
+  const verdicts = [];
+  for (const id of STYLE_IDS) {
+    const dir = path.join(out, id);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(path.join(dir, "stage"), { recursive: true });
+    const treatment = demoTreatment(id, format);
+    writeFileSync(path.join(dir, "treatment.json"), `${JSON.stringify(treatment, null, 2)}\n`);
+    writeFileSync(path.join(dir, "stage", "index.html"), demoPage(treatment));
+    log(`styles: rendering the ${id} board`);
+    const r = await renderStage({ out: dir, round: 1, stillsOnly: true, env, log });
+    verdicts.push(`${id}: ${r.code === EXIT.OK ? "board check PASS" : r.message.split(";")[0]}`);
+    boards.push(decodePng(readFileSync(path.join(dir, "stills", "board.png"))));
+  }
+  const rgba = boards.map((b) => (b.channels === 4 ? b.pixels : toRgba(b.pixels, b.channels)));
+  const sheet = composeGrid(rgba, boards[0].width, boards[0].height, { cols: 2, tw: 960, th: 540 });
+  const file = path.join(out, "styles.png");
+  writeFileSync(file, sheet);
+  const failed = verdicts.filter((v) => !/PASS$/u.test(v));
+  return { code: failed.length ? EXIT.GATE_FAIL_QA : EXIT.OK, message: `STYLES: ${file}\n${verdicts.join("\n")}` };
+}
+
+function toRgba(pixels, channels) {
+  const n = pixels.length / channels;
+  const out = Buffer.alloc(n * 4);
+  for (let i = 0; i < n; i++) {
+    out[i * 4] = pixels[i * channels];
+    out[i * 4 + 1] = pixels[i * channels + (channels >= 3 ? 1 : 0)];
+    out[i * 4 + 2] = pixels[i * channels + (channels >= 3 ? 2 : 0)];
+    out[i * 4 + 3] = 255;
+  }
+  return out;
+}

package/plugin/skills/lit-typographic-motion/engine/node/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 = "litmuse.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((f) => f?.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;
+}

package/plugin/skills/lit-typographic-motion/engine/node/pipeline.mjs

@@ -2,6 +2,7 @@
 // brief): timeline -> pre-flight gate -> stills -> contact sheet -> [--stills-only stops] -> master,
 // preview, poster, reduced-motion still into .run/stage -> determinism re-render and perf in a second
 // Chrome process -> full gate -> promote, or withhold on a flash-audit FAIL.
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, createWriteStream } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -23,6 +24,8 @@ import { formatReport, formatPreflightReport } from "./report.mjs";
 import { loadTreatment, TreatmentError } from "./treatment.mjs";
 import { viewedCount } from "./look.mjs";
 import { stillsPlan, writeStills } from "./stills.mjs";
+import { addToStills, writeBoard } from "./board.mjs";
+import { recordHouse } from "./house.mjs";
 import { treatmentSha } from "./done.mjs";
 import { auditMuxed } from "./sound.mjs";
 import { soundTrackFor } from "./sound-cli.mjs";
@@ -183,7 +186,7 @@ export function cutFrames(plan) {
  * midpoints, a -6/0/+6 strip at each of the engine's cuts, and a 12-frame sheet. Returns the frames
  * so a full render can rewrite the index with the delivered poster.
  */
-async function renderStillsSet({ session, plan, treatment, out, round, stillsOnly }) {
+async function renderStillsSet({ session, plan, treatment, out, round, stillsOnly, env = process.env, log = () => {} }) {
   const beats = treatment.beats.map((b) => ({ t0: Math.min(b.t0, plan.durationSec), t1: Math.min(b.t1, plan.durationSec) }));
   const cuts = plan.shots.slice(1).map((sh) => Math.round(sh.start * plan.fps)).filter((c) => c > 0 && c < plan.frameCount);
   const layout = stillsPlan({ beats, fps: plan.fps, frameCount: plan.frameCount, cuts, posterBeat: treatment.posterBeat });
@@ -194,8 +197,15 @@ async function renderStillsSet({ session, plan, treatment, out, round, stillsOnl
       frames.set(n, Buffer.from(bytes));
     });
   }
-  const write = (posterFile = null) => writeStills({ out, plan: layout, frames, width: 1920, height: 1080, fps: plan.fps, frameCount: plan.frameCount, round, stillsOnly, path: "type", posterFile });
-  return { layout, frames, stills: write(), write };
+  // Every stills set carries the storyboard (references/studio.md), drawn from its beat stills.
+  const write = async (posterFile = null) => {
+    const stills = writeStills({ out, plan: layout, frames, width: 1920, height: 1080, fps: plan.fps, frameCount: plan.frameCount, round, stillsOnly, path: "type", posterFile });
+    const beatFiles = stills.index.files.filter((f) => f.kind === "beat").sort((a, b) => a.beat - b.beat).map((f) => path.join(out, f.file));
+    await writeBoard({ out, treatment, beatFiles, env, log });
+    stills.sha256 = addToStills(out, { file: "stills/board.png", kind: "board", frames: layout.beats }, { sha256: (b) => createHash("sha256").update(b).digest("hex") });
+    return stills;
+  };
+  return { layout, frames, stills: await write(), write };
 }
 
 function contrastFrames(plan) {
@@ -444,10 +454,10 @@ export async function make({ briefPath, out, round = 1, stillsOnly = false, view
   let poster;
   let still;
   try {
-    stillsSet = await renderStillsSet({ session, plan, treatment: prep.treatment, out, round, stillsOnly: stillsOnly || !ffmpeg });
+    stillsSet = await renderStillsSet({ session, plan, treatment: prep.treatment, out, round, stillsOnly: stillsOnly || !ffmpeg, env, log });
     log(`stills: ${stillsSet.stills.files.length} files in ${path.join(out, "stills")}`);
     if (stillsOnly) {
-      return { code: EXIT.OK, message: `STILLS_ONLY: look at every file in ${path.join(out, "stills")} (index.json lists them), record the round with look --round ${round}, make the change, then render the film with --round ${round + 1} (no --stills-only)`, plan, stills: stillsSet.stills, egress: session.egress, renderer: session.renderer };
+      return { code: EXIT.OK, message: `STILLS_ONLY: open the storyboard ${path.join(out, "stills", "board.png")} and every file in ${path.join(out, "stills")} (index.json lists them), record the round with look --round ${round}, make the change, then render the film with --round ${round + 1} (no --stills-only)`, plan, stills: stillsSet.stills, egress: session.egress, renderer: session.renderer };
     }
     if (!ffmpeg) {
       return { code: EXIT.BLOCKED_NO_FFMPEG_FOR_VIDEO, message: `BLOCKED_NO_FFMPEG_FOR_VIDEO: ffmpeg is not on PATH; the stills and contact sheet are in ${path.join(out, "stills")}; install ffmpeg for the MP4, preview and poster`, plan };
@@ -496,7 +506,8 @@ export async function make({ briefPath, out, round = 1, stillsOnly = false, view
   const { gate, manifest } = collectAndEvaluate({ out, previewRecords: preview.records, previewFps: preview.rung?.fps, determinism, perf, coverage: pre.coverage, still, extraRules: soundAudit.rules });
   const promoted = promote({ out, gate });
   const loc = (name) => (promoted.withheld ? path.join(out, "withheld", name) : path.join(out, name));
-  if (existsSync(loc("poster.png"))) stillsSet.write(loc("poster.png"));
+  if (existsSync(loc("poster.png"))) await stillsSet.write(loc("poster.png"));
+  if (gate.pass && !promoted.withheld) recordHouse(out, { style: prep.treatment.style, path: "type", format: prep.treatment.format, durationSec: prep.treatment.durationSec });
   const report = formatReport({
     manifest, reason: plan.reason, gate, round, framesViewed: resolveViewed(out, viewed), software: manifest.softwareRenderer, withheld: promoted.withheld,
     outputs: { film: loc("film.mp4"), preview: preview.file ? loc(path.basename(preview.file)) : "(no preview under 3 MB)", poster: loc("poster.png"), still: loc("reduced-motion.png") },
@@ -568,7 +579,7 @@ export async function partial({ mode, briefPath, out, env = process.env, log = (
   const session = await openSession({ plan: prep.plan, fontKeys: prep.fontKeys, runDir: prep.runDir, env, log });
   try {
     if (mode === "stills" || mode === "sheet") {
-      const set = await renderStillsSet({ session, plan: prep.plan, treatment: prep.treatment, out, round: 1, stillsOnly: true });
+      const set = await renderStillsSet({ session, plan: prep.plan, treatment: prep.treatment, out, round: 1, stillsOnly: true, env, log });
       return { code: EXIT.OK, message: `STILLS: ${set.stills.files.length} files in ${path.join(out, "stills")} (the sheet is stills/sheet.png)` };
     }
     const perf = await perfCheck({ session, plan: prep.plan });