@tanstack/ai-solid 0.15.1 → 0.16.1

package/src/use-generation.ts

@@ -2,11 +2,11 @@ import { GenerationClient } from '@tanstack/ai-client'
 import { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import {
   createEffect,
-  createMemo,
   createSignal,
   createUniqueId,
   onCleanup,
   onMount,
+  untrack,
 } from 'solid-js'
 import type { StreamChunk } from '@tanstack/ai'
 import type {
@@ -15,6 +15,8 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
+  GenerationRestoredResult,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 import type { Accessor } from 'solid-js'
@@ -33,12 +35,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.
    *
@@ -53,16 +94,26 @@ 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 (possibly transformed from the raw result)
+ * @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: Accessor<TOutput | null>
   /** Whether a generation is currently in progress */
@@ -75,6 +126,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: Accessor<string | null>
 }
 
 /**
@@ -108,26 +166,51 @@ export function useGeneration<
   TResult,
   TTransformed = void,
 >(
-  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+  options: Omit<
+    UseGenerationOptions<TInput, TResult>,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: TResult) => TTransformed
-  },
-): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>> {
+  } & GenerationPersistenceOptions,
+): UseGenerationReturn<
+  InferGenerationOutputFromReturn<TResult, TTransformed>,
+  TInput
+> {
   type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
   const hookId = createUniqueId()
-  const clientId = options.id || hookId
 
   const [result, setResult] = createSignal<TOutput | null>(null)
   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((): GenerationClient<TInput, TResult, TOutput> => {
     // Conditional spread on `body`: `GenerationClientOptions.body` is a
     // strict optional (`body?: Record<string, any>`) and EOPT forbids
     // assigning the source `T | undefined` directly.
     const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
-      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 }),
+      ...(options.reconstructResult
+        ? { reconstructResult: options.reconstructResult }
+        : {}),
       devtoolsBridgeFactory: createGenerationDevtoolsBridge,
       devtools: {
         ...options.devtools,
@@ -140,13 +223,30 @@ export function useGeneration<
       onResult: ((r: TResult) => options.onResult?.(r)) as (
         result: TResult,
       ) => TOutput | null | void,
-      onError: (e: Error) => options.onError?.(e),
-      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-      onChunk: (c: StreamChunk) => options.onChunk?.(c),
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
+      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)
+      },
+      onResultChange: (r) => {
+        if (!disposed) setResult(() => r)
+      },
+      onLoadingChange: (l) => {
+        if (!disposed) setIsLoading(l)
+      },
+      onErrorChange: (e) => {
+        if (!disposed) setError(e)
+      },
+      onStatusChange: (s) => {
+        if (!disposed) setStatus(s)
+      },
+      onResumeStateChange: (rs) => {
+        if (!disposed) setRunId(rs?.runId ?? null)
+      },
     }
 
     if (options.connection) {
@@ -166,44 +266,48 @@ export function useGeneration<
     throw new Error(
       'useGeneration 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: TInput) => {
-    await client().generate(input)
+    await client.generate(input)
   }
 
   const stop = () => {
-    client().stop()
+    client.stop()
   }
 
   const reset = () => {
-    client().reset()
+    client.reset()
   }
 
   return {
-    generate: generate as (input: Record<string, any>) => Promise<void>,
+    generate,
     result,
     isLoading,
     error,
     status,
     stop,
     reset,
+    runId,
   }
 }

package/src/use-summarize.ts

@@ -1,10 +1,16 @@
 import { useGeneration } from './use-generation'
+import { reconstructSummarizeResult } from '@tanstack/ai-client'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPersistenceOptions,
   InferGenerationOutputFromReturn,
   SummarizeGenerateInput,
 } from '@tanstack/ai-client'
@@ -15,12 +21,19 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to SummarizationResult)
  */
-export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+export interface UseSummarizeOptions<
+  TOutput = SummarizationResult,
+> extends Pick<
+  UseGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
+  'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for summarization */
   fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
-  /** Unique identifier for this generation instance */
+  /**
+   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
+   */
   id?: string
   /** Additional body parameters to send with connect-based adapter requests */
   body?: Record<string, any>
@@ -47,7 +60,10 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
  *
  * @template TOutput - The transformed output type (defaults to SummarizationResult)
  */
-export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+export interface UseSummarizeReturn<TOutput = SummarizationResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger summarization */
   generate: (input: SummarizeGenerateInput) => Promise<void>
   /** The summarization result, or null */
@@ -58,10 +74,6 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current summarization */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -94,9 +106,12 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
  * ```
  */
 export function useSummarize<TTransformed = void>(
-  options: Omit<UseSummarizeOptions, 'onResult'> & {
+  options: Omit<
+    UseSummarizeOptions,
+    'onResult' | 'persistence' | 'threadId' | 'id'
+  > & {
     onResult?: (result: SummarizationResult) => TTransformed
-  },
+  } & GenerationPersistenceOptions,
 ): UseSummarizeReturn<
   InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
 > {
@@ -106,19 +121,15 @@ export function useSummarize<TTransformed = void>(
     hookName: 'useSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+    reconstructResult: reconstructSummarizeResult,
+  })
 
-  return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
-  }
+  return generation
 }

package/src/use-transcription.ts

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