@vgai/engine 0.2.0

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

@@ -0,0 +1,124 @@
+/**
+ * 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 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).
+ */
+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++;
+    o.children.forEach((c, i) => {
+      visit(c, `${path}/${i}`);
+    });
+  };
+  scene.children.forEach((c, i) => {
+    visit(c, `${i}`);
+  });
+  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

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

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

@@ -0,0 +1,176 @@
+/**
+ * Overlay apply report — D9 (docs/DECISIONS-PENDING.md §D9): decide + surface
+ * what happens when a saved ingest overlay is reapplied onto a scene that may
+ * have moved on since the overlay was authored (a vendored game bump, or a
+ * dynamic subtree that never respawned). Two independent signals, either of
+ * which is worth a loud (never silent) structured warning:
+ *   - a GAME-VERSION mismatch: the overlay's `authoredAgainst.gameVersion`
+ *     (`./overlay-file.ts`'s envelope, stamped from the manifest's `version`
+ *     at save time) disagrees with the currently-mounted game's version;
+ *   - ORPHANED ids: structural-path ids in the overlay that resolved to
+ *     nothing on the current scene walk (`./overlay-apply.ts`'s
+ *     `applyOverlayToObjects`).
+ *
+ * Neither condition blocks mounting — the overlay still applies everything it
+ * CAN; this module only decides whether/how to report what it couldn't.
+ *
+ * This is the SEAM T3.8 (the runtime overlay applier, i.e. reapplying an
+ * ingest overlay against a shipped/played build rather than the editor)
+ * reuses: `./overlay-applier.ts`'s `applyVgaiOverlay` builds + logs this EXACT
+ * report shape, same as the editor does. Moved here from the editor-only
+ * module that used to own it (`packages/editor/src/authoring/overlay-report.ts`,
+ * which now re-exports everything below unchanged plus the editor-only
+ * "active report" banner slot) — kept dependency-free (no `editor-console`/
+ * `window` import) so it stays importable from a headless runtime context —
+ * same discipline as `../achieved-tier.ts`.
+ *
+ * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/§7.1 item 9) adds a THIRD
+ * independent signal alongside version-mismatch/orphans: an UPSTREAM-PIN
+ * mismatch. `gameVersion` alone cannot catch a same-slot substitution after a
+ * re-vendor (structural ids are position+type+name; a re-vendor that keeps a
+ * slot's shape reapplies the overlay onto a semantically different object
+ * with `applied:1, orphanedIds:[]`, and every vendored game's manifest
+ * `version` is hand-set and need not change on a re-vendor). The upstream pin
+ * (`./upstream-pin.ts`, read from the vendored game's `UPSTREAM.md`) is bound
+ * to the thing that actually changes. Like the other two signals, a mismatch
+ * never blocks application — it's a report, not a block (matching orphan
+ * semantics) — so a re-vendor surfaces as an explicit "authored against pin
+ * X, applying onto pin Y" instead of silent success.
+ */
+
+/** One mount's version + orphan findings — the D9 acceptance-criteria shape. */
+export interface OverlayApplyReport {
+  gameId: string;
+  /** `authoredAgainst.gameVersion` from the loaded overlay envelope, or `null` if never stamped. */
+  authoredAgainst: string | null;
+  /** The currently-mounted game's manifest `version`, or `null` if unknown at this call site. */
+  currentVersion: string | null;
+  /** Both sides known AND different — never true if either side is `null` (anti-shim: no guessing). */
+  versionMismatch: boolean;
+  applied: number;
+  /** Structural-path ids present in the overlay that resolved to nothing on this scene walk. */
+  orphanedIds: string[];
+  /**
+   * R5 — upstream-pin identity check (see this module's header). Distinct
+   * from `versionMismatch`/`orphanedIds`: it catches a same-slot
+   * SUBSTITUTION (id persists, meaning changed) that those two cannot.
+   */
+  upstreamPin: {
+    /** The pin the overlay was authored against, or `null` if never recorded/discoverable. */
+    authored: string | null;
+    /** The currently-mounted game's own discoverable pin, or `null` if undiscoverable here
+     * (e.g. the runtime ship-path applier, which has no `UPSTREAM.md` access at all — a
+     * documented no-op there — or an externally-authored, non-vendored project). */
+    current: string | null;
+    /**
+     * Whether the SAVED overlay envelope recorded the upstream-pin concept at
+     * all (i.e. `authoredAgainst.upstreamPin` was a present key, even if its
+     * value was `null`). `false` means a legacy overlay — saved by pre-R5
+     * code (or the pre-D9 flat-file shape) — for which the pin check is
+     * skipped entirely, not silently treated as a match. This is the
+     * "explicit legacy indication" the report surfaces so a legacy overlay's
+     * clean apply doesn't read as "verified" when it was never checked.
+     */
+    recorded: boolean;
+    /** `recorded` AND both sides known AND different — never true otherwise (anti-shim). */
+    mismatch: boolean;
+  };
+}
+
+/** Greppable prefix shared by every overlay-related log line (mirrors `achieved-tier.ts`'s `TIER_SHORTFALL_PREFIX`). */
+export const OVERLAY_REPORT_PREFIX = 'overlay-report';
+
+/** Build the report from a mount's raw findings — pure, no logging. */
+export function buildOverlayApplyReport(args: {
+  gameId: string;
+  authoredAgainst: string | null;
+  currentVersion: string | null;
+  applied: number;
+  orphanedIds: string[];
+  /**
+   * R5: the loaded overlay's `authoredAgainst.upstreamPin`. Pass `undefined`
+   * (or omit) when the saved envelope never had the key at all (legacy
+   * overlay — `upstreamPin.recorded` becomes `false`); pass `null` when the
+   * envelope DID have the key but its value was `null` (R5-aware code
+   * looked, found nothing — `recorded` is `true`, `authored` is `null`); pass
+   * the pin string otherwise.
+   */
+  authoredUpstreamPin?: string | null | undefined;
+  /**
+   * R5: the currently-mounted game's own discoverable pin, or `null`/omitted
+   * when undiscoverable at this call site (anti-shim: never fabricated).
+   */
+  currentUpstreamPin?: string | null | undefined;
+}): OverlayApplyReport {
+  const versionMismatch =
+    args.authoredAgainst !== null &&
+    args.currentVersion !== null &&
+    args.authoredAgainst !== args.currentVersion;
+  const recorded = args.authoredUpstreamPin !== undefined;
+  const authoredPin = args.authoredUpstreamPin ?? null;
+  const currentPin = args.currentUpstreamPin ?? null;
+  const upstreamPinMismatch =
+    recorded && authoredPin !== null && currentPin !== null && authoredPin !== currentPin;
+  return {
+    gameId: args.gameId,
+    authoredAgainst: args.authoredAgainst,
+    currentVersion: args.currentVersion,
+    applied: args.applied,
+    orphanedIds: args.orphanedIds,
+    versionMismatch,
+    upstreamPin: {
+      authored: authoredPin,
+      current: currentPin,
+      recorded,
+      mismatch: upstreamPinMismatch,
+    },
+  };
+}
+
+/** Whether this report is worth surfacing (mismatch OR any orphan) — pure, no logging. */
+export function overlayReportWarrants(report: OverlayApplyReport): boolean {
+  return report.versionMismatch || report.orphanedIds.length > 0 || report.upstreamPin.mismatch;
+}
+
+/** The one shared message shape — greppable on the prefix, JSON-parseable on the trailing payload. */
+export function formatOverlayApplyReportMessage(report: OverlayApplyReport): string {
+  const parts: string[] = [];
+  if (report.versionMismatch) {
+    parts.push(
+      `overlay authored against v${report.authoredAgainst}, game is v${report.currentVersion}`,
+    );
+  }
+  if (report.upstreamPin.mismatch) {
+    parts.push(
+      `overlay authored against upstream pin ${report.upstreamPin.authored}, ` +
+        `game is vendored at pin ${report.upstreamPin.current}`,
+    );
+  }
+  if (report.orphanedIds.length > 0) {
+    parts.push(
+      `${report.orphanedIds.length} orphaned overlay entr${report.orphanedIds.length === 1 ? 'y' : 'ies'}`,
+    );
+  }
+  return (
+    `${OVERLAY_REPORT_PREFIX} game "${report.gameId}": ${parts.join('; ')} ` +
+    `(D9, docs/DECISIONS-PENDING.md §D9; upstream-pin check R5, ` +
+    `docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)). ${OVERLAY_REPORT_PREFIX} ${JSON.stringify(report)}`
+  );
+}
+
+/**
+ * Emit the ONE structured `console.warn` this report warrants (mirroring the
+ * tier-shortfall pattern), or do nothing when neither signal fires. Returns
+ * whether it warned (callers that also want the panel-visible `editorConsole`
+ * echo, or the inline banner, use the return value / the report itself).
+ */
+export function logOverlayApplyReport(report: OverlayApplyReport): boolean {
+  if (!overlayReportWarrants(report)) return false;
+  // The D9 AC requires this EXACT native console.warn (spied on directly in
+  // overlay-versioning.test.ts) — other deliberate native console.warn call sites in
+  // this codebase (e.g. editor-store.ts) are unsuppressed and already counted in the
+  // lint baseline; this one is suppressed to keep this task's diff at zero NEW warnings.
+  // biome-ignore lint/suspicious/noConsole: see comment above
+  console.warn(formatOverlayApplyReportMessage(report));
+  return true;
+}