@vgai/engine 0.5.16 → 0.5.18

package/dist/runtime/mount-manifest.js

@@ -30,7 +30,6 @@ import { loadGameManifest, } from '../manifest/load';
 import { createGameRuntime } from './create-runtime';
 import { 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';
 /**
@@ -167,7 +166,6 @@ function buildRootMountSpec(world, entry) {
         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
     // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
@@ -208,10 +206,6 @@ function buildRootMountSpec(world, entry) {
  * 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) {
     const manifest = resolveManifest(opts.manifest);
@@ -219,20 +213,7 @@ export async function mountManifestRoots(opts) {
         throw new Error('mountManifestRoots: manifest declares no roots — nothing to mount.');
     }
     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 = mountable.map((world) => buildRootMountSpec(world, entries[world.id]));
+    const roots = manifest.roots.map((world) => buildRootMountSpec(world, entries[world.id]));
     // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
     // Game, and therefore `ctx.random`, before any world's `mount()`/`setup()`
     // runs — see `createGame`'s own doc comment): the seed must be baked in at
@@ -253,7 +234,7 @@ export async function mountManifestRoots(opts) {
         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/dist/world3d-react/engine-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC;;wCAEoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAU/C"}
+{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC;;wCAEoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAkC/C"}

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

@@ -14,6 +14,7 @@
  * component reaches engine services.
  */
 import { createContext, useContext } from 'react';
+import { useOptionalGame } from '../react/world-state';
 export const EngineBridge = createContext(null);
 /**
  * This R3F root's context, for use inside any component in the tree — an
@@ -39,10 +40,34 @@ export const EngineBridge = createContext(null);
  */
 export function useGameContext() {
     const bridge = useContext(EngineBridge);
+    // Read unconditionally (rules of hooks) — used only to shape the throw below.
+    const hostedByGame = useOptionalGame() !== null;
     if (!bridge?.ctx) {
-        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>.');
+        // 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(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/dist/world3d-react/index.d.ts

@@ -33,15 +33,15 @@
  * 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 { applyWorldRendererConfig, type WorldOutputColorSpace, type WorldRendererConfig, type WorldToneMapping, } 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 { applyWorldRendererConfig, type WorldOutputColorSpace, type WorldRendererConfig, type WorldToneMapping, } from './renderer-config';
 export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, type R3FGameContext, type R3FRootContextOptions, type R3FRootRuntime, } from './world-context';
 //# sourceMappingURL=index.d.ts.map

package/dist/world3d-react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world3d-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world3d-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/world3d-react/index.js

@@ -33,14 +33,14 @@
  * 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 { applyWorldRendererConfig, } from '../adapter/renderer-config';
 export { EngineBridge, useGameContext } from './engine-bridge';
 export { createR3FAdapter } from './r3f-adapter';
 export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
-export { applyWorldRendererConfig, } from './renderer-config';
 export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';

package/dist/world3d-react/r3f-adapter.d.ts

@@ -20,7 +20,7 @@
  */
 import { type ReactNode } from 'react';
 import type { RootAdapter } from '../adapter';
-import { type WorldRendererConfig } from './renderer-config';
+import { type WorldRendererConfig } from '../adapter/renderer-config';
 /** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
 export interface CreateR3FAdapterOptions {
     /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
@@ -45,7 +45,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;
 }
 /**

package/dist/world3d-react/r3f-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,OAAO,EAA2B,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAgBlF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2CvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2gB9E"}
+{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,OAAO,EAA2B,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AA+DhG,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;0DAGsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2kB9E"}

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

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

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

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

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

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

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

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

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

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

package/dist/world3d-react/renderer-config.d.ts

@@ -1,73 +1,11 @@
 /**
- * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ * `@engine/world3d-react/renderer-config` — a published entry point.
  *
- * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
- * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
- * a world authored against them and WRONG for a world that was authored against a different
- * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
- * at all, so ACES quietly desaturates and darkens every colour its author picked.
- *
- * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
- * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
- * of that shape are load-bearing:
- *
- *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
- *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
- *    module-level three global, so one world's declaration cannot change how the editor's own
- *    viewport, another root, or a thumbnail bake renders.
- *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
- *    is never written, so declaring a tone mapping does not silently reset the clear colour.
- *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
- *    back what it found would leak its pipeline into whatever mounts next.
- *
- * This is deliberately NOT a general render-settings system. It carries what a world can honestly
- * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
- * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
- * declared here, because there would be no honest moment to apply it.
- */
-import type * as THREE from 'three';
-/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
-export type WorldToneMapping = 'none' | 'linear' | 'reinhard' | 'cineon' | 'aces' | 'agx' | 'neutral';
-/**
- * The output transfer function the frame is written with.
- *
- *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
- *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
- *    result is already in display space and encoding it a second time washes the frame out.
- */
-export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
-/**
- * The shadow-map filter, named as data rather than as three's numeric enum.
- *
- * This is a renderer INSTANCE property (`WebGLRenderer.shadowMap.type`), not a context attribute,
- * so unlike MSAA it has an honest moment at which a world can ask for it — which is the whole test
- * this file's header states. A source engine that declares its own shadow filter (Godot 3's
- * `rendering/quality/shadows/filter_mode`) would otherwise inherit whatever the host built with.
- */
-export type WorldShadowMapType = 'basic' | 'pcf' | 'pcf-soft' | 'vsm';
-/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
-export interface WorldRendererConfig {
-    readonly toneMapping?: WorldToneMapping | undefined;
-    readonly toneMappingExposure?: number | undefined;
-    readonly outputColorSpace?: WorldOutputColorSpace | undefined;
-    /**
-     * `WebGLRenderer.shadowMap.type`. Writing it after a shadow map has already been built needs
-     * `shadowMap.needsUpdate`, which this function sets — three caches the compiled depth material
-     * per type and would otherwise keep filtering with the previous one.
-     */
-    readonly shadowMapType?: WorldShadowMapType | undefined;
-    /**
-     * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
-     * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
-     * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
-     */
-    readonly clearColor?: string | undefined;
-}
-/**
- * Apply `config` to `renderer`, returning the restore function that puts back what was there.
- *
- * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * The engine package's export map is the wildcard `"./*"`, so every file under
+ * `packages/engine/src/` is an entry point a game outside this repo can import by path. The module
+ * itself now lives in the adapter seam (`@engine/adapter/renderer-config`, which its header
+ * explains), and this file keeps the path that shipped resolving to it. Import the seam path in
+ * new code.
  */
-export declare function applyWorldRendererConfig(three: typeof THREE, renderer: THREE.WebGLRenderer, config: WorldRendererConfig): () => void;
+export * from '../adapter/renderer-config';
 //# sourceMappingURL=renderer-config.d.ts.map

package/dist/world3d-react/renderer-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer-config.d.ts","sourceRoot":"","sources":["../../src/world3d-react/renderer-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,aAAa,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,UAAU,GAAG,KAAK,CAAC;AAEtE,sGAAsG;AACtG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,KAAK,EACnB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,MAAM,EAAE,mBAAmB,GAC1B,MAAM,IAAI,CA+EZ"}
+{"version":3,"file":"renderer-config.d.ts","sourceRoot":"","sources":["../../src/world3d-react/renderer-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,4BAA4B,CAAC"}