perf(desktop): virtualize message timeline to stop the cold-switch beachball

[wpfleger96]

buzz beachballs on every main-nav transition (channel switch, Home/inbox, Agents menu) and on the first thread-open after a channel switch on v0.3.25. The synchronous block is the message timeline: a channel switch streams up to 200 (CHANNEL_HISTORY_LIMIT) uncontained MessageRows — each with synchronous shiki markdown — then useTimelineScrollManager fires scrollToBottom("auto") from a useLayoutEffect, and alignToBottom does a synchronous scrollHeight read-then-write that forces a full-document reflow over all 200 rows before paint. The Agents-menu stall is a separate cause: a React.lazy route chunk with no preload.

This windows the main timeline on @tanstack/react-virtual, eliminating the reflow at its root, plus a route-chunk preload for the lazy stall.

What changed

Flatten the heterogeneous tree. The day-grouped <section> tree is flattened to a typed TimelineItem[] discriminated-union stream (day-divider / unread-divider / system / message / thread-summary) in a pure lib builder. The same single walk produces the messageId -> itemIndex map, so the stream and the map cannot drift. A single useMemo keyed on [deferredMessages, firstUnreadMessageId] owns both — firstUnreadMessageId is load-bearing because the unread-divider item shifts indices.

Re-path every scroll path onto the index model. Windowing removes off-screen rows from the DOM, so the old querySelector('[data-message-id]') lookups would silently fail for any off-screen target. scrollToMessage, in-channel search-jump, jump-to-oldest-unread, scrollToBottom, and the load-older prepend anchor now resolve through the index map instead of the DOM. Load-older captures the first-visible item index before fetch and re-aims at oldFirstIndex + N after the prepend, restoring the intra-row offset.

Split scroll convergence. @tanstack/react-virtual owns offset convergence — its internal rAF loop re-runs getOffsetForIndex as off-screen rows mount and measureElement corrects their estimated heights. A pure reducer (scrollConvergence.ts) owns only what the library cannot: it re-resolves the target's index by id every frame, so a concurrent prepend or delete that shifts the target re-aims the library instead of stranding it on a stale index; it terminates with converged: false if the target is deleted mid-settle, and caps at 32 frames. A thin rAF adapter (useConvergentScrollToMessage.ts) drives the virtualizer and re-issues scrollToIndex only when the index moves, so a steady settle does not reset the library's stable-frame counter.

Thread reply list gets content-visibility: auto rather than virtualization. It is bounded (replies to one root), unpaginated, ungrouped, and shares useTimelineScrollManager — virtualizing it would force a second index re-path on the shared hook and a head/prologue split for no beachball gain. content-visibility: auto skips layout for off-screen reply rows while keeping them DOM-resident, so the shared deep-link path still works there.

Route-chunk preload (Phase 2). agents.tsx, channels.$channelId.tsx, and ChannelScreenLazyViews.ts export preload*() for their React.lazy chunks; a single idle-gated effect in AppShell.tsx warms all three once startup is ready, clearing the Agents-menu first-visit stall.

Tests

The breaking math lives in lib/ under the .mjs suite: convergence within the 32-frame cap on mixed measured/estimated heights, landing within tolerance, termination when a row keeps re-measuring, target-removed-mid-settle terminating with converged: false, and the staleness re-resolve. The builder tests gate divider placement (3-day channel, unread divider mid-day-2) and map index correctness across new-message / prepend / delete.

[wpfleger96]

Superseded by #1123 — the hybrid work (virtualization + single-owner anchored scroll + role-3 convergence + spinner slot) lives there, rebased onto eva and now CI-unblocked.