@tanstack/ai-preact 0.9.14 → 0.10.0

package/dist/esm/index.d.ts

@@ -0,0 +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, 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

@@ -0,0 +1,16 @@
+import { useChat } from "./use-chat.js";
+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
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"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/types.d.ts

@@ -0,0 +1,106 @@
+import { AnyClientTool, ModelMessage, SchemaInput } from '@tanstack/ai';
+import { AIDevtoolsDisplayOptions, ChatClientOptions, ChatClientState, ChatRequestBody, ClientContextOptionFromTools, ConnectionStatus, DistributedOmit, InferredClientContext, MultimodalContent, UIMessage } from '@tanstack/ai-client';
+export type { ChatRequestBody, MultimodalContent, UIMessage };
+/**
+ * Options for the useChat hook.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by Preact state:
+ * - `onMessagesChange` - Managed by Preact state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by Preact state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by Preact state (exposed as `error`)
+ * - `onStatusChange` - Managed by Preact state (exposed as `status`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * Note: Connection and body changes will recreate the ChatClient instance.
+ * To update these options, remount the component or use a key prop.
+ */
+export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = InferredClientContext<TTools>> = DistributedOmit<ChatClientOptions<TTools, TContext>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange' | 'onStatusChange' | 'onSubscriptionChange' | 'onConnectionStatusChange' | 'onSessionGeneratingChange' | 'context' | 'devtools'> & {
+    live?: boolean;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Standard-schema-compatible schema used to identify structured-output chat
+     * hooks in devtools. Preact currently exposes structured-output parts via
+     * `messages`; typed `partial` / `final` sugar is implemented in the other
+     * framework adapters.
+     */
+    outputSchema?: SchemaInput;
+} & ClientContextOptionFromTools<TTools, TContext>;
+export interface UseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
+    /**
+     * Current messages in the conversation
+     */
+    messages: Array<UIMessage<TTools>>;
+    /**
+     * Send a message and get a response.
+     * Can be a simple string or multimodal content with images, audio, etc.
+     */
+    sendMessage: (content: string | MultimodalContent) => Promise<void>;
+    /**
+     * Append a message to the conversation
+     */
+    append: (message: ModelMessage | UIMessage<TTools>) => Promise<void>;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult: (result: {
+        toolCallId: string;
+        tool: string;
+        output: unknown;
+        state?: 'output-available' | 'output-error';
+        errorText?: string;
+    }) => Promise<void>;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse: (response: {
+        id: string;
+        approved: boolean;
+    }) => Promise<void>;
+    /**
+     * Reload the last assistant message
+     */
+    reload: () => Promise<void>;
+    /**
+     * Stop the current response generation
+     */
+    stop: () => void;
+    /**
+     * Whether a response is currently being generated
+     */
+    isLoading: boolean;
+    /**
+     * Current error, if any
+     */
+    error: Error | undefined;
+    /**
+     * Set messages manually
+     */
+    setMessages: (messages: Array<UIMessage<TTools>>) => void;
+    /**
+     * Clear all messages
+     */
+    clear: () => void;
+    /**
+     * Current generation status
+     */
+    status: ChatClientState;
+    /**
+     * Whether the subscription loop is currently active
+     */
+    isSubscribed: boolean;
+    /**
+     * Current connection lifecycle status
+     */
+    connectionStatus: ConnectionStatus;
+    /**
+     * Whether the shared session is actively generating.
+     * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+     * Unlike `isLoading` (request-local), this reflects shared generation
+     * activity visible to all subscribers (e.g. across tabs/devices).
+     */
+    sessionGenerating: boolean;
+}

package/dist/esm/use-chat.d.ts

@@ -0,0 +1,4 @@
+import { InferredClientContext } from '@tanstack/ai-client';
+import { AnyClientTool } from '@tanstack/ai';
+import { UseChatOptions, UseChatReturn } from './types.js';
+export declare function useChat<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = InferredClientContext<TTools>>(options: UseChatOptions<TTools, TContext>): UseChatReturn<TTools>;

package/dist/esm/use-chat.js

@@ -0,0 +1,224 @@
+import { ChatClient } from "@tanstack/ai-client";
+import { createChatDevtoolsBridge } from "@tanstack/ai-client/devtools";
+import { useId, useState, useRef, useEffect, useMemo, useCallback } from "preact/hooks";
+function useChat(options) {
+  const hookId = useId();
+  const clientId = options.id || hookId;
+  const [messages, setMessages] = useState(
+    options.initialMessages || []
+  );
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(void 0);
+  const [status, setStatus] = useState("ready");
+  const [isSubscribed, setIsSubscribed] = useState(false);
+  const [connectionStatus, setConnectionStatus] = useState("disconnected");
+  const [sessionGenerating, setSessionGenerating] = useState(false);
+  const messagesRef = useRef(
+    options.initialMessages || []
+  );
+  const isFirstMountRef = useRef(true);
+  const activeClientRef = useRef(null);
+  const cleanupInvalidationRef = useRef(
+    null
+  );
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+  const client = useMemo(() => {
+    const messagesToUse = options.initialMessages || [];
+    isFirstMountRef.current = false;
+    const initialOptions = optionsRef.current;
+    const transport = initialOptions.connection ? { connection: initialOptions.connection } : { fetcher: initialOptions.fetcher };
+    const instance = new ChatClient({
+      devtoolsBridgeFactory: createChatDevtoolsBridge,
+      ...transport,
+      id: clientId,
+      initialMessages: messagesToUse,
+      ...initialOptions.body !== void 0 && { body: initialOptions.body },
+      ...initialOptions.threadId !== void 0 && {
+        threadId: initialOptions.threadId
+      },
+      ...initialOptions.forwardedProps !== void 0 && {
+        forwardedProps: initialOptions.forwardedProps
+      },
+      ...initialOptions.persistence !== void 0 && {
+        persistence: initialOptions.persistence
+      },
+      ...initialOptions.context !== void 0 && {
+        context: initialOptions.context
+      },
+      devtools: {
+        ...initialOptions.devtools,
+        framework: "preact",
+        hookName: "useChat",
+        outputKind: initialOptions.outputSchema ? "structured" : "chat"
+      },
+      // Wrap every callback so the latest options are read at call time.
+      // Capturing the function reference directly would freeze it to whatever
+      // the parent passed on the first render.
+      onResponse: (response) => {
+        if (activeClientRef.current !== instance) return;
+        return optionsRef.current.onResponse?.(response);
+      },
+      onChunk: (chunk) => {
+        if (activeClientRef.current !== instance) return;
+        optionsRef.current.onChunk?.(chunk);
+      },
+      onFinish: (message) => {
+        if (activeClientRef.current !== instance) return;
+        optionsRef.current.onFinish?.(message);
+      },
+      onError: (err) => {
+        if (activeClientRef.current !== instance) return;
+        optionsRef.current.onError?.(err);
+      },
+      onCustomEvent: (eventType, data, context) => {
+        if (activeClientRef.current !== instance) return;
+        optionsRef.current.onCustomEvent?.(eventType, data, context);
+      },
+      ...initialOptions.tools !== void 0 && {
+        tools: initialOptions.tools
+      },
+      ...options.streamProcessor !== void 0 && {
+        streamProcessor: options.streamProcessor
+      },
+      onMessagesChange: (newMessages) => {
+        if (activeClientRef.current !== instance) return;
+        setMessages(newMessages);
+      },
+      onLoadingChange: (newIsLoading) => {
+        if (activeClientRef.current !== instance) return;
+        setIsLoading(newIsLoading);
+      },
+      onStatusChange: (newStatus) => {
+        if (activeClientRef.current !== instance) return;
+        setStatus(newStatus);
+      },
+      onErrorChange: (newError) => {
+        if (activeClientRef.current !== instance) return;
+        setError(newError);
+      },
+      onSubscriptionChange: (nextIsSubscribed) => {
+        if (activeClientRef.current !== instance) return;
+        setIsSubscribed(nextIsSubscribed);
+      },
+      onConnectionStatusChange: (nextStatus) => {
+        if (activeClientRef.current !== instance) return;
+        setConnectionStatus(nextStatus);
+      },
+      onSessionGeneratingChange: (isGenerating) => {
+        if (activeClientRef.current !== instance) return;
+        setSessionGenerating(isGenerating);
+      }
+    });
+    activeClientRef.current = instance;
+    return instance;
+  }, [clientId]);
+  useEffect(() => {
+    const clientMessages = client.getMessages();
+    if (clientMessages !== messagesRef.current) {
+      setMessages(clientMessages);
+    }
+  }, [client]);
+  useEffect(() => {
+    client.updateOptions({
+      body: options.body,
+      ...options.forwardedProps !== void 0 && {
+        forwardedProps: options.forwardedProps
+      },
+      context: options.context
+    });
+  }, [client, options.body, options.forwardedProps, options.context]);
+  useEffect(() => {
+    if (options.live) {
+      client.subscribe();
+    } else {
+      client.unsubscribe();
+    }
+  }, [client, options.live]);
+  useEffect(() => {
+    if (cleanupInvalidationRef.current) {
+      clearTimeout(cleanupInvalidationRef.current);
+      cleanupInvalidationRef.current = null;
+    }
+    activeClientRef.current = client;
+    client.mountDevtools();
+    return () => {
+      cleanupInvalidationRef.current = setTimeout(() => {
+        if (activeClientRef.current === client) {
+          activeClientRef.current = null;
+        }
+        cleanupInvalidationRef.current = null;
+      }, 0);
+      if (optionsRef.current.live) {
+        client.unsubscribe();
+      } else {
+        client.stop();
+      }
+      client.dispose();
+    };
+  }, [client]);
+  const sendMessage = useCallback(
+    async (content) => {
+      await client.sendMessage(content);
+    },
+    [client]
+  );
+  const append = useCallback(
+    async (message) => {
+      await client.append(message);
+    },
+    [client]
+  );
+  const reload = useCallback(async () => {
+    await client.reload();
+  }, [client]);
+  const stop = useCallback(() => {
+    client.stop();
+  }, [client]);
+  const clear = useCallback(() => {
+    client.clear();
+  }, [client]);
+  const setMessagesManually = useCallback(
+    (newMessages) => {
+      client.setMessagesManually(newMessages);
+    },
+    [client]
+  );
+  const addToolResult = useCallback(
+    async (result) => {
+      await client.addToolResult(result);
+    },
+    [client]
+  );
+  const addToolApprovalResponse = useCallback(
+    async (response) => {
+      await client.addToolApprovalResponse(response);
+    },
+    [client]
+  );
+  const renderedMessages = client.getMessages();
+  return {
+    messages: renderedMessages,
+    sendMessage,
+    append,
+    reload,
+    stop,
+    isLoading,
+    error,
+    status,
+    isSubscribed,
+    connectionStatus,
+    sessionGenerating,
+    setMessages: setMessagesManually,
+    clear,
+    addToolResult,
+    addToolApprovalResponse
+  };
+}
+export {
+  useChat
+};
+//# sourceMappingURL=use-chat.js.map

package/dist/esm/use-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chat.js","sources":["../../src/use-chat.ts"],"sourcesContent":["import { ChatClient } from '@tanstack/ai-client'\nimport { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport {\n  useCallback,\n  useEffect,\n  useId,\n  useMemo,\n  useRef,\n  useState,\n} from 'preact/hooks'\nimport type {\n  ChatClientState,\n  ConnectionStatus,\n  InferredClientContext,\n} from '@tanstack/ai-client'\nimport type { AnyClientTool, ModelMessage } from '@tanstack/ai'\n\nimport type {\n  MultimodalContent,\n  UIMessage,\n  UseChatOptions,\n  UseChatReturn,\n} from './types'\n\nexport function useChat<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = InferredClientContext<TTools>,\n>(options: UseChatOptions<TTools, TContext>): UseChatReturn<TTools> {\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<ChatClientState>('ready')\n  const [isSubscribed, setIsSubscribed] = useState(false)\n  const [connectionStatus, setConnectionStatus] =\n    useState<ConnectionStatus>('disconnected')\n  const [sessionGenerating, setSessionGenerating] = useState(false)\n\n  // Track current messages in a ref to preserve them when client is recreated\n  const messagesRef = useRef<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const isFirstMountRef = useRef(true)\n  const activeClientRef = useRef<ChatClient | null>(null)\n  const cleanupInvalidationRef = useRef<ReturnType<typeof setTimeout> | null>(\n    null,\n  )\n  const optionsRef = useRef<UseChatOptions<TTools, TContext>>(options)\n\n  optionsRef.current = options\n\n  useEffect(() => {\n    messagesRef.current = messages\n  }, [messages])\n\n  const client = useMemo(() => {\n    const messagesToUse = options.initialMessages || []\n    isFirstMountRef.current = false\n\n    // Build options with conditional spreads for fields whose source\n    // type is `T | undefined` but the ChatClient target uses a strict\n    // optional (`field?: T`) — `exactOptionalPropertyTypes` rejects\n    // assigning `undefined` to those, so we omit the key when absent.\n    const initialOptions = optionsRef.current\n    const transport = initialOptions.connection\n      ? { connection: initialOptions.connection }\n      : { fetcher: initialOptions.fetcher }\n\n    const instance = new ChatClient<TTools, TContext>({\n      devtoolsBridgeFactory: createChatDevtoolsBridge,\n      ...transport,\n      id: clientId,\n      initialMessages: messagesToUse,\n      ...(initialOptions.body !== undefined && { body: initialOptions.body }),\n      ...(initialOptions.threadId !== undefined && {\n        threadId: initialOptions.threadId,\n      }),\n      ...(initialOptions.forwardedProps !== undefined && {\n        forwardedProps: initialOptions.forwardedProps,\n      }),\n      ...(initialOptions.persistence !== undefined && {\n        persistence: initialOptions.persistence,\n      }),\n      ...(initialOptions.context !== undefined && {\n        context: initialOptions.context,\n      }),\n      devtools: {\n        ...initialOptions.devtools,\n        framework: 'preact',\n        hookName: 'useChat',\n        outputKind: initialOptions.outputSchema ? 'structured' : 'chat',\n      },\n      // Wrap every callback so the latest options are read at call time.\n      // Capturing the function reference directly would freeze it to whatever\n      // the parent passed on the first render.\n      onResponse: (response) => {\n        if (activeClientRef.current !== instance) return\n        return optionsRef.current.onResponse?.(response)\n      },\n      onChunk: (chunk) => {\n        if (activeClientRef.current !== instance) return\n        optionsRef.current.onChunk?.(chunk)\n      },\n      onFinish: (message) => {\n        if (activeClientRef.current !== instance) return\n        optionsRef.current.onFinish?.(message)\n      },\n      onError: (err) => {\n        if (activeClientRef.current !== instance) return\n        optionsRef.current.onError?.(err)\n      },\n      onCustomEvent: (eventType, data, context) => {\n        if (activeClientRef.current !== instance) return\n        optionsRef.current.onCustomEvent?.(eventType, data, context)\n      },\n      ...(initialOptions.tools !== undefined && {\n        tools: initialOptions.tools,\n      }),\n      ...(options.streamProcessor !== undefined && {\n        streamProcessor: options.streamProcessor,\n      }),\n      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {\n        if (activeClientRef.current !== instance) return\n        setMessages(newMessages)\n      },\n      onLoadingChange: (newIsLoading: boolean) => {\n        if (activeClientRef.current !== instance) return\n        setIsLoading(newIsLoading)\n      },\n      onStatusChange: (newStatus: ChatClientState) => {\n        if (activeClientRef.current !== instance) return\n        setStatus(newStatus)\n      },\n      onErrorChange: (newError: Error | undefined) => {\n        if (activeClientRef.current !== instance) return\n        setError(newError)\n      },\n      onSubscriptionChange: (nextIsSubscribed: boolean) => {\n        if (activeClientRef.current !== instance) return\n        setIsSubscribed(nextIsSubscribed)\n      },\n      onConnectionStatusChange: (nextStatus: ConnectionStatus) => {\n        if (activeClientRef.current !== instance) return\n        setConnectionStatus(nextStatus)\n      },\n      onSessionGeneratingChange: (isGenerating: boolean) => {\n        if (activeClientRef.current !== instance) return\n        setSessionGenerating(isGenerating)\n      },\n    })\n    activeClientRef.current = instance\n    return instance\n  }, [clientId])\n\n  useEffect(() => {\n    const clientMessages = client.getMessages()\n    if (clientMessages !== messagesRef.current) {\n      setMessages(clientMessages)\n    }\n  }, [client])\n\n  // Sync body / forwardedProps changes to the client.\n  // Both populate the same wire payload; `forwardedProps` is preferred\n  // and `body` is deprecated but still supported.\n  useEffect(() => {\n    // Conditional spread: `updateOptions` declares strict-optional\n    // fields and rejects explicit `undefined` under EOPT.\n    client.updateOptions({\n      body: options.body,\n      ...(options.forwardedProps !== undefined && {\n        forwardedProps: options.forwardedProps,\n      }),\n      context: options.context,\n    })\n  }, [client, options.body, options.forwardedProps, options.context])\n\n  useEffect(() => {\n    if (options.live) {\n      client.subscribe()\n    } else {\n      client.unsubscribe()\n    }\n  }, [client, options.live])\n\n  // Cleanup on unmount: stop any in-flight requests\n  // Note: We only cleanup when client changes or component unmounts.\n  // DO NOT include isLoading in dependencies - that would cause the cleanup\n  // to run when isLoading changes, aborting continuation requests.\n  useEffect(() => {\n    if (cleanupInvalidationRef.current) {\n      clearTimeout(cleanupInvalidationRef.current)\n      cleanupInvalidationRef.current = null\n    }\n    activeClientRef.current = client\n    client.mountDevtools()\n\n    return () => {\n      cleanupInvalidationRef.current = setTimeout(() => {\n        if (activeClientRef.current === client) {\n          activeClientRef.current = null\n        }\n        cleanupInvalidationRef.current = null\n      }, 0)\n      // Subscribe/unsubscribe on `options.live` is owned by the dedicated\n      // effect above. This cleanup only fires on unmount or client swap,\n      // so read `live` through the ref to avoid disposing the client every\n      // time `live` toggles.\n      if (optionsRef.current.live) {\n        client.unsubscribe()\n      } else {\n        client.stop()\n      }\n      client.dispose()\n    }\n  }, [client])\n\n  // All callback options are read through optionsRef at call time, so fresh\n  // closures from each render are picked up without recreating the client.\n  const sendMessage = useCallback(\n    async (content: string | MultimodalContent) => {\n      await client.sendMessage(content)\n    },\n    [client],\n  )\n\n  const append = useCallback(\n    async (message: ModelMessage | UIMessage) => {\n      await client.append(message)\n    },\n    [client],\n  )\n\n  const reload = useCallback(async () => {\n    await client.reload()\n  }, [client])\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const clear = useCallback(() => {\n    client.clear()\n  }, [client])\n\n  const setMessagesManually = useCallback(\n    (newMessages: Array<UIMessage<TTools>>) => {\n      client.setMessagesManually(newMessages)\n    },\n    [client],\n  )\n\n  const addToolResult = useCallback(\n    async (result: {\n      toolCallId: string\n      tool: string\n      output: unknown\n      state?: 'output-available' | 'output-error'\n      errorText?: string\n    }) => {\n      await client.addToolResult(result)\n    },\n    [client],\n  )\n\n  const addToolApprovalResponse = useCallback(\n    async (response: { id: string; approved: boolean }) => {\n      await client.addToolApprovalResponse(response)\n    },\n    [client],\n  )\n\n  const renderedMessages = client.getMessages()\n\n  return {\n    messages: renderedMessages,\n    sendMessage,\n    append,\n    reload,\n    stop,\n    isLoading,\n    error,\n    status,\n    isSubscribed,\n    connectionStatus,\n    sessionGenerating,\n    setMessages: setMessagesManually,\n    clear,\n    addToolResult,\n    addToolApprovalResponse,\n  }\n}\n"],"names":[],"mappings":"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"}

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.14",
+  "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.5"
+    "@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.36.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],
+  )
+}