[Bugfix #630] Fix terminal scroll-to-top from split escapes and WebGL context loss - #631
Merged
waleedkadous merged 5 commits intoMar 19, 2026
Merged
Conversation
…equences and WebGL context loss Three fixes for scroll-to-top: 1. EscapeBuffer: buffers incomplete escape sequences split across WebSocket frames, preventing xterm parsing errors that reset viewport 2. ScrollController: auto-corrects unexpected scroll-to-top by restoring previous position instead of just warning 3. WebGL context loss: saves/restores scroll position during renderer transition from WebGL to canvas fallback
…oll-to-top correction
…ytes (CMAP feedback)
…anual scroll (CMAP feedback) Auto-correction can't distinguish parsing-error resets from intentional user scroll-to-top. Root causes are already prevented upstream by EscapeBuffer and WebGL context loss handler. Keep diagnostic warning.
…write-callback correction
waleedkadous
deleted the
builder/bugfix-630-bug-terminal-scroll-to-top-cau
branch
March 19, 2026 12:53
waleedkadous
added a commit
that referenced
this pull request
Mar 19, 2026
Restore auto-correction in ScrollController that was incorrectly removed in #631. A >50 line jump to viewportY=0 is clearly an xterm reset, not user scrolling. User scrolling generates incremental events.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #630
Root Cause
Two distinct triggers cause the terminal to scroll to the top:
Split escape sequences: PTY output containing escape sequences (e.g.,
\x1b[31mfor red text) can be split across WebSocket frames. When xterm.js receives an incomplete escape sequence, it enters escape state and hits a parsing error on the next non-escape character, which can reset its internal buffer state and causeviewportYto jump to 0. This also causesfilterDAto fail on split DA responses, leaving dangling ESC characters.WebGL context loss: When the browser's GPU context is lost (resource pressure, tab switching, GPU driver reset), xterm's WebGL renderer loses state. During the dispose/fallback transition to canvas renderer, the viewport resets to 0.
Fix
Two proactive fixes that prevent the root causes:
EscapeBuffer (
dashboard/src/lib/escapeBuffer.ts): Buffers incoming PTY data and holds back trailing incomplete escape sequences. When the next chunk arrives, the pending data is prepended, ensuring xterm always receives complete escape sequences. Also fixesfilterDAfailing to match DA responses split across frames. Buffer is flushed on reconnect to prevent stale bytes from contaminating new streams.WebGL context loss scroll preservation (
dashboard/src/components/Terminal.tsx): TheonContextLosshandler now saves the viewport position before disposing the WebGL addon and restores it after loading the canvas fallback.Test Plan
CMAP Review
escBuf.flush()in connect resetAll REQUEST_CHANGES addressed. Final architecture: prevent root causes upstream (EscapeBuffer + WebGL handler), warn diagnostically on unexpected scroll-to-top without interfering with user scrolling.