@ggui-ai/iframe-runtime 0.7.0 → 0.9.0

package/dist/mcp-app-iframe-host.d.ts

@@ -1,5 +1,5 @@
 /**
- * Vanilla-TS port of `@ggui-ai/react::components/GguiRender.tsx`'s
+ * Vanilla-TS port of `@ggui-ai/mcp-apps-react::components/GguiRender.tsx`'s
  * MCP-Apps branch. Used when a ggui render's `type === 'mcpApps'`
  * — the renderer mounts a nested iframe that embeds a foreign
  * MCP App.

package/dist/meta-parse.d.ts

@@ -11,9 +11,9 @@ import type { McpAppAiGguiMetaParseResult } from './types.js';
  *     direct-call callers like `parseMetaFromGlobal` / tests; the
  *     envelope-driven extractors already enforce this in the protocol-
  *     level parser).
- *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, kind}` MUST
- *     be present. Without any mode discriminator the iframe has nothing
- *     to mount.
+ *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, codeB64,
+ *     kind}` MUST be present. Without any mode discriminator the iframe
+ *     has nothing to mount.
  */
 export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGguiMetaParseResult;
 /**

package/dist/meta-parse.js

@@ -40,9 +40,10 @@
  *
  *   - **live** — slice has `wsUrl` + `wsToken`; runtime opens
  *     live-channel WS and renders agent-driven frames.
- *   - **static-component** — slice has `codeUrl`; runtime fetches
- *     the content-addressable URL, dynamic-imports the React
- *     component, mounts it, never opens WS.
+ *   - **static-component** — slice has `codeUrl` (runtime fetches the
+ *     content-addressable URL) and/or `codeB64` (runtime decodes the
+ *     inline bytes, no fetch); mounts the React component, never
+ *     opens WS.
  *   - **system-card** — slice has `kind`; runtime maps to a
  *     built-in component via the system-card registry.
  *
@@ -177,9 +178,9 @@ function projectPublicEnv(raw) {
  *
  * Invariants enforced here that the combiner doesn't:
  *   - `expiresAt` (when present) MUST parse to a valid timestamp. If
- *     in the past AND the slice carries static content (codeUrl / kind),
- *     DEGRADE to static-only (drop `wsUrl` / `wsToken` / `expiresAt`);
- *     otherwise return EXPIRED_BOOTSTRAP.
+ *     in the past AND the slice carries static content (codeUrl /
+ *     codeB64 / kind), DEGRADE to static-only (drop `wsUrl` /
+ *     `wsToken` / `expiresAt`); otherwise return EXPIRED_BOOTSTRAP.
  *   - `gadgets` / `publicEnv` / `permissionsPolicy` /
  *     `streamWebSocketLocalTools` / `contextSlots` get defensive
  *     entry-level validation; malformed → defaulted.
@@ -238,6 +239,12 @@ function projectMeta(meta, hasStaticContent) {
         ...(meta.pollingUrl !== undefined
             ? { pollingUrl: meta.pollingUrl }
             : {}),
+        // sseUrl mirrors pollingUrl's posture: unconditional pass-through,
+        // OUTSIDE the dropLiveCreds guard. Both are server-stamped
+        // wsToken-gated URLs; on the expired-creds degrade path they're
+        // harmless dead data because runtime.ts early-returns static-only
+        // before any live bind.
+        ...(meta.sseUrl !== undefined ? { sseUrl: meta.sseUrl } : {}),
         ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
         ...(themeMode !== undefined ? { themeMode } : {}),
         // Per-app theme overlay carried through verbatim. Already validated
@@ -250,6 +257,13 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(permissionsPolicy !== undefined ? { permissionsPolicy } : {}),
         ...(meta.lastSequence !== undefined ? { lastSequence: meta.lastSequence } : {}),
+        // Freeze-latch self-epoch (#483): this mount's own history number.
+        // Non-number collapses to undefined (⇒ boot treats itself as epoch
+        // 0). Dropping this field is catastrophic-but-quiet: every mount
+        // then boots believing epoch 0, and the first epoch-stamped live
+        // frame — including an amend's, addressed to the HEAD — freezes it
+        // (probe 18 round 2: the head card froze on its own amend).
+        ...(typeof meta.epoch === 'number' ? { epoch: meta.epoch } : {}),
         ...(meta.propsJson !== undefined ? { propsJson: meta.propsJson } : {}),
         ...(contextSlots !== undefined ? { contextSlots } : {}),
         ...(meta.contractHash !== undefined && meta.validatorsUrl !== undefined
@@ -260,6 +274,7 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(meta.codeUrl !== undefined ? { codeUrl: meta.codeUrl } : {}),
         ...(meta.codeHash !== undefined ? { codeHash: meta.codeHash } : {}),
+        ...(meta.codeB64 !== undefined ? { codeB64: meta.codeB64 } : {}),
         ...(meta.kind !== undefined ? { kind: meta.kind } : {}),
     };
     return { ok: true, meta: projected };
@@ -275,9 +290,9 @@ function projectMeta(meta, hasStaticContent) {
  *     direct-call callers like `parseMetaFromGlobal` / tests; the
  *     envelope-driven extractors already enforce this in the protocol-
  *     level parser).
- *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, kind}` MUST
- *     be present. Without any mode discriminator the iframe has nothing
- *     to mount.
+ *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, codeB64,
+ *     kind}` MUST be present. Without any mode discriminator the iframe
+ *     has nothing to mount.
  */
 export function validateMeta(meta) {
     // `runtimeUrl` is a hard wire-required field on every render slice
@@ -292,8 +307,9 @@ export function validateMeta(meta) {
     }
     const hasLive = isNonEmptyString(meta.wsUrl) && isNonEmptyString(meta.wsToken);
     const hasCodeUrl = isNonEmptyString(meta.codeUrl);
+    const hasCodeB64 = isNonEmptyString(meta.codeB64);
     const hasKind = isNonEmptyString(meta.kind);
-    const hasStaticContent = hasCodeUrl || hasKind;
+    const hasStaticContent = hasCodeUrl || hasCodeB64 || hasKind;
     if (!hasLive && !hasStaticContent) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }

package/dist/observability.d.ts

@@ -148,7 +148,7 @@ export interface ChannelPollRecoveredEvent {
 /**
  * Fired when the end user submits the runtime's in-iframe UI-feedback
  * affordance ("did this generated UI work for you?"). Field semantics
- * mirror `UiFeedbackPayload` in `@ggui-ai/react` / `@ggui-ai/react-native`
+ * mirror `UiFeedbackPayload` in `@ggui-ai/mcp-apps-react` / `@ggui-ai/mcp-apps-react-native`
  * (the host-chrome twin of this affordance):
  *
  *   - `verdict` — `'love'` / `'dislike'`, or `'other'` for the

package/dist/provisional-renderer.d.ts

@@ -1,7 +1,7 @@
 /**
  * Provisional (A2UI preview) renderer for the iframe runtime.
  *
- * Port of `@ggui-ai/react::components/ProvisionalRenderer.tsx` with
+ * Port of `@ggui-ai/mcp-apps-react::components/ProvisionalRenderer.tsx` with
  * the React-hook consumer stripped. The A2UI reduce + adjacency-list
  * render is preserved verbatim; the inputs + mount lifecycle differ:
  *

package/dist/provisional-renderer.js

@@ -1,7 +1,7 @@
 /**
  * Provisional (A2UI preview) renderer for the iframe runtime.
  *
- * Port of `@ggui-ai/react::components/ProvisionalRenderer.tsx` with
+ * Port of `@ggui-ai/mcp-apps-react::components/ProvisionalRenderer.tsx` with
  * the React-hook consumer stripped. The A2UI reduce + adjacency-list
  * render is preserved verbatim; the inputs + mount lifecycle differ:
  *

package/dist/react-renderer.d.ts

@@ -1,7 +1,7 @@
 /**
  * React component renderer for the iframe runtime.
  *
- * Port of `@ggui-ai/react::components/ReactComponentRenderer.tsx` (L10-384)
+ * Port of `@ggui-ai/mcp-apps-react::components/ReactComponentRenderer.tsx` (L10-384)
  * with the enclosing React component stripped — the iframe runtime
  * does not have an outer React tree; it owns the root `createRoot`
  * mount itself. The inner eval + data-URL-shim + error-boundary

package/dist/react-renderer.js

@@ -1,7 +1,7 @@
 /**
  * React component renderer for the iframe runtime.
  *
- * Port of `@ggui-ai/react::components/ReactComponentRenderer.tsx` (L10-384)
+ * Port of `@ggui-ai/mcp-apps-react::components/ReactComponentRenderer.tsx` (L10-384)
  * with the enclosing React component stripped — the iframe runtime
  * does not have an outer React tree; it owns the root `createRoot`
  * mount itself. The inner eval + data-URL-shim + error-boundary
@@ -32,7 +32,18 @@
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
 import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
-import { hoistImports, loadModule } from '@ggui-ai/design/module-loader';
+import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
+/**
+ * Document-lifetime verdict: URL-scheme module loading (`blob:` main
+ * module + `data:` import shims) is blocked by the host CSP. Set only
+ * when the inline path succeeded where the URL path failed AND the
+ * known-good `probeUrlModuleLoad()` module ALSO fails — an arbitrary
+ * module's failure is not CSP evidence (an import-shim allowlist miss
+ * rejects blob-instantiation of that one module while URL loading is
+ * healthy, and latching on it would force every later evaluation in
+ * the document onto the inline path's narrower semantics).
+ */
+let urlModuleLoadBlocked = false;
 // =============================================================================
 // Scope class helpers — port of RCR's `makeScopeClass` + counter.
 // =============================================================================
@@ -80,12 +91,17 @@ class RcrErrorBoundary extends Component {
             clearTimeout(this.retryTimer);
     }
     render() {
-        const { error, autoRetrying, catchCount } = this.state;
+        const { error, autoRetrying } = this.state;
         if (error === null)
             return this.props.children;
         // The two fallback UIs match the host-SDK error boundary
         // verbatim (same inline styles so operator-visible DOM is
         // identical between the host-SDK and iframe-renderer paths).
+        // Colors inherit the themed body (`--ggui-color-onSurface`) with
+        // opacity for hierarchy — hardcoded white-alpha text was
+        // illegible on light shells (#481); the boundary must stay
+        // readable on WHATEVER background the theme painted, including
+        // when theme CSS itself failed to inject (browser-default white).
         const FONT = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
         if (autoRetrying) {
             return createElement('div', {
@@ -98,14 +114,15 @@ class RcrErrorBoundary extends Component {
                     gap: 8,
                     fontFamily: FONT,
                     fontSize: 13,
-                    color: 'rgba(255,255,255,0.4)',
+                    color: 'var(--ggui-color-onSurface, inherit)',
+                    opacity: 0.6,
                 },
             }, createElement('div', {
                 style: {
                     width: 16,
                     height: 16,
-                    border: '2px solid rgba(255,255,255,0.15)',
-                    borderTopColor: 'rgba(255,255,255,0.5)',
+                    border: '2px solid rgba(128,128,128,0.25)',
+                    borderTopColor: 'currentColor',
                     borderRadius: '50%',
                     animation: 'ggui-err-spin 0.6s linear infinite',
                 },
@@ -122,6 +139,7 @@ class RcrErrorBoundary extends Component {
                 gap: 12,
                 textAlign: 'center',
                 fontFamily: FONT,
+                color: 'var(--ggui-color-onSurface, inherit)',
             },
         }, createElement('div', {
             style: {
@@ -129,27 +147,48 @@ class RcrErrorBoundary extends Component {
                 height: 48,
                 borderRadius: 14,
                 background: 'rgba(239, 68, 68, 0.1)',
+                color: '#ef4444',
                 display: 'flex',
                 alignItems: 'center',
                 justifyContent: 'center',
                 fontSize: 22,
             },
-        }, '!'), createElement('div', { style: { fontSize: 14, fontWeight: 600, color: 'rgba(255,255,255,0.8)' } }, 'Something went wrong'), createElement('div', { style: { fontSize: 12, color: 'rgba(255,255,255,0.4)', maxWidth: 280, lineHeight: 1.4 } }, 'This component encountered an error. Try asking for a different view.'), createElement('button', {
+        }, '!'), createElement('div', { style: { fontSize: 14, fontWeight: 600, opacity: 0.9 } }, 'Something went wrong'), createElement('div', { style: { fontSize: 12, opacity: 0.6, maxWidth: 280, lineHeight: 1.4 } }, 'This component encountered an error. Try asking for a different view.'), createElement('button', {
             onClick: () => this.setState({ error: null, catchCount: 0 }),
             style: {
                 marginTop: 4,
                 padding: '8px 20px',
                 borderRadius: 8,
-                border: '1px solid rgba(255,255,255,0.15)',
-                background: 'rgba(255,255,255,0.08)',
-                color: 'rgba(255,255,255,0.7)',
+                border: '1px solid currentColor',
+                background: 'transparent',
+                color: 'inherit',
+                opacity: 0.75,
                 fontSize: 13,
                 fontWeight: 500,
                 cursor: 'pointer',
             },
-        }, 'Retry'), catchCount > 1
-            ? createElement('div', { style: { fontSize: 11, color: 'rgba(255,255,255,0.2)' } }, error.message)
-            : null);
+        }, 'Retry'), 
+        // Diagnostic is ALWAYS reachable (#481 ruling: errors must be
+        // visible) — collapsed by default, legible when opened.
+        createElement('details', {
+            style: {
+                marginTop: 8,
+                maxWidth: 320,
+                width: '100%',
+                textAlign: 'left',
+                opacity: 0.65,
+            },
+        }, createElement('summary', { style: { fontSize: 11, cursor: 'pointer' } }, 'Error details'), createElement('pre', {
+            style: {
+                fontSize: 11,
+                fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+                whiteSpace: 'pre-wrap',
+                overflowWrap: 'anywhere',
+                margin: '6px 0 0',
+                maxHeight: 140,
+                overflow: 'auto',
+            },
+        }, error.message)));
     }
 }
 /**
@@ -177,25 +216,66 @@ export async function mountReactRoot(container, opts) {
         }
         // 1. Strip metadata markers (__GGUI_META__ / __GGUI_STREAM_SPEC__).
         const cleaned = stripMarkers(resolved);
-        // 2. Hoist imports above var declarations.
+        // 2. Hoist imports above var declarations. Load-bearing for BOTH
+        //    execution paths: the inline transform places its bindings at
+        //    the import statement's position, so a pre-import statement
+        //    referencing an imported name needs the hoist exactly as the
+        //    real module semantics do.
         const hoisted = hoistImports(cleaned);
-        // 3. Rewrite bare specifiers to data-url shims reading from
-        //    `globalThis.__ggui__`. The __ggui__ registry is installed
-        //    by `runtime.ts::bootSequence` BEFORE any mountReactRoot call
-        //    — see globals.ts docstring on TOCTOU ordering.
-        const rewritten = rewriteImports(hoisted, {
-            mode: 'data-url',
-            gadgetPackages: currentOpts.gadgetPackages,
-        });
-        // 4. Dynamically import the module.
-        const mod = await loadModule(rewritten);
-        // 5. Extract default export (or first function export).
-        const Comp = (mod.default ??
-            Object.values(mod).find((v) => typeof v === 'function'));
-        if (Comp === undefined) {
-            throw new Error('Module does not export a default component');
+        const pick = (mod) => {
+            const Comp = (mod.default ??
+                Object.values(mod).find((v) => typeof v === 'function'));
+            if (Comp === undefined) {
+                throw new Error('Module does not export a default component');
+            }
+            return Comp;
+        };
+        const evaluateInline = () => pick(loadModuleInline(hoisted, {
+            ...(currentOpts.gadgetPackages !== undefined
+                ? { gadgetPackages: currentOpts.gadgetPackages }
+                : {}),
+        }));
+        // Once URL-scheme module loading has been proven blocked in this
+        // document, go straight to inline execution — the CSP verdict
+        // cannot change within the document's lifetime.
+        if (urlModuleLoadBlocked) {
+            return evaluateInline();
+        }
+        try {
+            // 3. Rewrite bare specifiers to data-url shims reading from
+            //    `globalThis.__ggui__`. The __ggui__ registry is installed
+            //    by `runtime.ts::bootSequence` BEFORE any mountReactRoot call
+            //    — see globals.ts docstring on TOCTOU ordering.
+            const rewritten = rewriteImports(hoisted, {
+                mode: 'data-url',
+                gadgetPackages: currentOpts.gadgetPackages,
+            });
+            // 4. Dynamically import the module.
+            const mod = await loadModule(rewritten);
+            // 5. Extract default export (or first function export).
+            return pick(mod);
+        }
+        catch (urlError) {
+            // A host CSP granting only 'unsafe-inline' rejects the blob:/
+            // data: imports above. Attempt the inline classic-script path;
+            // a buggy component fails on both paths, and the original error
+            // is the honest one to surface.
+            try {
+                const Comp = evaluateInline();
+                // Latch the inline path for the rest of the document ONLY on
+                // proven CSP evidence: the known-good probe module must also
+                // fail. A module-specific blob failure (import-shim allowlist
+                // drift) leaves the latch off so the next evaluation gets real
+                // module semantics again.
+                if (!(await probeUrlModuleLoad())) {
+                    urlModuleLoadBlocked = true;
+                }
+                return Comp;
+            }
+            catch {
+                throw urlError;
+            }
         }
-        return Comp;
     }
     function renderTree(opts) {
         const themeCss = opts.themeId

package/dist/registry-subscribe.d.ts

@@ -1,7 +1,7 @@
 import type { AckPayload } from '@ggui-ai/protocol';
 import type { ConnectionStatus } from '@ggui-ai/protocol/transport/websocket';
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import type { ChannelRegistry, RegistryPollingOptions, WsTransportHandle } from '@ggui-ai/live-channel';
+import type { AnyTransportHandle, ChannelLogger, ChannelRegistry, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';
 import { type ProtocolErrorEmitter } from './protocol-error.js';
 import type { ObservabilityEmitter } from './observability.js';
 /**
@@ -12,8 +12,19 @@ import type { ObservabilityEmitter } from './observability.js';
  * render slot.
  */
 export interface RegistrySubscribeHandle {
-    readonly handle: WsTransportHandle;
-    readonly ack: AckPayload;
+    /**
+     * The bound transport. `kind: 'ws'` on trio binds (the FailoverHandle
+     * facade keeps it across demotions); `kind: 'polling'` on trio-less
+     * bridge-only binds — narrow before using the ws-only `send` surface.
+     */
+    readonly handle: AnyTransportHandle;
+    /**
+     * First subscribe ack — present on trio binds only. A trio-less
+     * bridge-only bind has no subscribe handshake (the static seed
+     * already painted; the bridge delivers deltas), so the key is
+     * absent entirely (exact-optional).
+     */
+    readonly ack?: AckPayload;
 }
 /**
  * Caller-provided callbacks. The runtime's `bootSequence` owns the
@@ -90,6 +101,34 @@ export interface ConnectViaRegistryOptions {
      * URL- and shape-agnostic.
      */
     readonly polling?: RegistryPollingOptions;
+    /**
+     * SSE middle-rung descriptor (WS → SSE → polling ladder). Composed
+     * at the runtime layer from `meta.sseUrl` + the shared ladder
+     * cursor — the live-channel is URL- and auth-agnostic. Absent →
+     * two-rung WS→polling ladder (or WS-only when `polling` is also
+     * absent).
+     */
+    readonly sse?: RegistrySseOptions;
+    /**
+     * Bridge-pull terminal-rung descriptor (WS → SSE → polling → bridge
+     * ladder). Same {@link RegistryPollingOptions} shape as `polling`
+     * because bridge-pull IS the polling algorithm on the `fetchBody`
+     * carrier — the event ledger pulled via `ggui_runtime_pull`
+     * `tools/call`s over the host's postMessage bridge instead of an
+     * HTTP URL. Composed at the runtime layer (`buildBridgePolling`
+     * bound to `app.callServerTool` + the shared ladder cursor)
+     * whenever the connected App handle exists; threaded verbatim to
+     * `bind()` like `sse`/`polling`. Absent → the ladder ends at
+     * whichever of the rungs above is armed.
+     */
+    readonly bridge?: RegistryPollingOptions;
+    /**
+     * Diagnostics tap threaded into the live-channel bind — the
+     * transports' own `channel_*` events flow to it. The runtime passes
+     * its telemetry sink's `ChannelLogger` facade here so ladder
+     * behavior on console-less sandboxed hosts reaches the server.
+     */
+    readonly logger?: ChannelLogger;
 }
 /**
  * Open the WS via the registry, send subscribe (composed by the

package/dist/registry-subscribe.js

@@ -146,14 +146,22 @@ export function connectViaRegistry(opts) {
         let seenOpen = false;
         const emitProtocolError = opts.onProtocolError ?? (() => { });
         const emitObserve = opts.onObserve ?? (() => { });
-        // Defense-in-depth — live mode requires both wsUrl + wsToken. The
-        // caller validates this before invoking; reject early with a
-        // typed transport failure if either is missing.
+        // Defense-in-depth — the WS rung requires both wsUrl + wsToken.
+        // A trio-less meta is still connectable when a BRIDGE descriptor
+        // is supplied (#471 round-6 live finding): CSP-jailed MCP-Apps
+        // hosts mount statically with NO trio at all, and the bridge-pull
+        // terminal rung — whose only precondition is the host's tools/call
+        // postMessage bridge — is precisely their subscription. The
+        // registry handles a trio-less bootstrap by starting the ladder at
+        // its tail. Trio-less AND bridge-less remains the typed failure.
         const wsUrl = opts.meta.wsUrl;
         const wsToken = opts.meta.wsToken;
-        if (typeof wsUrl !== 'string' || wsUrl.length === 0 ||
-            typeof wsToken !== 'string' || wsToken.length === 0) {
-            const err = new Error('connectViaRegistry: render-meta missing wsUrl/wsToken — live-mode required');
+        const hasTrio = typeof wsUrl === 'string' &&
+            wsUrl.length > 0 &&
+            typeof wsToken === 'string' &&
+            wsToken.length > 0;
+        if (!hasTrio && opts.bridge === undefined) {
+            const err = new Error('connectViaRegistry: render-meta missing wsUrl/wsToken and no bridge descriptor — nothing to subscribe');
             emitProtocolError(fromTransportFailure('DISCONNECTED', false, err.message));
             reject(err);
             return;
@@ -281,25 +289,40 @@ export function connectViaRegistry(opts) {
                 reject(new Error('connectViaRegistry: transport went to failed state before ack'));
             }
         };
-        const composedUrl = composeWsUrl(wsUrl, wsToken);
         // `bind()` selects the transport (WS for wsUrl+wsToken sessions;
         // the live-channel narrows on its `bootstrap` shape) and starts
         // it. We override `bootstrap.wsUrl` with the composed URL so the
         // registry's WS transport gets the wsToken-threaded variant. The
         // live-channel's `bootstrap` arg is its internal name; the field
-        // on the wire is `wsToken`.
+        // on the wire is `wsToken`. Trio-less (bridge-capable) binds carry
+        // NEITHER key — the registry then starts the ladder at its tail.
         void opts.registry
             .bind({
             bootstrap: {
-                wsUrl: composedUrl,
-                wsToken,
+                ...(hasTrio
+                    ? { wsUrl: composeWsUrl(wsUrl, wsToken), wsToken }
+                    : {}),
                 sessionId: opts.meta.sessionId,
                 appId: opts.meta.appId,
             },
+            ...(opts.logger !== undefined ? { logger: opts.logger } : {}),
             onStatusChange: mappedStatusCallback,
+            ...(opts.sse !== undefined ? { sse: opts.sse } : {}),
             ...(opts.polling !== undefined ? { polling: opts.polling } : {}),
+            ...(opts.bridge !== undefined ? { bridge: opts.bridge } : {}),
         })
             .then((bound) => {
+            if (!hasTrio) {
+                // Bridge-only bind — no subscribe handshake, no ack. The
+                // polling facade reports 'open' immediately (mapped to
+                // 'connected' for the consumer); resolve with the handle
+                // alone and let the ladder deliver deltas.
+                if (!settled) {
+                    settled = true;
+                    resolve({ handle: bound });
+                }
+                return;
+            }
             // bound is `AnyTransportHandle`. Composed URL + wsToken means
             // the registry selected WSTransport — `kind === 'ws'` is the
             // structural invariant. Narrow defensively.

package/dist/render-item.js

@@ -10,7 +10,7 @@
  * `StackRenderer` / `StackRenderContext` orchestrator (a stack-of-N
  * map keyed by item id) was retired along with `StackModel`.
  *
- * The dispatch tree mirrors `@ggui-ai/react::DynamicComponent` +
+ * The dispatch tree mirrors `@ggui-ai/mcp-apps-react::DynamicComponent` +
  * `GguiRender`'s MCP-Apps branch:
  *
  *   - `type === 'mcpApps'` → `mountMcpAppIframe` (vanilla iframe

package/dist/runtime-telemetry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Transport-telemetry sink — the iframe runtime's self-report channel
+ * (`ggui_runtime_telemetry`).
+ *
+ * Why: on sandboxed MCP-Apps hosts (claude.ai's `claudemcpcontent.com`
+ * frames) the console is unreadable from outside and the CSP blocks
+ * every network channel — when the delivery ladder (WS → SSE → polling
+ * → bridge-pull) misbehaves there, the failure is invisible by
+ * construction. This sink batches the ladder's own events and flushes
+ * them over the host's `tools/call` postMessage bridge, the one
+ * carrier a CSP jail cannot block.
+ *
+ * What flows through it:
+ *   - `record()` calls from the boot sequence (path decisions, status
+ *     transitions, doorbell rings);
+ *   - the live-channel's OWN diagnostics via {@link channelLogger} —
+ *     a `ChannelLogger` facade that forwards every
+ *     `channel_failover_swap` / `channel_polling_*` / SSE event the
+ *     transports already emit. Tapping the logger means ZERO new
+ *     instrumentation inside `@ggui-ai/live-channel`.
+ *
+ * Posture: bounded, fire-and-forget, diagnostics-only.
+ *   - Buffer caps at the protocol's per-batch limit; overflow drops
+ *     the OLDEST entries (the tail of a failure story beats its
+ *     preamble).
+ *   - First flush is delayed (~4s) so one batch carries the whole
+ *     boot+ladder story; later flushes throttle.
+ *   - A hard per-session flush cap bounds host load; flush failures
+ *     are swallowed (a diagnostics channel must never cause the
+ *     symptoms it reports).
+ */
+import type { ChannelLogger } from '@ggui-ai/live-channel';
+/** Narrow slice of `App.callServerTool` the sink needs. */
+export type TelemetryCallTool = (args: {
+    name: string;
+    arguments: Record<string, unknown>;
+}) => Promise<unknown>;
+export interface TelemetrySink {
+    /** Append one event; schedules a (throttled) flush. */
+    record(kind: string, detail?: string): void;
+    /**
+     * `ChannelLogger` facade for the live-channel bind — every event the
+     * transports emit lands in the buffer verbatim (event name = kind,
+     * fields JSON = detail).
+     */
+    readonly channelLogger: ChannelLogger;
+    /** Cancel timers; buffered-but-unflushed events are dropped. */
+    dispose(): void;
+}
+export declare function createTelemetrySink(opts: {
+    readonly sessionId: string;
+    readonly callTool: TelemetryCallTool;
+}): TelemetrySink;

package/dist/runtime-telemetry.js

@@ -0,0 +1,74 @@
+import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol';
+const FIRST_FLUSH_DELAY_MS = 4_000;
+const FLUSH_THROTTLE_MS = 8_000;
+const MAX_FLUSHES_PER_SESSION = 12;
+const MAX_DETAIL_CHARS = 500;
+export function createTelemetrySink(opts) {
+    const bootAt = Date.now();
+    const buffer = [];
+    let flushes = 0;
+    let timer = null;
+    let disposed = false;
+    let firstFlushDone = false;
+    const flush = () => {
+        timer = null;
+        if (disposed || buffer.length === 0)
+            return;
+        if (flushes >= MAX_FLUSHES_PER_SESSION)
+            return;
+        flushes += 1;
+        firstFlushDone = true;
+        const events = buffer.splice(0, buffer.length);
+        void opts
+            .callTool({
+            name: 'ggui_runtime_telemetry',
+            arguments: { sessionId: opts.sessionId, events },
+        })
+            .catch(() => {
+            // Swallowed by design — the diagnostics channel must never
+            // cause the failures it exists to report.
+        });
+    };
+    const scheduleFlush = () => {
+        if (disposed || timer !== null)
+            return;
+        if (flushes >= MAX_FLUSHES_PER_SESSION)
+            return;
+        timer = setTimeout(flush, firstFlushDone ? FLUSH_THROTTLE_MS : FIRST_FLUSH_DELAY_MS);
+    };
+    const record = (kind, detail) => {
+        if (disposed)
+            return;
+        if (buffer.length >= RUNTIME_TELEMETRY_MAX_EVENTS)
+            buffer.shift();
+        buffer.push({
+            at: Math.max(0, Date.now() - bootAt),
+            kind: kind.slice(0, 64),
+            ...(detail !== undefined ? { detail: detail.slice(0, MAX_DETAIL_CHARS) } : {}),
+        });
+        scheduleFlush();
+    };
+    const fieldsToDetail = (fields) => {
+        try {
+            return JSON.stringify(fields).slice(0, MAX_DETAIL_CHARS);
+        }
+        catch {
+            return '[unserializable]';
+        }
+    };
+    return {
+        record,
+        channelLogger: {
+            info: (event, fields) => record(event, fieldsToDetail(fields)),
+            warn: (event, fields) => record(event, fieldsToDetail(fields)),
+            debug: (event, fields) => record(event, fieldsToDetail(fields)),
+        },
+        dispose() {
+            disposed = true;
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+        },
+    };
+}