pixi-effects 0.28.2 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.29.0
+
+**Changed (breaking): presentation leaves the core**
+
+The talk side of the library is now its own entry, `pixi-effects/present`, built on the core's public API only (a test enforces the import rule). The core keeps `composition.stops` (named times, `movie.stops`) and gains two general moves; everything else that was about a talk moved out.
+
+| before | now |
+|---|---|
+| `movie.next()` `prev()` `goToStop(i)` `goToPage(n)` | `next(movie)` `prev(movie)` `goToStop(movie, i)` `goToPage(movie, n)` from `pixi-effects/present` |
+| `movie.stopIndex` `pageIndex` `pageCount` `currentStop` | `stopIndex(movie)` `pageIndex(movie)` `pageCount(movie)` `currentStop(movie)` |
+| `movie.on('stop', fn)` | `const off = onStop(movie, fn)` |
+| `movie.stopImages(o)` `movie.inspectStops(o)` `movie.exportPDF(o)` | `stopImages(movie, o)` `inspectStops(movie, o)` `exportPDF(movie, o)` |
+| `import { deck } from 'pixi-effects'` | `import { deck } from 'pixi-effects/present'` |
+| `import { Presenter } from 'pixi-effects/presenter'` (`dist/Presenter.js`) | `import { Presenter } from 'pixi-effects/present'` (`dist/present.js`; the import map line is `"pixi-effects/present"`) |
+| `normalizeStops`, `pictureStops` exported from `pixi-effects` | not exported (the core normalises `composition.stops` itself; `pictureStops` is inside `pixi-effects/present`) |
+| the types `StopEvent`, `StopImage`, `StopImagesOptions` from `pixi-effects` | the same names from `pixi-effects/present` (`Stop` and `StopSpec` stay in `pixi-effects`) |
+
+A page that only maps `"pixi-effects"` still gets its stops reviewed and its PDF exported by `check` / `render`: they load `present.js` from beside the library.
+
+**Changed (breaking): the API list for 0.29** (`docs/api-surface.txt` is the whole public surface, read from the sources and frozen by a test; the decisions are in `docs/superpowers/specs/2026-10-11-api-list-0.29.md`)
+
+| before | now |
+|---|---|
+| `maskInverted: true` next to `mask: { …a layer… }` | `mask: { layer: { …the mask layer… }, invert: true }` (the one inverted-mask form, the same as `{ layer: 'name', invert: true }` for a named matte; `channel: 'luma'` works on a layer written in place too). The old key warns and says this. Inside a list of masks only names are allowed |
+| `Controller` options `enableKeyboardShortcuts`, `showExportButton`, `present` | `keyboard`, `exportButton`, `presentButton` (the Presenter's names). An unknown `Controller` option now warns, with did-you-mean |
+| `pixi-effects/controller` also exported `CONTROLLER_CSS`, `formatTime`, `frameToPercent`, `pxToFrame`, `pxToFraction`, `extensionForMimeType` | `Controller`, `ControllerOptions`, `ControllerTheme` only |
+| the bins `pixi-effects-check`, `pixi-effects-render`, `pixi-effects-view` | `pixi-effects check|render|view` (the one bin; `npx pixi-effects-check` never worked) |
+| `pixi-effects render --fail-on-warn` | `--strict`, the word `check` already used (the old flag says so) |
+| `Movie.emit`, `audioSource`, `gainNode`; `Sequence.bindTimeline`, `collectAudio`, `absoluteStart`, `keepHidden`, `maskSequence`, `filters`, `updateSpace`, `syncFrame` in the type declarations | marked `@internal` and stripped from the declarations (the library still uses them) |
+
+**Added**
+
+- `movie.playUntil(seconds?)`: play and pause exactly at a time (`true` when it landed; `false` when a pause, a seek or a newer `playUntil` ended it first; no time = to the end). It is what `next(movie)` is made of, and the way to "play the intro, then wait".
+- `movie.peek(fn)`: run a function that looks around (seeks, pictures) and put the playhead or the poster back; the seeks inside are not reported as `seeking` / `seeked`.
+- `movie.snapshot(frame, { quality })` (JPEG quality) and `{ as: 'imageData' }` (the pixels, to measure or compare).
+- `warnUnknownOptions(where, options, validNames)` is exported: the did-you-mean warning for an unknown option, for presets and layer types written outside the library.
+- `animateText({ out: { preset, at: T } })`: the exit starts at composition second T (the pieces leave in the same wave and stay gone until the layer ends). Without `at` it is the end of the layer run backwards, as before; a warning says `out.at ≤ …` when the exit does not fit, or when T is before the entrance has finished.
+- `pixi-effects render --help` and `pixi-effects view --help` (usage, exit 0), like `check`.
+- A warning when a picture key (`filters`, `filterArea`, `mask`, `blendMode`, `threeD`, `hideBehindCamera`, `lit`, `castsShadows`) is put on a layer that is never drawn: an audio layer, a camera, a light (a light keeps `castsShadows`, its own switch). The key did nothing there, silently.
+
+**Fixed**
+
+- `NamedFilterType` lacked `'warp'`: `{ type: 'warp' }` was a TypeScript error though it worked at run time. The compiler now checks the type and the runtime filter tables against each other, both ways.
+
+**Checked, not reproduced**
+
+- The two bugs the old roadmap listed (an inline shape mask under a transition; a 4000 x 2400 `threeD` layer black on WebGPU) do not reproduce on this code. Real-browser tests pin both, on both backends.
+
+**Docs**
+
+- **The film guide says who it is for.** `direction.md` opens with a note for an AI in a browser chat (no shell, no files): this guide is not yours, follow `ai/CHAT.md`; you can still put a three-line plan in your reply and ask. The `llms.txt` line for it says "for an AI with a shell and files; a browser chat skips it".
+
 ## 0.28.2
 
 **Added**

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.28.2`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.29.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.
 
@@ -21,14 +21,14 @@ 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/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).
+- **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).
 - **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`).
 - **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.
+- **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.
 - **Tiny dependency surface** — only `mediabunny` (runtime) plus PixiJS (a peer dep). three.js is an *optional* peer, needed only if you import `pixi-effects/three`.
 
 ## Install
@@ -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.28.2/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.2/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.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.28.2/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.29.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.
 >
@@ -77,7 +77,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.28.2/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/three.js"
   }
 }
 </script>
@@ -175,7 +175,7 @@ This library is designed to be written by AI: a video is plain data, and every m
 - [`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` (it also watches the folder: when the work changes it shows "Updated hh:mm:ss — reload (R)" and never switches by itself; reload comes back to the same frame) (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.
+- **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), `--strict` (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.
 
@@ -184,7 +184,7 @@ They ship in the npm package (`node_modules/pixi-effects/ai/`).
 ## Documentation
 
 - [**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/presenter`, `pixi-effects/three`, events, render options
+- [**API reference**](./docs/api.md) — `Movie`, `Controller`, `pixi-effects/present`, `pixi-effects/three`, events, render options
 - [**Examples**](./examples/) — runnable HTML files (read in order):
   - `01-hello.html` — minimum viable composition
   - `02-keyframes.html` — keyframes, easings, expressions

package/ai/chat-template.html

@@ -59,17 +59,17 @@
     "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.28.2/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.2/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.2/dist/Presenter.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/present.js"
     }
   }
   </script>
 
   <script type="module">
-    import { Movie, kenBurns, withFade, wiggle, stagger, animateText, followPath, particles, deck } from 'pixi-effects';
+    import { Movie, kenBurns, withFade, wiggle, stagger, animateText, followPath, particles } from 'pixi-effects';
     import { Controller } from 'pixi-effects/controller';
-    // A talk instead of a video: import { Presenter } from 'pixi-effects/presenter'; use deck({ pages: [...] }) and new Presenter(movie, { canvas }) instead of the Controller.
+    // A talk instead of a video: import { deck, Presenter } from 'pixi-effects/present'; use deck({ pages: [...] }) and new Presenter(movie, { canvas }) instead of the Controller.
 
     // ===================== EDIT FROM HERE =====================
     const W = 1280, H = 720, FPS = 30, DURATION = 6;

package/ai/tools/check.mjs

@@ -286,6 +286,18 @@ const waveformScript = (audio, duration) => `(() => {
 // ───────────────────────────── the check ─────────────────────────────
 
 export const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * JavaScript, as text, for the page: it resolves to the page's own `pixi-effects/present` module (stops, pages, PDF). The page's import map names it
+ * (`pixi-effects/present`); a page that only maps `pixi-effects` gets the `present.js` that sits beside the library.
+ */
+export const LOAD_PRESENT = `(async () => {
+  try { return await import('pixi-effects/present'); } catch (e) { /* not in the import map: look beside the library */ }
+  let lib = null;
+  try { lib = JSON.parse(document.querySelector('script[type="importmap"]').textContent).imports['pixi-effects']; } catch (e) { /* none */ }
+  if (!lib) throw new Error('the page has no "pixi-effects" in its import map');
+  return import(new URL('present.js', new URL(lib, document.baseURI)).href);
+})()`;
 /** A path for display: relative to the cwd when it is inside it, absolute otherwise. */
 export const shown = f => { const r = path.relative(process.cwd(), f); return r.startsWith('..') || path.isAbsolute(r) ? f : r; };
 const kb = n => (n >= 1048576 ? `${(n / 1048576).toFixed(2)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`);
@@ -404,11 +416,13 @@ export async function runCheck(opts, log = console.log) {
     }
 
     // a presentation (composition.stops): one picture of every stop, in order, so the pages and steps can be read at a glance
-    const stops = await cdp.eval(`(() => { const s = movie.stops || []; return s.length ? { count: s.length, pages: movie.pageCount, items: s.map(x => ({ at: Math.round(x.at * 100) / 100, frame: x.frame, page: x.page, pageStart: x.pageStart, notes: !!x.notes, pdf: x.pdf })) } : null; })()`).catch(() => null);
+    const stops = await cdp.eval(`(() => { const s = movie.stops || []; return s.length ? { count: s.length, pages: new Set(s.map(x => x.pageIndex)).size, items: s.map(x => ({ at: Math.round(x.at * 100) / 100, frame: x.frame, page: x.page, pageStart: x.pageStart, notes: !!x.notes, pdf: x.pdf })) } : null; })()`).catch(() => null);
     if (stops) {
       report.stops = stops;
       // is the picture at each stop still changing? (the audience, the page overview and a PDF would see a half-finished animation)
-      const settled = await cdp.eval('movie.inspectStops()').catch(() => null);
+      let skipped = '';
+      const settled = await cdp.eval(`${LOAD_PRESENT}.then(p => p.inspectStops(movie))`).catch(e => { skipped = String((e && e.message) || e); return null; });
+      if (!settled) report.stops.reviewSkipped = `${skipped || 'no answer'} (the page needs "pixi-effects/present": ".../dist/present.js" in its import map, from the same version as the library)`;
       if (settled) {
         report.stops.review = settled.issues;
         report.stops.moving = settled.stops.map(s => Math.round(s.moving * 10000) / 10000);
@@ -529,7 +543,8 @@ function finish(report, outDir, log) {
   }
   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`);
+    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`)
+    if (s.reviewSkipped) L.push(`            not reviewed for stops that are still moving: ${s.reviewSkipped}`);
     if (s.review?.length) {
       L.push(`  review    ${s.review.length} stop(s) where the picture is still changing (may be on purpose, e.g. something always moving; use --strict to fail on them):`);
       for (const r of s.review.slice(0, 4)) L.push(`            - ${r}`);

package/ai/tools/pixi-effects.mjs

@@ -7,7 +7,7 @@
  *   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.
+ * exit code and the output. It is the package's only bin (the older `pixi-effects-check|render|view` are gone).
  */
 import { spawn } from 'node:child_process';
 import { realpathSync } from 'node:fs';

package/ai/tools/render.mjs

@@ -6,7 +6,7 @@
  *
  * It starts a private static server and a private headless Chrome, opens the page, waits for `window.__ready === true`
  * (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).
+ * 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.
  * Exit code: 0 = the file was written, 1 = the page or the render failed (no file), 2 = bad usage.
@@ -17,7 +17,7 @@
  *          --draft (for looking: half size, low quality, no motion blur; a --quality you give still wins) ·
  *          --motion-blur SAMPLES (2-64: each frame is drawn that many times over the shutter and averaged; overrides the page's own motionBlur) ·
  *          --shutter FRACTION (with --motion-blur: how long the shutter is open, 0-1 of a frame, default 0.5) ·
- *          --video-codec C (avc hevc vp9 av1 vp8) · --video-bitrate B (a quality or bits a second: 8M, 800k) · --audio-codec C · --query "a=1&b=2" (added to the page URL) · --fail-on-warn (exit 1 when the page
+ *          --video-codec C (avc hevc vp9 av1 vp8) · --video-bitrate B (a quality or bits a second: 8M, 800k) · --audio-codec C · --query "a=1&b=2" (added to the page URL) · --strict (exit 1 when the page
  *          logged a warning; the file is still written) · --quiet (no progress line) · --timeout SECONDS (default 900) ·
  *          --root DIR (static server root; default: the nearest folder above the page with dist/) · --chrome PATH
  */
@@ -25,7 +25,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { findChrome, findRoot, serve, launchChrome, shown, sleep } from './check.mjs';
+import { findChrome, findRoot, serve, launchChrome, shown, sleep, LOAD_PRESENT } from './check.mjs';
 
 const FORMATS = ['mp4', 'webm', 'mov', 'mkv', 'wav', 'ogg', 'pdf'];
 const SOUND_ONLY = ['wav', 'ogg'];
@@ -43,12 +43,15 @@ export function defaultOutput(page, format) {
   return path.resolve(path.basename(page).replace(/\.[^.]+$/, '') + '.' + format);
 }
 
+export const USAGE = 'usage: node ai/tools/render.mjs <page.html> [-o out.mp4] [--format mp4|webm|mov|mkv|pdf] [--range A:B | --scene NAME] [--scale S] [--draft] [--quality very-low|low|medium|high|very-high] [--query a=1] [--strict] [--quiet] [--timeout S] [--root DIR] [--chrome PATH]';
+
 export function parseRenderArgs(argv) {
-  const o = { range: null, scene: null, scale: null, draft: false, qualityGiven: false, page: null, out: null, format: null, quality: 'high', videoCodec: null, videoBitrate: null, audioCodec: null, allStops: false, motionBlur: null, shutter: null, query: null, failOnWarn: false, quiet: false, timeout: 900, root: null, chrome: null };
+  const o = { range: null, scene: null, scale: null, draft: false, qualityGiven: false, page: null, out: null, format: null, quality: 'high', videoCodec: null, videoBitrate: null, audioCodec: null, allStops: false, motionBlur: null, shutter: null, query: null, strict: false, quiet: false, timeout: 900, root: null, chrome: null };
   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];
-    if (a === '-o' || a === '--out') o.out = need(i++, a);
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '-o' || a === '--out') o.out = need(i++, a);
     else if (a === '--format') {
       o.format = need(i++, a).toLowerCase();
       if (!FORMATS.includes(o.format)) throw new Error(`--format must be mp4, webm, mov, mkv, wav, ogg or pdf (got "${o.format}")`);
@@ -79,7 +82,8 @@ export function parseRenderArgs(argv) {
     } else if (a === '--draft') o.draft = true;
     else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
     else if (a === '--all-stops') o.allStops = true;
-    else if (a === '--fail-on-warn') o.failOnWarn = true;
+    else if (a === '--strict') o.strict = true;
+    else if (a === '--fail-on-warn') throw new Error('--fail-on-warn is now --strict (the same word as in check: a warning, or anything it would only list, fails the run)');
     else if (a === '--quiet') o.quiet = true;
     else if (a === '--timeout') o.timeout = Math.max(10, Number(need(i++, a)) || 900);
     else if (a === '--root') o.root = need(i++, a);
@@ -109,7 +113,7 @@ const renderScript = (format, quality, videoCodec, audioCodec, motionBlur, shutt
       const video = { ${[videoBitrate ? `bitrate: ${JSON.stringify(/^\d+(\.\d+)?$/.test(videoBitrate) ? Number(videoBitrate) : videoBitrate)}` : part.draft && !part.qualityGiven ? null : `bitrate: ${JSON.stringify(quality)}`, videoCodec ? `codec: ${JSON.stringify(videoCodec)}` : null].filter(Boolean).join(', ')} };
       const audio = { bitrate: ${JSON.stringify(quality)}${audioCodec ? `, codec: ${JSON.stringify(audioCodec)}` : ''} };
       const blob = ${JSON.stringify(format)} === 'pdf'
-        ? await movie.exportPDF({ which: ${allStops ? "'stops'" : "'pages'"}, title: document.title })
+        ? await (${LOAD_PRESENT}).catch(e => { throw new Error('a PDF needs pixi-effects/present in the page (add "pixi-effects/present": ".../dist/present.js" to its import map, from the same version as the library): ' + ((e && e.message) || e)); }).then(p => p.exportPDF(movie, { which: ${allStops ? "'stops'" : "'pages'"}, title: document.title }))
         : await movie.render({ format: ${JSON.stringify(format)}, ${SOUND_ONLY.includes(format) ? '' : 'video, '}audio${part.range ? `, range: [${part.range[0] ?? 0}, ${part.range[1] ?? 'movie.duration'}]` : ''}${part.scene ? `, range: ${JSON.stringify(part.scene)}` : ''}${part.scale ? `, scale: ${part.scale}` : ''}${part.draft ? ', draft: true' : ''}${motionBlur ? `, motionBlur: { samples: ${motionBlur}${shutter ? `, shutter: ${shutter}` : ''} }` : ''} });
       const res = await fetch(${JSON.stringify(UPLOAD)}, { method: 'PUT', body: blob });
       if (!res.ok) throw new Error('could not hand the file to the command (' + res.status + ')');
@@ -209,8 +213,9 @@ if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process
   try {
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseRenderArgs(process.argv.slice(2));
+    if (opts.help) { console.log(USAGE); process.exit(0); }
     if (!opts.page) {
-      console.error('usage: node ai/tools/render.mjs <page.html> [-o out.mp4] [--format mp4|webm|mov|mkv|pdf] [--range A:B | --scene NAME] [--scale S] [--draft] [--quality very-low|low|medium|high|very-high] [--query a=1] [--fail-on-warn] [--quiet] [--timeout S] [--root DIR] [--chrome PATH]');
+      console.error(USAGE);
       process.exit(2);
     }
     let last = -1;
@@ -227,7 +232,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process
       process.exit(1);
     }
     console.log(`${shown(r.file)}  ${kb(r.bytes)} · ${r.duration} s · ${SOUND_ONLY.includes(opts.format) ? 'sound only' : `${r.width}×${r.height} @ ${r.frameRate} fps`} · ${opts.format} · rendered in ${r.seconds} s`);
-    process.exit(opts.failOnWarn && r.logs.length ? 1 : 0);
+    process.exit(opts.strict && r.logs.length ? 1 : 0);
   } catch (e) {
     console.error(`pixi-effects render failed: ${e.message}`);
     process.exit(2);

package/ai/tools/view.mjs

@@ -26,12 +26,15 @@ import { findRoot, serve } from './check.mjs';
 
 export const VIEWER = '/__viewer';
 
+export const USAGE = 'usage: node ai/tools/view.mjs <page.html> [--port N] [--no-open] [--query a=1] [--root DIR]';
+
 export function parseViewArgs(argv) {
   const o = { page: null, port: 0, open: true, query: null, root: null };
   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];
-    if (a === '--port') o.port = Math.max(0, Math.round(Number(need(i++, a))) || 0);
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--port') o.port = Math.max(0, Math.round(Number(need(i++, a))) || 0);
     else if (a === '--no-open') o.open = false;
     else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
     else if (a === '--root') o.root = need(i++, a);
@@ -343,8 +346,9 @@ export async function startViewer(opts) {
 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.help) { console.log(USAGE); process.exit(0); }
     if (!opts.page) {
-      console.error('usage: node ai/tools/view.mjs <page.html> [--port N] [--no-open] [--query a=1] [--root DIR]');
+      console.error(USAGE);
       process.exit(2);
     }
     const { url } = await startViewer(opts);

package/dist/Base-CB1_FPZD.d.cts

@@ -0,0 +1,60 @@
+import { Container } from 'pixi.js';
+import { S as SequenceSpec, C as CompositionShape } from './types-BzIB65Vk.cjs';
+
+/**
+ * Resolves a routed keyframe path to a concrete tween target.
+ * `path` is everything after the registered prefix + dot (for
+ * `three.cube.rotation.y` under prefix `three`, path = `cube.rotation.y`).
+ * Return null to skip the key (the router is expected to have warned).
+ */
+type PathRouter = (path: string) => {
+    target: object;
+    prop: string;
+} | null;
+type PathRouters = Record<string, PathRouter>;
+
+/** Variables available to expression evaluation. */
+interface Scope {
+    w: number;
+    h: number;
+    W: number;
+    H: number;
+    GW: number;
+    GH: number;
+    contain: number;
+    cover: number;
+    t: number;
+    d: number;
+    T: number;
+}
+
+declare abstract class Sequence {
+    spec: SequenceSpec;
+    parent: CompositionShape | null;
+    root: CompositionShape;
+    target: Container | null;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+    at: number;
+    duration: number | undefined;
+    constructor(spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape);
+    abstract build(): Promise<void>;
+    buildFilters(): void;
+    scope(): Scope;
+    /**
+     * Prefix routers contributed to the keyframe pipeline (e.g. `three.` in
+     * pixi-effects/three). Base sequences route nothing extra.
+     */
+    protected pathRouters(): PathRouters;
+    /**
+     * The `initial` and `keyframes` that go onto the display object. A layer whose `time` runs a clock (video, composition) takes `time`
+     * out of them: it is not a property of the display object.
+     */
+    protected displayProps(): {
+        initial: SequenceSpec['initial'];
+        keyframes: SequenceSpec['keyframes'];
+    };
+    destroy(): void;
+}
+
+export { type PathRouters as P, Sequence as S };

package/dist/Base-Ne74ztNl.d.ts

@@ -0,0 +1,60 @@
+import { Container } from 'pixi.js';
+import { S as SequenceSpec, C as CompositionShape } from './types-BzIB65Vk.js';
+
+/**
+ * Resolves a routed keyframe path to a concrete tween target.
+ * `path` is everything after the registered prefix + dot (for
+ * `three.cube.rotation.y` under prefix `three`, path = `cube.rotation.y`).
+ * Return null to skip the key (the router is expected to have warned).
+ */
+type PathRouter = (path: string) => {
+    target: object;
+    prop: string;
+} | null;
+type PathRouters = Record<string, PathRouter>;
+
+/** Variables available to expression evaluation. */
+interface Scope {
+    w: number;
+    h: number;
+    W: number;
+    H: number;
+    GW: number;
+    GH: number;
+    contain: number;
+    cover: number;
+    t: number;
+    d: number;
+    T: number;
+}
+
+declare abstract class Sequence {
+    spec: SequenceSpec;
+    parent: CompositionShape | null;
+    root: CompositionShape;
+    target: Container | null;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+    at: number;
+    duration: number | undefined;
+    constructor(spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape);
+    abstract build(): Promise<void>;
+    buildFilters(): void;
+    scope(): Scope;
+    /**
+     * Prefix routers contributed to the keyframe pipeline (e.g. `three.` in
+     * pixi-effects/three). Base sequences route nothing extra.
+     */
+    protected pathRouters(): PathRouters;
+    /**
+     * The `initial` and `keyframes` that go onto the display object. A layer whose `time` runs a clock (video, composition) takes `time`
+     * out of them: it is not a property of the display object.
+     */
+    protected displayProps(): {
+        initial: SequenceSpec['initial'];
+        keyframes: SequenceSpec['keyframes'];
+    };
+    destroy(): void;
+}
+
+export { type PathRouters as P, Sequence as S };

package/dist/Composition-MUKR3FYD.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkWHNADXXG_cjs = require('./chunk-WHNADXXG.cjs');
+require('./chunk-ZVUO325O.cjs');
+require('./chunk-2DXPTKQZ.cjs');
+require('./chunk-LYOKH7KE.cjs');
+require('./chunk-TWZNOUM7.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkWHNADXXG_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-MUKR3FYD.cjs.map
+//# sourceMappingURL=Composition-MUKR3FYD.cjs.map

package/dist/{Composition-K6B3APM5.cjs.map → Composition-MUKR3FYD.cjs.map}

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

package/dist/Composition-RJGA7KDU.js

@@ -0,0 +1,7 @@
+export { CompositionSequence } from './chunk-A3Q3SDSH.js';
+import './chunk-ZAXYPXKW.js';
+import './chunk-4KB3GUEK.js';
+import './chunk-RCVZX2JP.js';
+import './chunk-BXOCEZ4U.js';
+//# sourceMappingURL=Composition-RJGA7KDU.js.map
+//# sourceMappingURL=Composition-RJGA7KDU.js.map

package/dist/{Composition-H7UNR5F5.js.map → Composition-RJGA7KDU.js.map}

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