@litfamily/lithermes 1.0.32 → 1.0.34

package/assets/lithermes-plugin/skills/lit-code/references/typescript/README.md

@@ -31,7 +31,7 @@ These are deliberate project choices. Violations are always wrong, not "style pr
 3. **Exhaustive switch** — every `switch` on a discriminated union ends with `default: assertNever(x)`. No fall-through.
 4. **No any** — `any` is banned in annotations, returns, and parameters. Use `unknown` and narrow.
 5. **No type assertions** — `as any`, `as unknown` banned. `as const` and `satisfies` are fine.
-6. **No non-null assertion** — `x!` is banned. Use narrowing or optional chaining (`x?.y`).
+6. **No non-null assertion** — `x!.y` is banned. Use narrowing or optional chaining (`x?.y`).
 7. **No @ts-ignore / @ts-expect-error** — fix the type.
 8. **No enum** — use `as const` objects + literal union types.
 9. **Zod at boundaries** — external input (API, user, file) → Zod schema. Internal → plain types.
@@ -163,7 +163,7 @@ Violations caught by `../../scripts/typescript/check-no-excuse-rules.ts`. Run af
 | `no-ts-ignore` | `@ts-ignore` | None — fix the type |
 | `no-ts-expect-error` | `@ts-expect-error` | None — fix the type |
 | `no-enum` | `enum` declarations | None — use `as const` |
-| `no-non-null-assertion` | `x!` postfix | None — narrow or `?.` |
+| `no-non-null-assertion` | `x!.y` postfix | None — narrow or `?.` |
 | `no-throw-literal` | `throw "string"` / `throw 123` | None — throw Error subclass |
 | `no-mutable-export` | `export let` / `export var` | None — use `export const` |
 | `no-any-annotation` | `: any` in parameter/return/variable types | `// no-excuse-ok: any` |

package/assets/lithermes-plugin/skills/lit-code/references/typescript/backend-hono.md

@@ -100,7 +100,7 @@ app.get(
   validator('query', QuerySchema),
   (c) => {
     const query = c.req.valid('query')
-    return c.json({ message: `Hello ${query.name ?? 'Hono'}!` })
+    return c.json({ message: `Hello ${query.name ?? 'Hono'}.` })
   },
 )
 

package/assets/lithermes-plugin/skills/lit-code/references/typescript/tsconfig-strict.md

@@ -128,7 +128,7 @@ For Bun projects, add to `compilerOptions`:
 | Rule | What |
 |---|---|
 | `noExplicitAny` | `any` in annotations is an error |
-| `noNonNullAssertion` | `x!` is an error |
+| `noNonNullAssertion` | `x!.y` is an error |
 | `noDefaultExport` | Forces named exports |
 | `useImportType` | Forces `import type` for type-only imports |
 | `noParameterAssign` | No mutation of function parameters |

package/assets/lithermes-plugin/skills/lit-code/scripts/typescript/check-no-excuse-rules.ts

@@ -8,7 +8,7 @@
  *   no-ts-ignore            - `@ts-ignore` comments
  *   no-ts-expect-error      - `@ts-expect-error` comments
  *   no-enum                 - `enum` declarations
- *   no-non-null-assertion   - `x!` postfix operator
+ *   no-non-null-assertion   - `x!.y` postfix operator
  *   no-throw-literal        - `throw "string"` / `throw 123`
  *   no-mutable-export       - `export let` / `export var`
  *   no-any-annotation       - `: any` in annotations (opt out: `// no-excuse-ok: any`)
@@ -140,7 +140,7 @@ function analyzeFile(filePath: string): Violation[] {
     // ── x! non-null assertion ──
     if (ts.isNonNullExpression(node)) {
       const p = pos(node)
-      violations.push({ ruleId: "no-non-null-assertion", filePath, ...p, message: "`x!` — use narrowing or optional chaining" })
+      violations.push({ ruleId: "no-non-null-assertion", filePath, ...p, message: "`x!.y` — use narrowing or optional chaining" })
     }
 
     // ── throw "literal" ──

package/assets/lithermes-plugin/skills/lit-typographic-motion/SKILL.md

@@ -64,7 +64,7 @@ Done only when `$M complete --out DIR` exits 0: valid treatment, passing gate (a
 
 ## #contract.hard_stops
 
-Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 the treatment field, 17 a stage break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault, 21 no cover encoder, 22 a missing cover asset. Never install during a render, deliver a flash-failing film, or downgrade to pass.
+Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 the treatment field, 17 a stage or clip break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault, 21 no cover encoder, 22 a missing cover asset. Never install during a render, deliver a flash-failing film, or downgrade to pass.
 
 ## #contract.anti_patterns
 

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

@@ -102,7 +102,7 @@ function prepare(out, env) {
   recordFirstTreatment(out, plan.treatment);
   const coverDir = join(out, COVER_DIR);
   if (!existsSync(join(coverDir, 'index.html'))) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: no ${COVER_DIR}/index.html in ${out}; write the cover page first (references/cover.md)`);
-  const scan = scanStage(coverDir);
+  const scan = scanStage(coverDir, { clips: false });
   if (scan.contract.length) throw fail(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${scan.contract.join('; ')}`);
   if (scan.network.length) throw fail(EXIT.STAGE_NETWORK_REQUEST, `STAGE_NETWORK_REQUEST: ${scan.network.join('; ')}; a cover is served offline`);
   const assets = checkAssets({ out, recipe: plan.treatment.recipe, rasters: scan.rasters.paths, coverDir: COVER_DIR });

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

@@ -85,6 +85,7 @@ export function renderStageReport(manifest, gate, { out, previewName }) {
   lines.push(`path: stage; format ${manifest.format} (${manifest.resolution.join('x')}); ${manifest.durationSec.toFixed(2)} s at ${manifest.fps} fps (${manifest.totalFrames} frames); treatment ${manifest.targetDurationSec} s`);
   lines.push(`renderer: ${manifest.renderer}; flags: ${manifest.chromeFlags.join(' ')}`);
   lines.push(`frame time: p50 ${manifest.frameTimeMs.p50} ms, p95 ${manifest.frameTimeMs.p95} ms over ${manifest.frameTimeMs.captured} captures; master ${manifest.masterSec?.toFixed(1)} s`);
+  if (manifest.scan?.clips?.length) lines.push(`clips: ${manifest.scan.clips.map((c) => `${c.id} ${c.count} frames at ${c.fps} fps`).join(', ')} (keyed overlays, chosen from film time)`);
   if (manifest.sound) lines.push(`sound: ${manifest.sound.label}`);
   lines.push(`QA gate: ${gate.failed.length ? 'FAIL' : 'PASS'}`);
   for (const rule of gate.rules) lines.push(`${rule.id}: ${rule.status} — ${rule.detail}`);

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

@@ -1,7 +1,7 @@
 // LitHermes stage kit, served to stage pages at /lit/stage-kit.js.
 // Motion primitives only: easing, springs, keyframes, timing, seeded
-// randomness, text splitting, path drawing and morphing, masks, colour mixing
-// and text registration. It ships no scene, object, layout or copy; the page
+// randomness, text splitting, path drawing and morphing, masks, colour mixing,
+// text registration and declared keyed clips. It ships no scene, object, layout or copy; the page
 // draws whatever its treatment calls for. Every function is a pure function of
 // its arguments (and of t), so a frame depends only on the virtual clock.
 (() => {
@@ -374,6 +374,45 @@
     return target;
   }
 
+  // A declared keyed clip (stage/clips/clips.json, served as window.LitClips by /lit/clips.js). One absolutely
+  // placed wrapper at `box` holds the clip's frame for t; the frame index is floor((t - start) * fps) + 1 counted
+  // from `from`, a pure function of film time, so no <video> and no real clock is involved. Outside from..to the
+  // wrapper is hidden (null returned) unless `hold` keeps the last frame or `loop` wraps by frame index. The page
+  // scales or fades the returned wrapper; the <img> inside is replaced on a frame change and the renderer waits
+  // for its decode before it captures.
+  function clip({ parent, id, box } = {}) {
+    const all = window.LitClips;
+    if (!all) throw new Error('LitStage.clip: load <script src="/lit/clips.js"></script> after the kit; the stage declares no clips (clips/clips.json)');
+    const c = all[id];
+    if (!c) throw new Error(`LitStage.clip: no clip "${id}" in clips/clips.json (declared: ${Object.keys(all).join(', ')})`);
+    if (!parent || !box || !(box.w > 0) || !(box.h > 0)) throw new Error('LitStage.clip: needs { parent, id, box: { x, y, w, h } }');
+    const wrap = document.createElement('div');
+    wrap.setAttribute('data-lit-clip', id);
+    Object.assign(wrap.style, { position: 'absolute', left: `${box.x}px`, top: `${box.y}px`, width: `${box.w}px`, height: `${box.h}px`, display: 'none', pointerEvents: 'none' });
+    parent.append(wrap);
+    let shown = 0;
+    let img = null;
+    return (t, { start = 0, from = 1, to = c.count, loop = false, hold = false } = {}) => {
+      if (!(from >= 1 && to <= c.count && from <= to)) throw new Error(`LitStage.clip: from..to must lie within 1..${c.count} (got ${from}..${to})`);
+      const n = to - from + 1;
+      const k = Math.floor((t - start) * c.fps + 1e-6);
+      const i = k < 0 ? 0 : k < n ? from + k : loop ? from + (k % n) : hold ? to : 0;
+      wrap.style.display = i ? 'block' : 'none';
+      if (!i) return null;
+      if (i !== shown) {
+        const next = document.createElement('img');
+        next.src = `${c.src}/frame_${String(i).padStart(4, '0')}.png`;
+        next.alt = '';
+        Object.assign(next.style, { display: 'block', width: '100%', height: '100%', objectFit: 'contain' });
+        if (img) img.replaceWith(next);
+        else wrap.append(next);
+        img = next;
+        shown = i;
+      }
+      return wrap;
+    };
+  }
+
   function define(film) {
     if (!film || typeof film !== 'object') throw new Error('LitStage.define needs { width, height, fps, duration, render }');
     for (const key of ['width', 'height', 'duration']) if (!Number.isFinite(film[key])) throw new Error(`LitStage.define: ${key} must be a number`);
@@ -384,6 +423,6 @@
 
   window.LitStage = Object.freeze({
     ease, bezier, spring, kf, at, stagger, seq, rand, splitText, drawPath, morph,
-    clipInset, clipCircle, maskWipe, mix, text, define,
+    clipInset, clipCircle, maskWipe, mix, text, define, clip,
   });
 })();

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

@@ -22,6 +22,7 @@ import { runTextQa } from './stage-qa.mjs';
 import { readStyle, styleCss, styleScript } from './styles.mjs';
 import { addToStills, writeBoard } from './board.mjs';
 import { FONT_FILES } from './frame.mjs';
+import { decodePng } from './cover-png.mjs';
 
 import { findCache, fontFile, fontState, hangulPath, runtimeRequire, WARM } from '../bin/runtime.mjs';
 
@@ -54,6 +55,12 @@ export const CONTENT_TYPES = Object.freeze({
 const RASTER = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
 const TEXTUAL = new Set(['.html', '.js', '.mjs', '.css', '.svg', '.json']);
 export const RASTER_LIMITS = Object.freeze({ count: 24, bytes: 8 * 1024 * 1024, sameSize: 10 });
+// Declared keyed clips (references/stage.md, Clips) answer to these caps instead of RASTER_LIMITS. A clip
+// is a sticker on the film, never the film: 8-bit RGBA PNG frames, at most `side` px on the long side.
+export const CLIP_LIMITS = Object.freeze({
+  clips: 12, framesPerClip: 360, framesTotal: 1500, bytesPerClip: 40 * 1024 * 1024, bytesTotal: 128 * 1024 * 1024, side: 720, fps: 30,
+});
+export const CLIPS_DIR = 'clips';
 
 // The software rung only (SwiftShader, CPU raster): a mismatch between two
 // captures can then only come from the page. Plus the stage set and the two
@@ -171,14 +178,130 @@ function walk(dir, root, out = []) {
   return out;
 }
 
-export function scanStage(stageDir) {
+// ---------------------------------------------------------------------------
+// Declared clips: stage/clips/clips.json and the frame folders it names.
+
+const CLIP_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/u;
+const CLIP_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u;
+const clipFrame = (i) => `frame_${String(i).padStart(4, '0')}.png`;
+const mb = (bytes) => (bytes / 1048576).toFixed(1);
+
+// The clips clips.json declares ([] without the file), checked for shape. Throws a plain Error naming the break.
+function declaredClips(root, limits = CLIP_LIMITS) {
+  const file = join(root, CLIPS_DIR, 'clips.json');
+  if (!existsSync(file)) return [];
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { throw new Error(`${CLIPS_DIR}/clips.json is not valid JSON (${error.message})`); }
+  if (!doc || !Array.isArray(doc.clips)) throw new Error(`${CLIPS_DIR}/clips.json needs { "clips": [ { "id", "dir", "count", "fps" } ] }`);
+  if (doc.clips.length > limits.clips) throw new Error(`${doc.clips.length} clips declared (at most ${limits.clips} clips)`);
+  const ids = new Set(), dirs = new Set();
+  return doc.clips.map((c, n) => {
+    const at = `${CLIPS_DIR}/clips.json clip #${n + 1}`;
+    if (!c || typeof c !== 'object') throw new Error(`${at} is not an object`);
+    if (typeof c.id !== 'string' || !CLIP_ID.test(c.id)) throw new Error(`${at}: id must be a plain token of letters, digits, - and _ (got ${JSON.stringify(c.id)})`);
+    if (ids.has(c.id)) throw new Error(`${at}: duplicate id ${c.id}`);
+    ids.add(c.id);
+    if (typeof c.dir !== 'string' || !CLIP_DIR.test(c.dir) || c.dir.includes('..')) throw new Error(`clip "${c.id}": dir must be a folder name directly under ${CLIPS_DIR}/ (got ${JSON.stringify(c.dir)})`);
+    if (dirs.has(c.dir)) throw new Error(`clip "${c.id}": dir ${c.dir} is already declared by another clip`);
+    dirs.add(c.dir);
+    if (!Number.isInteger(c.count) || c.count < 1) throw new Error(`clip "${c.id}": count must be a whole number of frames (got ${JSON.stringify(c.count)})`);
+    if (!Number.isInteger(c.fps) || c.fps < 1 || c.fps > limits.fps) throw new Error(`clip "${c.id}": fps must be a whole number from 1 to ${limits.fps} (got ${JSON.stringify(c.fps)})`);
+    return { id: c.id, dir: c.dir, count: c.count, fps: c.fps };
+  });
+}
+
+// One declared clip against its bytes: exactly frame_0001.png..frame_<count>.png in clips/<dir>/, each an 8-bit
+// non-animated RGBA PNG of one size within the overlay cap, real transparency in the first, middle and last frame.
+function checkClip(d, byRel, limits) {
+  const fail = (message) => new Error(`clip "${d.id}": ${message}`);
+  if (d.count > limits.framesPerClip) throw fail(`${d.count} frames (at most ${limits.framesPerClip} per clip)`);
+  const names = [];
+  for (let i = 1; i <= d.count; i++) {
+    const rel = join(CLIPS_DIR, d.dir, clipFrame(i));
+    if (!byRel.has(rel)) throw fail(`${CLIPS_DIR}/${d.dir}/${clipFrame(i)} is missing (declared ${d.count} frames, named frame_0001.png onward)`);
+    names.push(rel);
+  }
+  const prefix = join(CLIPS_DIR, d.dir) + sep;
+  const stray = [...byRel.keys()].find((rel) => rel.startsWith(prefix) && !names.includes(rel));
+  if (stray) throw fail(`${stray.split(sep).join('/')} is not one of the ${d.count} declared frames; raise count or remove it`);
+  const bytes = names.reduce((sum, rel) => sum + statSync(byRel.get(rel)).size, 0);
+  if (bytes > limits.bytesPerClip) throw fail(`${mb(bytes)} MB (at most ${(limits.bytesPerClip / 1048576).toFixed(0)} MB per clip)`);
+  let size = null;
+  for (const rel of names) {
+    const data = readFileSync(byRel.get(rel));
+    const shown = rel.split(sep).join('/');
+    if (data.length < 33 || data.readUInt32BE(12) !== 0x49484452 || data.toString('latin1', 1, 4) !== 'PNG') throw fail(`${shown} is not a readable PNG`);
+    if (isAnimatedRaster(data, '.png')) throw fail(`${shown} is an animated image; a clip is a folder of still frames`);
+    if (data[25] !== 6 || data[24] !== 8) throw fail(`${shown} must be an 8-bit RGBA PNG with an alpha channel (a keyed frame), not an opaque image`);
+    const [width, height] = imageSize(data, '.png');
+    if (Math.max(width, height) > limits.side) throw fail(`${shown} is ${width}x${height}; a clip is an overlay of at most ${limits.side} px on the long side`);
+    if (size && (size[0] !== width || size[1] !== height)) throw fail(`${shown} is ${width}x${height} but frame_0001.png is ${size[0]}x${size[1]}; one size per clip`);
+    size = [width, height];
+  }
+  for (const rel of [names[0], names[Math.floor((names.length - 1) / 2)], names[names.length - 1]]) {
+    let rgba;
+    try { ({ rgba } = decodePng(readFileSync(byRel.get(rel)))); } catch (error) { throw fail(`${rel.split(sep).join('/')} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`); }
+    let transparent = false;
+    for (let i = 3; i < rgba.length && !transparent; i += 4) transparent = rgba[i] < 255;
+    if (!transparent) throw fail(`${rel.split(sep).join('/')} has no transparent pixel; a clip is keyed, not a full-frame video`);
+  }
+  return { ...d, width: size[0], height: size[1], bytes, frames: names };
+}
+
+/**
+ * Check every declared clip. Never throws: returns { clips, problems, claimed }, where `clips` are the clips that
+ * passed ({ id, dir, count, fps, width, height, bytes, frames }), `problems` are the contract findings, and
+ * `claimed` is the set of stage-relative raster paths inside declared clip folders, which are not page rasters.
+ */
+export function scanClips(stageDir, { limits = CLIP_LIMITS, files = null } = {}) {
+  const root = realpathSync(stageDir);
+  const problems = [];
+  let decls;
+  try { decls = declaredClips(root, limits); } catch (error) { return { clips: [], problems: [error.message], claimed: new Set() }; }
+  const byRel = new Map();
+  for (const f of files || walk(root, root)) if (!f.escape && RASTER.has(extname(f.path).toLowerCase())) byRel.set(relative(root, f.path), f.real);
+  const claimed = new Set();
+  const clips = [];
+  let frames = 0, bytes = 0;
+  for (const d of decls) {
+    const prefix = join(CLIPS_DIR, d.dir) + sep;
+    const mine = new Map([...byRel].filter(([rel]) => rel.startsWith(prefix)));
+    for (const rel of mine.keys()) claimed.add(rel);
+    try { clips.push(checkClip(d, mine, limits)); } catch (error) { problems.push(error.message); }
+  }
+  for (const c of clips) { frames += c.count; bytes += c.bytes; }
+  if (frames > limits.framesTotal) problems.push(`${frames} clip frames in all (at most ${limits.framesTotal})`);
+  if (bytes > limits.bytesTotal) problems.push(`${mb(bytes)} MB of clip frames in all (at most ${(limits.bytesTotal / 1048576).toFixed(0)} MB)`);
+  return { clips, problems, claimed };
+}
+
+/**
+ * window.LitClips for LitStage.clip: id -> { src, count, fps, width, height }, from clips.json and the first frame's
+ * header. null when the stage declares no clips, or declares ones the scan would refuse.
+ */
+export function clipsScript(stageDir) {
+  try {
+    const root = realpathSync(stageDir);
+    const table = Object.fromEntries(declaredClips(root).map((c) => {
+      const [width, height] = imageSize(readFileSync(join(root, CLIPS_DIR, c.dir, clipFrame(1))), '.png');
+      return [c.id, { src: `${CLIPS_DIR}/${c.dir}`, count: c.count, fps: c.fps, width, height }];
+    }));
+    return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
+  } catch { return null; }
+}
+
+// `clips: false` (cover mode) ignores clips.json, so a clip folder is held to the raster limits.
+export function scanStage(stageDir, { clips: allowClips = true } = {}) {
   const root = realpathSync(stageDir);
   const contract = [], network = [];
   const files = walk(root, root);
+  const clipScan = allowClips ? scanClips(root, { files }) : { clips: [], problems: [], claimed: new Set() };
+  contract.push(...clipScan.problems);
   const rasters = [];
   for (const file of files) {
     const rel = relative(root, file.path);
     if (file.escape) { contract.push(`${rel} is a symlink that leaves the stage dir`); continue; }
+    if (clipScan.claimed.has(rel)) continue;
     const ext = extname(file.path).toLowerCase();
     const bytes = readFileSync(file.real);
     if (RASTER.has(ext)) {
@@ -199,7 +322,8 @@ 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, paths: rasters.map((r) => r.rel) } };
+  const clips = clipScan.clips.map(({ id, count, fps, width, height, bytes }) => ({ id, count, fps, width, height, bytes }));
+  return { contract: [...new Set(contract)], network: [...new Set(network)], files: files.length, rasters: { count: rasters.length, bytes: total, paths: rasters.map((r) => r.rel) }, clips };
 }
 
 // ---------------------------------------------------------------------------
@@ -312,6 +436,7 @@ export async function openStage({ runtime, stageDir, profileRoot, width, height,
   const cdp = await context.newCDPSession(page);
   const root = realpathSync(stageDir);
   const kit = readFileSync(join(here, 'stage-kit.js'));
+  const clipsJs = clipsScript(root);
   const blocked = [], contract = [];
   const serve = async (event) => {
     const { requestId, request } = event;
@@ -329,6 +454,7 @@ export async function openStage({ runtime, stageDir, profileRoot, width, height,
     const path = decodeURIComponent(url.pathname);
     if (path === '/lit/stage-kit.js') return reply(200, CONTENT_TYPES['.js'], kit);
     if (path === '/lit/fonts.css') return reply(200, CONTENT_TYPES['.css'], fontCss);
+    if (path === '/lit/clips.js' && clipsJs) return reply(200, CONTENT_TYPES['.js'], clipsJs);
     if (path === '/lit/style.css' && style) return reply(200, CONTENT_TYPES['.css'], style.css);
     if (path === '/lit/style.js' && style) return reply(200, CONTENT_TYPES['.js'], style.js);
     if (path.startsWith('/lit/three/')) {
@@ -448,9 +574,12 @@ function beatFramesOf(treatment, fps, totalFrames) {
   });
 }
 
-function imageUrlsIn(stageDir) {
+// The rasters decoded before frame 0. Declared clip frames are left out: a page decodes each one when it shows it.
+export function imageUrlsIn(stageDir) {
   const root = realpathSync(stageDir);
-  return walk(root, root).filter((f) => !f.escape && RASTER.has(extname(f.path).toLowerCase()))
+  let prefixes = [];
+  try { prefixes = declaredClips(root).map((c) => join(CLIPS_DIR, c.dir) + sep); } catch { /* the scan already refused a bad declaration */ }
+  return walk(root, root).filter((f) => !f.escape && RASTER.has(extname(f.path).toLowerCase()) && !prefixes.some((p) => relative(root, f.path).startsWith(p)))
     .map((f) => `${ORIGIN}/${relative(root, f.path).split(sep).map(encodeURIComponent).join('/')}`);
 }
 

package/assets/lithermes-plugin/skills/lit-typographic-motion/references/stage.md

@@ -17,7 +17,8 @@ deliverable.
 Never install, download or copy a third-party library into the stage dir. Use
 the kit below and your own code. Rasters are textures and stills, never a frame
 sequence: at most 24 raster images and 8 MB in total; 10 or more rasters of the
-same size (a flipbook), or any animated GIF, APNG or WebP, is exit 17.
+same size (a flipbook), or any animated GIF, APNG or WebP, is exit 17. The one
+frame sequence a page may carry is a declared keyed clip (Clips).
 
 Put all on-screen copy in one `COPY` object at the top of `stage/index.html`,
 so the copy is easy to find and edit:
@@ -43,6 +44,8 @@ declares the film:
   1080×1920 for 9:16. `duration` is the treatment's `durationSec`; the render
   must land within ±10 % of it.
 - `fps` is 60. Use 30 only when the treatment says so.
+- A page that shows clips also loads `<script src="/lit/clips.js"></script>`
+  after the kit (Clips).
 - `render(t)` draws the frame at time `t` in seconds. It may be omitted when
   the page animates only with CSS or the Web Animations API.
 - Setting `window.litStage` to the same object is equivalent to calling
@@ -168,6 +171,57 @@ scenes, no objects, no layouts, no copy. `window.LitStage` holds:
 - **Text registration.** `LitStage.text(el, { decor: true })` and
   `LitStage.text({ content, x, y, w, h })`, above.
 
+- **Clips.** `LitStage.clip({ parent, id, box })` registers a declared keyed
+  clip once and returns `show(t, opts)`, which `render(t)` calls every frame
+  (Clips).
+
+  ```text
+  const boom = LitStage.clip({ parent: layer, id: "boom", box: { x: 1200, y: 300, w: 520, h: 511 } });
+  boom(t, { start: 2.1 });
+  ```
+
+## Clips
+
+Real keyed footage (a reaction clip, a spinning loop shot on a green screen) joins the
+film as a layer of the page. The footage is keyed outside the renderer into one 8-bit RGBA
+PNG per frame, the frames are declared, and the page picks the frame from film time. Nothing
+is encoded by hand: the renderer captures the page, so the flash audit, the determinism
+replay and the text checks see the final pixels like any other film.
+
+1. Put each clip's frames in the run's stage folder as `stage/clips/<dir>/frame_0001.png`,
+   `frame_0002.png` and on, with no gap and no other image in that folder.
+2. Declare the clips in `stage/clips/clips.json`:
+
+   ```json
+   { "clips": [ { "id": "boom", "dir": "01-boom", "count": 122, "fps": 30 } ] }
+   ```
+
+   `id` is the name the page uses, `dir` a folder directly under `clips/`, `count` the number
+   of frames and `fps` the clip's own rate, 1 to 30. Declare a clip once even if it plays twice.
+3. The page loads `<script src="/lit/clips.js"></script>` after the kit. For each place a clip
+   appears it calls `LitStage.clip({ parent, id, box })` once, outside `render`, and calls the
+   returned `show(t, opts)` from `render(t)`. `parent` holds the clip, `box` is its place in
+   pixels and the frame is fitted inside it. `show` returns the clip's wrapper element, or
+   `null` while the clip is hidden; scale, fade or move that wrapper from `t` like any layer.
+
+The frame is `floor((t - start) * fps) + 1`, counted from `from`, so a cue is plain
+arithmetic: `start = cue - (N - 1) / fps` puts frame N on the cue. A clip whose own sound
+sits on frame 85 and has to land on a cue at 0.12 s takes `start = 0.12 - 84 / 30`. Options
+are `start` (film seconds, default 0), `from` and `to` (the frame range, default the whole
+clip), `loop` (wrap by frame index) and `hold` (keep the last frame). Before `start`, and after
+`to` without `loop` or `hold`, the clip is hidden.
+
+The pre-flight scan refuses with exit 17, naming the clip: a stage holds at most 12 clips; a
+clip holds at most 360 frames and the stage 1500 in all; more than 40 MB in a clip or 128 MB in
+all; a frame whose long side is above 720 px (a clip is an overlay, not the film); a frame rate
+above 30; frames of mixed sizes; a missing or extra frame; a frame that is not an 8-bit RGBA
+PNG, or has no transparent pixel in the first, middle and last frame (an opaque video is not
+keyed); an animated image; a duplicate `id`; and a `dir` that leaves `clips/`. A folder that is
+not declared, and any frame sequence beside a declared clip, is a flipbook as before. Cover mode takes no clips,
+so a declaration there changes nothing and the folder meets the raster limits.
+The text checks read DOM text, so keep clips clear of copy; a clip laid over a line is yours to
+catch on the stills. The manifest and the gate report list each clip.
+
 ## How the capture works
 
 The renderer serves the page to a software-rendered Chrome (SwiftShader, CPU

package/assets/lithermes-plugin/skills/readme-studio/templates/remotion/package-lock.json

@@ -3771,9 +3771,9 @@
       "license": "ISC"
     },
     "node_modules/zod": {
-      "version": "4.5.4",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.5.4.tgz",
-      "integrity": "sha512-sC95tT5iHHH9gtpj6A81kh+NEaRAUFN+qlUPDUbRfOMvNf5QCBqsb3WgvnpVtK5Y+4UfA6KqufotuTvMGiTlsA==",
+      "version": "4.6.6",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.6.tgz",
+      "integrity": "sha512-4UmzQUF5fxvfcYHlbjBmejU+w+hbDnWFx4aS8kBx7nPBHcO2SqPbpAG8snbdg+Xse4pRefR98hgjFgIMCI/UhA==",
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"

package/assets/lithermes-plugin/skills/readme-studio/templates/remotion/package.json

@@ -3,5 +3,6 @@
   "private": true,
   "type": "module",
   "scripts": {"render": "remotion render", "still": "remotion still"},
-  "dependencies": {"@remotion/cli":"4.0.526", "remotion":"4.0.526", "react":"19.3.0", "react-dom":"19.3.0"}
+  "dependencies": {"@remotion/cli":"4.0.526", "remotion":"4.0.526", "react":"19.3.0", "react-dom":"19.3.0"},
+  "overrides": {"zod": "4.6.6"}
 }

package/assets/lithermes-plugin/skills/rules/SKILL.md

@@ -169,7 +169,7 @@ priority rules.
   `paths` and Copilot `applyTo` aliases. A Cursor-style comma-separated scalar
   (`globs: *.ts,*.tsx`) is split into separate patterns.
 - **Glob support is a documented SUBSET**, not picomatch. `**`, `*`, `?`,
-  `[seq]`, `{a,b}` and a leading `!` work. Extglob (`@(a|b)`) and POSIX classes
+  `[seq]`, `{a,b}` and a leading (!) work. Extglob (`@(a|b)`) and POSIX classes
   (`[[:alpha:]]`) do NOT — a rule using them silently matches nothing. The full
   divergence list lives in `rules/globmatch.py` `DIVERGENCES`; read it before
   claiming a glob "should have" matched.

package/assets/lithermes-plugin/skills/visual-qa/references/complete-contract.md

@@ -485,7 +485,7 @@ isolated Hermes home. Use `--hermes-home`; never `--home`.
 
 ```text
 $ node packages/lithermes-installer/bin/lithermes.js install --yes --offline --no-hud --hermes-home "$ISOLATED"
-Installed LitHermes 1.0.32
+Installed LitHermes 1.0.34
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -502,7 +502,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.32)
+[OK] plugin.yaml readable (version 1.0.34)
 [OK] skills bundled: 40
 [OK] litgoal durable runtime importable
 ```

package/assets/{lithermes-plugin → npm-channel}/auto_update.py

@@ -42,6 +42,8 @@ INSTALL_TIMEOUT_SECONDS = 90.0
 MAX_RESPONSE_BYTES = 64 * 1024
 AUTO_UPDATE_GUARD_ENV = "LITHERMES_AUTO_UPDATE_RUNNING"
 INSTALLER_DISTRIBUTION = "npm"
+NPM_CHANNEL_MARKER_NAME = ".lithermes-npm-channel"
+NPM_CHANNEL_MARKER_TEXT = "lithermes npm channel\n"
 ATTEMPT_RECORD_NAME = "auto-update-attempt.json"
 # A broken npm fetch blocked each new session's first reply for about 70 s, so
 # after a failed install the bridge waits a day before it tries the same
@@ -244,19 +246,51 @@ def _read_install_receipt(home: Path) -> dict[str, Any] | None:
     return _read_state_json(home, "auto-update-receipt.json")
 
 
+def _plugin_dir(home: Path, manifest: dict[str, Any] | None) -> Path:
+    """Prefer the receipt's plugin path when it is a real directory, not a link."""
+
+    raw = manifest.get("pluginPath") if isinstance(manifest, dict) else None
+    if isinstance(raw, str) and raw.strip():
+        candidate = Path(raw).expanduser()
+        try:
+            info = candidate.lstat()
+        except OSError:
+            info = None
+        if info is not None and stat.S_ISDIR(info.st_mode) and not stat.S_ISLNK(info.st_mode):
+            return candidate
+    return home / "plugins" / "lithermes"
+
+
+def _channel_marker_matches(root: Path) -> bool:
+    marker = root / NPM_CHANNEL_MARKER_NAME
+    expected = NPM_CHANNEL_MARKER_TEXT.encode("utf-8")
+    try:
+        info = marker.lstat()
+        if not stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode):
+            return False
+        fd = os.open(marker, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+        try:
+            data = os.read(fd, len(expected) + 1)
+        finally:
+            os.close(fd)
+    except OSError:
+        return False
+    return data == expected
+
+
 def _is_npm_channel(home: Path) -> bool:
-    """Return true only for a manifest written by the npm installer.
-
-    Hermes catalog/git installs copy the plugin tree directly and do not create the
-    installer's ownership receipt.  The explicit distribution marker makes a stale
-    receipt fail closed too: a catalog payload must never use it as permission to
-    fetch and replace itself.  Older receipts without the marker are intentionally
-    treated as non-npm until the user runs the installer once, which preserves the
-    catalog safety boundary over an ambiguous channel.
+    """Return true only for an npm receipt that also carries the channel marker.
+
+    The receipt lives outside the plugin directory and survives a catalog replace,
+    so ``distribution: npm`` alone is not permission to fetch and replace the
+    tree. The marker is written only by the npm installer, into the plugin
+    directory, and a catalog copy never contains it. A symlink is not the marker.
     """
 
     manifest = _read_state_json(home, "install-manifest.json")
-    return isinstance(manifest, dict) and manifest.get("distribution") == INSTALLER_DISTRIBUTION
+    if not (isinstance(manifest, dict) and manifest.get("distribution") == INSTALLER_DISTRIBUTION):
+        return False
+    return _channel_marker_matches(_plugin_dir(home, manifest))
 
 
 def _utc_stamp(seconds: float | None = None) -> str:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/lithermes",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Hermes Agent plugin that plans, builds, checks and hands off your work when you add one word, lit, to a request.",
   "keywords": [
     "hermes-agent",

package/readme-assets/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.32"><title>release: 1.0.32</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.32</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.34"><title>release: 1.0.34</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.34</text></g></svg>

package/src/lib/canonicalCorpus.js

@@ -14,7 +14,7 @@ const EXPECTED = Object.freeze({
   tree: "9188410be0af35f2421ba300d91a0d7a7341caf0",
   fileCount: 167,
   totalBytes: 2596360,
-  digest: "b0d1a085de8856e7edeba24127d26875fe5473b80c0d95f6578addfdc801e445",
+  digest: "c921ed87f41b5aaef14ef480c791f1c36bbd3ec616eaccc32f5e1246fcc547e6",
   directories: ["design", "designpowers", "perfection", "ui-ux-db"],
   attributes: "corpus/** -text\nlegal/** -text\n",
   legal: [

package/src/lib/install.js

@@ -32,6 +32,9 @@ const { installSkins } = require("./skins");
 
 const packageRoot = path.resolve(__dirname, "..", "..");
 const assetRoot = path.join(packageRoot, "assets", "lithermes-plugin");
+const channelRoot = path.join(packageRoot, "assets", "npm-channel");
+const NPM_CHANNEL_MARKER_NAME = ".lithermes-npm-channel";
+const NPM_CHANNEL_MARKER_TEXT = "lithermes npm channel\n";
 const LEGACY_VENDOR_DIRS = new Map([
   ["vendor/022_handoff", "vendor/handoff"],
   ["vendor/045_scientific-visualization", "vendor/scientific-visualization"],
@@ -547,6 +550,24 @@ function previewModelRoute(flags = {}) {
   };
 }
 
+function stageNpmChannel(dest) {
+  const source = path.join(channelRoot, "auto_update.py");
+  const sourceStat = fs.lstatSync(source);
+  if (!sourceStat.isFile()) {
+    throw new LitHermesError("npm channel updater is missing.", 5);
+  }
+  const target = path.join(dest, "auto_update.py");
+  fs.copyFileSync(source, target);
+  fs.chmodSync(target, 0o644);
+  const marker = path.join(dest, NPM_CHANNEL_MARKER_NAME);
+  fs.writeFileSync(marker, NPM_CHANNEL_MARKER_TEXT, { encoding: "utf8", mode: 0o644 });
+  fs.chmodSync(marker, 0o644);
+  return [
+    { path: "auto_update.py", sha256: sha256(target) },
+    { path: NPM_CHANNEL_MARKER_NAME, sha256: sha256(marker) },
+  ];
+}
+
 function installLitHermes(flags = {}) {
   const dryRun = Boolean(flags["dry-run"]);
   const homeInfo = dryRun
@@ -655,6 +676,7 @@ function installLitHermes(flags = {}) {
     assertPluginParent(hermesHome);
     fs.rmSync(dest, { recursive: true, force: true });
     const files = copyTree(assetRoot, dest);
+    files.push(...stageNpmChannel(dest));
     onProgress("Writing Hermes config");
     checkState();
     let afterConfig = beforeConfig;