Skip to content

fix(terminal): add proportional scroll fallback for sidebar resize - #901

Merged
Jinwoo-H merged 14 commits into
mainfrom
Jinwoo-H/sidebar-scroll-reset
Apr 22, 2026
Merged

Jinwoo-H merged 14 commits into
mainfrom
Jinwoo-H/sidebar-scroll-reset

Conversation

@Jinwoo-H

Copy link
Copy Markdown
Contributor

Summary

  • Fixes terminal scrolling to top when toggling the right sidebar (Cmd+L)
  • Root cause: restoreScrollState uses content-based line matching to find the original scroll position after xterm.js reflow. When the first visible line is blank (empty prompt, blank line between outputs) or content can't be matched after reflow, it returned -1 and did nothing — leaving the terminal wherever xterm.js put it (often the top)
  • Adds a proportional fallback: when content matching fails, maps the old viewportY/totalLines ratio into the new buffer dimensions to approximate the original position
  • This also improves scroll preservation for window resizes, font size changes, and any other layout change that triggers reflow

Test plan

  • Open a terminal with scrollback, scroll to middle
  • Press Cmd+L to toggle sidebar — verify scroll position stays approximately the same
  • Repeat with the viewport showing blank lines at the top
  • Verify terminals at bottom still stay at bottom
  • Verify drag-resize scroll preservation still works

Jinwoo-H added 11 commits April 21, 2026 23:21
… fails

When restoreScrollState's content-based line matching fails (first
visible line is blank, or content not found after reflow), the terminal
previously stayed wherever xterm.js left it after the reflow — often
scrolled to the top. This was most visible when toggling the right
sidebar (Cmd+L), which changes column count and triggers reflow.

Adds a proportional fallback: viewportY/totalLines ratio from before the
reflow is mapped into the new buffer dimensions to approximate the
original scroll position.
The 150ms debounce between ResizeObserver fire and fitPanes() gave async
events (WebGL context loss, xterm.js Viewport._sync) time to corrupt
the scroll position. By the time fitAllPanesInternal captured the state,
viewportY was already wrong.

Fix: capture scroll states at the instant the ResizeObserver fires
(before the debounce), then pass those pristine states to the debounced
fit call. This ensures scroll restoration uses the true pre-resize
viewport position regardless of what happens during the 150ms window.
Sidebar toggles (Cmd+L, Cmd+B) change the terminal container width
synchronously, which causes xterm.js to fire internal scroll events
that corrupt viewportY before any ResizeObserver callback can capture
the pre-resize state.

Fix: dispatch a LAYOUT_WILL_CHANGE_EVENT synchronously before every
sidebar state change. Terminal panes listen for this event and lock
scroll states (reusing the same pendingDragScrollState mechanism that
keeps divider drag scroll stable). The lock ensures fitAllPanesInternal
restores from the pre-corruption capture, then a 300ms timer unlocks
after the ResizeObserver debounce + fit cycle settles.
resumeRendering() recreates WebGL contexts and calls refresh(), which
can fire xterm.js internal scroll events that corrupt viewportY before
guardedFit captures state. Capture scroll states before resumeRendering
and pass them through to fitPanes so the pre-corruption position is
always used for restoration.
The layout scroll lock (sidebar toggle, worktree switch) was reusing
pendingDragScrollState, which meant a keyboard sidebar toggle during
an active divider drag could steal the drag's lock. Introduce a
dedicated pendingLayoutScrollState field so the two locking mechanisms
are fully independent.
…d lines

When the viewport starts at a wrapped continuation row (common in
Claude Code sessions with long commands), the continuation's content
doesn't appear as a line start after reflow — content matching fails
and the terminal scrolls to the wrong position.

Fix: walk backward from viewportY to the logical line start (first
non-wrapped row) and use that as the content anchor. Logical line
starts always remain line starts after reflow regardless of column
width. Store the row offset and column count so restoreScrollState
can scale the offset to approximate the correct viewport position
in the new layout.
fit() queues an async _sync() that updates scrollHeight via the
terminal's refresh callback. When the terminal gets wider (fewer wraps
→ smaller scrollHeight), _sync reduces scrollHeight AFTER our
synchronous scrollbar jiggle, causing the browser to clamp scrollTop.
_sync then skips re-setting scrollTop because ydisp === _latestYDisp.
This leaves scrollTop stale — the terminal looks correct but the first
user scroll interaction jumps to the wrong position.

Fix: add a deferred rAF jiggle that runs after _sync has settled,
re-syncing scrollTop to the correct ydisp.
The single-rAF deferred jiggle wasn't sufficient because xterm.js's
queued _sync (via addRefreshCallback) fires after the renderer's rAF,
not before. The _sync updates scrollHeight via setScrollDimensions,
which causes SmoothScrollableElement to clamp scrollTop. But _sync
skips setScrollPosition because _latestYDisp is stale — it's never
updated to the new target since _handleScroll sees diff=0 after each
scrollToLine (buffer.ydisp already matches).

Fix: use double-rAF to guarantee our deferred re-scroll runs after
the render + refresh callback cycle. Re-applying scrollToLine triggers
a new _sync where ydisp !== stale _latestYDisp, forcing
setScrollPosition to correct scrollTop.
- Fully suppress PTY resize during divider drag (no debounce)
- Flush final resize via pane-drag-end DOM event at drag end
- Extend pendingDragScrollState lock 500ms past drag end so
  ResizeObserver doesn't capture SIGWINCH-corrupted viewportY
- Remove deferredDragScrollRestore re-capture to prevent cascading
  state poisoning
- Add isPaneDragResizing() to PaneManager public API

Known issue: brief visual flash during the 500ms settling window
where viewport jumps to top before restoring.
Replace passive setTimeout-only restore with an active rAF loop that
restores scroll every frame during the 500ms settling period. Without
this, Claude Code's SIGWINCH redraw moves viewportY between the
initial restore and the settling timeout, causing a visible flash.
…drag

Add E2E tests covering scroll position preservation during pane divider
drag resize, including wrapping content, triple-split layouts, active
terminal writes, TUI-style SIGWINCH redraws, and an Ink TUI simulator
fixture. Remove diagnostic console.log calls from restoreScrollState.
@Jinwoo-H
Jinwoo-H force-pushed the Jinwoo-H/sidebar-scroll-reset branch from 5e27d0d to 019e271 Compare April 22, 2026 03:22
…ttling loop

Sidebar toggle (Cmd+B / Cmd+L) triggers a CSS transition (200ms) followed
by ResizeObserver debounce (150ms) before the final fit. PTY resize during
this window sends SIGWINCH, causing Claude Code / Ink to redraw and corrupt
viewportY.

Add a settling rAF loop to unlockAllPaneScrollStates that continuously
restores scroll position for 500ms after unlock, absorbing SIGWINCH-driven
redraws. Increase the unlock timer from 300ms to 500ms so it fires after
the final fit. Total lock duration ~1000ms covers all async corruption.
The pane-drag-end event listener requires pane.container, which was
missing from the test mock.
@Jinwoo-H
Jinwoo-H merged commit 2ab2db9 into main Apr 22, 2026
2 checks passed
@Jinwoo-H
Jinwoo-H deleted the Jinwoo-H/sidebar-scroll-reset branch April 22, 2026 04:28
Jinwoo-H added a commit that referenced this pull request Apr 22, 2026
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant