pixi-effects 0.16.1 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.16.2
+
+**Site**
+
+- **A landing page** at the root of the GitHub Pages site (`site/landing/index.html`, replacing the plain list of examples): a hero whose video is the exact snippet shown beside it, running live in the browser after a click; "Start with one sentence" (`Use https://github.com/yjmtmtk/pixi-effects to make a video: …`); what you get; how an AI writes and checks it (contact sheet, timeline); a gallery strip; and an honest comparison with Remotion and fframes (facts read from their own pages on 2026-10-07, with when NOT to choose pixi-effects). A poster in its gallery strip plays that piece in a player on the page (its link goes to that piece in the gallery; the frame shows only the picture: the piece's page is scaled so its canvas sits exactly on the frame, with no scrollbars, measured for all 16 posters at 1440 and 390 px); "A real piece, live" plays on the first click. `npm run landing` builds a local preview. Written by Fable from a fact sheet (`site/landing/FACTS.md`); tests keep it honest (the release it names, the links, its size, no third-party loads).
+- **`AGENTS.md`** (and `CLAUDE.md`, which imports it) and a one-sentence start at the top of the README: an AI that is told only "Use https://github.com/yjmtmtk/pixi-effects to make a video" is sent to the right file for what it can do (a shell, or a chat with no shell). Tried with a fresh session given only that sentence: it found its way and made a video.
+
+**Changed**
+
+- **`animateText()` and `splitText()` reject an expression string for `x` / `y`** with an error that says what to write (`x: 640`): `animateText({ x: 'GW/2' })` used to draw nothing, silently, because the letters are measured at build time. The docs now say that `y` is the top of the line. (Found by a fresh AI session given only the repository URL.)
+
+**Fixed**
+
+- **A `threeD` card showed the previous frame after a seek.** A card (a `threeD` composition) is drawn into its own texture before the stage is drawn, but the shapes inside it were only brought up to the playhead after that, so after a jump seek, `snapshot()`, `contactSheet()` and the paused canvas showed a card whose children had animated (a `trimEnd` draw-on, a growing box) as it was one seek earlier: lines half drawn or missing. Seeking the same frame twice hid it; playing forward and the export were one frame late. The layers are now synced first. (Found by the Opus showpiece `ma`, whose gate lines were missing in review pictures.)
+
+**Added**
+
+- **`cameraPath({ points, duration, ease, look, … })`**: a camera flight through `[x, y, z]` points as keyframes (a smooth curve at an even speed; an `ease` such as `'power2.in'` accelerates; it faces where it flies, or a fixed `look`). With the recipe `camera-fly-through`.
+- **Camera `offsetX` / `offsetY` / `offsetZ` and `lookOffsetX` / `lookOffsetY` / `lookOffsetZ`**: added to the camera's position and look-at point, so a handheld shake (`wiggle()`) on them never collides with a dolly or an orbit (two tweens on one property overwrite each other).
+- **`hideBehindCamera: true`** on a threeD layer the camera passes on purpose: it is hidden quietly behind the camera instead of warning.
+- **`trimEach: true`** on a `path` with several sub-paths: every sub-path is trimmed on its own, so they all draw on at the same time (a glyph or logo made of several strokes). The default is unchanged: the trim walks the sub-paths in order as one outline. (From the Opus showpiece's list: it had given every sub-path its own layer.)
+- **A showpiece in the gallery: `ma`** (「間 MA — the space between」, 48 s, 1920×1080, by Opus): a kinetic essay about one word, with a corridor of 2.5D gates, a beat of true silence and a score written as text. 39 pieces. Its notes list the library gaps it ran into (a seek redraw bug for 3D cards, `trimEnd` across subpaths, camera paths, a shared mask, grain, an animatable gradient).
+
 ## 0.16.1
 
 **Added**

package/README.md

@@ -1,14 +1,16 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.16.1`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.16.1` adds `musicBuffer()` and a music lab page with eight tunes, `0.16.0` adds music written as text (`{ type: 'audio', music }`, `musicEnvelope()`), `0.15.0` adds a way in for an AI in a browser chat (`ai/CHAT.md` and `ai/chat-template.html`), `0.14.0` adds `movie.inspectStops()` (and a check review) for stops that land mid-animation, `0.13.1` fixes decks starting past their first stop in the guide and gallery and draws the stop marks as dots, `0.13.0` makes the player bar play a deck stop by stop (`pauseAtStops`), marks the stops more clearly, adds PDF to the download panel and a `pdf` flag on stops, `0.12.0` adds presentations (`stops`, `Presenter`, `deck()`, page overview, presenter view, PDF export) and audio-reactive visuals (`audioEnvelope()`, `react()`), `0.11.0` adds particles, motion blur, a shared loader and a much faster build for pieces with many layers, `0.10.0` adds seeded randomness, `wiggle` and `stagger`, null layers with `parent`, `animateText`, `followPath` and path morphing, and click-to-play in the player, `0.9.0` adds a poster time (`movie.init({ poster })`) and a guide site, `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
+> **Status**: experimental — current release `0.16.2`. The API may still change between minor versions (see [CHANGELOG](./CHANGELOG.md): `0.16.2` adds a landing page, `AGENTS.md` and a one-sentence start for AI, camera flights (`cameraPath`, shake offsets), `trimEach`, the showpiece `ma` and a fix for 3D cards after a seek, `0.16.1` adds `musicBuffer()` and a music lab page with eight tunes, `0.16.0` adds music written as text (`{ type: 'audio', music }`, `musicEnvelope()`), `0.15.0` adds a way in for an AI in a browser chat (`ai/CHAT.md` and `ai/chat-template.html`), `0.14.0` adds `movie.inspectStops()` (and a check review) for stops that land mid-animation, `0.13.1` fixes decks starting past their first stop in the guide and gallery and draws the stop marks as dots, `0.13.0` makes the player bar play a deck stop by stop (`pauseAtStops`), marks the stops more clearly, adds PDF to the download panel and a `pdf` flag on stops, `0.12.0` adds presentations (`stops`, `Presenter`, `deck()`, page overview, presenter view, PDF export) and audio-reactive visuals (`audioEnvelope()`, `react()`), `0.11.0` adds particles, motion blur, a shared loader and a much faster build for pieces with many layers, `0.10.0` adds seeded randomness, `wiggle` and `stagger`, null layers with `parent`, `animateText`, `followPath` and path morphing, and click-to-play in the player, `0.9.0` adds a poster time (`movie.init({ poster })`) and a guide site, `0.8.0` adds events and a theme for building your own player, `0.7.0` adds filters by name, the `pixi-effects-render` and `pixi-effects-view` commands and the timeline chart, `0.6.0` adds draw-on strokes (`trimEnd`) and text that changes over time, `0.5.0` adds synthesised sound effects (`sfx`, no files) and the `check` tool, `0.4.0` makes a mask share its layer's lifetime, `0.3.0` made keyframe `at` relative to the layer).
 
-**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 38 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
+**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 39 portfolio pieces written as plain data by AI models · **[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
 
-**Make a video with an AI chat** (no install): paste this to ChatGPT or Claude in the browser, then open the file it gives you and use the download button in the player bar for the MP4:
+## Make a video by asking an AI
 
-> Read https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md and follow it. Make a 10-second 1280×720 title video for … (what you see, the colours, what you hear). Give me the whole HTML file.
+Give any AI (ChatGPT, Claude, Codex, Cursor, Claude Code …) one sentence:
 
-(For an AI that has a shell and a browser, such as Claude Code: [`ai/SKILL.md`](./ai/SKILL.md).)
+> Use https://github.com/yjmtmtk/pixi-effects to make a video: a 10-second title for a bakery, warm colours, a soft chime at the end.
+
+That is all it needs. **If you are the AI** that was asked to do this, do not read the whole repository: if you can run commands (a shell, Node 22, Chrome), read [`AGENTS.md`](./AGENTS.md) and [`ai/SKILL.md`](./ai/SKILL.md); if you can only write text (a browser chat), fetch https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md and follow it. You will write the video as plain data in one HTML file, check it (the check tool writes a contact sheet to look at), and hand it over; the person opens the file and downloads the MP4 with the button in the player bar.
 
 Declarative composition and video rendering for the web. After Effects-style timelines on top of [PixiJS v8](https://pixijs.com/) and [GSAP](https://gsap.com/), with strict TypeScript types. Render to MP4 / WebM / MOV via [mediabunny](https://mediabunny.dev/).
 
@@ -49,8 +51,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
     "gsap":                    "https://esm.sh/gsap@3.12.5",
     "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/Controller.js"
   }
 }
 </script>
@@ -61,7 +63,7 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
 </script>
 ```
 
-Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.16.1/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.16.2/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
 
 > **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
 >
@@ -77,7 +79,7 @@ Add two more entries to the importmap above: three.js itself, and the `pixi-effe
   "imports": {
     "...":                     "(everything from the importmap above)",
     "three":                   "https://esm.sh/three@0.178.0",
-    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/three.js"
   }
 }
 </script>

package/ai/SKILL.md

@@ -33,7 +33,7 @@ You describe a video as a tree of plain objects; the library plays it in a canva
 - **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.
 - **Group / parent layers = `{ type: 'null', name: 'rig' }`** (draws nothing, only moves) + `parent: 'rig'` on the layers that should follow it: their `x`/`y` are then measured from the null's origin, and the null's position / rotation / scale / alpha carry them (orbits, clock hands, grouped fades). Nulls chain. Only `null` layers can be parents; not for `threeD` layers.
-- **Built in:** `animateText()` (per-letter / per-word / per-line entrances and exits in one call: `...animateText('Title', style, { x, y, align: 'center', at: 0.5, duration: 5, in: 'rise', out: 'fade', stagger: { each: 0.05 } })`), `splitText()` / `measureText()` (per-letter / per-word layers, exact positions, by hand), `shape: 'arc'` (progress rings, pie / donut slices: animate `endAngle`), `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`, seeded randomness (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS, never `Math.random()`) `wiggle()` (a seeded shake as keyframes) `music` (a tune with no file: `{ type: 'audio', music: { bpm, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }, { inst: 'bass', notes: 'c2:2 g1:2' }], drums: { from: 8, kick: 'x...x...' } } }`: notes and chords as text, counted in beats; instruments `keys pluck pad bass sub lead bell musicbox`; `musicEnvelope(music)` feeds `react()`), `audioEnvelope()` / `bpmEnvelope()` + `react()` (visuals that follow music: `const env = await audioEnvelope('music.mp3', { frameRate })` before `movie.init`, then `keyframes: react(env, { duration, props: { scale: { base: 1, amount: 0.4, band: 'bass', release: 0.2 } } })`; `beats: true` pulses on the beats; `bpmEnvelope(120, …)` when there is no file), `deck()` + `Presenter` (a talk as one movie: pages, steps, stops that pause playback, arrow keys / click / swipe to move on: `...deck({ transition: { kind: 'slide', duration: 0.6 }, pages: [{ name, duration, stops, sequences }] })`, `new Presenter(movie, { canvas })` from `pixi-effects/presenter`; G = page overview, P = presenter view with notes and a timer; `pixi-effects-render talk.html -o talk.pdf` = a PDF of the pages), `particles()` (bursts, snow, confetti, sparks as seeded layers: `...particles({ count: 90, at: 2, life: [1, 1.8], area: { x: 640, y: 330 }, speed: [120, 420], gravity: 240, fade: { out: 0.6 } })`), `followPath()` (a layer along an SVG path: `keyframes: followPath({ d, duration, orient: true })`), path morphing (`{ shape: 'path', d, morphTo, initial/keyframes: morph 0 → 1 }`) and `stagger()` (delays for a wave of layers: `stagger(letters, { each: 0.05, from: 'center' })`, or `stagger(n, …)` for numbers; GSAP-style `each` / `amount` / `from` / `grid` / `ease`). **Not in the DSL (hand-roll with a JS loop):** other per-frame curves (waves, spirals: sample them into short linear keyframes), shared masks. (Draw-on strokes `trimEnd`, text that changes over time `set: { text }` / `visibleChars`, shake `wiggle()` and particles are built in.)
+- **Built in:** `animateText()` (per-letter / per-word / per-line entrances and exits in one call: `...animateText('Title', style, { x, y, align: 'center', at: 0.5, duration: 5, in: 'rise', out: 'fade', stagger: { each: 0.05 } })`), `splitText()` / `measureText()` (per-letter / per-word layers, exact positions, by hand), `shape: 'arc'` (progress rings, pie / donut slices: animate `endAngle`), `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`, seeded randomness (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS, never `Math.random()`) `wiggle()` (a seeded shake as keyframes; on a camera put it on `offsetX` / `offsetY` so it rides on the move) `cameraPath()` (a camera flight through `[x, y, z]` points as keyframes; layers it passes: `hideBehindCamera: true`) `music` (a tune with no file: `{ type: 'audio', music: { bpm, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }, { inst: 'bass', notes: 'c2:2 g1:2' }], drums: { from: 8, kick: 'x...x...' } } }`: notes and chords as text, counted in beats; instruments `keys pluck pad bass sub lead bell musicbox`; `musicEnvelope(music)` feeds `react()`), `audioEnvelope()` / `bpmEnvelope()` + `react()` (visuals that follow music: `const env = await audioEnvelope('music.mp3', { frameRate })` before `movie.init`, then `keyframes: react(env, { duration, props: { scale: { base: 1, amount: 0.4, band: 'bass', release: 0.2 } } })`; `beats: true` pulses on the beats; `bpmEnvelope(120, …)` when there is no file), `deck()` + `Presenter` (a talk as one movie: pages, steps, stops that pause playback, arrow keys / click / swipe to move on: `...deck({ transition: { kind: 'slide', duration: 0.6 }, pages: [{ name, duration, stops, sequences }] })`, `new Presenter(movie, { canvas })` from `pixi-effects/presenter`; G = page overview, P = presenter view with notes and a timer; `pixi-effects-render talk.html -o talk.pdf` = a PDF of the pages), `particles()` (bursts, snow, confetti, sparks as seeded layers: `...particles({ count: 90, at: 2, life: [1, 1.8], area: { x: 640, y: 330 }, speed: [120, 420], gravity: 240, fade: { out: 0.6 } })`), `followPath()` (a layer along an SVG path: `keyframes: followPath({ d, duration, orient: true })`), path morphing (`{ shape: 'path', d, morphTo, initial/keyframes: morph 0 → 1 }`) and `stagger()` (delays for a wave of layers: `stagger(letters, { each: 0.05, from: 'center' })`, or `stagger(n, …)` for numbers; GSAP-style `each` / `amount` / `from` / `grid` / `ease`). **Not in the DSL (hand-roll with a JS loop):** other per-frame curves (waves, spirals: sample them into short linear keyframes), shared masks. (Draw-on strokes `trimEnd`, text that changes over time `set: { text }` / `visibleChars`, shake `wiggle()` and particles are built in.)
 - **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.
 

package/ai/chat-template.html

@@ -61,9 +61,9 @@
       "gsap":                    "https://cdn.jsdelivr.net/npm/gsap@3.12.5/+esm",
       "gsap/PixiPlugin":         "https://cdn.jsdelivr.net/npm/gsap@3.12.5/PixiPlugin/+esm",
       "mediabunny":              "https://cdn.jsdelivr.net/npm/mediabunny@1.61.3/+esm",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Presenter.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/Presenter.js"
     }
   }
   </script>

package/ai/reference/cheatsheet.md

@@ -70,7 +70,7 @@ Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate t
 | polygon | `points: [[x,y],…]  open` — canvas coordinates like `line` |
 | path | `d` (SVG path data) — canvas coordinates like `line`. **Morph:** `morphTo: 'M…Z'` + animate `morph` 0 → 1 (points half way between, closed outlines lined up so they do not twist; `morphPoints` 8–2048) |
 
-**Draw-on:** every shape but `arc` has `trimStart` / `trimEnd` (0–1 of the outline, default 0 / 1, animatable): `trimEnd: 0` + keyframe `to: { trimEnd: 1 }` draws a line / border / path on; `trimStart` 0 → 1 after it wipes it off; both = a travelling dash. The fill is NOT trimmed. Rect outline starts top-left, circle / ellipse at 12 o'clock, both clockwise. Use `strokeCap: 'round'`.
+**Draw-on:** every shape but `arc` has `trimStart` / `trimEnd` (0–1 of the outline, default 0 / 1, animatable): `trimEnd: 0` + keyframe `to: { trimEnd: 1 }` draws a line / border / path on; `trimStart` 0 → 1 after it wipes it off; both = a travelling dash. The fill is NOT trimmed. Rect outline starts top-left, circle / ellipse at 12 o'clock, both clockwise. A `path` with several sub-paths walks them in order as one length; `trimEach: true` trims each on its own (all draw on together). Use `strokeCap: 'round'`.
 
 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. Stroke ends and corners: `strokeCap: 'butt'|'round'|'square'`, `strokeJoin: 'miter'|'round'|'bevel'` (top level or in `initial`; not animated — `round` keeps sharp corners like an M from poking out).
 
@@ -82,6 +82,10 @@ Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha stro
 
 **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`.
 
+## Camera flight and a camera shake
+
+`...cameraPath({ points: [[x, y, z], …], duration, ease, look: 'ahead' | [x, y, z], lookAhead: 0.08, smooth: true, from, to, frameRate })` → camera keyframes (`x y z lookAtX lookAtY lookAtZ`) along a smooth curve at even speed (`ease: 'power2.in'` accelerates). A handheld shake goes on the camera's **offsets** so it never collides with the move: `...wiggle({ duration, props: { offsetX: { around: 0, amp: 5 }, offsetY: {…} } })` (`offsetX/Y/Z`, `lookOffsetX/Y/Z` are added to the position and the look-at point). A threeD layer the camera passes on purpose: `hideBehindCamera: true` (hidden quietly behind the camera, no warning). Recipe `camera-fly-through`.
+
 ## 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`.
@@ -111,7 +115,7 @@ transitions: [{ kind: 'crossfade' | 'wipe' | 'iris' | 'slide' | 'dip' | 'zoom' |
 ## Presets
 
 ```js
-import { kenBurns, withFade, wiggle, stagger, followPath, particles, deck, audioEnvelope, bpmEnvelope, musicEnvelope, react, random } from 'pixi-effects';
+import { kenBurns, withFade, wiggle, stagger, followPath, cameraPath, particles, deck, audioEnvelope, bpmEnvelope, musicEnvelope, react, random } 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
@@ -146,7 +150,7 @@ measureText('Hello', style)                              // → { width, height,
 splitText('Hello world', style, { by: 'chars' | 'words' | 'lines', x, y, align: 'left' | 'center' | 'right' })
                                                          // → [{ text, x, y, width, index, line }] — one text layer per piece, same style, anchor top-left
 ```
-Per-letter / per-word / per-line animation in one call: `...animateText(text, style, { x, y, align, by: 'chars'|'words'|'lines', at, duration /* required: until the last piece is gone */, in: 'rise'|'drop'|'fade'|'pop'|'zoom'|'slide'|'spin'|{ from, to, duration, ease }|false, out: <same, runs in the same wave>, stagger: { each, from, … }, idle: { y: 4, rotation: 1 }, styleFor: p => ({ fill }) })` → text layers `<name>-0…` (anchor centre; `x`/`y` in `from` are offsets) to spread into `sequences` (recipe `animate-text`). By hand: `splitText(...)` + one layer per piece (recipe `split-text`). A web font must be loaded before measuring.
+Per-letter / per-word / per-line animation in one call: `...animateText(text, style, { x, y, align, by: 'chars'|'words'|'lines', at, duration /* required: until the last piece is gone */, in: 'rise'|'drop'|'fade'|'pop'|'zoom'|'slide'|'spin'|{ from, to, duration, ease }|false, out: <same, runs in the same wave>, stagger: { each, from, … }, idle: { y: 4, rotation: 1 }, styleFor: p => ({ fill }) })` → text layers `<name>-0…` (anchor centre; `x`/`y` in `from` are offsets) to spread into `sequences`. **`x` / `y` are pixel NUMBERS (an expression like `'GW/2'` throws: compute `W / 2`), and `y` is the TOP of the line box**: the visible text is centred `lineHeight / 2` below it, so an underline goes at `y + lineHeight`, not at `y` (recipe `animate-text`). By hand: `splitText(...)` + one layer per piece (recipe `split-text`). A web font must be loaded before measuring.
 
 ## Assets
 

package/ai/reference/pitfalls.md

@@ -87,4 +87,5 @@ A good habit that catches most of these: after `init`, read `window.__logs` (see
 60. **Build-ups are layers and `vol` points, not louder notes.** A track's `vol` can be `[[0, 0], [8, 0.7]]` (a fade over 8 beats); the pad's `attack` can be 2–3 s; enter instruments with rests. Per-note `!` and `,` only accent and soften.
 61. **Music is a bed: `volume` 0.5–0.8 under speech or sfx.** At `volume: 1` it peaks at −6 dBFS (an sfx peaks at −12). A layer shorter than the music cuts it with a fade; longer is silent after it unless `loop: true`. Do not also add an mp3 bed.
 62. **Chord names are voiced close around octave 3**: use `[c3 g3 e4]` for an exact voicing or `Am7/e` for a bass note; `swing` only moves notes that start on an off-beat eighth (`.5`) or sixteenth (`.75`); the bell and music box ring for `ring` seconds whatever the written length (shorten `ring` for fast bell lines); the synth is a handy bed, not an orchestra: keep tracks to 3–6, vary the bars, and end on the tonic.
+63. **`animateText()` / `splitText()`: `x` and `y` are pixel numbers, and `y` is the TOP of the line.** An expression such as `x: 'GW/2'` throws (the letters are measured once, at build time): write `x: W / 2`. The pieces are centred half a line below `y`, so a line drawn under the text goes at `y + lineHeight` (about 1.2 × `fontSize`), not at `y`; look at the contact sheet, the layout check cannot see an underline through a word. (`check` writes into `check-out/` of the current folder unless you pass `--out`.)
 

package/ai/reference/recipes.md

@@ -589,6 +589,29 @@ new Presenter(movie, { canvas });     // arrows / Space / Enter / click / swipe
 
 ---
 
+## A camera flight through a corridor (`cameraPath`, `hideBehindCamera`, a handheld shake)
+
+`cameraPath({ points, duration, ease })` is the camera's route as keyframes: a smooth curve through `[x, y, z]` points at an even speed (an `ease` shapes it; `'power2.in'` is an accelerating rush), facing where it flies (`look: 'ahead'`, the default) or at a fixed `look: [x, y, z]`. Layers the camera passes get `hideBehindCamera: true` (hidden quietly instead of a warning). A handheld shake goes on the camera's **offsets** (`offsetX`, `offsetY`, `offsetZ`, `lookOffsetX`…): they are added to the move, so a `wiggle()` never collides with the dolly.
+
+```js
+// @recipe camera-fly-through
+const gate = (i, z) => ({
+  type: 'composition', name: 'gate-' + i, threeD: true, hideBehindCamera: true, width: 360, height: 480,
+  initial: { x: 640, y: 360, z, pivotX: 180, pivotY: 240 },
+  sequences: [{ type: 'shape', shape: 'rect', width: 330, height: 450, cornerRadius: 6, initial: { x: 180, y: 240, strokeColor: '#ffe9c4', strokeWidth: 6 } }],
+});
+return { duration: 8, sequences: [
+  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0b0a10' } },
+  ...Array.from({ length: 9 }, (_, i) => gate(i, -i * 380)),
+  { type: 'camera', keyframes: [
+    ...cameraPath({ points: [[640, 360, 2200], [690, 330, 900], [640, 360, -3000]], duration: 7, ease: 'power2.in', frameRate: 30 }),
+    ...wiggle({ duration: 7, freq: 9, seed: 2, props: { offsetX: { around: 0, amp: 5 }, offsetY: { around: 0, amp: 3 } } }),
+  ] },
+] };
+```
+
+---
+
 ## Looping motion
 
 `repeat` (a finite count) and `yoyo` go on any keyframe. Total time = `duration × (repeat + 1)`.

package/ai/template.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>pixi-effects video</title>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/loader.css" />   <!-- the loader: HTML + CSS only, so it is on screen at once and keeps moving while the page builds the video -->
   <style>
     body { background: #0d1220; margin: 0; padding: 16px; }
     .stage { position: relative; width: min(960px, 100%); }                 /* the player and the loader both sit inside this box */
@@ -39,10 +39,10 @@
       "gsap":                    "https://esm.sh/gsap@3.12.5",
       "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
       "mediabunny":              "https://esm.sh/mediabunny",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/Presenter.js",
-      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.1/dist/three.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/Presenter.js",
+      "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.16.2/dist/three.js",
       "pixi-filters":            "https://esm.sh/pixi-filters@6.1.5?external=pixi.js",
       "three":                   "https://esm.sh/three@0.178.0"
     }

package/dist/{Base-qvqNxvyt.d.ts → Base-BQUodYZK.d.ts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-C8XEUoqe.js';
+import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-SS51lP6O.js';
 import { gsap } from 'gsap';
 
 /**

package/dist/{Base-DPEqyeB0.d.cts → Base-OHqp8qvX.d.cts}

@@ -1,5 +1,5 @@
 import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
-import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-C8XEUoqe.cjs';
+import { S as SequenceSpec, C as CompositionShape, a0 as AudioDescriptor } from './types-SS51lP6O.cjs';
 import { gsap } from 'gsap';
 
 /**

package/dist/Composition-3WWNVRR5.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var chunk2ROVCPSL_cjs = require('./chunk-2ROVCPSL.cjs');
+require('./chunk-FJA5VUOF.cjs');
+require('./chunk-UQBGW5DO.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunk2ROVCPSL_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-3WWNVRR5.cjs.map
+//# sourceMappingURL=Composition-3WWNVRR5.cjs.map

package/dist/{Composition-ZZGSMQ4E.cjs.map → Composition-3WWNVRR5.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-ZZGSMQ4E.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-3WWNVRR5.cjs"}

package/dist/Composition-VJWY2NDL.js

@@ -0,0 +1,5 @@
+export { CompositionSequence } from './chunk-XTIHKODH.js';
+import './chunk-ZNKQH356.js';
+import './chunk-DKGG7WD4.js';
+//# sourceMappingURL=Composition-VJWY2NDL.js.map
+//# sourceMappingURL=Composition-VJWY2NDL.js.map

package/dist/{Composition-X2VZSVPD.js.map → Composition-VJWY2NDL.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-X2VZSVPD.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-VJWY2NDL.js"}

package/dist/Controller.d.cts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-CJMfAizW.cjs';
+import { f as Movie } from './Movie-oA0SUAyb.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-C8XEUoqe.cjs';
+import './types-SS51lP6O.cjs';
 
 /** The bar's default stylesheet. Its colours and sizes are CSS custom properties (`--mc-accent`, `--mc-fg`, `--mc-track`, `--mc-bar-bg`, `--mc-track-height`, `--mc-font`): set them in your page CSS, or with the `theme` option. */
 declare const CONTROLLER_CSS = "\n.movie-controller-wrap { position: relative; display: inline-block; line-height: 0; }\n.movie-controller {\n  position: absolute;\n  pointer-events: none;\n  font-family: var(--mc-font, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif);\n  display: flex;\n  flex-direction: column;\n  justify-content: flex-end;\n  opacity: 1;\n  transition: opacity 200ms ease;\n}\n.movie-controller[data-state=\"hidden\"] { opacity: 0; }\n.movie-controller > * { pointer-events: auto; }\n\n.mc-progress {\n  position: relative;\n  width: 100%;\n  height: 16px;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  outline: none;\n}\n.mc-progress:focus-visible {\n  outline: 2px solid var(--mc-accent, #007AFF);\n  outline-offset: 2px;\n}\n.mc-progress::before {\n  content: \"\"; position: absolute; left: 12px; right: 12px;\n  height: var(--mc-track-height, 3px); background: var(--mc-track, rgba(255,255,255,0.25));\n  transition: height 120ms ease;\n}\n.mc-progress:hover::before, .mc-progress.mc-scrubbing::before { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-stops { position: absolute; left: 12px; right: 12px; top: 0; bottom: 0; pointer-events: none; }\n.mc-stop-tick { position: absolute; top: 50%; width: 7px; height: 7px; transform: translate(-50%, -50%); border-radius: 50%; background: var(--mc-fg, #fff); box-shadow: 0 0 0 1.5px rgba(0,0,0,0.5); }\n.mc-stop-page { width: 11px; height: 11px; box-shadow: 0 0 0 2.5px var(--mc-accent, #007AFF), 0 0 0 4px rgba(0,0,0,0.35); }\n.mc-progress-fill {\n  position: absolute; left: 12px; top: 50%;\n  height: var(--mc-track-height, 3px);\n  width: calc((100% - 24px) * var(--mc-fill, 0));\n  background: var(--mc-accent, #007AFF);\n  transform: translateY(-50%);\n  transition: height 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-fill,\n.mc-progress.mc-scrubbing .mc-progress-fill { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-progress-thumb {\n  position: absolute; top: 50%;\n  left: calc(12px + (100% - 24px) * var(--mc-fill, 0));\n  width: 12px; height: 12px; border-radius: 50%;\n  background: var(--mc-accent, #007AFF);\n  transform: translate(-50%, -50%) scale(0);\n  transition: transform 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-thumb,\n.mc-progress.mc-scrubbing .mc-progress-thumb { transform: translate(-50%, -50%) scale(1); }\n\n.mc-bar {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 12px 8px 12px;\n  background: var(--mc-bar-bg, linear-gradient(to top, rgba(0,0,0,0.75) 0%, rgba(0,0,0,0) 100%));\n  color: var(--mc-fg, #fff);\n  line-height: 1;\n}\n.mc-btn {\n  background: none; border: 0; padding: 0; margin: 0;\n  width: 28px; height: 28px;\n  display: inline-flex; align-items: center; justify-content: center;\n  color: var(--mc-fg, #fff); opacity: 0.85; cursor: pointer;\n  transition: opacity 120ms ease;\n}\n.mc-btn:hover { opacity: 1; }\n.mc-btn:disabled { opacity: 0.4; cursor: not-allowed; }\n.mc-time {\n  font-size: 12px; font-family: Menlo, Monaco, monospace;\n  color: var(--mc-fg, #fff); opacity: 0.85;\n  min-width: 90px;\n}\n.mc-spacer { flex: 1; }\n\n.mc-volume { display: flex; align-items: center; }\n.mc-vol-slider {\n  position: relative;\n  width: 0;\n  height: 28px;\n  display: flex;\n  align-items: center;\n  cursor: pointer;\n  margin-left: 0;\n  outline: none;\n  transition: width 200ms ease, margin-left 200ms ease;\n  overflow: hidden;\n}\n.mc-volume:hover .mc-vol-slider,\n.mc-volume:focus-within .mc-vol-slider,\n.mc-vol-slider.mc-scrubbing {\n  width: 70px;\n  margin-left: 6px;\n}\n.mc-vol-slider:focus-visible { outline: 2px solid var(--mc-accent, #007AFF); outline-offset: 2px; }\n.mc-vol-slider::before {\n  content: \"\"; position: absolute; left: 4px; right: 4px;\n  height: 3px; background: var(--mc-track, rgba(255,255,255,0.25)); border-radius: 2px;\n}\n.mc-vol-fill {\n  position: absolute; left: 4px; top: 50%;\n  height: 3px;\n  width: calc((100% - 8px) * var(--mc-volume, 1));\n  background: var(--mc-fg, #fff);\n  transform: translateY(-50%);\n  border-radius: 2px;\n  pointer-events: none;\n}\n.mc-vol-thumb {\n  position: absolute; top: 50%;\n  left: calc(4px + (100% - 8px) * var(--mc-volume, 1));\n  width: 10px; height: 10px; border-radius: 50%;\n  background: var(--mc-fg, #fff);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n\n[data-mc-wrap]:fullscreen {\n  width: 100vw; height: 100vh;\n  display: flex; align-items: center; justify-content: center;\n  background: #000;\n}\n[data-mc-wrap]:fullscreen > canvas {\n  width: 100% !important;\n  height: 100% !important;\n  max-width: none !important;\n  max-height: none !important;\n  object-fit: contain;\n  border-radius: 0;\n}\n\n.mc-settings-popover {\n  position: absolute;\n  bottom: calc(100% + 8px);\n  right: 12px;\n  background: rgba(20, 20, 20, 0.96);\n  border-radius: 8px;\n  padding: 10px 12px;\n  min-width: 180px;\n  color: #fff;\n  font-size: 12px;\n  box-shadow: 0 4px 16px rgba(0,0,0,0.4);\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n.mc-settings-popover[data-open=\"false\"] { display: none; }\n.mc-settings-row {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 12px;\n}\n.mc-settings-row > span { color: rgba(255,255,255,0.85); }\n.mc-settings-row > select {\n  font: inherit;\n  background: rgba(255,255,255,0.1);\n  color: #fff;\n  border: 1px solid rgba(255,255,255,0.18);\n  border-radius: 4px;\n  padding: 2px 6px;\n  cursor: pointer;\n}\n.mc-export-confirm {\n  margin-top: 4px;\n  width: 100%;\n  background: var(--mc-accent, #007AFF);\n  color: #fff;\n  border: 0;\n  border-radius: 4px;\n  padding: 6px 10px;\n  font: inherit;\n  font-weight: 600;\n  cursor: pointer;\n  transition: background 120ms ease;\n}\n.mc-export-confirm:hover { background: #0066d6; }\n.mc-export-confirm:disabled { background: rgba(255,255,255,0.18); cursor: not-allowed; }\n\n.mc-export-overlay {\n  position: absolute; inset: 0;\n  background: rgba(0,0,0,0.7);\n  display: flex; justify-content: center; align-items: center;\n  z-index: 2;\n}\n.mc-export-panel {\n  background: rgba(20,20,20,0.96); color: #fff;\n  border-radius: 8px; padding: 16px 20px;\n  text-align: center; min-width: 200px; max-width: 80%;\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n}\n.mc-export-title { font-size: 13px; margin-bottom: 10px; opacity: 0.9; }\n.mc-export-track {\n  width: 100%; height: 6px;\n  background: rgba(255,255,255,0.15); border-radius: 3px;\n  margin-bottom: 8px; overflow: hidden;\n}\n.mc-export-fill {\n  height: 100%; width: 0%;\n  background: linear-gradient(90deg, var(--mc-accent, #007AFF), var(--mc-accent, #0056CC));\n  transition: width 0.3s ease; border-radius: 3px;\n}\n.mc-export-text {\n  color: rgba(255,255,255,0.7); font-size: 11px;\n  font-family: Menlo, Monaco, monospace;\n}\n";

package/dist/Controller.d.ts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-BIGDIla0.js';
+import { f as Movie } from './Movie-DilBC348.js';
 import 'pixi.js';
 import 'gsap';
-import './types-C8XEUoqe.js';
+import './types-SS51lP6O.js';
 
 /** The bar's default stylesheet. Its colours and sizes are CSS custom properties (`--mc-accent`, `--mc-fg`, `--mc-track`, `--mc-bar-bg`, `--mc-track-height`, `--mc-font`): set them in your page CSS, or with the `theme` option. */
 declare const CONTROLLER_CSS = "\n.movie-controller-wrap { position: relative; display: inline-block; line-height: 0; }\n.movie-controller {\n  position: absolute;\n  pointer-events: none;\n  font-family: var(--mc-font, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif);\n  display: flex;\n  flex-direction: column;\n  justify-content: flex-end;\n  opacity: 1;\n  transition: opacity 200ms ease;\n}\n.movie-controller[data-state=\"hidden\"] { opacity: 0; }\n.movie-controller > * { pointer-events: auto; }\n\n.mc-progress {\n  position: relative;\n  width: 100%;\n  height: 16px;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  outline: none;\n}\n.mc-progress:focus-visible {\n  outline: 2px solid var(--mc-accent, #007AFF);\n  outline-offset: 2px;\n}\n.mc-progress::before {\n  content: \"\"; position: absolute; left: 12px; right: 12px;\n  height: var(--mc-track-height, 3px); background: var(--mc-track, rgba(255,255,255,0.25));\n  transition: height 120ms ease;\n}\n.mc-progress:hover::before, .mc-progress.mc-scrubbing::before { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-stops { position: absolute; left: 12px; right: 12px; top: 0; bottom: 0; pointer-events: none; }\n.mc-stop-tick { position: absolute; top: 50%; width: 7px; height: 7px; transform: translate(-50%, -50%); border-radius: 50%; background: var(--mc-fg, #fff); box-shadow: 0 0 0 1.5px rgba(0,0,0,0.5); }\n.mc-stop-page { width: 11px; height: 11px; box-shadow: 0 0 0 2.5px var(--mc-accent, #007AFF), 0 0 0 4px rgba(0,0,0,0.35); }\n.mc-progress-fill {\n  position: absolute; left: 12px; top: 50%;\n  height: var(--mc-track-height, 3px);\n  width: calc((100% - 24px) * var(--mc-fill, 0));\n  background: var(--mc-accent, #007AFF);\n  transform: translateY(-50%);\n  transition: height 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-fill,\n.mc-progress.mc-scrubbing .mc-progress-fill { height: calc(var(--mc-track-height, 3px) + 2px); }\n.mc-progress-thumb {\n  position: absolute; top: 50%;\n  left: calc(12px + (100% - 24px) * var(--mc-fill, 0));\n  width: 12px; height: 12px; border-radius: 50%;\n  background: var(--mc-accent, #007AFF);\n  transform: translate(-50%, -50%) scale(0);\n  transition: transform 120ms ease;\n  pointer-events: none;\n}\n.mc-progress:hover .mc-progress-thumb,\n.mc-progress.mc-scrubbing .mc-progress-thumb { transform: translate(-50%, -50%) scale(1); }\n\n.mc-bar {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 12px 8px 12px;\n  background: var(--mc-bar-bg, linear-gradient(to top, rgba(0,0,0,0.75) 0%, rgba(0,0,0,0) 100%));\n  color: var(--mc-fg, #fff);\n  line-height: 1;\n}\n.mc-btn {\n  background: none; border: 0; padding: 0; margin: 0;\n  width: 28px; height: 28px;\n  display: inline-flex; align-items: center; justify-content: center;\n  color: var(--mc-fg, #fff); opacity: 0.85; cursor: pointer;\n  transition: opacity 120ms ease;\n}\n.mc-btn:hover { opacity: 1; }\n.mc-btn:disabled { opacity: 0.4; cursor: not-allowed; }\n.mc-time {\n  font-size: 12px; font-family: Menlo, Monaco, monospace;\n  color: var(--mc-fg, #fff); opacity: 0.85;\n  min-width: 90px;\n}\n.mc-spacer { flex: 1; }\n\n.mc-volume { display: flex; align-items: center; }\n.mc-vol-slider {\n  position: relative;\n  width: 0;\n  height: 28px;\n  display: flex;\n  align-items: center;\n  cursor: pointer;\n  margin-left: 0;\n  outline: none;\n  transition: width 200ms ease, margin-left 200ms ease;\n  overflow: hidden;\n}\n.mc-volume:hover .mc-vol-slider,\n.mc-volume:focus-within .mc-vol-slider,\n.mc-vol-slider.mc-scrubbing {\n  width: 70px;\n  margin-left: 6px;\n}\n.mc-vol-slider:focus-visible { outline: 2px solid var(--mc-accent, #007AFF); outline-offset: 2px; }\n.mc-vol-slider::before {\n  content: \"\"; position: absolute; left: 4px; right: 4px;\n  height: 3px; background: var(--mc-track, rgba(255,255,255,0.25)); border-radius: 2px;\n}\n.mc-vol-fill {\n  position: absolute; left: 4px; top: 50%;\n  height: 3px;\n  width: calc((100% - 8px) * var(--mc-volume, 1));\n  background: var(--mc-fg, #fff);\n  transform: translateY(-50%);\n  border-radius: 2px;\n  pointer-events: none;\n}\n.mc-vol-thumb {\n  position: absolute; top: 50%;\n  left: calc(4px + (100% - 8px) * var(--mc-volume, 1));\n  width: 10px; height: 10px; border-radius: 50%;\n  background: var(--mc-fg, #fff);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n\n[data-mc-wrap]:fullscreen {\n  width: 100vw; height: 100vh;\n  display: flex; align-items: center; justify-content: center;\n  background: #000;\n}\n[data-mc-wrap]:fullscreen > canvas {\n  width: 100% !important;\n  height: 100% !important;\n  max-width: none !important;\n  max-height: none !important;\n  object-fit: contain;\n  border-radius: 0;\n}\n\n.mc-settings-popover {\n  position: absolute;\n  bottom: calc(100% + 8px);\n  right: 12px;\n  background: rgba(20, 20, 20, 0.96);\n  border-radius: 8px;\n  padding: 10px 12px;\n  min-width: 180px;\n  color: #fff;\n  font-size: 12px;\n  box-shadow: 0 4px 16px rgba(0,0,0,0.4);\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n.mc-settings-popover[data-open=\"false\"] { display: none; }\n.mc-settings-row {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 12px;\n}\n.mc-settings-row > span { color: rgba(255,255,255,0.85); }\n.mc-settings-row > select {\n  font: inherit;\n  background: rgba(255,255,255,0.1);\n  color: #fff;\n  border: 1px solid rgba(255,255,255,0.18);\n  border-radius: 4px;\n  padding: 2px 6px;\n  cursor: pointer;\n}\n.mc-export-confirm {\n  margin-top: 4px;\n  width: 100%;\n  background: var(--mc-accent, #007AFF);\n  color: #fff;\n  border: 0;\n  border-radius: 4px;\n  padding: 6px 10px;\n  font: inherit;\n  font-weight: 600;\n  cursor: pointer;\n  transition: background 120ms ease;\n}\n.mc-export-confirm:hover { background: #0066d6; }\n.mc-export-confirm:disabled { background: rgba(255,255,255,0.18); cursor: not-allowed; }\n\n.mc-export-overlay {\n  position: absolute; inset: 0;\n  background: rgba(0,0,0,0.7);\n  display: flex; justify-content: center; align-items: center;\n  z-index: 2;\n}\n.mc-export-panel {\n  background: rgba(20,20,20,0.96); color: #fff;\n  border-radius: 8px; padding: 16px 20px;\n  text-align: center; min-width: 200px; max-width: 80%;\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n}\n.mc-export-title { font-size: 13px; margin-bottom: 10px; opacity: 0.9; }\n.mc-export-track {\n  width: 100%; height: 6px;\n  background: rgba(255,255,255,0.15); border-radius: 3px;\n  margin-bottom: 8px; overflow: hidden;\n}\n.mc-export-fill {\n  height: 100%; width: 0%;\n  background: linear-gradient(90deg, var(--mc-accent, #007AFF), var(--mc-accent, #0056CC));\n  transition: width 0.3s ease; border-radius: 3px;\n}\n.mc-export-text {\n  color: rgba(255,255,255,0.7); font-size: 11px;\n  font-family: Menlo, Monaco, monospace;\n}\n";

package/dist/{Movie-BIGDIla0.d.ts → Movie-DilBC348.d.ts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-C8XEUoqe.js';
+import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-SS51lP6O.js';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
@@ -457,7 +457,13 @@ declare class Movie {
      */
     private _renderNow;
     private _requireReady;
-    /** Projects every `threeD` layer for the current frame (see src/space). */
+    /** True when the layers were already synced to the playhead for the frame about to be drawn (so `_renderNow` need not do it again). */
+    private _synced;
+    /**
+     * Projects every `threeD` layer for the current frame (see src/space). A threeD card is drawn into its own texture HERE, before the stage is
+     * drawn, so the shapes inside it must be brought up to the playhead first: syncing only in `_renderNow` left every card showing the state of
+     * the frame before (after a jump seek, a card whose children were animated showed a stale picture).
+     */
     private _updateSpace;
     /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
     private _blurFor;

package/dist/{Movie-CJMfAizW.d.cts → Movie-oA0SUAyb.d.cts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-C8XEUoqe.cjs';
+import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-SS51lP6O.cjs';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
@@ -457,7 +457,13 @@ declare class Movie {
      */
     private _renderNow;
     private _requireReady;
-    /** Projects every `threeD` layer for the current frame (see src/space). */
+    /** True when the layers were already synced to the playhead for the frame about to be drawn (so `_renderNow` need not do it again). */
+    private _synced;
+    /**
+     * Projects every `threeD` layer for the current frame (see src/space). A threeD card is drawn into its own texture HERE, before the stage is
+     * drawn, so the shapes inside it must be brought up to the playhead first: syncing only in `_renderNow` left every card showing the state of
+     * the frame before (after a jump seek, a card whose children were animated showed a stale picture).
+     */
     private _updateSpace;
     /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
     private _blurFor;

package/dist/Presenter.d.cts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-CJMfAizW.cjs';
+import { f as Movie } from './Movie-oA0SUAyb.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-C8XEUoqe.cjs';
+import './types-SS51lP6O.cjs';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/Presenter.d.ts

@@ -1,7 +1,7 @@
-import { f as Movie } from './Movie-BIGDIla0.js';
+import { f as Movie } from './Movie-DilBC348.js';
 import 'pixi.js';
 import 'gsap';
-import './types-C8XEUoqe.js';
+import './types-SS51lP6O.js';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/{chunk-V54NBCWG.cjs → chunk-2ROVCPSL.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSPPNTV7E_cjs = require('./chunk-SPPNTV7E.cjs');
+var chunkFJA5VUOF_cjs = require('./chunk-FJA5VUOF.cjs');
 var chunkUQBGW5DO_cjs = require('./chunk-UQBGW5DO.cjs');
 var pixi_js = require('pixi.js');
 var gsap = require('gsap');
@@ -65,8 +65,8 @@ function readLayerTransform(target) {
     x: c.x,
     y: c.y,
     z: c.z ?? 0,
-    rotationX: (c.rotationX ?? 0) * chunkSPPNTV7E_cjs.DEG,
-    rotationY: (c.rotationY ?? 0) * chunkSPPNTV7E_cjs.DEG,
+    rotationX: (c.rotationX ?? 0) * chunkFJA5VUOF_cjs.DEG,
+    rotationY: (c.rotationY ?? 0) * chunkFJA5VUOF_cjs.DEG,
     rotationZ: c.rotation,
     scaleX: c.scale.x,
     scaleY: c.scale.y,
@@ -111,18 +111,19 @@ var Layer3D = class {
     if (!(needW >= 1 && needH >= 1) || !Number.isFinite(bounds.x) || !Number.isFinite(bounds.y)) return this.hide();
     const size = this.sizeFor(needW, needH);
     const frame = { x: bounds.x - pad, y: bounds.y - pad, width: size.w, height: size.h };
-    const projected = chunkSPPNTV7E_cjs.projectLayer(readLayerTransform(target), frame, basis);
+    const projected = chunkFJA5VUOF_cjs.projectLayer(readLayerTransform(target), frame, basis);
     this.depth = projected.depth;
     if (!projected.visible) {
       if (!this.warnedBehind) {
         this.warnedBehind = true;
-        if (projected.depth > chunkSPPNTV7E_cjs.NEAR) {
+        if (this.seq.spec.hideBehindCamera) return this.hide();
+        if (projected.depth > chunkFJA5VUOF_cjs.NEAR) {
           console.warn(
-            `pixi-effects: ${chunkSPPNTV7E_cjs.describeLayer(this.seq.spec)}: part of it (a corner) reaches the camera plane (z = ${(target.z ?? 0).toFixed(0)}, rotationX ${(target.rotationX ?? 0).toFixed(0)}\xB0, rotationY ${(target.rotationY ?? 0).toFixed(0)}\xB0), and a layer is hidden whole when any corner is at or behind it. Tilt it less (rotationX / rotationY), make it smaller, or keep the camera further away from it (the default camera sits at z = (height/2)/tan(fov/2), about 989 for 720p at fov 40).`
+            `pixi-effects: ${chunkFJA5VUOF_cjs.describeLayer(this.seq.spec)}: part of it (a corner) reaches the camera plane (z = ${(target.z ?? 0).toFixed(0)}, rotationX ${(target.rotationX ?? 0).toFixed(0)}\xB0, rotationY ${(target.rotationY ?? 0).toFixed(0)}\xB0), and a layer is hidden whole when any corner is at or behind it. Tilt it less (rotationX / rotationY), make it smaller, or keep the camera further away from it (the default camera sits at z = (height/2)/tan(fov/2), about 989 for 720p at fov 40).`
           );
         } else {
           console.warn(
-            `pixi-effects: ${chunkSPPNTV7E_cjs.describeLayer(this.seq.spec)} is at or behind the camera plane (z = ${(target.z ?? 0).toFixed(0)}) and is hidden. If that is unintended, lower its z or move the camera back (the default camera sits at z = (height/2)/tan(fov/2), about 989 for 720p at fov 40).`
+            `pixi-effects: ${chunkFJA5VUOF_cjs.describeLayer(this.seq.spec)} is at or behind the camera plane (z = ${(target.z ?? 0).toFixed(0)}) and is hidden. If that is unintended, lower its z or move the camera back (the default camera sits at z = (height/2)/tan(fov/2), about 989 for 720p at fov 40).`
           );
         }
       }
@@ -206,12 +207,12 @@ var CAMERA_ALIASES = {
   pointOfInterest: 'did you mean "lookAtX / lookAtY / lookAtZ"?',
   lookAt: 'did you mean "lookAtX / lookAtY / lookAtZ"?'
 };
-var CAMERA_PROPS = ["x", "y", "z", "fov", "lookAtX", "lookAtY", "lookAtZ"];
+var CAMERA_PROPS = ["x", "y", "z", "fov", "lookAtX", "lookAtY", "lookAtZ", "offsetX", "offsetY", "offsetZ", "lookOffsetX", "lookOffsetY", "lookOffsetZ"];
 var NEEDS_THREE_D = ["z", "rotationX", "rotationY"];
 var SKEW_KEYS = ["skew", "skewX", "skewY"];
 function lintSequence(spec, warn = defaultWarn) {
-  const who = chunkSPPNTV7E_cjs.describeLayer(spec);
-  const keys = chunkSPPNTV7E_cjs.collectPropKeys(spec);
+  const who = chunkFJA5VUOF_cjs.describeLayer(spec);
+  const keys = chunkFJA5VUOF_cjs.collectPropKeys(spec);
   const explained = /* @__PURE__ */ new Set();
   for (const k of keys) {
     const hint = LAYER_ALIASES[k] ?? (spec.type === "camera" ? CAMERA_ALIASES[k] : void 0);
@@ -257,7 +258,7 @@ function applyBlendMode(spec, display) {
   const mode = spec.blendMode;
   if (mode === void 0) return;
   if (!MODES.includes(mode)) {
-    console.warn(`pixi-effects: ${chunkSPPNTV7E_cjs.describeLayer(spec)}: blendMode "${mode}" is not supported (use ${MODES.join(", ")})`);
+    console.warn(`pixi-effects: ${chunkFJA5VUOF_cjs.describeLayer(spec)}: blendMode "${mode}" is not supported (use ${MODES.join(", ")})`);
     return;
   }
   const filters = display.filters;
@@ -269,7 +270,7 @@ function applyBlendMode(spec, display) {
 }
 
 // src/sequences/Composition.ts
-var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
+var CompositionSequence = class extends chunkFJA5VUOF_cjs.Sequence {
   _innerContainer = null;
   _compositionShape = null;
   _children = [];
@@ -303,18 +304,18 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
     const lateKeyframes = [];
     for (const s of this.spec.sequences ?? []) {
       lintSequence(s);
-      chunkSPPNTV7E_cjs.lintTiming(s, this.duration, (message, kind) => kind === "late-keyframe" ? lateKeyframes.push(message) : console.warn(message));
-      chunkSPPNTV7E_cjs.lintText(s);
+      chunkFJA5VUOF_cjs.lintTiming(s, this.duration, (message, kind) => kind === "late-keyframe" ? lateKeyframes.push(message) : console.warn(message));
+      chunkFJA5VUOF_cjs.lintText(s);
     }
-    for (const message of chunkSPPNTV7E_cjs.summarizeWarnings(lateKeyframes)) console.warn(message);
-    this._children = await chunkSPPNTV7E_cjs.buildSequenceTree(
+    for (const message of chunkFJA5VUOF_cjs.summarizeWarnings(lateKeyframes)) console.warn(message);
+    this._children = await chunkFJA5VUOF_cjs.buildSequenceTree(
       this.spec.sequences ?? [],
       this._compositionShape,
       this.root
     );
     this._resolveParents();
     for (const child of this._children) {
-      if (child instanceof chunkSPPNTV7E_cjs.CameraSequence) {
+      if (child instanceof chunkFJA5VUOF_cjs.CameraSequence) {
         this._cameras.push(child);
         continue;
       }
@@ -329,7 +330,7 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
         this._visual.push({ seq: child, layer });
         applyBlendMode(child.spec, layer.display);
         if (maskSpec) {
-          console.warn(`pixi-effects: ${chunkSPPNTV7E_cjs.describeLayer(child.spec)}: mask is not supported on threeD layers yet; ignored`);
+          console.warn(`pixi-effects: ${chunkFJA5VUOF_cjs.describeLayer(child.spec)}: mask is not supported on threeD layers yet; ignored`);
         }
         continue;
       }
@@ -339,7 +340,7 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
       applyBlendMode(child.spec, child.target);
       if (maskSpec) {
         const lifetime = maskSpec.at === void 0 ? { at: child.at, duration: maskSpec.duration ?? child.duration } : {};
-        const built = await chunkSPPNTV7E_cjs.buildSequenceTree([{ ...maskSpec, ...lifetime }], this._compositionShape, this.root);
+        const built = await chunkFJA5VUOF_cjs.buildSequenceTree([{ ...maskSpec, ...lifetime }], this._compositionShape, this.root);
         const maskSeq = built[0];
         if (maskSeq?.target) {
           into.addChild(maskSeq.target);
@@ -389,7 +390,7 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
       for (let p = this._parentOf.get(seq); p; p = this._parentOf.get(p)) out.push(p);
       return out;
     };
-    return [...this._visual.map((v) => v.seq), ...this._nested].filter((seq) => !(seq instanceof chunkSPPNTV7E_cjs.NullSequence)).map((seq) => {
+    return [...this._visual.map((v) => v.seq), ...this._nested].filter((seq) => !(seq instanceof chunkFJA5VUOF_cjs.NullSequence)).map((seq) => {
       const layer = this._visual.find((v) => v.seq === seq)?.layer ?? null;
       return {
         seq,
@@ -401,14 +402,14 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
   }
   /** Match every `parent: 'name'` to a null layer; anything that cannot work is said out loud and drawn unparented. */
   _resolveParents() {
-    const nulls = this._children.filter((c) => c instanceof chunkSPPNTV7E_cjs.NullSequence);
+    const nulls = this._children.filter((c) => c instanceof chunkFJA5VUOF_cjs.NullSequence);
     const nullNames = nulls.map((n) => n.spec.name).filter((n) => !!n);
     const warned = /* @__PURE__ */ new Set();
     for (const child of this._children) {
       const want = child.spec.parent;
       if (want === void 0) continue;
-      const who = chunkSPPNTV7E_cjs.describeLayer(child.spec);
-      if (child instanceof chunkSPPNTV7E_cjs.CameraSequence) {
+      const who = chunkFJA5VUOF_cjs.describeLayer(child.spec);
+      if (child instanceof chunkFJA5VUOF_cjs.CameraSequence) {
         console.warn(`pixi-effects: ${who}: a camera cannot have a parent; ignored`);
         continue;
       }
@@ -422,7 +423,7 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
         console.warn(`pixi-effects: ${who}: parent "${want}": no layer with that name${hint ? `; did you mean "${hint}"?` : ""} (the layer is drawn without a parent)`);
         continue;
       }
-      const holder = same.find((c) => c instanceof chunkSPPNTV7E_cjs.NullSequence);
+      const holder = same.find((c) => c instanceof chunkFJA5VUOF_cjs.NullSequence);
       if (!holder) {
         console.warn(`pixi-effects: ${who}: parent "${want}" is a ${same[0].spec.type} layer; only { type: 'null' } layers can be parents (the layer is drawn without a parent)`);
         continue;
@@ -465,7 +466,7 @@ var CompositionSequence = class extends chunkSPPNTV7E_cjs.Sequence {
       t,
       compEnd
     );
-    const basis = chunkSPPNTV7E_cjs.cameraBasis(active ? active.cam.state() : chunkSPPNTV7E_cjs.homeCamera(width, height), width, height);
+    const basis = chunkFJA5VUOF_cjs.cameraBasis(active ? active.cam.state() : chunkFJA5VUOF_cjs.homeCamera(width, height), width, height);
     for (const layer of this._layers3d) layer.update(host, basis);
     const order = assignDepthOrder(
       this._visual.map((v, i) => ({ stackIndex: i, threeD: v.layer !== null, depth: v.layer?.depth ?? 0 }))
@@ -494,5 +495,5 @@ function frameOf(child) {
 }
 
 exports.CompositionSequence = CompositionSequence;
-//# sourceMappingURL=chunk-V54NBCWG.cjs.map
-//# sourceMappingURL=chunk-V54NBCWG.cjs.map
+//# sourceMappingURL=chunk-2ROVCPSL.cjs.map
+//# sourceMappingURL=chunk-2ROVCPSL.cjs.map