@vgai/live 0.5.13 → 0.5.14

package/dist/editor.d.ts

@@ -10,8 +10,9 @@
  * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
  * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
  */
-import type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedHierarchy, InspectedInspection, PresentedEditorView, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
+import type { ActiveDocumentCapture, AnimationCaptureAction, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, PresentedEditorView, ShadingMode, ViewPreset, 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';
 /**
@@ -33,6 +34,9 @@ export declare class LiveEditor {
      * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
      */
     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);
     /**
      * The active authoring adapter's persistence destination — where a save would
@@ -109,23 +113,10 @@ export declare class LiveEditor {
     stats(on: boolean): Promise<void>;
     shading(mode: ShadingMode): Promise<void>;
     /**
-     * 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.
      */
-    persistToGameSource(on: boolean): Promise<{
-        enabled: boolean;
-        recorder: string | null;
-    }>;
+    recordAnimation(action: AnimationCaptureAction): Promise<void>;
     /**
      * READ the inspector, as data — the serialized inspection subject
      * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
@@ -185,8 +176,15 @@ export declare 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).
      */
-    setField(path: string, value: unknown): Promise<InspectedInspection>;
+    setField(path: string, value: unknown): Promise<InspectedFieldWrite>;
     /** Undo / redo one project transaction, through the session's own history
      *  queue — the same one the keyboard shortcut drives. */
     undo(): Promise<HistoryStep>;

package/dist/editor.js

@@ -11,6 +11,7 @@
  * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
  */
 import { LiveEditorDocument } from './editor-document.js';
+import { LiveGameplayRecording } from './recording.js';
 const EXTENSION_KIND = {
     '.glb': 'model',
     '.gltf': 'model',
@@ -61,9 +62,13 @@ export class LiveEditor {
      * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
      */
     document;
+    /** Clean real-time game capture: start/stop through `vgai eval`, standard
+     * WebM on disk. This is evidence capture, not an animation authoring tool. */
+    recording;
     constructor(client) {
         this.#client = client;
         this.document = new LiveEditorDocument(client);
+        this.recording = new LiveGameplayRecording(client);
     }
     /**
      * The active authoring adapter's persistence destination — where a save would
@@ -216,21 +221,11 @@ export class LiveEditor {
         await this.#client.setShadingMode(mode);
     }
     /**
-     * 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) {
-        return this.#client.setSourcePersistConsent(on);
+    async recordAnimation(action) {
+        await this.#client.recordAnimation(action);
     }
     /**
      * READ the inspector, as data — the serialized inspection subject
@@ -295,6 +290,13 @@ 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, value) {
         return this.#client.setInspectionField(path, value);

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

@@ -76,4 +76,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/dist/game-client/capture-notes.d.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
@@ -22,9 +23,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,7 +50,7 @@ export type CaptureListener = (capture: CaptureRecord) => void | Promise<void>;
  * 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.
  */

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

@@ -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
@@ -19,23 +20,23 @@
  * listener — so the words a human reads in the terminal and the words a run
  * record carries beside the frame cannot drift apart.
  */
-/** 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) {
     const parts = [];
-    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/dist/game-client/client.d.ts

@@ -39,6 +39,10 @@ export declare class PageTransport implements BridgeTransport {
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
      *  to satisfy the shared interface). */
     runPageScript(_src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /** 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. */
+    reloadPage(): Promise<void>;
 }
 export interface GameClientOptions {
     /** The bridge transport — `new PageTransport(page)` for a standalone page
@@ -111,7 +115,7 @@ export declare 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.
      *
@@ -294,6 +298,17 @@ export declare class GameClient {
      * `runPageScript` doc comment for the full contract this method wraps.
      */
     page<T = unknown>(step: (page: Page) => T | Promise<T>): Promise<T>;
+    /**
+     * 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.
+     */
+    reloadPage(): Promise<void>;
     private toSessionFailure;
     /** run-3 friction #2 — called at the top of every bridge dispatch, before
      *  the await, so a burst of short calls (e.g. many `hold()`s) keeps

package/dist/game-client/client.js

@@ -128,6 +128,12 @@ export class PageTransport {
             };
         }
     }
+    /** 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() {
+        await this.page.reload();
+    }
 }
 /**
  * A relay-transport call that overran its async-invoke timeout budget
@@ -181,7 +187,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.
      *
@@ -672,6 +678,19 @@ export class GameClient {
         const outcome = await this.#transport.runPageScript(step.toString(), erased);
         return this.unwrap(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() {
+        await this.#transport.reloadPage();
+    }
     async toSessionFailure(err) {
         const providers = await this.providers();
         const screenshotPath = await this.screenshot('waitfor-timeout').catch(() => null);
@@ -694,7 +713,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/dist/game-client/failure-block.d.ts

@@ -39,7 +39,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`);
@@ -49,7 +49,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 {
     headline: string;
@@ -79,7 +79,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 {
     message: string;

package/dist/game-client/failure-block.js

@@ -26,14 +26,23 @@ export function annotateStateTiers(state, providers) {
 function ratioLine(simElapsedSeconds, wallElapsedMs, loopLiveness) {
     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.
-    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'
+    // 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 === '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 = `sim-time elapsed: ${simElapsedSeconds.toFixed(2)}s over ${wallElapsedS.toFixed(1)}s wall ` +

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

@@ -98,4 +98,44 @@ export declare class RelayTransport implements BridgeTransport {
      * `PageTransport` (which DOES call it directly) also implements.
      */
     runPageScript(src: string, _step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /**
+     * 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.
+     */
+    reloadPage(): Promise<void>;
+    /** 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 pollUntil;
+    /** 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 readTabEpochs;
 }

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

@@ -34,6 +34,16 @@ const PAGE_SCRIPT_TIMEOUT_MS = 60_000;
  *  long enough that the per-leg preflight doesn't double a bot's request
  *  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) {
+    return ((Date.now() - since) / 1000).toFixed(1);
+}
 export class RelayTransport {
     baseUrl;
     timeoutMs;
@@ -119,9 +129,13 @@ export class RelayTransport {
         const hidden = this.forceHiddenDrive || (await this.isHiddenCached());
         if (hidden && !this.hiddenDriveAnnounced) {
             this.hiddenDriveAnnounced = true;
-            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');
+            // 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 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;
     }
@@ -182,12 +196,12 @@ export class RelayTransport {
     }
     async screenshot(path) {
         // 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 } : {}),
@@ -205,7 +219,7 @@ export class RelayTransport {
         // human watching this terminal is looking.
         const warning = body['flatness']?.warning;
         const notes = {
-            ...(body['hiddenFrame'] === true ? { hiddenFrame: true } : {}),
+            ...(body['loopRecoveryFrame'] === true ? { loopRecoveryFrame: true } : {}),
             ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
         };
         const caveat = describeCaptureCaveat(notes);
@@ -238,4 +252,102 @@ export class RelayTransport {
             };
         }
     }
+    /**
+     * 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() {
+        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 }));
+            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. */
+    async pollUntil(deadline, check) {
+        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. */
+    async readTabEpochs() {
+        try {
+            const res = await fetch(`${this.baseUrl}/__editor/state`, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            const state = (await res.json());
+            const epochs = new Map();
+            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/dist/game-client/types.d.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[];
@@ -120,7 +120,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). */