@litfamily/litopencode 1.0.30 → 1.0.32

package/skills/lit-typographic-motion/engine/cover/treatment.mjs

@@ -6,10 +6,10 @@
 // aspect and loop, and the title box the contrast and size gates measure. Its text is inert data.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { COVER } from "../constants.mjs";
-import { normalize, restates, TREATMENT_EXIT } from "../treatment.mjs";
+import { COVER, EXIT } from "../constants.mjs";
+import { normUrl, normalize, requestUrls, restates, TREATMENT_EXIT } from "../treatment.mjs";
 
-export const RECIPES = Object.freeze(["painted-light", "weight-tide", "orbit-loop", "own"]);
+export const RECIPES = Object.freeze(["hero-3d", "painted-light", "weight-tide", "orbit-loop", "own"]);
 export const LAYERS = Object.freeze(["slow", "mid", "beat"]);
 
 class Invalid extends Error {
@@ -28,6 +28,20 @@ function text(t, key, { maxSentences } = {}) {
   return value;
 }
 
+// A link in the request names the product: the cover is built from its real logo, images and words,
+// fetched by `render.mjs assets --cover` before the treatment, never from the name alone.
+function checkProduct(t) {
+  const urls = requestUrls(t.request);
+  if (!("product" in t)) {
+    need(!urls.length, "product", `missing: the request links ${urls[0]}; fetch its real assets first with render.mjs assets --out <dir> --url <link> --cover, look at them, and set product { name, url } (references/cover.md, Named products)`);
+    return;
+  }
+  need(t.product && typeof t.product === "object" && !Array.isArray(t.product), "product", "must be an object { name, url }");
+  text(t, "product.name");
+  if (urls.length) need(urls.includes(normUrl(t.product.url)), "product.url", `must be the link the request gives (${urls.join(", ")})`);
+  if ("unreachable" in t.product) text(t, "product.unreachable");
+}
+
 /** Validate a cover treatment. Returns { ok: true, cover } with the derived sizes, or { ok: false, field, detail }. */
 export function validateCoverTreatment(t) {
   try {
@@ -38,7 +52,10 @@ export function validateCoverTreatment(t) {
     need(!restates(t.idea, t.request), "idea", "the idea restates the request; say what the loop does");
     need(RECIPES.includes(t.recipe), "recipe", `must be one of ${RECIPES.join(", ")} (references/cover.md)`);
     text(t, "recipeReason", { maxSentences: 2 });
+    text(t, "hero", { maxSentences: 2 });
+    text(t, "beat", { maxSentences: 2 });
     text(t, "brandWord");
+    checkProduct(t);
     need(words(t.brandWord) <= 3, "brandWord", "is the name, set once: at most three words");
     if ("motto" in t) {
       need(t.motto && typeof t.motto === "object", "motto", "must be { text, source: user | project, from? }");
@@ -103,6 +120,16 @@ export function loadCoverTreatment(out) {
   if (parsed?.mode !== "cover") throw fail("mode", "this treatment is a film; render it with `render.mjs stage` or `render.mjs film` (references/treatment.md). A cover sets mode: cover");
   const result = validateCoverTreatment(parsed);
   if (!result.ok) throw fail(result.field, result.detail);
+  const product = result.cover.product;
+  if (product?.unreachable) throw Object.assign(new Error(`BLOCKED_ASSET_MISSING (${EXIT.BLOCKED_ASSET_MISSING}): ${product.name}'s real assets could not be reached (${product.unreachable}); ask the user for its logo or README images, put them in ${path.join(out, "cover", "assets")} and list them in assets.json with source user`), { exitCode: EXIT.BLOCKED_ASSET_MISSING });
+  if (product) {
+    const file = path.join(out, "product.json");
+    if (!existsSync(file)) throw fail("product", `no ${file}: run render.mjs assets --out ${out} --url ${product.url} --cover first`);
+    let fetched = [];
+    try { fetched = JSON.parse(readFileSync(file, "utf8"))?.product?.assets ?? []; } catch (error) { throw fail("product", `${file} is not valid JSON (${error.message}); run render.mjs assets --out ${out} --url ${product.url} --cover again`); }
+    const astray = fetched.filter((asset) => !String(asset?.path ?? "").startsWith("cover/assets/"));
+    if (astray.length) throw fail("product", `${astray[0].path} sits outside cover/assets/, where the cover page cannot load it; run render.mjs assets --out ${out} --url ${product.url} --cover again`);
+  }
   const first = path.join(out, ".run", "treatment-first.json");
   mkdirSync(path.dirname(first), { recursive: true });
   if (!existsSync(first)) writeFileSync(first, JSON.stringify(parsed, null, 2) + "\n");

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

@@ -0,0 +1,54 @@
+// How full a rendered frame is. `busyShare` reads the share of 48 px cells that carry anything
+// (DEAD-AIR) and `regionFill` reads it per region of a 4 x 3 grid (RICH-FILL). A dense reference
+// frame (a full dashboard) measured 0.57 or more in every region; films with an empty half measured
+// 0.00-0.10 there. Opaque RGBA frames in, 0..1 shares out; pure, so the gate tests drive it directly.
+export const FILL_GRID = Object.freeze({ cols: 4, rows: 3 });
+
+const luma8 = (p, o) => Math.round(0.299 * p[o] + 0.587 * p[o + 1] + 0.114 * p[o + 2]);
+
+// A cell is busy when its luma varies (sd > 6) or its mean sits more than 16 levels off the frame's
+// ground, the most common luma smoothed over +-3 levels. Sampled on a 3 px lattice.
+export function busyShare(rgba, width, height, { cell = 48, step = 3 } = {}) {
+  const hist = new Uint32Array(256);
+  for (let y = 0; y < height; y += step) for (let x = 0; x < width; x += step) hist[luma8(rgba, (y * width + x) * 4)] += 1;
+  let ground = 0;
+  let best = -1;
+  for (let i = 0; i < 256; i++) {
+    let s = 0;
+    for (let k = Math.max(0, i - 3); k <= Math.min(255, i + 3); k++) s += hist[k];
+    if (s > best) [best, ground] = [s, i];
+  }
+  let busy = 0;
+  let cells = 0;
+  for (let cy = 0; cy + cell <= height; cy += cell) {
+    for (let cx = 0; cx + cell <= width; cx += cell) {
+      let sum = 0, sumSq = 0, n = 0;
+      for (let y = cy; y < cy + cell; y += step) for (let x = cx; x < cx + cell; x += step) {
+        const l = luma8(rgba, (y * width + x) * 4);
+        sum += l; sumSq += l * l; n += 1;
+      }
+      const mean = sum / n;
+      if (Math.sqrt(Math.max(0, sumSq / n - mean * mean)) > 6 || Math.abs(mean - ground) > 16) busy += 1;
+      cells += 1;
+    }
+  }
+  return cells ? busy / cells : 0;
+}
+
+// The busyShare of each region of the FILL_GRID, row by row.
+export function regionFill(rgba, width, height) {
+  const out = [];
+  const rw = Math.floor(width / FILL_GRID.cols);
+  const rh = Math.floor(height / FILL_GRID.rows);
+  for (let r = 0; r < FILL_GRID.rows; r++) {
+    for (let c = 0; c < FILL_GRID.cols; c++) {
+      const sub = new Uint8Array(rw * rh * 4);
+      for (let y = 0; y < rh; y++) {
+        const from = ((r * rh + y) * width + c * rw) * 4;
+        sub.set(rgba.subarray(from, from + rw * 4), y * rw * 4);
+      }
+      out.push(busyShare(sub, rw, rh));
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,118 @@
+// `render.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
+// can see 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` puts 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 "./constants.mjs";
+import { areaResize, decodePng, encodePng } from "./png.mjs";
+import { scaffoldHtml } from "./scaffold.mjs";
+import { tile } 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 of each 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) }));
+  const colours = [["ground", "ground"], ["ink", "copy"], ["signal", "signal"], ["muted", "grid"]];
+  return {
+    // A calibration sheet, not a film: the same simple demo in every style, so the styles compare.
+    request: `render a 12 s${vertical} minimal 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: "A style sheet is four unrelated pictures.", turn: "The dot crosses its path and shows the four screens are one system.", beat: 2, payoff: "The grid settles and the house reads as one piece." },
+    protagonist: { name: "the dot", kind: "object", look: "a small round dot in the signal colour, a twentieth of the frame high", acts: [{ beat: 0, action: "waits inside the ring" }, { beat: 1, action: "stands beside the bars" }, { beat: 2, action: "travels its path" }, { beat: 3, action: "settles into 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 },
+    palette: colours.map(([key, role]) => ({ hex: style.palette[key], role })),
+    sound: { mode: "generated", plan: "The style's own bed with a hit on the cuts and a closing cadence.", palette: style.beds[0].palette, key: style.beds[0].key, tempo: style.beds[0].tempo },
+    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]}`);
+}
+
+const toRgba = (image) => {
+  if (image.channels === 4) return image.pixels;
+  const out = Buffer.alloc(image.width * image.height * 4);
+  for (let i = 0, j = 0; i < image.pixels.length; i += image.channels, j += 4) { out[j] = image.pixels[i]; out[j + 1] = image.pixels[i + 1]; out[j + 2] = image.pixels[i + 2]; out[j + 3] = 255; }
+  return out;
+};
+
+// Renders the gallery: a board round per style, then one sheet of the four boards. `render` is
+// renderStage; it is passed in so the gallery stays testable without a browser.
+export async function stylesCommand(out, { format = "16:9", render, log = () => {} }) {
+  if (!["16:9", "9:16"].includes(format)) throw Object.assign(new Error("--format is 16:9 or 9:16"), { exitCode: 2 });
+  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 result = await render(dir, { round: 1, stillsOnly: true });
+    const failed = result.board.failed.map((rule) => rule.id);
+    verdicts.push({ id, pass: failed.length === 0, text: `${id}: ${failed.length ? `board check FAIL (${failed.join(", ")})` : "board check PASS"}` });
+    boards.push(decodePng(readFileSync(path.join(dir, "stills", "board.png"))));
+  }
+  const images = boards.map((board) => areaResize(toRgba(board), board.width, board.height, 960, 540, 4));
+  const sheet = tile(images, 2, 960, 540, 8);
+  const file = path.join(out, "styles.png");
+  writeFileSync(file, encodePng(sheet.width, sheet.height, sheet.pixels, 4, 6));
+  const failing = verdicts.filter((verdict) => !verdict.pass);
+  return { code: failing.length ? EXIT.GATE_FAIL_QA : EXIT.OK, file, message: `STYLES: ${file}\n${verdicts.map((verdict) => verdict.text).join("\n")}` };
+}

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

@@ -0,0 +1,42 @@
+// The house file: `motion-house.json` beside a film's output folder (the user's working 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 data the validator reads, so the second film starts from the first one's style
+// without anyone having to remember it.
+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 = "litopencode.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 there is none or it is 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 sets the house style; later films are appended. A film in a
+// style the request named outright is appended 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/skills/lit-typographic-motion/engine/look.mjs

@@ -22,8 +22,14 @@ export const LOOK_QUESTIONS = Object.freeze([
   "Is any element on screen without a job in its beat?",
   "Could every copy line be pasted unchanged into a film about a different subject?"
 ]);
+// A stage film is also asked whether it is as full as its register asks and whether its turn lands.
+export const STAGE_LOOK_QUESTIONS = Object.freeze([
+  ...LOOK_QUESTIONS,
+  "Is the film rich enough for its register (rich: layered, every region of the frame working; minimal: a few elements, none idle)?",
+  "Does the turn land: at the turn shot, does what the film set up visibly break and change, so a stranger would notice it?"
+]);
 // A "no" here means another round; for the others a "yes" does (Q7: a nameable gap).
-const noMeansRevise = new Set([1, 2, 3, 5, 6]);
+const noMeansRevise = new Set([1, 2, 3, 5, 6, 10, 11]);
 // A cover is looked at for motion, the seam and damage, never for beats (references/cover.md).
 export const COVER_LOOK_QUESTIONS = Object.freeze([
   "Is something moving in every half-second window (the sheet's plot never lies flat on the red dashes)?",
@@ -33,9 +39,10 @@ export const COVER_LOOK_QUESTIONS = Object.freeze([
   "Are all three speed layers visible: a slow perpetual layer, a mid swell, beat events?",
   "Does anything read as a slide, a card swap, a title fade or an end card, or does light wash in place instead of travelling as an edge?",
   "Is any glyph, glint or glow damaged: a colour block, a dark disc, a visible box?",
-  "Would a skilled motion designer add or remove something? Name it."
+  "Would a skilled motion designer add or remove something? Name it.",
+  "Does the hero act its beat once per loop: one clear action, at the beat's time, not a wobble?"
 ]);
-const coverNoMeansRevise = new Set([1, 2, 3, 4, 5]);
+const coverNoMeansRevise = new Set([1, 2, 3, 4, 5, 9]);
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const shaFile = (file) => sha256(readFileSync(file));
 const readJson = (file, fallback = null) => (existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : fallback);
@@ -107,7 +114,8 @@ export function recordLook(out, round, answersFile) {
   const set = currentSet(out);
   if (set.stills.round !== round) throw new LookError(`the latest stills set was rendered with --round ${set.stills.round}; look at the set of round ${round}`);
   const cover = set.kind === "cover";
-  const questions = cover ? COVER_LOOK_QUESTIONS : LOOK_QUESTIONS;
+  const stageFilm = !cover && readJson(path.join(out, "treatment.json"))?.path === "stage";
+  const questions = cover ? COVER_LOOK_QUESTIONS : stageFilm ? STAGE_LOOK_QUESTIONS : LOOK_QUESTIONS;
   const blocked = input.blocked === "no-vision-tool";
   const viewed = [...new Set([...(Array.isArray(input.viewed) ? input.viewed : []), ...(Array.isArray(input.answers) ? input.answers.map((answer) => answer?.frame).filter((frame) => frame && frame !== "sound-cues.json") : [])])];
   const unknown = viewed.filter((frame) => typeof frame !== "string" || !set.files.includes(frame.replace(/^\.\//u, "")));
@@ -146,9 +154,10 @@ export function recordLook(out, round, answersFile) {
   return entry;
 }
 
-// Every image the last round must have viewed: poster, contact sheet, every beat midpoint and strip.
+// Every image the last round must have viewed: poster, contact sheet, storyboard, every beat midpoint
+// and strip.
 export function requiredFrames(set) {
-  return set.files.filter((file) => /(?:^|\/)poster\.png$|sheet\/contact\.png$|stills\/beat-\d+-mid\.png$|stills\/cut-\d+-strip\.png$/u.test(file));
+  return set.files.filter((file) => /(?:^|\/)poster\.png$|sheet\/contact\.png$|stills\/board\.png$|stills\/beat-\d+-mid\.png$|stills\/cut-\d+-strip\.png$/u.test(file));
 }
 
 function imageReads(out) {
@@ -207,14 +216,62 @@ export function coverDoneState(out) {
   return result("DONE", 0);
 }
 
+// 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. The full render waits for the user.
+function previewDone(out, { reasons, labels, result }) {
+  const stills = readJson(path.join(out, "stills", "stills.json"));
+  if (!stills) { reasons.push("no board yet: render with `stage --stills-only`"); return result("NOT DONE", 1); }
+  if (!stills.files.some((entry) => entry.kind === "board")) reasons.push("the stills set has no storyboard (stills/board.png); render with `stage --stills-only` again");
+  const check = readJson(path.join(out, "stills", "check.json"));
+  if (check) {
+    const failed = check.rules.filter((rule) => rule.status === "FAIL").map((rule) => rule.id);
+    if (failed.length) reasons.push(`the board check failed (${failed.join(", ")}); fix the page and render the board again`);
+  } else reasons.push("the board check result (stills/check.json) is missing");
+  const rounds = readJson(path.join(out, "look.json"), { rounds: [] }).rounds;
+  const last = rounds.at(-1);
+  if (!last) reasons.push("no look round on the board: open the storyboard and the stills with the read tool and record round 1");
+  else {
+    if (last.manifestSha256 !== shaFile(path.join(out, "stills", "stills.json"))) reasons.push("the look round was recorded before the latest board; look again and record it");
+    const required = stills.files.filter((entry) => ["board", "sheet", "beat"].includes(entry.kind)).map((entry) => entry.file);
+    const skipped = required.filter((file) => !Object.hasOwn(last.frames ?? {}, file));
+    if (skipped.length && !last.blocked) reasons.push(`the round did not view: ${skipped.join(", ")}`);
+    if (last.host === "opencode" && !last.blocked) {
+      const reads = imageReads(out);
+      const notRead = Object.entries(last.frames ?? {}).filter(([file, sha]) => !reads.some((read) => read.file === file && read.sha256 === sha)).map(([file]) => file);
+      if (notRead.length) reasons.push(`not opened with the read tool: ${notRead.join(", ")}`);
+    }
+  }
+  if (reasons.length) return result("NOT DONE", 1);
+  labels.push(`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`);
+  return last.blocked === "no-vision-tool" ? result("DONE_UNVIEWED", 3) : result("DONE", 0);
+}
+
+// The run a done call means. `given` is the directory named by a path or `--out` (empty or missing: the
+// working directory, which is what an unset or empty shell variable leaves). When that folder holds no
+// treatment.json, the nearest ancestor within three levels that does is the run, so the check also works
+// from the film's stage/ or stills/ folder.
+export function findRunDir(given, cwd = process.cwd()) {
+  const start = path.resolve(cwd, typeof given === "string" && given !== "" ? given : ".");
+  let dir = start;
+  for (let level = 0; level <= 3; level++) {
+    if (existsSync(path.join(dir, "treatment.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
 // Status: DONE (0), NOT DONE (1), DONE_WITH_OPEN_ITEMS (2, round 3 spent), DONE_UNVIEWED (3).
 export function doneState(dir) {
-  const out = path.resolve(dir);
+  const out = findRunDir(dir);
   if (isCoverRun(out)) return coverDoneState(out);
   const reasons = [], open = [];
-  const result = (status, code) => ({ status, code, done: code === 0, reasons, open, downgraded });
+  const labels = [];
+  const result = (status, code) => ({ status, code, done: code === 0, reasons, open, downgraded, labels });
   let treatment = null, downgraded = [];
   try { ({ treatment } = loadTreatment(out)); } catch (error) { reasons.push(error.message); return result("NOT DONE", 1); }
+  if (treatment.preview === true) return previewDone(out, { reasons, labels, result });
   downgraded = downgrades(readJson(path.join(out, ".run", "treatment-first.json")), treatment);
   const manifestFile = path.join(out, "manifest.json");
   const manifest = readJson(manifestFile);

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

@@ -0,0 +1,101 @@
+// Loudness for every generated track: the ITU-R BS.1770-4 meter, the sample peak, a lookahead limiter and
+// the master stage that brings a mix to -16 LUFS under a -2 dBFS ceiling. Pure functions over Float64
+// channels at 48 kHz; the sound bed and the score both end here.
+export const RATE = 48000;
+export const TARGET_LUFS = -16;
+export const PEAK_CEILING_DBFS = -2;
+
+// ITU-R BS.1770-4: K-weighting at 48 kHz, 400 ms blocks with 75 % overlap, -70 LUFS absolute and
+// -10 LU relative gates.
+const shelf = { b: [1.53512485958697, -2.69169618940638, 1.19839281085285], a: [1, -1.69065929318241, 0.73248077421585] };
+const highPass = { b: [1, -2, 1], a: [1, -1.99004745483398, 0.99007225036621] };
+function biquad(input, { b, a }) {
+  const out = new Float64Array(input.length);
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+  for (let i = 0; i < input.length; i++) {
+    const x = input[i];
+    const y = b[0] * x + b[1] * x1 + b[2] * x2 - a[1] * y1 - a[2] * y2;
+    x2 = x1; x1 = x; y2 = y1; y1 = y;
+    out[i] = y;
+  }
+  return out;
+}
+export function integratedLoudness(channels, rate = RATE) {
+  if (rate !== RATE) throw new Error("the loudness meter's K-weighting coefficients are for 48 kHz");
+  const weighted = channels.map((channel) => biquad(biquad(channel, shelf), highPass));
+  const block = Math.round(0.4 * rate), hop = Math.round(0.1 * rate);
+  const blocks = [];
+  for (let start = 0; start + block <= weighted[0].length; start += hop) {
+    let sum = 0;
+    for (const channel of weighted) { let s = 0; for (let i = start; i < start + block; i++) s += channel[i] * channel[i]; sum += s / block; }
+    blocks.push(sum);
+  }
+  const loudness = (z) => -0.691 + 10 * Math.log10(z);
+  const absolute = blocks.filter((z) => loudness(z) > -70);
+  if (absolute.length === 0) return -Infinity;
+  const relativeGate = loudness(absolute.reduce((s, z) => s + z, 0) / absolute.length) - 10;
+  const gated = absolute.filter((z) => loudness(z) > relativeGate);
+  return loudness(gated.reduce((s, z) => s + z, 0) / gated.length);
+}
+
+export const dbfs = (value) => (value > 0 ? 20 * Math.log10(value) : -Infinity);
+export function samplePeakDbfs(channels) {
+  let peak = 0;
+  for (const channel of channels) for (const v of channel) peak = Math.max(peak, Math.abs(v));
+  return dbfs(peak);
+}
+export function wavBytes(pcm, rate = RATE, channels = 2) {
+  const data = Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0); header.writeUInt32LE(36 + data.length, 4); header.write("WAVEfmt ", 8);
+  header.writeUInt32LE(16, 16); header.writeUInt16LE(1, 20); header.writeUInt16LE(channels, 22); header.writeUInt32LE(rate, 24);
+  header.writeUInt32LE(rate * channels * 2, 28); header.writeUInt16LE(channels * 2, 32); header.writeUInt16LE(16, 34); header.write("data", 36); header.writeUInt32LE(data.length, 40);
+  return Buffer.concat([header, data]);
+}
+
+// A lookahead limiter: the gain that keeps every sample under `ceiling` is found 5 ms ahead, so the
+// reduction is fully in place when the peak arrives, then released over 80 ms. Returns new channels.
+export function limit(channels, ceiling, { lookaheadSec = 0.005, releaseSec = 0.08, rate = RATE } = {}) {
+  const n = channels[0].length;
+  const look = Math.max(1, Math.round(lookaheadSec * rate));
+  const need = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    let peak = 0;
+    for (const channel of channels) peak = Math.max(peak, Math.abs(channel[i]));
+    need[i] = peak > ceiling ? ceiling / peak : 1;
+  }
+  // The minimum of the required gain over the next `look` samples (a sliding window, monotone deque).
+  const floor = new Float64Array(n);
+  const deque = [];
+  let head = 0;
+  for (let i = n - 1; i >= 0; i--) {
+    while (deque.length > head && need[deque.at(-1)] >= need[i]) deque.pop();
+    deque.push(i);
+    while (deque[head] > i + look) head++;
+    floor[i] = need[deque[head]];
+  }
+  const release = Math.exp(-1 / (releaseSec * rate));
+  const attack = Math.exp(-1 / (look * 0.5));
+  const gain = new Float64Array(n);
+  let g = 1;
+  for (let i = 0; i < n; i++) {
+    g = floor[i] < g ? attack * g + (1 - attack) * floor[i] : release * g + (1 - release) * floor[i];
+    gain[i] = g;
+  }
+  // The smoothed gain can sit above the required gain for a few samples on the attack; clamp so no sample passes the ceiling.
+  return channels.map((channel) => channel.map((v, i) => v * Math.min(gain[i], need[i])));
+}
+
+// The master stage: gain to -16 LUFS, then the limiter under -2 dBFS, repeated until the limited result
+// sits within 0.1 LU. Returns the final channels, the gain applied before the limiter and the loudness.
+export function masterTo(left, right, { target = TARGET_LUFS, ceilingDbfs = PEAK_CEILING_DBFS } = {}) {
+  const ceiling = 10 ** (ceilingDbfs / 20) * 0.995;
+  let gain = 1, lufs = integratedLoudness([left, right]), out = [left, right];
+  for (let pass = 0; pass < 8 && Number.isFinite(lufs); pass++) {
+    gain *= 10 ** ((target - lufs) / 20);
+    out = limit([left.map((v) => v * gain), right.map((v) => v * gain)], ceiling);
+    lufs = integratedLoudness(out);
+    if (Math.abs(lufs - target) < 0.1) break;
+  }
+  return { left: out[0], right: out[1], gain, lufs };
+}