fix(react): throttle useChat messages snapshot to prevent maximum update depth error

[takumiz19]

Background

useChat re-renders past throttle / experimental_throttle and can hit React's "Maximum update depth exceeded" during streaming on slower devices (Android, heavy markdown, CPU throttling). Reported in #6166.

The root cause is a mismatch between what experimental_throttle throttles and what actually drives re-renders. useChat subscribes to messages via useSyncExternalStore:

const messages = useSyncExternalStore(
  subscribeToMessages,
  () => chatRef.current.messages, // getSnapshot
  () => chatRef.current.messages,
);

The throttle was applied only to the subscribe callback (~registerMessagesCallback). But replaceMessage swaps #messages for a new array on every chunk, and that is exactly what getSnapshot() returned. useSyncExternalStore re-reads getSnapshot() on every render and, when the reference differs from the rendered one, forces a synchronous re-render (tearing prevention). That path never goes through subscribe, so throttling the subscribe callback did not limit it — during streaming the array reference changes on essentially every commit, so React re-renders per chunk regardless of the throttle. Once renders fall behind chunk arrival it trips the nested-update limit.

This matches the reports in the thread: it is machine/load dependent (a threshold, not a hard infinite loop), and raising the throttle / using chunking: 'line' / memoizing markdown only reduces how much work each forced render does, rather than capping the re-render count.

Summary

Keep the published snapshot separate from the internal message buffer so that getSnapshot() returns a stable reference between throttle windows:

• ReactChatState now holds #messages (internal buffer, always current — used by AbstractChat for slicing/finding/replacing) and a separate #messagesSnapshot (the reference React reads).
• Throttling is moved onto the state itself: #publishMessages swaps #messagesSnapshot = #messages and notifies subscribers together, and that whole publish is throttled. So the notification and the snapshot are throttled in lockstep, and experimental_throttle behaves as documented.
• useChat's getSnapshot now reads chatRef.current.messagesSnapshot instead of messages.

When throttling is disabled (the default) publishing is synchronous, so behavior is unchanged.

End-to-End Verification

Reproduced with a long streamed response under Chrome DevTools 6x CPU throttling: before this change, experimental_throttle: 100 did not prevent "Maximum update depth exceeded"; after it, streaming stays throttled and no longer trips the limit.

The added regression test (does not bypass throttling when the component re-renders for an unrelated reason) fails on main (an unrelated re-render mid-window shows the un-throttled buffered content) and passes with this change. The full @ai-sdk/react suite (90 tests) passes.

Checklist

• All commits are signed (PRs with unsigned commits cannot be merged)
• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

Related Issues

Fixes #6166

[ai-sdk-factory]

Bugfix review

Outcome: changes-required

Fixes issue

Status: partially-addresses

The stable published snapshot fixes the reported throttle bypass for a single useChat subscriber, but shared Chat instances can still have throttling disabled or changed by another subscriber.

Concerns:

• Each registration overwrites the single state-wide throttle configuration, so the most recently registered useChat hook controls publishing for every subscriber.
• The repository documents sharing one Chat between useChat({ chat, throttle: 50 }) and useChat({ chat }); this supported pattern can defeat the protection or unexpectedly throttle the second hook.

Side effects

Risk: medium

Moving throttling from individual callbacks into shared Chat state makes previously independent hook options interfere with one another.

Concerns:

• Two hooks using the same Chat with different throttle values no longer receive their independently configured update behavior.
• The state retains its last throttle configuration after subscribers unsubscribe, allowing later mutations or remounts to observe delayed snapshots.

Performance

Risk: medium

A second unthrottled subscriber can globally disable snapshot throttling and restore the high-frequency rendering behavior responsible for the reported performance failure.

Concerns:

• Focused verification showed that changing subscriber registration order changed whether consecutive updates were published immediately or throttled.
• Message mutations continue scheduling the retained state-level throttle even after all message subscribers have been removed.

Backwards compatibility

Risk: none

The change does not alter persisted message formats, storage, serialization, or existing stored data.

Breaking changes

Risk: medium

Public types and accepted inputs remain compatible, but the externally observable semantics of the public throttle option change for shared Chat instances.

Concerns:

• A hook's throttle behavior now depends on other mounted hooks and subscription order rather than only its own option.
• An unthrottled hook may become throttled, while a throttled hook may become unthrottled, which is incompatible with the documented per-useChat option behavior.

Architecture

Risk: medium

Package boundaries remain intact, but subscriber-specific React configuration is incorrectly owned by the shared Chat state.

Concerns:

• ReactChatState represents a shared store with multiple callbacks, while throttle is supplied independently by each useChat subscription; collapsing these into one global state value creates cross-subscriber coupling.
• The snapshot caching direction follows React's useSyncExternalStore contract, but the snapshot must preserve independent subscriber behavior rather than use last-registration-wins state.

Change scope

Status: minimal

The implementation, focused regression test, and patch changeset are all directly related to the reported bug.

Security

Risk: none

No credential handling, network validation, parsing, authorization, or other security-sensitive behavior is changed.

Testing

Status: needs-more

The new test covers unrelated re-renders for one subscriber, but omits supported shared-Chat and subscription-lifecycle cases exposed by the implementation.

Concerns:

• Add a regression test with multiple useChat hooks sharing one Chat and using different throttle values, including one hook with no throttle.
• Test dynamic throttle changes and unmount/remount behavior, including pending publications from an earlier throttle configuration.

Verification

Inspected all four changed files, the React Chat and AbstractChat state contracts, public exports, documentation examples, and throttle implementation. The @ai-sdk/react suite passed all 90 tests, targeted type checking and diff validation passed, and focused state verification demonstrated that subscriber registration order currently determines the global snapshot throttle. React's official useSyncExternalStore snapshot contract was also checked.

Relevant Documentation

• https://react.dev/reference/react/useSyncExternalStore

[gr2m]

closing in favor of #18525