The type for mutable cell grids.

The type for rectangular areas in cell coordinates. Covers cells satisfying x <= col < x + width and y <= row < y + height. Non-positive width or height yields an empty region.

create ~width ~height () is a grid with all cells set to spaces (white foreground, transparent background) with:

• glyph_pool shared grapheme storage. A fresh pool is allocated if omitted.
• width_method grapheme width method. Defaults to `Unicode.
• respect_alpha alpha blending on set_cell. Defaults to false.

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

width g is the grid width in cells.

height g is the grid height in cells.

glyph_pool g is the glyph pool used by g.

width_method g is the current width computation method.

set_width_method g m changes the width method for subsequent draw_text calls. Existing cell widths are not updated.

respect_alpha g is true iff alpha blending is enabled for set_cell and blit_region.

set_respect_alpha g b sets the alpha blending mode.

active_height g is the number of rows from the top containing non-blank content (character code other than 0 or space). Returns 0 for an empty or cleared grid.

idx g ~x ~y is the flat index for cell (x, y). No bounds checking.

get_code g idx is the cell code at idx.

get_glyph g idx is the glyph at idx.

get_attrs g idx is the packed attribute integer at idx.

get_link g idx is the internal hyperlink ID at idx.

Foreground RGBA components at idx, in [0.0, 1.0].

Background RGBA components at idx, in [0.0, 1.0].

get_text g idx is the grapheme at idx as a string. Returns "" for empty or continuation cells.

get_style g idx reconstructs the style at idx.

get_background g idx is the background color at idx.

is_empty g idx is true iff the cell is the null/empty glyph sentinel. Different from a blank space cell (Glyph.space), which is the default content after create and clear.

is_continuation g idx is true iff the cell is the trailing part of a wide character.

is_inline g idx is true iff the cell needs no glyph pool lookup (ASCII or single codepoint).

cell_width g idx is the display width of the cell (0 for empty/continuation, 1–2 for start).

cells_equal g1 idx1 g2 idx2 is true iff both cells have identical content and styling. Uses epsilon comparison for RGBA floats.

hyperlink_url g id resolves a link ID (from get_link) to a URL. Returns None for the no-link sentinel or unknown IDs.

hyperlink_url_direct g id is like hyperlink_url but returns "" instead of None.

resize g ~width ~height resizes the grid, preserving existing contents where possible. Cells outside the new bounds are released. No-op if dimensions are unchanged.

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

clear ~color g resets all cells to spaces with white foreground and color background. color defaults to transparent. Releases all glyph pool references. The scissor stack is preserved.

blit ~src ~dst copies all cell data from src to dst, resizing dst to match. When pools are shared, codes are copied verbatim. When pools differ, each distinct grapheme is re-interned once. No alpha blending.

copy g is a deep copy of g sharing the same glyph pool. The scissor stack starts empty on the copy.

blit_region ~src ~dst ~src_x ~src_y ~width ~height ~dst_x ~dst_y copies a rectangular region from src to dst.

The region is clamped to valid bounds in both grids. Negative coordinates shift the region inward. Respects the scissor on dst. Alpha blending occurs when dst's respect_alpha is true or source alpha < 1.0. Same-grid overlapping regions are handled correctly. Never resizes dst.

fill_rect g ~x ~y ~width ~height ~color fills a rectangle:

• Transparent (alpha ≈ 0): clears content, preserves existing background.
• Semi-transparent: blends over existing background.
• Opaque: overwrites entirely (space glyph, white foreground, color background).

Clipped to grid bounds and scissor.

draw_text ~style ~tab_width g ~x ~y ~text draws single-line text. Text is segmented into grapheme clusters using the current width_method. Wide characters occupy multiple cells with continuation markers. Newlines are skipped; tabs expand to tab_width spaces (default 2).

When the resolved background has alpha < 1.0, colors are blended with existing cells. A space on a translucent background preserves the existing glyph and tints its colors.

Respects the active scissor.

Box-drawing border character sets.

draw_box g ~x ~y ~width ~height () draws a box with Unicode borders and:

• border character set. Defaults to Border.single.
• sides to draw. Defaults to Border.all.
• style for border characters. Defaults to Ansi.Style.default.
• fill interior and border cell background color. When absent, no fill is applied.
• title on the top border when \`Top is included and width >= title_width + 4.
• title_alignment defaults to \`Left with 2-cell padding.
• title_style for the title text.

Respects the scissor.

The type for line drawing glyph sets.

Unicode box-drawing: "─", "│", "╱", "╲".

ASCII: "-", "|", "/", "\\".

draw_line g ~x1 ~y1 ~x2 ~y2 () draws a line using Bresenham's algorithm with:

• \`Line (default) uses box-drawing characters with per-step glyph selection based on direction.
• \`Braille uses 2×4 dot patterns that merge with existing braille cells, allowing multiple lines to share cells.

Respects the scissor.

set_cell g ~x ~y ~glyph ~fg ~bg ~attrs () writes a single cell. blend defaults to the grid's respect_alpha setting; pass ~blend:true to force blending.

Cells outside the grid or scissor are skipped. Existing wide graphemes spanning this cell are cleaned up. The caller is responsible for writing continuation cells for multi-column graphemes.

push_clip g r pushes a clipping region. The effective clip is the intersection of r with the current clip.

pop_clip g pops the most recent clip. No-op if the stack is empty.

clear_clip g removes all clipping regions.

clip g r f runs f () with r as the active clip, popping it on return (even on exception).

push_opacity g o pushes o (clamped to [0.0, 1.0]).

pop_opacity g pops the most recent opacity. No-op if the stack is empty.

current_opacity g is the product of all stacked opacities, or 1.0 if the stack is empty.

scroll g ~top ~bottom n scrolls rows [top..bottom] by n lines. Positive n scrolls content up (new blank lines at bottom). Negative n scrolls down. Zero is a no-op.

diff_cells prev curr is the (x, y) coordinates of cells that differ. Iterates over the union of both grids' dimensions. Uses epsilon comparison for RGBA. Sorted by row then column.

to_ansi ~reset g renders g to a string with full ANSI escape sequences. Appends a reset sequence when reset is true (default).