@ggui-ai/mcp-apps-react-native 0.0.1-placeholder → 0.9.0

package/src/McpAppIframe/dispatch.ts

@@ -0,0 +1,418 @@
+/**
+ * Platform-agnostic JSON-RPC dispatch for `<McpAppIframe>` on React
+ * Native — the canonical RN MCP-Apps host primitive. The web side
+ * retired its `<McpAppIframe>` in favor of `<AppRenderer>` from
+ * `@mcp-ui/client`, which is built around iframes + a two-iframe
+ * sandbox-proxy model that has no meaningful WebView equivalent;
+ * `<McpAppIframe>` on RN stays as the host primitive for mobile.
+ *
+ * The host responds to:
+ *
+ *   - `ping` → `{ok: true, pong: true}`.
+ *   - `ui/initialize` → a spec-canonical `McpUiInitializeResult`
+ *     whose `hostContext` carries `{locale, containerDimensions}`
+ *     ONLY — the adapter-boundary rule (no outer-app state leaks).
+ *     NEVER carries `toolOutput._meta` — see "Reading-B retired"
+ *     note below.
+ *   - `ui/open-link` with http(s) URLs → caller opens externally;
+ *     other schemes → reject `unsupported-scheme`.
+ *   - `tools/call` → caller-provided handler, or reject
+ *     `no-tool-handler` when none.
+ *   - any other method → `method_not_supported`.
+ *
+ * Notifications (no `id`) return `null` — the caller MUST NOT post a
+ * response back to the iframe.
+ *
+ * ── Reading-B retired (parity with iframe-runtime Phase 1.19b.3) ─────
+ *
+ * The legacy "stuff the `ai.ggui/render` slice on `ui/initialize`
+ * result.toolOutput._meta" path is retired here. iframe-runtime's
+ * App-class adoption means `App.connect()` does NOT expose
+ * `result.toolOutput`, so any meta crammed into the initialize
+ * response is silently dropped on the renderer side.
+ *
+ * The spec-canonical delivery channel is now {@link
+ * buildToolResultNotification} — a `ui/notifications/tool-result`
+ * notification (JSON-RPC) wrapping a `CallToolResult` whose `_meta`
+ * carries the single `ai.ggui/render` slice. The McpAppIframe host
+ * sends this notification immediately after the
+ * `ui/initialize` response when `meta` is supplied, so the renderer's
+ * `awaitToolResultMeta` window-message listener (autostart layer) or
+ * its App-mediated `toolresult` event catches the meta and boots the
+ * render. Wire shape matches what `@mcp-ui/client`'s `<AppRenderer
+ * toolResult={...}>` forwards on web.
+ *
+ * The shared host-role switch (`handleHostBridgeRequest`) lives in the
+ * sibling `components/mcp-apps-bridge.ts`; it covers the same methods
+ * but bakes in the ggui-server `/mcp-apps/tools-call` proxy URL,
+ * whereas this dispatcher leaves `tools/call` to a caller-supplied
+ * handler so the iframe stays generic across hosts.
+ */
+
+import {
+  MCP_APP_BOOTSTRAP_FAILED_TYPE,
+  MCP_APP_LIFECYCLE_TYPE,
+  MCP_APP_OBSERVE_TYPE,
+  toMcpAppEnvelope,
+  type McpAppAiGguiRenderMeta,
+} from '@ggui-ai/protocol/integrations/mcp-apps';
+import {
+  LATEST_PROTOCOL_VERSION,
+  McpUiUpdateModelContextRequestSchema,
+  type McpUiInitializeResult,
+} from '@modelcontextprotocol/ext-apps';
+import type {
+  McpAppIframeDimensions,
+  McpAppIframeProps,
+} from './types.js';
+
+export interface HostBridgeRequest {
+  readonly jsonrpc?: '2.0';
+  readonly id?: number | string;
+  readonly method?: string;
+  readonly params?: Record<string, unknown>;
+}
+
+export interface HostBridgeResponse {
+  readonly jsonrpc: '2.0';
+  readonly id: number | string;
+  readonly result?: Record<string, unknown>;
+  readonly error?: { readonly code: number; readonly message: string };
+}
+
+export interface HostBridgeNotification {
+  readonly jsonrpc: '2.0';
+  readonly method: string;
+  readonly params?: Record<string, unknown>;
+}
+
+export interface HostBridgeContext {
+  readonly locale: string;
+  readonly containerDimensions: McpAppIframeDimensions;
+  readonly openLink: (url: string) => Promise<void> | void;
+  readonly onToolCall?: McpAppIframeProps['onToolCall'];
+  readonly onUpdateModelContext?: McpAppIframeProps['onUpdateModelContext'];
+}
+
+function isJsonRpcRequest(value: unknown): value is HostBridgeRequest {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as { jsonrpc?: unknown; method?: unknown };
+  return v.jsonrpc === '2.0' && typeof v.method === 'string';
+}
+
+function paramString(
+  params: HostBridgeRequest['params'],
+  key: string,
+): string {
+  if (!params) return '';
+  const v = params[key];
+  return typeof v === 'string' ? v : '';
+}
+
+function paramObject(
+  params: HostBridgeRequest['params'],
+  key: string,
+): Record<string, unknown> {
+  if (!params) return {};
+  const v = params[key];
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return {};
+  return v as Record<string, unknown>;
+}
+
+/**
+ * Host-role method dispatcher. Returns a JSON-RPC response, or `null`
+ * when the request is malformed / a notification. Pure function —
+ * testable without a WebView present.
+ */
+export async function dispatchHostBridgeRequest(
+  req: HostBridgeRequest,
+  ctx: HostBridgeContext,
+): Promise<HostBridgeResponse | null> {
+  if (!isJsonRpcRequest(req)) return null;
+  if (req.id === undefined) return null;
+
+  const id = req.id;
+
+  switch (req.method) {
+    case 'ping': {
+      return { jsonrpc: '2.0', id, result: { ok: true, pong: true } };
+    }
+    case 'ui/initialize': {
+      // Spec-canonical `McpUiInitializeResult`. The `@modelcontextprotocol/
+      // ext-apps` `App.connect` running inside the WebView zod-validates
+      // this response, and `protocolVersion` + `hostInfo` +
+      // `hostCapabilities` + `hostContext` are ALL required — the
+      // pre-App draft shape (`{theme, containerDimensions, locale}` at
+      // the top level) fails that gate and kills every mount before
+      // the renderer boots.
+      //
+      // ADAPTER BOUNDARY. `hostContext` carries `{locale,
+      // containerDimensions}` ONLY — no outer-app state leaks into
+      // the iframe. ggui theming rides the `ai.ggui/render.theme`
+      // slice (two-layer theming), never this handshake; the spec's
+      // `hostContext.styles` variable set is a closed union of
+      // spec-defined keys that ggui's overlay deliberately does not
+      // claim. First-party `ai.ggui/render` meta is delivered via the
+      // separate spec-canonical `ui/notifications/tool-result`
+      // notification (see {@link buildToolResultNotification}), NOT
+      // via this initialize response.
+      const requested = paramString(req.params, 'protocolVersion');
+      const result: McpUiInitializeResult = {
+        protocolVersion: requested.length > 0 ? requested : LATEST_PROTOCOL_VERSION,
+        // `hostInfo.version` is diagnostic-only; this tsc-built package
+        // has no build-stamp machinery (unlike iframe-runtime's esbuild
+        // `define`), and a hand-maintained literal would silently drift
+        // from the published version at every release.
+        hostInfo: { name: 'ggui-react-native', version: 'unstamped' },
+        hostCapabilities: {},
+        hostContext: {
+          locale: ctx.locale,
+          containerDimensions: ctx.containerDimensions,
+        },
+      };
+      return { jsonrpc: '2.0', id, result };
+    }
+    case 'ui/open-link': {
+      const url = paramString(req.params, 'url');
+      if (!/^https?:\/\//i.test(url)) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32602, message: 'unsupported-scheme' },
+        };
+      }
+      try {
+        await ctx.openLink(url);
+        return { jsonrpc: '2.0', id, result: { opened: true } };
+      } catch (err) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: {
+            code: -32000,
+            message: `open_link_failed: ${String(err)}`,
+          },
+        };
+      }
+    }
+    case 'tools/call': {
+      if (ctx.onToolCall === undefined) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32000, message: 'no-tool-handler' },
+        };
+      }
+      const tool = paramString(req.params, 'name');
+      if (tool.length === 0) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32602, message: 'tools/call requires params.name' },
+        };
+      }
+      const args = paramObject(req.params, 'arguments');
+      try {
+        const result: unknown = await ctx.onToolCall(tool, args);
+        const wrapped: Record<string, unknown> =
+          result !== null && typeof result === 'object' && !Array.isArray(result)
+            ? (result as Record<string, unknown>)
+            : { value: result };
+        return { jsonrpc: '2.0', id, result: wrapped };
+      } catch (err) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: {
+            code: -32000,
+            message: `tool_call_failed: ${String(err)}`,
+          },
+        };
+      }
+    }
+    case 'ui/update-model-context': {
+      // App → host context contribution (the renderer sends this on
+      // interaction). Forwarded to the caller when a handler is wired;
+      // WITHOUT one the honest answer stays `method_not_supported` —
+      // acking context we did not carry anywhere would mislead the app
+      // (first-integrator report, ggui#425 fourth finding).
+      if (ctx.onUpdateModelContext === undefined) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32601, message: 'method_not_supported' },
+        };
+      }
+      const parsed = McpUiUpdateModelContextRequestSchema.safeParse({
+        method: 'ui/update-model-context',
+        params: req.params,
+      });
+      if (!parsed.success) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32602, message: 'invalid ui/update-model-context params' },
+        };
+      }
+      await ctx.onUpdateModelContext(parsed.data.params);
+      return { jsonrpc: '2.0', id, result: {} };
+    }
+    default: {
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: 'method_not_supported' },
+      };
+    }
+  }
+}
+
+// =============================================================================
+// Renderer → host envelope classification
+// =============================================================================
+
+export type RendererEnvelopeTag =
+  | 'bootstrap-failed'
+  | 'observability'
+  | 'lifecycle'
+  | 'jsonrpc'
+  | 'unknown';
+
+/**
+ * Classify a raw message payload received from the WebView. The
+ * platform host routes each tag to the matching callback prop. The
+ * recognized `type` discriminators are the protocol-owned renderer →
+ * host envelope vocabulary (`@ggui-ai/protocol/integrations/mcp-apps`)
+ * — this classifier recognizes exactly the tags renderers emit, no
+ * phantom arms. (`ggui:renderer-ready` is deliberately untagged: it is
+ * an optional informational signal this host has no callback for, so
+ * it falls through to `unknown` and is dropped.)
+ */
+export function classifyRendererEnvelope(data: unknown): RendererEnvelopeTag {
+  if (data === null || typeof data !== 'object') return 'unknown';
+  const d = data as { type?: unknown; jsonrpc?: unknown; method?: unknown };
+  if (typeof d.type === 'string') {
+    switch (d.type) {
+      case MCP_APP_BOOTSTRAP_FAILED_TYPE:
+        return 'bootstrap-failed';
+      case MCP_APP_OBSERVE_TYPE:
+        return 'observability';
+      case MCP_APP_LIFECYCLE_TYPE:
+        return 'lifecycle';
+      default:
+        break;
+    }
+  }
+  if (d.jsonrpc === '2.0' && typeof d.method === 'string') return 'jsonrpc';
+  return 'unknown';
+}
+
+export function buildDispatchActionNotification(
+  name: string,
+  data: unknown,
+): HostBridgeNotification {
+  return {
+    jsonrpc: '2.0',
+    method: name,
+    params: { data },
+  };
+}
+
+export function buildResourceTeardownNotification(): HostBridgeNotification {
+  return {
+    jsonrpc: '2.0',
+    method: 'ui/resource-teardown',
+    params: { reason: 'host_unmount' },
+  };
+}
+
+/**
+ * Build a spec-canonical `ui/notifications/tool-result` JSON-RPC
+ * notification carrying the `ai.ggui/render` slice on `params._meta`.
+ *
+ * Wire shape:
+ * ```
+ * {
+ *   jsonrpc: '2.0',
+ *   method: 'ui/notifications/tool-result',
+ *   params: {                       // CallToolResult per MCP spec
+ *     content: [],
+ *     structuredContent: {},
+ *     _meta: {
+ *       'ai.ggui/render': { sessionId, appId, runtimeUrl, ... },
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * Mirrors what `@mcp-ui/client`'s `<AppRenderer toolResult={...}>`
+ * forwards to its inner iframe on web (per MCP-Apps SEP-1865 and
+ * `McpUiToolResultNotification` in
+ * `@modelcontextprotocol/ext-apps/spec.types`). The renderer's
+ * `parseMetaFromToolResult` extractor
+ * (`packages/iframe-runtime/src/meta-parse.ts`) reads `params._meta`
+ * exactly.
+ *
+ * Sent immediately after the `ui/initialize` response when the host
+ * was given a `meta` prop, so the renderer's pre-handshake
+ * `awaitToolResultMeta` listener (Tier 2 in `bootSequence`) catches
+ * it and boots the render.
+ */
+export function buildToolResultNotification(
+  meta: McpAppAiGguiRenderMeta,
+): HostBridgeNotification {
+  return {
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [],
+      structuredContent: {},
+      _meta: toMcpAppEnvelope(meta),
+    },
+  };
+}
+
+// =============================================================================
+// Resource → WebView mount-source derivation
+// =============================================================================
+
+/**
+ * RN WebView `source` shape. Matches react-native-webview's `source`
+ * prop.
+ */
+export type ResourceWebViewSource =
+  | { readonly html: string; readonly baseUrl?: string }
+  | { readonly uri: string };
+
+/**
+ * Compute the WebView `source` from an MCP Apps `ResourceContents`.
+ * Mirrors the web version's `deriveResourceMountSource` decision tree:
+ *
+ *   1. `text` present → `source={{html: text}}` (inline HTML;
+ *      opaque origin, safest path).
+ *   2. `blob` + `mimeType` → data-URL fallback (native WebView treats
+ *      this as a top-level URL load). Opaque origin too.
+ *   3. Else → `source={{uri}}` IF `uri` is http(s); else `null`
+ *      (caller renders an empty WebView + emits a bootstrap failure).
+ */
+export function deriveResourceMountSource(resource: {
+  readonly uri: string;
+  readonly mimeType?: string;
+  readonly text?: string;
+  readonly blob?: string;
+}): ResourceWebViewSource | null {
+  if (typeof resource.text === 'string' && resource.text.length > 0) {
+    return { html: resource.text };
+  }
+  if (typeof resource.blob === 'string' && resource.blob.length > 0) {
+    const mime =
+      typeof resource.mimeType === 'string' && resource.mimeType.length > 0
+        ? resource.mimeType
+        : 'text/html';
+    return { uri: `data:${mime};base64,${resource.blob}` };
+  }
+  if (typeof resource.uri === 'string' && /^https?:\/\//i.test(resource.uri)) {
+    return { uri: resource.uri };
+  }
+  return null;
+}

package/src/McpAppIframe/index.ts

@@ -0,0 +1,15 @@
+/**
+ * `<McpAppIframe>` barrel — generic MCP Apps iframe host for React
+ * Native.
+ *
+ * Re-exported at the package root (`@ggui-ai/mcp-apps-react-native`) —
+ * consumers import from the root barrel, not this path.
+ */
+
+export { McpAppIframe } from './McpAppIframe.js';
+export type {
+  McpAppIframeDimensions,
+  McpAppIframePermissions,
+  McpAppIframeProps,
+  McpAppIframeRef,
+} from './types.js';

package/src/McpAppIframe/types.ts

@@ -0,0 +1,227 @@
+/**
+ * Public props + imperative-ref shape for `<McpAppIframe>` on React
+ * Native — the canonical MCP-Apps WebView host exported from
+ * `@ggui-ai/mcp-apps-react-native`.
+ *
+ * The web side retired `<McpAppIframe>` in favor of `<AppRenderer>`
+ * from `@mcp-ui/client`. That migration relied on a two-iframe
+ * sandbox-proxy architecture (cross-origin iframe nesting) that has
+ * no meaningful WebView equivalent — a `react-native-webview` WebView
+ * is itself a top-level browser surface, not a nestable origin. So on
+ * RN, `<McpAppIframe>` IS the spec-canonical host primitive.
+ *
+ * Wire shape parity with `<AppRenderer>` is preserved on every other
+ * surface: spec-canonical `ui/initialize` handshake (adapter-boundary
+ * response), `ui/notifications/tool-result` for render-meta delivery,
+ * `tools/call` outbound routing, `ui/open-link` delegated to
+ * `Linking.openURL`, `ui/resource-teardown` notification at unmount,
+ * and observability / lifecycle envelopes posted upward.
+ */
+
+import type { ResourceContents } from '@modelcontextprotocol/sdk/types.js';
+import type {
+  ObservabilityEvent,
+  ProtocolError,
+} from '@ggui-ai/iframe-runtime';
+import type {
+  McpAppAiGguiRenderMeta,
+  McpAppLifecycleEvent,
+} from '@ggui-ai/protocol/integrations/mcp-apps';
+
+/**
+ * Container-dimensions hint forwarded verbatim to the iframe via
+ * `ui/initialize.result.hostContext.containerDimensions`.
+ */
+export interface McpAppIframeDimensions {
+  readonly width?: number;
+  readonly height?: number;
+  readonly maxWidth?: number;
+  readonly maxHeight?: number;
+}
+
+/**
+ * Permissions-Policy hint forwarded to the WebView (RN). Spec-canonical
+ * field names. Native WebView enforces these through platform-specific
+ * permission prompts — on web these map to the iframe `allow` attribute.
+ */
+export interface McpAppIframePermissions {
+  readonly camera?: boolean;
+  readonly microphone?: boolean;
+  readonly geolocation?: boolean;
+  readonly clipboardWrite?: boolean;
+}
+
+/**
+ * Props for `<McpAppIframe>` on React Native.
+ *
+ * Host obligations:
+ *   - Host MUST mount WebView with `source` derived from `resource`:
+ *     `source={{html: resource.text}}` for inline HTML; `source={{uri:
+ *     resource.uri}}` for URL resources (http(s) only).
+ *   - `ui/initialize` replies carry ONLY `{theme, containerDimensions,
+ *     locale}` — adapter-boundary rule.
+ *   - `tools/call` forwards to `onToolCall`; absent handler → reject
+ *     `no-tool-handler`.
+ *   - `ui/open-link` with `https?://` → delegates to `Linking.openURL`;
+ *     other schemes → reject `unsupported-scheme`.
+ *   - Unknown method → `method_not_supported`.
+ */
+export interface McpAppIframeProps {
+  /**
+   * The MCP Apps resource to render. Structurally compatible with
+   * `@modelcontextprotocol/sdk`'s `ResourceContents` (same TS type).
+   *
+   * Shape:
+   *   - `uri` — required. Identifies the resource.
+   *   - `mimeType?` — used when deriving a data-URL from a `blob`.
+   *   - `text?` — when present, host mounts via `source={{html}}`
+   *     (inline HTML).
+   *   - `blob?` — when present (and no `text`), host mounts via a
+   *     data-URL derived from the base64 blob + `mimeType` (defaults
+   *     `text/html`).
+   *   - Else → host mounts via `source={{uri}}` — caller is
+   *     responsible for the URI being `http(s)://` (WebView rejects
+   *     non-http schemes via `originWhitelist`).
+   */
+  readonly resource: ResourceContents;
+
+  /**
+   * Locale string forwarded to `ui/initialize.result.hostContext.locale`.
+   * On RN, defaults to `'en-US'` when absent (no `navigator` available).
+   */
+  readonly locale?: string;
+
+  /**
+   * Called when the embedded app sends `ui/update-model-context` —
+   * content the app wants added to the host's model/conversation
+   * context (the ggui renderer sends this on user interaction). When
+   * wired, the request is schema-validated and acked with an empty
+   * result; the host owns delivering the content to its agent. When
+   * absent, the host answers `method_not_supported` — the honest
+   * response for context it would not carry anywhere.
+   */
+  readonly onUpdateModelContext?: (
+    params: import('@modelcontextprotocol/ext-apps').McpUiUpdateModelContextRequest['params'],
+  ) => Promise<void> | void;
+
+  /**
+   * Container-dimensions hint. Mirrored to the View element's style
+   * AND echoed to the iframe via
+   * `ui/initialize.result.hostContext.containerDimensions`.
+   */
+  readonly containerDimensions?: McpAppIframeDimensions;
+
+  /**
+   * Permissions-Policy hint. Passed through to the platform WebView's
+   * media/geolocation gating; does NOT leak into `ui/initialize`.
+   */
+  readonly permissions?: McpAppIframePermissions;
+
+  /**
+   * Opt-in first-party `ai.ggui/render` meta delivery for ggui
+   * renderer WebViews.
+   *
+   * **When set:** the host fires a spec-canonical
+   * `ui/notifications/tool-result` JSON-RPC notification immediately
+   * after responding to the renderer's `ui/initialize` request,
+   * wrapping a `CallToolResult` whose `_meta` carries the single
+   * `ai.ggui/render` slice from the supplied {@link
+   * McpAppAiGguiRenderMeta}. The renderer's `parseMetaFromToolResult`
+   * extractor (`packages/iframe-runtime/src/meta-parse.ts`) reads
+   * `params._meta` and uses it to fetch the renderer bundle, open the
+   * WebSocket, and bootstrap the render. This matches the wire shape
+   * `<AppRenderer toolResult={...}>` forwards on web and the
+   * `McpUiToolResultNotification` shape in
+   * `@modelcontextprotocol/ext-apps/spec.types`. The `ui/initialize`
+   * response itself is unchanged — it carries the adapter-boundary
+   * `{theme, containerDimensions, locale}` fields ONLY.
+   *
+   * **When absent (default):** no `ui/notifications/tool-result`
+   * notification is sent. The renderer falls through to its other
+   * boot paths (inline `__GGUI_META__` global from a self-contained
+   * shell, or the per-app live channel). Third-party MCP App
+   * WebViews MUST NOT be given `meta` here — leaking outer-app state
+   * into a generic MCP App is exactly the adapter-boundary
+   * violation the rule exists to prevent.
+   *
+   * **Rule of thumb:** set this exactly when the WebView was spawned by
+   * following ggui's own resource URI (`ui://ggui/render` or
+   * `ui://ggui/render/<sessionId>` etc.) and the host is responsible
+   * for wiring the meta forward — e.g. the console's
+   * `<McpAppIframe>` mount feeds it the meta fetched from
+   * `GET /ggui/console/session-resource`. Do NOT set this for any
+   * WebView loading content authored outside ggui's render-resource
+   * surface.
+   *
+   * **Recursive case.** The renderer itself hosts third-party MCP App
+   * iframes via `packages/iframe-runtime/src/mcp-app-iframe-host.ts`.
+   * That nested host MUST NOT forward `meta` regardless of the outer
+   * host's posture — first-party meta delivery does NOT cascade
+   * through to third-party content the renderer is itself hosting.
+   */
+  readonly meta?: McpAppAiGguiRenderMeta;
+
+  /**
+   * Caller-provided handler for `tools/call` dispatches from the
+   * iframe. The host forwards `(toolName, args)` and awaits; the
+   * resolved value becomes the JSON-RPC `result`, rejections become
+   * `-32000` errors. Absent handler = every `tools/call` is rejected
+   * with `no-tool-handler`.
+   */
+  readonly onToolCall?: (
+    toolName: string,
+    args: Record<string, unknown>,
+  ) => Promise<unknown>;
+
+  /**
+   * Surfaced on every ProtocolError the host classifies from the
+   * WebView (today: the `ggui:bootstrap-failed` envelope, which also
+   * carries the renderer's version-handshake rejection as reason
+   * `UPGRADE_REQUIRED`). Hosts pattern-match on `err.kind`. Handlers
+   * MUST NOT throw.
+   */
+  readonly onError?: (err: ProtocolError) => void;
+
+  /**
+   * Surfaced for every {@link ObservabilityEvent} the iframe emits
+   * via `postMessage({type:'ggui:observe', event})`. Handlers MUST
+   * tolerate unknown `event.kind` values (extensibly-closed union).
+   */
+  readonly onObserve?: (event: ObservabilityEvent) => void;
+
+  /**
+   * Optional callback for every {@link McpAppLifecycleEvent} the iframe
+   * emits via `postMessage({type:'ggui:lifecycle', event})`.
+   *
+   * Lifecycle is **always mirrored to the outer `<View>`** via
+   * `accessibilityValue={{text: state}}` regardless of whether this
+   * callback is bound — this is the canonical observation surface
+   * (RN equivalent of the web `data-ggui-mcp-app-iframe-lifecycle`
+   * attribute that E2E + console inspectors pin on). On RN, lifecycle
+   * is mirrored via `accessibilityValue={{text: state}}` on the host
+   * `<View>` so RN testing libraries (`@testing-library/react-native`)
+   * can query the same observable surface as web E2E selectors. Hosts
+   * that want richer reactive state should bind `onLifecycle` directly.
+   *
+   * Handlers MUST tolerate any future `state` values per the
+   * `McpAppLifecycleState` closed union — adding a new state requires a
+   * protocol change, but legacy hosts MUST not crash on a state they
+   * don't recognise (the host filters known states before mirroring;
+   * unknown states reach this callback as opaque strings the host
+   * neither mirrors nor blocks).
+   */
+  readonly onLifecycle?: (event: McpAppLifecycleEvent) => void;
+}
+
+/**
+ * Imperative ref shape. Mirror of the web version — keep stable so
+ * host-side tooling (e.g. a test-action panel) works against either
+ * platform.
+ */
+export interface McpAppIframeRef {
+  /**
+   * Dispatch a JSON-RPC notification into the WebView. Fire-and-
+   * forget; the iframe MUST NOT respond.
+   */
+  readonly dispatchAction: (name: string, data: unknown) => void;
+}

package/src/chat-helpers/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure helpers for chat-shaped integrations. Populated in Chunk 1.2.
+ * Do NOT use `export *` here — named re-exports only (parity-test policy).
+ */
+export { useRafThrottled } from './useRafThrottled';
+export { extractRenderFromToolResult, extractSessionIdFromToolResult } from './render';
+export {
+  invokeMessageToContentGroups,
+  contentGroupsToConversationMessages,
+  conversationMessagesToInvokeHistory,
+  type ContentGroup,
+} from './message-groups';