@vgai/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1,103 @@
+/**
+ * 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

@@ -0,0 +1,97 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,248 @@
+/**
+ * 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

@@ -0,0 +1,47 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}

package/dist/adapter/ingest/upstream-pin.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */
+const COMMIT_BULLET_RE = /-\s*Commit:\s*\*\*`([0-9a-fA-F]{7,40})`\*\*/;
+/**
+ * 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 function extractUpstreamPin(markdown) {
+    return COMMIT_BULLET_RE.exec(markdown)?.[1] ?? null;
+}

package/dist/adapter/loop-gate-report.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
+ * (`gated | self-driven`) as independent of capability tier: a `self-driven`
+ * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
+ * its adapter implements an explicit loop-gate capability
+ * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
+ * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
+ * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
+ * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
+ * silence a world's audio on pause must report, not pretend.
+ *
+ * Pure compute + message-formatting, same split as `achieved-tier.ts`
+ * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
+ * `console.warn`/`editorConsole.warn` call; this module never logs.
+ */
+/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
+ *  could not actually be gated). */
+export declare const LOOP_GATE_PREFIX = "loop-gate";
+/** Greppable prefix for an audio-gate shortfall (pause requested, world's
+ *  audio could not actually be silenced). */
+export declare const AUDIO_GATE_PREFIX = "audio-gate";
+/** One shortfall instance: which world, and why the capability wasn't there. */
+export interface CapabilityGateReport {
+    readonly worldId: string;
+    readonly reason: string;
+}
+/** Format a loop-gate shortfall message (a `self-driven` world with no
+ *  working pause capability). */
+export declare function formatLoopGateMessage(report: CapabilityGateReport): string;
+/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
+ *  whose adapter cannot actually silence it). */
+export declare function formatAudioGateMessage(report: CapabilityGateReport): string;
+//# sourceMappingURL=loop-gate-report.d.ts.map

package/dist/adapter/loop-gate-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-gate-report.d.ts","sourceRoot":"","sources":["../../src/adapter/loop-gate-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;oCACoC;AACpC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;6CAC6C;AAC7C,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAcD;iCACiC;AACjC,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE1E;AAED;iDACiD;AACjD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE3E"}

package/dist/adapter/loop-gate-report.js

@@ -0,0 +1,37 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
+ * (`gated | self-driven`) as independent of capability tier: a `self-driven`
+ * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
+ * its adapter implements an explicit loop-gate capability
+ * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
+ * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
+ * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
+ * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
+ * silence a world's audio on pause must report, not pretend.
+ *
+ * Pure compute + message-formatting, same split as `achieved-tier.ts`
+ * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
+ * `console.warn`/`editorConsole.warn` call; this module never logs.
+ */
+/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
+ *  could not actually be gated). */
+export const LOOP_GATE_PREFIX = 'loop-gate';
+/** Greppable prefix for an audio-gate shortfall (pause requested, world's
+ *  audio could not actually be silenced). */
+export const AUDIO_GATE_PREFIX = 'audio-gate';
+function formatGateMessage(prefix, capability, report) {
+    return (`${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
+        `(${report.reason}) — reporting honestly instead of silently no-op-ing ` +
+        `(docs/CAPABILITY-TIERS.md §d). ${prefix} ${JSON.stringify(report)}`);
+}
+/** Format a loop-gate shortfall message (a `self-driven` world with no
+ *  working pause capability). */
+export function formatLoopGateMessage(report) {
+    return formatGateMessage(LOOP_GATE_PREFIX, "this world's loop", report);
+}
+/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
+ *  whose adapter cannot actually silence it). */
+export function formatAudioGateMessage(report) {
+    return formatGateMessage(AUDIO_GATE_PREFIX, "this world's audio", report);
+}

package/dist/adapter/rapier-physics-adapter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * RapierPhysicsAdapter — the first-party `PhysicsAdapter` over the existing
+ * `PhysicsRegistry` (Object3D ↔ Rapier body/collider). This is the generalized,
+ * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
+ * the editor freeze a body, apply a gizmo edit, and resume — without the editor
+ * knowing Rapier exists.
+ */
+import type * as THREE from 'three';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { PhysicsAdapter } from './system-adapter';
+export declare function createRapierPhysicsAdapter(registry: PhysicsRegistry, debugMesh?: THREE.Object3D | null): PhysicsAdapter;
+//# sourceMappingURL=rapier-physics-adapter.d.ts.map

package/dist/adapter/rapier-physics-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rapier-physics-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/rapier-physics-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAChC,cAAc,CAsChB"}