Smart scroll for the agent terminal

[mattmoran56]

Summary

• Streaming pty output yanked the user back to the bottom on every write because xterm follows the cursor on term.write. The terminal now snapshots the user's distance from the bottom before each write and restores it in the post-parse callback, so past output stays readable while the agent streams.
• Returning the viewport to the bottom re-engages auto-follow.
• Detection reads the live .xterm-viewport scrollTop (the only source of truth that updates synchronously with user input — term.onScroll lags because buffer.viewportY syncs from the DOM async).

Implementation

• New src/renderer/components/terminal/smartScroll.ts with pure decision functions (isDomAnchored, distanceFromBottom, computeDomScrollAction, plus buffer-space equivalents kept for symmetry/tests) and a attachSmartScroll(term, getVisible) controller exposing write / isAnchored / dispose.
• useTerminal.ts now routes pty data through controller.write instead of term.write, drops the old anchoredToBottom instance field, and asks the controller for the anchor state in the visibility re-fit effect.

Test plan

• 28 unit tests — pure logic for both buffer-space and DOM-space anchoring/restore math (tests/unit/components/terminal/smartScroll.test.ts)
• 8 controller tests — attachSmartScroll against a fake terminal that simulates xterm's auto-follow on writes (tests/unit/components/terminal/smartScroll.integration.test.ts)
• 2 Playwright e2e tests against the mock backend (tests/e2e/smart-scroll.spec.ts):
  • Scrolling up while the mock streams keeps the user at their position
  • Returning to the bottom re-engages auto-follow
• Manual: verified in the dev app — scrolled up while an agent was emitting output and stayed put; scrolled back to the bottom and auto-follow resumed

Note on screenshots

This is a streaming-time scroll behaviour change — a static screenshot can't show it. The Playwright e2e suite is the canonical demo; it asserts the exact pixel-level behaviour against a real browser running the app.

🤖 Generated with Claude Code