@vgai/live 0.5.13 → 0.5.14

package/dist/index.d.ts

@@ -55,13 +55,27 @@ export type { DocumentGestureOptions, DocumentKeyOptions, DocumentPasteOptions,
 export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame, type LiveGame } from './game.js';
 export * from './game-client/index.js';
+export type { GameplayRecordingResult } from './recording.js';
+export { LiveGameplayRecording } from './recording.js';
 export type { ProjectSessionHint, ResolvedSession, SessionListingTransport, SessionResolutionDeps, } from './session.js';
 export { findProjectRootFrom, resolveSession } from './session.js';
 export type { LazySession } from './singleton.js';
 export { createLazySession } from './singleton.js';
 export { LiveTools } from './tools.js';
-/** A `game.page(step)`-shaped call — see this module's doc comment for the closure-capture limitation. */
-export type PageStep = GameClient['page'];
+/**
+ * The `page` binding: a `game.page(step)`-shaped CALL (see this module's doc
+ * comment for the closure-capture limitation) that also carries the one page
+ * verb no step can express — `page.reload()`.
+ *
+ * `reload` is a property rather than a step because a step that navigates
+ * destroys the channel its own result would return on: `page(p =>
+ * p.evaluate(() => location.reload()))` was the only spelling available, and
+ * it resolves on a send while failing outright outside play mode. See
+ * `GameClient.reloadPage`.
+ */
+export type PageStep = GameClient['page'] & {
+    reload: GameClient['reloadPage'];
+};
 export interface LiveSession extends LiveBindings {
     /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
     session: ResolvedSession;
@@ -73,7 +87,9 @@ export interface LiveBindings {
      *  several mounted instances (multiplayer authoring). A bare `game` call
      *  targets the sole instance and refuses when several are live. */
     game: LiveGame;
-    /** `GameClient.page` bound to `game` — see this module's own doc comment for the wire limitation. */
+    /** `GameClient.page` bound to `game`, plus `page.reload()` — see this
+     *  module's own doc comment for the wire limitation, and {@link PageStep}
+     *  for why reload is a property rather than a step. */
     page: PageStep;
     /** Registered project callables: enumerate, inspect, and invoke. */
     tools: LiveTools;

package/dist/index.js

@@ -55,6 +55,7 @@ export { inferAssetKind, LiveEditor } from './editor.js';
 export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame } from './game.js';
 export * from './game-client/index.js';
+export { LiveGameplayRecording } from './recording.js';
 export { findProjectRootFrom, resolveSession } from './session.js';
 export { createLazySession } from './singleton.js';
 export { LiveTools } from './tools.js';
@@ -67,7 +68,8 @@ 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 page = (step) => game.page(step);
+    const step = (fn) => game.page(fn);
+    const page = Object.assign(step, { reload: () => game.reloadPage() });
     const tools = new LiveTools(client);
     return { editor, game, page, tools };
 }

package/dist/recording.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `editor.recording` — real-time gameplay evidence through the existing live
+ * editor session. The browser owns MediaRecorder and the game pixels/audio;
+ * the project server streams the standard WebM to disk while this namespace
+ * exposes the start/stop controls and optional final copy destination.
+ *
+ * Recording deliberately is not a CLI workflow of its own. Agents start and
+ * stop it through the one general door (`vgai eval`) and use ordinary ffmpeg,
+ * ffprobe, and filesystem tools to review or trim the result.
+ */
+import type { EditorClient, GameplayRecordingOptions, GameplayRecordingStarted } from '@vgai/editor-sdk';
+export interface GameplayRecordingResult extends GameplayRecordingStarted {
+    /** Absolute path to the standard WebM written on stop. */
+    path: string;
+    durationMs: number;
+    droppedFrames: number;
+    frameErrors: number;
+}
+export declare class LiveGameplayRecording {
+    #private;
+    constructor(client: EditorClient);
+    /** Start one clean game recording. The page owns it until `stop()`, even
+     * when start and stop are issued by separate `vgai eval` processes. */
+    start(options?: GameplayRecordingOptions): Promise<GameplayRecordingStarted>;
+    /** Finalize the active recording, write it to disk, and return honest media
+     * metadata without echoing the large base64 transport payload to stdout. */
+    stop(destination?: string): Promise<GameplayRecordingResult>;
+}

package/dist/recording.js

@@ -0,0 +1,52 @@
+/**
+ * `editor.recording` — real-time gameplay evidence through the existing live
+ * editor session. The browser owns MediaRecorder and the game pixels/audio;
+ * the project server streams the standard WebM to disk while this namespace
+ * exposes the start/stop controls and optional final copy destination.
+ *
+ * Recording deliberately is not a CLI workflow of its own. Agents start and
+ * stop it through the one general door (`vgai eval`) and use ordinary ffmpeg,
+ * ffprobe, and filesystem tools to review or trim the result.
+ */
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, resolve } from 'node:path';
+function recordingPath(destination) {
+    if (destination.trim() === '')
+        throw new Error('recording destination must not be empty');
+    const withExtension = extname(destination) === '' ? `${destination}.webm` : destination;
+    return isAbsolute(withExtension) ? withExtension : resolve(process.cwd(), withExtension);
+}
+export class LiveGameplayRecording {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** Start one clean game recording. The page owns it until `stop()`, even
+     * when start and stop are issued by separate `vgai eval` processes. */
+    async start(options = {}) {
+        return this.#client.startGameplayRecording(options);
+    }
+    /** Finalize the active recording, write it to disk, and return honest media
+     * metadata without echoing the large base64 transport payload to stdout. */
+    async stop(destination) {
+        const capture = await this.#client.stopGameplayRecording();
+        const path = destination === undefined ? capture.path : recordingPath(destination);
+        if (path !== capture.path) {
+            await mkdir(dirname(path), { recursive: true });
+            await copyFile(capture.path, path);
+        }
+        return {
+            path,
+            startedAt: capture.startedAt,
+            mimeType: capture.mimeType,
+            width: capture.width,
+            height: capture.height,
+            fps: capture.fps,
+            audio: capture.audio,
+            durationMs: capture.durationMs,
+            droppedFrames: capture.droppedFrames,
+            frameErrors: capture.frameErrors,
+            layers: capture.layers,
+        };
+    }
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,8 +31,8 @@
     "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.13",
-    "@vgai/sdk": "0.5.13"
+    "@vgai/editor-sdk": "0.5.14",
+    "@vgai/sdk": "0.5.14"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/editor.ts

@@ -13,6 +13,7 @@
 
 import type {
   ActiveDocumentCapture,
+  AnimationCaptureAction,
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
@@ -21,6 +22,7 @@ import type {
   EditorState,
   EditorView,
   HistoryStep,
+  InspectedFieldWrite,
   InspectedHierarchy,
   InspectedInspection,
   PresentedEditorView,
@@ -29,6 +31,7 @@ import type {
   ViewportCapture,
 } from '@vgai/editor-sdk';
 import { LiveEditorDocument } from './editor-document.js';
+import { LiveGameplayRecording } from './recording.js';
 
 /** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
 export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'console' | 'build';
@@ -86,9 +89,14 @@ export class LiveEditor {
    */
   readonly document: LiveEditorDocument;
 
+  /** Clean real-time game capture: start/stop through `vgai eval`, standard
+   * WebM on disk. This is evidence capture, not an animation authoring tool. */
+  readonly recording: LiveGameplayRecording;
+
   constructor(client: EditorClient) {
     this.#client = client;
     this.document = new LiveEditorDocument(client);
+    this.recording = new LiveGameplayRecording(client);
   }
 
   /**
@@ -271,21 +279,11 @@ export class LiveEditor {
   }
 
   /**
-   * CONSENT to edits being written into the game's own source files, for this
-   * session — the Game document's "Persist to game source" checkbox, reachable
-   * from a script.
-   *
-   * Off by default every session, on purpose: it is a statement about what you
-   * are doing right now, never a property of the game. With it off, an edit
-   * lives on the running object and says so; with it on, an edit that can be
-   * honestly anchored to the line that CREATED the object is written there,
-   * and one that cannot still says so. Answers with the server's own phrase for
-   * who records the resulting diff — your version control, or a vendored
-   * game's own lock — and refuses, with the reason, where the checkbox is
-   * disabled.
+   * Drive the recorder of the active native animation document. The document
+   * decides the native destination and refuses when it owns no safe writer.
    */
-  async persistToGameSource(on: boolean): Promise<{ enabled: boolean; recorder: string | null }> {
-    return this.#client.setSourcePersistConsent(on);
+  async recordAnimation(action: AnimationCaptureAction): Promise<void> {
+    await this.#client.recordAnimation(action);
   }
 
   /**
@@ -353,8 +351,15 @@ export class LiveEditor {
   /**
    * Write one editable field from `inspect()` by its stable path, through the
    * same Inspector IO and persistence boundary the human control uses.
+   *
+   * The answer is `{ subject, write }`, and `write` is the half worth reading
+   * first: a write with no persistence route open still succeeds — it lands on
+   * the live object and journals live-only — so `write.persisted` is how you
+   * tell a saved edit from one that will not survive the session, without
+   * diffing the tree. `write.destination` is the adapter's own words for where
+   * it went ("live-only (not saved)" is a destination, never silence).
    */
-  async setField(path: string, value: unknown): Promise<InspectedInspection> {
+  async setField(path: string, value: unknown): Promise<InspectedFieldWrite> {
     return this.#client.setInspectionField(path, value);
   }
 

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

@@ -75,4 +75,23 @@ export interface BridgeTransport {
    * serialized — inline every value the step needs.
    */
   runPageScript(src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+  /**
+   * P20 — reload the document showing the game, resolving only once the page
+   * is BACK and taking commands again.
+   *
+   * Deliberately not expressible as a `runPageScript` step, which is why it
+   * is on this interface at all: a step that calls `location.reload()` kills
+   * the channel its own acknowledgement would travel on, so the caller's
+   * promise resolves on a thrown/timed-out send and says nothing about
+   * whether a page came back. Each transport therefore owns its own honest
+   * completion signal — Playwright's real `page.reload()` on the page
+   * transport, a new document load plus a working command round trip on the
+   * relay.
+   *
+   * This exists because it was MISSING: P20's recovery for stale asset bytes
+   * is a full document reload, and the only way to spell it through
+   * `vgai eval` was `page(p => p.evaluate(() => location.reload()))` — which
+   * both fails outside play mode and resolves on a send, not on a reload.
+   */
+  reloadPage(): Promise<void>;
 }

package/src/game-client/capture-notes.ts

@@ -4,9 +4,10 @@
  *
  * 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 `hiddenFrame` when
- * the surface was hidden and the runtime had to render one deterministic tick
- * on demand (`command-listener.ts`'s `handleBridgeScreenshot`), and it reports
+ * measured elsewhere in the stack: 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
  * `console.warn` inside the relay transport — visible to a human watching a
@@ -23,9 +24,9 @@
 /** The conditions a capture was taken under, as facts. Both fields are
  *  optional and absent means "not so": an ordinary frame carries no notes. */
 export interface CaptureNotes {
-  /** The surface showing the game was hidden, so the frame exists only because
-   *  the runtime was asked for one deterministic tick. */
-  readonly hiddenFrame?: boolean;
+  /** The host loop was starved, so the frame exists only because the runtime
+   *  was asked for one deterministic tick. */
+  readonly loopRecoveryFrame?: boolean;
   /** The page's own near-blank-frame sentence, verbatim (it owns the wording;
    *  see `composite-screenshot.ts`'s `CaptureFlatness.warning`). */
   readonly flatnessWarning?: string;
@@ -49,24 +50,24 @@ export interface CaptureRecord {
  *  capture with where the run was standing, say) can. */
 export type CaptureListener = (capture: CaptureRecord) => void | Promise<void>;
 
-/** The hidden-surface sentence. Spelled once because it is said in two places
+/** 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. */
-const HIDDEN_FRAME_CAVEAT =
-  'HIDDEN FRAME — the surface showing the game was hidden, so the runtime rendered one ' +
-  'deterministic tick on demand. It is current, not stale; it is not a frame anyone was watching.';
+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 (a hidden tab's on-demand tick that also came
+ * 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.
  */
 export function describeCaptureCaveat(notes: CaptureNotes): string | null {
   const parts: string[] = [];
-  if (notes.hiddenFrame === true) parts.push(HIDDEN_FRAME_CAVEAT);
+  if (notes.loopRecoveryFrame === true) parts.push(LOOP_RECOVERY_FRAME_CAVEAT);
   if (typeof notes.flatnessWarning === 'string' && notes.flatnessWarning !== '') {
     parts.push(notes.flatnessWarning);
   }

package/src/game-client/client.ts

@@ -157,6 +157,13 @@ export class PageTransport implements BridgeTransport {
       };
     }
   }
+
+  /** Playwright's own reload already waits for the new document's `load`
+   *  event, which is exactly the completion signal this method's contract
+   *  asks for — nothing to reconstruct on this leg. */
+  async reloadPage(): Promise<void> {
+    await this.page.reload();
+  }
 }
 
 export interface GameClientOptions {
@@ -268,7 +275,7 @@ export class GameInput {
    * instead of the old set → `waitSimTime`'s 150ms-interval snapshot poll
    * loop → clear (15+ transport round trips over the editor relay for a
    * multi-second hold). The wait uses ordinary host-loop ticks while visible.
-   * If the browser has hidden-paused that loop, the bridge drives the held
+   * If the browser has loop-starved that loop, the bridge drives the held
    * action through the same game phases with deterministic ticks; this
    * collapses transport cost without letting a background tab deadlock it.
    *
@@ -797,6 +804,20 @@ export class GameClient {
     return this.unwrap<T>(outcome);
   }
 
+  /**
+   * Reload the document showing the game, resolving only once it is back and
+   * answering commands (see `bridge-transport.ts`'s `reloadPage`).
+   *
+   * Bound as `page.reload()` on `@vgai/live`'s `page` binding. It is the one
+   * recovery for bytes that changed on disk after the running document
+   * loaded: `vgai restart` remounts every root from fresh SOURCE, but
+   * module-scope loaders and the page-lifetime asset caches (Pixi `Assets`,
+   * three's loader caches) survive a remount and keep serving the old bytes.
+   */
+  async reloadPage(): Promise<void> {
+    await this.#transport.reloadPage();
+  }
+
   private async toSessionFailure(err: WaitForTimeoutError): Promise<SessionFailure> {
     const providers = await this.providers();
     const screenshotPath = await this.screenshot('waitfor-timeout').catch(() => null);
@@ -820,7 +841,7 @@ export class GameClient {
       // as a generic "loop is stalled" no matter WHY the clock was frozen.
       // `HiddenRecoveryDriver` already tried ONE `bringToFront()` recovery
       // before this failure fires (see this class's constructor) — if the
-      // loop is STILL hidden-paused here, recovery couldn't reach the tab
+      // loop is STILL loop-starved here, recovery couldn't reach the tab
       // (headless run, no-op bringToFront), and the failure block must say
       // so explicitly rather than leaving an agent to guess "stalled" for a
       // tab that is simply backgrounded.

package/src/game-client/failure-block.ts

@@ -42,7 +42,7 @@ export interface FailureBlockContext {
   /**
    * Issue #175 — the REAL loop liveness at the moment of failure (the
    * timed-out/failed snapshot's `time.loopLiveness`). When this is
-   * `'hidden-paused'`, `ratioLine` below replaces its generic "if ~0x, the
+   * `'loop-starved'`, `ratioLine` below replaces its generic "if ~0x, the
    * loop is stalled" hint with an explicit "the tab is hidden" diagnosis —
    * `HiddenRecoveryDriver` already tried ONE `bringToFront()` recovery
    * before this failure was ever thrown (see `client.ts`/`hidden-recovery.ts`);
@@ -52,7 +52,7 @@ export interface FailureBlockContext {
    * itself crashed. Optional/`undefined` when the bridge build predates
    * `loopLiveness` — falls back to the old generic hint, same as before.
    */
-  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null | undefined;
+  loopLiveness?: 'running' | 'loop-starved' | 'stopped' | null | undefined;
 }
 
 export interface SessionFailureData {
@@ -75,7 +75,7 @@ export interface SessionFailureData {
    *  Machine-readable twin of `elapsed.line`'s hidden-tab hint, for a JSON
    *  reporter that doesn't want to parse prose to tell a frozen tab from a
    *  stalled game. `undefined`/`null` exactly mirrors the context field. */
-  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null | undefined;
+  loopLiveness?: 'running' | 'loop-starved' | 'stopped' | null | undefined;
 }
 
 export interface AssembledFailureBlock {
@@ -103,19 +103,28 @@ export function annotateStateTiers(
 function ratioLine(
   simElapsedSeconds: number,
   wallElapsedMs: number,
-  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null,
+  loopLiveness?: 'running' | 'loop-starved' | 'stopped' | null,
 ): { ratio: number; line: string } {
   const wallElapsedS = wallElapsedMs / 1000;
   const ratio = wallElapsedS > 0 ? simElapsedSeconds / wallElapsedS : 0;
-  // Issue #175: a hidden tab hard-stops the engine loop (T2.1's deliberate
-  // idle throttle) — the same ~0x reading a genuinely stalled/crashed game
-  // produces. Without this branch an agent sees "loop is stalled" and has no
-  // way to tell a frozen tab from a dead game; say so explicitly instead.
+  // Issue #175: an rAF chain can make no progress while UI play state still
+  // says running — the same ~0x reading a genuinely crashed game produces.
+  // The loop's own measurement distinguishes that condition without guessing
+  // what is happening to the browser window.
+  //
+  // P21: state the READING, not a conclusion about the human's screen. This
+  // hint used to read "the EDITOR/BROWSER TAB IS HIDDEN", and that sentence
+  // reached the owner as an assertion about a tab they were looking at.
+  // `loop-starved` is what the engine's own loop reports when no recent host
+  // rAF callback was observed; repeating that is honest, narrating the window
+  // is not.
   const hint =
-    loopLiveness === 'hidden-paused'
-      ? 'the EDITOR/BROWSER TAB IS HIDDEN — the engine loop deliberately ' +
-        'stops ticking while backgrounded (not a crash); bring the tab to ' +
-        'the foreground and retry'
+    loopLiveness === 'loop-starved'
+      ? "the loop reported liveness 'loop-starved' — no recent host rAF " +
+        'callback was observed (not, by itself, a crash or a visibility ' +
+        'verdict). Sim time still advances through game.waitSimTime/waitFor, ' +
+        'which drive deterministic ticks over the relay; `vgai status` prints ' +
+        'the visibility readings with their ages if you need to know why'
       : 'if ~0x, the loop is stalled; if <1x under CI, the budget may just ' +
         'be too small for SwiftShader';
   const line =

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

@@ -75,6 +75,18 @@ const PAGE_SCRIPT_TIMEOUT_MS = 60_000;
  *  count. */
 const HIDDEN_SAMPLE_TTL_MS = 500;
 
+/** How long `reloadPage` waits for a new document AND a working command
+ *  round trip before it reports what it did and did not observe. A cold Vite
+ *  re-optimize on a first reload is the slow case this budget is sized for. */
+const RELOAD_READY_TIMEOUT_MS = 60_000;
+const RELOAD_POLL_MS = 250;
+
+/** Seconds since `since`, one decimal — every `reloadPage` failure names how
+ *  long it actually waited rather than quoting the budget. */
+function elapsedSeconds(since: number): string {
+  return ((Date.now() - since) / 1000).toFixed(1);
+}
+
 export class RelayTransport implements BridgeTransport {
   private readonly baseUrl: string;
   private readonly timeoutMs: number;
@@ -174,10 +186,14 @@ export class RelayTransport implements BridgeTransport {
     const hidden = this.forceHiddenDrive || (await this.isHiddenCached());
     if (hidden && !this.hiddenDriveAnnounced) {
       this.hiddenDriveAnnounced = true;
+      // P21: what was measured, and what this run is doing about it — not a
+      // claim about where the tab is. The reading is a `presence` snapshot
+      // (`isHidden` below), which ages between the tab's own reports.
       process.stdout.write(
-        'vgai: the editor tab is HIDDEN — the engine hidden-pauses its loop while the tab ' +
-          'is backgrounded, so this run drives deterministic runTicks through the session relay. ' +
-          'Bring the editor tab to the foreground for real-time play.\n',
+        'vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
+          'stops its loop while the page reports itself hidden, so this run drives ' +
+          'deterministic runTicks through the session relay instead of wall clock. Sim time ' +
+          'advances either way; `vgai status` prints that reading with its age.\n',
       );
     }
     return hidden;
@@ -249,13 +265,13 @@ export class RelayTransport implements BridgeTransport {
 
   async screenshot(path: string): Promise<CaptureNotes> {
     // Same preflight as every other leg — a hidden tab's canvas is a provably
-    // stale frame, and `refreshHiddenFrame` is what asks the relay for a
+    // stale frame, and `refreshStarvedFrame` is what asks the relay for a
     // deterministic one-tick refresh instead of a `BRIDGE_SCREENSHOT_STALE`
     // refusal (`command-listener.ts`'s `handleBridgeScreenshot`).
     const body = await this.postCommand(
       {
         type: 'bridge-screenshot',
-        refreshHiddenFrame: await this.preflightHidden(),
+        refreshStarvedFrame: await this.preflightHidden(),
         // Address THIS transport's instance so a per-seat `game.instance(id)`
         // screenshot captures that seat's game stack, not always the primary.
         ...(this.instance !== undefined ? { instance: this.instance } : {}),
@@ -277,7 +293,7 @@ export class RelayTransport implements BridgeTransport {
     // human watching this terminal is looking.
     const warning = (body['flatness'] as { warning?: string } | undefined)?.warning;
     const notes: CaptureNotes = {
-      ...(body['hiddenFrame'] === true ? { hiddenFrame: true } : {}),
+      ...(body['loopRecoveryFrame'] === true ? { loopRecoveryFrame: true } : {}),
       ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
     };
     const caveat = describeCaptureCaveat(notes);
@@ -310,4 +326,112 @@ export class RelayTransport implements BridgeTransport {
       };
     }
   }
+
+  /**
+   * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
+   *
+   * Two witnesses, in order, because either one alone lies in a way that
+   * matters:
+   *
+   *  1. The tab table's EPOCH count rising. A tab's epoch id is minted per
+   *     page-load and carried on its heartbeat, so the server increments
+   *     this when it observes a new document — not when the tab claims one.
+   *     Without it, a `page-reload` that the page never acted on (a
+   *     `beforeunload` blocker, a listener that had already died) would look
+   *     identical to a completed reload.
+   *
+   *     `lastIndexRequestAt` was the first choice here and is measurably the
+   *     WRONG one: a reload served from the browser's own cache leaves it
+   *     untouched (observed live 2026-08-15 — `epochCount` went 2 → 3 while
+   *     the stamp did not move), so it reported "no new document" for a
+   *     reload that had plainly happened.
+   *  2. A `list-instances` command completing. That is the whole relay path
+   *     — server → SSE channel → the NEW document's command listener — so it
+   *     is the difference between "a document loaded" and "the session can
+   *     be driven again". It is the one command with no play gate and no
+   *     side effects (`command-listener.ts`), and it is held-and-retried by
+   *     the relay while a tab is mid-boot, so a refusal here means the page
+   *     genuinely is not answering yet.
+   *
+   * Neither witness is inferred from the send. A reload that never completes
+   * REJECTS with what was and was not observed, rather than resolving into a
+   * caller's belief that the page is fresh.
+   */
+  async reloadPage(): Promise<void> {
+    const before = await this.readTabEpochs();
+    const orderedAt = Date.now();
+    const ordered = await this.postCommand({ type: 'page-reload' }, this.timeoutMs);
+    if (!ordered.ok) {
+      throw new Error(
+        `vgai: the editor session refused the reload — ${ordered.error ?? 'no reason given'}`,
+      );
+    }
+    // The stale visibility sample belongs to a document that no longer
+    // exists; the next leg must measure the new one.
+    this.hiddenCache = null;
+    const deadline = orderedAt + RELOAD_READY_TIMEOUT_MS;
+    const loaded = await this.pollUntil(deadline, async () => {
+      const now = await this.readTabEpochs();
+      // Any present tab whose epoch count has RISEN, or a tab that was not
+      // in the table before (the reload arrived as a fresh row). An unknown
+      // table — an unreachable server, an older one — never witnesses a
+      // reload by default; `undefined` compares false here on purpose.
+      return [...now].some(([tabId, epochs]) => epochs > (before.get(tabId) ?? 0));
+    });
+    if (!loaded) {
+      throw new Error(
+        `vgai: reload ordered ${elapsedSeconds(orderedAt)}s ago and no tab of the session at ` +
+          `${this.baseUrl} has reported a new page load. The tab may be gone; ` +
+          '`vgai edit` reopens it.',
+      );
+    }
+    const answering = await this.pollUntil(deadline, async () => {
+      const ready = await this.postCommand({ type: 'list-instances' }, this.timeoutMs).catch(
+        () => ({ ok: false }) as RelayCommandBody,
+      );
+      return ready.ok;
+    });
+    if (!answering) {
+      throw new Error(
+        `vgai: reload ordered ${elapsedSeconds(orderedAt)}s ago — a new document loaded, but ` +
+          'its command listener has not answered yet. Check `vgai status` for page errors ' +
+          'from that load.',
+      );
+    }
+  }
+
+  /** Poll `check` every {@link RELOAD_POLL_MS} until it holds or `deadline`
+   *  passes; `false` means the deadline won, and the CALLER names what that
+   *  means — a shared "timed out" sentence would be exactly the kind of
+   *  message that says nothing about which witness was missing. */
+  private async pollUntil(deadline: number, check: () => Promise<boolean>): Promise<boolean> {
+    for (;;) {
+      await new Promise((resolve) => setTimeout(resolve, RELOAD_POLL_MS));
+      if (await check()) return true;
+      if (Date.now() >= deadline) return false;
+    }
+  }
+
+  /** Page-loads per present tab, from `/__editor/state`'s tab table — the
+   *  server's own count of the documents it has seen a tab run. Empty when
+   *  the server cannot answer, which witnesses nothing. */
+  private async readTabEpochs(): Promise<Map<string, number>> {
+    try {
+      const res = await fetch(`${this.baseUrl}/__editor/state`, {
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      const state = (await res.json()) as {
+        tabs?: { tabId8?: string; epochCount?: number }[];
+      };
+      const epochs = new Map<string, number>();
+      for (const tab of state.tabs ?? []) {
+        if (typeof tab.tabId8 === 'string' && typeof tab.epochCount === 'number') {
+          epochs.set(tab.tabId8, tab.epochCount);
+        }
+      }
+      return epochs;
+    } catch {
+      return new Map();
+    }
+  }
 }

package/src/game-client/types.ts

@@ -86,15 +86,15 @@ export interface DebugSnapshot {
      * Issue #175 — the REAL engine `GameLoop.liveness` behind this session
      * (mirrors `@vgai/engine`'s `GameLoopLiveness`; this package never
      * imports the engine — see the module doc above — so the union is
-     * declared here from the same contract). `'hidden-paused'` means the
-     * T2.1 idle throttle has stopped the loop because the tab is
-     * backgrounded: `simSeconds`/`tick` above are frozen, but this is NOT a
-     * crashed/wedged game — it resumes the instant the tab is foregrounded.
+     * declared here from the same contract). `'loop-starved'` means no recent
+     * host rAF callback was observed. It may reflect the current visibility
+     * gate or an armed callback the browser has starved; it is NOT itself a
+     * visibility verdict or proof that the game crashed.
      * `undefined` against an older bridge build that predates this field;
      * `null` when the live bridge has no loop wired at all (should not
      * happen against a real `Game`, but never fabricated either way).
      */
-    loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null;
+    loopLiveness?: 'running' | 'loop-starved' | 'stopped' | null;
   };
   state: Record<string, unknown>;
   events: TickStampedEvent[];
@@ -121,7 +121,7 @@ export interface VgaiBridgeHandle {
   runTicks(n: number, opts?: RunTicksOptions): void;
   /** Collapses `input.setVirtualAction(action, true)` → wait `simSeconds` of
    *  sim time (host-loop ticks while visible, deterministic same-phase ticks
-   *  while hidden-paused) → `input.clearVirtualActions()` into one call — see
+   *  while loop-starved) → `input.clearVirtualActions()` into one call — see
    *  `runtime/debug-bridge.ts`'s
    *  `holdFor` doc comment for the full contract (gated-immediately /
    *  play-stopped-mid-wait shapes). */