fix(ai-react): replace the client a hidden <Activity> disposed when it shows again

.changeset/use-chat-hidden-activity.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-react': patch
+---
+
+`useChat` keeps working in a view hidden by React's `<Activity>`. Hiding runs the hook's effect cleanups, and the deferred teardown disposed the client while React kept the hook, so the view came back with a dead client: a reply in flight never resumed and the thread did not load again. When the view shows again, `useChat` now replaces the disposed client with a new one that starts from the messages on screen, loads the thread and rejoins its run.

docs/api/ai-react.md

@@ -121,6 +121,44 @@ State values are plain React values. The hook renders again when they change.
 | `partial`, `final` | Structured output. Only when you pass `outputSchema`. |
 | `subagents` | Live child-agent runs. See [Subagents](../chat/subagents). |
 
+### Hidden views
+
+You can keep a chat mounted while it is hidden, for example in `<Activity mode="hidden">`. A hidden chat holds no connection to the server.
+
+When the chat shows again, `useChat` starts a new client for the same thread, with the messages that were on screen. With `persistence: true`, the client loads the thread again and joins the run that is in progress.
+
+```tsx
+import { Activity, useState } from "react";
+import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
+
+function Chat() {
+  const { messages } = useChat({
+    connection: fetchServerSentEvents("/api/chat"),
+    threadId: "support-chat",
+    persistence: true,
+  });
+
+  return <p>{messages.length} messages</p>;
+}
+
+export function Tabs() {
+  const [tab, setTab] = useState<"chat" | "settings">("chat");
+
+  return (
+    <div>
+      <button onClick={() => setTab(tab === "chat" ? "settings" : "chat")}>
+        Switch tab
+      </button>
+      <Activity mode={tab === "chat" ? "visible" : "hidden"}>
+        <Chat />
+      </Activity>
+    </div>
+  );
+}
+```
+
+To join a run, the server needs the `GET` handler from [Resumable Streams](../resumable-streams/overview).
+
 ### Example: tool approval
 
 A tool with `needsApproval: true` pauses the run. The pending call shows up in `interrupts`.

docs/config.json

@@ -2010,7 +2010,7 @@
           "label": "@tanstack/ai-react",
           "to": "api/ai-react",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-10-21"
+          "updatedAt": "2026-10-24"
         },
         {
           "label": "@tanstack/ai-solid",

packages/ai-react/src/use-chat.ts

@@ -51,6 +51,16 @@ export function useChat<
     client: ChatClient
     timeout: ReturnType<typeof setTimeout>
   } | null>(null)
+  // A client the deferred teardown disposed while the hook stayed mounted: a
+  // hidden `<Activity>` keeps state and memos, runs the effect cleanups, and
+  // runs the effects again when it shows. The teardown replaces the client,
+  // which starts from the messages it had on screen for the same thread, so
+  // the hook never renders a disposed client.
+  const disposedClientRef = useRef<{
+    client: ChatClient
+    threadId: string | undefined
+  } | null>(null)
+  const [clientRevision, setClientRevision] = useState(0)
 
   // Track current options in a ref to avoid recreating client when options change
   const optionsRef =
@@ -63,7 +73,11 @@ export function useChat<
   // restores the same conversation. User callbacks read latest options.
   const { client, initialization, serverSnapshot, startPersistenceHydration } =
     useMemo(() => {
-      const messagesToUse = options.initialMessages || []
+      const disposed = disposedClientRef.current
+      const messagesToUse =
+        disposed && disposed.threadId === options.threadId
+          ? disposed.client.getMessages()
+          : options.initialMessages || []
 
       const initialOptions = optionsRef.current
       const { persistence, release: releasePersistenceHydration } =
@@ -184,7 +198,7 @@ export function useChat<
         serverSnapshot: capturedServerSnapshot,
         startPersistenceHydration: releasePersistenceHydration,
       }
-    }, [options.threadId])
+    }, [options.threadId, clientRevision])
 
   useEffect(() => {
     activeClientRef.current = client
@@ -287,6 +301,9 @@ export function useChat<
   }, [client, startPersistenceHydration])
 
   useEffect(() => {
+    disposedClientRef.current = null
+    // The options this client was made with, as committed alongside it.
+    const threadId = optionsRef.current.threadId
     if (cleanupDisposalRef.current?.client === client) {
       clearTimeout(cleanupDisposalRef.current.timeout)
       cleanupDisposalRef.current = null
@@ -309,7 +326,9 @@ export function useChat<
       // later; calling `stop()` would abort a constructor rejoin
       // (`resumeInFlightRun`) and can wipe the durable resume pointer before
       // the first chunk. Real teardown lives in the deferred dispose path
-      // below, which only runs when the client is not remounted.
+      // below, which only runs when the client is not remounted. A hidden
+      // `<Activity>` runs it too and keeps the hook: the teardown then replaces
+      // the disposed client.
       // Subscribe/unsubscribe on `options.live` is still owned by the
       // dedicated effect above for live toggles.
       const disposal = {
@@ -321,6 +340,12 @@ export function useChat<
             client.stop()
           }
           client.dispose()
+          // Replace it only if the hook has no newer client: on a new
+          // threadId the new client is active by now, and stays.
+          if (activeClientRef.current === null) {
+            disposedClientRef.current = { client, threadId }
+            setClientRevision((revision) => revision + 1)
+          }
           if (cleanupDisposalRef.current === disposal) {
             cleanupDisposalRef.current = null
           }

packages/ai-react/tests/use-chat.test.ts

@@ -2,9 +2,11 @@ import { EventType } from '@tanstack/ai'
 import { ChatClient } from '@tanstack/ai-client'
 import { act, render, renderHook, waitFor } from '@testing-library/react'
 import {
+  Activity,
   StrictMode,
   Suspense,
   createElement,
+  useEffect,
   useLayoutEffect,
   useState,
 } from 'react'
@@ -3184,4 +3186,244 @@ describe('useChat', () => {
       )
     })
   })
+
+  describe('inside a hidden <Activity>', () => {
+    // React keeps a hidden Activity's state and memos but runs its effect
+    // cleanups, then runs the effects again when it shows. A view hidden for
+    // longer than a tick must come back with a working client.
+    function createRunServer() {
+      const chunks: Array<StreamChunk> = []
+      const waiters = new Set<() => void>()
+      let done = false
+      const push = (...next: Array<StreamChunk>) => {
+        chunks.push(...next)
+        for (const wake of waiters) wake()
+        waiters.clear()
+      }
+      // The run's durable log: from the start, then live until it ends.
+      async function* tail(signal?: AbortSignal) {
+        let read = 0
+        for (;;) {
+          if (signal?.aborted) return
+          if (read < chunks.length) {
+            yield chunks[read++]!
+            continue
+          }
+          if (done) return
+          await new Promise<void>((resolve) => {
+            waiters.add(resolve)
+            signal?.addEventListener('abort', () => resolve(), { once: true })
+          })
+        }
+      }
+      const hydrate = vi.fn(async (_threadId: string) => ({
+        messages: [],
+        activeRun: chunks.length > 0 && !done ? { runId: 'r1' } : null,
+        interrupts: null,
+      }))
+      const joinRun = vi.fn((_runId: string, signal?: AbortSignal) =>
+        tail(signal),
+      )
+      const connection: ResumableConnectConnectionAdapter = {
+        connect: (_messages, _data, signal) => {
+          push(
+            {
+              type: EventType.RUN_STARTED,
+              runId: 'r1',
+              threadId: 't1',
+              timestamp: 1,
+            },
+            {
+              type: EventType.TEXT_MESSAGE_START,
+              messageId: 'a1',
+              role: 'assistant',
+              timestamp: 2,
+            },
+          )
+          return tail(signal)
+        },
+        joinRun,
+        hydrate,
+      }
+      return {
+        connection,
+        hydrate,
+        joinRun,
+        say: (delta: string) =>
+          push({
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: 'a1',
+            delta,
+            timestamp: 3,
+          }),
+        finish: () => {
+          push(
+            { type: EventType.TEXT_MESSAGE_END, messageId: 'a1', timestamp: 4 },
+            {
+              type: EventType.RUN_FINISHED,
+              runId: 'r1',
+              threadId: 't1',
+              finishReason: 'stop',
+              timestamp: 5,
+            },
+          )
+          done = true
+        },
+      }
+    }
+
+    function renderInActivity(connection: ResumableConnectConnectionAdapter) {
+      let mode: 'visible' | 'hidden' = 'visible'
+      const rendered = renderHook(
+        ({ threadId }: { threadId: string }) =>
+          useChat({ connection, threadId, persistence: true }),
+        {
+          initialProps: { threadId: 't1' },
+          wrapper: ({ children }) =>
+            createElement(Activity, { mode, children }),
+        },
+      )
+      const show = (shown: boolean, threadId = 't1') => {
+        mode = shown ? 'visible' : 'hidden'
+        rendered.rerender({ threadId })
+      }
+      return { ...rendered, show }
+    }
+
+    const assistantText = (messages: ReadonlyArray<UIMessage>) => {
+      const part = messages
+        .find((m) => m.role === 'assistant')
+        ?.parts.find((p) => p.type === 'text')
+      return part && 'content' in part ? part.content : undefined
+    }
+    // Longer than the tick the hook waits before it disposes a client whose
+    // effects did not run again.
+    const outlastDisposal = () =>
+      act(() => new Promise<void>((resolve) => setTimeout(resolve, 10)))
+
+    it('rejoins the run a hidden view left when it shows again', async () => {
+      const server = createRunServer()
+      const { result, show } = renderInActivity(server.connection)
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+
+      act(() => {
+        void result.current.sendMessage('hi')
+      })
+      server.say('Hel')
+      await waitFor(() =>
+        expect(assistantText(result.current.messages)).toBe('Hel'),
+      )
+
+      act(() => show(false))
+      await outlastDisposal()
+      server.say('lo')
+      act(() => show(true))
+      server.finish()
+
+      await waitFor(() =>
+        expect(assistantText(result.current.messages)).toBe('Hello'),
+      )
+      expect(server.joinRun).toHaveBeenCalledWith('r1', expect.anything())
+      expect(result.current.status).toBe('ready')
+    })
+
+    it('shows again with the new client, never the disposed one', async () => {
+      const server = createRunServer()
+      // What the view's own effects read, as they run on each commit.
+      const loadingInEffects: Array<boolean> = []
+      let mode: 'visible' | 'hidden' = 'visible'
+      const { result, rerender } = renderHook(
+        () => {
+          const chat = useChat({
+            connection: server.connection,
+            threadId: 't1',
+            persistence: true,
+          })
+          useEffect(() => {
+            loadingInEffects.push(chat.isHydrating)
+          })
+          return chat
+        },
+        {
+          wrapper: ({ children }) =>
+            createElement(Activity, { mode, children }),
+        },
+      )
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+
+      mode = 'hidden'
+      rerender()
+      await outlastDisposal()
+      const shownAt = loadingInEffects.length
+      mode = 'visible'
+      rerender()
+
+      // The effects that run as the view shows read a client that loads the
+      // thread, not the idle snapshot of the client the teardown disposed.
+      expect(loadingInEffects[shownAt]).toBe(true)
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+    })
+
+    it('keeps the transcript on screen after an idle hide', async () => {
+      const server = createRunServer()
+      const { result, show } = renderInActivity(server.connection)
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+      act(() => {
+        void result.current.sendMessage('hi')
+      })
+      server.say('Hello')
+      server.finish()
+      await waitFor(() => expect(result.current.status).toBe('ready'))
+
+      act(() => show(false))
+      await outlastDisposal()
+      const loads = server.hydrate.mock.calls.length
+      act(() => show(true))
+
+      // The new client loads the thread, and the server sends no messages.
+      await waitFor(() => {
+        expect(server.hydrate.mock.calls.length).toBeGreaterThan(loads)
+        expect(result.current.isHydrating).toBe(false)
+      })
+      expect(assistantText(result.current.messages)).toBe('Hello')
+    })
+
+    it('keeps the client of a new thread, and disposes only the old one', async () => {
+      const server = createRunServer()
+      const { result, show } = renderInActivity(server.connection)
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+
+      act(() => show(true, 't2'))
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+      await outlastDisposal()
+      await outlastDisposal()
+
+      // The old thread's teardown disposes its own client, not the new one:
+      // the new thread loads once and stays loaded.
+      const loadsOfT2 = server.hydrate.mock.calls.filter(
+        ([threadId]) => threadId === 't2',
+      )
+      expect(loadsOfT2).toHaveLength(1)
+      expect(result.current.isHydrating).toBe(false)
+    })
+
+    it('starts another thread empty when it shows on a new threadId', async () => {
+      const server = createRunServer()
+      const { result, show } = renderInActivity(server.connection)
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+      act(() => {
+        void result.current.sendMessage('hi')
+      })
+      server.say('Hello')
+      server.finish()
+      await waitFor(() => expect(result.current.status).toBe('ready'))
+
+      act(() => show(false))
+      await outlastDisposal()
+      act(() => show(true, 't2'))
+
+      await waitFor(() => expect(result.current.isHydrating).toBe(false))
+      expect(result.current.messages).toEqual([])
+    })
+  })
 })

testing/e2e/README.md

@@ -98,6 +98,7 @@ Notes:
 | `tests/delivery-durability.spec.ts`    | Transport layer: offset-tagged log, `Last-Event-ID` reconnect, second-tab join, SSE + NDJSON                                                                |
 | `tests/persistence-durability.spec.ts` | Client layer: a browser refresh restores the conversation and any pending interrupt                                                                         |
 | `tests/join-run-client-tool.spec.ts`   | Mid-run reload: `joinRun` replay that ends on a client tool drains the continuation (issue #1058)                                                           |
+| `tests/use-chat-hidden-view.spec.ts`   | Client layer: a chat that `<Activity>` hides mid-reply loads the thread and joins the run when it shows again                                               |
 | `tests/sandbox-durability.spec.ts`     | Sandbox instances: a second run resumes the persisted sandbox                                                                                               |
 | `tests/durable-takeover.spec.ts`       | Takeover with log alignment, detach-on-disconnect, out-of-band cancel in both bands, cancel-vs-disconnect divergence, and the superseded-driver epoch fence |