pixi-effects 0.28.1 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # 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**
+
+- **`pixi-effects view` tells you the work changed, and never switches by itself.** It watches the page's folder (not `node_modules`, `out`, `reviews`, `check-out`, hidden files); when something changes it shows "Updated hh:mm:ss — reload (R)" and nothing else. Reload (the button or R) loads the page again and returns to the frame you were on; the switch "auto" (off by default, remembered) reloads only while the movie is paused. The skill now says to start the viewer right after copying the template (before the brief is written) and to give the human the address in the first message, so the first address goes out within two minutes and they watch the film grow.
+
+**Fixed**
+
+- **`pixi-effects view` centres the page, and the timeline legend no longer gets cut off.** A page that keeps its picture at the left edge (the template does) sat against the left of a wide viewer; the iframe is now as wide as the page's own content and centred. The legend under the timeline (text, shape, image, …) is wrapped onto more lines when the chart is narrow instead of running past the right edge (`timelineSvg()` and the `timeline.html` that `check` writes).
+- **A text layer whose `style` has an undefined value is no longer blanked.** `style: { fontSize: undefined }` (a variable that was never set) erased the default size and the text was not drawn; the check said only "has no size". The undefined keys are now skipped (Pixi keeps its default) and one warning names them: `style.fontSize is undefined … omit the key instead`.
+
+**Docs**
+
+- Pitfall 103: load a web font before `measureText` / `splitText` / `animateText` (measured: a Latin headline is 21 % wider in the fallback font). `direction.md` asks the reviewer to write the three defects into `reviews/notes.md`, to measure the smallest text, and to look at both ends of every cut. Both came from a fresh agent making a company film from the published skill alone.
+
 ## 0.28.1
 
 **Changed**

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.28.1`. 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.1/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/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.1/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.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.1/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.29.0/dist/three.js"
   }
 }
 </script>
@@ -174,8 +174,8 @@ This library is designed to be written by AI: a video is plain data, and every m
 - [`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). Install it with `npx skills add yjmtmtk/pixi-effects` (or copy the `skills/pixi-effects/` folder to `~/.claude/skills/pixi-effects/` or your project's `.claude/skills/`) and your agent loads it by itself 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.
+- **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), `--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.1/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.28.1/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

@@ -9,6 +9,10 @@
  * Click or drag on the timeline to seek the movie; click a layer's name to jump to where it starts; Space plays / pauses,
  * ← / → step a frame (Shift: a second), Home / End jump to the ends. Stop it with Ctrl-C.
  *
+ * It watches the page's folder (not `node_modules`, `out`, `reviews`, `check-out`, hidden files). When the work changes it shows "Updated hh:mm:ss — reload (R)"
+ * and NOTHING else: the picture you are looking at never switches by itself. Reload (the button, or R) loads the page again and goes back to the frame you were on.
+ * The switch "auto" (off by default, remembered) reloads for you, but only while the movie is paused and you are not dragging the timeline.
+ *
  * Needs: Node >= 18. A browser (the default one is opened; --no-open prints the address instead). The page must follow
  * 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/)
@@ -22,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);
@@ -38,6 +45,26 @@ export function parseViewArgs(argv) {
   return o;
 }
 
+const IGNORED = new Set(['node_modules', 'out', 'reviews', 'check-out', '.git', 'dist']);
+
+/** A short fingerprint of the work in a folder (file count, newest edit, total size): it changes when something is edited or added. Outputs, installs and hidden files are left out. */
+export function folderSignature(dir, { ignore = IGNORED, maxFiles = 4000, maxDepth = 5 } = {}) {
+  let count = 0, newest = 0, bytes = 0;
+  const walk = (d, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (count >= maxFiles) return;
+      if (e.name.startsWith('.')) continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) { if (!ignore.has(e.name) && depth < maxDepth) walk(full, depth + 1); continue; }
+      try { const st = fs.statSync(full); count++; newest = Math.max(newest, st.mtimeMs); bytes += st.size; } catch { /* removed while we looked */ }
+    }
+  };
+  walk(dir, 0);
+  return count + ':' + Math.round(newest) + ':' + bytes;
+}
+
 const escHtml = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
 /** The viewer page: the composition in an iframe, its timeline under it (zoomable), a playhead, click / drag / keys to seek. */
@@ -53,6 +80,8 @@ export function viewerHtml({ pageUrl, title }) {
   header b { font-size: 14px; font-weight: 600; }
   #time { font-family: ui-monospace, Menlo, monospace; color: var(--dim); }
   #status { color: var(--dim); }
+  #update button { background: var(--head); color: #fff; border-color: var(--head); font-weight: 600; }
+  #autolabel { color: var(--dim); user-select: none; }
   .zoom { display: inline-flex; align-items: center; gap: 4px; margin-left: auto; }
   #zlabel { min-width: 44px; text-align: center; font-family: ui-monospace, Menlo, monospace; color: var(--dim); }
   button { font: inherit; background: transparent; color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: 3px 12px; cursor: pointer; }
@@ -72,7 +101,7 @@ export function viewerHtml({ pageUrl, title }) {
   #head line { stroke: var(--head); stroke-width: 2; } #head path { fill: var(--head); }
 </style></head>
 <body>
-<header><b>${escHtml(title)}</b><button id="play" type="button" disabled>▶</button><span id="time">0.00 / 0.00 s · frame 0</span><span id="status">loading the page…</span>
+<header><b>${escHtml(title)}</b><button id="play" type="button" disabled>▶</button><span id="time">0.00 / 0.00 s · frame 0</span><span id="status">loading the page…</span><span id="update" hidden><button id="reload" type="button" title="load the page again, on the frame you are on (R)">Updated — reload (R)</button></span><label id="autolabel" title="reload by itself, but only while the movie is paused"><input type="checkbox" id="auto"> auto</label>
   <span class="zoom"><button id="zout" type="button" title="zoom out (-)" disabled>−</button><span id="zlabel">fit</span><button id="zin" type="button" title="zoom in (+, or Ctrl/⌘ + wheel)" disabled>+</button><button id="zfit" type="button" title="fit the whole movie (0)" disabled>fit</button></span></header>
 <div id="stage"><iframe id="page" src="${escHtml(pageUrl)}" allow="autoplay; fullscreen"></iframe></div>
 <div id="chart"><div id="names"></div><div id="plot"></div></div>
@@ -87,31 +116,75 @@ export function viewerHtml({ pageUrl, title }) {
   const sleep = ms => new Promise(r => setTimeout(r, ms));
   const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
   const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-  let movie = null, svg = null, head = null, geom = null, zoom = 1, scrubbing = false;
+  let movie = null, svg = null, head = null, geom = null, zoom = 1, scrubbing = false, bound = false;
+  const $update = document.getElementById('update'), $reload = document.getElementById('reload'), $auto = document.getElementById('auto');
+  let seen = null, pending = false;
+  try { $auto.checked = localStorage.getItem('pe-view-auto') === '1'; } catch { /* storage may be blocked */ }
 
-  (async () => {
+  /** Wait for the page inside to be a ready movie, then (re)build the timeline. \`restore\` = { frame, playing }: go back where the viewer was. */
+  async function attach(restore) {
+    movie = null; svg = null; head = null; geom = null;
     for (let i = 0; i < 600 && !movie; i++) {
       try { const w = frame.contentWindow; if (w && w.__ready === true && w.movie) movie = w.movie; } catch { /* still loading */ }
       if (!movie) await sleep(200);
     }
-    if (!movie) { $status.textContent = 'the page did not become ready (window.__ready === true and window.movie are needed)'; return; }
+    if (!movie) {
+      let logs = '';
+      try { logs = (frame.contentWindow.__logs || []).slice(-3).join(' | '); } catch { /* unreadable */ }
+      $status.textContent = 'the page did not become ready (window.__ready === true and window.movie are needed)' + (logs ? ' — ' + logs : '');
+      return;
+    }
     if (typeof movie.timelineSvg !== 'function') { $status.textContent = 'this page loads a pixi-effects without movie.timelineSvg() (0.7+ needed)'; return; }
     layout();
     mount();
-  })();
+    if (restore) { await seekFrame(restore.frame); if (restore.playing) movie.play(); }
+  }
+  attach(null);
+
+  /** Load the page again and come back to the same frame (and playing, if it was). Only ever on a request. */
+  async function reload() {
+    const restore = movie ? { frame: movie.currentFrame, playing: movie.isPlaying } : null;
+    pending = false; $update.hidden = true;
+    movie = null; svg = null; head = null; geom = null; plot.innerHTML = ''; names.innerHTML = '';
+    const loaded = new Promise(r => frame.addEventListener('load', r, { once: true }));
+    try { frame.contentWindow.location.reload(); } catch { frame.src = frame.src; }
+    await loaded;
+    await attach(restore);
+  }
+  $reload.addEventListener('click', reload);
+  $auto.addEventListener('change', () => { try { localStorage.setItem('pe-view-auto', $auto.checked ? '1' : '0'); } catch { /* storage may be blocked */ } });
+  // auto only while the movie is paused and nobody is dragging: otherwise the notice waits
+  const maybeAuto = () => { if (pending && $auto.checked && movie && !movie.isPlaying && !scrubbing) reload(); };
 
-  // The page is shown whole: as tall as its picture, scaled down (never up) so the timeline stays in view under it.
+  // does the work still look the same? (the server's number goes up when a file in the folder changes)
+  async function poll() {
+    try {
+      const v = await (await fetch('/__viewer/version', { cache: 'no-store' })).json();
+      if (seen === null) seen = v.version;
+      else if (v.version !== seen) {
+        seen = v.version; pending = true;
+        const d = new Date(v.at), p2 = n => String(n).padStart(2, '0');
+        $reload.textContent = 'Updated ' + p2(d.getHours()) + ':' + p2(d.getMinutes()) + ':' + p2(d.getSeconds()) + ' — reload (R)';
+        $update.hidden = false;
+      }
+    } catch { /* the viewer is stopped */ }
+  }
+  poll(); setInterval(poll, 800);
+
+  // The page is shown whole and in the MIDDLE: as tall as its picture, scaled down (never up) so the timeline stays in view under it. A page that
+  // keeps its picture at the left edge (the template does) is still centred: the iframe is as wide as the page's own content, then centred.
   function layout() {
     const stageW = stage.clientWidth || innerWidth, headH = document.querySelector('header').offsetHeight;
-    let h = 560;
-    const fit = k => { frame.style.width = (stageW / k) + 'px'; frame.style.transform = 'scale(' + k + ')'; };
-    fit(1);
+    let h = 560, cw = stageW;
+    frame.style.width = stageW + 'px'; frame.style.transform = 'none'; frame.style.marginLeft = '0px';
     try {
       const c = frame.contentDocument.querySelector('canvas');
-      if (c) h = Math.round(c.getBoundingClientRect().height + 40);
+      if (c) { const r = c.getBoundingClientRect(); h = Math.round(r.height + 40); cw = Math.min(stageW, Math.round(r.right + r.left)); }
     } catch { /* a page we cannot read */ }
     const k = Math.min(1, Math.max(200, innerHeight - headH - 240) / h);
-    fit(k);
+    frame.style.width = cw + 'px';
+    frame.style.transform = 'scale(' + k + ')';
+    frame.style.marginLeft = Math.max(0, Math.round((stageW - cw * k) / 2)) + 'px';
     frame.style.height = h + 'px';
     stage.style.height = Math.round(h * k) + 'px';
   }
@@ -180,10 +253,12 @@ export function viewerHtml({ pageUrl, title }) {
     const data = movie.timelineData();
     names.innerHTML = '<div class="ruler" style="height:34px"></div>' + data.rows.map(r =>
       '<div class="name" data-start="' + r.start + '" style="padding-left:' + (8 + r.depth * 14) + 'px" title="' + esc(r.path + ' · ' + r.type) + '">' + esc(r.name) + '</div>').join('');
-    names.addEventListener('click', e => { const n = e.target.closest('.name'); if (n) seekTime(parseFloat(n.dataset.start) || 0); });
     render(null);
     $status.textContent = 'click or drag the timeline · Space plays · ← → step a frame (Shift: a second) · + / − zoom (Ctrl/⌘ + wheel) · click a layer name to jump to its start';
     $play.disabled = false; $zfit.disabled = true;
+    if (bound) return;                                              // the controls below are bound once; a reload only rebuilds the timeline
+    bound = true;
+    names.addEventListener('click', e => { const n = e.target.closest('.name'); if (n && movie) seekTime(parseFloat(n.dataset.start) || 0); });
 
     $play.addEventListener('click', toggle);
     $zin.addEventListener('click', () => setZoom(zoom * 1.6, playheadAnchor()));
@@ -198,6 +273,8 @@ export function viewerHtml({ pageUrl, title }) {
     }, { passive: false });
     addEventListener('keydown', e => {
       if (e.target && /input|textarea|select/i.test(e.target.tagName)) return;
+      if ((e.key === 'r' || e.key === 'R') && !e.metaKey && !e.ctrlKey && !e.altKey) { e.preventDefault(); reload(); return; }
+      if (!movie) return;
       const fps = movie.frameRate, f = movie.currentFrame;
       if (e.key === ' ') { e.preventDefault(); toggle(); }
       else if (e.key === 'ArrowLeft') { e.preventDefault(); seekFrame(f - (e.shiftKey ? fps : 1)); }
@@ -210,9 +287,11 @@ export function viewerHtml({ pageUrl, title }) {
     });
     requestAnimationFrame(tick);
   }
-  const toggle = () => { if (movie.isPlaying) movie.pause(); else movie.play(); };
+  const toggle = () => { if (!movie) return; if (movie.isPlaying) movie.pause(); else movie.play(); };
 
   function tick() {
+    if (!movie || !head || !geom) { maybeAuto(); requestAnimationFrame(tick); return; }
+    maybeAuto();
     const t = nowT(), x = tToX(t);
     head.setAttribute('transform', 'translate(' + x.toFixed(2) + ',0)');
     $time.textContent = t.toFixed(2) + ' / ' + geom.dur.toFixed(2) + ' s · frame ' + movie.currentFrame;
@@ -244,19 +323,32 @@ export async function startViewer(opts) {
   const pageUrl = '/' + rel + (opts.query ? '?' + opts.query : '');
   const title = path.basename(pagePath).replace(/\.[^.]+$/, '');
   const html = viewerHtml({ pageUrl, title });
+  // The work's version: a number that goes up when a file in the page's folder changes. The viewer only SHOWS it; it never reloads by itself.
+  const dir = path.dirname(pagePath);
+  let version = 1, changedAt = Date.now(), signature = folderSignature(dir);
+  const timer = setInterval(() => { const now = folderSignature(dir); if (now !== signature) { signature = now; version++; changedAt = Date.now(); } }, opts.watchEvery ?? 400);
+  timer.unref();
   const { server, port } = await serve(root, (req, res) => {
-    if (req.method !== 'GET' || !req.url.startsWith(VIEWER)) return false;
+    if (req.method !== 'GET') return false;
+    const pathname = req.url.split('?')[0];
+    if (pathname === VIEWER + '/version') {
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' }).end(JSON.stringify({ version, at: changedAt }));
+      return true;
+    }
+    if (pathname !== VIEWER) return false;
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }).end(html);
     return true;
   }, opts.port);
+  server.on('close', () => clearInterval(timer));
   return { server, url: `http://127.0.0.1:${port}${VIEWER}` };
 }
 
 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 };