Support clearing scrollback

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+* Support for clearing scrollback with `Screen::clear_scrollback` and `CSI 3 J`.
+
 ## [0.16.2] - 2025-07-11
 
 ### Fixed

examples/generate_fixture.rs

@@ -14,9 +14,8 @@ fn main() {
             .unwrap();
     let inputs = std::io::BufReader::new(inputs);
 
-    let mut i = 1;
     let mut prev_input = vec![];
-    for line in inputs.lines() {
+    for (i, line) in (1..).zip(inputs.lines()) {
         let line = line.unwrap();
 
         let input = helpers::unhex(line.as_bytes());
@@ -36,7 +35,5 @@ fn main() {
         ))
         .unwrap();
         serde_json::to_writer_pretty(output_file, &screen).unwrap();
-
-        i += 1;
     }
 }

src/grid.rs

@@ -199,6 +199,11 @@ impl Grid {
         self.scrollback_offset = rows.min(self.scrollback.len());
     }
 
+    pub fn clear_scrollback(&mut self) {
+        self.scrollback.clear();
+        self.scrollback_offset = 0;
+    }
+
     pub fn write_contents(&self, contents: &mut String) {
         let mut wrapping = false;
         for row in self.visible_rows() {

src/screen.rs

@@ -114,6 +114,16 @@ impl Screen {
         self.grid_mut().set_scrollback(rows);
     }
 
+    /// Clears the scrollback history for the active screen and returns the
+    /// scrollback position to the live viewport.
+    ///
+    /// This does not erase the visible screen contents or reset terminal
+    /// modes. To model a terminal action that clears both the visible display
+    /// and scrollback history, process both `CSI 2 J` and `CSI 3 J`.
+    pub fn clear_scrollback(&mut self) {
+        self.grid_mut().clear_scrollback();
+    }
+
     /// Returns the current position in the scrollback.
     ///
     /// This position indicates the offset from the top of the screen, and is
@@ -1062,6 +1072,7 @@ impl Screen {
             0 => self.grid_mut().erase_all_forward(attrs),
             1 => self.grid_mut().erase_all_backward(attrs),
             2 => self.grid_mut().erase_all(attrs),
+            3 => self.clear_scrollback(),
             _ => unhandled(self),
         }
     }

tests/scroll.rs

@@ -191,6 +191,65 @@ fn scrollback_larger_than_rows() {
     assert_eq!(parser.screen().contents(), gen_nums(1..=3, "\n"));
 }
 
+#[test]
+fn clear_scrollback() {
+    let mut parser = vt100::Parser::new(3, 20, 10);
+
+    parser.process(gen_nums(1..=6, "\r\n").as_bytes());
+    parser.screen_mut().set_scrollback(3);
+    assert_eq!(parser.screen().scrollback(), 3);
+    assert_eq!(parser.screen().contents(), gen_nums(1..=3, "\n"));
+
+    parser.screen_mut().clear_scrollback();
+    assert_eq!(parser.screen().scrollback(), 0);
+    assert_eq!(parser.screen().contents(), gen_nums(4..=6, "\n"));
+
+    parser.screen_mut().set_scrollback(10);
+    assert_eq!(parser.screen().scrollback(), 0);
+}
+
+#[test]
+fn erase_saved_lines_csi_3j() {
+    let mut parser = vt100::Parser::new(3, 20, 10);
+
+    parser.process(gen_nums(1..=6, "\r\n").as_bytes());
+    assert_eq!(parser.screen().contents(), gen_nums(4..=6, "\n"));
+
+    parser.screen_mut().set_scrollback(2);
+    assert_eq!(parser.screen().scrollback(), 2);
+    parser.process(b"\x1b[3J");
+
+    assert_eq!(parser.screen().scrollback(), 0);
+    assert_eq!(parser.screen().contents(), gen_nums(4..=6, "\n"));
+    parser.screen_mut().set_scrollback(10);
+    assert_eq!(parser.screen().scrollback(), 0);
+}
+
+#[test]
+fn erase_saved_lines_csi_3j_preserves_modes() {
+    let mut parser = vt100::Parser::new(3, 20, 10);
+
+    parser.process(b"\x1b[?1h\x1b[?25l\x1b[?1000h\x1b[?1006h\x1b[?2004h");
+    parser.process(gen_nums(1..=6, "\r\n").as_bytes());
+
+    parser.screen_mut().set_scrollback(2);
+    parser.process(b"\x1b[3J");
+
+    assert_eq!(parser.screen().scrollback(), 0);
+    assert_eq!(parser.screen().contents(), gen_nums(4..=6, "\n"));
+    assert!(parser.screen().application_cursor());
+    assert!(parser.screen().hide_cursor());
+    assert!(parser.screen().bracketed_paste());
+    assert_eq!(
+        parser.screen().mouse_protocol_mode(),
+        vt100::MouseProtocolMode::PressRelease
+    );
+    assert_eq!(
+        parser.screen().mouse_protocol_encoding(),
+        vt100::MouseProtocolEncoding::Sgr
+    );
+}
+
 #[cfg(test)]
 fn gen_nums(range: RangeInclusive<u8>, join: &str) -> String {
     range