@tanstack/ai-react 0.28.0 → 0.29.3

package/README.md

@@ -240,6 +240,7 @@ Official adapters include:
 | [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus)     | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR            |
 | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal)               | fal.ai image, video, audio, speech, and transcription models                           |
 | [`@tanstack/ai-reactor`](https://tanstack.com/ai/latest/docs/adapters/reactor)       | Reactor live world and video generation (Orbis, Happy Oyster, LingBot, Helios, FastH3) |
+| [`@tanstack/ai-worldlabs`](https://tanstack.com/ai/latest/docs/adapters/worldlabs)   | World Labs Marble persistent 3D world generation                                       |
 | [`@tanstack/ai-cloudflare`](https://tanstack.com/ai/latest/docs/adapters/cloudflare) | Cloudflare Workers AI chat, embeddings, image, speech, transcription, and AI Gateway   |
 
 The adapter system is tree-shakeable by activity. Import `openaiText` for chat,

package/dist/esm/index.d.ts

@@ -4,8 +4,8 @@ export { useByok } from './use-byok.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 { useWebMCPTools } from './use-web-mcp-tools.js';
-export type { UseWebMCPToolsOptions } from './use-web-mcp-tools.js';
+export { usePageWebMCPTools, useRegisterWebMCPTools, useWebMCPTools, } from './use-web-mcp-tools.js';
+export type { UsePageWebMCPToolsOptions, UseRegisterWebMCPToolsOptions, UseWebMCPToolsOptions, } from './use-web-mcp-tools.js';
 export type { DeepPartial, UseChatOptions, UseChatReturn, UIMessage, ChatRequestBody, QueuedMessage, SendMessageOptions, WhenBusy, QueueConfig, QueueStrategy, QueueOption, } from './types.js';
 export type { UseRealtimeChatOptions, UseRealtimeChatReturn, } from './realtime-types.js';
 export { useGeneration } from './use-generation.js';
@@ -24,4 +24,4 @@ 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 { AudioRecorder, ChatClient, InterruptManager, RealtimeClient, GenerationClient, VideoGenerationClient, GENERATION_EVENTS, reconstructImageResult, reconstructAudioResult, reconstructSpeechResult, reconstructTranscriptionResult, reconstructSummarizeResult, UnsupportedResponseStreamError, createAIDevtoolsGenerationPreview, StreamTruncatedError, DurableStreamIncompleteError, StreamReconnectLimitError, uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, convertMessagesToModelMessages, normalizeToUIMessage, generateMessageId, StreamProcessor, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, parsePartialJSON, PartialJSONParser, defaultJSONParser, registerWebMCPTools, clientTools, fetchServerSentEvents, localStoragePersistence, sessionStoragePersistence, indexedDBPersistence, StorageUnavailableError, type ChatClientPersistence, type ChatPersistedState, type ChatPersistenceOption, type ChatStorageAdapter, type WebStoragePersistenceOptions, type IndexedDBPersistenceOptions, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, webSocket, 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 WebSocketConnectionOptions, type InferChatMessages, type GenericInterrupt, type RegisteredGenericInterrupt, type GenerationClientState, type ImageGenerateInput, type AudioGenerateInput, type SpeechGenerateInput, type TranscriptionGenerateInput, type SummarizeGenerateInput, type VideoGenerateInput, type VideoGenerateResult, type VideoStatusInfo, } from '@tanstack/ai-client';
+export { AudioRecorder, ChatClient, InterruptManager, RealtimeClient, GenerationClient, VideoGenerationClient, GENERATION_EVENTS, reconstructImageResult, reconstructAudioResult, reconstructSpeechResult, reconstructTranscriptionResult, reconstructSummarizeResult, UnsupportedResponseStreamError, createAIDevtoolsGenerationPreview, StreamTruncatedError, DurableStreamIncompleteError, StreamReconnectLimitError, uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, convertMessagesToModelMessages, normalizeToUIMessage, generateMessageId, StreamProcessor, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, parsePartialJSON, PartialJSONParser, defaultJSONParser, registerWebMCPTools, getWebMCPTools, subscribeWebMCPTools, type GetWebMCPToolsOptions, type SubscribeWebMCPToolsOptions, type WebMCPPageTool, clientTools, fetchServerSentEvents, localStoragePersistence, sessionStoragePersistence, indexedDBPersistence, StorageUnavailableError, type ChatClientPersistence, type ChatPersistedState, type ChatPersistenceOption, type ChatStorageAdapter, type WebStoragePersistenceOptions, type IndexedDBPersistenceOptions, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, webSocket, 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 WebSocketConnectionOptions, type InferChatMessages, type GenericInterrupt, type RegisteredGenericInterrupt, 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

@@ -3,7 +3,7 @@ import { createChatHook } from "./create-chat-hook.js";
 import { useByok } from "./use-byok.js";
 import { useRealtimeChat } from "./use-realtime-chat.js";
 import { useMcpAppBridge } from "./use-mcp-app-bridge.js";
-import { useWebMCPTools } from "./use-web-mcp-tools.js";
+import { usePageWebMCPTools, useRegisterWebMCPTools, useWebMCPTools } from "./use-web-mcp-tools.js";
 import { useGeneration } from "./use-generation.js";
 import { useGenerateImage } from "./use-generate-image.js";
 import { useGenerateAudio } from "./use-generate-audio.js";
@@ -12,5 +12,5 @@ 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 { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents } from "@tanstack/ai-client";
-export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createChatHook, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, useAudioRecorder, useByok, useChat, useGenerateAudio, useGenerateImage, useGenerateSpeech, useGenerateVideo, useGeneration, useMcpAppBridge, useRealtimeChat, useSummarize, useTranscription, useWebMCPTools, webSocket, xhrHttpStream, xhrServerSentEvents };
+import { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, getWebMCPTools, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, subscribeWebMCPTools, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents } from "@tanstack/ai-client";
+export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createChatHook, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, getWebMCPTools, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, subscribeWebMCPTools, uiMessageToModelMessages, useAudioRecorder, useByok, useChat, useGenerateAudio, useGenerateImage, useGenerateSpeech, useGenerateVideo, useGeneration, useMcpAppBridge, usePageWebMCPTools, useRealtimeChat, useRegisterWebMCPTools, useSummarize, useTranscription, useWebMCPTools, webSocket, xhrHttpStream, xhrServerSentEvents };

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

@@ -1,4 +1,4 @@
-import { useGeneration } from "./use-generation.js";
+import { useGenerationWithDevtoolsIdentity } from "./use-generation.js";
 import { reconstructAudioResult } from "@tanstack/ai-client";
 //#region src/use-generate-audio.ts
 /**
@@ -32,16 +32,12 @@ import { reconstructAudioResult } from "@tanstack/ai-client";
 * ```
 */
 function useGenerateAudio(options) {
-	const devtools = {
-		...options.devtools,
-		framework: "react",
-		hookName: "useGenerateAudio",
-		outputKind: "audio"
-	};
-	return useGeneration({
+	return useGenerationWithDevtoolsIdentity({
 		...options,
-		devtools,
 		reconstructResult: reconstructAudioResult
+	}, {
+		hookName: "useGenerateAudio",
+		outputKind: "audio"
 	});
 }
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"use-generate-audio.js","names":[],"sources":["../../src/use-generate-audio.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport { reconstructAudioResult } from '@tanstack/ai-client'\nimport type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  AudioGenerateInput,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateAudio hook.\n *\n * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)\n */\nexport interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for audio generation */\n  fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 audio is generated. 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: AudioGenerationResult) => 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 useGenerateAudio hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {\n  /** Trigger audio generation */\n  generate: (input: AudioGenerateInput) => Promise<void>\n  /** The generation result containing audio, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating audio (music, sound effects) using AI models.\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)\n * - **Fetcher** — Direct async function call\n *\n * @example\n * ```tsx\n * import { useGenerateAudio } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function AudioGenerator() {\n *   const { generate, result, isLoading, error, reset } = useGenerateAudio({\n *     connection: fetchServerSentEvents('/api/generate/audio'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'An upbeat electronic track', duration: 10 })}>\n *         Generate\n *       </button>\n *       {isLoading && <p>Generating...</p>}\n *       {error && <p>Error: {error.message}</p>}\n *       {result?.audio.url && <audio src={result.audio.url} controls />}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateAudio<TTransformed = void>(\n  options: Omit<\n    UseGenerateAudioOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: AudioGenerationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateAudioReturn<\n  InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useGenerateAudio',\n    outputKind: 'audio' as const,\n  }\n  const generation = useGeneration<\n    AudioGenerateInput,\n    AudioGenerationResult,\n    TTransformed\n  >({\n    ...options,\n    devtools,\n    reconstructResult: reconstructAudioResult,\n  })\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiJA,SAAgB,iBACd,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"}
+{"version":3,"file":"use-generate-audio.js","names":[],"sources":["../../src/use-generate-audio.ts"],"sourcesContent":["import { useGenerationWithDevtoolsIdentity } from './use-generation'\nimport { reconstructAudioResult } from '@tanstack/ai-client'\nimport type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  AudioGenerateInput,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateAudio hook.\n *\n * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)\n */\nexport interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for audio generation */\n  fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 audio is generated. 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: AudioGenerationResult) => 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 useGenerateAudio hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {\n  /** Trigger audio generation */\n  generate: (input: AudioGenerateInput) => Promise<void>\n  /** The generation result containing audio, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating audio (music, sound effects) using AI models.\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)\n * - **Fetcher** — Direct async function call\n *\n * @example\n * ```tsx\n * import { useGenerateAudio } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function AudioGenerator() {\n *   const { generate, result, isLoading, error, reset } = useGenerateAudio({\n *     connection: fetchServerSentEvents('/api/generate/audio'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'An upbeat electronic track', duration: 10 })}>\n *         Generate\n *       </button>\n *       {isLoading && <p>Generating...</p>}\n *       {error && <p>Error: {error.message}</p>}\n *       {result?.audio.url && <audio src={result.audio.url} controls />}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateAudio<TTransformed = void>(\n  options: Omit<\n    UseGenerateAudioOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: AudioGenerationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateAudioReturn<\n  InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>\n> {\n  const generation = useGenerationWithDevtoolsIdentity<\n    AudioGenerateInput,\n    AudioGenerationResult,\n    TTransformed\n  >(\n    { ...options, reconstructResult: reconstructAudioResult },\n    {\n      hookName: 'useGenerateAudio',\n      outputKind: 'audio',\n    },\n  )\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiJA,SAAgB,iBACd,SAQA;CAaA,OAZmB,kCAKjB;EAAE,GAAG;EAAS,mBAAmB;CAAuB,GACxD;EACE,UAAU;EACV,YAAY;CACd,CAGK;AACT"}

package/dist/esm/use-generate-image.js

@@ -1,4 +1,4 @@
-import { useGeneration } from "./use-generation.js";
+import { useGenerationWithDevtoolsIdentity } from "./use-generation.js";
 import { reconstructImageResult } from "@tanstack/ai-client";
 //#region src/use-generate-image.ts
 /**
@@ -34,16 +34,12 @@ import { reconstructImageResult } from "@tanstack/ai-client";
 * ```
 */
 function useGenerateImage(options) {
-	const devtools = {
-		...options.devtools,
-		framework: "react",
-		hookName: "useGenerateImage",
-		outputKind: "image"
-	};
-	return useGeneration({
+	return useGenerationWithDevtoolsIdentity({
 		...options,
-		devtools,
 		reconstructResult: reconstructImageResult
+	}, {
+		hookName: "useGenerateImage",
+		outputKind: "image"
 	});
 }
 //#endregion

package/dist/esm/use-generate-image.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-generate-image.js","names":[],"sources":["../../src/use-generate-image.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport { reconstructImageResult } from '@tanstack/ai-client'\nimport type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  ImageGenerateInput,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateImage hook.\n *\n * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)\n */\nexport interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for image generation */\n  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 images are generated. 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: ImageGenerationResult) => 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 useGenerateImage hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {\n  /** Trigger image generation */\n  generate: (input: ImageGenerateInput) => Promise<void>\n  /** The generation result containing images, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating images using AI models.\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)\n * - **Fetcher** — Direct async function call\n *\n * @example\n * ```tsx\n * import { useGenerateImage } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function ImageGenerator() {\n *   const { generate, result, isLoading, error, reset } = useGenerateImage({\n *     connection: fetchServerSentEvents('/api/generate/image'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A sunset over mountains' })}>\n *         Generate\n *       </button>\n *       {isLoading && <p>Generating...</p>}\n *       {error && <p>Error: {error.message}</p>}\n *       {result?.images.map((img, i) => (\n *         <img key={i} src={img.url || `data:image/png;base64,${img.b64Json}`} />\n *       ))}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateImage<TTransformed = void>(\n  options: Omit<\n    UseGenerateImageOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: ImageGenerationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateImageReturn<\n  InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useGenerateImage',\n    outputKind: 'image' as const,\n  }\n  const generation = useGeneration<\n    ImageGenerateInput,\n    ImageGenerationResult,\n    TTransformed\n  >({\n    ...options,\n    devtools,\n    reconstructResult: reconstructImageResult,\n  })\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJA,SAAgB,iBACd,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"}
+{"version":3,"file":"use-generate-image.js","names":[],"sources":["../../src/use-generate-image.ts"],"sourcesContent":["import { useGenerationWithDevtoolsIdentity } from './use-generation'\nimport { reconstructImageResult } from '@tanstack/ai-client'\nimport type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  ImageGenerateInput,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateImage hook.\n *\n * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)\n */\nexport interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for image generation */\n  fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 images are generated. 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: ImageGenerationResult) => 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 useGenerateImage hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {\n  /** Trigger image generation */\n  generate: (input: ImageGenerateInput) => Promise<void>\n  /** The generation result containing images, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating images using AI models.\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)\n * - **Fetcher** — Direct async function call\n *\n * @example\n * ```tsx\n * import { useGenerateImage } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function ImageGenerator() {\n *   const { generate, result, isLoading, error, reset } = useGenerateImage({\n *     connection: fetchServerSentEvents('/api/generate/image'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A sunset over mountains' })}>\n *         Generate\n *       </button>\n *       {isLoading && <p>Generating...</p>}\n *       {error && <p>Error: {error.message}</p>}\n *       {result?.images.map((img, i) => (\n *         <img key={i} src={img.url || `data:image/png;base64,${img.b64Json}`} />\n *       ))}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateImage<TTransformed = void>(\n  options: Omit<\n    UseGenerateImageOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: ImageGenerationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateImageReturn<\n  InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>\n> {\n  const generation = useGenerationWithDevtoolsIdentity<\n    ImageGenerateInput,\n    ImageGenerationResult,\n    TTransformed\n  >(\n    { ...options, reconstructResult: reconstructImageResult },\n    {\n      hookName: 'useGenerateImage',\n      outputKind: 'image',\n    },\n  )\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJA,SAAgB,iBACd,SAQA;CAaA,OAZmB,kCAKjB;EAAE,GAAG;EAAS,mBAAmB;CAAuB,GACxD;EACE,UAAU;EACV,YAAY;CACd,CAGK;AACT"}

package/dist/esm/use-generate-speech.js

@@ -1,4 +1,4 @@
-import { useGeneration } from "./use-generation.js";
+import { useGenerationWithDevtoolsIdentity } from "./use-generation.js";
 import { reconstructSpeechResult } from "@tanstack/ai-client";
 //#region src/use-generate-speech.ts
 /**
@@ -28,16 +28,12 @@ import { reconstructSpeechResult } from "@tanstack/ai-client";
 * ```
 */
 function useGenerateSpeech(options) {
-	const devtools = {
-		...options.devtools,
-		framework: "react",
-		hookName: "useGenerateSpeech",
-		outputKind: "audio"
-	};
-	return useGeneration({
+	return useGenerationWithDevtoolsIdentity({
 		...options,
-		devtools,
 		reconstructResult: reconstructSpeechResult
+	}, {
+		hookName: "useGenerateSpeech",
+		outputKind: "audio"
 	});
 }
 //#endregion

package/dist/esm/use-generate-speech.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-generate-speech.js","names":[],"sources":["../../src/use-generate-speech.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport { reconstructSpeechResult } from '@tanstack/ai-client'\nimport type { StreamChunk, TTSResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  SpeechGenerateInput,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateSpeech hook.\n *\n * @template TOutput - The output type after optional transform (defaults to TTSResult)\n */\nexport interface UseGenerateSpeechOptions<TOutput = TTSResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for speech generation */\n  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 speech is generated. 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: TTSResult) => 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 useGenerateSpeech hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateSpeechReturn<TOutput = TTSResult> {\n  /** Trigger speech generation */\n  generate: (input: SpeechGenerateInput) => Promise<void>\n  /** The TTS result containing audio data, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating speech (text-to-speech) using AI models.\n *\n * @example\n * ```tsx\n * import { useGenerateSpeech } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function SpeechGenerator() {\n *   const { generate, result, isLoading } = useGenerateSpeech({\n *     connection: fetchServerSentEvents('/api/generate/speech'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>\n *         Generate Speech\n *       </button>\n *       {result && (\n *         <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />\n *       )}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateSpeech<TTransformed = void>(\n  options: Omit<\n    UseGenerateSpeechOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TTSResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateSpeechReturn<\n  InferGenerationOutputFromReturn<TTSResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useGenerateSpeech',\n    outputKind: 'audio' as const,\n  }\n  const generation = useGeneration<\n    SpeechGenerateInput,\n    TTSResult,\n    TTransformed\n  >({\n    ...options,\n    devtools,\n    reconstructResult: reconstructSpeechResult,\n  })\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6IA,SAAgB,kBACd,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"}
+{"version":3,"file":"use-generate-speech.js","names":[],"sources":["../../src/use-generate-speech.ts"],"sourcesContent":["import { useGenerationWithDevtoolsIdentity } from './use-generation'\nimport { reconstructSpeechResult } from '@tanstack/ai-client'\nimport type { StreamChunk, TTSResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  SpeechGenerateInput,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGenerateSpeech hook.\n *\n * @template TOutput - The output type after optional transform (defaults to TTSResult)\n */\nexport interface UseGenerateSpeechOptions<TOutput = TTSResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for speech generation */\n  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 speech is generated. 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: TTSResult) => 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 useGenerateSpeech hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateSpeechReturn<TOutput = TTSResult> {\n  /** Trigger speech generation */\n  generate: (input: SpeechGenerateInput) => Promise<void>\n  /** The TTS result containing audio data, or null */\n  result: TOutput | null\n  /** Whether generation 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 generation */\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 generating speech (text-to-speech) using AI models.\n *\n * @example\n * ```tsx\n * import { useGenerateSpeech } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function SpeechGenerator() {\n *   const { generate, result, isLoading } = useGenerateSpeech({\n *     connection: fetchServerSentEvents('/api/generate/speech'),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>\n *         Generate Speech\n *       </button>\n *       {result && (\n *         <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />\n *       )}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useGenerateSpeech<TTransformed = void>(\n  options: Omit<\n    UseGenerateSpeechOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TTSResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateSpeechReturn<\n  InferGenerationOutputFromReturn<TTSResult, TTransformed>\n> {\n  const generation = useGenerationWithDevtoolsIdentity<\n    SpeechGenerateInput,\n    TTSResult,\n    TTransformed\n  >(\n    { ...options, reconstructResult: reconstructSpeechResult },\n    {\n      hookName: 'useGenerateSpeech',\n      outputKind: 'audio',\n    },\n  )\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6IA,SAAgB,kBACd,SAQA;CAaA,OAZmB,kCAKjB;EAAE,GAAG;EAAS,mBAAmB;CAAwB,GACzD;EACE,UAAU;EACV,YAAY;CACd,CAGK;AACT"}

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

@@ -1,5 +1,5 @@
 import { StreamChunk } from '@tanstack/ai';
-import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, GenerationPersistenceOptions, GenerationRestoredResult, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+import { AIDevtoolsClientMetadata, AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, GenerationPersistenceOptions, GenerationRestoredResult, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
 import { ByokClient } from '@tanstack/ai-client/byok';
 import { ProviderId } from '@tanstack/ai/byok';
 /**
@@ -133,3 +133,12 @@ export interface UseGenerationReturn<TOutput, TInput extends Record<string, any>
 export declare function useGeneration<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult' | 'persistence' | 'threadId'> & {
     onResult?: (result: TResult) => TTransformed;
 } & GenerationPersistenceOptions): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>, TInput>;
+interface GenerationDevtoolsIdentity {
+    hookName: AIDevtoolsClientMetadata['hookName'];
+    outputKind?: AIDevtoolsClientMetadata['outputKind'];
+}
+/** @internal */
+export declare function useGenerationWithDevtoolsIdentity<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult' | 'persistence' | 'threadId'> & {
+    onResult?: (result: TResult) => TTransformed;
+} & GenerationPersistenceOptions, devtoolsIdentity: GenerationDevtoolsIdentity): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>, TInput>;
+export {};

package/dist/esm/use-generation.js

@@ -22,6 +22,10 @@ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 * ```
 */
 function useGeneration(options) {
+	return useGenerationWithDevtoolsIdentity(options, { hookName: "useGeneration" });
+}
+/** @internal */
+function useGenerationWithDevtoolsIdentity(options, devtoolsIdentity) {
 	const hookId = useId();
 	const clientIdentity = options.threadId ?? hookId;
 	const [result, setResult] = useState(null);
@@ -43,9 +47,10 @@ function useGeneration(options) {
 			...opts.reconstructResult ? { reconstructResult: opts.reconstructResult } : {},
 			devtoolsBridgeFactory: createGenerationDevtoolsBridge,
 			devtools: {
-				hookName: "useGeneration",
+				...opts.devtools,
 				framework: "react",
-				...opts.devtools
+				hookName: devtoolsIdentity.hookName,
+				...devtoolsIdentity.outputKind !== void 0 && { outputKind: devtoolsIdentity.outputKind }
 			},
 			onResult: ((r) => optionsRef.current.onResult?.(r)),
 			onError: (e) => {
@@ -118,6 +123,6 @@ function useGeneration(options) {
 	};
 }
 //#endregion
-export { useGeneration };
+export { useGeneration, useGenerationWithDevtoolsIdentity };
 
 //# sourceMappingURL=use-generation.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-generation.js","names":[],"sources":["../../src/use-generation.ts"],"sourcesContent":["import { GenerationClient } from '@tanstack/ai-client'\nimport { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  GenerationRestoredResult,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGeneration hook.\n *\n * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\nexport interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for one-shot generation (no streaming protocol needed) */\n  fetcher?: GenerationFetcher<TInput, TResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 a result is received. 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: TResult) => 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   * @internal Rebuild a typed result from a restored snapshot, injected by each\n   * specialized hook (image / speech / audio / transcription / summarize).\n   * Forwarded to the client so a server-hydrate restore repaints `result`.\n   */\n  reconstructResult?: (restored: GenerationRestoredResult) => TResult | null\n}\n\n/**\n * Return type for the useGeneration hook.\n *\n * @template TOutput - The output type (after optional transform)\n * @template TInput - The input type accepted by `generate` (defaults to any object)\n */\nexport interface UseGenerationReturn<\n  TOutput,\n  TInput extends Record<string, any> = Record<string, any>,\n> {\n  /** Trigger a generation request */\n  generate: (input: TInput) => Promise<void>\n  /** The generation result, or null if not yet generated */\n  result: TOutput | null\n  /** Whether a generation is currently in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation client */\n  status: GenerationClientState\n  /** Abort the current generation */\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 * Generic React hook for one-shot generation tasks.\n *\n * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,\n * `useTranscription`, and `useSummarize`. You can also use it directly\n * for custom generation types.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```tsx\n * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({\n *   connection: fetchServerSentEvents('/api/generate/custom'),\n * })\n *\n * await generate({ prompt: 'Hello' })\n * ```\n */\n// `TTransformed` infers from the `onResult` return position (a covariant\n// inference site that works even for an optional nested property), which types\n// the callback parameter as `TResult` and narrows `result`. Inferring the\n// whole callback as a defaulted type parameter instead collapses to the\n// default, leaving the parameter `any` — a hard error under `strict`. See\n// issue #848.\nexport function useGeneration<\n  TInput extends Record<string, any>,\n  TResult,\n  TTransformed = void,\n>(\n  options: Omit<\n    UseGenerationOptions<TInput, TResult>,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerationReturn<\n  InferGenerationOutputFromReturn<TResult, TTransformed>,\n  TInput\n> {\n  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>\n  const hookId = useId()\n  // The hook identity is `threadId`. `hookId` is only a React recreation key.\n  const clientIdentity = options.threadId ?? hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<GenerationClientState>('idle')\n  const [runId, setRunId] = useState<string | null>(null)\n\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const disposedRef = useRef(false)\n\n  const client = useMemo(() => {\n    const opts = optionsRef.current\n\n    // Conditional spread for `body` (strict-optional in target;\n    // local source is `Record<string, any> | undefined`). Callbacks\n    // wrap optional ones in non-returning bodies so `?.()`'s\n    // implicit `undefined` doesn't pollute the function return type.\n    const clientOptions: Omit<\n      GenerationClientOptions<TInput, TResult, TOutput>,\n      'persistence' | 'threadId'\n    > = {\n      body: opts.body,\n      ...(opts.hydrateGeneration !== undefined && {\n        hydrateGeneration: opts.hydrateGeneration,\n      }),\n      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),\n      ...(opts.byok !== undefined && { byok: opts.byok }),\n      byokProvider: () => optionsRef.current.byokProvider?.(),\n      ...(opts.reconstructResult\n        ? { reconstructResult: opts.reconstructResult }\n        : {}),\n      devtoolsBridgeFactory: createGenerationDevtoolsBridge,\n      devtools: {\n        hookName: 'useGeneration',\n        framework: 'react',\n        ...opts.devtools,\n      },\n      // The transform's raw return type (`TTransformed`) and the stored output\n      // (`TOutput`, with null/void/undefined stripped) are identical at runtime;\n      // the cast bridges the relationship that the conditional type hides.\n      onResult: ((r: TResult) => optionsRef.current.onResult?.(r)) as (\n        result: TResult,\n      ) => TOutput | null | void,\n      onError: (e: Error) => {\n        if (!disposedRef.current) optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        if (!disposedRef.current) optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        if (!disposedRef.current) optionsRef.current.onChunk?.(c)\n      },\n      onResultChange: (r) => {\n        if (!disposedRef.current) setResult(r)\n      },\n      onLoadingChange: (l) => {\n        if (!disposedRef.current) setIsLoading(l)\n      },\n      onErrorChange: (e) => {\n        if (!disposedRef.current) setError(e)\n      },\n      onStatusChange: (s) => {\n        if (!disposedRef.current) setStatus(s)\n      },\n      onResumeStateChange: (rs) => {\n        if (!disposedRef.current) setRunId(rs?.runId ?? null)\n      },\n    }\n\n    const persistenceProps =\n      typeof opts.threadId === 'string' && opts.persistence\n        ? {\n            persistence: opts.persistence,\n            threadId: opts.threadId,\n          }\n        : {\n            ...(opts.threadId !== undefined && { threadId: opts.threadId }),\n          }\n\n    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        ...persistenceProps,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        ...persistenceProps,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGeneration requires either a connection or fetcher option',\n    )\n  }, [clientIdentity, hookId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    // Conditional spread: target uses strict-optional `body?: T`.\n    client.updateOptions({\n      ...(options.body !== undefined && { body: options.body }),\n    })\n  }, [client, options.body])\n\n  // Mount devtools and clean up on unmount. Generation runs are never\n  // auto-started on mount — persisted state is only displayed. Mounting\n  // revives the client after a StrictMode dispose → remount replay.\n  useEffect(() => {\n    disposedRef.current = false\n    client.mountDevtools()\n\n    return () => {\n      disposedRef.current = true\n      client.dispose()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: TInput) => {\n      await client.generate(input)\n    },\n    [client],\n  )\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const reset = useCallback(() => {\n    client.reset()\n  }, [client])\n\n  return {\n    generate,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n    runId,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA4JA,SAAgB,cAKd,SASA;CAEA,MAAM,SAAS,MAAM;CAErB,MAAM,iBAAiB,QAAQ,YAAY;CAE3C,MAAM,CAAC,QAAQ,aAAa,SAAyB,IAAI;CACzD,MAAM,CAAC,WAAW,gBAAgB,SAAS,KAAK;CAChD,MAAM,CAAC,OAAO,YAAY,SAA4B,KAAA,CAAS;CAC/D,MAAM,CAAC,QAAQ,aAAa,SAAgC,MAAM;CAClE,MAAM,CAAC,OAAO,YAAY,SAAwB,IAAI;CAEtD,MAAM,aAAa,OAAO,OAAO;CACjC,WAAW,UAAU;CACrB,MAAM,cAAc,OAAO,KAAK;CAEhC,MAAM,SAAS,cAAc;EAC3B,MAAM,OAAO,WAAW;EAMxB,MAAM,gBAGF;GACF,MAAM,KAAK;GACX,GAAI,KAAK,sBAAsB,KAAA,KAAa,EAC1C,mBAAmB,KAAK,kBAC1B;GACA,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,QAAQ;GAC1D,GAAI,KAAK,SAAS,KAAA,KAAa,EAAE,MAAM,KAAK,KAAK;GACjD,oBAAoB,WAAW,QAAQ,eAAe;GACtD,GAAI,KAAK,oBACL,EAAE,mBAAmB,KAAK,kBAAkB,IAC5C,CAAC;GACL,uBAAuB;GACvB,UAAU;IACR,UAAU;IACV,WAAW;IACX,GAAG,KAAK;GACV;GAIA,YAAY,MAAe,WAAW,QAAQ,WAAW,CAAC;GAG1D,UAAU,MAAa;IACrB,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,UAAU,CAAC;GAC1D;GACA,aAAa,GAAW,MAAe;IACrC,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,aAAa,GAAG,CAAC;GAChE;GACA,UAAU,MAAmB;IAC3B,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,UAAU,CAAC;GAC1D;GACA,iBAAiB,MAAM;IACrB,IAAI,CAAC,YAAY,SAAS,UAAU,CAAC;GACvC;GACA,kBAAkB,MAAM;IACtB,IAAI,CAAC,YAAY,SAAS,aAAa,CAAC;GAC1C;GACA,gBAAgB,MAAM;IACpB,IAAI,CAAC,YAAY,SAAS,SAAS,CAAC;GACtC;GACA,iBAAiB,MAAM;IACrB,IAAI,CAAC,YAAY,SAAS,UAAU,CAAC;GACvC;GACA,sBAAsB,OAAO;IAC3B,IAAI,CAAC,YAAY,SAAS,SAAS,IAAI,SAAS,IAAI;GACtD;EACF;EAEA,MAAM,mBACJ,OAAO,KAAK,aAAa,YAAY,KAAK,cACtC;GACE,aAAa,KAAK;GAClB,UAAU,KAAK;EACjB,IACA,EACE,GAAI,KAAK,aAAa,KAAA,KAAa,EAAE,UAAU,KAAK,SAAS,EAC/D;EAEN,IAAI,KAAK,YACP,OAAO,IAAI,iBAA2C;GACpD,GAAG;GACH,GAAG;GACH,YAAY,KAAK;EACnB,CAAC;EAGH,IAAI,KAAK,SACP,OAAO,IAAI,iBAA2C;GACpD,GAAG;GACH,GAAG;GACH,SAAS,KAAK;EAChB,CAAC;EAGH,MAAM,IAAI,MACR,8DACF;CACF,GAAG,CAAC,gBAAgB,MAAM,CAAC;CAG3B,gBAAgB;EAEd,OAAO,cAAc,EACnB,GAAI,QAAQ,SAAS,KAAA,KAAa,EAAE,MAAM,QAAQ,KAAK,EACzD,CAAC;CACH,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;CAKzB,gBAAgB;EACd,YAAY,UAAU;EACtB,OAAO,cAAc;EAErB,aAAa;GACX,YAAY,UAAU;GACtB,OAAO,QAAQ;EACjB;CACF,GAAG,CAAC,MAAM,CAAC;CAiBX,OAAO;EACL,UAhBe,YACf,OAAO,UAAkB;GACvB,MAAM,OAAO,SAAS,KAAK;EAC7B,GACA,CAAC,MAAM,CAYP;EACA;EACA;EACA;EACA;EACA,MAdW,kBAAkB;GAC7B,OAAO,KAAK;EACd,GAAG,CAAC,MAAM,CAYR;EACA,OAXY,kBAAkB;GAC9B,OAAO,MAAM;EACf,GAAG,CAAC,MAAM,CASR;EACA;CACF;AACF"}
+{"version":3,"file":"use-generation.js","names":[],"sources":["../../src/use-generation.ts"],"sourcesContent":["import { GenerationClient } from '@tanstack/ai-client'\nimport { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsClientMetadata,\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  GenerationRestoredResult,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useGeneration hook.\n *\n * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\nexport interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for one-shot generation (no streaming protocol needed) */\n  fetcher?: GenerationFetcher<TInput, TResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 a result is received. 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: TResult) => 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   * @internal Rebuild a typed result from a restored snapshot, injected by each\n   * specialized hook (image / speech / audio / transcription / summarize).\n   * Forwarded to the client so a server-hydrate restore repaints `result`.\n   */\n  reconstructResult?: (restored: GenerationRestoredResult) => TResult | null\n}\n\n/**\n * Return type for the useGeneration hook.\n *\n * @template TOutput - The output type (after optional transform)\n * @template TInput - The input type accepted by `generate` (defaults to any object)\n */\nexport interface UseGenerationReturn<\n  TOutput,\n  TInput extends Record<string, any> = Record<string, any>,\n> {\n  /** Trigger a generation request */\n  generate: (input: TInput) => Promise<void>\n  /** The generation result, or null if not yet generated */\n  result: TOutput | null\n  /** Whether a generation is currently in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation client */\n  status: GenerationClientState\n  /** Abort the current generation */\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 * Generic React hook for one-shot generation tasks.\n *\n * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,\n * `useTranscription`, and `useSummarize`. You can also use it directly\n * for custom generation types.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```tsx\n * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({\n *   connection: fetchServerSentEvents('/api/generate/custom'),\n * })\n *\n * await generate({ prompt: 'Hello' })\n * ```\n */\n// `TTransformed` infers from the `onResult` return position (a covariant\n// inference site that works even for an optional nested property), which types\n// the callback parameter as `TResult` and narrows `result`. Inferring the\n// whole callback as a defaulted type parameter instead collapses to the\n// default, leaving the parameter `any` — a hard error under `strict`. See\n// issue #848.\nexport function useGeneration<\n  TInput extends Record<string, any>,\n  TResult,\n  TTransformed = void,\n>(\n  options: Omit<\n    UseGenerationOptions<TInput, TResult>,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerationReturn<\n  InferGenerationOutputFromReturn<TResult, TTransformed>,\n  TInput\n> {\n  return useGenerationWithDevtoolsIdentity<TInput, TResult, TTransformed>(\n    options,\n    { hookName: 'useGeneration' },\n  )\n}\n\ninterface GenerationDevtoolsIdentity {\n  hookName: AIDevtoolsClientMetadata['hookName']\n  outputKind?: AIDevtoolsClientMetadata['outputKind']\n}\n\n/** @internal */\nexport function useGenerationWithDevtoolsIdentity<\n  TInput extends Record<string, any>,\n  TResult,\n  TTransformed = void,\n>(\n  options: Omit<\n    UseGenerationOptions<TInput, TResult>,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TResult) => TTransformed\n  } & GenerationPersistenceOptions,\n  devtoolsIdentity: GenerationDevtoolsIdentity,\n): UseGenerationReturn<\n  InferGenerationOutputFromReturn<TResult, TTransformed>,\n  TInput\n> {\n  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>\n  const hookId = useId()\n  // The hook identity is `threadId`. `hookId` is only a React recreation key.\n  const clientIdentity = options.threadId ?? hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<GenerationClientState>('idle')\n  const [runId, setRunId] = useState<string | null>(null)\n\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const disposedRef = useRef(false)\n\n  const client = useMemo(() => {\n    const opts = optionsRef.current\n\n    // Conditional spread for `body` (strict-optional in target;\n    // local source is `Record<string, any> | undefined`). Callbacks\n    // wrap optional ones in non-returning bodies so `?.()`'s\n    // implicit `undefined` doesn't pollute the function return type.\n    const clientOptions: Omit<\n      GenerationClientOptions<TInput, TResult, TOutput>,\n      'persistence' | 'threadId'\n    > = {\n      body: opts.body,\n      ...(opts.hydrateGeneration !== undefined && {\n        hydrateGeneration: opts.hydrateGeneration,\n      }),\n      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),\n      ...(opts.byok !== undefined && { byok: opts.byok }),\n      byokProvider: () => optionsRef.current.byokProvider?.(),\n      ...(opts.reconstructResult\n        ? { reconstructResult: opts.reconstructResult }\n        : {}),\n      devtoolsBridgeFactory: createGenerationDevtoolsBridge,\n      devtools: {\n        ...opts.devtools,\n        framework: 'react',\n        hookName: devtoolsIdentity.hookName,\n        ...(devtoolsIdentity.outputKind !== undefined && {\n          outputKind: devtoolsIdentity.outputKind,\n        }),\n      },\n      // The transform's raw return type (`TTransformed`) and the stored output\n      // (`TOutput`, with null/void/undefined stripped) are identical at runtime;\n      // the cast bridges the relationship that the conditional type hides.\n      onResult: ((r: TResult) => optionsRef.current.onResult?.(r)) as (\n        result: TResult,\n      ) => TOutput | null | void,\n      onError: (e: Error) => {\n        if (!disposedRef.current) optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        if (!disposedRef.current) optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        if (!disposedRef.current) optionsRef.current.onChunk?.(c)\n      },\n      onResultChange: (r) => {\n        if (!disposedRef.current) setResult(r)\n      },\n      onLoadingChange: (l) => {\n        if (!disposedRef.current) setIsLoading(l)\n      },\n      onErrorChange: (e) => {\n        if (!disposedRef.current) setError(e)\n      },\n      onStatusChange: (s) => {\n        if (!disposedRef.current) setStatus(s)\n      },\n      onResumeStateChange: (rs) => {\n        if (!disposedRef.current) setRunId(rs?.runId ?? null)\n      },\n    }\n\n    const persistenceProps =\n      typeof opts.threadId === 'string' && opts.persistence\n        ? {\n            persistence: opts.persistence,\n            threadId: opts.threadId,\n          }\n        : {\n            ...(opts.threadId !== undefined && { threadId: opts.threadId }),\n          }\n\n    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        ...persistenceProps,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        ...persistenceProps,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGeneration requires either a connection or fetcher option',\n    )\n  }, [clientIdentity, hookId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    // Conditional spread: target uses strict-optional `body?: T`.\n    client.updateOptions({\n      ...(options.body !== undefined && { body: options.body }),\n    })\n  }, [client, options.body])\n\n  // Mount devtools and clean up on unmount. Generation runs are never\n  // auto-started on mount — persisted state is only displayed. Mounting\n  // revives the client after a StrictMode dispose → remount replay.\n  useEffect(() => {\n    disposedRef.current = false\n    client.mountDevtools()\n\n    return () => {\n      disposedRef.current = true\n      client.dispose()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: TInput) => {\n      await client.generate(input)\n    },\n    [client],\n  )\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const reset = useCallback(() => {\n    client.reset()\n  }, [client])\n\n  return {\n    generate,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n    runId,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA6JA,SAAgB,cAKd,SASA;CACA,OAAO,kCACL,SACA,EAAE,UAAU,gBAAgB,CAC9B;AACF;;AAQA,SAAgB,kCAKd,SAMA,kBAIA;CAEA,MAAM,SAAS,MAAM;CAErB,MAAM,iBAAiB,QAAQ,YAAY;CAE3C,MAAM,CAAC,QAAQ,aAAa,SAAyB,IAAI;CACzD,MAAM,CAAC,WAAW,gBAAgB,SAAS,KAAK;CAChD,MAAM,CAAC,OAAO,YAAY,SAA4B,KAAA,CAAS;CAC/D,MAAM,CAAC,QAAQ,aAAa,SAAgC,MAAM;CAClE,MAAM,CAAC,OAAO,YAAY,SAAwB,IAAI;CAEtD,MAAM,aAAa,OAAO,OAAO;CACjC,WAAW,UAAU;CACrB,MAAM,cAAc,OAAO,KAAK;CAEhC,MAAM,SAAS,cAAc;EAC3B,MAAM,OAAO,WAAW;EAMxB,MAAM,gBAGF;GACF,MAAM,KAAK;GACX,GAAI,KAAK,sBAAsB,KAAA,KAAa,EAC1C,mBAAmB,KAAK,kBAC1B;GACA,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,QAAQ;GAC1D,GAAI,KAAK,SAAS,KAAA,KAAa,EAAE,MAAM,KAAK,KAAK;GACjD,oBAAoB,WAAW,QAAQ,eAAe;GACtD,GAAI,KAAK,oBACL,EAAE,mBAAmB,KAAK,kBAAkB,IAC5C,CAAC;GACL,uBAAuB;GACvB,UAAU;IACR,GAAG,KAAK;IACR,WAAW;IACX,UAAU,iBAAiB;IAC3B,GAAI,iBAAiB,eAAe,KAAA,KAAa,EAC/C,YAAY,iBAAiB,WAC/B;GACF;GAIA,YAAY,MAAe,WAAW,QAAQ,WAAW,CAAC;GAG1D,UAAU,MAAa;IACrB,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,UAAU,CAAC;GAC1D;GACA,aAAa,GAAW,MAAe;IACrC,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,aAAa,GAAG,CAAC;GAChE;GACA,UAAU,MAAmB;IAC3B,IAAI,CAAC,YAAY,SAAS,WAAW,QAAQ,UAAU,CAAC;GAC1D;GACA,iBAAiB,MAAM;IACrB,IAAI,CAAC,YAAY,SAAS,UAAU,CAAC;GACvC;GACA,kBAAkB,MAAM;IACtB,IAAI,CAAC,YAAY,SAAS,aAAa,CAAC;GAC1C;GACA,gBAAgB,MAAM;IACpB,IAAI,CAAC,YAAY,SAAS,SAAS,CAAC;GACtC;GACA,iBAAiB,MAAM;IACrB,IAAI,CAAC,YAAY,SAAS,UAAU,CAAC;GACvC;GACA,sBAAsB,OAAO;IAC3B,IAAI,CAAC,YAAY,SAAS,SAAS,IAAI,SAAS,IAAI;GACtD;EACF;EAEA,MAAM,mBACJ,OAAO,KAAK,aAAa,YAAY,KAAK,cACtC;GACE,aAAa,KAAK;GAClB,UAAU,KAAK;EACjB,IACA,EACE,GAAI,KAAK,aAAa,KAAA,KAAa,EAAE,UAAU,KAAK,SAAS,EAC/D;EAEN,IAAI,KAAK,YACP,OAAO,IAAI,iBAA2C;GACpD,GAAG;GACH,GAAG;GACH,YAAY,KAAK;EACnB,CAAC;EAGH,IAAI,KAAK,SACP,OAAO,IAAI,iBAA2C;GACpD,GAAG;GACH,GAAG;GACH,SAAS,KAAK;EAChB,CAAC;EAGH,MAAM,IAAI,MACR,8DACF;CACF,GAAG,CAAC,gBAAgB,MAAM,CAAC;CAG3B,gBAAgB;EAEd,OAAO,cAAc,EACnB,GAAI,QAAQ,SAAS,KAAA,KAAa,EAAE,MAAM,QAAQ,KAAK,EACzD,CAAC;CACH,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;CAKzB,gBAAgB;EACd,YAAY,UAAU;EACtB,OAAO,cAAc;EAErB,aAAa;GACX,YAAY,UAAU;GACtB,OAAO,QAAQ;EACjB;CACF,GAAG,CAAC,MAAM,CAAC;CAiBX,OAAO;EACL,UAhBe,YACf,OAAO,UAAkB;GACvB,MAAM,OAAO,SAAS,KAAK;EAC7B,GACA,CAAC,MAAM,CAYP;EACA;EACA;EACA;EACA;EACA,MAdW,kBAAkB;GAC7B,OAAO,KAAK;EACd,GAAG,CAAC,MAAM,CAYR;EACA,OAXY,kBAAkB;GAC9B,OAAO,MAAM;EACf,GAAG,CAAC,MAAM,CASR;EACA;CACF;AACF"}

package/dist/esm/use-summarize.js

@@ -1,4 +1,4 @@
-import { useGeneration } from "./use-generation.js";
+import { useGenerationWithDevtoolsIdentity } from "./use-generation.js";
 import { reconstructSummarizeResult } from "@tanstack/ai-client";
 //#region src/use-summarize.ts
 /**
@@ -31,16 +31,12 @@ import { reconstructSummarizeResult } from "@tanstack/ai-client";
 * ```
 */
 function useSummarize(options) {
-	const devtools = {
-		...options.devtools,
-		framework: "react",
-		hookName: "useSummarize",
-		outputKind: "text"
-	};
-	return useGeneration({
+	return useGenerationWithDevtoolsIdentity({
 		...options,
-		devtools,
 		reconstructResult: reconstructSummarizeResult
+	}, {
+		hookName: "useSummarize",
+		outputKind: "text"
 	});
 }
 //#endregion

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

@@ -1 +1 @@
-{"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'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\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  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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'\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgJA,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"}
+{"version":3,"file":"use-summarize.js","names":[],"sources":["../../src/use-summarize.ts"],"sourcesContent":["import { useGenerationWithDevtoolsIdentity } 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'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\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  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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'\n  > & {\n    onResult?: (result: SummarizationResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseSummarizeReturn<\n  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>\n> {\n  const generation = useGenerationWithDevtoolsIdentity<\n    SummarizeGenerateInput,\n    SummarizationResult,\n    TTransformed\n  >(\n    { ...options, reconstructResult: reconstructSummarizeResult },\n    {\n      hookName: 'useSummarize',\n      outputKind: 'text',\n    },\n  )\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgJA,SAAgB,aACd,SAQA;CAaA,OAZmB,kCAKjB;EAAE,GAAG;EAAS,mBAAmB;CAA2B,GAC5D;EACE,UAAU;EACV,YAAY;CACd,CAGK;AACT"}

package/dist/esm/use-transcription.js

@@ -1,4 +1,4 @@
-import { useGeneration } from "./use-generation.js";
+import { useGenerationWithDevtoolsIdentity } from "./use-generation.js";
 import { reconstructTranscriptionResult } from "@tanstack/ai-client";
 //#region src/use-transcription.ts
 /**
@@ -36,16 +36,12 @@ import { reconstructTranscriptionResult } from "@tanstack/ai-client";
 * ```
 */
 function useTranscription(options) {
-	const devtools = {
-		...options.devtools,
-		framework: "react",
-		hookName: "useTranscription",
-		outputKind: "text"
-	};
-	return useGeneration({
+	return useGenerationWithDevtoolsIdentity({
 		...options,
-		devtools,
 		reconstructResult: reconstructTranscriptionResult
+	}, {
+		hookName: "useTranscription",
+		outputKind: "text"
 	});
 }
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"use-transcription.js","names":[],"sources":["../../src/use-transcription.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport { reconstructTranscriptionResult } from '@tanstack/ai-client'\nimport type { StreamChunk, TranscriptionResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  TranscriptionGenerateInput,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useTranscription hook.\n *\n * @template TOutput - The output type after optional transform (defaults to TranscriptionResult)\n */\nexport interface UseTranscriptionOptions<TOutput = TranscriptionResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for transcription */\n  fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 transcription 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: TranscriptionResult) => 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 useTranscription hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseTranscriptionReturn<TOutput = TranscriptionResult> {\n  /** Trigger transcription */\n  generate: (input: TranscriptionGenerateInput) => Promise<void>\n  /** The transcription result, or null */\n  result: TOutput | null\n  /** Whether transcription 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 transcription */\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 transcribing audio to text using AI models.\n *\n * @example\n * ```tsx\n * import { useTranscription } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function Transcriber() {\n *   const { generate, result, isLoading } = useTranscription({\n *     connection: fetchServerSentEvents('/api/transcribe'),\n *   })\n *\n *   const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {\n *     const file = e.target.files?.[0]\n *     if (file) {\n *       const reader = new FileReader()\n *       reader.onload = () => {\n *         generate({ audio: reader.result as string, language: 'en' })\n *       }\n *       reader.readAsDataURL(file)\n *     }\n *   }\n *\n *   return (\n *     <div>\n *       <input type=\"file\" accept=\"audio/*\" onChange={handleFile} />\n *       {isLoading && <p>Transcribing...</p>}\n *       {result && <p>{result.text}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useTranscription<TTransformed = void>(\n  options: Omit<\n    UseTranscriptionOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TranscriptionResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseTranscriptionReturn<\n  InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>\n> {\n  const devtools = {\n    ...options.devtools,\n    framework: 'react',\n    hookName: 'useTranscription',\n    outputKind: 'text' as const,\n  }\n  const generation = useGeneration<\n    TranscriptionGenerateInput,\n    TranscriptionResult,\n    TTransformed\n  >({ ...options, devtools, reconstructResult: reconstructTranscriptionResult })\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqJA,SAAgB,iBACd,SAQA;CACA,MAAM,WAAW;EACf,GAAG,QAAQ;EACX,WAAW;EACX,UAAU;EACV,YAAY;CACd;CAOA,OANmB,cAIjB;EAAE,GAAG;EAAS;EAAU,mBAAmB;CAA+B,CAErE;AACT"}
+{"version":3,"file":"use-transcription.js","names":[],"sources":["../../src/use-transcription.ts"],"sourcesContent":["import { useGenerationWithDevtoolsIdentity } from './use-generation'\nimport { reconstructTranscriptionResult } from '@tanstack/ai-client'\nimport type { StreamChunk, TranscriptionResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  TranscriptionGenerateInput,\n} from '@tanstack/ai-client'\nimport type { ByokClient } from '@tanstack/ai-client/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\n\n/**\n * Options for the useTranscription hook.\n *\n * @template TOutput - The output type after optional transform (defaults to TranscriptionResult)\n */\nexport interface UseTranscriptionOptions<TOutput = TranscriptionResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for transcription */\n  fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */\n  byok?: ByokClient\n  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */\n  byokProvider?: () => ProviderId | undefined\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. If\n   * omitted, the client mints a wire id after mount.\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 transcription 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: TranscriptionResult) => 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 useTranscription hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseTranscriptionReturn<TOutput = TranscriptionResult> {\n  /** Trigger transcription */\n  generate: (input: TranscriptionGenerateInput) => Promise<void>\n  /** The transcription result, or null */\n  result: TOutput | null\n  /** Whether transcription 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 transcription */\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 transcribing audio to text using AI models.\n *\n * @example\n * ```tsx\n * import { useTranscription } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function Transcriber() {\n *   const { generate, result, isLoading } = useTranscription({\n *     connection: fetchServerSentEvents('/api/transcribe'),\n *   })\n *\n *   const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {\n *     const file = e.target.files?.[0]\n *     if (file) {\n *       const reader = new FileReader()\n *       reader.onload = () => {\n *         generate({ audio: reader.result as string, language: 'en' })\n *       }\n *       reader.readAsDataURL(file)\n *     }\n *   }\n *\n *   return (\n *     <div>\n *       <input type=\"file\" accept=\"audio/*\" onChange={handleFile} />\n *       {isLoading && <p>Transcribing...</p>}\n *       {result && <p>{result.text}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useTranscription<TTransformed = void>(\n  options: Omit<\n    UseTranscriptionOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: TranscriptionResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseTranscriptionReturn<\n  InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>\n> {\n  const generation = useGenerationWithDevtoolsIdentity<\n    TranscriptionGenerateInput,\n    TranscriptionResult,\n    TTransformed\n  >(\n    { ...options, reconstructResult: reconstructTranscriptionResult },\n    {\n      hookName: 'useTranscription',\n      outputKind: 'text',\n    },\n  )\n\n  return generation\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqJA,SAAgB,iBACd,SAQA;CAaA,OAZmB,kCAKjB;EAAE,GAAG;EAAS,mBAAmB;CAA+B,GAChE;EACE,UAAU;EACV,YAAY;CACd,CAGK;AACT"}

package/dist/esm/use-web-mcp-tools.d.ts

@@ -1,12 +1,14 @@
-import { AnyClientTool, InferredClientContext, RegisterWebMCPToolsOptions } from '@tanstack/ai-client';
-/** Options for the React {@link useWebMCPTools} lifecycle hook. */
-export type UseWebMCPToolsOptions<TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
+import { AnyClientTool, InferredClientContext, RegisterWebMCPToolsOptions, SubscribeWebMCPToolsOptions } from '@tanstack/ai-client';
+/** Options for the React {@link useRegisterWebMCPTools} lifecycle hook. */
+export type UseRegisterWebMCPToolsOptions<TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
     /** Receives an asynchronous registration failure. */
     onError?: (error: unknown) => void;
 };
-type UseWebMCPToolsArguments<TTools extends ReadonlyArray<AnyClientTool>, TContext> = RegisterWebMCPToolsOptions<TTools, TContext> extends {
+/** @deprecated Use `UseRegisterWebMCPToolsOptions`. Removed in 1.0.0. */
+export type UseWebMCPToolsOptions<TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>> = UseRegisterWebMCPToolsOptions<TTools, TContext>;
+type UseRegisterWebMCPToolsArguments<TTools extends ReadonlyArray<AnyClientTool>, TContext> = RegisterWebMCPToolsOptions<TTools, TContext> extends {
     context: unknown;
-} ? [options: UseWebMCPToolsOptions<TTools, TContext>] : [options?: UseWebMCPToolsOptions<TTools, TContext>];
+} ? [options: UseRegisterWebMCPToolsOptions<TTools, TContext>] : [options?: UseRegisterWebMCPToolsOptions<TTools, TContext>];
 /**
  * Registers client tools with WebMCP for the lifetime of a React component.
  *
@@ -18,10 +20,35 @@ type UseWebMCPToolsArguments<TTools extends ReadonlyArray<AnyClientTool>, TConte
  *
  * @example
  * ```tsx
- * useWebMCPTools([searchProducts], {
+ * useRegisterWebMCPTools([searchProducts], {
  *   toolOptions: { searchProducts: { title: 'Search products' } },
  * })
  * ```
  */
-export declare function useWebMCPTools<const TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>>(tools: TTools, ...[options]: UseWebMCPToolsArguments<TTools, TContext>): void;
+export declare function useRegisterWebMCPTools<const TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>>(tools: TTools, ...[options]: UseRegisterWebMCPToolsArguments<TTools, TContext>): void;
+/**
+ * @deprecated Use `useRegisterWebMCPTools`. Removed in 1.0.0.
+ * @alias
+ */
+export declare const useWebMCPTools: typeof useRegisterWebMCPTools;
+/** Options for {@link usePageWebMCPTools}. */
+export type UsePageWebMCPToolsOptions = Omit<SubscribeWebMCPToolsOptions, 'signal'>;
+/**
+ * Returns the WebMCP tools on the page as client tools for `useChat`.
+ *
+ * The list starts empty and updates when the page registers or removes a
+ * tool. The hook reads the latest `filter` and `onError` on each update.
+ * Unsupported browsers and server rendering return an empty array.
+ *
+ * @param options - A filter that skips tools, and an error callback.
+ *
+ * @example
+ * ```tsx
+ * const pageTools = usePageWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * const chat = useChat({ connection, tools: pageTools })
+ * ```
+ */
+export declare function usePageWebMCPTools(options?: UsePageWebMCPToolsOptions): Array<AnyClientTool>;
 export {};

package/dist/esm/use-web-mcp-tools.js

@@ -1,5 +1,5 @@
-import { registerWebMCPTools } from "@tanstack/ai-client";
-import { useEffect } from "react";
+import { registerWebMCPTools, subscribeWebMCPTools } from "@tanstack/ai-client";
+import { useEffect, useRef, useState } from "react";
 //#region src/use-web-mcp-tools.ts
 /**
 * Registers client tools with WebMCP for the lifetime of a React component.
@@ -12,12 +12,12 @@ import { useEffect } from "react";
 *
 * @example
 * ```tsx
-* useWebMCPTools([searchProducts], {
+* useRegisterWebMCPTools([searchProducts], {
 *   toolOptions: { searchProducts: { title: 'Search products' } },
 * })
 * ```
 */
-function useWebMCPTools(tools, ...[options]) {
+function useRegisterWebMCPTools(tools, ...[options]) {
 	useEffect(() => {
 		const controller = new AbortController();
 		const { onError, ...registrationOptions } = options ?? {};
@@ -30,7 +30,44 @@ function useWebMCPTools(tools, ...[options]) {
 		return () => controller.abort();
 	}, [tools, options]);
 }
+/**
+* @deprecated Use `useRegisterWebMCPTools`. Removed in 1.0.0.
+* @alias
+*/
+var useWebMCPTools = useRegisterWebMCPTools;
+/**
+* Returns the WebMCP tools on the page as client tools for `useChat`.
+*
+* The list starts empty and updates when the page registers or removes a
+* tool. The hook reads the latest `filter` and `onError` on each update.
+* Unsupported browsers and server rendering return an empty array.
+*
+* @param options - A filter that skips tools, and an error callback.
+*
+* @example
+* ```tsx
+* const pageTools = usePageWebMCPTools({
+*   filter: (tool) => tool.origin === location.origin,
+* })
+* const chat = useChat({ connection, tools: pageTools })
+* ```
+*/
+function usePageWebMCPTools(options) {
+	const [tools, setTools] = useState([]);
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	useEffect(() => {
+		const controller = new AbortController();
+		subscribeWebMCPTools(setTools, {
+			signal: controller.signal,
+			filter: (tool) => optionsRef.current?.filter?.(tool) ?? true,
+			onError: (error) => optionsRef.current?.onError?.(error)
+		});
+		return () => controller.abort();
+	}, []);
+	return tools;
+}
 //#endregion
-export { useWebMCPTools };
+export { usePageWebMCPTools, useRegisterWebMCPTools, useWebMCPTools };
 
 //# sourceMappingURL=use-web-mcp-tools.js.map

package/dist/esm/use-web-mcp-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-web-mcp-tools.js","names":[],"sources":["../../src/use-web-mcp-tools.ts"],"sourcesContent":["import { useEffect } from 'react'\nimport { registerWebMCPTools } from '@tanstack/ai-client'\nimport type {\n  AnyClientTool,\n  InferredClientContext,\n  RegisterWebMCPToolsOptions,\n} from '@tanstack/ai-client'\n\n/** Options for the React {@link useWebMCPTools} lifecycle hook. */\nexport type UseWebMCPToolsOptions<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {\n  /** Receives an asynchronous registration failure. */\n  onError?: (error: unknown) => void\n}\n\ntype UseWebMCPToolsArguments<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext,\n> =\n  RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }\n    ? [options: UseWebMCPToolsOptions<TTools, TContext>]\n    : [options?: UseWebMCPToolsOptions<TTools, TContext>]\n\n/**\n * Registers client tools with WebMCP for the lifetime of a React component.\n *\n * The hook replaces the registration when `tools` or `options` changes.\n * Unsupported browsers and server rendering do not register tools.\n *\n * @param tools - The executable client tools to expose through WebMCP.\n * @param options - Runtime context, per-tool options, and an error callback.\n *\n * @example\n * ```tsx\n * useWebMCPTools([searchProducts], {\n *   toolOptions: { searchProducts: { title: 'Search products' } },\n * })\n * ```\n */\nexport function useWebMCPTools<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(tools: TTools, ...[options]: UseWebMCPToolsArguments<TTools, TContext>) {\n  useEffect(() => {\n    const controller = new AbortController()\n    const { onError, ...registrationOptions } = options ?? {}\n\n    registerWebMCPTools(tools, {\n      ...registrationOptions,\n      signal: controller.signal,\n    }).catch((error) => {\n      if (!controller.signal.aborted) onError?.(error)\n    })\n\n    return () => controller.abort()\n  }, [tools, options])\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,eAGd,OAAe,GAAG,CAAC,UAAqD;CACxE,gBAAgB;EACd,MAAM,aAAa,IAAI,gBAAgB;EACvC,MAAM,EAAE,SAAS,GAAG,wBAAwB,WAAW,CAAC;EAExD,oBAAoB,OAAO;GACzB,GAAG;GACH,QAAQ,WAAW;EACrB,CAAC,CAAC,CAAC,OAAO,UAAU;GAClB,IAAI,CAAC,WAAW,OAAO,SAAS,UAAU,KAAK;EACjD,CAAC;EAED,aAAa,WAAW,MAAM;CAChC,GAAG,CAAC,OAAO,OAAO,CAAC;AACrB"}
+{"version":3,"file":"use-web-mcp-tools.js","names":[],"sources":["../../src/use-web-mcp-tools.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react'\nimport { registerWebMCPTools, subscribeWebMCPTools } from '@tanstack/ai-client'\nimport type {\n  AnyClientTool,\n  InferredClientContext,\n  RegisterWebMCPToolsOptions,\n  SubscribeWebMCPToolsOptions,\n} from '@tanstack/ai-client'\n\n/** Options for the React {@link useRegisterWebMCPTools} lifecycle hook. */\nexport type UseRegisterWebMCPToolsOptions<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n> = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {\n  /** Receives an asynchronous registration failure. */\n  onError?: (error: unknown) => void\n}\n\n/** @deprecated Use `UseRegisterWebMCPToolsOptions`. Removed in 1.0.0. */\nexport type UseWebMCPToolsOptions<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n> = UseRegisterWebMCPToolsOptions<TTools, TContext>\n\ntype UseRegisterWebMCPToolsArguments<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext,\n> =\n  RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }\n    ? [options: UseRegisterWebMCPToolsOptions<TTools, TContext>]\n    : [options?: UseRegisterWebMCPToolsOptions<TTools, TContext>]\n\n/**\n * Registers client tools with WebMCP for the lifetime of a React component.\n *\n * The hook replaces the registration when `tools` or `options` changes.\n * Unsupported browsers and server rendering do not register tools.\n *\n * @param tools - The executable client tools to expose through WebMCP.\n * @param options - Runtime context, per-tool options, and an error callback.\n *\n * @example\n * ```tsx\n * useRegisterWebMCPTools([searchProducts], {\n *   toolOptions: { searchProducts: { title: 'Search products' } },\n * })\n * ```\n */\nexport function useRegisterWebMCPTools<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(\n  tools: TTools,\n  ...[options]: UseRegisterWebMCPToolsArguments<TTools, TContext>\n) {\n  useEffect(() => {\n    const controller = new AbortController()\n    const { onError, ...registrationOptions } = options ?? {}\n\n    registerWebMCPTools(tools, {\n      ...registrationOptions,\n      signal: controller.signal,\n    }).catch((error) => {\n      if (!controller.signal.aborted) onError?.(error)\n    })\n\n    return () => controller.abort()\n  }, [tools, options])\n}\n\n/**\n * @deprecated Use `useRegisterWebMCPTools`. Removed in 1.0.0.\n * @alias\n */\nexport const useWebMCPTools = useRegisterWebMCPTools\n\n/** Options for {@link usePageWebMCPTools}. */\nexport type UsePageWebMCPToolsOptions = Omit<\n  SubscribeWebMCPToolsOptions,\n  'signal'\n>\n\n/**\n * Returns the WebMCP tools on the page as client tools for `useChat`.\n *\n * The list starts empty and updates when the page registers or removes a\n * tool. The hook reads the latest `filter` and `onError` on each update.\n * Unsupported browsers and server rendering return an empty array.\n *\n * @param options - A filter that skips tools, and an error callback.\n *\n * @example\n * ```tsx\n * const pageTools = usePageWebMCPTools({\n *   filter: (tool) => tool.origin === location.origin,\n * })\n * const chat = useChat({ connection, tools: pageTools })\n * ```\n */\nexport function usePageWebMCPTools(\n  options?: UsePageWebMCPToolsOptions,\n): Array<AnyClientTool> {\n  const [tools, setTools] = useState<Array<AnyClientTool>>([])\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n\n  useEffect(() => {\n    const controller = new AbortController()\n    subscribeWebMCPTools(setTools, {\n      signal: controller.signal,\n      filter: (tool) => optionsRef.current?.filter?.(tool) ?? true,\n      onError: (error) => optionsRef.current?.onError?.(error),\n    })\n    return () => controller.abort()\n  }, [])\n\n  return tools\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,uBAId,OACA,GAAG,CAAC,UACJ;CACA,gBAAgB;EACd,MAAM,aAAa,IAAI,gBAAgB;EACvC,MAAM,EAAE,SAAS,GAAG,wBAAwB,WAAW,CAAC;EAExD,oBAAoB,OAAO;GACzB,GAAG;GACH,QAAQ,WAAW;EACrB,CAAC,CAAC,CAAC,OAAO,UAAU;GAClB,IAAI,CAAC,WAAW,OAAO,SAAS,UAAU,KAAK;EACjD,CAAC;EAED,aAAa,WAAW,MAAM;CAChC,GAAG,CAAC,OAAO,OAAO,CAAC;AACrB;;;;;AAMA,IAAa,iBAAiB;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,mBACd,SACsB;CACtB,MAAM,CAAC,OAAO,YAAY,SAA+B,CAAC,CAAC;CAC3D,MAAM,aAAa,OAAO,OAAO;CACjC,WAAW,UAAU;CAErB,gBAAgB;EACd,MAAM,aAAa,IAAI,gBAAgB;EACvC,qBAAqB,UAAU;GAC7B,QAAQ,WAAW;GACnB,SAAS,SAAS,WAAW,SAAS,SAAS,IAAI,KAAK;GACxD,UAAU,UAAU,WAAW,SAAS,UAAU,KAAK;EACzD,CAAC;EACD,aAAa,WAAW,MAAM;CAChC,GAAG,CAAC,CAAC;CAEL,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-react",
-  "version": "0.28.0",
+  "version": "0.29.3",
   "description": "React hooks for TanStack AI streaming chat, realtime voice, structured outputs, and media generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -58,14 +58,14 @@
   ],
   "dependencies": {
     "@tanstack/markdown": "^0.0.13",
-    "@tanstack/ai-client": "^0.34.0"
+    "@tanstack/ai-client": "^0.36.0"
   },
   "peerDependencies": {
     "@mcp-ui/client": "^7",
     "@types/react": ">=18.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "@tanstack/ai": "^0.59.0"
+    "@tanstack/ai": "^0.63.0"
   },
   "peerDependenciesMeta": {
     "@mcp-ui/client": {
@@ -85,12 +85,13 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.59.0"
+    "@tanstack/ai": "0.63.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",
     "lint:fix": "oxlint src --type-aware --fix",
     "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "test:lib": "vitest run",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc",

package/src/index.ts

@@ -4,8 +4,16 @@ export { useByok } from './use-byok'
 export { useRealtimeChat } from './use-realtime-chat'
 export { useMcpAppBridge } from './use-mcp-app-bridge'
 export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge'
-export { useWebMCPTools } from './use-web-mcp-tools'
-export type { UseWebMCPToolsOptions } from './use-web-mcp-tools'
+export {
+  usePageWebMCPTools,
+  useRegisterWebMCPTools,
+  useWebMCPTools,
+} from './use-web-mcp-tools'
+export type {
+  UsePageWebMCPToolsOptions,
+  UseRegisterWebMCPToolsOptions,
+  UseWebMCPToolsOptions,
+} from './use-web-mcp-tools'
 export type {
   DeepPartial,
   UseChatOptions,
@@ -105,6 +113,11 @@ export {
   PartialJSONParser,
   defaultJSONParser,
   registerWebMCPTools,
+  getWebMCPTools,
+  subscribeWebMCPTools,
+  type GetWebMCPToolsOptions,
+  type SubscribeWebMCPToolsOptions,
+  type WebMCPPageTool,
   clientTools,
   fetchServerSentEvents,
   localStoragePersistence,

package/src/use-generate-audio.ts

@@ -1,4 +1,4 @@
-import { useGeneration } from './use-generation'
+import { useGenerationWithDevtoolsIdentity } from './use-generation'
 import { reconstructAudioResult } from '@tanstack/ai-client'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
@@ -153,21 +153,17 @@ export function useGenerateAudio<TTransformed = void>(
 ): UseGenerateAudioReturn<
   InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
 > {
-  const devtools = {
-    ...options.devtools,
-    framework: 'react',
-    hookName: 'useGenerateAudio',
-    outputKind: 'audio' as const,
-  }
-  const generation = useGeneration<
+  const generation = useGenerationWithDevtoolsIdentity<
     AudioGenerateInput,
     AudioGenerationResult,
     TTransformed
-  >({
-    ...options,
-    devtools,
-    reconstructResult: reconstructAudioResult,
-  })
+  >(
+    { ...options, reconstructResult: reconstructAudioResult },
+    {
+      hookName: 'useGenerateAudio',
+      outputKind: 'audio',
+    },
+  )
 
   return generation
 }

package/src/use-generate-image.ts

@@ -1,4 +1,4 @@
-import { useGeneration } from './use-generation'
+import { useGenerationWithDevtoolsIdentity } from './use-generation'
 import { reconstructImageResult } from '@tanstack/ai-client'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
@@ -155,21 +155,17 @@ export function useGenerateImage<TTransformed = void>(
 ): UseGenerateImageReturn<
   InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
 > {
-  const devtools = {
-    ...options.devtools,
-    framework: 'react',
-    hookName: 'useGenerateImage',
-    outputKind: 'image' as const,
-  }
-  const generation = useGeneration<
+  const generation = useGenerationWithDevtoolsIdentity<
     ImageGenerateInput,
     ImageGenerationResult,
     TTransformed
-  >({
-    ...options,
-    devtools,
-    reconstructResult: reconstructImageResult,
-  })
+  >(
+    { ...options, reconstructResult: reconstructImageResult },
+    {
+      hookName: 'useGenerateImage',
+      outputKind: 'image',
+    },
+  )
 
   return generation
 }

package/src/use-generate-speech.ts

@@ -1,4 +1,4 @@
-import { useGeneration } from './use-generation'
+import { useGenerationWithDevtoolsIdentity } from './use-generation'
 import { reconstructSpeechResult } from '@tanstack/ai-client'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
@@ -149,21 +149,17 @@ export function useGenerateSpeech<TTransformed = void>(
 ): UseGenerateSpeechReturn<
   InferGenerationOutputFromReturn<TTSResult, TTransformed>
 > {
-  const devtools = {
-    ...options.devtools,
-    framework: 'react',
-    hookName: 'useGenerateSpeech',
-    outputKind: 'audio' as const,
-  }
-  const generation = useGeneration<
+  const generation = useGenerationWithDevtoolsIdentity<
     SpeechGenerateInput,
     TTSResult,
     TTransformed
-  >({
-    ...options,
-    devtools,
-    reconstructResult: reconstructSpeechResult,
-  })
+  >(
+    { ...options, reconstructResult: reconstructSpeechResult },
+    {
+      hookName: 'useGenerateSpeech',
+      outputKind: 'audio',
+    },
+  )
 
   return generation
 }

package/src/use-generation.ts

@@ -3,6 +3,7 @@ import { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import type { StreamChunk } from '@tanstack/ai'
 import type {
+  AIDevtoolsClientMetadata,
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientOptions,
@@ -168,6 +169,34 @@ export function useGeneration<
 ): UseGenerationReturn<
   InferGenerationOutputFromReturn<TResult, TTransformed>,
   TInput
+> {
+  return useGenerationWithDevtoolsIdentity<TInput, TResult, TTransformed>(
+    options,
+    { hookName: 'useGeneration' },
+  )
+}
+
+interface GenerationDevtoolsIdentity {
+  hookName: AIDevtoolsClientMetadata['hookName']
+  outputKind?: AIDevtoolsClientMetadata['outputKind']
+}
+
+/** @internal */
+export function useGenerationWithDevtoolsIdentity<
+  TInput extends Record<string, any>,
+  TResult,
+  TTransformed = void,
+>(
+  options: Omit<
+    UseGenerationOptions<TInput, TResult>,
+    'onResult' | 'persistence' | 'threadId'
+  > & {
+    onResult?: (result: TResult) => TTransformed
+  } & GenerationPersistenceOptions,
+  devtoolsIdentity: GenerationDevtoolsIdentity,
+): UseGenerationReturn<
+  InferGenerationOutputFromReturn<TResult, TTransformed>,
+  TInput
 > {
   type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
   const hookId = useId()
@@ -207,9 +236,12 @@ export function useGeneration<
         : {}),
       devtoolsBridgeFactory: createGenerationDevtoolsBridge,
       devtools: {
-        hookName: 'useGeneration',
-        framework: 'react',
         ...opts.devtools,
+        framework: 'react',
+        hookName: devtoolsIdentity.hookName,
+        ...(devtoolsIdentity.outputKind !== undefined && {
+          outputKind: devtoolsIdentity.outputKind,
+        }),
       },
       // The transform's raw return type (`TTransformed`) and the stored output
       // (`TOutput`, with null/void/undefined stripped) are identical at runtime;

package/src/use-summarize.ts

@@ -1,4 +1,4 @@
-import { useGeneration } from './use-generation'
+import { useGenerationWithDevtoolsIdentity } from './use-generation'
 import { reconstructSummarizeResult } from '@tanstack/ai-client'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
@@ -152,21 +152,17 @@ export function useSummarize<TTransformed = void>(
 ): UseSummarizeReturn<
   InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
 > {
-  const devtools = {
-    ...options.devtools,
-    framework: 'react',
-    hookName: 'useSummarize',
-    outputKind: 'text' as const,
-  }
-  const generation = useGeneration<
+  const generation = useGenerationWithDevtoolsIdentity<
     SummarizeGenerateInput,
     SummarizationResult,
     TTransformed
-  >({
-    ...options,
-    devtools,
-    reconstructResult: reconstructSummarizeResult,
-  })
+  >(
+    { ...options, reconstructResult: reconstructSummarizeResult },
+    {
+      hookName: 'useSummarize',
+      outputKind: 'text',
+    },
+  )
 
   return generation
 }

package/src/use-transcription.ts

@@ -1,4 +1,4 @@
-import { useGeneration } from './use-generation'
+import { useGenerationWithDevtoolsIdentity } from './use-generation'
 import { reconstructTranscriptionResult } from '@tanstack/ai-client'
 import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
 import type {
@@ -157,17 +157,17 @@ export function useTranscription<TTransformed = void>(
 ): UseTranscriptionReturn<
   InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>
 > {
-  const devtools = {
-    ...options.devtools,
-    framework: 'react',
-    hookName: 'useTranscription',
-    outputKind: 'text' as const,
-  }
-  const generation = useGeneration<
+  const generation = useGenerationWithDevtoolsIdentity<
     TranscriptionGenerateInput,
     TranscriptionResult,
     TTransformed
-  >({ ...options, devtools, reconstructResult: reconstructTranscriptionResult })
+  >(
+    { ...options, reconstructResult: reconstructTranscriptionResult },
+    {
+      hookName: 'useTranscription',
+      outputKind: 'text',
+    },
+  )
 
   return generation
 }

package/src/use-web-mcp-tools.ts

@@ -1,13 +1,14 @@
-import { useEffect } from 'react'
-import { registerWebMCPTools } from '@tanstack/ai-client'
+import { useEffect, useRef, useState } from 'react'
+import { registerWebMCPTools, subscribeWebMCPTools } from '@tanstack/ai-client'
 import type {
   AnyClientTool,
   InferredClientContext,
   RegisterWebMCPToolsOptions,
+  SubscribeWebMCPToolsOptions,
 } from '@tanstack/ai-client'
 
-/** Options for the React {@link useWebMCPTools} lifecycle hook. */
-export type UseWebMCPToolsOptions<
+/** Options for the React {@link useRegisterWebMCPTools} lifecycle hook. */
+export type UseRegisterWebMCPToolsOptions<
   TTools extends ReadonlyArray<AnyClientTool>,
   TContext = InferredClientContext<TTools>,
 > = Omit<RegisterWebMCPToolsOptions<TTools, TContext>, 'signal'> & {
@@ -15,13 +16,19 @@ export type UseWebMCPToolsOptions<
   onError?: (error: unknown) => void
 }
 
-type UseWebMCPToolsArguments<
+/** @deprecated Use `UseRegisterWebMCPToolsOptions`. Removed in 1.0.0. */
+export type UseWebMCPToolsOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+> = UseRegisterWebMCPToolsOptions<TTools, TContext>
+
+type UseRegisterWebMCPToolsArguments<
   TTools extends ReadonlyArray<AnyClientTool>,
   TContext,
 > =
   RegisterWebMCPToolsOptions<TTools, TContext> extends { context: unknown }
-    ? [options: UseWebMCPToolsOptions<TTools, TContext>]
-    : [options?: UseWebMCPToolsOptions<TTools, TContext>]
+    ? [options: UseRegisterWebMCPToolsOptions<TTools, TContext>]
+    : [options?: UseRegisterWebMCPToolsOptions<TTools, TContext>]
 
 /**
  * Registers client tools with WebMCP for the lifetime of a React component.
@@ -34,15 +41,18 @@ type UseWebMCPToolsArguments<
  *
  * @example
  * ```tsx
- * useWebMCPTools([searchProducts], {
+ * useRegisterWebMCPTools([searchProducts], {
  *   toolOptions: { searchProducts: { title: 'Search products' } },
  * })
  * ```
  */
-export function useWebMCPTools<
+export function useRegisterWebMCPTools<
   const TTools extends ReadonlyArray<AnyClientTool>,
   TContext = InferredClientContext<TTools>,
->(tools: TTools, ...[options]: UseWebMCPToolsArguments<TTools, TContext>) {
+>(
+  tools: TTools,
+  ...[options]: UseRegisterWebMCPToolsArguments<TTools, TContext>
+) {
   useEffect(() => {
     const controller = new AbortController()
     const { onError, ...registrationOptions } = options ?? {}
@@ -57,3 +67,52 @@ export function useWebMCPTools<
     return () => controller.abort()
   }, [tools, options])
 }
+
+/**
+ * @deprecated Use `useRegisterWebMCPTools`. Removed in 1.0.0.
+ * @alias
+ */
+export const useWebMCPTools = useRegisterWebMCPTools
+
+/** Options for {@link usePageWebMCPTools}. */
+export type UsePageWebMCPToolsOptions = Omit<
+  SubscribeWebMCPToolsOptions,
+  'signal'
+>
+
+/**
+ * Returns the WebMCP tools on the page as client tools for `useChat`.
+ *
+ * The list starts empty and updates when the page registers or removes a
+ * tool. The hook reads the latest `filter` and `onError` on each update.
+ * Unsupported browsers and server rendering return an empty array.
+ *
+ * @param options - A filter that skips tools, and an error callback.
+ *
+ * @example
+ * ```tsx
+ * const pageTools = usePageWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * const chat = useChat({ connection, tools: pageTools })
+ * ```
+ */
+export function usePageWebMCPTools(
+  options?: UsePageWebMCPToolsOptions,
+): Array<AnyClientTool> {
+  const [tools, setTools] = useState<Array<AnyClientTool>>([])
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  useEffect(() => {
+    const controller = new AbortController()
+    subscribeWebMCPTools(setTools, {
+      signal: controller.signal,
+      filter: (tool) => optionsRef.current?.filter?.(tool) ?? true,
+      onError: (error) => optionsRef.current?.onError?.(error),
+    })
+    return () => controller.abort()
+  }, [])
+
+  return tools
+}