@vgai/engine 0.5.21 → 0.5.23

package/src/runtime/game.ts

@@ -12,9 +12,9 @@
 import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import type { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
+import type { RootBinding } from '../adapter/binding';
 import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
 import type { MountedRoot } from '../adapter/root-adapter';
-import type { MountedSetupThreeRoot } from '../adapter/setup-three-root-adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import type { AssetCache } from '../assets';
 import type { createGameLoop } from '../core/game-loop';
@@ -41,15 +41,15 @@ import {
   registerDebugRegistry,
 } from './debug-registry';
 import { createGameplayRngTrap, registerGameplayRngTrapControl } from './gameplay-rng-trap';
+import type { PlaytestContext } from './playtest';
 import { createStateBridge, type GameStateBridge } from './state-bridge';
-import type { GameContext, PlaytestContext } from './types';
 
 /** The one loop type — `createGameLoop`'s return shape (fixed-step sim,
- *  display-rate presentation since WO-P13). */
+ *  display-rate presentation). */
 export type GameLoop = ReturnType<typeof createGameLoop>;
 
 /**
- * WO-P13 — the tail of `PHASE_ORDER` that presents rather than simulates, and
+ * The tail of `PHASE_ORDER` that presents rather than simulates, and
  * therefore runs once per DISPLAY frame (`runRenderFrameImpl`) rather than
  * once per fixed substep. The same two phases `runTicks`' `skipRenderPhases`
  * fast-forward skips and `render-control.ts`'s `renderOnce()` drives — one
@@ -68,10 +68,10 @@ const DISPLAY_RATE_PHASES: readonly SystemPhaseName[] = PHASE_ORDER.filter(
  * freezes. A paused-and-pausable world's `render` phase still runs (with `dt`
  * forced to `0`, so time-based render effects — e.g. a post-processing pass with
  * its own internal clock — don't silently keep animating under a "frozen" scene)
- * — simulation freezes, the screen does not go black. WO-P13 changed only the
- * CADENCE of that: once per display frame under a host that drives
- * `runRenderFrame`, once per substep under one that still renders inside
- * `runFrame`. `GameLoop.timeScale` (unaffected by this) remains the orthogonal
+ * — simulation freezes, the screen does not go black. That render runs once per
+ * display frame under a host that drives `runRenderFrame`, and once per substep
+ * under one that still renders inside
+ * `runFrame`. `GameLoop.timeScale` 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.
@@ -119,7 +119,7 @@ export interface PlayState {
  * `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
- * (`ecs/behavior.ts`, `ecs/component-manager.ts`) compiling unchanged.
+ * compiling unchanged.
  */
 export type AdapterSurface = AdapterSurfaceLeaf;
 
@@ -145,6 +145,24 @@ export interface RootFrameHooks {
 /**
  * A single world instance: the unit of adaptation.
  */
+/**
+ * One `SystemAdapters` slot a mounted root's `systems` table answered with
+ * `absent(reason)` (`adapter/system-slot.ts`) — a POSITIVE absence.
+ *
+ * Nothing is installed for it. It exists so a reader can tell "this game has no
+ * physics" from "nobody looked", which the adapter bag alone cannot do: an
+ * unfilled slot has the same shape for both, and only one of them is a work
+ * order.
+ */
+export interface DeclaredSystemAbsence {
+  /** The root whose declaration answered — absences are declared per root, and
+   *  the slot is only truly absent when NO root fills it. */
+  readonly rootId: string;
+  readonly slot: keyof SystemAdapters;
+  /** The game's own words: what was searched, and what was found. */
+  readonly reason: string;
+}
+
 export interface RootInstance {
   /** Manifest root id. */
   readonly id: string;
@@ -198,6 +216,39 @@ export interface RootInstance {
    *  instead (unless it `drivesOwnLoop`, in which case it isn't ticked at
    *  all — see `runFrame`). */
   readonly frame?: RootFrameHooks | undefined;
+  /** True from the moment this world's `mounted.dispose()` runs. There is no
+   *  `unregisterRoot`, so a disposed world stays in `Game.roots`; `runFrame`
+   *  reads this to skip it entirely — frame hooks AND the opaque
+   *  `mounted.update` fallback (see the disposed-world guard in
+   *  `createRootInstance`). */
+  readonly disposed: boolean;
+  /**
+   * THIS ROOT'S WHOLE DECLARATION, BOUND — `adapter/binding.ts`'s
+   * {@link RootBinding}, assembled at registration from this instance's own
+   * `adapter`/`mounted`/`pausable` plus the {@link RootDeclaration} the
+   * resolver produced. Every member of it is a reference to something already
+   * reachable through the fields above; it is the ONE place the five protocol
+   * families are addressed by name rather than re-assembled per consumer.
+   *
+   * `null` in exactly ONE honest case, and never as a degrade: the
+   * registration carried NO declaration — a bare
+   * `registerThreeRoot(game, adapter, mounted)` from a test harness, or a
+   * `mountManifestRoots` caller that supplied an already-constructed adapter
+   * with no entry namespace behind it. There is no manifest root, no parsed
+   * definition and no entry surface to bind, and fabricating them would be
+   * the anti-shim rule broken at the seam that exists to hold it. Every root
+   * the editor resolves through `resolveAllRoots`/`resolveAllRootEntries`
+   * carries a declaration, so its binding is non-null.
+   *
+   * A mount that exposes no `authoring` does NOT null this out; it costs that
+   * root its `projection` and `truth` members only (see
+   * {@link RootBinding.projection}). That distinction is load-bearing: the
+   * editor supplies native TSX roots' authoring itself, so treating an
+   * absent `mounted.authoring` as an absent BINDING made `binding` null for
+   * every first-party root and left four perfectly constructible families
+   * unreadable.
+   */
+  readonly binding: RootBinding | null;
 }
 
 /**
@@ -236,6 +287,9 @@ export interface RootInstanceInit {
   readonly physics2d?: Physics2DRegistry | undefined;
   readonly camera?: unknown;
   readonly frame?: RootFrameHooks | undefined;
+  /** This root's bound declaration — see {@link RootInstance.binding} for
+   *  when it is legitimately absent. */
+  readonly binding?: RootBinding | null | undefined;
 }
 
 /**
@@ -259,6 +313,7 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
     physics2d,
     camera,
     frame,
+    binding = null,
   } = init;
 
   // A three world with no scene has nothing for `threeScene()` to return —
@@ -302,11 +357,11 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
   // read, so this wraps `mounted.dispose` in place (mutating the SAME mount
   // object every holder of `mounted` shares — calling `mounted.dispose()`
   // directly, exactly like calling `world.mounted.dispose()`, trips this)
-  // to flip a private flag, and wraps the frame hooks so they silently no-op
-  // once that flag is set. `runFrame` itself needs no knowledge of disposal
-  // — a disposed world is skipped by construction from the next call
-  // onward. (The opaque-world `mounted.update` fallback path is unaffected
-  // by this guard — no opaque-mount two-world scenario exists yet to need it.)
+  // to flip a flag this instance exposes as `disposed`, and wraps the frame
+  // hooks so they silently no-op once it is set. `runFrame` reads `disposed`
+  // and skips the world outright, which is what also covers the OPAQUE
+  // `mounted.update` fallback — the path every three root takes now that a
+  // mount is a plain `RootAdapter` with no phase-partitioned entry point.
   let disposed = false;
   const originalDispose = mounted.dispose.bind(mounted);
   mounted.dispose = () => {
@@ -337,6 +392,10 @@ export function createRootInstance(init: RootInstanceInit): RootInstance {
     physics2d,
     camera,
     frame: guardedFrame,
+    binding,
+    get disposed(): boolean {
+      return disposed;
+    },
     threeScene(): THREE.Scene {
       if (kind !== 'three' || !scene) {
         throw new Error(
@@ -374,26 +433,9 @@ 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` 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
- * mounted` — a foreign mount may carry an unrelated `ctx` key, so a
- * structural `'ctx' in mounted` check would misfire. The probe is a plain property read, not an
- * `instanceof`/value import of `setup-three-root-adapter.ts` — the
- * `MountedSetupThreeRoot` import above stays type-only.
- */
-export function isFirstPartyMounted(mounted: MountedRoot): mounted is MountedSetupThreeRoot {
-  return (mounted as { firstParty?: unknown }).firstParty === true;
-}
-
 /**
  * One world's half of a debris disposal, as {@link disposeDebrisSubtree} needs
- * it. A first-party `GameContext` satisfies this structurally.
+ * it.
  *
  * `physics`/`rapierWorld` are OPTIONAL: an owner that builds no first-party
  * Rapier runtime (an R3F world) carries neither, and {@link
@@ -401,8 +443,8 @@ export function isFirstPartyMounted(mounted: MountedRoot): mounted is MountedSet
  * unconditionally.
  */
 export interface DebrisOwner {
-  readonly physics?: GameContext['physics'];
-  readonly rapierWorld?: GameContext['rapierWorld'];
+  readonly physics?: PhysicsRegistry;
+  readonly rapierWorld?: import('@dimforge/rapier3d-compat').World;
 }
 
 /**
@@ -412,7 +454,7 @@ export interface DebrisOwner {
  */
 function readRapierHandles(owner: DebrisOwner): {
   physics: NonNullable<DebrisOwner['physics']>;
-  rapierWorld: GameContext['rapierWorld'];
+  rapierWorld: NonNullable<DebrisOwner['rapierWorld']>;
 } | null {
   const { physics, rapierWorld } = owner;
   if (!physics || !rapierWorld) return null;
@@ -424,15 +466,14 @@ function readRapierHandles(owner: DebrisOwner): {
  * only *when*; this is the *what*, and it lives here because it is the runtime
  * that knows about Rapier and shared geometry.
  *
- * The order mirrors `adapter/setup-three-root-adapter.ts`'s world teardown for
+ * The order mirrors `adapter/world3d-react/r3f-root-factory.tsx`'s world teardown for
  * ONE subtree. Within the physics step,
  * `rapierWorld.removeRigidBody(body)` comes BEFORE `physics.remove(node)`: the
  * registry's `remove()` only drops index entries, so reversing the two leaks
  * the Rapier body.
  *
- * `owners` is every world that could own part of the subtree — `createGame`
- * passes all of its first-party three roots as their `GameContext`, a bare
- * adapter mount passes its own ctx. `physics.get` is a no-op for a node the
+ * `owners` is every world that could own part of the subtree. `physics.get`
+ * is a no-op for a node the
  * owner does not own, so offering the subtree to each is safe.
  *
  * Safe on an object already removed or already disposed: `removeFromParent` on
@@ -473,13 +514,17 @@ export function disposeDebrisSubtree(
 }
 
 /**
- * The {@link DebrisOwner}s one registered world contributes: its `GameContext`
- * when the mount is first-party, else nothing. Written as a standalone function
+ * The {@link DebrisOwner}s one registered world contributes. Written as a
+ * standalone function
  * so `createGame`'s clock disposer is one line and the "which mounts count"
  * rule has exactly one home.
  */
-function debrisOwnersOf(world: RootInstance): DebrisOwner[] {
-  return isFirstPartyMounted(world.mounted) ? [world.mounted.ctx] : [];
+function debrisOwnersOf(_world: RootInstance): DebrisOwner[] {
+  // No mount carries first-party Rapier handles: physics is a declared
+  // system built inside the world's own tree, and the library owns its
+  // bodies' lifecycles there. The owner list stays as the disposal seam's
+  // shape; today it is always empty.
+  return [];
 }
 
 /**
@@ -499,13 +544,13 @@ export interface Game {
    * 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
+   * `ctx.systems.add`, which stays world-bound to the default world).
+   * Empty for every existing game (nothing registers
    * against it), so an empty runner has no frame cost beyond dispatch.
    */
   readonly systems: SystemRunner;
   /** Declaration-ordered. This is the same array reference `registerRoot`
-   *  mutates, not a snapshot, so holders (e.g. `GameContext.roots`) observe
+   *  mutates, not a snapshot, so holders observe
    *  later registrations. */
   readonly roots: ReadonlyArray<RootInstance>;
   world(id: string): RootInstance | null;
@@ -538,6 +583,36 @@ export interface Game {
   readonly systemAdapters: SystemAdapters;
   /** Subscribe when a mounted root registers or replaces a system adapter. */
   subscribeSystemAdapters?(listener: () => void): () => void;
+  /**
+   * Install a root's STATICALLY DECLARED system-adapter slots — the native
+   * module surface's `export const systems` (adapter/native-debug-module.ts),
+   * already validated by `contract-system-adapters.ts`. The host calls this
+   * once per declaring root at mount; project components never do
+   * (ARCHITECTURE-CORE §System adapters: "Components never call
+   * `registerSystemAdapter`" — this door is the replacement, and the slots it
+   * installs take precedence over a component registration for the same root
+   * in {@link systemAdapters}'s merge, with the standard collision warning).
+   * Throws on an unmounted root id or a second declaration for the same root.
+   * Optional for the same reason {@link subscribeSystemAdapters} is: partial
+   * `Game` doubles in tests; `installNativeSystemsBindings` refuses loudly
+   * when the hosting Game lacks it.
+   */
+  installDeclaredSystemAdapters?(
+    rootId: string,
+    slots: Readonly<Partial<SystemAdapters>>,
+    absent?: readonly DeclaredSystemAbsence[],
+  ): void;
+  /**
+   * Every slot a mounted root's `systems` table answered with `absent(reason)`,
+   * across all roots — the game-scoped read of the positive absences.
+   *
+   * This is what separates "this game has no networking" from "nobody looked",
+   * and it is the ONLY source for that distinction on a native mount: the
+   * adapter bag ({@link systemAdapters}) can only say a slot is unfilled, which
+   * is the same shape for both. Empty means no root declared any absence — NOT
+   * that every slot is answered.
+   */
+  readonly declaredSystemAbsences?: readonly DeclaredSystemAbsence[];
   /** The one game-owned `InputManager`, shared by every first-party root. */
   readonly input: InputManager;
   /**
@@ -552,7 +627,7 @@ export interface Game {
   /** Game-level play-state control surface (D10, T7.6) — see {@link PlayState}. */
   readonly play: PlayState;
   /**
-   * WO-P13 — the interpolation alpha the most recent display frame presented
+   * The interpolation alpha the most recent display frame presented
    * at: `accumulator / fixedDt`, in `[0, 1]`. `0` means "exactly on the last
    * completed fixed state", `0.5` means "halfway to the next one".
    *
@@ -564,7 +639,7 @@ export interface Game {
    */
   readonly renderAlpha: number;
   /**
-   * WO-P13 — the `RenderStepped`-shaped host: register a callback that runs
+   * The `RenderStepped`-shaped host: register a callback that runs
    * ONCE PER DISPLAY FRAME, before that frame's `preRender`/`render` phases,
    * with `(alpha, displayDt)`.
    *
@@ -639,19 +714,19 @@ export interface GameInternal extends Game {
    * touches no other world at all — a natural no-op while not paused, since
    * the frozen set is then empty.
    *
-   * WO-P13 addendum: `opts.skipRenderPhases` omits `preRender`+`render` from
+   * `opts.skipRenderPhases` omits `preRender`+`render` from
    * the pass — every other phase, and `endFrame`, run exactly as always. A
    * host that drives presentation at DISPLAY rate sets it on every substep
    * and calls {@link runRenderFrame} once per real frame instead
    * (`create-runtime.ts`). A host that does
-   * not set it keeps the pre-WO-P13 shape verbatim — which is why
+   * not set it renders inside the substep — which is why
    * `externalDrive` capture (`render-control.ts`'s `simulateSubsteps`, which
-   * calls `runFrame(fixedDt)` with no opts) is frame-exact and unchanged.
+   * calls `runFrame(fixedDt)` with no opts) is frame-exact.
    * `runTicks` sets it per tick for its `render: 'none' | 'last'` modes.
    */
   runFrame(dt: number, opts?: { skipRenderPhases?: boolean }): void;
   /**
-   * WO-P13 — run ONE display frame's presentation pass: the registered
+   * Run ONE display frame's presentation pass: the registered
    * `onRenderStep` callbacks, then the `preRender` and `render` phases across
    * game-scoped systems and every host-driven world, in the same
    * game-systems-then-worlds order {@link runFrame} uses.
@@ -726,8 +801,8 @@ export interface GameInternal extends Game {
   runTicks(n: number, opts?: RunTicksOptions): void;
   /**
    * ADAPTER-MOUNT surface, not game-facing: an adapter's `mount()` calls
-   * this (via `host.game` — the classic `SetupThreeRootAdapter` and the R3F
-   * `createR3FRootContext` both do) to load the game-owned input map ONCE,
+   * this (via `host.game` — the R3F
+   * `createR3FRootContext` does) to load the game-owned input map ONCE,
    * even when several roots ask for the same path; competing paths throw
    * (input is game-owned, so roots cannot load competing maps). GAME code
    * never calls this — a project's map loads automatically at mount from
@@ -774,7 +849,7 @@ export function createGame(opts: {
   const input = new InputManager();
   const stateBridge = createStateBridge();
   // D15 (T-D15.1) — the game-scoped seeded-random surface every world's
-  // `ctx.random` aliases (see `setup-three-root-adapter.ts`'s `ctx.random =
+  // `ctx.random` aliases (see `world3d-react/r3f-root-factory.tsx`'s `ctx.random =
   // ...`, wired the same way `ctx.debug` is just below). Constructed
   // unconditionally (cheap — a handful of closures) regardless of whether
   // this project ever declares `determinism.seededRandom`; only the BOOT
@@ -807,7 +882,7 @@ export function createGame(opts: {
   // the CURRENT values.
   let tick = 0;
   let simT = 0;
-  // WO-P13 — the display-rate half. `renderAlpha` is the last alpha
+  // The display-rate half. `renderAlpha` is the last alpha
   // `runRenderFrameImpl` presented at (0 until a host drives one); the set is
   // the `RenderStepped`-shaped registry `Game.onRenderStep` feeds. Deliberately
   // NOT beside `tick`/`simT` in meaning: neither of these ever advances sim
@@ -823,7 +898,7 @@ export function createGame(opts: {
   //
   // The disposer is supplied HERE rather than inside the clock because
   // `core/sim-clock.ts` deliberately knows nothing about Rapier or shared
-  // geometry. It mirrors `setup-three-root-adapter.ts`'s world teardown
+  // geometry. It mirrors `world3d-react/r3f-root-factory.tsx`'s world teardown
   // ordering for ONE subtree.
   const simClock: SimClockInternal = createSimClock({
     // Every mount that could own part of the subtree is offered it:
@@ -881,7 +956,17 @@ export function createGame(opts: {
   // above's "once per game instance" idiom.
   const warnedSystemAdapterKeys = new Set<string>();
   const systemAdapterListeners = new Set<() => void>();
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
+  /** Per-root slots installed by `installDeclaredSystemAdapters` — the native
+   *  module surface's static `systems` declaration. Merged BEFORE the same
+   *  root's live `mounted.systems` below, so during migration a lingering
+   *  component registration for a declared slot is shadowed (with the
+   *  standard warning) rather than silently winning by running later. */
+  const declaredSystemAdapters = new Map<string, Readonly<Partial<SystemAdapters>>>();
+  /** Per-root POSITIVE ABSENCES from the same declaration — `absent(reason)`
+   *  slots. Nothing binds them (there is nothing to bind); they are kept so a
+   *  reader can tell an answered absence from an unasked question. */
+  const declaredAbsences = new Map<string, readonly DeclaredSystemAbsence[]>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-source × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
   function computeSystemAdapters(): SystemAdapters {
     // Debug is game-scoped: React hooks, probes, and the built-in time
     // provider all register with the one registry created above, regardless
@@ -891,9 +976,11 @@ export function createGame(opts: {
     // intentional shared registration it is.
     const result: SystemAdapters = { debug: debugRegistry.adapter };
     const ownerRootId = new Map<string, string>([['debug', '(game)']]);
-    for (const world of roots) {
-      const adapters = world.mounted.systems;
-      if (!adapters) continue;
+    const merge = (
+      owner: string,
+      adapters: Readonly<Partial<SystemAdapters>>,
+      quietKeys?: ReadonlySet<string>,
+    ): void => {
       for (const key of Object.keys(adapters) as (keyof SystemAdapters)[]) {
         if (adapters[key] === undefined) continue;
         const existingOwner = ownerRootId.get(key);
@@ -903,12 +990,19 @@ export function createGame(opts: {
           // object under `systems.debug` — that is by design, not a
           // collision, so it must never warn.
           if (result[key] === adapters[key]) continue;
+          // A world's own DECLARED slot overriding that same world's
+          // substrate-seeded default (the three lane pre-seeds physics/audio/
+          // renderDebug into `mounted.systems`) is the door working as
+          // intended, not a collision — same silence `ctx.
+          // registerSystemAdapter` gives the same override. Cross-root
+          // collisions still warn.
+          if (quietKeys?.has(key)) continue;
           if (!warnedSystemAdapterKeys.has(key)) {
             warnedSystemAdapterKeys.add(key);
             // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
             console.warn(
-              `[game] systemAdapters: "${key}" is registered by both world "${existingOwner}" and ` +
-                `world "${world.id}" — the FIRST registration ("${existingOwner}") wins; the later ` +
+              `[game] systemAdapters: "${key}" is registered by both ${existingOwner} and ` +
+                `${owner} — the FIRST registration (${existingOwner}) wins; the later ` +
                 'one is shadowed (game-scoped system adapters).',
             );
           }
@@ -916,7 +1010,19 @@ export function createGame(opts: {
         }
         // biome-ignore lint/suspicious/noExplicitAny: SystemAdapters is a plain optional-field record; the per-key copy is correct by construction (same key on both sides), just not expressible without a cast
         (result as any)[key] = adapters[key];
-        ownerRootId.set(key, world.id);
+        ownerRootId.set(key, owner);
+      }
+    };
+    for (const world of roots) {
+      const declared = declaredSystemAdapters.get(world.id);
+      if (declared) merge(`world "${world.id}" (declared systems export)`, declared);
+      const adapters = world.mounted.systems;
+      if (adapters) {
+        merge(
+          `world "${world.id}"`,
+          adapters,
+          declared ? new Set(Object.keys(declared)) : undefined,
+        );
       }
     }
     return result;
@@ -952,6 +1058,13 @@ export function createGame(opts: {
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fans out TWO independent capability gates (loop, audio) with the same "call it, else report once" shape per world — splitting the two gates into separate loops would duplicate the fan-out, not reduce real complexity
   function setRootGates(next: boolean): void {
     for (const world of roots) {
+      // A disposed world stays in `roots` (there is no `unregisterRoot`), and
+      // its adapter's `setPaused`/`systems.audio` reach a renderer, ticker or
+      // audio graph that `dispose()` already released — the same reason
+      // `runFrame`/`runRenderFrame`/`runTicks` skip it. Without this, a
+      // pause/resume after a partial teardown calls into freed resources, and
+      // the audio leg re-mutes a context that no longer exists.
+      if (world.disposed) continue;
       if (!world.pausable) continue; // pausable:false roots are untouched by design
       if (world.mounted.drivesOwnLoop) {
         if (world.mounted.setPaused) {
@@ -986,14 +1099,14 @@ export function createGame(opts: {
     // declare `determinism.seededRandom`).
     if (rngTrapEnabled) rngTrap.enable();
     profiler.beginFrame();
-    // D15/T-D15.4 + WO-P13: the render-phase skip. Two callers set it, for the
+    // 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
     // want to paint (see `runTicks`'s doc comment on `GameInternal`), and a
     // DISPLAY-RATE host sets it on every substep because `runRenderFrame`
-    // paints once per real frame instead. Unlike `onlyFrozen` below it is no
-    // longer internal-only: it is part of the public `GameInternal.runFrame`
-    // signature, since an external host is now one of those two callers.
+    // paints once per real frame instead. Unlike `onlyFrozen` below it is not
+    // internal-only: it is part of the public `GameInternal.runFrame`
+    // signature, since an external host is one of those two callers.
     const skipRenderPhases = frameOpts?.skipRenderPhases ?? false;
     // `onlyFrozen` is internal-only (not part of the public `GameInternal.runFrame`
     // signature — no external caller sets it) — `Game.play.step()` below is the
@@ -1011,6 +1124,7 @@ export function createGame(opts: {
     inputFrameActive = false;
     for (let i = 0; i < n; i++) {
       const world = roots[i]!;
+      if (world.disposed) continue;
       if (onlyFrozen) {
         if (paused && world.pausable && !world.mounted.drivesOwnLoop) {
           inputFrameActive = true;
@@ -1040,6 +1154,7 @@ export function createGame(opts: {
     if (!onlyFrozen) {
       for (let i = 0; i < n; i++) {
         const world = roots[i]!;
+        if (world.disposed) continue;
         if (!world.mounted.drivesOwnLoop) continue;
         if (!paused || !world.pausable || !world.mounted.setPaused) {
           advanced = true;
@@ -1064,6 +1179,7 @@ export function createGame(opts: {
         if (inputFrameActive) systems.runPhase(phase, dt);
         for (let i = 0; i < n; i++) {
           const world = roots[i]!;
+          if (world.disposed) continue;
           if (world.mounted.drivesOwnLoop) continue;
           if (!(paused && world.pausable)) continue; // only the frozen set
           try {
@@ -1080,6 +1196,7 @@ export function createGame(opts: {
       }
       for (let i = 0; i < n; i++) {
         const world = roots[i]!;
+        if (world.disposed) continue;
         if (world.mounted.drivesOwnLoop) continue;
         if (!(paused && world.pausable)) continue;
         advanced = true;
@@ -1116,6 +1233,7 @@ export function createGame(opts: {
           systems.runPhase(phase, dt);
           for (let i = 0; i < n; i++) {
             const world = roots[i]!;
+            if (world.disposed) continue;
             if (world.mounted.drivesOwnLoop) continue;
             // D10/T7.6: a `pausable` world under an active pause
             // skips every phase except `render` — its render still runs, every
@@ -1143,6 +1261,7 @@ export function createGame(opts: {
       }
       for (let i = 0; i < n; i++) {
         const world = roots[i]!;
+        if (world.disposed) continue;
         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.
@@ -1196,7 +1315,7 @@ export function createGame(opts: {
   }
 
   /**
-   * WO-P13 — one display frame's PRESENTATION pass. See
+   * One display frame's PRESENTATION pass. See
    * `GameInternal.runRenderFrame`'s doc comment for the contract; this is the
    * `preRender`+`render` slice of `runFrameImpl`'s phase loop, lifted out and
    * driven by the loop's own per-real-frame callback instead of by the substep
@@ -1244,6 +1363,7 @@ export function createGame(opts: {
       systems.runPhase(phase, displayDt);
       for (let i = 0; i < n; i++) {
         const world = roots[i]!;
+        if (world.disposed) continue;
         if (world.mounted.drivesOwnLoop) continue;
         // D10/T7.6, carried over verbatim in substance: a frozen world still
         // renders (a paused viewport stays painted) but with `dt` forced to
@@ -1292,6 +1412,34 @@ export function createGame(opts: {
     notifySystemAdaptersChanged() {
       for (const listener of systemAdapterListeners) listener();
     },
+    get declaredSystemAbsences() {
+      return [...declaredAbsences.values()].flat();
+    },
+    installDeclaredSystemAdapters(
+      rootId: string,
+      slots: Readonly<Partial<SystemAdapters>>,
+      absent: readonly DeclaredSystemAbsence[] = [],
+    ) {
+      if (!roots.some((w) => w.id === rootId)) {
+        throw new Error(
+          `installDeclaredSystemAdapters: no mounted root is named "${rootId}" ` +
+            `(mounted: ${roots.map((w) => `"${w.id}"`).join(', ') || 'none'}).`,
+        );
+      }
+      if (declaredSystemAdapters.has(rootId)) {
+        throw new Error(
+          `installDeclaredSystemAdapters: root "${rootId}" already installed its declared ` +
+            'systems — a declaration is static and installs exactly once per mount.',
+        );
+      }
+      declaredSystemAdapters.set(rootId, slots);
+      // ALWAYS set, never merge: a re-install (an HMR of the entry's `systems`
+      // table) that dropped an `absent()` marker must also drop the recorded
+      // absence, or the coverage report keeps printing a game statement the
+      // game no longer makes.
+      declaredAbsences.set(rootId, absent);
+      gameInternal.notifySystemAdaptersChanged();
+    },
     input,
     state: stateBridge,
     play: {
@@ -1318,6 +1466,10 @@ export function createGame(opts: {
         // not paused, nothing here runs — step() is a whole-call no-op.
         if (paused) {
           for (const world of roots) {
+            // Same disposed-world guard `runFrameImpl` (and `setRootGates`)
+            // make: a disposed world's `mounted.step` drives a loop whose
+            // resources are already freed.
+            if (world.disposed) continue;
             if (!world.pausable || !world.mounted.drivesOwnLoop) continue;
             if (!world.mounted.setPaused) continue; // never gated — still running
             if (world.mounted.step) {
@@ -1344,8 +1496,8 @@ export function createGame(opts: {
       // `endFrame` called once per registration) and double-dispose-wrapped
       // (`createRootInstance` wraps `mounted.dispose` in place — a second
       // wrap would flip `disposed` and call through on ITS OWN wrapped
-      // `originalDispose`, which is harmless today only by accident of
-      // `SetupThreeRootAdapter.dispose` being idempotent; a foreign adapter
+      // `originalDispose`, which would be harmless only if the adapter's
+      // dispose happened to be idempotent; a foreign adapter
       // has no such guarantee). Reject it outright instead.
       if (roots.some((w) => w.mounted === world.mounted)) {
         throw new Error(
@@ -1357,14 +1509,14 @@ export function createGame(opts: {
       roots.push(world);
       gameInternal.notifySystemAdaptersChanged();
       // Notify state-bridge subscribers THE INSTANT the world list changes —
-      // not just at the next completed `runFrame`. Root-cause fix for the
-      // "roots: " (empty) hang in `36-r3f-first-party.spec.ts` on CI (gate
-      // 4): `mountAllRootSpecs` (`create-runtime.ts`) mounts roots
+      // not just at the next completed `runFrame`. Otherwise a UI that lists
+      // worlds hangs on an empty list: `mountAllRootSpecs`
+      // (`create-runtime.ts`) mounts roots
       // SEQUENTIALLY, and a react world's `adapter.mount()`
       // (`resolveDefaultReactAdapter`/`mountOneReactRoot`) renders its tree —
       // synchronously in some React builds, but React 19's concurrent
       // renderer does NOT guarantee a synchronous first commit (see
-      // `r3f-adapter.tsx`'s own doc comment on `onCreated`) — BEFORE the
+      // `r3f-root-factory.tsx`'s own doc comment on `onCreated`) — BEFORE the
       // caller calls `registerRoot` for that very world. A `useWorldState`
       // selector reading `g.roots` can therefore render for the first time
       // while `roots` is still missing entries that register moments later.
@@ -1408,17 +1560,11 @@ export function createGame(opts: {
       // world mount), eroding the signal for a genuinely un-observable
       // ingested world.
       // A HOST-DRIVEN mount (`drivesOwnLoop: false`, notably the R3F adapter)
-      // is observable through `Game.state` even though it does not carry the
-      // classic scene adapter's `firstParty` brand: it ticks inside
-      // `runFrame`, so the frame-versioned bridge covers it. Requiring a
+      // is observable through `Game.state` when it ticks inside
+      // `runFrame` — the frame-versioned bridge covers it. Requiring a
       // foreign-world `observe` bridge there produces a false warning while
       // the canonical bridge is already live.
-      if (
-        !isFirstPartyMounted(world.mounted) &&
-        world.mounted.drivesOwnLoop &&
-        world.kind !== 'dom' &&
-        !world.mounted.observe
-      ) {
+      if (world.mounted.drivesOwnLoop && world.kind !== 'dom' && !world.mounted.observe) {
         console.warn(
           `[game] world "${world.id}" (kind: ${world.kind}, adapter: "${world.adapter.id}"): ` +
             'no state bridge — this mounted game has no `observe` (RootStateObserver); ' +
@@ -1514,7 +1660,7 @@ export function createGame(opts: {
       // root's `mounted.dispose()`, whereas a per-root teardown may be ending
       // just one sub-session while sibling roots keep running (see the
       // disposed-world guard in `runFrame`). It used to be disposed from
-      // `setup-three-root-adapter.ts`'s teardown, which meant disposing one of
+      // `world3d-react/r3f-root-factory.tsx`'s teardown, which meant disposing one of
       // two three roots froze `now()` for the whole Game, rejected the other
       // world's pending `delay`s and turned its `after()` calls into silent
       // no-ops. Note the asymmetry that gives the bug away: `seededRandom` and