grindlemire/go-tui code browser

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

package tui

// ColorCapability describes the level of color support in a terminal.
type ColorCapability int

const (
	// ColorNone indicates a monochrome terminal with no color support.
	ColorNone ColorCapability = iota
	// Color16 indicates basic 16-color support (ANSI standard colors).
	Color16
	// Color256 indicates ANSI 256 palette support.
	Color256
	// ColorTrue indicates 24-bit true color (RGB) support.
	ColorTrue
)

// Capabilities describes what features the terminal supports.
type Capabilities struct {
	// Colors indicates the level of color support.
	Colors ColorCapability
	// Unicode indicates whether the terminal can render Unicode characters.
	Unicode bool
	// TrueColor indicates whether 24-bit RGB colors are supported.
	TrueColor bool
	// AltScreen indicates whether the terminal supports alternate screen buffer.
	AltScreen bool
	// KittyKeyboard indicates the Kitty keyboard protocol was successfully negotiated.
	KittyKeyboard bool
	// Hyperlinks indicates the terminal supports OSC 8 hyperlinks.
	Hyperlinks bool
}

// Terminal abstracts terminal operations for rendering and input.
// Implementations handle ANSI, Windows Console, or mock terminals for testing.
type Terminal interface {
	// Size returns the terminal dimensions (width, height) in cells.
	Size() (width, height int)

	// Flush writes the given cell changes to the terminal.
	// Changes are expected to be in row-major order for optimal performance.
	Flush(changes []CellChange)

	// Clear clears the entire terminal screen.
	Clear()

	// ClearToEnd clears from the cursor position to the end of the screen.
	ClearToEnd()

	// SetCursor moves the cursor to the specified position (0-indexed).
	SetCursor(x, y int)

	// HideCursor makes the cursor invisible.
	HideCursor()

	// ShowCursor makes the cursor visible.
	ShowCursor()

	// EnterRawMode puts the terminal into raw mode for character-by-character input.
	// Returns an error if raw mode cannot be enabled.
	EnterRawMode() error

	// ExitRawMode restores the terminal to its previous mode.
	// Returns an error if the previous mode cannot be restored.
	ExitRawMode() error

	// EnterAltScreen switches to the alternate screen buffer.
	// This preserves the original terminal content.
	EnterAltScreen()

	// ExitAltScreen switches back to the main screen buffer.
	// This restores the original terminal content.
	ExitAltScreen()

	// EnableMouse enables mouse event reporting.
	// After calling this, mouse clicks will be reported as events.
	EnableMouse()

	// DisableMouse disables mouse event reporting.
	// Call this before exiting to restore normal terminal behavior.
	DisableMouse()

	// EnableAltScroll enables alternate-scroll mode so the mouse wheel scrolls
	// via cursor keys while on the alternate screen with mouse reporting off.
	// This keeps native text selection and link clicking working.
	EnableAltScroll()

	// DisableAltScroll disables alternate-scroll mode.
	DisableAltScroll()

	// NegotiateKittyKeyboard attempts to enable the Kitty keyboard protocol
	// using push/pop stack semantics. Each implementation uses its own stored
	// input fd to read the terminal's response. Returns true if the protocol
	// was successfully negotiated.
	NegotiateKittyKeyboard() bool

	// EnableKittyKeyboard pushes Kitty keyboard protocol mode onto the
	// terminal's stack without querying. Use this on resume when the terminal
	// is already known to support the protocol (avoids stdin query/response
	// races after SIGCONT).
	EnableKittyKeyboard()

	// DisableKittyKeyboard pops the Kitty keyboard protocol mode from the
	// terminal's stack, restoring the previous mode. No-op if Kitty mode
	// was not negotiated.
	DisableKittyKeyboard()

	// ResetStyle invalidates cached style state, forcing the next Flush to
	// emit style codes unconditionally. Call this after terminal state may
	// have been disrupted (e.g., suspend/resume).
	ResetStyle()

	// Caps returns the terminal's capabilities.
	Caps() Capabilities

	// WriteDirect writes raw bytes directly to the terminal.
	// Use this for escape sequences that are not covered by other methods.
	WriteDirect([]byte) (int, error)
}