@litfamily/lithermes 1.0.27 → 1.0.28

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

@@ -0,0 +1,118 @@
+// Child processes that survive Windows. Since the CVE-2024-27980 fix, Node refuses to spawn a
+// .cmd or .bat file without a shell (spawnSync npm.cmd EINVAL), and PATH lookups there depend on
+// PATHEXT. Platform, env and fs probes are arguments so tests can simulate win32 without
+// touching globals. Every skill that spawns tools carries a byte-identical copy of this file.
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+
+const SHELL_SCRIPT = /\.(?:cmd|bat)$/i;
+const SAFE_ARG = /^[\w@+=:,./\\-]+$/;
+
+export function whichSync(name, { platform = process.platform, env = process.env, exists = existsSync } = {}) {
+  const win = platform === 'win32';
+  const p = win ? win32 : posix;
+  const exts = win ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').map((e) => e.trim().toLowerCase()).filter(Boolean) : [''];
+  const hasExt = win && exts.some((e) => name.toLowerCase().endsWith(e.toLowerCase()));
+  // A bare name never matches on Windows: npm leaves an extensionless sh script beside npm.cmd.
+  const names = win ? (hasExt ? [name] : exts.map((e) => name + e)) : [name];
+  const dirs = p.isAbsolute(name) || /[\\/]/.test(name) ? [''] : String(env.PATH ?? env.Path ?? '').split(win ? ';' : ':').map((d) => d.trim().replace(/^"|"$/g, '')).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of names) {
+      const full = dir ? p.join(dir, candidate) : candidate;
+      if (exists(full)) return full;
+    }
+  }
+  return null;
+}
+
+// Quoted for cmd.exe, which still expands %VAR% inside quotes, so those are refused, never escaped.
+export function quoteCmdArg(arg) {
+  const text = String(arg);
+  if (/["%\r\n\0]/.test(text)) throw new Error(`refusing an argument with a quote, percent sign or line break on a Windows shell: ${JSON.stringify(text.slice(0, 40))}`);
+  if (text !== '' && SAFE_ARG.test(text)) return text;
+  return `"${text.replace(/\\+$/, (run) => run + run)}"`;
+}
+
+// Where an npm or npx shim's JavaScript entry lives, so Windows can run it with node directly.
+function npmCli(name, resolved, { env, execPath, exists }) {
+  const cli = `${name}-cli.js`;
+  const dirs = [];
+  if (typeof env.npm_execpath === 'string' && /\.js$/i.test(env.npm_execpath)) dirs.push(win32.dirname(env.npm_execpath));
+  dirs.push(win32.join(win32.dirname(resolved), 'node_modules', 'npm', 'bin'));
+  dirs.push(win32.join(win32.dirname(execPath), 'node_modules', 'npm', 'bin'));
+  return dirs.map((dir) => win32.join(dir, cli)).find((file) => exists(file)) || null;
+}
+
+export function prepareSpawn(command, args = [], options = {}, ctx = {}) {
+  const { platform = process.platform, execPath = process.execPath, exists = existsSync } = ctx;
+  if (platform !== 'win32') return { command, args, options };
+  const env = ctx.env || options.env || process.env;
+  const resolved = whichSync(command, { platform, env, exists });
+  if (!resolved || !SHELL_SCRIPT.test(resolved)) return { command: resolved || command, args, options };
+  const base = win32.basename(resolved).replace(SHELL_SCRIPT, '').toLowerCase();
+  if (base === 'npm' || base === 'npx') {
+    const cli = npmCli(base, resolved, { env, execPath, exists });
+    if (cli) return { command: execPath, args: [cli, ...args], options };
+  }
+  const line = [resolved, ...args].map(quoteCmdArg).join(' ');
+  return { command: line, args: [], options: { ...options, shell: true } };
+}
+
+export function spawnTool(command, args, options, ctx = {}) {
+  const run = ctx.spawnSync || nodeSpawnSync;
+  const prepared = prepareSpawn(command, args, options, ctx);
+  return run(prepared.command, prepared.args, prepared.options);
+}
+
+// One line naming the real cause: the spawn error, the exit status and the last stderr line.
+export function describeSpawnFailure(label, result, { limit = 200 } = {}) {
+  if (!result) return `${label} returned no result`;
+  const tail = String(result.stderr || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) || '';
+  const clean = tail.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, limit);
+  if (result.error) return `${label} could not run: ${result.error.code || 'error'} ${result.error.message}${clean ? ` (${clean})` : ''}`;
+  if (result.signal) return `${label} stopped by ${result.signal}${clean ? ` (${clean})` : ''}`;
+  return `${label} exited ${result.status}${clean ? `: ${clean}` : ''}`;
+}
+
+// Interpreter inside a venv: Scripts\python.exe on Windows, bin/python elsewhere.
+export function venvPython(dir, platform = process.platform) {
+  return platform === 'win32' ? win32.join(dir, 'Scripts', 'python.exe') : posix.join(dir, 'bin', 'python');
+}
+
+// The newest CPython the Office wheels ship for (pip runs --only-binary); 3.15 has no PyYAML wheel,
+// so a python3 that is 3.15 is passed over. A caller whose lock is narrower passes its own max.
+export const PYTHON_MAX = [3, 14];
+
+export function probePython(command, env = process.env, spawn = spawnTool) {
+  const result = spawn(command, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'], { encoding: 'utf8', env, timeout: 10000 });
+  if (!result || result.error || result.status !== 0) return null;
+  const version = String(result.stdout || '').trim();
+  const [major, minor] = version.split('.').map(Number);
+  return Number.isInteger(major) && Number.isInteger(minor) ? { version, major, minor } : null;
+}
+
+// The host Python a pinned venv is built from. An override variable, when set, is the only
+// candidate and is not range-checked. Otherwise the newest python3.X from `max` down to `min`,
+// then python3 and python, each kept only when it runs and falls inside min..max.
+// Returns { python, version } or { python: null, detail } naming what was tried.
+export function pickPython({ env = process.env, override, min = [3, 10], max = PYTHON_MAX, probe = probePython } = {}) {
+  if (override && env[override]) {
+    const found = probe(env[override], env);
+    return found ? { python: env[override], version: found.version } : { python: null, detail: `${override} is set to ${env[override]}, which does not run` };
+  }
+  const candidates = [];
+  for (let minor = max[1]; minor >= min[1]; minor -= 1) candidates.push(`python3.${minor}`);
+  candidates.push('python3', 'python');
+  const tried = [];
+  for (const command of candidates) {
+    const found = probe(command, env);
+    if (!found) continue;
+    const inRange = (found.major > min[0] || (found.major === min[0] && found.minor >= min[1]))
+      && (found.major < max[0] || (found.major === max[0] && found.minor <= max[1]));
+    if (inRange) return { python: command, version: found.version };
+    tried.push(`${command} ${found.version}`);
+  }
+  const range = `${min.join('.')} to ${max.join('.')}`;
+  return { python: null, detail: `no supported Python (${range}) on PATH${tried.length ? `; found only ${tried.join(', ')}` : ''}` };
+}

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

@@ -9,6 +9,9 @@ import { join, resolve } from 'node:path';
 import { checkCompletion } from './completion.mjs';
 import { writeJson } from './director.mjs';
 import { validateTreatment } from './treatment.mjs';
+import { COVER } from './constants.mjs';
+import { generatedLabels } from './cover-assets.mjs';
+import { isCoverTreatment, validateCoverTreatment } from './cover-treatment.mjs';
 
 const sha = (data) => createHash('sha256').update(data).digest('hex');
 const usage = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -26,6 +29,21 @@ export const QUESTIONS = Object.freeze({
 });
 const NEED_YES = new Set([1, 2, 3, 5, 6]);
 const NEED_NO = new Set([4, 8, 9]);
+// Cover mode asks its own eight (references/cover.md): motion in every half second, the seam,
+// motion that survives the encoder, the brand word, the three layers, slide-likeness, damage,
+// and what a skilled motion designer would change.
+export const COVER_QUESTIONS = Object.freeze({
+  1: 'Is something moving in every half-second window (the plot never lies flat on the red dashes)?',
+  2: 'Does the seam disappear in the decoded file (seam.png, the right end of the plot)?',
+  3: 'Does it still move after encoding, with no region that freezes and then pops?',
+  4: 'Is the brand word present, legible and in place in every frame, never faded or swapped?',
+  5: 'Are all three speed layers visible: a slow perpetual layer, a mid swell and beat events?',
+  6: 'Does anything read as a slide, a card swap, a title fade or an end card, or does light wash in place instead of travelling as an edge?',
+  7: 'Is any glyph, glint or glow damaged: a colour block, a dark disc, a visible box?',
+  8: 'Name one thing a skilled motion designer would add or remove, or none.',
+});
+const COVER_NEED_YES = new Set([1, 2, 3, 4, 5]);
+const COVER_NEED_NO = new Set([6, 7]);
 const BARE = /^(?:yes|no|y|n|ok|okay|none|n\/a|네|예|아니오|아니요|아니|응|없음|있음)[.!]?$/iu;
 
 export function verdictOf(value) {
@@ -78,6 +96,8 @@ export function recordLook(out, round, answers) {
   }
 
   const files = new Map(set.files.map((f) => [f.file, f]));
+  const cover = set.mode === 'cover';
+  if (!cover && answers.defects !== undefined) throw usage('defects are a cover-mode record; a film round names its weakest beat in "change"');
   const viewed = [...new Set(answers.viewed || [])];
   if (!viewed.length) throw usage('list every stills file you viewed in "viewed"');
   const answerList = Array.isArray(answers.answers) ? answers.answers : [];
@@ -88,16 +108,23 @@ export function recordLook(out, round, answers) {
     if (onDisk !== files.get(file).sha256) throw usage(`${file} changed after the stills set was written; render again`);
     if (viewed.includes(file)) frames.push({ file, sha256: onDisk });
   }
-  for (const q of Object.keys(QUESTIONS).map(Number)) {
-    if (!answerList.some((a) => Number(a.q) === q)) throw usage(`question ${q} is unanswered: ${QUESTIONS[q]}`);
+  const questions = cover ? COVER_QUESTIONS : QUESTIONS;
+  for (const q of Object.keys(questions).map(Number)) {
+    if (!answerList.some((a) => Number(a.q) === q)) throw usage(`question ${q} is unanswered: ${questions[q]}`);
   }
   const reasons = [];
   for (const a of answerList) {
     const q = Number(a.q);
-    if (!QUESTIONS[q]) throw usage(`unknown question ${a.q}`);
+    if (!questions[q]) throw usage(`unknown question ${a.q}`);
     if (!a.frame) throw usage(`question ${q} names no frame`);
     if (!concrete(a.observed)) throw usage(`question ${q}: "observed" must be at least one sentence naming a concrete visible detail in ${a.frame}, not a bare yes or no`);
     const verdict = verdictOf(a.verdict);
+    if (cover) {
+      if (COVER_NEED_YES.has(q) && verdict === 'no') reasons.push(`Q${q}: no`);
+      if (COVER_NEED_NO.has(q) && verdict === 'yes') reasons.push(`Q${q}: yes`);
+      if (q === 8 && verdict !== 'none') reasons.push('Q8: a motion designer would change something');
+      continue;
+    }
     if (q === 1) {
       if (!['blind', 'self'].includes(a.by)) throw usage('question 1 needs "by": "blind" (a fresh delegate_task subagent) or "self"');
       if (a.by === 'blind' && !concrete(a.stranger)) throw usage('question 1 answered blind needs the subagent\'s sentence, verbatim, in "stranger"');
@@ -107,14 +134,38 @@ export function recordLook(out, round, answers) {
     if (q === 7 && verdict !== 'none') reasons.push('Q7: a designer would have shown something this film does not');
   }
   if (round === 1) {
-    if (!stillsOnlyMode(set.mode)) throw usage('round 1 is a stills round: render with --stills-only --round 1 before the first full render');
-    if (!concrete(answers.change)) throw usage('round 1 must name the weakest beat and the change you made in "change"');
+    if (!cover && !stillsOnlyMode(set.mode)) throw usage('round 1 is a stills round: render with --stills-only --round 1 before the first full render');
+    if (!concrete(answers.change)) throw usage(cover ? 'round 1 must name the change you make before round 2 in "change"' : 'round 1 must name the weakest beat and the change you made in "change"');
   }
-  look.rounds.push({ ...base, frames, answers: answerList, change: answers.change || null, aids: answers.aids || [], another: reasons.length > 0, reasons });
+  const defects = cover ? checkDefects(answers.defects, set, files) : undefined;
+  look.rounds.push({ ...base, frames, answers: answerList, change: answers.change || null, aids: answers.aids || [], ...(cover ? { defects } : {}), another: reasons.length > 0, reasons });
   writeJson(join(out, 'look.json'), look);
   return look.rounds.at(-1);
 }
 
+// Cover defects: at most three per round, worst first, each { t, region, frame, observed, cause,
+// fix }: the loop time in seconds where it shows, the [x, y, w, h] it covers in cover pixels, and a
+// file of the current stills set that shows it. `cover --window` checks the fix before the next
+// full render.
+function checkDefects(list, set, files) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) throw usage('defects must be an array');
+  if (list.length > COVER.maxDefects) throw usage(`at most ${COVER.maxDefects} defects per round; fix the worst first`);
+  const [W, H] = set.size || [0, 0];
+  const loop = set.durationSec;
+  return list.map((d, i) => {
+    const at = `defect ${i + 1}`;
+    if (!d || typeof d !== 'object') throw usage(`${at} must be an object`);
+    if (typeof d.t !== 'number' || !(d.t >= 0) || (loop && d.t >= loop)) throw usage(`${at}: t must be the loop time in seconds where it shows (0 to ${loop})`);
+    const r = d.region;
+    if (!Array.isArray(r) || r.length !== 4 || !r.every(Number.isInteger) || r[0] < 0 || r[1] < 0 || r[2] <= 0 || r[3] <= 0 || r[0] + r[2] > W || r[1] + r[3] > H) throw usage(`${at}: region must be [x, y, w, h] inside the ${W}x${H} cover`);
+    if (!files.has(d.frame)) throw usage(`${at}: frame ${JSON.stringify(d.frame)} is not in the latest stills set`);
+    if (!concrete(d.observed)) throw usage(`${at}: observed must be at least one sentence naming what is visible there`);
+    if (![d.cause, d.fix].every((x) => typeof x === 'string' && x.trim().length >= 8 && !/<[^<>\n]{1,80}>/u.test(x))) throw usage(`${at}: cause and fix must each say something concrete`);
+    return { t: d.t, region: r, frame: d.frame, observed: d.observed.trim(), cause: d.cause.trim(), fix: d.fix.trim() };
+  });
+}
+
 export async function lookCommand(flags) {
   const out = resolve(flags.out || 'motion-output');
   try {
@@ -130,7 +181,7 @@ export async function lookCommand(flags) {
     }
     console.log(`look round ${round.round} recorded: ${round.frames.length} frames viewed (manifest ${round.manifestSha256.slice(0, 12)})`);
     if (round.another) console.log(`another round is due (${round.reasons.join('; ')})${round.round >= 3 ? '; this was round 3 of 3: deliver with these open items stated plainly' : `; revise and render --round ${round.round + 1}`}`);
-    else if (round.round === 1) console.log('round 1 done: make the change you named, then render the film with --round 2');
+    else if (round.round === 1) console.log(round.stillsMode === 'cover' ? 'round 1 done: make the change you named (check a defect fix with `cover --window t0,t1`), then render the cover with --round 2' : 'round 1 done: make the change you named, then render the film with --round 2');
     return 0;
   } catch (error) {
     console.error(error.exitCode ? error.message : `motion internal error: ${error.stack || error.message}`);
@@ -171,6 +222,7 @@ export function checkDone(out) {
   if (!existsSync(statePath)) return no('no run-state.json: no render finished in this directory');
   const state = readJson(statePath);
   if (!state.finished || state.exitCode === null || state.exitCode === undefined) return no('the render command started but did not finish');
+  if (state.path === 'cover' || state.mode === 'cover') return checkCoverDone(out, state, no);
   if (stillsOnlyMode(state.mode)) return no('the last render was a stills round; render the film');
   if (state.exitCode !== 0) return no(`the last render exited ${state.exitCode}${state.failed?.length ? ` (${state.failed.join(', ')})` : ''}; done needs a passing gate`);
   if (state.path !== 'stage') {
@@ -213,11 +265,55 @@ export function checkDone(out) {
   return { done: true, status: 'COMPLETE', reason: `gate passed; ${rounds.length} look rounds; the last viewed all ${set.files.length} stills of the final render${receipts ? ' (vision_analyze receipts matched)' : ''}`, openItems, ...extra };
 }
 
+// Cover done (references/cover.md): a valid cover treatment unchanged since the last render, that
+// render's decoded cover at every TARGET gate (exit 0), at least two look rounds (round 1 naming its
+// change) and a last round on the final render that viewed the sheet, the poster and the seam pair,
+// with vision_analyze receipts when the Hermes tool hook recorded them.
+function checkCoverDone(out, state, no) {
+  const labels = generatedLabels(out);
+  const extra = { downgraded: [], labels };
+  const file = join(out, 'treatment.json');
+  if (!existsSync(file)) return no('treatment.json is missing', extra);
+  let treatment;
+  try { treatment = readJson(file); } catch { return no('treatment.json is not valid JSON', extra); }
+  if (!isCoverTreatment(treatment)) return no('the last render was a cover but treatment.json is now a film; render again', extra);
+  const valid = validateCoverTreatment(treatment);
+  if (!valid.ok) return no(`treatment.json no longer validates (field ${valid.field})`, extra);
+  if (!existsSync(join(out, 'manifest.json')) || !existsSync(join(out, 'gate-report.txt'))) return no('no cover render has finished (manifest.json or gate-report.txt is missing)', extra);
+  const manifest = readJson(join(out, 'manifest.json'));
+  if (manifest.treatment?.sha256 !== sha(readFileSync(file))) return no('treatment.json changed after the last cover render; render again', extra);
+  if (state.exitCode !== 0 || !/^COVER gate --strict: PASS\+TARGET$/mu.test(readFileSync(join(out, 'gate-report.txt'), 'utf8'))) {
+    return no(`the decoded cover did not reach every TARGET gate on the last render (exit ${state.exitCode}${state.failed?.length ? `; ${state.failed.join(', ')}` : ''})`, extra);
+  }
+  const set = readStillsSet(out);
+  if (set.mode !== 'cover') return no('the stills set is not a cover set; render the cover again', extra);
+  const rounds = readLook(out).rounds;
+  if (!rounds.length) return no('no look round is recorded; view stills/sheet.png, stills/poster.png and stills/seam.png and record them with `look`', extra);
+  const last = rounds.at(-1);
+  const manifestSha256 = sha(readFileSync(join(out, 'manifest.json')));
+  if (last.manifestSha256 !== manifestSha256) return no('the last look round was recorded before the final cover render; look again and record it', extra);
+  if (last.blocked === 'no-vision-tool') return { done: true, status: 'DONE_UNVIEWED', reason: 'the cover reached TARGET but no image tool could view it; say plainly that nobody viewed the frames', ...extra };
+  if (rounds.length < 2) return no('done needs two look rounds: round 1 with the change it named, then a round on the final render', extra);
+  if (!rounds[0].change) return no('round 1 must name the change made after it', extra);
+  const seen = new Map(last.frames.map((f) => [f.file, f.sha256]));
+  const required = set.files.filter((f) => set.required.includes(f.file));
+  const missing = required.filter((f) => seen.get(f.file) !== f.sha256).map((f) => f.file);
+  if (missing.length) return no(`the last round did not view ${missing.join(', ')}`, extra);
+  const receipts = hostReceipts(out);
+  if (receipts) {
+    const unviewed = required.filter((f) => !receipts.viewed.has(`${f.file}|${f.sha256}`)).map((f) => f.file);
+    if (unviewed.length) return no(`the tool hook saw no vision_analyze call on ${unviewed.join(', ')}`, extra);
+  }
+  if (last.another && last.round < 3) return no(`the last look round asks for another round (${last.reasons.join('; ')})`, extra);
+  return { done: true, status: 'COMPLETE', reason: `cover reached TARGET; ${rounds.length} look rounds; the last viewed the sheet, the poster and the seam pair${receipts ? ' (vision_analyze receipts matched)' : ''}`, openItems: last.another ? last.reasons : [], ...extra };
+}
+
 export function completeCommand(out) {
   const result = checkDone(out);
   if (existsSync(out)) writeJson(join(out, 'done.json'), { ...result, at: new Date().toISOString() });
   console.log(`${result.status}: ${result.reason}`);
   for (const item of result.downgraded || []) console.log(`downgraded: ${item}`);
   for (const item of result.openItems || []) console.log(`open item: ${item}`);
+  for (const item of result.labels || []) console.log(`label: ${item}`);
   return result.done ? 0 : 1;
 }

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/loop-kit.js

@@ -0,0 +1,80 @@
+// LitLoop: the helper kit a cover page loads from /lit/loop-kit.js (references/cover.md). A cover
+// page is one picture drawn from a loop time t in [0, 1) by window.renderFrame(t); the renderer
+// seeks frames in any order and draws some twice in fresh pages. So every helper below is either
+// pure or periodic in t: frame N would equal frame 0, and no frame depends on the one before it.
+// Clocks and unseeded entropy throw in a cover page, so layout randomness comes from rng(seed).
+(function attachLitLoop(scope) {
+  'use strict';
+  const TAU = 2 * Math.PI;
+  const clamp = (x, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, x));
+  const fract = (x) => x - Math.floor(x);
+  const mix = (a, b, k) => a + (b - a) * k;
+
+  // mulberry32: a seeded stream for layout (positions, sizes, which copy carries the accent).
+  function rng(seed) {
+    let s = seed >>> 0;
+    return function next() {
+      s = (s + 0x6d2b79f5) >>> 0;
+      let z = Math.imul(s ^ (s >>> 15), s | 1);
+      z ^= z + Math.imul(z ^ (z >>> 7), z | 61);
+      return ((z ^ (z >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  // Value noise on a seeded 3-D lattice. loopNoise samples it on a circle of `radius` around
+  // `offset`, so the value at t = 1 is the value at t = 0; different offsets decorrelate copies.
+  function makeNoise(seed) {
+    const next = rng(seed);
+    const table = new Float32Array(256);
+    const perm = new Uint8Array(512);
+    for (let i = 0; i < 256; i++) { table[i] = 2 * next() - 1; perm[i] = i; }
+    for (let i = 255; i > 0; i--) { const j = Math.floor(next() * (i + 1)); const k = perm[i]; perm[i] = perm[j]; perm[j] = k; }
+    for (let i = 0; i < 256; i++) perm[256 + i] = perm[i];
+    const fade = (u) => u * u * (3 - 2 * u);
+    const lattice = (x, y, z) => table[perm[perm[perm[x & 255] + (y & 255)] + (z & 255)]];
+    return function noise(x, y, z) {
+      const x0 = Math.floor(x), y0 = Math.floor(y), z0 = Math.floor(z);
+      const u = fade(x - x0), v = fade(y - y0), w = fade(z - z0);
+      const edge = (yy, zz) => mix(lattice(x0, yy, zz), lattice(x0 + 1, yy, zz), u);
+      const face = (zz) => mix(edge(y0, zz), edge(y0 + 1, zz), v);
+      return mix(face(z0), face(z0 + 1), w);
+    };
+  }
+  const loopNoise = (noise, t, offset = 0, radius = 1.3) =>
+    noise(offset + radius * Math.cos(TAU * t), radius * Math.sin(TAU * t), 0.37 * offset);
+
+  // Shapes for events. Linear time is only for motion that never stops (drift, laps).
+  const ease = Object.freeze({
+    smooth: (p) => p * p * (3 - 2 * p),
+    outCubic: (p) => 1 - (1 - p) ** 3,
+    inCubic: (p) => p * p * p,
+    outExpo: (p) => (p >= 1 ? 1 : 1 - 2 ** (-10 * p)),
+    outBack: (p, s = 1.6) => { const q = p - 1; return 1 + (s + 1) * q * q * q + s * q * q; },
+    gain: (p, k) => (p < 0.5 ? 0.5 * (2 * p) ** k : 1 - 0.5 * (2 - 2 * p) ** k),
+  });
+
+  // cubicPulse is a symmetric bump of half-width w around c, zero outside. Use it for micro events:
+  // the long tail of expImpulse is a slow fade, and a lossy animation encoder drops slow fades.
+  function cubicPulse(c, w, x) {
+    const d = Math.abs(x - c);
+    if (d >= w) return 0;
+    const k = d / w;
+    return 1 - k * k * (3 - 2 * k);
+  }
+  const expImpulse = (x, k) => { const h = k * x; return h * Math.exp(1 - h); };
+
+  // phase: where one copy of the rule is in its own cycle. cdist: distance around the loop, for an
+  // event that straddles t = 0. window: a one-shot event, -1 outside [start, start + dur) (wraps).
+  const phase = (t, offset = 0, cycles = 1) => fract(cycles * t - offset);
+  const cdist = (p, c) => { const d = fract(p - c); return Math.min(d, 1 - d); };
+  const once = (p, start, dur) => { const q = fract(p - start); return q < dur ? q / dur : -1; };
+  // steps: hold at `stops` poses per cycle, travelling during the last `travel` of each slot.
+  function steps(p, stops, travel = 0.35, shape = ease.smooth) {
+    const x = p * stops, i = Math.floor(x);
+    return (i + shape(clamp((x - i - (1 - travel)) / travel))) / stops;
+  }
+  // swell: 0 -> 1 -> 0 over one cycle, dwelling at both ends.
+  const swell = (p) => 0.5 - 0.5 * Math.cos(TAU * p);
+
+  scope.LitLoop = Object.freeze({ TAU, clamp, fract, mix, rng, makeNoise, loopNoise, ease, cubicPulse, expImpulse, phase, cdist, window: once, steps, swell });
+})(typeof window === 'undefined' ? globalThis : window);

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

@@ -282,7 +282,7 @@ export function muxArgs({ video, track, output, durationSec }) {
 
 export function muxAudio({ video, track, output, durationSec }) {
   const result = spawnSync('ffmpeg', muxArgs({ video, track, output, durationSec }), { encoding: 'utf8' });
-  if (result.status !== 0) throw fail(`the sound track could not be muxed: ${(result.stderr || result.error?.message || '').trim().split('\n').at(-1)}`);
+  if (result.status !== 0) throw fail(`the sound track could not be muxed: ${(result.stderr || result.error?.message || '').trim().split(/\r?\n/).at(-1)}`);
 }
 
 function streams(file) {

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

@@ -167,7 +167,7 @@ export function scanStage(stageDir) {
   const bySize = new Map();
   for (const r of rasters) if (r.size) { const key = r.size.join('x'); bySize.set(key, (bySize.get(key) || 0) + 1); }
   for (const [key, count] of bySize) if (count >= RASTER_LIMITS.sameSize) contract.push(`${count} rasters of the same size ${key} read as a flipbook; draw motion, do not play frames`);
-  return { contract: [...new Set(contract)], network: [...new Set(network)], files: files.length, rasters: { count: rasters.length, bytes: total } };
+  return { contract: [...new Set(contract)], network: [...new Set(network)], files: files.length, rasters: { count: rasters.length, bytes: total, paths: rasters.map((r) => r.rel) } };
 }
 
 // ---------------------------------------------------------------------------
@@ -181,6 +181,8 @@ const FACE_ROUTES = [
   ['Silkscreen', 400, '100%', 'silkscreen-400'], ['Silkscreen', 700, '100%', 'silkscreen-700'],
 ];
 
+const MONO_FILE = 'JetBrainsMono-wght-latin.woff2';
+
 export function fontRoutes(cache) {
   const routes = new Map();
   const faces = [];
@@ -192,6 +194,10 @@ export function fontRoutes(cache) {
     const format = name.endsWith('.otf') ? 'opentype' : 'truetype';
     faces.push(`@font-face { font-family: "${family}"; src: url("/lit/fonts/${name}") format("${format}"); font-weight: ${weight}; font-stretch: ${stretch}; font-style: normal; font-display: block; }`);
   }
+  // JetBrains Mono, pinned in the same cache: a variable face with a real wght axis (100-800)
+  // and a fixed advance, so weight motion on a cover never reflows a line.
+  routes.set(`/lit/fonts/${MONO_FILE}`, fontFile(cache, `fonts/${MONO_FILE}`));
+  faces.push(`@font-face { font-family: "JetBrains Mono"; src: url("/lit/fonts/${MONO_FILE}") format("woff2"); font-weight: 100 800; font-style: normal; font-display: block; }`);
   return { routes, css: `${faces.join('\n')}\n` };
 }
 
@@ -515,7 +521,7 @@ class StageSession {
       this.masterSec = Number(process.hrtime.bigint() - started) / 1e9;
       if (encoder) {
         const done = await encoder.finish();
-        if (done.code !== 0) throw fail(1, `ffmpeg master encode failed: ${done.stderr.split('\n').filter(Boolean).at(-1) || done.code}`);
+        if (done.code !== 0) throw fail(1, `ffmpeg master encode failed: ${done.stderr.split(/\r?\n/).filter(Boolean).at(-1) || done.code}`);
       }
       this.pngs = pngs;
     } finally {

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

@@ -103,6 +103,7 @@ const need = (cond, field, message) => { if (!cond) throw new Invalid(field, mes
 
 function check(t, { outDir, examples }) {
   need(t && typeof t === 'object' && !Array.isArray(t), 'treatment', 'treatment.json must be a JSON object');
+  need(t.mode !== 'cover', 'mode', 'this is a cover treatment; render it with `cover --out DIR` (references/cover.md)');
   for (const field of ['request', 'genre', 'path', 'pathReason', 'idea', 'audience', 'channel', 'format', 'durationSec', 'beats', 'subject', 'visualDevices', 'typePlan', 'palette', 'sound', 'copy', 'ambition']) {
     need(t[field] !== undefined && t[field] !== null && t[field] !== '', field, `${field} is required`);
   }

package/assets/lithermes-plugin/skills/lit-typographic-motion/recipes/negatives/card-scenes/expected.json

@@ -0,0 +1,49 @@
+{
+  "schema": "lithermes.cover-negative/v1",
+  "note": "Never a recipe. qa/cover-recipes.js and the test suite capture it, encode it and gate the decoded file; it counts as caught only when every gate in mustFail fails and no undeclared FLOOR gate among G1-G4 fails. Never change a threshold so it passes.",
+  "mustFail": [
+    "G2.floor"
+  ],
+  "observed": {
+    "medianD": 0,
+    "movingFrac": 0.3203125,
+    "longestStillSec": 1.449,
+    "spike": 22.180186084476993,
+    "seamLocal": 0.30624810170866057,
+    "bytes": 180632,
+    "failed": [
+      "G2"
+    ]
+  },
+  "treatment": {
+    "mode": "cover",
+    "request": "A negative check page for the cover gate.",
+    "idea": "Four card scenes that fade in, hold and fade out: the old stage path as a cover.",
+    "recipe": "own",
+    "recipeReason": "A shipped negative that must keep failing its named gates.",
+    "brandWord": "LITHERMES",
+    "aspect": "2:1",
+    "loopSec": 8,
+    "fps": 16,
+    "layers": {
+      "slow": "None.",
+      "mid": "None.",
+      "beat": "None."
+    },
+    "system": {
+      "rule": "None.",
+      "copies": "None.",
+      "offset": "None."
+    },
+    "title": {
+      "box": [
+        0.1,
+        0.25,
+        0.8,
+        0.25
+      ],
+      "kind": "live"
+    },
+    "ambition": "It fails the gates it is named for, every time."
+  }
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/recipes/negatives/card-scenes/index.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/loop-kit.js"></script>
+<style>
+  html, body { margin: 0; width: 1200px; height: 600px; overflow: hidden; background: #080d14; color: #f2efdf; font-family: "JetBrains Mono"; }
+  .mid { position: absolute; left: 0; right: 0; text-align: center; white-space: nowrap; }
+  body.mask, body.mask * { background: #000 !important; color: #000 !important; border-color: #000 !important; }
+  body.mask .title { color: #fff !important; }
+</style>
+<style>.card { position: absolute; inset: 0; opacity: 0; } .box { position: absolute; border: 3px solid #ff6337; border-radius: 10px; }</style>
+</head>
+<body>
+<!-- NEGATIVE (never a recipe): the old stage path as a cover. Four card scenes fade in, hold and
+     fade out, the last one an end card. It must keep failing G2: the holds leave most grid steps
+     still, whatever the fades do. -->
+<div class="card" id="c0"><div class="mid title" style="top:200px;font-size:96px;font-weight:800">LITHERMES</div><div class="mid" style="top:340px;font-size:30px">A workflow family for Hermes Agent</div></div>
+<div class="card" id="c1"><div class="box" style="left:160px;top:180px;width:260px;height:240px"></div><div style="position:absolute;left:480px;top:240px;font-size:44px;font-weight:700">1. Plan</div><div style="position:absolute;left:480px;top:310px;font-size:26px">Decision-complete steps.</div></div>
+<div class="card" id="c2"><div class="box" style="left:160px;top:180px;width:260px;height:240px;border-color:#d7f75b"></div><div style="position:absolute;left:480px;top:240px;font-size:44px;font-weight:700">2. Loop</div><div style="position:absolute;left:480px;top:310px;font-size:26px">Test first, then green.</div></div>
+<div class="card" id="c3"><div class="mid" style="top:250px;font-size:64px;font-weight:700">KEEP THE WORK <span style="color:#ff6337">LIT.</span></div></div>
+<script>
+const { clamp, ease } = LitLoop, LENGTH = 10, SCENES = [[0, 2.6], [2.6, 5.0], [5.0, 7.4], [7.4, 10]];
+window.renderFrame = (t, options = {}) => {
+  document.body.className = options.mask ? 'mask' : '';
+  const s = t * LENGTH;
+  SCENES.forEach(([a, b], i) => {
+    const el = document.getElementById(`c${i}`);
+    el.style.opacity = String(ease.smooth(clamp((s - a) / 0.4)) * (1 - ease.smooth(clamp((s - (b - 0.4)) / 0.4))));
+    el.style.transform = `translateX(${20 * (1 - ease.outCubic(clamp((s - a) / 0.5)))}px)`;
+  });
+};
+document.fonts.load('800 96px "JetBrains Mono"').then(() => document.fonts.ready).then(() => { window.renderFrame(0); window.ready = true; });
+</script>
+</body>
+</html>

package/assets/lithermes-plugin/skills/lit-typographic-motion/recipes/negatives/reset-sweep/expected.json

@@ -0,0 +1,49 @@
+{
+  "schema": "lithermes.cover-negative/v1",
+  "note": "Never a recipe. qa/cover-recipes.js and the test suite capture it, encode it and gate the decoded file; it counts as caught only when every gate in mustFail fails and no undeclared FLOOR gate among G1-G4 fails. Never change a threshold so it passes.",
+  "mustFail": [
+    "G4.floor"
+  ],
+  "observed": {
+    "medianD": 0.0007350640633021579,
+    "movingFrac": 1,
+    "longestStillSec": 0,
+    "spike": 124.92159799457926,
+    "seamLocal": 121.841924929272,
+    "bytes": 30944,
+    "failed": [
+      "G4"
+    ]
+  },
+  "treatment": {
+    "mode": "cover",
+    "request": "A negative check page for the cover gate.",
+    "idea": "A progress sweep that resets at the loop point: the seam is a cut.",
+    "recipe": "own",
+    "recipeReason": "A shipped negative that must keep failing its named gates.",
+    "brandWord": "LITHERMES",
+    "aspect": "2:1",
+    "loopSec": 8,
+    "fps": 16,
+    "layers": {
+      "slow": "None.",
+      "mid": "None.",
+      "beat": "None."
+    },
+    "system": {
+      "rule": "None.",
+      "copies": "None.",
+      "offset": "None."
+    },
+    "title": {
+      "box": [
+        0.1,
+        0.25,
+        0.8,
+        0.25
+      ],
+      "kind": "live"
+    },
+    "ambition": "It fails the gates it is named for, every time."
+  }
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/recipes/negatives/reset-sweep/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/loop-kit.js"></script>
+<style>
+  html, body { margin: 0; width: 1200px; height: 600px; overflow: hidden; background: #080d14; color: #f2efdf; font-family: "JetBrains Mono"; }
+  .mid { position: absolute; left: 0; right: 0; text-align: center; white-space: nowrap; }
+  body.mask, body.mask * { background: #000 !important; color: #000 !important; border-color: #000 !important; }
+  body.mask .title { color: #fff !important; }
+</style>
+</head>
+<body>
+<!-- NEGATIVE (never a recipe): a wall-clock habit, a progress sweep that fills once and resets at
+     the loop point, so the seam is a cut. It must keep failing G4. -->
+<div id="sweep" style="position:absolute;left:0;top:0;height:600px;background:#1d2633"></div>
+<div class="mid title" style="top:230px;font-size:110px;font-weight:800;letter-spacing:6px">LITHERMES</div>
+<script>
+window.renderFrame = (t, options = {}) => {
+  document.body.className = options.mask ? 'mask' : '';
+  document.getElementById('sweep').style.width = `${1200 * t}px`;
+};
+document.fonts.load('800 110px "JetBrains Mono"').then(() => document.fonts.ready).then(() => { window.renderFrame(0); window.ready = true; });
+</script>
+</body>
+</html>