@ggui-ai/iframe-runtime 0.1.0-rc.1

package/dist/system-cards/host-detect.js

@@ -0,0 +1,108 @@
+/**
+ * Host environment detection — figure out which embedder is hosting
+ * the iframe-runtime so system cards can adapt their theming.
+ *
+ * Two signals matter:
+ *
+ *   - **Is this Claude?** (claude.ai web's `claudemcpcontent.com`
+ *     sandbox proxy, or Claude Desktop's local iframe). When yes,
+ *     system cards should drop their own background so the host's
+ *     chat-bubble surface shows through, and use Claude-friendly
+ *     accents.
+ *   - **What color scheme does the user prefer?** Read from
+ *     `prefers-color-scheme`. Subscribed via `matchMedia` so the card
+ *     re-themes live when the user toggles their OS appearance.
+ *
+ * Both helpers are SSR-safe (return sensible defaults when `window`
+ * is undefined).
+ */
+import * as React from 'react';
+/**
+ * Best-effort detection that we're embedded inside Claude (web or
+ * desktop). Heuristics:
+ *
+ *   1. Hostname endsWith `claudemcpcontent.com` → claude.ai web.
+ *      claude.ai loads the runtime through this sandbox proxy
+ *      origin, so the iframe's own location lands here.
+ *   2. Document referrer contains `claude.ai` → loaded from the
+ *      claude.ai chat surface (covers cases where the runtime
+ *      iframe inherits the parent origin via srcdoc).
+ *   3. Hostname/UA contains `claude` (case-insensitive) → covers
+ *      Claude Desktop's `desktop.claude.ai` / similar.
+ *
+ * Returns `false` when `window` is undefined (SSR / Node test
+ * environments) — the caller can default to a non-Claude theme.
+ *
+ * @public
+ */
+export function isInsideClaude() {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        const host = window.location?.hostname ?? '';
+        if (host.endsWith('claudemcpcontent.com'))
+            return true;
+        if (/(^|\.)claude\.ai$/i.test(host))
+            return true;
+        if (/claude/i.test(host))
+            return true;
+        const referrer = typeof document !== 'undefined' ? document.referrer : '';
+        if (/claude\.ai/i.test(referrer))
+            return true;
+        const ua = typeof navigator !== 'undefined' ? navigator.userAgent : '';
+        if (/Claude/.test(ua))
+            return true;
+    }
+    catch {
+        /* cross-origin frame access denied / malformed location — fall through */
+    }
+    return false;
+}
+/**
+ * React hook returning the user's preferred color scheme. Listens to
+ * the `prefers-color-scheme` media query so the card re-themes live
+ * when the user toggles between light and dark in their OS / browser
+ * settings.
+ *
+ * Defaults to `'light'` when `window.matchMedia` is unavailable
+ * (older runtimes, SSR pre-paint).
+ *
+ * @public
+ */
+export function useColorScheme() {
+    const getInitial = React.useCallback(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return 'light';
+        }
+        return window.matchMedia('(prefers-color-scheme: dark)').matches
+            ? 'dark'
+            : 'light';
+    }, []);
+    const [scheme, setScheme] = React.useState(getInitial);
+    React.useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return undefined;
+        }
+        const mql = window.matchMedia('(prefers-color-scheme: dark)');
+        const handler = (e) => {
+            setScheme(e.matches ? 'dark' : 'light');
+        };
+        // Both `addEventListener` (modern) and `addListener` (Safari ≤13)
+        // — defensive in case the runtime ships in a webview that hasn't
+        // updated its MediaQueryList implementation.
+        if (typeof mql.addEventListener === 'function') {
+            mql.addEventListener('change', handler);
+            return () => {
+                mql.removeEventListener('change', handler);
+            };
+        }
+        // Legacy fallback intentionally cast through unknown — older lib.dom
+        // typings expose `addListener` only on the deprecated branch.
+        const legacy = mql;
+        legacy.addListener(handler);
+        return () => {
+            legacy.removeListener(handler);
+        };
+    }, []);
+    return scheme;
+}

package/dist/system-cards/host-intents.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host-intents — request actions from the embedding host (parent
+ * window) that the sandboxed iframe cannot perform itself.
+ *
+ * The MCP Apps spec (SEP-1865) defines `ui/notifications/*` and
+ * `ui/request/*` namespaces for iframe→host communication. This
+ * module sends well-formed requests for the actions the no-
+ * credentials card and other system cards need (open external URL,
+ * etc.), and falls back gracefully when the host doesn't implement
+ * the request.
+ *
+ * Design posture:
+ *
+ *   - **All-strategies-fire-in-parallel.** Most MCP hosts ignore
+ *     methods they don't implement. Sending three speculative
+ *     requests costs three postMessages — all of which are no-ops
+ *     to a host that doesn't recognize them. Whichever the host
+ *     honors first wins.
+ *
+ *   - **Always include a clipboard fallback.** Clipboard write is
+ *     the only mechanism that works in every sandbox without any
+ *     host cooperation. Strategies are layered: try popup, try
+ *     anchor, try postMessage; clipboard is the floor.
+ *
+ *   - **Observable outcome.** Caller gets a discriminated result
+ *     `{outcome, mechanism}` so the UI can show "opened" vs
+ *     "copied" vs "user-select-only" with confident copy.
+ */
+/**
+ * Request the host open a URL in the user's real browser tab.
+ *
+ * In claudemcpcontent.com (claude.ai's MCP Apps sandbox), the iframe
+ * is sandboxed without `allow-popups` AND `connect-src 'self'` blocks
+ * fetches to other origins, so neither `window.open(url)` nor
+ * `<a target="_blank">` succeed. This helper:
+ *
+ *   1. Tries `window.open(url, '_blank', 'noopener,noreferrer')` —
+ *      works on hosts without sandbox restrictions (console, web
+ *      embed, desktop with permissive iframe, etc.).
+ *   2. Programmatic anchor click — some hosts trap this differently
+ *      from `window.open`; cheap to try.
+ *   3. postMessage `ui/request/open-url` to parent — speculative but
+ *      canonical. If/when MCP hosts implement an open-url request
+ *      method (likely a v2 of the spec), this is the form they'll
+ *      use.
+ *   4. postMessage `tools/call` requesting an `open_url` tool — if
+ *      the host exposes `open_url` as a registered tool, the iframe
+ *      can request its invocation. Stretch path; cheap to attempt.
+ *   5. `navigator.clipboard.writeText(url)` — guaranteed-to-work
+ *      fallback. Even if every other mechanism is blocked, the
+ *      clipboard write executes synchronously in the user-gesture
+ *      context and is permitted in every sandbox we've tested.
+ *
+ * The return value reflects what we *think* happened — strategy 1
+ * is observable (returns null when blocked); strategies 2–4 we
+ * fire and forget (no host has documented a reply contract). The
+ * clipboard outcome is the most reliable signal because it
+ * resolves a Promise we can `await`.
+ *
+ * @public
+ */
+export declare function requestOpenUrl(url: string): Promise<RequestOpenUrlResult>;
+/**
+ * Outcome of {@link requestOpenUrl}.
+ *
+ *   - `opened` — `window.open` returned a non-null window. Best-
+ *     effort signal that a tab/popup was created. UI should say
+ *     "Opened in browser ✓" or similar.
+ *   - `copied` — popup was blocked, but clipboard write succeeded.
+ *     UI should say "URL copied — paste in your browser address bar"
+ *     and keep the URL block visible for confirmation.
+ *   - `unsupported` — every mechanism failed. UI must surface the
+ *     URL prominently with `user-select: all` so the user can
+ *     long-press / triple-click + copy manually.
+ */
+export type RequestOpenUrlResult = {
+    readonly outcome: 'opened';
+    readonly mechanism: 'window.open';
+} | {
+    readonly outcome: 'copied';
+    readonly mechanism: 'clipboard';
+} | {
+    readonly outcome: 'unsupported';
+    readonly mechanism: null;
+};

package/dist/system-cards/host-intents.js

@@ -0,0 +1,170 @@
+/**
+ * Host-intents — request actions from the embedding host (parent
+ * window) that the sandboxed iframe cannot perform itself.
+ *
+ * The MCP Apps spec (SEP-1865) defines `ui/notifications/*` and
+ * `ui/request/*` namespaces for iframe→host communication. This
+ * module sends well-formed requests for the actions the no-
+ * credentials card and other system cards need (open external URL,
+ * etc.), and falls back gracefully when the host doesn't implement
+ * the request.
+ *
+ * Design posture:
+ *
+ *   - **All-strategies-fire-in-parallel.** Most MCP hosts ignore
+ *     methods they don't implement. Sending three speculative
+ *     requests costs three postMessages — all of which are no-ops
+ *     to a host that doesn't recognize them. Whichever the host
+ *     honors first wins.
+ *
+ *   - **Always include a clipboard fallback.** Clipboard write is
+ *     the only mechanism that works in every sandbox without any
+ *     host cooperation. Strategies are layered: try popup, try
+ *     anchor, try postMessage; clipboard is the floor.
+ *
+ *   - **Observable outcome.** Caller gets a discriminated result
+ *     `{outcome, mechanism}` so the UI can show "opened" vs
+ *     "copied" vs "user-select-only" with confident copy.
+ */
+/**
+ * Request the host open a URL in the user's real browser tab.
+ *
+ * In claudemcpcontent.com (claude.ai's MCP Apps sandbox), the iframe
+ * is sandboxed without `allow-popups` AND `connect-src 'self'` blocks
+ * fetches to other origins, so neither `window.open(url)` nor
+ * `<a target="_blank">` succeed. This helper:
+ *
+ *   1. Tries `window.open(url, '_blank', 'noopener,noreferrer')` —
+ *      works on hosts without sandbox restrictions (console, web
+ *      embed, desktop with permissive iframe, etc.).
+ *   2. Programmatic anchor click — some hosts trap this differently
+ *      from `window.open`; cheap to try.
+ *   3. postMessage `ui/request/open-url` to parent — speculative but
+ *      canonical. If/when MCP hosts implement an open-url request
+ *      method (likely a v2 of the spec), this is the form they'll
+ *      use.
+ *   4. postMessage `tools/call` requesting an `open_url` tool — if
+ *      the host exposes `open_url` as a registered tool, the iframe
+ *      can request its invocation. Stretch path; cheap to attempt.
+ *   5. `navigator.clipboard.writeText(url)` — guaranteed-to-work
+ *      fallback. Even if every other mechanism is blocked, the
+ *      clipboard write executes synchronously in the user-gesture
+ *      context and is permitted in every sandbox we've tested.
+ *
+ * The return value reflects what we *think* happened — strategy 1
+ * is observable (returns null when blocked); strategies 2–4 we
+ * fire and forget (no host has documented a reply contract). The
+ * clipboard outcome is the most reliable signal because it
+ * resolves a Promise we can `await`.
+ *
+ * @public
+ */
+export async function requestOpenUrl(url) {
+    if (typeof window === 'undefined') {
+        return { outcome: 'unsupported', mechanism: null };
+    }
+    // 1. window.open — observable. `null` return == popup-blocked /
+    //    sandbox-blocked. A non-null window object means the browser
+    //    initiated a tab/window (we can't actually verify the user
+    //    sees it, but absence of null is a strong positive signal).
+    let openedWindow = null;
+    try {
+        openedWindow = window.open(url, '_blank', 'noopener,noreferrer');
+    }
+    catch {
+        openedWindow = null;
+    }
+    // 2. Programmatic anchor click. Same iframe-sandbox limits apply,
+    //    but some mobile WebViews (notably iOS Safari embedded as
+    //    SFSafariViewController) trap anchor.click() differently from
+    //    window.open. Cheap to try; no observable signal.
+    try {
+        const anchor = document.createElement('a');
+        anchor.href = url;
+        anchor.target = '_blank';
+        anchor.rel = 'noopener noreferrer';
+        anchor.style.display = 'none';
+        document.body.appendChild(anchor);
+        anchor.click();
+        document.body.removeChild(anchor);
+    }
+    catch {
+        // Anchor strategy failed — fall through.
+    }
+    // 3. postMessage `ui/request/open-url`. Speculative — no MCP host
+    //    has shipped this yet, but it's the canonical request shape
+    //    a future host should implement. Sending it is harmless: a
+    //    host that doesn't recognize the method ignores the message.
+    //    We don't await a reply because there's no documented
+    //    response contract; if a host ships one, future versions of
+    //    this helper can listen for `ui/responses/open-url`.
+    try {
+        window.parent.postMessage({
+            jsonrpc: '2.0',
+            method: 'ui/request/open-url',
+            params: { url },
+        }, '*');
+    }
+    catch {
+        /* parent detached / sandboxed */
+    }
+    // 4. postMessage `tools/call` → `open_url`. Some hosts model
+    //    "request the user's browser to open a URL" as a registered
+    //    tool the iframe can invoke. Cheap probe; harmless when the
+    //    tool isn't registered.
+    try {
+        window.parent.postMessage({
+            jsonrpc: '2.0',
+            id: Math.floor(Math.random() * 1e9),
+            method: 'tools/call',
+            params: { name: 'open_url', arguments: { url } },
+        }, '*');
+    }
+    catch {
+        /* parent detached / sandboxed */
+    }
+    // 5. Clipboard fallback — guaranteed to work in every host that
+    //    grants `clipboard-write` (which the MCP Apps default
+    //    permissions-policy includes). The user-gesture context the
+    //    click came in on is exactly what `writeText` requires.
+    //
+    //    Timeout via Promise.race: in some sandbox environments
+    //    (headless browsers without a real clipboard, MCP hosts that
+    //    don't grant clipboard-write but never reject — they just
+    //    hang the Promise), `writeText` returns a Promise that
+    //    NEVER resolves or rejects. Without a timeout the whole
+    //    helper hangs forever and the CTA gets stuck on "Opening…".
+    //    1.5s is generous enough for a real clipboard write
+    //    (microsecond-fast in normal browsers) yet short enough
+    //    that the user doesn't perceive a hang.
+    let clipboardCopied = false;
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+        const CLIPBOARD_TIMEOUT_MS = 1500;
+        try {
+            await Promise.race([
+                navigator.clipboard.writeText(url).then(() => {
+                    clipboardCopied = true;
+                }, () => {
+                    clipboardCopied = false;
+                }),
+                new Promise((resolve) => setTimeout(resolve, CLIPBOARD_TIMEOUT_MS)),
+            ]);
+        }
+        catch {
+            clipboardCopied = false;
+        }
+    }
+    // Decide the outcome. Priority:
+    //   - If window.open returned a non-null window, claim 'opened'
+    //     (highest-confidence observable signal).
+    //   - Else if clipboard succeeded, 'copied' (the fallback worked).
+    //   - Else 'unsupported' (user must long-press / triple-click the
+    //     URL block manually).
+    if (openedWindow !== null) {
+        return { outcome: 'opened', mechanism: 'window.open' };
+    }
+    if (clipboardCopied) {
+        return { outcome: 'copied', mechanism: 'clipboard' };
+    }
+    return { outcome: 'unsupported', mechanism: null };
+}

package/dist/system-cards/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * System-card registry.
+ *
+ * Central mapping from `SystemStackItem.kind` (a stable wire string)
+ * to a real React component bundled inside the iframe-runtime. The
+ * runtime's self-contained boot path looks up the kind here when it
+ * sees a stack item with `type: 'system'`. Unknown kinds fall through
+ * to {@link UnknownSystemCard} so an old runtime + new server still
+ * surfaces something visible (vs. a blank iframe).
+ *
+ * Adding a new system card:
+ *
+ *   1. Author `MyNewCard.tsx` in this directory.
+ *   2. Add an entry to {@link SYSTEM_CARD_REGISTRY} below.
+ *   3. (Optional) Add the new kind string to
+ *      `SystemStackItemKind` in `@ggui-ai/protocol` for IDE autocomplete.
+ */
+import * as React from 'react';
+import { NoCredentialsCard, type NoCredentialsCardProps } from './NoCredentialsCard.js';
+import { ProtocolProbeCard, type ProtocolProbeCardProps } from './ProtocolProbeCard.js';
+/**
+ * Generic typed-component shape for the registry. Each entry takes a
+ * loosely-typed `Record<string, unknown>` (the wire `props`) and is
+ * responsible for narrowing its own props internally — the runtime
+ * does NOT validate against the JSX prop shape because the wire is
+ * versioned independently of the bundle.
+ */
+export type SystemCardComponent = React.ComponentType<Record<string, unknown>>;
+/**
+ * Registered system-card kinds. Keep keys aligned with
+ * `SystemStackItemKind` in `@ggui-ai/protocol` so wire + bundle stay
+ * in sync. New kinds added without a registry entry render as
+ * {@link UnknownSystemCard}.
+ */
+export declare const SYSTEM_CARD_REGISTRY: Record<string, SystemCardComponent>;
+/**
+ * Resolve a registered component by kind, or the fallback when the
+ * kind is unknown. Always returns a renderable React element.
+ */
+export declare function renderSystemCard(kind: string, props: Record<string, unknown>): React.ReactElement;
+/**
+ * Top-level mount component the runtime renders for system stack
+ * items. Wraps the resolved card in a {@link ThemeProvider} so design
+ * tokens (`var(--ggui-*)`) resolve at `:root` even though the host's
+ * shell HTML doesn't pre-stamp them. Idempotent across remounts —
+ * shares the `ggui-theme-vars` style id with the rest of the design
+ * system, last writer wins.
+ *
+ * Adapts to the embedding host:
+ *
+ *   - **Inside Claude** (claude.ai web's `claudemcpcontent.com` or
+ *     Claude Desktop): drops the body background to `transparent` so
+ *     the chat-bubble surface shows through, and follows the user's
+ *     OS-level `prefers-color-scheme`. The card's own surfaces stay
+ *     opaque so the content remains readable on either bubble color.
+ *   - **Anywhere else**: lightTheme + opaque white background — the
+ *     historical default, suitable for stand-alone preview iframes
+ *     and console inspectors.
+ *
+ * Theme choice re-runs live: if the user toggles dark mode in their
+ * OS while the card is mounted, `useColorScheme` updates and we
+ * re-emit the matching theme's CSS variables.
+ */
+export declare function SystemCardHost({ kind, props, themeId: _themeId, }: {
+    kind: string;
+    props: Record<string, unknown>;
+    themeId?: string | undefined;
+}): React.ReactElement;
+export { NoCredentialsCard, ProtocolProbeCard };
+export type { NoCredentialsCardProps, ProtocolProbeCardProps };

package/dist/system-cards/index.js

@@ -0,0 +1,134 @@
+/**
+ * System-card registry.
+ *
+ * Central mapping from `SystemStackItem.kind` (a stable wire string)
+ * to a real React component bundled inside the iframe-runtime. The
+ * runtime's self-contained boot path looks up the kind here when it
+ * sees a stack item with `type: 'system'`. Unknown kinds fall through
+ * to {@link UnknownSystemCard} so an old runtime + new server still
+ * surfaces something visible (vs. a blank iframe).
+ *
+ * Adding a new system card:
+ *
+ *   1. Author `MyNewCard.tsx` in this directory.
+ *   2. Add an entry to {@link SYSTEM_CARD_REGISTRY} below.
+ *   3. (Optional) Add the new kind string to
+ *      `SystemStackItemKind` in `@ggui-ai/protocol` for IDE autocomplete.
+ */
+import * as React from 'react';
+import { ThemeProvider, lightTheme, darkTheme } from '@ggui-ai/design/themes';
+import { NoCredentialsCard, } from './NoCredentialsCard.js';
+import { ProtocolProbeCard, } from './ProtocolProbeCard.js';
+import { isInsideClaude, useColorScheme } from './host-detect.js';
+/**
+ * Wrap a strongly-typed card component in a loosely-typed entry the
+ * registry can store uniformly. Each card narrows its own props out of
+ * the bag — runtime cost is negligible (a property read + typeof
+ * checks).
+ */
+function entry(Component, narrow) {
+    return function SystemCardEntry(props) {
+        // The narrowed shape is the component's actual prop type — cast
+        // through `unknown` because React's typed `createElement` overloads
+        // can't see through the registry's loose `Record<string, unknown>`
+        // surface.
+        const Comp = Component;
+        const narrowed = narrow(props);
+        return React.createElement(Comp, narrowed);
+    };
+}
+/**
+ * Fallback card rendered when the runtime sees a `kind` it doesn't
+ * have a registered component for — typically because the server is
+ * running a newer protocol version. Surfaces the kind + raw props so
+ * the user can at least file a useful bug report.
+ */
+function UnknownSystemCard({ kind, props, }) {
+    return React.createElement('div', {
+        style: {
+            padding: '16px',
+            border: '1px solid var(--ggui-color-outlineVariant, #e4e4e7)',
+            borderRadius: 'var(--ggui-shape-radius-md, 10px)',
+            fontFamily: 'var(--ggui-font-family-sans, -apple-system, BlinkMacSystemFont, sans-serif)',
+            background: 'var(--ggui-color-surfaceVariant, #f4f4f5)',
+            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+        },
+    }, React.createElement('div', { style: { fontWeight: 600, marginBottom: 8 } }, `Unknown system card: ${kind}`), React.createElement('div', {
+        style: {
+            fontSize: 12,
+            fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, monospace)',
+            opacity: 0.7,
+            wordBreak: 'break-all',
+        },
+    }, JSON.stringify(props)));
+}
+/**
+ * Registered system-card kinds. Keep keys aligned with
+ * `SystemStackItemKind` in `@ggui-ai/protocol` so wire + bundle stay
+ * in sync. New kinds added without a registry entry render as
+ * {@link UnknownSystemCard}.
+ */
+export const SYSTEM_CARD_REGISTRY = {
+    'no-credentials': entry(NoCredentialsCard, (raw) => {
+        const settingsUrl = typeof raw['settingsUrl'] === 'string' ? raw['settingsUrl'] : '';
+        const intent = typeof raw['intent'] === 'string' ? raw['intent'] : undefined;
+        return {
+            settingsUrl,
+            ...(intent !== undefined ? { intent } : {}),
+        };
+    }),
+    'mcp-apps-probe': entry(ProtocolProbeCard, (raw) => {
+        const intent = typeof raw['intent'] === 'string' ? raw['intent'] : undefined;
+        return {
+            ...(intent !== undefined ? { intent } : {}),
+        };
+    }),
+};
+/**
+ * Resolve a registered component by kind, or the fallback when the
+ * kind is unknown. Always returns a renderable React element.
+ */
+export function renderSystemCard(kind, props) {
+    const Comp = SYSTEM_CARD_REGISTRY[kind];
+    if (Comp) {
+        return React.createElement(Comp, props);
+    }
+    return React.createElement(UnknownSystemCard, { kind, props });
+}
+/**
+ * Top-level mount component the runtime renders for system stack
+ * items. Wraps the resolved card in a {@link ThemeProvider} so design
+ * tokens (`var(--ggui-*)`) resolve at `:root` even though the host's
+ * shell HTML doesn't pre-stamp them. Idempotent across remounts —
+ * shares the `ggui-theme-vars` style id with the rest of the design
+ * system, last writer wins.
+ *
+ * Adapts to the embedding host:
+ *
+ *   - **Inside Claude** (claude.ai web's `claudemcpcontent.com` or
+ *     Claude Desktop): drops the body background to `transparent` so
+ *     the chat-bubble surface shows through, and follows the user's
+ *     OS-level `prefers-color-scheme`. The card's own surfaces stay
+ *     opaque so the content remains readable on either bubble color.
+ *   - **Anywhere else**: lightTheme + opaque white background — the
+ *     historical default, suitable for stand-alone preview iframes
+ *     and console inspectors.
+ *
+ * Theme choice re-runs live: if the user toggles dark mode in their
+ * OS while the card is mounted, `useColorScheme` updates and we
+ * re-emit the matching theme's CSS variables.
+ */
+export function SystemCardHost({ kind, props, themeId: _themeId, }) {
+    // `themeId` reserved for future per-card theme override. Today the
+    // host environment + system color scheme drive the choice.
+    const inClaude = isInsideClaude();
+    const scheme = useColorScheme();
+    const theme = scheme === 'dark' ? darkTheme : lightTheme;
+    return React.createElement(ThemeProvider, {
+        theme,
+        mode: scheme,
+        transparent: inClaude,
+        children: renderSystemCard(kind, props),
+    });
+}
+export { NoCredentialsCard, ProtocolProbeCard };

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal types shared across the `@ggui-ai/iframe-runtime` runtime.
+ *
+ * These shapes describe the renderer's INTERNAL contracts — the
+ * bootstrap-parse outcome union + the renderer-host postMessage
+ * frames. The wire shapes consumed FROM the network
+ * (`SubscribePayload`, `AckPayload`, `WebSocketMessage`,
+ * `GguiBootstrapMeta`) come from `@ggui-ai/protocol` and are imported
+ * as `type` only so esbuild emits no runtime require for the protocol
+ * package — the bundle stays self-contained.
+ *
+ * Post-B3b: the WS lifecycle lives inside `@ggui-ai/channel-client`'s
+ * `WSTransport`; the renderer no longer maintains its own manager
+ * class. The `RendererWebSocketManagerOptions` type that pre-B3b
+ * declared the manager's constructor bag has been retired.
+ */
+import type { GguiBootstrapMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { HostContextProjection } from '@ggui-ai/protocol';
+/**
+ * Why a bootstrap parse can fail. Closed union — every value is a
+ * canonical reason the renderer surfaces to the host via postMessage.
+ *
+ * This set is intentionally narrow — it covers only parse-time
+ * outcomes. Host-observable failures (`BUNDLE_FETCH_FAILED`,
+ * `CSP_VIOLATION`, etc) live on the broader `BootstrapFailureReason`
+ * union in `protocol-error.ts`. The four parse-time outcomes:
+ *
+ *   - `MISSING_TOOL_OUTPUT` — host echoed `ui/initialize` without a
+ *     `result.toolOutput` object at all.
+ *   - `MISSING_META_GGUI_BOOTSTRAP` — `result.toolOutput` exists but
+ *     `_meta.ggui.bootstrap` is absent. The on-wire synonym is
+ *     `BOOTSTRAP_META_MISSING`.
+ *   - `MALFORMED_BOOTSTRAP` — `_meta.ggui.bootstrap` is present but
+ *     missing one of the four required string fields (`wsUrl`,
+ *     `token`, `sessionId`, `appId`) — i.e. it doesn't satisfy
+ *     `GguiBootstrapMeta`.
+ *   - `EXPIRED_BOOTSTRAP` — `expiresAt` is set and parses to a
+ *     timestamp in the past. UX sugar; servers reject expired tokens
+ *     anyway, but we skip the round-trip when the proof is on hand.
+ */
+export type BootstrapParseFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSING_META_GGUI_BOOTSTRAP' | 'MALFORMED_BOOTSTRAP' | 'EXPIRED_BOOTSTRAP';
+/**
+ * Result of a bootstrap-meta extraction attempt. Discriminated on
+ * `ok` so call sites get exhaustive narrowing without a typed-error
+ * class — keeps the renderer's runtime cost tiny (no class metadata
+ * in the bundle).
+ *
+ * widening: the `ok: true` arm now also carries
+ * an optional `hostContext: HostContextProjection`. When the bootstrap
+ * is extracted from the `ui/initialize` response (Reading-A path), the
+ * parser opportunistically projects the surrounding `McpUiHostContext`
+ * into this field so the runtime can:
+ *   - drive canvas-mode display-mode escalation
+ *   - echo to the server (live-channel `host_context_observed` envelope)
+ *   - feed the agent on next handshake/consume
+ *
+ * Capture is best-effort: a malformed `HostContext` never blocks the
+ * bootstrap parse. Absent for the other extraction paths
+ * (`__GGUI_BOOTSTRAP__` global, `ui/notifications/tool-result`) — those
+ * envelopes don't carry HostContext.
+ */
+export type BootstrapParseResult = {
+    readonly ok: true;
+    readonly bootstrap: GguiBootstrapMeta;
+    readonly hostContext?: HostContextProjection;
+} | {
+    readonly ok: false;
+    readonly reason: BootstrapParseFailureReason;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+export {};
+// `RendererWebSocketManagerOptions` retired in B3b — the WS lifecycle
+// moved to `@ggui-ai/channel-client`'s `WSTransport`.