Terminal manages terminal protocol state and writes escape sequences through a caller-provided output callback. The caller (runtime) owns all I/O resources: no Unix.select, no threads, no wakeup pipe, no signal handling.
Capability detection
Capabilities are seeded from environment heuristics at creation time (make). The runtime refines them by calling probe with I/O callbacks, or incrementally via apply_capability_event as the input parser produces capability responses.
Protocol symmetry
Every protocol enabled through the handle is unwound by close or reset_state. Protocol operations are idempotent: requesting a mode that is already active is a no-op. For non-TTY handles (tty = false) escape sequences are suppressed but internal state tracking remains active.
The type for tracked cursor positions. x and y are one-based coordinates; (1, 1) is the top-left corner. visible reflects the last requested visibility.
true if SGR pixel-position mouse reports (mode 1016) are supported.
*)
color_scheme_updates : bool;
(*
true if colour-scheme update notifications (mode 2031) are supported.
*)
explicit_width : bool;
(*
true if the terminal reported explicit cell-width information via proprietary cursor-position queries.
*)
explicit_cursor_positioning : bool;
(*
true if the terminal may miscalculate grapheme widths but supports reliable cursor positioning. When set, the renderer repositions the cursor after each wide grapheme to prevent column drift. Only used when explicit_width is false.
*)
scaled_text : bool;
(*
true if scaled text sizing is supported.
*)
sixel : bool;
(*
true if SIXEL graphics are supported.
*)
sync : bool;
(*
true if synchronised output (mode 2026) is supported.
*)
hyperlinks : bool;
(*
true if OSC 8 hyperlinks are supported.
*)
}
The type for terminal capabilities.
Detection happens in two stages:
Environment stage.make inspects $TERM, $COLORTERM, $KITTY_WINDOW_ID, platform quirks, and overrides such as MATRIX_FORCE_UNICODE. No escape sequences are emitted.
Probe stage. The runtime calls probe with I/O callbacks and the results are folded into the capability record.
Boolean fields from probing are monotonic: once confirmed, subsequent probes do not disable them. Environment policy overrides may still disable features in specific contexts (e.g. tmux forces wcwidth mode).
The type for terminal emulator identity. name and version are populated from XTVersion when available; otherwise derived from $TERM_PROGRAM and $TERM_PROGRAM_VERSION. from_xtversion is true iff name and version came from an XTVersion response.
The type for terminal protocol state. A value of type t encapsulates an output callback, capability and terminal metadata, and protocol state (mouse mode, cursor, alternate screen, etc.).
Sourceval make :
output:(string -> unit)->?tty:bool ->?initial_caps:capabilities->unit ->t
make ~output ~tty ~initial_caps () is a terminal handle with:
output receives escape sequence strings.
tty controls whether escape sequences are emitted. Defaults to true. Set to false for non-TTY outputs or testing.
initial_caps seeds the capability record. When omitted, capabilities are built from $TERM and environment heuristics. When provided, the record is used as-is and environment overrides are not applied.
Sends a compound query payload through output and processes responses using the provided I/O callbacks and parser. Updates capabilities and terminal_info with the results.
Using the caller's parser ensures that partial escape sequences spanning the probe boundary are preserved. User input events received during probing are forwarded to on_event.
timeout is the maximum probe duration in seconds. Defaults to 0.2.
Protocol control
All protocol operations are idempotent. For TTY handles, escape sequences are emitted through output. For non-TTY handles, only internal state is updated.
Sourceval restore_modes : ?skip_focus:bool ->t-> unit
restore_modes ?skip_focus t unconditionally re-sends enable sequences for every currently-active protocol mode (mouse tracking, focus reporting, bracketed paste, Kitty keyboard, modifyOtherKeys).
When skip_focus is true, the focus-tracking enable sequence is not re-sent. This avoids a feedback loop when restore_modes is called from a Focus event handler: some terminals re-report focus state upon receiving the enable sequence, creating an infinite cycle.
Intended for focus-in recovery: some terminal emulators (notably Windows Terminal / ConPTY) strip DEC private modes when the window loses focus.
Note. For the Kitty keyboard protocol, the existing stack entry is popped before re-pushing to avoid unbounded stack growth.
cursor_style_state t is the current cursor style and blinking flag as (style, blinking).
Sourceval set_cursor_color : t->r:float ->g:float ->b:float ->a:float -> unit
set_cursor_color t ~r ~g ~b ~a sets the cursor colour. Components are clamped to [0.0; 1.0]. NaN components are treated as 0.0. The alpha channel is tracked but not sent to the terminal.
query_pixel_resolution t sends a pixel resolution query (CSI 14 t) through output. The response arrives asynchronously and should be processed via apply_capability_event.
set_raw fd puts fd into raw mode (no echo, no canonical processing, no signals, non-blocking) and returns the original termios for later restoration with restore.