@vgai/engine 0.5.21 → 0.5.23

package/dist/world3d-react/r3f-root-factory.js

@@ -1,8 +1,6 @@
 /**
  * `r3fRootFactory` — mount a `three` root whose entry module DEFAULT-EXPORTS a
- * React component.
- *
- * The idiomatic-shape fix (D26). A model asked for an R3F world writes:
+ * React component. This is the ONE first-party three mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,84 +8,432 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createR3FAdapter({ id, content })`.
- * That export is pure vgai ceremony wrapped around a component the author
- * already wrote, and it is the second-largest non-idiomatic thing left in a
- * world file (the largest is the missing `<Canvas>`, which is a separate
- * question about who owns the canvas — see D26).
- *
- * The `dom` root already settled this convention: its factory reads
- * `entryModule.default` and wraps it. This is the same contract for three
- * roots, so both surfaces answer "what do I export?" the same way.
+ * The world is an ordinary R3F app. Everything vgai-shaped stays at the entry
+ * module's STATIC surface (`export { debug, systems } from './commands'`) and
+ * on the host's side of the seam; no vgai runtime context ever enters the
+ * React tree. The host controls Fiber's `frameloop: 'never'` scheduler, wires
+ * the game-scoped input seams from outside (`../runtime/game-input-seams.ts`),
+ * and installs `WorldProvider` off the Game handle so the lib-legal react
+ * doors (`useWorldState`, `useOptionalGame`, `useDebugProvider`) resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
- * `defaultThreeAdapterFactory` lives beside the registry, and the registry
- * module is deliberately dependency-free: its own doc notes threejs is safe to
- * ship there because `three` is already an unconditional engine dependency.
- * `@react-three/fiber` is NOT — it is the PROJECT's dependency, and
- * `world3d-react` is the opt-in module that owns it. Putting this factory
- * there would make R3F unconditional for every game, including ones with no
- * React at all.
+ * The adapter registry module is deliberately dependency-free beyond `three`
+ * (already an unconditional engine dependency). `@react-three/fiber` is NOT —
+ * it is the PROJECT's dependency, and `world3d-react` is the opt-in module
+ * that owns it. Putting this factory beside the registry would make R3F
+ * unconditional for every game, including ones with no React at all; instead
+ * each project's `main.ts` registers it (`registerAdapter('three',
+ * r3fRootFactory)`).
  *
- * ## Compatibility
+ * ## The mount mechanics (fiber v9, host-gated)
  *
- * An `adapter` export still wins, so existing worlds are untouched and a game
- * needing full control over its own `RootAdapter` keeps it.
+ * 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']`.
  */
-import { createElement } from 'react';
-import { createR3FAdapter } from './r3f-adapter';
+import { advance, createRoot, extend, flushSync, events as pointerEvents, } from '@react-three/fiber';
+import { createElement, Fragment, useEffect } from 'react';
+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 { getDebugRegistry } from '../runtime/debug-registry';
+import { devBuildEnabled } from '../runtime/dev-build';
+import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
+/**
+ * Build the `RootAdapter` for one default-exported R3F world. Mounts 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.
+ */
+function threeWorldAdapter(id, component) {
+    const content = createElement(component);
+    return {
+        id,
+        async mount(host) {
+            // Headless honesty — every `mount()` must work headless: the conformance
+            // kit 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.
+            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 HOST WIRES THIS GAME'S INPUT FROM OUTSIDE THE TREE: 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. The conventional path is optional — quiet
+            // when the project ships no map, since a brand-new project declares no
+            // actions yet. Actions must exist before any component's first frame
+            // reads them — wait for the (never-rejecting) load before the first
+            // commit.
+            const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
+            if (gameDebugRegistry) {
+                await wireGameInputSeams(host, gameDebugRegistry, {
+                    id,
+                    inputMapPath: DEFAULT_INPUT_MAP_PATH,
+                    optionalInputMap: true,
+                });
+            }
+            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 supported hook, 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 provider/command effect 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>`) —
+            // it must be awaited before `render()`.
+            await root.configure({
+                // The engine's renderer, not a second one — 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" (FX-5: every three
+                // root silently 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; `drivesOwnLoop: false`).
+                frameloop: 'never',
+                // `RenderProps.size` types as the FULL `Size` (width/height/top/left),
+                // so `top`/`left` are pinned to 0 (this bridge always fills its whole
+                // canvas; no offset viewport).
+                size: { width: host.surface.width, height: host.surface.height, top: 0, left: 0 },
+                // Fiber's pointer-event manager, passed EXPLICITLY. There IS no
+                // default for a bare `createRoot`: the `events = createPointerEvents`
+                // default lives in the `<Canvas>` COMPONENT, which this mount does not
+                // use, and `configure` gates on `if (events && !state.events.handlers)`.
+                // With `events` undefined the store keeps its initial
+                // `{ priority, enabled, connected: false }` — no handlers, nothing
+                // bound to the canvas, no error — and every mesh-level pointer prop
+                // (`onClick`, `onPointerOver`, `onPointerMissed`) is dead. Proven by a
+                // control experiment differing ONLY in this property.
+                events: pointerEvents,
+                onCreated: (state) => resolveState(state),
+            });
+            // No `<StrictMode>` — the host mounts once; StrictMode's deliberate
+            // double-invoke of effects would double-subscribe `useFrame` callbacks
+            // against a host loop that only ticks once per frame.
+            //
+            // `WorldProvider` rides `host.game` — the React seam every dom root
+            // already has (`useWorldState`, `useOptionalGame`, `useDebugProvider` in
+            // lib code), and the only way a capability hook can reach the ONE
+            // game-scoped registry the editor/`vgai eval` read. `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.
+            const game = host.game;
+            const world = createElement(Fragment, null, content, createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }));
+            const provided = game ? createElement(WorldProvider, { game }, world) : world;
+            root.render(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();
+                    gameDebugRegistry?.strip(id);
+                    reject(new Error(`three world "${id}": fiber crashed before its first commit — ${event.message} ` +
+                        '(mount() fails loudly instead of hanging on onCreated)'));
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    root.unmount();
+                    gameDebugRegistry?.strip(id);
+                    reject(new Error(`three world "${id}": 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: 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();
+            // THE STORE IS THE TRUTH, NOT THE `onCreated` SNAPSHOT.
+            //
+            // `state` is one immutable zustand snapshot: every `set(...)` produces a
+            // NEW state object. 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, and fiber's own `update()` renders
+            // `state.gl.render(state.scene, state.camera)` off the state object it
+            // is HANDED. Measured: an authored `OrthographicCamera` world rendered
+            // from fiber's default (0, 0, 5) forever, culling every ground polygon.
+            // `state.get()` is fiber's own `StoreApi.getState`, carried on
+            // `RootState` for precisely this reason; it is a plain map read.
+            const live = () => state.get();
+            // --- Live render vitals, host-seeded ---------------------------------
+            // 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. Gate: `devBuildEnabled()` (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.
+            let renderVitals = null;
+            if (host.game && devBuildEnabled()) {
+                // 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(`three world "${id}": 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.
+            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. The
+            // world's own declared systems merge in from the entry module at the
+            // Game layer (`installDeclaredSystemAdapters`).
+            const 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 world and SKIPS
+            // it while that world is frozen, and `Game.play.step()` ticks it exactly
+            // once.
+            //
+            // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
+            // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
+            // `frameloop:'never'` (verified against fiber's `update()`
+            // implementation): `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` means fiber's clock does not advance across a
+            // pause. Wall clock would leak the pause duration into the first
+            // resumed frame as one giant `useFrame` delta.
+            let elapsed = 0;
+            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`.
+                //
+                // 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,
+                // Adapter surface: `debug` (the shared game registry) and, when a real
+                // WebGL2 context exists, `renderDebug` are engine-seeded. The game's
+                // own capabilities arrive as the entry module's declared `systems`.
+                systems: systemAdapters,
+                update(dt) {
+                    elapsed += dt;
+                    const current = live();
+                    renderDebugWiring?.beforeRender();
+                    try {
+                        const profiler = host.game?.profiler;
+                        if (!profiler?.enabled) {
+                            advance(elapsed, true, current);
+                            return;
+                        }
+                        // The frame's CPU submission cost, produced where the draw
+                        // actually happens: `advance()` under `frameloop: 'never'` is what
+                        // calls `gl.render(scene, camera)`, and this bracket 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. `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 this world's
+                    // registrations.
+                    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 —
+                    // ended here, before the strip, so a subscription can never outlive
+                    // the door it feeds.
+                    renderVitals?.dispose();
+                    renderVitals = null;
+                    // `strip(id)` ends this world's PROVIDERS AND COMMANDS (the
+                    // render-vitals door above is the one this mount registers under
+                    // `id`); sibling roots are untouched. It does NOT end the input
+                    // seams `wireGameInputSeams` set — see that module's LIFETIME note.
+                    gameDebugRegistry?.strip(id);
+                },
+            };
+        },
+    };
+}
 /**
  * What a three entry module MEANS, in one place.
  *
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link r3fRootFactory}, below) and the EDITOR's design session
  * (`packages/editor/src/authoring/r3f-design-session.ts`), which design-mounts
- * the same entry so edit mode authors the live fiber scene. When only the
- * runtime knew about the default-export shape, the converted starter played
- * fine under `npm run game` and edit mode showed "(no scene loaded)".
+ * the same entry so edit mode authors the live fiber scene.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws, the design session declines the world
- * and leaves existing paths alone).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws, the design
+ * session declines the world and leaves existing paths alone).
  */
 export function resolveR3FEntryAdapter(entryModule, rootId) {
     const mod = entryModule;
-    if (mod?.adapter)
-        return mod.adapter;
-    if (typeof mod?.default === 'function') {
-        return createR3FAdapter({
-            id: rootId,
-            content: createElement(mod.default),
-            // A default-exported R3F component is an ordinary R3F app. The host
-            // controls Fiber's native `frameloop: 'never'` scheduler; the vgai
-            // runtime CONTEXT (`useGameContext`, `ctx.systems`) never enters its
-            // React tree.
-            //
-            // This flag governs that context and nothing else. It does NOT govern
-            // `WorldProvider`: `useDebugProvider`/`useDebugCommand`/`useWorldState`
-            // are the documented door a game declares its own state/commands
-            // through, and they must work in the idiomatic shape — which is the
-            // ONLY shape `vgai create` scaffolds. `r3f-adapter.tsx` therefore keys
-            // that provider off `host.game`, not off this flag; see the comment
-            // beside `const game = host.game` there for the measured symptom
-            // (`vgai eval 'await game.providers()'` listing only built-ins).
-            engineRuntime: false,
-        });
-    }
+    if (typeof mod?.default === 'function')
+        return threeWorldAdapter(rootId, mod.default);
     return null;
 }
 /**
  * Register with `registerAdapter('three', r3fRootFactory)`.
- *
- * Resolution order mirrors `defaultThreeAdapterFactory`'s (explicit adapter
- * wins) and then accepts the default-exported component.
  */
 export const r3fRootFactory = (root, ctx) => {
     const adapter = resolveR3FEntryAdapter(ctx.entryModule, root.id);
     if (adapter)
         return { kind: 'three', adapter };
     throw new Error(`r3fRootFactory: entry module "${root.entry ?? '(none)'}" for root "${root.id}" must ` +
-        'default-export a React component (`export default function World() { … }`) — or export ' +
-        'an `adapter` for full control.');
+        'default-export a React component (`export default function World() { … }`).');
 };

package/dist/world3d-react/rapier-physics-bridge.d.ts

@@ -4,11 +4,9 @@
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
  * coordination (`freeze → apply → unfreeze`) and the universal
- * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
- * first-party imperative three root registers one from
- * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
- * Rapier runtime at all (see `R3FGameContext`'s doc comment) — it does physics
- * with `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. An R3F world
+ * builds no first-party Rapier runtime at all — it does physics with
+ * `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
  * can see it. Result, before this: the colliders instrument read `null` (an
  * em-dash) and its toggle threw "no physics adapter" in every shipped example
  * and every scaffolded game.
@@ -40,24 +38,30 @@
  * is how a `SystemAdapters` member says "not supported".
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
- * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
- * on the R3F root it is mounted in. It allocates nothing else — no timers, no
- * subscriptions, no per-frame work (see the phase note below), and no Rapier
- * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the
- * colliders instrument, the editor's transform coordination. They read; they
- * never dispose.
- * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
- * set (`registerSystemAdapter('physics', undefined)`, which
- * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
- * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
- * bridges in one root would fight over that one key; mount exactly one.
+ * OWNER: this component owns one physics ADAPTER, published onto the ONE
+ * module-scoped slot `rapierPhysicsSystem()` forwards to (GAME-GLOBAL — the
+ * entry's static `systems.physics` declaration cannot be per-root). It allocates nothing
+ * else — no timers, no subscriptions, no per-frame work (see the phase note
+ * below), and no Rapier objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the colliders
+ * instrument, the editor's transform coordination. They read; they never
+ * dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
+ * and the slot it set (identity-guarded), so a play stop/start, a hot
+ * restart, or a world that unmounts `<Physics>` leaves no stale adapter
+ * behind. Because the slot is PAGE-global (see its doc below — an engine
+ * module is shared across the editor's Play instances), mount exactly ONE
+ * bridge per PAGE: with two — a scene that mounts two, or two Play instances
+ * of one rapier world — the later mount wins the slot and the later unmount
+ * clears it while the earlier bridge is still live. That state is reported
+ * loudly the moment it starts (`warnOnContendedMount`).
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
  * BETWEEN frames, by an editor gesture or an instrument command, never from a
  * phase.
  */
+import type { PhysicsAdapter } from '../adapter/system-adapter';
 export interface RapierPhysicsBridgeProps {
     /**
      * Set the `debug` prop of the SAME `<Physics>` this bridge is mounted in.
@@ -73,4 +77,13 @@ export interface RapierPhysicsBridgeProps {
  * `useRapier()`). Renders nothing.
  */
 export declare function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps): null;
+/**
+ * The `systems.physics` slot for a default-exported world — declare it from
+ * the entry (`export const systems = { physics: rapierPhysicsSystem() }`) and
+ * keep `<RapierPhysicsBridge />` mounted inside `<Physics>`. Every call
+ * forwards to the LIVE bridge adapter, so the static declaration answers with
+ * the running world's physics; while none is mounted, every call refuses by
+ * name rather than fabricating.
+ */
+export declare function rapierPhysicsSystem(): PhysicsAdapter;
 //# sourceMappingURL=rapier-physics-bridge.d.ts.map

package/dist/world3d-react/rapier-physics-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAkBH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0PrF"}
+{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAUH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0QrF;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}