pixi-effects 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.41.0
+
+`movie.pick` (what is under a point of the canvas) and a better fit of the light falloff in a `three` layer. Nothing breaks.
+
+- **New: `movie.pick(x, y)`, `pickAll`, `canvasPoint(event)`: what is under a point of the canvas.** The layer on top (or every layer under the point, the top first) at the frame on screen, in canvas pixels: a flat layer by its own shape (a rotated bar by its rotated rectangle, a circle by the circle), a `threeD` card by its projected quad, a `three` layer by a ray through its camera (`hit.three.object` names the object it met, with the point and the distance; with `followCamera` it is the composition's camera). `canvasPoint(event)` turns a pointer event into canvas pixels when the canvas is shown at another size. A layer outside its life, at alpha 0, hidden by a parent or outside its mask is not hit; `{ only, ignore }` choose by name or path. No clock: it reads the frame as the last draw left it, so it is a function of the frame (a seek back gives the same answer). Not in this version: alpha-exact hits, hover and drag. `check --at 3.5 --pick 640,360` (repeatable) prints what is under that point at each moment, so an AI can answer "is the button where I think" without looking. Recipe `pick-click`; `docs/api.md`; tests `tests/core/pick.test.ts`, `tests/films/pick` (real Chrome: rotated bar, circle, a turned card, a cube, a gliding camera, a canvas shown at twice its size).
+
+- **Changed: `followLights` fits the falloff better.** `falloff: 'smooth'` on a mirrored light is now three's cut-off distance and gain chosen from where the fall starts (before: the cut-off at `radius + falloffDistance`), which halves the largest difference to the composition's curve (0.15–0.40 before, 0.09–0.17 for a fall that is not steep; in the real picture mean 0.08–0.28 of 255, was 1.0–1.2). `'inverseSquare'` was already exact outside the radius (mean 0.02–0.03) but blows out inside it (three keeps rising where the composition holds 1; measured mean 21 of 255 with the lit objects inside the radius): the layer now says so once, with the distance and the way out (a smaller radius, or `'smooth'`). `tests/films/three-space`, `tests/three/spaceBridge.test.ts`.
+
+## 0.40.0
+
+The `three` layer grows up: it can live in the composition's space, it loads glTF models, `check` holds it to the library's contract, and it can use three's WebGPU renderer. Nothing else changed; one type-only break (the last entry).
+
+- **New: a `three` layer can live in the composition's space (`followCamera`, `followLights`, `followFog`).** `followCamera: true` puts the layer's `PerspectiveCamera` where the composition's `camera` layer is, every frame (position, look-at point, vertical fov, the handheld offsets), so one `cameraPath()` or `orbit()` flies through the flat layers and the three scene together. The scene is in composition pixels with y flipped (the composition's `(x, y, z)` is `(x, -y, z)` in three); a point lands on the same pixel as the composition's own projection (to 1e-6 px; against the composition's cards in the real picture: mean 0.14–0.19 of 255, edges only). `followLights: true` makes the composition's `light` layers three lights (ambient, point, spot, parallel; position, colour, intensity, cone, falloff; the intensity times π, because three divides a diffuse surface by π), moved every frame; **a light with `castsShadows` casts in three** (the layer's own meshes choose who casts and receives: a card in front of a wall under a spot throws the same shadow as the composition's cards, mean 0.2–0.35 of 255, WebGL and WebGPU, at 480 × 270 and at 1280 × 720). With `MeshLambertMaterial` and three's colour management off the planes shade like the cards (mean 0.02–0.2 of 255); with three's defaults close (0.8–1.4). `followFog: true` makes the camera's fog the scene's `Fog`: close, not equal (three fades by `smoothstep`, the composition linearly, and has no `fogAmount` below 1, which warns once; mean 0.5–1.8 of 255 where the fog's own effect is 2–7). `ctx.space` gives the raw camera, lights and fog. A composition whose only consumer is such a layer no longer warns that its camera or light has no effect, or that no layer casts a shadow. Pinned by `tests/films/three-space` against the composition's own cards. See `docs/dsl.md` → three.
+- **New: glTF models in the free `three` layer: `threeGltf`, `threeFrameCamera`, `pixi-effects probe model.glb`.** `threeGltf(url, { animation, speed, offset, loop })` returns `{ object, clips, size, pose(t), fit(px), dispose() }`: the group's origin is the centre of the model, `pose(t)` is `AnimationMixer.setTime` (a function of the time: a seek, an export and a repeat give the same frame), `fit(px)` scales the longest side to pixels, and skinned meshes are drawn always (three culls them by a bounding sphere that does not follow them: a moving, shadow-casting Fox drew its shadow depending on the frames drawn before it). `threeFrameCamera(camera, object, { direction, margin })` puts a camera where the whole model fits (a three-quarter view, from the corners of the bounding box rather than a sphere). `probe model.glb` (or `.gltf`) reads in Node, with no browser and no three.js, the clips with their lengths, the size (equal to what `threeGltf(...).size` measures; Khronos Fox: 25.185 × 79.029 × 154.72) and notes (Draco / KTX2 / Meshopt need a decoder that `threeGltf` does not set up; no animation; files to keep beside the model). The template's import map has `three/addons/`. Recipes `gltf-in-space` and `gltf-shadow-room` (a model running through a sweeping spotlight with its shadow on a wall and a lit flat caption), written and corrected after three fresh-AI trials on the real Khronos Fox. Tests: `tests/three/gltf.test.ts`, `tests/films/gltf-model`, `tests/tools/probeGltf.test.ts`.
+- **New: `check` holds a `three` layer to "a function of the time", as it does a `canvas` layer.** It draws the scene at four moments in two orders (one draw thrown away first), reads the picture from the renderer's canvas and compares: a clock, `Math.random`, a mixer advanced with `mixer.update(dt)` or a speed that builds up from call to call is reported with the moments and the fix (`mixer.setTime(t)` / `threeGltf(url).pose(t)`); `Math.random` / `Date.now` / `performance.now` / `new Date` in `update` also warns at build. `check` prints a `three` line when every layer passed (WebGL and WebGPU), the canvas heading says "layer(s) (canvas / three)", and `movie.canvasReport()` rows have a `kind`. `tests/tools/threeDeterminism.test.ts`.
+- **New: a page with too many `three` layers says so instead of going blank.** A browser keeps about 16 live WebGL contexts for a page (about 32 WebGPU: measured on Chrome); layers beyond that draw nothing and raise no error. The 13th live WebGL layer (the 29th WebGPU one) now warns once with the count and the way out, and a layer whose WebGL context the browser took away names itself. `docs/dsl.md` had said "roughly 8–16". `tests/films/three-budget` (20 layers in real Chrome).
+- **New: a `three` layer can draw with three's WebGPU renderer (`renderer: 'webgpu'`), `antialias`, and a page-level default `registerThree({ renderer })`.** The layer used `WebGLRenderer` always, in its own offscreen context. `renderer: 'webgpu'` uses `WebGPURenderer` from `three/webgpu` (three 0.17x or later); the default stays `'webgl'` (a design review by two independent reviewers, with measurements on four large GLSL clips, rejected a silent fallback that runs `setup` twice: a second `setup` can draw a different video). The same lit scene draws within 0.06 of 255 per channel of the WebGL picture and each renderer is a function of the time (`tests/films/three-renderers`); the render alone is about the same for a box and about twice as fast on WebGPU for 2,880 instanced rods; an MP4 export is limited by the encode and took the same time. `antialias` (default `true`): WebGPURenderer blends fog and resolves multisampling in linear light before tone mapping, WebGLRenderer after it, so fog and thin hot edges differ by design; with `antialias: false` and no fog the two agree to 0.04 of 255. On `'webgpu'`, a `ShaderMaterial` / `RawShaderMaterial` / `onBeforeCompile` material stops the build with the fix (it used to draw a broken picture) and a `PMREMGenerator` taken from `three` is explained; where the browser has no WebGPU three's WebGL2 backend draws the same picture (`ThreeSequence.renderer` / `.backend` say what was used, and `movie.inspect()` lists them). Three's WebGPU renderer updates light uniforms once per animation-loop frame, so a seek or an export showed stale lights: the layer now advances three's node frame before each render and gives `time` the layer's own time. See `docs/dsl.md` → three.
+- **Changed (types only): `ThreeContext.renderer` is `WebGLRenderer | WebGPURenderer`.** TypeScript code that used WebGL-only members of `ctx.renderer` has to narrow it (`ctx.renderer instanceof WebGLRenderer`); `setClearColor`, `toneMapping` and `toneMappingExposure` exist on both. `docs/api.md` → `pixi-effects/three` lists the whole entry.
+
 ## 0.39.0
 
 **The tools tell the truth, and a file can be checked against what it must be**

package/README.md

@@ -1,8 +1,8 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.39.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.41.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/)** · 52 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.
+**[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 43 pieces written as plain data by AI models · **[For AI →](https://yjmtmtk.github.io/pixi-effects/for-ai.html)** · what an AI reads and runs · **[Playground →](https://yjmtmtk.github.io/pixi-effects/examples/playground.html)** in the browser.
 
 ## Make a video by asking an AI
 
@@ -21,11 +21,11 @@ Declarative composition and video rendering for the web. After Effects-style tim
 - **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; 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/present`) 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 (`exportPDF(movie)`, `pixi-effects render talk.html -o talk.pdf`). See the [Presenting guide](https://yjmtmtk.github.io/pixi-effects/guide/presenting.html).
+- **Presentations** — `stops` in the composition pause the movie where you say; `Presenter` (`pixi-effects/present`) 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 (`exportPDF(movie)`, `pixi-effects render talk.html -o talk.pdf`).
 - **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.
 - **Audio-reactive visuals** — `audioEnvelope('music.mp3')` analyses loudness, bass / mid / treble and the beats per frame; `react()` turns them into keyframes, so the picture follows the music and still renders identically.
 - **2.5D layers & camera** — add `threeD: true`, `z`, `rotationX/Y` and a `{ type: 'camera' }` layer for parallax, flips and dolly zooms; no three.js needed.
-- **three.js layer** *(optional)* — drop a real three.js scene in as a layer via `pixi-effects/three`; keyframes drive its objects (`three.cube.rotation.y`).
+- **three.js layer** *(optional)* — drop a real three.js scene in as a layer via `pixi-effects/three`; keyframes drive its objects (`three.cube.rotation.y`). It can live in the composition's space: the composition's camera, lights, shadows and fog drive the scene, so one `cameraPath()` flies through the flat layers and a glTF model together (`threeGltf`).
 - **Built-in player UI — or your own** — a drop-in HTML5-`<video>`-style overlay controller (play, scrub, mute, volume, fullscreen, export-to-file) whose colours are one option (`theme: { accent: '#ff4d6d' }`); or build a player yourself on the movie's `<video>`-named events (`play pause ended seeking seeked volumechange error`).
 - **MP4 / WebM / MOV export** — pick container and quality from the controller, call `movie.render()` from code, or render headless from the command line (`pixi-effects render`).
 - **A timeline you can read and scrub** — `movie.timelineChart()` draws every layer as a bar on a time axis; `pixi-effects view` opens the page with that timeline under it, zoomable, with a playhead you can drag.
@@ -49,8 +49,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
   "imports": {
     "pixi.js":                 "https://esm.sh/pixi.js@8.22.0?bundle-deps",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.39.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.39.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/Controller.js"
   }
 }
 </script>
@@ -61,7 +61,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.39.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.41.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.
 >
@@ -69,7 +69,7 @@ Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg
 
 #### Adding three.js (optional)
 
-Add two more entries to the importmap above: three.js itself, and the `pixi-effects/three` entry.
+Add two more entries to the importmap above: three.js itself, and the `pixi-effects/three` entry (and `three/addons/` if you load a glTF model with `threeGltf`).
 
 ```html
 <script type="importmap">
@@ -77,7 +77,8 @@ 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.39.0/dist/three.js"
+    "three/addons/":           "https://cdn.jsdelivr.net/npm/three@0.178.0/examples/jsm/",
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/three.js"
   }
 }
 </script>
@@ -112,7 +113,7 @@ Always route `three` through the importmap — both your code and `pixi-effects/
 </script>
 ```
 
-The layer is a normal sprite once built, so 2D keyframes, masks and filters work on it. Full spec, rules and caveats (one WebGL context per layer, `update(t)` must be a pure function of `t`): [DSL reference § three](./docs/dsl.md#three) and [API reference](./docs/api.md#pixi-effectsthree). Runnable: [`examples/10-three.html`](./examples/10-three.html).
+The layer is a normal sprite once built, so 2D keyframes, masks and filters work on it. Full spec, rules and caveats (one WebGL context per layer, `update(t)` must be a pure function of `t`): [DSL reference § three](./docs/dsl.md#three) and [API reference](./docs/api.md#pixi-effectsthree).
 
 With a bundler, `import { registerThree, three } from 'pixi-effects/three'` works the same once you've installed `three`.
 
@@ -164,7 +165,7 @@ 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. 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).
+`+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).
 
 ## For AI agents
 
@@ -187,25 +188,10 @@ They ship in the npm package (`node_modules/pixi-effects/ai/`).
 
 - [**DSL reference**](./docs/dsl.md) — composition, sequences, 3D layers & camera, three.js layer, keyframes, expressions, filters
 - [**API reference**](./docs/api.md) — `Movie`, `Controller`, `pixi-effects/present`, `pixi-effects/three`, events, render options
-- [**Interactive movies**](./examples/interactive/) — nine live samples of a movie you change while it plays (variables, `setVars`, `rebuild`, loop): rock paper scissors, a scrolling city, a tune from four chords, a card for anyone, choose your ending … ([the guide chapter](./site/guide/interactive.md))
-- [**Examples**](./examples/) — runnable HTML files (read in order):
-  - `01-hello.html` — minimum viable composition
-  - `02-keyframes.html` — keyframes, easings, expressions
-  - `03-shapes.html` — every shape primitive
-  - `04-media.html` — image / video / audio
-  - `05-composition-mask.html` — nested compositions and masks
-  - `06-filters.html` — built-in and pixi-filters (as `{ type: 'custom' }`; most can now be written by name, see `docs/dsl.md` → Named filters)
-  - `07-transitions.html` — all seven transition kinds in one timeline
-  - `08-presets-export.html` — `kenBurns` preset and `movie.render()` from code
-  - `09-audio.html` — multi-track audio mixing with BGM ducking and SFX cues
-  - `10-three.html` — a three.js scene as a layer (`pixi-effects/three`)
-  - `11-depth.html` — 2.5D layers and camera: parallax, spin, dolly zoom
-  - `12-title-motion.html` — a staggered 2.5D title: letters fly in from depth, particles, orbiting camera
-  - `13-sfx.html` — synthesised sound effects (no audio files), a riser into a hit, a custom voice
-  - `15-custom-player.html` — a complete player of your own in about 40 lines (play, seek, volume, replay) using the movie's events
-  - `14-draw-on.html` — draw-on strokes (`trimStart` / `trimEnd`) and text that changes over time (`visibleChars`, `set: { text }`)
-  - `music-lab.html` — eight tunes written as text (no audio files): press play, read each score; `musicBuffer()` plays music with no movie
-  - `playground.html` — in-browser editor on the chat template's edit block: twelve examples, a problems panel from `movie.review()`, share links, save as HTML, and WebMCP tools for an AI agent
+- [**Interactive movies**](./examples/interactive/) — nine live samples of a movie you change while it plays (variables, `setVars`, `rebuild`, loop): rock paper scissors, a scrolling city, a tune from four chords, a card for anyone, choose your ending … ([docs/api.md](./docs/api.md))
+- [**Gallery**](./examples/gallery/) — 43 complete pieces, each one HTML file of data
+- [**Recipes**](./skills/pixi-effects/reference/recipes.md) — tested code you can copy (`npx pixi-effects recipe`)
+- [**Playground**](./examples/playground.html) — in-browser editor on the chat template's edit block: fourteen examples (the tested recipes), a problems panel from `movie.review()`, share links, save as HTML, and WebMCP tools for an AI agent
 
 ## Browser support
 

package/ai/chat-template.html

@@ -59,9 +59,9 @@
     "imports": {
       "pixi.js":                 "https://cdn.jsdelivr.net/npm/pixi.js@8.22.0/dist/pixi.min.mjs",
       "mediabunny":              "https://cdn.jsdelivr.net/npm/mediabunny@1.61.3/+esm",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.39.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.39.0/dist/Controller.js",
-      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.39.0/dist/present.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/present.js"
     }
   }
   </script>

package/ai/tools/check.mjs

@@ -16,6 +16,7 @@
  * 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) ·
  *          --crop X,Y,W,H (with --at: each picture is that part of the canvas, in canvas pixels, enlarged up to 4x so a small figure can be judged) ·
+ *          --pick X,Y (with --at, repeatable: what is under that canvas point at each moment, the top layer first, and the object a three layer met: `movie.pick`) ·
  *          --onion A:B (one picture of the movement between A and B seconds, frames overlaid: onion.png) ·
  *          --seam (a movie made to loop: the last frame to the first is compared with the steps between ordinary neighbouring frames; a jump is a problem) ·
  *          --strict (text overlaps and stops where the picture is still changing fail the check; by default they are only listed for review) · --out DIR · --frames N (contact sheet tiles, default 12) · --formats mp4,webm (default mp4) · --no-export ·
@@ -81,10 +82,10 @@ export function findChrome(env = process.env, exists = fs.existsSync, platform =
   return candidates.find(c => c && exists(c)) ?? null;
 }
 
-export const USAGE = 'usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--draft] [--at 3.5,title@end] [--crop X,Y,W,H] [--onion 1:3] [--seam] [--query a=1&b=2] [--var name=value] [--size 1920x1080,1080x1920] [--timeout S] [--root DIR] [--chrome PATH] [--strict] [--help]\n(the header of ai/tools/check.mjs explains each option)';
+export const USAGE = 'usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--draft] [--at 3.5,title@end] [--crop X,Y,W,H] [--pick X,Y] [--onion 1:3] [--seam] [--query a=1&b=2] [--var name=value] [--size 1920x1080,1080x1920] [--timeout S] [--root DIR] [--chrome PATH] [--strict] [--help]\n(the header of ai/tools/check.mjs explains each option)';
 
 export function parseArgs(argv) {
-  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, crop: null, draft: false, onion: null, seam: false, query: null, vars: [], sizes: [], help: false };
+  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, crop: null, draft: false, onion: null, seam: false, query: null, pick: [], vars: [], sizes: [], help: false };
   const need = (i, name) => { if (i + 1 >= argv.length) throw new Error(`${name} needs a value`); return argv[i + 1]; };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -102,6 +103,11 @@ export function parseArgs(argv) {
       if (m.length !== 4 || !m.every(Number.isFinite) || m[0] < 0 || m[1] < 0 || m[2] < 1 || m[3] < 1) throw new Error(`--crop must look like 100,200,400,300 (x, y, width, height in canvas pixels, width and height at least 1), got "${argv[i]}"`);
       o.crop = { x: Math.round(m[0]), y: Math.round(m[1]), width: Math.round(m[2]), height: Math.round(m[3]) };
     }
+    else if (a === '--pick') {
+      const m = need(i++, a).split(',').map(Number);
+      if (m.length !== 2 || !m.every(Number.isFinite)) throw new Error(`--pick must look like 640,360 (x, y in canvas pixels), got "${argv[i]}"`);
+      o.pick.push({ x: m[0], y: m[1] });
+    }
     else if (a === '--var') o.vars.push(parseVar(need(i++, a)));
     else if (a === '--size') o.sizes.push(...parseSizes(need(i++, a)));
     else if (a === '--seam') o.seam = true;
@@ -118,6 +124,7 @@ export function parseArgs(argv) {
     else throw new Error(`unexpected argument ${a}`);
   }
   if (o.crop && !o.at) throw new Error('--crop crops the pictures of --at: give --at too (for example --at 3.5 --crop 100,200,400,300)');
+  if (o.pick.length && !o.at) throw new Error('--pick asks about the moments of --at: give --at too (for example --at 3.5 --pick 640,360)');
   return o;
 }
 
@@ -435,7 +442,7 @@ export async function runCheck(opts, log = console.log) {
     const layoutProblems = rv.problems.filter(g => g.kind !== 'canvas'), canvasProblems = rv.problems.filter(g => g.kind === 'canvas');
     report.inspect = { checkedFrames: rv.frames, issues: layoutProblems, review: rv.review, canvas: canvasProblems.map(g => g.message), canvasLayers: rv.canvas ?? [] };
     if (layoutProblems.length) report.problems.push(`${layoutProblems.length} kind(s) of layout issue from movie.inspect`);
-    if (canvasProblems.length) report.problems.push(`${canvasProblems.length} canvas layer(s) that do not draw the same picture for the same time (movie.canvasProblems)`);
+    if (canvasProblems.length) report.problems.push(`${canvasProblems.length} layer(s) (canvas / three) that do not draw the same picture for the same time (movie.canvasProblems)`);
     // fonts: a web font whose file did not load is a problem (the library lists a layer with no available font for review)
     report.fonts = rv.fonts;
     if (rv.fonts.failed.length) report.problems.push(`${rv.fonts.failed.length} web font(s) failed to load: ${rv.fonts.failed.join(', ')} (the layers that use them are drawn in a fallback)`);
@@ -466,6 +473,10 @@ 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);
+        // pick: what is under each --pick point at this moment (the frame is on screen after the snapshot above)
+        if (opts.pick.length) {
+          w.pick = await cdp.eval(`(${JSON.stringify(opts.pick)}).map(p => ({ x: p.x, y: p.y, hits: movie.pickAll(p.x, p.y).map(h => ({ name: h.name ?? h.path, path: h.path, kind: h.kind, object: h.three ? h.three.object : undefined })) }))`).catch(() => []);
+        }
         // 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);
@@ -682,11 +693,13 @@ function finish(report, outDir, log) {
     if (g.length > 8) L.push(`            … ${g.length - 8} more (report.json)`);
     const cv = report.inspect.canvas ?? [];
     const rows = report.inspect.canvasLayers ?? [];
-    if (cv.length) { L.push(`  canvas    ${cv.length} canvas layer(s) that do not draw the same picture for the same time:`); for (const m of cv.slice(0, 4)) L.push(`            - ${m}`); }
-    if (rows.length) {                                              // silence must not be the only sign that the check ran
-      const good = rows.filter(r => r.ok), slow = [...rows].sort((a, b) => b.drawMs - a.drawMs)[0];
+    if (cv.length) { L.push(`  canvas    ${cv.length} layer(s) (canvas / three) that do not draw the same picture for the same time:`); for (const m of cv.slice(0, 4)) L.push(`            - ${m}`); }
+    for (const kind of ['canvas', 'three']) {                       // silence must not be the only sign that the check ran
+      const mine = rows.filter(r => (r.kind ?? 'canvas') === kind);
+      if (!mine.length) continue;
+      const good = mine.filter(r => r.ok), slow = [...mine].sort((a, b) => b.drawMs - a.drawMs)[0];
       const ms = x => x < 10 ? x.toFixed(1) : String(Math.round(x));
-      if (good.length) L.push(`  canvas    ${cv.length ? 'the other ' : ''}${good.length} canvas layer(s) drew the same picture twice at ${good[0].moments.length} moments (two orders): deterministic · slowest draw ${ms(slow.drawMs)} ms on the CPU (${slow.name})`);
+      if (good.length) L.push(`  ${kind.padEnd(9)} ${cv.length ? 'the other ' : ''}${good.length} ${kind} layer(s) drew the same picture twice at ${good[0].moments.length} moments (two orders): deterministic · slowest draw ${ms(slow.drawMs)} ms${kind === 'canvas' ? ' on the CPU' : ''} (${slow.name})`);
     }
     const rv = report.inspect.review;
     if (rv.length) {
@@ -700,6 +713,12 @@ function finish(report, outDir, log) {
     L.push(`  sizes     ${g.map(x => `${x.size} ${x.issues.length ? x.issues.length + ' layout issue kind(s)' : 'no layout issue'}`).join(' · ')}${g.length > 1 ? ' (one contact sheet each: sheet.png, sheet-<size>.png)' : ''}`);
     for (const x of g) for (const i of x.issues.slice(0, 3)) L.push(`            - ${x.size}: ${i.message}`);
   }
+  for (const w of (report.at ?? []).filter(x => x.pick)) {
+    for (const p of w.pick) {
+      const says = p.hits.length ? p.hits.map(h => h.kind === 'three' ? `${h.name} (three: ${h.object || '?'})` : h.name).join(', ') : 'nothing';
+      L.push(`  pick      ${w.label} (${p.x}, ${p.y}) — ${says}`);
+    }
+  }
   for (const w of (report.at ?? []).filter(x => x.depthBlur)) {
     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)`);

package/ai/tools/gltfProbe.mjs

@@ -0,0 +1,122 @@
+/**
+ * `pixi-effects probe model.glb` — what is in a glTF model, read in Node with no browser and no three.js: the clips (name and length), the size of the model in the file's own units
+ * (the bounding box of the meshes through the transforms of the nodes: the pose the file is stored in, which is what `threeGltf(...).size` measures), what it holds, and the notes an
+ * author trips on (a file that needs a decoder, a model with no clip).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const GLB_MAGIC = 0x46546c67, JSON_CHUNK = 0x4e4f534a;
+const round = (v, d = 3) => Math.round(v * 10 ** d) / 10 ** d;
+export const isGltfFile = (file) => /\.(glb|gltf)(\?.*)?$/i.test(file);
+const isUrl = (f) => /^https?:\/\//i.test(f);
+
+/** The JSON of a .glb (its first chunk) or a .gltf. */
+function parseJson(file, buf) {
+  const name = isUrl(file) ? file : path.basename(file);
+  if (buf.length >= 12 && buf.readUInt32LE(0) === GLB_MAGIC) {
+    const version = buf.readUInt32LE(4);
+    if (version !== 2) throw new Error(`${name}: glTF version ${version} (only 2.0 is read)`);
+    let at = 12;
+    while (at + 8 <= buf.length) {
+      const len = buf.readUInt32LE(at), type = buf.readUInt32LE(at + 4);
+      if (type === JSON_CHUNK) return { json: JSON.parse(buf.subarray(at + 8, at + 8 + len).toString('utf8')), container: 'glb' };
+      at += 8 + len + ((4 - (len % 4)) % 4);
+    }
+    throw new Error(`${name}: a .glb with no JSON chunk`);
+  }
+  try { return { json: JSON.parse(buf.toString('utf8')), container: 'gltf' }; }
+  catch { throw new Error(`${name} is not a glTF model (it is neither a .glb, which starts with "glTF", nor glTF JSON)`); }
+}
+
+// 4x4 matrices, column-major as glTF stores them.
+const identity = () => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const multiply = (a, b) => { const o = new Array(16).fill(0); for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) for (let k = 0; k < 4; k++) o[c * 4 + r] += a[k * 4 + r] * b[c * 4 + k]; return o; };
+function local(node) {
+  if (node.matrix?.length === 16) return node.matrix;
+  const [tx, ty, tz] = node.translation ?? [0, 0, 0], [x, y, z, w] = node.rotation ?? [0, 0, 0, 1], [sx, sy, sz] = node.scale ?? [1, 1, 1];
+  return [
+    (1 - 2 * (y * y + z * z)) * sx, 2 * (x * y + z * w) * sx, 2 * (x * z - y * w) * sx, 0,
+    2 * (x * y - z * w) * sy, (1 - 2 * (x * x + z * z)) * sy, 2 * (y * z + x * w) * sy, 0,
+    2 * (x * z + y * w) * sz, 2 * (y * z - x * w) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
+    tx, ty, tz, 1,
+  ];
+}
+const apply = (m, [x, y, z]) => [m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14]];
+
+/** The report of a glTF JSON. */
+export function describeGltf(json, { file, bytes, container }) {
+  const nodes = json.nodes ?? [], meshes = json.meshes ?? [], accessors = json.accessors ?? [];
+  const notes = [];
+  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+  let measured = 0, unmeasured = 0;
+  const seen = new Set();
+  const visit = (i, parent) => {
+    if (seen.has(i) || !nodes[i]) return;                                 // a node reached twice is a broken file, not a reason to loop
+    seen.add(i);
+    const world = multiply(parent, local(nodes[i]));
+    const mesh = meshes[nodes[i].mesh];
+    for (const prim of mesh?.primitives ?? []) {
+      const acc = accessors[prim.attributes?.POSITION];
+      if (!acc?.min || !acc?.max) { unmeasured++; continue; }
+      measured++;
+      for (const x of [acc.min[0], acc.max[0]]) for (const y of [acc.min[1], acc.max[1]]) for (const z of [acc.min[2], acc.max[2]]) {
+        const p = apply(world, [x, y, z]);
+        for (let k = 0; k < 3; k++) { if (p[k] < lo[k]) lo[k] = p[k]; if (p[k] > hi[k]) hi[k] = p[k]; }
+      }
+    }
+    for (const c of nodes[i].children ?? []) visit(c, world);
+  };
+  const scene = json.scenes?.[json.scene ?? 0];
+  const roots = scene?.nodes ?? nodes.map((_, i) => i).filter((i) => !nodes.some((n) => n.children?.includes(i)));
+  for (const r of roots) visit(r, identity());
+  const size = measured ? [0, 1, 2].map((k) => hi[k] - lo[k]) : null;
+  if (!size) notes.push('the size of the model could not be read (its position accessors have no min / max)');
+  else if (unmeasured) notes.push(`${unmeasured} mesh part(s) have no position min / max: the size leaves them out`);
+
+  const animations = (json.animations ?? []).map((a, index) => {
+    let duration = 0;
+    for (const s of a.samplers ?? []) { const t = accessors[s.input]; if (t?.max?.[0] > duration) duration = t.max[0]; }
+    return { index, name: a.name ?? `(unnamed ${index})`, duration: round(duration) };
+  });
+  if (!animations.length) notes.push('no animation: threeGltf poses nothing; the model stays in the pose it is stored in');
+  const required = json.extensionsRequired ?? [];
+  const decoders = required.filter((e) => /draco|meshopt|basisu|ktx2|webp/i.test(e));
+  if (decoders.length) notes.push(`needs ${decoders.join(', ')}: three's GLTFLoader needs a decoder for it (DRACOLoader / KTX2Loader / MeshoptDecoder), and threeGltf does not set one up: re-export the model without that compression, or load it yourself`);
+  const external = [...(json.buffers ?? []), ...(json.images ?? [])].filter((x) => x.uri && !/^data:/i.test(x.uri));
+  if (external.length) notes.push(`${external.length} file(s) are loaded next to the model (${external.slice(0, 3).map((x) => x.uri).join(', ')}${external.length > 3 ? ', …' : ''}): keep them beside it`);
+  return {
+    file, container: `glTF ${json.asset?.version ?? '2.0'} (${container})`, bytes,
+    counts: { nodes: nodes.length, meshes: meshes.length, skins: (json.skins ?? []).length, materials: (json.materials ?? []).length, textures: (json.textures ?? []).length },
+    size: size ? size.map((v) => round(v, 6)) : null, longest: size ? round(Math.max(...size), 6) : null,
+    animations, extensions: json.extensionsUsed ?? [], notes,
+  };
+}
+
+/** Read a local file or a URL and describe it. */
+export async function probeGltf(file) {
+  let buf;
+  if (isUrl(file)) {
+    const res = await fetch(file);
+    if (!res.ok) throw new Error(`could not read ${file}: HTTP ${res.status}`);
+    buf = Buffer.from(await res.arrayBuffer());
+  } else {
+    if (!fs.existsSync(file)) throw new Error(`${file}: no such file`);
+    buf = fs.readFileSync(file);
+  }
+  const { json, container } = parseJson(file, buf);
+  return describeGltf(json, { file, bytes: isUrl(file) ? null : buf.length, container });
+}
+
+const num = (v) => String(round(v, 3));
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+export function gltfText(r) {
+  const kb = (n) => (n >= 1048576 ? `${(n / 1048576).toFixed(2)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`);
+  const L = [r.file, `  ${r.container}${r.bytes != null ? ` · ${kb(r.bytes)}` : ''}`];
+  const c = r.counts;
+  L.push(`  model  ${plural(c.nodes, 'node')} · ${plural(c.meshes, 'mesh').replace('meshs', 'meshes')} · ${plural(c.skins, 'skin')} · ${plural(c.materials, 'material')} · ${plural(c.textures, 'texture')}`);
+  if (r.size) L.push(`  size   ${r.size.map(num).join(' × ')}  (x × y × z in the file's units, as stored: the longest side is ${num(r.longest)}; threeGltf's fit(px) scales that side to px)`);
+  for (const a of r.animations) L.push(`  clip   ${a.index} "${a.name}" ${num(a.duration)} s`);
+  for (const n of r.notes) L.push(`  note   ${n}`);
+  return L.join('\n');
+}

package/ai/tools/media.mjs

@@ -2,7 +2,7 @@
 /**
  * pixi-effects probe | trim | frames | sound — look at, listen to and cut footage, with no ffmpeg installed.
  *
- *   npx pixi-effects probe  <file|url> [--keyframes] [--json]            what is in a file: container, duration, tracks, codecs, size, notes
+ *   npx pixi-effects probe  <file|url> [--keyframes] [--json]            what is in a file: container, duration, tracks, codecs, size, notes (a .glb / .gltf model: clips and size)
  *   npx pixi-effects trim   <file|url> <start> <end> -o <out> [--exact] [--force] [--json]
  *                                                                        cut [start, end] (seconds, or 1:02.5): by COPY when it can (no re-encode, no loss),
  *                                                                        and it says the real times; --exact re-encodes so the start is the frame asked for
@@ -22,6 +22,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { gltfText, isGltfFile, probeGltf } from './gltfProbe.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(HERE, '../..');
@@ -314,6 +315,12 @@ export function checkExpect(report, items) {
 function bitrateWanted(op, raw) { const n = expectNumber('bitrate', raw); return `${op}${Math.round(n / 1e5) / 10} Mbps`; }
 
 commands.probe = async ({ file, opts }, io) => {
+  if (isGltfFile(file)) {                                                                        // a model, not footage: read in Node, no container library, no browser
+    if (opts.expect !== undefined || opts.keyframes) throw new UsageError('probe on a glTF model takes no --expect or --keyframes (they are for video and audio files); it prints the clips and the size');
+    const r = await probeGltf(file);
+    io.log(opts.json ? JSON.stringify(r, null, 2) : gltfText(r));
+    return 0;
+  }
   const items = opts.expect !== undefined ? parseExpect(opts.expect) : null;                      // a bad expectation is a usage error before any file is read
   const r = await probeFile(file, { keyframes: !!opts.keyframes, exact: !!items });
   const results = items ? checkExpect(r, items) : null;

package/ai/tools/pixi-effects.mjs

@@ -22,7 +22,7 @@ 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
-  pixi-effects probe  <file|url>                            what is in a video or audio file (codecs, size, duration), with no ffmpeg
+  pixi-effects probe  <file|url>                            what is in a video or audio file (codecs, size, duration), with no ffmpeg; or a .glb / .gltf model (its clips and its size)
   pixi-effects trim   <file|url> <start> <end> -o <out>     cut a file (by copy when it can) and say the real times
   pixi-effects frames <file|url> [--at 1,50%,end] [--sheet] pictures of a video at those times
   pixi-effects sound  <file|url> [--waveform]               loudness, peak, silences of a file's sound

package/dist/{Base-BKKwxavW.d.cts → Base-DQWIJ6bJ.d.cts}

@@ -1,5 +1,5 @@
 import { Container } from 'pixi.js';
-import { a as SequenceSpec, C as CompositionShape } from './types-BXi-0iZS.cjs';
+import { S as SequenceSpec, C as CompositionShape } from './types-DIh93lFb.cjs';
 
 /**
  * Resolves a routed keyframe path to a concrete tween target.

package/dist/{Base-ioh_AjLB.d.ts → Base-Jgkud1Aw.d.ts}

@@ -1,5 +1,5 @@
 import { Container } from 'pixi.js';
-import { a as SequenceSpec, C as CompositionShape } from './types-BXi-0iZS.js';
+import { S as SequenceSpec, C as CompositionShape } from './types-DIh93lFb.js';
 
 /**
  * Resolves a routed keyframe path to a concrete tween target.

package/dist/Composition-N6BOROJ2.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunk3HZV3UHU_cjs = require('./chunk-3HZV3UHU.cjs');
+require('./chunk-X62H3RBG.cjs');
+require('./chunk-JN7JHNZR.cjs');
+require('./chunk-3SAS3ZE5.cjs');
+require('./chunk-TWZNOUM7.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunk3HZV3UHU_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-N6BOROJ2.cjs.map
+//# sourceMappingURL=Composition-N6BOROJ2.cjs.map

package/dist/{Composition-3MNLNT2E.cjs.map → Composition-N6BOROJ2.cjs.map}

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

package/dist/Composition-YGBQX3HZ.js

@@ -0,0 +1,7 @@
+export { CompositionSequence } from './chunk-ICI6ACHY.js';
+import './chunk-4QVQ5UJJ.js';
+import './chunk-VNP7QCJE.js';
+import './chunk-32MMNDDN.js';
+import './chunk-BXOCEZ4U.js';
+//# sourceMappingURL=Composition-YGBQX3HZ.js.map
+//# sourceMappingURL=Composition-YGBQX3HZ.js.map

package/dist/{Composition-P37AD4GN.js.map → Composition-YGBQX3HZ.js.map}

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

package/dist/Controller.d.cts

@@ -1,7 +1,7 @@
-import { M as Movie } from './Movie-CSWUTnMd.cjs';
+import { M as Movie } from './Movie-DWtxRiJ2.cjs';
 import 'pixi.js';
 import './soundEntry-DT13DNt8.cjs';
-import './types-BXi-0iZS.cjs';
+import './types-DIh93lFb.cjs';
 
 /**
  * The look of the bar. Each key sets a CSS custom property on the bar (so you can also set `--mc-accent` … in your own CSS, on the

package/dist/Controller.d.ts

@@ -1,7 +1,7 @@
-import { M as Movie } from './Movie-BtwFI2ne.js';
+import { M as Movie } from './Movie-CwqRLOzE.js';
 import 'pixi.js';
 import './soundEntry-DT13DNt8.js';
-import './types-BXi-0iZS.js';
+import './types-DIh93lFb.js';
 
 /**
  * The look of the bar. Each key sets a CSS custom property on the bar (so you can also set `--mc-accent` … in your own CSS, on the

package/dist/{Movie-BtwFI2ne.d.ts → Movie-CwqRLOzE.d.ts}

@@ -1,6 +1,6 @@
 import { Application } from 'pixi.js';
 import { A as AudioReport, a as AudioInspectOptions } from './soundEntry-DT13DNt8.js';
-import { d as Stop, A as AssetSpec, c as CompositionSpec } from './types-BXi-0iZS.js';
+import { b as Stop, A as AssetSpec, a as CompositionSpec } from './types-DIh93lFb.js';
 
 type EaseFn = (p: number) => number;
 
@@ -149,6 +149,8 @@ interface CanvasRow {
     ok: boolean;
     /** Why not, in a sentence (empty when ok). */
     problem: string;
+    /** Which kind of layer drew it: a `canvas` layer or a `three` layer (both are held to "a function of the time"). */
+    kind: 'canvas' | 'three';
 }
 
 /** One kind of issue, with how many frames it was seen in. Issues that differ only by numbers are one kind. */
@@ -208,6 +210,9 @@ interface LayerInfo {
     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;
+    /** A `three` layer: the renderer it draws with (`'webgl'` / `'webgpu'`) and the backend under it (`'webgl2'`: three's WebGPURenderer found no WebGPU and used its own WebGL2 backend: the same picture). */
+    renderer?: 'webgl' | 'webgpu';
+    backend?: 'webgl' | 'webgpu' | 'webgl2';
 }
 interface InspectReport {
     frame: number;
@@ -230,6 +235,39 @@ interface InspectOptions {
     layers?: 'all' | 'visible' | 'none';
 }
 
+interface PickHit {
+    /** The layer's `name` (when it has one). */
+    name?: string;
+    /** Names (or `type#index`) from the root, joined by `/`: the same as `movie.inspect()`'s `path`. */
+    path: string;
+    type: string;
+    /** `'flat'`: a 2D layer; `'card'`: a `threeD` layer (its projected card); `'three'`: a `three` layer, and `three` says what the ray met. */
+    kind: 'flat' | 'card' | 'three';
+    /** The point asked about, in canvas pixels. */
+    point: {
+        x: number;
+        y: number;
+    };
+    /** A flat layer: the point in the layer's own pixels (the top-left of its picture is 0, 0). */
+    local?: {
+        x: number;
+        y: number;
+    };
+    /** A `three` layer: what the ray through that point met first: the object (its name, or `''`), where (three's own units), and how far from the camera. */
+    three?: {
+        object: unknown;
+        point: [number, number, number];
+        distance: number;
+        object3d?: unknown;
+    };
+}
+interface PickOptions {
+    /** Only these layers can be hit (by `name` or by `path`). */
+    only?: string[];
+    /** These layers cannot be hit (by `name` or by `path`). */
+    ignore?: string[];
+}
+
 /** One layer (or a run of similar layers) on the timeline. Times are in seconds, absolute (from the start of the movie). */
 interface TimelineRow {
     /** `parent/child` for a layer inside a composition. */
@@ -673,6 +711,19 @@ declare class Movie {
      * Where every layer is drawn at `frame` (canvas pixels, visibility) plus `issues` — text that is off
      * the canvas, cut by an edge, empty, or overlapping other text. Seeks there and stays there.
      */
+    /**
+     * What is under the canvas point (x, y) (canvas pixels: the movie's own `width` x `height`; `canvasPoint(event)` makes them from a pointer event) at the frame on screen: the layer on
+     * top, or null. A flat layer is hit by its own shape, a `threeD` card by its projected quad, a `three` layer by a ray through its camera (`hit.three` has the object). It reads the
+     * frame as the last draw left it, so after `await movie.snapshot(frame)` or any seek it answers for that frame. `opts.only` / `opts.ignore`: layer names or paths.
+     */
+    pick(x: number, y: number, opts?: PickOptions): PickHit | null;
+    /** Every layer under the canvas point, the one on top first (see `pick`). */
+    pickAll(x: number, y: number, opts?: PickOptions): PickHit[];
+    /** A pointer event's place in canvas pixels (the canvas may be shown larger or smaller than its own size): `movie.pick(...movie.canvasPoint(event))`. */
+    canvasPoint(event: {
+        clientX: number;
+        clientY: number;
+    }): [number, number];
     inspect(frame?: number, opts?: InspectOptions): Promise<InspectReport>;
     /** The canvas layers whose same frame is not the same picture (what `check` reports as a problem): one sentence each. */
     canvasProblems(): string[];
@@ -763,4 +814,4 @@ declare class Movie {
     destroy(): Promise<void>;
 }
 
-export { type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type ProgressEvent as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type RebuildReason as l, type RebuildReport as m, type RenderOptions as n, type ReviewOptions as o, type ReviewReport as p, type TimelineData as q, type TimelineHtmlOptions as r, type TimelineRow as s, type TimelineSvgOptions as t, type TimelineTransition as u, dismissLoader as v, failLoader as w, resolveLoader as x };
+export { type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type PickHit as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type PickOptions as l, type ProgressEvent as m, type RebuildReason as n, type RebuildReport as o, type RenderOptions as p, type ReviewOptions as q, type ReviewReport as r, type TimelineData as s, type TimelineHtmlOptions as t, type TimelineRow as u, type TimelineSvgOptions as v, type TimelineTransition as w, dismissLoader as x, failLoader as y, resolveLoader as z };