Module chord 

Renderer-neutral chord representation – the typed canonical form the keymap trie indexes by.

One KeyChord is one keypress: a KeyKind (a character or a named SpecialKey) plus KeyMods. A binding path is a sequence of them, written in vim notation and parsed by parse_chord_sequence; Display prints a chord back in the same notation, so parse → display → parse is the identity for every chord the parser can produce (except <F13>.. <F24>; see special_label).

Examples

use lattice_protocol::{KeyChord, KeyKind, KeyMods, SpecialKey, parse_chord_sequence};

let seq = parse_chord_sequence("<C-w>j<Esc>").unwrap();
assert_eq!(
    seq,
    vec![
        KeyChord::ctrl('w'),
        KeyChord::char('j'),
        KeyChord::special(SpecialKey::Esc),
    ]
);

// Round-trip through the canonical spelling.
let text: String = seq.iter().map(ToString::to_string).collect();
assert_eq!(text, "<C-w>j<Esc>");
assert_eq!(parse_chord_sequence(&text).unwrap(), seq);

// Shift on a letter folds into its case; on a named key it is kept.
assert_eq!(parse_chord_sequence("<S-a>").unwrap(), vec![KeyChord::char('A')]);
let shift_tab = KeyChord::new(KeyKind::Special(SpecialKey::Tab), KeyMods::SHIFT);
assert_eq!(shift_tab.to_string(), "<S-Tab>");

K.2.1 (2026-06-01): moved from lattice-host::chord into lattice-protocol, alongside the other renderer-neutral wire types (Position, Edit, Selection, …). The substrate sits at the dependency floor so any crate that constructs a binding – including mode crates like lattice-multibuffer that contribute keymaps via Mode::keymap() – can do so without depending on lattice-host. lattice-host::chord is retained as a re-export shim for one release cycle to avoid downstream churn.

Phase 5.4 split: every type + parser + formatter here is pure data. The crossterm-coupled side (KeyEvent → KeyChord conversion, format_chord for ratatui-driven describe-key output) lives in lattice-ui-tui::chord and reaches into the neutral types defined here. The future lattice-ui-gpui ships its own adapter from GPUI’s key event type into the same KeyChord without coordinating with the TUI’s adapter.

Notation conventions

Match the strings the keymap registry catalog uses:

• Bare printable char: "a", "$", "0". No angles.
• Modifier-only-Shift on a printable char: folded into the char ("A", not "<S-a>"). Shift on a non-character key keeps the prefix: "<S-Tab>", "<S-F1>".
• Ctrl: "<C-x>" – always lowercase letter, even if the keyboard reports it uppercase.
• Alt / Meta: "<M-x>" ("<A-x>" is accepted on input).
• Super / Cmd: "<D-x>".
• Combined modifiers in canonical order C, S, M, D: "<C-S-x>", "<C-M-x>". Input accepts them in any order; each at most once.
• Named special keys: <Esc>, <Tab>, <CR>, <BS>, <Up>, <Down>, <Left>, <Right>, <Home>, <End>, <PageUp>, <PageDown>, <Insert>, <Delete>, <F1>-<F12>, <Space>. Input also accepts the aliases <Escape>, <Enter>, <Return>, <Backspace>, <Ins>, <Del> and <F13>-<F24>.
• An unmodified <Space> is the space character (Char(' ')), and prints as <Space>; a modified one (<C-Space>) is the special key.
• Literal < types as <lt> (vim convention) so the parser reading these strings can disambiguate.

Structs

KeyChord

Canonical, stack-allocated representation of one chord.

KeyMods

Modifier bitfield. Copy + Eq + Hash so the whole KeyChord fits in a CPU register.

Enums

ChordParseError

Parse-side error variants. Detail-level so :bind-style error messages can surface what was wrong.

ChordPattern

One element of a keymap registration path.

KeyKind

What kind of key the chord represents.

SpecialKey

Named special keys. Renderer-neutral; crossterm’s KeyCode::BackTab is normalised away by the TUI adapter (from_crossterm) into Special(Tab) + KeyMods::SHIFT so the trie has one entry for “shift-tab” rather than two ambiguous ones.

Functions

last_chord_token_byte_len

Number of bytes the last chord token occupies at the end of text, treating it as a sequence of chord tokens (one chord per logical keypress). Used by chord-capture’s backspace handler to remove a whole token instead of a single char.

parse_chord_sequence

Parse a chord-sequence string into the canonical Vec<KeyChord> the keymap trie indexes by.

special_label

Canonical name for a SpecialKey. Round-trips through parse_special. Renderer-neutral text; both the TUI’s format_chord and any future GPUI describe-key renderer use this label.