fix(code): avoid transcript hydration lag

[Johannes du Plessis (johannes117)]

Resumed transcripts now load quickly and scroll smoothly without blocking on message hydration.

---

Textual reapplies styles across the mounted DOM whenever history widgets are inserted. This made on-demand hydration stutter even in small batches, especially because collapsed tool rows still retained their full widget trees.

This mounts a small initial history window, warms it in bounded batches, prefetches relative to virtual spacer boundaries, coalesces hydration work, and delays pruning until scrolling settles. Restored successful tool runs are represented by lazy data-backed summaries whose detail widgets mount only when expanded.

On a 681-message local thread, restored history compacted to 265 display rows, initial loading took about 0.9 seconds, and background warmup completed the transcript before backward scrolling required hydration.

Test plan

• 623 focused tests passed
• Ruff passed on changed files
• ty passed on changed production files

Video

New (left) - Old (right)

Virtualization.Side.by.side.mp4

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[Mason Daugherty (mdrxy)]

If you expand a saved group of tool calls, then expand one tool’s output inside it, that "inner expanded" state looks like can be lost when the UI scrolls the group out of memory.

[Mason Daugherty (mdrxy)]

Posted by Codex

I found a few issues worth addressing before merge. I have kept these to behaviors that follow directly from the implementation; the larger hydration-oscillation claim needs a reproducible regression test before treating it as a blocker.

1. _continue_hydration() now checks both edges after every hydration slice.

_hydrate_messages_above() schedules a below-edge prune, and _hydrate_messages_below() schedules an above-edge prune. Once the continuation runs, it calls both _check_hydration_needed() and _check_hydration_below_needed() regardless of which direction was just hydrated.

The prior implementation re-checked only the direction that had just hydrated. Please add coverage for a transcript with archived rows on both sides and verify that an idle viewport does not repeatedly request alternating hydration directions. If the symmetric re-check is intentional, document the termination condition.

2. A permanently unbuildable edge message is retried forever.

Both hydrate loops stop on the first to_widget() failure, correctly preserving contiguity, but leave the failing entry as the next candidate. A later scroll retries the same failure indefinitely; the spacer continues to reserve estimated height for content that will never mount. _notify_hydration_failure() is also session-latched, so a subsequent distinct failure may have no visible feedback.

Please either record a recoverable failure state for that row, or provide a bounded retry/skip strategy that preserves ordering without leaving an unfillable virtual gap.

3. Batch rollback hides removal failures.

remove_attached_nodes() suppresses every Exception from node.remove() without logging. If a partial mount fails and rollback leaves a node attached, the store remains unchanged and the next hydration can attempt to mount the same IDs again.

At minimum, log rollback failures. It would also be safer to make the batch failure explicit rather than silently relying on a future hydrate attempt to repair a partially attached DOM.

4. Tool completion uses a stale shared prune direction.

_sync_tool_message_state() schedules pruning with _transcript_prune_direction, which represents the last hydration direction rather than the direction appropriate for this newly completed tool. For example, after hydrate-above, the stored direction is "below" and a tool completion can prune recent completed rows from the tail.

Please pass an explicit direction here, as _mount_message() does, rather than reusing the shared hydration state.

5. Lazy-group expansion fails without user-visible recovery.

On expansion failure, LazyToolGroupSummary._set_expanded() logs, removes any partial children, and returns. The group remains collapsed and emits no ExpansionChanged event or user-facing notification. For restored transcripts, this can make the retained tool details inaccessible with no explanation.

Please notify the user on failure, or render a visible fallback/error state in the summary.

6. The collapse branch has no equivalent exception handling.

The expansion path catches errors, but collapse performs zip(..., strict=True) and remove_children() outside that handler. A mismatch between _message_data and _detail_widgets therefore escapes the worker. The lists should be represented as one collection of paired data/widgets, or collapse should handle and report this inconsistency consistently with expansion.

7. Pruning can stop recovering after a missing-widget desync.

When pruning cannot find a candidate widget, it logs at debug level and does not mark it pruned, which is correct. But _run_transcript_prune_slice() only schedules another slice when pruned > 0. The same missing head/tail candidate can therefore prevent all further pruning while the visible range continues to exceed the soft limit.

Please add a recovery path for this state—for example, reschedule with bounded retries or reconcile the mounted IDs against the store.

8. Cancelled assistant rendering is treated as success.

asyncio.gather(..., return_exceptions=True) can return CancelledError, which is a BaseException, not an Exception. The isinstance(error, Exception) check misses it, so the batch may be marked hydrated even though an assistant’s post-mount content render was cancelled.

Please explicitly handle cancellation results, or re-raise cancellation rather than treating the batch as successful.

Non-blocking cleanup:

• MessageData.__post_init__() requires non-empty TOOL_GROUP details, while to_widget() falls back to self.tool_group_messages or []. The fallback masks a violated invariant and can render an empty summary.
• The prune-delay comments are misleading: scrolling also resets the timer, so it is not simply “seconds without hydration.”
• The restore-path DIFF grouping branch appears unreachable today: restored diffs use diff_tool_name="edit_file", which is excluded from grouping.
• Please add focused tests for generation changes during mount, retry behavior after build/mount failure, prune recovery after a missing widget, deferred lazy-group expansion, and both-direction hydration near virtual boundaries.

[Johannes du Plessis (johannes117)]

Addressed in c8f85a1:

• preserved nested tool-output expansion state across virtualization
• limited continuation checks to the hydration edge that just completed
• replaced unbuildable rows with visible placeholders instead of blocking history
• logged rollback cleanup failures and rolled back/re-raised cancelled rendering
• surfaced lazy-group expansion/collapse failures and made collapse state tracking consistent
• reconciled missing boundary widgets during pruning
• tightened the tool-group invariant and removed stale prune wording/dead restore grouping

The shared prune direction remains unchanged because it tracks the edge to trim for the current mounted window.