pixi-effects 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.26.0
+
+**Added**
+
+- **Agent skill.** `npx skills add yjmtmtk/pixi-effects` registers pixi-effects as a skill in Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and about 70 more agents; its description starts from the task (a video, motion graphics, an animated title, a lower third, a promo, a chart), so an agent can reach it without being told the library's name. Claude Code also installs it as a plugin (`/plugin install pixi-effects --marketplace yjmtmtk/pixi-effects`).
+- **`pixi-effects` bin** (named like the package): `npx pixi-effects check my-video.html`, `npx pixi-effects render … -o x.mp4`, `npx pixi-effects view …` run the same three tools with nothing installed, and a mistyped command says which one you meant. The three `pixi-effects-check|render|view` bins stay; `npx pixi-effects-check` on its own never worked (npm looks for a package of that name), the docs now say `npx pixi-effects check`. **Fixed:** the three tools printed nothing and exited 0 when npm started them through its symlink (`./node_modules/.bin/pixi-effects-check`); they now run.
+- **`movie.audioBlocked`**: true while the browser keeps the movie's sound silent until a tap (iOS Safari); a player can then ask for the tap. The landing page does: the reel and the gallery pieces start with one tap inside the frame when the sound is locked.
+
+**Changed**
+
+- The skill moved from `ai/` to `skills/pixi-effects/` (`SKILL.md`, `template.html`, `reference/`, `scripts/save-image.py`); `ai/` keeps the chat guide and the tools. Old links to `ai/SKILL.md`, `ai/reference/*` and `ai/template.html` no longer exist. The skill's commands are `npx pixi-effects-check|render|view`.
+
 ## 0.25.0
 
 One release holds three milestones that were built one after the other: **composition** (named mattes, the luma wipe), **light** (lights, shadows, fog) and **freedom of drawing** (the shader layer, the `warp` filter). Wipe, iris and dissolve transitions now also work on WebGL (they drew nothing there before).

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.25.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.26.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
 
 **[Guide →](https://yjmtmtk.github.io/pixi-effects/guide/)** · **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 50 portfolio pieces written as plain data by AI models · **[Examples →](https://yjmtmtk.github.io/pixi-effects/examples/)** · 15 numbered examples, a music lab + an in-browser playground.
 
@@ -10,7 +10,7 @@ Give any AI (ChatGPT, Claude, Codex, Cursor, Claude Code …) one sentence:
 
 > Use https://github.com/yjmtmtk/pixi-effects to make a video: a 10-second title for a bakery, warm colours, a soft chime at the end.
 
-That is all it needs. **If you are the AI** that was asked to do this, do not read the whole repository: if you can run commands (a shell, Node 22, Chrome), read [`AGENTS.md`](./AGENTS.md) and [`ai/SKILL.md`](./ai/SKILL.md); if you can only write text (a browser chat), fetch https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md and follow it. You will write the video as plain data in one HTML file, check it (the check tool writes a contact sheet to look at), and hand it over; the person opens the file and downloads the MP4 with the button in the player bar.
+That is all it needs. **To register it as a skill** in your agent (Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode, …): `npx skills add yjmtmtk/pixi-effects` (update with `npx skills update`). In Claude Code you can also run `/plugin install pixi-effects --marketplace yjmtmtk/pixi-effects`. **If you are the AI** that was asked to do this, do not read the whole repository: if you can run commands (a shell, Node 22, Chrome), read [`AGENTS.md`](./AGENTS.md) and [`skills/pixi-effects/SKILL.md`](./skills/pixi-effects/SKILL.md); if you can only write text (a browser chat), fetch https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md and follow it. You will write the video as plain data in one HTML file, check it (the check tool writes a contact sheet to look at), and hand it over; the person opens the file and downloads the MP4 with the button in the player bar.
 
 Declarative composition and video rendering for the web. After Effects-style timelines on top of [PixiJS v8](https://pixijs.com/) and [GSAP](https://gsap.com/), with strict TypeScript types. Render to MP4 / WebM / MOV via [mediabunny](https://mediabunny.dev/).
 
@@ -19,7 +19,7 @@ Declarative composition and video rendering for the web. After Effects-style tim
 - **Expression language** — sprinkle `'GW * 0.5'` or `'min(W, H) / 2'` anywhere a number goes. Resolved at runtime against a sequence-relative scope.
 - **Filters by name** — `filters: [{ type: 'glow', outerStrength: 3 }]`, no import: `blur noise alpha colorMatrix` (pixi.js) and the 38 filters of [`pixi-filters`](https://github.com/pixijs/filters) (`dropShadow crt rgbSplit oldFilm glitch pixelate twist …`), animated with `'filters.<name>.<option>'`. Any other PixiJS `Filter` goes in as `{ type: 'custom' }`.
 - **Draw-on strokes and changing text** — `trimEnd` 0 → 1 draws a line, border or SVG path on; a keyframe `set: { text }` swaps a string and `visibleChars` is a typewriter.
-- **Masks, transitions, chroma key** — inline masks; chroma key; seven scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`).
+- **Masks, transitions, chroma key** — inline masks; chroma key; eight scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`, `luma`).
 - **Presets** — `kenBurns` for stills, `withFade` for fade-in/out; `wiggle`, `stagger`, `animateText`, `followPath`, `particles` and `react` return keyframes or layers (seeded, so every render is the same).
 - **Presentations** — `stops` in the composition pause the movie where you say; `Presenter` (`pixi-effects/presenter`) moves on with arrow keys, a click or a swipe, with a page overview (G), a presenter view with notes and a timer (P), and `deck()` to lay out pages and steps. Export a deck as PDF (`movie.exportPDF()`, `pixi-effects-render talk.html -o talk.pdf`). See the [Presenting guide](https://yjmtmtk.github.io/pixi-effects/guide/presenting.html).
 - **Music written as text** — `{ type: 'audio', music: { bpm: 96, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }], drums: { kick: 'x...x...' } } }`: a tune with no audio file, played by a small built-in synthesiser (keys, pluck, pad, bass, lead, bell, music box, drums; chords by name, swing, fades, a ritardando). Deterministic, in the exported file at the same moment; an AI writes it as easily as a title.
@@ -51,8 +51,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
     "gsap":                    "https://esm.sh/gsap@3.12.5",
     "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Controller.js"
   }
 }
 </script>
@@ -63,7 +63,7 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
 </script>
 ```
 
-Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.25.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.26.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
 
 > **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
 >
@@ -79,7 +79,7 @@ Add two more entries to the importmap above: three.js itself, and the `pixi-effe
   "imports": {
     "...":                     "(everything from the importmap above)",
     "three":                   "https://esm.sh/three@0.178.0",
-    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/three.js"
   }
 }
 </script>
@@ -173,13 +173,13 @@ sequences: [
 This library is designed to be written by AI: a video is plain data, and every mistake we found while having AI sessions build test animations is either warned about at runtime or written down.
 
 - [`llms.txt`](./llms.txt) / [`llms-full.txt`](./llms-full.txt) — index and full text for LLM tooling (generated from the files below).
-- [`ai/SKILL.md`](./ai/SKILL.md) — a [skill](https://docs.claude.com/en/docs/claude-code/skills) (workflow, rules, verification loop). Copy the `ai/` folder to `~/.claude/skills/pixi-effects/` (or your project's `.claude/skills/`) to have Claude load it automatically when you ask for a video.
-- [`ai/reference/cheatsheet.md`](./ai/reference/cheatsheet.md), [`recipes.md`](./ai/reference/recipes.md) (tested), [`pitfalls.md`](./ai/reference/pitfalls.md), and a starter [`ai/template.html`](./ai/template.html).
+- [`skills/pixi-effects/SKILL.md`](./skills/pixi-effects/SKILL.md) — a [skill](https://docs.claude.com/en/docs/claude-code/skills) (workflow, rules, verification loop). Copy the `ai/` folder to `~/.claude/skills/pixi-effects/` (or your project's `.claude/skills/`) to have Claude load it automatically when you ask for a video.
+- [`skills/pixi-effects/reference/cheatsheet.md`](./skills/pixi-effects/reference/cheatsheet.md), [`recipes.md`](./skills/pixi-effects/reference/recipes.md) (tested), [`pitfalls.md`](./skills/pixi-effects/reference/pitfalls.md), and a starter [`skills/pixi-effects/template.html`](./skills/pixi-effects/template.html).
 
-- **Look at a page with its timeline, and scrub one with the other:** `npx pixi-effects-view my-video.html` (or `node ai/tools/view.mjs …`) opens your browser on a viewer: the page on top, the timeline of every layer under it with a playhead that follows the movie. Click or drag the timeline to seek, click a layer's name to jump to where it starts, Space plays, ← / → step a frame, + / − (or Ctrl/⌘ + wheel) zoom, the names stay in place. For the human who wants to see what the AI made.
-- **Render a page to a video file, headless:** `npx pixi-effects-render my-video.html -o my-video.mp4` (or `node ai/tools/render.mjs …`; Node ≥ 22 and Chrome installed, no dependencies). The container follows the extension (`mp4 webm mov mkv`); `--quality very-low…very-high`, `--query lang=ja` (added to the page URL), `--fail-on-warn` (exit 1 when the page logged a warning), `--quiet`. It waits for `window.__ready`, runs `movie.render()` and streams the file to disk; exit 0 = written, 1 = the page or the render failed (no file). For scripts, CI and batches; `pixi-effects-check` below is the review.
-- **A talk as a PDF:** `npx pixi-effects-render my-talk.html -o my-talk.pdf` (one page per page of a `deck()` / `stops` movie; `--all-stops` makes a page of every step). The review tool writes `stops.png` for such a page, one picture per stop.
-- **One-command review for the AI that wrote the page:** `npx pixi-effects-check my-video.html` (or `node ai/tools/check.mjs my-video.html`; Node ≥ 22 and Chrome installed, no dependencies). It opens the page in its own headless Chrome and reports warnings, layout (`movie.inspect` over the whole timeline), the soundtrack (`movie.inspectAudio`) and a real export decoded again, and writes a contact sheet PNG and a `timeline.html` (every layer as a bar on a time axis) to look at. Exit code 0 / 1.
+- **Look at a page with its timeline, and scrub one with the other:** `npx pixi-effects view my-video.html` (or `node ai/tools/view.mjs …`) opens your browser on a viewer: the page on top, the timeline of every layer under it with a playhead that follows the movie. Click or drag the timeline to seek, click a layer's name to jump to where it starts, Space plays, ← / → step a frame, + / − (or Ctrl/⌘ + wheel) zoom, the names stay in place. For the human who wants to see what the AI made.
+- **Render a page to a video file, headless:** `npx pixi-effects render my-video.html -o my-video.mp4` (or `node ai/tools/render.mjs …`; Node ≥ 22 and Chrome installed, no dependencies). The container follows the extension (`mp4 webm mov mkv`); `--quality very-low…very-high`, `--query lang=ja` (added to the page URL), `--fail-on-warn` (exit 1 when the page logged a warning), `--quiet`. It waits for `window.__ready`, runs `movie.render()` and streams the file to disk; exit 0 = written, 1 = the page or the render failed (no file). For scripts, CI and batches; `pixi-effects-check` below is the review.
+- **A talk as a PDF:** `npx pixi-effects render my-talk.html -o my-talk.pdf` (one page per page of a `deck()` / `stops` movie; `--all-stops` makes a page of every step). The review tool writes `stops.png` for such a page, one picture per stop.
+- **One-command review for the AI that wrote the page:** `npx pixi-effects check my-video.html` (or `node ai/tools/check.mjs my-video.html`; Node ≥ 22 and Chrome installed, no dependencies). It opens the page in its own headless Chrome and reports warnings, layout (`movie.inspect` over the whole timeline), the soundtrack (`movie.inspectAudio`) and a real export decoded again, and writes a contact sheet PNG and a `timeline.html` (every layer as a bar on a time axis) to look at. Exit code 0 / 1.
 
 They ship in the npm package (`node_modules/pixi-effects/ai/`).
 

package/ai/CHAT.md

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

package/ai/chat-template.html

@@ -61,9 +61,9 @@
       "gsap":                    "https://cdn.jsdelivr.net/npm/gsap@3.12.5/+esm",
       "gsap/PixiPlugin":         "https://cdn.jsdelivr.net/npm/gsap@3.12.5/PixiPlugin/+esm",
       "mediabunny":              "https://cdn.jsdelivr.net/npm/mediabunny@1.61.3/+esm",
-      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/Controller.js",
-      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.25.0/dist/Presenter.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Controller.js",
+      "pixi-effects/presenter":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.26.0/dist/Presenter.js"
     }
   }
   </script>

package/ai/tools/check.mjs

@@ -2,7 +2,7 @@
 /**
  * pixi-effects check — review a composition page in ONE command, without driving a browser by hand.
  *
- *   node ai/tools/check.mjs my-video.html            (or:  npx pixi-effects-check my-video.html)
+ *   node ai/tools/check.mjs my-video.html            (or:  npx pixi-effects check my-video.html)
  *
  * It starts a private static server and a private headless Chrome (nothing shared with other sessions), opens the page,
  * waits for `window.__ready === true`, then checks: console warnings / errors, `movie.inspect` over the whole timeline
@@ -11,7 +11,7 @@
  * (`sheet.png`, `<name>.<format>`, `report.json`; a presentation with `stops` also gets `stops.png`, one picture per stop) and a short summary is printed. Exit code 0 = nothing to fix, 1 = problems.
  *
  * Needs: Node >= 22 (built-in WebSocket), Chrome / Chromium installed (or --chrome PATH / CHROME=PATH). No npm dependencies.
- * The page must follow ai/template.html: it exposes `window.movie` and sets `window.__ready = true` (and `window.__logs`).
+ * The page must follow skills/pixi-effects/template.html: it exposes `window.movie` and sets `window.__ready = true` (and `window.__logs`).
  *
  * Options: --draft (the export is a draft: half size, low quality, no motion blur: a much smaller file; the drawing itself is not faster) · --at LIST (pictures at moments you name: 3.5, 50%, f120, title@end → frames/*.png and at.png) ·
  *          --query "a=1&b=2" (added to the page address: for a page that reads it, such as one video of a batch) ·
@@ -514,7 +514,7 @@ function finish(report, outDir, log) {
 
 // ───────────────────────────── CLI ─────────────────────────────
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {   // the real path: npm starts a bin through a symlink
   try {
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseArgs(process.argv.slice(2));

package/ai/tools/pixi-effects.mjs

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

package/ai/tools/render.mjs

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

package/ai/tools/view.mjs

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

package/dist/Controller.d.cts

@@ -1,4 +1,4 @@
-import { h as Movie } from './Movie-CTpN1wYL.cjs';
+import { h as Movie } from './Movie-DXReF4-W.cjs';
 import 'pixi.js';
 import 'gsap';
 import './types-CoT0ypcx.cjs';

package/dist/Controller.d.ts

@@ -1,4 +1,4 @@
-import { h as Movie } from './Movie-FM5m67V0.js';
+import { h as Movie } from './Movie-DP5p1r4E.js';
 import 'pixi.js';
 import 'gsap';
 import './types-CoT0ypcx.js';

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

@@ -445,6 +445,8 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** True while the movie has sound but the browser keeps it silent until the viewer taps (iOS Safari, a page nobody has touched): a player can show "tap for sound"; the sound starts at a tap or key press that arrives while play() is pending, or at the next play() made from a tap. */
+    get audioBlocked(): boolean;
     /** The poster time as a frame number, or null. */
     get posterFrame(): number | null;
     /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */

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

@@ -445,6 +445,8 @@ declare class Movie {
     off(event: string, fn: Listener): this;
     emit(event: string, ...args: unknown[]): void;
     get isReady(): boolean;
+    /** True while the movie has sound but the browser keeps it silent until the viewer taps (iOS Safari, a page nobody has touched): a player can show "tap for sound"; the sound starts at a tap or key press that arrives while play() is pending, or at the next play() made from a tap. */
+    get audioBlocked(): boolean;
     /** The poster time as a frame number, or null. */
     get posterFrame(): number | null;
     /** Draw the poster frame on the canvas and leave the playhead where it is (frame 0): the picture before the movie plays. */

package/dist/Presenter.d.cts

@@ -1,4 +1,4 @@
-import { h as Movie } from './Movie-CTpN1wYL.cjs';
+import { h as Movie } from './Movie-DXReF4-W.cjs';
 import 'pixi.js';
 import 'gsap';
 import './types-CoT0ypcx.cjs';

package/dist/Presenter.d.ts

@@ -1,4 +1,4 @@
-import { h as Movie } from './Movie-FM5m67V0.js';
+import { h as Movie } from './Movie-DP5p1r4E.js';
 import 'pixi.js';
 import 'gsap';
 import './types-CoT0ypcx.js';

package/dist/index.cjs

@@ -2120,6 +2120,9 @@ function startWhenRunning(ctx, start, gesture) {
   return stop;
 }
 var GESTURES = ["pointerdown", "mousedown", "touchend", "keydown"];
+function audioIsBlocked(ctx, hasAudio) {
+  return !!ctx && hasAudio && ctx.state !== "running";
+}
 
 // src/core/poster.ts
 function normalizePoster(poster, duration, frameRate) {
@@ -2412,6 +2415,10 @@ var Movie = class {
   get isReady() {
     return this._initState === "ready";
   }
+  /** True while the movie has sound but the browser keeps it silent until the viewer taps (iOS Safari, a page nobody has touched): a player can show "tap for sound"; the sound starts at a tap or key press that arrives while play() is pending, or at the next play() made from a tap. */
+  get audioBlocked() {
+    return audioIsBlocked(this._audioContext, !!this.audioBuffer);
+  }
   /** The poster time as a frame number, or null. */
   get posterFrame() {
     return this._posterFrame;