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

package/dist/system-cards/ProtocolProbeCard.js

@@ -0,0 +1,463 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * MCP Apps protocol probe system card.
+ *
+ * Diagnostic + regression fixture exercising every gesture surface
+ * the iframe runtime routes:
+ *
+ *   1. **Pattern β bridge** — `tools/call ggui_runtime_submit_action` (audit) +
+ *      `ui/update-model-context` (silent context) + `ui/message`
+ *      (consent prompt). Fires for cross-server / non-app-visible
+ *      `actionSpec[name].dispatch.tool` targets, OR any
+ *      `dispatch.kind === 'agent'` entry. Empirical-first reproduction
+ *      of the production `dispatchWiredAction` path.
+ *   2. **Pattern α direct fire** — `tools/call ggui_runtime_submit_action`
+ *      (audit) + `tools/call <T>` (direct, no consent prompt). Fires
+ *      for same-server, app-visible target tools. Probes against
+ *      `ggui_runtime_submit_action` itself (the only universally-app-visible
+ *      tool the iframe can be sure exists).
+ *   3. **Native-idiom: anchor click** — `ui/open-link` paired with
+ *      `kind: 'openLink'` audit. Triggered by the runtime's
+ *      capture-phase `<a href>` interceptor (cross-origin or
+ *      `target="_blank"`). The probe row simulates the postMessage
+ *      directly so the operator sees the envelope without needing to
+ *      click an anchor.
+ *   4. **Native-idiom: fullscreen** — `ui/request-display-mode` +
+ *      `kind: 'requestDisplayMode'` audit. Triggered by the runtime's
+ *      `Element.prototype.requestFullscreen` /
+ *      `Document.prototype.exitFullscreen` overrides. The probe row
+ *      simulates the postMessage; the row labelled "exitFullscreen"
+ *      sends `mode: 'inline'` per the spec'd inverse mapping.
+ *
+ * Each button transitions through `idle → pending → success | error`
+ * so the operator can see exactly which methods the embedding host
+ * (claude.ai web, Claude Desktop, …) actually honors today. The
+ * persistent receive-log captures every `ui/notifications/*` and
+ * host-issued request seen while the card is mounted.
+ *
+ * Why this lives outside the wire-context: system cards (`kind:
+ * 'mcp-apps-probe'`, `'no-credentials'`, …) mount in a render-only
+ * branch of `bootSelfContained` that does NOT install
+ * `<GguiWireProvider>` — they exist precisely to surface protocol
+ * state when the wire-context might not be live (auth missing,
+ * compile failed, etc.). The probe card mirrors the postMessage
+ * envelopes the runtime's gesture surfaces would emit, derived from
+ * the canonical `SubmitActionEnvelope` shape in
+ * `@ggui-ai/protocol/integrations/mcp-apps`.
+ *
+ * Originating context: an earlier runtime posted its outbound
+ * action dispatch only as `{method:'tools/call',
+ * name:'ggui_runtime_submit_action', ...}`. Per MCP Apps spec §401, hosts MUST
+ * reject `tools/call` from views for tools without `'app'` in
+ * visibility — claude.ai silently dropped the call. The original
+ * probe diagnosed the gap; the routing simplification work landed
+ * Pattern α / Pattern β / native idioms in response.
+ */
+import * as React from 'react';
+import { Card, Stack, Heading, Text, Button, Badge, } from '@ggui-ai/design/primitives';
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Lifetime-scoped JSON-RPC caller. One instance per card mount —
+ * mirrors the runtime's own `makeJsonRpcCaller` (runtime.ts:105) so
+ * the card behaves like a real View per spec semantics. Pending
+ * requests are tracked by id; the persistent `message` listener
+ * matches by id and resolves.
+ */
+function useJsonRpcCaller() {
+    const nextIdRef = React.useRef(10_000);
+    const pendingRef = React.useRef(new Map());
+    React.useEffect(() => {
+        const onMessage = (event) => {
+            const data = event.data;
+            if (data === null || typeof data !== 'object')
+                return;
+            const id = data.id;
+            if (typeof id !== 'number')
+                return;
+            const resolver = pendingRef.current.get(id);
+            if (resolver === undefined)
+                return;
+            pendingRef.current.delete(id);
+            resolver(data);
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }, []);
+    return React.useCallback((method, params) => {
+        return new Promise((resolve) => {
+            const id = nextIdRef.current;
+            nextIdRef.current += 1;
+            pendingRef.current.set(id, resolve);
+            try {
+                window.parent.postMessage({ jsonrpc: '2.0', id, method, params: params ?? {} }, '*');
+            }
+            catch (err) {
+                pendingRef.current.delete(id);
+                resolve({
+                    error: {
+                        code: -32099,
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+            window.setTimeout(() => {
+                if (pendingRef.current.delete(id)) {
+                    resolve({ error: { code: -32001, message: 'TIMEOUT' } });
+                }
+            }, PROBE_TIMEOUT_MS);
+        });
+    }, []);
+}
+/**
+ * Persistent listener for host-emitted notifications. Captures every
+ * `jsonrpc:'2.0'` message that arrives without an `id` (= notification)
+ * AND has a `method` starting with `ui/notifications/` or matching one
+ * of the spec's other host→view methods. Bounded to the most recent
+ * 50 entries to keep the DOM small even on chatty hosts.
+ */
+function useNotificationLog() {
+    const [entries, setEntries] = React.useState([]);
+    const seqRef = React.useRef(0);
+    React.useEffect(() => {
+        const onMessage = (event) => {
+            const data = event.data;
+            if (data === null || typeof data !== 'object')
+                return;
+            const obj = data;
+            if (obj.jsonrpc !== '2.0')
+                return;
+            if (typeof obj.method !== 'string')
+                return;
+            // Capture notifications (no id) AND host-issued requests
+            // (e.g. `ui/resource-teardown` carries an id). Skip echoes of
+            // OUR own outbound calls — those have ids in the 10k range we
+            // assigned.
+            const isOurEcho = typeof obj.id === 'number' &&
+                obj.id >= 10_000 &&
+                (obj.method === 'ui/message' ||
+                    obj.method === 'ui/update-model-context' ||
+                    obj.method === 'ui/open-link' ||
+                    obj.method === 'ui/request-display-mode' ||
+                    obj.method === 'tools/call');
+            if (isOurEcho)
+                return;
+            seqRef.current += 1;
+            const entry = {
+                id: seqRef.current,
+                tsIso: new Date().toISOString(),
+                method: obj.method,
+                params: obj.params,
+            };
+            setEntries((prev) => {
+                const next = [entry, ...prev];
+                return next.slice(0, 50);
+            });
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }, []);
+    return entries;
+}
+/**
+ * Build a default param payload for each canonical method. The shapes
+ * mirror the spec examples (apps.mdx:963-1102) exactly so any host
+ * with a strict validator accepts them.
+ */
+function defaultParams(method) {
+    switch (method) {
+        case 'ui/message':
+            // Empirical 2026-05-03: claude.ai's validator wants `content`
+            // as a ContentBlock[] array, NOT the single-object shape the
+            // spec example (apps.mdx:1006-1011) shows. Other hosts may
+            // accept either; an array satisfies both.
+            return {
+                role: 'user',
+                content: [
+                    { type: 'text', text: '[ggui:probe] hello from the protocol probe card' },
+                ],
+            };
+        case 'ui/update-model-context':
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '[ggui:probe] this user prefers concise replies',
+                    },
+                ],
+            };
+        case 'ui/open-link':
+            return { url: 'https://ggui.ai' };
+        case 'ui/request-display-mode':
+            return { mode: 'fullscreen' };
+        case 'tools/call':
+            // Mirror `runtime.ts::emitAudit` + `runtime.ts::dispatchWiredAction`
+            // so this probe empirically validates the canonical
+            // `GguiUserActionInput` envelope (SPEC §4.6, see
+            // `@ggui-ai/protocol/integrations/mcp-apps`). `ggui_runtime_submit_action`
+            // MUST be server-registered with `_meta.ui.visibility: ['app']`
+            // for claude.ai to honor the call (spec §401). With registration
+            // in place, the server echoes the discriminated envelope back as
+            // a tool result; the host forwards that result to this iframe
+            // via the JSON-RPC response matching our outbound id.
+            //
+            // The probe uses `kind: 'dispatch'` so the chained Pattern β
+            // 3-message follow-up (`ui/update-model-context` + `ui/message`)
+            // semantically matches a real wired-action click.
+            return {
+                name: 'ggui_runtime_submit_action',
+                arguments: {
+                    kind: 'dispatch',
+                    payload: {
+                        intent: 'probe-click',
+                        data: { note: 'hello from the protocol probe' },
+                    },
+                    sessionId: 'probe-session',
+                    appId: 'probe-app',
+                    actionId: '00000000', // overwritten in onClick with real FNV-1a
+                    firedAt: new Date().toISOString(),
+                },
+            };
+    }
+}
+/**
+ * Compute a short deterministic action-id from an action payload.
+ * FNV-1a 32-bit, 8 hex chars — not cryptographically strong, just
+ * collision-resistant enough for in-flight wired-action correlation.
+ *
+ * Why hash (vs. random UUID): the id reproduces from
+ * `{intent, data, firedAt}` so both the silent context-update AND
+ * the loud consent message arrive at the SAME id without
+ * cross-state coordination. The LLM can then cross-check
+ * `actionId` in message ↔ `actionId` in pending-action context
+ * before acting — catches the case where a second click overwrote
+ * the context between message-fire and user-confirm.
+ */
+function hashAction(payload) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < payload.length; i += 1) {
+        hash ^= payload.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Render an action's `data` payload as a short inline string for
+ * embedding in a chat message. Goal: readable by humans, not a JSON
+ * dump. Falls back to truncated JSON for nested / non-scalar values
+ * so the consent prompt doesn't drop information silently.
+ */
+function formatActionDataInline(data) {
+    if (data === null || data === undefined)
+        return '';
+    if (typeof data !== 'object' || Array.isArray(data))
+        return '';
+    const entries = Object.entries(data);
+    if (entries.length === 0)
+        return '';
+    const parts = entries.map(([k, v]) => {
+        if (v === null)
+            return `${k}: null`;
+        if (typeof v === 'string')
+            return `${k}: ${v}`;
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return `${k}: ${v}`;
+        // Fallback for nested objects / arrays — keep it terse.
+        const json = JSON.stringify(v);
+        return `${k}: ${json.length > 40 ? `${json.slice(0, 37)}…` : json}`;
+    });
+    return parts.join(', ');
+}
+function ProbeButtonRow({ method, description, call, }) {
+    const [outcome, setOutcome] = React.useState({ state: 'idle' });
+    const onClick = React.useCallback(() => {
+        const startedAtMs = Date.now();
+        setOutcome({ state: 'pending', startedAtMs });
+        const params = defaultParams(method);
+        void call(method, params).then((resp) => {
+            if (resp.error) {
+                setOutcome({
+                    state: 'error',
+                    code: resp.error.code ?? '?',
+                    message: resp.error.message ?? '(no message)',
+                });
+                return;
+            }
+            setOutcome({ state: 'success', result: resp.result ?? {} });
+            // Tools/call chain. After the gateway tool acknowledges, fire
+            // TWO follow-ups so the LLM gets both human-readable AND
+            // machine-readable signals about the action:
+            //
+            //   1. `ui/update-model-context` (silent) — structured payload
+            //      describing the pending action. Persists in context so
+            //      the LLM has unambiguous tool-args data instead of
+            //      having to parse "tomorrow 3pm" out of natural language.
+            //      Spec §1099: each call overwrites the previous; we DON'T
+            //      attempt to accumulate (latest click wins, which matches
+            //      most UX flows).
+            //
+            //   2. `ui/message` (consent prompt) — natural-language
+            //      surface of the same action. claude.ai pre-fills the
+            //      input with this text and asks the user to confirm
+            //      before sending. The consent IS the prompt-injection
+            //      firewall (visibility:['app'] keeps the LLM from
+            //      seeing view-issued tool calls directly).
+            //
+            // LLM next turn sees: the user-confirmed message + the
+            // structured pending-action context. Combination reduces
+            // tool-arg ambiguity dramatically — production actionSpec
+            // routing would also include `tool: actionSpec.<intent>.tool`
+            // in the structured context so the LLM knows the exact
+            // downstream tool to call.
+            if (method === 'tools/call') {
+                const args = params
+                    .arguments ?? {};
+                // New gesture-envelope shape (SPEC §4.6): `{kind, payload,
+                // sessionId, appId, actionId, firedAt}`. For Pattern β the
+                // `payload` carries `{intent, data}`.
+                const payload = args['payload'] ?? {};
+                const intent = String(payload['intent'] ?? '?');
+                const data = payload['data'];
+                const inlineData = formatActionDataInline(data);
+                const dataPart = inlineData === '' ? '' : ` (${inlineData})`;
+                const firedAt = new Date().toISOString();
+                // Action id binds the silent context update and the loud
+                // consent message together. LLM verifies `actionId` in the
+                // message matches `actionId` in pending-action context
+                // before acting — guarantees the args it uses are the args
+                // we authorized (not a stale or overwritten set).
+                const actionId = hashAction(`${intent}|${JSON.stringify(data ?? null)}|${firedAt}`);
+                // Silent — structured hint for the LLM. `actionId` is the
+                // verification token; rest carries the exact args.
+                void call('ui/update-model-context', {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `[ggui:pending-action] ${JSON.stringify({
+                                actionId,
+                                intent,
+                                data: data ?? null,
+                                firedAt,
+                            })}`,
+                        },
+                    ],
+                });
+                // Loud — user-confirmable surface. Three layers:
+                //   - Intent in **bold** so the user sees what they're
+                //     authorizing at a glance.
+                //   - Inline data so the consent prompt is human-readable
+                //     (no "approve a black box" UX).
+                //   - Trailing `[id: <hash>]` stamp the LLM cross-checks
+                //     against the pending-action context. Mismatch → LLM
+                //     should refuse to act (production prompt-engineering).
+                void call('ui/message', {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Please proceed with **${intent}**${dataPart}. [id: \`${actionId}\`]`,
+                        },
+                    ],
+                });
+            }
+        });
+    }, [call, method]);
+    const buttonLabel = outcome.state === 'pending'
+        ? 'Sending…'
+        : outcome.state === 'success'
+            ? 'Send again ✓'
+            : outcome.state === 'error'
+                ? 'Retry'
+                : 'Send';
+    const statusBadge = outcome.state === 'idle' ? (_jsx(Badge, { variant: "default", children: "idle" })) : outcome.state === 'pending' ? (_jsx(Badge, { variant: "info", children: "pending" })) : outcome.state === 'success' ? (_jsx(Badge, { variant: "success", children: "success" })) : (_jsx(Badge, { variant: "warning", children: "error" }));
+    return (_jsxs("div", { style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--ggui-spacing-2, 8px)',
+            padding: 'var(--ggui-spacing-3, 12px)',
+            borderRadius: 'var(--ggui-shape-radius-md, 10px)',
+            border: '1px solid var(--ggui-color-neutral-200, #e4e4e7)',
+            background: 'var(--ggui-color-surface, #fff)',
+        }, children: [_jsxs("div", { style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'space-between',
+                    gap: 'var(--ggui-spacing-3, 12px)',
+                    flexWrap: 'wrap',
+                }, children: [_jsx("code", { style: {
+                            fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
+                            fontSize: 'var(--ggui-font-size-sm, 13px)',
+                            color: 'var(--ggui-color-onSurface, #111)',
+                            fontWeight: 'var(--ggui-font-weight-semibold, 600)',
+                        }, children: method }), statusBadge] }), _jsx(Text, { variant: "caption", style: {
+                    color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                    fontSize: 'var(--ggui-font-size-xs, 11px)',
+                }, children: description }), _jsx("div", { style: { display: 'flex', gap: 'var(--ggui-spacing-2, 8px)' }, children: _jsx(Button, { variant: "primary", size: "sm", onClick: onClick, disabled: outcome.state === 'pending', children: buttonLabel }) }), outcome.state === 'success' || outcome.state === 'error' ? (_jsx("pre", { style: {
+                    margin: 0,
+                    fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
+                    fontSize: 'var(--ggui-font-size-xs, 11px)',
+                    color: outcome.state === 'error'
+                        ? 'var(--ggui-color-warning, #b45309)'
+                        : 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                    background: 'var(--ggui-color-neutral-100, #f4f4f5)',
+                    padding: 'var(--ggui-spacing-2, 8px)',
+                    borderRadius: 'var(--ggui-shape-radius-sm, 6px)',
+                    overflow: 'auto',
+                    maxHeight: '120px',
+                    whiteSpace: 'pre-wrap',
+                    wordBreak: 'break-word',
+                }, children: outcome.state === 'error'
+                    ? `${outcome.code}: ${outcome.message}`
+                    : JSON.stringify(outcome.result, null, 2) })) : null] }));
+}
+export function ProtocolProbeCard({ intent, }) {
+    const call = useJsonRpcCaller();
+    const log = useNotificationLog();
+    return (_jsx(Card, { padding: "lg", border: false, shadow: "none", style: { backgroundColor: 'transparent' }, children: _jsxs(Stack, { gap: "lg", children: [_jsxs(Stack, { gap: "sm", children: [_jsxs("div", { style: {
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: 'var(--ggui-spacing-3, 12px)',
+                                flexWrap: 'wrap',
+                            }, children: [_jsx(Heading, { level: 3, children: "MCP Apps protocol probe" }), _jsx(Badge, { variant: "info", children: "diagnostic" })] }), _jsxs(Text, { style: {
+                                color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                lineHeight: '1.55',
+                            }, children: ["One button per primary host effect emitted by the iframe runtime's gesture surfaces (Pattern \u03B1 / Pattern \u03B2 / native- idiom interceptors). Click each to verify which methods this host honors. The", _jsx("code", { children: "tools/call" }), " row chains the full Pattern \u03B2 bridge (audit + context + consent), reproducing the production", _jsx("code", { children: "dispatchWiredAction" }), " envelope shape verbatim. The receive log below captures every notification the host emits while this card is mounted."] })] }), _jsxs(Stack, { gap: "md", children: [_jsx(ProbeButtonRow, { method: "ui/message", description: "Pattern \u03B2 step 3 \u2014 consent-gated user authorization. Host pre-fills + waits for user confirm before the LLM acts on the paired pending-action context.", call: call }), _jsx(ProbeButtonRow, { method: "ui/update-model-context", description: "Pattern \u03B2 step 2 \u2014 silent structured `[ggui:pending-action]` context drop. LLM honors on next turn. No immediate UI.", call: call }), _jsx(ProbeButtonRow, { method: "ui/open-link", description: "Native-idiom anchor click interceptor primary effect. Opens ggui.ai in the host's browser / new tab. Real iframe code triggers via `<a href target='_blank'>` or cross-origin href.", call: call }), _jsx(ProbeButtonRow, { method: "ui/request-display-mode", description: "Native-idiom fullscreen interceptor primary effect. Request fullscreen \u2014 real iframe code calls `el.requestFullscreen()`; the runtime overrides the prototype to route through here.", call: call }), _jsx(ProbeButtonRow, { method: "tools/call", description: "Pattern \u03B2 full bridge: `tools/call ggui_runtime_submit_action` (audit, kind:'dispatch') + `ui/update-model-context` + `ui/message`. Spec \u00A7401 requires `_meta.ui.visibility:['app']` on the receiving tool. Pattern \u03B1 (direct fire to a same-server app-visible target) would skip steps 2+3 and add a second `tools/call` to the target tool instead.", call: call })] }), _jsxs(Stack, { gap: "sm", children: [_jsxs("div", { style: {
+                                display: 'flex',
+                                alignItems: 'baseline',
+                                justifyContent: 'space-between',
+                                gap: 'var(--ggui-spacing-3, 12px)',
+                            }, children: [_jsx(Heading, { level: 4, children: "Receive log" }), _jsxs(Text, { variant: "caption", style: {
+                                        color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                        fontSize: 'var(--ggui-font-size-xs, 11px)',
+                                    }, children: [log.length, " ", log.length === 1 ? 'event' : 'events'] })] }), log.length === 0 ? (_jsx(Text, { variant: "caption", style: {
+                                color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                fontStyle: 'italic',
+                            }, children: "No host notifications observed yet. Click a probe button or wait for the host to emit one." })) : (_jsx("div", { style: {
+                                display: 'flex',
+                                flexDirection: 'column',
+                                gap: 'var(--ggui-spacing-1, 4px)',
+                                maxHeight: '320px',
+                                overflow: 'auto',
+                                padding: 'var(--ggui-spacing-2, 8px)',
+                                background: 'var(--ggui-color-neutral-100, #f4f4f5)',
+                                border: '1px solid var(--ggui-color-neutral-200, #e4e4e7)',
+                                borderRadius: 'var(--ggui-shape-radius-md, 10px)',
+                            }, children: log.map((entry) => (_jsxs("details", { style: {
+                                    fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
+                                    fontSize: 'var(--ggui-font-size-xs, 11px)',
+                                }, children: [_jsxs("summary", { style: {
+                                            cursor: 'pointer',
+                                            padding: 'var(--ggui-spacing-1, 4px) 0',
+                                            color: 'var(--ggui-color-onSurface, #111)',
+                                        }, children: [_jsx("span", { style: {
+                                                    color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                                    marginRight: '8px',
+                                                }, children: entry.tsIso.slice(11, 19) }), _jsx("span", { style: { fontWeight: 600 }, children: entry.method })] }), _jsx("pre", { style: {
+                                            margin: '4px 0 0 16px',
+                                            whiteSpace: 'pre-wrap',
+                                            wordBreak: 'break-word',
+                                            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                        }, children: JSON.stringify(entry.params, null, 2) })] }, entry.id))) }))] }), intent ? (_jsxs(Text, { variant: "caption", style: {
+                        color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                        opacity: 0.7,
+                    }, children: ["Triggered by: ", intent] })) : null] }) }));
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Tiny QR code component — renders a URL as a scannable SVG QR code.
+ *
+ * The mobile-best fallback for system cards that need to send the
+ * user out to a real browser. From inside an MCP App iframe sandbox
+ * (claudemcpcontent.com etc.), no JS API can spawn a browser tab —
+ * `window.open` is blocked, `target="_blank"` silently fails, and
+ * postMessage host-intents (`ui/request/open-url`) are speculative.
+ * A QR code bypasses every sandbox limit: phone camera scans →
+ * opens the URL in real Safari/Chrome with no host cooperation
+ * required.
+ *
+ * Renders inline SVG (no canvas, no images, no network fetch). Bundle
+ * cost: `qrcode-generator` is ~6 KB unminified, ~3 KB gzipped — tiny
+ * compared to the alternative of "tell the user to scan a clipboard".
+ */
+import * as React from 'react';
+export interface QrCodeProps {
+    /** URL to encode. Truncated implicitly by the QR encoder if too long. */
+    readonly value: string;
+    /**
+     * Side length in CSS pixels. Default 128 — readable on a phone
+     * camera at arm's length without being visually dominant on the
+     * card.
+     */
+    readonly size?: number;
+    /**
+     * Error correction level. `M` (medium, ~15% recoverable) is the
+     * default sweet spot — robust to dust / glare without bloating
+     * module count for short URLs. Bump to `Q` or `H` only when
+     * encoding into a high-traffic surface.
+     */
+    readonly errorCorrection?: 'L' | 'M' | 'Q' | 'H';
+    /** Foreground color (the dots). Defaults to theme onSurface. */
+    readonly foreground?: string;
+    /** Background color. Defaults to theme surface. */
+    readonly background?: string;
+    /** Optional aria-label override. */
+    readonly ariaLabel?: string;
+}
+/**
+ * Render a QR code as inline SVG. Returns `null` when the encoder
+ * fails (e.g., URL too long for any error-correction level) so the
+ * caller can render a fallback.
+ */
+export declare function QrCode({ value, size, errorCorrection, foreground, background, ariaLabel, }: QrCodeProps): React.JSX.Element | null;

package/dist/system-cards/QrCode.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Tiny QR code component — renders a URL as a scannable SVG QR code.
+ *
+ * The mobile-best fallback for system cards that need to send the
+ * user out to a real browser. From inside an MCP App iframe sandbox
+ * (claudemcpcontent.com etc.), no JS API can spawn a browser tab —
+ * `window.open` is blocked, `target="_blank"` silently fails, and
+ * postMessage host-intents (`ui/request/open-url`) are speculative.
+ * A QR code bypasses every sandbox limit: phone camera scans →
+ * opens the URL in real Safari/Chrome with no host cooperation
+ * required.
+ *
+ * Renders inline SVG (no canvas, no images, no network fetch). Bundle
+ * cost: `qrcode-generator` is ~6 KB unminified, ~3 KB gzipped — tiny
+ * compared to the alternative of "tell the user to scan a clipboard".
+ */
+import * as React from 'react';
+import qrcodeFactory from 'qrcode-generator';
+/**
+ * Render a QR code as inline SVG. Returns `null` when the encoder
+ * fails (e.g., URL too long for any error-correction level) so the
+ * caller can render a fallback.
+ */
+export function QrCode({ value, size = 128, errorCorrection = 'M', foreground = 'var(--ggui-color-onSurface, #18181b)', background = 'var(--ggui-color-surface, #ffffff)', ariaLabel, }) {
+    const moduleMatrix = React.useMemo(() => {
+        try {
+            // typeNumber=0 lets the encoder pick the smallest fit. The
+            // qrcode-generator default-export is a factory function —
+            // calling it returns a `qr` object with `.addData()` /
+            // `.make()` / `.getModuleCount()` / `.isDark(row, col)`.
+            const qr = qrcodeFactory(0, errorCorrection);
+            qr.addData(value);
+            qr.make();
+            const count = qr.getModuleCount();
+            const matrix = [];
+            for (let row = 0; row < count; row += 1) {
+                const r = [];
+                for (let col = 0; col < count; col += 1) {
+                    r.push(qr.isDark(row, col));
+                }
+                matrix.push(r);
+            }
+            return matrix;
+        }
+        catch {
+            return null;
+        }
+    }, [value, errorCorrection]);
+    if (moduleMatrix === null)
+        return null;
+    const moduleCount = moduleMatrix.length;
+    // 1px viewBox per module — let CSS handle final size scaling.
+    return (_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: `0 0 ${moduleCount} ${moduleCount}`, width: size, height: size, role: "img", "aria-label": ariaLabel ?? `QR code for ${value}`, shapeRendering: "crispEdges", style: { display: 'block', flexShrink: 0 }, children: [_jsx("rect", { width: moduleCount, height: moduleCount, fill: background }), moduleMatrix.flatMap((row, y) => row.map((isDark, x) => isDark ? (_jsx("rect", { x: x, y: y, width: 1, height: 1, fill: foreground }, `${x}-${y}`)) : null))] }));
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function isInsideClaude(): boolean;
+/**
+ * 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 declare function useColorScheme(): 'light' | 'dark';