@tanstack/ai-octane 0.1.6 → 0.3.0

package/README.md

@@ -1,3 +1,23 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
 # @tanstack/ai-octane
 
 [TanStack AI](https://tanstack.com/ai) bindings for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-octane",
-  "version": "0.1.6",
+  "version": "0.3.0",
   "description": "Octane bindings for TanStack AI streaming chat, structured outputs, and media generation.",
   "author": "Dominic Gannaway",
   "license": "MIT",
@@ -38,7 +38,8 @@
   "module": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./ui": "./src/ui.ts"
   },
   "files": [
     "src",
@@ -46,11 +47,11 @@
   ],
   "//lint": "The .tsrx.d.ts companions are generated declaration emits of the .tsrx implementations, so they are not hand-formatted and are excluded from lint rather than edited in place (a regeneration would undo any fix).",
   "dependencies": {
-    "@tanstack/ai-client": "0.29.2"
+    "@tanstack/ai-client": "0.31.0"
   },
   "peerDependencies": {
     "octane": "^0.1.17",
-    "@tanstack/ai": "^0.52.0"
+    "@tanstack/ai": "^0.53.0"
   },
   "devDependencies": {
     "@octanejs/testing-library": "0.1.14",
@@ -61,7 +62,7 @@
     "octane": "0.1.17",
     "vite": "^8.2.1",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.52.0"
+    "@tanstack/ai": "0.53.0"
   },
   "scripts": {
     "lint:fix": "oxlint src --type-aware --ignore-pattern '**/*.tsrx.d.ts' --fix",

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

@@ -0,0 +1,105 @@
+import { useMemo, useRef } from 'octane'
+import type { ComponentBody } from 'octane'
+
+type ComponentType<P = any> = ComponentBody<P>
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type {
+  ChatUIInterruptsOf,
+  ChatUISchemaOf,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import { useChat as useUnboundChat } from '../use-chat.tsrx'
+import type { UseChatOptions } from '../types'
+import { createChatUI } from './create-ui.tsrx'
+import type { ChatUIFactoryConfig, ChatUIHost, InputProps } from './create-ui.tsrx'
+
+type HeadlessOptions<TOptions> = UseChatOptions<
+  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.
+ *
+ * This matches Form `createFormHook` and Table `createTableHook`. The
+ * returned `useAppChat` creates a chat instance. `chat.AppChat` renders it.
+ * `useChatContext` reads that instance. Part and interrupt widgets take
+ * `part` / `interrupt` as props. Do not read those from context.
+ *
+ * Pass instance overrides such as `threadId` into `useAppChat()`.
+ *
+ * @example
+ * ```tsx
+ * const { useAppChat, useChatContext } = createChatHook({
+ *   options: chatOptions,
+ *   components: { layout: ChatLayout, message: ChatMessage },
+ *   partsComponents: { fallback: FallbackPart },
+ *   toolsComponents: { getWeather: WeatherTool, purchaseItem: PurchaseTool },
+ *   interruptsComponents: { generic: { choosePlan: ChoosePlan } },
+ * })
+ *
+ * function Support() {
+ *   const chat = useAppChat({ threadId: 'support-1' })
+ *   return <chat.AppChat />
+ * }
+ * ```
+ */
+export function createChatHook<
+  const TOptions,
+  TInput extends ComponentType<any> | undefined =
+    | ComponentType<InputProps<NoInfer<TOptions>>>
+    | undefined,
+>({
+  options,
+  ...chatComponents
+}: {
+  options: TOptions
+} & ChatUIFactoryConfig<NoInfer<TOptions>, TInput>) {
+  const ui = createChatUI(
+    options,
+    chatComponents as ChatUIFactoryConfig<NoInfer<TOptions>, TInput>,
+  )
+
+  function useAppChat(overrides?: ChatInstanceOverrides<TOptions>) {
+    const chat = (
+      overrides
+        ? useUnboundChat({
+            ...(options as HeadlessOptions<TOptions>),
+            ...overrides,
+          })
+        : useUnboundChat(options as HeadlessOptions<TOptions>)
+    ) as ChatUIHost<TOptions>
+
+    // `useChat` returns a fresh object on every render. The mixed Chat
+    // component must stay stable, or React remounts the tree on each
+    // update. Read the current instance from a ref.
+    const chatRef = useRef(chat)
+    chatRef.current = chat
+
+    const AppChat = useMemo(() => {
+      function AppChatImpl() {
+        return <ui.Chat chat={chatRef.current} />
+      }
+      return AppChatImpl
+    }, [])
+
+    return Object.assign(chat, { AppChat }) as ChatUIHost<TOptions> & {
+      AppChat: ComponentType
+    }
+  }
+
+  return {
+    useAppChat,
+    useChatContext: ui.useChatContext,
+  }
+}

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

@@ -0,0 +1,20 @@
+import type { ComponentBody } from 'octane'
+import type { ChatUIFactoryConfig, ChatUIHost } from './create-ui.tsrx'
+
+export declare function createChatHook<
+  const TOptions,
+  TInput extends ComponentBody<any> | undefined =
+    | ComponentBody<any>
+    | undefined,
+>(
+  config: { options: TOptions } & ChatUIFactoryConfig<TOptions, TInput>,
+): {
+  useAppChat: (overrides?: {
+    threadId?: string
+    live?: boolean
+    forwardedProps?: Record<string, any>
+    body?: Record<string, any>
+    initialMessages?: ChatUIHost<TOptions>['messages']
+  }) => ChatUIHost<TOptions> & { AppChat: ComponentBody }
+  useChatContext: () => ChatUIHost<TOptions>
+}

package/src/chat-ui/create-ui-contexts.tsrx

@@ -0,0 +1,57 @@
+import { createContext, useContext } from 'octane'
+import type { Context } from 'octane'
+import type {
+  ChatUIInterrupt,
+  ChatUISelectedPart,
+} from '@tanstack/ai-client/ui'
+import type { UseChatReturn } from '../types'
+
+/**
+ * Scoped chat, part, and interrupt contexts plus matching context hooks.
+ * Pass these into {@link createChatHook} when widgets live in other files, or
+ * when two chat trees nest and must not share the default contexts.
+ */
+export interface ChatUIContexts {
+  chatContext: Context<UseChatReturn<any, any, any> | null>
+  partContext: Context<ChatUISelectedPart | null>
+  interruptContext: Context<ChatUIInterrupt | null>
+  useChatContext: () => UseChatReturn<any, any, any>
+}
+
+/**
+ * Create a fresh set of chat UI contexts. This matches Form
+ * `createFormHookContexts` and Table `createTableHookContexts`.
+ *
+ * Most apps can skip this. `createChatHook` uses shared module contexts by
+ * default. The hooks on this object are the escape hatch for a widget file
+ * that cannot import the `createChatHook` result (circular import), or for
+ * nested chats that need isolated providers.
+ *
+ * Prefer the `useChatContext` hook returned from `createChatHook` when you
+ * can import that result. That hook knows the `chatComponents` types. Part
+ * and interrupt widgets take `part` / `interrupt` as props.
+ */
+export function createChatHookContexts(): ChatUIContexts {
+  const chatContext = createContext<UseChatReturn<any, any, any> | null>(null)
+  const partContext = createContext<ChatUISelectedPart | null>(null)
+  const interruptContext = createContext<ChatUIInterrupt | null>(null)
+
+  function useChatContext() {
+    const chat = useContext(chatContext)
+    if (!chat) {
+      throw new Error(
+        '`useChatContext` must be used within `UI.Provider` or `UI.Chat`.',
+      )
+    }
+    return chat
+  }
+
+  return {
+    chatContext,
+    partContext,
+    interruptContext,
+    useChatContext,
+  }
+}
+
+export const defaultChatUIContexts = createChatHookContexts()

package/src/chat-ui/create-ui-contexts.tsrx.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'octane'
+import type {
+  ChatUIInterrupt,
+  ChatUISelectedPart,
+} from '@tanstack/ai-client/ui'
+import type { UseChatReturn } from '../types'
+
+export interface ChatUIContexts {
+  chatContext: Context<UseChatReturn<any, any, any> | null>
+  partContext: Context<ChatUISelectedPart | null>
+  interruptContext: Context<ChatUIInterrupt | null>
+  useChatContext: () => UseChatReturn<any, any, any>
+}
+
+export declare function createChatHookContexts(): ChatUIContexts
+export declare const defaultChatUIContexts: ChatUIContexts

package/src/chat-ui/create-ui.tsrx

@@ -0,0 +1,764 @@
+import { createContext, memo, useContext } from 'octane'
+import type { ComponentBody, Context, OctaneNode } from 'octane'
+
+type ComponentType<P = any> = ComponentBody<P>
+type ComponentProps<T> = T extends ComponentBody<infer P> ? P : Record<string, never>
+import {
+  automaticPartsForMessage,
+  collectInlineToolNames,
+  resolveInterruptComponent,
+  selectChatUI,
+  selectMessageUI,
+} from '@tanstack/ai-client/ui'
+import type {
+  ChatUIData,
+  ChatUIHasNamedInterrupts,
+  ChatUIHasNamedTools,
+  ChatUIInterrupt,
+  ChatUIInterruptName,
+  ChatUIInterruptOf,
+  ChatUIInterruptsOf,
+  ChatUIMessages,
+  ChatUINamedInterruptId,
+  ChatUIPartKey,
+  ChatUIPartOf,
+  ChatUISchemaOf,
+  ChatUISelectedPart,
+  ChatUISelectedPartOf,
+  ChatUIToolApproval,
+  ChatUIToolName,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import type {
+  MessagePart,
+  QueuedMessage,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '@tanstack/ai-client'
+import type { UseChatReturn } from '../types'
+import { defaultChatUIContexts } from './create-ui-contexts.tsrx'
+import type { ChatUIContexts } from './create-ui-contexts.tsrx'
+
+export type ChatUIHost<TOptions = unknown> = UseChatReturn<
+  ChatUIToolsOf<TOptions>,
+  ChatUISchemaOf<TOptions>,
+  ChatUIInterruptsOf<TOptions>
+>
+
+export type ChatUIQueueItem = QueuedMessage & {
+  cancelQueued: () => void
+}
+
+export type LayoutProps<
+  TOptions,
+  TInput extends ComponentType<any> | undefined = ComponentType<
+    InputProps<TOptions>
+  >,
+> = {
+  Messages: ComponentType
+  Interrupts: ComponentType
+  Queue: ComponentType
+  readonly __ui?: TOptions
+} & (TInput extends ComponentType<any> ? { Input: ComponentType } : {})
+
+export type MessageProps<TOptions> = {
+  message: UIMessage<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>
+  Parts: ComponentType
+}
+
+export type InputProps<TOptions> = {
+  readonly __ui?: TOptions
+}
+
+export type QueueProps<TOptions> = {
+  item: ChatUIQueueItem
+  readonly __ui?: TOptions
+}
+
+export type PartProps<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = {
+  part: ChatUIPartOf<TOptions, TKey>
+}
+
+export type ToolProps<
+  TOptions,
+  TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
+> = {
+  part: Extract<ToolCallPart<ChatUIToolsOf<TOptions>>, { name: TName }>
+  result?: ToolResultPart
+  interrupt?: ChatUIToolApproval<TOptions, TName>
+}
+
+export type InterruptProps<
+  TOptions,
+  TName extends ChatUIInterruptName<TOptions> = never,
+> = {
+  interrupt: ChatUIInterruptOf<TOptions, TName>
+  readonly __ui?: TOptions
+}
+
+type GenericInterruptComponents<TOptions> =
+  ChatUIHasNamedInterrupts<TOptions> extends true
+    ? {
+        [K in ChatUINamedInterruptId<TOptions>]: ComponentType<
+          InterruptProps<TOptions, K & ChatUIInterruptName<TOptions>>
+        >
+      } & {
+        fallback?: ComponentType<InterruptProps<TOptions>>
+      }
+    : {
+        fallback?: ComponentType<InterruptProps<TOptions>>
+      }
+
+type ToolApprovalMap<TOptions> = {
+  [K in ChatUIToolName<TOptions>]?: ComponentType<
+    InterruptProps<TOptions, K & ChatUIInterruptName<TOptions>>
+  >
+}
+
+/** The chrome around the message list: `layout`, `message`, and `input`. */
+export type ChatUIChromeComponents<
+  TOptions,
+  TInput extends ComponentType<InputProps<TOptions>> | undefined =
+    ComponentType<InputProps<TOptions>>,
+> = {
+  layout: ComponentType<LayoutProps<TOptions, TInput>>
+  message: ComponentType<MessageProps<TOptions>>
+  input?: TInput
+  queue?: ComponentType<QueueProps<TOptions>>
+}
+
+export type ChatUIPartsComponents<TOptions> = {
+  [K in ChatUIPartKey]?: ComponentType<PartProps<TOptions, K>>
+} & {
+  fallback?: ComponentType<PartProps<TOptions>>
+}
+
+export type ChatUIInterruptsComponents<TOptions> = {
+  tools?: ToolApprovalMap<TOptions>
+  generic: GenericInterruptComponents<TOptions>
+}
+
+export type ChatUIComponents<
+  TOptions,
+  TInput extends ComponentType<InputProps<TOptions>> | undefined =
+    ComponentType<InputProps<TOptions>>,
+> = {
+  components: ChatUIChromeComponents<TOptions, TInput>
+  partsComponents: ChatUIPartsComponents<TOptions>
+} & (ChatUIHasNamedTools<TOptions> extends true
+  ? {
+      toolsComponents: {
+        [K in ChatUIToolName<TOptions>]: ComponentType<ToolProps<TOptions, K>>
+      }
+    }
+  : {
+      toolsComponents?: {
+        [K in ChatUIToolName<TOptions>]?: ComponentType<ToolProps<TOptions, K>>
+      }
+    }) &
+  (ChatUIHasNamedInterrupts<TOptions> extends true
+    ? { interruptsComponents: ChatUIInterruptsComponents<TOptions> }
+    : {
+        interruptsComponents?: {
+          tools?: ToolApprovalMap<TOptions>
+          generic?: GenericInterruptComponents<TOptions>
+        }
+      })
+
+/** Scoped contexts, for widgets in other files or nested chat trees. */
+export type ChatUIContextConfig = {
+  chatContext?: ChatUIContexts['chatContext']
+  partContext?: ChatUIContexts['partContext']
+  interruptContext?: ChatUIContexts['interruptContext']
+}
+
+export type ChatUIFactoryConfig<
+  TOptions,
+  TInput extends ComponentType<InputProps<TOptions>> | undefined =
+    ComponentType<InputProps<TOptions>>,
+> = ChatUIComponents<TOptions, TInput> & {
+  context?: ChatUIContextConfig
+}
+
+type BoundWidget = ComponentType<Record<string, never>>
+
+type PartMixins<TOptions> = {
+  [K in ChatUIPartKey]?: BoundWidget
+} & {
+  [K in ChatUIToolName<TOptions>]: BoundWidget
+} & {
+  Render: BoundWidget
+}
+
+type InterruptMixins<TOptions> = {
+  [K in ChatUINamedInterruptId<TOptions>]: BoundWidget
+} & {
+  [K in ChatUIToolName<TOptions>]?: BoundWidget
+} & {
+  fallback?: BoundWidget
+  Render: BoundWidget
+}
+
+function createWarnOnce() {
+  const seen = new Set<string>()
+  return (key: string, message: string) => {
+    if (process.env.NODE_ENV === 'production') return
+    if (seen.has(key)) return
+    seen.add(key)
+    console.warn(message)
+  }
+}
+
+function readMessages<TOptions>(chat: ChatUIHost<TOptions>) {
+  return chat.messages as ChatUIMessages<TOptions>
+}
+
+function readInterrupts<TOptions>(chat: ChatUIHost<TOptions>) {
+  return chat.interrupts ?? []
+}
+
+function queueItemEqual(
+  prev: { item: QueuedMessage; cancelQueued: (id: string) => void },
+  next: { item: QueuedMessage; cancelQueued: (id: string) => void },
+) {
+  return (
+    prev.item.id === next.item.id &&
+    prev.item.createdAt === next.item.createdAt &&
+    prev.item.content === next.item.content &&
+    prev.cancelQueued === next.cancelQueued
+  )
+}
+
+function selectedPartPropsEqual(
+  prev: { selected: ChatUISelectedPart },
+  next: { selected: ChatUISelectedPart },
+) {
+  if (prev.selected.key !== next.selected.key) return false
+  if (prev.selected.part !== next.selected.part) return false
+  if (prev.selected.key === 'toolCall' && next.selected.key === 'toolCall') {
+    return (
+      prev.selected.result === next.selected.result &&
+      prev.selected.interrupt === next.selected.interrupt
+    )
+  }
+  if (
+    prev.selected.key === 'toolResult' &&
+    next.selected.key === 'toolResult'
+  ) {
+    return prev.selected.matched === next.selected.matched
+  }
+  return true
+}
+
+function isSelectedPart(
+  value: MessagePart | ChatUISelectedPart,
+): value is ChatUISelectedPart {
+  return 'key' in value && 'part' in value
+}
+
+function bindMap(
+  map: Record<string, ComponentType<any> | undefined> | undefined,
+  bind: (component: ComponentType<any>) => BoundWidget,
+) {
+  const out: Record<string, BoundWidget> = {}
+  for (const [key, component] of Object.entries(map ?? {})) {
+    if (component) out[key] = bind(component)
+  }
+  return out
+}
+
+/**
+ * Bind chat options and UI widgets once at module scope. This matches Form
+ * `createFormHook` and Table `createTableHook`: widgets register here, mix
+ * onto Part / Interrupt / the UI kit, and automatic dispatch still walks the
+ * message list.
+ *
+ * `chatOptions` is type-only at runtime. Pass optional `chatContext`,
+ * `partContext`, and `interruptContext` from {@link createChatHookContexts}
+ * when widgets live in other files or when nested chats need isolation.
+ */
+export function createChatUI<
+  const TOptions,
+  TInput extends ComponentType<any> | undefined =
+    | ComponentType<InputProps<NoInfer<TOptions>>>
+    | undefined,
+>(options: TOptions, config: ChatUIFactoryConfig<NoInfer<TOptions>, TInput>) {
+  void options
+  const {
+    context: contextOption,
+    components,
+    partsComponents: parts,
+    toolsComponents: tools,
+    interruptsComponents: interrupts,
+  } = config as ChatUIFactoryConfig<TOptions, TInput> & {
+    toolsComponents?: Record<string, ComponentType<any> | undefined>
+    interruptsComponents?: {
+      tools?: Record<string, ComponentType<any> | undefined>
+      generic?: Record<string, ComponentType<any> | undefined>
+    }
+  }
+  const {
+    layout: Layout,
+    message: MessageComponent,
+    input: InputComponent,
+    queue: QueueItemComponent,
+  } = components
+  const {
+    chatContext: chatContextOption,
+    partContext: partContextOption,
+    interruptContext: interruptContextOption,
+  } = contextOption ?? {}
+  const warn = createWarnOnce()
+  const ChatContext = (chatContextOption ??
+    defaultChatUIContexts.chatContext) as Context<ChatUIHost<TOptions> | null>
+  const PartContext = (partContextOption ??
+    defaultChatUIContexts.partContext) as Context<ChatUISelectedPart | null>
+  const InterruptContext = (interruptContextOption ??
+    defaultChatUIContexts.interruptContext) as Context<ChatUIInterrupt | null>
+  const inlineToolNames = collectInlineToolNames(
+    interrupts?.tools as Record<string, unknown> | undefined,
+    Object.keys(tools ?? {}),
+  )
+
+  function useChatContext() {
+    const chat = useContext(ChatContext)
+    if (!chat) {
+      throw new Error(
+        '`useChatContext` must be used within `UI.Provider` or `UI.Chat`.',
+      )
+    }
+    return chat
+  }
+
+  function usePartContext<TKey extends ChatUIPartKey = ChatUIPartKey>() {
+    const selected = useContext(PartContext)
+    if (!selected) {
+      throw new Error(
+        '`usePartContext` must be used within `UI.Part` or an automatic part.',
+      )
+    }
+    return selected as ChatUISelectedPartOf<TOptions, TKey>
+  }
+
+  function useInterruptContext<
+    TName extends ChatUIInterruptName<TOptions> = ChatUIInterruptName<TOptions>,
+  >() {
+    const interrupt = useContext(InterruptContext)
+    if (!interrupt) {
+      throw new Error(
+        '`useInterruptContext` must be used within `UI.Interrupt`.',
+      )
+    }
+    return interrupt as ChatUIInterruptOf<TOptions, TName>
+  }
+
+  function bindPart(Component: ComponentType<PartProps<TOptions>>) {
+    return function BoundPart() {
+      const selected = usePartContext()
+      return <Component part={selected.part as PartProps<TOptions>['part']} />
+    }
+  }
+
+  function bindTool(Component: ComponentType<ToolProps<TOptions>>) {
+    return function BoundTool() {
+      const selected = usePartContext()
+      if (selected.key !== 'toolCall') return null
+      return (
+        <Component
+          part={selected.part as ToolProps<TOptions>['part']}
+          result={selected.result}
+          interrupt={selected.interrupt as ToolProps<TOptions>['interrupt']}
+        />
+      )
+    }
+  }
+
+  function bindInterrupt(Component: ComponentType<InterruptProps<TOptions>>) {
+    return function BoundInterrupt() {
+      const interrupt = useInterruptContext()
+      return (
+        <Component
+          interrupt={interrupt as InterruptProps<TOptions>['interrupt']}
+        />
+      )
+    }
+  }
+
+  const partMixins = bindMap(
+    parts as Record<string, ComponentType<any> | undefined>,
+    bindPart,
+  )
+  const toolMixins = bindMap(
+    tools as Record<string, ComponentType<any> | undefined>,
+    bindTool,
+  )
+  const interruptMixins = {
+    ...bindMap(
+      interrupts?.generic as
+        | Record<string, ComponentType<any> | undefined>
+        | undefined,
+      bindInterrupt,
+    ),
+    ...bindMap(
+      interrupts?.tools as
+        | Record<string, ComponentType<any> | undefined>
+        | undefined,
+      bindInterrupt,
+    ),
+  }
+
+  function mixPart(selected: ChatUISelectedPart) {
+    return Object.assign({}, selected, partMixins, toolMixins, {
+      Render: BoundRender,
+    }) as ChatUISelectedPart & PartMixins<TOptions>
+  }
+
+  function mixInterrupt(interrupt: ChatUIInterrupt) {
+    return Object.assign({}, interrupt, interruptMixins, {
+      Render: BoundInterruptRender,
+    }) as ChatUIInterrupt & InterruptMixins<TOptions>
+  }
+
+  function Provider({
+    chat,
+    children,
+  }: {
+    chat: ChatUIHost<TOptions>
+    children?: OctaneNode
+  }) {
+    return <ChatContext.Provider value={chat}>{children}</ChatContext.Provider>
+  }
+
+  // Backstop for when the conditional `Input` type cannot be inferred (see the
+  // `input` note in docs/ui/react.md). The type hides `Input` when no `input`
+  // is registered, but inference degrades on some config shapes, so always
+  // supply a component: warn once rather than crash on an undefined element.
+  function MissingInput() {
+    warn(
+      'input',
+      '[tanstack-ai-ui] Rendered <Input /> but no `input` component is registered.',
+    )
+    return null
+  }
+
+  // `Messages`, `Interrupts`, `Queue` and `InputComponent` are declared once
+  // per factory, so these props are stable for the lifetime of the kit.
+  const LayoutSlots = {
+    Messages: Messages as ComponentType,
+    Interrupts: Interrupts as ComponentType,
+    Queue: Queue as ComponentType,
+    Input: (InputComponent ?? MissingInput) as ComponentType,
+  }
+
+  function Chat({ chat }: { chat: ChatUIHost<TOptions> }) {
+    return (
+      <Provider chat={chat}>
+        <Layout {...(LayoutSlots as ComponentProps<ComponentType<any>>)} />
+      </Provider>
+    )
+  }
+
+  function Queue() {
+    const chat = useChatContext()
+    if (!QueueItemComponent) return null
+    const items = chat.queue
+    return (
+      <>
+        {items.map((item) => (
+          <QueueItemView
+            key={item.id}
+            cancelQueued={chat.cancelQueued}
+            item={item}
+          />
+        ))}
+      </>
+    )
+  }
+
+  const QueueItemView = memo(function QueueItemView({
+    item,
+    cancelQueued,
+  }: {
+    item: QueuedMessage
+    cancelQueued: (id: string) => void
+  }) {
+    if (!QueueItemComponent) return null
+    return (
+      <QueueItemComponent
+        item={{
+          ...item,
+          cancelQueued: () => {
+            cancelQueued(item.id)
+          },
+        }}
+      />
+    )
+  }, queueItemEqual)
+
+  function Messages({
+    children,
+  }: {
+    children?: (messages: ChatUIMessages<TOptions>) => OctaneNode
+  } = {}) {
+    const chat = useChatContext()
+    const messages = readMessages(chat)
+    const interrupts = readInterrupts(chat)
+    if (children) return <>{children(messages)}</>
+    return (
+      <>
+        {messages.map((message) => (
+          <MessageView
+            key={message.id}
+            inlineToolNames={inlineToolNames}
+            interrupts={interrupts}
+            message={message}
+          />
+        ))}
+      </>
+    )
+  }
+
+  // Scoped to one message render. `Parts` reads it instead of closing over the
+  // message, which is what keeps its identity constant across re-renders — a
+  // fresh component per render would remount every part on each stream chunk.
+  type MessageRenderValue = {
+    message: ChatUIMessages<TOptions>[number]
+    interrupts: ReadonlyArray<ChatUIInterrupt>
+    inlineToolNames: ReadonlyArray<string>
+  }
+  const MessageRenderContext = createContext<MessageRenderValue | null>(null)
+
+  function Parts() {
+    const scope = useContext(MessageRenderContext)
+    if (!scope) {
+      throw new Error('`Parts` must be rendered by a `message` component.')
+    }
+    return (
+      <AutomaticParts
+        inlineToolNames={scope.inlineToolNames}
+        interrupts={scope.interrupts}
+        message={scope.message}
+      />
+    )
+  }
+
+  const MessageView = memo(function MessageView({
+    message,
+    interrupts,
+    inlineToolNames: names,
+    children,
+  }: {
+    message: ChatUIMessages<TOptions>[number]
+    interrupts: ReadonlyArray<ChatUIInterrupt>
+    inlineToolNames: ReadonlyArray<string>
+    children?: (parts: Array<ChatUISelectedPart>) => OctaneNode
+  }) {
+    const selected = selectMessageUI(message, {
+      interrupts,
+      inlineToolNames: names,
+    })
+    if (children) return <>{children(selected.parts)}</>
+    return (
+      <MessageRenderContext.Provider
+        value={{ message, interrupts, inlineToolNames: names }}
+      >
+        <MessageComponent message={message} Parts={Parts} />
+      </MessageRenderContext.Provider>
+    )
+  })
+
+  function Message({
+    message,
+    children,
+  }: {
+    message: ChatUIMessages<TOptions>[number]
+    children?: (parts: Array<ChatUISelectedPart>) => OctaneNode
+  }) {
+    const chat = useChatContext()
+    return (
+      <MessageView
+        children={children}
+        inlineToolNames={inlineToolNames}
+        interrupts={readInterrupts(chat)}
+        message={message}
+      />
+    )
+  }
+
+  const AutomaticParts = memo(function AutomaticParts({
+    message,
+    interrupts,
+    inlineToolNames: names,
+  }: {
+    message: ChatUIMessages<TOptions>[number]
+    interrupts: ReadonlyArray<ChatUIInterrupt>
+    inlineToolNames: ReadonlyArray<string>
+  }) {
+    const selected = selectMessageUI(message, {
+      interrupts,
+      inlineToolNames: names,
+    })
+    return (
+      <>
+        {automaticPartsForMessage(selected).map((part, index) => (
+          <SelectedPartView key={`${message.id}-${index}`} selected={part} />
+        ))}
+      </>
+    )
+  })
+
+  const SelectedPartInner = memo(function SelectedPartInner({
+    selected,
+  }: {
+    selected: ChatUISelectedPart
+  }) {
+    if (selected.key === 'toolCall') {
+      const name = selected.part.name
+      const Tool = tools?.[name as ChatUIToolName<TOptions>] as
+        | ComponentType<ToolProps<TOptions>>
+        | undefined
+      if (!Tool) {
+        warn(`tool:${name}`, `[tanstack-ai-ui] Missing tools.${name} component`)
+        return null
+      }
+      return (
+        <Tool
+          part={selected.part as ToolProps<TOptions>['part']}
+          result={selected.result}
+          interrupt={selected.interrupt as ToolProps<TOptions>['interrupt']}
+        />
+      )
+    }
+
+    const PartComponent = (parts[selected.key] ?? parts.fallback) as
+      | ComponentType<PartProps<TOptions>>
+      | undefined
+    if (!PartComponent) {
+      warn(
+        `part:${selected.key}`,
+        `[tanstack-ai-ui] Missing parts.${selected.key} component`,
+      )
+      return null
+    }
+    return <PartComponent part={selected.part as PartProps<TOptions>['part']} />
+  }, selectedPartPropsEqual)
+
+  const SelectedPartView = memo(function SelectedPartView({
+    selected,
+  }: {
+    selected: ChatUISelectedPart
+  }) {
+    return (
+      <PartContext.Provider value={selected}>
+        <SelectedPartInner selected={selected} />
+      </PartContext.Provider>
+    )
+  })
+
+  function BoundRender() {
+    const selected = usePartContext()
+    return <SelectedPartInner selected={selected} />
+  }
+
+  function Part({
+    part,
+    children,
+  }: {
+    part: MessagePart | ChatUISelectedPart
+    children?: (mixed: ChatUISelectedPart & PartMixins<TOptions>) => OctaneNode
+  }) {
+    const chat = useChatContext()
+    const selected = isSelectedPart(part)
+      ? part
+      : selectMessageUI(
+          { id: 'part', role: 'assistant', parts: [part] },
+          { interrupts: readInterrupts(chat), inlineToolNames: [] },
+        ).parts[0]
+    if (!selected) return null
+    return (
+      <PartContext.Provider value={selected}>
+        {children ? (
+          children(mixPart(selected))
+        ) : (
+          <SelectedPartInner selected={selected} />
+        )}
+      </PartContext.Provider>
+    )
+  }
+
+  function Interrupts({
+    children,
+  }: {
+    children?: (interrupts: ReadonlyArray<ChatUIInterrupt>) => OctaneNode
+  } = {}) {
+    const chat = useChatContext()
+    const selected = selectChatUI({
+      messages: readMessages(chat),
+      interrupts: readInterrupts(chat),
+      inlineToolNames,
+    })
+    if (children) return <>{children(selected.interrupts)}</>
+    return (
+      <>
+        {selected.interrupts.map((interrupt) => (
+          <Interrupt key={interrupt.id} interrupt={interrupt} />
+        ))}
+      </>
+    )
+  }
+
+  const InterruptInner = memo(function InterruptInner({
+    interrupt,
+  }: {
+    interrupt: ChatUIInterrupt
+  }) {
+    const Component = resolveInterruptComponent(interrupt, interrupts) as
+      | ComponentType<InterruptProps<TOptions>>
+      | undefined
+    if (!Component) {
+      warn(
+        `interrupt:${interrupt.id}`,
+        `[tanstack-ai-ui] Missing interrupt component for ${interrupt.kind}`,
+      )
+      return null
+    }
+    return <Component interrupt={interrupt} />
+  })
+
+  function BoundInterruptRender() {
+    const interrupt = useInterruptContext()
+    return <InterruptInner interrupt={interrupt} />
+  }
+
+  const Interrupt = memo(function Interrupt({
+    interrupt,
+    children,
+  }: {
+    interrupt: ChatUIInterrupt
+    children?: (mixed: ChatUIInterrupt & InterruptMixins<TOptions>) => OctaneNode
+  }) {
+    return (
+      <InterruptContext.Provider value={interrupt}>
+        {children ? (
+          children(mixInterrupt(interrupt))
+        ) : (
+          <InterruptInner interrupt={interrupt} />
+        )}
+      </InterruptContext.Provider>
+    )
+  })
+
+  return {
+    Chat,
+    Provider,
+    Messages,
+    Message,
+    Part,
+    Interrupts,
+    Interrupt,
+    Queue,
+    useChatContext,
+    Input: InputComponent,
+  }
+}

package/src/chat-ui/create-ui.tsrx.d.ts

@@ -0,0 +1,116 @@
+import type { ComponentBody, Context, OctaneNode } from 'octane'
+import type { UseChatReturn } from '../types'
+import type { ChatUIContexts } from './create-ui-contexts.tsrx'
+import type {
+  ChatUIInterruptName,
+  ChatUIInterruptsOf,
+  ChatUIPartKey,
+  ChatUIPartOf,
+  ChatUISchemaOf,
+  ChatUIToolName,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import type { QueuedMessage } from '@tanstack/ai-client'
+
+type ComponentType<P = any> = ComponentBody<P>
+
+export type ChatUIHost<TOptions = unknown> = UseChatReturn<
+  ChatUIToolsOf<TOptions>,
+  ChatUISchemaOf<TOptions>,
+  ChatUIInterruptsOf<TOptions>
+>
+
+export type ChatUIQueueItem = QueuedMessage & { cancelQueued: () => void }
+
+export type LayoutProps<
+  TOptions,
+  TInput extends ComponentType<any> | undefined = ComponentType<any>,
+> = {
+  Messages: ComponentType
+  Interrupts: ComponentType
+  Queue: ComponentType
+  readonly __ui?: TOptions
+} & (TInput extends ComponentType<any> ? { Input: ComponentType } : {})
+
+export type MessageProps<TOptions> = {
+  message: ChatUIHost<TOptions>['messages'][number]
+  Parts: ComponentType
+}
+
+export type InputProps<TOptions> = { readonly __ui?: TOptions }
+export type QueueProps<TOptions> = {
+  item: ChatUIQueueItem
+  readonly __ui?: TOptions
+}
+export type PartProps<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = {
+  part: ChatUIPartOf<TOptions, TKey>
+}
+export type ToolProps<
+  TOptions,
+  TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
+> = {
+  part: { name: TName }
+  result?: unknown
+  interrupt?: unknown
+}
+export type InterruptProps<
+  TOptions,
+  TName extends ChatUIInterruptName<TOptions> = never,
+> = {
+  interrupt: { kind: string }
+  readonly __ui?: TOptions
+}
+
+export type ChatUIFactoryConfig<
+  TOptions,
+  TInput extends ComponentType<any> | undefined = ComponentType<any>,
+> = {
+  components: {
+    layout: ComponentType<LayoutProps<TOptions, TInput>>
+    message: ComponentType<MessageProps<TOptions>>
+    input?: TInput
+    queue?: ComponentType<QueueProps<TOptions>>
+  }
+  partsComponents: Record<string, ComponentType<any> | undefined>
+  toolsComponents?: Record<string, ComponentType<any> | undefined>
+  interruptsComponents?: {
+    tools?: Record<string, ComponentType<any> | undefined>
+    generic?: Record<string, ComponentType<any> | undefined>
+  }
+  context?: {
+    chatContext?: ChatUIContexts['chatContext']
+    partContext?: ChatUIContexts['partContext']
+    interruptContext?: ChatUIContexts['interruptContext']
+  }
+}
+
+export type ChatUIComponents<
+  TOptions,
+  TInput extends ComponentType<any> | undefined = ComponentType<any>,
+> = ChatUIFactoryConfig<TOptions, TInput>
+
+export declare function createChatUI<
+  const TOptions,
+  TInput extends ComponentType<any> | undefined =
+    | ComponentType<any>
+    | undefined,
+>(
+  options: TOptions,
+  config: ChatUIFactoryConfig<TOptions, TInput>,
+): {
+  Chat: ComponentType<{ chat: ChatUIHost<TOptions> }>
+  Provider: ComponentType<{
+    chat: ChatUIHost<TOptions>
+    children?: OctaneNode
+  }>
+  Messages: ComponentType
+  Message: ComponentType
+  Part: ComponentType
+  Interrupts: ComponentType
+  Interrupt: ComponentType
+  Queue: ComponentType
+  useChatContext: () => ChatUIHost<TOptions>
+  Input: TInput
+}
+
+export type { Context }

package/src/create-chat-hook.ts

@@ -0,0 +1,54 @@
+import { useChat as useUnboundChat } from './use-chat.tsrx'
+import type {
+  AnyClientTool,
+  InterruptDefinition,
+  SchemaInput,
+} from '@tanstack/ai/client'
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type { UseChatOptions } from './types'
+
+type ChatHookOverrides<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TSchema extends SchemaInput | undefined,
+  TContext,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = {
+  threadId?: string
+  live?: boolean
+  forwardedProps?: Record<string, any>
+  body?: Record<string, any>
+  initialMessages?: UseChatOptions<
+    TTools,
+    TSchema,
+    TContext,
+    TInterrupts
+  >['initialMessages']
+}
+
+/**
+ * Bind chat options once at module scope. The returned `useChat` hook
+ * creates a chat instance from those options.
+ *
+ * Pass per-call overrides for instance keys such as `threadId`,
+ * `initialMessages`, `live`, and `forwardedProps`. Do not change `tools`,
+ * `interrupts`, or `outputSchema` here. Those stay on the factory options.
+ */
+export function createChatHook<
+  const TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+  TContext = InferredClientContext<TTools>,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = readonly [],
+>(options: UseChatOptions<TTools, TSchema, TContext, TInterrupts>) {
+  function useChat(
+    overrides?: ChatHookOverrides<TTools, TSchema, TContext, TInterrupts>,
+  ) {
+    if (!overrides) {
+      return useUnboundChat(options)
+    }
+    return useUnboundChat({ ...options, ...overrides })
+  }
+
+  return { useChat }
+}

package/src/index.ts

@@ -1,7 +1,10 @@
 export { useChat } from './use-chat.tsrx'
+export { createChatHook } from './create-chat-hook'
 export { useRealtimeChat } from './use-realtime-chat.tsrx'
 export { useMcpAppBridge } from './use-mcp-app-bridge.tsrx'
 export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.tsrx'
+export { useWebMCPTools } from './use-web-mcp-tools.tsrx'
+export type { UseWebMCPToolsOptions } from './use-web-mcp-tools.tsrx'
 export type {
   DeepPartial,
   UseChatOptions,

package/src/ui.ts

@@ -0,0 +1,20 @@
+// Barrel entry for the `@tanstack/ai-octane/ui` subpath.
+export {
+  createChatUI,
+  type ChatUIComponents,
+  type ChatUIFactoryConfig,
+  type ChatUIHost,
+  type ChatUIQueueItem,
+  type InputProps,
+  type InterruptProps,
+  type LayoutProps,
+  type MessageProps,
+  type PartProps,
+  type QueueProps,
+  type ToolProps,
+} from './chat-ui/create-ui.tsrx'
+export { createChatHook } from './chat-ui/create-chat-hook.tsrx'
+export {
+  createChatHookContexts,
+  type ChatUIContexts,
+} from './chat-ui/create-ui-contexts.tsrx'

package/src/use-web-mcp-tools.tsrx

@@ -0,0 +1,61 @@
+import { useEffect } from 'octane'
+import { registerWebMCPTools } from '@tanstack/ai-client'
+import type {
+  AnyClientTool,
+  InferredClientContext,
+  RegisterWebMCPToolsOptions,
+} from '@tanstack/ai-client'
+
+/** Options for the Octane {@link useWebMCPTools} lifecycle hook. */
+export type UseWebMCPToolsOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
+  /** Receives an asynchronous registration failure. */
+  onError?: (error: unknown) => void
+}
+
+type UseWebMCPToolsArguments<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext,
+> = RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }
+  ? [options: UseWebMCPToolsOptions<TTools, TContext>]
+  : [options?: UseWebMCPToolsOptions<TTools, TContext>]
+
+/**
+ * Registers client tools with WebMCP for the lifetime of an Octane component.
+ *
+ * The hook replaces the registration when `tools` or `options` changes.
+ * Unsupported browsers and server rendering do not register tools.
+ *
+ * @param tools - The executable client tools to expose through WebMCP.
+ * @param options - Runtime context, per-tool options, and an error callback.
+ *
+ * @example
+ * ```tsx
+ * useWebMCPTools([searchProducts], {
+ *   toolOptions: { searchProducts: { title: 'Search products' } },
+ * })
+ * ```
+ */
+export function useWebMCPTools<
+  const TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+>(
+  tools: TTools,
+  ...[options]: UseWebMCPToolsArguments<TTools, TContext>
+) {
+  useEffect(() => {
+    const controller = new AbortController()
+    const { onError, ...registrationOptions } = options ?? {}
+
+    registerWebMCPTools(tools, {
+      ...registrationOptions,
+      signal: controller.signal,
+    }).catch((error) => {
+      if (!controller.signal.aborted) onError?.(error)
+    })
+
+    return () => controller.abort()
+  }, [tools, options])
+}

package/src/use-web-mcp-tools.tsrx.d.ts

@@ -0,0 +1,42 @@
+// Declaration companion generated from use-web-mcp-tools.tsrx.
+import type {
+  AnyClientTool,
+  InferredClientContext,
+  RegisterWebMCPToolsOptions,
+} from '@tanstack/ai-client'
+
+/** Options for the Octane {@link useWebMCPTools} lifecycle hook. */
+export type UseWebMCPToolsOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
+  /** Receives an asynchronous registration failure. */
+  onError?: (error: unknown) => void
+}
+type UseWebMCPToolsArguments<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext,
+> =
+  RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }
+    ? [options: UseWebMCPToolsOptions<TTools, TContext>]
+    : [options?: UseWebMCPToolsOptions<TTools, TContext>]
+/**
+ * Registers client tools with WebMCP for the lifetime of an Octane component.
+ *
+ * The hook replaces the registration when `tools` or `options` changes.
+ * Unsupported browsers and server rendering do not register tools.
+ *
+ * @param tools - The executable client tools to expose through WebMCP.
+ * @param options - Runtime context, per-tool options, and an error callback.
+ *
+ * @example
+ * ```tsx
+ * useWebMCPTools([searchProducts], {
+ *   toolOptions: { searchProducts: { title: 'Search products' } },
+ * })
+ * ```
+ */
+export declare function useWebMCPTools<
+  const TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+>(tools: TTools, ...[options]: UseWebMCPToolsArguments<TTools, TContext>): void