@ggui-ai/iframe-runtime 0.8.0 → 0.10.0

package/dist/runtime.js

@@ -1,5 +1,34 @@
-import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
-import { parseMetaFromGlobal, parseMetaFromToolResult, } from './meta-parse.js';
+/**
+ * `@ggui-ai/iframe-runtime` iframe runtime entry.
+ *
+ * This is the file esbuild bundles into `dist/iframe-runtime.js`. The
+ * thin-shell HTML loads it via `<script type="module" src=".../iframe-runtime.js">`;
+ * on import the side-effects below take over: build a status DOM,
+ * postMessage `ui/initialize` to the parent, parse the bootstrap, open
+ * the WebSocket, run the version handshake, and mount the render
+ * placeholder.
+ *
+ * Boot sequence:
+ *   - Boot from the `_meta["ai.ggui/render"]` slice received via
+ *     `ui/initialize`.
+ *   - Open the WebSocket, run the subscribe handshake.
+ *   - Mount the render — either a structural placeholder or, when
+ *     the renderer hooks are wired, a React mount of `componentCode`.
+ *
+ * The runtime advertises its build version via a post-`ui/initialize`
+ * notification (`ggui:renderer-ready`).
+ *
+ * Failure surfacing: every parse / handshake failure goes to two
+ * places — (1) the in-iframe status line (operator-visible) and
+ * (2) a parent-bound `postMessage({type:'ggui:bootstrap-failed', ...})`.
+ * The post-message envelope is consumed by the `<McpAppIframe>` host
+ * wrapper, which routes it to the host's `onError` callback.
+ */
+// FIRST import on purpose — declares zod jitless before any
+// schema-defining dependency initializes (see zod-jitless.ts).
+import './zod-jitless.js';
+import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
@@ -7,9 +36,11 @@ import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
 import { RelayIncapableError } from './relay-incapability.js';
 import { ChannelRegistry } from '@ggui-ai/live-channel';
+import { createTelemetrySink, } from './runtime-telemetry.js';
 import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createPropsUpdateHandler, createRenderHandler, } from './channels/index.js';
 import { connectViaRegistry, } from './registry-subscribe.js';
-import { buildEventsPolling } from './events-polling.js';
+import { buildBridgePolling, buildEventsPolling, createSequenceCursor, } from './events-polling.js';
+import { unwrapCallToolResult } from './call-tool-unwrap.js';
 import { ensureStatusDom, setStatus, setConnectedStatus, } from './status-dom.js';
 import { mergeReservedValidators, setActiveValidatorSet, } from './validation.js';
 import { loadCompiledValidatorsFromUrl } from './compiled-validators.js';
@@ -129,6 +160,32 @@ export function setCurrentApp(app) {
 function getCurrentApp() {
     return currentApp;
 }
+/**
+ * The host's announced color mode, read from the connected App's
+ * pre-merged hostContext (`ui/initialize` result, kept current by the
+ * App across `host-context-changed`). `undefined` when no App is
+ * connected, the host sent no `theme`, or it sent something outside
+ * the spec's `'light' | 'dark'` literals (dropped, never guessed —
+ * the same tolerant posture as `projectHostContext`).
+ *
+ * This is the INPUT leg of host-theme adaptation
+ * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * `hostContext.theme` alone reaches only `data-theme` +
+ * `color-scheme` via `applyDocumentTheme` — nothing in the token
+ * pipeline keys off it, so a dark host painted the light ladder
+ * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
+ * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
+ * every operator layer (live provider > per-render override > app
+ * default > server default) still wins by being stamped; the host
+ * fills the gap where no operator had an opinion.
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export function hostAnnouncedThemeMode() {
+    const theme = currentApp?.getHostContext()?.theme;
+    return theme === 'light' || theme === 'dark' ? theme : undefined;
+}
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -312,7 +369,16 @@ export async function bootSequence(opts) {
             parsed = inline;
         }
         else {
-            const fromToolResult = await toolResultPromise;
+            // Tier 1.5 — the read-plane door (ggui#537). A pre-boot tool
+            // result named the view but carried no material; now that the
+            // App is connected, resolve the locator through the host's
+            // `resources/read` proxy. One round trip, ahead of the Tier 2
+            // wait; a miss falls through to Tier 2 unchanged (its listener
+            // is already armed and resolves locator-only arrivals too).
+            const viaDoor = opts.preResolvedLocator !== undefined
+                ? await resolveMetaViaReadDoor(app, opts.preResolvedLocator)
+                : null;
+            const fromToolResult = viaDoor ?? (await toolResultPromise);
             if (fromToolResult !== null) {
                 parsed = { ok: true, meta: fromToolResult };
             }
@@ -386,16 +452,24 @@ export async function bootSequence(opts) {
     // In-iframe UI-feedback affordance (ggui#244) — mounted adjacent to
     // the session root, gated inside the helper on `window.parent !==
     // window` (top-level `/r/<shortCode>` tabs have no `ggui:observe`
-    // egress, so they get NO affordance). Interaction emits a
-    // `ui-feedback` ObservabilityEvent through the boot path's emitter;
-    // when no emitter was injected the postMessage-to-parent default
-    // still gives the mounted affordance a live sink (the gate already
-    // proved a parent exists). Fire-and-forget: chrome never blocks or
-    // fails the boot.
-    void mountUiFeedbackChrome(doc, {
-        emit: onObserve ?? postObservabilityToParent,
-        sessionId: meta.sessionId,
-    });
+    // egress, so they get NO affordance) AND here on a LIVE SINK: an
+    // injected `onObserve` emitter, or a first-party embed host — the
+    // only parent that consumes the `ggui:observe` envelope
+    // (mcp-app-iframe-host answers `ui/initialize` with exactly this
+    // hostInfo name). Third-party MCP-Apps hosts (claude.ai, ChatGPT,
+    // Claude Desktop) drop the envelope on the floor, so rendering the
+    // affordance there is a dead control — the first #471 claude.ai
+    // retest surfaced it as unstyled clutter that could never deliver
+    // feedback anywhere. Fire-and-forget: chrome never blocks or fails
+    // the boot.
+    const feedbackSinkLive = onObserve !== undefined ||
+        app.getHostVersion()?.name === 'ggui-iframe-runtime-embed-host';
+    if (feedbackSinkLive) {
+        void mountUiFeedbackChrome(doc, {
+            emit: onObserve ?? postObservabilityToParent,
+            sessionId: meta.sessionId,
+        });
+    }
     setStatus(refs, `Connecting to ${meta.sessionId}…`, 'connecting');
     // Boot-without-renderer path: we still need a ChannelRegistry to
     // receive frames, because the registry is the only dispatch
@@ -471,6 +545,27 @@ export async function bootSequence(opts) {
         meta.wsUrl.length > 0 &&
         typeof meta.wsToken === 'string' &&
         meta.wsToken.length > 0;
+    // Transport-telemetry sink — the iframe's self-report channel (see
+    // runtime-telemetry.ts). Created for EVERY boot with an App bridge;
+    // the first batch carries the boot-path decision so operators can
+    // see which ladder (if any) this mount composed, even on hosts
+    // whose console and network are unreachable.
+    const telemetryApp = getCurrentApp();
+    const telemetry = telemetryApp !== null
+        ? createTelemetrySink({
+            sessionId: meta.sessionId,
+            callTool: (args) => telemetryApp.callServerTool(args),
+        })
+        : null;
+    currentTelemetrySink = telemetry;
+    // Fresh boot ⇒ not superseded (matters only for test re-runs that
+    // reuse the module; a real iframe boots once).
+    mountSuperseded = false;
+    telemetry?.record('boot.path', JSON.stringify({
+        hasStaticContent,
+        hasLiveTrio,
+        bridgeCapable: telemetryApp !== null,
+    }));
     // ── Static seed mount — zero-round-trip paint, no WS required. ──────
     // The ONLY mount path for spec-compliant MCP-Apps hosts that expose no
     // ggui live channel (claude.ai / ChatGPT / Claude Desktop), AND the
@@ -511,17 +606,28 @@ export async function bootSequence(opts) {
             emitCodeReadyOnce();
         }
     }
-    // ── No live channel → static-only host. ────────────────────────────
+    // ── No live channel → static-only host (unless bridge-capable). ─────
     // The static seed already painted (or there was nothing to paint).
     // A bootstrap with neither static content nor a live trio is a
     // misconfiguration — surface a typed boot failure.
-    if (!hasLiveTrio) {
-        if (mountedRender === null) {
-            const message = 'bootstrap carries neither static content (codeUrl/codeB64/kind) nor a live trio (wsUrl/wsToken)';
-            setStatus(refs, message, 'error');
-            emitBootFailure('MISSING_META_GGUI_BOOTSTRAP', message);
-            return { ok: false, mountedRender };
-        }
+    //
+    // #471 round-6 live finding: when the host exposes an App bridge
+    // (tools/call postMessage — claude.ai, every MCP Apps host), a
+    // trio-less static mount must NOT stop here — the bridge-pull
+    // terminal rung is exactly its subscription. Fall through to the
+    // subscribe below, which binds trio-less (the registry starts the
+    // ladder at its tail). Gating the terminal rung behind the WS
+    // trio's presence disabled it on precisely the host class it was
+    // built for.
+    const staticOnlyNoBridge = !hasLiveTrio && getCurrentApp() === null;
+    if (!hasLiveTrio && mountedRender === null) {
+        const message = 'bootstrap carries neither static content (codeUrl/codeB64/kind) nor a live trio (wsUrl/wsToken)';
+        setStatus(refs, message, 'error');
+        emitBootFailure('MISSING_META_GGUI_BOOTSTRAP', message);
+        return { ok: false, mountedRender };
+    }
+    if (staticOnlyNoBridge) {
+        telemetry?.record('boot.static_only_no_bridge');
         // Host-context wiring for the no-WS static mount (claude.ai / ChatGPT
         // / Claude Desktop). The INITIAL host theme/style/fonts were already
         // applied at boot (applyHostContextStyling, above); attach the
@@ -543,12 +649,42 @@ export async function bootSequence(opts) {
         return { ok: true, mountedRender };
     }
     // ── Live-channel subscribe (conditional enhancement). ──────────────
+    // Failover-ladder rung URLs (WS → SSE → polling → bridge-pull),
+    // hoisted so the spreads below stay exact-optional-clean without
+    // non-null assertions. `sseUrl` is the server-stamped wsToken-gated
+    // `/api/sessions/<id>/stream` URL; SSE `id:` = ledger sequence = the
+    // SAME cursor model as the WS `sinceSequence` replay and polling
+    // ticks — switching rungs does not lose events.
+    const sseUrl = typeof meta.sseUrl === 'string' && meta.sseUrl.length > 0
+        ? meta.sseUrl
+        : undefined;
+    const pollingBaseUrl = typeof meta.pollingUrl === 'string' && meta.pollingUrl.length > 0
+        ? meta.pollingUrl
+        : undefined;
+    // One shared cursor for the whole ladder — SSE deliveries advance it
+    // (via onSequence), the polling + bridge descriptors read it per
+    // tick, so a demotion down the ladder resumes from the last
+    // delivered event instead of re-replaying from the boot snapshot.
+    // Created when ANY fallback rung exists — including the bridge-pull
+    // rung, whose only precondition is a connected App handle (the
+    // universal floor: a CSP-jailed host stamps no sseUrl/pollingUrl,
+    // yet its `tools/call` postMessage bridge still reaches the ledger).
+    const bridgeApp = getCurrentApp();
+    const ladderCursor = sseUrl !== undefined || pollingBaseUrl !== undefined || bridgeApp !== null
+        ? createSequenceCursor(meta.lastSequence ?? 0)
+        : undefined;
     let handle;
     try {
         handle = await connectFn({
             meta,
             registry: activeRegistry,
+            // Live-channel diagnostics tap — every channel_* event the
+            // transports emit (failover swaps, polling budget exhaustion,
+            // SSE lifecycle) lands in the telemetry buffer. Without this the
+            // ladder's story on sandboxed hosts is unobservable.
+            ...(telemetry !== null ? { logger: telemetry.channelLogger } : {}),
             onStatusChange: (status) => {
+                telemetry?.record(`status.${status}`);
                 setStatus(refs, status === 'connected' ? 'Connected.' : `Connection ${status}…`, status);
                 // Propagate WS status to the per-channel transport router so
                 // it can flip WS-bound channels into polling
@@ -573,21 +709,48 @@ export async function bootSequence(opts) {
             onResubscribeAck: (ack) => {
                 void applyAck(ack);
             },
-            // R7 — registry-level events-polling fallback. Composed once at
-            // bind time from `meta.pollingUrl` (server-stamped wsToken-
-            // gated /api/sessions/<id>/events URL) + `meta.lastSequence`
-            // (cursor seed). FailoverHandle uses this when WS reaches
-            // 'failed'; absent → no polling fallback (WS-only mode).
+            // Failover-ladder fallback rungs (WS → SSE → polling →
+            // bridge-pull), composed once at bind time from the
+            // server-stamped wsToken-gated URLs + `meta.lastSequence`
+            // (shared cursor seed). FailoverHandle descends a rung on each
+            // 'failed'; the bridge rung is terminal (never emits 'failed').
             //
             // Same cursor model as the WS subscribe `sinceSequence` replay
             // path — switching transports does not lose events.
-            ...(typeof meta.pollingUrl === 'string' && meta.pollingUrl.length > 0
+            ...(sseUrl !== undefined && ladderCursor !== undefined
+                ? {
+                    sse: {
+                        url: sseUrl,
+                        initialSinceSequence: ladderCursor.get(),
+                        onSequence: (seq) => {
+                            ladderCursor.advance(seq);
+                        },
+                    },
+                }
+                : {}),
+            ...(pollingBaseUrl !== undefined && ladderCursor !== undefined
                 ? {
                     polling: buildEventsPolling({
-                        baseUrl: meta.pollingUrl,
-                        ...(meta.lastSequence !== undefined
-                            ? { initialSinceSequence: meta.lastSequence }
-                            : {}),
+                        baseUrl: pollingBaseUrl,
+                        cursor: ladderCursor,
+                    }),
+                }
+                : {}),
+            // Bridge-pull terminal rung — composed whenever the App handle
+            // is bound (it always is by this point in the boot: connectApp
+            // succeeded and setCurrentApp ran above), INDEPENDENT of
+            // sseUrl/pollingUrl presence. This is the universal floor for
+            // CSP-jailed hosts (claude.ai) where the iframe has no network
+            // path at all: the ledger is pulled via `ggui_runtime_pull`
+            // `tools/call`s over the host's postMessage bridge. Shares the
+            // SAME ladder cursor — a demotion into the bridge resumes from
+            // whatever the rungs above already delivered.
+            ...(bridgeApp !== null && ladderCursor !== undefined
+                ? {
+                    bridge: buildBridgePolling({
+                        callTool: (name, args) => bridgeApp.callServerTool({ name, arguments: args }),
+                        sessionId: meta.sessionId,
+                        cursor: ladderCursor,
                     }),
                 }
                 : {}),
@@ -626,12 +789,19 @@ export async function bootSequence(opts) {
         emitBootFailure('WS_HANDSHAKE_FAILED', message);
         return { ok: false, mountedRender };
     }
+    telemetry?.record('subscribe.resolved', JSON.stringify({ kind: handle.handle.kind, hasAck: handle.ack !== undefined }));
     // Attach the live transport handle to the renderer — flushes any
-    // buffered outbound `action` frames that were queued
-    // while the subscribe handshake completed. `handle.handle.send` is
-    // the canonical send surface for the bound WS transport.
+    // buffered outbound `action` frames that were queued while the
+    // subscribe handshake completed. `send` narrows to the ws surface:
+    // a trio-less bridge-only bind has NO outbound channel (gestures
+    // ride app.callServerTool, not the transport), so its sends drop —
+    // the same posture a post-swap FailoverHandle already has.
+    const transportSend = (msg) => {
+        if (handle.handle.kind === 'ws')
+            handle.handle.send(msg);
+    };
     if (renderer !== null && rendererHooks?.attachManager !== undefined) {
-        rendererHooks.attachManager(renderer, { send: (msg) => handle.handle.send(msg) });
+        rendererHooks.attachManager(renderer, { send: transportSend });
     }
     // seed the host-context emitter with the projection captured from
     // `app.getHostContext()` (the App class's spec-canonical
@@ -642,7 +812,7 @@ export async function bootSequence(opts) {
     if (parsed.hostContext !== undefined) {
         seedHostContext({
             sessionId: meta.sessionId,
-            send: (msg) => handle.handle.send(msg),
+            send: transportSend,
             initial: parsed.hostContext,
         });
         // Bind via App's spec-canonical `hostcontextchanged` event surface.
@@ -655,8 +825,12 @@ export async function bootSequence(opts) {
     // `pinnedSessionId`) and mount it. Reuses the same `applyAck` helper
     // the reconnect-rebootstrap path uses — so a server-restart-driven
     // snapshot replay and the first-boot snapshot apply flow through
-    // one implementation.
-    await applyAck(handle.ack);
+    // one implementation. Trio-less bridge-only binds have no handshake
+    // and therefore no ack — the static seed already painted, and the
+    // bridge delivers deltas from the boot cursor.
+    if (handle.ack !== undefined) {
+        await applyAck(handle.ack);
+    }
     setConnectedStatus(refs);
     // Lifecycle `code-ready` — terminal happy state. Emitted ONCE per boot
     // (a static+live meta already fired it from the seed mount, so this is
@@ -942,6 +1116,26 @@ export function readPendingToolResults() {
     }
     return null;
 }
+/**
+ * Sibling of {@link readPendingToolResults} for the read-plane-only
+ * posture (ggui#537): the NEWEST buffered tool result that carries a
+ * `ui://ggui/render/…` locator but no bootstrap material. Consulted only
+ * when the buffer yielded no inline slice; the autostart threads it to
+ * `bootSequence` as `preResolvedLocator`, resolved after the handshake.
+ */
+export function readPendingToolResultLocator() {
+    if (typeof window === 'undefined')
+        return null;
+    const raw = window.__GGUI_PENDING_TOOL_RESULTS__;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    for (let i = raw.length - 1; i >= 0; i--) {
+        const locator = extractLocatorFromToolResult(raw[i]);
+        if (locator !== null)
+            return locator;
+    }
+    return null;
+}
 /**
  * Listen for a `ui/notifications/tool-result` notification via the
  * App's spec-canonical event surface and resolve to the extracted
@@ -957,36 +1151,75 @@ export function readPendingToolResults() {
 function awaitToolResultMetaFromApp(app, timeoutMs) {
     return new Promise((resolve) => {
         let settled = false;
-        const handler = (params) => {
+        const settle = (value) => {
             if (settled)
                 return;
-            const meta = extractMetaFromToolResult(params);
-            if (meta === null)
-                return;
             settled = true;
             app.removeEventListener('toolresult', handler);
             clearTimeout(timer);
-            resolve(meta);
+            resolve(value);
         };
-        app.addEventListener('toolresult', handler);
-        const timer = setTimeout(() => {
+        const handler = (params) => {
             if (settled)
                 return;
-            settled = true;
-            app.removeEventListener('toolresult', handler);
-            resolve(null);
-        }, timeoutMs);
+            const meta = extractMetaFromToolResult(params);
+            if (meta !== null) {
+                settle(meta);
+                return;
+            }
+            // Read-plane door (ggui#537): identity-only result → resolve the
+            // locator through the host's `resources/read` proxy. Async, and
+            // it never settles `null` — a later result carrying the slice
+            // inline (or the timeout) still decides.
+            const locator = extractLocatorFromToolResult(params);
+            if (locator === null)
+                return;
+            void resolveMetaViaReadDoor(app, locator).then((resolved) => {
+                if (resolved !== null)
+                    settle(resolved);
+            });
+        };
+        app.addEventListener('toolresult', handler);
+        const timer = setTimeout(() => settle(null), timeoutMs);
     });
 }
 /**
- * Pre-handshake variant — listens to raw `window.message` for the
- * autostart layer. Used BEFORE the App is constructed, so this can't
- * route through `app.addEventListener`. Pairs with the minimal-shell
- * pattern: the shell buffers any tool-results that arrived BEFORE
- * runtime load (read via {@link readPendingToolResults}); this
- * listener catches the ones that arrive AFTER the bundle parses but
- * BEFORE bootSequence runs.
- */
+ * The read-plane door (ggui#537). A server running the read-plane-only
+ * posture publishes only the view's identity on the tool result — the
+ * `ui://ggui/render/…` locator — and no bootstrap material; the
+ * per-render resource that locator names is the self-contained shell,
+ * whose document inlines the very envelope this runtime boots from.
+ * Ask the HOST to read it (`app.readServerResource` → `resources/read`,
+ * proxied by the host's own MCP client — no fetch from this sandbox, so
+ * a host CSP without `connect-src` to the server is not in the way),
+ * recover the envelope with the protocol's writer/reader pair
+ * ({@link readGguiShellEnvelope}), and validate it exactly as an inline
+ * slice would be. `null` on any miss (host cannot proxy reads, resource
+ * gone, no envelope) — the caller's other tiers still decide.
+ */
+export async function resolveMetaViaReadDoor(app, locator) {
+    let text;
+    try {
+        const res = await app.readServerResource({ uri: locator });
+        const first = res.contents[0];
+        text = first !== undefined && 'text' in first && typeof first.text === 'string' ? first.text : undefined;
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console -- operator-visible: the door is a boot tier, its miss must be legible
+        console.warn(`[ggui-runtime] read-plane door: host could not read ${locator} — ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (text === undefined)
+        return null;
+    const envelope = readGguiShellEnvelope(text);
+    if (envelope === undefined)
+        return null;
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope);
+    if (!parsed.ok || parsed.meta === undefined)
+        return null;
+    const validated = validateMeta(parsed.meta);
+    return validated.ok ? validated.meta : null;
+}
 function awaitToolResultMeta(timeoutMs) {
     if (typeof window === 'undefined')
         return Promise.resolve(null);
@@ -1009,8 +1242,17 @@ function awaitToolResultMeta(timeoutMs) {
                 return;
             }
             const meta = extractMetaFromToolResult(m.params);
-            if (meta !== null)
-                settle(meta);
+            if (meta !== null) {
+                settle({ kind: 'meta', meta });
+                return;
+            }
+            // Identity-only result (ggui#537): settle NOW with the locator so
+            // boot starts immediately and the door runs after the handshake —
+            // waiting the full timeout for a slice this posture never sends
+            // would cost every spec-host view 30 s for nothing.
+            const locator = extractLocatorFromToolResult(m.params);
+            if (locator !== null)
+                settle({ kind: 'locator', locator });
         };
         window.addEventListener('message', onMessage);
         const timer = setTimeout(() => settle(null), timeoutMs);
@@ -1307,6 +1549,23 @@ export function emitAudit(args) {
  * iframe-runtime then falls through to `ui/message` so the gesture
  * still reaches the agent on its next turn.
  */
+/**
+ * Unwrap the payload record of a relayed submit-action tool result.
+ * Envelope-level shim over the shared 3-tier unwrap
+ * ({@link unwrapCallToolResult}: `structuredContent` →
+ * `content[0].text` parsed as JSON → bare result) — this wrapper only
+ * peels the JSON-RPC `result` field first. The tiers themselves are
+ * shared with the bridge-pull rung's `fetchBody` carrier
+ * (`events-polling.ts`) so both reads agree on which envelope tier
+ * carries the payload for a given host shape.
+ * Returns `null` when no tier yields an object — the caller treats
+ * that as fallback/unknown.
+ */
+function submitActionPayload(resp) {
+    if (resp === null || typeof resp !== 'object')
+        return null;
+    return unwrapCallToolResult(resp.result);
+}
 function classifySubmitActionResponse(resp) {
     if (resp === null || typeof resp !== 'object')
         return 'fallback';
@@ -1315,15 +1574,9 @@ function classifySubmitActionResponse(resp) {
         resp.error !== null) {
         return 'fallback';
     }
-    const result = resp.result;
-    if (result === null || typeof result !== 'object')
+    const inner = submitActionPayload(resp);
+    if (inner === null)
         return 'fallback';
-    const r = result;
-    // Spec-canonical hosts wrap tool output under `structuredContent`;
-    // looser hosts may surface fields directly on `result`.
-    const inner = r.structuredContent && typeof r.structuredContent === 'object'
-        ? r.structuredContent
-        : r;
     return inner.ok === true ? 'success' : 'fallback';
 }
 /**
@@ -1355,25 +1608,65 @@ function isRelayShapedFailure(resp) {
 /**
  * Extract `consumerPresent` from a successful submit_action response.
  * Returns the boolean if present + well-typed; `undefined` otherwise
- * (server didn't wire the registry, agnostic host stripped the field,
- * or any non-`ok:true` shape — callers fall back to the 10s timer
- * path on `undefined`). Mirrors the structuredContent → result
- * unwrap of {@link classifySubmitActionResponse} so both reads agree
- * on which envelope tier carries the success payload.
+ * (agnostic host stripped the field, or any non-`ok:true` shape).
+ * `undefined` is treated by the dispatch gate as "no confirmed
+ * consumer" — the doorbell rings. Shares {@link submitActionPayload}
+ * with {@link classifySubmitActionResponse} so both reads agree on
+ * which envelope tier carries the payload.
  */
 function extractConsumerPresent(resp) {
-    if (resp === null || typeof resp !== 'object')
-        return undefined;
-    const result = resp.result;
-    if (result === null || typeof result !== 'object')
+    const inner = submitActionPayload(resp);
+    if (inner === null)
         return undefined;
-    const r = result;
-    const inner = r.structuredContent && typeof r.structuredContent === 'object'
-        ? r.structuredContent
-        : r;
     const flag = inner.consumerPresent;
     return typeof flag === 'boolean' ? flag : undefined;
 }
+/**
+ * Freeze-cue overlay (#483). A superseded (history) card gets a
+ * subtle, theme-aware "superseded" veil + a labelled pill, and its
+ * content is made non-interactive so a stale-view click can't even
+ * reach a control. Idempotent — the overlay id guards a second call.
+ * A polite live-region announcement (reusing the #447 announcer)
+ * tells a screen-reader user the card is now history.
+ */
+const FREEZE_CUE_ID = '__ggui-superseded-cue__';
+function applyFreezeCue(root) {
+    if (typeof document === 'undefined')
+        return;
+    if (root.querySelector(`#${FREEZE_CUE_ID}`) !== null)
+        return;
+    // Non-interactive + visually receded — inherits the mount's own
+    // colors, so it reads correctly in any theme.
+    root.style.pointerEvents = 'none';
+    root.style.opacity = '0.55';
+    root.style.filter = 'grayscale(0.4)';
+    root.style.transition = 'opacity 160ms ease, filter 160ms ease';
+    if (getComputedStyle(root).position === 'static') {
+        root.style.position = 'relative';
+    }
+    const pill = document.createElement('div');
+    pill.id = FREEZE_CUE_ID;
+    pill.setAttribute('role', 'note');
+    pill.textContent = 'Superseded — a newer version continues below';
+    Object.assign(pill.style, {
+        position: 'absolute',
+        top: '8px',
+        right: '8px',
+        padding: '4px 10px',
+        borderRadius: '9999px',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        fontSize: '11px',
+        fontWeight: '600',
+        color: 'var(--ggui-color-onSurface, inherit)',
+        background: 'rgba(128,128,128,0.16)',
+        border: '1px solid currentColor',
+        opacity: '0.85',
+        pointerEvents: 'none',
+        zIndex: '2',
+    });
+    root.appendChild(pill);
+    announceToast('This card was superseded by a newer version below', 'fallback');
+}
 /** Container id for the announcer holding both live regions. */
 const TOAST_ANNOUNCER_ID = '__ggui-toast-announcer__';
 /**
@@ -1710,7 +2003,7 @@ function emitUserActionDoorbell(args) {
         `  <next_args>${nextArgs}</next_args>`,
         `</ggui_directive>`,
         '',
-        `The user interacted with render ${args.sessionId} while no ggui_consume long-poll was active. The gesture is queued on the consume pipe for that render — it is NOT in this message. After ggui_consume returns, react to the returned event with the appropriate domain tool, then call ggui_update on the SAME sessionId (${args.sessionId}).`,
+        `The user interacted with render ${args.sessionId} while no ggui_consume long-poll was active. The gesture is queued on the consume pipe for that render — it is NOT in this message. After ggui_consume returns, react to the returned event with the appropriate domain tool, then call ggui_amend on the SAME sessionId (${args.sessionId}) — the card the user is looking at repaints in place. Use ggui_update instead only if this moment deserves a NEW card in the conversation (it advances the history number).`,
     ].join('\n');
     // Structured mirror of the directive for ggui-aware programmatic
     // consumers. OPTIONAL — nothing in the loop depends on a server-side
@@ -1754,6 +2047,7 @@ function emitUserActionDoorbell(args) {
     // record — the proper extension point). Namespaced under
     // `ai.ggui/userAction` to match our other protocol extensions
     // (`ai.ggui/render`, `ai.ggui/bootstrap`, etc.).
+    currentTelemetrySink?.record('doorbell.ring', args.sessionId);
     postToParent({
         jsonrpc: '2.0',
         id: Math.floor(Math.random() * 1e9),
@@ -1785,6 +2079,23 @@ function emitUserActionDoorbell(args) {
  * nothing else about the latch is observable to the host.
  */
 let relayIncapabilityAnnounced = false;
+/**
+ * Module-level handle to the CURRENT boot's telemetry sink so
+ * module-scope paths (the doorbell emitter below) can report without
+ * threading the sink through every call chain. Per-iframe
+ * single-tenancy makes a single slot correct — same justification as
+ * `getCurrentApp()`.
+ */
+let currentTelemetrySink = null;
+/**
+ * Freeze latch (#483): set true once a higher-epoch `ggui_update`
+ * supersedes this mount. A frozen mount is HISTORY — its gestures no
+ * longer target the live session, so `dispatchSubmitAction` drops them
+ * (a stale-view submit against the live head is a prevented bug class).
+ * Module-level for the same single-mount-per-iframe reason as
+ * `currentTelemetrySink`.
+ */
+let mountSuperseded = false;
 /**
  * Whether the user has manually dismissed the CURRENTLY-STANDING relay
  * notice (ggui#442).
@@ -2066,7 +2377,20 @@ function showPostDismissalCue(intent) {
 export function dispatchSubmitAction(args) {
     if (typeof window === 'undefined')
         return;
+    // Freeze latch (#483): a superseded (history) mount does not drive
+    // the live session — drop the gesture rather than submit a stale
+    // view's action against the current head.
+    if (mountSuperseded) {
+        currentTelemetrySink?.record('gesture.dropped_superseded', args.intent);
+        return;
+    }
     const { toolName, intent, data, sessionId, appId } = args;
+    // Gesture-path telemetry — the click's own autopsy trail. #471
+    // round 12 hit a frame whose channels + beacons were fully healthy
+    // while clicks produced NOTHING observable; without a record at the
+    // dispatch entry there is no way to tell "handler never fired" from
+    // "dispatch swallowed it" on a console-less host.
+    currentTelemetrySink?.record('gesture.dispatch', JSON.stringify({ intent, toolName }));
     const firedAt = new Date().toISOString();
     const actionId = fnv1aHex(`${intent}|${JSON.stringify(data ?? null)}|${firedAt}`);
     const inlineData = formatSubmitActionDataInline(data);
@@ -2151,6 +2475,15 @@ export function dispatchSubmitAction(args) {
             showActionToast(`⚠ ${intent} — transport error`, 'error');
             resp = null;
         }
+        // Final hop of the gesture autopsy trail — what the relay
+        // answered (or that it didn't).
+        currentTelemetrySink?.record('gesture.result', JSON.stringify({
+            intent,
+            ok: resp !== null && resp.error === undefined,
+            ...(resp?.error?.message !== undefined
+                ? { error: resp.error.message.slice(0, 120) }
+                : {}),
+        }));
         // Self-healing (ggui#440): a result envelope arriving at all is
         // proof this host CAN relay — `{ok:false, code:'PIPE_NOT_FOUND'}`
         // (an otherwise-healthy relay, expired pipe) proves it exactly as
@@ -2192,16 +2525,25 @@ export function dispatchSubmitAction(args) {
         }
         if (resp !== null && classifySubmitActionResponse(resp) === 'success') {
             const consumerPresent = extractConsumerPresent(resp);
-            if (consumerPresent === false) {
-                // No `ggui_consume` long-poll is draining this render's pipe,
-                // so the gesture needs a fresh agent turn. `ui/message` is the
-                // ONLY view→host method that can start one — a host that does
-                // not accept it cannot be woken by us at all, and the user has
-                // to send a message themselves (ggui#440).
+            if (consumerPresent !== true) {
+                // No `ggui_consume` long-poll is POSITIVELY confirmed to be
+                // draining this render's pipe, so the gesture needs a fresh
+                // agent turn. `ui/message` is the ONLY view→host method that
+                // can start one — a host that does not accept it cannot be
+                // woken by us at all, and the user has to send a message
+                // themselves (ggui#440).
                 //
-                // The doorbell is posted either way: capability absence is an
-                // unconfirmed signal, not a proven "cannot", and a dropped
-                // postMessage costs nothing.
+                // `!== true` (not `=== false`) is load-bearing: a relay host
+                // that normalizes the tool result and strips the
+                // `consumerPresent` field (claude.ai's live behavior — the
+                // first #471 retest click died exactly here) must ring the
+                // doorbell, not wait forever for a drain_ack that cannot
+                // arrive without a live channel. The doorbell is pointer-only
+                // and the pipe pop is exactly-once, so a redundant ring on a
+                // field-stripping host with a live consumer costs one empty
+                // `ggui_consume`; servers that CAN answer always send an
+                // explicit `true` (the factory wires the registry
+                // unconditionally), so confirmed-consumer hosts stay quiet.
                 showActionToast(hostCanReceiveMessages()
                     ? `💬 ${intent}${dataPart} — agent not listening, sent to chat`
                     : `💬 ${intent}${dataPart} — agent not listening. Send a message to continue.`, 'action_required');
@@ -2213,9 +2555,9 @@ export function dispatchSubmitAction(args) {
                 });
                 return;
             }
-            // consumerPresent is true (or undefined — agnostic host stripped
-            // the field). Toast stays `pending`; drain_ack listener dismisses
-            // it when ggui_consume drains the event.
+            // consumerPresent === true — a live long-poll is confirmed
+            // draining the pipe. Toast stays `pending`; the drain_ack
+            // listener dismisses it when ggui_consume drains the event.
             return;
         }
         // Enqueue failed (pipe gone / transport error / host has no relay).
@@ -2759,7 +3101,7 @@ function readLiveBootstrapShape() {
  * re-await the same postMessage or re-parse the same global), saving
  * up to the 30s postMessage timeout for spec-strict hosts.
  */
-function runBootProduction(preResolvedMeta) {
+function runBootProduction(preResolvedMeta, preResolvedLocator) {
     const { app, transport } = createDefaultApp();
     void bootProduction({
         doc: document,
@@ -2775,6 +3117,7 @@ function runBootProduction(preResolvedMeta) {
         onObserve: postObservabilityToParent,
         onLifecycle: postLifecycleToParent,
         ...(preResolvedMeta !== undefined ? { preResolvedMeta } : {}),
+        ...(preResolvedLocator !== undefined ? { preResolvedLocator } : {}),
     });
 }
 if (shouldAutostart() && typeof window !== 'undefined') {
@@ -2805,15 +3148,26 @@ if (shouldAutostart() && typeof window !== 'undefined') {
     }
     else {
         const buffered = readPendingToolResults();
+        const bufferedLocator = buffered === null ? readPendingToolResultLocator() : null;
         if (buffered !== null) {
             runBootProduction(buffered);
         }
+        else if (bufferedLocator !== null) {
+            // Read-plane-only posture (ggui#537): the buffered result named
+            // the view; the door resolves it right after the handshake.
+            runBootProduction(undefined, bufferedLocator);
+        }
         else if (readLiveBootstrapShape()) {
             runBootProduction();
         }
         else {
-            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((postMessageMeta) => {
-                runBootProduction(postMessageMeta ?? undefined);
+            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((pre) => {
+                if (pre === null)
+                    runBootProduction();
+                else if (pre.kind === 'meta')
+                    runBootProduction(pre.meta);
+                else
+                    runBootProduction(undefined, pre.locator);
             });
         }
     }
@@ -2982,6 +3336,28 @@ async function bootProduction(opts) {
             // these lived only in the retired self-contained boot path; the
             // WS-driven path installed neither, so anchor clicks + fullscreen
             // requests in a live-rendered component silently no-op'd.
+            // Root of the gesture autopsy trail: a capture-phase listener
+            // proving pointer events reach this document AT ALL. #471
+            // round 12: a healthy frame (beacons + pulls flowing) whose
+            // clicks produced nothing observable — without this record,
+            // "host swallows pointer events" and "component handler never
+            // attached" are indistinguishable from outside a console-less
+            // host. Bounded: only the first few clicks record (the sink
+            // throttles + caps flushes regardless).
+            if (typeof document !== 'undefined') {
+                let recordedClicks = 0;
+                document.addEventListener('click', (ev) => {
+                    if (recordedClicks >= 5)
+                        return;
+                    recordedClicks += 1;
+                    const target = ev.target instanceof Element ? ev.target : null;
+                    currentTelemetrySink?.record('gesture.dom_click', JSON.stringify({
+                        tag: target?.tagName ?? 'unknown',
+                        role: target?.getAttribute('role') ?? undefined,
+                        trusted: ev.isTrusted,
+                    }));
+                }, { capture: true });
+            }
             installAnchorClickInterceptor({
                 dispatchToolName,
                 sessionId: meta.sessionId,
@@ -2999,6 +3375,10 @@ async function bootProduction(opts) {
                 manager,
                 streamBus,
                 onDispatchEnvelope: (envelope) => {
+                    // First hop of the gesture autopsy trail (see
+                    // `dispatchSubmitAction`'s sibling record): proves the wire
+                    // layer received the component's action envelope at all.
+                    currentTelemetrySink?.record('gesture.envelope', JSON.stringify({ type: envelope.type }));
                     if (envelope.type !== 'data:submit')
                         return;
                     const payload = envelope.payload;
@@ -3066,10 +3446,30 @@ async function bootProduction(opts) {
                     ...(meta.gadgets !== undefined
                         ? { gadgetPackages: meta.gadgets.map((g) => g.package) }
                         : {}),
-                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
-                    ...(meta.themeMode !== undefined
-                        ? { themeMode: meta.themeMode }
+                    // Strict-CSP module variant (ggui#522 slice 2) — attached to
+                    // the INLINE SEED mount only, detected by the absence of the
+                    // server-assigned ledger fields (`buildGguiSessionSeedInput`
+                    // omits them; every wire-delivered GguiSession carries them).
+                    // The variant URL names the SEEDED bytes: a WS-delivered
+                    // body may differ, and importing a stale variant would paint
+                    // the WRONG component rather than fail. A WS redelivery of
+                    // the SAME bytes loses nothing — same code ⇒ the renderer
+                    // skips re-evaluation entirely.
+                    ...(meta.codeModuleUrl !== undefined &&
+                        render.type !== 'mcpApps' &&
+                        render.type !== 'system' &&
+                        !('createdAt' in render)
+                        ? { codeModuleUrl: meta.codeModuleUrl }
                         : {}),
+                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
+                    // Mode: the slice's stamped `themeMode` (every operator layer
+                    // resolves into it) wins; when absent, the HOST's announced
+                    // theme fills the gap (ggui#551 — see `hostAnnouncedThemeMode`).
+                    // Absent-in-slice means "no operator opinion", not "light".
+                    ...(() => {
+                        const themeMode = meta.themeMode ?? hostAnnouncedThemeMode();
+                        return themeMode !== undefined ? { themeMode } : {};
+                    })(),
                     // Per-app theme overlay (St3 M2.2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
@@ -3185,9 +3585,28 @@ async function bootProduction(opts) {
                 streamBus,
                 validatorCtx,
             }));
+            // Freeze latch (#483). This mount's own history epoch, read once
+            // from its boot meta: render → 0, an update-minted card → its N,
+            // a pinned `#N` read → N. When a `props_update` frame carries a
+            // higher epoch, a newer card superseded this one.
+            const selfEpoch = typeof meta.epoch === 'number' ? meta.epoch : 0;
+            let superseded = false;
+            const supersede = () => {
+                if (superseded)
+                    return;
+                superseded = true;
+                // Module-level dispatch guard: a history card's gestures no
+                // longer target the live session.
+                mountSuperseded = true;
+                currentTelemetrySink?.record('epoch.frozen', String(selfEpoch));
+                applyFreezeCue(renderInto);
+            };
             channelRegistry.register(createPropsUpdateHandler({
                 getCurrentGguiSession: () => currentRender,
                 applyRender,
+                getSelfEpoch: () => selfEpoch,
+                onSuperseded: supersede,
+                isSuperseded: () => superseded,
             }));
             channelRegistry.register(createDrainAckHandler({ dispatch: dispatchDrainAck }));
             channelRegistry.register(createChannelPayloadHandler({
@@ -3238,5 +3657,8 @@ async function bootProduction(opts) {
         ...(opts.preResolvedMeta !== undefined
             ? { preResolvedMeta: opts.preResolvedMeta }
             : {}),
+        ...(opts.preResolvedLocator !== undefined
+            ? { preResolvedLocator: opts.preResolvedLocator }
+            : {}),
     });
 }