@vgai/engine 0.5.0 → 0.5.2

package/dist/adapter/vgai-scene-game-adapter.js

@@ -1,762 +0,0 @@
-/**
- * VgaiSceneGameAdapter — the FIRST-PARTY implementer of {@link GameAdapter}.
- *
- * 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).
- *
- * `GameSetupFn` / `GameContext` are imported ONLY here (and in the example
- * `fromSetup` wrappers) — never by the host. That confinement is the inversion.
- */
-import RAPIER from '@dimforge/rapier3d-compat';
-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';
-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 { resolveRenderSettings } from '../render/render-settings';
-import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
-import { tickCustomMaterials } from '../scene/material-registry';
-import { clearAssetCaches, loadScene, loadSceneFromData, updateSceneLODs, } from '../scene/scene-loader';
-import { hasUserData, setUserData } from '../scene/user-data';
-import { setupAudio } from '../setup/setup-audio';
-import { setupParticles } from '../setup/setup-particles';
-import { setupPhysics, updatePhysicsDebug } from '../setup/setup-physics';
-import { applyRendererSettings, applyScenePostProcessing, createSceneView, } from '../setup/setup-renderer';
-import { createAudioSystemAdapter, createInputManagerAdapter, createNavigationAdapter, createVgaiAssetAdapter, } from './first-party-systems';
-import { createRapierPhysicsAdapter } from './rapier-physics-adapter';
-/** Minimal stand-in for the GPU composer when mounting headlessly. */
-function headlessComposer(renderer) {
-    return {
-        render: () => { },
-        setSize: () => { },
-        dispose: () => { },
-        addPass: () => { },
-        removeAllPasses: () => { },
-        passes: [],
-        getRenderer: () => renderer,
-    };
-}
-/**
- * Wrap a first-party `setup` function as a {@link GameAdapter}. 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, setup) {
-    return new VgaiSceneGameAdapter({ id, setup });
-}
-export class VgaiSceneGameAdapter {
-    config;
-    id;
-    constructor(config = {}) {
-        this.config = config;
-        this.id = config.id ?? 'vgai-scene';
-    }
-    // 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) {
-        const { setup, editorPreview, scenePath, sceneData, componentRegistry, inputMapPath = '/inputmaps/default.inputmap.json', assetPrefix = '/', } = this.config;
-        const headless = host.headless === true;
-        const { width, height } = host.surface;
-        const renderer = host.renderer;
-        setAssetPrefix(assetPrefix);
-        // --- Scene view (scene/camera/composer). Browser: the canonical builder, so
-        //     behavior is byte-identical to the old create-runtime. Headless: plain
-        //     scene/camera + a no-op composer (no GPU). ---
-        let scene;
-        let camera;
-        let composer;
-        if (headless) {
-            scene = new THREE.Scene();
-            scene.background = new THREE.Color(0x1a1a2e);
-            camera = new THREE.PerspectiveCamera(60, width / height || 1, 0.1, 1000);
-            camera.position.set(0, 5, 10);
-            camera.lookAt(0, 0, 0);
-            composer = headlessComposer(renderer);
-        }
-        else {
-            const view = createSceneView(renderer, width, height);
-            scene = view.scene;
-            camera = view.camera;
-            composer = view.composer;
-        }
-        // --- Rapier physics ---
-        await RAPIER.init();
-        const physics = setupPhysics(RAPIER, scene);
-        const physicsRegistry = createPhysicsRegistry();
-        const writeTransforms = createTransformWriter(physicsRegistry, scene);
-        // --- Input (InputManager attaches window listeners; stub it headlessly) ---
-        const input = headless ? headlessInput() : new InputManager();
-        if (!headless)
-            await input.loadMap(inputMapPath);
-        // --- Collision system ---
-        const collisions = createCollisionSystem(physics.rapierWorld, physics.eventQueue);
-        // --- Audio (Web Audio — browser only) ---
-        const audio = headless ? headlessAudio() : setupAudio(camera);
-        // --- Particles (three.quarks BatchedRenderer) ---
-        const particles = setupParticles(scene);
-        // --- 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(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('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) => {
-                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) ---
-        const onDebugToggle = (e) => {
-            if (e.code === 'KeyP') {
-                physics.debugEnabled = !physics.debugEnabled;
-                physics.debugMesh.visible = physics.debugEnabled;
-            }
-        };
-        if (!headless)
-            window.addEventListener('keydown', onDebugToggle);
-        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
-        // the first-party entries below; GAME-owned capabilities (networking,
-        // navigation) are registered by the game's setup through the ctx hook.
-        // The editor holds this same object reference (setActiveSystems), so
-        // late registrations are visible to its panels at read time.
-        const systemAdapters = {};
-        // --- GameContext (the first-party runtime surface) ---
-        const ctx = {
-            scene,
-            camera,
-            rapierWorld: physics.rapierWorld,
-            rapier: RAPIER,
-            physics: physicsRegistry,
-            input,
-            collisions,
-            composer,
-            audio,
-            particles,
-            debugDraw,
-            assets,
-            systems,
-            components: null,
-            registerSystemAdapter: (kind, adapter) => {
-                systemAdapters[kind] = adapter;
-            },
-        };
-        // 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
-        // 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.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
-        // from here on is "game" content that `hotReload` bulk-removes via
-        // `systems.removeAllNonEngine()` on every restart (T1.7).
-        systems.markEngineBoundary();
-        // First-party System adapters over the real subsystems — seeded HERE,
-        // BEFORE setup()/scene load runs below, so that a game which registers any
-        // of these kinds during its own setup (via `ctx.registerSystemAdapter`)
-        // 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.debugMesh);
-        systemAdapters.input = createInputManagerAdapter(input);
-        systemAdapters.assets = createVgaiAssetAdapter();
-        // 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.
-        const 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 = 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`
-        // use this to strip every GAME-registered kind (including an override of a
-        // first-party kind) left over from the outgoing game, so a warm restart or
-        // a full stop never exposes a disposed game's networking/etc. adapter to
-        // the next setup.
-        const engineAdapterKinds = new Set(Object.keys(systemAdapters));
-        // 'navigation' is engine-owned too (R8 item 7), but the scene load that
-        // populates it (below, `applySceneNavigation`) happens AFTER this
-        // snapshot — add it explicitly so the generic "strip every non-engine
-        // kind" step (hotReload/disposeGame) never mistakes a first-party
-        // navigation adapter for game-registered content and deletes it. (The
-        // adapter is still kept in sync with the CURRENT scene's NavMeshManager
-        // via the dedicated `clear navigation adapter` teardown step below, which
-        // runs independently of this snapshot.)
-        engineAdapterKinds.add('navigation');
-        // --- Scene / game setup ---
-        const engineSceneChildren = new Set(scene.children.slice());
-        // Tag engine-owned infra (particle BatchedRenderer, debug-draw + subtrees) so
-        // the editor's play-mode hierarchy skips them — they're not game entities.
-        for (const c of engineSceneChildren) {
-            c.traverse((n) => setUserData(n, 'engineInternal', true));
-        }
-        let currentCleanup = null;
-        let batchSystem = null;
-        // 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 = (inst) => {
-            if (headless)
-                return;
-            const scope = inst.environment?.rendering;
-            const settings = resolveRenderSettings(scope);
-            // live renderer settings (shadows, resolution scale)
-            applyRendererSettings(renderer, scope);
-            // post-processing master switch: (re)build when the scene defines effects OR
-            // the master is off (to strip the default bloom pass down to a plain scene).
-            if (inst.environment?.postProcessing || !settings['postProcessing']) {
-                applyScenePostProcessing(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.__vgaiBatch = batchSystem;
-            }
-        };
-        // 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) => {
-            if (inst.navMesh) {
-                systemAdapters.navigation = createNavigationAdapter(inst.navMesh);
-            }
-            else {
-                delete systemAdapters.navigation;
-            }
-        };
-        const loadFromData = async (data) => {
-            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 }),
-            });
-            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) {
-            // #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,
-                rapier: ctx.rapier,
-                physics: ctx.physics,
-                audioListener: ctx.audio.listener,
-                ...(componentRegistry ? { componentRegistry } : {}),
-                componentManager: ctx.components,
-                particleRenderer: ctx.particles.batchedRenderer,
-                ...(headless ? {} : { renderer }),
-            });
-            applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera, preLoadPose);
-            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) {
-            const preLoadPose = captureCameraPose(camera);
-            const inst = await loadFromData(sceneData);
-            applyEditorCamera(editorPreview, camera) || adoptSceneCamera(inst, camera, preLoadPose);
-            currentCleanup = {
-                dispose: () => {
-                    inst.navMesh?.dispose(scene);
-                    inst.dispose();
-                },
-            };
-        }
-        // Idempotency guard for disposeGame — see below. Declared here (not inside
-        // disposeGame) so hotReload can also refuse to run on an already-disposed
-        // adapter.
-        let disposed = false;
-        // 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
-        // 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, fn) => {
-            try {
-                fn();
-            }
-            catch (err) {
-                console.error(`VgaiSceneGameAdapter: teardown step "${label}" threw (continuing)`, err);
-            }
-        };
-        const disposeGame = () => {
-            // A second stop() must be a safe no-op — do NOT double-free the Rapier
-            // world/EventQueue (WASM handles panic/throw on a second free) or
-            // double-run teardown side effects.
-            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;
-            });
-            // The scene instance's NavMeshManager (if any) was just disposed above
-            // (currentCleanup.dispose calls `inst.navMesh?.dispose(scene)`) — clear
-            // the wrapper too, or `mounted.systems.navigation` would keep pointing
-            // at a freed manager (R8 item 7). Unconditional: harmless if navigation
-            // was never set.
-            safeStep('clear navigation adapter', () => {
-                delete systemAdapters.navigation;
-            });
-            if (!headless) {
-                safeStep('removeEventListener(keydown)', () => window.removeEventListener('keydown', onDebugToggle));
-            }
-            // 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());
-            safeStep('remove rigid bodies', () => {
-                const handles = [];
-                physics.rapierWorld.forEachRigidBody((b) => handles.push(b.handle));
-                for (const h of handles) {
-                    const b = physics.rapierWorld.getRigidBody(h);
-                    if (b)
-                        physics.rapierWorld.removeRigidBody(b);
-                }
-            });
-            safeStep('rapierWorld.free', () => physics.rapierWorld.free());
-            safeStep('eventQueue.free', () => physics.eventQueue.free()); // WASM handle — must be freed manually
-            safeStep('physicsRegistry.clear', () => physicsRegistry.clear());
-            safeStep('scene children dispose', () => {
-                for (const obj of [...scene.children]) {
-                    scene.remove(obj);
-                    obj.traverse((node) => {
-                        if (node instanceof THREE.Mesh) {
-                            if (!hasUserData(node, '__sharedGeometry'))
-                                node.geometry?.dispose();
-                            if (Array.isArray(node.material))
-                                node.material.forEach((m) => {
-                                    m.dispose();
-                                });
-                            else
-                                node.material?.dispose();
-                        }
-                    });
-                }
-                scene.fog = null;
-                scene.background = null;
-                scene.environment = null;
-            });
-            safeStep('clearAssetCaches', () => clearAssetCaches());
-            safeStep('debugDraw.clear', () => debugDraw.clear());
-            // R8 item 7 (C) — disposeGame (Stop) used to skip both of these, unlike
-            // hotReload (warm restart), which already ran them: a game lifecycle
-            // system registered via `ctx.systems.register(...)` never had its
-            // `dispose()` hook called on a full Stop, and a game-registered
-            // 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 (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).
-            safeStep('systems.removeAllNonEngine', () => systems.removeAllNonEngine());
-            safeStep('strip game-registered systemAdapters', () => {
-                for (const kind of Object.keys(systemAdapters)) {
-                    if (!engineAdapterKinds.has(kind))
-                        delete systemAdapters[kind];
-                }
-            });
-            // 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', () => {
-                    audio.masterGain.gain.value = 0;
-                    audio.listener.context.suspend();
-                    camera.remove(audio.listener);
-                    composer.dispose();
-                });
-            }
-            safeStep('input.dispose', () => input.dispose());
-            safeStep('gpuTimer.dispose', () => gpuTimer?.dispose());
-        };
-        const hotReload = async (newSetup, newEditorPreview) => {
-            if (disposed) {
-                throw new Error('VgaiSceneGameAdapter: 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
-            // 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
-            // 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 = [];
-                physics.rapierWorld.forEachRigidBody((b) => handles.push(b.handle));
-                for (const h of handles) {
-                    const b = physics.rapierWorld.getRigidBody(h);
-                    if (b)
-                        physics.rapierWorld.removeRigidBody(b);
-                }
-                physicsRegistry.clear();
-            });
-            safeStep('scene children dispose', () => {
-                for (const obj of [...scene.children]) {
-                    if (engineSceneChildren.has(obj))
-                        continue;
-                    scene.remove(obj);
-                    obj.traverse((node) => {
-                        if (node instanceof THREE.Mesh) {
-                            if (!hasUserData(node, '__sharedGeometry'))
-                                node.geometry?.dispose();
-                            if (Array.isArray(node.material))
-                                node.material.forEach((m) => {
-                                    m.dispose();
-                                });
-                            else
-                                node.material?.dispose();
-                        }
-                    });
-                }
-                scene.fog = null;
-                scene.background = null;
-                scene.environment = null;
-            });
-            safeStep('debugDraw.clear', () => debugDraw.clear());
-            // Bulk-remove every system the outgoing game registered (this restart's
-            // predecessor) so warm restarts never accumulate duplicate systems —
-            // engine systems registered before mount()'s boundary mark are untouched.
-            safeStep('systems.removeAllNonEngine', () => systems.removeAllNonEngine());
-            // Strip every GAME-registered systemAdapters kind left by the outgoing
-            // game (including any override of a first-party kind) so the disposed
-            // game's networking/etc. adapter is never exposed to the next setup —
-            // see registerSystemAdapter's docstring in runtime/types.ts. ('navigation'
-            // is engine-kind and is NOT touched here — it's a first-party adapter now,
-            // kept in sync with the current scene's NavMeshManager by the dedicated
-            // `clear navigation adapter` step above instead.) The new setup below
-            // either re-registers a kind or it stays absent.
-            safeStep('strip game-registered systemAdapters', () => {
-                for (const kind of Object.keys(systemAdapters)) {
-                    if (!engineAdapterKinds.has(kind))
-                        delete systemAdapters[kind];
-                }
-            });
-            // 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);
-        };
-        return {
-            kind: 'threejs',
-            scene,
-            camera,
-            firstParty: true,
-            drivesOwnLoop: false,
-            update: (dt) => {
-                systems.run(dt);
-                postFrame();
-            },
-            resize: (w, h) => {
-                const safeWidth = Math.max(1, w);
-                const safeHeight = Math.max(1, h);
-                composer.setSize(safeWidth, safeHeight);
-                camera.aspect = safeWidth / safeHeight;
-                camera.updateProjectionMatrix();
-            },
-            dispose: disposeGame,
-            systems: systemAdapters,
-            ctx,
-            composer: headless ? null : composer,
-            hotReload,
-            frame: {
-                runPhase: (phase, dt) => systems.runPhase(phase, dt),
-                endFrame: postFrame,
-            },
-        };
-    }
-}
-// --- Camera precedence helpers (moved from create-runtime, unchanged) ---
-function applyEditorCamera(editor, runtimeCamera) {
-    if (!editor?.viewportCamera)
-        return false;
-    runtimeCamera.position.fromArray(editor.viewportCamera.position);
-    runtimeCamera.quaternion.fromArray(editor.viewportCamera.quaternion);
-    return true;
-}
-export function captureCameraPose(camera) {
-    return { position: camera.position.clone(), quaternion: camera.quaternion.clone() };
-}
-export function adoptSceneCamera(sceneInstance, runtimeCamera, preLoadPose) {
-    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.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. */
-function headlessInput() {
-    return {
-        poll: () => { },
-        endFrame: () => { },
-        dispose: () => { },
-        loadMap: async () => { },
-        isPressed: () => false,
-        getAxis: () => 0,
-    };
-}
-/** Headless audio stand-in (no Web Audio). Only the fields the loader/cleanup
- *  touch are present; setup-based games never mount headlessly. */
-function headlessAudio() {
-    return {
-        listener: undefined,
-        masterGain: { gain: { value: 1 } },
-    };
-}