@vgai/engine 0.5.21 → 0.5.23

package/dist/animation/clip-map.d.ts

@@ -1,12 +0,0 @@
-import type * as THREE from 'three';
-/**
- * Build the clip lookup shared by runtime and editor.
- *
- * GLTF exporters disagree about case and may prefix animation names with an
- * armature (`Armature|Idle`). Keep the exact exported suffix while also
- * exposing a lowercase lookup, then apply aliases case-insensitively. This
- * lets authored graphs use either `Idle_Loop` or `idle_loop` without silently
- * falling back to the bind pose.
- */
-export declare function buildClipMap(animations: THREE.AnimationClip[], aliases?: Record<string, string>): Map<string, THREE.AnimationClip>;
-//# sourceMappingURL=clip-map.d.ts.map

package/dist/animation/clip-map.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clip-map.d.ts","sourceRoot":"","sources":["../../src/animation/clip-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,EACjC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CAmBlC"}

package/dist/animation/clip-map.js

@@ -1,31 +0,0 @@
-/**
- * Build the clip lookup shared by runtime and editor.
- *
- * GLTF exporters disagree about case and may prefix animation names with an
- * armature (`Armature|Idle`). Keep the exact exported suffix while also
- * exposing a lowercase lookup, then apply aliases case-insensitively. This
- * lets authored graphs use either `Idle_Loop` or `idle_loop` without silently
- * falling back to the bind pose.
- */
-export function buildClipMap(animations, aliases = {}) {
-    const clips = new Map();
-    const canonical = new Map();
-    for (const clip of animations) {
-        const raw = clip.name.split('|').pop()?.trim() || clip.name;
-        canonical.set(raw.toLowerCase(), clip);
-        if (!clips.has(raw))
-            clips.set(raw, clip);
-        if (!clips.has(raw.toLowerCase()))
-            clips.set(raw.toLowerCase(), clip);
-    }
-    for (const [source, alias] of Object.entries(aliases)) {
-        const clip = canonical.get(source.toLowerCase());
-        if (!clip)
-            continue;
-        if (!clips.has(alias))
-            clips.set(alias, clip);
-        if (!clips.has(alias.toLowerCase()))
-            clips.set(alias.toLowerCase(), clip);
-    }
-    return clips;
-}

package/dist/asset-registry.d.ts

@@ -1,38 +0,0 @@
-/**
- * Central asset registry — stores per-asset metadata (import corrections, etc.).
- *
- * Loaded once via fetch(), cached in memory. Both the runtime scene loader
- * and editor entity factory import from this module.
- */
-import * as THREE from 'three';
-export interface ImportCorrection {
-    /** Uniform scale factor applied to the GLTF clone before entity transform. */
-    scale?: number;
-    /** Euler rotation in degrees [x, y, z] applied to the GLTF clone before entity transform. */
-    rotation?: [number, number, number];
-}
-export interface AssetMeta {
-    importCorrection?: ImportCorrection;
-}
-/**
- * Apply an asset's visual-only import correction to the loaded GLTF content.
- * Call this on the model child, before placing it under the entity wrapper, so
- * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
- * -Z-forward coordinate contract.
- */
-export declare function applyImportCorrection(content: THREE.Object3D, correction: ImportCorrection | undefined): void;
-type AssetRegistry = Record<string, AssetMeta>;
-/**
- * Fetch and cache the asset registry. Safe to call multiple times —
- * returns the cached result after the first successful load.
- */
-export declare function loadRegistry(): Promise<AssetRegistry>;
-/** Get metadata for an asset path, or undefined if not in the registry. */
-export declare function getAssetMeta(path: string): AssetMeta | undefined;
-/**
- * Update the in-memory cache directly (used by the editor after saving
- * import settings, to avoid a re-fetch).
- */
-export declare function setRegistryCache(data: AssetRegistry): void;
-export {};
-//# sourceMappingURL=asset-registry.d.ts.map

package/dist/asset-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-registry.d.ts","sourceRoot":"","sources":["../src/asset-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,KAAK,CAAC,QAAQ,EACvB,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,IAAI,CAUN;AAED,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAU/C;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAgBrD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAG1D"}

package/dist/asset-registry.js

@@ -1,66 +0,0 @@
-/**
- * Central asset registry — stores per-asset metadata (import corrections, etc.).
- *
- * Loaded once via fetch(), cached in memory. Both the runtime scene loader
- * and editor entity factory import from this module.
- */
-import * as THREE from 'three';
-import { resolveUrl } from './loader';
-/**
- * Apply an asset's visual-only import correction to the loaded GLTF content.
- * Call this on the model child, before placing it under the entity wrapper, so
- * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
- * -Z-forward coordinate contract.
- */
-export function applyImportCorrection(content, correction) {
-    if (!correction)
-        return;
-    if (correction.scale !== undefined)
-        content.scale.multiplyScalar(correction.scale);
-    if (correction.rotation) {
-        content.rotation.set(THREE.MathUtils.degToRad(correction.rotation[0]), THREE.MathUtils.degToRad(correction.rotation[1]), THREE.MathUtils.degToRad(correction.rotation[2]));
-    }
-}
-let registryCache = null;
-let registryPromise = null;
-/** Normalize asset path for registry lookup (strip leading slash). */
-function normalize(path) {
-    return path.startsWith('/') ? path.slice(1) : path;
-}
-/**
- * Fetch and cache the asset registry. Safe to call multiple times —
- * returns the cached result after the first successful load.
- */
-export function loadRegistry() {
-    if (registryCache)
-        return Promise.resolve(registryCache);
-    if (registryPromise)
-        return registryPromise;
-    registryPromise = fetch(resolveUrl('asset-registry.json'))
-        .then((res) => {
-        if (!res.ok)
-            return {};
-        return res.json();
-    })
-        .catch(() => ({}))
-        .then((data) => {
-        registryCache = data;
-        return data;
-    });
-    return registryPromise;
-}
-/** Get metadata for an asset path, or undefined if not in the registry. */
-export function getAssetMeta(path) {
-    if (!registryCache)
-        return undefined;
-    // Try exact match first, then normalized
-    return registryCache[path] ?? registryCache[normalize(path)];
-}
-/**
- * Update the in-memory cache directly (used by the editor after saving
- * import settings, to avoid a re-fetch).
- */
-export function setRegistryCache(data) {
-    registryCache = data;
-    registryPromise = null;
-}

package/dist/canvas-react/engine-bridge.d.ts

@@ -1,45 +0,0 @@
-/**
- * `@engine/canvas-react` — the React context that carries a canvas world's
- * engine runtime into its `@pixi/react` tree: the world's `GameContext`, read
- * with {@link useGameContext}.
- *
- * The bridge value is built by `createPixiReactAdapter`'s `mount()`
- * (./pixi-react-adapter.tsx), whose `update(dt)` runs this world's phases under
- * the HOST loop — so registered systems tick in engine phase order, pause
- * included (no update while the world is frozen).
- *
- * Behavior in a canvas world is components + hooks: `useGameContext` reaches
- * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
- * `useApplication` is the door to the live `Application`.
- */
-import type { CanvasGameContext } from './world-context';
-export interface EngineBridgeValue {
-    /** This root's `CanvasGameContext` — `input`, `debug`, `random`, `clock`, `game`,
-     *  `roots`, `systems`, `registerSystemAdapter`. Present so ordinary
-     *  components can reach engine services with a HOOK (see
-     *  {@link useGameContext}). */
-    readonly ctx?: CanvasGameContext | undefined;
-}
-export declare const EngineBridge: import("react").Context<EngineBridgeValue | null>;
-/**
- * This canvas root's `CanvasGameContext`, for use inside any component in the tree.
- *
- * An ordinary component does what a model would write:
- *
- * ```tsx
- * function Player({ speed = 220 }) {
- *   const { input } = useGameContext();
- *   const ref = useRef<Sprite>(null);
- *   useTick(({ deltaMS }) => {
- *     if (input?.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
- *   });
- *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
- * }
- * ```
- *
- * Throws when called outside a canvas root mounted by
- * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
- * `null` would surface as a mystery `undefined` deep in a tick callback.
- */
-export declare function useGameContext(): CanvasGameContext;
-//# sourceMappingURL=engine-bridge.d.ts.map

package/dist/canvas-react/engine-bridge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/canvas-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC;;;mCAG+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC9C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,CAUlD"}

package/dist/canvas-react/engine-bridge.js

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

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

@@ -1,77 +0,0 @@
-/**
- * `createPixiReactAdapter` — wraps a `@pixi/react` tree as a first-party
- * `RootAdapter<'canvas'>` so a Pixi world mounts as an ordinary
- * `surface: "canvas"` root: the engine hands `mount()` a `CanvasHostContext`
- * (its own canvas + size + compositing hints, per `../adapter/host-context.ts`);
- * this returns a `MountedPixiRoot` (`../adapter/root-adapter.ts`) whose `stage`
- * is the REAL `PIXI.Container` the reconciler renders into.
- *
- * This is the canvas surface's sibling of `world3d-react`'s
- * `createR3FAdapter`, with `@pixi/react` where that one has
- * react-three-fiber. The explicit factory still supplies the engine context
- * used by the current first-party Canvas examples while their app-owned input
- * and debugger migration remains tracked in `docs/WORK.md`; `useTick` hooks
- * stay registered on Pixi's real ticker throughout that migration.
- *
- * ## The loop contract
- *
- * `Application` is initialized with `autoStart: false` and `sharedTicker:
- * false`, so it owns a native Pixi ticker that is NEVER started and therefore
- * never requests an animation frame. `mounted.update(dt)` is the only thing
- * that advances that ticker, and it feeds GAME time, not wall time — which is
- * what makes the world freeze exactly when the host freezes it, and what makes
- * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
- * loop's own catch-up still calls `update`, and Pixi has no independent clock
- * to disagree with it).
- *
- * ## Component catalogue
- *
- * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
- * that starts EMPTY — the first intrinsic in an un-extended tree throws
- * "X is not part of the PIXI namespace! Did you forget to extend?". This
- * module extends it with the whole `pixi.js` namespace once per mount
- * (idempotent `Object.assign`), the same thing `createR3FAdapter` does with
- * `extend(host.three)`. A world that adds its own classes (`@pixi/tilemap`,
- * a custom `Container` subclass) calls `extend`/`useExtend` itself.
- */
-import 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;
-    /**
-     * Transitional compatibility for component trees that still consume the
-     * engine context. Native trees opt out once their input, observation and
-     * debugger state are application-owned.
-     */
-    readonly engineRuntime?: boolean | undefined;
-    /**
-     * Extra `Application.init` options merged UNDER this adapter's own — e.g.
-     * `{ antialias: false }`, `{ roundPixels: true }`. The loop-critical ones
-     * (`autoStart`, `sharedTicker`) and the ones the host owns (size, dpr,
-     * transparency, `preserveDrawingBuffer`) are applied after this and cannot
-     * be overridden: a world that starts its own ticker or clears an opaque
-     * background under a stacked sibling breaks the host's contract, not just
-     * its own frame.
-     */
-    readonly applicationOptions?: Partial<ApplicationOptions> | undefined;
-}
-/**
- * Build a `RootAdapter<'canvas'>` that mounts `options.content` through
- * `@pixi/react`, gated entirely by the host's own loop and rendering into the
- * host's own canvas — never a second canvas, never a second
- * `requestAnimationFrame` loop.
- */
-export declare function createPixiReactAdapter(options: CreatePixiReactAdapterOptions): RootAdapter<'canvas'>;
-//# sourceMappingURL=pixi-react-adapter.d.ts.map

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

@@ -1 +0,0 @@
-{"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,EAA2B,KAAK,SAAS,EAA8B,MAAM,OAAO,CAAC;AAC5F,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AA2BlF,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;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;;;;;;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,CAwPvB"}

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

@@ -1,294 +0,0 @@
-/**
- * `createPixiReactAdapter` — wraps a `@pixi/react` tree as a first-party
- * `RootAdapter<'canvas'>` so a Pixi world mounts as an ordinary
- * `surface: "canvas"` root: the engine hands `mount()` a `CanvasHostContext`
- * (its own canvas + size + compositing hints, per `../adapter/host-context.ts`);
- * this returns a `MountedPixiRoot` (`../adapter/root-adapter.ts`) whose `stage`
- * is the REAL `PIXI.Container` the reconciler renders into.
- *
- * This is the canvas surface's sibling of `world3d-react`'s
- * `createR3FAdapter`, with `@pixi/react` where that one has
- * react-three-fiber. The explicit factory still supplies the engine context
- * used by the current first-party Canvas examples while their app-owned input
- * and debugger migration remains tracked in `docs/WORK.md`; `useTick` hooks
- * stay registered on Pixi's real ticker throughout that migration.
- *
- * ## The loop contract
- *
- * `Application` is initialized with `autoStart: false` and `sharedTicker:
- * false`, so it owns a native Pixi ticker that is NEVER started and therefore
- * never requests an animation frame. `mounted.update(dt)` is the only thing
- * that advances that ticker, and it feeds GAME time, not wall time — which is
- * what makes the world freeze exactly when the host freezes it, and what makes
- * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
- * loop's own catch-up still calls `update`, and Pixi has no independent clock
- * to disagree with it).
- *
- * ## Component catalogue
- *
- * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
- * that starts EMPTY — the first intrinsic in an un-extended tree throws
- * "X is not part of the PIXI namespace! Did you forget to extend?". This
- * module extends it with the whole `pixi.js` namespace once per mount
- * (idempotent `Object.assign`), the same thing `createR3FAdapter` does with
- * `extend(host.three)`. A world that adds its own classes (`@pixi/tilemap`,
- * a custom `Container` subclass) calls `extend`/`useExtend` itself.
- */
-import { createRoot, extend } from '@pixi/react';
-import * as PIXI from 'pixi.js';
-import { createElement, Fragment, useEffect, useLayoutEffect } from 'react';
-import { WorldProvider } from '../react/world-state';
-import { getDebugRegistry } from '../runtime/debug-registry';
-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, engineRuntime = true, applicationOptions } = options;
-    return {
-        id,
-        async mount(host) {
-            const runtime = engineRuntime ? createCanvasRootContext(host, { id, inputMapPath }) : null;
-            const bridge = runtime ? { ctx: runtime.ctx } : null;
-            // Actions must exist before any component's first tick reads them — wait
-            // for the (never-rejecting) input-map load before the first commit.
-            await runtime?.inputMapReady;
-            const canvas = host.canvas;
-            if (MOUNTED_CANVASES.has(canvas)) {
-                runtime?.dispose();
-                throw new Error(`createPixiReactAdapter: root "${id}" was handed a canvas this lane has already ` +
-                    'mounted. @pixi/react keys its reconciler roots off the canvas element, so re-using ' +
-                    'one would resurrect a root whose Application is destroyed. Hand each mount a fresh ' +
-                    'canvas (every vgai host already does).');
-            }
-            MOUNTED_CANVASES.add(canvas);
-            // The catalogue is module-global and starts empty; this is idempotent.
-            extend(PIXI);
-            let resolveCommitted;
-            const committed = new Promise((resolve) => {
-                resolveCommitted = resolve;
-            });
-            let resolveEffectsReady;
-            const effectsReady = new Promise((resolve) => {
-                resolveEffectsReady = 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;
-                }, []);
-                // This component is the last sibling. Reaching its passive effect
-                // means the initial tree's useDebugProvider/useDebugCommand effects
-                // have registered, so mount() can truthfully back Play's ack.
-                useEffect(resolveEffectsReady, []);
-                return null;
-            }
-            // The React seam every dom root already has — `useWorldState`,
-            // `useDebugProvider`/`useDebugCommand`/`useDebugEmit`
-            // (`../react/world-state`) — works identically inside a canvas root
-            // because a canvas root IS React. `host.game` is genuinely absent in
-            // bare/foreign hosts, so the provider is conditional and those hooks
-            // stay the inert no-ops they already document themselves to be.
-            //
-            // READ FROM `host.game`, NEVER FROM `runtime` — the same rule, and the
-            // same reasoning, as the three lane's (`../world3d-react/r3f-adapter.tsx`,
-            // beside its own `const game = host.game`). The two providers answer
-            // different questions: `EngineBridge` rides `bridge` (the vgai runtime
-            // CONTEXT, which must not enter an ecosystem-native tree), `WorldProvider`
-            // rides the Game handle the host already holds. Keyed off `runtime`, a
-            // world mounted with `engineRuntime: false` gets no `WorldProvider` at
-            // all and every `useDebugProvider` in it no-ops IN SILENCE — no error, and
-            // `vgai eval 'await game.providers()'` lists only the built-ins. That is
-            // exactly what happened on the three lane. It has never fired here only
-            // because `pixi-react-root-factory.tsx` still leaves the runtime on;
-            // that flag is the tracked component-root migration's to flip, and this
-            // seam must not be waiting for it.
-            const game = host.game;
-            const world = createElement(Fragment, null, content, createElement(Lifecycle));
-            const provided = game ? createElement(WorldProvider, { game }, world) : world;
-            const element = bridge
-                ? createElement(EngineBridge.Provider, { value: bridge }, provided)
-                : provided;
-            const root = 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,
-            };
-            // 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;
-            const reconcileFailure = new Promise((resolve) => {
-                reportReconcileFailure = resolve;
-            });
-            const onError = (event) => {
-                reportReconcileFailure(`the Pixi tree crashed before its first commit — ${event.message} ` +
-                    '(mount() fails loudly instead of hanging)');
-            };
-            globalThis.addEventListener?.('error', onError);
-            let app;
-            let timer;
-            try {
-                // `root.render` is async: it awaits `Application.init()` (which is what
-                // creates the renderer) and only then hands the tree to the reconciler.
-                // A crash inside init rejects here, which is the loud failure we want.
-                const renderedApp = await root.render(element, initOptions);
-                app = renderedApp;
-                runtime?.setApplication(renderedApp);
-                // A reconcile-time crash (e.g. an un-extended component) surfaces as
-                // an uncaught window error and the first commit never lands. Race that
-                // exact signal against the commit and the last-resort ceiling.
-                const timeout = new Promise((resolve) => {
-                    timer = setTimeout(() => resolve(`no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
-                        '(mount() fails loudly instead of hanging)'), FIRST_COMMIT_TIMEOUT_MS);
-                });
-                const failure = await Promise.race([
-                    Promise.all([committed, effectsReady]).then(() => null),
-                    reconcileFailure,
-                    timeout,
-                ]);
-                if (failure !== null) {
-                    throw new Error(`createPixiReactAdapter: root "${id}" — ${failure}`);
-                }
-            }
-            catch (error) {
-                try {
-                    app?.destroy(false, { children: true });
-                }
-                catch {
-                    /* the world never fully came up; teardown failure must not mask why */
-                }
-                runtime?.dispose();
-                throw error;
-            }
-            finally {
-                if (timer !== undefined)
-                    clearTimeout(timer);
-                globalThis.removeEventListener?.('error', onError);
-            }
-            // `app` is assigned before the first-commit race. Reaching here proves
-            // both initialization and commit succeeded, so narrow once for the live
-            // mounted-root methods below.
-            if (app === undefined) {
-                runtime?.dispose();
-                throw new Error(`createPixiReactAdapter: root "${id}" initialized without an Application`);
-            }
-            const mountedApp = app;
-            // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
-            // without this the first `update()` would report a 1ms phantom delta on
-            // top of the real one. From here every `deltaMS` a `useTick` callback
-            // sees is exactly the `dt` the host handed us — no wall clock anywhere,
-            // which is what makes a paused world's resume frame ordinary rather than
-            // one giant catch-up step.
-            mountedApp.ticker.lastTime = 0;
-            let elapsedMs = 0;
-            let disposed = false;
-            const registry = host.game ? getDebugRegistry(host.game) : null;
-            const systemAdapters = runtime?.systemAdapters ?? (registry ? { debug: registry.adapter } : {});
-            const disposeComplete = unmounted.then(() => {
-                mountedApp.destroy(false, { children: true });
-            });
-            return {
-                kind: 'canvas',
-                // The reconciler's real root container — the same `PIXI.Container`
-                // `RootInstance.pixiStage()` hands the editor.
-                stage: mountedApp.stage,
-                drivesOwnLoop: false,
-                // Adapter surface: the host's shared debug registry. A native component
-                // tree registers nothing; its entry-module `debug` export is projected
-                // after mount by the shared native adapter.
-                systems: systemAdapters,
-                disposeComplete,
-                update(dt) {
-                    if (disposed)
-                        return;
-                    elapsedMs += dt * 1000;
-                    // The optional legacy runtime drains first when explicitly enabled;
-                    // the native path has none. The real Pixi ticker remains the one
-                    // scheduler `useTick` observes, and the host only gates/advances it.
-                    runtime?.systems.run(dt);
-                    mountedApp.ticker.update(elapsedMs);
-                },
-                resize(width, 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.
-                    mountedApp.renderer.resize(width, height);
-                },
-                dispose() {
-                    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);
-                    // Rendering `null` children is the only unmount path `@pixi/react`
-                    // exposes publicly (its `unmountRoot` helper is internal), and React
-                    // commits that deletion on its own schedule — NOT synchronously. So
-                    // the Application is destroyed on the `Lifecycle` cleanup signal
-                    // instead of inline: `useTick`'s cleanup calls `ticker.remove()`, and
-                    // a ticker destroyed before it lands throws inside React's commit.
-                    // `removeView` stays false — the canvas belongs to the HOST.
-                    void root.render(null, initOptions);
-                    runtime?.dispose();
-                },
-            };
-        },
-    };
-}