@litfamily/litmuse 0.1.0 → 0.1.2

package/plugin/skills/lit-typographic-motion/recipes/hero-3d/expected.json

@@ -0,0 +1,69 @@
+{
+  "schema": "litmuse.motion-cover-recipe/v1",
+  "note": "The decoded gate row this recipe reached when it shipped (scripts/qa-cover-recipes.mjs re-renders it and fails when median d or moving leave +-15 %, seamLocal leaves TARGET or bytes pass 2 MiB). Measured 2026-10-25 on headless Chrome's GPU rung (ANGLE Metal, Apple M5 Pro) with three.js r170 and libwebp; 20 fps keeps every frame on the 50 ms gate grid.",
+  "row": {
+    "medianD": 0.002485,
+    "movingFrac": 1,
+    "longestStillSec": 0.05,
+    "spike": 3.684,
+    "seamLocal": 1.199,
+    "bytes": 1060856
+  },
+  "settings": {
+    "size": [
+      1000,
+      500
+    ],
+    "fps": 20,
+    "frames": 160,
+    "encode": {
+      "q": 94,
+      "edgeQ": 97,
+      "edgeFrames": 15,
+      "method": 4
+    }
+  },
+  "treatment": {
+    "mode": "cover",
+    "request": "A README motion cover for LitMuse with a product object that opens.",
+    "idea": "A case turns once and opens on its beat to show the lit core inside, beside a still name.",
+    "recipe": "hero-3d",
+    "recipeReason": "One object acting once per loop says what the project holds better than a type pattern.",
+    "hero": "A rounded case with a hinged lid and a lit core.",
+    "beat": "The lid opens, the core rises and settles, and the lid closes.",
+    "brandWord": "LITMUSE",
+    "motto": {
+      "text": "KEEP THE WORK LIT.",
+      "source": "project",
+      "from": "README.md"
+    },
+    "aspect": "2:1",
+    "loopSec": 8,
+    "fps": 20,
+    "layers": {
+      "slow": "The case turns exactly once per loop.",
+      "mid": "The camera breathes twice per loop.",
+      "beat": "The lid opens on the core and a ring runs out across the floor."
+    },
+    "system": {
+      "rule": "One hinge rule and one turn rule on one object.",
+      "copies": "One case, one core, one ring.",
+      "offset": "The ring trails the lid by a tenth of the loop."
+    },
+    "title": {
+      "box": [
+        0.05,
+        0.36,
+        0.43,
+        0.14
+      ],
+      "kind": "live"
+    },
+    "encode": {
+      "q": 94,
+      "edgeQ": 97,
+      "edgeFrames": 15
+    },
+    "ambition": "The object reads as a product in a studio and its beat lands once per loop."
+  }
+}

package/plugin/skills/lit-typographic-motion/recipes/hero-3d/index.html

@@ -0,0 +1,139 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<!-- Recipe D, hero 3D: one product object, lit in a small studio, acting its beat once per loop. A
+     worked example: a rounded case turns exactly once per loop (slow layer), the camera breathes twice
+     (mid layer), and once per loop the lid opens, a lit core rises and settles back and the lid closes,
+     while a ring runs out across the floor (the beat). The word sits still on the left. Drawn with the
+     pinned three.js build on the GPU rung (software when the GPU is missing). Replace the word, the
+     motto and the HERO block with the project's own object. -->
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/loop-kit.js"></script>
+<script type="importmap">{ "imports": { "three": "/lit/three/three.module.js", "three/addons/": "/lit/three/addons/" } }</script>
+<style>
+  html, body { margin: 0; width: 1200px; height: 600px; overflow: hidden; background: #0b0f16; }
+  canvas { position: absolute; left: 0; top: 0; width: 1200px; height: 600px; display: block; }
+</style>
+</head>
+<body>
+<canvas id="world"></canvas>
+<canvas id="type" width="2400" height="1200"></canvas>
+<script type="module">
+import * as THREE from "three";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import { RoundedBoxGeometry } from "three/addons/geometries/RoundedBoxGeometry.js";
+
+const { TAU, clamp, fract, ease } = LitLoop;
+const span = (a, b, t) => clamp((t - a) / (b - a));
+const C = { bg: "#0b0f16", ivory: "#f2efdf", dim: "#8b8f8f", orange: "#ff6337", shell: "#d9d4c4", inner: "#1a2230" };
+const W = 1200, H = 600;
+const AIM = { x: 860, y: 318 };
+
+// ---- the world: renderer, studio light, floor ----
+const glCanvas = document.getElementById("world");
+const renderer = new THREE.WebGLRenderer({ canvas: glCanvas, antialias: true, alpha: true, preserveDrawingBuffer: true });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(W, H, false);
+renderer.setClearColor(0x000000, 0);
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+const scene = new THREE.Scene();
+scene.environment = new THREE.PMREMGenerator(renderer).fromScene(new RoomEnvironment(), 0.04).texture;
+scene.environmentIntensity = 0.55;
+const cam = new THREE.PerspectiveCamera(30, W / H, 0.1, 60);
+cam.setViewOffset(W, H, W / 2 - AIM.x, H / 2 - AIM.y, W, H);
+const key = new THREE.DirectionalLight(0xffffff, 2.4);
+key.position.set(-3, 6, 4);
+key.castShadow = true;
+key.shadow.mapSize.set(2048, 2048);
+key.shadow.radius = 5;
+key.shadow.bias = -0.0004;
+key.shadow.normalBias = 0.03;
+key.shadow.camera.left = -4; key.shadow.camera.right = 4; key.shadow.camera.top = 4; key.shadow.camera.bottom = -4;
+const rim = new THREE.DirectionalLight(0xffb08f, 1.1);
+rim.position.set(4, 2.5, -5);
+scene.add(key, rim);
+const floor = new THREE.Mesh(new THREE.PlaneGeometry(30, 30), new THREE.ShadowMaterial({ opacity: 0.35 }));
+floor.rotation.x = -Math.PI / 2;
+floor.receiveShadow = true;
+scene.add(floor);
+const ring = new THREE.Mesh(new THREE.RingGeometry(0.98, 1, 128), new THREE.MeshBasicMaterial({ color: C.orange, transparent: true, opacity: 0 }));
+ring.rotation.x = -Math.PI / 2;
+ring.position.y = 0.002;
+scene.add(ring);
+
+// ---- HERO: the product object (a case with a hinged lid and a lit core) ----
+const shell = new THREE.MeshPhysicalMaterial({ color: C.shell, roughness: 0.32, metalness: 0.05, clearcoat: 0.6, clearcoatRoughness: 0.2 });
+const inner = new THREE.MeshStandardMaterial({ color: C.inner, roughness: 0.8 });
+const HERO = new THREE.Group();
+const base = new THREE.Mesh(new RoundedBoxGeometry(1.6, 0.62, 1.1, 6, 0.12), shell);
+base.position.y = 0.31;
+const well = new THREE.Mesh(new RoundedBoxGeometry(1.38, 0.5, 0.88, 4, 0.08), inner);
+well.position.y = 0.4;
+const hinge = new THREE.Group();
+hinge.position.set(0, 0.64, -0.55);
+const lid = new THREE.Mesh(new RoundedBoxGeometry(1.6, 0.16, 1.1, 6, 0.07), shell);
+lid.position.set(0, 0.08, 0.55);
+hinge.add(lid);
+const coreMat = new THREE.MeshStandardMaterial({ color: C.orange, emissive: C.orange, emissiveIntensity: 0, roughness: 0.35 });
+const core = new THREE.Mesh(new THREE.IcosahedronGeometry(0.24, 3), coreMat);
+const glow = new THREE.PointLight(C.orange, 0, 4, 2);
+core.add(glow);
+for (const m of [base, lid, core]) m.castShadow = true;
+base.receiveShadow = true;
+HERO.add(base, well, hinge, core);
+scene.add(HERO);
+
+// The beat: open 0.28-0.44, hold, close 0.62-0.78; zero at both ends, so the loop closes.
+const openAt = (t) => ease.smooth(span(0.28, 0.44, t)) * (1 - ease.smooth(span(0.62, 0.78, t)));
+
+function drawWorld(t) {
+  HERO.rotation.y = -0.5 + TAU * t;
+  const open = openAt(t);
+  hinge.rotation.x = -1.45 * open;
+  const rise = ease.outBack(span(0.36, 0.5, t)) * (1 - ease.smooth(span(0.58, 0.7, t)));
+  core.position.y = 0.42 + 0.6 * rise;
+  core.rotation.y = TAU * 2 * t;
+  coreMat.emissiveIntensity = 1.1 * open;
+  glow.intensity = 3 * open;
+  const wave = ease.outCubic(span(0.38, 0.72, t));
+  ring.scale.setScalar(0.9 + 1.3 * wave);
+  ring.material.opacity = 0.55 * open * (1 - wave);
+  const breathe = Math.sin(TAU * 2 * t);
+  cam.position.set(5.8 * Math.sin(0.35), 2.3 + 0.12 * breathe, 5.8 * Math.cos(0.35));
+  cam.lookAt(0, 0.62 + 0.04 * breathe, 0);
+  renderer.render(scene, cam);
+}
+
+// ---- the word, set once ----
+const ctx = document.getElementById("type").getContext("2d");
+ctx.scale(2, 2);
+function drawType(mask) {
+  ctx.clearRect(0, 0, W, H);
+  if (mask) { ctx.fillStyle = "#000"; ctx.fillRect(0, 0, W, H); }
+  ctx.textBaseline = "alphabetic";
+  ctx.fillStyle = mask ? "#fff" : C.ivory;
+  ctx.font = '800 84px "JetBrains Mono"';
+  ctx.fillText("LITMUSE", 70, 292);
+  if (mask) return;
+  ctx.font = '500 18px "JetBrains Mono"';
+  ctx.fillStyle = C.dim;
+  let mx = 74;
+  for (const ch of "KEEP THE WORK ") { ctx.fillText(ch, mx, 338); mx += 19.6; }
+  ctx.fillStyle = C.orange;
+  ctx.font = '700 18px "JetBrains Mono"';
+  for (const ch of "LIT.") { ctx.fillText(ch, mx, 338); mx += 19.6; }
+}
+
+window.renderFrame = (t, o = {}) => {
+  glCanvas.style.visibility = o.mask ? "hidden" : "visible";
+  if (!o.mask) drawWorld(fract(t));
+  drawType(Boolean(o.mask));
+};
+document.fonts.load('800 84px "JetBrains Mono"').then(() => document.fonts.load('500 18px "JetBrains Mono"')).then(() => { window.renderFrame(0); window.ready = true; });
+</script>
+</body>
+</html>

package/plugin/skills/lit-typographic-motion/references/depth.md

@@ -0,0 +1,122 @@
+# Depth: the 3D route
+
+Read this when the treatment's subject is a `depth3d` device (`depth: "3d"`), or when a cover takes
+the `hero-3d` recipe. A drawn 3D object is the right subject when the film is about a thing that has
+a back and an inside: a product that turns, opens, unfolds or is assembled. A flat diagram, a chart or
+type does not need it; keep those on the 2D page.
+
+## What the renderer gives you
+
+- **A pinned three.js.** The skill ships three.js r170 (npm `three@0.170.0`, MIT) in
+  `engine/vendor/three/`: the unminified `three.module.js` plus two addons,
+  `environments/RoomEnvironment.js` and `geometries/RoundedBoxGeometry.js`. The renderer serves them at
+  `/lit/three/`; a page imports them through an import map:
+
+  ```html
+  <script type="importmap">{ "imports": { "three": "/lit/three/three.module.js", "three/addons/": "/lit/three/addons/" } }</script>
+  <script type="module">
+    import * as THREE from "three";
+    import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+  </script>
+  ```
+
+  Any other path under `/lit/three/` is refused as a missing file, and the network rules still hold:
+  never load three.js, a model or a texture from a CDN. The file hashes and the licence are in
+  `engine/THIRD_PARTY_NOTICES`.
+- **The GPU rung.** A `depth: 3d` film and a `hero-3d` cover start Chrome on the platform's GPU rung
+  (ANGLE on Metal on macOS, GL on Linux, D3D11 on Windows), with GPU rasterization of the page
+  itself still off. The renderer records the WebGL renderer string, and the gate's WebGL line names
+  the rung and the renderer. The same determinism replay runs as on the software rung: a fresh
+  browser on the same rung must reproduce the sampled frames pixel for pixel, or the render stops with
+  exit 18. On an Apple M-series Mac the 3D test page and the `hero-3d` cover replayed identically.
+- **A labelled fallback.** When the GPU rung cannot start, or starts without WebGL, the render
+  reopens on the software rung (SwiftShader), adds a warning to the report and the manifest naming
+  the reason, and records `rung: "software"`. The film still renders, more slowly. Say in the reply
+  that it rendered without the GPU. Only when neither rung has WebGL is it exit 11.
+
+The rung is chosen from the treatment (`depth`) or the cover recipe, never by the page.
+
+## The scaffold's world
+
+`motion.mjs scaffold` on a `depth: 3d` treatment adds, on top of the 2D shots:
+
+- `<canvas id="world">` behind every shot's section, so the type stays DOM text the QA can read;
+- one renderer for the whole film (alpha, `preserveDrawingBuffer`, pixel ratio 1, ACES tone mapping,
+  soft shadows), a `RoomEnvironment` for reflections, a key light with a biased shadow, a hemisphere
+  light in the style's colours and a shadow-only floor;
+- `HERO`, a group that holds the protagonist from the first frame to the last;
+- `aim(layout)`, which offsets the camera so the world origin lands on the centre of the shot's subject
+  zone; a `hero` layout shot therefore fills the frame and a `split` shot keeps the object on its side;
+- `WORLD[i](s, hero, cam, t)`, one function per shot that poses the hero, the camera and anything else
+  as a function of the shot (`s.p`, `s.local`, `s.enter(...)`).
+
+Build the protagonist once, in `HERO`, and only pose it per shot: that is what makes it the same
+object across the film. For a named product, start from its real logo and screens: a fetched logo or
+screenshot goes on a plane or a face of the object as a texture (`TextureLoader` on the file under
+`stage/assets/`); a simple logo shape can be traced into a `THREE.Shape` and given depth with
+`ExtrudeGeometry`.
+
+## Craft and the gate
+
+- **Turn slowly.** A full turn takes the loop (a cover) or a whole shot (a film). Fast spins, a flicker
+  of specular highlights and shadow acne all read as flashes and fail MO-C-03.
+- **Bias the shadow.** On a turning object set `shadow.bias` about -0.0004 and `shadow.normalBias`
+  about 0.03; without them the self-shadow flickers frame to frame.
+- **Ease every open and close.** A lid, a drawer or an exploded view eases in and out (`ease.smooth`),
+  holds, and returns; the move is the beat, so it happens once, where the treatment's story puts it.
+- **Keep the type in the DOM.** Copy stays in the shot's type zone as HTML text over the canvas;
+  text drawn inside the 3D scene is invisible to the QA unless registered with `LitStage.text`.
+- **Mind the dead air.** A small object on a large empty ground is `DEAD-AIR`; frame it with the
+  `hero` layout or move the camera in.
+- **Covers at 20 fps.** The cover gate measures on a 50 ms grid; at 25 fps a smooth turn lands two
+  frames on one step at the seam (FLOOR), at 20 fps every step is one frame (TARGET). Encode at q94:
+  smooth light surfaces blotch at the default q86.
+
+## Camera moves and the flash audit
+
+A rich film moves its camera in at least half its shots, and the flash audit stays exactly as it is.
+When a move fails MO-C-03, keep the move and change what it passes over: slow the light change (a
+highlight that sweeps over 0.5 s or more, not a frame), lower the contrast of the detail behind the
+move, add motion blur (the Blender rung renders it; on the GPU rung average 4-8 sub-frame poses), or cut
+instead of whipping. Removing the camera move is a downgrade.
+
+## The Blender rung (`render3d: "blender"`)
+
+For path-traced light (bevels that catch it, soft global illumination, depth of field, motion blur) a
+3D film can render its world in Blender with Cycles. The page then shows the rendered plate and keeps
+its type, labels and 2D layers in the DOM over it.
+
+Take this rung when the request asks for high-quality, cinematic or photoreal 3D (고퀄리티, 고품질,
+시네마틱, 실사, cinematic, photoreal, high-quality, Blender) and Blender is installed: `scaffold` prints
+`BLENDER:` with the path when both hold. On an Apple M-series GPU a full hero scene rendered at 8-10 s
+per 1080p frame at 160 samples, so a 13 s plate (390 frames) takes about an hour. Settle the scene on
+the preview stills first, since a fix after the final means rendering the plate again, and build the
+page's panels while it renders.
+
+1. Set `depth: 3d`, a `depth3d` subject and `render3d: "blender"`.
+2. Write `stage/scene.py`, a Blender Python scene. It runs inside the bundled runner with `bpy`,
+   `math`, `Vector` and `lit` in scope; times are film seconds and the plate starts at frame 1:
+   `lit.camera(location, target, lens, dof=(distance, fstop))`, `lit.area_light(name, location, target,
+   power, size, color)`, `lit.world(color, strength)`, `lit.material(name, color, roughness, metallic,
+   emission, strength)`, `lit.rounded_box(name, size, radius, segments, material, location)`,
+   `lit.image_card(name, path, width, location)` (a fetched product image as a card) and
+   `lit.key(obj, prop, t, value)`. The scene must set a camera. The command line sets size, samples,
+   device, fps and frames; the scene sets everything else.
+3. `motion.mjs blender --out <dir>` renders preview stills at the beat midpoints (50 %, 40 samples) into
+   `stage/plate-preview/`. Open them, compare them with any reference frames the user gave, and fix
+   `scene.py` before the final.
+4. `motion.mjs blender --out <dir> --final` renders the plate (full size, 160 samples, motion blur,
+   30 fps, `stage/plate/000001.png ...`) detached with a progress file; it can take most of an hour.
+   It writes `plate.json`, which lists every frame by name and size with the Blender version, device and
+   samples. Listed plate frames are not counted as page rasters; any other frame sequence is still a
+   flipbook (exit 17).
+5. On the page, `const show = LitStage.plate({ parent, count, fps: 30 })` returns `show(t)`; call it from
+   `render(t)`. The page renders on the software rung, and the stage refuses to start (exit 17) when the
+   plate is missing or does not cover the film.
+
+Blender is found from `LITMUSE_BLENDER` (used only if it exists), the macOS app
+(`/Applications/Blender.app/Contents/MacOS/Blender`) or `blender` on PATH, and runs as `blender -b
+--factory-startup -P runner.py -- ...`, on Metal on Apple silicon, another GPU backend next, the CPU
+last; the receipt says which. Without Blender the command renders nothing and prints `FALLBACK`: set
+`render3d` to `three`, build the world in three.js on the GPU rung, and say so in the reply. The report
+and manifest name the plate (Blender version, Cycles device, samples).

package/plugin/skills/lit-typographic-motion/references/sound.md

@@ -1,28 +1,67 @@
 # Sound
 
-Films have sound unless the user said otherwise. The treatment's `sound` object (`{ mode, plan, palette,
-file }`) plans it on both paths, the renderer muxes the track the plan names, and after the encode it
-decodes the film's audio stream and gates it. The generated bed is synthesized by LitMuse's own code from
-the treatment: no sample library, model or package is downloaded for it, and the same treatment always
-produces the same bytes.
+Films have sound unless the user said otherwise. The treatment's `sound` object (`{ mode, plan, genre?,
+palette?, events?, file? }`) plans it on both paths, the renderer muxes the track the plan names, and after
+the encode it decodes the film's audio stream and gates it. The score and the generated bed are synthesized
+by LitMuse's own code from the treatment: no sample library, model or package is downloaded for either, no
+melody is borrowed, and the same treatment always produces the same bytes.
 
 ## Choosing a mode
 
 | `sound.mode` | Track | Use it when |
 | --- | --- | --- |
-| `generated` | A bed built from the treatment: a tempo grid, a pulse, a pad chord per beat, and the accents the beats ask for | The default under a bare `lit`, on either path |
+| `score` | A layered score built for this film: drums, bass, chords, lead, arrangement FX and the on-screen events as separate stems, mixed and mastered | The default under a bare `lit` and for every rich film, on either path |
+| `generated` | One of the style's preset beds: a pad chord progression with a pulse and the accents the beats ask for | Minimal films only (`register: minimal`) |
 | `supplied` | The user's file at `sound.file` (relative to the output folder), padded or trimmed to the film | The user handed over a track |
 | `authored` | A WAV you wrote into the stage folder, named by `sound.file` | The plan needs sound the bed cannot make; the file must sit inside `<dir>/stage/` |
 | `none` | No audio stream | The request asks for silence (무음, 소리 없이, silent, muted, no music …) or the `channel` plays muted by design |
 
 A supplied or authored track is always muxed, whatever the state of the optional analysis tier below.
-The reply calls a generated bed "a generated music bed" in plain words and names a supplied track by its
-file name. Switching to `none` to get past a failing check is a downgrade: the done-check records it and the
-reply has to admit it.
-
-## The generated bed's palette
+The reply calls the track "an original score generated for this film" (or "a generated music bed" for a
+minimal film) in plain words and names a supplied track by its file name. Switching to `none` to get past a
+failing check is a downgrade: the done-check records it and the reply has to admit it.
+
+## The score
+
+The score is produced like a house track from the film itself, so no two films share one.
+
+- **Genre.** `house` (120–126 BPM, four-on-the-floor), `tech-house` (124–128, rolling bass), `deep-house`
+  (118–122, pads, light swing) or `garage` (130–134, broken kick, heavy swing). The style picks one
+  (swiss-signal house, terminalcore tech-house, tidal deep-house, paper garage); `sound.genre` names
+  another when the film asks for it. Launch and hero films stay in house or tech-house.
+- **Key, tempo, progression.** Seeded from the request, idea, turn, protagonist and beats: one of twelve
+  keys, major or minor, a tempo inside the genre's band, one progression per mode, the last bar home.
+- **Arrangement from the beats.** The shots before `story.beat` are intro and build; the drop lands on the
+  turn, on a downbeat; with three or more shots after the turn the first is a break and the rest drop again;
+  the last shot is the outro. Risers run into every change (strongest into the drop), an impact lands on it,
+  a downlifter follows, and a reverse swell breathes into the other changes, with the kick out for the half
+  bar before the drop and a snare roll into it.
+- **Stems.** `kick`, `clap`, `hats`, `perc`, `bass` (sub and line), `chords` (stab and pad), `lead` (a motif
+  off the key's pentatonic), `fx` (risers, impacts, downlifters, reverse swells) and `events`, each its own
+  pattern in its own buffer.
+- **Mix.** Per-stem gain and pan, a high-pass on everything but kick and bass, bass/chords/lead ducked under
+  the kick (the sidechain depth is measured and reported in dB), reverb and tempo-delay sends, bus
+  compression, then the shared master stage (−16 LUFS, peak under −2 dBFS).
+
+Write `sound.plan` as the producer's brief (where the drop lands, where it breaks) and put the cue words
+in the beats' `sound` fields. `motion.mjs sound` writes `sound/score.wav`, every stem and both returns under
+`sound/stems/`, and `sound-cues.json` with genre, key, tempo, progression, sections, FX, stem levels,
+sidechain depth, bus settings and every cue.
+
+## Palettes (minimal films)
+
+A minimal film's generated bed takes one of its style's beds exactly (the validator refuses anything
+else); the first is the default and the other two let two films in one style differ:
+
+| Style | Default bed | Alternatives |
+| --- | --- | --- |
+| `swiss-signal` | glass, A minor, 104 | pulse-synth, D minor, 112; soft-keys, C major, 96 |
+| `tidal` | felt-strings, D major, 84 | glass, F# minor, 76; soft-keys, Bb major, 72 |
+| `terminalcore` | pulse-synth, E minor, 120 | glass, B minor, 132; pulse-synth, A minor, 100 |
+| `paper` | soft-keys, F major, 96 | felt-strings, G major, 88; glass, C major, 108 |
 
-A generated bed needs `sound.palette`:
+Pick the bed for the film's mood and pace: a slower or tenderer film the slower bed, a launch the
+brighter one. `sound.palette` is:
 
 ```json
 { "timbre": "<timbre>", "key": "<pitch class>", "mode": "<major or minor>", "tempo": "<60-160>" }
@@ -61,6 +100,24 @@ The bed adds an accent only where a beat's `sound` text asks for one. It reads t
 A beat that names none of these gets pad and pulse only. The cut times come from the beats on the stage
 path and from the brief's shots on the type path.
 
+## Events
+
+Cue words tie accents to cuts. Events tie sounds to what moves inside a shot: a latch clicks when the lid
+opens, a card lands, a cursor types, a progress bar completes. A score or generated bed on the stage path
+lists them in `sound.events`:
+
+```json
+"events": [{ "t": 6.42, "on": "the lid clicks open", "kind": "tap" }]
+```
+
+- `t`: the second the event happens on screen, read from the page's own timing, never guessed from the beat;
+- `on`: what happens at that frame, as a viewer would see it;
+- `kind`: `tap` (a short click with a pitched body), `hit` (the cut hit), `whoosh` (air ending on the event)
+  or `chime` (two notes of the key: something completes).
+
+At least two events, and at least half of them 0.1 s or more away from every cut, so the sound follows the
+picture rather than only the edit. An event never snaps to a cut: it sounds at its own `t`.
+
 `<dir>/sound-cues.json` records each cue with `kind`, `t` in seconds, `beatIndex`, `target` (the boundary or
 cut it serves) and `delta` (`t - target`), alongside the timbre, key, tempo, loudness, peak, sample count
 and the bed's SHA-256. Look question 6 ("does the sound follow the cuts?") is answered from this file: every
@@ -102,10 +159,11 @@ the field named.
 node "$SKILL_ROOT/scripts/motion.mjs" sound --out <dir>
 ```
 
-This reads `<dir>/treatment.json` and writes `<dir>/sound/bed.wav` and `<dir>/sound-cues.json`, so the cue
-deltas can be checked before any frame is captured. For a supplied, authored or silent plan it only reports
-what the render will do. The full render rebuilds the bed itself at the film's real frame count and cut
-times, so the muxed bed always fits the final cut.
+This reads `<dir>/treatment.json` and writes the score (`<dir>/sound/score.wav` with its stems) or a
+minimal film's bed (`<dir>/sound/bed.wav`), plus `<dir>/sound-cues.json`, so the track can be heard and its
+cues checked before a render. For a supplied, authored or silent plan it only reports what the render will
+do. The full render rebuilds the track at the film's exact frame count and cut times, so the muxed track
+always matches the film sample for sample. Two builds from the same treatment give the same bytes.
 
 ## The optional analysis tier
 

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

@@ -3,7 +3,10 @@
 Load this once the treatment says `path: stage`. On this path the film is a web page you write, and the
 LitMuse renderer turns it into frames: it serves the page to a headless Chrome on a private origin,
 drives a virtual clock from zero, captures every frame in order, then encodes, replays and gates the
-result. You draw everything the treatment promised, the subject first. The kit described below supplies
+result. You draw everything the treatment promised, the subject first. The house style gives the frame
+(palette, type roles, layout zones, motion tokens, hand-offs), served as `/lit/style.css` and
+`/lit/style.js`. Start every page from `motion.mjs scaffold --out <dir>`, which writes the treatment's
+structure for you; fill its `DRAW` functions with the drawing. The kit described below supplies
 timing and reveal primitives and nothing pictorial, so no two stage films start from the same template.
 
 ## The page contract
@@ -12,10 +15,14 @@ The page lives at `<dir>/stage/index.html`, next to the local files it uses (SVG
 CSS, WAV). Only that folder is served, under the origin `http://lit.stage`; a symlink that resolves
 outside it is a contract error.
 
-Two routes come from the renderer itself and are always available:
+Four routes come from the renderer itself and are always available:
 
 - `<link rel="stylesheet" href="/lit/fonts.css">` declares the verified faces (table below).
 - `<script src="/lit/stage-kit.js"></script>` defines the global `LitStage`.
+- `<link rel="stylesheet" href="/lit/style.css">` and `<script src="/lit/style.js"></script>` serve the
+  film's house style for its format: custom properties, the type-role and colour classes, `window.LitStyle`
+  (tokens and pixel zones) and `window.LitTimeline` (the treatment's shots). Set copy with the classes;
+  the gate checks the rendered result either way.
 
 The page hands the renderer its spec with `LitStage.define({ width, height, fps, duration, render })`, or
 by assigning the same object to `window.litStage`. `define` checks the spec as soon as it is called:
@@ -193,9 +200,11 @@ node "$SKILL_ROOT/scripts/motion.mjs" stage --out <dir> --round 2
 ```
 
 The stills-only round writes `<dir>/stills/`: one PNG per beat midpoint, one transition strip per cut (the
-frames 6 before, at and 6 after the cut, side by side at half size), a 12-frame contact sheet, and
-`stills/index.json`. Nothing is encoded. Open those PNGs with `read_file` and record the round as
-`references/look.md` describes before the full render.
+frames 6 before, at and 6 after the cut, side by side at half size), a 12-frame contact sheet,
+`stills/board.png` with `stills/check.json`, and `stills/index.json`. Nothing is encoded. The board round
+also runs the board check, the gate's text and style rules on the board frames, and exits 13 naming each
+failed rule. Open the board and those PNGs with `read_file` and record the round as `references/look.md`
+describes before the full render.
 
 The full render captures the master, encodes the MP4 (with the planned sound muxed), builds the preview
 WebP or GIF, the poster and the reduced-motion still, runs the determinism replay and the text QA in
@@ -203,6 +212,21 @@ parallel, and writes `gate-report.txt`, `manifest.json` and `render.jsonl`. It r
 phase to `<dir>/.run/progress.json`. If the `bash` call times out, run the same command again: it attaches
 to the render already running and returns its result. Never cut the film short to finish sooner.
 
+## The 3D route
+
+When the treatment says `depth: 3d`, the subject is drawn as a three.js world (`references/depth.md`).
+The scaffold page already carries the shape: an import map onto the vendored build at `/lit/three/`, a
+full-frame canvas behind the shots, one persistent protagonist group `HERO`, and one `WORLD` function per
+shot that poses the hero, the camera and anything else as a function of the shot's progress. The renderer
+serves the pinned build and its few addons; pages import them through the import map, never from a URL.
+A 3D film asks for the GPU rung; the software rung is the fallback, slower, with the same frames.
+
+A path-traced look with Blender installed takes the offline rung instead (`render3d: blender`): write the
+world in `stage/scene.py`, render preview stills with `motion.mjs blender --out <dir>`, then the plate with
+`--final` into `stage/plate/`, and show it under HTML type and labels with `LitStage.plate()`. The plate
+frames are listed by name and size in `stage/plate/plate.json`; the scan trusts them and holds everything
+else to the raster limits.
+
 ## The stage gate
 
 `gate-report.txt` ends with `QA gate: PASS` or lists the failed rule ids. The stage rules are: