@ggui-ai/iframe-runtime 0.7.0 → 0.9.0

package/dist/runtime.js

@@ -7,9 +7,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';
@@ -386,16 +388,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
@@ -461,16 +471,37 @@ export async function bootSequence(opts) {
         onLifecycle?.(makeLifecycleEvent('code-ready', { sessionId: meta.sessionId }));
     };
     // Mode discriminators. The mount surface is DECOUPLED from the live
-    // channel: static content (codeUrl/kind) paints immediately with no WS;
-    // the live trio (wsUrl+wsToken) is an OPTIONAL enhancement that
-    // delivers props_update / data / re-render frames. A bootstrap with
-    // NEITHER has nothing to show and nowhere to subscribe.
-    const hasStaticContent = (typeof meta.codeUrl === 'string' && meta.codeUrl.length > 0) ||
-        (typeof meta.kind === 'string' && meta.kind.length > 0);
+    // channel: static content (codeUrl/codeB64/kind) paints immediately
+    // with no WS; the live trio (wsUrl+wsToken) is an OPTIONAL
+    // enhancement that delivers props_update / data / re-render frames.
+    // A bootstrap with NEITHER has nothing to show and nowhere to
+    // subscribe.
+    const hasStaticContent = hasStaticContentMeta(meta);
     const hasLiveTrio = typeof meta.wsUrl === 'string' &&
         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 +542,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/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 +585,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 +645,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 +725,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 +748,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 +761,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
@@ -801,16 +911,22 @@ function parseSeedProps(propsJson) {
  * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
  * live channel (claude.ai / ChatGPT / Claude Desktop).
  *
- * Two static-content shapes (the autostart discriminator):
+ * Three static-content shapes (the autostart discriminator), in
+ * priority order:
  *   - `kind`    → a system-card seed (`type:'system'`); no fetch.
+ *   - `codeB64` → a compiled-component seed carried inline; DECODED,
+ *     never fetched. Preferred over `codeUrl` when both are present —
+ *     the inline bytes exist precisely for hosts whose iframe CSP
+ *     blocks the fetch.
  *   - `codeUrl` → a compiled-component seed; fetches the
  *     content-addressable component bytes.
  *
- * Returns `null` when the meta carries NEITHER (a live-only meta has
+ * Returns `null` when the meta carries NONE (a live-only meta has
  * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
- * fetch fails so the caller can surface a typed boot failure. The four
- * server-assigned ledger fields are intentionally absent — the first
- * ack reconciles the seed to a full `GguiSession` (no fabrication).
+ * fetch fails or `codeB64` is not valid base64 so the caller can
+ * surface a typed boot failure. The four server-assigned ledger fields
+ * are intentionally absent — the first ack reconciles the seed to a
+ * full `GguiSession` (no fabrication).
  */
 export async function buildGguiSessionSeedInput(meta) {
     const props = parseSeedProps(meta.propsJson);
@@ -824,6 +940,15 @@ export async function buildGguiSessionSeedInput(meta) {
             ...(props !== undefined ? { props } : {}),
         };
     }
+    // Inline compiled-component mode — decode, no network.
+    if (meta.codeB64 !== undefined) {
+        return {
+            id: meta.sessionId,
+            appId: meta.appId,
+            componentCode: decodeCodeB64(meta.codeB64),
+            ...(props !== undefined ? { props } : {}),
+        };
+    }
     // Compiled-component mode — fetch the content-addressable bytes.
     if (meta.codeUrl === undefined)
         return null;
@@ -839,6 +964,45 @@ export async function buildGguiSessionSeedInput(meta) {
         ...(props !== undefined ? { props } : {}),
     };
 }
+/**
+ * Does this slice carry STATIC content the mount surface can paint
+ * without any network round-trip authorization — `codeUrl` (fetched),
+ * `codeB64` (decoded inline), or `kind` (built-in registry)?
+ *
+ * The ONE discriminator `bootSequence` consults when deciding whether
+ * the static seed-mount path runs. `codeB64` counting here is
+ * load-bearing for fetch-blocked hosts: their meta carries codeB64
+ * PLUS a live trio the iframe can never connect, and missing the
+ * inline arm would skip the only paint path and die on the dead WS.
+ * Mirrors `validateMeta`'s static-content arm (meta-parse.ts) and the
+ * protocol host-helper's `hasMountModeDiscriminator` — drift among
+ * the three IS the historical bug class, hence the named export.
+ */
+export function hasStaticContentMeta(meta) {
+    return ((typeof meta.codeUrl === 'string' && meta.codeUrl.length > 0) ||
+        (typeof meta.codeB64 === 'string' && meta.codeB64.length > 0) ||
+        (typeof meta.kind === 'string' && meta.kind.length > 0));
+}
+/**
+ * Decode a `codeB64` slice field to UTF-8 component source. `atob`
+ * yields a byte string; routing through `TextDecoder` restores
+ * multi-byte characters (component source is UTF-8 — string literals
+ * carry emoji, quotes, non-Latin text). Throws a labeled error on
+ * malformed base64 so the boot-failure surface names the field.
+ */
+function decodeCodeB64(codeB64) {
+    try {
+        const byteString = atob(codeB64);
+        const bytes = new Uint8Array(byteString.length);
+        for (let i = 0; i < byteString.length; i++) {
+            bytes[i] = byteString.charCodeAt(i);
+        }
+        return new TextDecoder().decode(bytes);
+    }
+    catch (cause) {
+        throw new Error('buildGguiSessionSeedInput: codeB64 is not valid base64', { cause });
+    }
+}
 /**
  * Extract a {@link McpAppAiGguiRenderMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
@@ -860,23 +1024,29 @@ export function extractMetaFromToolResult(params) {
 /**
  * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
  * minimal shell populates while messages arrive between
- * shell-load and runtime-load. Returns the first valid slice meta
- * found; later params (if any) are dropped (each new tool-result
- * supersedes the previous).
- *
- * The shell-side buffer contract: an array of
- * `{params: unknown}`-shaped JSON-RPC params from
- * `ui/notifications/tool-result` notifications, populated in
- * arrival order. The runtime drains it on first read.
- */
-function readPendingToolResults() {
+ * shell-load and runtime-load. Returns the NEWEST valid slice meta
+ * (each new tool-result supersedes the previous — every emission
+ * carries complete state, so last-wins loses nothing). Newest-first
+ * matters on the inline-runtime shell: its preflight completes the
+ * handshake BEFORE the large bundle parses, so a render AND a
+ * follow-up update can both land in the buffer during parse — booting
+ * the oldest would paint stale props and drop the update forever
+ * (buffered entries never reach the post-mount listener; it hears
+ * only post-App arrivals).
+ *
+ * The shell-side buffer contract: an array whose ELEMENTS are the raw
+ * JSON-RPC `params` values of `ui/notifications/tool-result`
+ * notifications, in arrival order (shells cap it newest-biased). The
+ * runtime reads it once at autostart.
+ */
+export function readPendingToolResults() {
     if (typeof window === 'undefined')
         return null;
     const raw = window.__GGUI_PENDING_TOOL_RESULTS__;
     if (!Array.isArray(raw) || raw.length === 0)
         return null;
-    for (const params of raw) {
-        const meta = extractMetaFromToolResult(params);
+    for (let i = raw.length - 1; i >= 0; i--) {
+        const meta = extractMetaFromToolResult(raw[i]);
         if (meta !== null)
             return meta;
     }
@@ -1247,6 +1417,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';
@@ -1255,15 +1442,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';
 }
 /**
@@ -1295,25 +1476,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__';
 /**
@@ -1650,7 +1871,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
@@ -1694,6 +1915,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),
@@ -1725,6 +1947,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).
@@ -2006,7 +2245,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);
@@ -2091,6 +2343,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
@@ -2132,16 +2393,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');
@@ -2153,9 +2423,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).
@@ -2609,6 +2879,10 @@ function installPostMountListener() {
             meta.sessionId,
             meta.kind ?? '-',
             meta.codeUrl ?? '-',
+            // Inline code participates like codeUrl: an update that ships new
+            // component bytes (re-generation) must re-mount even when
+            // sessionId + props are unchanged.
+            meta.codeB64 ?? '-',
             meta.propsJson ?? '-',
             liveTrio,
         ].join('|');
@@ -2918,6 +3192,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,
@@ -2935,6 +3231,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;
@@ -3121,9 +3421,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({