pixi-effects 0.30.1 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.32.0
+
+**`spans`: colour and style inside one text layer, and the papercuts of five films (planned as 0.32)**
+
+- **`spans`** (design: `docs/superpowers/specs/2026-10-12-spans-design.md`): a text layer takes `spans: [{ text: 'type', fill: '#7fa07f' }, ': ', { text: "'a'", fill: '#ffd166', fontWeight: '700' }, ',\n next']` instead of `text`. A span changes `fill`, `fontWeight`, `fontStyle`, `fontVariant`, `letterSpacing` or `dropShadow` (a size, a font, `lineHeight`, `align` or a `stroke` is warned about and ignored: they belong to the layer's `style`; the style's expressions and variables are resolved before measuring, and a missing `fontSize` is measured as the text layer's default); `\n` starts a line; `style.align` places the lines. At build time the layer becomes a group of ordinary text layers `<name>.0 …` (so every keyframe, filter and mask works, `anchorX` / `anchorY` centre the whole block, `inspect`, `check` and the timeline view see the pieces); a `visibleChars` typewriter counts over all the spans, the newline included; `{name}` variables inside spans are read before the layout, so `setVars` lays the line out again. Needs the font loaded, like `splitText`. The films needed one text layer per token to stream coloured code.
+- **A dotted keyframe key on a filter now moves the leaf of a point option** (`'filters.s.red.x'`): it used to be written as a property literally named `red.x` and nothing moved, silently. A path that leads nowhere is warned about once. The docs said both that it works and that it does not; they say one true sentence now (the whole point `red: { x, y }` as a keyframe value still does not tween).
+- **Filter options are copied** when the filter is made: a keyframe on `'filters.s.red.x'` writes the leaf of the point in place, which wrote into the author's spec object (after a `rebuild` a `to` keyframe then started from the last frame that had been drawn). A dotted key in `initial` / a `set` is a path too.
+- **`pixi-effects render` prints the length of the FILE** (it printed the length of the whole movie for a `--range` or `--scene`).
+- **A property written on a layer instead of in `initial`** (`z`, `x`, `alpha`, `rotationX` …) now says "put it in `initial`" instead of guessing another key ("did you mean d?" on a path).
+- **The depth-of-field warning says where it starts** ("it warns from 20") and has a test.
+- Docs: `animateText` without `out` (the pieces stay), what the default `dissolve` looks like (blotches; `scale: 200` is grain), a `path` in canvas coordinates takes no `x` / `y`. The roadmap's 0.32 list was checked against the 0.31.0 build before work began: of 11 gaps reported by AI agents, 6 were already documented or warned about.
+
+**Landing: two 45-second films next to the reel**
+
+- `examples/films/ink-and-paper.html` and `examples/films/light-as-material.html`: two films, each one HTML page of data, played live from the landing page on a click (the same way as the reel). They open in a terminal where an AI is asked for a video and then combine Rough.js, D3 and three.js with the library's own features (springs, particles, shaders, warp, light and shadows, depth of field, camera paths, time remap, music and sfx written as text). Written by an AI model from the docs and a short brief. Their web fonts load inside the film pages only; the landing page itself still loads nothing from third parties.
+- They are not gallery pieces (the gallery's rules are 8–14 s and no third-party fonts), so the gallery's 52 is unchanged.
+- A browser test: each of the two cards loads its page on a click, the page is ready and logs nothing.
+
+## 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.32.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.32.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.32.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.32.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.32.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.32.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.32.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.32.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)');
@@ -117,12 +124,28 @@ const renderScript = (format, quality, videoCodec, audioCodec, motionBlur, shutt
         : 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 + ')');
-      window.__r = { state: 'done', bytes: blob.size, type: blob.type };
+      // how long the FILE is (a range or a scene is shorter than the movie): ask a media element, which reads the metadata of what was written; null when it cannot
+      let length = null;
+      try {
+        if (${JSON.stringify(format)} !== 'pdf') {
+          const el = document.createElement(${SOUND_ONLY.includes(format) ? "'audio'" : "'video'"}); el.preload = 'metadata'; el.muted = true; el.src = URL.createObjectURL(blob);
+          length = await new Promise(res => { el.onloadedmetadata = () => res(Number.isFinite(el.duration) ? Math.round(el.duration * 10) / 10 : null); el.onerror = () => res(null); setTimeout(() => res(null), 5000); });
+          URL.revokeObjectURL(el.src);
+        }
+      } catch { /* the length stays unknown: the command falls back to the movie's */ }
+      window.__r = { state: 'done', bytes: blob.size, type: blob.type, length };
     } catch (e) { window.__r = { state: 'error', message: String((e && e.message) || e) }; }
   })();
   return 0;
 })()`;
 
+/** The length to print: the file's own (read in the page); when that could not be read, the range asked for, and only then the whole movie's. */
+export function fileSeconds(r, opts) {
+  if (r.length != null) return r.length;
+  if (opts.range && r.duration != null) return Math.round(((opts.range[1] ?? r.duration) - (opts.range[0] ?? 0)) * 10) / 10;
+  return r.duration;
+}
+
 export async function runRender(opts, log = console.log, progress = () => {}) {
   const pagePath = path.resolve(opts.page);
   if (!fs.existsSync(pagePath)) throw new Error(`page not found: ${opts.page}`);
@@ -178,6 +201,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));
@@ -196,6 +225,7 @@ export async function runRender(opts, log = console.log, progress = () => {}) {
     fs.renameSync(part, out);
     result.file = out;
     result.bytes = written;
+    result.length = result.render?.length ?? null;                   // the file's own length; a range or a scene is not the whole movie
     result.seconds = Math.round((Date.now() - t0) / 100) / 10;
     return result;
   } finally {
@@ -231,7 +261,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process
       console.error(`pixi-effects render failed: ${r.problems.join('; ') || 'no file written'}`);
       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`);
+    console.log(`${shown(r.file)}  ${kb(r.bytes)} · ${fileSeconds(r, opts)} 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.strict && r.logs.length ? 1 : 0);
   } catch (e) {
     console.error(`pixi-effects render failed: ${e.message}`);

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-Ne74ztNl.d.ts → Base-CXsMdmJB.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-CavnUvd5.js';
 
 /**
  * Resolves a routed keyframe path to a concrete tween target.

package/dist/{Base-CB1_FPZD.d.cts → Base-pNq6sVGl.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-CavnUvd5.cjs';
 
 /**
  * Resolves a routed keyframe path to a concrete tween target.

package/dist/Composition-LNMKWXSL.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkCRUDOKSD_cjs = require('./chunk-CRUDOKSD.cjs');
+require('./chunk-QHDN6TF5.cjs');
+require('./chunk-Z437UWI4.cjs');
+require('./chunk-FCGYJCVO.cjs');
+require('./chunk-TWZNOUM7.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkCRUDOKSD_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-LNMKWXSL.cjs.map
+//# sourceMappingURL=Composition-LNMKWXSL.cjs.map

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

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

package/dist/Composition-RF7QOEXT.js

@@ -0,0 +1,7 @@
+export { CompositionSequence } from './chunk-D5BFQVKL.js';
+import './chunk-AW5NPDE4.js';
+import './chunk-QFNS6BFL.js';
+import './chunk-C5BNHVKK.js';
+import './chunk-BXOCEZ4U.js';
+//# sourceMappingURL=Composition-RF7QOEXT.js.map
+//# sourceMappingURL=Composition-RF7QOEXT.js.map

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

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

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;