Module MatrixSource

ANSI escape sequence generation.

Unicode glyph measurement.

Cell-based drawing grid.

Terminal input event parsing.

Double-buffered frame rendering.

Terminal protocol state machine.

Declarative image composition and rendering.

The type for Kitty keyboard protocol configurations.

• `Auto enables the protocol when the terminal advertises support; falls back to modify-other-keys for Ctrl+Alt chords on legacy terminals.
• `Disabled never negotiates the protocol.
• `Enabled flags forces activation with the given bitmask. See the Kitty keyboard protocol specification for flag values.

The type for presentation modes.

• `Alt uses the alternate screen buffer. The application fully owns the screen; content is restored on exit.
• `Primary renders inline on the primary screen below the current cursor row. Static output flows above the UI and enters native scrollback.

The type for debug overlay anchor corners.

The type for live applications. All frame, query, and control functions require this handle. Created by create or attach.

create () is a live application with Unix I/O wired in.

Sets up the terminal, enables raw mode, installs signal handlers, and returns a ready-to-run handle.

Display:

• mode presentation mode. Defaults to `Alt.
• raw_mode whether to switch the TTY into raw mode. Defaults to true.

Rendering:

• respect_alpha whether to honour alpha blending. Defaults to false.
• cursor_visible initial cursor visibility. Defaults to true in `Alt mode, false in `Primary.
• explicit_width whether to use built-in wcwidth instead of querying the terminal. Defaults to false.

Frame timing:

• target_fps optional FPS cap in Hz. Defaults to Some 30.. None for uncapped.
• resize_debounce debounce window in seconds for resize events. Defaults to Some 0.1.

Primary mode:

• min_tui_height minimum height in rows reserved for the dynamic TUI region. Static content will not grow past this floor. Defaults to 1.
• start_idle when true, the render loop starts in idle state even when target_fps is set. The loop begins running only when request_live is called. One-shot redraws via request_redraw still work while idle. Defaults to false.

Input:

• mouse_enabled whether to enable mouse tracking. Defaults to true.
• mouse explicit mouse tracking mode. Defaults to None (selects `Sgr_any when mouse_enabled is true).
• bracketed_paste whether to enable bracketed paste. Defaults to true.
• focus_reporting whether to enable focus-in/focus-out events. Defaults to true.
• kitty_keyboard Kitty keyboard protocol configuration. Defaults to `Auto.
• exit_on_ctrl_c whether Ctrl+C exits. Defaults to true.
• input_timeout timeout in seconds for input polling when no cadence is active. Defaults to None (block indefinitely).

Unix:

• output output target. Defaults to `Stdout.
• signal_handlers whether to install SIGTERM/SIGINT/SIGQUIT handlers. Defaults to true.
• initial_caps seed capabilities passed to Terminal.make.

Diagnostics:

• debug_overlay show the debug overlay. Defaults to false.
• debug_overlay_corner anchor corner. Defaults to `Bottom_right.
• debug_overlay_capacity maximum metric samples retained.
• frame_dump_every dump every Nth frame. Defaults to 0 (disabled).
• frame_dump_dir directory for frame dumps.
• frame_dump_pattern filename pattern for frame dumps.
• frame_dump_hits include hit grid in dumps. Defaults to false.

run ~on_render app drives the immediate-mode event loop.

Each iteration:

• Polls for events and invokes on_input / on_resize.
• Calls on_frame with the elapsed seconds since the last render.
• Calls prepare to clear buffers.
• Invokes on_render (draw to grid here).
• Optionally samples primary_required_rows for `Primary mode sizing.
• Calls submit to diff and flush output.

The loop exits when running becomes false. Exceptions close the runtime before propagating.

prepare app starts a new frame. Clears the grid and hits buffers and updates layout calculations.

Note. Called automatically by run.

grid app is the mutable grid for the current frame.

hits app is the hit grid for the current frame.

submit ?primary_required_rows app diffs the current frame against the previous one and flushes ANSI output. Call after drawing into grid.

In `Primary mode, primary_required_rows can be provided to request a larger dynamic render region for this frame.

Note. Called automatically by run.

close app tears down protocols and releases resources. Safe to call multiple times.

stop app marks the runtime as stopped. The run loop exits on the next tick.

start app resumes the render cadence and marks the control state as explicitly started.

pause app stops the render cadence but leaves the terminal configured. start resumes.

suspend app pauses rendering and restores the terminal to cooked mode. resume reapplies configuration.

resume app reapplies terminal configuration after suspend.

request_live app signals pending live work. Restarts the render cadence when transitioning from idle.

drop_live app decrements the live counter. When it reaches zero in auto mode the cadence idles.

running app is true iff the event loop is active.

request_redraw app marks the frame dirty for the next iteration.

mode app is the presentation mode set at creation time.

size app is the current dynamic-region dimensions as (cols, rows).

full_size app is the full terminal dimensions (cols, rows), ignoring the primary-mode render offset. In `Alt mode this is identical to size.

effective_size app is the dynamic-region dimensions (cols, rows) that will be in effect once pending static writes are flushed. In `Alt mode or when the static queue is empty this equals size. Use this in on_render to lay out the dynamic UI against the post-commit geometry.

pixel_resolution app is the last known pixel resolution as (width, height), or None if the terminal has not reported one.

terminal app is the underlying terminal handle.

capabilities app is the current terminal capabilities.

static_write app ~rows s writes s to the static area, using rows as the exact number of terminal rows consumed. The caller is responsible for computing rows accurately (e.g. from Grid.active_height after rendering to a grid).

static_clear app clears static content and resets the primary scroll region.

set_cursor ?visible ?style app updates cursor visibility and/or style.

set_cursor_style app ~style ~blinking sets cursor shape and blink.

set_cursor_position app ~row ~col moves the cursor to 1-based coordinates within the dynamic render region.

set_cursor_color app ~r ~g ~b ~a sets the cursor color. Components are in [0.;1.].

set_debug_overlay app ~enabled shows or hides the debug overlay. corner defaults to the value given to create.

toggle_debug_overlay app flips overlay visibility.

configure_frame_dump app updates the periodic frame-dump schedule. See the diagnostics parameters of create.

dump_frame app writes the current frame to disk immediately.

install_signal_handlers () installs shutdown handlers for SIGTERM, SIGINT, SIGQUIT, and SIGABRT. Idempotent.

attach ... () is like create but wired to caller-provided I/O callbacks.

The optional parameters mirror create. The required callbacks are:

• write_output writes len bytes from buf at off.
• now returns the current monotonic time in seconds.
• wake signals the event loop to re-check state.
• terminal_size returns (cols, rows).
• set_raw_mode toggles raw mode.
• flush_input discards pending input.
• read_events blocks for events up to timeout, invoking on_event for each.
• query_cursor_position queries cursor position with the given timeout.
• cleanup releases resources on close.

parser is the input parser, terminal the protocol handle, and width/height the initial dimensions.

render_offset defaults to 0. static_needs_newline defaults to false.