@tanstack/ai-react 0.8.2 → 0.10.0

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { useChat } from './use-chat.js';
 export { useRealtimeChat } from './use-realtime-chat.js';
-export type { UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, } from './types.js';
+export type { DeepPartial, UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, } from './types.js';
 export type { UseRealtimeChatOptions, UseRealtimeChatReturn, } from './realtime-types.js';
 export { useGeneration } from './use-generation.js';
 export type { UseGenerationOptions, UseGenerationReturn, } from './use-generation.js';

package/dist/esm/types.d.ts

@@ -1,6 +1,14 @@
-import { AnyClientTool, ModelMessage } from '@tanstack/ai';
+import { AnyClientTool, InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai';
 import { ChatClientOptions, ChatClientState, ChatRequestBody, ConnectionStatus, MultimodalContent, UIMessage } from '@tanstack/ai-client';
 export type { ChatRequestBody, MultimodalContent, UIMessage };
+/**
+ * Recursive partial — every property and every nested array element is optional.
+ * Used to type the in-flight `partial` value the hook exposes while a structured
+ * output stream is still arriving (the JSON has shape but is incomplete).
+ */
+export type DeepPartial<T> = T extends ReadonlyArray<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * Options for the useChat hook.
  *
@@ -14,17 +22,51 @@ export type { ChatRequestBody, MultimodalContent, UIMessage };
  * All other callbacks (onResponse, onChunk, onFinish, onError) are
  * passed through to the underlying ChatClient and can be used for side effects.
  *
+ * When `outputSchema` is supplied, the hook returns a typed `partial` (live
+ * progressive object, updated from `TEXT_MESSAGE_CONTENT` deltas via
+ * `parsePartialJSON`) and `final` (validated terminal payload from the
+ * `structured-output.complete` event). The schema is used purely for type
+ * inference on the client — server-side validation still runs against the
+ * schema you pass to `chat({ outputSchema })` on the server route.
+ *
  * Note: Connection and body changes will recreate the ChatClient instance.
  * To update these options, remount the component or use a key prop.
  */
-export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> = Omit<ChatClientOptions<TTools>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange' | 'onStatusChange' | 'onSubscriptionChange' | 'onConnectionStatusChange' | 'onSessionGeneratingChange'> & {
+export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any, TSchema extends SchemaInput | undefined = undefined> = Omit<ChatClientOptions<TTools>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange' | 'onStatusChange' | 'onSubscriptionChange' | 'onConnectionStatusChange' | 'onSessionGeneratingChange'> & {
     /**
      * Opt into mount-time live subscription behavior.
      * When enabled, the hook subscribes on mount and unsubscribes on unmount.
      */
     live?: boolean;
+    /**
+     * Standard-schema-compatible schema (Zod, Valibot, ArkType, or a plain JSON
+     * Schema). Used to infer the shape of `partial` and `final` in the return.
+     * The schema is **not** sent to the server — server-side validation runs
+     * against the schema passed to `chat({ outputSchema })` on the server route.
+     */
+    outputSchema?: TSchema;
 };
-export interface UseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
+/**
+ * Discriminated return shape: when `outputSchema` is supplied, the hook adds
+ * typed `partial` / `final` fields; when it is omitted (default), the return
+ * is unchanged.
+ */
+export type UseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any, TSchema extends SchemaInput | undefined = undefined> = BaseUseChatReturn<TTools> & (TSchema extends SchemaInput ? {
+    /**
+     * Live, progressively-parsed structured output. Updated from
+     * `TEXT_MESSAGE_CONTENT` deltas via `parsePartialJSON` while the stream
+     * is still arriving, and snapped to the validated payload when
+     * `structured-output.complete` fires. Resets on every new run
+     * (`sendMessage` / `reload`).
+     */
+    partial: DeepPartial<InferSchemaType<TSchema>>;
+    /**
+     * Final, schema-validated structured output. `null` until the terminal
+     * `structured-output.complete` event arrives. Resets on every new run.
+     */
+    final: InferSchemaType<TSchema> | null;
+} : Record<never, never>);
+interface BaseUseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
     /**
      * Current messages in the conversation
      */

package/dist/esm/use-chat.d.ts

@@ -1,3 +1,3 @@
-import { AnyClientTool } from '@tanstack/ai';
+import { AnyClientTool, SchemaInput } from '@tanstack/ai';
 import { UseChatOptions, UseChatReturn } from './types.js';
-export declare function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(options: UseChatOptions<TTools>): UseChatReturn<TTools>;
+export declare function useChat<TTools extends ReadonlyArray<AnyClientTool> = any, TSchema extends SchemaInput | undefined = undefined>(options: UseChatOptions<TTools, TSchema>): UseChatReturn<TTools, TSchema>;

package/dist/esm/use-chat.js

@@ -1,4 +1,5 @@
 import { ChatClient } from "@tanstack/ai-client";
+import { parsePartialJSON } from "@tanstack/ai";
 import { useId, useState, useRef, useMemo, useEffect, useCallback } from "react";
 function useChat(options) {
   const hookId = useId();
@@ -12,6 +13,9 @@ function useChat(options) {
   const [isSubscribed, setIsSubscribed] = useState(false);
   const [connectionStatus, setConnectionStatus] = useState("disconnected");
   const [sessionGenerating, setSessionGenerating] = useState(false);
+  const [partial, setPartial] = useState({});
+  const [final, setFinal] = useState(null);
+  const rawJsonRef = useRef("");
   const messagesRef = useRef(
     options.initialMessages || []
   );
@@ -27,11 +31,30 @@ function useChat(options) {
       id: clientId,
       initialMessages: messagesToUse,
       body: optionsRef.current.body,
+      forwardedProps: optionsRef.current.forwardedProps,
       // Wrap every callback so the latest options are read at call time.
       // Capturing the function reference directly would freeze it to whatever
       // the parent passed on the first render.
       onResponse: (response) => optionsRef.current.onResponse?.(response),
-      onChunk: (chunk) => optionsRef.current.onChunk?.(chunk),
+      onChunk: (chunk) => {
+        if (optionsRef.current.outputSchema !== void 0) {
+          if (chunk.type === "RUN_STARTED") {
+            rawJsonRef.current = "";
+            setPartial({});
+            setFinal(null);
+          } else if (chunk.type === "TEXT_MESSAGE_CONTENT" && chunk.delta) {
+            rawJsonRef.current += chunk.delta;
+            const progressive = parsePartialJSON(rawJsonRef.current);
+            if (progressive && typeof progressive === "object") {
+              setPartial(progressive);
+            }
+          } else if (chunk.type === "CUSTOM" && chunk.name === "structured-output.complete") {
+            const value = chunk.value;
+            setFinal(value.object);
+          }
+        }
+        optionsRef.current.onChunk?.(chunk);
+      },
       onFinish: (message) => {
         optionsRef.current.onFinish?.(message);
       },
@@ -65,8 +88,11 @@ function useChat(options) {
     });
   }, [clientId]);
   useEffect(() => {
-    client.updateOptions({ body: options.body });
-  }, [client, options.body]);
+    client.updateOptions({
+      body: options.body,
+      forwardedProps: options.forwardedProps
+    });
+  }, [client, options.body, options.forwardedProps]);
   useEffect(() => {
     if (options.initialMessages && options.initialMessages.length > 0) {
       if (messages.length === 0) {
@@ -144,7 +170,9 @@ function useChat(options) {
     setMessages: setMessagesManually,
     clear,
     addToolResult,
-    addToolApprovalResponse
+    addToolApprovalResponse,
+    partial,
+    final
   };
 }
 export {

package/dist/esm/use-chat.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-chat.js","sources":["../../src/use-chat.ts"],"sourcesContent":["import { ChatClient } from '@tanstack/ai-client'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { AnyClientTool, ModelMessage } from '@tanstack/ai'\nimport type { ChatClientState, ConnectionStatus } from '@tanstack/ai-client'\n\nimport type {\n  MultimodalContent,\n  UIMessage,\n  UseChatOptions,\n  UseChatReturn,\n} from './types'\n\nexport function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(\n  options: UseChatOptions<TTools>,\n): UseChatReturn<TTools> {\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<ChatClientState>('ready')\n  const [isSubscribed, setIsSubscribed] = useState(false)\n  const [connectionStatus, setConnectionStatus] =\n    useState<ConnectionStatus>('disconnected')\n  const [sessionGenerating, setSessionGenerating] = useState(false)\n\n  // Track current messages in a ref to preserve them when client is recreated\n  const messagesRef = useRef<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const isFirstMountRef = useRef(true)\n\n  // Update ref synchronously during render so it's always current when useMemo runs.\n  // A useEffect here would be async and messagesRef could be stale on client recreation.\n  messagesRef.current = messages\n\n  // Track current options in a ref to avoid recreating client when options change\n  const optionsRef = useRef<UseChatOptions<TTools>>(options)\n  optionsRef.current = options\n\n  // Create ChatClient instance with callbacks to sync state\n  // Note: Options are captured at client creation time.\n  // The connection adapter can use functions for dynamic values (url, headers, etc.)\n  // which are evaluated lazily on each request.\n  const client = useMemo(() => {\n    // On first mount, use initialMessages. On subsequent recreations, preserve existing messages.\n    const messagesToUse = isFirstMountRef.current\n      ? options.initialMessages || []\n      : messagesRef.current\n\n    isFirstMountRef.current = false\n\n    return new ChatClient({\n      connection: optionsRef.current.connection,\n      id: clientId,\n      initialMessages: messagesToUse,\n      body: optionsRef.current.body,\n      // Wrap every callback so the latest options are read at call time.\n      // Capturing the function reference directly would freeze it to whatever\n      // the parent passed on the first render.\n      onResponse: (response) => optionsRef.current.onResponse?.(response),\n      onChunk: (chunk) => optionsRef.current.onChunk?.(chunk),\n      onFinish: (message: UIMessage<TTools>) => {\n        optionsRef.current.onFinish?.(message)\n      },\n      onError: (error: Error) => {\n        optionsRef.current.onError?.(error)\n      },\n      tools: optionsRef.current.tools,\n      onCustomEvent: (eventType, data, context) =>\n        optionsRef.current.onCustomEvent?.(eventType, data, context),\n      streamProcessor: options.streamProcessor,\n      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {\n        setMessages(newMessages)\n      },\n      onLoadingChange: (newIsLoading: boolean) => {\n        setIsLoading(newIsLoading)\n      },\n      onErrorChange: (newError: Error | undefined) => {\n        setError(newError)\n      },\n      onStatusChange: (status: ChatClientState) => {\n        setStatus(status)\n      },\n      onSubscriptionChange: (nextIsSubscribed: boolean) => {\n        setIsSubscribed(nextIsSubscribed)\n      },\n      onConnectionStatusChange: (nextStatus: ConnectionStatus) => {\n        setConnectionStatus(nextStatus)\n      },\n      onSessionGeneratingChange: (isGenerating: boolean) => {\n        setSessionGenerating(isGenerating)\n      },\n    })\n  }, [clientId])\n\n  // Sync body changes to the client\n  // This allows dynamic body values (like model selection) to be updated without recreating the client\n  useEffect(() => {\n    client.updateOptions({ body: options.body })\n  }, [client, options.body])\n\n  // Sync initial messages on mount only\n  // Note: initialMessages are passed to ChatClient constructor, but we also\n  // set them here to ensure React state is in sync\n  useEffect(() => {\n    if (options.initialMessages && options.initialMessages.length > 0) {\n      // Only set if current messages are empty (initial state)\n      if (messages.length === 0) {\n        client.setMessagesManually(options.initialMessages)\n      }\n    }\n  }, []) // Only run on mount - initialMessages are handled by ChatClient constructor\n\n  // Keep connection lifecycle opt-in and explicit.\n  useEffect(() => {\n    if (options.live) {\n      client.subscribe()\n    } else {\n      client.unsubscribe()\n    }\n  }, [client, options.live])\n\n  // Cleanup on unmount: stop any in-flight requests\n  // Note: We only cleanup when client changes or component unmounts.\n  // DO NOT include isLoading in dependencies - that would cause the cleanup\n  // to run when isLoading changes, aborting continuation requests.\n  useEffect(() => {\n    return () => {\n      // live mode owns the connection lifecycle; non-live keeps request-only stop.\n      if (options.live) {\n        client.unsubscribe()\n      } else {\n        client.stop()\n      }\n    }\n  }, [client, options.live])\n\n  // All callback options are read through optionsRef at call time, so fresh\n  // closures from each render are picked up without recreating the client.\n\n  const sendMessage = useCallback(\n    async (content: string | MultimodalContent) => {\n      await client.sendMessage(content)\n    },\n    [client],\n  )\n\n  const append = useCallback(\n    async (message: ModelMessage | UIMessage) => {\n      await client.append(message)\n    },\n    [client],\n  )\n\n  const reload = useCallback(async () => {\n    await client.reload()\n  }, [client])\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const clear = useCallback(() => {\n    client.clear()\n  }, [client])\n\n  const setMessagesManually = useCallback(\n    (newMessages: Array<UIMessage<TTools>>) => {\n      client.setMessagesManually(newMessages)\n    },\n    [client],\n  )\n\n  const addToolResult = useCallback(\n    async (result: {\n      toolCallId: string\n      tool: string\n      output: any\n      state?: 'output-available' | 'output-error'\n      errorText?: string\n    }) => {\n      await client.addToolResult(result)\n    },\n    [client],\n  )\n\n  const addToolApprovalResponse = useCallback(\n    async (response: { id: string; approved: boolean }) => {\n      await client.addToolApprovalResponse(response)\n    },\n    [client],\n  )\n\n  return {\n    messages,\n    sendMessage,\n    append,\n    reload,\n    stop,\n    isLoading,\n    error,\n    status,\n    isSubscribed,\n    connectionStatus,\n    sessionGenerating,\n    setMessages: setMessagesManually,\n    clear,\n    addToolResult,\n    addToolApprovalResponse,\n  }\n}\n"],"names":["error","status"],"mappings":"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"}
+{"version":3,"file":"use-chat.js","sources":["../../src/use-chat.ts"],"sourcesContent":["import { ChatClient } from '@tanstack/ai-client'\nimport { parsePartialJSON } from '@tanstack/ai'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type {\n  AnyClientTool,\n  InferSchemaType,\n  ModelMessage,\n  SchemaInput,\n  StreamChunk,\n} from '@tanstack/ai'\nimport type { ChatClientState, ConnectionStatus } from '@tanstack/ai-client'\n\nimport type {\n  DeepPartial,\n  MultimodalContent,\n  UIMessage,\n  UseChatOptions,\n  UseChatReturn,\n} from './types'\n\nexport function useChat<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TSchema extends SchemaInput | undefined = undefined,\n>(options: UseChatOptions<TTools, TSchema>): UseChatReturn<TTools, TSchema> {\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [messages, setMessages] = useState<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<ChatClientState>('ready')\n  const [isSubscribed, setIsSubscribed] = useState(false)\n  const [connectionStatus, setConnectionStatus] =\n    useState<ConnectionStatus>('disconnected')\n  const [sessionGenerating, setSessionGenerating] = useState(false)\n\n  // Structured-output state. Only meaningful when `outputSchema` is supplied;\n  // when it isn't, these stay at their initial values and are hidden from the\n  // return type by the conditional in UseChatReturn. Runtime always tracks\n  // them — the type system gates visibility, not the runtime.\n  type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>\n  type Final = InferSchemaType<NonNullable<TSchema>>\n  const [partial, setPartial] = useState<Partial>({} as Partial)\n  const [final, setFinal] = useState<Final | null>(null)\n  // Raw JSON accumulator for parsePartialJSON. Ref instead of state — partial\n  // JSON parsing happens synchronously inside the chunk handler; we don't want\n  // a re-render per delta solely to track the buffer.\n  const rawJsonRef = useRef('')\n\n  // Track current messages in a ref to preserve them when client is recreated\n  const messagesRef = useRef<Array<UIMessage<TTools>>>(\n    options.initialMessages || [],\n  )\n  const isFirstMountRef = useRef(true)\n\n  // Update ref synchronously during render so it's always current when useMemo runs.\n  // A useEffect here would be async and messagesRef could be stale on client recreation.\n  messagesRef.current = messages\n\n  // Track current options in a ref to avoid recreating client when options change\n  const optionsRef = useRef<UseChatOptions<TTools, TSchema>>(options)\n  optionsRef.current = options\n\n  // Create ChatClient instance with callbacks to sync state\n  // Note: Options are captured at client creation time.\n  // The connection adapter can use functions for dynamic values (url, headers, etc.)\n  // which are evaluated lazily on each request.\n  const client = useMemo(() => {\n    // On first mount, use initialMessages. On subsequent recreations, preserve existing messages.\n    const messagesToUse = isFirstMountRef.current\n      ? options.initialMessages || []\n      : messagesRef.current\n\n    isFirstMountRef.current = false\n\n    return new ChatClient({\n      connection: optionsRef.current.connection,\n      id: clientId,\n      initialMessages: messagesToUse,\n      body: optionsRef.current.body,\n      forwardedProps: optionsRef.current.forwardedProps,\n      // Wrap every callback so the latest options are read at call time.\n      // Capturing the function reference directly would freeze it to whatever\n      // the parent passed on the first render.\n      onResponse: (response) => optionsRef.current.onResponse?.(response),\n      onChunk: (chunk: StreamChunk) => {\n        // Internal structured-output tracking — runs before the user callback\n        // so user code observes the same state the hook does. Only active when\n        // a schema is supplied; otherwise the branches are no-ops.\n        if (optionsRef.current.outputSchema !== undefined) {\n          if (chunk.type === 'RUN_STARTED') {\n            // New run — reset both views.\n            rawJsonRef.current = ''\n            setPartial({} as Partial)\n            setFinal(null)\n          } else if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {\n            rawJsonRef.current += chunk.delta\n            const progressive = parsePartialJSON(rawJsonRef.current)\n            if (progressive && typeof progressive === 'object') {\n              setPartial(progressive as Partial)\n            }\n          } else if (\n            chunk.type === 'CUSTOM' &&\n            chunk.name === 'structured-output.complete'\n          ) {\n            const value = chunk.value as { object: unknown }\n            setFinal(value.object as Final)\n          }\n        }\n        optionsRef.current.onChunk?.(chunk)\n      },\n      onFinish: (message: UIMessage<TTools>) => {\n        optionsRef.current.onFinish?.(message)\n      },\n      onError: (error: Error) => {\n        optionsRef.current.onError?.(error)\n      },\n      tools: optionsRef.current.tools,\n      onCustomEvent: (eventType, data, context) =>\n        optionsRef.current.onCustomEvent?.(eventType, data, context),\n      streamProcessor: options.streamProcessor,\n      onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {\n        setMessages(newMessages)\n      },\n      onLoadingChange: (newIsLoading: boolean) => {\n        setIsLoading(newIsLoading)\n      },\n      onErrorChange: (newError: Error | undefined) => {\n        setError(newError)\n      },\n      onStatusChange: (status: ChatClientState) => {\n        setStatus(status)\n      },\n      onSubscriptionChange: (nextIsSubscribed: boolean) => {\n        setIsSubscribed(nextIsSubscribed)\n      },\n      onConnectionStatusChange: (nextStatus: ConnectionStatus) => {\n        setConnectionStatus(nextStatus)\n      },\n      onSessionGeneratingChange: (isGenerating: boolean) => {\n        setSessionGenerating(isGenerating)\n      },\n    })\n  }, [clientId])\n\n  // Sync body / forwardedProps changes to the client.\n  // This allows dynamic values (like model selection) to be updated\n  // without recreating the client. Both fields populate the same\n  // wire payload; `forwardedProps` is preferred and `body` is\n  // deprecated but still supported.\n  useEffect(() => {\n    client.updateOptions({\n      body: options.body,\n      forwardedProps: options.forwardedProps,\n    })\n  }, [client, options.body, options.forwardedProps])\n\n  // Sync initial messages on mount only\n  // Note: initialMessages are passed to ChatClient constructor, but we also\n  // set them here to ensure React state is in sync\n  useEffect(() => {\n    if (options.initialMessages && options.initialMessages.length > 0) {\n      // Only set if current messages are empty (initial state)\n      if (messages.length === 0) {\n        client.setMessagesManually(options.initialMessages)\n      }\n    }\n  }, []) // Only run on mount - initialMessages are handled by ChatClient constructor\n\n  // Keep connection lifecycle opt-in and explicit.\n  useEffect(() => {\n    if (options.live) {\n      client.subscribe()\n    } else {\n      client.unsubscribe()\n    }\n  }, [client, options.live])\n\n  // Cleanup on unmount: stop any in-flight requests\n  // Note: We only cleanup when client changes or component unmounts.\n  // DO NOT include isLoading in dependencies - that would cause the cleanup\n  // to run when isLoading changes, aborting continuation requests.\n  useEffect(() => {\n    return () => {\n      // live mode owns the connection lifecycle; non-live keeps request-only stop.\n      if (options.live) {\n        client.unsubscribe()\n      } else {\n        client.stop()\n      }\n    }\n  }, [client, options.live])\n\n  // All callback options are read through optionsRef at call time, so fresh\n  // closures from each render are picked up without recreating the client.\n\n  const sendMessage = useCallback(\n    async (content: string | MultimodalContent) => {\n      await client.sendMessage(content)\n    },\n    [client],\n  )\n\n  const append = useCallback(\n    async (message: ModelMessage | UIMessage) => {\n      await client.append(message)\n    },\n    [client],\n  )\n\n  const reload = useCallback(async () => {\n    await client.reload()\n  }, [client])\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const clear = useCallback(() => {\n    client.clear()\n  }, [client])\n\n  const setMessagesManually = useCallback(\n    (newMessages: Array<UIMessage<TTools>>) => {\n      client.setMessagesManually(newMessages)\n    },\n    [client],\n  )\n\n  const addToolResult = useCallback(\n    async (result: {\n      toolCallId: string\n      tool: string\n      output: any\n      state?: 'output-available' | 'output-error'\n      errorText?: string\n    }) => {\n      await client.addToolResult(result)\n    },\n    [client],\n  )\n\n  const addToolApprovalResponse = useCallback(\n    async (response: { id: string; approved: boolean }) => {\n      await client.addToolApprovalResponse(response)\n    },\n    [client],\n  )\n\n  // partial / final are runtime-tracked unconditionally; the conditional\n  // return type (UseChatReturn<TTools, TSchema>) hides them from callers that\n  // didn't supply `outputSchema`. The `as` cast is the seam between the\n  // unconditional runtime shape and the schema-discriminated public shape.\n  return {\n    messages,\n    sendMessage,\n    append,\n    reload,\n    stop,\n    isLoading,\n    error,\n    status,\n    isSubscribed,\n    connectionStatus,\n    sessionGenerating,\n    setMessages: setMessagesManually,\n    clear,\n    addToolResult,\n    addToolApprovalResponse,\n    partial,\n    final,\n  } as unknown as UseChatReturn<TTools, TSchema>\n}\n"],"names":["error","status"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-react",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "React hooks for TanStack AI",
   "author": "",
   "license": "MIT",
@@ -31,21 +31,22 @@
     "streaming"
   ],
   "dependencies": {
-    "@tanstack/ai-client": "0.9.1"
+    "@tanstack/ai-client": "0.10.0"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",
     "react": ">=18.0.0",
-    "@tanstack/ai": "^0.16.0"
+    "@tanstack/ai": "^0.18.0"
   },
   "devDependencies": {
+    "@standard-schema/spec": "^1.1.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.7",
     "@vitest/coverage-v8": "4.0.14",
     "jsdom": "^27.2.0",
     "react": "^19.2.3",
     "vite": "^7.2.7",
-    "@tanstack/ai": "0.16.0"
+    "@tanstack/ai": "0.18.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/src/index.ts

@@ -1,6 +1,7 @@
 export { useChat } from './use-chat'
 export { useRealtimeChat } from './use-realtime-chat'
 export type {
+  DeepPartial,
   UseChatOptions,
   UseChatReturn,
   UIMessage,

package/src/types.ts

@@ -1,4 +1,9 @@
-import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  AnyClientTool,
+  InferSchemaType,
+  ModelMessage,
+  SchemaInput,
+} from '@tanstack/ai'
 import type {
   ChatClientOptions,
   ChatClientState,
@@ -11,6 +16,18 @@ import type {
 // Re-export types from ai-client
 export type { ChatRequestBody, MultimodalContent, UIMessage }
 
+/**
+ * Recursive partial — every property and every nested array element is optional.
+ * Used to type the in-flight `partial` value the hook exposes while a structured
+ * output stream is still arriving (the JSON has shape but is incomplete).
+ */
+export type DeepPartial<T> =
+  T extends ReadonlyArray<infer U>
+    ? Array<DeepPartial<U>>
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T
+
 /**
  * Options for the useChat hook.
  *
@@ -24,30 +41,71 @@ export type { ChatRequestBody, MultimodalContent, UIMessage }
  * All other callbacks (onResponse, onChunk, onFinish, onError) are
  * passed through to the underlying ChatClient and can be used for side effects.
  *
+ * When `outputSchema` is supplied, the hook returns a typed `partial` (live
+ * progressive object, updated from `TEXT_MESSAGE_CONTENT` deltas via
+ * `parsePartialJSON`) and `final` (validated terminal payload from the
+ * `structured-output.complete` event). The schema is used purely for type
+ * inference on the client — server-side validation still runs against the
+ * schema you pass to `chat({ outputSchema })` on the server route.
+ *
  * Note: Connection and body changes will recreate the ChatClient instance.
  * To update these options, remount the component or use a key prop.
  */
-export type UseChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> =
-  Omit<
-    ChatClientOptions<TTools>,
-    | 'onMessagesChange'
-    | 'onLoadingChange'
-    | 'onErrorChange'
-    | 'onStatusChange'
-    | 'onSubscriptionChange'
-    | 'onConnectionStatusChange'
-    | 'onSessionGeneratingChange'
-  > & {
-    /**
-     * Opt into mount-time live subscription behavior.
-     * When enabled, the hook subscribes on mount and unsubscribes on unmount.
-     */
-    live?: boolean
-  }
-
-export interface UseChatReturn<
+export type UseChatOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+> = Omit<
+  ChatClientOptions<TTools>,
+  | 'onMessagesChange'
+  | 'onLoadingChange'
+  | 'onErrorChange'
+  | 'onStatusChange'
+  | 'onSubscriptionChange'
+  | 'onConnectionStatusChange'
+  | 'onSessionGeneratingChange'
+> & {
+  /**
+   * Opt into mount-time live subscription behavior.
+   * When enabled, the hook subscribes on mount and unsubscribes on unmount.
+   */
+  live?: boolean
+  /**
+   * Standard-schema-compatible schema (Zod, Valibot, ArkType, or a plain JSON
+   * Schema). Used to infer the shape of `partial` and `final` in the return.
+   * The schema is **not** sent to the server — server-side validation runs
+   * against the schema passed to `chat({ outputSchema })` on the server route.
+   */
+  outputSchema?: TSchema
+}
+
+/**
+ * Discriminated return shape: when `outputSchema` is supplied, the hook adds
+ * typed `partial` / `final` fields; when it is omitted (default), the return
+ * is unchanged.
+ */
+export type UseChatReturn<
   TTools extends ReadonlyArray<AnyClientTool> = any,
-> {
+  TSchema extends SchemaInput | undefined = undefined,
+> = BaseUseChatReturn<TTools> &
+  (TSchema extends SchemaInput
+    ? {
+        /**
+         * Live, progressively-parsed structured output. Updated from
+         * `TEXT_MESSAGE_CONTENT` deltas via `parsePartialJSON` while the stream
+         * is still arriving, and snapped to the validated payload when
+         * `structured-output.complete` fires. Resets on every new run
+         * (`sendMessage` / `reload`).
+         */
+        partial: DeepPartial<InferSchemaType<TSchema>>
+        /**
+         * Final, schema-validated structured output. `null` until the terminal
+         * `structured-output.complete` event arrives. Resets on every new run.
+         */
+        final: InferSchemaType<TSchema> | null
+      }
+    : Record<never, never>)
+
+interface BaseUseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
   /**
    * Current messages in the conversation
    */

package/src/use-chat.ts

@@ -1,18 +1,27 @@
 import { ChatClient } from '@tanstack/ai-client'
+import { parsePartialJSON } from '@tanstack/ai'
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
-import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  AnyClientTool,
+  InferSchemaType,
+  ModelMessage,
+  SchemaInput,
+  StreamChunk,
+} from '@tanstack/ai'
 import type { ChatClientState, ConnectionStatus } from '@tanstack/ai-client'
 
 import type {
+  DeepPartial,
   MultimodalContent,
   UIMessage,
   UseChatOptions,
   UseChatReturn,
 } from './types'
 
-export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
-  options: UseChatOptions<TTools>,
-): UseChatReturn<TTools> {
+export function useChat<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+>(options: UseChatOptions<TTools, TSchema>): UseChatReturn<TTools, TSchema> {
   const hookId = useId()
   const clientId = options.id || hookId
 
@@ -27,6 +36,19 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
     useState<ConnectionStatus>('disconnected')
   const [sessionGenerating, setSessionGenerating] = useState(false)
 
+  // Structured-output state. Only meaningful when `outputSchema` is supplied;
+  // when it isn't, these stay at their initial values and are hidden from the
+  // return type by the conditional in UseChatReturn. Runtime always tracks
+  // them — the type system gates visibility, not the runtime.
+  type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
+  type Final = InferSchemaType<NonNullable<TSchema>>
+  const [partial, setPartial] = useState<Partial>({} as Partial)
+  const [final, setFinal] = useState<Final | null>(null)
+  // Raw JSON accumulator for parsePartialJSON. Ref instead of state — partial
+  // JSON parsing happens synchronously inside the chunk handler; we don't want
+  // a re-render per delta solely to track the buffer.
+  const rawJsonRef = useRef('')
+
   // Track current messages in a ref to preserve them when client is recreated
   const messagesRef = useRef<Array<UIMessage<TTools>>>(
     options.initialMessages || [],
@@ -38,7 +60,7 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
   messagesRef.current = messages
 
   // Track current options in a ref to avoid recreating client when options change
-  const optionsRef = useRef<UseChatOptions<TTools>>(options)
+  const optionsRef = useRef<UseChatOptions<TTools, TSchema>>(options)
   optionsRef.current = options
 
   // Create ChatClient instance with callbacks to sync state
@@ -58,11 +80,37 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
       id: clientId,
       initialMessages: messagesToUse,
       body: optionsRef.current.body,
+      forwardedProps: optionsRef.current.forwardedProps,
       // Wrap every callback so the latest options are read at call time.
       // Capturing the function reference directly would freeze it to whatever
       // the parent passed on the first render.
       onResponse: (response) => optionsRef.current.onResponse?.(response),
-      onChunk: (chunk) => optionsRef.current.onChunk?.(chunk),
+      onChunk: (chunk: StreamChunk) => {
+        // Internal structured-output tracking — runs before the user callback
+        // so user code observes the same state the hook does. Only active when
+        // a schema is supplied; otherwise the branches are no-ops.
+        if (optionsRef.current.outputSchema !== undefined) {
+          if (chunk.type === 'RUN_STARTED') {
+            // New run — reset both views.
+            rawJsonRef.current = ''
+            setPartial({} as Partial)
+            setFinal(null)
+          } else if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {
+            rawJsonRef.current += chunk.delta
+            const progressive = parsePartialJSON(rawJsonRef.current)
+            if (progressive && typeof progressive === 'object') {
+              setPartial(progressive as Partial)
+            }
+          } else if (
+            chunk.type === 'CUSTOM' &&
+            chunk.name === 'structured-output.complete'
+          ) {
+            const value = chunk.value as { object: unknown }
+            setFinal(value.object as Final)
+          }
+        }
+        optionsRef.current.onChunk?.(chunk)
+      },
       onFinish: (message: UIMessage<TTools>) => {
         optionsRef.current.onFinish?.(message)
       },
@@ -97,11 +145,17 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
     })
   }, [clientId])
 
-  // Sync body changes to the client
-  // This allows dynamic body values (like model selection) to be updated without recreating the client
+  // Sync body / forwardedProps changes to the client.
+  // This allows dynamic values (like model selection) to be updated
+  // without recreating the client. Both fields populate the same
+  // wire payload; `forwardedProps` is preferred and `body` is
+  // deprecated but still supported.
   useEffect(() => {
-    client.updateOptions({ body: options.body })
-  }, [client, options.body])
+    client.updateOptions({
+      body: options.body,
+      forwardedProps: options.forwardedProps,
+    })
+  }, [client, options.body, options.forwardedProps])
 
   // Sync initial messages on mount only
   // Note: initialMessages are passed to ChatClient constructor, but we also
@@ -195,6 +249,10 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
     [client],
   )
 
+  // partial / final are runtime-tracked unconditionally; the conditional
+  // return type (UseChatReturn<TTools, TSchema>) hides them from callers that
+  // didn't supply `outputSchema`. The `as` cast is the seam between the
+  // unconditional runtime shape and the schema-discriminated public shape.
   return {
     messages,
     sendMessage,
@@ -211,5 +269,7 @@ export function useChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
     clear,
     addToolResult,
     addToolApprovalResponse,
-  }
+    partial,
+    final,
+  } as unknown as UseChatReturn<TTools, TSchema>
 }