@vgai/engine 0.2.0

package/src/adapter/game-adapter.ts

@@ -0,0 +1,151 @@
+/**
+ * GameAdapter — the host ⇄ runtime contract. A "game" 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`,
+ * `.vscn`, or `GameComponent` — those are the internals of ONE implementer
+ * (`VgaiSceneGameAdapter`). First-party content and an unmodified external game
+ * are peer implementers of THIS interface; the host has no branch on which.
+ */
+
+import type { Container } from 'pixi.js';
+import type * as THREE from 'three';
+import type { AuthoringAdapter } from './authoring';
+import type { HostContext } from './host-context';
+import type { SystemAdapters } from './system-adapter';
+import type { WorldKind } from './world-kind';
+
+/**
+ * The ingested-world observation contract (T7.4 slice 2 — `docs/
+ * REACT-STATE-BRIDGE.md` §4, "the must-answer"). Cross-world data flow with a
+ * foreign game is observation via an adapter-provided interface, not ordinary
+ * component access (that's D7's answer for first-party↔first-party flow —
+ * foreign games host no `GameComponent`s). Optional on {@link MountedGame} —
+ * 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.registerWorld` in `runtime/game.ts`)
+ * rather than silently offering an `undefined`-forever subscription.
+ */
+export interface WorldStateObserver {
+  /**
+   * Notified at most once per frame IF the adapter can hook the game's own
+   * update (`loop: 'gated'` worlds, `docs/CAPABILITY-TIERS.md` §(d));
+   * self-driven worlds (`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 (see `docs/REACT-STATE-BRIDGE.md` §6).
+   */
+  snapshot(): unknown;
+}
+
+/**
+ * Everything a mounted world provides EXCEPT its render surface (T7.5,
+ * `docs/BACKBONE-TASKS.md`'s D6 row — "replace THREE.Scene/THREE.Camera
+ * typing with kind-tagged world surfaces"). Split out of the old flat
+ * `MountedGame` 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 MountedWorldBase {
+  /**
+   * 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, docs/COMPOSITION-DESIGN.md §5.2 —
+   *    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.registerWorld` reports this loudly, once, for
+   *  any non-first-party mount. First-party mounts are exempt — their state
+   *  is observed through `Game.state`/`useGameState` instead (§3), not this
+   *  field. */
+  readonly observe?: WorldStateObserver;
+}
+
+/** A live, mounted threejs world. The host obtains `scene`/`camera` to
+ *  render+author. This is what `MountedGame` (the permanent alias every
+ *  pre-T7.5 threejs-world call site still names) now means. */
+export interface MountedThreeWorld extends MountedWorldBase {
+  readonly kind: 'threejs';
+  /** The live scene + camera the editor inspects/renders for authoring. */
+  readonly scene: THREE.Scene;
+  readonly camera: THREE.Camera;
+}
+
+/** A live, mounted pixijs world (T7.3) — the pixi analog of
+ *  {@link MountedThreeWorld}. `stage` is the pixi world container the host
+ *  renders/authors, the surface `WorldInstance.pixiRoot()` returns. */
+export interface MountedPixiWorld extends MountedWorldBase {
+  readonly kind: 'pixijs';
+  readonly stage: Container;
+}
+
+/** A live, mounted react world (T6.2) — the react analog of
+ *  {@link MountedThreeWorld}. `container` is the DOM-root layer the host
+ *  handed the adapter's `mount` (the SAME element `WorldInstance.reactRoot()`
+ *  returns) — a react world's tree renders into it via `createRoot`. */
+export interface MountedReactWorld extends MountedWorldBase {
+  readonly kind: 'react';
+  readonly container: HTMLElement;
+}
+
+/** Every kind of live, mounted world (T7.5) — the union `WorldInstance.mounted`
+ *  is typed against now, replacing the THREE-only `MountedGame`. */
+export type MountedWorld = MountedThreeWorld | MountedPixiWorld | MountedReactWorld;
+
+/** Map a {@link WorldKind} to its mounted-world shape (mirrors `NodeOf`/
+ *  `BodyOf`/`ColliderOf` in `ecs/game-component.ts`) — lets generic code over
+ *  `K extends WorldKind` name the right surface without a manual union. */
+export type MountedWorldFor<K extends WorldKind> = K extends 'threejs'
+  ? MountedThreeWorld
+  : K extends 'pixijs'
+    ? MountedPixiWorld
+    : K extends 'react'
+      ? MountedReactWorld
+      : never;
+
+/**
+ * Permanent alias (T7.1 precedent — old names stay valid forever once a
+ * generalization lands): `MountedGame` now means "a mounted THREEJS world."
+ * Every pre-T7.5 threejs-only call site (`VgaiMountedGame extends MountedGame`,
+ * `registerThreeWorld`, ingest adapters, …) keeps compiling unchanged.
+ */
+export type MountedGame = MountedThreeWorld;
+
+/** The interface every game implements to run on the host. Generic over
+ *  {@link WorldKind} (T7.5) so a non-threejs implementer's `mount` returns its
+ *  OWN kind-tagged surface instead of being cast through the threejs shape —
+ *  defaults to `'threejs'` so every pre-T7.5 implementer/call site
+ *  (`GameAdapter`, unparameterized) keeps compiling unchanged. */
+export interface GameAdapter<K extends WorldKind = 'threejs'> {
+  /** Stable id (telemetry/registry/conformance). */
+  readonly id: string;
+  /** Build/start the game against a host-provided context; return the handle. */
+  mount(host: HostContext): Promise<MountedWorldFor<K>>;
+}

package/src/adapter/host-context.ts

@@ -0,0 +1,77 @@
+/**
+ * HostContext — the NEUTRAL primitives the host hands a game when mounting it.
+ *
+ * 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, assets, a UI overlay — 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.
+ */
+
+import type * as THREE from 'three';
+import type { AssetCache } from '../assets';
+import type { GameInternal } from '../runtime/game';
+
+/** The canvas/container the game renders into, plus its size. */
+export interface HostSurface {
+  readonly canvas: HTMLCanvasElement;
+  readonly width: number;
+  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;
+}
+
+/**
+ * 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.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: extended by first-party host wiring as systems become provisionable
+export interface SystemRegistry {}
+
+export interface HostContext {
+  /** 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. */
+  readonly assets: AssetCache;
+  /** HUD overlay container (pointer-events:none by default). */
+  readonly ui: HTMLElement;
+  /**
+   * 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.worlds` 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;
+}

package/src/adapter/index.ts

@@ -0,0 +1,85 @@
+/**
+ * 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)
+ *
+ * The first-party `.vscn`/`GameComponent`/Rapier/Colyseus stack is ONE
+ * implementer of these interfaces, not the engine's vocabulary. See
+ * docs/ADAPTER-ARCHITECTURE.md.
+ */
+
+export type {
+  AssetDropProvider,
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  BoxEditProvider,
+  ColorSampleProvider,
+  ComponentsProvider,
+  DOMRectLike,
+  EditorNode,
+  FileMapProvider,
+  HierarchyProvider,
+  InspectorProvider,
+  LayoutProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  RectProvider,
+  RootGroup,
+  RootGroupsProvider,
+  SelectionProvider,
+  StoriesProvider,
+  StoryRef,
+  StructureProvider,
+  TextProvider,
+  TransformProvider,
+} from './authoring';
+export {
+  type ColyseusNetworkingConfig,
+  createColyseusNetworkingAdapter,
+} from './colyseus-networking-adapter';
+export {
+  createAnimationAdapter,
+  createInputManagerAdapter,
+  createNavigationAdapter,
+  createVgaiAssetAdapter,
+} from './first-party-systems';
+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';
+export type {
+  AnimationAdapter,
+  AnimationGraphInfo,
+  AssetAdapter,
+  ConnectionState,
+  InputAdapter,
+  NavigationAdapter,
+  NavPoint,
+  NetPeer,
+  NetworkingAdapter,
+  PhysicsAdapter,
+  ReplicationStats,
+  RoomInfo,
+  SystemAdapters,
+  Unsubscribe,
+} from './system-adapter';
+export type { Transform, TransformOwner } from './transform';
+export {
+  fromSetup,
+  type VgaiMountedGame,
+  type VgaiSceneConfig,
+  VgaiSceneGameAdapter,
+} from './vgai-scene-game-adapter';
+export type { WorldKind } from './world-kind';

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

@@ -0,0 +1,59 @@
+/**
+ * The game→host contract: ONE pre-defined interface an external game may
+ * declare on `window.vgaiGame` to let the editor work with it like native
+ * content. Capabilities are by PRESENCE — every field is optional, and a game
+ * that declares nothing runs exactly as before (doctrine: adaptation enables
+ * editor features; it never bends a game around host internals). This file is
+ * the single source of truth for the contract's shape — host code reads it
+ * through {@link readGameContract} instead of ad-hoc `window` casts, so the
+ * spec and the implementation cannot drift apart.
+ *
+ * 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%
+ * 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).
+ */
+
+/**
+ * Session lifecycle endpoints. Declaring `start` means "I support cold
+ * mount": when the host sets `window.__vgaiMountCold` before the game's entry
+ * executes, the game may defer its session side-effects (backend connections,
+ * narrative, audio) and render a quiet, inspectable scene; the host calls
+ * `start()` — at most once per mount — when the user presses ▶. Declaring
+ * `pause`/`resume` means the game can genuinely freeze/unfreeze itself; the
+ * host prefers these over its outside-in loop gate (which cannot gate a raw
+ * requestAnimationFrame loop at all — R3F games, notably).
+ */
+export interface VgaiGameLifecycle {
+  start?(): void;
+  pause?(): void;
+  resume?(): void;
+}
+
+export interface VgaiGameContract {
+  /** Bump only on breaking shape changes; additive endpoints keep version 1. */
+  contractVersion: 1;
+  /**
+   * The element that OWNS the game's whole DOM (canvas + HUD + overlay
+   * portals). The host adopts it wholesale into the game pane, so DOM-hybrid
+   * games keep their UI instead of stranding it at page level. The host
+   * verifies it actually contains the captured canvas before adopting.
+   */
+  root?: HTMLElement;
+  lifecycle?: VgaiGameLifecycle;
+}
+
+/**
+ * Read the declared contract, if any. The `contractVersion` gate is the
+ * forward-compatibility hinge: a future v2 game on a v1 host is ignored
+ * (pre-contract fallbacks apply) rather than half-interpreted.
+ */
+export function readGameContract(): VgaiGameContract | null {
+  const declared = (window as unknown as { vgaiGame?: VgaiGameContract }).vgaiGame;
+  if (!declared || declared.contractVersion !== 1) return null;
+  return declared;
+}

package/src/adapter/ingest/overlay-applier.ts

@@ -0,0 +1,207 @@
+/**
+ * `applyVgaiOverlay` — the T3.8 deliverable (docs/DECISIONS-PENDING.md §D9):
+ * the opt-in runtime overlay applier a game owner adds to THEIR OWN deployment
+ * so an adapted (ingested-then-edited) game ships with the editor's edits
+ * visible, with zero involvement from the editor at runtime.
+ *
+ * The opt-in shape (D9's "minimal source opt-in, consistent with the
+ * zero-diff-unless-opted-in invariant"): one import + one call, placed before
+ * the game's own entry point runs (so the capture trap below is installed
+ * before the game's `WebGLRenderer` is constructed):
+ *
+ *   import * as THREE from 'three';
+ *   import { applyVgaiOverlay } from '@vgai/engine/adapter/ingest/overlay-applier';
+ *
+ *   applyVgaiOverlay({ three: THREE, gameId: 'my-game' }); // fire-and-forget
+ *   import('./my-game-entry.js'); // the UNMODIFIED game, unchanged
+ *
+ * No scene is passed manually — this reuses the SAME render-accessor trap
+ * (`./scene-capture.ts`) the editor's ingest mode uses to obtain the game's
+ * live `Scene`/camera the moment it first renders, so this works for ANY
+ * unmodified three.js game the SAME way ingestion already captures it (per
+ * `scene-capture.ts`'s own caveat, this requires the game to share the host's
+ * `three` module instance — a bundled/vendored copy of `three` cannot be
+ * captured this way, matching the editor's own capture ceiling).
+ *
+ * Failure modes are all graceful (the game always keeps running unmodified)
+ * but never silent — every one is logged via `console.warn` under the shared
+ * `overlay-report` prefix (`./overlay-report.ts`) so ops can grep one string
+ * for every overlay-related issue across both the editor and the ship path:
+ *   - no overlay file at `overlayUrl` (never authored, or a 404/network
+ *     error) → nothing applied, logged, scene never even captured;
+ *   - the game never renders within `captureTimeoutMs` (bundled/non-shared
+ *     three, or the game simply never boots) → nothing applied, logged;
+ *   - a version mismatch and/or orphaned overlay ids (D9) → whatever DOES
+ *     resolve is still applied; the report names what didn't.
+ *
+ * Precedence (D9 "overlay-vs-game-save-system precedence"): the overlay is
+ * applied exactly ONCE, synchronously, in the continuation of the game's
+ * FIRST captured render call — i.e. between that frame finishing and the
+ * game's own next frame starting. Any later mutation of the SAME
+ * property by the game's own logic (its own save/load system, a per-frame
+ * animation, etc.) therefore wins from then on purely by construction: this
+ * applier never re-applies and never re-reads the overlay after this one
+ * pass. A property the game's own logic never revisits stays overlaid for
+ * the life of the session; a property the game's own logic re-derives every
+ * frame reverts to the game's own value on the very next frame. This
+ * ordering is exercised directly by `overlay-applier.test.ts`'s "precedence"
+ * case (apply, then simulate one more game-owned mutation frame).
+ */
+
+import type * as THREE from 'three';
+import { applyOverlayToObjects, assignStructuralIds } from './overlay-apply';
+import { type OverlayFile, overlayPath, parseOverlayFile } from './overlay-file';
+import {
+  buildOverlayApplyReport,
+  logOverlayApplyReport,
+  OVERLAY_REPORT_PREFIX,
+  type OverlayApplyReport,
+} from './overlay-report';
+import { installSceneCapture } from './scene-capture';
+
+export interface ApplyVgaiOverlayOptions {
+  /**
+   * The game's own `three` module namespace — pass `import * as THREE from
+   * 'three'` from the SAME module instance the game imports (required for the
+   * capture trap to see the game's renderer; see `scene-capture.ts`).
+   */
+  three: unknown;
+  /** Stable id for this game — namespaces the overlay file (matches the editor's `overlayPath(gameId)`). */
+  gameId: string;
+  /** Where to fetch the saved overlay from. Defaults to `overlayPath(gameId)` (`.vgai/overlays/<gameId>.json`, resolved relative to the deployed page — the editor saves to `<projectRoot>/.vgai/overlays/`; a deployment copies that file next to the built page). */
+  overlayUrl?: string | undefined;
+  /**
+   * The deployed game's own version, if known — compared against the
+   * overlay's `authoredAgainst.gameVersion` for drift reporting. Omit/null:
+   * never fabricated (anti-shim) — a mismatch is only ever reported when
+   * BOTH sides are known (`./overlay-report.ts`).
+   */
+  gameVersion?: string | null | undefined;
+  /**
+   * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)): the deployed game's own
+   * `UPSTREAM.md` pin, if the game owner happens to know it (e.g. baked in at
+   * build time from their own vendoring step). Compared against the overlay's
+   * `authoredAgainst.upstreamPin` for the same drift reporting `gameVersion`
+   * gets, but catches a same-slot SUBSTITUTION that `gameVersion` alone
+   * cannot (see `./upstream-pin.ts` + `./overlay-report.ts`'s header).
+   * DELIBERATE NO-OP by default: this ship-path applier runs in the game
+   * owner's OWN deployed build, which has no filesystem access to the
+   * `UPSTREAM.md` that lived in the vgai monorepo/editor project at
+   * ingest-authoring time — there is no way for this applier to discover the
+   * pin itself, so it is never fabricated (anti-shim) and the check silently
+   * skips (report's `upstreamPin.mismatch` stays `false`) unless the caller
+   * supplies this option explicitly.
+   */
+  upstreamPin?: string | null | undefined;
+  /** How long to wait for the game's first captured render call before giving up (ms). Defaults to `installSceneCapture`'s own default (10s). */
+  captureTimeoutMs?: number | undefined;
+  /** Injectable `fetch` (tests / non-browser hosts). Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch | undefined;
+}
+
+export interface ApplyVgaiOverlayResult {
+  /** Whether the game's scene was actually captured (false only when capture itself timed out or no overlay was found — either way the game runs unmodified). */
+  captured: boolean;
+  /** The D9 apply report, or `null` when there was no overlay to apply at all (not an error — the game runs unmodified). */
+  report: OverlayApplyReport | null;
+  /**
+   * The captured scene/camera, present only when `captured` is true. Most
+   * callers (a game's own entry point) have no reason to touch this — it's
+   * surfaced for diagnostics/tooling (and for tests, which use it to inspect
+   * the live post-apply scene the same way the editor's ingest proof pages do)
+   * rather than requiring a second, independent capture.
+   */
+  scene?: THREE.Scene | undefined;
+  camera?: THREE.Camera | undefined;
+}
+
+/** Shared warn helper — every graceful-failure path below logs through here. */
+function warn(gameId: string, message: string): void {
+  // biome-ignore lint/suspicious/noConsole: deliberate, greppable (mirrors overlay-report.ts's own console.warn)
+  console.warn(`${OVERLAY_REPORT_PREFIX} game "${gameId}": ${message}`);
+}
+
+async function fetchOverlayFile(
+  url: string,
+  gameId: string,
+  fetchImpl: typeof fetch | undefined,
+): Promise<OverlayFile | null> {
+  const doFetch = fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined);
+  if (!doFetch) {
+    warn(gameId, 'no fetch implementation available — overlay not applied, running unmodified.');
+    return null;
+  }
+  try {
+    const res = await doFetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const raw: unknown = await res.json();
+    return parseOverlayFile(raw);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    warn(gameId, `no overlay applied (${reason}) — running unmodified.`);
+    return null;
+  }
+}
+
+/**
+ * The opt-in ship-path applier — see this module's header for the full
+ * contract. Installs the scene-capture trap SYNCHRONOUSLY (before the first
+ * `await`), so a caller that follows the documented pattern (call this, THEN
+ * import/boot the game) never races the trap against the game's first frame
+ * — the trap's `captured` slot latches on the game's first render regardless
+ * of when (or whether) this function later calls `waitForCapture` on it.
+ * Only PROCEEDS to actually wait for that capture once an overlay has been
+ * found (fetched first, deliberately) — the common "never edited this game"
+ * case then costs one fetch, never a multi-second capture-timeout wait.
+ */
+export async function applyVgaiOverlay(
+  options: ApplyVgaiOverlayOptions,
+): Promise<ApplyVgaiOverlayResult> {
+  const { three, gameId, gameVersion = null, upstreamPin = null, fetchImpl } = options;
+  const overlayUrl = options.overlayUrl ?? overlayPath(gameId);
+
+  // Install the capture trap before anything else in this function (and
+  // before returning control to the caller's microtask queue) — see the
+  // header comment's ordering guarantee.
+  const capture = installSceneCapture(three);
+
+  const overlayFile = await fetchOverlayFile(overlayUrl, gameId, fetchImpl);
+  if (!overlayFile) {
+    // Nothing to apply (never authored, 404, network error — already logged
+    // by fetchOverlayFile) — don't bother waiting for a render at all.
+    capture.uninstall();
+    return { captured: false, report: null };
+  }
+
+  let rt: Awaited<ReturnType<typeof capture.waitForCapture>>;
+  try {
+    rt = await capture.waitForCapture(options.captureTimeoutMs);
+  } catch (err) {
+    capture.uninstall();
+    const reason = err instanceof Error ? err.message : String(err);
+    warn(gameId, `scene capture failed (${reason}) — overlay not applied, running unmodified.`);
+    return { captured: false, report: null };
+  }
+  capture.uninstall(); // one-shot: we have what we need, stop wrapping future renders.
+
+  const { byId } = assignStructuralIds(rt.scene, rt.camera);
+  const { applied, orphanedIds } = applyOverlayToObjects(byId, overlayFile.overrides);
+
+  const report = buildOverlayApplyReport({
+    gameId,
+    authoredAgainst: overlayFile.authoredAgainst.gameVersion,
+    currentVersion: gameVersion,
+    applied,
+    orphanedIds,
+    // R5: `authoredUpstreamPin` passes through undefined for a legacy overlay
+    // (the key was never in `authoredAgainst` at all — see overlay-file.ts),
+    // preserving the "never checked" vs. "checked, found nothing" distinction
+    // all the way from disk. `currentUpstreamPin` is this no-op-by-default
+    // option (see its doc comment above) — `null` unless a game owner passes it.
+    authoredUpstreamPin: overlayFile.authoredAgainst.upstreamPin,
+    currentUpstreamPin: upstreamPin,
+  });
+  logOverlayApplyReport(report);
+
+  return { captured: true, report, scene: rt.scene, camera: rt.camera };
+}