Struct TerminalBuffer 

pub struct TerminalBuffer {

    pub id: BufferId,
    pub pty: Arc<PtyHandle>,
    pub cwd: Option<PathBuf>,
    pub label: String,
    pub program_name: String,
    pub snapshot: Arc<ArcSwap<TerminalSnapshot>>,
    pub term: SharedTerm,
    pub current_match: Option<GridSearchHit>,
    pub visual: Option<TerminalVisualState>,
    pub last_visual: Option<TerminalVisualState>,
    pub insert_exit_pending: bool,
    pub nav_cursor: Option<(i32, u16)>,
    pub all_matches: Vec<GridSearchHit>,
    pub synthetic: Option<Arc<SyntheticDoc>>,
    pub created_at: SystemTime,
    /* private fields */
}

PTY-backed terminal buffer entry held in the host’s buffer registry. Owns the writer handle, the published snapshot cell, and the reader task’s AbortHandle so dropping the buffer kills the reader (and, transitively, the child via PTY close on SIGHUP).

Construct via TerminalBuffer::from_spawn — the host never names the internal field shape directly so adding fields stays non-breaking.

Fields

id: BufferId

pty: Arc<PtyHandle>

cwd: Option<PathBuf>

label: String

program_name: String

2026-05-25: short display name for the spawned program (e.g. zsh, bash, cargo). Captured at spawn from the program path’s basename so the modeline can surface “what’s running here” instead of just “terminal #N”.

snapshot: Arc<ArcSwap<TerminalSnapshot>>

term: SharedTerm

T3 (2026-05-25): shared handle to the alacritty Term. Dispatch-side scroll / resize ops lock the inner Mutex and republish the snapshot. Same handle the reader task holds — cheap to clone (Arc + ArcSwap + Notify).

current_match: Option<GridSearchHit>

T3.b.3 (2026-05-25): the most recent search hit on this terminal, set by submit_search / repeat_search for Terminal buffers and cleared by cancel_search. Renderers read this in their per-frame paint and overlay the matched cells with the search-highlight style. None when no active search is in flight.

visual: Option<TerminalVisualState>

T3.b.2 (2026-05-25): linewise Visual-mode selection state on this terminal buffer. None outside Visual. Both rows are alacritty grid lines (negative = history). Renderers paint the inclusive min(anchor,head)..=max(anchor,head) row range with the selection bg; run_terminal_invocation extends head_line on j / k while Visual is active.

last_visual: Option<TerminalVisualState>

T3.b.3 (2026-05-25): captured prior-Visual state on terminal — restored by gv. Same shape as visual. None when no Visual session has been completed yet.

insert_exit_pending: bool

T2.c (2026-05-25): true after the user has pressed <C-\> in Terminal-Insert and we’re waiting for the second key of the exit chord. Cleared by either the confirm key (<C-n> → exit) or any other key (which emits \x1c plus that key’s PTY bytes).

nav_cursor: Option<(i32, u16)>

2026-05-25: Normal-in-terminal navigation cursor in alacritty grid coords (line: negative = history; positive = live screen; col: cell column). None means “snap to live PTY cursor” — the initial state and what EnterTerminalInsert resets to. Set on the first j / k / h / l / gg / G and tracked thereafter. Renderers paint a block cursor at this position when set; Visual entry uses it as the initial anchor / head.

all_matches: Vec<GridSearchHit>

T3.b.3 (2026-05-25): every regex match across the grid for the current search pattern. Populated alongside current_match in submit_search / repeat_search and cleared by cancel_search / enter-Insert. Renderers paint these with the softer hlsearch overlay; the distinguished current_match keeps the stronger current-hit style.

synthetic: Option<Arc<SyntheticDoc>>

T-mode-1 (2026-05-27): frozen scrollback snapshot when TerminalNormalMode is active on this buffer; None otherwise. Populated by the mode’s on_activate hook (rope build from term.build_normal_snapshot()) and dropped by the mode’s Guard. The central vim grammar operates on this rope during Normal / Visual sub-states; see docs/dev/architecture/terminal-as-document.md. Arc so the host’s render-state publish path can clone out a cheap reference without holding the buffer lock.

created_at: SystemTime

Implementations

impl TerminalBuffer

pub fn from_spawn( id: BufferId, label: String, cwd: Option<PathBuf>, program_name: String, handles: SpawnHandles, ) -> Self

Build a buffer entry from freshly-spawned PTY handles + the host-assigned identity. Centralises the TerminalBuffer field list so the host stays insulated from substrate-internal field changes.

pub fn scrollback_view(&self) -> ScrollbackView

Trait Implementations

impl Debug for TerminalBuffer

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

Formats the value using the given formatter.

impl Drop for TerminalBuffer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.