@tanstack/ai-react 0.15.14 → 0.16.0

package/dist/esm/index.d.ts

@@ -0,0 +1,23 @@
+export { useChat } from './use-chat.js';
+export { useRealtimeChat } from './use-realtime-chat.js';
+export { useMcpAppBridge } from './use-mcp-app-bridge.js';
+export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.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';
+export { useGenerateImage } from './use-generate-image.js';
+export type { UseGenerateImageOptions, UseGenerateImageReturn, } from './use-generate-image.js';
+export { useGenerateAudio } from './use-generate-audio.js';
+export type { UseGenerateAudioOptions, UseGenerateAudioReturn, } from './use-generate-audio.js';
+export { useGenerateSpeech } from './use-generate-speech.js';
+export type { UseGenerateSpeechOptions, UseGenerateSpeechReturn, } from './use-generate-speech.js';
+export { useTranscription } from './use-transcription.js';
+export type { UseTranscriptionOptions, UseTranscriptionReturn, } from './use-transcription.js';
+export { useSummarize } from './use-summarize.js';
+export type { UseSummarizeOptions, UseSummarizeReturn } from './use-summarize.js';
+export { useGenerateVideo } from './use-generate-video.js';
+export type { UseGenerateVideoOptions, UseGenerateVideoReturn, } from './use-generate-video.js';
+export { useAudioRecorder } from './use-audio-recorder.js';
+export type { UseAudioRecorderOptions, UseAudioRecorderReturn, } from './use-audio-recorder.js';
+export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, createChatClientOptions, createMcpAppBridge, type McpAppBridge, type CreateMcpAppBridgeOptions, type ChatFetcher, type ChatFetcherInput, type ChatFetcherOptions, type ConnectionAdapter, type ConnectConnectionAdapter, type SubscribeConnectionAdapter, type RunAgentInputContext, type FetchConnectionOptions, type XhrConnectionOptions, type InferChatMessages, type GenerationClientState, type ImageGenerateInput, type AudioGenerateInput, type SpeechGenerateInput, type TranscriptionGenerateInput, type SummarizeGenerateInput, type VideoGenerateInput, type VideoGenerateResult, type VideoStatusInfo, } from '@tanstack/ai-client';

package/dist/esm/index.js

@@ -0,0 +1,34 @@
+import { useChat } from "./use-chat.js";
+import { useRealtimeChat } from "./use-realtime-chat.js";
+import { useMcpAppBridge } from "./use-mcp-app-bridge.js";
+import { useGeneration } from "./use-generation.js";
+import { useGenerateImage } from "./use-generate-image.js";
+import { useGenerateAudio } from "./use-generate-audio.js";
+import { useGenerateSpeech } from "./use-generate-speech.js";
+import { useTranscription } from "./use-transcription.js";
+import { useSummarize } from "./use-summarize.js";
+import { useGenerateVideo } from "./use-generate-video.js";
+import { useAudioRecorder } from "./use-audio-recorder.js";
+import { createChatClientOptions, createMcpAppBridge, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "@tanstack/ai-client";
+export {
+  createChatClientOptions,
+  createMcpAppBridge,
+  fetchHttpStream,
+  fetchServerSentEvents,
+  rpcStream,
+  stream,
+  useAudioRecorder,
+  useChat,
+  useGenerateAudio,
+  useGenerateImage,
+  useGenerateSpeech,
+  useGenerateVideo,
+  useGeneration,
+  useMcpAppBridge,
+  useRealtimeChat,
+  useSummarize,
+  useTranscription,
+  xhrHttpStream,
+  xhrServerSentEvents
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/esm/mcp-apps.d.ts

@@ -0,0 +1,20 @@
+import { UIResourcePart } from '@tanstack/ai';
+import { McpAppBridge } from '@tanstack/ai-client';
+import { JSX } from 'react';
+export interface MCPAppResourceProps {
+    /** The ui-resource part from a UIMessage assistant part. */
+    part: UIResourcePart;
+    /**
+     * Framework-agnostic bridge for tool calls, prompt sending, and link opening.
+     * Omit it to render the widget in display-only mode — iframe interactions
+     * that would trigger tool calls or prompts are ignored.
+     */
+    bridge?: McpAppBridge;
+    /** Sandbox iframe configuration — must include the proxy page URL. */
+    sandbox: {
+        url: URL;
+    };
+    /** Optional structured arguments forwarded to the guest UI once it's ready. */
+    toolInput?: Record<string, unknown>;
+}
+export declare function MCPAppResource(props: MCPAppResourceProps): JSX.Element;

package/dist/esm/mcp-apps.js

@@ -0,0 +1,52 @@
+import { jsx } from "react/jsx-runtime";
+import { AppRenderer } from "@mcp-ui/client";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resultToText(result) {
+  if (typeof result === "string") return result;
+  const stringify = JSON.stringify;
+  return stringify(result) ?? "null";
+}
+function MCPAppResource(props) {
+  const { bridge } = props;
+  return /* @__PURE__ */ jsx(
+    AppRenderer,
+    {
+      toolName: props.part.toolName,
+      sandbox: props.sandbox,
+      html: props.part.resource.text,
+      toolResourceUri: props.part.resource.uri,
+      toolInput: props.toolInput,
+      onCallTool: bridge ? async ({ name, arguments: args }) => {
+        const result = await bridge.callTool({
+          serverId: props.part.serverId,
+          toolName: name,
+          args
+        });
+        const structuredContent = isRecord(result) ? result : void 0;
+        return {
+          content: [
+            {
+              type: "text",
+              text: resultToText(result)
+            }
+          ],
+          structuredContent
+        };
+      } : void 0,
+      onMessage: bridge ? async ({ content }) => {
+        const text = content.filter(
+          (c) => c.type === "text"
+        ).map((c) => c.text).join("");
+        if (text) await bridge.sendPrompt(text);
+        return {};
+      } : void 0,
+      onOpenLink: bridge ? ({ url }) => Promise.resolve(bridge.openLink(url)) : void 0
+    }
+  );
+}
+export {
+  MCPAppResource
+};
+//# sourceMappingURL=mcp-apps.js.map

package/dist/esm/mcp-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-apps.js","sources":["../../src/mcp-apps.tsx"],"sourcesContent":["import { AppRenderer } from '@mcp-ui/client'\nimport type { UIResourcePart } from '@tanstack/ai'\nimport type { McpAppBridge } from '@tanstack/ai-client'\nimport type { JSX } from 'react'\n\nexport interface MCPAppResourceProps {\n  /** The ui-resource part from a UIMessage assistant part. */\n  part: UIResourcePart\n  /**\n   * Framework-agnostic bridge for tool calls, prompt sending, and link opening.\n   * Omit it to render the widget in display-only mode — iframe interactions\n   * that would trigger tool calls or prompts are ignored.\n   */\n  bridge?: McpAppBridge\n  /** Sandbox iframe configuration — must include the proxy page URL. */\n  sandbox: { url: URL }\n  /** Optional structured arguments forwarded to the guest UI once it's ready. */\n  toolInput?: Record<string, unknown>\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Coalesce an arbitrary bridge result into the `string` required by the\n * `CallToolResult` text content block. `JSON.stringify` is typed to return\n * `string` but actually returns `undefined` for inputs like `undefined` or a\n * function, so we narrow explicitly to avoid `text: undefined`.\n */\nfunction resultToText(result: unknown): string {\n  if (typeof result === 'string') return result\n  // `JSON.stringify`'s lib signature claims `string`, but it returns\n  // `undefined` for `undefined`/function inputs; type the call honestly.\n  const stringify: (value: unknown) => string | undefined = JSON.stringify\n  return stringify(result) ?? 'null'\n}\n\nexport function MCPAppResource(props: MCPAppResourceProps): JSX.Element {\n  const { bridge } = props\n  return (\n    <AppRenderer\n      toolName={props.part.toolName}\n      sandbox={props.sandbox}\n      html={props.part.resource.text}\n      toolResourceUri={props.part.resource.uri}\n      toolInput={props.toolInput}\n      onCallTool={\n        bridge\n          ? async ({ name, arguments: args }) => {\n              const result = await bridge.callTool({\n                serverId: props.part.serverId,\n                toolName: name,\n                args,\n              })\n              const structuredContent = isRecord(result) ? result : undefined\n              return {\n                content: [\n                  {\n                    type: 'text' as const,\n                    text: resultToText(result),\n                  },\n                ],\n                structuredContent,\n              }\n            }\n          : undefined\n      }\n      onMessage={\n        bridge\n          ? async ({ content }) => {\n              const text = content\n                .filter(\n                  (c): c is { type: 'text'; text: string } => c.type === 'text',\n                )\n                .map((c) => c.text)\n                .join('')\n              if (text) await bridge.sendPrompt(text)\n              return {}\n            }\n          : undefined\n      }\n      onOpenLink={\n        bridge ? ({ url }) => Promise.resolve(bridge.openLink(url)) : undefined\n      }\n    />\n  )\n}\n"],"names":[],"mappings":";;AAoBA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAQA,SAAS,aAAa,QAAyB;AAC7C,MAAI,OAAO,WAAW,SAAU,QAAO;AAGvC,QAAM,YAAoD,KAAK;AAC/D,SAAO,UAAU,MAAM,KAAK;AAC9B;AAEO,SAAS,eAAe,OAAyC;AACtE,QAAM,EAAE,WAAW;AACnB,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,UAAU,MAAM,KAAK;AAAA,MACrB,SAAS,MAAM;AAAA,MACf,MAAM,MAAM,KAAK,SAAS;AAAA,MAC1B,iBAAiB,MAAM,KAAK,SAAS;AAAA,MACrC,WAAW,MAAM;AAAA,MACjB,YACE,SACI,OAAO,EAAE,MAAM,WAAW,WAAW;AACnC,cAAM,SAAS,MAAM,OAAO,SAAS;AAAA,UACnC,UAAU,MAAM,KAAK;AAAA,UACrB,UAAU;AAAA,UACV;AAAA,QAAA,CACD;AACD,cAAM,oBAAoB,SAAS,MAAM,IAAI,SAAS;AACtD,eAAO;AAAA,UACL,SAAS;AAAA,YACP;AAAA,cACE,MAAM;AAAA,cACN,MAAM,aAAa,MAAM;AAAA,YAAA;AAAA,UAC3B;AAAA,UAEF;AAAA,QAAA;AAAA,MAEJ,IACA;AAAA,MAEN,WACE,SACI,OAAO,EAAE,cAAc;AACrB,cAAM,OAAO,QACV;AAAA,UACC,CAAC,MAA2C,EAAE,SAAS;AAAA,QAAA,EAExD,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,EAAE;AACV,YAAI,KAAM,OAAM,OAAO,WAAW,IAAI;AACtC,eAAO,CAAA;AAAA,MACT,IACA;AAAA,MAEN,YACE,SAAS,CAAC,EAAE,UAAU,QAAQ,QAAQ,OAAO,SAAS,GAAG,CAAC,IAAI;AAAA,IAAA;AAAA,EAAA;AAItE;"}

package/dist/esm/realtime-types.d.ts

@@ -0,0 +1,109 @@
+import { AnyClientTool, RealtimeMessage, RealtimeMode, RealtimeStatus, RealtimeToken } from '@tanstack/ai';
+import { RealtimeAdapter } from '@tanstack/ai-client';
+/**
+ * Options for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatOptions {
+    /**
+     * Function to fetch a realtime token from the server.
+     * Called on connect and when token needs refresh.
+     */
+    getToken: () => Promise<RealtimeToken>;
+    /**
+     * The realtime adapter to use (e.g., openaiRealtime())
+     */
+    adapter: RealtimeAdapter;
+    /**
+     * Client-side tools with execution logic
+     */
+    tools?: ReadonlyArray<AnyClientTool>;
+    /**
+     * Auto-play assistant audio (default: true)
+     */
+    autoPlayback?: boolean;
+    /**
+     * Request microphone access on connect (default: true)
+     */
+    autoCapture?: boolean;
+    /**
+     * System instructions for the assistant
+     */
+    instructions?: string;
+    /**
+     * Voice to use for audio output
+     */
+    voice?: string;
+    /**
+     * Voice activity detection mode (default: 'server')
+     */
+    vadMode?: 'server' | 'semantic' | 'manual';
+    /**
+     * Output modalities for responses (e.g., ['audio', 'text'])
+     */
+    outputModalities?: Array<'audio' | 'text'>;
+    /**
+     * Temperature for generation (provider-specific range)
+     */
+    temperature?: number;
+    /**
+     * Maximum number of tokens in a response
+     */
+    maxOutputTokens?: number | 'inf';
+    /**
+     * Eagerness level for semantic VAD ('low', 'medium', 'high')
+     */
+    semanticEagerness?: 'low' | 'medium' | 'high';
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (error: Error) => void;
+    onMessage?: (message: RealtimeMessage) => void;
+    onModeChange?: (mode: RealtimeMode) => void;
+    onInterrupted?: () => void;
+}
+/**
+ * Return type for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatReturn {
+    /** Current connection status */
+    status: RealtimeStatus;
+    /** Current error, if any */
+    error: Error | null;
+    /** Connect to the realtime session */
+    connect: () => Promise<void>;
+    /** Disconnect from the realtime session */
+    disconnect: () => Promise<void>;
+    /** Current mode (idle, listening, thinking, speaking) */
+    mode: RealtimeMode;
+    /** Conversation messages */
+    messages: Array<RealtimeMessage>;
+    /** User transcript while speaking (before finalized) */
+    pendingUserTranscript: string | null;
+    /** Assistant transcript while speaking (before finalized) */
+    pendingAssistantTranscript: string | null;
+    /** Start listening for voice input (manual VAD mode) */
+    startListening: () => void;
+    /** Stop listening for voice input (manual VAD mode) */
+    stopListening: () => void;
+    /** Interrupt the current assistant response */
+    interrupt: () => void;
+    /** Send a text message instead of voice */
+    sendText: (text: string) => void;
+    /** Send an image to the conversation */
+    sendImage: (imageData: string, mimeType: string) => void;
+    /** Current input (microphone) volume level */
+    inputLevel: number;
+    /** Current output (speaker) volume level */
+    outputLevel: number;
+    /** Get frequency data for input audio visualization */
+    getInputFrequencyData: () => Uint8Array;
+    /** Get frequency data for output audio visualization */
+    getOutputFrequencyData: () => Uint8Array;
+    /** Get time domain data for input waveform */
+    getInputTimeDomainData: () => Uint8Array;
+    /** Get time domain data for output waveform */
+    getOutputTimeDomainData: () => Uint8Array;
+    /** Current VAD mode */
+    vadMode: 'server' | 'semantic' | 'manual';
+    /** Change VAD mode at runtime */
+    setVADMode: (mode: 'server' | 'semantic' | 'manual') => void;
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,150 @@
+import { AnyClientTool, InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai/client';
+import { AIDevtoolsDisplayOptions, ChatClientOptions, ChatClientState, ChatRequestBody, ClientContextOptionFromTools, ConnectionStatus, DistributedOmit, InferredClientContext, 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.
+ *
+ * Pass either `connection` or `fetcher` — the XOR is enforced at the type
+ * level via `ChatTransport`.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by React state:
+ * - `onMessagesChange` - Managed by React state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by React state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by React state (exposed as `error`)
+ * - `onStatusChange` - Managed by React state (exposed as `status`)
+ *
+ * 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, TSchema extends SchemaInput | undefined = undefined, TContext = InferredClientContext<TTools>> = DistributedOmit<ChatClientOptions<TTools, TContext>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange' | 'onStatusChange' | 'onSubscriptionChange' | 'onConnectionStatusChange' | 'onSessionGeneratingChange' | 'context' | 'devtools'> & {
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * 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;
+} & ClientContextOptionFromTools<TTools, TContext>;
+/**
+ * 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 ? InferSchemaType<TSchema> : unknown> & (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, TData = unknown> {
+    /**
+     * Current messages in the conversation. When `outputSchema` is supplied,
+     * `messages[i].parts.find(p => p.type === 'structured-output')` is typed
+     * with the schema's inferred shape — `data: T`, `partial: DeepPartial<T>`.
+     */
+    messages: Array<UIMessage<TTools, TData>>;
+    /**
+     * Send a message and get a response.
+     * Can be a simple string or multimodal content with images, audio, etc.
+     */
+    sendMessage: (content: string | MultimodalContent) => Promise<void>;
+    /**
+     * Append a message to the conversation
+     */
+    append: (message: ModelMessage | UIMessage<TTools, TData>) => Promise<void>;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult: (result: {
+        toolCallId: string;
+        tool: string;
+        output: any;
+        state?: 'output-available' | 'output-error';
+        errorText?: string;
+    }) => Promise<void>;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse: (response: {
+        id: string;
+        approved: boolean;
+    }) => Promise<void>;
+    /**
+     * Reload the last assistant message
+     */
+    reload: () => Promise<void>;
+    /**
+     * Stop the current response generation
+     */
+    stop: () => void;
+    /**
+     * Whether a response is currently being generated
+     */
+    isLoading: boolean;
+    /**
+     * Current error, if any
+     */
+    error: Error | undefined;
+    /**
+     * Current status of the chat client
+     */
+    status: ChatClientState;
+    /**
+     * Whether the subscription loop is currently active
+     */
+    isSubscribed: boolean;
+    /**
+     * Current connection lifecycle status
+     */
+    connectionStatus: ConnectionStatus;
+    /**
+     * Whether the shared session is actively generating.
+     * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+     * Unlike `isLoading` (request-local), this reflects shared generation
+     * activity visible to all subscribers (e.g. across tabs/devices).
+     */
+    sessionGenerating: boolean;
+    /**
+     * Set messages manually
+     */
+    setMessages: (messages: Array<UIMessage<TTools, TData>>) => void;
+    /**
+     * Clear all messages
+     */
+    clear: () => void;
+}

package/dist/esm/use-audio-recorder.d.ts

@@ -0,0 +1,43 @@
+import { AudioRecorderOptions, AudioRecording, InferAudioRecordingOutput } from '@tanstack/ai-client';
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+    /**
+     * Optional transform applied to the recording when `stop()` resolves. Its
+     * (awaited) return value becomes `recording` and the resolved value of
+     * `stop()`. Return nothing to keep the raw `AudioRecording`.
+     */
+    onComplete?: TOnComplete;
+};
+export interface UseAudioRecorderReturn<TOutput> {
+    /** Latest recording (transformed if `onComplete` provided), or null. */
+    recording: TOutput | null;
+    /** True while actively capturing audio. */
+    isRecording: boolean;
+    /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+    isSupported: boolean;
+    /** Acquire the mic and begin recording. */
+    start: () => Promise<void>;
+    /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+    stop: () => Promise<TOutput>;
+    /** Discard the in-progress recording and release the mic. */
+    cancel: () => void;
+}
+/**
+ * React hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+export declare function useAudioRecorder<TOnComplete extends (recording: AudioRecording) => unknown>(options: UseAudioRecorderOptions<TOnComplete>): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>;
+export declare function useAudioRecorder(options?: UseAudioRecorderOptions<undefined>): UseAudioRecorderReturn<AudioRecording>;

package/dist/esm/use-audio-recorder.js

@@ -0,0 +1,49 @@
+import { useState, useRef, useMemo, useEffect, useCallback } from "react";
+import { AudioRecorder } from "@tanstack/ai-client";
+function useAudioRecorder(options = {}) {
+  const [isRecording, setIsRecording] = useState(false);
+  const [recording, setRecording] = useState(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const recorder = useMemo(
+    () => new AudioRecorder({
+      ...options.audio !== void 0 && { audio: options.audio },
+      ...options.mimeType !== void 0 && { mimeType: options.mimeType },
+      onError: (err) => optionsRef.current.onError?.(err)
+    }),
+    // Recorder config (audio/mimeType) is captured once at mount, matching the
+    // other hooks' create-once pattern.
+    []
+  );
+  useEffect(() => {
+    const unsubscribe = recorder.subscribe((state) => {
+      setIsRecording(state === "recording");
+    });
+    return () => {
+      unsubscribe();
+      recorder.cancel();
+    };
+  }, [recorder]);
+  const start = useCallback(() => recorder.start(), [recorder]);
+  const stop = useCallback(async () => {
+    const recording2 = await recorder.stop();
+    const transformed = await optionsRef.current.onComplete?.(recording2);
+    const output = transformed === void 0 ? recording2 : transformed;
+    setRecording(() => output);
+    return output;
+  }, [recorder]);
+  const cancel = useCallback(() => recorder.cancel(), [recorder]);
+  return {
+    recording,
+    isRecording,
+    // recording is client-only; if SSR'd, gate UI on a mounted flag.
+    isSupported: AudioRecorder.isSupported(),
+    start,
+    stop,
+    cancel
+  };
+}
+export {
+  useAudioRecorder
+};
+//# sourceMappingURL=use-audio-recorder.js.map

package/dist/esm/use-audio-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-audio-recorder.js","sources":["../../src/use-audio-recorder.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react'\nimport { AudioRecorder } from '@tanstack/ai-client'\nimport type {\n  AudioRecorderOptions,\n  AudioRecording,\n  InferAudioRecordingOutput,\n} from '@tanstack/ai-client'\n\nexport type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {\n  /**\n   * Optional transform applied to the recording when `stop()` resolves. Its\n   * (awaited) return value becomes `recording` and the resolved value of\n   * `stop()`. Return nothing to keep the raw `AudioRecording`.\n   */\n  onComplete?: TOnComplete\n}\n\nexport interface UseAudioRecorderReturn<TOutput> {\n  /** Latest recording (transformed if `onComplete` provided), or null. */\n  recording: TOutput | null\n  /** True while actively capturing audio. */\n  isRecording: boolean\n  /** Whether the browser supports recording (getUserMedia + MediaRecorder). */\n  isSupported: boolean\n  /** Acquire the mic and begin recording. */\n  start: () => Promise<void>\n  /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */\n  stop: () => Promise<TOutput>\n  /** Discard the in-progress recording and release the mic. */\n  cancel: () => void\n}\n\n/**\n * React hook for recording an audio message. The resolved\n * {@link AudioRecording} carries `.part` (an audio content part for\n * `useChat.sendMessage`) and `.base64` (for the generation hooks).\n *\n * Errors are delivered via `onError`. `start()` and `stop()` also reject on\n * failure (and `stop()` rejects with `Recording cancelled` if the component\n * unmounts while a stop is in flight) — handle one channel, not both.\n *\n * @example\n * ```tsx\n * const { isRecording, start, stop, recording } = useAudioRecorder()\n * const { sendMessage } = useChat({ connection })\n * // ...\n * const rec = await stop()\n * sendMessage({ content: [rec.part] })\n * ```\n */\nexport function useAudioRecorder<\n  TOnComplete extends (recording: AudioRecording) => unknown,\n>(\n  options: UseAudioRecorderOptions<TOnComplete>,\n): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>\nexport function useAudioRecorder(\n  options?: UseAudioRecorderOptions<undefined>,\n): UseAudioRecorderReturn<AudioRecording>\nexport function useAudioRecorder(\n  options: UseAudioRecorderOptions<(recording: AudioRecording) => unknown> = {},\n): UseAudioRecorderReturn<unknown> {\n  const [isRecording, setIsRecording] = useState(false)\n  const [recording, setRecording] = useState<unknown>(null)\n  // Read the freshest callbacks at fire time without recreating the recorder.\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n\n  const recorder = useMemo(\n    () =>\n      new AudioRecorder({\n        ...(options.audio !== undefined && { audio: options.audio }),\n        ...(options.mimeType !== undefined && { mimeType: options.mimeType }),\n        onError: (err) => optionsRef.current.onError?.(err),\n      }),\n    // Recorder config (audio/mimeType) is captured once at mount, matching the\n    // other hooks' create-once pattern.\n    [],\n  )\n\n  useEffect(() => {\n    const unsubscribe = recorder.subscribe((state) => {\n      setIsRecording(state === 'recording')\n    })\n    return () => {\n      unsubscribe()\n      recorder.cancel()\n    }\n  }, [recorder])\n\n  const start = useCallback(() => recorder.start(), [recorder])\n  const stop = useCallback(async () => {\n    const recording = await recorder.stop()\n    const transformed = await optionsRef.current.onComplete?.(recording)\n    // Only `undefined` (returning nothing) falls back to the raw recording, so\n    // a transform that returns null is preserved — matching the inferred type,\n    // which excludes only undefined/void/null from the transform's return.\n    const output = transformed === undefined ? recording : transformed\n    setRecording(() => output)\n    return output\n  }, [recorder])\n  const cancel = useCallback(() => recorder.cancel(), [recorder])\n\n  return {\n    recording,\n    isRecording,\n    // recording is client-only; if SSR'd, gate UI on a mounted flag.\n    isSupported: AudioRecorder.isSupported(),\n    start,\n    stop,\n    cancel,\n  }\n}\n"],"names":["recording"],"mappings":";;AA0DO,SAAS,iBACd,UAA2E,IAC1C;AACjC,QAAM,CAAC,aAAa,cAAc,IAAI,SAAS,KAAK;AACpD,QAAM,CAAC,WAAW,YAAY,IAAI,SAAkB,IAAI;AAExD,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,WAAW;AAAA,IACf,MACE,IAAI,cAAc;AAAA,MAChB,GAAI,QAAQ,UAAU,UAAa,EAAE,OAAO,QAAQ,MAAA;AAAA,MACpD,GAAI,QAAQ,aAAa,UAAa,EAAE,UAAU,QAAQ,SAAA;AAAA,MAC1D,SAAS,CAAC,QAAQ,WAAW,QAAQ,UAAU,GAAG;AAAA,IAAA,CACnD;AAAA;AAAA;AAAA,IAGH,CAAA;AAAA,EAAC;AAGH,YAAU,MAAM;AACd,UAAM,cAAc,SAAS,UAAU,CAAC,UAAU;AAChD,qBAAe,UAAU,WAAW;AAAA,IACtC,CAAC;AACD,WAAO,MAAM;AACX,kBAAA;AACA,eAAS,OAAA;AAAA,IACX;AAAA,EACF,GAAG,CAAC,QAAQ,CAAC;AAEb,QAAM,QAAQ,YAAY,MAAM,SAAS,SAAS,CAAC,QAAQ,CAAC;AAC5D,QAAM,OAAO,YAAY,YAAY;AACnC,UAAMA,aAAY,MAAM,SAAS,KAAA;AACjC,UAAM,cAAc,MAAM,WAAW,QAAQ,aAAaA,UAAS;AAInE,UAAM,SAAS,gBAAgB,SAAYA,aAAY;AACvD,iBAAa,MAAM,MAAM;AACzB,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,CAAC;AACb,QAAM,SAAS,YAAY,MAAM,SAAS,UAAU,CAAC,QAAQ,CAAC;AAE9D,SAAO;AAAA,IACL;AAAA,IACA;AAAA;AAAA,IAEA,aAAa,cAAc,YAAA;AAAA,IAC3B;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

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

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