@tanstack/ai-solid 0.15.0 → 0.16.0

package/src/use-generate-audio.ts

@@ -1,4 +1,9 @@
 import { useGeneration } from './use-generation'
+import { reconstructAudioResult } from '@tanstack/ai-client'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -6,6 +11,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 import type { Accessor } from 'solid-js'
@@ -15,12 +21,19 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to AudioGenerationResult)
  */
-export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  UseGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
   fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
-  /** 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>
@@ -47,7 +60,9 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The transformed output type (defaults to AudioGenerationResult)
  */
-export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioReturn<
+  TOutput = AudioGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
   /** The generation result containing audio, or null */
@@ -58,10 +73,6 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -89,9 +100,12 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
  * ```
  */
 export function useGenerateAudio<TTransformed = void>(
-  options: Omit<UseGenerateAudioOptions, 'onResult'> & {
+  options: Omit<
+    UseGenerateAudioOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: AudioGenerationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseGenerateAudioReturn<
   InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
 > {
@@ -101,19 +115,15 @@ export function useGenerateAudio<TTransformed = void>(
     hookName: 'useGenerateAudio',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    AudioGenerateInput,
+    AudioGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+    reconstructResult: reconstructAudioResult,
+  })
 
-  return {
-    generate: generate as (input: AudioGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/src/use-generate-image.ts

@@ -1,10 +1,16 @@
 import { useGeneration } from './use-generation'
+import { reconstructImageResult } from '@tanstack/ai-client'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   ImageGenerateInput,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
@@ -15,12 +21,19 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to ImageGenerationResult)
  */
-export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageOptions<
+  TOutput = ImageGenerationResult,
+> extends Pick<
+  UseGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for image generation */
   fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>
-  /** 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>
@@ -47,7 +60,9 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
  *
  * @template TOutput - The transformed output type (defaults to ImageGenerationResult)
  */
-export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageReturn<
+  TOutput = ImageGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger image generation */
   generate: (input: ImageGenerateInput) => Promise<void>
   /** The generation result containing images, or null */
@@ -58,10 +73,6 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -97,9 +108,12 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
  * ```
  */
 export function useGenerateImage<TTransformed = void>(
-  options: Omit<UseGenerateImageOptions, 'onResult'> & {
+  options: Omit<
+    UseGenerateImageOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: ImageGenerationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseGenerateImageReturn<
   InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
 > {
@@ -109,19 +123,15 @@ export function useGenerateImage<TTransformed = void>(
     hookName: 'useGenerateImage',
     outputKind: 'image' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    ImageGenerateInput,
+    ImageGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+    reconstructResult: reconstructImageResult,
+  })
 
-  return {
-    generate: generate as (input: ImageGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/src/use-generate-speech.ts

@@ -1,10 +1,16 @@
 import { useGeneration } from './use-generation'
+import { reconstructSpeechResult } from '@tanstack/ai-client'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   SpeechGenerateInput,
 } from '@tanstack/ai-client'
@@ -15,12 +21,17 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to TTSResult)
  */
-export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
+export interface UseGenerateSpeechOptions<TOutput = TTSResult> extends Pick<
+  UseGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for speech generation */
   fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
-  /** 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>
@@ -47,7 +58,10 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
  *
  * @template TOutput - The transformed output type (defaults to TTSResult)
  */
-export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
+export interface UseGenerateSpeechReturn<TOutput = TTSResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger speech generation */
   generate: (input: SpeechGenerateInput) => Promise<void>
   /** The TTS result containing audio data, or null */
@@ -58,10 +72,6 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -91,9 +101,12 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
  * ```
  */
 export function useGenerateSpeech<TTransformed = void>(
-  options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
+  options: Omit<
+    UseGenerateSpeechOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: TTSResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseGenerateSpeechReturn<
   InferGenerationOutputFromReturn<TTSResult, TTransformed>
 > {
@@ -103,19 +116,15 @@ export function useGenerateSpeech<TTransformed = void>(
     hookName: 'useGenerateSpeech',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SpeechGenerateInput,
+    TTSResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+    reconstructResult: reconstructSpeechResult,
+  })
 
-  return {
-    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/src/use-generate-video.ts

@@ -2,11 +2,11 @@ import { VideoGenerationClient } from '@tanstack/ai-client'
 import { createVideoDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import {
   createEffect,
-  createMemo,
   createSignal,
   createUniqueId,
   onCleanup,
   onMount,
+  untrack,
 } from 'solid-js'
 import type { StreamChunk } from '@tanstack/ai'
 import type {
@@ -14,6 +14,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
@@ -31,12 +32,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.
    *
@@ -81,6 +121,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: Accessor<string | null>
 }
 
 /**
@@ -118,9 +165,12 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
 // parameter is typed as `VideoGenerateResult` and `result` narrows to the
 // transform's return. See issue #848.
 export function useGenerateVideo<TTransformed = void>(
-  options: Omit<UseGenerateVideoOptions, 'onResult'> & {
+  options: Omit<
+    UseGenerateVideoOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: VideoGenerateResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseGenerateVideoReturn<
   InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>
 > {
@@ -129,7 +179,6 @@ export function useGenerateVideo<TTransformed = void>(
     TTransformed
   >
   const hookId = createUniqueId()
-  const clientId = options.id || hookId
 
   const [result, setResult] = createSignal<TOutput | null>(null)
   const [jobId, setJobId] = createSignal<string | null>(null)
@@ -139,13 +188,30 @@ export function useGenerateVideo<TTransformed = void>(
   const [isLoading, setIsLoading] = createSignal(false)
   const [error, setError] = createSignal<Error | undefined>(undefined)
   const [status, setStatus] = createSignal<GenerationClientState>('idle')
+  const [runId, setRunId] = createSignal<string | null>(null)
+  let disposed = false
 
-  const client = createMemo(() => {
+  // Built once. `untrack` keeps the option reads below from subscribing
+  // construction to `options.persistence` / `options.devtools` /
+  // `options.body`: a re-run would build a second client
+  // and orphan the first (only the live one is disposed on cleanup). Later
+  // `options.body` changes are pushed through `updateOptions` instead.
+  const client = untrack((): VideoGenerationClient<TOutput> => {
     // Conditional spread on `body`: VideoGenerationClientOptions.body
     // is a strict optional; EOPT forbids passing `T | undefined`.
     const baseOptions = {
-      id: clientId,
       body: options.body,
+      // Identity: pass `threadId` alone when set (never also pass deprecated `id`).
+      ...(options.threadId !== undefined
+        ? { threadId: options.threadId }
+        : { id: options.id ?? hookId }),
+      ...(options.persistence !== undefined && {
+        persistence: options.persistence,
+      }),
+      ...(options.hydrateGeneration !== undefined && {
+        hydrateGeneration: options.hydrateGeneration,
+      }),
+      ...(options.joinRun !== undefined && { joinRun: options.joinRun }),
       devtoolsBridgeFactory: createVideoDevtoolsBridge,
       devtools: {
         ...options.devtools,
@@ -159,17 +225,42 @@ export function useGenerateVideo<TTransformed = void>(
       onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
         result: VideoGenerateResult,
       ) => TOutput | null | void,
-      onError: (e: Error) => options.onError?.(e),
-      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-      onChunk: (c: StreamChunk) => options.onChunk?.(c),
-      onJobCreated: (id: string) => options.onJobCreated?.(id),
-      onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
-      onJobIdChange: setJobId,
-      onVideoStatusChange: setVideoStatus,
+      onError: (e: Error) => {
+        if (!disposed) options.onError?.(e)
+      },
+      onProgress: (p: number, m?: string) => {
+        if (!disposed) options.onProgress?.(p, m)
+      },
+      onChunk: (c: StreamChunk) => {
+        if (!disposed) options.onChunk?.(c)
+      },
+      onJobCreated: (id: string) => {
+        if (!disposed) options.onJobCreated?.(id)
+      },
+      onStatusUpdate: (s: VideoStatusInfo) => {
+        if (!disposed) options.onStatusUpdate?.(s)
+      },
+      onResultChange: (r: TOutput | null) => {
+        if (!disposed) setResult(() => r)
+      },
+      onLoadingChange: (l: boolean) => {
+        if (!disposed) setIsLoading(l)
+      },
+      onErrorChange: (e: Error | undefined) => {
+        if (!disposed) setError(e)
+      },
+      onStatusChange: (s: GenerationClientState) => {
+        if (!disposed) setStatus(s)
+      },
+      onJobIdChange: (id: string | null) => {
+        if (!disposed) setJobId(id)
+      },
+      onVideoStatusChange: (s: VideoStatusInfo | null) => {
+        if (!disposed) setVideoStatus(s)
+      },
+      onResumeStateChange: (rs: { runId: string } | null) => {
+        if (!disposed) setRunId(rs?.runId ?? null)
+      },
     }
 
     if (options.connection) {
@@ -189,35 +280,38 @@ export function useGenerateVideo<TTransformed = void>(
     throw new Error(
       'useGenerateVideo requires either a connection or fetcher option',
     )
-  }, [clientId])
+  })
 
   // Sync body changes without recreating client
   createEffect(() => {
     const currentBody = options.body
-    client().updateOptions({
+    client.updateOptions({
       ...(currentBody !== undefined && { body: currentBody }),
     })
   })
 
+  // Mount devtools only. Generation runs are never auto-started on mount — a
+  // persisted snapshot is hydrated for display, never replayed.
   onMount(() => {
-    client().mountDevtools()
+    client.mountDevtools()
   })
 
   // Cleanup on unmount: stop any in-flight requests and unregister devtools
   onCleanup(() => {
-    client().dispose()
+    disposed = true
+    client.dispose()
   })
 
   const generate = async (input: VideoGenerateInput) => {
-    await client().generate(input)
+    await client.generate(input)
   }
 
   const stop = () => {
-    client().stop()
+    client.stop()
   }
 
   const reset = () => {
-    client().reset()
+    client.reset()
   }
 
   return {
@@ -230,5 +324,6 @@ export function useGenerateVideo<TTransformed = void>(
     status,
     stop,
     reset,
+    runId,
   }
 }