pixi-effects 0.28.2 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.30.0
+
+**Added**
+
+- **`pixi-effects new <name>`, `recipe [id]` and `help <word>`: read what you need, not 100 KB.** `new` writes `<name>.html` from the template, titled with the name and pinned to the installed version (it will not overwrite without `--force`). `recipe` lists the tested recipes (id and title); with an id (or a unique part of one) it prints that recipe's text and code; an id nobody has says the nearest one. `help <word>` prints the sections of the docs about a word (`docs/dsl.md`, the cheatsheet, the pitfalls, `docs/api.md`, `direction.md`), headings first, each cut to 30 lines with where the rest is, never more than 170 lines in all.
+- **`skills/pixi-effects/reference/quickstart.md`** (under 2 KB, a test holds it there): the five commands, a title card that the recipe tests build and lint, and the rules that cause most failures. `SKILL.md`, `AGENTS.md`, `llms.txt` and the README start an agent there; the 35 KB cheatsheet and the 41 KB pitfalls are for looking things up.
+
+## 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.30.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.30.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.30.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.30.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.30.0/dist/three.js"
   }
 }
 </script>
@@ -174,8 +174,9 @@ 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).
 
+- **Start a page, and read only what you need:** `npx pixi-effects new my-video` writes `my-video.html` from the template; `npx pixi-effects recipe [id]` lists the tested recipes and prints one with its code; `npx pixi-effects help <word>` prints the sections of the docs about a word (`mask`, `threeD`, `keyframes`, `music` …). An AI starts from the 2 KB [quick start](./skills/pixi-effects/reference/quickstart.md), not from the cheatsheet.
 - **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 +185,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.30.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.30.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.30.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/lookup.mjs

@@ -0,0 +1,208 @@
+// pixi-effects recipe | help | new: let an agent read what it needs instead of a 35 KB cheatsheet and a 69 KB list of recipes.
+//
+//   npx pixi-effects recipe              the recipes (id and title)
+//   npx pixi-effects recipe <id>         one recipe: its text and its code (a part of an id works when it is unique)
+//   npx pixi-effects help <word>         the sections of the docs about a word (mask, threeD, keyframes, music …)
+//   npx pixi-effects new <name>          <name>.html from the template, pinned to this package's version
+//
+// Zero dependencies. The texts are the ones the package ships (docs/dsl.md, docs/api.md, skills/pixi-effects/reference/*.md, skills/pixi-effects/template.html).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const RECIPES = 'skills/pixi-effects/reference/recipes.md';
+/** What `help` reads, most useful first (the number is a small bonus in the ranking). */
+const CORPUS = [
+  ['docs/dsl.md', 10], ['skills/pixi-effects/reference/cheatsheet.md', 8], ['skills/pixi-effects/reference/pitfalls.md', 6],
+  ['docs/api.md', 4], ['skills/pixi-effects/reference/direction.md', 2],
+];
+const MAX_HITS = 5, MAX_LINES_PER_HIT = 30, MAX_OUTPUT_LINES = 170;
+
+function distance(a, b) {
+  const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) m[0][j] = j;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+    m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) m[i][j] = Math.min(m[i][j], m[i - 2][j - 2] + 1);
+  }
+  return m[a.length][b.length];
+}
+const nearestOf = (word, list) => {
+  let best = null;
+  for (const c of list) { const d = distance(word.toLowerCase(), c.toLowerCase()); if (d <= Math.max(2, Math.floor(c.length / 3)) && (!best || d < best.d)) best = { c, d }; }
+  return best ? best.c : undefined;
+};
+
+/** The "## " sections of a markdown text (a heading inside a code fence is not one). Each: { title, text, line (1-based), ids (the names after // @recipe or // @docs-only) }. */
+export function parseRecipes(md) {
+  const lines = md.split('\n');
+  const sections = [];
+  let fence = false, cur = null;
+  lines.forEach((line, i) => {
+    if (/^```/.test(line)) fence = !fence;
+    const h = !fence && /^## (.+)$/.exec(line);
+    if (h) { cur = { title: h[1].trim(), lines: [line], line: i + 1 }; sections.push(cur); }
+    else if (cur) cur.lines.push(line);
+  });
+  return sections.map(s => {
+    const body = [...s.lines];
+    while (body.length && /^(---|\s*)$/.test(body[body.length - 1])) body.pop();             // the separator belongs to nobody
+    const text = body.join('\n');
+    return { title: s.title, text, line: s.line, ids: [...text.matchAll(/\/\/ @(?:recipe|docs-only)[ \t]+([A-Za-z0-9_-]+)/g)].map(m => m[1]) };
+  });
+}
+
+/** { section, id } for an exact id or a unique part of one (or of a title); { many } when several match; { nearest } (maybe undefined) when none does. */
+export function findRecipe(sections, query) {
+  const q = query.trim().toLowerCase();
+  const exact = sections.find(s => s.ids.some(id => id.toLowerCase() === q));
+  if (exact) return { section: exact, id: exact.ids.find(id => id.toLowerCase() === q) };
+  const part = sections.filter(s => s.ids.some(id => id.toLowerCase().includes(q)) || s.title.toLowerCase().includes(q));
+  if (part.length === 1) return { section: part[0] };
+  if (part.length > 1) return { many: part };
+  return { nearest: nearestOf(q, sections.flatMap(s => s.ids)) };
+}
+
+const readIf = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
+
+/** Sections of a doc: a "## / ### / ####" heading each; for the pitfalls, a numbered item each ("84. **Subtract …**"). */
+function docSections(text, file) {
+  const out = [];
+  const lines = text.split('\n');
+  const pit = /pitfalls\.md$/.test(file);
+  let fence = false, cur = null;
+  lines.forEach((line, i) => {
+    if (/^```/.test(line)) fence = !fence;
+    let heading = null;
+    if (!fence) {
+      const h = /^#{2,4} (.+)$/.exec(line);
+      const p = pit && /^(\d+[a-z]?)\. \*\*(.+?)\*\*/.exec(line);
+      if (h) heading = h[1].trim();
+      else if (p) heading = `pitfall ${p[1]}: ${p[2].replace(/[`*]/g, '')}`.slice(0, 100);
+    }
+    if (heading) { cur = { file, heading, line: i + 1, lines: [line] }; out.push(cur); }
+    else if (cur) cur.lines.push(line);
+  });
+  return out;
+}
+
+/** The sections of the docs about `word` (all its words must appear), best first: [{ file, line, heading, lines, more }]. */
+export function searchDocs(root, word) {
+  const tokens = String(word).toLowerCase().split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const scored = [];
+  for (const [file, bonus] of CORPUS) {
+    const text = readIf(path.join(root, file));
+    if (!text) continue;
+    for (const s of docSections(text, file)) {
+      const heading = s.heading.toLowerCase();
+      const body = s.lines.join('\n').toLowerCase();
+      if (!tokens.every(t => body.includes(t))) continue;
+      const inHeading = tokens.every(t => heading.includes(t));
+      const count = tokens.reduce((n, t) => n + body.split(t).length - 1, 0);
+      scored.push({ s, score: (inHeading ? 1000 : 0) + Math.min(count, 50) + bonus });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, MAX_HITS).map(({ s }) => {
+    const body = s.lines.filter((l, i) => i === 0 || l.trim() !== '' || true);
+    const shown = body.slice(0, MAX_LINES_PER_HIT);
+    return { file: s.file, line: s.line, heading: s.heading, lines: shown, more: Math.max(0, body.length - shown.length) };
+  });
+}
+
+/** The lines `help` prints for those hits (the whole answer stays under MAX_OUTPUT_LINES), with the next step at the end. */
+export function formatHelp(hits, word, root = PACKAGE_ROOT) {
+  const out = [];
+  const share = Math.max(8, Math.floor((MAX_OUTPUT_LINES - 6 - hits.length * 3) / Math.max(1, hits.length)));
+  for (const h of hits) {
+    out.push(`── ${h.file}:${h.line}  ${h.heading}`);
+    const lines = h.lines.slice(0, share);
+    out.push(...lines);
+    const more = h.more + (h.lines.length - lines.length);
+    if (more > 0) out.push(`… ${more} more lines: ${h.file}:${h.line}`);
+    out.push('');
+  }
+  const md = readIf(path.join(root, RECIPES));
+  const ids = md ? parseRecipes(md).filter(s => String(word).toLowerCase().split(/\s+/).every(t => s.title.toLowerCase().includes(t) || s.ids.some(id => id.includes(t)))).flatMap(s => s.ids).slice(0, 6) : [];
+  out.push(`next: pixi-effects help <another word>${ids.length ? ` · recipes about it: ${ids.map(i => `pixi-effects recipe ${i}`).join(', ')}` : ' · pixi-effects recipe (the tested pieces to copy)'}`);
+  return out.slice(0, MAX_OUTPUT_LINES);
+}
+
+/** <name>.html from the template, titled with the name, its CDN pins set to this package's version. Throws if the file exists (without `force`). */
+export function newPage(name, { cwd = process.cwd(), root = PACKAGE_ROOT, force = false } = {}) {
+  if (!name || !String(name).trim()) throw new Error('give the page a name: pixi-effects new my-video');
+  const raw = String(name).trim();
+  const base = path.basename(raw).replace(/\.html?$/i, '');
+  const dir = path.dirname(raw);
+  const file = path.resolve(cwd, dir, base.replace(/[\\/:*?"<>|]/g, '').replace(/\s+/g, '-') + '.html');
+  if (!fs.existsSync(path.dirname(file))) throw new Error(`the folder ${path.dirname(file)} does not exist`);
+  if (fs.existsSync(file) && !force) throw new Error(`${file} already exists (give another name, or --force to replace it)`);
+  const template = readIf(path.join(root, 'skills/pixi-effects/template.html'));
+  if (!template) throw new Error('the template is missing from this package (skills/pixi-effects/template.html)');
+  const version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+  const html = template
+    .replace(/pixi-effects@\d+\.\d+\.\d+/g, `pixi-effects@${version}`)
+    .replace('<title>pixi-effects video</title>', `<title>${base.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</title>`);
+  fs.writeFileSync(file, html);
+  return { file };
+}
+
+const shownPath = (file, cwd) => { const r = path.relative(cwd, file); return r.startsWith('..') || path.isAbsolute(r) ? file : r; };
+
+export const LOOKUP_COMMANDS = ['recipe', 'help', 'new'];
+
+/** Run one of the commands: { code, stdout, stderr } (nothing is printed here). */
+export function runLookup(cmd, args, { cwd = process.cwd(), root = PACKAGE_ROOT } = {}) {
+  const ok = (stdout) => ({ code: 0, stdout: stdout.endsWith('\n') ? stdout : stdout + '\n', stderr: '' });
+  const fail = (stderr, code = 1) => ({ code, stdout: '', stderr: stderr.endsWith('\n') ? stderr : stderr + '\n' });
+  if (cmd === 'recipe') {
+    const md = readIf(path.join(root, RECIPES));
+    if (!md) return fail(`the recipes are missing from this package (${RECIPES})`);
+    const sections = parseRecipes(md);
+    const query = args.join(' ').trim();
+    if (!query) {
+      const lines = ['recipes (pixi-effects recipe <id> prints one with its code):'];
+      for (const s of sections) for (const id of s.ids) lines.push(`  ${id.padEnd(28)} ${s.title}`);
+      return ok(lines.join('\n'));
+    }
+    const r = findRecipe(sections, query);
+    if (r.section) return ok(r.section.text);
+    if (r.many) return fail(`several recipes match "${query}": ${r.many.map(s => s.ids[0] ?? s.title).join(', ')}. Give one id (pixi-effects recipe lists them).`);
+    return fail(`no recipe "${query}"${r.nearest ? `; did you mean "${r.nearest}"?` : ''} (pixi-effects recipe lists them)`);
+  }
+  if (cmd === 'help') {
+    const word = args.join(' ').trim();
+    if (!word) {
+      return ok([
+        'pixi-effects help <word>: the sections of the docs about a word. Try:',
+        '  layers      text  shape  image  video  audio  composition  camera  light  shader  null',
+        '  motion      keyframes  ease  stagger  wiggle  spring  speed  time  expression',
+        '  look        mask  filters  blendMode  gradient  transition  threeD  depth of field',
+        '  sound       sfx  music  audioEnvelope',
+        '  checking    check  inspect  contactSheet  render  stops',
+        'pixi-effects recipe lists the tested pieces to copy; pixi-effects check <page.html> reviews your work.',
+      ].join('\n'));
+    }
+    const hits = searchDocs(root, word);
+    if (!hits.length) return fail(`nothing in the docs about "${word}": try another word (pixi-effects help lists some), or pixi-effects recipe`);
+    return ok(formatHelp(hits, word, root).join('\n'));
+  }
+  if (cmd === 'new') {
+    const force = args.includes('--force');
+    const name = args.filter(a => a !== '--force')[0];
+    if (!name) return fail('give the page a name: pixi-effects new my-video [--force]', 2);
+    try {
+      const { file } = newPage(name, { cwd, root, force });
+      const f = shownPath(file, cwd);
+      return ok([
+        `created ${f} (the template: a 1280x720 page that collects every warning in window.__logs)`,
+        `next: npx pixi-effects view ${f}     look at it as you edit (it says when the file changed)`,
+        `      npx pixi-effects check ${f}    review it: warnings, layout, sound, a contact sheet, a real export`,
+        '      npx pixi-effects recipe        tested pieces to copy  ·  npx pixi-effects help <word>',
+      ].join('\n'));
+    } catch (e) { return fail(`pixi-effects new: ${e.message}`); }
+  }
+  return fail(`unknown command ${cmd}`, 2);
+}

package/ai/tools/pixi-effects.mjs

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

package/ai/tools/render.mjs

@@ -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);