@vgai/engine 0.5.13 → 0.5.14

package/dist/adapter/ingest/mount-readiness.d.ts

@@ -0,0 +1,84 @@
+/**
+ * READINESS, declared vs measured — and the three sentences a failed mount is
+ * allowed to say (M29).
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": the system answers
+ * a question by reading a DECLARATION, by walking ground truth, or by
+ * diagnosing declared-vs-measured drift — and a guess at a fact the game's
+ * author could have stated is a defect whose fix is a declaration slot. "Is
+ * this game ready?" was the guess: the host polled draw counts, watched a
+ * scene's child count stop growing, and waited fixed windows.
+ *
+ * The declaration is `window.vgaiGame.ready` ({@link VgaiGameReady} in
+ * `game-contract.ts`) for a self-booting game, and MOUNT COMPLETION for a
+ * host-mounted (exported-composition) root — the host runs that mount, so it
+ * answers the question without the game writing a line. The measured waits
+ * stay for everything else; what they stop being is silent, which is what
+ * {@link ReadinessSource} is for.
+ *
+ * M29's defect: a game that threw during its own async init reported as
+ * "rendered no capturable frame within timeout" — the wait's expiry, which is a
+ * CONSEQUENCE of the crash, presented as the blocker. It misdirected two sweep
+ * measurements. {@link describeMountFailure} is the fix: three different
+ * sentences pointing at three different blockers, chosen from facts the host
+ * already has (did the game declare readiness; did anything throw during its
+ * boot window).
+ */
+/**
+ * WHERE a readiness answer came from.
+ *
+ * `declared` — the game (or, for a host-mounted root, the host's own completed
+ * mount) STATED it. `measured` — nobody stated it, so a host-side wait stood in.
+ * Both are legitimate; only one of them is a fact about the game, which is why
+ * every reporting surface carries this field instead of presenting the two as
+ * the same answer.
+ */
+export type ReadinessSource = 'declared' | 'measured';
+/**
+ * The three blockers a mount that never reached a live world can have. Carried
+ * on the report so a reader (status bar, `vgai status`, the Console line) can
+ * branch without re-parsing the sentence.
+ */
+export type MountFailureKind = 
+/** Something threw during the game's own boot window. Fix that first. */
+'crashed-before-ready'
+/** The game DECLARED `ready`, yet no capturable render arrived and nothing
+ *  was thrown. (The host awaits `ready` only after the first captured
+ *  render, so whether it resolved was not observed — the sentence states
+ *  exactly that.) */
+ | 'declared-ready-never-resolved'
+/** No declaration at all: the measured fallback wait is what expired. */
+ | 'no-readiness-declaration';
+export interface MountFailureDescription {
+    readonly kind: MountFailureKind;
+    /** The one sentence every surface prints. */
+    readonly message: string;
+    /** The errors thrown during the boot window, ATTACHED rather than left for
+     *  the reader to correlate by timestamp in a console they may not have open.
+     *  Empty for the two non-crash kinds. */
+    readonly pageErrors: readonly string[];
+}
+export interface MountFailureInput {
+    /** The game's manifest/root id, as every other report names it. */
+    readonly gameId: string;
+    /** The capture window that expired, in VISIBLE ms. */
+    readonly timeoutMs: number;
+    /** Where the readiness answer would have come from — see {@link ReadinessSource}. */
+    readonly readinessSource: ReadinessSource;
+    /** Errors observed during the game's boot window, oldest first. */
+    readonly pageErrors: readonly string[];
+    /** The underlying rejection's own text, kept verbatim at the end. */
+    readonly cause: string;
+}
+/**
+ * Which of the three sentences this failure gets.
+ *
+ * A CRASH wins over everything: if something threw during the boot window,
+ * every other reading is downstream of it, and the old single sentence's whole
+ * defect was reporting the downstream one. After that the split is the
+ * declaration itself — a game that stated `ready` and never resolved it has a
+ * different blocker (and a different owner) from a game that stated nothing and
+ * outlasted a host-side guess.
+ */
+export declare function describeMountFailure(input: MountFailureInput): MountFailureDescription;
+//# sourceMappingURL=mount-readiness.d.ts.map

package/dist/adapter/ingest/mount-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-readiness.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/mount-readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB;AAC1B,yEAAyE;AACvE,sBAAsB;AACxB;;;qBAGqB;GACnB,+BAA+B;AACjC,yEAAyE;GACvE,0BAA0B,CAAC;AAE/B,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;6CAEyC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAQD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,uBAAuB,CA8CtF"}

package/dist/adapter/ingest/mount-readiness.js

@@ -0,0 +1,81 @@
+/**
+ * READINESS, declared vs measured — and the three sentences a failed mount is
+ * allowed to say (M29).
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": the system answers
+ * a question by reading a DECLARATION, by walking ground truth, or by
+ * diagnosing declared-vs-measured drift — and a guess at a fact the game's
+ * author could have stated is a defect whose fix is a declaration slot. "Is
+ * this game ready?" was the guess: the host polled draw counts, watched a
+ * scene's child count stop growing, and waited fixed windows.
+ *
+ * The declaration is `window.vgaiGame.ready` ({@link VgaiGameReady} in
+ * `game-contract.ts`) for a self-booting game, and MOUNT COMPLETION for a
+ * host-mounted (exported-composition) root — the host runs that mount, so it
+ * answers the question without the game writing a line. The measured waits
+ * stay for everything else; what they stop being is silent, which is what
+ * {@link ReadinessSource} is for.
+ *
+ * M29's defect: a game that threw during its own async init reported as
+ * "rendered no capturable frame within timeout" — the wait's expiry, which is a
+ * CONSEQUENCE of the crash, presented as the blocker. It misdirected two sweep
+ * measurements. {@link describeMountFailure} is the fix: three different
+ * sentences pointing at three different blockers, chosen from facts the host
+ * already has (did the game declare readiness; did anything throw during its
+ * boot window).
+ */
+/** The clause every kind shares: hidden time was not charged to the game, so
+ *  nobody reads this as a backgrounded-tab failure (it was, twice). */
+const VISIBLE_TIME_CLAUSE = 'Time the tab spent hidden was NOT counted against it, so this is not a backgrounded-tab ' +
+    'failure.';
+/**
+ * Which of the three sentences this failure gets.
+ *
+ * A CRASH wins over everything: if something threw during the boot window,
+ * every other reading is downstream of it, and the old single sentence's whole
+ * defect was reporting the downstream one. After that the split is the
+ * declaration itself — a game that stated `ready` and never resolved it has a
+ * different blocker (and a different owner) from a game that stated nothing and
+ * outlasted a host-side guess.
+ */
+export function describeMountFailure(input) {
+    const { gameId, timeoutMs, readinessSource, pageErrors, cause } = input;
+    const budget = `${timeoutMs}ms of VISIBLE time`;
+    if (pageErrors.length > 0) {
+        const listed = pageErrors.map((error) => `  · ${error}`).join('\n');
+        return {
+            kind: 'crashed-before-ready',
+            pageErrors: [...pageErrors],
+            message: `Ingest game "${gameId}" CRASHED BEFORE IT BECAME READY: ${pageErrors.length} error(s) ` +
+                `were thrown while it was booting, and the capture window (${budget}) then expired. ` +
+                'The expiry is a CONSEQUENCE of the crash, not the blocker — fix these first:\n' +
+                `${listed}\n` +
+                `${VISIBLE_TIME_CLAUSE} Underlying wait: ${cause}`,
+        };
+    }
+    if (readinessSource === 'declared') {
+        return {
+            kind: 'declared-ready-never-resolved',
+            pageErrors: [],
+            message: `Ingest game "${gameId}" DECLARED A READINESS SIGNAL AND STILL PRODUCED NO CAPTURABLE ` +
+                `RENDER: it stated \`window.vgaiGame.ready\`, but the capture window (${budget}) expired ` +
+                "before the editor's three saw a render, and nothing was thrown. (The host awaits " +
+                '`ready` only after the first captured render, so whether it resolved was not observed.) ' +
+                "Nothing is wrong with the host's wait — the likely blocker is whatever the game's own " +
+                'boot is waiting on (an asset fetch, a socket, a user gesture the editor never makes), ' +
+                'or a game that draws through a renderer the capture trap cannot see. ' +
+                `${VISIBLE_TIME_CLAUSE} Underlying wait: ${cause}`,
+        };
+    }
+    return {
+        kind: 'no-readiness-declaration',
+        pageErrors: [],
+        message: `Ingest game "${gameId}" DECLARED NO READINESS SIGNAL, and the MEASURED fallback wait ` +
+            `expired: the editor's three saw no render within ${budget} and nothing was thrown, so ` +
+            'the host has no way to tell a slow boot from a stopped one. Recovery: declare ' +
+            '`window.vgaiGame.ready` (a promise resolved when the game has built its world) so this ' +
+            'question stops being measured — or, if the game genuinely needs longer on screen, raise ' +
+            `"captureTimeoutMs" in the root's ingest block. ${VISIBLE_TIME_CLAUSE} ` +
+            `Underlying wait: ${cause}`,
+    };
+}

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

@@ -49,6 +49,7 @@
  * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
  */
 import type * as THREE from 'three';
+import { type VisibilityClock, type VisibleCaptureWindow } from './visible-capture-window';
 /** A live runtime captured from an external game on its first rendered frame. */
 export interface CapturedRuntime {
     scene: THREE.Scene;
@@ -79,7 +80,65 @@ export interface SceneCaptureOptions {
      * so (`packages/editor/src/host-renderers.ts`).
      */
     isHostRenderer?: (renderer: unknown) => boolean;
+    /**
+     * The game's OWN declared world, read from its contract
+     * (`window.vgaiGame` — the host passes a reader, never a cached value, because
+     * the contract is declared by the game's modules and may not exist yet when
+     * the trap installs).
+     *
+     * When it answers non-null, the DECLARATION decides: only a render of that
+     * scene is adopted, and first-render-wins never runs. When it answers null —
+     * the case for every game that declares nothing — behaviour is unchanged and
+     * the adoption is reported as `measured`.
+     */
+    declaredScene?: () => unknown;
+    /**
+     * How the world was adopted, and every DISTINCT world seen afterwards.
+     *
+     * First-non-host-render-wins is a good measured default and a permanent,
+     * SILENT commitment: a splash scene, a shadow pre-pass, or a
+     * render-to-texture warm-up that happens to draw first is adopted as the game
+     * forever, and the real world that renders one frame later reaches no reader
+     * at all. This is that reader. It never changes which world is adopted — it
+     * makes the ambiguity a recorded fact (`packages/editor/src/world-adoption.ts`
+     * publishes it to `vgai status`).
+     *
+     * Post-processing games legitimately render several (scene, camera) pairs per
+     * frame, so alternates are INFORMATION, never an error. Host renders are
+     * excluded by the same `isHostRenderer` declaration the adoption itself uses.
+     */
+    onWorldAdoption?: (event: WorldAdoptionEvent) => void;
 }
+/**
+ * One world-adoption fact. `adopted` fires exactly once, when the trap commits
+ * to a (scene, camera, renderer) triple; `alternate` fires for each DISTINCT
+ * triple seen afterwards, up to {@link MAX_RECORDED_ALTERNATES}.
+ */
+export type WorldAdoptionEvent = {
+    readonly phase: 'adopted';
+    /** `declared` = the contract named this scene; `measured` = first render won. */
+    readonly source: 'declared' | 'measured';
+    readonly sceneId: string;
+    readonly cameraId: string;
+} | {
+    readonly phase: 'alternate';
+    readonly sceneId: string;
+    readonly cameraId: string;
+    /** `false` ⇒ a SECOND renderer is drawing, which is the stronger signal. */
+    readonly sameRenderer: boolean;
+    /** Draws observed when this alternate first appeared — how far past the
+     *  adoption it is, without a wall clock. */
+    readonly drawCount: number;
+};
+/**
+ * How many distinct alternates are recorded before the trap stops looking.
+ *
+ * The bound is the point: this runs inside the game's own render call, and a
+ * post-processing chain can present a new (scene, camera) pair every frame. A
+ * handful names the ambiguity; an unbounded set would turn a diagnostic into a
+ * leak on the hottest path in the process.
+ */
+export declare const MAX_RECORDED_ALTERNATES = 8;
 /**
  * Brackets ONE `render()` call the captured renderer makes.
  *
@@ -99,6 +158,27 @@ export interface RenderPassHooks {
     before(): void;
     after(): void;
 }
+/**
+ * Options for {@link SceneCaptureHandle.waitForCapture}. Passing a bare number
+ * is the same as `{ timeoutMs }` — the shape every existing caller uses.
+ */
+export interface CaptureWaitOptions {
+    /** The capture window, in VISIBLE milliseconds (default 10s). */
+    timeoutMs?: number | undefined;
+    /** Injected in tests; defaults to the document's own visibility. */
+    visibility?: VisibilityClock | undefined;
+    /**
+     * Called with a LIVE view of the wait when it begins, and with `null` the
+     * moment it ends (captured, expired, or the window was cancelled).
+     *
+     * A wait parked on a hidden tab is otherwise indistinguishable from a hung
+     * mount: nothing renders, nothing fails, and every door reports silence.
+     * This is the seam the editor publishes to `vgai status` so the answer is
+     * "waiting for the first visible frame — the tab is hidden", not a
+     * countdown that is not running.
+     */
+    onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
     /** The captured runtime, or null until the game renders its first frame. */
@@ -111,8 +191,17 @@ export interface SceneCaptureHandle {
      * renders come through the same trap and are not the game's frame.
      */
     setRenderPassHooks(hooks: RenderPassHooks | null): void;
-    /** Resolve once a scene+camera is captured (rejects on timeout). */
-    waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
+    /**
+     * Resolve once a scene+camera is captured.
+     *
+     * The timeout is a budget of **visible** time, not wall-clock time: a hidden
+     * document cannot render (the browser parks rAF), so counting hidden time
+     * against the game is counting time it was not allowed to use. The wait
+     * therefore PARKS while `document.hidden` and resumes on `visibilitychange`
+     * — see `visible-capture-window.ts` for the whole argument. Rejects only
+     * when the window is spent with the document VISIBLE.
+     */
+    waitForCapture(options?: number | CaptureWaitOptions): 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

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

@@ -1 +1 @@
-{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;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,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACjD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IACxD,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,EAC5B,IAAI,CAAC,EAAE,mBAAmB,GACzB,kBAAkB,CAoOpB"}
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"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"}

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

@@ -48,6 +48,25 @@
  * against the `bloom-composer` fixture
  * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
  */
+import { startVisibleCaptureWindow, } from './visible-capture-window';
+/**
+ * How many distinct alternates are recorded before the trap stops looking.
+ *
+ * The bound is the point: this runs inside the game's own render call, and a
+ * post-processing chain can present a new (scene, camera) pair every frame. A
+ * handful names the ambiguity; an unbounded set would turn a diagnostic into a
+ * leak on the hottest path in the process.
+ */
+export const MAX_RECORDED_ALTERNATES = 8;
+/** A three object's identity, as a string a status facet can carry. `type` is
+ *  what a reader recognizes ("Scene", "PerspectiveCamera"); `uuid` is what
+ *  makes two of the same type tellable apart. */
+function objectId(value) {
+    const obj = value;
+    const type = typeof obj?.type === 'string' ? obj.type : 'unknown';
+    const uuid = typeof obj?.uuid === 'string' ? obj.uuid : '(no uuid)';
+    return `${type}:${uuid}`;
+}
 /**
  * Install the render accessor trap on `threeNamespace.WebGLRenderer.prototype`.
  * Pass the host's `three` module so the game (which shares it) is trapped.
@@ -69,6 +88,14 @@ export function installSceneCapture(threeNamespace, effectComposerCtor, opts) {
     const REAL = Symbol('vgai.realRender');
     let captured = null;
     let drawCount = 0;
+    /** Memoized answer of `opts.declaredScene` — asked each render until it
+     *  answers, because a game declares its contract from its own modules and may
+     *  not have run yet when the trap installs. Once it answers, it is fixed:
+     *  a declaration that changes mid-boot is not a thing the host chases. */
+    let declaredScene = null;
+    /** Distinct alternates already reported, keyed by the same triple identity the
+     *  event carries — see {@link MAX_RECORDED_ALTERNATES} for why it is bounded. */
+    const seenAlternates = new Set();
     /** Set post-capture by the host; see {@link SceneCaptureHandle.setRenderPassHooks}. */
     let renderPassHooks = null;
     const waiters = [];
@@ -123,6 +150,59 @@ export function installSceneCapture(threeNamespace, effectComposerCtor, opts) {
             hooks.after();
         }
     }
+    /**
+     * Commit to a world, DECLARATION FIRST.
+     *
+     * First-non-host-render-wins is the measured default and a permanent one, so
+     * a game that states which scene is its world is not made to race its own
+     * splash screen. `declaredScene` is asked until it answers (the game's own
+     * modules declare the contract, and may not have run when the trap installed);
+     * once it does, only that scene is adopted.
+     */
+    function adoptWorld(self, scene, camera) {
+        if (declaredScene === null)
+            declaredScene = opts?.declaredScene?.() ?? null;
+        if (declaredScene !== null && declaredScene !== scene)
+            return;
+        captured = {
+            scene: scene,
+            camera: camera,
+            renderer: self,
+        };
+        opts?.onWorldAdoption?.({
+            phase: 'adopted',
+            source: declaredScene === null ? 'measured' : 'declared',
+            sceneId: objectId(scene),
+            cameraId: objectId(camera),
+        });
+        for (const resolve of waiters.splice(0))
+            resolve(captured);
+    }
+    /**
+     * A DISTINCT world drew after the adopted one. Recorded, never acted on:
+     * which world is adopted does not change (that would break every handle the
+     * host already built from it) — but the reader stops being the only party who
+     * could have noticed. Deduped and bounded because this is the game's own
+     * render call.
+     */
+    function recordAlternateWorld(self, scene, camera) {
+        if (!captured || seenAlternates.size >= MAX_RECORDED_ALTERNATES)
+            return;
+        if (scene === captured.scene && camera === captured.camera)
+            return;
+        const sameRenderer = self === captured.renderer;
+        const key = `${objectId(scene)}|${objectId(camera)}|${sameRenderer}`;
+        if (seenAlternates.has(key))
+            return;
+        seenAlternates.add(key);
+        opts?.onWorldAdoption?.({
+            phase: 'alternate',
+            sceneId: objectId(scene),
+            cameraId: objectId(camera),
+            sameRenderer,
+            drawCount,
+        });
+    }
     Object.defineProperty(proto, 'render', {
         configurable: true,
         set(fn) {
@@ -153,15 +233,11 @@ export function installSceneCapture(threeNamespace, effectComposerCtor, opts) {
                 // Whether that happened at all came down to whether the editor
                 // rendered a frame inside the game's capture window, so the same
                 // session could pass or fail on timing alone.
-                const isHostRender = opts?.isHostRenderer?.(self) === true;
-                if (!captured && !isHostRender && scene && scene.isScene) {
-                    captured = {
-                        scene: scene,
-                        camera: camera,
-                        renderer: self,
-                    };
-                    for (const resolve of waiters.splice(0))
-                        resolve(captured);
+                if (opts?.isHostRenderer?.(self) !== true && scene?.isScene) {
+                    if (captured)
+                        recordAlternateWorld(self, scene, camera);
+                    else
+                        adoptWorld(self, scene, camera);
                 }
                 return forwardRender(self, args);
             };
@@ -226,22 +302,38 @@ export function installSceneCapture(threeNamespace, effectComposerCtor, opts) {
                 composer.setPixelRatio(pixelRatio);
             }
         },
-        waitForCapture(timeoutMs = 10_000) {
+        waitForCapture(options) {
+            const opts = typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
+            const timeoutMs = opts.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);
+                // A budget of VISIBLE time. The window disarms itself while the
+                // document is hidden and resumes when it comes back, so a tab that
+                // boots in the background waits instead of dying — and the trap it is
+                // waiting on stays installed the whole time, which is what makes the
+                // first frame after foregrounding a capture rather than a retry.
+                const captureWindow = startVisibleCaptureWindow({
+                    budgetMs: timeoutMs,
+                    ...(opts.visibility !== undefined ? { clock: opts.visibility } : {}),
+                    onExpire: () => {
+                        const i = waiters.indexOf(wrapped);
+                        if (i >= 0)
+                            waiters.splice(i, 1);
+                        opts.onWait?.(null);
+                        reject(new Error(`Scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
+                            `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
+                            'a hidden tab cannot render) — the game never rendered, ' +
+                            'or it bundles its own (un-shared) copy of three.'));
+                    },
+                });
                 const wrapped = (rt) => {
-                    clearTimeout(timer);
+                    captureWindow.cancel();
+                    opts.onWait?.(null);
                     resolve(rt);
                 };
                 waiters.push(wrapped);
+                opts.onWait?.(captureWindow);
             });
         },
         uninstall() {

package/dist/adapter/ingest/structural-ids.d.ts

@@ -3,14 +3,14 @@
  * reflection helper that rides along with it) the editor's live-three authoring
  * adapter uses to address the objects of a world whose source carries no
  * serve-time identity stamps
- * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ * (`packages/editor/src/projection/three.ts`, `structuralIdentity`).
  *
  * Identity: each object gets a **structural-path id** — deterministic from the
  * scene's shape (position in the tree + three.js type + name), so the SAME id
  * re-binds to the SAME object after the game rebuilds its scene within a
- * session. 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.
+ * session. The pure walk returns that identity beside the native objects; the
+ * editor keeps the reverse lookup in its authoring adapter rather than writing
+ * editor currency into a foreign graph.
  *
  * This module used to be the shared core of a per-game JSON sidecar
  * persistence system, which was deleted outright (2026-08-02) — ingest edits
@@ -38,7 +38,7 @@ export interface StructuralIdWalk {
     lights: number;
 }
 /**
- * (Re)assign structural-path ids to every object under `scene` (and, if
+ * (Re)collect structural-path ids for 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) — so a re-walk after the game rebuilds part of its
@@ -60,5 +60,11 @@ export interface StructuralIdWalk {
  * hierarchy/inspector projections built on this walk, where they were
  * selectable and colorable as if they were game content.
  */
+export declare function collectStructuralIds(scene: THREE.Object3D, camera?: THREE.Object3D | undefined): StructuralIdWalk;
+/**
+ * Compatibility entry point for first-party callers that explicitly want
+ * structural ids stamped into their own graph. Foreign ingest authoring uses
+ * {@link collectStructuralIds} and never calls this mutating form.
+ */
 export declare function assignStructuralIds(scene: THREE.Object3D, camera?: THREE.Object3D | undefined): StructuralIdWalk;
 //# sourceMappingURL=structural-ids.d.ts.map

package/dist/adapter/ingest/structural-ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structural-ids.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/structural-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,0FAA0F;AAC1F,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAoBzC;;;;;;;GAOG;AACH,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CAgClB"}
+{"version":3,"file":"structural-ids.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/structural-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,0FAA0F;AAC1F,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAoBzC;;;;;;;GAOG;AACH,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CA8BlB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CAIlB"}

package/dist/adapter/ingest/structural-ids.js

@@ -3,14 +3,14 @@
  * reflection helper that rides along with it) the editor's live-three authoring
  * adapter uses to address the objects of a world whose source carries no
  * serve-time identity stamps
- * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ * (`packages/editor/src/projection/three.ts`, `structuralIdentity`).
  *
  * Identity: each object gets a **structural-path id** — deterministic from the
  * scene's shape (position in the tree + three.js type + name), so the SAME id
  * re-binds to the SAME object after the game rebuilds its scene within a
- * session. 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.
+ * session. The pure walk returns that identity beside the native objects; the
+ * editor keeps the reverse lookup in its authoring adapter rather than writing
+ * editor currency into a foreign graph.
  *
  * This module used to be the shared core of a per-game JSON sidecar
  * persistence system, which was deleted outright (2026-08-02) — ingest edits
@@ -31,7 +31,7 @@ export const CAMERA_ID = 'ingest:camera';
 const EDITOR_ONLY_LAYER_MASK = 1 << 31;
 /**
  * Editor furniture, not game content. Excluded from the walk entirely — see
- * {@link assignStructuralIds} for why that exclusion is what makes the id
+ * {@link collectStructuralIds} for why that exclusion is what makes the id
  * scheme's central promise true.
  */
 function isEditorOnly(o) {
@@ -53,7 +53,7 @@ export function colorMaterialOf(o) {
     return m?.color ? m : null;
 }
 /**
- * (Re)assign structural-path ids to every object under `scene` (and, if
+ * (Re)collect structural-path ids for 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) — so a re-walk after the game rebuilds part of its
@@ -75,14 +75,13 @@ export function colorMaterialOf(o) {
  * hierarchy/inspector projections built on this walk, where they were
  * selectable and colorable as if they were game content.
  */
-export function assignStructuralIds(scene, camera) {
+export function collectStructuralIds(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)
@@ -102,9 +101,19 @@ export function assignStructuralIds(scene, camera) {
     };
     visitChildren(scene, '');
     if (camera) {
-        setUserData(camera, 'entityId', CAMERA_ID);
         byId.set(CAMERA_ID, camera);
         count++;
     }
     return { byId, count, meshes, lights };
 }
+/**
+ * Compatibility entry point for first-party callers that explicitly want
+ * structural ids stamped into their own graph. Foreign ingest authoring uses
+ * {@link collectStructuralIds} and never calls this mutating form.
+ */
+export function assignStructuralIds(scene, camera) {
+    const walk = collectStructuralIds(scene, camera);
+    for (const [id, object] of walk.byId)
+        setUserData(object, 'entityId', id);
+    return walk;
+}

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

@@ -27,8 +27,10 @@
  *   - 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.
+ * backtick-code full (or abbreviated) git SHA. Every BUNDLE-vendored game in
+ * this repo (`tanks`, `simcity`) follows this exact shape. Source-tree
+ * vendored games carry their pin in `vendor/games/<id>.UPSTREAM.lock`'s
+ * machine-readable `commit` instead and never reach this parser.
  */
 /**
  * Extract the pinned upstream commit hash from a vendored game's

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

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

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

@@ -27,8 +27,10 @@
  *   - 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.
+ * backtick-code full (or abbreviated) git SHA. Every BUNDLE-vendored game in
+ * this repo (`tanks`, `simcity`) follows this exact shape. Source-tree
+ * vendored games carry their pin in `vendor/games/<id>.UPSTREAM.lock`'s
+ * machine-readable `commit` instead and never reach this parser.
  */
 /** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */
 const COMMIT_BULLET_RE = /-\s*Commit:\s*\*\*`([0-9a-fA-F]{7,40})`\*\*/;