@vgai/engine 0.5.16 → 0.5.17

package/dist/world3d-react/r3f-adapter.js

@@ -28,10 +28,10 @@ import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { WorldProvider } from '../react/world-state';
 import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
 import { getDebugRegistry } from '../runtime/debug-registry';
-import { devLayersEnabled } from '../runtime/dev-layers';
+import { devBuildEnabled } from '../runtime/dev-build';
 import { EngineBridge } from './engine-bridge';
 import { applyWorldRendererConfig } from './renderer-config';
-import { createR3FRootContext } from './world-context';
+import { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from './world-context';
 /**
  * Scene depth for any soft-particle system this world mounted, drawn between
  * gameplay and the draw.
@@ -52,6 +52,11 @@ import { createR3FRootContext } from './world-context';
  * sort is stable) — the tie-break among priority-0 callbacks is insertion
  * order.
  *
+ * It is mounted only when THIS host carries a real WebGL context. The editor's
+ * design-time host deliberately reconciles the scene without one because the
+ * editor viewport owns the real renderer and camera; that viewport runs the
+ * same generic depth pass immediately before it presents the adopted scene.
+ *
  * Costs nothing while no soft-particle system is armed — see
  * `../render/soft-particle-depth.ts` for what "armed" means and what the pass
  * spends when it is.
@@ -127,10 +132,32 @@ export function createR3FAdapter(options) {
             // `ctx` rides the bridge so ordinary components can reach engine
             // services through `useGameContext()`.
             const bridge = runtime ? { ctx: runtime.ctx } : null;
+            const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
+            // THE HOST STILL WIRES THIS GAME'S INPUT WHEN THE WORLD TAKES NO CONTEXT.
+            //
+            // A default-exported world mounts with `engineRuntime: false` — no vgai
+            // runtime context enters its React tree, by design. That says nothing
+            // about the GAME-scoped input the host owns from the outside: the
+            // project's declared map, and this root's `game.input.*` seams on the
+            // debug registry. Skipping those made a fresh scaffold's bot/autoplay/
+            // `vgai eval` input doors throw `DEBUG_INPUT_UNAVAILABLE` and left the
+            // declared actions unloaded — in the ONE world shape `vgai create`
+            // produces. Same host-vs-context split as `WorldProvider` below.
+            //
+            // `inputMapPath` unset (what the default-export factory passes) means
+            // "the conventional path, if this project ships one" — quiet when it
+            // does not, since a brand-new project declares no actions yet.
+            const hostInputReady = runtime || !gameDebugRegistry
+                ? null
+                : wireGameInputSeams(host, gameDebugRegistry, {
+                    id,
+                    inputMapPath: inputMapPath ?? DEFAULT_INPUT_MAP_PATH,
+                    optionalInputMap: inputMapPath === undefined,
+                });
             // Actions must exist before any component's init()/first frame reads
             // them — wait for the (never-rejecting) input-map load before the first
             // commit.
-            await runtime?.inputMapReady;
+            await (runtime?.inputMapReady ?? hostInputReady);
             // The world's own colour pipeline. Applied AFTER `root.configure()` below — see the comment
             // at its call site for why "before" is the version that silently does nothing.
             let restoreRendererConfig = () => { };
@@ -257,13 +284,37 @@ export function createR3FAdapter(options) {
             // until this landed. `host.game` is genuinely absent in bare/headless
             // hosts, so the provider is conditional and those hooks stay the inert
             // no-ops they already document themselves to be.
-            const game = runtime?.ctx.game;
+            //
+            // READ FROM `host.game`, NEVER FROM `runtime` — the two are not the same
+            // question, and conflating them silently dark-ended the seam for every
+            // scaffolded game. The IDIOMATIC three world (`export default function
+            // World()`) mounts through `resolveR3FEntryAdapter` with
+            // `engineRuntime: false` (`r3f-root-factory.tsx`), so it has no
+            // `runtime` and no `bridge` — by design, because the vgai runtime
+            // CONTEXT (`useGameContext`) must not enter an ecosystem-native tree.
+            // `WorldProvider` is not that context: it carries the Game handle the
+            // host already holds, and it is the only way a game's own
+            // `useDebugProvider('stat', …)` can reach the ONE game-scoped registry
+            // the editor/`vgai eval` read. Keyed off `runtime`, every
+            // default-exported world's registrations no-opped in silence and
+            // `vgai eval 'await game.providers()'` listed only the built-ins.
+            // The canvas lane never had the gap (`canvas-react/
+            // pixi-react-root-factory.tsx` keeps its entry runtime on).
+            const game = host.game;
             // `SoftParticleDepth` trails the world's own tree deliberately — see its
-            // docblock for why the subscription must land last.
-            const world = createElement(Fragment, null, content, runtime ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }) : null, createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }));
-            root.render(bridge
-                ? createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, world) : world)
-                : world);
+            // docblock for why the subscription must land last. A no-context design
+            // mount omits this fiber callback because the adopting editor viewport
+            // runs the pass with its own renderer and camera instead.
+            const world = createElement(Fragment, null, content, runtime && typeof host.renderer.getContext === 'function'
+                ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' })
+                : null, createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }));
+            // The two providers are INDEPENDENT: `EngineBridge` rides `bridge` (the
+            // vgai runtime context, absent for a native default-exported world),
+            // `WorldProvider` rides `host.game` (the React seam, present whenever a
+            // Game hosts this world). Nesting the second inside the first is what
+            // made the seam a hostage of the first.
+            const provided = game ? createElement(WorldProvider, { game }, world) : world;
+            root.render(bridge ? createElement(EngineBridge.Provider, { value: bridge }, provided) : provided);
             // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
             // surfaces as an uncaught window error and `onCreated` never fires —
             // without this guard, `mount()` would await `statePromise` FOREVER and
@@ -274,6 +325,8 @@ export function createR3FAdapter(options) {
                     cleanup();
                     root.unmount();
                     runtime?.dispose();
+                    if (!runtime)
+                        gameDebugRegistry?.strip(id);
                     restoreRendererConfig();
                     reject(new Error(`r3f-adapter: fiber crashed before its first commit — ${event.message} ` +
                         '(mount() fails loudly instead of hanging on onCreated)'));
@@ -282,6 +335,8 @@ export function createR3FAdapter(options) {
                     cleanup();
                     root.unmount();
                     runtime?.dispose();
+                    if (!runtime)
+                        gameDebugRegistry?.strip(id);
                     restoreRendererConfig();
                     reject(new Error('r3f-adapter: onCreated did not fire within 10s — the R3F tree never reached ' +
                         'its first commit (mount() fails loudly instead of hanging)'));
@@ -334,7 +389,6 @@ export function createR3FAdapter(options) {
             // `RootState` for precisely this reason, so reading it per frame is the
             // supported way to see the live root. It is a plain map read.
             const live = () => state.get();
-            const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
             // --- Live render vitals (issue #1504), for an R3F world -----------------
             // The SAME door the classic adapter seeds
             // (`../adapter/setup-three-root-adapter.ts`), seeded here for the same
@@ -345,11 +399,11 @@ export function createR3FAdapter(options) {
             // world is the only shape a scaffolded project's three root has, so a
             // door wired only into the classic path is a door no scaffolded project
             // ever gets (issue #1518: `game.state('render.vitals')` answered "no
-            // state provider registered" in the field while every other dev layer of
-            // the same world worked).
+            // state provider registered" in the field while every other debug
+            // reading of the same world worked).
             //
             // The gate is the same three conditions, minus the one that cannot
-            // arise: `devLayersEnabled()` (`../runtime/dev-layers.ts`, the ONE owner
+            // arise: `devBuildEnabled()` (`../runtime/dev-build.ts`, the ONE owner
             // of "is this a dev context" — a ship build registers nothing and pays
             // nothing), and a `Game` shell (the readings are folded out of that
             // game's profiler frames). "Not headless" needs no term here: a headless
@@ -367,7 +421,7 @@ export function createR3FAdapter(options) {
             // (the fold) and `runtime.dispose()`'s scoped `strip(id)` (the
             // registrations) — the same split the classic adapter documents.
             let renderVitals = null;
-            if (host.game && devLayersEnabled()) {
+            if (host.game && devBuildEnabled()) {
                 // Same auto-enable as the classic adapter: the readings are folded out
                 // of profiler frames, and the profiler is a flag the editor already
                 // sets on play — under the dev gate this is the same cost arriving a
@@ -551,6 +605,27 @@ export function createR3FAdapter(options) {
                     renderVitals?.dispose();
                     renderVitals = null;
                     runtime?.dispose();
+                    // The no-context path has no `runtime.dispose()` to carry its scoped
+                    // strip, so it ends its own registrations here — the same
+                    // `strip(id)`, at the same moment. That is what ends this world's
+                    // PROVIDERS AND COMMANDS (the render-vitals door above is the one
+                    // this path actually registers under `id`); sibling roots are
+                    // untouched.
+                    //
+                    // It does NOT end the input seams `wireGameInputSeams` set, and
+                    // nothing else does either: `strip` walks providers/commands only
+                    // (`runtime/debug-registry.ts`), so `virtualInputTargets`/
+                    // `inputActionsSources`/`inputTraceSources` keep this world's id
+                    // until a remount of the same id overwrites it. The runtime path has
+                    // always been identical, and the residue is inert rather than
+                    // hidden: every one of those closures reads GAME-scoped state
+                    // (`game.input`, `game.loop.fixedDt`, the game's seed), so a stale
+                    // entry actuates exactly what a live one would. What it can still do
+                    // is name a dead world in `DEBUG_INPUT_WORLD_NOT_FOUND`'s registered
+                    // list. Do not write "the strip clears the input seams" here again
+                    // without changing `strip` to actually do it.
+                    if (!runtime)
+                        gameDebugRegistry?.strip(id);
                     restoreRendererConfig();
                 },
             };

package/dist/world3d-react/r3f-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAc/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAwB/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}

package/dist/world3d-react/r3f-root-factory.js

@@ -60,8 +60,18 @@ export function resolveR3FEntryAdapter(entryModule, rootId) {
             id: rootId,
             content: createElement(mod.default),
             // A default-exported R3F component is an ordinary R3F app. The host
-            // controls Fiber's native `frameloop: 'never'` scheduler; vgai runtime
-            // context, systems and state providers never enter its React tree.
+            // controls Fiber's native `frameloop: 'never'` scheduler; the vgai
+            // runtime CONTEXT (`useGameContext`, `ctx.systems`) never enters its
+            // React tree.
+            //
+            // This flag governs that context and nothing else. It does NOT govern
+            // `WorldProvider`: `useDebugProvider`/`useDebugCommand`/`useWorldState`
+            // are the documented door a game declares its own state/commands
+            // through, and they must work in the idiomatic shape — which is the
+            // ONLY shape `vgai create` scaffolds. `r3f-adapter.tsx` therefore keys
+            // that provider off `host.game`, not off this flag; see the comment
+            // beside `const game = host.game` there for the measured symptom
+            // (`vgai eval 'await game.providers()'` listing only built-ins).
             engineRuntime: false,
         });
     }

package/dist/world3d-react/rapier-physics-bridge.d.ts

@@ -3,7 +3,7 @@
  * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
- * coordination (`freeze → apply → unfreeze`) and the dev menu's universal
+ * coordination (`freeze → apply → unfreeze`) and the universal
  * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
  * first-party imperative three root registers one from
  * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
@@ -44,7 +44,7 @@
  * on the R3F root it is mounted in. It allocates nothing else — no timers, no
  * subscriptions, no per-frame work (see the phase note below), and no Rapier
  * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the dev menu's
+ * SHARERS: every reader of `game.systemAdapters.physics` — the
  * colliders instrument, the editor's transform coordination. They read; they
  * never dispose.
  * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
@@ -55,13 +55,13 @@
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
- * BETWEEN frames, by an editor gesture or a dev-menu command, never from a
+ * BETWEEN frames, by an editor gesture or an instrument command, never from a
  * phase.
  */
 export interface RapierPhysicsBridgeProps {
     /**
      * Set the `debug` prop of the SAME `<Physics>` this bridge is mounted in.
-     * The dev menu's "Colliders drawn" toggle calls it; the world's own state is
+     * The "Colliders drawn" instrument calls it; the world's own state is
      * what `<Physics debug={…}>` reads, so the library's debug rendering is the
      * only thing that ever draws a collider.
      */

package/dist/world3d-react/rapier-physics-bridge.js

@@ -3,7 +3,7 @@
  * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
- * coordination (`freeze → apply → unfreeze`) and the dev menu's universal
+ * coordination (`freeze → apply → unfreeze`) and the universal
  * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
  * first-party imperative three root registers one from
  * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
@@ -44,7 +44,7 @@
  * on the R3F root it is mounted in. It allocates nothing else — no timers, no
  * subscriptions, no per-frame work (see the phase note below), and no Rapier
  * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the dev menu's
+ * SHARERS: every reader of `game.systemAdapters.physics` — the
  * colliders instrument, the editor's transform coordination. They read; they
  * never dispose.
  * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
@@ -55,7 +55,7 @@
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
- * BETWEEN frames, by an editor gesture or a dev-menu command, never from a
+ * BETWEEN frames, by an editor gesture or an instrument command, never from a
  * phase.
  */
 import { useRapier } from '@react-three/rapier';

package/dist/world3d-react/world-context.d.ts

@@ -128,6 +128,49 @@ export interface R3FRootRuntime {
      *  react-door registrations are untouched when a Game hosts this world). */
     dispose(): void;
 }
+/**
+ * The GAME-SCOPED input wiring one three root owns — and the half that has
+ * nothing to do with the vgai runtime context.
+ *
+ * Two things happen here, both of them HOST work performed from outside the
+ * world's own tree:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * It is called on BOTH three-root paths, and that is the point: a world that
+ * mounts as a default-exported component receives no vgai runtime context
+ * (`engineRuntime: false` — see `r3f-root-factory.tsx`), but "no context in the
+ * tree" was never meant to say "the host does not wire this game's input". It
+ * was read that way, and the cost was measured on a fresh scaffold: the
+ * declared map never loaded and every `game.input.*` door threw, so the QA
+ * bot, autoplay routes and `vgai eval` could not drive the ONE world shape
+ * `vgai create` produces. Same split, same reasoning, as `WorldProvider`
+ * riding `host.game` rather than the runtime (see `r3f-adapter.tsx`).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose (both
+ * paths), but it walks providers/commands only — the three seams set here
+ * survive it, keyed by this world's id, until a remount of the same id
+ * overwrites them. That residue is inert rather than hidden: every closure
+ * below reads GAME-scoped state (`game.input`, `game.loop.fixedDt`, the game's
+ * seed), so a stale entry actuates exactly what a live one would. See the
+ * dispose comment in `r3f-adapter.tsx` for the full accounting.
+ */
+export declare function wireGameInputSeams(host: ThreeHostContext, registry: DebugRegistry, options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+}): Promise<void>;
 /**
  * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
  * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`

package/dist/world3d-react/world-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE1E;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAC/C,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC,GAAG;IAC/D,qEAAqE;IACrE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;CACtB,CAAC;AAEJ,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;;mFAE+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;yDAMqD;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAqJhB"}
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE1E;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAC/C,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC,GAAG;IAC/D,qEAAqE;IACrE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;CACtB,CAAC;AAEJ,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;;mFAE+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;yDAMqD;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjD,GACA,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAqGhB"}

package/dist/world3d-react/world-context.js

@@ -43,6 +43,92 @@ import { disposeDebrisSubtree } from '../runtime/game';
 /** The classic adapter's default input-map path — the conventional location
  *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
 export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+/**
+ * The GAME-SCOPED input wiring one three root owns — and the half that has
+ * nothing to do with the vgai runtime context.
+ *
+ * Two things happen here, both of them HOST work performed from outside the
+ * world's own tree:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * It is called on BOTH three-root paths, and that is the point: a world that
+ * mounts as a default-exported component receives no vgai runtime context
+ * (`engineRuntime: false` — see `r3f-root-factory.tsx`), but "no context in the
+ * tree" was never meant to say "the host does not wire this game's input". It
+ * was read that way, and the cost was measured on a fresh scaffold: the
+ * declared map never loaded and every `game.input.*` door threw, so the QA
+ * bot, autoplay routes and `vgai eval` could not drive the ONE world shape
+ * `vgai create` produces. Same split, same reasoning, as `WorldProvider`
+ * riding `host.game` rather than the runtime (see `r3f-adapter.tsx`).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose (both
+ * paths), but it walks providers/commands only — the three seams set here
+ * survive it, keyed by this world's id, until a remount of the same id
+ * overwrites them. That residue is inert rather than hidden: every closure
+ * below reads GAME-scoped state (`game.input`, `game.loop.fixedDt`, the game's
+ * seed), so a stale entry actuates exactly what a live one would. See the
+ * dispose comment in `r3f-adapter.tsx` for the full accounting.
+ */
+export function wireGameInputSeams(host, registry, options) {
+    const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH, optionalInputMap = false } = options;
+    if (!host.game)
+        return Promise.resolve();
+    const game = host.game;
+    const input = game.input;
+    registry.setInputActionsSource(id, () => input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })));
+    registry.setInputTraceSource(id, () => {
+        const raw = input.getInputTrace();
+        return {
+            version: raw.version,
+            seed: getSeededRandom(game)?.seed ?? null,
+            fixedDt: game.loop.fixedDt,
+            ticks: raw.ticks,
+        };
+    });
+    registry.setVirtualInputTarget(id, {
+        setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+        tapVirtualAction: (action) => input.tapVirtualAction(action),
+        clearVirtualActions: () => input.clearVirtualActions(),
+        scheduleActionAtTick: (tick, action, value) => input.scheduleActionAtTick(tick, action, value),
+        startInputRecording: () => input.startInputRecording(),
+        stopInputRecording: () => input.stopInputRecording(),
+        isInputRecording: () => input.isInputRecording(),
+        injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+        injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+        injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+        injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+    });
+    if (host.headless || inputMapPath === null)
+        return Promise.resolve();
+    // Load-once through the game-owned path (competing paths across roots throw
+    // THERE, loudly). A FAILED load (missing/bad file) must not fail the mount:
+    // a three world with no declared actions is legal. It degrades loudly
+    // instead — naming exactly what breaks.
+    // The non-optional call passes ONE argument, exactly as it always has — a
+    // trailing `undefined` is a different call to any observer of it.
+    const load = optionalInputMap
+        ? game.loadInputMap(inputMapPath, { optional: true })
+        : game.loadInputMap(inputMapPath);
+    return load.catch((err) => {
+        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+        console.error(`three world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+            'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+            'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+            `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
 /**
  * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
  * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
@@ -101,52 +187,9 @@ export function createR3FRootContext(host, options) {
     const gameClock = host.game ? getSimClock(host.game) : null;
     const clock = gameClock ?? createSimClock({ dispose: (obj) => disposeDebrisSubtree(obj, []) });
     ctx.clock = clock;
-    // --- ctx.input + the debug-registry input seams (gap 3) — the game-owned
-    // InputManager, polled by the game-scoped runner each frame; this world
-    // registers the SAME per-world seams the classic adapter registers so
-    // `game.input.*` (virtual input) and the built-in `input.actions`/
-    // `input.trace` providers resolve to it. ---
-    let inputMapReady = Promise.resolve();
-    if (host.game) {
-        const game = host.game;
-        const input = game.input;
-        debugRegistry.setInputActionsSource(id, () => input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })));
-        debugRegistry.setInputTraceSource(id, () => {
-            const raw = input.getInputTrace();
-            return {
-                version: raw.version,
-                seed: getSeededRandom(game)?.seed ?? null,
-                fixedDt: game.loop.fixedDt,
-                ticks: raw.ticks,
-            };
-        });
-        debugRegistry.setVirtualInputTarget(id, {
-            setVirtualAction: (action, value) => input.setVirtualAction(action, value),
-            tapVirtualAction: (action) => input.tapVirtualAction(action),
-            clearVirtualActions: () => input.clearVirtualActions(),
-            scheduleActionAtTick: (tick, action, value) => input.scheduleActionAtTick(tick, action, value),
-            startInputRecording: () => input.startInputRecording(),
-            stopInputRecording: () => input.stopInputRecording(),
-            isInputRecording: () => input.isInputRecording(),
-            injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
-            injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
-            injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
-            injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
-        });
-        if (!host.headless && inputMapPath !== null) {
-            // Load-once through the game-owned path (classic parity — competing
-            // paths across roots throw THERE, loudly). A FAILED load (missing/bad
-            // file) must not fail this mount: an R3F tree with no declared actions
-            // is legal. It degrades loudly instead — naming exactly what breaks.
-            inputMapReady = game.loadInputMap(inputMapPath).catch((err) => {
-                // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
-                console.error(`R3F world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
-                    'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
-                    'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
-                    `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`);
-            });
-        }
-    }
+    // --- ctx.input + the debug-registry input seams (gap 3) — see
+    // `wireGameInputSeams` below; `ctx.input` is that same game-owned manager. ---
+    const inputMapReady = wireGameInputSeams(host, debugRegistry, { id, inputMapPath });
     return {
         ctx,
         systems,