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. The index resolves to its span at call time (#436) — both designation APIs converge on one stored representation.

pub fn set_active_search_match(&mut self, m: Option<Match>)

Designate the active match by its absolute span (#436), independent of the held highlight set — the past-cap path: a backend that caps its hand-over (the documented 1000, xterm’s highlightLimit) can still give the current match its active emphasis, exactly as xterm creates the active decoration from the found result outside the capped list. The span projects through the same viewport math as any match (wrap-aware); it need not be a member of the held set, so past the cap the match paints the ACTIVE colour only (no plain highlight underneath). None clears. Same lifecycle as the index form: reset on every set_search_highlights hand-over and on any coordinate-shifting invalidation.

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.