Struct Term 

pub struct Term { /* private fields */ }

Owns the authoritative screen state and applies VT actions to it.

Implementations

impl Term

pub fn new(cols: usize, rows: usize) -> Self

pub fn with_scrollback( cols: usize, rows: usize, scrollback_limit: usize, ) -> Self

pub fn damage(&self) -> TermDamage

What changed since the last reset_damage() — line ranges, each with a changed column span. See ADR-0003.

pub fn reset_damage(&mut self)

Clear accumulated damage. The consumer calls this after applying a frame (the ack); the next damage() reflects only changes since.

pub fn mark_fully_damaged(&mut self)

Mark the whole screen damaged (alt switch / clear / flood, and a consumer reattach that needs a full re-sync — see crate::Engine::mark_fully_damaged).

pub fn scroll_delta(&self) -> Option<ScrollOp>

The first-class scroll recorded since the last reset_damage, if any. Suppressed while scrolled up — a content scroll must not shift the frozen viewport.

pub fn frame(&self) -> Frame

Build a serializable Frame from the current damage + grid + grapheme pool (#6). Full ships every row; Partial ships the damaged spans. The global side-table is remapped to frame-local indices — the engine pool is append-only and leaky, so a frame carries only the clusters its cells reference, renumbered, with each cell’s extra rewritten to the local id.

pub fn scrollback_len(&self) -> usize

Number of lines currently held in scrollback history.

pub fn synchronized_output(&self) -> bool

Whether the app has an open synchronized-output block (DEC ?2026, #73).

pub fn color_scheme_updates(&self) -> bool

Whether the app enabled color-scheme-update notifications (DEC ?2031, #85).

pub fn grapheme_clustering(&self) -> bool

Whether the app enabled grapheme-cluster mode (DEC ?2027, #295): emoji ZWJ / skin-tone / flag / VS16 sequences are clustered into one cell. OFF (default) is per-char, wcwidth-compat.

pub fn win32_input_mode(&self) -> bool

Whether the app enabled win32-input-mode (DEC ?9001, #86). The engine does not encode the raw key-records itself (a non-goal); a ConPTY consumer reads this to decide whether to emit them.

pub fn report_color_scheme(&mut self, dark: bool)

Queue a color-scheme report (CSI ? 997 ; 1 n dark / ; 2 n light) on the reply channel. The consumer calls this to answer a ColorSchemeQuery event or, when its scheme changes and color_scheme_updates() is set, to send the unsolicited notification. The engine never stores or interprets the scheme (#85).

pub fn report_palette_color(&mut self, index: u8, spec: &str)

Answer an OSC 4 palette query (#122): wrap the consumer-supplied spec for index in the OSC 4 reply envelope, ST-terminated.

pub fn report_foreground(&mut self, spec: &str)

Answer an OSC 10 foreground query (#122): wrap the consumer-supplied spec in the OSC 10 reply envelope, ST-terminated.

pub fn report_background(&mut self, spec: &str)

Answer an OSC 11 background query (#122): wrap the consumer-supplied spec (it knows its palette) in the OSC 11 reply envelope, ST-terminated. The engine formats the envelope only — it never knows the colour.

pub fn viewport_line(&self, i: usize) -> &[Cell]

The cells of visible row i (0..rows) at the current scroll position. The viewport windows into [history.. ; screen..]: rows above scrollback.len() come from history, the rest from the live screen.

pub fn scroll_up(&mut self, n: usize)

Scroll the viewport up by n lines into history (clamped to the oldest).

pub fn scroll_down(&mut self, n: usize)

Scroll the viewport down by n lines toward the live screen.

pub fn scroll_to_bottom(&mut self)

Jump the viewport back to the live screen (follow the bottom).

pub fn viewport_logical_lines(&self) -> Vec<LogicalLine>

The viewport’s logical lines (#113/ADR-0017): each line’s text plus a per-char map to its viewport (row, col). Wide-char spacers are skipped and trailing blanks trimmed (so the text is 1:1 with cells). Empty rows are dropped. The cell-aware assembly the consumer can’t do in frame mode.

pub fn search(&self, query: &str) -> Vec<Match>

Literal search over the whole buffer ([scrollback ++ screen]), returning every non-overlapping match top-to-bottom in absolute coordinates. Matches cross soft-wrapped rows (one logical line) and skip wide-char spacers. Smart-case: a query with no uppercase matches case-insensitively.

pub fn search_with(&self, query: &str, opts: SearchOptions) -> Vec<Match>

Search with explicit SearchOptions — regex, whole-word, and a case-sensitivity override on top of the literal + smart-case search (#314). Same coordinates, soft-wrap join, spacer skip, and grapheme-mark inclusion (#304) as search.

pub fn search_scroll_to(&mut self, m: &Match)

Scroll the viewport so a match’s start line is visible (placed at the top when it sits in history; the live view when it is already on screen).

pub fn match_spans(&self, m: &Match) -> Vec<SelectionSpan>

Project a match onto the current viewport as inclusive-column spans, one per visible row (off-screen parts dropped) — for the renderer to highlight, like selection_range.

pub fn set_search_highlights(&mut self, matches: Vec<Match>)

Set the search highlights to paint (#108). The consumer owns the Vec<Match> (it drives next/prev); handing it back here lets frame() project the highlights onto the viewport. An empty vec clears them.

pub fn set_active_search_highlight(&mut self, index: Option<usize>)

Designate which member of the held highlight set is the active match (#428) — the one the consumer’s next/prev navigation currently points at. frame() projects it into overlay.active_match (it also stays in overlay.matches; the renderer’s ranking resolves the overlap, #424). None or an out-of-range index projects nothing; the designation resets whenever a new set is passed to set_search_highlights.

pub fn add_marker(&mut self, row: usize) -> MarkerId

pub fn command_marks(&self) -> Vec<(MarkerId, usize, MarkerKind)>

The OSC 133 command-boundary marks in buffer order — (id, absolute line, kind) (#158). Plain decoration markers (#118) are excluded. The consumer pairs prompt/command/finished marks and drives navigation/announce policy (#160); core only parses and anchors them.

pub fn command_lines(&self) -> Vec<CommandLine>

The executed shell commands recovered from OSC-133 marks, in buffer order (#166) — the data behind screen-reader command navigation. Each CommandLine pairs a CommandStart(B) with the following OutputStart(C) to extract the typed command (the prompt before B and the output after C excluded via the captured columns, VSCode extractCommandLine parity), and attaches the trailing CommandFinished(D) exit. A command still being typed (B with no C yet) is not navigable — its text has no bound — so it is omitted until output starts.

pub fn remove_marker(&mut self, id: MarkerId)

Remove a marker by id (#118). Disposing it fires MarkerDisposed so the consumer’s cleanup is one path whether the marker left by eviction or by this explicit call (xterm’s dispose() likewise always fires onDispose). A no-op for an unknown/already-disposed id.

pub fn selection_begin( &mut self, row: usize, col: usize, side: Side, ty: SelectionType, )

Begin a selection of ty at viewport (row, col), side.

pub fn selection_extend(&mut self, row: usize, col: usize, side: Side)

Extend the live selection’s focus to viewport (row, col), side.

pub fn selection_clear(&mut self)

Clear the selection.

pub fn selection_range(&self) -> Vec<SelectionSpan>

The selection projected onto the current viewport: one inclusive-column span per visible row. Rows scrolled off-screen (above or below) are dropped. Empty when nothing is selected. See SelectionSpan.

pub fn selection_text(&self) -> Option<String>

The selected text (for copy), or None when nothing is selected.

pub fn accessible_text(&self) -> String

The whole buffer as one text document (#150): scrollback + screen assembled into logical lines (soft-wrap joined, wide-spacers skipped, trailing blanks trimmed at the logical end) — the accessible-view a screen reader reads as a document, distinct from the viewport row tree (#119). Reuses the selection extraction (extract_lines) over the full range. On the alt screen only the alt buffer is shown — its “scrollback” is the primary buffer’s, not this app’s — mirroring viewport_logical_lines’ alt floor.

pub fn resize(&mut self, cols: usize, rows: usize)

Resize the screen to cols x rows. Rows dropped off the top (on shrink) enter scrollback. Column reflow of soft-wrapped lines is layered on top separately (#7). The whole screen is damaged.

pub fn grid(&self) -> &Grid

pub fn cursor(&self) -> &Cursor

pub fn bracketed_paste(&self) -> bool

Whether bracketed-paste mode (DEC ?2004) is enabled. The input encoder (#11) reads this to decide whether to wrap pasted text in markers.

pub fn encode_key(&self, ev: KeyEvent) -> Option<Vec<u8>>

Encode a key event to bytes using the active cursor-key mode (DECCKM) and the kitty keyboard-protocol flags (encode_key consults both).

pub fn encode_mouse(&self, ev: MouseEvent) -> Option<Vec<u8>>

Encode a mouse event using the active tracking mode + encoding. None when reporting is off or the event is filtered by the mode.

pub fn encode_paste(&self, text: &str) -> Vec<u8>

Encode pasted text, wrapping it in bracketed-paste markers when ?2004 is on.

pub fn encode_focus(&self, focused: bool) -> Option<Vec<u8>>

Encode a focus change (CSI I/CSI O), or None when focus reporting (?1004) is off.

pub fn drain_events(&mut self) -> Vec<TermEvent>

Take the consumer events queued since the last drain, emptying the queue.

pub fn drain_replies(&mut self) -> Vec<u8>

Take the reply bytes queued since the last drain (DA/DSR/DECRQM answers), emptying the buffer. The consumer writes them back to the PTY.

pub fn hyperlink(&self, link: NonZeroU32) -> Option<&str>

Resolve a cell’s link index (OSC 8) to its URI, or None if the index is out of range. The renderer reads Cell.link, then this, to make a cell clickable (#26).

Trait Implementations

impl Perform for Term

fn osc_dispatch(&mut self, params: &[&[u8]], _bell_terminated: bool)

OSC dispatch (#12 event surface): title (0/2), cwd (7). OSC 8 hyperlink is per-cell state, handled in its own slice (#26), not here.

fn print(&mut self, c: char)

Draw a character to the screen and update states.

fn execute(&mut self, byte: u8)

Execute a C0 or C1 control function.

fn csi_dispatch( &mut self, params: &Params, intermediates: &[u8], _ignore: bool, action: char, )

A final character has arrived for a CSI sequence

fn esc_dispatch(&mut self, intermediates: &[u8], _ignore: bool, byte: u8)

The final character of an escape sequence has arrived.

fn hook( &mut self, _params: &Params, _intermediates: &[u8], _ignore: bool, _action: char, )

Invoked when a final character arrives in first part of device control string.

fn put(&mut self, _byte: u8)

Pass bytes as part of a device control string to the handle chosen in hook. C0 controls will also be passed to the handler.

fn unhook(&mut self)

Called when a device control string is terminated.

fn terminated(&self) -> bool

Whether the parser should terminate prematurely.