@tanstack/ai-svelte 0.19.3 → 0.20.0

package/dist/chat-ui/ui-queue.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import {
+    getChatContext,
+    getComponentsContext,
+    readQueue,
+    type UIDescriptor,
+  } from './create-ui'
+
+  let { ui }: { ui: UIDescriptor } = $props()
+
+  const chat = $derived(getChatContext(ui))
+  const comps = $derived(getComponentsContext(ui))
+  const items = $derived(readQueue(chat))
+  const QueueItem = $derived(comps.components.queue as any)
+</script>
+
+{#if QueueItem}
+  {#each items as item (item.id)}
+    <QueueItem {item} />
+  {/each}
+{/if}

package/dist/chat-ui/ui-queue.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type UIDescriptor } from './create-ui';
+type $$ComponentProps = {
+    ui: UIDescriptor;
+};
+declare const UiQueue: import("svelte").Component<$$ComponentProps, {}, "">;
+type UiQueue = ReturnType<typeof UiQueue>;
+export default UiQueue;

package/dist/create-chat-hook.d.ts

@@ -0,0 +1,35 @@
+import type { AnyClientTool, InterruptDefinition, SchemaInput } from '@tanstack/ai';
+import type { InferredClientContext } from '@tanstack/ai-client';
+import type { CreateChatOptions } 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?: CreateChatOptions<TTools, TSchema, TContext, TInterrupts>['initialMessages'];
+};
+/**
+ * Bind chat options once at module scope. The returned `createChat`
+ * function 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.
+ *
+ * Rename the function at the call site if you already import `createChat` from
+ * `@tanstack/ai-svelte`: `const { createChat: createAppChat } = createChatHook(chatOptions)`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChatHook } from '@tanstack/ai-svelte'
+ *
+ *   const { createChat } = createChatHook(chatOptions)
+ *   const chat = createChat({ threadId: 'support-1' })
+ * </script>
+ * ```
+ */
+export declare 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: CreateChatOptions<TTools, TSchema, TContext, TInterrupts>): {
+    createChat: (overrides?: ChatHookOverrides<TTools, TSchema, TContext, TInterrupts>) => import("./types").CreateChatReturn<TTools, TSchema, TContext, TInterrupts>;
+};
+export {};

package/dist/create-chat-hook.js

@@ -0,0 +1,31 @@
+import { createChat as createUnboundChat } from './create-chat.svelte';
+/**
+ * Bind chat options once at module scope. The returned `createChat`
+ * function 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.
+ *
+ * Rename the function at the call site if you already import `createChat` from
+ * `@tanstack/ai-svelte`: `const { createChat: createAppChat } = createChatHook(chatOptions)`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChatHook } from '@tanstack/ai-svelte'
+ *
+ *   const { createChat } = createChatHook(chatOptions)
+ *   const chat = createChat({ threadId: 'support-1' })
+ * </script>
+ * ```
+ */
+export function createChatHook(options) {
+    function createChat(overrides) {
+        if (!overrides) {
+            return createUnboundChat(options);
+        }
+        return createUnboundChat({ ...options, ...overrides });
+    }
+    return { createChat };
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createChat } from './create-chat.svelte';
+export { createChatHook } from './create-chat-hook';
 export { createByok } from './create-byok.svelte';
 export type { CreateChatOptions, CreateChatReturn, DeepPartial, UIMessage, ChatRequestBody, QueuedMessage, SendMessageOptions, WhenBusy, QueueConfig, QueueStrategy, QueueOption, } from './types';
 export { createGeneration } from './create-generation.svelte';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createChat } from './create-chat.svelte';
+export { createChatHook } from './create-chat-hook';
 export { createByok } from './create-byok.svelte';
 // Generation hooks
 export { createGeneration } from './create-generation.svelte';

package/dist/ui.d.ts

@@ -0,0 +1,11 @@
+export { createChatUI, getUIContext } from './chat-ui/create-ui';
+export { createChatHook } from './chat-ui/create-chat-hook';
+export type { ChatUIComponents, ChatUIFactoryConfig, ChatUIHost, ChatUIQueueItem, InputProps, InterruptProps, LayoutProps, MessageProps, PartProps, QueueProps, ToolProps, UIDescriptor, } from './chat-ui/create-ui';
+export { default as UIChat } from './chat-ui/ui-chat.svelte';
+export { default as UIProvider } from './chat-ui/ui-provider.svelte';
+export { default as UIMessages } from './chat-ui/ui-messages.svelte';
+export { default as UIMessage } from './chat-ui/ui-message.svelte';
+export { default as UIPart } from './chat-ui/ui-part.svelte';
+export { default as UIInterrupts } from './chat-ui/ui-interrupts.svelte';
+export { default as UIInterrupt } from './chat-ui/ui-interrupt.svelte';
+export { default as UIQueue } from './chat-ui/ui-queue.svelte';

package/dist/ui.js

@@ -0,0 +1,11 @@
+// Barrel entry for the `@tanstack/ai-svelte/ui` subpath.
+export { createChatUI, getUIContext } from './chat-ui/create-ui';
+export { createChatHook } from './chat-ui/create-chat-hook';
+export { default as UIChat } from './chat-ui/ui-chat.svelte';
+export { default as UIProvider } from './chat-ui/ui-provider.svelte';
+export { default as UIMessages } from './chat-ui/ui-messages.svelte';
+export { default as UIMessage } from './chat-ui/ui-message.svelte';
+export { default as UIPart } from './chat-ui/ui-part.svelte';
+export { default as UIInterrupts } from './chat-ui/ui-interrupts.svelte';
+export { default as UIInterrupt } from './chat-ui/ui-interrupt.svelte';
+export { default as UIQueue } from './chat-ui/ui-queue.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-svelte",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "Svelte 5 bindings for TanStack AI streaming chat, structured outputs, and media generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -26,6 +26,11 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js",
       "import": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "svelte": "./dist/ui.js",
+      "import": "./dist/ui.js"
     }
   },
   "files": [
@@ -46,11 +51,11 @@
     "media-generation"
   ],
   "dependencies": {
-    "@tanstack/ai-client": "^0.29.1"
+    "@tanstack/ai-client": "^0.30.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0",
-    "@tanstack/ai": "^0.51.0"
+    "@tanstack/ai": "^0.52.1"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -63,7 +68,7 @@
     "svelte-check": "^4.2.0",
     "typescript": "5.9.3",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.51.0"
+    "@tanstack/ai": "0.52.1"
   },
   "scripts": {
     "clean": "rm -rf ./dist",

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

@@ -0,0 +1,62 @@
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type {
+  ChatUIInterruptsOf,
+  ChatUISchemaOf,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import { createChat as createUnboundChat } from '../create-chat.svelte'
+import type { CreateChatOptions } from '../types'
+import { createChatUI } from './create-ui'
+import type { ChatUIFactoryConfig, ChatUIHost } from './create-ui'
+
+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 descriptor (`ui`), and
+ * `useChatContext`. Pass `{ui}` into `UIChat`. Pass instance overrides
+ * such as `threadId` into `createAppChat()`.
+ */
+export function createChatHook<const TOptions>({
+  options,
+  ...chatComponents
+}: {
+  options: TOptions
+} & ChatUIFactoryConfig<NoInfer<TOptions>>) {
+  const ui = createChatUI(
+    options,
+    chatComponents as ChatUIFactoryConfig<NoInfer<TOptions>>,
+  )
+
+  function createAppChat(overrides?: ChatInstanceOverrides<TOptions>) {
+    if (!overrides) {
+      return createUnboundChat(
+        options as HeadlessOptions<TOptions>,
+      ) as ChatUIHost<TOptions>
+    }
+    return createUnboundChat({
+      ...(options as HeadlessOptions<TOptions>),
+      ...overrides,
+    }) as ChatUIHost<TOptions>
+  }
+
+  return {
+    createAppChat,
+    ui,
+    useChatContext: ui.useChatContext,
+  }
+}

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

@@ -0,0 +1,310 @@
+import { getContext, setContext } from 'svelte'
+import {
+  automaticPartsForMessage,
+  collectInlineToolNames,
+  resolveInterruptComponent,
+  selectChatUI,
+  selectMessageUI,
+} from '@tanstack/ai-client/ui'
+import type {
+  ChatUIData,
+  ChatUIHasNamedInterrupts,
+  ChatUIHasNamedTools,
+  ChatUIInterrupt,
+  ChatUIInterruptName,
+  ChatUIInterruptOf,
+  ChatUIInterruptsOf,
+  ChatUINamedInterruptId,
+  ChatUIPartKey,
+  ChatUIPartOf,
+  ChatUISchemaOf,
+  ChatUISelectedPart,
+  ChatUIToolApproval,
+  ChatUIToolName,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import type {
+  QueuedMessage,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '@tanstack/ai-client'
+import type { CreateChatReturn } from '../types'
+
+export type ChatUIHost<TOptions = unknown> = CreateChatReturn<
+  ChatUIToolsOf<TOptions>,
+  ChatUISchemaOf<TOptions>,
+  unknown,
+  ChatUIInterruptsOf<TOptions>
+>
+
+type GenericInterruptComponents<TOptions> =
+  ChatUIHasNamedInterrupts<TOptions> extends true
+    ? {
+        [K in ChatUINamedInterruptId<TOptions>]: unknown
+      } & {
+        fallback?: unknown
+      }
+    : {
+        fallback?: unknown
+      }
+
+type ToolApprovalMap<TOptions> = {
+  [K in ChatUIToolName<TOptions>]?: unknown
+}
+
+/** The chrome around the message list: `layout`, `message`, and `input`. */
+export type ChatUIChromeComponents = {
+  layout: unknown
+  message: unknown
+  input?: unknown
+  queue?: unknown
+}
+
+export type ChatUIPartsComponents = {
+  [K in ChatUIPartKey]?: unknown
+} & {
+  fallback?: unknown
+}
+
+export type ChatUIInterruptsComponents<TOptions> = {
+  tools?: ToolApprovalMap<TOptions>
+  generic: GenericInterruptComponents<TOptions>
+}
+
+/** The flat shape the runtime reads, assembled from the factory config. */
+export type ChatUIComponents<TOptions> = ChatUIChromeComponents & {
+  parts: ChatUIPartsComponents
+  tools?: { [K in ChatUIToolName<TOptions>]?: unknown }
+  interrupts?: {
+    tools?: ToolApprovalMap<TOptions>
+    generic?: GenericInterruptComponents<TOptions>
+  }
+}
+
+export type ChatUIFactoryConfig<TOptions> = {
+  components: ChatUIChromeComponents
+  partsComponents: ChatUIPartsComponents
+} & (ChatUIHasNamedTools<TOptions> extends true
+  ? { toolsComponents: { [K in ChatUIToolName<TOptions>]: unknown } }
+  : { toolsComponents?: { [K in ChatUIToolName<TOptions>]?: unknown } }) &
+  (ChatUIHasNamedInterrupts<TOptions> extends true
+    ? { interruptsComponents: ChatUIInterruptsComponents<TOptions> }
+    : {
+        interruptsComponents?: {
+          tools?: ToolApprovalMap<TOptions>
+          generic?: GenericInterruptComponents<TOptions>
+        }
+      })
+
+export type UIDescriptor<TOptions = unknown> = {
+  key: symbol
+  warn: (key: string, message: string) => void
+  components: ChatUIComponents<TOptions>
+  useChatContext: () => ChatUIHost<TOptions>
+}
+
+export type UIContextValue<TOptions = unknown> = {
+  chat: ChatUIHost<TOptions>
+  components: ChatUIComponents<TOptions>
+  ui: UIDescriptor<TOptions>
+}
+
+type ComponentsValue<TOptions = unknown> = {
+  components: ChatUIComponents<TOptions>
+  warn: (key: string, message: string) => void
+  inlineToolNames: ReadonlyArray<string>
+}
+
+type UIRuntime<TOptions = unknown> = UIDescriptor<TOptions> & {
+  componentsKey: symbol
+}
+
+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)
+  }
+}
+
+export function createChatUI<const TOptions>(
+  options: TOptions,
+  config: ChatUIFactoryConfig<NoInfer<TOptions>>,
+): UIDescriptor<TOptions> {
+  void options
+  const {
+    components: chrome,
+    partsComponents,
+    toolsComponents,
+    interruptsComponents,
+  } = config as ChatUIFactoryConfig<TOptions> & {
+    toolsComponents?: Record<string, unknown>
+    interruptsComponents?: {
+      tools?: Record<string, unknown>
+      generic?: Record<string, unknown>
+    }
+  }
+  // The runtime keeps the flat shape the rest of this module reads.
+  const components = {
+    ...chrome,
+    parts: partsComponents,
+    tools: toolsComponents,
+    interrupts: interruptsComponents,
+  } as ChatUIComponents<TOptions>
+  const ui: UIRuntime<TOptions> = {
+    key: Symbol('tanstack-ai-ui-chat'),
+    componentsKey: Symbol('tanstack-ai-ui-components'),
+    warn: createWarnOnce(),
+    components,
+    useChatContext() {
+      return getChatContext(ui)
+    },
+  }
+  return ui
+}
+
+export function setUIContext<TOptions>(value: UIContextValue<TOptions>) {
+  setContext(value.ui.key, value.chat)
+  setContext((value.ui as UIRuntime).componentsKey, {
+    components: value.components,
+    warn: value.ui.warn,
+    inlineToolNames: inlineNames(value.components),
+  } satisfies ComponentsValue<TOptions>)
+}
+
+export function getChatContext<TOptions>(ui: UIDescriptor<TOptions>) {
+  const chat = getContext<ChatUIHost<TOptions> | undefined>(ui.key)
+  if (!chat) {
+    throw new Error(
+      'Chat UI components must be wrapped in UIProvider or UIChat.',
+    )
+  }
+  return chat
+}
+
+export function getComponentsContext<TOptions>(ui: UIDescriptor<TOptions>) {
+  const value = getContext<ComponentsValue<TOptions> | undefined>(
+    (ui as UIRuntime).componentsKey,
+  )
+  if (!value) {
+    throw new Error(
+      'Chat UI components must be wrapped in UIProvider or UIChat.',
+    )
+  }
+  return value
+}
+
+export function getUIContext<TOptions>(ui: UIDescriptor<TOptions>) {
+  return {
+    ui,
+    chat: getChatContext(ui),
+    components: getComponentsContext(ui).components,
+  } satisfies UIContextValue<TOptions>
+}
+
+export function readMessages<TOptions>(chat: ChatUIHost<TOptions>) {
+  return chat.messages ?? []
+}
+
+export function readInterrupts<TOptions>(chat: ChatUIHost<TOptions>) {
+  return chat.interrupts ?? []
+}
+
+export function readQueue<TOptions>(chat: ChatUIHost<TOptions>) {
+  const items = chat.queue ?? []
+  return items.map((item) => ({
+    ...item,
+    cancelQueued: () => {
+      chat.cancelQueued(item.id)
+    },
+  }))
+}
+
+export function inlineNames<TOptions>(components: ChatUIComponents<TOptions>) {
+  return collectInlineToolNames(
+    components.interrupts?.tools as Record<string, unknown> | undefined,
+    Object.keys(components.tools ?? {}),
+  )
+}
+
+export function messageParts(
+  message: UIMessage,
+  interrupts: ReadonlyArray<ChatUIInterrupt>,
+  inlineToolNames: ReadonlyArray<string>,
+): Array<ChatUISelectedPart> {
+  return automaticPartsForMessage(
+    selectMessageUI(message, { interrupts, inlineToolNames }),
+  )
+}
+
+export function listInterrupts<TOptions>(
+  chat: ChatUIHost<TOptions>,
+  inlineToolNames: ReadonlyArray<string>,
+) {
+  return selectChatUI({
+    messages: readMessages(chat),
+    interrupts: readInterrupts(chat),
+    inlineToolNames,
+  }).interrupts
+}
+
+export function toolComponent<TOptions>(
+  components: ChatUIComponents<TOptions>,
+  name: string,
+) {
+  return components.tools?.[name as never]
+}
+
+export function partComponent<TOptions>(
+  components: ChatUIComponents<TOptions>,
+  key: string,
+) {
+  return components.parts[key as ChatUIPartKey] ?? components.parts.fallback
+}
+
+export function interruptComponent<TOptions>(
+  components: ChatUIComponents<TOptions>,
+  interrupt: ChatUIInterrupt,
+) {
+  return resolveInterruptComponent(interrupt, components.interrupts)
+}
+
+export type ChatUIQueueItem = QueuedMessage & {
+  cancelQueued: () => void
+}
+
+export type LayoutProps<TOptions> = {
+  readonly __ui?: TOptions
+}
+export type MessageProps<TOptions> = {
+  message: UIMessage<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>
+}
+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>
+  readonly __ui?: TOptions
+}
+export type InterruptProps<
+  TOptions,
+  TName extends ChatUIInterruptName<TOptions> = never,
+> = {
+  interrupt: ChatUIInterruptOf<TOptions, TName>
+  readonly __ui?: TOptions
+}

package/src/chat-ui/selected-part.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+  import {
+    getComponentsContext,
+    partComponent,
+    toolComponent,
+    type UIDescriptor,
+  } from './create-ui'
+  import type { ChatUISelectedPart } from '@tanstack/ai-client/ui'
+
+  let {
+    ui,
+    selected,
+  }: {
+    ui: UIDescriptor
+    selected: ChatUISelectedPart
+  } = $props()
+
+  const comps = $derived(getComponentsContext(ui))
+</script>
+
+{#if selected.key === 'toolCall'}
+  {@const Tool = toolComponent(comps.components, selected.part.name) as any}
+  {#if Tool}
+    <Tool
+      part={selected.part}
+      result={selected.result}
+      interrupt={selected.interrupt}
+    />
+  {:else}
+    {comps.warn(
+      `tool:${selected.part.name}`,
+      `[tanstack-ai-ui] Missing tools.${selected.part.name} component`,
+    )}
+  {/if}
+{:else}
+  {@const Part = partComponent(comps.components, selected.key) as any}
+  {#if Part}
+    <Part part={selected.part} />
+  {:else}
+    {comps.warn(
+      `part:${selected.key}`,
+      `[tanstack-ai-ui] Missing parts.${selected.key} component`,
+    )}
+  {/if}
+{/if}

package/src/chat-ui/ui-chat.svelte

@@ -0,0 +1,42 @@
+<script lang="ts">
+  import UIProvider from './ui-provider.svelte'
+  import UIMessages from './ui-messages.svelte'
+  import UIInterrupts from './ui-interrupts.svelte'
+  import UIQueue from './ui-queue.svelte'
+  import type { ChatUIComponents, UIDescriptor } from './create-ui'
+
+  let {
+    ui,
+    chat,
+    components,
+  }: {
+    ui: UIDescriptor
+    // ponytail: Svelte components are not generic, so ChatUIHost<TOptions> cannot
+    // accept a typed createChat() host with tool-approval interrupts.
+    chat: any
+    components?: ChatUIComponents<unknown>
+  } = $props()
+
+  const bound = $derived(components ?? ui.components)
+  const Layout = $derived(bound.layout as any)
+  const Input = $derived(bound.input as any)
+</script>
+
+<UIProvider {ui} {chat} components={bound}>
+  <Layout>
+    {#snippet messages()}
+      <UIMessages {ui} />
+    {/snippet}
+    {#snippet interrupts()}
+      <UIInterrupts {ui} />
+    {/snippet}
+    {#snippet queue()}
+      <UIQueue {ui} />
+    {/snippet}
+    {#snippet input()}
+      {#if Input}
+        <Input />
+      {/if}
+    {/snippet}
+  </Layout>
+</UIProvider>

package/src/chat-ui/ui-interrupt.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  import {
+    getComponentsContext,
+    interruptComponent,
+    type UIDescriptor,
+  } from './create-ui'
+  import type { ChatUIInterrupt } from '@tanstack/ai-client/ui'
+
+  let {
+    ui,
+    interrupt,
+  }: {
+    ui: UIDescriptor
+    interrupt: ChatUIInterrupt
+  } = $props()
+
+  const comps = $derived(getComponentsContext(ui))
+  const Component = $derived(
+    interruptComponent(comps.components, interrupt) as any,
+  )
+</script>
+
+{#if Component}
+  <Component {interrupt} />
+{:else}
+  {comps.warn(
+    `interrupt:${interrupt.id}`,
+    `[tanstack-ai-ui] Missing interrupt component for ${interrupt.kind}`,
+  )}
+{/if}