@vgai/engine 0.5.16 → 0.5.18

package/src/runtime/create-runtime.ts

@@ -149,22 +149,6 @@ export interface RootMountSpecBase {
   readonly zOrder?: number | undefined;
   /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
   readonly pausable?: boolean | undefined;
-  /**
-   * `vgai.project.json`'s `dev: true` — this root is a DEV LAYER (the game's
-   * own dev GUI), not shipped game content. Two things happen here: the
-   * surface is stacked ABOVE every non-dev root (a dev layer sits topmost),
-   * and it is marked `data-vgai-dev-layer="true"` so the play compositor can
-   * leave it out of a capture (`composite-screenshot.ts`). Whether a dev root
-   * reaches this function at all is the CALLER's gate —
-   * `mountManifestRoots` asks `devLayersEnabled()` before building the spec.
-   *
-   * It steals no input from the game while closed for a reason that predates
-   * this flag and needs no new mechanism: a dev layer is a `dom` root, DOM
-   * layers are `pointer-events:none` (see `mountOneReactRoot`) with the
-   * mounted tree opting individual elements back in, and the input router
-   * never sees DOM roots at all.
-   */
-  readonly dev?: boolean | undefined;
   /**
    * Optional claim predicate for the delegating input router (D5 §2a), over
    * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
@@ -328,6 +312,8 @@ export interface RootsRuntimeConfig {
  */
 export interface GameSession {
   stop(): void;
+  /** Resolves after every root has finished the cleanup initiated by stop(). */
+  readonly stopComplete: Promise<void>;
   pause(): void;
   resume(): void;
   step(): void;
@@ -776,22 +762,12 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   // DOM-root layer shares this SAME stacking pass even though it is a `<div>`, not a
   // canvas, and carries no `hitTest` (the router never sees react entries at
   // all — see the dispatch loop below). ---
-  // Dev layers sit TOPMOST, above every non-dev root, whatever zOrder either
-  // declares: a dev GUI the game can paint over is not a dev GUI. Expressed as
-  // two independent `stackOrder` passes concatenated rather than a magic
-  // zOrder value, so `stackOrder`'s one rule (ascending zOrder, ties -> array
-  // order) still governs WITHIN each band and nothing has to reason about what
-  // number is "high enough".
   const claimEntries = mountSpecs.map((spec) => ({
     id: spec.id,
     zOrder: spec.zOrder ?? 0,
     hitTest: spec.hitTest,
-    dev: spec.dev === true,
   }));
-  const stacked = [
-    ...stackOrder(claimEntries.filter((e) => !e.dev)),
-    ...stackOrder(claimEntries.filter((e) => e.dev)),
-  ];
+  const stacked = stackOrder(claimEntries);
   const bottomId = stacked[0]?.id;
   const kindById = new Map(mountSpecs.map((spec) => [spec.id, spec.kind] as const));
 
@@ -807,11 +783,6 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     // surface.ts`, which is the one door the capture/staleness/screenshot
     // sites now ask (ARCHITECTURE-CORE §The editor protocol, zero inference).
     surface.dataset['vgaiRootId'] = entry.id;
-    // The capture's marker (`composite-screenshot.ts` reads exactly this
-    // attribute): a dev layer is excluded from a play capture unless the
-    // capture asks for it, because a contaminated "does the game look right"
-    // frame is worthless.
-    if (entry.dev) surface.dataset['vgaiDevLayer'] = 'true';
     if (!isReact) {
       const canvas = surface as unknown as HTMLCanvasElement;
       canvas.width = w;
@@ -917,33 +888,48 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
       ? installSessionRenderHarness(game, renderModeLocation, config.renderControl?.target)
       : undefined;
 
+  let resolveStopComplete!: () => void;
+  const stopComplete = new Promise<void>((resolve) => {
+    resolveStopComplete = resolve;
+  });
+  let stopping = false;
+
   function fullCleanup(): void {
-    loop.stop();
-    router.dispose();
-    for (const entry of mountedEntries) {
-      entry.mounted.dispose();
-      entry.renderer?.dispose();
-      entry.renderer?.forceContextLoss();
-      // Remove from the element's CURRENT parent, not the mount-time
-      // `container`: the editor's Game panel re-parents the live surfaces
-      // when its mount element swaps (fill <-> device preset, W2c), and
-      // `container.removeChild` would throw NotFoundError after such a move.
-      // `container` remains the fallback for hosts whose element stand-ins
-      // never wire `parentNode` (headless unit fixtures); an element already
-      // detached by such a host is a no-op via the catch.
-      try {
-        (entry.element.parentNode ?? container).removeChild(entry.element);
-      } catch {
-        /* already detached — nothing to remove */
+    if (stopping) return;
+    stopping = true;
+    try {
+      loop.stop();
+      router.dispose();
+      for (const entry of mountedEntries) {
+        entry.mounted.dispose();
+        entry.renderer?.dispose();
+        entry.renderer?.forceContextLoss();
+        // Remove from the element's CURRENT parent, not the mount-time
+        // `container`: the editor's Game panel re-parents the live surfaces
+        // when its mount element swaps (fill <-> device preset, W2c), and
+        // `container.removeChild` would throw NotFoundError after such a move.
+        // `container` remains the fallback for hosts whose element stand-ins
+        // never wire `parentNode` (headless unit fixtures); an element already
+        // detached by such a host is a no-op via the catch.
+        try {
+          (entry.element.parentNode ?? container).removeChild(entry.element);
+        } catch {
+          /* already detached — nothing to remove */
+        }
       }
+      game.dispose();
+      retractDevGlobals();
+      retractRenderHarness?.();
+    } finally {
+      void Promise.allSettled(
+        mountedEntries.map((entry) => entry.mounted.disposeComplete ?? Promise.resolve()),
+      ).then(() => resolveStopComplete());
     }
-    game.dispose();
-    retractDevGlobals();
-    retractRenderHarness?.();
   }
 
   return {
     stop: fullCleanup,
+    stopComplete,
     // `Game.play` owns per-world pause, loop-gate, and audio-gate semantics.
     pause() {
       game.play.pause();

package/src/runtime/dev-build.ts

@@ -0,0 +1,49 @@
+/**
+ * THE one owner of "is this a development context". Every reader that has to
+ * answer that question calls {@link devBuildEnabled}; there is deliberately NO
+ * second source of truth — not a module-level cached boolean, not a
+ * `globalThis` flag, not a per-host copy of the `import.meta.env` read below.
+ * Instrumentation that ships to players because two places disagreed about
+ * what "dev" means is exactly the failure this single owner exists to make
+ * impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: the two three-root adapters (`adapter/setup-three-root-adapter.ts`
+ *    and `world3d-react/r3f-adapter.tsx`), which seed live render vitals only
+ *    under it, and the `static-batch` capability's mutation watch and `Frozen`
+ *    warning. Any future dev-only instrument calls this too, with its own
+ *    `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-call answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through. The editor's own preview mount is the worked
+ *     case: it is a dev session by definition even when the editor SPA it
+ *     runs inside is a production build.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_BUILD=true`.
+ *     Instrumenting a production bundle is a real, legitimate choice (an
+ *     internal playtest build, a QA build), and it must be an opt-in someone
+ *     had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export function devBuildEnabled(override?: boolean | undefined): boolean {
+  if (override !== undefined) return override;
+  // `import.meta` is cast whole, not just its `.env`: this module is reachable
+  // from programs whose tsconfig does not pull in `vite/client` (the session
+  // client's, for one, which reaches the three adapter transitively), and there
+  // `ImportMeta` has no declared `env` at all. The cast keeps the single owner
+  // of the dev answer importable from ANY program rather than forcing every
+  // downstream tsconfig to adopt Vite's ambient types.
+  const env = (import.meta as unknown as { env?: unknown }).env as
+    | { DEV?: boolean | undefined; VITE_VGAI_DEV_BUILD?: string | undefined }
+    | undefined;
+  if (env?.DEV === true) return true;
+  return env?.VITE_VGAI_DEV_BUILD === 'true';
+}

package/src/runtime/game.ts

@@ -734,8 +734,14 @@ export interface GameInternal extends Game {
    * the conventional `/inputmaps/default.inputmap.json` (or the adapter's
    * configured `inputMapPath`); runtime additions go through
    * `ctx.input.registerAction` instead.
+   *
+   * `{ optional: true }` is the CONVENTIONAL-PATH probe a root uses when the
+   * project never named a map: an absent file resolves quietly (a brand-new
+   * scaffold declares no actions yet), pins nothing — so a sibling root may
+   * still declare its own map — and yields to a map another root already
+   * owns. A map that exists but fails to parse is as loud either way.
    */
-  loadInputMap(path: string): Promise<void>;
+  loadInputMap(path: string, options?: { optional?: boolean }): Promise<void>;
   /** Release game-owned resources after every mounted root has disposed. */
   dispose(): void;
 }
@@ -856,6 +862,10 @@ export function createGame(opts: {
   input.setDebugEmit((event, detail) => debugRegistry.forRoot('(game)').emit(event, detail));
   let inputMapPath: string | null = null;
   let inputMapLoad: Promise<void> | null = null;
+  /** In-flight/settled conventional-path probes (`loadInputMap(path, {optional})`),
+   *  so two roots probing the same path share one fetch. Separate from
+   *  `inputMapLoad` because a probe that found nothing declares nothing. */
+  const inputMapProbes = new Map<string, Promise<void>>();
 
   function requireDefaultRoot(): RootInstance {
     if (roots.length === 0) {
@@ -1468,7 +1478,26 @@ export function createGame(opts: {
         runFrameImpl(fixedDt, { skipRenderPhases });
       }
     },
-    loadInputMap(path: string): Promise<void> {
+    loadInputMap(path: string, options?: { optional?: boolean }): Promise<void> {
+      if (options?.optional === true) {
+        // The conventional-path probe. It never becomes the game's declared
+        // map unless a file was actually there, so a root that DOES name a
+        // map (a sibling canvas root, a later mount) is never pre-empted by a
+        // probe that found nothing — the competing-path throw below would
+        // otherwise fire on a project that declared exactly one map.
+        if (inputMapPath) return inputMapLoad ?? Promise.resolve();
+        let probe = inputMapProbes.get(path);
+        if (!probe) {
+          probe = input.loadMapIfPresent(path).then((loaded) => {
+            if (loaded && !inputMapPath) {
+              inputMapPath = path;
+              inputMapLoad = Promise.resolve();
+            }
+          });
+          inputMapProbes.set(path, probe);
+        }
+        return probe;
+      }
       if (inputMapPath && inputMapPath !== path) {
         throw new Error(
           `Game.loadInputMap: input map is already "${inputMapPath}"; root requested "${path}". ` +

package/src/runtime/mount-manifest.ts

@@ -36,7 +36,6 @@ import {
 import { createGameRuntime, type GameSession, type RootMountSpec } from './create-runtime';
 import { type DebugBridgeWindowTarget, maybeInstallDebugBridge } from './debug-bridge';
 import { getDebugRegistry } from './debug-registry';
-import { devLayersEnabled } from './dev-layers';
 import { getGameplayRngTrapControl } from './gameplay-rng-trap';
 import { RENDER_SEED_QUERY_PARAM } from './render-seed';
 import type { GameSetupFn, PlaytestContext } from './types';
@@ -156,15 +155,6 @@ export interface MountManifestOptions {
   readonly seed?: number | undefined;
   /** Host identity for a private play run or coordinated Team Test. */
   readonly playtest?: PlaytestContext | null | undefined;
-  /**
-   * The explicit per-mount answer to "are dev layers enabled" — forwarded
-   * verbatim to `devLayersEnabled` (`runtime/dev-layers.ts`), the ONE owner of
-   * that question. Omit it and the build decides (dev build ⇒ on; production
-   * build ⇒ off unless `VITE_VGAI_DEV_LAYERS=true`). A root declaring
-   * `dev: true` is simply not mounted when the answer is `false`, so a shipped
-   * build carries no dev GUI at all.
-   */
-  readonly devLayers?: boolean | undefined;
   /** Where to read `?vgai-seed=` from for the boot-time seed reader. Same
    *  override precedent as `debugBridge.url` (defaults to `window.location`
    *  when a real `window` exists; a headless caller with no override gets no
@@ -346,7 +336,6 @@ function buildRootMountSpec(
     id: world.id,
     zOrder: world.zOrder,
     pausable: world.pausable,
-    dev: world.dev,
   };
 
   // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
@@ -390,10 +379,6 @@ function buildRootMountSpec(
  * ingest }` adapter with no caller-supplied adapter, or an empty manifest all
  * throw a named `Error` identifying the world id, its kind, and what was
  * expected — never a silent skip or a partially-mounted session.
- *
- * The ONE root that IS skipped silently is a `dev: true` dev layer when dev
- * layers are disabled (`devLayersEnabled`) — that skip is the feature: it is
- * what makes a dev GUI safe to leave in the game.
  */
 export async function mountManifestRoots(opts: MountManifestOptions): Promise<GameSession> {
   const manifest = resolveManifest(opts.manifest);
@@ -402,23 +387,7 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
   }
   const entries = opts.entries ?? {};
 
-  // The SHIP GATE. A `dev: true` root is the game's own dev GUI; it mounts
-  // only when dev layers are enabled, so a production build carries no dev
-  // GUI. The answer comes from `devLayersEnabled` and nowhere else — see that
-  // function's header for why there is exactly one owner. Dropping the root
-  // here (rather than mounting it hidden) is deliberate: nothing of the dev
-  // layer is constructed, so its entry module's cost and its DOM never exist
-  // in a shipped build.
-  const devEnabled = devLayersEnabled(opts.devLayers);
-  const mountable = devEnabled ? manifest.roots : manifest.roots.filter((world) => !world.dev);
-  if (mountable.length === 0) {
-    throw new Error(
-      'mountManifestRoots: every root in this manifest is a dev layer (`dev: true`) and dev ' +
-        'layers are disabled for this build — there is no game to mount.',
-    );
-  }
-
-  const roots: RootMountSpec[] = mountable.map((world) =>
+  const roots: RootMountSpec[] = manifest.roots.map((world) =>
     buildRootMountSpec(world, entries[world.id]),
   );
 
@@ -443,7 +412,7 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
     headless: opts.headless,
     // `rendering.antialias` reaches the WebGL context at CONSTRUCTION and can be honoured
     // nowhere else — see the manifest schema's own `rendering` block and
-    // `world3d-react/renderer-config.ts`'s header for why it is not a world-level declaration.
+    // `adapter/renderer-config.ts`'s header for why it is not a world-level declaration.
     ...(manifest.rendering === undefined ? {} : { antialias: manifest.rendering.antialias }),
     seed: resolvedSeed,
     playtest: opts.playtest,

package/src/world3d-react/engine-bridge.ts

@@ -15,6 +15,7 @@
  */
 
 import { createContext, useContext } from 'react';
+import { useOptionalGame } from '../react/world-state';
 import type { R3FGameContext } from './world-context';
 
 export interface EngineBridgeValue {
@@ -50,11 +51,35 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  */
 export function useGameContext(): R3FGameContext {
   const bridge = useContext(EngineBridge);
+  // Read unconditionally (rules of hooks) — used only to shape the throw below.
+  const hostedByGame = useOptionalGame() !== null;
   if (!bridge?.ctx) {
+    // NAME THE REAL CAUSE. This throw used to say "check that the component is
+    // rendered inside your world entry" — advice a scaffolded game has already
+    // followed, because the shape `vgai create` produces (`export default
+    // function World()`) mounts as a COMPONENT ROOT and receives no vgai
+    // runtime context at all: `r3f-root-factory.tsx` passes
+    // `engineRuntime: false` deliberately, so this hook can never resolve
+    // there however the component is nested. A world whose first render calls
+    // it dies with "fiber crashed before its first commit" and a fix
+    // instruction that cannot work. The `Game` in scope tells the two cases
+    // apart: present means a vgai-mounted world, absent means no root at all.
     throw new Error(
-      'useGameContext(): no engine root context. This hook only works inside an R3F ' +
-        'root mounted by createR3FAdapter (@engine/world3d-react) — check that the ' +
-        'component is rendered inside your world entry, not in a standalone <Canvas>.',
+      hostedByGame
+        ? 'useGameContext(): this world mounts as a COMPONENT ROOT (the default-exported ' +
+            'shape `vgai create` scaffolds) and receives no vgai runtime context — by design, ' +
+            'so nesting cannot fix it. Game-scoped services are on the Game handle instead: ' +
+            '`useGame().input` (from @vgai/engine/react/world-state) is the game-owned ' +
+            "InputManager the host already loaded this project's input map into and the same " +
+            'one `game.input.hold/tap` drives; `useDebugProvider`/`useDebugCommand`/' +
+            '`useWorldState` are the state/command doors. If this world genuinely needs the ' +
+            'imperative runtime (`ctx.systems`, adapter options like `inputMapPath`), export ' +
+            '`adapter = createR3FAdapter({ id, content: <World/> })` from the entry instead of ' +
+            'default-exporting the component.'
+        : 'useGameContext(): no engine root context and no Game in scope — this component is ' +
+            'rendering outside any mounted vgai root (a standalone <Canvas>, a story, or a ' +
+            "bare test render). Mount it through your project's three root, or read services " +
+            'the component root way (native hooks and project-owned state).',
     );
   }
   return bridge.ctx;

package/src/world3d-react/index.ts

@@ -33,22 +33,22 @@
  * 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
  * contract to `react`/`@react-three/fiber`/`three` alone.
  */
 
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
-export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
-export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
 export {
   applyWorldRendererConfig,
   type WorldOutputColorSpace,
   type WorldRendererConfig,
   type WorldToneMapping,
-} from './renderer-config';
+} from '../adapter/renderer-config';
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
+export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
+export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
 export {
   createR3FRootContext,
   DEFAULT_INPUT_MAP_PATH,

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

@@ -30,6 +30,7 @@ import {
 } from '@react-three/fiber';
 import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import { applyWorldRendererConfig, type WorldRendererConfig } from '../adapter/renderer-config';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
@@ -43,10 +44,9 @@ 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, 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
@@ -77,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.
@@ -112,7 +117,7 @@ export interface CreateR3FAdapterOptions {
   /** 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
-   *  pipeline — see `./renderer-config.ts`. */
+   *  pipeline — see `../adapter/renderer-config.ts`. */
   readonly renderer?: WorldRendererConfig | undefined;
 }
 
@@ -185,10 +190,33 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // `ctx` rides the bridge so ordinary components can reach engine
       // services through `useGameContext()`.
       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.
@@ -320,24 +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,
-        runtime ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }) : null,
+        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 },
-              game ? createElement(WorldProvider, { game }, world) : 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 —
@@ -349,6 +397,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           cleanup();
           root.unmount();
           runtime?.dispose();
+          if (!runtime) gameDebugRegistry?.strip(id);
           restoreRendererConfig();
           reject(
             new Error(
@@ -361,6 +410,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           cleanup();
           root.unmount();
           runtime?.dispose();
+          if (!runtime) gameDebugRegistry?.strip(id);
           restoreRendererConfig();
           reject(
             new Error(
@@ -420,7 +470,6 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // `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 = (): RootState => 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
@@ -432,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
@@ -454,7 +503,7 @@ 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
@@ -640,6 +689,26 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           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/src/world3d-react/r3f-root-factory.tsx

@@ -70,8 +70,18 @@ export function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): Ro
       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,
     });
   }