@vgai/engine 0.5.0 → 0.5.2

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"}

package/dist/adapter/ingest/scene-capture.js

@@ -1,248 +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`).
- */
-/**
- * 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 function installSceneCapture(threeNamespace, effectComposerCtor) {
-    const THREE_NS = threeNamespace;
-    const proto = THREE_NS.WebGLRenderer.prototype;
-    // Stash the real render fn per-instance under a unique symbol so multiple
-    // renderers (editor's + game's) never collide.
-    const REAL = Symbol('vgai.realRender');
-    let captured = null;
-    let drawCount = 0;
-    const waiters = [];
-    // Preserve any descriptor already on the prototype so uninstall can restore it.
-    const priorDescriptor = Object.getOwnPropertyDescriptor(proto, 'render');
-    // Trap setAnimationLoop to record each renderer's game loop callback, so the host
-    // can freeze (set null) and resume (re-set) the game's own rAF for stable editing.
-    // CRITICAL: like `render`, WebGLRenderer assigns `this.setAnimationLoop` as an OWN
-    // instance property in its constructor — NOT on the prototype. A naive value-wrapper
-    // on the prototype is therefore shadowed by the instance's own property and never
-    // runs (resume could never recover the callback). So we mirror the `render` trap: a
-    // prototype getter/setter. The constructor's `this.setAnimationLoop = realFn` hits
-    // our SETTER (the instance has no own property yet) and we stash realFn per-instance;
-    // the GETTER returns a wrapper that records each non-null callback before forwarding.
-    const REAL_SAL = Symbol('vgai.realSetAnimationLoop');
-    const loopCallbacks = new WeakMap();
-    const priorSAL = Object.getOwnPropertyDescriptor(proto, 'setAnimationLoop');
-    Object.defineProperty(proto, 'setAnimationLoop', {
-        configurable: true,
-        set(fn) {
-            this[REAL_SAL] = fn;
-        },
-        get() {
-            const self = this;
-            return function setAnimationLoop(cb) {
-                if (cb)
-                    loopCallbacks.set(self, cb);
-                const real = self[REAL_SAL];
-                return typeof real === 'function'
-                    ? real.call(self, cb)
-                    : undefined;
-            };
-        },
-    });
-    Object.defineProperty(proto, 'render', {
-        configurable: true,
-        set(fn) {
-            this[REAL] = fn;
-        },
-        get() {
-            const self = this;
-            return function render(...args) {
-                const [scene, camera] = args;
-                drawCount++;
-                if (!captured && scene && scene.isScene) {
-                    captured = {
-                        scene: scene,
-                        camera: camera,
-                        renderer: self,
-                    };
-                    for (const resolve of waiters.splice(0))
-                        resolve(captured);
-                }
-                // Forward to the renderer's real render with the original args.
-                return self[REAL].apply(self, args);
-            };
-        },
-    });
-    // ---- Wave 17 (D-C2): additive composer capture, only when a composer ctor
-    // was passed. `EffectComposer` methods (including `render`) live on the
-    // PROTOTYPE (a plain ES class — the constructor never does `this.render =
-    // …`), so a direct method-wrapper suffices — no getter/setter indirection
-    // like the `render`/`setAnimationLoop` traps above need. ----
-    const composers = new Set();
-    let composerProto;
-    let priorComposerRender;
-    if (effectComposerCtor) {
-        const EC = effectComposerCtor;
-        composerProto = EC.prototype;
-        priorComposerRender = composerProto['render'];
-        composerProto['render'] = function (...args) {
-            // Call the real render FIRST: a composer's RenderPass calls
-            // `renderer.render(scene,camera)` internally, which is what actually
-            // sets `captured` (above) on the game's first frame. Checking after
-            // ensures a composer's very first render is still collected.
-            const result = priorComposerRender?.apply(this, args);
-            if (captured && this.renderer === captured.renderer) {
-                composers.add(this);
-            }
-            return result;
-        };
-    }
-    // Extracted so `uninstall()`'s own cognitive complexity doesn't grow with
-    // this additive Wave-17 restore step (biome's noExcessiveCognitiveComplexity).
-    function restoreComposerTrap() {
-        if (!composerProto)
-            return;
-        if (priorComposerRender)
-            composerProto['render'] = priorComposerRender;
-        else
-            delete composerProto['render'];
-    }
-    return {
-        get captured() {
-            return captured;
-        },
-        getDrawCount() {
-            return drawCount;
-        },
-        getAnimationLoop(renderer) {
-            return loopCallbacks.get(renderer) ?? null;
-        },
-        resizeComposers(w, h) {
-            // No composer ctor passed (or none constructed yet) → no-op, and never
-            // touches `renderer.getPixelRatio()` — a non-composer game's captured
-            // renderer need not even expose that method for this to stay a no-op.
-            if (!captured || composers.size === 0)
-                return;
-            const pixelRatio = captured.renderer.getPixelRatio();
-            for (const composer of composers) {
-                composer.setSize(w, h);
-                composer.setPixelRatio(pixelRatio);
-            }
-        },
-        waitForCapture(timeoutMs = 10_000) {
-            if (captured)
-                return Promise.resolve(captured);
-            return new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    const i = waiters.indexOf(wrapped);
-                    if (i >= 0)
-                        waiters.splice(i, 1);
-                    reject(new Error(`Scene capture timed out after ${timeoutMs}ms — the game never rendered, ` +
-                        `or it bundles its own (un-shared) copy of three.`));
-                }, timeoutMs);
-                const wrapped = (rt) => {
-                    clearTimeout(timer);
-                    resolve(rt);
-                };
-                waiters.push(wrapped);
-            });
-        },
-        uninstall() {
-            // Restore the captured renderer's real render as an OWN property so its
-            // loop keeps working after the prototype trap is removed.
-            if (captured) {
-                const r = captured.renderer;
-                const real = r[REAL];
-                if (typeof real === 'function') {
-                    Object.defineProperty(captured.renderer, 'render', {
-                        configurable: true,
-                        writable: true,
-                        value: real,
-                    });
-                }
-            }
-            if (priorDescriptor) {
-                Object.defineProperty(proto, 'render', priorDescriptor);
-            }
-            else {
-                delete proto['render'];
-            }
-            // Restore the captured renderer's real setAnimationLoop as an OWN property (the
-            // prototype getter/setter intercepted the constructor's assignment, so the
-            // instance has none) — else removing the prototype trap would leave it without
-            // setAnimationLoop and freeze its loop.
-            if (captured) {
-                const r = captured.renderer;
-                const realSal = r[REAL_SAL];
-                if (typeof realSal === 'function') {
-                    Object.defineProperty(captured.renderer, 'setAnimationLoop', {
-                        configurable: true,
-                        writable: true,
-                        value: realSal,
-                    });
-                }
-            }
-            if (priorSAL)
-                Object.defineProperty(proto, 'setAnimationLoop', priorSAL);
-            else
-                delete proto['setAnimationLoop'];
-            // Wave 17: fully restore the composer addon's `render` (a plain
-            // prototype method — no per-instance own-property to restore, unlike
-            // the renderer/loop traps above).
-            restoreComposerTrap();
-        },
-    };
-}

package/dist/adapter/ingest/upstream-pin.d.ts

@@ -1,47 +0,0 @@
-/**
- * Upstream-pin extraction — R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/
- * §7.1 item 9): the fix for the overlay identity gap the structural-id +
- * `authoredAgainst.gameVersion` scheme (T7.7/D9) does not close. A re-vendor
- * of a vendored upstream game that keeps a slot's shape (index + three.js
- * type + name unchanged) reapplies a saved overlay onto a semantically
- * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning
- * success — because `authoredAgainst.gameVersion` is the MANIFEST's own
- * `version` (hand-set by whoever wrote `vgai.game.json`, e.g. every
- * `public/ingest/*` vendored game ships `"version": "0.1.0"` regardless of
- * which upstream commit it vendors — see `public/ingest/{tanks,racing-game,
- * simcity}/vgai.game.json`), never tied to the thing that actually changes on
- * a re-vendor: the `UPSTREAM.md` pin.
- *
- * This module is the pure, dependency-free half (parse text -> pin, or
- * `null`): NO file I/O here, so it is usable from any context (editor
- * save/apply-time hooks over a fetched `/UPSTREAM.md`, a future Node-side
- * CLI check, tests). READ-ONLY by construction — it has no writer; this
- * codebase never generates or edits an `UPSTREAM.md` (the anti-shim rule:
- * adapters never fabricate first-party data, and a game's own vendoring
- * provenance is exactly that).
- *
- * Format (established convention, not invented here — see every
- * `public/ingest/*\/UPSTREAM.md`'s `## Upstream` section, e.g.
- * `public/ingest/tanks/UPSTREAM.md`):
- *
- *   ## Upstream
- *
- *   - Repo: https://github.com/colyseus/realtime-tanks-demo
- *   - Commit: **`6339493130b4b1d4d28f0f52d17b2fba738c7d47`**
- *
- * i.e. a Markdown bullet whose label is `Commit:` and whose value is a bold,
- * backtick-code full (or abbreviated) git SHA. Every vendored game in this
- * repo (`tanks`, `racing-game`, `simcity`) follows this exact shape.
- */
-/**
- * Extract the pinned upstream commit hash from a vendored game's
- * `UPSTREAM.md` prose, or `null` if the file doesn't follow the convention
- * (or wasn't found — the caller decides what a missing file means; this
- * function only parses text it's handed). Never throws — an unparseable
- * document is an honest `null`, not an error (anti-shim: no guessing, no
- * fabricating a pin from a game folder that doesn't declare one, e.g. an
- * externally-authored non-vendored project opened via the CLI-on-folder
- * route).
- */
-export declare function extractUpstreamPin(markdown: string): string | null;
-//# sourceMappingURL=upstream-pin.d.ts.map

package/dist/adapter/ingest/upstream-pin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"upstream-pin.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/upstream-pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAElE"}