feat(tty): add display erase commands (#23)

Author: tonyfettes

README.md

@@ -34,10 +34,10 @@ Use `Tty` when an operation needs a real terminal handle:
 - dynamic color queries: `Tty::query_default_foreground_color`,
   `Tty::query_default_background_color`, and `Tty::query_cursor_color`
 - terminal events: `Tty::read_event`
-- output commands: cursor movement/visibility, line erase, scroll margins,
-  reverse index, alternate screen, bracketed paste mode, SGR mouse tracking,
-  focus tracking, DEC auto wrap mode, foreground/background colors, text
-  attributes, and style reset
+- output commands: cursor movement/visibility, line/display/scrollback erase,
+  scroll margins, reverse index, alternate screen, bracketed paste mode, SGR
+  mouse tracking, focus tracking, DEC auto wrap mode, foreground/background
+  colors, text attributes, and style reset
 
 Raw file and stdio byte I/O should use `moonbitlang/async/fs` and
 `moonbitlang/async/stdio` directly. The root package does not wrap them as

docs/plan.md

@@ -18,6 +18,7 @@ This board tracks implementation direction for `moonbit-community/tty`. Use
 | TTY-2 | done | termios state and raw mode | `state.mbt`, `state.c`, `examples/raw` | callers can capture, make raw, restore, and manually validate raw input | `moon check`, `moon test`, `examples/raw` manual run |
 | VT-1 | done | cursor movement and visibility sequences | `vt/cursor.mbt`, `vt/cursor_test.mbt`, `examples/cursor` | cursor helpers emit expected bytes and demo can draw a bounded region | `moon test vt`, `examples/cursor` manual run |
 | VT-2 | done | line erase and alternate screen helpers | `vt/erase.mbt`, `vt/screen.mbt`, `examples/input`, `examples/cursor` | demos can redraw one-line input and restore screen state | `moon test vt`, demo manual run |
+| VT-6 | done | display and scrollback erase commands | `docs/plans/2026-06-01-erase-display.md`, `internal/vt/erase.mbt`, root package | root `Tty` can emit `CSI 2 J` and `CSI 3 J` without screen state | `moon fmt`, `moon test internal/vt`, `moon test .`, `moon check`, `moon info`, `git diff --check` |
 | IN-1 | done | input event reader and common key sequences | `docs/plans/2026-05-20-input-event-reader.md` | `EventReader` decodes common keys while preserving unknown sequences | `moon fmt`, `moon check`, `moon test input`, `moon check examples/input`, `moon info`, manual `examples/input` run |
 | IN-2 | done | UTF-8 text decoding via core utf8 | `docs/plans/2026-05-20-utf8-input-decoding.md`, `input/` | non-ASCII text is decoded with `moonbitlang/core/encoding/utf8` without a local utf8 package | `moon fmt`, `moon check`, `moon test input`, `moon info` |
 | IN-5 | done | event reader buffer window | `docs/plans/2026-05-20-event-reader-buffer-window.md`, `input/` | `EventReader` uses one dynamic ordered byte window for current-event bytes and unread bytes | `moon fmt`, `moon check`, `moon test input`, `moon info` |

docs/plans/2026-06-01-erase-display.md

@@ -0,0 +1,114 @@
+# Display Erase Commands
+
+## Goal
+
+Add root `Tty` command helpers for `CSI 2 J` and `CSI 3 J`, while keeping VT
+byte construction internal and avoiding any terminal screen or scrollback state
+model.
+
+## Status
+
+Done.
+
+## Context And Decisions
+
+- `CSI 2 J` is Erase in Display (ED) mode 2. It clears the visible display.
+- `CSI 3 J` is the common xterm extension for clearing saved lines or
+  scrollback.
+- Avoid the name `erase_display_all` because it can imply that `CSI 2 J` also
+  clears scrollback.
+- Use the shorter approved root method names:
+  - `erase_display`
+  - `erase_scrollback`
+- These are output-side commands only. Unsupported terminals may ignore
+  `CSI 3 J`; no support query is added.
+
+## References Or Standards
+
+- ECMA-48 Erase in Display (ED), `CSI Ps J`.
+- xterm-compatible `CSI 3 J` saved-lines erase extension.
+
+## Target Files
+
+- `internal/vt/erase.mbt`
+- `internal/vt/erase_test.mbt`
+- `style.mbt`
+- `tty_wbtest.mbt`
+- `README.md`
+- `docs/plan.md`
+- generated `.mbti` files from `moon info`
+
+## Public API Changes
+
+Root package additions:
+
+- `Tty::erase_display(Self) -> Unit`
+- `Tty::erase_scrollback(Self) -> Unit`
+
+Internal VT package additions:
+
+- `erase_display : Bytes`
+- `erase_scrollback : Bytes`
+
+No new public type, parser state, input event, platform backend, dependency, or
+capability query is proposed.
+
+## Invariants
+
+- `Tty` remains the public output-command surface.
+- `internal/vt` remains byte-sequence-only and does not own output streams.
+- The package does not remember, infer, or expose terminal display state.
+- The package does not model or manage terminal scrollback.
+
+## Acceptance Criteria
+
+- Internal VT helpers emit `CSI 2 J` and `CSI 3 J`.
+- Root command helpers write the same bytes through `Tty`.
+- Generated `.mbti` diffs contain only the intended API additions.
+- README mentions display and scrollback erase as output commands.
+
+## Validation Commands
+
+- `moon fmt`
+- `moon test internal/vt`
+- `moon test .`
+- `moon check`
+- `moon info`
+- review generated `.mbti` diff
+- `git diff --check`
+
+## Public API Audit
+
+- Root `.mbti` adds only `Tty::erase_display` and
+  `Tty::erase_scrollback`.
+- Internal VT `.mbti` adds only the `erase_display` and `erase_scrollback`
+  byte constants used by root command methods.
+- No public type, mutable field, parser state, input event, platform handle,
+  backend selection, dependency, or capability query was added.
+- Generated `.mbti` files were reviewed after `moon info`.
+
+## Result Notes
+
+- Added fixed ED byte constants for `CSI 2 J` and `CSI 3 J`.
+- Added root write-through helpers on `Tty`.
+- Added internal VT byte tests and extended the root pipe-backed terminal
+  command test to cover both new methods.
+- Updated README output-command wording and the execution board.
+- Real terminal clear behavior needs a terminal emulator with observable screen
+  state; pipe and PTY tests only verify byte traffic. No terminal-emulator
+  integration test was added for this task.
+
+## Validation Results
+
+- `moon fmt` passed.
+- `moon test internal/vt` passed: 18 tests.
+- `moon test .` passed: 24 tests.
+- `moon test` passed: 146 tests.
+- `moon check` passed.
+- `moon info` passed and regenerated intended `.mbti` entries.
+- generated `.mbti` diff reviewed.
+- `git diff --check` passed.
+
+## Open Questions
+
+- None.

internal/vt/erase.mbt

@@ -15,3 +15,15 @@ pub let erase_line_left : Bytes = b"\x1b[1K"
 ///
 /// Erases the entire current line.
 pub let erase_line_all : Bytes = b"\x1b[2K"
+
+///|
+/// Erase in Display (ED), ECMA-48.
+///
+/// Erases the visible display.
+pub let erase_display : Bytes = b"\x1b[2J"
+
+///|
+/// Erase in Display (ED), xterm extension.
+///
+/// Erases saved lines in the terminal scrollback.
+pub let erase_scrollback : Bytes = b"\x1b[3J"

internal/vt/erase_test.mbt

@@ -4,3 +4,9 @@ test "erase line sequences" {
   @debug.assert_eq(@vt.erase_line_left, b"\x1b[1K")
   @debug.assert_eq(@vt.erase_line_all, b"\x1b[2K")
 }
+
+///|
+test "erase display sequences" {
+  @debug.assert_eq(@vt.erase_display, b"\x1b[2J")
+  @debug.assert_eq(@vt.erase_scrollback, b"\x1b[3J")
+}

internal/vt/pkg.generated.mbti

@@ -50,12 +50,16 @@ pub let enable_sgr_mouse : Bytes
 
 pub let enter_alt_screen : Bytes
 
+pub let erase_display : Bytes
+
 pub let erase_line_all : Bytes
 
 pub let erase_line_left : Bytes
 
 pub let erase_line_right : Bytes
 
+pub let erase_scrollback : Bytes
+
 pub let hide_cursor : Bytes
 
 pub let italic : Bytes

pkg.generated.mbti

@@ -63,7 +63,9 @@ pub async fn Tty::enable_focus_tracking(Self) -> Unit
 pub async fn Tty::enable_mouse(Self, MouseTrackingMode) -> Unit
 pub async fn Tty::enter_alt_screen(Self) -> Unit
 pub fn Tty::enter_raw_mode(Self) -> State raise @os_error.OSError
+pub async fn Tty::erase_display(Self) -> Unit
 pub async fn Tty::erase_line_all(Self) -> Unit
+pub async fn Tty::erase_scrollback(Self) -> Unit
 pub fn Tty::get_state(Self) -> State raise @os_error.OSError
 pub async fn Tty::hide_cursor(Self) -> Unit
 pub async fn Tty::italic(Self) -> Unit

style.mbt

@@ -446,6 +446,18 @@ pub async fn Tty::erase_line_all(self : Self) -> Unit {
   self.write(@vt.erase_line_all)
 }
 
+///|
+/// Erase the visible display (ED 2), ECMA-48.
+pub async fn Tty::erase_display(self : Self) -> Unit {
+  self.write(@vt.erase_display)
+}
+
+///|
+/// Erase saved lines in the terminal scrollback (ED 3), xterm extension.
+pub async fn Tty::erase_scrollback(self : Self) -> Unit {
+  self.write(@vt.erase_scrollback)
+}
+
 ///|
 /// Set Top and Bottom Margins (DECSTBM).
 pub async fn Tty::set_top_bottom_margins(

tty_wbtest.mbt

@@ -63,6 +63,8 @@ async test "pipe tty terminal commands write sequences" {
     tty.cursor_up(2)
     tty.cursor_forward(3)
     tty.erase_line_all()
+    tty.erase_display()
+    tty.erase_scrollback()
     tty.set_top_bottom_margins(1, 5)
     tty.reverse_index()
     tty.reset_top_bottom_margins()
@@ -85,7 +87,7 @@ async test "pipe tty terminal commands write sequences" {
   })
   inspect(
     output,
-    content="\u{1B}[?1049h\u{1B}[?2004h\u{1B}[?25l\u{1B}[3;4H\u{1B}[2A\u{1B}[3C\u{1B}[2K\u{1B}[1;5r\u{1B}M\u{1B}[r\u{1B}[31m\u{1B}[39m\u{1B}[48;5;42m\u{1B}[49m\u{1B}[1m\u{1B}[22m\u{1B}[3m\u{1B}[23m\u{1B}[4m\u{1B}[24m\u{1B}[7m\u{1B}[27m\u{1B}[0m\u{1B}[?25h\u{1B}[?2004l\u{1B}[?1049l",
+    content="\u{1B}[?1049h\u{1B}[?2004h\u{1B}[?25l\u{1B}[3;4H\u{1B}[2A\u{1B}[3C\u{1B}[2K\u{1B}[2J\u{1B}[3J\u{1B}[1;5r\u{1B}M\u{1B}[r\u{1B}[31m\u{1B}[39m\u{1B}[48;5;42m\u{1B}[49m\u{1B}[1m\u{1B}[22m\u{1B}[3m\u{1B}[23m\u{1B}[4m\u{1B}[24m\u{1B}[7m\u{1B}[27m\u{1B}[0m\u{1B}[?25h\u{1B}[?2004l\u{1B}[?1049l",
   )
 }