feat: add scroll navigation, Clear, and AddMarker to Terminal

Add public Terminal methods for programmatic scroll navigation and
viewport management, porting the upstream xterm.js CoreTerminal and
headless Terminal APIs:

- ScrollLines(disp) — scroll viewport by N lines
- ScrollPages(pageCount) — scroll viewport by N pages
- ScrollToTop() — scroll to top of scrollback
- ScrollToBottom() — scroll to bottom (latest output)
- ScrollToLine(line) — scroll to specific line
- Clear() — clear viewport and scrollback
- AddMarker(cursorYOffset) — create marker relative to cursor

Fixes #21

Co-authored-by: Ona <no-reply@ona.com>

Author: ona-automations

terminal.go

@@ -277,6 +277,67 @@ func (t *Terminal) ScrollTop() int { return t.bufferService.Buffer().ScrollTop }
 // ScrollBottom returns the bottom of the scroll region (0-based).
 func (t *Terminal) ScrollBottom() int { return t.bufferService.Buffer().ScrollBottom }
 
+// ScrollLines scrolls the viewport by disp lines (negative = up, positive = down).
+func (t *Terminal) ScrollLines(disp int) {
+	t.bufferService.ScrollLines(disp, false)
+}
+
+// ScrollPages scrolls the viewport by pageCount pages.
+func (t *Terminal) ScrollPages(pageCount int) {
+	t.ScrollLines(pageCount * t.bufferService.Rows)
+}
+
+// ScrollToTop scrolls the viewport to the top of the scrollback.
+func (t *Terminal) ScrollToTop() {
+	t.ScrollLines(-t.bufferService.Buffer().YDisp)
+}
+
+// ScrollToBottom scrolls the viewport to the bottom (latest output).
+func (t *Terminal) ScrollToBottom() {
+	t.ScrollLines(t.bufferService.Buffer().YBase - t.bufferService.Buffer().YDisp)
+}
+
+// ScrollToLine scrolls the viewport so that the given line is at the top.
+func (t *Terminal) ScrollToLine(line int) {
+	t.ScrollLines(line - t.bufferService.Buffer().YDisp)
+}
+
+// Clear clears the viewport and scrollback buffer, preserving the line the
+// cursor is on. Ported from xterm.js src/headless/Terminal.ts clear().
+func (t *Terminal) Clear() {
+	buf := t.bufferService.Buffer()
+	if buf.YBase == 0 && buf.Y == 0 {
+		// Nothing to clear.
+		return
+	}
+
+	// Clear rows above the cursor.
+	for i := buf.YBase + buf.Y - 1; i >= buf.YBase; i-- {
+		line := buf.Lines.Get(i)
+		if line != nil && line.GetTrimmedLength() != 0 {
+			break
+		}
+		if i > buf.YBase+buf.Y-1 {
+			continue
+		}
+		buf.Lines.Set(i, buf.GetBlankLine(nil, false))
+	}
+
+	// Trim scrollback.
+	buf.Lines.TrimStart(buf.YBase)
+	buf.YBase = 0
+	buf.YDisp = 0
+	t.bufferService.IsUserScrolling = false
+
+	t.OnScrollEmitter.Fire(buf.YDisp)
+}
+
+// AddMarker creates a marker at the cursor position plus the given offset.
+func (t *Terminal) AddMarker(cursorYOffset int) *Marker {
+	buf := t.bufferService.Buffer()
+	return buf.AddMarker(buf.YBase + buf.Y + cursorYOffset)
+}
+
 // Scrollback returns the scrollback buffer size.
 func (t *Terminal) Scrollback() int { return t.optionsService.Options.Scrollback }
 

terminal_test.go

@@ -843,3 +843,251 @@ func TestTerminalRegisterOscHandler(t *testing.T) {
 	}
 }
 
+// fillScrollback writes enough lines to the terminal to create scrollback content.
+func fillScrollback(term *Terminal, lineCount int) {
+	for i := range lineCount {
+		term.WriteString(fmt.Sprintf("line %d\r\n", i))
+	}
+}
+
+func TestTerminalScrollLines(t *testing.T) {
+	t.Parallel()
+
+	type Expectation struct {
+		YDisp int
+		YBase int
+	}
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	yBase := term.Buffer().YBase
+
+	// Scroll up 3 lines
+	term.ScrollLines(-3)
+
+	got := Expectation{
+		YDisp: term.Buffer().YDisp,
+		YBase: term.Buffer().YBase,
+	}
+	expected := Expectation{
+		YDisp: yBase - 3,
+		YBase: yBase,
+	}
+	if diff := cmp.Diff(expected, got); diff != "" {
+		t.Errorf("(-want +got):\n%s", diff)
+	}
+}
+
+func TestTerminalScrollLinesDown(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	// Scroll up then back down
+	term.ScrollLines(-5)
+	term.ScrollLines(5)
+
+	if term.Buffer().YDisp != term.Buffer().YBase {
+		t.Errorf("YDisp = %d, want %d (YBase)", term.Buffer().YDisp, term.Buffer().YBase)
+	}
+}
+
+func TestTerminalScrollPages(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 30)
+
+	yBase := term.Buffer().YBase
+
+	// Scroll up 2 pages (2 * 5 rows = 10 lines)
+	term.ScrollPages(-2)
+
+	expected := yBase - 10
+	if term.Buffer().YDisp != expected {
+		t.Errorf("YDisp = %d, want %d", term.Buffer().YDisp, expected)
+	}
+}
+
+func TestTerminalScrollToTop(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	term.ScrollToTop()
+
+	if term.Buffer().YDisp != 0 {
+		t.Errorf("YDisp = %d, want 0", term.Buffer().YDisp)
+	}
+}
+
+func TestTerminalScrollToBottom(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	// Scroll to top first, then back to bottom
+	term.ScrollToTop()
+	term.ScrollToBottom()
+
+	if term.Buffer().YDisp != term.Buffer().YBase {
+		t.Errorf("YDisp = %d, want %d (YBase)", term.Buffer().YDisp, term.Buffer().YBase)
+	}
+}
+
+func TestTerminalScrollToLine(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	term.ScrollToLine(5)
+
+	if term.Buffer().YDisp != 5 {
+		t.Errorf("YDisp = %d, want 5", term.Buffer().YDisp)
+	}
+}
+
+func TestTerminalScrollToLineClamps(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	// Scroll to a line beyond YBase — should clamp to YBase
+	term.ScrollToLine(9999)
+
+	if term.Buffer().YDisp != term.Buffer().YBase {
+		t.Errorf("YDisp = %d, want %d (YBase)", term.Buffer().YDisp, term.Buffer().YBase)
+	}
+}
+
+func TestTerminalScrollNoScrollback(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	// No scrollback content — scrolling should be a no-op
+	term.ScrollLines(-5)
+
+	if term.Buffer().YDisp != 0 {
+		t.Errorf("YDisp = %d, want 0", term.Buffer().YDisp)
+	}
+}
+
+func TestTerminalClear(t *testing.T) {
+	t.Parallel()
+
+	type Expectation struct {
+		YBase           int
+		YDisp           int
+		IsUserScrolling bool
+	}
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	// Scroll up to simulate user scrolling
+	term.ScrollToTop()
+
+	term.Clear()
+
+	got := Expectation{
+		YBase:           term.Buffer().YBase,
+		YDisp:           term.Buffer().YDisp,
+		IsUserScrolling: term.bufferService.IsUserScrolling,
+	}
+	expected := Expectation{
+		YBase:           0,
+		YDisp:           0,
+		IsUserScrolling: false,
+	}
+	if diff := cmp.Diff(expected, got); diff != "" {
+		t.Errorf("(-want +got):\n%s", diff)
+	}
+}
+
+func TestTerminalClearEmptyTerminal(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	// Clear on empty terminal should be a no-op (no panic)
+	term.Clear()
+
+	if term.Buffer().YBase != 0 {
+		t.Errorf("YBase = %d, want 0", term.Buffer().YBase)
+	}
+}
+
+func TestTerminalClearFiresScrollEvent(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	scrollFired := false
+	term.OnScroll(func(int) { scrollFired = true })
+
+	term.Clear()
+
+	if !scrollFired {
+		t.Error("expected OnScroll to fire after Clear()")
+	}
+}
+
+func TestTerminalAddMarker(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 24)
+	term.WriteString("hello\r\nworld\r\n")
+
+	// Cursor is at row 2 (0-based), add marker at cursor position
+	marker := term.AddMarker(0)
+	if marker == nil {
+		t.Fatal("AddMarker returned nil")
+	}
+
+	expectedLine := term.Buffer().YBase + term.CursorY()
+	if marker.Line != expectedLine {
+		t.Errorf("marker.Line = %d, want %d", marker.Line, expectedLine)
+	}
+}
+
+func TestTerminalAddMarkerWithOffset(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 24)
+	term.WriteString("line1\r\nline2\r\nline3\r\n")
+
+	// Add marker 1 line above cursor
+	marker := term.AddMarker(-1)
+	if marker == nil {
+		t.Fatal("AddMarker returned nil")
+	}
+
+	expectedLine := term.Buffer().YBase + term.CursorY() - 1
+	if marker.Line != expectedLine {
+		t.Errorf("marker.Line = %d, want %d", marker.Line, expectedLine)
+	}
+}
+
+func TestTerminalScrollLinesFiresEvent(t *testing.T) {
+	t.Parallel()
+
+	term := newTestTerminal(80, 5)
+	fillScrollback(term, 20)
+
+	scrollEvents := 0
+	term.OnScroll(func(int) { scrollEvents++ })
+
+	term.ScrollLines(-3)
+
+	if scrollEvents != 1 {
+		t.Errorf("scroll events = %d, want 1", scrollEvents)
+	}
+}
+
+