pixi-effects 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.31.0
+
+**Added: variables, and a composition that is built again (design: `docs/superpowers/specs/2026-10-11-variables-0.31-design.md`)**
+
+- **`movie.init({ vars: { title: 'NORD', accent: '#e5399a', shift: 0 } })`.** A number is a plain name in an expression (`x: 'W/2 + shift'`); any value is `{title}` inside a string anywhere in the composition (`text`, a colour, `asset`, a layer name). Not `$`: that is a price. Reserved (refused, said once): `w h W H GW GH t d T contain cover value`, the expression functions and `PI`. `at` and `duration` stay plain numbers: a variable moves values, not timing.
+- **`movie.setVars()`, `movie.resize(w, h)`, `movie.rebuild({ composition, vars, width, height })`, `movie.vars`, the `'rebuilt'` event.** The composition is built off the stage and swapped in whole, at the same frame; a playing movie keeps playing, a poster stays; a failure keeps the old composition (`error` with `where: 'rebuild'`, and the promise rejects); calls that overlap are joined (the latest values are built once more). Each returns `{ reason, ms, audio: 'reused' | 'mixed' | 'none', frame, playing }`. The sound is mixed again **only if it changed** (a mix of a film takes 0.6 to 0.8 s, the rest about 20 ms). After `resize()` the movie's size beats a `width` / `height` the composition names. The `Controller` redraws its stop marks.
+- **Warnings at `init` (and when `rebuild({ composition })` replaces the spec):** a variable nothing reads, and a `{name}` nobody declared (with the declared name it looks like). `setVars` of an undeclared name is ignored with a did-you-mean.
+- **`pixi-effects check` / `render` take `--var name=value` (repeatable) and `--size WxH`.** The tool builds the page again once it is ready, so a page needs nothing for it; a number variable is given a number, a name the page did not declare stops the run with the nearest one. `check --size 1920x1080,1080x1920` writes a contact sheet and a layout review per size (`sheet.png`, `sheet-1080x1920.png`) and a `vars` and a `sizes` line; `render --var lang=ja --size 1080x1920` writes the variant.
+- **Fixed with it: `play()`'s first frame could land one frame BEHIND where it was started** (the animation frame's time is a little earlier than the start time), so a pause and play in a row walked the playhead back; and rebuilds that came faster than a frame held a playing movie still. A rebuild that leaves the sound alone no longer stops anything.
+- **`movie.loop` (and `init({ loop })`, the `loopchange` event) and the Controller's loop button.** At the end of an ordinary `play()` the movie goes back to the start and plays on: no `ended`, no `pause` / `play` events at the wrap, the sound starts again. Default `false`, like a `<video>`; `playUntil()` and `render()` ignore it. The bar has a loop button next to the volume and the `L` key (`Controller` option `loopButton`, default true).
+- **Fixed: a text outline no longer spikes.** `style.stroke: { color, width }` was drawn with PixiJS's default `miter` join, which grows spikes on the sharp corners of W, V, A, k (an AI wrote this often). An outline that names no `join` is round-joined now; `join: 'miter'` / `'bevel'` still say what they say. Pitfall 106; `docs/dsl.md` (Text).
+- Recipes `variants` (a language and a colour as variables) and `liquid-layout` (`ResizeObserver` + `rebuild`); pitfalls 104 and 105; `docs/dsl.md` "Variables", `docs/api.md` "Movie variables and rebuilding".
+
+**Known limits.** While a movie plays, the new composition is built beside the old one (it keeps playing); when the sound is unchanged nothing stops, when it changed the sound starts again from the same frame (a short gap); a rebuild is the whole composition, not one property (measured in the spike: evaluating the expressions is about 40 µs, so a finer recompute buys little).
+
 ## 0.30.1
 
 **Docs**

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.30.1`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.31.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.
 
@@ -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.30.1/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.30.1/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.31.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.31.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.30.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.31.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.30.1/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.31.0/dist/three.js"
   }
 }
 </script>
@@ -186,6 +186,7 @@ They ship in the npm package (`node_modules/pixi-effects/ai/`).
 
 - [**DSL reference**](./docs/dsl.md) — composition, sequences, 3D layers & camera, three.js layer, keyframes, expressions, filters
 - [**API reference**](./docs/api.md) — `Movie`, `Controller`, `pixi-effects/present`, `pixi-effects/three`, events, render options
+- [**Interactive movies**](./examples/interactive/) — nine live samples of a movie you change while it plays (variables, `setVars`, `rebuild`, loop): rock paper scissors, a scrolling city, a tune from four chords, a card for anyone, choose your ending … ([the guide chapter](./site/guide/interactive.md))
 - [**Examples**](./examples/) — runnable HTML files (read in order):
   - `01-hello.html` — minimum viable composition
   - `02-keyframes.html` — keyframes, easings, expressions

package/ai/chat-template.html

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

package/ai/tools/check.mjs

@@ -25,6 +25,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseVar, parseSizes, applyToPage } from './varArgs.mjs';
 
 // ───────────────────────────── pure helpers (unit-tested) ─────────────────────────────
 
@@ -78,10 +79,10 @@ export function findChrome(env = process.env, exists = fs.existsSync, platform =
   return candidates.find(c => c && exists(c)) ?? null;
 }
 
-export const USAGE = 'usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--draft] [--at 3.5,title@end] [--onion 1:3] [--query a=1&b=2] [--timeout S] [--root DIR] [--chrome PATH] [--strict] [--help]\n(the header of ai/tools/check.mjs explains each option)';
+export const USAGE = 'usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--draft] [--at 3.5,title@end] [--onion 1:3] [--query a=1&b=2] [--var name=value] [--size 1920x1080,1080x1920] [--timeout S] [--root DIR] [--chrome PATH] [--strict] [--help]\n(the header of ai/tools/check.mjs explains each option)';
 
 export function parseArgs(argv) {
-  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, draft: false, onion: null, query: null, help: false };
+  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, draft: false, onion: null, query: null, vars: [], sizes: [], help: false };
   const need = (i, name) => { if (i + 1 >= argv.length) throw new Error(`${name} needs a value`); return argv[i + 1]; };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -94,6 +95,8 @@ export function parseArgs(argv) {
     else if (a === '--draft') o.draft = true;
     else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
     else if (a === '--at') o.at = need(i++, a);
+    else if (a === '--var') o.vars.push(parseVar(need(i++, a)));
+    else if (a === '--size') o.sizes.push(...parseSizes(need(i++, a)));
     else if (a === '--onion') {
       const m = need(i++, a).match(/^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/);
       if (!m || !(Number(m[1]) < Number(m[2]))) throw new Error(`--onion must look like 1:3 (seconds, from before to), got "${argv[i]}"`);
@@ -353,6 +356,13 @@ export async function runCheck(opts, log = console.log) {
       report.problems.push(`the page did not become ready (window.__ready !== true within 60 s${info?.hasMovie ? '' : '; window.movie is missing'})`);
       return finish(report, outDir, log);
     }
+    // --var / --size: the page is rebuilt once with what the command line gave (the first size; the others are looked at after the export)
+    if (opts.vars.length || opts.sizes.length) {
+      report.rebuilt = await applyToPage(cdp, opts.vars, opts.sizes[0] ?? null);
+      info = await cdp.eval(INFO).catch(() => info) ?? info;
+      report.logs = [...new Set([...(info?.logs ?? []), ...consoleLines])];
+    }
+    report.vars = await cdp.eval('JSON.parse(JSON.stringify((window.movie && window.movie.vars) || {}))').catch(() => ({}));
     Object.assign(report, { width: info.width, height: info.height, frameRate: info.frameRate, totalFrames: info.totalFrames, duration: info.duration, hasAudio: info.hasAudio });
     if (report.logs.length) report.problems.push(`${report.logs.length} console warning(s) / error(s) — each says what to change`);
 
@@ -500,6 +510,30 @@ export async function runCheck(opts, log = console.log) {
         report.exports.push(ex);
       }
     }
+
+    // --size A,B,…: the same movie at the other sizes, a layout review and a contact sheet each (the export above was the first size)
+    if (opts.sizes.length) {
+      report.sizes = [{ size: `${info.width}x${info.height}`, sheet: report.files.sheet, issues: report.inspect.issues, review: report.inspect.review }];
+      for (const size of opts.sizes.slice(1)) {
+        left();
+        const label = `${size.width}x${size.height}`;
+        await applyToPage(cdp, [], size);
+        const r = await cdp.eval(`movie.review(${JSON.stringify({ strict: !!opts.strict })})`);
+        const sheetAt = await cdp.eval(`movie.contactSheet({ count: ${opts.frames}, as: 'dataURL' })`);
+        const file = path.join(outDir, `sheet-${label}.png`);
+        fs.writeFileSync(file, Buffer.from(sheetAt.slice(sheetAt.indexOf(',') + 1), 'base64'));
+        report.files[`sheet ${label}`] = shown(file);
+        report.sizes.push({ size: label, sheet: shown(file), issues: r.problems, review: r.review });
+        if (r.problems.length) report.problems.push(`${r.problems.length} kind(s) of layout issue from movie.inspect at ${label}`);
+      }
+    }
+    // what the page said while the other sizes were built (the first list was taken before)
+    const later = await cdp.eval('window.__logs || []').catch(() => []);
+    const fresh = [...new Set([...later, ...consoleLines])].filter(l => !report.logs.includes(l));
+    if (fresh.length) {
+      report.logs.push(...fresh);
+      report.problems.push(`${fresh.length} more console warning(s) / error(s) while the page was built at the other size(s) — each says what to change`);
+    }
     return finish(report, outDir, log);
   } finally {
     try { chromeProc?.kill(); } catch { /* already gone */ }
@@ -519,6 +553,7 @@ function finish(report, outDir, log) {
   if (report.ready) L.push(`  page      ready in ${report.readySeconds} s · ${report.width}×${report.height} · ${report.frameRate} fps · ${report.totalFrames} frames (${report.duration} s)${report.hasAudio ? ' · audio' : ''}`);
   else L.push('  page      NOT READY');
   if (report.loadStages) L.push(`  loading   ${formatLoadStages(report.loadStages)}`);
+  if (report.vars && Object.keys(report.vars).length) L.push(`  vars      ${Object.entries(report.vars).map(([k, v]) => `${k}=${typeof v === 'string' && v.length > 40 ? v.slice(0, 37) + '…' : v}`).join(', ')}${report.rebuilt ? ' (after --var / --size: the page was built again)' : ''}`);
   L.push(`  warnings  ${report.logs?.length ? report.logs.length + ' — ' + report.logs.slice(0, 5).map(l => l.length > 220 ? l.slice(0, 217) + '…' : l).join('\n            ') + (report.logs.length > 5 ? `\n            … ${report.logs.length - 5} more (report.json)` : '') : 'none'}`);
   if (report.inspect) {
     const g = report.inspect.issues;
@@ -533,6 +568,11 @@ function finish(report, outDir, log) {
       if (rv.length > 4) L.push(`            … ${rv.length - 4} more (report.json)`);
     }
   }
+  if (report.sizes) {
+    const g = report.sizes;
+    L.push(`  sizes     ${g.map(x => `${x.size} ${x.issues.length ? x.issues.length + ' layout issue kind(s)' : 'no layout issue'}`).join(' · ')}${g.length > 1 ? ' (one contact sheet each: sheet.png, sheet-<size>.png)' : ''}`);
+    for (const x of g) for (const i of x.issues.slice(0, 3)) L.push(`            - ${x.size}: ${i.message}`);
+  }
   for (const w of (report.at ?? []).filter(x => x.depthBlur)) {
     const shown = Object.entries(w.depthBlur).slice(0, 8).map(([k, px]) => `${k} ${px} px`).join(', ');
     L.push(`  depth     ${w.label} — ${shown}${Object.keys(w.depthBlur).length > 8 ? ', …' : ''} (blur of each threeD layer at that moment; 0 = sharp)`);

package/ai/tools/render.mjs

@@ -26,6 +26,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { findChrome, findRoot, serve, launchChrome, shown, sleep, LOAD_PRESENT } from './check.mjs';
+import { parseVar, parseSizes, applyToPage } from './varArgs.mjs';
 
 const FORMATS = ['mp4', 'webm', 'mov', 'mkv', 'wav', 'ogg', 'pdf'];
 const SOUND_ONLY = ['wav', 'ogg'];
@@ -43,10 +44,10 @@ 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 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] [--var name=value] [--size 1080x1920] [--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, strict: 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, vars: [], size: 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];
@@ -81,6 +82,12 @@ export function parseRenderArgs(argv) {
       if (!(o.scale > 0 && o.scale <= 1)) throw new Error(`--scale must be above 0 and at most 1 (0.5 is half size), got "${argv[i]}"`);
     } else if (a === '--draft') o.draft = true;
     else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
+    else if (a === '--var') o.vars.push(parseVar(need(i++, a)));
+    else if (a === '--size') {
+      const sizes = parseSizes(need(i++, a));
+      if (sizes.length > 1) throw new Error('render writes one file: one --size (1080x1920); check takes several');
+      o.size = sizes[0];
+    }
     else if (a === '--all-stops') o.allStops = 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)');
@@ -178,6 +185,12 @@ export async function runRender(opts, log = console.log, progress = () => {}) {
       result.problems.push(`the page did not become ready (window.__ready !== true${info?.hasMovie ? '' : '; window.movie is missing'})${result.logs.length ? ': ' + result.logs[0] : ''}`);
       return result;
     }
+    // --var / --size: the page is built again with them before anything is drawn
+    if (opts.vars.length || opts.size) {
+      await applyToPage(cdp, opts.vars, opts.size);
+      info = await cdp.eval(`(() => { const m = window.movie; return { logs: window.__logs || [], duration: m.duration, totalFrames: m.totalFrames, width: m.width, height: m.height, frameRate: m.frameRate }; })()`);
+      result.logs = [...new Set([...info.logs, ...consoleLines])];
+    }
     Object.assign(result, { duration: info.duration, frames: info.totalFrames, width: info.width, height: info.height, frameRate: info.frameRate });
 
     await cdp.eval(renderScript(opts.format, opts.quality, opts.videoCodec, opts.audioCodec, opts.motionBlur, opts.shutter, opts.allStops, { range: opts.range, scene: opts.scene, scale: opts.scale, draft: opts.draft, qualityGiven: opts.qualityGiven }, opts.videoBitrate));

package/ai/tools/varArgs.mjs

@@ -0,0 +1,75 @@
+/**
+ * `--var name=value` and `--size WxH` for `pixi-effects check` and `render`: read here, matched against what the page declares
+ * (`movie.vars`), then the tool calls `movie.rebuild({ vars, width, height })` once the page is ready. The page needs nothing for this.
+ */
+
+/** 'lang=en' → ['lang', 'en'] (the value is the rest of the text; the page decides whether it is a number). */
+export function parseVar(text) {
+  const m = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/.exec(text);
+  if (!m) throw new Error(`--var must look like name=value (lang=en, shift=40, accent=#e5399a), got "${text}"`);
+  return [m[1], m[2]];
+}
+
+/** '1920x1080,1080x1920' → [{ width, height }, …]. */
+export function parseSizes(text) {
+  const bad = () => new Error(`--size must look like 1920x1080 (whole pixels; several with a comma: 1920x1080,1080x1920), got "${text}"`);
+  const out = String(text).split(',').map(part => {
+    const m = /^\s*(\d+)\s*[xX×]\s*(\d+)\s*$/.exec(part);
+    if (!m || Number(m[1]) < 1 || Number(m[2]) < 1) throw bad();
+    return { width: Number(m[1]), height: Number(m[2]) };
+  });
+  if (!out.length) throw bad();
+  return out;
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]; row[0] = i;
+    for (let j = 1; j <= b.length; j++) { const keep = row[j]; row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1)); prev = keep; }
+  }
+  return row[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?.c ?? null;
+};
+
+/** The pairs from `--var`, as the values the page's variables take: a number variable gets a number, a string variable the text. `declared` is `movie.vars`. */
+export function coerceVars(pairs, declared) {
+  const names = Object.keys(declared);
+  const out = {};
+  for (const [name, raw] of pairs) {
+    if (!names.length) throw new Error(`--var ${name}: the page declares no variables (declare them in movie.init({ vars: { ${name}: … }, … }))`);
+    if (!Object.prototype.hasOwnProperty.call(declared, name)) {
+      const guess = nearestOf(name, names);
+      throw new Error(`--var ${name}: the page declares no variable "${name}"${guess ? ` — did you mean "${guess}"?` : ''} (declared: ${names.join(', ')})`);
+    }
+    if (typeof declared[name] === 'number') {
+      const n = raw.trim() === '' ? NaN : Number(raw);
+      if (!Number.isFinite(n)) throw new Error(`--var ${name}=${raw}: "${name}" is a number in the page (it declares ${declared[name]}), got "${raw}"`);
+      out[name] = n;
+    } else out[name] = raw;
+  }
+  return out;
+}
+
+/**
+ * Once the page is ready: set the variables and the size the command line gave, with one `movie.rebuild`. Returns the rebuild report, or null when
+ * nothing was asked. `cdp.eval` is the command's page connection. A refusal (an unknown name, a rebuild that failed) is thrown as a usage error.
+ */
+export async function applyToPage(cdp, pairs, size) {
+  if (!pairs.length && !size) return null;
+  if (await cdp.eval("typeof (window.movie && window.movie.rebuild)") !== 'function') throw new Error("this page's pixi-effects is older than --var / --size: use 0.31 or newer (the version in the page's import map)");
+  const declared = await cdp.eval('JSON.parse(JSON.stringify((window.movie && window.movie.vars) || {}))');
+  const given = coerceVars(pairs, declared);
+  const change = { ...(Object.keys(given).length ? { vars: given } : {}), ...(size ?? {}) };
+  const answer = JSON.parse(await cdp.eval(`(async () => {
+    try {
+      return JSON.stringify({ report: await movie.rebuild(${JSON.stringify(change)}) });
+    } catch (e) { return JSON.stringify({ error: String((e && e.message) || e) }); }
+  })()`));
+  if (answer.error) throw new Error(`${answer.error.replace(/^pixi-effects: /, '')} (while applying ${[...pairs.map(([n, v]) => `--var ${n}=${v}`), size ? `--size ${size.width}x${size.height}` : ''].filter(Boolean).join(' ')})`);
+  return answer.report;
+}

package/dist/{Base-CB1_FPZD.d.cts → Base-BKagtWc0.d.cts}

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

package/dist/{Base-Ne74ztNl.d.ts → Base-jRiMHcWT.d.ts}

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

package/dist/Composition-DQCPJPFE.js

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

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

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

package/dist/Composition-V2XYSW6P.cjs

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

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

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

package/dist/Controller.cjs

@@ -81,6 +81,7 @@ var CONTROLLER_CSS = `
   transition: opacity 120ms ease;
 }
 .mc-btn:hover { opacity: 1; }
+.mc-loop[aria-pressed="true"] { opacity: 1; color: var(--mc-accent); }
 .mc-btn:disabled { opacity: 0.4; cursor: not-allowed; }
 .mc-time {
   font-size: 12px; font-family: Menlo, Monaco, monospace;
@@ -262,6 +263,7 @@ var ICONS = {
   pause: '<svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor"><rect x="3" y="2" width="3.5" height="12"/><rect x="9.5" y="2" width="3.5" height="12"/></svg>',
   volumeOn: '<svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor"><path d="M2 6 H5 L9 2 V14 L5 10 H2 Z"/><path d="M11 5 Q13 8 11 11" fill="none" stroke="currentColor" stroke-width="1.2"/><path d="M12.5 3.5 Q15.5 8 12.5 12.5" fill="none" stroke="currentColor" stroke-width="1.2"/></svg>',
   volumeOff: '<svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor"><path d="M2 6 H5 L9 2 V14 L5 10 H2 Z"/><path d="M11 5 L15 11 M15 5 L11 11" fill="none" stroke="currentColor" stroke-width="1.4"/></svg>',
+  loop: '<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7 V6 Q3 4 5 4 H12"/><path d="M10 2 L12.5 4 L10 6"/><path d="M13 9 V10 Q13 12 11 12 H4"/><path d="M6 14 L3.5 12 L6 10"/></svg>',
   download: '<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2 V11 M4 7 L8 11 L12 7 M3 13 H13"/></svg>',
   fullscreenEnter: '<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M2 6 V2 H6 M14 6 V2 H10 M2 10 V14 H6 M14 10 V14 H10"/></svg>',
   present: '<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M2 2.5 H14 V10.5 H2 Z M8 10.5 V13.5 M5 13.5 H11"/></svg>',
@@ -293,7 +295,7 @@ var THEME_PROPERTIES = {
   trackHeight: "--mc-track-height",
   font: "--mc-font"
 };
-var CONTROLLER_OPTION_KEYS = ["canvas", "theme", "exportButton", "keyboard", "clickToPlay", "presentButton", "pauseAtStops", "className"];
+var CONTROLLER_OPTION_KEYS = ["canvas", "theme", "exportButton", "keyboard", "clickToPlay", "presentButton", "pauseAtStops", "loopButton", "className"];
 var Controller = class _Controller {
   movie;
   options;
@@ -311,6 +313,8 @@ var Controller = class _Controller {
   progressThumbEl;
   playBtn;
   muteBtn;
+  loopBtn = null;
+  onLoopChange = null;
   timeEl;
   exportBtn = null;
   settingsPopoverEl = null;
@@ -335,6 +339,8 @@ var Controller = class _Controller {
   settingsKeyHandler = null;
   settingsOutsideHandler = null;
   onReady = null;
+  /** A rebuild (setVars, resize, rebuild) may have moved the stops: draw their marks again. */
+  onRebuilt = null;
   presenter = null;
   /** `pixi-effects/present`, loaded as soon as the movie has stops (a press of play must not wait for it). */
   present = null;
@@ -380,6 +386,7 @@ var Controller = class _Controller {
       clickToPlay: options.clickToPlay ?? true,
       presentButton: options.presentButton ?? true,
       pauseAtStops: options.pauseAtStops ?? true,
+      loopButton: options.loopButton ?? true,
       className: options.className ?? "movie-controller"
     };
     installStyles();
@@ -403,6 +410,7 @@ var Controller = class _Controller {
     if (this.options.clickToPlay) this.bindCanvasClick();
     this.bindScrubbing();
     this.bindMuteButton();
+    this.bindLoopButton();
     this.bindVolumeSlider();
     this.bindExportPopover();
     this.bindFullscreen();
@@ -447,6 +455,7 @@ var Controller = class _Controller {
             <div class="mc-vol-thumb"></div>
           </div>
         </div>
+        ${this.options.loopButton ? `<button class="mc-btn mc-loop" aria-label="Loop" aria-pressed="false" title="Loop (L)">${ICONS.loop}</button>` : ""}
         <span class="mc-time">0:00 / 0:00</span>
         <div class="mc-spacer"></div>
         ${this.options.exportButton ? `<button class="mc-btn mc-export" aria-label="Export" aria-expanded="false">${ICONS.download}</button>` : ""}
@@ -577,7 +586,11 @@ var Controller = class _Controller {
       this.exportFillEl.style.width = `${progress}%`;
       this.exportTextEl.textContent = `${progress}% (${frame} / ${totalFrames} frames)`;
     };
+    this.onRebuilt = () => {
+      this.refreshStops();
+    };
     this.movie.on("ready", this.onReady);
+    this.movie.on("rebuilt", this.onRebuilt);
     this.movie.on("frame", this.onFrame);
     this.movie.on("play", this.onPlay);
     this.movie.on("pause", this.onPause);
@@ -712,6 +725,20 @@ var Controller = class _Controller {
     this.playBtn.innerHTML = this.movie.isPlaying ? ICONS.pause : ICONS.play;
     this.playBtn.setAttribute("aria-label", this.movie.isPlaying ? "Pause" : "Play");
   }
+  bindLoopButton() {
+    this.loopBtn = this.root.querySelector(".mc-loop");
+    if (!this.loopBtn) return;
+    const refresh = () => {
+      this.loopBtn.setAttribute("aria-pressed", String(this.movie.loop));
+    };
+    this.loopBtn.addEventListener("click", () => {
+      this.movie.loop = !this.movie.loop;
+      refresh();
+    });
+    this.onLoopChange = refresh;
+    this.movie.on("loopchange", this.onLoopChange);
+    refresh();
+  }
   bindMuteButton() {
     this.muteBtn.addEventListener("click", () => {
       this.movie.toggleMute();
@@ -1124,6 +1151,12 @@ var Controller = class _Controller {
           e.preventDefault();
           this.muteBtn.click();
           break;
+        case "KeyL":
+          if (this.loopBtn) {
+            e.preventDefault();
+            this.loopBtn.click();
+          }
+          break;
         case "KeyE":
           if (e.shiftKey && this.exportBtn) {
             e.preventDefault();
@@ -1158,6 +1191,14 @@ var Controller = class _Controller {
       this.movie.off("ready", this.onReady);
       this.onReady = null;
     }
+    if (this.onRebuilt) {
+      this.movie.off("rebuilt", this.onRebuilt);
+      this.onRebuilt = null;
+    }
+    if (this.onLoopChange) {
+      this.movie.off("loopchange", this.onLoopChange);
+      this.onLoopChange = null;
+    }
     if (this.onFrame) {
       this.movie.off("frame", this.onFrame);
       this.onFrame = null;