@litfamily/litopencode 1.0.28 → 1.0.30

package/skills/lit-humanizer/scripts/guard-scan.mjs

@@ -2,10 +2,12 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseRules, scanText } from "./core.mjs";
+import { negationClusterFindings, parseRules, scanText } from "./core.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const maxInputBytes = 8 * 1024 * 1024;
+// The host refuses worker output over its byte cap and then allows the write, so blocks go first and the list is bounded.
+const maxFindings = 1000;
 
 try {
   const input = readFileSync(0);
@@ -15,21 +17,25 @@ try {
     throw new Error("guard input must contain file, oldText, and newText strings");
   }
   const rules = parseRules(readFileSync(join(here, "../rules.json"), "utf8"));
-  const oldFindings = scanText(request.oldText, rules, request.file);
+  const scan = (text) => [...scanText(text, rules, request.file), ...negationClusterFindings(text, request.file)];
+  // A document-scope finding is keyed by its occurrence lines, so an edit between two old occurrences does not re-raise it.
+  const keyOf = (finding) => JSON.stringify([finding.rule, finding.severity, finding.occurrences ?? finding.excerpt]);
+  const oldFindings = scan(request.oldText);
   const remaining = new Map();
   for (const finding of oldFindings) {
-    const key = JSON.stringify([finding.rule, finding.severity, finding.excerpt]);
+    const key = keyOf(finding);
     remaining.set(key, (remaining.get(key) ?? 0) + 1);
   }
-  const findings = scanText(request.newText, rules, request.file).filter((finding) => {
-    const key = JSON.stringify([finding.rule, finding.severity, finding.excerpt]);
+  const findings = scan(request.newText).filter((finding) => {
+    const key = keyOf(finding);
     const count = remaining.get(key) ?? 0;
     if (count === 0) return true;
     if (count === 1) remaining.delete(key);
     else remaining.set(key, count - 1);
     return false;
   });
-  process.stdout.write(`${JSON.stringify({ findings })}\n`);
+  const ordered = [...findings.filter((finding) => finding.severity === "block"), ...findings.filter((finding) => finding.severity !== "block")];
+  process.stdout.write(`${JSON.stringify({ findings: ordered.slice(0, maxFindings) })}\n`);
 } catch (error) {
   process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
   process.exitCode = 2;

package/skills/lit-pptx/SKILL.md

@@ -43,7 +43,7 @@ Under `lit`, create a `.pptx` by default. Do not ask a theme, colour or font que
 
 ## #contract.procedure
 
-1. **Runtime.** Nothing to install by hand. The first `node <skill>/run.mjs compile …` installs the pinned Node lockfile into the LitOpenCode cache and prints one notice line; the first Python helper call does the same for its venv. `node <skill>/run.mjs doctor` reports readiness without installing. A failed first-use install (no network, no `npm`, no Python 3) is a capability failure: quote the error line and stop; never install anything globally or inside the skill.
+1. **Runtime.** Nothing to install by hand. The first `node <skill>/run.mjs compile …` installs the pinned Node lockfile into the LitOpenCode cache and prints one notice line; the first Python helper call does the same for its venv. `node <skill>/run.mjs doctor` reports readiness without installing. A failed first-use install (no network, no `npm`, no Python 3.10 to 3.14; the venv comes from the newest `python3.X` in that range, a newer `python3` such as 3.15 is passed over, and `LITOPENCODE_OFFICE_PYTHON` names one interpreter instead) is a capability failure: quote the error line and stop; never install anything globally or inside the skill.
 
 2. **Choose the direction first, and write the direction card.** Before the first slide is written, decide the look and record it. Follow `references/direction-step.md`:
    - Settle four facts and write any inference down: deck type, reader, delivery (presented or read) and language.

package/skills/lit-pptx/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-pptx/run.mjs

@@ -6,6 +6,7 @@ import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { commandPlan, npmPlan, supportedPython } from "./command.mjs";
 
 const root = path.dirname(fileURLToPath(import.meta.url));
 const cache = path.join(process.env.XDG_CACHE_HOME || path.join(homedir(), ".cache"), "litopencode", "office");
@@ -20,12 +21,19 @@ const commands = {
   validate: ["python", "scripts/validate_pptx.py"],
 };
 
+// Windows: Node refuses to spawn a .cmd shim without a shell (spawn EINVAL) and a bare name never
+// matches npm.cmd or python.exe; command.mjs plans the launch (npm through Node and its own CLI).
+const isWindows = process.platform === "win32";
+
 function run(binary, args, options = {}) {
-  const result = spawnSync(binary, args, { stdio: "inherit", cwd: root, ...options });
-  if (result.error) throw result.error;
+  const launch = binary === "npm" ? npmPlan(args) : commandPlan(binary, args);
+  const result = spawnSync(launch.command, launch.args, { stdio: "inherit", cwd: root, shell: launch.shell, windowsHide: true, ...options });
+  if (result.error) throw new Error(`${binary} could not start: ${result.error.message}`);
   if (result.status !== 0) process.exit(result.status || 1);
 }
 
+const venvPython = (venv) => path.join(venv, ...(isWindows ? ["Scripts", "python.exe"] : ["bin", "python"]));
+
 function prepareNode() {
   if (existsSync(path.join(nodeRoot, "node_modules", "pptxgenjs"))) return;
   mkdirSync(cache, { recursive: true });
@@ -42,14 +50,16 @@ function prepareNode() {
 }
 
 function preparePython() {
-  const binary = path.join(pythonRoot, "bin", "python");
+  const binary = venvPython(pythonRoot);
   if (existsSync(binary)) return binary;
   mkdirSync(cache, { recursive: true });
   const temporary = mkdtempSync(path.join(cache, "python-install-"));
   try {
     process.stderr.write("Installing LitOpenCode office Python dependencies in its cache.\n");
-    run("python3", ["-m", "venv", temporary]);
-    run(path.join(temporary, "bin", "python"), ["-m", "pip", "install", "--disable-pip-version-check", "--require-hashes", "-r", path.join(root, "requirements.lock")]);
+    const python = supportedPython({ min: 10, max: 14, override: process.env.LITOPENCODE_OFFICE_PYTHON });
+    if (!python.ok) throw new Error(`${python.detail}. Install Python 3.10 to 3.14, or set LITOPENCODE_OFFICE_PYTHON to one.`);
+    run(python.command, ["-m", "venv", temporary]);
+    run(venvPython(temporary), ["-m", "pip", "install", "--disable-pip-version-check", "--require-hashes", "-r", path.join(root, "requirements.lock")]);
     renameSync(temporary, pythonRoot);
   } finally {
     if (existsSync(temporary)) rmSync(temporary, { recursive: true, force: true });
@@ -59,7 +69,7 @@ function preparePython() {
 
 const [command, ...args] = process.argv.slice(2);
 if (command === "doctor") {
-  console.log(JSON.stringify({ nodeReady: existsSync(path.join(nodeRoot, "node_modules", "pptxgenjs")), pythonReady: existsSync(path.join(pythonRoot, "bin", "python")) }));
+  console.log(JSON.stringify({ nodeReady: existsSync(path.join(nodeRoot, "node_modules", "pptxgenjs")), pythonReady: existsSync(venvPython(pythonRoot)) }));
 } else if (Object.hasOwn(commands, command)) {
   const [kind, script] = commands[command];
   const binary = kind === "node" ? (prepareNode(), "node") : preparePython();

package/skills/lit-pptx/scripts/compile-deck.js

@@ -451,7 +451,7 @@ if (require.main === module) {
           // Run Python boilerplate engine for PPTX
           await new Promise((resolve, reject) => {
             const pyArgs = [pyScript, tmpAstPath, "--output", pptxPath];
-            execFile("python3", pyArgs, { cwd: scriptDir }, (error, stdout, stderr) => {
+            execFile(process.platform === "win32" ? "python" : "python3", pyArgs, { cwd: scriptDir }, (error, stdout, stderr) => {
               // Clean up temp file
               try { fs.unlinkSync(tmpAstPath); } catch (_) {}
               if (error) {
@@ -475,7 +475,7 @@ if (require.main === module) {
         // Optional: embed bundled fonts into the PPTX for a self-contained deck.
         if (embedFonts && pptxPath) {
           const { execFileSync } = require("child_process");
-          execFileSync("python3", [path.join(__dirname, "embed_fonts.py"), pptxPath], {
+          execFileSync(process.platform === "win32" ? "python" : "python3", [path.join(__dirname, "embed_fonts.py"), pptxPath], {
             stdio: "inherit",
           });
         }

package/skills/lit-typographic-motion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lit-typographic-motion
-description: Direct a finished film from a written treatment. Films that show things take the stage path (your own HTML, SVG, Canvas or WebGL page, captured frame by frame); films made of the words alone take the type path. Both are gated and looked at. Use for a new film or video, including a bare lit request with video wording.
+description: Direct a finished film from a written treatment. Films that show things take the stage path (your own HTML, SVG, Canvas or WebGL page, captured frame by frame); films made of the words alone take the type path. Both are gated and looked at. A README cover loop takes cover mode. Use for a new film or video, including a bare lit request with video wording.
 reader_projection: shared_rule
 ---
 
@@ -34,6 +34,7 @@ Read the request, supplied words, facts, audio and any named style. Treat reques
 | Stage film | `node render.mjs stage --out <d> --round N` | film, stills, gate |
 | Type look | `node render.mjs film --brief <b> --out <d> --stills-only --round 1` | stills set, no encode |
 | Type film | `node render.mjs film --brief <b> --out <d> --round N` | film, stills, gate |
+| Cover | `node render.mjs cover --out <d> --round N` | `cover.webp`, decoded stills, strict gate |
 | Sound | `node render.mjs sound --out <d>` | `sound.wav`, `sound-cues.json` |
 | Look | `node render.mjs look --out <d> --round N --answers <file>` | one round appended to `look.json` |
 | Re-gate | `node gate.mjs <d>` | gate report |
@@ -41,6 +42,8 @@ Read the request, supplied words, facts, audio and any named style. Treat reques
 
 ## #contract.procedure
 
+A README, hero, banner or cover loop is not a film: follow `references/cover.md` instead of the steps below.
+
 1. Load `references/treatment.md` only, and write `treatment.json` in the output directory: idea, subject, beats on the genre's arc, devices, copy, palette, sound (generated by default under `lit`), ambition.
 2. Its `path` decides what to load next. Stage: `references/stage.md`, then write `index.html` in a `stage` folder of the output directory, using `/lit/stage-kit.js` and `/lit/fonts.css`. Type: `references/authoring.md`, `references/type-craft.md` and `references/style-bibles.md` (MO-B-00 preset pick), then write the brief.
 3. Round 1 (stills): run the look command with `--stills-only`, open every still with the read tool, answer the nine questions in `references/craft-loop.md`, name the weakest beat and the change, record it with `look --round 1`, then make that change.
@@ -70,7 +73,7 @@ The evidence is the treatment, the gate report, the manifest, `look.json` and th
 
 ## #contract.hard_stops
 
-On BLOCKED exit 10 (Chrome), 11 (WebGL2), 12 (ffmpeg; stills still work), 14 (runtime not pre-warmed) or 15 (font missing or hash mismatch), stop, name the state and its fix command; never install inside the session. Exit 16 (treatment), 17 (stage contract), 18 (stage not deterministic), 19 (network request) and 20 (sound) name the cause to fix. A flash-audit failure withholds the exports in every round.
+On BLOCKED exit 10 (Chrome), 11 (WebGL2), 12 (ffmpeg; stills still work), 14 (runtime not pre-warmed) or 15 (font missing or hash mismatch), stop, name the state and its fix command; never install inside the session. Exit 21 (no cover encoder) and 22 (a listed cover asset is missing; never draw a stand-in) stop too. Exit 16 (treatment), 17 (stage contract), 18 (stage not deterministic), 19 (network request) and 20 (sound) name the cause to fix. A flash-audit failure withholds the exports in every round.
 
 ## #contract.anti_patterns
 

package/skills/lit-typographic-motion/THIRD_PARTY_NOTICES

@@ -8,6 +8,9 @@ Fonts bundled in this skill (paths relative to this file):
 - VT323, fonts/VT323-Regular.ttf: SIL OFL 1.1, licence at fonts/VT323-OFL.txt
 - Silkscreen, fonts/Silkscreen-Regular.ttf and fonts/Silkscreen-Bold.ttf: SIL OFL 1.1, licence at fonts/Silkscreen-OFL.txt
 - EMS single-stroke SVG fonts (EMSAllure, EMSFelix, EMSOsmotron, EMSReadability, EMSTech), fonts/stroke/*.svg: SIL OFL 1.1, licence at fonts/stroke/OFL.txt, credits at fonts/stroke/CREDITS
+- JetBrains Mono, variable wght 100-800, Latin subset, fonts/JetBrainsMono-wght-latin.woff2 (unmodified file
+  files/jetbrains-mono-latin-wght-normal.woff2 of @fontsource-variable/jetbrains-mono 5.3.0; served to cover pages
+  only): SIL OFL 1.1, no Reserved Font Name, licence at fonts/JetBrainsMono-OFL.txt
 
 Fonts reused by path from the sibling lit-pptx skill:
 - Pretendard Regular and Bold, ../lit-pptx/pretendard-font/public/static/Pretendard-{Regular,Bold}.otf: SIL OFL 1.1, licence at ../lit-pptx/pretendard-font/LICENSE.txt

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

@@ -5,17 +5,11 @@ import { existsSync, mkdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { chromeFlagRungs } from "./constants.mjs";
+import { splitLines, which } from "./command.mjs";
 
 const macChrome = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
 
-export function which(name, env = process.env) {
-  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
-    if (!dir) continue;
-    const candidate = path.join(dir, name);
-    if (existsSync(candidate)) return candidate;
-  }
-  return undefined;
-}
+export { which };
 
 export function findChrome(env = process.env) {
   if (env.CHROME_PATH) return existsSync(env.CHROME_PATH) ? { path: env.CHROME_PATH } : { missing: `CHROME_PATH does not exist: ${env.CHROME_PATH}` };
@@ -29,7 +23,7 @@ export function findChrome(env = process.env) {
 
 export function chromeVersion(executable) {
   const result = spawnSync(executable, ["--version"], { encoding: "utf8", timeout: 10000 });
-  return result.status === 0 ? result.stdout.trim() : `version unavailable (${(result.stderr || result.error?.message || "").split("\n")[0]})`;
+  return result.status === 0 ? result.stdout.trim() : `version unavailable (${splitLines(result.stderr || result.error?.message || "")[0]})`;
 }
 
 export async function loadPlaywright(cacheDir) {

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 [];
+  }
+}