@vgai/engine 0.5.21 → 0.5.23

package/dist/world3d-react/r3f-adapter.js

@@ -1,634 +0,0 @@
-/**
- * `createR3FAdapter` — wraps a react-three-fiber tree as a first-party
- * `RootAdapter` so an R3F scene mounts as an ordinary `kind: "three"`
- * world: the engine hands `mount()` a `ThreeHostContext` (ITS OWN renderer +
- * canvas + gated loop, per `../adapter/host-context.ts`); this returns a
- * `MountedThreeRoot` (`../adapter/root-adapter.ts`) whose `scene`/`camera`
- * are fiber's REAL `THREE.Scene`/`THREE.Camera` instances.
- *
- * Upstreamed from `examples/r3f-first-party/src/r3f-adapter.tsx` (R4 — the
- * `@engine/world3d-react` opt-in module, mirroring how `pixi/` is the
- * PixiJS surface's opt-in home). The mount semantics
- * are byte-for-byte the example's live-proven Phase-1 bridge. External adopters
- * (alien-stories-style) keep the exact same calling contract.
- *
- * three.js identity: this module never imports `three` itself for scene objects
- * — fiber's internal `import * as THREE from 'three'` must resolve to the SAME
- * instance the engine's `ThreeHostContext.three` points at, which the importing
- * project guarantees via its Vite `resolve.dedupe: ['three', 'react',
- * 'react-dom']` (see `examples/r3f-first-party/vite.config.ts`).
- */
-import { advance, createRoot, extend, flushSync, events as pointerEvents, useFrame, } from '@react-three/fiber';
-import { createElement, Fragment, useEffect, useMemo } from 'react';
-import { applyWorldRendererConfig } from '../adapter/renderer-config';
-import { registerRenderVitals } from '../dev/register-render-vitals';
-import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
-import { collectRenderMemory } from '../dev/render-memory';
-import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
-import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
-import { WorldProvider } from '../react/world-state';
-import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
-import { getDebugRegistry } from '../runtime/debug-registry';
-import { devBuildEnabled } from '../runtime/dev-build';
-import { EngineBridge } from './engine-bridge';
-import { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from './world-context';
-/**
- * Scene depth for any soft-particle system this world mounted, drawn between
- * gameplay and the draw.
- *
- * `useFrame`'s priority is the whole reason this is a component rather than an
- * engine phase: `systems.run(dt)` below finishes BEFORE `advance()`, and
- * `advance()` is where every `useFrame` gameplay callback moves the frame's
- * transforms — depth taken from an engine phase would be one frame stale.
- * Priority `0` puts it after every negative-priority callback (fiber sorts
- * subscribers by priority) and before both a positive-priority composer and
- * fiber's own `state.gl.render` — and, unlike a positive priority, it does NOT
- * flip fiber into manual-render mode (`internal.priority` only counts
- * subscribers with `priority > 0`), so mounting it can never stop an ordinary
- * world from drawing itself.
- *
- * Rendered as the LAST child of the adapter's tree so its subscription lands
- * after the world's own (React completes children before siblings, and fiber's
- * sort is stable) — the tie-break among priority-0 callbacks is insertion
- * order.
- *
- * It is mounted only when THIS host carries a real WebGL context. The editor's
- * design-time host deliberately reconciles the scene without one because the
- * editor viewport owns the real renderer and camera; that viewport runs the
- * same generic depth pass immediately before it presents the adopted scene.
- *
- * Costs nothing while no soft-particle system is armed — see
- * `../render/soft-particle-depth.ts` for what "armed" means and what the pass
- * spends when it is.
- */
-function SoftParticleDepth() {
-    const pass = useMemo(() => createSoftParticleDepthPass(), []);
-    useEffect(() => () => pass.dispose(), [pass]);
-    useFrame(({ gl, scene, camera }) => pass.render(gl, scene, camera), 0);
-    return null;
-}
-/**
- * Build a `RootAdapter` that mounts `options.content` through
- * react-three-fiber, gated entirely by the host's own loop and rendering
- * through the host's own `WebGLRenderer` — never a second renderer, never a
- * second `requestAnimationFrame` loop (design §1.C).
- */
-export function createR3FAdapter(options) {
-    const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
-    return {
-        id,
-        async mount(host) {
-            // Headless honesty — every `mount()` must work headless: the
-            // conformance kit / CI
-            // runs `mount()` in Node — no canvas, no WebGL, no fiber reconciler.
-            // Guard the ENTIRE fiber mount behind `!host.headless` and return a
-            // bare, real scene + camera instead (still `instanceof
-            // host.three.Scene` / `.Camera` — the identity rule holds even here,
-            // since this uses the host's own `three` instance, not a fresh
-            // import). Residual: the hierarchy is empty under headless
-            // conformance — recorded as design O2, not hidden; a react-nil-style
-            // headless reconciler mount is the known fix, out of scope for v1.
-            if (host.headless) {
-                const scene = new host.three.Scene();
-                const camera = new host.three.PerspectiveCamera();
-                return {
-                    kind: 'three',
-                    scene,
-                    camera,
-                    drivesOwnLoop: false,
-                    dispose() {
-                        /* nothing was ever mounted */
-                    },
-                };
-            }
-            // Fiber v9 made the THREE catalogue tree-shakeable: `<Canvas>` calls
-            // `extend(THREE)` for you, a bare `createRoot` does NOT — without this,
-            // the FIRST three intrinsic in the tree (`<color>`, `<ambientLight>`,
-            // …) throws "X is not part of the THREE namespace! Did you forget to
-            // extend?" at reconcile time. Extending with `host.three` (not a fresh
-            // `import * as THREE`) keeps the catalogue on the host's deduped three
-            // instance — the same identity rule the returned scene/camera rely on.
-            // `extend` merges into a module-global catalogue, so calling it once
-            // per mount is idempotent.
-            extend(host.three);
-            // The engine runtime this world OWNS: a real SystemRunner,
-            // provided to the R3F tree via `EngineBridge`.
-            // `update(dt)` below runs the phases under the host loop, so registered
-            // systems tick in engine phase order and freeze under
-            // pause exactly like `useFrame` work does.
-            //
-            // HONESTY NOTE: the manager's ctx is an `R3FGameContext`, not the full
-            // `GameContext`. The shared game-scoped subsystems are REAL
-            // classic-adapter parity (`./world-context.ts`):
-            // `ctx.debug`/`ctx.random`/`ctx.game`/`ctx.roots`, and `ctx.input` (the
-            // game-owned InputManager, with this world's virtual-input/actions/trace
-            // debug seams registered and the project's input map loaded). The
-            // subsystems an R3F world genuinely does not build (Rapier, composer,
-            // audio, particles, debugDraw) are absent from that TYPE, so reaching
-            // for one is a compile error rather than anything that can happen at
-            // runtime. `scene`/`camera` are backfilled right after fiber's first
-            // commit resolves them, before any tick can run.
-            const runtime = engineRuntime ? createR3FRootContext(host, { id, inputMapPath }) : null;
-            // `ctx` rides the bridge so ordinary components can reach engine
-            // services through `useGameContext()`.
-            const bridge = runtime ? { ctx: runtime.ctx } : null;
-            const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
-            // THE HOST STILL WIRES THIS GAME'S INPUT WHEN THE WORLD TAKES NO CONTEXT.
-            //
-            // A default-exported world mounts with `engineRuntime: false` — no vgai
-            // runtime context enters its React tree, by design. That says nothing
-            // about the GAME-scoped input the host owns from the outside: the
-            // project's declared map, and this root's `game.input.*` seams on the
-            // debug registry. Skipping those made a fresh scaffold's bot/autoplay/
-            // `vgai eval` input doors throw `DEBUG_INPUT_UNAVAILABLE` and left the
-            // declared actions unloaded — in the ONE world shape `vgai create`
-            // produces. Same host-vs-context split as `WorldProvider` below.
-            //
-            // `inputMapPath` unset (what the default-export factory passes) means
-            // "the conventional path, if this project ships one" — quiet when it
-            // does not, since a brand-new project declares no actions yet.
-            const hostInputReady = runtime || !gameDebugRegistry
-                ? null
-                : wireGameInputSeams(host, gameDebugRegistry, {
-                    id,
-                    inputMapPath: inputMapPath ?? DEFAULT_INPUT_MAP_PATH,
-                    optionalInputMap: inputMapPath === undefined,
-                });
-            // Actions must exist before any component's init()/first frame reads
-            // them — wait for the (never-rejecting) input-map load before the first
-            // commit.
-            await (runtime?.inputMapReady ?? hostInputReady);
-            // The world's own colour pipeline. Applied AFTER `root.configure()` below — see the comment
-            // at its call site for why "before" is the version that silently does nothing.
-            let restoreRendererConfig = () => { };
-            const canvas = host.surface.canvas;
-            const root = createRoot(canvas);
-            // `RootState` (the live scene/camera/gl fiber built) only arrives via
-            // the `onCreated` callback — `root.render()`'s return value is
-            // TECHNICALLY the same store, but `onCreated` is the hook the design
-            // doc's §1.C sketch names, and waiting for it (rather than assuming
-            // the first commit already ran synchronously) is the honest choice
-            // under React 19's concurrent renderer, which does not guarantee a
-            // synchronous first commit the way legacy ReactDOM.render did.
-            let resolveState;
-            const statePromise = new Promise((resolve) => {
-                resolveState = resolve;
-            });
-            let resolveEffectsReady;
-            const effectsReady = new Promise((resolve) => {
-                resolveEffectsReady = resolve;
-            });
-            // Rendered after the game's content. React runs passive effects in tree
-            // order, so when this fires every useDebugProvider/useDebugCommand in
-            // the initial tree has registered. A Play acknowledgement is a claim
-            // that the mounted game's command surface exists, not merely that Fiber
-            // allocated a scene.
-            function MountEffectsReady() {
-                useEffect(resolveEffectsReady, []);
-                return null;
-            }
-            // `root.configure()` is ASYNC in fiber v9 (`Promise<ReconcilerRoot>`)
-            // — the design doc's §1.C sketch shows it called synchronously; the
-            // real v9 API (verified against
-            // `node_modules/@react-three/fiber/dist/declarations/src/core/index.d.ts`)
-            // requires awaiting it before `render()`.
-            await root.configure({
-                // The engine's renderer, not a second one (design §1.C) — fiber
-                // renders THROUGH `host.renderer` instead of constructing its own
-                // `WebGLRenderer`.
-                gl: host.renderer,
-                // …and the host's shadow map, not fiber's.
-                //
-                // `configure()` runs `gl.shadowMap.enabled = !!shadows`
-                // UNCONDITIONALLY, against its own default of `false`. Passing nothing
-                // therefore does not mean "leave it alone" — it means "turn shadows
-                // off on the renderer the host just configured". Every three root
-                // silently did that (FX-5): `applyRendererSettings` sets
-                // `shadowMap.enabled` from the `shadows` render feature, which
-                // defaults ON, and the setting had no surviving reader on this path —
-                // so `castShadow`/`receiveShadow` all over a world produced nothing
-                // and the scene read flat, with no error anywhere.
-                //
-                // Reading it back off the renderer is exactly "don't clobber": a
-                // boolean also pins `shadowMap.type` to `PCFSoftShadowMap`, which is
-                // what `createHostRenderer` already sets, so the round trip is
-                // lossless and the HOST stays the one deciding.
-                //
-                // Optional-chained even though `WebGLRenderer.shadowMap` is not
-                // optional: a headless/stub host renderer is a real shape in this
-                // repo's tests, and fiber's own `if (gl.shadowMap)` guard means the
-                // value it reads there is ignored anyway.
-                shadows: host.renderer.shadowMap?.enabled ?? false,
-                // The engine's gated loop is the ONLY loop — fiber must never run
-                // its own rAF (that would defeat editor pause; design §1.C's
-                // `drivesOwnLoop: false` contract, guide §2's loop-model note).
-                frameloop: 'never',
-                // `RenderProps.size` types as the FULL `Size` (width/height/top/left),
-                // not `Partial<Size>` — the design sketch's `{ width, height }` alone
-                // does not satisfy fiber v9's real type, so `top`/`left` are pinned
-                // to 0 (this bridge always fills its whole canvas; no offset
-                // viewport in v1).
-                size: { width: host.surface.width, height: host.surface.height, top: 0, left: 0 },
-                // Fiber's pointer-event manager, passed EXPLICITLY.
-                //
-                // This comment used to say `events` was "deliberately left at fiber's
-                // default (binds to `gl.domElement`)". That was false, and it cost
-                // every R3F world in this engine its mesh-level pointer props —
-                // `onClick`, `onPointerOver`, `onPointerMissed` were dead everywhere.
-                // There IS no default for a bare `createRoot`: the
-                // `events = createPointerEvents` default lives in the `<Canvas>`
-                // COMPONENT, which this bridge does not use, and `configure` gates on
-                // `if (events && !state.events.handlers)`. With `events` undefined the
-                // store kept its initial `{ priority, enabled, connected: false }` —
-                // no handlers, nothing bound to the canvas, no error.
-                //
-                // Found by the WO-P6 builder, whose control experiment isolated the
-                // variable properly: the same stub renderer, the same
-                // `frameloop: 'never'`, the same jsdom canvas and pointer sequence,
-                // differing ONLY in passing `events` — and `onClick` fired. Fiber is
-                // fine under a host-driven loop; we omitted one property.
-                //
-                // (Design O1's open question about a delegating multi-canvas input
-                // router still only matters for a shell+net composite; this bridge is
-                // the single-canvas world O1 says is unaffected.)
-                events: pointerEvents,
-                onCreated: (state) => resolveState(state),
-            });
-            // THE WORLD'S OWN COLOUR PIPELINE — and it must land HERE, after `configure()`.
-            //
-            // `configure()` writes `outputColorSpace` and `toneMapping` onto the renderer
-            // UNCONDITIONALLY, from its own `linear`/`flat` props whose defaults are `false`/`false` —
-            // i.e. sRGB output and ACES. That is the SAME trap as the `shadows` note above, and it is
-            // silent: applying a world's config before `configure()` leaves every field set and every
-            // pixel unchanged (measured on the squash-the-creeps Godot port — the ground stayed at byte
-            // 138 with `toneMapping: 'none'` declared and applied).
-            //
-            // Applying it here is still before any frame: `advance()` only runs from `update()` below,
-            // and `render()` on the next line merely reconciles.
-            if (rendererConfig !== undefined) {
-                restoreRendererConfig = applyWorldRendererConfig(host.three, host.renderer, rendererConfig);
-            }
-            // No `<StrictMode>` (design §1.C: "no StrictMode: host mounts once")
-            // — this bridge mounts exactly once per `mount()` call; StrictMode's
-            // deliberate double-invoke of effects would double-subscribe
-            // `useFrame` callbacks against a host loop that only ticks once per
-            // frame. The `EngineBridge` provider threads the component runtime
-            // (above) into the tree (W3), where `useGameContext()` reads it.
-            // R3F IS React, so the React seam every dom root already has —
-            // `useWorldState`, `useDebugProvider`/`useDebugCommand`/`useDebugEmit`
-            // (`../react/world-state`) — should work identically inside a three root.
-            // Without this provider a behavior-as-a-hook could only reach the debug
-            // registry by destructuring `useGameContext()` and calling
-            // `debug?.registerStateProvider(...)` by hand, which has no unmount
-            // story: the template's follow-camera hook leaked a provider per remount
-            // until this landed. `host.game` is genuinely absent in bare/headless
-            // hosts, so the provider is conditional and those hooks stay the inert
-            // no-ops they already document themselves to be.
-            //
-            // READ FROM `host.game`, NEVER FROM `runtime` — the two are not the same
-            // question, and conflating them silently dark-ended the seam for every
-            // scaffolded game. The IDIOMATIC three world (`export default function
-            // World()`) mounts through `resolveR3FEntryAdapter` with
-            // `engineRuntime: false` (`r3f-root-factory.tsx`), so it has no
-            // `runtime` and no `bridge` — by design, because the vgai runtime
-            // CONTEXT (`useGameContext`) must not enter an ecosystem-native tree.
-            // `WorldProvider` is not that context: it carries the Game handle the
-            // host already holds, and it is the only way a game's own
-            // `useDebugProvider('stat', …)` can reach the ONE game-scoped registry
-            // the editor/`vgai eval` read. Keyed off `runtime`, every
-            // default-exported world's registrations no-opped in silence and
-            // `vgai eval 'await game.providers()'` listed only the built-ins.
-            // The canvas lane never had the gap (`canvas-react/
-            // pixi-react-root-factory.tsx` keeps its entry runtime on).
-            const game = host.game;
-            // `SoftParticleDepth` trails the world's own tree deliberately — see its
-            // docblock for why the subscription must land last. A no-context design
-            // mount omits this fiber callback because the adopting editor viewport
-            // runs the pass with its own renderer and camera instead.
-            const world = createElement(Fragment, null, content, runtime && typeof host.renderer.getContext === 'function'
-                ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' })
-                : null, createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }));
-            // The two providers are INDEPENDENT: `EngineBridge` rides `bridge` (the
-            // vgai runtime context, absent for a native default-exported world),
-            // `WorldProvider` rides `host.game` (the React seam, present whenever a
-            // Game hosts this world). Nesting the second inside the first is what
-            // made the seam a hostage of the first.
-            const provided = game ? createElement(WorldProvider, { game }, world) : world;
-            root.render(bridge ? createElement(EngineBridge.Provider, { value: bridge }, provided) : provided);
-            // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
-            // surfaces as an uncaught window error and `onCreated` never fires —
-            // without this guard, `mount()` would await `statePromise` FOREVER and
-            // silently wedge every world declared after this one (roots mount
-            // sequentially). Convert that class of failure into a loud mount error.
-            const state = await new Promise((resolve, reject) => {
-                const onError = (event) => {
-                    cleanup();
-                    root.unmount();
-                    runtime?.dispose();
-                    if (!runtime)
-                        gameDebugRegistry?.strip(id);
-                    restoreRendererConfig();
-                    reject(new Error(`r3f-adapter: fiber crashed before its first commit — ${event.message} ` +
-                        '(mount() fails loudly instead of hanging on onCreated)'));
-                };
-                const timer = setTimeout(() => {
-                    cleanup();
-                    root.unmount();
-                    runtime?.dispose();
-                    if (!runtime)
-                        gameDebugRegistry?.strip(id);
-                    restoreRendererConfig();
-                    reject(new Error('r3f-adapter: onCreated did not fire within 10s — the R3F tree never reached ' +
-                        'its first commit (mount() fails loudly instead of hanging)'));
-                }, 10_000);
-                const cleanup = () => {
-                    clearTimeout(timer);
-                    window.removeEventListener('error', onError);
-                };
-                window.addEventListener('error', onError);
-                void Promise.all([statePromise, effectsReady]).then(([s]) => {
-                    cleanup();
-                    resolve(s);
-                });
-            });
-            // Clock hardening (field-proven by the first external adopter,
-            // alien-stories' proto): fiber's internal `update()` calls
-            // `state.clock.getDelta()` BEFORE its `frameloop:'never'` branch, and a
-            // RUNNING (or autoStart) `THREE.Clock` accumulates WALL time into
-            // `elapsedTime` as a side effect — skewing the deltas the 'never'
-            // branch derives from the game timestamps `update(dt)` feeds below.
-            // Stopped + autoStart=false makes `getDelta()` a pure no-op, so
-            // `useFrame` deltas come from game time alone.
-            state.clock.autoStart = false;
-            state.clock.stop();
-            // Backfill the component runtime's ctx with fiber's real scene/camera
-            // (W3 — see the HONESTY NOTE above). This happens before the first
-            // `update(dt)` tick, so no component ever observes them missing.
-            runtime?.setSceneCamera(state.scene, state.camera);
-            // THE STORE IS THE TRUTH, NOT THE `onCreated` SNAPSHOT.
-            //
-            // `state` is one immutable zustand snapshot: fiber's store is
-            // `create<RootState>()`, and every `set(...)` produces a NEW state
-            // object rather than mutating this one. So a world that legitimately
-            // REPLACES the default camera — `useThree(s => s.set)({ camera })`,
-            // which is exactly what drei's `makeDefault` does — never reaches
-            // anything read off `state` directly.
-            //
-            // That is not cosmetic: fiber's own `update()` renders
-            // `state.gl.render(state.scene, state.camera)` off the state object it
-            // is HANDED, so `advance(t, true, state)` below pinned the render
-            // camera to fiber's default `PerspectiveCamera` at (0, 0, 5) forever.
-            // Measured on the squash-the-creeps Godot port (WO-G14): the world set
-            // its authored `OrthographicCamera` and the frame still rendered from
-            // (0, 0, 5) — a point INSIDE that game's 60x2x60 ground box, so every
-            // ground polygon was back-facing, was culled, and the "ground" was the
-            // cleared canvas. Nothing anywhere reported an error; edit mode looked
-            // right because the editor renders with its own camera.
-            //
-            // `state.get()` is fiber's own `StoreApi.getState`, carried on
-            // `RootState` for precisely this reason, so reading it per frame is the
-            // supported way to see the live root. It is a plain map read.
-            const live = () => state.get();
-            // --- Live render vitals (issue #1504), for an R3F world -----------------
-            // The SAME door the classic adapter seeds
-            // (`../adapter/setup-three-root-adapter.ts`), seeded here for the same
-            // reason: a running game must be able to explain its own frame cost
-            // through the debug registry, with no capability to install and nothing
-            // for a game to write. It has to be seeded in BOTH adapters because they
-            // are two independent mount paths onto the same `Game` — and a TSX/R3F
-            // world is the only shape a scaffolded project's three root has, so a
-            // door wired only into the classic path is a door no scaffolded project
-            // ever gets (issue #1518: `game.state('render.vitals')` answered "no
-            // state provider registered" in the field while every other debug
-            // reading of the same world worked).
-            //
-            // The gate is the same three conditions, minus the one that cannot
-            // arise: `devBuildEnabled()` (`../runtime/dev-build.ts`, the ONE owner
-            // of "is this a dev context" — a ship build registers nothing and pays
-            // nothing), and a `Game` shell (the readings are folded out of that
-            // game's profiler frames). "Not headless" needs no term here: a headless
-            // mount returned above, before fiber was ever configured.
-            //
-            // Two module instances, one answer: under the packaged editor this
-            // module is served out of the PROJECT's own Vite graph (see
-            // `packages/editor/vite-plugin-react-world-runtime.ts` — the packaged
-            // shell imports `resolveR3FEntryAdapter` through the project-rooted
-            // server precisely so fiber/react/three identity is the project's), so
-            // `import.meta.env.DEV` here is the project server's `true`, not the
-            // prebuilt shell's `false`.
-            //
-            // OWNER of the registration+fold: this mount, ended by `dispose()` below
-            // (the fold) and `runtime.dispose()`'s scoped `strip(id)` (the
-            // registrations) — the same split the classic adapter documents.
-            let renderVitals = null;
-            if (host.game && devBuildEnabled()) {
-                // Same auto-enable as the classic adapter: the readings are folded out
-                // of profiler frames, and the profiler is a flag the editor already
-                // sets on play — under the dev gate this is the same cost arriving a
-                // little earlier, not a new one.
-                host.game.profiler.enabled = true;
-                if (!gameDebugRegistry) {
-                    throw new Error('r3f-adapter: mounted Game has no debug registry.');
-                }
-                renderVitals = registerRenderVitals({
-                    registry: gameDebugRegistry,
-                    worldId: id,
-                    profiler: host.game.profiler,
-                    scene: live().scene,
-                    renderer: host.renderer,
-                });
-            }
-            // Engine-owned render introspection, built over the SAME renderer and
-            // scene Fiber uses. A design-time stand-in has no context and a
-            // headless mount returned above, so both honestly omit the capability.
-            // `frameCaptureContextFor` is the same construction gate as the classic
-            // Three adapter; no editor-side renderer inference is involved.
-            const rendererContext = typeof host.renderer.getContext === 'function' ? host.renderer.getContext() : undefined;
-            const frameCaptureContext = frameCaptureContextFor(false, rendererContext);
-            const frameCapture = frameCaptureContext
-                ? createWebGLFrameCapture(frameCaptureContext)
-                : null;
-            const renderDebugWiring = frameCapture
-                ? createRenderDebugAdapter({
-                    capture: frameCapture,
-                    scene: state.scene,
-                    memory: () => collectRenderMemory(live().scene, host.renderer.info),
-                })
-                : null;
-            // The session debug registry is host instrumentation, not component
-            // context. Publishing the existing adapter here lets coverage and
-            // editor panels see the same door without wrapping the R3F tree.
-            const systemAdapters = runtime?.systemAdapters ?? (gameDebugRegistry ? { debug: gameDebugRegistry.adapter } : {});
-            if (renderDebugWiring)
-                systemAdapters.renderDebug = renderDebugWiring.adapter;
-            // The engine drives every `useFrame` through the mounted world's
-            // `update(dt)` hook, never off a raw host-loop callback. That is the
-            // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
-            // `mounted.update?.(dt)` per substep for a host-driven
-            // (`drivesOwnLoop: false`) world and SKIPS it while that world is
-            // frozen, and `Game.play.step()` ticks it exactly once — whereas any
-            // callback run outside `game.runFrame`'s gate would fire
-            // unconditionally, pause or not. Advancing fiber from such a callback
-            // LOOKS right and silently breaks acceptance gate 2 — proven by the
-            // 36-r3f-first-party e2e, whose paused instance-matrix samples kept
-            // moving until this moved to `update`. (The former `ThreeHostContext.loop`
-            // seam that made the wrong path reachable was deleted, zero consumers.)
-            //
-            // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
-            // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
-            // `frameloop:'never'` (verified against fiber's `update()`
-            // implementation, not just its `.d.ts` — the declared signature alone
-            // doesn't say this): `delta = timestamp - clock.elapsedTime;
-            // clock.elapsedTime = timestamp`. So `timestamp` must be a
-            // monotonically increasing SECONDS value — GAME time, not wall time:
-            // `update` simply isn't called while this world is frozen, so
-            // accumulating its `dt` (seconds; the loop runs a fixed 1/60 timestep)
-            // means fiber's clock does not advance across a pause. Wall clock
-            // (`performance.now()`) would leak the pause duration into the first
-            // resumed frame as one giant `useFrame` delta — the exact "time passed
-            // while frozen" illusion acceptance gate 2 forbids.
-            let elapsed = 0;
-            /** The legacy component ctx camera last backfilled by `update()`. */
-            let backfilledCamera = state.camera;
-            return {
-                kind: 'three',
-                // Fiber's REAL `THREE.Scene`/`THREE.Camera`. Checkout development
-                // dedupes `three`; a registry-installed project and the prebundled
-                // editor can legitimately have distinct constructor identities, so
-                // editor boundaries recognize Three's stable structural brands
-                // (`isScene`, `isCamera`) rather than relying only on `instanceof`.
-                // `state.camera`'s type (`Camera = (OrthographicCamera |
-                // PerspectiveCamera) & { manual?: boolean }`) is a structural subtype
-                // of `THREE.Camera`, so no cast is needed.
-                //
-                // Both are GETTERS over the live store, not snapshot fields: the host
-                // and the editor must see the camera the world actually renders
-                // through, including one the world swapped in after the first commit
-                // (see `live` above).
-                get scene() {
-                    return live().scene;
-                },
-                get camera() {
-                    return live().camera;
-                },
-                drivesOwnLoop: false,
-                // REPORTED for a host that draws this scene with a renderer other than
-                // the one it mounted us against — see `MountedThreeRoot.rendererConfig`.
-                // It is the same object already applied to `host.renderer` above; the
-                // report never applies anything itself.
-                rendererConfig: rendererConfig,
-                // Adapter surface: `debug` (the shared game registry) and, when a real
-                // WebGL2 context exists, `renderDebug` are engine-seeded. Game code
-                // adds its own capabilities via `ctx.registerSystemAdapter` exactly
-                // as in a classic world.
-                systems: systemAdapters,
-                update(dt) {
-                    elapsed += dt;
-                    const current = live();
-                    // A world that swapped the default camera gets it onto `ctx` too —
-                    // `ctx.camera` and the rendered camera are the same fact, and a
-                    // component reading one while the frame uses the other is the
-                    // silent kind of wrong. Identity-gated, so this is one comparison
-                    // per frame in the overwhelmingly common no-swap case.
-                    if (runtime && current.camera !== backfilledCamera) {
-                        backfilledCamera = current.camera;
-                        runtime.setSceneCamera(current.scene, current.camera);
-                    }
-                    // Engine phases FIRST (registered systems mutate transforms),
-                    // then fiber's advance (useFrame callbacks + the actual render see
-                    // the fresh state). Both are host-gated: neither runs while frozen.
-                    runtime?.systems.run(dt);
-                    renderDebugWiring?.beforeRender();
-                    try {
-                        const profiler = host.game?.profiler;
-                        if (!profiler?.enabled) {
-                            advance(elapsed, true, current);
-                            return;
-                        }
-                        // Issue #1504's measurement, produced where the draw actually
-                        // happens. `advance()` under `frameloop: 'never'` is what calls
-                        // `gl.render(scene, camera)`, so this bracket — not a phase span
-                        // inside `systems` — is the frame's CPU submission cost, and it is
-                        // also what makes this frame a PRESENTATION as far as the vitals
-                        // fold is concerned (`../dev/render-vitals.ts`: no bracket, no
-                        // display frame). The profiler's phase clock is a stack, so
-                        // bracketing here cannot truncate an enclosing phase.
-                        const info = host.renderer.info;
-                        const passesBefore = info?.render.frame ?? 0;
-                        profiler.beginPhase();
-                        try {
-                            advance(elapsed, true, current);
-                        }
-                        finally {
-                            profiler.endPhase(RENDER_SUBMIT_PHASE);
-                        }
-                        // Checked, not assumed — a duck-typed/design-time renderer supplies
-                        // only what a mount needs, and a mount with no counters must report
-                        // NOTHING rather than throw once per frame (the classic adapter's
-                        // `postFrame` pays for the same assumption for the same reason).
-                        // `gpuMs` is null: this path runs no GPU timer, and the profiler
-                        // keeps the previous reading rather than inventing a zero.
-                        if (info) {
-                            profiler.reportRender({
-                                gpuMs: null,
-                                drawCalls: info.render.calls,
-                                triangles: info.render.triangles,
-                                geometries: info.memory.geometries,
-                                textures: info.memory.textures,
-                                renderPasses: info.render.frame - passesBefore,
-                            });
-                        }
-                    }
-                    finally {
-                        renderDebugWiring?.afterRender();
-                    }
-                },
-                resize(width, height) {
-                    live().setSize(width, height);
-                },
-                dispose() {
-                    // Reject/restore a pending capture while its renderables still
-                    // exist, then unmount component effects and strip runtime state.
-                    renderDebugWiring?.dispose();
-                    // The editor audits and disposes the mounted game's window/document realm immediately
-                    // after `session.stop()`. Fiber's ordinary `unmount()` submits a concurrent reconciler
-                    // update, so component effect cleanups could still be pending at that boundary and the
-                    // audit would truthfully report/reclaim listeners the world was about to remove itself.
-                    // Force the unmount COMMIT (not fiber's deliberately delayed renderer/context disposal)
-                    // to finish here: a stopped root owns no live component lifecycle beyond this method.
-                    flushSync(() => root.unmount());
-                    // The vitals fold owns two `profiler.subscribe` registrations, and
-                    // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —
-                    // this is the one path that ends the subscriptions, exactly as the
-                    // classic adapter's teardown documents. Before the strip, so a
-                    // subscription can never outlive the door it feeds.
-                    renderVitals?.dispose();
-                    renderVitals = null;
-                    runtime?.dispose();
-                    // The no-context path has no `runtime.dispose()` to carry its scoped
-                    // strip, so it ends its own registrations here — the same
-                    // `strip(id)`, at the same moment. That is what ends this world's
-                    // PROVIDERS AND COMMANDS (the render-vitals door above is the one
-                    // this path actually registers under `id`); sibling roots are
-                    // untouched.
-                    //
-                    // It does NOT end the input seams `wireGameInputSeams` set, and
-                    // nothing else does either: `strip` walks providers/commands only
-                    // (`runtime/debug-registry.ts`), so `virtualInputTargets`/
-                    // `inputActionsSources`/`inputTraceSources` keep this world's id
-                    // until a remount of the same id overwrites it. The runtime path has
-                    // always been identical, and the residue is inert rather than
-                    // hidden: every one of those closures reads GAME-scoped state
-                    // (`game.input`, `game.loop.fixedDt`, the game's seed), so a stale
-                    // entry actuates exactly what a live one would. What it can still do
-                    // is name a dead world in `DEBUG_INPUT_WORLD_NOT_FOUND`'s registered
-                    // list. Do not write "the strip clears the input seams" here again
-                    // without changing `strip` to actually do it.
-                    if (!runtime)
-                        gameDebugRegistry?.strip(id);
-                    restoreRendererConfig();
-                },
-            };
-        },
-    };
-}