Repository navigation
perf(ios): virtualize the chat transcript on ChatLayout - #2178
Conversation
The transcript is a UICollectionView laid out by ChatLayout 2.5.2 (MIT), with each row a SwiftUI view in a hosted cell. Only rows near the screen are built and measured. The layout keeps what is on screen anchored when older pages go in or rows above grow, and keeps the newest row on the bottom while the guardian is there. Replaces the eager stack and its position patches (placingOlder hold, ScrollHandle shifts, lazy switch, anchor roles, the iOS 17 path). Fixes #2141 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first fling up built the newest cards (task, approval, widget) in one frame. Laying each out and drawing it once off screen, one per frame after the open, moves that cost out of the scroll. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
zoolsher
left a comment
There was a problem hiding this comment.
Design & Alternatives review: ✅ APPROVE
Problem: When the guardian scrolls up through older pages, or a row above the screen grows, the rows in view jump. Past 400 rows, scrolling back down froze for seconds. The cause: a SwiftUI ScrollView + VStack/LazyVStack has no built-in way to keep its position when content goes in above. The old TranscriptList in ChatScreen.swift (about 640 lines) faked one with ScrollHandle.shift, the placingOlder 150 ms hold, two defaultScrollAnchor roles, eagerRowLimit and a separate iOS 17 path, and still produced the iOS 27 jump (#2148).
Goals: only rows near the screen are built; older pages go in while a fling is still gliding without moving rows in view; a row that grows moves nothing in view; follow-bottom, jump-to-quote, unread line and status-bar tap behave as before. Non-goals: the thread overlay (ThreadOverlay.swift, which stays a SwiftUI ScrollView with StayAtBottom), and the row views, TranscriptStore paging semantics and ChatActions.
What I checked: I read the new TranscriptList.swift in full, the deleted list, and the TranscriptStore paging change (olderPage and placeOlderPage removed, so loadOlder merges right away). I traced all four callers: ChatScreen, TopicChatScreen, TaskChatScreen and the tests. I grepped the row views for things a hosting cell would break. None of them read a named coordinate space, send preference keys up to a parent, use matchedGeometryEffect or @FocusState. The only matchedTransitionSource is the header's ChatIdentity, which is outside the list. The deployment target stays iOS 17.0, and ChatLayout supports it. There is no other UICollectionView in the app to reuse.
Alternatives
| Approach | Added complexity | Correctness / completeness | Blast radius | Reversibility | Maintenance | Effort |
|---|---|---|---|---|---|---|
This PR: UICollectionView + ChatLayout 2.5.2, a SwiftUI row in each UIHostingConfiguration cell |
One pinned SPM dependency; about 720 lines replace about 640 lines of patches; one UIKit bridge (environment hand-off, its own cell sizing) | The layout keeps the position on batch updates and when a cell resizes itself, which is the cause of the bug; measured drift is 0 pt and older pages go in in 4–11 ms | Every chat transcript | Two-way door: in-app only, no API, schema or wire-format change; a revert restores the old list | A third-party layout that must keep up with new iOS releases (pinned exact, MIT, no transitive dependencies); the hosting-cell quirks are recorded in ios/CLAUDE.md |
Done |
Do nothing / keep #2164's patches on the SwiftUI ScrollView |
Already high: offset shifts, the hold, the lazy switch, iOS 17/18 branches | Treats the symptom; each iOS release has broken the shift, and the freeze past 400 rows remains | Same | n/a | Worst: every SwiftUI scroll change needs a new patch | None now, recurring later |
SwiftUI-native LazyVStack + scrollPosition(id:anchor:) / ScrollPosition |
Low code, but iOS 18+ APIs need an iOS 17 fallback | The old eagerRowLimit comment records why it fails: a lazy stack guesses heights wrong for a mix of cards and bubbles, and rows jump as content shrinks |
Same | Two-way | Depends on SwiftUI internals, as before | Medium |
Own UICollectionViewFlowLayout subclass, using contentOffsetAdjustment on self-sizing and on batch updates (no dependency) |
Re-implements the core of ChatLayout's position bookkeeping, mid-glide prepends included | Doable, but the edge cases ChatLayout already handles (resizing while decelerating, a prepend during a scroll animation) would have to be found again | Same | Two-way | We own the layout code | High |
| Inverted (flipped) list, spiked and rejected | Flip transforms on the list and every cell | Works, but VoiceOver order, edge effects, insets and context-menu previews all need flip workarounds | Same | Two-way | Ongoing flip workarounds | Medium |
Recommendation: the PR's approach is the best fit. It fixes the cause (no position-keeping primitive) rather than adding another offset patch, and it deletes more special cases than it adds: no hold, no lazy switch, no iOS-version branches. The two cheaper options (keep patching, or SwiftUI-native anchoring) both fail for reasons this repo already wrote down. A hand-rolled layout would avoid the dependency but rebuild the hardest part of ChatLayout. The dependency is the only lasting commitment, and it is small, pinned and easy to back out.
Follow-up: two list implementations remain, since ThreadOverlay keeps its own SwiftUI ScrollView. That is a stated non-goal, but once this design settles, moving the thread onto TranscriptList would make it the only list.
One optional note (P3): each streamed token still re-renders every visible cell, through CellContext. See the finding below.
Verdict: APPROVE — Moving the transcript to a UICollectionView with ChatLayout fixes the cause of the problem instead of adding more patches, and it is the best fit among the options I checked. The dependency is pinned to an exact version and the change is fully reversible, so nothing here should block the merge.
1 finding(s) posted as inline comments below.
| Severity | Category | File | Title |
|---|---|---|---|
| P3 | performance | ios/Rome/Features/Chat/TranscriptList.swift |
Each list update re-renders every visible cell through CellContext |
Automated review by RomeOS Code Review · commit 15fac98 · Full review history
| coordinator.scroll = scroll | ||
| scroll.target = coordinator | ||
| PerfProbe.count("listUpdate") | ||
| coordinator.cells.environment = context.environment |
There was a problem hiding this comment.
[P3] performance — Each list update re-renders every visible cell through CellContext
EnvironmentValues and AnyView are not Equatable, so the @Observable setters on CellContext notify on every assignment. updateUIView runs on every streamed token, because rows carries agentText text, and each run re-renders every visible RowHost and the FooterHost. That works against the RowBox goal that "a streamed reply redraws its own cell, not the list". It is still cheaper than the old code, which rebuilt the row closure for every row on each token, so this is optional. If ROME_PERF=stream shows it, mark environment and footer @ObservationIgnored and push only the custom keys (shareTurns and the actions); trait-backed keys such as colorScheme and dynamicTypeSize already reach UIHostingConfiguration cells through UIKit traits.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
yunfanye
left a comment
There was a problem hiding this comment.
Design & Alternatives review: 🛑 REQUEST_CHANGES
Problem
When guardians scroll through long chats, paging jumps and scrolling stalls happen because the eager transcript builds too many rows and its lazy fallback relies on estimated heights plus manual offset corrections.
Goals and non-goals
Goals: virtualize rendering, preserve visible positions during paging and resizing, and retain navigation and interactive-card behavior. Non-goals: server/API changes, transcript persistence changes, or rewriting the thread overlay.
Design & Alternatives
The PR replaces the stack with ChatLayout-backed reusable cells, retaining the existing store and SwiftUI rows. This addresses layout ownership directly, but recycling also changes the lifetime of editable row state.
| Approach | Added complexity | Correctness/completeness | Blast radius | Reversibility | Maintenance | Effort |
|---|---|---|---|---|---|---|
| PR as written | UIKit bridge and dependency | Layout addressed; unsent card state unprotected | All main/topic/task transcripts | Easy revert | Less anchoring code; lifecycle gap | Implemented |
| Retain existing stack and patches | No new machinery | Preserves eager-row state; retains scaling problem | Existing transcripts | Immediate | Continued offset workarounds | Low |
| Bounded SwiftUI render window | Height ledger, spacers, window navigation | Feasible, but dynamic heights still need explicit anchoring | Transcript rendering and jumps | Reversible | App owns virtualization details | High |
| ChatLayout plus transcript-owned editable state | Small keyed state owner beyond PR | Virtualization without losing unsent answers | Same transcripts and editable cards | Reversible | Clear model/view lifetimes | Moderate incremental |
The retained-stack alternative is grounded in the base implementation of ios/Rome/Features/Chat/ChatScreen.swift; ios/Rome/Features/Chat/ThreadOverlay.swift still uses that eager pattern. A bounded render window could slice TranscriptStore.rows while preserving the complete store for sharing and jumps, but would require new height and anchor bookkeeping. The model-owned alternative can reuse WidgetSurface from ios/Rome/Features/Chat/WidgetUICardView.swift, rather than retaining whole hosted views.
Recommendation
ChatLayout is the best layout fit, but complete the state-ownership migration before merging: preserve editable card state independently of cell lifetime, following Apple’s hosted-cell model-binding pattern. No public API, schema, or wire-format one-way doors were found; the dependency and rendering change are reversible.
Verification
Inspected the implementation, all three production callers, card-state ownership, relevant tests, and pinned ChatLayout source. Paging/growth tests do not cover edited-card reuse. Hosted tests could not be run on Linux because Xcode is unavailable.
Verdict: REQUEST_CHANGES — ChatLayout fits the scrolling problem, but the migration leaves unsent card answers owned by recyclable cells.
1 finding(s) posted as inline comments below.
| Severity | Category | File | Title |
|---|---|---|---|
| P1 | design | ios/Rome/Features/Chat/TranscriptList.swift |
Preserve unsent card answers outside recyclable cells |
Automated review by RomeOS Code Review · commit 15fac98 · Full review history
| ) | ||
| default: | ||
| guard let box = boxes[id] else { return UIHostingConfiguration { EmptyView() }.margins(.all, 0) } | ||
| content = AnyView(RowHost(box: box, cells: cells) { [weak self] row, previous in |
There was a problem hiding this comment.
[P1] design — Preserve unsent card answers outside recyclable cells
The unchanged question/widget rows own WidgetSurface through WidgetUICardView.@StateObject, and WidgetCatalog writes unsent choices and text only into that surface’s data model. Once their hosted cell is recycled, neither RowBox nor TranscriptStore retains those edits, so scrolling away and back can reconstruct the card with its defaults—unlike the previous eager transcript. Keep virtualization, but retain editable card state in a transcript-owned model keyed by row identity and bind the cells to it. Add a hosted test that edits a question, forces cell reuse, and verifies that its answers survive and remain isolated from other cards.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
A drag that stops a status-bar scroll before the top left the list waiting for a "reached the top" that UIKit never sends, so older pages stopped loading in that chat. A drag now clears it, and a tap with the list already on top no longer sets it. Near the top, a failed fetch is asked again at most once a second instead of on every scroll frame. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
A question or widget card kept its unsent answers and its sent lock in its own view, so a cell reused for another row lost them, and a sent card could be sent again. The transcript now keeps each card's surface, by its tool use id, for as long as the list lives. Each hosted cell also takes its row's identity, so before iOS 18 a reused cell no longer keeps the previous row's state, such as its photo. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
A tool use id such as item_0 repeats across turns, so two cards could share one kept surface: one's answers showed in the other, and a sent card locked a later one. Kept surfaces are now known by their row and their tool use id. A read cancelled because the card's view went away no longer leaves the kept card showing an error. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
A page of traces adds no row and moves nothing, so no scroll asked for the next page, and a short screen stopped filling at the spinner. The near-top fetch now goes on while a page adds messages but no rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
There was a problem hiding this comment.
🔁 This review has been superseded. See the latest review.
The hosts that draw the rows above the screen once after a chat opens could outlive the warm-up, and they kept observing their row and the list, so they redrew off screen on later changes. Each host is emptied after it draws. The growth tests also wait for the warm-up before they read where rows are, since its hosts report frames outside the window. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Jessie-QingYu
left a comment
There was a problem hiding this comment.
Code Review: ✅ APPROVE
Goal: The PR replaces the eager SwiftUI VStack transcript and its offset patches (placingOlder, ScrollHandle shifts, the lazy switch, the iOS 17 path) with a UICollectionView laid out by ChatLayout 2.5.2. Each row is a SwiftUI view in its own hosted cell. ChatLayout keeps the rows in view still, so TranscriptStore.loadOlder can now place an older page as soon as it is fetched.
Approach: This is the right fix. It removes the root cause (a SwiftUI ScrollView cannot keep its position when content goes in above) instead of adding another patch, and it deletes far more code than it adds. The dependency is MIT, has no dependencies of its own, and is pinned to an exact version.
What changed since the last review: One commit (5bf9185):
- After the off-screen warm-up draws a row, it sets the warm-up host's
rootViewtoEmptyView. The host can outlive the loop, so it no longer keeps observingRowBoxandCellContextand redrawing off screen. TranscriptListTestsnow waits until the warm-up hosts stop reporting frames, then clears the frames they reported. Their off-screen frames can no longer confusemiddleRow().
Interaction checked: Emptying the host cancels any card .task the warm-up started. Both WidgetSurface.load() exits now check Task.isCancelled, so the shared surface keeps its state. Because loaded stays false, the card reads its binds again when its real cell appears. show() returns early when the part is the same, so the processor and any unsent answers survive.
What else I checked:
- All of
TranscriptList.swift:apply, the insets,readScroll/askOlder, theonNearToploop that keeps paging past hidden-only pages, reveal and scroll-to-bottom, the warm-up, and the self-sizingTranscriptCell. - The
TranscriptStore.loadOlderchange and therevealUnreadloop. - The
WidgetSurfacesandWidgetCardBodysplit, and the.id(id)reset on reused cells. - The three
TranscriptListcall sites: Chat, topic chats and task chats. - Nothing in
ios/still refers to the removed symbols.
Prior threads: I am not raising them again.
- The P1 on keeping unsent card answers through cell reuse is fixed by
WidgetSurfaces, keyed by row and tool use id. - The P3 on redrawing every visible cell per token, and the P3 on a jump being dropped when its row is merged in the same update, are still optional and are listed as follow-ups.
iOS tests could not run on this Linux host.
Verdict: APPROVE — I found no new P0–P2 issues. The only commit since the last approved head (de4bf63 → 5bf9185) is a small, correct fix, and the earlier P1 findings on card state and on paging past hidden pages are both fixed.
No issues found. Code looks good!
Automated review by RomeOS Code Review · commit 5bf9185 · Full review history
zoolsher
left a comment
There was a problem hiding this comment.
Code Review: ✅ APPROVE
Code Review: ✅ APPROVE
Goal: The transcript was an eager SwiftUI VStack that switched to a lazy stack past 400 rows, and offset patches kept it still. This PR replaces it with a UICollectionView laid out by ChatLayout 2.5.2, with one SwiftUI row per cell. ChatLayout keeps the rows in view still when an older page goes in or a row above grows. That lets the placingOlder hold, the ScrollHandle shifts, the lazy switch and the iOS 17 path go, and TranscriptStore.loadOlder now places a page as soon as it is fetched.
Approach: This is the right fix. It removes the cause (a SwiftUI ScrollView cannot hold its position when content goes in above) instead of adding another patch. The new code is small and contained: one MIT dependency pinned with exactVersion 2.5.2 (Package.resolved revision dd4cb5c), TranscriptList.swift, and a WidgetSurfaces map passed through the environment.
What changed since the last approved head (de4bf63 → 5bf9185):
warmRowsAbovenow wraps its host's root view inAnyViewand sets it toEmptyView()after the one off-screen draw. The host is alive across theawait, andRowHostwatchescells.environment, which is set on everyupdateUIView. So before this change the host redrew off screen on every list update until it was released.- Emptying the host can cancel a card's
.task(id: part)partway through. I checkedWidgetSurface.load(): it returns early onTask.isCancelledand changes no state, and the real cell's.taskreads the binds again (showexits early for the same part). The surface comes from the sharedWidgetSurfacesmap under the row's id, so the warm host and the real cell use the same surface. - The test change waits until the warm-up hosts stop reporting frames, then clears
growth.frames. Thefor … whereloop stops sleeping once the count holds steady, so it ends.
What I checked beyond the diff:
- I read all of
TranscriptList.swift:applyon first load and on updates, insets,readScroll/askOlder,readDivider, reveal and back to bottom,warmRowsAbove, andTranscriptCell. - In
TranscriptStoreI readloadOlder,revealUnread,revealCardandjump(to:). Nothing still refers toolderPage,placeOlderPageorplacingOlder. - I read all three call sites (Chat, topic chats, task chats).
- I read the
WidgetSurfaces/WidgetCardBodysplit. - I looked at row-level
onAppear/.taskside effects that a warm-up host could set off (watchApproval, image loads). They are idempotent or can be cancelled.store.arrived()is attached to the list, not to a row.
Earlier threads: The P1 on card state is fixed by WidgetSurfaces, keyed by row and tool use id. The two P3s (CellContext redrawing every visible cell, and a jump to a row merged in the same update) are optional, and the PR description already lists the first as follow-up work, so I have not raised them again. I could not run the iOS hosted tests on this Linux host.
No new issues found.
Verdict: APPROVE — I found no new P0–P2 issues. The only commit since the last approved head (5bf9185) is a small warm-up fix that is safe, and the earlier P1 findings on card state and on hidden-only pages are fixed.
No issues found. Code looks good!
Automated review by RomeOS Code Review · commit 5bf9185 · Full review history
yunfanye
left a comment
There was a problem hiding this comment.
Code Review: ✅ APPROVE
The ChatLayout migration appropriately replaces manual scroll anchoring. Reviewed the changed implementation, all three chat integrations, paging and jump paths, retained widget state, regression tests, and pinned dependency APIs. iOS builds and simulator tests could not run on this Linux host.
Verdict: APPROVE — No new actionable issues found in the reviewed implementation and integrations.
No issues found. Code looks good!
Automated review by RomeOS Code Review · commit 5bf9185 · Full review history
Why
The transcript was an eager
VStackin aScrollView. Keeping the rows in view still while older pages go in took layer after layer of patches, and the iOS 27 paging jump (#2148) came out of them. Past 400 rows it switched to a lazy stack, and scrolling down from there froze for seconds. The transcript is now aUICollectionViewlaid out by ChatLayout, which keeps the position itself, with each row a SwiftUI view in its own cell. This replaces #2164's patches, which are closed unmerged.Invariants
Scope
UICollectionViewLayoutwith no transitive dependencies.placingOlderhold, theScrollHandleoffset shifts,eagerRowLimitand the lazy switch, thedefaultScrollAnchorroles,DistanceFromBottom/BottomMarker, and the iOS 17 legacy path.TranscriptStore, the row views andChatActionsare unchanged; older pages now go in when they are fetched.Merge danger
Two-way door; a revert restores the old list. Blast radius: every chat transcript (main Chat, topic chats, task chats).
Evidence
PagingUpTests, updated). The scroll, store, cache, share and thread suites pass on an iOS 27.2 simulator.ROME_PERF=paging/pagingdownagainst fix(ios): keep the transcript still and smooth when older pages load #2164's head, same simulator: a mid-screen row drifted 0 pt in every hold (11 holds paging up, 9 coming down, against fix(ios): keep the transcript still and smooth when older pages load #2164's 0 pt kept rows). An older page goes in in 4–11 ms including layout, against 45–78 ms. Scrolling down past 520 messages has a worst frame of 43–103 ms, against 150 ms. Flinging up has a hitch rate of 10–14 ms/s, against 18–23, and a worst frame of 60–67 ms, against 110–125.main, except for animation frames. VoiceOver order was not checked with VoiceOver; without a flip it follows the rows' order.WidgetSurfacesTests). Each cell takes its row's identity, so a reused cell starts fresh before iOS 18 too; no iOS 17 runtime was at hand to watch that on.Follow-up (not blocking)
mainredraws every row per token, so this is no regression, and the hand-off is also what brings fresh row closures to cells on screen. Measure withROME_PERF=stream, then pass only the keys the rows read.ThreadOverlaykeeps its own SwiftUIScrollView; moving the thread ontoTranscriptListwould leave one list.Fixes #2141
Fixes #2148
🤖 Generated with Claude Code