@litfamily/litopencode 1.0.36 → 1.0.38

package/docs/reference.md

@@ -498,12 +498,34 @@ settings but does not send them yet.
   TUI: the line under the prompt (`prompt.footer.status`) reads `🔥 LIT IGNITED · <discipline>` while the
   latest prompt of the session is a lit prompt. On OpenCode 1 the mark stays where it was.
 - *Toasts.* The server cannot show toasts on OpenCode 2. The TUI raises the ignition toast itself when a
-  user message arrives with the lit mark the server writes into its metadata. The automatic-handoff
-  notices and the skill hint, which only the server knew about, are not shown there.
-- *TUI.* The mission panel sits in the session sidebar as before. OpenCode 2 passes no options to a TUI
-  that comes with a server plugin, and it keeps no todo list, so mission progress comes from the ledger,
-  the work record and the plan. The status band under the session and the home-screen line are drawn on
-  OpenCode 1 only.
+  user message arrives with the lit mark the server writes into its metadata, and it raises the same gate
+  toasts as OpenCode 1 (plan saved, goal set, criterion passed, blockers, complete) plus three more that
+  only OpenCode 2 has: the workflow stage moving (`🔥 Stage`, `work 3/7`), a switch of discipline
+  (`🔥 lit-loop → start-work`) and a lane starting or finishing. A burst folds into one toast with a
+  `+N more` tail. The restart notice, the `lit adhd` suggestion and the opt-in finish alert work as on
+  OpenCode 1. The automatic-handoff notices, which only the server knew about, reach the screen through
+  `.litopencode/notices.jsonl`: the OpenCode 2 server plugin can only subscribe to events and has no way to
+  raise a toast, so it appends each notice there and the TUI plugin shows the lines that appear after it
+  started (the file is capped and never follows a symbolic link). The one popup the server raised besides
+  those, the ignition toast, is already the TUI's own, so there is no separate skill hint left to port.
+- *TUI.* The HUD is placed in the slots OpenCode 2 publishes: the status card is claimed in `app`, under
+  the session and the sidebar, and keeps its four rows idle or working; the stage chip shares
+  `prompt.footer.status` with the ignition line, because there is no slot right of the agent and model
+  row; the home line is in `home.footer`; the mission panel sits in `sidebar.content`, so it shows when
+  the sidebar is open. The card, chip, panel and home line use the same text builders as OpenCode 1. The
+  `band` and `notify` options of the plugin entry are read from the options OpenCode 2 hands over. The footer
+  line steps down with the terminal width instead of being clipped by the host: mark plus the whole chip,
+  mark plus a smaller chip, the chip alone, the chip as `🔥 1/3`, the bare flame, then nothing; the room is the
+  width less the sidebar (assumed open above 120 columns) and the host's own spinner and figures. OpenCode 2
+  keeps no todo list, so mission progress comes from the ledger, the work record and the plan. It names
+  its tools differently (`shell`, `subagent`, a `skill` tool that takes `id`), and the card reads those
+  names. OpenCode 2 gives plugins one usage source, `client.usage.limits()`: the OpenCode Go allowance of the
+  Console workspace the location is signed in to (a rolling five-hour window, a weekly one and a monthly
+  one). For a session whose latest answer came from the `opencode-go` provider the card's bottom border shows
+  `5h 42% · 1w 18%` after the context figure (the monthly window only from 90%, and a window the host reports
+  as refusing requests reads `limited`). It asks at most once a minute. For any other provider, a signed-out
+  host (the reply is `null`) or an error, nothing is drawn; OpenCode 2 exposes no provider rate-limit headers or
+  events to a plugin, so there is no 5-hour or weekly figure for the Anthropic or OpenAI plans.
 - *Updates.* There is no automatic self-update inside the plugin on OpenCode 2. Run
   `opencode plugin update`, or let OpenCode 2's own update policy handle it.
 
@@ -586,7 +608,7 @@ What it draws:
     the colour wheel at one fixed lightness, four small colour steps a second with no flashing. It
     is off under `motion: false` and `NO_COLOR`. An idle session in a workspace with earlier work
     says `lit adhd to pick up where you left off`, and the first fresh session there raises one
-    toast with the same words (v1 TUI only; the v2 TUI has no band and no toast).
+    toast with the same words (OpenCode 1 and 2).
   - one look at a time, picked from a small registry in `src/tui/mission-looks.ts`. Every route that runs
     lit-adhd wears the rewind look: `lit adhd`/`lit rewind` in chat, `/lit-adhd`/`/lit-rewind` (also from an
     installed v2 alias file) and a native `skill` load. While the session waits on you (a permission or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litopencode",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "Workflow plugin for OpenCode: add lit to a prompt and the work is planned, built, checked and written down so the next session can pick it up.",
   "keywords": [
     "opencode",
@@ -70,7 +70,7 @@
   },
   "dependencies": {
     "yaml": "^2.9.0",
-    "zod": "4.1.8"
+    "zod": "4.6.6"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.6",
@@ -79,6 +79,10 @@
     "picomatch": "^4.0.5",
     "typescript": "^5.9.3"
   },
+  "overrides": {
+    "zod": "$zod",
+    "toml": "5.0.1"
+  },
   "publishConfig": {
     "access": "public"
   }

package/skills/lit-typographic-motion/engine/cover/render.mjs

@@ -108,7 +108,7 @@ function prepare(out) {
   const cover = loadCoverTreatment(out);
   const coverDir = path.join(out, "cover");
   if (!existsSync(path.join(coverDir, "index.html"))) throw stop(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `no cover page at ${path.join(coverDir, "index.html")}; write it first (references/cover.md)`);
-  const scan = scanStage(coverDir);
+  const scan = scanStage(coverDir, { clips: false });
   const assets = checkAssets({ out, treatment: cover, rasters: scan.rasters });
   const state = inspectWarmState();
   if (state.blocked) throw stop(state.blocked.exit, state.blocked.name, `${state.blocked.detail}; fix: ${state.fix}`);

package/skills/lit-typographic-motion/engine/stage/capture.mjs

@@ -6,7 +6,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { chromeFlagRungs } from "../constants.mjs";
-import { StageError, contentTypes, insideDir } from "./scan.mjs";
+import { StageError, clipsScript, contentTypes, insideDir } from "./scan.mjs";
 
 export const stageHost = "lit.stage";
 export const stageOrigin = `http://${stageHost}`;
@@ -108,7 +108,8 @@ export async function openStage(chromium, { chromePath, profile, stageDir, width
     const line = String(error?.message ?? error).split("\n").find((part) => part.trim()) ?? String(error);
     throw Object.assign(new Error(`BLOCKED_NO_CHROME (10): Chrome failed to launch headless: ${line}; fix: check that Chrome can start headless in this sandbox`), { exitCode: 10 });
   }
-  const { blocked, refused, missing } = await serveStage(context, { stageDir, fonts, scripts: { "/lit/stage-kit.js": kitSource(), ...styleFiles } });
+  const clips = clipsScript(stageDir);
+  const { blocked, refused, missing } = await serveStage(context, { stageDir, fonts, scripts: { "/lit/stage-kit.js": kitSource(), ...(clips ? { "/lit/clips.js": clips } : {}), ...styleFiles } });
   await context.addInitScript({ content: `window.__litStageConfig = ${JSON.stringify({ seed: seed >>> 0, fps })};\n${clockSource()}` });
   if (extraInit) await context.addInitScript({ content: extraInit });
   const page = context.pages()[0] ?? await context.newPage();

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

@@ -146,6 +146,7 @@ export function formatStageReport(result, context) {
     `outputs: ${out("film.mp4")} · ${out(manifest.previewEncoder === "gif" ? "preview.gif" : "preview.webp")} (encoder: ${manifest.previewEncoder}) · ${out("poster.png")} · ${out("reduced-motion.png")}`,
     `format / fps / length: ${manifest.format} ${manifest.resolution.join("x")} @ ${manifest.fps} fps, ${manifest.durationSec.toFixed(2)} s (treatment ${manifest.targetDurationSec} s)`,
     `renderer: stage ${manifest.rung === "gpu" ? `GPU rung (${manifest.renderer ?? "native ANGLE"})` : "software rung"} (flags: ${(manifest.chromeFlags ?? []).join(" ")})`,
+    ...(manifest.clips?.length ? [`clips: ${manifest.clips.map((clip) => `${clip.id} ${clip.frames} frames at ${clip.fps} fps`).join(", ")} (keyed overlays, chosen from film time)`] : []),
     ...(manifest.warnings ?? []).map((note) => `notice: ${note}`),
     `timing: master ${manifest.timing?.masterSec ?? "?"} s, per frame p50 ${manifest.timing?.frameP50 ?? "?"} ms / p95 ${manifest.timing?.frameP95 ?? "?"} ms, total ${manifest.timing?.totalSec ?? "?"} s`,
     "",

package/skills/lit-typographic-motion/engine/stage/render.mjs

@@ -450,6 +450,7 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
       preview: preview ? { width: preview.width, height: preview.height, fps: preview.fps, bytes: preview.bytes } : null,
       posterFrame, posterSize: [poster.width, poster.height], stillFrame, determinismFrames: samples,
       timing: { ...master.timing, totalSec: Number(((performance.now() - began) / 1000).toFixed(1)) },
+      ...(context.scan.clips.length ? { clips: context.scan.clips.map((clip) => ({ id: clip.id, frames: clip.count, fps: clip.fps, width: clip.width, height: clip.height, bytes: clip.bytes })) } : {}),
       ...(context.plate ? { plate: { blender: context.plate.blender, engine: context.plate.engine, device: context.plate.device, samples: context.plate.samples, fps: context.plate.fps, frames: context.plate.frames.length } } : {}),
       sound, qa: { file: ".run/qa.json", samples: qaResult.samples.length, trackFrames: qaResult.trackFrames, allowedFaces: qaResult.allowedFaces },
       treatmentSha256: sha256(readFileSync(path.join(out, "treatment.json"))), stageSha256: stageSha(context.stageDir),

package/skills/lit-typographic-motion/engine/stage/scan.mjs

@@ -5,6 +5,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
+import { decodePng } from "../png.mjs";
 
 export const STAGE_CONTRACT = 17;
 export const STAGE_NETWORK = 19;
@@ -32,6 +33,11 @@ export function readPlate(stageDir, sub = "plate") {
 }
 
 export const rasterLimits = Object.freeze({ files: 24, bytes: 8 * 1024 * 1024, sameSizeFlipbook: 10 });
+// Keyed overlay clips: frame folders that stage/clips/clips.json declares are held to these caps instead of
+// rasterLimits. 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, at most `fps` frames a second.
+export const clipLimits = Object.freeze({ clips: 12, framesPerClip: 360, framesTotal: 1500, bytesPerClip: 40 * 1024 * 1024, bytesTotal: 128 * 1024 * 1024, side: 720, fps: 30 });
+export const clipsDir = "clips";
 // XML namespace identifiers are names, not requests.
 const namespaceUris = /https?:\/\/www\.w3\.org\/(?:2000\/svg|1999\/xlink|1999\/xhtml|XML\/1998\/namespace|2000\/xmlns\/?|1998\/Math\/MathML)/gu;
 
@@ -76,7 +82,7 @@ export function rasterInfo(bytes, ext) {
       if (type === "IDAT" || type === "IEND") break;
       offset += 12 + length;
     }
-    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), animated };
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), animated, bitDepth: bytes[24], colorType: bytes[25] };
   }
   if (ext === ".gif") {
     const width = bytes.readUInt16LE(6), height = bytes.readUInt16LE(8);
@@ -123,10 +129,108 @@ export function rasterInfo(bytes, ext) {
   return null;
 }
 
-// Throws a StageError for the first violation; returns the raster list for pre-decoding.
-export function scanStage(stageDir) {
+// ---- declared clips: stage/clips/clips.json and the frame folders it names ----
+const clipFrame = (n) => `frame_${String(n).padStart(4, "0")}.png`;
+const clipId = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/u;
+const clipFolder = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u;
+
+// The clips stage/clips/clips.json declares ([] without the file), checked for shape only. Throws exit 17.
+export function declaredClips(stageDir, limits = clipLimits) {
+  const file = path.join(stageDir, clipsDir, "clips.json");
+  if (!existsSync(file)) return [];
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw contract(`${clipsDir}/clips.json is not valid JSON (${error.message})`); }
+  if (!doc || !Array.isArray(doc.clips)) throw contract(`${clipsDir}/clips.json needs { "clips": [ { "id", "dir", "count", "fps" } ] }`);
+  if (doc.clips.length > limits.clips) throw contract(`${doc.clips.length} clips declared (at most ${limits.clips} clips)`);
+  const ids = new Set();
+  const dirs = new Set();
+  return doc.clips.map((entry, n) => {
+    const at = `${clipsDir}/clips.json clip #${n + 1}`;
+    if (!entry || typeof entry !== "object") throw contract(`${at} is not an object`);
+    if (typeof entry.id !== "string" || !clipId.test(entry.id)) throw contract(`${at}: id must be a plain token of letters, digits, - and _ (got ${JSON.stringify(entry.id)})`);
+    if (ids.has(entry.id)) throw contract(`${at}: duplicate id ${entry.id}`);
+    ids.add(entry.id);
+    if (typeof entry.dir !== "string" || !clipFolder.test(entry.dir) || entry.dir.includes("..")) throw contract(`clip "${entry.id}": dir must be a folder name directly under ${clipsDir}/ (got ${JSON.stringify(entry.dir)})`);
+    if (dirs.has(entry.dir)) throw contract(`clip "${entry.id}": dir ${entry.dir} is already declared by another clip`);
+    dirs.add(entry.dir);
+    if (!Number.isInteger(entry.count) || entry.count < 1) throw contract(`clip "${entry.id}": count must be a whole number of frames (got ${JSON.stringify(entry.count)})`);
+    if (!Number.isInteger(entry.fps) || entry.fps < 1 || entry.fps > limits.fps) throw contract(`clip "${entry.id}": fps must be a whole number from 1 to ${limits.fps} (got ${JSON.stringify(entry.fps)})`);
+    return { id: entry.id, dir: entry.dir, count: entry.count, fps: entry.fps };
+  });
+}
+
+// Checks every declared clip against its bytes: exactly frame_0001.png..frame_<count>.png in clips/<dir>/,
+// each an 8-bit still RGBA PNG of one size within the overlay cap, real transparency in the first, middle
+// and last frame, and the per-clip and total caps. Returns [{ id, dir, count, fps, width, height, bytes,
+// frames }], `frames` being stage-relative paths.
+export function scanClips(stageDir, { limits = clipLimits, files = listStage(stageDir) } = {}) {
+  let totalFrames = 0;
+  let totalBytes = 0;
+  const clips = declaredClips(stageDir, limits).map((declared) => {
+    const prefix = `${clipsDir}/${declared.dir}/`;
+    if (declared.count > limits.framesPerClip) throw contract(`clip "${declared.id}": ${declared.count} frames (at most ${limits.framesPerClip} per clip)`);
+    const have = new Set(files.filter((rel) => rel.startsWith(prefix) && rasterExtensions.has(path.extname(rel).toLowerCase())).map((rel) => rel.slice(prefix.length)));
+    const frames = [];
+    for (let n = 1; n <= declared.count; n++) {
+      if (!have.has(clipFrame(n))) throw contract(`clip "${declared.id}": ${prefix}${clipFrame(n)} is missing (declared ${declared.count} frames, named frame_0001.png onward)`);
+      frames.push(`${prefix}${clipFrame(n)}`);
+    }
+    if (have.size !== declared.count) {
+      const stray = [...have].find((name) => !frames.includes(`${prefix}${name}`));
+      throw contract(`clip "${declared.id}": ${prefix}${stray} is not one of the ${declared.count} declared frames; raise count or remove it`);
+    }
+    let size = null;
+    let bytes = 0;
+    for (const rel of frames) {
+      const data = readFileSync(path.join(stageDir, rel));
+      bytes += data.length;
+      const info = path.extname(rel).toLowerCase() === ".png" && data.length > 33 ? rasterInfo(data, ".png") : null;
+      if (!info) throw contract(`clip "${declared.id}": ${rel} is not a readable PNG`);
+      if (info.animated) throw contract(`clip "${declared.id}": ${rel} is an animated image; a clip is a folder of still frames`);
+      if (info.colorType !== 6 || info.bitDepth !== 8) throw contract(`clip "${declared.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 contract(`clip "${declared.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 contract(`clip "${declared.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 };
+    }
+    if (bytes > limits.bytesPerClip) throw contract(`clip "${declared.id}": ${(bytes / 1048576).toFixed(1)} MB (at most ${(limits.bytesPerClip / 1048576).toFixed(0)} MB per clip)`);
+    for (const rel of [frames[0], frames[Math.floor((frames.length - 1) / 2)], frames.at(-1)]) {
+      let pixels;
+      try { ({ pixels } = decodePng(readFileSync(path.join(stageDir, rel)))); } catch (error) { throw contract(`clip "${declared.id}": ${rel} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`); }
+      let transparent = false;
+      for (let i = 3; i < pixels.length && !transparent; i += 4) transparent = pixels[i] < 255;
+      if (!transparent) throw contract(`clip "${declared.id}": ${rel} has no transparent pixel; a clip is keyed, not a full-frame video`);
+    }
+    totalFrames += declared.count;
+    totalBytes += bytes;
+    return { ...declared, ...size, bytes, frames };
+  });
+  if (totalFrames > limits.framesTotal) throw contract(`${totalFrames} clip frames in all (at most ${limits.framesTotal})`);
+  if (totalBytes > limits.bytesTotal) throw contract(`${(totalBytes / 1048576).toFixed(1)} MB of clip frames in all (at most ${(limits.bytesTotal / 1048576).toFixed(0)} MB)`);
+  return clips;
+}
+
+// window.LitClips for LitStage.clip: id -> { src, count, fps, width, height }, written from clips.json and
+// the first frame's header. null when the stage declares no clips (or one the scan would refuse).
+export function clipsScript(stageDir) {
+  let table;
+  try {
+    table = Object.fromEntries(declaredClips(stageDir).map((clip) => {
+      const first = path.join(stageDir, clipsDir, clip.dir, clipFrame(1));
+      const info = rasterInfo(readFileSync(first), ".png");
+      return [clip.id, { src: `${clipsDir}/${clip.dir}`, count: clip.count, fps: clip.fps, width: info.width, height: info.height }];
+    }));
+  } catch { return null; }
+  return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
+}
+
+// Throws a StageError for the first violation; returns the raster list for pre-decoding and the declared
+// clips, whose frames are not page rasters. `clips: false` (a cover page) ignores clips.json, so a clip
+// folder there is held to the raster limits.
+export function scanStage(stageDir, { clips: allowClips = true } = {}) {
   const files = listStage(stageDir);
   if (!files.includes("index.html")) throw contract("stage/index.html is missing");
+  const clips = allowClips ? scanClips(stageDir, { files }) : [];
+  const clipped = new Set(clips.flatMap((clip) => clip.frames));
   const rasters = [];
   let rasterBytes = 0;
   const plates = ["plate", "plate-preview"].map((sub) => readPlate(stageDir, sub)).filter(Boolean);
@@ -134,7 +238,7 @@ export function scanStage(stageDir) {
   for (const rel of files) {
     const ext = path.extname(rel).toLowerCase();
     const full = path.join(stageDir, rel);
-    if (rel === "scene.py" || plated.has(rel)) continue;
+    if (rel === "scene.py" || plated.has(rel) || clipped.has(rel)) continue;
     if (!Object.hasOwn(contentTypes, ext)) throw contract(`${rel}: ${ext || "extensionless"} files are not served on the stage`);
     if (rasterExtensions.has(ext)) {
       const bytes = readFileSync(full);
@@ -170,7 +274,7 @@ export function scanStage(stageDir) {
   const bySize = new Map();
   for (const raster of rasters) bySize.set(`${raster.width}x${raster.height}`, [...(bySize.get(`${raster.width}x${raster.height}`) ?? []), raster.rel]);
   for (const [size, list] of bySize) if (list.length >= rasterLimits.sameSizeFlipbook) throw contract(`${list.length} rasters share the size ${size} (a flipbook); rasters are textures and stills, never a frame sequence`);
-  return { files, rasters };
+  return { files, rasters, clips };
 }
 
 // One hash over every stage file's name and bytes: a render records it, the done check compares it.

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

@@ -227,7 +227,7 @@
   }
 
   // ---- masks and clips ----
-  const clip = {
+  const clipMasks = {
     // A circle growing from (cx, cy) in percent of the element's box.
     circle(el, p, { cx = 50, cy = 50, max = 150 } = {}) { el.style.clipPath = `circle(${clamp(p) * max}% at ${cx}% ${cy}%)`; },
     // A straight wipe from one side: "left", "right", "top" or "bottom".
@@ -370,6 +370,44 @@
     };
   }
 
+  // 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 <img> inside is replaced on a frame change; the renderer waits for its decode.
+  // The same name carries the clip-path helpers (clip.circle, clip.wipe, clip.iris), so both keep working.
+  function keyedClip({ 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, 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;
+    };
+  }
+  const clip = Object.assign(keyedClip, clipMasks);
+
   // ---- the stage contract ----
   let definition = null;
   function define(spec) {

package/skills/lit-typographic-motion/references/cover.md

@@ -33,7 +33,8 @@ mode (the stage and type paths) is unchanged and takes every other request.
   The renderer serves only that folder, the loop kit at `/lit/loop-kit.js` and the faces at
   `/lit/fonts.css`. The stage path's static scan applies unchanged: no network, no `<video>`,
   `<audio>` or `<iframe>`, no workers, no WebSocket, at most 24 rasters and 8 MB, no animated
-  raster, no flipbook of same-size frames.
+  raster, no flipbook of same-size frames; a cover takes no keyed clips either, so a folder of
+  frames there is a flipbook.
 - `<out>/assets.json`: every raster the page can load (below).
 
 Start from a recipe: copy `recipes/<name>/index.html` from the installed skill into `cover/`, then

package/skills/lit-typographic-motion/references/runtime.md

@@ -39,7 +39,7 @@ warning, and the pre-warm state naming what is missing and the command that fixe
 | 14 | BLOCKED_DEPS_NOT_PREWARMED | the pinned packages are absent (or Tier-3 models are requested) | `litopencode motion-runtime install` outside the session |
 | 15 | BLOCKED_FONT_FETCH | a required font is missing or its bytes do not match the pin | `litopencode motion-runtime install`; a mismatch is never accepted |
 | 16 | BLOCKED_TREATMENT_INVALID | `treatment.json` is missing or a field breaks its rule; the message names the field | fix that field (`treatment.md`) |
-| 17 | STAGE_CONTRACT_ERROR | the stage page broke its contract: no `LitStage.define`, a wrong size, a forbidden element or API, a flipbook or animated raster, a path outside `stage/`, or a copy line never found on screen | fix the page (`stage.md`) |
+| 17 | STAGE_CONTRACT_ERROR | the stage page broke its contract: no `LitStage.define`, a wrong size, a forbidden element or API, a flipbook or animated raster, a keyed clip that breaks its declaration or limits, a path outside `stage/`, or a copy line never found on screen | fix the page (`stage.md`) |
 | 18 | STAGE_NONDETERMINISTIC | a sample frame differs between the master and a fresh replay from 0; the message names the frame and the first region | remove the clock or random source the renderer does not drive |
 | 19 | STAGE_NETWORK_REQUEST | the page requested something outside the stage origin, or a stage file names an external URL | make the asset local |
 | 20 | SOUND_INVALID | the planned track is missing from the film, too long or short, too loud, or a generated bed starts silent; a score that cannot be built | fix the track or its plan |

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

@@ -16,7 +16,7 @@ loop time the renderer seeks in any order, with the loop kit instead of this one
   into the stage directory.
 - Rasters are textures and stills, never a frame sequence: at most 24 raster files and 8 MB in total.
   Ten or more rasters of one size (a flipbook), or any animated GIF, APNG or WebP, stops the render
-  with exit 17.
+  with exit 17. The one frame sequence a page may carry is a declared keyed clip (Clips).
 - `<out>/stage/assets/`: the real logo, screenshots and README images of a named product, written by
   `render.mjs assets` (`treatment.md`, Named products). Show them; never redraw them.
 - A film about a thing with a back and an inside takes the 3D route: the renderer serves a pinned
@@ -76,7 +76,7 @@ unless the film needs another structure.
 
 | Stops with | What |
 | --- | --- |
-| 17 `STAGE_CONTRACT_ERROR` | `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`; `new Audio()`, `AudioContext`, `OfflineAudioContext`; `Worker`, `SharedWorker`, service workers; no `LitStage.define`; a wrong size; a flipbook or animated raster; a copy line never found on screen |
+| 17 `STAGE_CONTRACT_ERROR` | `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`; `new Audio()`, `AudioContext`, `OfflineAudioContext`; `Worker`, `SharedWorker`, service workers; no `LitStage.define`; a wrong size; a flipbook or animated raster; a clip that breaks its declaration or limits; a copy line never found on screen |
 | 18 `STAGE_NONDETERMINISTIC` | a frame that differs between two fresh replays: wall-clock reads such as `performance.timeOrigin`, `crypto.getRandomValues`, or state that depends on how fast frames arrive |
 | 19 `STAGE_NETWORK_REQUEST` | any request outside the stage origin; an absolute `http(s)://` or `//host` URL in a stage file (W3C namespace URIs such as `http://www.w3.org/2000/svg` are fine); `preconnect`, `dns-prefetch`, `prefetch` or `prerender` links; `WebSocket`, `WebTransport`, `RTCPeerConnection` |
 
@@ -147,6 +147,52 @@ LitStage.text(signEl, { decor: true });                   // illustrative text i
 LitStage.text({ content: "…", x, y, w, h });              // canvas or WebGL text, every frame it is drawn
 ```
 
+Keyed footage (a declared clip, see Clips): `LitStage.clip` is a function as well as the mask
+namespace above, so `LitStage.clip.wipe(el, p)` and the keyed call live side by side.
+
+```js
+const boom = LitStage.clip({ parent: stageEl, id: "boom", box: { x: 1200, y: 300, w: 520, h: 511 } });
+boom(t, { start: 2.1 });                                   // inside render(t); returns the wrapper, or null while hidden
+```
+
+## Clips
+
+Real keyed footage (a reaction clip, a spinning-cat loop shot on a green screen) joins the film as a
+layer inside the page. The video 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. A declared clip is exempt from the
+flipbook and count rule; every other raster keeps its limits. Nothing is encoded by hand: the frames
+are captured with the page, so the flash audit, the determinism replay and the text checks run on the
+final pixels as for any other film.
+
+1. Copy each clip's frames into `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` is a folder directly under `clips/`; `count` is the number of
+   frames; `fps` is 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.clip({ parent, id, box })` and calls the returned `show(t, opts)` from `render(t)`.
+   `parent` is the element the clip sits in; `box` is its place in pixels, the frame fitted inside it.
+   `show` returns the wrapper element, or `null` while hidden; scale, fade or move that wrapper from
+   `t` like any other layer. The frame is `floor((t - start) * fps) + 1`, counted from `from`, so the
+   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), `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, more than 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), a rate above 30 fps, frames of mixed sizes, a missing or extra frame, a
+frame that is not an 8-bit RGBA PNG or that has no transparent pixel in its 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. A cover takes no
+clips. The text checks read DOM text, so a clip laid over a line is yours to catch on the stills. The
+manifest and the report list each clip.
+
 ## How the QA reads the stage
 
 - Every `copy.lines` entry must appear on screen at some beat; a missing line stops the render with