@vgai/engine 0.5.2 → 0.5.4

package/src/adapter/ingest/scene-capture.ts

@@ -24,29 +24,28 @@
  * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
  * three`), an external ESM game's `import 'three'` resolves to that one instance,
  * so passing the host's `THREE` here traps the game's renderer too. A game that
- * bundles its own copy of `three` cannot be captured this way (see
- * `docs/UNMODIFIED-GAME-INGESTION-STUDY.md` §4A — the module-identity gatekeeper).
+ * bundles its own copy of `three` cannot be captured this way (the module-identity
+ * gatekeeper).
  *
- * Wave 17 (`docs/WAVE17-F13-COMPOSER-RESIZE-FIX-DESIGN.md`) adds an OPTIONAL,
- * ADDITIVE composer capture: a game rendering through its own three.js addon
- * `EffectComposer` (`three/examples/jsm/postprocessing/EffectComposer.js`)
- * still trips the `render` trap above (its `RenderPass` calls
- * `renderer.render(scene,camera)` internally), but the renderer holds no
- * reference back to the composer, so the host previously could not resize the
- * composer's own (intentionally non-1:1, progressively-downsampled — see
- * `UnrealBloomPass`) render targets when the host resizes the game's pane.
- * Unlike `WebGLRenderer`, `EffectComposer` is a plain ES class whose methods
- * (including `render`) live on the PROTOTYPE, not assigned as own instance
- * properties in the constructor — so a direct method-wrapper (no getter/
- * setter indirection) on `EffectComposer.prototype.render` is sufficient: it
- * calls through to the real `render`, then — AFTER that call, so any nested
+ * Wave 17 adds an OPTIONAL, ADDITIVE composer capture: a game rendering through
+ * its own three.js addon `EffectComposer`
+ * (`three/examples/jsm/postprocessing/EffectComposer.js`) still trips the `render`
+ * trap above (its `RenderPass` calls `renderer.render(scene,camera)` internally),
+ * but the renderer holds no reference back to the composer, so the host previously
+ * could not resize the composer's own (intentionally non-1:1,
+ * progressively-downsampled — see `UnrealBloomPass`) render targets when the host
+ * resizes the game's pane. Unlike `WebGLRenderer`, `EffectComposer` is a plain ES
+ * class whose methods (including `render`) live on the PROTOTYPE, not assigned as
+ * own instance properties in the constructor — so a direct method-wrapper (no
+ * getter/ setter indirection) on `EffectComposer.prototype.render` is sufficient:
+ * it calls through to the real `render`, then — AFTER that call, so any nested
  * `renderer.render()` the pass makes has already hit the trap above and set
- * `captured` — records `this` (the composer instance) if its `.renderer` is
- * the captured one. This is deduped/shared-trappable for the same reason
+ * `captured` — records `this` (the composer instance) if its `.renderer` is the
+ * captured one. This is deduped/shared-trappable for the same reason
  * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
  * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
- * instance — not a separate package with its own dedupe question. Proven
- * live against the `bloom-composer` fixture
+ * instance — not a separate package with its own dedupe question. Proven live
+ * against the `bloom-composer` fixture
  * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
  */
 

package/src/adapter/ingest/structural-ids.ts

@@ -0,0 +1,127 @@
+/**
+ * Structural identity — the deterministic id scheme (and the small material
+ * reflection helper that rides along with it) the editor's live-three authoring
+ * adapter uses to address the objects of a world whose source carries no
+ * serve-time identity stamps
+ * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ *
+ * Identity: each object gets a **structural-path id** — deterministic from the
+ * scene's shape (position in the tree + three.js type + name), so the SAME id
+ * re-binds to the SAME object after the game rebuilds its scene within a
+ * session. It is also written to `userData.entityId` so the editor's object map
+ * / gizmo / selection (which key on `entityId`) bind to foreign objects with no
+ * further shim.
+ *
+ * This module used to be the shared core of a per-game JSON sidecar
+ * persistence system, which was deleted outright (2026-08-02) — ingest edits
+ * are LIVE-ONLY now. The id scheme survives because it is what makes the live
+ * hierarchy/selection/inspector work at all; nothing here reads or writes a
+ * file.
+ */
+
+import type * as THREE from 'three';
+import { setUserData } from '../../ecs/user-data';
+
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export const CAMERA_ID = 'ingest:camera';
+
+/**
+ * The editor parks its OWN objects — grid, its two lights, the particle
+ * BatchedRenderer, every TransformControls/gizmo helper — on layer 31
+ * (`packages/editor/src/editor-layers.ts`'s `EDITOR_LAYER`) so the game camera
+ * never sees them. In ingest mode those objects are added to the GAME'S OWN
+ * scene, which is the same tree this walk indexes.
+ */
+const EDITOR_ONLY_LAYER_MASK = 1 << 31;
+
+/**
+ * Editor furniture, not game content. Excluded from the walk entirely — see
+ * {@link assignStructuralIds} for why that exclusion is what makes the id
+ * scheme's central promise true.
+ */
+function isEditorOnly(o: THREE.Object3D): boolean {
+  return (o.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0;
+}
+
+/**
+ * The material whose colour a mesh's swatch reflects, if it has one.
+ *
+ * A multi-material mesh reflects its FIRST slot — that is what a single swatch
+ * can honestly stand for, and it is also the slot a creation-site anchor for
+ * `material.color` resolves against. Returns `null` for anything with no
+ * `color` at all rather than fabricating one.
+ */
+export function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null {
+  const mat = (o as THREE.Mesh).material;
+  if (!mat) return null;
+  const m = (Array.isArray(mat) ? mat[0] : mat) as THREE.MeshStandardMaterial | undefined;
+  return m?.color ? m : null;
+}
+
+/** Result of a structural-path walk: the id→object map plus a few reflection stats. */
+export interface StructuralIdWalk {
+  byId: Map<string, THREE.Object3D>;
+  count: number;
+  meshes: number;
+  lights: number;
+}
+
+/**
+ * (Re)assign structural-path ids to every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — so a re-walk after the game rebuilds part of its
+ * tree re-binds the same ids to the same objects.
+ *
+ * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
+ * cosmetic. In ingest mode the editor adds its grid, lights, particle
+ * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
+ * they arrive asynchronously — some before the walk, some after. Indexing them
+ * made a game object's path depend on how much editor furniture happened to be
+ * attached at walk time, so the same mesh changed id across a re-walk (observed
+ * in the games-fps ingest: an object addressed as `ingest:106/0/0/0:…` came
+ * back as `ingest:102/0:Mesh:Cube004` — four root slots earlier, exactly the
+ * grid + two editor lights + BatchedRenderer).
+ *
+ * Skipping the furniture entirely — not merely declining to give it an id —
+ * is what fixes that: the game's own children occupy 0..N-1 whatever else is
+ * parented alongside them. It also keeps gizmo handles and the grid out of the
+ * hierarchy/inspector projections built on this walk, where they were
+ * selectable and colorable as if they were game content.
+ */
+export function assignStructuralIds(
+  scene: THREE.Object3D,
+  camera?: THREE.Object3D | undefined,
+): StructuralIdWalk {
+  const byId = new Map<string, THREE.Object3D>();
+  let count = 0;
+  let meshes = 0;
+  let lights = 0;
+  const visit = (
+    o: THREE.Object3D & { isMesh?: boolean; isLight?: boolean },
+    path: string,
+  ): void => {
+    const id = `ingest:${path}:${o.type}:${o.name || ''}`;
+    setUserData(o, 'entityId', id);
+    byId.set(id, o);
+    count++;
+    if (o.isLight) lights++;
+    else if (o.isMesh) meshes++;
+    visitChildren(o, path);
+  };
+  const visitChildren = (o: THREE.Object3D, path: string): void => {
+    let i = 0;
+    for (const c of o.children) {
+      if (isEditorOnly(c)) continue;
+      visit(c, path ? `${path}/${i}` : `${i}`);
+      i++;
+    }
+  };
+  visitChildren(scene, '');
+  if (camera) {
+    setUserData(camera, 'entityId', CAMERA_ID);
+    byId.set(CAMERA_ID, camera);
+    count++;
+  }
+  return { byId, count, meshes, lights };
+}

package/src/adapter/ingest/upstream-pin.ts

@@ -1,16 +1,13 @@
 /**
- * Upstream-pin extraction — R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/
- * §7.1 item 9): the fix for the overlay identity gap the structural-id +
- * `authoredAgainst.gameVersion` scheme (T7.7/D9) does not close. A re-vendor
- * of a vendored upstream game that keeps a slot's shape (index + three.js
- * type + name unchanged) reapplies a saved overlay onto a semantically
- * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning
- * success — because `authoredAgainst.gameVersion` is the MANIFEST's own
- * `version` (hand-set by whoever wrote `vgai.game.json`, e.g. every
- * `public/ingest/*` vendored game ships `"version": "0.1.0"` regardless of
- * which upstream commit it vendors — see `public/ingest/{tanks,racing-game,
- * simcity}/vgai.game.json`), never tied to the thing that actually changes on
- * a re-vendor: the `UPSTREAM.md` pin.
+ * Upstream-pin extraction — R5 ((c)/ §7.1 item 9): the fix for the overlay identity
+ * gap the structural-id + `authoredAgainst.gameVersion` scheme (T7.7/D9) does not
+ * close. A re-vendor of a vendored upstream game that keeps a slot's shape (index +
+ * three.js type + name unchanged) reapplies a saved overlay onto a semantically
+ * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning success
+ * — because `authoredAgainst.gameVersion` is the MANIFEST's own `version` (hand-set
+ * by whoever wrote the ingest manifest, e.g. every `public/ingest/*` vendored game
+ * ships `"version": "0.1.0"` regardless of which upstream commit it vendors), never
+ * tied to the thing that actually changes on a re-vendor: the `UPSTREAM.md` pin.
  *
  * This module is the pure, dependency-free half (parse text -> pin, or
  * `null`): NO file I/O here, so it is usable from any context (editor

package/src/adapter/loop-gate-report.ts

@@ -1,14 +1,14 @@
 /**
  * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
- * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
- * (`gated | self-driven`) as independent of capability tier: a `self-driven`
- * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
- * its adapter implements an explicit loop-gate capability
- * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
- * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
- * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
- * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
- * silence a world's audio on pause must report, not pretend.
+ * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) as
+ * independent of capability tier: a `self-driven` world (an ingested game
+ * driving its own rAF/ticker) pauses for real ONLY if its adapter implements an
+ * explicit loop-gate capability (`MountedRootBase.setPaused`/`step`) —
+ * otherwise it "honestly reports so" rather than a silent no-op (the
+ * D5 §5.2 finding: gating a raw-rAF loop from outside was
+ * demonstrated and REJECTED). The audio seam (`SystemAdapters.AudioAdapter`)
+ * has the identical shape: absent or unable to silence a world's audio on pause
+ * must report, not pretend.
  *
  * Pure compute + message-formatting, same split as `achieved-tier.ts`
  * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
@@ -36,8 +36,8 @@ function formatGateMessage(
 ): string {
   return (
     `${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
-    `(${report.reason}) — reporting honestly instead of silently no-op-ing ` +
-    `(docs/CAPABILITY-TIERS.md §d). ${prefix} ${JSON.stringify(report)}`
+    `(${report.reason}) — reporting honestly instead of silently no-op-ing. ` +
+    `${prefix} ${JSON.stringify(report)}`
   );
 }
 

package/src/adapter/rapier-physics-adapter.ts

@@ -4,6 +4,11 @@
  * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
  * the editor freeze a body, apply a gizmo edit, and resume — without the editor
  * knowing Rapier exists.
+ *
+ * The seam is keyed by NODE ID (P-4), so THIS is where the three-specific
+ * `id → Object3D` step happens: once, at the implementer's own boundary,
+ * through the `resolve` function its constructor is handed. Nothing above this
+ * line — not the editor, not the seam — needs to know an `Object3D` exists.
  */
 
 import type RAPIER from '@dimforge/rapier3d-compat';
@@ -15,7 +20,14 @@ import type { Transform, TransformOwner } from './transform';
 
 export function createRapierPhysicsAdapter(
   registry: PhysicsRegistry,
-  physics?: PhysicsContext | null,
+  physics: PhysicsContext | null | undefined,
+  /**
+   * The world's own `id → Object3D` map. Injected rather than derived here so
+   * this file never hard-codes an identity convention (e.g. reading the
+   * first-party `userData.entityId` key off foreign objects, which is the
+   * ingest-stamping leak the retirement playbook deliberately parked).
+   */
+  resolve: (nodeId: string) => THREE.Object3D | null,
 ): PhysicsAdapter {
   /** Saved body types while frozen, so unfreeze can restore them. */
   const frozen = new Map<RAPIER.RigidBody, number>();
@@ -64,22 +76,28 @@ export function createRapierPhysicsAdapter(
     return contactBuf.subarray(0, contactCount * 3);
   };
 
+  /** The one place this adapter crosses from node id into Three's vocabulary. */
+  const bodyFor = (nodeId: string): RAPIER.RigidBody | undefined => {
+    const o = resolve(nodeId);
+    return o ? registry.get(o)?.body : undefined;
+  };
+
   return {
-    ownerOf(o: THREE.Object3D): TransformOwner {
-      const body = registry.get(o)?.body;
+    ownerOf(nodeId: string): TransformOwner {
+      const body = bodyFor(nodeId);
       if (!body) return 'editor';
       // A fixed body never moves on its own → the editor owns its transform.
       return body.isFixed() ? 'editor' : 'physics';
     },
-    freeze(o: THREE.Object3D): void {
-      const body = registry.get(o)?.body;
+    freeze(nodeId: string): void {
+      const body = bodyFor(nodeId);
       if (!body || frozen.has(body)) return;
       frozen.set(body, body.bodyType());
       // Kinematic-position: the body stops simulating but tracks the pose we set.
       body.setBodyType(2 /* KinematicPositionBased */, true);
     },
-    commit(o: THREE.Object3D, t: Transform): void {
-      const body = registry.get(o)?.body;
+    commit(nodeId: string, t: Transform): void {
+      const body = bodyFor(nodeId);
       if (!body) return;
       body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
       body.setRotation(
@@ -87,8 +105,8 @@ export function createRapierPhysicsAdapter(
         true,
       );
     },
-    unfreeze(o: THREE.Object3D): void {
-      const body = registry.get(o)?.body;
+    unfreeze(nodeId: string): void {
+      const body = bodyFor(nodeId);
       if (!body) return;
       const prev = frozen.get(body);
       if (prev !== undefined) {

package/src/adapter/root-adapter.ts

@@ -0,0 +1,217 @@
+/**
+ * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
+ *
+ * This is the interface the HOST depends on. It replaces the old
+ * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`
+ * — that is the internal of ONE implementer
+ * (`SetupThreeRootAdapter`). First-party content and an unmodified external game
+ * are peer implementers of THIS interface; the host has no branch on which.
+ *
+ * It was `GameAdapter` until WO-9 #60, and the rename is an ONTOLOGY fix, not
+ * taste. Under D20 a *game* is the manifest's whole `roots` array — that is
+ * what `runtime/game.ts`'s `Game` is. Every implementer of THIS interface
+ * adapts exactly ONE root. So `Game` and `GameAdapter` sat at different levels
+ * of the ontology while sharing a name-stem, which reads as though one were
+ * the adapter for the other. The surrounding vocabulary had already moved:
+ * `MountedRootBase`, `MountedRoot`, `MountedRootFor`, `RootStateObserver`,
+ * `SurfaceAdapterFor`, `RootInstance`, `mountManifestRoots` — and, decisively,
+ * the resolver that PRODUCES these (`resolveRootAdapter`, `RootAdapterSchema`,
+ * `resolveThreeRootAdapter`) already said root. The interface was the last
+ * holdout, out of step with its own resolver.
+ *
+ * The `K = 'three'` default below is KEPT deliberately (see the note on the
+ * interface).
+ */
+
+import type { Container } from 'pixi.js';
+import type * as THREE from 'three';
+import type { AdapterSurface } from './adapter-surface';
+import type { AuthoringAdapter } from './authoring';
+import type { HostContextFor } from './host-context';
+import type { SystemAdapters } from './system-adapter';
+
+/**
+ * The ingested-world observation contract (T7.4 slice 2, "the
+ * must-answer"). Cross-world data flow with a
+ * foreign game is observation via an adapter-provided interface, not ordinary
+ * shared state (that's D7's answer for first-party↔first-party flow).
+ * Optional on {@link MountedThreeRoot} —
+ * absence means the adapter has nothing genuinely observable to expose (the
+ * anti-shim rule: never fabricate state), and the world takes the honest
+ * "no state bridge" tier hit (see `Game.registerRoot` in `runtime/game.ts`)
+ * rather than silently offering an `undefined`-forever subscription.
+ */
+export interface RootStateObserver {
+  /**
+   * Notified at most once per frame IF the adapter can hook the game's own
+   * update (`loop: 'gated'` roots, §(d)); self-driven roots (`loop:
+   * 'self-driven'`, raw-rAF) may notify on their OWN rAF cadence instead —
+   * consumers must not assume our frame timing. Returns an unsubscribe
+   * function.
+   */
+  subscribe(onChange: () => void): () => void;
+  /**
+   * A cheap, adapter-chosen snapshot of this world's observable state.
+   * Returns a STABLE reference while nothing has changed (so a selector run
+   * over it can cheaply bail out by reference, same spirit as
+   * `GameStateBridge`'s frame-version cache). Shape is adapter-defined —
+   * not centrally schematized in v1.
+   */
+  snapshot(): unknown;
+}
+
+/**
+ * Everything a mounted world provides EXCEPT its render surface: THREE.Scene/
+ * THREE.Camera typing is replaced with kind-tagged world surfaces. Split out
+ * of the old flat
+ * `MountedThreeRoot` so a non-threejs world can carry its own kind-appropriate
+ * surface field (a pixi `stage`, a react `container`) instead of being
+ * force-fit through THREE `scene`/`camera` fields it doesn't have.
+ */
+export interface MountedRootBase {
+  /**
+   * Loop model:
+   *  - `false` (host-driven): first-party + "clean" externals. The host ticks
+   *    `update(dt)` in its loop.
+   *  - `true` (self-driven): an unmodified game that owns its renderer + rAF.
+   *    The host does NOT tick it. Pause/step control is a DECLARED CAPABILITY,
+   *    not a promise: implement `setPaused`/`step` only where the game exposes
+   *    a sanctioned pause/step mechanism. Gating a raw-rAF loop from outside
+   *    was demonstrated and REJECTED (D5 — it halts the loop rather than
+   *    pausing it); such games are the "composited, unsynchronized" tier:
+   *    `setPaused` absent, host degrades loudly (T7.6 owns the tier surface).
+   */
+  readonly drivesOwnLoop: boolean;
+
+  update?(dt: number): void; // host-driven only
+  fixedUpdate?(dt: number): void;
+  setPaused?(paused: boolean): void; // capability, not promise — see loop-model note above
+  step?(): void;
+
+  resize?(width: number, height: number): void;
+  dispose(): void;
+
+  /** Optional capability providers — absence = "not supported", host degrades. */
+  readonly authoring?: AuthoringAdapter;
+  readonly systems?: SystemAdapters;
+  /** Optional state-observation capability (T7.4 slice 2, §4) — absent means
+   *  "no state bridge"; `Game.registerRoot` reports this loudly, once, for
+   *  any non-first-party mount. First-party mounts are exempt — their state
+   *  is observed through `Game.state`/`useWorldState` instead (§3), not this
+   *  field. */
+  readonly observe?: RootStateObserver;
+}
+
+/** A live, mounted three world. The host obtains `scene`/`camera` to
+ *  render+author. Until WO-9 task #9 this type also had a `MountedGame` alias,
+ *  which every pre-T7.5 threejs call site named; the alias is deleted, because
+ *  what it aliased is one three ROOT and a game is the manifest's whole set of
+ *  roots (D20). */
+export interface MountedThreeRoot extends MountedRootBase {
+  readonly kind: 'three';
+  /** The live scene + camera the editor inspects/renders for authoring. */
+  readonly scene: THREE.Scene;
+  readonly camera: THREE.Camera;
+}
+
+/** A live, mounted canvas world (T7.3) — the pixi analog of
+ *  {@link MountedThreeRoot}. `stage` is the pixi world container the host
+ *  renders/authors, the surface `RootInstance.pixiStage()` returns. */
+export interface MountedPixiRoot extends MountedRootBase {
+  readonly kind: 'canvas';
+  readonly stage: Container;
+}
+
+/** A live, mounted react world (T6.2) — the react analog of
+ *  {@link MountedThreeRoot}. `container` is the DOM-root layer the host
+ *  handed the adapter's `mount` (the SAME element `RootInstance.reactRoot()`
+ *  returns) — a react world's tree renders into it via `createRoot`. */
+export interface MountedReactRoot extends MountedRootBase {
+  readonly kind: 'dom';
+  readonly container: HTMLElement;
+}
+
+/** Every kind of live, mounted world (T7.5) — the union `RootInstance.mounted`
+ *  is typed against now, replacing the THREE-only `MountedThreeRoot`. */
+export type MountedRoot = MountedThreeRoot | MountedPixiRoot | MountedReactRoot;
+
+/** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
+ *  `BodyOf`/`ColliderOf` in `ecs/behavior.ts`) — lets generic code over
+ *  `K extends AdapterSurface` name the right surface without a manual union. */
+export type MountedRootFor<K extends AdapterSurface> = K extends 'three'
+  ? MountedThreeRoot
+  : K extends 'canvas'
+    ? MountedPixiRoot
+    : K extends 'dom'
+      ? MountedReactRoot
+      : never;
+
+/**
+ * The interface every game implements to run on the host. Generic over
+ * {@link AdapterSurface} (T7.5) so a non-threejs implementer's `mount` returns
+ * its OWN kind-tagged surface instead of being cast through the three shape —
+ * defaults to `'three'` so every pre-T7.5 implementer/call site
+ * (`RootAdapter`, unparameterized) keeps compiling unchanged.
+ *
+ * `K` parameterizes BOTH halves of `mount` (P-8): until then only the RETURN
+ * type was kind-tagged, while the PARAMETER was always the three-shaped
+ * `ThreeHostContext` — so a `RootAdapter<'canvas'>` was, by its own type, handed a
+ * `THREE.WebGLRenderer` it cannot use, and the production Pixi/React adapters
+ * could not be `RootAdapter`s at all (they were separate structural types over
+ * `CanvasHostContext`/`DomHostContext`, and `RootAdapter<'canvas'>` existed only in
+ * tests). With `HostContextFor<K>` the surface tag picks the context type, and
+ * those production adapters are now genuine `RootAdapter<K>` subtypes —
+ * `Pixi2DRootAdapter extends RootAdapter<'canvas'>`, `ReactRootAdapter extends
+ * RootAdapter<'dom'>` (`runtime/create-runtime.ts`).
+ */
+/**
+ * On the `= 'three'` default (WO-9 #60 considered removing it, and did not):
+ * this default is type-level only: an author who writes bare `RootAdapter` for
+ * a pixi root gets a compile error on `mount`'s return type, because
+ * `MountedRootFor<'three'>` demands `scene`/`camera` a `MountedPixiRoot` has
+ * not got. Wrong-by-default is caught by tsc, so removing this default would
+ * be churn across ~125 bare call sites for no defect it could catch.
+ */
+export interface RootAdapter<K extends AdapterSurface = 'three'> {
+  /** Stable id (telemetry/registry/conformance). */
+  readonly id: string;
+  /** Build/start the game against the host context for ITS surface; return the
+   *  handle. */
+  mount(host: HostContextFor<K>): Promise<MountedRootFor<K>>;
+}
+
+/**
+ * One surface tag paired with an adapter typed FOR that surface (WO-34).
+ *
+ * Why this exists: a resolver that turns a manifest root into a mountable
+ * adapter handles every surface in one function, so its return type has to
+ * span all three. Returning the bare union `RootAdapter<'three'> |
+ * RootAdapter<'canvas'> | RootAdapter<'dom'>` does NOT work — a union of
+ * function types INTERSECTS its parameters, so `.mount(host)` becomes
+ * uncallable with any single host value (no one object is simultaneously a
+ * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`). The historical
+ * workaround was to declare the whole channel `RootAdapter<'three'>` and
+ * re-assert the real kind at each call site with `as unknown as` — kind
+ * ERASURE: the surface tag the manifest already knew was thrown away and
+ * guessed back.
+ *
+ * Carrying the tag ALONGSIDE the adapter fixes that structurally: this is a
+ * discriminated union on `surface`, so `switch (resolved.surface)` narrows
+ * `resolved.adapter` to ONE `RootAdapter<K>` inside each branch — a single
+ * signature again, hence `.mount(host)` is callable with that surface's own
+ * host context, checked by the compiler instead of asserted.
+ */
+export type SurfaceAdapterFor<K extends AdapterSurface> = {
+  readonly surface: K;
+  readonly adapter: RootAdapter<K>;
+};
+
+/** Every surface's {@link SurfaceAdapterFor}, as one discriminated union.
+ *  Written out member-by-member (rather than as a distributive conditional)
+ *  so `assertNever` sees exactly three variants and a hypothetical 4th
+ *  `AdapterSurface` member fails to compile HERE, at the vocabulary, rather
+ *  than silently widening every consumer's exhaustiveness guard. */
+export type SurfaceAdapter =
+  | SurfaceAdapterFor<'three'>
+  | SurfaceAdapterFor<'canvas'>
+  | SurfaceAdapterFor<'dom'>;