@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/png.mjs

@@ -0,0 +1,112 @@
+// Minimal PNG encode/decode with node:zlib, so stills, masks, sheets and preview frames never need
+// an image dependency. Encodes 8-bit grayscale, RGB and RGBA; decodes non-interlaced 8-bit PNGs.
+import { deflateSync, inflateSync } from "node:zlib";
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffers) {
+  let c = 0xffffffff;
+  for (const buf of buffers) for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const name = Buffer.from(type, "ascii");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32([name, data]));
+  return Buffer.concat([len, name, data, crc]);
+}
+
+const COLOR_TYPE = { 1: 0, 3: 2, 4: 6 };
+
+/** Encode `channels` (1 gray, 3 RGB, 4 RGBA) 8-bit pixels, rows top to bottom. */
+export function encodePng(pixels, width, height, channels = 4, { level = 6 } = {}) {
+  const stride = width * channels;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 1; // filter: Sub
+    const row = y * stride;
+    const out = y * (stride + 1) + 1;
+    for (let x = 0; x < stride; x++) raw[out + x] = (pixels[row + x] - (x >= channels ? pixels[row + x - channels] : 0)) & 0xff;
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = COLOR_TYPE[channels];
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw, { level })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/** RGBA -> RGB (drops alpha). */
+export function rgbaToRgb(rgba, width, height) {
+  const out = Buffer.alloc(width * height * 3);
+  for (let i = 0, j = 0; i < rgba.length; i += 4, j += 3) {
+    out[j] = rgba[i]; out[j + 1] = rgba[i + 1]; out[j + 2] = rgba[i + 2];
+  }
+  return out;
+}
+
+/** Decode an 8-bit non-interlaced PNG to { width, height, channels, pixels }. */
+export function decodePng(buf) {
+  if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error("not a PNG");
+  let off = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 0;
+  const idat = [];
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString("ascii", off + 4, off + 8);
+    const data = buf.subarray(off + 8, off + 8 + len);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      if (data[8] !== 8 || data[12] !== 0) throw new Error("only 8-bit non-interlaced PNG is supported");
+      channels = { 0: 1, 2: 3, 6: 4 }[data[9]];
+      if (!channels) throw new Error(`unsupported PNG colour type ${data[9]}`);
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    off += 12 + len;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const pixels = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const src = y * (stride + 1) + 1;
+    const dst = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? pixels[dst + x - channels] : 0;
+      const b = y > 0 ? pixels[dst - stride + x] : 0;
+      const c = x >= channels && y > 0 ? pixels[dst - stride + x - channels] : 0;
+      let v = raw[src + x];
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a);
+        const pb = Math.abs(p - b);
+        const pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      pixels[dst + x] = v & 0xff;
+    }
+  }
+  return { width, height, channels, pixels };
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/report.mjs

@@ -0,0 +1,66 @@
+// The MO-C-17 render report, written verbatim in structure to <out>/gate-report.txt, then one line
+// each for MO-C-25, MO-C-26, MO-C-27, MO-C-29, MO-D-02, MO-D-03 and MO-D-04, then one line per other
+// enforced MO-A / MO-SH / MO-FT rule in rule-index order.
+import { PROVISIONAL_RULES } from "../core/constants.mjs";
+
+const pad = (label) => `  ${label}`.padEnd(34);
+const verdict = (rule) => (rule ? `${rule.status}${rule.provisional ? " (provisional number)" : ""}` : "N/A");
+
+export function formatReport({ manifest, outputs, reason, gate, round, framesViewed, software, withheld }) {
+  const byId = new Map(gate.rules.map((x) => [x.id, x]));
+  const line = (id, label, text) => `${pad(`${id} ${label}:`)}${text ?? `${verdict(byId.get(id))} — ${byId.get(id)?.detail ?? "not evaluated"}`}`;
+  const flash = byId.get("MO-C-03");
+  const contrast = byId.get("MO-C-06");
+  const reading = byId.get("MO-C-07/08");
+  const det = byId.get("MO-C-09");
+  const floors = byId.get("MO-C-10/11/12");
+  const sizes = byId.get("MO-C-13");
+  const still = byId.get("MO-C-14");
+  const passes = (manifest.passRanges ?? []).map((p) => `${p.pass}@${p.sceneId}#${p.shotIndex}:${p.frameStart}-${p.frameEnd}`);
+  const lines = [
+    "lit-typographic-motion — render report",
+    `outputs: ${outputs.film} · ${outputs.preview} (encoder: ${manifest.previewEncoder ?? "none"}) · ${outputs.poster} · ${outputs.still}${withheld ? "  [WITHHELD: MO-C-03 flash audit failed; exports are diagnostics in withheld/, not deliverables]" : ""}`,
+    `preset: ${manifest.presetId}  (chosen because: ${reason})`,
+    `duration / fps / resolution: ${manifest.durationSec} s @ ${manifest.fps} fps, ${manifest.resolution[0] * manifest.scale}x${manifest.resolution[1] * manifest.scale}`,
+    `GLSL passes (manifest): ${passes.join(", ")}`,
+    `WebGL2: ${software ? "software" : "hardware"} — ${manifest.renderer}  (flags: ${manifest.chromeFlags.join(" ")})${software ? "  [software-rendered, --samples lowered to 1, tidal octaves and crt persistence downgraded]" : ""}`,
+    "",
+    `QA gate: ${gate.pass ? "PASS" : "FAIL"}`,
+    line("MO-C-01", "GLSL presence", `${verdict(byId.get("MO-C-01"))}`),
+    line("MO-C-02", "WebGL2 tier", `${verdict(byId.get("MO-C-02"))}`),
+    line("MO-C-03", "flash audit", `worst window ${flash?.worst ?? "?"} general / ${flash?.worstRed ?? "?"} red  (limit 3 / 3) — ${verdict(flash)}; ${flash?.detail ?? ""}`),
+    line("MO-C-04", "title-safe", `${verdict(byId.get("MO-C-04"))}  (${byId.get("MO-C-04")?.detail ?? ""})`),
+    line("MO-C-05", "action-safe", `${verdict(byId.get("MO-C-05"))}`),
+    line("MO-C-06", "type contrast", `${contrast?.detail ?? "not measured"} — ${verdict(contrast)}`),
+    line("MO-C-07/08", "reading time", `${reading?.detail ?? ""} — ${verdict(reading)}`),
+    line("MO-C-09", "determinism", `rgbaSha256 match ${det?.status === "PASS" ? "Y" : det?.status === "WARN" ? "Y (SwiftShader re-check)" : "N"}  (${det?.detail ?? ""})`),
+    line("MO-C-10/11/12", "duration/fps/res", `${verdict(floors)}  (${floors?.detail ?? ""})`),
+    line("MO-C-13", "file sizes", `${sizes?.detail ?? ""} — ${verdict(sizes)}`),
+    line("MO-C-14", "reduced-motion still", `${still?.detail ?? ""} — ${verdict(still)}`),
+    "",
+    `craft rounds run: ${round} / 3 max`,
+    `frames actually viewed this run: ${framesViewed ?? 0} (confirmed looked, not just rendered)`,
+    "",
+    "additional rules:",
+  ];
+  const extraOrder = ["MO-C-25", "MO-C-26", "MO-C-27", "MO-C-29", "MO-D-02", "MO-D-03", "MO-D-04"];
+  for (const id of extraOrder) lines.push(line(id, "", undefined).replace(/ :\s*/u, ": "));
+  const shown = new Set(["MO-C-01", "MO-C-02", "MO-C-03", "MO-C-04", "MO-C-05", "MO-C-06", "MO-C-07/08", "MO-C-09", "MO-C-10/11/12", "MO-C-13", "MO-C-14", ...extraOrder]);
+  for (const rule of gate.rules) if (!shown.has(rule.id)) lines.push(`${pad(`${rule.id}:`)}${verdict(rule)} — ${rule.detail}`);
+  lines.push("", `provisional numbers (spec [NEW] defaults awaiting sign-off, implemented as written): ${PROVISIONAL_RULES.join(", ")}`);
+  if (!gate.pass) lines.push(`failed rules: ${gate.failed.join(", ")}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatPreflightReport({ preflight, reason, presetId }) {
+  const lines = [
+    "lit-typographic-motion — render report (pre-flight)",
+    `preset: ${presetId}  (chosen because: ${reason})`,
+    "",
+    `QA gate: FAIL (pre-flight; no frame was rendered)`,
+    ...preflight.rules.map((x) => `${pad(`${x.id}:`)}${x.status} — ${x.detail}`),
+    "",
+    `failed rules: ${preflight.failed.join(", ")}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/runtime.mjs

@@ -0,0 +1,330 @@
+// The motion runtime: pinned engine dependencies, fetched fonts and the opt-in audio venv, all in a
+// LitClaude-owned cache (MO-A-42..55). This reuses the office runtime's cache mechanics (a cache
+// directory keyed by the lockfile, an mkdir lock, `npm ci --omit=dev --ignore-scripts`) but never
+// its first-use trigger: only `litclaude-ai motion-runtime install` and the installer's pre-warm
+// write here. A render only reads, and an unwarmed cache is BLOCKED 14, never a mid-session install.
+//
+//   $LITCLAUDE_MOTION_RUNTIME                               when set
+//   ${XDG_CACHE_HOME:-~/.cache}/litclaude/motion-runtime     otherwise
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+export const ENGINE_ROOT = path.join(SKILL_ROOT, "engine");
+export const FONT_ROOT = path.join(SKILL_ROOT, "fonts");
+const READY = ".litclaude-ready";
+const STALE_LOCK_MS = 20 * 60 * 1000;
+export const INSTALL_COMMAND = "litclaude-ai motion-runtime install";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const fileSha = (file) => sha256(readFileSync(file));
+
+export function runtimeRoot(env = process.env) {
+  if (env.LITCLAUDE_MOTION_RUNTIME) return path.resolve(env.LITCLAUDE_MOTION_RUNTIME);
+  const cacheHome = env.XDG_CACHE_HOME || path.join(homedir(), ".cache");
+  return path.join(cacheHome, "litclaude", "motion-runtime");
+}
+
+export function lockHash() {
+  const h = createHash("sha256");
+  for (const file of ["package.json", "package-lock.json"]) h.update(readFileSync(path.join(ENGINE_ROOT, file)));
+  return h.digest("hex");
+}
+
+export const nodeDir = (env) => path.join(runtimeRoot(env), `node-${lockHash().slice(0, 12)}-${process.platform}-${process.arch}`);
+export const fontsDir = (env) => path.join(runtimeRoot(env), "fonts");
+export const opentypeModule = (env) => path.join(nodeDir(env), "node_modules", "opentype.js", "dist", "opentype.mjs");
+
+export function loadFontManifest() {
+  return JSON.parse(readFileSync(path.join(FONT_ROOT, "manifest.json"), "utf8"));
+}
+
+/** Where a font's bytes live after install (bundled, reused lit-pptx file, or the cache). */
+export function fontLocation(key, font, env) {
+  if (font.source === "bundled") return path.join(FONT_ROOT, font.path);
+  if (font.source === "reuse") {
+    const reused = path.resolve(FONT_ROOT, font.path);
+    if (existsSync(reused)) return reused;
+    return path.join(fontsDir(env), font.fallback.file);
+  }
+  return path.join(fontsDir(env), font.file);
+}
+
+/** Verify one font and its licence files. Returns { key, ok, problem, path }. */
+export function checkFont(key, font, env) {
+  const file = fontLocation(key, font, env);
+  const expected = font.source === "reuse" && !existsSync(path.resolve(FONT_ROOT, font.path)) ? font.fallback.sha256 : font.sha256;
+  if (!existsSync(file)) return { key, ok: false, problem: "missing", path: file };
+  if (fileSha(file) !== expected) return { key, ok: false, problem: "sha256 mismatch", path: file };
+  const licences = font.source === "fetch" ? font.licence.map((l) => ({ file: path.join(fontsDir(env), l.file), sha256: l.sha256 }))
+    : font.source === "reuse" && !existsSync(path.resolve(FONT_ROOT, font.path)) ? font.fallback.licence.map((l) => ({ file: path.join(fontsDir(env), l.file), sha256: l.sha256 }))
+      : font.licence.map((l) => ({ file: path.resolve(FONT_ROOT, l.path), sha256: l.sha256 }));
+  for (const l of licences) {
+    if (!existsSync(l.file)) return { key, ok: false, problem: `licence file missing: ${path.basename(l.file)}`, path: file };
+    if (fileSha(l.file) !== l.sha256) return { key, ok: false, problem: `licence file sha256 mismatch: ${path.basename(l.file)}`, path: file };
+  }
+  return { key, ok: true, problem: null, path: file };
+}
+
+export function nodeStatus(env) {
+  const dir = nodeDir(env);
+  let marker = null;
+  try {
+    marker = JSON.parse(readFileSync(path.join(dir, READY), "utf8"));
+  } catch {
+    marker = null;
+  }
+  const expected = lockHash();
+  const ready = Boolean(marker) && marker.lockHash === expected && existsSync(opentypeModule(env));
+  const pinned = JSON.parse(readFileSync(path.join(ENGINE_ROOT, "package.json"), "utf8")).dependencies;
+  return { ready, dir, pinned, problem: ready ? null : marker && marker.lockHash !== expected ? "lockfile hash differs from the installed one" : "not installed" };
+}
+
+// ---- audio (Tier 2) ----
+const AUDIO_LOCK = path.join(ENGINE_ROOT, "audio", "requirements.lock");
+const venvPython = (dir) => (process.platform === "win32" ? path.join(dir, "Scripts", "python.exe") : path.join(dir, "bin", "python"));
+
+export function pythonCommand(env = process.env) {
+  return env.LITCLAUDE_MOTION_PYTHON || "python3";
+}
+
+function probePython(env) {
+  const probe = spawnSync(pythonCommand(env), ["-c", "import sys; print('%d.%d' % sys.version_info[:2])"], { encoding: "utf8" });
+  return probe.status === 0 ? probe.stdout.trim() : null;
+}
+
+export function audioDir(env, version = probePython(env)) {
+  const key = createHash("sha256").update(readFileSync(AUDIO_LOCK)).update(`${process.platform}-${process.arch}-py${version ?? "none"}`).digest("hex").slice(0, 12);
+  return path.join(runtimeRoot(env), `audio-${key}`);
+}
+
+/** 'absent' (never created), 'ready', or 'mismatch' (a venv whose pins no longer match). */
+export function audioStatus(env) {
+  const root = runtimeRoot(env);
+  const expected = fileSha(AUDIO_LOCK);
+  const dir = audioDir(env);
+  let marker = null;
+  try {
+    marker = JSON.parse(readFileSync(path.join(dir, READY), "utf8"));
+  } catch {
+    marker = null;
+  }
+  if (marker && marker.lockSha256 === expected && existsSync(venvPython(dir))) return { state: "ready", dir, python: venvPython(dir) };
+  if (marker || (existsSync(root) && existsSync(dir))) return { state: "mismatch", dir, python: venvPython(dir) };
+  return { state: "absent", dir, python: null };
+}
+
+export const AUDIO_WARNING = `audio analysis not prewarmed: run ${INSTALL_COMMAND} --audio`;
+
+// ---- word timing (Tier 3) ----
+export function loadWordTiming() {
+  return JSON.parse(readFileSync(path.join(ENGINE_ROOT, "models", "word-timing.json"), "utf8"));
+}
+
+export function wordTimingStatus() {
+  const doc = loadWordTiming();
+  return { state: doc.alignerRuntime.status === "ready" ? "ready" : "absent", reason: "the Tier-3 aligner runtime is not part of this release", totalBytes: doc.totalBytes };
+}
+
+export function licenceVerdict(license, doc = loadWordTiming()) {
+  const l = String(license ?? "").toLowerCase();
+  if (doc.deniedLicensePatterns.some((p) => l.includes(p))) return "denied";
+  return doc.allowedLicenses.includes(l) ? "allowed" : "unknown";
+}
+
+// ---- status ----
+
+/** Required font keys for a preset (all presets when omitted). */
+export function requiredFonts(presetVoices) {
+  const keys = new Set();
+  for (const voices of presetVoices) for (const v of Object.values(voices)) {
+    for (const k of [v.latin, v.hangul, ...(v.weightSteps ?? [])]) if (k) keys.add(k);
+    if (v.latin?.startsWith("archivo-")) for (const w of v.latinWidths ?? [100]) keys.add(`archivo-${w}-${v.latin.split("-")[2]}`);
+  }
+  return [...keys];
+}
+
+export function runtimeStatus({ env = process.env, fontKeys } = {}) {
+  const manifest = loadFontManifest();
+  const keys = fontKeys ?? Object.keys(manifest.fonts);
+  const fonts = keys.map((key) => checkFont(key, manifest.fonts[key], env));
+  const node = nodeStatus(env);
+  const missing = [
+    ...(node.ready ? [] : [`engine deps (${Object.entries(node.pinned).map(([k, v]) => `${k} ${v}`).join(", ")}): ${node.problem}`]),
+    ...fonts.filter((f) => !f.ok).map((f) => `font ${f.key}: ${f.problem}`),
+  ];
+  return { root: runtimeRoot(env), node, fonts, audio: audioStatus(env), wordTiming: wordTimingStatus(), ready: missing.length === 0, missing, command: INSTALL_COMMAND };
+}
+
+export function formatStatus(status) {
+  const lines = [`motion runtime root: ${status.root}`];
+  lines.push(`engine deps: ${status.node.ready ? `ready (${Object.entries(status.node.pinned).map(([k, v]) => `${k} ${v}`).join(", ")})` : `missing (${status.node.problem})`}`);
+  const bad = status.fonts.filter((f) => !f.ok);
+  lines.push(`fonts: ${bad.length === 0 ? `ready (${status.fonts.length} verified by sha256)` : `missing or mismatched: ${bad.map((f) => `${f.key} (${f.problem})`).join(", ")}`}`);
+  lines.push(`audio tier (optional): ${status.audio.state === "ready" ? "ready" : status.audio.state === "mismatch" ? `venv pins no longer match; Tier 1 is used; run ${INSTALL_COMMAND} --audio` : `not installed; Tier 1 is used; run ${INSTALL_COMMAND} --audio to enable`}`);
+  lines.push(`word timing (optional, --word-timing): ${status.wordTiming.state === "ready" ? "ready" : status.wordTiming.reason}`);
+  lines.push(status.ready ? "pre-warm: ready" : `pre-warm: NOT READY — run ${INSTALL_COMMAND}`);
+  return lines;
+}
+
+// ---- install ----
+
+function withLock(root, fn) {
+  mkdirSync(root, { recursive: true });
+  const lock = path.join(root, ".install.lock");
+  const deadline = Date.now() + STALE_LOCK_MS;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let age = 0;
+      try { age = Date.now() - statSync(lock).mtimeMs; } catch { continue; }
+      if (age > STALE_LOCK_MS) { rmSync(lock, { recursive: true, force: true }); continue; }
+      if (Date.now() > deadline) throw new Error(`MOTION_RUNTIME_LOCKED: ${lock} is held by another installer`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 500);
+    }
+  }
+  return Promise.resolve().then(fn).finally(() => rmSync(lock, { recursive: true, force: true }));
+}
+
+/** Fetch bytes from an http(s) or file URL. A mirror (tests, air-gapped hosts) serves files by sha256. */
+async function fetchBytes(url, { sha256: expected, env }) {
+  const mirror = env.LITCLAUDE_MOTION_MIRROR;
+  const source = mirror && expected ? `${mirror.replace(/\/$/u, "")}/${expected}` : url;
+  let bytes;
+  if (source.startsWith("file://")) bytes = readFileSync(fileURLToPath(source));
+  else {
+    const response = await fetch(source, { signal: AbortSignal.timeout(120000) });
+    if (!response.ok) throw new Error(`HTTP ${response.status} for ${source}`);
+    bytes = Buffer.from(await response.arrayBuffer());
+  }
+  if (expected && sha256(bytes) !== expected) throw new Error(`sha256 mismatch for ${url} (expected ${expected}, got ${sha256(bytes)})`);
+  return bytes;
+}
+
+function writeAtomic(file, bytes) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.part-${process.pid}`;
+  writeFileSync(tmp, bytes);
+  renameSync(tmp, file);
+}
+
+export async function installFonts({ env = process.env, log = () => {} } = {}) {
+  const manifest = loadFontManifest();
+  const done = [];
+  for (const [key, font] of Object.entries(manifest.fonts)) {
+    const needsFetch = font.source === "fetch" || (font.source === "reuse" && !existsSync(path.resolve(FONT_ROOT, font.path)));
+    if (!needsFetch) continue;
+    const spec = font.source === "fetch" ? font : font.fallback;
+    const status = checkFont(key, font, env);
+    if (status.ok) {
+      done.push(key);
+      continue;
+    }
+    log(`fetching ${key} (${spec.bytes ?? "?"} bytes) from ${spec.url}`);
+    writeAtomic(path.join(fontsDir(env), spec.file), await fetchBytes(spec.url, { sha256: spec.sha256, env }));
+    for (const l of spec.licence) writeAtomic(path.join(fontsDir(env), l.file), await fetchBytes(l.url, { sha256: l.sha256, env }));
+    const after = checkFont(key, font, env);
+    if (!after.ok) throw new Error(`font ${key} failed verification after fetch: ${after.problem}`);
+    done.push(key);
+  }
+  return done;
+}
+
+function npm(args, options) {
+  const bin = process.platform === "win32" ? "npm.cmd" : "npm";
+  return spawnSync(bin, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options });
+}
+
+export async function installNode({ env = process.env, log = () => {} } = {}) {
+  const status = nodeStatus(env);
+  if (status.ready) return status;
+  const dir = status.dir;
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  for (const file of ["package.json", "package-lock.json"]) copyFileSync(path.join(ENGINE_ROOT, file), path.join(dir, file));
+  log(`installing pinned engine packages (${Object.entries(status.pinned).map(([k, v]) => `${k} ${v}`).join(", ")}) into ${dir}`);
+  const args = ["ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund", "--loglevel=error"];
+  let cache = null;
+  if (env.LITCLAUDE_MOTION_MIRROR) {
+    cache = path.join(tmpdir(), `lit-motion-npm-${process.pid}-${Date.now()}`);
+    const lock = JSON.parse(readFileSync(path.join(ENGINE_ROOT, "package-lock.json"), "utf8"));
+    for (const [name, pkg] of Object.entries(lock.packages)) {
+      if (!name) continue;
+      const integrity = Buffer.from(pkg.integrity.replace(/^sha512-/u, ""), "base64").toString("hex");
+      const mirror = env.LITCLAUDE_MOTION_MIRROR.replace(/\/$/u, "");
+      const source = `${mirror}/${path.basename(new URL(pkg.resolved).pathname)}`;
+      const bytes = source.startsWith("file://") ? readFileSync(fileURLToPath(source)) : Buffer.from(await (await fetch(source)).arrayBuffer());
+      if (createHash("sha512").update(bytes).digest("hex") !== integrity) throw new Error(`integrity mismatch for ${name}`);
+      const tarball = path.join(cache, path.basename(new URL(pkg.resolved).pathname));
+      writeAtomic(tarball, bytes);
+      const add = npm(["cache", "add", tarball, "--cache", cache], { env: { ...env } });
+      if (add.status !== 0) throw new Error(`npm cache add failed: ${add.stderr.trim().slice(-400)}`);
+    }
+    args.push("--offline", "--cache", cache);
+  }
+  const result = npm(args, { cwd: dir, env: { ...env } });
+  if (cache) rmSync(cache, { recursive: true, force: true });
+  if (result.error || result.status !== 0) {
+    rmSync(dir, { recursive: true, force: true });
+    throw new Error(`npm ci exited ${result.status}: ${(result.stderr || result.error?.message || "").trim().slice(-600)}`);
+  }
+  writeFileSync(path.join(dir, READY), `${JSON.stringify({ lockHash: lockHash(), pinned: status.pinned })}\n`);
+  return nodeStatus(env);
+}
+
+export async function installAudio({ env = process.env, log = () => {} } = {}) {
+  const version = probePython(env);
+  if (!version) throw new Error(`${pythonCommand(env)} was not found; install Python 3.10+ or set LITCLAUDE_MOTION_PYTHON`);
+  const dir = audioDir(env, version);
+  const current = audioStatus(env);
+  if (current.state === "ready") return current;
+  rmSync(dir, { recursive: true, force: true });
+  log(`creating the audio venv (Python ${version}, librosa and its hash-pinned wheels) in ${dir}`);
+  const venv = spawnSync(pythonCommand(env), ["-m", "venv", dir], { encoding: "utf8" });
+  if (venv.status !== 0) throw new Error(`python -m venv failed: ${(venv.stderr || "").trim().slice(-400)}`);
+  const pip = spawnSync(venvPython(dir), ["-m", "pip", "install", "--require-hashes", "--only-binary=:all:", "--no-input", "--disable-pip-version-check", "--quiet", "-r", AUDIO_LOCK], { encoding: "utf8", env: { ...env } });
+  if (pip.status !== 0) {
+    rmSync(dir, { recursive: true, force: true });
+    throw new Error(`pip install --require-hashes failed: ${(pip.stderr || "").trim().slice(-600)}`);
+  }
+  writeFileSync(path.join(dir, READY), `${JSON.stringify({ lockSha256: fileSha(AUDIO_LOCK), python: version })}\n`);
+  return audioStatus(env);
+}
+
+/**
+ * The word-timing plan: download size, every pin and its licence verdict. Printed before anything
+ * else; with no aligner runtime in this release, nothing is downloaded after it.
+ */
+export function wordTimingPlan() {
+  const doc = loadWordTiming();
+  const lines = [`word timing: ${(doc.totalBytes / 1e9).toFixed(2)} GB to download (${doc.models.length} models):`];
+  const verdicts = [];
+  for (const m of doc.models) {
+    const verdict = licenceVerdict(m.license, doc);
+    verdicts.push(verdict);
+    lines.push(`  ${m.id} @ ${m.revision} — licence ${m.license} (${verdict}) — ${(m.bytes / 1e6).toFixed(0)} MB — ${m.role}`);
+  }
+  const blocked = verdicts.some((v) => v !== "allowed");
+  lines.push(blocked ? "word timing: a model licence is not on the allowed list; failing closed" : "word timing: every pinned licence is permissive");
+  lines.push("word timing: the aligner runtime is not part of this release; nothing was downloaded (Tier 3 stays opt-in and unavailable)");
+  return { lines, blocked: true, licenceBlocked: blocked };
+}
+
+/** Pre-warm: engine deps, then fonts, then the optional audio tier. */
+export async function installRuntime({ env = process.env, audio = false, log = () => {} } = {}) {
+  const root = runtimeRoot(env);
+  return withLock(root, async () => {
+    const node = await installNode({ env, log });
+    const fonts = await installFonts({ env, log });
+    const result = { root, node, fonts, audio: null };
+    if (audio) result.audio = await installAudio({ env, log });
+    return result;
+  });
+}

package/plugins/litclaude/skills/lit-typographic-motion/engine/node/session.mjs

@@ -0,0 +1,145 @@
+// One render session: the page served from the skill directory and the runtime cache, headless
+// Chrome on the first WebGL2 rung, and frame egress. The WebSocket on 127.0.0.1:0 is the primary
+// path; when `listen` is refused (a sandbox), frames are pulled over CDP from the same readback
+// buffer instead (the sanctioned MO-A-02 variant). The screencast path is never used.
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { APP_ORIGIN, launchWithLadder, findChrome } from "./chrome.mjs";
+import { startFrameServer } from "./ws-server.mjs";
+import { ENGINE_ROOT, loadFontManifest, fontLocation, opentypeModule } from "./runtime.mjs";
+
+function faultListen(env) {
+  if (env.LITCLAUDE_MOTION_FAULT !== "listen-eperm") return null;
+  return () => {
+    const error = new Error("listen EPERM: operation not permitted 127.0.0.1");
+    error.code = "EPERM";
+    throw error;
+  };
+}
+
+/** Plan sent to the page: shots, timing, preset, fonts and the egress endpoint. */
+function pagePlan(plan, { fontKeys, ws }) {
+  const manifest = loadFontManifest();
+  return {
+    presetId: plan.presetId, signalHue: plan.signalHue, fps: plan.fps, seed: plan.seed, frameCount: plan.frameCount,
+    durationSec: plan.durationSec, label: plan.label, passParams: plan.passParams, post: plan.post,
+    shots: plan.shots.map((s) => ({ ...s, reading: undefined })),
+    fonts: fontKeys.map((key) => ({ key, format: manifest.fonts[key].format, weight: manifest.fonts[key].weight, scripts: manifest.fonts[key].scripts, file: path.basename(manifest.fonts[key].path ?? manifest.fonts[key].file) })),
+    egress: { ws },
+  };
+}
+
+export async function openSession({ plan, fontKeys, runDir, env = process.env, softwareOnly = false, log = () => {} }) {
+  mkdirSync(runDir, { recursive: true });
+  const manifest = loadFontManifest();
+  let planJson = "{}";
+  const routes = (pathname) => {
+    if (pathname === "/run/plan.json") return { body: planJson, type: "application/json" };
+    if (pathname === "/vendor/opentype.mjs") return opentypeModule(env);
+    if (pathname.startsWith("/fonts/")) {
+      const key = pathname.slice("/fonts/".length);
+      return manifest.fonts[key] ? fontLocation(key, manifest.fonts[key], env) : null;
+    }
+    if (pathname.startsWith("/web/") || pathname.startsWith("/core/")) {
+      const file = path.resolve(ENGINE_ROOT, `.${pathname}`);
+      if (!file.startsWith(path.join(ENGINE_ROOT, path.sep)) || !existsSync(file)) return null;
+      return file;
+    }
+    return null;
+  };
+
+  // Egress first: a refused listen selects the CDP pull and says why.
+  const queue = [];
+  const waiters = [];
+  let pendingMeta = null;
+  let server = null;
+  let listenError = null;
+  try {
+    server = await startFrameServer({
+      onText: (text) => { pendingMeta = JSON.parse(text); },
+      onBinary: (bytes) => {
+        queue.push({ meta: pendingMeta, bytes });
+        pendingMeta = null;
+        const w = waiters.shift();
+        if (w) w();
+      },
+      listen: faultListen(env),
+    });
+  } catch (error) {
+    listenError = error;
+    log(`egress: listen failed (${error.message}); using CDP pull of the readback buffer`);
+  }
+
+  const chrome = findChrome(env);
+  let launched;
+  try {
+    launched = await launchWithLadder({ chrome, profileRoot: path.join(runDir, "chrome"), routes, softwareOnly, log });
+  } catch (error) {
+    await server?.close();
+    throw error;
+  }
+  const { session, flags, renderer } = launched;
+  planJson = JSON.stringify(pagePlan(plan, { fontKeys, ws: server?.url ?? null }));
+  await session.navigate(`${APP_ORIGIN}/web/index.html`);
+  const deadline = Date.now() + 120000;
+  let state;
+  for (;;) {
+    state = await session.evaluate("({ ready: window.__litMotion?.ready ?? false, error: window.__litMotion?.error ?? null })").catch(() => ({ ready: false, error: null }));
+    if (state.ready || state.error) break;
+    if (Date.now() > deadline) {
+      state.error = `page did not become ready: ${session.logs.slice(0, 5).join(" | ")}`;
+      break;
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  if (state.error) {
+    await session.close();
+    await server?.close();
+    throw new Error(`engine page failed: ${state.error}\n${session.logs.slice(0, 20).join("\n")}`);
+  }
+  const info = await session.evaluate("window.__litMotion.info()");
+  if (server && info.egress !== "websocket") log("egress: page could not open the WebSocket; using CDP pull");
+
+  /**
+   * Render frames [from, to) and hand each (meta, bytes) to `onFrame` in order. In WebSocket mode
+   * the ack is sent after onFrame resolves, which bounds how far the page runs ahead.
+   */
+  async function render({ from, to, fps, samples, shutter, stillOverrides = null, tag }, onFrame) {
+    const opts = JSON.stringify({ from, to, fps, samples, shutter, stillOverrides, tag });
+    if (info.egress === "websocket") {
+      let failure = null;
+      const streaming = session.evaluate(`window.__litMotion.stream(${opts})`).catch((error) => {
+        failure = error;
+        while (waiters.length) waiters.shift()();
+      });
+      for (let n = from; n < to; n++) {
+        while (queue.length === 0 && !failure) await new Promise((r) => waiters.push(r));
+        if (failure) throw failure;
+        const frame = queue.shift();
+        await onFrame(frame.meta, frame.bytes);
+        server.ack("ok");
+      }
+      await streaming;
+      if (failure) throw failure;
+      return;
+    }
+    for (let n = from; n < to; n++) {
+      await session.evaluate(`window.__litMotion.frame(${JSON.stringify({ n, fps, samples, shutter, stillOverrides, tag })})`);
+      const pulled = await session.evaluate("window.__litMotion.pull()");
+      await onFrame(pulled.meta, Buffer.from(pulled.b64, "base64"));
+    }
+  }
+
+  return {
+    session, flags, renderer, info,
+    egress: info.egress === "websocket" ? "websocket (127.0.0.1:0, pipe-driven Chrome)" : `CDP pull of the readback buffer${listenError ? ` (listen refused: ${listenError.message})` : ""}`,
+    listenError,
+    render,
+    perf: (frames, fps) => session.evaluate(`window.__litMotion.perf(${JSON.stringify({ frames, fps })})`),
+    async close() {
+      await session.close();
+      await server?.close();
+      rmSync(path.join(runDir, "chrome"), { recursive: true, force: true });
+    },
+  };
+}