@ggui-ai/iframe-runtime 0.8.0 → 0.10.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

@@ -30,6 +30,19 @@ export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGgui
  * so the runtime can mount without any postMessage round-trip.
  */
 export declare function parseMetaFromGlobal(): McpAppAiGguiMetaParseResult;
+/**
+ * The `ui://ggui/render/…` LOCATOR a tool result publishes when a server
+ * runs the read-plane-only posture (`withholdResultMeta`, guuey#209 C3 /
+ * ggui#537): the bootstrap material is absent, but the view's durable
+ * identity rides `structuredContent.resourceUri` (ggui-aware hosts) and
+ * the spec-canonical `_meta.ui.resourceUri` (MCP Apps hosts) — same
+ * value, either slot. The runtime resolves such a result through the
+ * read-plane door (`app.readServerResource` → the per-render
+ * self-contained shell → its inlined envelope). `null` for anything else
+ * — a result that carries the slice inline never needs this, and a
+ * result with neither is not a view.
+ */
+export declare function extractLocatorFromToolResult(params: unknown): string | null;
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
  * postMessage params payload. `params` is a `CallToolResult` per the

package/dist/meta-parse.js

@@ -239,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
@@ -251,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
@@ -261,6 +274,11 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(meta.codeUrl !== undefined ? { codeUrl: meta.codeUrl } : {}),
         ...(meta.codeHash !== undefined ? { codeHash: meta.codeHash } : {}),
+        // Strict-CSP module-variant twin (ggui#522 slice 2). The protocol
+        // parser already enforces the with-a-raw-carrier pairing.
+        ...(meta.codeModuleUrl !== undefined
+            ? { codeModuleUrl: meta.codeModuleUrl }
+            : {}),
         ...(meta.codeB64 !== undefined ? { codeB64: meta.codeB64 } : {}),
         ...(meta.kind !== undefined ? { kind: meta.kind } : {}),
     };
@@ -336,6 +354,29 @@ export function parseMetaFromGlobal() {
     }
     return validateMeta(parsed.meta);
 }
+/**
+ * The `ui://ggui/render/…` LOCATOR a tool result publishes when a server
+ * runs the read-plane-only posture (`withholdResultMeta`, guuey#209 C3 /
+ * ggui#537): the bootstrap material is absent, but the view's durable
+ * identity rides `structuredContent.resourceUri` (ggui-aware hosts) and
+ * the spec-canonical `_meta.ui.resourceUri` (MCP Apps hosts) — same
+ * value, either slot. The runtime resolves such a result through the
+ * read-plane door (`app.readServerResource` → the per-render
+ * self-contained shell → its inlined envelope). `null` for anything else
+ * — a result that carries the slice inline never needs this, and a
+ * result with neither is not a view.
+ */
+export function extractLocatorFromToolResult(params) {
+    if (!isPlainObject(params))
+        return null;
+    const sc = params['structuredContent'];
+    const fromStructured = isPlainObject(sc) && typeof sc['resourceUri'] === 'string' ? sc['resourceUri'] : null;
+    const meta = params['_meta'];
+    const ui = isPlainObject(meta) ? meta['ui'] : undefined;
+    const fromUi = isPlainObject(ui) && typeof ui['resourceUri'] === 'string' ? ui['resourceUri'] : null;
+    const uri = fromStructured ?? fromUi;
+    return uri !== null && uri.startsWith('ui://ggui/render/') ? uri : null;
+}
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
  * postMessage params payload. `params` is a `CallToolResult` per the

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
@@ -41,6 +41,18 @@ export interface ReactRootMountOptions {
         readonly id?: string;
         readonly componentCode: string;
         readonly props?: Record<string, unknown>;
+        /**
+         * Strict-CSP module variant of `componentCode` (ggui#522 slice 2):
+         * a server-side import-rewritten twin of the SAME bytes, directly
+         * `import()`able (its imports resolve to static shim assets on an
+         * allowed origin — no `data:`, no `blob:`, no eval). Tried FIRST;
+         * any failure falls through to the blob/inline ladder on the raw
+         * bytes. Callers MUST pass it only when it names exactly these
+         * `componentCode` bytes — a stale variant would paint the WRONG
+         * component, not fail (the runtime's dispatcher guards this by
+         * attaching it to the inline seed only).
+         */
+        readonly codeModuleUrl?: string;
     };
     readonly themeId?: string;
     /**

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
@@ -91,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', {
@@ -109,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',
                 },
@@ -133,6 +139,7 @@ class RcrErrorBoundary extends Component {
                 gap: 12,
                 textAlign: 'center',
                 fontFamily: FONT,
+                color: 'var(--ggui-color-onSurface, inherit)',
             },
         }, createElement('div', {
             style: {
@@ -140,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)));
     }
 }
 /**
@@ -207,6 +235,30 @@ export async function mountReactRoot(container, opts) {
                 ? { gadgetPackages: currentOpts.gadgetPackages }
                 : {}),
         }));
+        // Asset-module path (ggui#522 slice 2) — FIRST when the mount
+        // carries the strict-CSP variant URL: a plain https module import,
+        // legal under `script-src` origins alone, no scheme sources, no
+        // eval. Under a strict host CSP it is the ONLY path that works;
+        // under a permissive one it costs a CDN round-trip on cold cache
+        // and nothing on warm (the URL is immutable). Any failure — CSP
+        // block, network fault, a 404 from a redeployed variant family —
+        // falls through to the raw-bytes ladder below. No document latch
+        // on failure: unlike the per-evaluation blob probe, this branch
+        // runs only when componentCode changes (rare — usually once per
+        // mount), so the retry cost is one fetch, and the failure classes
+        // (transient network vs permanent CSP) are indistinguishable in
+        // the import error anyway.
+        const moduleUrl = currentOpts.render.codeModuleUrl;
+        if (moduleUrl !== undefined) {
+            try {
+                const mod = (await import(
+                /* webpackIgnore: true */ /* @vite-ignore */ moduleUrl));
+                return pick(mod);
+            }
+            catch {
+                // Fall through — the raw bytes are the authoritative carrier.
+            }
+        }
         // 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.
@@ -250,9 +302,25 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        const themeCss = opts.themeId
+        let themeCss = opts.themeId
             ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
             : getScopedCssTokens(scopeClass, opts.themeMode);
+        if (opts.appTheme) {
+            const decls = Object.entries(opts.appTheme.cssVariables)
+                .map(([k, v]) => `${k}: ${v};`)
+                .join('');
+            // The overlay must be merged HERE, into the scoped style that
+            // mounts INSIDE the scope div — the `:root` append below is
+            // cascade-dead for tree content: the in-scope block sits later
+            // in document order than anything in `<head>`, so at equal
+            // specificity the base scoped tokens always win over a head-level
+            // override (browser-verified in rnd/gen-ui/beauty/experiments/001,
+            // the probe sequence that found this). Appended AFTER the base
+            // block and BEFORE `cssOverrides`, so: base < operator overlay <
+            // explicit overrides. Values validated injection-safe upstream
+            // (same guarantee the `:root` append cites).
+            themeCss += `.${scopeClass}{${decls}}`;
+        }
         // Also inject theme CSS at `:root` on `document.head`. The scoped
         // injection above isolates token resolution to the React tree, but
         // the embedding shell's body styles (font-family, color, background)
@@ -270,10 +338,12 @@ export async function mountReactRoot(container, opts) {
                 const decls = Object.entries(opts.appTheme.cssVariables)
                     .map(([k, v]) => `${k}: ${v};`)
                     .join('');
-                // Appended AFTER the base block → the per-app overlay wins; it is a
-                // partial set (unset vars keep their token defaults). CSS custom
-                // properties at :root inherit into the scoped React tree, so this
-                // alone is sufficient for the component to resolve `var(--ggui-*)`.
+                // BODY-CHROME ONLY. This `:root` append themes the embedding
+                // shell's body styles (font/color/background outside the scope
+                // div). It does NOT reach tree content — the scoped in-body
+                // token block wins by document order (see the scoped merge in
+                // `renderTree`, and rnd/gen-ui/beauty/experiments/001 for the
+                // probe that falsified the old "inherits into the tree" claim).
                 // Values were validated injection-safe upstream (write-side
                 // `appThemeSchema` + the wire parser re-validates), so the
                 // string-join here is safe — do NOT re-sanitize.

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.d.ts

@@ -29,6 +29,15 @@ export interface RenderItemOptions {
      * this. STDLIB `@ggui-ai/gadgets` is always rewritten regardless.
      */
     readonly gadgetPackages?: readonly string[];
+    /**
+     * Strict-CSP module variant of the render's `componentCode`
+     * (ggui#522 slice 2), forwarded to
+     * {@link ReactRootMountOptions.render.codeModuleUrl}. The CALLER
+     * owns the bytes↔URL association: pass it only when it names
+     * exactly `render.componentCode`'s bytes (the runtime attaches it
+     * to the inline seed mount only — a WS-delivered render drops it).
+     */
+    readonly codeModuleUrl?: string;
     /** Theme id passed to ReactComponentRenderer for scoped CSS. */
     readonly themeId?: string;
     /**

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
@@ -169,6 +169,9 @@ export async function mountRender(container, opts) {
                 ...(render.props !== undefined
                     ? { props: render.props }
                     : {}),
+                ...(currentOpts.codeModuleUrl !== undefined
+                    ? { codeModuleUrl: currentOpts.codeModuleUrl }
+                    : {}),
             },
             ...(gadgetPackages !== undefined ? { gadgetPackages } : {}),
             ...(currentOpts.themeId !== undefined ? { themeId: currentOpts.themeId } : {}),
@@ -234,6 +237,9 @@ export async function mountRender(container, opts) {
                         ...(render.props !== undefined
                             ? { props: render.props }
                             : {}),
+                        ...(next.codeModuleUrl !== undefined
+                            ? { codeModuleUrl: next.codeModuleUrl }
+                            : {}),
                     },
                     ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
                     ...(next.themeMode !== undefined ? { themeMode: next.themeMode } : {}),

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;
+            }
+        },
+    };
+}