@tanstack/ai-react 0.18.1 → 0.19.1

package/dist/esm/use-generation.js

@@ -1,94 +1,117 @@
 import { GenerationClient } from "@tanstack/ai-client";
 import { createGenerationDevtoolsBridge } from "@tanstack/ai-client/devtools";
-import { useId, useState, useRef, useMemo, useEffect, useCallback } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+//#region src/use-generation.ts
+/**
+* Generic React 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' })
+* ```
+*/
 function useGeneration(options) {
-  const hookId = useId();
-  const clientId = options.id || hookId;
-  const [result, setResult] = useState(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState(void 0);
-  const [status, setStatus] = useState("idle");
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  const client = useMemo(() => {
-    const opts = optionsRef.current;
-    const clientOptions = {
-      id: clientId,
-      body: opts.body,
-      devtoolsBridgeFactory: createGenerationDevtoolsBridge,
-      devtools: {
-        hookName: "useGeneration",
-        framework: "react",
-        ...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) => optionsRef.current.onResult?.(r)),
-      onError: (e) => {
-        optionsRef.current.onError?.(e);
-      },
-      onProgress: (p, m) => {
-        optionsRef.current.onProgress?.(p, m);
-      },
-      onChunk: (c) => {
-        optionsRef.current.onChunk?.(c);
-      },
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus
-    };
-    if (opts.connection) {
-      return new GenerationClient({
-        ...clientOptions,
-        connection: opts.connection
-      });
-    }
-    if (opts.fetcher) {
-      return new GenerationClient({
-        ...clientOptions,
-        fetcher: opts.fetcher
-      });
-    }
-    throw new Error(
-      "useGeneration requires either a connection or fetcher option"
-    );
-  }, [clientId]);
-  useEffect(() => {
-    client.updateOptions({
-      ...options.body !== void 0 && { body: options.body }
-    });
-  }, [client, options.body]);
-  useEffect(() => {
-    client.mountDevtools();
-    return () => {
-      client.dispose();
-    };
-  }, [client]);
-  const generate = useCallback(
-    async (input) => {
-      await client.generate(input);
-    },
-    [client]
-  );
-  const stop = useCallback(() => {
-    client.stop();
-  }, [client]);
-  const reset = useCallback(() => {
-    client.reset();
-  }, [client]);
-  return {
-    generate,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset
-  };
+	const hookId = useId();
+	const clientIdentity = options.threadId ?? options.id ?? hookId;
+	const [result, setResult] = useState(null);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState(void 0);
+	const [status, setStatus] = useState("idle");
+	const [runId, setRunId] = useState(null);
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	const disposedRef = useRef(false);
+	const client = useMemo(() => {
+		const opts = optionsRef.current;
+		const clientOptions = {
+			body: opts.body,
+			...opts.threadId !== void 0 ? { threadId: opts.threadId } : { id: opts.id ?? hookId },
+			...opts.persistence !== void 0 && { persistence: opts.persistence },
+			...opts.hydrateGeneration !== void 0 && { hydrateGeneration: opts.hydrateGeneration },
+			...opts.joinRun !== void 0 && { joinRun: opts.joinRun },
+			...opts.reconstructResult ? { reconstructResult: opts.reconstructResult } : {},
+			devtoolsBridgeFactory: createGenerationDevtoolsBridge,
+			devtools: {
+				hookName: "useGeneration",
+				framework: "react",
+				...opts.devtools
+			},
+			onResult: ((r) => optionsRef.current.onResult?.(r)),
+			onError: (e) => {
+				if (!disposedRef.current) optionsRef.current.onError?.(e);
+			},
+			onProgress: (p, m) => {
+				if (!disposedRef.current) optionsRef.current.onProgress?.(p, m);
+			},
+			onChunk: (c) => {
+				if (!disposedRef.current) optionsRef.current.onChunk?.(c);
+			},
+			onResultChange: (r) => {
+				if (!disposedRef.current) setResult(r);
+			},
+			onLoadingChange: (l) => {
+				if (!disposedRef.current) setIsLoading(l);
+			},
+			onErrorChange: (e) => {
+				if (!disposedRef.current) setError(e);
+			},
+			onStatusChange: (s) => {
+				if (!disposedRef.current) setStatus(s);
+			},
+			onResumeStateChange: (rs) => {
+				if (!disposedRef.current) setRunId(rs?.runId ?? null);
+			}
+		};
+		if (opts.connection) return new GenerationClient({
+			...clientOptions,
+			connection: opts.connection
+		});
+		if (opts.fetcher) return new GenerationClient({
+			...clientOptions,
+			fetcher: opts.fetcher
+		});
+		throw new Error("useGeneration requires either a connection or fetcher option");
+	}, [clientIdentity, hookId]);
+	useEffect(() => {
+		client.updateOptions({ ...options.body !== void 0 && { body: options.body } });
+	}, [client, options.body]);
+	useEffect(() => {
+		disposedRef.current = false;
+		client.mountDevtools();
+		return () => {
+			disposedRef.current = true;
+			client.dispose();
+		};
+	}, [client]);
+	return {
+		generate: useCallback(async (input) => {
+			await client.generate(input);
+		}, [client]),
+		result,
+		isLoading,
+		error,
+		status,
+		stop: useCallback(() => {
+			client.stop();
+		}, [client]),
+		reset: useCallback(() => {
+			client.reset();
+		}, [client]),
+		runId
+	};
 }
-export {
-  useGeneration
-};
-//# sourceMappingURL=use-generation.js.map
+//#endregion
+export { useGeneration };
+
+//# sourceMappingURL=use-generation.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-generation.js","sources":["../../src/use-generation.ts"],"sourcesContent":["import { GenerationClient } from '@tanstack/ai-client'\nimport { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGeneration hook.\n *\n * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\nexport interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for one-shot generation (no streaming protocol needed) */\n  fetcher?: GenerationFetcher<TInput, TResult>\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 a result is received. 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: TResult) => 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 useGeneration hook.\n *\n * @template TOutput - The output type (after optional transform)\n */\nexport interface UseGenerationReturn<TOutput> {\n  /** Trigger a generation request */\n  generate: (input: Record<string, any>) => Promise<void>\n  /** The generation result, or null if not yet generated */\n  result: TOutput | null\n  /** Whether a generation is currently in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation client */\n  status: GenerationClientState\n  /** Abort the current generation */\n  stop: () => void\n  /** Clear result, error, and return to idle */\n  reset: () => void\n}\n\n/**\n * Generic React hook for one-shot generation tasks.\n *\n * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,\n * `useTranscription`, and `useSummarize`. You can also use it directly\n * for custom generation types.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```tsx\n * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({\n *   connection: fetchServerSentEvents('/api/generate/custom'),\n * })\n *\n * await generate({ prompt: 'Hello' })\n * ```\n */\n// `TTransformed` infers from the `onResult` return position (a covariant\n// inference site that works even for an optional nested property), which types\n// the callback parameter as `TResult` and narrows `result`. Inferring the\n// whole callback as a defaulted type parameter instead collapses to the\n// default, leaving the parameter `any` — a hard error under `strict`. See\n// issue #848.\nexport function useGeneration<\n  TInput extends Record<string, any>,\n  TResult,\n  TTransformed = void,\n>(\n  options: Omit<UseGenerationOptions<TInput, TResult>, 'onResult'> & {\n    onResult?: (result: TResult) => TTransformed\n  },\n): UseGenerationReturn<InferGenerationOutputFromReturn<TResult, TTransformed>> {\n  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>\n  const hookId = useId()\n  const clientId = options.id || hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<GenerationClientState>('idle')\n\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n\n  const client = useMemo(() => {\n    const opts = optionsRef.current\n\n    // Conditional spread for `body` (strict-optional in target;\n    // local source is `Record<string, any> | undefined`). Callbacks\n    // wrap optional ones in non-returning bodies so `?.()`'s\n    // implicit `undefined` doesn't pollute the function return type.\n    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {\n      id: clientId,\n      body: opts.body,\n      devtoolsBridgeFactory: createGenerationDevtoolsBridge,\n      devtools: {\n        hookName: 'useGeneration',\n        framework: 'react',\n        ...opts.devtools,\n      },\n      // The transform's raw return type (`TTransformed`) and the stored output\n      // (`TOutput`, with null/void/undefined stripped) are identical at runtime;\n      // the cast bridges the relationship that the conditional type hides.\n      onResult: ((r: TResult) => optionsRef.current.onResult?.(r)) as (\n        result: TResult,\n      ) => TOutput | null | void,\n      onError: (e: Error) => {\n        optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        optionsRef.current.onChunk?.(c)\n      },\n      onResultChange: setResult,\n      onLoadingChange: setIsLoading,\n      onErrorChange: setError,\n      onStatusChange: setStatus,\n    }\n\n    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGeneration requires either a connection or fetcher option',\n    )\n  }, [clientId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    // Conditional spread: target uses strict-optional `body?: T`.\n    client.updateOptions({\n      ...(options.body !== undefined && { body: options.body }),\n    })\n  }, [client, options.body])\n\n  // Cleanup on unmount\n  useEffect(() => {\n    client.mountDevtools()\n\n    return () => {\n      client.dispose()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: TInput) => {\n      await client.generate(input)\n    },\n    [client],\n  )\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const reset = useCallback(() => {\n    client.reset()\n  }, [client])\n\n  return {\n    generate: generate as (input: Record<string, any>) => Promise<void>,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n  }\n}\n"],"names":[],"mappings":";;;AAgGO,SAAS,cAKd,SAG6E;AAE7E,QAAM,SAAS,MAAA;AACf,QAAM,WAAW,QAAQ,MAAM;AAE/B,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAyB,IAAI;AACzD,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,KAAK;AAChD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA4B,MAAS;AAC/D,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAgC,MAAM;AAElE,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,SAAS,QAAQ,MAAM;AAC3B,UAAM,OAAO,WAAW;AAMxB,UAAM,gBAAmE;AAAA,MACvE,IAAI;AAAA,MACJ,MAAM,KAAK;AAAA,MACX,uBAAuB;AAAA,MACvB,UAAU;AAAA,QACR,UAAU;AAAA,QACV,WAAW;AAAA,QACX,GAAG,KAAK;AAAA,MAAA;AAAA;AAAA;AAAA;AAAA,MAKV,WAAW,CAAC,MAAe,WAAW,QAAQ,WAAW,CAAC;AAAA,MAG1D,SAAS,CAAC,MAAa;AACrB,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,YAAY,CAAC,GAAW,MAAe;AACrC,mBAAW,QAAQ,aAAa,GAAG,CAAC;AAAA,MACtC;AAAA,MACA,SAAS,CAAC,MAAmB;AAC3B,mBAAW,QAAQ,UAAU,CAAC;AAAA,MAChC;AAAA,MACA,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,eAAe;AAAA,MACf,gBAAgB;AAAA,IAAA;AAGlB,QAAI,KAAK,YAAY;AACnB,aAAO,IAAI,iBAA2C;AAAA,QACpD,GAAG;AAAA,QACH,YAAY,KAAK;AAAA,MAAA,CAClB;AAAA,IACH;AAEA,QAAI,KAAK,SAAS;AAChB,aAAO,IAAI,iBAA2C;AAAA,QACpD,GAAG;AAAA,QACH,SAAS,KAAK;AAAA,MAAA,CACf;AAAA,IACH;AAEA,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ,GAAG,CAAC,QAAQ,CAAC;AAGb,YAAU,MAAM;AAEd,WAAO,cAAc;AAAA,MACnB,GAAI,QAAQ,SAAS,UAAa,EAAE,MAAM,QAAQ,KAAA;AAAA,IAAK,CACxD;AAAA,EACH,GAAG,CAAC,QAAQ,QAAQ,IAAI,CAAC;AAGzB,YAAU,MAAM;AACd,WAAO,cAAA;AAEP,WAAO,MAAM;AACX,aAAO,QAAA;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,WAAW;AAAA,IACf,OAAO,UAAkB;AACvB,YAAM,OAAO,SAAS,KAAK;AAAA,IAC7B;AAAA,IACA,CAAC,MAAM;AAAA,EAAA;AAGT,QAAM,OAAO,YAAY,MAAM;AAC7B,WAAO,KAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,QAAM,QAAQ,YAAY,MAAM;AAC9B,WAAO,MAAA;AAAA,EACT,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"use-generation.js","names":[],"sources":["../../src/use-generation.ts"],"sourcesContent":["import { GenerationClient } from '@tanstack/ai-client'\nimport { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'\nimport { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  AIDevtoolsDisplayOptions,\n  ConnectConnectionAdapter,\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n  GenerationPersistenceOptions,\n  GenerationRestoredResult,\n  InferGenerationOutputFromReturn,\n} from '@tanstack/ai-client'\n\n/**\n * Options for the useGeneration hook.\n *\n * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\nexport interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {\n  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */\n  connection?: ConnectConnectionAdapter\n  /** Direct async function for one-shot generation (no streaming protocol needed) */\n  fetcher?: GenerationFetcher<TInput, TResult>\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 a result is received. 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: TResult) => 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   * @internal Rebuild a typed result from a restored snapshot, injected by each\n   * specialized hook (image / speech / audio / transcription / summarize).\n   * Forwarded to the client so a server-hydrate restore repaints `result`.\n   */\n  reconstructResult?: (restored: GenerationRestoredResult) => TResult | null\n}\n\n/**\n * Return type for the useGeneration hook.\n *\n * @template TOutput - The output type (after optional transform)\n * @template TInput - The input type accepted by `generate` (defaults to any object)\n */\nexport interface UseGenerationReturn<\n  TOutput,\n  TInput extends Record<string, any> = Record<string, any>,\n> {\n  /** Trigger a generation request */\n  generate: (input: TInput) => Promise<void>\n  /** The generation result, or null if not yet generated */\n  result: TOutput | null\n  /** Whether a generation is currently in progress */\n  isLoading: boolean\n  /** Current error, if any */\n  error: Error | undefined\n  /** Current state of the generation client */\n  status: GenerationClientState\n  /** Abort the current generation */\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 * Generic React hook for one-shot generation tasks.\n *\n * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,\n * `useTranscription`, and `useSummarize`. You can also use it directly\n * for custom generation types.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```tsx\n * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({\n *   connection: fetchServerSentEvents('/api/generate/custom'),\n * })\n *\n * await generate({ prompt: 'Hello' })\n * ```\n */\n// `TTransformed` infers from the `onResult` return position (a covariant\n// inference site that works even for an optional nested property), which types\n// the callback parameter as `TResult` and narrows `result`. Inferring the\n// whole callback as a defaulted type parameter instead collapses to the\n// default, leaving the parameter `any` — a hard error under `strict`. See\n// issue #848.\nexport function useGeneration<\n  TInput extends Record<string, any>,\n  TResult,\n  TTransformed = void,\n>(\n  options: Omit<\n    UseGenerationOptions<TInput, TResult>,\n    'onResult' | 'persistence' | 'threadId' | 'id'\n  > & {\n    onResult?: (result: TResult) => TTransformed\n  } & GenerationPersistenceOptions,\n): UseGenerationReturn<\n  InferGenerationOutputFromReturn<TResult, TTransformed>,\n  TInput\n> {\n  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>\n  const hookId = useId()\n  // Single identity: prefer `threadId`; deprecated `id` only when no threadId.\n  const clientIdentity = options.threadId ?? options.id ?? hookId\n\n  const [result, setResult] = useState<TOutput | null>(null)\n  const [isLoading, setIsLoading] = useState(false)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [status, setStatus] = useState<GenerationClientState>('idle')\n  const [runId, setRunId] = useState<string | null>(null)\n\n  const optionsRef = useRef(options)\n  optionsRef.current = options\n  const disposedRef = useRef(false)\n\n  const client = useMemo(() => {\n    const opts = optionsRef.current\n\n    // Conditional spread for `body` (strict-optional in target;\n    // local source is `Record<string, any> | undefined`). Callbacks\n    // wrap optional ones in non-returning bodies so `?.()`'s\n    // implicit `undefined` doesn't pollute the function return type.\n    // Identity: pass `threadId` alone when set (never also pass deprecated `id`).\n    const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {\n      body: opts.body,\n      ...(opts.threadId !== undefined\n        ? { threadId: opts.threadId }\n        : { id: opts.id ?? hookId }),\n      ...(opts.persistence !== undefined && { persistence: opts.persistence }),\n      ...(opts.hydrateGeneration !== undefined && {\n        hydrateGeneration: opts.hydrateGeneration,\n      }),\n      ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),\n      ...(opts.reconstructResult\n        ? { reconstructResult: opts.reconstructResult }\n        : {}),\n      devtoolsBridgeFactory: createGenerationDevtoolsBridge,\n      devtools: {\n        hookName: 'useGeneration',\n        framework: 'react',\n        ...opts.devtools,\n      },\n      // The transform's raw return type (`TTransformed`) and the stored output\n      // (`TOutput`, with null/void/undefined stripped) are identical at runtime;\n      // the cast bridges the relationship that the conditional type hides.\n      onResult: ((r: TResult) => optionsRef.current.onResult?.(r)) as (\n        result: TResult,\n      ) => TOutput | null | void,\n      onError: (e: Error) => {\n        if (!disposedRef.current) optionsRef.current.onError?.(e)\n      },\n      onProgress: (p: number, m?: string) => {\n        if (!disposedRef.current) optionsRef.current.onProgress?.(p, m)\n      },\n      onChunk: (c: StreamChunk) => {\n        if (!disposedRef.current) optionsRef.current.onChunk?.(c)\n      },\n      onResultChange: (r) => {\n        if (!disposedRef.current) setResult(r)\n      },\n      onLoadingChange: (l) => {\n        if (!disposedRef.current) setIsLoading(l)\n      },\n      onErrorChange: (e) => {\n        if (!disposedRef.current) setError(e)\n      },\n      onStatusChange: (s) => {\n        if (!disposedRef.current) setStatus(s)\n      },\n      onResumeStateChange: (rs) => {\n        if (!disposedRef.current) setRunId(rs?.runId ?? null)\n      },\n    }\n\n    if (opts.connection) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        connection: opts.connection,\n      })\n    }\n\n    if (opts.fetcher) {\n      return new GenerationClient<TInput, TResult, TOutput>({\n        ...clientOptions,\n        fetcher: opts.fetcher,\n      })\n    }\n\n    throw new Error(\n      'useGeneration requires either a connection or fetcher option',\n    )\n  }, [clientIdentity, hookId])\n\n  // Sync body changes without recreating client\n  useEffect(() => {\n    // Conditional spread: target uses strict-optional `body?: T`.\n    client.updateOptions({\n      ...(options.body !== undefined && { body: options.body }),\n    })\n  }, [client, options.body])\n\n  // Mount devtools and clean up on unmount. Generation runs are never\n  // auto-started on mount — persisted state is only displayed. Mounting\n  // revives the client after a StrictMode dispose → remount replay.\n  useEffect(() => {\n    disposedRef.current = false\n    client.mountDevtools()\n\n    return () => {\n      disposedRef.current = true\n      client.dispose()\n    }\n  }, [client])\n\n  const generate = useCallback(\n    async (input: TInput) => {\n      await client.generate(input)\n    },\n    [client],\n  )\n\n  const stop = useCallback(() => {\n    client.stop()\n  }, [client])\n\n  const reset = useCallback(() => {\n    client.reset()\n  }, [client])\n\n  return {\n    generate,\n    result,\n    isLoading,\n    error,\n    status,\n    stop,\n    reset,\n    runId,\n  }\n}\n"],"mappings":"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"}

package/dist/esm/use-mcp-app-bridge.js

@@ -1,26 +1,49 @@
-import { useRef, useMemo } from "react";
 import { createMcpAppBridge } from "@tanstack/ai-client";
+import { useMemo, useRef } from "react";
+//#region src/use-mcp-app-bridge.ts
+/**
+* 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.
+*/
 function useMcpAppBridge(options) {
-  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options;
-  const chatRef = useRef(chat);
-  chatRef.current = chat;
-  const onLinkRef = useRef(onLink);
-  onLinkRef.current = onLink;
-  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) : void 0
-    }),
-    [threadId, callEndpoint, fetchImpl, hasOnLink]
-  );
+	const { threadId, callEndpoint, chat, fetchImpl, onLink } = options;
+	const chatRef = useRef(chat);
+	chatRef.current = chat;
+	const onLinkRef = useRef(onLink);
+	onLinkRef.current = onLink;
+	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) : void 0
+	}), [
+		threadId,
+		callEndpoint,
+		fetchImpl,
+		hasOnLink
+	]);
 }
-export {
-  useMcpAppBridge
-};
-//# sourceMappingURL=use-mcp-app-bridge.js.map
+//#endregion
+export { useMcpAppBridge };
+
+//# sourceMappingURL=use-mcp-app-bridge.js.map

package/dist/esm/use-mcp-app-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-mcp-app-bridge.js","sources":["../../src/use-mcp-app-bridge.ts"],"sourcesContent":["import { useMemo, useRef } from 'react'\nimport { createMcpAppBridge } from '@tanstack/ai-client'\nimport type {\n  CreateMcpAppBridgeOptions,\n  McpAppBridge,\n} from '@tanstack/ai-client'\n\nexport type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions\n\n/**\n * React wrapper around `createMcpAppBridge` that returns a **stable** bridge for\n * the given `threadId`/`callEndpoint`, while always invoking the latest\n * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating\n * the bridge on every render and the stale-closure / `exhaustive-deps` dance\n * you'd otherwise write by hand:\n *\n * ```tsx\n * const { sendMessage } = useChat({ threadId, connection })\n * const bridge = useMcpAppBridge({\n *   threadId,\n *   callEndpoint: '/api/mcp-apps-call',\n *   chat: { sendMessage: async (content) => void sendMessage(content) },\n *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),\n * })\n * // pass `bridge` to <MCPAppResource bridge={bridge} … />\n * ```\n *\n * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or\n * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`\n * each render does not churn it.\n */\nexport function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {\n  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options\n\n  // Latest-value refs so the bridge identity stays stable but its callbacks are\n  // never stale (the bridge calls `.current` at invocation time, not creation).\n  const chatRef = useRef(chat)\n  chatRef.current = chat\n  const onLinkRef = useRef(onLink)\n  onLinkRef.current = onLink\n\n  // Whether a link handler was supplied governs the bridge's link behavior\n  // (forward vs. display-only warn), so it's part of the bridge's identity.\n  const hasOnLink = onLink != null\n\n  return useMemo(\n    () =>\n      createMcpAppBridge({\n        threadId,\n        callEndpoint,\n        fetchImpl,\n        chat: {\n          sendMessage: (content, body) =>\n            chatRef.current.sendMessage(content, body),\n        },\n        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,\n      }),\n    [threadId, callEndpoint, fetchImpl, hasOnLink],\n  )\n}\n"],"names":[],"mappings":";;AA+BO,SAAS,gBAAgB,SAA+C;AAC7E,QAAM,EAAE,UAAU,cAAc,MAAM,WAAW,WAAW;AAI5D,QAAM,UAAU,OAAO,IAAI;AAC3B,UAAQ,UAAU;AAClB,QAAM,YAAY,OAAO,MAAM;AAC/B,YAAU,UAAU;AAIpB,QAAM,YAAY,UAAU;AAE5B,SAAO;AAAA,IACL,MACE,mBAAmB;AAAA,MACjB;AAAA,MACA;AAAA,MACA;AAAA,MACA,MAAM;AAAA,QACJ,aAAa,CAAC,SAAS,SACrB,QAAQ,QAAQ,YAAY,SAAS,IAAI;AAAA,MAAA;AAAA,MAE7C,QAAQ,YAAY,CAAC,QAAQ,UAAU,UAAU,GAAG,IAAI;AAAA,IAAA,CACzD;AAAA,IACH,CAAC,UAAU,cAAc,WAAW,SAAS;AAAA,EAAA;AAEjD;"}
+{"version":3,"file":"use-mcp-app-bridge.js","names":[],"sources":["../../src/use-mcp-app-bridge.ts"],"sourcesContent":["import { useMemo, useRef } from 'react'\nimport { createMcpAppBridge } from '@tanstack/ai-client'\nimport type {\n  CreateMcpAppBridgeOptions,\n  McpAppBridge,\n} from '@tanstack/ai-client'\n\nexport type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions\n\n/**\n * React wrapper around `createMcpAppBridge` that returns a **stable** bridge for\n * the given `threadId`/`callEndpoint`, while always invoking the latest\n * `chat.sendMessage` and `onLink` (kept in refs). This avoids both recreating\n * the bridge on every render and the stale-closure / `exhaustive-deps` dance\n * you'd otherwise write by hand:\n *\n * ```tsx\n * const { sendMessage } = useChat({ threadId, connection })\n * const bridge = useMcpAppBridge({\n *   threadId,\n *   callEndpoint: '/api/mcp-apps-call',\n *   chat: { sendMessage: async (content) => void sendMessage(content) },\n *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),\n * })\n * // pass `bridge` to <MCPAppResource bridge={bridge} … />\n * ```\n *\n * The bridge is recreated only when `threadId`, `callEndpoint`, `fetchImpl`, or\n * the *presence* of `onLink` changes — passing a new inline `onLink`/`sendMessage`\n * each render does not churn it.\n */\nexport function useMcpAppBridge(options: UseMcpAppBridgeOptions): McpAppBridge {\n  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options\n\n  // Latest-value refs so the bridge identity stays stable but its callbacks are\n  // never stale (the bridge calls `.current` at invocation time, not creation).\n  const chatRef = useRef(chat)\n  chatRef.current = chat\n  const onLinkRef = useRef(onLink)\n  onLinkRef.current = onLink\n\n  // Whether a link handler was supplied governs the bridge's link behavior\n  // (forward vs. display-only warn), so it's part of the bridge's identity.\n  const hasOnLink = onLink != null\n\n  return useMemo(\n    () =>\n      createMcpAppBridge({\n        threadId,\n        callEndpoint,\n        fetchImpl,\n        chat: {\n          sendMessage: (content, body) =>\n            chatRef.current.sendMessage(content, body),\n        },\n        onLink: hasOnLink ? (url) => onLinkRef.current?.(url) : undefined,\n      }),\n    [threadId, callEndpoint, fetchImpl, hasOnLink],\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,gBAAgB,SAA+C;CAC7E,MAAM,EAAE,UAAU,cAAc,MAAM,WAAW,WAAW;CAI5D,MAAM,UAAU,OAAO,IAAI;CAC3B,QAAQ,UAAU;CAClB,MAAM,YAAY,OAAO,MAAM;CAC/B,UAAU,UAAU;CAIpB,MAAM,YAAY,UAAU;CAE5B,OAAO,cAEH,mBAAmB;EACjB;EACA;EACA;EACA,MAAM,EACJ,cAAc,SAAS,SACrB,QAAQ,QAAQ,YAAY,SAAS,IAAI,EAC7C;EACA,QAAQ,aAAa,QAAQ,UAAU,UAAU,GAAG,IAAI,KAAA;CAC1D,CAAC,GACH;EAAC;EAAU;EAAc;EAAW;CAAS,CAC/C;AACF"}