@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

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 ?? {}),
-    };
-}

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

@@ -1,113 +0,0 @@
-/**
- * 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 declare const OVERLAY_REPORT_PREFIX = "overlay-report";
-/** Build the report from a mount's raw findings — pure, no logging. */
-export declare 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;
-/** Whether this report is worth surfacing (mismatch OR any orphan) — pure, no logging. */
-export declare function overlayReportWarrants(report: OverlayApplyReport): boolean;
-/** The one shared message shape — greppable on the prefix, JSON-parseable on the trailing payload. */
-export declare function formatOverlayApplyReportMessage(report: OverlayApplyReport): string;
-/**
- * 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 declare function logOverlayApplyReport(report: OverlayApplyReport): boolean;
-//# sourceMappingURL=overlay-report.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"overlay-report.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+FAA+F;IAC/F,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qGAAqG;IACrG,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE;QACX,0FAA0F;QAC1F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB;;wFAEgF;QAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB;;;;;;;;WAQG;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,wFAAwF;QACxF,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,wHAAwH;AACxH,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAChD,GAAG,kBAAkB,CAwBrB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEzE;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAuBlF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CASzE"}

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

@@ -1,103 +0,0 @@
-/**
- * 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.
- */
-/** 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) {
-    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) {
-    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) {
-    const parts = [];
-    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) {
-    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;
-}

package/dist/adapter/ingest/scene-capture.d.ts

@@ -1,97 +0,0 @@
-/**
- * Scene capture — the core primitive of unmodified-game ingestion.
- *
- * An external three.js game owns its own `WebGLRenderer`, `Scene`, camera, and
- * render loop. To let the editor inspect/edit that live scene WITHOUT touching
- * the game's code, we need a handle to the game's `Scene`+camera the moment it
- * first renders. The robust way to obtain it is an **accessor trap** on
- * `WebGLRenderer.prototype.render`:
- *
- *   - `WebGLRenderer` assigns `this.render` as an OWN instance property inside
- *     its constructor (not on the prototype), and `THREE.WebGLRenderer` is a
- *     read-only module export (can't subclass-swap it). A naive "wrap render"
- *     hook therefore captures nothing.
- *   - Installing a getter/setter for `render` on the PROTOTYPE means the
- *     constructor's `this.render = realFn` hits our setter (the instance has no
- *     own `render` yet), we stash the real fn, and our getter returns a wrapper
- *     that captures `(scene, camera, renderer)` on the first real frame.
- *
- * This is the hardened, typed form of the `ingest-study` spike
- * (`docs/ingest-study-spike/vgai-ingest-adapter.js`), proven against an
- * unmodified `three.js/examples/games_fps` game.
- *
- * CRITICAL: the trap must be installed on the SAME `three` module instance the
- * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
- * three`), an external ESM game's `import 'three'` resolves to that one instance,
- * so passing the host's `THREE` here traps the game's renderer too. A game that
- * bundles its own copy of `three` cannot be captured this way (see
- * `docs/UNMODIFIED-GAME-INGESTION-STUDY.md` §4A — the module-identity gatekeeper).
- *
- * Wave 17 (`docs/WAVE17-F13-COMPOSER-RESIZE-FIX-DESIGN.md`) adds an OPTIONAL,
- * ADDITIVE composer capture: a game rendering through its own three.js addon
- * `EffectComposer` (`three/examples/jsm/postprocessing/EffectComposer.js`)
- * still trips the `render` trap above (its `RenderPass` calls
- * `renderer.render(scene,camera)` internally), but the renderer holds no
- * reference back to the composer, so the host previously could not resize the
- * composer's own (intentionally non-1:1, progressively-downsampled — see
- * `UnrealBloomPass`) render targets when the host resizes the game's pane.
- * Unlike `WebGLRenderer`, `EffectComposer` is a plain ES class whose methods
- * (including `render`) live on the PROTOTYPE, not assigned as own instance
- * properties in the constructor — so a direct method-wrapper (no getter/
- * setter indirection) on `EffectComposer.prototype.render` is sufficient: it
- * calls through to the real `render`, then — AFTER that call, so any nested
- * `renderer.render()` the pass makes has already hit the trap above and set
- * `captured` — records `this` (the composer instance) if its `.renderer` is
- * the captured one. This is deduped/shared-trappable for the same reason
- * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
- * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
- * instance — not a separate package with its own dedupe question. Proven
- * live against the `bloom-composer` fixture
- * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
- */
-import type * as THREE from 'three';
-/** A live runtime captured from an external game on its first rendered frame. */
-export interface CapturedRuntime {
-    scene: THREE.Scene;
-    camera: THREE.Camera;
-    renderer: THREE.WebGLRenderer;
-}
-/** Handle returned by {@link installSceneCapture}. */
-export interface SceneCaptureHandle {
-    /** The captured runtime, or null until the game renders its first frame. */
-    readonly captured: CapturedRuntime | null;
-    /** Resolve once a scene+camera is captured (rejects on timeout). */
-    waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
-    /** Total `render()` calls observed through the trap (a liveness signal). */
-    getDrawCount(): number;
-    /** The game's last (non-null) `setAnimationLoop` callback for a renderer, so the
-     *  host can pause (set null) and resume (re-set it) the game's own loop. */
-    getAnimationLoop(renderer: THREE.WebGLRenderer): ((time: number) => void) | null;
-    /**
-     * Wave 17 (D-C3): resize every captured `EffectComposer` that renders
-     * through the captured renderer to `w`×`h`, matching its pixel ratio to
-     * `renderer.getPixelRatio()` — the composer tracks whatever DPR policy the
-     * host already applies to the renderer; no separate knob. A no-op when no
-     * `effectComposerCtor` was passed to {@link installSceneCapture} (or no
-     * composer of that ctor has rendered through the captured renderer yet) —
-     * a non-composer game is unaffected.
-     */
-    resizeComposers(w: number, h: number): void;
-    /** Remove the trap and restore the captured renderer's real `render`. */
-    uninstall(): void;
-}
-/**
- * Install the render accessor trap on `threeNamespace.WebGLRenderer.prototype`.
- * Pass the host's `three` module so the game (which shares it) is trapped.
- *
- * `effectComposerCtor` is OPTIONAL (Wave 17, D-C2): pass the host's
- * `EffectComposer` class (`three/examples/jsm/postprocessing/EffectComposer.js`)
- * to also trap composer construction/rendering on that shared addon, so
- * `resizeComposers()` can reach it. Omitting it (or a game never constructing
- * one) leaves capture byte-identical to before this wave.
- *
- * Idempotent per call site is NOT guaranteed — install once per ingest session
- * and `uninstall()` on teardown.
- */
-export declare function installSceneCapture(threeNamespace: unknown, effectComposerCtor?: unknown): SceneCaptureHandle;
-//# sourceMappingURL=scene-capture.d.ts.map

package/dist/adapter/ingest/scene-capture.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;CAC/B;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C,oEAAoE;IACpE,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,YAAY,IAAI,MAAM,CAAC;IACvB;gFAC4E;IAC5E,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAAC;CACnB;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,OAAO,EACvB,kBAAkB,CAAC,EAAE,OAAO,GAC3B,kBAAkB,CAwLpB"}