@ggui-ai/iframe-runtime 0.6.3 → 0.8.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './m
 export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, AuthRequiredEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, UiFeedbackEvent, UnknownObservabilityEvent, } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayIncapabilityEvent, UnknownObservabilityEvent, } from './observability.js';
 export { postObservabilityToParent } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/mcp-app-iframe-host.js

@@ -116,7 +116,14 @@ export function mountMcpAppIframe(container, opts) {
                 const result = {
                     protocolVersion: requested,
                     hostInfo: { name: 'ggui-iframe-runtime-embed-host', version: EMBED_HOST_VERSION },
-                    hostCapabilities: {},
+                    // Advertise exactly what the `switch` below implements
+                    // (ggui#440). `serverTools`: the `tools/call` case proxies
+                    // guest tool calls to the MCP server. NOT `message`: there is
+                    // no `ui/message` case here, so a doorbell would be dropped —
+                    // and the runtime now surfaces that to the user rather than
+                    // claiming the gesture reached the agent. If a `ui/message`
+                    // case is ever added, advertise `message` in the same change.
+                    hostCapabilities: { serverTools: {} },
                     hostContext: {
                         locale: opts.locale ??
                             (typeof navigator !== 'undefined' ? navigator.language : 'en-US'),

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.
@@ -260,6 +261,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 +277,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 +294,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

@@ -33,7 +33,7 @@ import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
  *
  * @public
  */
-export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | AuthRequiredEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | UiFeedbackEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -61,57 +61,6 @@ export interface SubscribeFailedEvent {
     readonly reason: string;
     readonly message?: string;
 }
-/**
- * Fired when the server emits a `system` frame with
- * `action: 'auth_required'` — the agent needs the end-user to authorize
- * an OAuth service (Google, Slack, etc.) before its tool call can
- * proceed. The host listens via `<McpAppIframe onObserve>` and renders
- * a consent overlay OUTSIDE the iframe, then redirects the user to
- * `authUrl` to complete the OAuth flow.
- *
- * Observability-only — the wire signal is already fully typed on
- * `@ggui-ai/protocol`'s `SystemPayload` (live-channel.ts). This event is a
- * renderer↔host projection of that payload, not a new protocol surface,
- * matching the vendor-neutral-separation posture of every
- * other `ObservabilityEvent` kind.
- *
- * Fields map 1:1 from `SystemPayload`:
- *   - `provider` ← `serviceId` (canonical identifier the credential
- *     store keys off — e.g., `"google"`, `"slack"`).
- *   - `authUrl` ← `consentUrl` (URL the host opens in a popup / new tab
- *     to initiate the OAuth consent flow).
- *   - `displayName` / `scopes` / `message` are optional hints the host
- *     can surface in the consent overlay; absent means "render with
- *     generic copy".
- *
- * @public
- */
-export interface AuthRequiredEvent {
-    readonly kind: 'auth-required';
-    /**
-     * Canonical identifier of the service needing authorization (e.g.
-     * `"google"`, `"slack"`). Maps to `SystemPayload.serviceId`.
-     */
-    readonly provider: string;
-    /**
-     * URL the host opens in a popup / new tab to initiate the OAuth
-     * consent flow. Maps to `SystemPayload.consentUrl`.
-     */
-    readonly authUrl: string;
-    /**
-     * Human-readable service name (e.g. `"Google"`, `"Slack"`). Optional
-     * — absent when the server doesn't supply one.
-     */
-    readonly displayName?: string;
-    /**
-     * OAuth scopes the agent is requesting. Optional.
-     */
-    readonly scopes?: readonly string[];
-    /**
-     * Human-readable message explaining why access is needed. Optional.
-     */
-    readonly message?: string;
-}
 /**
  * Fired by the channel-transport router when it picks a transport
  * for a `streamSpec[ch].source.tool` channel. Hosts can inspect the
@@ -152,6 +101,50 @@ export interface ChannelTransportResubscribedEvent {
     readonly sessionId: string;
     readonly channelName: string;
 }
+/**
+ * Fired by the channel-transport router when a polling channel's
+ * `tools/call` fails for a reason the router classifies as STRUCTURAL
+ * — the failure will repeat identically until the underlying
+ * condition changes, so spending a full-cadence poll on it is waste.
+ *
+ * The channel drops to a slower probe cadence; it never stops. That
+ * distinction is the fail-safe: recovery is a property of the running
+ * loop, not of an external nudge, so a host that regains the missing
+ * capability sees its channels come back on their own.
+ *
+ * Emitted ONCE per healthy→degraded transition, never per probe tick
+ * — a channel degraded for an hour emits one event, not 120.
+ *
+ * @public
+ */
+export interface ChannelPollDegradedEvent {
+    readonly kind: 'channel-poll-degraded';
+    readonly sessionId: string;
+    readonly channelName: string;
+    /**
+     * What the router classified. `'relay-incapable'` = the runtime has
+     * confirmed this host cannot relay `tools/call` to the MCP server
+     * (see `RelayIncapableError`), so every poll fails before reaching
+     * the transport.
+     */
+    readonly reason: 'relay-incapable';
+    /** Cadence (ms) the channel probes at while degraded. */
+    readonly probeIntervalMs: number;
+}
+/**
+ * Fired by the channel-transport router when a previously-degraded
+ * channel's `tools/call` succeeds again. The channel returns to its
+ * normal cadence. Emitted once per degraded→healthy transition.
+ *
+ * @public
+ */
+export interface ChannelPollRecoveredEvent {
+    readonly kind: 'channel-poll-recovered';
+    readonly sessionId: string;
+    readonly channelName: string;
+    /** Cadence (ms) the channel returns to. */
+    readonly pollIntervalMs: number;
+}
 /**
  * Fired when the end user submits the runtime's in-iframe UI-feedback
  * affordance ("did this generated UI work for you?"). Field semantics
@@ -190,6 +183,37 @@ export interface UiFeedbackEvent {
     /** Tool that produced the render (e.g. `ggui_render`). */
     readonly toolName?: string;
 }
+/**
+ * Fired at the two transition edges of the renderer's
+ * relay-incapability latch — the runtime's confirmed determination
+ * that the host cannot relay `tools/call` to the MCP server:
+ *
+ *   - `'latched'` — a real user gesture just failed relay-shaped (no
+ *     well-formed result envelope came back at all) on a host whose
+ *     captured capability handshake never advertised `serverTools`.
+ *     The runtime now treats relay as confirmed-unavailable: it shows
+ *     one persistent explanation instead of a per-gesture error toast,
+ *     and channel polls fail fast without a transport round-trip.
+ *   - `'cleared'` — a later well-formed result envelope arrived
+ *     (`ok:true` and `ok:false` alike — either proves the host relayed
+ *     the call there and back), so the determination no longer holds;
+ *     per-gesture feedback and channel transport attempts resume.
+ *
+ * Emitted once per edge, never per channel poll tick: repeated failing
+ * gestures while latched emit nothing further, and the router's
+ * fail-fast ticks emit nothing at all — the edges carry the full
+ * information.
+ *
+ * Always emitted via the postMessage-to-parent default — the emission
+ * sites live in module-level gesture-dispatch code outside the boot
+ * graph, so they never flow through an injected `onObserve` sink.
+ *
+ * @public
+ */
+export interface RelayIncapabilityEvent {
+    readonly kind: 'relay-incapability';
+    readonly state: 'latched' | 'cleared';
+}
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.
  * Lets the union stay extensible without forcing protocol-version

package/dist/react-renderer.js

@@ -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.
 // =============================================================================
@@ -177,25 +188,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/relay-incapability.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Relay-incapability failure vocabulary.
+ *
+ * Two modules need to agree on ONE fact: whether a failed
+ * `tools/call` failed because this host structurally cannot relay
+ * calls to the MCP server, or because something transient went wrong
+ * on an otherwise-working relay.
+ *
+ *   - `runtime.ts` is the THROWER. It owns the relay-incapability
+ *     latch (set only after a real user gesture failed relay-shaped
+ *     on a host that never advertised `serverTools`) and throws
+ *     {@link RelayIncapableError} from `channelToolsCall` before
+ *     spending a transport round-trip.
+ *   - `channel-transport.ts` is the CLASSIFIER. Its poll tick reads
+ *     the thrown value to decide between "back off to a probe
+ *     cadence" and "stay quiet, next tick may succeed".
+ *
+ * The vocabulary lives in its own module rather than in either party
+ * because `runtime.ts` already imports `channel-transport.ts` — a
+ * reverse import would close a cycle. Naming it for the CONCEPT
+ * (relay incapability) rather than for either party keeps the
+ * dependency direction obvious.
+ *
+ * Classification is by type, never by message string: a thrown
+ * `Error` whose text happens to mention relaying is NOT a structural
+ * failure, and re-wording a message must never silently re-classify
+ * a channel.
+ */
+/**
+ * Canonical code carried by {@link RelayIncapableError}.
+ *
+ * Package-internal. Nothing in this module reaches a host: it is not
+ * re-exported from `index.ts`, so an embedding app can neither catch
+ * this class nor read this code. The host-facing surface for the same
+ * information is the `channel-poll-degraded` / `channel-poll-recovered`
+ * observability pair, which IS exported.
+ */
+export declare const RELAY_INCAPABLE = "RELAY_INCAPABLE";
+/**
+ * Thrown when the runtime has CONFIRMED (not merely suspected) that
+ * the surrounding host cannot relay `tools/call` to the MCP server,
+ * so an attempt would be spent for a guaranteed failure.
+ *
+ * "Confirmed" is load-bearing. Absence of an advertised `serverTools`
+ * capability is NOT confirmation — plenty of hosts under-advertise
+ * and relay perfectly well. Only a real gesture that failed
+ * relay-shaped sets the latch this error reports, and any later
+ * well-formed result envelope clears it.
+ *
+ * Consumers MUST classify by `instanceof` (or by `code`), never by
+ * parsing {@link Error.message}.
+ */
+export declare class RelayIncapableError extends Error {
+    /** Canonical classification code. */
+    readonly code: typeof RELAY_INCAPABLE;
+    constructor();
+}
+/**
+ * Type guard for the structural-failure class. Thrower and classifier
+ * are bundled together into one iframe artifact, so `instanceof` is
+ * exact here — there is no module-realm boundary between them to
+ * defend against.
+ */
+export declare function isRelayIncapableError(err: unknown): err is RelayIncapableError;

package/dist/relay-incapability.js

@@ -0,0 +1,69 @@
+/**
+ * Relay-incapability failure vocabulary.
+ *
+ * Two modules need to agree on ONE fact: whether a failed
+ * `tools/call` failed because this host structurally cannot relay
+ * calls to the MCP server, or because something transient went wrong
+ * on an otherwise-working relay.
+ *
+ *   - `runtime.ts` is the THROWER. It owns the relay-incapability
+ *     latch (set only after a real user gesture failed relay-shaped
+ *     on a host that never advertised `serverTools`) and throws
+ *     {@link RelayIncapableError} from `channelToolsCall` before
+ *     spending a transport round-trip.
+ *   - `channel-transport.ts` is the CLASSIFIER. Its poll tick reads
+ *     the thrown value to decide between "back off to a probe
+ *     cadence" and "stay quiet, next tick may succeed".
+ *
+ * The vocabulary lives in its own module rather than in either party
+ * because `runtime.ts` already imports `channel-transport.ts` — a
+ * reverse import would close a cycle. Naming it for the CONCEPT
+ * (relay incapability) rather than for either party keeps the
+ * dependency direction obvious.
+ *
+ * Classification is by type, never by message string: a thrown
+ * `Error` whose text happens to mention relaying is NOT a structural
+ * failure, and re-wording a message must never silently re-classify
+ * a channel.
+ */
+/**
+ * Canonical code carried by {@link RelayIncapableError}.
+ *
+ * Package-internal. Nothing in this module reaches a host: it is not
+ * re-exported from `index.ts`, so an embedding app can neither catch
+ * this class nor read this code. The host-facing surface for the same
+ * information is the `channel-poll-degraded` / `channel-poll-recovered`
+ * observability pair, which IS exported.
+ */
+export const RELAY_INCAPABLE = 'RELAY_INCAPABLE';
+/**
+ * Thrown when the runtime has CONFIRMED (not merely suspected) that
+ * the surrounding host cannot relay `tools/call` to the MCP server,
+ * so an attempt would be spent for a guaranteed failure.
+ *
+ * "Confirmed" is load-bearing. Absence of an advertised `serverTools`
+ * capability is NOT confirmation — plenty of hosts under-advertise
+ * and relay perfectly well. Only a real gesture that failed
+ * relay-shaped sets the latch this error reports, and any later
+ * well-formed result envelope clears it.
+ *
+ * Consumers MUST classify by `instanceof` (or by `code`), never by
+ * parsing {@link Error.message}.
+ */
+export class RelayIncapableError extends Error {
+    /** Canonical classification code. */
+    code = RELAY_INCAPABLE;
+    constructor() {
+        super('tools/call unavailable: host did not advertise serverTools');
+        this.name = 'RelayIncapableError';
+    }
+}
+/**
+ * Type guard for the structural-failure class. Thrower and classifier
+ * are bundled together into one iframe artifact, so `instanceof` is
+ * exact here — there is no module-realm boundary between them to
+ * defend against.
+ */
+export function isRelayIncapableError(err) {
+    return err instanceof RelayIncapableError;
+}