@litfamily/litopencode 1.0.28 → 1.0.30

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

@@ -0,0 +1,173 @@
+// One cover browser: the stage path's software rung and stage flags at device scale 2, the cover
+// page served from disk on the stage origin (engine/stage/capture.mjs serveStage, so no socket
+// listens), the loop kit at /lit/loop-kit.js, the product faces plus JetBrains Mono at
+// /lit/fonts.css, and the cover init script before any page script. The renderer SEEKS: it calls
+// window.renderFrame(t, { mask }) for any t in [0, 1) in any order and screenshots the page at twice
+// its CSS size; a worker pool reduces each screenshot to the cover size with Lanczos and writes it.
+// The master pass, the replay pass and the seek-order pass each open their own browser.
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { EXIT } from "../constants.mjs";
+import { serveStage, stageChromeFlags, stageFonts, stageOrigin } from "../stage/capture.mjs";
+import { StageError } from "../stage/scan.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const stageDir = path.join(here, "..", "stage");
+
+/**
+ * The stage flags with the device scale raised to the cover's capture scale, and raster kept on the
+ * CPU and whole. G0 compares every frame of two fresh browsers, and glyphs rasterized through the
+ * software GL (canvas fillText, and DOM text at changing weights) came out one level apart on a
+ * handful of pixels between them; CPU raster gives the same pixels every time.
+ */
+export function coverChromeFlags(width, height, scale) {
+  const flags = stageChromeFlags(width, height).map((flag) => (flag === "--force-device-scale-factor=1" ? `--force-device-scale-factor=${scale}` : flag));
+  return [...flags, "--disable-gpu-rasterization", "--disable-partial-raster"];
+}
+
+/** The stage faces plus JetBrains Mono, a variable face with a real wght axis (100-800). */
+export function coverFonts(skillRoot, state, pins) {
+  const fonts = stageFonts(skillRoot, state, pins);
+  const file = path.join(skillRoot, "fonts", "JetBrainsMono-wght-latin.woff2");
+  fonts.files.set(path.basename(file), file);
+  fonts.css += `@font-face { font-family: "JetBrains Mono"; src: url("/lit/fonts/${path.basename(file)}") format("woff2"); font-weight: 100 800; font-style: normal; font-display: block; }\n`;
+  fonts.families.push("JetBrains Mono");
+  return fonts;
+}
+
+const contractError = (detail) => new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", detail);
+
+/**
+ * Wait for window.ready, but stop at the page's first uncaught error: a page that throws while it
+ * builds (a stage-contract message such as `PAINTING.glows has no entry for the hero panel N`) never
+ * becomes ready, so the render reports that message now instead of after the full wait.
+ */
+export async function waitForCoverReady(tab, pageFailed, timeout = 60000) {
+  const ready = tab.waitForFunction(() => window.ready === true, null, { timeout, polling: 50 }).then(
+    () => undefined,
+    () => { throw new Error(`the cover page never set window.ready = true within ${timeout / 1000} s`); }
+  );
+  ready.catch(() => {});
+  const failure = await Promise.race([ready, pageFailed]);
+  if (failure !== undefined) throw new Error(`the cover page raised an error before it set window.ready: ${failure}`);
+  return undefined;
+}
+
+/**
+ * Launch a cover browser on `coverDir` and load its index.html. `page` is the CSS size; screenshots
+ * are `scale` times that. Returns { frame(t, { mask }), capture(), close(), flags }.
+ */
+export async function openCover(chromium, { chromePath, profile, coverDir, page: [width, height], scale, fonts }) {
+  const flags = coverChromeFlags(width, height, scale);
+  let context;
+  try {
+    context = await chromium.launchPersistentContext(profile, {
+      executablePath: chromePath, headless: true, args: flags, chromiumSandbox: true, timeout: 30000,
+      viewport: { width, height }, deviceScaleFactor: scale, serviceWorkers: "block"
+    });
+  } catch (error) {
+    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: EXIT.BLOCKED_NO_CHROME });
+  }
+  const served = await serveStage(context, { stageDir: coverDir, fonts, scripts: { "/lit/loop-kit.js": readFileSync(path.join(stageDir, "loop-kit.js"), "utf8") } });
+  await context.addInitScript({ content: readFileSync(path.join(stageDir, "cover-init.js"), "utf8") });
+  const tab = context.pages()[0] ?? await context.newPage();
+  const errors = [];
+  const pageFailed = new Promise((resolve) => tab.on("pageerror", (error) => {
+    errors.push(String(error?.message ?? error).split("\n")[0]);
+    resolve(errors[0]);
+  }));
+  const cdp = await context.newCDPSession(tab);
+  await cdp.send("Emulation.setDeviceMetricsOverride", { width, height, deviceScaleFactor: scale, mobile: false, screenWidth: width, screenHeight: height });
+  const close = async () => { await context.close().catch(() => {}); };
+  // Everything a cover page may not do, named; `at` says when.
+  const check = async (at) => {
+    if (served.blocked.length) throw new StageError(EXIT.STAGE_NETWORK_REQUEST, "STAGE_NETWORK_REQUEST", `the cover page requested ${served.blocked[0]}; everything is local`);
+    if (served.refused.length) throw contractError(`the cover page asked for ${served.refused[0]}, which is outside the cover folder or not a stage file type`);
+    const used = await tab.evaluate(() => (window.__litCover ? window.__litCover.used() : [])).catch(() => []);
+    if (used.length) throw new StageError(EXIT.STAGE_NONDETERMINISTIC, "STAGE_NONDETERMINISTIC", `the cover page called ${used.join(", ")}${at ? ` ${at}` : ""}; a cover frame is a function of t alone (LitLoop.rng(seed) for layout)`);
+  };
+  try {
+    try { await tab.goto(`${stageOrigin}/index.html`, { waitUntil: "load", timeout: 60000 }); }
+    catch (error) { await check("while loading"); throw contractError(`the cover page did not load: ${String(error?.message ?? error).split("\n")[0]}`); }
+    try { await waitForCoverReady(tab, pageFailed); }
+    catch (error) {
+      await check("while loading");
+      throw contractError(`${error.message}${served.missing[0] ? `; missing file: ${served.missing[0]}` : ""}`);
+    }
+    await check("while loading");
+    if (await tab.evaluate(() => typeof window.renderFrame) !== "function") throw contractError("the cover page set window.ready but defines no window.renderFrame(t, { mask })");
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  return {
+    flags, errors, missing: served.missing, close,
+    async frame(t, { mask = false } = {}) {
+      try {
+        await tab.evaluate(async ({ time, asMask }) => {
+          await window.renderFrame(time, { mask: asMask });
+          if (document.fonts) await document.fonts.ready;
+        }, { time: t, asMask: mask });
+      } catch (error) {
+        await check(`at t = ${t.toFixed(4)}`);
+        throw contractError(`renderFrame(${t.toFixed(4)}${mask ? ", { mask: true }" : ""}) threw: ${String(error?.message ?? error).split("\n")[0]}`);
+      }
+      await check(`at t = ${t.toFixed(4)}`);
+    },
+    async capture() {
+      const shot = await cdp.send("Page.captureScreenshot", { format: "png", optimizeForSpeed: true, captureBeyondViewport: false, fromSurface: true, clip: { x: 0, y: 0, width, height, scale: 1 } });
+      return Buffer.from(shot.data, "base64");
+    }
+  };
+}
+
+/** Worker threads that reduce screenshots to the cover size, write them, and hash the pixels. */
+export class CoverPool {
+  constructor(size = Math.max(2, Math.min(6, os.availableParallelism() - 3))) {
+    this.workers = Array.from({ length: size }, () => new Worker(path.join(here, "frame-worker.mjs")));
+    this.jobs = new Map();
+    this.id = 0;
+    this.turn = 0;
+    for (const worker of this.workers) {
+      worker.on("message", (message) => {
+        const job = this.jobs.get(message.id);
+        this.jobs.delete(message.id);
+        if (message.error) job.reject(contractError(message.error)); else job.resolve(message);
+      });
+      worker.on("error", (error) => { for (const job of this.jobs.values()) job.reject(error); this.jobs.clear(); });
+    }
+  }
+  reduce(png, size, file) {
+    const id = this.id++;
+    const bytes = new Uint8Array(png);
+    return new Promise((resolve, reject) => {
+      this.jobs.set(id, { resolve, reject });
+      this.workers[this.turn++ % this.workers.length].postMessage({ id, png: bytes, size, file }, [bytes.buffer]);
+    });
+  }
+  async close() { await Promise.all(this.workers.map((worker) => worker.terminate())); }
+}
+
+/**
+ * Draw and capture `times` ([index, t] pairs) in the order given, writing `<prefix>NNNN.png` at the
+ * cover `size` into `dir`. Returns Map index -> SHA-256 of the reduced frame's RGBA.
+ */
+export async function capturePass({ browser, pool, times, dir, prefix = "f", mask = false, size, expected }) {
+  const hashes = new Map();
+  const pending = [];
+  for (const [index, t] of times) {
+    await browser.frame(t, { mask });
+    const png = await browser.capture();
+    pending.push(pool.reduce(png, size, path.join(dir, `${prefix}${String(index).padStart(4, "0")}.png`)).then((result) => {
+      if (result.captured !== expected) throw contractError(`the capture is ${result.captured}, not ${expected}; the cover page must not resize its viewport`);
+      hashes.set(index, result.sha256);
+    }));
+    if (pending.length >= 12) await Promise.all(pending.splice(0, 6));
+  }
+  await Promise.all(pending);
+  return hashes;
+}

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

@@ -0,0 +1,173 @@
+// Decode an encoded cover the way a README reader's browser shows it, frame by frame, with each
+// frame's display time. The gate reads only this: a lossy animation encoder skips pixels that change
+// by less than a few levels, and those skips exist in the file, never in the PNG frames it was fed.
+//
+// Animated WebP: the RIFF container is read here (canvas, loop count, and every ANMF rectangle with
+// its duration, blend and dispose bits); each frame's own bitstream is wrapped as a still WebP and
+// decoded by `dwebp` from libwebp (it ships beside img2webp); the stills are composited on a
+// transparent canvas as libwebp's animation decoder does. GIF (the gifski fallback): ffmpeg decodes
+// the frames and the container gives the delays and the loop count.
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { which } from "../browser.mjs";
+
+const u24 = (bytes, at) => bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+
+/** The WebP container: { width, height, loop, frames: [{ x, y, w, h, durationMs, blend, dispose, payload }] }. */
+export function readWebpContainer(bytes) {
+  if (bytes.length < 20 || bytes.toString("latin1", 0, 4) !== "RIFF" || bytes.toString("latin1", 8, 12) !== "WEBP") throw new Error("not a WebP file");
+  const info = { width: 0, height: 0, loop: null, frames: [] };
+  const end = Math.min(bytes.length, 8 + bytes.readUInt32LE(4));
+  for (let at = 12; at + 8 <= end;) {
+    const kind = bytes.toString("latin1", at, at + 4);
+    const size = bytes.readUInt32LE(at + 4);
+    const body = bytes.subarray(at + 8, at + 8 + size);
+    if (kind === "VP8X") {
+      info.width = 1 + u24(body, 4);
+      info.height = 1 + u24(body, 7);
+    } else if (kind === "ANIM") {
+      info.loop = body.readUInt16LE(4);
+    } else if (kind === "ANMF") {
+      info.frames.push({ x: 2 * u24(body, 0), y: 2 * u24(body, 3), w: 1 + u24(body, 6), h: 1 + u24(body, 9), durationMs: u24(body, 12), blend: (body[15] & 2) === 0, dispose: (body[15] & 1) === 1, payload: body.subarray(16) });
+    } else if ((kind === "VP8 " || kind === "VP8L") && info.frames.length === 0) {
+      info.frames.push({ x: 0, y: 0, w: 0, h: 0, durationMs: 0, blend: false, dispose: false, still: bytes.subarray(at, at + 8 + size + (size & 1)) });
+    }
+    at += 8 + size + (size & 1);
+  }
+  if (info.loop === null && info.frames.length === 1) info.loop = 0;
+  return info;
+}
+
+// One ANMF payload (an optional ALPH chunk, then VP8 or VP8L) as a standalone still WebP.
+function stillWebp(frame) {
+  if (frame.still) return withRiffSize(Buffer.concat([Buffer.from("RIFF\0\0\0\0WEBP", "latin1"), frame.still]));
+  const alpha = frame.payload.toString("latin1", 0, 4) === "ALPH";
+  const parts = [];
+  if (alpha) {
+    const vp8x = Buffer.alloc(18);
+    vp8x.write("VP8X", 0, "latin1");
+    vp8x.writeUInt32LE(10, 4);
+    vp8x[8] = 0x10;
+    vp8x.writeUIntLE(frame.w - 1, 12, 3);
+    vp8x.writeUIntLE(frame.h - 1, 15, 3);
+    parts.push(vp8x);
+  }
+  parts.push(frame.payload);
+  return withRiffSize(Buffer.concat([Buffer.from("RIFF\0\0\0\0WEBP", "latin1"), ...parts]));
+}
+function withRiffSize(buffer) {
+  buffer.writeUInt32LE(buffer.length - 8, 4);
+  return buffer;
+}
+
+/** A PAM (P7) image as dwebp writes it: { width, height, rgba }. */
+export function readPam(buffer) {
+  const end = buffer.indexOf("ENDHDR\n");
+  if (buffer.toString("latin1", 0, 2) !== "P7" || end < 0) throw new Error("not a PAM image");
+  const header = buffer.toString("latin1", 0, end);
+  const field = (name) => Number(header.match(new RegExp(`${name} (\\d+)`, "u"))?.[1]);
+  const width = field("WIDTH"), height = field("HEIGHT"), depth = field("DEPTH");
+  const data = buffer.subarray(end + 7);
+  if (depth === 4) return { width, height, rgba: data };
+  const rgba = Buffer.alloc(width * height * 4, 255);
+  for (let i = 0; i < width * height; i++) for (let c = 0; c < 3; c++) rgba[i * 4 + c] = data[i * depth + Math.min(c, depth - 1)];
+  return { width, height, rgba };
+}
+
+// Draw a decoded rectangle onto the canvas: replace, or alpha-blend without premultiplication.
+function composite(canvas, canvasWidth, frame, rgba) {
+  for (let y = 0; y < frame.h; y++) {
+    for (let x = 0; x < frame.w; x++) {
+      const s = (y * frame.w + x) * 4, d = ((frame.y + y) * canvasWidth + frame.x + x) * 4;
+      const sa = rgba[s + 3];
+      if (!frame.blend || sa === 255) {
+        canvas[d] = rgba[s]; canvas[d + 1] = rgba[s + 1]; canvas[d + 2] = rgba[s + 2]; canvas[d + 3] = sa;
+        continue;
+      }
+      if (sa === 0) continue;
+      const below = (canvas[d + 3] * (255 - sa)) / 255;
+      const alpha = sa + below;
+      for (let c = 0; c < 3; c++) canvas[d + c] = Math.round((rgba[s + c] * sa + canvas[d + c] * below) / alpha);
+      canvas[d + 3] = Math.round(alpha);
+    }
+  }
+}
+
+function clearRect(canvas, canvasWidth, frame) {
+  for (let y = frame.y; y < frame.y + frame.h; y++) canvas.fill(0, (y * canvasWidth + frame.x) * 4, (y * canvasWidth + frame.x + frame.w) * 4);
+}
+
+/** The GIF container: per-frame delays in ms, the loop count and the size. */
+export function readGifContainer(bytes) {
+  if (bytes.toString("latin1", 0, 3) !== "GIF") throw new Error("not a GIF file");
+  const delays = [];
+  let loop = null, delay = 100;
+  let at = 13 + (bytes[10] & 0x80 ? 3 * 2 ** ((bytes[10] & 7) + 1) : 0);
+  const skipBlocks = () => { while (at < bytes.length && bytes[at] !== 0) at += bytes[at] + 1; at += 1; };
+  while (at < bytes.length) {
+    const marker = bytes[at];
+    if (marker === 0x3b) break;
+    if (marker === 0x21) {
+      const label = bytes[at + 1];
+      if (label === 0xf9) delay = 10 * bytes.readUInt16LE(at + 4);
+      if (label === 0xff && bytes.toString("latin1", at + 3, at + 14) === "NETSCAPE2.0") loop = bytes.readUInt16LE(at + 16);
+      at += 2;
+      skipBlocks();
+    } else if (marker === 0x2c) {
+      const flags = bytes[at + 9];
+      at += 10 + (flags & 0x80 ? 3 * 2 ** ((flags & 7) + 1) : 0) + 1;
+      skipBlocks();
+      delays.push(delay > 0 ? delay : 100);
+      delay = 100;
+    } else break;
+  }
+  return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8), loop, delays };
+}
+
+/**
+ * Decode every frame of `file` (.webp or .gif). `onFrame(index, rgba, durationMs, width, height)`
+ * sees the composited canvas, which is reused between calls: copy what you keep. Returns
+ * { format, width, height, loop, durations, bytes }.
+ */
+export function decodeCover(file, { env = process.env, onFrame = () => {} } = {}) {
+  const bytes = readFileSync(file);
+  if (file.toLowerCase().endsWith(".gif")) {
+    const info = readGifContainer(bytes);
+    const ffmpeg = which("ffmpeg", env);
+    if (!ffmpeg) throw new Error("ffmpeg is needed to decode a GIF cover");
+    const raw = spawnSync(ffmpeg, ["-v", "error", "-i", file, "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1"], { maxBuffer: 2 ** 31 });
+    if (raw.status !== 0) throw new Error(`ffmpeg could not decode ${file}: ${String(raw.stderr).trim().split(/\r?\n/u)[0]}`);
+    const size = info.width * info.height * 4;
+    const count = Math.min(info.delays.length, Math.floor(raw.stdout.length / size));
+    for (let i = 0; i < count; i++) onFrame(i, raw.stdout.subarray(i * size, (i + 1) * size), info.delays[i], info.width, info.height);
+    return { format: "gif", width: info.width, height: info.height, loop: info.loop, durations: info.delays.slice(0, count), bytes: bytes.length };
+  }
+  const dwebp = which("dwebp", env);
+  if (!dwebp) throw new Error("dwebp not found (libwebp ships it beside img2webp); install libwebp");
+  const info = readWebpContainer(bytes);
+  if (!info.frames.length) throw new Error(`${file} holds no frame`);
+  const work = mkdtempSync(path.join(os.tmpdir(), "ltm-webp-"));
+  try {
+    let width = info.width, height = info.height, canvas = null, previous = null;
+    const durations = [];
+    info.frames.forEach((frame, i) => {
+      const source = path.join(work, "frame.webp"), target = path.join(work, "frame.pam");
+      writeFileSync(source, stillWebp(frame));
+      const run = spawnSync(dwebp, [source, "-pam", "-quiet", "-o", target], { encoding: "utf8" });
+      if (run.status !== 0) throw new Error(`dwebp failed on frame ${i}: ${(run.stderr || run.error?.message || "").trim().split(/\r?\n/u)[0]}`);
+      const decoded = readPam(readFileSync(target));
+      if (frame.still) { width = decoded.width; height = decoded.height; frame.w = width; frame.h = height; }
+      canvas ??= Buffer.alloc(width * height * 4);
+      if (previous?.dispose) clearRect(canvas, width, previous);
+      composite(canvas, width, frame, decoded.rgba);
+      durations.push(frame.durationMs);
+      onFrame(i, canvas, frame.durationMs, width, height);
+      previous = frame;
+    });
+    return { format: "webp", width, height, loop: info.loop, durations, bytes: bytes.length };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}

package/skills/lit-typographic-motion/engine/cover/frame-worker.mjs

@@ -0,0 +1,19 @@
+// Worker thread for the cover capture: decode one 2x screenshot, reduce it to the cover size with
+// Lanczos, write it as a PNG (the encoder's input, and what G0, G5, G6 and the seek check read)
+// and return the SHA-256 of the reduced RGBA, so the browser can draw the next frame meanwhile.
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { parentPort } from "node:worker_threads";
+import { decodePng, encodePng } from "../png.mjs";
+import { lanczosResize, rgbaOf } from "./image.mjs";
+
+parentPort.on("message", ({ id, png, size: [width, height], file }) => {
+  try {
+    const shot = decodePng(Buffer.from(png));
+    const small = lanczosResize(rgbaOf(shot), shot.width, shot.height, width, height);
+    writeFileSync(file, encodePng(width, height, small, 4, 1));
+    parentPort.postMessage({ id, sha256: createHash("sha256").update(small).digest("hex"), captured: `${shot.width}x${shot.height}` });
+  } catch (error) {
+    parentPort.postMessage({ id, error: String(error?.message ?? error) });
+  }
+});

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

@@ -0,0 +1,261 @@
+// The cover gate, measured on the DECODED cover (engine/cover/decode.mjs), never only on the frames
+// that went into the encoder: G0 determinism, G1 size, length and loop, G2 motion energy, G3 holds
+// and spikes, G4 the seam, G5 title contrast through the mask pass, G6 title cap height at README
+// width. Every motion number is taken on a fixed time grid, because the encoder merges identical
+// frames into one long frame and a per-frame count would make a slide film look busy. FLOOR fails
+// the cover; TARGET is what cover mode delivers, and `--strict` (every cover render) fails on it too,
+// 2 MiB included. Thresholds live in engine/constants.mjs (COVER).
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { COVER } from "../constants.mjs";
+import { decodePng } from "../png.mjs";
+import { decodeCover } from "./decode.mjs";
+import { lumaGrid, meanLumaStep, rgbaOf } from "./image.mjs";
+
+const sorted = (list) => [...list].sort((a, b) => a - b);
+const median = (list) => { const s = sorted(list), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const quantile = (list, q) => { const s = sorted(list); return s[Math.min(s.length - 1, Math.max(0, Math.round(q * (s.length - 1))))]; };
+
+/** A PNG on disk as { width, height, rgba }. */
+export function readRgba(file) {
+  const image = decodePng(readFileSync(file));
+  return { width: image.width, height: image.height, rgba: rgbaOf(image) };
+}
+/** The sorted `<prefix>NNNN.png` files of a capture directory. */
+export function framesIn(dir, prefix = "f") {
+  return existsSync(dir) ? readdirSync(dir).filter((name) => name.startsWith(prefix) && name.endsWith(".png")).sort().map((name) => path.join(dir, name)) : [];
+}
+/** SHA-256 of a frame's decoded RGBA, the hash every determinism check compares (never PNG bytes). */
+export const rgbaSha = (rgba) => createHash("sha256").update(rgba).digest("hex");
+
+/**
+ * Load a cover for the gate: an encoded .webp or .gif, or a directory of PNG frames shown at `fps`.
+ * `keep(index, durationMs)` is asked once per decoded frame, in order, whether to keep that frame
+ * whole (RGBA) for the stills and the frame-0 art check. Returns { format, width, height, loop,
+ * bytes, durations, lumas, kept }.
+ */
+export function loadCover(input, { fps = 16, keep = () => false, env = process.env } = {}) {
+  const lumas = [];
+  const kept = new Map();
+  if (statSync(input).isDirectory()) {
+    const files = framesIn(input);
+    let width = 0, height = 0;
+    files.forEach((file, i) => {
+      const image = readRgba(file);
+      ({ width, height } = image);
+      lumas.push(lumaGrid(image.rgba, width, height).luma);
+      if (keep(i, 1000 / fps)) kept.set(i, image.rgba);
+    });
+    return { format: "png", width, height, loop: 0, bytes: null, durations: files.map(() => 1000 / fps), lumas, kept };
+  }
+  const info = decodeCover(input, {
+    env,
+    onFrame: (i, rgba, ms, width, height) => {
+      lumas.push(lumaGrid(rgba, width, height).luma);
+      if (keep(i, ms > 0 ? ms : 100)) kept.set(i, Buffer.from(rgba));
+    }
+  });
+  return { ...info, durations: info.durations.map((ms) => (ms > 0 ? ms : 100)), lumas, kept };
+}
+
+/** The frame on show at each grid time 0, step, 2 step, ... over the whole loop. */
+export function onGrid(frames, durations, step) {
+  const total = durations.reduce((a, b) => a + b, 0);
+  const out = [];
+  let index = 0, ends = durations[0];
+  for (let ms = 0; ms < total - 1e-6; ms += step) {
+    while (ms >= ends && index < frames.length - 1) ends += durations[++index];
+    out.push(frames[index]);
+  }
+  return out;
+}
+
+/** Motion on the grid. The loop is a ring: the step from the last sample back to the first is the seam. */
+export function motionMetrics({ lumas, durations }) {
+  const step = Math.max(COVER.gridMs, Math.min(...durations));
+  const grid = onGrid(lumas, durations, step);
+  const n = grid.length;
+  const steps = [];
+  for (let i = 1; i < n; i++) steps.push(meanLumaStep(grid[i], grid[i - 1]));
+  const seam = meanLumaStep(grid[0], grid[n - 1]);
+  const ring = [...steps, seam];
+  const medianD = median(ring);
+  const still = ring.map((d) => d < COVER.stillEps);
+  let longest = 0;
+  if (still.every(Boolean)) longest = n * step;
+  else {
+    // Walk the ring once from a moving step, so a hold that wraps through the seam counts whole.
+    const from = still.indexOf(false);
+    let run = 0;
+    for (let k = 1; k <= n; k++) {
+      run = still[(from + k) % n] ? run + step : 0;
+      longest = Math.max(longest, run);
+    }
+  }
+  // On a coarse grid (merged frames) the last sample reaches past the loop's end; a hold is never longer than the loop.
+  longest = Math.min(longest, durations.reduce((a, b) => a + b, 0));
+  const neighbours = n >= 4 ? (ring[n - 3] + ring[n - 2] + ring[0] + ring[1]) / 4 : medianD;
+  return {
+    gridFrames: n, gridMs: step, durationSec: (n * step) / 1000, sourceDurationSec: durations.reduce((a, b) => a + b, 0) / 1000,
+    medianD, p10D: quantile(ring, 0.1), p90D: quantile(ring, 0.9), maxD: Math.max(...ring),
+    movingFrac: ring.filter((d) => d >= COVER.stillEps).length / ring.length,
+    longestStillSec: longest / 1000, spike: Math.max(...ring) / Math.max(medianD, COVER.stillEps),
+    seam, seamLocal: seam / Math.max(COVER.stillEps, neighbours), steps: ring
+  };
+}
+
+const linear = (c) => { const v = c / 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; };
+const luminance = (rgba, p) => 0.2126 * linear(rgba[p]) + 0.7152 * linear(rgba[p + 1]) + 0.0722 * linear(rgba[p + 2]);
+/** A [x, y, w, h] box of fractions as whole pixels of a width x height frame. */
+export const boxPixels = (box, width, height) => box.map((v, k) => Math.round(v * (k % 2 ? height : width)));
+
+/**
+ * G5 on every frame: the median title pixel (white in the mask) against the 90th-percentile
+ * background pixel of the title box, the background being box pixels at least 3 px from any title
+ * pixel. Without one mask per frame the gate fails and says what is missing.
+ */
+export function titleContrast({ framesDir, masksDir, box }) {
+  const frames = framesIn(framesDir, "f"), masks = framesIn(masksDir, "m");
+  if (!frames.length || masks.length !== frames.length) return { measured: false, reason: `one mask per frame is needed (${frames.length} frames, ${masks.length} masks)` };
+  const ratios = [];
+  for (let i = 0; i < frames.length; i++) {
+    const frame = readRgba(frames[i]), mask = readRgba(masks[i]);
+    const { width, height } = frame;
+    if (mask.width !== width || mask.height !== height) return { measured: false, reason: `mask ${i} is ${mask.width}x${mask.height}, the frame ${width}x${height}` };
+    const [bx, by, bw, bh] = boxPixels(box, width, height);
+    const role = new Uint8Array(width * height); // 0 background, 1 halo, 2 title
+    for (let p = 0; p < width * height; p++) if (mask.rgba[p * 4] > 127) role[p] = 2;
+    for (let y = by; y < by + bh; y++) for (let x = bx; x < bx + bw; x++) {
+      if (role[y * width + x] !== 2) continue;
+      for (let dy = -3; dy <= 3; dy++) for (let dx = -3; dx <= 3; dx++) {
+        const yy = y + dy, xx = x + dx;
+        if (yy >= 0 && yy < height && xx >= 0 && xx < width && role[yy * width + xx] === 0) role[yy * width + xx] = 1;
+      }
+    }
+    const title = [], ground = [];
+    for (let y = by; y < by + bh; y++) for (let x = bx; x < bx + bw; x++) {
+      const p = y * width + x;
+      if (role[p] === 2) title.push(luminance(frame.rgba, p * 4));
+      else if (role[p] === 0) ground.push(luminance(frame.rgba, p * 4));
+    }
+    if (!title.length || !ground.length) return { measured: false, reason: `frame ${i}: the title box holds ${title.length} title and ${ground.length} background pixels` };
+    const t = median(title);
+    const g = t > median(ground) ? quantile(ground, 0.9) : quantile(ground, 0.1);
+    ratios.push((Math.max(t, g) + 0.05) / (Math.min(t, g) + 0.05));
+  }
+  return { measured: true, min: Math.min(...ratios), median: median(ratios), frames: ratios.length };
+}
+
+/**
+ * G6 on up to 12 mask frames spread over the loop: the white pixels in the title box are split into
+ * connected glyphs; dots and accents (under 1 % of the largest glyph's area or 30 % of the tallest
+ * glyph's height) are left out; the median height of the rest is the cap height. The smallest
+ * sample, scaled from the cover width to `displayWidth`, must reach COVER.minCapPx. A title painted
+ * into declared base art is `exempt`: still measured, reported as INFO. G6 stands beside G5.
+ */
+export function capHeight({ masksDir, box, displayWidth = COVER.displayWidth, exempt = null, samples = 12 }) {
+  const masks = framesIn(masksDir, "m");
+  if (!masks.length) return { pass: false, reason: "no mask frames to measure the title on" };
+  const count = Math.min(samples, masks.length);
+  const picks = [...new Set(Array.from({ length: count }, (_, k) => Math.floor((k * masks.length) / count)))];
+  let cap = Infinity, glyphs = 0, coverWidth = 0;
+  for (const i of picks) {
+    const mask = readRgba(masks[i]);
+    coverWidth = mask.width;
+    const [bx, by, bw, bh] = boxPixels(box, mask.width, mask.height);
+    const seen = new Uint8Array(bw * bh);
+    for (let y = 0; y < bh; y++) for (let x = 0; x < bw; x++) seen[y * bw + x] = mask.rgba[((by + y) * mask.width + bx + x) * 4] > 127 ? 1 : 0;
+    const parts = [];
+    for (let start = 0; start < seen.length; start++) {
+      if (seen[start] !== 1) continue;
+      const stack = [start];
+      seen[start] = 2;
+      let area = 0, top = bh, bottom = -1;
+      while (stack.length) {
+        const q = stack.pop(), y = Math.floor(q / bw), x = q % bw;
+        area += 1; top = Math.min(top, y); bottom = Math.max(bottom, y);
+        for (const next of [x > 0 ? q - 1 : -1, x < bw - 1 ? q + 1 : -1, y > 0 ? q - bw : -1, y < bh - 1 ? q + bw : -1]) {
+          if (next >= 0 && seen[next] === 1) { seen[next] = 2; stack.push(next); }
+        }
+      }
+      parts.push({ area, height: bottom - top + 1 });
+    }
+    if (!parts.length) return { pass: false, reason: `mask ${i} has no title pixels in the title box` };
+    const largest = Math.max(...parts.map((p) => p.area)), tallest = Math.max(...parts.map((p) => p.height));
+    const letters = parts.filter((p) => p.area >= 0.01 * largest && p.height >= 0.3 * tallest);
+    glyphs = Math.max(glyphs, letters.length);
+    cap = Math.min(cap, median(letters.map((p) => p.height)));
+  }
+  const capPx = (cap * displayWidth) / coverWidth;
+  const measured = { capPx: Number(capPx.toFixed(1)), coverPx: cap, displayWidth, glyphs, sampled: picks.length };
+  if (exempt) return { pass: null, ...measured, reason: exempt };
+  return { pass: capPx >= COVER.minCapPx, ...measured };
+}
+
+/** G0: two captures in fresh browsers, compared frame by frame on decoded RGBA. */
+export function determinism(a, b) {
+  const first = framesIn(a, "f"), second = framesIn(b, "f");
+  const count = Math.min(first.length, second.length);
+  let identical = 0, firstDiffering = null;
+  for (let i = 0; i < count; i++) {
+    if (rgbaSha(readRgba(first[i]).rgba) === rgbaSha(readRgba(second[i]).rgba)) identical += 1;
+    else firstDiffering ??= i;
+  }
+  return { compared: count, identical, countsMatch: first.length === second.length, firstDiffering };
+}
+
+/**
+ * Gate one cover. `frames` and `replay` (two capture directories) give G0; `masks` and `title` give
+ * G5; `glyph` adds G6. Returns the metrics, `gates`, `pass` (FLOOR) and `target` (TARGET, which
+ * `--strict` and every cover render need), plus the kept frames.
+ */
+export function coverGate(input, { frames = null, replay = null, masks = null, title = null, glyph = null, fps = 16, keep, env = process.env } = {}) {
+  const source = loadCover(input, { fps, keep, env });
+  const m = motionMetrics(source);
+  const gates = {};
+  if (frames && replay) {
+    const det = determinism(frames, replay);
+    gates.G0 = { pass: det.compared > 0 && det.countsMatch && det.identical === det.compared, ...det };
+  }
+  if (source.format !== "png") {
+    gates.G1 = {
+      pass: source.bytes <= COVER.maxBytes && m.sourceDurationSec >= COVER.minSec && m.sourceDurationSec <= COVER.maxSec && source.loop === 0,
+      target: source.bytes <= COVER.targetBytes,
+      bytes: source.bytes, durationSec: m.sourceDurationSec, loop: source.loop, size: `${source.width}x${source.height}`
+    };
+  }
+  const F = COVER.floor, T = COVER.target;
+  gates.G2 = { pass: m.medianD >= F.medianD && m.movingFrac >= F.movingFrac, target: m.medianD >= T.medianD && m.movingFrac >= T.movingFrac, medianD: m.medianD, movingFrac: m.movingFrac };
+  gates.G3 = { pass: m.longestStillSec <= F.stillSec, target: m.longestStillSec <= T.stillSec && m.spike <= T.spike, longestStillSec: m.longestStillSec, spike: m.spike };
+  gates.G4 = { pass: m.seamLocal <= F.seamLocal, target: m.seamLocal >= T.seamLocalMin && m.seamLocal <= T.seamLocal, seam: m.seam, seamLocal: m.seamLocal };
+  if (title && frames) {
+    const c = titleContrast({ framesDir: frames, masksDir: masks, box: title });
+    gates.G5 = c.measured ? { pass: c.min >= COVER.minContrast, min: c.min, median: c.median, frames: c.frames } : { pass: false, reason: c.reason };
+  }
+  if (title && masks && glyph) gates.G6 = capHeight({ masksDir: masks, box: title, displayWidth: glyph.displayWidth ?? COVER.displayWidth, exempt: glyph.exempt ?? null });
+  return { input, ...source, lumas: undefined, sourceFrames: source.lumas.length, ...m, gates, ...verdicts(gates) };
+}
+
+/** FLOOR is every gate's pass; TARGET also needs every gate's target. INFO rows (pass null) count for neither. */
+export function verdicts(gates) {
+  const pass = Object.values(gates).every((g) => g.pass !== false);
+  return { pass, target: pass && Object.values(gates).every((g) => g.target !== false) };
+}
+
+const shown = (v) => (typeof v === "number" && !Number.isInteger(v) ? Number(v.toPrecision(4)) : v);
+
+/** The report: the verdict line (the done check reads it), the file line, one line per gate. */
+export function formatCoverReport(result, { strict = false } = {}) {
+  const verdict = result.pass ? (result.target ? "PASS+TARGET" : "PASS(floor)") : "FAIL";
+  const lines = [
+    `COVER gate${strict ? " --strict" : ""}: ${verdict}`,
+    `  ${result.width}x${result.height} ${result.format} frames=${result.sourceFrames} dur=${shown(result.sourceDurationSec)}s bytes=${result.bytes ?? "-"} loop=${result.loop} grid=${result.gridMs}ms`
+  ];
+  for (const [name, gate] of Object.entries(result.gates)) {
+    const { pass, target, ...detail } = gate;
+    const word = pass === null ? "INFO" : pass ? (target === false ? "pass(floor)" : "pass") : "FAIL";
+    lines.push(`  ${name} ${word} ${Object.entries(detail).map(([k, v]) => `${k}=${shown(v)}`).join(" ")}`.trimEnd());
+  }
+  return `${lines.join("\n")}\n`;
+}