fix(terminal): prevent scroll-to-top race during fast output

[astex]

During fast terminal output (e.g. streaming from Claude Code or other AI tools), the viewport randomly jumps to the top of the scrollback buffer. This makes the terminal unusable during long-running commands that produce rapid output.

The root cause is a race between xterm.js's content-driven scroll and the ResizeObserver-triggered fitAddon.fit(). Tabby disables xterm's built-in scrollToBottom (replacing it with a no-op to manage scroll manually), but the resize handler calls fit() without preserving or restoring the viewport position. During fast output, fit() can reset the viewport to line 0, and since auto-scroll is disabled, nothing brings it back.

A subtlety that makes this worse: xterm.onScroll only fires for content-driven scrolling (new lines added to the buffer), not for user-initiated wheel or keyboard scrolling (xterm.js #3864, #3201). Any attempt to use onScroll to detect user scroll-up intent will falsely trigger during fast output, because viewportY briefly lags behind baseY as new lines arrive. Additionally, during fast output viewportY transiently equals baseY during xterm's internal write processing, which means any code checking isAtBottom() (including onScroll handlers and resize reconciliation) can falsely re-pin the viewport.

The fix tracks a pinnedToBottom flag with careful rules about what can change it:

• Wheel and keyboard events (capture phase) are the only things that can unpin, since they represent actual user scroll intent. Capture phase is required because xterm.js handles events on its internal viewport element and stops propagation.
• Immediate unpin on scroll-up — pinnedToBottom is set to false synchronously on wheel-up/PageUp, before the requestAnimationFrame callback, so that writes arriving before the next frame don't yank the viewport back down.
• No onScroll handler — during fast output, viewportY transiently equals baseY during xterm's internal processing, which would falsely re-pin. Re-pinning happens only through wheel/keyboard RAF callbacks, explicit scrollToBottom() calls, or scroll API methods.
• wasPinned snapshot in write — the write method captures pinnedToBottom before flowControl.write() so that transient state changes during the async write don't affect the scroll decision.
• Resize handler saves and restores scroll position: if pinned, it scrolls to bottom after fit(); if unpinned, it restores the previous viewportY.
• Scroll API methods (scrollToTop, scrollPages, scrollLines, scrollToBottom) update pinned state consistently.

The same class of bug was independently identified and fixed in Fleet, another xterm.js-based terminal.

Tested

• Fast output while pinned to bottom — viewport stays at bottom
• Fast output while scrolled up — viewport holds position, does not jump to top or bottom
• Resize during fast output — viewport does not jump to line 0
• Re-pin on scroll to bottom — scrolling back to bottom during output re-pins and follows new output
• Scroll API (Ctrl+Home, Ctrl+End, PageUp/PageDown) — works normally
• Idle terminal scrolling — no regressions

Fixes #10648

[wdjwxh]

finally , cant wait to merge

[astex]

finally , cant wait to merge

IKR?

Seems to work empirically. I've reasoned through each of the hacks that Claude threw together here, understand them, and think they are reasonable. And after staring at the code a bit, I don't see any obvious cleaner approach (besides maybe give up on the workarounds entirely and just lean on xterm's scroll behavior).

But, it really feels like there should be a cleaner approach to this.

[astex]

@Eugeny I'm not sure what I need to do to request review.

[wdjwxh]

I just hang in the startup screen..

[zhepoch]

Hi @Eugeny, did you have some time to review this PR? I think it can resolve the Claude code scroll-to-top problem. I absolutely love Tabby, but using Claude codes in it is so inconvenient.

[jose-cabral]

Can't wait to have this merged 🙏

[astex]

Alright. Well the fix has taken long enough to get reviewed that I've rolled my own terminal emulator with a specific focus on agentic work with claude. https://github.com/astex/mandelbot

I'll keep tabs on this in case anything changes.

GitHub

GitHub - astex/mandelbot

Contribute to astex/mandelbot development by creating an account on GitHub.