@litfamily/litopencode 1.0.7 → 1.0.9

package/skills/lit-typographic-motion/package-lock.json

@@ -0,0 +1,78 @@
+{
+  "name": "litopencode-motion-runtime",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "litopencode-motion-runtime",
+      "version": "1.0.0",
+      "dependencies": {
+        "opentype.js": "1.3.4",
+        "playwright-core": "1.55.1",
+        "ws": "8.18.3"
+      }
+    },
+    "node_modules/opentype.js": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/opentype.js/-/opentype.js-1.3.4.tgz",
+      "integrity": "sha512-d2JE9RP/6uagpQAVtJoF0pJJA/fgai89Cc50Yp0EJHk+eLp6QQ7gBoblsnubRULNY132I0J1QKMJ+JTbMqz4sw==",
+      "license": "MIT",
+      "dependencies": {
+        "string.prototype.codepointat": "^0.2.1",
+        "tiny-inflate": "^1.0.3"
+      },
+      "bin": {
+        "ot": "bin/ot"
+      },
+      "engines": {
+        "node": ">= 8.0.0"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.55.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.55.1.tgz",
+      "integrity": "sha512-Z6Mh9mkwX+zxSlHqdr5AOcJnfp+xUWLCt9uKV18fhzA8eyxUd8NUWzAjxUh55RZKSYwDGX0cfaySdhZJGMoJ+w==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/string.prototype.codepointat": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/string.prototype.codepointat/-/string.prototype.codepointat-0.2.1.tgz",
+      "integrity": "sha512-2cBVCj6I4IOvEnjgO/hWqXjqBGsY+zwPmHl12Srk9IXSZ56Jwwmy+66XO5Iut/oQVR7t5ihYdLB0GMa4alEUcg==",
+      "license": "MIT"
+    },
+    "node_modules/tiny-inflate": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
+      "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==",
+      "license": "MIT"
+    },
+    "node_modules/ws": {
+      "version": "8.18.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.3.tgz",
+      "integrity": "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

package/skills/lit-typographic-motion/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "litopencode-motion-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "opentype.js": "1.3.4",
+    "playwright-core": "1.55.1",
+    "ws": "8.18.3"
+  }
+}

package/skills/lit-typographic-motion/probe.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// The five MO-A-44 probes, reported on every doctor/status run: Chrome, ffmpeg (with the preview
+// encoder rung), the WebGL2 renderer string from a real headless probe, the software-GL warning, and
+// pre-warm state naming what is missing and the command that fixes it.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isSoftwareRenderer, unknownRenderer } from "./engine/constants.mjs";
+import { chromeVersion, findChrome, launchLadder, loadPlaywright, which } from "./engine/browser.mjs";
+import { inspectWarmState } from "./runtime.mjs";
+
+export function previewEncoderRung(ffmpeg, env = process.env) {
+  if (ffmpeg) {
+    const encoders = spawnSync(ffmpeg, ["-hide_banner", "-encoders"], { encoding: "utf8", timeout: 15000 }).stdout ?? "";
+    if (/\blibwebp_anim\b/u.test(encoders)) return "libwebp_anim";
+  }
+  if (which("img2webp", env)) return "img2webp";
+  return ffmpeg ? "gif" : "none";
+}
+
+export async function probe(env = process.env) {
+  const prewarm = inspectWarmState(env);
+  const chrome = findChrome(env);
+  const ffmpeg = which("ffmpeg", env);
+  const report = {
+    chrome: chrome.path ? { ok: true, path: chrome.path, version: chromeVersion(chrome.path) } : { ok: false, detail: `${chrome.missing} (not found on PATH / not installed)` },
+    ffmpeg: ffmpeg ? { ok: true, path: ffmpeg, version: (spawnSync(ffmpeg, ["-version"], { encoding: "utf8", timeout: 15000 }).stdout ?? "").split("\n")[0], previewEncoder: previewEncoderRung(ffmpeg, env) }
+      : { ok: false, detail: "ffmpeg not found on PATH", previewEncoder: previewEncoderRung(undefined, env) },
+    webgl2: { ok: false, renderer: null, flags: [], detail: "" },
+    softwareWarning: null,
+    prewarm
+  };
+  if (!chrome.path) report.webgl2.detail = "not probed: Chrome is missing";
+  else if (prewarm.deps.length) report.webgl2.detail = `not probed: the pinned driver is not pre-warmed; run ${prewarm.fix}`;
+  else {
+    const scratch = mkdtempSync(path.join(os.tmpdir(), "ltm-probe-"));
+    try {
+      const chromium = await loadPlaywright(prewarm.nodeDir);
+      const launched = await launchLadder(chromium, chrome.path, scratch, { timeout: 20000 });
+      report.webgl2 = { ok: true, renderer: launched.renderer, flags: launched.rung.flags, rung: launched.rung.name };
+      await launched.context.close();
+    } catch (error) {
+      report.webgl2.detail = `no WebGL2 context obtainable (not even software): ${error.message}`;
+    } finally {
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+  const renderer = report.webgl2.renderer;
+  report.softwareWarning = !renderer ? `renderer not probed (${report.webgl2.detail})`
+    : renderer === unknownRenderer ? "renderer type unknown — debug-info extension unavailable"
+    : isSoftwareRenderer(renderer) ? `software GL detected (${renderer}); renders will be slower, --samples lowered automatically`
+    : "none (hardware renderer)";
+  return report;
+}
+
+export function formatProbe(report) {
+  const p = report.prewarm;
+  const missing = [...p.deps, ...p.missingFonts, ...p.mismatchedFonts.map((name) => `${name} (hash mismatch)`)];
+  return [
+    `motion chrome: ${report.chrome.ok ? `${report.chrome.path} — ${report.chrome.version}` : report.chrome.detail}`,
+    `motion ffmpeg: ${report.ffmpeg.ok ? `${report.ffmpeg.path} — ${report.ffmpeg.version}` : report.ffmpeg.detail}; preview encoder rung: ${report.ffmpeg.previewEncoder}`,
+    `motion webgl2: ${report.webgl2.ok ? `${report.webgl2.renderer} (rung ${report.webgl2.rung}: ${report.webgl2.flags.join(" ")})` : report.webgl2.detail}`,
+    `motion software-gl: ${report.softwareWarning}`,
+    `motion prewarm: ${p.ready ? `ready in ${p.cache} (Hangul body: ${p.hangul})` : `missing ${missing.join(", ")}; run ${p.fix}`}; audio: ${p.audio.ready ? "ready" : p.audio.reason}; word timing: ${p.wordTiming.reason}`
+  ].join("\n");
+}
+
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  const json = process.argv.includes("--json");
+  if (process.argv.includes("--help")) console.log("lit-typographic-motion probe\nUsage: node probe.mjs [--json]");
+  else probe().then((report) => console.log(json ? JSON.stringify(report, null, 2) : formatProbe(report)));
+}

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

@@ -0,0 +1,110 @@
+# Authoring: brief schema and the scene/engine contract
+
+## The brief (`motion-brief.json`)
+
+On the type path the brief lays out the scenes; it comes after the treatment (`treatment.md`), which
+fixes the copy, the length, the sound and the beats. Everything else is derived from the two files,
+deterministically.
+
+```json
+{
+  "title": "<the film's own name, printed only when it is also a copy line>",
+  "description": "<one line about the film, used for the preset keyword check>",
+  "preset": "<swiss-signal, terminalcore or tidal; omit to let MO-B-00 pick>",
+  "bpm": "<40-240>",
+  "seed": "<integer>",
+  "audio": "<optional path to a supplied track>",
+  "scenes": [
+    { "scene": "title-slam", "text": "<copy line>" },
+    { "scene": "karaoke", "text": "<copy line>" },
+    { "scene": "kinetic-list", "heading": "<copy line>", "items": ["<item>", "<item>"] },
+    { "scene": "counter", "from": "<number>", "to": "<number>", "label": "<copy line>" },
+    { "scene": "signature", "text": "<Latin copy line>", "font": "<EMS stroke font>" },
+    { "scene": "end-card", "text": "<copy line>", "sub": "<copy line>", "paragraph": "<optional credit block>" }
+  ]
+}
+```
+
+The values are placeholders that only show each field's shape; the render refuses a brief that still
+holds one. The copy comes from the treatment's `copy.lines`: the user's words when they gave words,
+otherwise lines written from the treatment's subject. The treatment's `durationSec` sets the length:
+every hold scales up by the same factor (never below its reading floor), and when the floors force a
+longer film the report says so.
+
+| Field | Rule |
+| --- | --- |
+| `scenes` | Ordered shots. Omit it to give `lines` instead (first line = title slam, middle lines = karaoke, last = end-card sub line). |
+| `preset` / `style` | An explicit style. Leave both out to let MO-B-00 pick. The report says "user-specified" only when the request names the preset; otherwise "agent default". |
+| `bpm` | Tier-1 grid, 40..240; default 100 (MO-A-14). Ignored when an audio file yields a beat grid. |
+| `seed` | Run seed for every pass seed (`fnv1a32(runSeed:sceneId:shotIndex:pass)`, MO-SH-01). |
+| `audio` | Tier 2: analysed once, offline, by the pre-warmed librosa venv; absent or failed analysis falls back to Tier 1 with a warning (MO-A-19). |
+| `minDurationSec` | Stretches the last shot so the film is at least this long (never shorter than 3 s); the treatment's `durationSec` is the usual target. |
+
+Scene kinds: `title-slam` (one line, display voice), `karaoke` (one line revealed one 어절 at a
+time, wrapped at word boundaries when long), `kinetic-list` (two or more items appearing one per
+step), `counter` (a number counting from `from` to `to`, with an optional label), `signature`
+(Latin text written by a single-stroke EMS pen; `font` is one of EMSAllure, EMSFelix, EMSOsmotron,
+EMSReadability, EMSTech) and `end-card` (title, optional sub line and optional paragraph).
+Give each repeated scene its own `sceneId` only if you need to address it; repeats become shot 1,
+shot 2 of the same scene id.
+
+## Timeline (Phase 1)
+
+- Tier 1 (default): each shot holds `1.25 x` its reading floor (MO-A-09/10), at least two beats
+  (MO-A-16), and every start is a grid beat, so every cut lands within one frame of a beat
+  (MO-A-15). Reveal steps are at least 0.35 s (MO-A-12) and land on beats too.
+- Reading floor, one function (MO-C-07/08): `line`/`scene` = max(0.9 s Latin or 1.0 s with Hangul,
+  0.2 s per Hangul syllable + words / 3.3); `word` = max(0.5, same rate); `reveal` = 0.35 s. A
+  line/scene must also stay under 17 Latin characters per second. These numbers are provisional.
+- Tier 2: the beat grid replaces the fixed BPM; the same rules apply against it.
+- Tier 3 (`--word-timing`) is opt-in only and fails closed in this build (see runtime.md).
+
+The render refuses to start (exit 13, pre-flight) if the generated timeline breaks any of these,
+or if any character of the brief is missing from the font it resolves to (MO-D-04).
+
+## What the engine does with a scene
+
+A scene is a pure function of the frame: `f.t` (film seconds), `f.lt`/`f.p` (time and 0..1 progress
+inside its own window), its timeline entry and its reveal units. Every beat inside a scene is a
+function of `f.lt` or `f.p`, never a frame number (MO-A-06). The engine then:
+
+1. renders the pinned sub-sample times `t_n + (shutter/fps)((i + 0.5)/N - 0.5)` (MO-A-28; master
+   `--samples 4 --shutter 0.5`, stills and previews one sample);
+2. composites each sample in linear HDR: the preset's layout passes, the type layer (glyphs from
+   real font outlines), then the filter passes;
+3. averages the samples, runs the post chain once with the centre sample's overrides, in the fixed
+   order bloom and halation, chromatic aberration, tone shoulder, grain, vignette, flash,
+   shake/zoom, invert (§A7), and applies sRGB exactly once;
+4. reads the 8-bit frame back and sends the same bytes to the frame hash, the flash audit and ffmpeg.
+
+Post overrides a scene may return, with their neutral values (MO-A-58): `exposure` 1, `bloom` 0,
+`bloomThreshold` 0.85, `bloomKnee` 0, `bloomRadius` 0, `halation` 0, `ca` 0, `grain` 0, `vignette` 0,
+`fade` 1, `flash` 0, `shake` [0,0], `zoom` 1, `invert` false. `invert` may change only on a cut and
+must then hold two beats; every rise of `flash` above 0.1 and every `invert` change counts as an
+event, and a shot allows at most two events in any one-second window (MO-SH-03).
+
+A scene that carries state across frames is `stateful`: CRT phosphor persistence reads the three
+previous frames' pre-CRT images, so on a seek the engine re-renders those frames first (preroll).
+This keeps a seeked still byte-identical to the same frame of a sequential video (MO-A-25).
+
+## Frame log (`render.jsonl`)
+
+One line per pass per frame (`{"frame", "pass", "draws", "uniforms"}`) written by the single
+uniform setter, and one frame line (`"pass": null`) with `rgbaSha256`, `sampleTimes`, `textBoxes`
+(each drawn text's bbox, font, size, weight, voice and script runs), `graphics` (non-glyph element
+boxes), `fills`, the effective post values, the flash transitions and the glyph-ink pixel count.
+The gate reads these records; it never re-detects text from pixels.
+
+## Starter scene craft notes
+
+- Title slam: largest size that fits 1440 px, placed low-left on the grid; enters in 180 ms from a
+  scale of 1.04 (never from collapsed) with Latin width stepping from 125 to 100; tracking stays at
+  -0.035em or looser.
+- Karaoke: glyph positions come from the whole line's layout, so revealed words never shift.
+- Kinetic list: items step in 24 px from the left on their beat; line height 1.5 (Latin) or 1.6
+  (Hangul).
+- Counter: the value steps at 15 updates per second and the digit block stays small so changing
+  digits never fill a quarter of a 10-degree window.
+- Signature: pen travel is distributed over each character's own time window.
+- End card: title, sub line and an optional 60-75 character paragraph; the one accent mark lives
+  here when the preset has an accent and the card is at most 10% of the film.

package/skills/lit-typographic-motion/references/craft-loop.md

@@ -0,0 +1,110 @@
+# Look rounds, done and the reply
+
+A film is not done when a command exits 0. It is done when a gate PASS, a valid treatment and at
+least two recorded look rounds agree, and the last round looked at the final render's own frames.
+
+## The stills set
+
+Every render, `--stills-only` or full, writes the same set:
+
+- `stills/beat-NN-mid.png`: the frame at each treatment beat's midpoint;
+- `stills/cut-NN-strip.png`: a strip of three frames around every cut (-6, 0, +6 frames);
+- `sheet/contact.png`: a 12-frame contact sheet across the whole film;
+- `stills/stills.json`: the round, each file's SHA-256 and what each beat should show.
+
+A full render adds `poster.png`. Open these files with OpenCode's read tool; only images passed to the
+read tool count as viewed (LitOpenCode records each read of a film's stills). OCR or pixel statistics
+may go in `aids` but never count as looking.
+
+## The nine questions
+
+Answer each against a frame you opened. `observed` is at least one sentence naming a concrete
+visible detail in that frame; a bare yes or no is refused.
+
+1. "A stranger would say this film is for: <…>". Ask a fresh subagent that gets only the contact sheet
+   and the beat stills, never the request or the treatment, and record its sentence verbatim with
+   `by: "blind"`; without a subagent, answer it yourself with `by: "self"`. `verdict: "yes"` when that
+   reading matches the treatment's subject.
+2. Does every beat show its `onScreen` plan?
+3. Is the craft at the level `ambition` asks for (transitions, rhythm, depth, hierarchy)?
+4. Is any request text, meta label, placeholder, file name or internal term on screen?
+5. Does the ending land?
+6. Does the sound follow the cuts? Answer from `sound-cues.json`.
+7. Name one thing a skilled motion designer, given only the request, would have shown that this film
+   does not. `verdict: "yes"` when you can name one; then revise.
+8. Is any element on screen without a job in its beat?
+9. Could every copy line be pasted unchanged into a film about a different subject? If yes, rewrite
+   the copy from `subject.specifics`.
+
+Another round is required after a "no" on 1, 2, 3, 5 or 6, a "yes" on 4, 8 or 9, or a nameable Q7.
+
+## Recording a round
+
+```sh
+node render.mjs look --out <d> --round N --answers <answers.json>
+```
+
+```json
+{
+  "viewed": ["stills/beat-01-mid.png", "sheet/contact.png"],
+  "weakestBeat": "<beat index and why>",
+  "change": "<the change you will make before the next render>",
+  "answers": [
+    { "q": 1, "verdict": "<yes or no>", "frame": "sheet/contact.png", "observed": "<a sentence>", "by": "<blind or self>" }
+  ]
+}
+```
+
+- Rounds share one counter with renders (1-3): `look --round N` belongs to the stills set rendered
+  with `--round N`, and each round is the previous one plus one.
+- `look` refuses a frame that is not in the latest stills set, and stamps the round with the SHA-256
+  of the current manifest (`stills/stills.json` after a stills round, `manifest.json` after a full
+  render) and of each listed frame.
+- Round 1 is always a stills round before the first full render; it must name the weakest beat and
+  the change.
+- The last round must view the poster, the contact sheet, every beat midpoint and every transition
+  strip of the final render.
+- If no image tool is reachable, record `"blocked": "no-vision-tool"`; the done check then ends with
+  `DONE_UNVIEWED`, and the reply says in plain words that nobody viewed the frames.
+- At most 3 rounds. After round 3, deliver with every open item stated plainly.
+
+## Done
+
+`node gate.mjs --done <d>` exits:
+
+| Exit | Status | Meaning |
+| --- | --- | --- |
+| 0 | `DONE` | gate PASS, a valid treatment, 2+ look rounds (round 1 on stills with a change, the last on the final render's manifest and all its frames), no round still asking for another, and, under OpenCode, every viewed frame read with the read tool |
+| 1 | `NOT DONE` | something above is missing; the reason names it |
+| 2 | `DONE_WITH_OPEN_ITEMS` | round 3 is spent; deliver and state each open gate rule or look item |
+| 3 | `DONE_UNVIEWED` | everything else holds, but the frames were not viewed |
+
+The done check also compares the final treatment with the first valid one and prints `downgraded:`
+for a length cut of more than 20 %, fewer subject beats, sound switched to none without a user
+request, or a stage film moved to the type path. Never downgrade to pass: fix the cause (a scrim,
+size, placement, timing or seeded randomness) or deliver with the failure stated.
+
+## The reply
+
+- Keep the product's activation line where it is; below it, no second banner and no emoji.
+- Plain words, no internal names (no rule ids, no path or preset jargon).
+- One line on the defaults chosen.
+- A label on every invention (subject, name, facts, copy) and on generated sound.
+- One plain line on what was checked: flash safety, legibility, and the frames looked at.
+- Where the copy lives (the `COPY` object in `stage/index.html`, or the brief) and the one command
+  that re-renders.
+- Any `downgraded` item and any open look item or failed rule.
+
+## Gate rows (both paths)
+
+| Check | Path | Rule |
+| --- | --- | --- |
+| Flash (WCAG 2.3.1) | both | at most 3 general and 3 red flashes in any 1 s window, master and looping preview; the grid and window transpose for 9:16; a failure withholds every export |
+| Size, fps, length | both | stage: exactly the format size, 60 or 30 fps, within ±10 % of `durationSec`; type: 1920x1080 at 60 fps |
+| File sizes | both | preview at most 3 MB, poster at most 1 MB |
+| Reduced-motion still | both | present; on the stage it is the final beat's midpoint |
+| Near-black runs | both | no near-black stretch longer than twice the minimum hold |
+| Sound | both, unless `none` | a stream within ±0.1 s of the video, sample peak at most -0.5 dBFS; a generated bed has no stretch below -50 dBFS RMS longer than 1.5 s in the first 3 s |
+| Determinism | both | stage: 8-16 sample frames replayed from 0 in a fresh browser; type: the cut frames re-rendered and compared |
+| Text | stage | copy found, contrast, title-safe, reading floor, fonts; decor limits; meta labels |
+| Type rules | type | GLSL presence, contrast, reading time, tracking, Hangul, leading, measure, hue clusters, frame time, glyph coverage |

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

@@ -0,0 +1,88 @@
+# Runtime, pre-warm and BLOCKED codes
+
+## Pre-warm once, read-only afterwards
+
+`litopencode motion-runtime install` runs outside any sandboxed session. It installs, into
+`${XDG_CACHE_HOME:-~/.cache}/litopencode/motion-runtime/`:
+
+- the engine's pinned JavaScript packages (`playwright-core`, `opentype.js`, `ws`) with
+  `npm ci --omit=dev --ignore-scripts` from the lockfile inside this skill, plus a lockfile receipt;
+- the fetched fonts and their licence files, each checked against its pinned sha256 (`fonts/pins.json`):
+  Galmuri9 with its OFL text, MesloLGS NF with the Apache-2.0 notice, the Apache-2.0 text and the
+  Vera/Arev notices; the official Pretendard Regular only if the lit-pptx Hangul pair is missing;
+- with `--audio`, a Python venv holding the hash-pinned librosa set from `requirements-audio.txt`
+  (`pip install --require-hashes --only-binary=:all:`).
+
+`litopencode install` attempts the same pre-warm and prints one receipt line; a failure never fails
+the install. A render never installs, fetches or repairs anything: it checks hashes and receipts and
+stops with a named state.
+
+`litopencode motion-runtime status` and `litopencode doctor` report five probes on every run:
+Chrome (path and version), ffmpeg (version and the preview encoder rung: `libwebp_anim`, `img2webp`
+or GIF), the WebGL2 renderer string from a real headless probe, the software-GL or unknown-renderer
+warning, and the pre-warm state naming what is missing and the command that fixes it.
+
+## Exit codes
+
+| Exit | Name | Meaning | Fix |
+| --- | --- | --- | --- |
+| 0 | OK | the requested mode finished; for `film`, the gate passed | none |
+| 10 | BLOCKED_NO_CHROME | Chrome is missing or failed to start headless; the message carries its first error line | install Chrome or set `CHROME_PATH` |
+| 11 | BLOCKED_NO_WEBGL2 | Chrome ran but no rung produced a WebGL2 context | check GPU drivers; the SwiftShader rung is already tried |
+| 12 | BLOCKED_NO_FFMPEG_FOR_VIDEO | a film was requested without ffmpeg | install ffmpeg; `--stills-only`, `stills` and `sheet` still work |
+| 13 | GATE_FAIL_QA | pre-flight or the full gate failed; the report names the rules | fix and rerun the next round |
+| 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`) |
+| 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 | fix the track or its plan |
+
+## Chrome, egress and the sandbox
+
+- Launch ladder (MO-A-51), first rung that yields a real `getContext('webgl2')` in the page wins and
+  is recorded as `chromeFlags`: the platform GPU rung (macOS `--use-angle=metal`, Linux
+  `--use-angle=gl`, Windows `--use-angle=d3d11`), then `--use-angle=swiftshader
+  --enable-unsafe-swiftshader`. The anti-throttling flags are always appended. The Chrome profile
+  lives in `<out>/.run/` and is removed on exit; Chrome is driven over a pipe, so no control port.
+- Frame egress: a WebSocket on `127.0.0.1:0`. If the sandbox refuses to listen, each frame's
+  readback buffer is pulled over CDP instead. Either way the hash, the flash audit and ffmpeg see
+  the same bytes.
+- A software renderer (SwiftShader, llvmpipe, softpipe, lavapipe, Apple Software Renderer,
+  Microsoft Basic Render Driver) is allowed and labelled: one sample per frame, tidal octaves
+  halved (at least 3), CRT persistence off, affected pass ranges marked `downgraded`.
+
+## The stage renderer
+
+- The stage path always uses the software rung (SwiftShader, CPU raster) with the compositor, image
+  and animation flags that keep capture deterministic, `--mute-audio`, `--force-color-profile=srgb`,
+  `--force-device-scale-factor=1`, the window at the format size, and the mock-keychain flags.
+- The page is served from the synthetic origin `http://lit.stage/` through request interception, so
+  nothing listens on a port; every other request fails and is recorded (exit 19), and a host
+  resolver rule maps every other host to nothing as a backstop.
+- Three browsers run side by side: the master capture, a fresh replay for the determinism samples and
+  a separate QA replay that hides text to measure ink. The master never changes a style.
+- Fonts come from this skill and the pre-warmed cache; an unwarmed cache stops with exit 14.
+
+## Sound
+
+- Generated (the default under bare `lit`, on both paths): a deterministic bed from the treatment,
+  built in code with no network or model weights: tempo, pulse and a chord pad, plus the accents the
+  beats ask for. 48 kHz 16-bit stereo, exactly the film's length, peaks at most -2 dBFS, integrated
+  loudness about -16 LUFS (ITU-R BS.1770-4, measured in this code). `sound-cues.json` lists every cue
+  against its cut. `node render.mjs sound --out <d>` builds it on its own.
+- Supplied or authored tracks are always muxed, whatever the audio-analysis tier's state, padded or
+  trimmed to the film with a 50 ms fade. AAC at 256 kb/s.
+
+## Audio analysis tiers (the type path's cut grid)
+
+- Tier 1 (default): text reading time and a BPM grid.
+- Tier 2: a supplied audio file is analysed once by the pre-warmed venv into a beat grid for this
+  run only. An absent venv, a venv that no longer matches its pins, or a failed analysis falls back
+  to Tier 1 with a warning; the venv is never repaired in the session.
+- Tier 3 (`--word-timing`, opt-in only): `motion-runtime install --word-timing` states the download
+  size and every model pin before downloading and fails closed unless each model has a pinned id,
+  revision and a verified licence that allows commercial use. This build pins no licence-verified
+  Korean alignment model, so the install fails closed and a render with `--word-timing` exits 14.
+  MMS_FA and madmom weights, aubio and essentia are never used at any tier.

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

@@ -0,0 +1,164 @@
+# Stage path: authoring a page the renderer films
+
+Load this after the treatment says `path: stage`. On the stage path you are the illustrator, the
+animator and the editor: you write one page that draws the film as a function of time, and the
+renderer captures it frame by frame, deterministically, then gates, checks and encodes it. The page
+is yours; the kit gives motion primitives, never ready-made scenes, objects or layouts.
+
+## Files
+
+- `<out>/treatment.json`: the treatment (see `treatment.md`).
+- `<out>/stage/index.html`: the page. Put its own SVG, PNG, JPG, WebP, JS, CSS and WAV files beside
+  it under `stage/`. Write everything yourself; never install, download or copy a third-party library
+  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.
+
+## The page contract
+
+```html
+<!doctype html>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/stage-kit.js"></script>
+<body>…your SVG, DOM and canvases…</body>
+<script>
+  const COPY = { /* every on-screen line, in one place, so copy is easy to edit */ };
+  LitStage.define({ width: 1920, height: 1080, fps: 60, duration: 16, render(t) { /* draw frame t */ } });
+</script>
+```
+
+- `LitStage.define({ width, height, fps, duration, render })` (or `window.litStage = { … }`). The size
+  must match the treatment's `format`: 1920x1080 for 16:9, 1080x1920 for 9:16. `fps` is 60, or 30 when
+  the treatment says so. `duration` in seconds must land within ±10 % of `durationSec`.
+- `render(t)` draws the frame at time `t` in seconds. Make it a pure function of `t` where you can;
+  that keeps every frame seekable and deterministic.
+- You may also use CSS animations and transitions, the Web Animations API, SVG SMIL, and
+  `requestAnimationFrame` with Canvas2D or WebGL. The renderer drives all of them from a virtual
+  clock: `Date`, `performance.now`, timers, `requestAnimationFrame`, `requestIdleCallback`,
+  `document.timeline` and `Math.random` (seeded from the treatment's `seed`) all read film time.
+- The page is served from `http://lit.stage/` with no listening socket. Only files inside `stage/`,
+  the kit and the fonts are served; `..` and symlinks that leave the directory are refused.
+- Fonts: `/lit/fonts.css` declares the product's faces with `font-display: block`: `Archivo` (widths
+  75 %, 100 %, 125 %; weights 400, 700, 900), `LitOpenCode Sans` (400, 700; Hangul), `VT323`,
+  `Silkscreen` (400, 700), `MesloLGS NF` and `Galmuri9`. Use only these; the QA checks the platform
+  font behind every copy line.
+
+## Forbidden (the render stops)
+
+| 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 |
+| 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` |
+
+A page that asks for a WebGL context and gets none stops with exit 11.
+
+## Kit reference (`/lit/stage-kit.js`, global `LitStage`)
+
+Easing. Named curves plus `bezier()`:
+
+```js
+const e = LitStage.ease.snap(0.4);                  // also linear, in/out/inOut Quad..Quint, Sine, Expo, Circ, Back, glide, settle, exit, anticipate
+const custom = LitStage.bezier(0.2, 0.9, 0.1, 1)(p);
+```
+
+Spring (closed form, exact at any `t`):
+
+```js
+const y = LitStage.spring({ stiffness: 180, damping: 14, from: 80, to: 0 })(t - 1.2);
+```
+
+Keyframes over numbers, arrays or colours:
+
+```js
+const x = LitStage.kf(t, [{ t: 0, v: -200 }, { t: 1.4, v: 0, ease: "settle" }, { t: 3, v: 40, ease: "glide" }]);
+```
+
+Timing windows, staggers and sequences:
+
+```js
+const p = LitStage.at(t, 2.0, 0.8, "snap");          // 0..1 inside [2.0, 2.8]
+const delay = LitStage.stagger(i, { each: 0.06, from: "center", n: items.length });
+const s = LitStage.seq([["enter", 0.6], ["hold", 2.4], ["leave", 0.5]], 4); s.hold.progress(t);
+```
+
+Seeded random (the treatment's `seed` by default):
+
+```js
+const r = LitStage.rand(); const jitter = r.range(-4, 4); const pick = r.pick(list);
+```
+
+Text splitting, grapheme- and 어절-aware:
+
+```js
+const parts = LitStage.splitText(el, { by: "grapheme" });  // or "word" (a Hangul 어절 stays whole) or "line"
+```
+
+SVG path drawing and a single-subpath morph (multi-subpath morphs are unsupported; morph each
+subpath on its own):
+
+```js
+LitStage.drawPath(pathEl, LitStage.at(t, 0.5, 1.5, "glide"));
+const shape = LitStage.morph(fromD, toD); pathEl.setAttribute("d", shape(p));
+```
+
+Masks, clips and colour:
+
+```js
+LitStage.clip.circle(el, p, { cx: 30, cy: 60 }); LitStage.clip.wipe(el, p, "left"); LitStage.clip.iris(el, p);
+LitStage.mask.linear(el, p, { angle: 120, soft: 10 }); LitStage.mask.radial(el, p);
+el.style.fill = LitStage.mix("#1b3a4b", "#e0a458", p);   // mixed in linear light
+```
+
+Text registration for the QA:
+
+```js
+LitStage.text(titleEl);                                   // one reading run
+LitStage.text(signEl, { decor: true });                   // illustrative text inside a drawn subject
+LitStage.text({ content: "…", x, y, w, h });              // canvas or WebGL text, every frame it is drawn
+```
+
+## How the QA reads the stage
+
+- Every `copy.lines` entry must appear on screen at some beat; a missing line stops the render with
+  exit 17 and quotes it. Keep copy in DOM or SVG text where you can; canvas copy is found through its
+  registration, but its contrast is not measured (a WARN).
+- Copy runs FAIL on contrast (3.0 for large type, 4.5 for body; large means at least 3 % of the
+  frame's short side), on leaving the central 90 % title-safe area and on a hold shorter than the
+  reading floor. Decor runs only WARN on contrast, are exempt from title-safe and the reading floor,
+  may not carry a copy line, and may cover at most 25 % of the visible text area.
+- A run equal to or containing the request, the idea, a file name or a word such as path, preset,
+  gate, beat or treatment is a WARN the look must answer.
+- Canvas text drawn without registration is not measured (a WARN the look must answer).
+- The subject must be drawn: when every word is hidden, at least half of the beat midpoints still
+  carry visible structure outside the text boxes.
+
+## Determinism
+
+- The renderer replays the clock from 0 in a fresh browser and compares 8-16 sample frames by the
+  SHA-256 of their pixels. A mismatch stops with exit 18, naming the frame and the first region.
+- Filters (`blur()`, `backdrop-filter`, `mix-blend-mode`, `box-shadow`, SVG `feGaussianBlur`, Canvas2D
+  `shadowBlur`) and WebGL shaders are deterministic on the software renderer the stage uses.
+- Seed every random choice from `LitStage.rand()` or `Math.random()` (both seeded); never read
+  `crypto.getRandomValues` or `performance.timeOrigin`.
+
+## Rendering
+
+- Stills round: `node render.mjs stage --out <d> --stills-only --round 1` (about 20 s): the beat
+  midpoints, a strip around every cut and a 12-frame contact sheet, no encode.
+- Film: `node render.mjs stage --out <d> --round N`. Give the command a timeout of at least 600 s; a
+  15 s 1080x1920 film with its checks takes a few minutes. Never shorten the film to save render time.
+  Progress is written to `<d>/.run/progress.json`. When the host's command timeout is shorter, add
+  `--detach`: the render continues in the background, and `<d>/.run/render-exit.json` holds its exit
+  code when it ends (the log is `<d>/.run/render.log`).
+- Outputs: `film.mp4` (H.264, BT.709, sound muxed), `preview.webp` or `.gif`, `poster.png`,
+  `reduced-motion.png` (the final beat's midpoint), `manifest.json`, `gate-report.txt`, `stills/`,
+  `sheet/` and `sound-cues.json`.
+
+## Sound on the stage
+
+The default is the generated bed (`sound.mode: generated`). To score the film yourself, write a WAV
+into `stage/` and set `sound: { mode: "authored", file: "stage/<name>.wav", plan }`. The page itself
+never plays audio: audio elements and audio contexts are forbidden, and the renderer muxes the track.