// Package vt wraps a headless virtual terminal emulator behind a small
// Go interface. The intent is that all cgo to libghostty-vt is confined
// to the GhosttyEmulator implementation in this package.
package vt

// Screen identifies which buffer is currently displayed.
type Screen uint8

const (
	ScreenPrimary Screen = iota
	ScreenAlternate
)

// CursorState is a snapshot of cursor position and visibility.
type CursorState struct {
	Col, Row uint16
	Visible  bool
}

// Emulator is the headless VT used by the daemon (and by the milestone-1 spike).
//
// Implementations are not required to be safe for concurrent use. The spike
// CLI funnels all calls through a single goroutine.
type Emulator interface {
	// Write feeds bytes from the PTY master into the emulator. It returns
	// the number of bytes consumed (always len(p) on success).
	Write(p []byte) (int, error)

	// Resize updates the emulator's cell grid. The caller is responsible
	// for issuing TIOCSWINSZ on the PTY itself.
	Resize(cols, rows uint16) error

	// PlainText returns the active screen rendered as plain text, with
	// soft-wrapped lines unwrapped and trailing whitespace trimmed.
	PlainText() (string, error)

	// ScreenText returns the active screen as fixed screen rows. Unlike
	// PlainText, this preserves row boundaries so a host UI can repaint
	// into a clipped viewport.
	ScreenText() (string, error)

	// SerializeVT returns the active screen as a VT byte sequence that, when
	// written to a fresh terminal, reproduces the visible state (colours,
	// styles, cursor, hyperlinks, etc.). Used as the daemon's "catch-up
	// frame" for newly-attached clients.
	SerializeVT() ([]byte, error)

	// StyledScreenVT returns the active screen's visible cell grid as VT
	// bytes with SGR styling and child-space cursor movement, but without
	// terminal modes, scroll regions, tabstops, or formatter cursor side
	// effects.
	StyledScreenVT() ([]byte, error)

	// Cursor returns cursor position and visibility on the active screen.
	Cursor() (CursorState, error)

	// ActiveScreen reports whether we are on the primary or alternate buffer.
	ActiveScreen() (Screen, error)

	// ScrollViewportTop moves the viewport to the top of the scrollback.
	ScrollViewportTop() error

	// ScrollViewportBottom moves the viewport back to the active area.
	ScrollViewportBottom() error

	// ScrollViewportDelta moves the viewport by `delta` rows (negative = up).
	ScrollViewportDelta(delta int) error

	// OnWritePTY registers a callback that fires when the emulator wants
	// to write bytes back to the PTY master (e.g. responses to DA / DSR
	// queries). The callback runs synchronously inside Write and must not
	// recurse into the emulator.
	OnWritePTY(fn func([]byte))

	// Close releases any underlying resources.
	Close() error
}