@vgai/engine 0.5.15 → 0.5.17

package/dist/runtime/create-runtime.js

@@ -14,12 +14,11 @@ import { installRenderControlHarness, isRenderModeRequested } from './render-con
  * by `createGameRuntime` and every headless test harness
  * (`test/game-root.test.ts`, `test/frame-order.test.ts`,
  * `test/game-two-roots.test.ts`) so there is exactly one code path for this
- * wiring (T7.1 slice 1, id-generalized in slice 3 for the two-world proof — stage
- * 3) — `physics`/`collisions`/`camera`/ `frame` are populated from the mount's
+ * wiring. `physics`/`collisions`/`camera`/`frame` are populated from the mount's
  * first-party `GameContext`/ `MountedSetupThreeRoot` when available, left
  * `undefined` otherwise (an external adapter's mount has none of these
  * first-party handles — `frame` in particular is what makes
- * `GameInternal.runFrame` (T7.1 slice 2) fall back to a single opaque
+ * `GameInternal.runFrame` fall back to a single opaque
  * `mounted.update` call per substep for such a world).
  */
 function firstPartyExtras(mounted) {
@@ -34,10 +33,8 @@ function firstPartyExtras(mounted) {
 }
 /**
  * Register a three world onto the Game shell. `opts.id` defaults to
- * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
- * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
- * real multi-world manifests later) pass an explicit id. This is the ONE
- * registration code path for a three world, whatever its id.
+ * `'main'`; multi-root callers pass an explicit id. This is the one
+ * registration path for a three world, whatever its id.
  */
 export function registerThreeRoot(game, adapter, mounted, opts) {
     const world = createRootInstance({
@@ -73,13 +70,13 @@ export function registerPixiRoot(game, adapter, mounted, opts) {
     return world;
 }
 /**
- * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * Register a React world onto the Game shell — the DOM
  * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
  * world has no `frame` hooks (react's own
  * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
  * leaves a world with no `frame` untouched by its opaque-`update` fallback
  * too, since `MountedReactGame` declares no `update`). `adapter` is typed
- * as the real {@link ReactRootAdapter} shape (T7.5, same reasoning as
+ * as the real {@link ReactRootAdapter} shape (same reasoning as
  * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
@@ -106,7 +103,7 @@ export async function createGameRuntime(config) {
     return createRootsGameRuntime(config);
 }
 // ---------------------------------------------------------------------------
-// Worlds path (T6.1 slice 1)
+// Universal root host
 // ---------------------------------------------------------------------------
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
  *  roots — mirrors `SetupThreeRootAdapter.mount`'s own `headlessComposer`
@@ -162,11 +159,8 @@ async function mountOneThreeRoot(spec, ctx) {
     // resize-staleness (the roots-path `resize()` below always calls
     // `setSize(rw, rh, false)`, so nothing else was ever going to update this
     // canvas' CSS after mount). `createHostRenderer`'s own default
-    // (`updateStyle:true`) is intentionally left alone — the LEGACY
-    // single-canvas path (editor play-mode's non-multi-world branch) still
-    // relies on that construction-time stamp + its own later `updateStyle:true`
-    // resizes for byte-identical behavior; this fix touches only the
-    // roots-path canvas, after the fact.
+    // (`updateStyle:true`) is intentionally left alone; the host owns CSS layout
+    // and reasserts the container-relative size after renderer construction.
     canvas.style.width = '100%';
     canvas.style.height = '100%';
     renderer.setPixelRatio(dpr);
@@ -239,7 +233,7 @@ async function mountOnePixiRoot(spec, ctx) {
     };
 }
 /**
- * Mount one react `RootMountSpec` (T6.2 slice 1) — the react sibling of
+ * Mount one React `RootMountSpec` — the DOM sibling of
  * `mountOneThreeRoot`/`mountOnePixiRoot`. Unlike its canvas-backed siblings
  * this returns NO `routerEntry`: a react world's DOM-root layer participates in
  * D5's z-order/box stacking (the caller still creates and positions its `<div>`
@@ -269,7 +263,7 @@ layer) {
     // An absolutely-positioned layer with no width/height collapses to zero
     // content size, so a child's
     // own position:absolute offsets resolve against a degenerate containing
-    // block (found by the T6.2 slice-3 e2e — clicks landed outside the game).
+    // block; otherwise clicks land outside the game.
     layer.style.width = '100%';
     layer.style.height = '100%';
     const reactHost = { container: layer, game };
@@ -289,8 +283,8 @@ layer) {
     };
 }
 /**
- * The roots-path implementer behind {@link createGameRuntime} (T6.1 slice
- * 1; react roots added T6.2 slice 1). Builds ONE surface per world — a
+ * The universal host implementer behind {@link createGameRuntime}. It builds
+ * one surface per world — a
  * canvas for three/canvas, a DOM-root `<div>` layer for react — stacked
  * per D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
@@ -303,16 +297,11 @@ layer) {
  */
 /**
  * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the roots
- * path's DEFAULT world (E4) — split out of `createRootsGameRuntime` purely
- * to keep that function's own cyclomatic complexity down. Mirrors the
- * legacy single-world path's identical exposure (above, in this same file),
- * using the SAME "first three world, else none" default-world rule the
- * `GameSession.scene`/`.camera` getters alias (`Game.defaultRoot`): a
- * non-threejs default world (or none at all) publishes neither global,
- * exactly like those getters return `undefined` in that case. Returns a
- * retraction callback — identity-guarded (a newer session's globals must
- * never be clobbered by an older session's stop, same reason the legacy
- * path's own cleanup guards it) — that is a no-op when nothing was
+ * path's default world — split out of `createRootsGameRuntime` purely
+ * to keep that function's own cyclomatic complexity down. It uses the
+ * "first three world, else none" rule: a non-Three default world publishes
+ * neither global. Returns an identity-guarded retraction callback so an
+ * older session's stop cannot clobber a newer session's globals. It is a no-op when nothing was
  * published (non-DEV build, or non-threejs default world).
  */
 function installDefaultRootDevGlobals(game) {
@@ -451,26 +440,15 @@ async function createRootsGameRuntime(config) {
     // --- Surface stack (D5 §1): DOM/z-order follows zOrder, ties -> array order
     // — computed FIRST (bottom -> top) so both the z-index assignment below and
     // the router's default-claim rule share one definition. A react world's
-    // DOM-root layer shares this SAME stacking pass (T6.2 slice 1 — "one
-    // stacking model, no special case") even though it is a `<div>`, not a
+    // 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]));
     const surfacesById = new Map();
@@ -485,12 +463,6 @@ async function createRootsGameRuntime(config) {
         // 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;
             canvas.width = w;
@@ -509,7 +481,7 @@ async function createRootsGameRuntime(config) {
         // too (not just in `mountOneThreeRoot`) means every surface, whatever
         // kind, starts container-relative from its very first paint, before any
         // per-kind mount work has even run.
-        // `contain:layout paint` makes each surface the CONTAINING BLOCK for
+        // `contain:layout paint` makes each surface the containing block for
         // `position:fixed` descendants (and clips overflow to the world's
         // rectangle): full-screen game UI written the natural way (`fixed;
         // inset:0`) then fills the WORLD, not the page. Without it, `fixed` UI
@@ -579,17 +551,7 @@ async function createRootsGameRuntime(config) {
     const router = createInputRouter(container, routerEntries);
     started = true;
     loop.start();
-    // Expose scene & camera for dev tools / e2e tests — mirrors the legacy
-    // single-world path's identical dev-only exposure above, generalized to
-    // the roots path's DEFAULT world (E4): `mountGameFromManifest`/
-    // `mountManifestRoots` route every caller (including a
-    // single-threejs-world scaffold project) through THIS path, so a caller
-    // migrating off the legacy `{canvas, adapter}` call must not silently
-    // lose `window.__vgaiScene`/`__vgaiCamera` — real e2e/dev tooling
-    // depends on them
-    // (`packages/editor/e2e/tests/04-standalone-game.spec.ts`). Split into
-    // its own top-level helper (with its retraction counterpart below)
-    // purely to keep this function's own cyclomatic complexity down.
+    // Expose the default Three root's scene and camera for dev/e2e tooling.
     const retractDevGlobals = installDefaultRootDevGlobals(game);
     // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
     // host. Installed at the TAIL of the mount (same position as
@@ -599,39 +561,48 @@ async function createRootsGameRuntime(config) {
     const retractRenderHarness = renderMode && renderModeLocation !== undefined
         ? installSessionRenderHarness(game, renderModeLocation, config.renderControl?.target)
         : undefined;
+    let resolveStopComplete;
+    const stopComplete = new Promise((resolve) => {
+        resolveStopComplete = resolve;
+    });
+    let stopping = false;
     function fullCleanup() {
-        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,
-        // D10/T7.6: `Game.play` fans out per-world pausable/loop-gate/audio-gate
-        // semantics itself now (see the legacy path's identical comment above) —
-        // a `pausable: false` world (a menu/HUD world) keeps ticking while every
-        // other world freezes, which the old blind `for (const entry of
-        // mountedEntries) entry.mounted.setPaused?.(true)` fan-out (with no
-        // `pausable` check at all) could never express.
+        stopComplete,
+        // `Game.play` owns per-world pause, loop-gate, and audio-gate semantics.
         pause() {
             game.play.pause();
         },
@@ -655,24 +626,6 @@ async function createRootsGameRuntime(config) {
                 entry.mounted.resize?.(safeWidth, safeHeight);
             }
         },
-        // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultRoot` (T6.1
-        // slice 1's "first three world, else first world" rule) — a legacy
-        // convenience shaped for the threejs-only past. T7.5 narrows the read via
-        // the `kind` discriminant instead of a blind `.scene`/`.camera` cast
-        // through a nonexistent property (identical behavior to before: still
-        // `undefined` for a roots-path session whose default world isn't
-        // three — real per-world surface routing for that case is T7.6's).
-        get scene() {
-            const m = game.defaultRoot.mounted;
-            return (m.kind === 'three' ? m.scene : undefined);
-        },
-        get camera() {
-            const m = game.defaultRoot.mounted;
-            return (m.kind === 'three' ? m.camera : undefined);
-        },
-        get mounted() {
-            return game.defaultRoot.mounted;
-        },
         game,
     };
 }

package/dist/runtime/dev-build.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function devBuildEnabled(override?: boolean | undefined): boolean;
+//# sourceMappingURL=dev-build.d.ts.map

package/dist/runtime/dev-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-build.d.ts","sourceRoot":"","sources":["../../src/runtime/dev-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAavE"}

package/dist/runtime/dev-build.js

@@ -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) {
+    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.env;
+    if (env?.DEV === true)
+        return true;
+    return env?.VITE_VGAI_DEV_BUILD === 'true';
+}

package/dist/runtime/game.d.ts

@@ -1,22 +1,8 @@
 /**
- * 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.
  */
 import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
@@ -33,7 +19,6 @@ import { InputManager } from '../input/input-manager';
 import type { CollisionSystem } from '../physics/collision-system';
 import type { PhysicsRegistry } from '../physics/physics-registry';
 import type { Physics2DRegistry } from '../pixi/physics-registry';
-import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import { type RunTicksOptions } from './debug-registry';
 import { type GameStateBridge } from './state-bridge';
 import type { GameContext, PlaytestContext } from './types';
@@ -54,10 +39,7 @@ export type GameLoop = ReturnType<typeof createGameLoop>;
  * `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
@@ -95,11 +77,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
@@ -107,7 +87,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
@@ -116,7 +96,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
@@ -126,14 +106,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
@@ -157,7 +135,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
@@ -176,7 +154,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
@@ -229,8 +207,8 @@ export declare 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
@@ -275,13 +253,9 @@ export interface DebrisOwner {
  */
 export declare function disposeDebrisSubtree(obj: THREE.Object3D, owners: ReadonlyArray<DebrisOwner>): void;
 /**
- * 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;
@@ -291,18 +265,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>;
@@ -338,9 +310,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
@@ -421,28 +390,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
@@ -459,7 +418,6 @@ export interface GameInternal extends Game {
      * `runTicks` sets it per tick for its `render: 'none' | 'last'` modes.
      */
     runFrame(dt: number, opts?: {
-        ignorePause?: boolean;
         skipRenderPhases?: boolean;
     }): void;
     /**
@@ -546,8 +504,16 @@ 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;
 }