@vgai/engine 0.5.5 → 0.5.6

package/dist/adapter/setup-three-root-adapter.js

@@ -0,0 +1,791 @@
+/**
+ * SetupThreeRootAdapter — the first-party implementer of {@link RootAdapter}
+ * that mounts ONE three root from an imperative `setup(ctx)` function.
+ *
+ * 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.
+ */
+import RAPIER from '@dimforge/rapier3d-compat';
+import * as THREE from 'three';
+import { clearAssetCaches } from '../asset-loaders';
+import { createSeededRandom, DEFAULT_SEEDED_RANDOM_SEED, getSeededRandom, } from '../core/seeded-random';
+import { createSimClock, getSimClock } from '../core/sim-clock';
+import { createSystemRunner } from '../core/system-runner';
+import { createDebugDraw } from '../dev/debug-draw';
+import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
+import { collectRenderMemory } from '../dev/render-memory';
+import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
+import { createWebGLGpuTimer } from '../dev/webgl-gpu-timer';
+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 { updateSceneLODs } from '../render/lod';
+import { disposeSparkRendererWhenIdle, SPARK_DISCOVERY_INTERVAL_MS, sceneHasGaussianSplat, shouldDiscoverGaussianSplat, } from '../render/spark-renderer-lifecycle';
+import { ViewportShadingRenderer } from '../render/viewport-shading';
+import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
+import { disposeDebrisSubtree } from '../runtime/game';
+import { setupAudio } from '../setup/setup-audio';
+import { setupParticles } from '../setup/setup-particles';
+import { setupPhysics, updatePhysicsDebug } from '../setup/setup-physics';
+import { createSceneView } from '../setup/setup-renderer';
+import { createAudioSystemAdapter, releaseAudioMeters } 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 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, setup) {
+    return new SetupThreeRootAdapter({ id, setup });
+}
+export class SetupThreeRootAdapter {
+    config;
+    id;
+    constructor(config = {}) {
+        this.config = config;
+        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) {
+        const { setup, editorPreview, 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 ownsInput = !host.game;
+        const input = host.game?.input ?? (headless ? headlessInput() : new InputManager());
+        if (!headless) {
+            if (host.game)
+                await host.game.loadInputMap(inputMapPath);
+            else
+                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;
+        // W4b (F11 frame debugger): first-party WebGL2 frame capture, constructed
+        // under the SAME real-context guard as gpuTimer — a headless/stub mount
+        // (`frameCaptureContextFor` returns null) never builds it and never
+        // registers `renderDebug`, so the capability is honestly absent there. The
+        // capture only patches the context WHILE a `captureFrame()` is armed (see
+        // beginPass/endPass in the render system below); every non-capture frame
+        // is zero-overhead.
+        const frameCaptureContext = frameCaptureContextFor(headless, rendererContext);
+        const frameCapture = frameCaptureContext ? createWebGLFrameCapture(frameCaptureContext) : null;
+        const renderDebugWiring = frameCapture
+            ? createRenderDebugAdapter({
+                capture: frameCapture,
+                scene,
+                memory: () => collectRenderMemory(scene, renderer.info),
+            })
+            : null;
+        const viewportShading = new ViewportShadingRenderer();
+        let viewportShadingMode = 'solid';
+        // --- System runner (engine-level systems) ---
+        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
+        // 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.
+        if (ownsInput)
+            systems.add('input', () => input.poll(), { 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);
+            updateSceneLODs(scene, camera);
+            sparkDiscoveryElapsedMs += dt * 1_000;
+            const shouldDiscover = shouldDiscoverGaussianSplat(0, sparkDiscoveryElapsedMs);
+            if (!sparkRenderer && !sparkRendererLoading && !sparkRendererFailed && shouldDiscover) {
+                sparkDiscoveryElapsedMs = 0;
+                if (!sceneHasGaussianSplat(scene))
+                    return;
+                sparkRendererLoading = true;
+                void import('@sparkjsdev/spark')
+                    .then(({ SparkRenderer }) => {
+                    if (disposed || sparkRenderer)
+                        return;
+                    sparkRenderer = new SparkRenderer({ renderer, enableLod: false });
+                    sparkRenderer.traverse((node) => setUserData(node, 'engineInternal', true));
+                })
+                    .catch((error) => {
+                    sparkRendererFailed = true;
+                    // biome-ignore lint/suspicious/noConsole: A missing renderer chunk must fail once and loudly, not retry every frame.
+                    console.error('Failed to install SparkRenderer for a live Gaussian splat.', error);
+                })
+                    .finally(() => {
+                    sparkRendererLoading = false;
+                });
+            }
+        }, { name: 'materials-and-particles' });
+        if (!headless) {
+            systems.add('render', (dt) => {
+                if (host.game?.profiler.enabled)
+                    gpuTimer?.begin();
+                if (sparkRenderer)
+                    scene.add(sparkRenderer);
+                // W4b: arm-gated frame capture wraps the real draw calls. beginPass
+                // is a no-op unless a captureFrame() armed it; afterRender delivers
+                // the assembled capture to a pending captureFrame() and restores the
+                // patched context — in the SAME finally as gpuTimer.end(). Spark is
+                // added before this so its draws fall inside the captured frame.
+                renderDebugWiring?.beforeRender();
+                try {
+                    viewportShading.render(scene, viewportShadingMode, () => composer.render(dt), 
+                    // Scene authoring can temporarily attach editor infrastructure
+                    // (gizmos/helpers on their own layer) to this same native scene.
+                    // Only replace materials the actual game camera can render.
+                    (mesh) => camera.layers.test(mesh.layers));
+                }
+                finally {
+                    renderDebugWiring?.afterRender();
+                    sparkRenderer?.removeFromParent();
+                    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 = () => {
+            if (ownsInput)
+                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 = {};
+        // 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 = host.game ? getSimClock(host.game) : null;
+        const clock = 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 = {
+            scene,
+            camera,
+            rapierWorld: physics.rapierWorld,
+            rapier: RAPIER,
+            physics: physicsRegistry,
+            input,
+            collisions,
+            composer,
+            audio,
+            particles,
+            debugDraw,
+            assets,
+            systems,
+            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 `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;
+        }
+        // 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();
+        // 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
+        // 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.
+        // 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();
+        const resolveNodeObject = (nodeId) => {
+            const cached = nodeObjectCache.get(nodeId);
+            if (cached?.parent)
+                return cached;
+            let found = 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): 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;
+        // W4b: the render-debug capability is engine-owned and first-party, seeded
+        // here (like physics/input/assets) BEFORE the engineAdapterKinds snapshot
+        // 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.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`
+        // 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 (!host.game && 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 sparkRenderer = null;
+        let sparkRendererLoading = false;
+        let sparkRendererFailed = false;
+        // Discovery is render-loop scheduling, so advance it from the loop's `dt`
+        // instead of introducing a second wall-clock frontier into engine code.
+        // Start at the threshold so the first rendered frame discovers eager splats.
+        let sparkDiscoveryElapsedMs = SPARK_DISCOVERY_INTERVAL_MS;
+        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
+        // lazily INSIDE the first draw calls — measured as ~0.5s of main-thread
+        // driver stalls on every editor play press. Gated on
+        // KHR_parallel_shader_compile: with the extension, compileAsync overlaps
+        // the compiles with the play transition; WITHOUT it (software
+        // rasterizers — SwiftShader in CI) compileAsync degenerates into one big
+        // synchronous compile that delays mount by whole seconds, strictly worse
+        // than the lazy first-draw path it was replacing. Best-effort: lazy
+        // compilation stays correct if it throws, and test hosts pass renderer
+        // stubs without these methods.
+        const glContext = typeof renderer.getContext === 'function' ? renderer.getContext() : undefined;
+        const parallelCompile = !!glContext &&
+            typeof glContext.getExtension === 'function' &&
+            !!glContext.getExtension('KHR_parallel_shader_compile');
+        if (!headless && parallelCompile && typeof renderer.compileAsync === 'function') {
+            try {
+                await renderer.compileAsync(scene, camera);
+            }
+            catch {
+                // Fall back to lazy compilation.
+            }
+        }
+        // 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 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, fn) => {
+            try {
+                fn();
+            }
+            catch (err) {
+                console.error(`SetupThreeRootAdapter: 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('currentCleanup.dispose', () => {
+                currentCleanup?.dispose();
+                currentCleanup = null;
+            });
+            safeStep('sparkRenderer.dispose', () => {
+                if (!sparkRenderer)
+                    return;
+                sparkRenderer.removeFromParent();
+                disposeSparkRendererWhenIdle(sparkRenderer);
+                sparkRenderer = 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));
+            }
+            // 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 = [];
+                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];
+                }
+            });
+            // A game-hosted mount owns only its world-scoped registrations; sibling
+            // roots remain alive during root replacement. A bare standalone adapter
+            // owns the registry and can clear it globally.
+            safeStep('debugRegistry.strip', () => host.game ? debugRegistry.strip(this.id) : debugRegistry.strip());
+            // 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) {
+                safeStep('audio teardown', () => {
+                    audio.masterGain.gain.value = 0;
+                    audio.listener.context.suspend();
+                    camera.remove(audio.listener);
+                    composer.dispose();
+                });
+            }
+            if (ownsInput)
+                safeStep('input.dispose', () => input.dispose());
+            // W4b: restore any pending capture wrappers and reject a capture in
+            // flight (a Stop mid-capture must not leave the context patched).
+            safeStep('renderDebug.dispose', () => renderDebugWiring?.dispose());
+            safeStep('gpuTimer.dispose', () => gpuTimer?.dispose());
+            safeStep('viewportShading.dispose', () => viewportShading.dispose());
+        };
+        const hotReload = async (newSetup, newEditorPreview) => {
+            if (disposed) {
+                throw new Error('SetupThreeRootAdapter: cannot hotReload after dispose()/stop()');
+            }
+            // Full parity with disposeGame for the parts a warm restart rebuilds:
+            // 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('currentCleanup.dispose', () => {
+                currentCleanup?.dispose();
+                currentCleanup = null;
+            });
+            // 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('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: 'three',
+            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,
+            setViewportShadingMode: (mode) => {
+                viewportShadingMode = mode;
+            },
+            hotReload,
+            frame: {
+                runPhase: (phase, dt) => systems.runPhase(phase, dt),
+                endFrame: postFrame,
+            },
+        };
+    }
+}
+/** Headless input stand-in — `InputManager` attaches `window` listeners in its
+ *  constructor, which Node lacks. A headless mount 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 mount/cleanup
+ *  touch are present. */
+function headlessAudio() {
+    return {
+        listener: undefined,
+        masterGain: { gain: { value: 1 } },
+    };
+}