@vgai/engine 0.5.25 → 0.5.27

package/src/adapter/root-seam-contract.ts

@@ -2,7 +2,7 @@
 
 import type { AdapterSurface } from './adapter-surface';
 import type {
-  MountedPixiRoot,
+  MountedCanvasRoot,
   MountedReactRoot,
   MountedRootBase,
   MountedThreeRoot,
@@ -36,7 +36,7 @@ export const ROOT_STATE_OBSERVER_SHAPE = defineSeamShape<RootStateObserver>()({
 });
 
 type ThreeSurface = Omit<MountedThreeRoot, keyof MountedRootBase>;
-type CanvasSurface = Omit<MountedPixiRoot, keyof MountedRootBase>;
+type CanvasSurface = Omit<MountedCanvasRoot, keyof MountedRootBase>;
 type DomSurface = Omit<MountedReactRoot, keyof MountedRootBase>;
 
 export const MOUNTED_THREE_SURFACE_SHAPE = defineSeamShape<ThreeSurface>()({
@@ -48,7 +48,8 @@ export const MOUNTED_THREE_SURFACE_SHAPE = defineSeamShape<ThreeSurface>()({
 
 export const MOUNTED_CANVAS_SURFACE_SHAPE = defineSeamShape<CanvasSurface>()({
   kind: { optional: false, kind: 'value', required: 'shape' },
-  stage: { optional: false, kind: 'value', required: 'effect' },
+  canvas: { optional: false, kind: 'value', required: 'effect' },
+  substrate: { optional: false, kind: 'value', required: 'effect' },
 });
 
 export const MOUNTED_DOM_SURFACE_SHAPE = defineSeamShape<DomSurface>()({

package/src/adapter/system-adapter.ts

@@ -357,6 +357,16 @@ export interface NavCrowdAgentState {
   velocity: NavPoint;
   radius: number;
   height: number;
+  /** The crowd's own agent state. `invalid` is the expressible FAILURE — the
+   * agent is off the navmesh (a bad spawn or teleport) and will not move;
+   * `offmesh` is an off-mesh connection traversal. Absent on an adapter that
+   * predates this field — the editor draws such agents as walking. */
+  state?: 'invalid' | 'walking' | 'offmesh';
+  /** The agent's current move target, when the implementation reports one. */
+  target?: NavPoint;
+  /** The local path-corridor corners the agent is steering along — the
+   * REQUESTED PATH the debug draw projects. Empty or absent when idle. */
+  corners?: NavPoint[];
 }
 
 /**

package/src/ai/navigation.ts

@@ -31,8 +31,22 @@ export interface CrowdAgentSnapshot {
   velocity: Vector3Like;
   radius: number;
   height: number;
+  /** Detour's own agent state. `invalid` is the crowd's expressible FAILURE —
+   * the agent is not on the navmesh (a bad spawn or teleport) and will not
+   * move until re-placed; `offmesh` is an off-mesh connection traversal. */
+  state: 'invalid' | 'walking' | 'offmesh';
+  /** The agent's current move target — detour's own answer, reported as the
+   * fact it is. Whether a request is ACTIVE is what {@link corners} says. */
+  target: Vector3Like;
+  /** The local path-corridor corners toward the target — the REQUESTED PATH
+   * the crowd is steering along right now (detour keeps a local corridor, not
+   * the whole route). Empty when the agent has nowhere to go. */
+  corners: Vector3Like[];
 }
 
+/** Detour `CrowdAgentState` values, named. */
+const AGENT_STATES = ['invalid', 'walking', 'offmesh'] as const;
+
 export interface NavMeshBuildParams {
   cellSize?: number | undefined;
   cellHeight?: number | undefined;
@@ -176,11 +190,21 @@ export class NavMeshManager {
     return this.crowd.getAgents().map((a) => {
       const p = a.interpolatedPosition;
       const v = a.velocity();
+      const t = a.target();
+      // An invalid agent has no corridor, and detour's accessors are not
+      // guaranteed meaningful off the mesh — report the failure state with an
+      // empty path rather than reading through it.
+      const state = AGENT_STATES[a.state()] ?? 'invalid';
+      const corners =
+        state === 'invalid' ? [] : a.corners().map((c) => ({ x: c.x, y: c.y, z: c.z }));
       return {
         position: { x: p.x, y: p.y, z: p.z },
         velocity: { x: v.x, y: v.y, z: v.z },
         radius: a.radius,
         height: a.height,
+        state,
+        target: { x: t.x, y: t.y, z: t.z },
+        corners,
       };
     });
   }

package/src/canvas-react/pixi-react-root-factory.tsx

@@ -80,6 +80,20 @@ type PixiReactRoot = ReturnType<typeof createRoot>;
 interface CanvasEntryModuleExports {
   /** The one shape: the world IS a component. */
   readonly default?: ComponentType;
+  /** Imperative canvas substrates export their own host adapter. This is the
+   * same explicit boundary the three entry adjudicator accepts; gameplay
+   * modules remain ecosystem-native. */
+  readonly adapter?: unknown;
+}
+
+function isCanvasRootAdapter(candidate: unknown): candidate is RootAdapter<'canvas'> {
+  if (candidate === null || typeof candidate !== 'object') return false;
+  const value = candidate as Record<string, unknown>;
+  return (
+    typeof value['id'] === 'string' &&
+    value['id'].length > 0 &&
+    typeof value['mount'] === 'function'
+  );
 }
 
 /**
@@ -274,9 +288,8 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
 
       return {
         kind: 'canvas',
-        // The reconciler's real root container — the same `PIXI.Container`
-        // `RootInstance.pixiStage()` hands the editor.
-        stage: mountedApp.stage,
+        canvas,
+        substrate: { name: 'pixi', root: mountedApp.stage },
         drivesOwnLoop: false,
         systems: systemAdapters,
         disposeComplete,
@@ -337,6 +350,7 @@ export function resolveCanvasEntryAdapter(
   rootId: string,
 ): RootAdapter<'canvas'> | null {
   const mod = entryModule as CanvasEntryModuleExports | undefined;
+  if (isCanvasRootAdapter(mod?.adapter)) return mod.adapter;
   if (typeof mod?.default === 'function') return canvasWorldAdapter(rootId, mod.default);
   return null;
 }

package/src/pixi/authoring.ts

@@ -2,7 +2,7 @@ import type { Container } from 'pixi.js';
 
 /**
  * AuthoringAdapter-2D — the Pixi analog of the editor AuthoringAdapter /
- * LiveThreeAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
+ * ThreeAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
  * (no fabricated document — the anti-shim rule). Used by the editor to
  * inspect + edit Pixi display-tree entities (first-party OR an ingested unmodified game),
  * with stable structural-path ids so edits re-bind after the tree rebuilds.
@@ -668,7 +668,7 @@ export class AuthoringAdapter2D {
    * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
    * and a later `refresh()` re-applies it again. Ids absent from the current tree
    * are skipped (orphaned, not an error) — the 2D analog of
-   * `LiveThreeAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+   * `ThreeAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
    * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
    * (re-apply a changed overlay file without a full remount).
    */
@@ -699,7 +699,7 @@ export class AuthoringAdapter2D {
     for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
     this.dirty = true;
   }
-  /** Clear the dirty flag after a successful save (mirrors LiveThreeAuthoringAdapter). */
+  /** Clear the dirty flag after a successful save (mirrors ThreeAuthoringAdapter). */
   markClean(): void {
     this.dirty = false;
   }

package/src/runtime/create-runtime.ts

@@ -3,7 +3,7 @@ import { assertNever } from '../adapter/adapter-surface';
 import { createRootBinding, type RootBinding, type RootDeclaration } from '../adapter/binding';
 import type { CanvasHostContext, DomHostContext, ThreeHostContext } from '../adapter/host-context';
 import type {
-  MountedPixiRoot,
+  MountedCanvasRoot,
   MountedReactRoot,
   MountedRoot,
   MountedThreeRoot,
@@ -100,16 +100,17 @@ function bindRoot(
 }
 
 /**
- * Register a canvas world onto the Game shell — the pixi analog of
+ * Register a canvas world onto the Game shell — the canvas analog of
  * {@link registerThreeRoot}. `adapter` is the seam's own
  * `RootAdapter<'canvas'>`; `RootInstance.adapter` itself only needs `.id`
  * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
- * `stage` is the one field every `MountedPixiRoot` actually carries.
+ * The substrate root remains opaque here; the editor dispatches from the
+ * mount's explicit `substrate.name` declaration.
  */
-export function registerPixiRoot(
+export function registerCanvasRoot(
   game: GameInternal,
   adapter: RootAdapter<'canvas'>,
-  mounted: MountedPixiRoot,
+  mounted: MountedCanvasRoot,
   opts?: RegisterRootOptions,
 ): RootInstance {
   const id = opts?.id ?? 'main';
@@ -120,7 +121,7 @@ export function registerPixiRoot(
     pausable,
     adapter,
     mounted,
-    stage: mounted.stage,
+    canvasRoot: mounted.substrate.root,
     binding: bindRoot(game, opts?.declaration, { surface: 'canvas', adapter }, mounted, pausable),
   });
   game.registerRoot(world);
@@ -129,13 +130,13 @@ export function registerPixiRoot(
 
 /**
  * Register a React world onto the Game shell — the DOM
- * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
+ * analog of {@link registerThreeRoot}/{@link registerCanvasRoot}. A react
  * world has no `frame` hooks (react's own
  * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
  * leaves a world with no `frame` untouched by its opaque-`update` fallback
  * too, since `MountedReactGame` declares no `update`). `adapter` is typed
  * as the real {@link ReactRootAdapter} shape (same reasoning as
- * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
+ * `registerCanvasRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
 export function registerReactRoot(
@@ -202,10 +203,10 @@ export interface ThreeRootMountSpec extends RootMountSpecBase {
 
 /**
  * `adapter` is the SEAM's `RootAdapter<'canvas'>` — a canvas root's mount
- * honestly returns only a `MountedPixiRoot`, and naming the real contract
+ * honestly returns a `MountedCanvasRoot`, and naming the real contract
  * here is what keeps the resolver cast-free.
  */
-export interface PixiRootMountSpec extends RootMountSpecBase {
+export interface CanvasRootMountSpec extends RootMountSpecBase {
   readonly kind: 'canvas';
   readonly adapter: RootAdapter<'canvas'>;
 }
@@ -234,7 +235,7 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
  * `kind`/`container` satisfy `MountedReactRoot` (`adapter/
  * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
  * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
- * `pixiStage()`'s "same instance the adapter mounted" contract); every
+ * `canvasRoot()`'s "same instance the adapter mounted" contract); every
  * `ReactRootAdapter` implementer echoes it back here so `mounted` alone
  * (with no separately-threaded `container`) satisfies the union
  * `RootInstanceInit.mounted`/`RootInstance.mounted` with zero cast.
@@ -259,14 +260,14 @@ export interface ReactRootAdapter extends RootAdapter<'dom'> {
   mount(host: DomHostContext): Promise<MountedReactGame>;
 }
 
-/** Same reasoning as {@link PixiRootMountSpec} above: the seam's
+/** Same reasoning as {@link CanvasRootMountSpec} above: the seam's
  *  `RootAdapter<'dom'>` is what a DOM root actually guarantees. */
 export interface ReactRootMountSpec extends RootMountSpecBase {
   readonly kind: 'dom';
   readonly adapter: RootAdapter<'dom'>;
 }
 
-export type RootMountSpec = ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec;
+export type RootMountSpec = ThreeRootMountSpec | CanvasRootMountSpec | ReactRootMountSpec;
 
 /**
  * Mount N adapter roots (three + canvas + react)
@@ -450,7 +451,7 @@ interface OneRootResult {
 
 /** Shared per-world mount inputs, computed once in `createRootsGameRuntime`'s
  *  loop (canvas stacking + one dpr) and threaded into whichever of
- *  `mountOneThreeRoot`/`mountOnePixiRoot` this world's `kind` needs — split
+ *  `mountOneThreeRoot`/`mountOneCanvasRoot` this world's `kind` needs — split
  *  out so the orchestrating loop itself stays a simple dispatch. */
 interface OneRootContext {
   readonly game: GameInternal;
@@ -469,7 +470,7 @@ interface OneRootContext {
 /** Mount one three `RootMountSpec` (canvas + renderer construction, per
  *  D5 §1/§4, then `registerThreeRoot`). Split out of
  *  `createRootsGameRuntime` purely to keep that function's own branching
- *  simple — see `mountOnePixiRoot` for the canvas sibling. */
+ *  simple — see `mountOneCanvasRoot` for the canvas sibling. */
 async function mountOneThreeRoot(
   spec: ThreeRootMountSpec,
   ctx: OneRootContext,
@@ -539,7 +540,7 @@ async function mountOneThreeRoot(
 }
 
 /** Mount one canvas `RootMountSpec` (via its own `CanvasHostContext`, per D5
- *  §1/§3/§4, then `registerPixiRoot`) — the pixi sibling of
+ *  §1/§3/§4, then `registerCanvasRoot`) — the canvas sibling of
  *  `mountOneThreeRoot` above.
  *
  *  Unlike `mountOneThreeRoot`, this needs no explicit `canvas.style.width`/
@@ -556,8 +557,8 @@ async function mountOneThreeRoot(
  *  already calls `session.resize()` unconditionally right after mount, so
  *  this never surfaces as a lasting bug the way three' buffer-only resize
  *  did (never self-healing, by design — see above). */
-async function mountOnePixiRoot(
-  spec: PixiRootMountSpec,
+async function mountOneCanvasRoot(
+  spec: CanvasRootMountSpec,
   ctx: Omit<OneRootContext, 'assets'>,
 ): Promise<OneRootResult> {
   const { game, canvas, w, h, dpr, headless, isBottom } = ctx;
@@ -572,7 +573,7 @@ async function mountOnePixiRoot(
     preserveDrawingBuffer: true,
   };
   const mounted = await spec.adapter.mount(pixiHost);
-  registerPixiRoot(game, spec.adapter, mounted, {
+  registerCanvasRoot(game, spec.adapter, mounted, {
     id: spec.id,
     pausable: spec.pausable,
     declaration: spec.declaration,
@@ -596,7 +597,7 @@ async function mountOnePixiRoot(
 
 /**
  * Mount one React `RootMountSpec` — the DOM sibling of
- * `mountOneThreeRoot`/`mountOnePixiRoot`. Unlike its canvas-backed siblings
+ * `mountOneThreeRoot`/`mountOneCanvasRoot`. Unlike its canvas-backed siblings
  * this returns NO `routerEntry`: a react world's DOM-root layer participates in
  * D5's z-order/box stacking (the caller still creates and positions its `<div>`
  * exactly like a canvas — see `createRootsGameRuntime`'s stack-building loop)
@@ -655,7 +656,7 @@ async function mountOneReactRoot(
  * canvas for three/canvas, a DOM-root `<div>` layer for react — stacked
  * per D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
- * via `registerThreeRoot`/`registerPixiRoot`/`registerReactRoot` — the
+ * via `registerThreeRoot`/`registerCanvasRoot`/`registerReactRoot` — the
  * SAME wiring `test/create-runtime-worlds.test.ts` proves for the
  * three/canvas pair. Worlds MOUNT in `roots` ARRAY order ("manifest
  * declaration order" — the frame/registration axis), independent of
@@ -720,14 +721,14 @@ interface MountAllRootsResult {
  * Mount + register every world spec, in ARRAY (declaration) order — split
  * out of `createRootsGameRuntime` purely to keep that function's own
  * cyclomatic complexity down (E4, same reason `mountOneThreeRoot`/
- * `mountOnePixiRoot` are already split out). React roots contribute NO
+ * `mountOneCanvasRoot` are already split out). React roots contribute NO
  * router entry ("DOM layers need no entry in the router's hit-test loop"):
  * their layer's own `pointer-events` discipline handles claim/fall-through
  * natively, with zero router involvement (see `mountOneReactRoot`'s doc
  * comment).
  */
 async function mountAllRootSpecs(
-  mountSpecs: (ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec)[],
+  mountSpecs: (ThreeRootMountSpec | CanvasRootMountSpec | ReactRootMountSpec)[],
   bottomId: string | undefined,
   inputs: MountAllRootsInputs,
 ): Promise<MountAllRootsResult> {
@@ -751,7 +752,7 @@ async function mountAllRootSpecs(
       if (spec.kind === 'three') {
         ({ mountedEntry, routerEntry } = await mountOneThreeRoot(spec, oneCtx));
       } else if (spec.kind === 'canvas') {
-        ({ mountedEntry, routerEntry } = await mountOnePixiRoot(spec, oneCtx));
+        ({ mountedEntry, routerEntry } = await mountOneCanvasRoot(spec, oneCtx));
       } else {
         // Exhaustiveness guard (§7.4-2): 'react' was already handled by the
         // early `continue` above, so only a hypothetical 4th `AdapterSurface` can
@@ -876,7 +877,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   if (specs.length === 0) {
     throw new Error('createGameRuntime: `roots` must contain at least one root.');
   }
-  const mountSpecs = specs as (ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec)[];
+  const mountSpecs = specs as (ThreeRootMountSpec | CanvasRootMountSpec | ReactRootMountSpec)[];
 
   const w = Math.max(
     1,
@@ -992,7 +993,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   // --- Mount + register every world, in ARRAY (declaration) order. ---
   // Split out into its own top-level function purely to keep
   // `createRootsGameRuntime`'s own cyclomatic complexity down (E4) — same
-  // reason `mountOneThreeRoot`/`mountOnePixiRoot` are already split out
+  // reason `mountOneThreeRoot`/`mountOneCanvasRoot` are already split out
   // below.
   let mounted: MountAllRootsResult;
   try {

package/src/runtime/game.ts

@@ -5,11 +5,6 @@
  * RootInstance retains its own mounted surface and optional capabilities.
  */
 
-// TYPE-ONLY pixi import: `game.ts` must never value-import
-// `pixi.js` — a value import would pull the Pixi runtime into 3D-only
-// bundles that never touch a canvas root. Every pixi-typed field below is erased
-// at compile time; nothing here constructs or calls into Pixi.
-import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import type { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
 import type { RootBinding } from '../adapter/binding';
@@ -180,21 +175,20 @@ export interface RootInstance {
    *  gain — see `AdapterHandle` below. */
   readonly adapter: AdapterHandle;
   /** The live mounted surface — one of `MountedRoot`'s kind-tagged shapes
-   *  (T7.5; `MountedThreeRoot` for a three world, `MountedPixiRoot` for
+   *  (T7.5; `MountedThreeRoot` for a three world, `MountedCanvasRoot` for
    *  canvas, `MountedReactRoot` for react). */
   readonly mounted: MountedRoot;
   /** Kind-narrowed accessor: throws a descriptive error when this world is
    *  not a three world. */
   threeScene(): THREE.Scene;
-  /** Kind-narrowed accessor for canvas roots (T7.3): returns the stage
-   *  passed to `createRootInstance` for a `'canvas'`-kind world. Throws
-   *  descriptively for a non-pixijs world, or a canvas world built without
-   *  a `stage` (see `RootInstanceInit.stage`). */
-  pixiStage(): PIXI.Container;
+  /** Kind-narrowed accessor for canvas roots: returns the native substrate
+   * root the adapter mounted. The host keeps it opaque; a substrate adapter
+   * that declared the matching name narrows `T`. */
+  canvasRoot<T = unknown>(): T;
   /** Kind-narrowed accessor for DOM roots: returns the
    *  DOM-root layer `<div>` the host mounted this world's react tree into
    *  (the SAME element passed as `container` to `createRootInstance` —
-   *  identity matters, mirroring `threeScene()`/`pixiStage()`'s "same
+   *  identity matters, mirroring `threeScene()`/`canvasRoot()`'s "same
    *  instance the adapter mounted" contract). Throws descriptively for a
    *  non-react world, or a react world built without a `container` (see
    *  `RootInstanceInit.container`). */
@@ -275,9 +269,9 @@ export interface RootInstanceInit {
   readonly mounted: MountedRoot;
   /** Required when `kind === 'three'` — backs `threeScene()`. */
   readonly scene?: THREE.Scene | undefined;
-  /** Required when `kind === 'canvas'` — backs `pixiStage()` (T7.3 slice 2,
-   *  symmetric with `scene` for three above). */
-  readonly stage?: PIXI.Container | undefined;
+  /** Required when `kind === 'canvas'` — backs `canvasRoot()`, symmetric with
+   * `scene` for three above. */
+  readonly canvasRoot?: unknown;
   /** Required when `kind === 'dom'` — backs `reactRoot()` (T6.2 slice 1,
    *  symmetric with `scene`/`stage` above): the DOM-root layer `<div>` this
    *  world's react tree is mounted into. */
@@ -295,7 +289,7 @@ export interface RootInstanceInit {
 /**
  * Build a `RootInstance` whose kind-narrowed accessors throw descriptively
  * on kind mismatch. This is the one place that builds
- * `threeScene`/`pixiStage`, so every world (however it's constructed, in this
+ * `threeScene`/`canvasRoot`, so every world (however it's constructed, in this
  * slice or later ones) gets identical throw behavior.
  */
 export function createRootInstance(init: RootInstanceInit): RootInstance {
@@ -306,7 +300,7 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
     adapter,
     mounted,
     scene,
-    stage,
+    canvasRoot,
     container,
     physics,
     collisions,
@@ -327,13 +321,13 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
     );
   }
 
-  // Symmetric check for canvas (T7.3 slice 2) — a canvas world with no stage
-  // has nothing for `pixiStage()` to return; fail loudly here, at
+  // Symmetric check for canvas — a canvas world with no native substrate root
+  // has nothing for `canvasRoot()` to return; fail loudly here, at
   // construction, same as the three/scene check above.
-  if (kind === 'canvas' && !stage) {
+  if (kind === 'canvas' && (canvasRoot === undefined || canvasRoot === null)) {
     throw new Error(
-      `RootInstance "${id}" (kind: canvas): a canvas world requires a stage — ` +
-        'pass `stage` in RootInstanceInit.',
+      `RootInstance "${id}" (kind: canvas): a canvas world requires a native substrate root — ` +
+        'pass `canvasRoot` in RootInstanceInit.',
     );
   }
 
@@ -405,23 +399,20 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
       }
       return scene;
     },
-    pixiStage(): PIXI.Container {
-      // The `!stage` branch a canvas world could hit here is now unreachable
-      // (T7.3 slice 2): construction above throws for `kind === 'canvas'`
-      // with no `stage`, symmetric with `threeScene()`'s `scene` guard.
-      if (kind !== 'canvas' || !stage) {
+    canvasRoot<T = unknown>(): T {
+      if (kind !== 'canvas' || canvasRoot === undefined || canvasRoot === null) {
         throw new Error(
-          `RootInstance "${id}" (kind: ${kind}): pixiStage() requested but this world is not ` +
+          `RootInstance "${id}" (kind: ${kind}): canvasRoot() requested but this world is not ` +
             'a canvas world',
         );
       }
-      return stage;
+      return canvasRoot as T;
     },
     reactRoot(): HTMLElement {
       // The `!container` branch a react world could hit here is now
       // unreachable (T6.2 slice 1): construction above throws for
       // `kind === 'dom'` with no `container`, symmetric with
-      // `threeScene()`/`pixiStage()`'s guards.
+      // `threeScene()`/`canvasRoot()`'s guards.
       if (kind !== 'dom' || !container) {
         throw new Error(
           `RootInstance "${id}" (kind: ${kind}): reactRoot() requested but this world is not ` +

package/src/runtime/render-control.ts

@@ -469,7 +469,12 @@ function countRoots(game: Game): PerfRootCount[] {
     if (world.kind === 'three') {
       counts.push({ id: world.id, kind: world.kind, ...countRootGraph(world.threeScene()) });
     } else if (world.kind === 'canvas') {
-      counts.push({ id: world.id, kind: world.kind, ...countRootGraph(world.pixiStage()) });
+      // Node counting is a substrate projection, not a surface fact. Pixi's
+      // native tree exposes `children`; other canvas substrates are omitted
+      // until their adapter declares an honest counter.
+      if (world.mounted.kind === 'canvas' && world.mounted.substrate.name === 'pixi') {
+        counts.push({ id: world.id, kind: world.kind, ...countRootGraph(world.canvasRoot()) });
+      }
     }
   }
   return counts;