@tanstack/ai-preact 0.9.15 → 0.10.0

package/dist/esm/index.d.ts

@@ -1,3 +1,5 @@
 export { useChat } from './use-chat.js';
+export { useMcpAppBridge } from './use-mcp-app-bridge.js';
+export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.js';
 export type { UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, } from './types.js';
-export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, createChatClientOptions, type ConnectionAdapter, type ConnectConnectionAdapter, type SubscribeConnectionAdapter, type RunAgentInputContext, type FetchConnectionOptions, type XhrConnectionOptions, type InferChatMessages, } from '@tanstack/ai-client';
+export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, createChatClientOptions, createMcpAppBridge, type McpAppBridge, type CreateMcpAppBridgeOptions, type ConnectionAdapter, type ConnectConnectionAdapter, type SubscribeConnectionAdapter, type RunAgentInputContext, type FetchConnectionOptions, type XhrConnectionOptions, type InferChatMessages, } from '@tanstack/ai-client';

package/dist/esm/index.js

@@ -1,12 +1,15 @@
 import { useChat } from "./use-chat.js";
-import { createChatClientOptions, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "@tanstack/ai-client";
+import { useMcpAppBridge } from "./use-mcp-app-bridge.js";
+import { createChatClientOptions, createMcpAppBridge, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "@tanstack/ai-client";
 export {
   createChatClientOptions,
+  createMcpAppBridge,
   fetchHttpStream,
   fetchServerSentEvents,
   rpcStream,
   stream,
   useChat,
+  useMcpAppBridge,
   xhrHttpStream,
   xhrServerSentEvents
 };

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/esm/mcp-apps.d.ts

@@ -0,0 +1,25 @@
+import { UIResourcePart } from '@tanstack/ai';
+import { McpAppBridge } from '@tanstack/ai-client';
+export interface MCPAppResourceProps {
+    /** The ui-resource part from a UIMessage assistant part. */
+    part: UIResourcePart;
+    /**
+     * Framework-agnostic bridge for tool calls, prompt sending, and link opening.
+     * Omit it to render the widget in display-only mode — iframe interactions
+     * that would trigger tool calls or prompts are ignored.
+     */
+    bridge?: McpAppBridge;
+    /** Sandbox iframe configuration — must include the proxy page URL. */
+    sandbox: {
+        url: URL;
+    };
+    /** Optional structured arguments forwarded to the guest UI once it's ready. */
+    toolInput?: Record<string, unknown>;
+}
+/**
+ * Renders an MCP App UI resource inside a sandboxed iframe.
+ *
+ * Wraps `@mcp-ui/client`'s `AppRenderer` and wires its callbacks to a
+ * framework-agnostic {@link McpAppBridge}.
+ */
+export declare function MCPAppResource(props: MCPAppResourceProps): import("preact").JSX.Element;

package/dist/esm/mcp-apps.js

@@ -0,0 +1,52 @@
+import { jsx } from "preact/jsx-runtime";
+import { AppRenderer } from "@mcp-ui/client";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resultToText(result) {
+  if (typeof result === "string") return result;
+  const stringify = JSON.stringify;
+  return stringify(result) ?? "null";
+}
+function MCPAppResource(props) {
+  const { part, bridge, sandbox, toolInput } = props;
+  const onCallTool = bridge ? async (params) => {
+    const result = await bridge.callTool({
+      serverId: part.serverId,
+      toolName: params.name,
+      args: params.arguments
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: resultToText(result)
+        }
+      ],
+      structuredContent: isRecord(result) ? result : void 0
+    };
+  } : void 0;
+  const onMessage = bridge ? async (params) => {
+    const text = params.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+    if (text) await bridge.sendPrompt(text);
+    return {};
+  } : void 0;
+  const onOpenLink = bridge ? (params) => Promise.resolve(bridge.openLink(params.url)) : void 0;
+  return /* @__PURE__ */ jsx(
+    AppRenderer,
+    {
+      toolName: part.toolName,
+      sandbox,
+      html: part.resource.text,
+      toolResourceUri: part.resource.uri,
+      toolInput,
+      onCallTool,
+      onMessage,
+      onOpenLink
+    }
+  );
+}
+export {
+  MCPAppResource
+};
+//# sourceMappingURL=mcp-apps.js.map

package/dist/esm/mcp-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-apps.js","sources":["../../src/mcp-apps.tsx"],"sourcesContent":["/**\n * MCPAppResource — Preact wrapper for rendering MCP App UI resources.\n *\n * PREACT/COMPAT NOTE:\n * `@mcp-ui/client@7.1.1` is published React-only: `AppRenderer` is a React\n * `forwardRef` component. There is NO dedicated preact entry point and NO web\n * component variant. This wrapper imports `{ AppRenderer }` from\n * `'@mcp-ui/client'` identically to the React wrapper and relies on the\n * *consumer's* `preact/compat` alias (resolving `react` / `react-dom` to\n * `preact/compat`) to render the React component under Preact.\n * Wiring up that alias is the consumer's responsibility and is NOT\n * runtime-verified in this repository.\n */\nimport { AppRenderer } from '@mcp-ui/client'\nimport type { AppRendererProps } from '@mcp-ui/client'\nimport type { UIResourcePart } from '@tanstack/ai'\nimport type { McpAppBridge } from '@tanstack/ai-client'\n\nexport interface MCPAppResourceProps {\n  /** The ui-resource part from a UIMessage assistant part. */\n  part: UIResourcePart\n  /**\n   * Framework-agnostic bridge for tool calls, prompt sending, and link opening.\n   * Omit it to render the widget in display-only mode — iframe interactions\n   * that would trigger tool calls or prompts are ignored.\n   */\n  bridge?: McpAppBridge\n  /** Sandbox iframe configuration — must include the proxy page URL. */\n  sandbox: { url: URL }\n  /** Optional structured arguments forwarded to the guest UI once it's ready. */\n  toolInput?: Record<string, unknown>\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Coalesce an arbitrary bridge result into the `string` required by the\n * `CallToolResult` text content block. `JSON.stringify` is typed to return\n * `string` but actually returns `undefined` for inputs like `undefined` or a\n * function, so we narrow explicitly to avoid `text: undefined`.\n */\nfunction resultToText(result: unknown): string {\n  if (typeof result === 'string') return result\n  // `JSON.stringify`'s lib signature claims `string`, but it returns\n  // `undefined` for `undefined`/function inputs; type the call honestly.\n  const stringify: (value: unknown) => string | undefined = JSON.stringify\n  return stringify(result) ?? 'null'\n}\n\n/**\n * Renders an MCP App UI resource inside a sandboxed iframe.\n *\n * Wraps `@mcp-ui/client`'s `AppRenderer` and wires its callbacks to a\n * framework-agnostic {@link McpAppBridge}.\n */\nexport function MCPAppResource(props: MCPAppResourceProps) {\n  const { part, bridge, sandbox, toolInput } = props\n\n  const onCallTool: AppRendererProps['onCallTool'] = bridge\n    ? async (params) => {\n        const result = await bridge.callTool({\n          serverId: part.serverId,\n          toolName: params.name,\n          args: params.arguments,\n        })\n\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: resultToText(result),\n            },\n          ],\n          structuredContent: isRecord(result) ? result : undefined,\n        }\n      }\n    : undefined\n\n  const onMessage: AppRendererProps['onMessage'] = bridge\n    ? async (params) => {\n        const text = params.content\n          .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n          .map((c) => c.text)\n          .join('')\n        if (text) await bridge.sendPrompt(text)\n        return {}\n      }\n    : undefined\n\n  const onOpenLink: AppRendererProps['onOpenLink'] = bridge\n    ? (params) => Promise.resolve(bridge.openLink(params.url))\n    : undefined\n\n  return (\n    <AppRenderer\n      toolName={part.toolName}\n      sandbox={sandbox}\n      html={part.resource.text}\n      toolResourceUri={part.resource.uri}\n      toolInput={toolInput}\n      onCallTool={onCallTool}\n      onMessage={onMessage}\n      onOpenLink={onOpenLink}\n    />\n  )\n}\n"],"names":[],"mappings":";;AAiCA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAQA,SAAS,aAAa,QAAyB;AAC7C,MAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,QAAM,YAAoD,KAAK;AAC/D,SAAO,UAAU,MAAM,KAAK;AAC9B;AAQO,SAAS,eAAe,OAA4B;AACzD,QAAM,EAAE,MAAM,QAAQ,SAAS,cAAc;AAE7C,QAAM,aAA6C,SAC/C,OAAO,WAAW;AAChB,UAAM,SAAS,MAAM,OAAO,SAAS;AAAA,MACnC,UAAU,KAAK;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,MAAM,OAAO;AAAA,IAAA,CACd;AAED,WAAO;AAAA,MACL,SAAS;AAAA,QACP;AAAA,UACE,MAAM;AAAA,UACN,MAAM,aAAa,MAAM;AAAA,QAAA;AAAA,MAC3B;AAAA,MAEF,mBAAmB,SAAS,MAAM,IAAI,SAAS;AAAA,IAAA;AAAA,EAEnD,IACA;AAEJ,QAAM,YAA2C,SAC7C,OAAO,WAAW;AAChB,UAAM,OAAO,OAAO,QACjB,OAAO,CAAC,MAA2C,EAAE,SAAS,MAAM,EACpE,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,EAAE;AACV,QAAI,KAAM,OAAM,OAAO,WAAW,IAAI;AACtC,WAAO,CAAA;AAAA,EACT,IACA;AAEJ,QAAM,aAA6C,SAC/C,CAAC,WAAW,QAAQ,QAAQ,OAAO,SAAS,OAAO,GAAG,CAAC,IACvD;AAEJ,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,UAAU,KAAK;AAAA,MACf;AAAA,MACA,MAAM,KAAK,SAAS;AAAA,MACpB,iBAAiB,KAAK,SAAS;AAAA,MAC/B;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAAA;AAGN;"}

package/dist/esm/use-mcp-app-bridge.d.ts

@@ -0,0 +1,25 @@
+import { CreateMcpAppBridgeOptions, McpAppBridge } from '@tanstack/ai-client';
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions;
+/**
+ * Preact wrapper around `createMcpAppBridge` that returns a **stable** bridge for
+ * the given `threadId`/`callEndpoint`, while always invoking the latest
+ * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating
+ * the bridge on every render and the stale-closure / `exhaustive-deps` dance
+ * you'd otherwise write by hand:
+ *
+ * ```tsx
+ * const { sendMessage } = useChat({ threadId, connection })
+ * const bridge = useMcpAppBridge({
+ *   threadId,
+ *   callEndpoint: '/api/mcp-apps-call',
+ *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ * })
+ * // pass `bridge` to <MCPAppResource bridge={bridge} … />
+ * ```
+ *
+ * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or
+ * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`
+ * each render does not churn it.
+ */
+export declare function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge;

package/dist/esm/use-mcp-app-bridge.js

@@ -0,0 +1,26 @@
+import { useRef, useMemo } from "preact/hooks";
+import { createMcpAppBridge } from "@tanstack/ai-client";
+function useMcpAppBridge(options) {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options;
+  const chatRef = useRef(chat);
+  chatRef.current = chat;
+  const onLinkRef = useRef(onLink);
+  onLinkRef.current = onLink;
+  const hasOnLink = onLink != null;
+  return useMemo(
+    () => createMcpAppBridge({
+      threadId,
+      callEndpoint,
+      fetchImpl,
+      chat: {
+        sendMessage: (content, body) => chatRef.current.sendMessage(content, body)
+      },
+      onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : void 0
+    }),
+    [threadId, callEndpoint, fetchImpl, hasOnLink]
+  );
+}
+export {
+  useMcpAppBridge
+};
+//# sourceMappingURL=use-mcp-app-bridge.js.map

package/dist/esm/use-mcp-app-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mcp-app-bridge.js","sources":["../../src/use-mcp-app-bridge.ts"],"sourcesContent":["import { useMemo, useRef } from 'preact/hooks'\nimport { createMcpAppBridge } from '@tanstack/ai-client'\nimport type {\n  CreateMcpAppBridgeOptions,\n  McpAppBridge,\n} from '@tanstack/ai-client'\n\nexport type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions\n\n/**\n * Preact wrapper around `createMcpAppBridge` that returns a **stable** bridge for\n * the given `threadId`/`callEndpoint`, while always invoking the latest\n * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating\n * the bridge on every render and the stale-closure / `exhaustive-deps` dance\n * you'd otherwise write by hand:\n *\n * ```tsx\n * const { sendMessage } = useChat({ threadId, connection })\n * const bridge = useMcpAppBridge({\n *   threadId,\n *   callEndpoint: '/api/mcp-apps-call',\n *   chat: { sendMessage: async (content) => void sendMessage(content) },\n *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),\n * })\n * // pass `bridge` to <MCPAppResource bridge={bridge} … />\n * ```\n *\n * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or\n * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`\n * each render does not churn it.\n */\nexport function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {\n  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options\n\n  // Latest-value refs so the bridge identity stays stable but its callbacks are\n  // never stale (the bridge calls `.current` at invocation time, not creation).\n  const chatRef = useRef(chat)\n  chatRef.current = chat\n  const onLinkRef = useRef(onLink)\n  onLinkRef.current = onLink\n\n  // Whether a link handler was supplied governs the bridge's link behavior\n  // (forward vs. display-only warn), so it's part of the bridge's identity.\n  const hasOnLink = onLink != null\n\n  return useMemo(\n    () =>\n      createMcpAppBridge({\n        threadId,\n        callEndpoint,\n        fetchImpl,\n        chat: {\n          sendMessage: (content, body) =>\n            chatRef.current.sendMessage(content, body),\n        },\n        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,\n      }),\n    [threadId, callEndpoint, fetchImpl, hasOnLink],\n  )\n}\n"],"names":[],"mappings":";;AA+BO,SAAS,gBAAgB,SAA+C;AAC7E,QAAM,EAAE,UAAU,cAAc,MAAM,WAAW,WAAW;AAI5D,QAAM,UAAU,OAAO,IAAI;AAC3B,UAAQ,UAAU;AAClB,QAAM,YAAY,OAAO,MAAM;AAC/B,YAAU,UAAU;AAIpB,QAAM,YAAY,UAAU;AAE5B,SAAO;AAAA,IACL,MACE,mBAAmB;AAAA,MACjB;AAAA,MACA;AAAA,MACA;AAAA,MACA,MAAM;AAAA,QACJ,aAAa,CAAC,SAAS,SACrB,QAAQ,QAAQ,YAAY,SAAS,IAAI;AAAA,MAAA;AAAA,MAE7C,QAAQ,YAAY,CAAC,QAAQ,UAAU,UAAU,GAAG,IAAI;AAAA,IAAA,CACzD;AAAA,IACH,CAAC,UAAU,cAAc,WAAW,SAAS;AAAA,EAAA;AAEjD;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-preact",
-  "version": "0.9.15",
+  "version": "0.10.0",
   "description": "Preact hooks for TanStack AI streaming chat and typed messages.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -24,6 +24,10 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./mcp-apps": {
+      "types": "./dist/esm/mcp-apps.d.ts",
+      "import": "./dist/esm/mcp-apps.js"
     }
   },
   "files": [
@@ -42,18 +46,26 @@
     "tool-calling"
   ],
   "dependencies": {
-    "@tanstack/ai-client": "0.18.6"
+    "@tanstack/ai-client": "0.19.0"
   },
   "devDependencies": {
+    "@mcp-ui/client": "^7.1.1",
     "@testing-library/preact": "^3.2.4",
     "@vitest/coverage-v8": "4.0.14",
     "jsdom": "^27.2.0",
     "preact": "^10.26.9",
-    "vite": "^7.3.3"
+    "vite": "^7.3.3",
+    "@tanstack/ai": "0.38.0"
   },
   "peerDependencies": {
+    "@mcp-ui/client": "^7",
     "preact": ">=10.11.0",
-    "@tanstack/ai": "^0.37.0"
+    "@tanstack/ai": "^0.38.0"
+  },
+  "peerDependenciesMeta": {
+    "@mcp-ui/client": {
+      "optional": true
+    }
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/src/index.ts

@@ -1,4 +1,6 @@
 export { useChat } from './use-chat'
+export { useMcpAppBridge } from './use-mcp-app-bridge'
+export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge'
 export type {
   UseChatOptions,
   UseChatReturn,
@@ -14,6 +16,9 @@ export {
   stream,
   rpcStream,
   createChatClientOptions,
+  createMcpAppBridge,
+  type McpAppBridge,
+  type CreateMcpAppBridgeOptions,
   type ConnectionAdapter,
   type ConnectConnectionAdapter,
   type SubscribeConnectionAdapter,

package/src/mcp-apps.tsx

@@ -0,0 +1,108 @@
+/**
+ * MCPAppResource — Preact wrapper for rendering MCP App UI resources.
+ *
+ * PREACT/COMPAT NOTE:
+ * `@mcp-ui/client@7.1.1` is published React-only: `AppRenderer` is a React
+ * `forwardRef` component. There is NO dedicated preact entry point and NO web
+ * component variant. This wrapper imports `{ AppRenderer }` from
+ * `'@mcp-ui/client'` identically to the React wrapper and relies on the
+ * *consumer's* `preact/compat` alias (resolving `react` / `react-dom` to
+ * `preact/compat`) to render the React component under Preact.
+ * Wiring up that alias is the consumer's responsibility and is NOT
+ * runtime-verified in this repository.
+ */
+import { AppRenderer } from '@mcp-ui/client'
+import type { AppRendererProps } from '@mcp-ui/client'
+import type { UIResourcePart } from '@tanstack/ai'
+import type { McpAppBridge } from '@tanstack/ai-client'
+
+export interface MCPAppResourceProps {
+  /** The ui-resource part from a UIMessage assistant part. */
+  part: UIResourcePart
+  /**
+   * Framework-agnostic bridge for tool calls, prompt sending, and link opening.
+   * Omit it to render the widget in display-only mode — iframe interactions
+   * that would trigger tool calls or prompts are ignored.
+   */
+  bridge?: McpAppBridge
+  /** Sandbox iframe configuration — must include the proxy page URL. */
+  sandbox: { url: URL }
+  /** Optional structured arguments forwarded to the guest UI once it's ready. */
+  toolInput?: Record<string, unknown>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Coalesce an arbitrary bridge result into the `string` required by the
+ * `CallToolResult` text content block. `JSON.stringify` is typed to return
+ * `string` but actually returns `undefined` for inputs like `undefined` or a
+ * function, so we narrow explicitly to avoid `text: undefined`.
+ */
+function resultToText(result: unknown): string {
+  if (typeof result === 'string') return result
+  // `JSON.stringify`'s lib signature claims `string`, but it returns
+  // `undefined` for `undefined`/function inputs; type the call honestly.
+  const stringify: (value: unknown) => string | undefined = JSON.stringify
+  return stringify(result) ?? 'null'
+}
+
+/**
+ * Renders an MCP App UI resource inside a sandboxed iframe.
+ *
+ * Wraps `@mcp-ui/client`'s `AppRenderer` and wires its callbacks to a
+ * framework-agnostic {@link McpAppBridge}.
+ */
+export function MCPAppResource(props: MCPAppResourceProps) {
+  const { part, bridge, sandbox, toolInput } = props
+
+  const onCallTool: AppRendererProps['onCallTool'] = bridge
+    ? async (params) => {
+        const result = await bridge.callTool({
+          serverId: part.serverId,
+          toolName: params.name,
+          args: params.arguments,
+        })
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: resultToText(result),
+            },
+          ],
+          structuredContent: isRecord(result) ? result : undefined,
+        }
+      }
+    : undefined
+
+  const onMessage: AppRendererProps['onMessage'] = bridge
+    ? async (params) => {
+        const text = params.content
+          .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+          .map((c) => c.text)
+          .join('')
+        if (text) await bridge.sendPrompt(text)
+        return {}
+      }
+    : undefined
+
+  const onOpenLink: AppRendererProps['onOpenLink'] = bridge
+    ? (params) => Promise.resolve(bridge.openLink(params.url))
+    : undefined
+
+  return (
+    <AppRenderer
+      toolName={part.toolName}
+      sandbox={sandbox}
+      html={part.resource.text}
+      toolResourceUri={part.resource.uri}
+      toolInput={toolInput}
+      onCallTool={onCallTool}
+      onMessage={onMessage}
+      onOpenLink={onOpenLink}
+    />
+  )
+}

package/src/use-mcp-app-bridge.ts

@@ -0,0 +1,60 @@
+import { useMemo, useRef } from 'preact/hooks'
+import { createMcpAppBridge } from '@tanstack/ai-client'
+import type {
+  CreateMcpAppBridgeOptions,
+  McpAppBridge,
+} from '@tanstack/ai-client'
+
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
+
+/**
+ * Preact wrapper around `createMcpAppBridge` that returns a **stable** bridge for
+ * the given `threadId`/`callEndpoint`, while always invoking the latest
+ * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating
+ * the bridge on every render and the stale-closure / `exhaustive-deps` dance
+ * you'd otherwise write by hand:
+ *
+ * ```tsx
+ * const { sendMessage } = useChat({ threadId, connection })
+ * const bridge = useMcpAppBridge({
+ *   threadId,
+ *   callEndpoint: '/api/mcp-apps-call',
+ *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ * })
+ * // pass `bridge` to <MCPAppResource bridge={bridge} … />
+ * ```
+ *
+ * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or
+ * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`
+ * each render does not churn it.
+ */
+export function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options
+
+  // Latest-value refs so the bridge identity stays stable but its callbacks are
+  // never stale (the bridge calls `.current` at invocation time, not creation).
+  const chatRef = useRef(chat)
+  chatRef.current = chat
+  const onLinkRef = useRef(onLink)
+  onLinkRef.current = onLink
+
+  // Whether a link handler was supplied governs the bridge's link behavior
+  // (forward vs. display-only warn), so it's part of the bridge's identity.
+  const hasOnLink = onLink != null
+
+  return useMemo(
+    () =>
+      createMcpAppBridge({
+        threadId,
+        callEndpoint,
+        fetchImpl,
+        chat: {
+          sendMessage: (content, body) =>
+            chatRef.current.sendMessage(content, body),
+        },
+        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,
+      }),
+    [threadId, callEndpoint, fetchImpl, hasOnLink],
+  )
+}