feat: configurable client-side message queue for useChat

.changeset/message-queue.md

@@ -0,0 +1,14 @@
+---
+'@tanstack/ai-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-vue': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-preact': minor
+---
+
+Messages sent while a stream is already in flight are now queued by default and automatically sent once the in-flight stream settles, instead of being silently dropped. **This is a behavior change.**
+
+The behavior is configurable via a new `queue` option, which accepts `whenBusy: 'queue' | 'drop' | 'interrupt'`, `drain: 'fifo' | 'batch'`, `maxSize`, and `onOverflow`, or a custom strategy function for full control.
+
+Queued messages are exposed on the hook as `queue` and can be cancelled before they send via `cancelQueued(id)`. `sendMessage` also accepts a per-call `{ whenBusy }` override.

docs/chat/streaming.md

@@ -203,13 +203,62 @@ export async function POST(request: Request) {
 }
 ```
 
+## Queueing Messages
+
+By default, calling `sendMessage` while a stream is already in flight **queues** the message instead of dropping it — it sends automatically once the current run settles. Configure this with the `queue` option, which accepts a `QueueConfig` object, a plain shorthand string, or a strategy function:
+
+```tsx group=queueing-messages
+import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
+
+const { messages, queue, sendMessage, cancelQueued, isLoading } = useChat({
+  connection: fetchServerSentEvents("/api/chat"),
+  queue: { whenBusy: "queue", drain: "fifo", maxSize: 5 },
+});
+```
+
+- **`whenBusy`** — what happens to a send that arrives mid-stream:
+  - `"queue"` (default) — hold the message; it sends once the stream settles.
+  - `"drop"` — ignore the send.
+  - `"interrupt"` — abort the current stream (like calling `stop()`) and send the new message immediately.
+- **`drain`** — how queued items leave the queue: `"fifo"` (default) sends them one at a time in order; `"batch"` merges everything currently queued into a single send once the stream settles (string contents joined with `\n`, multimodal content concatenated in order).
+- **`maxSize`** — caps how many messages can be queued.
+- **`onOverflow`** — `"reject"` (default) ignores a send once `maxSize` is reached; `"drop-oldest"` evicts the oldest queued item to make room.
+
+You can also pass a plain `WhenBusy` string (e.g. `queue: "interrupt"`) as shorthand for `{ whenBusy: "interrupt" }` — this applies for any `WhenBusy` value (`"queue"`, `"drop"`, or `"interrupt"`), not just `"interrupt"` — or a `QueueStrategy` function for full control over the per-send decision (the drain order stays FIFO for the function form).
+
+`useChat` exposes the pending queue as `queue` so you can render it distinctly from `messages`, along with `cancelQueued(id)` to cancel an item before it sends:
+
+```tsx group=queueing-messages
+function PendingQueue() {
+  return (
+    <>
+      {queue.map((q) => (
+        <div key={q.id} className="pending">
+          {typeof q.content === "string" ? q.content : "[attachment]"}
+          <button onClick={() => cancelQueued(q.id)}>Cancel</button>
+        </div>
+      ))}
+    </>
+  );
+}
+```
+
+Override the configured policy for a single send with the second argument to `sendMessage`:
+
+```tsx group=queueing-messages
+sendMessage("Never mind, do this instead", { whenBusy: "interrupt" });
+```
+
+> **Note:** This is a default-behavior change — messages sent while streaming used to be silently dropped. They are now queued unless you opt into `whenBusy: "drop"` or `"interrupt"`.
+
 ## Best Practices
 
 1. **Handle loading states** - Use `isLoading` to show loading indicators
 2. **Handle errors** - Check `error` state for stream failures
 3. **Cancel on unmount** - Clean up streams when components unmount
 4. **Optimize rendering** - Batch updates if needed for performance
 5. **Show progress** - Display partial content as it streams
+6. **Render queued messages distinctly** - Use `queue` to show pending sends separately from `messages`
 
 ## Next Steps
 

docs/config.json

@@ -157,7 +157,7 @@
           "label": "Streaming",
           "to": "chat/streaming",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-03"
+          "updatedAt": "2026-07-06"
         },
         {
           "label": "Connection Adapters",

examples/ts-react-chat/src/components/Header.tsx

@@ -10,6 +10,7 @@ import {
   Guitar,
   Home,
   Image,
+  Layers,
   Menu,
   LayoutGrid,
   Mic,
@@ -231,6 +232,19 @@ export default function Header() {
             <span className="font-medium">Persistent Chats</span>
           </Link>
 
+          <Link
+            to="/queueing"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Layers size={20} />
+            <span className="font-medium">Queueing Strategies</span>
+          </Link>
+
           <Link
             to="/example/runtime-context"
             onClick={() => setIsOpen(false)}

examples/ts-react-chat/src/routeTree.gen.ts

@@ -13,6 +13,7 @@ import { Route as ThreadsRouteImport } from './routes/threads'
 import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as SandboxesRouteImport } from './routes/sandboxes'
 import { Route as RealtimeRouteImport } from './routes/realtime'
+import { Route as QueueingRouteImport } from './routes/queueing'
 import { Route as McpDemoRouteImport } from './routes/mcp-demo'
 import { Route as McpAppsRouteImport } from './routes/mcp-apps'
 import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-result'
@@ -74,6 +75,11 @@ const RealtimeRoute = RealtimeRouteImport.update({
   path: '/realtime',
   getParentRoute: () => rootRouteImport,
 } as any)
+const QueueingRoute = QueueingRouteImport.update({
+  id: '/queueing',
+  path: '/queueing',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const McpDemoRoute = McpDemoRouteImport.update({
   id: '/mcp-demo',
   path: '/mcp-demo',
@@ -287,6 +293,7 @@ export interface FileRoutesByFullPath {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/queueing': typeof QueueingRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -333,6 +340,7 @@ export interface FileRoutesByTo {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/queueing': typeof QueueingRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -380,6 +388,7 @@ export interface FileRoutesById {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/queueing': typeof QueueingRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -428,6 +437,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/queueing'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -474,6 +484,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/queueing'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -520,6 +531,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/queueing'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -567,6 +579,7 @@ export interface RootRouteChildren {
   Issue176ToolResultRoute: typeof Issue176ToolResultRoute
   McpAppsRoute: typeof McpAppsRoute
   McpDemoRoute: typeof McpDemoRoute
+  QueueingRoute: typeof QueueingRoute
   RealtimeRoute: typeof RealtimeRoute
   SandboxesRoute: typeof SandboxesRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
@@ -635,6 +648,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof RealtimeRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/queueing': {
+      id: '/queueing'
+      path: '/queueing'
+      fullPath: '/queueing'
+      preLoaderRoute: typeof QueueingRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/mcp-demo': {
       id: '/mcp-demo'
       path: '/mcp-demo'
@@ -927,6 +947,7 @@ const rootRouteChildren: RootRouteChildren = {
   Issue176ToolResultRoute: Issue176ToolResultRoute,
   McpAppsRoute: McpAppsRoute,
   McpDemoRoute: McpDemoRoute,
+  QueueingRoute: QueueingRoute,
   RealtimeRoute: RealtimeRoute,
   SandboxesRoute: SandboxesRoute,
   ServerFnChatRoute: ServerFnChatRoute,