feat(mobile): add a scroll-to-bottom button to the terminal

Merged
SA
3mo ago
+141-4

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 the hidden = buffer.length - term.rows calculation 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 Button with .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 .glass needs 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_bottom by 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; scrollToBottom returns viewportY to baseY; in the alternate buffer hidden is 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.ts is regenerated output of scripts/generate-terminal-html.ts (do not review by hand).
  • Maestro can target it via testID/accessibility label terminal-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() and onScrollChange(atBottom).
  • UI: SwiftUI Button with buttonStyle("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_bottom with workspace_id and source: "button"; testID "terminal-scroll-to-bottom" and accessibility label "Scroll to bottom".
  • Review: terminalHtml.generated.ts is generated from scripts/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.