Make CSI 3 J discard the scrollback instead of erasing the screen

[tomlm]

Reported downstream as Iciclecreek.Avalonia.Terminal#28: cls in cmd.exe leaves the history scrollable with the mouse wheel, unlike conhost and Windows Terminal.

The bug

Mode 3 shared mode 2's body:

case 2: // Erase all
case 3: // Erase scrollback (extension)
    for (int i = 0; i < _terminal.Rows; i++)
        _buffer.Lines[_buffer.YBase + i]?.Fill(emptyCell);

That erases the visible screen and never touches the scrollback — the opposite of what mode 3 asks for. The comment said "erase scrollback"; the code did not. The two modes are complements rather than variations, so a caller wanting both sends 2 and 3.

Why that surfaced as a cls bug

Captured from ConPTY, this is what cls actually emits:

<ESC>[?25l <ESC>[H  ...25× <ESC>[K<CR><LF>...  <ESC>[3J  <ESC>[2;1H

It never sends CSI 2 J. It clears the screen itself, line by line with ESC[K, and then sends CSI 3 J for the history. With mode 3 doing nothing, the history survived.

That also explains the reporter's odd follow-up — that cls did clear a fresh terminal but not one that had run dir first. With no scrollback yet, clearing the screen looks exactly like clearing everything.

The fix

TerminalBuffer.ClearScrollback() trims the lines above the visible screen and moves _yBase and _yDisp with them.

Discarding rather than blanking is the point. Blanked lines are still present and still scrollable, so the history would remain reachable even after the terminal had been told to throw it away.

Moving the indices is load-bearing. _yBase and _yDisp are absolute indices into the line list, so trimming without adjusting them leaves the visible screen pointing at an offset that no longer exists — the next write walks off the end:

IndexOutOfRangeException at CircularList`1.get_Item
  at InputHandler.Print → Terminal.Write

I hit that while probing whether a downstream workaround was possible, which is also how I concluded the fix belonged here rather than in the consumer.

Tests

Four, alongside the existing EraseInDisplay cases. Three fail against the previous behaviour; the fourth, LeavesTheBufferWritable, passes either way and is deliberate — it guards this implementation's own risk, the stale-index crash, rather than reproducing the original defect.

607 tests green.

Version left at 1.0.15 — bumping looks like something you do deliberately at release time.

🤖 Generated with Claude Code