pixi-effects 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.36.0
+
+**Vertical writing, `check` that sees pictures over text, holes in paths, and the fixes found by 18 fresh authors (the claims that were verified on the real build)**
+
+- **New: vertical writing (tategaki).** `animateText(..., { vertical: true })` and `splitText(..., { vertical: true })`: characters go down a column and a new line is a new column to the left (`x` is the right edge of the first column). 、。 sit at the upper right of their cell, small kana a little up and right, and the long vowel mark, dashes, waves and brackets are turned a quarter clockwise (`rotation: 90`); pieces carry `cx` / `cy` / `rotation`. No tate-chu-yoko and no automatic line breaking.
+- **New: `check` lists an opaque shape or image drawn over part of a text, and a thin line drawn over its body** (review list, with the other overlaps; a shadow, glow, ring or backdrop is not reported), **`check --at … --crop X,Y,W,H`** writes each picture as that part of the canvas, enlarged up to 4x, and **`help`** finds a heading written with spaces (`motionBlur`), a table row (`path`) and a call (`steps`).
+- **New: `format: { time: 'hh:mm' }`** (also `'hh:mm:ss'`, `'h:mm:ss'`, `'mm:ss'`, `'m:ss'`) prints a counter's value, in seconds, as a clock; **`resolution`** on a text layer (1–8) draws it at N× the pixels so text inside a group scaled up N× stays sharp; **image `scaleMode: 'nearest'`** for pixel art; **`inspectAudio`** gives each source `belowMixDb` (how far below the mix around its loudest moment it is) and `check` gives ONE note when short sfx sit more than 12 dB under the mix ("buried", naming the worst).
+- **Guide demos load this repository's build** (`../../dist/…`), like the gallery pages, so a demo shows the code of the same commit.
+- **Fixed: `initial: { fill }` on a text layer was dropped without a word** (only a `fill` keyframe worked). It is now the colour from the start (it wins over `style.fill`).
+- **Fixed: a filter option set to `undefined` (a misspelt variable) overwrote the filter's own default**: `{ type: 'bloom', strength: undefined }` made `movie.init` fail with "Cannot read properties of undefined (reading 'x')". The key is now left out and a warning names the filter and the options.
+- **`check --at`** no longer leaves the pictures of an earlier run in `frames/` (it cleared nothing, so an old frame could be taken for the current one). The music read-back no longer says "ends early" for a track that is a few millionths of a beat shorter (decimal note lengths add up with float noise).
+- **`pixi-effects new --size`** sizes the shown page for a tall or square movie (it was 960 px wide, so a 9:16 page was 1700 px tall).
+- **New: `fillRule: 'evenodd'` on a `path`** (a donut written as two circles in one `d` was a solid disc: sub-paths were never holes). The biggest sub-path is the shape, every other one is cut out of it, and the stroke goes round all of them.
+- **Changed: a morph between two outlines with the same number of corners is paired corner to corner** (it resampled both to 128 points along the edges, so a morph between two quads whose edges are not in proportion rounded the corners half way). Outlines with different corner counts, and curves, behave as before.
+- Docs: a keyframe's `from` holds from the start of the layer and beats `initial` (cheatsheet, pitfall 114: no warning, because `initial` = the resting value and `from` = where it starts is what the recipes do); a path's `x` / `y`, when given, place its middle.
+- Docs: `--out DIR` writes straight into DIR (no `<name>/` inside); pitfalls 112 (text under a scaled-up parent is soft) and 113 (an `sfx` lasts at most 10 s, a `music` layer plays 16 tracks).
+- Gallery and guide: 59 pieces (18 new, 17 swapped, 11 removed); the guide no longer shows gallery pieces (its demos are built from its own recipes, `scripts/build-guide-demos.mjs`); `scripts/gallery-swap.mjs` also adds (`--add`) and removes (`--remove`).
+
+## 0.35.0
+
+**The player's seek-bar preview (`thumbnails: true`, off by default) and `movie.thumbnail()`**
+
+- **`movie.thumbnail(frame, { width? | scale? })`** gives a small canvas of any frame **without moving the playhead or changing the picture**, also while the movie plays. It draws the frame on the side inside one task (nominal time set, 3D / shader layers awaited, the playhead put back and awaited), so the browser never shows the in-between; it equals `snapshot({ motionBlur: false })` at that size. `null` when a seek, render or another thumbnail is running. Seeks, renders and peeks wait for a running thumbnail, so they never interleave with it.
+- **`movie.thumbnailsOff`** is `'variables'` for a movie that declares variables and `'video'` for one with a video layer, else `null`; `thumbnail()` gives `null` then (a video would have to seek twice, a variable movie can be re-laid out under it).
+- **`new Controller(movie, { canvas, thumbnails: true })`**: hover (or move along) the seek bar and a 160 px picture with the time appears above it, kept inside the picture, hidden while dragging; pictures are cached per tenth of a second until a rebuild. Default off.
+- Tests: `tests/tools/thumbnail.test.ts` (exact against `snapshot`, undisturbed canvas and playhead, playback with a thumbnail per frame, the off reasons, options) and `tests/tools/thumbnailPreview.test.ts` (the bar, with real mouse moves).
+
 ## 0.34.0
 
 **From the capability probe of 2026-10-12 (15 kinds of video tried by fresh agents; nothing was impossible, 9 needed hand-written glue; these are the defects that were verified on the real build)**

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.34.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.36.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.34.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.34.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.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.34.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.36.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.34.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.0/dist/three.js"
   }
 }
 </script>

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.34.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.34.0/dist/Controller.js",
-      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.34.0/dist/present.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.36.0/dist/present.js"
     }
   }
   </script>

package/ai/tools/check.mjs

@@ -7,7 +7,7 @@
  * 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
  * (grouped), `movie.inspectAudio()`, a contact sheet (a PNG you can look at), and a real export (`movie.render`) that it
- * decodes again: video size / length, audio length, loudness per second, silence. Output goes to `check-out/<name>/`
+ * decodes again: video size / length, audio length, loudness per second, silence. Output goes to `check-out/<name>/` (`--out DIR` writes straight into DIR, with no <name>/ inside it)
  * (`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.
@@ -15,6 +15,7 @@
  *
  * 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) ·
+ *          --crop X,Y,W,H (with --at: each picture is that part of the canvas, in canvas pixels, enlarged up to 4x so a small figure can be judged) ·
  *          --onion A:B (one picture of the movement between A and B seconds, frames overlaid: onion.png) ·
  *          --strict (text overlaps and stops where the picture is still changing fail the check; by default they are only listed for review) · --out DIR · --frames N (contact sheet tiles, default 12) · --formats mp4,webm (default mp4) · --no-export ·
  *          --timeout SECONDS (default 240) · --root DIR (static server root; default: the nearest folder above the page with dist/) · --chrome PATH
@@ -44,8 +45,8 @@ export function formatMusic(sources) {
     out.push(`  music     ${s.layer} · ${num(m.bpm)} bpm · ${num(m.beats)} beats = ${num(m.bars)} bars of ${m.meter} beats${assumed} · ${num(Math.round(m.seconds * 10) / 10)} s (+ ${num(m.tail)} s tail)`);
     for (const t of m.tracks) {
       const whole = Math.abs(t.bars - Math.round(t.bars)) < 1e-6;
-      // a track shorter than the longest stops early (whatever its length in bars); a short BAR can only be the longest track's, and only the author's meter can say so
-      const note = t.beats < m.beats - 1e-6 ? ` (ends early: silent from beat ${num(t.beats)})` : !whole && m.meterSet !== false ? ' (not a whole number of bars: a bar is short)' : '';
+      // a track shorter than the longest stops early (whatever its length in bars; decimal note lengths add up with float noise, so a gap under 1e-4 of a beat is none); a short BAR can only be the longest track's, and only the author's meter can say so
+      const note = t.beats < m.beats - 1e-4 ? ` (ends early: silent from beat ${num(t.beats)})` : !whole && m.meterSet !== false ? ' (not a whole number of bars: a bar is short)' : '';
       const cell = names => { const n = names.match(/\[[^\]]*\]\S*|\S+/g) ?? []; return n.length === 0 ? '–' : n.length > 4 ? `${n.slice(0, 4).join(' ')} …` : n.join(' '); };
       const shown = t.perBar.slice(0, 16).map(cell).join(' | ');
       out.push(`${pad}${t.inst.padEnd(6)} ${num(t.bars)} bar${t.bars === 1 ? '' : 's'}${note} | ${shown}${t.perBar.length > 16 ? ` | … (${t.perBar.length - 16} more)` : ''}`);
@@ -79,10 +80,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] [--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 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] [--crop X,Y,W,H] [--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, vars: [], sizes: [], help: false };
+  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, crop: 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];
@@ -95,6 +96,11 @@ 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 === '--crop') {
+      const m = need(i++, a).split(',').map(Number);
+      if (m.length !== 4 || !m.every(Number.isFinite) || m[0] < 0 || m[1] < 0 || m[2] < 1 || m[3] < 1) throw new Error(`--crop must look like 100,200,400,300 (x, y, width, height in canvas pixels, width and height at least 1), got "${argv[i]}"`);
+      o.crop = { x: Math.round(m[0]), y: Math.round(m[1]), width: Math.round(m[2]), height: Math.round(m[3]) };
+    }
     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') {
@@ -109,6 +115,7 @@ export function parseArgs(argv) {
     else if (!o.page) o.page = a;
     else throw new Error(`unexpected argument ${a}`);
   }
+  if (o.crop && !o.at) throw new Error('--crop crops the pictures of --at: give --at too (for example --at 3.5 --crop 100,200,400,300)');
   return o;
 }
 
@@ -377,6 +384,7 @@ export async function runCheck(opts, log = console.log) {
       if (r.error) throw new Error(r.error.replace(/^pixi-effects: /, ''));
       atList = r.at;
     }
+    if (opts.crop && (opts.crop.x + opts.crop.width > info.width || opts.crop.y + opts.crop.height > info.height)) throw new Error(`--crop ${opts.crop.x},${opts.crop.y},${opts.crop.width},${opts.crop.height} goes past the canvas (${info.width}×${info.height})`);
     if (opts.onion && opts.onion[1] > info.duration + 1e-9) throw new Error(`--onion ${opts.onion[0]}:${opts.onion[1]} goes past the end: the movie is ${info.duration} s`);
 
     const rv = await cdp.eval(`movie.review(${JSON.stringify({ strict: !!opts.strict })})`);
@@ -398,8 +406,16 @@ export async function runCheck(opts, log = console.log) {
       const wanted = atList;
       const framesDir = path.join(outDir, 'frames');
       fs.mkdirSync(framesDir, { recursive: true });
+      for (const old of fs.readdirSync(framesDir)) if (old.endsWith('.png')) fs.rmSync(path.join(framesDir, old));        // the pictures of an earlier run: frames/ shows this run's moments only
+      // --crop: that part of the canvas, enlarged by a whole factor (up to 4x, the longer side to about 800 px) with no smoothing, so small figures and fine lines can be judged
+      const crop = opts.crop ? { ...opts.crop, scale: Math.max(1, Math.min(4, Math.floor(800 / Math.max(opts.crop.width, opts.crop.height)))) } : null;
+      const cropped = [];
       for (const w of wanted) {
-        const png = await cdp.eval(`movie.snapshot(${w.frame}, { as: 'dataURL' })`);
+        let png = await cdp.eval(`movie.snapshot(${w.frame}, { as: 'dataURL' })`);
+        if (crop) {
+          png = await cdp.eval(`(async (url, c) => { const img = new Image(); img.src = url; await img.decode(); const cv = document.createElement('canvas'); cv.width = c.width * c.scale; cv.height = c.height * c.scale; const g = cv.getContext('2d'); g.imageSmoothingEnabled = false; g.drawImage(img, c.x, c.y, c.width, c.height, 0, 0, cv.width, cv.height); return cv.toDataURL('image/png'); })(${JSON.stringify(png)}, ${JSON.stringify(crop)})`);
+          cropped.push(png);
+        }
         fs.writeFileSync(path.join(framesDir, `${w.label}.png`), Buffer.from(png.slice(png.indexOf(',') + 1), 'base64'));
         // depth of field: the blur (px) each threeD layer has at this moment, so a focus pull can be read as numbers (0 = sharp)
         const rows = await cdp.eval(`movie.inspect(${w.frame}).then(r => r.layers.filter(l => l.depthBlur !== undefined).map(l => [l.path, l.depthBlur]))`).catch(() => []);
@@ -408,12 +424,15 @@ export async function runCheck(opts, log = console.log) {
         const lit = await cdp.eval(`movie.inspect(${w.frame}).then(r => r.layers.filter(l => l.light !== undefined).map(l => [l.path, l.light]))`).catch(() => []);
         if (lit.length) w.light = Object.fromEntries(lit);
       }
-      const atSheet = await cdp.eval(`movie.contactSheet({ frames: ${JSON.stringify(wanted.map(w => w.frame))}, as: 'dataURL' })`);
+      const atSheet = crop
+        ? await cdp.eval(`(async (urls) => { const imgs = await Promise.all(urls.map(async u => { const i = new Image(); i.src = u; await i.decode(); return i; })); const cols = Math.min(imgs.length, 3), rows = Math.ceil(imgs.length / cols), w = imgs[0].width, h = imgs[0].height; const cv = document.createElement('canvas'); cv.width = cols * w; cv.height = rows * h; const g = cv.getContext('2d'); imgs.forEach((im, k) => g.drawImage(im, (k % cols) * w, Math.floor(k / cols) * h)); return cv.toDataURL('image/png'); })(${JSON.stringify(cropped)})`)
+        : await cdp.eval(`movie.contactSheet({ frames: ${JSON.stringify(wanted.map(w => w.frame))}, as: 'dataURL' })`);
       const atFile = path.join(outDir, 'at.png');
       fs.writeFileSync(atFile, Buffer.from(atSheet.slice(atSheet.indexOf(',') + 1), 'base64'));
       report.files.at = shown(atFile);
       report.files.frames = shown(framesDir);
       report.at = wanted;
+      if (crop) report.crop = crop;
     }
 
     // --onion A:B: one picture of the movement between A and B seconds (8 frames overlaid, the later the stronger)

package/ai/tools/lookup.mjs

@@ -105,9 +105,19 @@ export function searchDocs(root, word) {
       const heading = s.heading.toLowerCase();
       const body = s.lines.join('\n').toLowerCase();
       if (!tokens.every(t => body.includes(t))) continue;
-      const inHeading = tokens.every(t => heading.includes(t));
+      const flat = (x) => x.replace(/[^a-z0-9]/g, '');                       // "motionBlur" is the heading "Motion blur"
+      const inHeading = tokens.every(t => heading.includes(t) || (flat(t).length > 2 && flat(heading).includes(flat(t))));
       const count = tokens.reduce((n, t) => n + body.split(t).length - 1, 0);
-      scored.push({ s, score: (inHeading ? 1000 : 0) + Math.min(count, 50) + bonus });
+      // the word as a table row (`| \`path\` | …`, the first cell) or as a call in code (`steps(n)`) says the section is ABOUT it, not that it only mentions it
+      const row = tokens.some(t => s.lines.some(l => new RegExp(`^\\|\\s*\\*{0,2}\\x60${t.replace(/[^a-z0-9]/g, '')}\\x60`).test(l.toLowerCase())));
+      const calls = (t) => {                                                 // the word followed by a bracket INSIDE code: a fenced block or an inline `span` (not prose that has a bracket after it)
+        const w = t.replace(/[^a-z0-9]/g, ''), re = new RegExp(`\\b${w}\\s*\\(`);
+        const fences = [...body.matchAll(/```[\s\S]*?```/g)].map(m => m[0]);
+        const inline = [...body.replace(/```[\s\S]*?```/g, ' ').matchAll(/`([^`\n]+)`/g)].map(m => m[1]);
+        return [...fences, ...inline].some(code => re.test(code));
+      };
+      const call = tokens.some(calls);
+      scored.push({ s, score: (inHeading ? 1000 : 0) + (row ? 1100 : 0) + (call ? 300 : 0) + Math.min(count, 50) + bonus });
     }
   }
   scored.sort((a, b) => b.score - a.score);
@@ -155,6 +165,8 @@ export function newPage(name, { cwd = process.cwd(), root = PACKAGE_ROOT, force
     .replace('<title>pixi-effects video</title>', `<title>${base.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</title>`)
     // the size sits in two places (the canvas attributes and W / H) and the length in one; the poster follows DURATION
     .replace('<canvas id="stage" width="1280" height="720">', size ? `<canvas id="stage" width="${size.width}" height="${size.height}">` : '<canvas id="stage" width="1280" height="720">')
+    // a tall or square page would be 960 px wide and far taller than a laptop screen: its width follows a height of about 760 px
+    .replace('.stage { position: relative; width: min(960px, 100%); }', size ? `.stage { position: relative; width: min(${Math.min(960, Math.round(760 * size.width / size.height))}px, 100%); }` : '.stage { position: relative; width: min(960px, 100%); }')
     .replace('const W = 1280, H = 720, FPS = 30, DURATION = 6;', `const W = ${size ? size.width : 1280}, H = ${size ? size.height : 720}, FPS = 30, DURATION = ${duration ?? 6};`);
   fs.writeFileSync(file, html);
   return { file };

package/dist/{Base-CXsMdmJB.d.ts → Base-CdF7AJop.d.ts}

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

package/dist/{Base-pNq6sVGl.d.cts → Base-CmiFiwQM.d.cts}

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

package/dist/Composition-BMRCE5FH.js

@@ -0,0 +1,7 @@
+export { CompositionSequence } from './chunk-AZ6AINSW.js';
+import './chunk-G3DX65HO.js';
+import './chunk-WIIU42FH.js';
+import './chunk-2JFFKHXO.js';
+import './chunk-BXOCEZ4U.js';
+//# sourceMappingURL=Composition-BMRCE5FH.js.map
+//# sourceMappingURL=Composition-BMRCE5FH.js.map

package/dist/{Composition-NDXKQHB4.js.map → Composition-BMRCE5FH.js.map}

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

package/dist/Composition-XRLYR6GL.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkY5UWFH6Y_cjs = require('./chunk-Y5UWFH6Y.cjs');
+require('./chunk-KJSEQVBV.cjs');
+require('./chunk-NEUPEENI.cjs');
+require('./chunk-42ML5AKN.cjs');
+require('./chunk-TWZNOUM7.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkY5UWFH6Y_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-XRLYR6GL.cjs.map
+//# sourceMappingURL=Composition-XRLYR6GL.cjs.map

package/dist/{Composition-OLH7RC5Z.cjs.map → Composition-XRLYR6GL.cjs.map}

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

package/dist/Controller.cjs

@@ -63,6 +63,19 @@ var CONTROLLER_CSS = `
 .mc-progress:hover .mc-progress-thumb,
 .mc-progress.mc-scrubbing .mc-progress-thumb { transform: translate(-50%, -50%) scale(1); }
 
+.movie-controller > .mc-preview {
+  position: absolute; bottom: 74px; left: 0;
+  transform: translateX(-50%);
+  display: flex; flex-direction: column; align-items: center; gap: 4px;
+  padding: 3px; border-radius: 4px;
+  background: rgba(0,0,0,0.75);
+  pointer-events: none;
+  opacity: 0; transition: opacity 100ms ease;
+}
+.mc-preview[data-show="1"] { opacity: 1; }
+.mc-preview canvas { display: block; width: 160px; height: auto; border-radius: 2px; }
+.mc-preview-time { font-size: 12px; line-height: 1; color: var(--mc-fg, #fff); font-variant-numeric: tabular-nums; }
+
 .mc-bar {
   position: relative;
   display: flex;
@@ -295,7 +308,7 @@ var THEME_PROPERTIES = {
   trackHeight: "--mc-track-height",
   font: "--mc-font"
 };
-var CONTROLLER_OPTION_KEYS = ["canvas", "theme", "exportButton", "keyboard", "clickToPlay", "presentButton", "pauseAtStops", "loopButton", "className"];
+var CONTROLLER_OPTION_KEYS = ["canvas", "theme", "exportButton", "keyboard", "clickToPlay", "presentButton", "pauseAtStops", "loopButton", "thumbnails", "className"];
 var Controller = class _Controller {
   movie;
   options;
@@ -341,6 +354,17 @@ var Controller = class _Controller {
   onReady = null;
   /** A rebuild (setVars, resize, rebuild) may have moved the stops: draw their marks again. */
   onRebuilt = null;
+  previewEl = null;
+  previewCanvas = null;
+  previewTimeEl = null;
+  /** Pictures already made, by frame bucket (a frame is a pure function of time; cleared on a rebuild). */
+  previewCache = /* @__PURE__ */ new Map();
+  previewWanted = null;
+  previewRunning = false;
+  previewRetry = null;
+  previewRetries = 0;
+  previewCleanup = null;
+  static PREVIEW_WIDTH_PX = 160;
   presenter = null;
   /** `pixi-effects/present`, loaded as soon as the movie has stops (a press of play must not wait for it). */
   present = null;
@@ -387,6 +411,7 @@ var Controller = class _Controller {
       presentButton: options.presentButton ?? true,
       pauseAtStops: options.pauseAtStops ?? true,
       loopButton: options.loopButton ?? true,
+      thumbnails: options.thumbnails ?? false,
       className: options.className ?? "movie-controller"
     };
     installStyles();
@@ -409,6 +434,7 @@ var Controller = class _Controller {
     this.bindPlayButton();
     if (this.options.clickToPlay) this.bindCanvasClick();
     this.bindScrubbing();
+    if (this.options.thumbnails) this.bindPreview();
     this.bindMuteButton();
     this.bindLoopButton();
     this.bindVolumeSlider();
@@ -588,6 +614,7 @@ var Controller = class _Controller {
     };
     this.onRebuilt = () => {
       this.refreshStops();
+      this.previewCache.clear();
     };
     this.movie.on("ready", this.onReady);
     this.movie.on("rebuilt", this.onRebuilt);
@@ -911,6 +938,104 @@ var Controller = class _Controller {
     };
     window.addEventListener("blur", this.windowBlurHandler);
   }
+  /** The hover preview above the seek bar (`thumbnails: true`). */
+  bindPreview() {
+    const el = document.createElement("div");
+    el.className = "mc-preview";
+    el.setAttribute("aria-hidden", "true");
+    const canvas = document.createElement("canvas");
+    const time = document.createElement("span");
+    time.className = "mc-preview-time";
+    el.append(canvas, time);
+    this.root.appendChild(el);
+    this.previewEl = el;
+    this.previewCanvas = canvas;
+    this.previewTimeEl = time;
+    const hide = () => {
+      this.previewWanted = null;
+      el.removeAttribute("data-show");
+    };
+    const onMove = (e) => {
+      if (this.isScrubbing || this.movie.thumbnailsOff || e.pointerType === "touch") {
+        hide();
+        return;
+      }
+      const rect = this.progressEl.getBoundingClientRect();
+      const inset = _Controller.PROGRESS_INSET_PX;
+      const frame = pxToFrame(e.clientX, { left: rect.left + inset, width: Math.max(0, rect.width - 2 * inset) }, this.movie.totalFrames);
+      const rootRect = this.root.getBoundingClientRect();
+      const half = el.getBoundingClientRect().width / 2 + 2;
+      const x = Math.min(Math.max(e.clientX - rootRect.left, half), Math.max(half, rootRect.width - half));
+      el.style.left = `${rootRect.width > 0 ? x / rootRect.width * 100 : 50}%`;
+      this.previewRetries = 0;
+      time.textContent = formatTime(frame / (this.movie.frameRate || 1));
+      this.previewWanted = frame;
+      void this.runPreview();
+    };
+    this.progressEl.addEventListener("pointermove", onMove);
+    this.progressEl.addEventListener("pointerleave", hide);
+    this.progressEl.addEventListener("pointerdown", hide);
+    this.previewCleanup = () => {
+      this.progressEl.removeEventListener("pointermove", onMove);
+      this.progressEl.removeEventListener("pointerleave", hide);
+      this.progressEl.removeEventListener("pointerdown", hide);
+      if (this.previewRetry) {
+        clearTimeout(this.previewRetry);
+        this.previewRetry = null;
+      }
+      el.remove();
+    };
+  }
+  /** Draws the picture of the wanted frame into the preview; one at a time, and the last wish wins. */
+  async runPreview() {
+    if (this.previewRunning) return;
+    this.previewRunning = true;
+    try {
+      while (this.previewWanted !== null && !this.destroyed) {
+        const wanted = this.previewWanted;
+        const fps = this.movie.frameRate || 30;
+        const step = Math.max(1, Math.round(fps / 10));
+        const key = Math.min(this.movie.totalFrames, Math.round(wanted / step) * step);
+        let pic = this.previewCache.get(key) ?? null;
+        if (!pic) {
+          try {
+            pic = await this.movie.thumbnail(key, { width: _Controller.PREVIEW_WIDTH_PX });
+          } catch {
+            this.previewWanted = null;
+            this.previewEl?.removeAttribute("data-show");
+            break;
+          }
+          if (pic) {
+            if (this.previewCache.size >= 120) this.previewCache.delete(this.previewCache.keys().next().value);
+            this.previewCache.set(key, pic);
+          }
+        }
+        if (this.previewWanted === null || this.destroyed) break;
+        if (pic) {
+          const c = this.previewCanvas;
+          if (c.width !== pic.width || c.height !== pic.height) {
+            c.width = pic.width;
+            c.height = pic.height;
+          }
+          c.getContext("2d").drawImage(pic, 0, 0);
+          this.previewEl.setAttribute("data-show", "1");
+          if (this.previewWanted === wanted) this.previewWanted = null;
+        } else if (this.previewWanted !== wanted) {
+        } else if (!this.movie.thumbnailsOff && this.previewRetries++ < 10) {
+          this.previewRetry = setTimeout(() => {
+            this.previewRetry = null;
+            void this.runPreview();
+          }, 120);
+          break;
+        } else {
+          this.previewWanted = null;
+          this.previewEl?.removeAttribute("data-show");
+        }
+      }
+    } finally {
+      this.previewRunning = false;
+    }
+  }
   seekFromPointer(clientX) {
     const rect = this.progressEl.getBoundingClientRect();
     const inset = _Controller.PROGRESS_INSET_PX;
@@ -1187,6 +1312,10 @@ var Controller = class _Controller {
     if (this.destroyed) return;
     this.destroyed = true;
     this.stopPresenting();
+    if (this.previewCleanup) {
+      this.previewCleanup();
+      this.previewCleanup = null;
+    }
     if (this.onReady) {
       this.movie.off("ready", this.onReady);
       this.onReady = null;