TanStack · AlemTuzlak · Aug 19, 2026 · Aug 19, 2026 · coderabbitai · Aug 19, 2026
diff --git a/.changeset/ssr-thread-identity.md b/.changeset/ssr-thread-identity.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-client': patch
+'@tanstack/ai-react': patch
+'@tanstack/ai-preact': patch
+'@tanstack/ai-vue': patch
+'@tanstack/ai-solid': patch
+'@tanstack/ai-svelte': patch
+'@tanstack/ai-angular': patch
+---
+
+Mint omitted `threadId` after the view mounts, not during render. DevTools binds the hook row to `threadId`. Persistence that is on (`true` or a storage adapter) requires a `threadId` at compile time, and throws at runtime if it is missing. Chat and generation clients no longer accept a separate `id` option. Use `threadId`.
diff --git a/docs/api/ai-angular.md b/docs/api/ai-angular.md
@@ -52,8 +52,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client` (minus internal state cal
 - `fetcher?` - Direct async function for one-shot generation (alternative to `connection`)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field. Reactive — accepts a plain value, an Angular `Signal`, or a zero-arg getter; changes sync automatically via `effect`
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire. Reactive (same forms as `forwardedProps`)
 - `context?` - Typed client-local runtime context passed to client tool implementations. Reactive (same forms). This value is not serialized to the server
@@ -380,7 +379,7 @@ export class CustomGenerationComponent {
 }
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?` (reactive), `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `threadId?`, `body?` (reactive), `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `runId`. All reactive state is a read-only `Signal<T>`.
 

diff --git a/docs/api/ai-client.md b/docs/api/ai-client.md
@@ -95,8 +95,7 @@ goes away. Users of the framework hooks need no change.
 
 - `connection` - Connection adapter for streaming
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works — values are merged into `forwardedProps` on the wire and mirrored under the legacy `data` field for backward compatibility
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server

diff --git a/docs/api/ai-preact.md b/docs/api/ai-preact.md
@@ -73,8 +73,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 - `connection` - Connection adapter (required)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server

diff --git a/docs/api/ai-react.md b/docs/api/ai-react.md
@@ -83,8 +83,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 - `connection` - Connection adapter (required)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server

diff --git a/docs/api/ai-solid.md b/docs/api/ai-solid.md
@@ -74,8 +74,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 - `connection` - Connection adapter (required)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server

diff --git a/docs/api/ai-svelte.md b/docs/api/ai-svelte.md
@@ -72,8 +72,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client` (minus internal state cal
 - `connection` - Connection adapter (required)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server
@@ -297,7 +296,7 @@ const gen = createGeneration({
 // gen.result, gen.isLoading, gen.error, gen.status
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `threadId?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `runId`, `updateBody` -- all state properties are reactive getters.
 

diff --git a/docs/api/ai-vue.md b/docs/api/ai-vue.md
@@ -70,8 +70,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client` (minus internal state cal
 - `connection` - Connection adapter (required)
 - `tools?` - Array of client tool implementations (with `.client()` method)
 - `initialMessages?` - Initial messages array
-- `id?` - Unique identifier for this chat instance
-- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
+- `threadId?` - The only identity for this chat. Required when persistence is on. If omitted, minted after mount.
 - `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (reactive -- changes are synced automatically via `watch`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire (reactive)
 - `context?` - Typed client-local runtime context passed to client tool implementations (reactive). This value is not serialized to the server
@@ -314,7 +313,7 @@ const { generate, result, isLoading, error, status, stop, reset } =
   });
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `threadId?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `runId` -- all reactive state is `DeepReadonly<ShallowRef<T>>`.
 

diff --git a/docs/config.json b/docs/config.json
@@ -29,7 +29,7 @@
           "label": "Devtools",
           "to": "getting-started/devtools",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-22"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "Quick Start: Vue",
@@ -284,7 +284,8 @@
         {
           "label": "Id Map",
           "to": "persistence/id-map",
-          "addedAt": "2026-08-04"
+          "addedAt": "2026-08-04",
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "Keep Generated Files",
@@ -410,7 +411,7 @@
           "label": "Generations",
           "to": "media/generations",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-04"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "Realtime Voice Chat",
@@ -446,7 +447,7 @@
           "label": "Image Generation",
           "to": "media/image-generation",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-18"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "Video Generation",
@@ -458,7 +459,7 @@
           "label": "Generation Hooks",
           "to": "media/generation-hooks",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-30"
+          "updatedAt": "2026-08-19"
         }
       ]
     },
@@ -752,43 +753,43 @@
           "label": "@tanstack/ai-client",
           "to": "api/ai-client",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-04"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-react",
           "to": "api/ai-react",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-solid",
           "to": "api/ai-solid",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-preact",
           "to": "api/ai-preact",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-vue",
           "to": "api/ai-vue",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-30"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-svelte",
           "to": "api/ai-svelte",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-30"
+          "updatedAt": "2026-08-19"
         },
         {
           "label": "@tanstack/ai-angular",
           "to": "api/ai-angular",
           "addedAt": "2026-06-15",
-          "updatedAt": "2026-07-30"
+          "updatedAt": "2026-08-19"
         }
       ]
     },

diff --git a/docs/getting-started/devtools.md b/docs/getting-started/devtools.md
@@ -58,7 +58,7 @@ import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
 
 export function ImageStudio() {
   const image = useGenerateImage({
-    id: 'generation-hooks:useGenerateImage',
+    threadId: 'generation-hooks:useGenerateImage',
     connection: fetchServerSentEvents('/api/image'),
     devtools: {
       name: 'Image Studio',

diff --git a/docs/media/generation-hooks.md b/docs/media/generation-hooks.md
@@ -397,7 +397,7 @@ function EmbeddingGenerator() {
 |--------|------|-------------|
 | `connection` | `ConnectConnectionAdapter` | Streaming transport (SSE, HTTP stream, custom) |
 | `fetcher` | `GenerationFetcher<TInput, TResult>` | Direct async function (no streaming protocol needed) |
-| `id` | `string` | Unique identifier for this generation instance |
+| `threadId` | `string` | Stable scope for this generation. Required when `persistence` is on. Optional for ephemeral runs. |
 | `body` | `Record<string, any>` | Additional body parameters sent with connection requests |
 | `onResult` | `(result: TResult) => TOutput \| null \| void` | Transform or react to results |
 | `onError` | `(error: Error) => void` | Error callback |

diff --git a/docs/media/generations.md b/docs/media/generations.md
@@ -250,7 +250,7 @@ All generation hooks share the same interface:
 |--------|------|-------------|
 | `connection` | `ConnectionAdapter` | Streaming transport (SSE, HTTP stream, custom) |
 | `fetcher` | `(input) => Promise<Result \| Response>` | Direct async function, or server function returning an SSE `Response` |
-| `id` | `string` | Unique identifier for this instance |
+| `threadId` | `string` | Stable scope for this generation. Required when `persistence` is on. Optional for ephemeral runs. |
 | `body` | `Record<string, any>` | Additional body parameters (connection mode) |
 | `onResult` | `(result) => T \| null \| void` | Transform or react to the result |
 | `onError` | `(error) => void` | Error callback |

diff --git a/docs/media/image-generation.md b/docs/media/image-generation.md
@@ -460,7 +460,7 @@ The `useGenerateImage` hook accepts:
 | ------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 | `connection` | `ConnectionAdapter`                                     | Streaming transport (SSE, HTTP stream, custom)                                                 |
 | `fetcher`    | `(input) => Promise<ImageGenerationResult \| Response>` | Direct async function, or server function returning an SSE `Response`                          |
-| `id`         | `string`                                                | Unique identifier for this instance                                                            |
+| `threadId`   | `string`                                                | Stable scope for this generation. Required when `persistence` is on. Optional for ephemeral runs. |
 | `body`       | `Record<string, any>`                                   | Additional body parameters (connection mode)                                                   |
 | `onResult`   | `(result) => TOutput \| null \| void`                   | Callback when images are generated. Optionally return a transformed value to store as `result` |
 | `onError`    | `(error) => void`                                       | Callback on error                                                                              |

diff --git a/docs/persistence/id-map.md b/docs/persistence/id-map.md
@@ -27,6 +27,14 @@ broken.
 Persistence stores and restores by `threadId`. `runId` is what you read when you
 need to talk to your own server about the execution happening right now.
 
+If you omit `threadId`, the client mints one after the view mounts. That
+ephemeral id is the wire thread and the DevTools row for this session. A reload
+starts a new conversation. Persistence needs an explicit `threadId` from your
+app.
+
+Do not pass a separate `id`. `threadId` is the only identity on chat and
+generation clients.
+
 ```tsx
 import {
   fetchServerSentEvents,
@@ -251,10 +259,10 @@ option. Chat is the same shape: the `threadId` you pass `useChat` is the one
 
 ## When you can skip `threadId`
 
-Without persistence, `threadId` is optional. The hooks fall back to a generated id
-purely to satisfy the protocol, which requires a thread id on the wire. The run
-works, it just cannot be found again, which is fine for a one-shot image you show
-and forget.
+Without persistence, `threadId` is optional. After the view mounts, the client
+mints an ephemeral thread id to satisfy the protocol. That id is also the
+DevTools row for the session. The run works, it just cannot be found again,
+which is fine for a one-shot image you show and forget.
 
 Turn `persistence` on and `threadId` becomes required, on the hook and on the
 activity the middleware wraps. `withGenerationPersistence` throws when neither

diff --git a/packages/ai-angular/src/inject-chat.ts b/packages/ai-angular/src/inject-chat.ts
@@ -41,8 +41,6 @@ import type {
 const EMPTY_INTERRUPTS = Object.freeze([])
 const EMPTY_INTERRUPT_ERRORS = Object.freeze([])
 
-let nextId = 0
-
 export function injectChat<
   const TTools extends ReadonlyArray<AnyClientTool> = any,
   TSchema extends SchemaInput | undefined = undefined,
@@ -61,7 +59,6 @@ export function injectChat<
 
   const destroyRef = inject(DestroyRef)
   const injector = inject(Injector)
-  const clientId = options.id || `injectChat-${nextId++}`
 
   const messages = signal<Array<UIMessage<TTools>>>(
     options.initialMessages || [],
@@ -100,18 +97,21 @@ export function injectChat<
   const client = new ChatClient<TTools, TContext>({
     devtoolsBridgeFactory: createChatDevtoolsBridge,
     ...transport,
-    id: clientId,
     ...(options.initialMessages !== undefined && {
       initialMessages: options.initialMessages,
     }),
-    ...(options.persistence !== undefined && {
-      persistence: options.persistence,
-    }),
+    ...(typeof options.threadId === 'string' && options.persistence
+      ? {
+          persistence: options.persistence,
+          threadId: options.threadId,
+        }
+      : {
+          ...(options.threadId !== undefined && { threadId: options.threadId }),
+        }),
     ...(options.initialResumeSnapshot !== undefined && {
       initialResumeSnapshot: options.initialResumeSnapshot,
     }),
     ...(bodySource !== undefined && { body: bodySource() }),
-    ...(options.threadId !== undefined && { threadId: options.threadId }),
     ...(forwardedPropsSource !== undefined && {
       forwardedProps: forwardedPropsSource(),
     }),

diff --git a/packages/ai-angular/src/inject-generate-audio.ts b/packages/ai-angular/src/inject-generate-audio.ts
@@ -32,10 +32,6 @@ export interface InjectGenerateAudioOptions<
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
   fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
-  /**
-   * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
-   */
-  id?: string
   /** Additional body parameters to send with connect-based adapter requests. Reactive. */
   body?: ReactiveOption<Record<string, any>>
   /** Display options for TanStack AI Devtools. */
@@ -110,7 +106,7 @@ export interface InjectGenerateAudioResult<
 export function injectGenerateAudio<TTransformed = void>(
   options: Omit<
     InjectGenerateAudioOptions,
-    'onResult' | 'persistence' | 'threadId' | 'id'
+    'onResult' | 'persistence' | 'threadId'
   > & {
     onResult?: (result: AudioGenerationResult) => TTransformed
   } & GenerationPersistenceOptions,

diff --git a/packages/ai-angular/src/inject-generate-image.ts b/packages/ai-angular/src/inject-generate-image.ts
@@ -33,7 +33,7 @@ export interface InjectGenerateImageResult<
 export function injectGenerateImage<TTransformed = void>(
   options: Omit<
     InjectGenerateImageOptions,
-    'onResult' | 'persistence' | 'threadId' | 'id'
+    'onResult' | 'persistence' | 'threadId'
   > & {
     onResult?: (result: ImageGenerationResult) => TTransformed
   } & GenerationPersistenceOptions,

diff --git a/packages/ai-angular/src/inject-generate-speech.ts b/packages/ai-angular/src/inject-generate-speech.ts
@@ -34,7 +34,7 @@ export interface InjectGenerateSpeechResult<TOutput = TTSResult> extends Omit<
 export function injectGenerateSpeech<TTransformed = void>(
   options: Omit<
     InjectGenerateSpeechOptions,
-    'onResult' | 'persistence' | 'threadId' | 'id'
+    'onResult' | 'persistence' | 'threadId'
   > & {
     onResult?: (result: TTSResult) => TTransformed
   } & GenerationPersistenceOptions,