pixi-effects 0.50.1 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.51.0
+
+Nothing breaks: a 2D layer can stay next to an object of a scene.
+
+- **`follow: 'planets/Mars'`: a label next to an object, every frame.** Any 2D layer (text, shape, image, composition, null) is carried to where an object of a `scene3d`, `three` or `scene2d` layer is on screen (a name its setup returned in `objects`, or a node's label / `name`), or another layer's anchor point (`follow: 'title'`, a path through nested compositions, or a unique name found anywhere); its own `x` / `y` become an offset from there. It is placed after every layer is set for the frame (the scene layers' `update(t)` and `followCamera`), so it sits where the object is drawn in playback, a seek and an export, and it is hidden while the object is behind the camera or the followed layer is not on screen. An unknown layer or object is warned with the names there are (did you mean); a `threeD` follower, a target inside a `threeD` card and an offset larger than the composition are said in a sentence. In a trial (2026-11-14) both agents that labelled orbiting planets wrote the camera projection by hand and copied the camera's ease. Film `follow`.
+- **`movie.project(target)`** → `{ x, y } | null`: the same point for your own code, in canvas pixels (the space `movie.pick` takes).
+- **`check --do "click planets/Mars"`** clicks an object of a scene by name, where `movie.project` says it is (it knew only layer names).
+- **`release:check` runs the files that failed in the full run once more, alone** (not when more than 8 failed): three full runs in a row had each timed out a different real-browser test under the load of the run itself; it names the files it ran again.
+
 ## 0.50.1
 
 Fixes from a trial of 8 fresh agents (Sonnet, Opus) making videos with `scene2d` / `scene3d` on 0.50.0; nothing breaks.

package/README.md

@@ -1,6 +1,6 @@
 # pixi-effects
 
-> **Status**: experimental — current release `0.50.1`. The API may still change between minor versions; see the [CHANGELOG](./CHANGELOG.md) for what each release changed.
+> **Status**: experimental — current release `0.51.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.
 
@@ -52,8 +52,8 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
   "imports": {
     "pixi.js":                 "https://esm.sh/pixi.js@8.23.0?bundle-deps",
     "mediabunny":              "https://esm.sh/mediabunny",
-    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/index.js",
-    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/Controller.js"
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/Controller.js"
   }
 }
 </script>
@@ -66,7 +66,7 @@ Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML
 
 The `mediabunny` line is needed only to export (the download button, `movie.render()`) or for a `video` layer; a page that only plays can leave it out and never fetches it (or call `useMediabunny(url)` instead, see [the API](docs/api.md#where-the-encoder-comes-from-usemediabunnysource)).
 
-Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.50.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.51.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.
 
 > **A 3D scene?** Add three more entries (`pixi-effects/3d`, `@pixi/3d`, `@pixi/3d/extras`) — see [Adding a 3D scene](#adding-a-3d-scene-optional) below. **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
 >
@@ -81,7 +81,7 @@ Add three entries to the importmap above (PixiJS 3D needs `pixi.js` 8.23.0 or la
 {
   "imports": {
     "...":                     "(everything from the importmap above)",
-    "pixi-effects/3d":         "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/3d.js",
+    "pixi-effects/3d":         "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/3d.js",
     "@pixi/3d":                "https://cdn.jsdelivr.net/npm/@pixi/3d@0.1.0/dist/pixijs-3d.min.mjs",
     "@pixi/3d/extras":         "https://cdn.jsdelivr.net/npm/@pixi/3d@0.1.0/dist/pixijs-3d-extras.min.mjs"
   }
@@ -125,7 +125,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.50.1/dist/three.js"
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/three.js"
   }
 }
 </script>

package/ai/chat-template.html

@@ -65,10 +65,10 @@
     "imports": {
       "pixi.js":                 "https://cdn.jsdelivr.net/npm/pixi.js@8.23.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.50.1/dist/index.js",
-      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/Controller.js",
-      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/present.js",
-      "pixi-effects/3d":         "https://cdn.jsdelivr.net/npm/pixi-effects@0.50.1/dist/3d.js",
+      "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/index.js",
+      "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/Controller.js",
+      "pixi-effects/present":  "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/present.js",
+      "pixi-effects/3d":         "https://cdn.jsdelivr.net/npm/pixi-effects@0.51.0/dist/3d.js",
       "@pixi/3d":                "https://cdn.jsdelivr.net/npm/@pixi/3d@0.1.0/dist/pixijs-3d.min.mjs",
       "@pixi/3d/extras":         "https://cdn.jsdelivr.net/npm/@pixi/3d@0.1.0/dist/pixijs-3d-extras.min.mjs"
     }

package/ai/tools/check.mjs

@@ -19,7 +19,7 @@
  *          --pick X,Y (with --at, repeatable: what is under that canvas point at each moment, the top layer first, and the object a three layer met: `movie.pick`) ·
 
  *          --do "click Lime; hover 640,360; drag card > 770,240; wait 1; key Space" (real mouse and key events on the page, one step after the other, after everything else: what was under the pointer, which
- *          variables changed, whether the page warned, one picture per step in steps/; a point is x,y in canvas pixels or a layer name (the middle of its box); repeatable) ·
+ *          variables changed, whether the page warned, one picture per step in steps/; a point is x,y in canvas pixels, a layer name (the middle of its box) or layer/object, an object of a scene3d, three or scene2d layer (where movie.project says it is); repeatable) ·
  *          --onion A:B (one picture of the movement between A and B seconds, frames overlaid: onion.png) ·
  *          --seam (a movie made to loop: the last frame to the first is compared with the steps between ordinary neighbouring frames; a jump is a problem) ·
  *          --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 ·
@@ -104,7 +104,7 @@ const CRITICAL_TYPES = new Set(['Script', 'Document', 'Stylesheet', 'Other', und
 const DO_VERBS = ['click', 'hover', 'drag', 'wait', 'key'];
 const pointOf = (text) => { const m = text.trim().match(/^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/); return m ? { x: Number(m[1]), y: Number(m[2]) } : { name: text.trim() }; };
 /**
- * `--do` steps: "click 640,360; hover Lime; drag card > 770,240; wait 0.5; key Space" (`;` or a new line between steps). A point is `x,y` in canvas pixels or a layer name; the points of a
+ * `--do` steps: "click 640,360; hover Lime; drag card > 770,240; wait 0.5; key Space" (`;` or a new line between steps). A point is `x,y` in canvas pixels, a layer name or `layer/object` (an object of a scene layer); the points of a
  * drag are separated by `>` or by spaces (a name with spaces needs `>`). Returns [{ verb, points?, seconds?, key? }].
  */
 export function parseDo(text) {
@@ -867,8 +867,14 @@ export async function runSteps(cdp, steps, outDir, size, consoleLines, seenLogs)
         const points = [];
         for (const pt of step.points) {
           if (pt.name === undefined) { points.push({ ...pt }); continue; }
-          const box = await cdp.eval(`(async () => { const r = (await movie.inspect(movie.currentFrame)).layers.find(l => l.name === ${JSON.stringify(pt.name)} || l.path === ${JSON.stringify(pt.name)}); return r && r.bounds ? { x: r.bounds.x + r.bounds.width / 2, y: r.bounds.y + r.bounds.height / 2 } : null; })()`);
-          if (!box) throw new Error(`no layer named "${pt.name}" at this moment (it may not be alive yet: put a wait before, or give x,y)`);
+          let box = await cdp.eval(`(async () => { const r = (await movie.inspect(movie.currentFrame)).layers.find(l => l.name === ${JSON.stringify(pt.name)} || l.path === ${JSON.stringify(pt.name)}); return r && r.bounds ? { x: r.bounds.x + r.bounds.width / 2, y: r.bounds.y + r.bounds.height / 2 } : null; })()`);
+          if (!box) {
+            // not a layer: an object of a scene ("world/mover"), where movie.project says it is
+            const p = await cdp.eval(`(() => { try { const p = movie.project(${JSON.stringify(pt.name)}); return p ? { x: p.x, y: p.y } : { hidden: true }; } catch (e) { return { error: String(e && e.message || e).replace(/^pixi-effects: /, '') }; } })()`);
+            if (p && Number.isFinite(p.x)) box = p;
+            else if (p?.hidden) throw new Error(`"${pt.name}" is not on screen at this moment (behind the camera, or its layer is not alive: put a wait before, or give x,y)`);
+            else throw new Error(pt.name.includes('/') && p?.error ? p.error : `no layer named "${pt.name}" at this moment (it may not be alive yet: put a wait before, or give x,y)`);
+          }
           points.push({ x: Math.round(box.x), y: Math.round(box.y), name: pt.name });
         }
         res.label = `${step.verb} ${points.map(pt => pt.name ? `${pt.name} (${pt.x}, ${pt.y})` : `${pt.x},${pt.y}`).join(' > ')}`;

package/dist/3d.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkNXMNBFHM_cjs = require('./chunk-NXMNBFHM.cjs');
+var chunk6KVW442J_cjs = require('./chunk-6KVW442J.cjs');
 require('./chunk-VQXZ2NOI.cjs');
-var chunkGXGIISFS_cjs = require('./chunk-GXGIISFS.cjs');
-var chunk3FCDRLW3_cjs = require('./chunk-3FCDRLW3.cjs');
+var chunkHMI6W5V3_cjs = require('./chunk-HMI6W5V3.cjs');
+var chunkPBGZ47ZS_cjs = require('./chunk-PBGZ47ZS.cjs');
 var chunkDOLTCXCL_cjs = require('./chunk-DOLTCXCL.cjs');
 var _3d = require('@pixi/3d');
 var pixi_js = require('pixi.js');
@@ -248,7 +248,7 @@ async function layerTexture(ctx, name, options = {}) {
 var OWN_KEYS = ["width", "height", "view", "resolution", "setup", "update", "dispose", "followCamera", "followLights", "followFog", "reuse"];
 var THREE_ONLY = ["renderer", "shareGpu", "antialias"];
 var LAYER_OWNED = ["width", "height", "autoResize"];
-var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
+var Scene3DSequence = class extends chunk6KVW442J_cjs.Sequence {
   _view = null;
   _ctx = null;
   _objects = {};
@@ -273,7 +273,7 @@ var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
   /** True once another layer took this layer's scene: destroying this one must not let it go. */
   _donated = false;
   /** What setup left on the objects the keyframes reach, shared with a layer that takes the scene over (core/setupValues.ts). */
-  _setupValues = new chunkNXMNBFHM_cjs.SetupValues();
+  _setupValues = new chunk6KVW442J_cjs.SetupValues();
   _pendingRebinds = [];
   _lightMirror = null;
   _fogMirror = null;
@@ -304,14 +304,14 @@ var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
     if (this.duration === void 0) this.duration = this.parent?.duration ?? this.root.duration;
     this._checkKeys();
     this._checkTint();
-    if (typeof spec.update === "function" && chunkNXMNBFHM_cjs.NOT_PURE.test(spec.update.toString())) {
+    if (typeof spec.update === "function" && chunk6KVW442J_cjs.NOT_PURE.test(spec.update.toString())) {
       this._say("pure", "update calls Math.random, Date.now, performance.now or new Date, so it is not deterministic: the same frame would draw differently in playback, in a seek and in an export. Derive the value from t");
     }
     const renderer = this.root.pixiRenderer;
     if (renderer && !renderer.renderPipes.view3d) {
       throw new Error(`${this._who()}: PixiJS 3D was loaded after the renderer started; import 'pixi-effects/3d' (and call register3D()) before movie.init`);
     }
-    const scope = chunkNXMNBFHM_cjs.buildScope(this, this.parent, this.root);
+    const scope = chunk6KVW442J_cjs.buildScope(this, this.parent, this.root);
     const width = resolveDim(spec.width, scope) ?? this.parent?.width ?? this.root.width;
     const height = resolveDim(spec.height, scope) ?? this.parent?.height ?? this.root.height;
     const viewOptions = { ...spec.view ?? {} };
@@ -420,7 +420,7 @@ var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
   }
   /** Unknown keys (with the likely one), and the keys only a three layer has. */
   _checkKeys() {
-    const valid = [...chunk3FCDRLW3_cjs.COMMON, ...OWN_KEYS];
+    const valid = [...chunkPBGZ47ZS_cjs.COMMON, ...OWN_KEYS];
     for (const key of Object.keys(this.spec)) {
       if (valid.includes(key)) continue;
       if (THREE_ONLY.includes(key)) {
@@ -501,8 +501,8 @@ var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
     const current = view.filters ?? [];
     const others = current.filter((f) => f !== this._look && f !== this._blend);
     const authored = String(this.spec.blendMode ?? "normal");
-    if (others.length === 0 && chunkGXGIISFS_cjs.isAdvancedBlend(authored) && !this._blend) {
-      this._blend = chunkGXGIISFS_cjs.blendFilterFor(authored);
+    if (others.length === 0 && chunkHMI6W5V3_cjs.isAdvancedBlend(authored) && !this._blend) {
+      this._blend = chunkHMI6W5V3_cjs.blendFilterFor(authored);
       if (this._blend) view.blendMode = "normal";
     }
     const mode = String(view.blendMode ?? "normal");
@@ -739,6 +739,31 @@ var Scene3DSequence = class extends chunkNXMNBFHM_cjs.Sequence {
       material: hit.target.material
     };
   }
+  /**
+   * `follow` / `movie.project`: where an object of the scene is on the canvas (a name setup returned in `objects`, or the label of any node), from the view's own projection
+   * of the node's origin; null while it is behind the camera, undefined for no such object.
+   */
+  screenPoint(object) {
+    const node = this._nodeNamed(object);
+    if (!node) return void 0;
+    const p = this._view?.worldToScreen(node.getGlobalPosition(new _3d.Vector3()));
+    return p ? { x: p.x, y: p.y } : null;
+  }
+  /** The names `screenPoint` knows: the objects setup returned, then the labelled nodes of the scene. */
+  objectNames() {
+    const names = new Set(Object.keys(this._objects).filter((k) => this._nodeNamed(k)));
+    const visit = (n) => {
+      if (n.label && n.label !== n.constructor?.name) names.add(n.label);
+      for (const c of n.children ?? []) visit(c);
+    };
+    if (this._view) for (const c of this._view.root.children) visit(c);
+    return [...names];
+  }
+  _nodeNamed(name) {
+    const own = this._objects[name];
+    if (own && typeof own.getGlobalPosition === "function") return own;
+    return this._view?.root.getChildByLabel(name, true) ?? null;
+  }
   /**
    * `hit.scene3d.grab(plane)`: a function of a point (u, v) of the layer's picture that gives where the pointer's ray meets a plane through the grabbed point, and how far that is
    * from it (`delta`): move the object by it. `plane`: 'screen' (facing the camera: the default), 'floor' (horizontal: y up), 'wall' (z constant), or a normal [x, y, z].
@@ -866,7 +891,7 @@ function reuseKeyOf(spec, width, height) {
 function resolveDim(v, scope) {
   if (v === void 0) return void 0;
   if (typeof v === "number") return v;
-  return chunkNXMNBFHM_cjs.evaluateExpr(v, scope);
+  return chunk6KVW442J_cjs.evaluateExpr(v, scope);
 }
 var label2 = "pixi-effects: loadModel";
 async function loadModel(url, options = {}) {
@@ -952,7 +977,7 @@ function register3D() {
   }
   _3d.Model3D.defaultOptions.autoUpdate = false;
   _3d.AnimationPlayer.defaultOptions.autoUpdate = false;
-  chunkNXMNBFHM_cjs.registerSequenceType("scene3d", Scene3DSequence);
+  chunk6KVW442J_cjs.registerSequenceType("scene3d", Scene3DSequence);
 }
 function scene3d(spec) {
   return spec;