Skip to content

Terminal: implement the alternate screen buffer (DEC mode 1049) - #2899

Merged
akurtakov merged 1 commit into
eclipse-platform:masterfrom
insjang:alt-screen
Nov 4, 2026
Merged

akurtakov merged 1 commit into
eclipse-platform:masterfrom
insjang:alt-screen

Conversation

@insjang

@insjang insjang commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Full screen programs - vi, less, htop, and lately CLIs that draw their own UI - ask for the alternate screen with CSI ? 1049 h and give it back with CSI ? 1049 l. The emulator accepted the sequences and ignored them, so such a program drew over the shell's scrollback and left its last screen behind when it exited.

Switching to the alternate screen now saves the normal buffer and the cursor, clears the screen and caps the buffer at the screen height, so that scrolling drops the top line instead of growing history the alternate screen is not supposed to have. Switching back restores the saved buffer and cursor, lifts the cap again, and brings the buffer to the current width and at least the screen height, since the window may have been resized in the meantime: a narrower buffer made every write past its old margin throw, a shorter one put the top of the screen above its first line. The restored buffer tells its snapshots so the view redraws instead of keeping the program's last screen.

Modes 47 and 1047 are treated the same; 1048 (save/restore cursor alone) stays ignored. Asking for the screen one is already on is a no-op, as programs do ask twice.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Resizing on the alternate screen can recreate scrollback and restore the cursor onto the wrong history line.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2 Medium severity

Open (2)
What changed in this PR

Implements DEC alternate-screen buffers so full-screen terminal applications preserve shell content and scrollback.

Changes:

  • Handles DEC modes 47, 1047, and 1049.
  • Saves/restores terminal content and cursor state.
  • Adds snapshot notifications and alternate-screen tests.
File Description
VT100EmulatorTest.java Tests escape-sequence switching.
VT100EmulatorBackendTest.java Tests buffer restoration and resizing.
TerminalTextData.java Notifies snapshots after copying.
VT100EmulatorBackend.java Implements alternate-buffer lifecycle.
VT100Emulator.java Dispatches DEC screen modes.
VT100BackendTraceDecorator.java Traces screen switches.
IVT100EmulatorBackend.java Adds the switching API.
META-INF/​MANIFEST.MF Increments the bundle version.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Test Results

    54 files  ± 0      54 suites  ±0   34m 12s ⏱️ - 2m 31s
 4 968 tests +18   4 946 ✅ +18   22 💤 ±0  0 ❌ ±0 
12 795 runs  +54  12 641 ✅ +54  154 💤 ±0  0 ❌ ±0 

Results for commit e9a976f. ± Comparison against base commit 8719d5b.

♻️ This comment has been updated with latest results.

insjang added a commit to insjang/eclipse.platform that referenced this pull request Sep 28, 2026
The alternate screen caps its buffer at the screen height so that
nothing scrolls into history. The cap was set once, on entry, so after
the window shrank the buffer grew back to the old height and left
history behind. It now follows the screen height on every resize.

The cursor of the normal screen was saved as a row of the screen. When
the window grew meanwhile, the same row pointed into older history on
return, and the next output overwrote it. It is now saved as a line of
the normal buffer and turned back into a row of the screen as it is on
return.

Found by review of eclipse-platform#2899.
@insjang

insjang commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Rebased on current master and addressed both review comments in 0924176, with tests.

@insjang

insjang commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up in 84b7af6: 0924176 lowered the cap while the buffer could still be higher than the new screen, which TerminalTextDataFastScroll (the buffer the terminal actually uses) rejects with an IllegalArgumentException, so shrinking the window under a full screen program threw from the resize handler. TerminalTextDataStore, which the tests use, accepts it. The alternate screen now keeps its buffer exactly as high as the screen, dropping lines above the cursor on a shorter one, and only then sets the cap. testAlternateScreenShrunkKeepsNoHistory now runs on both buffers.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Alternate-screen state can survive reconnection, preference updates can re-enable history, and duplicate disable sequences reset normal-screen state.

Review effort: Balanced
Findings: 1 High severity · 4 Medium severity

Open (5)

insjang added a commit to insjang/eclipse.platform that referenced this pull request Sep 30, 2026
The alternate screen caps its buffer at the screen height so that
nothing scrolls into history. The cap was set once, on entry, so after
the window shrank the buffer grew back to the old height and left
history behind. It now follows the screen height on every resize.

The cursor of the normal screen was saved as a row of the screen. When
the window grew meanwhile, the same row pointed into older history on
return, and the next output overwrote it. It is now saved as a line of
the normal buffer and turned back into a row of the screen as it is on
return.

Found by review of eclipse-platform#2899.
@insjang
insjang force-pushed the alt-screen branch 2 times, most recently from 65493b4 to 87b9ec5 Compare November 4, 2026 01:14
@insjang

insjang commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Rebased on master (with #2894 in) and squashed into one commit, 87b9ec5; all terminal tests pass.

How to test, in a runtime Eclipse with this org.eclipse.terminal.control, Terminal view, local shell:

  1. Fill the scrollback: seq 1 200
  2. Run a full screen program and quit it: less /etc/services (or vi, man ls, htop), scroll a few pages, q.
    Expected: the shell screen comes back as it was before, with the prompt below 200. Scrolling up shows 1..200 and none of the program's pages. Before this change the program's last screen stayed behind and its pages ended up in the scrollback.
  3. Resize while the program runs: start less /etc/services, make the view much shorter, then taller, then narrower, then quit.
    Expected: no exception in the Error Log, the shell screen comes back whole and the prompt is on the line after 200.
  4. Without a program: printf '\e[?1049h'; seq 1 50; sleep 2; printf '\e[?1049l'
    Expected: the numbers show for two seconds and are gone afterwards, also from the scrollback.
  5. A repeated switch back is a no-op: printf '\e[2;5r\e[?1049l'; seq 1 20 keeps the scroll region set first (lines 2..5 scroll), as before.
  6. Disconnect while a program has the screen: start vi, disconnect the terminal (or close the shell from outside), connect again.
    Expected: the new session starts on the normal screen with scrollback.

Unit tests: VT100EmulatorBackendTest (testAlternateScreenBuffer, testAlternateScreenShrunkKeepsNoHistory, testBufferLineLimitWhileAlternateScreen, testResetStateLeavesAlternateScreen) and VT100EmulatorTest (testAlternateScreen, testRepeatedAlternateScreenOffKeepsMargins), run on both TerminalTextDataStore and TerminalTextDataFastScroll.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@insjang

insjang commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

All five were real; fixed in 46cefbd, each with a test that fails without the change: ESC c now leaves the alternate screen first, as the connection reset does. Switching back puts the normal screen back as if it had been resized along with the alternate one: with no history, the unused rows below the cursor go when the screen got shorter, so the cursor returns to its prompt; rows the buffer gains are cleared; a limit lowered meanwhile takes the oldest lines, never the screen; and a wrap pending on the last column is pending again if the width is unchanged. The new tests run on TerminalTextDataFastScroll as well. All terminal tests pass.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@insjang

insjang commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

All six Copilot findings since the rebase were real and are fixed in ab4267a, each with a test that fails without the change: ESC c leaves the alternate screen; switching back resizes the normal screen as the alternate one was resized (unused rows below the cursor go, gained rows are cleared, a lowered limit takes the oldest lines), keeps a pending wrap, and restores the shell's rendition. The three threads still marked open (reset on reconnect, the cap across preference updates, a duplicate 1049l) were fixed in September and are part of the same commit. All terminal tests pass.

@akurtakov
akurtakov requested a balanced review from Copilot November 4, 2026 08:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Entering the alternate screen resets the active rendition to the default style, causing text to lose previously selected colours even though no SGR reset was sent.

3 open issues
2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the alternate-screen support change.

No open issues 🎉

3 resolved since last review

Review effort: Balanced

@akurtakov akurtakov left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, all the Copilot findings look fixed to me, and putting the normal screen back through the same rules as a resize is a good way to do it. Two things left: Clear Terminal while a program is showing is undone when it exits, and getBufferLineLimit() reports the screen height meanwhile. The rest are minor. Details inline.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Alternate-screen modes 47 and 1047 incorrectly reset the cursor to the top-left, so switching must preserve the cursor position and pending-wrap state when cursor saving is disabled.

1 open issue

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The tests do not verify snapshot invalidation and refreshed contents after model copies with unchanged or changed dimensions, leaving the stale-display regression uncovered.

1 open issue
1 resolved since last review

Review effort: Balanced

Full screen programs - vi, less, htop, and lately CLIs that draw their
own UI - ask for the alternate screen with CSI ? 1049 h and give it
back with CSI ? 1049 l. The emulator accepted the sequences and ignored
them, so such a program drew over the shell's scrollback and left its
last screen behind when it exited.

Switching to the alternate screen now saves the normal buffer and the
cursor, clears the screen and keeps the buffer exactly as high as the
screen, so that scrolling drops the top line instead of growing history
the alternate screen is not supposed to have. The cap follows every
resize; on a shorter screen the lines above the cursor are dropped, as
many as it takes to keep the cursor on the screen.

Switching back puts the normal screen back as if it had been resized
along with the alternate one, since the window may have been resized
in the meantime: as wide as the screen and at least as high; with no
history, the unused rows below the cursor go when the screen got
shorter; rows the buffer gains are cleared, as they may still hold what
the program drew there; and a buffer line limit lowered meanwhile takes
the oldest lines, never the screen. The cursor is saved as a line of
the normal buffer, not a row of the screen, so it comes back to the
same text however the screen has changed, and a wrap pending on the
last column is pending again if the line is as wide as it was. The
rendition the shell had selected carries over into the alternate
screen, as no SGR reset was sent, and comes back with the cursor, as
DECSC saves it, so the program's colours do not leak into the shell's
output. The restored
buffer tells its snapshots so the view redraws instead of keeping the
program's last screen. The scroll region is reset only when the screen
actually switches back.

A reset leaves the alternate screen, so a connection that ended while a
full screen program had the screen does not leave the next one on the
capped buffer, and so does a full reset (ESC c). It leaves the alternate
screen before resetting the rendition, which leaving it puts back. The buffer line limit from the preferences goes through
the backend, which keeps it for the normal screen while the alternate
one is showing.

The modes differ in the cursor as in xterm: 1049 saves it on the way in
and restores it on the way out, as DECSC and DECRC do, while 47 and
1047 move it neither way in nor out, a pending wrap included; 1048 saves and restores it as
ESC 7 and ESC 8 do. ESC 7 keeps a slot per screen, so a program saving
its cursor does not overwrite the one the shell saved. The alternate
screen starts blank for all three, where xterm keeps its contents
between switches for 47. Asking for the screen one is already on is a
no-op, as programs do ask twice.

Clear Terminal while a program has the alternate screen clears the
normal screen behind it as well, its cursor kept on its row, so leaving
the program does not bring back what the user cleared. The buffer line
limit is read through the backend as it is written, so it reports the
normal screen's limit while the alternate screen shows.

Tests run on both TerminalTextDataStore and TerminalTextDataFastScroll,
the buffer the terminal actually uses.
TerminalTextDataSnapshotTest checks that a copy into the model refreshes
its snapshots, at the same size and at another.
@akurtakov

Copy link
Copy Markdown
Member

This looks good to me now. Being able to use vi and exit it properly in eclipse is a fun state :).

@akurtakov
akurtakov merged commit b528d00 into eclipse-platform:master Nov 4, 2026
18 checks passed
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.

3 participants