@tanstack/ai-solid 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,437 @@
+# @tanstack/ai-react
+
+React hooks for building AI chat interfaces with TanStack AI.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-react @tanstack/ai-client
+```
+
+## useChat Hook
+
+The `useChat` hook manages chat state, handles streaming responses, and provides a complete chat interface in a single hook.
+
+**Design Philosophy (v5 API):**
+
+- You control input state
+- Just call `sendMessage()` when ready
+- No form-centric API - use buttons, keyboard events, or any trigger
+- More flexible and less opinionated
+
+### Basic Usage
+
+```typescript
+import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
+import { useState } from "react";
+
+function ChatComponent() {
+  const { messages, sendMessage, isLoading } = useChat({
+    connection: fetchServerSentEvents("/api/chat"),
+  });
+
+  const [input, setInput] = useState("");
+
+  const handleSend = () => {
+    sendMessage(input);
+    setInput("");
+  };
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        onKeyDown={(e) => e.key === "Enter" && handleSend()}
+        disabled={isLoading}
+      />
+      <button onClick={handleSend} disabled={isLoading || !input.trim()}>
+        Send
+      </button>
+    </div>
+  );
+}
+```
+
+### API
+
+#### Options
+
+```typescript
+interface UseChatOptions {
+  // Connection adapter (required)
+  connection: ConnectionAdapter
+
+  // Configuration
+  initialMessages?: UIMessage[] // Starting messages
+  id?: string // Unique chat ID
+  body?: Record<string, any> // Extra data to send
+
+  // Callbacks
+  onResponse?: (response?: Response) => void
+  onChunk?: (chunk: StreamChunk) => void
+  onFinish?: (message: UIMessage) => void
+  onError?: (error: Error) => void
+}
+```
+
+#### Return Value
+
+```typescript
+interface UseChatReturn {
+  messages: UIMessage[] // Current conversation
+  sendMessage: (content: string) => Promise<void> // Send a message
+  append: (message) => Promise<void> // Add message programmatically
+  reload: () => Promise<void> // Reload last response
+  stop: () => void // Stop current generation
+  isLoading: boolean // Is generating a response
+  error: Error | undefined // Current error
+  setMessages: (messages) => void // Set messages manually
+  clear: () => void // Clear all messages
+}
+```
+
+## Connection Adapters
+
+Connection adapters provide flexible streaming for different scenarios. See the complete guides:
+
+- 📖 [Connection Adapters Guide](../../docs/CONNECTION_ADAPTERS_GUIDE.md) - Complete guide with examples
+- 📖 [Connection Adapters API](../ai-client/CONNECTION_ADAPTERS.md) - API reference
+
+### Quick Examples
+
+**SSE (Most Common):**
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const chat = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+})
+```
+
+**Server Functions:**
+
+```typescript
+import { useChat, stream } from '@tanstack/ai-react'
+
+const chat = useChat({
+  connection: stream((messages) => serverChatFunction({ messages })),
+})
+```
+
+**Custom (e.g., WebSockets):**
+
+```typescript
+import { useChat } from '@tanstack/ai-react'
+import type { ConnectionAdapter } from '@tanstack/ai-client'
+
+const wsAdapter: ConnectionAdapter = {
+  async *connect(messages) {
+    // Your WebSocket logic
+  },
+}
+
+const chat = useChat({ connection: wsAdapter })
+```
+
+### Backend Endpoint
+
+Your backend should use the `chat()` method which **automatically handles tool execution in a loop**:
+
+1. Receive POST requests with this body:
+
+```typescript
+{
+  messages: Message[];
+  data?: Record<string, any>;
+}
+```
+
+2. Use `chat()` to stream responses (with automatic tool execution):
+
+```typescript
+import { chat, toStreamResponse } from '@tanstack/ai'
+import { openai } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openai(),
+    model: 'gpt-4o',
+    messages,
+    tools: [weatherTool], // Optional: auto-executed in loop
+    agentLoopStrategy: maxIterations(5), // Optional: control loop
+  })
+
+  // Convert to HTTP streaming response with SSE headers
+  return toStreamResponse(stream)
+}
+```
+
+The response streams `StreamChunk` objects as Server-Sent Events:
+
+```
+data: {"type":"content","delta":"Hello","content":"Hello",...}
+data: {"type":"tool_call","toolCall":{...},...}
+data: {"type":"tool_result","toolCallId":"...","content":"...",...}
+data: {"type":"content","delta":" world","content":"Hello world",...}
+data: {"type":"done","finishReason":"stop","usage":{...}}
+```
+
+**Note:** The `chat()` method automatically executes tools and emits `tool_result` chunks - you don't need to handle tool execution manually!
+
+### Advanced Usage
+
+#### With Callbacks
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const { messages, sendMessage } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+  onChunk: (chunk) => {
+    if (chunk.type === 'content') {
+      console.log('New token:', chunk.delta)
+    }
+  },
+  onFinish: (message) => {
+    console.log('Final message:', message)
+    // Save to database, log analytics, etc.
+  },
+  onError: (error) => {
+    console.error('Chat error:', error)
+    // Show toast notification, log error, etc.
+  },
+})
+
+// Send messages programmatically
+await sendMessage('Tell me a joke')
+```
+
+#### Flexible Triggering
+
+```typescript
+import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
+
+const { sendMessage, isLoading } = useChat({
+  connection: fetchServerSentEvents("/api/chat")
+});
+const [input, setInput] = useState("");
+
+// Button click
+<button onClick={() => sendMessage(input)}>Send</button>
+
+// Enter key
+<input onKeyDown={(e) => e.key === "Enter" && sendMessage(input)} />
+
+// Voice input
+<button onClick={async () => {
+  const transcript = await voiceToText();
+  sendMessage(transcript);
+}}>🎤 Speak</button>
+
+// Predefined prompts
+<button onClick={() => sendMessage("Explain quantum computing")}>
+  Ask about quantum computing
+</button>
+```
+
+#### With Custom Headers
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const chat = useChat({
+  connection: fetchServerSentEvents('/api/chat', {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'X-Custom-Header': 'value',
+    },
+  }),
+  body: {
+    userId: '123',
+    sessionId: 'abc',
+  },
+})
+```
+
+#### Programmatic Control
+
+```typescript
+const { messages, sendMessage, append, reload, stop, clear } = useChat()
+
+// Send a simple message
+await sendMessage('Hello!')
+
+// Add a message with more control
+await append({
+  role: 'user',
+  content: 'Hello!',
+  id: 'custom-id',
+})
+
+// Reload the last AI response
+await reload()
+
+// Stop the current generation
+stop()
+
+// Clear all messages
+clear()
+```
+
+#### Multiple Chats
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+function App() {
+  const chat1 = useChat({
+    id: 'chat-1',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+  const chat2 = useChat({
+    id: 'chat-2',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  // Each hook manages independent state
+}
+```
+
+## Example Backend (Node.js/Express)
+
+```typescript
+import express from 'express'
+import { AI, toStreamResponse } from '@tanstack/ai'
+import { OpenAIAdapter } from '@tanstack/ai-openai'
+
+const app = express()
+app.use(express.json())
+
+const ai = new AI(new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }))
+
+app.post('/api/chat', async (req, res) => {
+  const { messages } = req.body
+
+  // One line to create streaming response!
+  const stream = ai.streamChat({
+    model: 'gpt-3.5-turbo',
+    messages,
+  })
+
+  const response = toStreamResponse(stream)
+
+  // Copy headers and stream to Express response
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value)
+  })
+
+  const reader = response.body?.getReader()
+  if (reader) {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      res.write(value)
+    }
+  }
+  res.end()
+})
+
+app.listen(3000)
+```
+
+## Example Backend (Next.js App Router)
+
+```typescript
+// app/api/chat/route.ts
+import { AI, toStreamResponse } from '@tanstack/ai'
+import { OpenAIAdapter } from '@tanstack/ai-openai'
+
+export const runtime = 'edge'
+
+const ai = new AI(new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }))
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+
+  // One line!
+  return toStreamResponse(
+    ai.streamChat({
+      model: 'gpt-3.5-turbo',
+      messages,
+    }),
+  )
+}
+```
+
+## Example Backend (TanStack Start)
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { AI, toStreamResponse } from '@tanstack/ai'
+import { AnthropicAdapter } from '@tanstack/ai-anthropic'
+
+const ai = new AI(
+  new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
+)
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        // One line with automatic tool execution!
+        return toStreamResponse(
+          ai.streamChat({
+            model: 'claude-3-5-sonnet-20241022',
+            messages,
+            tools, // Tools with execute functions
+          }),
+        )
+      },
+    },
+  },
+})
+```
+
+## TypeScript Types
+
+All types are fully exported:
+
+```typescript
+import type {
+  UIMessage,
+  UseChatOptions,
+  UseChatReturn,
+  ChatRequestBody,
+} from '@tanstack/ai-react'
+```
+
+## Features
+
+- ✅ Automatic message state management
+- ✅ Streaming response handling
+- ✅ Loading and error states
+- ✅ Simple `sendMessage()` API (v5 style)
+- ✅ You control input state (flexible)
+- ✅ Abort/stop generation
+- ✅ Reload last response
+- ✅ Clear conversation
+- ✅ Custom headers and body data (via connection adapter options)
+- ✅ Callback hooks for lifecycle events
+- ✅ Multiple concurrent chats
+- ✅ Full TypeScript support
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { ChatRequestBody, UIMessage, UseChatOptions, UseChatReturn } from "./types.js";
+import { useChat } from "./use-chat.js";
+import { ConnectionAdapter, FetchConnectionOptions, InferChatMessages, createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream } from "@tanstack/ai-client";
+export { type ChatRequestBody, type ConnectionAdapter, type FetchConnectionOptions, type InferChatMessages, type UIMessage, type UseChatOptions, type UseChatReturn, createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream, useChat };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { useChat } from "./use-chat.js";
+import { createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream } from "@tanstack/ai-client";
+
+export { createChatClientOptions, fetchHttpStream, fetchServerSentEvents, stream, useChat };

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+import { Accessor } from "solid-js";
+import { ChatClientOptions, ChatRequestBody, UIMessage } from "@tanstack/ai-client";
+import { AnyClientTool, ModelMessage } from "@tanstack/ai";
+
+//#region src/types.d.ts
+
+/**
+ * Options for the useChat hook.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by Solid signals:
+ * - `onMessagesChange` - Managed by Solid signal (exposed as `messages`)
+ * - `onLoadingChange` - Managed by Solid signal (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by Solid signal (exposed as `error`)
+ *
+ * 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.
+ */
+type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> = Omit<ChatClientOptions<TTools>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'>;
+interface UseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
+  /**
+   * Current messages in the conversation
+   */
+  messages: Accessor<Array<UIMessage<TTools>>>;
+  /**
+   * Send a message and get a response
+   */
+  sendMessage: (content: string) => 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: any;
+    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: Accessor<boolean>;
+  /**
+   * Current error, if any
+   */
+  error: Accessor<Error | undefined>;
+  /**
+   * Set messages manually
+   */
+  setMessages: (messages: Array<UIMessage<TTools>>) => void;
+  /**
+   * Clear all messages
+   */
+  clear: () => void;
+}
+//#endregion
+export { type ChatRequestBody, type UIMessage, UseChatOptions, UseChatReturn };
+//# sourceMappingURL=types.d.ts.map

package/dist/use-chat.d.ts

@@ -0,0 +1,8 @@
+import { UseChatOptions, UseChatReturn } from "./types.js";
+import { AnyClientTool } from "@tanstack/ai";
+
+//#region src/use-chat.d.ts
+declare function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(options?: UseChatOptions<TTools>): UseChatReturn<TTools>;
+//#endregion
+export { useChat };
+//# sourceMappingURL=use-chat.d.ts.map

package/dist/use-chat.js

@@ -0,0 +1,85 @@
+import { createEffect, createMemo, createSignal, createUniqueId } from "solid-js";
+import { ChatClient } from "@tanstack/ai-client";
+
+//#region src/use-chat.ts
+function useChat(options = {}) {
+	const hookId = createUniqueId();
+	const clientId = options.id || hookId;
+	const [messages, setMessages] = createSignal(options.initialMessages || []);
+	const [isLoading, setIsLoading] = createSignal(false);
+	const [error, setError] = createSignal(void 0);
+	const client = createMemo(() => {
+		return new ChatClient({
+			connection: options.connection,
+			id: clientId,
+			initialMessages: options.initialMessages,
+			body: options.body,
+			onResponse: options.onResponse,
+			onChunk: options.onChunk,
+			onFinish: options.onFinish,
+			onError: options.onError,
+			tools: options.tools,
+			streamProcessor: options.streamProcessor,
+			onMessagesChange: (newMessages) => {
+				setMessages(newMessages);
+			},
+			onLoadingChange: (newIsLoading) => {
+				setIsLoading(newIsLoading);
+			},
+			onErrorChange: (newError) => {
+				setError(newError);
+			}
+		});
+	}, [clientId]);
+	createEffect(() => {
+		if (options.initialMessages && options.initialMessages.length > 0) {
+			if (messages().length === 0) client().setMessagesManually(options.initialMessages);
+		}
+	});
+	createEffect(() => {
+		return () => {
+			if (isLoading()) client().stop();
+		};
+	}, [client, isLoading]);
+	const sendMessage = async (content) => {
+		await client().sendMessage(content);
+	};
+	const append = async (message) => {
+		await client().append(message);
+	};
+	const reload = async () => {
+		await client().reload();
+	};
+	const stop = () => {
+		client().stop();
+	};
+	const clear = () => {
+		client().clear();
+	};
+	const setMessagesManually = (newMessages) => {
+		client().setMessagesManually(newMessages);
+	};
+	const addToolResult = async (result) => {
+		await client().addToolResult(result);
+	};
+	const addToolApprovalResponse = async (response) => {
+		await client().addToolApprovalResponse(response);
+	};
+	return {
+		messages,
+		sendMessage,
+		append,
+		reload,
+		stop,
+		isLoading,
+		error,
+		setMessages: setMessagesManually,
+		clear,
+		addToolResult,
+		addToolApprovalResponse
+	};
+}
+
+//#endregion
+export { useChat };
+//# sourceMappingURL=use-chat.js.map

package/dist/use-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chat.js","names":[],"sources":["../src/use-chat.ts"],"sourcesContent":["import {\n  createEffect,\n  createMemo,\n  createSignal,\n  createUniqueId,\n} from 'solid-js'\nimport { ChatClient } from '@tanstack/ai-client'\nimport type { AnyClientTool, ModelMessage } from '@tanstack/ai'\nimport type { UIMessage, UseChatOptions, UseChatReturn } from './types'\n\nexport function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(\n  options: UseChatOptions<TTools> = {} as UseChatOptions<TTools>,\n): UseChatReturn<TTools> {\n  const hookId = createUniqueId()\n  const clientId = options.id || hookId\n\n  const [messages, setMessages] = createSignal<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const [isLoading, setIsLoading] = createSignal(false)\n  const [error, setError] = createSignal<Error | undefined>(undefined)\n\n  // Create ChatClient instance with callbacks to sync state\n  // Note: Options are captured at client creation time.\n  // The connection adapter can use functions for dynamic values (url, headers, etc.)\n  // which are evaluated lazily on each request.\n  const client = createMemo(() => {\n    return new ChatClient({\n      connection: options.connection,\n      id: clientId,\n      initialMessages: options.initialMessages,\n      body: options.body,\n      onResponse: options.onResponse,\n      onChunk: options.onChunk,\n      onFinish: options.onFinish,\n      onError: options.onError,\n      tools: options.tools,\n      streamProcessor: options.streamProcessor,\n      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {\n        setMessages(newMessages)\n      },\n      onLoadingChange: (newIsLoading: boolean) => {\n        setIsLoading(newIsLoading)\n      },\n      onErrorChange: (newError: Error | undefined) => {\n        setError(newError)\n      },\n    })\n    // Only recreate when clientId changes\n    // Connection and other options are captured at creation time\n  }, [clientId])\n\n  // Sync initial messages on mount only\n  // Note: initialMessages are passed to ChatClient constructor, but we also\n  // set them here to ensure React state is in sync\n  createEffect(() => {\n    if (options.initialMessages && options.initialMessages.length > 0) {\n      // Only set if current messages are empty (initial state)\n      if (messages().length === 0) {\n        client().setMessagesManually(options.initialMessages)\n      }\n    }\n  }) // Only run on mount - initialMessages are handled by ChatClient constructor\n\n  // Cleanup on unmount: stop any in-flight requests\n  createEffect(() => {\n    return () => {\n      // Stop any active generation when component unmounts\n      if (isLoading()) {\n        client().stop()\n      }\n    }\n  }, [client, isLoading])\n\n  // Note: Callback options (onResponse, onChunk, onFinish, onError, onToolCall)\n  // are captured at client creation time. Changes to these callbacks require\n  // remounting the component or changing the connection to recreate the client.\n\n  const sendMessage = async (content: string) => {\n    await client().sendMessage(content)\n  }\n\n  const append = async (message: ModelMessage | UIMessage<TTools>) => {\n    await client().append(message)\n  }\n\n  const reload = async () => {\n    await client().reload()\n  }\n\n  const stop = () => {\n    client().stop()\n  }\n\n  const clear = () => {\n    client().clear()\n  }\n\n  const setMessagesManually = (newMessages: Array<UIMessage<TTools>>) => {\n    client().setMessagesManually(newMessages)\n  }\n\n  const addToolResult = async (result: {\n    toolCallId: string\n    tool: string\n    output: any\n    state?: 'output-available' | 'output-error'\n    errorText?: string\n  }) => {\n    await client().addToolResult(result)\n  }\n\n  const addToolApprovalResponse = async (response: {\n    id: string\n    approved: boolean\n  }) => {\n    await client().addToolApprovalResponse(response)\n  }\n\n  return {\n    messages,\n    sendMessage,\n    append,\n    reload,\n    stop,\n    isLoading,\n    error,\n    setMessages: setMessagesManually,\n    clear,\n    addToolResult,\n    addToolApprovalResponse,\n  }\n}\n"],"mappings":";;;;AAUA,SAAgB,QACd,UAAkC,EAAE,EACb;CACvB,MAAM,SAAS,gBAAgB;CAC/B,MAAM,WAAW,QAAQ,MAAM;CAE/B,MAAM,CAAC,UAAU,eAAe,aAC9B,QAAQ,mBAAmB,EAAE,CAC9B;CACD,MAAM,CAAC,WAAW,gBAAgB,aAAa,MAAM;CACrD,MAAM,CAAC,OAAO,YAAY,aAAgC,OAAU;CAMpE,MAAM,SAAS,iBAAiB;AAC9B,SAAO,IAAI,WAAW;GACpB,YAAY,QAAQ;GACpB,IAAI;GACJ,iBAAiB,QAAQ;GACzB,MAAM,QAAQ;GACd,YAAY,QAAQ;GACpB,SAAS,QAAQ;GACjB,UAAU,QAAQ;GAClB,SAAS,QAAQ;GACjB,OAAO,QAAQ;GACf,iBAAiB,QAAQ;GACzB,mBAAmB,gBAA0C;AAC3D,gBAAY,YAAY;;GAE1B,kBAAkB,iBAA0B;AAC1C,iBAAa,aAAa;;GAE5B,gBAAgB,aAAgC;AAC9C,aAAS,SAAS;;GAErB,CAAC;IAGD,CAAC,SAAS,CAAC;AAKd,oBAAmB;AACjB,MAAI,QAAQ,mBAAmB,QAAQ,gBAAgB,SAAS,GAE9D;OAAI,UAAU,CAAC,WAAW,EACxB,SAAQ,CAAC,oBAAoB,QAAQ,gBAAgB;;GAGzD;AAGF,oBAAmB;AACjB,eAAa;AAEX,OAAI,WAAW,CACb,SAAQ,CAAC,MAAM;;IAGlB,CAAC,QAAQ,UAAU,CAAC;CAMvB,MAAM,cAAc,OAAO,YAAoB;AAC7C,QAAM,QAAQ,CAAC,YAAY,QAAQ;;CAGrC,MAAM,SAAS,OAAO,YAA8C;AAClE,QAAM,QAAQ,CAAC,OAAO,QAAQ;;CAGhC,MAAM,SAAS,YAAY;AACzB,QAAM,QAAQ,CAAC,QAAQ;;CAGzB,MAAM,aAAa;AACjB,UAAQ,CAAC,MAAM;;CAGjB,MAAM,cAAc;AAClB,UAAQ,CAAC,OAAO;;CAGlB,MAAM,uBAAuB,gBAA0C;AACrE,UAAQ,CAAC,oBAAoB,YAAY;;CAG3C,MAAM,gBAAgB,OAAO,WAMvB;AACJ,QAAM,QAAQ,CAAC,cAAc,OAAO;;CAGtC,MAAM,0BAA0B,OAAO,aAGjC;AACJ,QAAM,QAAQ,CAAC,wBAAwB,SAAS;;AAGlD,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;EACD"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tanstack/ai-solid",
+  "version": "0.0.1",
+  "description": "Solid hooks for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-solid"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "solidjs",
+    "hooks",
+    "tanstack",
+    "chat",
+    "streaming"
+  ],
+  "dependencies": {
+    "zod": "^4.1.13",
+    "@tanstack/ai": "0.0.1",
+    "@tanstack/ai-client": "0.0.1"
+  },
+  "devDependencies": {
+    "@solidjs/testing-library": "^0.8.10",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.0.14",
+    "jsdom": "^27.2.0",
+    "solid-js": "^1.9.10",
+    "tsdown": "^0.17.0-beta.6",
+    "typescript": "5.9.3",
+    "vitest": "^4.0.14"
+  },
+  "peerDependencies": {
+    "solid-js": ">=1.9.10",
+    "@tanstack/ai": "0.0.1",
+    "@tanstack/ai-client": "0.0.1"
+  },
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { useChat } from './use-chat'
+export type {
+  UseChatOptions,
+  UseChatReturn,
+  UIMessage,
+  ChatRequestBody,
+} from './types'
+
+// Re-export from ai-client for convenience
+export {
+  fetchServerSentEvents,
+  fetchHttpStream,
+  stream,
+  createChatClientOptions,
+  type ConnectionAdapter,
+  type FetchConnectionOptions,
+  type InferChatMessages,
+} from '@tanstack/ai-client'

package/src/types.ts

@@ -0,0 +1,102 @@
+import type { Accessor } from 'solid-js'
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  ChatClientOptions,
+  ChatRequestBody,
+  UIMessage,
+} from '@tanstack/ai-client'
+
+// Re-export types from ai-client
+export type { UIMessage, ChatRequestBody }
+
+/**
+ * Options for the useChat hook.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by Solid signals:
+ * - `onMessagesChange` - Managed by Solid signal (exposed as `messages`)
+ * - `onLoadingChange` - Managed by Solid signal (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by Solid signal (exposed as `error`)
+ *
+ * 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> =
+  Omit<
+    ChatClientOptions<TTools>,
+    'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'
+  >
+
+export interface UseChatReturn<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> {
+  /**
+   * Current messages in the conversation
+   */
+  messages: Accessor<Array<UIMessage<TTools>>>
+
+  /**
+   * Send a message and get a response
+   */
+  sendMessage: (content: string) => 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: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => Promise<void>
+
+  /**
+   * Respond to a tool approval request
+   */
+  addToolApprovalResponse: (response: {
+    id: string // approval.id, not toolCallId
+    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: Accessor<boolean>
+
+  /**
+   * Current error, if any
+   */
+  error: Accessor<Error | undefined>
+
+  /**
+   * Set messages manually
+   */
+  setMessages: (messages: Array<UIMessage<TTools>>) => void
+
+  /**
+   * Clear all messages
+   */
+  clear: () => void
+}
+
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience

package/src/use-chat.ts

@@ -0,0 +1,133 @@
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+} from 'solid-js'
+import { ChatClient } from '@tanstack/ai-client'
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type { UIMessage, UseChatOptions, UseChatReturn } from './types'
+
+export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
+  options: UseChatOptions<TTools> = {} as UseChatOptions<TTools>,
+): UseChatReturn<TTools> {
+  const hookId = createUniqueId()
+  const clientId = options.id || hookId
+
+  const [messages, setMessages] = createSignal<Array<UIMessage<TTools>>>(
+    options.initialMessages || [],
+  )
+  const [isLoading, setIsLoading] = createSignal(false)
+  const [error, setError] = createSignal<Error | undefined>(undefined)
+
+  // Create ChatClient instance with callbacks to sync state
+  // Note: Options are captured at client creation time.
+  // The connection adapter can use functions for dynamic values (url, headers, etc.)
+  // which are evaluated lazily on each request.
+  const client = createMemo(() => {
+    return new ChatClient({
+      connection: options.connection,
+      id: clientId,
+      initialMessages: options.initialMessages,
+      body: options.body,
+      onResponse: options.onResponse,
+      onChunk: options.onChunk,
+      onFinish: options.onFinish,
+      onError: options.onError,
+      tools: options.tools,
+      streamProcessor: options.streamProcessor,
+      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
+        setMessages(newMessages)
+      },
+      onLoadingChange: (newIsLoading: boolean) => {
+        setIsLoading(newIsLoading)
+      },
+      onErrorChange: (newError: Error | undefined) => {
+        setError(newError)
+      },
+    })
+    // Only recreate when clientId changes
+    // Connection and other options are captured at creation time
+  }, [clientId])
+
+  // Sync initial messages on mount only
+  // Note: initialMessages are passed to ChatClient constructor, but we also
+  // set them here to ensure React state is in sync
+  createEffect(() => {
+    if (options.initialMessages && options.initialMessages.length > 0) {
+      // Only set if current messages are empty (initial state)
+      if (messages().length === 0) {
+        client().setMessagesManually(options.initialMessages)
+      }
+    }
+  }) // Only run on mount - initialMessages are handled by ChatClient constructor
+
+  // Cleanup on unmount: stop any in-flight requests
+  createEffect(() => {
+    return () => {
+      // Stop any active generation when component unmounts
+      if (isLoading()) {
+        client().stop()
+      }
+    }
+  }, [client, isLoading])
+
+  // Note: Callback options (onResponse, onChunk, onFinish, onError, onToolCall)
+  // are captured at client creation time. Changes to these callbacks require
+  // remounting the component or changing the connection to recreate the client.
+
+  const sendMessage = async (content: string) => {
+    await client().sendMessage(content)
+  }
+
+  const append = async (message: ModelMessage | UIMessage<TTools>) => {
+    await client().append(message)
+  }
+
+  const reload = async () => {
+    await client().reload()
+  }
+
+  const stop = () => {
+    client().stop()
+  }
+
+  const clear = () => {
+    client().clear()
+  }
+
+  const setMessagesManually = (newMessages: Array<UIMessage<TTools>>) => {
+    client().setMessagesManually(newMessages)
+  }
+
+  const addToolResult = async (result: {
+    toolCallId: string
+    tool: string
+    output: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => {
+    await client().addToolResult(result)
+  }
+
+  const addToolApprovalResponse = async (response: {
+    id: string
+    approved: boolean
+  }) => {
+    await client().addToolApprovalResponse(response)
+  }
+
+  return {
+    messages,
+    sendMessage,
+    append,
+    reload,
+    stop,
+    isLoading,
+    error,
+    setMessages: setMessagesManually,
+    clear,
+    addToolResult,
+    addToolApprovalResponse,
+  }
+}