The type for virtual terminal emulators.

create ~rows ~cols () is a VTE with the given dimensions and:

• scrollback is the maximum number of scrollback lines stored in a ring buffer. Defaults to 10000. Use 0 to disable. Only applies to the primary screen.
• glyph_pool is a shared grapheme pool for multi-width character storage. If omitted a fresh pool is created and shared between both grids and the scrollback.
• width_method is the grapheme width computation method. Defaults to `Unicode. See Glyph.width_method.
• respect_alpha enables alpha blending for semi-transparent colours. Defaults to false.
• default_fg is the opaque foreground colour used when the current style has no explicit foreground. Defaults to Ansi.Color.white.
• default_bg is the opaque background colour used when the current style has no explicit background, and for clearing grids on resize or reset. Defaults to Ansi.Color.black.

rows and cols are clamped to a minimum of 1. The returned VTE has both screens cleared with default_bg, cursor at (0, 0) and visible, auto-wrap on, all other modes off, and the scroll region spanning the full screen.

rows t is t's height in lines.

cols t is t's width in columns.

resize t ~rows ~cols resizes both grids to the given dimensions. Both grids are cleared after the resize. Cursor and scroll region are clamped to the new bounds. Scrollback content is preserved; compressed lines adapt to the new width during decompression.

rows and cols are clamped to a minimum of 1. Marks all rows dirty.

feed t buf ofs len processes len bytes starting at offset ofs in buf as terminal input.

Accepts partial and interleaved text/escape sequences. Invalid or unrecognised sequences are silently ignored. Updates the active grid, cursor, title, style, and mode flags.

ofs and len must satisfy 0 <= ofs and ofs + len <= Bytes.length buf. Out-of-bounds access is undefined behaviour.

O(len), amortised constant time per byte.

feed_string t s is feed t (Bytes.unsafe_of_string s) 0 (String.length s).

grid t is the active visible grid (primary or alternate).

Warning. The grid is mutable and shared with t. External modifications break dirty tracking and may cause rendering inconsistencies.

title t is the terminal title set via OSC 0 or OSC 2 sequences.

is_alternate_screen t is true iff the alternate screen is active. Switched via DECSET/DECRST 47, 1047, or 1049.

Defaults to false.

is_dirty t is true iff grid, cursor, or style state changed since the last clear_dirty.

Note. OSC title updates and mode toggles do not flip the dirty flag.

dirty_rows t is the list of zero-based row indices modified since the last clear_dirty, sorted ascending. O(k) where k is the number of dirty rows.

is_cursor_dirty t is true iff cursor position or visibility changed since the last clear_dirty.

clear_dirty t resets the dirty flag, dirty row set, and cursor dirty flag. Does not alter content.

cursor_pos t is the cursor position (row, col). Satisfies 0 <= row < rows t and 0 <= col <= cols t. col can equal cols t in pending-wrap state when auto-wrap is enabled.

cursor_visible t is true iff the cursor is visible. Controlled via DECTCEM (CSI ?25h/l). Defaults to true.

set_cursor_pos t ~row ~col moves the cursor. row is clamped to [0, rows-1], col to [0, cols]. Marks cursor dirty if the position changes.

set_cursor_visible t v shows or hides the cursor. Marks cursor dirty if visibility changes.

scrollback_capacity t is the maximum number of scrollback lines. 0 if scrollback is disabled.

scrollback_size t is the current number of lines in the scrollback buffer. 0 if scrollback is disabled, empty, or the alternate screen is active. Satisfies 0 <= scrollback_size t <= scrollback_capacity t.

scrollback_lines t is the scrollback content as plain-text strings ordered oldest to newest. Style information is discarded. Trailing spaces are trimmed during compression. Empty if scrollback is disabled, empty, or the alternate screen is active. O(scrollback_size).

render_with_scrollback t ~offset dst renders a snapshot combining scrollback history and the live screen into dst.

The top rows of dst are filled with scrollback lines (oldest at the top) and the remaining rows with the current screen. offset is the number of lines above the live screen the snapshot extends: 0 shows only the live terminal. offset is clamped to [0, scrollback_size].

dst should have the same width as t for correct glyph placement; smaller widths clip decompressed graphemes. On the alternate screen (no scrollback) this is equivalent to Grid.blit ~src:(grid t) ~dst.

O(Grid.height dst × cols).

auto_wrap_mode t is true iff auto-wrap (DECAWM) is active. When enabled, writing past the right margin wraps to the next line. Controlled via CSI ?7h/l. Defaults to true.

insert_mode t is true iff insert mode (IRM) is active. Characters push existing content right instead of replacing it. Controlled via CSI 4h/l. Defaults to false.

cursor_key_mode t is true iff cursor keys use application mode (DECCKM). Application mode sends ESC O A instead of ESC [ A for arrow keys. Controlled via CSI ?1h/l. Defaults to false.

bracketed_paste_mode t is true iff bracketed paste is active. Pasted text is wrapped with ESC [ 200 ~ / ESC [ 201 ~ markers. Controlled via CSI ?2004h/l. Defaults to false.

origin_mode t is true iff origin mode (DECOM) is active. In origin mode, CUP/HVP coordinates are relative to the scroll region.

Note. DECOM handling is not wired yet; this accessor always returns false in the current release.

scroll_up t n scrolls the current scroll region up by n lines. Lines leaving the top enter scrollback only when the primary screen is active, scrollback is enabled, and the region starts at row 0. Newly exposed rows are cleared with the default transparent background. No effect if n <= 0.

Marks all rows in the scroll region dirty.

scroll_down t n scrolls the current scroll region down by n lines. Blank rows are inserted at the top; lines leaving the bottom are discarded (never saved to scrollback). No effect if n <= 0.

Marks all rows in the scroll region dirty.

See also scroll_up.

reset t resets t to its initial state. Clears both grids and scrollback, moves cursor to (0, 0) and makes it visible, resets style to default, sets auto-wrap on and all other modes off, resets scroll region to full screen, and switches to the primary screen. Dimensions are unchanged. Equivalent to RIS (ESC c).

Marks all rows dirty.

to_string t is the visible screen content as a multi-line string. One line per row, separated by newlines. Trailing spaces are preserved. Wide graphemes appear once. Style information is not included. The result does not end with a trailing newline.