@tanstack/ai-react 0.18.1 → 0.19.0

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

@@ -1,188 +1,188 @@
-import { useState, useRef, useEffect, useCallback } from "react";
 import { RealtimeClient } from "@tanstack/ai-client";
-const emptyFrequencyData = new Uint8Array(128);
-const emptyTimeDomainData = new Uint8Array(128).fill(128);
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/use-realtime-chat.ts
+var emptyFrequencyData = /* @__PURE__ */ new Uint8Array(128);
+var emptyTimeDomainData = (/* @__PURE__ */ new Uint8Array(128)).fill(128);
+/**
+* React hook for realtime voice conversations.
+*
+* Provides a simple interface for voice-to-voice AI interactions
+* with support for multiple providers (OpenAI, ElevenLabs, etc.).
+*
+* @param options - Configuration options including adapter and callbacks
+* @returns Hook return value with state and control methods
+*
+* @example
+* ```typescript
+* import { useRealtimeChat } from '@tanstack/ai-react'
+* import { openaiRealtime } from '@tanstack/ai-openai'
+*
+* function VoiceChat() {
+*   const {
+*     status,
+*     mode,
+*     messages,
+*     connect,
+*     disconnect,
+*     inputLevel,
+*     outputLevel,
+*   } = useRealtimeChat({
+*     getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+*     adapter: openaiRealtime(),
+*   })
+*
+*   return (
+*     <div>
+*       <p>Status: {status}</p>
+*       <p>Mode: {mode}</p>
+*       <button onClick={status === 'idle' ? connect : disconnect}>
+*         {status === 'idle' ? 'Start' : 'Stop'}
+*       </button>
+*     </div>
+*   )
+* }
+* ```
+*/
 function useRealtimeChat(options) {
-  const [status, setStatus] = useState("idle");
-  const [mode, setMode] = useState("idle");
-  const [messages, setMessages] = useState([]);
-  const [pendingUserTranscript, setPendingUserTranscript] = useState(null);
-  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState(null);
-  const [error, setError] = useState(null);
-  const [inputLevel, setInputLevel] = useState(0);
-  const [outputLevel, setOutputLevel] = useState(0);
-  const clientRef = useRef(null);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const animationFrameRef = useRef(null);
-  if (!clientRef.current) {
-    const initial = optionsRef.current;
-    clientRef.current = new RealtimeClient({
-      getToken: initial.getToken,
-      adapter: initial.adapter,
-      ...initial.tools !== void 0 && { tools: initial.tools },
-      ...initial.instructions !== void 0 && {
-        instructions: initial.instructions
-      },
-      ...initial.voice !== void 0 && { voice: initial.voice },
-      ...initial.autoPlayback !== void 0 && {
-        autoPlayback: initial.autoPlayback
-      },
-      ...initial.autoCapture !== void 0 && {
-        autoCapture: initial.autoCapture
-      },
-      ...initial.vadMode !== void 0 && { vadMode: initial.vadMode },
-      ...initial.outputModalities !== void 0 && {
-        outputModalities: initial.outputModalities
-      },
-      ...initial.temperature !== void 0 && {
-        temperature: initial.temperature
-      },
-      ...initial.maxOutputTokens !== void 0 && {
-        maxOutputTokens: initial.maxOutputTokens
-      },
-      ...initial.semanticEagerness !== void 0 && {
-        semanticEagerness: initial.semanticEagerness
-      },
-      onStatusChange: (newStatus) => {
-        setStatus(newStatus);
-      },
-      onModeChange: (newMode) => {
-        setMode(newMode);
-        optionsRef.current.onModeChange?.(newMode);
-      },
-      onMessage: (message) => {
-        setMessages((prev) => [...prev, message]);
-        optionsRef.current.onMessage?.(message);
-      },
-      onUsage(usage) {
-        optionsRef.current.onUsage?.(usage);
-      },
-      onGoAway(timeLeft) {
-        optionsRef.current.onGoAway?.(timeLeft);
-      },
-      onError: (err) => {
-        setError(err);
-        optionsRef.current.onError?.(err);
-      },
-      onConnect: () => {
-        setError(null);
-        optionsRef.current.onConnect?.();
-      },
-      onDisconnect: () => {
-        optionsRef.current.onDisconnect?.();
-      },
-      onInterrupted: () => {
-        setPendingAssistantTranscript(null);
-        optionsRef.current.onInterrupted?.();
-      }
-    });
-    clientRef.current.onStateChange((state) => {
-      setPendingUserTranscript(state.pendingUserTranscript);
-      setPendingAssistantTranscript(state.pendingAssistantTranscript);
-    });
-  }
-  const client = clientRef.current;
-  useEffect(() => {
-    function updateLevels() {
-      if (clientRef.current?.audio) {
-        setInputLevel(clientRef.current.audio.inputLevel);
-        setOutputLevel(clientRef.current.audio.outputLevel);
-      }
-      animationFrameRef.current = requestAnimationFrame(updateLevels);
-    }
-    if (status === "connected") {
-      updateLevels();
-    }
-    return () => {
-      if (animationFrameRef.current) {
-        cancelAnimationFrame(animationFrameRef.current);
-        animationFrameRef.current = null;
-      }
-    };
-  }, [status]);
-  useEffect(() => {
-    return () => {
-      clientRef.current?.destroy();
-    };
-  }, []);
-  const connect = useCallback(async () => {
-    setError(null);
-    setMessages([]);
-    setPendingUserTranscript(null);
-    setPendingAssistantTranscript(null);
-    await client.connect();
-  }, [client]);
-  const disconnect = useCallback(async () => {
-    await client.disconnect();
-  }, [client]);
-  const startListening = useCallback(() => {
-    client.startListening();
-  }, [client]);
-  const stopListening = useCallback(() => {
-    client.stopListening();
-  }, [client]);
-  const interrupt = useCallback(() => {
-    client.interrupt();
-  }, [client]);
-  const sendText = useCallback(
-    (text) => {
-      client.sendText(text);
-    },
-    [client]
-  );
-  const sendImage = useCallback(
-    (imageData, mimeType) => {
-      client.sendImage(imageData, mimeType);
-    },
-    [client]
-  );
-  const getInputFrequencyData = useCallback(() => {
-    return clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData;
-  }, []);
-  const getOutputFrequencyData = useCallback(() => {
-    return clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData;
-  }, []);
-  const getInputTimeDomainData = useCallback(() => {
-    return clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData;
-  }, []);
-  const getOutputTimeDomainData = useCallback(() => {
-    return clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData;
-  }, []);
-  const updateSession = useCallback((config) => {
-    clientRef.current?.updateSession(config);
-  }, []);
-  return {
-    // Connection state
-    status,
-    error,
-    connect,
-    disconnect,
-    // Conversation state
-    mode,
-    messages,
-    pendingUserTranscript,
-    pendingAssistantTranscript,
-    // Voice control
-    startListening,
-    stopListening,
-    interrupt,
-    // Text input
-    sendText,
-    // Image input
-    sendImage,
-    // Audio visualization
-    inputLevel,
-    outputLevel,
-    getInputFrequencyData,
-    getOutputFrequencyData,
-    getInputTimeDomainData,
-    getOutputTimeDomainData,
-    // Session control
-    updateSession
-  };
+	const [status, setStatus] = useState("idle");
+	const [mode, setMode] = useState("idle");
+	const [messages, setMessages] = useState([]);
+	const [pendingUserTranscript, setPendingUserTranscript] = useState(null);
+	const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState(null);
+	const [error, setError] = useState(null);
+	const [inputLevel, setInputLevel] = useState(0);
+	const [outputLevel, setOutputLevel] = useState(0);
+	const clientRef = useRef(null);
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	const animationFrameRef = useRef(null);
+	if (!clientRef.current) {
+		const initial = optionsRef.current;
+		clientRef.current = new RealtimeClient({
+			getToken: initial.getToken,
+			adapter: initial.adapter,
+			...initial.tools !== void 0 && { tools: initial.tools },
+			...initial.instructions !== void 0 && { instructions: initial.instructions },
+			...initial.voice !== void 0 && { voice: initial.voice },
+			...initial.autoPlayback !== void 0 && { autoPlayback: initial.autoPlayback },
+			...initial.autoCapture !== void 0 && { autoCapture: initial.autoCapture },
+			...initial.vadMode !== void 0 && { vadMode: initial.vadMode },
+			...initial.outputModalities !== void 0 && { outputModalities: initial.outputModalities },
+			...initial.temperature !== void 0 && { temperature: initial.temperature },
+			...initial.maxOutputTokens !== void 0 && { maxOutputTokens: initial.maxOutputTokens },
+			...initial.semanticEagerness !== void 0 && { semanticEagerness: initial.semanticEagerness },
+			onStatusChange: (newStatus) => {
+				setStatus(newStatus);
+			},
+			onModeChange: (newMode) => {
+				setMode(newMode);
+				optionsRef.current.onModeChange?.(newMode);
+			},
+			onMessage: (message) => {
+				setMessages((prev) => [...prev, message]);
+				optionsRef.current.onMessage?.(message);
+			},
+			onUsage(usage) {
+				optionsRef.current.onUsage?.(usage);
+			},
+			onGoAway(timeLeft) {
+				optionsRef.current.onGoAway?.(timeLeft);
+			},
+			onError: (err) => {
+				setError(err);
+				optionsRef.current.onError?.(err);
+			},
+			onConnect: () => {
+				setError(null);
+				optionsRef.current.onConnect?.();
+			},
+			onDisconnect: () => {
+				optionsRef.current.onDisconnect?.();
+			},
+			onInterrupted: () => {
+				setPendingAssistantTranscript(null);
+				optionsRef.current.onInterrupted?.();
+			}
+		});
+		clientRef.current.onStateChange((state) => {
+			setPendingUserTranscript(state.pendingUserTranscript);
+			setPendingAssistantTranscript(state.pendingAssistantTranscript);
+		});
+	}
+	const client = clientRef.current;
+	useEffect(() => {
+		function updateLevels() {
+			if (clientRef.current?.audio) {
+				setInputLevel(clientRef.current.audio.inputLevel);
+				setOutputLevel(clientRef.current.audio.outputLevel);
+			}
+			animationFrameRef.current = requestAnimationFrame(updateLevels);
+		}
+		if (status === "connected") updateLevels();
+		return () => {
+			if (animationFrameRef.current) {
+				cancelAnimationFrame(animationFrameRef.current);
+				animationFrameRef.current = null;
+			}
+		};
+	}, [status]);
+	useEffect(() => {
+		return () => {
+			clientRef.current?.destroy();
+		};
+	}, []);
+	return {
+		status,
+		error,
+		connect: useCallback(async () => {
+			setError(null);
+			setMessages([]);
+			setPendingUserTranscript(null);
+			setPendingAssistantTranscript(null);
+			await client.connect();
+		}, [client]),
+		disconnect: useCallback(async () => {
+			await client.disconnect();
+		}, [client]),
+		mode,
+		messages,
+		pendingUserTranscript,
+		pendingAssistantTranscript,
+		startListening: useCallback(() => {
+			client.startListening();
+		}, [client]),
+		stopListening: useCallback(() => {
+			client.stopListening();
+		}, [client]),
+		interrupt: useCallback(() => {
+			client.interrupt();
+		}, [client]),
+		sendText: useCallback((text) => {
+			client.sendText(text);
+		}, [client]),
+		sendImage: useCallback((imageData, mimeType) => {
+			client.sendImage(imageData, mimeType);
+		}, [client]),
+		inputLevel,
+		outputLevel,
+		getInputFrequencyData: useCallback(() => {
+			return clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData;
+		}, []),
+		getOutputFrequencyData: useCallback(() => {
+			return clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData;
+		}, []),
+		getInputTimeDomainData: useCallback(() => {
+			return clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData;
+		}, []),
+		getOutputTimeDomainData: useCallback(() => {
+			return clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData;
+		}, []),
+		updateSession: useCallback((config) => {
+			clientRef.current?.updateSession(config);
+		}, [])
+	};
 }
-export {
-  useRealtimeChat
-};
-//# sourceMappingURL=use-realtime-chat.js.map
+//#endregion
+export { useRealtimeChat };
+
+//# sourceMappingURL=use-realtime-chat.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-realtime-chat.js","sources":["../../src/use-realtime-chat.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react'\nimport { RealtimeClient } from '@tanstack/ai-client'\nimport type {\n  RealtimeMessage,\n  RealtimeMode,\n  RealtimeSessionConfig,\n  RealtimeStatus,\n} from '@tanstack/ai'\nimport type {\n  UseRealtimeChatOptions,\n  UseRealtimeChatReturn,\n} from './realtime-types'\n\n// Empty frequency data for when client is not connected\nconst emptyFrequencyData = new Uint8Array(128)\nconst emptyTimeDomainData = new Uint8Array(128).fill(128)\n\n/**\n * React hook for realtime voice conversations.\n *\n * Provides a simple interface for voice-to-voice AI interactions\n * with support for multiple providers (OpenAI, ElevenLabs, etc.).\n *\n * @param options - Configuration options including adapter and callbacks\n * @returns Hook return value with state and control methods\n *\n * @example\n * ```typescript\n * import { useRealtimeChat } from '@tanstack/ai-react'\n * import { openaiRealtime } from '@tanstack/ai-openai'\n *\n * function VoiceChat() {\n *   const {\n *     status,\n *     mode,\n *     messages,\n *     connect,\n *     disconnect,\n *     inputLevel,\n *     outputLevel,\n *   } = useRealtimeChat({\n *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),\n *     adapter: openaiRealtime(),\n *   })\n *\n *   return (\n *     <div>\n *       <p>Status: {status}</p>\n *       <p>Mode: {mode}</p>\n *       <button onClick={status === 'idle' ? connect : disconnect}>\n *         {status === 'idle' ? 'Start' : 'Stop'}\n *       </button>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useRealtimeChat(\n  options: UseRealtimeChatOptions,\n): UseRealtimeChatReturn {\n  // State\n  const [status, setStatus] = useState<RealtimeStatus>('idle')\n  const [mode, setMode] = useState<RealtimeMode>('idle')\n  const [messages, setMessages] = useState<Array<RealtimeMessage>>([])\n  const [pendingUserTranscript, setPendingUserTranscript] = useState<\n    string | null\n  >(null)\n  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState<\n    string | null\n  >(null)\n  const [error, setError] = useState<Error | null>(null)\n  const [inputLevel, setInputLevel] = useState(0)\n  const [outputLevel, setOutputLevel] = useState(0)\n\n  // Refs\n  const clientRef = useRef<RealtimeClient | null>(null)\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const animationFrameRef = useRef<number | null>(null)\n\n  // Create client instance - use ref to ensure we reuse the same instance\n  // This handles React StrictMode double-rendering\n  if (!clientRef.current) {\n    // Each optional source field is spread conditionally because the\n    // `RealtimeClientOptions` target declares strict optionals\n    // (`field?: T`) and `exactOptionalPropertyTypes` rejects passing\n    // `undefined` for absent values.\n    const initial = optionsRef.current\n    clientRef.current = new RealtimeClient({\n      getToken: initial.getToken,\n      adapter: initial.adapter,\n      ...(initial.tools !== undefined && { tools: initial.tools }),\n      ...(initial.instructions !== undefined && {\n        instructions: initial.instructions,\n      }),\n      ...(initial.voice !== undefined && { voice: initial.voice }),\n      ...(initial.autoPlayback !== undefined && {\n        autoPlayback: initial.autoPlayback,\n      }),\n      ...(initial.autoCapture !== undefined && {\n        autoCapture: initial.autoCapture,\n      }),\n      ...(initial.vadMode !== undefined && { vadMode: initial.vadMode }),\n      ...(initial.outputModalities !== undefined && {\n        outputModalities: initial.outputModalities,\n      }),\n      ...(initial.temperature !== undefined && {\n        temperature: initial.temperature,\n      }),\n      ...(initial.maxOutputTokens !== undefined && {\n        maxOutputTokens: initial.maxOutputTokens,\n      }),\n      ...(initial.semanticEagerness !== undefined && {\n        semanticEagerness: initial.semanticEagerness,\n      }),\n      onStatusChange: (newStatus) => {\n        setStatus(newStatus)\n      },\n      onModeChange: (newMode) => {\n        setMode(newMode)\n        optionsRef.current.onModeChange?.(newMode)\n      },\n      onMessage: (message) => {\n        setMessages((prev) => [...prev, message])\n        optionsRef.current.onMessage?.(message)\n      },\n      onUsage(usage) {\n        optionsRef.current.onUsage?.(usage)\n      },\n      onGoAway(timeLeft) {\n        optionsRef.current.onGoAway?.(timeLeft)\n      },\n      onError: (err) => {\n        setError(err)\n        optionsRef.current.onError?.(err)\n      },\n      onConnect: () => {\n        setError(null)\n        optionsRef.current.onConnect?.()\n      },\n      onDisconnect: () => {\n        optionsRef.current.onDisconnect?.()\n      },\n      onInterrupted: () => {\n        setPendingAssistantTranscript(null)\n        optionsRef.current.onInterrupted?.()\n      },\n    })\n\n    // Subscribe to state changes for transcripts\n    clientRef.current.onStateChange((state) => {\n      setPendingUserTranscript(state.pendingUserTranscript)\n      setPendingAssistantTranscript(state.pendingAssistantTranscript)\n    })\n  }\n\n  const client = clientRef.current\n\n  // Audio level animation loop\n  useEffect(() => {\n    function updateLevels() {\n      if (clientRef.current?.audio) {\n        setInputLevel(clientRef.current.audio.inputLevel)\n        setOutputLevel(clientRef.current.audio.outputLevel)\n      }\n      animationFrameRef.current = requestAnimationFrame(updateLevels)\n    }\n\n    if (status === 'connected') {\n      updateLevels()\n    }\n\n    return () => {\n      if (animationFrameRef.current) {\n        cancelAnimationFrame(animationFrameRef.current)\n        animationFrameRef.current = null\n      }\n    }\n  }, [status])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      clientRef.current?.destroy()\n    }\n  }, [])\n\n  // Connection methods\n  const connect = useCallback(async () => {\n    setError(null)\n    setMessages([])\n    setPendingUserTranscript(null)\n    setPendingAssistantTranscript(null)\n    await client.connect()\n  }, [client])\n\n  const disconnect = useCallback(async () => {\n    await client.disconnect()\n  }, [client])\n\n  // Voice control methods\n  const startListening = useCallback(() => {\n    client.startListening()\n  }, [client])\n\n  const stopListening = useCallback(() => {\n    client.stopListening()\n  }, [client])\n\n  const interrupt = useCallback(() => {\n    client.interrupt()\n  }, [client])\n\n  // Text input\n  const sendText = useCallback(\n    (text: string) => {\n      client.sendText(text)\n    },\n    [client],\n  )\n\n  // Image input\n  const sendImage = useCallback(\n    (imageData: string, mimeType: string) => {\n      client.sendImage(imageData, mimeType)\n    },\n    [client],\n  )\n\n  // Audio visualization\n  const getInputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getOutputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getInputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  const getOutputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  const updateSession = useCallback((config: RealtimeSessionConfig) => {\n    clientRef.current?.updateSession(config)\n  }, [])\n\n  return {\n    // Connection state\n    status,\n    error,\n    connect,\n    disconnect,\n\n    // Conversation state\n    mode,\n    messages,\n    pendingUserTranscript,\n    pendingAssistantTranscript,\n\n    // Voice control\n    startListening,\n    stopListening,\n    interrupt,\n\n    // Text input\n    sendText,\n\n    // Image input\n    sendImage,\n\n    // Audio visualization\n    inputLevel,\n    outputLevel,\n    getInputFrequencyData,\n    getOutputFrequencyData,\n    getInputTimeDomainData,\n    getOutputTimeDomainData,\n\n    // Session control\n    updateSession,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-realtime-chat.js","names":[],"sources":["../../src/use-realtime-chat.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react'\nimport { RealtimeClient } from '@tanstack/ai-client'\nimport type {\n  RealtimeMessage,\n  RealtimeMode,\n  RealtimeSessionConfig,\n  RealtimeStatus,\n} from '@tanstack/ai'\nimport type {\n  UseRealtimeChatOptions,\n  UseRealtimeChatReturn,\n} from './realtime-types'\n\n// Empty frequency data for when client is not connected\nconst emptyFrequencyData = new Uint8Array(128)\nconst emptyTimeDomainData = new Uint8Array(128).fill(128)\n\n/**\n * React hook for realtime voice conversations.\n *\n * Provides a simple interface for voice-to-voice AI interactions\n * with support for multiple providers (OpenAI, ElevenLabs, etc.).\n *\n * @param options - Configuration options including adapter and callbacks\n * @returns Hook return value with state and control methods\n *\n * @example\n * ```typescript\n * import { useRealtimeChat } from '@tanstack/ai-react'\n * import { openaiRealtime } from '@tanstack/ai-openai'\n *\n * function VoiceChat() {\n *   const {\n *     status,\n *     mode,\n *     messages,\n *     connect,\n *     disconnect,\n *     inputLevel,\n *     outputLevel,\n *   } = useRealtimeChat({\n *     getToken: () => fetch('/api/realtime-token').then(r => r.json()),\n *     adapter: openaiRealtime(),\n *   })\n *\n *   return (\n *     <div>\n *       <p>Status: {status}</p>\n *       <p>Mode: {mode}</p>\n *       <button onClick={status === 'idle' ? connect : disconnect}>\n *         {status === 'idle' ? 'Start' : 'Stop'}\n *       </button>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useRealtimeChat(\n  options: UseRealtimeChatOptions,\n): UseRealtimeChatReturn {\n  // State\n  const [status, setStatus] = useState<RealtimeStatus>('idle')\n  const [mode, setMode] = useState<RealtimeMode>('idle')\n  const [messages, setMessages] = useState<Array<RealtimeMessage>>([])\n  const [pendingUserTranscript, setPendingUserTranscript] = useState<\n    string | null\n  >(null)\n  const [pendingAssistantTranscript, setPendingAssistantTranscript] = useState<\n    string | null\n  >(null)\n  const [error, setError] = useState<Error | null>(null)\n  const [inputLevel, setInputLevel] = useState(0)\n  const [outputLevel, setOutputLevel] = useState(0)\n\n  // Refs\n  const clientRef = useRef<RealtimeClient | null>(null)\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const animationFrameRef = useRef<number | null>(null)\n\n  // Create client instance - use ref to ensure we reuse the same instance\n  // This handles React StrictMode double-rendering\n  if (!clientRef.current) {\n    // Each optional source field is spread conditionally because the\n    // `RealtimeClientOptions` target declares strict optionals\n    // (`field?: T`) and `exactOptionalPropertyTypes` rejects passing\n    // `undefined` for absent values.\n    const initial = optionsRef.current\n    clientRef.current = new RealtimeClient({\n      getToken: initial.getToken,\n      adapter: initial.adapter,\n      ...(initial.tools !== undefined && { tools: initial.tools }),\n      ...(initial.instructions !== undefined && {\n        instructions: initial.instructions,\n      }),\n      ...(initial.voice !== undefined && { voice: initial.voice }),\n      ...(initial.autoPlayback !== undefined && {\n        autoPlayback: initial.autoPlayback,\n      }),\n      ...(initial.autoCapture !== undefined && {\n        autoCapture: initial.autoCapture,\n      }),\n      ...(initial.vadMode !== undefined && { vadMode: initial.vadMode }),\n      ...(initial.outputModalities !== undefined && {\n        outputModalities: initial.outputModalities,\n      }),\n      ...(initial.temperature !== undefined && {\n        temperature: initial.temperature,\n      }),\n      ...(initial.maxOutputTokens !== undefined && {\n        maxOutputTokens: initial.maxOutputTokens,\n      }),\n      ...(initial.semanticEagerness !== undefined && {\n        semanticEagerness: initial.semanticEagerness,\n      }),\n      onStatusChange: (newStatus) => {\n        setStatus(newStatus)\n      },\n      onModeChange: (newMode) => {\n        setMode(newMode)\n        optionsRef.current.onModeChange?.(newMode)\n      },\n      onMessage: (message) => {\n        setMessages((prev) => [...prev, message])\n        optionsRef.current.onMessage?.(message)\n      },\n      onUsage(usage) {\n        optionsRef.current.onUsage?.(usage)\n      },\n      onGoAway(timeLeft) {\n        optionsRef.current.onGoAway?.(timeLeft)\n      },\n      onError: (err) => {\n        setError(err)\n        optionsRef.current.onError?.(err)\n      },\n      onConnect: () => {\n        setError(null)\n        optionsRef.current.onConnect?.()\n      },\n      onDisconnect: () => {\n        optionsRef.current.onDisconnect?.()\n      },\n      onInterrupted: () => {\n        setPendingAssistantTranscript(null)\n        optionsRef.current.onInterrupted?.()\n      },\n    })\n\n    // Subscribe to state changes for transcripts\n    clientRef.current.onStateChange((state) => {\n      setPendingUserTranscript(state.pendingUserTranscript)\n      setPendingAssistantTranscript(state.pendingAssistantTranscript)\n    })\n  }\n\n  const client = clientRef.current\n\n  // Audio level animation loop\n  useEffect(() => {\n    function updateLevels() {\n      if (clientRef.current?.audio) {\n        setInputLevel(clientRef.current.audio.inputLevel)\n        setOutputLevel(clientRef.current.audio.outputLevel)\n      }\n      animationFrameRef.current = requestAnimationFrame(updateLevels)\n    }\n\n    if (status === 'connected') {\n      updateLevels()\n    }\n\n    return () => {\n      if (animationFrameRef.current) {\n        cancelAnimationFrame(animationFrameRef.current)\n        animationFrameRef.current = null\n      }\n    }\n  }, [status])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      clientRef.current?.destroy()\n    }\n  }, [])\n\n  // Connection methods\n  const connect = useCallback(async () => {\n    setError(null)\n    setMessages([])\n    setPendingUserTranscript(null)\n    setPendingAssistantTranscript(null)\n    await client.connect()\n  }, [client])\n\n  const disconnect = useCallback(async () => {\n    await client.disconnect()\n  }, [client])\n\n  // Voice control methods\n  const startListening = useCallback(() => {\n    client.startListening()\n  }, [client])\n\n  const stopListening = useCallback(() => {\n    client.stopListening()\n  }, [client])\n\n  const interrupt = useCallback(() => {\n    client.interrupt()\n  }, [client])\n\n  // Text input\n  const sendText = useCallback(\n    (text: string) => {\n      client.sendText(text)\n    },\n    [client],\n  )\n\n  // Image input\n  const sendImage = useCallback(\n    (imageData: string, mimeType: string) => {\n      client.sendImage(imageData, mimeType)\n    },\n    [client],\n  )\n\n  // Audio visualization\n  const getInputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getOutputFrequencyData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputFrequencyData() ?? emptyFrequencyData\n    )\n  }, [])\n\n  const getInputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getInputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  const getOutputTimeDomainData = useCallback(() => {\n    return (\n      clientRef.current?.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData\n    )\n  }, [])\n\n  const updateSession = useCallback((config: RealtimeSessionConfig) => {\n    clientRef.current?.updateSession(config)\n  }, [])\n\n  return {\n    // Connection state\n    status,\n    error,\n    connect,\n    disconnect,\n\n    // Conversation state\n    mode,\n    messages,\n    pendingUserTranscript,\n    pendingAssistantTranscript,\n\n    // Voice control\n    startListening,\n    stopListening,\n    interrupt,\n\n    // Text input\n    sendText,\n\n    // Image input\n    sendImage,\n\n    // Audio visualization\n    inputLevel,\n    outputLevel,\n    getInputFrequencyData,\n    getOutputFrequencyData,\n    getInputTimeDomainData,\n    getOutputTimeDomainData,\n\n    // Session control\n    updateSession,\n  }\n}\n"],"mappings":"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"}

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

@@ -1,5 +1,5 @@
 import { StreamChunk, SummarizationResult } from '@tanstack/ai';
-import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn, SummarizeGenerateInput } from '@tanstack/ai-client';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, GenerationPersistenceOptions, InferGenerationOutputFromReturn, SummarizeGenerateInput } from '@tanstack/ai-client';
 /**
  * Options for the useSummarize hook.
  *
@@ -10,12 +10,51 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for summarization */
     fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>;
-    /** Unique identifier for this generation instance */
+    /**
+     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+     */
     id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
     devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * How this generation persists across reloads.
+     * - Omit / `false`: ephemeral, in-memory only.
+     * - `true`: server-driven — on mount the client hydrates the last generation
+     *   for its `threadId` from the server (needs a connection with a
+     *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+     */
+    persistence?: boolean;
+    /**
+     * The **scope** this generation belongs to: a stable, app-chosen name for the
+     * slot successive runs fill — not a link to a chat conversation.
+     *
+     * The hook starts empty and produces many runs over its life; each gets its
+     * own `runId`, but all belong to one scope. Persistence keys on this, so
+     * derive it from your own domain and keep it identical across reloads (e.g.
+     * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+     * id on the wire, which the protocol requires.
+     *
+     * **Required whenever `persistence` is set** — an app that cannot name the
+     * scope has nothing to restore to. Optional for ephemeral generations, where
+     * it falls back to `id` purely to satisfy the wire.
+     */
+    threadId?: string;
+    /**
+     * Server-driven hydration handler for `persistence: true` when the
+     * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+     * `rpcStream()` adapter built without handlers) — typically a one-line
+     * server-function call. The connection's own handler takes precedence.
+     */
+    hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration'];
+    /**
+     * Re-attach handler that replays a run still generating to completion on
+     * mount, when the connection doesn't carry one. Without it, a restored
+     * `running` snapshot surfaces as an (interrupted) error. The connection's
+     * own handler takes precedence.
+     */
+    joinRun?: ConnectConnectionAdapter['joinRun'];
     /**
      * Callback when summarization is complete. Can optionally return a transformed value.
      *
@@ -51,6 +90,13 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
     stop: () => void;
     /** Clear result, error, and return to idle */
     reset: () => void;
+    /**
+     * The id of the generation job currently running, or `null` when nothing is in
+     * flight. Each call to `generate` is one job with its own id. Pass it to your
+     * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+     * local stream, it does not stop work already running on the provider.
+     */
+    runId: string | null;
 }
 /**
  * React hook for summarizing text using AI models.
@@ -81,6 +127,6 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
  * }
  * ```
  */
-export declare function useSummarize<TTransformed = void>(options: Omit<UseSummarizeOptions, 'onResult'> & {
+export declare function useSummarize<TTransformed = void>(options: Omit<UseSummarizeOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
     onResult?: (result: SummarizationResult) => TTransformed;
-}): UseSummarizeReturn<InferGenerationOutputFromReturn<SummarizationResult, TTransformed>>;
+} & GenerationPersistenceOptions): UseSummarizeReturn<InferGenerationOutputFromReturn<SummarizationResult, TTransformed>>;

package/dist/esm/use-summarize.js

@@ -1,26 +1,49 @@
 import { useGeneration } from "./use-generation.js";
+import { reconstructSummarizeResult } from "@tanstack/ai-client";
+//#region src/use-summarize.ts
+/**
+* React hook for summarizing text using AI models.
+*
+* @example
+* ```tsx
+* import { useSummarize } from '@tanstack/ai-react'
+* import { fetchServerSentEvents } from '@tanstack/ai-client'
+*
+* function Summarizer() {
+*   const { generate, result, isLoading } = useSummarize({
+*     connection: fetchServerSentEvents('/api/summarize'),
+*   })
+*
+*   return (
+*     <div>
+*       <button onClick={() => generate({
+*         text: 'Long article text...',
+*         style: 'bullet-points',
+*         maxLength: 200,
+*       })}>
+*         Summarize
+*       </button>
+*       {isLoading && <p>Summarizing...</p>}
+*       {result && <p>{result.summary}</p>}
+*     </div>
+*   )
+* }
+* ```
+*/
 function useSummarize(options) {
-  const devtools = {
-    ...options.devtools,
-    framework: "react",
-    hookName: "useSummarize",
-    outputKind: "text"
-  };
-  const { generate, result, isLoading, error, status, stop, reset } = useGeneration({
-    ...options,
-    devtools
-  });
-  return {
-    generate,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset
-  };
+	const devtools = {
+		...options.devtools,
+		framework: "react",
+		hookName: "useSummarize",
+		outputKind: "text"
+	};
+	return useGeneration({
+		...options,
+		devtools,
+		reconstructResult: reconstructSummarizeResult
+	});
 }
-export {
-  useSummarize
-};
-//# sourceMappingURL=use-summarize.js.map
+//#endregion
+export { useSummarize };
+
+//# sourceMappingURL=use-summarize.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-summarize.js","sources":["../../src/use-summarize.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport type { StreamChunk, SummarizationResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutputFromReturn,\n  SummarizeGenerateInput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useSummarize hook.\n *\n * @template TOutput - The output type after optional transform (defaults to SummarizationResult)\n */\nexport interface UseSummarizeOptions<TOutput = SummarizationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for summarization */\n  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>\n  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * Callback when summarization is complete. Can optionally return a transformed value.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: SummarizationResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n}\n\n/**\n * Return type for the useSummarize hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseSummarizeReturn<TOutput = SummarizationResult> {\n  /** Trigger summarization */\n  generate: (input: SummarizeGenerateInput) => Promise<void>\n  /** The summarization result, or null */\n  result: TOutput | null\n  /** Whether summarization is in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation */\n  status: GenerationClientState\n  /** Abort the current summarization */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n}\n\n/**\n * React hook for summarizing text using AI models.\n *\n * @example\n * ```tsx\n * import { useSummarize } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function Summarizer() {\n *   const { generate, result, isLoading } = useSummarize({\n *     connection: fetchServerSentEvents('/api/summarize'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({\n *         text: 'Long article text...',\n *         style: 'bullet-points',\n *         maxLength: 200,\n *       })}>\n *         Summarize\n *       </button>\n *       {isLoading && <p>Summarizing...</p>}\n *       {result && <p>{result.summary}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useSummarize<TTransformed = void>(\n  options: Omit<UseSummarizeOptions, 'onResult'> & {\n    onResult?: (result: SummarizationResult) => TTransformed\n  },\n): UseSummarizeReturn<\n  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useSummarize',\n    outputKind: 'text' as const,\n  }\n  const { generate, result, isLoading, error, status, stop, reset } =\n    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({\n      ...options,\n      devtools,\n    })\n\n  return {\n    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";AA8FO,SAAS,aACd,SAKA;AACA,QAAM,WAAW;AAAA,IACf,GAAG,QAAQ;AAAA,IACX,WAAW;AAAA,IACX,UAAU;AAAA,IACV,YAAY;AAAA,EAAA;AAEd,QAAM,EAAE,UAAU,QAAQ,WAAW,OAAO,QAAQ,MAAM,MAAA,IACxD,cAAyE;AAAA,IACvE,GAAG;AAAA,IACH;AAAA,EAAA,CACD;AAEH,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"use-summarize.js","names":[],"sources":["../../src/use-summarize.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport { reconstructSummarizeResult } from '@tanstack/ai-client'\nimport type { StreamChunk, SummarizationResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  SummarizeGenerateInput,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useSummarize hook.\n *\n * @template TOutput - The output type after optional transform (defaults to SummarizationResult)\n */\nexport interface UseSummarizeOptions<TOutput = SummarizationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for summarization */\n  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>\n  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when summarization is complete. Can optionally return a transformed value.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: SummarizationResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n}\n\n/**\n * Return type for the useSummarize hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseSummarizeReturn<TOutput = SummarizationResult> {\n  /** Trigger summarization */\n  generate: (input: SummarizeGenerateInput) => Promise<void>\n  /** The summarization result, or null */\n  result: TOutput | null\n  /** Whether summarization is in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation */\n  status: GenerationClientState\n  /** Abort the current summarization */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n  /**\n   * The id of the generation job currently running, or `null` when nothing is in\n   * flight. Each call to `generate` is one job with its own id. Pass it to your\n   * own endpoint to cancel or poll the provider job — `stop()` only aborts the\n   * local stream, it does not stop work already running on the provider.\n   */\n  runId: string | null\n}\n\n/**\n * React hook for summarizing text using AI models.\n *\n * @example\n * ```tsx\n * import { useSummarize } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function Summarizer() {\n *   const { generate, result, isLoading } = useSummarize({\n *     connection: fetchServerSentEvents('/api/summarize'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({\n *         text: 'Long article text...',\n *         style: 'bullet-points',\n *         maxLength: 200,\n *       })}>\n *         Summarize\n *       </button>\n *       {isLoading && <p>Summarizing...</p>}\n *       {result && <p>{result.summary}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useSummarize<TTransformed = void>(\n  options: Omit<\n    UseSummarizeOptions,\n    'onResult' | 'persistence' | 'threadId' | 'id'\n  > & {\n    onResult?: (result: SummarizationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseSummarizeReturn<\n  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useSummarize',\n    outputKind: 'text' as const,\n  }\n  const generation = useGeneration<\n    SummarizeGenerateInput,\n    SummarizationResult,\n    TTransformed\n  >({\n    ...options,\n    devtools,\n    reconstructResult: reconstructSummarizeResult,\n  })\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8IA,SAAgB,aACd,SAQA;CACA,MAAM,WAAW;EACf,GAAG,QAAQ;EACX,WAAW;EACX,UAAU;EACV,YAAY;CACd;CAWA,OAVmB,cAIjB;EACA,GAAG;EACH;EACA,mBAAmB;CACrB,CAEO;AACT"}