@tanstack/ai-client 0.29.2 → 0.30.0

package/README.md

@@ -61,12 +61,8 @@ framework bindings as your app needs them.
 
 - [Overview](https://tanstack.com/ai/latest/docs/getting-started/overview) -
   what TanStack AI is and how the packages fit together.
-- [Quick Start: React](https://tanstack.com/ai/latest/docs/getting-started/quick-start) -
-  add streaming chat to a React app.
-- [Quick Start: Vue](https://tanstack.com/ai/latest/docs/getting-started/quick-start-vue) -
-  build with Vue composables.
-- [Quick Start: Svelte](https://tanstack.com/ai/latest/docs/getting-started/quick-start-svelte) -
-  build with Svelte 5 runes.
+- [Quick Start](https://tanstack.com/ai/latest/docs/getting-started/quick-start) -
+  add streaming chat. Pick your framework at the top of the page.
 - [Quick Start: Server Only](https://tanstack.com/ai/latest/docs/getting-started/quick-start-server) -
   use TanStack AI from a server endpoint, script, or backend service.
 - [TanStack AI vs Vercel AI SDK](https://tanstack.com/ai/latest/docs/comparison/vercel-ai-sdk) -
@@ -226,15 +222,15 @@ on.
 
 ## Framework Packages
 
-| Package                                                                    | What it provides                                                         |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| [`@tanstack/ai-client`](https://tanstack.com/ai/latest/docs/api/ai-client) | Headless chat, realtime, and generation clients                          |
-| [`@tanstack/ai-react`](https://tanstack.com/ai/latest/docs/api/ai-react)   | React hooks including `useChat`, `useRealtimeChat`, and generation hooks |
-| [`@tanstack/ai-solid`](https://tanstack.com/ai/latest/docs/api/ai-solid)   | Solid hooks for chat and generations                                     |
-| [`@tanstack/ai-vue`](https://tanstack.com/ai/latest/docs/api/ai-vue)       | Vue composables for chat and generations                                 |
-| [`@tanstack/ai-svelte`](https://tanstack.com/ai/latest/docs/api/ai-svelte) | Svelte 5 factories for chat and generations                              |
-| [`@tanstack/ai-preact`](https://tanstack.com/ai/latest/docs/api/ai-preact) | Preact hooks for chat                                                    |
-| `@tanstack/ai-react-ui`, `@tanstack/ai-solid-ui`, `@tanstack/ai-vue-ui`    | Headless UI components for chat interfaces                               |
+| Package                                                                                           | What it provides                                                                                                                        |
+| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@tanstack/ai-client`](https://tanstack.com/ai/latest/docs/api/ai-client)                        | Headless chat, realtime, and generation clients                                                                                         |
+| [`@tanstack/ai-react`](https://tanstack.com/ai/latest/docs/api/ai-react)                          | React hooks including `useChat`, `useRealtimeChat`, and generation hooks                                                                |
+| [`@tanstack/ai-solid`](https://tanstack.com/ai/latest/docs/api/ai-solid)                          | Solid hooks for chat and generations                                                                                                    |
+| [`@tanstack/ai-vue`](https://tanstack.com/ai/latest/docs/api/ai-vue)                              | Vue composables for chat and generations                                                                                                |
+| [`@tanstack/ai-svelte`](https://tanstack.com/ai/latest/docs/api/ai-svelte)                        | Svelte 5 factories for chat and generations                                                                                             |
+| [`@tanstack/ai-preact`](https://tanstack.com/ai/latest/docs/api/ai-preact)                        | Preact hooks for chat                                                                                                                   |
+| `@tanstack/ai-react/ui`, `@tanstack/ai-solid/ui`, `@tanstack/ai-vue/ui`, `@tanstack/ai-svelte/ui` | Headless UI components for chat interfaces. `@tanstack/ai-react-ui`, `@tanstack/ai-solid-ui`, and `@tanstack/ai-vue-ui` are deprecated. |
 
 ## Advanced Docs
 

package/dist/esm/ui/selectors.d.ts

@@ -0,0 +1,11 @@
+import { UIMessage } from '../types.js';
+import { ChatUIInterrupt, ChatUIPartKey, ChatUISelectInput, ChatUISelectedMessage, ChatUISelectedPart, ChatUISelection } from './types.js';
+export declare function partTypeToKey(type: string): ChatUIPartKey | string;
+export declare function collectInlineToolNames(toolInterrupts?: Record<string, unknown>, mappedToolNames?: ReadonlyArray<string>): Array<string>;
+export declare function resolveInterruptComponent(interrupt: ChatUIInterrupt, interruptsMap: {
+    tools?: Record<string, unknown>;
+    generic?: Record<string, unknown>;
+} | undefined): unknown;
+export declare function selectChatUI(input: ChatUISelectInput): ChatUISelection;
+export declare function automaticPartsForMessage(selected: ChatUISelectedMessage): Array<ChatUISelectedPart>;
+export declare function selectMessageUI(message: UIMessage, input: Omit<ChatUISelectInput, 'messages'>): ChatUISelectedMessage;

package/dist/esm/ui/selectors.js

@@ -0,0 +1,106 @@
+//#region src/ui/selectors.ts
+var PART_KEY_BY_TYPE = {
+	text: "text",
+	image: "image",
+	audio: "audio",
+	video: "video",
+	document: "document",
+	thinking: "thinking",
+	"tool-call": "toolCall",
+	"tool-result": "toolResult",
+	"structured-output": "structuredOutput",
+	"ui-resource": "uiResource"
+};
+function partTypeToKey(type) {
+	const mapped = PART_KEY_BY_TYPE[type];
+	if (mapped) return mapped;
+	return type.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function collectInlineToolNames(toolInterrupts, mappedToolNames) {
+	const listPlaced = new Set(Object.keys(toolInterrupts ?? {}));
+	return (mappedToolNames ?? []).filter((name) => !listPlaced.has(name));
+}
+function resolveInterruptComponent(interrupt, interruptsMap) {
+	if (!interruptsMap) return void 0;
+	if (interrupt.kind === "tool-approval") return interruptsMap.tools?.[interrupt.toolName];
+	const generic = interruptsMap.generic;
+	if (!generic) return void 0;
+	const definitionId = "definitionId" in interrupt && typeof interrupt.definitionId === "string" ? interrupt.definitionId : void 0;
+	if (definitionId && definitionId !== "fallback") {
+		const registered = generic[definitionId];
+		if (registered) return registered;
+	}
+	return generic.fallback;
+}
+function isToolCallPart(part) {
+	return part.type === "tool-call";
+}
+function isToolResultPart(part) {
+	return part.type === "tool-result";
+}
+function isToolApproval(interrupt) {
+	return interrupt.kind === "tool-approval";
+}
+function selectChatUI(input) {
+	const messages = input.messages;
+	const interrupts = input.interrupts ?? [];
+	const inlineToolNames = new Set(input.inlineToolNames ?? []);
+	const resultsByCallId = /* @__PURE__ */ new Map();
+	const callIds = /* @__PURE__ */ new Set();
+	for (const message of messages) for (const part of message.parts) {
+		if (isToolCallPart(part)) callIds.add(part.id);
+		if (isToolResultPart(part)) resultsByCallId.set(part.toolCallId, part);
+	}
+	const approvalByCallId = /* @__PURE__ */ new Map();
+	for (const interrupt of interrupts) if (isToolApproval(interrupt)) approvalByCallId.set(interrupt.toolCallId, interrupt);
+	return {
+		messages: messages.map((message) => ({
+			message,
+			parts: message.parts.map((part) => toSelectedPart(part, resultsByCallId, approvalByCallId, callIds))
+		})),
+		interrupts: interrupts.filter((interrupt) => {
+			if (!isToolApproval(interrupt)) return true;
+			if (!inlineToolNames.has(interrupt.toolName)) return true;
+			return !callIds.has(interrupt.toolCallId);
+		})
+	};
+}
+function toSelectedPart(part, resultsByCallId, approvalByCallId, callIds) {
+	if (isToolCallPart(part)) {
+		const result = resultsByCallId.get(part.id);
+		const interrupt = approvalByCallId.get(part.id);
+		return {
+			key: "toolCall",
+			part,
+			...result ? { result } : {},
+			...interrupt ? { interrupt } : {},
+			input: part.input,
+			output: part.output
+		};
+	}
+	if (isToolResultPart(part)) return {
+		key: "toolResult",
+		part,
+		matched: callIds.has(part.toolCallId)
+	};
+	return {
+		key: partTypeToKey(part.type),
+		part
+	};
+}
+function automaticPartsForMessage(selected) {
+	return selected.parts.filter((part) => !(part.key === "toolResult" && part.matched));
+}
+function selectMessageUI(message, input) {
+	return selectChatUI({
+		...input,
+		messages: [message]
+	}).messages[0] ?? {
+		message,
+		parts: []
+	};
+}
+//#endregion
+export { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI };
+
+//# sourceMappingURL=selectors.js.map

package/dist/esm/ui/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","names":[],"sources":["../../../src/ui/selectors.ts"],"sourcesContent":["import type {\n  MessagePart,\n  ToolApprovalInterrupt,\n  ToolCallPart,\n  ToolResultPart,\n  UIMessage,\n} from '../types'\nimport type {\n  ChatUIInterrupt,\n  ChatUIPartKey,\n  ChatUISelectInput,\n  ChatUISelectedMessage,\n  ChatUISelectedPart,\n  ChatUISelection,\n} from './types'\n\nconst PART_KEY_BY_TYPE: Record<string, ChatUIPartKey> = {\n  text: 'text',\n  image: 'image',\n  audio: 'audio',\n  video: 'video',\n  document: 'document',\n  thinking: 'thinking',\n  'tool-call': 'toolCall',\n  'tool-result': 'toolResult',\n  'structured-output': 'structuredOutput',\n  'ui-resource': 'uiResource',\n}\n\nexport function partTypeToKey(type: string): ChatUIPartKey | string {\n  const mapped = PART_KEY_BY_TYPE[type]\n  if (mapped) return mapped\n  return type.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())\n}\n\nexport function collectInlineToolNames(\n  toolInterrupts?: Record<string, unknown>,\n  mappedToolNames?: ReadonlyArray<string>,\n): Array<string> {\n  const listPlaced = new Set(Object.keys(toolInterrupts ?? {}))\n  return (mappedToolNames ?? []).filter((name) => !listPlaced.has(name))\n}\n\nexport function resolveInterruptComponent(\n  interrupt: ChatUIInterrupt,\n  interruptsMap:\n    | {\n        tools?: Record<string, unknown>\n        generic?: Record<string, unknown>\n      }\n    | undefined,\n): unknown {\n  if (!interruptsMap) return undefined\n  if (interrupt.kind === 'tool-approval') {\n    return interruptsMap.tools?.[interrupt.toolName]\n  }\n  const generic = interruptsMap.generic\n  if (!generic) return undefined\n  const definitionId =\n    'definitionId' in interrupt && typeof interrupt.definitionId === 'string'\n      ? interrupt.definitionId\n      : undefined\n  if (definitionId && definitionId !== 'fallback') {\n    const registered = generic[definitionId]\n    if (registered) return registered\n  }\n  return generic.fallback\n}\n\nfunction isToolCallPart(part: MessagePart): part is ToolCallPart {\n  return part.type === 'tool-call'\n}\n\nfunction isToolResultPart(part: MessagePart): part is ToolResultPart {\n  return part.type === 'tool-result'\n}\n\nfunction isToolApproval(\n  interrupt: ChatUIInterrupt,\n): interrupt is ToolApprovalInterrupt {\n  return interrupt.kind === 'tool-approval'\n}\n\nexport function selectChatUI(input: ChatUISelectInput): ChatUISelection {\n  const messages = input.messages\n  const interrupts = input.interrupts ?? []\n  const inlineToolNames = new Set(input.inlineToolNames ?? [])\n\n  const resultsByCallId = new Map<string, ToolResultPart>()\n  const callIds = new Set<string>()\n  for (const message of messages) {\n    for (const part of message.parts) {\n      if (isToolCallPart(part)) callIds.add(part.id)\n      if (isToolResultPart(part)) resultsByCallId.set(part.toolCallId, part)\n    }\n  }\n\n  const approvalByCallId = new Map<string, ToolApprovalInterrupt>()\n  for (const interrupt of interrupts) {\n    if (isToolApproval(interrupt)) {\n      approvalByCallId.set(interrupt.toolCallId, interrupt)\n    }\n  }\n\n  const selectedMessages: Array<ChatUISelectedMessage> = messages.map(\n    (message) => ({\n      message,\n      parts: message.parts.map((part) =>\n        toSelectedPart(part, resultsByCallId, approvalByCallId, callIds),\n      ),\n    }),\n  )\n\n  return {\n    messages: selectedMessages,\n    interrupts: interrupts.filter((interrupt) => {\n      if (!isToolApproval(interrupt)) return true\n      if (!inlineToolNames.has(interrupt.toolName)) return true\n      return !callIds.has(interrupt.toolCallId)\n    }),\n  }\n}\n\nfunction toSelectedPart(\n  part: MessagePart,\n  resultsByCallId: Map<string, ToolResultPart>,\n  approvalByCallId: Map<string, ToolApprovalInterrupt>,\n  callIds: Set<string>,\n): ChatUISelectedPart {\n  if (isToolCallPart(part)) {\n    const result = resultsByCallId.get(part.id)\n    const interrupt = approvalByCallId.get(part.id)\n    return {\n      key: 'toolCall',\n      part,\n      ...(result ? { result } : {}),\n      ...(interrupt ? { interrupt } : {}),\n      input: part.input,\n      output: part.output,\n    }\n  }\n\n  if (isToolResultPart(part)) {\n    return {\n      key: 'toolResult',\n      part,\n      matched: callIds.has(part.toolCallId),\n    }\n  }\n\n  return {\n    key: partTypeToKey(part.type) as Exclude<\n      ChatUIPartKey,\n      'toolCall' | 'toolResult'\n    >,\n    part,\n  }\n}\n\nexport function automaticPartsForMessage(\n  selected: ChatUISelectedMessage,\n): Array<ChatUISelectedPart> {\n  return selected.parts.filter(\n    (part) => !(part.key === 'toolResult' && part.matched),\n  )\n}\n\nexport function selectMessageUI(\n  message: UIMessage,\n  input: Omit<ChatUISelectInput, 'messages'>,\n): ChatUISelectedMessage {\n  return (\n    selectChatUI({ ...input, messages: [message] }).messages[0] ?? {\n      message,\n      parts: [],\n    }\n  )\n}\n"],"mappings":"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"}

package/dist/esm/ui/types.d.ts

@@ -0,0 +1,103 @@
+import { AnyClientTool, InferSchemaType, InferToolInput, InferToolOutput, InterruptDefinition, SchemaInput } from '@tanstack/ai/client';
+import { ChatInterrupt, MessagePart, RegisteredGenericInterrupt, StructuredOutputPart, ToolApprovalInterrupt, ToolCallPart, ToolResultPart, UIMessage } from '../types.js';
+export type ChatUIPartKey = 'text' | 'image' | 'audio' | 'video' | 'document' | 'thinking' | 'toolCall' | 'toolResult' | 'structuredOutput' | 'uiResource';
+export type ChatUIPartTypeByKey = {
+    text: 'text';
+    image: 'image';
+    audio: 'audio';
+    video: 'video';
+    document: 'document';
+    thinking: 'thinking';
+    toolCall: 'tool-call';
+    toolResult: 'tool-result';
+    structuredOutput: 'structured-output';
+    uiResource: 'ui-resource';
+};
+export type ChatUIPartOf<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = TKey extends ChatUIPartKey ? Extract<MessagePart<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>, {
+    type: ChatUIPartTypeByKey[TKey];
+}> : never;
+export type ChatUIToolsOf<TOptions> = TOptions extends {
+    tools: infer TTools;
+} ? TTools extends ReadonlyArray<AnyClientTool> ? TTools : any : any;
+export type ChatUIInterruptsOf<TOptions> = TOptions extends {
+    interrupts: infer TInterrupts;
+} ? TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> ? TInterrupts : readonly [] : readonly [];
+export type ChatUISchemaOf<TOptions> = TOptions extends {
+    outputSchema: infer TSchema;
+} ? TSchema extends SchemaInput ? TSchema : undefined : undefined;
+export type ChatUIData<TOptions> = TOptions extends {
+    outputSchema: infer TSchema;
+} ? TSchema extends SchemaInput ? InferSchemaType<TSchema> : unknown : unknown;
+export type ChatUIToolName<TOptions> = ChatUIToolsOf<TOptions>[number] extends infer TTool ? TTool extends AnyClientTool ? TTool['name'] : string : string;
+export type ChatUIRegisteredInterruptId<TOptions> = ChatUIInterruptsOf<TOptions>[number] extends infer TDefinition ? TDefinition extends InterruptDefinition<infer TId, any, any, any> ? TId : string : string;
+export type ChatUIHasNamedTools<TOptions> = [ChatUIToolName<TOptions>] extends [
+    never
+] ? false : [string] extends [ChatUIToolName<TOptions>] ? false : true;
+export type ChatUIHasNamedInterrupts<TOptions> = [
+    ChatUIRegisteredInterruptId<TOptions>
+] extends [never] ? false : [string] extends [ChatUIRegisteredInterruptId<TOptions>] ? false : true;
+export type ChatUINamedInterruptId<TOptions> = Exclude<ChatUIRegisteredInterruptId<TOptions>, 'fallback'>;
+export type ChatUIInterruptName<TOptions> = (ChatUIHasNamedTools<TOptions> extends true ? ChatUIToolName<TOptions> : never) | (ChatUIHasNamedInterrupts<TOptions> extends true ? ChatUINamedInterruptId<TOptions> : never);
+type ToolByName<TOptions, TName> = Extract<ChatUIToolsOf<TOptions> extends ReadonlyArray<infer TTool> ? TTool : never, {
+    name: TName;
+}>;
+export type ChatUIInterrupt = ChatInterrupt | ToolApprovalInterrupt;
+export type ChatUIToolApproval<TOptions, TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>> = Extract<ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>, {
+    kind: 'tool-approval';
+    toolName: TName;
+}>;
+export type ChatUIToolPart<TOptions, TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>> = {
+    key: 'toolCall';
+    part: Extract<ToolCallPart<ChatUIToolsOf<TOptions>>, {
+        name: TName;
+    }>;
+    result?: ToolResultPart;
+    interrupt?: Extract<ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>, {
+        kind: 'tool-approval';
+        toolName: TName;
+    }>;
+    input?: InferToolInput<ToolByName<TOptions, TName>>;
+    output?: InferToolOutput<ToolByName<TOptions, TName>>;
+};
+export type RegisteredUIInterrupt<TOptions, TId extends ChatUIRegisteredInterruptId<TOptions> = ChatUIRegisteredInterruptId<TOptions>> = Extract<RegisteredGenericInterrupt<ChatUIInterruptsOf<TOptions>>, {
+    definitionId: TId;
+}>;
+export type ChatUIInterruptOf<TOptions, TName extends ChatUIInterruptName<TOptions> = never> = [TName] extends [never] ? ChatUIInterrupt : TName extends (ChatUIHasNamedTools<TOptions> extends true ? ChatUIToolName<TOptions> : never) ? ChatUIToolApproval<TOptions, TName> : TName extends ChatUINamedInterruptId<TOptions> ? RegisteredUIInterrupt<TOptions, TName> : ChatUIInterrupt;
+export type ChatUISelectedToolPart = {
+    key: 'toolCall';
+    part: ToolCallPart;
+    result?: ToolResultPart;
+    interrupt?: ChatUIInterrupt;
+    input?: unknown;
+    output?: unknown;
+};
+export type ChatUISelectedResultPart = {
+    key: 'toolResult';
+    part: ToolResultPart;
+    matched: boolean;
+};
+export type ChatUISelectedGenericPart = {
+    key: Exclude<ChatUIPartKey, 'toolCall' | 'toolResult'>;
+    part: MessagePart;
+};
+export type ChatUISelectedPart = ChatUISelectedToolPart | ChatUISelectedResultPart | ChatUISelectedGenericPart;
+export type ChatUISelectedPartOf<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = TKey extends 'toolCall' ? ChatUIToolPart<TOptions> : TKey extends 'toolResult' ? ChatUISelectedResultPart : {
+    key: TKey;
+    part: ChatUIPartOf<TOptions, TKey>;
+};
+export type ChatUISelectedMessage = {
+    message: UIMessage;
+    parts: Array<ChatUISelectedPart>;
+};
+export type ChatUISelection = {
+    messages: Array<ChatUISelectedMessage>;
+    interrupts: Array<ChatUIInterrupt>;
+};
+export type ChatUISelectInput = {
+    messages: ReadonlyArray<UIMessage>;
+    interrupts?: ReadonlyArray<ChatUIInterrupt>;
+    inlineToolNames?: ReadonlyArray<string>;
+};
+export type ChatUIMessages<TOptions> = Array<UIMessage<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>>;
+export type ChatUIStructuredPart<TOptions> = StructuredOutputPart<ChatUIData<TOptions>>;
+export {};

package/dist/esm/ui.d.ts

@@ -0,0 +1,3 @@
+export { partTypeToKey, selectChatUI } from './ui/selectors.js';
+export { automaticPartsForMessage, collectInlineToolNames, resolveInterruptComponent, selectMessageUI, } from './ui/selectors.js';
+export type { ChatUIData, ChatUIHasNamedInterrupts, ChatUIHasNamedTools, ChatUIInterrupt, ChatUIInterruptName, ChatUIInterruptOf, ChatUIInterruptsOf, ChatUINamedInterruptId, ChatUIMessages, ChatUIPartKey, ChatUIPartOf, ChatUIPartTypeByKey, ChatUIRegisteredInterruptId, ChatUISchemaOf, ChatUISelectInput, ChatUISelectedGenericPart, ChatUISelectedMessage, ChatUISelectedPart, ChatUISelectedPartOf, ChatUISelectedResultPart, ChatUISelectedToolPart, ChatUISelection, ChatUIStructuredPart, ChatUIToolApproval, ChatUIToolName, ChatUIToolPart, ChatUIToolsOf, RegisteredUIInterrupt, } from './ui/types.js';

package/dist/esm/ui.js

@@ -0,0 +1,2 @@
+import { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI } from "./ui/selectors.js";
+export { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.29.2",
+  "version": "0.30.0",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -46,6 +46,10 @@
     "./byok": {
       "types": "./dist/esm/byok.d.ts",
       "import": "./dist/esm/byok.js"
+    },
+    "./ui": {
+      "types": "./dist/esm/ui.d.ts",
+      "import": "./dist/esm/ui.js"
     }
   },
   "files": [
@@ -53,7 +57,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "^0.52.0",
+    "@tanstack/ai": "^0.52.1",
     "@tanstack/ai-event-client": "^0.11.2",
     "@tanstack/ai-utils": "^0.4.0"
   },

package/src/ui/selectors.ts

@@ -0,0 +1,178 @@
+import type {
+  MessagePart,
+  ToolApprovalInterrupt,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '../types'
+import type {
+  ChatUIInterrupt,
+  ChatUIPartKey,
+  ChatUISelectInput,
+  ChatUISelectedMessage,
+  ChatUISelectedPart,
+  ChatUISelection,
+} from './types'
+
+const PART_KEY_BY_TYPE: Record<string, ChatUIPartKey> = {
+  text: 'text',
+  image: 'image',
+  audio: 'audio',
+  video: 'video',
+  document: 'document',
+  thinking: 'thinking',
+  'tool-call': 'toolCall',
+  'tool-result': 'toolResult',
+  'structured-output': 'structuredOutput',
+  'ui-resource': 'uiResource',
+}
+
+export function partTypeToKey(type: string): ChatUIPartKey | string {
+  const mapped = PART_KEY_BY_TYPE[type]
+  if (mapped) return mapped
+  return type.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+}
+
+export function collectInlineToolNames(
+  toolInterrupts?: Record<string, unknown>,
+  mappedToolNames?: ReadonlyArray<string>,
+): Array<string> {
+  const listPlaced = new Set(Object.keys(toolInterrupts ?? {}))
+  return (mappedToolNames ?? []).filter((name) => !listPlaced.has(name))
+}
+
+export function resolveInterruptComponent(
+  interrupt: ChatUIInterrupt,
+  interruptsMap:
+    | {
+        tools?: Record<string, unknown>
+        generic?: Record<string, unknown>
+      }
+    | undefined,
+): unknown {
+  if (!interruptsMap) return undefined
+  if (interrupt.kind === 'tool-approval') {
+    return interruptsMap.tools?.[interrupt.toolName]
+  }
+  const generic = interruptsMap.generic
+  if (!generic) return undefined
+  const definitionId =
+    'definitionId' in interrupt && typeof interrupt.definitionId === 'string'
+      ? interrupt.definitionId
+      : undefined
+  if (definitionId && definitionId !== 'fallback') {
+    const registered = generic[definitionId]
+    if (registered) return registered
+  }
+  return generic.fallback
+}
+
+function isToolCallPart(part: MessagePart): part is ToolCallPart {
+  return part.type === 'tool-call'
+}
+
+function isToolResultPart(part: MessagePart): part is ToolResultPart {
+  return part.type === 'tool-result'
+}
+
+function isToolApproval(
+  interrupt: ChatUIInterrupt,
+): interrupt is ToolApprovalInterrupt {
+  return interrupt.kind === 'tool-approval'
+}
+
+export function selectChatUI(input: ChatUISelectInput): ChatUISelection {
+  const messages = input.messages
+  const interrupts = input.interrupts ?? []
+  const inlineToolNames = new Set(input.inlineToolNames ?? [])
+
+  const resultsByCallId = new Map<string, ToolResultPart>()
+  const callIds = new Set<string>()
+  for (const message of messages) {
+    for (const part of message.parts) {
+      if (isToolCallPart(part)) callIds.add(part.id)
+      if (isToolResultPart(part)) resultsByCallId.set(part.toolCallId, part)
+    }
+  }
+
+  const approvalByCallId = new Map<string, ToolApprovalInterrupt>()
+  for (const interrupt of interrupts) {
+    if (isToolApproval(interrupt)) {
+      approvalByCallId.set(interrupt.toolCallId, interrupt)
+    }
+  }
+
+  const selectedMessages: Array<ChatUISelectedMessage> = messages.map(
+    (message) => ({
+      message,
+      parts: message.parts.map((part) =>
+        toSelectedPart(part, resultsByCallId, approvalByCallId, callIds),
+      ),
+    }),
+  )
+
+  return {
+    messages: selectedMessages,
+    interrupts: interrupts.filter((interrupt) => {
+      if (!isToolApproval(interrupt)) return true
+      if (!inlineToolNames.has(interrupt.toolName)) return true
+      return !callIds.has(interrupt.toolCallId)
+    }),
+  }
+}
+
+function toSelectedPart(
+  part: MessagePart,
+  resultsByCallId: Map<string, ToolResultPart>,
+  approvalByCallId: Map<string, ToolApprovalInterrupt>,
+  callIds: Set<string>,
+): ChatUISelectedPart {
+  if (isToolCallPart(part)) {
+    const result = resultsByCallId.get(part.id)
+    const interrupt = approvalByCallId.get(part.id)
+    return {
+      key: 'toolCall',
+      part,
+      ...(result ? { result } : {}),
+      ...(interrupt ? { interrupt } : {}),
+      input: part.input,
+      output: part.output,
+    }
+  }
+
+  if (isToolResultPart(part)) {
+    return {
+      key: 'toolResult',
+      part,
+      matched: callIds.has(part.toolCallId),
+    }
+  }
+
+  return {
+    key: partTypeToKey(part.type) as Exclude<
+      ChatUIPartKey,
+      'toolCall' | 'toolResult'
+    >,
+    part,
+  }
+}
+
+export function automaticPartsForMessage(
+  selected: ChatUISelectedMessage,
+): Array<ChatUISelectedPart> {
+  return selected.parts.filter(
+    (part) => !(part.key === 'toolResult' && part.matched),
+  )
+}
+
+export function selectMessageUI(
+  message: UIMessage,
+  input: Omit<ChatUISelectInput, 'messages'>,
+): ChatUISelectedMessage {
+  return (
+    selectChatUI({ ...input, messages: [message] }).messages[0] ?? {
+      message,
+      parts: [],
+    }
+  )
+}

package/src/ui/types.ts

@@ -0,0 +1,243 @@
+import type {
+  AnyClientTool,
+  InferSchemaType,
+  InferToolInput,
+  InferToolOutput,
+  InterruptDefinition,
+  SchemaInput,
+} from '@tanstack/ai/client'
+import type {
+  ChatInterrupt,
+  MessagePart,
+  RegisteredGenericInterrupt,
+  StructuredOutputPart,
+  ToolApprovalInterrupt,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '../types'
+
+export type ChatUIPartKey =
+  | 'text'
+  | 'image'
+  | 'audio'
+  | 'video'
+  | 'document'
+  | 'thinking'
+  | 'toolCall'
+  | 'toolResult'
+  | 'structuredOutput'
+  | 'uiResource'
+
+export type ChatUIPartTypeByKey = {
+  text: 'text'
+  image: 'image'
+  audio: 'audio'
+  video: 'video'
+  document: 'document'
+  thinking: 'thinking'
+  toolCall: 'tool-call'
+  toolResult: 'tool-result'
+  structuredOutput: 'structured-output'
+  uiResource: 'ui-resource'
+}
+
+export type ChatUIPartOf<
+  TOptions,
+  TKey extends ChatUIPartKey = ChatUIPartKey,
+> = TKey extends ChatUIPartKey
+  ? Extract<
+      MessagePart<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>,
+      { type: ChatUIPartTypeByKey[TKey] }
+    >
+  : never
+
+export type ChatUIToolsOf<TOptions> = TOptions extends {
+  tools: infer TTools
+}
+  ? TTools extends ReadonlyArray<AnyClientTool>
+    ? TTools
+    : any
+  : any
+
+export type ChatUIInterruptsOf<TOptions> = TOptions extends {
+  interrupts: infer TInterrupts
+}
+  ? TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>
+    ? TInterrupts
+    : readonly []
+  : readonly []
+
+export type ChatUISchemaOf<TOptions> = TOptions extends {
+  outputSchema: infer TSchema
+}
+  ? TSchema extends SchemaInput
+    ? TSchema
+    : undefined
+  : undefined
+
+export type ChatUIData<TOptions> = TOptions extends {
+  outputSchema: infer TSchema
+}
+  ? TSchema extends SchemaInput
+    ? InferSchemaType<TSchema>
+    : unknown
+  : unknown
+
+export type ChatUIToolName<TOptions> =
+  ChatUIToolsOf<TOptions>[number] extends infer TTool
+    ? TTool extends AnyClientTool
+      ? TTool['name']
+      : string
+    : string
+
+export type ChatUIRegisteredInterruptId<TOptions> =
+  ChatUIInterruptsOf<TOptions>[number] extends infer TDefinition
+    ? TDefinition extends InterruptDefinition<infer TId, any, any, any>
+      ? TId
+      : string
+    : string
+
+export type ChatUIHasNamedTools<TOptions> = [ChatUIToolName<TOptions>] extends [
+  never,
+]
+  ? false
+  : [string] extends [ChatUIToolName<TOptions>]
+    ? false
+    : true
+
+export type ChatUIHasNamedInterrupts<TOptions> = [
+  ChatUIRegisteredInterruptId<TOptions>,
+] extends [never]
+  ? false
+  : [string] extends [ChatUIRegisteredInterruptId<TOptions>]
+    ? false
+    : true
+
+export type ChatUINamedInterruptId<TOptions> = Exclude<
+  ChatUIRegisteredInterruptId<TOptions>,
+  'fallback'
+>
+
+export type ChatUIInterruptName<TOptions> =
+  | (ChatUIHasNamedTools<TOptions> extends true
+      ? ChatUIToolName<TOptions>
+      : never)
+  | (ChatUIHasNamedInterrupts<TOptions> extends true
+      ? ChatUINamedInterruptId<TOptions>
+      : never)
+
+type ToolByName<TOptions, TName> = Extract<
+  ChatUIToolsOf<TOptions> extends ReadonlyArray<infer TTool> ? TTool : never,
+  { name: TName }
+>
+
+export type ChatUIInterrupt = ChatInterrupt | ToolApprovalInterrupt
+
+export type ChatUIToolApproval<
+  TOptions,
+  TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
+> = Extract<
+  ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>,
+  { kind: 'tool-approval'; toolName: TName }
+>
+
+export type ChatUIToolPart<
+  TOptions,
+  TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
+> = {
+  key: 'toolCall'
+  part: Extract<ToolCallPart<ChatUIToolsOf<TOptions>>, { name: TName }>
+  result?: ToolResultPart
+  interrupt?: Extract<
+    ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>,
+    { kind: 'tool-approval'; toolName: TName }
+  >
+  input?: InferToolInput<ToolByName<TOptions, TName>>
+  output?: InferToolOutput<ToolByName<TOptions, TName>>
+}
+
+export type RegisteredUIInterrupt<
+  TOptions,
+  TId extends ChatUIRegisteredInterruptId<TOptions> =
+    ChatUIRegisteredInterruptId<TOptions>,
+> = Extract<
+  RegisteredGenericInterrupt<ChatUIInterruptsOf<TOptions>>,
+  { definitionId: TId }
+>
+
+export type ChatUIInterruptOf<
+  TOptions,
+  TName extends ChatUIInterruptName<TOptions> = never,
+> = [TName] extends [never]
+  ? ChatUIInterrupt
+  : TName extends (
+        ChatUIHasNamedTools<TOptions> extends true
+          ? ChatUIToolName<TOptions>
+          : never
+      )
+    ? ChatUIToolApproval<TOptions, TName>
+    : TName extends ChatUINamedInterruptId<TOptions>
+      ? RegisteredUIInterrupt<TOptions, TName>
+      : ChatUIInterrupt
+
+export type ChatUISelectedToolPart = {
+  key: 'toolCall'
+  part: ToolCallPart
+  result?: ToolResultPart
+  interrupt?: ChatUIInterrupt
+  input?: unknown
+  output?: unknown
+}
+
+export type ChatUISelectedResultPart = {
+  key: 'toolResult'
+  part: ToolResultPart
+  matched: boolean
+}
+
+export type ChatUISelectedGenericPart = {
+  key: Exclude<ChatUIPartKey, 'toolCall' | 'toolResult'>
+  part: MessagePart
+}
+
+export type ChatUISelectedPart =
+  | ChatUISelectedToolPart
+  | ChatUISelectedResultPart
+  | ChatUISelectedGenericPart
+
+export type ChatUISelectedPartOf<
+  TOptions,
+  TKey extends ChatUIPartKey = ChatUIPartKey,
+> = TKey extends 'toolCall'
+  ? ChatUIToolPart<TOptions>
+  : TKey extends 'toolResult'
+    ? ChatUISelectedResultPart
+    : {
+        key: TKey
+        part: ChatUIPartOf<TOptions, TKey>
+      }
+
+export type ChatUISelectedMessage = {
+  message: UIMessage
+  parts: Array<ChatUISelectedPart>
+}
+
+export type ChatUISelection = {
+  messages: Array<ChatUISelectedMessage>
+  interrupts: Array<ChatUIInterrupt>
+}
+
+export type ChatUISelectInput = {
+  messages: ReadonlyArray<UIMessage>
+  interrupts?: ReadonlyArray<ChatUIInterrupt>
+  inlineToolNames?: ReadonlyArray<string>
+}
+
+export type ChatUIMessages<TOptions> = Array<
+  UIMessage<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>
+>
+
+export type ChatUIStructuredPart<TOptions> = StructuredOutputPart<
+  ChatUIData<TOptions>
+>

package/src/ui.ts

@@ -0,0 +1,37 @@
+export { partTypeToKey, selectChatUI } from './ui/selectors'
+export {
+  automaticPartsForMessage,
+  collectInlineToolNames,
+  resolveInterruptComponent,
+  selectMessageUI,
+} from './ui/selectors'
+export type {
+  ChatUIData,
+  ChatUIHasNamedInterrupts,
+  ChatUIHasNamedTools,
+  ChatUIInterrupt,
+  ChatUIInterruptName,
+  ChatUIInterruptOf,
+  ChatUIInterruptsOf,
+  ChatUINamedInterruptId,
+  ChatUIMessages,
+  ChatUIPartKey,
+  ChatUIPartOf,
+  ChatUIPartTypeByKey,
+  ChatUIRegisteredInterruptId,
+  ChatUISchemaOf,
+  ChatUISelectInput,
+  ChatUISelectedGenericPart,
+  ChatUISelectedMessage,
+  ChatUISelectedPart,
+  ChatUISelectedPartOf,
+  ChatUISelectedResultPart,
+  ChatUISelectedToolPart,
+  ChatUISelection,
+  ChatUIStructuredPart,
+  ChatUIToolApproval,
+  ChatUIToolName,
+  ChatUIToolPart,
+  ChatUIToolsOf,
+  RegisteredUIInterrupt,
+} from './ui/types'