@tanstack/ai-remix 0.0.0

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,11 @@
+# @tanstack/ai-remix
+
+Remix 3 helpers for TanStack AI streaming chat.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai-remix @tanstack/ai @tanstack/ai-client remix
+```
+
+This package publishes uncompiled source. Remix compiles JSX through `jsxImportSource` `remix/ui`.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@tanstack/ai-remix",
+  "version": "0.0.0",
+  "description": "Remix 3 bindings for TanStack AI streaming chat, structured outputs, and media generation.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-remix"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "remix",
+    "chat",
+    "streaming",
+    "tool-calling",
+    "structured-outputs",
+    "media-generation"
+  ],
+  "//": "This package publishes uncompiled source (.ts / .tsx). Remix compiles JSX via jsxImportSource remix/ui. There is therefore no build/dist and no publint test:build target.",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ui": "./src/ui.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@tanstack/ai-client": "^0.30.0"
+  },
+  "peerDependencies": {
+    "remix": "^3.0.0-rc.1",
+    "@tanstack/ai": "^0.52.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "happy-dom": "^20.11.2",
+    "remix": "^3.0.0-rc.1",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10",
+    "@tanstack/ai": "0.52.1"
+  },
+  "scripts": {
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/chat-ui/chat-input.tsx

@@ -0,0 +1,125 @@
+import { on } from 'remix/ui'
+import type { Handle, RemixNode } from 'remix/ui'
+import { useChatContext } from './chat.tsx'
+
+export interface ChatInputRenderProps {
+  value: string
+  onChange: (value: string) => void
+  onSubmit: () => void
+  isLoading: boolean
+  disabled: boolean
+}
+
+/** @deprecated Use `createChatUI()` and an application-owned input component. Removed in 1.0.0. */
+export interface ChatInputProps {
+  children?: (props: ChatInputRenderProps) => RemixNode
+  class?: string
+  placeholder?: string
+  disabled?: boolean
+  submitOnEnter?: boolean
+}
+
+/**
+ * @deprecated Use `createChatUI()` and an application-owned input component.
+ * Removed in 1.0.0.
+ */
+export function ChatInput(handle: Handle<ChatInputProps>) {
+  let value = ''
+
+  return () => {
+    const { sendMessage, isLoading } = useChatContext(handle)
+    const disabled = Boolean(handle.props.disabled || isLoading)
+    const submitOnEnter = handle.props.submitOnEnter !== false
+
+    function onChange(next: string) {
+      value = next
+      void handle.update()
+    }
+
+    function onSubmit() {
+      if (!value.trim() || disabled) return
+      void sendMessage(value)
+      value = ''
+      void handle.update()
+    }
+
+    const renderProps: ChatInputRenderProps = {
+      value,
+      onChange,
+      onSubmit,
+      isLoading,
+      disabled,
+    }
+
+    if (typeof handle.props.children === 'function') {
+      return handle.props.children(renderProps)
+    }
+
+    return (
+      <div
+        class={handle.props.class}
+        data-chat-input
+        style={{
+          display: 'flex',
+          gap: '0.75rem',
+          alignItems: 'center',
+          width: '100%',
+        }}
+      >
+        <input
+          data-chat-textarea
+          disabled={disabled}
+          placeholder={handle.props.placeholder ?? 'Type a message...'}
+          type="text"
+          value={value}
+          mix={[
+            on('input', (event) => {
+              onChange((event.currentTarget as HTMLInputElement).value)
+            }),
+            on('keydown', (event) => {
+              if (
+                submitOnEnter &&
+                event.key === 'Enter' &&
+                !event.isComposing
+              ) {
+                event.preventDefault()
+                onSubmit()
+              }
+            }),
+          ]}
+          style={{
+            flex: '1',
+            padding: '0.75rem 1rem',
+            fontSize: '0.875rem',
+            border: '1px solid rgba(255, 255, 255, 0.1)',
+            borderRadius: '0.75rem',
+            backgroundColor: 'rgba(31, 41, 55, 0.5)',
+            color: 'white',
+            outline: 'none',
+          }}
+        />
+        <button
+          data-chat-submit
+          disabled={disabled || !value.trim()}
+          mix={[on('click', onSubmit)]}
+          style={{
+            padding: '0.75rem 1.5rem',
+            fontSize: '0.875rem',
+            fontWeight: 500,
+            color: 'white',
+            backgroundColor:
+              disabled || !value.trim()
+                ? 'rgba(107, 114, 128, 0.5)'
+                : 'rgb(249, 115, 22)',
+            border: 'none',
+            borderRadius: '0.75rem',
+            cursor: disabled || !value.trim() ? 'not-allowed' : 'pointer',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {isLoading ? 'Sending...' : 'Send'}
+        </button>
+      </div>
+    )
+  }
+}

package/src/chat-ui/chat-message.tsx

@@ -0,0 +1,197 @@
+import type { Handle, RemixNode } from 'remix/ui'
+import { ThinkingPart } from './thinking-part.tsx'
+import type { UIMessage } from '../types.ts'
+
+export interface ToolCallRenderProps {
+  id: string
+  name: string
+  arguments: string
+  state: string
+  approval?: {
+    id: string
+    needsApproval: boolean
+    approved?: boolean
+  }
+  output?: unknown
+}
+
+/** @deprecated Use `createChatUI()` Message instead. Removed in 1.0.0. */
+export interface ChatMessageProps {
+  message: UIMessage
+  class?: string
+  userClass?: string
+  assistantClass?: string
+  textPartRenderer?: (props: { content: string }) => RemixNode
+  thinkingPartRenderer?: (props: {
+    content: string
+    isComplete?: boolean
+  }) => RemixNode
+  toolsRenderer?: Record<string, (props: ToolCallRenderProps) => RemixNode>
+  defaultToolRenderer?: (props: ToolCallRenderProps) => RemixNode
+  toolResultRenderer?: (props: {
+    toolCallId: string
+    content: string
+    state: string
+  }) => RemixNode
+}
+
+function toolResultContentToString(
+  content: string | Array<{ type: string; content?: string }>,
+): string {
+  if (typeof content === 'string') return content
+  return content
+    .filter((part) => part.type === 'text')
+    .map((part) => part.content ?? '')
+    .join('')
+}
+
+/** @deprecated Use `createChatUI()` Message instead. Removed in 1.0.0. */
+export function ChatMessage(handle: Handle<ChatMessageProps>) {
+  return () => {
+    const message = handle.props.message
+    const roleClass =
+      message.role === 'user'
+        ? handle.props.userClass
+        : handle.props.assistantClass
+    const combinedClass = [handle.props.class, roleClass]
+      .filter(Boolean)
+      .join(' ')
+
+    return (
+      <div
+        class={combinedClass || undefined}
+        data-message-id={message.id}
+        data-message-role={message.role}
+        data-message-created={message.createdAt?.toISOString()}
+      >
+        {message.parts.map((part, index) => (
+          <MessagePart
+            key={`${message.id}-part-${index}`}
+            defaultToolRenderer={handle.props.defaultToolRenderer}
+            isThinkingComplete={
+              part.type === 'thinking' &&
+              message.parts.slice(index + 1).some((p) => p.type === 'text')
+            }
+            part={part}
+            textPartRenderer={handle.props.textPartRenderer}
+            thinkingPartRenderer={handle.props.thinkingPartRenderer}
+            toolResultRenderer={handle.props.toolResultRenderer}
+            toolsRenderer={handle.props.toolsRenderer}
+          />
+        ))}
+      </div>
+    )
+  }
+}
+
+function MessagePart(
+  handle: Handle<{
+    part: UIMessage['parts'][number]
+    isThinkingComplete?: boolean
+    textPartRenderer?: ChatMessageProps['textPartRenderer']
+    thinkingPartRenderer?: ChatMessageProps['thinkingPartRenderer']
+    toolsRenderer?: ChatMessageProps['toolsRenderer']
+    defaultToolRenderer?: ChatMessageProps['defaultToolRenderer']
+    toolResultRenderer?: ChatMessageProps['toolResultRenderer']
+  }>,
+) {
+  return () => {
+    const part = handle.props.part
+
+    if (part.type === 'text') {
+      if (handle.props.textPartRenderer) {
+        return handle.props.textPartRenderer({ content: part.content })
+      }
+      return (
+        <div data-part-type="text" data-part-content>
+          {part.content}
+        </div>
+      )
+    }
+
+    if (part.type === 'thinking') {
+      if (handle.props.thinkingPartRenderer) {
+        return handle.props.thinkingPartRenderer({
+          content: part.content,
+          isComplete: handle.props.isThinkingComplete,
+        })
+      }
+      return (
+        <ThinkingPart
+          content={part.content}
+          isComplete={handle.props.isThinkingComplete}
+        />
+      )
+    }
+
+    if (part.type === 'tool-call') {
+      const toolProps: ToolCallRenderProps = {
+        id: part.id,
+        name: part.name,
+        arguments: part.arguments,
+        state: part.state,
+        approval: part.approval,
+        output: part.output,
+      }
+      const named = handle.props.toolsRenderer?.[part.name]
+      if (named) return named(toolProps)
+      if (handle.props.defaultToolRenderer) {
+        return handle.props.defaultToolRenderer(toolProps)
+      }
+      return (
+        <div
+          data-part-type="tool-call"
+          data-tool-id={part.id}
+          data-tool-name={part.name}
+          data-tool-state={part.state}
+        >
+          <div data-tool-header>
+            <strong>{part.name}</strong>
+            <span data-tool-state-badge>{part.state}</span>
+          </div>
+          {part.arguments ? (
+            <div data-tool-arguments>
+              <pre>{part.arguments}</pre>
+            </div>
+          ) : null}
+          {part.approval ? (
+            <div data-tool-approval>
+              {part.approval.approved !== undefined
+                ? part.approval.approved
+                  ? 'Approved'
+                  : 'Denied'
+                : 'Awaiting approval...'}
+            </div>
+          ) : null}
+          {part.output ? (
+            <div data-tool-output>
+              <pre>{JSON.stringify(part.output, null, 2)}</pre>
+            </div>
+          ) : null}
+        </div>
+      )
+    }
+
+    if (part.type === 'tool-result') {
+      const content = toolResultContentToString(part.content)
+      if (handle.props.toolResultRenderer) {
+        return handle.props.toolResultRenderer({
+          toolCallId: part.toolCallId,
+          content,
+          state: part.state,
+        })
+      }
+      return (
+        <div
+          data-part-type="tool-result"
+          data-tool-call-id={part.toolCallId}
+          data-tool-result-state={part.state}
+        >
+          <div data-tool-result-content>{content}</div>
+        </div>
+      )
+    }
+
+    return null
+  }
+}

package/src/chat-ui/chat-messages.tsx

@@ -0,0 +1,67 @@
+import { ref } from 'remix/ui'
+import type { Handle, RemixNode } from 'remix/ui'
+import { useChatContext } from './chat.tsx'
+import { ChatMessage } from './chat-message.tsx'
+import type { UIMessage } from '../types.ts'
+
+/** @deprecated Use `createChatUI()` Messages instead. Removed in 1.0.0. */
+export interface ChatMessagesProps {
+  children?: (message: UIMessage, index: number) => RemixNode
+  class?: string
+  emptyState?: RemixNode
+  loadingState?: RemixNode
+  errorState?: (props: {
+    error: Error
+    reload: () => Promise<void>
+  }) => RemixNode
+  autoScroll?: boolean
+}
+
+/** @deprecated Use `createChatUI()` Messages instead. Removed in 1.0.0. */
+export function ChatMessages(handle: Handle<ChatMessagesProps>) {
+  let container: HTMLElement | null = null
+
+  return () => {
+    const { messages, isLoading, error, reload } = useChatContext(handle)
+    const autoScroll = handle.props.autoScroll !== false
+
+    if (autoScroll && container) {
+      container.scrollTop = container.scrollHeight
+    }
+
+    if (error && handle.props.errorState) {
+      return handle.props.errorState({ error, reload })
+    }
+
+    if (isLoading && messages.length === 0 && handle.props.loadingState) {
+      return handle.props.loadingState
+    }
+
+    if (messages.length === 0 && handle.props.emptyState) {
+      return handle.props.emptyState
+    }
+
+    return (
+      <div
+        class={handle.props.class}
+        data-chat-messages
+        data-message-count={messages.length}
+        mix={[
+          ref((node) => {
+            container = node
+          }),
+        ]}
+      >
+        {messages.map((message, index) =>
+          typeof handle.props.children === 'function' ? (
+            <div key={message.id} data-message-id={message.id}>
+              {handle.props.children(message, index)}
+            </div>
+          ) : (
+            <ChatMessage key={message.id} message={message} />
+          ),
+        )}
+      </div>
+    )
+  }
+}

package/src/chat-ui/chat.tsx

@@ -0,0 +1,48 @@
+import type { ConnectionAdapter } from '@tanstack/ai-client'
+import type { Handle, RemixNode } from 'remix/ui'
+import { createChat } from '../create-chat.ts'
+import type { CreateChatReturn, UIMessage } from '../types.ts'
+
+/** @deprecated Use `createChatUI()` Chat/Provider instead. Removed in 1.0.0. */
+export interface ChatProps {
+  children?: RemixNode
+  class?: string
+  connection: ConnectionAdapter
+  initialMessages?: Array<UIMessage>
+  id?: string
+  body?: Record<string, any>
+  tools?: Array<any>
+}
+
+/** @deprecated Use `createChatHook().useChatContext(handle)` from `@tanstack/ai-remix/ui` instead. Removed in 1.0.0. */
+export function useChatContext(handle: Handle<any>): CreateChatReturn {
+  const chat = handle.context.get(Chat)
+  if (!chat) {
+    throw new Error(
+      'Chat components must be wrapped in <Chat>. Make sure you use Chat.Messages, Chat.Input, and the rest inside a <Chat> component.',
+    )
+  }
+  return chat
+}
+
+/**
+ * @deprecated Use `createChatHook()` from `@tanstack/ai-remix/ui` instead.
+ * Removed in 1.0.0.
+ */
+export function Chat(handle: Handle<ChatProps, CreateChatReturn>) {
+  const chat = createChat(handle, {
+    connection: handle.props.connection,
+    ...(handle.props.initialMessages !== undefined
+      ? { initialMessages: handle.props.initialMessages }
+      : {}),
+    ...(handle.props.id !== undefined ? { threadId: handle.props.id } : {}),
+    ...(handle.props.body !== undefined ? { body: handle.props.body } : {}),
+    ...(handle.props.tools !== undefined ? { tools: handle.props.tools } : {}),
+  })
+  handle.context.set(chat)
+  return () => (
+    <div class={handle.props.class} data-chat-root>
+      {handle.props.children}
+    </div>
+  )
+}

package/src/chat-ui/create-chat-hook.ts

@@ -0,0 +1,66 @@
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type {
+  ChatUIInterruptsOf,
+  ChatUISchemaOf,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import type { Handle } from 'remix/ui'
+import { createChat as createUnboundChat } from '../create-chat.ts'
+import type { CreateChatOptions } from '../types.ts'
+import { createChatUI } from './create-ui.tsx'
+import type { ChatUIFactoryConfig, ChatUIHost } from './create-ui.tsx'
+
+type HeadlessOptions<TOptions> = CreateChatOptions<
+  ChatUIToolsOf<TOptions>,
+  ChatUISchemaOf<TOptions>,
+  InferredClientContext<ChatUIToolsOf<TOptions>>,
+  ChatUIInterruptsOf<TOptions>
+>
+
+type ChatInstanceOverrides<TOptions> = {
+  threadId?: string
+  live?: boolean
+  forwardedProps?: Record<string, any>
+  body?: Record<string, any>
+  initialMessages?: HeadlessOptions<TOptions>['initialMessages']
+}
+
+/**
+ * Bind chat options and UI widgets once at module scope.
+ *
+ * Returns a bound `createAppChat`, the UI kit (`ui`), and `useChatContext`.
+ * Call `createAppChat(handle)` in a Remix setup function. Render
+ * `<ui.Chat chat={chat} />`. Pass instance overrides such as `threadId`
+ * into `createAppChat(handle, overrides)`.
+ */
+export function createChatHook<const TOptions>({
+  options,
+  ...chatComponents
+}: {
+  options: TOptions
+} & ChatUIFactoryConfig<NoInfer<TOptions>>) {
+  const ui = createChatUI(
+    options,
+    chatComponents as ChatUIFactoryConfig<NoInfer<TOptions>>,
+  )
+
+  function createAppChat(
+    handle: Handle<any>,
+    overrides?: ChatInstanceOverrides<TOptions>,
+  ): ChatUIHost<TOptions> {
+    const chat = overrides
+      ? createUnboundChat(handle, {
+          ...(options as HeadlessOptions<TOptions>),
+          ...overrides,
+        })
+      : createUnboundChat(handle, options as HeadlessOptions<TOptions>)
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- return shape always includes partial/final; ChatUIHost gates those on TSchema
+    return chat as unknown as ChatUIHost<TOptions>
+  }
+
+  return {
+    createAppChat,
+    ui,
+    useChatContext: ui.useChatContext,
+  }
+}