@vgai/engine 0.5.15 → 0.5.17

package/src/animation/xstate-animation-binding.ts

@@ -4,7 +4,10 @@ import type { createSystemRunner } from '../core/system-runner';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
-import { attachAnimationRuntimeInspection } from './runtime-inspection';
+import {
+  type AnimationPreviewTransport,
+  attachAnimationRuntimeInspection,
+} from './runtime-inspection';
 import {
   type AnimationBoneMask,
   type AnimationMetaStateNodeLike,
@@ -109,6 +112,12 @@ export interface XStateAnimationBindingOptions {
    * omitted, the caller owns ticking (useful for standalone Three tests).
    */
   systems?: Pick<ReturnType<typeof createSystemRunner>, 'add' | 'remove'>;
+  /**
+   * Publish a seekable transport for an isolated design-time mount such as a
+   * CSF story. Never enable this on the live game binding: runtime inspection
+   * stays read-only there, while the story deliberately owns this preview.
+   */
+  previewTransport?: boolean;
 }
 
 export interface XStateAnimationLayerState {
@@ -368,6 +377,89 @@ export function bindXStateAnimation(
   const activeLayers = new Map<string, ActiveState>();
   let disposed = false;
   let detachRuntimeInspection = () => {};
+  let previewClip: string | null = null;
+  let previewAction: THREE.AnimationAction | null = null;
+  let previewPlaying = true;
+  let previewLoop = true;
+  let previewSpeed = 1;
+
+  function controllerPreviewSubject(): {
+    clip: string;
+    action: THREE.AnimationAction | null;
+  } {
+    const layers = [activeLayers.get('base'), ...activeLayers.values()].filter(
+      (active, index, all): active is ActiveState =>
+        Boolean(active) && all.indexOf(active) === index,
+    );
+    for (const active of layers) {
+      const weighted = [...active.natural].sort((left, right) => {
+        const leftWeight = actionCache.get(left.actionKey)?.action.getEffectiveWeight() ?? 0;
+        const rightWeight = actionCache.get(right.actionKey)?.action.getEffectiveWeight() ?? 0;
+        return rightWeight - leftWeight;
+      })[0];
+      if (weighted) {
+        return {
+          clip: weighted.clip,
+          action: actionCache.get(weighted.actionKey)?.action ?? null,
+        };
+      }
+    }
+    return { clip: clips.keys().next().value ?? '', action: null };
+  }
+
+  function actionIsControllerOwned(action: THREE.AnimationAction): boolean {
+    for (const cached of actionCache.values()) {
+      if (cached.action === action) return true;
+    }
+    return false;
+  }
+
+  function releasePreviewAction(): void {
+    const action = previewAction;
+    if (!action) return;
+    action.stop();
+    if (!actionIsControllerOwned(action)) {
+      mixer.uncacheAction(action.getClip(), action.getRoot());
+    }
+    previewAction = null;
+  }
+
+  function enterClipPreview(name: string): void {
+    const clip = clips.get(name);
+    if (!clip) return;
+    releasePreviewAction();
+    previewClip = name;
+    for (const cached of actionCache.values()) cached.action.setEffectiveWeight(0);
+    const action = mixer.clipAction(clip).reset().play();
+    action.setEffectiveWeight(1);
+    action.setEffectiveTimeScale(1);
+    action.setLoop(previewLoop ? THREE.LoopRepeat : THREE.LoopOnce, previewLoop ? Infinity : 1);
+    action.clampWhenFinished = !previewLoop;
+    previewAction = action;
+    mixer.update(0);
+  }
+
+  function restoreControllerPreview(): void {
+    releasePreviewAction();
+    previewClip = null;
+    const snapshot = actor.getSnapshot();
+    reconcile(snapshot);
+    const context = snapshot.context;
+    for (const cached of actionCache.values()) cached.action.setEffectiveWeight(0);
+    for (const active of activeLayers.values()) {
+      active.crossfadeRemaining = 0;
+      active.natural = weightsOf(active.stateId, active.meta, context);
+      const loop = isBlendTreeAnimationMeta(active.meta) ? true : active.meta.loop;
+      const speed = isBlendTreeAnimationMeta(active.meta) ? 1 : active.meta.speed;
+      const layerWeight = layerWeightOf(active.meta);
+      for (const weighted of active.natural) {
+        ensureAction(weighted.actionKey, loop, speed, layerWeight)
+          .play()
+          .setEffectiveWeight(weighted.weight * layerWeight);
+      }
+    }
+    mixer.update(0);
+  }
 
   function silence(weights: WeightedClip[], except: string | undefined, duration: number): void {
     for (const weighted of weights) {
@@ -465,23 +557,76 @@ export function bindXStateAnimation(
   const initialSnapshot = actor.getSnapshot();
   reconcile(initialSnapshot);
   const subscription = actor.subscribe((snapshot) => {
-    if (!disposed) reconcile(snapshot);
+    // Isolated clip review deliberately holds behavior output. The actor may
+    // keep receiving story args, but its latest state is reconciled only when
+    // the user returns to Controller.
+    if (!disposed && !previewClip) reconcile(snapshot);
   });
 
   function tick(dt: number): void {
     if (disposed) return;
+    if (options.previewTransport && !previewPlaying) return;
+    const elapsed = dt * (options.previewTransport ? previewSpeed : 1);
+    if (options.previewTransport && previewClip && previewAction) {
+      mixer.update(elapsed);
+      const clip = clips.get(previewClip);
+      if (!previewLoop && clip && previewAction.time >= clip.duration) previewPlaying = false;
+      return;
+    }
     const context = actor.getSnapshot().context;
     for (const active of activeLayers.values()) {
       if (active.crossfadeRemaining > 0) {
-        active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - dt);
+        active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - elapsed);
         if (active.crossfadeRemaining <= 0) applyLiveBlendWeights(active, context);
       } else {
         applyLiveBlendWeights(active, context);
       }
     }
-    mixer.update(dt);
+    mixer.update(elapsed);
   }
 
+  const previewTransport: AnimationPreviewTransport | undefined = options.previewTransport
+    ? {
+        getSnapshot: () => {
+          const controller = controllerPreviewSubject();
+          return {
+            clip: previewClip ?? controller.clip,
+            time: previewClip ? (previewAction?.time ?? 0) : (controller.action?.time ?? 0),
+            playing: previewPlaying,
+            loop: previewLoop,
+            speed: previewSpeed,
+            mode: previewClip ? 'clip' : 'controller',
+          };
+        },
+        setPlaying(playing) {
+          previewPlaying = playing;
+        },
+        setLoop(loop) {
+          previewLoop = loop;
+          if (!previewClip) enterClipPreview(controllerPreviewSubject().clip);
+          previewAction?.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
+          if (previewAction) previewAction.clampWhenFinished = !loop;
+        },
+        setSpeed(speed) {
+          previewSpeed = THREE.MathUtils.clamp(speed, 0.05, 4);
+        },
+        seek(time) {
+          if (!previewClip) enterClipPreview(controllerPreviewSubject().clip);
+          const clip = previewClip ? clips.get(previewClip) : undefined;
+          if (!clip || !previewAction) return;
+          previewAction.time = THREE.MathUtils.clamp(time, 0, Math.max(clip.duration, 0));
+          mixer.update(0);
+        },
+        setClip(name) {
+          if (name === null) {
+            if (previewClip) restoreControllerPreview();
+            return;
+          }
+          enterClipPreview(name);
+        },
+      }
+    : undefined;
+
   const binding: XStateAnimationBinding = {
     tick,
     actor,
@@ -503,6 +648,7 @@ export function bindXStateAnimation(
       if (disposed) return;
       disposed = true;
       detachRuntimeInspection();
+      releasePreviewAction();
       options.systems?.remove('animation', tick);
       subscription.unsubscribe();
       for (const { action, clip } of actionCache.values()) {
@@ -520,6 +666,7 @@ export function bindXStateAnimation(
   detachRuntimeInspection = attachAnimationRuntimeInspection(owner, {
     mixer,
     clips,
+    ...(previewTransport ? { previewTransport } : {}),
     getSnapshot: () => ({
       layers: [...activeLayers.values()].map((active) => {
         const parameters = readParameters(actor.getSnapshot().context);

package/src/canvas-react/engine-bridge.ts

@@ -14,20 +14,20 @@
  */
 
 import { createContext, useContext } from 'react';
-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 const EngineBridge = createContext<EngineBridgeValue | null>(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:
  *
@@ -36,7 +36,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(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} />;
  * }
@@ -46,7 +46,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
  * `null` would surface as a mystery `undefined` deep in a tick callback.
  */
-export function useGameContext(): GameContext {
+export function useGameContext(): CanvasGameContext {
   const bridge = useContext(EngineBridge);
   if (!bridge?.ctx) {
     throw new Error(

package/src/canvas-react/index.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.
@@ -43,6 +43,7 @@ export {
 } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
 export {
+  type CanvasGameContext,
   type CanvasRootContextOptions,
   type CanvasRootRuntime,
   createCanvasRootContext,

package/src/canvas-react/pixi-react-adapter.tsx

@@ -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).
@@ -38,9 +38,11 @@
 import { createRoot, extend } from '@pixi/react';
 import type { Application, ApplicationOptions } from 'pixi.js';
 import * as PIXI from 'pixi.js';
-import { createElement, type ReactNode, useLayoutEffect } from 'react';
+import { createElement, Fragment, type ReactNode, useEffect, useLayoutEffect } from 'react';
 import type { CanvasHostContext, MountedPixiRoot, RootAdapter } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
 import { WorldProvider } from '../react/world-state';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
 import { createCanvasRootContext } from './world-context';
 
@@ -77,6 +79,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
@@ -98,21 +106,21 @@ export interface CreatePixiReactAdapterOptions {
 export function createPixiReactAdapter(
   options: CreatePixiReactAdapterOptions,
 ): RootAdapter<'canvas'> {
-  const { id, content, inputMapPath, applicationOptions } = options;
+  const { id, content, inputMapPath, engineRuntime = true, applicationOptions } = options;
 
   return {
     id,
 
     async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
-      const runtime = createCanvasRootContext(host, { id, inputMapPath });
-      const bridge: EngineBridgeValue = { ctx: runtime.ctx };
+      const runtime = engineRuntime ? createCanvasRootContext(host, { id, inputMapPath }) : null;
+      const bridge: EngineBridgeValue | null = 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 ' +
@@ -129,6 +137,10 @@ export function createPixiReactAdapter(
       const committed = new Promise<void>((resolve) => {
         resolveCommitted = resolve;
       });
+      let resolveEffectsReady!: () => void;
+      const effectsReady = new Promise<void>((resolve) => {
+        resolveEffectsReady = resolve;
+      });
       let resolveUnmounted!: () => void;
       const unmounted = new Promise<void>((resolve) => {
         resolveUnmounted = resolve;
@@ -152,22 +164,39 @@ export function createPixiReactAdapter(
           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: PixiReactRoot = createRoot(canvas);
 
@@ -189,50 +218,74 @@ export function createPixiReactAdapter(
         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: Application = await root.render(element, initOptions);
-      runtime.setApplication(app);
+      // 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!: (why: string) => void;
+      const reconcileFailure = new Promise<string>((resolve) => {
+        reportReconcileFailure = resolve;
+      });
+      const onError = (event: ErrorEvent): void => {
+        reportReconcileFailure(
+          `the Pixi tree crashed before its first commit — ${event.message} ` +
+            '(mount() fails loudly instead of hanging)',
+        );
+      };
+      globalThis.addEventListener?.('error', onError);
+
+      let app: Application | undefined;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      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 — without this
-      // guard `mount()` would await `committed` forever. Convert that class of
-      // failure into a loud mount error.
-      await new Promise<void>((resolve, reject) => {
-        const fail = (why: string) => {
-          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: ErrorEvent) =>
-          fail(
-            `the Pixi tree crashed before its first commit — ${event.message} ` +
-              '(mount() fails loudly instead of hanging)',
+        // 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<string>((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 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();
         });
-      });
+        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
@@ -240,39 +293,53 @@ export function createPixiReactAdapter(
       // 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: 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: number): void {
           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: number, height: number): void {
           if (disposed) return;
           // `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(): void {
           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 as unknown as HTMLElement);
           // 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
@@ -281,8 +348,7 @@ export function createPixiReactAdapter(
           // 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/src/canvas-react/pixi-react-root-factory.tsx

@@ -66,6 +66,10 @@ export function resolveCanvasEntryAdapter(
     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;