@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/skills/lit-typographic-motion/fonts/stroke/OFL.txt

@@ -0,0 +1,91 @@
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/plugins/litclaude/skills/lit-typographic-motion/fonts/vt323/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2011, The VT323 Project Authors (peter.hull@oikoi.com)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/plugins/litclaude/skills/lit-typographic-motion/references/brief-schema.md

@@ -0,0 +1,91 @@
+# Brief schema (`litclaude.motion-brief/v1`, type path)
+
+On the type path the brief is what the engine renders. Write it after `treatment.json` (which sets
+`path: type`, the length, the beats and the copy) as plain JSON next to the output directory. The
+engine reads the treatment and the brief, builds the timeline, checks it before the first frame,
+and renders. Text in the brief is the film's content; nothing in it is ever executed.
+
+## Two shapes
+
+**Lines only** — the engine composes the film: the first line (or `title`) becomes a title slam,
+each middle line with two or more words becomes a karaoke line (single words become title slams),
+and the last line becomes the end card.
+
+```json
+{
+  "schema": "litclaude.motion-brief/v1",
+  "lines": ["<first copy line>", "<a middle copy line>", "<last copy line>"]
+}
+```
+
+**Explicit shots** — the agent chooses each scene. Use this when the copy has a list, a number, a
+signature or a credit line. The values are placeholders; the engine refuses a brief that still
+shows one.
+
+```json
+{
+  "schema": "litclaude.motion-brief/v1",
+  "style": "<preset>",
+  "bpm": "<tempo>",
+  "shots": [
+    { "scene": "title-slam", "text": "<opening line>", "sub": "<small machine-voice line>" },
+    { "scene": "karaoke-line", "text": "<a line read eojeol by eojeol>" },
+    { "scene": "kinetic-list", "heading": "<list heading>", "items": ["<item>", "<item>", "<item>"] },
+    { "scene": "number-counter", "from": 0, "to": "<figure>", "label": "<what the figure counts>" },
+    { "scene": "signature", "text": "<a Latin line to write by pen>", "font": "<stroke font>" },
+    { "scene": "end-card", "text": "<closing line>", "sub": "<credit line>" }
+  ]
+}
+```
+
+## Fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `schema` | string | `litclaude.motion-brief/v1` |
+| `title` | string | Working title; never drawn on screen |
+| `label` | string | The film's own name, drawn as the terminal window label; omit it and no label is drawn |
+| `request` | string | The user's request, verbatim; read only by the preset auto-pick (the treatment's copy wins) |
+| `style` | `auto` \| `swiss-signal` \| `terminalcore` \| `tidal` | Explicit style wins over the auto-pick; the report calls it user-specified only when the request names it, otherwise agent default |
+| `signalHue` | `green` \| `blue` | terminalcore only: one signal hue per film |
+| `bpm` | number | Tier-1 beat grid; default 100 |
+| `seed` | integer | Run seed for every pass (default 20260926) |
+| `audio` | path | Tier 2 beat grid when the librosa venv is pre-warmed; the track itself comes from `treatment.sound` and is always muxed |
+| `wordTiming` | boolean | Tier 3 opt-in; exits 14 until its runtime exists |
+| `lines` | string[] | Lines-only shape |
+| `shots` | object[] | Explicit shape (below) |
+| `posterFrame` | integer | Frame for the poster; default the middle of the first text shot |
+| `post`, `passParams` | object | Expert overrides; the gate still applies every cap |
+
+## Shots
+
+| `scene` | Fields | What it shows |
+| --- | --- | --- |
+| `title-slam` | `text`, `sub` | Display type landing on the beat; `sub` is a small machine-voice line |
+| `karaoke-line` | `text` | The line revealed eojeol by eojeol; nothing reflows |
+| `kinetic-list` | `heading`, `items[]` | A heading and items that arrive one per reveal step |
+| `number-counter` | `from`, `to`, `prefix`, `suffix`, `label` | A figure counting up in the machine voice |
+| `signature` | `text` (Latin only), `font` | A pen writing the line in an EMS single-stroke font |
+| `end-card` | `text`, `sub` | The closing statement; its last frame is the reduced-motion still |
+
+Stroke fonts: `ems-allure` (connected script), `ems-felix` (brush), `ems-osmotron` (geometric),
+`ems-readability` (clean sans, default), `ems-tech` (hand lettering). They have no Hangul; a
+`signature` shot with Hangul is refused before rendering.
+
+Optional per shot: `hold` (seconds, only ever lengthens), `post` (MO-A-58 overrides for that shot).
+
+## Writing text for motion
+
+- Length comes from the treatment. The engine gives every unit at least 1.25 x its reading floor,
+  then scales the holds up until the film reaches `durationSec`; it never holds a unit under its
+  floor. When the floors alone make the film longer than the treatment asked, the render warns and
+  the reply says so.
+- One idea per shot. A shot that needs a paragraph is a card, not a slam; give it a `kinetic-list`
+  or split it across shots.
+- Keep the user's words when they supplied words, and never change what they mean. When the
+  treatment's copy is invented, write it from `subject.specifics`, never from the request.
+  Punctuation is made typographic for display voices automatically (`...` becomes an ellipsis,
+  straight quotes become curly); the terminal look keeps typewriter punctuation.
+- A running index ("01 / 05") appears only when `typePlan.index` is true; the engine refuses one
+  otherwise. The working title is never drawn; only `label`, the film's own name, is.
+- Never put lyrics or other text the user does not own into a film as its content.

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

@@ -0,0 +1,69 @@
+# Craft loop and QA gate
+
+## One round (MO-C-15)
+
+Rounds share one counter (1-3) with the look rounds in `look.md`.
+
+1. `make brief.json --out <dir> --round N --stills-only`: treatment check, pre-flight gate (fonts,
+   glyph coverage, timeline), the beat stills, one transition strip per cut and the contact sheet in
+   `<dir>/stills/`. Nothing is encoded yet.
+2. **Look.** Open every file the stills index lists with the Read tool and answer the look questions
+   in `look.md`: nothing clipped at the edges, no empty frame at a cut, type legible at its size, the
+   preset's palette and nothing else, the accent at most once, no working title or index on screen.
+   Record the round with `look --round N`.
+3. Fix the brief (a different scene, a different style, better copy) where a still is wrong; rerun
+   step 1 when you changed it.
+4. `make brief.json --out <dir> --round N`: master with the sound bed, preview, poster,
+   reduced-motion still, a second-process determinism re-render, a perf run and the full gate.
+5. On exit 13 read `gate-report.txt`, fix the named rule, and start the next round from step 1.
+
+## Stop conditions (MO-C-16)
+
+- Done follows `look.md`: gate PASS, a valid treatment, at least two look rounds (the round-1
+  stills round with its change, then a last round on the final full render's stills).
+- Round 3 still failing: stop and report the failed rules and what each round changed. The film
+  and exports are kept at their names for the user's judgment, except after a flash-audit FAIL.
+- **Flash-audit (MO-C-03) FAIL in any round:** the MP4, preview, poster and still move to
+  `withheld/`. They are diagnostics, never deliverables, not even as a draft. Say the render is
+  withheld pending a fix.
+- A blocked environment (exit 10, 11, 12, 14, 15): stop at once and name the fix; more rounds cannot
+  repair a missing host tool.
+- A frame-time (MO-D-02) FAIL alone still delivers the film with the report.
+- Never answer a failure by shortening the film, dropping a shot, or switching the sound to none.
+
+## Gate table
+
+Numbers marked provisional are the spec's proposed defaults, implemented as written until the
+user signs them off; the report labels them.
+
+| Rule | Threshold | Typical fix |
+| --- | --- | --- |
+| MO-C-01 GLSL presence | every frame covered by a look pass that drew | never remove the preset's passes |
+| MO-C-02 WebGL2 tier | renderer recorded; software GL labelled | none (environment) |
+| MO-C-03 flash audit | <= 3 general and <= 3 red flashes in every 1 s window, master (non-looping) and preview (looping); excursion method, 640x360 window | fewer, slower large changes; no full-frame flips |
+| MO-C-04 title-safe | every glyph bbox inside x 96–1824, y 54–1026 | shorter line, smaller size |
+| MO-C-05 action-safe (provisional) | non-glyph marks inside x 48–1872, y 27–1053 | move the mark |
+| MO-C-06 contrast (provisional size rule) | 4.5:1, or 3:1 at >= 32 px (>= 25 px bold) | use the type colour, not the signal, for small text |
+| MO-C-07/08 reading time (provisional) | the floor function in type-craft.md | fewer words per shot, or `hold` |
+| MO-A-13 eojeol | reveals are whole eojeol / items | keep items whole |
+| MO-A-15 / 16 beat | cuts within 1 frame of a beat; shots >= 2 beats | engine-generated; check custom `hold` |
+| MO-C-09 / MO-A-25 determinism | byte-identical `rgbaSha256` in a second process; seeked equals sequential | a scene read a clock or random: fix the scene |
+| MO-C-10/11/12 | >= 1920x1080, >= 30 fps, >= 3 s; ffprobe yuv420p / bt709 / tv | engine-set |
+| MO-C-13 sizes (provisional) | preview <= 3 MB, poster <= 1 MB; MP4 warn > 100 MB / 10 s | the preview ladder steps down itself |
+| MO-C-14 reduced-motion still (provisional) | present; ink >= 0.9x the final text frame | end on a settled end card |
+| MO-C-25 tracking (provisional) | display >= -0.04 em; machine voice never negative | |
+| MO-C-26 line height | >= 1.5 Latin / 1.6 Korean for 2+ lines | |
+| MO-C-27 measure | Latin paragraph cards 60–75 ch | |
+| MO-C-29 accent (provisional) | <= 1 signal + 1 accent saturated cluster; accent in one entry, <= 10% of frames | remove the extra colour |
+| MO-D-02 perf (provisional) | p95 <= 40 ms (hardware) / 250 ms (software) at samples 1 over >= 120 frames, each timed as the next frame of a sequence | lower octaves; never withholds |
+| MO-D-03 empty frames (provisional) | no empty near-black run longer than 2x the minimum hold (+1 s at the ends) | a scene that failed to paint |
+| MO-D-04 glyphs (provisional) | every character in its run's font | change the text or style |
+| MO-SH-01..11 | seed formula, event budget, glitch/surge/flicker caps, dither seed per shot, guides off, <= 2 terminal layers, software downgrade | engine-enforced; report any FAIL as an engine defect |
+| MO-A-33, MO-FT-04, MO-A-58 | Hangul weights from the lit-pptx pair only; no tracking or width motion on Hangul; post overrides in range, invert only on cuts | |
+
+## Report (MO-C-17)
+
+`gate-report.txt` starts with the fixed render-report block (outputs, preset and why, duration,
+passes, WebGL2 tier, one line per MO-C-01..14 rule, rounds, frames viewed from `look.json`), then one line each for
+MO-C-25/26/27/29 and MO-D-02/03/04, then every other enforced rule. Quote its verdict line and any
+FAIL lines to the user; do not paraphrase a FAIL into a pass.

package/plugins/litclaude/skills/lit-typographic-motion/references/engine-contract.md

@@ -0,0 +1,104 @@
+# Engine contract (scene author ↔ engine)
+
+The engine renders any output frame from its time `t` and the run's fixed parameters (seed,
+samples, shutter, scale, preset). Nothing else may change a pixel: no clock, no unseeded random,
+no network, no file read during the render. This is what makes a still you looked at in round 1 the
+same frame the film contains, and what the determinism gate hashes.
+
+## Pipeline
+
+1. **Plan (Node).** The brief becomes shots and the canonical timeline (`engine/core/timeline.mjs`).
+2. **Page (headless Chrome).** `engine/web/` is served from disk through DevTools Fetch
+   interception; Chrome runs on the pipe transport, so no control port listens. The page gets the
+   plan and the fonts (bundled, reused lit-pptx files, or the pre-warmed cache).
+3. **Frame n.** For each of `samples` sub-frames at `t = max(0, n/fps + (shutter/fps)((i+0.5)/N − 0.5))`
+   the shot active at that time is composited in linear HDR: background pass, grid rules or window
+   chrome, the scene's marks, the glyph layer, then the filter passes in preset order. The
+   sub-frames are averaged, then the post chain runs once with the middle sub-frame's overrides,
+   with grain keyed to the frame's own time.
+4. **Egress.** The final RGBA8 frame (rows top to bottom; alpha carries the glyph-coverage mask) is
+   read back through a fenced pixel-pack buffer and sent over a WebSocket on 127.0.0.1:0. If the
+   host refuses `listen`, the same buffer is pulled over CDP instead, and the report says so.
+5. **Node.** Each frame is analysed (ink pixels from the mask, then alpha forced to 255), hashed
+   (`rgbaSha256`), audited for flashes, logged, and piped to ffmpeg. The bytes hashed, audited and
+   encoded are the same bytes.
+
+## Scene API (`engine/web/scene.mjs`)
+
+A scene is constructed once per shot with `ctx` (shot, preset, palette, voices, grid, terminal,
+fps, total frames, seed, stroke fonts, accent window) and implements:
+
+| Member | Contract |
+| --- | --- |
+| `render(f, stage)` | Draw frame `f` and return post overrides. Pure given `f` (and state, below). |
+| `stateful`, `prerollMax` | Set when the scene keeps state between frames. The state must have finite memory no longer than `prerollMax`. |
+| `advance(f)` | The only place state changes. Called for every sub-frame, including preroll replays. |
+| `reset()` | Restore the initial state. Called when the shot is entered and after a seek. |
+
+`f` carries `t`, `lt` (time since the shot started), `p` (0..1 progress), `start`, `end`. Beats in
+a scene are anchored to `lt`, `p` or the shot's reveal steps, never a literal frame number.
+
+`stage` provides `type` (the type kit), `glyphs` (the glyph layer; its alpha becomes the mask),
+`lines` (instanced hairlines), `mark(rect, hex, id, kind)` (a filled non-glyph mark, recorded for the
+action-safe and accent checks) and `record` (the frame's element and fill log).
+
+After a seek the engine resets a stateful shot and replays `advance` over the frames inside
+`prerollMax` with the same sub-frame pattern, so a seeked still equals the sequential frame.
+
+## Post chain (fixed order)
+
+bloom + halation → chromatic aberration → tone shoulder → grain → vignette → fade → flash →
+shake/zoom → invert. All maths in linear light; the sRGB transfer happens once, in the last pass.
+Scenes may override any field for their frame, never the order.
+
+| Field | Range | Neutral |
+| --- | --- | --- |
+| `exposure` | > 0 | 1 |
+| `bloom`, `halation`, `grain`, `vignette` | 0–1 | 0 |
+| `bloomThreshold` | 0–1 | 0.85 |
+| `bloomKnee`, `bloomRadius` | 0–1 | 0 |
+| `ca` | px at 1080p | 0 |
+| `fade` | 0–1 (opacity) | 1 |
+| `flash` | 0–1; each rise above 0.1 is an event | 0 |
+| `shake` | [x, y] px | [0, 0] |
+| `zoom` | > 0 | 1 |
+| `invert` | boolean; only on a cut, held >= 2 beats | false |
+
+## Look-library passes
+
+| Pass | Kind | Seed | Hard limits |
+| --- | --- | --- | --- |
+| `swiss-grid` | layout (hairline rules) | none | guides off in any export |
+| `dither` | filter | only blue-noise mode | seed fixed for the whole shot |
+| `tidal-gradient` | background | noise origin per shot | surges <= 2/s, attack and decay >= 0.1 s |
+| `crt` | filter | static triad grain | flicker <= 0.06 peak-to-peak; persistence only on stateful shots |
+| `glitch` | filter | hit schedule per shot | <= 2.0 hits/s, band <= 20% of the frame, one displace + one restore |
+| `terminal-ui` | background (Canvas2D chrome) | cosmetic readout digit | <= 2 layers per scene |
+
+Every pass seed is `fnv1a32("<runSeed>:<sceneId>:<shotIndex>:<pass>")` as an unsigned integer.
+Across all sources a shot has at most two events (glitch hits, surges, flash rises, invert changes,
+boot flickers) in any one second; the schedule is built before the first frame.
+
+Every draw goes through one uniform-setter wrapper that logs `{frame, pass, draws, uniforms}` to
+`render.jsonl`. A frame counts as covered by the look library only when some pass issued a draw.
+
+## Software GL
+
+If the WebGL2 renderer string contains swiftshader, llvmpipe, softpipe, lavapipe, apple software
+renderer or microsoft basic render driver, the engine lowers `--samples` to 1, the tidal octaves to
+max(3, floor(octaves/2)), turns crt persistence off, marks those passes `downgraded: true`, and the
+report says so.
+
+## Outputs and logs
+
+`manifest.json` holds the canonical fields (schemaVersion, engineCredit, presetId, seed, fps,
+resolution, scale, samples, shutter, renderer, softwareRenderer, chromeFlags, previewEncoder,
+audioTier, bpm or beatGrid, durationSec, generatedAt, passRanges, timeline, warnings) plus
+`frameCount`, `round` and the poster/still overrides. `render.jsonl` has one line per pass per frame
+and one frame line (`pass: null`) with `rgbaSha256`, `textBoxes`, ink pixels, elements, fills, post
+values and the frame's flash-audit transitions.
+
+A textBoxes entry is `{elementId, text, voice, fontFile, fontSizePx, capHeightPx, weight, fill,
+bbox}` plus `script`, `trackingEm`, `widthPct` and, for multi-line blocks, `lineCount`,
+`lineHeight`, `cjk`, `paragraph`, `measureCh`. The bbox comes from the real glyph outlines under
+the scene's transform, in logical 1920x1080 px.

package/plugins/litclaude/skills/lit-typographic-motion/references/look.md

@@ -0,0 +1,106 @@
+# Look rounds and Done
+
+A gate PASS says the film is safe and legible. It does not say the film is good. The look rounds are
+where you judge the pixels against the treatment, and the done-check will not accept a film nobody
+looked at.
+
+## Viewing pixels
+
+Only files you open with the Read tool count as viewed. OCR, pixel statistics and file listings may
+be written down as `aids`, but they never count as looking. Every render (stills-only or full)
+writes the stills set into `<dir>/stills/`, listed in `stills/index.json`:
+
+- `beat-NN.png`: the frame at each beat's midpoint, full size;
+- `strip-NN.png`: one transition strip per cut, the frames 6 before, at and 6 after the cut;
+- `sheet.png`: a 12-frame contact sheet across the film;
+- after a full render, the delivered `poster.png` is listed too.
+
+If no image tool can be reached, record the round with `look --round N --blocked no-vision-tool`.
+The done-check then ends as `DONE_UNVIEWED`, and the reply must say in plain words that nobody
+viewed the frames.
+
+## Questions
+
+Answer all nine every round. Each answer names the frame it is about and what you saw there.
+
+1. A stranger would say this film is for: `<…>`. Ask a fresh subagent (the Agent tool) with only the
+   contact sheet and the beat stills, never the request or the treatment, and record its sentence
+   verbatim with `by: blind`. If no subagent can run, answer it yourself with `by: self`.
+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 it from `sound-cues.json`.
+7. Name one thing a skilled motion designer, given only the request, would have shown that this film
+   does not. If you can name one, 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`.
+
+## Answers file
+
+Write the answers to a JSON file and record them with
+`node "$SKILL_ROOT/scripts/motion.mjs" look --out <dir> --round <N> --answers <file>`.
+The values below are placeholders; `look` refuses them.
+
+```json
+{
+  "viewed": ["stills/sheet.png", "stills/beat-01.png", "stills/strip-01.png"],
+  "weakestBeat": "<beat index; round 1>",
+  "change": "<what you changed after round 1>",
+  "aids": ["<optional notes that are not looking>"],
+  "answers": [
+    { "q": 1, "verdict": "<yes or no: does the stranger's sentence match the film's audience and subject>", "by": "<blind or self>", "sentence": "<the stranger's sentence, verbatim>", "frame": "stills/sheet.png", "observed": "<a concrete visible detail in that frame>" },
+    { "q": 7, "verdict": "<none or named>", "frame": "<a listed still>", "observed": "<what a skilled designer would have shown, or the detail that shows nothing is missing>" }
+  ]
+}
+```
+
+- `viewed` lists every stills file you opened with Read this round, paths relative to `<dir>`.
+- `verdict` is `yes` or `no` for questions 1–6, 8 and 9, and `none` or `named` for question 7.
+- `observed` is at least one sentence naming a concrete visible detail in `frame`; a bare yes or no
+  is refused, and so is the same sentence used for two answers.
+- `look` refuses a frame that is not in the latest stills set, and stamps the round with the SHA-256
+  of `stills/index.json` and of every listed frame.
+
+## Rounds
+
+Rounds share one counter with the renders, 1 to 3.
+
+- **Round 1** is always a stills round: render with `--stills-only`, look, and record `weakestBeat`
+  and `change`, then make that change before the full render.
+- A `no` on questions 1, 2, 3, 5 or 6, a `yes` on 4, 8 or 9, or a `named` question 7 needs another
+  round: fix it, render again, look again.
+- There are at most 3 rounds. After round 3, deliver with the open items stated plainly.
+
+## Done
+
+Done needs all of:
+
+- a valid treatment;
+- gate PASS;
+- at least 2 look rounds: round 1 on a stills-only render with a `change`, then a last round;
+- the last round stamped with the stills manifest of the final full render (`look` after the render,
+  never before);
+- the last round's `viewed` covering the poster, the contact sheet, every beat still and every
+  transition strip, each of them opened with the Read tool in this session;
+- the last round free of revise answers, or round 3 with its open items said in the reply.
+
+The Stop hook checks every item and holds the turn with a named reason. A missing, unreadable or
+outdated `treatment.json` or `look.json` is a named reason, never a pass.
+
+## Never downgrade to pass
+
+Do not answer a gate failure by shortening the film, removing a beat, removing the subject device,
+switching `sound.mode` to `none`, switching `path` to `type`, or deleting effects. Fix the cause
+instead: a scrim behind the text, a larger size, a placement inside the safe area, slower timing,
+seeded randomness. The done-check compares the final treatment with the first valid one and records
+`downgraded` when `durationSec` dropped by more than 20 %, the subject covers fewer beats, the sound
+became `none` without a user request, or the path moved from stage to type. The reply must say so.
+
+## Reply
+
+Keep the activation line where it is; below it there is no second banner and no emoji. Plain words,
+no internal names: one line on the defaults chosen; a label on every invention and on generated
+sound; one plain line on what was checked (flash safety, legibility, the frames looked at); where the
+copy lives and the one command that re-renders it; and any downgraded item or open look item.

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

@@ -0,0 +1,65 @@
+# Runtime, pre-warm and BLOCKED states
+
+## What is installed where
+
+| Piece | Where | Installed by |
+| --- | --- | --- |
+| Engine code, GLSL passes, scenes, bundled fonts | this skill directory (the plugin) | the LitClaude package |
+| opentype.js 2.0.0 (pinned in `engine/package-lock.json`) | `<cache>/node-<lockdigest>-<platform>-<arch>/` | `litclaude-ai motion-runtime install` (`npm ci --omit=dev --ignore-scripts`) |
+| Galmuri9, MesloLGS NF and their licence files | `<cache>/fonts/` (pinned URL, sha256-verified) | same command |
+| Pretendard Regular / Bold | `../lit-pptx/fonts/pretendard/` (reused by path, hash-checked) | the package |
+| librosa venv (Tier 2, optional) | `<cache>/audio-<digest>/` from `engine/audio/requirements.lock` with `pip install --require-hashes --only-binary=:all:` | `litclaude-ai motion-runtime install --audio` |
+| Word-timing models (Tier 3, optional) | not in this release | `--word-timing` prints the size and pins, then stops |
+| Chrome, ffmpeg, img2webp | host tools, never bundled | the user |
+
+`<cache>` is `$LITCLAUDE_MOTION_RUNTIME`, otherwise `${XDG_CACHE_HOME:-~/.cache}/litclaude/motion-runtime`.
+
+## Pre-warm, never first use
+
+The cache is written only by `litclaude-ai motion-runtime install`; `litclaude-ai install` (and the
+global npm postinstall, which runs it) attempts the same pre-warm and prints one receipt line if it
+fails, without failing the install. A Claude Code marketplace install runs no lifecycle step, so
+there the explicit command is the pre-warm. A render session only reads the cache: it never runs
+npm, pip or a download, because a sandboxed session usually has no network or no write access
+outside the workspace, and a half-finished install would look like a broken engine.
+
+`litclaude-ai doctor` (and `npm run doctor` in a checkout) prints the five probes: Chrome,
+ffmpeg with the preview encoder rung, the WebGL2 renderer from a real headless probe, the software-GL
+or unknown-renderer warning, and the pre-warm state naming anything missing and the fix command.
+`litclaude-ai motion-runtime status` prints the pre-warm state alone.
+
+## Exit codes
+
+| Exit | Name | Meaning | Fix |
+| --- | --- | --- | --- |
+| 0 | OK | the mode finished; for `make`, the gate passed | — |
+| 10 | BLOCKED_NO_CHROME | Chrome is missing or cannot launch headless; the message carries the launcher's first error line | install Chrome or set `CHROME_PATH` |
+| 11 | BLOCKED_NO_WEBGL2 | Chrome runs but no flag rung gives a WebGL2 context, not even SwiftShader | GPU drivers; nothing can render without WebGL2 |
+| 12 | BLOCKED_NO_FFMPEG_FOR_VIDEO | ffmpeg missing; stills and sheet were still written | install ffmpeg |
+| 13 | GATE_FAIL_QA | the gate (or the pre-flight gate) failed; see `gate-report.txt` | fix the named rule; next round |
+| 14 | BLOCKED_DEPS_NOT_PREWARMED | engine dependencies (or Tier-3 models) missing from the cache | `litclaude-ai motion-runtime install` outside the session |
+| 15 | BLOCKED_FONT_FETCH | a required font is missing or its sha256 differs | same command |
+
+Each state names its real cause. A sandbox that refuses `listen` is not a blocked state: frames are
+pulled over CDP from the same readback buffer, and the report names that egress.
+
+## Chrome flags (MO-A-51)
+
+Tried in order, each counting only if a page gets WebGL2: macOS `--use-angle=metal
+--enable-gpu-rasterization --ignore-gpu-blocklist`; Linux `--use-angle=gl --enable-gpu-rasterization
+--ignore-gpu-blocklist`; Windows `--use-angle=d3d11 --enable-gpu-rasterization`; then the software rung
+`--use-angle=swiftshader --enable-unsafe-swiftshader`. Every rung adds the three anti-throttling
+flags. The rung that worked is recorded as `chromeFlags`. The Chrome profile lives in the run's own
+`.run/chrome/` directory and is removed when the render ends. Every launch also passes
+`--use-mock-keychain` and `--password-store=basic`, so Chrome never asks the OS keychain for its
+safe-storage item (on macOS a fresh profile would otherwise raise a keychain dialog).
+
+## Audio tiers
+
+- **Tier 1 (default):** text reading time on a 100 BPM grid (or the brief's `bpm`).
+- **Tier 2:** an audio file in the brief and a ready venv: librosa beat grid, cuts on detected
+  beats, audio muxed into the MP4. A missing venv, a venv whose pins changed, or a failed analysis
+  falls back to Tier 1 with the warning "audio analysis not prewarmed: run litclaude-ai
+  motion-runtime install --audio" (or the analysis error). It is never repaired in the session.
+- **Tier 3:** `--word-timing` only; exits 14 in this release. Never MMS_FA or madmom weights,
+  never aubio or essentia, at any tier.