@vgai/engine 0.5.2 → 0.5.4

package/src/adapter/{vgai-scene-game-adapter.ts → setup-three-root-adapter.ts}

@@ -1,12 +1,20 @@
 /**
- * VgaiSceneGameAdapter — the FIRST-PARTY implementer of {@link GameAdapter}.
+ * SetupThreeRootAdapter — the first-party implementer of {@link RootAdapter}
+ * that mounts ONE three root from an imperative `setup(ctx)` function.
  *
- * This is where `.vscn` + `GameComponent` + Rapier live now: the host no longer
- * knows about any of them. `mount(host)` builds the full first-party runtime
- * (the body that used to live inline in `create-runtime.ts`) from a neutral
- * {@link HostContext}, runs the game's `setup`/scene load, and returns a
- * {@link MountedGame}. First-party content is now just one implementer of the
- * same interface an unmodified external game implements (Phase B).
+ * This is where Rapier lives now: the host no longer knows about it.
+ * `mount(host)` builds the full first-party runtime (the body
+ * that used to live inline in `create-runtime.ts`) from a neutral
+ * {@link ThreeHostContext}, runs the game's `setup`, and returns a
+ * {@link MountedThreeRoot}. First-party content is now just one implementer of
+ * the same interface an unmodified external game implements (Phase B).
+ *
+ * It was `VgaiSceneGameAdapter` until WO-9 tasks #6/#9. Both halves of that
+ * name had stopped being true: it loads no scene (the `.vscn.json` branches
+ * went with the format in WO-8 — `setup` is the only mount path left), and what
+ * it mounts is one three ROOT, not a game (a game is the manifest's whole set
+ * of roots). The R3F/TSX world root is a SEPARATE adapter; this one is
+ * specifically the `fromSetup` path.
  *
  * `GameSetupFn` / `GameContext` are imported ONLY here (and in the example
  * `fromSetup` wrappers) — never by the host. That confinement is the inversion.
@@ -16,14 +24,15 @@ import RAPIER from '@dimforge/rapier3d-compat';
 import type { SparkRenderer } from '@sparkjsdev/spark';
 import type { EffectComposer } from 'postprocessing';
 import * as THREE from 'three';
+import { clearAssetCaches } from '../asset-loaders';
 import {
   createSeededRandom,
   DEFAULT_SEEDED_RANDOM_SEED,
   getSeededRandom,
 } from '../core/seeded-random';
+import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
 import { createDebugDraw } from '../dev/debug-draw';
-import { log } from '../dev/logger';
 import {
   createRenderDebugAdapter,
   frameCaptureContextFor,
@@ -32,15 +41,14 @@ import {
 import { collectRenderMemory } from '../dev/render-memory';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { createWebGLGpuTimer } from '../dev/webgl-gpu-timer';
-import { createComponentManager } from '../ecs/component-manager';
+import { createSceneIndex } from '../ecs/scene-index';
+import { getUserData, hasUserData, setUserData } from '../ecs/user-data';
 import { InputManager } from '../input/input-manager';
 import { setAssetPrefix } from '../loader';
 import { createCollisionSystem } from '../physics/collision-system';
 import { createPhysicsRegistry } from '../physics/physics-registry';
 import { createTransformWriter } from '../physics/transform-writer';
-import { createTriggerDispatch } from '../physics/trigger-dispatch';
-import { RenderBatchSystem } from '../render/render-batch-system';
-import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
+import { updateSceneLODs } from '../render/lod';
 import {
   disposeSparkRendererWhenIdle,
   SPARK_DISCOVERY_INTERVAL_MS,
@@ -53,76 +61,42 @@ import {
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
-import type { WorldFrameHooks } from '../runtime/game';
+import { disposeDebrisSubtree, type RootFrameHooks } from '../runtime/game';
 import type { EditorPreview, GameCleanup, GameContext, GameSetupFn } from '../runtime/types';
-import type { ComponentRegistry } from '../scene/component-registry';
-import {
-  clearAssetCaches,
-  loadScene,
-  loadSceneFromData,
-  type SceneInstance,
-  updateSceneLODs,
-} from '../scene/scene-loader';
-import type { SceneFile } from '../scene/scene-types';
-import { hasUserData, setUserData } from '../scene/user-data';
 import { type AudioContext as GameAudio, setupAudio } from '../setup/setup-audio';
 import { setupParticles } from '../setup/setup-particles';
 import { setupPhysics, updatePhysicsDebug } from '../setup/setup-physics';
-import { applySceneRenderPipeline, createSceneView } from '../setup/setup-renderer';
-import {
-  createAudioSystemAdapter,
-  createInputManagerAdapter,
-  createNavigationAdapter,
-  createVgaiAssetAdapter,
-} from './first-party-systems';
-import type { GameAdapter, MountedGame } from './game-adapter';
-import type { HostContext } from './host-context';
+import { createSceneView } from '../setup/setup-renderer';
+import { createAudioSystemAdapter, releaseAudioMeters } from './first-party-systems';
+import type { ThreeHostContext } from './host-context';
 import { createRapierPhysicsAdapter } from './rapier-physics-adapter';
+import type { MountedThreeRoot, RootAdapter } from './root-adapter';
 import type { SystemAdapters } from './system-adapter';
 
-/** How a {@link VgaiSceneGameAdapter} builds its game (the former RuntimeConfig). */
-export interface VgaiSceneConfig {
+/** How a {@link SetupThreeRootAdapter} builds its game (the former RuntimeConfig). */
+export interface SetupThreeRootConfig {
   /** Game setup function — registers systems and loads scenes. */
   setup?: GameSetupFn | undefined;
   /** Editor context — passed to setup() when launched from the editor. */
   editorPreview?: EditorPreview | undefined;
-  /** Path to a .vscn.json scene file. Loaded if no setup is provided. */
-  scenePath?: string | undefined;
-  /** In-memory scene data. Loaded if no setup and no scenePath is provided. */
-  sceneData?: SceneFile | undefined;
-  /**
-   * Component name -> GameComponent class map, threaded into the scene
-   * loader's `SceneLoadContext.componentRegistry` for both the `scenePath`
-   * and `sceneData` branches (never for `setup` — a custom setup already
-   * owns its own registry, e.g. `template/src/scripts/main.ts`'s generic
-   * fallback). Without this, a scene's `components:` entries throw
-   * ("Component ... not found in registry") or, pre-T7.2-closure, were
-   * simply unreachable through these two config options at all (the T7.2
-   * finding `docs/CLI-ON-FOLDER-DESIGN.md` §1D calls out — see
-   * `packages/editor/src/adapter-resolver.ts`, the only production caller
-   * that sets this today).
-   */
-  componentRegistry?: ComponentRegistry | undefined;
   /** Input map JSON path. Defaults to 'inputmaps/default.inputmap.json'. */
   inputMapPath?: string | undefined;
   /** URL prefix for relative asset paths. Defaults to '/'. */
   assetPrefix?: string | undefined;
-  /** Stable adapter id (for registry/conformance). Defaults to 'vgai-scene'. */
+  /** Stable adapter id (for registry/conformance). Defaults to 'setup-three'. */
   id?: string | undefined;
 }
 
 /**
- * The first-party `MountedGame`, with concrete extras the editor host uses for
+ * The first-party `MountedThreeRoot`, with concrete extras the editor host uses for
  * first-party features (HMR, physics sync) that are NOT part of the neutral
- * interface. The generic host only touches the `MountedGame` surface.
+ * interface. The generic host only touches the `MountedThreeRoot` surface.
  */
-export interface VgaiMountedGame extends MountedGame {
+export interface MountedSetupThreeRoot extends MountedThreeRoot {
   /**
    * First-party brand (checklist item 1 / T7.3 lookahead): a plain `'ctx' in
-   * mounted` structural check misfires once world2d's `MountedGame2D`
-   * (`world2d/pixi-game-adapter.ts`) also has a `ctx` key — its `ctx` is a
-   * `World2DContext`, not a `GameContext`, and has none of
-   * `queryByComponent`/`physics`/`collisions`/`camera`. This literal-`true`
+   * mounted` structural check misfires against any foreign mount that happens
+   * to carry an unrelated `ctx` key. This literal-`true`
    * property is what `isFirstPartyMounted` (`runtime/game.ts`) actually
    * checks; `game.ts` reads it via a structural `{ firstParty?: unknown }`
    * probe so it never needs a value import of this module (the existing
@@ -136,16 +110,16 @@ export interface VgaiMountedGame extends MountedGame {
   /** Warm-restart: dispose the current game, re-run a new setup on the same ctx. */
   hotReload(newSetup: GameSetupFn, editorPreview?: EditorPreview): Promise<void>;
   /**
-   * Phase-partitioned frame entry point (T7.1 slice 2,
-   * `docs/GAME-ROOT-DESIGN.md` §4) — wired onto this world's `WorldInstance`
-   * by `registerThreeWorld` (`create-runtime.ts`). `Game.runFrame` is
-   * the CANONICAL driver going forward: it calls `frame.runPhase` once per
-   * (phase, substep) for every world, then `frame.endFrame` once per
-   * substep after all roots finish all phases. `update` (below) remains
-   * the legacy/direct entry point to the exact same `SystemRunner` — direct
-   * callers (editor HMR, adapter conformance tests) keep using it unchanged.
+   * Phase-partitioned frame entry point (T7.1 slice 2) — wired onto this
+   * world's `RootInstance` by `registerThreeRoot` (`create-runtime.ts`).
+   * `Game.runFrame` is the CANONICAL driver going forward: it calls
+   * `frame.runPhase` once per (phase, substep) for every world, then
+   * `frame.endFrame` once per substep after all roots finish all phases.
+   * `update` (below) remains the legacy/direct entry point to the exact same
+   * `SystemRunner` — direct callers (editor HMR, adapter conformance tests)
+   * keep using it unchanged.
    */
-  readonly frame: WorldFrameHooks;
+  readonly frame: RootFrameHooks;
 }
 
 /** Minimal stand-in for the GPU composer when mounting headlessly. */
@@ -162,28 +136,25 @@ function headlessComposer(renderer: THREE.WebGLRenderer): EffectComposer {
 }
 
 /**
- * Wrap a first-party `setup` function as a {@link GameAdapter}. This is how every
+ * Wrap a first-party `setup` function as a {@link RootAdapter}. This is how every
  * first-party example becomes an implementer of the same interface an external
  * game implements — with no change to the setup's body.
  */
-export function fromSetup(id: string, setup: GameSetupFn): GameAdapter {
-  return new VgaiSceneGameAdapter({ id, setup });
+export function fromSetup(id: string, setup: GameSetupFn): RootAdapter {
+  return new SetupThreeRootAdapter({ id, setup });
 }
 
-export class VgaiSceneGameAdapter implements GameAdapter {
+export class SetupThreeRootAdapter implements RootAdapter {
   readonly id: string;
-  constructor(private readonly config: VgaiSceneConfig = {}) {
-    this.id = config.id ?? 'vgai-scene';
+  constructor(private readonly config: SetupThreeRootConfig = {}) {
+    this.id = config.id ?? 'setup-three';
   }
 
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive first-party bootstrap (moved verbatim from create-runtime); splitting it would obscure the ordering contract
-  async mount(host: HostContext): Promise<VgaiMountedGame> {
+  async mount(host: ThreeHostContext): Promise<MountedSetupThreeRoot> {
     const {
       setup,
       editorPreview,
-      scenePath,
-      sceneData,
-      componentRegistry,
       inputMapPath = '/inputmaps/default.inputmap.json',
       assetPrefix = '/',
     } = this.config;
@@ -268,7 +239,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     let viewportShadingMode: ViewportShadingMode = 'solid';
 
     // --- System runner (engine-level systems) ---
-    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'threejs');
+    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'three');
     // D15/T-D15.3/.5: pass the LIVE shared game tick (not a locally-counted
     // one) into every `poll()` call — `debugRegistry` is declared further
     // down in this same `mount()` (it needs `ctx`/`systemAdapters` to exist
@@ -384,6 +355,22 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // late registrations are visible to its panels at read time.
     const systemAdapters: SystemAdapters = {};
 
+    // P3 — `ctx.clock`. Same "ONE per Game root, shared across every world"
+    // reach-in as `ctx.debug`/`ctx.random` below: `getSimClock(host.game)`
+    // returns the clock `createGame` filed, and `runFrameImpl` is what flushes
+    // it. A bare mount with no Game shell (headless harness, foreign host) gets
+    // a private, mount-local clock so the field is always a real value — but
+    // nothing flushes that one, because a mount with no Game has no fixed loop
+    // to bind timers to and inventing a wall-clock frontier here is exactly the
+    // hazard `core/sim-clock.ts` exists to avoid. Its `disposeAfter` is
+    // therefore unreachable; the disposer is still the real one.
+    const gameClock: SimClockInternal | null = host.game ? getSimClock(host.game) : null;
+    const clock: SimClockInternal =
+      gameClock ?? createSimClock({ dispose: (obj) => disposeDebrisSubtree(obj, [ctx]) });
+    /** Only a mount-local fallback is THIS mount's to dispose — see the
+     *  `clock.dispose` teardown step below for why the game-scoped one is not. */
+    const ownsClock = gameClock === null;
+
     // --- GameContext (the first-party runtime surface) ---
     const ctx: GameContext = {
       scene,
@@ -399,30 +386,33 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       debugDraw,
       assets,
       systems,
-      components: null!,
+      clock,
+      // The live scene index for THIS root (P2 `observe`). Created before
+      // setup() runs so a game's own objects are indexed as they are added —
+      // it subscribes to three's `childadded`/`childremoved` on the scene, so
+      // everything the game builds arrives through it. Disposed in
+      // disposeGame() below (a warm restart keeps it: same `scene`, same ctx).
+      sceneIndex: createSceneIndex(scene),
       registerSystemAdapter: (kind, adapter) => {
         systemAdapters[kind] = adapter;
+        host.game?.notifySystemAdaptersChanged();
       },
     };
     // Game root (T7.1 slice 1): only present once the host has constructed a
     // Game shell (createGameRuntime does this before mount; headless/foreign
     // hosts may omit it — ctx.game/ctx.roots simply stay undefined, which is
     // the documented zero-break behavior). `ctx.roots` is assigned the SAME
-    // live array `host.game` mutates via `registerWorld` (not a copy) — the
+    // live array `host.game` mutates via `registerRoot` (not a copy) — the
     // default world is registered AFTER mount returns, and this reference
     // must observe that later push.
     if (host.game) {
       ctx.game = host.game;
       ctx.roots = host.game.roots;
+      ctx.playtest = host.game.playtest ?? null;
     }
-    ctx.components = createComponentManager(ctx, physicsRegistry);
-    collisions.onCollision(
-      createTriggerDispatch(physicsRegistry, ctx.components, physics.rapierWorld, ctx),
-    );
-
-    // Everything registered above (engine systems + the ComponentManager's
-    // per-phase tick, just wired in) is "engine" and must survive a warm
-    // restart. Everything a game (setup()/scenePath/sceneData, below) adds
+    // Everything registered above (the engine systems) is "engine" and must
+    // survive a warm
+    // restart. Everything a game's setup() (below) adds
     // from here on is "game" content that `hotReload` bulk-removes via
     // `systems.removeAllNonEngine()` on every restart (T1.7).
     systems.markEngineBoundary();
@@ -433,26 +423,44 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // always wins over the engine's first-party entry (see
     // registerSystemAdapter's docstring in runtime/types.ts). `navigation` is
     // ALSO first-party now (R8 item 7): `createNavigationAdapter` wraps the
-    // real `NavMeshManager` a scenePath/sceneData scene load may produce (see
-    // `applySceneNavigation` below) — it is wired once that scene instance
     // resolves, not here (no NavMeshManager exists yet at this point in the
     // mount). `networking` remains the one game-owned capability with no
     // first-party implementer; it simply starts absent here.
-    systemAdapters.physics = createRapierPhysicsAdapter(physicsRegistry, physics);
-    if (ownsInput) systemAdapters.input = createInputManagerAdapter(input);
-    systemAdapters.assets = createVgaiAssetAdapter();
+    // P-4: the physics seam is keyed by node id, so the first-party mount
+    // supplies the first-party `id → Object3D` map. `userData.entityId` is
+    // THIS stack's identity convention (the scene loader stamps it, and the
+    // editor's `objectMap`/`hierarchy.object3D` agree on it), which is exactly
+    // why the lookup belongs here and not inside `rapier-physics-adapter.ts`.
+    // Memoized because the gizmo/inspector ask repeatedly for one selection;
+    // a miss (or an object since detached) re-walks once and re-caches.
+    const nodeObjectCache = new Map<string, THREE.Object3D>();
+    const resolveNodeObject = (nodeId: string): THREE.Object3D | null => {
+      const cached = nodeObjectCache.get(nodeId);
+      if (cached?.parent) return cached;
+      let found: THREE.Object3D | null = null;
+      scene.traverse((o) => {
+        if (!found && getUserData(o, 'entityId') === nodeId) found = o;
+      });
+      if (found) nodeObjectCache.set(nodeId, found);
+      else nodeObjectCache.delete(nodeId);
+      return found;
+    };
+    systemAdapters.physics = createRapierPhysicsAdapter(
+      physicsRegistry,
+      physics,
+      resolveNodeObject,
+    );
     // D10/T7.6: the audio seam `Game.play.pause()` silences on pause. Works
     // against the headless stand-in too (`headlessAudio()`'s plain
     // `masterGain.gain` object) — this world's `pause()` mutes it harmlessly.
     systemAdapters.audio = createAudioSystemAdapter(audio);
-    // Debug/synthetic-player seam (T1.1, docs/SYNTHETIC-PLAYER-SPEC.md §3.1):
-    // ONE registry per Game root, shared across every world that mounts onto
-    // it — `getDebugRegistry(host.game)` reaches the SAME accumulator
-    // `createGame` filed, so a second/third world's `ctx.debug` feeds it too
-    // (see debug-registry.ts's module doc for the provenance/id note). A
-    // mount with no Game shell at all (bare test harnesses predating T7.1)
-    // gets a private, mount-local registry instead — same absence precedent
-    // as `ctx.game`/`ctx.roots` above.
+    // Debug/synthetic-player seam (T1.1): ONE registry per Game root, shared
+    // across every world that mounts onto it — `getDebugRegistry(host.game)`
+    // reaches the SAME accumulator `createGame` filed, so a second/third
+    // world's `ctx.debug` feeds it too (see debug-registry.ts's module doc
+    // for the provenance/id note). A mount with no Game shell at all (bare
+    // test harnesses predating T7.1) gets a private, mount-local registry
+    // instead — same absence precedent as `ctx.game`/`ctx.roots` above.
     const debugRegistry: DebugRegistry =
       (host.game ? getDebugRegistry(host.game) : null) ??
       createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
@@ -462,7 +470,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // below so a warm restart / stop never mistakes it for game content. Only
     // present when a real WebGL2 context backed the mount (renderDebugWiring).
     if (renderDebugWiring) systemAdapters.renderDebug = renderDebugWiring.adapter;
-    ctx.debug = debugRegistry.forWorld(this.id);
+    ctx.debug = debugRegistry.forRoot(this.id);
     // T1.2: the InputManager is a first-party per-world handle the registry
     // has no other way to reach — wired as a lazy supplier (not a direct
     // read here), scoped to THIS world's id, so the built-in `input.actions`
@@ -555,7 +563,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       c.traverse((n) => setUserData(n, 'engineInternal', true));
     }
     let currentCleanup: GameCleanup | null = null;
-    let batchSystem: RenderBatchSystem | null = null;
     let sparkRenderer: SparkRenderer | null = null;
     let sparkRendererLoading = false;
     let sparkRendererFailed = false;
@@ -564,109 +571,21 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // Start at the threshold so the first rendered frame discovers eager splats.
     let sparkDiscoveryElapsedMs = SPARK_DISCOVERY_INTERVAL_MS;
 
-    // Apply scene-level render settings + transparent auto-batching after a scene
-    // loads (GPU host only). Gated on the resolved `environment.rendering` cascade
-    // (defaults preserve prior behavior when a scene omits `rendering`).
-    const applySceneRendering = async (inst: SceneInstance): Promise<void> => {
-      if (headless) return;
-      const scope = inst.environment?.rendering as RenderScope | undefined;
-      const settings = resolveRenderSettings(scope);
-      // Always apply the whole authored scene pipeline. Tone mapping is an
-      // authored setting even when the scene has no post-processing effects.
-      applySceneRenderPipeline(composer, renderer, scene, camera, inst.environment);
-      // transparent batching: collapse static/mover meshes sharing a signature
-      if (settings['autoBatch']) {
-        batchSystem = new RenderBatchSystem(scene, settings);
-        batchSystem.build();
-        ctx.systems.add('preRender', () => batchSystem?.update());
-        if (import.meta.env?.DEV)
-          (window as unknown as { __vgaiBatch?: unknown }).__vgaiBatch = batchSystem;
-      }
-      if (inst.splatCount > 0 && !sparkRenderer) {
-        const { SparkRenderer } = await import('@sparkjsdev/spark');
-        sparkRenderer = new SparkRenderer({ renderer, enableLod: false });
-        sparkRenderer.traverse((node) => setUserData(node, 'engineInternal', true));
-      }
-    };
-
-    // Wire the (first-party) navigation system adapter to whichever
-    // NavMeshManager the CURRENT scene instance carries — reassigned on every
-    // scene load, and explicitly cleared (not just left stale) when the new
-    // scene has none, so `mounted.systems.navigation` never lingers pointing
-    // at a manager a later teardown step disposes (R8 item 7).
-    const applySceneNavigation = (inst: SceneInstance): void => {
-      if (inst.navMesh) {
-        systemAdapters.navigation = createNavigationAdapter(inst.navMesh);
-      } else {
-        delete systemAdapters.navigation;
-      }
-    };
-
-    const loadFromData = async (data: SceneFile): Promise<SceneInstance> => {
-      const inst = await loadSceneFromData(data, {
-        scene,
-        rapierWorld: ctx.rapierWorld,
-        rapier: ctx.rapier,
-        physics: ctx.physics,
-        audioListener: ctx.audio.listener,
-        ...(componentRegistry ? { componentRegistry } : {}),
-        componentManager: ctx.components,
-        particleRenderer: ctx.particles.batchedRenderer,
-        ...(headless ? {} : { renderer }),
-      });
-      await applySceneRendering(inst);
-      applySceneNavigation(inst);
-      ctx.systems.add('postPhysics', (dt) => inst.update(dt));
-      return inst;
-    };
-
-    if (setup) {
-      if (headless) throw new Error('VgaiSceneGameAdapter: setup-based games require a GPU host');
-      currentCleanup = await setup(ctx, editorPreview);
-    } else if (scenePath) {
-      // The editor viewport is only the fallback/initial play viewpoint. Apply
-      // it BEFORE capturing the load baseline so authored scene cameras and
-      // camera GameComponents can override it during/after scene load.
-      applyEditorCamera(editorPreview, camera);
-      // #139: captured immediately BEFORE load so adoptSceneCamera can tell
-      // whether a component (e.g. SceneCamera.init) framed the camera.
-      const preLoadPose = captureCameraPose(camera);
-      const inst = await loadScene(scenePath, {
-        scene,
-        rapierWorld: ctx.rapierWorld,
-        rapier: ctx.rapier,
-        physics: ctx.physics,
-        audioListener: ctx.audio.listener,
-        ...(componentRegistry ? { componentRegistry } : {}),
-        componentManager: ctx.components,
-        particleRenderer: ctx.particles.batchedRenderer,
-        ...(headless ? {} : { renderer }),
-      });
-      adoptSceneCamera(inst, camera, preLoadPose);
-      await applySceneRendering(inst);
-      applySceneNavigation(inst);
-      ctx.systems.add('postPhysics', (dt) => inst.update(dt));
-      // A pre-baked navmesh (sibling .navmesh file — see scene-loader.ts) holds
-      // live recast-navigation WASM handles that leak unless destroyed
-      // explicitly; dispose it alongside the scene instance on teardown.
-      currentCleanup = {
-        dispose: () => {
-          inst.navMesh?.dispose(scene);
-          inst.dispose();
-        },
-      };
-    } else if (sceneData) {
-      applyEditorCamera(editorPreview, camera);
-      const preLoadPose = captureCameraPose(camera);
-      const inst = await loadFromData(sceneData);
-      adoptSceneCamera(inst, camera, preLoadPose);
-      currentCleanup = {
-        dispose: () => {
-          inst.navMesh?.dispose(scene);
-          inst.dispose();
-        },
-      };
+    if (!setup) {
+      throw new Error(
+        'SetupThreeRootAdapter: no `setup` supplied. The `.vscn.json` scene branches ' +
+          '(`scenePath` / `sceneData`) were removed with the format; a first-party three root ' +
+          'is either an imperative ' +
+          '`setup(ctx)` (wrap it with `fromSetup(id, setup)`) or a TSX/R3F world root ' +
+          '(`entry` pointing at a .tsx module — mounted by the R3F adapter, not this one).',
+      );
     }
+    // Headless is legal here: `createSceneView` was skipped above, the composer
+    // is a no-op stand-in, and `setup` gets a real `THREE.Scene`/camera. It used
+    // to throw because headless existed only for the `.vscn` `sceneData` branch;
+    // with the format gone (WO-8) `setup` is the only mount path, and headless
+    // unit mounts are what exercise the Game/roots/frame machinery without WebGL.
+    currentCleanup = await setup(ctx, editorPreview);
 
     // Warm the GPU program cache before the first visible frame. A mount gets
     // a fresh WebGL context, so without this every scene material compiles
@@ -697,40 +616,16 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // adapter.
     let disposed = false;
 
-    // W3c: attach the read-only Audio-debugger introspection capabilities
-    // (graph/transport/meters/events) onto the SAME first-party audio adapter
-    // seeded above. Dynamically imported so `tone` stays out of the
-    // mount-critical chunk (the Colyseus dynamic-import idiom); the editor
-    // panel polls, so a few-ms-late attachment is invisible. If the game
-    // replaced `systems.audio` with its OWN adapter during setup(), the
-    // first-party augmentation is skipped — the game's adapter is the truth
-    // the editor sees.
-    let disposeAudioIntrospection: (() => void) | null = null;
-    const firstPartyAudioAdapter = systemAdapters.audio;
-    if (firstPartyAudioAdapter) {
-      void import('../audio/audio-introspection').then(
-        (m) => {
-          if (disposed || systemAdapters.audio !== firstPartyAudioAdapter) return;
-          disposeAudioIntrospection = m.attachAudioIntrospection(firstPartyAudioAdapter, audio);
-        },
-        (err) => {
-          log.audio.warn('VgaiSceneGameAdapter: audio introspection unavailable', {
-            error: String(err),
-          });
-        },
-      );
-    }
-
-    // Run one teardown step in isolation: a throwing step (e.g. a
-    // GameComponent's dispose() misbehaving, or a WASM free() panicking) must
-    // not abort the remaining steps — otherwise a single bad component leaks
+    // Run one teardown step in isolation: a throwing step (e.g. a game's own
+    // cleanup misbehaving, or a WASM free() panicking) must
+    // not abort the remaining steps — otherwise a single bad step leaks
     // the Rapier world and skips input.dispose() with no way to retry (a
     // second call is a no-op once `disposed` is set). Logs and continues.
     const safeStep = (label: string, fn: () => void): void => {
       try {
         fn();
       } catch (err) {
-        console.error(`VgaiSceneGameAdapter: teardown step "${label}" threw (continuing)`, err);
+        console.error(`SetupThreeRootAdapter: teardown step "${label}" threw (continuing)`, err);
       }
     };
 
@@ -741,10 +636,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       if (disposed) return;
       disposed = true;
 
-      safeStep('batchSystem.teardown', () => {
-        batchSystem?.teardown(); // re-attach detached sources before scene teardown
-        batchSystem = null;
-      });
       safeStep('currentCleanup.dispose', () => {
         currentCleanup?.dispose();
         currentCleanup = null;
@@ -769,12 +660,29 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         );
       }
 
-      // Components BEFORE the physics world is freed/bodies are removed: a
-      // GameComponent's dispose() may read `this.rigidBody`/`this.collider`
-      // (see game-component.ts) — freeing the world first would make those
-      // dangling WASM references. Isolated: a throwing component dispose must
-      // not prevent the world/eventQueue frees or input.dispose() below.
-      safeStep('components.clear', () => ctx.components.clear());
+      // P3 — the MOUNT-LOCAL clock only, and only when this mount created one
+      // (a bare mount with no Game shell). The game-scoped clock is disposed by
+      // `GameInternal.dispose()`, which `create-runtime.ts` runs after every
+      // root has torn down — because disposing ONE world's mount is a supported
+      // way to end a sub-session while the Game keeps running, and destroying a
+      // shared clock there froze `now()` and killed the sibling worlds' timers.
+      // The asymmetry is the tell: `seededRandom` and `debugRegistry` are
+      // game-scoped too, and this teardown destroys neither (it strips only its
+      // OWN slice of the registry, a few steps below).
+      //
+      // Sim timers still go BEFORE the Rapier world they would touch: a pending
+      // `disposeAfter`/`after` fires into a live Rapier world, and once that is
+      // gone it would operate on freed WASM handles.
+      // Disposing cancels every timer and rejects every pending `delay` with an
+      // `AbortError` (which awaiting game code is documented to tolerate,
+      // exactly like an aborted `fetch`).
+      if (ownsClock) safeStep('clock.dispose', () => clock.dispose());
+
+      // Before the scene is emptied below: dropping the listeners
+      // first means the teardown's ~N `scene.remove()` calls do no index
+      // bookkeeping, and — the failure mode this exists to prevent — no
+      // `childadded` listener is left behind on a disposed scene.
+      safeStep('sceneIndex.dispose', () => ctx.sceneIndex.dispose());
 
       safeStep('remove rigid bodies', () => {
         const handles: number[] = [];
@@ -833,12 +741,18 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         host.game ? debugRegistry.strip(this.id) : debugRegistry.strip(),
       );
 
-      // W3c: detach introspection BEFORE the audio teardown below — releases
-      // Tone transport listeners (the transport singleton outlives this
-      // world), the context statechange hook, and any meter taps still alive.
-      safeStep('audio introspection dispose', () => {
-        disposeAudioIntrospection?.();
-        disposeAudioIntrospection = null;
+      // Release analyser taps BEFORE the audio teardown below. A consumer
+      // (the editor's meter poll) should dispose its own handle, but Stop must
+      // never leak taps regardless.
+      //
+      // This used to ride on the Tone introspection module's disposer, which
+      // meant a game that never touched Tone leaked them — the module was
+      // never loaded, so nothing ever called this. `acquireMeters` belongs to
+      // the base adapter (535d248dc), so its release does too, and the world
+      // that created the adapter is what disposes it.
+      safeStep('audio meters release', () => {
+        const audioAdapter = systemAdapters.audio;
+        if (audioAdapter) releaseAudioMeters(audioAdapter);
       });
 
       if (!headless) {
@@ -862,35 +776,27 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       newEditorPreview?: EditorPreview,
     ): Promise<void> => {
       if (disposed) {
-        throw new Error('VgaiSceneGameAdapter: cannot hotReload after dispose()/stop()');
+        throw new Error('SetupThreeRootAdapter: cannot hotReload after dispose()/stop()');
       }
 
       // Full parity with disposeGame for the parts a warm restart rebuilds:
-      // batch-render teardown, game cleanup, component batch teardown (in that
+      // game cleanup, component batch teardown (in that
       // ordering, BEFORE bodies are pulled from the world — see disposeGame),
       // scene-UI dispose (React root unmount), and bulk system removal. Each
       // step isolated the same way as disposeGame — one throwing step (e.g. a
       // component dispose) must not abort the rest of the warm restart.
-      safeStep('batchSystem.teardown', () => {
-        batchSystem?.teardown(); // re-attach detached sources before scene teardown
-        batchSystem = null;
-      });
       safeStep('currentCleanup.dispose', () => {
         currentCleanup?.dispose();
         currentCleanup = null;
       });
-      // Same reasoning as disposeGame: the outgoing scene instance's
-      // NavMeshManager was just disposed above, and `hotReload`'s `newSetup`
-      // (below) never auto-wires a replacement (that only happens for THIS
-      // adapter's own scenePath/sceneData mount, once, at initial mount) — so
-      // clear the stale wrapper here. A `newSetup` that wants navigation may
+      // Clear any navigation adapter a previous `setup` registered: `hotReload`'s
+      // `newSetup` (below) never auto-wires a replacement, so leaving the old
+      // wrapper would point at a disposed manager. A `newSetup` that wants navigation may
       // register its own via `ctx.registerSystemAdapter('navigation', ...)`.
       safeStep('clear navigation adapter', () => {
         delete systemAdapters.navigation;
       });
 
-      safeStep('components.clear', () => ctx.components.clear());
-
       safeStep('remove rigid bodies', () => {
         const handles: number[] = [];
         physics.rapierWorld.forEachRigidBody((b) => handles.push(b.handle));
@@ -954,7 +860,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     };
 
     return {
-      kind: 'threejs',
+      kind: 'three',
       scene,
       camera,
       firstParty: true,
@@ -986,92 +892,8 @@ export class VgaiSceneGameAdapter implements GameAdapter {
   }
 }
 
-// --- Camera precedence helpers (moved from create-runtime, unchanged) ---
-
-function applyEditorCamera(
-  editor: EditorPreview | undefined,
-  runtimeCamera: THREE.PerspectiveCamera,
-): boolean {
-  if (!editor?.viewportCamera) return false;
-  runtimeCamera.position.fromArray(editor.viewportCamera.position);
-  runtimeCamera.quaternion.fromArray(editor.viewportCamera.quaternion);
-  return true;
-}
-
-/** The pose `adoptSceneCamera` compares against to detect that a component
- *  already framed the runtime camera during scene load (#139). Capture with
- *  `captureCameraPose(camera)` immediately BEFORE `loadScene`. */
-export interface CameraPose {
-  position: THREE.Vector3;
-  quaternion: THREE.Quaternion;
-}
-
-export function captureCameraPose(camera: THREE.PerspectiveCamera): CameraPose {
-  return { position: camera.position.clone(), quaternion: camera.quaternion.clone() };
-}
-
-export function adoptSceneCamera(
-  sceneInstance: SceneInstance,
-  runtimeCamera: THREE.PerspectiveCamera,
-  preLoadPose?: CameraPose,
-): boolean {
-  const sceneCam = sceneInstance.cameras[0];
-  if (!sceneCam) return false;
-  // #133 (blind run #4): `camera.type: 'orthographic'` builds a real
-  // OrthographicCamera in the scene graph (`createCamera`), but the RUNTIME
-  // renders through a hardcoded PerspectiveCamera — the authored projection
-  // silently never reached the screen. Until ortho support is ranked
-  // (implement-vs-reject, owner call on #133), say so loudly instead of
-  // letting a coplanar game render in unexplained perspective.
-  if ((sceneCam as THREE.Camera & { isOrthographicCamera?: boolean }).isOrthographicCamera) {
-    console.warn(
-      "adoptSceneCamera (#133): this scene's camera is ORTHOGRAPHIC, but the runtime camera is " +
-        'perspective-only — the orthographic projection is NOT applied (only the pose is). ' +
-        'Use type: "perspective" (a long-lens fake: far position + small fov) until #133 lands.',
-    );
-  }
-  // #139 (blind run #5): if a GameComponent already positioned/oriented the
-  // runtime camera during scene load (`SceneCamera.init`'s
-  // `ctx.camera.position.set` + `lookAt` is the blessed shape), the camera
-  // ENTITY's transform must not stomp it — an unauthored `transform.rotation`
-  // is identity ("stare down −Z"), which silently blanked an entire correct
-  // game while every state-based probe spec passed. Components win the pose;
-  // the entity still contributes the LENS (fov/near/far below), which
-  // `SceneCamera` never sets.
-  const componentFramedCamera =
-    preLoadPose !== undefined &&
-    (!runtimeCamera.position.equals(preLoadPose.position) ||
-      !runtimeCamera.quaternion.equals(preLoadPose.quaternion));
-  const parent = sceneCam.parent;
-  if (parent && !componentFramedCamera) {
-    parent.updateMatrixWorld(true);
-    runtimeCamera.position.copy(parent.getWorldPosition(new THREE.Vector3()));
-    const worldQuat = parent.getWorldQuaternion(new THREE.Quaternion());
-    runtimeCamera.quaternion.copy(worldQuat);
-    // Identity orientation on an adopted scene camera is almost never intent
-    // (it means "look at the horizon down −Z", not "look at my scene") — the
-    // exact silent-blank-viewport footgun above. Adopt it anyway (authored
-    // data is truth) but say so loudly, with the two blessed remedies.
-    if (Math.abs(1 - Math.abs(worldQuat.w)) < 1e-6) {
-      console.warn(
-        'adoptSceneCamera (#139): the scene camera entity has no rotation — the runtime camera ' +
-          'will stare horizontally down −Z and may show nothing. Either attach the SceneCamera ' +
-          'component (position + lookAt, no quaternion math) or author transform.rotation on ' +
-          'the camera entity.',
-      );
-    }
-  }
-  if (sceneCam instanceof THREE.PerspectiveCamera) {
-    runtimeCamera.fov = sceneCam.fov;
-    runtimeCamera.near = sceneCam.near;
-    runtimeCamera.far = sceneCam.far;
-    runtimeCamera.updateProjectionMatrix();
-  }
-  return true;
-}
-
 /** Headless input stand-in — `InputManager` attaches `window` listeners in its
- *  constructor, which Node lacks. The scene-data path never reads input. */
+ *  constructor, which Node lacks. A headless mount never reads input. */
 function headlessInput(): InputManager {
   return {
     poll: () => {},
@@ -1083,8 +905,8 @@ function headlessInput(): InputManager {
   } as unknown as InputManager;
 }
 
-/** Headless audio stand-in (no Web Audio). Only the fields the loader/cleanup
- *  touch are present; setup-based games never mount headlessly. */
+/** Headless audio stand-in (no Web Audio). Only the fields the mount/cleanup
+ *  touch are present. */
 function headlessAudio(): GameAudio {
   return {
     listener: undefined as unknown as THREE.AudioListener,