@ggui-ai/iframe-runtime 0.8.0 → 0.10.0

package/dist/call-tool-unwrap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared 3-tier `CallToolResult` payload unwrap.
+ *
+ * MCP hosts relay `tools/call` results to the iframe in three observed
+ * envelope shapes. The tiers, in the order probed:
+ *
+ *   1. `structuredContent` — spec-canonical hosts.
+ *   2. `content[0].text` parsed as JSON — relay hosts that NORMALIZE
+ *      the CallToolResult down to its text block (claude.ai's live
+ *      behavior on the #471 retest: the enqueue succeeded server-side,
+ *      but the response arrived text-only and classified as a failure,
+ *      so no doorbell rang).
+ *   3. Fields directly on the bare result — looser hosts.
+ *
+ * Shared by the submit-action response classifier (`runtime.ts`'s
+ * `submitActionPayload`) and the bridge-pull rung's `fetchBody`
+ * carrier (`events-polling.ts`'s `buildBridgePolling`), so both reads
+ * agree on which envelope tier carries the payload for a given host
+ * shape.
+ */
+/**
+ * Unwrap the payload record of a relayed `tools/call` result. `result`
+ * is the CallToolResult-level value (i.e. the JSON-RPC envelope's
+ * `result` field, already extracted by the caller).
+ *
+ * Returns `null` when no tier yields an object — the caller treats
+ * that as fallback/unknown.
+ */
+export declare function unwrapCallToolResult(result: unknown): Record<string, unknown> | null;

package/dist/call-tool-unwrap.js

@@ -0,0 +1,56 @@
+/**
+ * Shared 3-tier `CallToolResult` payload unwrap.
+ *
+ * MCP hosts relay `tools/call` results to the iframe in three observed
+ * envelope shapes. The tiers, in the order probed:
+ *
+ *   1. `structuredContent` — spec-canonical hosts.
+ *   2. `content[0].text` parsed as JSON — relay hosts that NORMALIZE
+ *      the CallToolResult down to its text block (claude.ai's live
+ *      behavior on the #471 retest: the enqueue succeeded server-side,
+ *      but the response arrived text-only and classified as a failure,
+ *      so no doorbell rang).
+ *   3. Fields directly on the bare result — looser hosts.
+ *
+ * Shared by the submit-action response classifier (`runtime.ts`'s
+ * `submitActionPayload`) and the bridge-pull rung's `fetchBody`
+ * carrier (`events-polling.ts`'s `buildBridgePolling`), so both reads
+ * agree on which envelope tier carries the payload for a given host
+ * shape.
+ */
+/**
+ * Unwrap the payload record of a relayed `tools/call` result. `result`
+ * is the CallToolResult-level value (i.e. the JSON-RPC envelope's
+ * `result` field, already extracted by the caller).
+ *
+ * Returns `null` when no tier yields an object — the caller treats
+ * that as fallback/unknown.
+ */
+export function unwrapCallToolResult(result) {
+    if (result === null || typeof result !== 'object')
+        return null;
+    const r = result;
+    if (r.structuredContent && typeof r.structuredContent === 'object') {
+        return r.structuredContent;
+    }
+    // Text-block tier BEFORE the bare-result tier when content exists:
+    // a normalized result's own top level carries only `content`, so
+    // probing it for payload fields would always miss anyway — but a
+    // parseable text block is decisive evidence of the real payload.
+    const content = r.content;
+    if (Array.isArray(content) && content.length > 0) {
+        const first = content[0];
+        if (first && first.type === 'text' && typeof first.text === 'string') {
+            try {
+                const parsed = JSON.parse(first.text);
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch {
+                // Not JSON — fall through to the bare-result tier.
+            }
+        }
+    }
+    return r;
+}

package/dist/channels/props-update.d.ts

@@ -45,5 +45,24 @@ export interface PropsUpdateHandlerDeps {
      * the render-frame handler so React updates flow through one path.
      */
     readonly applyRender: (render: GguiSession | GguiSessionSeedInput) => Promise<void>;
+    /**
+     * This mount's OWN history epoch (#483 freeze latch). A
+     * `props_update` frame carrying a HIGHER epoch means an
+     * `ggui_update` minted a newer card and this one is now history —
+     * the handler hands off to {@link onSuperseded} instead of applying.
+     * Absent ⇒ 0 (a fresh render).
+     */
+    readonly getSelfEpoch?: () => number;
+    /**
+     * Invoked (once) when a higher-epoch update supersedes this mount.
+     * The runtime freezes the frame: stop applying, tear down
+     * subscriptions, disable dispatch, show the superseded cue.
+     */
+    readonly onSuperseded?: () => void;
+    /**
+     * True after this mount has frozen. When true the handler drops
+     * every frame — a superseded mount never repaints again.
+     */
+    readonly isSuperseded?: () => boolean;
 }
 export declare function createPropsUpdateHandler(deps: PropsUpdateHandlerDeps): ChannelHandler<PropsUpdatePayload>;

package/dist/channels/props-update.js

@@ -33,9 +33,22 @@ export function createPropsUpdateHandler(deps) {
     return {
         type: 'props_update',
         onMessage: async (payload) => {
-            const { sessionId, props } = payload;
+            // Already frozen (#483): a superseded mount never repaints again.
+            if (deps.isSuperseded?.() === true)
+                return;
+            const { sessionId, props, epoch } = payload;
             if (typeof sessionId !== 'string' || sessionId.length === 0)
                 return;
+            // Freeze latch (#483): a frame stamped with a HIGHER epoch than
+            // this mount's own means a `ggui_update` minted a newer card —
+            // this one is history. Do NOT apply; hand off to the freeze
+            // routine. (`ggui_amend` carries the unchanged head epoch, so
+            // amends to the live head still apply.)
+            const selfEpoch = deps.getSelfEpoch?.() ?? 0;
+            if (typeof epoch === 'number' && epoch > selfEpoch) {
+                deps.onSuperseded?.();
+                return;
+            }
             if (props === null || typeof props !== 'object')
                 return;
             const current = deps.getCurrentGguiSession();

package/dist/compiled-validators.d.ts

@@ -39,17 +39,26 @@ export declare const EMPTY_COMPILED_VALIDATOR_SET: CompiledValidatorSet;
  */
 export declare function loadCompiledValidators(meta: CompiledContractValidators | undefined, warn?: (message: string, detail: unknown) => void): Promise<CompiledValidatorSet>;
 /**
- * #109 content-addressable variant: fetch the validator-bundle URL,
- * dynamic-import the response, then delegate to
- * {@link loadCompiledValidators}. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
+ * #109 content-addressable variant: fetch the validator-bundle URL via
+ * ONE dynamic import. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
  * when `url` is undefined OR the fetch/import fails — sidecar
  * semantics, the server-side `assertActionContract` gate remains
  * authoritative on validator absence.
  *
- * Response shape: an ES module whose `default` export is a
- * {@link CompiledContractValidators} object (produced server-side by
- * `bundleCompiledValidatorsAsModule`). `Cache-Control: immutable` so
- * repeat renders with the same contract hit browser cache with no
+ * Response shape (v2 executable format, ggui#522 slice 2): an ES
+ * module whose `default` export carries the validate FUNCTIONS
+ * themselves (produced server-side by
+ * `bundleValidatorExprsAsExecutableModule`) — the single https import
+ * is the whole load, governed by `script-src` origins alone. No
+ * per-validator `blob:` import remains on this path, which is what
+ * lets a strict-CSP embedder (no `blob:`, no `data:`, no
+ * `'unsafe-eval'`) run client-side outbound validation at all.
+ *
+ * A default export whose leaves are not functions (the retired v1
+ * format carried module SOURCES as strings — reachable only through a
+ * stale CDN copy under a pre-salt URL, which no current slice mints)
+ * degrades to the empty set with a warning. `Cache-Control: immutable`
+ * so repeat renders with the same contract hit browser cache with no
  * round-trip.
  */
 export declare function loadCompiledValidatorsFromUrl(url: string | undefined, warn?: (message: string, detail: unknown) => void): Promise<CompiledValidatorSet>;

package/dist/compiled-validators.js

@@ -73,17 +73,26 @@ export async function loadCompiledValidators(meta, warn) {
     };
 }
 /**
- * #109 content-addressable variant: fetch the validator-bundle URL,
- * dynamic-import the response, then delegate to
- * {@link loadCompiledValidators}. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
+ * #109 content-addressable variant: fetch the validator-bundle URL via
+ * ONE dynamic import. Returns {@link EMPTY_COMPILED_VALIDATOR_SET}
  * when `url` is undefined OR the fetch/import fails — sidecar
  * semantics, the server-side `assertActionContract` gate remains
  * authoritative on validator absence.
  *
- * Response shape: an ES module whose `default` export is a
- * {@link CompiledContractValidators} object (produced server-side by
- * `bundleCompiledValidatorsAsModule`). `Cache-Control: immutable` so
- * repeat renders with the same contract hit browser cache with no
+ * Response shape (v2 executable format, ggui#522 slice 2): an ES
+ * module whose `default` export carries the validate FUNCTIONS
+ * themselves (produced server-side by
+ * `bundleValidatorExprsAsExecutableModule`) — the single https import
+ * is the whole load, governed by `script-src` origins alone. No
+ * per-validator `blob:` import remains on this path, which is what
+ * lets a strict-CSP embedder (no `blob:`, no `data:`, no
+ * `'unsafe-eval'`) run client-side outbound validation at all.
+ *
+ * A default export whose leaves are not functions (the retired v1
+ * format carried module SOURCES as strings — reachable only through a
+ * stale CDN copy under a pre-salt URL, which no current slice mints)
+ * degrades to the empty set with a warning. `Cache-Control: immutable`
+ * so repeat renders with the same contract hit browser cache with no
  * round-trip.
  */
 export async function loadCompiledValidatorsFromUrl(url, warn) {
@@ -96,7 +105,31 @@ export async function loadCompiledValidatorsFromUrl(url, warn) {
             warn?.('[ggui:validators] contract bundle: default export is not an object', compiled);
             return EMPTY_COMPILED_VALIDATOR_SET;
         }
-        return loadCompiledValidators(compiled, warn);
+        const groups = compiled;
+        const pickGroup = (group, kind) => {
+            const map = new Map();
+            if (group === undefined)
+                return map;
+            for (const [name, fn] of Object.entries(group)) {
+                if (isValidateFunction(fn)) {
+                    map.set(name, fn);
+                }
+                else {
+                    warn?.(`[ggui:validators] ${kind}.${name}: bundle entry is not a function (stale v1-format bundle?)`, typeof fn);
+                }
+            }
+            return map;
+        };
+        const props = isValidateFunction(groups.props) ? groups.props : undefined;
+        if (groups.props !== undefined && props === undefined) {
+            warn?.('[ggui:validators] props: bundle entry is not a function (stale v1-format bundle?)', typeof groups.props);
+        }
+        return {
+            ...(props !== undefined ? { props } : {}),
+            actions: pickGroup(groups.actions, 'action'),
+            streams: pickGroup(groups.streams, 'stream'),
+            context: pickGroup(groups.context, 'context'),
+        };
     }
     catch (err) {
         warn?.(`[ggui:validators] contract bundle: failed to load ${url}`, err);

package/dist/events-polling.d.ts

@@ -22,6 +22,15 @@
  *     only sees the body, so we emit a synthetic `error` frame for the
  *     registry to surface upward.
  *
+ * # Bridge-pull carrier (terminal rung)
+ *
+ * `buildBridgePolling` composes the SAME algorithm on the `fetchBody`
+ * carrier: a CSP-jailed MCP-Apps iframe with no network path pulls the
+ * same ledger by issuing `ggui_runtime_pull` `tools/call`s over the
+ * host's postMessage bridge. One parse core
+ * (`createEventsSnapshotParser`), two carriers — the tool's output is
+ * byte-parity with the `/events` route by contract.
+ *
  * # Anthropic first-mount race fix
  *
  * Iframes mounted inside the Anthropic SDK lose `__GGUI_META__` because
@@ -39,6 +48,39 @@
  * fallback, and live updates.
  */
 import type { RegistryPollingOptions } from '@ggui-ai/live-channel';
+import type { GguiRuntimePullInput } from '@ggui-ai/protocol';
+/**
+ * Shared, monotonic event-ledger cursor for the failover ladder.
+ *
+ * The SSE rung advances it via `RegistrySseOptions.onSequence` (the
+ * SSE `id:` field IS the ledger sequence); the polling descriptor
+ * reads it per tick — so an SSE→polling demotion resumes from the
+ * last streamed event instead of re-replaying from the boot snapshot.
+ */
+export interface SequenceCursor {
+    get(): number;
+    /**
+     * Monotonic max — no-op when `seq <= current`, guaranteeing a stale
+     * rung can never rewind progress another rung already made. Normal
+     * delivery path (SSE `id:`, polling `lastSequence`).
+     */
+    advance(seq: number): void;
+    /**
+     * Unconditional server-truth override — the REPLAY_HORIZON_PASSED
+     * escape hatch, and ONLY that. When the server declares the cursor
+     * outside the replayable window it reports its actual high-water
+     * mark, which can be BELOW the client cursor (a re-minted or reset
+     * session whose ledger restarted). A monotonic `advance` would no-op
+     * there and every subsequent tick would re-ask ahead of the horizon —
+     * a permanent error loop. `reset` adopts the server's number so the
+     * next tick lands inside the window and the ladder self-heals.
+     */
+    reset(seq: number): void;
+}
+/**
+ * Create a {@link SequenceCursor} seeded at `seed` (default `0`).
+ */
+export declare function createSequenceCursor(seed?: number): SequenceCursor;
 export interface BuildEventsPollingOptions {
     /**
      * Base URL the polling tick reads from. The composer appends
@@ -53,7 +95,9 @@ export interface BuildEventsPollingOptions {
      * Optional cursor seed — initial value of `sinceSequence` on the
      * first tick. Typically threaded from `render.lastSequence` so the
      * cold-mount-after-WS-fail path picks up where the snapshot left
-     * off. Defaults to `0` (replay everything still retained).
+     * off. Defaults to `0` (replay everything still retained). Ignored
+     * when {@link cursor} is supplied — the shared cursor carries its
+     * own seed.
      */
     readonly initialSinceSequence?: number;
     /**
@@ -67,6 +111,14 @@ export interface BuildEventsPollingOptions {
      * single tick to keep latency bounded.
      */
     readonly limit?: number;
+    /**
+     * Shared ladder cursor (WS → SSE → polling). When supplied, the
+     * descriptor reads/advances it instead of a private closure cursor,
+     * so SSE deliveries observed via `RegistrySseOptions.onSequence`
+     * move the polling replay point forward. Absent → private internal
+     * cursor seeded from {@link initialSinceSequence} (today's behavior).
+     */
+    readonly cursor?: SequenceCursor;
 }
 /**
  * Build a {@link RegistryPollingOptions} descriptor that reads
@@ -93,3 +145,73 @@ export interface BuildEventsPollingOptions {
  * pulls the live cursor and composes the URL anew.
  */
 export declare function buildEventsPolling(opts: BuildEventsPollingOptions): RegistryPollingOptions;
+export interface BuildBridgePollingOptions {
+    /**
+     * Host `tools/call` dispatcher the tick pulls through. The runtime
+     * binds this to `app.callServerTool` on the connected MCP-Apps App
+     * handle — in a CSP-jailed host the postMessage bridge is the only
+     * carrier the iframe has, which is why this rung exists. The
+     * resolved value is the raw `CallToolResult`; the tick unwraps it
+     * via the shared 3-tier {@link unwrapCallToolResult} (the same
+     * unwrap submit-action responses use, so host-normalization
+     * quirks — claude.ai's text-only collapse included — are handled
+     * identically on both paths).
+     */
+    readonly callTool: (name: 'ggui_runtime_pull', args: GguiRuntimePullInput) => Promise<unknown>;
+    /** Active render id — threaded verbatim as the tool's `sessionId`. */
+    readonly sessionId: string;
+    /**
+     * Shared ladder cursor (WS → SSE → polling → bridge). REQUIRED —
+     * unlike {@link BuildEventsPollingOptions.cursor} there is no
+     * private-cursor fallback, because the bridge rung never exists
+     * alone: the runtime always creates the ladder cursor when it
+     * composes this rung, and a demotion into the bridge must resume
+     * from whatever the rungs above already delivered.
+     */
+    readonly cursor: SequenceCursor;
+    /**
+     * Failure-pacing interval. Defaults to 3000ms. In subscription mode
+     * the chain paces via `nextDelayMs`; this value only paces retries
+     * after FAILED ticks (transport contract).
+     */
+    readonly intervalMs?: number;
+    /**
+     * Server-side hold per subscription-mode pull, in seconds. Defaults
+     * to 20 (under ggui_consume's proven 25s host tolerance). `0`
+     * disables holding entirely — every pull returns immediately and
+     * pacing degrades to {@link idleIntervalMs}.
+     */
+    readonly holdSeconds?: number;
+    /**
+     * Consecutive empty holds before demoting subscription → idle
+     * polling. Defaults to 3. Any delivered event re-promotes.
+     */
+    readonly demoteAfterEmpties?: number;
+    /**
+     * Idle-mode pull cadence. Defaults to 15000ms.
+     */
+    readonly idleIntervalMs?: number;
+    /**
+     * Optional per-page event cap, forwarded as the tool's `limit`
+     * argument only when set. Absent → the key is omitted and the
+     * server default applies.
+     */
+    readonly limit?: number;
+}
+/**
+ * Build the bridge-pull rung of the failover ladder — the SAME
+ * polling algorithm as {@link buildEventsPolling} on a different
+ * carrier: instead of an HTTP `url`, the descriptor supplies a
+ * `fetchBody` that pulls the event ledger through the host's
+ * `tools/call` postMessage bridge (`ggui_runtime_pull`). Terminal
+ * rung: the registry never arms a failure budget on it.
+ *
+ * Per tick: `callTool('ggui_runtime_pull', {sessionId, sinceSequence:
+ * <cursor>, limit?})` → unwrap the CallToolResult via the shared
+ * 3-tier {@link unwrapCallToolResult} → the unwrapped body feeds the
+ * SAME parse core as the HTTP rung (`EventsResponse` dispatch,
+ * `lastSequence` advance, REPLAY_HORIZON_PASSED reset — the tool's
+ * output is byte-parity with `GET /api/sessions/:sessionId/events` by
+ * contract).
+ */
+export declare function buildBridgePolling(opts: BuildBridgePollingOptions): RegistryPollingOptions;

package/dist/events-polling.js

@@ -1,5 +1,29 @@
+import { unwrapCallToolResult } from './call-tool-unwrap.js';
 const DEFAULT_EVENTS_POLL_INTERVAL_MS = 2000;
 const DEFAULT_EVENTS_PAGE_LIMIT = 100;
+const DEFAULT_BRIDGE_PULL_INTERVAL_MS = 3000;
+// Subscription-mode defaults (transport-ladder ruling 20). The hold
+// stays under ggui_consume's proven 25s host tolerance; K=3 empty
+// holds (~1 min of silence) demotes to sparse idle pulls.
+const DEFAULT_BRIDGE_HOLD_SECONDS = 20;
+const DEFAULT_BRIDGE_DEMOTE_AFTER_EMPTIES = 3;
+const DEFAULT_BRIDGE_IDLE_INTERVAL_MS = 15_000;
+/**
+ * Create a {@link SequenceCursor} seeded at `seed` (default `0`).
+ */
+export function createSequenceCursor(seed = 0) {
+    let current = seed;
+    return {
+        get: () => current,
+        advance: (seq) => {
+            if (seq > current)
+                current = seq;
+        },
+        reset: (seq) => {
+            current = seq;
+        },
+    };
+}
 /**
  * Compose the per-tick URL with `&sinceSequence=N&limit=M` appended.
  * The base URL may or may not already carry a query string; we pick
@@ -68,7 +92,10 @@ function isGguiSessionEvent(value) {
  * pulls the live cursor and composes the URL anew.
  */
 export function buildEventsPolling(opts) {
-    let cursor = opts.initialSinceSequence ?? 0;
+    // Shared ladder cursor when supplied; else a private cursor seeded
+    // from `initialSinceSequence` — behaviorally identical to the old
+    // closure `let cursor`, modulo monotonicity (advance() never rewinds).
+    const cur = opts.cursor ?? createSequenceCursor(opts.initialSinceSequence ?? 0);
     const limit = opts.limit ?? DEFAULT_EVENTS_PAGE_LIMIT;
     const intervalMs = opts.intervalMs ?? DEFAULT_EVENTS_POLL_INTERVAL_MS;
     // Each `url` access recomputes from the current cursor. The
@@ -76,7 +103,7 @@ export function buildEventsPolling(opts) {
     const descriptor = Object.create(null);
     Object.defineProperty(descriptor, 'url', {
         enumerable: true,
-        get: () => composeTickUrl(opts.baseUrl, cursor, limit),
+        get: () => composeTickUrl(opts.baseUrl, cur.get(), limit),
     });
     Object.defineProperty(descriptor, 'intervalMs', {
         enumerable: true,
@@ -84,60 +111,161 @@ export function buildEventsPolling(opts) {
     });
     Object.defineProperty(descriptor, 'parseSnapshot', {
         enumerable: true,
-        value: (body) => {
-            // 410 case manifests as a body that doesn't match the
-            // EventsResponse shape (`{reason: 'REPLAY_HORIZON_PASSED',
-            // currentSequence}`). Surface a synthetic `error` frame so the
-            // registry's error handler can fire the re-mount signal.
+        value: createEventsSnapshotParser(cur),
+    });
+    return descriptor;
+}
+/**
+ * The ONE per-tick `EventsResponse` parse core behind BOTH ledger-pull
+ * carriers — HTTP polling ({@link buildEventsPolling}) and bridge-pull
+ * ({@link buildBridgePolling}). Byte-parity between `GET
+ * /api/sessions/:sessionId/events` and `ggui_runtime_pull` output is
+ * contractual precisely so this single parser handles both.
+ *
+ * Reads the `EventsResponse` envelope, dispatches each event by
+ * `event.type` to the registered channel handler, advances the shared
+ * cursor to `lastSequence`, and folds the REPLAY_HORIZON_PASSED
+ * escape hatch through `cursor.reset()` + a synthetic `error` frame.
+ */
+function createEventsSnapshotParser(cur) {
+    return (body) => {
+        // 410 case manifests as a body that doesn't match the
+        // EventsResponse shape (`{reason: 'REPLAY_HORIZON_PASSED',
+        // currentSequence}`). Surface a synthetic `error` frame so the
+        // registry's error handler can fire the re-mount signal.
+        if (body !== null &&
+            typeof body === 'object' &&
+            body.reason === 'REPLAY_HORIZON_PASSED') {
+            const cs = body.currentSequence;
+            const currentSequence = typeof cs === 'number' ? cs : 0;
+            // Advance to the server's high-water mark; next tick starts
+            // fresh from there (monotonic — inside the replayable-range
+            // contract the high-water mark is >= the cursor, and a shared
+            // ladder cursor must never rewind another rung's progress).
+            // Consumers handle the re-mount via the error channel.
+            // Server-truth override, NOT advance(): the horizon error can
+            // report a high-water mark BELOW this cursor (re-minted/reset
+            // session ledger) — monotonic advance would no-op and every
+            // subsequent tick would re-ask ahead of the horizon forever.
+            cur.reset(currentSequence);
+            const errorFrame = {
+                type: 'error',
+                payload: {
+                    code: 'REPLAY_HORIZON_PASSED',
+                    message: `events polling cursor outside replayable range; reset to ${currentSequence}`,
+                    details: { currentSequence },
+                },
+            };
+            return { error: errorFrame };
+        }
+        if (!isEventsResponse(body))
+            return null;
+        // Advance cursor even on empty pages — the server's high-water
+        // mark moves with /state reads too.
+        cur.advance(body.lastSequence);
+        if (body.events.length === 0) {
+            // Nothing to dispatch; the empty object signals "snapshot
+            // parsed but no handlers matched today's keys" (distinct from
+            // `null` = no change).
+            return {};
+        }
+        // Group events by type. The registry-level polling transport
+        // calls one handler per type; if multiple events share a type
+        // we'd lose deliveries. Today's wire frame types
+        // (render/props_update) are typically distinct per tick at the
+        // expected 2s cadence, but the protocol allows multiple of the
+        // same type. Honest workaround: dispatch the LAST event of each
+        // type and rely on the consumer's idempotency. Future R8: extend
+        // the dispatch shape to a list per type.
+        const frames = {};
+        for (const event of body.events) {
+            if (!isGguiSessionEvent(event))
+                continue;
+            // Two namespaces meet here, and THIS is the single translation
+            // point: the ledger speaks the canonical event taxonomy
+            // ('ui.updated', 'user.submitted', …) while the registry's
+            // handler map speaks live-channel FRAME types ('props_update',
+            // …). `ggui_update` appends 'ui.updated' with the exact
+            // `{sessionId, props}` payload the props_update handler
+            // expects — map the name so pull rungs repaint through the
+            // same handler the WS/SSE push planes use.
+            const frameType = event.type === 'ui.updated' ? 'props_update' : event.type;
+            frames[frameType] = {
+                type: frameType,
+                payload: event.data,
+            };
+        }
+        return frames;
+    };
+}
+/**
+ * Build the bridge-pull rung of the failover ladder — the SAME
+ * polling algorithm as {@link buildEventsPolling} on a different
+ * carrier: instead of an HTTP `url`, the descriptor supplies a
+ * `fetchBody` that pulls the event ledger through the host's
+ * `tools/call` postMessage bridge (`ggui_runtime_pull`). Terminal
+ * rung: the registry never arms a failure budget on it.
+ *
+ * Per tick: `callTool('ggui_runtime_pull', {sessionId, sinceSequence:
+ * <cursor>, limit?})` → unwrap the CallToolResult via the shared
+ * 3-tier {@link unwrapCallToolResult} → the unwrapped body feeds the
+ * SAME parse core as the HTTP rung (`EventsResponse` dispatch,
+ * `lastSequence` advance, REPLAY_HORIZON_PASSED reset — the tool's
+ * output is byte-parity with `GET /api/sessions/:sessionId/events` by
+ * contract).
+ */
+export function buildBridgePolling(opts) {
+    const { callTool, sessionId, cursor } = opts;
+    const limit = opts.limit;
+    const intervalMs = opts.intervalMs ?? DEFAULT_BRIDGE_PULL_INTERVAL_MS;
+    const holdSeconds = opts.holdSeconds ?? DEFAULT_BRIDGE_HOLD_SECONDS;
+    const demoteAfterEmpties = opts.demoteAfterEmpties ?? DEFAULT_BRIDGE_DEMOTE_AFTER_EMPTIES;
+    const idleIntervalMs = opts.idleIntervalMs ?? DEFAULT_BRIDGE_IDLE_INTERVAL_MS;
+    // Subscription-mode state (transport-ladder ruling 20). Two modes,
+    // one counter:
+    //   - SUBSCRIPTION (hot): each pull carries `wait` — the server
+    //     holds the call until an event lands or the hold times out —
+    //     and the next pull fires IMMEDIATELY on return. Back-to-back
+    //     held single-shots emulate push: event→screen ≈ one relay RTT.
+    //   - POLLING (idle): after `demoteAfterEmpties` consecutive empty
+    //     holds the card is presumed quiet; drop to sparse un-held
+    //     pulls every `idleIntervalMs` so a dormant card doesn't pin
+    //     the host's relay open forever.
+    // Any delivered event promotes straight back to subscription mode.
+    let consecutiveEmpties = 0;
+    const hot = () => consecutiveEmpties < demoteAfterEmpties;
+    return {
+        intervalMs,
+        fetchBody: async () => {
+            const result = await callTool('ggui_runtime_pull', {
+                sessionId,
+                sinceSequence: cursor.get(),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(hot() ? { wait: holdSeconds } : {}),
+            });
+            return unwrapCallToolResult(result);
+        },
+        parseSnapshot: createEventsSnapshotParser(cursor),
+        nextDelayMs: (body) => {
+            if (isEventsResponse(body)) {
+                if (body.events.length > 0) {
+                    consecutiveEmpties = 0;
+                    return 0;
+                }
+                consecutiveEmpties += 1;
+                return hot() ? 0 : idleIntervalMs;
+            }
             if (body !== null &&
                 typeof body === 'object' &&
                 body.reason === 'REPLAY_HORIZON_PASSED') {
-                const cs = body.currentSequence;
-                const currentSequence = typeof cs === 'number' ? cs : 0;
-                // Reset cursor to the server's high-water mark; next tick
-                // starts fresh from there. Consumers handle the re-mount via
-                // the error channel.
-                cursor = currentSequence;
-                const errorFrame = {
-                    type: 'error',
-                    payload: {
-                        code: 'REPLAY_HORIZON_PASSED',
-                        message: `events polling cursor outside replayable range; reset to ${currentSequence}`,
-                        details: { currentSequence },
-                    },
-                };
-                return { error: errorFrame };
-            }
-            if (!isEventsResponse(body))
-                return null;
-            // Advance cursor even on empty pages — the server's high-water
-            // mark moves with /state reads too.
-            cursor = body.lastSequence;
-            if (body.events.length === 0) {
-                // Nothing to dispatch; the empty object signals "snapshot
-                // parsed but no handlers matched today's keys" (distinct from
-                // `null` = no change).
-                return {};
-            }
-            // Group events by type. The registry-level polling transport
-            // calls one handler per type; if multiple events share a type
-            // we'd lose deliveries. Today's wire frame types
-            // (render/props_update) are typically distinct per tick at the
-            // expected 2s cadence, but the protocol allows multiple of the
-            // same type. Honest workaround: dispatch the LAST event of each
-            // type and rely on the consumer's idempotency. Future R8: extend
-            // the dispatch shape to a list per type.
-            const frames = {};
-            for (const event of body.events) {
-                if (!isGguiSessionEvent(event))
-                    continue;
-                frames[event.type] = {
-                    type: event.type,
-                    payload: event.data,
-                };
+                // Cursor just self-healed to the server's high-water mark
+                // (parseSnapshot reset it) — one immediate re-pull lands
+                // inside the window.
+                return 0;
             }
-            return frames;
+            // Unrecognized body — pace like idle rather than hot-looping on
+            // garbage.
+            return idleIntervalMs;
         },
-    });
-    return descriptor;
+    };
 }