@vgai/engine 0.5.15 → 0.5.17

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

@@ -18,7 +18,7 @@
  * project guarantees via its Vite `resolve.dedupe: ['three', 'react',
  * 'react-dom']` (see `examples/r3f-first-party/vite.config.ts`).
  */
-import { advance, createRoot, extend, events as pointerEvents, useFrame, } from '@react-three/fiber';
+import { advance, createRoot, extend, flushSync, events as pointerEvents, useFrame, } from '@react-three/fiber';
 import { createElement, Fragment, useEffect, useMemo } from 'react';
 import { registerRenderVitals } from '../dev/register-render-vitals';
 import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
@@ -27,10 +27,11 @@ import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { WorldProvider } from '../react/world-state';
 import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
-import { devLayersEnabled } from '../runtime/dev-layers';
+import { getDebugRegistry } from '../runtime/debug-registry';
+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.
@@ -51,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.
@@ -68,7 +74,7 @@ function SoftParticleDepth() {
  * second `requestAnimationFrame` loop (design §1.C).
  */
 export function createR3FAdapter(options) {
-    const { id, content, inputMapPath, renderer: rendererConfig } = options;
+    const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
     return {
         id,
         async mount(host) {
@@ -122,15 +128,36 @@ export function createR3FAdapter(options) {
             // for one is a compile error rather than anything that can happen at
             // runtime. `scene`/`camera` are backfilled right after fiber's first
             // commit resolves them, before any tick can run.
-            const runtime = createR3FRootContext(host, { id, inputMapPath });
-            const { systems } = runtime;
+            const runtime = engineRuntime ? createR3FRootContext(host, { id, inputMapPath }) : null;
             // `ctx` rides the bridge so ordinary components can reach engine
             // services through `useGameContext()`.
-            const bridge = { ctx: runtime.ctx };
+            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 = () => { };
@@ -147,6 +174,19 @@ export function createR3FAdapter(options) {
             const statePromise = new Promise((resolve) => {
                 resolveState = resolve;
             });
+            let resolveEffectsReady;
+            const effectsReady = new Promise((resolve) => {
+                resolveEffectsReady = resolve;
+            });
+            // Rendered after the game's content. React runs passive effects in tree
+            // order, so when this fires every useDebugProvider/useDebugCommand in
+            // the initial tree has registered. A Play acknowledgement is a claim
+            // that the mounted game's command surface exists, not merely that Fiber
+            // allocated a scene.
+            function MountEffectsReady() {
+                useEffect(resolveEffectsReady, []);
+                return null;
+            }
             // `root.configure()` is ASYNC in fiber v9 (`Promise<ReconcilerRoot>`)
             // — the design doc's §1.C sketch shows it called synchronously; the
             // real v9 API (verified against
@@ -244,11 +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, createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }));
-            root.render(createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, 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
@@ -258,7 +324,9 @@ export function createR3FAdapter(options) {
                 const onError = (event) => {
                     cleanup();
                     root.unmount();
-                    runtime.dispose();
+                    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)'));
@@ -266,7 +334,9 @@ export function createR3FAdapter(options) {
                 const timer = setTimeout(() => {
                     cleanup();
                     root.unmount();
-                    runtime.dispose();
+                    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)'));
@@ -276,7 +346,7 @@ export function createR3FAdapter(options) {
                     window.removeEventListener('error', onError);
                 };
                 window.addEventListener('error', onError);
-                void statePromise.then((s) => {
+                void Promise.all([statePromise, effectsReady]).then(([s]) => {
                     cleanup();
                     resolve(s);
                 });
@@ -294,7 +364,7 @@ export function createR3FAdapter(options) {
             // Backfill the component runtime's ctx with fiber's real scene/camera
             // (W3 — see the HONESTY NOTE above). This happens before the first
             // `update(dt)` tick, so no component ever observes them missing.
-            runtime.setSceneCamera(state.scene, state.camera);
+            runtime?.setSceneCamera(state.scene, state.camera);
             // THE STORE IS THE TRUTH, NOT THE `onCreated` SNAPSHOT.
             //
             // `state` is one immutable zustand snapshot: fiber's store is
@@ -329,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
@@ -351,14 +421,17 @@ 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
                 // little earlier, not a new one.
                 host.game.profiler.enabled = true;
+                if (!gameDebugRegistry) {
+                    throw new Error('r3f-adapter: mounted Game has no debug registry.');
+                }
                 renderVitals = registerRenderVitals({
-                    registry: runtime.debugRegistry,
+                    registry: gameDebugRegistry,
                     worldId: id,
                     profiler: host.game.profiler,
                     scene: live().scene,
@@ -382,8 +455,12 @@ export function createR3FAdapter(options) {
                     memory: () => collectRenderMemory(live().scene, host.renderer.info),
                 })
                 : null;
+            // The session debug registry is host instrumentation, not component
+            // context. Publishing the existing adapter here lets coverage and
+            // editor panels see the same door without wrapping the R3F tree.
+            const systemAdapters = runtime?.systemAdapters ?? (gameDebugRegistry ? { debug: gameDebugRegistry.adapter } : {});
             if (renderDebugWiring)
-                runtime.systemAdapters.renderDebug = renderDebugWiring.adapter;
+                systemAdapters.renderDebug = renderDebugWiring.adapter;
             // The engine drives every `useFrame` through the mounted world's
             // `update(dt)` hook, never off a raw host-loop callback. That is the
             // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
@@ -411,7 +488,7 @@ export function createR3FAdapter(options) {
             // resumed frame as one giant `useFrame` delta — the exact "time passed
             // while frozen" illusion acceptance gate 2 forbids.
             let elapsed = 0;
-            /** The camera `ctx` was last backfilled with — see `update()`. */
+            /** The legacy component ctx camera last backfilled by `update()`. */
             let backfilledCamera = state.camera;
             return {
                 kind: 'three',
@@ -444,7 +521,7 @@ export function createR3FAdapter(options) {
                 // WebGL2 context exists, `renderDebug` are engine-seeded. Game code
                 // adds its own capabilities via `ctx.registerSystemAdapter` exactly
                 // as in a classic world.
-                systems: runtime.systemAdapters,
+                systems: systemAdapters,
                 update(dt) {
                     elapsed += dt;
                     const current = live();
@@ -453,14 +530,14 @@ export function createR3FAdapter(options) {
                     // component reading one while the frame uses the other is the
                     // silent kind of wrong. Identity-gated, so this is one comparison
                     // per frame in the overwhelmingly common no-swap case.
-                    if (current.camera !== backfilledCamera) {
+                    if (runtime && current.camera !== backfilledCamera) {
                         backfilledCamera = current.camera;
                         runtime.setSceneCamera(current.scene, current.camera);
                     }
                     // Engine phases FIRST (registered systems mutate transforms),
                     // then fiber's advance (useFrame callbacks + the actual render see
                     // the fresh state). Both are host-gated: neither runs while frozen.
-                    systems.run(dt);
+                    runtime?.systems.run(dt);
                     renderDebugWiring?.beforeRender();
                     try {
                         const profiler = host.game?.profiler;
@@ -513,7 +590,13 @@ export function createR3FAdapter(options) {
                     // Reject/restore a pending capture while its renderables still
                     // exist, then unmount component effects and strip runtime state.
                     renderDebugWiring?.dispose();
-                    root.unmount();
+                    // The editor audits and disposes the mounted game's window/document realm immediately
+                    // after `session.stop()`. Fiber's ordinary `unmount()` submits a concurrent reconciler
+                    // update, so component effect cleanups could still be pending at that boundary and the
+                    // audit would truthfully report/reclaim listeners the world was about to remove itself.
+                    // Force the unmount COMMIT (not fiber's deliberately delayed renderer/context disposal)
+                    // to finish here: a stopped root owns no live component lifecycle beyond this method.
+                    flushSync(() => root.unmount());
                     // The vitals fold owns two `profiler.subscribe` registrations, and
                     // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —
                     // this is the one path that ends the subscriptions, exactly as the
@@ -521,7 +604,28 @@ export function createR3FAdapter(options) {
                     // subscription can never outlive the door it feeds.
                     renderVitals?.dispose();
                     renderVitals = null;
-                    runtime.dispose();
+                    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,CAU/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

@@ -59,6 +59,20 @@ export function resolveR3FEntryAdapter(entryModule, rootId) {
         return createR3FAdapter({
             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; 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,
         });
     }
     return null;

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

@@ -13,12 +13,15 @@
  *     `ctx.debug = registry.forRoot(id)`, so a component's
  *     effect can `ctx.debug.registerStateProvider(...)` and be visible
  *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` —
  *     the same instance the classic adapter uses when hosted), and this
  *     module registers the SAME per-world debug-registry seams the classic
  *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
  *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
  *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     A bare/foreign mount receives `null`, visibly in the type, rather than
+ *     a getter that throws later inside a frame callback.
  *     The project's input map is loaded through `Game.loadInputMap` (the
  *     game-owned, load-once path every root shares) with the SAME default
  *     path the classic adapter uses. A missing/unparseable map degrades
@@ -36,7 +39,7 @@ import type { ThreeHostContext } from '../adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import { createSystemRunner } from '../core/system-runner';
 import { type DebugRegistry } from '../runtime/debug-registry';
-import type { GameContext } from '../runtime/types';
+import type { ComponentContextBase, GameContext } from '../runtime/types';
 /** The classic adapter's default input-map path — the conventional location
  *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
 export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json";
@@ -75,7 +78,10 @@ export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json"
  * exporting `setup(ctx): Promise<GameCleanup>`, which `SetupThreeRootAdapter`
  * mounts with the complete {@link GameContext}.
  */
-export type R3FGameContext = Pick<GameContext, 'scene' | 'camera' | 'sceneIndex' | 'input' | 'assets' | 'systems' | 'clock' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'>;
+export type R3FGameContext = ComponentContextBase & Pick<GameContext, 'scene' | 'sceneIndex' | 'assets' | 'clock'> & {
+    /** Fiber may install either a perspective or orthographic camera. */
+    camera: THREE.Camera;
+};
 export interface R3FRootContextOptions {
     /** World id — provenance for every debug-registry registration (matches the
      *  manifest root id by the same convention the classic adapter follows). */
@@ -122,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCK;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,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,WAAW,EACT,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,uBAAuB,CAC1B,CAAC;AAEF,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,CAsKhB"}
+{"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"}