refactor(ui): make the transcript the only writer of its scroll position by Astro-Han · Pull Request #1 · Astro-Han/maka-agent

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han · 2026-08-29T03:42:40Z

Summary

Stacked on apache#4105 — review that first; this diff is against its branch.

Three writers moved scrollTop in the chat transcript: Astryx's auto-follow lock and spring, Maka's height-delta compensation and scrollIntoView, and the browser's own anchoring. None of them held the answer to "where should the viewport be", so they avoided each other through flags, effect ordering, and heuristics rebuilt from DOM signals — scroll direction, height deltas, wheel events — each of which has more than one cause. apache#4105 fixed the symptoms that were reachable; the three regressions it records as knowingly unfixed are the ones that need the ownership itself to move, and this PR eliminates all three.

The policy is now one boolean:

pinned — content that grows writes scrollTop = scrollHeight
not pinned — nothing here writes scrollTop, ever, and overflow-anchor: auto (already the initial value, no CSS added) keeps the reader where they were reading

Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at scrollTop === 0 — the single place native anchoring declines to help. Each releases the pin before it moves anything, so a command cannot race the policy.

Being the only writer is what makes the state exact rather than guessed. A write flags itself, so an unflagged scroll event is the reader by construction. And because scroll does not bubble, a gesture a nested scroller consumed never reaches the authority at all.

Deliberate choices worth a reviewer's attention:

Astryx's scroll layer is disabled per call site, through a new scrollOwner prop on ChatSurfaceLayout, not globally. The workhub surfaces render no ChatView and still want stock auto-follow.
No new observer. The growth signal is the turn virtualizer's existing ResizeObserver, called synchronously in its callback so the pin writes in the frame the content grew.
The history anchor is an element, not a height. A scrollHeight delta counts growth below the reader too, and counts a load that returned nothing as a push. It also picks the first visible turn, not the first mounted one — the virtual window is free to drop turns above the viewport while the load lands.
attach runs in a passive effect, not a layout one. The scroller is Astryx's layout root, an ancestor, and React attaches a parent's ref after its children's layout effects have run.
Nothing here reads an animation flag. Astryx gated its wheel predicate on animatingRef, and CDP measurement on the built branch found that ref sitting at true on a resting transcript (scrollHeight constant for 2.5s, spring target reachable, six seconds of quiet before the gesture) — emptying the stock wheel handler made the release disappear and restoring it brought it back, three times over. A "is something animating" flag desyncs from the rAF chains it is supposed to describe, so no equivalent flag was kept for compatibility.

Because Maka now owns the position, the patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks: conversationKey, unlockAutoFollow and resetInitialFill are gone, replaced by forwarding one autoScroll flag into useChatStreamScroll's existing enabled switch. Patch file: 55 hunks → 49, 149 of its lines rewritten.

Two unit test files are deleted rather than ported. Both exercised unlockAutoFollow and the conversation-swap reset — mechanisms this PR removes, not behaviours it changes.

Refs apache#4105

Verification

apps/desktop/e2e/transcript-scroll.spec.ts — 5 passed (1.0m), real Electron window:
- a streaming answer keeps the viewport at the tail
- content that arrives after the reader scrolls up does not pull them back
- a gesture a nested scroller consumed does not release the tail (real mouse.wheel over a real overflowing child, guarded by asserting the child actually moved)
- the dock affordance returns the reader to the tail
- earlier history lands above the turn the reader is on
packages/ui scroll + rail unit tests: 13 passed, 0 failed (node --test --test-concurrency 4), including 4 new cases for the authority.
Previously affected e2e suites — prompt-rail, streaming-remount, quote-selection: 12 passed, 1 skipped.
npm run build -w @maka/ui, npm run typecheck -w apps/desktop (preload/main/renderer/storybook), npm run typecheck:stories -w apps/desktop, npm run format — all clean.
Patch integrity: git apply --check --reverse patches/@astryxdesign+core+0.5.0.patch against an npm ci-installed tree exits 0.
Not run: the full repository suite.

Review focus

The e2e assertions deliberately avoid fixed pixel budgets. They compare element positions before and after, and where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that same frame's growth, because following by ResizeObserver is one frame behind by construction and that frame is never painted.

AI use

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

Tool(s) and scope: Claude Opus 5 via Claude Code — implementation, tests, and this description, under human direction and review. Affected commits carry Generated-by trailers.

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

Three writers moved `scrollTop` in the chat transcript — Astryx's auto-follow lock and spring, Maka's height-delta compensation and `scrollIntoView`, and the browser's own anchoring — and none of them held the answer to "where should the viewport be". They avoided each other through flags, effect ordering and heuristics reconstructed from DOM signals, and each heuristic had more than one cause. Collapse the policy to one boolean. `pinned` means growth writes `scrollTop = scrollHeight`; not pinned means nothing here writes it, ever, and `overflow-anchor: auto` — already the initial value — keeps the reader where they were reading for free. Around it sit three one-shot commands: return to the tail, jump to a turn, and compensate earlier history at `scrollTop === 0`, the one place native anchoring declines to help. Every command releases the pin first, so a command can never race the policy. Being the only writer is what makes the state exact. A write flags itself, so an unflagged `scroll` event is the reader by construction — and because `scroll` does not bubble, a gesture a nested scroller consumed never reaches the authority at all. Astryx's scroll layer is turned off per call site through a new `scrollOwner` prop rather than globally: the workhub surfaces render no `ChatView` and still want stock auto-follow. The growth signal reuses the turn virtualizer's existing `ResizeObserver`; no new observer is added. The patch's scroll-related surface shrinks from six files and ten hunks to three files and five hunks — `conversationKey`, `unlockAutoFollow` and `resetInitialFill` all disappear, replaced by forwarding one `autoScroll` flag into the hook's existing `enabled` switch. Generated-by: Claude Opus 5 via Claude Code

coderabbitai · 2026-08-29T03:42:47Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Five Playwright assertions over the real Electron window, one per property the single scroll authority is supposed to have: a streaming answer keeps the tail on screen, content arriving after the reader scrolls up does not pull them back, a gesture a nested scroller consumed does not release the tail, the dock affordance returns the reader to the tail, and earlier history lands above the turn the reader is on. They assert element positions rather than pixel deltas. Where lag has to be measured at all it is self-calibrating — the worst frame's lag is compared against that frame's own growth, because following by `ResizeObserver` is one frame behind by construction and that frame is never painted. A fixed pixel budget would encode the machine it was written on. Generated-by: Claude Opus 5 via Claude Code

Astro-Han · 2026-08-29T03:53:29Z

Superseded: this work is being merged into apache#4105 directly, since that PR is the teardown and this is the rebuild — they cannot land independently.

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Astro-Han force-pushed the refactor/chat-scroll-single-authority branch from 9ddbeb8 to ecd3290Compare August 29, 2026 03:46

Astro-Han closed this Aug 29, 2026

Astro-Han deleted the refactor/chat-scroll-single-authority branch August 29, 2026 04:02

Conversation

Astro-Han commented Aug 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review focus

AI use

Checklist

Uh oh!

coderabbitaiBot commented Aug 29, 2026

Draft PR not reviewed

Uh oh!

Astro-Han commented Aug 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Astro-Han commented Aug 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review focus

AI use

Checklist

Uh oh!

coderabbitaiBot commented Aug 29, 2026

Draft PR not reviewed

Uh oh!

Astro-Han commented Aug 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Astro-Han commented Aug 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review focus

AI use

Checklist

Uh oh!

coderabbitaiBot commented Aug 29, 2026

Draft PR not reviewed

Uh oh!

Astro-Han commented Aug 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Astro-Han commented Aug 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review focus

AI use

Checklist

Uh oh!

coderabbitaiBot commented Aug 29, 2026

Draft PR not reviewed

Uh oh!

Astro-Han commented Aug 29, 2026

Uh oh!

Astro-Han commented Aug 29, 2026•
edited
Loading

Astro-Han commented Aug 29, 2026•
edited
Loading

Astro-Han commented Aug 29, 2026•
edited
Loading

Astro-Han commented Aug 29, 2026•
edited
Loading

Astro-Han commented Aug 29, 2026•
edited
Loading

Astro-Han commented Aug 29, 2026•
edited
Loading