@litfamily/litmuse 0.1.0 → 0.1.2

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

@@ -0,0 +1,245 @@
+# Studio: house styles, shots, the board and the house file
+
+Read this for every film, after `treatment.md`. It is what makes two films of one request look like
+the same studio made them, and what lets the user see the film before the full render. Covers keep
+their own recipes (`cover.md`); everything here is for films on the stage and type paths.
+
+The rule behind every part below: a decision the model used to make again on each run is now data
+the page is built from, or a check the renderer runs. Prose that only asks for consistency does not
+produce it; data and checks do.
+
+## The flow
+
+1. **Style.** The treatment names one house style. The validator accepts only the style the rules
+   choose (below), so the same request always gets the same style.
+2. **Shots.** Each beat of the treatment is a shot with a `layout`, a `hero` move and a `transition`.
+   The layouts are one grid shared by every style; the style maps them to pixels per format.
+3. **Scaffold** (stage path). `motion.mjs scaffold --out <dir>` writes `stage/index.html` from the
+   treatment. Draw the subject of each shot in its `DRAW` function; keep the rest of the structure.
+4. **Board round** (round 1). `stage --round 1 --stills-only` (or `make ... --stills-only` on the type
+   path) writes the stills and `stills/board.png`, the storyboard. On the stage path it also runs the
+   board check, the text and style rules of the gate on the board frames, and exits 13 naming each
+   failed rule before any film is encoded.
+5. **Film.** The full render, with the style rules in its gate.
+6. **House.** A passed film records its style in `motion-house.json` beside the output folder; the next
+   film in that folder takes the same style unless the user names another.
+
+## Register: rich is the default
+
+Every film is maximal unless the request asks otherwise. `register` is `rich` by default and
+`minimal` only when the request asks for a calm, quiet, simple or minimal film (미니멀, 잔잔, 차분, 조용,
+심플, 절제, minimal, calm, quiet, simple, understated, sparse, serene). The validator refuses
+`minimal` without that ask and `rich` with it.
+
+A rich film fills its frame the way the reference studios do:
+
+- **A layered world** (`world.layers`, at least 3, back to front): what lives in the far ground, the
+  middle and the near ground of the film's place. Every shot shows at least two of them at once.
+- **Labelled parts** (`world.labels`, at least 6, at most 4 words each): the names a viewer reads on
+  the drawn parts, readouts, tabs and tags. A named product uses its real names. The text QA's
+  `TEXT-LABELS` rule fails when fewer than 75 % of them reach the screen, or when half the beat
+  midpoints show fewer than 3 readable text runs.
+- **A filled frame.** At each beat midpoint the text QA cuts the frame into 4 x 3 regions; `RICH-FILL`
+  fails when more than one shot leaves over 2 of the 12 empty (the end card may breathe). A 3D hero on a
+  dark floor does not fill a frame by itself: put the world's parts around it as panels in the DOM
+  (live counters, a log that scrolls, stage pills, a progress readout, the product's own screens at a
+  size that reads), the way a dense dashboard frame does.
+- **A moving camera** (`world.camera`, `[{beat, move}]`, in at least half the shots): push-in, truck,
+  crane, orbit, rack focus, parallax. A locked shot is not listed.
+- **Accents by role.** Besides its core palette each style has at least three accent colours, each
+  for one role (a state, a category, a path); a rich `palette` may add them, at most 14 entries.
+- **Decor text** (readouts, coordinates, part numbers) may fill up to 60 % of the text area.
+- **An authored score**: `sound.mode: score`, layered stems arranged on the film's beats (`sound.md`).
+- **Full 3D where the subject allows**: `depth: 3d`, and `render3d: blender` for path-traced light
+  when Blender is installed and the request asks for high-quality, cinematic or photoreal 3D
+  (`depth.md`); `scaffold` prints `BLENDER:` when both hold.
+
+A minimal film keeps the restraint of a single hero on an open ground: the core palette only, decor
+under 25 %, no world plan, and the style's preset beds (`sound.mode: generated`).
+
+The flash audit (MO-C-03) is the same in both registers. Density is met with slower light changes,
+lower-contrast detail behind a move, motion blur and cuts, never by locking the camera.
+
+## House styles
+
+A style is a file in `styles/<id>.json`: palette roles, faces per type role, a type scale per format,
+leading, motion tokens (eases, durations, staggers, a spring per object class, secondary and ambient
+travel, the hold push), the transitions it hands off with, its ground, its sound beds (a default and
+two alternatives, `sound.md`) and the defaults it never uses. Four ship:
+
+| Style | Look | Type | Hand-offs | Default bed |
+|---|---|---|---|---|
+| `swiss-signal` (default) | Ink ground, bone type, one teal signal, one amber moment | Archivo display and headline, Pretendard body, MesloLGS NF labels | cut, wipe, match, push | glass, A minor, 104 BPM |
+| `tidal` | Indigo ground with a slow teal-to-violet flow, off-white type, one coral moment | Archivo 700, Pretendard body | dissolve, match, wipe | felt-strings, D major, 84 BPM |
+| `terminalcore` | Navy terminal, phosphor type at typing speed, one signal hue, no easing | VT323 with Galmuri9 for Hangul, sizes on its 9 px grid | cut, wipe | pulse-synth, E minor, 120 BPM |
+| `paper` | Warm paper ground, near-black ink, terracotta signal, one blue moment, soft springs | Pretendard throughout, MesloLGS NF labels | cut, match, wipe, iris, push | soft-keys, F major, 96 BPM |
+
+`swiss-signal`, `tidal` and `terminalcore` are the type engine's presets too, so a style means the same
+palette on both paths. `paper` is stage-only.
+
+Type sizes per role (px):
+
+| Style | 16:9 display / headline / body / label | 9:16 display / headline / body / label |
+|---|---|---|
+| swiss-signal | 128 / 76 / 40 / 26 | 120 / 80 / 46 / 32 |
+| tidal | 116 / 72 / 40 / 26 | 112 / 76 / 46 / 32 |
+| terminalcore | 126 / 81 / 45 / 36 | 117 / 81 / 54 / 36 |
+| paper | 112 / 68 / 40 / 26 | 108 / 74 / 46 / 32 |
+
+`motion.mjs styles --out <dir> [--format 16:9|9:16]` renders the same demo film in every style and
+writes `<dir>/styles.png`, the four boards side by side. Show it when the user wants to choose a style,
+or asks what the films will look like.
+
+## Choosing the style
+
+In this order, first match wins; the validator refuses anything else and says which rule chose:
+
+1. The request names a style: its id (`swiss-signal`, `tidal`, `terminalcore`) or `paper style`
+   (`페이퍼`, `타이달`, `터미널코어`, `스위스 시그널` too).
+2. The project's house style (`motion-house.json` beside the output folder).
+3. A keyword in the request or the copy: terminal words (터미널, CRT, 해커, terminal, hacker) take
+   `terminalcore`; calm or wave words (물결, 파도, 잔잔한, 흐름, gradient, wave, tide, calm) take `tidal`;
+   warm or paper words (따뜻한, 밝은, 종이, 손그림, 포근한, 아기자기, warm, cozy, bright, paper, handmade,
+   hand-drawn) take `paper` on the stage path.
+4. The genre: an `explainer` takes `paper` (a warm, legible ground for diagrams and steps; on the type
+   path, where `paper` has no preset, the rule is skipped) and a `brand-mood` film takes `tidal`.
+5. Otherwise `swiss-signal`.
+
+The style fixes more than colour. On the stage path the treatment's `palette` may only list the style's
+colours (a rich film adds its role accents), `typePlan.faces` only its faces, and a minimal film's
+generated bed is one of the style's beds exactly. A score takes the style's genre unless `sound.genre`
+names another.
+On the type path the brief's `style` must equal the treatment's style or be left out.
+
+## Shots and layouts
+
+Each beat carries three shot fields on the stage path:
+
+| Field | Rule |
+|---|---|
+| `layout` | `title`, `split`, `split-alt`, `stage`, `full` or `hero` |
+| `hero` | The one move the eye follows in this shot, as a viewer would describe it |
+| `transition` | How the shot hands off: a word from the style's list; the last shot is `end` |
+| `lines` | Optional: the indices of the copy lines this shot shows (a `full` shot shows none) |
+
+The layouts, as `[x, y, w, h]` fractions of the frame:
+
+| Layout | 16:9 type zone | 16:9 subject zone | 9:16 type zone | 9:16 subject zone |
+|---|---|---|---|---|
+| `title` | 0.08, 0.20, 0.84, 0.60 | whole frame (backdrop) | 0.09, 0.26, 0.82, 0.48 | whole frame |
+| `split` | 0.08, 0.16, 0.36, 0.68 (left) | 0.48, 0.08, 0.46, 0.84 | 0.09, 0.08, 0.82, 0.26 (top) | 0.06, 0.36, 0.88, 0.56 |
+| `split-alt` | 0.56, 0.16, 0.36, 0.68 (right) | 0.06, 0.08, 0.46, 0.84 | 0.09, 0.66, 0.82, 0.26 (bottom) | 0.06, 0.06, 0.88, 0.56 |
+| `stage` | 0.08, 0.75, 0.84, 0.18 (caption band) | 0.06, 0.07, 0.88, 0.64 | 0.09, 0.79, 0.82, 0.13 | 0.06, 0.06, 0.88, 0.68 |
+| `full` | none: no copy | whole frame | none | whole frame |
+| `hero` | 0.08, 0.76, 0.84, 0.17 (low band) | 0.03, 0.03, 0.94, 0.94 | 0.09, 0.80, 0.82, 0.12 | 0.03, 0.03, 0.94, 0.94 |
+
+Choose layouts for the story: `title` for an opening or closing line over a backdrop, `split` and
+`split-alt` for a line beside the thing it is about (alternate them so the eye moves), `stage` when the
+drawing is the shot and the words are a caption, `full` when the picture must speak alone, `hero` when
+the protagonist fills the frame (a close-up, the turn, the product reveal) with one short line under
+it. Composition changes with the story: two adjacent shots never share a layout, and a film of four or
+more shots uses at least three layouts; the validator refuses a treatment that parks the eye. One hero
+move leads each shot and the eye follows it; in a rich film the world around it keeps working:
+secondary moves on the labelled parts travel 50-70 % as far and start 0.1-0.2 s later, the layers drift
+at their own depths, and ambient motion never stops. A minimal film keeps ambient motion under the
+style's ambient travel.
+
+## The page: style.css, style.js and the kit
+
+The renderer serves two files for the film's style and format:
+
+- `/lit/style.css`: custom properties (`--lit-ground`, `--lit-ink`, `--lit-muted`, `--lit-signal`,
+  `--lit-accent`, `--lit-line`, `--lit-surface`, the size steps), the body ground, the type-role classes
+  `.lit-display`, `.lit-headline`, `.lit-body`, `.lit-label` (face, size, weight, leading) and the colour
+  classes `.lit-ink`, `.lit-muted`, `.lit-signal`, `.lit-accent`, `.lit-knockout`.
+- `/lit/style.js`: `window.LitStyle` (the tokens, with the layout zones in pixels for this format) and
+  `window.LitTimeline` (the treatment's shots: `t0`, `t1`, `layout`, `transition`, plus fps and length).
+
+The kit reads them:
+
+- `LitStage.shot(t)` returns the shot at `t`: `index`, `beat`, `layout`, `transition`, `local` (seconds
+  into the shot), `length`, `p` (0..1), `enter(delay, dur)` (0 to 1 on the style's entrance ease) and
+  `exit(dur)` (0 to 1 over the shot's last `dur` seconds on its exit ease).
+- `LitStage.zone(layout, "type" | "subject")` returns `{ x, y, w, h }` in pixels;
+  `LitStage.place(el, layout, part)` positions an element there.
+- `LitStage.tokens()` returns the style's eases as functions (`enter`, `move`, `exit`), durations,
+  staggers, a spring per object class (`micro`, `panel`, `headline`, `subject`, `camera`, each a
+  function of seconds from 0 to 1), `secondary`, `ambient` and `push`.
+
+The page times every shot from `LitTimeline`, so the treatment, the page, the stills, the board, the
+sound cues and the gate read one timeline. Set copy with the classes (or the same values): the gate
+checks the result, not the class names.
+
+## Scaffold
+
+`motion.mjs scaffold --out <dir>` needs a valid stage treatment and writes `<dir>/stage/index.html`:
+the COPY block with every copy line, one `<section>` per shot with its type placed in the shot's type
+zone (first line headline, or display in a `title` shot; further lines body in the muted colour), an
+empty `<svg>` in the subject zone, entrances on the style's ease, the hand-off of each shot (wipe,
+iris, dissolve, push; match, morph and cut switch on the cut, so carry the matching shape yourself),
+and one `DRAW` function per shot. Fill the `DRAW` functions: they receive the shot (`s`), the shot's
+svg and `t`. Change the structure only for a reason the treatment states. The scaffold never replaces
+an existing page.
+
+## The board round
+
+Round 1 is the board round. A stills-only render writes the stills set and `stills/board.png`: one
+keyframe per shot with its number, time, layout and hand-off under it and its hero move in words, the
+shot's type zone dashed over the frame, and a header with the style, palette and the film's format,
+length and bed. On the stage path the same render runs the board check, the gate's text and style
+rules on the board frames, writes `stills/check.json` and prints the verdict on the board.
+
+- Exit 0: open the board and every still with read_file, record round 1 with its change, and render the
+  film.
+- Exit 13 `BOARD_CHECK_FAIL`: the message names each failed rule. Fix the page and render the board
+  again before the full render; a full render fails the same rules.
+
+The board is a deliverable. The reply names it, so the user can see what was built.
+
+## Style rules in the gate
+
+All FAIL, on the stage path, on the board round and the full render alike:
+
+| Rule | Fails when | Typical fix |
+|---|---|---|
+| `TEXT-OVERLAP` | Two visible text runs overlap by more than 8 % of the smaller box at a QA sample | Fewer lines per shot, the `split` layout, or let one line leave before the next arrives |
+| `TEXT-ON-STYLE` | Settled copy is in a colour outside the style's text roles, a face outside the style, or a size more than 4 % off the type scale | Use the type-role and colour classes |
+| `TEXT-ZONE` | Settled copy sits outside its shot's type zone (by more than 1.2 % of the frame), or any copy shows in a `full` shot | Shorter copy, a smaller role, or a layout with a larger type zone |
+| `TEXT-OVERLAP` (cut) | Text of the outgoing and the incoming shot overlaps during a hand-off: the QA samples every second frame within 0.4 s of each cut, and the failure is marked `(cut)` | Let the outgoing copy leave before the incoming copy arrives, or move the incoming copy to a different zone |
+| `FLAT-FRAME` (full render) | More than 1 s of frames whose 0.5-99.5 % luminance spread is under 0.02: an empty frame of any colour | Draw the shot; never leave a stub `DRAW` empty |
+| `DEAD-AIR` (full render) | More than 0.5 s in a row (0.4 s more allowed at the opening, 0.6 s more at the close) where under 2.5 % of the frame carries anything: a 48 px cell counts when its pixels vary (sd over 6) or differ from the ground by more than 16 levels | Keep the protagonist or the next shot's subject on screen through the hand-off; enter the next thing before the last one has gone |
+| `ASSET-USED` (named product) | `product.assets` lists real files and the page loads none of them | Show the real logo, screenshot or README image from `stage/assets/` |
+
+Non-copy text off the scale is a WARN; decor text (`text(el, { decor: true })`) is exempt. The cut
+samples check overlap only: copy in mid-transition is off its zone and scale by design.
+
+`FLAT-FRAME` catches a blank frame; `DEAD-AIR` catches the frame that is not blank but says nothing,
+one thin line or a lone label on an empty ground, held long enough to read as a stall.
+
+## Preview
+
+When the request asks for a preview or a storyboard first (미리보기, 스토리보드, 콘티, preview,
+storyboard), set `preview: true` in the treatment. The film is then done at the board: a board round
+whose check passed, looked at, with the board in the viewed list. The reply shows the board and says the
+film is not rendered yet; when the user says go, set `preview` to false and render the film. Without
+those words a bare `lit` still asks no questions and renders the film, and the reply still names the
+board.
+
+## The house file
+
+`motion-house.json` sits beside the output folder (the user's working directory):
+
+```json
+{ "schema": "litmuse.motion-house/v1", "style": "<style id>", "createdAt": "<time>", "films": [{ "dir": "<folder>", "style": "<style id>", "path": "<stage or type>", "format": "<16:9 or 9:16>", "durationSec": 0, "at": "<time>" }] }
+```
+
+The renderer writes it when a full render passes and nothing is withheld; the first film sets the
+house style and later films are appended. While it exists the validator holds new films in that folder
+to the house style; a request that names another style wins for that film and does not move the house
+style. To change the house style, edit `style` in the file or delete it.
+
+## What stays free
+
+The subject, the idea, the copy, the drawing, the hero moves and the arc stay the model's, with the
+treatment's concept rules (`treatment.md`). The studio fixes how a film looks and is built, never what
+it is about.

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

@@ -43,20 +43,27 @@ Once the path is set, load its references. Stage path: `references/stage.md`. Ty
 | Field | What the validator requires |
 | --- | --- |
 | `request` | Non-empty: the user's words, verbatim. |
-| `genre` | One of `announcement`, `brand-mood`, `event`, `explainer`, `motion-graphics`, `type-led`, `other`. |
+| `genre` | One of `announcement`, `brand-mood`, `event`, `explainer`, `motion-graphics`, `type-led`, `other`. A genre word in the request fixes it: 설명/원리 or explain for `explainer`, 출시/런칭/티저 or launch/teaser for `announcement`, 행사/공연/축제 or event/festival/concert for `event`; a type compound or a quoted span of two-plus words for `type-led`. The validator refuses a genre that contradicts the request's own word. |
 | `path`, `pathReason` | `type` or `stage` by the rule above, and a sentence on why. |
+| `style`, `register` | The house style id and `rich` (the default) or `minimal`. `references/studio.md` has the choosing order and the rich register; the validator holds the film to both. `minimal` only when the request asks for calm, quiet or minimal. |
 | `idea` | Exactly one sentence describing what the film does. It may not share a run of characters with the request (see Restatement). |
 | `audience`, `channel` | Who watches and where it plays. `channel` also matters for sound: a channel that plays muted by design is one of the two ways `sound.mode: none` is accepted. |
 | `format`, `formatReason` | `16:9` renders 1920×1080 and `9:16` renders 1080×1920. The reason ties the shape to the channel. |
-| `durationSec` | A number from 4 to 90. `announcement`, `event`, `explainer` and `motion-graphics` films run at least 10 s unless the request states a length (a number with 초, 분, s, sec, seconds, min or minutes). |
-| `fps` | Optional. 60 by default; 30 is the only other value. |
-| `beats[]` | Objects `{t0, t1, purpose, onScreen, motion, sound}`. The first starts within 0.25 s of zero, each following beat starts within 0.25 s of the previous end and never overlaps it, every beat lasts at least 1.2 s, and the last ends within 0.25 s of `durationSec`. The four text fields are non-empty and not placeholders. |
+| `durationSec` | A number from 4 to 90. A stated length (a number with 초, 분, s, sec, seconds, min or minutes) holds within 10 % of itself. Otherwise the genre sets the band: `announcement` 12–18, `brand-mood` 10–15, `event` 10–15, `explainer` 16–24, `motion-graphics` 12–18, `other` 10–15, `type-led` 4–8 s per line. `announcement`, `event`, `explainer` and `motion-graphics` run at least 10 s. |
+| `fps` | Optional. 60 by default; 30 only when the request asks for 30 fps. |
+| `preview` | Optional boolean. `true` only when the request asks for a preview or storyboard first; the film is then done at its board round (see Preview below). |
+| `beats[]` | Objects `{t0, t1, layout, hero, transition, purpose, onScreen, motion, sound}` on the stage path (`layout`/`hero`/`transition` per `references/studio.md`), `{t0, t1, purpose, onScreen, motion, sound}` on the type path. The first starts within 0.25 s of zero, each following beat starts within 0.25 s of the previous end and never overlaps it, every beat lasts at least 1.2 s, and the last ends within 0.25 s of `durationSec`. The text fields are non-empty and not placeholders. |
 | `posterBeat` | Optional beat index whose midpoint becomes the poster; the middle beat otherwise. |
+| `story` | `{expect, turn, beat, payoff}`: what the viewer expects, what happens instead, the index of the shot where the turn lands (after the opening, before the end), and what the ending gives. The turn must differ from the expectation. |
+| `protagonist` | Stage path only. `{name, kind, look, acts[]}` with `kind` `character` or `object`: the drawn thing that acts across the film, what it looks like on screen, and one act per shot (`{beat, action}`) covering at least half the film, including an act on the turn's shot. |
+| `product` | Required when the request links a product, repository or site. `{name, url, assets[]}` with each asset `{path, role, source, sha256}` under `stage/assets/`, or `{unreachable, reason}` when nothing could be fetched — then the film stops with exit 22 until the user supplies the files. Fetch first with `motion.mjs assets --out <dir> --url <link>`. `role` is one of `logo`, `wordmark`, `icon`, `photo`, `screenshot`, `ui`, `readme-image`. A `screen` device may only show an asset listed here. |
+| `depth`, `render3d` | `depth: 3d` with a `depth3d` subject device takes the 3D route (`references/depth.md`); `render3d` is `three` (the GPU rung, default) or `blender` (the offline Cycles rung, needs `stage/scene.py` and `motion.mjs blender --final`). |
 | `subject` | `{name, source, specifics[]}` with `source` `user` or `invented`. A user subject needs one concrete specific; an invented one needs two: what it is or does, for whom, and a detail nobody else has. |
 | `visualDevices[]` | `{kind, role, beats[]}`. Kinds: `illustration`, `diagram`, `chart`, `icon`, `shape`, `path`, `mask`, `depth3d`, `particles`, `grid`, `gradient`, `photo-texture`. Roles: `subject`, `support`, `texture`. `grid`, `gradient`, `particles` and `photo-texture` are always `texture`. `beats` lists valid beat indices. |
 | `typePlan` | `{faces[], hierarchy, maxWordsOnScreen, index?}`. Faces come from the verified set: `Pretendard`, `Archivo`, `VT323`, `Silkscreen`, `Galmuri9`, `MesloLGS NF`. `maxWordsOnScreen` is a positive integer. `index` is a boolean and is true only when the film should carry a running shot counter. |
-| `palette[]` | Three to six `{color, role}` entries; colours are `#rgb` or `#rrggbb`. |
-| `sound` | `{mode, plan, palette?, file?}`. Modes `generated`, `supplied`, `authored`, `none`; `references/sound.md` has the rules. A generated bed needs a valid `palette`; supplied and authored tracks need `file`. |
+| `palette[]` | On the stage path, the style's own colours (a rich film may add its role accents, at most 14 entries); on the type path, three to six `{color, role}` entries with `#rgb` or `#rrggbb` colours. |
+| `world` | Stage path, rich register only. `{layers[], labels[], camera[]}`: at least 3 depth layers back to front, at least 6 on-screen labels of at most 4 words each, and camera moves in at least half the beats. `references/studio.md` has the register. |
+| `sound` | `{mode, plan, palette?, events?, file?, genre?}`. Modes `score` (the default for rich films: a layered per-film score arranged on the beats), `generated` (a minimal film's bed, exactly one of the style's beds), `supplied`, `authored`, `none`; `references/sound.md` has the rules. `none` only when the request asks for silence or the channel plays muted. Stage films with `score` or `generated` list their on-screen sound events (`{t, on, kind}`, at least 2, half away from the cuts). |
 | `copy` | `{source, lines[]}` with at least one line. `user` lines must each be found inside the request after normalization; `invented` lines must not restate it. |
 | `inventions[]` | Strings. Required, and non-empty, whenever the subject or the copy is invented; it must contain the invented subject's name. |
 | `ambition` | One or two sentences, in craft terms, on what would make this particular film excellent. |
@@ -93,20 +100,29 @@ validator refuses it as written, and a treatment that echoes it is refused as `c
   "genre": "<genre>",
   "path": "<stage or type>",
   "pathReason": "<why this renderer>",
+  "style": "<house style id>",
+  "register": "<rich or minimal>",
   "idea": "<one sentence: what this film does>",
   "audience": "<who watches>",
   "channel": "<where it plays>",
   "format": "<16:9 or 9:16>",
   "formatReason": "<the channel's reason for that shape>",
   "durationSec": "<seconds from the arc>",
+  "preview": "<true only when the request asks for a preview first>",
   "beats": [
-    { "t0": "<start>", "t1": "<end>", "purpose": "<the beat's job in the arc>", "onScreen": "<what a viewer sees, drawn and written>", "motion": "<how it moves, how it cuts>", "sound": "<pad only, or a hit, rise or cadence>" }
+    { "t0": "<start>", "t1": "<end>", "layout": "<shot layout>", "hero": "<the move the eye follows>", "transition": "<hand-off, end on the last>", "purpose": "<the beat's job in the arc>", "onScreen": "<what a viewer sees, drawn and written>", "motion": "<how it moves, how it cuts>", "sound": "<pad only, or a hit, rise or cadence>" }
   ],
+  "story": { "expect": "<what the viewer expects>", "turn": "<what happens instead>", "beat": "<the shot where it lands>", "payoff": "<what the ending gives>" },
+  "protagonist": { "name": "<name>", "kind": "<character or object>", "look": "<what it looks like on screen>", "acts": [{ "beat": "<index>", "action": "<what it does, as seen>" }] },
   "subject": { "name": "<name>", "source": "<user or invented>", "specifics": ["<what it does and for whom>", "<the distinctive detail>"] },
+  "product": { "name": "<name>", "url": "<link>", "assets": [{ "path": "<stage/assets/ file>", "role": "<role>", "source": "<fetched or user>", "sha256": "<hash>" }] },
+  "depth": "<2d, or 3d with a depth3d subject>",
+  "render3d": "<three or blender>",
   "visualDevices": [{ "kind": "<kind>", "role": "<subject, support or texture>", "beats": ["<index>"] }],
   "typePlan": { "faces": ["<face>"], "hierarchy": "<what reads first, second, third>", "maxWordsOnScreen": "<n>" },
   "palette": [{ "color": "<#hex>", "role": "<what the colour does>" }],
-  "sound": { "mode": "<mode>", "plan": "<the sound's job>", "palette": { "timbre": "<timbre>", "key": "<pitch class>", "mode": "<major or minor>", "tempo": "<bpm>" } },
+  "world": { "layers": ["<what lives in the back, middle, front>"], "labels": ["<six on-screen names>"], "camera": [{ "beat": "<index>", "move": "<the move>" }] },
+  "sound": { "mode": "<mode>", "plan": "<the sound's job>", "palette": { "timbre": "<timbre>", "key": "<pitch class>", "mode": "<major or minor>", "tempo": "<bpm>" }, "events": [{ "t": "<second>", "on": "<what happens on screen>", "kind": "<tap, hit, whoosh or chime>" }] },
   "copy": { "source": "<user or invented>", "lines": ["<a line>"] },
   "inventions": ["<each invented part>"],
   "ambition": "<the craft bar for this film>"
@@ -150,6 +166,13 @@ show something the previous one did not.
 literally see, never a mood word. A beat's `sound` field is where accents are requested: write "hit on the
 cut", "rise into the reveal" or "cadence to close", and the bed places them (`references/sound.md`).
 
+## Preview
+
+When the request asks for a preview or a storyboard first (미리보기, 스토리보드, 콘티, preview,
+storyboard), set `preview: true`. The film is then done at its board: a stills-only render whose board
+check passed, looked at, with the board in the viewed list. The reply shows the board and says the film
+is not rendered yet; when the user says go, set `preview` back to false and render the film.
+
 ## Downgrades are recorded
 
 The first valid treatment of an output folder is saved to `.run/treatment.first.json`. When the done-check

package/plugin/skills/lit-typographic-motion/scripts/motion.mjs

@@ -5,7 +5,7 @@
 // WebGL2, 12 no ffmpeg for video, 13 QA gate FAIL, 14 runtime not pre-warmed, 15 font missing or
 // hash-mismatched, 16 treatment invalid, 17 stage contract, 18 stage nondeterministic, 19 stage
 // network request, 20 sound invalid (2 = usage).
-import { realpathSync } from "node:fs";
+import { realpathSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { EXIT, EXIT_NAME, CREDIT_LINE } from "../engine/core/constants.mjs";
@@ -13,21 +13,29 @@ import { EXIT, EXIT_NAME, CREDIT_LINE } from "../engine/core/constants.mjs";
 export const USAGE = `lit-typographic-motion render CLI (LitMuse)
 
 usage:
-  motion.mjs stage --out <dir> [--round N] [--stills-only]      stage path: renders the page in <dir>/stage/
+  motion.mjs styles --out <dir> [--format 16:9|9:16]              the house-style gallery: one demo board per style
+  motion.mjs assets --out <dir> --url <link> [--cover]            a named product's real logo, README images and words:
+                                                                  <dir>/stage/assets/ (cover/assets/), <dir>/product/, <dir>/product.json
+  motion.mjs scaffold --out <dir>                                 writes <dir>/stage/index.html from the treatment
+  motion.mjs stage --out <dir> [--round N] [--stills-only]      stage path: renders the page in <dir>/stage/;
+                                                                  --stills-only is the board round (storyboard + check)
   motion.mjs cover --out <dir> [--round N] [--window t0,t1]   cover mode: the seamless README loop in <dir>/cover/;
                                                                   --window re-renders only t0-0.5 s .. t1+0.5 s and sheets it
   motion.mjs cover-gate <cover.webp> [--frames d --frames2 d --masks d --title x,y,w,h] [--strict] [--json]
                                                                   the cover gate on a decoded cover file
   motion.mjs make  <brief.json> --out <dir> [--round N] [--stills-only] [--word-timing]
                                                                   type path: the typographic engine
-  motion.mjs sound --out <dir>                                    builds <dir>/sound/bed.wav from the treatment
+  motion.mjs blender --out <dir> [--final]                        the offline Blender rung (render3d: blender): preview stills of
+                                                                  <dir>/stage/scene.py, then with --final the plate in <dir>/stage/plate/
+  motion.mjs sound --out <dir>                                    builds the film's score (or a minimal film's bed) from the treatment
   motion.mjs look  --out <dir> --round N --answers <file>         records one look round in <dir>/look.json
                    (--blocked no-vision-tool when no image tool can be reached)
   motion.mjs gate  <dir>                                          reruns the full type-path gate on a render
   motion.mjs stills|sheet|video|perf <brief.json> --out <dir>     one type-path stage alone
 
 Every render reads <dir>/treatment.json first (exit 16 names the field). A render with --stills-only
-writes the beat stills, the transition strips and the contact sheet, then stops; the full render adds
+writes the beat stills, the transition strips, the contact sheet and the storyboard (stills/board.png),
+and on the stage path runs the board check (exit 13 when it fails), then stops; the full render adds
 the master, preview, poster, reduced-motion still, determinism re-check, sound and the gate. A
 flash-audit FAIL withholds every export in <dir>/withheld/. A cover render (treatment mode: cover)
 captures at 2x, encodes cover.webp and gates the decoded file; it exits 13 until every gate reaches
@@ -44,7 +52,7 @@ function parse(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (["--stills-only", "--word-timing", "--help", "-h", "--foreground", "--worker", "--strict", "--json"].includes(a)) args[a.replace(/^-+/u, "")] = true;
+    if (["--stills-only", "--word-timing", "--help", "-h", "--foreground", "--worker", "--strict", "--json", "--cover", "--final"].includes(a)) args[a.replace(/^-+/u, "")] = true;
     else if (a.startsWith("--")) {
       args[a.slice(2)] = argv[i + 1];
       i += 1;
@@ -65,10 +73,21 @@ export async function main(argv, { env = process.env, stdout = process.stdout, s
   const pipeline = await import("../engine/node/pipeline.mjs");
   try {
     let result;
-    if (["stage", "cover", "sound", "look"].includes(mode)) {
+    if (["stage", "cover", "sound", "look", "scaffold", "styles", "assets", "blender"].includes(mode)) {
       if (!args.out) throw new BlockedError(EXIT.USAGE, `${mode} needs --out <dir>`);
       const out = path.resolve(args.out);
-      if (mode === "cover") {
+      if (mode === "assets") {
+        if (!args.url) throw new BlockedError(EXIT.USAGE, "assets needs --url <link>");
+        const { fetchAssets } = await import("../engine/node/assets.mjs");
+        result = await fetchAssets({ out, url: String(args.url), into: args.cover ? "cover" : "stage" });
+      } else if (mode === "scaffold") {
+        const { scaffoldCommand } = await import("../engine/node/scaffold.mjs");
+        const { asBlocked } = pipeline;
+        result = asBlocked(() => scaffoldCommand({ out }));
+      } else if (mode === "styles") {
+        const { stylesCommand } = await import("../engine/node/gallery.mjs");
+        result = await stylesCommand({ out, format: args.format ?? "16:9", env, log });
+      } else if (mode === "cover") {
         const cover = await import("../engine/node/cover.mjs");
         const round = Number(args.round ?? 1);
         const run = () => cover.renderCover({ out, round, env, log });
@@ -94,6 +113,20 @@ export async function main(argv, { env = process.env, stdout = process.stdout, s
           result = await stage.renderStageDetached({ out, round, cli: fileURLToPath(import.meta.url), env, log });
           if (result.blocked) throw new BlockedError(result.code, result.message);
         }
+      } else if (mode === "blender") {
+        const { blenderCommand } = await import("../engine/node/blender.mjs");
+        const final = Boolean(args.final);
+        if (args.worker) {
+          const progress = (frame, frameCount) => writeProgress(out, { phase: "plate", frame, frameCount });
+          return await detachedWorker({ run: () => blenderCommand({ out, final: true, env, log, progress }), out, BlockedError });
+        }
+        // The final plate can take most of an hour, so it runs detached like a full stage render.
+        if (!final || args.foreground || env.LITMUSE_MOTION_FOREGROUND === "1") result = await blenderCommand({ out, final, env, log });
+        else {
+          const { renderStageDetached } = await import("../engine/node/stage.mjs");
+          result = await renderStageDetached({ out, round: 1, cli: fileURLToPath(import.meta.url), mode: "blender", env, log });
+          if (result.blocked) throw new BlockedError(result.code, result.message);
+        }
       } else if (mode === "sound") {
         const { soundCommand } = await import("../engine/node/sound-cli.mjs");
         result = await soundCommand({ out, env, log });
@@ -138,6 +171,14 @@ export async function main(argv, { env = process.env, stdout = process.stdout, s
   }
 }
 
+const writeProgress = (out, p) => {
+  try {
+    writeFileSync(path.join(out, ".run", "progress.json"), JSON.stringify(p));
+  } catch {
+    // The waiting caller only logs progress; a missed write costs nothing.
+  }
+};
+
 /** The detached side of a full stage or cover render: run it and leave the result for the waiting caller. */
 async function detachedWorker({ run, out, BlockedError }) {
   const { writeFileSync } = await import("node:fs");

package/plugin/skills/lit-typographic-motion/styles/paper.json

@@ -0,0 +1,41 @@
+{
+  "schema": "litmuse.motion-style/v1",
+  "id": "paper",
+  "name": "Paper",
+  "summary": "A warm paper ground, near-black ink, one terracotta signal and one blue moment; soft springs, hand-drawn calm.",
+  "light": true,
+  "typePreset": null,
+  "palette": { "ground": "#F3EEE5", "surface": "#E6DED0", "ink": "#1D1B18", "muted": "#5B564E", "signal": "#B0452A", "accent": "#2B5D8E", "line": "#C9BFAE" },
+  "accents": [{ "role": "growth and done", "color": "#3F7D3A" }, { "role": "a second data series", "color": "#7A3E7A" }, { "role": "a warning or a date", "color": "#8A6418" }, { "role": "a third data series", "color": "#1F6F6B" }],
+  "textRoles": ["ink", "muted", "signal", "accent", "ground"],
+  "faces": {
+    "display": { "family": "Pretendard", "weight": 700 },
+    "headline": { "family": "Pretendard", "weight": 700 },
+    "body": { "family": "Pretendard", "weight": 400 },
+    "label": { "family": "MesloLGS NF", "weight": 400 }
+  },
+  "scale": {
+    "16:9": { "display": 112, "headline": 68, "body": 40, "label": 26 },
+    "9:16": { "display": 108, "headline": 74, "body": 46, "label": 32 }
+  },
+  "leading": { "display": 1.15, "headline": 1.25, "body": 1.6, "label": 1.4 },
+  "motion": {
+    "ease": { "enter": [0.22, 1, 0.36, 1], "move": [0.65, 0, 0.35, 1], "exit": [0.55, 0, 1, 0.45] },
+    "dur": { "micro": 0.18, "move": 0.55, "hero": 0.8, "exit": 0.32 },
+    "stagger": { "letter": 0.03, "word": 0.09, "item": 0.1 },
+    "spring": { "micro": { "zeta": 0.85, "hz": 3.5 }, "panel": { "zeta": 0.8, "hz": 2 }, "headline": { "zeta": 0.95, "hz": 2.2 }, "subject": { "zeta": 0.6, "hz": 1.8 }, "camera": { "zeta": 1, "hz": 0.5 } },
+    "secondary": { "delay": 0.15, "travel": 0.6 },
+    "ambient": { "travel": 0.04 },
+    "push": 0.02
+  },
+  "transitions": ["cut", "match", "wipe", "iris", "push"],
+  "ground": { "kind": "flat" },
+  "sound": { "timbre": "soft-keys", "key": "F", "mode": "major", "tempo": 96 },
+  "score": { "genre": "garage" },
+  "beds": [
+    { "timbre": "soft-keys", "key": "F", "mode": "major", "tempo": 96 },
+    { "timbre": "felt-strings", "key": "G", "mode": "major", "tempo": 88 },
+    { "timbre": "glass", "key": "C", "mode": "major", "tempo": 108 }
+  ],
+  "bans": ["drop shadows that float type", "neon or glow", "gradients on type", "a saturated colour with no role", "bouncy type"]
+}

package/plugin/skills/lit-typographic-motion/styles/swiss-signal.json

@@ -0,0 +1,41 @@
+{
+  "schema": "litmuse.motion-style/v1",
+  "id": "swiss-signal",
+  "name": "Swiss signal",
+  "summary": "Ink ground, bone type, one teal signal and one amber moment; type lands precisely and cuts hard.",
+  "light": false,
+  "typePreset": "swiss-signal",
+  "palette": { "ground": "#0C0E13", "surface": "#171B24", "ink": "#E9EBE4", "muted": "#A4A9AF", "signal": "#0F7A82", "accent": "#D9A441", "line": "#4B5058" },
+  "accents": [{ "role": "state under review", "color": "#E2725B" }, { "role": "state planned", "color": "#9B8CFF" }, { "role": "state done", "color": "#8FC25A" }, { "role": "state in progress", "color": "#5BA8E0" }],
+  "textRoles": ["ink", "muted", "signal", "accent", "ground"],
+  "faces": {
+    "display": { "family": "Archivo", "weight": 900, "stretch": "100%" },
+    "headline": { "family": "Archivo", "weight": 700, "stretch": "100%" },
+    "body": { "family": "Pretendard", "weight": 400 },
+    "label": { "family": "MesloLGS NF", "weight": 400 }
+  },
+  "scale": {
+    "16:9": { "display": 128, "headline": 76, "body": 40, "label": 26 },
+    "9:16": { "display": 120, "headline": 80, "body": 46, "label": 32 }
+  },
+  "leading": { "display": 1.1, "headline": 1.2, "body": 1.55, "label": 1.4 },
+  "motion": {
+    "ease": { "enter": [0.16, 1, 0.3, 1], "move": [0.65, 0, 0.35, 1], "exit": [0.7, 0, 0.84, 0] },
+    "dur": { "micro": 0.15, "move": 0.45, "hero": 0.6, "exit": 0.28 },
+    "stagger": { "letter": 0.025, "word": 0.07, "item": 0.08 },
+    "spring": { "micro": { "zeta": 1, "hz": 4 }, "panel": { "zeta": 0.9, "hz": 2.2 }, "headline": { "zeta": 1, "hz": 2.6 }, "subject": { "zeta": 0.8, "hz": 1.8 }, "camera": { "zeta": 1, "hz": 0.5 } },
+    "secondary": { "delay": 0.15, "travel": 0.6 },
+    "ambient": { "travel": 0.03 },
+    "push": 0.02
+  },
+  "transitions": ["cut", "wipe", "match", "push"],
+  "ground": { "kind": "flat", "grid": true },
+  "sound": { "timbre": "glass", "key": "A", "mode": "minor", "tempo": 104 },
+  "score": { "genre": "house" },
+  "beds": [
+    { "timbre": "glass", "key": "A", "mode": "minor", "tempo": 104 },
+    { "timbre": "pulse-synth", "key": "D", "mode": "minor", "tempo": 112 },
+    { "timbre": "soft-keys", "key": "C", "mode": "major", "tempo": 96 }
+  ],
+  "bans": ["glow or bloom on type", "an accent colour with no role", "centred fade-in as the only move", "overshoot or bounce on type", "particles as decoration", "gradients behind type"]
+}

package/plugin/skills/lit-typographic-motion/styles/terminalcore.json

@@ -0,0 +1,42 @@
+{
+  "schema": "litmuse.motion-style/v1",
+  "id": "terminalcore",
+  "name": "Terminalcore",
+  "summary": "A navy terminal: phosphor type that appears at typing speed, one signal hue, hard cuts, nothing eases.",
+  "light": false,
+  "typePreset": "terminalcore",
+  "palette": { "ground": "#05070A", "surface": "#0C1116", "ink": "#39FF6A", "muted": "#7C8B93", "signal": "#39FF6A", "line": "#1E2A33" },
+  "accents": [{ "role": "a warning line", "color": "#FFB23F" }, { "role": "an error line", "color": "#FF6B6B" }, { "role": "a path or a link", "color": "#6CA8FF" }],
+  "textRoles": ["ink", "muted", "signal", "ground"],
+  "faces": {
+    "display": { "family": "VT323", "weight": 400 },
+    "headline": { "family": "VT323", "weight": 400 },
+    "body": { "family": "VT323", "weight": 400 },
+    "label": { "family": "MesloLGS NF", "weight": 400 }
+  },
+  "hangul": { "family": "Galmuri9", "weight": 400 },
+  "scale": {
+    "16:9": { "display": 126, "headline": 81, "body": 45, "label": 36 },
+    "9:16": { "display": 117, "headline": 81, "body": 54, "label": 36 }
+  },
+  "leading": { "display": 1.1, "headline": 1.2, "body": 1.5, "label": 1.4 },
+  "motion": {
+    "ease": { "enter": [0, 0, 1, 1], "move": [0, 0, 1, 1], "exit": [0, 0, 1, 1] },
+    "dur": { "micro": 0.1, "move": 0.3, "hero": 0.5, "exit": 0.1 },
+    "stagger": { "letter": 0.0455, "word": 0.18, "item": 0.25 },
+    "spring": { "micro": { "zeta": 1, "hz": 6 }, "panel": { "zeta": 1, "hz": 4 }, "headline": { "zeta": 1, "hz": 4 }, "subject": { "zeta": 1, "hz": 3 }, "camera": { "zeta": 1, "hz": 1 } },
+    "secondary": { "delay": 0.1, "travel": 0.6 },
+    "ambient": { "travel": 0.02 },
+    "push": 0
+  },
+  "transitions": ["cut", "wipe"],
+  "ground": { "kind": "flat", "panel": "surface" },
+  "sound": { "timbre": "pulse-synth", "key": "E", "mode": "minor", "tempo": 120 },
+  "score": { "genre": "tech-house" },
+  "beds": [
+    { "timbre": "pulse-synth", "key": "E", "mode": "minor", "tempo": 120 },
+    { "timbre": "glass", "key": "B", "mode": "minor", "tempo": 132 },
+    { "timbre": "pulse-synth", "key": "A", "mode": "minor", "tempo": 100 }
+  ],
+  "bans": ["falling code rain", "purple-cyan neon haze", "glitch running continuously", "an accent hue with no role", "pixel type too small to read", "eased type"]
+}