@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/adapter/vgai-scene-game-adapter.ts

@@ -15,8 +15,14 @@
 import RAPIER from '@dimforge/rapier3d-compat';
 import type { EffectComposer } from 'postprocessing';
 import * as THREE from 'three';
+import {
+  createSeededRandom,
+  DEFAULT_SEEDED_RANDOM_SEED,
+  getSeededRandom,
+} from '../core/seeded-random';
 import { createSystemRunner } from '../core/system-runner';
 import { createDebugDraw } from '../dev/debug-draw';
+import { createWebGLGpuTimer } from '../dev/webgl-gpu-timer';
 import { createComponentManager } from '../ecs/component-manager';
 import { InputManager } from '../input/input-manager';
 import { setAssetPrefix } from '../loader';
@@ -26,14 +32,12 @@ 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 type { WorldFrameHooks } from '../runtime/game';
 import {
-  renderSceneUI,
-  type SceneUIDataSourceLike,
-  type SceneUIGameServices,
-  type SceneUIHandle,
-} from '../runtime/scene-ui-bridge';
-import { gameStateDataSource } from '../runtime/scene-ui-data';
+  createDebugRegistry,
+  type DebugRegistry,
+  getDebugRegistry,
+} from '../runtime/debug-registry';
+import type { WorldFrameHooks } from '../runtime/game';
 import type { EditorPreview, GameCleanup, GameContext, GameSetupFn } from '../runtime/types';
 import type { ComponentRegistry } from '../scene/component-registry';
 import { tickCustomMaterials } from '../scene/material-registry';
@@ -88,24 +92,6 @@ export interface VgaiSceneConfig {
    * that sets this today).
    */
   componentRegistry?: ComponentRegistry | undefined;
-  /**
-   * The project's scene-UI registry (design/24-scene-ui.md D9/D11) —
-   * `components`/`transforms`/`strings` only, opaque records engine-side (the
-   * engine never imports `@vgai/scene-ui`'s real `ProjectUIRegistry` type;
-   * they're React things it never inspects). Threaded per-mount into the
-   * services `renderSceneUI` receives, mirroring `componentRegistry` above:
-   * the editor's default-three adapter resolver passes its cached project
-   * registry here for the editor-play path (D11); a standalone host that
-   * already registered a static registry via `registerSceneUIRenderer`
-   * typically omits this (registration-time registry is enough there).
-   */
-  uiRegistry?:
-    | {
-        components?: Record<string, unknown>;
-        transforms?: Record<string, unknown>;
-        strings?: Record<string, Record<string, string>>;
-      }
-    | undefined;
   /** Input map JSON path. Defaults to 'inputmaps/default.inputmap.json'. */
   inputMapPath?: string | undefined;
   /** URL prefix for relative asset paths. Defaults to '/'. */
@@ -139,10 +125,10 @@ export interface VgaiMountedGame extends MountedGame {
   /**
    * Phase-partitioned frame entry point (T7.1 slice 2,
    * `docs/GAME-ROOT-DESIGN.md` §4) — wired onto this world's `WorldInstance`
-   * by `registerDefaultThreeWorld` (`create-runtime.ts`). `Game.runFrame` is
+   * 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 worlds finish all phases. `update` (below) remains
+   * 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.
    */
@@ -185,7 +171,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       scenePath,
       sceneData,
       componentRegistry,
-      uiRegistry,
       inputMapPath = '/inputmaps/default.inputmap.json',
       assetPrefix = '/',
     } = this.config;
@@ -234,31 +219,69 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // --- Particles (three.quarks BatchedRenderer) ---
     const particles = setupParticles(scene);
 
-    // --- UI container (host-provided) ---
-    const uiContainer = host.ui as HTMLDivElement;
-
     // --- Debug draw / assets ---
     const debugDraw = createDebugDraw(scene);
     const assets = host.assets;
+    // Test/headless adapters may provide the renderer surface needed by the
+    // runtime without a real WebGL context. GPU timing is optional diagnostics:
+    // degrade honestly when the renderer/context cannot expose extensions.
+    const rendererContext =
+      typeof renderer.getContext === 'function' ? renderer.getContext() : undefined;
+    const gpuTimer =
+      !headless && rendererContext && typeof rendererContext.getExtension === 'function'
+        ? createWebGLGpuTimer(rendererContext)
+        : null;
 
     // --- System runner (engine-level systems) ---
-    const systems = createSystemRunner();
-    systems.add('input', () => input.poll());
-    systems.add('physics', () => physics.rapierWorld.step(physics.eventQueue));
-    systems.add('postPhysics', () => {
-      collisions.drain();
-      writeTransforms();
+    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'threejs');
+    // 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
+    // first), but this callback only ever executes during real frame
+    // ticks, long after `mount()` has fully returned and `debugRegistry` is
+    // initialized (a safe closure-over-a-later-const, not a genuine
+    // use-before-init). `host.game` gates it: a bare mount with no `Game`
+    // shell behind it (test harnesses predating T7.1) has no shared tick to
+    // key off, so `InputManager.poll()` falls back to its own internal
+    // self-incrementing counter instead (unchanged pre-D15 behavior) rather
+    // than being pinned to a constant `0` forever.
+    systems.add('input', () => input.poll(host.game ? debugRegistry.getGameTick() : undefined), {
+      name: 'input.poll',
     });
-    systems.add('preRender', (dt) => {
-      particles.batchedRenderer.update(dt);
-      tickCustomMaterials(scene, dt);
-      updateSceneLODs(scene, camera);
+    systems.add('physics', () => physics.rapierWorld.step(physics.eventQueue), {
+      name: 'physics.step',
     });
+    systems.add(
+      'postPhysics',
+      () => {
+        collisions.drain();
+        writeTransforms();
+      },
+      { name: 'physics.sync' },
+    );
+    systems.add(
+      'preRender',
+      (dt) => {
+        particles.batchedRenderer.update(dt);
+        tickCustomMaterials(scene, dt);
+        updateSceneLODs(scene, camera);
+      },
+      { name: 'materials-and-particles' },
+    );
     if (!headless) {
-      systems.add('render', (dt) => {
-        composer.render(dt);
-        if (physics.debugEnabled) updatePhysicsDebug(physics.rapierWorld, physics.debugMesh);
-      });
+      systems.add(
+        'render',
+        (dt) => {
+          if (host.game?.profiler.enabled) gpuTimer?.begin();
+          try {
+            composer.render(dt);
+          } finally {
+            gpuTimer?.end();
+          }
+          if (physics.debugEnabled) updatePhysicsDebug(physics.rapierWorld, physics.debugMesh);
+        },
+        { name: 'three.render' },
+      );
     }
 
     // --- Debug toggle (browser only) ---
@@ -270,7 +293,18 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     };
     if (!headless) window.addEventListener('keydown', onDebugToggle);
 
-    const postFrame = () => input.endFrame();
+    const postFrame = () => {
+      input.endFrame();
+      if (host.game?.profiler.enabled) {
+        host.game.profiler.reportRender({
+          gpuMs: gpuTimer?.poll() ?? null,
+          drawCalls: renderer.info.render.calls,
+          triangles: renderer.info.render.triangles,
+          geometries: renderer.info.memory.geometries,
+          textures: renderer.info.memory.textures,
+        });
+      }
+    };
 
     // The mounted game's adapter surface (`mounted.systems`). Declared before
     // ctx so `ctx.registerSystemAdapter` can close over it: the engine fills
@@ -280,17 +314,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // late registrations are visible to its panels at read time.
     const systemAdapters: SystemAdapters = {};
 
-    // Game-registered scene-UI services (design/24-scene-ui.md D2/D7) — a `let`
-    // bag mutated by `ctx.setSceneUIServices`, declared here (BEFORE `ctx` is
-    // built) so the closure below has something to capture: a GameComponent
-    // calling `ctx.setSceneUIServices` from its `init()` runs DURING
-    // `componentManager.initAll()` (scene-loader.ts), which is awaited before
-    // `loadScene`/`loadFromData` return below — well before `sceneUIHandle`
-    // exists — so early calls just accumulate here and are folded into the
-    // FIRST render (`buildSceneUIServices`, below) rather than routed through
-    // the late-update path.
-    let sceneUIServices: SceneUIGameServices = {};
-
     // --- GameContext (the first-party runtime surface) ---
     const ctx: GameContext = {
       scene,
@@ -307,38 +330,20 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       assets,
       systems,
       components: null!,
-      uiContainer,
       registerSystemAdapter: (kind, adapter) => {
         systemAdapters[kind] = adapter;
       },
-      setSceneUIServices: (incoming) => {
-        sceneUIServices = { ...sceneUIServices, ...incoming };
-        // Late call (after the initial mount already resolved a sceneInstance
-        // and rendered it): route to the live handle instead of just banking
-        // the services for a mount that already happened (D7).
-        if (sceneUIHandle && sceneInstance) {
-          const merged = buildSceneUIServices(sceneInstance);
-          if (sceneUIHandle.update) {
-            sceneUIHandle.update(merged);
-          } else {
-            sceneUIHandle.dispose();
-            sceneUIHandle = sceneInstance.ui
-              ? renderSceneUI(uiContainer, sceneInstance.ui, merged)
-              : null;
-          }
-        }
-      },
     };
     // 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.worlds simply stay undefined, which is
-    // the documented zero-break behavior). `ctx.worlds` is assigned the SAME
+    // 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
     // default world is registered AFTER mount returns, and this reference
     // must observe that later push.
     if (host.game) {
       ctx.game = host.game;
-      ctx.worlds = host.game.worlds;
+      ctx.roots = host.game.roots;
     }
     ctx.components = createComponentManager(ctx, physicsRegistry);
     collisions.onCollision(
@@ -370,6 +375,85 @@ export class VgaiSceneGameAdapter implements GameAdapter {
     // 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.
+    const debugRegistry: DebugRegistry =
+      (host.game ? getDebugRegistry(host.game) : null) ??
+      createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+    systemAdapters.debug = debugRegistry.adapter;
+    ctx.debug = debugRegistry.forWorld(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`
+    // provider always reflects the CURRENT action set, not a snapshot taken
+    // at mount time. Per-world (not a single last-writer-wins slot) since
+    // D15/T-D15.5 — see `debug-registry.ts`'s `setInputActionsSource` doc.
+    debugRegistry.setInputActionsSource(this.id, () =>
+      typeof input.actionNames === 'function'
+        ? input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) }))
+        : [],
+    );
+    // D15/T-D15.5 — same lazy-supplier pattern (and same headless-stand-in
+    // guard) as `setInputActionsSource` immediately above: the built-in
+    // `input.trace` provider always reads the CURRENT recorded trace, never
+    // a snapshot taken at mount time. `seed`/`fixedDt` are assembled here
+    // (not inside `InputManager`, which has no business knowing about
+    // `ctx.random` or the loop) — the two replay-critical metadata fields
+    // the design doc's format sketch (§2.c) calls for beside the raw
+    // per-tick deltas; `null` only absent a Game/ctx.random behind this
+    // mount, matching every other "no Game" fallback in this file.
+    debugRegistry.setInputTraceSource(this.id, () => {
+      const raw: { version: 1; ticks: unknown[] } =
+        typeof input.getInputTrace === 'function'
+          ? input.getInputTrace()
+          : { version: 1, ticks: [] };
+      const seed = (host.game ? getSeededRandom(host.game) : null)?.seed ?? null;
+      const fixedDt = host.game?.loop.fixedDt ?? null;
+      return { version: raw.version, seed, fixedDt, ticks: raw.ticks };
+    });
+    // Task 2.1 — the same InputManager instance, wired as the debug bridge's
+    // actuation target (`runtime/debug-bridge.ts`'s `input.*` methods) at the
+    // same seed spot as `setInputActionsSource` above. Per-world (D15 review
+    // objection 2 fix) — see `debug-registry.ts`'s `setVirtualInputTarget`
+    // doc for why this used to be a single last-writer-wins slot.
+    debugRegistry.setVirtualInputTarget(this.id, {
+      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+      tapVirtualAction: (action) => input.tapVirtualAction(action),
+      clearVirtualActions: () => input.clearVirtualActions(),
+      scheduleActionAtTick: (tick, action, value) =>
+        input.scheduleActionAtTick(tick, action, value),
+      startInputRecording: () => input.startInputRecording(),
+      stopInputRecording: () => input.stopInputRecording(),
+      isInputRecording: () => input.isInputRecording(),
+      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+    });
+    // R4-class fix — wire the InputManager's `'input.schedule.dropped'` sink
+    // to THIS world's debug registry, same seed spot/precedent as
+    // `setInputActionsSource`/`setVirtualInputTarget` above (typeof-guarded:
+    // a headless `InputManager` stand-in may have no `setDebugEmit`).
+    if (typeof input.setDebugEmit === 'function') {
+      input.setDebugEmit((event, detail) => ctx.debug?.emit(event, detail));
+    }
+    // D15 (T-D15.1) — same "ONE per Game root, shared across every world"
+    // pattern as the debug registry immediately above: `getSeededRandom
+    // (host.game)` reaches the SAME `SeededRandom` `createGame` filed (boot-
+    // seeded by the manifest-aware mount path, `mount-manifest.ts`, before
+    // ANY world's `mount()`/`setup()` runs — see `createGame`'s own doc
+    // comment), so every world's `ctx.random` is the identical instance, not
+    // a per-world copy. Same absence precedent as `ctx.debug`: a mount with
+    // no Game shell at all gets a private, mount-local surface instead.
+    ctx.random =
+      (host.game ? getSeededRandom(host.game) : null) ??
+      createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
 
     // Snapshot of the engine-owned adapter kinds, taken right after seeding
     // and before any setup() has had a chance to run. `hotReload`/`disposeGame`
@@ -396,13 +480,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       c.traverse((n) => setUserData(n, 'engineInternal', true));
     }
     let currentCleanup: GameCleanup | null = null;
-    let sceneUIHandle: SceneUIHandle | null = null;
     let batchSystem: RenderBatchSystem | null = null;
-    // The scenePath/sceneData branch's resolved SceneInstance, if either ran
-    // (stays undefined for a `setup`-based mount — see the `sceneUI` deriva-
-    // tion below). Single source of truth for both the scene-graph `ui` tree
-    // and (potentially, in future) other instance-derived wiring.
-    let sceneInstance: SceneInstance | undefined;
 
     // Apply scene-level render settings + transparent auto-batching after a scene
     // loads (GPU host only). Gated on the resolved `environment.rendering` cascade
@@ -441,61 +519,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       }
     };
 
-    // Scratch vector for the D5 default worldProjector — reused across calls
-    // (one per bound world-tracked canvas per render), never allocated per-frame.
-    const _sceneUIProjectorTmp = new THREE.Vector3();
-
-    // The D4 default data source subscribes to game.state for its whole
-    // lifetime with no unsubscribe path, so it must be built at most ONCE per
-    // adapter mount — buildSceneUIServices runs again on every late
-    // setSceneUIServices call, and rebuilding it there would both leak a
-    // subscription and force every bound node to resubscribe to a fresh store.
-    let defaultSceneUIData: SceneUIDataSourceLike | undefined;
-
-    /**
-     * Assemble the services `renderSceneUI` receives (design/24-scene-ui.md
-     * D2): engine defaults (D4 data source, D5 worldProjector, D6 onEvent) <-
-     * the project's per-mount UI registry (D11, editor-play threading) <-
-     * game-registered services (`ctx.setSceneUIServices`) — per key, each
-     * later layer winning over the one before it.
-     */
-    const buildSceneUIServices = (inst: SceneInstance): SceneUIGameServices => {
-      const defaults: SceneUIGameServices = {
-        onEvent: (handlerId) => {
-          console.warn(
-            `scene-ui: unhandled UI event "${handlerId}" — register onEvent via ctx.setSceneUIServices`,
-          );
-        },
-        worldProjector: (id) => {
-          const obj = inst.entities.get(id);
-          if (!obj) return null;
-          const projected = obj.getWorldPosition(_sceneUIProjectorTmp).project(camera);
-          if (projected.z > 1) return null; // behind the camera -> hidden
-          const w = uiContainer.clientWidth;
-          const h = uiContainer.clientHeight;
-          // Rounded (not sub-pixel) — matches CrtScreen's integer-rounding
-          // (crt-screen.ts), which exists specifically to stop an asymptotic
-          // camera lerp from shimmering a tracked canvas every frame.
-          return {
-            x: Math.round(((projected.x + 1) / 2) * w),
-            y: Math.round(((1 - projected.y) / 2) * h),
-          };
-        },
-      };
-      // Lazily and at-most-once; skipped entirely while the game supplies its
-      // own `data` service (no point subscribing a default nobody reads).
-      if (!sceneUIServices.data && ctx.game && componentRegistry) {
-        defaultSceneUIData ??= gameStateDataSource(ctx.game, componentRegistry);
-        defaults.data = defaultSceneUIData;
-      }
-      const registryPortion: SceneUIGameServices = {
-        ...(uiRegistry?.components ? { components: uiRegistry.components } : {}),
-        ...(uiRegistry?.transforms ? { transforms: uiRegistry.transforms } : {}),
-        ...(uiRegistry?.strings ? { strings: uiRegistry.strings } : {}),
-      };
-      return { ...defaults, ...registryPortion, ...sceneUIServices };
-    };
-
     const loadFromData = async (data: SceneFile): Promise<SceneInstance> => {
       const inst = await loadSceneFromData(data, {
         scene,
@@ -518,6 +541,9 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       if (headless) throw new Error('VgaiSceneGameAdapter: setup-based games require a GPU host');
       currentCleanup = await setup(ctx, editorPreview);
     } else if (scenePath) {
+      // #139: captured BEFORE load so adoptSceneCamera can tell whether a
+      // component (e.g. SceneCamera.init) already framed the camera.
+      const preLoadPose = captureCameraPose(camera);
       const inst = await loadScene(scenePath, {
         scene,
         rapierWorld: ctx.rapierWorld,
@@ -529,11 +555,10 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         particleRenderer: ctx.particles.batchedRenderer,
         ...(headless ? {} : { renderer }),
       });
-      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera);
+      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera, preLoadPose);
       applySceneRendering(inst);
       applySceneNavigation(inst);
       ctx.systems.add('postPhysics', (dt) => inst.update(dt));
-      sceneInstance = inst;
       // 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.
@@ -544,9 +569,9 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         },
       };
     } else if (sceneData) {
+      const preLoadPose = captureCameraPose(camera);
       const inst = await loadFromData(sceneData);
-      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera);
-      sceneInstance = inst;
+      applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera, preLoadPose);
       currentCleanup = {
         dispose: () => {
           inst.navMesh?.dispose(scene);
@@ -555,19 +580,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       };
     }
 
-    // Render scene-graph UI (the `ui` tree) into the overlay via the injected React
-    // renderer (B1). Sourced from the loaded `SceneInstance` — the single source of
-    // truth for BOTH the scenePath and sceneData branches (R8 item 7 / B: previously
-    // only sceneData's raw `SceneFile.ui` was read via a `resolvedSceneData` special-
-    // case, so a scenePath mount's `ui` tree was silently dropped even though
-    // `loadScene` fully parses it). A `setup`-based mount has no `sceneInstance` at
-    // all — its game owns any UI mounting itself. No-op if no UI or no renderer
-    // registered. Engine stays React-free.
-    const sceneUI = sceneInstance?.ui;
-    if (sceneUI && sceneInstance && !headless) {
-      sceneUIHandle = renderSceneUI(uiContainer, sceneUI, buildSceneUIServices(sceneInstance));
-    }
-
     // Idempotency guard for disposeGame — see below. Declared here (not inside
     // disposeGame) so hotReload can also refuse to run on an already-disposed
     // adapter.
@@ -654,13 +666,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       });
       safeStep('clearAssetCaches', () => clearAssetCaches());
       safeStep('debugDraw.clear', () => debugDraw.clear());
-      safeStep('sceneUIHandle.dispose', () => {
-        sceneUIHandle?.dispose();
-        sceneUIHandle = null;
-      });
-      safeStep('uiContainer reset', () => {
-        uiContainer.innerHTML = '';
-      });
 
       // R8 item 7 (C) — disposeGame (Stop) used to skip both of these, unlike
       // hotReload (warm restart), which already ran them: a game lifecycle
@@ -669,7 +674,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       // systemAdapters kind (e.g. a `setup`-registered 'networking') survived
       // a Stop and would be visible on a STALE `mounted.systems` even though
       // the game that owned it is gone. Same two steps, same relative
-      // ordering as hotReload (right after `uiContainer reset`, before the
+      // ordering as hotReload (before the
       // engine-owned audio/input teardown below, which hotReload doesn't
       // touch at all since it warm-restarts rather than tearing engine
       // subsystems down).
@@ -679,6 +684,12 @@ export class VgaiSceneGameAdapter implements GameAdapter {
           if (!engineAdapterKinds.has(kind)) delete systemAdapters[kind as keyof SystemAdapters];
         }
       });
+      // Defect 2 fix: a full Stop means the whole GAME is going away (every
+      // world it mounted, plus any react-door registrations from its HUDs)
+      // — unlike hotReload below (a SINGLE mount warm-restarting), so this is
+      // the one call site that legitimately wants strip()'s global, no-id
+      // form rather than scoping to `this.id`.
+      safeStep('debugRegistry.strip', () => debugRegistry.strip());
 
       if (!headless) {
         safeStep('audio teardown', () => {
@@ -689,6 +700,7 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         });
       }
       safeStep('input.dispose', () => input.dispose());
+      safeStep('gpuTimer.dispose', () => gpuTimer?.dispose());
     };
 
     const hotReload = async (
@@ -754,20 +766,6 @@ export class VgaiSceneGameAdapter implements GameAdapter {
         scene.environment = null;
       });
       safeStep('debugDraw.clear', () => debugDraw.clear());
-      safeStep('sceneUIHandle.dispose', () => {
-        sceneUIHandle?.dispose();
-        sceneUIHandle = null;
-      });
-      // Strip game-registered scene-UI services back to none before the
-      // incoming game's setup/init runs (D7) — same contract as the
-      // systemAdapters strip below: a disposed game's onEvent/data/
-      // worldProjector must never leak onto the next mount.
-      safeStep('reset sceneUIServices', () => {
-        sceneUIServices = {};
-      });
-      safeStep('uiContainer reset', () => {
-        uiContainer.innerHTML = '';
-      });
 
       // Bulk-remove every system the outgoing game registered (this restart's
       // predecessor) so warm restarts never accumulate duplicate systems —
@@ -787,6 +785,16 @@ export class VgaiSceneGameAdapter implements GameAdapter {
           if (!engineAdapterKinds.has(kind)) delete systemAdapters[kind as keyof SystemAdapters];
         }
       });
+      // Hot-reload re-seed (spec §3.1): the incoming game's setup (below)
+      // re-registers its providers/commands under the SAME worldId — strip()
+      // clears the outgoing game's registrations first so that re-seed is
+      // silent (no stale duplicate-name warning) rather than "replacing" a
+      // dead game's entries. Defect 2 fix: scoped to THIS mount's worldId
+      // (`this.id`) — a blind global strip() here wiped every OTHER live
+      // world's registrations on every warm restart of just this one, plus
+      // every react-door registration (whose `useEffect` cleanup never
+      // re-fires to restore them after someone else's strip).
+      safeStep('debugRegistry.strip', () => debugRegistry.strip(this.id));
 
       currentCleanup = await newSetup(ctx, newEditorPreview);
     };
@@ -833,17 +841,68 @@ function applyEditorCamera(
   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) {
+  if (parent && !componentFramedCamera) {
     parent.updateMatrixWorld(true);
     runtimeCamera.position.copy(parent.getWorldPosition(new THREE.Vector3()));
-    runtimeCamera.quaternion.copy(parent.getWorldQuaternion(new THREE.Quaternion()));
+    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;