@vgai/live 0.5.22 → 0.5.24

package/dist/{editor.d.ts → vgai-live/src/editor.d.ts}

@@ -1,14 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (Wave 2). Methods are named after the
+ * page }`. Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
  * separate `selectAll`, `showPanel('viewport-play')` rather than
  * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
  * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
- * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
- * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
+ * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
+ * escape hatch: every method goes over the wire.
  */
 import type { ActiveDocumentCapture, AnimationCaptureAction, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, OpenedDocument, PresentedEditorView, RagdollGenerationResult, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
 import { LiveEditorDocument } from './editor-document.js';
@@ -40,11 +40,8 @@ export declare class LiveEditor {
     constructor(client: EditorClient);
     /**
      * The active authoring adapter's persistence destination — where a save would
-     * land (`status().savePath`).
-     *
-     * WO-8: this also took a `path` and OPENED that scene through
-     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
-     * (the `.vscn.json` format is deleted), so only the read remains.
+     * land (`status().savePath`). A read only: a three root has no scene document
+     * to open, and its root is activated instead.
      */
     scene(): Promise<string | null>;
     /**

package/dist/{editor.js → vgai-live/src/editor.js}

@@ -1,14 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (Wave 2). Methods are named after the
+ * page }`. Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
  * separate `selectAll`, `showPanel('viewport-play')` rather than
  * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
  * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
- * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
- * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
+ * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
+ * escape hatch: every method goes over the wire.
  */
 import { LiveEditorDocument } from './editor-document.js';
 import { LiveGameplayRecording } from './recording.js';
@@ -72,11 +72,8 @@ export class LiveEditor {
     }
     /**
      * The active authoring adapter's persistence destination — where a save would
-     * land (`status().savePath`).
-     *
-     * WO-8: this also took a `path` and OPENED that scene through
-     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
-     * (the `.vscn.json` format is deleted), so only the read remains.
+     * land (`status().savePath`). A read only: a three root has no scene document
+     * to open, and its root is activated instead.
      */
     async scene() {
         const state = await this.#client.getState();
@@ -98,13 +95,6 @@ export class LiveEditor {
     async captureActiveDocument(size) {
         return this.#client.captureActiveDocument(size);
     }
-    /*
-     * `applyDiff` lived here. It dispatched `project.scene.apply`, one of the
-     * twelve `.vscn` document tools deleted with the format, so there is nothing
-     * left for it to call. `ApplyDiffInput` / `ApplyDiffResult` went with it, and
-     * so did `projectRoot` — this was the ONE method that used it (every other
-     * method goes over the wire).
-     */
     async play(opts) {
         await this.#client.play(opts);
     }

package/dist/{game-client → vgai-live/src/game-client}/bridge-transport.d.ts

@@ -52,7 +52,7 @@ export interface BridgeTransport {
      *  blank/corrupt file. */
     screenshot(path: string): Promise<CaptureNotes>;
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal `async (page) => {...}` (`GameClient.page()`,
      * `client.ts`). `src` is `step.toString()`; `step` is the ORIGINAL
      * function, wrapped so its own parameter type is erased to `unknown` (only
@@ -76,6 +76,15 @@ export interface BridgeTransport {
      * serialized — inline every value the step needs.
      */
     runPageScript(src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /**
+     * THE MODULE LANE — run a step INSIDE the editor page against
+     * `{ page, modules, instanceId }`, where `modules(path)` imports the
+     * RUNNING mount's own instance of a project module (never a phantom
+     * second copy). Same serialization contract as `runPageScript`: the
+     * step's source travels as text, closures do not survive, and the return
+     * value must be plain data. `instance` scopes multi-instance sessions.
+     */
+    runGameScript(src: string, step: (scope: unknown) => unknown, instance?: string): Promise<BridgeCallOutcome>;
     /**
      * P20 — reload the document showing the game, resolving only once the page
      * is BACK and taking commands again.

package/dist/{game-client → vgai-live/src/game-client}/client.d.ts

@@ -33,12 +33,19 @@ export declare class PageTransport implements BridgeTransport {
      *  (`capture-notes.ts`) exists on this leg. `{}` says that honestly rather
      *  than inventing a clean bill of health. */
     screenshot(path: string): Promise<CaptureNotes>;
-    /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+    /** The ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
      *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
      *  to satisfy the shared interface). */
     runPageScript(_src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /** THE MODULE LANE under a real Playwright host: the step's source is
+     *  evaluated INSIDE the editor page via the same in-page handler the relay
+     *  op uses (`window.__vgaiGameEval`), because `modules()` only means
+     *  anything in the page's own module space — a Node-side call could never
+     *  hand back the running mount's instances. Same serialization contract
+     *  as the relay leg. */
+    runGameScript(src: string, _step: (scope: unknown) => unknown, instance?: string): Promise<BridgeCallOutcome>;
     /** Playwright's own reload already waits for the new document's `load`
      *  event, which is exactly the completion signal this method's contract
      *  asks for — nothing to reconstruct on this leg. */
@@ -275,14 +282,12 @@ export declare class GameClient {
      * `events.expect`'s failure path each shoot a frame on their own
      * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
      * observer may shoot one from inside a callback the driver never sees. The
-     * only place that sees ALL of them is here, which is why an autoplay run
-     * stamps its captures by listening rather than by intercepting
-     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
-     * listener).
+     * only place that sees ALL of them is here, which is why a driving tool
+     * stamps its captures by listening rather than by intercepting.
      */
     onCapture(listener: CaptureListener): () => void;
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface
      * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
      * executing Playwright"). Under `PageTransport` this drives the REAL
@@ -298,6 +303,31 @@ export declare class GameClient {
      * `runPageScript` doc comment for the full contract this method wraps.
      */
     page<T = unknown>(step: (page: Page) => T | Promise<T>): Promise<T>;
+    /**
+     * THE MODULE LANE — run literal JS INSIDE the game's page, with the
+     * running mount's modules in reach:
+     *
+     * ```js
+     * await game.run(async ({ modules }) => {
+     *   const { simHost } = await modules('src/sim/host.ts');
+     *   return simHost().state.day;
+     * })
+     * ```
+     *
+     * `scope` is `{ page, modules, instanceId }`. Serialization contract as
+     * `game.page()`: the step travels as source (no closures), and the return
+     * value must be plain data. `modules(path)` resolves through the ACTIVE
+     * mount's own url space, so what you touch IS the running game — never a
+     * phantom second copy. Dev-server sessions only; a shipped build's curated
+     * surface is its adapter exports.
+     */
+    run<T = unknown>(step: (scope: {
+        page: Page;
+        modules: (path: string) => Promise<Record<string, unknown>>;
+        instanceId: string;
+    }) => T | Promise<T>, opts?: {
+        instance?: string;
+    }): Promise<T>;
     /**
      * Reload the document showing the game, resolving only once it is back and
      * answering commands (see `bridge-transport.ts`'s `reloadPage`).

package/dist/{game-client → vgai-live/src/game-client}/client.js

@@ -111,7 +111,7 @@ export class PageTransport {
         await this.page.screenshot({ path });
         return {};
     }
-    /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+    /** The ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
      *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
@@ -128,6 +128,30 @@ export class PageTransport {
             };
         }
     }
+    /** THE MODULE LANE under a real Playwright host: the step's source is
+     *  evaluated INSIDE the editor page via the same in-page handler the relay
+     *  op uses (`window.__vgaiGameEval`), because `modules()` only means
+     *  anything in the page's own module space — a Node-side call could never
+     *  hand back the running mount's instances. Same serialization contract
+     *  as the relay leg. */
+    async runGameScript(src, _step, instance) {
+        try {
+            const result = await this.page.evaluate(async (args) => {
+                const hook = window['__vgaiGameEval'];
+                if (typeof hook !== 'function') {
+                    throw new Error('game-eval: this page has no __vgaiGameEval hook — is the editor page loaded?');
+                }
+                return hook(args.src, args.instance);
+            }, { src, ...(instance === undefined ? {} : { instance }) });
+            return { ok: true, result };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: { code: undefined, message: err instanceof Error ? err.message : String(err) },
+            };
+        }
+    }
     /** Playwright's own reload already waits for the new document's `load`
      *  event, which is exactly the completion signal this method's contract
      *  asks for — nothing to reconstruct on this leg. */
@@ -422,6 +446,9 @@ export class GameClient {
     /** Per-test tick-rate samples, fed by every `snapshot()` read (a poll the
      *  client was making anyway — zero extra page.evaluate round trips). */
     #tps = new TpsAccumulator();
+    /** True after the settled run-ticks door proved absent on this page (an older exported
+     *  game's engine) — see `fastForward`'s `runTicksBatch`. */
+    #legacyRunTicksDoor = false;
     /** Hidden-tab recovery (hollowstone field lesson: the engine hard-stops
      *  while `document.hidden`). Client-lifetime state so `bringToFront()`
      *  fires at most once per test, across ALL waitFor/waitSimTime loops. */
@@ -504,7 +531,30 @@ export class GameClient {
         // names neither the method nor the shape).
         assertValidWaitForBudget(budget, 'fastForward');
         const clock = {
-            runTicksBatch: (n, render) => this.callBridgeVoid('runTicks', n, { render }),
+            // The SETTLED door (`runTicksSettled`, an async bridge method): ticks never race a scene
+            // remount's async commit, so which tick first runs a freshly reloaded world is
+            // deterministic (see engine/runtime/run-ticks-settled.ts — measured: without it, one
+            // drive script produced 7 or 8 post-respawn walked ticks depending on wall timing).
+            // Falls back ONCE to the plain sync door for a page whose engine predates the method
+            // (an older exported game), and remembers the verdict for the rest of the burst.
+            runTicksBatch: async (n, render) => {
+                if (this.#legacyRunTicksDoor) {
+                    await this.callBridgeVoid('runTicks', n, { render });
+                    return;
+                }
+                try {
+                    await this.callBridgeAsync('runTicksSettled', n, { render });
+                }
+                catch (error) {
+                    const code = error.code;
+                    const message = error instanceof Error ? error.message : String(error);
+                    const doorAbsent = code === 'UNKNOWN_BRIDGE_METHOD' || /is not a function|undefined/i.test(message);
+                    if (!doorAbsent)
+                        throw error;
+                    this.#legacyRunTicksDoor = true;
+                    await this.callBridgeVoid('runTicks', n, { render });
+                }
+            },
             readTime: async () => {
                 // Raw bridge read — deliberately NOT `this.snapshot()`, which would
                 // feed the TpsAccumulator (see fast-forward.ts's module doc, point 2).
@@ -529,7 +579,7 @@ export class GameClient {
                 snapshot: () => this.snapshot(),
                 now: () => Date.now(),
                 sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-                // Fixture heartbeat (Wave-6 findings ledger) — real stdout, the
+                // Fixture heartbeat — real stdout, the
                 // same channel a caller watching stdout already treats as
                 // liveness (see wait-for.ts's module doc for the emission
                 // invariant `maybeHeartbeat` enforces).
@@ -565,7 +615,7 @@ export class GameClient {
         const start = await this.snapshot();
         let lastTick = null;
         let stalledPolls = 0;
-        // Fixture heartbeat (Wave-6 findings ledger) — same invariant as
+        // Fixture heartbeat — same invariant as
         // `wait-for.ts`'s `runWaitFor`: a heartbeat requires BOTH 60s of wall
         // silence AND the tick having advanced since the last one emitted, so a
         // genuinely stalled sim clock (caught by `stalledPolls` above, ~30s)
@@ -646,10 +696,8 @@ export class GameClient {
      * `events.expect`'s failure path each shoot a frame on their own
      * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
      * observer may shoot one from inside a callback the driver never sees. The
-     * only place that sees ALL of them is here, which is why an autoplay run
-     * stamps its captures by listening rather than by intercepting
-     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
-     * listener).
+     * only place that sees ALL of them is here, which is why a driving tool
+     * stamps its captures by listening rather than by intercepting.
      */
     onCapture(listener) {
         this.#captureListeners.add(listener);
@@ -658,7 +706,7 @@ export class GameClient {
         };
     }
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface
      * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
      * executing Playwright"). Under `PageTransport` this drives the REAL
@@ -678,6 +726,29 @@ export class GameClient {
         const outcome = await this.#transport.runPageScript(step.toString(), erased);
         return this.unwrap(outcome);
     }
+    /**
+     * THE MODULE LANE — run literal JS INSIDE the game's page, with the
+     * running mount's modules in reach:
+     *
+     * ```js
+     * await game.run(async ({ modules }) => {
+     *   const { simHost } = await modules('src/sim/host.ts');
+     *   return simHost().state.day;
+     * })
+     * ```
+     *
+     * `scope` is `{ page, modules, instanceId }`. Serialization contract as
+     * `game.page()`: the step travels as source (no closures), and the return
+     * value must be plain data. `modules(path)` resolves through the ACTIVE
+     * mount's own url space, so what you touch IS the running game — never a
+     * phantom second copy. Dev-server sessions only; a shipped build's curated
+     * surface is its adapter exports.
+     */
+    async run(step, opts) {
+        const erased = (arg) => step(arg);
+        const outcome = await this.#transport.runGameScript(step.toString(), erased, opts?.instance);
+        return this.unwrap(outcome);
+    }
     /**
      * Reload the document showing the game, resolving only once it is back and
      * answering commands (see `bridge-transport.ts`'s `reloadPage`).

package/dist/{game-client → vgai-live/src/game-client}/relay-transport.d.ts

@@ -52,6 +52,17 @@ export declare class RelayTransport implements BridgeTransport {
     private hiddenCache;
     private readonly instance;
     constructor(opts: RelayTransportOptions);
+    /**
+     * Deliberately NOT guarded against a page-fallback answer the way the browser
+     * (`packages/editor/src/editor-server-response.ts`) and the CLI client
+     * (`@vgai/editor-sdk`'s `EditorClient.readJson`) are. Those two can be pointed
+     * at an arbitrary URL — a share tunnel, a static host — where a `200
+     * text/html` for an unserved route is real. This `baseUrl` is
+     * `http://127.0.0.1:<port>` and nothing else, and `session.ts` has already
+     * PROVED that port is this project's editor server (`probeServedProject`, whose
+     * own unparseable-answer path is exactly the refusal): a foreign occupant is
+     * refused there, before any command reaches here.
+     */
     private postCommand;
     /** Maps the relay's wire body back onto the transport-neutral
      *  `BridgeCallOutcome` — `result` on success, `code`/`error`/the rest of
@@ -67,7 +78,7 @@ export declare class RelayTransport implements BridgeTransport {
      *
      * It runs on every leg, not just `call('snapshot')`, because that is where
      * the measured gap was: a bot that drives the game with `hold`/`command` and
-     * reads through them — the shape `npm run playtest` actually has — could run
+     * reads through them could run
      * its entire session against a backgrounded tab and never be told, so a
      * later failure read as a generic relay timeout instead of "your tab is
      * hidden". Returns whether the tab is hidden so `call` can decide whether to
@@ -89,7 +100,7 @@ export declare class RelayTransport implements BridgeTransport {
     bringToFront(): Promise<void>;
     screenshot(path: string): Promise<CaptureNotes>;
     /**
-     * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+     * Ships `src` (`step.toString()`) to the editor dev server's
      * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
      * above), not a `bridge-call` method (see `command-listener.ts`'s
      * `handlePageScript` doc comment for why). `step` itself is unused on this
@@ -98,6 +109,8 @@ export declare class RelayTransport implements BridgeTransport {
      * `PageTransport` (which DOES call it directly) also implements.
      */
     runPageScript(src: string, _step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+    runGameScript(src: string, _step: (scope: unknown) => unknown, instance?: string): Promise<BridgeCallOutcome>;
     /**
      * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
      *

package/dist/{game-client → vgai-live/src/game-client}/relay-transport.js

@@ -57,6 +57,17 @@ export class RelayTransport {
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.instance = opts.instance;
     }
+    /**
+     * Deliberately NOT guarded against a page-fallback answer the way the browser
+     * (`packages/editor/src/editor-server-response.ts`) and the CLI client
+     * (`@vgai/editor-sdk`'s `EditorClient.readJson`) are. Those two can be pointed
+     * at an arbitrary URL — a share tunnel, a static host — where a `200
+     * text/html` for an unserved route is real. This `baseUrl` is
+     * `http://127.0.0.1:<port>` and nothing else, and `session.ts` has already
+     * PROVED that port is this project's editor server (`probeServedProject`, whose
+     * own unparseable-answer path is exactly the refusal): a foreign occupant is
+     * refused there, before any command reaches here.
+     */
     async postCommand(body, timeoutMs) {
         const res = await fetch(`${this.baseUrl}/__editor/command`, {
             method: 'POST',
@@ -119,7 +130,7 @@ export class RelayTransport {
      *
      * It runs on every leg, not just `call('snapshot')`, because that is where
      * the measured gap was: a bot that drives the game with `hold`/`command` and
-     * reads through them — the shape `npm run playtest` actually has — could run
+     * reads through them could run
      * its entire session against a backgrounded tab and never be told, so a
      * later failure read as a generic relay timeout instead of "your tab is
      * hidden". Returns whether the tab is hidden so `call` can decide whether to
@@ -132,7 +143,14 @@ export class RelayTransport {
             // P21: what was measured, and what this run is doing about it — not a
             // claim about where the tab is. The reading is a `presence` snapshot
             // (`isHidden` below), which ages between the tab's own reports.
-            process.stdout.write('vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
+            // STDERR, not stdout. `vgai status` and every other `--json`-shaped verb
+            // put their PAYLOAD on stdout and every banner on stderr; this notice went
+            // to stdout and prepended a prose sentence to the JSON, so any machine
+            // consumer piping `vgai status` into a parser got a SyntaxError the moment
+            // the tab happened to be hidden — measured while reading the coverage
+            // table on a backgrounded session. A diagnostic that breaks the payload it
+            // annotates is worse than no diagnostic.
+            process.stderr.write('vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
                 'stops its loop while the page reports itself hidden, so this run drives ' +
                 'deterministic runTicks through the session relay instead of wall clock. Sim time ' +
                 'advances either way; `vgai status` prints that reading with its age.\n');
@@ -228,7 +246,7 @@ export class RelayTransport {
         return notes;
     }
     /**
-     * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+     * Ships `src` (`step.toString()`) to the editor dev server's
      * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
      * above), not a `bridge-call` method (see `command-listener.ts`'s
      * `handlePageScript` doc comment for why). `step` itself is unused on this
@@ -252,6 +270,23 @@ export class RelayTransport {
             };
         }
     }
+    /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+    async runGameScript(src, _step, instance) {
+        try {
+            const body = await this.postCommand({ type: 'game-eval', src, ...(instance === undefined ? {} : { instance }) }, PAGE_SCRIPT_TIMEOUT_MS);
+            return this.toBridgeOutcome(body);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: {
+                    code: 'RELAY_UNREACHABLE',
+                    message: `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+                        `${err instanceof Error ? err.message : String(err)}`,
+                },
+            };
+        }
+    }
     /**
      * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
      *

package/dist/{game-client → vgai-live/src/game-client}/types.d.ts

@@ -41,15 +41,15 @@ export interface DebugBridgeInput {
     setVirtualAction(action: string, value: VirtualActionValue): VirtualActionResult;
     tapVirtualAction(action: string): VirtualActionResult;
     clearVirtualActions(): void;
-    /** D15/T-D15.5 — schedule a virtual actuation for a specific tick, applied
-     *  at the start of that tick's input phase. Declared here (Wave-2
-     *  bridge↔wire coverage-parity gate) for type-shape completeness with
+    /** Schedule a virtual actuation for a specific tick, applied
+     *  at the start of that tick's input phase. Declared here for the
+     *  bridge↔wire coverage-parity gate — type-shape completeness with
      *  `runtime/debug-bridge.ts`'s `VgaiDebugInputHandle` — this package still
      *  exposes no client-side convenience wrapper around it (deliberately
      *  parked; see `GameInput` in `client.ts`), this is pure type-shape
      *  mirroring. */
     scheduleActionAtTick(tick: number, action: string, value: VirtualActionValue): void;
-    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+    /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
      *  `VgaiDebugInputHandle.injectPointerDelta`: accumulates a synthetic
      *  pointer delta for a named test source (sums within a frame, clears each
      *  frame). Declared here for type-shape completeness with the bridge, same
@@ -59,7 +59,7 @@ export interface DebugBridgeInput {
         x: number;
         y: number;
     }): void;
-    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+    /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
      *  `VgaiDebugInputHandle.injectPointerPosition`: sets a synthetic absolute
      *  pointer position for a named test source (last-write-wins, persists
      *  until changed). Same type-shape-only precedent as `scheduleActionAtTick`. */

package/dist/{game-client → vgai-live/src/game-client}/wait-for.js

@@ -96,7 +96,7 @@ export class WaitForTimeoutError extends Error {
     }
 }
 // ---------------------------------------------------------------------------
-// Fixture heartbeat (Wave-6 findings ledger: "Watchdog sim-awareness / fixture
+// Fixture heartbeat ("Watchdog sim-awareness / fixture
 // heartbeat for long silent tests" — Session C hit exit-5 on the runner's
 // 2x90s stdout-liveness watchdog during a legitimately silent 5-minute test).
 //
@@ -107,7 +107,7 @@ export class WaitForTimeoutError extends Error {
 // advancing test can never false-wedge regardless of duration, no matter how
 // long a single `simSeconds` budget runs.
 //
-// INVARIANT (tested below and in fixture.test.ts): a heartbeat requires BOTH
+// INVARIANT (tested below): a heartbeat requires BOTH
 // (a) >= HEARTBEAT_INTERVAL_MS of wall time since the last heartbeat, AND
 // (b) the tick has ADVANCED since the last heartbeat (not merely since the
 // last poll). Without (b), the poll loop itself — which keeps running

package/dist/{game.d.ts → vgai-live/src/game.d.ts}

@@ -20,7 +20,7 @@ import { GameClient } from './game-client/index.js';
 /** A `GameClient` addressing ONE mounted instance, tagged with the mount `id`
  *  it drives. `id` is the whole point of the handle to a CALLER: it is what
  *  `tools.run(name, args, { instance: handle.id })` passes to scope a
- *  node-hosted tool (e.g. `project.autoplay`) to this seat — the two-seat
+ *  node-hosted tool to this seat — the two-seat
  *  multiplayer verification pattern. Without it the caller has a client it can
  *  drive but no id to hand a tool, so the seat-scoped path silently degrades to
  *  the sole-instance one. */

package/dist/{index.d.ts → vgai-live/src/index.d.ts}

@@ -34,8 +34,8 @@
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
  *
- * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
- * PR #166) — write `step` as a literal `async (page) => {...}` and inline
+ * `page(step)` = `GameClient.page(step)`, the playwright-shim surface —
+ * write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
  * binds to, `step` is shipped to the editor dev server as `step.toString()`
  * and reconstructed there — closures over outer variables do NOT survive that

package/dist/{index.js → vgai-live/src/index.js}

@@ -34,8 +34,8 @@
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
  *
- * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
- * PR #166) — write `step` as a literal `async (page) => {...}` and inline
+ * `page(step)` = `GameClient.page(step)`, the playwright-shim surface —
+ * write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
  * binds to, `step` is shipped to the editor dev server as `step.toString()`
  * and reconstructed there — closures over outer variables do NOT survive that

package/dist/{recording.js → vgai-live/src/recording.js}

@@ -36,17 +36,10 @@ export class LiveGameplayRecording {
             await copyFile(capture.path, path);
         }
         return {
+            ...capture,
+            // The caller's `destination` copy, when there was one — otherwise the
+            // project path the recorder wrote. Spread first so this wins.
             path,
-            startedAt: capture.startedAt,
-            mimeType: capture.mimeType,
-            width: capture.width,
-            height: capture.height,
-            fps: capture.fps,
-            audio: capture.audio,
-            durationMs: capture.durationMs,
-            droppedFrames: capture.droppedFrames,
-            frameErrors: capture.frameErrors,
-            layers: capture.layers,
         };
     }
 }

package/dist/{session.d.ts → vgai-live/src/session.d.ts}

@@ -76,11 +76,4 @@ export interface ProjectSessionHint {
     url: string;
     startedAt: string;
 }
-/**
- * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
- * running `vgai edit` session. Throws a descriptive error (never hangs
- * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
- * silently attaches to an unrelated project's session — see the module doc
- * above) when no vgai.project.json is found, or no live session covers it.
- */
 export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;