feat(mobile): add a scroll-to-bottom button to the terminal
Merged
SA
3mo ago+141+141+012345678901234567890123456789-4-4-0123456789
Scrolling back through an agent's output on a phone left no quick way back to the live edge — the overlay scrollbar can be dragged, but only by finding a 20pt gutter and pulling it the whole way.
How it works
- The xterm page reports
{type:"scroll", atBottom}over the bridge whenever the viewport reaches or leaves the bottom of the scrollback, reusing thehidden = buffer.length - term.rowscalculation the overlay scrollbar already makes — the two affordances appear and disappear together and cannot disagree. A new{type:"scrollToBottom"}message scrolls back. - The button is a SwiftUI
Buttonwith.buttonStyle(.glass)via@expo/ui/swift-ui(44pt, matching the navigation bar's own glass buttons), so the press response and Reduce Transparency behaviour are the system's. The deployment target is iOS 26, so.glassneeds no fallback. - Fades in/out (180ms/160ms, native driver — the PTY streams onto the JS thread, a JS-driven fade would stutter under output). Hidden during select mode.
- It lives inside the terminal container rather than the measured composer stack: joining the stack would resize the PTY every time it appeared, and the container's keyboard-driven bottom margin gives it keyboard avoidance on the keyboard's own curve for free.
- In a full-screen TUI the alternate buffer keeps no scrollback, so neither the button nor the scrollbar shows — the TUI (e.g. Claude's fullscreen mode, which draws its own Jump to bottom pill) owns its scroll, and
scrollToBottom()would be a no-op. - Taps are captured as
terminal_scrolled_to_bottomby hand — the tap lands in SwiftUI where RN autocapture cannot see it.
Verification
- Headless (xterm page in Chrome, bridge shimmed): at-bottom flag flips exactly at the edges with no duplicate posts;
scrollToBottomreturnsviewportYtobaseY; in the alternate bufferhiddenis 0 and no report fires. - On device (iPhone 17 sim, iOS 26.5, against a live PTY with 300 lines of scrollback): asserted the button appears after scrolling up, tap returns to the bottom marker, button disappears; still present and correctly repositioned (125pt up) with the composer focused; press shows the system glass press response.
- Incidentally verified the fullscreen standdown against a real Claude session: Claude's own Jump to bottom pill renders while this button stays away.
Notes
terminalHtml.generated.tsis regenerated output ofscripts/generate-terminal-html.ts(do not review by hand).- Maestro can target it via
testID/accessibility labelterminal-scroll-to-bottom/ "Scroll to bottom".
https://claude.ai/code/session_01MmTRNzZsBgjggTXe1qc5TK
Summary by cubic
Adds a scroll-to-bottom button to the mobile terminal so users can quickly return to live output. Previously users dragged the overlay scrollbar; now the button appears off-bottom and hides at the bottom, and the page posts the initial scroll state on boot to prevent stale button state after reconnects.
- Bridge: page→RN
{"type":"scroll","atBottom"}; RN→page{"type":"scrollToBottom"}. Uses the same bottom calculation as the overlay scrollbar to keep them in sync. - TerminalWebView API: adds
scrollToBottom()andonScrollChange(atBottom). - UI: SwiftUI
ButtonwithbuttonStyle("glass")(44pt), native fade in/out, hidden in select mode, always mounted, positioned inside the terminal container for keyboard avoidance without resizing the PTY. - Full-screen TUI: alternate buffer has no scrollback; neither the button nor the overlay scrollbar appears;
scrollToBottom()is a no-op. - Robustness and QA: page now posts the initial scroll state on boot; captures
terminal_scrolled_to_bottomwithworkspace_idandsource: "button";testID"terminal-scroll-to-bottom" and accessibility label "Scroll to bottom". - Review:
terminalHtml.generated.tsis generated fromscripts/generate-terminal-html.ts(do not review by hand).
Summary by CodeRabbit
- New Features
- Added a floating button that appears when the terminal is scrolled away from the bottom.
- Tapping the button quickly returns the terminal view to the latest output.
- The button includes smooth animations and accessibility support.
- Button usage is recorded for product analytics.
- Bug Fixes
- Terminal scroll position now updates correctly after switching sessions.