@litfamily/lithermes 1.0.33 → 1.0.34

package/README.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 <p align="center">
-<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/badge-version.svg" alt="1.0.33" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/badge-version.svg" alt="1.0.34" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -17,7 +17,7 @@
 
 A plugin for **Hermes Agent**. Put `lit` in front of a request, and Hermes plans the task, does it, checks the result and writes down where things stand, so the next session can pick up where this one stopped.
 
-**[README and docs on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/README_Ko-KR.md)
+**[README and docs on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/README_Ko-KR.md)
 
 ## Install
 

package/README_Ko-KR.md

@@ -1,14 +1,14 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 <p align="center">
-<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/badge-version.svg" alt="1.0.33" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/badge-version.svg" alt="1.0.34" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -17,7 +17,7 @@
 
 **Hermes Agent**용 플러그인입니다. 요청 앞에 `lit`을 붙이면 Hermes가 작업을 계획하고, 해내고, 결과를 확인한 뒤 어디까지 왔는지 적어 둡니다. 그래서 다음 세션이 그 기록을 읽고 멈춘 자리에서 이어 갈 수 있습니다.
 
-**[GitHub의 README와 문서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.33/README.md)
+**[GitHub의 README와 문서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.34/README.md)
 
 ## 설치
 

package/assets/lithermes-plugin/payload-version.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-10-31T04:39:04.686Z",
+  "syncedAt": "2026-11-01T12:25:40.311Z",
   "source": "bundled-payload",
-  "sourceHash": "eb3d5233f206bc088a614b8feedd37be49b298e4c9bb8de4d8ade6bd5805bc3f",
+  "sourceHash": "2301b868931c86d3bfeecdd04559f48bea1a0d8edf65879d4c3720755b023e07",
   "files": [
     {
       "path": "NOTICE.md",
@@ -181,7 +181,7 @@
     },
     {
       "path": "plugin.yaml",
-      "sha256": "52de503a4b2026a261e4ae4abe8df3bf107ac6833052537d53b601536dc963e1"
+      "sha256": "d3a858b2ae8b43fe9010b8078777737ab2bb6eae3f32b38b44043df7454e381d"
     },
     {
       "path": "provider_metrics.py",
@@ -1329,7 +1329,7 @@
     },
     {
       "path": "skills/frontend-ui-ux/references/complete-contract.md",
-      "sha256": "eae55bedc712a6c6ceba08b624324dc323addf9d4203c5e2b19f3b6ac37c7f34"
+      "sha256": "fae8c15d7256482e79a48444972ca1b91ae8ea723d362521648f74b286c12e9a"
     },
     {
       "path": "skills/frontend-ui-ux/references/composition.md",
@@ -4329,7 +4329,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/SKILL.md",
-      "sha256": "ff4c4f987a7762fce2d33cdc8ef86de670284310a843da9854a00bcaf70b6dd6"
+      "sha256": "a1da7728a3f998c05150a23426be0b7e1a0e000e58ffe5a24289d50a71b8370e"
     },
     {
       "path": "skills/lit-typographic-motion/bin/audio.py",
@@ -4417,7 +4417,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/engine/cover.mjs",
-      "sha256": "7bd6e2ff73ebb0525bf416f8685a36236316443631217245055c68668cfaa15f"
+      "sha256": "0a112972eacbc6b18f7ca1765a26a5044c4b5c76dfd4812338ae7486f831c2d9"
     },
     {
       "path": "skills/lit-typographic-motion/engine/director.mjs",
@@ -4485,7 +4485,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/engine/stage-gate.mjs",
-      "sha256": "fd3ddea38388d93a87fb3b880b834002a49b937a6705b929a290cb31e784ea06"
+      "sha256": "7ce876d61ed0cbee9b2e3f847e9da0257113572737b1f7c76649632a2a31ff9d"
     },
     {
       "path": "skills/lit-typographic-motion/engine/stage-init.js",
@@ -4493,7 +4493,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/engine/stage-kit.js",
-      "sha256": "4dc0083faf542f9b873d866438549f4f618896acbefa7b51797f44b00552931b"
+      "sha256": "b33f71648fd897c22c119841c1b43226cb11bb5ad855e85040a1dc8d81ca66e2"
     },
     {
       "path": "skills/lit-typographic-motion/engine/stage-qa.mjs",
@@ -4505,7 +4505,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/engine/stage.mjs",
-      "sha256": "fb31e467eed069d6110d121e31825d314b7bf4e8d478aea30bb04d99e8fbed34"
+      "sha256": "03165bde6fdb74ca8ad29e38a835629f672c272cb1e88d43c1c2f64914849a8f"
     },
     {
       "path": "skills/lit-typographic-motion/engine/stills.mjs",
@@ -4637,7 +4637,7 @@
     },
     {
       "path": "skills/lit-typographic-motion/references/stage.md",
-      "sha256": "555e788a408d41e74ce217a63507d096a4d945419e79f33cdf05cc4af236dca8"
+      "sha256": "c02bd6c8373bd684b58ae3f92c178418353465cbefabf310292c17cf8f91490b"
     },
     {
       "path": "skills/lit-typographic-motion/references/studio.md",
@@ -4941,7 +4941,7 @@
     },
     {
       "path": "skills/visual-qa/references/complete-contract.md",
-      "sha256": "c27ea8291007970ab513d9cca426538840dc6c24a4cfcb06c266765ecb5f6884"
+      "sha256": "393cc99a6fabb2fc40d8d77075833747580e2553614b552012ca1d22acc9e7e5"
     },
     {
       "path": "skills/visual-qa/schemas/evidence-manifest-v1alpha1.schema.json",

package/assets/lithermes-plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: lithermes
-version: 1.0.33
+version: 1.0.34
 description: "Hermes-native workflow toolkit: litgoal durable runtime, 5-lane review orchestrator, Litwork commands, skills, and prompt steering."
 author: "LitHermes contributors"
 kind: standalone

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/complete-contract.md

@@ -445,7 +445,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.33
+Installed LitHermes 1.0.34
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -462,7 +462,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.33)
+[OK] plugin.yaml readable (version 1.0.34)
 [OK] skills bundled: 40
 [OK] litgoal durable runtime importable
 ```

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/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.33
+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.33)
+[OK] plugin.yaml readable (version 1.0.34)
 [OK] skills bundled: 40
 [OK] litgoal durable runtime importable
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/lithermes",
-  "version": "1.0.33",
+  "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.33"><title>release: 1.0.33</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.33</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>