Crate justerm_core 

justerm-core — the pure terminal engine of the justerm family.

Feed VT bytes in; read terminal state out. The engine does no I/O, no IPC, no rendering, and is theme-agnostic (it stores colour references, never hex). See CLAUDE.md for the boundary invariants and docs/architecture.md for the full contract.

use justerm_core::{Color, Engine};

let mut term = Engine::new(80, 24);
term.feed(b"\x1b[31mhi\x1b[0m");
assert_eq!(term.grid().cell(0, 0).c(), 'h');
assert_eq!(term.grid().cell(0, 0).fg(), Color::Indexed(1));

Structs

Cell

One character position: a base glyph, fg/bg colour references, and flags. Combining marks (#45) and an OSC 8 hyperlink (#46) attach via per-row maps, signalled by the COMBINED_PRESENT / LINK_PRESENT bits — the cell itself is three packed words, no Option field. All access is through the accessor seam (#44); construct with Cell::from_parts or Cell::default.

CellFlags

Per-cell flags: the standard SGR attributes plus layout markers.

Cursor

The input position, its pending-wrap state, and the current pen.

Engine

The terminal engine: pairs the vte parser with our state model.

Frame

One serialized damage cycle: the decoded logical form that encode/decode round-trip. side_table holds this frame’s grapheme clusters (referenced by each cell’s frame-local extra); link_table holds its OSC 8 hyperlink URIs (referenced by each cell’s frame-local link).

Grid

The current screen: rows × cols cells.

KeyEvent

A key event: a key, the modifiers held with it, its press/repeat/release type (defaults to Press), and consumer-supplied extras the kitty protocol’s alternate-keys / associated-text flags report (all None for legacy).

LineDamage

The damaged column span of a single line.

Match

One literal match, inclusive on both ends, in absolute buffer coordinates.

Modifiers

Modifier keys held during an event. The bit values follow the kitty scheme (the superset): Shift=1, Alt=2, Ctrl=4, Super=8, Hyper=16, Meta=32, CapsLock=64, NumLock=128. Legacy xterm can only express the first three plus Meta-at-8, so csi_param remaps; kitty uses the bits directly (#23).

MouseEvent

A mouse event in viewport cell coordinates (0-based — the encoding shifts to 1-based on the wire).

Pen

The current SGR state — the appearance copied into each printed cell.

Row

One row of cells plus its per-row, column-keyed combining and link maps.

ScrollOp

A first-class scroll: rows [top..=bottom] shifted by count lines (positive = up, negative = down). The renderer moves the rows instead of redrawing them. Recorded by the engine — which executes the scroll — rather than diff-detected (ADR-0003).

SelectionSpan

One highlighted run on a single viewport row: columns left..=right (both inclusive). selection_range returns one per visible row the selection touches — the renderer paints these. Off-screen rows are not emitted.

Span

A damaged column run on one line, with its cells.

Term

Owns the authoritative screen state and applies VT actions to it.

Enums

Color

A cell’s foreground or background colour, stored as a reference.

CursorShape

The cursor’s drawn shape (DECSCUSR / the renderer’s caret glyph). The engine reports it on the frame; the renderer draws it. Default Block (#81).

DecodeError

Why a byte buffer could not be decoded into a Frame.

FrameKind

Whether a frame redraws everything or just its spans.

Key

A logical key press from the consumer (already decoded from the platform’s keyboard event — justerm does not read hardware).

KeyAction

Press / repeat / release. Legacy reports only presses; the kitty protocol’s “report event types” flag (bit 1) carries repeat and release too (#23).

KeypadKey

A numeric-keypad key. In application-keypad mode (DECNKM ?66 / DECKPAM, #74) these encode as the classic VT100/VT220 SS3 sequences; in numeric mode as the literal character. The consumer produces these for raw keypad identity — it owns NumLock / key-location resolution (#83).

MouseAction

What the mouse did.

MouseButton

Which mouse button an event concerns. None on a MouseEvent means bare motion with no button held.

SelectionType

What a selection covers.

Side

Which half of a cell an anchor sits on — the left or right edge. Lets a drag include or exclude the cell under the pointer (mouse precision).

TermDamage

What changed since the last reset_damage().

TermEvent

A consumer-facing event emitted while parsing the VT stream.

Constants

CELL_RECORD_LEN

Length in bytes of one fixed-width wire cell record (see encode_cell_record).

WIRE_VERSION

The wire-format version (the gating VERSION byte), exposed so a binding can assert at load that its decoder matches the backend encoder (#34/ADR-0008).

Functions

decode

Deserialize the binary wire format back into a Frame.

encode

Serialize a frame to the binary wire format.

encode_cell_record

Encode one Cell to its fixed 18-byte little-endian record: c u32 (Unicode scalar) · fg u32 · bg u32 · flags u16 · extra u16 (frame-local grapheme index, 0 = none) · link u16 (frame-local hyperlink index, 0 = none). Width derives from flags.

encode_color

A colour reference as a tagged u32: high byte = tag (0 = Default, 1 = Indexed, 2 = Rgb), low 24 bits = payload. The tag is mandatory so Default, Indexed(0), and Rgb(0,0,0) stay distinct.