@litfamily/litopencode 1.0.29 → 1.0.31

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

@@ -7,6 +7,9 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { downgrades, loadTreatment } from "./treatment.mjs";
 import { stageSha } from "./stage/scan.mjs";
+import { COVER } from "./constants.mjs";
+import { generatedAssetLabels } from "./cover/assets.mjs";
+import { isCoverRun, validateCoverTreatment } from "./cover/treatment.mjs";
 
 export const LOOK_QUESTIONS = Object.freeze([
   "A stranger would say this film is for: <…>",
@@ -21,6 +24,18 @@ export const LOOK_QUESTIONS = Object.freeze([
 ]);
 // 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]);
+// 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)?",
+  "Does the seam disappear in the decoded file (seam.png, the right end of the plot)?",
+  "Does it still move after encoding, with no region that freezes and then pops?",
+  "Is the brand word present, legible and in place in every frame, never faded or swapped?",
+  "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."
+]);
+const coverNoMeansRevise = new Set([1, 2, 3, 4, 5]);
 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);
@@ -36,8 +51,31 @@ export function concreteObservation(text) {
   return words >= 4 || (words >= 2 && value.replace(/\s+/gu, "").length >= 12);
 }
 
-export function needsAnotherRound(answers) {
-  return answers.filter((answer) => (noMeansRevise.has(answer.q) ? answer.verdict === "no" : answer.verdict === "yes")).map((answer) => answer.q);
+export function needsAnotherRound(answers, kind = "film") {
+  const reviseOnNo = kind === "cover" ? coverNoMeansRevise : noMeansRevise;
+  return answers.filter((answer) => (reviseOnNo.has(answer.q) ? answer.verdict === "no" : answer.verdict === "yes")).map((answer) => answer.q);
+}
+
+// Cover defects, at most three per round, worst first: { t, region, frame, observed, cause, fix }.
+// `t` is the loop time in seconds where it shows, `region` the [x, y, w, h] it covers in cover pixels,
+// `frame` a file of the current stills set that shows it. A window render around t checks the fix.
+function checkDefects(list, set) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) throw new LookError("defects must be an array");
+  if (list.length > COVER.maxDefects) throw new LookError(`at most ${COVER.maxDefects} defects per round; record the worst first`);
+  const [width, height] = set.stills.size;
+  const loopSec = set.stills.durationSec;
+  return list.map((defect, i) => {
+    const at = `defect ${i + 1}`;
+    if (!defect || typeof defect !== "object") throw new LookError(`${at} must be an object`);
+    if (typeof defect.t !== "number" || !(defect.t >= 0) || defect.t >= loopSec) throw new LookError(`${at}: t must be the loop time in seconds (0 to ${loopSec}) where the defect shows`);
+    const r = defect.region;
+    if (!Array.isArray(r) || r.length !== 4 || !r.every(Number.isInteger) || r[0] < 0 || r[1] < 0 || r[2] <= 0 || r[3] <= 0 || r[0] + r[2] > width || r[1] + r[3] > height) throw new LookError(`${at}: region must be [x, y, w, h] inside the ${width}x${height} cover`);
+    if (!set.files.includes(defect.frame)) throw new LookError(`${at}: frame ${defect.frame} is not in the latest stills set`);
+    if (!concreteObservation(defect.observed)) throw new LookError(`${at}: observed must be a sentence naming what is visible there`);
+    for (const key of ["cause", "fix"]) if (typeof defect[key] !== "string" || defect[key].trim().length < 8 || /<[^<>\n]{1,80}>/u.test(defect[key])) throw new LookError(`${at}: ${key} must say something concrete`);
+    return { t: defect.t, region: r, frame: defect.frame, observed: defect.observed.trim(), cause: defect.cause.trim(), fix: defect.fix.trim() };
+  });
 }
 
 // The frames a round may cite: the latest stills set, plus the poster after a full render.
@@ -47,8 +85,12 @@ export function currentSet(out) {
   const stillsSha = shaFile(path.join(out, "stills", "stills.json"));
   const manifestFile = path.join(out, "manifest.json");
   const manifest = readJson(manifestFile);
-  const film = manifest && manifest.stillsSha256 === stillsSha && manifest.craftRound === stills.round;
   const files = stills.files.map((entry) => entry.file);
+  if (stills.mode === "cover") {
+    const rendered = manifest?.mode === "cover" && manifest.stillsSha256 === stillsSha;
+    return { stills, kind: "cover", manifestSha: rendered ? shaFile(manifestFile) : stillsSha, files };
+  }
+  const film = manifest && manifest.stillsSha256 === stillsSha && manifest.craftRound === stills.round;
   const poster = ["poster.png", path.join("withheld", "poster.png")].find((name) => existsSync(path.join(out, name)));
   if (film && poster) files.push(poster);
   return { stills, kind: film ? "film" : "stills", manifestSha: film ? shaFile(manifestFile) : stillsSha, files };
@@ -64,6 +106,8 @@ export function recordLook(out, round, answersFile) {
   if (round !== expected) throw new LookError(`the next round is ${expected}; rounds share one counter with renders`);
   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 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, "")));
@@ -71,24 +115,31 @@ export function recordLook(out, round, answersFile) {
   const answers = Array.isArray(input.answers) ? input.answers : [];
   if (!blocked) {
     const asked = new Set(answers.map((answer) => answer?.q));
-    const missing = LOOK_QUESTIONS.map((_, i) => i + 1).filter((q) => !asked.has(q));
+    const missing = questions.map((_, i) => i + 1).filter((q) => !asked.has(q));
     if (missing.length) throw new LookError(`answer every question; missing ${missing.join(", ")}`);
     for (const answer of answers) {
-      if (!Number.isInteger(answer.q) || answer.q < 1 || answer.q > 9) throw new LookError(`unknown question ${answer.q}`);
+      if (!Number.isInteger(answer.q) || answer.q < 1 || answer.q > questions.length) throw new LookError(`unknown question ${answer.q}`);
       if (!["yes", "no"].includes(answer.verdict)) throw new LookError(`question ${answer.q}: verdict must be "yes" or "no"`);
       if (!concreteObservation(answer.observed)) throw new LookError(`question ${answer.q}: "observed" must be a sentence naming something visible in ${answer.frame ?? "the frame"}, not a bare answer`);
-      if (answer.q === 6 ? !["sound-cues.json", ...set.files].includes(answer.frame) : !set.files.includes(answer.frame)) throw new LookError(`question ${answer.q}: frame ${answer.frame} is not in the latest stills set`);
-      if (answer.q === 1 && !["blind", "self"].includes(answer.by)) throw new LookError('question 1: "by" must be "blind" (a fresh subagent) or "self"');
+      if (answer.q === 6 && !cover ? !["sound-cues.json", ...set.files].includes(answer.frame) : !set.files.includes(answer.frame)) throw new LookError(`question ${answer.q}: frame ${answer.frame} is not in the latest stills set`);
+      if (answer.q === 1 && !cover && !["blind", "self"].includes(answer.by)) throw new LookError('question 1: "by" must be "blind" (a fresh subagent) or "self"');
     }
   }
-  if (round === 1 && set.kind !== "stills") throw new LookError("round 1 is a stills round, before the first full render");
-  if (round === 1 && !blocked && (typeof input.change !== "string" || !input.change.trim() || typeof input.weakestBeat !== "string" || !input.weakestBeat.trim())) throw new LookError("round 1 must name the weakest beat and the change you will make");
+  if (cover) {
+    if (round === 1 && !blocked && (typeof input.change !== "string" || !input.change.trim())) throw new LookError("round 1 of a cover must name the change you will make before round 2");
+  } else {
+    if (input.defects !== undefined) throw new LookError("defects belong to a cover round; a film round names its weakest beat");
+    if (round === 1 && set.kind !== "stills") throw new LookError("round 1 is a stills round, before the first full render");
+    if (round === 1 && !blocked && (typeof input.change !== "string" || !input.change.trim() || typeof input.weakestBeat !== "string" || !input.weakestBeat.trim())) throw new LookError("round 1 must name the weakest beat and the change you will make");
+  }
+  const defects = cover ? checkDefects(input.defects, set) : [];
   const frames = Object.fromEntries(viewed.map((frame) => [frame, shaFile(path.join(out, frame))]));
   const entry = {
     round, kind: set.kind, manifestSha256: set.manifestSha, frames, answers: answers.map(({ q, verdict, frame, observed, by }) => ({ q, verdict, frame, observed, ...(by ? { by } : {}) })),
     ...(input.weakestBeat ? { weakestBeat: String(input.weakestBeat) } : {}), ...(input.change ? { change: String(input.change) } : {}),
     ...(Array.isArray(input.aids) ? { aids: input.aids.map(String) } : {}), ...(blocked ? { blocked: "no-vision-tool" } : {}),
-    needsAnotherRound: blocked ? [] : needsAnotherRound(answers), host: process.env.OPENCODE === "1" ? "opencode" : null, recordedAt: new Date().toISOString()
+    ...(cover ? { defects } : {}),
+    needsAnotherRound: blocked ? [] : needsAnotherRound(answers, set.kind), host: process.env.OPENCODE === "1" ? "opencode" : null, recordedAt: new Date().toISOString()
   };
   look.rounds.push(entry);
   writeFileSync(path.join(out, "look.json"), JSON.stringify(look, null, 2) + "\n");
@@ -106,9 +157,60 @@ function imageReads(out) {
   return readFileSync(file, "utf8").split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } });
 }
 
+// The cover branch of the done check (references/cover.md, "Rounds and done"): a valid cover
+// treatment; the last render's report at PASS+TARGET on the decoded file, with nothing changed since;
+// two look rounds, the first naming its change, the last on the final render's stills and opening
+// the sheet, the poster and the seam pair with the read tool. Generated assets owe a reply label.
+export function coverDoneState(out) {
+  const reasons = [], open = [];
+  const labels = generatedAssetLabels(out);
+  const result = (status, code) => ({ status, code, done: code === 0, reasons, open, downgraded: [], labels, mode: "cover" });
+  let raw = null;
+  try { raw = JSON.parse(readFileSync(path.join(out, "treatment.json"), "utf8")); } catch (error) { reasons.push(`treatment.json is unreadable (${error.message})`); return result("NOT DONE", 1); }
+  const valid = validateCoverTreatment(raw);
+  if (!valid.ok) { reasons.push(`BLOCKED_TREATMENT_INVALID (16): field ${valid.field}: ${valid.detail}`); return result("NOT DONE", 1); }
+  const manifestFile = path.join(out, "manifest.json");
+  const manifest = readJson(manifestFile);
+  const report = existsSync(path.join(out, "gate-report.txt")) ? readFileSync(path.join(out, "gate-report.txt"), "utf8") : null;
+  if (manifest?.mode !== "cover" || !report) { reasons.push("no finished cover render (manifest.json or gate-report.txt is missing): run render.mjs cover"); return result("NOT DONE", 1); }
+  if (manifest.treatmentSha256 !== shaFile(path.join(out, "treatment.json"))) reasons.push("the treatment changed after the last cover render; render again");
+  if (existsSync(path.join(out, "cover")) && manifest.coverSha256 !== stageSha(path.join(out, "cover"))) reasons.push("the cover page or an asset changed after the last cover render; render again");
+  const passed = /^COVER gate --strict: PASS\+TARGET$/mu.test(report);
+  const rounds = readJson(path.join(out, "look.json"), { rounds: [] }).rounds;
+  const first = rounds[0], last = rounds.at(-1);
+  const round = manifest.craftRound ?? last?.round ?? 0;
+  if (!passed) (round >= 3 ? open : reasons).push(`the decoded cover did not reach every TARGET gate (${report.split("\n").filter((line) => /^\s+\S+ (?:FAIL|pass\(floor\))(?: |$)/u.test(line)).map((line) => line.trim().split(" ")[0]).join(", ") || "see gate-report.txt"})`);
+  if (existsSync(path.join(out, "withheld"))) reasons.push("the flash audit failed; the cover is withheld");
+  if (rounds.length < 2) reasons.push(`${rounds.length} look round(s) recorded; a cover needs two: look, make the named change, render again, look again`);
+  if (first && !first.blocked && !first.change) reasons.push("round 1 must name the change made before round 2");
+  let unviewed = false;
+  if (last) {
+    if (last.kind !== "cover" || last.manifestSha256 !== shaFile(manifestFile)) reasons.push("the last look round was not taken on the final cover render; look again at this render");
+    let set = null;
+    try { set = currentSet(out); } catch (error) { reasons.push(error.message); }
+    if (set && !last.blocked) {
+      const required = set.stills.files.filter((entry) => ["sheet", "poster", "seam"].includes(entry.kind)).map((entry) => entry.file);
+      const skipped = required.filter((file) => !Object.hasOwn(last.frames ?? {}, file));
+      if (skipped.length) reasons.push(`the last round did not view: ${skipped.join(", ")}`);
+    }
+    if (last.blocked === "no-vision-tool") unviewed = true;
+    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 (last.needsAnotherRound?.length) (last.round >= 3 ? open : reasons).push(`cover look questions ${last.needsAnotherRound.join(", ")} ask for another round`);
+  }
+  if (reasons.length) return result("NOT DONE", 1);
+  if (unviewed) return result("DONE_UNVIEWED", 3);
+  if (open.length) return result("DONE_WITH_OPEN_ITEMS", 2);
+  return result("DONE", 0);
+}
+
 // 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);
+  if (isCoverRun(out)) return coverDoneState(out);
   const reasons = [], open = [];
   const result = (status, code) => ({ status, code, done: code === 0, reasons, open, downgraded });
   let treatment = null, downgraded = [];
@@ -161,6 +263,7 @@ export function formatDone(state) {
   for (const reason of state.reasons.slice(1)) lines.push(`- ${reason}`);
   for (const item of state.open) lines.push(`open: ${item}`);
   for (const item of state.downgraded) lines.push(`downgraded: ${item}`);
+  if (state.done || state.code === 2 || state.code === 3) for (const label of state.labels ?? []) lines.push(label);
   if (state.status === "DONE_UNVIEWED") lines.push("nobody viewed the frames: say so plainly in the reply");
   return lines.join("\n");
 }

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

@@ -243,7 +243,7 @@ export function muxTrack(videoFile, track, durationSec, target) {
   const result = spawnSync("ffmpeg", ["-y", "-loglevel", "error", "-i", videoFile, "-i", track.file, "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy",
     "-af", `aresample=${RATE},apad,atrim=0:${durationSec.toFixed(6)},afade=t=in:d=${fadeSec},afade=t=out:st=${fadeOut}:d=${fadeSec}`,
     "-ac", "2", "-c:a", "aac", "-b:a", "256k", "-movflags", "+faststart", target], { encoding: "utf8", timeout: 300000 });
-  if (result.status !== 0) throw Object.assign(new Error(`SOUND_INVALID (20): the ${track.mode} track could not be muxed: ${(result.stderr || "").trim().split("\n").at(-1)}`), { exitCode: SOUND_EXIT });
+  if (result.status !== 0) throw Object.assign(new Error(`SOUND_INVALID (20): the ${track.mode} track could not be muxed: ${(result.stderr || "").trim().split(/\r?\n/u).at(-1)}`), { exitCode: SOUND_EXIT });
 }
 
 // Decodes a film's audio stream (48 kHz stereo float) for the gate; null when there is none.

package/skills/lit-typographic-motion/engine/stage/capture.mjs

@@ -46,32 +46,20 @@ export function stageFonts(skillRoot, state, pins) {
   return { css, files, families: [...new Set(faces.map((face) => face.family))] };
 }
 
-// Launch one stage browser. `profile` is a short directory under the run's .run/, removed on close.
-export async function openStage(chromium, { chromePath, profile, stageDir, width, height, fps, seed, fonts, extraInit }) {
-  rmSync(profile, { recursive: true, force: true });
-  mkdirSync(profile, { recursive: true });
-  const flags = stageChromeFlags(width, height);
-  let context;
-  try {
-    context = await chromium.launchPersistentContext(profile, {
-      executablePath: chromePath, headless: true, args: flags, chromiumSandbox: true, timeout: 30000,
-      viewport: { width, height }, deviceScaleFactor: 1, serviceWorkers: "block"
-    });
-  } catch (error) {
-    rmSync(profile, { recursive: true, force: true });
-    const line = String(error?.message ?? error).split("\n").find((part) => part.trim()) ?? String(error);
-    throw Object.assign(new Error(`BLOCKED_NO_CHROME (10): Chrome failed to launch headless: ${line}; fix: check that Chrome can start headless in this sandbox`), { exitCode: 10 });
-  }
+// Serve the stage origin from disk through request interception: the product's scripts and faces
+// under /lit/, every other path from inside `stageDir` only. Anything else is recorded, never fetched:
+// another origin in `blocked`, a path that leaves the directory or has no stage type in `refused`, a
+// file that is not there in `missing`. The stage and the cover browsers both use it.
+export async function serveStage(context, { stageDir, fonts, scripts }) {
   const blocked = [];
   const refused = [];
   const missing = [];
   const root = realpathSync(stageDir);
-  const kit = kitSource();
   await context.route("**/*", async (route) => {
     const url = new URL(route.request().url());
     if (url.origin !== stageOrigin) { blocked.push(url.href); return route.abort("blockedbyclient"); }
     const pathname = decodeURIComponent(url.pathname);
-    if (pathname === "/lit/stage-kit.js") return route.fulfill({ status: 200, contentType: contentTypes[".js"], body: kit });
+    if (Object.hasOwn(scripts, pathname)) return route.fulfill({ status: 200, contentType: contentTypes[".js"], body: scripts[pathname] });
     if (pathname === "/lit/fonts.css") return route.fulfill({ status: 200, contentType: contentTypes[".css"], body: fonts.css });
     if (pathname.startsWith("/lit/fonts/")) {
       const file = fonts.files.get(pathname.slice("/lit/fonts/".length));
@@ -87,6 +75,26 @@ export async function openStage(chromium, { chromePath, profile, stageDir, width
     if (!type) { refused.push(rel); return route.fulfill({ status: 404, body: "" }); }
     return route.fulfill({ status: 200, contentType: type, body: readFileSync(real) });
   });
+  return { blocked, refused, missing };
+}
+
+// Launch one stage browser. `profile` is a short directory under the run's .run/, removed on close.
+export async function openStage(chromium, { chromePath, profile, stageDir, width, height, fps, seed, fonts, extraInit }) {
+  rmSync(profile, { recursive: true, force: true });
+  mkdirSync(profile, { recursive: true });
+  const flags = stageChromeFlags(width, height);
+  let context;
+  try {
+    context = await chromium.launchPersistentContext(profile, {
+      executablePath: chromePath, headless: true, args: flags, chromiumSandbox: true, timeout: 30000,
+      viewport: { width, height }, deviceScaleFactor: 1, serviceWorkers: "block"
+    });
+  } catch (error) {
+    rmSync(profile, { recursive: true, force: true });
+    const line = String(error?.message ?? error).split("\n").find((part) => part.trim()) ?? String(error);
+    throw Object.assign(new Error(`BLOCKED_NO_CHROME (10): Chrome failed to launch headless: ${line}; fix: check that Chrome can start headless in this sandbox`), { exitCode: 10 });
+  }
+  const { blocked, refused, missing } = await serveStage(context, { stageDir, fonts, scripts: { "/lit/stage-kit.js": kitSource() } });
   await context.addInitScript({ content: `window.__litStageConfig = ${JSON.stringify({ seed: seed >>> 0, fps })};\n${clockSource()}` });
   if (extraInit) await context.addInitScript({ content: extraInit });
   const page = context.pages()[0] ?? await context.newPage();

package/skills/lit-typographic-motion/engine/stage/cover-init.js

@@ -0,0 +1,38 @@
+// Cover init: injected into a cover page before any of its own scripts (engine/cover/capture.mjs).
+// A cover frame is a pure function of loop time t, and the renderer asks for frames out of order,
+// so every wall clock, frame loop and unseeded entropy source answers with an error instead of a
+// value. Each refusal is remembered by name, because a page may swallow the error in a try block;
+// the renderer reads the list after every frame and stops with exit 18 naming the call. CSS
+// animations and transitions would run on the real clock, so they are switched off.
+(function () {
+  "use strict";
+  const used = [];
+  const refuse = (name, instead) => function refused() {
+    if (!used.includes(name)) used.push(name);
+    throw new Error(`${name} is not available in a cover page: ${instead}`);
+  };
+  const fromT = "draw every frame from t";
+  const RealDate = Date;
+  function CoverDate(...args) {
+    if (new.target && args.length > 0) return new RealDate(...args);
+    return refuse("Date", fromT)();
+  }
+  CoverDate.prototype = RealDate.prototype;
+  CoverDate.now = refuse("Date.now", fromT);
+  CoverDate.parse = RealDate.parse;
+  CoverDate.UTC = RealDate.UTC;
+  Object.defineProperty(window, "Date", { value: CoverDate, writable: true, configurable: true });
+  Object.defineProperty(Performance.prototype, "now", { value: refuse("performance.now", fromT), writable: true, configurable: true });
+  Math.random = refuse("Math.random", "use LitLoop.rng(seed) for layout and t for motion");
+  window.requestAnimationFrame = refuse("requestAnimationFrame", "the renderer calls renderFrame(t); a cover page runs no loop of its own");
+  window.setInterval = refuse("setInterval", "the renderer calls renderFrame(t); a cover page runs no loop of its own");
+  if (window.crypto) Object.defineProperty(window.crypto, "getRandomValues", { value: refuse("crypto.getRandomValues", "use LitLoop.rng(seed)"), configurable: true });
+  const still = () => {
+    const style = document.createElement("style");
+    style.textContent = "*, *::before, *::after { animation: none !important; transition: none !important; }";
+    (document.head ?? document.documentElement).appendChild(style);
+  };
+  if (document.documentElement) still();
+  else document.addEventListener("readystatechange", still, { once: true });
+  window.__litCover = Object.freeze({ used: () => used.slice() });
+})();

package/skills/lit-typographic-motion/engine/stage/loop-kit.js

@@ -0,0 +1,102 @@
+// LitLoop, served at /lit/loop-kit.js to a cover page (references/cover.md). A cover page draws one
+// picture per loop time t in [0, 1) through window.renderFrame(t); the cover renderer seeks the
+// frames t = i / N in any order, more than once, in fresh browsers. So every helper below is either
+// periodic in t (its value at t = 1 is its value at t = 0) or a pure function of its arguments, and
+// none of them keeps state between calls. Randomness exists only as rng(seed), for layout.
+(function (scope) {
+  "use strict";
+
+  const TAU = 2 * Math.PI;
+  const fract = (x) => x - Math.floor(x);
+  const clamp = (x, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, x));
+  const mix = (a, b, k) => a * (1 - k) + b * k;
+
+  // mulberry32: the same seed always lays out the same picture.
+  function rng(seed) {
+    let state = seed >>> 0;
+    return function 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;
+    };
+  }
+
+  // Value noise on a seeded 3D lattice, smooth-stepped between lattice points.
+  function makeNoise(seed) {
+    const draw = rng(seed);
+    const table = new Float32Array(256).map(() => draw() * 2 - 1);
+    const order = Array.from({ length: 256 }, (_, i) => i);
+    for (let i = 255; i > 0; i--) {
+      const j = Math.floor(draw() * (i + 1));
+      const keep = order[i];
+      order[i] = order[j];
+      order[j] = keep;
+    }
+    const hash = (x, y, z) => table[order[(order[(order[x & 255] + y) & 255] + z) & 255]];
+    const fade = (k) => k * k * (3 - 2 * k);
+    return function noise(x, y, z) {
+      const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);
+      const u = fade(x - ix), v = fade(y - iy), w = fade(z - iz);
+      const plane = (zz) => mix(
+        mix(hash(ix, iy, zz), hash(ix + 1, iy, zz), u),
+        mix(hash(ix, iy + 1, zz), hash(ix + 1, iy + 1, zz), u),
+        v
+      );
+      return mix(plane(iz), plane(iz + 1), w);
+    };
+  }
+
+  // Noise sampled on a circle of `radius` around `offset`: one lap per loop, so it closes at t = 1.
+  // Different offsets give different copies of the same wander.
+  function loopNoise(noise, t, offset = 0, radius = 1.25) {
+    const a = TAU * t;
+    return noise(offset + radius * Math.cos(a), radius * Math.sin(a), 0.41 * offset);
+  }
+
+  // Easing shapes for events. Motion that never stops (a drift, a lap) stays linear.
+  const ease = Object.freeze({
+    smooth: (p) => p * p * (3 - 2 * p),
+    outCubic: (p) => 1 - Math.pow(1 - p, 3),
+    inCubic: (p) => p * p * p,
+    outExpo: (p) => (p >= 1 ? 1 : 1 - Math.pow(2, -10 * p)),
+    outBack: (p, s = 1.6) => 1 + (s + 1) * Math.pow(p - 1, 3) + s * Math.pow(p - 1, 2),
+    gain: (p, k) => (p < 0.5 ? 0.5 * Math.pow(2 * p, k) : 1 - 0.5 * Math.pow(2 - 2 * p, k))
+  });
+
+  // A symmetric bump of half-width w centred on c; 0 outside it. Micro events use this: an
+  // exponential tail is a slow fade, and the lossy encoder drops slow fades.
+  function cubicPulse(c, w, x) {
+    const d = Math.abs(x - c) / w;
+    return d >= 1 ? 0 : 1 - d * d * (3 - 2 * d);
+  }
+  // A fast attack and an exponential decay; kept for shapes that end before the loop does.
+  function expImpulse(x, k) {
+    const h = k * x;
+    return h * Math.exp(1 - h);
+  }
+
+  // The loop position of one copy: `cycles` laps per loop, shifted back by `offset`.
+  const phase = (t, offset = 0, cycles = 1) => fract(cycles * t - offset);
+  // How far p is from c around the loop (0 to 0.5): an event can straddle t = 0.
+  function cdist(p, c) {
+    const d = fract(p - c);
+    return d > 0.5 ? 1 - d : d;
+  }
+  // A one-shot inside the loop: progress 0..1 while p is in [start, start + dur) (wrapping), else -1.
+  function windowAt(p, start, dur) {
+    const q = fract(p - start);
+    return q < dur ? q / dur : -1;
+  }
+  // Dwell and move: `stops` poses per lap, travelling during the last `travel` share of each slot.
+  function steps(p, stops, travel = 0.35, shape = ease.smooth) {
+    const slot = Math.floor(p * stops);
+    const inSlot = p * stops - slot;
+    return (slot + shape(clamp((inSlot - (1 - travel)) / travel))) / stops;
+  }
+  // 0 -> 1 -> 0 over one lap, resting at both ends.
+  const swell = (p) => 0.5 * (1 - Math.cos(TAU * p));
+
+  scope.LitLoop = Object.freeze({ TAU, clamp, fract, mix, rng, makeNoise, loopNoise, ease, cubicPulse, expImpulse, phase, cdist, window: windowAt, steps, swell });
+})(typeof window === "undefined" ? globalThis : window);

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

@@ -402,15 +402,15 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
   }
 }
 
-// `render.mjs stage [--detach]`: a detached run writes its log and exit code under .run/ so a host
-// tool timeout never kills a long render.
-export function detachStage(out, args) {
+// `render.mjs stage|cover [--detach]`: a detached run writes its log and exit code under .run/ so a
+// host tool timeout never kills a long render.
+export function detachStage(out, args, mode = "stage") {
   const runDir = path.join(out, ".run");
   mkdirSync(runDir, { recursive: true });
   const logFile = path.join(runDir, "render.log");
   rmSync(path.join(runDir, "render-exit.json"), { force: true });
   const fd = openSync(logFile, "w");
-  const child = spawn(process.execPath, [path.join(skillRoot, "render.mjs"), "stage", ...args.filter((arg) => arg !== "--detach"), "--exit-file", path.join(runDir, "render-exit.json")], { detached: true, stdio: ["ignore", fd, fd] });
+  const child = spawn(process.execPath, [path.join(skillRoot, "render.mjs"), mode, ...args.filter((arg) => arg !== "--detach"), "--exit-file", path.join(runDir, "render-exit.json")], { detached: true, stdio: ["ignore", fd, fd] });
   child.unref();
   closeSync(fd);
   return { pid: child.pid, logFile, progressFile: path.join(runDir, "progress.json"), exitFile: path.join(runDir, "render-exit.json") };

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

@@ -229,6 +229,7 @@ export function loadTreatment(out) {
   if (!existsSync(file)) throw fail("treatment", `no treatment.json in ${out}; write it first (references/treatment.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 is a cover treatment; render it with `render.mjs cover --out <dir>` (references/cover.md)");
   const result = validateTreatment(parsed);
   if (!result.ok) throw fail(result.field, result.detail);
   return { treatment: parsed, file };

package/skills/lit-typographic-motion/fonts/JetBrainsMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono) JetBrainsMono-Italic[wght].ttf: Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/skills/lit-typographic-motion/fonts/pins.json

@@ -39,6 +39,8 @@
     "fonts/stroke/EMSReadability.svg": "eebece4f2a47b9d3a8f40cab2b0f689ca60902997abd5c81064ef0d2a3a05522",
     "fonts/stroke/EMSTech.svg": "7b5a420d4e16285213e7e2b1d187d086835c2dd7a7f64c5b8057434f082fc46f",
     "fonts/stroke/OFL.txt": "f19c674290e5dc79f02e8efe16139ab56a06a7128876f5b1579ffd0db5bc897e",
-    "fonts/stroke/CREDITS": "7be8857db66d53b6c6a7b82465a522cb4bbd1533af40f3e02f7dd7ffc9d44f9a"
+    "fonts/stroke/CREDITS": "7be8857db66d53b6c6a7b82465a522cb4bbd1533af40f3e02f7dd7ffc9d44f9a",
+    "fonts/JetBrainsMono-wght-latin.woff2": "18be452724bfdc236c074ca94a249a7f41a86752c7d04ab258ce9ed5651f6a7e",
+    "fonts/JetBrainsMono-OFL.txt": "403581b69dac5cff4079205e01c6b467e56af449ecbd7247693ddb1baafa005b"
   }
 }

package/skills/lit-typographic-motion/gate.mjs

@@ -17,6 +17,7 @@ import { pinnedSampleTimes } from "./engine/timing.mjs";
 import { checkStageRun, formatStageReport } from "./engine/stage/gate.mjs";
 import { soundChecks } from "./engine/sound.mjs";
 import { doneState, formatDone } from "./engine/look.mjs";
+import { coverGate, formatCoverReport } from "./engine/cover/gate.mjs";
 
 export const exportNames = ["film.mp4", "preview.webp", "preview.gif", "poster.png", "reduced-motion.png"];
 const isShot = (entry) => entry.kind === "line" || entry.kind === "scene";
@@ -569,9 +570,29 @@ export function completionState(dir) {
   return doneState(dir);
 }
 
+// `--cover <file>`: the cover gate on any encoded cover (.webp, .gif) or PNG frame folder. With the
+// capture folders it adds G0, G5 and G6; `--strict` exits 13 unless every gate reaches TARGET.
+// A cover output directory re-gates its own cover.webp with the folders its last render kept.
+export function runCoverGate(input, { frames, replay, masks, title, displayWidth, strict = false } = {}) {
+  const box = typeof title === "string" ? title.split(",").map(Number) : title;
+  const result = coverGate(input, { frames, replay, masks, title: box, glyph: box && masks ? { displayWidth } : null });
+  const report = formatCoverReport(result, { strict });
+  return { result, report, exitCode: result.pass && (!strict || result.target) ? EXIT.OK : EXIT.GATE_FAIL_QA };
+}
+
+function coverDirGate(root) {
+  const manifest = JSON.parse(readFileSync(path.join(root, "manifest.json"), "utf8"));
+  const file = [path.join(root, manifest.file), path.join(root, "withheld", manifest.file)].find((candidate) => existsSync(candidate));
+  if (!file) throw new Error(`the cover file ${manifest.file} is not in ${root}; render it again`);
+  const run = path.join(root, ".run", "cover");
+  const kept = (name) => (existsSync(path.join(run, name)) ? path.join(run, name) : undefined);
+  const treatment = JSON.parse(readFileSync(path.join(root, "treatment.json"), "utf8"));
+  return runCoverGate(file, { frames: kept("frames"), replay: kept("replay"), masks: kept("masks"), title: treatment.title?.box, strict: true });
+}
+
 function main(argv) {
   if (!argv.length || argv.includes("--help")) {
-    console.log("lit-typographic-motion gate\nUsage: node gate.mjs <output-dir> [--viewed N]\n       node gate.mjs --done <output-dir>   (0 DONE, 1 NOT DONE, 2 DONE_WITH_OPEN_ITEMS after round 3, 3 DONE_UNVIEWED)");
+    console.log("lit-typographic-motion gate\nUsage: node gate.mjs <output-dir> [--viewed N]\n       node gate.mjs --done <output-dir>   (0 DONE, 1 NOT DONE, 2 DONE_WITH_OPEN_ITEMS after round 3, 3 DONE_UNVIEWED)\n       node gate.mjs --cover <cover.webp|cover.gif|frames-dir> [--frames d --replay d --masks d --title x,y,w,h --display-width N] [--strict] [--json]");
     return 0;
   }
   if (argv[0] === "--done") {
@@ -579,6 +600,18 @@ function main(argv) {
     console.log(formatDone(state));
     return state.code;
   }
+  const value = (name) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : undefined; };
+  if (argv[0] === "--cover") {
+    const gated = runCoverGate(path.resolve(argv[1]), { frames: value("frames"), replay: value("replay"), masks: value("masks"), title: value("title"), displayWidth: value("display-width") ? Number(value("display-width")) : undefined, strict: argv.includes("--strict") });
+    const { kept, steps, durations, ...shown } = gated.result;
+    process.stdout.write(argv.includes("--json") ? `${JSON.stringify(shown, null, 2)}\n` : gated.report);
+    return gated.exitCode;
+  }
+  if (existsSync(path.join(argv[0], "manifest.json")) && JSON.parse(readFileSync(path.join(argv[0], "manifest.json"), "utf8")).mode === "cover") {
+    const gated = coverDirGate(path.resolve(argv[0]));
+    process.stdout.write(gated.report);
+    return gated.exitCode;
+  }
   const viewedIndex = argv.indexOf("--viewed");
   const viewed = viewedIndex >= 0 ? Number(argv[viewedIndex + 1]) || 0 : undefined;
   const result = runGate(argv[0], { viewed });