@vgai/engine 0.5.21 → 0.5.23

package/src/audio/bus-mixer.ts

@@ -0,0 +1,161 @@
+/**
+ * A named-bus mixer over Web Audio: buses created on demand, routed into each
+ * other by name, and set in DECIBELS.
+ *
+ * Every mixer a game reaches for is this shape — Unity's `AudioMixerGroup`,
+ * Godot's bus layout, FMOD's VCAs, and the `music`/`sfx`/`voice` trio
+ * `setup/setup-audio.ts` hands a first-party three world. What they share is
+ * not the protocol (that part is genuinely per-ecosystem and stays with the
+ * lane that speaks it) but the machinery underneath: a `GainNode` per bus, a
+ * name → node map, a parent to route into, and the one conversion below. This
+ * file owns exactly that, and nothing that names an ecosystem.
+ *
+ * ## dB is not a gain, and the mistake is silent
+ *
+ * `GainNode.gain` is a LINEAR amplitude multiplier; every mixer's authored
+ * volume is logarithmic dB, where 0 dB is unity and −80 dB is silence. Writing
+ * the dB number straight onto `gain.value` gives you a gain of −80 (a phase
+ * inversion at 80x) where the author asked for silence, and it does not throw,
+ * warn, or look wrong in a debugger — it is just loud. {@link dbToLinear} is
+ * the one conversion, `10^(dB/20)`, which is both Godot's `db_to_linear`
+ * (`core/math/math_funcs.h`: `exp(db * 0.11512925464970228…)`, the same
+ * function written in base e) and Unity's mixer volume curve.
+ *
+ * It deliberately does NOT clamp. A mixer's RANGE is protocol — Unity's
+ * exposed parameters saturate at its slider's ends, Godot's `volume_db` does
+ * not — so the lane that knows the range applies it before calling here, and
+ * this file cannot silently mute or silently boost anyone's authored value.
+ *
+ * ## Create-on-demand, and why it is the contract rather than a convenience
+ *
+ * {@link AudioBusMixer.bus} MINTS a bus the first time it is named and returns
+ * the SAME node forever after. The identity is the contract, not the minting:
+ * a source connects to a bus long before anything sets that bus's volume, and
+ * a parent is usually named by its child before anyone asks for it directly
+ * (`bus('music', 'master')` builds `master` too, and the later `bus('master')`
+ * must be that same node). A `bus()` that minted per call would hand the
+ * volume control a SECOND node — the sources would keep feeding the first one,
+ * every later write would land on a node nothing plays through, and nothing
+ * would throw or look wrong. So the map is authoritative, and the only way a
+ * name stops resolving to its node is {@link AudioBusMixer.remove} or
+ * {@link AudioBusMixer.disconnect}.
+ *
+ * A re-ask that names a DIFFERENT parent throws by name. Routing is decided at
+ * creation (the node is already connected by then), so honouring the second
+ * parent would mean silently re-routing live audio and ignoring it would mean
+ * silently keeping the first — a loud error is the only reading that is not a
+ * lie.
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * No module-scoped state: {@link createAudioBusMixer} is a factory and the
+ * OWNER of an instance is whoever called it (a `setupAudio` graph, one
+ * translated port's mixer store). What an instance ALLOCATES is one `GainNode`
+ * per named bus, and disconnecting those is the whole of its teardown
+ * obligation — {@link AudioBusMixer.disconnect}, called once by that same
+ * owner. The `context` and the `destination` node are NOT its own: they are
+ * passed in, shared with everything else hanging off the same graph, and this
+ * file never creates, closes, suspends or disconnects either one.
+ */
+
+/**
+ * The graph an {@link AudioBusMixer} hangs off, as the two members it touches.
+ *
+ * Narrow on purpose: `createGain` is all it needs from the context, so a real
+ * `AudioContext`, an `OfflineAudioContext` and a headless stand-in are all
+ * acceptable without a cast.
+ */
+export interface AudioBusMixerOptions {
+  readonly context: { createGain(): GainNode };
+  /** The node every parentless bus feeds. Usually a master gain or the context's destination. */
+  readonly destination: AudioNode;
+}
+
+export interface AudioBusMixer {
+  /**
+   * The bus named `name`, created on the first ask and connected to `parent`
+   * (itself created on demand) or to the destination.
+   *
+   * The returned node is the real `GainNode` — set `gain.value`, schedule
+   * automation on `gain`, connect sources to it. Nothing here stands between a
+   * caller and Web Audio's own API.
+   */
+  bus(name: string, parent?: string): GainNode;
+  /** The bus named `name` if it EXISTS, else null. Never mints one. */
+  find(name: string): GainNode | null;
+  /** Set this bus's gain from decibels, creating it if absent. Clamp before calling — see the header. */
+  setDb(name: string, db: number, parent?: string): void;
+  /**
+   * Disconnect one bus and forget its name, so a later {@link bus} mints a
+   * fresh node. Buses that named it as their parent are NOT re-routed — they
+   * keep feeding the removed node, which now reaches nothing.
+   */
+  remove(name: string): void;
+  /** Disconnect every bus and forget them all. The owner's ONE teardown. */
+  disconnect(): void;
+}
+
+/** dB → linear amplitude: `10^(dB/20)`. 0 dB is 1, −6 dB is ~0.5, −80 dB is ~0.0001. Never clamps. */
+export function dbToLinear(db: number): number {
+  return 10 ** (db / 20);
+}
+
+interface BusRecord {
+  readonly node: GainNode;
+  readonly parent: string | undefined;
+}
+
+function safeDisconnect(node: GainNode): void {
+  try {
+    node.disconnect();
+  } catch {
+    // already disconnected
+  }
+}
+
+/** Create one named-bus mixer. See the header for what owns the instance and what it allocates. */
+export function createAudioBusMixer(options: AudioBusMixerOptions): AudioBusMixer {
+  const { context, destination } = options;
+  const buses = new Map<string, BusRecord>();
+
+  function bus(name: string, parent?: string): GainNode {
+    const existing = buses.get(name);
+    if (existing !== undefined) {
+      if (parent !== undefined && parent !== existing.parent) {
+        throw new Error(
+          `audio bus ${JSON.stringify(name)} already routes into ` +
+            `${existing.parent === undefined ? 'the destination' : JSON.stringify(existing.parent)}` +
+            `; it cannot also route into ${JSON.stringify(parent)}. Routing is decided when a bus ` +
+            'is created (see packages/engine/src/audio/bus-mixer.ts).',
+        );
+      }
+      return existing.node;
+    }
+    // The parent is resolved (and minted, recursively) before this bus is
+    // seated, so a conflicting-parent throw upstream leaves nothing half-built.
+    const into = parent === undefined ? destination : bus(parent);
+    const node = context.createGain();
+    node.gain.value = 1;
+    node.connect(into);
+    buses.set(name, { node, parent });
+    return node;
+  }
+
+  return {
+    bus,
+    find: (name) => buses.get(name)?.node ?? null,
+    setDb: (name, db, parent) => {
+      bus(name, parent).gain.value = dbToLinear(db);
+    },
+    remove: (name) => {
+      const record = buses.get(name);
+      if (record === undefined) return;
+      buses.delete(name);
+      safeDisconnect(record.node);
+    },
+    disconnect: () => {
+      for (const record of buses.values()) safeDisconnect(record.node);
+      buses.clear();
+    },
+  };
+}

package/src/canvas-react/index.ts

@@ -15,19 +15,15 @@
  * or the Pixi reconciler.
  *
  * Surface:
- *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
- *    a first-party `surface: "canvas"` root under the host's gated loop.
  *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
- *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *    module MEANS: a default-exported component, mounted as a first-party
+ *    `surface: "canvas"` root under the host's gated loop. The world's vgai
+ *    surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host at
+ *    mount.
  *  - `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 `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.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
- *    adopters building their own bridge.
  *
  * The Pixi runtime itself is NOT re-exported here. A component reaches the live
  * `Application` (and therefore `stage`, `renderer`, `ticker`) with
@@ -35,17 +31,5 @@
  * assets with Pixi's own `Assets` — the library's API, not a second one.
  */
 
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
 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 CanvasGameContext,
-  type CanvasRootContextOptions,
-  type CanvasRootRuntime,
-  createCanvasRootContext,
-  DEFAULT_INPUT_MAP_PATH,
-} from './world-context';

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

@@ -1,8 +1,6 @@
 /**
  * `pixiReactRootFactory` — mount a `canvas` root whose entry module
- * DEFAULT-EXPORTS a React component.
- *
- * A model asked for a 2D world writes:
+ * DEFAULT-EXPORTS a React component. This is the ONE first-party canvas mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,11 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createPixiReactAdapter({ id, content })`.
- * That export is vgai ceremony wrapped around a component the author already
- * wrote. The `three` and `dom` roots both settled this convention — read
- * `entryModule.default` and wrap it — and this is the same contract for canvas
- * roots, so all three surfaces answer "what do I export?" the same way.
+ * The world is an ordinary `@pixi/react` app. Everything vgai-shaped stays at
+ * the entry module's STATIC surface (`export { debug, systems } from
+ * './commands'`) and on the host's side of the seam; no vgai runtime context
+ * ever enters the React tree. The host advances Pixi's real (never-started)
+ * ticker on GAME time, wires the game-scoped input seams from outside
+ * (`../runtime/game-input-seams.ts`), and installs `WorldProvider` off the
+ * Game handle so the lib-legal react doors resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -24,22 +24,298 @@
  * the opt-in module that owns those dependencies, so the factory lives here and
  * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
  *
- * ## Compatibility
+ * ## 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).
  *
- * An `adapter` export still wins, so a game needing full control over its own
- * `RootAdapter<'canvas'>` keeps 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`). A world that adds its own classes
+ * (`@pixi/tilemap`, a custom `Container` subclass) calls `extend`/`useExtend`
+ * itself.
  */
 
-import { type ComponentType, createElement } from 'react';
-import type { RootAdapter } from '../adapter/root-adapter';
+import { createRoot, extend } from '@pixi/react';
+import type { Application, ApplicationOptions } from 'pixi.js';
+import * as PIXI from 'pixi.js';
+import { type ComponentType, createElement, Fragment, 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 { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
-import { createPixiReactAdapter } from './pixi-react-adapter';
+
+/** 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>;
 
 interface CanvasEntryModuleExports {
-  /** The idiomatic shape: the world IS a component. */
+  /** The one shape: the world IS a component. */
   readonly default?: ComponentType;
-  /** Full control, and still the winner when present. */
-  readonly adapter?: RootAdapter<'canvas'>;
+}
+
+/**
+ * Build the `RootAdapter<'canvas'>` for one default-exported Pixi world.
+ * Mounts 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.
+ */
+function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'canvas'> {
+  const content = createElement(component);
+
+  return {
+    id,
+
+    async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
+      // THE HOST WIRES THIS GAME'S INPUT FROM OUTSIDE THE TREE — the project's
+      // declared map (conventional path, optional: a brand-new project
+      // declares no actions yet) and this root's `game.input.*` seams on the
+      // debug registry. Actions must exist before any component's first tick
+      // reads them — wait for the (never-rejecting) load before the first
+      // commit.
+      const registry = host.game ? getDebugRegistry(host.game) : null;
+      if (registry) {
+        await wireGameInputSeams(host, registry, {
+          id,
+          inputMapPath: DEFAULT_INPUT_MAP_PATH,
+          optionalInputMap: true,
+        });
+      }
+
+      const canvas = host.canvas;
+      if (MOUNTED_CANVASES.has(canvas)) {
+        throw new Error(
+          `canvas world "${id}": this lane has already mounted this canvas. @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 provider/command effects have registered,
+        // so mount() can truthfully back Play's ack.
+        useEffect(resolveEffectsReady, []);
+        return null;
+      }
+
+      // `WorldProvider` rides `host.game` — the React seam every dom root
+      // already has, and the only way a capability hook can reach the ONE
+      // game-scoped registry the editor/`vgai eval` read. `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 game = host.game;
+      const world = createElement(Fragment, null, content, createElement(Lifecycle));
+      const element = game ? createElement(WorldProvider, { game }, world) : world;
+
+      const root: PixiReactRoot = createRoot(canvas);
+
+      // The host owns size, dpr, transparency and capture cost; the loop
+      // contract owns `autoStart`/`sharedTicker`.
+      const initOptions: Partial<ApplicationOptions> = {
+        antialias: true,
+        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;
+
+        // 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(`canvas world "${id}": ${failure}`);
+        }
+      } catch (error) {
+        try {
+          app?.destroy(false, { children: true });
+        } catch {
+          /* the world never fully came up; teardown failure must not mask why */
+        }
+        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) {
+        throw new Error(`canvas world "${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;
+      // Adapter surface: the host's shared debug registry. The game's own
+      // capabilities arrive as the entry module's declared `systems`.
+      const systemAdapters: 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,
+        systems: systemAdapters,
+        disposeComplete,
+        update(dt: number): void {
+          if (disposed) return;
+          elapsedMs += dt * 1000;
+          // The real Pixi ticker remains the one scheduler `useTick` observes;
+          // the host only gates/advances it.
+          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);
+        },
+      };
+    },
+  };
 }
 
 /**
@@ -48,45 +324,31 @@ interface CanvasEntryModuleExports {
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link pixiReactRootFactory}, below) and the EDITOR, which resolves
  * the same entry for play mode and for the design-time layer. When only one
- * side knows about the default-export shape, a world plays fine and shows
- * "(no scene loaded)" in edit mode — the exact split the three lane already
- * paid for.
+ * side knows the shape, a world plays fine and shows "(no scene loaded)" in
+ * edit mode.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws; the editor reports a mount failure on
- * that root's boundary node and leaves every sibling working).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws; the editor
+ * reports a mount failure on that root's boundary node and leaves every
+ * sibling working).
  */
 export function resolveCanvasEntryAdapter(
   entryModule: unknown,
   rootId: string,
 ): RootAdapter<'canvas'> | null {
   const mod = entryModule as CanvasEntryModuleExports | undefined;
-  if (mod?.adapter) return mod.adapter;
-  if (typeof mod?.default === 'function') {
-    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.
-    });
-  }
+  if (typeof mod?.default === 'function') return canvasWorldAdapter(rootId, mod.default);
   return null;
 }
 
 /**
  * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
- *
- * Resolution order mirrors the three lane's (explicit adapter wins) and then
- * accepts the default-exported component.
  */
 export const pixiReactRootFactory: AdapterSurfaceFactory = (root, ctx) => {
   const adapter = resolveCanvasEntryAdapter(ctx.entryModule, root.id);
   if (adapter) return { kind: 'canvas', adapter };
   throw new Error(
     `pixiReactRootFactory: entry module "${root.entry ?? '(none)'}" for root "${root.id}" must ` +
-      'default-export a React component (`export default function World() { … }`) — or export ' +
-      'an `adapter` for full control.',
+      'default-export a React component (`export default function World() { … }`).',
   );
 };