@litfamily/lithermes 1.0.27 → 1.0.29

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

@@ -0,0 +1,263 @@
+// The cover gate (references/cover.md): G0 determinism, G1 budget and loop, G2 motion energy, G3
+// anti-slide, G4 seam, G5 title contrast, G6 title cap height. It measures the DECODED cover (the
+// animated WebP, or the GIF fallback), never only the frames that went into the encoder. Motion
+// numbers are taken on a fixed time grid, because the encoder merges identical frames into one
+// long frame and counting frames would make a slide film look busy; the loop is a ring, so the
+// seam is one more step. FLOOR fails a cover, TARGET is the cover-mode goal and the strict verdict.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { COVER } from './constants.mjs';
+import { lumaGrid } from './cover-image.mjs';
+import { decodePng } from './cover-png.mjs';
+import { decodeWebp, which } from './cover-webp.mjs';
+
+const sorted = (xs) => [...xs].sort((a, b) => a - b);
+const median = (xs) => { const s = sorted(xs), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const quantile = (xs, q) => { const s = sorted(xs); return s[Math.min(s.length - 1, Math.max(0, Math.round(q * (s.length - 1))))]; };
+const meanStep = (a, b) => { let sum = 0; for (let i = 0; i < a.length; i++) sum += Math.abs(a[i] - b[i]); return sum / a.length / 255; };
+
+export const readPng = (file) => decodePng(readFileSync(file));
+export const framesIn = (dir, prefix = 'f') => (existsSync(dir) ? readdirSync(dir).filter((n) => n.startsWith(prefix) && n.endsWith('.png')).sort().map((n) => join(dir, n)) : []);
+
+// GIF container facts ffmpeg's raw pipe does not return: per-frame delays (ms) and the loop count.
+export function gifTiming(bytes) {
+  if (bytes.toString('latin1', 0, 3) !== 'GIF') throw new Error('not a GIF file');
+  const delays = [];
+  let loop = null, delay = 100, at = 13;
+  if (bytes[10] & 0x80) at += 3 * (1 << ((bytes[10] & 7) + 1));
+  const skip = (p) => { while (p < bytes.length && bytes[p]) p += bytes[p] + 1; return p + 1; };
+  while (at < bytes.length) {
+    const block = bytes[at];
+    if (block === 0x3b) break;
+    if (block === 0x21) {
+      if (bytes[at + 1] === 0xf9) delay = 10 * bytes.readUInt16LE(at + 4);
+      if (bytes[at + 1] === 0xff && bytes.toString('latin1', at + 3, at + 14) === 'NETSCAPE2.0') loop = bytes.readUInt16LE(at + 16);
+      at = skip(at + 2);
+    } else if (block === 0x2c) {
+      let p = at + 10;
+      if (bytes[at + 9] & 0x80) p += 3 * (1 << ((bytes[at + 9] & 7) + 1));
+      at = skip(p + 1);
+      delays.push(delay > 0 ? delay : 100);
+      delay = 100;
+    } else break;
+  }
+  return { delays, loop, width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+
+// Load a cover: { lumas, delays, width, height, loop, bytes, format, kept }. keep(i, ms) is asked
+// once per decoded frame, in order, whether to keep that frame whole (RGBA) for the stills.
+export function loadCover(input, { fps = 16, keep = () => false, env = process.env } = {}) {
+  const lumas = [], kept = new Map();
+  if (statSync(input).isDirectory()) {
+    let width = 0, height = 0;
+    const files = framesIn(input);
+    files.forEach((file, i) => {
+      const img = readPng(file);
+      ({ width, height } = img);
+      lumas.push(lumaGrid(img.rgba, width, height).luma);
+      if (keep(i, 1000 / fps)) kept.set(i, img.rgba);
+    });
+    return { lumas, delays: files.map(() => 1000 / fps), width, height, loop: 0, bytes: null, format: 'png', kept };
+  }
+  if (input.toLowerCase().endsWith('.gif')) {
+    const bytes = readFileSync(input), timing = gifTiming(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', input, '-fps_mode', 'passthrough', '-f', 'rawvideo', '-pix_fmt', 'rgba', 'pipe:1'], { maxBuffer: 2 ** 31, env });
+    if (raw.status !== 0) throw new Error(`ffmpeg could not decode ${input}`);
+    const size = timing.width * timing.height * 4;
+    for (let i = 0; (i + 1) * size <= raw.stdout.length; i++) {
+      const rgba = raw.stdout.subarray(i * size, (i + 1) * size);
+      lumas.push(lumaGrid(rgba, timing.width, timing.height).luma);
+      if (keep(i, timing.delays[i] ?? 100)) kept.set(i, Buffer.from(rgba));
+    }
+    return { lumas, delays: timing.delays.slice(0, lumas.length), width: timing.width, height: timing.height, loop: timing.loop, bytes: bytes.length, format: 'gif', kept };
+  }
+  const info = decodeWebp(input, {
+    env,
+    onFrame: (i, rgba, ms, width, height) => {
+      lumas.push(lumaGrid(rgba, width, height).luma);
+      if (keep(i, ms > 0 ? ms : 100)) kept.set(i, Buffer.from(rgba));
+    },
+  });
+  return { lumas, delays: info.durations.map((d) => (d > 0 ? d : 100)), width: info.width, height: info.height, loop: info.loop, bytes: info.bytes, format: 'webp', kept };
+}
+
+// The frame on screen at each grid time.
+export function resample(frames, delays, stepMs) {
+  const total = delays.reduce((a, b) => a + b, 0), out = [];
+  let i = 0, end = delays[0];
+  for (let ms = 0; ms < total - 1e-6; ms += stepMs) {
+    while (ms >= end && i < frames.length - 1) end += delays[++i];
+    out.push(frames[i]);
+  }
+  return out;
+}
+
+export function motionMetrics({ lumas, delays }) {
+  const stepMs = Math.max(COVER.gridMs, Math.min(...delays));
+  const grid = resample(lumas, delays, stepMs), n = grid.length;
+  const steps = [];
+  for (let i = 1; i < n; i++) steps.push(meanStep(grid[i], grid[i - 1]));
+  const seam = meanStep(grid[0], grid[n - 1]);
+  const ring = [...steps, seam];
+  const medianD = median(ring);
+  const still = ring.map((d) => d < COVER.stillEps);
+  let longest = 0;
+  if (still.every(Boolean)) longest = n * stepMs;
+  else {
+    // Walk the ring once from a moving step, so a hold that wraps the seam is counted whole.
+    const start = still.findIndex((s) => !s);
+    let run = 0;
+    for (let k = 1; k <= n; k++) { run = still[(start + k) % n] ? run + stepMs : 0; longest = Math.max(longest, run); }
+  }
+  const around = n >= 4 ? (ring[n - 3] + ring[n - 2] + ring[0] + ring[1]) / 4 : medianD;
+  return {
+    gridFrames: n, stepMs, durationSec: (n * stepMs) / 1000, sourceDurationSec: delays.reduce((a, b) => a + b, 0) / 1000,
+    medianD, p90D: quantile(ring, 0.9), maxD: Math.max(...ring), movingFrac: ring.filter((d) => d >= COVER.stillEps).length / ring.length,
+    longestStillSec: longest / 1000, spike: Math.max(...ring) / Math.max(medianD, COVER.stillEps), seam, seamLocal: seam / Math.max(COVER.stillEps, around), diffs: ring,
+  };
+}
+
+const LIN = Float64Array.from({ length: 256 }, (_, v) => { const s = v / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+const relLum = (px, at) => 0.2126 * LIN[px[at]] + 0.7152 * LIN[px[at + 1]] + 0.0722 * LIN[px[at + 2]];
+const boxPx = (box, W, H) => box.map((v, k) => Math.round(v * (k % 2 ? H : W)));
+
+// G5: per frame, the median title pixel against the 90th-percentile background pixel of the title
+// box (background = box pixels at least 3 px from any title pixel), through the per-frame mask.
+export function titleContrast({ framesDir, masksDir, box }) {
+  const frames = framesIn(framesDir, 'f'), masks = framesIn(masksDir, 'm');
+  if (!frames.length || masks.length !== frames.length) return { measured: false, reason: `needs one mask per frame (${frames.length} frames, ${masks.length} masks)` };
+  const ratios = [];
+  for (let i = 0; i < frames.length; i++) {
+    const { width: W, height: H, rgba } = readPng(frames[i]);
+    const mask = readPng(masks[i]);
+    if (mask.width !== W || mask.height !== H) return { measured: false, reason: `mask ${i} is ${mask.width}x${mask.height}, the frame ${W}x${H}` };
+    const [bx, by, bw, bh] = boxPx(box, W, H);
+    const role = new Uint8Array(W * H);
+    for (let p = 0; p < W * H; p++) if (mask.rgba[p * 4] > 127) role[p] = 2;
+    for (let y = by; y < by + bh; y++) for (let x = bx; x < bx + bw; x++) {
+      if (role[y * W + x] !== 2) continue;
+      for (let dy = -3; dy <= 3; dy++) for (let dx = -3; dx <= 3; dx++) {
+        const yy = y + dy, xx = x + dx;
+        if (yy >= 0 && yy < H && xx >= 0 && xx < W && role[yy * W + xx] === 0) role[yy * W + xx] = 1;
+      }
+    }
+    const text = [], ground = [];
+    for (let y = by; y < by + bh; y++) for (let x = bx; x < bx + bw; x++) {
+      const r = role[y * W + x];
+      if (r === 2) text.push(relLum(rgba, (y * W + x) * 4)); else if (r === 0) ground.push(relLum(rgba, (y * W + x) * 4));
+    }
+    if (!text.length || !ground.length) return { measured: false, reason: `frame ${i}: the title box holds ${text.length} title and ${ground.length} background pixels` };
+    const t = median(text), g = t > median(ground) ? quantile(ground, 0.9) : quantile(ground, 0.1);
+    ratios.push((Math.max(t, g) + 0.05) / (Math.min(t, g) + 0.05));
+  }
+  return { measured: true, min: Math.min(...ratios), median: median(ratios), frames: ratios.length };
+}
+
+// G6: the title's cap height at the README display width. In up to 12 sampled masks the white
+// pixels inside the title box split into connected glyphs; dots and accents (under 1 % of the
+// largest glyph's area or 30 % of the tallest glyph) are dropped and the median height of the rest
+// is that frame's cap height. The smallest one, scaled from the cover width to displayWidth, must
+// reach COVER.minCapPx. A title painted into declared base art is exempt: measured, reported INFO.
+export function glyphHeights({ masksDir, box, displayWidth = COVER.displayWidth, exempt = null, samples = 12 }) {
+  const masks = framesIn(masksDir, 'm');
+  if (!masks.length) return { pass: false, reason: 'no mask frames to measure the title on' };
+  const n = Math.min(samples, masks.length);
+  const picks = [...new Set(Array.from({ length: n }, (_, k) => Math.floor((k * masks.length) / n)))];
+  let cap = Infinity, glyphs = 0, width = 0;
+  for (const i of picks) {
+    const m = readPng(masks[i]);
+    width = m.width;
+    const [bx, by, bw, bh] = boxPx(box, m.width, m.height);
+    const on = new Uint8Array(bw * bh);
+    for (let y = 0; y < bh; y++) for (let x = 0; x < bw; x++) on[y * bw + x] = m.rgba[((by + y) * m.width + bx + x) * 4] > 127 ? 1 : 0;
+    const parts = [];
+    for (let seed = 0; seed < on.length; seed++) {
+      if (on[seed] !== 1) continue;
+      const stack = [seed];
+      on[seed] = 2;
+      let area = 0, top = bh, bottom = -1;
+      while (stack.length) {
+        const q = stack.pop(), y = Math.floor(q / bw), x = q - y * bw;
+        area++; top = Math.min(top, y); bottom = Math.max(bottom, y);
+        for (const nb of [x > 0 ? q - 1 : -1, x < bw - 1 ? q + 1 : -1, y > 0 ? q - bw : -1, y < bh - 1 ? q + bw : -1]) if (nb >= 0 && on[nb] === 1) { on[nb] = 2; stack.push(nb); }
+      }
+      parts.push({ area, height: bottom - top + 1 });
+    }
+    if (!parts.length) return { pass: false, reason: `mask ${i}: no title pixels inside the title box` };
+    const biggest = Math.max(...parts.map((p) => p.area)), tallest = Math.max(...parts.map((p) => p.height));
+    const letters = parts.filter((p) => p.area >= 0.01 * biggest && p.height >= 0.3 * tallest);
+    glyphs = Math.max(glyphs, letters.length);
+    cap = Math.min(cap, median(letters.map((p) => p.height)));
+  }
+  const capPx = (cap * displayWidth) / width;
+  const row = { capPx: Number(capPx.toFixed(1)), coverPx: cap, displayWidth, glyphs, sampled: picks.length };
+  return exempt ? { pass: null, ...row, reason: exempt } : { pass: capPx >= COVER.minCapPx, ...row };
+}
+
+// G0: SHA-256 per frame file of two independent captures.
+export function determinism(dirA, dirB) {
+  const a = framesIn(dirA, 'f'), b = framesIn(dirB, 'f');
+  const hash = (f) => createHash('sha256').update(readFileSync(f)).digest('hex');
+  let identical = 0, firstDiffering = null;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) { if (hash(a[i]) === hash(b[i])) identical++; else if (firstDiffering === null) firstDiffering = i; }
+  return { compared: n, identical, countsMatch: a.length === b.length, firstDiffering };
+}
+
+// Gate one cover. Options: frames + frames2 (G0), masks + title (G5, G6), glyph ({ displayWidth,
+// exempt }), fps (for a PNG folder input), keep. Returns the metrics, each gate, pass and target.
+export function coverGate(input, { frames = null, frames2 = null, masks = null, title = null, glyph = {}, fps = 16, keep, env = process.env } = {}) {
+  const src = loadCover(input, { fps, keep, env });
+  const m = motionMetrics(src);
+  const F = COVER.floor, T = COVER.target, gates = {};
+  if (frames && frames2) {
+    const det = determinism(frames, frames2);
+    gates.G0 = { pass: det.compared > 0 && det.countsMatch && det.identical === det.compared, ...det };
+  }
+  if (src.format !== 'png') {
+    gates.G1 = {
+      pass: src.bytes <= COVER.maxBytes && m.sourceDurationSec >= COVER.minSec && m.sourceDurationSec <= COVER.maxSec && src.loop === 0,
+      target: src.bytes <= COVER.targetBytes, bytes: src.bytes, durationSec: m.sourceDurationSec, loop: src.loop, size: `${src.width}x${src.height}`,
+    };
+  }
+  gates.G2 = { pass: m.medianD >= F.medianD && m.movingFrac >= F.movingFrac, target: m.medianD >= T.medianD && m.movingFrac >= T.movingFrac, medianD: m.medianD, movingFrac: m.movingFrac };
+  gates.G3 = { pass: m.longestStillSec <= F.stillSec, target: m.longestStillSec <= T.stillSec && m.spike <= T.spike, longestStillSec: m.longestStillSec, spike: m.spike };
+  gates.G4 = { pass: m.seamLocal <= F.seamLocal, target: m.seamLocal >= T.seamLo && m.seamLocal <= T.seamHi, seam: m.seam, seamLocal: m.seamLocal };
+  if (title && masks) {
+    const c = frames ? titleContrast({ framesDir: frames, masksDir: masks, box: title }) : { measured: false, reason: 'needs the captured frames (--frames) beside the masks' };
+    gates.G5 = c.measured ? { pass: c.min >= COVER.minContrast, min: c.min, median: c.median, frames: c.frames } : { pass: false, reason: c.reason };
+    gates.G6 = glyphHeights({ masksDir: masks, box: title, displayWidth: glyph.displayWidth ?? COVER.displayWidth, exempt: glyph.exempt ?? null });
+  }
+  return finishGate({ input, src, m, gates });
+}
+
+// Recompute the verdicts after a caller added gates (SEEK, ART, FLASH).
+export function finishGate({ input, src, m, gates }) {
+  const pass = Object.values(gates).every((g) => g.pass !== false);
+  const target = pass && Object.values(gates).every((g) => g.target !== false);
+  return { input, format: src.format, width: src.width, height: src.height, bytes: src.bytes, loop: src.loop, sourceFrames: src.lumas.length, durations: src.delays, kept: src.kept, ...m, gates, pass, target, src, m };
+}
+
+const num = (x) => (typeof x === 'number' && !Number.isInteger(x) ? Number(x.toPrecision(4)) : x);
+
+export function coverVerdict(r) {
+  return r.pass ? (r.target ? 'PASS+TARGET' : 'PASS(floor)') : 'FAIL';
+}
+
+// Report text: the strict verdict line, the file line, one line per gate.
+export function formatCoverReport(r, { strict = true } = {}) {
+  const lines = [
+    `COVER gate${strict ? ' --strict' : ''}: ${coverVerdict(r)}`,
+    `  ${r.width}x${r.height} ${r.format} frames=${r.sourceFrames} dur=${num(r.sourceDurationSec)}s bytes=${r.bytes ?? '-'} loop=${r.loop} grid=${num(r.stepMs)}ms`,
+  ];
+  for (const [id, g] of Object.entries(r.gates)) {
+    const { pass, target, ...detail } = g;
+    const word = pass === null ? 'INFO' : pass ? (target === false ? 'pass(floor)' : 'pass') : 'FAIL';
+    lines.push(`  ${id} ${word} ${Object.entries(detail).map(([k, v]) => `${k}=${num(v)}`).join(' ')}`.trimEnd());
+  }
+  return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,103 @@
+// Pixel helpers for cover mode, all on RGBA8 buffers and dependency-free so the gate also runs in
+// the test suite without the runtime cache: a separable Lanczos-3 resize (the 2x seek capture is
+// brought down to the cover size with it), the gate's luma grid (Rec. 709 weights on the encoded
+// values, box-averaged to about 300 px wide, so every motion number is a thumbnail-scale number),
+// a rectangle copy, and a tiled SSIM on luma for the frame-0 base-art check.
+
+export const LUMA_WIDTH = 300;
+
+const sinc = (x) => (x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x));
+const lanczos3 = (x) => (Math.abs(x) < 3 ? sinc(x) * sinc(x / 3) : 0);
+
+// One row of taps per output pixel: the first source index and normalised weights. When shrinking,
+// the kernel is stretched by the scale so every source pixel contributes (no aliasing).
+function taps(from, to) {
+  const scale = from / to, stretch = Math.max(1, scale), reach = 3 * stretch;
+  return Array.from({ length: to }, (_, i) => {
+    const centre = (i + 0.5) * scale - 0.5;
+    const first = Math.max(0, Math.ceil(centre - reach));
+    const last = Math.min(from - 1, Math.floor(centre + reach));
+    const weights = [];
+    for (let j = first; j <= last; j++) weights.push(lanczos3((j - centre) / stretch));
+    const total = weights.reduce((a, b) => a + b, 0);
+    return { first, weights: weights.map((w) => w / total) };
+  });
+}
+
+// Resize opaque RGBA8 with Lanczos-3, horizontal pass then vertical; alpha comes out 255.
+export function lanczosResize(src, sw, sh, dw, dh) {
+  if (sw === dw && sh === dh) return Buffer.from(src.buffer, src.byteOffset, src.byteLength);
+  const tx = taps(sw, dw), ty = taps(sh, dh);
+  const mid = new Float32Array(dw * sh * 3);
+  for (let y = 0; y < sh; y++) {
+    for (let x = 0; x < dw; x++) {
+      const { first, weights } = tx[x];
+      let r = 0, g = 0, b = 0;
+      for (let k = 0, at = (y * sw + first) * 4; k < weights.length; k++, at += 4) {
+        const w = weights[k];
+        r += src[at] * w; g += src[at + 1] * w; b += src[at + 2] * w;
+      }
+      const o = (y * dw + x) * 3;
+      mid[o] = r; mid[o + 1] = g; mid[o + 2] = b;
+    }
+  }
+  const out = Buffer.alloc(dw * dh * 4);
+  const byte = (v) => (v <= 0 ? 0 : v >= 255 ? 255 : Math.round(v));
+  for (let y = 0; y < dh; y++) {
+    const { first, weights } = ty[y];
+    for (let x = 0; x < dw; x++) {
+      let r = 0, g = 0, b = 0;
+      for (let k = 0; k < weights.length; k++) {
+        const at = ((first + k) * dw + x) * 3, w = weights[k];
+        r += mid[at] * w; g += mid[at + 1] * w; b += mid[at + 2] * w;
+      }
+      const o = (y * dw + x) * 4;
+      out[o] = byte(r); out[o + 1] = byte(g); out[o + 2] = byte(b); out[o + 3] = 255;
+    }
+  }
+  return out;
+}
+
+// Luma (0..255) box-averaged by an integer factor that brings the width near LUMA_WIDTH.
+export function lumaGrid(rgba, width, height) {
+  const f = Math.max(1, Math.round(width / LUMA_WIDTH));
+  const w = Math.floor(width / f), h = Math.floor(height / f);
+  const luma = new Float32Array(w * h);
+  for (let y = 0; y < h * f; y++) {
+    const row = Math.floor(y / f) * w;
+    for (let x = 0, at = y * width * 4; x < w * f; x++, at += 4) luma[row + Math.floor(x / f)] += 0.2126 * rgba[at] + 0.7152 * rgba[at + 1] + 0.0722 * rgba[at + 2];
+  }
+  for (let i = 0; i < luma.length; i++) luma[i] /= f * f;
+  return { luma, w, h };
+}
+
+export function crop(rgba, width, [x, y, w, h]) {
+  const out = Buffer.alloc(w * h * 4);
+  const src = Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength);
+  for (let row = 0; row < h; row++) src.copy(out, row * w * 4, ((y + row) * width + x) * 4, ((y + row) * width + x + w) * 4);
+  return out;
+}
+
+// SSIM on luma, averaged over non-overlapping 8x8 tiles (the classic constants for 8-bit data).
+export function ssim(a, b, width, height) {
+  const C1 = (0.01 * 255) ** 2, C2 = (0.03 * 255) ** 2, T = 8;
+  const Y = (px, i) => 0.2126 * px[i * 4] + 0.7152 * px[i * 4 + 1] + 0.0722 * px[i * 4 + 2];
+  let sum = 0, tiles = 0;
+  for (let ty = 0; ty + T <= height; ty += T) {
+    for (let tx = 0; tx + T <= width; tx += T) {
+      let ma = 0, mb = 0;
+      const va = new Float64Array(T * T), vb = new Float64Array(T * T);
+      for (let k = 0; k < T * T; k++) {
+        const i = (ty + Math.floor(k / T)) * width + tx + (k % T);
+        va[k] = Y(a, i); vb[k] = Y(b, i); ma += va[k]; mb += vb[k];
+      }
+      ma /= T * T; mb /= T * T;
+      let sa = 0, sb = 0, cov = 0;
+      for (let k = 0; k < T * T; k++) { const da = va[k] - ma, db = vb[k] - mb; sa += da * da; sb += db * db; cov += da * db; }
+      const n = T * T - 1;
+      sum += ((2 * ma * mb + C1) * (2 * cov / n + C2)) / ((ma * ma + mb * mb + C1) * (sa / n + sb / n + C2));
+      tiles++;
+    }
+  }
+  return tiles ? sum / tiles : 0;
+}

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

@@ -0,0 +1,36 @@
+// Cover init script: runs in every cover document before any page script. The film stage gives a
+// page a virtual clock; a cover page gets none, because a cover frame is a function of t alone and
+// the renderer seeks frames out of order. Every clock and every unseeded entropy source therefore
+// throws, and the call is remembered by name so the renderer can report it (exit 18) even when the
+// page caught the error. CSS animations and transitions would run on the wall clock: they are off.
+(function litCoverInit() {
+  'use strict';
+  const seen = [];
+  const refuse = (name, fix) => function refused() {
+    if (!seen.includes(name)) seen.push(name);
+    throw new Error(`${name} is not available in a cover page; ${fix}`);
+  };
+  const fromT = 'draw every frame from t';
+  Math.random = refuse('Math.random', 'use LitLoop.rng(seed) for layout and t for motion');
+  const NativeDate = Date;
+  function CoverDate(...args) {
+    if (!new.target || args.length === 0) return refuse('Date', fromT)();
+    return Reflect.construct(NativeDate, args, new.target);
+  }
+  CoverDate.prototype = NativeDate.prototype;
+  CoverDate.now = refuse('Date.now', fromT);
+  CoverDate.parse = NativeDate.parse;
+  CoverDate.UTC = NativeDate.UTC;
+  Object.defineProperty(window, 'Date', { value: CoverDate, writable: true, configurable: true });
+  Object.defineProperty(Performance.prototype, 'now', { value: refuse('performance.now', fromT), writable: true, configurable: true });
+  window.requestAnimationFrame = refuse('requestAnimationFrame', 'the renderer calls renderFrame(t); a cover runs no loop of its own');
+  window.setInterval = refuse('setInterval', 'the renderer calls renderFrame(t); a cover runs no loop of its own');
+  if (window.crypto) Object.defineProperty(window.crypto, 'getRandomValues', { value: refuse('crypto.getRandomValues', 'use LitLoop.rng(seed)'), configurable: true });
+  const still = () => {
+    const style = document.createElement('style');
+    style.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; }';
+    (document.head || document.documentElement).appendChild(style);
+  };
+  if (document.documentElement) still(); else document.addEventListener('readystatechange', still, { once: true });
+  window.__litCoverMisuse = () => seen.slice();
+})

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

@@ -0,0 +1,77 @@
+// A small PNG codec on node:zlib for cover mode, so the cover gate, the sheet and the tests read and
+// write frames without the runtime cache. It reads 8-bit grey, grey+alpha, RGB, RGBA and palette
+// images (non-interlaced, which is all Chrome, dwebp and this module write) and writes RGB.
+import { deflateSync, inflateSync } from 'node:zlib';
+
+const SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const CRC = new Int32Array(256).map((_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c; });
+const crc32 = (buf) => { let c = -1; for (const b of buf) c = CRC[(c ^ b) & 255] ^ (c >>> 8); return (c ^ -1) >>> 0; };
+
+function chunk(type, data) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, 'latin1');
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+  return Buffer.concat([head, data, tail]);
+}
+
+// RGBA8 (or RGB8 with channels 3) -> PNG bytes, colour type 2, filter "up" on every row.
+export function encodePng(pixels, width, height, { channels = 4, level = 6 } = {}) {
+  const stride = width * 3;
+  const raw = Buffer.alloc((stride + 1) * height);
+  let previous = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const row = Buffer.alloc(stride);
+    for (let x = 0; x < width; x++) for (let c = 0; c < 3; c++) row[x * 3 + c] = pixels[(y * width + x) * channels + c];
+    const at = y * (stride + 1);
+    raw[at] = 2;
+    for (let i = 0; i < stride; i++) raw[at + 1 + i] = (row[i] - previous[i]) & 255;
+    previous = row;
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 2;
+  return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw, { level })), chunk('IEND', Buffer.alloc(0))]);
+}
+
+const paeth = (a, b, c) => { const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c); return pa <= pb && pa <= pc ? a : pb <= pc ? b : c; };
+
+// PNG bytes -> { width, height, rgba }.
+export function decodePng(bytes) {
+  if (!bytes.subarray(0, 8).equals(SIGNATURE)) throw new Error('not a PNG file');
+  let width = 0, height = 0, depth = 0, type = 0, interlace = 0, palette = null, alpha = null;
+  const idat = [];
+  for (let at = 8; at + 8 <= bytes.length;) {
+    const length = bytes.readUInt32BE(at), name = bytes.toString('latin1', at + 4, at + 8), data = bytes.subarray(at + 8, at + 8 + length);
+    if (name === 'IHDR') { width = data.readUInt32BE(0); height = data.readUInt32BE(4); depth = data[8]; type = data[9]; interlace = data[12]; }
+    else if (name === 'PLTE') palette = data;
+    else if (name === 'tRNS') alpha = data;
+    else if (name === 'IDAT') idat.push(data);
+    else if (name === 'IEND') break;
+    at += 12 + length;
+  }
+  if (depth !== 8 || interlace) throw new Error(`unsupported PNG (bit depth ${depth}, interlace ${interlace})`);
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+  if (!channels) throw new Error(`unsupported PNG colour type ${type}`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const px = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const out = y * stride, up = out - stride;
+    for (let i = 0; i < stride; i++) {
+      const a = i >= channels ? px[out + i - channels] : 0, b = y ? px[up + i] : 0, c = y && i >= channels ? px[up + i - channels] : 0;
+      const v = line[i];
+      px[out + i] = (filter === 0 ? v : filter === 1 ? v + a : filter === 2 ? v + b : filter === 3 ? v + ((a + b) >> 1) : v + paeth(a, b, c)) & 255;
+    }
+  }
+  const rgba = Buffer.alloc(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    const o = i * 4, s = i * channels;
+    if (type === 3) { const k = px[s]; rgba[o] = palette[k * 3]; rgba[o + 1] = palette[k * 3 + 1]; rgba[o + 2] = palette[k * 3 + 2]; rgba[o + 3] = alpha && k < alpha.length ? alpha[k] : 255; }
+    else if (channels <= 2) { rgba[o] = rgba[o + 1] = rgba[o + 2] = px[s]; rgba[o + 3] = channels === 2 ? px[s + 1] : 255; }
+    else { rgba[o] = px[s]; rgba[o + 1] = px[s + 1]; rgba[o + 2] = px[s + 2]; rgba[o + 3] = channels === 4 ? px[s + 3] : 255; }
+  }
+  return { width, height, rgba };
+}

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

@@ -0,0 +1,70 @@
+// The cover's review image: decoded frames in a 4-wide grid above a plot of the whole loop's
+// frame-to-frame difference (one point per grid step), with the still threshold (red dashes) and
+// the median (green dots) drawn across it. The plot shows what single stills cannot: a hold is a
+// flat run on the dashes, encoder pops are regular spikes, a reset is a spike at the right end.
+// Drawn straight into pixels, like the film contact sheet, so it needs neither Chrome nor fonts;
+// each tile carries its loop time in seconds. `marks` shade spans of the plot (a window render).
+import { writeFileSync } from 'node:fs';
+import { COVER } from './constants.mjs';
+import { lanczosResize } from './cover-image.mjs';
+import { encodePng } from './cover-png.mjs';
+
+const GLYPHS = {
+  0: '111101101101111', 1: '010110010010111', 2: '111001111100111', 3: '111001111001111', 4: '101101111001001',
+  5: '111100111001111', 6: '111100111101111', 7: '111001001001001', 8: '111101111101111', 9: '111101111001111',
+  '.': '000000000000010', s: '011100010001110', '-': '000000111000000',
+};
+
+function fill(buf, W, x, y, w, h, [r, g, b], a = 1) {
+  for (let yy = Math.max(0, y); yy < y + h; yy++) for (let xx = Math.max(0, x); xx < Math.min(W, x + w); xx++) {
+    const o = (yy * W + xx) * 4;
+    if (o + 3 >= buf.length) return;
+    buf[o] = Math.round(buf[o] * (1 - a) + r * a); buf[o + 1] = Math.round(buf[o + 1] * (1 - a) + g * a); buf[o + 2] = Math.round(buf[o + 2] * (1 - a) + b * a); buf[o + 3] = 255;
+  }
+}
+
+function label(buf, W, x, y, text, scale = 3, colour = [235, 235, 225]) {
+  let cx = x;
+  for (const ch of String(text)) {
+    const glyph = GLYPHS[ch];
+    if (glyph) for (let i = 0; i < 15; i++) if (glyph[i] === '1') fill(buf, W, cx + (i % 3) * scale, y + Math.floor(i / 3) * scale, scale, scale, colour);
+    cx += 4 * scale;
+  }
+}
+
+function line(buf, W, x0, y0, x1, y1, colour, thick = 2) {
+  const n = Math.max(1, Math.ceil(Math.hypot(x1 - x0, y1 - y0)));
+  for (let k = 0; k <= n; k++) fill(buf, W, Math.round(x0 + ((x1 - x0) * k) / n) - (thick >> 1), Math.round(y0 + ((y1 - y0) * k) / n) - (thick >> 1), thick, thick, colour);
+}
+
+// tiles: [{ rgba, width, height, t }]; diffs: every grid step's d (the seam last); marks: [{ t0, t1 }]
+// in seconds of `durationSec`. Writes an RGB PNG and returns its size.
+export function writeCoverSheet({ file, tiles, diffs, medianD, durationSec, marks = [] }) {
+  const pad = 8, cols = 4, tileW = 400, tileH = Math.round((tileW * tiles[0].height) / tiles[0].width), cap = 24;
+  const rows = Math.ceil(tiles.length / cols);
+  const W = cols * tileW + (cols + 1) * pad;
+  const plotTop = rows * (tileH + cap + pad) + pad + 6, plotH = 170;
+  const H = plotTop + plotH + pad;
+  const buf = Buffer.alloc(W * H * 4);
+  fill(buf, W, 0, 0, W, H, [8, 11, 16]);
+  tiles.forEach((tile, k) => {
+    const x = pad + (k % cols) * (tileW + pad), y = pad + Math.floor(k / cols) * (tileH + cap + pad);
+    label(buf, W, x + 2, y + 4, `${tile.t.toFixed(2)}s`);
+    const small = lanczosResize(tile.rgba, tile.width, tile.height, tileW, tileH);
+    for (let row = 0; row < tileH; row++) small.copy(buf, ((y + cap + row) * W + x) * 4, row * tileW * 4, (row + 1) * tileW * 4);
+  });
+  const left = pad, width = W - 2 * pad;
+  fill(buf, W, left, plotTop, width, plotH, [17, 22, 29]);
+  for (const m of marks) {
+    const a = left + Math.round((m.t0 / durationSec) * width), b = left + Math.round((m.t1 / durationSec) * width);
+    fill(buf, W, a, plotTop, Math.max(2, b - a), plotH, [255, 176, 46], 0.18);
+  }
+  const top = Math.max(0.01, ...diffs) * 1.05;
+  const Y = (v) => Math.round(plotTop + plotH - 1 - (v / top) * (plotH - 2));
+  const X = (i) => Math.round(left + (i / Math.max(1, diffs.length - 1)) * (width - 1));
+  for (let x = left; x < left + width; x += 8) fill(buf, W, x, Y(COVER.stillEps), 4, 1, [170, 51, 51]);
+  for (let x = left; x < left + width; x += 5) fill(buf, W, x, Y(medianD), 2, 1, [85, 170, 136]);
+  for (let i = 1; i < diffs.length; i++) line(buf, W, X(i - 1), Y(diffs[i - 1]), X(i), Y(diffs[i]), [255, 122, 70]);
+  writeFileSync(file, encodePng(buf, W, H, { level: 6 }));
+  return { width: W, height: H };
+}