feat: add RegisterCsiHandler, RegisterEscHandler, RegisterDcsHandler, RegisterOscHandler to Terminal

Expose the four missing custom handler registration methods on Terminal,
forwarding to the underlying parser. The parser already supported all
four; only the Terminal-level public API was missing.

Fixes #20

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

Author: ona-automations

terminal.go

@@ -226,6 +226,28 @@ func (t *Terminal) RegisterApcHandler(ident int, handler func(data string) bool)
 	return t.inputHandler.parser.RegisterApcHandler(ident, NewApcStringHandler(handler))
 }
 
+// RegisterCsiHandler registers a custom handler for a CSI escape sequence.
+// The handler returns true to stop the handler chain from bubbling further.
+func (t *Terminal) RegisterCsiHandler(id FunctionIdentifier, handler CsiHandler) Disposable {
+	return t.inputHandler.parser.RegisterCsiHandler(id, handler)
+}
+
+// RegisterEscHandler registers a custom handler for an ESC escape sequence.
+// The handler returns true to stop the handler chain from bubbling further.
+func (t *Terminal) RegisterEscHandler(id FunctionIdentifier, handler EscHandler) Disposable {
+	return t.inputHandler.parser.RegisterEscHandler(id, handler)
+}
+
+// RegisterDcsHandler registers a custom handler for a DCS escape sequence.
+func (t *Terminal) RegisterDcsHandler(id FunctionIdentifier, handler DcsHandler) Disposable {
+	return t.inputHandler.parser.RegisterDcsHandler(id, handler)
+}
+
+// RegisterOscHandler registers a custom handler for an OSC escape sequence.
+func (t *Terminal) RegisterOscHandler(ident int, handler OscHandler) Disposable {
+	return t.inputHandler.parser.RegisterOscHandler(ident, handler)
+}
+
 // NormalBuffer returns the normal (primary) buffer.
 func (t *Terminal) NormalBuffer() *Buffer { return t.bufferService.Buffers.Normal() }
 

terminal_test.go

@@ -735,3 +735,111 @@ func TestTerminalTabStops(t *testing.T) {
 		t.Errorf("CursorX() = %d, want 9 (after tab + B)", term.CursorX())
 	}
 }
+
+func TestTerminalRegisterCsiHandler(t *testing.T) {
+	t.Parallel()
+	term := newTestTerminal(80, 24)
+
+	var called bool
+	var gotParams []int32
+	d := term.RegisterCsiHandler(FunctionIdentifier{Final: 'Z'}, func(params *Params) bool {
+		called = true
+		gotParams = make([]int32, params.Length)
+		copy(gotParams, params.Params[:params.Length])
+		return true
+	})
+
+	// Send CSI 1;2 Z
+	term.WriteString("\x1b[1;2Z")
+	if !called {
+		t.Fatal("CSI handler was not called")
+	}
+	if len(gotParams) < 2 || gotParams[0] != 1 || gotParams[1] != 2 {
+		t.Fatalf("got params %v, want [1 2]", gotParams)
+	}
+
+	// Dispose and verify handler no longer fires.
+	called = false
+	d.Dispose()
+	term.WriteString("\x1b[1;2Z")
+	if called {
+		t.Fatal("CSI handler was called after Dispose")
+	}
+}
+
+func TestTerminalRegisterEscHandler(t *testing.T) {
+	t.Parallel()
+	term := newTestTerminal(80, 24)
+
+	var called bool
+	d := term.RegisterEscHandler(FunctionIdentifier{Intermediates: "#", Final: '9'}, func() bool {
+		called = true
+		return true
+	})
+
+	// Send ESC # 9
+	term.WriteString("\x1b#9")
+	if !called {
+		t.Fatal("ESC handler was not called")
+	}
+
+	// Dispose and verify handler no longer fires.
+	called = false
+	d.Dispose()
+	term.WriteString("\x1b#9")
+	if called {
+		t.Fatal("ESC handler was called after Dispose")
+	}
+}
+
+func TestTerminalRegisterDcsHandler(t *testing.T) {
+	t.Parallel()
+	term := newTestTerminal(80, 24)
+
+	var gotData string
+	d := term.RegisterDcsHandler(FunctionIdentifier{Final: 'z'}, NewDcsStringHandler(func(data string, params *Params) bool {
+		gotData = data
+		return true
+	}))
+
+	// Send DCS z <payload> ST (DCS = ESC P, ST = ESC \)
+	term.WriteString("\x1bPz" + "hello" + "\x1b\\")
+	if gotData != "hello" {
+		t.Fatalf("DCS handler got data %q, want %q", gotData, "hello")
+	}
+
+	// Dispose and verify handler no longer fires.
+	gotData = ""
+	d.Dispose()
+	term.WriteString("\x1bPz" + "world" + "\x1b\\")
+	if gotData != "" {
+		t.Fatalf("DCS handler got data %q after Dispose, want empty", gotData)
+	}
+}
+
+func TestTerminalRegisterOscHandler(t *testing.T) {
+	t.Parallel()
+	term := newTestTerminal(80, 24)
+
+	var gotData string
+	// Use a high OSC number unlikely to conflict with built-in handlers.
+	d := term.RegisterOscHandler(9999, NewOscStringHandler(func(data string) bool {
+		gotData = data
+		return true
+	}))
+
+	// Send OSC 9999 ; payload BEL
+	term.WriteString("\x1b]9999;test-payload\x07")
+	if gotData != "test-payload" {
+		t.Fatalf("OSC handler got data %q, want %q", gotData, "test-payload")
+	}
+
+	// Dispose and verify handler no longer fires.
+	gotData = ""
+	d.Dispose()
+	term.WriteString("\x1b]9999;after-dispose\x07")
+	if gotData != "" {
+		t.Fatalf("OSC handler got data %q after Dispose, want empty", gotData)
+	}
+}
+