@tanstack/ai-react 0.19.3 → 0.21.1

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'\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  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when 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' | 'id'\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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-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'\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  /** 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6IA,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"}

package/dist/esm/use-generate-speech.d.ts

@@ -10,10 +10,6 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for speech generation */
     fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>;
-    /**
-     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-     */
-    id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
@@ -37,8 +33,8 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
      * id on the wire, which the protocol requires.
      *
      * **Required whenever `persistence` is set** — an app that cannot name the
-     * scope has nothing to restore to. Optional for ephemeral generations, where
-     * it falls back to `id` purely to satisfy the wire.
+     * scope has nothing to restore to. Optional for ephemeral generations. If
+     * omitted, the client mints a wire id after mount.
      */
     threadId?: string;
     /**
@@ -124,6 +120,6 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
  * }
  * ```
  */
-export declare function useGenerateSpeech<TTransformed = void>(options: Omit<UseGenerateSpeechOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+export declare function useGenerateSpeech<TTransformed = void>(options: Omit<UseGenerateSpeechOptions, 'onResult' | 'persistence' | 'threadId'> & {
     onResult?: (result: TTSResult) => TTransformed;
 } & GenerationPersistenceOptions): UseGenerateSpeechReturn<InferGenerationOutputFromReturn<TTSResult, TTransformed>>;

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'\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  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when 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' | 'id'\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2IA,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 { 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'\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  /** 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuIA,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"}

package/dist/esm/use-generate-video.d.ts

@@ -8,10 +8,6 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function that returns a completed video result */
     fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>;
-    /**
-     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-     */
-    id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
@@ -35,8 +31,8 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
      * id on the wire, which the protocol requires.
      *
      * **Required whenever `persistence` is set** — an app that cannot name the
-     * scope has nothing to restore to. Optional for ephemeral generations, where
-     * it falls back to `id` purely to satisfy the wire.
+     * scope has nothing to restore to. Optional for ephemeral generations. If
+     * omitted, the client mints a wire id after mount.
      */
     threadId?: string;
     /**
@@ -135,6 +131,6 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
  * }
  * ```
  */
-export declare function useGenerateVideo<TTransformed = void>(options: Omit<UseGenerateVideoOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+export declare function useGenerateVideo<TTransformed = void>(options: Omit<UseGenerateVideoOptions, 'onResult' | 'persistence' | 'threadId'> & {
     onResult?: (result: VideoGenerateResult) => TTransformed;
 } & GenerationPersistenceOptions): UseGenerateVideoReturn<InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>>;

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

@@ -35,7 +35,7 @@ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 */
 function useGenerateVideo(options) {
 	const hookId = useId();
-	const clientIdentity = options.threadId ?? options.id ?? hookId;
+	const clientIdentity = options.threadId ?? hookId;
 	const [result, setResult] = useState(null);
 	const [jobId, setJobId] = useState(null);
 	const [videoStatus, setVideoStatus] = useState(null);
@@ -50,8 +50,6 @@ function useGenerateVideo(options) {
 		const opts = optionsRef.current;
 		const baseOptions = {
 			body: opts.body,
-			...opts.threadId !== void 0 ? { threadId: opts.threadId } : { id: opts.id ?? hookId },
-			...opts.persistence !== void 0 && { persistence: opts.persistence },
 			...opts.hydrateGeneration !== void 0 && { hydrateGeneration: opts.hydrateGeneration },
 			...opts.joinRun !== void 0 && { joinRun: opts.joinRun },
 			devtoolsBridgeFactory: createVideoDevtoolsBridge,
@@ -99,12 +97,18 @@ function useGenerateVideo(options) {
 				if (!disposedRef.current) setRunId(rs?.runId ?? null);
 			}
 		};
+		const persistenceProps = typeof opts.threadId === "string" && opts.persistence ? {
+			persistence: opts.persistence,
+			threadId: opts.threadId
+		} : { ...opts.threadId !== void 0 && { threadId: opts.threadId } };
 		if (opts.connection) return new VideoGenerationClient({
 			...baseOptions,
+			...persistenceProps,
 			connection: opts.connection
 		});
 		if (opts.fetcher) return new VideoGenerationClient({
 			...baseOptions,
+			...persistenceProps,
 			fetcher: opts.fetcher
 		});
 		throw new Error("useGenerateVideo requires either a connection or fetcher option");

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

@@ -1 +1 @@
-{"version":3,"file":"use-generate-video.js","names":[],"sources":["../../src/use-generate-video.ts"],"sourcesContent":["import { VideoGenerationClient } from '@tanstack/ai-client'\nimport { createVideoDevtoolsBridge } 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  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  VideoGenerateInput,\n  VideoGenerateResult,\n  VideoStatusInfo,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGenerateVideo hook.\n */\nexport interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {\n  /** Connect-based adapter for streaming transport (server handles polling) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function that returns a completed video result */\n  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>\n  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when video generation completes. 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: VideoGenerateResult) => 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 when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => 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 useGenerateVideo hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {\n  /** Trigger video generation */\n  generate: (input: VideoGenerateInput) => Promise<void>\n  /** The final video result (with URL), or null */\n  result: TOutput | null\n  /** The current job ID, or null */\n  jobId: string | null\n  /** Current video generation status info, or null */\n  videoStatus: VideoStatusInfo | null\n  /** Whether generation/polling 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/polling */\n  stop: () => void\n  /** Clear all state 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 videos using AI models.\n *\n * Video generation is asynchronous: a job is created, then polled for status\n * until completion. This hook handles the full lifecycle.\n *\n * @example\n * ```tsx\n * import { useGenerateVideo } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function VideoGenerator() {\n *   const { generate, result, videoStatus, isLoading } = useGenerateVideo({\n *     connection: fetchServerSentEvents('/api/generate/video'),\n *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>\n *         Generate Video\n *       </button>\n *       {isLoading && videoStatus && (\n *         <p>Status: {videoStatus.status} ({videoStatus.progress}%)</p>\n *       )}\n *       {result && <video src={result.url} controls />}\n *     </div>\n *   )\n * }\n * ```\n */\n// `TTransformed` infers from the `onResult` return position so the callback\n// parameter is typed as `VideoGenerateResult` and `result` narrows to the\n// transform's return. See issue #848.\nexport function useGenerateVideo<TTransformed = void>(\n  options: Omit<\n    UseGenerateVideoOptions,\n    'onResult' | 'persistence' | 'threadId' | 'id'\n  > & {\n    onResult?: (result: VideoGenerateResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateVideoReturn<\n  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>\n> {\n  type TOutput = InferGenerationOutputFromReturn<\n    VideoGenerateResult,\n    TTransformed\n  >\n  const hookId = useId()\n  // Single identity: prefer `threadId`; deprecated `id` only when no threadId.\n  const clientIdentity = options.threadId ?? options.id ?? hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [jobId, setJobId] = useState<string | null>(null)\n  const [videoStatus, setVideoStatus] = useState<VideoStatusInfo | 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    // Optional callbacks are wrapped in non-returning bodies so\n    // `?.()`'s implicit `undefined` doesn't widen the function\n    // return type (which `exactOptionalPropertyTypes` rejects\n    // against the strict-optional target).\n    // Identity: pass `threadId` alone when set (never also pass deprecated `id`).\n    const baseOptions = {\n      body: opts.body,\n      ...(opts.threadId !== undefined\n        ? { threadId: opts.threadId }\n        : { id: opts.id ?? hookId }),\n      ...(opts.persistence !== undefined && { persistence: opts.persistence }),\n      ...(opts.hydrateGeneration !== undefined && {\n        hydrateGeneration: opts.hydrateGeneration,\n      }),\n      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),\n      devtoolsBridgeFactory: createVideoDevtoolsBridge,\n      devtools: {\n        ...opts.devtools,\n        framework: 'react',\n        hookName: 'useGenerateVideo',\n        outputKind: 'video' as const,\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: VideoGenerateResult) =>\n        optionsRef.current.onResult?.(r)) as (\n        result: VideoGenerateResult,\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      onJobCreated: (id: string) => {\n        if (!disposedRef.current) optionsRef.current.onJobCreated?.(id)\n      },\n      onStatusUpdate: (s: VideoStatusInfo) => {\n        if (!disposedRef.current) optionsRef.current.onStatusUpdate?.(s)\n      },\n      onResultChange: (r: TOutput | null) => {\n        if (!disposedRef.current) setResult(r)\n      },\n      onLoadingChange: (l: boolean) => {\n        if (!disposedRef.current) setIsLoading(l)\n      },\n      onErrorChange: (e: Error | undefined) => {\n        if (!disposedRef.current) setError(e)\n      },\n      onStatusChange: (s: GenerationClientState) => {\n        if (!disposedRef.current) setStatus(s)\n      },\n      onJobIdChange: (id: string | null) => {\n        if (!disposedRef.current) setJobId(id)\n      },\n      onVideoStatusChange: (s: VideoStatusInfo | null) => {\n        if (!disposedRef.current) setVideoStatus(s)\n      },\n      onResumeStateChange: (rs: { runId: string } | null) => {\n        if (!disposedRef.current) setRunId(rs?.runId ?? null)\n      },\n    }\n\n    if (opts.connection) {\n      return new VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGenerateVideo 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: VideoGenerateInput) => {\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    jobId,\n    videoStatus,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n    runId,\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"use-generate-video.js","names":[],"sources":["../../src/use-generate-video.ts"],"sourcesContent":["import { VideoGenerationClient } from '@tanstack/ai-client'\nimport { createVideoDevtoolsBridge } 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  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  InferGenerationOutputFromReturn,\n  VideoGenerateInput,\n  VideoGenerateResult,\n  VideoGenerationClientOptions,\n  VideoStatusInfo,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGenerateVideo hook.\n */\nexport interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {\n  /** Connect-based adapter for streaming transport (server handles polling) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function that returns a completed video result */\n  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations. 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 video generation completes. 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: VideoGenerateResult) => 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 when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => 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 useGenerateVideo hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {\n  /** Trigger video generation */\n  generate: (input: VideoGenerateInput) => Promise<void>\n  /** The final video result (with URL), or null */\n  result: TOutput | null\n  /** The current job ID, or null */\n  jobId: string | null\n  /** Current video generation status info, or null */\n  videoStatus: VideoStatusInfo | null\n  /** Whether generation/polling 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/polling */\n  stop: () => void\n  /** Clear all state 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 videos using AI models.\n *\n * Video generation is asynchronous: a job is created, then polled for status\n * until completion. This hook handles the full lifecycle.\n *\n * @example\n * ```tsx\n * import { useGenerateVideo } from '@tanstack/ai-react'\n * import { fetchServerSentEvents } from '@tanstack/ai-client'\n *\n * function VideoGenerator() {\n *   const { generate, result, videoStatus, isLoading } = useGenerateVideo({\n *     connection: fetchServerSentEvents('/api/generate/video'),\n *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>\n *         Generate Video\n *       </button>\n *       {isLoading && videoStatus && (\n *         <p>Status: {videoStatus.status} ({videoStatus.progress}%)</p>\n *       )}\n *       {result && <video src={result.url} controls />}\n *     </div>\n *   )\n * }\n * ```\n */\n// `TTransformed` infers from the `onResult` return position so the callback\n// parameter is typed as `VideoGenerateResult` and `result` narrows to the\n// transform's return. See issue #848.\nexport function useGenerateVideo<TTransformed = void>(\n  options: Omit<\n    UseGenerateVideoOptions,\n    'onResult' | 'persistence' | 'threadId'\n  > & {\n    onResult?: (result: VideoGenerateResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerateVideoReturn<\n  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>\n> {\n  type TOutput = InferGenerationOutputFromReturn<\n    VideoGenerateResult,\n    TTransformed\n  >\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 [jobId, setJobId] = useState<string | null>(null)\n  const [videoStatus, setVideoStatus] = useState<VideoStatusInfo | 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    // Optional callbacks are wrapped in non-returning bodies so\n    // `?.()`'s implicit `undefined` doesn't widen the function\n    // return type (which `exactOptionalPropertyTypes` rejects\n    // against the strict-optional target).\n    const baseOptions: Omit<\n      VideoGenerationClientOptions<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      devtoolsBridgeFactory: createVideoDevtoolsBridge,\n      devtools: {\n        ...opts.devtools,\n        framework: 'react',\n        hookName: 'useGenerateVideo',\n        outputKind: 'video' as const,\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: VideoGenerateResult) =>\n        optionsRef.current.onResult?.(r)) as (\n        result: VideoGenerateResult,\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      onJobCreated: (id: string) => {\n        if (!disposedRef.current) optionsRef.current.onJobCreated?.(id)\n      },\n      onStatusUpdate: (s: VideoStatusInfo) => {\n        if (!disposedRef.current) optionsRef.current.onStatusUpdate?.(s)\n      },\n      onResultChange: (r: TOutput | null) => {\n        if (!disposedRef.current) setResult(r)\n      },\n      onLoadingChange: (l: boolean) => {\n        if (!disposedRef.current) setIsLoading(l)\n      },\n      onErrorChange: (e: Error | undefined) => {\n        if (!disposedRef.current) setError(e)\n      },\n      onStatusChange: (s: GenerationClientState) => {\n        if (!disposedRef.current) setStatus(s)\n      },\n      onJobIdChange: (id: string | null) => {\n        if (!disposedRef.current) setJobId(id)\n      },\n      onVideoStatusChange: (s: VideoStatusInfo | null) => {\n        if (!disposedRef.current) setVideoStatus(s)\n      },\n      onResumeStateChange: (rs: { runId: string } | null) => {\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 VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        ...persistenceProps,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new VideoGenerationClient<TOutput>({\n        ...baseOptions,\n        ...persistenceProps,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGenerateVideo 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: VideoGenerateInput) => {\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    jobId,\n    videoStatus,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n    runId,\n  }\n}\n"],"mappings":"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"}

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

@@ -14,10 +14,6 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for one-shot generation (no streaming protocol needed) */
     fetcher?: GenerationFetcher<TInput, TResult>;
-    /**
-     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-     */
-    id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
@@ -41,8 +37,8 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
      * id on the wire, which the protocol requires.
      *
      * **Required whenever `persistence` is set** — an app that cannot name the
-     * scope has nothing to restore to. Optional for ephemeral generations, where
-     * it falls back to `id` purely to satisfy the wire.
+     * scope has nothing to restore to. Optional for ephemeral generations. If
+     * omitted, the client mints a wire id after mount.
      */
     threadId?: string;
     /**
@@ -128,6 +124,6 @@ export interface UseGenerationReturn<TOutput, TInput extends Record<string, any>
  * await generate({ prompt: 'Hello' })
  * ```
  */
-export declare function useGeneration<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+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>;

package/dist/esm/use-generation.js

@@ -23,7 +23,7 @@ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 */
 function useGeneration(options) {
 	const hookId = useId();
-	const clientIdentity = options.threadId ?? options.id ?? hookId;
+	const clientIdentity = options.threadId ?? hookId;
 	const [result, setResult] = useState(null);
 	const [isLoading, setIsLoading] = useState(false);
 	const [error, setError] = useState(void 0);
@@ -36,8 +36,6 @@ function useGeneration(options) {
 		const opts = optionsRef.current;
 		const clientOptions = {
 			body: opts.body,
-			...opts.threadId !== void 0 ? { threadId: opts.threadId } : { id: opts.id ?? hookId },
-			...opts.persistence !== void 0 && { persistence: opts.persistence },
 			...opts.hydrateGeneration !== void 0 && { hydrateGeneration: opts.hydrateGeneration },
 			...opts.joinRun !== void 0 && { joinRun: opts.joinRun },
 			...opts.reconstructResult ? { reconstructResult: opts.reconstructResult } : {},
@@ -73,12 +71,18 @@ function useGeneration(options) {
 				if (!disposedRef.current) setRunId(rs?.runId ?? null);
 			}
 		};
+		const persistenceProps = typeof opts.threadId === "string" && opts.persistence ? {
+			persistence: opts.persistence,
+			threadId: opts.threadId
+		} : { ...opts.threadId !== void 0 && { threadId: opts.threadId } };
 		if (opts.connection) return new GenerationClient({
 			...clientOptions,
+			...persistenceProps,
 			connection: opts.connection
 		});
 		if (opts.fetcher) return new GenerationClient({
 			...clientOptions,
+			...persistenceProps,
 			fetcher: opts.fetcher
 		});
 		throw new Error("useGeneration requires either a connection or fetcher option");

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'\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  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when 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' | 'id'\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  // Single identity: prefer `threadId`; deprecated `id` only when no threadId.\n  const clientIdentity = options.threadId ?? options.id ?? 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    // Identity: pass `threadId` alone when set (never also pass deprecated `id`).\n    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {\n      body: opts.body,\n      ...(opts.threadId !== undefined\n        ? { threadId: opts.threadId }\n        : { id: opts.id ?? hookId }),\n      ...(opts.persistence !== undefined && { persistence: opts.persistence }),\n      ...(opts.hydrateGeneration !== undefined && {\n        hydrateGeneration: opts.hydrateGeneration,\n      }),\n      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),\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    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\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":"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"}
+{"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'\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  /** 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.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":"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"}

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

@@ -10,10 +10,6 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for summarization */
     fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>;
-    /**
-     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-     */
-    id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
@@ -37,8 +33,8 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
      * id on the wire, which the protocol requires.
      *
      * **Required whenever `persistence` is set** — an app that cannot name the
-     * scope has nothing to restore to. Optional for ephemeral generations, where
-     * it falls back to `id` purely to satisfy the wire.
+     * scope has nothing to restore to. Optional for ephemeral generations. If
+     * omitted, the client mints a wire id after mount.
      */
     threadId?: string;
     /**
@@ -127,6 +123,6 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
  * }
  * ```
  */
-export declare function useSummarize<TTransformed = void>(options: Omit<UseSummarizeOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+export declare function useSummarize<TTransformed = void>(options: Omit<UseSummarizeOptions, 'onResult' | 'persistence' | 'threadId'> & {
     onResult?: (result: SummarizationResult) => TTransformed;
 } & GenerationPersistenceOptions): UseSummarizeReturn<InferGenerationOutputFromReturn<SummarizationResult, TTransformed>>;

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

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

@@ -10,10 +10,6 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for transcription */
     fetcher?: GenerationFetcher<TranscriptionGenerateInput, TranscriptionResult>;
-    /**
-     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-     */
-    id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
@@ -37,8 +33,8 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
      * id on the wire, which the protocol requires.
      *
      * **Required whenever `persistence` is set** — an app that cannot name the
-     * scope has nothing to restore to. Optional for ephemeral generations, where
-     * it falls back to `id` purely to satisfy the wire.
+     * scope has nothing to restore to. Optional for ephemeral generations. If
+     * omitted, the client mints a wire id after mount.
      */
     threadId?: string;
     /**
@@ -132,6 +128,6 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
  * }
  * ```
  */
-export declare function useTranscription<TTransformed = void>(options: Omit<UseTranscriptionOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
+export declare function useTranscription<TTransformed = void>(options: Omit<UseTranscriptionOptions, 'onResult' | 'persistence' | 'threadId'> & {
     onResult?: (result: TranscriptionResult) => TTransformed;
 } & GenerationPersistenceOptions): UseTranscriptionReturn<InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>>;

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'\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  /**\n   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).\n   */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * How this generation persists across reloads.\n   * - Omit / `false`: ephemeral, in-memory only.\n   * - `true`: server-driven — on mount the client hydrates the last generation\n   *   for its `threadId` from the server (needs a connection with a\n   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.\n   */\n  persistence?: boolean\n  /**\n   * The **scope** this generation belongs to: a stable, app-chosen name for the\n   * slot successive runs fill — not a link to a chat conversation.\n   *\n   * The hook starts empty and produces many runs over its life; each gets its\n   * own `runId`, but all belong to one scope. Persistence keys on this, so\n   * derive it from your own domain and keep it identical across reloads (e.g.\n   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread\n   * id on the wire, which the protocol requires.\n   *\n   * **Required whenever `persistence` is set** — an app that cannot name the\n   * scope has nothing to restore to. Optional for ephemeral generations, where\n   * it falls back to `id` purely to satisfy the wire.\n   */\n  threadId?: string\n  /**\n   * Server-driven hydration handler for `persistence: true` when the\n   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /\n   * `rpcStream()` adapter built without handlers) — typically a one-line\n   * server-function call. The connection's own handler takes precedence.\n   */\n  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']\n  /**\n   * Re-attach handler that replays a run still generating to completion on\n   * mount, when the connection doesn't carry one. Without it, a restored\n   * `running` snapshot surfaces as an (interrupted) error. The connection's\n   * own handler takes precedence.\n   */\n  joinRun?: ConnectConnectionAdapter['joinRun']\n  /**\n   * Callback when 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' | 'id'\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJA,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 { 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'\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  /** 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+IA,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-react",
-  "version": "0.19.3",
+  "version": "0.21.1",
   "description": "React hooks for TanStack AI streaming chat, realtime voice, structured outputs, and media generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -49,13 +49,13 @@
     "media-generation"
   ],
   "dependencies": {
-    "@tanstack/ai-client": "^0.23.3"
+    "@tanstack/ai-client": "^0.25.1"
   },
   "peerDependencies": {
     "@mcp-ui/client": "^7",
     "@types/react": ">=18.0.0",
     "react": ">=18.0.0",
-    "@tanstack/ai": "^0.45.0"
+    "@tanstack/ai": "^0.47.1"
   },
   "peerDependenciesMeta": {
     "@mcp-ui/client": {
@@ -71,7 +71,7 @@
     "jsdom": "^27.4.0",
     "react": "^19.2.3",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.45.0"
+    "@tanstack/ai": "0.47.1"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/src/index.ts

@@ -84,6 +84,7 @@ export {
   xhrHttpStream,
   stream,
   rpcStream,
+  webSocket,
   createChatClientOptions,
   createMcpAppBridge,
   type McpAppBridge,
@@ -97,7 +98,10 @@ export {
   type RunAgentInputContext,
   type FetchConnectionOptions,
   type XhrConnectionOptions,
+  type WebSocketConnectionOptions,
   type InferChatMessages,
+  type GenericInterrupt,
+  type RegisteredGenericInterrupt,
   type GenerationClientState,
   type ImageGenerateInput,
   type AudioGenerateInput,