refactor(ui): make the transcript the only writer of its scroll position

[Astro-Han]

Summary

Switching sessions moved the transcript under the reader after it had already settled.

The immediate cause was one speculative prefetch: on arrival, useChatScroll scheduled an idle callback that loaded earlier history nobody asked for and inserted it above the reader's position, where it then inflated in waves. The upward-scroll and wheel handlers already load that history on real intent, so the prefetch had no job.

Removing it exposed the real one. scrollTop had three writers — Astryx's lock and spring, this hook's compensation and scrollIntoView, and the browser's own anchoring — and nothing decided where the viewport should be. They coordinated through ref flags and effect ordering, so every defect in this area is two writers colliding in one commit. unlockAutoFollow was the tell: a seam whose only purpose is to let one owner overrule another.

So this PR ends with one writer. transcript-scroll-authority holds a single boolean:

• pinned → content that grows writes scrollTop = scrollHeight
• !pinned → nothing here writes scrollTop, ever

"Keep the reader where they were reading" is the definition of overflow-anchor: auto, already the initial value and free, and "the reader is dragging" is also don't touch it — both are the same instruction to this code. Navigation becomes a one-shot command that only runs while unpinned, so a command cannot race the policy.

Being the only writer is what makes "the reader moved" exact rather than inferred. The authority remembers the offset it wrote, so an event that finds the scroller still on that offset is its own echo however late it arrives; and an event arriving with scrollHeight or clientHeight changed is the content or the viewport moving under the reader — anchoring, growth that outran a write, a resize the browser answered by clamping — which moves their offset without changing their intent. What is left is the reader, and the authority publishes it (subscribeToReaderScroll) so nothing else keeps a second reading of the raw event. Astryx had to infer this from scroll direction, height deltas and wheel events, and every one of those signals has more than one cause.

It watches its own scroller, too: the scroller's box, because the tail moves when the viewport shrinks, and the scroller's children's boxes, because that is what scrollHeight is made of. Not a list of nodes the transcript thinks matter — an observer that knows which nodes matter is an observer that can be wrong about it, and it was: the transcript renders the optimistic user message, the no-tail live fallback and orphaned conversation items outside the virtual turn wrappers.

Removed along the way, because the authority makes them redundant: arrival-bottom-pin, the idle prefetch, chat-scroll-anchor, data-turn-window and the fonts.ready wait, fifty markdown polls and double rAF that timed its release, the notifyContentResize command and the onContentResize wiring through useTurnVirtualizer, and three of the four injection points in the vendored Astryx patch. The patch's scroll surface is now one seam — ChatLayout forwarding autoScroll into the enabled option useChatStreamScroll already published.

The hand-rolled compensation for content landing above the reader went too. It existed because the browser declines to anchor at scrollTop === 0, and that hole is exactly one pixel deep: measured in Chromium, a 501px insert above the reader moves scrollTop by 501 at an offset of 1 and by nothing at 0. Raising the offset to 1 before asking for history hands the case to native anchoring, which was already doing the work at every other offset the load can fire from.

The authority is also unconditional: every ChatSurfaceLayout provides one, so nothing below carries a second behaviour for its absence, and autoScroll — which scrollOwner decides and the layout spread last — is off the public props. Deduplicating an earlier-history request moved to app-shell, where the request originates, so the hook no longer tracks a load it does not own.

23 files changed, 1321 insertions, 999 deletions.

Refs #4099

Verification

Layout shift, measured with alternating within-instance A/B, four sessions, three repetitions each. Only same-instance comparisons are used — the same build across restarts varies far more than the effect.

configuration	mean CLS
before	0.481–0.521
after	0.089

Left: main. Right: this branch. Same session switch, the three seconds after it.

Both the table and the capture were measured at 31539bc66, where the prefetch was removed and Astryx still owned scrolling. They are not re-measured at the tip: the single authority only removes writers of scrollTop, so it cannot reintroduce the shift, and what it changes beyond that is scroll position, which CLS cannot see. The Playwright assertions below are the tip's evidence.

CLS was the wrong instrument for the rest of it: it measures layout shift, and every remaining defect was a wrong scroll position, which it cannot see. Those are now covered by nine Playwright assertions against a real Electron window (apps/desktop/e2e/transcript-scroll.spec.ts), each asserting where an element ended up rather than a pixel delta:

• a streaming answer keeps the viewport at the tail (worst lag ≤ worst frame growth + 8px; settles within 4px)
• content that grows outside the turn wrappers is followed too — asserts the growth landed outside [data-virtual-turn-id], which is where a turn-shaped growth signal stops seeing it
• content that arrives after the reader scrolls up does not pull them back (anchor turn moves ≤ 4px)
• a gesture a nested scroller consumed does not release the tail — real mouse.wheel over a genuinely overflowing nested container, with a guard assertion proving the wheel was consumed
• the dock affordance returns the reader to the tail (availability read from computed pointer-events/opacity, since toBeVisible is true at opacity: 0)
• earlier history lands above the turn the reader is on
• history asked for at the very top still lands above the reader — the assertion fails without the one-pixel raise, holding the scroller at zero
• following the tail does not ask for the history above it — fails without the fix by loading 120 turns nobody asked for
• a wheel the scroller cannot act on still asks for history — synthetic WheelEvent, because a real wheel scrolls and the scroll would settle the question by itself

Green on CI at the current head (test, Linux/xvfb). Locally: transcript-scroll 9 passed, @maka/ui transcript-scroll-authority 9 passed and use-turn-virtualizer 12 passed, plus npm run format:check and tsc --noEmit for packages/ui and the desktop renderer. Not run: the full repository suite.

What review found

Three rounds of adversarial review found fourteen defects. Eleven were the same problem — a fact about the viewport re-derived somewhere that did not own it — and the collapse to a single boolean plus one-shot commands makes them structurally inexpressible rather than fixed one at a time:

• "Return to latest" not reaching the bottom. Visibility and the click used to be two independent judgements of "where is the reader". Now the button's isVisible is authority.getSnapshot().awayFromTail and its onClick is authority.pinToTail() — read and write on one object, with no second source that can go stale. pinToTail() consults no precondition, so no state exists that could veto it.
• A cross-session jump releasing following, then being re-locked in the same commit. Two opposite intents used to live in two effects, and React's effect order decided the winner. There is now one boolean: a swap is pinToTail(), a jump is releasePin(). They write the same variable instead of overruling each other, and the later call wins because the call order says so.
• A wheel up over a nested scroller silently stopping tail-follow. The old predicate was a gesture (deltaY < 0 && animatingRef.current), and gestures bubble — a wheel a nested scroller consumed passed through the transcript anyway. CDP also showed animatingRef is true at rest, so that conjunct never constrained anything. Release now comes from the authority's own reading of the scroller, and scroll does not bubble, so a gesture the transcript never acted on cannot reach it.
• The pin re-derived from position on events the reader did not cause — the one that failed CI at 302px where it passed locally. Anchoring compensating for turns landing above, growth outrunning a tail write, and the browser clamping the offset on a viewport resize all arrive as ordinary scroll events at an offset the authority did not write, and each silently re-answered "is the reader following the tail". Scroll geometry is now the discriminator.
• "The reader wants earlier history" re-derived in a second place. use-chat-scroll read the raw scroll event and asked whenever the offset was near the start — which fired on the authority's own pin writes (on any transcript shorter than about three viewports the tail is inside that band), and missed the one gesture that matters: a wheel up at scrollTop === 0, where the scroller cannot move and no scroll event follows. It now subscribes to subscribeToReaderScroll, and the wheel releases the pin because a reader asking for what is above them is no longer following what is below.
• Growth outside the virtual turn wrappers reaching nobody. The growth signal came from the turn virtualizer, which observes turns to keep its height index — a set that is not the transcript. Sending a Follow Up was enough to hit it. The authority observes the scroller's children instead, and the borrowed signal is gone.

Review focus

Two behaviours change deliberately:

• Returning to the bottom re-locks following; the old pin's release was permanent for that arrival.
• "Return to latest" now loads the latest range and pins, rather than scrolling to a specific turn. Positioning is the pin; the range that arrives after it is growth, and growth is already followed.

Two upstream defects surfaced while adopting the Astryx hook, both filed: gesture release is dead under prefers-reduced-motion (facebook/astryx#5662), and jumpToBottom does not cancel its in-flight spring (facebook/astryx#5663). Neither is reachable now that Astryx's scroll layer is off for the transcript.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code — root-cause investigation, the CDP measurement harness, the code changes, the E2E spec, and this description. Independent adversarial review agents produced the findings above; each was verified against source, and the behaviours were then measured against a running build. The contributor of record reviewed the final diff and owns the merge decision.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[jackwener]

I found no P0–P3 issues on exact head e7baf0d75847edf0d2f953a83980e1d6ab186457.

The session-switch jump was a real path: after arrival, useChatScroll scheduled an idle callback that called requestEarlier() whenever the scroller was still near the top, which is exactly where a newly filled transcript sits. That inserted history the reader had not asked for, and those turns then grew under them. The upward-scroll and wheel handlers already load earlier history on intent, so the prefetch had no job.

What remains of Maka's scroll work is the pair Astryx cannot see: jump-to-turn and earlier-history load both call unlockAutoFollow, and "return to latest" calls scrollToBottom({ behavior: 'instant' }). @astryxdesign/core@0.5.0 already has that method; the patch only exposes it and uses an instant jump on conversationKey change instead of lock(), which re-entered the spring. The one-pixel nudge at scrollTop === 0 matches the documented overflow-anchor hole. I did not treat issue #4099 as evidence.

I am not merging. This is a behavior-changing scroll-ownership change; merge is a human call. Hosted test was still queued when I posted. This review does not claim CI is green.

---

Posted by an automated review agent operated by @WAWQAQ. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

精确 head e7baf0d75847edf0d2f953a83980e1d6ab186457 上我没有发现 P0–P3。

会话切换后的跳动是真实路径：到达后 useChatScroll 会在空闲时无条件预取更早历史，而新填满的转录往往还停在顶部附近，于是读者没要的回合被插进来并在下方长高。向上滚动和滚轮已经会按意图加载，这段预取没有工作可做。

Maka 还留下 Astryx 看不见的两处：跳到指定回合、加载更早历史会 unlockAutoFollow；回到最新会 scrollToBottom({ behavior: 'instant' })。@astryxdesign/core@0.5.0 已有这个方法，补丁只是暴露它，并在 conversationKey 变化时立刻跳到底，而不是 lock() 再走弹簧。scrollTop === 0 时的 1px 挪动对得上 overflow-anchor 在最顶端不生效的缺口。我没有把 issue #4099 当证据。

我不合入。这是会改行为的滚动归属调整，合入由人类决定。发这条时 hosted test 还在排队，这次审查不表示 CI 已绿。

本条评论由 @WAWQAQ 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查，也不能替代人类审查。有人类对本条评论负责，如有错误请直接指出。

[M4n5ter]

I am approving exact head e7baf0d75847edf0d2f953a83980e1d6ab186457 because I found no P0 or P1 issues. I left one non-blocking P2 inline: when a session's transcript arrives asynchronously, the conversation-change jump consumes Astryx's pending first-fill state while the scroller is still empty, so the later content still enters through the spring instead of landing at the bottom in one step.

The simplification is otherwise real: the change removes the speculative prefetch, two product-owned scroll authorities, their gating state, and their dedicated tests instead of moving them elsewhere. The remaining host seams are limited to the two moves Astryx cannot infer itself: releasing auto-follow for reader-directed navigation and re-locking it when returning to the latest turn.

I verified all 237 UI tests, the Desktop production build, seven real Electron prompt-rail tests, Biome, and the changed diff. The exact-head hosted windows_recovery check is green; hosted test is still queued, so this approval does not claim CI is fully green.

---

Posted by an automated review agent operated by @M4n5ter. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

本条评论由 @M4n5ter 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查，也不能替代人类审查。有人类对本条评论负责，如有错误请直接指出。

[jackwener]

I am not approving exact head 9eb824f9a9225e615236fd0816d88a05d6c002c5. 1×P1, no P0, no P2/P3.

P1. Earlier-history load is no longer tied to reader intent, and a real ask at the top keeps the pin.

The single-writer pin is the right cut. These two handlers sit outside it. 9eb824f9a stopped unpinning on a history request because a short latest window was requesting while still following — that request should not fire while the reader is at the tail, and a wheel-up at scrollTop === 0 is a reader ask the authority cannot see (scroll does not fire there).

I did not treat issue #4099 as evidence. I am not merging: this is a behavior-changing scroll refactor, and merge is a human call. Hosted test was still queued when I posted; this review does not claim CI is green.

---

Posted by an automated review agent operated by @WAWQAQ. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

精确 head 9eb824f9a9225e615236fd0816d88a05d6c002c5 上我不 Approve。1×P1，没有 P0，没有 P2/P3。

P1. 更早历史的加载已经不再绑定读者意图；真正在顶端要历史时，钉住也不会松开。

单一写入者这个切法是对的。出问题的是钉住外面的两个 handler。9eb824f9a 不再在请求历史上松钉，是因为短窗口在跟随时也会发出请求——跟随时根本不该请求；而 scrollTop === 0 时向上滚轮是读者在要历史，authority 看不见（这里不会有 scroll）。

我没有把 issue #4099 当证据。我不合入：这是会改行为的滚动重构，合入由人类决定。发这条时 hosted test 还在排队，这次审查不表示 CI 已绿。

本条评论由 @WAWQAQ 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查，也不能替代人类审查。有人类对本条评论负责，如有错误请直接指出。

[zhiiw]

Reviewed at exact head 9eb824f9 (23 files, +1059/−994). The mechanism reads clean on inspection — one writer for scrollTop, navigation as a one-shot command while unpinned, the duplicated prefetch removed. I did not find correctness issues in the code itself worth a P-level.

However, this head cannot be approved: its own evidence spec is red in CI. Run 33237483941 (test, Linux/xvfb) fails two of the six new transcript-scroll assertions, both with the same signature — the transcript settles 302px off the tail where the budget is ≤4px:

• a streaming answer keeps the viewport at the tail
• a gesture a nested scroller consumed does not release the tail

The author verified them locally and they pass there; on the hosted runner they do not. Until that gap is reconciled (either the tests are environment-fragile or the behavior differs off the author's machine), the PR's own claims are unproven on CI. Inline notes on the two failing specs.

简体中文

代码本身读完没有发现值得定级的问题，但这个 head 不能批：PR 自己新增的证据测试在 CI（Linux/xvfb）上挂了 2/6，失败签名一致——收敛后离尾部 302px（预算是 ≤4px）。作者本地是过的。这个落差没 reconciled 之前，本 PR 自己的声明在 CI 上未被证明。

[M4n5ter]

I reviewed exact head 14f894da459463ead9a2bde47d327208f49b30ce. I found no P0 or P1 issue, so I am approving it with non-blocking P2 feedback.

The latest commit closes the event-ordering defect from the preceding head: the authority now matches its clamped written offset instead of owning a whole animation-frame window. The production-state probe now preserves a reader scroll across later growth, and the real Electron dock regression passed 5/5. The earlier delayed conversation-fill problem also remains closed.

I independently reproduced both active use-chat-scroll.ts history-loading threads and did not add duplicate inline comments. I classify their observed effects as P2 rather than P1: one path performs bounded earlier-history work without reader intent, and the already-at-zero wheel path causes a recoverable viewport jump after the first page loads. Neither loses data or creates an unrecoverable state. I added one separate P2 inline for a supported transcript-growth path that still does not reach the new authority.

The refactor's simplification is genuine: it removes the two previous scroll authorities, speculative prefetch machinery, duplicate DOM/state seams, and their dedicated suites. All 258 UI tests and the Desktop production build pass locally. Hosted checks for this exact head were still running at my last read, so this approval does not claim that CI is green.

---

Posted by an automated review agent operated by @M4n5ter. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

本条评论由 @M4n5ter 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查，也不能替代人类审查。有人类对本条评论负责，如有错误请直接指出。

[zhiiw]

Re-reviewed at exact head 944f2342, after the three follow-up commits that answer my earlier inline comments.

The fix for the CI-red evidence is the right one. The old authority flagged its own scrollTop writes with a frame-windowed writing flag — on a loaded machine the echo of a write can arrive after the window closes, which is exactly how the hosted Linux runner failed the two settle assertions while the author's machine passed. The new authority identifies its own writes by position (lastWrittenTop read back after clamping) and discriminates reader movement from content/viewport movement by comparing scroll geometry (scrollHeight/clientHeight) — no timing anywhere. The ResizeObserver now watches the scroller's children rather than relying on the transcript's own idea of what grew. notifyContentResize is gone with no remaining callers.

My earlier comments are answered by this head. Nothing new to report.

Executed on a real Windows machine at this head: transcript-scroll-authority 9/9, including the new echo-late-arrival and growth-outruns-write cases. Hosted test and windows_recovery are both completed/success on the exact head.

简体中文

新 head 回答了我上一轮的行内评论：把"自己写的滚动"从时间窗识别改成位置回读（lastWrittenTop 读回 clamp 后的值）+ 几何比对（scrollHeight/clientHeight）区分读者手势与内容/视口移动——完全不依赖时序，这正是 hosted runner 上挂掉、作者机器上过的那个失败模式。本机真 Windows：transcript-scroll-authority 9/9（含新增的晚到 echo 与超增长的用例），hosted test 与 windows_recovery 在当前 head 全绿。