@litfamily/lithermes 1.0.7 → 1.0.9

package/assets/lithermes-plugin/skills/lit-typographic-motion/references/stage.md

@@ -0,0 +1,261 @@
+# Stage path
+
+The stage path is for every film that shows things: a drawn subject, shapes,
+diagrams, charts, illustration or interface, and every 9:16 film. You author a
+page; this skill's renderer captures it frame by frame on a virtual clock,
+encodes it with the pinned encode, muxes the sound and runs the gate. Every
+frame passes through that renderer. A hand-encoded film (a PIL frame loop, a
+raw ffmpeg filter graph, a screen recording, a raster flipbook) is not the
+deliverable.
+
+## What you write
+
+- `DIR/treatment.json` (`treatment.md`) with `path: stage`.
+- `DIR/stage/index.html` and its local assets: SVG, PNG, JPG, WebP, JS, CSS,
+  JSON and WAV files inside `DIR/stage/`.
+
+Never install, download or copy a third-party library into the stage dir. Use
+the kit below and your own code. Rasters are textures and stills, never a frame
+sequence: at most 24 raster images and 8 MB in total; 10 or more rasters of the
+same size (a flipbook), or any animated GIF, APNG or WebP, is exit 17.
+
+Put all on-screen copy in one `COPY` object at the top of `stage/index.html`,
+so the copy is easy to find and edit:
+
+```text
+const COPY = { title: "<line>", steps: ["<line>", "<line>"], close: "<line>" };
+```
+
+## The page contract
+
+The page loads the kit and the fonts from the renderer's own routes, and then
+declares the film:
+
+```text
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/stage-kit.js"></script>
+<script>
+  LitStage.define({ width: 1920, height: 1080, fps: 60, duration: <seconds>, render(t) { /* draw the frame at t */ } });
+</script>
+```
+
+- `width` and `height` equal the treatment's format: 1920×1080 for 16:9,
+  1080×1920 for 9:16. `duration` is the treatment's `durationSec`; the render
+  must land within ±10 % of it.
+- `fps` is 60. Use 30 only when the treatment says so.
+- `render(t)` draws the frame at time `t` in seconds. It may be omitted when
+  the page animates only with CSS or the Web Animations API.
+- Setting `window.litStage` to the same object is equivalent to calling
+  `LitStage.define`.
+
+The page 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 one virtual clock.
+
+Forbidden, each exit 17 naming the element or API: `<video>`, `<audio>`,
+`<iframe>`, `<object>`, `<embed>`, `<frame>`; `new Audio()`, `AudioContext`,
+`OfflineAudioContext`; `Worker`, `SharedWorker`, service workers. `WebSocket`,
+`WebTransport` and `RTCPeerConnection` are network requests: exit 19. Sound
+belongs in the treatment, not in the page.
+
+Network: the page is served from a synthetic origin, `http://lit.stage/`,
+without a listening socket. Any request outside it fails the run with exit 19,
+and so does an absolute `http(s)://` or protocol-relative URL, or a preconnect
+or prefetch link, anywhere in the stage files.
+
+### Fonts
+
+`/lit/fonts.css` declares this product's verified faces with
+`font-display: block`, served from the pre-warmed cache and the reused lit-pptx
+Pretendard pair: `Pretendard` (400, 700), `Archivo` (500, 700, 900 at
+`font-stretch` 75 %, 100 %, 125 %), `Galmuri9`, `VT323`, `Silkscreen` (400,
+700) and `MesloLGS NF`. Use Pretendard for Hangul. Any other family falls back
+to a system face; the QA reports it and fails it on copy.
+
+### Text the QA can read
+
+- HTML and SVG text is found automatically. Mark text that is part of a drawn
+  subject (a label on a drawn jar, a number on a drawn clock) as decor:
+  `LitStage.text(el, { decor: true })`. Decor text is exempt from title-safe
+  and reading-floor checks, may not carry a copy line, and may not exceed 25 %
+  of the visible text area.
+- Canvas and WebGL text is invisible to the QA unless you register it every
+  frame you draw it: `LitStage.text({ content, x, y, w, h })`. Unregistered
+  canvas text is reported as "canvas text not measured".
+
+## The kit
+
+`/lit/stage-kit.js` is this skill's own code: motion primitives only, no
+scenes, no objects, no layouts, no copy. `window.LitStage` holds:
+
+- **Eases.** `LitStage.ease.outCubic(p)` and the rest of the named set
+  (`linear`, `inSine`/`outSine`/`inOutSine`, `inQuad`…`inOutQuart`,
+  `inExpo`/`outExpo`/`inOutExpo`, `inBack`/`outBack`/`inOutBack`), plus
+  `LitStage.bezier(x1, y1, x2, y2)` for a CSS-style cubic-bezier.
+
+  ```text
+  const lift = LitStage.bezier(0.2, 0.8, 0.2, 1)(p);
+  ```
+
+- **Spring.** An analytic damped spring, a pure function of time:
+
+  ```text
+  const s = LitStage.spring({ from: 0, to: 1, stiffness: 180, damping: 18 });
+  el.style.transform = `scale(${s(t - 1.5)})`;
+  ```
+
+- **Keyframes.** `LitStage.kf(t, keys)` interpolates numbers or number arrays,
+  with an optional ease per segment:
+
+  ```text
+  const [x, y] = LitStage.kf(t, [{ t: 0, v: [0, 40] }, { t: 1.2, v: [320, 0], ease: "outCubic" }]);
+  ```
+
+- **Timing.** `LitStage.at(t, start, dur, ease)` returns the eased progress of
+  a window, clamped to 0–1. `LitStage.stagger(i, { each, from })` returns the
+  start offset of item `i`. `LitStage.seq(t, [d0, d1, ...])` returns
+  `{ index, p }` for back-to-back segments.
+
+  ```text
+  items.forEach((el, i) => { el.style.opacity = LitStage.at(t, 2 + LitStage.stagger(i, { each: 0.08 }), 0.4, "outQuad"); });
+  ```
+
+- **Seeded randomness.** `LitStage.rand(seed)` returns a deterministic
+  generator; `Math.random` is also seeded from the treatment by the renderer.
+
+  ```text
+  const r = LitStage.rand(7); const dots = Array.from({ length: 40 }, () => [r() * 1920, r() * 1080]);
+  ```
+
+- **Splitting text.** `LitStage.splitText(el, { by: "grapheme" | "word" })`
+  wraps each grapheme, or each word (어절 for Hangul), in a span and returns
+  them. It uses `Intl.Segmenter`, so a Hangul syllable is never split.
+
+  ```text
+  LitStage.splitText(title, { by: "word" }).forEach((w, i) => w.style.opacity = LitStage.at(t, i * 0.12, 0.3));
+  ```
+
+- **Path draw.** `LitStage.drawPath(pathEl, p)` reveals an SVG path from its
+  start by stroke dash.
+
+  ```text
+  LitStage.drawPath(outline, LitStage.at(t, 0.5, 1.6, "inOutSine"));
+  ```
+
+- **Morph.** `LitStage.morph(fromD, toD)` returns `p => d` for two
+  single-subpath shapes: both are normalized to cubics, resampled by arc length
+  and aligned at the best rotation. Multi-subpath morphs are not supported;
+  split them into single paths.
+
+  ```text
+  const m = LitStage.morph(bud.getAttribute("d"), bloom.getAttribute("d")); shape.setAttribute("d", m(p));
+  ```
+
+- **Masks and clips.** `LitStage.clipInset(el, p, "left" | "right" | "top" |
+  "bottom")` wipes an element in; `LitStage.clipCircle(el, p, cx, cy)` opens
+  an iris; `LitStage.maskWipe(el, p, angleDeg, softPx)` sweeps a soft gradient
+  mask.
+
+  ```text
+  LitStage.clipCircle(scene2, LitStage.at(t, 6, 0.8, "inOutCubic"), "50%", "60%");
+  ```
+
+- **Colour.** `LitStage.mix("#0f3b4c", "#f2c14e", p)` returns an `rgb()`
+  string.
+
+- **Text registration.** `LitStage.text(el, { decor: true })` and
+  `LitStage.text({ content, x, y, w, h })`, above.
+
+## How the capture works
+
+The renderer serves the page to a software-rendered Chrome (SwiftShader, CPU
+raster, no GPU rung), so any difference between two captures is a page leak,
+not a driver. An init script replaces `Date`, `performance.now`, `setTimeout`,
+`setInterval`, `requestAnimationFrame`, `requestIdleCallback`,
+`document.timeline.currentTime` and `Math.random` with a virtual clock and a
+seeded generator.
+
+Before frame 0 it loads every face in `fonts.css` and decodes every image.
+For each frame `f` it sets `t = f / fps` (computed, never accumulated), seeks
+every running animation to its own time, runs due timers and animation-frame
+callbacks, calls `render(t)`, pauses and records any animation that appeared,
+waits for fonts and images, lets Chrome paint twice, and captures exactly
+`width × height` pixels. The pixels go straight into the pinned H.264 encode.
+
+What this means for you:
+
+- Drive motion from `t`, CSS or WAAPI. Never from wall-clock time.
+- `performance.timeOrigin` and `crypto.getRandomValues` are not virtualized.
+  A frame that depends on them differs between two captures: exit 18.
+- A CSS transition started at `t` runs on the virtual clock like any other
+  animation; a `finished.then(...)` chain continues on it.
+
+A full render records per-frame timing (p50, p95, total) in the manifest.
+Long films take minutes: give the command a timeout of at least 600 s, or run
+it with `--detach` and poll `DIR/.run/progress.json` and `DIR/run-state.json`.
+Never shorten the film to save render time.
+
+## Determinism
+
+After the film, the renderer re-captures 8 to 16 sample frames (frame 0, the
+last frame, the first frame of every beat, then beat midpoints) in a fresh
+Chrome that replays the clock from 0, and compares the SHA-256 of the decoded
+pixels. A mismatch is exit 18, naming the frame and the first differing region.
+
+## Text QA
+
+A separate replay reads every visible text run (the nearest `LitStage.text`
+element, otherwise the nearest block; `::before` and `::after` content; and
+registered canvas text). At every beat midpoint, plus two settled frames per
+beat, it captures the frame, hides only the text fill, captures again, and
+takes the difference as the ink. Contrast uses the worst pairing of median ink
+against the dark and light ends of the ground in the text box grown by a quarter
+of the cap height, so a scrim behind type must reach past that margin. Only
+settled text is judged: its box moved less than 2 px since the previous probe
+and its opacity is at least 0.95. The samples sit at every beat's midpoint and
+at 35 % and 80 % of it; runs are also read every 1/10 s for the reading floor
+and the copy-found check. A run counts as visible at opacity 0.6 or more, on
+screen after clipping, with at least 12 ink pixels at a sample. Registered
+canvas text cannot be hidden, so its ink is the pixels in its box that stand
+apart from the box's edge.
+
+| Check | Copy text | Decor text |
+|---|---|---|
+| Contrast (3.0 large, 4.5 body; large is at least 3 % of the short side) | FAIL | WARN |
+| Title-safe (inside the central 90 % of the frame) | FAIL | exempt |
+| Reading floor (on screen at least as long as the line takes to read) | FAIL | exempt |
+
+Also checked:
+
+- Every `copy.lines` entry must appear on screen: exit 17 quoting the line.
+- WARN, and the look must answer it: text that equals or contains the request,
+  the idea, a file name or an internal term; canvas text not measured; a
+  sample where something other than text moved; less than half of the beat
+  midpoints showing any non-text image.
+- Fonts outside the verified set: WARN, FAIL on copy.
+
+## Stage gate
+
+`$M gate --out DIR` re-measures the exports and the sound and rewrites the
+report without touching `manifest.json`, so a recorded look round stays valid
+and the viewed count carries over.
+
+| Rule | What fails |
+|---|---|
+| MO-C-03 | more than 3 general or 3 red flashes in any 1 s window (the grid turns for 9:16) |
+| MO-C-09 | a sample frame that differs in a fresh replay (exit 18) |
+| MO-C-10 | a film that is not exactly 1920×1080 or 1080×1920 as the format says |
+| MO-C-11 | tags other than yuv420p, bt709, tv, or under 30 fps |
+| MO-C-12 | a length more than 10 % from `durationSec` |
+| MO-C-13 | a preview over 3 MB or a poster over 1 MB |
+| MO-C-14 | a reduced-motion still (the final beat's midpoint) with no ink |
+| MO-D-03 | an empty, near-black run longer than 2.4 s (1 s more at either end of the film) |
+| text rules | the Text QA table above |
+| sound | a missing stream, a length more than 0.1 s off, a peak over −0.5 dBFS, or (generated beds) a silence over 1.5 s in the first 3 s |
+
+## Effects and determinism
+
+`filter: blur()`, `backdrop-filter`, `mix-blend-mode`, `box-shadow`, SVG
+`feGaussianBlur`, Canvas2D `shadowBlur` and WebGL shaders all capture the same
+way twice on the software renderer. A WebGL context needs the software GL;
+without it the stage exits 11.

package/assets/lithermes-plugin/skills/lit-typographic-motion/references/style-bibles.md

@@ -0,0 +1,122 @@
+# Style bibles
+
+On the type path the treatment (`treatment.md`) already fixes the idea, the
+audience, the arc, the palette and the sound. The style bible adds the look
+decisions the type engine will not make by itself. Write it in your own words
+for this film. Under bare `lit` do not ask the user; choose, then label each
+choice as a default in the final reply.
+
+## The style-bible template
+
+Fill every field. A field left open is decided by the engine's preset default.
+The right-hand column says what a useful answer contains; it is not an answer
+to copy.
+
+| Field | What to write | A useful answer names |
+|---|---|---|
+| Idea | The treatment's `idea`, unchanged | <the treatment's one sentence> |
+| Preset | `swiss-signal`, `terminalcore` or `tidal`, and why | <the preset> because <what in this film calls for it> |
+| Palette | The preset palette, or one stated swap inside its rules | <the swap and the brief key that sets it> |
+| Voices | Which text is display, body, machine | <which line takes which voice> |
+| Motion tone | The preset's named tokens you rely on | <entrance, hold and cut tokens> |
+| Shot list | One line per shot: scene id, text, what moves | <scene id>: <line>, <what moves> |
+| Accent | The one moment that gets the accent, or none | <the line index and why> |
+| Anti-slop | Two or three things this film must not do | <habits this film avoids> |
+| Originality | The visual idea that belongs to this film only | <a device drawn from the subject's specifics> |
+
+The shot list maps directly to the brief JSON: `text` is the list of lines in
+order and `scenes` is the optional list of scene ids in the same order.
+
+## Auto-pick (MO-B-00)
+
+The engine reads the brief's `text`, `mood` and `topic` and takes the first row
+that matches. Latin keywords match as whole words only; Korean keywords match
+only at the start of a token, so a keyword never fires inside a longer word it
+merely ends. An explicit `"style"` in the brief always wins over this table.
+The report labels a style you chose as `agent default`; it says
+`user-specified` only when the user's own request named that style.
+
+| Brief mentions | Preset |
+|---|---|
+| 터미널, 해커 / terminal, hacker, CRT | `terminalcore` |
+| 물결, 파도, 잔잔한, 흐름 / gradient, wave, tide, calm | `tidal` |
+| anything else | `swiss-signal` |
+
+`system`, `status` and a bare `flow` are deliberately not keywords: they appear
+in payment-system, design-system and workflow briefs that have nothing to do
+with a terminal or a tide. The manifest records the pick and the reason, and the
+gate report prints them on its `preset:` line.
+
+## swiss-signal (MO-B-01)
+
+Print precision on paper. The ground is bone `#E9EBE4`; type is ink `#0C0E13`
+(16:1 either way round). One signal hue, teal `#0F7A82`, is for large type (32 px
+and up, or 25 px bold), rules and bars, never small body copy: it measures about
+4.2:1 on bone. One accent, `#D9A441`, belongs to a single moment and never to
+text; the engine shows it as a small square at the title's rule for at most two
+beats and never on more than 10% of the film's frames. Graphite `#4B5058` is
+reserved for non-text marks.
+
+Voices: Archivo for display type (fetched width instances 75/100/125 at weights
+500/700/900; 500 stands in for 400 because that is what the pinned set ships),
+PretendardGOV Regular or Bold for any Hangul, MesloLGS NF for annotations.
+Motion tokens: `slam` (180 ms on the proven deceleration curve, entrance scale
+0.96 to 1, never from zero), `hold` for the reading time, `snap-cut` at the beat.
+The title slam steps Latin width from 125 to 100 halfway through its landing;
+Hangul never takes that step. Passes: `swiss-grid` hairline rules as the layout
+backbone, then `dither` at low strength as a printed grain. Grid: 12 columns,
+24 px gutter, 96 px margin, 8 px baseline, compositions left-anchored rather than
+centred.
+
+Anti-slop: centred fade-in words as the only move; one ease for every beat;
+glitch without a reason; any rainbow or second signal hue; bloom on anything but
+the signal; a hold so long it reads as a stall.
+
+## terminalcore (MO-B-02)
+
+A terminal interface, not a code-rain poster. Background navy `#05070A`, window
+panel `#0C1116`, one signal hue per film: phosphor green `#39FF6A` by default or
+electric blue `#2FB6FF` (`"signalHue": "blue"`), never both. Both clear 4.5:1 on
+navy and panel, so body-size readouts are safe; grey `#7C8B93` (5.7:1) is for
+chrome labels.
+
+Voices: Galmuri9 for Hangul (always at a multiple of its 9 px grid, 45 px or
+more on screen), VT323 for Latin display, MesloLGS NF for status readouts,
+Silkscreen for window-chrome labels only. Galmuri and VT323 never share one line
+cell for cell. Motion tokens: `type-in` at 22 characters per second with no ease
+(Hangul appears a whole 어절 at a time), `boot-flicker` for the first 250 ms of the
+film, bounded by the CRT flicker cap, and `hard-cut` on the beat. Passes, in
+order: `terminal-ui` (window chrome, meters, caret drawn as a Canvas2D layer),
+`crt` (scanlines, curvature, seeded triad grain, capped flicker, phosphor
+persistence over the two previous frames of the same shot), `dither` (Bayer4,
+2 px cells), `glitch` (at most one scheduled hit per shot of 1.8 s or longer).
+
+Anti-slop: falling code rain; neon purple-cyan haze; continuous glitch; both
+signal hues in one film; pixel type too small for its grid.
+
+## tidal (MO-B-03)
+
+Slow water. Background indigo `#0E1420` under a moving two-stop gradient of deep
+teal `#124559` and violet `#4C3B6E`; type off-white `#E8ECEF` (15:1 on indigo,
+8:1 or better on either stop, so no scrim is needed). Coral `#E07856` is a rare
+accent for one moment only.
+
+Voices: Archivo at a calmer weight (700) for display, PretendardGOV for Hangul,
+Meslo for small notes. Motion tokens: `drift` (opacity over up to 1.2 s and a
+24 px rise over up to 2.4 s, both on the in-out sine token, matched to the
+gradient's flow speed) and `surge-punch`, a gradient brightening with attack
+0.15 s and decay 0.25 s that lands on each shot's opening. Passes: `tidal-gradient`
+(domain-warped flow seeded per shot), `swiss-grid` for layout rules with guides
+off, and `glitch` as rare punctuation: at most one hit in the whole film, on the
+longest middle shot, at 0.5 hits per second or less.
+
+Anti-slop: a hue-cycling rainbow; bloom on the gradient; glitch as texture; type
+riding a flow so fast it blurs under motion sampling.
+
+## Originality
+
+The pattern transfers, never the values of the film this engine came from: one
+small named palette, one signal, one rare accent, three voices. Invent this
+brief's own visual idea per shot. Do not reuse scene names, motifs or copy from
+any source film. Keep example subjects neutral and fictional unless the user
+supplied them.

package/assets/lithermes-plugin/skills/lit-typographic-motion/references/treatment.md

@@ -0,0 +1,164 @@
+# Treatment
+
+Every film starts here. Write `treatment.json` in the run's output directory
+before any render. The validator runs before every `stage` and `run` call,
+stills-only included, and exits 16 (`BLOCKED_TREATMENT_INVALID`) naming the
+first field that breaks a rule. Nothing renders until it passes.
+
+The treatment is a director's plan: what the film is about, who watches it and
+where, how it is shaped over time, what is drawn on screen, how it sounds, and
+what would make it excellent. Write it from the request, not from the example
+below.
+
+## Load order
+
+1. This file, always first.
+2. Set `path`. Then load only that path's references:
+   - `stage`: `stage.md` (authoring contract, kit, capture, QA), then
+     `craft-loop.md` (look rounds and done).
+   - `type`: `engine-contract.md`, `style-bibles.md`, `type-craft.md`, then
+     `craft-loop.md`.
+3. `runtime.md` only when a command exits 10, 11, 12, 14 or 15.
+
+The stage path never needs a type-path reference.
+
+## Path rule
+
+- `type` when the words themselves are the film: the user asked for kinetic
+  type, a lyric or quote video, a title sequence or typographic motion, or
+  supplied words with no other subject. Type films are 16:9.
+- `stage` for every other film, including any film that needs shapes, drawn
+  objects, diagrams or imagery beyond type. Supplied words on the stage path
+  become stage copy.
+- A 9:16 film always takes the stage path.
+
+The router may add a line "Type-led cue found: ...". It is a hint that the
+request contains a type compound, an explicit lyric or kinetic-type ask, or a
+quoted phrase. It never decides the path; you do, from the whole request.
+
+## Fields
+
+Normalization, used by several rules: NFC, lowercase, then remove whitespace,
+punctuation and symbols. Before any comparison against `request`, every quoted
+span is removed from it.
+
+| Field | Rule |
+|---|---|
+| `request` | The user's words, verbatim. |
+| `genre` | `announcement`, `brand-mood`, `event`, `explainer`, `motion-graphics`, `type-led` or `other`. |
+| `path`, `pathReason` | `type` or `stage`, per the path rule. `type` needs `copy.source: user` or a type-led cue in `request`, and `format: 16:9`. |
+| `idea` | One sentence: the film's own idea. It must not share a normalized run of min(10, half the normalized request length) characters with the request. |
+| `audience`, `channel` | Who watches, and where it plays. |
+| `format`, `formatReason` | `16:9` (1920×1080) or `9:16` (1080×1920), with a reason tied to `channel`. |
+| `durationSec` | 4 to 90. Unless the user asked for a length, `announcement`, `event`, `explainer` and `motion-graphics` run at least 10 s. |
+| `beats[]` | `{t0, t1, purpose, onScreen, motion, sound}` each. They cover 0 to `durationSec` with no gap over 0.25 s, every beat lasts at least 1.2 s, and there are at least as many beats as the genre's arc has stages. |
+| `subject` | `{name, source: user or invented, specifics[]}`. When the request names no specific subject, invent one: a name plus at least 2 concrete specifics (what it is or does, for whom, one distinctive detail). |
+| `visualDevices[]` | `{kind, role: subject, support or texture, beats[]}`, where `beats` lists beat indexes from 0. Kinds: `illustration`, `diagram`, `chart`, `icon`, `shape`, `path`, `mask`, `depth3d`, `particles`, `grid`, `gradient`, `photo-texture`. |
+| `typePlan` | `{faces[], hierarchy, maxWordsOnScreen}`. Faces come from this product's verified set: Pretendard, Archivo, Galmuri9, VT323, Silkscreen, MesloLGS NF. |
+| `palette[]` | 3 to 6 `{color: "#rrggbb", role}` entries. |
+| `sound` | `{mode, plan, palette}`; `file` for `supplied` and `authored`. |
+| `copy` | `{source: user or invented, lines[]}`. |
+| `inventions[]` | Every invented part. Required when the subject or the copy is invented, and it must contain `subject.name` when the subject is invented. |
+| `ambition` | One or two sentences, in craft terms, on what would make this film excellent for this request. |
+
+### Stage-path device rules
+
+- At least one `role: subject` device. It is a drawn depiction of what the film
+  is about, not a background, and its beats cover at least half of
+  `durationSec`.
+- At least 2 distinct counting kinds. `grid`, `gradient`, `particles` and
+  `photo-texture` are always `texture` and never count.
+
+### Copy rules
+
+- `copy.source: user` when the user supplied the words. Every normalized line
+  must be a substring of the normalized request, quoted spans included. Keep
+  the user's words exactly; line breaks are yours.
+- `copy.source: invented` when the request supplies no film words. Write the
+  copy from `subject.specifics`, never from the request's wording: no invented
+  line may share the idea's substring limit with the request. List the copy in
+  `inventions[]`.
+- A line that could be pasted unchanged into a film about a different subject
+  is not copy yet. Name the specific thing.
+
+### Sound rules
+
+- `generated` is the default under bare `lit`, on both paths. The `sound`
+  subcommand builds a deterministic bed from the treatment: tempo, pulse and a
+  pad chord progression, plus accents only where a beat's `sound` field asks
+  (a hit on a cut, a rise into a change, a closing cadence). `sound.palette` is
+  one of `soft-mallet`, `warm-keys`, `glass-pulse` or `low-strings`; key and
+  tempo follow from the treatment, so two films rarely share a bed. The reply
+  labels the bed as generated.
+- `supplied`: the user's WAV, named in `sound.file`, relative to the output dir.
+- `authored`: a WAV you wrote into the stage dir (`stage/*.wav`).
+- `none` only when the user asked for silence, or when the channel plays muted
+  by design (say so in `channel`).
+
+Any supplied, authored or generated track is muxed on either path. It is
+padded or trimmed to the film with a 50 ms fade; it never shortens the film.
+
+## Genre arcs
+
+The arc sets the minimum number of beats. Length comes from the arc, never
+from a wish to be short.
+
+- **announcement:** hook → context → key moment → details → close.
+- **brand-mood:** motif → variation → peak → resolve.
+- **event:** hook → what, when, where → highlight → close.
+- **explainer:** question → steps → result → recap.
+- **motion-graphics:** opening motif → set piece → set piece → peak → resolve.
+- **type-led:** one breath per line, with emphasis and pause.
+- **other:** at least 3 beats with a clear opening, middle and close.
+
+## Craft rules
+
+- Show the subject; do not only name it. With the sound muted and every word hidden, the drawn subject alone should still suggest what the film is about.
+- Aim for professional motion-design craft in every film: varied transitions (match cuts, masks, morphs), rhythm locked to the sound, layered depth, clear hierarchy, deliberate easing. Every beat shows something new. Length comes from the arc; never shorten the film or merge beats to pass a check.
+
+## Placeholder example
+
+This shows the shape of every field. Its values are placeholders: the validator
+rejects any `<...>` value, and it rejects a treatment whose free-text values
+mostly equal this example's (`copiedExample`). Do not copy it; write your own.
+
+```json
+{
+  "request": "<the user's words, verbatim>",
+  "genre": "<one genre id>",
+  "path": "<type or stage>",
+  "pathReason": "<why this path fits>",
+  "idea": "<one sentence: the film's own idea>",
+  "audience": "<who watches>",
+  "channel": "<where it plays>",
+  "format": "<16:9 or 9:16>",
+  "formatReason": "<why this format suits the channel>",
+  "durationSec": "<4–90>",
+  "beats": [
+    { "t0": "<start s>", "t1": "<end s>", "purpose": "<arc stage>", "onScreen": "<what is drawn>", "motion": "<how it moves>", "sound": "<what the sound does here>" }
+  ],
+  "subject": { "name": "<a specific name>", "source": "<user or invented>", "specifics": ["<what it is or does>", "<for whom>", "<one distinctive detail>"] },
+  "visualDevices": [
+    { "kind": "<device kind>", "role": "<subject, support or texture>", "beats": ["<beat index>"] }
+  ],
+  "typePlan": { "faces": ["<verified face>"], "hierarchy": "<levels of type>", "maxWordsOnScreen": "<n>" },
+  "palette": [
+    { "color": "<#rrggbb>", "role": "<what this colour does>" }
+  ],
+  "sound": { "mode": "<generated, supplied, authored or none>", "plan": "<how the sound follows the arc>", "palette": "<timbre palette>" },
+  "copy": { "source": "<user or invented>", "lines": ["<line>"] },
+  "inventions": ["<every invented part>"],
+  "ambition": "<one or two sentences in craft terms>"
+}
+```
+
+## 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 type, a
+larger size, a new placement, different timing, seeded randomness. Or deliver
+with the failure stated. The done-check compares the final treatment with the
+first valid one and records `downgraded` when the duration dropped by more than
+20 %, there are fewer subject beats, sound became `none` without a user
+request, or the path went from stage to type. The reply must then say so.

package/assets/lithermes-plugin/skills/lit-typographic-motion/references/type-craft.md

@@ -0,0 +1,92 @@
+# Korean and Latin type craft
+
+The engine enforces most of these rules in code; this page is what to aim for
+when you write the brief and read the stills.
+
+## Fonts per voice
+
+| Voice | Latin | Hangul |
+|---|---|---|
+| display (swiss, tidal) | Archivo width instance 75/100/125 x weight 500/700/900 | PretendardGOV Bold (700) |
+| body (swiss, tidal) | Archivo 100 width | PretendardGOV Regular or Bold |
+| display and body (terminalcore) | VT323 | Galmuri9 |
+| machine | MesloLGS NF | PretendardGOV Regular (swiss, tidal) or Galmuri9 (terminalcore) |
+| chrome label (terminalcore) | Silkscreen | Galmuri9 |
+| stroke | EMS single-stroke SVG (Allure for signatures) | none; stroke text is Latin only |
+
+PretendardGOV Regular and Bold are this product's own lit-pptx pair, reused by
+path and checked against its recorded hashes. Hangul weight moves only between
+those two files. Every other font is fetched by the pre-warm from a pinned URL
+and checked by sha256 before a render may use it. Galmuri and Pretendard carry
+reserved names, so they are only ever used unmodified, never subset.
+
+## Script runs
+
+A line is split into Latin and Hangul runs. Digits, punctuation and spaces are
+not a script: they join the run on their left, or the run on their right when
+nothing precedes them. So `2026년` is one Hangul run and `LIT팀` is `LIT` plus
+`팀`. Each run takes its own font, and tracking or width motion applies to Latin
+runs only. A Hangul run is always untracked and never condensed, expanded or
+stepped through width instances, even inside a Latin line.
+
+## Kerning and split words
+
+The engine lays out a whole line once with the font's kerning, then places each
+piece of a split word at its glyph position inside that line. It never measures
+`text.slice(0, i)`, which silently drops the kern between the last drawn glyph
+and the next one. Karaoke words and list items all come from the whole-line
+layout.
+
+## Line breaks and 어절
+
+Korean lines break only at whitespace between 어절. A word too wide for the
+measure stays whole on its own line. Karaoke reveal steps and terminal type-in
+never show half a 어절.
+
+## Punctuation
+
+Display strings go through `smart()`: straight quotes become curly, leading
+elisions ('til, 'cause, '90s) get an apostrophe, `...` becomes `…`. Terminalcore
+keeps typewriter punctuation (`plain()`), because a terminal types straight
+quotes.
+
+## Tracking, line height, measure
+
+| Rule | Floor or range |
+|---|---|
+| Display tracking | not tighter than -0.04 em (the engine uses -0.02 em on Latin titles) |
+| Machine, body and label tracking | 0 or looser |
+| Two wrapped lines, Latin | line height >= 1.5 |
+| Two wrapped lines, Hangul or mixed | >= 1.6 |
+| Three or more lines | >= 1.4 (the engine uses 1.6) |
+| Latin paragraph card | 60-75 characters per line |
+| Korean paragraph card | 30-45 characters, advisory only |
+
+## Contrast
+
+Body type needs 4.5:1 against what is actually painted behind it; large type
+(32 px and up, or 25 px at weight 700 and up) needs 3:1. The gate measures the
+median of the glyph pixels under a mask eroded by 1 px against the 5th and 95th
+percentile of the background around the word, so very thin small strokes read
+lighter than their palette colour suggests. Give small annotations full ink or
+a larger size rather than a mid tint. Never fix contrast with an outline or a
+halo: move the word, change its colour inside the palette, or pick a calmer
+background moment.
+
+## Size floors
+
+- Galmuri9 renders on a 9 px grid: use multiples of 9 px and at least 45 px on
+  screen, or it blurs into its own strokes.
+- Hold small type at weight 400 or heavier; large Hangul slams use Bold, because
+  thin strokes break down under motion sampling.
+- Every glyph's ink stays inside the title-safe rectangle 96-1824 x 54-1026 at
+  1080p; non-type graphics stay inside 48-1872 x 27-1053.
+
+## Reading time
+
+Every unit holds at least its floor: 0.2 s per Hangul syllable plus one word per
+0.3 s (3.3 words/s), at least 0.9 s for a Latin line and 1.0 s for any line with
+Hangul, 0.5 s for a word shown alone, 0.35 s for a reveal step inside a line that
+stays visible, and never more than 17 Latin characters per second on a line. A
+4-어절 line of 14 syllables therefore needs 2.8 s; the generator gives it 3.5 s
+before snapping to the beat.