@vgai/engine 0.5.1 → 0.5.3

package/src/runtime/types.ts

@@ -5,21 +5,20 @@ import type { z } from 'zod';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import type { AssetCache } from '../assets';
 import type { SeededRandom } from '../core/seeded-random';
+import type { SimClock } from '../core/sim-clock';
 import type { createSystemRunner } from '../core/system-runner';
 import type { createDebugDraw } from '../dev/debug-draw';
-import type { ComponentManager } from '../ecs/component-manager';
+import type { SceneIndex } from '../ecs/scene-index';
 import type { InputManager } from '../input/input-manager';
 import type { CollisionSystem } from '../physics/collision-system';
 import type { PhysicsRegistry } from '../physics/physics-registry';
-import type { SceneFile } from '../scene/scene-types';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import type { ParticlesContext } from '../setup/setup-particles';
-import type { Game, WorldInstance } from './game';
+import type { Game, RootInstance } from './game';
 
 /**
  * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
- * Colyseus room (Task 2.2, `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1's "Multiplayer
- * locus" note): just enough to send the reserved `__vgai:debugCommand`
+ * Colyseus room: just enough to send the reserved `__vgai:debugCommand`
  * message and listen for its `__vgai:debugCommandResult` reply. Structural,
  * not a Colyseus type import — the same seam-boundary style every other
  * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
@@ -36,11 +35,10 @@ export interface DebugRoomHandle {
 /**
  * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
  * handler's parameter tuple from its declared Zod `args` tuple (dry-run
- * finding, `docs/E2E-TESTING-BUILD-PLAN.md` Wave 6 ledger —
- * "`registerCommand` fn typing forces `unknown[]` casts"): a real
- * `z.ZodTuple` infers its element types (`z.tuple([z.number(), z.string()])`
- * → `(n: number, s: string) => ...`), while omitting `args` (the generic's
- * `undefined` default) resolves to the original permissive
+ * finding, ledger — "`registerCommand` fn typing forces `unknown[]` casts"):
+ * a real `z.ZodTuple` infers its element types (`z.tuple([z.number(),
+ * z.string()])` → `(n: number, s: string) => ...`), while omitting `args`
+ * (the generic's `undefined` default) resolves to the original permissive
  * `(...args: unknown[]) => ...` shape every command had before this generic
  * existed. That permissive fallback is deliberate, not just a placeholder —
  * it keeps every existing no-schema registration (including ones whose
@@ -53,13 +51,11 @@ export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T e
   : unknown[];
 
 /**
- * The authoring half of the debug/synthetic-player seam
- * (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1) — the read/actuate half is
- * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from
- * any GameComponent's `init` (one file per new provider/command), or from a
- * react world's `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration
- * feeds the ONE game-scoped registry (`runtime/debug-registry.ts`) — never a
- * per-world accumulator.
+ * The authoring half of the debug/synthetic-player seam — the read/actuate half is
+ * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from any
+ * `init` (one file per new provider/command), or from a react world's
+ * `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration feeds the ONE
+ * game-scoped registry (`runtime/debug-registry.ts`) — never a per-world accumulator.
  */
 export interface DebugCtxSurface {
   /** Register (or replace) a named, JSON-serializable state read. Duplicate
@@ -99,7 +95,7 @@ export interface DebugCtxSurface {
 
 /**
  * All engine subsystems, passed to every game `setup(ctx)` and to each
- * GameComponent lifecycle method (`init`/`update`/`dispose`/trigger callbacks).
+ * game lifecycle callback.
  *
  * The surface is intentionally split in two:
  *
@@ -109,6 +105,17 @@ export interface DebugCtxSurface {
  *   into the phase-ordered game loop. Reach for these when you need behavior the
  *   raw library doesn't provide (physics↔Object3D mapping, system phases, etc.).
  */
+/** Host-supplied identity for one private play run or coordinated team test.
+ * Games may pass `roomKey` as a Colyseus filter/join option; the engine never
+ * joins a room or couples this authoring identity to a networking library. */
+export interface PlaytestContext {
+  readonly mode: 'private' | 'team';
+  readonly id: string;
+  readonly roomKey: string;
+  readonly revision: number | null;
+  readonly participantId: string | null;
+}
+
 export interface GameContext {
   // ─── Raw libraries (the real library objects — call them directly) ───
 
@@ -116,7 +123,7 @@ export interface GameContext {
    *  groups) here. This is THE scene — there is no separate engine scene. */
   scene: THREE.Scene;
   /** The single render camera. Move/aim it directly, or (preferred) drive it
-   *  from a camera GameComponent — see the camera-precedence note below. */
+   *  from game code — see the camera-precedence note below. */
   camera: THREE.PerspectiveCamera;
   /** The Rapier physics `World`. Step/query it, create bodies & colliders via
    *  `ctx.rapier`. One shared world for the whole scene. */
@@ -136,7 +143,7 @@ export interface GameContext {
   input: InputManager;
   /** Rapier collision-event dispatcher. Register handlers with
    *  `collisions.onCollision(...)`; it is drained each `postPhysics`. Prefer a
-   *  GameComponent's `onTriggerEnter/Exit` for per-entity sensor logic. */
+   *  own handler for per-entity sensor logic. */
   collisions: CollisionSystem;
   /** `Object3D ↔ Rapier body/collider` registry (+ collider→Object3D reverse
    *  index). Use to find an entity's body/collider, or the entity behind a
@@ -161,11 +168,36 @@ export interface GameContext {
   assets: AssetCache;
   /** The phase-ordered system runner. `systems.add(phase, fn)` registers a
    *  per-frame callback. Reserve this for non-gameplay infra (audio mixers,
-   *  network send); per-entity GAMEPLAY belongs in a GameComponent. */
+   *  network send); per-entity GAMEPLAY belongs in a `useFrame` hook. */
   systems: ReturnType<typeof createSystemRunner>;
-  /** Manager for all live GameComponent instances (attach/detach/HMR). The
-   *  scene loader drives this; gameplay code rarely touches it directly. */
-  components: ComponentManager;
+  /**
+   * P3 — the SIM-TIME scheduler (`core/sim-clock.ts`). `await ctx.clock.delay(n)`
+   * waits `n` seconds of the fixed loop's own time, so it pauses when the game
+   * pauses, steps when `Game.play.step()` steps, and reproduces exactly in an
+   * offline export; `ctx.clock.after(n, fn)` is the frame-exact synchronous
+   * form, and `ctx.clock.disposeAfter(obj, n)` is debris removal. Cancellation
+   * is `AbortSignal`.
+   *
+   * REQUIRED, unlike `debug`/`random` above: every world has a sim clock. When
+   * a Game hosts the mount it is the ONE game-scoped clock the fixed loop
+   * flushes; a bare harness mount with no Game shell gets a private,
+   * mount-local clock that nothing advances (so `now()` stays 0) rather than an
+   * absent field.
+   *
+   * NOT `AnimationClock` (`animation/animation-clock.ts`) — that one is the
+   * seekable cinematic playhead and runs backwards. This one is monotonic and
+   * never rewinds, which is exactly why a Promise can be bound to it. See
+   * `core/sim-clock.ts`'s header.
+   */
+  clock: SimClock;
+  /** The live scene index for this root (P2 `observe`): tag/entity-id lookup
+   *  that never traverses, plus the change signals — `entityadded`,
+   *  `entityremoved`, `tagadded`, `tagremoved`, `attributechanged` — on a plain
+   *  `EventTarget`, unsubscribed with an `AbortSignal`. Maintained from three's
+   *  own `childadded`/`childremoved` parent events, so it costs nothing on a
+   *  frame where nothing changes. See `ecs/scene-index.ts`; the one-shot
+   *  `ecs/scene-query.ts` walks remain for a single ad-hoc question. */
+  sceneIndex: SceneIndex;
   /** Register a game-owned `SystemAdapters` capability (networking,
    *  navigation, …) on the mounted game's adapter surface, so the editor's
    *  introspection panels (via `getActiveSystems()`) can see it. The engine
@@ -186,33 +218,32 @@ export interface GameContext {
    *  mounted surface. */
   registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
 
-  /** The debug/synthetic-player authoring surface (`docs/SYNTHETIC-PLAYER-SPEC.md`
-   *  §3.1) — see {@link DebugCtxSurface}. Optional, same absence precedent as
-   *  `registerSystemAdapter`: present on every first-party mount, absent only
-   *  in bare test harnesses that build a hand-rolled `ctx`. */
+  /** The debug/synthetic-player authoring surface — see {@link DebugCtxSurface}.
+   *  Optional, same absence precedent as `registerSystemAdapter`: present on every
+   *  first-party mount, absent only in bare test harnesses that build a
+   *  hand-rolled `ctx`. */
   debug?: DebugCtxSurface;
 
   /**
-   * D15 (T-D15.1, `docs/D15-DETERMINISM-DESIGN.md` §2.a) — the game-scoped,
-   * named-stream seeded PRNG. `ctx.random()` draws from the `'gameplay'`
-   * stream; `ctx.random.stream('vfx')` (or any other name) draws from an
-   * INDEPENDENT stream, so a cosmetic/VFX draw can never shift the gameplay
-   * draw sequence. Use this instead of raw `Math.random()` for anything a
-   * project wants to keep reproducible; `ctx.random` itself always exists
-   * and is always internally consistent (same seed ⇒ same sequence) whether
-   * or not the project's manifest declares `determinism.seededRandom` — that
-   * flag only gates the BOOT-TIME seeding from
-   * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint
-   * scan, and the dev-mode `Math.random` phase trap (three separate
-   * enforcers, `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`),
-   * never `ctx.random`'s mere presence. Same absence precedent as `debug`
-   * above: present on every first-party mount, optional only for bare test
-   * harnesses that build a hand-rolled `ctx`. `reseed(seed)` (future draws
-   * only) is `play.seed.set`'s eventual target (T-D15.6, not yet wired).
+   * D15 (T-D15.1) — the game-scoped, named-stream seeded PRNG. `ctx.random()`
+   * draws from the `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other
+   * name) draws from an INDEPENDENT stream, so a cosmetic/VFX draw can never
+   * shift the gameplay draw sequence. Use this instead of raw `Math.random()` for
+   * anything a project wants to keep reproducible; `ctx.random` itself always
+   * exists and is always internally consistent (same seed ⇒ same sequence)
+   * whether or not the project's manifest declares `determinism.seededRandom` —
+   * that flag only gates the BOOT-TIME seeding from
+   * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint scan,
+   * and the dev-mode `Math.random` phase trap (three separate enforcers,
+   * `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`), never
+   * `ctx.random`'s mere presence. Same absence precedent as `debug` above:
+   * present on every first-party mount, optional only for bare test harnesses
+   * that build a hand-rolled `ctx`. `reseed(seed)` (future draws only) is
+   * `play.seed.set`'s eventual target (T-D15.6, not yet wired).
    */
   random?: SeededRandom;
 
-  // ─── Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6) ───
+  // ─── Game root (T7.1 slice 1 — D6) ───
 
   /** The Game root — the loop, the world registry, and game-scoped handles.
    *  Absent only in bare test harnesses that construct a partial context (the
@@ -222,7 +253,10 @@ export interface GameContext {
   game?: Game | undefined;
   /** Alias for `game.roots` — the live, declaration-ordered world registry.
    *  Same optionality/absence rule as `game` above. */
-  roots?: ReadonlyArray<WorldInstance> | undefined;
+  roots?: ReadonlyArray<RootInstance> | undefined;
+  /** The host's current private play or Team Test identity. Optional for
+   * standalone/custom hosts; networking remains game-owned and direct. */
+  playtest?: PlaytestContext | null | undefined;
 }
 
 /** Return value from a game setup function. */
@@ -232,10 +266,6 @@ export interface GameCleanup {
 
 /** Context passed to setup() when launched from the editor's play mode. */
 export interface EditorPreview {
-  /** Path of the .vscn.json file the user has open (null if unsaved). */
-  scenePath: string | null;
-  /** The editor's in-memory scene document, including unsaved edits. */
-  sceneData: SceneFile;
   /** Editor viewport camera transform — use this as the initial game camera viewpoint. */
   viewportCamera?: {
     position: [number, number, number];
@@ -243,12 +273,16 @@ export interface EditorPreview {
   };
   /**
    * Which bundled example the static/browser build's project picker wants to
-   * run (docs/EXAMPLES-AS-PROJECTS-DESIGN.md §4 — Adjudication H). Only
-   * meaningful to `packages/editor/src/browser-play-entry.ts`'s dispatch over
-   * the generated `SETUP_BY_EXAMPLE_ID` table; every other `GameSetupFn`
-   * consumer ignores it. Undefined ⇒ the generic scene-loader fallback
-   * (today's only reachable behavior — no caller sets this yet, since the
-   * picker itself is a later wave).
+   * run (Adjudication H).
+   *
+   * Its one former reader — `browser-play-entry.ts`'s whole-bundle `setup()`,
+   * which dispatched over the generated `SETUP_BY_EXAMPLE_ID` table — is
+   * DELETED. Hosted dispatch is per-root (`ADAPTER_BY_EXAMPLE_ROOT` /
+   * `REACT_BY_EXAMPLE_ROOT`, resolved in `adapter-resolver.ts`) and never
+   * consults this field; `exampleDispatchFor` still sets it as the marker for
+   * "play the project's own shipped game" rather than a `?scene=` override
+   * (which sets `assetPrefix` instead — that one IS read, by
+   * `SetupThreeRootAdapter`). Every `GameSetupFn` consumer ignores it.
    */
   exampleId?: string | undefined;
   /**
@@ -265,9 +299,8 @@ export interface EditorPreview {
 /** A game setup function: receives engine context, returns cleanup.
  *
  * This is the MOUNT body of the FIRST-PARTY implementer. The host no longer
- * depends on it — the host depends on `GameAdapter` (`@engine/adapter`), and
- * `GameSetupFn` is wrapped into a `VgaiSceneGameAdapter` via `fromSetup`. See
- * docs/ADAPTER-ARCHITECTURE.md. (The former `GameAdapter` `{ setup, components }`
- * interface lived here; it is superseded by the real adapter interfaces in
- * `@engine/adapter`.) */
+ * depends on it — the host depends on `RootAdapter` (`@engine/adapter`), and
+ * `GameSetupFn` is wrapped into a `SetupThreeRootAdapter` via `fromSetup`.. (The
+ * former `RootAdapter` `{ setup, components }` interface lived here; it is
+ * superseded by the real adapter interfaces in `@engine/adapter`.) */
 export type GameSetupFn = (ctx: GameContext, editor?: EditorPreview) => Promise<GameCleanup>;

package/src/setup/setup-renderer.ts

@@ -35,9 +35,10 @@ import {
   SSREffect,
   VelocityDepthNormalPass,
 } from '../../vendor/realism-effects/dist/index.js';
+import type { RenderEnvironment } from '../asset-formats/render-env';
+import { DEFAULTS } from '../defaults';
+import { detectKtx2Support } from '../loader';
 import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
-import { DEFAULTS } from '../scene/defaults';
-import type { SceneEnvironment } from '../scene/scene-types';
 
 export interface RendererContext {
   renderer: THREE.WebGLRenderer;
@@ -69,14 +70,14 @@ export function applyRendererSettings(
 
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
- * `HostContext.renderer`); the game/adapter owns the scene/camera/composer it
+ * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
  * renders into. Split out of `setupRenderer` for the adapter inversion.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
  * settings (via {@link applyRendererSettings}). Absent → registry defaults.
  *
- * `opts` is additive (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §1/§4): omitted
+ * `opts` is additive (T6.1 slice 1, D5 §1/§4): omitted
  * entirely, construction is byte-identical to before (no `alpha`/
  * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
  * passes it. The roots path passes `alpha:true` for every stacked canvas
@@ -109,6 +110,10 @@ export function createHostRenderer(
   renderer.shadowMap.type = THREE.PCFSoftShadowMap;
   renderer.toneMapping = toneMappingModes[DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
   renderer.toneMappingExposure = DEFAULTS.toneMapping.exposure;
+  // The shared KTX2Loader cannot transcode a KHR_texture_basisu texture until
+  // some renderer has told it which compressed formats this GPU accepts.
+  // Idempotent — see `detectKtx2Support`.
+  detectKtx2Support(renderer);
   return renderer;
 }
 
@@ -193,7 +198,7 @@ export function applyScenePostProcessing(
   renderer: THREE.WebGLRenderer,
   scene: THREE.Scene,
   camera: THREE.Camera,
-  env?: SceneEnvironment,
+  env?: RenderEnvironment,
   objectMap?: Map<string, THREE.Object3D>,
   entityTags?: Map<string, string[]>,
 ): void {
@@ -553,7 +558,7 @@ export function applySceneRenderPipeline(
   renderer: THREE.WebGLRenderer,
   scene: THREE.Scene,
   camera: THREE.Camera,
-  env?: SceneEnvironment,
+  env?: RenderEnvironment,
   options?: {
     basePixelRatio?: number;
     objectMap?: Map<string, THREE.Object3D>;

package/src/world3d-react/engine-bridge.ts

@@ -1,48 +1,61 @@
 /**
- * `@engine/world3d-react` — the React context that carries the engine
- * component runtime into an R3F tree, so `<Behavior>` (./behavior.tsx) can
- * reach the REAL `ComponentManager.attach` path from inside fiber JSX.
+ * `@engine/world3d-react` — the React context that carries this R3F world's
+ * engine runtime into its fiber tree: the world's `R3FGameContext`, read
+ * with {@link useGameContext}.
  *
- * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4,
- * docs/R3F-FOLLOW-THROUGH-SPEC.md — the opt-in module
- * R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names). The bridge value is built by
- * `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
- * `createSystemRunner` + `createComponentManager` pair whose phases the
- * adapter's `update(dt)` runs under the HOST loop — so attached
- * GameComponents tick in engine phase order, pause included (no update while
- * the world is frozen), exactly like scene-authored components.
+ * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4).
+ * The bridge value
+ * is built by `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
+ * `createSystemRunner` whose phases the adapter's `update(dt)` runs under the
+ * HOST loop — so registered systems tick in engine phase order, pause included
+ * (no update while the world is frozen).
  *
- * `registry` is the project's own behavior registry (`<Behavior type="…">`
- * resolves against it) — REGISTRY-DRIVEN by design: the engine module never
- * imports project code; the project hands its registry to
- * `createR3FAdapter({ components })`, which places it here.
+ * Behavior in an R3F world is components and hooks: `useGameContext` is how a
+ * component reaches engine services.
  */
 
-import { createContext } from 'react';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { GameComponentClass } from '../ecs/game-component';
-
-/** A project's behavior registry: `<Behavior type>` keys → component classes. */
-export type BehaviorRegistry = Readonly<Record<string, GameComponentClass>>;
+import { createContext, useContext } from 'react';
+import type { R3FGameContext } from './world-context';
 
 export interface EngineBridgeValue {
-  /** The engine's real component manager for this R3F world. */
-  readonly components: ComponentManager;
-  /** The project's behavior registry (absent ⇒ `<Behavior>` degrades loudly). */
-  readonly registry?: BehaviorRegistry | undefined;
+  /** This root's context — `input`, `debug`, `random`, `game`, `roots`, … .
+   *  Present so ordinary components can reach engine services with a HOOK
+   *  (see {@link useGameContext}). */
+  readonly ctx?: R3FGameContext | undefined;
 }
 
 export const EngineBridge = createContext<EngineBridgeValue | null>(null);
 
-/** Resolve a `<Behavior type>` key against the bridge's registry, throwing a
- *  teaching error naming the registered keys (the same loud failure shape the
- *  example's project-owned `getComponent` had). */
-export function resolveBehaviorClass(registry: BehaviorRegistry, type: string): GameComponentClass {
-  const cls = registry[type];
-  if (!cls) {
+/**
+ * This R3F root's context, for use inside any component in the tree — an
+ * {@link R3FGameContext}, which is exactly the subsystems an R3F world builds.
+ * The ones it does not build are absent from the type, so reaching for one is
+ * a compile error at the call site; that type's doc comment says what to reach
+ * for instead.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 4.5 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<THREE.Group>(null);
+ *   useFrame((_, dt) => { if (input.isPressed('move_forward')) … });
+ *   return <group ref={ref}><PlayerCharacter /></group>;
+ * }
+ * ```
+ *
+ * Throws when called outside an R3F root mounted by `createR3FAdapter` —
+ * absent context is a wiring bug, and a silent `null` would surface as a
+ * mystery `undefined` deep in a frame callback.
+ */
+export function useGameContext(): R3FGameContext {
+  const bridge = useContext(EngineBridge);
+  if (!bridge?.ctx) {
     throw new Error(
-      `Unknown behavior type "${type}" — registered: ${Object.keys(registry).join(', ')}`,
+      'useGameContext(): no engine root context. This hook only works inside an R3F ' +
+        'root mounted by createR3FAdapter (@engine/world3d-react) — check that the ' +
+        'component is rendered inside your world entry, not in a standalone <Canvas>.',
     );
   }
-  return cls;
+  return bridge.ctx;
 }

package/src/world3d-react/index.ts

@@ -1,15 +1,15 @@
 /**
- * world3d-react — the react-three-fiber bridge for vgai's threejs surface
+ * world3d-react — the react-three-fiber bridge for vgai's three surface
  * (`@engine/world3d-react`).
  *
- * The OPT-IN module R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names, upstreamed
- * from the live-proven `examples/r3f-first-party` project copies (R4,
- * docs/R3F-FOLLOW-THROUGH-SPEC.md; decision D24 — R3F TSX is the blessed
- * three.js authoring path). Mirrors how `world2d/` is pixi's opt-in home: a
- * peer surface module the engine CORE never imports (enforced by
- * `packages/engine/test/react-core-import-ban.test.ts` — this directory is
- * an allowed react-importing entry alongside `react/`, and core files may
- * not import it).
+ * An OPT-IN module, upstreamed
+ * from the live-proven `examples/r3f-first-party` project copies (R4;
+ * decision D24 — R3F TSX is the blessed three.js authoring path). Mirrors how
+ * `pixi/` is the PixiJS surface's opt-in home: a peer surface module the engine
+ * CORE never imports (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/`, and core files may not
+ * import it).
  *
  * Peer contract: an importing PROJECT already depends on `react`,
  * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
@@ -19,26 +19,31 @@
  * that already mount through fiber ever import this module.
  *
  * Surface:
- *  - `createR3FAdapter({ id, content, components })` — mount an R3F tree as
- *    a first-party `kind: "threejs"` world under the host's gated loop.
- *  - `<Behavior type="…" {...config}>` — attach a registry GameComponent to
- *    the wrapped child's Object3D under engine phases (registry-driven via
- *    `EngineBridge`; generic over the project's registry for typed keys).
- *  - `EngineBridge` / `EngineBridgeValue` / `BehaviorRegistry` — the context
- *    contract, exported for advanced adopters building their own bridge.
+ *  - `createR3FAdapter({ id, content })` — mount an R3F tree as a first-party
+ *    `kind: "three"` world under the host's gated loop.
+ *  - `useGameContext()` — this root's `R3FGameContext` (`input`, `debug`,
+ *    `random`, `game`, `roots`, …) from inside any component in the tree. This
+ *    is how an R3F world reaches engine services: behavior is components +
+ *    hooks (D26b), not a class under a string key. The subsystems an R3F world
+ *    does not build are absent from that type — see its doc comment for what
+ *    to use instead.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
+ *    for advanced adopters building their own bridge.
  */
 
-export { Behavior, type BehaviorProps } from './behavior';
-export {
-  type BehaviorRegistry,
-  EngineBridge,
-  type EngineBridgeValue,
-  resolveBehaviorClass,
-} from './engine-bridge';
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
 export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
+export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
+export {
+  applyWorldRendererConfig,
+  type WorldOutputColorSpace,
+  type WorldRendererConfig,
+  type WorldToneMapping,
+} from './renderer-config';
 export {
-  createR3FWorldContext,
+  createR3FRootContext,
   DEFAULT_INPUT_MAP_PATH,
-  type R3FWorldContextOptions,
-  type R3FWorldRuntime,
+  type R3FGameContext,
+  type R3FRootContextOptions,
+  type R3FRootRuntime,
 } from './world-context';