@vgai/engine 0.5.15 → 0.5.17

package/dist/asset-formats/mesh.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 export declare const MeshDescriptorSchema: z.ZodObject<{
     type: z.ZodEnum<{
-        capsule: "capsule";
-        box: "box";
         sphere: "sphere";
+        box: "box";
+        capsule: "capsule";
         plane: "plane";
         cylinder: "cylinder";
         gltf: "gltf";

package/dist/asset-formats/particles.d.ts

@@ -1387,8 +1387,8 @@ export declare const ParticlesDescriptorSchema: z.ZodObject<{
             anisotropy: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         blending: z.ZodOptional<z.ZodEnum<{
-            additive: "additive";
             normal: "normal";
+            additive: "additive";
         }>>;
         transparent: z.ZodOptional<z.ZodBoolean>;
         depthWrite: z.ZodOptional<z.ZodBoolean>;

package/dist/canvas-react/engine-bridge.d.ts

@@ -12,17 +12,17 @@
  * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
  * `useApplication` is the door to the live `Application`.
  */
-import type { GameContext } from '../runtime/types';
+import type { CanvasGameContext } from './world-context';
 export interface EngineBridgeValue {
-    /** This root's `GameContext` — `input`, `debug`, `random`, `clock`, `game`,
+    /** This root's `CanvasGameContext` — `input`, `debug`, `random`, `clock`, `game`,
      *  `roots`, `systems`, `registerSystemAdapter`. Present so ordinary
      *  components can reach engine services with a HOOK (see
      *  {@link useGameContext}). */
-    readonly ctx?: GameContext | undefined;
+    readonly ctx?: CanvasGameContext | undefined;
 }
 export declare const EngineBridge: import("react").Context<EngineBridgeValue | null>;
 /**
- * This canvas root's `GameContext`, for use inside any component in the tree.
+ * This canvas root's `CanvasGameContext`, for use inside any component in the tree.
  *
  * An ordinary component does what a model would write:
  *
@@ -31,7 +31,7 @@ export declare const EngineBridge: import("react").Context<EngineBridgeValue | n
  *   const { input } = useGameContext();
  *   const ref = useRef<Sprite>(null);
  *   useTick(({ deltaMS }) => {
- *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *     if (input?.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
  *   });
  *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
  * }
@@ -41,5 +41,5 @@ export declare const EngineBridge: import("react").Context<EngineBridgeValue | n
  * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
  * `null` would surface as a mystery `undefined` deep in a tick callback.
  */
-export declare function useGameContext(): GameContext;
+export declare function useGameContext(): CanvasGameContext;
 //# sourceMappingURL=engine-bridge.d.ts.map

package/dist/canvas-react/engine-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/canvas-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC;;;mCAG+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACxC;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAU5C"}
+{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/canvas-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC;;;mCAG+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC9C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,CAUlD"}

package/dist/canvas-react/engine-bridge.js

@@ -15,7 +15,7 @@
 import { createContext, useContext } from 'react';
 export const EngineBridge = createContext(null);
 /**
- * This canvas root's `GameContext`, for use inside any component in the tree.
+ * This canvas root's `CanvasGameContext`, for use inside any component in the tree.
  *
  * An ordinary component does what a model would write:
  *
@@ -24,7 +24,7 @@ export const EngineBridge = createContext(null);
  *   const { input } = useGameContext();
  *   const ref = useRef<Sprite>(null);
  *   useTick(({ deltaMS }) => {
- *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *     if (input?.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
  *   });
  *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
  * }

package/dist/canvas-react/index.d.ts

@@ -22,7 +22,7 @@
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
  *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
  *    Behavior in a canvas world is components + hooks, never a class under a
  *    string key.
@@ -38,5 +38,5 @@ export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-b
 export { adoptNow, PixiPrimitive, type PixiPrimitiveProps } from './pixi-primitive';
 export { type CreatePixiReactAdapterOptions, createPixiReactAdapter, } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
-export { type CanvasRootContextOptions, type CanvasRootRuntime, createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';
+export { type CanvasGameContext, type CanvasRootContextOptions, type CanvasRootRuntime, createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';
 //# sourceMappingURL=index.d.ts.map

package/dist/canvas-react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/canvas-react/index.js

@@ -22,7 +22,7 @@
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
  *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
  *    Behavior in a canvas world is components + hooks, never a class under a
  *    string key.

package/dist/canvas-react/pixi-react-adapter.d.ts

@@ -6,20 +6,20 @@
  * this returns a `MountedPixiRoot` (`../adapter/root-adapter.ts`) whose `stage`
  * is the REAL `PIXI.Container` the reconciler renders into.
  *
- * This is the canvas surface's exact sibling of `world3d-react`'s
+ * This is the canvas surface's sibling of `world3d-react`'s
  * `createR3FAdapter`, with `@pixi/react` where that one has
- * react-three-fiber. Everything structural is the same, because the seam is
- * the same: one loop (the host's), one canvas (the host's), a world-local
- * `SystemRunner` ticked in engine phase order before the renderer advances,
- * and a `GameContext` threaded into the tree through `EngineBridge`.
+ * react-three-fiber. The explicit factory still supplies the engine context
+ * used by the current first-party Canvas examples while their app-owned input
+ * and debugger migration remains tracked in `docs/WORK.md`; `useTick` hooks
+ * stay registered on Pixi's real ticker throughout that migration.
  *
  * ## The loop contract
  *
  * `Application` is initialized with `autoStart: false` and `sharedTicker:
- * false`, so it owns a ticker that is NEVER started and therefore never
- * requests an animation frame. `mounted.update(dt)` is the only thing that
- * advances it, and it feeds GAME time, not wall time — which is what makes the
- * world freeze exactly when the host freezes it, and what makes
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
  * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
  * loop's own catch-up still calls `update`, and Pixi has no independent clock
  * to disagree with it).
@@ -50,6 +50,12 @@ export interface CreatePixiReactAdapterOptions {
      *  actions). A missing/invalid map degrades loudly without failing the
      *  mount — see `world-context.ts`. */
     readonly inputMapPath?: string | null | undefined;
+    /**
+     * Transitional compatibility for component trees that still consume the
+     * engine context. Native trees opt out once their input, observation and
+     * debugger state are application-owned.
+     */
+    readonly engineRuntime?: boolean | undefined;
     /**
      * Extra `Application.init` options merged UNDER this adapter's own — e.g.
      * `{ antialias: false }`, `{ roundPixels: true }`. The loop-critical ones

package/dist/canvas-react/pixi-react-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-react-adapter.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAiB,KAAK,SAAS,EAAmB,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AAyBlF,sFAAsF;AACtF,MAAM,WAAW,6BAA6B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;yDACqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,WAAW,CAAC,QAAQ,CAAC,CA8LvB"}
+{"version":3,"file":"pixi-react-adapter.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAA2B,KAAK,SAAS,EAA8B,MAAM,OAAO,CAAC;AAC5F,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AA2BlF,sFAAsF;AACtF,MAAM,WAAW,6BAA6B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;yDACqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,WAAW,CAAC,QAAQ,CAAC,CAwPvB"}

package/dist/canvas-react/pixi-react-adapter.js

@@ -6,20 +6,20 @@
  * this returns a `MountedPixiRoot` (`../adapter/root-adapter.ts`) whose `stage`
  * is the REAL `PIXI.Container` the reconciler renders into.
  *
- * This is the canvas surface's exact sibling of `world3d-react`'s
+ * This is the canvas surface's sibling of `world3d-react`'s
  * `createR3FAdapter`, with `@pixi/react` where that one has
- * react-three-fiber. Everything structural is the same, because the seam is
- * the same: one loop (the host's), one canvas (the host's), a world-local
- * `SystemRunner` ticked in engine phase order before the renderer advances,
- * and a `GameContext` threaded into the tree through `EngineBridge`.
+ * react-three-fiber. The explicit factory still supplies the engine context
+ * used by the current first-party Canvas examples while their app-owned input
+ * and debugger migration remains tracked in `docs/WORK.md`; `useTick` hooks
+ * stay registered on Pixi's real ticker throughout that migration.
  *
  * ## The loop contract
  *
  * `Application` is initialized with `autoStart: false` and `sharedTicker:
- * false`, so it owns a ticker that is NEVER started and therefore never
- * requests an animation frame. `mounted.update(dt)` is the only thing that
- * advances it, and it feeds GAME time, not wall time — which is what makes the
- * world freeze exactly when the host freezes it, and what makes
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
  * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
  * loop's own catch-up still calls `update`, and Pixi has no independent clock
  * to disagree with it).
@@ -36,8 +36,9 @@
  */
 import { createRoot, extend } from '@pixi/react';
 import * as PIXI from 'pixi.js';
-import { createElement, useLayoutEffect } from 'react';
+import { createElement, Fragment, useEffect, useLayoutEffect } from 'react';
 import { WorldProvider } from '../react/world-state';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { EngineBridge } from './engine-bridge';
 import { createCanvasRootContext } from './world-context';
 /** How long `mount()` waits for the tree's first commit before failing loudly
@@ -61,18 +62,18 @@ const MOUNTED_CANVASES = new WeakSet();
  * `requestAnimationFrame` loop.
  */
 export function createPixiReactAdapter(options) {
-    const { id, content, inputMapPath, applicationOptions } = options;
+    const { id, content, inputMapPath, engineRuntime = true, applicationOptions } = options;
     return {
         id,
         async mount(host) {
-            const runtime = createCanvasRootContext(host, { id, inputMapPath });
-            const bridge = { ctx: runtime.ctx };
+            const runtime = engineRuntime ? createCanvasRootContext(host, { id, inputMapPath }) : null;
+            const bridge = runtime ? { ctx: runtime.ctx } : null;
             // Actions must exist before any component's first tick reads them — wait
             // for the (never-rejecting) input-map load before the first commit.
-            await runtime.inputMapReady;
+            await runtime?.inputMapReady;
             const canvas = host.canvas;
             if (MOUNTED_CANVASES.has(canvas)) {
-                runtime.dispose();
+                runtime?.dispose();
                 throw new Error(`createPixiReactAdapter: root "${id}" was handed a canvas this lane has already ` +
                     'mounted. @pixi/react keys its reconciler roots off the canvas element, so re-using ' +
                     'one would resurrect a root whose Application is destroyed. Hand each mount a fresh ' +
@@ -85,6 +86,10 @@ export function createPixiReactAdapter(options) {
             const committed = new Promise((resolve) => {
                 resolveCommitted = resolve;
             });
+            let resolveEffectsReady;
+            const effectsReady = new Promise((resolve) => {
+                resolveEffectsReady = resolve;
+            });
             let resolveUnmounted;
             const unmounted = new Promise((resolve) => {
                 resolveUnmounted = resolve;
@@ -108,16 +113,38 @@ export function createPixiReactAdapter(options) {
                     resolveCommitted();
                     return resolveUnmounted;
                 }, []);
+                // This component is the last sibling. Reaching its passive effect
+                // means the initial tree's useDebugProvider/useDebugCommand effects
+                // have registered, so mount() can truthfully back Play's ack.
+                useEffect(resolveEffectsReady, []);
                 return null;
             }
-            const game = runtime.ctx.game;
             // The React seam every dom root already has — `useWorldState`,
             // `useDebugProvider`/`useDebugCommand`/`useDebugEmit`
             // (`../react/world-state`) — works identically inside a canvas root
             // because a canvas root IS React. `host.game` is genuinely absent in
             // bare/foreign hosts, so the provider is conditional and those hooks
             // stay the inert no-ops they already document themselves to be.
-            const element = createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, content) : content, createElement(Lifecycle));
+            //
+            // READ FROM `host.game`, NEVER FROM `runtime` — the same rule, and the
+            // same reasoning, as the three lane's (`../world3d-react/r3f-adapter.tsx`,
+            // beside its own `const game = host.game`). The two providers answer
+            // different questions: `EngineBridge` rides `bridge` (the vgai runtime
+            // CONTEXT, which must not enter an ecosystem-native tree), `WorldProvider`
+            // rides the Game handle the host already holds. Keyed off `runtime`, a
+            // world mounted with `engineRuntime: false` gets no `WorldProvider` at
+            // all and every `useDebugProvider` in it no-ops IN SILENCE — no error, and
+            // `vgai eval 'await game.providers()'` lists only the built-ins. That is
+            // exactly what happened on the three lane. It has never fired here only
+            // because `pixi-react-root-factory.tsx` still leaves the runtime on;
+            // that flag is the tracked component-root migration's to flip, and this
+            // seam must not be waiting for it.
+            const game = host.game;
+            const world = createElement(Fragment, null, content, createElement(Lifecycle));
+            const provided = game ? createElement(WorldProvider, { game }, world) : world;
+            const element = bridge
+                ? createElement(EngineBridge.Provider, { value: bridge }, provided)
+                : provided;
             const root = createRoot(canvas);
             // The host owns size, dpr, transparency and capture cost; the loop
             // contract owns `autoStart`/`sharedTicker`. Both are applied AFTER the
@@ -136,69 +163,101 @@ export function createPixiReactAdapter(options) {
                 autoStart: false,
                 sharedTicker: false,
             };
-            // `root.render` is async: it awaits `Application.init()` (which is what
-            // creates the renderer) and only then hands the tree to the reconciler.
-            // A crash inside init rejects here, which is the loud failure we want.
-            const app = await root.render(element, initOptions);
-            runtime.setApplication(app);
-            // A reconcile-time crash (e.g. an un-extended component) surfaces as an
-            // uncaught window error and the first commit never lands — without this
-            // guard `mount()` would await `committed` forever. Convert that class of
-            // failure into a loud mount error.
-            await new Promise((resolve, reject) => {
-                const fail = (why) => {
-                    cleanup();
-                    try {
-                        app.destroy(false, { children: true });
-                    }
-                    catch {
-                        /* the world never fully came up; teardown failure must not mask why */
-                    }
-                    runtime.dispose();
-                    reject(new Error(`createPixiReactAdapter: root "${id}" — ${why}`));
-                };
-                const onError = (event) => fail(`the Pixi tree crashed before its first commit — ${event.message} ` +
+            // Install the reconcile-error listener BEFORE `root.render`: Pixi hands
+            // the Application back after `init()` but React can already have thrown
+            // during that same turn. Attaching after the await loses the real error
+            // and turns it into a misleading ten-second timeout.
+            let reportReconcileFailure;
+            const reconcileFailure = new Promise((resolve) => {
+                reportReconcileFailure = resolve;
+            });
+            const onError = (event) => {
+                reportReconcileFailure(`the Pixi tree crashed before its first commit — ${event.message} ` +
                     '(mount() fails loudly instead of hanging)');
-                const timer = setTimeout(() => fail(`no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
-                    '(mount() fails loudly instead of hanging)'), FIRST_COMMIT_TIMEOUT_MS);
-                const cleanup = () => {
-                    clearTimeout(timer);
-                    globalThis.removeEventListener?.('error', onError);
-                };
-                globalThis.addEventListener?.('error', onError);
-                void committed.then(() => {
-                    cleanup();
-                    resolve();
+            };
+            globalThis.addEventListener?.('error', onError);
+            let app;
+            let timer;
+            try {
+                // `root.render` is async: it awaits `Application.init()` (which is what
+                // creates the renderer) and only then hands the tree to the reconciler.
+                // A crash inside init rejects here, which is the loud failure we want.
+                const renderedApp = await root.render(element, initOptions);
+                app = renderedApp;
+                runtime?.setApplication(renderedApp);
+                // A reconcile-time crash (e.g. an un-extended component) surfaces as
+                // an uncaught window error and the first commit never lands. Race that
+                // exact signal against the commit and the last-resort ceiling.
+                const timeout = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(`no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
+                        '(mount() fails loudly instead of hanging)'), FIRST_COMMIT_TIMEOUT_MS);
                 });
-            });
+                const failure = await Promise.race([
+                    Promise.all([committed, effectsReady]).then(() => null),
+                    reconcileFailure,
+                    timeout,
+                ]);
+                if (failure !== null) {
+                    throw new Error(`createPixiReactAdapter: root "${id}" — ${failure}`);
+                }
+            }
+            catch (error) {
+                try {
+                    app?.destroy(false, { children: true });
+                }
+                catch {
+                    /* the world never fully came up; teardown failure must not mask why */
+                }
+                runtime?.dispose();
+                throw error;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                globalThis.removeEventListener?.('error', onError);
+            }
+            // `app` is assigned before the first-commit race. Reaching here proves
+            // both initialization and commit succeeded, so narrow once for the live
+            // mounted-root methods below.
+            if (app === undefined) {
+                runtime?.dispose();
+                throw new Error(`createPixiReactAdapter: root "${id}" initialized without an Application`);
+            }
+            const mountedApp = app;
             // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
             // without this the first `update()` would report a 1ms phantom delta on
             // top of the real one. From here every `deltaMS` a `useTick` callback
             // sees is exactly the `dt` the host handed us — no wall clock anywhere,
             // which is what makes a paused world's resume frame ordinary rather than
             // one giant catch-up step.
-            app.ticker.lastTime = 0;
+            mountedApp.ticker.lastTime = 0;
             let elapsedMs = 0;
             let disposed = false;
+            const registry = host.game ? getDebugRegistry(host.game) : null;
+            const systemAdapters = runtime?.systemAdapters ?? (registry ? { debug: registry.adapter } : {});
+            const disposeComplete = unmounted.then(() => {
+                mountedApp.destroy(false, { children: true });
+            });
             return {
                 kind: 'canvas',
                 // The reconciler's real root container — the same `PIXI.Container`
                 // `RootInstance.pixiStage()` hands the editor.
-                stage: app.stage,
+                stage: mountedApp.stage,
                 drivesOwnLoop: false,
-                // Adapter surface: `debug` pre-seeded (the shared game registry's
-                // adapter); game code adds capabilities via `ctx.registerSystemAdapter`.
-                systems: runtime.systemAdapters,
+                // Adapter surface: the host's shared debug registry. A native component
+                // tree registers nothing; its entry-module `debug` export is projected
+                // after mount by the shared native adapter.
+                systems: systemAdapters,
+                disposeComplete,
                 update(dt) {
                     if (disposed)
                         return;
                     elapsedMs += dt * 1000;
-                    // Engine phases FIRST (registered systems mutate transforms), then
-                    // the ticker — so `useTick` callbacks and the render that follows
-                    // them at `UPDATE_PRIORITY.LOW` both see the fresh state. Both are
-                    // host-gated: neither runs while this world is frozen.
-                    runtime.systems.run(dt);
-                    app.ticker.update(elapsedMs);
+                    // The optional legacy runtime drains first when explicitly enabled;
+                    // the native path has none. The real Pixi ticker remains the one
+                    // scheduler `useTick` observes, and the host only gates/advances it.
+                    runtime?.systems.run(dt);
+                    mountedApp.ticker.update(elapsedMs);
                 },
                 resize(width, height) {
                     if (disposed)
@@ -206,12 +265,19 @@ export function createPixiReactAdapter(options) {
                     // `autoDensity: true` makes Pixi re-stamp `canvas.style.width`/
                     // `.height` from this call, so the on-screen box follows the logical
                     // size with no explicit CSS write from the host.
-                    app.renderer.resize(width, height);
+                    mountedApp.renderer.resize(width, height);
                 },
                 dispose() {
                     if (disposed)
                         return;
                     disposed = true;
+                    // Pixi's EventSystem owns document.pointermove + window.pointerup
+                    // (and its event ticker's global listener). React's deletion commit
+                    // is asynchronous, so waiting to destroy the Application leaves
+                    // those listeners live when the host audits this game realm. Detach
+                    // the input target synchronously; the later Application.destroy()
+                    // repeats this idempotently after every useTick cleanup has landed.
+                    mountedApp.renderer.events.setTargetElement(null);
                     // Rendering `null` children is the only unmount path `@pixi/react`
                     // exposes publicly (its `unmountRoot` helper is internal), and React
                     // commits that deletion on its own schedule — NOT synchronously. So
@@ -220,8 +286,7 @@ export function createPixiReactAdapter(options) {
                     // a ticker destroyed before it lands throws inside React's commit.
                     // `removeView` stays false — the canvas belongs to the HOST.
                     void root.render(null, initOptions);
-                    void unmounted.then(() => app.destroy(false, { children: true }));
-                    runtime.dispose();
+                    runtime?.dispose();
                 },
             };
         },

package/dist/canvas-react/pixi-react-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAU9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAQlC,CAAC"}
+{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAc9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAQlC,CAAC"}

package/dist/canvas-react/pixi-react-root-factory.js

@@ -53,6 +53,10 @@ export function resolveCanvasEntryAdapter(entryModule, rootId) {
         return createPixiReactAdapter({
             id: rootId,
             content: createElement(mod.default),
+            // The supported Canvas portfolio still consumes the compatibility
+            // context. Removing it belongs to the tracked component-root migration;
+            // disabling it here first made every current default-exported game fail
+            // to mount before that migration had happened.
         });
     }
     return null;

package/dist/canvas-react/world-context.d.ts

@@ -11,7 +11,8 @@
  *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
  *     component's effect can `ctx.debug.registerStateProvider(...)` and be
  *     visible to `vgai eval`/the editor's debug panels.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` — the
  *     same instance every sibling root shares), and this module registers the
  *     per-world debug-registry seams (`setVirtualInputTarget`/
  *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
@@ -19,13 +20,14 @@
  *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
  *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
  *     A missing/unparseable map degrades LOUDLY without failing the mount — a
- *     canvas world with no declared actions is legal.
- *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
- *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
- *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
- *     context carries none — see `adapter/host-context.ts`). Reading those
- *     `ctx` fields yields a throwing getter naming the limitation and the
- *     sanctioned alternative, never a silent `undefined`.
+ *     canvas world with no declared actions is legal. A bare/foreign mount
+ *     receives `null`, visibly in the type, rather than a throwing getter.
+ *  3. **Absent subsystems are absent from the type.** A canvas world builds no
+ *     THREE scene/camera, Rapier world, composer, first-party audio/particles/
+ *     debug-draw, or Three-flavoured `AssetCache`. Its explicit
+ *     {@link CanvasGameContext} cannot name those fields, so misuse fails at
+ *     the call site during typechecking instead of from a throwing getter at
+ *     runtime.
  *
  * The Pixi handles themselves are deliberately NOT re-exposed here: a component
  * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
@@ -36,8 +38,9 @@
 import type { Application } from 'pixi.js';
 import type { CanvasHostContext } from '../adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
+import type { SimClock } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
-import type { GameContext } from '../runtime/types';
+import type { ComponentContextBase } from '../runtime/types';
 /** The conventional input-map location every scaffolded project ships. Shared
  *  verbatim with the three lane — a project has ONE input map, whatever surface
  *  reads it. */
@@ -55,12 +58,19 @@ export interface CanvasRootContextOptions {
      */
     readonly inputMapPath?: string | null | undefined;
 }
+/** The engine services a Canvas component genuinely receives. Pixi's own
+ * `useApplication()` and `Assets` remain the doors to rendering and assets.
+ * `disposeAfter` is excluded because it accepts a `THREE.Object3D`; Canvas
+ * code schedules `displayObject.destroy()` with `clock.after()` instead. */
+export type CanvasGameContext = ComponentContextBase & {
+    readonly clock: Omit<SimClock, 'disposeAfter'>;
+};
 /** What {@link createCanvasRootContext} returns — the engine runtime one canvas
  *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
 export interface CanvasRootRuntime {
-    /** The (partial, loud-on-absence) `GameContext` this world's components read
-     *  through `useGameContext`. See this module's header for what is present. */
-    readonly ctx: GameContext;
+    /** The explicit Canvas context this world's components read through
+     *  `useGameContext`. See {@link CanvasGameContext}. */
+    readonly ctx: CanvasGameContext;
     /** The world-local phase runner `mount().update(dt)` ticks. */
     readonly systems: ReturnType<typeof createSystemRunner>;
     /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —

package/dist/canvas-react/world-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/canvas-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;gBAEgB;AAChB,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC;6BACyB;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;wEACwE;AACxE,MAAM,WAAW,iBAAiB;IAChC;kFAC8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;gFAC4E;IAC5E,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;8CAE0C;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AA4BD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAoMnB"}
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/canvas-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;gBAEgB;AAChB,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC;6BACyB;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;;;4EAG4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG;IACrD,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;CAChD,CAAC;AAEF;wEACwE;AACxE,MAAM,WAAW,iBAAiB;IAChC;2DACuD;IACvD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;gFAC4E;IAC5E,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;8CAE0C;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAwInB"}