@vgai/engine 0.5.12 → 0.5.14

package/dist/pixi/authoring.js

@@ -8,15 +8,21 @@ function kindOf(o) {
         return 'text';
     return 'container';
 }
+/** Deterministic structural-path ids: `w2d:<path>:<kind>:<label>`. */
+export const STRUCTURAL_CANVAS_IDENTITY = {
+    idFor: (object, path) => `w2d:${path.join('/')}:${kindOf(object)}:${object.label ?? ''}`,
+};
 export class AuthoringAdapter2D {
     root;
     byId = new Map();
     overlay = {};
     dirty = false;
+    identity;
     constructor(root, opts = {}) {
         this.root = root;
         if (opts.overlay)
             this.overlay = opts.overlay;
+        this.identity = opts.identity ?? STRUCTURAL_CANVAS_IDENTITY;
         this.refresh();
     }
     /**
@@ -30,21 +36,22 @@ export class AuthoringAdapter2D {
      */
     reindex() {
         this.byId.clear();
+        this.identity.beginWalk?.();
         let count = 0;
         let sprites = 0;
         const visit = (o, path) => {
-            const id = `w2d:${path}:${kindOf(o)}:${o.label ?? ''}`;
+            const id = this.identity.idFor(o, path);
             o.__authId = id;
             this.byId.set(id, o);
             count++;
             if (kindOf(o).includes('sprite'))
                 sprites++;
             o.children.forEach((c, i) => {
-                visit(c, `${path}/${i}`);
+                visit(c, [...path, i]);
             });
         };
         this.root.children.forEach((c, i) => {
-            visit(c, `${i}`);
+            visit(c, [i]);
         });
         return { count, sprites };
     }

package/dist/pixi/index.d.ts

@@ -7,7 +7,7 @@
  * in-realm mount, the live display-tree authoring adapter, and the
  * Rapier-2D handle registry the editor's transform coordination reads.
  */
-export { AuthoringAdapter2D, type EditorNode2D, type Overlay2D, type Override2D, type Property2D, type Transform2DValue, } from './authoring';
+export { AuthoringAdapter2D, type CanvasIdentity, type EditorNode2D, type Overlay2D, type Override2D, type Property2D, STRUCTURAL_CANVAS_IDENTITY, type Transform2DValue, } from './authoring';
 export { type IngestGame2D, type IngestMount2D, mountIngestGame2D } from './ingest';
 export { createPhysics2DRegistry, type Physics2DRefs, type Physics2DRegistry, } from './physics-registry';
 export { type CapturedRuntime2D, installSceneCapture2D, type SceneCapture2DHandle, } from './scene-capture';

package/dist/pixi/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pixi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pixi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,0BAA0B,EAC1B,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/pixi/index.js

@@ -7,7 +7,7 @@
  * in-realm mount, the live display-tree authoring adapter, and the
  * Rapier-2D handle registry the editor's transform coordination reads.
  */
-export { AuthoringAdapter2D, } from './authoring';
+export { AuthoringAdapter2D, STRUCTURAL_CANVAS_IDENTITY, } from './authoring';
 export { mountIngestGame2D } from './ingest';
 export { createPhysics2DRegistry, } from './physics-registry';
 export { installSceneCapture2D, } from './scene-capture';

package/dist/pixi/ingest.d.ts

@@ -1,3 +1,4 @@
+import type { VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
 import { type SceneCapture2DHandle } from './scene-capture';
 /** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
 export interface IngestGame2D {
@@ -22,8 +23,15 @@ export interface IngestMount2D {
  * instance, runs the game's `load()`, waits for the game to render its first
  * frame (capturing its live stage), and exposes loop gating + cleanup. A game
  * whose pixi the trap cannot reach never captures, and the mount FAILS by name.
+ *
+ * `onWait` is the three lane's own seam (`ingest-root-adapter.ts` passes
+ * `setCaptureWait`): the capture window PARKS while the tab is hidden, and a
+ * parked wait is otherwise indistinguishable from a hung mount at every door.
+ * Threading it here is what lets `vgai status` say "waiting for the first
+ * visible frame — the tab is hidden" over a canvas ingest too.
  */
 export declare function mountIngestGame2D(pixiNamespace: unknown, game: IngestGame2D, opts?: {
     captureTimeoutMs?: number;
+    onWait?: (wait: VisibleCaptureWindow | null) => void;
 }): Promise<IngestMount2D>;
 //# sourceMappingURL=ingest.d.ts.map

package/dist/pixi/ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/pixi/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEnF,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC,aAAa,CAAC,CAwBxB"}
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/pixi/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEnF,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE;IACJ,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,KAAK,IAAI,CAAC;CACjD,GACL,OAAO,CAAC,aAAa,CAAC,CA2BxB"}

package/dist/pixi/ingest.js

@@ -5,6 +5,12 @@ import { installSceneCapture2D } from './scene-capture';
  * instance, runs the game's `load()`, waits for the game to render its first
  * frame (capturing its live stage), and exposes loop gating + cleanup. A game
  * whose pixi the trap cannot reach never captures, and the mount FAILS by name.
+ *
+ * `onWait` is the three lane's own seam (`ingest-root-adapter.ts` passes
+ * `setCaptureWait`): the capture window PARKS while the tab is hidden, and a
+ * parked wait is otherwise indistinguishable from a hung mount at every door.
+ * Threading it here is what lets `vgai status` say "waiting for the first
+ * visible frame — the tab is hidden" over a canvas ingest too.
  */
 export async function mountIngestGame2D(pixiNamespace, game, opts = {}) {
     const capture = installSceneCapture2D(pixiNamespace);
@@ -17,7 +23,10 @@ export async function mountIngestGame2D(pixiNamespace, game, opts = {}) {
     }
     const timeout = opts.captureTimeoutMs ?? game.captureTimeoutMs ?? 8000;
     try {
-        const rt = await capture.waitForCapture(timeout);
+        const rt = await capture.waitForCapture({
+            timeoutMs: timeout,
+            ...(opts.onWait ? { onWait: opts.onWait } : {}),
+        });
         return {
             stage: rt.stage,
             capture,

package/dist/pixi/render-pass-bracket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The render-pass BRACKET on the Pixi surface — the canvas-substrate answer to
+ * the question the three lane answers with the render accessor-trap's
+ * `setRenderPassHooks` (`adapter/ingest/scene-capture.ts`): *when does this
+ * renderer's pass begin and end?*
+ *
+ * ## Why the renderer's own runners, and not another wrap
+ *
+ * Pixi's `AbstractRenderer.render()` emits five runners in a fixed order —
+ * `prerender → renderStart → render → renderEnd → postrender` (verified in the
+ * installed pixi.js 8.19,
+ * `rendering/renderers/shared/system/AbstractRenderer.mjs`). EVERY GL draw the
+ * pass issues happens between the first and the last: the batcher draws under
+ * `render`, and even the back-buffer blit, the one draw that is easy to miss,
+ * runs under `renderStart`/`renderEnd` (`gl/GlBackBufferSystem.mjs`). So a
+ * listener added to `prerender` and `postrender` brackets the whole pass using
+ * the renderer's OWN published seam — no instance shadowing, no prototype
+ * patch, no ordering assumption beyond the one Pixi itself guarantees.
+ *
+ * `SystemRunner.add(item)` binds by METHOD NAME (`item[runnerName]` must
+ * exist) and `remove(item)` takes it back off, so installing and uninstalling
+ * is symmetric and touches nothing else on the renderer.
+ *
+ * ## Honest absence
+ *
+ * A renderer that publishes no such runners is not bracketed by guesswork:
+ * this returns `null`, and the caller treats that exactly like a missing
+ * WebGL2 context — the capability is absent, never faked.
+ */
+import type { RenderPassHooks } from '../adapter/ingest/scene-capture';
+/**
+ * Bracket a Pixi renderer's render pass with `hooks.before`/`hooks.after`.
+ *
+ * Returns the uninstall function, or `null` when this renderer publishes no
+ * `prerender`/`postrender` runners — the honest "cannot bracket this", which
+ * the caller reads as "no render-debug capability here".
+ *
+ * Neither hook may throw — the same contract the three lane's `RenderPassHooks`
+ * carries, and for a sharper reason here: these run as listeners on the
+ * renderer's own runners, so a throwing `before` aborts the game's frame AND
+ * skips the `postrender` emit that would have closed the pass. The assembly
+ * point (`ingest/ingest-render-debug.ts`) is where that contract is kept.
+ */
+export declare function installPixiRenderPassBracket(renderer: unknown, hooks: RenderPassHooks): (() => void) | null;
+/**
+ * The captured Pixi renderer's real WebGL2 context, or `undefined`.
+ *
+ * `WebGLRenderer.gl` is the renderer's own published field — `GlContextSystem`
+ * assigns it (`this._renderer.gl = gl`,
+ * `rendering/renderers/gl/context/GlContextSystem.mjs`) as part of
+ * initialisation, and `WebGLRenderer.d.ts` declares it. A WebGPU renderer, or
+ * a renderer that has not initialised a context, simply has none — which is the
+ * answer, not an error.
+ */
+export declare function pixiRenderingContext(renderer: unknown): unknown;
+//# sourceMappingURL=render-pass-bracket.d.ts.map

package/dist/pixi/render-pass-bracket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-pass-bracket.d.ts","sourceRoot":"","sources":["../../src/pixi/render-pass-bracket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AA0BvE;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,eAAe,GACrB,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CA6BrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAG/D"}

package/dist/pixi/render-pass-bracket.js

@@ -0,0 +1,98 @@
+/**
+ * The render-pass BRACKET on the Pixi surface — the canvas-substrate answer to
+ * the question the three lane answers with the render accessor-trap's
+ * `setRenderPassHooks` (`adapter/ingest/scene-capture.ts`): *when does this
+ * renderer's pass begin and end?*
+ *
+ * ## Why the renderer's own runners, and not another wrap
+ *
+ * Pixi's `AbstractRenderer.render()` emits five runners in a fixed order —
+ * `prerender → renderStart → render → renderEnd → postrender` (verified in the
+ * installed pixi.js 8.19,
+ * `rendering/renderers/shared/system/AbstractRenderer.mjs`). EVERY GL draw the
+ * pass issues happens between the first and the last: the batcher draws under
+ * `render`, and even the back-buffer blit, the one draw that is easy to miss,
+ * runs under `renderStart`/`renderEnd` (`gl/GlBackBufferSystem.mjs`). So a
+ * listener added to `prerender` and `postrender` brackets the whole pass using
+ * the renderer's OWN published seam — no instance shadowing, no prototype
+ * patch, no ordering assumption beyond the one Pixi itself guarantees.
+ *
+ * `SystemRunner.add(item)` binds by METHOD NAME (`item[runnerName]` must
+ * exist) and `remove(item)` takes it back off, so installing and uninstalling
+ * is symmetric and touches nothing else on the renderer.
+ *
+ * ## Honest absence
+ *
+ * A renderer that publishes no such runners is not bracketed by guesswork:
+ * this returns `null`, and the caller treats that exactly like a missing
+ * WebGL2 context — the capability is absent, never faked.
+ */
+function runnerPair(renderer) {
+    if (!renderer || typeof renderer !== 'object')
+        return null;
+    const runners = renderer.runners;
+    const pre = runners?.prerender;
+    const post = runners?.postrender;
+    if (!pre || typeof pre.add !== 'function' || typeof pre.remove !== 'function')
+        return null;
+    if (!post || typeof post.add !== 'function' || typeof post.remove !== 'function')
+        return null;
+    return { pre, post };
+}
+/**
+ * Bracket a Pixi renderer's render pass with `hooks.before`/`hooks.after`.
+ *
+ * Returns the uninstall function, or `null` when this renderer publishes no
+ * `prerender`/`postrender` runners — the honest "cannot bracket this", which
+ * the caller reads as "no render-debug capability here".
+ *
+ * Neither hook may throw — the same contract the three lane's `RenderPassHooks`
+ * carries, and for a sharper reason here: these run as listeners on the
+ * renderer's own runners, so a throwing `before` aborts the game's frame AND
+ * skips the `postrender` emit that would have closed the pass. The assembly
+ * point (`ingest/ingest-render-debug.ts`) is where that contract is kept.
+ */
+export function installPixiRenderPassBracket(renderer, hooks) {
+    const pair = runnerPair(renderer);
+    if (!pair)
+        return null;
+    // One object per runner: `SystemRunner.add` binds by method name, so the
+    // `prerender` listener and the `postrender` listener cannot be the same
+    // object unless it answers to both — keeping them separate makes each
+    // `remove()` exact.
+    const preListener = {
+        prerender() {
+            hooks.before();
+        },
+    };
+    const postListener = {
+        postrender() {
+            hooks.after();
+        },
+    };
+    pair.pre.add(preListener);
+    pair.post.add(postListener);
+    let uninstalled = false;
+    return () => {
+        if (uninstalled)
+            return;
+        uninstalled = true;
+        pair.pre.remove(preListener);
+        pair.post.remove(postListener);
+    };
+}
+/**
+ * The captured Pixi renderer's real WebGL2 context, or `undefined`.
+ *
+ * `WebGLRenderer.gl` is the renderer's own published field — `GlContextSystem`
+ * assigns it (`this._renderer.gl = gl`,
+ * `rendering/renderers/gl/context/GlContextSystem.mjs`) as part of
+ * initialisation, and `WebGLRenderer.d.ts` declares it. A WebGPU renderer, or
+ * a renderer that has not initialised a context, simply has none — which is the
+ * answer, not an error.
+ */
+export function pixiRenderingContext(renderer) {
+    if (!renderer || typeof renderer !== 'object')
+        return undefined;
+    return renderer.gl;
+}

package/dist/pixi/scene-capture.d.ts

@@ -17,6 +17,20 @@
  * instance, so it is trapped; a game bundling its own pixi cannot be captured at
  * all, and its mount fails by name.
  */
+import { type VisibilityClock, type VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
+/**
+ * Options for {@link SceneCapture2DHandle.waitForCapture} — the same shape the
+ * three lane's `CaptureWaitOptions` has, because it is the same wait. Passing a
+ * bare number is `{ timeoutMs }`, which is what every existing caller does.
+ */
+export interface CaptureWait2DOptions {
+    /** The capture window, in VISIBLE milliseconds (default 10s). */
+    timeoutMs?: number | undefined;
+    /** Injected in tests; defaults to the document's own visibility. */
+    visibility?: VisibilityClock | undefined;
+    /** Live view of the wait while it runs, `null` the moment it ends. */
+    onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
 /** A live Pixi runtime captured from an external PixiJS game. */
 export interface CapturedRuntime2D {
     /** The game's root stage Container. */
@@ -28,7 +42,24 @@ export interface CapturedRuntime2D {
 }
 export interface SceneCapture2DHandle {
     readonly captured: CapturedRuntime2D | null;
-    waitForCapture(timeoutMs?: number): Promise<CapturedRuntime2D>;
+    /**
+     * Resolve once the game's stage is captured.
+     *
+     * The timeout is a budget of **VISIBLE** time, not wall-clock time — the same
+     * rule the three lane has had since `visible-capture-window.ts`, and for the
+     * same measured reason: a hidden document cannot render (the browser parks
+     * rAF), so counting hidden time against the game counts time it was not
+     * allowed to use. MEASURED on the bubbo-bubbo ingest with a plain
+     * `setTimeout` here: the mount succeeded when the auto-opened tab happened to
+     * be in front and died terminally 8s later when it was behind — "canvas
+     * ingest: game … rendered no capturable frame", with foregrounding the tab
+     * afterwards changing nothing. The normal HUMAN path is the backgrounded one.
+     *
+     * So the wait PARKS while hidden, the trap stays installed, and the first
+     * frame the tab draws after it comes forward is trapped exactly as it would
+     * have been at boot. Rejects only when the window is spent while VISIBLE.
+     */
+    waitForCapture(options?: number | CaptureWait2DOptions): Promise<CapturedRuntime2D>;
     getDrawCount(): number;
     /** Pause/resume the captured game's own ticker (loop-host gating). */
     setPaused(paused: boolean): void;

package/dist/pixi/scene-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../src/pixi/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/D,YAAY,IAAI,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,oBAAoB,CAoElF"}
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../src/pixi/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,0CAA0C,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACzC,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACpE;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpF,YAAY,IAAI,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,oBAAoB,CAgFlF"}

package/dist/pixi/scene-capture.js

@@ -17,6 +17,7 @@
  * instance, so it is trapped; a game bundling its own pixi cannot be captured at
  * all, and its mount fails by name.
  */
+import { documentVisibilityClock, startVisibleCaptureWindow, } from '../adapter/ingest/visible-capture-window';
 /**
  * Install the render trap on `pixiNamespace.Application.prototype.render`. Pass the
  * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
@@ -60,22 +61,33 @@ export function installSceneCapture2D(pixiNamespace) {
             else
                 app.ticker.start();
         },
-        waitForCapture(timeoutMs = 10_000) {
+        waitForCapture(options) {
+            const opts = typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
+            const timeoutMs = opts.timeoutMs ?? 10_000;
             if (captured)
                 return Promise.resolve(captured);
             return new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    const i = waiters.indexOf(wrapped);
-                    if (i >= 0)
-                        waiters.splice(i, 1);
-                    reject(new Error(`pixi scene capture timed out after ${timeoutMs}ms — the game never ` +
-                        `rendered, or it bundles its own (un-shared) copy of pixi.js.`));
-                }, timeoutMs);
+                const captureWindow = startVisibleCaptureWindow({
+                    budgetMs: timeoutMs,
+                    clock: opts.visibility ?? documentVisibilityClock(),
+                    onExpire: () => {
+                        const i = waiters.indexOf(wrapped);
+                        if (i >= 0)
+                            waiters.splice(i, 1);
+                        opts.onWait?.(null);
+                        reject(new Error(`pixi scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
+                            `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
+                            'a hidden tab cannot render) — the game never rendered, or it bundles its own ' +
+                            '(un-shared) copy of pixi.js.'));
+                    },
+                });
                 const wrapped = (rt) => {
-                    clearTimeout(timer);
+                    captureWindow.cancel();
+                    opts.onWait?.(null);
                     resolve(rt);
                 };
                 waiters.push(wrapped);
+                opts.onWait?.(captureWindow);
             });
         },
         uninstall() {

package/dist/pixi/system-adapters.d.ts

@@ -5,12 +5,41 @@ import type { Physics2DRegistry } from './physics-registry';
  * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
  * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
  * sticks instead of being stomped by the next physics step.
+ *
+ * KEYED BY THE DISPLAY OBJECT, and that is this surface's own vocabulary rather
+ * than a shortcut: the canvas gizmo's real caller
+ * (`editor/src/authoring/pixi-live-write-target.ts`) resolves node id → display
+ * itself before it asks, so there is no node-id hop on this lane at all.
+ *
+ * `keyedBy` is REQUIRED here and optional on the 3D {@link PhysicsAdapter} —
+ * see that interface's doc comment for why the union has to be tagged, and why
+ * the newcomer is the shape obliged to say so.
  */
 export interface PhysicsAdapter2D {
+    /** Discriminates this shape from the node-id-keyed {@link PhysicsAdapter}
+     *  inside `SystemAdapters['physics']`. */
+    readonly keyedBy: 'display';
     ownerOf(display: Container): 'physics' | 'none';
     freeze(display: Container): void;
     commit(display: Container, position: [number, number], rotation: number): void;
     unfreeze(display: Container): void;
 }
 export declare function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapter2D;
+/**
+ * ONE carrier over several, each owning a DIFFERENT set of display objects.
+ *
+ * The canvas ingest mount is the case: the host always builds a registry-backed
+ * carrier for objects the editor itself created, and an ingested game may ALSO
+ * declare one over its own simulation's objects. Neither is a superset of the
+ * other and neither can answer for the other's objects, so the composition is
+ * ownership-routed rather than layered — `ownerOf` asks each in order and the
+ * FIRST to claim the object handles every other call for it. A display object
+ * nobody claims answers `'none'` and the freeze/commit/unfreeze trio no-ops,
+ * which is exactly what a single unclaiming carrier already does.
+ *
+ * Order is precedence: earlier carriers win a (never-expected) double claim,
+ * so the caller states its own preference instead of this function inventing
+ * one.
+ */
+export declare function composePhysicsAdapters2D(carriers: readonly PhysicsAdapter2D[]): PhysicsAdapter2D;
 //# sourceMappingURL=system-adapters.d.ts.map

package/dist/pixi/system-adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-adapters.d.ts","sourceRoot":"","sources":["../../src/pixi/system-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,MAAM,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAgCnF"}
+{"version":3,"file":"system-adapters.d.ts","sourceRoot":"","sources":["../../src/pixi/system-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B;8CAC0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,MAAM,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAiCnF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,CAUhG"}

package/dist/pixi/system-adapters.js

@@ -2,6 +2,7 @@ export function createPhysicsAdapter2D(physics) {
     // Remember each frozen body's prior type so unfreeze restores it.
     const frozen = new WeakMap();
     return {
+        keyedBy: 'display',
         ownerOf(display) {
             const refs = physics.get(display);
             if (!refs)
@@ -35,3 +36,29 @@ export function createPhysicsAdapter2D(physics) {
         },
     };
 }
+/**
+ * ONE carrier over several, each owning a DIFFERENT set of display objects.
+ *
+ * The canvas ingest mount is the case: the host always builds a registry-backed
+ * carrier for objects the editor itself created, and an ingested game may ALSO
+ * declare one over its own simulation's objects. Neither is a superset of the
+ * other and neither can answer for the other's objects, so the composition is
+ * ownership-routed rather than layered — `ownerOf` asks each in order and the
+ * FIRST to claim the object handles every other call for it. A display object
+ * nobody claims answers `'none'` and the freeze/commit/unfreeze trio no-ops,
+ * which is exactly what a single unclaiming carrier already does.
+ *
+ * Order is precedence: earlier carriers win a (never-expected) double claim,
+ * so the caller states its own preference instead of this function inventing
+ * one.
+ */
+export function composePhysicsAdapters2D(carriers) {
+    const ownerFor = (display) => carriers.find((carrier) => carrier.ownerOf(display) === 'physics') ?? null;
+    return {
+        keyedBy: 'display',
+        ownerOf: (display) => (ownerFor(display) ? 'physics' : 'none'),
+        freeze: (display) => ownerFor(display)?.freeze(display),
+        commit: (display, position, rotation) => ownerFor(display)?.commit(display, position, rotation),
+        unfreeze: (display) => ownerFor(display)?.unfreeze(display),
+    };
+}

package/dist/render/particles-factory.d.ts

@@ -1,7 +1,9 @@
 /**
  * Converts ParticlesDescriptor JSON → three.quarks ParticleSystem.
  *
- * Shared between the editor entity-factory and the runtime scene-loader.
+ * A published engine entry point (the export map is the wildcard `./*`): the
+ * one in-repo caller is the godot-compat capability's `createCpuParticles3D`,
+ * and user games outside this repo reach it directly.
  * The schema mirrors quarks' native JSON format, so most fields pass through
  * directly to quarks' fromJSON or constructor methods.
  */
@@ -19,7 +21,7 @@ export interface ParticleSystemResult {
  * The non-JSON companion to a {@link ParticlesDescriptor} — the runtime objects
  * a JSON document cannot carry, and an authoring toggle. Every field is
  * optional and the whole argument is optional, so existing single-argument
- * callers (the editor entity-factory, the runtime scene-loader) are unchanged.
+ * callers are unchanged.
  *
  * This is how a caller with fidelity a plain descriptor cannot express reaches
  * the SAME factory instead of hand-building its own `new ParticleSystem(...)`:
@@ -86,10 +88,22 @@ export declare function applyParticlesDataLive(system: ParticleSystem, data: Par
 export declare function scrubParticleSystemTo(system: ParticleSystem, time: number, step?: number): void;
 /**
  * Register a particle system with a BatchedRenderer.
+ *
+ * This is also the ONE seat that arms the scene-depth prepass: a system built
+ * with `softParticles` compiles its batch with three.quarks' `SOFT_PARTICLES`
+ * define, which samples a `depthTexture` uniform nothing else in this engine
+ * would ever fill (see `render/soft-particle-depth.ts` for what an unfilled one
+ * does to the frame). Arming here — rather than in
+ * {@link createParticleSystemFromData} — is what makes it correct: the uniform
+ * lives on the BATCH, and no batch exists until a renderer is handed the
+ * system.
  */
 export declare function registerParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
 /**
  * Unregister a particle system from a BatchedRenderer.
+ *
+ * Disarms the depth prepass — one decrement against the arming above, so a
+ * renderer hosting several soft systems stays armed until its last one leaves.
  */
 export declare function unregisterParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
 /**

package/dist/render/particles-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/render/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAQL,KAAK,YAAY,EAmBlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAIV,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AAyNpC,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAC1C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AAEH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CA6DtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAsB9F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,IAAI,CAU/F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CA6B1D"}
+{"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/render/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAQL,KAAK,YAAY,EAmBlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAIV,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AA4RpC,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAC1C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AAEH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CA6DtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAsB9F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,IAAI,CAU/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CA6B1D"}