KetraTermTerminalBuffer
Full public contract for the terminal buffer.
Composes all role-specific interfaces into a single surface for host applications and host tests.
Cursor positions and cell/line reads use zero-based viewport coordinates. Margin and rectangular commands retain the DEC one-based conventions documented on each method, including zero for omitted rectangle parameters. The host adapter owns conversion from parser commands; the parser does not own grid coordinates.
Instances returned by io.github.ketraterm.core.TerminalBuffers require external serialization of mutations and grid/cursor/history reads. Atomic mode snapshots may be read independently as documented by TerminalModeReader. Borrowed line and render views are valid only while that serialization is held. Session-backed hosts access terminal state through their session boundary rather than concurrently mutating this buffer.
Host adapters should depend on the narrower interfaces they need; this facade composes the complete core contract for direct embedders.
Inheritors
Properties
Invalidation token for incomplete transfers, changed by reset, screen switch and destructive clearing. Compare for inequality, not ordering. This is separate from the render frame's graphics generation.
Number of retained off-screen history lines in the active buffer.
Actual active screen. Read synchronously under the same serialization as terminal mutations.
Current immutable effective palette, including application color overrides. Reading retains the existing object without allocating or reading a render frame. Synchronize with terminal mutations before reading; a retained palette remains safe to use after releasing that synchronization.
The number of queued response bytes currently waiting to be read.
Active xterm window title.
Functions
Applies borrowed OSC 21 color operations in order, without retaining request. Queries observe preceding operations and share one response in request order. Resets restore the latest theme; dynamic selection and cursor roles retain their dynamic behavior until changed or reset. Application changes do not emit color-scheme notifications.
Commits an externally decoded upload or query under the same admission, placement and reply rules as applyGraphicsCommand. The decoder owns payload validation; core still validates controls, image bounds and placement before replacing any retained image. PNG dimensions come from image.
Applies a complete command using the Base64-decoded prefix data[0 until length]. command and data are borrowed for this call. Raw RGB/RGBA pixels are copied into immutable storage before returning; upload-only and query operations do not place an image. Placement uses the current cursor and known cell-pixel geometry.
Executes a carriage return (CR, 0x0D).
Changes DECCARA visual attributes without changing cell values, protection, hyperlinks, or the current SGR pen. Masks use io.github.ketraterm.protocol.DecRectangleAttribute bits.
Clears all tab stops (TBC 3, CSI 3 g).
Discards all queued response bytes from this channel.
Clears the visible screen and homes the cursor (equivalent to ED 2 + CUP).
Clears the tab stop at the current cursor column (TBC 0, CSI 0 g).
Moves the cursor backward by count tab stops (CBT, CSI Ps Z).
Moves the cursor down by n rows (CUD, CSI n B).
Advances the cursor forward by count tab stops (CHT, CSI Ps I).
Moves the cursor left by n columns (CUB, CSI n D).
Moves the cursor right by n columns (CUF, CSI n C).
Deletes count characters at the cursor column, shifting the remainder of the line left and filling the vacated right cells with blanks using the active pen attribute (DCH, CSI n P). Cursor position is not changed.
Deletes DECDC columns at the cursor column across the active vertical scroll region.
Deletes count lines starting at the cursor row within the active scroll region (DL, CSI n M).
Switches to the alternate screen buffer with cursor save (CSI ? 1049 h).
Switches to the alternate screen buffer without saving the primary cursor state.
Erases the active screen and history with the current erase attributes. Preserves the cursor position, pen, modes, margins, tabs, saved cursor, and inactive buffer. Cancels pending wrap and replaces erased line identities. The caller must serialize access with all other terminal operations.
Erases count characters starting at the cursor column without shifting the remainder of the line (ECH, CSI n X).
Erases the entire current line without moving the cursor (EL 2, CSI 2 K).
Erases the entire visible screen without moving the cursor (ED 2, CSI 2 J).
Erases from the start of the current line through the cursor (EL 1, CSI 1 K).
Erases from the cursor to the end of the current line (EL 0, CSI 0 K).
Erases all scrollback history while preserving the visible viewport (xterm/VTE ED 3, CSI 3 J).
Erases from the start of the visible screen through the cursor (ED 1, CSI 1 J).
Erases from the cursor to the end of the visible screen (ED 0, CSI 0 J).
Executes DECCOLM (CSI ? 3 h / CSI ? 3 l) as a core-owned macro command.
Returns to the primary screen buffer with cursor restore (CSI ? 1049 l).
Returns to the primary screen buffer without restoring a saved cursor.
Returns scrollback history followed by the visible screen as a newline-joined string, oldest line first.
Returns the attributes at a screen position as an unpacked CellAttributes object.
Returns the display/base codepoint at [col, row].
Returns one atomic packed snapshot for input encoders.
Returns the content of a visible row as a string, trimming trailing blank cells while preserving intentional space characters.
Returns one atomic snapshot of the published packed mode subset.
Returns an immutable snapshot of the published TerminalModeSnapshot fields.
Returns the visible screen as a newline-joined string, top to bottom.
Advances the cursor to the next tab stop (HT, 0x09).
Inserts count blank cells at the cursor column, shifting existing cells right (ICH, CSI n @). Cells pushed past the right margin are discarded.
Inserts DECIC blank columns at the cursor column across the active vertical scroll region.
Inserts count blank lines at the cursor row within the active scroll region (IL, CSI n L).
Restores and removes the most recently saved colors; an empty stack has no effect. The latest host theme remains the source for color resets. Host light/dark preference and bold-as-bright behavior are preserved. An effective change invalidates visible rows without emitting a color-scheme notification; unchanged colors preserve palette identity and render generations.
Moves the cursor to an absolute position (CUP / HVP, CSI row ; col H).
Saves effective indexed and named colors, including dynamic presentation, on a terminal-wide stack of ten entries. A full stack discards its oldest entry. Screen switches, resize, and theme changes preserve saved colors; hard and soft terminal resets clear the stack. Saving does not repaint.
Pushes the current Kitty keyboard progressive-enhancement flags to the stack, and sets the new active flags. Each screen retains at most 32 entries, evicting the oldest when full.
Enqueues the color query response for a dynamic target (10, 11, or 12).
Enqueues the color query response for a specific 256-color palette index.
Enqueues the response for a DCS DECRQSS request.
Enqueues the response for a DCS XTGETTCAP request.
Enqueues a device attributes (DA) report response.
Enqueues a device status report (DSR) response.
Enqueues an allowlisted XTQFMTKEYS reply using the active format resource. Unknown and reserved resources stay silent; this protocol defines no failure reply. Host adapters must enforce terminal-response policy before calling this API.
Enqueues an allowlisted xterm key-modifier option response.
Enqueues the active Kitty keyboard progressive-enhancement flags as a parameterless CSI ? u query response. Core reports only flags retained by its supported-mode mask.
Enqueues one ANSI or DEC private DECRPM reply (CSI [?] mode;status $ y). The explicit mode allowlist returns status 0 for unsupported queries. Negative identifiers produce no response. Queries do not mutate modes or invalidate rendering. Invoke under the same synchronization as core mutation. Host adapters must enforce terminal-response policy before calling this API.
Enqueues an allowlisted window report response using current host geometry. Pixel-size query reports remain silent when the host has not supplied usable dimensions. Cell pixel dimensions use the integer text-area pixel size divided by the grid dimensions. Callers must enforce terminal-response permission for application queries.
Resets the cursor to the home position (col=0, row=0).
Restores the configured default shape and enables cursor blinking.
Restores one dynamic color from the latest host-configured theme. Other application overrides are preserved; unsupported targets are ignored.
Restores one format resource to 0; unknown resources are ignored.
Restores all xterm format resources atomically, preserving modifier resources.
Restores one modifier resource's initial value; unknown resources are ignored.
Restores all xterm modifier resources atomically, preserving format resources.
Restores indexed colors from the latest host-configured theme in one update.
Resets the scroll region to the full viewport and homes the cursor.
Restores the core-owned state saved by saveCursor (DECRC, ESC 8).
Executes Reverse Index (RI, ESC M).
Reverses DECRARA visual attributes without changing cell values, protection, hyperlinks, or the current SGR pen. reverseMask uses io.github.ketraterm.protocol.DecRectangleAttribute bits.
Saves the core-owned cursor state (DECSC, ESC 7).
Scrolls the active scroll region down by one line (SD, CSI 1 T).
Scrolls the active region down by count lines, capped at its height. Non-positive counts are ignored. Preserves the cursor position and uses the same horizontal-margin rules as scrollDown, without consuming history. Work is bounded by the grid dimensions, not the supplied count.
Scrolls the active scroll region up by one line (SU, CSI 1 S).
Selectively erases the entire current line without moving the cursor (DECSEL 2).
Selectively erases the entire visible screen without moving the cursor (DECSED 2).
Selectively erases from the start of the current line through the cursor (DECSEL 1).
Selectively erases from the cursor to the end of the current line (DECSEL 0).
Selectively erases from the start of the visible screen through the cursor (DECSED 1).
Selectively erases from the cursor through the end of the visible screen (DECSED 0).
Sets alternate-screen wheel scrolling (DEC private mode 1007). Enabled by default; host policy may suppress wheel-to-key translation. Preserves pending wrap and survives screen switches, resize, and DECSTR.
Toggles application cursor key mode (DECCKM, CSI ? 1 h / CSI ? 1 l).
Toggles application keypad mode (DECNKM).
Selects DECSACE extent for future DECCARA and DECRARA operations.
Enables or disables DECAWM auto-wrap (CSI ? 7 h / CSI ? 7 l).
Selects the Backspace wire byte through DECBKM (CSI ? 67 h/l).
Toggles urgent bell mode (?1042).
Enables or disables bracketed paste reporting (CSI ? 2004 h / CSI ? 2004 l).
Publishes host permission for automatic color-scheme and resize reports.
Subscribes to host color-scheme changes (DECSET/DECRST ?2031).
Toggles cursor blink presentation state.
Sets the cursor shape/style.
Toggles cursor visibility presentation state (DECTCEM, CSI ? 25 h / CSI ? 25 l).
Sets the default cursor shape/style restored on reset.
Updates a dynamic target color (foreground, background, or cursor color).
Enables or disables focus in/out reporting (CSI ? 1004 h / CSI ? 1004 l).
Sets the format-other-keys wire format used when modify-other-keys applies.
Sets the active OSC 8 hyperlink id stamped onto future printed cells.
Sets the xterm icon title.
Subscribes to text-area resize reports (DECSET/DECRST ?2048).
Enables or disables Insert Replace Mode (IRM, CSI 4 h / CSI 4 l).
Selects format 0 (CSI 27) or 1 (CSI u) for one xterm resource. Resource 0 is independent storage, as in xterm; it does not override per-class formats.
Sets one xterm modifier resource. Resource 0 retains the legacy-profile admission mask; the current PC profile always permits modifiers. Values are -1 (disable), 0..3 for ordinary keys, 0..15 for resource 0, and 0..4 for other key classes.
Sets active Kitty keyboard progressive-enhancement flags.
Enables or disables left/right margin mode (DECLRMM, CSI ? 69 h / CSI ? 69 l).
Sets the active horizontal margins (DECSLRM, CSI left ; right s).
Sets the modify-other-keys reporting level.
Sets the active mouse report encoding mode used by terminal-to-host reporting.
Sets the active mouse tracking mode used by terminal-to-host reporting.
Enables or disables New Line Mode (LNM, CSI 20 h / CSI 20 l).
Enables or disables Origin Mode (DECOM, CSI ? 6 h / CSI ? 6 l).
Updates an individual color index in the active 256-color palette.
Sets the active pen attributes used by all subsequent write and erase operations.
Sets the active pen attributes using explicit default, indexed, or RGB colors.
Toggles pop on bell mode (?1043).
Toggles reverse-video presentation state (DECSCNM, CSI ? 5 h / CSI ? 5 l).
Enables reverse wrap across soft-wrapped rows (DEC private mode 45). Requires auto-wrap. Stops at hard line breaks and the top margin. Changing this mode preserves the cursor and pending wrap.
Enables extended reverse wrap (DEC private mode 1045). Requires auto-wrap and takes precedence over mode 45. Crosses hard line breaks and cycles from the top margin to the bottom margin. Changing this mode preserves the cursor and pending wrap.
Sets the active vertical scroll region (DECSTBM, CSI top ; bottom r).
Enables or disables selective-erase protection on future printed cells (DECSCA).
Requests Shift as a mouse reporting modifier (XTSHIFTESCAPE). Disabled by default so Shift restores local interaction. Hosts may deny reporting. Preserves pending wrap and survives screen switches, resize, and DECSTR.
Toggles synchronized output mode (DECSET/DECRST ?2026).
Sets a tab stop at the current cursor column (HTS, ESC H).
Sets the theme-configured color palette for the terminal session.
Controls how East Asian Ambiguous codepoints are measured for future writes.
Updates the recorded window minimization state.
Updates the recorded text-area size in pixels, excluding host padding. A changed size emits a subscribed mode 2048 report when permitted. Use the pixel-aware TerminalBuffer.resize overload when both grid and pixel dimensions change so one report describes the completed resize. If either dimension is nonpositive, both are recorded as unknown zero.
Sets the xterm window title.
Updates only the supplied SGR pen fields. A null field is unchanged; CellColor.DEFAULT explicitly selects the default color and false clears a flag. Hyperlink and selective-erase protection are preserved. With all fields null this is a no-op. Consumed synchronously; serialize with other terminal reads and writes. No cell is changed.
Updates the most recently written printable cell with a complete grapheme sequence.
Writes one pre-segmented grapheme cluster to the grid.
Writes one Unicode scalar value at the cursor position using the active pen attributes, then advances the cursor.