pixi-effects 0.2.0 → 0.4.0

package/llms-full.txt

@@ -0,0 +1,2001 @@
+# pixi-effects — full documentation for AI agents
+
+Concatenation of the skill, cheatsheet, pitfalls, recipes and the DSL / API references. Generated by scripts/build-llms.mjs; do not edit.
+
+
+
+<!-- ===== ai/SKILL.md ===== -->
+
+# pixi-effects — write a video as data
+
+You describe a video as a tree of plain objects; the library plays it in a canvas and exports it (MP4/WebM/MOV). You never write per-frame code. **Read `reference/cheatsheet.md` once before writing anything**, copy a recipe from `reference/recipes.md` when one fits, and skim `reference/pitfalls.md` — every item there cost a previous session a retry.
+
+## Workflow
+
+1. **Start from `template.html`** (copy it; it loads the library from a CDN, collects every console warning into `window.__logs`, and exposes `window.movie`). One HTML file, plain JS. Default canvas 1280×720 @ 30 fps.
+2. **Write the composition as data.** Anything repeated (letters, bars, particles, scenes) is a JS function or loop that returns specs — never copy-paste objects. Derive coordinates and times from constants/data, not magic numbers.
+3. **Run it and read the logs first.** `window.__ready` must be `true` and `window.__logs` should be `[]`. A pixi-effects warning is an instruction: fix what it names.
+4. **Look at it** — you cannot judge motion from code. The library has the tools built in:
+   - `await movie.contactSheet({ count: 6, as: 'dataURL' })` → ONE image of several labelled frames (pass `frames: [...]` / `times: [...]` to choose; include the middle of every transition and the last second). Save it and view it.
+   - `await movie.inspect(frame)` → every layer's canvas bounds and visibility, plus `issues` (text off the canvas, cut off by an edge, empty, or overlapping other text). Run it at several frames; fix every issue it names.
+   - `await movie.snapshot(frame, { as: 'dataURL' })` → one frame, canvas only (no player bar).
+   From a browser tool the result is a `data:` URL string: `agent-browser eval "movie.contactSheet({ count: 6, as: 'dataURL' })" | python3 ai/tools/save-image.py /absolute/sheet.png`, then open the PNG. Sheet tiles are small (~480 px): use `snapshot` for detail. `inspect` output is long on busy scenes: pass `{ layers: 'none' }` and read `issues` first. Give layers a `name` so inspect paths are readable. A moving ticker is not flagged as cut off.
+5. **Iterate** on what you saw (clipped text, collisions, wrong timing). Then export: `const blob = await movie.render({ format: 'mp4' })` (about real time; `movie.on('progress', …)` reports 0–100).
+
+## The rules that cause most failures
+
+- **Keyframe `at` starts at 0 when the layer appears** (negative = back from the layer's end). A layer's own `at` and a transition's `at` are composition time.
+- **Layers are hidden, not removed, after their lifespan; z-order is array order.** Switch scenes by stacking layers with `at`/`duration` over an opaque background rect.
+- **Angles are degrees. `+z` is toward the viewer. Numbers can be expressions** (`'GW/2 - w/2'`; no `pi`; no per-frame variable).
+- **Anchors**: rect/circle/ellipse are centred on `x,y`; text and image are top-left (use `anchorX/anchorY: 0.5`); compositions use `pivotX/pivotY`. A bar that grows from its base needs `anchorY: 1`.
+- **`audio` shorter than its layer goes silent** — add `loop: true`.
+- **Masks live in the parent's coordinates and don't follow the masked layer.** **`filterArea` is in the layer's own coordinates.**
+- **2.5D needs `threeD: true`** on each layer plus a `{ type: 'camera' }` layer; camera props go in `initial`/keyframes; keep every `z` below the camera distance (≈ 989 at 720p, fov 40); under a dolly zoom only `z = 0` stays fixed.
+- **Built in:** `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`. **Not in the DSL (hand-roll, recipes exist or loops are easy):** arc / progress-ring and stroke draw-on, text that changes over time (other than `{value}`), other per-frame curves and jitter, per-letter text animators (one layer per letter), particle emitters, group/parent layers.
+- **Blend modes:** `blendMode: 'add' | 'screen' | 'multiply'` on any layer (glows, light leaks).
+- **One `Movie` per page.** A sound effect needs no `duration` (it lasts as long as its clip). Seeking is safe: counters, colours and growing shapes are right after any jump.
+
+## Layout sanity (the cheap bugs a screenshot catches)
+
+Centred text must be positioned by `anchorX/anchorY: 0.5`; estimate text width as ~0.6 × `fontSize` per glyph (monospace) or ~0.8 (heavy sans) and leave margin; captions stay above the bottom 60 px; nothing important within 5 % of the frame edge; a `threeD` layer can be sorted in front of text.
+
+## Files
+
+- `reference/cheatsheet.md` — every layer type, prop, default and rule on one page.
+- `reference/recipes.md` — tested building blocks: slam type, lower-third, marquee, count-up, bar chart, 2.5D title, camera orbit, slideshow with transitions + music, looping, particles, gradients/vignette, three.js metal.
+- `reference/pitfalls.md` — the full list of real mistakes, with status.
+- `template.html` — the starting file. (It loads the library from a CDN; when testing against a local build, point the three `pixi-effects*` importmap entries at `../../dist/…`.)
+- `tools/save-image.py` — save a `dataURL` result (contact sheet / snapshot) to a PNG.
+- Full reference: `docs/dsl.md` and `docs/api.md` in the repository.
+
+
+<!-- ===== ai/reference/cheatsheet.md ===== -->
+
+# pixi-effects cheatsheet
+
+A video is **data**: a tree of plain objects. Everything below is a JS object you put in `composition.sequences`. Build repeated structure with JS functions and loops; the spec is just objects.
+
+## Conventions (state once, never guess)
+
+| Thing | Rule |
+|---|---|
+| Canvas | pixels, origin top-left, `+x` right, `+y` down. Typical: 1280×720 @ 30 fps |
+| Angles | **degrees**: `rotation`, `skew*`, `rotationX`, `rotationY` |
+| Depth (`z`) | `+z` toward the viewer (bigger, nearer) |
+| Numbers | any number may be an **expression string**: `'GW/2 - w/2'`, `'min(W,H)*0.4'` (build-time only; no per-frame time variable) |
+| Colours | `'#rrggbb'` strings or numbers; text colour is `style.fill`, shape colour is `fillColor`/`strokeColor`, image colour is `tint` |
+| Z-order | **array order**, later = on top. A layer is hidden (not removed) outside `[at, at+duration)` and keeps its last values |
+| Time of a sequence's `at` | seconds from the start of its **parent composition** (default 0) |
+| Time of a keyframe's `at` | seconds from the start of **its own layer**; **negative = back from the layer's end** |
+| Time of a transition's `at` | seconds from the start of the **parent composition**; negative = back from its end |
+| `duration` | defaults to the parent composition's duration |
+
+## Expressions
+
+Operators `+ - * /`, parentheses, unary `-`. Functions `min max abs floor ceil round sqrt pow sin cos tan` (radians; there is **no `pi`**: write `3.14159`).
+
+| Variable | Meaning |
+|---|---|
+| `W`, `H` | parent composition size |
+| `GW`, `GH` | root (movie) size |
+| `w`, `h` | this layer's own size (image/video natural size, text size **after** its style is applied, shape bounds) |
+| `cover`, `contain` | scale that makes the layer cover / fit the parent (`scale: 'cover'`) |
+| `t`, `d`, `T` | layer start time, layer duration, parent duration |
+
+## Common fields (every layer)
+
+```
+name, at, duration,
+initial: { ...props applied before any keyframe },
+keyframes: [ { at, duration, ease, set | to | from | (from + to), repeat?, yoyo?, repeatDelay? } ],
+filters: [ { type: 'chromaKey', keyColor, threshold, smoothing, spill } | { type: 'custom', name, filter: <Pixi Filter> } ],
+mask: <a layer spec>, maskInverted,   // a mask with no `at` of its own starts and ends with the layer it masks (its keyframes count from that layer's start); an explicit mask `at` is composition time
+filterArea: { x, y, width, height }   // in the layer's OWN coordinates; lets blur/glow draw past the layer's bounds
+threeD: true                          // opt into 2.5D (see below)
+blendMode: 'normal' | 'add' | 'screen' | 'multiply'   // add / screen brighten (glows, light leaks: overlapping halos add up); on a composition its children inherit the mode
+```
+
+Animatable props (`initial` / keyframes): `x y alpha rotation scale scaleX scaleY pivotX pivotY anchorX anchorY skewX skewY tint width height visible autoAlpha`, plus for shapes their style/geometry, for text `fill`, for audio `volume`, for 3D `z rotationX rotationY`, filter params as `'filters.<name>.<param>'`, three objects as `'three.<obj>.<path>'`.
+
+Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate to), `from` (animate from), `from`+`to`. `from` / `from+to` show their start value from the layer's start, so a delayed fade-in needs no `initial.alpha`. `repeat` (finite extra plays), `yoyo`, `repeatDelay` loop any of them (endless repeats are not allowed). `ease` = any GSAP ease (`'none'`, `'power2.out'`, `'expo.out'`, `'back.out(1.7)'`, `'elastic.out(1,0.5)'`, `'sine.inOut'`, `'bounce.out'`…). Default ease is linear.
+
+## Layer types
+
+**text** — `text`, `style` (any PixiJS TextStyle field: `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding`; expressions OK for numbers), `colorSpace`. Default anchor is **top-left**; use `anchorX/anchorY: 0.5` to centre on `x,y`. A text layer has one animatable number, `value`, printed where the text contains `{value}` (`text: '{value} users'`, `initial: { value: 0 }`, keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Other content cannot change over time. Multi-line text is centre-aligned by default (`style.align: 'left'` to change).
+
+**image** — `asset`, `tint`, `colorSpace: 'rgb'|'oklab'|'oklch'`. Default anchor top-left; natural size = `w`,`h`.
+
+**video** — `asset`, `loop`, `audio`, `volume`; `initial: { scale: 'cover' }`.
+
+**audio** — `asset`, `loop`, `volume`; fade with volume keyframes (`{ at: -2, to: { volume: 0 }, duration: 2 }` fades the last 2 s). **Omit `duration` for a one-shot sound effect: it lasts exactly as long as its clip.** With `loop: true` and no `duration` it lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true`.
+
+**shape** — `shape: 'rect' | 'circle' | 'ellipse' | 'line' | 'polygon' | 'path'`:
+
+| shape | geometry (top level **or** in `initial`) |
+|---|---|
+| rect | `width height cornerRadius anchorX anchorY` |
+| circle | `radius anchorX anchorY` |
+| ellipse | `radiusX radiusY anchorX anchorY` |
+| line | `from: [x,y]  to: [x,y]` — plain canvas coordinates (omit `x,y`; if you give them they place the line's midpoint). Stroke in `initial`: `strokeColor`, `strokeWidth` |
+| polygon | `points: [[x,y],…]  open` — canvas coordinates like `line` |
+| path | `d` (SVG path data) — canvas coordinates like `line` |
+
+Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha strokeWidth`; `colorSpace: 'oklab'|'oklch'` for clean colour tweens. rect/circle/ellipse are **centred on `x,y` by default** (`anchorX/anchorY` default 0.5): for a bar growing from its base use `anchorY: 1` (or `anchorX: 0` for left-to-right). **`fillGradient`** (top level or `initial`; instead of `fillColor`): `{ type?: 'linear'|'radial', stops: [[0, '#000'], [1, 'rgba(0,0,0,.6)']], angle? /* linear, deg, 90 = top→bottom */, center?, innerRadius?, radius? /* radial, 0–1 of bounds */ }` — stops may have alpha, so a radial transparent→dark is a vignette.
+
+**composition** — `width height duration sequences transitions`. With `threeD: true` it is a **card**: its children are drawn into one texture (content outside its `width × height` is clipped: size it for a soft shadow too) and move / rotate in depth together. Children use the composition's local coordinates and times. Position/rotate/scale it as a unit; to rotate/scale about its centre set `pivotX/pivotY` to the centre and `x/y` to where that point should sit.
+
+**camera** (2.5D) — props in `initial`/keyframes: `x y z lookAtX lookAtY lookAtZ fov` (defaults: centred, looking at the z = 0 plane, `fov` 40, `z` auto = `(H/2)/tan(fov/2)` ≈ 989 at 720p). Never on the camera object itself. An orbit is `orbit()`; by hand: `x = cx + R·sin θ`, `z = R·cos θ`, `R = (H/2)/tan(fov/2)`, `lookAt` = the centre at `z = 0`.
+
+**three** (optional entry `pixi-effects/three`) — `three({ type:'three', width, height, setup(ctx) { …; return { objects: { knot } } }, update?, dispose? })`; drive with `'three.knot.rotation.y'` keyframes. Call `registerThree()` before `init`.
+
+## 2.5D in one paragraph
+
+Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY` (centre rotation with `anchorX/Y: 0.5` or `pivotX/Y`). Add a `{ type: 'camera' }` layer for a view. A `threeD` layer at `z: 0` with the default camera looks identical to a 2D one. Consecutive `threeD` layers are drawn farthest-first (equal `z` keeps array order); non-`threeD` layers ignore the camera and keep array order. Layers at/behind the camera plane are hidden. Not supported on `threeD` layers: masks, transitions, `filterArea`.
+
+## Transitions (on the parent composition)
+
+```js
+transitions: [{ kind: 'crossfade' | 'wipe' | 'iris' | 'slide' | 'dip' | 'zoom' | 'dissolve',
+                from: 'nameA', to: 'nameB', at: 3, duration: 1, ease: 'none',
+                direction: 'left|right|up|down' /* wipe, slide */, mode: 'in|out' /* iris, zoom */,
+                smoothing, fromScale /* zoom */, scale, seed /* dissolve */ }]
+```
+`from`/`to` are sibling layer `name`s, `to` declared after `from`, and both layers must be alive for the whole window (overlap them by `duration`). Only those two layers are affected; every other layer stays put. Wipe/iris/dissolve/zoom wrap the layers for you.
+
+## Presets
+
+```js
+import { kenBurns, withFade } from 'pixi-effects';
+kenBurns({ asset, name, at, duration, motion: 'still'|'scale'|'rotation'|'position',
+           fit: 'cover'|'contain', ease, /* scale */ origin, zoom, direction, /* rotation */ angle, /* position */ from, to })
+withFade(spec, { in: 0.5, out: 0.5 })   // alpha fade; `out` needs spec.duration
+orbit({ duration: 6, degrees: 40 /* , radius, center, start, fov, ease, at */ })   // a camera layer that circles a point
+```
+`kenBurns` covers the canvas, so source images should be at least canvas-sized (1920×1080 for 1280×720).
+
+## Assets
+
+`assets: [{ name, src }]` in `movie.init` (images, audio, video). `src` may be a URL or a `data:`/`blob:` URL (e.g. `canvas.toDataURL()`).
+
+## Movie API
+
+```js
+const movie = new Movie();
+await movie.init({ canvas, width, height, duration, frameRate, background, assets, composition });
+movie.play(); movie.pause();
+await movie.gotoFrame(n, true);                 // seek (frames; 30 fps => t = n/30)
+const blob = await movie.render({ format: 'mp4' });   // 'mp4' | 'webm' | 'mov' | 'mkv'; ~real-time
+movie.on('progress', e => e.progress /* 0–100 */);
+movie.audioBuffer                                // mixed audio (after init), if any audio layers
+await movie.contactSheet({ count: 6, as: 'dataURL' })   // ONE image of several labelled frames — look at it. Options: frames | times | count, columns, cellWidth, as
+await movie.snapshot(60, { as: 'dataURL' })             // one frame, canvas only (no player bar) — use it for detail; sheet tiles are small
+await movie.inspect(60, { layers: 'none' })             // issues only (default lists the visible layers); text off-canvas / cut off / empty / overlapping text. Name your layers so paths are readable
+new Controller(movie, { canvas })                // optional player bar (overlays the canvas bottom ~60px; not in the export)
+```
+
+
+<!-- ===== ai/reference/pitfalls.md ===== -->
+
+# pixi-effects pitfalls — what actually went wrong
+
+Collected by having fresh AI sessions build pieces from the docs alone: first six (kinetic type, news lower-third, slideshow, 2.5D showcase, three.js title, bar chart), then a portfolio of 16 more (items 32 and up), made by three different models. Each entry is a real stumble. **Status**: `fixed` = the library now handles or warns; `docs` = nothing can catch it, so remember it; `hand-roll` = the DSL has no feature, see the workaround.
+
+A good habit that catches most of these: after `init`, read `window.__logs` (see `ai/template.html`) — every pixi-effects warning says what to change.
+
+## Time
+
+1. **Keyframe `at` starts at 0 when THIS layer appears** *(fixed in 0.3.0; earlier versions measured from the composition and failed silently)*. A layer at `at: 2` with a keyframe `at: 0` animates at global 2 s. Negative `at` counts back from the layer's end. A keyframe that starts after its layer ends now warns ("never plays").
+2. **A layer's own `at` and a transition's `at` are composition time** (seconds from the parent composition's start). Only keyframes are layer-local.
+3. **Layers are hidden, not removed, after `[at, at+duration)`** and keep their last values. Z-order is array order (later = on top). To switch scenes, stack scenes with `at`/`duration`, each starting with an opaque full-screen rect. *(docs)*
+4. **Transitions need overlapping lifespans.** Both layers must be alive for the whole window: scene `i` starts at `i·(L−T)`, the transition's `at` is the next scene's start, total = `n·(L−T)+T`. A scene that ends while the transition is still running leaves a gap. *(docs)*
+5. **Audio length.** Omit `duration` on a one-shot sound effect: the layer lasts exactly as long as its clip (pop 0.13 s, click 0.1 s, chime 0.6 s, swoosh 0.55 s; nothing to measure). `loop: true` with no `duration` lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true` (`bgm.mp3` is 6 s) and warns. Volume fades work like any keyframe: `volume: 0` + `{ at: 0, to: { volume: v }, duration: 2 }` + `{ at: -2, to: { volume: 0 }, duration: 2 }` (the last 2 s only; `set` is a jump). *(fixed: volume keyframes used to ramp from the previous keyframe's end, so the music faded across the whole piece)*
+6. **Snap times to the frame grid (`Math.round(t*30)/30`) when two things must stay locked** (a bar and its label). Drive both from one JS easing function with per-frame `set` keyframes rather than mixing a tween with computed positions. *(docs)*
+7. **Pick eases on purpose.** `expo.in` stays tiny until the very end (a "flood" circle never reaches the corners — use a bigger radius and `power2.in`). A zoom transition with `power2.out` looks like a cut because the incoming scene is nearly opaque after 40 %. Default is linear. *(docs)*
+8. **`render()` runs in roughly real time** (6 s of 720p ≈ 6 s). Listen to `movie.on('progress', e => e.progress)` (0–100). *(docs)*
+
+## Layout and anchors
+
+9. **Defaults differ by type.** rect/circle/ellipse are centred on `x,y`; text and image are top-left; a composition has no anchor — use `pivotX/pivotY` and set `x,y` to where the pivot should land. For a bar growing from its base use `anchorY: 1` (or `anchorX: 0`). *(docs)*
+10. **Shape geometry may be at the top level or in `initial`** (`width height radius anchorX …`). *(fixed: `initial` used to be silently ignored)*
+11. **Angles are degrees** — `rotation`, `skew*`, `rotationX/Y` — and `rotation: -0.2` is almost no rotation. *(docs)*
+12. **Text**: anchor 0.5 centres the line *box*, not the cap height (an underline under serif or italic text needs ~`0.9·size` below the centre: `0.46·size` touches the descenders of a g or y). Arial Black is ~0.8·size wide per glyph, monospace ~0.6·size; leave ~7 % for hold-scale. `style` accepts any PixiJS TextStyle field: `letterSpacing`, `wordWrap` + `wordWrapWidth`, `lineHeight`, `stroke`, `dropShadow`, `padding`. A glow (`dropShadow` with `blur`) is clipped unless `padding ≥ 2·blur`. *(docs)*
+13. **`w` / `h` in expressions** are the layer's own size. For text they now describe the styled text (`x: '-w'` scrolls a marquee fully out). *(fixed)*
+14. **Masks live in the parent's coordinate space and do not follow the masked layer.** Reveal by growing the mask's `width` from a fixed edge (`anchorX: 0`); exit by tweening `x` and `width` together; slide the content separately. *(docs)*
+15. **`line` / `polygon` / `path` use plain canvas coordinates** when you give no `x,y` (they used to be drawn around (0,0)); with `x,y` those place the shape's centre. Stroke colour and width go in `initial`. A background pill must be sized from its text (~0.58 × fontSize per glyph + padding): `inspect` does not check text against shapes. *(fixed)*
+15b. **`filterArea` is in the layer's own coordinates** (origin = its local origin, e.g. a circle's centre), not the parent's. A blurred shape is clipped to its bounding box without it: `filterArea: { x: -(r+260), y: -(r+260), width: 2*(r+260), height: 2*(r+260) }`. `threeD` layers pad automatically. *(docs)*
+16. **The player bar overlays the bottom ~60 px of the canvas** in browser screenshots (not in the exported video). `movie.snapshot()` / `movie.contactSheet()` never include it; keep captions above it anyway. *(fixed: use the built-in snapshot tools)*
+
+## Missing features (hand-roll)
+
+17. **Gradients / vignettes**: use shape `fillGradient` (linear or radial, stops may have alpha). Earlier sessions hand-rolled canvas images or dozens of stacked bands. *(fixed)*
+18. **Counters**: `text: '{value}'` + animate `value` (with `format`). Other text content cannot change over time. Earlier sessions generated one text layer per number (40+ per bar). *(fixed)*
+19. **Loops**: `repeat` (finite) / `yoyo` / `repeatDelay` on any keyframe; infinite repeats are rejected with a warning. *(fixed)*
+20. **No per-frame expression time.** Expressions are evaluated once at build. A camera orbit is `orbit()`; any other curve (waves, spirals) must be sampled into short linear keyframes (~0.1 s) in a JS loop. *(partly fixed)*
+21. **No text split / per-letter animator, no group/null parent, no particle emitter, no blend modes, no caption-linked-to-slide.** One layer per letter; many layers; seeded random loops; plain alpha. *(hand-roll)*
+22. **Colour tweens look muddy in RGB** (red→green passes through brown). Use `colorSpace: 'oklab'` or `'oklch'` on the layer. *(docs)*
+23. **Generated images**: `canvas.toDataURL()` as an asset `src` works. Make them ≥ canvas size or `kenBurns` zooms look soft. *(docs)*
+
+## 2.5D / three.js
+
+24. **`threeD` is required** for `z`, `rotationX`, `rotationY` (they warn otherwise). Camera props go in `initial`/keyframes, never on the camera object. `+z` is toward the viewer. *(fixed: warns)*
+25. **A layer at/behind the camera plane is hidden** — the default camera sits at `z = (H/2)/tan(fov/2)` ≈ 989 at 720p, fov 40 (≈ 808 at fov 48, lower at higher fov). Keep every layer's `z` below it. *(fixed: warns once)*
+26. **Under a dolly zoom only the `z = 0` plane stays put**; everything nearer balloons and clips. Headline at `z: 0`, near cards `z ≤ ~70`. Perspective also pulls far layers toward the centre: put far cards at the outer x, near cards inward, and keep ~10 % margin for an orbit sweep. `orbit({ dollyZoom: { from, to } })` does both together. *(docs)*
+27. **Combining orbit and dolly zoom**: `orbit()` specifies `z`, so it stops following `fov` — write your own `fov` and `z = (H/2)/tan(fov/2)` keyframes for the zoom. *(docs)*
+28. **Nearer `threeD` layers sort on top of text** — lay out around them; equal `z` keeps array order. A card (rect + icon + label that move together) is a `composition` with `threeD: true`. A final call-to-action or overlay should be a plain 2D layer (last in the array): it ignores the camera, and fade the 3D scene and headline out before it appears (a dim rect alone leaves them visible). *(docs)*
+29. **three.js**: the layer clips at its own rectangle — size it to the area you want and pull the camera back (`z ≈ 5.4` for a radius-1 torus knot at fov 50). Metal needs an environment map (`PMREMGenerator(ctx.renderer)`); `three/addons` is not in the importmap. Route `three` through the importmap so there is one copy. Masks/transitions/`filterArea` are not supported on `threeD` layers. *(docs)*
+
+## Tooling (agent harness)
+
+30. **A scene change must keep the outgoing scene alive until the covering flood / wipe has finished**, and the next scene starts when it is complete; the flood circle must reach the corners (radius ≥ half the diagonal) and use `power2.in`, not `expo.in`. *(docs)*
+30b. **Unknown option names now warn** (`contactSheet({ cols: 2 })` → did you mean `columns`; `init({ fps })` → `frameRate`). Layer names show up in `inspect` paths, so give layers a `name`. `inspect` ignores faint (alpha < 0.3) layers and text whose x / y is animated (tickers), so a scrolling marquee is not reported as cut off. Pixi may print `[BindGroup] … destroyed while still bound` warnings at `movie.destroy()`: harmless (playback and seeking never warn). *(docs)*
+30c. **Look with the built-in tools, not OS screenshots**: `await movie.contactSheet({ count: 6, as: 'dataURL' })` returns one labelled image of the whole animation; `await movie.inspect(frame)` returns every layer's canvas bounds and `issues`. If you do use a browser tool, `screenshot` needs an **absolute path**, macOS `sed -i` needs `''`, and a static server may redirect `/x.html` → `/x` and drop `?query`. Keep the template's `try/catch` around `init` so failures land in `window.__logs`. Check ≥ 5 timestamps including mid-transition. *(fixed: tools built in)*
+31. **Check audio without rendering by decoding the render**: `const b = await movie.render({format:'mp4'})` then `new OfflineAudioContext(...).decodeAudioData(await b.arrayBuffer())` and measure RMS over time. `movie.audioBuffer` holds the mix. *(docs)*
+
+## Round 2 — found by building 16 portfolio pieces (examples/gallery)
+
+32. **Seeking is safe now** *(fixed)*: a `set` keyframe (counter value, text fill, image tint, shape style) is undone when you seek back before it, and shapes are redrawn before they are culled, so a rect growing from `width: 0` at the left edge draws after any jump seek (contact sheet, snapshot, scrubbing, export). The old workarounds (`width: 0.01`, a one-frame `to` instead of `set`) are not needed.
+33. **A mask starts and ends with the layer it masks** *(fixed)*, so its keyframes count from that layer's start. A mask with an explicit `at` keeps composition time. Before, a mask `at: 0` reveal had finished before a layer that appeared at 8 s, and the layer stayed invisible without any warning.
+34. **`from` and `from+to` show their start value from the LAYER's start**, not from the keyframe's `at` (GSAP behaviour): a delayed fade-in `{ at: 2, from: { alpha: 0 }, to: { alpha: 1 } }` needs no `initial.alpha`. To keep the current value until `at` and then jump, use `set`. *(docs)*
+35. **One `Movie` per page.** Creating a second Movie (for an isolated repro) and destroying it breaks the first (`null.clear`). Reload instead. *(docs)*
+36. **Multi-line text is centre-aligned by default** (`style.align: 'left'` for left-aligned paragraphs). *(docs)*
+37. **A `threeD` composition (a card) clips its children at its own width × height.** Size the card for its soft shadow too. A growing `threeD` shape or text is fine: its texture is resized in place (it used to warn "destroyed while still bound"). *(docs / fixed)*
+38. **Under an orbit the side the camera swings toward becomes the NEAR side**: a "far" card at `z: −200` can be drawn bigger than 1× on that side and run off the frame (`inspect` only checks text). Pull those cards inward / lower `z`, and check a frame at the extreme of the sweep. After `orbit()` ends the default camera returns, so to hold the final pose add a camera layer that starts there. Near particles balloon under a dolly zoom: cap particle `z` at about +150, or one becomes a fake full stop. *(docs)*
+39. **`fillGradient` stops span the whole unmasked shape**, not the visible part: under a mask, place the stops for the visible fraction (e.g. 0.64→1). A translucent shape over near-black reads as grey: put the alpha in the gradient stops. *(docs)*
+40. **Rotate a polygon / path about a chosen point** by wrapping it in a `composition` with `pivotX/pivotY` (its centre is otherwise the bounds centre). *(docs)*
+41. **Glow a whole set of layers** by putting them in one `composition` with a blur filter and `filterArea` (only a composition carries a filter for its children): wide enough for the blur, and the set is built once, so the extra copy is just a second group. *(docs)*
+42. **Transition looks:** the default `dissolve` reads as a hard black-and-white camouflage and `scale: 220` as static; `scale: 90, smoothing: 0.5` is a soft film dissolve. The default edge softness of `iris` (0.02) and `wipe` blurs flat graphics at 720p: `smoothing: 0.004`–`0.01` gives a clean edge. *(docs)*
+43. **Layers built in a loop need their z-order planned**: anything pushed to the array after the loop is drawn over what the loop made (rings crossed over a header). Keyframes on different properties of one layer may overlap in time. Keep a subject in the upper ~60 % of a source image if a caption will sit under it (`inspect` does not look at picture content). *(docs)*
+44. **`{value}` has no number padding**: a clock or timecode cannot show `:05`. Keep the value in a range that always has the same digit count, or split digits into two counters. *(hand-roll)*
+45. **The same mistake in a loop warns once**: the warning "keyframe starts after the layer ends" is summarised after three layers. The usual cause is an off-by-one (`f <= frames` instead of `f < frames`) that puts the last sample exactly at the layer's end. *(fixed)*
+46. **Still not in the DSL (hand-roll; round-two notes have workarounds):** arc / progress-ring primitive and stroke draw-on / trim path (use a growing rect mask for a one-direction reveal, tick marks, or pre-drawn arcs shown one per frame), text content that changes over time (only `{value}`), per-frame jitter (film grain = seeded `set` keyframes on an oversized image), particle emitters, per-letter / per-line text split (measure with `canvas.measureText` using Pixi's font string), shared masks, `zIndex`.
+46b. **Blend modes exist now** (`blendMode: 'add' | 'screen' | 'multiply'` on any layer, threeD layers and compositions included; a composition's children inherit it). Additive white cores no longer read grey on a coloured background. *(fixed)*
+47. **Browser tooling:** the `agent-browser` daemon is shared, so a `contactSheet` can come back from another session: after saving an image, look at it and confirm it is YOUR piece. In zsh a variable holding `agent-browser --session x` is not split into words (use a small wrapper script). `inspect` now clips overlaps to the visible area and ignores the two scenes of a running transition; it still does not compare text with picture content or shapes.
+48. **A composition's `alpha` is applied to each child separately, not to the flattened group** (measured: two overlapping opaque circles in a composition at `alpha: 0.5` show the lower one through the upper one in the overlap). Fading a group that has overlapping children therefore shows the overlap; fade the children themselves, or keep overlapping parts out of the group. Expressions have no way to read a sibling's size: measure text with `canvas.measureText` (the font string Pixi uses) and compute pill widths in JS. *(docs)*
+
+
+<!-- ===== ai/reference/recipes.md ===== -->
+
+# pixi-effects recipes
+
+Copy, adapt, run. Every block marked `@recipe` is a function body that **returns the composition's `sequences`** (or `{ sequences, transitions, duration }`); the repo's tests build each one and fail on any warning, so they stay correct. Blocks marked `@docs-only` need a browser (canvas / three.js) and are not executed by the tests.
+
+Assumed canvas: 1280×720 @ 30 fps. `kenBurns`, `withFade` and `orbit` come from `pixi-effects`.
+
+---
+
+## Words that slam in on the beat (kinetic type)
+
+Slam = big scale + tiny rotation easing out fast, plus a white flash rect on the beat. Keyframe `at` is local to the layer, so every word's keyframes start at `0`.
+
+```js
+// @recipe slam-words
+const WORDS = [['KAFFE', '#ffd166'], ['NORD', '#ef476f'], ['ROAST', '#06d6a0']];
+const BEAT = 0.5;                                    // seconds per beat
+const sequences = [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#111111' } },
+];
+WORDS.forEach(([word, color], i) => {
+  const at = i * BEAT * 2;
+  sequences.push({
+    type: 'text', text: word, at, duration: BEAT * 2,
+    style: { fontSize: 'GH * 0.4', fontWeight: '900', fill: color, fontFamily: 'Arial Black, Arial, sans-serif' },
+    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+    keyframes: [{ at: 0, from: { scale: 2.6, rotation: -5, alpha: 0 }, to: { scale: 1, rotation: 0, alpha: 1 }, duration: 0.16, ease: 'expo.out' }],
+  });
+  sequences.push({                                   // white flash on the beat
+    type: 'shape', shape: 'rect', width: 'GW', height: 'GH', at, duration: 0.3,
+    initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ffffff', alpha: 0.8 },
+    keyframes: [{ at: 0, to: { alpha: 0 }, duration: 0.28 }],
+  });
+});
+return sequences;
+```
+
+Size text by eye: Arial Black glyphs are ~0.8 × fontSize wide, monospace ~0.6 ×. Leave ~7 % of the frame for a hold-scale.
+
+---
+
+## Lower-third revealed by a wipe mask
+
+A `mask` is a layer in the **parent's** coordinate space and does **not** move with the layer it masks: reveal by growing the mask's `width` from a fixed left edge (`anchorX: 0`); exit by moving the left edge to the right while the width shrinks to 0. Rects are centred by default, hence `anchorX: 0`.
+
+```js
+// @recipe lower-third
+const bar = (name, y, w, h, color, at) => ({
+  type: 'shape', shape: 'rect', name, width: w, height: h, anchorX: 0, at, duration: 3.6,
+  initial: { x: 80, y, fillColor: color },
+  mask: {
+    type: 'shape', shape: 'rect', width: 0, height: h, anchorX: 0,
+    initial: { x: 80, y, fillColor: '#ffffff' },
+    keyframes: [
+      { at: 0, to: { width: w }, duration: 0.5, ease: 'power3.out' },                    // reveal
+      { at: -0.5, to: { x: 80 + w, width: 0 }, duration: 0.5, ease: 'power3.in' },        // exit
+    ],
+  },
+});
+return [
+  bar('name-bar', 600, 520, 56, '#e63946', 0.2),
+  bar('title-bar', 656, 420, 40, '#1d3557', 0.35),
+  { type: 'text', text: 'JANE DOE', at: 0.5, duration: 3, style: { fontSize: 34, fontWeight: 'bold', fill: '#ffffff' },
+    initial: { x: 100, y: 600, anchorX: 0, anchorY: 0.5, alpha: 0 },
+    keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }, { at: -0.4, to: { alpha: 0 }, duration: 0.3 }] },
+];
+```
+
+---
+
+## A ticker that scrolls out completely (`w` = the text's own width)
+
+`'-w'` is the exact x at which the text has left the screen on the left (`w` is measured after the style is applied).
+
+```js
+// @recipe marquee
+return [{
+  type: 'text', text: 'BREAKING NEWS  •  MARKETS RALLY  •  NEW RECORD SET', duration: 8,
+  style: { fontSize: 30, fontWeight: 'bold', fill: '#ffffff' },
+  initial: { x: 'GW', y: 670, anchorX: 0, anchorY: 0.5 },
+  keyframes: [{ at: 0, to: { x: '-w' }, duration: 8, ease: 'none' }],
+}];
+```
+
+---
+
+## Numbers that count up
+
+A text layer has an animatable number, `value`, printed wherever the text has `{value}`. Animate it with ordinary keyframes (ease, `from`/`to`, `repeat`).
+
+```js
+// @recipe count-up
+return [{
+  type: 'text', text: '{value}', format: { grouping: true },            // → "2,480"   (decimals: 0 by default)
+  style: { fontSize: 96, fontWeight: 'bold', fill: '#ffffff' },
+  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5, value: 0 },
+  keyframes: [{ at: 1, to: { value: 2480 }, duration: 1.2, ease: 'power3.out' }],
+}];
+```
+
+Prefixes and suffixes go in the text (`'${value}'`, `'{value} users'`, `'{value}%'`). If a bar must stay locked to its counter, give both the same `at`, `duration` and `ease` — see the bar chart below.
+
+---
+
+## Data-driven bar chart
+
+Generate the whole spec from the data. Bars grow from the baseline (`anchorY: 1` + a `height` keyframe); each value label rides the top of its bar and counts up with the same ease and timing, so they stay locked. A line's `from` / `to` are plain canvas coordinates (give `x,y` only to move it). A callout pill must be sized from its text.
+
+```js
+// @recipe bar-chart
+const data = [['Mon', 12], ['Tue', 30], ['Wed', 22], ['Thu', 41], ['Fri', 35]];
+const max = Math.max(...data.map(d => d[1]));
+const step = [1, 2, 2.5, 5, 10].map(m => m * 10 ** Math.floor(Math.log10(max / 4))).find(v => max / v <= 5) ?? 10;
+const NICE = Math.ceil(max / step) * step;                    // axis top, so the chart survives changed data
+const BASE = 600, CHART_H = 380, BAR_W = 90, GAP = 40, DUR = 0.9, EASE = 'power3.out';
+const X0 = (1280 - (data.length * BAR_W + (data.length - 1) * GAP)) / 2, X1 = X0 + data.length * BAR_W + (data.length - 1) * GAP;
+const sequences = [];
+for (let v = 0; v <= NICE; v += step) {                       // grid lines + tick labels
+  const y = BASE - CHART_H * v / NICE;
+  sequences.push({ type: 'shape', shape: 'line', from: [X0 - 20, y], to: [X1 + 20, y], initial: { strokeColor: '#33405c', strokeWidth: 1 } });
+  sequences.push({ type: 'text', text: String(v), style: { fontSize: 20, fill: '#7f8bb0' }, initial: { x: X0 - 32, y, anchorX: 1, anchorY: 0.5 } });
+}
+const best = data.findIndex(d => d[1] === max);
+data.forEach(([label, value], i) => {
+  const x = X0 + i * (BAR_W + GAP) + BAR_W / 2;
+  const at = 0.4 + i * 0.12;
+  const h = CHART_H * value / NICE;
+  sequences.push({
+    type: 'shape', shape: 'rect', width: BAR_W, height: 0, cornerRadius: 8, anchorY: 1, at, colorSpace: 'oklab',
+    initial: { x, y: BASE, fillColor: '#4f6df5' },
+    keyframes: [
+      { at: 0, to: { height: h }, duration: DUR, ease: EASE },
+      ...(i === best ? [{ at: 4 - at, to: { fillColor: '#ffd166' }, duration: 0.5 }] : [{ at: 4 - at, to: { alpha: 0.45 }, duration: 0.5 }]),   // highlight the maximum at t = 4 s
+    ],
+  });
+  sequences.push({                                            // value label: counts up while riding the bar's top
+    type: 'text', text: '{value}', at,
+    style: { fontSize: 28, fontWeight: 'bold', fill: '#ffffff' },
+    initial: { x, y: BASE - 14, anchorX: 0.5, anchorY: 1, value: 0 },
+    keyframes: [{ at: 0, to: { value, y: BASE - h - 14 }, duration: DUR, ease: EASE }],
+  });
+  sequences.push({ type: 'text', text: label, at, style: { fontSize: 26, fill: '#aab4d4' }, initial: { x, y: BASE + 16, anchorX: 0.5, anchorY: 0 } });
+});
+// callout: a pill sized from its text (~0.58 x fontSize per glyph + padding), a pointer triangle, clamped inside the plot
+const text = 'Peak: ' + data[best][0] + ' ' + max, FS = 26;
+const PW = text.length * FS * 0.58 + 44, cx = Math.min(Math.max(X0 + best * (BAR_W + GAP) + BAR_W / 2, X0 + PW / 2), X1 - PW / 2), cy = BASE - CHART_H - 70;
+sequences.push({ type: 'shape', shape: 'rect', width: PW, height: 52, cornerRadius: 26, at: 4.2, initial: { x: cx, y: cy, fillColor: '#ffd166', alpha: 0 },
+                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
+sequences.push({ type: 'shape', shape: 'polygon', points: [[-10, 0], [10, 0], [0, 12]], at: 4.2, initial: { x: cx, y: cy + 32, fillColor: '#ffd166', alpha: 0 },
+                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
+sequences.push({ type: 'text', text, at: 4.2, style: { fontSize: FS, fontWeight: 'bold', fill: '#1b1b2f' }, initial: { x: cx, y: cy, anchorX: 0.5, anchorY: 0.5, alpha: 0 },
+                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
+return sequences;
+```
+
+---
+
+## Letters that fly in from depth (2.5D title)
+
+One `threeD` text layer per letter, staggered; monospace so the advance is predictable (~0.6 × fontSize). `fov` eases while `z` auto-follows it, so the `z = 0` plane (the title) stays put. Letters start at `z: 560`, which must stay **below the camera distance** (≈ 808 at `fov` 48) or they are hidden. `dropShadow` glow needs `padding` (≥ 2 × blur).
+
+```js
+// @recipe depth-title
+const TEXT = 'PIXI EFFECTS', SIZE = 118, ADV = SIZE * 0.602;
+const letters = [...TEXT].flatMap((ch, i) => ch === ' ' ? [] : [{
+  type: 'text', text: ch, threeD: true,
+  style: {
+    fontSize: SIZE, fontWeight: '800', fill: '#3de0ff',
+    fontFamily: "ui-monospace, 'SF Mono', Menlo, Consolas, monospace",
+    dropShadow: { color: '#5b6cff', blur: 20, distance: 0, alpha: 0.9 }, padding: 48,
+  },
+  initial: { x: 640 + (i - (TEXT.length - 1) / 2) * ADV, y: 330, anchorX: 0.5, anchorY: 0.5, z: 560, rotationY: 75, rotationX: -45, alpha: 0 },
+  keyframes: [
+    { at: 0.55 + i * 0.075, to: { z: 0, rotationY: 0, rotationX: 0 }, duration: 1.0, ease: 'expo.out' },
+    { at: 0.55 + i * 0.075, to: { alpha: 1 }, duration: 0.3 },
+    { at: 0.7 + i * 0.075, to: { fill: '#f4f6ff' }, duration: 0.8, ease: 'sine.out' },      // colour flash on landing
+  ],
+}]);
+return [
+  { type: 'camera', initial: { fov: 48 }, keyframes: [{ at: 0, to: { fov: 34 }, duration: 6.5, ease: 'sine.inOut' }] },
+  ...letters,
+];
+```
+
+---
+
+## Camera orbit (+ optional dolly zoom)
+
+`orbit()` returns a camera layer that circles a point (the circle is sampled into short linear keyframes; the ease applies to the angle). Add `dollyZoom: { from, to }` and `fov` animates while the radius follows it, so the `z = 0` plane keeps its size and only the perspective changes. Under a dolly zoom everything with `z > 0` balloons toward the viewer: keep the hero content at `z = 0` and near content at small `z`; far layers are pulled toward the centre, so spread far cards to the outer x positions and near cards inward, and leave ~10 % margin for the orbit sweep.
+
+```js
+// @recipe camera-orbit
+const card = (x, z, color) => ({
+  type: 'shape', shape: 'rect', width: 300, height: 200, cornerRadius: 20, threeD: true,
+  initial: { x, y: 360, z, fillColor: color },
+});
+return [
+  orbit({ duration: 6, degrees: 50, dollyZoom: { from: 38, to: 62 } }),    // options: radius (not with dollyZoom), center, start, fov, ease
+  card(240, -300, '#3a6ea5'), card(640, 0, '#d96a3a'), card(990, 60, '#38a169'),     // near cards stay at small z
+];
+```
+
+A call-to-action or any overlay that must stay screen-aligned should be a plain 2D layer (no `threeD`) placed last: it ignores the camera and stays on top. Fade the 3D scene and headline out before it appears; a dim rect alone leaves them visible.
+
+---
+
+## A card in depth (a composition with `threeD: true`)
+
+A `composition` with `threeD: true` is a card: its children are drawn into one texture that is then moved in depth, so a rect, an icon and a label rotate and scale together. `threeD` layers at the same `z` keep array order. Entrance from depth, then a gentle bob with `repeat` / `yoyo`.
+
+```js
+// @recipe depth-cards
+const card = (title, color, x, y, z, at) => ({
+  type: 'composition', name: title, at, width: 300, height: 190, threeD: true,
+  initial: { x, y, z, pivotX: 150, pivotY: 95 },                       // pivot = the centre, so x,y is where the centre sits
+  sequences: [
+    { type: 'shape', shape: 'rect', width: 300, height: 190, cornerRadius: 24, initial: { x: 150, y: 95, fillColor: color } },
+    { type: 'text', text: title, style: { fontSize: 34, fontWeight: 'bold', fill: '#ffffff' }, initial: { x: 150, y: 95, anchorX: 0.5, anchorY: 0.5 } },
+  ],
+  keyframes: [
+    { at: 0, from: { alpha: 0, z: z - 400, rotationY: 55 }, to: { alpha: 1, z, rotationY: 0 }, duration: 0.9, ease: 'expo.out' },
+    { at: 1, to: { y: y - 14 }, duration: 1.2, ease: 'sine.inOut', repeat: 3, yoyo: true },
+  ],
+});
+return [
+  { type: 'camera', initial: { fov: 42 } },
+  card('Battery', '#3a6ea5', 220, 300, -280, 0.2),         // far cards at the outer x
+  card('Sound', '#d96a3a', 1060, 260, -200, 0.4),
+  card('Comfort', '#38a169', 640, 380, 0, 0.6),
+];
+```
+
+---
+
+## Cut to the next scene with an expanding circle
+
+The outgoing scene must stay alive until the covering shape has finished; the next scene starts when the flood is complete. Reach the far corners: radius ≥ half the diagonal (734 px at 720p). `expo.in` stays tiny until the very end — use `power2.in`.
+
+```js
+// @recipe scene-flood
+const FLOOD_AT = 3, FLOOD = 0.6, END = 6;
+return [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', duration: FLOOD_AT + FLOOD, initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1d2b53' } },
+  { type: 'text', text: 'BEFORE', duration: FLOOD_AT + FLOOD, style: { fontSize: 160, fontWeight: '900', fill: '#ffffff' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 } },
+  { type: 'shape', shape: 'circle', radius: 0, at: FLOOD_AT, duration: END - FLOOD_AT, initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ffd166' },
+    keyframes: [{ at: 0, to: { radius: 820 }, duration: FLOOD, ease: 'power2.in' }] },
+  { type: 'text', text: 'AFTER', at: FLOOD_AT + FLOOD, duration: END - FLOOD_AT - FLOOD, style: { fontSize: 160, fontWeight: '900', fill: '#1d2b53' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5, alpha: 0 },
+    keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.25 }] },
+];
+```
+
+---
+
+## Slideshow with transitions and background music
+
+Scene `i` starts at `i × (L − T)` and overlaps the next by the transition length `T`; the transition's `at` is the next scene's start; total = `n × (L − T) + T`. Transitions and `kenBurns` combine freely. Captions are top-level layers (transitions never touch layers they do not name); keep them above the bottom ~60 px. `bgm.mp3` is only 6 s: **`loop: true`** or it falls silent.
+
+```js
+// @recipe slideshow
+const photos = ['p1', 'p2', 'p3'], L = 4, T = 1, STEP = L - T;
+const kinds = ['crossfade', 'wipe', 'zoom'];
+const total = photos.length * STEP + T;
+const sequences = photos.map((asset, i) =>
+  kenBurns({ asset, name: 'scene' + i, at: i * STEP, duration: L, motion: i % 2 ? 'position' : 'scale' }));
+const transitions = photos.slice(1).map((_, i) => ({
+  kind: kinds[i % kinds.length], from: 'scene' + i, to: 'scene' + (i + 1), at: (i + 1) * STEP, duration: T,
+  ...(kinds[i % kinds.length] === 'wipe' ? { direction: 'left' } : {}),
+}));
+photos.forEach((_, i) => sequences.push(withFade({
+  type: 'text', text: 'Scene ' + (i + 1), at: i * STEP + 0.5, duration: L - 1.5,
+  style: { fontSize: 44, fill: '#ffffff', dropShadow: { color: '#000000', blur: 6, distance: 2, alpha: 0.7 } },
+  initial: { x: 'GW/2', y: 600, anchorX: 0.5, anchorY: 0.5 },
+}, { in: 0.4, out: 0.4 })));
+sequences.push({ type: 'audio', asset: 'bgm', loop: true, volume: 0, duration: total,
+  keyframes: [{ at: 0, to: { volume: 0.8 }, duration: 2 }, { at: -2, to: { volume: 0 }, duration: 2 }] });
+return { sequences, transitions, duration: total };
+```
+
+Source images should be at least canvas-sized (`kenBurns` zooms in): draw generated images at 1920×1080 for a 1280×720 movie.
+
+---
+
+## Looping motion
+
+`repeat` (a finite count) and `yoyo` go on any keyframe. Total time = `duration × (repeat + 1)`.
+
+```js
+// @recipe pulse
+return [{
+  type: 'shape', shape: 'circle', radius: 40, duration: 6,
+  initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ff3b3b' },
+  keyframes: [{ at: 0, to: { scale: 1.15 }, duration: 0.5, ease: 'sine.inOut', repeat: 11, yoyo: true }],   // 12 plays x 0.5 s = 6 s
+}];
+```
+
+---
+
+## Particles (seeded, so every run and export is identical)
+
+```js
+// @recipe particles
+let seed = 7;
+const rnd = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
+return Array.from({ length: 40 }, () => {
+  const x = rnd() * 1280, y = 100 + rnd() * 620;
+  return {
+    type: 'shape', shape: 'circle', radius: 2 + rnd() * 4, duration: 6,
+    initial: { x, y, fillColor: '#ffffff', fillAlpha: 0.3 + rnd() * 0.5 },
+    keyframes: [{ at: 0, to: { y: y - 80 }, duration: 6, ease: 'none' }],
+  };
+});
+```
+
+---
+
+## Gradients and vignettes
+
+`fillGradient` fills a shape with a linear or radial gradient (positions are 0–1 of the shape's own bounds; colours can have alpha). A radial gradient from transparent to dark, on a full-screen rect placed last, is a vignette.
+
+```js
+// @recipe gradient-background
+return [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
+    fillGradient: { stops: [[0, '#1b2a6b'], [0.6, '#7b3fe4'], [1, '#ff6a88']] } },                  // top → bottom
+  { type: 'shape', shape: 'rect', width: 520, height: 200, cornerRadius: 30, initial: { x: 'GW/2', y: 'GH/2' },
+    fillGradient: { angle: 0, stops: [[0, '#00f5a0'], [1, '#00d9f5']] } },                          // left → right
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
+    fillGradient: { type: 'radial', radius: 0.75, stops: [[0.45, 'rgba(0,0,0,0)'], [1, 'rgba(0,0,0,0.7)']] } },   // vignette, last = on top
+];
+```
+
+---
+
+## Generated placeholder images (no photos available)
+
+Draw on a canvas and register `canvas.toDataURL()` as an asset (`data:` URLs work). Make the image at least canvas-sized (1920×1080 for a 1280×720 movie) so `kenBurns` zooms stay sharp.
+
+```js
+// @docs-only
+function placeholderPhoto(name, hueA, hueB, w = 1920, h = 1080) {
+  const c = Object.assign(document.createElement('canvas'), { width: w, height: h });
+  const g = c.getContext('2d');
+  const grad = g.createLinearGradient(0, 0, w, h);
+  grad.addColorStop(0, `hsl(${hueA} 70% 45%)`); grad.addColorStop(1, `hsl(${hueB} 70% 25%)`);
+  g.fillStyle = grad; g.fillRect(0, 0, w, h);
+  return { name, src: c.toDataURL() };
+}
+// await movie.init({ assets: [placeholderPhoto('p1', 210, 280), placeholderPhoto('p2', 10, 60)], composition: { … } })
+```
+
+---
+
+## Metallic three.js object
+
+`ctx.renderer` is a normal `WebGLRenderer`, so an environment map works; lights alone make `metalness: 1` look black. `three/addons` is not in the importmap: build the environment yourself. Size the layer to the area you want (it clips at its own rectangle) and pull the camera back (`z ≈ 5.4` for a radius-1 torus knot at fov 50).
+
+```js
+// @docs-only
+// registerThree();  const THREE = await import('three');
+three({
+  type: 'three', width: 'GW * 0.56', height: 'GH * 0.9', initial: { x: 'GW * 0.77', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+  setup: (ctx) => {
+    const env = new THREE.Scene();
+    for (const [x, y, z] of [[4, 4, 4], [-4, 2, -4], [0, -4, 4]]) {
+      const lamp = new THREE.Mesh(new THREE.BoxGeometry(2, 2, 2), new THREE.MeshBasicMaterial({ color: 0xffffff }));
+      lamp.position.set(x, y, z); env.add(lamp);
+    }
+    ctx.scene.environment = new THREE.PMREMGenerator(ctx.renderer).fromScene(env).texture;
+    const knot = new THREE.Mesh(new THREE.TorusKnotGeometry(1, 0.32, 128, 32), new THREE.MeshStandardMaterial({ color: 0xcfd8ff, metalness: 1, roughness: 0.25 }));
+    ctx.scene.add(knot);
+    ctx.camera.position.z = 5.4;
+    return { objects: { knot } };
+  },
+  keyframes: [{ at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 }],
+})
+```
+
+
+<!-- ===== docs/dsl.md ===== -->
+
+# DSL Reference
+
+This document describes the declarative composition spec that you pass to `Movie.init({ composition })`. Every shape is exported as a TypeScript type from `pixi-effects` for editor autocomplete.
+
+- [Composition](#composition)
+- [Sequences](#sequences)
+- [3D layers & camera](#3d-layers--camera)
+- [Assets](#assets)
+- [Keyframes](#keyframes)
+- [Expressions](#expressions)
+- [Filters](#filters)
+
+---
+
+## Composition
+
+A composition is a tree node that has a width, a height, a duration, and a list of child sequences. The root composition is what you pass to `Movie.init({ composition })`. Nested compositions appear inside a parent as a `{ type: 'composition' }` sequence.
+
+```ts
+interface CompositionSpec {
+  width?: number;        // pixels; defaults to Movie width
+  height?: number;       // pixels; defaults to Movie height
+  duration?: number;     // seconds; defaults to Movie duration
+  sequences?: SequenceSpec[];
+  // (also: name, at, initial, keyframes, filters — same as SequenceCommon below)
+}
+```
+
+Children of a nested composition use that composition's local coordinate system. `W`/`H` in the [scope](#expressions) refer to the **immediate parent**; `GW`/`GH` always refer to the root.
+
+---
+
+## Sequences
+
+Every sequence shares this base shape:
+
+```ts
+interface SequenceCommon {
+  name?: string;            // optional id, used for cross-references and debugging
+  at?: number;              // start time in seconds, measured from the start of the PARENT composition (default 0)
+  duration?: number;        // seconds; defaults to the parent's duration
+  initial?: Props;          // properties applied before any keyframes evaluate
+  keyframes?: Keyframe[];
+  filters?: FilterSpec[];
+}
+```
+
+### Timing at a glance
+
+| What | Measured from |
+|---|---|
+| a sequence's `at` | the start of its **parent composition** (the root composition starts at 0) |
+| a **keyframe's** `at` | the start of **its own sequence** (After Effects style): `at: 0` = the moment the layer appears. **Negative = back from the sequence's end** (`-0.5` = 0.5 s before it ends) |
+| a transition's `at` | the start of the **parent composition** (like a sequence's `at`) |
+| `audio` volume keyframes | the start of their own sequence (same rule as every other keyframe) |
+
+### Anchors and origins
+
+| Layer | Where `x, y` land by default | To change it |
+|---|---|---|
+| `shape` rect / circle / ellipse | the **centre** of the shape | `anchorX` / `anchorY` (0–1). A bar growing from its base: `anchorY: 1`; left to right: `anchorX: 0` |
+| `shape` line / polygon / path | the centre of the shape's bounds | — |
+| `text`, `image`, `video` | the **top-left** corner | `anchorX` / `anchorY: 0.5` to centre |
+| `composition` | its top-left corner | `pivotX` / `pivotY` = the point that sits at `x, y` and that rotation / scale turn about |
+
+Shape geometry (`width height radius anchorX …`) may be written at the top level or in `initial`; the top level wins. `rotation`, `skew*` and `rotationX/Y` are in **degrees**.
+
+A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is only hidden, and it keeps its last animated values. Outside the lifespan it is invisible. **z-order is array order** (later = on top). Build scenes by giving layers `at` / `duration` and stacking them; a full-screen background rect in each scene hides what is below it.
+
+`Props` is `Record<string, number | string>`. String values are evaluated as [expressions](#expressions) unless the prop is a textual one (e.g. `fill`, `fontFamily`).
+
+### `text`
+
+Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content cannot change over time, with one exception: a `{value}` placeholder in `text` prints an animatable number (`text: '{value} users'`, `initial: { value: 0 }`, a keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Any other change of wording is a second layer (stack layers with `at` / `duration`). Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
+
+```ts
+{
+  type: 'text',
+  text: 'hello',
+  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+  keyframes: [
+    { at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.5 },
+  ],
+  style: {
+    fontSize: 'GW * 0.05',     // expression OK
+    fill: '#ffffff',           // verbatim string
+    fontWeight: 'bold',
+    fontFamily: 'Inter',
+  },
+}
+```
+
+The text's `fill` is also animatable via keyframes (under the `to`/`from`/`set` keys, not under `style`). Set `colorSpace` for perceptual interpolation:
+
+```ts
+{
+  type: 'text', text: 'COLORSPACE',
+  colorSpace: 'oklch',
+  style: { fill: '#ff0000', fontSize: 48, fontWeight: 'bold' },
+  keyframes: [
+    { at: 1, to: { fill: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
+  ],
+}
+```
+
+#### Counters (`{value}`)
+
+A text layer has one animatable number, `value`, printed wherever the text contains `{value}`. Animate it with the normal keyframes (any ease, `from`/`to`/`set`, `repeat`):
+
+```ts
+{
+  type: 'text', text: '{value} users', format: { decimals: 0, grouping: true },   // → "2,480 users"
+  initial: { value: 0 },
+  keyframes: [{ at: 1, to: { value: 2480 }, duration: 1.2, ease: 'power3.out' }],
+  style: { fontSize: 72, fill: '#fff' }, ...
+}
+```
+
+`format`: `decimals` (default 0) and thousands `grouping` (default false). Put prefixes and suffixes in the text (`'${value}'`, `'{value}%'`). If `value` is animated but the text has no `{value}`, a warning says so.
+
+### `image`
+
+Renders a [PIXI.Sprite](https://pixijs.com/8.x/guides/components/scene-objects/sprite/sprite) from a registered asset. Intrinsic `w`/`h` come from the loaded texture.
+
+```ts
+{
+  type: 'image',
+  asset: 'logo',
+  initial: { x: 'GW/2 - w/2', y: 'GH/2 - h/2' },
+}
+```
+
+`tint` is animatable via keyframes. Optionally set `colorSpace` to interpolate the tint perceptually:
+
+```ts
+{
+  type: 'image', asset: 'logo',
+  colorSpace: 'oklch',                 // smooth hue sweep instead of muddy sRGB
+  initial: { tint: '#ff0000' },
+  keyframes: [
+    { at: 1, to: { tint: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
+  ],
+}
+```
+
+### `video`
+
+Renders a video. Intrinsic `w`/`h` come from the video's natural size. `currentTime` is driven by the timeline (so seeking the Movie scrubs the video).
+
+```ts
+{
+  type: 'video',
+  asset: 'green',
+  loop?: false,           // loop back to start when finished (default false)
+  audio?: true,           // route audio track into the mix (default true)
+  volume?: 1,             // initial volume 0..1 (animatable via volume keyframes)
+  initial: { x: 0, y: 0, scale: 'cover' },
+}
+```
+
+Use `scale: 'cover'` or `scale: 'contain'` (these resolve via the [scope](#expressions)) to fit the video to the parent composition.
+
+### `audio`
+
+Audio-only sequence. No visual. Volume is animatable via keyframes.
+
+```ts
+{
+  type: 'audio',
+  asset: 'bgm',
+  loop?: false,
+  volume: 0,
+  keyframes: [
+    { at: 0,  to: { volume: 0.6 }, duration: 1 },     // fade in
+    { at: -1, to: { volume: 0 },   duration: 1 },     // fade out (negative `at` = relative to end)
+  ],
+}
+```
+
+Audio is mixed during `Movie.init()` and during `Movie.render()`. Volume keyframes interpolate linearly.
+
+### `composition`
+
+Nested composition. Same shape as the root spec but with `type: 'composition'` and an explicit `width`/`height`. Children animate within the local coordinate system; the composition itself can be positioned, scaled, and rotated as a unit.
+
+```ts
+{
+  type: 'composition',
+  width: 600, height: 120,
+  initial: { x: 'GW/2 - 300', y: 'GH * 0.86' },
+  keyframes: [
+    { at: 2.4, from: { alpha: 0, rotation: -12 },
+               to:   { alpha: 1, rotation: 0 },
+               duration: 0.7, ease: 'elastic.out(1, 0.5)' },
+  ],
+  sequences: [
+    { type: 'text', text: 'inside', initial: { x: 300, y: 60, anchorX: 0.5, anchorY: 0.5 }, style: { fontSize: 28, fill: '#fff' } },
+  ],
+}
+```
+
+### `shape`
+
+Parametric primitive backed by PIXI v8 `Graphics`. Six kinds, discriminated by `shape`. All geometry props accept the [expression language](#expressions), so dimensions can follow the canvas:
+
+```ts
+// Centered rounded panel that fills 80% of the canvas
+{
+  type: 'shape', shape: 'rect',
+  width: 'W * 0.8', height: 'H * 0.6', cornerRadius: 24,
+  initial: {
+    x: 'W/2', y: 'H/2',
+    fillColor: '#1a2640', fillAlpha: 0.85,
+    strokeColor: '#3a5680', strokeWidth: 2,
+  },
+}
+```
+
+Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `pivotX`/`pivotY` semantics line up with the other sequence types).
+
+| `shape`   | Required props                           | Optional               |
+|-----------|------------------------------------------|------------------------|
+| `rect`    | `width`, `height`                        | `cornerRadius`         |
+| `circle`  | `radius`                                 | —                      |
+| `ellipse` | `radiusX`, `radiusY`                     | —                      |
+| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | — |
+| `polygon` | `points: [[x,y], …]`                     | `open` (default false) |
+| `path`    | `d` (SVG path data)                      | —                      |
+
+**Style** is set on `initial` and animatable via keyframes:
+
+| Key           | Notes                                                        |
+|---------------|--------------------------------------------------------------|
+| `fillColor`   | Hex string (`'#3399ff'`) or number (`0x3399ff`). Omit = no fill. |
+| `fillAlpha`   | 0..1, default 1                                              |
+| `strokeColor` | Hex string or number. Requires `strokeWidth > 0` to render.  |
+| `strokeAlpha` | 0..1, default 1                                              |
+| `strokeWidth` | Pixels. Default 0 (no stroke).                               |
+
+Colour keys (`fillColor`, `strokeColor`) tween smoothly between hues — no snap at the end. Numeric keys (`fillAlpha` / `strokeAlpha` / `strokeWidth`) animate linearly.
+
+#### `fillGradient`
+
+Fill a shape with a gradient instead of `fillColor` (top level or in `initial`). Positions are in 0–1 of the shape's own bounds, so the gradient follows the shape's size. Colours may carry alpha, so a radial gradient from transparent to dark is a vignette. Not animatable.
+
+```ts
+{ type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
+  fillGradient: { stops: [[0, '#1b2a6b'], [0.6, '#7b3fe4'], [1, '#ff6a88']] } }                // linear, top → bottom
+{ ..., fillGradient: { angle: 0, stops: [[0, '#00f5a0'], [1, '#00d9f5']] } }                    // left → right
+{ ..., fillGradient: { type: 'radial', radius: 0.75, stops: [[0.45, 'rgba(0,0,0,0)'], [1, 'rgba(0,0,0,0.7)']] } }   // vignette
+```
+
+| Field | Notes |
+|---|---|
+| `type` | `'linear'` (default) or `'radial'` |
+| `stops` | at least two: `[offset 0–1, colour]` or `{ offset, color }` |
+| `angle` | linear: degrees, `0` = left → right, `90` = top → bottom (default) |
+| `center`, `innerRadius`, `radius` | radial: centre in 0–1 (default `[0.5, 0.5]`), inner radius (default 0), outer radius (default 0.5); an ellipse on a non-square shape |
+
+#### `colorSpace`
+
+Per-shape choice of how colour keyframes are interpolated. Default `'rgb'` (linear sRGB lerp via `gsap.utils.interpolate`) is fast but classic — a red → green ramp passes through muddy olive at the midpoint. The two perceptually uniform options keep saturation through the transition:
+
+| Value     | Behaviour                                                                                         |
+|-----------|---------------------------------------------------------------------------------------------------|
+| `'rgb'`   | Default. Linear sRGB lerp.                                                                        |
+| `'oklab'` | Straight line in OKLab's chromaticity plane. Brighter, more chromatic midpoints.                  |
+| `'oklch'` | (L, C, h) with hue along the shorter angular path. Smooth rainbow-style sweeps; ideal for hue cycling. |
+
+```ts
+{
+  type: 'shape', shape: 'circle', radius: 40,
+  colorSpace: 'oklch',                       // ← red → green via vibrant orange
+  initial: { fillColor: '#ff0000' },
+  keyframes: [
+    { at: 1, to: { fillColor: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
+  ],
+}
+```
+
+```ts
+{
+  type: 'shape', shape: 'circle', radius: 40,
+  initial: { x: 'W/2', y: 'H/2', fillColor: '#ff5577' },
+  keyframes: [
+    { at: 1, to: { fillColor: '#55ddaa' }, duration: 1.0, ease: 'sine.inOut' },
+    { at: 2, to: { strokeColor: '#fff', strokeWidth: 6 }, duration: 0.5 },
+  ],
+}
+```
+
+**Transforms animate normally.** `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `alpha` etc. all go through the standard keyframe pipeline.
+
+```ts
+// SVG-path heart that scale-pops on entry, then beats twice
+{
+  type: 'shape', shape: 'path',
+  d: 'M 0 -20 C -30 -50 -70 -10 0 30 C 70 -10 30 -50 0 -20 Z',
+  initial: { x: 'W/2', y: 'H/2', fillColor: '#ff3366' },
+  keyframes: [
+    { at: 0,   from: { alpha: 0, scale: 0 },
+               to:   { alpha: 1, scale: 1 },
+               duration: 0.5, ease: 'back.out(2.5)' },
+    { at: 1.5, to: { scale: 1.2 }, duration: 0.3, ease: 'power2.out' },
+    { at: 1.8, to: { scale: 1.0 }, duration: 0.3, ease: 'power2.in' },
+  ],
+}
+```
+
+**Scalar geometry is animatable.** `width`, `height`, `cornerRadius` (rect), `radius` (circle), `radiusX` / `radiusY` (ellipse) all flow through the same per-frame redraw and can be tweened via keyframes — useful for progress bars (animate `width`), pulsing icons (animate `radius`), or shape-morph callouts. Array geometry (polygon `points`, line endpoints, path `d`) is baked at build time; use `scale` / `scaleX` / `scaleY` for those.
+
+`anchorX` / `anchorY` (default `0.5` each) control which point on the bbox sits at the local origin — `0` is left/top, `1` is right/bottom. They're animatable too. Critical for "grow from one edge" effects:
+
+```ts
+// Left-anchored progress bar — width animates 0 → W, left edge stays at x
+{
+  type: 'shape', shape: 'rect', width: 0, height: 18, cornerRadius: 9,
+  anchorX: 0,                                  // ← left edge at x
+  initial: { x: 0, y: 'H/2', fillColor: '#5599ff' },
+  keyframes: [
+    { at: 0, to: { width: 'W' }, duration: 4, ease: 'sine.inOut' },
+  ],
+}
+```
+
+---
+
+## 3D layers & camera
+
+Place any 2D layer in depth and view it through a camera — After Effects style, no three.js. Everything uses the normal `initial` / `keyframes` / expression vocabulary.
+
+### Conventions (read this first)
+
+| Thing | Convention |
+|---|---|
+| Axes | `+x` right, `+y` down, **`+z` toward the viewer** (like CSS `translateZ`). Bigger `z` = nearer = larger on screen. |
+| Units | Positions in composition pixels. **Rotations in degrees.** |
+| Rotation signs | Same as CSS: `rotationY: 30` swings the right edge away; `rotationX: 30` brings the bottom edge toward you; `rotation` is the Z axis. |
+| Rotation centre | The same point 2D `rotation` uses: `anchorX/anchorY` (sprites, text, shapes) or `pivotX/pivotY` (compositions). Set `anchorX: 0.5, anchorY: 0.5` to spin about the centre. |
+| Default camera | Centred, looking straight at the `z = 0` plane, which maps 1:1 to pixels. A `threeD` layer at `z = 0` looks identical to a 2D layer. |
+| Camera props | `x`, `y`, `z`, `lookAtX`, `lookAtY`, `lookAtZ`, `fov` — all in `initial` / `keyframes`, never on the camera itself. |
+
+### `threeD` layers
+
+Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY`:
+
+```json
+{
+  "sequences": [
+    { "type": "text", "text": "tilted", "threeD": true,
+      "style": { "fontSize": 64, "fill": "#ffffff" },
+      "initial": { "x": "GW/2", "y": "GH/2", "anchorX": 0.5, "anchorY": 0.5, "rotationY": -35 },
+      "keyframes": [{ "at": 0, "to": { "rotationY": 0 }, "duration": 1, "ease": "power2.out" }] }
+  ]
+}
+```
+
+`z`, `rotationX` and `rotationY` are ignored on a layer without `threeD: true` (a warning tells you). `threeD: false` layers ignore the camera and keep stack order.
+
+### Camera
+
+The camera is a layer: `{ "type": "camera" }`. It has no visuals. With nothing set it is the default camera.
+
+| Prop | Meaning | Default |
+|---|---|---|
+| `x`, `y` | camera position | `W/2`, `H/2` |
+| `z` | camera depth. **Auto:** if you never set it, it follows `fov` so the `z = 0` plane stays 1:1 | `(H/2) / tan(fov/2)` |
+| `lookAtX`, `lookAtY`, `lookAtZ` | the point it looks at | `W/2`, `H/2`, `0` |
+| `fov` | vertical field of view, degrees (clamped to 1–179) | 40 |
+
+```json
+{
+  "sequences": [
+    { "type": "camera", "name": "cam",
+      "keyframes": [
+        { "at": 0, "from": { "x": "GW/2 - 260", "lookAtX": "GW/2 - 260" },
+                   "to":   { "x": "GW/2 + 260", "lookAtX": "GW/2 + 260" },
+          "duration": 4, "ease": "sine.inOut" }
+      ] },
+    { "type": "shape", "shape": "rect", "width": 300, "height": 200, "threeD": true,
+      "initial": { "x": "GW/2", "y": "GH/2", "z": -400, "fillColor": "#3a6ea5" } },
+    { "type": "shape", "shape": "rect", "width": 300, "height": 200, "threeD": true,
+      "initial": { "x": "GW/2", "y": "GH/2", "z": 250, "fillColor": "#d96a3a" } }
+  ]
+}
+```
+
+Moving the camera sideways makes the near rectangle slide faster than the far one (parallax). Animating only `fov` keeps the `z = 0` plane fixed and changes how strong the perspective is (a dolly zoom):
+
+```json
+{
+  "sequences": [
+    { "type": "camera",
+      "keyframes": [{ "at": 0, "to": { "fov": 70 }, "duration": 3, "ease": "sine.inOut" }] },
+    { "type": "shape", "shape": "circle", "radius": 120, "threeD": true,
+      "initial": { "x": "GW/2", "y": "GH/2", "z": 300, "fillColor": "#38a169" } }
+  ]
+}
+```
+
+- A camera affects the `threeD` layers that are its **siblings** (same composition). A nested composition has its own camera for its children, and is itself a layer in its parent's space when it has `threeD: true`.
+- Several cameras may exist if their lifespans (`at` / `duration`) do not overlap — each is a camera cut. Overlapping cameras warn; the last-listed one wins.
+- With no camera layer the default camera is used.
+
+### Depth order and limits
+
+- Consecutive `threeD` layers are drawn farthest-first. A non-`threeD` layer between them splits the group (like After Effects).
+- A layer at or behind the camera is hidden for that frame.
+- v1 limits: planes do not intersect (whole layers are sorted); masks, transitions and `filterArea` are not supported on `threeD` layers (a mask is ignored with a warning); each `threeD` layer costs one extra render pass per frame.
+- Wrong-but-likely names (`rotateY`, `translateZ`, `depth`, `perspective`, `zoom`) are not accepted; the console tells you the right name.
+
+---
+
+## three
+
+Composites a [three.js](https://threejs.org/) scene as a normal layer. Each frame, the scene is rendered into an offscreen WebGL canvas and uploaded into the sequence's PIXI texture — so once built, the layer is a plain sprite: 2D `initial` / keyframe props, [masks](#masks), and [filters](#filters) all apply to it exactly like any other sequence type.
+
+`type: 'three'` lives in the optional `pixi-effects/three` entry, not core `pixi-effects` — see [API reference](./api.md#pixi-effectsthree) for install/import details.
+
+```ts
+import { registerThree, three } from 'pixi-effects/three';
+import * as THREE from 'three';
+
+registerThree();   // once, before Movie.init
+
+three({
+  type: 'three',
+  name: 'knot',
+  width: 'GW * 0.6', height: 'GH * 0.6',
+  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+  setup: (ctx) => {
+    const knot = new THREE.Mesh(
+      new THREE.TorusKnotGeometry(1, 0.35, 128, 32),
+      new THREE.MeshStandardMaterial({ color: 0x7fb4ff }),
+    );
+    ctx.scene.add(knot);
+    ctx.camera.position.z = 4;
+    return { objects: { knot } };    // exposes `knot` to keyframes, see below
+  },
+  keyframes: [
+    { at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 },
+  ],
+})
+```
+
+### Spec fields
+
+| Field        | Type                                                        | Notes                                                                                   |
+| ------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `width?`     | `PropValue`                                                 | layer size in composition px; expressions allowed (e.g. `'W * 0.5'`). Default: parent composition size. |
+| `height?`    | `PropValue`                                                 | see `width`.                                                                              |
+| `resolution?` | `number`                                                    | supersampling factor for the offscreen canvas. Default `1`.                              |
+| `setup`      | `(ctx: ThreeContext) => Promise<ThreeSetupResult \| void> \| ThreeSetupResult \| void` | builds the scene once. Add objects to `ctx.scene`, position `ctx.camera` (or replace it via `{ camera }`). Async, so `Movie.init` can await GLTF / texture loading. |
+| `update?`    | `(t: number, ctx: ThreeContext) => void`                    | optional per-frame hook; `t` is sequence-local time in seconds.                          |
+| `dispose?`   | `(ctx: ThreeContext) => void`                                | cleanup for user-created GPU resources (geometries, materials, textures). Called from `destroy()`. |
+
+`ThreeContext` is `{ scene, camera, renderer, width, height }` — the three.js `Scene`, `Camera`, `WebGLRenderer`, and the resolved layer size in composition px.
+
+### Keyframe paths: `three.<name>.<path>`
+
+Objects returned from `setup`'s `{ objects }` are addressable from keyframes as `three.<name>.<path>`, using the same `from`/`to`/`set` vocabulary as every other prop:
+
+```ts
+setup: (ctx) => {
+  const knot = new THREE.Mesh(/* ... */);
+  ctx.scene.add(knot);
+  return { objects: { knot } };
+},
+keyframes: [
+  { at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 },
+  { at: 0, to: { 'three.knot.position.x': 1.5 },         duration: 3 },
+],
+```
+
+`camera` is exposed implicitly as `three.camera.<path>` unless `setup`'s `objects` already defines a `camera` key.
+
+### Rules
+
+1. Call `registerThree()` before `Movie.init` builds a composition containing a `type: 'three'` sequence — the sequence type is looked up by name at build time.
+2. `update(t)` must derive all state purely from `t` — no wall clock, no unseeded randomness. Playback and export both seek arbitrarily; anything else in `update` means identical timestamps can render different pixels.
+3. Each three sequence owns one WebGL context (an offscreen canvas + renderer). Browsers cap live WebGL contexts at roughly 8–16 — budget accordingly if a composition uses several three layers.
+4. Like `custom` filters, the spec carries functions (`setup`, optionally `update` / `dispose`) and is **not** JSON-serializable.
+5. The scene renders into the layer rectangle: anything that projects outside it is clipped at the layer's edges. Frame the camera with margin for the whole animation — rotating objects often project taller/wider than their resting pose (a `TorusKnotGeometry(radius, tube)`, for instance, extends to `1.5 * radius + tube`, not `radius`).
+
+---
+
+## Masks
+
+> A mask is a layer in the **parent's** coordinate space and does **not** follow the layer it masks: slide the content and the mask separately. Reveal by growing the mask's `width` from a fixed edge (`anchorX: 0`); exit by tweening `x` and `width` together.
+
+Any sequence can carry an inline `mask` — itself a full sequence — that shapes which pixels of the maskee are visible. The mask runs in the same coordinate space as the maskee (added to the same parent composition) and shares its lifetime, so a circular avatar crop is just:
+
+```ts
+{
+  type: 'image', asset: 'photo',
+  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
+  mask: {
+    type: 'shape', shape: 'circle', radius: 130,
+    initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff' },
+  },
+}
+```
+
+The mask is itself a sequence, so it can have `keyframes` of its own — useful for reveal animations (a circle growing from `scale: 0` to full size, a rect wiping across, …):
+
+```ts
+// Iris reveal — image is wiped in by a growing circle
+{
+  type: 'image', asset: 'photo',
+  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
+  mask: {
+    type: 'shape', shape: 'circle', radius: 200,
+    initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff', scale: 0 },
+    keyframes: [
+      { at: 0, to: { scale: 1 }, duration: 1.0, ease: 'power2.out' },
+    ],
+  },
+}
+```
+
+Notes:
+- The mask sequence is rendered as a mask, not as a normal child — its `fillColor` / `strokeColor` only matter for which pixels are kept, not for the visible colour.
+- Any sequence type works as a mask (shape / image / text / nested composition); shapes are the natural choice for geometric reveals.
+- For a left-to-right wipe, give the mask `anchorX: 0` (rect/circle/ellipse) so `width: 0 → full` grows rightward from the left edge.
+
+#### `maskInverted`
+
+When `true`, flip the mask sense: pixels INSIDE the mask shape become transparent, pixels OUTSIDE stay visible. Useful for knockout / cutout effects (punch a circular hole through a panel, etc.).
+
+```ts
+// Photo with a circular hole punched through the middle
+{
+  type: 'image', asset: 'photo',
+  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
+  maskInverted: true,
+  mask: {
+    type: 'shape', shape: 'circle', radius: 80,
+    initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff' },
+    keyframes: [
+      { at: 0, to: { radius: 120 }, duration: 1.5, ease: 'sine.inOut' },
+      { at: 1.5, to: { radius: 80 }, duration: 1.5, ease: 'sine.inOut' },
+    ],
+  },
+}
+```
+
+Routed through PIXI v8's native `setMask({ inverse: true })`.
+
+#### `blendMode`
+
+How a layer blends with what is behind it: `'normal'` (default), `'add'`, `'screen'` or `'multiply'`. `add` and `screen` brighten, so overlapping glows, halos and light leaks add up instead of covering each other; `multiply` darkens. It works on every layer type, on `threeD` layers, and on a composition (its children inherit the mode, each blending with what is behind it). Any other value warns and is ignored.
+
+```ts
+// A soft white glow that brightens whatever it overlaps
+{ type: 'shape', shape: 'circle', radius: 120, blendMode: 'add',
+  fillGradient: { type: 'radial', stops: [[0, 'rgba(255,255,255,0.9)'], [1, 'rgba(255,255,255,0)']] },
+  initial: { x: 'W/2', y: 'H/2' } }
+```
+
+---
+
+## Assets
+
+Pass a flat list of named assets to `Movie.init({ assets })`. Sequences refer to them by `name`.
+
+```ts
+await movie.init({
+  assets: [
+    { name: 'logo',  src: '/img/logo.png' },
+    { name: 'bgm',   src: '/audio/bgm.mp3' },
+    { name: 'green', src: '/video/green.mp4' },
+  ],
+  composition: { /* sequences reference 'logo', 'bgm', 'green' */ },
+});
+```
+
+Supported formats are whatever PixiJS Assets and the browser's audio/video decoders accept (typically PNG/JPG/WebP for images; MP3/AAC/Opus for audio; MP4/WebM for video).
+
+---
+
+## Keyframes
+
+```ts
+interface Keyframe {
+  at?: number;       // start, in seconds from the start of THIS sequence; negative = back from the sequence's end (-0.5 = 0.5 s before it ends)
+  duration?: number; // seconds (default 0 — instantaneous)
+  ease?: string;     // GSAP easing name (default 'none')
+  set?:  Props;      // jump to these values at `at`
+  to?:   Props;      // animate from current to these values over `duration`
+  from?: Props;      // animate from these values to current
+  // `from` + `to` together is a 'fromTo' tween
+}
+```
+
+The four kinds are mutually exclusive per keyframe:
+
+- **`set`** — instantaneous property assignment at `at`.
+- **`to`** — tween from whatever the property is at `at` to the given values, over `duration`.
+- **`from`** — tween from the given values back to the current property, over `duration`.
+- **`from` + `to`** — full fromTo tween, with explicit start and end values.
+
+### Repeating
+
+`repeat` (extra plays, a finite whole number), `yoyo` (every other play runs backwards) and `repeatDelay` (seconds between plays) work on every kind of animation — position, alpha, colour, shape geometry, filters, text `fill`/`value`:
+
+```ts
+{ at: 0, to: { scale: 1.15 }, duration: 0.5, ease: 'sine.inOut', repeat: 5, yoyo: true }   // a heartbeat: 6 plays, 6 s total
+```
+
+Total time = `duration × (repeat + 1)` (+ delays). Endless repeats are not allowed (the timeline needs a fixed length); `repeat: -1` / `Infinity` is ignored with a warning — repeat as many times as the layer lasts.
+
+### Negative `at`
+
+If `at < 0`, it's interpreted as `duration + at` — measured back from the end of **the sequence the keyframe belongs to**. Useful for fade-outs:
+
+```ts
+{ type: 'text', text: 'bye', at: 2, duration: 3,
+  keyframes: [{ at: -0.5, to: { alpha: 0 }, duration: 0.5 }] }   // fades during the last 500 ms of this text (global 4.5 s – 5 s)
+```
+
+### Easing
+
+Standard GSAP easing strings: `'none'`, `'linear'`, `'power1.in'` ... `'power4.inOut'`, `'sine.in/out/inOut'`, `'expo.in/out/inOut'`, `'circ.in/out/inOut'`, `'back.in/out/inOut(overshoot)'`, `'elastic.in/out/inOut(amplitude, period)'`, `'bounce.in/out/inOut'`. See [GSAP easing docs](https://gsap.com/docs/v3/Eases/).
+
+### PIXI shorthands
+
+These keys are auto-routed through GSAP's PixiPlugin when used in `initial` / `set` / `to` / `from` / `keyframes`:
+
+```
+scale, scaleX, scaleY
+anchor, anchorX, anchorY
+pivot, pivotX, pivotY
+skew, skewX, skewY
+position, positionX, positionY
+tilePosition, tilePositionX, tilePositionY
+tileScale, tileScaleX, tileScaleY
+tint, autoAlpha
+colorize, colorizeAmount, colorMatrixFilter
+blur, blurX, blurY, blurPadding
+lineColor, lineAlpha, fillColor, fillAlpha
+```
+
+(In addition to plain DisplayObject props like `x`, `y`, `rotation`, `alpha`, `width`, `height`, `visible`.) **Angles are in degrees**: `rotation`, `skew` / `skewX` / `skewY` (PixiPlugin converts them), and `rotationX` / `rotationY` for 3D layers.
+
+### Filter keyframe paths
+
+Animate a named filter's parameter using a dot-path key:
+
+```ts
+import { BlurFilter } from 'pixi.js';
+
+{
+  type: 'video',
+  asset: 'green',
+  filters: [
+    { name: 'k', type: 'chromaKey', keyColor: '#00ff00' },
+    { name: 'b', type: 'custom', filter: new BlurFilter({ strength: 0 }) },
+  ],
+  keyframes: [
+    { at: 2, to: { 'filters.b.strength': 8 }, duration: 1 },
+    { at: 4, to: { 'filters.k.threshold': 0.5 }, duration: 1 },
+  ],
+}
+```
+
+The path is `filters.<filter-name>.<animatable-param>`. A filter must have a `name` to be addressable.
+
+---
+
+## Expressions
+
+Any string `Props` value may be an arithmetic expression. Strings whose first character is a letter or digit are tried as expressions; verbatim strings (color hex, font names, etc.) are passed through when used in fields that don't expect a number.
+
+The expression parser is in-tree (no eval, CSP-safe). See [`src/expr/Parser.ts`](../src/expr/Parser.ts).
+
+### Operators and functions
+
+| Form                    | Notes                                                |
+| ----------------------- | ---------------------------------------------------- |
+| `+ - * /`               | binary arithmetic                                    |
+| `-x`, `+x`              | unary                                                |
+| `( ... )`               | parens                                               |
+| `1`, `1.5`, `.25`       | decimals                                             |
+| `min(a, b)`, `max(a, b)`| variadic                                             |
+| `abs(x)`                |                                                      |
+| `floor(x)`, `ceil(x)`, `round(x)` |                                            |
+| `sqrt(x)`               |                                                      |
+| `pow(a, b)`             | power                                                |
+| `sin(x)`, `cos(x)`, `tan(x)` | radians                                         |
+
+No comparison, conditional, bitwise, or string operators — keep it numeric.
+
+### Scope variables
+
+Each sequence has its own scope, computed at build time:
+
+| Name      | Meaning                                                                               |
+| --------- | ------------------------------------------------------------------------------------- |
+| `w`       | sequence intrinsic width (e.g. video natural width). 0 if not applicable.             |
+| `h`       | sequence intrinsic height.                                                            |
+| `W`       | parent composition width (or root if no parent).                                      |
+| `H`       | parent composition height.                                                            |
+| `GW`      | global (root) composition width.                                                      |
+| `GH`      | global (root) composition height.                                                     |
+| `contain` | scale factor that makes the sequence fit inside the parent (preserve aspect, no crop) |
+| `cover`   | scale factor that makes the sequence cover the parent (preserve aspect, may crop)     |
+| `t`       | sequence start time (the `at` after negative-`at` resolution), seconds                |
+| `d`       | sequence duration, seconds                                                            |
+| `T`       | parent (or root) duration, seconds                                                    |
+
+### Examples
+
+```ts
+// Center an image
+initial: { x: 'GW/2 - w/2', y: 'GH/2 - h/2' }
+
+// Fit a video without cropping
+initial: { x: 0, y: 0, scale: 'contain' }
+
+// Fill a video, may crop
+initial: { x: 0, y: 0, scale: 'cover' }
+
+// Responsive font size
+style: { fontSize: 'min(GW, GH) * 0.06' }
+
+// Subtitle 4% above bottom
+initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
+```
+
+---
+
+## Transitions
+
+A composition can declare scene-to-scene `transitions` that compress paired keyframes into a single line and add visual effects (mask wipes, iris reveals) that aren't expressible at the keyframe level.
+
+```ts
+{
+  sequences: [
+    { type: 'video', name: 'A', asset: 'a', at: 0, duration: 5 },
+    { type: 'video', name: 'B', asset: 'b', at: 4, duration: 5 },
+  ],
+  transitions: [
+    { kind: 'crossfade', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' },
+  ],
+}
+```
+
+Common fields (`TransitionCommon`):
+
+| Field      | Type    | Notes                                                                                  |
+| ---------- | ------- | -------------------------------------------------------------------------------------- |
+| `from`     | string  | sibling sequence's `name`. Must exist in the same composition.                         |
+| `to`       | string  | sibling sequence's `name`. Must be declared **after** `from` in `sequences[]`.         |
+| `at`       | number  | start of the transition, in the **parent composition's** time (like a sequence's `at`, not sequence-local); negative = back from the parent's end. |
+| `duration` | number  | seconds, must be > 0.                                                                  |
+| `ease`     | string? | GSAP easing name. Default `'none'` (linear).                                           |
+
+Validation runs at composition build time. Errors throw with the offending `transitions[<index>]` quoted in the message: missing names, `to` before `from`, transition window outside either sequence's lifespan, duplicate use of one sequence as `from`, `from === to`, `duration <= 0`.
+
+### `crossfade`
+
+Alpha cross-dissolve. `from` fades to `alpha: 0`, `to` starts at `alpha: 0` and fades to `1`, both over `[at, at + duration]`.
+
+```ts
+{ kind: 'crossfade', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' }
+```
+
+If `to` already has an explicit `initial.alpha` (other than 0), the expander throws — remove the manual setting.
+
+### `wipe`
+
+A directional reveal. `to` is masked by a soft edge that travels across the screen.
+
+```ts
+{
+  kind: 'wipe', from: 'A', to: 'B', at: 4, duration: 1,
+  direction: 'left' | 'right' | 'up' | 'down',
+  smoothing: 0.04,    // 0..1 edge softness (default 0.02)
+}
+```
+
+`direction` is the direction the wipe edge travels — `'left'` means the edge moves leftward across the canvas, exposing B starting from the right side. Mirror that for `'right'` / `'up'` / `'down'`.
+
+### `iris`
+
+A circular reveal centered on the canvas.
+
+```ts
+{
+  kind: 'iris', from: 'A', to: 'B', at: 4, duration: 1,
+  mode: 'in',         // default — B opens up from a point. 'out' = A closes down to a point.
+  smoothing: 0.03,    // 0..1 edge softness (default 0.02)
+}
+```
+
+`mode: 'in'` (default): B emerges from the center and grows outward.
+`mode: 'out'`: A disappears from the outside in, exposing B.
+
+### `slide`
+
+Both sequences slide together; the new scene comes in from the opposite side.
+
+```ts
+{
+  kind: 'slide', from: 'A', to: 'B', at: 4, duration: 1,
+  direction: 'left' | 'right' | 'up' | 'down',
+}
+```
+
+`direction` is the direction of motion. `'left'` means A slides off to the left and B enters from the right.
+
+The slide macro reads each sequence's existing `initial.x` / `initial.y` (if any) and treats it as the natural resting position. `B` is shifted off-screen by ±W or ±H from that position and slides back to it; `A` slides from its position to off-screen on the opposite side. So a centered text with `initial: { x: 'GW/2', anchorX: 0.5 }` ends the slide centered, not at `x: 0`.
+
+If you've manually keyframed `x` / `y` on `A` or `B`, the slide expansion appends new keyframes alongside — your existing motion is not overwritten. Behavior with conflicting motion is the user's responsibility.
+
+### `dip`
+
+"Dip through": A fades out across the first half of the window and B fades in across the second half. The visible color during the dip is whatever sits behind A and B — set `Movie.background` (or place a persistent layer beneath them) for dip-to-black / dip-to-white / dip-to-color.
+
+```ts
+{ kind: 'dip', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' }
+```
+
+If `to` already has a non-zero `initial.alpha`, the expander throws — remove the manual setting.
+
+### `zoom`
+
+A scaled punch-in / punch-out. By default `B` opens up: it starts large and zooms back to scale 1 while fading in; `A` simply fades. With `mode: 'out'` it's the opposite — `A` zooms outward as it fades, and `B` fades in at scale 1.
+
+```ts
+{
+  kind: 'zoom', from: 'A', to: 'B', at: 4, duration: 1,
+  mode: 'in',          // default — B opens up. 'out' = A closes outward.
+  fromScale: 4,        // starting scale of the zoomed sequence (default 4)
+  ease: 'power2.out',
+}
+```
+
+### `dissolve`
+
+Pixel-grain noise reveal driven by deterministic 2D Perlin noise. Pixels with a low noise value reveal first; as `uProgress` advances, more pixels reveal. The same `seed` always produces the same dissolve pattern, so a render is bit-exact reproducible.
+
+```ts
+{
+  kind: 'dissolve', from: 'A', to: 'B', at: 4, duration: 1,
+  scale: 30,         // pattern frequency (higher = finer grain). Default 30.
+  seed: 0,           // pattern offset. Different seeds → different reveal patterns.
+  smoothing: 0.05,   // edge softness within each chunk. Default 0.05.
+}
+```
+
+---
+
+## Filters
+
+> **`filterArea`** (on any layer) is a rectangle in the layer's **own** coordinates — origin = its local origin, e.g. a circle's centre — that widens the area a filter may draw into. Without it a blur or glow is clipped to the layer's bounding box: `filterArea: { x: -(r + 260), y: -(r + 260), width: 2 * (r + 260), height: 2 * (r + 260) }` for a circle of radius `r` blurred by up to 260 px. `threeD` layers add the filters' padding automatically.
+
+Filters are named, ordered, and per-sequence. Animate parameters via `'filters.<name>.<param>'` keyframe paths.
+
+### `chromaKey`
+
+Removes a key color from the source. Works on video, image, or composition layers.
+
+```ts
+{
+  name: 'k',
+  type: 'chromaKey',
+  keyColor?: string | [number, number, number],  // hex '#00ff00' or RGB 0..1; default green
+  threshold?: number,        // default 0.4 — distance from key color counted as transparent
+  smoothing?: number,        // default 0.1 — softness of the cutoff edge
+  spill?: number,            // default 0.2 — green-tint suppression
+}
+```
+
+Animatable: `threshold`, `smoothing`, `spill`. `keyColor` is set at build time.
+
+### `custom`
+
+Escape hatch for any PIXI `Filter` instance — including PIXI's own built-ins (`BlurFilter`, `ColorMatrixFilter`, `NoiseFilter`, etc.), [pixi-filters](https://github.com/pixijs/filters), community packages, or your own `Filter` subclass. The instance is used as-is; animation works the same way as for `chromaKey` as long as the filter has writable scalar properties at the addressed paths.
+
+```ts
+import { BlurFilter } from 'pixi.js';
+import { GlowFilter, OldFilmFilter } from 'pixi-filters';
+
+{
+  type: 'image',
+  asset: 'photo',
+  filters: [
+    { type: 'custom', name: 'b',    filter: new BlurFilter({ strength: 0 }) },
+    { type: 'custom', name: 'glow', filter: new GlowFilter({ outerStrength: 1, color: 0xffaa00 }) },
+    { type: 'custom', name: 'film', filter: new OldFilmFilter() },
+  ],
+  keyframes: [
+    { at: 1,    to: { 'filters.b.strength': 8 },          duration: 0.5 },
+    { at: 2,    to: { 'filters.glow.outerStrength': 4 },  duration: 1 },
+    { at: -0.5, to: { 'filters.film.noise': 0 },          duration: 0.5 },
+  ],
+}
+```
+
+Notes:
+
+- `filter` must be a `Filter` instance (constructor must have run on the consumer side).
+- Animation paths use scalar property setters. Filters whose properties are PointData (e.g. `pixi-filters` `RGBSplitFilter` exposes `red: { x, y }`) currently don't propagate the change to the GPU uniform when only `.x` is mutated — replace the whole point in an `onUpdate` callback or use a scalar-API filter instead.
+- Without a `name`, the filter still applies but cannot be addressed via `filters.<name>.<prop>` keyframe paths.
+
+Notes:
+
+- `filter` must be a PIXI `Filter` instance (constructor must have run on the consumer side). Plain object literals throw.
+- `pixi-filters` is **not** a dependency of pixi-effects — install it on your side if you want to use it.
+- Without a `name`, the filter still applies but cannot be addressed via `filters.<name>.<prop>` keyframe paths.
+
+---
+
+## Presets
+
+Presets are pure helpers that return a ready-to-use `SequenceSpec`. They expand into the existing keyframe / initial primitives — no engine surgery — so anything you can do with a preset you can also write by hand.
+
+### `kenBurns`
+
+Per-image motion preset for slideshows. Returns an `ImageSequenceSpec`; drop the result straight into `sequences[]`. Pair with `crossfade` / `dip` etc. transitions for the cuts between images — `kenBurns` itself emits no fade.
+
+```ts
+import { kenBurns } from 'pixi-effects';
+
+sequences: [
+  kenBurns({ asset: 'photo1', name: 'p1', at: 0,  duration: 6, motion: 'scale',    origin: [0.25, 0.25], zoom: 1.2 }),
+  kenBurns({ asset: 'photo2', name: 'p2', at: 5,  duration: 6, motion: 'rotation', angle: 6 }),
+  kenBurns({ asset: 'photo3', name: 'p3', at: 10, duration: 6, motion: 'position', from: [0, 0], to: [1, 1] }),
+  kenBurns({ asset: 'photo4', name: 'p4', at: 15, duration: 6, motion: 'still' }),
+],
+```
+
+The image is centred on the canvas; `fit` (default `'cover'`) controls how the texture is scaled to fill. The fitted scale is computed at runtime from the texture's intrinsic size, so you don't pass `imageWidth` / `imageHeight`.
+
+#### Common fields
+
+| Field      | Type                  | Notes                                                                                |
+| ---------- | --------------------- | ------------------------------------------------------------------------------------ |
+| `asset`    | string                | image asset name (registered via `Movie.init({ assets })`)                           |
+| `duration` | number                | seconds of animation (required)                                                      |
+| `name?`    | string                | sequence name so transitions can reference it                                        |
+| `at?`      | number                | start time, parent-relative seconds                                                  |
+| `fit?`     | `'cover'` \| `'contain'` | how the texture fills the canvas. Default `'cover'`.                              |
+| `ease?`    | string                | GSAP easing name. Default `'sine.inOut'`.                                            |
+
+#### `motion: 'still'`
+
+Image sits at the canvas centre, fitted but unanimated. Useful as a stable "rest" in between motion-heavy frames.
+
+#### `motion: 'scale'`
+
+Zoom in or out around an arbitrary 9-point pivot.
+
+| Field        | Type                       | Notes                                                                                       |
+| ------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
+| `origin?`    | `[number, number]`         | pivot in [0..1] image coords. Default `[0.5, 0.5]` (centre). The original convention uses the 9-point grid `0.25 / 0.5 / 0.75`. |
+| `zoom?`      | number                     | zoom factor relative to the fitted base. Default `1.15`.                                    |
+| `direction?` | `'in'` \| `'out'`          | `'in'`: 1 → zoom (default). `'out'`: zoom → 1.                                              |
+
+The pivot point stays pinned at its world position; the rest of the image grows / shrinks around it. This is the "focal-point" zoom you want for ken-burns slideshows — the eye anchors on the pivot while the surrounding pixels move.
+
+#### `motion: 'rotation'`
+
+Gentle rotation while keeping the image filling the canvas.
+
+| Field        | Type                                | Notes                                                                                       |
+| ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `angle?`     | number                              | total rotation in degrees. Default `8`. Capped at 30.                                       |
+| `direction?` | `'cw'` \| `'ccw'` \| `'through'`    | `'cw'` (default) = 0 → +angle. `'ccw'` = 0 → −angle. `'through'` = −angle/2 → +angle/2.     |
+
+The scale is over-set so the rotated bounding box still covers the canvas — no background gaps as the image tilts.
+
+#### `motion: 'position'`
+
+Pan the image between two points within its over-scaled bounds.
+
+| Field   | Type                | Notes                                                                                  |
+| ------- | ------------------- | -------------------------------------------------------------------------------------- |
+| `from?` | `[number, number]`  | start position in [0..1] of the over-scaled bounds. Default `[0.25, 0.25]`.            |
+| `to?`   | `[number, number]`  | end position. Default `[0.75, 0.75]`.                                                  |
+| `zoom?` | number              | over-scale factor (must be > 1 for any pan to be visible). Default `1.15`.             |
+
+`[0, 0]` looks at the top-left of the image; `[1, 1]` looks at the bottom-right. The default pans diagonally across the upper-left and lower-right quarters of the over-scaled image (matches the Yajima-Motion preset).
+
+### `orbit`
+
+A camera that circles a point. There is no per-frame expression in the DSL, so the circle is sampled into short linear keyframes (one per 0.1 s; the easing is applied to the angle). Returns a `camera` layer for `sequences[]`.
+
+```ts
+import { orbit } from 'pixi-effects';
+
+sequences: [
+  orbit({ duration: 6, degrees: 40 }),                                   // ±20° around the centre of a 1280×720 canvas
+  // …threeD layers…
+]
+```
+
+| Option | Notes |
+|---|---|
+| `duration`, `degrees` | required. `degrees` is the total sweep (negative = the other way) |
+| `start` | start angle in degrees; default `-degrees / 2` (0 = straight in front of the centre) |
+| `radius` | distance from the centre; default = the default camera distance for `height` and `fov`, so `z = 0` is 1:1 at angle 0 |
+| `center` | `[x, y]` to circle and look at; default the canvas centre |
+| `width`, `height` | canvas size for the defaults (1280 × 720) |
+| `fov`, `ease`, `at`, `name`, `stepsPerSecond` | `ease` default `'sine.inOut'` |
+
+`z` is specified, so it stops following `fov`; for an orbit **plus** a dolly zoom write your own `fov` and `z = (H/2) / tan(fov/2)` keyframes.
+
+### `withFade`
+
+Spec helper that adds alpha fade-in / fade-out to **any** sequence spec. Mutates and returns the spec, so it composes with other presets (`kenBurns`, …) and drops straight into `sequences[]`.
+
+```ts
+import { kenBurns, withFade } from 'pixi-effects';
+
+sequences: [
+  withFade(kenBurns({ asset: 'photo', at: 0, duration: 6, motion: 'scale' }), { in: 0.5, out: 0.5 }),
+  withFade({ type: 'text', text: 'hi', at: 5, duration: 3, initial: { x: 'GW/2' } }, { in: 0.4 }),
+]
+```
+
+| Option | Type   | Notes                                                                                         |
+| ------ | ------ | --------------------------------------------------------------------------------------------- |
+| `in?`  | number | fade-in length in seconds, at the start of the sequence. Sets `initial.alpha = 0`.            |
+| `out?` | number | fade-out length in seconds, anchored to `at + duration`. **Requires `duration` on the spec** (throws otherwise). |
+
+The added keyframes are layered on top of any keyframes the spec already has. `withFade` is available since `0.2.0`.
+
+
+<!-- ===== docs/api.md ===== -->
+
+# API Reference
+
+- [`Movie`](#movie) — composition runtime: init, playback, render
+- [`Controller`](#controller) — drop-in player UI overlay
+- [Helpers](#helpers) — pure utilities exported from `pixi-effects/controller`
+- [`pixi-effects/three`](#pixi-effectsthree) — optional three.js integration
+
+For DSL types (composition spec, sequences, filters, keyframes, expressions), see [DSL reference](./dsl.md).
+
+---
+
+## `Movie`
+
+Imported from `pixi-effects`.
+
+```ts
+import { Movie } from 'pixi-effects';
+
+const movie = new Movie();
+await movie.init({ /* ... */ });
+movie.play();
+```
+
+### Constructor
+
+```ts
+new Movie()
+```
+
+No arguments. State is fully populated by `init()`.
+
+### `movie.init(options): Promise<void>`
+
+Loads assets, builds the composition tree, mixes audio, and renders frame 0.
+
+```ts
+interface MovieOptions {
+  width?:      number;              // canvas pixels  (default 1920)
+  height?:     number;              // canvas pixels  (default 1080)
+  duration?:   number;              // seconds         (default 10)
+  frameRate?:  number;              // fps             (default 30)
+  background?: string;              // CSS color hex   (default '#000000')
+  canvas?:     HTMLCanvasElement;   // existing canvas to render into; otherwise PixiJS creates one
+  assets?:     AssetSpec[];         // [{ name, src }]
+  composition?: CompositionSpec;    // root composition (see DSL reference)
+}
+```
+
+Resolves once the composition is ready and the first frame has been rendered. Emits the `ready` event.
+
+### `movie.play(): void`
+
+Starts the requestAnimationFrame loop that drives `gotoFrame()` per tick. If `currentFrame >= totalFrames`, restarts from 0.
+
+If audio sources exist, schedules them on the AudioContext at the appropriate offsets.
+
+### `movie.pause(): void`
+
+Stops the rAF loop and any playing audio. Emits `'pause'` only when the previous state was playing (so calling `pause()` on an already-paused movie is a no-op for listeners).
+
+### `movie.gotoFrame(frame, force?): Promise<void>`
+
+```ts
+gotoFrame(frame: number, force?: boolean): Promise<void>
+```
+
+Seeks to a specific frame. Pauses if currently playing? **No** — does not change `isPlaying`. Updates `timeline.time()`, awaits any video frame readiness, renders, and emits `'frame'`.
+
+`force=true` skips the early-return when the requested frame equals `currentFrame`. Use it after a composition rebuild.
+
+### `movie.snapshot(frame?, options?): Promise<Blob | string>`
+
+```ts
+snapshot(frame?: number, options?: { scale?: number; type?: 'image/png' | 'image/jpeg'; as?: 'blob' | 'dataURL' }): Promise<Blob | string>
+```
+
+A picture of one frame: **the canvas only** (the player bar is not in it). Seeks to `frame` (default: the current frame) and stays there. `as: 'dataURL'` returns a `data:` URL string, handy when a script can only return text. Use it to look at what you built.
+
+### `movie.contactSheet(options?): Promise<Blob | string>`
+
+```ts
+contactSheet(options?: {
+  frames?: number[]; times?: number[]; count?: number;   // which frames: explicit, in seconds, or `count` evenly spread (default 6)
+  columns?: number;                                       // default 3
+  cellWidth?: number;                                     // picture width in px, default 480
+  as?: 'blob' | 'dataURL';
+}): Promise<Blob | string>
+```
+
+Many frames on **one** PNG, each labelled `frame N · T s`. The cheapest way to check a whole animation by eye (include the middle of every transition and the last second). Restores the current frame afterwards.
+
+### `movie.inspect(frame?, options?): Promise<InspectReport>`
+
+Where every layer is drawn at `frame`, as JSON — for checking layout without eyes. Seeks there and stays there. `options.layers`: `'visible'` (default, only layers drawn at this frame), `'all'`, or `'none'` (just `summary` and `issues`). Faint layers (alpha < 0.3) and text whose x / y is animated (tickers) are not reported.
+
+```ts
+interface InspectReport {
+  frame: number; time: number; canvas: { width: number; height: number };
+  summary: { layers: number; visible: number };
+  issues: string[];              // text off the canvas / cut by an edge / empty / overlapping other text — read this first
+  layers: Array<{
+    path: string;                // names (or type#index) from the root, joined by '/'
+    name?: string; type: string; threeD: boolean;
+    visible: boolean;            // alive at this frame, not hidden by an ancestor, alpha > 0
+    alpha: number;
+    bounds: { x: number; y: number; width: number; height: number } | null;   // canvas pixels; null inside a threeD layer
+    onCanvas: 'full' | 'partial' | 'none' | null;
+  }>;
+}
+```
+
+### `movie.render(options?): Promise<Blob>`
+
+Renders the entire timeline to a single video file. Pauses playback first.
+
+```ts
+interface RenderOptions {
+  format?: 'mp4' | 'mov' | 'webm' | 'mkv';   // default 'mp4'
+  video?: {
+    codec?:   string;   // default per format (mp4/mov→avc, webm/mkv→vp9)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+  };
+  audio?: {
+    codec?:   string;   // default per format (mp4/mov→aac, webm/mkv→opus)
+    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';   // default 'high'
+  };
+}
+```
+
+Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.
+
+The renderer also forces a keyframe every ~2 seconds so the resulting file scrubs efficiently in standard players.
+
+### `movie.destroy(): Promise<void>`
+
+Pauses playback, destroys the underlying PIXI Application, releases audio buffers and AudioContext, and marks the instance unusable.
+
+### Events
+
+```ts
+movie.on(event, fn): this
+movie.off(event, fn): this
+```
+
+| Event       | Payload                                           | Fired                                                 |
+| ----------- | ------------------------------------------------- | ----------------------------------------------------- |
+| `'ready'`   | none                                              | once, after `init()` resolves                         |
+| `'frame'`   | `{ frame: number; totalFrames: number }`          | every `gotoFrame` (so once per playback frame too)    |
+| `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
+| `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
+
+`progress` is `0..100` (rounded integer percent).
+
+### Public properties
+
+| Property         | Type      | Notes                                                   |
+| ---------------- | --------- | ------------------------------------------------------- |
+| `isPlaying`      | boolean   | true while the rAF loop is active                       |
+| `currentFrame`   | number    | 0-based current frame                                   |
+| `totalFrames`    | number    | `Math.round(duration * frameRate)`                      |
+| `frameRate`      | number    | from `init`                                             |
+| `duration`       | number    | seconds                                                 |
+| `width`, `height`| number    | canvas pixels                                           |
+| `background`     | string    | CSS color                                               |
+| `volume`         | number    | 0..1 getter/setter; immediate. Setter clamps and applies to active audio |
+| `muted`          | boolean   | getter/setter; immediate                                |
+| `app`            | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
+| `timeline`       | GSAP Timeline `\| null`         | underlying GSAP timeline (advanced)              |
+
+### `movie.toggleMute(): boolean`
+
+Flips `muted` and returns the new value.
+
+---
+
+## `Controller`
+
+Imported from `pixi-effects/controller`.
+
+```ts
+import { Controller } from 'pixi-effects/controller';
+
+const ctrl = new Controller(movie, { canvas });
+// later:
+ctrl.destroy();
+```
+
+A YouTube-style overlay anchored to the canvas:
+
+```
+[▶] [🔉━━━] 0:00 / 0:08 ··· [⬇] [⛶]
+└── play   └── volume   └── time     └── export   └── fullscreen
+```
+
+The bar auto-hides 2.5s after pointer activity stops (in both playing and paused state) and reappears on pointer move. Clicking the download icon opens a popover with format/quality selectors and a `Download` confirm button. Fullscreen scales the canvas + bar to the viewport.
+
+### Constructor
+
+```ts
+new Controller(movie: Movie, options: ControllerOptions)
+
+interface ControllerOptions {
+  canvas: HTMLCanvasElement;          // required
+  showExportButton?: boolean;         // default true; hides ⬇ + popover
+  enableKeyboardShortcuts?: boolean;  // default true
+  className?: string;                 // default 'movie-controller'
+}
+```
+
+Mounting strategy:
+
+- If `canvas.parentElement` already has a non-static `position`, the controller is appended directly into it.
+- Otherwise the canvas is wrapped in a `<div class="movie-controller-wrap">` (with `position: relative`). The wrapper is removed on `destroy()`.
+
+### `controller.destroy(): void`
+
+Idempotent. Removes:
+
+- the controller bar DOM
+- all listeners (Movie events, document keydown/pointerdown/fullscreenchange, wrapper pointermove/mouseleave)
+- the auto-hide timer
+- the wrapper, if it was created here
+- the injected stylesheet (ref-counted across multiple controllers)
+
+If the controller still owns `document.fullscreenElement`, it calls `exitFullscreen()`.
+
+### Export popover
+
+Format options: **MP4**, **WebM**, **MOV** (mp4 ↔ avc/aac, webm ↔ vp9/opus, mov ↔ avc/aac).
+
+Quality options: **Low**, **Medium**, **High** (default), **Very High**.
+
+These map directly to `Movie.render()`'s `format` and `video.bitrate` / `audio.bitrate` parameters. Selection persists for the lifetime of the controller instance (no localStorage).
+
+The download is triggered by an in-page `<a download>` click, so the file lands in the browser's default download location with a name like `movie-{YYYYMMDD-HHMMSS}.{ext}`.
+
+### Keyboard shortcuts
+
+Active when `enableKeyboardShortcuts: true` and the key target is not `<input>`/`<textarea>`/`<select>`/contenteditable.
+
+| Key         | Action                                              |
+| ----------- | --------------------------------------------------- |
+| `Space`     | play / pause                                        |
+| `←` / `→`   | step ±1 frame                                       |
+| `↑` / `↓`   | volume ±5% (clears mute when increasing past zero)  |
+| `M`         | toggle mute                                         |
+| `Shift+E`   | export with current settings (skips the popover)    |
+| `F`         | toggle fullscreen                                   |
+| `Esc`       | close the export popover or exit fullscreen (browser) |
+
+### Theming
+
+The bar uses fixed colors (`#007AFF` for the active track / fill / confirm button, white for icons, `rgba(0,0,0,0.75)` gradient background). Override by adding stricter CSS rules under `.movie-controller`. A theming API (CSS custom properties) is on the roadmap.
+
+---
+
+## Helpers
+
+These pure functions are exported from `pixi-effects/controller` for consumers who want to build custom controls or reuse the parsing utilities. All are side-effect-free.
+
+```ts
+import { formatTime, frameToPercent, pxToFrame, pxToFraction, extensionForMimeType }
+  from 'pixi-effects/controller';
+```
+
+### `formatTime(seconds: number): string`
+
+Returns `M:SS` (no leading zero on minutes). `formatTime(125)` → `"2:05"`. Negatives clamp to zero.
+
+### `frameToPercent(frame: number, totalFrames: number): number`
+
+Returns 0..100 (clamped). `totalFrames <= 0` returns 0.
+
+### `pxToFrame(clientX, rect, totalFrames): number`
+
+Maps a pointer X coordinate (relative to viewport) inside a `DOMRect`-shaped object to a frame index 0..totalFrames. Rounded.
+
+```ts
+pxToFrame(150, { left: 100, width: 200 } as DOMRect, 100)  // 25
+```
+
+### `pxToFraction(clientX, rect, inset?): number`
+
+Same as `pxToFrame` but returns a normalized 0..1 fraction. The optional `inset` shrinks the active range by that many pixels on each side (used internally for the volume slider).
+
+### `extensionForMimeType(mime: string): string`
+
+Maps common video MIME types to file extensions. Falls back to `'mp4'`.
+
+| MIME contains       | Extension |
+| ------------------- | --------- |
+| `webm`              | `webm`    |
+| `quicktime` / `mov` | `mov`     |
+| `matroska` / `mkv`  | `mkv`     |
+| anything else       | `mp4`     |
+
+---
+
+## `pixi-effects/three`
+
+Optional three.js integration, imported from its own entry so the core `pixi-effects` entry never touches three.js:
+
+```ts
+import { registerThree, three, ThreeSequence } from 'pixi-effects/three';
+```
+
+**Install:** `npm i three`. `three` is a peer dependency marked optional (`peerDependenciesMeta.three.optional = true`) — consumers who never import `pixi-effects/three` are unaffected either way.
+
+For the `type: 'three'` spec shape (fields, keyframe paths, rules), see [DSL reference § three](./dsl.md#three).
+
+### `registerThree(): void`
+
+Registers the `'three'` sequence type with the composition builder. Call once, before `Movie.init()` builds a composition containing a `type: 'three'` sequence. Idempotent.
+
+### `three(spec: ThreeSequenceSpec): SequenceSpec`
+
+Typing helper — accepts a strongly-typed three spec and returns it as a plain `SequenceSpec`, so it drops straight into `composition.sequences` alongside `text` / `image` / etc. A cast only; not required for the sequence to work, but gives editor autocomplete on `setup` / `update` / `dispose`.
+
+### `ThreeSequence`
+
+The `Sequence` subclass that backs `type: 'three'`. Exported for advanced use (e.g. `instanceof` checks); most consumers only need `registerThree()` and `three()`.
+
+### Exported types
+
+```ts
+import type { ThreeContext, ThreeSetupResult, ThreeSequenceSpec } from 'pixi-effects/three';
+```
+
+| Type                | Notes                                                                          |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `ThreeContext`      | `{ scene, camera, renderer, width, height }` handed to `setup` / `update` / `dispose`. |
+| `ThreeSetupResult`  | `{ objects?, camera? }` returned from `setup`.                                 |
+| `ThreeSequenceSpec` | the `type: 'three'` sequence spec.                                             |