@vgai/engine 0.5.4 → 0.5.6

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

@@ -0,0 +1,368 @@
+/**
+ * `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, events as pointerEvents, } from '@react-three/fiber';
+import { createElement } from 'react';
+import { WorldProvider } from '../react/world-state';
+import { EngineBridge } from './engine-bridge';
+import { applyWorldRendererConfig } from './renderer-config';
+import { createR3FRootContext } from './world-context';
+/**
+ * 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, 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 = createR3FRootContext(host, { id, inputMapPath });
+            const { systems } = runtime;
+            // `ctx` rides the bridge so ordinary components can reach engine
+            // services through `useGameContext()`.
+            const bridge = { ctx: runtime.ctx };
+            // 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;
+            // 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;
+            });
+            // `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.
+            const game = runtime.ctx.game;
+            root.render(createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, content) : content));
+            // 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();
+                    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();
+                    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 statePromise.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();
+            // 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 camera `ctx` was last backfilled with — see `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,
+                // Adapter surface: `debug` pre-seeded (the shared game registry's
+                // adapter); game code adds capabilities via
+                // `ctx.registerSystemAdapter` exactly as in a classic world.
+                systems: runtime.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 (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.
+                    systems.run(dt);
+                    advance(elapsed, true, current);
+                },
+                resize(width, height) {
+                    live().setSize(width, height);
+                },
+                dispose() {
+                    // Unmount FIRST so component effect cleanups run, then tear the
+                    // runtime down (scoped debug-registry strip).
+                    root.unmount();
+                    runtime.dispose();
+                    restoreRendererConfig();
+                },
+            };
+        },
+    };
+}

package/dist/world3d-react/r3f-root-factory.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `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:
+ *
+ * ```tsx
+ * export default function World() {
+ *   return <><ambientLight /><mesh>…</mesh></>;
+ * }
+ * ```
+ *
+ * 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.
+ *
+ * ## 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.
+ *
+ * ## Compatibility
+ *
+ * An `adapter` export still wins, so existing worlds are untouched and a game
+ * needing full control over its own `RootAdapter` keeps it.
+ */
+import type { RootAdapter } from '../adapter/root-adapter';
+import type { AdapterSurfaceFactory } from '../runtime/mount-game';
+/**
+ * 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)".
+ *
+ * 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).
+ */
+export declare function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): RootAdapter | null;
+/**
+ * Register with `registerAdapter('three', r3fRootFactory)`.
+ *
+ * Resolution order mirrors `defaultThreeAdapterFactory`'s (explicit adapter
+ * wins) and then accepts the default-exported component.
+ */
+export declare const r3fRootFactory: AdapterSurfaceFactory;
+//# sourceMappingURL=r3f-root-factory.d.ts.map

package/dist/world3d-react/r3f-root-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}

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

@@ -0,0 +1,79 @@
+/**
+ * `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:
+ *
+ * ```tsx
+ * export default function World() {
+ *   return <><ambientLight /><mesh>…</mesh></>;
+ * }
+ * ```
+ *
+ * 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.
+ *
+ * ## 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.
+ *
+ * ## Compatibility
+ *
+ * An `adapter` export still wins, so existing worlds are untouched and a game
+ * needing full control over its own `RootAdapter` keeps it.
+ */
+import { createElement } from 'react';
+import { createR3FAdapter } from './r3f-adapter';
+/**
+ * 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)".
+ *
+ * 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).
+ */
+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),
+        });
+    }
+    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.');
+};

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

@@ -0,0 +1,76 @@
+/**
+ * `<RapierPhysicsBridge>` — the one line that makes an R3F world's
+ * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
+ *
+ * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
+ * coordination (`freeze → apply → unfreeze`) and the dev menu's 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
+ * 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.
+ *
+ * NOT A WRAPPER. This registers an adapter and gets out of the way: the world
+ * still writes `<Physics>` itself, with the library's own props, and every
+ * `<RigidBody>`/collider call stays `@react-three/rapier`'s own API. The one
+ * thing it cannot do for you is flip the library's debug rendering, because
+ * `@react-three/rapier@2` exposes that ONLY as the `debug` boolean PROP on
+ * `<Physics>` (its `<Debug>` component is internal and unexported). A prop is
+ * the parent's to own, so the world holds the state and this bridge hands the
+ * setter to the instrument — which is why `onDebugChange` is required:
+ *
+ * ```tsx
+ * const [physicsDebug, setPhysicsDebug] = useState(false);
+ * // …
+ * <Physics debug={physicsDebug}>
+ *   <RapierPhysicsBridge onDebugChange={setPhysicsDebug} />
+ *   …
+ * </Physics>
+ * ```
+ *
+ * Nothing draws colliders here: the wireframes are the library's own
+ * `world.debugRender()` output, rendered by its own component.
+ *
+ * ANTI-SHIM. `debugDraw()` and `contactPoints()` are OMITTED, not stubbed —
+ * the library owns its debug line segments inside the tree and hands out no
+ * handle to them, so claiming the capability would be a fabrication. Absence
+ * 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 dev menu's
+ * 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.
+ *
+ * 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 a dev-menu command, never from a
+ * phase.
+ */
+export interface RapierPhysicsBridgeProps {
+    /**
+     * Set the `debug` prop of the SAME `<Physics>` this bridge is mounted in.
+     * The dev menu's "Colliders drawn" toggle calls it; the world's own state is
+     * what `<Physics debug={…}>` reads, so the library's debug rendering is the
+     * only thing that ever draws a collider.
+     */
+    readonly onDebugChange: (debug: boolean) => void;
+}
+/**
+ * Register this R3F world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics`. Mount it once, INSIDE `<Physics>` (it reads
+ * `useRapier()`). Renders nothing.
+ */
+export declare function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps): null;
+//# sourceMappingURL=rapier-physics-bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAYH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CAkDrF"}