@vgai/engine 0.5.21 → 0.5.22

package/src/world3d-react/rapier-physics-bridge.tsx

@@ -40,18 +40,20 @@
  * is how a `SystemAdapters` member says "not supported".
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
- * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
- * on the R3F root it is mounted in. It allocates nothing else — no timers, no
- * subscriptions, no per-frame work (see the phase note below), and no Rapier
- * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the
- * colliders instrument, the editor's transform coordination. They read; they
- * never dispose.
- * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
- * set (`registerSystemAdapter('physics', undefined)`, which
- * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
- * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
- * bridges in one root would fight over that one key; mount exactly one.
+ * OWNER: this component owns one physics ADAPTER, published onto the ONE
+ * module-scoped slot `rapierPhysicsSystem()` forwards to (GAME-GLOBAL — the
+ * entry's static `systems.physics` declaration cannot be per-root). It allocates nothing
+ * else — no timers, no subscriptions, no per-frame work (see the phase note
+ * below), and no Rapier objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the colliders
+ * instrument, the editor's transform coordination. They read; they never
+ * dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
+ * and the slot it set (identity-guarded), so a play stop/start, a hot
+ * restart, or a world that unmounts `<Physics>` leaves no stale adapter
+ * behind. Because the slot is game-global, mount exactly ONE bridge per
+ * GAME: with two, the later mount wins the slot and the later unmount clears
+ * it while the earlier bridge is still live.
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
@@ -73,7 +75,6 @@ import type {
   PhysicsJointSnapshot,
   PhysicsJointType,
 } from '../adapter/system-adapter';
-import { useGameContext } from './engine-bridge';
 
 export interface RapierPhysicsBridgeProps {
   /**
@@ -123,47 +124,29 @@ function owningBody(
  * `useRapier()`). Renders nothing.
  */
 export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps): null {
-  const ctx = useGameContext();
+  // This bridge publishes the module slot below, which the entry's
+  // `systems.physics` declaration (`rapierPhysicsSystem()`) forwards to —
+  // that declaration is the ONE path the host reads this world's physics
+  // through.
   const { colliderStates, rapier, rigidBodyStates, world } = useRapier();
-  const registerSystemAdapter = ctx.registerSystemAdapter;
 
   useEffect(() => {
-    if (!registerSystemAdapter) return;
-
     /**
-     * node id → the Rapier body driving it, in two hops the library and the
-     * engine each already own:
-     *
-     *  1. id → `Object3D`, through the live scene index — `userData.entityId`
-     *     is this stack's identity convention (the editor's R3F authoring
-     *     adapter stamps it; `../adapter/setup-three-root-adapter.ts` resolves
-     *     the same way for the imperative root).
-     *  2. `Object3D` → body, through `rigidBodyStates` — the library's OWN
-     *     body↔object map, carried on the `RapierContext` `useRapier()`
-     *     returns. Walking ANCESTORS matters: `<RigidBody>` owns a subtree, so
-     *     the selected mesh is usually a descendant of the object the state
-     *     names.
+     * node id → the Rapier body driving it, entirely through the library's
+     * OWN body↔object map (`rigidBodyStates`, carried on the `RapierContext`
+     * `useRapier()` returns): resolve `userData.entityId` — this stack's
+     * identity convention, stamped by the editor's R3F authoring adapter —
+     * inside the body-owned subtrees, then walk ANCESTORS to the owning body
+     * (`<RigidBody>` owns a subtree, so the selected mesh is usually a
+     * descendant of the object the state names).
      *
-     * Both maps are live, so this is computed per call rather than cached —
+     * The map is live, so this is computed per call rather than cached —
      * calls arrive at gesture rate (a gizmo drag start/end, a dev command),
-     * never per frame. `ctx.sceneIndex` is read AT CALL TIME, never captured:
-     * the R3F root backfills it once fiber resolves the scene, which can land
-     * after this component's first effect (`world-context.ts`'s
-     * `setSceneCamera`), so a destructured copy would be permanently absent.
+     * never per frame, and only objects under a `<RigidBody>` can have a body
+     * at all, so the body subtrees are the complete search space.
      */
     const bodyFor = (nodeId: string): RapierEditableBody | undefined => {
-      const indexed = ctx.sceneIndex?.byEntityId(nodeId);
-      const object = indexed ?? lateEntityObject(rigidBodyStates.values(), nodeId);
-      if (!indexed && object) {
-        // The editor assigns its stable authoring entity ids AFTER Fiber's
-        // first commit, while the root's SceneIndex is constructed during
-        // that commit. Resolve the one late id inside the library-owned body
-        // subtrees and immediately reindex it; subsequent gestures take the
-        // normal indexed path. This is the SceneIndex's documented escape
-        // hatch for a userData id written after construction, not a parallel
-        // scene mirror.
-        ctx.sceneIndex?.reindex(object);
-      }
+      const object = lateEntityObject(rigidBodyStates.values(), nodeId);
       if (!object) return undefined;
       return owningBody(object, rigidBodyStates.values());
     };
@@ -367,9 +350,65 @@ export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps)
       joints,
       previewJointAnchor,
     };
-    registerSystemAdapter('physics', adapter);
-    return () => registerSystemAdapter('physics', undefined);
-  }, [colliderStates, ctx, onDebugChange, rapier, registerSystemAdapter, rigidBodyStates, world]);
+    liveAdapter = adapter;
+    return () => {
+      if (liveAdapter === adapter) liveAdapter = null;
+    };
+  }, [colliderStates, onDebugChange, rapier, rigidBodyStates, world]);
 
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// The entry-declaration half
+// ---------------------------------------------------------------------------
+
+/** The mounted bridge's adapter, while one is live. Module-scoped on purpose:
+ *  the entry's `systems` declaration is static, the rapier world is not, and
+ *  this slot is the seam between the two. */
+let liveAdapter: PhysicsAdapter | null = null;
+
+function requireLiveAdapter(): PhysicsAdapter {
+  if (!liveAdapter) {
+    throw new Error(
+      'rapierPhysicsSystem: no <RapierPhysicsBridge> is mounted inside a live <Physics> right ' +
+        'now — the world is not playing, or the scene never mounted the bridge.',
+    );
+  }
+  return liveAdapter;
+}
+
+/**
+ * The `systems.physics` slot for a default-exported world — declare it from
+ * the entry (`export const systems = { physics: rapierPhysicsSystem() }`) and
+ * keep `<RapierPhysicsBridge />` mounted inside `<Physics>`. Every call
+ * forwards to the LIVE bridge adapter, so the static declaration answers with
+ * the running world's physics; while none is mounted, every call refuses by
+ * name rather than fabricating.
+ */
+export function rapierPhysicsSystem(): PhysicsAdapter {
+  // Every forward REQUIRES the live adapter and its member — a silent no-op
+  // or fabricated empty answer is the shape the anti-shim rule forbids. The
+  // bridge's adapter always carries all five optional members, so the member
+  // checks only ever fire against a foreign replacement.
+  const requireMember = <K extends keyof PhysicsAdapter>(member: K) => {
+    const adapter = requireLiveAdapter();
+    const value = adapter[member];
+    if (typeof value !== 'function') {
+      throw new Error(`rapierPhysicsSystem: the live physics adapter has no ${String(member)}().`);
+    }
+    return value.bind(adapter) as NonNullable<PhysicsAdapter[K]>;
+  };
+  return {
+    ownerOf: (nodeId) => requireLiveAdapter().ownerOf(nodeId),
+    freeze: (nodeId) => requireLiveAdapter().freeze(nodeId),
+    commit: (nodeId, t) => requireLiveAdapter().commit(nodeId, t),
+    unfreeze: (nodeId) => requireLiveAdapter().unfreeze(nodeId),
+    setDebugDrawEnabled: (enabled) => requireMember('setDebugDrawEnabled')(enabled),
+    colliders: (nodeId) => requireMember('colliders')(nodeId),
+    previewCollider: (colliderId, shape) => requireMember('previewCollider')(colliderId, shape),
+    joints: (nodeId) => requireMember('joints')(nodeId),
+    previewJointAnchor: (jointId, endpoint, anchor) =>
+      requireMember('previewJointAnchor')(jointId, endpoint, anchor),
+  };
+}

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

@@ -1,59 +0,0 @@
-/**
- * `@engine/canvas-react` — the React context that carries a canvas world's
- * engine runtime into its `@pixi/react` tree: the world's `GameContext`, read
- * with {@link useGameContext}.
- *
- * The bridge value is built by `createPixiReactAdapter`'s `mount()`
- * (./pixi-react-adapter.tsx), whose `update(dt)` runs this world's phases under
- * the HOST loop — so registered systems tick in engine phase order, pause
- * included (no update while the world is frozen).
- *
- * Behavior in a canvas world is components + hooks: `useGameContext` reaches
- * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
- * `useApplication` is the door to the live `Application`.
- */
-
-import { createContext, useContext } from 'react';
-import type { CanvasGameContext } from './world-context';
-
-export interface EngineBridgeValue {
-  /** 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?: CanvasGameContext | undefined;
-}
-
-export const EngineBridge = createContext<EngineBridgeValue | null>(null);
-
-/**
- * This canvas root's `CanvasGameContext`, for use inside any component in the tree.
- *
- * An ordinary component does what a model would write:
- *
- * ```tsx
- * function Player({ speed = 220 }) {
- *   const { input } = useGameContext();
- *   const ref = useRef<Sprite>(null);
- *   useTick(({ deltaMS }) => {
- *     if (input?.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
- *   });
- *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
- * }
- * ```
- *
- * Throws when called outside a canvas root mounted by
- * `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(): CanvasGameContext {
-  const bridge = useContext(EngineBridge);
-  if (!bridge?.ctx) {
-    throw new Error(
-      'useGameContext(): no engine root context. This hook only works inside a canvas ' +
-        'root mounted by createPixiReactAdapter (@engine/canvas-react) — check that the ' +
-        'component is rendered inside your world entry, not in a standalone <Application>.',
-    );
-  }
-  return bridge.ctx;
-}

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

@@ -1,356 +0,0 @@
-/**
- * `createPixiReactAdapter` — wraps a `@pixi/react` tree as a first-party
- * `RootAdapter<'canvas'>` so a Pixi world mounts as an ordinary
- * `surface: "canvas"` root: the engine hands `mount()` a `CanvasHostContext`
- * (its own canvas + size + compositing hints, per `../adapter/host-context.ts`);
- * 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 sibling of `world3d-react`'s
- * `createR3FAdapter`, with `@pixi/react` where that one has
- * 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 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).
- *
- * ## Component catalogue
- *
- * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
- * that starts EMPTY — the first intrinsic in an un-extended tree throws
- * "X is not part of the PIXI namespace! Did you forget to extend?". This
- * module extends it with the whole `pixi.js` namespace once per mount
- * (idempotent `Object.assign`), the same thing `createR3FAdapter` does with
- * `extend(host.three)`. A world that adds its own classes (`@pixi/tilemap`,
- * a custom `Container` subclass) calls `extend`/`useExtend` itself.
- */
-
-import { createRoot, extend } from '@pixi/react';
-import type { Application, ApplicationOptions } from 'pixi.js';
-import * as PIXI from 'pixi.js';
-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';
-
-/** How long `mount()` waits for the tree's first commit before failing loudly
- *  rather than hanging (and wedging every root declared after this one, since
- *  roots mount sequentially). */
-const FIRST_COMMIT_TIMEOUT_MS = 10_000;
-
-/**
- * `@pixi/react` keys its reconciler roots off the canvas element in a
- * module-global map, and its own unmount path (which would clear that key) is
- * not exported. So a canvas this lane has already mounted must never be handed
- * to a second mount: `createRoot` would silently hand back the FIRST root,
- * whose `Application` this lane already destroyed. Every host in this repo
- * builds a fresh canvas per mount, so this only ever fires on a genuine bug —
- * and it fires as a named error rather than as a dead world.
- */
-const MOUNTED_CANVASES = new WeakSet<HTMLCanvasElement>();
-
-/** `@pixi/react`'s reconciler-root handle. Its `Root` type is internal (the
- *  package exports the FUNCTION, not the type), so name it off the function. */
-type PixiReactRoot = ReturnType<typeof createRoot>;
-
-/** What {@link createPixiReactAdapter} needs to build one `RootAdapter<'canvas'>`. */
-export interface CreatePixiReactAdapterOptions {
-  /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
-  readonly id: string;
-  /** The Pixi tree to mount — `useTick` hooks, `useApplication`, Pixi filters
-   *  and any extended component all work unchanged. */
-  readonly content: ReactNode;
-  /** Input map loaded through the game-owned `Game.loadInputMap` (load-once
-   *  across roots). Defaults to the conventional
-   *  `/inputmaps/default.inputmap.json`; `null` opts out (a world with no
-   *  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
-   * (`autoStart`, `sharedTicker`) and the ones the host owns (size, dpr,
-   * transparency, `preserveDrawingBuffer`) are applied after this and cannot
-   * be overridden: a world that starts its own ticker or clears an opaque
-   * background under a stacked sibling breaks the host's contract, not just
-   * its own frame.
-   */
-  readonly applicationOptions?: Partial<ApplicationOptions> | undefined;
-}
-
-/**
- * Build a `RootAdapter<'canvas'>` that mounts `options.content` through
- * `@pixi/react`, gated entirely by the host's own loop and rendering into the
- * host's own canvas — never a second canvas, never a second
- * `requestAnimationFrame` loop.
- */
-export function createPixiReactAdapter(
-  options: CreatePixiReactAdapterOptions,
-): RootAdapter<'canvas'> {
-  const { id, content, inputMapPath, engineRuntime = true, applicationOptions } = options;
-
-  return {
-    id,
-
-    async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
-      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;
-
-      const canvas = host.canvas;
-      if (MOUNTED_CANVASES.has(canvas)) {
-        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 ' +
-            'canvas (every vgai host already does).',
-        );
-      }
-      MOUNTED_CANVASES.add(canvas);
-
-      // The catalogue is module-global and starts empty; this is idempotent.
-      extend(PIXI as unknown as Parameters<typeof extend>[0]);
-
-      let resolveCommitted!: () => void;
-      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;
-      });
-      /**
-       * Signals the tree's FIRST COMMIT and its LAST. A layout effect,
-       * deliberately, and rendered as the LAST child, deliberately:
-       *
-       *  - mount: layout effects run synchronously inside the commit, before
-       *    any passive effect and before any tick can be scheduled;
-       *  - unmount: React commits deletion effects in tree order, each node
-       *    before its own children, so the LAST sibling's cleanup is the last
-       *    to run. That is what makes this a reliable "every component has
-       *    finished tearing down" signal — and it is load-bearing, because
-       *    `useTick`'s own cleanup calls `ticker.remove()`. Destroying the
-       *    Application before that cleanup lands throws inside React's commit
-       *    on every teardown of any world with a tick hook.
-       */
-      function Lifecycle(): null {
-        useLayoutEffect(() => {
-          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;
-      }
-
-      // 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.
-      //
-      // 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);
-
-      // The host owns size, dpr, transparency and capture cost; the loop
-      // contract owns `autoStart`/`sharedTicker`. Both are applied AFTER the
-      // caller's own options so neither can be overridden from a world file.
-      const initOptions: Partial<ApplicationOptions> = {
-        antialias: true,
-        ...applicationOptions,
-        width: host.width,
-        height: host.height,
-        resolution: host.dpr ?? globalThis.devicePixelRatio ?? 1,
-        autoDensity: true,
-        // Stacked ABOVE a sibling root -> clear with alpha 0 so the layer below
-        // shows through (COMPOSITION-DESIGN D5 §1).
-        backgroundAlpha: host.transparent ? 0 : 1,
-        preserveDrawingBuffer: host.preserveDrawingBuffer ?? false,
-        autoStart: false,
-        sharedTicker: false,
-      };
-
-      // 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. 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 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.
-      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: mountedApp.stage,
-        drivesOwnLoop: false,
-        // 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;
-          // 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.
-          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
-          // the Application is destroyed on the `Lifecycle` cleanup signal
-          // instead of inline: `useTick`'s cleanup calls `ticker.remove()`, and
-          // 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);
-          runtime?.dispose();
-        },
-      };
-    },
-  };
-}