@vgai/engine 0.5.15 → 0.5.17

package/src/runtime/game.ts

@@ -1,25 +1,11 @@
 /**
- * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
- * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
- * `'canvas'`-kind `RootInstance` support (`stage`/`physics2d`, a real
- * `pixiStage()`) so a canvas adapter can register its world onto a real `Game`
- * instead of driving its own loop, and in T7.3 slice 2 with a
- * construction-time stage check (symmetric with the three/scene check).
- * T6.2 slice 1 adds real `'react'`-kind
- * `RootInstance` support (`container`, a real `reactRoot()`) — the DOM-root
- * world surface `runtime/create-runtime.ts`'s roots path now mounts, with
- * `physics`/`collisions`/`camera`/`frame` `undefined` for them exactly
- * like an opaque/foreign mount.
- *
- * (D6), particularly §4 (the frame algorithm) and §8 stage 2, for the full
- * target shape. This file holds the Game/ RootInstance shell, the NEW
- * game-scoped `SystemRunner`, and the host-facing `runFrame` frame executor.
- * The public surface is NOT frozen yet — do not add these exports to a
- * barrel/index; only the in-scope runtime/adapter files import this module
- * directly. The `gpu` per-world cache is the one remaining slice-1 omission.
+ * The surface-neutral Game root and its declaration-ordered root registry.
+ * Three, Canvas, and DOM roots share one game-scoped loop, input manager,
+ * system runner, state bridge, debug registry, clock, and seeded RNG. Each
+ * RootInstance retains its own mounted surface and optional capabilities.
  */
 
-// TYPE-ONLY pixi import (T7.3 slice 1): `game.ts` must never value-import
+// TYPE-ONLY pixi import: `game.ts` must never value-import
 // `pixi.js` — a value import would pull the Pixi runtime into 3D-only
 // bundles that never touch a canvas root. Every pixi-typed field below is erased
 // at compile time; nothing here constructs or calls into Pixi.
@@ -48,7 +34,6 @@ import type { PhysicsRegistry } from '../physics/physics-registry';
 // TYPE-ONLY (same rule as the pixi import above): this lives under `pixi/`,
 // but `game.ts` only ever names its TYPE.
 import type { Physics2DRegistry } from '../pixi/physics-registry';
-import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import {
   createDebugRegistry,
   DebugError,
@@ -89,10 +74,7 @@ const DISPLAY_RATE_PHASES: readonly SystemPhaseName[] = PHASE_ORDER.filter(
  * `runFrame`. `GameLoop.timeScale` (unaffected by this) remains the orthogonal
  * "speed up/slow down" axis — pausing never touches it, so the host's
  * accumulator/rAF loop keeps ticking at its normal cadence, which is what makes
- * "paused still renders" possible (the previous `GameSession.pause()`
- * implementation set `loop.timeScale = 0`, which starves the accumulator — and,
- * before WO-P13, stopped rendering with it; that was the bug this control
- * surface replaces, not a compatible behavior to keep).
+ * "paused still renders" possible.
  */
 export interface PlayState {
   /** Whether the game is currently paused (game-level — see the per-world
@@ -131,11 +113,9 @@ export interface PlayState {
 
 /**
  * The kinds of render surface a world can be. `'three'` and `'canvas'`
- * roots are both real; `'react'` is named
- * here so the type is already shaped for T7.4 and no caller has to widen a
- * union later.
+ * roots are canvas-backed; `'dom'` roots own a DOM layer.
  *
- * Re-exported from `adapter/adapter-surface.ts` (T7.5) — moved there so
+ * Re-exported from `adapter/adapter-surface.ts` so
  * `adapter/root-adapter.ts`'s kind-tagged `MountedRoot` types can name it
  * without an import cycle back to this file. This re-export keeps every
  * existing `import type { AdapterSurface } from '../runtime/game'` call site
@@ -144,7 +124,7 @@ export interface PlayState {
 export type AdapterSurface = AdapterSurfaceLeaf;
 
 /**
- * A world's per-phase frame hooks (T7.1 slice 2).
+ * A world's per-phase frame hooks.
  * Populated on a `RootInstance` only for first-party mounts — an opaque/
  * foreign mount has no phase-partitioned entry point, so it stays
  * `undefined` and the Game's frame executor (`GameInternal.runFrame`) falls
@@ -153,7 +133,7 @@ export type AdapterSurface = AdapterSurfaceLeaf;
 export interface RootFrameHooks {
   /** Run this world's engine systems + component ticks + world-bound game
    *  systems for one phase. For a first-party world this delegates to the
-   *  SAME `SystemRunner.runPhase` its (legacy) `mounted.update` uses. */
+   *  same `SystemRunner.runPhase` as its direct `mounted.update` entry. */
   runPhase(phase: SystemPhaseName, dt: number): void;
   /** Run once per substep, after ALL phases have run for ALL roots this
    *  substep (mirrors where `mounted.update`'s post-`systems.run` work sat
@@ -164,14 +144,12 @@ export interface RootFrameHooks {
 
 /**
  * A single world instance: the unit of adaptation.
- * Slice-1 subset — `gpu` (per-world GPU resource cache, §6.2) is omitted
- * until the slice that builds it.
  */
 export interface RootInstance {
-  /** Manifest id (T3.1). Slice 1 always registers exactly one: `'main'`. */
+  /** Manifest root id. */
   readonly id: string;
   readonly kind: AdapterSurface;
-  /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
+  /** Per-world play/pause semantics. */
   readonly pausable: boolean;
   /** The RootAdapter that produced `mounted` — first-party or external.
    *  Deliberately narrower than `RootAdapter<K>` (T7.5): this field is only
@@ -195,7 +173,7 @@ export interface RootInstance {
    *  descriptively for a non-pixijs world, or a canvas world built without
    *  a `stage` (see `RootInstanceInit.stage`). */
   pixiStage(): PIXI.Container;
-  /** Kind-narrowed accessor for react roots (T6.2 slice 1): returns the
+  /** Kind-narrowed accessor for DOM roots: returns the
    *  DOM-root layer `<div>` the host mounted this world's react tree into
    *  (the SAME element passed as `container` to `createRootInstance` —
    *  identity matters, mirroring `threeScene()`/`pixiStage()`'s "same
@@ -214,7 +192,7 @@ export interface RootInstance {
   readonly physics2d?: Physics2DRegistry | undefined;
   /** Kind-typed via `mounted` in T7.5; `unknown` here deliberately. */
   readonly camera?: unknown;
-  /** Phase-partitioned frame entry point (T7.1 slice 2) — present only for
+  /** Phase-partitioned frame entry point — present only for
    *  first-party mounts. `undefined` for an opaque/foreign mount, which
    *  `GameInternal.runFrame` drives via its single `mounted.update` call
    *  instead (unless it `drivesOwnLoop`, in which case it isn't ticked at
@@ -399,8 +377,8 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
 /**
  * Type guard for whether a `MountedThreeRoot` is a first-party
  * `SetupThreeRootAdapter` mount (has a live `GameContext` at `.ctx`). Used to
- * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
- * `input`/`audio`) can be populated from it — an external
+ * decide whether a world's `physics`/`collisions`/`camera` can be populated
+ * from it — an external
  * adapter's mount has none of these first-party handles.
  *
  * Checks the `firstParty: true` brand (checklist item 1), NOT `'ctx' in
@@ -505,13 +483,9 @@ function debrisOwnersOf(world: RootInstance): DebrisOwner[] {
 }
 
 /**
- * The Game root. Owns the one loop, the raw-asset
- * cache, the world registry, and (T7.1 slice 2) the game-scoped
- * `SystemRunner`. `input`/`audio` remain slice-1 late
- * additions: they delegate to the default world's first-party mount so
- * existing single-world call sites keep working; hoisting them to true
- * Game ownership (the target shape) is a later slice's
- * work, not this one's.
+ * The Game root. Owns the loop, raw-asset cache, world registry, input,
+ * and game-scoped `SystemRunner`. Surface-specific capabilities remain on
+ * their mounted roots or in the aggregated `SystemAdapters` contract.
  */
 export interface Game {
   readonly loop: GameLoop;
@@ -521,18 +495,16 @@ export interface Game {
   /** Per-game diagnostic store. Disabled by default; the editor enables it on demand. */
   readonly profiler: PerformanceProfiler;
   /**
-   * The game-scoped `SystemRunner` (T7.1 slice 2) — a
-   * NEW bucket, separate from any world's own runner. Within each phase,
+   * The game-scoped `SystemRunner`, separate from any world's own runner.
+   * Within each phase,
    * `GameInternal.runFrame` runs THIS runner's `runPhase` first, before any
    * world's engine systems/component ticks/world-bound game systems (e.g.
    * `ctx.systems.add`, which stays world-bound to the default world — see
    * `runtime/types.ts`). Empty for every existing game (nothing registers
-   * against it yet), so `runFrame`'s behavior for a single-world game is
-   * unchanged by its presence.
+   * against it), so an empty runner has no frame cost beyond dispatch.
    */
   readonly systems: SystemRunner;
-  /** Declaration-ordered. Slice 1 registers exactly one (the default
-   *  three world) — this is the SAME array reference `registerRoot`
+  /** Declaration-ordered. This is the same array reference `registerRoot`
    *  mutates, not a snapshot, so holders (e.g. `GameContext.roots`) observe
    *  later registrations. */
   readonly roots: ReadonlyArray<RootInstance>;
@@ -568,9 +540,6 @@ export interface Game {
   subscribeSystemAdapters?(listener: () => void): () => void;
   /** The one game-owned `InputManager`, shared by every first-party root. */
   readonly input: InputManager;
-  /** Delegates to the default world's first-party audio context. Throws
-   *  when the default world is not a first-party mount. */
-  readonly audio: GameAudio;
   /**
    * Frame-versioned state bridge (T7.4 slice 1). Bumped once per completed
    * `runFrame`, after all phases of all roots and all `endFrame` hooks (see
@@ -653,28 +622,18 @@ export interface GameInternal extends Game {
    *   else: world.mounted.update?.(dt)          // opaque world fallback
    * ```
    *
-   * For today's single first-party world this is byte-identical to the
-   * legacy `mounted.update(dt)` (`game.systems` is empty; the one world's
-   * `frame.runPhase` delegates to the SAME `SystemRunner.runPhase` its
-   * `update` used; `endFrame` is the same `postFrame` call). A
-   * `drivesOwnLoop` world is never ticked here at all — matching its
-   * exclusion from the legacy `!mountedRef.drivesOwnLoop` guard. An opaque
-   * host-driven world (no `frame`) gets exactly one `update(dt)` call per
-   * substep, after the phase loop — unchanged cadence from today.
+   * A single first-party world and its direct `mounted.update(dt)` entry run
+   * the same `SystemRunner` and `postFrame` work. A `drivesOwnLoop` world is
+   * never ticked here. An opaque host-driven world (no `frame`) gets exactly
+   * one `update(dt)` call per substep, after the phase loop.
    *
    * D10/T7.6 play-state addendum: when `Game.play.paused` is true, every
    * `pausable` (and non-`drivesOwnLoop`) world skips every phase EXCEPT
    * `render` (still called, every substep, with `dt` forced to `0`) and skips
    * its `endFrame`/opaque-`update` call entirely — a `pausable: false` world
-   * is completely unaffected. `opts.ignorePause` runs this call as if nothing
-   * were paused, regardless of the live `paused` flag; kept for external
-   * byte-compatibility (no first-party caller passes it today — grep finds
-   * none) but is no longer how `Game.play.step()` works (§7.1-2 fix,
-   * probe4: the old `ignorePause` full-frame re-run double-ticked every
-   * already-running `pausable: false` world, since D10's ordinary loop never
-   * stops ticking them). `Game.play.step()` now drives this function via the
-   * internal-only `onlyFrozen` mode instead (see `runFrameImpl` — not part of
-   * this public, host-facing signature): it ticks EXACTLY the currently
+   * is completely unaffected. `Game.play.step()` drives this function via the
+   * internal-only `onlyFrozen` mode (see `runFrameImpl` — not part of this
+   * public, host-facing signature): it ticks exactly the currently
    * frozen set (host-driven, `pausable`, and `paused`) through every phase +
    * `endFrame` with the real `dt` (not the render-phase's forced `0`), and
    * touches no other world at all — a natural no-op while not paused, since
@@ -690,7 +649,7 @@ export interface GameInternal extends Game {
    * calls `runFrame(fixedDt)` with no opts) is frame-exact and unchanged.
    * `runTicks` sets it per tick for its `render: 'none' | 'last'` modes.
    */
-  runFrame(dt: number, opts?: { ignorePause?: boolean; skipRenderPhases?: boolean }): void;
+  runFrame(dt: number, opts?: { skipRenderPhases?: boolean }): void;
   /**
    * WO-P13 — run ONE display frame's presentation pass: the registered
    * `onRenderStep` callbacks, then the `preRender` and `render` phases across
@@ -775,20 +734,18 @@ 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;
 }
 
-function describeMismatch(handle: 'input' | 'audio', world: RootInstance): string {
-  return (
-    `Game.${handle}: default world "${world.id}" (kind: ${world.kind}) is not a first-party ` +
-    "mount — hoisting these to true Game ownership is a later slice's work; available only " +
-    'via a first-party default world today'
-  );
-}
-
 /**
  * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
  * builds this BEFORE mounting its one adapter, then registers the default
@@ -879,7 +836,7 @@ export function createGame(opts: {
     getTick: () => tick,
     getSimT: () => simT,
     // D15/T-D15.5 — "the manifest's first/default world" for the debug
-    // registry's world-addressed input-target compatibility surface. Every
+    // registry's world-addressed input-target surface. Every
     // first-party root now registers the SAME game-owned InputManager, but the
     // stable default id still keeps explicit/implicit debug routing coherent.
     // Use the SAME "first three world, else first world" rule
@@ -905,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) {
@@ -913,14 +874,6 @@ export function createGame(opts: {
     return roots.find((w) => w.kind === 'three') ?? roots[0]!;
   }
 
-  function requireFirstPartyCtx(handle: 'input' | 'audio') {
-    const world = requireDefaultRoot();
-    if (!isFirstPartyMounted(world.mounted)) {
-      throw new Error(describeMismatch(handle, world));
-    }
-    return world.mounted.ctx;
-  }
-
   // --- Game.systemAdapters aggregation (§7.1-3, probe1) --------------------
   // Warn-once-per-colliding-key state, scoped to this Game instance (a fresh
   // Game gets a fresh warn history) — deliberately NOT reset by anything
@@ -1023,7 +976,7 @@ export function createGame(opts: {
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/roots — splitting it would obscure the ordering contract documented on GameInternal.runFrame
   function runFrameImpl(
     dt: number,
-    frameOpts?: { ignorePause?: boolean; onlyFrozen?: boolean; skipRenderPhases?: boolean },
+    frameOpts?: { onlyFrozen?: boolean; skipRenderPhases?: boolean },
   ): void {
     // D15 (T-D15.3) — brackets the ENTIRE frame body (every phase, every
     // world, both the `onlyFrozen` and normal branches below converge on the
@@ -1033,7 +986,6 @@ export function createGame(opts: {
     // declare `determinism.seededRandom`).
     if (rngTrapEnabled) rngTrap.enable();
     profiler.beginFrame();
-    const ignorePause = frameOpts?.ignorePause ?? false;
     // D15/T-D15.4 + WO-P13: the render-phase skip. Two callers set it, for the
     // same reason — this substep is not the thing that paints. `runTicks`'s
     // `render: 'none'|'last'` fast-forward sets it on every tick it doesn't
@@ -1048,9 +1000,6 @@ export function createGame(opts: {
     // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
     // `pausable`, and `paused`) through every phase + `endFrame`, with the REAL
     // `dt` (not the render-phase's forced `0`), and touches no other world at all
-    // — §7.1-2 fix, probe4: the previous `ignorePause` full-frame re-run ticked
-    // EVERY host-driven world, double-ticking every already-running
-    // `pausable: false` world (D10's ordinary loop never stops ticking them).
     const onlyFrozen = frameOpts?.onlyFrozen ?? false;
     // Checklist item 7: snapshot the world count ONCE at entry and iterate
     // by index in both loops below. A world registered mid-frame (e.g. from
@@ -1068,10 +1017,9 @@ export function createGame(opts: {
           break;
         }
       } else if (
-        ignorePause ||
-        (world.mounted.drivesOwnLoop
+        world.mounted.drivesOwnLoop
           ? !paused || !world.pausable || !world.mounted.setPaused
-          : !paused || !world.pausable)
+          : !paused || !world.pausable
       ) {
         inputFrameActive = true;
         break;
@@ -1169,13 +1117,12 @@ export function createGame(opts: {
           for (let i = 0; i < n; i++) {
             const world = roots[i]!;
             if (world.mounted.drivesOwnLoop) continue;
-            // D10/T7.6: a `pausable` world under an active (non-ignored) pause
+            // D10/T7.6: a `pausable` world under an active pause
             // skips every phase except `render` — its render still runs, every
             // substep, but with `dt` forced to `0` (deterministic: no
             // time-based render effect silently keeps animating a "frozen"
-            // scene). A `pausable: false` world (or any world while
-            // `ignorePause`) is unaffected.
-            const frozen = !ignorePause && paused && world.pausable;
+            // scene). A `pausable: false` world is unaffected.
+            const frozen = paused && world.pausable;
             if (frozen && phase !== SystemPhase.RENDER) continue;
             const phaseDt = frozen ? 0 : dt;
             // Checklist item 2: isolate each world's per-phase work — one
@@ -1199,7 +1146,7 @@ export function createGame(opts: {
         if (world.mounted.drivesOwnLoop) continue;
         // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
         // there is nothing to "end the frame" of when nothing ran this substep.
-        const frozen = !ignorePause && paused && world.pausable;
+        const frozen = paused && world.pausable;
         if (frozen) continue;
         advanced = true;
         if (world.frame) {
@@ -1346,9 +1293,6 @@ export function createGame(opts: {
       for (const listener of systemAdapterListeners) listener();
     },
     input,
-    get audio() {
-      return requireFirstPartyCtx('audio').audio;
-    },
     state: stateBridge,
     play: {
       get paused() {
@@ -1387,11 +1331,7 @@ export function createGame(opts: {
             }
           }
         }
-        // §7.1-2 fix (probe4): tick EXACTLY the frozen (host-driven, pausable,
-        // paused) set — not `{ ignorePause: true }`, which re-ran a FULL
-        // extra frame for every host-driven world (including already-running
-        // `pausable: false` ones — a double-tick, since D10's ordinary loop
-        // never stops ticking them). See `runFrameImpl`'s `onlyFrozen` mode.
+        // Tick exactly the frozen (host-driven, pausable, paused) set.
         runFrameImpl(dt, { onlyFrozen: true });
       },
     },
@@ -1486,7 +1426,7 @@ export function createGame(opts: {
         );
       }
     },
-    runFrame(dt: number, frameOpts?: { ignorePause?: boolean; skipRenderPhases?: boolean }): void {
+    runFrame(dt: number, frameOpts?: { skipRenderPhases?: boolean }): void {
       runFrameImpl(dt, frameOpts);
     },
     runRenderFrame(alpha: number, displayDt: number): void {
@@ -1538,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-game.ts

@@ -17,6 +17,11 @@
 // even the 'three' convenience export is a plain function the CALLER
 // registers, not something this module wires up automatically.
 
+import {
+  installNativeDebugBindings,
+  type NativeDebugBinding,
+  nativeDebugBindingFromEntryModule,
+} from '../adapter/native-debug-module';
 import type { RootAdapter } from '../adapter/root-adapter';
 import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { GameSession } from './create-runtime';
@@ -209,6 +214,15 @@ function worldIsSelfSufficient(_world: ResolvedAdapterRoot): boolean {
   return false;
 }
 
+function nativeDebugForEntry(
+  world: ResolvedAdapterRoot,
+  entryModule: unknown,
+): NativeDebugBinding[] {
+  if (entryModule === undefined || world.adapter.type !== 'builtin') return [];
+  const binding = nativeDebugBindingFromEntryModule(world.id, entryModule);
+  return binding ? [binding] : [];
+}
+
 /**
  * Mount every world declared by a `vgai.project.json` manifest onto `host
  * .container`, resolving each world's kind through the `registerAdapter`
@@ -240,6 +254,7 @@ export async function mountGameFromManifest(
   assertExportedOrInEditor();
   const manifest = resolveManifest(manifestInput);
   const entries: Record<string, MountEntry> = { ...opts.entries };
+  const nativeDebug: NativeDebugBinding[] = [];
 
   for (const world of manifest.roots) {
     if (entries[world.id] !== undefined) continue; // explicit entry always wins
@@ -250,6 +265,7 @@ export async function mountGameFromManifest(
         world.entry !== undefined && host.loadEntryModule
           ? await host.loadEntryModule(world.entry)
           : undefined;
+      nativeDebug.push(...nativeDebugForEntry(world, entryModule));
       entries[world.id] = await factory(world, { host, entryModule });
       continue;
     }
@@ -265,7 +281,7 @@ export async function mountGameFromManifest(
     );
   }
 
-  return mountManifestRoots({
+  const session = await mountManifestRoots({
     manifest,
     container: host.container,
     entries,
@@ -273,4 +289,6 @@ export async function mountGameFromManifest(
     height: host.height,
     headless: host.headless,
   });
+  installNativeDebugBindings(session.game, nativeDebug);
+  return session;
 }

package/src/runtime/mount-manifest.ts

@@ -20,8 +20,7 @@
 // `entries[id].adapter` (the caller's own module graph built it). Threejs is
 // different: `three`/
 // `SetupThreeRootAdapter` are already unconditional dependencies of every
-// caller of `createGameRuntime`'s legacy path (this same file's sibling,
-// immediately below in this directory), so wrapping a `setup` with
+// caller of `createGameRuntime`, so wrapping a `setup` with
 // `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
 
 import { assertNever } from '../adapter/adapter-surface';
@@ -37,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';
@@ -157,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
@@ -275,8 +264,9 @@ function resolveThreeAdapter(
   if (world.adapter.type === 'ingest') {
     throw new Error(
       `mountManifestRoots: world "${world.id}" (three) declares an { ingest } adapter — ` +
-        "ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
-        "plus in-realm scene capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
+        "captured ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
+        'plus in-realm scene capture, see resolveIngestDescriptor + ' +
+        'mountThreeIngestRootFromManifest) and are ' +
         'not supported by mountManifestRoots (no porting aids, no hosted ingest routes).',
     );
   }
@@ -346,8 +336,6 @@ function buildRootMountSpec(
     id: world.id,
     zOrder: world.zOrder,
     pausable: world.pausable,
-    dev: world.dev,
-    loop: world.loop,
   };
 
   // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
@@ -391,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);
@@ -403,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]),
   );
 

package/src/runtime/types.ts

@@ -259,6 +259,28 @@ export interface GameContext {
   playtest?: PlaytestContext | null | undefined;
 }
 
+/**
+ * Services shared by component-authored roots, independent of their render
+ * surface. This is deliberately an explicit pick from {@link GameContext}:
+ * adding a subsystem to the imperative Three setup context never silently
+ * exposes it to R3F or Canvas components.
+ *
+ * `input` is nullable because it belongs to the optional `Game` host. Normal
+ * vgai project mounts always provide it; bare harnesses and foreign hosts do
+ * not. Component code therefore sees the absence in its type instead of a
+ * getter that first throws from inside a frame callback.
+ *
+ * `clock` is surface-specific and intentionally absent here. The imperative
+ * and R3F clocks can dispose `THREE.Object3D` debris; a Canvas context narrows
+ * that Three-only operation away.
+ */
+export type ComponentContextBase = Pick<
+  GameContext,
+  'systems' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'
+> & {
+  readonly input: InputManager | null;
+};
+
 /** Return value from a game setup function. */
 export interface GameCleanup {
   dispose: () => void;

package/src/setup/setup-renderer.ts

@@ -79,10 +79,9 @@ export function applyRendererSettings(
  * reload-only `antialias` option at construction and the live shadow/resolution
  * settings (via {@link applyRendererSettings}). Absent → registry defaults.
  *
- * `opts` is additive (T6.1 slice 1, D5 §1/§4): omitted
- * entirely, construction is byte-identical to before (no `alpha`/
- * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
- * passes it. The roots path passes `alpha:true` for every stacked canvas
+ * When `opts` is omitted, construction leaves `alpha` and
+ * `preserveDrawingBuffer` at their renderer defaults. The host passes
+ * `alpha:true` for every stacked canvas
  * above the bottom one (so its clear-alpha-0 shows the layer below through
  * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
  * recorded capture-tier cost, paid once here rather than re-derived later).

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 {
@@ -39,7 +40,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  * function Player({ speed = 4.5 }) {
  *   const { input } = useGameContext();
  *   const ref = useRef<THREE.Group>(null);
- *   useFrame((_, dt) => { if (input.isPressed('move_forward')) … });
+ *   useFrame((_, dt) => { if (input?.isPressed('move_forward')) … });
  *   return <group ref={ref}><PlayerCharacter /></group>;
  * }
  * ```
@@ -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;