hide_cursor()

Hide the terminal cursor

show_cursor()

Show the terminal cursor

go(line, col)

Move cursor to an absolute line and column position

write(s)

Write a string to stdout and flush

write_at(line, col, s)

Move cursor to a position and write a string

move(direction, count)

Move cursor in a relative direction

Direction can be "up", "down", "left", "right", "line_down", "line_up", or "column". Count defaults to 1.

clear()

Clear the entire screen

clear_line(mode)

Clear part or all of the current line

Mode 0 (default) clears from cursor to end, 1 from cursor to beginning, 2 the entire line. Cursor position does not change.

style(...) -> ansi

Build an ANSI style escape sequence from style names

Accepts style names such as "bold", "italic", "underlined", "dim", "inverted", "reset". Returns the combined ANSI escape sequence, or an empty string if no valid styles are given.

set_style(...)

Apply ANSI styles to the terminal immediately

color(fg, bg) -> ansi

Build an ANSI color escape sequence for foreground and background

Color values can be a named color string (e.g. "red"), a 256-color index number, or an RGB table {r, g, b}.

set_color(fg, bg)

Apply foreground and background colors immediately

cursor_position() -> line, col

Query the terminal for the current cursor position

Sends a CPR request (ESC [ 6 n) and reads the response (ESC [ row ; col R). Requires a TTY; typically called while the terminal is in raw mode. Returns nil on parse failure or if the terminal does not respond with the expected sequence.

title(str)

Set the terminal window title

kitty_notify(title, body)

Send a desktop notification via Kitty's notification protocol

text_size(text, opts) -> sized

Apply Kitty text sizing protocol to text

The opts table may contain: s (scale 1--7), w (width 0--7), n/d (fractional numerator/denominator), v (vertical align), h (horizontal align). When fractional scaling with explicit width is used, text is automatically chunked.

text_size_chunks(text, opts) -> chunks, meta_str

Calculate text-sizing chunk boundaries without generating escape sequences

Helper used by tss:apply_sized(). Accepts the same opts table as text_size(). Three return cases:

• Chunking needed (n, d, and w all set): a table of {start, stop, meta_str} chunk descriptors (1-based UTF-8 character indices) plus the meta_str string.

• Single wrap (no fractional chunking): nil, meta_str.

• No text sizing applicable: nil, nil.

has_kkbp() -> supported

Check whether the terminal supports the Kitty keyboard protocol

Sends two probes simultaneously: a KKBP flags query (CSI ? u) and a Primary Device Attributes request (CSI c). Whichever response arrives first determines the result: CSI ? <flags> u → supported; CSI ? ... c → not supported.

has_ts() -> support

Detect text sizing protocol support via cursor position reports

Must be called in raw mode. Returns true for full support, "width" for width-only support, or false for no support.

has_ts_combined() -> combined

Check how the terminal handles combined scale and width text sizing

Must be called in raw mode. Sends OSC 66 ; s=2:w=2 ; <space> then reads the resulting cursor position. A 4-cell advance means the terminal uses combined semantics (s × w cells); a 2-cell advance means width-only semantics. Results are cached after the first call.

init_ts_width_mode()

Derive and cache text-sizing width mode from detection results

Calls has_ts() and, when full support is detected, has_ts_combined() (both require raw mode). Caches the results consumed by ts_width_mode() and supports_ts(). Must be called once during terminal capability detection before any text-sized rendering begins.

ts_width_mode() -> mode

Return cached text-sizing width mode

Returns "w_only" when the w parameter and fractional n/d scaling are interpreted independently by the terminal, or "combined" when the terminal applies Kitty-native semantics where w multiplies the scale factor. Defaults to "combined" if init_ts_width_mode() has not been called yet.

supports_ts() -> supported

Return cached text-sizing support boolean

enable_kkbp()

Enable the Kitty keyboard protocol with progressive enhancement level 15

Pushes a KKBP stack entry and sets progressive enhancement flags to 15 (1 = disambiguate escape codes, 2 = report event types, 4 = report alternate keys, 8 = report all keys as escape codes). Flag 16 (report associated text) is intentionally excluded. The term.input module assumes this exact enhancement level.

disable_kkbp()

Disable the Kitty keyboard protocol and restore default key handling

enable_bracketed_paste()

Enable bracketed paste mode for clipboard paste detection

disable_bracketed_paste()

Disable bracketed paste mode

get_pixel_dimensions(timeout_ms) -> win_w, win_h, cell_w, cell_h

Query the terminal for pixel dimensions of the window and cells

Sends CSI 14 t (window pixel size) and CSI 16 t (cell pixel size) and reads both xterm-style responses. Returns win_w, win_h, cell_w, cell_h (all in pixels). Returns nil if either response does not arrive within timeout_ms (default 100 ms) or the terminal does not support pixel dimension queries.

set_sane_mode()

Restore the terminal to sane (cooked) mode

set_raw_mode()

Switch the terminal to raw mode if not already active

switch_screen(scr)

Switch between the main and alternate terminal screen buffers

Pass "main" (default) to switch to the main screen, or "alt" for the alternate screen.

alt_screen() -> state

Enter the alternate screen with KKBP and bracketed paste enabled

Saves the cursor position, switches to the alt screen, enables KKBP and bracketed paste, and hides the cursor. Returns a state object with a state:done() method that restores everything.

get() -> key, mods, event, shifted, base

Read a keyboard event via the Kitty keyboard protocol

Returns the key name or character, modifier bitmask, event type (1=press, 2=repeat, 3=release), shifted key, and base key. Handles bracketed paste and returns the pasted text directly.

mods_to_string(mods) -> combination

Convert a modifier bitmask to a human-readable string

Maps a KKBP modifier bitmask to a "+" separated string of modifier names. Bit values: SHIFT=1, ALT=2, CTRL=4, SUPER=8, HYPER=16, META=32, CAPS_LOCK=64, NUM_LOCK=128. Example: mods_to_string(5) → "SHIFT+CTRL"

string_to_mods(combination) -> mods

Convert a modifier string to a bitmask

Parses a "+" separated modifier name string and returns the corresponding KKBP bitmask. Unknown names are silently ignored. Example: string_to_mods("SHIFT+CTRL") → 5

simple_get() -> key

Read a keyboard event and return a simplified key description

Wraps get() to return either a single character for printable keys or a shortcut string like "CTRL+c" for modified keys. Ignores key release events.