@prestyj/cli 5.28.0 → 5.29.0

package/assets/motion/references/build-sheet.md

@@ -0,0 +1,206 @@
+# Build sheet
+
+Everything needed to write a composition with the move kit and to score it,
+in one place. It is the complete public surface: you do not need to open
+`moves.js`, `score-synth.mjs` or any helper's `--help` to use them.
+
+## Move kit (`window.GGMotionKit`)
+
+Install with `<node> "<motion bin>/library.mjs" kit <project>`, load
+`assets/kit/moves.js` after GSAP, then `const kit = window.GGMotionKit;`.
+Every move adds tweens to `tl` from time `at` and returns the time of its key
+moment, so the next move can start from it. Options are all optional; the
+value after `=` is the default.
+
+### Arrivals
+
+| Call                         | Options                                                                                                       | Returns                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `liftWords(tl, el, at, o)`   | `stagger=0.07`, `spring="snappy"`, `duration`, `from=115` (start yPercent)                                    | when the last word has mostly risen |
+| `dropLetters(tl, el, at, o)` | `height=260`, `fall=0.38`, `stagger=0.05`, `squash=0.24`, `spring="bouncy"`                                   | the last landing                    |
+| `reveal(tl, el, at, o)`      | `from="bottom"` (top, bottom, left, right), `duration=0.8`, `ease="snap"`                                     | end                                 |
+| `typewrite(tl, el, at, o)`   | `text` (default the element's text), `cps=22`, `jitter=0.4`, `seed=11`, `caret="▍"` or `false`, `caretHold=0` | when typing ends                    |
+| `tick(tl, path, at, o)`      | `duration=0.34`, `ease="snap"` (an SVG path)                                                                  | end                                 |
+| `pop(tl, el, at, o)`         | `from=0.3` (start scale), `spring="bouncy"`                                                                   | when it reads as arrived            |
+| `stamp(tl, el, at, o)`       | `duration=0.2`, `rotate=-4`, `from=2.4`                                                                       | the contact                         |
+
+### Handoffs
+
+| Call                               | Options                                                                                                              | Returns               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `reshape(tl, el, at, to, o)`       | `to` is `{ x, y, w, h, r }` or an element; `duration=0.85`, `ease="travel"`, or `spring`                             | when the change reads |
+| `openFrom(tl, stage, at, o)`       | `x`, `y` (default the centre), `width=1920`, `height=1080`, `from=0`, `duration=0.9`, `ease="travel"`                | end                   |
+| `diveThrough(tl, layer, at, o)`    | `x=960`, `y=540`, `zoom=16`, `duration=1`, `ease="drop"`, `next` (element shown at the end)                          | end                   |
+| `converge(tl, els, at, target, o)` | `target` is `{ x, y }`; `duration=0.85`, `stagger=0.05`, `bow=0.28`, `shrink=0.12`, `seed=5`, `ease="drop"`, `space` | the last arrival      |
+
+`converge` and `hop` own the element's transform: wrap an element to also
+pop or move it.
+
+**What each move animates**, so two moves on one element never fight:
+`liftWords` yPercent of its word spans; `dropLetters` y, scaleX, scaleY and
+opacity of its letters; `reveal` and `openFrom` clip-path; `tick`
+stroke-dashoffset; `pop` scale and opacity; `stamp` scale, rotation and
+opacity; `reshape` left, top, width, height and border-radius (position the
+element absolutely); `diveThrough` the layer's scale and the `next`
+element's visibility; `knock` rotation; `impact` the shake layer's x and
+rotation; `converge`, `hop` and `cursorPath` write `style.transform`
+directly. `typewrite` changes only the text.
+
+### Contact
+
+| Call                    | Options                                                                                                    | Returns          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- |
+| `hop(tl, el, at, o)`    | `height=140`, `duration=0.5` (air time), `squash=0.2`                                                      | the landing      |
+| `impact(tl, at, o)`     | `shake` (a layer, not the camera world), `amount=16`, `duration=0.6`, `split: [left, right]`, `spread=140` | `at`             |
+| `knock(tl, els, at, o)` | `push=48`, `gap=0.11`, `tilt=7`, `axis="x"` or `"y"`                                                       | the last contact |
+
+### Camera
+
+`const cam = kit.camera(tl, world, keys, o)` drives `world`, a layer holding
+the whole scene in world pixels. It returns `{ plan, at(t), toScreen(t, x, y) }`.
+Make `world` an absolutely positioned element at left 0, top 0 (any size;
+place scenes inside it at their world coordinates). The camera owns its
+transform and sets its transform-origin to 0 0: never animate `world`
+yourself; move things inside it. A key's `x, y` is the world point shown at
+the centre of the frame, so `{ x: 960, y: 540, zoom: 1 }` shows the first
+1920 × 1080 of the world unchanged.
+
+- **Keys**: `[{ x, y, zoom=1, rotate=0 }, { at, x, y, zoom, rotate, move, duration }, ...]`.
+  The first key is the start. `move` is a curve name (`whip` by default,
+  `glide` for slow pushes, `cut` for a jump); `duration=0.9`.
+- **Options**: `width=1920`, `height=1080`, `duration` (default the last move),
+  `lead` (seconds each move starts early), `handheld: { amp=6, rotate=0.2, rate=0.5, seed=7 }`,
+  `rests: [[from, to], ...]` (exactly still there), `shakes: [{ at, amount=14, decay=9 }]`,
+  `layers: [{ el, depth }]` (0 pinned, 0.5 far, 1 the world, above 1 near).
+- Pure helpers: `cameraAt(plan, t, o)`, `atDepth(cam, depth)`, `toScreen(cam, x, y)`.
+
+### Deep zoom, light, texture
+
+| Call                                | Options                                                                                                                                                                                                                                              | Returns                     |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| `deepZoom(tl, world, at, o)`        | `anchor={x,y}` (world point, default the centre), `from=1`, `to=100` (any factor, up to about 1000), `screenFrom`, `screenTo` (where the anchor sits on screen; default the centre), `duration=3`, `ease="glide"`, `width`, `height`                 | end                         |
+| `lightGround(tl, el, at, o)`        | `rise=0.9`, `hold=0.6`, `drain=0.9`, `x`, `y` (default below the frame), `reach=1.15`, `color` (an `r, g, b` string), `ease="glide"`; on a canvas it paints, on other elements it sets `--light`, `--light-r`, `--light-x`, `--light-y` (with units) | the flood                   |
+| `rings(tl, el, at, o)`              | `count=4`, `duration=1.2`, `stagger=0.14`, `x`, `y` (default the centre), `ease="snap"`; reveals `el` (the next scene) through expanding rings                                                                                                       | fully shown                 |
+| `silk(tl, canvas, at, duration, o)` | `colors` (two or more hex), `seed=1`, `speed=0.08`, `scale=2.2`, `warp=1.2`, `cols=64`, `rows`                                                                                                                                                       | end                         |
+| `belt(tl, items, at, o)`            | `speed=240` (px/s), `stop` (timeline time it comes to rest), `spacing=360`, `axis="x"`, `direction=-1`, `rampIn=0.6`, `rampOut=0.9`, `origin`, `wrap`                                                                                                | `{ stop, at(t), clock(t) }` |
+| `brushStroke(tl, canvas, at, o)`    | `path` (SVG path) or `points`, `width=28`, `bristles=48`, `dryness=0.65`, `color`, `duration=0.8`, `seed=3`, `ease`                                                                                                                                  | when the brush lifts        |
+| `grain(el, o)`                      | `amount=0.05`, `seed=9`, `size=128`; a fixed overlay so dark gradients do not band; identical on every frame                                                                                                                                         | the tile's data URL         |
+
+### Print look (riso, screen print)
+
+| Call                             | Options                                                                                                                                                                                                                 | Returns              |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `printInk(el, o)`                | `offset={x:0,y:0}` (fixed misregistration), `cell=7` (halftone spacing px), `angle=15`, `amount=0.86` (ink coverage), `rough=0.18`, `seed=3`; sets multiply blending and a halftone mask, so overlapping inks overprint | the tile's data URL  |
+| `misregister(tl, layers, at, o)` | `distance=26` px (or `from: [{x,y}, ...]`, one per layer), `seed=11`, `spring="soft"` or `ease` with `duration=0.8`, `apart=false` (true drifts apart instead of settling)                                              | when the inks settle |
+| `paperTexture(el, o)`            | `size=256`, `amount=0.06`, `tint="#fdf8ee"`, `fibres=160`, `seed=5`; identical on every frame                                                                                                                           | the tile's data URL  |
+
+Give each ink its own layer (one flat colour per layer, e.g. fluorescent pink
+and blue), lay them over paper, and let them settle into register on the beat.
+`printInk` uses the element's `mask-image` and `translate`. Pure helpers:
+`halftoneTile`, `misregisterAt`, `paperTile`.
+
+`deepZoom` owns `world`'s transform like the camera does: a dive or pull-out
+keeps its anchor exactly where it is keyed on screen at any depth. Pure
+helpers: `deepZoomAt`, `lightLevel`, `ringsAt`, `silkField`, `beltAt`,
+`grainTile`.
+
+### Cursor
+
+`const { end, presses } = kit.cursorPath(tl, cursor, at, stops, o)`. Stops are
+`{ x, y }` or `{ el }`, each with optional `click: true`, `hold=0.15` and
+`duration`. Options: `speed=1500` (px/s), `press=0.09`, `release=0.26`,
+`bow=0.12`, `tip=[6, 4]` (the hotspot), `space`. Script each pressed state and
+its sound from `presses`.
+
+### Sound
+
+`kit.cue(tl, at, sfx, { gain=1, x, pan, send, name })` marks a sound where the
+event happens. `x` is the object's screen x and pans with it; `pan` (-1..1)
+overrides it; `send` (0..1) is its distance. Then run
+`<node> "<motion bin>/cues.mjs" <project>`.
+
+### Timing and helpers
+
+- **Springs** (`spring` options): `snappy`, `bouncy`, `soft`, `heavy`, `whip`.
+  `kit.springEase(name)` gives a GSAP ease; `kit.settleTime(name)` gives its length.
+- **Curves** (`ease` and `move`): `snap`, `drop`, `glide`, `travel`, `whip`,
+  `settle`, `bounce`, `firm`, `cut`.
+- `drive(tl, at, duration, draw)`: calls `draw(localTime)` every frame, seeks
+  included; draw anything (counters, canvas, SVG) as a pure function of time.
+- `split(el, "words" | "chars", { mask })` returns spans; `centerOf(el, space)`
+  and `rectOf(el, space)` measure layout without transforms; `rng(seed)` and
+  `noise(seed, t)` are seeded.
+
+## Score (`score.json` for `score-synth.mjs`)
+
+Run `<node> "<motion bin>/score-synth.mjs" score.json assets/audio`. It writes
+`music.wav`, `sfx.wav` and `tempo-map.json` (beats, bars, hits, merges,
+balance) in under a second.
+
+```json
+{
+  "bpm": 84,
+  "duration": 24,
+  "seed": 3,
+  "style": "lofi",
+  "key": "F",
+  "scale": "major",
+  "chords": ["Fmaj7", "Em7", "Dm7", "Cmaj7"],
+  "sections": [
+    { "name": "intro", "from": 0, "energy": 0.3 },
+    { "name": "groove", "from": 2.9, "energy": 0.7 }
+  ],
+  "hits": [
+    { "t": 3.0, "sfx": "tap" },
+    { "beat": 8, "sfx": "chime" },
+    { "bar": 4, "sfx": "impact" }
+  ],
+  "cues": "cues.json",
+  "room": "room",
+  "duck": 0.55,
+  "ending": "resolve",
+  "air": true,
+  "music": true
+}
+```
+
+- **bpm** 40–220; **duration** in seconds; **seed** any integer.
+- **style**: `pulse` (four on the floor), `cinematic` (swells and low hits),
+  `minimal` (sparse keys), `lofi` (swung eighths, dusty keys, round bass,
+  soft kit, vinyl and tape wobble).
+- **key** and **scale** (`major` or `minor`) pick default chords; `chords`
+  overrides them.
+- **sections**: energy 0–1 brings parts in. In `lofi`: keys and vinyl alone
+  below 0.25, kick and snare from 0.25, hats from 0.4, the full kit from 0.5.
+- **hits**: `t` (seconds), `beat` or `bar`, `sfx`, optional `gain` (0–2),
+  `pan`, `send`, `name`. Sounds: `tap`, `press`, `knock`, `chime`, `thud`,
+  `plip`, `paper`, `breath`, `click`, `tick`, `snap`, `pop`, `glitch`,
+  `whoosh`, `whoosh-short`, `riser`, `swell`, `impact`, `sub-drop`, `sting`,
+  `shimmer`, `typing`.
+- **cues**: the file `cues.mjs` exported; its hits and camera air join these.
+- **room**: `none`, `booth`, `room`, `hall`. **duck**: music level under the
+  heaviest hit (1 = none). **ending**: `resolve` or `cut`. **air**: camera air
+  on or off. **music**: false for effects only.
+
+## Licensed or supplied music
+
+To cut a track the user supplies to the picture instead of synthesising one:
+`<node> "<motion bin>/music-fit.mjs" <track> --duration <s> [--land <trackTime>@<filmTime>] [--out assets/audio]`.
+It finds the tempo and downbeats, cuts whole bars on downbeats with short
+crossfades so the length is exact, lands the chosen downbeat (`--land`, snapped
+to the nearest one) on a film time, and writes `music.wav` plus
+`music-fit.json` with the downbeats in film time. Put hits on those downbeats.
+Constant tempo and 4/4 only.
+
+## Tall frame (1080 × 1920)
+
+Fill the frame and go big. The feeds cover only a bar over the top 138 px, a
+caption over the bottom 422 px and buttons over the right 179 px from y 840
+down; keep words out from under those.
+
+## Render
+
+| Step            | Command                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Final with blur | `<node> "<motion bin>/motion-blur.mjs" <project> renders/<name>-v1.mp4` (the one render, at feed loudness; run it in the background) |
+| Stills          | `<node> "<motion bin>/hyperframes.mjs" snapshot <project> --at 1,4,8,12 --describe false` (several at once)                          |

package/assets/motion/references/runtime/determinism-rules.md

@@ -15,7 +15,7 @@ For GSAP:
 - **Do not** call `tl.play()` for render-critical motion.
 - **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
 
-Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not override the selected recipe's geometry, timing or allowed input changes.
+Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not choose the design.
 
 ## Determinism Rules
 
@@ -41,9 +41,9 @@ Build the visible end-state in static HTML and CSS first, then animate from/to t
 - **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
 - Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
 - Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
-- Preserve the recipe's positioning model. Absolute layers are appropriate when reproducing authored source geometry; generic layout preferences must not alter it.
+- Absolute layers are appropriate for deliberately placed design elements; keep one positioning model per scene.
 - Prefer transforms and opacity for animation.
-- Keep text inside its intended container. Only use wrapping, resizing or `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` when the recipe permits that fit policy; otherwise resolve the input conflict.
+- Keep text inside its intended container. Wrap, resize or use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` deliberately; never let text clip silently.
 - For text measurement without DOM reflow, use `window.__hyperframes.pretext`. Measure off a canvas instead of writing into the page and reading it back, so nothing reflows: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)` → `{ lineCount, height }`. `prepare` does the font measurement; everything downstream of a prepared string is arithmetic and cheap enough to run per frame. `fitTextFontSize` is built on it.
   - `layout` gives you height, not width. To size a container to its text (shrinkwrap), use `pretext.prepareWithSegments(text, font)` and then `pretext.measureNaturalWidth(prepared)` for the single-line width, or `pretext.measureLineStats(prepared, maxWidth)` for `{ lineCount, maxLineWidth }`.
   - `font` is a CSS font shorthand string, e.g. `"700 90px Inter"`.

package/assets/motion/references/runtime/gsap-easing-and-stagger.md

@@ -11,14 +11,14 @@ Each has `.in`, `.out`, `.inOut` variants.
 | `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
 | `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
 | `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
-| `back.out(1.7)`                            | Overshoot then settle. RARE — explicitly-playful register only, never a default.                |
-| `elastic.out(1, 0.3)`                      | Springy bounce. Same playful-only rule; prefer a baked spring (see Spring Eases below).         |
+| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                  |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).             |
 | `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                        |
 | `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                        |
 
 Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
 
-**Smooth beats bouncy** — the motion doctrine (`rules/spring-pop-entrance.md`, the workflows' `motion-language.md`): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`) are a rare, explicitly-playful register, never the house style.
+**Smooth by default, bounce by choice**: entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
 
 ## Easing Vocabulary (character & mood)
 
@@ -26,18 +26,18 @@ Easings are tone of voice: a video that only whispers is boring; one that varies
 
 The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
 
-| Family               | Character                                                                    | Typical use                                                                                                                                  |
-| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
-| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | RARE — explicitly-playful register only, never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | RARE — same playful-only rule; the baked spring (below) is the physical version                                                              |
-| `bounce`             | Ball-drop bouncing                                                           | RARE — physical-comedy register only (something literally dropping)                                                                          |
-| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
-| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
-| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
-| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
+| Family               | Character                                                                    | Typical use                                                                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                             |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Chosen register only (playful, physical), never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                          |
+| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                  |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                    |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Nolan Burns, anything that loops. `.inOut` for yoyo motion                                                            |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                               |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                         |
 
-**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only on explicitly-playful beats. The storyboard's mood description should guide which character fits — not a formula.
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The video's register should guide which character fits — not a formula.
 
 ## Defaults
 
@@ -58,7 +58,7 @@ Setting defaults at timeline scope is preferred — it documents the motion lang
 
 ## Spring Eases (baked physics, seek-safe)
 
-The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for the rare playful register — bake the spring's closed-form solution into a function ease.
+The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for a playful register — bake the spring's closed-form solution into a function ease.
 
 Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
 
@@ -67,7 +67,7 @@ Why not a real-time spring library: an interactive spring is a stateful integrat
 // response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
 // dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
 //                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
-//                  0.60–0.70 = explicitly playful — ~5–10% overshoot (rare; replaces back.out)
+//                  0.60–0.70 = playful register — ~5–10% overshoot (by choice; replaces back.out)
 function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
   const w = (2 * Math.PI) / response; // undamped natural frequency
   const z = dampingFraction;
@@ -116,24 +116,24 @@ tl.fromTo(
 );
 ```
 
-| dampingFraction   | overshoot       | register                                                                                                                                           |
-| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
-| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
-| 0.60–0.70         | ~5–10%          | Explicitly-playful ONLY (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
-| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
+| dampingFraction   | overshoot       | register                                                                                                                                               |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                     |
+| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                                |
+| 0.60–0.70         | ~5–10%          | Playful register, by choice (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
+| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                       |
 
-| response  | duration (ζ=1) | feel                                                         |
-| --------- | -------------- | ------------------------------------------------------------ |
-| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
-| 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
-| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — check the `t ≤ 0.5s` visibility rule |
+| response  | duration (ζ=1) | feel                                                                                                                |
+| --------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                                                                        |
+| 0.35–0.50 | 0.51–0.74s     | standard entrance                                                                                                   |
+| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — when the shot opens on it, start it early so the subject is seen within about half a second |
 
 Craft notes:
 
 - **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
 - **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
-- **Doctrine unchanged**: ζ below ~0.8 is still the rare, explicitly-playful exception (`rules/spring-pop-entrance.md`). The default of this section is ζ=1 — real spring physics is not a license for bounce.
+- **Default unchanged**: ζ below ~0.8 is a register the brief chooses, never a default. The default of this section is ζ=1 — real spring physics is not a license for bounce.
 
 ## Stagger
 

package/assets/motion/references/runtime/gsap.md

@@ -56,13 +56,13 @@ For transforms, autoAlpha, clearProps, and SVG specifics see `./gsap-transforms-
 
 ## Animated properties
 
-Prefer these efficient targets when they preserve the recipe's behaviour:
+Prefer these efficient targets when they achieve the intended motion:
 
 - **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
 - **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
 - **CSS variables**: `"--hue": 180` etc.
 - **Media `volume`** (on `<audio>` / `<video>`): do not tween it for fades or ducking; use the `data-automation` volume lane (see `data-attributes.md`). A lane wins over a tween on the same element.
-- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Use a deterministic proxy value with `onUpdate` for locale formatting or suffix logic when the selected recipe needs it.
+- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Use a deterministic proxy value with `onUpdate` for locale formatting or suffix logic when the design needs it.
 
 **Avoid** (use the transform alias instead):
 
@@ -80,7 +80,7 @@ Prefer these efficient targets when they preserve the recipe's behaviour:
 - `./gsap-timeline-and-labels.md` — timeline creation, position parameter (`+=`, `<`, `>`), labels, nesting, sub-comp `fromTo` preference, playback control.
 - `./gsap-easing-and-stagger.md` — easing families, stagger objects, function-based values, `gsap.matchMedia()`, `gsap.defaults()`.
 - `./gsap-transforms-and-perf.md` — transform aliases, autoAlpha, `quickTo`, `will-change`, performance rules.
-- The selected recipe defines effects and motion mechanisms; these API examples are not additional creative instructions.
+- The video's plan defines effects and motion; these API examples are not additional creative instructions.
 
 ## Best Practices
 

package/assets/motion/references/runtime/inputs-and-assets.md

@@ -1,8 +1,7 @@
 # GG runtime inputs and assets
 
-This is implementation support, not a creative workflow. The selected recipe
-controls choreography and permitted adaptations. Bind approved text, fonts,
-colours, logos and media without adding a second look-selection process.
+This is implementation support, not a creative workflow. Bind approved text,
+fonts, colours, logos and media without adding a second look-selection process.
 
 `hf` in these references is shorthand for the exact bundled launcher command
 in the system prompt; expand it, never run bare `hf` or `npx hyperframes`.
@@ -14,13 +13,13 @@ package installs, cloud rendering or publishing without explicit permission.
 - Keep original captures/uploads in `sources/`; use local `assets/` for the
   files consumed by the composition. Never overwrite originals or finished renders.
 - A reusable kit lives at `brand-kits/<slug>/Motion.md` in the Motion workspace.
-  Keep it read-only for ordinary video work. Record the selected kit and permitted
-  bindings in `frame.md`; preserve legacy briefs rather than duplicating plans.
-- The recipe defines fit/crop/in-point policies. Record approved choices. A
-  different asset aspect ratio or title length does not authorize new choreography.
-- Root output duration is a static composition contract. If a permitted input
-  changes duration, update the authored root explicitly; a runtime variable
-  cannot silently change the compiled video length.
+  Keep it read-only for ordinary video work; preserve legacy briefs rather than
+  duplicating plans.
+- A longer title or a different aspect ratio calls for a deliberate layout adjustment, not a silent
+  crop.
+- Root output duration is a static composition contract. If an input changes
+  the duration, update the authored root explicitly; a runtime variable cannot
+  silently change the compiled video length.
 
 ## Existing helpers (only when needed)
 
@@ -37,16 +36,22 @@ Inspect helper help for less common operations; do not guess options. Fonts,
 Three.js and library assets remain available offline, but their existence does
 not require using them. Respect actual licenses and required brand typography.
 
+`fonts.mjs add` returns `head`: a `<style>` block of `@font-face` rules with
+paths from the project folder. Paste it into the composition `<head>`.
+`hf check` only recognises fonts declared in the page, so linking
+`assets/fonts/fonts.css` instead renders fine but is reported as missing fonts.
+
+GSAP loads from the pinned CDN script in
+[minimal-composition](minimal-composition.md). There is no local copy in the
+bundle; do not search for one or copy one from another project.
+
 Shared music and SFX are at `../../assets/music/` and `../../assets/sfx/` relative
 to this document. Upstream metadata can retain historical `skills/brag/` paths;
 resolve its filenames under these shared asset roots, not the removed skill.
 Those provenance notes are not instructions to invoke an old workflow.
 Preserve credits, cue maps and SFX analysis. Copy only used
-assets into the video project. The selected recipe or user determines whether
+assets into the video project. The plan or user determines whether
 sound belongs in the video; do not automatically add music or hits.
 
-Use `motion_check` once on the current render as specified by `video-qa`; it
-runs the media helpers and returns images for this agent to inspect. Do not
-repeat its checks as a separate checklist. Request permission before
-installing missing FFmpeg/browser software; a detector setup failure does not
-justify skipping validation. Never upload user files to resolve a local blocker.
+Request permission before installing missing FFmpeg/browser software. Never
+upload user files to resolve a local blocker.

package/assets/motion/references/runtime/lint-validate-inspect.md

@@ -1,6 +1,6 @@
 # lint, check, snapshot
 
-Motion's `motion_check` tool already runs `check`, including lint, runtime, layout and contrast, and returns rendered images. Do not run the commands below as additional delivery gates. Use them only for targeted debugging of a concrete failure. `snapshot` captures still frames and zoomed crops; `validate`, `inspect` and `layout` are deprecated because `check` covers them.
+Motion does not run these as delivery gates. Use them only for targeted debugging of a concrete failure. `snapshot` captures still frames and zoomed crops; `validate`, `inspect` and `layout` are deprecated because `check` covers them.
 
 ## Discipline (motion-heavy work)
 
@@ -9,7 +9,7 @@ For a concrete problem during authoring or editing:
 - Use `lint` for a static-code failure or `check --snapshots` for runtime/layout evidence, not both by default.
 - Look at the returned images before changing the animation: a diagnostic must not become an alternative art direction.
 - Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion` / `data-layout-allow-caption-zone` (caption band only).
-- Existing meaningful motion assertions may remain, but GG does not require a new `*.motion.json` sidecar for every video. Use rendered-pixel checks and the `video-qa` evidence process for liveness, especially for canvas/WebGL. No detector or screenshot proves playback was watched.
+- Existing meaningful motion assertions may remain, but EZ does not require a new `*.motion.json` sidecar for every video. Use stills of the render for liveness, especially for canvas/WebGL. No detector or screenshot proves playback was watched.
 
 ## lint
 
@@ -68,7 +68,7 @@ hf check --frame-check     # media (img/svg/video/canvas) out-of-frame detection
 
 `--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags a text element's DOM box (`getBoundingClientRect`) that overlaps the band. Waive intentional lower-third copy with `data-layout-allow-caption-zone` on the element or its nearest wrapper (see Escape hatches). `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
 
-**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply an allowed correction, or resolve a conflict with locked source/brand colours before changing them. Recheck the changed output through `motion_check`; do not duplicate the full diagnostic checklist.
+**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply an allowed correction, or resolve a conflict with locked source/brand colours before changing them. Look at a still of the changed moment; do not run the full diagnostic checklist.
 
 ## Motion verification (`*.motion.json` sidecar)
 

package/assets/motion/references/runtime/minimal-composition.md

@@ -67,3 +67,9 @@ What the runtime actually requires:
 Everything else in the skeleton is ordinary HTML and CSS: the `#root` box, `.clip` positioning, and fonts are yours to choose.
 
 This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.
+
+## Vertical (9:16)
+
+For phone-first video, set the viewport meta to `width=1080, height=1920`, give the root `data-width="1080"` and `data-height="1920"`, and render with the matching size (`--resolution portrait`). Everything else stays the same.
+
+Size type against the frame's width, not its height: a 96 px headline that suits a 1920 px-wide frame takes over half the width of a 1080 px one, so check that the longest word fits. When the video will play in a feed (Instagram, TikTok, YouTube Shorts), keep words out from under the apps' own bar, caption and buttons: on 1080×1920, the top 138 px, the bottom 422 px and the right 179 px from y 840 down.

package/assets/motion/references/runtime/preview-render.md

@@ -57,7 +57,7 @@ Failure modes:
 
 | Code                       | Meaning                                                                    |
 | -------------------------- | -------------------------------------------------------------------------- |
-| `preview-not-running`      | Start Studio first with `hf preview --background`.            |
+| `preview-not-running`      | Start Studio first with `hf preview --background`.                         |
 | `ambiguous-preview-server` | Multiple matching Studio servers are open; rerun with one listed `--port`. |
 | `preview-port-mismatch`    | The requested `--port` is not one of the matching Studio servers.          |
 | `no-selection`             | Studio is open, but the user has not selected an element yet.              |
@@ -99,7 +99,7 @@ Validation runs before any server boots, so an invalid value exits cleanly witho
 
 ## render
 
-> A clear video request authorizes a new, versioned local render. Preview is available when useful, not a mandatory approval checkpoint. Ask only for unresolved inputs, material choices or permission to overwrite an existing export; check the result once through `motion_check`.
+> A clear video request authorizes a new, versioned local render. Preview is available when useful, not a mandatory approval checkpoint. Ask only for unresolved inputs, material choices or permission to overwrite an existing export. The final render screens itself for harmful flashing.
 
 ```bash
 hf render                                # standard MP4 from cwd
@@ -153,4 +153,4 @@ hf render --docker                       # byte-identical
 Keep renders and diagnostics local. Feedback submission, issue filing, publishing
 and cloud rendering are not automatic completion steps. They require explicit
 user authorization; do not send source files, private assets or logs upstream.
-Use GG's `reveal.mjs` to select the delivered local file.
+Use EZ's `reveal.mjs` to select the delivered local file.

package/assets/motion/skills/app-walkthrough/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: app-walkthrough
+description: Job skill for showing how an app or product is used, step by step, on rebuilt real screens. Adds walkthrough questions, the screen-rebuild method, moves and pitfalls. Load once, before asking.
+---
+
+# App walkthrough
+
+A walkthrough is the product in use: open it, do the task, get the
+result. Build it as the `motion` skill describes; this page adds what is
+specific to walkthroughs.
+
+## Ask (on the motion skill's single card)
+
+- "Which task should the video walk through?" Offer the two or three tasks the
+  prompt or screenshots suggest, plus "Let EZ Motion choose".
+- "Where will people mostly watch this?" (from the `motion` skill).
+- "Should it have music?" (from the `motion` skill).
+- "Which idea should we go with?" Pitches below, recommended marked, plus "Let
+  EZ Motion choose".
+
+Without screenshots, end with one plain line: "Send me a screenshot of each
+step of that task, in order. Phone photos of the screen are fine." Do not ask
+for a shot list.
+
+## Rebuild the screens
+
+Rebuild each screen as HTML at the screenshot's own size, with its states
+scripted, its text big enough to read, one close-up per step and a cursor that
+presses. Start from the `screen-replica-steps` piece. Hide account names,
+emails and anything private. Data on screen comes from
+their screenshots or files, never invented.
+
+## Ideas that suit walkthroughs
+
+- **Follow the hand.** One continuous camera that rides the cursor from step to
+  step; each click opens the next framing.
+- **The request becomes the result.** The thing the user types or picks grows
+  into what the app gives back.
+- **The app's own transition.** Use the app's real sheet, drawer or page
+  animation as the handoff between steps.
+- **Before the tap, after the tap.** Each step is a held "before" frame, one
+  press, and the change it causes.
+
+## Beats that work
+
+- Open on the moment that matters most (the result), then rewind to how it is
+  done, or open straight on the first step with the cursor already moving.
+- One step per beat, with a close-up on the control being used.
+- Hold still on the result long enough to read it. That is the rest.
+- End on the app's name or icon and where to get it.
+
+## Moves
+
+`kit.cursorPath` with press and release; `kit.camera` following the cursor;
+`kit.typewrite` for typed input; `kit.tick` for completed steps;
+`kit.reshape` from the pressed control into the result. Pieces:
+`screen-replica-steps`, `request-to-result`, `cursor-click`, `phone-frame`,
+`browser-window`, `camera-rig`.
+
+## Pitfalls
+
+- Screenshots placed flat and slid around. Rebuild them.
+- Whole screens shown small: text unreadable at phone size.
+- The cursor teleporting, or changes happening without a click.
+- Steps of equal length with no rest on the result.
+- Made-up names, numbers or results.

package/assets/motion/skills/before-after/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: before-after
+description: Job skill for a before-and-after video, showing life without the product, then with it. Adds before/after questions, idea patterns, moves and pitfalls. Load once, before asking.
+---
+
+# Before and after
+
+The viewer should feel the difference, not read it. Build it as the `motion`
+skill describes; this page adds what is specific to comparisons.
+
+## Ask (on the motion skill's single card)
+
+- "What's the annoying part of life without it?" Offer two or three guesses
+  from the prompt, plus "Let EZ Motion choose".
+- "Where will people mostly watch this?" (from the `motion` skill).
+- "Should it have music?" (from the `motion` skill).
+- "Which idea should we go with?" Pitches below, plus "Let EZ Motion choose".
+
+## Ideas that suit comparisons
+
+- **The same task, twice, side by side.** Both halves start together; the
+  "before" side keeps getting interrupted while the "after" side simply
+  finishes. Then the losing half falls away.
+- **One drawing, broken and whole.** A shape or line is drawn twice: broken up
+  by the problem on one side, unbroken on the other. The whole one becomes the
+  logo.
+- **Rewind.** Play the messy version, rewind it in one motion, and play it
+  again with the product.
+
+The comparison must use one measure the viewer can see (time, steps, mess),
+shown on both sides in the same way.
+
+## Beats that work
+
+- Set up both sides in one frame so the comparison is fair.
+- Let the problem build, quickening, on the "before" side.
+- A held breath when the "after" side finishes: a real, still rest.
+- The winning side's result carries into the name.
+
+## Moves
+
+`kit.impact` for interruptions; `kit.camera` with a local shake on one side
+only; `kit.openFrom` from the finished result; `kit.converge` into the logo.
+Pieces: `before-after-split`, `open-from-subject`, `gather-to-logo`,
+`camera-rig`.
+
+## Pitfalls
+
+- Two separate scenes, before then after, with a cut between. Show them
+  together, or carry one into the other.
+- An unfair comparison: different tasks or different measures on each side.
+- Captions that state the difference instead of showing it.
+- Invented statistics about the improvement.