Skip to content

feat(terminal): reduce xterm.js scrollback for background terminals#3361

Merged
gregpriday merged 2 commits intodevelopfrom
feature/issue-3281-reduce-xterm-js-scrollback
Mar 16, 2026
Merged

feat(terminal): reduce xterm.js scrollback for background terminals#3361
gregpriday merged 2 commits intodevelopfrom
feature/issue-3281-reduce-xterm-js-scrollback

Conversation

@gregpriday
Copy link
Collaborator

Summary

  • Terminals that transition to the BACKGROUND tier now have their xterm.js scrollback shrunk to a reduced limit, freeing the idle buffer memory
  • When a terminal returns to an active tier, the scrollback limit is restored to the configured value so new output fills up to the full buffer
  • Reductions are skipped if the user is actively scrolled up or has a live text selection, preventing jarring scroll snaps or selection corruption

Resolves #3281

Changes

  • shared/config/scrollback.ts: added BACKGROUND_SCROLLBACK constant (500 lines) to define the reduced background limit
  • src/services/terminal/TerminalInstanceService.ts: added applyScrollbackForTier() method wired into onTierApplied — expands on upgrade, shrinks on downgrade with scroll-position and selection guards
  • src/services/terminal/__tests__/TerminalInstanceService.scrollback.test.ts: unit tests covering all guard conditions (scrolled up, active selection, alternate buffer) and the normal upgrade/downgrade paths

Testing

Unit tests pass. Guard conditions (scroll position, text selection, alternate buffer) tested directly. The alternate buffer case is implicitly safe — xterm.js enforces scrollback: 0 for alternate buffers regardless of what we set.

@gregpriday
Copy link
Collaborator Author

Review status: Fixed and ready

Fixes applied:

  • Changed SCROLLBACK_BACKGROUND from 1000 to 500 lines

Reason: PR #3365 reduces SCROLLBACK_DEFAULT from 2500 to 1000. With SCROLLBACK_BACKGROUND also at 1000, the background reduction would be a no-op for users on the default setting. Lowering to 500 preserves meaningful memory savings when terminals move to background tier.

…tions

- Add SCROLLBACK_BACKGROUND=1000 constant to shared/config/scrollback.ts
- Wire onTierApplied to call reduceScrollback on BACKGROUND tier and restoreScrollback on active tiers
- Add isAltBuffer and hasSelection() guards to reduceScrollback to prevent data loss
- Add deferred retry hooks in scroll, selection, and buffer-mode listeners for skipped trims
- Add tests for new isAltBuffer and hasSelection guard conditions
- Add writtenData assertions to isAltBuffer and hasSelection skip tests
- Verify no warning text is written when reduction is skipped
@gregpriday gregpriday force-pushed the feature/issue-3281-reduce-xterm-js-scrollback branch from 51d063b to 6ac9ca0 Compare March 16, 2026 06:27
@gregpriday gregpriday merged commit e80f8ea into develop Mar 16, 2026
3 checks passed
@gregpriday gregpriday deleted the feature/issue-3281-reduce-xterm-js-scrollback branch March 16, 2026 06:27
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.

Reduce xterm.js scrollback for background terminals to reclaim memory

1 participant