@litfamily/litgrok 1.0.30 → 1.0.32

package/.grok/rules/00-litgrok.md

@@ -203,7 +203,7 @@ An old agent name, prefixed or not, selects the renamed agent and prints that ro
 
 These rows are prompt guidance, not a router: old slash routes are not guaranteed; never create old skill directories or invent command metadata.
 
-<!-- litfamily:litgrok:start v=1.0.30 pre=0a -->
+<!-- litfamily:litgrok:start v=1.0.32 pre=0a -->
 ## LitGrok ground rules
 
 Grok Build reads this file on every turn. These lines are the working agreement. The sections above still choose the skill.

package/.grok/skills/lit-typographic-motion/references/stage.md

@@ -15,6 +15,7 @@ Allowed files: html, js, mjs, css, svg, png, jpg, webp, gif, wav, woff, woff2, t
   stage directory.
 - Rasters are textures and stills, never a frame sequence: at most 24 raster images and 8 MB in
   total. Ten or more rasters of one 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).
 - Forbidden, exit 17 naming it: `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`,
   `new Audio()`, `AudioContext`, `OfflineAudioContext`, Worker, SharedWorker, service workers,
   WebSocket, WebTransport, RTCPeerConnection.
@@ -25,6 +26,8 @@ Allowed files: html, js, mjs, css, svg, png, jpg, webp, gif, wav, woff, woff2, t
 <script src="/lit/stage-kit.js"></script>
 ```
 
+A page with clips also loads `<script src="/lit/clips.js"></script>` (Clips).
+
 `/lit/fonts.css` declares the verified faces with `font-display: block`: `Archivo` (weights 400,
 700, 900; `font-stretch` 75 %, 100 %, 125 %), `Pretendard` (Hangul, 400 and 700), `VT323`,
 `Silkscreen` (400, 700), `Galmuri9` and `Meslo` (both need the pre-warm), and `JetBrains Mono`
@@ -88,11 +91,58 @@ LitStage.drawPath(svgPath, p);                       // stroke draw-on
 const shape = LitStage.morph(dA, dB); path.setAttribute('d', shape(p));        // single-subpath morph
 LitStage.clip(el, p, { from: 'left' });              // inset reveal; LitStage.circle(el, p, { x, y })
 const c = LitStage.mix('#0b1f33', '#7fd1ff', p);     // colour mix
+const show = LitStage.overlay({ parent, id, box });    // a declared keyed clip (Clips); show(t, { start })
 ```
 
 `morph` normalizes both paths to cubics, resamples them by arc length and picks the best rotation;
 paths with more than one subpath are not supported (split them into separate paths).
 
+## Clips
+
+Real keyed footage (a reaction clip, a spinning-cat loop shot on green screen) joins the film as a
+layer inside the page. Key the video outside the renderer into one 8-bit RGBA PNG per frame, declare
+the frames, and the page picks the frame from film time. A declared clip leaves the flipbook and
+count rule; every other raster keeps its limits. Nothing is encoded by hand: the page is captured
+frame by frame as usual, so the flash audit, the determinism replay and the text checks run on the
+final pixels.
+
+1. Copy each clip's frames into the run's stage folder as `stage/clips/<dir>/frame_0001.png`,
+   `frame_0002.png` and so on, with no gaps and no other image in the folder.
+2. Declare them in `stage/clips/clips.json`:
+
+   ```json
+   { "clips": [ { "id": "boom", "dir": "01-vine-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. A clip used twice is declared once.
+3. The page loads `<script src="/lit/clips.js"></script>` after the kit, registers each use once with
+   `LitStage.overlay({ parent, id, box })` and calls the returned `show(t, opts)` from `render(t)`.
+   (`LitStage.clip` is the inset reveal; it has nothing to do with clips.) `parent` is the element
+   the clip sits in; `box` is its place in pixels, the frame fitted inside it. `show` returns the
+   clip's wrapper element, or `null` while hidden; scale, fade or move that wrapper from `t` like any
+   other layer.
+
+```js
+const boom = LitStage.overlay({ parent: stageEl, id: 'boom', box: { x: 1200, y: 300, w: 520, h: 511 } });
+render(t) { boom(t, { start: 2.1 }); }
+```
+
+The frame is `floor((t - start) * fps) + 1`, counted from `from`, so a cue is plain arithmetic: a
+clip whose own sound starts at frame 85 and must land on a cue at 0.12 s has
+`start = 0.12 - 84 / 30`. Options: `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 past `to`, without `loop` or `hold`, the clip is hidden.
+
+The scan refuses, with exit 17 and the clip named: more than 12 clips, 360 frames in a clip or 1500
+in all, 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), an fps 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, and a duplicate `id`. A folder that is not declared,
+or any frame sequence beside a declared clip, is a flipbook as before. Cover mode takes no clips.
+Keep clips clear of copy: the text checks read DOM text, so a clip laid over a line is yours to
+catch on the stills. The manifest and the gate report list each clip.
+
 ## Serving and network
 
 The page is served from the synthetic origin `http://lit.stage/` with no listening socket. Only

package/.grok/skills/lit-typographic-motion/scripts/lib/clips.mjs

@@ -0,0 +1,119 @@
+// Declared keyed overlay clips on the stage path: stage/clips/clips.json names RGBA frame folders,
+// scanClips checks every declared frame against its bytes, and clipsScript writes the table the page
+// reads as window.LitClips (served at /lit/clips.js). See references/stage.md, Clips.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLIP_LIMITS } from './constants.mjs';
+import { decodePng } from './png.mjs';
+
+export const CLIPS_DIR = 'clips';
+export const clipFrame = (i) => `frame_${String(i).padStart(4, '0')}.png`;
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/;
+const DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const MB = 1024 * 1024;
+
+/** Header facts of a PNG: size, bit depth, colour type (6 = RGBA) and whether it is an APNG. */
+function pngHeader(bytes) {
+  if (bytes.length < 33 || bytes.toString('latin1', 1, 4) !== 'PNG') return null;
+  let animated = false;
+  for (let o = 8; o + 8 <= bytes.length;) {
+    const type = bytes.toString('latin1', o + 4, o + 8);
+    if (type === 'acTL') animated = true;
+    if (type === 'IDAT' || type === 'IEND') break;
+    o += 12 + bytes.readUInt32BE(o);
+  }
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), bitDepth: bytes[24], colorType: bytes[25], animated };
+}
+
+/** The clips stage/clips/clips.json declares ([] without the file), checked for shape only. Throws Error. */
+export function declaredClips(stageDir, limits = CLIP_LIMITS) {
+  const file = join(stageDir, 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();
+  const 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' || !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' || !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 };
+  });
+}
+
+/**
+ * Check every declared clip against its bytes. Each clip needs exactly frame_0001.png..frame_<count>.png in clips/<dir>/, every one an
+ * 8-bit still RGBA PNG of one size within the overlay cap, a transparent pixel in the first, middle and
+ * last frame, and the per-clip and total caps. Throws Error naming the clip; returns
+ * [{ id, dir, count, fps, width, height, bytes, frames }] where `frames` are stage-relative paths.
+ */
+export function scanClips(stageDir, { limits = CLIP_LIMITS } = {}) {
+  const decls = declaredClips(stageDir, limits);
+  let totalFrames = 0;
+  let totalBytes = 0;
+  const clips = decls.map((d) => {
+    if (d.count > limits.framesPerClip) throw new Error(`clip "${d.id}": ${d.count} frames (at most ${limits.framesPerClip} per clip)`);
+    const prefix = `${CLIPS_DIR}/${d.dir}/`;
+    const folder = join(stageDir, CLIPS_DIR, d.dir);
+    const have = new Set(existsSync(folder) ? readdirSync(folder, { withFileTypes: true }).filter((e) => e.isFile() && /\.(png|jpe?g|webp|gif)$/i.test(e.name)).map((e) => e.name) : []);
+    const frames = [];
+    for (let i = 1; i <= d.count; i += 1) {
+      if (!have.has(clipFrame(i))) throw new Error(`clip "${d.id}": ${prefix}${clipFrame(i)} is missing (declared ${d.count} frames, named frame_0001.png onward)`);
+      frames.push(`${prefix}${clipFrame(i)}`);
+    }
+    const stray = [...have].find((name) => !frames.includes(`${prefix}${name}`));
+    if (stray) throw new Error(`clip "${d.id}": ${prefix}${stray} is not one of the ${d.count} declared frames; raise count or remove it`);
+    let size = null;
+    let bytes = 0;
+    const read = (rel) => readFileSync(join(stageDir, ...rel.split('/')));
+    const headers = frames.map((rel) => {
+      const buffer = read(rel);
+      bytes += buffer.length;
+      const info = pngHeader(buffer);
+      if (!info) throw new Error(`clip "${d.id}": ${rel} is not a readable PNG`);
+      if (info.animated) throw new Error(`clip "${d.id}": ${rel} is an animated image; a clip is a folder of still frames`);
+      if (info.colorType !== 6 || info.bitDepth !== 8) throw new Error(`clip "${d.id}": ${rel} must be an 8-bit RGBA PNG with an alpha channel (a keyed frame), not an opaque image`);
+      if (Math.max(info.width, info.height) > limits.side) throw new Error(`clip "${d.id}": ${rel} is ${info.width}x${info.height}; a clip is an overlay of at most ${limits.side} px on the long side`);
+      if (size && (size.width !== info.width || size.height !== info.height)) throw new Error(`clip "${d.id}": ${rel} is ${info.width}x${info.height} but frame_0001.png is ${size.width}x${size.height}; one size per clip`);
+      size = { width: info.width, height: info.height };
+      return buffer;
+    });
+    if (bytes > limits.bytesPerClip) throw new Error(`clip "${d.id}": ${(bytes / MB).toFixed(1)} MB (at most ${(limits.bytesPerClip / MB).toFixed(0)} MB per clip)`);
+    for (const at of [0, Math.floor((frames.length - 1) / 2), frames.length - 1]) {
+      let pixels;
+      try { ({ pixels } = decodePng(headers[at])); } catch (error) { throw new Error(`clip "${d.id}": ${frames[at]} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`); }
+      let keyed = false;
+      for (let i = 3; i < pixels.length && !keyed; i += 4) keyed = pixels[i] < 255;
+      if (!keyed) throw new Error(`clip "${d.id}": ${frames[at]} has no transparent pixel; a clip is keyed, not a full-frame video`);
+    }
+    totalFrames += d.count;
+    totalBytes += bytes;
+    return { ...d, ...size, bytes, frames };
+  });
+  if (totalFrames > limits.framesTotal) throw new Error(`${totalFrames} clip frames in all (at most ${limits.framesTotal})`);
+  if (totalBytes > limits.bytesTotal) throw new Error(`${(totalBytes / MB).toFixed(1)} MB of clip frames in all (at most ${(limits.bytesTotal / MB).toFixed(0)} MB)`);
+  return clips;
+}
+
+/**
+ * The script served at /lit/clips.js: window.LitClips = { id: { src, count, fps, width, height } }, from
+ * clips.json and each first frame's header. null when the stage declares no clips, or one the scan refuses.
+ */
+export function clipsScript(stageDir) {
+  try {
+    const table = Object.fromEntries(declaredClips(stageDir).map((c) => {
+      const info = pngHeader(readFileSync(join(stageDir, CLIPS_DIR, c.dir, clipFrame(1))));
+      return [c.id, { src: `${CLIPS_DIR}/${c.dir}`, count: c.count, fps: c.fps, width: info.width, height: info.height }];
+    }));
+    return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
+  } catch { return null; }
+}

package/.grok/skills/lit-typographic-motion/scripts/lib/constants.mjs

@@ -195,6 +195,19 @@ export const STAGE = Object.freeze({
   determinismMax: 16,
 });
 
+// Keyed overlay clips (references/stage.md, Clips): frame folders declared in stage/clips/clips.json
+// are held to these caps instead of the raster limits above. A clip is a sticker on the film, never
+// the film: 8-bit RGBA PNG frames with real transparency, 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,
+});
+
 // Cover mode (references/cover.md): the README cover loop and the gate that reads its DECODED file.
 // Calibrated on 2026-10-20 against eight earlier painted covers, four slide-like negatives and
 // three pilot loops; a number moves only with a new calibration table. FLOOR fails a cover (every

package/.grok/skills/lit-typographic-motion/scripts/lib/cover.mjs

@@ -137,7 +137,7 @@ function prepare({ out, env }) {
   const treatment = loadCoverTreatment(out);
   const dir = join(out, COVER_DIR);
   if (!existsSync(join(dir, 'index.html'))) throw new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${join(dir, 'index.html')} is missing; write the cover page first (start from a recipe in recipes/)`);
-  const scan = scanStage(dir);
+  const scan = scanStage(dir, { clips: false });
   const rename = (line) => line.replaceAll('stage/', `${COVER_DIR}/`);
   if (scan.network.length) throw new BlockedError(EXIT.STAGE_NETWORK, `STAGE_NETWORK_REQUEST: ${rename(scan.network[0])}; a cover loads only its own files and the /lit/ routes`);
   if (scan.contract.length) throw new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${rename(scan.contract[0])}`);

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-gate.mjs

@@ -124,6 +124,7 @@ export function stageReportText({ manifest, gate, withheld, perf, outDir, treatm
   lines.push(`path: stage · format ${manifest.format} (${manifest.resolution.join('x')}) · ${manifest.durationSec.toFixed(2)} s of ${treatment.durationSec} s target @ ${manifest.fps} fps`);
   lines.push(`sound: ${manifest.sound?.label ?? 'n/a'}${manifest.sound?.timbre ? ` (${manifest.sound.timbre}, ${manifest.sound.key}, ${manifest.sound.tempo} BPM, ${manifest.sound.lufs?.toFixed?.(1)} LUFS)` : ''}`);
   lines.push(`renderer: ${manifest.renderer}`);
+  if (manifest.clips?.length) lines.push(`clips: ${manifest.clips.map((c) => `${c.id} ${c.frames} frames at ${c.fps} fps`).join(', ')} (keyed overlays, chosen from film time)`);
   lines.push('');
   lines.push(`QA gate: ${gate.status}`);
   for (const r of gate.results) lines.push(`  ${`${r.id}:`.padEnd(30)}${r.status}  (${r.detail})`);

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-session.mjs

@@ -7,6 +7,7 @@ import { extname, join, sep } from 'node:path';
 import { STAGE } from './constants.mjs';
 import { launchStage } from './chrome.mjs';
 import { SKILL_ROOT } from './fonts.mjs';
+import { clipsScript } from './clips.mjs';
 
 export const CONTENT_TYPES = Object.freeze({
   '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
@@ -78,6 +79,7 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
   const network = [];
   const refused = [];
   const served = new Set();
+  const clipsJs = clipsScript(stageDir);
   const kit = existsSync(KIT_PATH) ? readFileSync(KIT_PATH) : Buffer.from('/* stage kit missing */');
   const respond = (requestId, status, body, type) => browser.send('Fetch.fulfillRequest', {
     requestId, responseCode: status,
@@ -95,6 +97,7 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
       return;
     }
     if (url.pathname === '/lit/stage-kit.js') { served.add('/lit/stage-kit.js'); await respond(requestId, 200, kit, CONTENT_TYPES['.js']); return; }
+    if (clipsJs && url.pathname === '/lit/clips.js') { served.add('/lit/clips.js'); await respond(requestId, 200, clipsJs, CONTENT_TYPES['.js']); return; }
     if (url.pathname.startsWith('/lit/three/')) {
       const resolved = resolveThree(url.pathname);
       if (resolved.refused) { refused.push(resolved.refused); await respond(requestId, 403, 'refused'); return; }

package/.grok/skills/lit-typographic-motion/scripts/lib/stage.mjs

@@ -6,6 +6,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { extname, join, relative } from 'node:path';
 import { BlockedError, DIRECTOR, EXIT, STAGE } from './constants.mjs';
+import { scanClips } from './clips.mjs';
 import { resolveChrome, stageArgs } from './chrome.mjs';
 import { fontPath, fontState, PINS, resolveFontKey } from './fonts.mjs';
 import { FlashDetector } from './flash.mjs';
@@ -67,17 +68,24 @@ export function rasterInfo(bytes, ext) {
 }
 
 // Static scan before any launch: forbidden elements (17), absolute or protocol-relative URLs and
-// preconnect/prefetch links (19), raster limits, flipbooks and animated rasters (17).
-export function scanStage(stageDir) {
+// preconnect/prefetch links (19), raster limits, flipbooks and animated rasters (17). Frames of a clip
+// declared in clips/clips.json are checked by scanClips instead; `clips: false` (cover mode) ignores the
+// declaration, so a declared folder is held to the raster limits like any other.
+export function scanStage(stageDir, { clips: allowClips = true } = {}) {
   const contract = [];
   const network = [];
   const warnings = [];
-  if (!existsSync(join(stageDir, 'index.html'))) return { contract: ['stage/index.html is missing'], network, warnings, files: [], rasters: [] };
+  if (!existsSync(join(stageDir, 'index.html'))) return { contract: ['stage/index.html is missing'], network, warnings, files: [], rasters: [], clips: [] };
   const files = walk(stageDir);
   // A Blender plate and its preview stills are frames the runner wrote and plate.json lists by name
   // and size; they are not page rasters. Anything not listed is held to the raster limits.
   const plates = [readPlate(stageDir, 'plate'), readPlate(stageDir, 'plate-preview')].filter(Boolean);
   const listed = new Set(plates.flatMap((p) => p.frames.map((f) => `${p.dir}/${String(f.name)}`)));
+  let clips = [];
+  if (allowClips) {
+    try { clips = scanClips(stageDir); } catch (error) { contract.push(error.message); }
+    for (const clip of clips) for (const rel of clip.frames) listed.add(rel);
+  }
   const rasters = [];
   for (const file of files) {
     if (file.symlink) continue;
@@ -112,7 +120,7 @@ export function scanStage(stageDir) {
   const bySize = new Map();
   for (const r of rasters) { const key = `${r.width}x${r.height}`; bySize.set(key, (bySize.get(key) ?? 0) + 1); }
   for (const [size, count] of bySize) if (count >= STAGE.flipbookCount) contract.push(`${count} rasters of one size (${size}) form a flipbook; rasters are textures and stills, never a frame sequence`);
-  return { contract, network, warnings, files: files.map((f) => f.rel), rasters };
+  return { contract, network, warnings, files: files.map((f) => f.rel), rasters, clips };
 }
 
 // ---- fonts -----------------------------------------------------------------------------------
@@ -424,6 +432,7 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
       schemaVersion: 1, path: 'stage', format: treatment.format, resolution: [width, height], fps, durationSec: totalFrames / fps, targetDurationSec: treatment.durationSec,
       frames: totalFrames, seed, rung: masterRung, renderer: `${masterRenderer} on the ${masterRung} rung (stage path)`, softwareRenderer: masterRung === 'software' || isSoftwareRenderer(masterRenderer), chromeFlags: masterArgs.filter((arg) => !arg.startsWith('--user-data-dir') && !arg.startsWith('--window-size') && arg !== 'about:blank'), previewEncoder: preview.encoder,
       sound: sound.summary, round, warnings,
+      clips: scan.clips.map((c) => ({ id: c.id, frames: c.count, fps: c.fps, width: c.width, height: c.height, bytes: c.bytes })),
     };
     const stills = writeStills(out, { plan, frames: kept, width, height, path: 'stage', round, mode: 'full', poster: { bytes: posterBytes, frame: posterFrame }, treatmentSha256 });
     // The final render ships its storyboard too: the done-check wants the board viewed on the final set.

package/.grok/skills/lit-typographic-motion/scripts/stage/stage-kit.js

@@ -280,6 +280,49 @@
     };
   }
 
+  // A declared keyed clip (stage/clips/clips.json, served as window.LitClips by /lit/clips.js): one
+  // wrapper at `box` over the film, holding the clip's frame for t. The frame is a pure function of film
+  // time, floor((t - start) * fps) + 1 within from..to, so no <video> and no real clock is involved.
+  // Before `start` and after `to` the wrapper is hidden (null) unless `hold` keeps the last frame or
+  // `loop` wraps by frame index. The wrapper is what a page scales or fades; the <img> inside is
+  // replaced on a frame change, so the renderer waits for its decode before the capture.
+  function overlay(opts) {
+    var all = root.LitClips, parent = opts && opts.parent, id = opts && opts.id, box = opts && opts.box;
+    if (!all) throw new Error('LitStage.overlay: load <script src="/lit/clips.js"></script> before the page script; the stage declares no clips (clips/clips.json)');
+    var c = all[id];
+    if (!c) throw new Error('LitStage.overlay: no clip "' + id + '" in clips/clips.json (declared: ' + Object.keys(all).join(', ') + ')');
+    if (!parent || !box || !(box.w > 0) || !(box.h > 0)) throw new TypeError('LitStage.overlay: pass { parent, id, box: { x, y, w, h } }');
+    var doc = parent.ownerDocument || root.document;
+    var wrap = doc.createElement('div');
+    wrap.setAttribute('data-lit-clip', id);
+    var ws = wrap.style;
+    ws.position = 'absolute'; ws.left = box.x + 'px'; ws.top = box.y + 'px'; ws.width = box.w + 'px'; ws.height = box.h + 'px';
+    ws.display = 'none'; ws.pointerEvents = 'none';
+    parent.append(wrap);
+    var shown = 0, img = null;
+    return function (t, o) {
+      o = o || {};
+      var start = o.start == null ? 0 : o.start, from = o.from == null ? 1 : o.from, to = o.to == null ? c.count : o.to;
+      if (!(from >= 1 && to <= c.count && from <= to)) throw new RangeError('LitStage.overlay: from..to must lie within 1..' + c.count + ' (got ' + from + '..' + to + ')');
+      var n = to - from + 1, k = Math.floor((t - start) * c.fps + 1e-6);
+      var i = k < 0 ? 0 : k < n ? from + k : o.loop ? from + (k % n) : o.hold ? to : 0;
+      wrap.style.display = i ? 'block' : 'none';
+      if (!i) return null;
+      if (i !== shown) {
+        var next = doc.createElement('img');
+        next.src = c.src + '/frame_' + String(i).padStart(4, '0') + '.png';
+        next.alt = '';
+        var ns = next.style;
+        ns.display = 'block'; ns.width = '100%'; ns.height = '100%'; ns.objectFit = 'contain';
+        if (img) img.replaceWith(next);
+        else wrap.append(next);
+        img = next;
+        shown = i;
+      }
+      return wrap;
+    };
+  }
+
   function rgb(hex) {
     var h = String(hex).replace('#', '');
     if (h.length === 3) h = h.split('').map(function (c) { return c + c; }).join('');
@@ -472,6 +515,7 @@
     clip: clip,
     circle: circle,
     plate: plate,
+    overlay: overlay,
     mix: mix,
     rgb: rgb,
     hex: hex,