Struct TerminalState 

pub struct TerminalState { /* private fields */ }

Terminal state wrapping alacritty_terminal

Implementations

impl TerminalState

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

Create a new terminal state

pub fn cwd(&self) -> Option<&Path>

The terminal’s current working directory as last reported by the shell via OSC 7, if any. Tracks cd within the session (when the shell is configured to emit OSC 7); None otherwise.

pub fn drain_pty_write_queue(&self) -> Vec<String>

Drain any pending data that needs to be written back to the PTY.

This is used for responses to terminal queries like DSR (cursor position report). The caller should write this data to the PTY writer.

pub fn process_output(&mut self, data: &[u8])

Process output from the PTY

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

Resize the terminal.

Scrollback is streamed to the backing file as complete logical lines. A resize perturbs the visible/history boundary and — on a width change — re-wraps already-persisted content, changing its physical row count. Reconciliation depends on why history changed:

• Pure height change (no reflow): physical rows are still valid, so leave synced_history_lines alone. A shrink pushes the top rows into scrollback — new content the next flush writes (no loss). A grow pulls rows back onto the screen; the current <= synced flush guard suppresses them until genuinely new lines scroll off (no duplicates).

• Width change (reflow): the physical count is meaningless now, but the logical line count is invariant under re-wrapping. Re-derive synced_history_lines from synced_logical_lines by walking the reflowed history (a cheap flag-only scan, no I/O) so the next flush appends exactly the logical lines not yet persisted — width spill included, re-wraps excluded. (Deferred if the alternate screen is up, since the primary grid isn’t the one in view.)

pub fn size(&self) -> (u16, u16)

Get current dimensions

pub fn is_dirty(&self) -> bool

Check if content has changed

pub fn mark_clean(&mut self)

Mark as clean after rendering

pub fn cursor_position(&self) -> (u16, u16)

Get the cursor position (column, row)

pub fn cursor_visible(&self) -> bool

Check if cursor is visible

pub fn last_visible_line(&self) -> String

Snapshot of the cursor row’s text content as a plain string.

Used by the terminal_output plugin hook so listeners (e.g. the Orchestrator agent state machine) can match prompt patterns without a separate readback API. Returns cells [0..cursor_col) of the cursor row so a legitimate trailing space typed by the program (typical for prompts like "... (Y/n): ") is preserved while the unwritten right-edge padding past the cursor is dropped. Falls back to trimming the whole row when the cursor has wrapped to the start of a freshly-allocated next row (col == 0): the visible content lives one row up, and the trailing space ambiguity doesn’t apply (a wrap means the line was full).

pub fn get_line(&self, row: u16) -> Vec<TerminalCell>

Get a line of content for rendering

Returns cells as (char, foreground_color, background_color, flags) tuples. Colors are ANSI color indices (0-255) or None for default. Accounts for scroll offset (display_offset) when accessing lines.

pub fn content_string(&self) -> String

Get all visible content as a string (for testing/debugging)

pub fn full_content_string(&self) -> String

Get all content including scrollback history as a string Lines are in chronological order (oldest first)

WARNING: This is O(total_history) and should NOT be used in hot paths. For mode switching, use the incremental streaming architecture instead:

• flush_new_scrollback() during PTY reads
• append_visible_screen() on mode exit

pub fn history_size(&self) -> usize

Get the number of scrollback history lines

pub fn title(&self) -> &str

Get the title (if set by escape sequence)

pub fn set_title(&mut self, title: String)

Set the terminal title (called when escape sequence is received)

pub fn scroll_to_bottom(&mut self)

Scroll to the bottom of the terminal (display offset = 0) Used when re-entering terminal mode from scrollback view

pub fn is_alternate_screen(&self) -> bool

Check if the terminal is in alternate screen mode. Programs like vim, less, htop use alternate screen.

pub fn wants_mouse_events(&self) -> bool

Check if the terminal wants mouse events reported. Returns true if any mouse reporting mode is enabled.

pub fn uses_sgr_mouse(&self) -> bool

Check if SGR mouse encoding is enabled (modern mouse protocol).

pub fn uses_alternate_scroll(&self) -> bool

Check if alternate scroll mode is enabled. When enabled, scroll wheel should be sent as up/down arrow keys.

pub fn is_app_cursor(&self) -> bool

Check if application cursor keys mode (DECCKM) is enabled. Programs like less, git log set this mode so that arrow keys send \x1bOA (SS3) instead of \x1b[A (CSI).

pub fn flush_new_scrollback<W: Write>( &mut self, writer: &mut W, ) -> Result<usize>

Flush newly scrolled-off scrollback to the writer as complete logical lines, returning the number of logical lines written.

Call after process_output() (and before reading the backing file) to incrementally persist scrollback. Rows that alacritty wrapped (WRAPLINE) are joined into one unwrapped logical line, so the backing file stores logical lines — the editor then soft-wraps them to whatever width the scroll-back view happens to be, instead of being frozen at the width they were captured. Only logical lines that have fully scrolled into history are written; a trailing line still continuing into the visible screen is left for a later flush, keeping the file on a logical-line boundary.

pub fn append_visible_screen<W: Write>(&self, writer: &mut W) -> Result<()>

Append the visible screen content to the writer as logical lines.

Call this when exiting terminal mode (or saving a session) to add the current screen to the backing file. Wrapped rows are joined like flush_new_scrollback, but every visible row is emitted (including the trailing logical line and blank rows) so the scroll-back viewport can anchor to the start of this block and line up with the live PTY frame. The block is temporary — re-entering terminal mode truncates the file back to backing_file_history_end.

pub fn backing_file_history_end(&self) -> u64

Get the byte offset where scrollback history ends in the backing file.

Used for truncating the file when re-entering terminal mode (to remove the visible screen portion).

pub fn set_backing_file_history_end(&mut self, offset: u64)

Set the byte offset where scrollback history ends.

Call this after flushing scrollback to record the file position.

pub fn synced_history_lines(&self) -> usize

Get the number of scrollback lines that have been synced to the backing file.

pub fn reset_sync_state(&mut self)

Reset sync state (e.g., when starting fresh or after truncation).