@vgai/engine 0.5.15 → 0.5.17

package/src/world3d-react/index.ts

@@ -33,7 +33,7 @@
  * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
  * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
  * world's `@react-three/rapier` physics as the game's
- * `SystemAdapters.physics` — so the dev menu's colliders instrument and the
+ * `SystemAdapters.physics` — so the colliders instrument and the
  * editor's transform coordination can see it. It imports
  * `@react-three/rapier`, and only a world that already depends on that library
  * should pull it into its graph; a deep import keeps this barrel's peer

package/src/world3d-react/r3f-adapter.tsx

@@ -23,12 +23,14 @@ import {
   advance,
   createRoot,
   extend,
+  flushSync,
   events as pointerEvents,
   type RootState,
   useFrame,
 } from '@react-three/fiber';
 import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
   createRenderDebugAdapter,
@@ -40,10 +42,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, type EngineBridgeValue } from './engine-bridge';
 import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
-import { createR3FRootContext } from './world-context';
+import { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from './world-context';
 
 /** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
  *  structurally rather than imported from `three`, per this module's own
@@ -74,6 +77,11 @@ interface RendererCounters {
  * 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.
@@ -99,6 +107,13 @@ export interface CreateR3FAdapterOptions {
    *  actions). A missing/invalid map degrades loudly without failing the
    *  mount — see `world-context.ts`. */
   readonly inputMapPath?: string | null | undefined;
+  /**
+   * Transitional compatibility for explicit pre-native adapters. The
+   * default-export root factory always passes `false`: ordinary R3F trees get
+   * no vgai context/provider or private scheduler. Remove this switch with
+   * the last explicit legacy adapter migration.
+   */
+  readonly engineRuntime?: boolean | undefined;
   /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
    *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
    *  defaults; declare it when the world's colours were picked against a different engine's
@@ -113,7 +128,7 @@ export interface CreateR3FAdapterOptions {
  * second `requestAnimationFrame` loop (design §1.C).
  */
 export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter {
-  const { id, content, inputMapPath, renderer: rendererConfig } = options;
+  const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
 
   return {
     id,
@@ -171,15 +186,37 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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: EngineBridgeValue = { ctx: runtime.ctx };
+      const bridge: EngineBridgeValue | null = 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.
@@ -199,6 +236,19 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       const statePromise = new Promise<RootState>((resolve) => {
         resolveState = resolve;
       });
+      let resolveEffectsReady!: () => void;
+      const effectsReady = new Promise<void>((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(): null {
+        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
@@ -298,21 +348,44 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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.
+      // 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,
-        createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }),
+        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(
-        createElement(
-          EngineBridge.Provider,
-          { value: bridge },
-          game ? createElement(WorldProvider, { game }, world) : world,
-        ),
+        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 —
@@ -323,7 +396,8 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         const onError = (event: ErrorEvent) => {
           cleanup();
           root.unmount();
-          runtime.dispose();
+          runtime?.dispose();
+          if (!runtime) gameDebugRegistry?.strip(id);
           restoreRendererConfig();
           reject(
             new Error(
@@ -335,7 +409,8 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         const timer = setTimeout(() => {
           cleanup();
           root.unmount();
-          runtime.dispose();
+          runtime?.dispose();
+          if (!runtime) gameDebugRegistry?.strip(id);
           restoreRendererConfig();
           reject(
             new Error(
@@ -349,7 +424,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           window.removeEventListener('error', onError);
         };
         window.addEventListener('error', onError);
-        void statePromise.then((s) => {
+        void Promise.all([statePromise, effectsReady]).then(([s]) => {
           cleanup();
           resolve(s);
         });
@@ -369,7 +444,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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.
       //
@@ -406,11 +481,11 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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
@@ -428,14 +503,17 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // (the fold) and `runtime.dispose()`'s scoped `strip(id)` (the
       // registrations) — the same split the classic adapter documents.
       let renderVitals: RenderVitalsRegistration | null = 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,
@@ -461,7 +539,12 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
             memory: () => collectRenderMemory(live().scene, host.renderer.info),
           })
         : null;
-      if (renderDebugWiring) runtime.systemAdapters.renderDebug = renderDebugWiring.adapter;
+      // 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: SystemAdapters =
+        runtime?.systemAdapters ?? (gameDebugRegistry ? { debug: gameDebugRegistry.adapter } : {});
+      if (renderDebugWiring) 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
@@ -490,7 +573,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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 {
@@ -524,7 +607,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         // 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: number): void {
           elapsed += dt;
           const current = live();
@@ -533,14 +616,14 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // 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;
@@ -591,7 +674,13 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // 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
@@ -599,7 +688,27 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // 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/src/world3d-react/r3f-root-factory.tsx

@@ -69,6 +69,20 @@ export function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): Ro
     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/src/world3d-react/rapier-physics-bridge.tsx

@@ -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.
  */
 
@@ -78,7 +78,7 @@ import { useGameContext } from './engine-bridge';
 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/src/world3d-react/world-context.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
@@ -49,7 +52,7 @@ import {
   getDebugRegistry,
 } from '../runtime/debug-registry';
 import { disposeDebrisSubtree } from '../runtime/game';
-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`). */
@@ -90,22 +93,11 @@ export 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
@@ -155,6 +147,103 @@ export interface R3FRootRuntime {
   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 function wireGameInputSeams(
+  host: ThreeHostContext,
+  registry: DebugRegistry,
+  options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+  },
+): Promise<void> {
+  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: unknown) => {
+    // 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()`
@@ -185,6 +274,7 @@ export function createR3FRootContext(
   const ctxRaw: Record<string, unknown> = {
     systems,
     assets: host.assets,
+    input: host.game?.input ?? null,
     registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
       // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the classic adapter performs; correct by construction
       (systemAdapters as any)[kind] = adapter;
@@ -223,75 +313,9 @@ export function createR3FRootContext(
     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<void> = Promise.resolve();
-  if (host.game) {
-    const game = host.game;
-    const input = game.input;
-    ctxRaw['input'] = 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: unknown) => {
-        // 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)}`,
-        );
-      });
-    }
-  } else {
-    // `input` IS a field of every R3F world's ctx — it is game-owned, and this
-    // particular mount has no Game to own it (a bare harness or a foreign
-    // host). A throwing getter names that at the read, instead of handing back
-    // `undefined` that breaks deep inside a frame callback. Non-enumerable so
-    // spreads/serialization of the ctx never trip it.
-    Object.defineProperty(ctxRaw, 'input', {
-      configurable: true,
-      enumerable: false,
-      get(): never {
-        throw new Error(
-          `R3F world "${id}": ctx.input is game-owned and this mount has no Game host ` +
-            '(host.game is absent — bare harness/foreign host); mount through the vgai host ' +
-            'to get the shared InputManager.',
-        );
-      },
-    });
-  }
+  // --- 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,