@vgai/engine 0.5.4 → 0.5.6

package/dist/canvas-react/pixi-primitive.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `<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 { Container } from 'pixi.js';
+import { type ReactNode } from 'react';
+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 declare function PixiPrimitive(props: PixiPrimitiveProps): React.JSX.Element;
+/**
+ * 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 declare function adoptNow(parent: Container, child: Container): void;
+//# sourceMappingURL=pixi-primitive.d.ts.map

package/dist/canvas-react/pixi-primitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixi-primitive.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-primitive.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,OAAO,CAAC;AA+Cf,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAC9B,2FAA2F;IAC3F,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA8B1E;AA+BD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAGlE"}

package/dist/canvas-react/pixi-primitive.js

@@ -0,0 +1,181 @@
+/**
+ * `<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, 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) {
+        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';
+/**
+ * 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) {
+    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 = { [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) {
+    const target = object;
+    const previous = Object.getOwnPropertyDescriptor(object, 'destroy');
+    let armed = true;
+    const disarm = () => {
+        if (!armed)
+            return;
+        armed = false;
+        if (previous === undefined)
+            delete target.destroy;
+        else
+            Object.defineProperty(object, 'destroy', previous);
+    };
+    Object.defineProperty(object, 'destroy', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: function detachInsteadOfDestroy() {
+            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, child) {
+    if (child.parent === parent)
+        return;
+    parent.addChild(child);
+}

package/dist/canvas-react/pixi-react-adapter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `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 type { ApplicationOptions } from 'pixi.js';
+import { type ReactNode } from 'react';
+import type { RootAdapter } from '../adapter';
+/** 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 declare function createPixiReactAdapter(options: CreatePixiReactAdapterOptions): RootAdapter<'canvas'>;
+//# sourceMappingURL=pixi-react-adapter.d.ts.map

package/dist/canvas-react/pixi-react-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixi-react-adapter.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAiB,KAAK,SAAS,EAAmB,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AAyBlF,sFAAsF;AACtF,MAAM,WAAW,6BAA6B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;yDACqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,WAAW,CAAC,QAAQ,CAAC,CA8LvB"}

package/dist/canvas-react/pixi-react-adapter.js

@@ -0,0 +1,229 @@
+/**
+ * `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 * as PIXI from 'pixi.js';
+import { createElement, useLayoutEffect } from 'react';
+import { WorldProvider } from '../react/world-state';
+import { EngineBridge } 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();
+/**
+ * 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) {
+    const { id, content, inputMapPath, applicationOptions } = options;
+    return {
+        id,
+        async mount(host) {
+            const runtime = createCanvasRootContext(host, { id, inputMapPath });
+            const bridge = { 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);
+            let resolveCommitted;
+            const committed = new Promise((resolve) => {
+                resolveCommitted = resolve;
+            });
+            let resolveUnmounted;
+            const unmounted = new Promise((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() {
+                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 = 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 = {
+                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 = 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((resolve, reject) => {
+                const fail = (why) => {
+                    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) => 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) {
+                    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, height) {
+                    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() {
+                    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/dist/canvas-react/pixi-react-root-factory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `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 { RootAdapter } from '../adapter/root-adapter';
+import type { AdapterSurfaceFactory } from '../runtime/mount-game';
+/**
+ * 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 declare function resolveCanvasEntryAdapter(entryModule: unknown, rootId: string): RootAdapter<'canvas'> | null;
+/**
+ * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
+ *
+ * Resolution order mirrors the three lane's (explicit adapter wins) and then
+ * accepts the default-exported component.
+ */
+export declare const pixiReactRootFactory: AdapterSurfaceFactory;
+//# sourceMappingURL=pixi-react-root-factory.d.ts.map

package/dist/canvas-react/pixi-react-root-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAU9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAQlC,CAAC"}