Crate keymap_term 

keymap-term — capture schema and capability-aware decoder

keymap-rs is measurement first: before any capability-aware byte decoding is written, we record what real terminals actually send. This crate defines the on-disk schema for those recordings (Capture) plus the lossless hex codec used to store raw bytes safely in TOML.

A capture is provenance-bearing ground truth: which terminal, whether tmux or SSH was in the path, when it was taken, what each key produced on the wire, and how each capability value was learned. Captures live under captures/, one file per terminal/session, and are the fixtures the decoder is validated against. The interactive recorder is the keymap-probe binary.

The decode function turns recorded bytes back into keymap_core::KeyInput under a DecodeMode, returning a Decoded outcome. It is a pure, state-free function built only from the byte shapes the committed captures contain (baseline and kitty-enhanced today).

On top of it, reachability reports empirical per-terminal reachability: for one Capture it enumerates which recorded chords actually arrive as themselves (the empirical refinement of keymap_core::legacy_form’s static lower bound). This crate carries no terminal-I/O dependencies.

Headless verification

There is no examples/ directory for this crate; the decoder is verified against the committed captures/*.toml fixtures by tests/decode_fixtures.rs, tests/capture_invariants.rs, and tests/reachability_fixtures.rs (cargo test -p keymap-term). New decoder behaviour is added by extending the captures, not by writing speculative byte shapes.

Structs

Capability

One observed terminal capability.

Capture

A single recording session against one terminal environment.

KeyPress

One recorded keypress: what the operator intended versus what arrived.

Meta

Where and when a Capture was taken — the index used to tell captures apart and to judge when one has gone stale.

ParseHexError

Error returned when a hex string in a capture cannot be decoded.

Enums

DecodeMode

Which terminal key-encoding mode produced the bytes being decoded.

Decoded

The outcome of decoding the front of a byte slice.

Provenance

How a capability value was learned. The same value is worth far less if it came from an environment-variable guess than from a query response.

Reachability

The empirical reachability verdict for one recorded chord on one terminal.

Functions

decode

Decodes the first complete key press at the front of bytes, read under the given DecodeMode. See the module docs for the contract.

from_hex

Decodes hex strings produced by to_hex back into bytes.

reachability

Enumerates the empirical reachability of every chord capture recorded.

to_hex

Encodes bytes as lowercase two-digit hex strings (0x1b -> "1b").