@vgai/engine 0.5.2 → 0.5.3

package/src/adapter/game-adapter.ts

@@ -1,164 +0,0 @@
-/**
- * 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 { ComponentManager } from '../ecs/component-manager';
-import type { AdapterSurface } from './adapter-surface';
-import type { AuthoringAdapter } from './authoring';
-import type { HostContext } from './host-context';
-import type { SystemAdapters } from './system-adapter';
-
-/**
- * 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'` roots, `docs/CAPABILITY-TIERS.md` §(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 (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 component-query capability: an adapter that runs the engine's
-   * REAL `ComponentManager` without being the classic first-party mount
-   * (e.g. `@engine/world3d-react`'s R3F adapter — `<Behavior>` attaches
-   * through a real manager) exposes it here so `Game.queryByComponent`
-   * (`runtime/game.ts`) aggregates this world's instances and
-   * `registerThreeWorld` (`runtime/create-runtime.ts`) backfills
-   * `instance.world` at registration, exactly like a first-party world.
-   * Absent for a genuinely foreign mount that hosts no GameComponents —
-   * such a world legitimately answers "no components".
-   */
-  readonly components?: ComponentManager;
-  /** 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 AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
- *  `BodyOf`/`ColliderOf` in `ecs/game-component.ts`) — lets generic code over
- *  `K extends AdapterSurface` name the right surface without a manual union. */
-export type MountedWorldFor<K extends AdapterSurface> = 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 AdapterSurface} (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 AdapterSurface = '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/ingest/overlay-applier.ts

@@ -1,207 +0,0 @@
-/**
- * `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 };
-}

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

@@ -1,168 +0,0 @@
-/**
- * Ingest overlay application core — the structural-path identity scheme and
- * override-application loop shared by the EDITOR's `IngestAuthoringAdapter`
- * (`packages/editor/src/authoring/ingest-authoring-adapter.ts`, which layers
- * hierarchy/selection/undo bookkeeping over it) and the T3.8 runtime ship-path
- * applier (`./overlay-applier.ts`, which uses it directly with none of that
- * editor bookkeeping). Extracted here (rather than duplicated) per D9's task
- * split (docs/DECISIONS-PENDING.md §D9) — the editor re-exports/reuses this
- * module so its behavior (and the ids it mints) stay byte-for-byte identical
- * between "authored in the editor" and "reapplied at ship time".
- *
- * Identity: each object gets a deterministic **structural-path id** — stable
- * for a given scene shape (position in the tree + three.js type + name), so
- * the SAME id re-binds to the SAME object after an independent fresh walk of
- * an unmodified game's rebuilt scene (a reload, or a separate page entirely —
- * this is what lets an overlay authored in the editor apply cleanly in a
- * shipped build that never ran the editor). 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.
- */
-
-import type * as THREE from 'three';
-import { setUserData } from '../../scene/user-data';
-import type { IngestOverlay } from './overlay-file';
-
-/** 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 single (non-array) standard-ish material of a mesh, if it has a color. */
-export function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null {
-  const mat = (o as THREE.Mesh).material;
-  if (!mat || Array.isArray(mat)) return null;
-  const m = mat as THREE.MeshStandardMaterial;
-  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) — the prerequisite for overlay reapplication
- * across an independent fresh walk (editor reload, or a shipped build that
- * never ran the editor at all).
- *
- * 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, which broke the two promises above:
- *
- *   • Across a RELOAD, the same mesh changed id. Observed in the games-fps
- *     overlay-persistence e2e: an object saved 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 — so the persisted
- *     override landed on nothing and was reported as an orphan.
- *   • A SHIPPED build (no editor, so no furniture at all) minted a different
- *     id set than the editor that authored the overlay — i.e. the ship path
- *     this module exists to serve could not reliably consume its own output.
- *
- * Skipping the furniture entirely — not merely declining to give it an id —
- * is what fixes both: 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 };
-}
-
-/** Result of applying a saved overlay onto a structural-id-walked scene. */
-export interface OverlayApplyOutcome {
-  applied: number;
-  orphanedIds: string[];
-}
-
-/**
- * Apply a saved overlay's overrides onto the live objects in `byId` (from
- * {@link assignStructuralIds}). Ids absent from the map are "orphaned" — e.g. a
- * dynamic child that didn't respawn, or the vendored game was bumped and
- * restructured — never an error; the caller reports them (never silently) via
- * `./overlay-report.ts`. Mutates matched objects in place; does not mutate
- * `overlay` itself or track dirty/undo state — that bookkeeping is the
- * editor-side `IngestAuthoringAdapter`'s job (persistable-edit tracking, so
- * orphans round-trip on the next save) and is irrelevant to the ship-path
- * applier (which never saves).
- */
-export function applyOverlayToObjects(
-  byId: Map<string, THREE.Object3D>,
-  overlay: IngestOverlay,
-): OverlayApplyOutcome {
-  let applied = 0;
-  const orphanedIds: string[] = [];
-  for (const [id, ov] of Object.entries(overlay)) {
-    const o = byId.get(id);
-    if (!o) {
-      orphanedIds.push(id);
-      continue;
-    }
-    if (ov.position) o.position.set(ov.position[0], ov.position[1], ov.position[2]);
-    if (ov.rotation)
-      o.quaternion.set(ov.rotation[0], ov.rotation[1], ov.rotation[2], ov.rotation[3]);
-    if (ov.scale) o.scale.set(ov.scale[0], ov.scale[1], ov.scale[2]);
-    if (ov.color) colorMaterialOf(o)?.color.set(ov.color);
-    if (ov.visible !== undefined) o.visible = ov.visible;
-    applied++;
-  }
-  return { applied, orphanedIds };
-}

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

@@ -1,126 +0,0 @@
-/**
- * Ingest overlay envelope — the on-disk shape shared by every consumer of a
- * saved ingest overlay: the editor (`packages/editor/src/authoring/ingest-overlay.ts`,
- * which persists it through the storage-backend seam) AND the T3.8 runtime ship-path
- * applier (`./overlay-applier.ts`, which fetches it over plain HTTP in a deployed
- * game with no editor/storage-backend dependency at all).
- *
- * This module is the dependency-free core (types + pure parsing) both share — moved
- * here (from the editor-only module that used to own it) per D9's task split
- * (docs/DECISIONS-PENDING.md §D9): the editor keeps the storage-backend-aware
- * `loadOverlay`/`saveOverlay` and re-exports everything below unchanged so its
- * existing import sites don't churn.
- */
-
-/** A single object's persisted overrides (only the fields the user changed). */
-export interface IngestOverride {
-  position?: [number, number, number];
-  rotation?: [number, number, number, number];
-  scale?: [number, number, number];
-  color?: string;
-  visible?: boolean;
-}
-
-/** id (structural-path) → overrides. */
-export type IngestOverlay = Record<string, IngestOverride>;
-
-/** Current on-disk envelope format version (D9, docs/DECISIONS-PENDING.md §D9). */
-export const OVERLAY_FORMAT_VERSION = 1;
-
-/**
- * The on-disk overlay envelope (D9 — overlay versioning + orphan reporting).
- * Wraps the flat `IngestOverlay` (id → overrides) with save-time provenance:
- * which game version the edits were authored against, so a later mount (editor
- * OR shipped runtime) can detect drift and report it (`./overlay-report.ts`'s
- * `OverlayApplyReport`).
- *
- * `formatVersion` distinguishes this from the PRE-D9 flat file (the whole JSON
- * file WAS the `IngestOverlay`): {@link parseOverlayFile} recognizes both. An
- * object with `formatVersion` + `overrides` parses as the real envelope; any
- * other shape (or unparseable content) parses as a legacy flat file, wrapped as
- * `{ formatVersion: 0, authoredAgainst: { gameVersion: null }, overrides: <the flat object> }`
- * — never rejected, never warned about by itself.
- *
- * `authoredAgainst.upstreamPin` (R5, docs/MASTER-ARCHITECTURE-REVIEW.md
- * §4(c)/§7.1 item 9 — the overlay-identity gap `gameVersion` alone doesn't
- * close: `gameVersion` is the manifest's own `version` field, which a
- * re-vendor of the upstream game need not bump — see every `public/ingest/*`
- * game's `vgai.game.json`, all pinned at `"version": "0.1.0"` regardless of
- * upstream commit) is an OPTIONAL sibling key, deliberately absent from this
- * type's older call sites' literal shape: its ABSENCE (the key missing from
- * `authoredAgainst` entirely) is the "legacy overlay" signal — saved by code
- * that predates this field, so the pin concept never existed for it, and
- * `./overlay-report.ts`'s apply-time check must skip it (not treat it as a
- * guaranteed mismatch OR a guaranteed match — anti-shim, no guessing). A
- * `null` VALUE (key present, value `null`) means R5-aware save-time code DID
- * look for a pin and honestly found none (e.g. an externally-authored,
- * non-vendored project opened via the CLI-on-folder route, which has no
- * `UPSTREAM.md` at all). See `./upstream-pin.ts` for the pure extraction, and
- * `packages/editor/src/ingest-mode.ts` for where it's read at save/apply
- * time. This is purely additive — {@link parseOverlayFile} never invents the
- * key for an envelope that didn't have it.
- */
-export interface OverlayFile {
-  formatVersion: number;
-  authoredAgainst: { gameVersion: string | null; upstreamPin?: string | null };
-  overrides: IngestOverlay;
-}
-
-/** Where a game's overlay lives, project-root-relative (also the ship path's default fetch URL). */
-export function overlayPath(gameId: string): string {
-  return `.vgai/overlays/${gameId}.json`;
-}
-
-/** The empty envelope — no overlay found / nothing authored yet. */
-export function emptyOverlayFile(): OverlayFile {
-  return {
-    formatVersion: OVERLAY_FORMAT_VERSION,
-    authoredAgainst: { gameVersion: null },
-    overrides: {},
-  };
-}
-
-/** An envelope has both its distinguishing keys — anything else is a legacy flat file. */
-function isEnvelope(raw: unknown): raw is OverlayFile {
-  return (
-    !!raw &&
-    typeof raw === 'object' &&
-    'formatVersion' in (raw as Record<string, unknown>) &&
-    'overrides' in (raw as Record<string, unknown>)
-  );
-}
-
-/**
- * Parse a loaded/fetched overlay's raw JSON into the {@link OverlayFile} shape,
- * transparently upgrading a legacy (pre-D9) flat file — the whole parsed value
- * IS the `IngestOverlay` in that case. Pure — no I/O, no storage backend, so
- * it's usable from any context (editor `loadOverlay`, the ship-path applier's
- * `fetch().then(r => r.json())`).
- */
-export function parseOverlayFile(raw: unknown): OverlayFile {
-  if (isEnvelope(raw)) {
-    const rawAuthored = (raw.authoredAgainst ?? { gameVersion: null }) as {
-      gameVersion?: string | null;
-      upstreamPin?: string | null;
-    };
-    const authoredAgainst: OverlayFile['authoredAgainst'] = {
-      gameVersion: rawAuthored.gameVersion ?? null,
-    };
-    // Preserve ABSENCE vs. explicit `null` (see this field's doc comment
-    // above) — only copy the key over if the raw JSON actually had it, rather
-    // than defaulting it in (which would make every pre-R5 saved overlay look
-    // like a "checked, found nothing" R5 save instead of "never checked").
-    if ('upstreamPin' in rawAuthored) authoredAgainst.upstreamPin = rawAuthored.upstreamPin ?? null;
-    return {
-      formatVersion: raw.formatVersion,
-      authoredAgainst,
-      overrides: raw.overrides ?? {},
-    };
-  }
-  // Legacy flat file (pre-D9): the whole parsed object IS the overrides map.
-  return {
-    formatVersion: 0,
-    authoredAgainst: { gameVersion: null },
-    overrides: (raw ?? {}) as IngestOverlay,
-  };
-}