@octanejs/tanstack-ai 0.0.1

package/src/use-generate-video.tsrx

@@ -0,0 +1,245 @@
+import { VideoGenerationClient } from '@tanstack/ai-client'
+import { createVideoDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'octane'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutputFromReturn,
+  VideoGenerateInput,
+  VideoGenerateResult,
+  VideoStatusInfo,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the useGenerateVideo hook.
+ */
+export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
+  /** Connect-based adapter for streaming transport (server handles polling) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function that returns a completed video result */
+  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with connect-based adapter requests */
+  body?: Record<string, any>
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * Callback when video generation completes. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: VideoGenerateResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback when a video job is created */
+  onJobCreated?: (jobId: string) => void
+  /** Callback on each status update */
+  onStatusUpdate?: (status: VideoStatusInfo) => void
+  /** Callback for each stream chunk (connect-based adapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useGenerateVideo hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
+  /** Trigger video generation */
+  generate: (input: VideoGenerateInput) => Promise<void>
+  /** The final video result (with URL), or null */
+  result: TOutput | null
+  /** The current job ID, or null */
+  jobId: string | null
+  /** Current video generation status info, or null */
+  videoStatus: VideoStatusInfo | null
+  /** Whether generation/polling is in progress */
+  isLoading: boolean
+  /** Current error, if any */
+  error: Error | undefined
+  /** Current state of the generation */
+  status: GenerationClientState
+  /** Abort the current generation/polling */
+  stop: () => void
+  /** Clear all state and return to idle */
+  reset: () => void
+}
+
+/**
+ * Octane 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 '@octanejs/tanstack-ai'
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+// `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?: (result: VideoGenerateResult) => TTransformed
+  },
+): UseGenerateVideoReturn<
+  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>
+> {
+  type TOutput = InferGenerationOutputFromReturn<
+    VideoGenerateResult,
+    TTransformed
+  >
+  const hookId = useId()
+  const clientId = options.id || hookId
+
+  const [result, setResult] = useState<TOutput | null>(null)
+  const [jobId, setJobId] = useState<string | null>(null)
+  const [videoStatus, setVideoStatus] = useState<VideoStatusInfo | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | undefined>(undefined)
+  const [status, setStatus] = useState<GenerationClientState>('idle')
+
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const client = useMemo(() => {
+    const opts = optionsRef.current
+
+    // Conditional spread for `body` (strict-optional in target).
+    // Optional callbacks are wrapped in non-returning bodies so
+    // `?.()`'s implicit `undefined` doesn't widen the function
+    // return type (which `exactOptionalPropertyTypes` rejects
+    // against the strict-optional target).
+    const baseOptions = {
+      id: clientId,
+      body: opts.body,
+      devtoolsBridgeFactory: createVideoDevtoolsBridge,
+      devtools: {
+        ...opts.devtools,
+        // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+        framework: 'octane',
+        hookName: 'useGenerateVideo',
+        outputKind: 'video' as const,
+      },
+      // 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)
+      },
+      onProgress: (p: number, m?: string) => {
+        optionsRef.current.onProgress?.(p, m)
+      },
+      onChunk: (c: StreamChunk) => {
+        optionsRef.current.onChunk?.(c)
+      },
+      onJobCreated: (id: string) => {
+        optionsRef.current.onJobCreated?.(id)
+      },
+      onStatusUpdate: (s: VideoStatusInfo) => {
+        optionsRef.current.onStatusUpdate?.(s)
+      },
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus,
+      onJobIdChange: setJobId,
+      onVideoStatusChange: setVideoStatus,
+    }
+
+    if (opts.connection) {
+      return new VideoGenerationClient<TOutput>({
+        ...baseOptions,
+        connection: opts.connection,
+      })
+    }
+
+    if (opts.fetcher) {
+      return new VideoGenerationClient<TOutput>({
+        ...baseOptions,
+        fetcher: opts.fetcher,
+      })
+    }
+
+    throw new Error(
+      'useGenerateVideo requires either a connection or fetcher option',
+    )
+  }, [clientId])
+
+  // Sync body changes without recreating client
+  useEffect(() => {
+    // Conditional spread: target uses strict-optional `body?: T`.
+    client.updateOptions({
+      ...(options.body !== undefined && { body: options.body }),
+    })
+  }, [client, options.body])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    client.mountDevtools()
+
+    return () => {
+      client.dispose()
+    }
+  }, [client])
+
+  const generate = useCallback(
+    async (input: VideoGenerateInput) => {
+      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,
+  }
+}

package/src/use-generate-video.tsrx.d.ts

@@ -0,0 +1,95 @@
+// Declaration companion generated from use-generate-video.tsrx.
+import type { StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn, VideoGenerateInput, VideoGenerateResult, VideoStatusInfo } from '@tanstack/ai-client';
+/**
+ * Options for the useGenerateVideo hook.
+ */
+export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
+    /** Connect-based adapter for streaming transport (server handles polling) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function that returns a completed video result */
+    fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when video generation completes. Can optionally return a transformed value.
+     *
+     * - Return a non-null value to transform and store it as the result
+     * - Return `null` to keep the previous result unchanged
+     * - Return nothing (`void`) to store the raw result as-is
+     */
+    onResult?: (result: VideoGenerateResult) => TOutput | null | void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when progress is reported (0-100) */
+    onProgress?: (progress: number, message?: string) => void;
+    /** Callback when a video job is created */
+    onJobCreated?: (jobId: string) => void;
+    /** Callback on each status update */
+    onStatusUpdate?: (status: VideoStatusInfo) => void;
+    /** Callback for each stream chunk (connect-based adapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGenerateVideo hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
+    /** Trigger video generation */
+    generate: (input: VideoGenerateInput) => Promise<void>;
+    /** The final video result (with URL), or null */
+    result: TOutput | null;
+    /** The current job ID, or null */
+    jobId: string | null;
+    /** Current video generation status info, or null */
+    videoStatus: VideoStatusInfo | null;
+    /** Whether generation/polling is in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation */
+    status: GenerationClientState;
+    /** Abort the current generation/polling */
+    stop: () => void;
+    /** Clear all state and return to idle */
+    reset: () => void;
+}
+/**
+ * Octane 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 '@octanejs/tanstack-ai'
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+export declare function useGenerateVideo<TTransformed = void>(options: Omit<UseGenerateVideoOptions, 'onResult'> & {
+    onResult?: (result: VideoGenerateResult) => TTransformed;
+}): UseGenerateVideoReturn<InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>>;

package/src/use-generation.tsrx

@@ -0,0 +1,216 @@
+import { GenerationClient } from '@tanstack/ai-client'
+import { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'octane'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientOptions,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutputFromReturn,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the useGeneration hook.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for one-shot generation (no streaming protocol needed) */
+  fetcher?: GenerationFetcher<TInput, TResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with connect-based adapter requests */
+  body?: Record<string, any>
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * Callback when a result is received. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (connect-based adapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the useGeneration hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerationReturn<TOutput> {
+  /** Trigger a generation request */
+  generate: (input: Record<string, any>) => Promise<void>
+  /** The generation result, or null if not yet generated */
+  result: TOutput | null
+  /** Whether a generation is currently in progress */
+  isLoading: boolean
+  /** Current error, if any */
+  error: Error | undefined
+  /** Current state of the generation client */
+  status: GenerationClientState
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+}
+
+/**
+ * Generic Octane hook for one-shot generation tasks.
+ *
+ * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,
+ * `useTranscription`, and `useSummarize`. You can also use it directly
+ * for custom generation types.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ *
+ * @example
+ * ```tsx
+ * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({
+ *   connection: fetchServerSentEvents('/api/generate/custom'),
+ * })
+ *
+ * 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,
+  TTransformed = void,
+>(
+  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+    onResult?: (result: TResult) => TTransformed
+  },
+): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>> {
+  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
+  const hookId = useId()
+  const clientId = options.id || hookId
+
+  const [result, setResult] = useState<TOutput | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | undefined>(undefined)
+  const [status, setStatus] = useState<GenerationClientState>('idle')
+
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const client = useMemo(() => {
+    const opts = optionsRef.current
+
+    // Conditional spread for `body` (strict-optional in target;
+    // local source is `Record<string, any> | undefined`). Callbacks
+    // wrap optional ones in non-returning bodies so `?.()`'s
+    // implicit `undefined` doesn't pollute the function return type.
+    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
+      id: clientId,
+      body: opts.body,
+      devtoolsBridgeFactory: createGenerationDevtoolsBridge,
+      devtools: {
+        hookName: 'useGeneration',
+        // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
+        framework: 'octane',
+        ...opts.devtools,
+      },
+      // 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)
+      },
+      onProgress: (p: number, m?: string) => {
+        optionsRef.current.onProgress?.(p, m)
+      },
+      onChunk: (c: StreamChunk) => {
+        optionsRef.current.onChunk?.(c)
+      },
+      onResultChange: setResult,
+      onLoadingChange: setIsLoading,
+      onErrorChange: setError,
+      onStatusChange: setStatus,
+    }
+
+    if (opts.connection) {
+      return new GenerationClient<TInput, TResult, TOutput>({
+        ...clientOptions,
+        connection: opts.connection,
+      })
+    }
+
+    if (opts.fetcher) {
+      return new GenerationClient<TInput, TResult, TOutput>({
+        ...clientOptions,
+        fetcher: opts.fetcher,
+      })
+    }
+
+    throw new Error(
+      'useGeneration requires either a connection or fetcher option',
+    )
+  }, [clientId])
+
+  // Sync body changes without recreating client
+  useEffect(() => {
+    // Conditional spread: target uses strict-optional `body?: T`.
+    client.updateOptions({
+      ...(options.body !== undefined && { body: options.body }),
+    })
+  }, [client, options.body])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    client.mountDevtools()
+
+    return () => {
+      client.dispose()
+    }
+  }, [client])
+
+  const generate = useCallback(
+    async (input: TInput) => {
+      await client.generate(input)
+    },
+    [client],
+  )
+
+  const stop = useCallback(() => {
+    client.stop()
+  }, [client])
+
+  const reset = useCallback(() => {
+    client.reset()
+  }, [client])
+
+  return {
+    generate: generate as (input: Record<string, any>) => Promise<void>,
+    result,
+    isLoading,
+    error,
+    status,
+    stop,
+    reset,
+  }
+}

package/src/use-generation.tsrx.d.ts

@@ -0,0 +1,81 @@
+// Declaration companion generated from use-generation.tsrx.
+import type { StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+/**
+ * Options for the useGeneration hook.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for one-shot generation (no streaming protocol needed) */
+    fetcher?: GenerationFetcher<TInput, TResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when a result is received. Can optionally return a transformed value.
+     *
+     * - Return a non-null value to transform and store it as the result
+     * - Return `null` to keep the previous result unchanged
+     * - Return nothing (`void`) to store the raw result as-is
+     */
+    onResult?: (result: TResult) => TOutput | null | void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when progress is reported (0-100) */
+    onProgress?: (progress: number, message?: string) => void;
+    /** Callback for each stream chunk (connect-based adapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the useGeneration hook.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface UseGenerationReturn<TOutput> {
+    /** Trigger a generation request */
+    generate: (input: Record<string, any>) => Promise<void>;
+    /** The generation result, or null if not yet generated */
+    result: TOutput | null;
+    /** Whether a generation is currently in progress */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | undefined;
+    /** Current state of the generation client */
+    status: GenerationClientState;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+}
+/**
+ * Generic Octane hook for one-shot generation tasks.
+ *
+ * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,
+ * `useTranscription`, and `useSummarize`. You can also use it directly
+ * for custom generation types.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ *
+ * @example
+ * ```tsx
+ * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({
+ *   connection: fetchServerSentEvents('/api/generate/custom'),
+ * })
+ *
+ * await generate({ prompt: 'Hello' })
+ * ```
+ */
+export declare function useGeneration<TInput extends Record<string, any>, TResult, TTransformed = void>(options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {
+    onResult?: (result: TResult) => TTransformed;
+}): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>>;

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

@@ -0,0 +1,60 @@
+import { useMemo, useRef } from 'octane'
+import { createMcpAppBridge } from '@tanstack/ai-client'
+import type {
+  CreateMcpAppBridgeOptions,
+  McpAppBridge,
+} from '@tanstack/ai-client'
+
+export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
+
+/**
+ * Octane 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],
+  )
+}