pixi-effects 0.22.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.26.0
+
+**Added**
+
+- **Agent skill.** `npx skills add yjmtmtk/pixi-effects` registers pixi-effects as a skill in Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and about 70 more agents; its description starts from the task (a video, motion graphics, an animated title, a lower third, a promo, a chart), so an agent can reach it without being told the library's name. Claude Code also installs it as a plugin (`/plugin install pixi-effects --marketplace yjmtmtk/pixi-effects`).
+- **`pixi-effects` bin** (named like the package): `npx pixi-effects check my-video.html`, `npx pixi-effects render … -o x.mp4`, `npx pixi-effects view …` run the same three tools with nothing installed, and a mistyped command says which one you meant. The three `pixi-effects-check|render|view` bins stay; `npx pixi-effects-check` on its own never worked (npm looks for a package of that name), the docs now say `npx pixi-effects check`. **Fixed:** the three tools printed nothing and exited 0 when npm started them through its symlink (`./node_modules/.bin/pixi-effects-check`); they now run.
+- **`movie.audioBlocked`**: true while the browser keeps the movie's sound silent until a tap (iOS Safari); a player can then ask for the tap. The landing page does: the reel and the gallery pieces start with one tap inside the frame when the sound is locked.
+
+**Changed**
+
+- The skill moved from `ai/` to `skills/pixi-effects/` (`SKILL.md`, `template.html`, `reference/`, `scripts/save-image.py`); `ai/` keeps the chat guide and the tools. Old links to `ai/SKILL.md`, `ai/reference/*` and `ai/template.html` no longer exist. The skill's commands are `npx pixi-effects-check|render|view`.
+
+## 0.25.0
+
+One release holds three milestones that were built one after the other: **composition** (named mattes, the luma wipe), **light** (lights, shadows, fog) and **freedom of drawing** (the shader layer, the `warp` filter). Wipe, iris and dissolve transitions now also work on WebGL (they drew nothing there before).
+
+**Added**
+
+- **Light, shadows and fog for 2.5D.** A `{ type: 'light', kind: 'ambient' | 'point' | 'spot' | 'parallel' }` layer (a carrier like the camera: its numbers go in `initial` / `keyframes`) lights every `threeD` layer of its composition, per pixel, in the layer's own mesh shader (no extra pass; GLSL and WGSL): Lambert shading with `falloff` (`none`, `smooth`, `inverseSquare`), a spot's cone and feather, a sun. `lit: false` opts a layer out. Shadows need `castsShadows` on the light AND on the layer: hard by default, `shadowDiffusion` for a penumbra that widens with distance, up to 4 casters per receiver, the strongest wins. The camera takes `fogNear` / `fogFar` / `fogColor` / `fogAmount` for depth fog. A composition with no light and no fog builds nothing and draws the same picture at the same cost: frames of all ten `threeD` pages of the repository are pixel-identical before and after. Checked against an independent JS reference (every pixel within 2/255) on WebGPU and WebGL for every kind, the falloffs, a card turned on two axes, a card seen from its back, fog, shadows (hard, soft, two and four casters, a turned caster), and together with depth of field, blend modes, the layer's own filters, cards, nested and time-remapped compositions and colour keyframes. Cost at 1080p on one machine: lights add 1 to 2.6 ms; soft shadows are the expensive part (3 soft lights over 20 layers: about 20 ms). Warnings, said once at build with a fix: no ambient light, a half-set `castsShadows`, too many lights or casters (which are dropped), 3 or more lights with soft shadows, misplaced keys and aliases (`target` → `lookAtX/Y/Z`, `angle` → `coneAngle`, `castShadows` → `castsShadows`, `intensity: 80`), `fogFar` not beyond `fogNear`. `movie.inspect` gives each lit layer a `light` number and `check --at` prints them most lit first.
+- **Shader layer.** `{ type: 'shader', fragment, uniforms, width, height, resolution, transparent }` draws a Shadertoy `mainImage` (GLSL ES 3.00) as a layer: `iResolution`, `iTime` (the layer's own seconds; a time-remapped composition's clock inside it) and `iFrame` are declared for you, and so is every `uniforms` entry (a number is a `float`, 2 to 4 numbers a vector, a hex colour a `vec3`); keyframes move them as `'uniforms.speed'` and `'uniforms.tint.0'`. It is a layer like any other: masks, named mattes (it can be a matte too), filters, blend modes, `threeD` and lights work on it. Every shader layer draws with ONE shared WebGL2 context (a context per layer would hit the browser's limit of about 16) and copies the result into a canvas of its own; a lost context is made again on the next frame. A compile error is reported in the author's own line numbers (`line 2: 'x' : undeclared identifier`) and the layer is a magenta checkerboard, never a silent blank. Static warnings with a fix: no `mainImage`, `gl_FragColor`, `texture2D`, `varying`, `#version`, a declared built-in, `iMouse` / `iChannel` / `iDate` (not provided), a `while` loop or a `for` with a bound that is not a constant, a bad `uniforms` value or name, `resolution`, `transparent`. Checked on WebGPU and WebGL: pixels against the formula, every seek order identical, error lines, transparency (premultiplied), layers of different sizes on one context, a rebuilt movie, a lost context, masks, mattes, filters, blend, `threeD`, lights, export. Cost in a prototype at 1080p on one machine: 20 small heavy shaders +11 to +17 ms a frame, one full-size shader about +10 ms. No `iChannel` textures, mouse or feedback in this version, and a shader cannot read what is behind it (it is a layer, not a filter).
+- **`warp` filter.** `{ type: 'warp', kind: 'wave' | 'haze', strength, scale, speed, angle, seed }` bends a layer's picture: a travelling wave (water, a flag) or drifting noise (heat haze). Its own GLSL and WGSL, a pure function of the frame's time through the same `TimeFilter` hook as `grain` (the sub-frames of a motion-blurred frame share one time), padded by `strength` so a shifted edge is not cut, options animated by the filter's name. Checked stripe by stripe against a JS reference on both backends (a worked-by-hand wave and constants from an independent implementation of the integer hash for `haze`). Aliases `distort`, `displace`, `ripple`, `wavy`, `heatHaze` point to it.
+- **Docs and examples:** `docs/dsl.md` (`shader`, the filter table and a distortion paragraph), the cheatsheet, SKILL, recipes `shader-plasma` and `warp-water`, pitfalls 89–92, the guide "Shaders and warps", Playground example 20, and a gallery piece (50 now): `shader-garden`, four formulas and no pictures (a flowing field under a title bent like water, contour lines of a noise terrain seen only through letters, ripples through a disc), made by a Claude Sonnet 5.5 subagent from the docs alone (its notes are in `examples/gallery/_notes/`; the two gaps it found are fixed: a mask cuts what the shader drew and does not move the pattern, and a small shader layer sits by its top-left corner).
+- **Docs and examples:** `docs/dsl.md` (Lights, Shadows, Fog), the cheatsheet, SKILL, recipes `spot-room` and `fog-depth`, pitfalls 85–88, the 2.5D guide, Playground example 19, and a gallery piece (49 now): `spotlight-room`, a dark room where one tight lamp picks out three pictures and they throw shadows on the wall, with slow camera and depth fog (made by a Claude Sonnet 5.5 subagent from the docs alone; its stumble notes are in `examples/gallery/_notes/`, and the gaps it found are fixed: the size of a spot's pool and the card that hides it, a hard shadow reading as a slab, how to build a floor, the `check` light line cut at 8 layers).
+
+- **Named mattes.** A layer can be named and used as the `mask` of any number of layers in the same composition: `mask: 'band'` (the matte reads its opacity), `mask: { layer: 'band', channel: 'luma', invert: true }` (its brightness, Rec. 709; the opposite) and a list `mask: ['panel', { layer: 'hole', invert: true }]` (an intersection; subtracting a matte is inverting it). The matte layer itself is not drawn: it is drawn once per frame into a texture (so three layers sharing a moving matte cost one pass for the matte) and a `MatteFilter` cuts each layer that names it. `blendMode` works with every matte. Warnings, said once at build with a fix: a name nobody has (did-you-mean), the same name twice, a matte that is not alive for as long as its users (they would vanish), a `threeD` matte or a masked `threeD` layer, a matte with a mask of its own, `maskInverted` written with a named matte, a `channel` that is not `alpha` / `luma` (`luminance` → `luma`), a masked layer with a `parent`, and more than 8 mattes in one composition (each is a texture the size of the composition: about 8 MiB at 1080p). `inspect` skips matte layers.
+- **Luma wipe.** The transition `{ kind: 'luma', from, to, at, duration, map, softness, flip }` follows a brightness map: dark parts change first. `map` is `'linear'`, `'diagonal'`, `'radial'` (computed on the GPU from the position on screen, a circle whatever the aspect ratio: no image, no canvas) or the name of a grayscale image asset; `softness` is the soft band (0.1), `flip` reverses it. An unknown map name warns once with the closest built-in. A layer a transition wraps keeps its named matte.
+- **A gallery piece for mattes and the luma wipe** (48 now): `matte-reel`, one moving matte shared by gradient "photographs", hairlines and captions, an inverted hole, a headline that blends in through a luma ramp, a multiply band, and a luma wipe (with a venetian-blind map drawn on a canvas) to an end card (made by a Claude Sonnet 5.5 subagent from the docs alone; its stumble notes are in `examples/gallery/_notes/`, and the two gaps it found are fixed in the docs: outside the matte layer's shape the matte is 0 for `luma` too, and a whole composition can be the masked layer).
+- **Docs and examples:** `docs/dsl.md` (Named mattes and luma, `luma` transition, blend rule 10), the cheatsheet, SKILL, recipes `shared-matte` and `luma-wipe`, pitfalls 81–84, the transitions and images guides, and Playground example 18.
+
+**Changed**
+
+- **Inverted masks (`maskInverted`) and text, image and video masks now go through the matte filter** (the same one as a named matte); a plain shape mask that is not inverted stays the stencil (the cheapest, hard-edged). The `AlphaMask` code, the `erase` wrapper group of 0.22 and the warning "a text mask with a blend loses the blend" are gone: **`blendMode` now works with every kind of mask**. Measured before and after on the 16 gallery and example pages that use masks (frames at 0, 25, 50, 75 and 99 %): 14 are pixel-identical (largest difference 0 to 1 of 255), `ma` differs in 10 edge pixels (largest 11 of 255), and the `05-composition-mask` example now draws its `maskInverted` hole correctly inside a nested composition (it was cut off at the bottom, and missing in the last frames).
+
+**Fixed**
+
+- **Wipe, iris and dissolve transitions did nothing on WebGL**: their fragment shader declared the frame uniforms without `highp`, so it did not link ("Precisions of uniform 'uOutputFrame' differ between VERTEX and FRAGMENT shaders") and the transition drew nothing (WebGPU, the default, was fine). The transitions are now tested on both backends.
+
 ## 0.22.0
 
 **Added**

package/README.md

@@ -1,8 +1,8 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.22.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.26.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
 
-**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 47 portfolio pieces written as plain data by AI models · **[Examples →](https://yjmtmtk.github.io/pixi-effects/examples/)** · 15 numbered examples, a music lab + an in-browser playground.
+**[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 50 portfolio pieces written as plain data by AI models · **[Examples →](https://yjmtmtk.github.io/pixi-effects/examples/)** · 15 numbered examples, a music lab + an in-browser playground.
 
 ## Make a video by asking an AI
 
@@ -10,7 +10,7 @@ Give any AI (ChatGPT, Claude, Codex, Cursor, Claude Code …) one sentence:
 
 > 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.
+That is all it needs. **To register it as a skill** in your agent (Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode, …): `npx skills add yjmtmtk/pixi-effects` (update with `npx skills update`). In Claude Code you can also run `/plugin install pixi-effects --marketplace yjmtmtk/pixi-effects`. **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 [`skills/pixi-effects/SKILL.md`](./skills/pixi-effects/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/).
 
@@ -19,7 +19,7 @@ Declarative composition and video rendering for the web. After Effects-style tim
 - **Expression language** — sprinkle `'GW * 0.5'` or `'min(W, H) / 2'` anywhere a number goes. Resolved at runtime against a sequence-relative scope.
 - **Filters by name** — `filters: [{ type: 'glow', outerStrength: 3 }]`, no import: `blur noise alpha colorMatrix` (pixi.js) and the 38 filters of [`pixi-filters`](https://github.com/pixijs/filters) (`dropShadow crt rgbSplit oldFilm glitch pixelate twist …`), animated with `'filters.<name>.<option>'`. Any other PixiJS `Filter` goes in as `{ type: 'custom' }`.
 - **Draw-on strokes and changing text** — `trimEnd` 0 → 1 draws a line, border or SVG path on; a keyframe `set: { text }` swaps a string and `visibleChars` is a typewriter.
-- **Masks, transitions, chroma key** — inline masks; chroma key; seven scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`).
+- **Masks, transitions, chroma key** — inline masks; chroma key; eight scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`, `luma`).
 - **Presets** — `kenBurns` for stills, `withFade` for fade-in/out; `wiggle`, `stagger`, `animateText`, `followPath`, `particles` and `react` return keyframes or layers (seeded, so every render is the same).
 - **Presentations** — `stops` in the composition pause the movie where you say; `Presenter` (`pixi-effects/presenter`) moves on with arrow keys, a click or a swipe, with a page overview (G), a presenter view with notes and a timer (P), and `deck()` to lay out pages and steps. Export a deck as PDF (`movie.exportPDF()`, `pixi-effects-render talk.html -o talk.pdf`). See the [Presenting guide](https://yjmtmtk.github.io/pixi-effects/guide/presenting.html).
 - **Music written as text** — `{ type: 'audio', music: { bpm: 96, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }], drums: { kick: 'x...x...' } } }`: a tune with no audio file, played by a small built-in synthesiser (keys, pluck, pad, bass, lead, bell, music box, drums; chords by name, swing, fades, a ritardando). Deterministic, in the exported file at the same moment; an AI writes it as easily as a title.
@@ -51,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.22.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.22.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Controller.js"
   }
 }
 </script>
@@ -63,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.22.0/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.26.0/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.
 >
@@ -79,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.22.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/three.js"
   }
 }
 </script>
@@ -166,20 +166,20 @@ sequences: [
 ]
 ```
 
-`+z` is toward the viewer, rotations are degrees (CSS signs), and with `z = 0` and the default camera a `threeD` layer looks identical to a 2D one. See [DSL reference § 3D layers & camera](./docs/dsl.md#3d-layers--camera) and [`examples/11-depth.html`](./examples/11-depth.html).
+`+z` is toward the viewer, rotations are degrees (CSS signs), and with `z = 0` and the default camera a `threeD` layer looks identical to a 2D one. Add `{ type: 'light', kind: 'spot', … }` layers for shading and shadows, and `fogNear` / `fogFar` on the camera for depth fog (nothing changes in a composition with neither). See [DSL reference § 3D layers & camera](./docs/dsl.md#3d-layers--camera) and [`examples/11-depth.html`](./examples/11-depth.html).
 
 ## For AI agents
 
 This library is designed to be written by AI: a video is plain data, and every mistake we found while having AI sessions build test animations is either warned about at runtime or written down.
 
 - [`llms.txt`](./llms.txt) / [`llms-full.txt`](./llms-full.txt) — index and full text for LLM tooling (generated from the files below).
-- [`ai/SKILL.md`](./ai/SKILL.md) — a [skill](https://docs.claude.com/en/docs/claude-code/skills) (workflow, rules, verification loop). Copy the `ai/` folder to `~/.claude/skills/pixi-effects/` (or your project's `.claude/skills/`) to have Claude load it automatically when you ask for a video.
-- [`ai/reference/cheatsheet.md`](./ai/reference/cheatsheet.md), [`recipes.md`](./ai/reference/recipes.md) (tested), [`pitfalls.md`](./ai/reference/pitfalls.md), and a starter [`ai/template.html`](./ai/template.html).
+- [`skills/pixi-effects/SKILL.md`](./skills/pixi-effects/SKILL.md) — a [skill](https://docs.claude.com/en/docs/claude-code/skills) (workflow, rules, verification loop). Copy the `ai/` folder to `~/.claude/skills/pixi-effects/` (or your project's `.claude/skills/`) to have Claude load it automatically when you ask for a video.
+- [`skills/pixi-effects/reference/cheatsheet.md`](./skills/pixi-effects/reference/cheatsheet.md), [`recipes.md`](./skills/pixi-effects/reference/recipes.md) (tested), [`pitfalls.md`](./skills/pixi-effects/reference/pitfalls.md), and a starter [`skills/pixi-effects/template.html`](./skills/pixi-effects/template.html).
 
-- **Look at a page with its timeline, and scrub one with the other:** `npx pixi-effects-view my-video.html` (or `node ai/tools/view.mjs …`) opens your browser on a viewer: the page on top, the timeline of every layer under it with a playhead that follows the movie. Click or drag the timeline to seek, click a layer's name to jump to where it starts, Space plays, ← / → step a frame, + / − (or Ctrl/⌘ + wheel) zoom, the names stay in place. For the human who wants to see what the AI made.
-- **Render a page to a video file, headless:** `npx pixi-effects-render my-video.html -o my-video.mp4` (or `node ai/tools/render.mjs …`; Node ≥ 22 and Chrome installed, no dependencies). The container follows the extension (`mp4 webm mov mkv`); `--quality very-low…very-high`, `--query lang=ja` (added to the page URL), `--fail-on-warn` (exit 1 when the page logged a warning), `--quiet`. It waits for `window.__ready`, runs `movie.render()` and streams the file to disk; exit 0 = written, 1 = the page or the render failed (no file). For scripts, CI and batches; `pixi-effects-check` below is the review.
-- **A talk as a PDF:** `npx pixi-effects-render my-talk.html -o my-talk.pdf` (one page per page of a `deck()` / `stops` movie; `--all-stops` makes a page of every step). The review tool writes `stops.png` for such a page, one picture per stop.
-- **One-command review for the AI that wrote the page:** `npx pixi-effects-check my-video.html` (or `node ai/tools/check.mjs my-video.html`; Node ≥ 22 and Chrome installed, no dependencies). It opens the page in its own headless Chrome and reports warnings, layout (`movie.inspect` over the whole timeline), the soundtrack (`movie.inspectAudio`) and a real export decoded again, and writes a contact sheet PNG and a `timeline.html` (every layer as a bar on a time axis) to look at. Exit code 0 / 1.
+- **Look at a page with its timeline, and scrub one with the other:** `npx pixi-effects view my-video.html` (or `node ai/tools/view.mjs …`) opens your browser on a viewer: the page on top, the timeline of every layer under it with a playhead that follows the movie. Click or drag the timeline to seek, click a layer's name to jump to where it starts, Space plays, ← / → step a frame, + / − (or Ctrl/⌘ + wheel) zoom, the names stay in place. For the human who wants to see what the AI made.
+- **Render a page to a video file, headless:** `npx pixi-effects render my-video.html -o my-video.mp4` (or `node ai/tools/render.mjs …`; Node ≥ 22 and Chrome installed, no dependencies). The container follows the extension (`mp4 webm mov mkv`); `--quality very-low…very-high`, `--query lang=ja` (added to the page URL), `--fail-on-warn` (exit 1 when the page logged a warning), `--quiet`. It waits for `window.__ready`, runs `movie.render()` and streams the file to disk; exit 0 = written, 1 = the page or the render failed (no file). For scripts, CI and batches; `pixi-effects-check` below is the review.
+- **A talk as a PDF:** `npx pixi-effects render my-talk.html -o my-talk.pdf` (one page per page of a `deck()` / `stops` movie; `--all-stops` makes a page of every step). The review tool writes `stops.png` for such a page, one picture per stop.
+- **One-command review for the AI that wrote the page:** `npx pixi-effects check my-video.html` (or `node ai/tools/check.mjs my-video.html`; Node ≥ 22 and Chrome installed, no dependencies). It opens the page in its own headless Chrome and reports warnings, layout (`movie.inspect` over the whole timeline), the soundtrack (`movie.inspectAudio`) and a real export decoded again, and writes a contact sheet PNG and a `timeline.html` (every layer as a bar on a time axis) to look at. Exit code 0 / 1.
 
 They ship in the npm package (`node_modules/pixi-effects/ai/`).
 
@@ -217,6 +217,8 @@ Rendering uses the [WebCodecs API](https://developer.mozilla.org/docs/Web/API/We
 | WebM (vp9)| ✅          | ✅        | ✅            | ✅            |
 | MOV (avc) | ✅          | ✅        | ✅            | ✅            |
 
+**Renderer:** the movie tries WebGPU first and falls back to WebGL (with a console warning) when WebGPU is missing or its device cannot start, so a page needs no setting. Every filter the library ships has a GLSL and a WGSL version. A frame is the same picture however it was reached **on one renderer**; the two renderers can differ in a few edge pixels, so do not compare an export from a WebGPU machine and one from a WebGL machine byte for byte. Tested on Chrome with an Apple GPU only (WebGPU on Metal, WebGL through ANGLE); other GPUs, Windows and Linux are untested.
+
 Some codecs (notably `aac` audio in older Firefox) may need the [mediabunny polyfill encoders](https://mediabunny.dev/) (`@mediabunny/aac-encoder`, etc.).
 
 ## License

package/ai/CHAT.md

@@ -60,7 +60,7 @@ That is a complete, working video (the block between the two markers). Change th
 - **Scenes.** Stack layers with `at` / `duration` over an opaque background rect. Do not remove layers.
 - **Sound with no files:** `{ type: 'audio', sfx: 'swoosh', at: 2 }`. Presets: `click pop swoosh swipe hit riser chime beep coin glitch typewriter`; optional `pitch`, `brightness`. A `riser` is loudest at its **end**: start it `duration` seconds before the hit. This page cannot load music or images from your own files; use shapes, text, sfx and `music` (below).
 - **Repeat with code, never by copying:** `Array.from({ length: 12 }, (_, i) => ({ type: 'shape', shape: 'circle', radius: 20, at: i * 0.15, duration: DURATION - i * 0.15, initial: { x: 120 + i * 90, y: 360, fillColor: '#ffd166' }, keyframes: [{ at: 0, from: { scale: 0 }, to: { scale: 1 }, duration: 0.4, ease: 'back.out(2)' }] }))` returns twelve layers: spread them into `sequences` with `...`.
-- **Helpers already imported** in the template: `kenBurns` (slow zoom for an image layer), `withFade`, `wiggle` (seeded shake as keyframes), `stagger`, `animateText` (per letter / word entrances), `followPath`, `particles` (seeded confetti / snow / sparks as layers), `deck` (slides). Each returns keyframes or layers: `keyframes: wiggle(...)`, `...particles(...)`. The full signatures are in `https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/reference/cheatsheet.md` (22 KB; read it only if you need a helper).
+- **Helpers already imported** in the template: `kenBurns` (slow zoom for an image layer), `withFade`, `wiggle` (seeded shake as keyframes), `stagger`, `animateText` (per letter / word entrances), `followPath`, `particles` (seeded confetti / snow / sparks as layers), `deck` (slides). Each returns keyframes or layers: `keyframes: wiggle(...)`, `...particles(...)`. The full signatures are in `https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/skills/pixi-effects/reference/cheatsheet.md` (22 KB; read it only if you need a helper).
 - **Advanced:** `const INIT = { assets: [...], composition: { transitions: [...] } }` in the edit block adds `movie.init` options (the page merges it); most videos need nothing here.
 - **Not available on this page:** named filters beyond `blur`, `noise`, `alpha`, `colorMatrix`, `grain` (the other 38 need the `pixi-filters` package; film grain is `{ type: 'grain' }`), three.js layers, your own image / video / music files. Say so rather than guessing.
 
@@ -107,4 +107,4 @@ Read your file once for these: every layer has a `type`; every keyframe `at` is
 
 A blank preview with no red box usually means the chat's preview window blocks external scripts or does not allow `eval`. Tell the person to **save the file as `video.html` and open it in a browser** (Chrome, Edge or Firefox on a computer); that always works.
 
-More: the full skill (`ai/SKILL.md`) and pitfalls (`ai/reference/pitfalls.md`) are for an AI with a shell and a browser; this page is the short version for a chat.
+More: the full skill (`skills/pixi-effects/SKILL.md`) and pitfalls (`skills/pixi-effects/reference/pitfalls.md`) are for an AI with a shell and a browser; this page is the short version for a chat.

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.22.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.22.0/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.22.0/dist/Presenter.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Presenter.js"
     }
   }
   </script>

package/ai/tools/check.mjs

@@ -2,7 +2,7 @@
 /**
  * pixi-effects check — review a composition page in ONE command, without driving a browser by hand.
  *
- *   node ai/tools/check.mjs my-video.html            (or:  npx pixi-effects-check my-video.html)
+ *   node ai/tools/check.mjs my-video.html            (or:  npx pixi-effects check my-video.html)
  *
  * It starts a private static server and a private headless Chrome (nothing shared with other sessions), opens the page,
  * waits for `window.__ready === true`, then checks: console warnings / errors, `movie.inspect` over the whole timeline
@@ -11,7 +11,7 @@
  * (`sheet.png`, `<name>.<format>`, `report.json`; a presentation with `stops` also gets `stops.png`, one picture per stop) and a short summary is printed. Exit code 0 = nothing to fix, 1 = problems.
  *
  * Needs: Node >= 22 (built-in WebSocket), Chrome / Chromium installed (or --chrome PATH / CHROME=PATH). No npm dependencies.
- * The page must follow ai/template.html: it exposes `window.movie` and sets `window.__ready = true` (and `window.__logs`).
+ * The page must follow skills/pixi-effects/template.html: it exposes `window.movie` and sets `window.__ready = true` (and `window.__logs`).
  *
  * Options: --draft (the export is a draft: half size, low quality, no motion blur: a much smaller file; the drawing itself is not faster) · --at LIST (pictures at moments you name: 3.5, 50%, f120, title@end → frames/*.png and at.png) ·
  *          --query "a=1&b=2" (added to the page address: for a page that reads it, such as one video of a batch) ·
@@ -342,6 +342,9 @@ export async function runCheck(opts, log = console.log) {
         // depth of field: the blur (px) each threeD layer has at this moment, so a focus pull can be read as numbers (0 = sharp)
         const rows = await cdp.eval(`movie.inspect(${w.frame}).then(r => r.layers.filter(l => l.depthBlur !== undefined).map(l => [l.path, l.depthBlur]))`).catch(() => []);
         if (rows.some(([, px]) => px > 0)) w.depthBlur = Object.fromEntries(rows);
+        // light: how lit each threeD layer is at this moment (left out when the composition has no light)
+        const lit = await cdp.eval(`movie.inspect(${w.frame}).then(r => r.layers.filter(l => l.light !== undefined).map(l => [l.path, l.light]))`).catch(() => []);
+        if (lit.length) w.light = Object.fromEntries(lit);
       }
       const atSheet = await cdp.eval(`movie.contactSheet({ frames: ${JSON.stringify(wanted.map(w => w.frame))}, as: 'dataURL' })`);
       const atFile = path.join(outDir, 'at.png');
@@ -479,6 +482,10 @@ function finish(report, outDir, log) {
     const shown = Object.entries(w.depthBlur).slice(0, 8).map(([k, px]) => `${k} ${px} px`).join(', ');
     L.push(`  depth     ${w.label} — ${shown}${Object.keys(w.depthBlur).length > 8 ? ', …' : ''} (blur of each threeD layer at that moment; 0 = sharp)`);
   }
+  for (const w of (report.at ?? []).filter(x => x.light)) {
+    const shown = Object.entries(w.light).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([k, v]) => `${k} ${v}`).join(', ');   // the most lit first
+    L.push(`  light     ${w.label} — ${shown}${Object.keys(w.light).length > 8 ? ', …' : ''} (the most lit threeD layers first: 1 = as bright as with no light, 0 = black; the number is the layer's middle, not what you can see)`);
+  }
   if (report.stops) {
     const s = report.stops;
     L.push(`  stops     ${s.count} stop(s) on ${s.pages} page(s) — stops.png shows each one in order; the picture at a stop is what the audience sees while it waits`);
@@ -507,7 +514,7 @@ function finish(report, outDir, log) {
 
 // ───────────────────────────── CLI ─────────────────────────────
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {   // the real path: npm starts a bin through a symlink
   try {
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseArgs(process.argv.slice(2));

package/ai/tools/pixi-effects.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * pixi-effects — one command for the three tools, named like the package so `npx pixi-effects check my-video.html` works with nothing installed.
+ *
+ *   npx pixi-effects check  my-video.html [--at 3,6] [--out dir]    review it: warnings, layout, sound, a contact sheet, a real export
+ *   npx pixi-effects render my-video.html -o my-video.mp4           export the file
+ *   npx pixi-effects view   my-video.html                           open it in a browser with a timeline
+ *
+ * Everything after the command goes to the tool unchanged (`check.mjs`, `render.mjs`, `view.mjs`; their own headers list every option), and so do the
+ * exit code and the output. The three older bins (`pixi-effects-check|render|view`) still work.
+ */
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TOOLS = { check: 'check.mjs', render: 'render.mjs', view: 'view.mjs' };
+const USAGE = `usage:
+  pixi-effects check  <page.html> [--at 3,6] [--out dir]    review a video page: warnings, layout, sound, contact sheet, real export
+  pixi-effects render <page.html> -o <file.mp4>             export the video
+  pixi-effects view   <page.html>                           look at it in a browser, with a timeline
+(every option of a command is listed in the header of its file: node_modules/pixi-effects/ai/tools/<command>.mjs)`;
+
+function nearest(word) {
+  const d = (a, b) => { const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]); for (let j = 1; j <= b.length; j++) m[0][j] = j;
+    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)); return m[a.length][b.length]; };
+  const best = Object.keys(TOOLS).map(k => [k, d(word, k)]).sort((x, y) => x[1] - y[1])[0];
+  return best[1] <= 2 ? best[0] : null;
+}
+
+/** Which tool a command line asks for: `{ tool, args }`, or `{ usage }` (no command / --help), or `{ error }`. */
+export function route(argv) {
+  const [cmd, ...args] = argv;
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') return { usage: USAGE };
+  if (TOOLS[cmd]) return { tool: TOOLS[cmd], args };
+  const guess = /\.html?$/i.test(cmd) ? 'check' : nearest(cmd);
+  return { error: `pixi-effects: unknown command "${cmd}"${guess ? `; did you mean "${guess}"?` : ''} The commands are: ${Object.keys(TOOLS).join(', ')}.\n${USAGE}` };
+}
+
+const self = fileURLToPath(import.meta.url);
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(self)) {
+  const r = route(process.argv.slice(2));
+  if (r.usage) { console.log(r.usage); process.exit(process.argv.length > 2 ? 0 : 2); }
+  if (r.error) { console.error(r.error); process.exit(2); }
+  const child = spawn(process.execPath, [resolve(dirname(self), r.tool), ...r.args], { stdio: 'inherit' });
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => child.kill(sig));   // a harness that stops this process stops the tool (and its Chrome) too
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 128 : 1)));
+}

package/ai/tools/render.mjs

@@ -2,10 +2,10 @@
 /**
  * pixi-effects render — turn a composition page into a video file, headless, in ONE command.
  *
- *   node ai/tools/render.mjs my-video.html -o my-video.mp4        (or:  npx pixi-effects-render my-video.html -o out.mp4)
+ *   node ai/tools/render.mjs my-video.html -o my-video.mp4        (or:  npx pixi-effects render my-video.html -o out.mp4)
  *
  * It starts a private static server and a private headless Chrome, opens the page, waits for `window.__ready === true`
- * (the contract of ai/template.html), runs `movie.render()` in the page and streams the file to disk. Nothing is decoded or
+ * (the contract of skills/pixi-effects/template.html), runs `movie.render()` in the page and streams the file to disk. Nothing is decoded or
  * reviewed: that is `pixi-effects-check`'s job. Use this one to produce the file (a script, CI, a batch).
  *
  * Needs: Node >= 22 (built-in WebSocket), Chrome / Chromium installed (or CHROME=PATH / --chrome PATH). No npm dependencies.
@@ -200,7 +200,7 @@ export async function runRender(opts, log = console.log, progress = () => {}) {
 
 // ───────────────────────────── CLI ─────────────────────────────
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {   // the real path: npm starts a bin through a symlink
   try {
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseRenderArgs(process.argv.slice(2));

package/ai/tools/view.mjs

@@ -2,7 +2,7 @@
 /**
  * pixi-effects view — look at a composition page WITH its timeline, and scrub the one with the other.
  *
- *   node ai/tools/view.mjs my-video.html            (or:  npx pixi-effects-view my-video.html)
+ *   node ai/tools/view.mjs my-video.html            (or:  npx pixi-effects view my-video.html)
  *
  * It serves the page's folder on a private port and opens your browser on a viewer: the page itself on top (its own player
  * works as usual) and, under it, the timeline of every layer (`movie.timelineSvg()`) with a playhead that follows the movie.
@@ -10,7 +10,7 @@
  * ← / → step a frame (Shift: a second), Home / End jump to the ends. Stop it with Ctrl-C.
  *
  * Needs: Node >= 18. A browser (the default one is opened; --no-open prints the address instead). The page must follow
- * ai/template.html (`window.movie`, `window.__ready = true`) and use a pixi-effects that has `movie.timelineSvg()` (0.7+).
+ * skills/pixi-effects/template.html (`window.movie`, `window.__ready = true`) and use a pixi-effects that has `movie.timelineSvg()` (0.7+).
  * Options: --port N (default: a free one) · --no-open · --query "a=1" (added to the page URL) · --root DIR (default: the nearest folder above the page with dist/)
  */
 import http from 'node:http';
@@ -252,7 +252,7 @@ export async function startViewer(opts) {
   return { server, url: `http://127.0.0.1:${port}${VIEWER}` };
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {   // the real path: npm starts a bin through a symlink
   try {
     const opts = parseViewArgs(process.argv.slice(2));
     if (!opts.page) {

package/dist/{Base-gu-5X0Cv.d.ts → Base-BgnRXbtJ.d.ts}

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

package/dist/{Base-BzlPgd-D.d.cts → Base-DHVKqA46.d.cts}

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

package/dist/Composition-2GJSCHPP.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkSY27HZC5_cjs = require('./chunk-SY27HZC5.cjs');
+require('./chunk-DP37TTMO.cjs');
+require('./chunk-3DLYAPK7.cjs');
+require('./chunk-ECA2WNRX.cjs');
+require('./chunk-TWZNOUM7.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkSY27HZC5_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-2GJSCHPP.cjs.map
+//# sourceMappingURL=Composition-2GJSCHPP.cjs.map

package/dist/{Composition-BK5SH6J7.cjs.map → Composition-2GJSCHPP.cjs.map}

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

package/dist/Composition-C4FSWJZF.js

@@ -0,0 +1,7 @@
+export { CompositionSequence } from './chunk-XS6GSJCN.js';
+import './chunk-PRZ4U6JN.js';
+import './chunk-AXZUKNXF.js';
+import './chunk-TLYTYBWX.js';
+import './chunk-BXOCEZ4U.js';
+//# sourceMappingURL=Composition-C4FSWJZF.js.map
+//# sourceMappingURL=Composition-C4FSWJZF.js.map

package/dist/{Composition-Q5TVG3HM.js.map → Composition-C4FSWJZF.js.map}

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

package/dist/Controller.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkUZTKEYFP_cjs = require('./chunk-UZTKEYFP.cjs');
+var chunkTWZNOUM7_cjs = require('./chunk-TWZNOUM7.cjs');
 
 // src/Controller.ts
 var ICONS = {
@@ -456,7 +456,7 @@ var Controller = class _Controller {
   }
   /** Change the look of the bar (see {@link ControllerTheme}): only the keys you give change, `null` restores the default. */
   setTheme(theme) {
-    chunkUZTKEYFP_cjs.warnUnknownOptions("Controller theme", theme, Object.keys(THEME_PROPERTIES));
+    chunkTWZNOUM7_cjs.warnUnknownOptions("Controller theme", theme, Object.keys(THEME_PROPERTIES));
     for (const key of Object.keys(THEME_PROPERTIES)) {
       if (!(key in theme)) continue;
       const value = theme[key];

package/dist/Controller.d.cts

@@ -1,7 +1,7 @@
-import { h as Movie } from './Movie-DMxOoTdW.cjs';
+import { h as Movie } from './Movie-DXReF4-W.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-DBbZVKGS.cjs';
+import './types-CoT0ypcx.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 { h as Movie } from './Movie--_TJvdJa.js';
+import { h as Movie } from './Movie-DP5p1r4E.js';
 import 'pixi.js';
 import 'gsap';
-import './types-DBbZVKGS.js';
+import './types-CoT0ypcx.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/Controller.js

@@ -1,4 +1,4 @@
-import { warnUnknownOptions } from './chunk-NHICCDTC.js';
+import { warnUnknownOptions } from './chunk-BXOCEZ4U.js';
 
 // src/Controller.ts
 var ICONS = {

package/dist/{Movie--_TJvdJa.d.ts → Movie-DP5p1r4E.d.ts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { V as Stop, e as AssetSpec, c as CompositionSpec } from './types-DBbZVKGS.js';
+import { _ as Stop, e as AssetSpec, c as CompositionSpec } from './types-CoT0ypcx.js';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
@@ -144,6 +144,8 @@ interface LayerInfo {
     onCanvas: 'full' | 'partial' | 'none' | null;
     /** Depth of field (threeD layers only): the blur radius in canvas pixels this frame, from the layer's depth and the camera's focus; 0 = sharp. */
     depthBlur?: number;
+    /** Light (threeD layers that receive lights): how lit the layer is this frame, 0..1+ (the brightness of the light falling on its middle; 1 = as with no light, 0 = black). Left out when there is no light. */
+    light?: number;
 }
 interface InspectReport {
     frame: number;
@@ -443,6 +445,8 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** True while the movie has sound but the browser keeps it silent until the viewer taps (iOS Safari, a page nobody has touched): a player can show "tap for sound"; the sound starts at a tap or key press that arrives while play() is pending, or at the next play() made from a tap. */
+    get audioBlocked(): boolean;
     /** The poster time as a frame number, or null. */
     get posterFrame(): number | null;
     /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */

package/dist/{Movie-DMxOoTdW.d.cts → Movie-DXReF4-W.d.cts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { gsap } from 'gsap';
-import { V as Stop, e as AssetSpec, c as CompositionSpec } from './types-DBbZVKGS.cjs';
+import { _ as Stop, e as AssetSpec, c as CompositionSpec } from './types-CoT0ypcx.cjs';
 
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
@@ -144,6 +144,8 @@ interface LayerInfo {
     onCanvas: 'full' | 'partial' | 'none' | null;
     /** Depth of field (threeD layers only): the blur radius in canvas pixels this frame, from the layer's depth and the camera's focus; 0 = sharp. */
     depthBlur?: number;
+    /** Light (threeD layers that receive lights): how lit the layer is this frame, 0..1+ (the brightness of the light falling on its middle; 1 = as with no light, 0 = black). Left out when there is no light. */
+    light?: number;
 }
 interface InspectReport {
     frame: number;
@@ -443,6 +445,8 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** True while the movie has sound but the browser keeps it silent until the viewer taps (iOS Safari, a page nobody has touched): a player can show "tap for sound"; the sound starts at a tap or key press that arrives while play() is pending, or at the next play() made from a tap. */
+    get audioBlocked(): boolean;
     /** The poster time as a frame number, or null. */
     get posterFrame(): number | null;
     /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */

package/dist/Presenter.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkUZTKEYFP_cjs = require('./chunk-UZTKEYFP.cjs');
+var chunkTWZNOUM7_cjs = require('./chunk-TWZNOUM7.cjs');
 
 // src/Presenter.ts
 var OPTION_KEYS = ["canvas", "keyboard", "clickToAdvance", "swipe", "indicator", "autoAdvance", "loop", "accent", "onExit"];
@@ -147,7 +147,7 @@ var Presenter = class {
   };
   constructor(movie, options) {
     if (!options || !options.canvas) throw new Error("Presenter requires options.canvas (HTMLCanvasElement).");
-    chunkUZTKEYFP_cjs.warnUnknownOptions("Presenter", options, OPTION_KEYS);
+    chunkTWZNOUM7_cjs.warnUnknownOptions("Presenter", options, OPTION_KEYS);
     this.movie = movie;
     this.options = {
       canvas: options.canvas,

package/dist/Presenter.d.cts

@@ -1,7 +1,7 @@
-import { h as Movie } from './Movie-DMxOoTdW.cjs';
+import { h as Movie } from './Movie-DXReF4-W.cjs';
 import 'pixi.js';
 import 'gsap';
-import './types-DBbZVKGS.cjs';
+import './types-CoT0ypcx.cjs';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/Presenter.d.ts

@@ -1,7 +1,7 @@
-import { h as Movie } from './Movie--_TJvdJa.js';
+import { h as Movie } from './Movie-DP5p1r4E.js';
 import 'pixi.js';
 import 'gsap';
-import './types-DBbZVKGS.js';
+import './types-CoT0ypcx.js';
 
 interface PresenterOptions {
     canvas: HTMLCanvasElement;

package/dist/Presenter.js

@@ -1,4 +1,4 @@
-import { warnUnknownOptions } from './chunk-NHICCDTC.js';
+import { warnUnknownOptions } from './chunk-BXOCEZ4U.js';
 
 // src/Presenter.ts
 var OPTION_KEYS = ["canvas", "keyboard", "clickToAdvance", "swipe", "indicator", "autoAdvance", "loop", "accent", "onExit"];

package/dist/{blendModes-HCP5XTNP.js → blendModes-G3NOAU3T.js}

@@ -1,6 +1,6 @@
-import { setBlendFilterFactory } from './chunk-YEPDQ7I3.js';
-import './chunk-E7RONUZ7.js';
-import './chunk-NHICCDTC.js';
+import { setBlendFilterFactory } from './chunk-AXZUKNXF.js';
+import './chunk-TLYTYBWX.js';
+import './chunk-BXOCEZ4U.js';
 import { BlendModeFilter, ExtensionType, extensions } from 'pixi.js';
 
 var SEPARABLE = {
@@ -86,5 +86,5 @@ fn blendRGB(cb: vec3<f32>, cs: vec3<f32>) -> vec3<f32> { ${s.gpu} }`);
 }
 
 export { OWN_MODES, createBlendFilter, registerBlendModes };
-//# sourceMappingURL=blendModes-HCP5XTNP.js.map
-//# sourceMappingURL=blendModes-HCP5XTNP.js.map
+//# sourceMappingURL=blendModes-G3NOAU3T.js.map
+//# sourceMappingURL=blendModes-G3NOAU3T.js.map