openchamber/CHAT_PERF_PLAN.md

# Chat Session Performance Plan

## Goal

Reduce render cost and history-load latency when switching between chat sessions
in `packages/ui/src/components/chat/`, especially on Windows desktop with
projects that have a long-running chat history (50–500 messages per session,
tool-heavy workloads where each tool call returns 10–200 KB of output).

The plan is **strictly behavior-preserving**: every change keeps the visible
behavior 1:1 with the current build. Differences are only in the cost of doing
the work, not in the UX, layout, limits, persistence, or order of operations.

The two scenarios this targets:

- Switching between sessions in the sidebar (especially in/out of a session
  with a long history) — the main window currently blocks the main thread
  for 200–500 ms on first paint while `JSON.parse` + `materializeSessionSnapshots`
  + `projectTurnRecords` run synchronously over the full initial page.
- Returning to a session you visited a few minutes ago — the in-memory LRU
  (`SESSION_MESSAGE_RECORDS_CACHE_MAX = 40` desktop) helps, but the second
  visit to a session outside that window still pays the full network + parse
  cost.

A secondary goal is to avoid hammering the OpenCode server with large
single-shot fetches; we want smaller, more frequent, deduped requests.

## Upstream context

Before implementing, I scanned open/closed PRs for overlap and lessons:

- **#1651 — "perf: migrate chat rendering to virtua"** (`b920fd6f`, MERGED).
  Already moved chat history to `virtua` virtualization with `bufferSize: 900`
  and `MESSAGE_LIST_VIRTUALIZE_THRESHOLD = 5`, plus deferred Prism highlight,
  mermaid/file annotation, table listeners, stable plugin lists. This plan
  builds on top of that.
- **#1650 — "perf: instant startup via cache hydration + decoupled readiness"**
  (`c62f0d1c`, MERGED). Instant startup + decoupled readiness — orthogonal.
- **#1503 — "fix(chat): do not force scroll in thinking block during streaming"**
  (OPEN). Scroll behaviour during streaming — not in our hot path.
- **#1584 — "feat: improve long user message collapse, scrolling, and navigation"**
  (DRAFT). Touches long user messages; no direct conflict with this plan.
- **#1621 — "feat: comprehensive scrolling and navigation improvements"**
  (DRAFT). Broad scroll/navigation PR; no direct conflict.
- **#1282 — "Optimize large-session sidebar trees, switching UX, and chat
  scroll restore stability"** (CLOSED by maintainer). Introduced session-
  switching instability, selection/chat desync, optimistic transitions.
  Lesson: keep this plan focused on render-cost reduction and stable memoization;
  do NOT add optimistic transitions, backend search endpoints, scroll-
  restoration loops, or pagination on top of an unstable base.
- **#1448 — "feat: implement unified multi-server sidebar"** (DRAFT). Rewrites
  large parts of `SessionSidebar`. Independent of this plan.

There is currently NO open PR targeting the same render-cost or history-load
problems for the chat panel. We can proceed without coordination.

## Current Architecture Notes

### Data flow on session switch

1. `ChatContainer` subscribes to `currentSessionId` from `useSessionUIStore`.
2. `useSessionMessageRecords(currentSessionId, directory)` reads from the
   directory-scoped sync store via `React.useSyncExternalStore`. Snapshot
   cache: `SESSION_MESSAGE_RECORDS_CACHE_MAX = 40` desktop, `4` vscode/mobile.
3. `useChatTimelineController.turnWindowModel` is rebuilt via
   `buildTurnWindowModel(messages)` on first open of a session; cached per
   sessionId in module-level `turnModelCache` (max 30 desktop, 4 constrained).
4. `MessageList.baseDisplayMessages` reverses + dedupes + normalizes each
   message via `getNormalizedMessageForDisplay` (per-message `WeakMap` cache).
5. `useTurnRecords` projects turn records via `projectTurnRecords` (O(N) over
   messages + per-turn work for summary/activity/diffStats/changedFiles).
   `previousProjectionRef` stabilizes across re-renders, but there is no
   module-level projection cache — returning to a session after the component
   unmounts pays the full projection cost again.
6. `useChatTimelineController` runs the `useLayoutEffect` on `[sessionId]`
   that resets `isLoadingOlder`, `pendingRevealWork`, `activeTurnId`.

### Render hot path (current cost map)

- `ChatContainer` (990 lines) subscribes to the full directory `permission`
  and `question` records via `useDirectorySync((s) => s.permission ?? {})` and
  `useDirectorySync((s) => s.question ?? {})` (`ChatContainer.tsx:436-443`).
  Any `permission.asked` or `question.asked` event for any session in the
  same directory re-renders `ChatContainer` and re-runs the `permissionsMap` /
  `questionsMap` / `scopedSessionIds` / `sessionPermissions` / `sessionQuestions`
  / `sessionIsWorking` chain. Same for `useSessions(directory)` — every
  `session.updated` event for any session in the directory re-renders the
  container.
- `MessageList.reviewTransferDirection` (`MessageList.tsx:1151`) does
  `useGlobalSessionsStore((state) => { const currentSession = state.activeSessions.find(...) })`
  — runs `find` + `some` over the entire global active list on every global
  store change.
- `MessageList` already has a `useStableEvent(getAnimationHandlers)`,
  `useStableEvent(scrollToBottom)`, and a module-level `timelineCache` for
  the virtua cache snapshot — those are the right pattern, just not applied
  uniformly.
- `ChatMessage` (1182 lines) is `React.memo`-wrapped with
  `areRenderRelevantMessagesEqual` plus `areRelevantTurnGroupingContextsEqual`.
  `MessageBody` (2121 lines) is NOT `React.memo`-wrapped but is only
  rendered through `MessageRow` → `ChatMessage` and only re-runs when
  `areRenderRelevantMessagesEqual` returns false.

### The 1.5 MB problem

The OpenCode server (separate repo, `anomalyco/opencode`) responds to
`GET /api/session/{sessionID}/message` with
`Array<{ info: Message, parts: Part[] }>` (the v1 wire shape preserved in
the v2 SDK). On a typical tool-heavy session of 150 messages, this array
serializes to ~1.5 MB of JSON. The bulk is `ToolStateCompleted.output: string`
(confirmed in `node_modules/.bun/@opencode-ai+sdk@1.17.7/.../types.gen.d.ts:357-373`).

The OpenChamber web server (`packages/web/server/index.js:1115`) installs
Express `compression()` middleware BEFORE the OpenCode proxy
(`packages/web/server/lib/opencode/proxy.js`), so the response IS compressed
on the way out (5x reduction on typical JSON, so ~300 KB on the wire). The
proxy explicitly sets `accept-encoding: identity` (`proxy.js:629`) which is
a no-op against the upstream OpenCode server (it has no compression
middleware — `server.ts` uses raw `@effect/platform-node` NodeHttpServer).

So the **wire cost is ~300 KB after gzip**, not 1.5 MB. The real cost is the
**client-side main-thread blocking**:

- `JSON.parse` on 1.5 MB of structured data: ~50–200 ms in V8.
- `materializeSessionSnapshots`: O(N) sort/filter, ~10–20 ms for 150.
- `projectTurnRecords`: O(N) with per-turn work (summary/activity/diffStats/
  changedFiles/indexes), ~30–100 ms for 150.
- `useChatTimelineController.useLayoutEffect` re-resolves pending scroll
  requests and updates `historySignals` — fast but runs synchronously.

Total main-thread block on first paint: **200–500 ms**. The user-perceived
"long load" is mostly this.

### Limit constants (current)

| Constant                              | Value                             | Location              | Purpose                                 |
| ------------------------------------- | --------------------------------- | --------------------- | --------------------------------------- |
| `INITIAL_MESSAGE_PAGE_SIZE`             | 150 (desktop), 30 (vscode/mobile) | `use-sync.ts:25-27`     | First page on session switch            |
| `HISTORY_MESSAGE_PAGE_SIZE`             | 200                               | `use-sync.ts:28`        | Scroll-up pagination                    |
| `MESSAGE_REFETCH_LIMIT`                 | 200                               | `session-actions.ts:27` | Refetch after revert/abort              |
| `RECONNECT_MESSAGE_LIMIT`               | 30                                | `sync-context.tsx:193`  | Reconnect bootstrap                     |
| `SESSION_MATERIALIZATION_MESSAGE_LIMIT` | 30                                | `sync-context.tsx:194`  | Materialize on `message.updated` recovery |
| `DEFAULT_MESSAGE_LIMIT`                 | 200                               | `sessionTypes.ts:78`    | Declarative ceiling; not enforced       |

For 99% of sessions, users read the latest 30–50 messages and rarely scroll
beyond. The 150-initial / 200-history combination fetches ~3x more than the
visible window on first paint.

### Already optimized (do not touch)

- `MessageList` virtualization with `virtua` at threshold 5, bufferSize 900
  (PR #1651).
- `MessageRow` / `ChatMessage` / `TurnBlock` `React.memo` with custom
  comparators.
- `getNormalizedMessageForDisplay` per-message `WeakMap` cache.
- `MarkdownRenderer` lazy-loaded via `lazyWithChunkRecovery`; Prism highlight
  and mermaid deferred (PR #1651).
- `expandedToolsStateCache` and `collapsedToolsStateCache` module-level LRU
  bounded at 4000 (`ChatMessage.tsx:39-95`).
- `aggregateLiveSessions` / `aggregateLiveSessionStatuses` bail via
  `areSessionListsEquivalent` and `areStatusMapsEquivalent`; consumed through
  `useLiveSyncSelector`.
- `useStickyProjectHeaders` IntersectionObserver.
- Targeted field cloning in `handleDirectoryEvent` (sync/DOCUMENTATION.md).
- `turnModelCache` for `buildTurnWindowModel` (30 desktop, 4 vscode/mobile).
- `timelineCache` for virtua snapshot (max 16 sessions).
- `session-prefetch-cache` 15s TTL dedup of `syncSession` requests.
- `syncSessionInflightByKey` for in-flight dedup.

## Proposed Architecture

### Bugfix Layer 0 — Fix rapid project-switch race in sidebar

**Observed bug:** When connected from desktop to an OpenChamber server, with
multiple trees in the sidebar and large sessions (~200k context), rapidly
switching between recent sessions in different projects causes the focus to
follow the **fetch completion order** instead of the user's final click. The
sequence is: user clicks 1, then 2, then 3; UI briefly shows 3; when fetch 1
finishes it jumps to 1; when fetch 2 finishes it jumps to 2; when fetch 3
finishes it finally lands on 3.

**Root cause:** `useProjectSessionSelection` (`useProjectSessionSelection.ts`)
has auto-selection logic that runs when `activeProjectId` changes. Combined
with uncancelled async fetches and cross-project store updates, stale fetch
completions update the sidebar session lists, which re-triggers selection
fallbacks and overwrites the user's explicit choice.

**Fix — four parts:**

1. **Layer 0a — Generation guard in `useEnsureSessionMessages`.**
   Track a per-hook generation counter. When the effect fires for a new
   `sessionID`, increment the generation. Ignore the result (do not apply
   store mutations) if the generation is stale by the time the async fetch
   completes.

2. **Layer 0b — Generation guard in `syncSession` / `loadMessages`.**
   Add a module-level `Map<sessionKey, number>` tracking the latest requested
   generation per session. Before every store write inside `syncSession` and
   `loadMessages`, check that the request is still current. This prevents
   fetches 1 and 2 from mutating state after the user has already selected 3.

3. **Layer 0c — Debounce `handleSessionSelect`.**
   In `useSessionActions.ts`, wrap the actual navigation in a short timeout
   (~80ms). The first click executes immediately; rapid subsequent clicks
   cancel the pending navigation and reschedule for the latest target. This
   coalesces 1→2→3 into a single `setCurrentSession(3)` call.

4. **Layer 0d — Explicit-selection guard in `useProjectSessionSelection`.**
   Track the timestamp of the last explicit user selection. Suppress the
   auto-select fallback in the layout effect for ~500ms after an explicit
   click, so fallback logic never overwrites an active user choice.

**Effect:** Rapid project switching becomes deterministic: the UI stays on the
last clicked session and only loads its content. Stale fetches are silently
ignored instead of fighting for focus.

**Files:** `sync-context.tsx`, `use-sync.ts`, `useSessionActions.ts`,
`useProjectSessionSelection.ts`.

---

### Layer 1 — Narrow subscriptions in ChatContainer

**Problem:** `ChatContainer.tsx:436-443` subscribes to the **full directory**
`permission` and `question` records. Any permission/question event for **any**
session in the directory causes a ChatContainer re-render, even if the event
is for an unrelated session. Same for `useSessions(directory)` at line 427
— every `session.updated` event re-renders the container.

There are already session-scoped hooks (`useSessionPermissions(sessionID)`,
`useSessionQuestions(sessionID)` at `sync-context.tsx:2151,2165`), but they
don't aggregate across descendant subagent sessions — which
`collectVisibleSessionIdsForBlockingRequests` (`ChatContainer.tsx:458-464`)
handles for the `sessionPermissions` / `sessionQuestions` / `sessionIsWorking`
chain.

**Fix:** Replace the broad directory reads with scoped subtree selectors. The
subtree is the current session and all its descendant subagent sessions.

Add to `sync-context.tsx`:

- `useScopedSubtreeIds(sessionID: string | null, directory?: string): Set<string>`
  — returns the set of session IDs in the current subtree (current session +
  all descendants by `parentID`). Reference-stabilized: a new Set is only
  returned when the actual membership changes, using the same "compare
  contents, reuse reference" pattern as `areSessionListsEquivalent`.

- `useScopedBlockingRequests(sessionID: string | null, directory: string, kind: 'permission' | 'question')`
  — combines `useScopedSubtreeIds` with the existing `useSessionPermissions` /
  `useSessionQuestions` patterns to return a flat array of blocking requests
  scoped to the subtree only.

- `useParentSession(sessionID: string | null): Session | null` — returns
  the parent Session via a pre-computed `Map<sessionId, Session>` that only
  changes when the target session or its parent changes. Replaces the O(N)
  `.find()` at `ChatContainer.tsx:564`.

`ChatContainer` then:
- reads `useScopedBlockingRequests` instead of the full `allPermissions`/
  `allQuestions` → `permissionsMap` → `scopedSessionIds` → `sessionPermissions`
  / `sessionQuestions` chain.
- reads `useParentSession` instead of `sessions.find(...)`.
- stops subscribing to `useSessions(directory)` entirely (the subtree selectors
  provide all needed session data scoped to the active subtree).

**Effect:** Third-party sessions in the same directory stop re-rendering
ChatContainer. Streaming events for unrelated sessions no longer invalidate
the chat's blocking-requests chain.

**Files:** `ChatContainer.tsx`, `sync-context.tsx`.

---

### Layer 3 — Module-level projection cache

**Problem:** `useTurnRecords` keeps `previousProjectionRef` for in-component
stabilization, but a session that unmounts and remounts loses that ref. Full
re-projection cost is paid every time you return to a session.

**Fix:** Add a module-level LRU keyed by `sessionKey`. The cache key must
capture the exact identity of the message list to avoid stale projections:

```ts
// Includes: sessionKey, message count, last message id,
// AND the count of parts on the last message (detects streaming deltas
// that add parts to an existing message without changing id or count).
type CacheKey = `${sessionKey}|${length}|${lastMessageId ?? ''}|${lastMessagePartCount ?? 0}`
const projectionCache = new Map<CacheKey, { projection: TurnProjectionResult }>()
```

Including `lastMessagePartCount` is critical: during streaming, new parts are
appended to the same last message — the message ID and total message count
stay the same, but the projection must be recomputed.

Cap at the same limits as `turnModelCache` (30 desktop, 4 vscode/mobile)
to bound memory.

`useTurnRecords` consults the cache before running `projectTurnRecords`; on
hit, returns the cached projection and refreshes LRU order; on miss, runs the
full projection and writes the result.

**Effect:** Returning to a session within the LRU window is zero projection
work. Combined with `MessageList.timelineCache` (which already caches the
virtua snapshot), the first paint after a remount is essentially "rebuild
only what's strictly session-specific (resolvers, refs)".

**Files:** `useTurnRecords.ts` (small extension) + new helper
`lib/turns/turnProjectionCache.ts`.

---

### Layer 4a — Start message fetch synchronously in setCurrentSession

**Problem:** `session-ui-store.setCurrentSession` currently only calls
`setState` (Zustand). The actual message fetch is started by
`ChatContainer.useEffect` at `ChatContainer.tsx:787-792`, which runs on the
render AFTER the state update — adding one React commit cycle (~30–80 ms)
of latency before the network request starts.

**Fix:** Start the fetch directly from `setCurrentSession` on the same tick
as the state update, using the existing imperative access layer.

The approach uses `session-actions.ts`, which already has module-level refs
(`_sdk`, `_childStores`, `_getDirectory` — `session-actions.ts:33-35`) set by
SyncProvider at mount time. Add a `fetchMessagesForSession(sessionID: string)`
function there that duplicates the core path from `useSync().syncSession`:
checks the child store for existing messages, fetches from SDK if needed,
calls `materializeSessionSnapshots`, and writes to the directory store.

`setCurrentSession` then calls `fetchMessagesForSession(targetId)` immediately
after `set({ currentSessionId: id, ... })`. The `syncSessionInflightByKey`
in `use-sync.ts` doesn't cover this new path, so the function also uses the
existing `_ensureMessagesLoading` Set in `sync-context.tsx` (line 2668) for
dedup.

The existing `ChatContainer.useEffect` at line 787 stays as a safety net for
sessions restored from URL or other non-sidebar entry points.

**Effect:** Fetch starts on the same tick as the state update, ~30–80 ms
earlier than the current "wait for React commit → useEffect → fetch" path.

**Files:** `session-ui-store.ts` (one new call in `setCurrentSession`),
`session-actions.ts` (new `fetchMessagesForSession` function).

---

### Layer 5 — Small wins

- **`reviewTransferDirection` pre-computed map.** In
  `MessageList.tsx:1151-1164`, replace
  `useGlobalSessionsStore((state) => state.activeSessions.find(...))` with
  a selector that reads a pre-computed `Map<sessionId, ReviewTransferDirection>`
  maintained by `useGlobalSessionsStore` (built once per active-sessions
  change, in the same reducer that updates `activeSessions`). Same selector
  shape from the component's perspective, but no `.find()` + `.some()` on
  every global store change.

- **`parentSession` lookup.** Part of Layer 1 (see `useParentSession` hook
  above). The pre-computed `Map<sessionId, Session>` is maintained in
  `sync-context.tsx` and read via the hook, eliminating the O(N) `.find()`
  in `ChatContainer`.

**Files:** `MessageList.tsx`, `useGlobalSessionsStore.ts`.

---

### Layer 6a — Reduce initial payload

Lower the page sizes to match typical user reading patterns:

- `INITIAL_MESSAGE_PAGE_SIZE`: 150 → 50 (desktop), 30 stays (vscode/mobile).
- `HISTORY_MESSAGE_PAGE_SIZE`: 200 → 100.
- `MESSAGE_REFETCH_LIMIT`: 200 → 100.
- `DEFAULT_MESSAGE_LIMIT` in `sessionTypes.ts`: stays 200 (it's a ceiling,
  not a fetch target).

**How the "load more" indicator still works with a smaller initial page:**
`historyMeta` in ChatContainer is built from `sync.hasMore(currentSessionId)`,
which reads `meta.current` (set immediately after the first `loadMessages`
call, before the component renders). If the server returns a cursor,
`sync.hasMore()` returns `true` → `historyMeta.complete = false` →
`hasMoreAboveTurns = true` → scroll-up indicator appears correctly.
The `messages.length >= defaultLimit` fallback is never reached in practice
because `historyMeta` is populated before the first render of the chat.

Effect on the 1.5 MB problem:

- Initial fetch payload: 1.5 MB → ~500 KB parsed (50 messages).
- JSON.parse cost: 100–200 ms → 30–70 ms.
- projection cost: 30–100 ms → 10–30 ms.
- Combined main-thread block: 200–500 ms → 50–150 ms.

User cost: one extra round trip when scrolling past the 50th message. The
scroll-triggered `loadMore` is already in place and is the right UX for "I
want to see older messages" — the previous behavior of "fetch 150 and ignore
100" was wasted work for the common case.

**Files:** `use-sync.ts`, `session-actions.ts`.

---

### Layer 6b — Progressive mount

`use-sync.syncSession` starts the initial 50-message page synchronously.
After the first page resolves, if the cursor indicates more messages, a
second fetch of `HISTORY_MESSAGE_PAGE_SIZE` (100 messages) is dispatched
via `loadMessages(sessionID, { before: cursor, mode: "prepend" })` — the
prepend mode already exists in `loadMessages` (`use-sync.ts:373`). This
second page is non-blocking; the user sees the first 50 messages immediately.

On the client side, `useTurnRecords` and `useChatTimelineController` must
re-run projection when the prepended messages arrive. Two options:

- **Simple:** Let the full re-projection run on the second page arrival
  (50→150 messages). With Layer 6a, projection of 150 messages is ~10–30 ms —
  fast enough that a one-time re-project on the second page is acceptable.

- **Optimal:** Extend `updateTurnWindowModelIncremental` (currently handles
  only +1 message appends — `windowTurns.ts:76-84` checks
  `nextMessages.length !== previousMessages.length + 1`) to handle batch
  prepends. This requires:
  1. A new `updateTurnWindowModelBatchPrepend` that verifies the new messages
     are all prepended (all existing message references match at the tail)
     and projects only the new messages into turn windows.
  2. A corresponding `updateTurnProjectionIncremental` in `projectTurnRecords.ts`
     that merges the new turns into the existing projection.

  Because `updateTurnWindowModelIncremental` is designed for single-message
  streaming deltas (not batch prepends), this is non-trivial additional work.
  Given Layer 6a alone reduces the main-thread block to ~50–150 ms, start
  with the simple approach and measure before committing to the incremental
  path.

**Net effect:** The first 50 messages mount within the same time as today
(possibly faster, because parsing 500 KB < parsing 1.5 MB). The next 100
arrive ~200–400 ms later. From the user's perspective, the chat becomes
interactive immediately.

**Files:** `use-sync.ts`, `ChatContainer.tsx` (small — no change to `loadMore` UX).

---

## What I do not propose to touch (and why)

- `useChatAutoFollow` and the scroll-restoration logic in
  `useChatTimelineController` (the `prePrependScrollRef` / height-delta
  compensation). PR #1282 closed because of scroll-restore regressions;
  these are working and tested.
- The event-pipeline coalescing and `message.part.delta` reducer path.
  Already correct (sync/DOCUMENTATION.md).
- The Markdown renderer and Prism highlight deferral. PR #1651 already took
  the low-hanging fruit.
- The `key={currentSessionId}` on `<ChatViewport>`. Forces a full remount,
  which is expensive, but a previous PR attempt (Layer 2 in the sidebar
  plan) regressed scroll/follow. Keeping the remount for now.
- The OpenCode server response shape. It's in `anomalyco/opencode`, which
  AGENTS.md forbids us from touching.
- The SDK's internal `JSON.parse` step. Replacing it with a streaming
  parser requires owning the fetch call (the SDK doesn't expose the
  `ReadableStream`), and the response is a single JSON array, not NDJSON —
  so streaming buys us the same "first N visible, rest in background"
  pattern that Layer 6b already implements.
- Tool output lazy-load. Would need a server-side endpoint like
  `GET /api/session/{sid}/part/{partID}` that the OpenCode server does
  not currently provide.

## Expected effect

- **Initial session switch on a 150-message tool-heavy session:**
  main-thread block 200–500 ms → 50–150 ms. ~3x faster.
- **Wire payload on the same session:** 1.5 MB parsed → 500 KB parsed.
  After gzip, ~300 KB → ~100 KB.
- **Returning to a session within the LRU window:** zero projection work
  (Layer 3), zero scroll-cache rebuild (existing `timelineCache`).
- **Returning to a session outside the LRU window:** same as initial, but
  the 15s `session-prefetch-cache` TTL catches sessions visited twice in
  rapid succession.
- **Server load:** the OpenCode server processes 1/3 the volume per
  session-switch, and the warm second page in Layer 6b is deduped
  against the inflight request. Strictly less load than today.

## Files Touched by the Plan

- `CHAT_PERF_PLAN.md` (new, this file)
- `packages/ui/src/sync/sync-context.tsx` (Bugfix Layer 0a — `useEnsureSessionMessages` guard)
- `packages/ui/src/sync/use-sync.ts` (Bugfix Layer 0b — `syncSession`/`loadMessages` guard; Layer 6a — constants)
- `packages/ui/src/components/session/sidebar/hooks/useSessionActions.ts` (Bugfix Layer 0c — debounce)
- `packages/ui/src/components/session/sidebar/hooks/useProjectSessionSelection.ts` (Bugfix Layer 0d — explicit-selection guard)
- `packages/ui/src/components/chat/ChatContainer.tsx` (Layers 1, 6b)
- `packages/ui/src/components/chat/MessageList.tsx` (Layer 5a)
- `packages/ui/src/stores/useGlobalSessionsStore.ts` (Layer 5a — pre-computed map)
- `packages/ui/src/sync/sync-context.tsx` (Layer 1 — new hooks: `useScopedSubtreeIds`, `useScopedBlockingRequests`, `useParentSession`)
- `packages/ui/src/sync/session-ui-store.ts` (Layer 4a — call fetch from `setCurrentSession`)
- `packages/ui/src/sync/session-actions.ts` (Layer 4a — new `fetchMessagesForSession`, Layer 6a — constants)
- `packages/ui/src/sync/use-sync.ts` (Layer 6a — constants, Layer 6b — progressive fetch)
- `packages/ui/src/stores/types/sessionTypes.ts` (Layer 6a — sync `DEFAULT_MESSAGE_LIMIT` with new constants)
- `packages/ui/src/components/chat/hooks/useTurnRecords.ts` (Layer 3 — projection cache)
- `packages/ui/src/components/chat/lib/turns/turnProjectionCache.ts` (new, Layer 3)

## Implementation order

1. **Bugfix Layer 0** (race condition fixes) — highest priority, fixes the
   observed sidebar switching bug before any optimization work.
2. **Layer 6a** (reduce constants) — simplest performance win, also reduces
   the race window.
3. **Layer 3** (projection cache) — isolated change, immediate return-visit win.
4. **Layer 5a** (reviewTransfer map) — isolated, low risk.
5. **Layer 1** (narrow subscriptions) — more complex but well-bounded.
6. **Layer 4a** (early fetch) — depends on Layer 1 for dedup safety.
7. **Layer 6b** (progressive mount) — highest complexity, implement after
   measuring real-world gains from 6a.

## Conflict risks

- None of the open PRs touch the files above in a conflicting way. PR #1584
  (draft, long user message collapse) modifies `UserTextPart.tsx`, not the
  files we touch. PR #1621 (draft, comprehensive scrolling) modifies scroll
  and navigation components, not the chat data flow. PR #1448 (draft,
  unified multi-server sidebar) is for `SessionSidebar.tsx` and family, not
  the chat panel.
- Existing internal benchmarks for `event-pipeline` are unaffected
  (Layers 1, 3, 4a, 5, 6 do not touch event coalescing or ordering).
- `bun run type-check` and `bun run lint` must remain green.

## Open Questions

1. **Layer 2 (drop `key={currentSessionId}` from `ChatViewport`):** explicitly
   out of scope per user. Revisit after the lower-risk layers ship.
2. **Layer 7 (Web Worker for `JSON.parse` + materialize):** out of scope.
   The Layer 6a/6b combo should bring main-thread block to ~50–150 ms,
   which is acceptable. Revisit if real-user feedback still shows jank.
3. **Layer 6b incremental projection for batch prepends:** start with the
   simple full-reproject-on-second-page approach (50→150 projection is
   ~10–30 ms post-Layer-6a). Only build the incremental path if benchmarks
   show the full reproject is still noticeable.
4. **Layer 3 cache invalidation during streaming:** the `lastMessagePartCount`
   in the cache key catches part deltas on the last message. If the streaming
   model appends parts to a message that is NOT the last (e.g., tool output
   on a completed turn while a new turn is streaming), the cache would miss —
   which is correct (projection must re-run). Confirm this edge case during
   smoke testing.