Documentation
¶
Overview ¶
Package vt implements the frontend-neutral terminal emulator core.
It tracks the visible cell grid, damage rectangles, scroll regions, alternate-screen state, cursor/reporting modes, and common xterm/VT control sequences. Wide runes that fit are stored as a head cell plus a continuation cell, and resize or edit operations repair row-boundary splits instead of leaving orphaned halves.
Stateful values are single-owner and are not internally synchronized. The owner must serialize Write, Resize, Snapshot, and History mutations. Write parses synchronously: every callback runs before Write returns and callbacks are delivered in the order their control sequences are encountered. A line eviction callback receives a stable row copy; response bytes should be consumed or copied during the callback. Other callback arguments are values or strings owned by the callback.
Snapshot and HistorySnapshotView capture owned state without sealing or mutating the live owner. Row methods return owned copies. BorrowedRow and HistoryView.Range expose immutable backing storage: callers must not mutate it, and Range callbacks must not retain their row after returning. A HistoryChunk pointer has stable identity for the lifetime of the view, so consumers can reuse unchanged sealed chunks. Direct Frame.Row access is a mutable borrow valid only until the frame scrolls or resizes.
Index ¶
- Constants
- Variables
- func MarshalEmptyHistoryTail() ([]byte, error)
- func MarshalHistory(view HistoryView) ([]byte, error)
- func MarshalHistoryChunk(chunk *HistoryChunk) ([]byte, error)
- func MarshalHistoryTail(view HistorySnapshotView) ([]byte, error)
- func MarshalSealedHistory(view HistoryView) ([][]byte, []byte, error)
- func RuneWidth(r rune) int
- type Cell
- type CursorSnapshot
- type Damage
- type DamageCapture
- type DamageKind
- type DecodeStats
- type Frame
- type Geometry
- type History
- func (h *History) Append(row []renderer.Cell, bound LineBound) error
- func (h *History) AppendWithID(row []renderer.Cell, bound LineBound, id RowID) error
- func (h *History) Cap() int
- func (h *History) CellCap() int
- func (h *History) Cells() int
- func (h *History) Len() int
- func (h *History) NextRowID() RowID
- func (h *History) SealAndView() HistoryView
- func (h *History) SnapshotView() HistorySnapshotView
- func (h *History) View() HistoryView
- type HistoryChunk
- type HistoryConfig
- type HistorySnapshotView
- type HistoryView
- func (v HistoryView) BorrowedRow(i int) []renderer.Cell
- func (v HistoryView) Bound(i int) LineBound
- func (v HistoryView) Cells() int
- func (v HistoryView) Chunk(i int) *HistoryChunk
- func (v HistoryView) ChunkCount() int
- func (v HistoryView) FindRowID(id RowID) int
- func (v HistoryView) Len() int
- func (v HistoryView) NextRowID() RowID
- func (v HistoryView) Range(yield func([]renderer.Cell) bool)
- func (v HistoryView) Row(i int) []renderer.Cell
- func (v HistoryView) RowID(i int) RowID
- type LineBound
- type ModeSnapshot
- type RGB
- type RecoveryTranscriptSnapshot
- type RowID
- type Screen
- func (s *Screen) AcknowledgeDamage(generation uint64) bool
- func (s *Screen) AltScreenActive() bool
- func (s *Screen) BracketedPasteMode() bool
- func (s *Screen) CaptureDamage() DamageCapture
- func (s *Screen) ClearColorScheme()
- func (s *Screen) ClearDamage()
- func (s *Screen) ColorSchemeMode() bool
- func (s *Screen) CursorCol() int
- func (s *Screen) CursorRow() int
- func (s *Screen) CursorStyle() (int, bool)
- func (s *Screen) CursorVisible() bool
- func (s *Screen) Damage() []renderer.Damage
- func (s *Screen) ForceSyncEnd()
- func (s *Screen) Geometry() Geometry
- func (s *Screen) GraphicsSnapshot() *graphics.Snapshot
- func (s *Screen) History() *History
- func (s *Screen) LineBounds() []LineBound
- func (s *Screen) MouseMode() (int, bool)
- func (s *Screen) RecoveryTranscriptSnapshot() RecoveryTranscriptSnapshot
- func (s *Screen) Resize(width, height int)
- func (s *Screen) RowID(y int) RowID
- func (s *Screen) RowIDs() []RowID
- func (s *Screen) SetColorScheme(light bool)
- func (s *Screen) SetDefaultColors(fg, bg renderer.RGB, ok bool)
- func (s *Screen) SetGeometry(geometry Geometry)
- func (s *Screen) Snapshot() ScreenSnapshot
- func (s *Screen) SyncUpdateActive() bool
- func (s *Screen) TerminalTitle() string
- func (s *Screen) Write(data []byte)
- type ScreenSnapshot
- func (s ScreenSnapshot) BorrowedRow(y int) []renderer.Cell
- func (s ScreenSnapshot) Bound(y int) LineBound
- func (s ScreenSnapshot) Columns() int
- func (s ScreenSnapshot) Cursor() CursorSnapshot
- func (s ScreenSnapshot) Graphics() *graphics.Snapshot
- func (s ScreenSnapshot) Modes() ModeSnapshot
- func (s ScreenSnapshot) NextRowID() RowID
- func (s ScreenSnapshot) Row(y int) []renderer.Cell
- func (s ScreenSnapshot) RowID(y int) RowID
- func (s ScreenSnapshot) RowIDs() []RowID
- func (s ScreenSnapshot) Rows() int
- func (s ScreenSnapshot) Title() string
- type Style
- type StyleAttrs
- type UnderlineStyle
Constants ¶
const ( AttrDim = core.AttrDim AttrUnderline = core.AttrUnderline AttrBlink = core.AttrBlink AttrStrikethrough = core.AttrStrikethrough UnderlineNone = core.UnderlineNone UnderlineSingle = core.UnderlineSingle UnderlineDouble = core.UnderlineDouble UnderlineCurly = core.UnderlineCurly UnderlineDotted = core.UnderlineDotted UnderlineDashed = core.UnderlineDashed DamageText = core.DamageText DamageClear = core.DamageClear DamageScrollUp = core.DamageScrollUp DamageFullRedraw = core.DamageFullRedraw )
const ( // ColorSchemeReportDark is the DEC 2031 dark-scheme report. ColorSchemeReportDark = "\x1b[?997;1n" // ColorSchemeReportLight is the DEC 2031 light-scheme report. ColorSchemeReportLight = "\x1b[?997;2n" )
Variables ¶
var ( BlankCell = core.BlankCell DefaultStyle = core.DefaultStyle FullRedraw = core.FullRedraw NewFrame = core.NewFrame )
var ErrHistoryRowTooWide = errors.New("history row exceeds cell capacity")
ErrHistoryRowTooWide is returned when a row cannot fit within the configured cell budget. The history is not modified when this error is returned.
Functions ¶
func MarshalEmptyHistoryTail ¶
MarshalEmptyHistoryTail returns the mandatory canonical empty tail blob.
func MarshalHistory ¶
func MarshalHistory(view HistoryView) ([]byte, error)
MarshalHistory encodes a HistoryView in a deterministic, self-contained format. It preserves chunk boundaries as well as every Cell and Style field.
func MarshalHistoryChunk ¶
func MarshalHistoryChunk(chunk *HistoryChunk) ([]byte, error)
MarshalHistoryChunk encodes one immutable chunk as a self-contained blob.
func MarshalHistoryTail ¶
func MarshalHistoryTail(view HistorySnapshotView) ([]byte, error)
MarshalHistoryTail encodes the copied mutable tail of a snapshot view as one canonical history blob. It does not seal or otherwise mutate live history.
func MarshalSealedHistory ¶
func MarshalSealedHistory(view HistoryView) ([][]byte, []byte, error)
MarshalSealedHistory serializes a SealAndView result as oldest-first, self-contained sealed blobs plus a mandatory empty tail blob. The empty tail carries NextRowID and is not the canonical default empty encoding.
Types ¶
type Cell ¶
The root package re-exports the frontend-neutral core model so screen, history, and renderer consumers share one cell/style/frame representation. The implementation and storage policy remain owned by the core package.
type CursorSnapshot ¶
CursorSnapshot is the cursor state captured with a visible screen snapshot.
type DamageCapture ¶
DamageCapture is an immutable copy of pending damage at one screen generation.
type DamageKind ¶
type DamageKind = core.DamageKind
type DecodeStats ¶
DecodeStats describes resources declared by one canonical VT blob.
func PreflightHistoryBlob ¶
func PreflightHistoryBlob(data []byte) (DecodeStats, error)
PreflightHistoryBlob validates one self-contained history blob without allocating decoded rows.
func (*DecodeStats) Add ¶
func (s *DecodeStats) Add(other DecodeStats) bool
Add adds another preflight result with overflow checking.
type Geometry ¶ added in v0.4.0
Geometry combines a terminal's required cell dimensions with optional pixel dimensions reported by its frontend. Zero pixel dimensions mean they are unknown and must not be inferred from the cell dimensions.
func (Geometry) PixelsKnown ¶ added in v0.4.0
PixelsKnown reports whether both pixel dimensions are available.
type History ¶
type History struct {
// contains filtered or unexported fields
}
History stores terminal rows in immutable chunks. It is intended to be mutated by the owner of a Screen; views are safe to retain after later appends.
func HistoryFromBlobs ¶
func HistoryFromBlobs(config HistoryConfig, sealed [][]byte, tail []byte) (*History, error)
HistoryFromBlobs restores history directly from sealed, oldest-first blobs and the mandatory tail blob. It never feeds decoded rows through Append.
func NewHistory ¶
func NewHistory(config HistoryConfig) *History
func (*History) Append ¶
Append records a copy of row along with its logical extent and an automatically allocated nonzero ID. Once a chunk is full it is sealed forever. Rows wider than the total cell capacity are rejected without mutation.
func (*History) AppendWithID ¶
AppendWithID records a copy of row with an explicit persisted identity. Unlike Append, malformed identities are rejected rather than synthesized.
func (*History) SealAndView ¶
func (h *History) SealAndView() HistoryView
SealAndView rotates the mutable tail into an immutable chunk, then captures the sealed chunks by identity. Callers must synchronize access to History.
func (*History) SnapshotView ¶
func (h *History) SnapshotView() HistorySnapshotView
SnapshotView captures history for persistence without sealing the mutable tail. Sealed chunks are shared by identity and the tail is deeply copied.
func (*History) View ¶
func (h *History) View() HistoryView
View captures the current history. Sealed chunks are shared by identity; a partially-filled tail is copied into a new immutable chunk for this view.
type HistoryChunk ¶
type HistoryChunk struct {
// contains filtered or unexported fields
}
HistoryChunk is an immutable group of history rows. Its identity is stable and can be used by consumers to avoid copying unchanged sealed chunks. bounds is parallel to rows and always has the same length.
func (*HistoryChunk) RowID ¶
func (c *HistoryChunk) RowID(i int) RowID
RowID returns the identity of the row within an immutable chunk.
type HistoryConfig ¶
HistoryConfig controls the bounded terminal history retained by a Screen.
type HistorySnapshotView ¶
type HistorySnapshotView struct {
// contains filtered or unexported fields
}
HistorySnapshotView captures sealed history chunks and the mutable tail independently. Sealed chunks are shared by identity; Tail is owned by the view and can be serialized without rotating the live tail into a chunk.
func (HistorySnapshotView) Cells ¶
func (v HistorySnapshotView) Cells() int
func (HistorySnapshotView) Chunk ¶
func (v HistorySnapshotView) Chunk(i int) *HistoryChunk
Chunk returns a sealed immutable chunk at i, or nil when i is out of range.
func (HistorySnapshotView) ChunkCount ¶
func (v HistorySnapshotView) ChunkCount() int
func (HistorySnapshotView) Len ¶
func (v HistorySnapshotView) Len() int
func (HistorySnapshotView) NextRowID ¶
func (v HistorySnapshotView) NextRowID() RowID
NextRowID returns the next identity recorded by this snapshot.
func (HistorySnapshotView) Tail ¶
func (v HistorySnapshotView) Tail() HistoryView
Tail returns an immutable view of the copied mutable tail.
type HistoryView ¶
type HistoryView struct {
// contains filtered or unexported fields
}
HistoryView is an immutable snapshot of history. Row returns a copy so the storage behind a sealed chunk remains owned by VT.
func UnmarshalHistory ¶
func UnmarshalHistory(data []byte) (HistoryView, error)
UnmarshalHistory strictly decodes a MarshalHistory payload. It rejects malformed declarations, cells, truncated data, and trailing bytes.
func (HistoryView) BorrowedRow ¶
func (v HistoryView) BorrowedRow(i int) []renderer.Cell
BorrowedRow returns immutable storage for the row at i, or nil when i is out of range. The caller must not mutate or retain the result after it no longer retains v. Consumers that need ownership should use Row instead.
func (HistoryView) Bound ¶
func (v HistoryView) Bound(i int) LineBound
Bound returns the logical extent of the row at i, or the zero value when i is out of range. A zero value describes a hard row whose End is not meaningful.
func (HistoryView) Cells ¶
func (v HistoryView) Cells() int
func (HistoryView) Chunk ¶
func (v HistoryView) Chunk(i int) *HistoryChunk
Chunk returns the immutable chunk at i, or nil when i is out of range.
func (HistoryView) ChunkCount ¶
func (v HistoryView) ChunkCount() int
func (HistoryView) FindRowID ¶
func (v HistoryView) FindRowID(id RowID) int
FindRowID returns the oldest-first index of id, or -1 when id is absent.
func (HistoryView) Len ¶
func (v HistoryView) Len() int
func (HistoryView) NextRowID ¶
func (v HistoryView) NextRowID() RowID
NextRowID returns the next identity recorded by this view.
func (HistoryView) Range ¶
func (v HistoryView) Range(yield func([]renderer.Cell) bool)
Range calls yield for each row in oldest-first order. The row is borrowed immutable storage: yield must not mutate or retain it after returning.
func (HistoryView) Row ¶
func (v HistoryView) Row(i int) []renderer.Cell
Row returns a copy of the row at i, or nil when i is out of range.
func (HistoryView) RowID ¶
func (v HistoryView) RowID(i int) RowID
RowID returns the identity of the row at i, or zero when i is out of range.
type LineBound ¶
LineBound describes a physical row's logical extent. End is exclusive: it is the count of meaningful cells, so the last significant column is End-1. It excludes padding introduced when a wide rune was moved off the right edge. Soft reports that the row continues into the following physical row.
type ModeSnapshot ¶
type ModeSnapshot struct {
AlternateScreen bool
BracketedPaste bool
SynchronizedUpdate bool
ColorSchemeMode bool
MouseTracking int
MouseSGR bool
}
ModeSnapshot is the renderer-relevant VT mode state captured with a screen.
type RecoveryTranscriptSnapshot ¶
type RecoveryTranscriptSnapshot struct {
// contains filtered or unexported fields
}
RecoveryTranscriptSnapshot is an owned, immutable capture of the viewport rows that should be replayed after retained terminal history during recovery.
func (RecoveryTranscriptSnapshot) Marshal ¶
func (snapshot RecoveryTranscriptSnapshot) Marshal() ([]byte, error)
Marshal encodes the captured rows as canonical terminal history without consulting or mutating live Screen history.
type RowID ¶
type RowID uint64
RowID identifies one physical terminal row for the lifetime of a Screen. Row IDs are never zero and are never reused by their owning Screen.
type Screen ¶
type Screen struct {
Frame renderer.Frame
Row int
Col int
Style renderer.Style
// OnLineEvicted is called just before a full-width upward scroll recycles
// and blanks rows. The callback receives a stable copy of each evicted row.
OnLineEvicted func([]renderer.Cell)
// OnResponse is called synchronously from Write with reply bytes that the
// emulator must send back to the child process (DA, DSR, and ANSI/DEC mode
// query reports). The host wires it to the PTY input. Nil disables responses.
OnResponse func([]byte)
// OnBell is called synchronously from Write for each lone BEL (0x07)
// outside escape sequences. BELs that terminate an OSC never fire it.
// Nil disables bell reporting.
OnBell func()
// OnNotify is called synchronously from Write for explicit terminal
// notifications: OSC 9 (body only) and OSC 777 "notify" (title;body).
// Other non-clipboard OSC payloads remain discarded. Nil disables it.
OnNotify func(title, body string)
// OnProgress is called synchronously from Write for OSC 9;4 progress
// transitions that request attention: active progress cleared or first entry
// into error state. Nil disables progress reporting.
OnProgress func(errored bool)
// OnClipboard is called synchronously from Write for a complete OSC 52
// clipboard set request from the child. The OSC 52 selection field is
// accepted but ignored; the callback receives only the raw base64 payload.
// Clipboard queries (data == "?") and malformed payloads are ignored and
// never invoke it. Nil disables it.
OnClipboard func(b64 string)
// contains filtered or unexported fields
}
func NewScreenWithHistory ¶
func NewScreenWithHistory(width, height int, config HistoryConfig) *Screen
NewScreenWithHistory creates a screen that records rows evicted from its primary screen into bounded immutable terminal history.
func NewScreenWithRecoveryTranscript ¶
func NewScreenWithRecoveryTranscript(width, height int, config HistoryConfig, sealed [][]byte, tail, transcript []byte) (*Screen, error)
NewScreenWithRecoveryTranscript constructs a fresh blank screen whose history contains the restored bounded history followed by the recovery transcript. The transcript is decoded in full before history is restored.
func (*Screen) AcknowledgeDamage ¶
AcknowledgeDamage consumes a capture only if no screen mutation occurred since it was taken. A stale acknowledgement conservatively requests a full redraw, ensuring intervening writes remain visible to the next capture.
func (*Screen) AltScreenActive ¶
func (*Screen) BracketedPasteMode ¶
BracketedPasteMode reports whether DEC private mode 2004 is currently enabled by the child process.
func (*Screen) CaptureDamage ¶
func (s *Screen) CaptureDamage() DamageCapture
CaptureDamage snapshots pending damage without consuming it.
func (*Screen) ClearColorScheme ¶
func (s *Screen) ClearColorScheme()
ClearColorScheme marks the host color scheme as unknown. Future child color scheme queries are silent until SetColorScheme supplies a known value again.
func (*Screen) ClearDamage ¶
func (s *Screen) ClearDamage()
func (*Screen) ColorSchemeMode ¶
ColorSchemeMode reports whether DEC private mode 2031 is currently enabled.
func (*Screen) CursorStyle ¶
func (*Screen) CursorVisible ¶
func (*Screen) Damage ¶
Damage returns the current damage list. The caller must not modify the returned slice; ClearDamage must be called after the damage is consumed.
func (*Screen) ForceSyncEnd ¶
func (s *Screen) ForceSyncEnd()
ForceSyncEnd forcibly leaves DEC private mode 2026 (synchronized update). Hosts use this as a safety valve if a child enters synchronized update mode and never sends the matching end sequence.
func (*Screen) Geometry ¶ added in v0.4.0
Geometry returns the screen's last frontend-supplied geometry.
func (*Screen) GraphicsSnapshot ¶ added in v0.4.0
GraphicsSnapshot returns an immutable snapshot of the active screen buffer's graphics scene, or nil before graphics has been used. The returned reference remains valid after subsequent Screen mutations.
func (*Screen) History ¶
History returns this screen's terminal history, or nil when history was not configured with NewScreenWithHistory.
func (*Screen) LineBounds ¶
LineBounds returns an owned copy of the live grid's per-row logical extents, indexed like Frame rows. It returns nil when the screen has no buffer.
func (*Screen) RecoveryTranscriptSnapshot ¶
func (s *Screen) RecoveryTranscriptSnapshot() RecoveryTranscriptSnapshot
RecoveryTranscriptSnapshot captures the active primary viewport, or the saved primary viewport followed by the active alternate viewport.
func (*Screen) RowID ¶
RowID returns the identity of active live row y, or zero when y is out of range.
func (*Screen) SetColorScheme ¶
SetColorScheme updates the host color scheme and notifies subscribed child apps.
func (*Screen) SetDefaultColors ¶
SetDefaultColors sets the terminal default foreground/background colors used to answer child OSC 10/11 color queries. Passing ok=false makes color queries silent until known colors are supplied again.
func (*Screen) SetGeometry ¶ added in v0.4.0
SetGeometry updates the frontend-supplied cell and optional pixel geometry. Cell changes retain the existing Resize behavior; pixel-only changes do not touch the text frame or damage state.
func (*Screen) Snapshot ¶
func (s *Screen) Snapshot() ScreenSnapshot
Snapshot captures the active visible viewport without mutating Screen, history, or pending damage. Screen remains single-owner; callers must serialize Snapshot with Write, Resize, and host mutations.
func (*Screen) SyncUpdateActive ¶
SyncUpdateActive reports whether DEC private mode 2026 (synchronized update) is currently enabled by the child process.
func (*Screen) TerminalTitle ¶
TerminalTitle returns the latest title set by OSC 0 or OSC 2.
type ScreenSnapshot ¶
type ScreenSnapshot struct {
// contains filtered or unexported fields
}
ScreenSnapshot is an owned immutable-by-convention capture of the active terminal viewport. Row returns caller-owned storage; BorrowedRow must not be mutated and remains valid while the snapshot is retained.
func (ScreenSnapshot) BorrowedRow ¶
func (s ScreenSnapshot) BorrowedRow(y int) []renderer.Cell
func (ScreenSnapshot) Bound ¶
func (s ScreenSnapshot) Bound(y int) LineBound
func (ScreenSnapshot) Columns ¶
func (s ScreenSnapshot) Columns() int
func (ScreenSnapshot) Cursor ¶
func (s ScreenSnapshot) Cursor() CursorSnapshot
func (ScreenSnapshot) Graphics ¶ added in v0.4.0
func (s ScreenSnapshot) Graphics() *graphics.Snapshot
Graphics returns the immutable graphics scene snapshot for the active screen buffer, or nil when that buffer has not used Kitty graphics.
func (ScreenSnapshot) Modes ¶
func (s ScreenSnapshot) Modes() ModeSnapshot
func (ScreenSnapshot) NextRowID ¶
func (s ScreenSnapshot) NextRowID() RowID
NextRowID returns the next identity allocated by the captured screen.
func (ScreenSnapshot) RowID ¶
func (s ScreenSnapshot) RowID(y int) RowID
RowID returns the identity of visible row y, or zero when out of range.
func (ScreenSnapshot) RowIDs ¶
func (s ScreenSnapshot) RowIDs() []RowID
RowIDs returns an owned copy of the visible physical-row identities.
func (ScreenSnapshot) Rows ¶
func (s ScreenSnapshot) Rows() int
func (ScreenSnapshot) Title ¶
func (s ScreenSnapshot) Title() string
type StyleAttrs ¶
type StyleAttrs = core.StyleAttrs
type UnderlineStyle ¶
type UnderlineStyle = core.UnderlineStyle
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ansi emits ANSI terminal output from the frontend-neutral github.com/bnema/vev-vt/core model.
|
Package ansi emits ANSI terminal output from the frontend-neutral github.com/bnema/vev-vt/core model. |
|
cmd
|
|
|
graphics-harness
command
Command graphics-harness renders Kitty graphics terminal input to a PNG for local development inspection.
|
Command graphics-harness renders Kitty graphics terminal input to a PNG for local development inspection. |
|
Package vtcore defines the frontend-neutral terminal model shared by the VT emulator and concrete ANSI renderers.
|
Package vtcore defines the frontend-neutral terminal model shared by the VT emulator and concrete ANSI renderers. |
|
Package graphics provides a renderer-neutral, bounded graphics scene.
|
Package graphics provides a renderer-neutral, bounded graphics scene. |
|
internal
|
|
|
graphicsharness
Package graphicsharness provides a headless reference compositor for inspecting graphics snapshots during development.
|
Package graphicsharness provides a headless reference compositor for inspecting graphics snapshots during development. |
|
protocol
|
|
|
kittygraphics
Package kittygraphics implements the bounded Kitty graphics protocol adapter.
|
Package kittygraphics implements the bounded Kitty graphics protocol adapter. |
|
terminalquery
Package terminalquery provides bounded parsers for terminal capability probes.
|
Package terminalquery provides bounded parsers for terminal capability probes. |