@vgai/live 0.5.5 → 0.5.6

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

@@ -16,6 +16,7 @@
  * `@playwright/test` import here, nor in `relay-transport.ts` — only
  * `client.ts` is allowed to touch a live `Page` (see its own module doc).
  */
+import type { CaptureNotes } from './capture-notes.js';
 /** Result of one generic bridge-method call — thrown page/relay-side errors
  *  never cross either transport boundary AS themselves (Node only keeps
  *  `.message` across `page.evaluate`; HTTP/JSON strips everything but what
@@ -43,10 +44,13 @@ export interface BridgeTransport {
     isHidden(): Promise<boolean>;
     /** Bring the surface showing the game to the foreground. */
     bringToFront(): Promise<void>;
-    /** Capture a screenshot to `path` (PNG). A transport that cannot support
-     *  this should reject with a descriptive error rather than write a blank/
-     *  corrupt file. */
-    screenshot(path: string): Promise<void>;
+    /** Capture a screenshot to `path` (PNG), returning whatever the surface knows
+     *  about the conditions the frame was taken under ({@link CaptureNotes} — a
+     *  hidden surface, a near-blank frame). `{}` is the honest answer for a
+     *  transport that cannot observe either. A transport that cannot support the
+     *  capture at all should reject with a descriptive error rather than write a
+     *  blank/corrupt file. */
+    screenshot(path: string): Promise<CaptureNotes>;
     /**
      * Wave-2 "one dialect, full capability" — runs a UI-automation step
      * written as a literal `async (page) => {...}` (`GameClient.page()`,

package/dist/game-client/capture-notes.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What a capture knows about ITSELF beyond its pixels — and the one place the
+ * caveat sentence is spelled.
+ *
+ * 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
+ * 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
+ * terminal, invisible to anything that later reads the file.
+ *
+ * So the transport seam carries them back as {@link CaptureNotes}, and
+ * {@link describeCaptureCaveat} turns them into the ONE sentence every surface
+ * says. Its two callers are the transport's own console warning and
+ * `GameClient.screenshot`, which hands the composed caveat to every capture
+ * listener — so the words a human reads in the terminal and the words a run
+ * record carries beside the frame cannot drift apart.
+ */
+/** 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 page's own near-blank-frame sentence, verbatim (it owns the wording;
+     *  see `composite-screenshot.ts`'s `CaptureFlatness.warning`). */
+    readonly flatnessWarning?: string;
+}
+/** One capture, as reported to a {@link CaptureListener} after the bytes are
+ *  on disk. `caveat` is already composed — see {@link describeCaptureCaveat} —
+ *  so a listener never has to know how a degraded frame is detected, only that
+ *  this one is and what to say about it. */
+export interface CaptureRecord {
+    /** The caller's own `screenshot()` argument, label or path, unaltered. */
+    readonly label: string;
+    /** The absolute file the bytes landed at. */
+    readonly path: string;
+    /** What a reader must know about this frame, or `null` for an ordinary one. */
+    readonly caveat: string | null;
+}
+/** Notified after every capture a `GameClient` writes. May be async — the
+ *  client awaits it, so a listener that needs to read the game (to stamp the
+ *  capture with where the run was standing, say) can. */
+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
+ * out near-blank), and both are said — a capture that is degraded twice over
+ * must not report only the first reason.
+ */
+export declare function describeCaptureCaveat(notes: CaptureNotes): string | null;

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

@@ -0,0 +1,43 @@
+/**
+ * What a capture knows about ITSELF beyond its pixels — and the one place the
+ * caveat sentence is spelled.
+ *
+ * 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
+ * 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
+ * terminal, invisible to anything that later reads the file.
+ *
+ * So the transport seam carries them back as {@link CaptureNotes}, and
+ * {@link describeCaptureCaveat} turns them into the ONE sentence every surface
+ * says. Its two callers are the transport's own console warning and
+ * `GameClient.screenshot`, which hands the composed caveat to every capture
+ * 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
+ *  (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.';
+/**
+ * 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
+ * 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 (typeof notes.flatnessWarning === 'string' && notes.flatnessWarning !== '') {
+        parts.push(notes.flatnessWarning);
+    }
+    return parts.length === 0 ? null : parts.join(' ');
+}

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

@@ -8,6 +8,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 TpsStats } from './perf-sampling.js';
 import type { DebugCommandInfo, DebugSnapshot, ProviderInfo, VirtualActionValue } from './types.js';
@@ -27,7 +28,11 @@ export declare class PageTransport implements BridgeTransport {
     callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
     isHidden(): Promise<boolean>;
     bringToFront(): Promise<void>;
-    screenshot(path: string): Promise<void>;
+    /** No notes: Playwright drives its own foregrounded page, so neither the
+     *  hidden-surface nor the near-blank measurement the editor page makes
+     *  (`capture-notes.ts`) exists on this leg. `{}` says that honestly rather
+     *  than inventing a clean bill of health. */
+    screenshot(path: string): Promise<CaptureNotes>;
     /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
      *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
@@ -258,6 +263,20 @@ export declare class GameClient {
      * an empty path.
      */
     screenshot(labelOrPath: string): Promise<string>;
+    /**
+     * Watch every capture this client writes, and get back the unsubscribe.
+     *
+     * The reason this exists rather than each caller wrapping `screenshot()`:
+     * a run does not take all of its own captures. `waitFor`'s timeout path and
+     * `events.expect`'s failure path each shoot a frame on their own
+     * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
+     * observer may shoot one from inside a callback the driver never sees. The
+     * only place that sees ALL of them is here, which is why an autoplay run
+     * stamps its captures by listening rather than by intercepting
+     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
+     * listener).
+     */
+    onCapture(listener: CaptureListener): () => void;
     /**
      * Wave-2 "one dialect, full capability" — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface

package/dist/game-client/client.js

@@ -9,6 +9,7 @@
 import { mkdir } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { maybeBridgeHeartbeat } from './bridge-heartbeat.js';
+import { describeCaptureCaveat } from './capture-notes.js';
 import { appendWarmSessionHint, inputGatedError, SessionError, SessionFailure } from './errors.js';
 import { describeEventsExpectation, matchEventsSubsequence } from './events-matcher.js';
 import { assembleFailureBlock } from './failure-block.js';
@@ -101,9 +102,14 @@ export class PageTransport {
     async bringToFront() {
         await this.page.bringToFront();
     }
+    /** No notes: Playwright drives its own foregrounded page, so neither the
+     *  hidden-surface nor the near-blank measurement the editor page makes
+     *  (`capture-notes.ts`) exists on this leg. `{}` says that honestly rather
+     *  than inventing a clean bill of health. */
     async screenshot(path) {
         await mkdir(dirname(path), { recursive: true });
         await this.page.screenshot({ path });
+        return {};
     }
     /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
@@ -405,6 +411,8 @@ export class GameClient {
     /** See `GameClientOptions.testTitle`. */
     #testTitle;
     #screenshotCounter = 0;
+    /** Everyone watching this client's captures — see {@link GameClient.onCapture}. */
+    #captureListeners = new Set();
     /** Per-test tick-rate samples, fed by every `snapshot()` read (a poll the
      *  client was making anyway — zero extra page.evaluate round trips). */
     #tps = new TpsAccumulator();
@@ -608,9 +616,41 @@ export class GameClient {
         if (target.consumedSequence)
             this.#screenshotCounter += 1;
         await mkdir(dirname(target.path), { recursive: true });
-        await this.#transport.screenshot(target.path);
+        const notes = await this.#transport.screenshot(target.path);
+        const capture = {
+            label: labelOrPath,
+            path: target.path,
+            caveat: describeCaptureCaveat(notes),
+        };
+        // Sequential and AWAITED: a listener may need to read the game to stamp
+        // this capture, and it must have finished before the path is handed back —
+        // a caller that files the path is entitled to assume the record of it is
+        // already complete. A throwing listener fails the call rather than being
+        // swallowed: a capture whose bookkeeping silently did not happen is the
+        // fabricated-evidence shape this whole seam exists to prevent.
+        for (const listener of this.#captureListeners)
+            await listener(capture);
         return target.path;
     }
+    /**
+     * Watch every capture this client writes, and get back the unsubscribe.
+     *
+     * The reason this exists rather than each caller wrapping `screenshot()`:
+     * a run does not take all of its own captures. `waitFor`'s timeout path and
+     * `events.expect`'s failure path each shoot a frame on their own
+     * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
+     * observer may shoot one from inside a callback the driver never sees. The
+     * only place that sees ALL of them is here, which is why an autoplay run
+     * stamps its captures by listening rather than by intercepting
+     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
+     * listener).
+     */
+    onCapture(listener) {
+        this.#captureListeners.add(listener);
+        return () => {
+            this.#captureListeners.delete(listener);
+        };
+    }
     /**
      * Wave-2 "one dialect, full capability" — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface

package/dist/game-client/index.d.ts

@@ -16,6 +16,8 @@
 export type { BridgeHeartbeatState } from './bridge-heartbeat.js';
 export { BRIDGE_HEARTBEAT_INTERVAL_MS, formatBridgeHeartbeatLine } from './bridge-heartbeat.js';
 export type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+export type { CaptureListener, CaptureNotes, CaptureRecord } from './capture-notes.js';
+export { describeCaptureCaveat } from './capture-notes.js';
 export type { GameClientOptions } from './client.js';
 export { GameClient, GameEvents, GameInput, PageTransport } from './client.js';
 export type { SessionErrorCode } from './errors.js';

package/dist/game-client/index.js

@@ -14,6 +14,7 @@
  * a dozen sibling paths; nothing here imports anything from `../`.
  */
 export { BRIDGE_HEARTBEAT_INTERVAL_MS, formatBridgeHeartbeatLine } from './bridge-heartbeat.js';
+export { describeCaptureCaveat } from './capture-notes.js';
 export { GameClient, GameEvents, GameInput, PageTransport } from './client.js';
 export { SESSION_ERROR_CODES, SessionError, SessionFailure } from './errors.js';
 export { matchEventsSubsequence } from './events-matcher.js';

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

@@ -19,6 +19,7 @@
  * anywhere in this path).
  */
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+import { type CaptureNotes } from './capture-notes.js';
 export interface RelayTransportOptions {
     /** The live editor session's dev-server port (e.g. from
      *  `findLiveEditorSession`/`vgai edit`). */
@@ -86,7 +87,7 @@ export declare class RelayTransport implements BridgeTransport {
      * path `call('snapshot')` normally activates from `/__editor/state`.
      */
     bringToFront(): Promise<void>;
-    screenshot(path: string): Promise<void>;
+    screenshot(path: string): Promise<CaptureNotes>;
     /**
      * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
      * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`

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

@@ -20,6 +20,7 @@
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { describeCaptureCaveat } from './capture-notes.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** `invoke` dispatches to arbitrary game-registered debug commands — give it
  *  real headroom rather than the ordinary sync-call budget above. */
@@ -196,18 +197,21 @@ export class RelayTransport {
         }
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, Buffer.from(body['base64'], 'base64'));
-        // `game.screenshot()` hands back a path, so a near-blank frame is
-        // indistinguishable from a good one until somebody opens the file — which
-        // is exactly how two probes cited blank captures as evidence. The page
-        // wrote the sentence; say it where the caller is looking.
+        // `game.screenshot()` hands back a path, so a near-blank or on-demand frame
+        // is indistinguishable from a good one until somebody opens the file —
+        // which is exactly how two probes cited blank captures as evidence. The
+        // page measured both conditions; carry them back so the caller can persist
+        // them beside the frame, and say the composed sentence here too, where a
+        // human watching this terminal is looking.
         const warning = body['flatness']?.warning;
-        if (typeof warning === 'string')
-            console.warn(`vgai screenshot: warning — ${warning}`);
-        if (body['hiddenFrame'] === true) {
-            console.warn(`vgai screenshot: ${path} is a HIDDEN FRAME — the editor tab is hidden, so the runtime ` +
-                'rendered one deterministic tick on demand. It is current, not stale; it is not a ' +
-                'frame anyone was watching.');
-        }
+        const notes = {
+            ...(body['hiddenFrame'] === true ? { hiddenFrame: true } : {}),
+            ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
+        };
+        const caveat = describeCaptureCaveat(notes);
+        if (caveat !== null)
+            console.warn(`vgai screenshot: ${path} — ${caveat}`);
+        return notes;
     }
     /**
      * Wave-2: ships `src` (`step.toString()`) to the editor dev server's

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,11 +27,12 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json"
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.5",
-    "@vgai/sdk": "0.5.5"
+    "@vgai/editor-sdk": "0.5.6",
+    "@vgai/sdk": "0.5.6"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

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

@@ -17,6 +17,8 @@
  * `client.ts` is allowed to touch a live `Page` (see its own module doc).
  */
 
+import type { CaptureNotes } from './capture-notes.js';
+
 /** Result of one generic bridge-method call — thrown page/relay-side errors
  *  never cross either transport boundary AS themselves (Node only keeps
  *  `.message` across `page.evaluate`; HTTP/JSON strips everything but what
@@ -41,10 +43,13 @@ export interface BridgeTransport {
   isHidden(): Promise<boolean>;
   /** Bring the surface showing the game to the foreground. */
   bringToFront(): Promise<void>;
-  /** Capture a screenshot to `path` (PNG). A transport that cannot support
-   *  this should reject with a descriptive error rather than write a blank/
-   *  corrupt file. */
-  screenshot(path: string): Promise<void>;
+  /** Capture a screenshot to `path` (PNG), returning whatever the surface knows
+   *  about the conditions the frame was taken under ({@link CaptureNotes} — a
+   *  hidden surface, a near-blank frame). `{}` is the honest answer for a
+   *  transport that cannot observe either. A transport that cannot support the
+   *  capture at all should reject with a descriptive error rather than write a
+   *  blank/corrupt file. */
+  screenshot(path: string): Promise<CaptureNotes>;
   /**
    * Wave-2 "one dialect, full capability" — runs a UI-automation step
    * written as a literal `async (page) => {...}` (`GameClient.page()`,

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

@@ -0,0 +1,74 @@
+/**
+ * What a capture knows about ITSELF beyond its pixels — and the one place the
+ * caveat sentence is spelled.
+ *
+ * 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
+ * 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
+ * terminal, invisible to anything that later reads the file.
+ *
+ * So the transport seam carries them back as {@link CaptureNotes}, and
+ * {@link describeCaptureCaveat} turns them into the ONE sentence every surface
+ * says. Its two callers are the transport's own console warning and
+ * `GameClient.screenshot`, which hands the composed caveat to every capture
+ * listener — so the words a human reads in the terminal and the words a run
+ * record carries beside the frame cannot drift apart.
+ */
+
+/** 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 page's own near-blank-frame sentence, verbatim (it owns the wording;
+   *  see `composite-screenshot.ts`'s `CaptureFlatness.warning`). */
+  readonly flatnessWarning?: string;
+}
+
+/** One capture, as reported to a {@link CaptureListener} after the bytes are
+ *  on disk. `caveat` is already composed — see {@link describeCaptureCaveat} —
+ *  so a listener never has to know how a degraded frame is detected, only that
+ *  this one is and what to say about it. */
+export interface CaptureRecord {
+  /** The caller's own `screenshot()` argument, label or path, unaltered. */
+  readonly label: string;
+  /** The absolute file the bytes landed at. */
+  readonly path: string;
+  /** What a reader must know about this frame, or `null` for an ordinary one. */
+  readonly caveat: string | null;
+}
+
+/** Notified after every capture a `GameClient` writes. May be async — the
+ *  client awaits it, so a listener that needs to read the game (to stamp the
+ *  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
+ *  (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.';
+
+/**
+ * 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
+ * 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 (typeof notes.flatnessWarning === 'string' && notes.flatnessWarning !== '') {
+    parts.push(notes.flatnessWarning);
+  }
+  return parts.length === 0 ? null : parts.join(' ');
+}

package/src/game-client/client.ts

@@ -12,6 +12,7 @@ import { dirname, resolve } from 'node:path';
 import type { Page } from '@playwright/test';
 import { type BridgeHeartbeatState, maybeBridgeHeartbeat } from './bridge-heartbeat.js';
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+import { type CaptureListener, type CaptureNotes, describeCaptureCaveat } from './capture-notes.js';
 import { appendWarmSessionHint, inputGatedError, SessionError, SessionFailure } from './errors.js';
 import { describeEventsExpectation, matchEventsSubsequence } from './events-matcher.js';
 import { assembleFailureBlock } from './failure-block.js';
@@ -130,9 +131,14 @@ export class PageTransport implements BridgeTransport {
     await this.page.bringToFront();
   }
 
-  async screenshot(path: string): Promise<void> {
+  /** No notes: Playwright drives its own foregrounded page, so neither the
+   *  hidden-surface nor the near-blank measurement the editor page makes
+   *  (`capture-notes.ts`) exists on this leg. `{}` says that honestly rather
+   *  than inventing a clean bill of health. */
+  async screenshot(path: string): Promise<CaptureNotes> {
     await mkdir(dirname(path), { recursive: true });
     await this.page.screenshot({ path });
+    return {};
   }
 
   /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
@@ -510,6 +516,8 @@ export class GameClient {
   /** See `GameClientOptions.testTitle`. */
   readonly #testTitle: string;
   #screenshotCounter = 0;
+  /** Everyone watching this client's captures — see {@link GameClient.onCapture}. */
+  readonly #captureListeners = new Set<CaptureListener>();
   /** Per-test tick-rate samples, fed by every `snapshot()` read (a poll the
    *  client was making anyway — zero extra page.evaluate round trips). */
   readonly #tps = new TpsAccumulator();
@@ -731,10 +739,42 @@ export class GameClient {
     });
     if (target.consumedSequence) this.#screenshotCounter += 1;
     await mkdir(dirname(target.path), { recursive: true });
-    await this.#transport.screenshot(target.path);
+    const notes = await this.#transport.screenshot(target.path);
+    const capture = {
+      label: labelOrPath,
+      path: target.path,
+      caveat: describeCaptureCaveat(notes),
+    };
+    // Sequential and AWAITED: a listener may need to read the game to stamp
+    // this capture, and it must have finished before the path is handed back —
+    // a caller that files the path is entitled to assume the record of it is
+    // already complete. A throwing listener fails the call rather than being
+    // swallowed: a capture whose bookkeeping silently did not happen is the
+    // fabricated-evidence shape this whole seam exists to prevent.
+    for (const listener of this.#captureListeners) await listener(capture);
     return target.path;
   }
 
+  /**
+   * Watch every capture this client writes, and get back the unsubscribe.
+   *
+   * The reason this exists rather than each caller wrapping `screenshot()`:
+   * a run does not take all of its own captures. `waitFor`'s timeout path and
+   * `events.expect`'s failure path each shoot a frame on their own
+   * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
+   * observer may shoot one from inside a callback the driver never sees. The
+   * only place that sees ALL of them is here, which is why an autoplay run
+   * stamps its captures by listening rather than by intercepting
+   * (`src/tools/route-context.ts` in a scaffolded project is the shipped
+   * listener).
+   */
+  onCapture(listener: CaptureListener): () => void {
+    this.#captureListeners.add(listener);
+    return () => {
+      this.#captureListeners.delete(listener);
+    };
+  }
+
   /**
    * Wave-2 "one dialect, full capability" — runs a UI-automation step
    * written as a literal Playwright `async (page) => {...}` (interface

package/src/game-client/index.ts

@@ -17,6 +17,8 @@
 export type { BridgeHeartbeatState } from './bridge-heartbeat.js';
 export { BRIDGE_HEARTBEAT_INTERVAL_MS, formatBridgeHeartbeatLine } from './bridge-heartbeat.js';
 export type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+export type { CaptureListener, CaptureNotes, CaptureRecord } from './capture-notes.js';
+export { describeCaptureCaveat } from './capture-notes.js';
 export type { GameClientOptions } from './client.js';
 export { GameClient, GameEvents, GameInput, PageTransport } from './client.js';
 export type { SessionErrorCode } from './errors.js';

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

@@ -22,6 +22,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+import { type CaptureNotes, describeCaptureCaveat } from './capture-notes.js';
 
 export interface RelayTransportOptions {
   /** The live editor session's dev-server port (e.g. from
@@ -246,7 +247,7 @@ export class RelayTransport implements BridgeTransport {
     this.forceHiddenDrive = true;
   }
 
-  async screenshot(path: string): Promise<void> {
+  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
     // deterministic one-tick refresh instead of a `BRIDGE_SCREENSHOT_STALE`
@@ -268,19 +269,20 @@ export class RelayTransport implements BridgeTransport {
     }
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, Buffer.from(body['base64'] as string, 'base64'));
-    // `game.screenshot()` hands back a path, so a near-blank frame is
-    // indistinguishable from a good one until somebody opens the file — which
-    // is exactly how two probes cited blank captures as evidence. The page
-    // wrote the sentence; say it where the caller is looking.
+    // `game.screenshot()` hands back a path, so a near-blank or on-demand frame
+    // is indistinguishable from a good one until somebody opens the file —
+    // which is exactly how two probes cited blank captures as evidence. The
+    // page measured both conditions; carry them back so the caller can persist
+    // them beside the frame, and say the composed sentence here too, where a
+    // human watching this terminal is looking.
     const warning = (body['flatness'] as { warning?: string } | undefined)?.warning;
-    if (typeof warning === 'string') console.warn(`vgai screenshot: warning — ${warning}`);
-    if (body['hiddenFrame'] === true) {
-      console.warn(
-        `vgai screenshot: ${path} is a HIDDEN FRAME — the editor tab is hidden, so the runtime ` +
-          'rendered one deterministic tick on demand. It is current, not stale; it is not a ' +
-          'frame anyone was watching.',
-      );
-    }
+    const notes: CaptureNotes = {
+      ...(body['hiddenFrame'] === true ? { hiddenFrame: true } : {}),
+      ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
+    };
+    const caveat = describeCaptureCaveat(notes);
+    if (caveat !== null) console.warn(`vgai screenshot: ${path} — ${caveat}`);
+    return notes;
   }
 
   /**