@tanstack/ai-react 0.15.14 → 0.16.0

package/src/use-audio-recorder.ts

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { AudioRecorder } from '@tanstack/ai-client'
+import type {
+  AudioRecorderOptions,
+  AudioRecording,
+  InferAudioRecordingOutput,
+} from '@tanstack/ai-client'
+
+export type UseAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+  /**
+   * Optional transform applied to the recording when `stop()` resolves. Its
+   * (awaited) return value becomes `recording` and the resolved value of
+   * `stop()`. Return nothing to keep the raw `AudioRecording`.
+   */
+  onComplete?: TOnComplete
+}
+
+export interface UseAudioRecorderReturn<TOutput> {
+  /** Latest recording (transformed if `onComplete` provided), or null. */
+  recording: TOutput | null
+  /** True while actively capturing audio. */
+  isRecording: boolean
+  /** Whether the browser supports recording (getUserMedia + MediaRecorder). */
+  isSupported: boolean
+  /** Acquire the mic and begin recording. */
+  start: () => Promise<void>
+  /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+  stop: () => Promise<TOutput>
+  /** Discard the in-progress recording and release the mic. */
+  cancel: () => void
+}
+
+/**
+ * React hook for recording an audio message. The resolved
+ * {@link AudioRecording} carries `.part` (an audio content part for
+ * `useChat.sendMessage`) and `.base64` (for the generation hooks).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if the component
+ * unmounts while a stop is in flight) — handle one channel, not both.
+ *
+ * @example
+ * ```tsx
+ * const { isRecording, start, stop, recording } = useAudioRecorder()
+ * const { sendMessage } = useChat({ connection })
+ * // ...
+ * const rec = await stop()
+ * sendMessage({ content: [rec.part] })
+ * ```
+ */
+export function useAudioRecorder<
+  TOnComplete extends (recording: AudioRecording) => unknown,
+>(
+  options: UseAudioRecorderOptions<TOnComplete>,
+): UseAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>
+export function useAudioRecorder(
+  options?: UseAudioRecorderOptions<undefined>,
+): UseAudioRecorderReturn<AudioRecording>
+export function useAudioRecorder(
+  options: UseAudioRecorderOptions<(recording: AudioRecording) => unknown> = {},
+): UseAudioRecorderReturn<unknown> {
+  const [isRecording, setIsRecording] = useState(false)
+  const [recording, setRecording] = useState<unknown>(null)
+  // Read the freshest callbacks at fire time without recreating the recorder.
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const recorder = useMemo(
+    () =>
+      new AudioRecorder({
+        ...(options.audio !== undefined && { audio: options.audio }),
+        ...(options.mimeType !== undefined && { mimeType: options.mimeType }),
+        onError: (err) => optionsRef.current.onError?.(err),
+      }),
+    // Recorder config (audio/mimeType) is captured once at mount, matching the
+    // other hooks' create-once pattern.
+    [],
+  )
+
+  useEffect(() => {
+    const unsubscribe = recorder.subscribe((state) => {
+      setIsRecording(state === 'recording')
+    })
+    return () => {
+      unsubscribe()
+      recorder.cancel()
+    }
+  }, [recorder])
+
+  const start = useCallback(() => recorder.start(), [recorder])
+  const stop = useCallback(async () => {
+    const recording = await recorder.stop()
+    const transformed = await optionsRef.current.onComplete?.(recording)
+    // Only `undefined` (returning nothing) falls back to the raw recording, so
+    // a transform that returns null is preserved — matching the inferred type,
+    // which excludes only undefined/void/null from the transform's return.
+    const output = transformed === undefined ? recording : transformed
+    setRecording(() => output)
+    return output
+  }, [recorder])
+  const cancel = useCallback(() => recorder.cancel(), [recorder])
+
+  return {
+    recording,
+    isRecording,
+    // recording is client-only; if SSR'd, gate UI on a mounted flag.
+    isSupported: AudioRecorder.isSupported(),
+    start,
+    stop,
+    cancel,
+  }
+}

package/src/use-generate-audio.ts

@@ -6,7 +6,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 
 /**
@@ -93,15 +93,12 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
  * }
  * ```
  */
-export function useGenerateAudio<
-  TOnResult extends ((result: AudioGenerationResult) => any) | undefined =
-    undefined,
->(
+export function useGenerateAudio<TTransformed = void>(
   options: Omit<UseGenerateAudioOptions, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: AudioGenerationResult) => TTransformed
   },
 ): UseGenerateAudioReturn<
-  InferGenerationOutput<AudioGenerationResult, TOnResult>
+  InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
 > {
   const devtools = {
     ...options.devtools,
@@ -110,7 +107,7 @@ export function useGenerateAudio<
     outputKind: 'audio' as const,
   }
   const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<AudioGenerateInput, AudioGenerationResult, TOnResult>({
+    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
       ...options,
       devtools,
     })

package/src/use-generate-image.ts

@@ -6,7 +6,7 @@ import type {
   GenerationClientState,
   GenerationFetcher,
   ImageGenerateInput,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 
 /**
@@ -95,15 +95,12 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
  * }
  * ```
  */
-export function useGenerateImage<
-  TOnResult extends ((result: ImageGenerationResult) => any) | undefined =
-    undefined,
->(
+export function useGenerateImage<TTransformed = void>(
   options: Omit<UseGenerateImageOptions, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: ImageGenerationResult) => TTransformed
   },
 ): UseGenerateImageReturn<
-  InferGenerationOutput<ImageGenerationResult, TOnResult>
+  InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
 > {
   const devtools = {
     ...options.devtools,
@@ -112,7 +109,7 @@ export function useGenerateImage<
     outputKind: 'image' as const,
   }
   const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<ImageGenerateInput, ImageGenerationResult, TOnResult>({
+    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
       ...options,
       devtools,
     })

package/src/use-generate-speech.ts

@@ -5,7 +5,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
   SpeechGenerateInput,
 } from '@tanstack/ai-client'
 
@@ -89,13 +89,13 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
  * }
  * ```
  */
-export function useGenerateSpeech<
-  TOnResult extends ((result: TTSResult) => any) | undefined = undefined,
->(
+export function useGenerateSpeech<TTransformed = void>(
   options: Omit<UseGenerateSpeechOptions, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: TTSResult) => TTransformed
   },
-): UseGenerateSpeechReturn<InferGenerationOutput<TTSResult, TOnResult>> {
+): UseGenerateSpeechReturn<
+  InferGenerationOutputFromReturn<TTSResult, TTransformed>
+> {
   const devtools = {
     ...options.devtools,
     framework: 'react',
@@ -103,7 +103,7 @@ export function useGenerateSpeech<
     outputKind: 'audio' as const,
   }
   const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SpeechGenerateInput, TTSResult, TOnResult>({
+    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
       ...options,
       devtools,
     })

package/src/use-generate-video.ts

@@ -7,7 +7,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
@@ -104,17 +104,20 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
  * }
  * ```
  */
-export function useGenerateVideo<
-  TOnResult extends ((result: VideoGenerateResult) => any) | undefined =
-    undefined,
->(
+// `TTransformed` infers from the `onResult` return position so the callback
+// 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'> & {
-    onResult?: TOnResult
+    onResult?: (result: VideoGenerateResult) => TTransformed
   },
 ): UseGenerateVideoReturn<
-  InferGenerationOutput<VideoGenerateResult, TOnResult>
+  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>
 > {
-  type TOutput = InferGenerationOutput<VideoGenerateResult, TOnResult>
+  type TOutput = InferGenerationOutputFromReturn<
+    VideoGenerateResult,
+    TTransformed
+  >
   const hookId = useId()
   const clientId = options.id || hookId
 
@@ -146,7 +149,13 @@ export function useGenerateVideo<
         hookName: 'useGenerateVideo',
         outputKind: 'video' as const,
       },
-      onResult: (r: VideoGenerateResult) => optionsRef.current.onResult?.(r),
+      // 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: VideoGenerateResult) =>
+        optionsRef.current.onResult?.(r)) as (
+        result: VideoGenerateResult,
+      ) => TOutput | null | void,
       onError: (e: Error) => {
         optionsRef.current.onError?.(e)
       },

package/src/use-generation.ts

@@ -8,7 +8,7 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
 
 /**
@@ -88,16 +88,22 @@ export interface UseGenerationReturn<TOutput> {
  * await generate({ prompt: 'Hello' })
  * ```
  */
+// `TTransformed` infers from the `onResult` return position (a covariant
+// inference site that works even for an optional nested property), which types
+// the callback parameter as `TResult` and narrows `result`. Inferring the
+// whole callback as a defaulted type parameter instead collapses to the
+// default, leaving the parameter `any` — a hard error under `strict`. See
+// issue #848.
 export function useGeneration<
   TInput extends Record<string, any>,
   TResult,
-  TOnResult extends ((result: TResult) => any) | undefined = undefined,
+  TTransformed = void,
 >(
   options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: TResult) => TTransformed
   },
-): UseGenerationReturn<InferGenerationOutput<TResult, TOnResult>> {
-  type TOutput = InferGenerationOutput<TResult, TOnResult>
+): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>> {
+  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
   const hookId = useId()
   const clientId = options.id || hookId
 
@@ -125,7 +131,12 @@ export function useGeneration<
         framework: 'react',
         ...opts.devtools,
       },
-      onResult: (r: TResult) => optionsRef.current.onResult?.(r),
+      // 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: TResult) => optionsRef.current.onResult?.(r)) as (
+        result: TResult,
+      ) => TOutput | null | void,
       onError: (e: Error) => {
         optionsRef.current.onError?.(e)
       },

package/src/use-mcp-app-bridge.ts

@@ -0,0 +1,60 @@
+import { useMemo, useRef } from 'react'
+import { createMcpAppBridge } from '@tanstack/ai-client'
+import type {
+  CreateMcpAppBridgeOptions,
+  McpAppBridge,
+} from '@tanstack/ai-client'
+
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
+
+/**
+ * React wrapper around `createMcpAppBridge` that returns a **stable** bridge for
+ * the given `threadId`/`callEndpoint`, while always invoking the latest
+ * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating
+ * the bridge on every render and the stale-closure / `exhaustive-deps` dance
+ * you'd otherwise write by hand:
+ *
+ * ```tsx
+ * const { sendMessage } = useChat({ threadId, connection })
+ * const bridge = useMcpAppBridge({
+ *   threadId,
+ *   callEndpoint: '/api/mcp-apps-call',
+ *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ * })
+ * // pass `bridge` to <MCPAppResource bridge={bridge} … />
+ * ```
+ *
+ * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or
+ * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`
+ * each render does not churn it.
+ */
+export function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options
+
+  // Latest-value refs so the bridge identity stays stable but its callbacks are
+  // never stale (the bridge calls `.current` at invocation time, not creation).
+  const chatRef = useRef(chat)
+  chatRef.current = chat
+  const onLinkRef = useRef(onLink)
+  onLinkRef.current = onLink
+
+  // Whether a link handler was supplied governs the bridge's link behavior
+  // (forward vs. display-only warn), so it's part of the bridge's identity.
+  const hasOnLink = onLink != null
+
+  return useMemo(
+    () =>
+      createMcpAppBridge({
+        threadId,
+        callEndpoint,
+        fetchImpl,
+        chat: {
+          sendMessage: (content, body) =>
+            chatRef.current.sendMessage(content, body),
+        },
+        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,
+      }),
+    [threadId, callEndpoint, fetchImpl, hasOnLink],
+  )
+}

package/src/use-summarize.ts

@@ -5,7 +5,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
   SummarizeGenerateInput,
 } from '@tanstack/ai-client'
 
@@ -92,14 +92,13 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
  * }
  * ```
  */
-export function useSummarize<
-  TOnResult extends ((result: SummarizationResult) => any) | undefined =
-    undefined,
->(
+export function useSummarize<TTransformed = void>(
   options: Omit<UseSummarizeOptions, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: SummarizationResult) => TTransformed
   },
-): UseSummarizeReturn<InferGenerationOutput<SummarizationResult, TOnResult>> {
+): UseSummarizeReturn<
+  InferGenerationOutputFromReturn<SummarizationResult, TTransformed>
+> {
   const devtools = {
     ...options.devtools,
     framework: 'react',
@@ -107,7 +106,7 @@ export function useSummarize<
     outputKind: 'text' as const,
   }
   const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TOnResult>({
+    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
       ...options,
       devtools,
     })

package/src/use-transcription.ts

@@ -5,7 +5,7 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
-  InferGenerationOutput,
+  InferGenerationOutputFromReturn,
   TranscriptionGenerateInput,
 } from '@tanstack/ai-client'
 
@@ -97,15 +97,12 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
  * }
  * ```
  */
-export function useTranscription<
-  TOnResult extends ((result: TranscriptionResult) => any) | undefined =
-    undefined,
->(
+export function useTranscription<TTransformed = void>(
   options: Omit<UseTranscriptionOptions, 'onResult'> & {
-    onResult?: TOnResult
+    onResult?: (result: TranscriptionResult) => TTransformed
   },
 ): UseTranscriptionReturn<
-  InferGenerationOutput<TranscriptionResult, TOnResult>
+  InferGenerationOutputFromReturn<TranscriptionResult, TTransformed>
 > {
   const devtools = {
     ...options.devtools,
@@ -114,10 +111,11 @@ export function useTranscription<
     outputKind: 'text' as const,
   }
   const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<TranscriptionGenerateInput, TranscriptionResult, TOnResult>({
-      ...options,
-      devtools,
-    })
+    useGeneration<
+      TranscriptionGenerateInput,
+      TranscriptionResult,
+      TTransformed
+    >({ ...options, devtools })
 
   return {
     generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,