Spatial indexing for mouse hit testing.

The type for screens. Manages double-buffered grids, hit grids, post-processing pipeline, statistics, and frame rate control.

The type for cumulative rendering statistics.

The type for per-frame metrics. All durations are in milliseconds unless noted otherwise.

create ~glyph_pool ~width_method ~respect_alpha ~mouse_enabled ~cursor_visible ~explicit_width () is a screen with:

• glyph_pool stores multi-width grapheme clusters. Defaults to a fresh pool. Share a pool across screens to reduce memory for common text.
• width_method is the character width computation method. Defaults to `Unicode. See Glyph.width_method.
• respect_alpha enables alpha blending when drawing cells. Defaults to false.
• mouse_enabled is the initial mouse-enabled flag. Defaults to true.
• cursor_visible is the initial cursor visibility. Defaults to true.
• explicit_width enables explicit-width OSC sequences for graphemes. Defaults to false.

Grids start at 1x1 and are resized automatically on the first build.

build t ~width ~height f builds a frame.

Resizes buffers to width x height when both are positive, clears the hit grid, then calls f with the next grid and hit grid for in-place mutation. Returns t for chaining.

When width <= 0 or height <= 0, f is not called; only the hit grid is cleared.

Warning. The Grid.t and Hit_grid.t passed to f must not be mutated after the next render -- they become the diff baseline.

glyph_pool t is the glyph pool shared by t's grids.

The type for post-processing effect identifiers.

post_process f t registers f as a persistent post-processing transform and is its effect_id.

f is called during each render after frame building but before diffing. It receives the next grid and ~delta (milliseconds since last render, 0. on the first frame). Processors run in insertion order and persist across frames until removed.

See also remove_post_process.

remove_post_process id t unregisters the post-processor identified by id. Returns t for chaining.

clear_post_processes t removes all post-processing functions. Returns t for chaining.

add_hit_region t ~x ~y ~width ~height ~id registers a hit region on the next hit grid. Convenience wrapper around Hit_grid.add for use outside the build callback. Regions outside grid bounds are clipped. Negative dimensions are clamped to zero. Returns t for chaining.

render ~full ~height_limit t is the ANSI output for the current frame.

Applies post-processors, diffs next against current (or renders all cells when full is true), then swaps buffers. Hit regions registered during this frame become queryable via query_hit.

• full renders all cells regardless of changes. Defaults to false.
• height_limit limits rendering to the first height_limit rows.

See also render_to_bytes.

render_to_bytes ~full ~height_limit t buf is like render but writes into buf and is the number of bytes written. buf must be large enough for the output.

set_mouse_enabled t b updates the desired mouse-enabled flag. Rendering does not emit mode changes.

set_cursor_visible t b updates the desired cursor visibility. Rendering does not emit mode changes.

set_explicit_width t b enables or disables explicit-width OSC emission for graphemes. When enabled and the terminal supports it, OSC sequences specifying the exact width of multi-width characters are emitted to prevent terminal-side width mismatch.

set_cursor_position t ~row ~col sets the desired cursor coordinates. row and col are one-based terminal coordinates where (1, 1) is the top-left corner.

clear_cursor_position t clears any requested cursor position so the cursor remains wherever the diff body last moved it.

set_cursor_style t ~style ~blinking sets the cursor's visual shape and blinking behaviour.

set_cursor_color t ~r ~g ~b sets the cursor colour via OSC 12. Components outside [0; 255] are clamped.

reset_cursor_color t restores the terminal's default cursor colour.

The type for cursor state snapshots.

cursor_info t is the current desired cursor state.

apply_capabilities t ~explicit_width ~explicit_cursor_positioning ~hyperlinks applies terminal capability flags to t.

• explicit_width: whether the terminal supports explicit-width OSC sequences.
• explicit_cursor_positioning: whether to reposition the cursor after wide graphemes as a fallback when explicit_width is false. Prevents column drift in terminals that miscalculate grapheme display widths.
• hyperlinks: whether the terminal supports OSC 8 hyperlinks.

set_width_method t m sets the grapheme width computation method on both the current and next buffers. Use this after capability changes that affect width calculation to keep buffers consistent across swaps.

resize t ~width ~height resizes all internal buffers to width x height. Grid contents are preserved where dimensions overlap; hit grids are cleared.

Raises Invalid_argument if width <= 0 or height <= 0.

Note. Normally unnecessary -- build resizes automatically.

reset t clears the next buffer, empties hit grids, zeros statistics, and resets frame timing. The current buffer (diff baseline) is left intact so the next render can efficiently clear previously rendered content. Post-processors and configuration are preserved.

stats t is cumulative rendering statistics since creation or the last reset.

last_metrics t is the metrics for the most recent frame.

record_runtime_metrics t ~frame_callback_ms ~overall_frame_ms ~stdout_ms supplements the most recent metrics with runtime measurements. All values are in milliseconds. Intended for higher-level runtimes that measure draw-call duration, total wall-clock time, and output flush time on behalf of the screen.

grid t is t's next buffer grid.

Warning. Do not mutate the returned grid after the next render -- it becomes the diff baseline.

hit_grid t is t's next hit grid.

Warning. Do not mutate the returned hit grid after the next render -- it becomes the active hit grid for query_hit.

query_hit t ~x ~y is the element ID at (x, y) in the current hit grid (i.e. regions from the most recent render). Returns 0 if out of bounds or no region is registered.

set_row_offset t n sets the vertical origin offset applied to all subsequent renders. Negative values are clamped to zero. Useful for inline primary-screen rendering.

row_offset t is t's current vertical origin offset.

invalidate_presented t clears the current buffer so the diff renderer treats all cells as changed on the next render.

Call this after physically erasing the terminal region to keep the renderer's baseline in sync with the actual terminal state.

Note. Does not emit any escape sequences.

active_height t is the number of rows containing non-blank content in the next buffer. Background-only cells (spaces) are ignored. Useful for sizing inline rendering regions.