@vgai/live 0.5.40 → 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';
@@ -226,6 +226,15 @@ export declare class GameClient {
     providers(): Promise<ProviderInfo[]>;
     commands(): Promise<DebugCommandInfo[]>;
     snapshot(sinceSeq?: number): Promise<DebugSnapshot>;
+    /**
+     * Read only the simulation clock for a predicate-free wait.
+     *
+     * `snapshot()` intentionally batches every declared provider for `waitFor`, whose predicate may
+     * read any of them. `waitSimTime` has no predicate: serializing a large `unity` provider every
+     * 150ms can itself consume multiple frames and corrupt the performance window it is advancing.
+     * Keep the two hardening observers fed exactly as an ordinary snapshot does.
+     */
+    private readTime;
     /** Fixture-teardown perf read: p50/p95 effective ticks-per-second over all
      *  the snapshot polls this test performed. */
     tpsStats(): TpsStats;
@@ -243,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
@@ -504,6 +522,20 @@ export class GameClient {
         await this.#hiddenRecovery.observeTick(snap.time.tick);
         return snap;
     }
+    /**
+     * Read only the simulation clock for a predicate-free wait.
+     *
+     * `snapshot()` intentionally batches every declared provider for `waitFor`, whose predicate may
+     * read any of them. `waitSimTime` has no predicate: serializing a large `unity` provider every
+     * 150ms can itself consume multiple frames and corrupt the performance window it is advancing.
+     * Keep the two hardening observers fed exactly as an ordinary snapshot does.
+     */
+    async readTime() {
+        const time = await this.callBridge('state', 'time');
+        this.#tps.record(time.tick, Date.now());
+        await this.#hiddenRecovery.observeTick(time.tick);
+        return time;
+    }
     /** Fixture-teardown perf read: p50/p95 effective ticks-per-second over all
      *  the snapshot polls this test performed. */
     tpsStats() {
@@ -513,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
@@ -556,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) {
@@ -612,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
@@ -620,17 +651,23 @@ 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 current = await this.snapshot();
-            if (current.time.simSeconds - start.time.simSeconds >= budget.simSeconds)
+            const currentTime = await this.readTime();
+            if (currentTime.simSeconds - startTime.simSeconds >= budget.simSeconds)
                 return;
-            stalledPolls = lastTick !== null && current.time.tick === lastTick ? stalledPolls + 1 : 0;
-            lastTick = current.time.tick;
+            stalledPolls = lastTick !== null && currentTime.tick === lastTick ? stalledPolls + 1 : 0;
+            lastTick = currentTime.tick;
             if (stalledPolls >= WAIT_FOR_STALL_POLL_LIMIT) {
+                // Failure diagnostics still carry one honest complete terminal snapshot. The hot path above
+                // stays clock-only; the expensive provider batch is paid only when it will be printed.
+                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)',
@@ -639,8 +676,8 @@ export class GameClient {
             }
             const heartbeatResult = maybeHeartbeat({
                 nowMs: Date.now(),
-                tick: current.time.tick,
-                simSeconds: current.time.simSeconds,
+                tick: currentTime.tick,
+                simSeconds: currentTime.simSeconds,
                 testTitle: this.#testTitle,
                 state: heartbeat,
             });
@@ -723,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);
     }
     /**
@@ -746,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/dist/game-client/relay-transport.js

@@ -171,7 +171,10 @@ export class RelayTransport {
     }
     async call(method, callArgs) {
         const hidden = await this.preflightHidden();
-        if (method === 'snapshot') {
+        // A predicate-free `waitSimTime` poll reads only the `time` provider. It needs the same hidden
+        // tab deterministic driver as a full snapshot or a hidden editor would freeze that lighter
+        // clock read forever.
+        if (method === 'snapshot' || (method === 'state' && callArgs[0] === 'time')) {
             if (hidden) {
                 const now = Date.now();
                 const elapsed = this.hiddenDriveLastWallMs === null ? 1000 / 60 : now - this.hiddenDriveLastWallMs;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.40",
+  "version": "0.5.42",
   "type": "module",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.40",
-    "@vgai/sdk": "0.5.40"
+    "@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
@@ -628,6 +647,21 @@ export class GameClient {
     return snap;
   }
 
+  /**
+   * Read only the simulation clock for a predicate-free wait.
+   *
+   * `snapshot()` intentionally batches every declared provider for `waitFor`, whose predicate may
+   * read any of them. `waitSimTime` has no predicate: serializing a large `unity` provider every
+   * 150ms can itself consume multiple frames and corrupt the performance window it is advancing.
+   * Keep the two hardening observers fed exactly as an ordinary snapshot does.
+   */
+  private async readTime(): Promise<DebugSnapshot['time']> {
+    const time = await this.callBridge<DebugSnapshot['time']>('state', 'time');
+    this.#tps.record(time.tick, Date.now());
+    await this.#hiddenRecovery.observeTick(time.tick);
+    return time;
+  }
+
   /** Fixture-teardown perf read: p50/p95 effective ticks-per-second over all
    *  the snapshot polls this test performed. */
   tpsStats(): TpsStats {
@@ -651,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).
@@ -681,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();
   }
 
@@ -745,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
@@ -753,17 +806,23 @@ 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 current = await this.snapshot();
-      if (current.time.simSeconds - start.time.simSeconds >= budget.simSeconds) return;
-      stalledPolls = lastTick !== null && current.time.tick === lastTick ? stalledPolls + 1 : 0;
-      lastTick = current.time.tick;
+      const currentTime = await this.readTime();
+      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) {
+        // Failure diagnostics still carry one honest complete terminal snapshot. The hot path above
+        // stays clock-only; the expensive provider batch is paid only when it will be printed.
+        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:
@@ -774,8 +833,8 @@ export class GameClient {
       }
       const heartbeatResult = maybeHeartbeat({
         nowMs: Date.now(),
-        tick: current.time.tick,
-        simSeconds: current.time.simSeconds,
+        tick: currentTime.tick,
+        simSeconds: currentTime.simSeconds,
         testTitle: this.#testTitle,
         state: heartbeat,
       });
@@ -858,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);
   }
 
@@ -889,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

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

@@ -232,7 +232,10 @@ export class RelayTransport implements BridgeTransport {
 
   async call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome> {
     const hidden = await this.preflightHidden();
-    if (method === 'snapshot') {
+    // A predicate-free `waitSimTime` poll reads only the `time` provider. It needs the same hidden
+    // tab deterministic driver as a full snapshot or a hidden editor would freeze that lighter
+    // clock read forever.
+    if (method === 'snapshot' || (method === 'state' && callArgs[0] === 'time')) {
       if (hidden) {
         const now = Date.now();
         const elapsed =