@vgai/engine 0.5.2 → 0.5.4

package/src/adapter/first-party-systems.ts

@@ -1,60 +1,28 @@
 /**
- * First-party implementations of the remaining `SystemAdapters` — input, assets,
+ * First-party implementations of the remaining `SystemAdapters` — audio and
  * navigation — each a thin coordination/introspection boundary over the real
  * engine subsystem (the original vision named these as first-class System
  * adapters; physics + networking shipped earlier). The editor speaks only the
- * interfaces; these wrap `InputManager`, the asset loader, and `NavMeshManager`
- * so an external game could supply its own equivalents. (The former
+ * interfaces; these wrap the engine audio bus and `NavMeshManager` so an
+ * external game could supply its own equivalents. (The former
  * `AnimationAdapter`/`createAnimationAdapter` over the `AnimGraph` map was
- * removed by E5 — AnimGraph no longer exists; see
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5.)
+ * removed by E5 — AnimGraph no longer exists. The former
+ * `createInputManagerAdapter`/`createVgaiAssetAdapter` went with
+ * `SystemAdapters.input`/`.assets` — registered, never read by anything.)
  */
 
 import type * as THREE from 'three';
 import type { NavMeshManager } from '../ai/navigation';
-import type { InputManager } from '../input/input-manager';
-import { resolveUrl } from '../loader';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import type {
-  ActionValueSnapshot,
-  AssetAdapter,
   AudioAdapter,
-  InputAdapter,
+  AudioGraphNode,
+  AudioMeterFrame,
+  AudioMeterHandle,
   NavigationAdapter,
   NavPoint,
 } from './system-adapter';
 
-/** First-party `InputAdapter` over the engine `InputManager`. Reads each action through
- *  `InputManager.readAction`, dispatched on that action's OWN declared `valueType`
- *  (`getActionValueType`) — never a hardcoded getter — so a scalar/Vector2/pointer action
- *  surfaces its real typed value instead of being coerced through `isPressed` (F1-followup;
- *  `readAction` on the wrong type would throw, so dispatch must follow the declared type). */
-export function createInputManagerAdapter(input: InputManager): InputAdapter {
-  return {
-    poll: () => input.poll(),
-    actions: () => {
-      const out: Record<string, ActionValueSnapshot> = {};
-      for (const name of input.actionNames()) {
-        const type = input.getActionValueType(name);
-        // `readAction`'s return type is inferred from a literal `expectedType`; with `type`
-        // widened to `ActionValueType` here it collapses to `boolean | number | Vector2`, so
-        // digital's `boolean` is normalized to the adapter's 1/0 the same way the old digital-
-        // only adapter did — every other value type already reads as `number | Vector2`.
-        const raw = input.readAction(name, type);
-        out[name] = { type, value: typeof raw === 'boolean' ? (raw ? 1 : 0) : raw };
-      }
-      return out;
-    },
-  };
-}
-
-/** First-party `AssetAdapter` — resolves URLs through the engine loader (which
- *  applies the project base + downloaded-asset remap). External/ingest games can
- *  supply their own to redirect relative paths. */
-export function createVgaiAssetAdapter(): AssetAdapter {
-  return { resolve: (url) => resolveUrl(url) };
-}
-
 /**
  * First-party `AudioAdapter` over the engine's master-gain bus
  * (`setup-audio.ts`'s `AudioContext.masterGain`) — the seam `Game.play.pause()`
@@ -64,10 +32,42 @@ export function createVgaiAssetAdapter(): AssetAdapter {
  * (the editor's `MuteButton`, `PlayBar.tsx`): pausing while already
  * user-muted resumes muted, exactly as a user would expect.
  */
+function audioNodeTypeName(value: object): string {
+  const name = (value as { constructor?: { name?: string } }).constructor?.name;
+  return name && name !== 'Object' ? name : 'AudioNode';
+}
+
+/** This world's real native context, when it has one (headless worlds do not). */
+function nativeAudioContext(audio: GameAudio): (BaseAudioContext & Partial<AudioContext>) | null {
+  const context = (audio.listener as { context?: BaseAudioContext } | undefined)?.context;
+  return context && typeof context.state === 'string'
+    ? (context as BaseAudioContext & Partial<AudioContext>)
+    : null;
+}
+
+/**
+ * Live meter handles per adapter, so a world teardown can release analyser
+ * taps a consumer forgot to dispose.
+ *
+ * This registry follows `acquireMeters` out of `audio-introspection.ts`: the
+ * safety net has to live wherever the taps are created, and they are created
+ * here now. Keyed weakly so an adapter that is simply dropped takes its entry
+ * with it.
+ */
+const meterHandlesByAdapter = new WeakMap<AudioAdapter, Set<AudioMeterHandle>>();
+
+/** Release every meter tap still open on `adapter` (world stop / teardown). */
+export function releaseAudioMeters(adapter: AudioAdapter): void {
+  const handles = meterHandlesByAdapter.get(adapter);
+  if (!handles) return;
+  for (const handle of [...handles]) handle.dispose();
+}
+
 export function createAudioSystemAdapter(audio: GameAudio): AudioAdapter {
   let muted = false;
   let priorGain = audio.masterGain.gain.value;
-  return {
+  const liveMeterHandles = new Set<AudioMeterHandle>();
+  const adapter: AudioAdapter = {
     resume: () => audio.resume(),
     setMuted(next: boolean) {
       if (next === muted) return;
@@ -80,7 +80,121 @@ export function createAudioSystemAdapter(audio: GameAudio): AudioAdapter {
       }
     },
     isMuted: () => muted,
+
+    /**
+     * The engine's own bus hierarchy.
+     *
+     * This lived in `audio-introspection.ts` — the Tone-backed module — which
+     * meant the editor could only ever show an audio graph for a game that had
+     * loaded Tone. Nothing here needs Tone: it is the destination, the master
+     * gain, the three engine buses and the THREE listener. The Tone half (nodes
+     * a game routed through `connectToneBusToMasterGain`) is APPENDED by that
+     * module when it attaches, which is the honest split — Tone routes are
+     * Tone's to report.
+     */
+    graphSnapshot(): AudioGraphNode[] {
+      const contextState = nativeAudioContext(audio)?.state;
+      const destination: AudioGraphNode = {
+        id: 'destination',
+        type: 'AudioDestinationNode',
+        label: 'Output',
+        outputs: [],
+      };
+      if (contextState !== undefined) destination.state = contextState;
+      const nodes: AudioGraphNode[] = [
+        destination,
+        {
+          id: 'master',
+          type: audioNodeTypeName(audio.masterGain),
+          label: 'Master',
+          outputs: ['destination'],
+        },
+        {
+          id: 'bus-music',
+          type: audioNodeTypeName(audio.buses.music),
+          label: 'Music bus',
+          outputs: ['master'],
+        },
+        {
+          id: 'bus-sfx',
+          type: audioNodeTypeName(audio.buses.sfx),
+          label: 'SFX bus',
+          outputs: ['master'],
+        },
+        {
+          id: 'bus-voice',
+          type: audioNodeTypeName(audio.buses.voice),
+          label: 'Voice bus',
+          outputs: ['master'],
+        },
+      ];
+      if (audio.listener) {
+        nodes.push({
+          id: 'listener',
+          type: audioNodeTypeName(audio.listener),
+          label: '3D listener (THREE)',
+          outputs: ['master'],
+        });
+      }
+      return nodes;
+    },
+
+    /**
+     * Per-bus linear-RMS levels, via native `AnalyserNode` taps.
+     *
+     * Zero Tone — analysers work identically whether or not Tone is bridged,
+     * and disposal is a plain disconnect. It was in the Tone module purely by
+     * where it was written, so a game that never touches Tone had no meters.
+     */
+    acquireMeters(): AudioMeterHandle | null {
+      const meterContext = nativeAudioContext(audio);
+      if (!meterContext || typeof meterContext.createAnalyser !== 'function') {
+        return null; // headless world — metering is impossible, and says so
+      }
+      const taps = (
+        [
+          ['master', 'Master', audio.masterGain],
+          ['bus-music', 'Music', audio.buses.music],
+          ['bus-sfx', 'SFX', audio.buses.sfx],
+          ['bus-voice', 'Voice', audio.buses.voice],
+        ] as const
+      ).map(([id, label, gain]) => {
+        const analyser = meterContext.createAnalyser();
+        analyser.fftSize = 1024;
+        gain.connect(analyser); // a TAP (analyser is a sink), not an insert
+        return { id, label, gain, analyser, buffer: new Float32Array(analyser.fftSize) };
+      });
+      let disposed = false;
+      const handle: AudioMeterHandle = {
+        read: (): AudioMeterFrame[] =>
+          taps.map(({ id, label, analyser, buffer }) => {
+            analyser.getFloatTimeDomainData(buffer);
+            let sum = 0;
+            for (let i = 0; i < buffer.length; i++) {
+              const sample = buffer[i] as number;
+              sum += sample * sample;
+            }
+            return { id, label, level: Math.sqrt(sum / buffer.length) };
+          }),
+        dispose: (): void => {
+          if (disposed) return;
+          disposed = true;
+          for (const tap of taps) {
+            try {
+              tap.gain.disconnect(tap.analyser);
+            } catch {
+              // already torn down with the context — nothing to release
+            }
+          }
+          liveMeterHandles.delete(handle);
+        },
+      };
+      liveMeterHandles.add(handle);
+      return handle;
+    },
   };
+  meterHandlesByAdapter.set(adapter, liveMeterHandles);
+  return adapter;
 }
 
 /** First-party `NavigationAdapter` over the engine `NavMeshManager` — the

package/src/adapter/host-context.ts

@@ -1,22 +1,87 @@
 /**
- * HostContext — the NEUTRAL primitives the host hands a game when mounting it.
+ * Host contexts — what the host hands a root when it mounts it, PER SURFACE.
  *
  * This generalizes the old `GameContext`, which baked in first-party system
  * choices (a Rapier world, the postprocessing composer, the InputManager, …).
- * `HostContext` provides only what ANY game needs — the shared three instance, a
- * surface, a renderer, a loop, and assets — and lets a game *ask* for
- * a first-party subsystem via `requestSystem`, which the host may or may not
- * supply. The host never assumes Rapier/Colyseus; those live behind
- * `SystemAdapters` owned by the first-party implementer.
- *
- * Migration note: `VgaiSceneGameAdapter.mount` builds today's `GameContext`
- * (Rapier world, composer, …) internally from a `HostContext`. New code targets
- * `HostContext`; `GameContext` is now a first-party implementation detail.
+ * The host never assumes Rapier/Colyseus; those live behind `SystemAdapters`
+ * owned by the first-party implementer.
+ *
+ * ## Why this file is a family, not one interface (P-8)
+ *
+ * There used to be a single "neutral" `HostContext` interface handed to EVERY
+ * root, with a NON-OPTIONAL `three: typeof THREE` and `renderer:
+ * THREE.WebGLRenderer` on it. That made the neutral layer three-LOCKED rather
+ * than merely three-named: a Pixi or React root would have been handed a WebGL
+ * renderer it cannot use. In practice nobody did hand it one — the production
+ * Pixi and React hosts have always built their own canvas/dom-shaped contexts
+ * instead — so the "one context for every surface"
+ * claim was already false in the tree; it just wasn't expressed in the types,
+ * which is why `RootAdapter<K>` could only parameterize its RETURN type and
+ * the Pixi/React adapters lived outside `RootAdapter` entirely.
+ *
+ * The split (ratified, docs/ARCHITECTURE-CORE.md "Seam"):
+ *
+ *   {@link HostContextBase}   what EVERY surface genuinely gets
+ *     ├─ {@link ThreeHostContext}   + `three` · `renderer` · `surface` · `assets`
+ *     ├─ {@link CanvasHostContext}  + `canvas`/`width`/`height` (+ dpr/compositing hints)
+ *     └─ {@link DomHostContext}     + `container`
+ *
+ * and {@link HostContextFor} maps an `AdapterSurface` to its context, so
+ * `RootAdapter<K>.mount`'s PARAMETER is K-typed too — the surface tag now
+ * picks the context type, which is the whole point of the tag.
+ *
+ * ### Where the line was drawn, and why
+ *
+ * The base holds exactly the members all three surfaces ALREADY carry today —
+ * nothing was invented to make the base look richer:
+ *
+ *  - `game` — the root handle. Every surface has one (three: `ThreeHostContext.game`,
+ *    canvas: `CanvasHostContext.game`, dom: `DomHostContext.game`), and it is the one
+ *    genuinely surface-independent thing a host can hand any root.
+ *  - `headless` — a property of the ENVIRONMENT (no GPU/DOM/audio), not of the
+ *    render surface.
+ *
+ * Deliberately NOT in the base:
+ *
+ *  - `renderer`/`three` — three's own objects; the defect this split exists to
+ *    fix.
+ *  - the render surface — its SHAPE is surface-specific and there is no honest
+ *    common denominator: three nests `{canvas,width,height}` under `surface`,
+ *    canvas passes those three flat (plus its own compositing hints), and a DOM
+ *    root gets an `HTMLElement` container and no canvas at all. A shared
+ *    `surface` field would have to be a union nobody can consume without
+ *    re-branching on kind — i.e. the same three-shaped promise, one level down.
+ *  - `assets` — `AssetCache`'s SIGNATURE reads neutral (`load<T>(url)`), but its
+ *    one implementation is a GLTF/texture loader (`assets.ts` branches on
+ *    `.glb`/`.gltf` and resolves THREE objects), and neither the canvas nor the
+ *    dom host has ever been handed one: a canvas adapter builds its own
+ *    cache inside `mount`. Promoting it to the base would be the anti-shim rule
+ *    in miniature — a host promise nothing keeps. It stays on
+ *    {@link ThreeHostContext} until a second surface genuinely receives one.
+ *
+ * These three names are the ONLY names for these shapes. The transitional
+ * aliases that carried the pre-split spellings were deleted; every implementer
+ * and call site names the surface it actually mounts on.
+ *
+ * It also used to carry `requestSystem<T extends keyof SystemRegistry>()` — an
+ * "ask the host for a first-party subsystem" hook — over an EMPTY
+ * `SystemRegistry`. That made `keyof SystemRegistry` = `never`, so no argument
+ * could legally be passed and the method was uncallable by construction. In
+ * practice it existed as 28 copies of `requestSystem: () => null` in tests and
+ * hosts, with no caller anywhere, and its only real effect would have been to
+ * re-open the door this interface exists to close: the host handing a game a
+ * subsystem it did not build. Deleted rather than kept as a promise.
+ *
+ * Migration note: `SetupThreeRootAdapter.mount` builds today's `GameContext`
+ * (Rapier world, composer, …) internally from a `ThreeHostContext`. New code
+ * targets these contexts; `GameContext` is now a first-party implementation
+ * detail.
  */
 
 import type * as THREE from 'three';
 import type { AssetCache } from '../assets';
-import type { GameInternal } from '../runtime/game';
+import type { Game, GameInternal } from '../runtime/game';
+import type { AdapterSurface } from './adapter-surface';
 
 /** The canvas/container the game renders into, plus its size. */
 export interface HostSurface {
@@ -25,51 +90,117 @@ export interface HostSurface {
   readonly height: number;
 }
 
-/** Host-owned scheduling. A game may register extra per-frame callbacks; the
- *  host owns when they run. (First-party ticks its own system runner inside
- *  `MountedGame.update`, so it does not need this — it exists for games that
- *  want to hook the host loop directly.) */
-export interface LoopHandle {
-  /** Register a per-frame callback; returns an unregister fn. */
-  onUpdate(fn: (dt: number) => void): () => void;
+/**
+ * The surface-INDEPENDENT half of every host context — see this file's header
+ * for why only these two members earned a place here. Generic host code (a
+ * harness, a tier report, anything that must not care what it is mounting) can
+ * type against this; a real adapter always receives one of the per-surface
+ * contexts below.
+ */
+export interface HostContextBase {
+  /**
+   * The Game root (T7.1 slice 1 — D6). The host
+   * constructs the Game shell BEFORE mounting an adapter and hands it down
+   * here so an adapter can expose `ctx.game`/`ctx.roots` to the game it
+   * mounts. Absent in headless harnesses and foreign hosts that predate the
+   * Game root — everything must keep working when this is undefined (the
+   * zero-break guarantee for this slice). Typed as the PUBLIC `Game` shell
+   * here because that is the weakest promise any surface makes (a react
+   * root's host has always carried a plain `Game`); the three and canvas
+   * contexts narrow it to `GameInternal`, which is what their hosts really
+   * pass.
+   */
+  readonly game?: Game | undefined;
+  /**
+   * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
+   * skips postprocessing/render/audio/input-map loading but still builds the
+   * scene + Rapier + components, so its scene/authoring/physics can be exercised
+   * headlessly. Browser hosts leave this false/undefined → full behavior.
+   */
+  readonly headless?: boolean;
 }
 
 /**
- * First-party subsystems a game MAY request from the host. The host returns
- * `null` when it does not provide the kind, so a game must tolerate absence —
- * the host never forces a subsystem on a game. Extended as new first-party
- * systems become host-provisioned.
+ * What a `three`-surface root is handed. This is the ONLY context carrying
+ * three's own objects — the split's entire point (see the header): a Pixi or
+ * React root is never handed a `WebGLRenderer` it cannot use.
  */
-// biome-ignore lint/suspicious/noEmptyInterface: extended by first-party host wiring as systems become provisionable
-export interface SystemRegistry {}
-
-export interface HostContext {
+export interface ThreeHostContext extends HostContextBase {
   /** The ONE shared three instance — identity matters for capture (see ingest). */
   readonly three: typeof THREE;
   /** Canvas/container + size; a self-driven game may take the surface over. */
   readonly surface: HostSurface;
   /** Host renderer — host-driven games render through it. */
   readonly renderer: THREE.WebGLRenderer;
-  /** Host-owned loop scheduling. */
-  readonly loop: LoopHandle;
-  /** Shared GLTF/texture cache. */
+  /** Shared GLTF/texture cache — three-flavored today; see the header. */
   readonly assets: AssetCache;
-  /**
-   * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
-   * skips postprocessing/render/audio/input-map loading but still builds the
-   * scene + Rapier + components, so its scene/authoring/physics can be exercised
-   * headlessly. Browser hosts leave this false/undefined → full behavior.
-   */
-  readonly headless?: boolean;
-  /** Ask the host for a first-party subsystem; `null` if not provided. */
-  requestSystem<T extends keyof SystemRegistry>(kind: T): SystemRegistry[T] | null;
-  /**
-   * The Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6). The host
-   * constructs the Game shell BEFORE mounting a `GameAdapter` and hands it
-   * down here so an adapter can expose `ctx.game`/`ctx.roots` to the game it
-   * mounts. Absent in headless harnesses and foreign hosts that predate the
-   * Game root — everything must keep working when this is undefined (the
-   * zero-break guarantee for this slice).
-   */
   readonly game?: GameInternal | undefined;
 }
+
+/**
+ * What a `canvas`-surface root is handed: a raw canvas + its
+ * logical size, plus the
+ * compositing hints the multi-root host computes once for every stacked
+ * surface. No `three`, no `renderer`, no `assets` — a Pixi root builds its own
+ * `PIXI.Application` and its own asset cache from this.
+ */
+export interface CanvasHostContext extends HostContextBase {
+  readonly canvas: HTMLCanvasElement;
+  readonly width: number;
+  readonly height: number;
+  /** Shared Game root when mounted by the universal multi-root host. */
+  readonly game?: GameInternal | undefined;
+  /** DPR override (T6.1 slice 1, D5 §3 — "one DPR
+   *  everywhere"): the roots-path host computes ONE dpr for every stacked
+   *  surface and passes it here; omitted -> the canvas adapter's own
+   *  default (`window.devicePixelRatio`, uncapped). */
+  readonly dpr?: number;
+  /** This root is stacked ABOVE another root (D5 §1): clear with alpha 0
+   *  instead of an opaque background so the layer below shows through. */
+  readonly transparent?: boolean;
+  /** Capture tier cost (D5 §4) — the renderer's `preserveDrawingBuffer`. */
+  readonly preserveDrawingBuffer?: boolean;
+}
+
+/**
+ * What a `dom`-surface root is handed (the shape `runtime/create-runtime.ts`
+ * used to spell `ReactRootHost`).
+ *
+ * `container` is the absolutely-positioned, z-ordered DOM-root layer `<div>`
+ * the host already created and stacked (same box/z-order rules as a canvas per
+ * D5 §1) — the adapter's `mount` renders its react tree INTO
+ * this exact element via `createRoot`; it must never create its own root
+ * element (the DOM analog of three's "the root's runtime renders into the
+ * surface it is handed" rule).
+ *
+ * `game` (inherited, and deliberately still optional): a
+ * `default-react` sibling mounted BESIDE an ingest root (`packages/editor/src/
+ * ingest-siblings.ts`) has no native `Game` to hand it — there is no
+ * first-party `GameContext`/loop for the sibling to join, only the ingested
+ * root's own foreign runtime — so its host carries no `game` at all rather than
+ * fabricating an empty one (anti-shim rule); the sibling mounts its entry
+ * component bare, with no `<WorldProvider>` wrap. `mountOneReactRoot`
+ * (`runtime/create-runtime.ts`, the NATIVE multi-root runtime path) still
+ * ALWAYS supplies a real `game` — this optionality is reached only by the
+ * composite sibling's own hand-built host, never by weakening the native path's
+ * guarantee.
+ */
+export interface DomHostContext extends HostContextBase {
+  readonly container: HTMLElement;
+}
+
+/**
+ * Map an {@link AdapterSurface} to the host context that surface's roots are
+ * handed — the mirror image of `MountedRootFor<K>` (`root-adapter.ts`), and
+ * what makes `RootAdapter<K>.mount`'s PARAMETER K-typed. A hypothetical 4th
+ * surface resolves to `never` here, so it cannot be mounted until it declares
+ * its own context (the same fail-to-compile discipline `assertNever` gives the
+ * dispatch sites).
+ */
+export type HostContextFor<K extends AdapterSurface> = K extends 'three'
+  ? ThreeHostContext
+  : K extends 'canvas'
+    ? CanvasHostContext
+    : K extends 'dom'
+      ? DomHostContext
+      : never;

package/src/adapter/index.ts

@@ -1,38 +1,49 @@
 /**
  * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
  *
- *   host    → GameAdapter ← { VgaiSceneGameAdapter, IngestGameAdapter, … }
- *   editor  → AuthoringAdapter ← { VgaiSceneAuthoringAdapter, IngestAuthoringAdapter, … }
- *   game    → SystemAdapters (physics/networking/input/assets)
+ *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
+ *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/navigation/audio/debug)
  *
- * The first-party `.vscn`/`GameComponent`/Rapier/Colyseus stack is ONE
- * implementer of these interfaces, not the engine's vocabulary. See
- * docs/ADAPTER-ARCHITECTURE.md.
+ * The first-party Rapier/Colyseus stack is ONE implementer of these
+ * interfaces, not the engine's vocabulary..
+ *
+ * **This module is TYPE-ONLY, and must stay that way (P-6).** It used to
+ * value-export its own implementers — `SetupThreeRootAdapter`/`fromSetup`,
+ * `createRapierPhysicsAdapter`, `createColyseusNetworkingAdapter`,
+ * `createNavigationAdapter` — so `import type { AuthoringAdapter } from
+ * '@engine/adapter'` was the only thing keeping the three/Rapier/Colyseus/
+ * `.vscn` stack out of a Pixi or React consumer's module graph. A seam that
+ * ships its implementers is not a seam. Import an implementer from its OWN
+ * path instead:
+ *
+ *   `@engine/adapter/setup-three-root-adapter`   SetupThreeRootAdapter, fromSetup
+ *   `@engine/adapter/rapier-physics-adapter`    createRapierPhysicsAdapter
+ *   `@engine/adapter/colyseus-networking-adapter` createColyseusNetworkingAdapter
+ *   `@engine/adapter/first-party-systems`       createNavigationAdapter
  */
 
 export type { AdapterSurface } from './adapter-surface';
 export type {
+  AssetDropContext,
   AssetDropProvider,
+  AssetSubjectProvider,
   AuthoringAdapter,
+  AuthoringAssetSubject,
   AuthoringCapabilities,
   AuthoringProvenance,
   BoxEditProvider,
   BoxEditReferencePoint,
   ColorSampleProvider,
-  ComponentsProvider,
+  CreationSiteProvider,
   DOMRectLike,
   EditorNode,
   EditorNodeRole,
-  EntityAssetProvider,
-  EntityAssetSaveDescriptor,
   FileMapProvider,
   HierarchyProvider,
   InspectorProvider,
-  LayoutProvider,
+  NodeCreationSite,
   PersistenceProvider,
-  PhysicsShape2DHandle,
-  PhysicsShape2DProjection,
-  PhysicsShape2DProvider,
   PickProvider,
   PropertyDescriptor,
   RectProvider,
@@ -40,46 +51,37 @@ export type {
   RootGroupsProvider,
   SelectionProvider,
   SelectionResolution,
-  SpriteAtlas2D,
-  SpriteAtlasFrame2D,
-  SpriteFrames2DDescriptor,
-  SpriteFrames2DProvider,
   StoriesProvider,
   StoryRef,
   StructureProvider,
   TextProvider,
-  TilemapCell,
-  TilemapEditGrid,
-  TilemapEditProvider,
   TransformChannel,
   TransformEditability,
+  TransformObservation,
   TransformProvider,
 } from './authoring';
-export {
-  type ColyseusNetworkingConfig,
-  createColyseusNetworkingAdapter,
-} from './colyseus-networking-adapter';
-export {
-  createInputManagerAdapter,
-  createNavigationAdapter,
-  createVgaiAssetAdapter,
-} from './first-party-systems';
+export type { ColyseusNetworkingConfig } from './colyseus-networking-adapter';
+export type {
+  CanvasHostContext,
+  DomHostContext,
+  HostContextBase,
+  HostContextFor,
+  HostSurface,
+  ThreeHostContext,
+} from './host-context';
 export type {
-  GameAdapter,
-  MountedGame,
-  MountedPixiWorld,
-  MountedReactWorld,
-  MountedThreeWorld,
-  MountedWorld,
-  MountedWorldBase,
-  MountedWorldFor,
-  WorldStateObserver,
-} from './game-adapter';
-export type { HostContext, HostSurface, LoopHandle, SystemRegistry } from './host-context';
-export { createRapierPhysicsAdapter } from './rapier-physics-adapter';
+  MountedPixiRoot,
+  MountedReactRoot,
+  MountedRoot,
+  MountedRootBase,
+  MountedThreeRoot,
+  RootAdapter,
+  RootStateObserver,
+  SurfaceAdapter,
+  SurfaceAdapterFor,
+} from './root-adapter';
+export type { MountedSetupThreeRoot, SetupThreeRootConfig } from './setup-three-root-adapter';
 export type {
-  ActionValueSnapshot,
-  AssetAdapter,
   AudioAdapter,
   AudioDebugEvent,
   AudioGraphNode,
@@ -87,15 +89,15 @@ export type {
   AudioMeterHandle,
   AudioTransportState,
   ConnectionState,
-  InputAdapter,
-  NavBakeParams,
   NavCrowdAgentState,
   NavigationAdapter,
   NavPoint,
   NetConditioning,
   NetMessageEvent,
   NetPeer,
+  NetPlayerIdentity,
   NetRates,
+  NetServerConfig,
   NetworkingAdapter,
   PhysicsAdapter,
   RenderDebugAdapter,
@@ -105,9 +107,3 @@ export type {
   Unsubscribe,
 } from './system-adapter';
 export type { Transform, TransformOwner } from './transform';
-export {
-  fromSetup,
-  type VgaiMountedGame,
-  type VgaiSceneConfig,
-  VgaiSceneGameAdapter,
-} from './vgai-scene-game-adapter';

package/src/adapter/ingest/game-contract.ts

@@ -10,12 +10,12 @@
  *
  * Relationship to the native engine: first-party content implements the SAME
  * conceptual surface (mount root, lifecycle, loop gating) through
- * `GameAdapter`/`MountedGame` — the native engine is the premade 100%
+ * `RootAdapter`/`MountedThreeRoot` — the native engine is the premade 100%
  * implementation of this contract. An ingested game climbs the same ladder
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin: docs/FTUE-EXTERNAL-R3F-GAME.md F16 (root), F17+F21 (lifecycle).
+ * Origin (root), F17+F21 (lifecycle).
  */
 
 /**