@vgai/live 0.5.41 → 0.5.44

package/dist/game-client/capture-notes.js

@@ -2,17 +2,25 @@
  * What a capture knows about ITSELF beyond its pixels — and the one place the
  * caveat sentence is spelled.
  *
- * A PNG is silent about the conditions it was taken under. Two of those
- * conditions change what the frame is worth as evidence, and both are already
- * measured elsewhere in the stack: the editor page reports
+ * A PNG is silent about the conditions it was taken under. Four of those
+ * conditions matter, and each is already measured elsewhere in the stack.
+ * Three change what the frame is worth as EVIDENCE: the editor page reports
  * `loopRecoveryFrame` when the host loop was starved and the runtime had to
  * render one deterministic tick on demand (`command-listener.ts`'s
  * `handleBridgeScreenshot`), and it reports
  * a `flatness.warning` sentence when the frame is nine-tenths one flat surface
- * (`composite-screenshot.ts`'s `measureFlatness`). Until now both stopped at a
+ * (`composite-screenshot.ts`'s `measureFlatness`), and it names the CLIP a
+ * frame of a recorded run belongs to (`command-listener.ts`'s
+ * `screenshotRecordingNotice`). Until now these stopped at a
  * `console.warn` inside the relay transport — visible to a human watching a
  * terminal, invisible to anything that later reads the file.
  *
+ * The fourth is not about the frame at all but about what taking it COST: a
+ * capture written under the served project root goes through the dev server's
+ * file watcher on every shot (measured ~3x slower frame rates), and the
+ * out-path resolver is the only place that knows
+ * (`screenshot-target.ts`'s `underWatchedProjectRoot`).
+ *
  * So the transport seam carries them back as {@link CaptureNotes}, and
  * {@link describeCaptureCaveat} turns them into the ONE sentence every surface
  * says. Its two callers are the transport's own console warning and
@@ -23,15 +31,27 @@
 /** The loop-recovery sentence. Spelled once because it is said in two places
  *  (a live console warning and a persisted record) and a second copy is a
  *  second wording. */
+/**
+ * The cost of writing a capture INSIDE the served project.
+ *
+ * The dev server watches the project root, and its ignore list names build
+ * output only — nothing about capture output — so every PNG written under the
+ * root goes through the watcher. Measured cost class: ~3x slower frame rates
+ * while a capture loop wrote there. Named, not fixed: where a capture goes is
+ * the caller's decision, and this door's job is to stop that decision being
+ * made blind.
+ */
+const WATCHED_CAPTURE_PATH_CAVEAT = 'writing captures under the project root triggers the dev server’s file watcher; expect ~3× ' +
+    'slower frame rates — write outside the project or to the session’s own capture dir';
 const LOOP_RECOVERY_FRAME_CAVEAT = 'LOOP-RECOVERY FRAME — the host loop was starved, so the runtime rendered one ' +
     'deterministic tick on demand. It is current, not stale; it was not produced by ordinary presentation.';
 /**
  * What a reader must be told about this frame, or `null` when there is nothing
  * to tell.
  *
- * Both notes can be true at once (an on-demand recovery tick that also came
- * out near-blank), and both are said — a capture that is degraded twice over
- * must not report only the first reason.
+ * Any of them can be true at once (an on-demand recovery tick that also came
+ * out near-blank, in a recorded run), and each is said — a capture that is
+ * degraded twice over must not report only the first reason.
  */
 export function describeCaptureCaveat(notes) {
     const parts = [];
@@ -40,5 +60,12 @@ export function describeCaptureCaveat(notes) {
     if (typeof notes.flatnessWarning === 'string' && notes.flatnessWarning !== '') {
         parts.push(notes.flatnessWarning);
     }
+    if (typeof notes.recordingPath === 'string' && notes.recordingPath !== '') {
+        parts.push(`ONE FRAME of a recorded run — ${notes.recordingPath} holds the whole of it. A still ` +
+            'answers what it looks like; a temporal question (did the jump land) needs the clip.');
+    }
+    if (typeof notes.watchedProjectRoot === 'string' && notes.watchedProjectRoot !== '') {
+        parts.push(`${WATCHED_CAPTURE_PATH_CAVEAT} (${notes.watchedProjectRoot}).`);
+    }
     return parts.length === 0 ? null : parts.join(' ');
 }

package/dist/game-client/client.d.ts

@@ -9,7 +9,7 @@
 import type { Page } from '@playwright/test';
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
 import { type CaptureListener, type CaptureNotes } from './capture-notes.js';
-import { type FastForwardBudget, type FastForwardOptions } from './fast-forward.js';
+import { type FastForwardBudget, type FastForwardOptions, type FastForwardTime } from './fast-forward.js';
 import { type TpsStats } from './perf-sampling.js';
 import type { DebugCommandInfo, DebugSnapshot, ProviderInfo, VirtualActionValue } from './types.js';
 import { type WaitForBudget } from './wait-for.js';
@@ -87,6 +87,11 @@ export interface GameClientOptions {
      *  actually running). */
     fenceWallMs: number;
     artifactsDir?: string | undefined;
+    /** The project root the editor session is SERVING, when the caller knows it
+     *  (`@vgai/live`'s `connect()` does). Used for one thing: saying, in a
+     *  capture's own notes, that its destination falls under the dev server's
+     *  file watcher — see `capture-notes.ts`. Never used to resolve a path. */
+    projectRoot?: string | undefined;
     /** Set by the caller when it reused an already-running game server rather
      *  than booting a fresh one for this run. Threaded through so `unwrap` can
      *  append the warm-session staleness hint to a
@@ -252,6 +257,9 @@ export declare class GameClient {
      * AFTER the tps baseline reset below, so it never itself corrupts the tps
      * stats either).
      */
+    fastForward(budget: FastForwardBudget, opts: FastForwardOptions & {
+        result: 'time';
+    }): Promise<FastForwardTime>;
     fastForward(budget: FastForwardBudget, opts?: FastForwardOptions): Promise<DebugSnapshot>;
     waitFor(pred: (s: (name: string) => unknown) => boolean, budget: WaitForBudget): Promise<void>;
     /** Used by `input.hold` — waits for a sim-time delta to pass with no
@@ -329,10 +337,28 @@ export declare class GameClient {
      * 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.
+     *
+     * `modules(path)` IS ASYNC — it dynamic-imports that url — so the callback
+     * is `async` and the call is `await`ed, in every example on this page and
+     * everywhere else. Skipping it does not fail quietly: reading a member off
+     * the unawaited promise throws a message naming the fix, because
+     * `TypeError: modules(...).simHost is not a function` (measured, cold fox
+     * #3) says nothing about promises.
+     *
+     * `modules` IS A FUNCTION, not a table — there is no module registry. To ask
+     * what the mount has loaded, read `modules.loaded`, the project-relative
+     * paths you can pass straight back in:
+     *
+     * ```js
+     * await game.run(({ modules }) => modules.loaded)
+     * // → ['src/scenes/MainScene.tsx', 'src/world.tsx', …]
+     * ```
      */
     run<T = unknown>(step: (scope: {
         page: Page;
-        modules: (path: string) => Promise<Record<string, unknown>>;
+        modules: ((path: string) => Promise<Record<string, unknown>>) & {
+            readonly loaded: string[];
+        };
         instanceId: string;
     }) => T | Promise<T>, opts?: {
         instance?: string;

package/dist/game-client/client.js

@@ -77,6 +77,24 @@ async function bridgeCallInPageAsync(args) {
         };
     }
 }
+/**
+ * A relay step crosses the wire as function source, so compiler-owned helpers that live beside the
+ * function in its Node module are closures too. esbuild's `keepNames` transform is the live case:
+ * a named helper inside an otherwise literal callback becomes `__name(fn, "helper")`, while the
+ * module-level `__name` implementation is absent after `step.toString()`. Seat that exact compiler
+ * primitive inside the serialized function instead of installing a page global or asking every
+ * caller to avoid ordinary named local helpers.
+ *
+ * Ordinary source stays byte-for-byte unchanged. That preserves the public wire account and keeps
+ * unsupported user closures loud; this only completes the source for a compiler helper whose
+ * semantics are intrinsic and deterministic.
+ */
+function selfContainedStepSource(step) {
+    const source = step.toString();
+    if (!/\b__name\s*\(/u.test(source))
+        return source;
+    return `(scope) => { const __name = (target, value) => Object.defineProperty(target, "name", { value, configurable: true }); return (${source})(scope); }`;
+}
 /**
  * #140 — the `BridgeTransport` `page.evaluate` implementation. This is the
  * ONE place a `Page` is ever touched to drive `window.__vgai` (module doc
@@ -436,6 +454,8 @@ export class GameClient {
     #transport;
     /** Where a labelled `screenshot()` lands — project-scoped by `@vgai/live`, cwd-relative otherwise. Public: a caller reading it is asking a fair question, and `screenshot()` returns a path under it anyway. */
     artifactsDir;
+    /** See `GameClientOptions.projectRoot`. */
+    #projectRoot;
     /** See `GameClientOptions.warmSession`. */
     #warmSession;
     /** See `GameClientOptions.testTitle`. */
@@ -466,6 +486,7 @@ export class GameClient {
         this.fenceSimSeconds = opts.fenceSimSeconds;
         this.fenceWallMs = opts.fenceWallMs;
         this.artifactsDir = opts.artifactsDir ?? resolve('.vgai/last-run');
+        this.#projectRoot = opts.projectRoot;
         this.#warmSession = opts.warmSession ?? false;
         this.#testTitle = opts.testTitle ?? 'test';
         this.#bridgeHeartbeat = { lastEmitWallMs: Date.now() };
@@ -527,18 +548,6 @@ export class GameClient {
     hiddenRecoveryTriggered() {
         return this.#hiddenRecovery.wasTriggered();
     }
-    /**
-     * D15/T-D15.4 — synchronously drives `budget` worth of sim time/ticks via
-     * the live `Game`'s `runTicks` (through the debug bridge), instead of
-     * waiting for real wall-clock time to pass. Doctrine (see
-     * `fast-forward.ts`'s module doc, which also documents the two honesty
-     * decisions this wraps): SETUP/STAGING traversal — reaching a known
-     * late-game state fast — not a substitute for real-input proofs, which
-     * still run in real ticks. Returns the final `{time, state, events,
-     * pageErrors}` snapshot (a completely ordinary `snapshot()` read, taken
-     * AFTER the tps baseline reset below, so it never itself corrupts the tps
-     * stats either).
-     */
     async fastForward(budget, opts) {
         // Same options-object-only contract as `waitSimTime` (`ticksForBudget`
         // would otherwise fail on `'simTicks' in 0.5` with a raw TypeError that
@@ -570,21 +579,26 @@ export class GameClient {
                 }
             },
             readTime: async () => {
-                // Raw bridge read — deliberately NOT `this.snapshot()`, which would
-                // feed the TpsAccumulator (see fast-forward.ts's module doc, point 2).
-                const snap = await this.callBridge('snapshot');
-                return { tick: snap.time.tick, simSeconds: snap.time.simSeconds };
+                // Raw, clock-only bridge read — deliberately NOT `this.snapshot()`,
+                // which both feeds the TpsAccumulator and serializes every declared
+                // provider. Large imported worlds can carry megabytes of census state;
+                // the batching math needs only these two numbers.
+                const time = await this.callBridge('state', 'time');
+                return { tick: time.tick, simSeconds: time.simSeconds };
             },
             heartbeat: (info) => {
                 console.log(`vgai fastForward: ${info.ticksDone}/${info.ticksTotal} ticks driven`);
             },
         };
-        await runFastForward(budget, opts ?? {}, clock);
+        const finalTime = await runFastForward(budget, opts ?? {}, clock);
         // The burst is over — reset the baseline so the very next ordinary poll
         // (including the `snapshot()` call right below) treats itself as a fresh
         // "first observation" rather than diffing across the burst's enormous
         // tick delta over a near-zero wall delta.
         this.#tps.resetBaseline();
+        if (opts?.result === 'time') {
+            return finalTime;
+        }
         return this.snapshot();
     }
     async waitFor(pred, budget) {
@@ -626,7 +640,13 @@ export class GameClient {
         // fires either. Refuse in the caller's own vocabulary instead of hanging.
         assertValidWaitForBudget(budget, 'waitSimTime');
         const startWall = Date.now();
-        const start = await this.snapshot();
+        // Predicate-free means clock-only from the FIRST read, not merely from the
+        // second poll onward. A full initial snapshot serializes every provider;
+        // the Unity FPS provider alone carries ~4,500 objects and measured a
+        // 150-300ms main-thread hitch each time a caller began an otherwise cheap
+        // wait. Failure diagnostics still take one complete terminal snapshot
+        // below, only on the failure path where its state is actually printed.
+        const startTime = await this.readTime();
         let lastTick = null;
         let stalledPolls = 0;
         // Fixture heartbeat — same invariant as
@@ -634,10 +654,10 @@ export class GameClient {
         // silence AND the tick having advanced since the last one emitted, so a
         // genuinely stalled sim clock (caught by `stalledPolls` above, ~30s)
         // goes heartbeat-silent well before this loop's own guard ever needs to.
-        let heartbeat = { lastEmitWallMs: startWall, lastEmitTick: start.time.tick };
+        let heartbeat = { lastEmitWallMs: startWall, lastEmitTick: startTime.tick };
         for (;;) {
             const currentTime = await this.readTime();
-            if (currentTime.simSeconds - start.time.simSeconds >= budget.simSeconds)
+            if (currentTime.simSeconds - startTime.simSeconds >= budget.simSeconds)
                 return;
             stalledPolls = lastTick !== null && currentTime.tick === lastTick ? stalledPolls + 1 : 0;
             lastTick = currentTime.tick;
@@ -647,7 +667,10 @@ export class GameClient {
                 const current = await this.snapshot();
                 throw await this.toSessionFailure(new WaitForTimeoutError({
                     budget,
-                    startSnapshot: start,
+                    // The timeout renderer reads only the start clock; provider state
+                    // is intentionally terminal-only because no initial provider read
+                    // occurred. Empty collections state that absence honestly.
+                    startSnapshot: { time: startTime, state: {}, events: [], pageErrors: [] },
                     lastSnapshot: current,
                     wallElapsedMs: Date.now() - startWall,
                     predicateSource: '(no predicate — game.input.hold is waiting for a sim-time delta to pass)',
@@ -685,16 +708,33 @@ export class GameClient {
             artifactsDir: this.artifactsDir,
             sequence: this.#screenshotCounter + 1,
             cwd: process.cwd(),
+            projectRoot: this.#projectRoot,
         });
         if (target.consumedSequence)
             this.#screenshotCounter += 1;
         await mkdir(dirname(target.path), { recursive: true });
-        const notes = await this.#transport.screenshot(target.path);
+        const transportNotes = await this.#transport.screenshot(target.path);
+        // The out-path resolver is the only thing that knows the destination fell
+        // under the served project root, and the notes are where a capture says
+        // what it cost — so the two are joined here rather than at either end.
+        const notes = {
+            ...transportNotes,
+            ...(target.underWatchedProjectRoot === undefined
+                ? {}
+                : { watchedProjectRoot: target.underWatchedProjectRoot }),
+        };
         const capture = {
             label: labelOrPath,
             path: target.path,
             caveat: describeCaptureCaveat(notes),
         };
+        // ONE place says the sentence, with the WHOLE note set — a human watching
+        // this terminal and a run record read beside the frame must not be told
+        // different things (`capture-notes.ts`'s contract). The transport used to
+        // warn from its own partial set, which silently dropped every note this
+        // layer adds.
+        if (capture.caveat !== null)
+            console.warn(`vgai screenshot: ${capture.path} — ${capture.caveat}`);
         // Sequential and AWAITED: a listener may need to read the game to stamp
         // this capture, and it must have finished before the path is handed back —
         // a caller that files the path is entitled to assume the record of it is
@@ -740,7 +780,7 @@ export class GameClient {
      */
     async page(step) {
         const erased = (arg) => step(arg);
-        const outcome = await this.#transport.runPageScript(step.toString(), erased);
+        const outcome = await this.#transport.runPageScript(selfContainedStepSource(step), erased);
         return this.unwrap(outcome);
     }
     /**
@@ -760,10 +800,26 @@ export class GameClient {
      * 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.
+     *
+     * `modules(path)` IS ASYNC — it dynamic-imports that url — so the callback
+     * is `async` and the call is `await`ed, in every example on this page and
+     * everywhere else. Skipping it does not fail quietly: reading a member off
+     * the unawaited promise throws a message naming the fix, because
+     * `TypeError: modules(...).simHost is not a function` (measured, cold fox
+     * #3) says nothing about promises.
+     *
+     * `modules` IS A FUNCTION, not a table — there is no module registry. To ask
+     * what the mount has loaded, read `modules.loaded`, the project-relative
+     * paths you can pass straight back in:
+     *
+     * ```js
+     * await game.run(({ modules }) => modules.loaded)
+     * // → ['src/scenes/MainScene.tsx', 'src/world.tsx', …]
+     * ```
      */
     async run(step, opts) {
         const erased = (arg) => step(arg);
-        const outcome = await this.#transport.runGameScript(step.toString(), erased, opts?.instance);
+        const outcome = await this.#transport.runGameScript(selfContainedStepSource(step), erased, opts?.instance);
         return this.unwrap(outcome);
     }
     /**

package/dist/game-client/fast-forward.d.ts

@@ -64,6 +64,11 @@ export interface FastForwardOptions {
     /** Overrides `DEFAULT_FAST_FORWARD_BATCH_TICKS` — test-only seam; real
      *  callers should leave this unset. */
     batchTicks?: number;
+    /** What the caller needs back after the burst. Defaults to the complete
+     * debug snapshot. Tick-by-tick orchestration that samples providers only at
+     * explicit boundaries selects `'time'` so it does not serialize every large
+     * state provider after every staging tick. */
+    result?: 'snapshot' | 'time';
 }
 /** One fixed timestep, matching every real host's loop construction
  *  (`createGameLoop`'s own `fixedTimestep ?? 1/60` default: "fixedDt = the

package/dist/game-client/relay-transport.d.ts

@@ -19,7 +19,7 @@
  * anywhere in this path).
  */
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
-import { type CaptureNotes } from './capture-notes.js';
+import type { CaptureNotes } from './capture-notes.js';
 export interface RelayTransportOptions {
     /** The live editor session's dev-server port (e.g. from
      *  `findLiveEditorSession`/`vgai edit`). */

package/dist/game-client/relay-transport.js

@@ -20,7 +20,6 @@
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { describeCaptureCaveat } from './capture-notes.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** `invoke` dispatches to arbitrary game-registered debug commands — give it
  *  real headroom rather than the ordinary sync-call budget above. */
@@ -236,16 +235,20 @@ export class RelayTransport {
         // is indistinguishable from a good one until somebody opens the file —
         // which is exactly how two probes cited blank captures as evidence. The
         // page measured both conditions; carry them back so the caller can persist
-        // them beside the frame, and say the composed sentence here too, where a
-        // human watching this terminal is looking.
+        // them beside the frame.
+        //
+        // The SENTENCE is not said here. `GameClient.screenshot` composes it from
+        // these notes PLUS the ones only it has (the out-path's relation to the
+        // served project root), and `capture-notes.ts`'s whole contract is that
+        // the terminal and the persisted record cannot drift — which a second
+        // `console.warn` on a partial set is exactly how they would.
         const warning = body['flatness']?.warning;
+        const recordingPath = body['recording']?.path;
         const notes = {
             ...(body['loopRecoveryFrame'] === true ? { loopRecoveryFrame: true } : {}),
             ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
+            ...(typeof recordingPath === 'string' ? { recordingPath } : {}),
         };
-        const caveat = describeCaptureCaveat(notes);
-        if (caveat !== null)
-            console.warn(`vgai screenshot: ${path} — ${caveat}`);
         return notes;
     }
     /**

package/dist/game-client/screenshot-target.d.ts

@@ -43,6 +43,10 @@ export interface ScreenshotTargetInput {
     readonly sequence: number;
     /** Base for resolving a relative path/artifactsDir — the process cwd. */
     readonly cwd: string;
+    /** The project root the dev server is SERVING, when it is known. Only used
+     *  to say whether the destination lands under the file watcher — see
+     *  {@link ScreenshotTarget.underWatchedProjectRoot}. */
+    readonly projectRoot?: string | undefined;
 }
 export interface ScreenshotTarget {
     readonly kind: ScreenshotArgKind;
@@ -51,6 +55,19 @@ export interface ScreenshotTarget {
     /** True when the caller's own ordinal was consumed (label form only), so a
      *  path-form call never perturbs the numbering of the artifacts around it. */
     readonly consumedSequence: boolean;
+    /**
+     * The served project root this destination falls under, when it does.
+     *
+     * The dev server watches the project root for source changes and its
+     * `server.watch.ignored` list names build output only (`dist/`, `.vercel/`,
+     * `logs/`, `.claude/worktrees/`) — nothing about capture output. So a PNG
+     * written anywhere under the root goes through the watcher on every shot,
+     * and the cost is not theoretical: measured ~3x slower frame rates while a
+     * capture loop wrote under the project. This does not CHANGE where anything
+     * is written; it lets the capture say what it costs
+     * ({@link import('./capture-notes.js').describeCaptureCaveat}).
+     */
+    readonly underWatchedProjectRoot?: string;
 }
 /**
  * Resolve the absolute file a screenshot call must write. Pure — no I/O, no

package/dist/game-client/screenshot-target.js

@@ -19,7 +19,7 @@
  * resolved against the process cwd — the same rule `vgai screenshot --out`
  * already documents.
  */
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 /**
  * PATH when the argument names a location: absolute, containing a `/` or `\`
  * separator, an explicit `./`-style relative prefix, or carrying a file
@@ -45,6 +45,17 @@ export function classifyScreenshotArg(arg) {
 export function sanitizeScreenshotLabel(label) {
     return label.replace(/[^a-zA-Z0-9-_]+/g, '-');
 }
+/** Is `file` inside `root` (not merely sharing a path prefix)? */
+function isUnder(root, file) {
+    const rel = relative(resolve(root), file);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/** The watched-root note, when the destination has one. */
+function watchedRoot(path, projectRoot) {
+    if (projectRoot === undefined || projectRoot === '')
+        return {};
+    return isUnder(projectRoot, path) ? { underWatchedProjectRoot: resolve(projectRoot) } : {};
+}
 /**
  * Resolve the absolute file a screenshot call must write. Pure — no I/O, no
  * `process.cwd()` read — so the contract above is testable without a browser,
@@ -54,15 +65,23 @@ export function resolveScreenshotTarget(input) {
     const kind = classifyScreenshotArg(input.arg);
     if (kind === 'path') {
         const withExtension = /\.[a-zA-Z0-9]{1,8}$/.test(input.arg) ? input.arg : `${input.arg}.png`;
+        const path = isAbsolute(withExtension) ? withExtension : resolve(input.cwd, withExtension);
         return {
             kind,
-            path: isAbsolute(withExtension) ? withExtension : resolve(input.cwd, withExtension),
+            path,
             consumedSequence: false,
+            ...watchedRoot(path, input.projectRoot),
         };
     }
     const fileName = `${String(input.sequence).padStart(3, '0')}-${sanitizeScreenshotLabel(input.arg)}.png`;
     const dir = isAbsolute(input.artifactsDir)
         ? input.artifactsDir
         : resolve(input.cwd, input.artifactsDir);
-    return { kind, path: resolve(dir, fileName), consumedSequence: true };
+    const path = resolve(dir, fileName);
+    return {
+        kind,
+        path,
+        consumedSequence: true,
+        ...watchedRoot(path, input.projectRoot),
+    };
 }

package/dist/game.d.ts

@@ -52,7 +52,7 @@ export interface LiveGame extends GameClient {
 /** The unaddressed `game` client — targets the sole live instance and refuses
  *  when several are mounted. Kept as a named export for callers/tests that
  *  want just the base client. */
-export declare function createGameClient(port: number, artifactsDir?: string): GameClient;
+export declare function createGameClient(port: number, artifactsDir?: string, projectRoot?: string): GameClient;
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export declare function createLiveGame(port: number, artifactsDir?: string): LiveGame;
+export declare function createLiveGame(port: number, artifactsDir?: string, projectRoot?: string): LiveGame;

package/dist/game.js

@@ -32,7 +32,7 @@ import { GameClient, RelayTransport } from './game-client/index.js';
  * fence. `pageErrors`/`consoleErrors` are always empty — relay mode has no
  * separate page handle to listen on.
  */
-function gameClientFor(port, artifactsDir, instance) {
+function gameClientFor(port, artifactsDir, instance, projectRoot) {
     return new GameClient({
         transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
         pageErrors: [],
@@ -43,13 +43,14 @@ function gameClientFor(port, artifactsDir, instance) {
         fenceWallMs: Date.now(),
         warmSession: false,
         artifactsDir,
+        projectRoot,
     });
 }
 /** The unaddressed `game` client — targets the sole live instance and refuses
  *  when several are mounted. Kept as a named export for callers/tests that
  *  want just the base client. */
-export function createGameClient(port, artifactsDir) {
-    return gameClientFor(port, artifactsDir);
+export function createGameClient(port, artifactsDir, projectRoot) {
+    return gameClientFor(port, artifactsDir, undefined, projectRoot);
 }
 /** Query the editor's live instance ids over the session wire.
  *
@@ -73,12 +74,12 @@ async function listInstanceIds(port) {
 }
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export function createLiveGame(port, artifactsDir) {
-    const base = gameClientFor(port, artifactsDir);
+export function createLiveGame(port, artifactsDir, projectRoot) {
+    const base = gameClientFor(port, artifactsDir, undefined, projectRoot);
     // Tag each addressed handle with the mount id it drives, so a caller can pass
     // `handle.id` to `tools.run(..., { instance })`. The id is already known here
     // (it is what parameterizes the relay); attaching it just hands it back.
-    const instance = (id) => Object.assign(gameClientFor(port, artifactsDir, id), { id });
+    const instance = (id) => Object.assign(gameClientFor(port, artifactsDir, id, projectRoot), { id });
     const instances = async () => (await listInstanceIds(port)).map(instance);
     return Object.assign(base, { instance, instances });
 }

package/dist/index.d.ts

@@ -29,7 +29,7 @@
  *
  * `editor.document` is the OTHER surface door and the one that is NOT
  * play-mode gated: `page(step)` is rooted at the running GAME container, so
- * `editor.document.{query,click,key,paste}` is how an editor surface that is
+ * `editor.document.{query,click,key,paste,select}` is how an editor surface that is
  * not a game — a capability's workspace document, the Data sheet — gets read
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).

package/dist/index.js

@@ -29,7 +29,7 @@
  *
  * `editor.document` is the OTHER surface door and the one that is NOT
  * play-mode gated: `page(step)` is rooted at the running GAME container, so
- * `editor.document.{query,click,key,paste}` is how an editor surface that is
+ * `editor.document.{query,click,key,paste,select}` is how an editor surface that is
  * not a game — a capability's workspace document, the Data sheet — gets read
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
@@ -67,7 +67,7 @@ export { LiveTools } from './tools.js';
 function bindTo(port, projectRoot) {
     const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
     const editor = new LiveEditor(client);
-    const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'));
+    const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'), projectRoot);
     const step = (fn) => game.page(fn);
     const page = Object.assign(step, { reload: () => game.reloadPage() });
     const tools = new LiveTools(client);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.41",
+  "version": "0.5.44",
   "type": "module",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.41",
-    "@vgai/sdk": "0.5.41"
+    "@vgai/editor-sdk": "0.5.44",
+    "@vgai/sdk": "0.5.44"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "@types/node": "^25.3.0",
+    "esbuild": "^0.25.12",
     "typescript": "^5.6.0"
   },
   "description": "Live-session client for VGAI projects: { editor, game, page, tools } over the vgai edit session wire.",