@litfamily/litopencode 1.0.29 → 1.0.30

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

@@ -0,0 +1,323 @@
+// `render.mjs cover`: one cover round. Treatment (exit 16) -> static scan of cover/ (17, 19) -> the
+// asset list (22 before any capture) -> pre-warm, Chrome and the encoder (10, 14, 15, 21) -> the
+// master browser seeks t = i / N for every frame at 2x, then the title-mask pass -> a fresh browser
+// repeats every frame (G0) -> another fresh browser draws a seeded shuffle of 16 frames, which must
+// match the master within the rasterizer's one-level rounding (18 otherwise: the page keeps state)
+// -> flash audit of the frames as a loop -> img2webp (frame 0 and the frames before the seam at a
+// higher quality), or gifski when libwebp is missing -> the gate on the DECODED file, with G6 and the
+// frame-0 art check -> stills from the decoded file (twelve frames, poster, seam pair, sheet) ->
+// manifest and report. Exit 13 until every gate reaches TARGET; a flash failure withholds the cover.
+// `--window t0,t1` captures and sheets only the frames around a logged defect and never counts as done.
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { COVER, EXIT } from "../constants.mjs";
+import { findChrome, loadPlaywright, which } from "../browser.mjs";
+import { ExcursionDetector, auditCells, countFlashes, flashGeometryFor } from "../flash.mjs";
+import { encodePng } from "../png.mjs";
+import { scanStage, stageSha } from "../stage/scan.mjs";
+import { inspectWarmState, pins, skillRoot } from "../../runtime.mjs";
+import { artCheck, checkAssets } from "./assets.mjs";
+import { CoverPool, capturePass, coverFonts, openCover } from "./capture.mjs";
+import { coverGate, formatCoverReport, framesIn, readRgba, verdicts } from "./gate.mjs";
+import { lumaGrid, meanLumaStep } from "./image.mjs";
+import { composeSheet } from "./sheet.mjs";
+import { loadCoverTreatment } from "./treatment.mjs";
+
+export const SHEET_TILES = 12;
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const stop = (code, name, detail) => Object.assign(new Error(`${name} (${code}): ${detail}`), { exitCode: code });
+const pad4 = (n) => String(n).padStart(4, "0");
+
+/** How long img2webp shows each frame: whole milliseconds. */
+export const frameMs = (fps) => Math.round(1000 / fps);
+/** Frame i of N shows loop time t = i / N; t = 1 is never drawn (it would repeat frame 0 at the seam). */
+export const loopTimes = (frames) => Array.from({ length: frames }, (_, i) => [i, i / frames]);
+
+/** The encoder this host offers a cover: img2webp (decoded with dwebp), else gifski (decoded with ffmpeg), else none. */
+export function coverEncoder(env = process.env) {
+  if (which("img2webp", env) && which("dwebp", env)) return { name: "img2webp", decoder: "dwebp" };
+  if (which("gifski", env) && which("ffmpeg", env)) return { name: "gifski", decoder: "ffmpeg" };
+  return { name: "none", fix: "install libwebp (img2webp and dwebp), or gifski with ffmpeg; a cover is never an MP4" };
+}
+
+/** img2webp arguments: lossy, loop forever, every frame `-d` ms, frame 0 and the last `edgeFrames` at `edgeQ`. */
+export function img2webpArgs({ files, fps, encode, out }) {
+  const args = ["-loop", "0", "-lossy", "-q", String(encode.q), "-m", String(encode.method)];
+  files.forEach((file, i) => args.push("-d", String(frameMs(fps)), "-q", String(i === 0 || i >= files.length - encode.edgeFrames ? encode.edgeQ : encode.q), file));
+  return [...args, "-o", out];
+}
+
+/** Encode the frames into `<out>/cover.webp` (or cover.gif); returns { file, encoder }. */
+export function encodeCover({ files, fps, encode, out, env = process.env }) {
+  const encoder = coverEncoder(env);
+  if (encoder.name === "none") throw stop(EXIT.BLOCKED_NO_COVER_ENCODER, "BLOCKED_NO_COVER_ENCODER", `no cover encoder on PATH; fix: ${encoder.fix}`);
+  const file = path.join(out, encoder.name === "img2webp" ? "cover.webp" : "cover.gif");
+  const args = encoder.name === "img2webp" ? img2webpArgs({ files, fps, encode, out: file }) : ["--fps", String(fps), "--quality", "90", "--repeat", "0", "-o", file, ...files];
+  const run = spawnSync(which(encoder.name, env), args, { encoding: "utf8", timeout: 1_200_000, maxBuffer: 64 * 1024 * 1024 });
+  if (run.status !== 0) throw new Error(`${encoder.name} failed: ${(run.stderr || run.error?.message || "").trim().split(/\r?\n/u).at(-1)}`);
+  return { file, encoder: encoder.name };
+}
+
+/** A seeded shuffle (mulberry32, as the loop kit) of `count` distinct frame indices. */
+export function seekOrder(frames, seed, count = COVER.seekFrames) {
+  let state = seed >>> 0;
+  const next = () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let z = state;
+    z = Math.imul(z ^ (z >>> 15), z | 1);
+    z ^= z + Math.imul(z ^ (z >>> 7), z | 61);
+    return ((z ^ (z >>> 14)) >>> 0) / 4294967296;
+  };
+  const order = Array.from({ length: frames }, (_, i) => i);
+  for (let i = frames - 1; i > 0; i--) {
+    const j = Math.floor(next() * (i + 1));
+    [order[i], order[j]] = [order[j], order[i]];
+  }
+  return order.slice(0, Math.min(count, frames));
+}
+
+/** The largest per-channel difference between two same-size frames on disk. */
+export function maxLevelDiff(fileA, fileB) {
+  const a = readRgba(fileA), b = readRgba(fileB);
+  if (a.width !== b.width || a.height !== b.height) return 255;
+  let worst = 0;
+  for (let i = 0; i < a.rgba.length; i++) worst = Math.max(worst, Math.abs(a.rgba[i] - b.rgba[i]));
+  return worst;
+}
+
+/** The film gate's flash detector (WCAG 2.3.1) over the cover frames as a loop. */
+export function flashAudit(files, fps) {
+  const first = readRgba(files[0]);
+  const geometry = flashGeometryFor(first.width, first.height);
+  const detector = new ExcursionDetector(geometry);
+  const records = [];
+  for (let i = 0; i < files.length + fps; i++) {
+    const frame = i === 0 ? first : readRgba(files[i % files.length]);
+    const record = detector.push(auditCells(frame.rgba, frame.width, frame.height, geometry));
+    if (i < files.length) records.push(record);
+    else for (const key of ["up", "down", "redUp", "redDown"]) records[i % files.length][key] ||= record[key];
+  }
+  return countFlashes(records, fps, true);
+}
+
+// Everything a cover round checks before a browser starts.
+function prepare(out) {
+  const cover = loadCoverTreatment(out);
+  const coverDir = path.join(out, "cover");
+  if (!existsSync(path.join(coverDir, "index.html"))) throw stop(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `no cover page at ${path.join(coverDir, "index.html")}; write it first (references/cover.md)`);
+  const scan = scanStage(coverDir);
+  const assets = checkAssets({ out, treatment: cover, rasters: scan.rasters });
+  const state = inspectWarmState();
+  if (state.blocked) throw stop(state.blocked.exit, state.blocked.name, `${state.blocked.detail}; fix: ${state.fix}`);
+  const chrome = findChrome();
+  if (!chrome.path) throw stop(EXIT.BLOCKED_NO_CHROME, "BLOCKED_NO_CHROME", `${chrome.missing}; fix: install Chrome or set CHROME_PATH`);
+  return { cover, coverDir, assets, state, chromePath: chrome.path, fonts: coverFonts(skillRoot, state, pins) };
+}
+
+// One browser for one pass; the profile lives under .run/cover/ and goes with the pass.
+async function withBrowser(chromium, context, profile, body) {
+  rmSync(profile, { recursive: true, force: true });
+  mkdirSync(profile, { recursive: true });
+  const browser = await openCover(chromium, { chromePath: context.chromePath, profile, coverDir: context.coverDir, page: context.cover.page, scale: COVER.captureScale, fonts: context.fonts });
+  try { return await body(browser); } finally { await browser.close(); rmSync(profile, { recursive: true, force: true }); }
+}
+
+/** The decoded frame on show `ms` into the loop. */
+export function frameAt(durations, ms) {
+  let end = 0;
+  for (let i = 0; i < durations.length; i++) { end += durations[i]; if (ms < end) return i; }
+  return durations.length - 1;
+}
+
+// The stills of a finished cover, taken from the decoded file, and their index stills/stills.json.
+function writeCoverStills(out, { round, gate, cover }) {
+  const dir = path.join(out, "stills");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const { width, height, durations, kept } = gate;
+  const total = durations.reduce((a, b) => a + b, 0);
+  const files = [];
+  const save = (name, w, h, pixels, kind, extra) => {
+    const bytes = encodePng(w, h, pixels, 4, 6);
+    writeFileSync(path.join(dir, name), bytes);
+    files.push({ file: `stills/${name}`, kind, sha256: sha256(bytes), ...extra });
+  };
+  const tiles = [];
+  for (let k = 0; k < SHEET_TILES; k++) {
+    const at = k / SHEET_TILES, index = frameAt(durations, at * total);
+    save(`frame-${String(k).padStart(2, "0")}.png`, width, height, kept.get(index), "frame", { t: Number((at * total / 1000).toFixed(3)), decodedFrame: index });
+    tiles.push({ rgba: kept.get(index), width, height, at });
+  }
+  const last = durations.length - 1;
+  save("poster.png", width, height, kept.get(0), "poster", { decodedFrame: 0 });
+  const pair = Buffer.alloc(width * 2 * height * 4);
+  for (let y = 0; y < height; y++) {
+    kept.get(last).copy(pair, y * width * 8, y * width * 4, (y + 1) * width * 4);
+    kept.get(0).copy(pair, y * width * 8 + width * 4, y * width * 4, (y + 1) * width * 4);
+  }
+  save("seam.png", width * 2, height, pair, "seam", { decodedFrames: [last, 0] });
+  const sheet = composeSheet({ tiles, steps: gate.steps, medianD: gate.medianD });
+  save("sheet.png", sheet.width, sheet.height, sheet.pixels, "sheet", { tiles: tiles.map((tile) => Number(tile.at.toFixed(4))) });
+  const index = { schemaVersion: 1, path: "cover", mode: "cover", round, size: [width, height], fps: cover.fps, durationSec: total / 1000, files, gate: { pass: gate.pass, target: gate.target } };
+  writeFileSync(path.join(dir, "stills.json"), JSON.stringify(index, null, 2) + "\n");
+  return { index, sha256: sha256(readFileSync(path.join(dir, "stills.json"))) };
+}
+
+// Moves the previous round's cover files aside, so a new round never mixes with them.
+function clearCoverExports(out, runDir) {
+  const previous = path.join(runDir, "previous-round");
+  rmSync(previous, { recursive: true, force: true });
+  for (const name of ["cover.webp", "cover.gif", "poster.png", "gate-report.txt", "manifest.json"]) {
+    for (const source of [path.join(out, name), path.join(out, "withheld", name)]) {
+      if (!existsSync(source)) continue;
+      mkdirSync(previous, { recursive: true });
+      renameSync(source, path.join(previous, `${path.basename(path.dirname(source))}-${name}`));
+    }
+  }
+  rmSync(path.join(out, "withheld"), { recursive: true, force: true });
+}
+
+/** One full cover round. Returns { code, report, manifest }: 0 at TARGET, 13 otherwise. */
+export async function renderCover(out, { round = 1, log = () => {} } = {}) {
+  const context = prepare(out);
+  const { cover } = context;
+  const encoder = coverEncoder();
+  if (encoder.name === "none") throw stop(EXIT.BLOCKED_NO_COVER_ENCODER, "BLOCKED_NO_COVER_ENCODER", `no cover encoder on PATH; fix: ${encoder.fix}`);
+  const runDir = path.join(out, ".run");
+  const work = path.join(runDir, "cover");
+  rmSync(work, { recursive: true, force: true });
+  const dirs = { frames: path.join(work, "frames"), masks: path.join(work, "masks"), replay: path.join(work, "replay"), seek: path.join(work, "seek") };
+  for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true });
+  const times = loopTimes(cover.frames);
+  const size = cover.size;
+  const expected = `${cover.page[0] * COVER.captureScale}x${cover.page[1] * COVER.captureScale}`;
+  const order = seekOrder(times.length, cover.seed);
+  const chromium = await loadPlaywright(context.state.nodeDir);
+  const pool = new CoverPool();
+  const began = performance.now();
+  let master, replay, sought;
+  try {
+    await withBrowser(chromium, context, path.join(work, "cm"), async (browser) => {
+      log(`cover: master pass, ${times.length} frames at ${expected}`);
+      master = await capturePass({ browser, pool, times, dir: dirs.frames, size, expected });
+      await capturePass({ browser, pool, times, dir: dirs.masks, prefix: "m", mask: true, size, expected });
+    });
+    log("cover: replay pass in a fresh browser");
+    replay = await withBrowser(chromium, context, path.join(work, "cr"), (browser) => capturePass({ browser, pool, times, dir: dirs.replay, size, expected }));
+    log(`cover: seek-order pass, ${order.length} frames`);
+    sought = await withBrowser(chromium, context, path.join(work, "cs"), (browser) => capturePass({ browser, pool, times: order.map((i) => times[i]), dir: dirs.seek, prefix: "s", size, expected }));
+  } finally {
+    await pool.close();
+  }
+  const captureSec = (performance.now() - began) / 1000;
+  const ms = frameMs(cover.fps);
+  const differing = times.filter(([i]) => master.get(i) !== replay.get(i));
+  if (differing.length) throw stop(EXIT.STAGE_NONDETERMINISTIC, "STAGE_NONDETERMINISTIC", `a fresh capture differs at ${differing.slice(0, 4).map(([i, t]) => `frame ${i} (t = ${t.toFixed(4)})`).join(", ")}${differing.length > 4 ? ` and ${differing.length - 4} more` : ""}; draw every pixel from t and LitLoop.rng(seed)`);
+  // An element whose opacity and transform change together can rasterize one level apart depending
+  // on what was painted before it; state kept between frames differs by far more.
+  let oneLevel = 0;
+  for (let k = 0; k < order.length; k++) {
+    const i = order[k];
+    if (sought.get(i) === master.get(i)) continue;
+    const worst = maxLevelDiff(path.join(dirs.frames, `f${pad4(i)}.png`), path.join(dirs.seek, `s${pad4(i)}.png`));
+    if (worst <= COVER.seekLevels) { oneLevel += 1; continue; }
+    throw stop(EXIT.STAGE_NONDETERMINISTIC, "STAGE_NONDETERMINISTIC", `frame ${i} (t = ${((i * ms) / 1000).toFixed(3)} s) differs by up to ${worst} levels when sought out of order (a fresh page drew it ${k ? `after frame ${order[k - 1]}` : "first"}); the page keeps state between frames: clear every canvas and draw each frame from t alone`);
+  }
+  const files = framesIn(dirs.frames, "f");
+  const flash = flashAudit(files, cover.fps);
+  const runOut = path.join(work, "encoded");
+  mkdirSync(runOut, { recursive: true });
+  const encoded = encodeCover({ files, fps: cover.fps, encode: cover.encode, out: runOut });
+  const planned = times.length * ms;
+  const wanted = Array.from({ length: SHEET_TILES }, (_, k) => (k / SHEET_TILES) * planned);
+  let elapsed = 0;
+  const keep = (i, duration) => {
+    const start = elapsed;
+    elapsed += duration;
+    return i === 0 || start + duration >= planned || wanted.some((x) => x >= start && x < start + duration);
+  };
+  const painted = cover.title.kind === "painted" ? context.assets.find((asset) => asset.role === "base-art" && asset.title) : null;
+  const gate = coverGate(encoded.file, { frames: dirs.frames, replay: dirs.replay, masks: dirs.masks, title: cover.title.box, glyph: { exempt: painted ? `painted into the base art ${painted.path}` : null }, fps: cover.fps, keep });
+  gate.gates.SEEK = { pass: true, sampled: order.length, identical: order.length - oneLevel, oneLevel };
+  for (const asset of context.assets.filter((entry) => entry.role === "base-art")) {
+    let art = null;
+    try { art = readRgba(path.join(out, asset.path)); } catch { art = null; }
+    const check = art ? artCheck({ frame0: gate.kept.get(0), width: gate.width, height: gate.height, art, box: asset.box, checkBox: asset.checkBox }) : null;
+    gate.gates.ART = check ? { pass: check.pass, ssim: check.ssim, checked: check.checked.join(",") } : { pass: false, reason: `${asset.path} is not a PNG the gate can compare with frame 0` };
+  }
+  gate.gates.FLASH = { pass: flash.pass, general: flash.general, red: flash.red };
+  Object.assign(gate, verdicts(gate.gates));
+  clearCoverExports(out, runDir);
+  const delivered = path.join(out, path.basename(encoded.file));
+  renameSync(encoded.file, delivered);
+  const stills = writeCoverStills(out, { round, gate, cover });
+  writeFileSync(path.join(out, "poster.png"), readFileSync(path.join(out, "stills", "poster.png")));
+  const report = formatCoverReport(gate, { strict: true });
+  writeFileSync(path.join(out, "gate-report.txt"), report);
+  const manifest = {
+    schemaVersion: 1, mode: "cover", path: "cover", craftRound: round, recipe: cover.recipe,
+    page: cover.page, size, scale: COVER.captureScale, fps: cover.fps, frames: times.length, frameMs: ms, seed: cover.seed,
+    encoder: encoded.encoder, encode: cover.encode, file: path.basename(delivered), bytes: statSync(delivered).size, captureSec: Number(captureSec.toFixed(1)),
+    treatmentSha256: sha256(readFileSync(path.join(out, "treatment.json"))), coverSha256: stageSha(context.coverDir), stillsSha256: stills.sha256,
+    gate: { pass: gate.pass, target: gate.target, medianD: gate.medianD, movingFrac: gate.movingFrac, longestStillSec: gate.longestStillSec, spike: gate.spike, seamLocal: gate.seamLocal, gates: gate.gates },
+    generatedAt: new Date().toISOString()
+  };
+  writeFileSync(path.join(out, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  if (!flash.pass) {
+    mkdirSync(path.join(out, "withheld"), { recursive: true });
+    renameSync(delivered, path.join(out, "withheld", path.basename(delivered)));
+    rmSync(path.join(out, "poster.png"), { force: true });
+  }
+  const failing = Object.entries(gate.gates).filter(([, g]) => g.pass === false).map(([name]) => name);
+  const short = Object.entries(gate.gates).filter(([, g]) => g.pass !== false && g.target === false).map(([name]) => name);
+  const summary = `cover: ${path.basename(delivered)} ${manifest.bytes} bytes, ${times.length} frames at ${cover.fps} fps, ${size[0]}x${size[1]} from ${expected} captures in ${captureSec.toFixed(0)} s; stills and sheet in ${path.join(out, "stills")}`;
+  if (gate.target) return { code: EXIT.OK, report: `${report}${summary}\n`, manifest };
+  const why = `GATE_FAIL_QA (13): ${[failing.length ? `${failing.join(", ")} fail` : "", short.length ? `${short.join(", ")} miss the cover TARGET` : ""].filter(Boolean).join("; ")}${flash.pass ? "" : "; the flash audit failed, so the cover is withheld"}`;
+  return { code: EXIT.GATE_FAIL_QA, report: `${report}${summary}\n${why}\n`, manifest };
+}
+
+/**
+ * `--window t0,t1` (seconds into the loop): capture only the frames from t0 - 0.5 s to t1 + 0.5 s
+ * (wrapping at the seam) in a fresh page, before encoding, and sheet them with the span shaded. It
+ * writes only windows/round-N/<t0>-<t1>/; the stills, the cover, the report and the manifest stay
+ * as they were, so a window render never counts as done.
+ */
+export async function renderCoverWindow(out, { round = 1, window: [t0, t1], log = () => {} } = {}) {
+  const context = prepare(out);
+  const { cover } = context;
+  const ms = frameMs(cover.fps);
+  const loopSec = (cover.frames * ms) / 1000;
+  if (!(Number.isFinite(t0) && Number.isFinite(t1) && t0 >= 0 && t1 >= t0 && t1 <= loopSec)) throw stop(2, "USAGE", `--window takes t0,t1 in seconds with 0 <= t0 <= t1 <= ${loopSec.toFixed(3)}`);
+  const from = t0 - COVER.windowPadSec, to = t1 + COVER.windowPadSec;
+  const picks = [];
+  for (let i = 0; i < cover.frames; i++) for (const lap of [-1, 0, 1]) {
+    const t = (i * ms) / 1000 + lap * loopSec;
+    if (t >= from - 1e-9 && t <= to + 1e-9) picks.push({ index: i, t: Number(t.toFixed(3)) });
+  }
+  picks.sort((a, b) => a.t - b.t);
+  const dir = path.join(out, "windows", `round-${round}`, `${t0.toFixed(3)}-${t1.toFixed(3)}`);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const expected = `${cover.page[0] * COVER.captureScale}x${cover.page[1] * COVER.captureScale}`;
+  const chromium = await loadPlaywright(context.state.nodeDir);
+  const pool = new CoverPool();
+  try {
+    log(`cover window: ${picks.length} frames from ${from.toFixed(3)} to ${to.toFixed(3)} s`);
+    await withBrowser(chromium, context, path.join(out, ".run", "cover-window"), (browser) => capturePass({ browser, pool, times: [...new Set(picks.map((p) => p.index))].map((i) => [i, i / cover.frames]), dir, size: cover.size, expected }));
+  } finally {
+    await pool.close();
+  }
+  const frames = picks.map((p) => readRgba(path.join(dir, `f${pad4(p.index)}.png`)));
+  const lumas = frames.map((f) => lumaGrid(f.rgba, f.width, f.height).luma);
+  const steps = lumas.slice(1).map((l, k) => meanLumaStep(l, lumas[k]));
+  const medianD = steps.length ? [...steps].sort((a, b) => a - b)[steps.length >> 1] : 0;
+  const count = Math.min(SHEET_TILES, picks.length);
+  const tiles = Array.from({ length: count }, (_, k) => Math.round((k * (picks.length - 1)) / Math.max(1, count - 1))).map((j) => ({ ...frames[j], at: (picks[j].t - from) / (to - from) }));
+  const sheet = composeSheet({ tiles, steps, medianD, marks: [{ from: (t0 - from) / (to - from), to: (t1 - from) / (to - from) }] });
+  writeFileSync(path.join(dir, "sheet.png"), encodePng(sheet.width, sheet.height, sheet.pixels, 4, 6));
+  writeFileSync(path.join(dir, "window.json"), JSON.stringify({ schemaVersion: 1, round, t0, t1, padSec: COVER.windowPadSec, frames: picks, tiles: tiles.map((tile) => Number((from + tile.at * (to - from)).toFixed(3))), note: "frames before encoding; a window render never counts as done" }, null, 2) + "\n");
+  return { code: EXIT.OK, report: `WINDOW round ${round}: ${picks.length} frames from ${from.toFixed(3)} to ${to.toFixed(3)} s; sheet: ${path.join(dir, "sheet.png")}\na window render never counts as done: fix the cause, then render the full cover\n` };
+}

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

@@ -0,0 +1,65 @@
+// The cover's review picture: twelve decoded frames (4 x 3) above a plot of every grid step's luma
+// change over the whole loop. The plot shows what single stills cannot: a hold is a flat run on the
+// red dashed still line, an encoder pop is a regular spike, a reset is a spike at the right end, the
+// green dotted line is the median. White ticks mark where each tile sits in the loop, and amber
+// shading marks a span (a logged defect, a re-rendered window). It is drawn in plain RGBA like the
+// film contact sheet, with no browser, so the same frames always give the same picture.
+import { COVER } from "../constants.mjs";
+import { lanczosResize } from "./image.mjs";
+
+const GAP = 8, PLOT_H = 170, COLS = 4;
+const INK = Object.freeze({ ground: [8, 11, 16], plot: [17, 22, 29], line: [255, 122, 70], still: [190, 60, 60], median: [90, 170, 130], tick: [220, 225, 232], mark: [255, 176, 46] });
+
+function canvas(width, height, fill) {
+  const pixels = Buffer.alloc(width * height * 4);
+  for (let i = 0; i < pixels.length; i += 4) { pixels[i] = fill[0]; pixels[i + 1] = fill[1]; pixels[i + 2] = fill[2]; pixels[i + 3] = 255; }
+  return { width, height, pixels };
+}
+function dot(img, x, y, color, alpha = 1) {
+  x = Math.round(x); y = Math.round(y);
+  if (x < 0 || y < 0 || x >= img.width || y >= img.height) return;
+  const p = (y * img.width + x) * 4;
+  for (let c = 0; c < 3; c++) img.pixels[p + c] = Math.round(img.pixels[p + c] * (1 - alpha) + color[c] * alpha);
+}
+function rect(img, x, y, w, h, color, alpha = 1) {
+  for (let yy = Math.round(y); yy < Math.round(y + h); yy++) for (let xx = Math.round(x); xx < Math.round(x + w); xx++) dot(img, xx, yy, color, alpha);
+}
+function segment(img, x0, y0, x1, y1, color, width = 1.5) {
+  const n = Math.max(1, Math.ceil(Math.hypot(x1 - x0, y1 - y0)));
+  for (let i = 0; i <= n; i++) {
+    const x = x0 + ((x1 - x0) * i) / n, y = y0 + ((y1 - y0) * i) / n;
+    for (let d = -Math.floor(width / 2); d <= Math.floor(width / 2); d++) dot(img, x, y + d, color);
+  }
+}
+function dashed(img, x0, x1, y, color, on, off) {
+  for (let x = x0; x < x1; x += on + off) rect(img, x, y, Math.min(on, x1 - x), 1, color);
+}
+
+/**
+ * Compose the sheet. `tiles` are { rgba, width, height, at } (at = position in the loop, 0..1);
+ * `steps` are the grid steps of the loop; `marks` are { from, to } spans as shares of the loop.
+ * Returns { width, height, pixels } (RGBA).
+ */
+export function composeSheet({ tiles, steps, medianD, marks = [], tileWidth = 400 }) {
+  const tileHeight = Math.round((tileWidth * tiles[0].height) / tiles[0].width);
+  const rows = Math.ceil(tiles.length / COLS);
+  const width = COLS * tileWidth + (COLS + 1) * GAP;
+  const plotTop = rows * (tileHeight + GAP) + 2 * GAP;
+  const img = canvas(width, plotTop + PLOT_H + 2 * GAP, INK.ground);
+  tiles.forEach((tile, k) => {
+    const small = lanczosResize(tile.rgba, tile.width, tile.height, tileWidth, tileHeight);
+    const x0 = GAP + (k % COLS) * (tileWidth + GAP), y0 = GAP + Math.floor(k / COLS) * (tileHeight + GAP);
+    for (let y = 0; y < tileHeight; y++) small.copy(img.pixels, ((y0 + y) * width + x0) * 4, y * tileWidth * 4, (y + 1) * tileWidth * 4);
+  });
+  const plotW = width - 2 * GAP;
+  rect(img, GAP, plotTop, plotW, PLOT_H, INK.plot);
+  for (const mark of marks) rect(img, GAP + mark.from * plotW, plotTop, Math.max(2, (mark.to - mark.from) * plotW), PLOT_H, INK.mark, 0.22);
+  const top = Math.max(0.01, ...steps) * 1.05;
+  const yOf = (v) => plotTop + PLOT_H - 1 - (Math.min(v, top) / top) * (PLOT_H - 2);
+  const xOf = (i) => GAP + (steps.length > 1 ? (i / (steps.length - 1)) * (plotW - 1) : 0);
+  dashed(img, GAP, GAP + plotW, Math.round(yOf(COVER.stillEps)), INK.still, 5, 4);
+  dashed(img, GAP, GAP + plotW, Math.round(yOf(medianD)), INK.median, 2, 3);
+  for (const tile of tiles) rect(img, GAP + tile.at * (plotW - 1), plotTop + PLOT_H - 7, 1, 7, INK.tick);
+  for (let i = 1; i < steps.length; i++) segment(img, xOf(i - 1), yOf(steps[i - 1]), xOf(i), yOf(steps[i]), INK.line);
+  return img;
+}

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

@@ -0,0 +1,110 @@
+// The cover treatment: `treatment.json` with `"mode": "cover"`, validated by every cover render
+// before anything starts (exit 16 names the first field that fails). A cover is not a film, so this
+// is not the film treatment with fields removed: it has no beats, no arc, no copy lines, no ending
+// and no sound. It names one recipe, the one rule copied many times, the three speed layers, the
+// brand word set once (plus at most one motto that the user wrote or the project already uses), the
+// 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";
+
+export const RECIPES = Object.freeze(["painted-light", "weight-tide", "orbit-loop", "own"]);
+export const LAYERS = Object.freeze(["slow", "mid", "beat"]);
+
+class Invalid extends Error {
+  constructor(field, detail) { super(detail); this.field = field; }
+}
+const need = (condition, field, detail) => { if (!condition) throw new Invalid(field, detail); };
+const placeholder = /<[^<>\n]{1,80}>|^\s*(?:todo|tbd|xxx|\.\.\.|…)\s*$/iu;
+const sentences = (text) => String(text).split(/(?<=[.!?。…])\s+/u).map((part) => part.trim()).filter(Boolean).length;
+const words = (text) => String(text).trim().split(/\s+/u).filter(Boolean).length;
+
+function text(t, key, { maxSentences } = {}) {
+  const value = key.split(".").reduce((node, part) => (node && typeof node === "object" ? node[part] : undefined), t);
+  need(typeof value === "string" && value.trim().length > 0, key, value === undefined ? "missing" : "must be a non-empty string");
+  need(!placeholder.test(value), key, `still holds a placeholder (${value})`);
+  if (maxSentences) need(sentences(value) <= maxSentences, key, `at most ${maxSentences} sentence(s)`);
+  return value;
+}
+
+/** Validate a cover treatment. Returns { ok: true, cover } with the derived sizes, or { ok: false, field, detail }. */
+export function validateCoverTreatment(t) {
+  try {
+    need(t && typeof t === "object" && !Array.isArray(t), "treatment", "treatment.json must hold a JSON object");
+    need(t.mode === "cover", "mode", "must be cover for a cover render");
+    text(t, "request");
+    text(t, "idea", { maxSentences: 1 });
+    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, "brandWord");
+    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? }");
+      text(t, "motto.text");
+      need(words(t.motto.text) <= 6, "motto.text", "at most six words");
+      need(["user", "project"].includes(t.motto.source), "motto.source", "must be user (in the request) or project (the project's own line, with from)");
+      if (t.motto.source === "user") need(normalize(t.request).includes(normalize(t.motto.text)), "motto.text", "a user motto appears in the request; a cover never invents a tagline");
+      else text(t, "motto.from");
+    }
+    for (const key of ["copy", "beats", "lines"]) need(!(key in t), key, "a cover has no copy lines and no beats: the brand word is set once and never swapped (references/cover.md)");
+    need(!("sound" in t) || t.sound === "none", "sound", "a cover is silent: leave sound out or set it to none");
+    need(Object.hasOwn(COVER.aspects, t.aspect), "aspect", `must be ${Object.keys(COVER.aspects).join(" or ")}`);
+    need(typeof t.loopSec === "number" && t.loopSec >= COVER.minSec && t.loopSec <= COVER.maxSec, "loopSec", `must be ${COVER.minSec}-${COVER.maxSec} seconds`);
+    need(COVER.fps.includes(t.fps), "fps", `must be one of ${COVER.fps.join(", ")}`);
+    need(t.layers && typeof t.layers === "object", "layers", "missing: name what moves on the slow, mid and beat layers");
+    for (const layer of LAYERS) text(t, `layers.${layer}`, { maxSentences: 2 });
+    need(t.system && typeof t.system === "object", "system", "missing: the one rule, what it is copied onto, and where the offsets come from");
+    for (const part of ["rule", "copies", "offset"]) text(t, `system.${part}`, { maxSentences: 2 });
+    const box = t.title?.box;
+    need(t.title && typeof t.title === "object", "title", "missing: { box: [x, y, w, h] as fractions of the cover, kind: live or painted }");
+    need(Array.isArray(box) && box.length === 4 && box.every((v) => typeof v === "number" && v >= 0 && v <= 1), "title.box", "must be [x, y, w, h], each a fraction of the cover");
+    need(box[2] > 0 && box[3] > 0 && box[0] + box[2] <= 1 + 1e-9 && box[1] + box[3] <= 1 + 1e-9, "title.box", "must lie inside the cover");
+    need(["live", "painted"].includes(t.title.kind), "title.kind", "must be live (set as text) or painted (part of the base art)");
+    if ("palette" in t) {
+      need(Array.isArray(t.palette) && t.palette.length >= 2 && t.palette.length <= 6, "palette", "2-6 { color, role } entries");
+      t.palette.forEach((entry, i) => {
+        need(/^#[0-9a-f]{6}$/iu.test(entry?.color ?? ""), `palette[${i}].color`, "must be #rrggbb");
+        need(typeof entry?.role === "string" && entry.role.trim(), `palette[${i}].role`, "must say the colour's job");
+      });
+    }
+    if ("encode" in t) {
+      need(t.encode && typeof t.encode === "object", "encode", "must be { q, edgeQ, edgeFrames }");
+      for (const [key, lo, hi] of [["q", 50, 100], ["edgeQ", 50, 100], ["edgeFrames", 0, 60]]) {
+        if (key in t.encode) need(Number.isInteger(t.encode[key]) && t.encode[key] >= lo && t.encode[key] <= hi, `encode.${key}`, `an integer ${lo}-${hi}`);
+      }
+    }
+    if ("seed" in t) need(Number.isSafeInteger(t.seed), "seed", "must be an integer");
+    text(t, "ambition", { maxSentences: 2 });
+    const { page, size } = COVER.aspects[t.aspect];
+    return {
+      ok: true,
+      cover: { ...t, page: [...page], size: [...size], frames: Math.round(t.loopSec * t.fps), encode: { ...COVER.encode, ...(t.encode ?? {}) }, seed: Number.isSafeInteger(t.seed) ? t.seed >>> 0 : 20261020 }
+    };
+  } catch (error) {
+    if (error instanceof Invalid) return { ok: false, field: error.field, detail: error.message };
+    throw error;
+  }
+}
+
+/** True when `<out>/treatment.json` is readable JSON with mode cover (validity aside). */
+export function isCoverRun(out) {
+  try { return JSON.parse(readFileSync(path.join(out, "treatment.json"), "utf8"))?.mode === "cover"; } catch { return false; }
+}
+
+/** Read and validate `<out>/treatment.json` as a cover; throws exit 16 naming the field. Keeps the first valid one. */
+export function loadCoverTreatment(out) {
+  const file = path.join(out, "treatment.json");
+  const fail = (field, detail) => Object.assign(new Error(`BLOCKED_TREATMENT_INVALID (16): field ${field}: ${detail}`), { exitCode: TREATMENT_EXIT, field });
+  if (!existsSync(file)) throw fail("treatment", `no treatment.json in ${out}; write the cover treatment first (references/cover.md)`);
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw fail("treatment", `treatment.json is not JSON (${error.message})`); }
+  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 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");
+  return result.cover;
+}

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

@@ -41,6 +41,6 @@ export async function encodePreview(runDir, frameDir, fps, count, encoder) {
     const files = Array.from({ length: count }, (_, k) => path.join(frameDir, `p${String(k).padStart(5, "0")}.png`));
     result = spawnSync("img2webp", ["-loop", "0", "-lossy", "-q", "78", "-m", "4", "-d", String(Math.round(1000 / fps)), ...files, "-o", target], { encoding: "utf8", timeout: 600000, maxBuffer: 16_000_000 });
   } else result = spawnSync("ffmpeg", ["-y", "-loglevel", "error", "-framerate", String(fps), "-i", pattern, "-filter_complex", "[0:v]split[a][b];[a]palettegen=stats_mode=full[p];[b][p]paletteuse=dither=bayer:bayer_scale=4", "-loop", "0", target], { encoding: "utf8", timeout: 600000 });
-  if (result.status !== 0) throw new Error(`preview encode (${encoder}) failed: ${(result.stderr || result.error?.message || "").trim().split("\n").slice(-2).join(" ")}`);
+  if (result.status !== 0) throw new Error(`preview encode (${encoder}) failed: ${(result.stderr || result.error?.message || "").trim().split(/\r?\n/u).slice(-2).join(" ")}`);
   return target;
 }