@tanstack/ai-react 0.18.1 → 0.19.1

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

@@ -1,26 +1,46 @@
 import { useGeneration } from "./use-generation.js";
+import { reconstructSpeechResult } from "@tanstack/ai-client";
+//#region src/use-generate-speech.ts
+/**
+* React hook for generating speech (text-to-speech) using AI models.
+*
+* @example
+* ```tsx
+* import { useGenerateSpeech } from '@tanstack/ai-react'
+* import { fetchServerSentEvents } from '@tanstack/ai-client'
+*
+* function SpeechGenerator() {
+*   const { generate, result, isLoading } = useGenerateSpeech({
+*     connection: fetchServerSentEvents('/api/generate/speech'),
+*   })
+*
+*   return (
+*     <div>
+*       <button onClick={() => generate({ text: 'Hello world', voice: 'alloy' })}>
+*         Generate Speech
+*       </button>
+*       {result && (
+*         <audio src={`data:audio/${result.format};base64,${result.audio}`} controls />
+*       )}
+*     </div>
+*   )
+* }
+* ```
+*/
 function useGenerateSpeech(options) {
-  const devtools = {
-    ...options.devtools,
-    framework: "react",
-    hookName: "useGenerateSpeech",
-    outputKind: "audio"
-  };
-  const { generate, result, isLoading, error, status, stop, reset } = useGeneration({
-    ...options,
-    devtools
-  });
-  return {
-    generate,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset
-  };
+	const devtools = {
+		...options.devtools,
+		framework: "react",
+		hookName: "useGenerateSpeech",
+		outputKind: "audio"
+	};
+	return useGeneration({
+		...options,
+		devtools,
+		reconstructResult: reconstructSpeechResult
+	});
 }
-export {
-  useGenerateSpeech
-};
-//# sourceMappingURL=use-generate-speech.js.map
+//#endregion
+export { useGenerateSpeech };
+
+//# sourceMappingURL=use-generate-speech.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-generate-speech.js","sources":["../../src/use-generate-speech.ts"],"sourcesContent":["import { useGeneration } from './use-generation'\nimport type { StreamChunk, TTSResult } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientState,\n  GenerationFetcher,\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  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * Callback when 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\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<UseGenerateSpeechOptions, 'onResult'> & {\n    onResult?: (result: TTSResult) => TTransformed\n  },\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 { generate, result, isLoading, error, status, stop, reset } =\n    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({\n      ...options,\n      devtools,\n    })\n\n  return {\n    generate: generate as (input: SpeechGenerateInput) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";AA2FO,SAAS,kBACd,SAKA;AACA,QAAM,WAAW;AAAA,IACf,GAAG,QAAQ;AAAA,IACX,WAAW;AAAA,IACX,UAAU;AAAA,IACV,YAAY;AAAA,EAAA;AAEd,QAAM,EAAE,UAAU,QAAQ,WAAW,OAAO,QAAQ,MAAM,MAAA,IACxD,cAA4D;AAAA,IAC1D,GAAG;AAAA,IACH;AAAA,EAAA,CACD;AAEH,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"use-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"}

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

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

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

@@ -1,107 +1,145 @@
 import { VideoGenerationClient } from "@tanstack/ai-client";
 import { createVideoDevtoolsBridge } from "@tanstack/ai-client/devtools";
-import { useId, useState, useRef, useMemo, useEffect, useCallback } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+//#region src/use-generate-video.ts
+/**
+* React hook for generating videos using AI models.
+*
+* Video generation is asynchronous: a job is created, then polled for status
+* until completion. This hook handles the full lifecycle.
+*
+* @example
+* ```tsx
+* import { useGenerateVideo } from '@tanstack/ai-react'
+* import { fetchServerSentEvents } from '@tanstack/ai-client'
+*
+* function VideoGenerator() {
+*   const { generate, result, videoStatus, isLoading } = useGenerateVideo({
+*     connection: fetchServerSentEvents('/api/generate/video'),
+*     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
+*   })
+*
+*   return (
+*     <div>
+*       <button onClick={() => generate({ prompt: 'A flying car over a city' })}>
+*         Generate Video
+*       </button>
+*       {isLoading && videoStatus && (
+*         <p>Status: {videoStatus.status} ({videoStatus.progress}%)</p>
+*       )}
+*       {result && <video src={result.url} controls />}
+*     </div>
+*   )
+* }
+* ```
+*/
 function useGenerateVideo(options) {
-  const hookId = useId();
-  const clientId = options.id || hookId;
-  const [result, setResult] = useState(null);
-  const [jobId, setJobId] = useState(null);
-  const [videoStatus, setVideoStatus] = useState(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState(void 0);
-  const [status, setStatus] = useState("idle");
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const client = useMemo(() => {
-    const opts = optionsRef.current;
-    const baseOptions = {
-      id: clientId,
-      body: opts.body,
-      devtoolsBridgeFactory: createVideoDevtoolsBridge,
-      devtools: {
-        ...opts.devtools,
-        framework: "react",
-        hookName: "useGenerateVideo",
-        outputKind: "video"
-      },
-      // The transform's raw return type (`TTransformed`) and the stored output
-      // (`TOutput`, with null/void/undefined stripped) are identical at runtime;
-      // the cast bridges the relationship that the conditional type hides.
-      onResult: ((r) => optionsRef.current.onResult?.(r)),
-      onError: (e) => {
-        optionsRef.current.onError?.(e);
-      },
-      onProgress: (p, m) => {
-        optionsRef.current.onProgress?.(p, m);
-      },
-      onChunk: (c) => {
-        optionsRef.current.onChunk?.(c);
-      },
-      onJobCreated: (id) => {
-        optionsRef.current.onJobCreated?.(id);
-      },
-      onStatusUpdate: (s) => {
-        optionsRef.current.onStatusUpdate?.(s);
-      },
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
-      onJobIdChange: setJobId,
-      onVideoStatusChange: setVideoStatus
-    };
-    if (opts.connection) {
-      return new VideoGenerationClient({
-        ...baseOptions,
-        connection: opts.connection
-      });
-    }
-    if (opts.fetcher) {
-      return new VideoGenerationClient({
-        ...baseOptions,
-        fetcher: opts.fetcher
-      });
-    }
-    throw new Error(
-      "useGenerateVideo requires either a connection or fetcher option"
-    );
-  }, [clientId]);
-  useEffect(() => {
-    client.updateOptions({
-      ...options.body !== void 0 && { body: options.body }
-    });
-  }, [client, options.body]);
-  useEffect(() => {
-    client.mountDevtools();
-    return () => {
-      client.dispose();
-    };
-  }, [client]);
-  const generate = useCallback(
-    async (input) => {
-      await client.generate(input);
-    },
-    [client]
-  );
-  const stop = useCallback(() => {
-    client.stop();
-  }, [client]);
-  const reset = useCallback(() => {
-    client.reset();
-  }, [client]);
-  return {
-    generate,
-    result,
-    jobId,
-    videoStatus,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset
-  };
+	const hookId = useId();
+	const clientIdentity = options.threadId ?? options.id ?? hookId;
+	const [result, setResult] = useState(null);
+	const [jobId, setJobId] = useState(null);
+	const [videoStatus, setVideoStatus] = useState(null);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState(void 0);
+	const [status, setStatus] = useState("idle");
+	const [runId, setRunId] = useState(null);
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	const disposedRef = useRef(false);
+	const client = useMemo(() => {
+		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,
+			devtools: {
+				...opts.devtools,
+				framework: "react",
+				hookName: "useGenerateVideo",
+				outputKind: "video"
+			},
+			onResult: ((r) => optionsRef.current.onResult?.(r)),
+			onError: (e) => {
+				if (!disposedRef.current) optionsRef.current.onError?.(e);
+			},
+			onProgress: (p, m) => {
+				if (!disposedRef.current) optionsRef.current.onProgress?.(p, m);
+			},
+			onChunk: (c) => {
+				if (!disposedRef.current) optionsRef.current.onChunk?.(c);
+			},
+			onJobCreated: (id) => {
+				if (!disposedRef.current) optionsRef.current.onJobCreated?.(id);
+			},
+			onStatusUpdate: (s) => {
+				if (!disposedRef.current) optionsRef.current.onStatusUpdate?.(s);
+			},
+			onResultChange: (r) => {
+				if (!disposedRef.current) setResult(r);
+			},
+			onLoadingChange: (l) => {
+				if (!disposedRef.current) setIsLoading(l);
+			},
+			onErrorChange: (e) => {
+				if (!disposedRef.current) setError(e);
+			},
+			onStatusChange: (s) => {
+				if (!disposedRef.current) setStatus(s);
+			},
+			onJobIdChange: (id) => {
+				if (!disposedRef.current) setJobId(id);
+			},
+			onVideoStatusChange: (s) => {
+				if (!disposedRef.current) setVideoStatus(s);
+			},
+			onResumeStateChange: (rs) => {
+				if (!disposedRef.current) setRunId(rs?.runId ?? null);
+			}
+		};
+		if (opts.connection) return new VideoGenerationClient({
+			...baseOptions,
+			connection: opts.connection
+		});
+		if (opts.fetcher) return new VideoGenerationClient({
+			...baseOptions,
+			fetcher: opts.fetcher
+		});
+		throw new Error("useGenerateVideo requires either a connection or fetcher option");
+	}, [clientIdentity, hookId]);
+	useEffect(() => {
+		client.updateOptions({ ...options.body !== void 0 && { body: options.body } });
+	}, [client, options.body]);
+	useEffect(() => {
+		disposedRef.current = false;
+		client.mountDevtools();
+		return () => {
+			disposedRef.current = true;
+			client.dispose();
+		};
+	}, [client]);
+	return {
+		generate: useCallback(async (input) => {
+			await client.generate(input);
+		}, [client]),
+		result,
+		jobId,
+		videoStatus,
+		isLoading,
+		error,
+		status,
+		stop: useCallback(() => {
+			client.stop();
+		}, [client]),
+		reset: useCallback(() => {
+			client.reset();
+		}, [client]),
+		runId
+	};
 }
-export {
-  useGenerateVideo
-};
-//# sourceMappingURL=use-generate-video.js.map
+//#endregion
+export { useGenerateVideo };
+
+//# sourceMappingURL=use-generate-video.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-generate-video.js","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  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  /** Unique identifier for this generation instance */\n  id?: string\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n  /** Display options for TanStack AI Devtools. */\n  devtools?: AIDevtoolsDisplayOptions\n  /**\n   * Callback when 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\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<UseGenerateVideoOptions, 'onResult'> & {\n    onResult?: (result: VideoGenerateResult) => TTransformed\n  },\n): UseGenerateVideoReturn<\n  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>\n> {\n  type TOutput = InferGenerationOutputFromReturn<\n    VideoGenerateResult,\n    TTransformed\n  >\n  const hookId = useId()\n  const clientId = 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\n  const optionsRef = useRef(options)\n  optionsRef.current = options\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 = {\n      id: clientId,\n      body: opts.body,\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        optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        optionsRef.current.onChunk?.(c)\n      },\n      onJobCreated: (id: string) => {\n        optionsRef.current.onJobCreated?.(id)\n      },\n      onStatusUpdate: (s: VideoStatusInfo) => {\n        optionsRef.current.onStatusUpdate?.(s)\n      },\n      onResultChange: setResult,\n      onLoadingChange: setIsLoading,\n      onErrorChange: setError,\n      onStatusChange: setStatus,\n      onJobIdChange: setJobId,\n      onVideoStatusChange: setVideoStatus,\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  }, [clientId])\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  // Cleanup on unmount\n  useEffect(() => {\n    client.mountDevtools()\n\n    return () => {\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  }\n}\n"],"names":[],"mappings":";;;AA6GO,SAAS,iBACd,SAKA;AAKA,QAAM,SAAS,MAAA;AACf,QAAM,WAAW,QAAQ,MAAM;AAE/B,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAyB,IAAI;AACzD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AACtD,QAAM,CAAC,aAAa,cAAc,IAAI,SAAiC,IAAI;AAC3E,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,KAAK;AAChD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA4B,MAAS;AAC/D,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAgC,MAAM;AAElE,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,SAAS,QAAQ,MAAM;AAC3B,UAAM,OAAO,WAAW;AAOxB,UAAM,cAAc;AAAA,MAClB,IAAI;AAAA,MACJ,MAAM,KAAK;AAAA,MACX,uBAAuB;AAAA,MACvB,UAAU;AAAA,QACR,GAAG,KAAK;AAAA,QACR,WAAW;AAAA,QACX,UAAU;AAAA,QACV,YAAY;AAAA,MAAA;AAAA;AAAA;AAAA;AAAA,MAKd,WAAW,CAAC,MACV,WAAW,QAAQ,WAAW,CAAC;AAAA,MAGjC,SAAS,CAAC,MAAa;AACrB,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,YAAY,CAAC,GAAW,MAAe;AACrC,mBAAW,QAAQ,aAAa,GAAG,CAAC;AAAA,MACtC;AAAA,MACA,SAAS,CAAC,MAAmB;AAC3B,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,cAAc,CAAC,OAAe;AAC5B,mBAAW,QAAQ,eAAe,EAAE;AAAA,MACtC;AAAA,MACA,gBAAgB,CAAC,MAAuB;AACtC,mBAAW,QAAQ,iBAAiB,CAAC;AAAA,MACvC;AAAA,MACA,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,eAAe;AAAA,MACf,gBAAgB;AAAA,MAChB,eAAe;AAAA,MACf,qBAAqB;AAAA,IAAA;AAGvB,QAAI,KAAK,YAAY;AACnB,aAAO,IAAI,sBAA+B;AAAA,QACxC,GAAG;AAAA,QACH,YAAY,KAAK;AAAA,MAAA,CAClB;AAAA,IACH;AAEA,QAAI,KAAK,SAAS;AAChB,aAAO,IAAI,sBAA+B;AAAA,QACxC,GAAG;AAAA,QACH,SAAS,KAAK;AAAA,MAAA,CACf;AAAA,IACH;AAEA,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ,GAAG,CAAC,QAAQ,CAAC;AAGb,YAAU,MAAM;AAEd,WAAO,cAAc;AAAA,MACnB,GAAI,QAAQ,SAAS,UAAa,EAAE,MAAM,QAAQ,KAAA;AAAA,IAAK,CACxD;AAAA,EACH,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;AAGzB,YAAU,MAAM;AACd,WAAO,cAAA;AAEP,WAAO,MAAM;AACX,aAAO,QAAA;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,WAAW;AAAA,IACf,OAAO,UAA8B;AACnC,YAAM,OAAO,SAAS,KAAK;AAAA,IAC7B;AAAA,IACA,CAAC,MAAM;AAAA,EAAA;AAGT,QAAM,OAAO,YAAY,MAAM;AAC7B,WAAO,KAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,QAAQ,YAAY,MAAM;AAC9B,WAAO,MAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"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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"}

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

@@ -1,5 +1,5 @@
 import { StreamChunk } from '@tanstack/ai';
-import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, GenerationPersistenceOptions, GenerationRestoredResult, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
 /**
  * Options for the useGeneration hook.
  *
@@ -14,12 +14,51 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
     connection?: ConnectConnectionAdapter;
     /** Direct async function for one-shot generation (no streaming protocol needed) */
     fetcher?: GenerationFetcher<TInput, TResult>;
-    /** Unique identifier for this generation instance */
+    /**
+     * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+     */
     id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
     /** Display options for TanStack AI Devtools. */
     devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * How this generation persists across reloads.
+     * - Omit / `false`: ephemeral, in-memory only.
+     * - `true`: server-driven — on mount the client hydrates the last generation
+     *   for its `threadId` from the server (needs a connection with a
+     *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+     */
+    persistence?: boolean;
+    /**
+     * The **scope** this generation belongs to: a stable, app-chosen name for the
+     * slot successive runs fill — not a link to a chat conversation.
+     *
+     * The hook starts empty and produces many runs over its life; each gets its
+     * own `runId`, but all belong to one scope. Persistence keys on this, so
+     * derive it from your own domain and keep it identical across reloads (e.g.
+     * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+     * id on the wire, which the protocol requires.
+     *
+     * **Required whenever `persistence` is set** — an app that cannot name the
+     * scope has nothing to restore to. Optional for ephemeral generations, where
+     * it falls back to `id` purely to satisfy the wire.
+     */
+    threadId?: string;
+    /**
+     * Server-driven hydration handler for `persistence: true` when the
+     * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+     * `rpcStream()` adapter built without handlers) — typically a one-line
+     * server-function call. The connection's own handler takes precedence.
+     */
+    hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration'];
+    /**
+     * Re-attach handler that replays a run still generating to completion on
+     * mount, when the connection doesn't carry one. Without it, a restored
+     * `running` snapshot surfaces as an (interrupted) error. The connection's
+     * own handler takes precedence.
+     */
+    joinRun?: ConnectConnectionAdapter['joinRun'];
     /**
      * Callback when a result is received. Can optionally return a transformed value.
      *
@@ -34,15 +73,22 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
     onProgress?: (progress: number, message?: string) => void;
     /** Callback for each stream chunk (connect-based adapter mode only) */
     onChunk?: (chunk: StreamChunk) => void;
+    /**
+     * @internal Rebuild a typed result from a restored snapshot, injected by each
+     * specialized hook (image / speech / audio / transcription / summarize).
+     * Forwarded to the client so a server-hydrate restore repaints `result`.
+     */
+    reconstructResult?: (restored: GenerationRestoredResult) => TResult | null;
 }
 /**
  * Return type for the useGeneration hook.
  *
  * @template TOutput - The output type (after optional transform)
+ * @template TInput - The input type accepted by `generate` (defaults to any object)
  */
-export interface UseGenerationReturn<TOutput> {
+export interface UseGenerationReturn<TOutput, TInput extends Record<string, any> = Record<string, any>> {
     /** Trigger a generation request */
-    generate: (input: Record<string, any>) => Promise<void>;
+    generate: (input: TInput) => Promise<void>;
     /** The generation result, or null if not yet generated */
     result: TOutput | null;
     /** Whether a generation is currently in progress */
@@ -55,6 +101,13 @@ export interface UseGenerationReturn<TOutput> {
     stop: () => void;
     /** Clear result, error, and return to idle */
     reset: () => void;
+    /**
+     * The id of the generation job currently running, or `null` when nothing is in
+     * flight. Each call to `generate` is one job with its own id. Pass it to your
+     * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+     * local stream, it does not stop work already running on the provider.
+     */
+    runId: string | null;
 }
 /**
  * Generic React hook for one-shot generation tasks.
@@ -75,6 +128,6 @@ export interface UseGenerationReturn<TOutput> {
  * await generate({ prompt: 'Hello' })
  * ```
  */
-export declare function useGeneration<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+export declare function useGeneration<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
     onResult?: (result: TResult) => TTransformed;
-}): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>>;
+} & GenerationPersistenceOptions): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>, TInput>;