@litfamily/lithermes 1.0.27 → 1.0.28

package/assets/lithermes-plugin/skills/lit-typographic-motion/bin/runtime.mjs

@@ -12,6 +12,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { describeSpawnFailure, pickPython, spawnTool, venvPython } from '../engine/hostexec.mjs';
 
 export const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const runtimeRoot = join(skillRoot, 'runtime');
@@ -86,10 +87,10 @@ export function fontState(env = process.env) {
 }
 
 function run(cmd, args, options = {}) {
-  const result = spawnSync(cmd, args, { encoding: 'utf8', ...options });
+  const result = spawnTool(cmd, args, { encoding: 'utf8', ...options });
   if (result.error || result.status !== 0) {
-    const detail = result.error?.message || (result.stderr || '').trim().split('\n').slice(-3).join(' ') || `exit ${result.status}`;
-    throw new Error(`${cmd} ${args[0] || ''} failed: ${detail}`);
+    const detail = (result.stderr || '').trim().split(/\r?\n/).slice(-3).join(' ');
+    throw new Error(`${describeSpawnFailure(`${cmd} ${args[0] || ''}`.trim(), { ...result, stderr: detail })}`);
   }
   return result.stdout;
 }
@@ -111,14 +112,9 @@ export async function fetchPinned(entry, targetFile, { mirror = process.env.LITH
   writeFileSync(targetFile, bytes, { flag: 'wx' });
 }
 
-function pythonFor(env) {
-  const candidates = [env.LITHERMES_MOTION_PYTHON, 'python3.11', 'python3.12', 'python3.13', 'python3'].filter(Boolean);
-  for (const candidate of candidates) {
-    const probe = spawnSync(candidate, ['-c', 'import sys; print(sys.version.split()[0])'], { encoding: 'utf8' });
-    if (probe.status === 0) return { python: candidate, version: probe.stdout.trim() };
-  }
-  return null;
-}
+// The audio venv takes the office runtime's supported-python pick, with a 3.11 floor: the lock pins
+// numpy 2.4 and scipy 1.17, which start at Python 3.11.
+export const pickAudioPython = (env = process.env) => pickPython({ env, override: 'LITHERMES_MOTION_PYTHON', min: [3, 11] });
 
 export const audioDir = (cache) => join(cache, `audio-${audioDigest}`);
 
@@ -126,7 +122,7 @@ export const audioDir = (cache) => join(cache, `audio-${audioDigest}`);
 export function audioState(env = process.env) {
   const cache = findCache(env) || cacheRoots(env)[0];
   const dir = audioDir(cache);
-  const python = join(dir, 'venv', 'bin', 'python');
+  const python = venvPython(join(dir, 'venv'));
   if (!existsSync(python) || !existsSync(join(dir, 'AUDIO_READY'))) return { state: 'absent', python: null, dir };
   const expected = [...audioLockBytes.toString().matchAll(/^([A-Za-z0-9_.-]+)==([A-Za-z0-9_.+-]+)/gm)].map(([, name, version]) => [name, version]);
   const script = [
@@ -139,19 +135,19 @@ export function audioState(env = process.env) {
     'print(json.dumps(bad))',
   ].join('\n');
   const check = spawnSync(python, ['-c', script, JSON.stringify(expected)], { encoding: 'utf8', timeout: 20000 });
-  if (check.status !== 0) return { state: 'mismatched', python, dir, detail: (check.stderr || '').trim().split('\n').at(-1) };
+  if (check.status !== 0) return { state: 'mismatched', python, dir, detail: (check.stderr || '').trim().split(/\r?\n/).at(-1) };
   const bad = JSON.parse(check.stdout || '[]');
   return bad.length ? { state: 'mismatched', python, dir, detail: `pins drifted: ${bad.join(', ')}` } : { state: 'ready', python, dir };
 }
 
 async function installAudio(cache, env) {
-  const py = pythonFor(env);
-  if (!py) throw new Error('no python3 interpreter found for the --audio venv (set LITHERMES_MOTION_PYTHON)');
+  const py = pickAudioPython(env);
+  if (!py.python) throw new Error(`${py.detail}; the --audio venv needs one (install Python 3.14 or set LITHERMES_MOTION_PYTHON)`);
   const dir = audioDir(cache);
   const stage = `${dir}.stage-${process.pid}`;
   rmSync(stage, { recursive: true, force: true });
   run(py.python, ['-m', 'venv', join(stage, 'venv')]);
-  run(join(stage, 'venv', 'bin', 'python'), ['-m', 'pip', 'install', '--disable-pip-version-check', '--require-hashes', '--only-binary=:all:', '-r', join(runtimeRoot, 'requirements.lock')], { timeout: 900000 });
+  run(venvPython(join(stage, 'venv')), ['-m', 'pip', 'install', '--disable-pip-version-check', '--require-hashes', '--only-binary=:all:', '-r', join(runtimeRoot, 'requirements.lock')], { timeout: 900000 });
   writeFileSync(join(stage, 'AUDIO_READY'), `${audioDigest}\n`);
   rmSync(dir, { recursive: true, force: true });
   renameSync(stage, dir);
@@ -217,6 +213,14 @@ export async function install({ audio = false, wordTiming: wantWords = false, en
   return receipts.join('\n');
 }
 
+function coverEncoderLine(env) {
+  const tool = (name) => { const probe = spawnSync(name, ['-version'], { encoding: 'utf8', timeout: 10000, env }); return probe.status === 0 ? (/\d+\.\d+(?:\.\d+)?/.exec(`${probe.stdout}${probe.stderr}`)?.[0] || 'unknown version') : null; };
+  const img2webp = tool('img2webp'), dwebp = tool('dwebp');
+  if (img2webp && dwebp) return `img2webp ${img2webp} and dwebp ${dwebp}; README covers encode as animated WebP and gate the decoded file`;
+  if (spawnSync('gifski', ['--version'], { encoding: 'utf8', timeout: 10000, env }).status === 0) return `gifski (GIF fallback; img2webp${img2webp ? '' : ' missing'}, dwebp${dwebp ? '' : ' missing'})`;
+  return 'not found: install libwebp (img2webp, dwebp) or gifski; cover renders stop with exit 21';
+}
+
 const chromeProbeScript = () => {
   const gl = document.createElement('canvas').getContext('webgl2');
   if (!gl) return null;
@@ -224,7 +228,8 @@ const chromeProbeScript = () => {
   return ext ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) : 'unknown (debug-info extension unavailable)';
 };
 
-// MO-A-44: five probes on every run, in this product's "name: value" status style.
+// MO-A-44: five probes on every run, in this product's "name: value" status style, plus the
+// cover encoder that cover mode needs (img2webp and dwebp, or the gifski fallback).
 export async function status(env = process.env) {
   const { chromeExecutable, launchChrome } = await import('../engine/browser.mjs');
   const { isSoftwareRenderer, UNKNOWN_RENDERER } = await import('../engine/constants.mjs');
@@ -253,7 +258,7 @@ export async function status(env = process.env) {
       glLine = `${renderer} (flags: ${launched.flags.join(' ')})`;
       await launched.context.close().catch(() => {});
     } catch (error) {
-      glLine = `no WebGL2 context obtainable: ${String(error.message).split('\n')[0]}`;
+      glLine = `no WebGL2 context obtainable: ${String(error.message).split(/\r?\n/)[0]}`;
     } finally { rmSync(profileRoot, { recursive: true, force: true }); }
   }
   const software = !renderer ? 'unknown (no renderer probed)'
@@ -269,10 +274,11 @@ export async function status(env = process.env) {
   const warm = warmParts.length ? `NOT READY - ${warmParts.join('; ')}; fix: ${WARM}` : `READY cache=${deps.cache}`;
   return [
     `Chrome: ${chrome ? `${chrome} (${version || 'version unknown'})` : 'not found on PATH / not installed (set CHROME_PATH)'}`,
-    `ffmpeg: ${ffmpeg.status === 0 ? `${ffmpeg.stdout.split('\n')[0]}; preview encoder: ${preview}` : 'not found on PATH (video export blocked; stills and sheet still work)'}`,
+    `ffmpeg: ${ffmpeg.status === 0 ? `${ffmpeg.stdout.split(/\r?\n/)[0]}; preview encoder: ${preview}` : 'not found on PATH (video export blocked; stills and sheet still work)'}`,
     `WebGL2 renderer: ${glLine}`,
     `software GL: ${software}`,
     `pre-warm: ${warm}; ${audioText}`,
+    `cover encoder: ${coverEncoderLine(env)}`,
   ];
 }
 

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES

@@ -49,6 +49,8 @@ font: <cache>/assets/fonts/stroke/EMSReadability.svg
   licence: runtime/licenses/EMS-OFL.txt and runtime/licenses/CREDITS (in this package)
 font: <cache>/assets/fonts/stroke/EMSTech.svg
   licence: runtime/licenses/EMS-OFL.txt and runtime/licenses/CREDITS (in this package)
+font: <cache>/assets/fonts/JetBrainsMono-wght-latin.woff2 (variable wght 100-800, latin subset, from @fontsource-variable/jetbrains-mono 5.3.0; unmodified)
+  licence: <cache>/assets/licenses/JetBrainsMono-OFL.txt (SIL OFL 1.1, no Reserved Font Name)
 font: ../lit-pptx/pretendard-font/public/static/Pretendard-Regular.otf (reused by path, unmodified)
   licence: ../lit-pptx/fonts/PRETENDARD-OFL.txt (SIL OFL 1.1)
 font: ../lit-pptx/pretendard-font/public/static/Pretendard-Bold.otf (reused by path, unmodified)

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/browser.mjs

@@ -5,7 +5,7 @@
 // pull of the same readback buffer (the sanctioned variant). Each MO-A-51 rung
 // counts only after a real getContext('webgl2') in the page.
 import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, win32 } from 'node:path';
 import { EXIT, UNKNOWN_RENDERER, chromeFlagLadder, isSoftwareRenderer } from './constants.mjs';
 
 export const blocked = (code, message) => Object.assign(new Error(message), { exitCode: code });
@@ -16,9 +16,16 @@ const CHROME_CANDIDATES = [
   '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser',
 ];
 
-export function chromeExecutable(env = process.env) {
-  if (env.CHROME_PATH) return existsSync(env.CHROME_PATH) ? env.CHROME_PATH : null;
-  return CHROME_CANDIDATES.find((candidate) => existsSync(candidate)) || null;
+const WINDOWS_CHROME = ['ProgramFiles', 'ProgramFiles(x86)', 'LOCALAPPDATA']
+  .flatMap((key) => [['Google', 'Chrome', 'Application', 'chrome.exe'], ['Chromium', 'Application', 'chrome.exe']].map((tail) => [key, tail]));
+
+export function chromeExecutable(env = process.env, { platform = process.platform, exists = existsSync } = {}) {
+  if (env.CHROME_PATH) return exists(env.CHROME_PATH) ? env.CHROME_PATH : null;
+  if (platform === 'win32') {
+    const found = WINDOWS_CHROME.map(([key, tail]) => (env[key] ? win32.join(env[key], ...tail) : null)).find((file) => file && exists(file));
+    return found || null;
+  }
+  return CHROME_CANDIDATES.find((candidate) => exists(candidate)) || null;
 }
 
 // The launcher's first line that names a cause. Crashpad's own complaints are

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/constants.mjs

@@ -143,6 +143,35 @@ export const EXIT = Object.freeze({
   STAGE_NONDETERMINISTIC: 18,
   STAGE_NETWORK_REQUEST: 19,
   SOUND_INVALID: 20,
+  // Cover mode.
+  BLOCKED_NO_COVER_ENCODER: 21,
+  BLOCKED_ASSET_MISSING: 22,
+});
+
+// Cover mode (references/cover.md): the decoded-file gate, calibrated on 2026-10-20 against eight
+// earlier painted README covers, four slide-like negative loops and three pilot loops. FLOOR fails
+// a cover (every calibration cover passes it, every negative fails it). TARGET is what a cover
+// render must reach; the calibration covers miss it on purpose (a 1.9 s hold, a flash at the seam).
+// A number here changes only with a new calibration table, never to let a cover pass.
+export const COVER = Object.freeze({
+  maxBytes: 3 * 1024 * 1024, targetBytes: 2 * 1024 * 1024,
+  minSec: 6, maxSec: 12, fps: Object.freeze([16, 20, 25]),
+  gridMs: 50, // metrics run on a grid of max(gridMs, the shortest decoded frame)
+  stillEps: 0.0005, // a grid step whose mean |dY| (0..1, ~300 px wide) is 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, seamLo: 0.25, seamHi: 2.0 }),
+  minContrast: 4.5,
+  minCapPx: 24, displayWidth: 830, // G6: cap height at the README column width
+  artSsim: 0.9, artMinShare: 0.1, // frame 0 shows the base art
+  seekSamples: 16, seekLevels: 1, // seek-order check: frames re-drawn out of order, one-level tolerance
+  windowPadSec: 0.5, maxDefects: 3,
+  captureScale: 2,
+  // Laid out at `page` CSS px, captured at captureScale, downsampled (Lanczos) to `size`.
+  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 }),
 });
 
 // MO-A-58 post-chain override vocabulary: [min, max, neutral]. null max = no ceiling.

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

@@ -0,0 +1,87 @@
+// Cover assets: every raster a cover page can load (base art, logo, wordmark, texture) is listed in
+// <out>/assets.json with its path, role, source (user or generated) and SHA-256, and the renderer
+// checks the list before the first capture. A listed file that is missing is BLOCKED_ASSET_MISSING
+// (exit 22): the art is supplied or generated, never replaced by a drawn stand-in. The
+// painted-light recipe needs its base art listed. After the render, frame 0 has to show that art:
+// the SSIM of its check box in decoded frame 0 against the source scaled into the art's box.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { COVER, EXIT } from './constants.mjs';
+import { crop, lanczosResize, ssim } from './cover-image.mjs';
+
+export const ASSETS_FILE = 'assets.json';
+export const ASSET_ROLES = Object.freeze(['base-art', 'logo', 'wordmark', 'texture']);
+
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const exit = (code, message) => Object.assign(new Error(message), { exitCode: code });
+const invalid = (field, message) => exit(EXIT.BLOCKED_TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID: field assets.json ${field}: ${message}`);
+const inside = (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;
+
+function entry(a, i, coverDir) {
+  const at = `assets[${i}]`;
+  if (!a || typeof a !== 'object') throw invalid(at, 'must be an object');
+  if (typeof a.path !== 'string' || !a.path.startsWith(`${coverDir}/`) || a.path.split('/').includes('..')) throw invalid(`${at}.path`, `must be a path under ${coverDir}/, relative to the output directory`);
+  if (!ASSET_ROLES.includes(a.role)) throw invalid(`${at}.role`, `must be one of ${ASSET_ROLES.join(', ')}`);
+  if (!['user', 'generated'].includes(a.source)) throw invalid(`${at}.source`, 'must be user (supplied) or generated (made for this cover)');
+  if (!/^[0-9a-f]{64}$/u.test(a.sha256 ?? '')) throw invalid(`${at}.sha256`, 'must be the file\'s SHA-256 (64 hex)');
+  if (a.box !== undefined && !inside(a.box)) throw invalid(`${at}.box`, 'must be [x, y, w, h], fractions of the cover, inside it');
+  if (a.role === 'base-art' && !a.box) throw invalid(`${at}.box`, 'base art needs the box it fills on the cover');
+  if (a.checkBox !== undefined) {
+    if (!inside(a.checkBox) || !a.box) throw invalid(`${at}.checkBox`, 'must be [x, y, w, h] inside the cover, beside a box');
+    const [bx, by, bw, bh] = a.box, [cx, cy, cw, ch] = a.checkBox;
+    if (cx < bx - 1e-9 || cy < by - 1e-9 || cx + cw > bx + bw + 1e-9 || cy + ch > by + bh + 1e-9) throw invalid(`${at}.checkBox`, 'must lie inside the art\'s box');
+    if (cw * ch < COVER.artMinShare * bw * bh) throw invalid(`${at}.checkBox`, `must cover at least ${COVER.artMinShare * 100} % of the art's box`);
+  }
+  return { path: a.path, role: a.role, source: a.source, sha256: a.sha256, box: a.box || null, checkBox: a.checkBox || null, title: a.title === true };
+}
+
+// rasters: the static scan's raster paths, relative to the cover folder. Exit 22 for a missing
+// listed file or a painted recipe without base art; exit 17 for an unlisted raster or a changed
+// file; exit 16 for a malformed entry.
+export function checkAssets({ out, recipe, rasters, coverDir = 'cover' }) {
+  const file = join(out, ASSETS_FILE);
+  let assets = [];
+  if (existsSync(file)) {
+    let doc;
+    try { doc = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { throw invalid('', `is not valid JSON: ${error.message}`); }
+    if (!doc || !Array.isArray(doc.assets)) throw invalid('assets', 'must be an array of { path, role, source, sha256 }');
+    assets = doc.assets.map((a, i) => entry(a, i, coverDir));
+    for (const a of assets) {
+      const real = join(out, a.path);
+      if (!existsSync(real)) throw exit(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: ${a.path} is listed in assets.json and missing; supply it or generate it, never draw a stand-in`);
+      if (sha(readFileSync(real)) !== a.sha256) throw exit(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${a.path} no longer matches its sha256 in assets.json; list it again after changing it`);
+    }
+  }
+  if (recipe === 'painted-light' && !assets.some((a) => a.role === 'base-art')) {
+    throw exit(EXIT.BLOCKED_ASSET_MISSING, 'BLOCKED_ASSET_MISSING: the painted-light recipe needs its base art listed in assets.json ({ path, role: base-art, source, sha256, box }); supply or generate the painting, never draw a stand-in');
+  }
+  const listed = new Set(assets.map((a) => a.path));
+  for (const rel of rasters) {
+    const path = `${coverDir}/${rel.split(sep).join('/')}`;
+    if (!listed.has(path)) throw exit(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${path} is a raster the page can load but assets.json does not list; list it with its role, source and sha256`);
+  }
+  return assets;
+}
+
+const toPx = (box, W, H) => box.map((v, k) => Math.round(v * (k % 2 ? H : W)));
+
+// Frame 0 shows the base art: the check box (default: the whole art box) cut from decoded frame 0,
+// against the same region of the source scaled into the art box. Boxes are cover fractions.
+export function artCheck({ frame0, width, height, art, box, checkBox = null }) {
+  const [bx, by, bw, bh] = toPx(box, width, height);
+  const scaled = lanczosResize(art.rgba, art.width, art.height, bw, bh);
+  const [cx, cy, cw, ch] = toPx(checkBox || box, width, height);
+  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 labels the reply carries for every generated asset (complete prints them).
+export function generatedLabels(out) {
+  try {
+    const doc = JSON.parse(readFileSync(join(out, ASSETS_FILE), 'utf8'));
+    return (doc.assets || []).filter((a) => a?.source === 'generated' && typeof a.path === 'string')
+      .map((a) => `the ${String(a.role || 'asset').replace('-', ' ')} ${a.path} was generated for this cover, not supplied: label it as generated in the reply`);
+  } catch { return []; }
+}

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

@@ -0,0 +1,189 @@
+// Cover capture. One headless Chrome per pass, on the stage path's software rung (so two captures
+// can only differ because of the page), laid out at the cover's page size in CSS px and captured
+// at device scale 2. The page is served from the synthetic stage origin through CDP request
+// interception (no socket listens), with the loop kit at /lit/loop-kit.js and the faces at
+// /lit/fonts.css; the cover init script runs before any page script. The renderer SEEKS: it calls
+// window.renderFrame(t, { mask }) for any t in [0, 1), in any order, and a worker pool brings each
+// capture down to the cover size with Lanczos and writes it as a PNG. The master, the replay and
+// the seek-order pass each open their own browser.
+import { mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { cpus } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { EXIT } from './constants.mjs';
+import { chromeExecutable, launchCause } from './browser.mjs';
+import { CONTENT_TYPES, ORIGIN, stageFile, stageFlags } from './stage.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fail = (code, message) => Object.assign(new Error(message), { exitCode: code });
+const within = (promise, ms, message) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref())]);
+
+export const coverFlags = ({ width, height, scale }) => stageFlags({ width, height })
+  .map((flag) => (flag === '--force-device-scale-factor=1' ? `--force-device-scale-factor=${scale}` : flag));
+
+// The init script as Chrome runs it, plus a paint wait that keeps the native frame callback the
+// init script takes away from the page.
+function initSource() {
+  const init = readFileSync(join(here, 'cover-init.js'), 'utf8').replace(/^\/\/.*\n/gmu, '').trim();
+  const paint = 'const nativeRAF = window.requestAnimationFrame.bind(window); window.__litCoverPaint = () => new Promise((done) => nativeRAF(() => nativeRAF(done)));';
+  return `(() => { ${paint} })(); try { ${init}(); } catch (error) { window.__litCoverInitError = String(error && error.stack || error); }`;
+}
+
+export async function openCover({ runtime, coverDir, fonts, width, height, scale, profileRoot, env = process.env }) {
+  const chrome = chromeExecutable(env);
+  if (!chrome) throw fail(EXIT.BLOCKED_NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; install Chrome or set CHROME_PATH');
+  const { chromium } = runtime('playwright-core');
+  mkdirSync(profileRoot, { recursive: true });
+  const profile = join(profileRoot, 'p');
+  const flags = coverFlags({ width, height, scale });
+  let context;
+  try {
+    context = await chromium.launchPersistentContext(profile, {
+      executablePath: chrome, headless: true, chromiumSandbox: true, args: flags, timeout: 30000,
+      viewport: { width, height }, deviceScaleFactor: scale, serviceWorkers: 'block',
+    });
+  } catch (error) {
+    rmSync(profile, { recursive: true, force: true });
+    throw fail(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: headless Chrome failed to launch on the software rung: ${launchCause(error)}`);
+  }
+  const page = context.pages()[0] || await context.newPage();
+  page.setDefaultTimeout(0);
+  const cdp = await context.newCDPSession(page);
+  const kit = readFileSync(join(here, 'loop-kit.js'));
+  const root = realpathSync(coverDir);
+  const refused = [], contract = [], errors = [];
+  page.on('pageerror', (error) => errors.push(String(error.message || error).split('\n')[0]));
+  cdp.on('Fetch.requestPaused', async ({ requestId, request }) => {
+    let url = null;
+    try { url = new URL(request.url); } catch { /* an unparsable URL is refused below */ }
+    if (!url || url.origin !== ORIGIN) {
+      refused.push(request.url.slice(0, 160));
+      return cdp.send('Fetch.failRequest', { requestId, errorReason: 'BlockedByClient' }).catch(() => {});
+    }
+    const reply = (status, type, body) => cdp.send('Fetch.fulfillRequest', {
+      requestId, responseCode: status, responseHeaders: [{ name: 'Content-Type', value: type }, { name: 'Cache-Control', value: 'no-store' }],
+      body: Buffer.from(body).toString('base64'),
+    }).catch(() => {});
+    const path = decodeURIComponent(url.pathname);
+    if (path === '/lit/loop-kit.js') return reply(200, CONTENT_TYPES['.js'], kit);
+    if (path === '/lit/fonts.css') return reply(200, CONTENT_TYPES['.css'], fonts.css);
+    if (fonts.routes.has(path)) return reply(200, CONTENT_TYPES[`.${path.split('.').pop()}`] || 'font/ttf', readFileSync(fonts.routes.get(path)));
+    const found = stageFile(root, path);
+    if (found.status === 403) { contract.push(found.reason); return reply(403, 'text/plain', 'forbidden'); }
+    if (found.status === 404) return reply(404, 'text/plain', 'not found');
+    return reply(200, found.type, readFileSync(found.file));
+  });
+  await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*' }] });
+  await page.addInitScript({ content: initSource() });
+
+  const evaluate = (fn, arg, what) => within(page.evaluate(fn, arg), 120000, `the cover page did not answer within 120 s (${what})`);
+  const browser = {
+    flags, errors,
+    // Throw the named exit for anything a cover page may not do.
+    async check(where) {
+      if (refused.length) throw fail(EXIT.STAGE_NETWORK_REQUEST, `STAGE_NETWORK_REQUEST: the cover page requested ${refused[0]}${refused.length > 1 ? ` (+${refused.length - 1} more)` : ''} ${where}; everything is local`);
+      if (contract.length) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${contract[0]}`);
+      const misuse = await evaluate(() => (window.__litCoverMisuse ? window.__litCoverMisuse() : []), null, 'misuse check').catch(() => []);
+      if (misuse.length) throw fail(EXIT.STAGE_NONDETERMINISTIC, `STAGE_NONDETERMINISTIC: the cover page called ${misuse.join(', ')} ${where}; a cover frame is a function of t alone (LitLoop.rng(seed) for layout)`);
+    },
+    async load() {
+      await page.goto(`${ORIGIN}/index.html`, { waitUntil: 'load', timeout: 120000 });
+      const deadline = Date.now() + 60000;
+      for (;;) {
+        const state = await evaluate(() => ({ ready: window.ready === true, render: typeof window.renderFrame, init: window.__litCoverInitError || null }), null, 'ready');
+        if (state.init) throw fail(1, `cover init failed: ${state.init}`);
+        // A page that threw before it was ready (for example ART.lights has no entry for the hero
+        // bay N) never becomes ready; say so now instead of after the 60 s wait.
+        if (!state.ready && errors.length) {
+          await browser.check('while loading');
+          throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: the cover page threw before it set window.ready, so it stopped at once instead of waiting 60 s; first page error: ${errors[0]}`);
+        }
+        if (state.ready) {
+          await browser.check('while loading');
+          if (state.render !== 'function') throw fail(EXIT.STAGE_CONTRACT_ERROR, 'STAGE_CONTRACT_ERROR: the cover page set window.ready but defines no window.renderFrame(t)');
+          return;
+        }
+        if (Date.now() > deadline) {
+          await browser.check('while loading');
+          throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: the cover page never set window.ready = true within 60 s${errors.length ? `; first page error: ${errors[0]}` : ''}`);
+        }
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    // Draw loop time t (or its title mask) and wait until it is painted.
+    async frame(t, { mask = false } = {}) {
+      const at = `at t = ${t.toFixed(4)}`;
+      try {
+        await evaluate(async ([time, m]) => {
+          await window.renderFrame(time, { mask: m });
+          if (document.fonts) await document.fonts.ready;
+          await window.__litCoverPaint();
+        }, [t, mask], at);
+      } catch (error) {
+        await browser.check(at);
+        throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: renderFrame(${t.toFixed(4)}${mask ? ', { mask: true }' : ''}) threw: ${String(error.message).split('\n')[0]}`);
+      }
+      await browser.check(at);
+    },
+    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');
+    },
+    async close() {
+      await context.close().catch(() => {});
+      rmSync(profile, { recursive: true, force: true });
+    },
+  };
+  try { await browser.load(); } catch (error) { await browser.close(); throw error; }
+  return browser;
+}
+
+// Workers that downsample a 2x capture to the cover size and write it as an RGB PNG.
+export class CoverPool {
+  constructor(size = Math.max(2, Math.min(4, cpus().length - 2))) {
+    this.workers = Array.from({ length: size }, () => new Worker(new URL('./cover-worker.mjs', import.meta.url)));
+    this.turn = 0;
+    this.id = 0;
+    this.waiting = new Map();
+    for (const worker of this.workers) {
+      worker.on('message', (msg) => {
+        const job = this.waiting.get(msg.id);
+        this.waiting.delete(msg.id);
+        if (msg.error) job.reject(new Error(msg.error)); else job.resolve(msg);
+      });
+      worker.on('error', (error) => { for (const job of this.waiting.values()) job.reject(error); this.waiting.clear(); });
+    }
+  }
+
+  run(png, width, height, file) {
+    const id = ++this.id, worker = this.workers[this.turn++ % this.workers.length];
+    const copy = png.buffer.slice(png.byteOffset, png.byteOffset + png.byteLength);
+    return new Promise((resolve, reject) => { this.waiting.set(id, { resolve, reject }); worker.postMessage({ id, png: copy, width, height, file }, [copy]); });
+  }
+
+  async close() { await Promise.all(this.workers.map((w) => w.terminate())); }
+}
+
+export const frameName = (prefix, index) => `${prefix}${String(index).padStart(4, '0')}.png`;
+
+// Capture [index, t] pairs in the given order into dir as <prefix><index>.png at the cover size;
+// returns Map index -> SHA-256 of the written PNG.
+export async function capturePass({ browser, pool, times, dir, prefix = 'f', mask = false, size, page, scale }) {
+  mkdirSync(dir, { recursive: true });
+  const hashes = new Map(), jobs = [];
+  const expected = `${page[0] * scale}x${page[1] * scale}`;
+  for (const [index, t] of times) {
+    await browser.frame(t, { mask });
+    const png = await browser.capture();
+    const job = pool.run(png, size[0], size[1], join(dir, frameName(prefix, index))).then((r) => {
+      if (r.captured !== expected) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: a capture came back ${r.captured}, not ${expected}; the page must not resize its viewport`);
+      hashes.set(index, r.sha256);
+    });
+    job.catch(() => {}); // awaited below; this only keeps an early failure from going unhandled
+    jobs.push(job);
+    if (jobs.length > 8) await jobs.shift();
+  }
+  await Promise.all(jobs);
+  return hashes;
+}