Crate justerm_core

Expand description

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.
CommandLine: One executed shell command recovered from OSC-133 marks (#166), for screen-reader command navigation. The consumer jumps prompt-to-prompt over these and announces command + a success/fail signal from exit.
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.
LogicalLine: One soft-wrap-joined logical line touching the viewport.
MarkerId: A stable handle to a buffer line, handed out by Engine::add_marker (#118). Monotonic per engine. The consumer attaches a decoration to the id; the frame reports where the marker currently sits, and TermEvent::MarkerDisposed signals when its line has left the buffer.
MarkerLine: A marker’s absolute buffer line (#120 S3, v11). Unlike MarkerPosition, this is reported for EVERY live marker — on-screen or not — so a frame-mode consumer can place overview-ruler marks buffer-relatively (dividing by scrollback + rows), the whole point of a ruler being to show off-viewport anchors. The consumer joins id with its decoration registry; the ruler mark’s colour is the consumer’s (theme-agnostic), so no kind/exit rides here.
MarkerPosition: A marker projected onto the viewport (#118): its id, the row it sits on, and its kind (#159). Only markers visible in the current viewport are reported; an off-screen marker is omitted but still alive (death comes via MarkerDisposed, not absence — so the consumer can tell “scrolled away” from “gone”). The kind carries the OSC 133 command-boundary role + exit code so the consumer can drive prompt-to-prompt navigation and success/fail signals (#160).
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).
MouseEvents: The mouse event categories the active tracking mode reports (#129) — the routing mask the frame carries so a frame-mode consumer sends an event to the app (a wanted bit set) or keeps it local (selection/scrollback). It is the single source encode_mouse’s restriction shares, so the wire mask and the encode-time gate cannot drift.
Overlay: Interaction overlays projected onto the viewport (#108): highlight spans the engine carries on the frame so a frame-mode consumer can paint them without an in-process model query. Positions only — highlight colour is the consumer’s (theme-agnostic). Coordinates are viewport rows/cols, re-projected by frame() against the scroll offset so the engine stays the single anchoring authority.
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).
SearchOptions: Search modes beyond the default literal + smart-case (see Term::search_with). Mirrors xterm.js’s ISearchOptions (#314). The default (all off / smart-case) is exactly Term::search.
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).
MarkerKind: What a marker means (#158). A plain add_marker decoration carries no semantics (MarkerKind::Plain); OSC 133 shell-integration marks carry the command-boundary role (prompt/command/output start, or command finished with its optional exit code). The engine only parses and anchors these — the success/failure colour, earcon and prompt-to-prompt navigation are consumer policy (ADR-0017), driven off the kind + exit the wire (#159) carries.
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.
is_valid_regex: Whether pattern is a regex Term::search_with can run (opts.regex = true) — a true guarantees search_with will build the pattern, and a false is exactly the case it silently swallows into an empty result (#316 D2).

Crate justerm_core

Crate justerm_core Copy item path

Structs§

Enums§

Constants§

Functions§

Crate justerm_core