@vgai/engine 0.5.2 → 0.5.3

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

@@ -0,0 +1,202 @@
+/**
+ * `<PixiPrimitive>` and `adoptNow` — the canvas surface's seam for an object React did NOT create.
+ *
+ * ## Why this exists
+ *
+ * A first-party canvas world is a `@pixi/react` tree, and every element in one is built by the
+ * reconciler: `createInstance` does `new PixiComponent(props)` and there is no escape hatch for an
+ * existing `Container`. That is fine until something OUTSIDE React owns an object the tree has to
+ * render — which is the ordinary case the moment a world has a runtime, not just a picture:
+ *
+ *  - a translated Godot scene's own root, written to by a script (`mob.position = …`) in the same
+ *    statement sequence that constructs it, BEFORE anything has rendered;
+ *  - a container a game's own module or an asset pipeline handed over whole.
+ *
+ * three's lane answers this with `<primitive object={…}>`. This is that element for Pixi, and the
+ * three properties it must have are the three that make it not a mirror: the props go on the SAME
+ * object, the children go UNDER the same object, and unmount DETACHES it rather than destroying it
+ * — because React never owned it.
+ *
+ * ## How it is wired, and what @pixi/react actually offers
+ *
+ * Through `extend()`, which is @pixi/react's own documented extension point — the catalogue it
+ * resolves an intrinsic tag against. A registered class is constructed with the element's props, and
+ * a JS constructor that RETURNS an object hands back that object instead of the one `new` made: so
+ * the element's instance IS the adopted container, and from there every host-config path is the
+ * library's own (`appendChild` -> `parent.addChild`, `applyProps` -> the same property writes every
+ * other element gets, `insertBefore` -> `addChildAt`). No parallel reconciler, no re-implemented
+ * host config, no patched package.
+ *
+ * ONE path could not be wired through: `removeChild` unconditionally calls `childInstance.destroy()`
+ * (`@pixi/react` 8.0.5, `lib/helpers/removeChild.mjs`), there is no per-instance opt-out, and the
+ * host config is module-private (the package's `exports` map has only `"."`, so its
+ * `lib/core/reconciler` cannot be imported). {@link PixiPrimitive} therefore arms a ONE-SHOT
+ * `destroy` on the object in its own layout-effect cleanup — which React runs, synchronously,
+ * immediately before the `removeChild` that would destroy it — and that override detaches, restores
+ * the real method and is gone. It is disarmed on the next microtask regardless, so a deletion that
+ * never reaches this node (React calls `removeChild` only for the OUTERMOST host node of a deleted
+ * subtree) cannot leave the override installed.
+ *
+ * ## What `adoptNow` is for
+ *
+ * @pixi/react exports no reconciler `flushSync` — every `react-reconciler` instance closes over its
+ * own scheduler state (`module.exports = function ($$$config) { … }`), so no second instance and no
+ * other renderer can flush this one's work. A state update made from inside a frame therefore
+ * commits on React's own schedule rather than inside the call that made it.
+ *
+ * {@link adoptNow} is what the seam CAN offer for that: the half of the guarantee that is about the
+ * DISPLAY TREE rather than about React. A caller that has just created an object and asked React to
+ * render it places it now, and the commit that follows is an idempotent re-adoption of the same
+ * object under the same parent — `<PixiPrimitive>` renders the object the caller already placed, so
+ * there is one object and one tree, never a second insertion. What it does not do is run the
+ * object's own mount work early: whatever the rendering component does in its layout effect still
+ * happens when React commits, and a caller that needs that ordering must say so.
+ */
+
+import { extend } from '@pixi/react';
+import { Container } from 'pixi.js';
+import {
+  createElement,
+  type FunctionComponent,
+  type ReactNode,
+  useLayoutEffect,
+  useRef,
+} from 'react';
+
+/** The prop the adoption element carries its object on. */
+const OBJECT_PROP = 'object';
+
+/**
+ * The catalogue entry, and the whole of the adoption mechanism.
+ *
+ * It is never instantiated: a constructor that returns an object hands that object back to the
+ * caller, so `new AdoptedPixiObject({ object })` IS `object`. That is the one thing @pixi/react's
+ * `createInstance` cannot do on its own and the only thing this class exists for.
+ */
+class AdoptedPixiObject {
+  constructor(props: { readonly [OBJECT_PROP]?: unknown }) {
+    const object = props[OBJECT_PROP];
+    if (!(object instanceof Container)) {
+      throw new Error(
+        'PixiPrimitive: `object` must be a PIXI.Container (got ' +
+          `${object === null ? 'null' : typeof object}). This element adopts an object the game ` +
+          'already owns; it does not create one.',
+      );
+    }
+    // `applyProps` writes every prop it is given onto the instance, and the instance here is the
+    // GAME'S object. A non-enumerable accessor answers with the object and swallows that write, so
+    // adoption never plants a self-reference on something the game holds.
+    Object.defineProperty(object, OBJECT_PROP, {
+      configurable: true,
+      enumerable: false,
+      get: () => object,
+      set: () => {},
+    });
+    // The returned object IS the mechanism — see this module's header. @pixi/react's
+    // `createInstance` has exactly one way to produce an element's instance
+    // (`new PixiComponent(props)`), so a constructor that hands back an existing object is the only
+    // door an existing one can be adopted through, and this class exists for nothing else. Nobody
+    // ever reads an `AdoptedPixiObject`; the catalogue is its only caller.
+    // biome-ignore lint/correctness/noConstructorReturn: adoption is exactly this return
+    return object;
+  }
+}
+
+extend({ VgaiAdopted: AdoptedPixiObject });
+
+/** The intrinsic `extend` above registered. Typed as a component so this module is the ONE place
+ *  that knows the tag; nothing else in the repo, and no game, ever spells it. */
+const ADOPTION_ELEMENT = 'pixiVgaiAdopted' as unknown as FunctionComponent<Record<string, unknown>>;
+
+export interface PixiPrimitiveProps {
+  /** The container to adopt. It must not change for the life of one element — see below. */
+  readonly object: Container;
+  readonly children?: ReactNode;
+  /** Everything else is an ordinary `@pixi/react` prop, applied to {@link object} itself. */
+  readonly [prop: string]: unknown;
+}
+
+/**
+ * Render an EXISTING `PIXI.Container` as an element of this tree.
+ *
+ * ```tsx
+ * <PixiPrimitive object={scene.node} label={'Main'} x={0} y={0}>
+ *   <pixiSprite label={'Background'} texture={background} />
+ * </PixiPrimitive>
+ * ```
+ *
+ * The props land on `scene.node`, the children become its children, and when this unmounts
+ * `scene.node` leaves the display tree intact — its lifetime belongs to whoever made it.
+ */
+export function PixiPrimitive(props: PixiPrimitiveProps): React.JSX.Element {
+  const { object, children, ...rest } = props;
+  // The adopted object is the element's INSTANCE, and an instance is fixed for the life of an
+  // element — a changed `object` would silently keep rendering the old one. Refuse by name instead.
+  const adopted = useRef(object);
+  if (adopted.current !== object) {
+    throw new Error(
+      'PixiPrimitive: `object` changed on a mounted element. The adopted container IS this ' +
+        "element's instance, so it cannot be swapped; give the element a `key` derived from the " +
+        'object instead, so React remounts it.',
+    );
+  }
+  useLayoutEffect(() => {
+    // React runs this cleanup, synchronously, just before the `removeChild` that would destroy the
+    // object — see this module's header.
+    return () => armDetach(object);
+    // `object` is invariant for this element (asserted above), so this is once per mount.
+  }, [object]);
+  // An `undefined` prop is DROPPED, so absent means "keep what the game set". @pixi/react's mount
+  // diff compares element props against the instance's OWN-enumerable snapshot, and for an own
+  // property (a v8 `Container`'s `label`) that snapshot shows the live value — so a forwarded-but-
+  // unset prop (`label={props.label}` on a spawned scene root) would diff `'Mob' -> undefined` and
+  // write `undefined` onto the game's object. Dropping the key instead also gives a later
+  // defined -> undefined transition the library's own REMOVAL semantics (reset to the class
+  // default) rather than a literal `undefined` write.
+  const applied: Record<string, unknown> = { [OBJECT_PROP]: object };
+  for (const [key, value] of Object.entries(rest)) {
+    if (value !== undefined) applied[key] = value;
+  }
+  return createElement(ADOPTION_ELEMENT, applied, children);
+}
+
+/**
+ * Turn the next `destroy()` on `object` into a detach, then restore the real method.
+ *
+ * One shot and self-disarming: the override removes itself before doing anything, and a microtask
+ * removes it in any case, so the window in which it can answer is exactly React's own (synchronous)
+ * commit.
+ */
+function armDetach(object: Container): void {
+  const target = object as unknown as { destroy: Container['destroy'] };
+  const previous = Object.getOwnPropertyDescriptor(object, 'destroy');
+  let armed = true;
+  const disarm = (): void => {
+    if (!armed) return;
+    armed = false;
+    if (previous === undefined) delete (target as Partial<typeof target>).destroy;
+    else Object.defineProperty(object, 'destroy', previous);
+  };
+  Object.defineProperty(object, 'destroy', {
+    configurable: true,
+    enumerable: false,
+    writable: true,
+    value: function detachInsteadOfDestroy(this: Container): void {
+      disarm();
+      this.removeFromParent();
+    },
+  });
+  queueMicrotask(disarm);
+}
+
+/**
+ * Put `child` under `parent` NOW, ahead of the commit that will render it.
+ *
+ * The canvas surface's answer to a reconciler `flushSync`, which @pixi/react does not expose (see
+ * this module's header). Idempotent with {@link PixiPrimitive}: re-adopting the same object under
+ * the same parent is what the commit does, and Pixi's own `addChild` treats it as a no-op reorder.
+ */
+export function adoptNow(parent: Container, child: Container): void {
+  if (child.parent === parent) return;
+  parent.addChild(child);
+}

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

@@ -0,0 +1,290 @@
+/**
+ * `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 exact 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`.
+ *
+ * ## 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
+ * `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, type ReactNode, useLayoutEffect } from 'react';
+import type { CanvasHostContext, MountedPixiRoot, RootAdapter } from '../adapter';
+import { WorldProvider } from '../react/world-state';
+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;
+  /**
+   * 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, applicationOptions } = options;
+
+  return {
+    id,
+
+    async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
+      const runtime = createCanvasRootContext(host, { id, inputMapPath });
+      const bridge: EngineBridgeValue = { ctx: runtime.ctx };
+      // 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 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;
+        }, []);
+        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),
+      );
+
+      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,
+      };
+
+      // `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);
+
+      // 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)',
+          );
+        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();
+        });
+      });
+
+      // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
+      // without this the first `update()` would report a 1ms phantom delta on
+      // top of the real one. From here every `deltaMS` a `useTick` callback
+      // sees is exactly the `dt` the host handed us — no wall clock anywhere,
+      // which is what makes a paused world's resume frame ordinary rather than
+      // one giant catch-up step.
+      app.ticker.lastTime = 0;
+      let elapsedMs = 0;
+      let disposed = false;
+
+      return {
+        kind: 'canvas',
+        // The reconciler's real root container — the same `PIXI.Container`
+        // `RootInstance.pixiStage()` hands the editor.
+        stage: app.stage,
+        drivesOwnLoop: false,
+        // Adapter surface: `debug` pre-seeded (the shared game registry's
+        // adapter); game code adds capabilities via `ctx.registerSystemAdapter`.
+        systems: runtime.systemAdapters,
+        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);
+        },
+        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);
+        },
+        dispose(): void {
+          if (disposed) return;
+          disposed = true;
+          // 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);
+          void unmounted.then(() => app.destroy(false, { children: true }));
+          runtime.dispose();
+        },
+      };
+    },
+  };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * `pixiReactRootFactory` — mount a `canvas` root whose entry module
+ * DEFAULT-EXPORTS a React component.
+ *
+ * A model asked for a 2D world writes:
+ *
+ * ```tsx
+ * export default function World() {
+ *   return <pixiContainer><pixiSprite texture={Texture.WHITE} /></pixiContainer>;
+ * }
+ * ```
+ *
+ * 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.
+ *
+ * ## Why this is NOT in `mount-game.ts`
+ *
+ * The kind registry beside `mount-game.ts` is deliberately dependency-free:
+ * registering a canvas factory there would make `pixi.js` + `@pixi/react`
+ * unconditional for every game, including three-only ones. `canvas-react` is
+ * the opt-in module that owns those dependencies, so the factory lives here and
+ * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
+ *
+ * ## Compatibility
+ *
+ * An `adapter` export still wins, so a game needing full control over its own
+ * `RootAdapter<'canvas'>` keeps it.
+ */
+
+import { type ComponentType, createElement } from 'react';
+import type { RootAdapter } from '../adapter/root-adapter';
+import type { AdapterSurfaceFactory } from '../runtime/mount-game';
+import { createPixiReactAdapter } from './pixi-react-adapter';
+
+interface CanvasEntryModuleExports {
+  /** The idiomatic shape: the world IS a component. */
+  readonly default?: ComponentType;
+  /** Full control, and still the winner when present. */
+  readonly adapter?: RootAdapter<'canvas'>;
+}
+
+/**
+ * What a canvas entry module MEANS, in one place.
+ *
+ * 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.
+ *
+ * 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).
+ */
+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),
+    });
+  }
+  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.',
+  );
+};