@vgai/engine 0.5.21 → 0.5.23

package/src/world3d-react/r3f-adapter.tsx

@@ -1,717 +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,
-  type RootState,
-  useFrame,
-} from '@react-three/fiber';
-import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
-import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
-import { applyWorldRendererConfig, type WorldRendererConfig } from '../adapter/renderer-config';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
-import {
-  createRenderDebugAdapter,
-  frameCaptureContextFor,
-  type RenderDebugWiring,
-} 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, type EngineBridgeValue } from './engine-bridge';
-import { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from './world-context';
-
-/** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
- *  structurally rather than imported from `three`, per this module's own
- *  identity rule (see the header): a duck-typed host renderer legitimately has
- *  no `info` at all, which is why every read of it is guarded. */
-interface RendererCounters {
-  readonly render: { readonly calls: number; readonly triangles: number; readonly frame: number };
-  readonly memory: { readonly geometries: number; readonly textures: number };
-}
-
-/**
- * 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(): null {
-  const pass = useMemo(() => createSoftParticleDepthPass(), []);
-  useEffect(() => () => pass.dispose(), [pass]);
-  useFrame(({ gl, scene, camera }) => pass.render(gl, scene, camera), 0);
-  return null;
-}
-
-/** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
-export interface CreateR3FAdapterOptions {
-  /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
-  readonly id: string;
-  /** The R3F scene tree to mount — drei helpers, `useFrame` hooks, etc. all
-   *  work unchanged (design §1.C: "drei works unchanged (it is fiber-context
-   *  userland)"). */
-  readonly content: ReactNode;
-  /** Input map loaded through the game-owned `Game.loadInputMap` (load-once
-   *  across roots). Defaults to the classic adapter's conventional path,
-   *  `/inputmaps/default.inputmap.json`; `null` opts out (a world with no
-   *  actions). A missing/invalid map degrades loudly without failing the
-   *  mount — see `world-context.ts`. */
-  readonly inputMapPath?: string | null | undefined;
-  /**
-   * Transitional compatibility for explicit pre-native adapters. The
-   * default-export root factory always passes `false`: ordinary R3F trees get
-   * no vgai context/provider or private scheduler. Remove this switch with
-   * the last explicit legacy adapter migration.
-   */
-  readonly engineRuntime?: boolean | undefined;
-  /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
-   *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
-   *  defaults; declare it when the world's colours were picked against a different engine's
-   *  pipeline — see `../adapter/renderer-config.ts`. */
-  readonly renderer?: WorldRendererConfig | undefined;
-}
-
-/**
- * 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: CreateR3FAdapterOptions): RootAdapter {
-  const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
-
-  return {
-    id,
-
-    async mount(host: ThreeHostContext): Promise<MountedThreeRoot> {
-      // 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(): void {
-            /* 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 as unknown as Parameters<typeof extend>[0]);
-
-      // 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: EngineBridgeValue | null = 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: () => void = () => {};
-
-      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!: (state: RootState) => void;
-      const statePromise = new Promise<RootState>((resolve) => {
-        resolveState = resolve;
-      });
-      let resolveEffectsReady!: () => void;
-      const effectsReady = new Promise<void>((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(): null {
-        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<RootState>((resolve, reject) => {
-        const onError = (event: ErrorEvent) => {
-          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 = (): RootState => 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: RenderVitalsRegistration | null = 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: RenderDebugWiring | null = 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: 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: number): void {
-          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 as RendererCounters | undefined;
-            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: number, height: number): void {
-          live().setSize(width, height);
-        },
-        dispose(): void {
-          // 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();
-        },
-      };
-    },
-  };
-}