@vgai/live 0.5.41 → 0.5.44

package/src/game-client/client.ts

@@ -20,6 +20,7 @@ import {
   type FastForwardBudget,
   type FastForwardClock,
   type FastForwardOptions,
+  type FastForwardTime,
   runFastForward,
 } from './fast-forward.js';
 import { HiddenRecoveryDriver } from './hidden-recovery.js';
@@ -104,6 +105,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: (scope: unknown) => unknown): string {
+  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
@@ -237,6 +256,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
@@ -553,6 +577,8 @@ export class GameClient {
   readonly #transport: BridgeTransport;
   /** 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. */
   readonly artifactsDir: string;
+  /** See `GameClientOptions.projectRoot`. */
+  readonly #projectRoot: string | undefined;
   /** See `GameClientOptions.warmSession`. */
   readonly #warmSession: boolean;
   /** See `GameClientOptions.testTitle`. */
@@ -584,6 +610,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() };
@@ -666,7 +693,15 @@ export class GameClient {
    * AFTER the tps baseline reset below, so it never itself corrupts the tps
    * stats either).
    */
-  async fastForward(budget: FastForwardBudget, opts?: FastForwardOptions): Promise<DebugSnapshot> {
+  async fastForward(
+    budget: FastForwardBudget,
+    opts: FastForwardOptions & { result: 'time' },
+  ): Promise<FastForwardTime>;
+  async fastForward(budget: FastForwardBudget, opts?: FastForwardOptions): Promise<DebugSnapshot>;
+  async fastForward(
+    budget: FastForwardBudget,
+    opts?: FastForwardOptions,
+  ): Promise<DebugSnapshot | FastForwardTime> {
     // Same options-object-only contract as `waitSimTime` (`ticksForBudget`
     // would otherwise fail on `'simTicks' in 0.5` with a raw TypeError that
     // names neither the method nor the shape).
@@ -696,21 +731,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<DebugSnapshot>('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<DebugSnapshot['time']>('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();
   }
 
@@ -760,7 +800,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: number | null = null;
     let stalledPolls = 0;
     // Fixture heartbeat — same invariant as
@@ -768,10 +814,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: HeartbeatState = { lastEmitWallMs: startWall, lastEmitTick: start.time.tick };
+    let heartbeat: HeartbeatState = { lastEmitWallMs: startWall, lastEmitTick: startTime.tick };
     for (;;) {
       const currentTime = await this.readTime();
-      if (currentTime.simSeconds - start.time.simSeconds >= budget.simSeconds) return;
+      if (currentTime.simSeconds - startTime.simSeconds >= budget.simSeconds) return;
       stalledPolls = lastTick !== null && currentTime.tick === lastTick ? stalledPolls + 1 : 0;
       lastTick = currentTime.tick;
       if (stalledPolls >= WAIT_FOR_STALL_POLL_LIMIT) {
@@ -781,7 +827,10 @@ export class GameClient {
         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:
@@ -821,15 +870,32 @@ 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: CaptureNotes = {
+      ...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
@@ -876,7 +942,10 @@ export class GameClient {
    */
   async page<T = unknown>(step: (page: Page) => T | Promise<T>): Promise<T> {
     const erased = (arg: unknown) => step(arg as Page);
-    const outcome = await this.#transport.runPageScript(step.toString(), erased);
+    const outcome = await this.#transport.runPageScript(
+      selfContainedStepSource(step as (scope: unknown) => unknown),
+      erased,
+    );
     return this.unwrap<T>(outcome);
   }
 
@@ -897,17 +966,37 @@ 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<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 },
   ): Promise<T> {
     const erased = (arg: unknown) => step(arg as Parameters<typeof step>[0]);
-    const outcome = await this.#transport.runGameScript(step.toString(), erased, opts?.instance);
+    const outcome = await this.#transport.runGameScript(
+      selfContainedStepSource(step as (scope: unknown) => unknown),
+      erased,
+      opts?.instance,
+    );
     return this.unwrap<T>(outcome);
   }
 

package/src/game-client/fast-forward.ts

@@ -63,6 +63,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

package/src/game-client/relay-transport.ts

@@ -22,7 +22,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
-import { type CaptureNotes, describeCaptureCaveat } 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
@@ -310,15 +310,20 @@ export class RelayTransport implements BridgeTransport {
     // 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'] as { warning?: string } | undefined)?.warning;
+    const recordingPath = (body['recording'] as { path?: string } | undefined)?.path;
     const notes: CaptureNotes = {
       ...(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/src/game-client/screenshot-target.ts

@@ -20,7 +20,7 @@
  * already documents.
  */
 
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 
 /** A caller's argument, classified. */
 export type ScreenshotArgKind = 'path' | 'label';
@@ -57,6 +57,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 {
@@ -66,6 +70,34 @@ 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;
+}
+
+/** Is `file` inside `root` (not merely sharing a path prefix)? */
+function isUnder(root: string, file: string): boolean {
+  const rel = relative(resolve(root), file);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/** The watched-root note, when the destination has one. */
+function watchedRoot(
+  path: string,
+  projectRoot: string | undefined,
+): { underWatchedProjectRoot: string } | Record<string, never> {
+  if (projectRoot === undefined || projectRoot === '') return {};
+  return isUnder(projectRoot, path) ? { underWatchedProjectRoot: resolve(projectRoot) } : {};
 }
 
 /**
@@ -77,15 +109,23 @@ export function resolveScreenshotTarget(input: ScreenshotTargetInput): Screensho
   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/src/game.ts

@@ -66,7 +66,12 @@ export interface LiveGame extends GameClient {
  * fence. `pageErrors`/`consoleErrors` are always empty — relay mode has no
  * separate page handle to listen on.
  */
-function gameClientFor(port: number, artifactsDir?: string, instance?: string): GameClient {
+function gameClientFor(
+  port: number,
+  artifactsDir?: string,
+  instance?: string,
+  projectRoot?: string,
+): GameClient {
   return new GameClient({
     transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
     pageErrors: [],
@@ -77,14 +82,19 @@ function gameClientFor(port: number, artifactsDir?: string, instance?: string):
     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: number, artifactsDir?: string): GameClient {
-  return gameClientFor(port, artifactsDir);
+export function createGameClient(
+  port: number,
+  artifactsDir?: string,
+  projectRoot?: string,
+): GameClient {
+  return gameClientFor(port, artifactsDir, undefined, projectRoot);
 }
 
 /** Query the editor's live instance ids over the session wire.
@@ -110,13 +120,17 @@ async function listInstanceIds(port: number): Promise<string[]> {
 
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export function createLiveGame(port: number, artifactsDir?: string): LiveGame {
-  const base = gameClientFor(port, artifactsDir);
+export function createLiveGame(
+  port: number,
+  artifactsDir?: string,
+  projectRoot?: string,
+): LiveGame {
+  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: string): AddressedGameClient =>
-    Object.assign(gameClientFor(port, artifactsDir, id), { id });
+    Object.assign(gameClientFor(port, artifactsDir, id, projectRoot), { id });
   const instances = async (): Promise<AddressedGameClient[]> =>
     (await listInstanceIds(port)).map(instance);
   return Object.assign(base, { instance, instances });

package/src/index.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`).
@@ -125,7 +125,7 @@ export interface LiveBindings {
 function bindTo(port: number, projectRoot: string): LiveBindings {
   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: GameClient['page'] = (fn) => game.page(fn);
   const page: PageStep = Object.assign(step, { reload: () => game.reloadPage() });
   const tools = new LiveTools(client);