refactor(ui): stream the transcript incrementally instead of re-deriving it per token

[Astro-Han]

Summary

PR B of #2030. Refs #2030 — PR A (the @astryxdesign/core tooltip patch) is independent, touches no file here, and is not substitutable for this: during streaming the tail turn's footer is a placeholder with no buttons, so the two remove different work.

The transcript simulated incremental updates by re-deriving the whole view model per token and trusting memo's reference comparison to work out which turns had not changed. Two links in that chain were not idempotent, so the guess was wrong:

• Per delta. overlayShellRunUpdates re-folded from its original input on every render and never wrote its derived result back. A background command's durable revision permanently leads the tool_result snapshot persisted in messages, so merged.changed stayed true forever and the owning turn was rebuilt on every token.
• Per phase boundary. Every refreshMessages replaced every turn wholesale, roughly 2 × steps + tools times per answer.

createTranscriptProjection owns that derived state instead of re-deriving it: it remembers the settled turns and hands the previous object back for any turn a message refresh did not actually change. valuesEqual is the only judge of "did not change", and it is the only place identity is decided.

turn.tools and turn.timeline were two structures carrying the same tools, each rewritten separately. The timeline is now the single tool authority and tools is flattened out of it, which also makes the rewrite pass idempotent.

Fixing the projection alone delivers nothing. TurnView is a shallow-compare memo, so a stable turn only skips if every sibling prop is stable too — and deriveAppShellTurnViewModel rebuilt turnFooterActionsByTurn from scratch on every refresh, because it derived those props by materializing the transcript a second time from the raw message log. Two independent authorities, neither able to give the other a stable key.

The derivation moved down instead of being patched

An earlier revision of this PR interned those per-turn props by value after the fact. That works, but interning is manufacturing a key that should already exist. The root cause is the second materializeTurns.

So the derivation now reads the turns the projection already produced. ChatView calls back a deriveTurnPresentation(turns) the shell supplies, and the shell keys its cache on those turn objects:

footerActionsByTurn[turn.turnId] = cache.get(turn) ?? derive(turn, …)

A turn the projection did not move costs one WeakMap hit and its footer, labels and badges come back as the same objects. The second authority and the interning disappear together, and prop stability falls out of turn stability rather than being re-established beside it.

Direction matters here: the derivation moved down to where the turns are, not the projection up to where the derivation was. chat-message-surface.tsx subscribes to liveTurn and shellRunUpdates at that layer precisely so a delta never reaches AppShell (#1985); hoisting the projection would have hoisted the delta with it and re-rendered the sidebar and composer on every token. Nothing moved above ChatMessageSurface, and quote-companion-panel.tsx — which renders ChatView without any of these props — is untouched.

Consequences of the down-shift:

• deriveAppShellTurnViewModel(messages, previous) → createAppShellTurnPresentationDerivation().derive(turns, context), plus useAppShellTurnPresentation, which mirrors useTranscriptProjection: a useRef-held factory, no useMemo, no previous argument to forget to thread.
• app-shell.tsx loses the useRef + useMemo + previous wiring entirely; it passes one prop.
• ChatView's four Record props collapse into deriveTurnPresentation, and safeResumeAction loses its turnId — which turn may be resumed is the derivation's answer now, so the shell supplies only the state and the callback.
• reconcileAppShellTurnViewModel, the Record-shaped reuseEqualEntries, and apps/desktop's dependency on valuesEqual no longer exist.

One behavior change: the presentation is now derived from the projected turns, which are live-overlaid and have draining assistant messages filtered out. For the live overlay only the tail turn can differ, and ChatView already replaces its footer with the non-actionable streaming placeholder while an answer is in flight (re-renders only the tail turn while an answer streams). The shell-run overlay is the exception worth naming: it rewrites tools[].result on any turn holding a background command, and the presentation does read turn.tools (sandbox-failure classification and the errored-tool count). No user-visible difference could be constructed — the overlay does not touch status, and its results carry no sandbox denial — so this is a narrowed claim, not a known defect.

Also removed

All three were introduced earlier in this PR and removed later in it: relative to main they are a no-op, and searching main for their names finds nothing. They are listed because reviewing this branch commit by commit walks through them, not because the branch deletes anything that shipped. (overlayShellRunUpdates, described above, is the one real deletion.)

• affectedTurnIds. No production caller (grep over packages/ and apps/ outside tests found none), and it carried a trap: repeating an input returned the previous step's affected set, so a consumer using it to scope re-renders would have been wrong. The 13 tests that asserted it now assert turn object identity directly, which is the property that actually reaches memo.
• The per-tool shell-run overlay memo. Its comment claimed that without it "the owning turn is rebuilt on every streamed token" — that was false: with the memo in place applied.out !== tool still held, so the turn was rebuilt anyway, and what actually returned identity was the reconcileTurnIdentities at the end. The memo also had a real hole: keying only on the entry (not the tool) would hand back a result derived from a stale tool, so a background command's output could freeze at an old value. Deleting it closes that without needing a test for it.
• valuesEqual's open key walk. valuesEqual(new Set([1]), new Set([2])) returned true, as did valuesEqual(new Date(0), new Date(999)) and valuesEqual(new Set([1]), {}). Every value it sees today is JSON-shaped, so there is no live defect — but it is exported as the rule every per-turn prop must intern by, and TurnFooterContext.pendingActions is already a ReadonlySet. It now fails closed outside plain objects and arrays: reporting "changed" costs a re-render, reporting "unchanged" freezes the UI.

Measured

CDP, real Electron, the original 107-turn session:

Input change	Before	After
text delta — heap	19.0 KiB	4.8 KiB
text delta — turn identities moved	5 / 107	1 / 107
refresh — heap	660 KiB	322 KiB
refresh — turn identities moved	107 / 107	0 / 107
full answer (658 deltas + 28 refreshes) — historical turn re-renders	5517	0

Node, synthetic transcripts (5 messages per turn, an 8 KiB tool result per turn; a throwaway Node script, not committed, so these numbers are not reproducible from the branch; mean of 20 runs after 2 warmups, Apple silicon). structuredClone of the message array is subtracted, since both shapes pay it:

	10 turns	40 turns	120 turns / 1.0 MB
refresh — projection reconcile + cached derivation (this PR)	0.21 ms	0.20 ms	0.49 ms
refresh — same, plus the second materializeTurns + full derivation (before)	0.24 ms	0.27 ms	0.71 ms
— of which: the second authority alone, now removed	0.03 ms	0.08 ms	0.18 ms
— of which: reconcileTurnIdentities deep compare, added by this PR	0.05 ms	0.18 ms	0.44 ms
delta — projection only, per token	0.004 ms	0.012 ms	0.032 ms
delta — projection + derivation, per token	0.010 ms	0.026 ms	0.073 ms

Two costs a reviewer should see rather than infer:

1. The refresh path pays a full deep comparison. reconcileTurnIdentities walks every turn's args and tool results; after IPC deserialization no string is reference-equal, so it degrades to memcmp over every Bash output in the session — 0.44 ms for a 1 MB transcript, growing linearly. refreshMessages fires at step and tool boundaries, not per token, and it buys eliminating a whole-transcript re-render, so this is a good trade; it is still a real new cost and it is now the dominant remaining one.
2. The derivation now runs per token, which it did not before (its useMemo was keyed on messages). At 120 turns that is 0.041 ms per token — rebuilding four Records over turns whose entries are all cache hits. Below any frame budget, but it is new work on the token path.

Review focus

This refactor inverts the failure mode. The old defect computed too much: slow, visible, measurable. The new risk is computing too little: stale UI, silent. So invalidation is tested with the same weight as stability, and every contract below was mutation-checked rather than observed green (table under Verification).

Two notes:

1. The projection lives in a useRef inside ChatView. It is a derivation accelerator, not authority: correctness comes from value reconciliation, so losing the state costs a recompute and never a wrong render. The sessionId reset is hygiene — it bounds what is retained. Dropping the reset is caught (a session switch shows the new session and retains nothing of the old, because two sessions in one revision lineage carry the same turn ids with different content), but that is the reset's retention property; value correctness is guaranteed independently by valuesEqual, which cannot reuse a turn whose content differs. A 4000-step property test comparing the stateful projection against a from-scratch projection at every step found no reachable divergence from removing it.
2. turn.tools order changed. A tool that is both persisted and still live now sits where the timeline renders it rather than at its original index. Every consumer is order-insensitive (counts and filters); the one that was not, findShellRunParentIndex, was fixed in review rather than left to depend on an order this PR no longer guarantees — see below.
3. One render body writes a ref: chat-view.tsx's promptRailTurnsRef. (app-shell.tsx's no longer does — the down-shift removed it; prompt-anchor-rail.tsx's was removed in review, see below.) This is the one place render is not a pure function. It is safe, and here is why: under StrictMode's double invocation the second call receives the first call's result as previous and returns it unchanged by value; under concurrent rendering a discarded render can advance the ref, but because the reuse is by value, the value stays correct and the only consequence is one extra re-render, never wrong UI; and the ref is per-component-instance, so multiple mounts cannot cross-talk. The cost is real and it is a deliberate trade for keeping the derivation and the render in the same object graph.

Known, not fixed here

• source_unavailable pins a detached run as running. Once ownership flips, the update's status stays running and the snapshot never advances. The projection carries that value faithfully and the flip itself invalidates correctly, but closing it belongs in the update state policy and needs a UX decision. Worth its own issue.
• overlayLiveTurn's fallback turn uses Date.now() for startedAt (materialize.ts:328) — the one place the projection's output is not a pure function of its input, and the sole source of the 16/4000 mismatches the property test found. It affects only the path where streaming starts before the optimistic user turn materializes, and that turn re-renders per delta regardless.
• use-quote-companion.ts filters allMessages unmemoized, so the companion panel's ChatView re-runs materializeTurns over the user's own turns on every render (typically single digits, ≈0.037 ms). reconcileTurnIdentities already recovers TurnView's memo there, so this is residual overhead, not a re-render. A useMemo keyed on allMessages plus a counter bumped at the ref's single mutation site would close it with no lag window (that hook currently discards the state value — const [, setOwnTurnTick] = useState(0) — so the counter has to be introduced, not just referenced), but it is off this PR's topic.
• Two intern implementations remain: reconcileTurnIdentities (arrays of turns) and the presentation cache (per turn object). They answer different questions and share valuesEqual where it matters.

Verification

• npm run typecheck (all workspaces), npm run lint, npm run format:check, npx knip — clean; knip output is byte-identical to the pre-change baseline.
• npm --workspace @maka/ui run test:dist — 316 pass. npm --workspace @maka/desktop run test:dist — 1585 pass.
• Desktop E2E (npm --workspace @maka/desktop run e2e) — 63 passed.
• packages/storage and packages/runtime fail in this environment for reasons this branch does not touch (/var vs /private/var symlink resolution in the path-containment tests; a writer-lock timing test). Neither package is modified by this branch.

Mutation results

Every contract this PR adds was verified by injecting the mutation and confirming a test goes red.

Mutation	Killed by
reconcileTurnIdentities ignores a shortened list	a turn missing from the durable snapshot is dropped…
Drop the sessionId reset	a session switch shows the new session and retains nothing of the old
lastUpdates = updates (alias the caller's array)	an update list mutated in place still advances the projection
Read messages once per projection call	a plain text delta never touches the message log at all
valuesEqual skips tokens	a refresh that only changes \tokens` moves the turn`
valuesEqual skips notes	a refresh that only changes \notes` moves the turn`
valuesEqual skips timeline	…\timeline`…`
valuesEqual skips status / statusSource	…\status`…, …`statusSource`…`
valuesEqual no longer fails closed	fails closed on anything that is not a plain object
Presentation derives without the per-turn cache	4 identity tests
Presentation cache key ignores lineage	moves a turn whose lineage changed even though the turn itself did not
Presentation cache key ignores whether a badge target still exists	drops a forward badge when its target turn leaves the transcript
Presentation cache key ignores pending actions	moves only the turn whose action went pending
A locale change does not invalidate the cache	relabels everything when the locale changes
useAppShellTurnPresentation rebuilds its derivation per render	keeps one turn-presentation derivation across renders
Lineage badge arrays not reused	keeps an untouched turn's lineage badges when the transcript grows
visibleMessages rebuilt on every render	re-renders only the tail turn… and re-renders nothing when a refresh republishes…
ChatView stops reusing the prompt rail's turns array	a delta must not rebuild the prompt rail observer
The presentation's failure copy, badges, or resume pairing never reach TurnView	renders every per-turn field the real derivation produces (five separate cuts)
Shell-run children fold only when they follow their parent	folds a child that renders ahead of the Bash owning the run
turn.tools reordered against turn.timeline	turn.tools is exactly the tools its timeline renders, order included

Three mutations survived, each for a reason rather than a gap:

• valuesEqual skips tools. Equivalent mutant: turn.tools is now exactly timelineTools(turn.timeline) (pinned by turn.tools is exactly the tools its timeline renders), so tools cannot move without timeline moving.
• ChatView stops passing sessionId to the projection. Nothing catches it, and nothing should: it is documented as hygiene, and its correctness-bearing counterpart (removing the reset itself) is caught. The previous revision of this description claimed this mutation was untestable based on the desktop ChatView suite; that suite is simply insensitive to it, and the claim was mis-sourced.
• Removing PromptAnchorRail's memo. Costs re-rendering a three-button list with identical props; pinning it would mean instrumenting the component's render count, which is more machinery than the regression is worth. The expensive half — tearing down and rebuilding a transcript-wide IntersectionObserver, one querySelector + observe per turn per token — is now caught on its own (see below).

Fixed in review

A round of independent review found six things worth acting on. All are in the last five commits.

• A literal NUL byte in the presentation cache key's join made git treat app-shell-turn-view-model.ts as binary, so the diff carrying this PR's core change showed up as Bin 4788 -> 9770 bytes and was unreviewable on GitHub. It is now 198 added / 74 removed lines of text.
• The shell-run fold no longer depends on tool order. Rather than leave the order-sensitive consumer standing behind a turn.tools order this PR deliberately changed, parents are indexed by ref over the whole list. The invariant test now carries two tools per turn on both paths, so a reversal is observable at all, and a new test pins the child-before-parent case directly.
• The presentation's wires to TurnView are covered. The stand-in this suite renders with returns empty maps for everything but the footer actions, so failure copy, lineage badges and the resume pairing were derived in one test and rendered in another. Cutting any of five wires kept the suite green; a failed, regenerated transcript now runs the real derivation through the real ChatView.
• The prompt rail lost its second stabilization layer. Its NUL-joined id key and its turns ref guarded the same thing ChatView's array reuse already guards — and covered for each other well enough that removing either one alone kept every test green. One guard remains, and the caller's reuse is now something the observer count can see.
• useAppShellTurnPresentation no longer pins its own identity. Nothing memoizes on it, so the useCallback bought nothing while the render-phase ref write it required would have frozen pending state the day ChatView is memoized.
• Two docblocks still pointed at deriveAppShellTurnViewModel, which this PR deleted, and valuesEqual still justified its export by the interning rule this PR removed. It now documents the coupling that is real: the shell keys a WeakMap on the turn objects this comparison decides, so relaxing it fails twice — the turn keeps its identity and hits a stale presentation entry.

ChatView's deriveTurnPresentation prop also now says what purity and idempotence do not imply: the deriver must carry a cache that outlives one render. A deriver rebuilt in the render body satisfies the documented contract, gives back every re-render this PR exists to avoid, and turns no test red — and app-shell.stories.tsx contains exactly that shape.

Fake-DOM fixes this required

FakeElement.querySelector() returned null unconditionally, so the prompt rail's idByElement.size === 0 early return always fired and its entire observer path was unreachable — all three changes in perf(ui): keep the prompt rail out of the streaming path tested green against a DOM that could not express them. querySelector/querySelectorAll now resolve [attr="value"] selectors against the real tree, and the observer stubs count their own lifecycle — separately per kind. Sharing one tally let a ResizeObserver from anywhere in the tree satisfy observe > 0, so that guard passed even with the rail's observer path unreachable; it now pins the exact {construct, observe, disconnect}.

Claims in earlier revisions of this description that were wrong and are corrected above: the docblock in ui-render-memo-boundary-contract.test.ts asserted that seam catches "a missing sessionId" (it does not — 11/11 stayed green); the quote-companion note gave "a one-render lag window" as the reason to defer a useMemo (there is no lag window; the real reason is scope) and named a binding that does not exist; the "Also removed" list read as deletions from main when they are self-corrections inside this PR; a mutation row credited the prompt rail's effect key with a kill that the array reuse was actually making; and the reported test counts were pre-rebase.