@vgai/engine 0.5.21 → 0.5.22

package/src/render/ibl-override-material.ts

@@ -0,0 +1,170 @@
+/**
+ * Replace Three's image-based-lighting functions on a `MeshStandardMaterial`,
+ * per fragment, without forking three.
+ *
+ * A local-probe system cannot express itself as `material.envMap`: one envMap
+ * per object picks ONE environment for the whole draw, and the decisive work —
+ * which probe volume contains this fragment, how it fades at the boundary,
+ * what happens where volumes overlap — is per-fragment and can differ across a
+ * single `InstancedMesh`. Every such system therefore does the same three
+ * things to three's own program, and this module is that shared mechanism:
+ *
+ *   1. take `ShaderChunk.envmap_physical_pars_fragment` and rename its two
+ *      entry points, so the caller's replacement can still call them as its
+ *      fallback ({@link baseIblFunctions});
+ *   2. publish the fragment's world position as a varying, spliced into
+ *      `<worldpos_vertex>` under `USE_ENVMAP` ({@link IBL_WORLD_POSITION});
+ *   3. swap the fragment chunk for the caller's own GLSL and extend the
+ *      program cache key so the variant is not shared with an unpatched
+ *      material ({@link overrideMaterialIbl}).
+ *
+ * What the caller keeps is exactly what makes its system ITS system: the
+ * lighting model in the GLSL body, the uniforms behind it, and how probes are
+ * discovered, scheduled and captured. This module decides none of that — it
+ * hands back three's own shader object and gets out of the way.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * deliberately different renderers over this one splice.
+ */
+import { type Mesh, type MeshStandardMaterial, ShaderChunk } from 'three';
+
+/** The shader object three hands to `onBeforeCompile`. */
+export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
+
+/**
+ * The `varying vec3` the vertex splice publishes and the fragment body reads.
+ *
+ * It is ONE name across every consumer on purpose: the splice that declares it
+ * lives here, so a per-consumer name would be a string two files have to agree
+ * on with nothing checking that they do.
+ */
+export const IBL_WORLD_POSITION = 'vgaiIblWorldPosition';
+
+/**
+ * Three's own IBL chunk with `getIBLIrradiance`/`getIBLRadiance` renamed to
+ * `getBaseIBLIrradiance`/`getBaseIBLRadiance`.
+ *
+ * A replacement chunk defines the original names itself; calling the renamed
+ * pair is how it falls back to the scene environment where no probe applies.
+ */
+export function baseIblFunctions(): string {
+  return ShaderChunk.envmap_physical_pars_fragment
+    .replaceAll('getIBLIrradiance', 'getBaseIBLIrradiance')
+    .replaceAll('getIBLRadiance', 'getBaseIBLRadiance');
+}
+
+/**
+ * Every material a mesh draws with that {@link overrideMaterialIbl} accepts.
+ *
+ * `isMeshStandardMaterial` is true for `MeshPhysicalMaterial` too, which is the
+ * intent: both compile the physical IBL chunk this module replaces.
+ */
+export function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[] {
+  const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+  return materials.filter((material): material is MeshStandardMaterial =>
+    Boolean((material as MeshStandardMaterial).isMeshStandardMaterial),
+  );
+}
+
+export interface IblOverrideOptions {
+  /**
+   * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at
+   * COMPILE time, not at install time, so a caller whose probe count is still
+   * settling does not have to reinstall to change it.
+   */
+  readonly fragment: () => string;
+  /**
+   * Appended to the material's own `customProgramCacheKey`, after a `|`. Must
+   * distinguish every shape of {@link IblOverrideOptions.fragment} the caller
+   * can produce — a probe COUNT belongs in here, because it changes the
+   * declared uniform array sizes.
+   */
+  readonly cacheKey: () => string;
+  /**
+   * Runs at the end of `onBeforeCompile`, with the shader three is compiling.
+   * Seed uniforms here: this is the only moment the caller is handed the
+   * object whose `uniforms` map the program will read.
+   */
+  readonly onCompile?: (shader: IblOverrideShader) => void;
+}
+
+export interface IblOverride {
+  readonly material: MeshStandardMaterial;
+  /**
+   * The shader three compiled this material with, or null before the first
+   * compile and after {@link IblOverride.restore}. Uniform writes go through
+   * `shader.uniforms`.
+   */
+  readonly shader: IblOverrideShader | null;
+  /** Put the material's own `onBeforeCompile`/`customProgramCacheKey` back. */
+  restore(): void;
+}
+
+/**
+ * Install the override. The returned handle is the only way to reach the
+ * compiled shader or to undo the patch; the material is otherwise untouched
+ * (in particular this never assigns `envMap`, which stays the caller's).
+ *
+ * The caller's own `onBeforeCompile` runs FIRST and its result is what gets
+ * spliced, so an override composes over a material that already had one.
+ */
+export function overrideMaterialIbl(
+  material: MeshStandardMaterial,
+  options: IblOverrideOptions,
+): IblOverride {
+  const previousCompile = material.onBeforeCompile;
+  const previousCacheKey = material.customProgramCacheKey;
+  let compiled: IblOverrideShader | null = null;
+
+  material.onBeforeCompile = (shader, renderer) => {
+    previousCompile.call(material, shader, renderer);
+    requireChunk(shader.vertexShader, '#include <worldpos_vertex>');
+    requireChunk(shader.fragmentShader, '#include <envmap_physical_pars_fragment>');
+    shader.vertexShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.vertexShader.replace(
+      '#include <worldpos_vertex>',
+      `#include <worldpos_vertex>
+#if defined(USE_ENVMAP)
+  ${IBL_WORLD_POSITION} = worldPosition.xyz;
+#endif`,
+    )}`;
+    shader.fragmentShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.fragmentShader.replace(
+      '#include <envmap_physical_pars_fragment>',
+      options.fragment(),
+    )}`;
+    compiled = shader;
+    options.onCompile?.(shader);
+  };
+  material.customProgramCacheKey = () => `${previousCacheKey.call(material)}|${options.cacheKey()}`;
+  material.needsUpdate = true;
+
+  return {
+    material,
+    get shader() {
+      return compiled;
+    },
+    restore() {
+      material.onBeforeCompile = previousCompile;
+      material.customProgramCacheKey = previousCacheKey;
+      material.needsUpdate = true;
+      compiled = null;
+    },
+  };
+}
+
+/**
+ * A missing chunk is a NAMED error rather than a silent no-op.
+ *
+ * `String.replace` with no match returns the string unchanged, which would
+ * leave the varying declared and never assigned — a shader that links and
+ * renders the wrong thing. The only way to reach this today is a preceding
+ * `onBeforeCompile` in the same chain having already replaced the chunk (two
+ * IBL overrides stacked on one material), and that is worth a message naming
+ * the chunk instead of a black frame.
+ */
+function requireChunk(source: string, chunk: string): void {
+  if (source.includes(chunk)) return;
+  throw new Error(
+    `overrideMaterialIbl needs three's ${chunk} shader chunk, and this material's program no longer contains it.`,
+  );
+}

package/src/runtime/game-input-seams.ts

@@ -0,0 +1,108 @@
+/**
+ * The GAME-SCOPED input wiring one world mount owns — HOST work performed from
+ * outside the world's own tree, shared verbatim by the three and canvas lanes
+ * (a project has ONE input map and one bot-input doctrine, whatever surface
+ * reads them).
+ *
+ * Two things happen here:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * A world's React tree receives no vgai context — this wiring is precisely the
+ * part that never needed one: every closure below reads GAME-scoped state the
+ * host owns (`game.input`, `game.loop.fixedDt`, the game's seed).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose, but it
+ * walks providers/commands only — the three seams set here survive it, keyed
+ * by this world's id, until a remount of the same id overwrites them. That
+ * residue is inert rather than hidden: every closure reads game-scoped state,
+ * so a stale entry actuates exactly what a live one would. What it can still
+ * do is name a dead world in `DEBUG_INPUT_WORLD_NOT_FOUND`'s registered list.
+ * Do not write "the strip clears the input seams" anywhere without changing
+ * `strip` to actually do it.
+ */
+
+import { getSeededRandom } from '../core/seeded-random';
+import type { DebugRegistry } from './debug-registry';
+import type { GameInternal } from './game';
+
+/** The conventional input-map location every scaffolded project ships
+ *  (`public/inputmaps/default.inputmap.json`). */
+export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+
+/** The slice of a host context this wiring reads — satisfied structurally by
+ *  both `ThreeHostContext` and `CanvasHostContext`. */
+export interface GameInputSeamHost {
+  readonly game?: GameInternal | null | undefined;
+  readonly headless?: boolean | undefined;
+}
+
+export function wireGameInputSeams(
+  host: GameInputSeamHost,
+  registry: DebugRegistry,
+  options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+  },
+): Promise<void> {
+  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH, optionalInputMap = false } = options;
+  if (!host.game) return Promise.resolve();
+  const game = host.game;
+  const input = game.input;
+  registry.setInputActionsSource(id, () =>
+    input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+  );
+  registry.setInputTraceSource(id, () => {
+    const raw = input.getInputTrace();
+    return {
+      version: raw.version,
+      seed: getSeededRandom(game)?.seed ?? null,
+      fixedDt: game.loop.fixedDt,
+      ticks: raw.ticks,
+    };
+  });
+  registry.setVirtualInputTarget(id, {
+    setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+    tapVirtualAction: (action) => input.tapVirtualAction(action),
+    clearVirtualActions: () => input.clearVirtualActions(),
+    scheduleActionAtTick: (tick, action, value) => input.scheduleActionAtTick(tick, action, value),
+    startInputRecording: () => input.startInputRecording(),
+    stopInputRecording: () => input.stopInputRecording(),
+    isInputRecording: () => input.isInputRecording(),
+    injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+    injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+    injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+    injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+  });
+  if (host.headless || inputMapPath === null) return Promise.resolve();
+  // Load-once through the game-owned path (competing paths across roots throw
+  // THERE, loudly). A FAILED load (missing/bad file) must not fail the mount:
+  // a world with no declared actions is legal. It degrades loudly instead —
+  // naming exactly what breaks.
+  // The non-optional call passes ONE argument, exactly as it always has — a
+  // trailing `undefined` is a different call to any observer of it.
+  const load = optionalInputMap
+    ? game.loadInputMap(inputMapPath, { optional: true })
+    : game.loadInputMap(inputMapPath);
+  return load.catch((err: unknown) => {
+    // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+    console.error(
+      `world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+        'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+        `loads. Ship one at the conventional path (${DEFAULT_INPUT_MAP_PATH}). ` +
+        `Cause: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+}

package/src/runtime/game.ts

@@ -538,6 +538,21 @@ export interface Game {
   readonly systemAdapters: SystemAdapters;
   /** Subscribe when a mounted root registers or replaces a system adapter. */
   subscribeSystemAdapters?(listener: () => void): () => void;
+  /**
+   * Install a root's STATICALLY DECLARED system-adapter slots — the native
+   * module surface's `export const systems` (adapter/native-debug-module.ts),
+   * already validated by `contract-system-adapters.ts`. The host calls this
+   * once per declaring root at mount; project components never do
+   * (ARCHITECTURE-CORE §System adapters: "Components never call
+   * `registerSystemAdapter`" — this door is the replacement, and the slots it
+   * installs take precedence over a component registration for the same root
+   * in {@link systemAdapters}'s merge, with the standard collision warning).
+   * Throws on an unmounted root id or a second declaration for the same root.
+   * Optional for the same reason {@link subscribeSystemAdapters} is: partial
+   * `Game` doubles in tests; `installNativeSystemsBindings` refuses loudly
+   * when the hosting Game lacks it.
+   */
+  installDeclaredSystemAdapters?(rootId: string, slots: Readonly<Partial<SystemAdapters>>): void;
   /** The one game-owned `InputManager`, shared by every first-party root. */
   readonly input: InputManager;
   /**
@@ -881,7 +896,13 @@ export function createGame(opts: {
   // above's "once per game instance" idiom.
   const warnedSystemAdapterKeys = new Set<string>();
   const systemAdapterListeners = new Set<() => void>();
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
+  /** Per-root slots installed by `installDeclaredSystemAdapters` — the native
+   *  module surface's static `systems` declaration. Merged BEFORE the same
+   *  root's live `mounted.systems` below, so during migration a lingering
+   *  component registration for a declared slot is shadowed (with the
+   *  standard warning) rather than silently winning by running later. */
+  const declaredSystemAdapters = new Map<string, Readonly<Partial<SystemAdapters>>>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-source × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
   function computeSystemAdapters(): SystemAdapters {
     // Debug is game-scoped: React hooks, probes, and the built-in time
     // provider all register with the one registry created above, regardless
@@ -891,9 +912,11 @@ export function createGame(opts: {
     // intentional shared registration it is.
     const result: SystemAdapters = { debug: debugRegistry.adapter };
     const ownerRootId = new Map<string, string>([['debug', '(game)']]);
-    for (const world of roots) {
-      const adapters = world.mounted.systems;
-      if (!adapters) continue;
+    const merge = (
+      owner: string,
+      adapters: Readonly<Partial<SystemAdapters>>,
+      quietKeys?: ReadonlySet<string>,
+    ): void => {
       for (const key of Object.keys(adapters) as (keyof SystemAdapters)[]) {
         if (adapters[key] === undefined) continue;
         const existingOwner = ownerRootId.get(key);
@@ -903,12 +926,19 @@ export function createGame(opts: {
           // object under `systems.debug` — that is by design, not a
           // collision, so it must never warn.
           if (result[key] === adapters[key]) continue;
+          // A world's own DECLARED slot overriding that same world's
+          // substrate-seeded default (the three lane pre-seeds physics/audio/
+          // renderDebug into `mounted.systems`) is the door working as
+          // intended, not a collision — same silence `ctx.
+          // registerSystemAdapter` gives the same override. Cross-root
+          // collisions still warn.
+          if (quietKeys?.has(key)) continue;
           if (!warnedSystemAdapterKeys.has(key)) {
             warnedSystemAdapterKeys.add(key);
             // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
             console.warn(
-              `[game] systemAdapters: "${key}" is registered by both world "${existingOwner}" and ` +
-                `world "${world.id}" — the FIRST registration ("${existingOwner}") wins; the later ` +
+              `[game] systemAdapters: "${key}" is registered by both ${existingOwner} and ` +
+                `${owner} — the FIRST registration (${existingOwner}) wins; the later ` +
                 'one is shadowed (game-scoped system adapters).',
             );
           }
@@ -916,7 +946,19 @@ export function createGame(opts: {
         }
         // biome-ignore lint/suspicious/noExplicitAny: SystemAdapters is a plain optional-field record; the per-key copy is correct by construction (same key on both sides), just not expressible without a cast
         (result as any)[key] = adapters[key];
-        ownerRootId.set(key, world.id);
+        ownerRootId.set(key, owner);
+      }
+    };
+    for (const world of roots) {
+      const declared = declaredSystemAdapters.get(world.id);
+      if (declared) merge(`world "${world.id}" (declared systems export)`, declared);
+      const adapters = world.mounted.systems;
+      if (adapters) {
+        merge(
+          `world "${world.id}"`,
+          adapters,
+          declared ? new Set(Object.keys(declared)) : undefined,
+        );
       }
     }
     return result;
@@ -1292,6 +1334,22 @@ export function createGame(opts: {
     notifySystemAdaptersChanged() {
       for (const listener of systemAdapterListeners) listener();
     },
+    installDeclaredSystemAdapters(rootId: string, slots: Readonly<Partial<SystemAdapters>>) {
+      if (!roots.some((w) => w.id === rootId)) {
+        throw new Error(
+          `installDeclaredSystemAdapters: no mounted root is named "${rootId}" ` +
+            `(mounted: ${roots.map((w) => `"${w.id}"`).join(', ') || 'none'}).`,
+        );
+      }
+      if (declaredSystemAdapters.has(rootId)) {
+        throw new Error(
+          `installDeclaredSystemAdapters: root "${rootId}" already installed its declared ` +
+            'systems — a declaration is static and installs exactly once per mount.',
+        );
+      }
+      declaredSystemAdapters.set(rootId, slots);
+      gameInternal.notifySystemAdaptersChanged();
+    },
     input,
     state: stateBridge,
     play: {

package/src/runtime/mount-game.ts

@@ -17,12 +17,17 @@
 // even the 'three' convenience export is a plain function the CALLER
 // registers, not something this module wires up automatically.
 
+import { declaredRoots } from '../adapter/manifest-interpreter';
 import {
   installNativeDebugBindings,
+  installNativeSystemsBindings,
   type NativeDebugBinding,
+  type NativeSystemsBinding,
   nativeDebugBindingFromEntryModule,
+  nativeSystemsBindingFromEntryModule,
 } from '../adapter/native-debug-module';
 import type { RootAdapter } from '../adapter/root-adapter';
+import { publishDevInstruments } from '../dev/instruments';
 import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { GameSession } from './create-runtime';
 import { type MountEntry, mountManifestRoots, resolveManifest } from './mount-manifest';
@@ -223,6 +228,15 @@ function nativeDebugForEntry(
   return binding ? [binding] : [];
 }
 
+function nativeSystemsForEntry(
+  world: ResolvedAdapterRoot,
+  entryModule: unknown,
+): NativeSystemsBinding[] {
+  if (entryModule === undefined || world.adapter.type !== 'builtin') return [];
+  const binding = nativeSystemsBindingFromEntryModule(world.id, entryModule, world.surface);
+  return binding ? [binding] : [];
+}
+
 /**
  * Mount every world declared by a `vgai.project.json` manifest onto `host
  * .container`, resolving each world's kind through the `registerAdapter`
@@ -255,8 +269,9 @@ export async function mountGameFromManifest(
   const manifest = resolveManifest(manifestInput);
   const entries: Record<string, MountEntry> = { ...opts.entries };
   const nativeDebug: NativeDebugBinding[] = [];
+  const nativeSystems: NativeSystemsBinding[] = [];
 
-  for (const world of manifest.roots) {
+  for (const world of declaredRoots(manifest)) {
     if (entries[world.id] !== undefined) continue; // explicit entry always wins
 
     const factory = registry.get(world.adapter.identity);
@@ -266,6 +281,7 @@ export async function mountGameFromManifest(
           ? await host.loadEntryModule(world.entry)
           : undefined;
       nativeDebug.push(...nativeDebugForEntry(world, entryModule));
+      nativeSystems.push(...nativeSystemsForEntry(world, entryModule));
       entries[world.id] = await factory(world, { host, entryModule });
       continue;
     }
@@ -290,5 +306,11 @@ export async function mountGameFromManifest(
     headless: host.headless,
   });
   installNativeDebugBindings(session.game, nativeDebug);
+  installNativeSystemsBindings(session.game, nativeSystems);
+  // The universal instruments are host furniture on EVERY mount path — the
+  // editor installs them in its own bindings pass; the standalone composer
+  // installs them here. The disposer is deliberately dropped: the set's one
+  // resource lives on this Game and dies with it.
+  publishDevInstruments(session.game);
   return session;
 }

package/src/runtime/mount-manifest.ts

@@ -24,6 +24,7 @@
 // `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
 
 import { assertNever } from '../adapter/adapter-surface';
+import { declaredRoots } from '../adapter/manifest-interpreter';
 import type { RootAdapter } from '../adapter/root-adapter';
 // Value-imported from the implementer's OWN path, not the type-only
 // `../adapter` barrel (P-6).
@@ -382,12 +383,13 @@ function buildRootMountSpec(
  */
 export async function mountManifestRoots(opts: MountManifestOptions): Promise<GameSession> {
   const manifest = resolveManifest(opts.manifest);
-  if (manifest.roots.length === 0) {
+  const mountPlan = declaredRoots(manifest);
+  if (mountPlan.length === 0) {
     throw new Error('mountManifestRoots: manifest declares no roots — nothing to mount.');
   }
   const entries = opts.entries ?? {};
 
-  const roots: RootMountSpec[] = manifest.roots.map((world) =>
+  const roots: RootMountSpec[] = mountPlan.map((world) =>
     buildRootMountSpec(world, entries[world.id]),
   );
 

package/src/runtime/types.ts

@@ -299,7 +299,7 @@ export interface EditorPreview {
    *
    * 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` /
+   * DELETED. Hosted dispatch is per-root (`THREE_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

package/src/world3d-react/index.ts

@@ -2,11 +2,8 @@
  * world3d-react — the react-three-fiber bridge for vgai's three surface
  * (`@engine/world3d-react`).
  *
- * 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
+ * An OPT-IN module, mirroring 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).
@@ -14,27 +11,23 @@
  * Peer contract: an importing PROJECT already depends on `react`,
  * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
  * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
- * in the project's Vite config; see `createR3FAdapter`'s header). The engine
- * package deliberately declares no hard dependency on fiber: only projects
- * that already mount through fiber ever import this module.
+ * in the project's Vite config). The engine package deliberately declares no
+ * hard dependency on fiber: only projects that already mount through fiber
+ * ever import this module.
  *
  * Surface:
- *  - `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.
+ *  - `r3fRootFactory` / `resolveR3FEntryAdapter` — what a three entry module
+ *    MEANS: a default-exported component (`export default function World()`),
+ *    mounted as a first-party `kind: "three"` world under the host's gated
+ *    loop. The world's vgai surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host
+ *    at mount.
  *
  * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
- * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
- * world's `@react-three/rapier` physics as the game's
- * `SystemAdapters.physics` — so the colliders instrument and the
- * editor's transform coordination can see it. It imports
+ * (`@engine/world3d-react/rapier-physics-bridge`), which publishes an R3F
+ * world's `@react-three/rapier` physics to the module slot the entry's
+ * `systems.physics` declaration forwards — so the colliders instrument and
+ * the editor's transform coordination can see it. It imports
  * `@react-three/rapier`, and only a world that already depends on that library
  * should pull it into its graph; a deep import keeps this barrel's peer
  * contract to `react`/`@react-three/fiber`/`three` alone.
@@ -46,13 +39,4 @@ export {
   type WorldRendererConfig,
   type WorldToneMapping,
 } from '../adapter/renderer-config';
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
-export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
 export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
-export {
-  createR3FRootContext,
-  DEFAULT_INPUT_MAP_PATH,
-  type R3FGameContext,
-  type R3FRootContextOptions,
-  type R3FRootRuntime,
-} from './world-context';