@tanstack/ai-react 0.18.1 → 0.19.0

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

@@ -1,5 +1,5 @@
 import { StreamChunk, TranscriptionResult } from '@tanstack/ai';
-import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn, TranscriptionGenerateInput } from '@tanstack/ai-client';
+import { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, GenerationPersistenceOptions, InferGenerationOutputFromReturn, TranscriptionGenerateInput } from '@tanstack/ai-client';
 /**
  * Options for the useTranscription hook.
  *
@@ -10,12 +10,51 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
     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>;
     /** 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 transcription is complete. Can optionally return a transformed value.
      *
@@ -51,6 +90,13 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
     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;
 }
 /**
  * React hook for transcribing audio to text using AI models.
@@ -86,6 +132,6 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
  * }
  * ```
  */
-export declare function useTranscription<TTransformed = void>(options: Omit<UseTranscriptionOptions, 'onResult'> & {
+export declare function useTranscription<TTransformed = void>(options: Omit<UseTranscriptionOptions, 'onResult' | 'persistence' | 'threadId' | 'id'> & {
     onResult?: (result: TranscriptionResult) => TTransformed;
-}): UseTranscriptionReturn<InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>>;
+} & GenerationPersistenceOptions): UseTranscriptionReturn<InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>>;

package/dist/esm/use-transcription.js

@@ -1,23 +1,54 @@
 import { useGeneration } from "./use-generation.js";
+import { reconstructTranscriptionResult } from "@tanstack/ai-client";
+//#region src/use-transcription.ts
+/**
+* React hook for transcribing audio to text using AI models.
+*
+* @example
+* ```tsx
+* import { useTranscription } from '@tanstack/ai-react'
+* import { fetchServerSentEvents } from '@tanstack/ai-client'
+*
+* function Transcriber() {
+*   const { generate, result, isLoading } = useTranscription({
+*     connection: fetchServerSentEvents('/api/transcribe'),
+*   })
+*
+*   const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
+*     const file = e.target.files?.[0]
+*     if (file) {
+*       const reader = new FileReader()
+*       reader.onload = () => {
+*         generate({ audio: reader.result as string, language: 'en' })
+*       }
+*       reader.readAsDataURL(file)
+*     }
+*   }
+*
+*   return (
+*     <div>
+*       <input type="file" accept="audio/*" onChange={handleFile} />
+*       {isLoading && <p>Transcribing...</p>}
+*       {result && <p>{result.text}</p>}
+*     </div>
+*   )
+* }
+* ```
+*/
 function useTranscription(options) {
-  const devtools = {
-    ...options.devtools,
-    framework: "react",
-    hookName: "useTranscription",
-    outputKind: "text"
-  };
-  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: "useTranscription",
+		outputKind: "text"
+	};
+	return useGeneration({
+		...options,
+		devtools,
+		reconstructResult: reconstructTranscriptionResult
+	});
 }
-export {
-  useTranscription
-};
-//# sourceMappingURL=use-transcription.js.map
+//#endregion
+export { useTranscription };
+
+//# sourceMappingURL=use-transcription.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-react",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "React hooks for TanStack AI streaming chat, realtime voice, structured outputs, and media generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -49,13 +49,13 @@
     "media-generation"
   ],
   "dependencies": {
-    "@tanstack/ai-client": "0.22.1"
+    "@tanstack/ai-client": "0.23.0"
   },
   "peerDependencies": {
     "@mcp-ui/client": "^7",
     "@types/react": ">=18.0.0",
     "react": ">=18.0.0",
-    "@tanstack/ai": "^0.42.0"
+    "@tanstack/ai": "^0.43.0"
   },
   "peerDependenciesMeta": {
     "@mcp-ui/client": {
@@ -70,13 +70,13 @@
     "@vitest/coverage-v8": "4.0.14",
     "jsdom": "^27.2.0",
     "react": "^19.2.3",
-    "vite": "^7.3.3",
-    "@tanstack/ai": "0.42.0"
+    "vite": "^8.1.4",
+    "@tanstack/ai": "0.43.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",
-    "lint:fix": "eslint ./src --fix",
-    "test:eslint": "eslint ./src",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:oxlint": "oxlint src --type-aware",
     "test:lib": "vitest run",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc",

package/src/index.ts

@@ -69,6 +69,16 @@ export type {
 // Re-export from ai-client for convenience
 export {
   fetchServerSentEvents,
+  localStoragePersistence,
+  sessionStoragePersistence,
+  indexedDBPersistence,
+  StorageUnavailableError,
+  type ChatClientPersistence,
+  type ChatPersistedState,
+  type ChatPersistenceOption,
+  type ChatStorageAdapter,
+  type WebStoragePersistenceOptions,
+  type IndexedDBPersistenceOptions,
   fetchHttpStream,
   xhrServerSentEvents,
   xhrHttpStream,

package/src/types.ts

@@ -2,13 +2,18 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai/client'
 import type {
   AIDevtoolsDisplayOptions,
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
+  ChatInterrupt,
+  ChatInterruptState,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -88,8 +93,14 @@ export type UseChatOptions<
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
   | 'onQueueChange'
+  | 'onResumeStateChange'
+  | 'onRunIdChange'
   | 'context'
   | 'devtools'
+  // `id` is not a hook option: the hook's identity is its `threadId`, which is
+  // also the persistence key. Persist across reloads by passing a stable
+  // `threadId`; there is no separate id to set.
+  | 'id'
 > & {
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
@@ -195,6 +206,39 @@ interface BaseUseChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  /**
+   * The id of the run this client has in flight — one it started or rejoined —
+   * or `null` when there is none (including while a run sits paused on an
+   * interrupt, waiting on approval).
+   *
+   * A run is one turn of the conversation, so this changes from turn to turn. A
+   * whole tool loop stays inside one run, while resuming after an interrupt
+   * continues the turn under a new id — so one user message can produce several
+   * run ids. Use it to talk to your own server about that run (cancel it, poll
+   * it, correlate a log line).
+   */
+  runId: string | null
+  interrupts: BoundInterrupts<TTools>
+  /** @deprecated Use `interrupts`. */
+  pendingInterrupts: BoundInterrupts<TTools>
+  interruptErrors: ChatInterruptState<TTools>['interruptErrors']
+  resuming: boolean
+  resolveInterrupts: {
+    (approved: boolean): void
+    (resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void
+  }
+  cancelInterrupts: () => void
+  retryInterrupts: () => void
+  resumeInterruptsUnsafe: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+  /** @deprecated Use bound interrupt methods or `resumeInterruptsUnsafe`. */
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */