@vgai/live 0.5.2 → 0.5.4

package/dist/editor.d.ts

@@ -1,42 +1,18 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (SHARED-SESSION-SPEC.md, Wave 2). Methods are named after the
+ * page }` (Wave 2). Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
- * separate `selectAll`, `showPanel('viewport-game')` rather than
- * `vgai show viewport game`'s two-token shape) — see each method's own doc
+ * separate `selectAll`, `showPanel('viewport-play')` rather than
+ * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
- * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module
- * never hand-rolls a `fetch` to `/__editor/command` itself. The ONE
- * exception is `applyDiff`, which is FILE mode (writes the scene file
- * directly), not a live wire command — see its own doc comment.
+ * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
+ * 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, EditorClient, EditorState, EditorView, PresentedEditorView, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
+import type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, InspectedInspection, PresentedEditorView, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
 /** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
-export type PanelName = 'viewport-scene' | 'viewport-game' | 'inspector' | 'console' | 'build';
-/** Mirrors `@vgai/sdk`'s `project.scene.apply` operation input — the same shape `vgai apply-diff` builds from its `<scene> <patch>` file arguments. `patch` is a `SceneDiff` JSON object (validated by the operation's own Zod schema — a malformed patch throws, never silently no-ops). */
-export interface ApplyDiffInput {
-    /** Project-relative path to the `.vscn.json` scene file to modify. */
-    scenePath: string;
-    /** A `SceneDiff`-shaped patch object. */
-    patch: unknown;
-    /** Validate + report only — never write to disk. Default `false`. */
-    dryRun?: boolean;
-    /** Refuse a stale write when the file's content hash no longer matches (optimistic concurrency) — omit to skip the check. */
-    baseHash?: string;
-}
-/** The `project.scene.apply` operation's result shape. */
-export interface ApplyDiffResult {
-    dryRun: boolean;
-    written: boolean;
-    filesChanged: string[];
-    before: {
-        scene: unknown;
-    };
-    after: {
-        scene: unknown;
-    };
-}
+export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'console' | 'build';
 /**
  * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
  * `kind` argument. Deliberately independent of (not shared with) the
@@ -46,18 +22,17 @@ export interface ApplyDiffResult {
  */
 export declare function inferAssetKind(path: string): AssetKind;
 export declare class LiveEditor {
-    private readonly client;
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    private readonly projectRoot;
-    constructor(client: EditorClient, 
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    projectRoot: string);
+    #private;
+    constructor(client: EditorClient);
     /**
-     * No `path` -> the currently open scene's save path (`status().savePath`).
-     * `path` given -> opens it (`EditorClient.openScene` — the same wire call
-     * `vgai scene <path>` sends), and the given path is returned back.
+     * The active authoring adapter's persistence destination — where a save would
+     * land (`status().savePath`).
+     *
+     * WO-8: this also took a `path` and OPENED that scene through
+     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
+     * (the `.vscn.json` format is deleted), so only the read remains.
      */
-    scene(path?: string): Promise<string | null>;
+    scene(): Promise<string | null>;
     /**
      * Make the connected human editor show the same subject/view as the agent.
      * The returned URL is a compact, shareable projection — not a serialized
@@ -68,16 +43,6 @@ export declare class LiveEditor {
     currentView(): Promise<EditorView>;
     /** Capture the same center document the human is currently looking at. */
     captureActiveDocument(size?: number): Promise<ActiveDocumentCapture>;
-    /**
-     * FILE mode — writes the scene file directly. NOT a live wire command:
-     * there is no live-editor wire op for this yet (`vgai apply-diff`'s own
-     * module doc names the identical gap: "LIVE MODE — NOT BUILT ... route the
-     * patch through a RUNNING editor"). Reuses the exact same engine
-     * machinery `vgai apply-diff` uses, through `@vgai/sdk`'s
-     * `project.scene.apply` operation (the operation-registry's own
-     * projection of that logic) — never hand-rolled here.
-     */
-    applyDiff(input: ApplyDiffInput): Promise<ApplyDiffResult>;
     play(opts?: {
         seed?: number;
     }): Promise<void>;
@@ -92,17 +57,75 @@ export declare class LiveEditor {
     deselect(): Promise<void>;
     /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
     focus(id?: string): Promise<void>;
+    /**
+     * Frame the edit viewport camera on one entity. Same framing as
+     * `focus(id)`, but an entity id the scene does not know THROWS, naming the
+     * id — where `focus` quietly does nothing. Reach for this whenever the next
+     * step reads the viewport (`screenshot()`, an
+     * `assetPreview(..., { stage: 'scene' })`): a framing that silently missed
+     * would otherwise be indistinguishable from one that worked.
+     */
+    frame(entityId: string): Promise<void>;
     view(preset: ViewPreset): Promise<void>;
-    /** `vgai show <viewport <scene|game>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
+    /**
+     * Show several instances of the running game split-screen — the whole point
+     * of multiplayer authoring: `await editor.instances(2)` puts a second view
+     * beside the first, watchable by a human, each drivable by its own bot
+     * (`game.instance(id)` / `tools.run(name, params, { instance })`). Pass a
+     * TOTAL count (default "Player 1"/"Player 2"/… labels) or explicit names
+     * (`editor.instances(['Alice', 'Bob'])`, index 0 = primary). A count of `1`
+     * (or a single name) collapses back to a single view. Requires a live play
+     * session.
+     */
+    instances(countOrNames: number | string[]): Promise<void>;
+    /** `vgai show <viewport <edit|play>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
     showPanel(name: PanelName): Promise<void>;
     /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
     openAsset(path: string, kind?: AssetKind): Promise<void>;
-    /** Captures the editor's native Asset Lab four-view preview for `path` (a project-relative asset path). */
-    assetPreview(path: string, options?: AssetPreviewOptions): Promise<AssetPreviewCapture>;
+    /**
+     * Captures the editor's native four-view preview. A bare string is a
+     * project-relative asset path (the common case); an explicit source object
+     * targets a path, a LIVE SCENE ENTITY (`assetPreview({ entityId }, …)`) —
+     * which is what makes `options.stage: 'scene'`, the entity photographed
+     * where it stands under the scene's own lighting, reachable from here — or
+     * RAW GLB BYTES (`assetPreview({ glbBase64 }, …)`), for a model that exists
+     * only in the calling Node process's memory and has never been written to
+     * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging this has
+     * always produced, and the bytes form is lab-only.
+     */
+    assetPreview(source: string | AssetPreviewSource, options?: AssetPreviewOptions): Promise<AssetPreviewCapture>;
     grid(on: boolean): Promise<void>;
     helpers(on: boolean): Promise<void>;
     stats(on: boolean): Promise<void>;
     shading(mode: ShadingMode): Promise<void>;
+    /**
+     * READ the inspector, as data — the serialized inspection subject
+     * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
+     * "The Inspection Model"). This is the Figma-Inspect analog: whatever a
+     * human would see in the inspector right now — the subject's identity, its
+     * verbs, and every identified section in display order, with a `fields`
+     * section's CURRENT VALUES at their scriptable `path`s.
+     *
+     * Reach for it whenever the next step depends on what an object actually
+     * IS: `await editor.select(id)` then `await editor.inspect()` answers "what
+     * properties does this thing have, and what are they set to" in one call,
+     * against the same model the panel renders — no scene-graph reads, no
+     * guessing at property names.
+     *
+     * When the inspector is showing NOTHING — nothing selected on a surface
+     * with no empty-state subject of its own, which is most of them — the answer
+     * is `{none: true}`, so "the human sees no inspector" and "the read failed"
+     * are never the same value. A surface whose empty space IS a real thing (an
+     * open Asset Lab document) still answers with that subject, and never with
+     * another surface's.
+     *
+     * A `custom` section body is a named opaque: the editor renders it with
+     * React, so the wire reports its identity rather than pretending to describe
+     * its rendering — plus, when the section can say what it DISPLAYS, a `data`
+     * payload in its own vocabulary (`transform` carries
+     * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
+     */
+    inspect(): Promise<InspectedInspection>;
     /** Mirrors `vgai status` — the full live editor state as JSON. */
     status(): Promise<EditorState>;
     /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */

package/dist/editor.js

@@ -1,17 +1,15 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (SHARED-SESSION-SPEC.md, Wave 2). Methods are named after the
+ * page }` (Wave 2). Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
- * separate `selectAll`, `showPanel('viewport-game')` rather than
- * `vgai show viewport game`'s two-token shape) — see each method's own doc
+ * separate `selectAll`, `showPanel('viewport-play')` rather than
+ * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
- * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module
- * never hand-rolls a `fetch` to `/__editor/command` itself. The ONE
- * exception is `applyDiff`, which is FILE mode (writes the scene file
- * directly), not a live wire command — see its own doc comment.
+ * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
+ * 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 { operations } from '@vgai/sdk';
 const EXTENSION_KIND = {
     '.glb': 'model',
     '.gltf': 'model',
@@ -20,6 +18,7 @@ const EXTENSION_KIND = {
     '.jpeg': 'image',
     '.webp': 'image',
     '.gif': 'image',
+    '.svg': 'image',
     '.mp3': 'audio',
     '.ogg': 'audio',
     '.wav': 'audio',
@@ -33,8 +32,10 @@ const EXTENSION_KIND = {
  * on. Callers with an unusual extension can always pass `kind` explicitly.
  */
 export function inferAssetKind(path) {
-    if (path.endsWith('.vscn.json'))
-        return 'scene';
+    // WO-8: `.vscn.json` mapped to 'scene' here. That format is deleted, and
+    // `.prefab.json` is likewise retired (PRs #578/#581/#589) but the `'prefab'`
+    // AssetKind itself still exists in `@vgai/editor-sdk`, so the mapping is left
+    // for that retirement's own follow-up rather than half-removed here.
     if (path.endsWith('.prefab.json'))
         return 'prefab';
     if (path.endsWith('.mat.json'))
@@ -44,25 +45,24 @@ export function inferAssetKind(path) {
     return EXTENSION_KIND[ext] ?? 'json';
 }
 export class LiveEditor {
-    client;
-    projectRoot;
-    constructor(client, 
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    projectRoot) {
-        this.client = client;
-        this.projectRoot = projectRoot;
+    /** `#`-private, not `private`: `vgai eval --list` enumerates this object's
+     *  real runtime members, and TypeScript's erased `private` would leave the
+     *  raw `EditorClient` advertised beside them. See `./game-client/`'s
+     *  `client.ts` (GameClient's field block) for the full reasoning. */
+    #client;
+    constructor(client) {
+        this.#client = client;
     }
     /**
-     * No `path` -> the currently open scene's save path (`status().savePath`).
-     * `path` given -> opens it (`EditorClient.openScene` — the same wire call
-     * `vgai scene <path>` sends), and the given path is returned back.
+     * The active authoring adapter's persistence destination — where a save would
+     * land (`status().savePath`).
+     *
+     * WO-8: this also took a `path` and OPENED that scene through
+     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
+     * (the `.vscn.json` format is deleted), so only the read remains.
      */
-    async scene(path) {
-        if (path !== undefined) {
-            await this.client.openScene(path);
-            return path;
-        }
-        const state = await this.client.getState();
+    async scene() {
+        const state = await this.#client.getState();
         return state.savePath;
     }
     /**
@@ -71,121 +71,174 @@ export class LiveEditor {
      * workspace or document payload.
      */
     async present(view) {
-        return this.client.present(view);
+        return this.#client.present(view);
     }
     /** The human editor's actual active document, selection, camera and utility. */
     async currentView() {
-        return this.client.currentView();
+        return this.#client.currentView();
     }
     /** Capture the same center document the human is currently looking at. */
     async captureActiveDocument(size) {
-        return this.client.captureActiveDocument(size);
-    }
-    /**
-     * FILE mode — writes the scene file directly. NOT a live wire command:
-     * there is no live-editor wire op for this yet (`vgai apply-diff`'s own
-     * module doc names the identical gap: "LIVE MODE — NOT BUILT ... route the
-     * patch through a RUNNING editor"). Reuses the exact same engine
-     * machinery `vgai apply-diff` uses, through `@vgai/sdk`'s
-     * `project.scene.apply` operation (the operation-registry's own
-     * projection of that logic) — never hand-rolled here.
+        return this.#client.captureActiveDocument(size);
+    }
+    /*
+     * `applyDiff` lived here. It dispatched `project.scene.apply`, one of the
+     * twelve `.vscn` document tools deleted with the format, so there is nothing
+     * left for it to call. `ApplyDiffInput` / `ApplyDiffResult` went with it, and
+     * so did `projectRoot` — this was the ONE method that used it (every other
+     * method goes over the wire).
      */
-    async applyDiff(input) {
-        const outcome = await operations.dispatch('project.scene.apply', input, {
-            projectRoot: this.projectRoot,
-        });
-        if (!outcome.ok) {
-            throw new Error(`@vgai/live: applyDiff failed [${outcome.error.code}]: ${outcome.error.message}`);
-        }
-        return outcome.data;
-    }
     async play(opts) {
-        await this.client.play(opts);
+        await this.#client.play(opts);
     }
     async stop() {
-        await this.client.stop();
+        await this.#client.stop();
     }
     async pause() {
-        await this.client.pause();
+        await this.#client.pause();
     }
     async resume() {
-        await this.client.resume();
+        await this.#client.resume();
     }
     /** Advance `n` frames (default 1) — `EditorClient.step()` sent `n` times, mirroring `vgai step` run repeatedly. */
     async step(n = 1) {
         for (let i = 0; i < n; i++) {
-            await this.client.step();
+            await this.#client.step();
         }
     }
     /** `'all'` -> `EditorClient.selectAll()` (mirrors `vgai select --all`); otherwise `EditorClient.select(id)` (mirrors `vgai select <entityId>`). */
     async select(id) {
         if (id === 'all') {
-            await this.client.selectAll();
+            await this.#client.selectAll();
             return;
         }
-        await this.client.select(id);
+        await this.#client.select(id);
     }
     /** Mirrors `vgai deselect`. */
     async deselect() {
-        await this.client.select(null);
+        await this.#client.select(null);
     }
     /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
     async focus(id) {
         if (id !== undefined) {
-            await this.client.focusEntity(id);
+            await this.#client.focusEntity(id);
             return;
         }
-        await this.client.focusSelection();
+        await this.#client.focusSelection();
+    }
+    /**
+     * Frame the edit viewport camera on one entity. Same framing as
+     * `focus(id)`, but an entity id the scene does not know THROWS, naming the
+     * id — where `focus` quietly does nothing. Reach for this whenever the next
+     * step reads the viewport (`screenshot()`, an
+     * `assetPreview(..., { stage: 'scene' })`): a framing that silently missed
+     * would otherwise be indistinguishable from one that worked.
+     */
+    async frame(entityId) {
+        await this.#client.frameEntity(entityId);
     }
     async view(preset) {
-        await this.client.viewPreset(preset);
+        await this.#client.viewPreset(preset);
     }
-    /** `vgai show <viewport <scene|game>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
+    /**
+     * Show several instances of the running game split-screen — the whole point
+     * of multiplayer authoring: `await editor.instances(2)` puts a second view
+     * beside the first, watchable by a human, each drivable by its own bot
+     * (`game.instance(id)` / `tools.run(name, params, { instance })`). Pass a
+     * TOTAL count (default "Player 1"/"Player 2"/… labels) or explicit names
+     * (`editor.instances(['Alice', 'Bob'])`, index 0 = primary). A count of `1`
+     * (or a single name) collapses back to a single view. Requires a live play
+     * session.
+     */
+    async instances(countOrNames) {
+        await this.#client.setInstanceCount(countOrNames);
+    }
+    /** `vgai show <viewport <edit|play>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
     async showPanel(name) {
         switch (name) {
-            case 'viewport-scene':
-                await this.client.showViewport('scene');
+            case 'viewport-edit':
+                await this.#client.showViewport('edit');
                 return;
-            case 'viewport-game':
-                await this.client.showViewport('game');
+            case 'viewport-play':
+                await this.#client.showViewport('play');
                 return;
             case 'inspector':
-                await this.client.showInspector();
+                await this.#client.showInspector();
                 return;
             case 'console':
-                await this.client.toggleConsole();
+                await this.#client.toggleConsole();
                 return;
             case 'build':
-                await this.client.showBuild();
+                await this.#client.showBuild();
                 return;
         }
     }
     /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
     async openAsset(path, kind) {
-        await this.client.openAsset(path, kind ?? inferAssetKind(path));
+        await this.#client.openAsset(path, kind ?? inferAssetKind(path));
     }
-    /** Captures the editor's native Asset Lab four-view preview for `path` (a project-relative asset path). */
-    async assetPreview(path, options) {
-        return this.client.captureAssetPreview({ assetPath: path }, options);
+    /**
+     * Captures the editor's native four-view preview. A bare string is a
+     * project-relative asset path (the common case); an explicit source object
+     * targets a path, a LIVE SCENE ENTITY (`assetPreview({ entityId }, …)`) —
+     * which is what makes `options.stage: 'scene'`, the entity photographed
+     * where it stands under the scene's own lighting, reachable from here — or
+     * RAW GLB BYTES (`assetPreview({ glbBase64 }, …)`), for a model that exists
+     * only in the calling Node process's memory and has never been written to
+     * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging this has
+     * always produced, and the bytes form is lab-only.
+     */
+    async assetPreview(source, options) {
+        return this.#client.captureAssetPreview(typeof source === 'string' ? { assetPath: source } : source, options);
     }
     async grid(on) {
-        await this.client.setGrid(on);
+        await this.#client.setGrid(on);
     }
     async helpers(on) {
-        await this.client.setHelpers(on);
+        await this.#client.setHelpers(on);
     }
     async stats(on) {
-        await this.client.setStats(on);
+        await this.#client.setStats(on);
     }
     async shading(mode) {
-        await this.client.setShadingMode(mode);
+        await this.#client.setShadingMode(mode);
+    }
+    /**
+     * READ the inspector, as data — the serialized inspection subject
+     * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
+     * "The Inspection Model"). This is the Figma-Inspect analog: whatever a
+     * human would see in the inspector right now — the subject's identity, its
+     * verbs, and every identified section in display order, with a `fields`
+     * section's CURRENT VALUES at their scriptable `path`s.
+     *
+     * Reach for it whenever the next step depends on what an object actually
+     * IS: `await editor.select(id)` then `await editor.inspect()` answers "what
+     * properties does this thing have, and what are they set to" in one call,
+     * against the same model the panel renders — no scene-graph reads, no
+     * guessing at property names.
+     *
+     * When the inspector is showing NOTHING — nothing selected on a surface
+     * with no empty-state subject of its own, which is most of them — the answer
+     * is `{none: true}`, so "the human sees no inspector" and "the read failed"
+     * are never the same value. A surface whose empty space IS a real thing (an
+     * open Asset Lab document) still answers with that subject, and never with
+     * another surface's.
+     *
+     * A `custom` section body is a named opaque: the editor renders it with
+     * React, so the wire reports its identity rather than pretending to describe
+     * its rendering — plus, when the section can say what it DISPLAYS, a `data`
+     * payload in its own vocabulary (`transform` carries
+     * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
+     */
+    async inspect() {
+        return this.#client.inspect();
     }
     /** Mirrors `vgai status` — the full live editor state as JSON. */
     async status() {
-        return this.client.getState();
+        return this.#client.getState();
     }
     /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */
     async screenshot(size) {
-        return this.client.captureViewport(size);
+        return this.#client.captureViewport(size);
     }
 }

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

@@ -0,0 +1,49 @@
+/**
+ * run-3 dogfood friction #2 — a legitimately-progressing script built from
+ * many short `game.input.hold()` calls looked WEDGED to anything watching its
+ * stdout for liveness, even though it was making real progress. Root cause: `GameInput.hold` (client.ts) collapsed
+ * what used to be a `waitSimTime` POLL loop into a single bridge call per
+ * hold (see its own doc comment — deliberately, to cut transport round
+ * trips), so a spec built from many holds and little else can go silent on
+ * stdout between them for minutes at a time.
+ *
+ * `wait-for.ts`'s `maybeHeartbeat` already solves the analogous problem for
+ * the `waitFor`/`waitSimTime` POLL loop, but it is deliberately SIM-TICK
+ * aware (a frozen sim clock must stay heartbeat-silent so that loop's own
+ * ~30s stall guard, `WAIT_FOR_STALL_POLL_LIMIT`, can still diagnose a
+ * genuinely-stuck game rather than a heartbeat papering over it). This is
+ * the companion for `GameClient`'s generic bridge dispatch
+ * (`callBridge`/`callBridgeAsync`), which has no poll loop and no sim tick
+ * to check at all: "wire activity" here just means a bridge call was
+ * actually DISPATCHED — sequential awaits mean a new dispatch can only
+ * happen once the previous one resolved, so a genuinely wedged page (bridge
+ * calls that never resolve at all) still goes — and stays — silent. The
+ * throttle exists only to bound
+ * stdout volume during a burst of fast calls, not to filter out "fake"
+ * activity.
+ */
+export declare const BRIDGE_HEARTBEAT_INTERVAL_MS = 30000;
+/** Mutable-by-replacement bookkeeping a caller threads through successive
+ *  `maybeBridgeHeartbeat` calls — mirrors `wait-for.ts`'s `HeartbeatState`
+ *  shape/style, minus the tick field (no sim-progress condition here). */
+export interface BridgeHeartbeatState {
+    lastEmitWallMs: number;
+}
+/** The liveness line this prints to stdout — greppable, and prefixed
+ *  distinctly from `wait-for.ts`'s `vgai-heartbeat` so the two liveness
+ *  sources are distinguishable in a run's log. */
+export declare function formatBridgeHeartbeatLine(testTitle: string, method: string): string;
+/**
+ * Pure decision, called once per bridge dispatch: should a heartbeat print
+ * now, and what's the updated bookkeeping? Returns the SAME `state` object
+ * (referentially) when nothing should emit, so a caller can cheaply no-op.
+ */
+export declare function maybeBridgeHeartbeat(opts: {
+    nowMs: number;
+    method: string;
+    testTitle: string;
+    state: BridgeHeartbeatState;
+}): {
+    line: string | null;
+    state: BridgeHeartbeatState;
+};

package/dist/game-client/bridge-heartbeat.js

@@ -0,0 +1,46 @@
+/**
+ * run-3 dogfood friction #2 — a legitimately-progressing script built from
+ * many short `game.input.hold()` calls looked WEDGED to anything watching its
+ * stdout for liveness, even though it was making real progress. Root cause: `GameInput.hold` (client.ts) collapsed
+ * what used to be a `waitSimTime` POLL loop into a single bridge call per
+ * hold (see its own doc comment — deliberately, to cut transport round
+ * trips), so a spec built from many holds and little else can go silent on
+ * stdout between them for minutes at a time.
+ *
+ * `wait-for.ts`'s `maybeHeartbeat` already solves the analogous problem for
+ * the `waitFor`/`waitSimTime` POLL loop, but it is deliberately SIM-TICK
+ * aware (a frozen sim clock must stay heartbeat-silent so that loop's own
+ * ~30s stall guard, `WAIT_FOR_STALL_POLL_LIMIT`, can still diagnose a
+ * genuinely-stuck game rather than a heartbeat papering over it). This is
+ * the companion for `GameClient`'s generic bridge dispatch
+ * (`callBridge`/`callBridgeAsync`), which has no poll loop and no sim tick
+ * to check at all: "wire activity" here just means a bridge call was
+ * actually DISPATCHED — sequential awaits mean a new dispatch can only
+ * happen once the previous one resolved, so a genuinely wedged page (bridge
+ * calls that never resolve at all) still goes — and stays — silent. The
+ * throttle exists only to bound
+ * stdout volume during a burst of fast calls, not to filter out "fake"
+ * activity.
+ */
+export const BRIDGE_HEARTBEAT_INTERVAL_MS = 30_000;
+/** The liveness line this prints to stdout — greppable, and prefixed
+ *  distinctly from `wait-for.ts`'s `vgai-heartbeat` so the two liveness
+ *  sources are distinguishable in a run's log. */
+export function formatBridgeHeartbeatLine(testTitle, method) {
+    return `vgai-bridge-heartbeat ${testTitle} method=${method}`;
+}
+/**
+ * Pure decision, called once per bridge dispatch: should a heartbeat print
+ * now, and what's the updated bookkeeping? Returns the SAME `state` object
+ * (referentially) when nothing should emit, so a caller can cheaply no-op.
+ */
+export function maybeBridgeHeartbeat(opts) {
+    const wallElapsed = opts.nowMs - opts.state.lastEmitWallMs;
+    if (wallElapsed >= BRIDGE_HEARTBEAT_INTERVAL_MS) {
+        return {
+            line: formatBridgeHeartbeatLine(opts.testTitle, opts.method),
+            state: { lastEmitWallMs: opts.nowMs },
+        };
+    }
+    return { line: null, state: opts.state };
+}