@vgai/live 0.5.41 → 0.5.42

package/dist/editor.d.ts

@@ -178,6 +178,8 @@ export declare class LiveEditor {
      * tree would be a fabricated answer about a surface nobody is being shown.
      */
     hierarchy(): Promise<InspectedHierarchy>;
+    /** Expand every branch through the Hierarchy panel's own action. */
+    expandHierarchyAll(): Promise<void>;
     /**
      * Write one editable field from `inspect()` by its stable path, through the
      * same Inspector IO and persistence boundary the human control uses.

package/dist/editor.js

@@ -289,6 +289,10 @@ export class LiveEditor {
     async hierarchy() {
         return this.#client.hierarchy();
     }
+    /** Expand every branch through the Hierarchy panel's own action. */
+    async expandHierarchyAll() {
+        await this.#client.expandHierarchyAll();
+    }
     /**
      * Write one editable field from `inspect()` by its stable path, through the
      * same Inspector IO and persistence boundary the human control uses.

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';
@@ -252,6 +252,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

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
@@ -527,18 +545,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 +576,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 +637,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 +651,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 +664,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)',
@@ -740,7 +760,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);
     }
     /**
@@ -763,7 +783,7 @@ export class GameClient {
      */
     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/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.41",
+  "version": "0.5.42",
   "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.42",
+    "@vgai/sdk": "0.5.42"
   },
   "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.",

package/src/editor.ts

@@ -353,6 +353,11 @@ export class LiveEditor {
     return this.#client.hierarchy();
   }
 
+  /** Expand every branch through the Hierarchy panel's own action. */
+  async expandHierarchyAll(): Promise<void> {
+    await this.#client.expandHierarchyAll();
+  }
+
   /**
    * Write one editable field from `inspect()` by its stable path, through the
    * same Inspector IO and persistence boundary the human control uses.

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
@@ -666,7 +685,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 +723,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 +792,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 +806,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 +819,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:
@@ -876,7 +917,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);
   }
 
@@ -907,7 +951,11 @@ export class GameClient {
     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