Struct SharedTerm 

pub struct SharedTerm { /* private fields */ }

Shared handle to the alacritty Term owned by a spawned terminal. The reader task locks the Mutex to advance bytes from the PTY; the host’s dispatch path locks it to invoke scroll / resize / future-T2.c operations. Contention is minimal — the reader only holds the lock during chunk processing (microseconds per call) and dispatch operations are user-driven (one per keystroke).

The snapshot Arc + paint_request notifier match the ones the reader publishes to so dispatch-side state changes (e.g. scrolling into history) republish a fresh snapshot without waiting for the next PTY byte.

Implementations

impl SharedTerm

pub fn fixture(rows: u16, cols: u16, scrollback: u32) -> Self

T-snap-1 (2026-05-27): build a fixture SharedTerm sized to (rows × cols) with a scrollback-line history ring. Empty grid, zero seq, fresh snapshot. Used by tests and the term_snapshot bench; not for production paths.

pub fn feed_for_fixture(&self, bytes: &[u8])

T-snap-1 (2026-05-27): feed VT bytes into a fixture-built SharedTerm. Mirrors what the production reader task does on each PTY read — runs the alacritty VT processor against the byte stream so escape sequences, cursor motions, and SGR attributes all land in the grid. Test/bench-only.

pub fn scroll(&self, kind: TerminalScrollKind)

T3: re-position the scrollback viewport and republish a fresh snapshot so the renderer paints history immediately (no wait for the next PTY byte to wake the reader).

pub fn bracketed_paste(&self) -> bool

CB.3 (docs/dev/architecture/clipboard.md §6): whether the running program has enabled DEC private mode 2004 (bracketed paste). Read by the host’s terminal-paste handler to decide whether to wrap pasted text in \x1b[200~ / \x1b[201~ before writing it to the PTY – programs that understand bracketed paste (shells with readline/zle, vim, etc.) use the markers to treat the whole paste as literal text instead of interpreting it as typed keystrokes. inner is crate-private, so this accessor is the published primitive; the host never reaches into the Term directly.

pub fn find_match( &self, regex: &Regex, direction: SearchDir, ) -> Option<GridSearchHit>

T3.b (2026-05-25): walk the grid (history + live screen) row by row, matching each row’s cell text against regex. Returns the first hit in direction’s walk order, or None if nothing matched.

Forward = top of scrollback → live edge (oldest first). Backward = live edge → top of scrollback (newest first). Trailing-space padding on each row is trimmed before the match so $-anchored regexes behave like vim’s.

pub fn line_range_text(&self, start_line: i32, end_line: i32) -> String

T3.b.2 (2026-05-25): extract cell text for the inclusive alacritty grid line range start_line..=end_line. Used by terminal-Visual linewise yank to copy selected rows into a register. Each row is trimmed of trailing-space padding (the cell grid pads short rows to column width) and joined with \n; the result always ends with \n so it round-trips as a linewise yank (matches vim’s V → y behaviour).

Returns String::new() if the range is empty or falls entirely outside the grid bounds.

pub fn block_range_text( &self, start_line: i32, end_line: i32, start_col: u16, end_col: u16, ) -> String

T3.b.2.b (2026-05-25): extract cell text for the inclusive blockwise rectangle [start_line..=end_line] × [start_col..=end_col]. Each row contributes the slice for its column window. Rows are joined with \n; the trailing newline mirrors line_range_text so paste p adds a row below cleanly. Padding spaces are preserved inside the rectangle (blockwise selections keep alignment).

pub fn char_range_text( &self, start_line: i32, start_col: u16, end_line: i32, end_col: u16, ) -> String

T3.b.2.b (2026-05-25): extract cell text for a character-wise selection from (start_line, start_col) to (end_line, end_col) inclusive, in (line, col) reading order. Multi-line selections include the tail of the start row, full rows between, and the head of the end row — same shape as vim’s charwise yank. The final row preserves its trailing-space padding inside the selection so character-precision is exact.

pub fn cursor_line(&self) -> i32

T3.b.2: row of the live cursor in alacritty grid coords. Used as the initial anchor / head when the user enters Visual mode on the live edge.

pub fn line_bounds(&self) -> (i32, i32)

T3.b.2: scrollback bounds (topmost / bottommost grid lines). Used by Visual-extend so j / k can’t push the head past the available history / live edge.

pub fn cursor_keys_application_mode(&self) -> bool

T2.c (2026-05-25): is the program in application-cursor-keys mode (DECCKM)? Programs that hand-roll fullscreen UIs (vim / less / htop / fzf) set this with ESC [ ? 1 h so arrow keys arrive as ESC O <letter> (SS3) rather than the default ESC [ <letter> (CSI). The translate layer reads this per keystroke when encoding arrow keys.

pub fn resize(&self, rows: u16, cols: u16)

T4.1 (2026-05-25): resize the alacritty grid + republish a fresh snapshot. Caller separately resizes the PTY via PtyHandle::resize so the child sees a SIGWINCH; this helper only updates Lattice’s view of the grid. Safe to call when nothing changed (no-op on identical dims).

pub fn find_all_matches(&self, regex: &Regex) -> Vec<GridSearchHit>

T3.b.3 (2026-05-25): collect every match on every row. Used by hlsearch-style overlay so renderers can paint all occurrences in the visible window with a softer highlight than the current-match. Bounded at 1024 hits to keep the worst-case (cat /dev/urandom | head -1k then /.) from running away.

pub fn scroll_to_line(&self, target: i32)

T3.b: re-position the viewport so target is visible at the top of the screen window. Used by the search-jump path after Self::find_match returns a hit on a scrollback row. Snaps to the live edge if target is already on-screen.

impl SharedTerm

pub fn build_normal_snapshot(&self) -> SyntheticDoc

Build a SyntheticDoc from the current grid state.

• Primary screen: includes scrollback (top..=bot = topmost_line..=bottommost_line).
• Alt screen: visible region only (alt screen has no scrollback semantics; programs like vim / less / htop own the canvas).

Trailing-blank padding is stripped per row before the rope is built. The alacritty grid cursor is translated to document-space (line, byte) coordinates and clamped to the row’s visible length (vim’s “cursor can’t sit in virtual whitespace by default” rule).

Cost is O(rows × cols). Bounded by terminal.scrollback-lines × cols; default 10 000 × 200. See the term_snapshot_build bench for the perf gate.

Trait Implementations

impl Clone for SharedTerm

fn clone(&self) -> SharedTerm

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SharedTerm

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.