@vgai/engine 0.5.0 → 0.5.2

package/dist/adapter/ingest/overlay-applier.d.ts

@@ -1,118 +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 { type OverlayApplyReport } from './overlay-report';
-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;
-}
-/**
- * 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 declare function applyVgaiOverlay(options: ApplyVgaiOverlayOptions): Promise<ApplyVgaiOverlayResult>;
-//# sourceMappingURL=overlay-applier.d.ts.map

package/dist/adapter/ingest/overlay-applier.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"overlay-applier.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,qQAAqQ;IACrQ,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC,+IAA+I;IAC/I,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,+JAA+J;IAC/J,QAAQ,EAAE,OAAO,CAAC;IAClB,0HAA0H;IAC1H,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;CACnC;AA8BD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAgDjC"}

package/dist/adapter/ingest/overlay-applier.js

@@ -1,132 +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 { applyOverlayToObjects, assignStructuralIds } from './overlay-apply';
-import { overlayPath, parseOverlayFile } from './overlay-file';
-import { buildOverlayApplyReport, logOverlayApplyReport, OVERLAY_REPORT_PREFIX, } from './overlay-report';
-import { installSceneCapture } from './scene-capture';
-/** Shared warn helper — every graceful-failure path below logs through here. */
-function warn(gameId, message) {
-    // 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, gameId, fetchImpl) {
-    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 = 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) {
-    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;
-    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/dist/adapter/ingest/overlay-apply.d.ts

@@ -1,60 +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 type { IngestOverlay } from './overlay-file';
-/** Fixed id for the captured render camera (not a scene child, so no structural path). */
-export declare const CAMERA_ID = "ingest:camera";
-/** The single (non-array) standard-ish material of a mesh, if it has a color. */
-export declare function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | 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 declare function assignStructuralIds(scene: THREE.Object3D, camera?: THREE.Object3D | undefined): StructuralIdWalk;
-/** 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 declare function applyOverlayToObjects(byId: Map<string, THREE.Object3D>, overlay: IngestOverlay): OverlayApplyOutcome;
-//# sourceMappingURL=overlay-apply.d.ts.map

package/dist/adapter/ingest/overlay-apply.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"overlay-apply.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,0FAA0F;AAC1F,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAEzC,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAKpF;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CA4BlB;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACjC,OAAO,EAAE,aAAa,GACrB,mBAAmB,CAkBrB"}

package/dist/adapter/ingest/overlay-apply.js

@@ -1,101 +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 { setUserData } from '../../scene/user-data';
-/** 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) {
-    const mat = o.material;
-    if (!mat || Array.isArray(mat))
-        return null;
-    const m = mat;
-    return m.color ? m : null;
-}
-/**
- * (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, camera) {
-    const byId = new Map();
-    let count = 0;
-    let meshes = 0;
-    let lights = 0;
-    const visit = (o, path) => {
-        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 };
-}
-/**
- * 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, overlay) {
-    let applied = 0;
-    const orphanedIds = [];
-    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/dist/adapter/ingest/overlay-file.d.ts

@@ -1,79 +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 declare 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 declare function overlayPath(gameId: string): string;
-/** The empty envelope — no overlay found / nothing authored yet. */
-export declare function emptyOverlayFile(): OverlayFile;
-/**
- * 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 declare function parseOverlayFile(raw: unknown): OverlayFile;
-//# sourceMappingURL=overlay-file.d.ts.map

package/dist/adapter/ingest/overlay-file.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"overlay-file.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE3D,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,IAAI,WAAW,CAM9C;AAYD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CA0B1D"}

package/dist/adapter/ingest/overlay-file.js

@@ -1,66 +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.
- */
-/** Current on-disk envelope format version (D9, docs/DECISIONS-PENDING.md §D9). */
-export const OVERLAY_FORMAT_VERSION = 1;
-/** Where a game's overlay lives, project-root-relative (also the ship path's default fetch URL). */
-export function overlayPath(gameId) {
-    return `.vgai/overlays/${gameId}.json`;
-}
-/** The empty envelope — no overlay found / nothing authored yet. */
-export function emptyOverlayFile() {
-    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) {
-    return (!!raw &&
-        typeof raw === 'object' &&
-        'formatVersion' in raw &&
-        'overrides' in raw);
-}
-/**
- * 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) {
-    if (isEnvelope(raw)) {
-        const rawAuthored = (raw.authoredAgainst ?? { gameVersion: null });
-        const 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 ?? {}),
-    };
-}