pixi-effects 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.35.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.35.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.35.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.35.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.35.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.35.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.35.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.35.0/dist/present.js"
     }
   }
   </script>

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;