Documentation
¶
Overview ¶
Package term manages the terminal's lifecycle around an interactive session: raw mode, the private modes the session needs (bracketed paste, focus reporting, the kitty keyboard enhancement), the terminal size, and a portable resize watcher. It is deliberately thin: everything stateful about rendering lives in the painter, everything about bytes-to-events in the decoder; this package only negotiates terminal state and guarantees it is restored, in reverse order, however the session ends.
Resize is watched by polling the size through the injected clock rather than a signal: SIGWINCH does not exist on Windows, and the Windows console is a first-class target, so one mechanism serves every platform and stays deterministic under a manual clock in tests.
Index ¶
- Constants
- func EditorCommand() []string
- func MakeRaw(fd int) (restore func() error, err error)
- func RunAttached(argv []string) error
- func Setup(w io.Writer, o Options) error
- func Size(fd int) (width, height int, err error)
- func Teardown(w io.Writer, o Options) error
- type Clipboard
- type Options
- type Watcher
Constants ¶
const ImagePNG = "image/png"
ImagePNG is the media type every image the clipboard port yields carries: golang.design/x/clipboard normalizes clipboard bitmaps to PNG on read.
Variables ¶
This section is empty.
Functions ¶
func EditorCommand ¶
func EditorCommand() []string
EditorCommand returns the user's editor as an argument vector: VISUAL, then EDITOR (either may carry arguments, split on whitespace), then a platform default that is present on a stock system.
func MakeRaw ¶
MakeRaw puts the terminal identified by fd into raw mode and returns the restore function. The caller defers restore so a panic or an early return can never leave the user's shell in raw mode.
func RunAttached ¶
RunAttached runs one command attached to this process's own standard streams and blocks until it exits: the editor handoff, where the user's configured editor takes over the terminal. The caller owns the terminal state around the call: hand the terminal back (cooked mode, shell modes off, input reader parked) before calling, and reclaim it after. The child inherits the full environment, because it is the user's own program on the user's own terminal at their explicit request, not an agent action; that is also why it may spawn directly instead of through the sandbox.
func Setup ¶
Setup writes the enable sequences for every selected mode. It returns the first write error; a partial setup is torn down by Teardown, which disables unconditionally.
Types ¶
type Clipboard ¶
type Clipboard interface {
// Image returns a PNG-encoded image on the clipboard and ok=true, or
// ok=false when the clipboard holds no image or is unavailable on this
// host or session. The returned bytes are always image/png.
Image() (data []byte, ok bool)
}
Clipboard reads image content from the OS clipboard. It is the port behind Ctrl+V image paste: reading the user's clipboard happens only at their explicit keystroke, never on the agent's initiative, so it lives here beside the $EDITOR handoff rather than anywhere an engine can reach. The interface keeps the composer testable with a fake and lets a host that has no clipboard (a pipe, a headless CI run) degrade cleanly instead of failing.
func NewClipboard ¶
func NewClipboard() Clipboard
NewClipboard returns the OS clipboard port. It does not touch the clipboard or probe availability until the first read, so constructing it is free and safe on a host that has no display.
type Options ¶
type Options struct {
// BracketedPaste makes a paste arrive as one delimited unit instead of a
// burst of keystrokes.
BracketedPaste bool
// FocusEvents reports the terminal gaining and losing focus.
FocusEvents bool
// KittyKeyboard pushes the keyboard-enhancement flags that disambiguate
// keys the legacy encoding conflates (Escape, modified Enter and Tab).
// Terminals without the protocol ignore the push and the pop.
KittyKeyboard bool
// HideCursor hides the terminal's own cursor for the session. The
// painter rests the hardware cursor at the start of the last live row,
// not at the edit point, so the session draws a software cursor and the
// hardware one stays out of sight until teardown restores it.
HideCursor bool
// AltScreen switches the session to the terminal's alternate screen buffer
// for its lifetime, restoring the primary screen (and its scrollback) on
// teardown. It pairs with the alternate-screen renderer for emulators where
// inline scroll-region insertion is unsafe.
AltScreen bool
}
Options selects the terminal modes a session runs with. The zero value enables nothing; the session's defaults are chosen by the caller so this package stays policy-free.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher polls the terminal size and reports changes. Stop it before restoring the terminal.
func WatchResize ¶
func WatchResize(timing clock.Timing, interval time.Duration, size func() (int, int, error), onResize func(w, h int)) *Watcher
WatchResize starts polling size (any function returning the current dimensions, typically a closure over Size) every interval, invoking onResize with each new width and height. The first call happens only on the first change: the caller already sized its first frame. Errors from size are skipped for that tick; a transiently unreadable terminal (a detached ConPTY during a window drag) is not a reason to tear anything down.
Source Files