@vgai/engine 0.5.2 → 0.5.3

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

@@ -1,71 +1,74 @@
 /**
  * `createR3FAdapter` — wraps a react-three-fiber tree as a first-party
- * `GameAdapter` so an R3F scene mounts as an ordinary `kind: "threejs"`
- * world: the engine hands `mount()` a `HostContext` (ITS OWN renderer +
+ * `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
- * `MountedThreeWorld` (`../adapter/game-adapter.ts`) whose `scene`/`camera`
+ * `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,
- * docs/R3F-FOLLOW-THROUGH-SPEC.md — the `@engine/world3d-react` opt-in
- * module R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names, mirroring how `world2d/`
- * is pixi's opt-in home). The mount semantics are byte-for-byte the
- * example's live-proven Phase-1 bridge; the one addition is the optional
- * `components` registry threaded into `EngineBridge` so `<Behavior>` can
- * resolve project component classes without the engine importing project
- * code. External adopters (alien-stories-style) keep the exact same calling
- * contract.
+ * 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 (docs/ADAPTER-AUTHORING-GUIDE.md §2): 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
- * `HostContext.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`).
+ * 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, type RootState } from '@react-three/fiber';
+import {
+  advance,
+  createRoot,
+  extend,
+  events as pointerEvents,
+  type RootState,
+} from '@react-three/fiber';
 import { createElement, type ReactNode } from 'react';
-import type { GameAdapter, HostContext, MountedThreeWorld } from '../adapter';
-import { type BehaviorRegistry, EngineBridge, type EngineBridgeValue } from './engine-bridge';
-import { createR3FWorldContext } from './world-context';
+import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import { WorldProvider } from '../react/world-state';
+import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
+import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
+import { createR3FRootContext } from './world-context';
 
-/** What {@link createR3FAdapter} needs to build one `GameAdapter`. */
+/** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
 export interface CreateR3FAdapterOptions {
-  /** Stable id (telemetry/registry/conformance) — `GameAdapter.id`. */
+  /** 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;
-  /** The project's behavior registry — `<Behavior type="…">` resolves against
-   *  it through `EngineBridge`. Optional: a tree with no `<Behavior>` usage
-   *  needs none; a `<Behavior>` rendered without it degrades loudly (warn,
-   *  no attach) rather than crashing. */
-  readonly components?: BehaviorRegistry | undefined;
   /** 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;
+  /** 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 `./renderer-config.ts`. */
+  readonly renderer?: WorldRendererConfig | undefined;
 }
 
 /**
- * Build a `GameAdapter` that mounts `options.content` through
+ * 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): GameAdapter {
-  const { id, content, components: registry, inputMapPath } = options;
+export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter {
+  const { id, content, inputMapPath, renderer: rendererConfig } = options;
 
   return {
     id,
 
-    async mount(host: HostContext): Promise<MountedThreeWorld> {
-      // Headless honesty (design §1.D; `docs/ADAPTER-AUTHORING-GUIDE.md` §2's
-      // "Your `mount()` must work headless" rule): the conformance kit / CI
+    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
@@ -78,7 +81,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
         const scene = new host.three.Scene();
         const camera = new host.three.PerspectiveCamera();
         return {
-          kind: 'threejs',
+          kind: 'three',
           scene,
           camera,
           drivesOwnLoop: false,
@@ -99,31 +102,37 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
       // per mount is idempotent.
       extend(host.three as unknown as Parameters<typeof extend>[0]);
 
-      // W3 (docs/R3F-SURFACE-SPIKE.md) — the engine component runtime this
-      // world OWNS: a real SystemRunner + ComponentManager pair, provided to
-      // the R3F tree via `EngineBridge` so `<Behavior>` (./behavior.tsx) can
-      // attach registry GameComponents with the engine's REAL attach path.
-      // `update(dt)` below runs the phases under the host loop, so attached
-      // components tick in engine phase order and freeze under pause exactly
-      // like `useFrame` work does.
+      // 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 still a PARTIAL GameContext, but
-      // the shared game-scoped subsystems are now 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 THROWING
-      // getters naming the limitation — never a silent `undefined`.
-      // `scene`/`camera` are backfilled right after fiber's first commit
-      // resolves them, before any tick can run.
-      const runtime = createR3FWorldContext(host, { id, inputMapPath });
-      const { systems, components } = runtime;
-      const bridge: EngineBridgeValue = { components, registry };
-      // Actions must exist before any Behavior component's init() reads them —
-      // wait for the (never-rejecting) input-map load before the first commit.
+      // 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: EngineBridgeValue = { 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: () => void = () => {};
+
       const canvas = host.surface.canvas;
       const root = createRoot(canvas);
 
@@ -149,6 +158,28 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
         // 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).
@@ -159,20 +190,70 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
         // 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 },
-        // `events` deliberately left at fiber's default (binds to
-        // `gl.domElement`, i.e. `host.surface.canvas`) — design O1's open
-        // question about a delegating multi-canvas input router only
-        // matters for a shell+net composite; this bridge is a genuine
-        // single-canvas world, the case O1 already says is unaffected.
+        // 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) to any `<Behavior>` wrapper in the tree (W3).
-      root.render(createElement(EngineBridge.Provider, { value: bridge }, content));
+      // (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
@@ -183,6 +264,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
           cleanup();
           root.unmount();
           runtime.dispose();
+          restoreRendererConfig();
           reject(
             new Error(
               `r3f-adapter: fiber crashed before its first commit — ${event.message} ` +
@@ -194,6 +276,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
           cleanup();
           root.unmount();
           runtime.dispose();
+          restoreRendererConfig();
           reject(
             new Error(
               'r3f-adapter: onCreated did not fire within 10s — the R3F tree never reached ' +
@@ -228,26 +311,43 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
       // `update(dt)` tick, so no component ever observes them missing.
       runtime.setSceneCamera(state.scene, state.camera);
 
-      // Match the classic scene-loader readiness contract: a mounted world is
-      // not ready until every scene-authored component has completed init().
-      // Deterministic warm-ups may advance many fixed substeps synchronously;
-      // an init deferred to the first frame cannot make progress until after
-      // that entire warm-up has already ended. `<Behavior>` attaches during
-      // the commit layout phase, so initAll() sees the complete component set.
-      await components.initAll();
+      // 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();
 
       // The engine drives every `useFrame` through the mounted world's
-      // `update(dt)` hook — NOT `host.loop.onUpdate`. The distinction is the
+      // `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 the
-      // raw loop's `onUpdate` extraUpdaters fire unconditionally, pause or
-      // not (they exist for host-level concerns; `create-runtime.ts` runs
-      // them outside `game.runFrame`'s gate). Advancing fiber from
-      // `onUpdate` therefore 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`.
+      // 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
@@ -263,9 +363,11 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
       // 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: 'threejs',
+        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
@@ -274,36 +376,49 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
         // `state.camera`'s type (`Camera = (OrthographicCamera |
         // PerspectiveCamera) & { manual?: boolean }`) is a structural subtype
         // of `THREE.Camera`, so no cast is needed.
-        scene: state.scene,
-        camera: state.camera,
+        //
+        // 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,
-        // The engine's REAL ComponentManager for this world — what makes
-        // `Game.queryByComponent` see `<Behavior>`-attached components
-        // (`runtime/game.ts` aggregates this optional capability for every
-        // non-first-party mount that exposes one).
-        components,
         // 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: number): void {
           elapsed += dt;
-          // Engine phases FIRST (attached GameComponents mutate transforms),
+          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 behavior models — `useFrame` and
-          // `<Behavior>` — are host-gated: neither runs while frozen.
+          // the fresh state). Both are host-gated: neither runs while frozen.
           systems.run(dt);
-          advance(elapsed, true, state);
+          advance(elapsed, true, current);
         },
         resize(width: number, height: number): void {
-          state.setSize(width, height);
+          live().setSize(width, height);
         },
         dispose(): void {
-          // Unmount FIRST so <Behavior> effect cleanups detach through the
-          // live manager, then tear the runtime down (components.clear +
-          // scoped debug-registry strip).
+          // Unmount FIRST so component effect cleanups run, then tear the
+          // runtime down (scoped debug-registry strip).
           root.unmount();
           runtime.dispose();
+          restoreRendererConfig();
         },
       };
     },

package/src/world3d-react/r3f-root-factory.tsx

@@ -0,0 +1,91 @@
+/**
+ * `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 ComponentType, createElement } from 'react';
+import type { RootAdapter } from '../adapter/root-adapter';
+import type { AdapterSurfaceFactory } from '../runtime/mount-game';
+import { createR3FAdapter } from './r3f-adapter';
+
+interface R3FEntryModuleExports {
+  /** The idiomatic shape: the world IS a component. */
+  readonly default?: ComponentType;
+  /** Full control, and still the winner when present. */
+  readonly adapter?: RootAdapter;
+}
+
+/**
+ * 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: unknown, rootId: string): RootAdapter | null {
+  const mod = entryModule as R3FEntryModuleExports | undefined;
+  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: AdapterSurfaceFactory = (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.',
+  );
+};