@litfamily/litgravity 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.7 — 2026-11-09
4
+
5
+ - TypeScript language-server install hints pin `typescript@6`. TypeScript 7 ships no `lib/tsserver.js`, which `typescript-language-server` loads.
6
+
7
+ ## 0.1.6 — 2026-11-01
8
+
9
+ - A film on the stage path can now carry real keyed footage. Put the chroma-keyed frames of a clip (8-bit RGBA PNG, real transparency) under `stage/clips/<dir>/`, declare them in `stage/clips/clips.json`, and the page shows them with `LitStage.clip` from film time: `start = cue - (N-1)/fps` lands a frame on a cue. The scan holds declared clips to their own limits (12 clips, 360 frames each, 1500 in all, 40 MB each, 128 MB in all, long side up to 720 px, up to 30 fps), a frame folder that is not declared is still refused as a flipbook, cover mode takes none, and the flash audit and determinism replay still run on the final pixels.
10
+
3
11
  ## 0.1.5 — 2026-10-31
4
12
 
5
13
  - The plugin now carries the official LitFamily ignition icon (`plugin/assets/logo.svg`, wired as the manifest `logo`), so `agy plugin validate --json --strict` reports zero findings instead of the no-logo note.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litfamily/litgravity",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "Installer for LitGravity: skills, hooks and agents that help Google's Antigravity CLI (agy) plan, build, check and hand off work.",
5
5
  "keywords": [
6
6
  "antigravity",
@@ -2,6 +2,6 @@
2
2
  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
3
3
  "name": "litgravity",
4
4
  "description": "LitFamily workflows for the Antigravity CLI: bare lit activation, planning, evidence-bound execution, review, research, handoff and Korean prose care.",
5
- "version": "0.1.5",
5
+ "version": "0.1.7",
6
6
  "logo": "assets/logo.svg"
7
7
  }
@@ -152,7 +152,7 @@ Stop at a blocked exit, at a gate failure you cannot fix within round 3, or when
152
152
  | 14 | BLOCKED_DEPS_NOT_PREWARMED | Run step 0, or give the user `npx @litfamily/litgravity runtime install motion` for a terminal. |
153
153
  | 15 | BLOCKED_FONT_FETCH | A cached font is missing or its sha256 differs; the same pre-warm command fixes it. |
154
154
  | 16 | BLOCKED_TREATMENT_INVALID | Fix the named field. |
155
- | 17 | STAGE_CONTRACT_ERROR | Fix the named element, API, raster, size or missing copy line. |
155
+ | 17 | STAGE_CONTRACT_ERROR | Fix the named element, API, raster, clip, size or missing copy line. |
156
156
  | 18 | STAGE_NONDETERMINISTIC | The page read something the clock does not drive; seed it or derive it from `t`. |
157
157
  | 19 | STAGE_NETWORK_REQUEST | Remove the named URL or connection; everything is local. |
158
158
  | 20 | SOUND_INVALID | The planned sound is missing, silent at the start or out of limits; fix it. |
@@ -187,7 +187,7 @@ function prepare({ out, env, log }) {
187
187
  const treatment = asBlocked(() => loadCoverTreatment(out));
188
188
  const stageDir = path.join(out, COVER_STAGE);
189
189
  if (!existsSync(path.join(stageDir, "index.html"))) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${path.join(stageDir, "index.html")} is missing; write the cover page first (references/cover.md)`);
190
- const scan = scanStage(stageDir);
190
+ const scan = scanStage(stageDir, { clips: false });
191
191
  for (const w of scan.warnings) log(`warning: ${w}`);
192
192
  const { assets } = checkAssets({ out, treatment, rasters: scan.rasters, coverDir: COVER_STAGE });
193
193
  return { treatment, stageDir, assets, faces: stageFonts(env) };
@@ -160,6 +160,7 @@ export function formatStageReport({ gate, manifest, outputs, round, framesViewed
160
160
  `outputs: ${outputs.film} · ${outputs.preview} · ${outputs.poster} · ${outputs.still}${withheld ? " [WITHHELD: MO-C-03 flash audit failed; exports are diagnostics in withheld/, not deliverables]" : ""}`,
161
161
  `format / duration / fps: ${manifest.format} ${manifest.width}x${manifest.height}, ${manifest.durationSec} s (treatment ${manifest.treatmentDurationSec} s) @ ${manifest.fps} fps, ${manifest.frameCount} frames`,
162
162
  `renderer: ${manifest.renderer} (${manifest.rung ?? "software"} rung, stage flags: ${manifest.chromeFlags.join(" ")})`,
163
+ ...(manifest.clips?.length ? [`clips: ${manifest.clips.map((c) => `${c.id} ${c.frames} frames at ${c.fps} fps`).join(", ")} (keyed overlays, chosen from film time)`] : []),
163
164
  ...(manifest.plate ? [`plate: Blender ${manifest.plate.blender}, ${manifest.plate.engine} ${manifest.plate.device}, ${manifest.plate.samples} spp, ${manifest.plate.frames} frames at ${manifest.plate.fps} fps`] : []),
164
165
  `sound: ${manifest.sound?.mode ?? "none"}${manifest.sound?.label ? ` (${manifest.sound.label})` : ""}`,
165
166
  "",
@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
9
9
  import { EXIT } from "../core/constants.mjs";
10
10
  import { readPlate } from "./blender.mjs";
11
11
  import { BlockedError } from "./chrome.mjs";
12
+ import { decodePng } from "./png.mjs";
12
13
  import { checkFont, fontLocation, fontsDir, loadFontManifest } from "./runtime.mjs";
13
14
 
14
15
  export const STAGE_ORIGIN = "http://lit.stage";
@@ -28,6 +29,13 @@ export const CONTENT_TYPES = Object.freeze({
28
29
  });
29
30
  export const RASTER = Object.freeze([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
30
31
  export const RASTER_LIMITS = Object.freeze({ count: 24, bytes: 8 * 1024 * 1024, flipbook: 10 });
32
+ // Keyed overlay clips (references/stage.md, Clips). A frame folder that stage/clips/clips.json declares is
33
+ // held to these caps instead of RASTER_LIMITS: a clip is a sticker on the film, never the film itself.
34
+ // Frames are 8-bit RGBA PNGs with real transparency, at most `side` px on the long side, at most `fps` per second.
35
+ export const CLIP_LIMITS = Object.freeze({
36
+ clips: 12, framesPerClip: 360, framesTotal: 1500, bytesPerClip: 40 * 1024 * 1024, bytesTotal: 128 * 1024 * 1024, side: 720, fps: 30,
37
+ });
38
+ export const CLIPS_DIR = "clips";
31
39
 
32
40
  // The product's verified faces as CSS families. Archivo's widths are one family at three stretches.
33
41
  const FAMILIES = [
@@ -107,7 +115,7 @@ function pngInfo(b) {
107
115
  if (type === "IDAT" || type === "IEND") break;
108
116
  o += 12 + len;
109
117
  }
110
- return { width: b.readUInt32BE(16), height: b.readUInt32BE(20), animated };
118
+ return { width: b.readUInt32BE(16), height: b.readUInt32BE(20), animated, bitDepth: b[24], colorType: b[25] };
111
119
  }
112
120
  function jpegInfo(b) {
113
121
  if (b[0] !== 0xff || b[1] !== 0xd8) return null;
@@ -165,6 +173,97 @@ export function rasterInfo(file) {
165
173
  return null;
166
174
  }
167
175
 
176
+ // ---- declared clips: stage/clips/clips.json and the frame folders it names ----
177
+ const clipFail = (message) => new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${message}`);
178
+ const clipFrame = (i) => `frame_${String(i).padStart(4, "0")}.png`;
179
+ const CLIP_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/u;
180
+ const CLIP_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u;
181
+
182
+ /** The clips stage/clips/clips.json declares ([] without the file), checked for shape only. Throws exit 17. */
183
+ export function declaredClips(stageDir, limits = CLIP_LIMITS) {
184
+ const file = path.join(stageDir, CLIPS_DIR, "clips.json");
185
+ if (!existsSync(file)) return [];
186
+ let doc;
187
+ try {
188
+ doc = JSON.parse(readFileSync(file, "utf8"));
189
+ } catch (error) {
190
+ throw clipFail(`${CLIPS_DIR}/clips.json is not valid JSON (${error.message})`);
191
+ }
192
+ if (!doc || !Array.isArray(doc.clips)) throw clipFail(`${CLIPS_DIR}/clips.json needs { "clips": [ { "id", "dir", "count", "fps" } ] }`);
193
+ if (doc.clips.length > limits.clips) throw clipFail(`${doc.clips.length} clips declared (at most ${limits.clips} clips)`);
194
+ const ids = new Set();
195
+ const dirs = new Set();
196
+ return doc.clips.map((c, n) => {
197
+ const at = `${CLIPS_DIR}/clips.json clip #${n + 1}`;
198
+ if (!c || typeof c !== "object") throw clipFail(`${at} is not an object`);
199
+ if (typeof c.id !== "string" || !CLIP_ID.test(c.id)) throw clipFail(`${at}: id must be a plain token of letters, digits, - and _ (got ${JSON.stringify(c.id)})`);
200
+ if (ids.has(c.id)) throw clipFail(`${at}: duplicate id ${c.id}`);
201
+ ids.add(c.id);
202
+ if (typeof c.dir !== "string" || !CLIP_DIR.test(c.dir) || c.dir.includes("..")) throw clipFail(`clip "${c.id}": dir must be a folder name directly under ${CLIPS_DIR}/ (got ${JSON.stringify(c.dir)})`);
203
+ if (dirs.has(c.dir)) throw clipFail(`clip "${c.id}": dir ${c.dir} is already declared by another clip`);
204
+ dirs.add(c.dir);
205
+ if (!Number.isInteger(c.count) || c.count < 1) throw clipFail(`clip "${c.id}": count must be a whole number of frames (got ${JSON.stringify(c.count)})`);
206
+ if (!Number.isInteger(c.fps) || c.fps < 1 || c.fps > limits.fps) throw clipFail(`clip "${c.id}": fps must be a whole number from 1 to ${limits.fps} (got ${JSON.stringify(c.fps)})`);
207
+ return { id: c.id, dir: c.dir, count: c.count, fps: c.fps };
208
+ });
209
+ }
210
+
211
+ /**
212
+ * Check every declared clip against its bytes: exactly frame_0001.png..frame_<count>.png in clips/<dir>/,
213
+ * each a non-animated 8-bit RGBA PNG of one size inside the overlay cap, real transparency in the first,
214
+ * middle and last frame, and the per-clip and total caps. Returns [{ id, dir, count, fps, width, height,
215
+ * bytes, frames }] where `frames` are stage-relative paths. Throws exit 17 naming the clip.
216
+ */
217
+ export function scanClips(stageDir, { limits = CLIP_LIMITS, files = listStage(stageDir) } = {}) {
218
+ const decls = declaredClips(stageDir, limits);
219
+ let totalFrames = 0;
220
+ let totalBytes = 0;
221
+ const clips = decls.map((d) => {
222
+ const prefix = `${CLIPS_DIR}${path.sep}${d.dir}${path.sep}`;
223
+ if (d.count > limits.framesPerClip) throw clipFail(`clip "${d.id}": ${d.count} frames (at most ${limits.framesPerClip} per clip)`);
224
+ const have = new Map(files.filter((f) => f.rel.startsWith(prefix) && RASTER.includes(path.extname(f.rel).toLowerCase())).map((f) => [f.rel.slice(prefix.length), f]));
225
+ const frames = [];
226
+ for (let i = 1; i <= d.count; i++) {
227
+ const f = have.get(clipFrame(i));
228
+ if (!f) throw clipFail(`clip "${d.id}": ${CLIPS_DIR}/${d.dir}/${clipFrame(i)} is missing (declared ${d.count} frames, named frame_0001.png onward)`);
229
+ frames.push(f);
230
+ }
231
+ if (have.size !== d.count) {
232
+ const stray = [...have.keys()].find((name) => !frames.some((f) => f.rel.endsWith(`${path.sep}${name}`)));
233
+ throw clipFail(`clip "${d.id}": ${CLIPS_DIR}/${d.dir}/${stray} is not one of the ${d.count} declared frames; raise count or remove it`);
234
+ }
235
+ let size = null;
236
+ for (const f of frames) {
237
+ const info = rasterInfo(f.real);
238
+ if (path.extname(f.rel).toLowerCase() !== ".png" || !info) throw clipFail(`clip "${d.id}": ${f.rel} is not a readable PNG`);
239
+ if (info.animated) throw clipFail(`clip "${d.id}": ${f.rel} is an animated image; a clip is a folder of still frames`);
240
+ if (info.colorType !== 6 || info.bitDepth !== 8) throw clipFail(`clip "${d.id}": ${f.rel} must be an 8-bit RGBA PNG with an alpha channel (a keyed frame), not an opaque image`);
241
+ if (Math.max(info.width, info.height) > limits.side) throw clipFail(`clip "${d.id}": ${f.rel} is ${info.width}x${info.height}; a clip is an overlay of at most ${limits.side} px on the long side`);
242
+ if (size && (size.width !== info.width || size.height !== info.height)) throw clipFail(`clip "${d.id}": ${f.rel} is ${info.width}x${info.height} but frame_0001.png is ${size.width}x${size.height}; one size per clip`);
243
+ size = { width: info.width, height: info.height };
244
+ }
245
+ const bytes = frames.reduce((s, f) => s + f.bytes, 0);
246
+ if (bytes > limits.bytesPerClip) throw clipFail(`clip "${d.id}": ${(bytes / 1048576).toFixed(1)} MB (at most ${(limits.bytesPerClip / 1048576).toFixed(0)} MB per clip)`);
247
+ for (const f of [frames[0], frames[Math.floor((frames.length - 1) / 2)], frames[frames.length - 1]]) {
248
+ let pixels;
249
+ try {
250
+ ({ pixels } = decodePng(readFileSync(f.real)));
251
+ } catch (error) {
252
+ throw clipFail(`clip "${d.id}": ${f.rel} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`);
253
+ }
254
+ let keyed = false;
255
+ for (let i = 3; i < pixels.length && !keyed; i += 4) keyed = pixels[i] < 255;
256
+ if (!keyed) throw clipFail(`clip "${d.id}": ${f.rel} has no transparent pixel; a clip is keyed, not a full-frame video`);
257
+ }
258
+ totalFrames += d.count;
259
+ totalBytes += bytes;
260
+ return { ...d, ...size, bytes, frames: frames.map((f) => f.rel) };
261
+ });
262
+ if (totalFrames > limits.framesTotal) throw clipFail(`${totalFrames} clip frames in all (at most ${limits.framesTotal})`);
263
+ if (totalBytes > limits.bytesTotal) throw clipFail(`${(totalBytes / 1048576).toFixed(1)} MB of clip frames in all (at most ${(limits.bytesTotal / 1048576).toFixed(0)} MB)`);
264
+ return clips;
265
+ }
266
+
168
267
  // ---- the static pre-flight scan ----
169
268
  const TEXT = new Set([".html", ".js", ".mjs", ".css", ".svg", ".json"]);
170
269
  const NAMESPACES = /^http:\/\/www\.w3\.org\/(?:2000\/svg|1999\/xlink|1999\/xhtml|XML\/1998\/namespace|2000\/xmlns\/?)$/u;
@@ -183,9 +282,11 @@ const NETWORK_API = /\bnew\s+(WebSocket|WebTransport|RTCPeerConnection|EventSour
183
282
 
184
283
  /**
185
284
  * Scan the stage dir before launch. Throws exit 17 (contract) or 19 (network) naming the file and
186
- * the thing found; returns { files, rasters, warnings, plate } otherwise (plate: the Blender plate, or null).
285
+ * the thing found; returns { files, rasters, warnings, plate, clips } otherwise (plate: the Blender plate, or
286
+ * null; clips: the declared keyed clips, checked by scanClips, whose frames are not page rasters).
287
+ * `clips: false` (cover mode) ignores clips.json, so a declared folder is held to the raster limits.
187
288
  */
188
- export function scanStage(stageDir) {
289
+ export function scanStage(stageDir, { clips: allowClips = true } = {}) {
189
290
  if (!existsSync(path.join(stageDir, "index.html"))) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${path.join(stageDir, "index.html")} is missing; write the stage page first (references/stage.md)`);
190
291
  const files = listStage(stageDir);
191
292
  const warnings = [];
@@ -195,6 +296,8 @@ export function scanStage(stageDir) {
195
296
  const plate = readPlate(stageDir, "plate");
196
297
  const preview = readPlate(stageDir, "plate-preview");
197
298
  const listed = new Set([plate, preview].filter(Boolean).flatMap((p) => p.frames.map((f) => path.join(p.dir, f.name))));
299
+ const clips = allowClips ? scanClips(stageDir, { files }) : [];
300
+ for (const c of clips) for (const rel of c.frames) listed.add(rel);
198
301
  for (const f of files) {
199
302
  const ext = path.extname(f.rel).toLowerCase();
200
303
  if (!CONTENT_TYPES[ext] && f.rel !== "scene.py") warnings.push(`${f.rel}: not a servable type; the page cannot load it`);
@@ -234,7 +337,24 @@ export function scanStage(stageDir) {
234
337
  for (const [size, names] of bySize) {
235
338
  if (names.length >= RASTER_LIMITS.flipbook) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${names.length} rasters of ${size} look like a flipbook; animate the page, not a frame sequence`);
236
339
  }
237
- return { files, rasters, warnings, plate };
340
+ return { files, rasters, warnings, plate, clips };
341
+ }
342
+
343
+ /**
344
+ * window.LitClips for LitStage.clip: id -> { src, count, fps, width, height }, written from clips.json and the
345
+ * first frame's header. null when the stage declares no clips (or one the scan would refuse).
346
+ */
347
+ function clipsScript(stageDir) {
348
+ let table;
349
+ try {
350
+ table = Object.fromEntries(declaredClips(stageDir).map((c) => {
351
+ const info = rasterInfo(path.join(stageDir, CLIPS_DIR, c.dir, clipFrame(1)));
352
+ return [c.id, { src: `${CLIPS_DIR}/${c.dir}`, count: c.count, fps: c.fps, width: info.width, height: info.height }];
353
+ }));
354
+ } catch {
355
+ return null;
356
+ }
357
+ return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
238
358
  }
239
359
 
240
360
  /**
@@ -242,6 +362,7 @@ export function scanStage(stageDir) {
242
362
  * type } | { kind: "blocked", reason } | { kind: "missing" }, and records every refusal.
243
363
  */
244
364
  export function stageRouter({ stageDir, faces, style = null }) {
365
+ const clipsJs = clipsScript(stageDir);
245
366
  const root = realpathSync(stageDir);
246
367
  const css = fontsCss(faces);
247
368
  const byRoute = new Map(faces.map((f) => [f.route, f.file]));
@@ -265,6 +386,7 @@ export function stageRouter({ stageDir, faces, style = null }) {
265
386
  if (pathname === "/lit/stage-kit.js") return { kind: "file", file: KIT_FILE, type: CONTENT_TYPES[".js"] };
266
387
  if (pathname === "/lit/loop-kit.js") return { kind: "file", file: LOOP_KIT_FILE, type: CONTENT_TYPES[".js"] };
267
388
  if (pathname === "/lit/fonts.css") return { kind: "body", body: css, type: CONTENT_TYPES[".css"] };
389
+ if (clipsJs && pathname === "/lit/clips.js") return { kind: "body", body: clipsJs, type: CONTENT_TYPES[".js"] };
268
390
  if (pathname.startsWith("/lit/three/")) {
269
391
  const rel = pathname.slice("/lit/three/".length);
270
392
  const file = path.join(THREE_DIR, rel);
@@ -480,6 +480,7 @@ export async function renderStage({ out, round = 1, stillsOnly = false, env = pr
480
480
  frameCount, seed: treatment.seed, renderer: finalState.webglRenderer ?? "no WebGL", rung: ctx.rung, chromeFlags: master.flags, usesWebGL: finalState.usesWebGL,
481
481
  cuts, stills: { sha256: stills.sha256, poster: plan.poster, reduced: plan.reduced }, posterEncoding: poster,
482
482
  geometry: geometryFor(width, height),
483
+ clips: scan.clips.map((c) => ({ id: c.id, frames: c.count, fps: c.fps, width: c.width, height: c.height, bytes: c.bytes })),
483
484
  plate: scan.plate ? { blender: scan.plate.blender, engine: scan.plate.engine, device: scan.plate.device, samples: scan.plate.samples, fps: scan.plate.fps, frames: scan.plate.frames.length } : null,
484
485
  sound: { mode: sound.mode, label: sound.label, file: sound.file ? path.relative(out, sound.file) : null, sha256: sound.file ? sha256(readFileSync(sound.file)) : null, lufs: sound.bed?.lufs ?? null },
485
486
  preview: { encoder: preview.encoder, rung: preview.rung, attempts: preview.attempts },
@@ -759,6 +759,45 @@
759
759
  };
760
760
  }
761
761
 
762
+ // A declared keyed clip (stage/clips/clips.json, served as window.LitClips by /lit/clips.js): one wrapper
763
+ // at `box` over the film holding the clip's frame for t. The frame is a pure function of film time,
764
+ // floor((t - start) * fps) + 1 within from..to, so no <video> and no real clock is involved. Before
765
+ // `start` and after `to` the wrapper is hidden and show returns null, unless `hold` keeps the last frame
766
+ // or `loop` wraps by frame index. The <img> inside is replaced on a frame change, so the renderer waits
767
+ // for its decode before the capture. Returns show(t, { start, from, to, loop, hold }); call it from render(t).
768
+ function clip({ parent, id, box } = {}) {
769
+ const all = root.LitClips;
770
+ 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)');
771
+ const c = all[id];
772
+ if (!c) throw new Error(`LitStage.clip: no clip "${id}" in clips/clips.json (declared: ${Object.keys(all).join(", ")})`);
773
+ if (!parent || !box || !(box.w > 0) || !(box.h > 0)) throw new Error("LitStage.clip: needs { parent, id, box: { x, y, w, h } }");
774
+ const wrap = document.createElement("div");
775
+ wrap.setAttribute("data-lit-clip", id);
776
+ 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" });
777
+ parent.append(wrap);
778
+ let shown = 0;
779
+ let img = null;
780
+ return (t, { start = 0, from = 1, to = c.count, loop = false, hold = false } = {}) => {
781
+ if (!(from >= 1 && to <= c.count && from <= to)) throw new Error(`LitStage.clip: from..to must lie within 1..${c.count} (got ${from}..${to})`);
782
+ const n = to - from + 1;
783
+ const k = Math.floor((t - start) * c.fps + 1e-6);
784
+ const i = k < 0 ? 0 : k < n ? from + k : loop ? from + (k % n) : hold ? to : 0;
785
+ wrap.style.display = i ? "block" : "none";
786
+ if (!i) return null;
787
+ if (i !== shown) {
788
+ const next = document.createElement("img");
789
+ next.src = `${c.src}/frame_${String(i).padStart(4, "0")}.png`;
790
+ next.alt = "";
791
+ Object.assign(next.style, { display: "block", width: "100%", height: "100%", objectFit: "contain" });
792
+ if (img) img.replaceWith(next);
793
+ else wrap.append(next);
794
+ img = next;
795
+ shown = i;
796
+ }
797
+ return wrap;
798
+ };
799
+ }
800
+
762
801
  // ---- the page contract ----
763
802
  const FORMATS = [[1920, 1080], [1080, 1920]];
764
803
  function define(spec) {
@@ -779,6 +818,6 @@
779
818
  clipRect, clipCircle, maskLinear, wipe,
780
819
  mix, rgba,
781
820
  clamp, lerp, invLerp, remap, smoothstep,
782
- shot, zone, place, tokens, plate,
821
+ shot, zone, place, tokens, plate, clip,
783
822
  });
784
823
  })(typeof window !== "undefined" ? window : globalThis);
@@ -12,7 +12,8 @@ Start every page from `motion.mjs scaffold --out <dir>`, which writes the struct
12
12
  SVG, PNG, JPG, WebP, JS, CSS and WAV files beside it. Nothing else is served.
13
13
  - The page loads the fonts, the style and the kit from the renderer's own routes:
14
14
  `<link rel="stylesheet" href="/lit/fonts.css">`, `<link rel="stylesheet" href="/lit/style.css">`,
15
- `<script src="/lit/style.js"></script>` and `<script src="/lit/stage-kit.js"></script>`.
15
+ `<script src="/lit/style.js"></script>` and `<script src="/lit/stage-kit.js"></script>`; a page that
16
+ uses clips adds `<script src="/lit/clips.js"></script>` after the kit (Clips).
16
17
  - Each shot's copy sits in its layout's type zone, in a type-role class and a colour class of the style;
17
18
  the gate's style rules check the result (`studio.md`).
18
19
  - The page calls `LitStage.define({ width, height, fps, duration, render })`, or sets
@@ -95,6 +96,8 @@ Every primitive is a pure function of its inputs. `LitStage` holds them all.
95
96
  - The style and the timeline (`studio.md`): `shot(t)` (the shot at `t`, with `p`, `local`,
96
97
  `enter(delay, dur)`, `exit(dur)`), `zone(layout, part)` and `place(el, layout, part)` (a layout zone in
97
98
  pixels), `tokens()` (the style's eases, durations, staggers and springs per object class).
99
+ - `clip({ parent, id, box })` registers a declared keyed clip once (Clips) and returns `show(t, opts)`:
100
+ `const boom = clip({ parent, id: "boom", box: { x: 1200, y: 300, w: 520, h: 511 } }); boom(t, { start: 2.1 });`.
98
101
 
99
102
  ## Fonts
100
103
 
@@ -115,6 +118,45 @@ Any other family falls back to a system face. The QA replay reports that, and fa
115
118
  text. Set Korean copy in Pretendard. Never ask for a weight the family does not have (the browser
116
119
  would synthesize a fake bold), and never animate tracking or width on Hangul.
117
120
 
121
+ ## Clips
122
+
123
+ Real keyed footage (a reaction clip, a spinning-cat loop shot on a green screen) joins the film as a
124
+ layer inside the page. Key the video outside the renderer into one 8-bit RGBA PNG per frame, declare the
125
+ frames, and the page picks the frame from film time. A declared clip is exempt from the flipbook and
126
+ count rule; every other raster keeps its limits. Nothing is encoded by hand: the clip frames are
127
+ captured with the page, so the flash audit, the determinism replay and the text checks run on the final
128
+ pixels like any other film.
129
+
130
+ 1. Copy each clip's frames into the run's stage folder as `stage/clips/<dir>/frame_0001.png`,
131
+ `frame_0002.png` and on, with no gaps and no other image in that folder.
132
+ 2. Declare them in `stage/clips/clips.json`:
133
+
134
+ ```json
135
+ { "clips": [ { "id": "boom", "dir": "01-vine-boom", "count": 122, "fps": 30 } ] }
136
+ ```
137
+
138
+ `id` is the name the page uses; `dir` is a folder directly under `clips/`; `count` is the number of
139
+ frames; `fps` is the clip's own rate, 1 to 30. A clip used twice is declared once.
140
+ 3. The page loads `<script src="/lit/clips.js"></script>` after the kit, registers each use once with
141
+ `LitStage.clip({ parent, id, box })`, and calls the returned `show(t, opts)` from `render(t)`.
142
+ `parent` is the element the clip sits in; `box` is its place in pixels, the frame fitted inside it.
143
+ `show` returns the clip's wrapper element, or `null` while hidden; scale, fade or move the wrapper
144
+ from `t` like any other layer. The frame is `floor((t - start) * fps) + 1`, counted from `from`, so
145
+ a cue is plain arithmetic: `start = cue - (N - 1) / fps`, where N is the frame whose own sound or
146
+ action must land on the cue (a clip whose sound starts at frame 85 and must land at 0.12 s has
147
+ `start = 0.12 - 84 / 30`). Options: `start` (film seconds, default 0), `from` and `to` (the frame
148
+ range, default the whole clip), `loop` (wrap by frame index) and `hold` (keep the last frame).
149
+ Before `start`, and past `to` without `loop` or `hold`, the clip is hidden.
150
+
151
+ The scan refuses, with exit 17 and the clip named: more than 12 clips, more than 360 frames in a clip or
152
+ 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
153
+ is an overlay, not the film), a frame rate above 30, frames of mixed sizes, a missing or extra frame, a
154
+ frame that is not an 8-bit RGBA PNG or that has no transparent pixel in the first, middle and last frame
155
+ (an opaque video is not keyed), an animated image, and a duplicate `id`. A folder that is not declared,
156
+ or any frame sequence beside a declared clip, is a flipbook as before. Cover mode takes no clips. Keep a
157
+ clip clear of copy: the text checks read DOM text, so a clip laid over a line is yours to catch on the
158
+ stills. The manifest and the report list each clip.
159
+
118
160
  ## Clock
119
161
 
120
162
  The renderer owns time. It steps a virtual clock frame by frame from 0 and captures the frames in
@@ -143,7 +185,7 @@ region. For variation, use `LitStage.rand(<seed>)`.
143
185
  CDN.
144
186
  - Rasters: at most 24 raster images and 8 MB in total. Ten or more rasters of the same size (a
145
187
  flipbook), or any animated GIF, APNG or WebP, is exit 17. Rasters are textures and stills, never a
146
- frame sequence.
188
+ frame sequence. The one frame sequence a page may carry is a declared keyed clip (Clips).
147
189
  - Hand-encoded films are not the deliverable: no frame loop encoded by hand, no screen recording,
148
190
  no raster flipbook. Every frame passes through the renderer.
149
191
 
@@ -156,7 +156,7 @@ These are the commands the references expand on. Treat them as candidates and le
156
156
 
157
157
  | Tool | macOS | Linux | Windows |
158
158
  | --- | --- | --- | --- |
159
- | TypeScript checker and server | `npm i -D typescript typescript-language-server` | same | same |
159
+ | TypeScript checker and server | `npm i -D typescript@6 typescript-language-server` | same | same |
160
160
  | `basedpyright` | `uv tool install basedpyright` or `brew install basedpyright` | `uv tool install basedpyright` or `pipx install basedpyright` | `uv tool install basedpyright` |
161
161
  | `ruff` | `brew install ruff` or `uv tool install ruff` | `uv tool install ruff` or `pipx install ruff` | `uv tool install ruff` |
162
162
  | `gopls` | `go install golang.org/x/tools/gopls@latest` or `brew install gopls` | `go install golang.org/x/tools/gopls@latest` | `go install golang.org/x/tools/gopls@latest` |
@@ -19,22 +19,24 @@ agy has no language-server tool and a plugin cannot register one, so this refere
19
19
 
20
20
  ## Install (the user runs these)
21
21
 
22
+ Pin `typescript@6`: TypeScript 7 ships no `lib/tsserver.js`, which `typescript-language-server` loads.
23
+
22
24
  **macOS**
23
25
 
24
- - project-local (preferred): `npm install --save-dev typescript typescript-language-server`
25
- - global: `npm install -g typescript typescript-language-server`
26
- - Homebrew alternative for the wrapper: `brew install typescript-language-server` (it still needs a `typescript` package)
26
+ - project-local (preferred): `npm install --save-dev typescript@6 typescript-language-server`
27
+ - global: `npm install -g typescript@6 typescript-language-server`
28
+ - Homebrew alternative for the wrapper: `brew install typescript-language-server` (it still needs a `typescript@6` package alongside it)
27
29
 
28
30
  **Linux**
29
31
 
30
- - project-local (preferred): `npm install --save-dev typescript typescript-language-server`
31
- - global: `npm install -g typescript typescript-language-server`; with a system Node a prefix such as `npm config set prefix ~/.local` avoids `sudo`
32
- - other package managers: `pnpm add -D typescript typescript-language-server`, `yarn add -D ...`, `bun add -d ...`
32
+ - project-local (preferred): `npm install --save-dev typescript@6 typescript-language-server`
33
+ - global: `npm install -g typescript@6 typescript-language-server`; with a system Node a prefix such as `npm config set prefix ~/.local` avoids `sudo`
34
+ - other package managers: `pnpm add -D typescript@6 typescript-language-server`, `yarn add -D ...`, `bun add -d ...`
33
35
 
34
36
  **Windows**
35
37
 
36
- - project-local (preferred): `npm install --save-dev typescript typescript-language-server`
37
- - global: `npm install -g typescript typescript-language-server`; the binaries land in `%AppData%\npm`, which must be on PATH
38
+ - project-local (preferred): `npm install --save-dev typescript@6 typescript-language-server`
39
+ - global: `npm install -g typescript@6 typescript-language-server`; the binaries land in `%AppData%\npm`, which must be on PATH
38
40
  - install Node first with `winget install OpenJS.NodeJS.LTS` when it is missing
39
41
 
40
42
  Confirm afterwards:
@@ -17,9 +17,9 @@ export const LANGUAGES = [
17
17
  checkers: ['tsc', 'eslint'], wired: true, buildCheck: 'npx tsc --noEmit -p tsconfig.json',
18
18
  projectFiles: ['tsconfig.json', 'jsconfig.json', 'package.json'],
19
19
  install: {
20
- darwin: 'npm install --save-dev typescript typescript-language-server (or: brew install typescript-language-server)',
21
- linux: 'npm install --save-dev typescript typescript-language-server',
22
- win32: 'npm install --save-dev typescript typescript-language-server',
20
+ darwin: 'npm install --save-dev typescript@6 typescript-language-server (or: brew install typescript-language-server)',
21
+ linux: 'npm install --save-dev typescript@6 typescript-language-server',
22
+ win32: 'npm install --save-dev typescript@6 typescript-language-server',
23
23
  } },
24
24
  { language: 'python', serverId: 'basedpyright', command: ['basedpyright-langserver', '--stdio'],
25
25
  extensions: ['.py', '.pyi'], checkers: ['pyright', 'basedpyright', 'ruff', 'mypy'], wired: true,