pixi-effects 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.42.0
+
+Interaction on top of `pick`: hover, dragging, a hit that looks at the picture, and a fix for a false warning that every rebuilt page with a `three` layer showed since 0.40.0. Nothing breaks.
+
+- **Fixed (found by an AI trial of the interactive features): a rebuilt `three` layer said the browser had taken its WebGL context.** `setVars`, `resize` and `rebuild` destroy the old layers; a three layer lets its context go with `forceContextLoss()`, and the loss event that follows was reported by the "the browser took this layer's WebGL context away" warning added in 0.40.0, though it was the layer's own doing. A page whose three layer changed a variable on a click showed a false warning. The layer now knows it is closing (`tests/three/budget.test.ts`; `tests/films/three-budget` rebuilds in Chrome and fails without the fix).
+- **New: `movie.hover({ onEnter, onLeave })`.** Which layer the pointer is over (in a `three` layer, which object), as callbacks on top of `pick`: `onEnter(hit)` when the layer under the pointer changes to another, `onLeave(hit)` for the one it left (also when the pointer leaves the picture or the returned stop function is called). While the pointer rests inside it is asked again on every frame, so a picture that moves under a still pointer is followed (a runner leaves the pointer with no pointer event in between: tested in real Chrome). `{ only, ignore }`, `cursor: true` (or a CSS cursor). A page-side tool: an exported video has no pointer.
+- **New: `pick` looks at the picture (`{ alpha }`), and an object of a `three` layer can be dragged (`hit.three.grab`, `movie.redraw()`).** `movie.pick(x, y, { alpha: 0.1 })` leaves out a pixel of an image, a video or a `canvas` layer whose alpha is at or below it (a transparent corner of a logo, the clear part of a drawn circle); off by default, nothing is read without it; shapes are hit by their outline, text and `shader` layers by their box (a shader's WebGL picture cannot be read back safely); a picture that cannot be read (another origin) stays a hit with one warning. `hit.three.grab('screen' | 'floor' | 'wall' | [nx, ny, nz])` fixes a plane through the point taken and `grab.move(x, y)` returns where the pointer's ray meets it and the `delta` from the point taken (null where it never does): the object follows the pointer exactly (checked in real Chrome on a wall and on a floor seen in perspective). `movie.redraw()` draws the paused frame again, quietly, for a layer that reads the page's own state. `pick`'s `only` / `ignore` take a group's name for everything in it (a card and its label: `only: ['card']`), as well as layer names and paths.
+- **Recipes and docs, from three fresh-AI trials of `pick`, `hover` and dragging** (a fox that stops when clicked, a card dragged onto a zone that lights, a logo clicked by its picture and a cube dragged along a floor; each page checked in a real browser): the recipes `pick-click`, `drag-drop` (a flat layer, a zone that lights by a variable alpha, the grab and grabbing cursors, `touch-action: none`) and `drag-3d` (with a floor variant) are complete pages whose code is tested (`tests/films/drag-recipe`, `drag3d`, `interact`, `pick`); SKILL.md says how to test an interactive page with pointer events (`check` does not click); the `vars` doc says a rebuild runs a three layer's `setup` again, so a 3D drag keeps the object's place in the page and calls `redraw()`.
+
 ## 0.41.0
 
 `movie.pick` (what is under a point of the canvas) and a better fit of the light falloff in a `three` layer. Nothing breaks.

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.41.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.42.0`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
 
 **[Gallery →](https://yjmtmtk.github.io/pixi-effects/examples/gallery/)** · 43 pieces written as plain data by AI models · **[For AI →](https://yjmtmtk.github.io/pixi-effects/for-ai.html)** · what an AI reads and runs · **[Playground →](https://yjmtmtk.github.io/pixi-effects/examples/playground.html)** in the browser.
 
@@ -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.41.0/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.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.41.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.42.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.
 >
@@ -78,7 +78,7 @@ Add two more entries to the importmap above: three.js itself, and the `pixi-effe
     "...":                     "(everything from the importmap above)",
     "three":                   "https://esm.sh/three@0.178.0",
     "three/addons/":           "https://cdn.jsdelivr.net/npm/three@0.178.0/examples/jsm/",
-    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.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.41.0/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/Controller.js",
-      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.41.0/dist/present.js"
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.42.0/dist/present.js"
     }
   }
   </script>

package/dist/Controller.d.cts

@@ -1,4 +1,4 @@
-import { M as Movie } from './Movie-DWtxRiJ2.cjs';
+import { M as Movie } from './Movie-BHGhg-fJ.cjs';
 import 'pixi.js';
 import './soundEntry-DT13DNt8.cjs';
 import './types-DIh93lFb.cjs';

package/dist/Controller.d.ts

@@ -1,4 +1,4 @@
-import { M as Movie } from './Movie-CwqRLOzE.js';
+import { M as Movie } from './Movie-CBVFZ1kg.js';
 import 'pixi.js';
 import './soundEntry-DT13DNt8.js';
 import './types-DIh93lFb.js';

package/dist/{Movie-DWtxRiJ2.d.cts → Movie-BHGhg-fJ.d.cts}

@@ -259,15 +259,45 @@ interface PickHit {
         point: [number, number, number];
         distance: number;
         object3d?: unknown;
+        /**
+         * Drag what the ray met: `grab(plane)` fixes a plane through the hit point (`'screen'` facing the camera, the default; `'floor'`; `'wall'`; or a normal `[x, y, z]`), and `move(x, y)` takes the pointer
+         * in canvas pixels and gives where its ray meets that plane (`point`) and how far that is from the hit point (`delta`): move the object by it. null where the ray never meets the plane.
+         */
+        grab?: (plane?: 'screen' | 'floor' | 'wall' | [number, number, number]) => {
+            move: (x: number, y: number) => {
+                point: [number, number, number];
+                delta: [number, number, number];
+            } | null;
+        };
     };
 }
 interface PickOptions {
-    /** Only these layers can be hit (by `name` or by `path`). */
+    /**
+     * Look at the picture, not the box: a pixel of an image, a video or a `canvas` layer whose alpha is at or below this (0..1; `0.1` leaves out what is nearly clear) is not a hit.
+     * Off by default (the box is the picture, and nothing is read). Shapes are always hit by their outline, text and `shader` layers by their box; a picture that cannot be read (from another origin) stays a hit.
+     */
+    alpha?: number;
+    /** Only these layers can be hit (by `name` or by `path`; a group's name stands for everything in it). */
     only?: string[];
-    /** These layers cannot be hit (by `name` or by `path`). */
+    /** These layers cannot be hit (by `name` or by `path`; a group's name stands for everything in it). */
     ignore?: string[];
 }
 
+/**
+ * `movie.hover({ onEnter, onLeave })`: which layer (or which object of a three layer) the pointer is over, as two callbacks. It is a page-side tool on top of `movie.pick`: it listens to the
+ * canvas, asks `pick` where the pointer is, and calls `onEnter(hit)` when the layer under it changes to another and `onLeave(hit)` for the one it left. While the pointer rests inside the
+ * picture it asks again on every frame, so a layer that runs away from a still pointer is left. Nothing here is part of the video: an exported file has no pointer.
+ */
+
+interface HoverOptions extends PickOptions {
+    /** The layer (or, in a `three` layer, the object) the pointer has just come onto. */
+    onEnter?: (hit: PickHit) => void;
+    /** The one it has just left (also when the pointer leaves the picture, or `stop()` is called). */
+    onLeave?: (hit: PickHit) => void;
+    /** A CSS cursor to show while something is hovered (`true` is `'pointer'`); it goes back when nothing is. */
+    cursor?: string | boolean;
+}
+
 /** One layer (or a run of similar layers) on the timeline. Times are in seconds, absolute (from the start of the movie). */
 interface TimelineRow {
     /** `parent/child` for a layer inside a composition. */
@@ -645,6 +675,11 @@ declare class Movie {
     private _runRebuild;
     private _doRebuild;
     gotoFrame(frame: number, force?: boolean): Promise<void>;
+    /**
+     * Draw the frame on screen again, quietly (no `seeking` / `seeked`). For a paused movie when something outside it that a layer reads has changed: a `three` layer whose `update` reads the page's own
+     * state (a dragged object's place) shows it after `await movie.redraw()`. A playing movie needs no call: the next frame draws it.
+     */
+    redraw(): Promise<void>;
     /** Run `fn` with `seeking` / `seeked` silenced: the movie is moving its own playhead, not answering a seek. */
     private _quietly;
     private _emitError;
@@ -719,6 +754,12 @@ declare class Movie {
     pick(x: number, y: number, opts?: PickOptions): PickHit | null;
     /** Every layer under the canvas point, the one on top first (see `pick`). */
     pickAll(x: number, y: number, opts?: PickOptions): PickHit[];
+    /**
+     * Which layer the pointer is over, as callbacks: `onEnter(hit)` when the layer (or, in a `three` layer, the object) under the pointer changes to another, `onLeave(hit)` for the one it
+     * left (also when the pointer leaves the picture). While the pointer rests inside, it is asked again on every frame, so a picture that moves under a still pointer is followed.
+     * `{ only, ignore }` as for `pick`; `cursor: true` (or a CSS cursor) shows it while something is hovered. Returns the function that stops it. A page-side tool: an exported video has no pointer.
+     */
+    hover(opts?: HoverOptions): () => void;
     /** A pointer event's place in canvas pixels (the canvas may be shown larger or smaller than its own size): `movie.pick(...movie.canvasPoint(event))`. */
     canvasPoint(event: {
         clientX: number;
@@ -814,4 +855,4 @@ declare class Movie {
     destroy(): Promise<void>;
 }
 
-export { type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type PickHit as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type PickOptions as l, type ProgressEvent as m, type RebuildReason as n, type RebuildReport as o, type RenderOptions as p, type ReviewOptions as q, type ReviewReport as r, type TimelineData as s, type TimelineHtmlOptions as t, type TimelineRow as u, type TimelineSvgOptions as v, type TimelineTransition as w, dismissLoader as x, failLoader as y, resolveLoader as z };
+export { type ContactSheetOptions as C, type FontReport as F, type HoverOptions as H, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type PickHit as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type PickOptions as l, type ProgressEvent as m, type RebuildReason as n, type RebuildReport as o, type RenderOptions as p, type ReviewOptions as q, type ReviewReport as r, type TimelineData as s, type TimelineHtmlOptions as t, type TimelineRow as u, type TimelineSvgOptions as v, type TimelineTransition as w, dismissLoader as x, failLoader as y, resolveLoader as z };

package/dist/{Movie-CwqRLOzE.d.ts → Movie-CBVFZ1kg.d.ts}

@@ -259,15 +259,45 @@ interface PickHit {
         point: [number, number, number];
         distance: number;
         object3d?: unknown;
+        /**
+         * Drag what the ray met: `grab(plane)` fixes a plane through the hit point (`'screen'` facing the camera, the default; `'floor'`; `'wall'`; or a normal `[x, y, z]`), and `move(x, y)` takes the pointer
+         * in canvas pixels and gives where its ray meets that plane (`point`) and how far that is from the hit point (`delta`): move the object by it. null where the ray never meets the plane.
+         */
+        grab?: (plane?: 'screen' | 'floor' | 'wall' | [number, number, number]) => {
+            move: (x: number, y: number) => {
+                point: [number, number, number];
+                delta: [number, number, number];
+            } | null;
+        };
     };
 }
 interface PickOptions {
-    /** Only these layers can be hit (by `name` or by `path`). */
+    /**
+     * Look at the picture, not the box: a pixel of an image, a video or a `canvas` layer whose alpha is at or below this (0..1; `0.1` leaves out what is nearly clear) is not a hit.
+     * Off by default (the box is the picture, and nothing is read). Shapes are always hit by their outline, text and `shader` layers by their box; a picture that cannot be read (from another origin) stays a hit.
+     */
+    alpha?: number;
+    /** Only these layers can be hit (by `name` or by `path`; a group's name stands for everything in it). */
     only?: string[];
-    /** These layers cannot be hit (by `name` or by `path`). */
+    /** These layers cannot be hit (by `name` or by `path`; a group's name stands for everything in it). */
     ignore?: string[];
 }
 
+/**
+ * `movie.hover({ onEnter, onLeave })`: which layer (or which object of a three layer) the pointer is over, as two callbacks. It is a page-side tool on top of `movie.pick`: it listens to the
+ * canvas, asks `pick` where the pointer is, and calls `onEnter(hit)` when the layer under it changes to another and `onLeave(hit)` for the one it left. While the pointer rests inside the
+ * picture it asks again on every frame, so a layer that runs away from a still pointer is left. Nothing here is part of the video: an exported file has no pointer.
+ */
+
+interface HoverOptions extends PickOptions {
+    /** The layer (or, in a `three` layer, the object) the pointer has just come onto. */
+    onEnter?: (hit: PickHit) => void;
+    /** The one it has just left (also when the pointer leaves the picture, or `stop()` is called). */
+    onLeave?: (hit: PickHit) => void;
+    /** A CSS cursor to show while something is hovered (`true` is `'pointer'`); it goes back when nothing is. */
+    cursor?: string | boolean;
+}
+
 /** One layer (or a run of similar layers) on the timeline. Times are in seconds, absolute (from the start of the movie). */
 interface TimelineRow {
     /** `parent/child` for a layer inside a composition. */
@@ -645,6 +675,11 @@ declare class Movie {
     private _runRebuild;
     private _doRebuild;
     gotoFrame(frame: number, force?: boolean): Promise<void>;
+    /**
+     * Draw the frame on screen again, quietly (no `seeking` / `seeked`). For a paused movie when something outside it that a layer reads has changed: a `three` layer whose `update` reads the page's own
+     * state (a dragged object's place) shows it after `await movie.redraw()`. A playing movie needs no call: the next frame draws it.
+     */
+    redraw(): Promise<void>;
     /** Run `fn` with `seeking` / `seeked` silenced: the movie is moving its own playhead, not answering a seek. */
     private _quietly;
     private _emitError;
@@ -719,6 +754,12 @@ declare class Movie {
     pick(x: number, y: number, opts?: PickOptions): PickHit | null;
     /** Every layer under the canvas point, the one on top first (see `pick`). */
     pickAll(x: number, y: number, opts?: PickOptions): PickHit[];
+    /**
+     * Which layer the pointer is over, as callbacks: `onEnter(hit)` when the layer (or, in a `three` layer, the object) under the pointer changes to another, `onLeave(hit)` for the one it
+     * left (also when the pointer leaves the picture). While the pointer rests inside, it is asked again on every frame, so a picture that moves under a still pointer is followed.
+     * `{ only, ignore }` as for `pick`; `cursor: true` (or a CSS cursor) shows it while something is hovered. Returns the function that stops it. A page-side tool: an exported video has no pointer.
+     */
+    hover(opts?: HoverOptions): () => void;
     /** A pointer event's place in canvas pixels (the canvas may be shown larger or smaller than its own size): `movie.pick(...movie.canvasPoint(event))`. */
     canvasPoint(event: {
         clientX: number;
@@ -814,4 +855,4 @@ declare class Movie {
     destroy(): Promise<void>;
 }
 
-export { type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type PickHit as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type PickOptions as l, type ProgressEvent as m, type RebuildReason as n, type RebuildReport as o, type RenderOptions as p, type ReviewOptions as q, type ReviewReport as r, type TimelineData as s, type TimelineHtmlOptions as t, type TimelineRow as u, type TimelineSvgOptions as v, type TimelineTransition as w, dismissLoader as x, failLoader as y, resolveLoader as z };
+export { type ContactSheetOptions as C, type FontReport as F, type HoverOptions as H, type InspectOptions as I, type LayerInfo as L, Movie as M, type OnionSkinOptions as O, type PickHit as P, type RebuildOptions as R, type SnapshotOptions as S, type ThumbnailOptions as T, type VolumeEvent as V, type MotionBlurSpec as a, type FrameEvent as b, type InspectReport as c, type IssueGroup as d, type LoadProgressState as e, type LoadStage as f, type LoaderOption as g, type LoopEvent as h, type MotionBlurOptions as i, type MovieErrorEvent as j, type MovieOptions as k, type PickOptions as l, type ProgressEvent as m, type RebuildReason as n, type RebuildReport as o, type RenderOptions as p, type ReviewOptions as q, type ReviewReport as r, type TimelineData as s, type TimelineHtmlOptions as t, type TimelineRow as u, type TimelineSvgOptions as v, type TimelineTransition as w, dismissLoader as x, failLoader as y, resolveLoader as z };

package/dist/{chunk-Y2N6U3X5.js → chunk-NFJKBWYO.js}

@@ -1730,6 +1730,23 @@ function inspectScene(root, frame, time, canvas, opts = {}) {
 }
 
 // src/core/pick.ts
+var scratch;
+var saidBlind = /* @__PURE__ */ new Set();
+var readResourceAlpha = (resource, x, y) => {
+  try {
+    if (scratch === void 0) {
+      const c = document.createElement("canvas");
+      c.width = c.height = 1;
+      scratch = c.getContext("2d", { willReadFrequently: true });
+    }
+    if (!scratch) return null;
+    scratch.clearRect(0, 0, 1, 1);
+    scratch.drawImage(resource, x, y, 1, 1, 0, 0, 1, 1);
+    return scratch.getImageData(0, 0, 1, 1).data[3] / 255;
+  } catch {
+    return null;
+  }
+};
 function pointInQuad(q, x, y) {
   let pos = 0, neg = 0;
   for (let i = 0; i < 4; i++) {
@@ -1754,11 +1771,14 @@ var above = (a, b) => {
   }
   return b.length - a.length;
 };
-function pickScene(root, x, y, opts = {}) {
+function pickScene(root, x, y, opts = {}, deps = {}) {
+  if (opts.alpha !== void 0 && !(opts.alpha >= 0 && opts.alpha <= 1)) throw new Error(`pixi-effects: pick: alpha must be a number from 0 to 1 (a pixel at or below it is not a hit), got ${opts.alpha}`);
+  const readAlpha = deps.readAlpha ?? readResourceAlpha;
   const found = [];
+  const names = (list, name, path) => list.some((e) => e === path || name !== void 0 && e === name || path.startsWith(e + "/") || path.split("/").slice(0, -1).includes(e));
   const wanted = (name, path) => {
-    if (opts.ignore && (opts.ignore.includes(path) || name !== void 0 && opts.ignore.includes(name))) return false;
-    if (opts.only && !(opts.only.includes(path) || name !== void 0 && opts.only.includes(name))) return false;
+    if (opts.ignore && names(opts.ignore, name, path)) return false;
+    if (opts.only && !names(opts.only, name, path)) return false;
     return true;
   };
   const inside = (b, p) => p.x >= b.x && p.x <= b.x + b.width && p.y >= b.y && p.y <= b.y + b.height;
@@ -1788,8 +1808,34 @@ function pickScene(root, x, y, opts = {}) {
         const lb = d.getLocalBounds();
         if (inside(lb, local)) {
           const three = typeof seq.pickAt === "function" ? seq.pickAt((local.x - lb.x) / lb.width, (local.y - lb.y) / lb.height) : void 0;
-          if (three) hit = { name, path, type: seq.spec.type, kind: "three", point, three };
-          else if (three === void 0 && (typeof d.containsPoint !== "function" || d.containsPoint(local))) hit = { name, path, type: seq.spec.type, kind: "flat", point, local: { x: local.x - lb.x, y: local.y - lb.y } };
+          if (three) {
+            const planeOf = seq.dragPlane;
+            if (planeOf) {
+              three.grab = (plane = "screen") => {
+                const along = planeOf.call(seq, three.point, plane);
+                return { move: (cx, cy) => {
+                  const lp = d.toLocal({ x: cx, y: cy });
+                  const b = d.getLocalBounds();
+                  return along((lp.x - b.x) / b.width, (lp.y - b.y) / b.height);
+                } };
+              };
+            }
+            hit = { name, path, type: seq.spec.type, kind: "three", point, three };
+          } else if (three === void 0 && (typeof d.containsPoint !== "function" || d.containsPoint(local))) {
+            let opaque = true;
+            const tex = opts.alpha !== void 0 && seq.spec.type !== "shader" ? d.texture : void 0;
+            if (tex?.source?.resource) {
+              const res = tex.source.resolution ?? 1;
+              const a = readAlpha(tex.source.resource, (tex.frame.x + (local.x - lb.x) / lb.width * tex.frame.width) * res, (tex.frame.y + (local.y - lb.y) / lb.height * tex.frame.height) * res);
+              if (a === null) {
+                if (!saidBlind.has(path)) {
+                  saidBlind.add(path);
+                  console.warn(`pixi-effects: pick: the picture of layer "${path}" cannot be read for { alpha } (a picture from another origin: load it with crossorigin="anonymous" or from the same site), so the box counts as the picture`);
+                }
+              } else opaque = a > opts.alpha;
+            }
+            if (opaque) hit = { name, path, type: seq.spec.type, kind: "flat", point, local: { x: local.x - lb.x, y: local.y - lb.y } };
+          }
         }
       }
       if (!hit) return;
@@ -1803,6 +1849,82 @@ function pickScene(root, x, y, opts = {}) {
   return found.sort((a, b) => above(a.order, b.order)).map((f) => f.hit);
 }
 
+// src/core/hover.ts
+var keyOf = (h) => h ? `${h.path}${h.three ? `#${h.three.object}` : ""}` : null;
+function startHover(host, opts = {}) {
+  const { canvas } = host;
+  const request = host.requestFrame ?? ((fn) => requestAnimationFrame(fn));
+  const cancel = host.cancelFrame ?? ((id) => cancelAnimationFrame(id));
+  const cursor = opts.cursor === true ? "pointer" : opts.cursor || "";
+  const pickOpts = {};
+  if (opts.only) pickOpts.only = opts.only;
+  if (opts.ignore) pickOpts.ignore = opts.ignore;
+  let current = null;
+  let last = null;
+  let loop = null;
+  let said = false;
+  const call = (fn, hit) => {
+    if (!fn) return;
+    try {
+      fn(hit);
+    } catch (err) {
+      if (!said) {
+        said = true;
+        console.warn("pixi-effects: movie.hover: a handler threw (said once) \u2014", err);
+      }
+    }
+  };
+  const setCursor = (on) => {
+    if (cursor) canvas.style.cursor = on ? cursor : "";
+  };
+  const evaluate = () => {
+    if (!last) return;
+    const [x, y] = host.point(last);
+    const hit = host.pick(x, y, pickOpts);
+    if (keyOf(hit) === keyOf(current)) {
+      current = hit ?? current;
+      return;
+    }
+    const was = current;
+    current = hit;
+    if (was) call(opts.onLeave, was);
+    if (hit) call(opts.onEnter, hit);
+    setCursor(!!hit);
+  };
+  const tick = () => {
+    loop = null;
+    if (last) {
+      evaluate();
+      loop = request(tick);
+    }
+  };
+  const onMove = (event) => {
+    last = event;
+    evaluate();
+    if (loop === null) loop = request(tick);
+  };
+  const onLeave = () => {
+    last = null;
+    if (loop !== null) {
+      cancel(loop);
+      loop = null;
+    }
+    const was = current;
+    current = null;
+    if (was) call(opts.onLeave, was);
+    setCursor(false);
+  };
+  canvas.addEventListener("pointermove", onMove);
+  canvas.addEventListener("pointerdown", onMove);
+  canvas.addEventListener("pointerleave", onLeave);
+  return () => {
+    canvas.removeEventListener("pointermove", onMove);
+    canvas.removeEventListener("pointerdown", onMove);
+    canvas.removeEventListener("pointerleave", onLeave);
+    onLeave();
+  };
+}
+
 // src/core/timelineChart.ts
 var GROUP_MIN = 4;
 var MAX_KEYS = 200;
@@ -2857,6 +2979,14 @@ var Movie = class {
     await this._goto(frame);
     this.emit("seeked", { frame: this.currentFrame, totalFrames: this.totalFrames });
   }
+  /**
+   * Draw the frame on screen again, quietly (no `seeking` / `seeked`). For a paused movie when something outside it that a layer reads has changed: a `three` layer whose `update` reads the page's own
+   * state (a dragged object's place) shows it after `await movie.redraw()`. A playing movie needs no call: the next frame draws it.
+   */
+  async redraw() {
+    this._requireReady("redraw");
+    await this._quietly(() => this.gotoFrame(this.currentFrame, true));
+  }
   /** Run `fn` with `seeking` / `seeked` silenced: the movie is moving its own playhead, not answering a seek. */
   async _quietly(fn) {
     this._quiet++;
@@ -3070,11 +3200,23 @@ var Movie = class {
   }
   /** Every layer under the canvas point, the one on top first (see `pick`). */
   pickAll(x, y, opts = {}) {
-    warnUnknownOptions("movie.pick()", opts, ["only", "ignore"]);
+    warnUnknownOptions("movie.pick()", opts, ["only", "ignore", "alpha"]);
     this._requireReady("pick");
     if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error(`pixi-effects: movie.pick(x, y) needs two numbers (canvas pixels), got ${x}, ${y}. For a pointer event: movie.pick(...movie.canvasPoint(event))`);
     return pickScene(this._rootSequence, x, y, opts);
   }
+  /**
+   * Which layer the pointer is over, as callbacks: `onEnter(hit)` when the layer (or, in a `three` layer, the object) under the pointer changes to another, `onLeave(hit)` for the one it
+   * left (also when the pointer leaves the picture). While the pointer rests inside, it is asked again on every frame, so a picture that moves under a still pointer is followed.
+   * `{ only, ignore }` as for `pick`; `cursor: true` (or a CSS cursor) shows it while something is hovered. Returns the function that stops it. A page-side tool: an exported video has no pointer.
+   */
+  hover(opts = {}) {
+    warnUnknownOptions("movie.hover()", opts, ["onEnter", "onLeave", "cursor", "only", "ignore"]);
+    this._requireReady("hover");
+    const canvas = this.app?.canvas;
+    if (!canvas) throw new Error("pixi-effects: movie.hover needs the movie's canvas");
+    return startHover({ canvas, pick: (x, y, o) => this.pick(x, y, o), point: (e) => this.canvasPoint(e) }, opts);
+  }
   /** A pointer event's place in canvas pixels (the canvas may be shown larger or smaller than its own size): `movie.pick(...movie.canvasPoint(event))`. */
   canvasPoint(event) {
     this._requireReady("canvasPoint");
@@ -4582,5 +4724,5 @@ function withFade(spec, opts) {
 }
 
 export { Movie, animateText, audioEnvelope, bpmEnvelope, cameraPath, computeEnvelope, dismissLoader, failLoader, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, musicEvents, orbit, parseEase2 as parseEase, particles, react, resolveLoader, samplePath, splitText, stagger, wiggle, withFade };
-//# sourceMappingURL=chunk-Y2N6U3X5.js.map
-//# sourceMappingURL=chunk-Y2N6U3X5.js.map
+//# sourceMappingURL=chunk-NFJKBWYO.js.map
+//# sourceMappingURL=chunk-NFJKBWYO.js.map