@litfamily/litopencode 1.0.29 → 1.0.30

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

@@ -0,0 +1,94 @@
+// Finding and starting commands on every platform. Windows keeps npm and most shims as `.cmd` files:
+// Node refuses to spawn one without a shell (CVE-2024-27980, `spawn EINVAL`), a bare name never
+// matches `ffmpeg.exe`, and a child's lines end in CRLF. Each rule here is injectable, so a test
+// proves the Windows answer on any machine.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/** Lines of a child's output, whichever line ending it printed. */
+export const splitLines = (text) => String(text ?? "").split(/\r?\n/u);
+
+/** The path of a command on PATH. On Windows the PATHEXT extensions are tried and a bare name never matches. */
+export function which(name, env = process.env, platform = process.platform) {
+  const windows = platform === "win32";
+  const extensions = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => ext.toLowerCase());
+  const names = !windows ? [name]
+    : [...(extensions.some((ext) => name.toLowerCase().endsWith(ext)) ? [name] : []), ...extensions.map((ext) => name + ext)];
+  for (const dir of (env.PATH ?? env.Path ?? "").split(windows ? ";" : path.delimiter)) {
+    if (!dir) continue;
+    for (const candidate of names) {
+      const file = path.join(dir, candidate);
+      if (existsSync(file)) return file;
+    }
+  }
+  return undefined;
+}
+
+const shim = /\.(?:cmd|bat)$/iu;
+
+/** One cmd.exe argument in double quotes; what quotes cannot protect is refused, so a value never becomes shell syntax. */
+export function quoteForCmd(value) {
+  if (/["%\r\n\0]/u.test(value)) throw new Error("A Windows command argument may not contain a quote, a percent sign or a line break.");
+  return `"${value.replace(/(\\+)$/u, "$1$1")}"`;
+}
+
+/** { command, args, shell } for spawnSync: a `.cmd` or `.bat` shim runs through a shell with quoted arguments. */
+export function commandPlan(command, args, { platform = process.platform, env = process.env, find = (name) => which(name, env, "win32") } = {}) {
+  if (platform !== "win32") return { command, args, shell: false };
+  const resolved = command.includes("/") || command.includes("\\") ? command : find(command) ?? command;
+  return shim.test(resolved) ? { command: quoteForCmd(resolved), args: args.map(quoteForCmd), shell: true } : { command: resolved, args, shell: false };
+}
+
+/** npm through Node and its own CLI script when one is at hand, else through the quoted shim. */
+export function npmPlan(args, { platform = process.platform, env = process.env, execPath = process.execPath, exists = existsSync, find = (name) => which(name, env, "win32") } = {}) {
+  if (platform !== "win32") return { command: "npm", args, shell: false };
+  if (env.npm_execpath && /\.[cm]?js$/iu.test(env.npm_execpath) && /^node(?:\.exe)?$/iu.test(path.win32.basename(execPath))) {
+    return { command: execPath, args: [env.npm_execpath, ...args], shell: false };
+  }
+  const found = find("npm");
+  if (found && shim.test(found)) {
+    const directory = path.win32.dirname(found);
+    const cli = path.win32.join(directory, "node_modules", "npm", "bin", "npm-cli.js");
+    if (exists(cli)) {
+      const sibling = path.win32.join(directory, "node.exe");
+      return { command: exists(sibling) ? sibling : find("node") ?? "node", args: [cli, ...args], shell: false };
+    }
+  }
+  return commandPlan("npm", args, { platform, env, find });
+}
+
+/** Runs `command` once to read its Python version: { ok, command, version } when it starts, else ok false. */
+export function probePython(command, env = process.env) {
+  const launch = commandPlan(command, ["-c", "import sys; print('%d.%d.%d' % sys.version_info[:3])"], { env });
+  const result = spawnSync(launch.command, launch.args, { encoding: "utf8", env, shell: launch.shell, windowsHide: true, timeout: 15000 });
+  if (result.error?.code === "ENOENT") return { ok: false, command, detail: "not found" };
+  if (result.error || result.status !== 0) return { ok: false, command, detail: (result.stderr || result.error?.message || "did not start").trim() };
+  return { ok: true, command, version: result.stdout.trim() };
+}
+
+/**
+ * The Python a venv of hash-pinned wheels is built from. The pins stop at a minor version, so a newer
+ * python3 (such as 3.15) fails pip on the first package without a wheel. `override` is used alone when
+ * set; otherwise the newest python3.<max> down to python3.<min> on PATH, then python3 and python.
+ * Returns { ok, command, version } or { ok: false, detail } naming each interpreter it passed over.
+ */
+export function supportedPython({ min, max, override, env = process.env, probe = probePython }) {
+  const range = `3.${min} to 3.${max}`;
+  const check = (command) => {
+    const found = probe(command, env);
+    if (!found.ok) return found;
+    const [major, minor] = found.version.split(".").map(Number);
+    if (major !== 3 || minor < min) return { ok: false, command, detail: `${found.version} is older than 3.${min}` };
+    if (minor > max) return { ok: false, command, detail: `${found.version} is newer than 3.${max}` };
+    return found;
+  };
+  const candidates = override ? [override] : [...Array.from({ length: max - min + 1 }, (_, index) => `python3.${max - index}`), "python3", "python"];
+  const passed = [];
+  for (const command of candidates) {
+    const found = check(command);
+    if (found.ok) return found;
+    if (override || found.detail !== "not found") passed.push(`${command}: ${found.detail}`);
+  }
+  return { ok: false, detail: `no supported Python (${range})${passed.length > 0 ? `; ${passed.join(", ")}` : " on PATH"}` };
+}

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

@@ -14,7 +14,9 @@ export const EXIT = Object.freeze({
   STAGE_CONTRACT_ERROR: 17,
   STAGE_NONDETERMINISTIC: 18,
   STAGE_NETWORK_REQUEST: 19,
-  SOUND_INVALID: 20
+  SOUND_INVALID: 20,
+  BLOCKED_NO_COVER_ENCODER: 21, // cover mode: neither img2webp + dwebp nor gifski on PATH
+  BLOCKED_ASSET_MISSING: 22 // cover mode: assets.json lists a file that is not there
 });
 
 export const FRAME = Object.freeze({ width: 1920, height: 1080, fps: 60 });
@@ -175,3 +177,29 @@ export const easeTokens = Object.freeze({
 
 export const engineCredit = "mexicat/pdoom-video ca251e3dddda422b364385eb484b5a3593a0990d (MIT)";
 export const engineCreditLine = "Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.";
+
+// Cover mode (references/cover.md): the README cover loop and its gate on the decoded file. The
+// thresholds were calibrated on 2026-10-20 against eight earlier painted covers (all pass FLOOR),
+// four slide-like negatives (all fail FLOOR) and three pilot loops (all reach TARGET). A number
+// moves only with a new calibration table, never to let a cover through.
+export const COVER = Object.freeze({
+  maxBytes: 3 * 1024 * 1024, // G1 FLOOR
+  targetBytes: 2 * 1024 * 1024, // G1 TARGET
+  minSec: 6, maxSec: 12,
+  gridMs: 50, // metrics run on a grid of max(gridMs, shortest decoded frame)
+  stillEps: 0.0005, // mean |dY| per grid step (luma 0..1 at about 300 px wide) below this is still
+  floor: Object.freeze({ medianD: 0.0004, movingFrac: 0.45, stillSec: 2.0, seamLocal: 8 }),
+  target: Object.freeze({ medianD: 0.0015, movingFrac: 0.95, stillSec: 0.5, spike: 6, seamLocal: 2.0, seamLocalMin: 0.25 }),
+  minContrast: 4.5, // G5, WCAG ratio of the title against its own box
+  minCapPx: 24, displayWidth: 830, // G6: cap height at a full-width README column
+  artSsim: 0.9, artMinShare: 0.1, // frame 0 shows the base art
+  seekFrames: 16, seekLevels: 1, // frames re-rendered out of order, and the rasterizer's rounding
+  windowPadSec: 0.5, maxDefects: 3,
+  captureScale: 2,
+  fps: Object.freeze([16, 20, 25]),
+  aspects: Object.freeze({
+    "2:1": Object.freeze({ page: Object.freeze([1200, 600]), size: Object.freeze([1000, 500]) }),
+    "3:2": Object.freeze({ page: Object.freeze([1200, 800]), size: Object.freeze([960, 640]) })
+  }),
+  encode: Object.freeze({ q: 86, edgeQ: 97, edgeFrames: 15, method: 4 })
+});

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

@@ -0,0 +1,91 @@
+// The cover's asset list, `<out>/assets.json`. Every raster the cover page can load (base art, logo,
+// wordmark, texture) is listed with its path, role, source (user: supplied; generated: made for this
+// cover and labelled so in the reply) and SHA-256, and the renderer checks the list before the first
+// capture. The art is supplied or generated, never replaced by a drawn stand-in: a listed file that
+// is missing stops the run as BLOCKED_ASSET_MISSING (exit 22), and so does the painted-light recipe
+// with no base art listed. After the render, decoded frame 0 must show the base art (artCheck).
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { COVER, EXIT } from "../constants.mjs";
+import { crop, lanczosResize, ssim } from "./image.mjs";
+
+export const ASSET_ROLES = Object.freeze(["base-art", "logo", "wordmark", "texture"]);
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const stop = (code, name, detail) => Object.assign(new Error(`${name} (${code}): ${detail}`), { exitCode: code });
+const badEntry = (field, detail) => stop(EXIT.BLOCKED_TREATMENT_INVALID, "BLOCKED_TREATMENT_INVALID", `assets.json ${field}: ${detail}`);
+const isBox = (b) => Array.isArray(b) && b.length === 4 && b.every((v) => typeof v === "number" && v >= 0 && v <= 1) && b[2] > 0 && b[3] > 0 && b[0] + b[2] <= 1 + 1e-9 && b[1] + b[3] <= 1 + 1e-9;
+const inside = (inner, outer) => inner[0] >= outer[0] - 1e-9 && inner[1] >= outer[1] - 1e-9 && inner[0] + inner[2] <= outer[0] + outer[2] + 1e-9 && inner[1] + inner[3] <= outer[1] + outer[3] + 1e-9;
+
+/**
+ * Check `<out>/assets.json` against the rasters the static scan found in the cover folder (paths
+ * relative to that folder). Returns the listed assets. Exit 22: a listed file is missing, or the
+ * painted-light recipe has no base art. Exit 17: a raster the list does not name, or a file whose
+ * hash changed since it was listed. Exit 16: a malformed entry.
+ */
+export function checkAssets({ out, treatment, rasters, coverDir = "cover" }) {
+  const file = path.join(out, "assets.json");
+  let assets = [];
+  if (existsSync(file)) {
+    let doc;
+    try { doc = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw badEntry("file", `not JSON (${error.message})`); }
+    if (!Array.isArray(doc?.assets)) throw badEntry("assets", "must be an array of { path, role, source, sha256 }");
+    assets = doc.assets.map((entry, i) => {
+      const at = `assets[${i}]`;
+      if (!entry || typeof entry !== "object") throw badEntry(at, "must be an object");
+      if (typeof entry.path !== "string" || !entry.path.startsWith(`${coverDir}/`) || entry.path.split("/").includes("..")) throw badEntry(`${at}.path`, `must be a path inside ${coverDir}/, relative to the output directory`);
+      if (!ASSET_ROLES.includes(entry.role)) throw badEntry(`${at}.role`, `must be one of ${ASSET_ROLES.join(", ")}`);
+      if (!["user", "generated"].includes(entry.source)) throw badEntry(`${at}.source`, "must be user (supplied) or generated");
+      if (!/^[0-9a-f]{64}$/u.test(entry.sha256 ?? "")) throw badEntry(`${at}.sha256`, "must be the file's SHA-256 (64 hex digits)");
+      if ("box" in entry && !isBox(entry.box)) throw badEntry(`${at}.box`, "must be [x, y, w, h] as fractions of the cover, inside it");
+      if (entry.role === "base-art" && !entry.box) throw badEntry(`${at}.box`, "base art needs the box it fills on the cover");
+      if (entry.role === "base-art" && !/\.png$/iu.test(entry.path)) throw badEntry(`${at}.path`, "base art is a PNG, so frame 0 can be compared with it");
+      if ("checkBox" in entry) {
+        if (!isBox(entry.checkBox) || !entry.box || !inside(entry.checkBox, entry.box)) throw badEntry(`${at}.checkBox`, "must be [x, y, w, h] inside the art's box");
+        if (entry.checkBox[2] * entry.checkBox[3] < COVER.artMinShare * entry.box[2] * entry.box[3]) throw badEntry(`${at}.checkBox`, `must cover at least ${COVER.artMinShare * 100} % of the art's box`);
+      }
+      return { path: entry.path, role: entry.role, source: entry.source, sha256: entry.sha256, box: entry.box ?? null, checkBox: entry.checkBox ?? null, title: entry.title === true };
+    });
+    for (const asset of assets) {
+      const real = path.join(out, asset.path);
+      if (!existsSync(real)) throw stop(EXIT.BLOCKED_ASSET_MISSING, "BLOCKED_ASSET_MISSING", `${asset.path} is listed in assets.json and is not there; supply it or generate it, never draw a stand-in`);
+      if (sha256(readFileSync(real)) !== asset.sha256) throw stop(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `${asset.path} no longer matches its sha256 in assets.json; list it again after changing it`);
+    }
+  }
+  if (treatment.recipe === "painted-light" && !assets.some((asset) => asset.role === "base-art")) {
+    throw stop(EXIT.BLOCKED_ASSET_MISSING, "BLOCKED_ASSET_MISSING", "the painted-light recipe relights a painting, and assets.json lists no base-art; supply the painting or generate it and list it, never draw a stand-in");
+  }
+  const listed = new Set(assets.map((asset) => asset.path));
+  for (const raster of rasters) {
+    const rel = `${coverDir}/${raster.rel.split(path.sep).join("/")}`;
+    if (!listed.has(rel)) throw stop(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `${rel} is a raster the page can load and assets.json does not list it; list it with its role, source and sha256`);
+  }
+  return assets;
+}
+
+/**
+ * Frame 0 is the poster and shows the base art: crop the check box (by default the whole art box)
+ * out of decoded frame 0 and compare it with the same region of the source scaled into the art box.
+ * `art` is { rgba, width, height }; boxes are fractions of the cover.
+ */
+export function artCheck({ frame0, width, height, art, box, checkBox = null }) {
+  const px = (b) => b.map((v, k) => Math.round(v * (k % 2 ? height : width)));
+  const [bx, by, bw, bh] = px(box);
+  const [cx, cy, cw, ch] = px(checkBox ?? box);
+  const scaled = lanczosResize(art.rgba, art.width, art.height, bw, bh);
+  const value = ssim(crop(frame0, width, [cx, cy, cw, ch]), crop(scaled, bw, [cx - bx, cy - by, cw, ch]), cw, ch);
+  return { ssim: value, pass: value >= COVER.artSsim, checked: [cx, cy, cw, ch] };
+}
+
+/** The reply labels a finished cover owes: one per asset the list marks as generated. */
+export function generatedAssetLabels(out) {
+  const file = path.join(out, "assets.json");
+  if (!existsSync(file)) return [];
+  try {
+    return (JSON.parse(readFileSync(file, "utf8")).assets ?? [])
+      .filter((asset) => asset?.source === "generated" && typeof asset.path === "string")
+      .map((asset) => `generated: ${asset.path} (${String(asset.role ?? "asset").replace("-", " ")}) was made for this cover, not supplied; label it as generated in the reply`);
+  } catch {
+    return [];
+  }
+}

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) });
+  }
+});