lattice_protocol/

chord.rs

//! 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.

use std::fmt;
use std::str::FromStr;

/// Canonical, stack-allocated representation of one chord.
///
/// `Copy` so call sites can pass it freely without lifetime
/// gymnastics; `Hash` + `Eq` so it works as a `HashMap` key in
/// the keymap trie. Memory: 8 bytes (1-byte mod bitfield + 1-byte
/// discriminant + a 4-byte char or 1-byte SpecialKey, padded).
///
/// Parse one chord with `str::parse` (`FromStr`), a sequence with
/// [`parse_chord_sequence`]; `Display` writes the canonical notation.
///
/// # Examples
///
/// ```
/// use lattice_protocol::{ChordParseError, KeyChord, KeyKind, KeyMods, SpecialKey};
///
/// let chord: KeyChord = "<C-S-Tab>".parse().unwrap();
/// assert_eq!(chord.key, KeyKind::Special(SpecialKey::Tab));
/// assert_eq!(chord.mods, KeyMods::CTRL | KeyMods::SHIFT);
/// assert_eq!(chord.to_string(), "<C-S-Tab>");
///
/// // `<` and a bare space are escaped when printed.
/// assert_eq!(KeyChord::char('<').to_string(), "<lt>");
/// assert_eq!(KeyChord::char(' ').to_string(), "<Space>");
///
/// // `FromStr` wants exactly one chord.
/// assert!(matches!("ab".parse::<KeyChord>(), Err(ChordParseError::BodyTooLong { .. })));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KeyChord {
    /// Which key was pressed.
    pub key: KeyKind,
    /// Modifiers held with it. For a letter, Shift is encoded in the case of
    /// [`KeyKind::Char`] instead, so this carries no SHIFT bit.
    pub mods: KeyMods,
}

/// What kind of key the chord represents.
///
/// `Char` covers printable characters and Ctrl/Alt-modified chars
/// (the modifier lives in `mods`). For *letters* the case
/// encodes shift (vim convention: `A` is shift+a; we don't carry
/// `KeyMods::SHIFT` for plain letters). For non-letter chars
/// (`$`, `0`, `<`, ...) the case is the only valid form.
///
/// `Special` covers named keys (`Esc`, `Enter`, `Tab`, `Up`, ...)
/// where shift IS carried separately because `<S-Tab>` is a
/// genuinely different chord from `<Tab>`.
///
/// Function keys live in `Special::F(u8)` rather than as their
/// own enum variant to keep the type compact; `1..=24` covers
/// every reasonable terminal.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum KeyKind {
    /// A character key: the character it produces (already shifted, so `A`
    /// or `$`, never `a`+Shift or `4`+Shift).
    Char(char),
    /// A named, non-character key.
    Special(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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SpecialKey {
    /// Escape — `<Esc>`.
    Esc,
    /// Return / Enter — `<CR>`.
    Enter,
    /// Tab — `<Tab>`; Shift-Tab is this plus [`KeyMods::SHIFT`].
    Tab,
    /// Backspace — `<BS>`.
    Backspace,
    /// Space *with a modifier* (`<C-Space>`). A bare space is
    /// `KeyKind::Char(' ')`; see the module notes.
    Space,
    /// Arrow up — `<Up>`.
    Up,
    /// Arrow down — `<Down>`.
    Down,
    /// Arrow left — `<Left>`.
    Left,
    /// Arrow right — `<Right>`.
    Right,
    /// Home — `<Home>`.
    Home,
    /// End — `<End>`.
    End,
    /// Page Up — `<PageUp>`.
    PageUp,
    /// Page Down — `<PageDown>`.
    PageDown,
    /// Insert — `<Insert>`.
    Insert,
    /// Forward delete — `<Delete>`.
    Delete,
    /// Function keys F1..=F24. `F(0)` is reserved (invalid).
    F(u8),
}

/// Modifier bitfield. `Copy + Eq + Hash` so the whole `KeyChord`
/// fits in a CPU register.
///
/// The raw `u8` is public for adapters; prefer the named constants, which
/// combine with `|` (or [`Self::with`]).
///
/// # Examples
///
/// ```
/// use lattice_protocol::KeyMods;
///
/// let mods = KeyMods::CTRL | KeyMods::ALT;
/// assert!(mods.ctrl() && mods.alt() && !mods.shift());
/// assert_eq!(mods.without(KeyMods::ALT), KeyMods::CTRL);
/// assert!(KeyMods::NONE.is_empty());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct KeyMods(pub u8);

impl KeyMods {
    /// No modifiers.
    pub const NONE: Self = Self(0);
    /// Control — `C-` in notation.
    pub const CTRL: Self = Self(1 << 0);
    /// Shift — `S-` in notation (only carried for non-letter keys).
    pub const SHIFT: Self = Self(1 << 1);
    /// Alt / Meta — `M-` in notation.
    pub const ALT: Self = Self(1 << 2);
    /// Super / Cmd / Windows — `D-` in notation.
    pub const SUPER: Self = Self(1 << 3);

    /// Whether Control is held.
    #[inline]
    pub const fn ctrl(self) -> bool {
        self.0 & Self::CTRL.0 != 0
    }
    /// Whether Shift is held.
    #[inline]
    pub const fn shift(self) -> bool {
        self.0 & Self::SHIFT.0 != 0
    }
    /// Whether Alt / Meta is held.
    #[inline]
    pub const fn alt(self) -> bool {
        self.0 & Self::ALT.0 != 0
    }
    /// Whether Super is held. (Trailing underscore: `super` is a keyword.)
    #[inline]
    pub const fn super_(self) -> bool {
        self.0 & Self::SUPER.0 != 0
    }
    /// Whether no modifier is held.
    #[inline]
    pub const fn is_empty(self) -> bool {
        self.0 == 0
    }

    /// Add `other`'s modifiers (a `const` spelling of `self | other`).
    #[inline]
    pub const fn with(self, other: Self) -> Self {
        Self(self.0 | other.0)
    }

    /// Strip a modifier (used by renderer adapters to clear the
    /// redundant SHIFT bit on bare printable chars where the
    /// terminal already encoded shift in the case / shifted
    /// symbol).
    #[inline]
    pub const fn without(self, other: Self) -> Self {
        Self(self.0 & !other.0)
    }
}

impl std::ops::BitOr for KeyMods {
    type Output = Self;
    #[inline]
    fn bitor(self, rhs: Self) -> Self {
        Self(self.0 | rhs.0)
    }
}

/// Parse-side error variants. Detail-level so `:bind`-style error
/// messages can surface what was wrong.
///
/// Every `at` is the byte offset, in the string handed to the parser, of the
/// token that failed — the `<` of an angle token, or the character itself.
///
/// # Examples
///
/// ```
/// use lattice_protocol::{ChordParseError, parse_chord_sequence};
///
/// assert_eq!(parse_chord_sequence(""), Err(ChordParseError::Empty));
/// assert_eq!(
///     parse_chord_sequence("g<C-w"),
///     Err(ChordParseError::UnterminatedAngle { at: 1 })
/// );
/// assert!(matches!(
///     parse_chord_sequence("<Foo>"),
///     Err(ChordParseError::UnknownName { .. })
/// ));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ChordParseError {
    /// String was empty.
    Empty,
    /// `<...>` token had no closing `>`.
    UnterminatedAngle {
        /// Byte offset of the unclosed `<`.
        at: usize,
    },
    /// `<...>` token body was empty (`<>`).
    EmptyAngle {
        /// Byte offset of the `<`.
        at: usize,
    },
    /// `<...>` body referenced an unknown name (`<Foo>`, `<F99>`,
    /// `<C-S-X>` where the body chunk after modifiers is
    /// unrecognised).
    UnknownName {
        /// The unrecognised name, modifiers stripped (`Foo`).
        name: String,
        /// Byte offset of the token's `<`.
        at: usize,
    },
    /// Modifier prefix (`C-`, `S-`, `M-`) without a body (`<C->`).
    DanglingModifier {
        /// Byte offset of the token's `<`.
        at: usize,
    },
    /// The same modifier appeared twice in one token (`<C-C-x>`).
    DuplicateModifier {
        /// Byte offset of the token's `<`.
        at: usize,
    },
    /// Input that should be exactly one chord was longer. Raised only by
    /// `KeyChord::from_str`, for trailing input after the first chord
    /// (`"ab"`, `"<Esc>x"`); a multi-character body such as `<C-foo>`
    /// reports [`Self::UnknownName`] instead.
    BodyTooLong {
        /// The whole input string.
        name: String,
        /// Byte offset of the first chord (always 0).
        at: usize,
    },
    /// Sequence parser saw a stray `>` (no matching `<`).
    StrayClose {
        /// Byte offset of the `>`.
        at: usize,
    },
}

impl fmt::Display for ChordParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => write!(f, "empty chord string"),
            Self::UnterminatedAngle { at } => {
                write!(f, "unterminated `<...>` at byte {at}")
            }
            Self::EmptyAngle { at } => {
                write!(f, "empty `<>` at byte {at}")
            }
            Self::UnknownName { name, at } => {
                write!(f, "unknown chord name `{name}` at byte {at}")
            }
            Self::DanglingModifier { at } => {
                write!(f, "dangling modifier prefix at byte {at}")
            }
            Self::DuplicateModifier { at } => {
                write!(f, "duplicate modifier at byte {at}")
            }
            Self::BodyTooLong { name, at } => {
                write!(
                    f,
                    "body `{name}` after modifiers is not a single chord at byte {at}"
                )
            }
            Self::StrayClose { at } => {
                write!(f, "stray `>` at byte {at}")
            }
        }
    }
}

impl std::error::Error for ChordParseError {}

impl KeyChord {
    /// Build directly from kind + mods. Useful for tests +
    /// internal callers; production callers go through the
    /// renderer-specific adapter (`lattice_ui_tui::chord::from_event`
    /// for the TUI, the analogous function in the future GPUI
    /// adapter).
    #[inline]
    pub const fn new(key: KeyKind, mods: KeyMods) -> Self {
        Self { key, mods }
    }

    /// Plain printable character with no modifiers.
    #[inline]
    pub const fn char(c: char) -> Self {
        Self {
            key: KeyKind::Char(c),
            mods: KeyMods::NONE,
        }
    }

    /// Ctrl-modified character. Letter case is normalised by the
    /// caller; convention is lowercase (`<C-c>`, not `<C-C>`).
    #[inline]
    pub const fn ctrl(c: char) -> Self {
        Self {
            key: KeyKind::Char(c),
            mods: KeyMods::CTRL,
        }
    }

    /// Special key with no modifiers.
    #[inline]
    pub const fn special(k: SpecialKey) -> Self {
        Self {
            key: KeyKind::Special(k),
            mods: KeyMods::NONE,
        }
    }
}

/// One element of a keymap registration path.
///
/// `Literal` matches a specific chord; `CharLiteral` matches any
/// single bare-char chord (no modifiers). The wildcard captures
/// the matched char so the resulting [`crate::ids::CommandId`]
/// invocation can receive it (mark / register / find-char
/// targets all flow through this).
///
/// Lives in `lattice-protocol` alongside [`KeyChord`] because
/// mode crates (which contribute keymap bindings via
/// `Mode::keymap()`) need to construct paths without depending
/// on `lattice-host`. The matcher engine
/// (`KeymapTrie` / `KeymapLayer` / `BoundCommand`) stays in host:
/// it owns the lookup hot path, not the wire shape.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum ChordPattern {
    /// Matches exactly this chord.
    Literal(KeyChord),
    /// Matches any single unmodified character chord, capturing the char
    /// (the `{char}` of `m{char}`, `"{char}`, `f{char}`).
    CharLiteral,
}

impl fmt::Display for KeyChord {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Plain printable chars with no modifiers render bare, except the two
        // that cannot survive it: `<` escapes as `<lt>` so the parser can
        // round-trip without ambiguity, and a literal space escapes as
        // `<Space>` for the same reason plus a second one.
        //
        // The parser round-trip alone does hold for a bare `" "` —
        // `parse_chord_sequence(" ")` reads it back as `Char(' ')`. What does
        // NOT hold is every context that delimits on whitespace or asks a
        // human to read the result:
        //
        // - the `:` line. `:describe-key` captures chords by appending
        //   `Display` tokens to the command line, so a captured space
        //   appended `" "` and the ex-parser split the argument on it — the
        //   user pressed Space and got `describe-key` with no argument.
        // - every listing. `:map`, `:keymap`, which-key and describe-key's own
        //   "… is not bound" line rendered the leader as an INVISIBLE column.
        //   `<Space>ff` reads; ` ff` does not.
        //
        // The chord itself is unchanged — `Char(' ')`, what both decoders
        // produce for an unmodified space (see `parse_angle_body`). This is
        // only how it is spelled back out.
        if self.mods.is_empty()
            && let KeyKind::Char(c) = self.key
        {
            if c == '<' {
                return f.write_str("<lt>");
            }
            if c == ' ' {
                return f.write_str("<Space>");
            }
            return write!(f, "{c}");
        }

        f.write_str("<")?;
        if self.mods.ctrl() {
            f.write_str("C-")?;
        }
        if self.mods.shift() {
            f.write_str("S-")?;
        }
        if self.mods.alt() {
            f.write_str("M-")?;
        }
        if self.mods.super_() {
            f.write_str("D-")?;
        }
        match self.key {
            KeyKind::Char(c) => {
                // Ctrl/Alt-letter is rendered lowercase
                // (normalised by the renderer adapter); `<C-S-c>`
                // is distinct from `<C-c>` only by the explicit
                // S- prefix.
                write!(f, "{c}")?;
            }
            KeyKind::Special(s) => {
                f.write_str(special_label(s))?;
            }
        }
        f.write_str(">")
    }
}

/// 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.
///
/// The one exception to the round-trip: `F13`..=`F24` (and the invalid
/// `F(0)`) all render as `"F?"`, although the parser accepts `<F13>`..`<F24>`.
///
/// # Examples
///
/// ```
/// use lattice_protocol::{SpecialKey, special_label};
///
/// assert_eq!(special_label(SpecialKey::Enter), "CR");
/// assert_eq!(special_label(SpecialKey::F(5)), "F5");
/// ```
pub fn special_label(k: SpecialKey) -> &'static str {
    match k {
        SpecialKey::Esc => "Esc",
        SpecialKey::Enter => "CR",
        SpecialKey::Tab => "Tab",
        SpecialKey::Backspace => "BS",
        SpecialKey::Space => "Space",
        SpecialKey::Up => "Up",
        SpecialKey::Down => "Down",
        SpecialKey::Left => "Left",
        SpecialKey::Right => "Right",
        SpecialKey::Home => "Home",
        SpecialKey::End => "End",
        SpecialKey::PageUp => "PageUp",
        SpecialKey::PageDown => "PageDown",
        SpecialKey::Insert => "Insert",
        SpecialKey::Delete => "Delete",
        SpecialKey::F(1) => "F1",
        SpecialKey::F(2) => "F2",
        SpecialKey::F(3) => "F3",
        SpecialKey::F(4) => "F4",
        SpecialKey::F(5) => "F5",
        SpecialKey::F(6) => "F6",
        SpecialKey::F(7) => "F7",
        SpecialKey::F(8) => "F8",
        SpecialKey::F(9) => "F9",
        SpecialKey::F(10) => "F10",
        SpecialKey::F(11) => "F11",
        SpecialKey::F(12) => "F12",
        SpecialKey::F(_) => "F?", // 13..24; renderer-only fallback
    }
}

/// Inverse of `special_label`. Used by the parser when an
/// `<...>` body's modifier-stripped chunk is more than one
/// char (`<Esc>`, `<F12>`, etc.).
fn parse_special(name: &str) -> Option<SpecialKey> {
    Some(match name {
        "Esc" | "Escape" => SpecialKey::Esc,
        "CR" | "Enter" | "Return" => SpecialKey::Enter,
        "Tab" => SpecialKey::Tab,
        "BS" | "Backspace" => SpecialKey::Backspace,
        "Space" => SpecialKey::Space,
        "Up" => SpecialKey::Up,
        "Down" => SpecialKey::Down,
        "Left" => SpecialKey::Left,
        "Right" => SpecialKey::Right,
        "Home" => SpecialKey::Home,
        "End" => SpecialKey::End,
        "PageUp" => SpecialKey::PageUp,
        "PageDown" => SpecialKey::PageDown,
        "Insert" | "Ins" => SpecialKey::Insert,
        "Delete" | "Del" => SpecialKey::Delete,
        n if n.starts_with('F') => {
            let num: u8 = n[1..].parse().ok()?;
            if (1..=24).contains(&num) {
                SpecialKey::F(num)
            } else {
                return None;
            }
        }
        _ => return None,
    })
}

impl FromStr for KeyChord {
    type Err = ChordParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        // Single-chord parse: either one bare char or one
        // `<...>` token.
        let mut iter = s.char_indices();
        let (start, first) = iter.next().ok_or(ChordParseError::Empty)?;
        if first == '<' {
            let close_rel = s[start + 1..]
                .find('>')
                .ok_or(ChordParseError::UnterminatedAngle { at: start })?;
            let body_end = start + 1 + close_rel;
            let body = &s[start + 1..body_end];
            // Single-chord parse rejects trailing input -- the
            // caller is asking for ONE chord, not a sequence.
            if body_end + 1 != s.len() {
                return Err(ChordParseError::BodyTooLong {
                    name: s.to_string(),
                    at: start,
                });
            }
            return parse_angle_body(body, start);
        }
        // Bare char. Reject trailing input for the same reason.
        if iter.next().is_some() {
            return Err(ChordParseError::BodyTooLong {
                name: s.to_string(),
                at: start,
            });
        }
        Ok(KeyChord::char(first))
    }
}

/// Parse the body of an `<...>` token (without the angles).
/// Handles modifier prefixes (`C-`, `S-`, `M-`, `D-`), the
/// `lt` literal, special-key names, and bare letters.
fn parse_angle_body(body: &str, at: usize) -> Result<KeyChord, ChordParseError> {
    if body.is_empty() {
        return Err(ChordParseError::EmptyAngle { at });
    }
    if body == "lt" {
        return Ok(KeyChord::char('<'));
    }
    let mut mods = KeyMods::NONE;
    let mut rest = body;
    loop {
        // Each modifier prefix is exactly two bytes (`C-`,
        // `S-`, `M-`, `D-`). Walk them off the front.
        if rest.len() < 2 || rest.as_bytes()[1] != b'-' {
            break;
        }
        let prefix = rest.as_bytes()[0];
        let m = match prefix {
            b'C' => KeyMods::CTRL,
            b'S' => KeyMods::SHIFT,
            b'M' | b'A' => KeyMods::ALT,
            b'D' => KeyMods::SUPER,
            _ => break,
        };
        if mods.0 & m.0 != 0 {
            return Err(ChordParseError::DuplicateModifier { at });
        }
        mods = mods | m;
        rest = &rest[2..];
    }
    if rest.is_empty() {
        return Err(ChordParseError::DanglingModifier { at });
    }
    // After modifiers: either a single char or a special-key name.
    let mut chars = rest.chars();
    let first = chars.next().expect("rest non-empty checked above");
    if chars.next().is_none() {
        // Single char body. Letters with Ctrl / Alt normalise to
        // lowercase to match the adapter's canonical form. Plain
        // shift on a letter folds into the case (`<S-a>` -> `A`).
        if mods.ctrl() || mods.alt() {
            return Ok(KeyChord {
                key: KeyKind::Char(first.to_ascii_lowercase()),
                mods,
            });
        }
        if mods.shift() && first.is_ascii_alphabetic() {
            // <S-a> = `A`; strip shift.
            mods = KeyMods(mods.0 & !KeyMods::SHIFT.0);
            return Ok(KeyChord {
                key: KeyKind::Char(first.to_ascii_uppercase()),
                mods,
            });
        }
        return Ok(KeyChord {
            key: KeyKind::Char(first),
            mods,
        });
    }
    // Multi-char body -- must be a special-key name.
    let special = parse_special(rest).ok_or_else(|| ChordParseError::UnknownName {
        name: rest.to_string(),
        at,
    })?;
    // **An UNMODIFIED `<Space>` is the literal character, not the special key.**
    //
    // Both key decoders already apply exactly this rule — a bare space arrives
    // as `Char(' ')` and only a modified one becomes `Special(Space)` (TUI
    // `chord::from_event`, GPUI `gpui_chord::from_event`). The parser did not,
    // so the two spellings of the same keypress disagreed and anything bound
    // via the string `<Space>` could never be typed.
    //
    // That is not hypothetical: the DEFAULT `keymap.leader` is `<Space>`, and
    // `<leader>` is substituted at BIND time, so every `<leader>x` binding in
    // the editor landed under `Special(Space)` while the keyboard produced
    // `Char(' ')`. The entire leader keymap was unreachable.
    //
    // Normalising here rather than at each decoder is what makes it stay
    // fixed: the parser is the one path every plugin binding, user keymap and
    // `:map` command shares, and both renderers already agree with each other.
    // `<S-Space>` / `<C-Space>` are untouched — a modifier still means the
    // special key, because a modified space is not text.
    if special == SpecialKey::Space && mods.is_empty() {
        return Ok(KeyChord {
            key: KeyKind::Char(' '),
            mods,
        });
    }
    Ok(KeyChord {
        key: KeyKind::Special(special),
        mods,
    })
}

/// Parse a chord-sequence string into the canonical
/// `Vec<KeyChord>` the keymap trie indexes by.
///
/// Examples:
///
/// - `"j"` -> `[char('j')]`
/// - `"gg"` -> `[char('g'), char('g')]`
/// - `"<C-w>j"` -> `[ctrl('w'), char('j')]`
/// - `"dw"` -> `[char('d'), char('w')]`
/// - `"<lt>"` -> `[char('<')]`
///
/// Used by:
/// - The `keymap_entry!` macro at startup to convert the
///   catalog's `&'static str` chord into the trie's typed key.
/// - `:bind` user / plugin invocations that take a
///   chord-string at runtime.
///
/// `<leader>` is *not* understood here: it is substituted before parsing, at
/// bind time, by the keymap layer.
///
/// # Errors
///
/// A [`ChordParseError`] naming the first bad token; the empty string is
/// [`ChordParseError::Empty`].
///
/// # Examples
///
/// ```
/// use lattice_protocol::{KeyChord, parse_chord_sequence};
///
/// assert_eq!(
///     parse_chord_sequence("gg").unwrap(),
///     vec![KeyChord::char('g'), KeyChord::char('g')]
/// );
/// // Ctrl letters normalise to lowercase; `<lt>` is a literal `<`.
/// assert_eq!(parse_chord_sequence("<C-W>").unwrap(), vec![KeyChord::ctrl('w')]);
/// assert_eq!(parse_chord_sequence("<lt>").unwrap(), vec![KeyChord::char('<')]);
/// // An unmodified <Space> is the space character.
/// assert_eq!(parse_chord_sequence("<Space>f").unwrap()[0], KeyChord::char(' '));
/// ```
pub fn parse_chord_sequence(s: &str) -> Result<Vec<KeyChord>, ChordParseError> {
    if s.is_empty() {
        return Err(ChordParseError::Empty);
    }
    let mut out = Vec::new();
    let mut i = 0;
    let bytes = s.as_bytes();
    while i < bytes.len() {
        if bytes[i] == b'<' {
            // Walk to matching `>`. Brackets don't nest in
            // chord notation.
            let close = match s[i + 1..].find('>') {
                Some(rel) => i + 1 + rel,
                None => return Err(ChordParseError::UnterminatedAngle { at: i }),
            };
            let body = &s[i + 1..close];
            out.push(parse_angle_body(body, i)?);
            i = close + 1;
        } else if bytes[i] == b'>' {
            return Err(ChordParseError::StrayClose { at: i });
        } else {
            // One UTF-8 char. Walk to the next char boundary.
            let ch_len = utf8_char_len(bytes[i]);
            let end = i + ch_len;
            let ch = s[i..end].chars().next().expect("valid utf-8 boundary");
            out.push(KeyChord::char(ch));
            i = end;
        }
    }
    Ok(out)
}

/// UTF-8 byte length of the leading char given its first byte.
/// Returns 1 for ASCII / continuation bytes (defensive; the
/// caller has already checked it's a leading byte).
#[inline]
fn utf8_char_len(b: u8) -> usize {
    if b < 0x80 {
        1
    } else if b & 0b1110_0000 == 0b1100_0000 {
        2
    } else if b & 0b1111_0000 == 0b1110_0000 {
        3
    } else if b & 0b1111_1000 == 0b1111_0000 {
        4
    } else {
        1
    }
}

/// 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.
///
/// A token is either:
/// - A `<…>` group (matched balanced angle brackets).
/// - A single character.
///
/// Returns 0 if `text` is empty.
///
/// # Examples
///
/// ```
/// use lattice_protocol::last_chord_token_byte_len;
///
/// assert_eq!(last_chord_token_byte_len("gg<C-w>"), 5); // "<C-w>"
/// assert_eq!(last_chord_token_byte_len("<C-w>é"), 2); // one 2-byte char
/// assert_eq!(last_chord_token_byte_len(""), 0);
/// ```
pub fn last_chord_token_byte_len(text: &str) -> usize {
    let bytes = text.as_bytes();
    let n = bytes.len();
    if n == 0 {
        return 0;
    }
    if bytes[n - 1] == b'>' {
        // Walk back to the matching `<`. Brackets don't nest in
        // chord notation (no `<<…>>`), so a simple scan suffices.
        let mut i = n;
        while i > 0 {
            i -= 1;
            if bytes[i] == b'<' {
                return n - i;
            }
        }
        // Unbalanced `>` -- treat as a single-byte token.
        return 1;
    }
    // Plain char token. UTF-8 safe: walk back to a char boundary.
    let mut i = n - 1;
    while i > 0 && (bytes[i] & 0b1100_0000) == 0b1000_0000 {
        i -= 1;
    }
    n - i
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used)]
    use super::*;

    /// **A bare `<Space>` parses to the literal char, not the special key.**
    ///
    /// Both key decoders produce `Char(' ')` for an unmodified space, so a
    /// parser that produced `Special(Space)` made the two spellings of one
    /// keypress disagree — and nothing bound as `<Space>` could be typed.
    ///
    /// The default `keymap.leader` IS `<Space>` and `<leader>` is substituted
    /// at bind time, so this made the whole leader keymap unreachable.
    #[test]
    fn a_bare_space_parses_to_the_literal_char() {
        let seq = parse_chord_sequence("<Space>").unwrap();
        assert_eq!(seq.len(), 1);
        assert_eq!(seq[0].key, KeyKind::Char(' '));
        assert!(seq[0].mods.is_empty());
    }

    /// The leader sequence a `<leader>oa` binding actually lands under.
    #[test]
    fn a_leader_sequence_parses_as_a_typeable_space_then_letters() {
        let seq = parse_chord_sequence("<Space>oa").unwrap();
        assert_eq!(
            seq.iter().map(|c| c.key).collect::<Vec<_>>(),
            vec![KeyKind::Char(' '), KeyKind::Char('o'), KeyKind::Char('a')],
            "every element must be what the keyboard produces: {seq:?}"
        );
    }

    /// A MODIFIED space is still the special key — a modified space is not
    /// text, and `<C-Space>` must keep matching what the decoders now build.
    #[test]
    fn a_modified_space_stays_the_special_key() {
        for spelling in ["<C-Space>", "<S-Space>", "<A-Space>"] {
            let seq = parse_chord_sequence(spelling).unwrap();
            assert_eq!(
                seq[0].key,
                KeyKind::Special(SpecialKey::Space),
                "{spelling} keeps the special key"
            );
            assert!(!seq[0].mods.is_empty(), "{spelling} keeps its modifier");
        }
    }

    /// `<Space>` must survive a Display→parse round trip, and must survive it
    /// as a **visible, non-splitting** token.
    ///
    /// Display used to render the literal char as a bare `" "`. That
    /// round-tripped through `parse_chord_sequence` and through nothing else:
    /// the `:` line delimits arguments on whitespace, so `:describe-key`'s
    /// chord capture appended a space and submitted an empty argument; and a
    /// keymap listing rendered the leader as an invisible column.
    ///
    /// So the assertion is two-part on purpose. Round-tripping alone is what
    /// the old spelling already satisfied, which is why it survived.
    #[test]
    fn a_space_chord_round_trips_through_display() {
        let parsed = parse_chord_sequence("<Space>oa").unwrap();
        let rendered: String = parsed.iter().map(|c| c.to_string()).collect();
        assert_eq!(
            parse_chord_sequence(&rendered).unwrap(),
            parsed,
            "rendered as {rendered:?}"
        );
        assert_eq!(
            rendered, "<Space>oa",
            "the leader must render as a token a human can see and a \
             whitespace-delimited parser will not split"
        );
        assert!(
            !rendered.contains(' '),
            "no rendered chord sequence may contain a raw space: {rendered:?}"
        );
    }

    /// A MODIFIED space keeps rendering through the modifier path, which
    /// already spelled it `<C-Space>`. The new escape must not double up.
    #[test]
    fn a_modified_space_still_renders_once() {
        let seq = parse_chord_sequence("<C-Space>").unwrap();
        assert_eq!(seq[0].to_string(), "<C-Space>");
    }

    #[test]
    fn keychord_display_round_trips_through_from_str() {
        // Pick representative chords across every shape:
        // bare char, Ctrl/Alt letters, multi-modifier, specials,
        // shift-special, function keys, the `<lt>` literal.
        let cases: &[KeyChord] = &[
            KeyChord::char('a'),
            KeyChord::char('$'),
            KeyChord::char('A'),
            KeyChord::ctrl('c'),
            KeyChord {
                key: KeyKind::Char('x'),
                mods: KeyMods::CTRL | KeyMods::SHIFT,
            },
            KeyChord {
                key: KeyKind::Char('q'),
                mods: KeyMods::ALT,
            },
            KeyChord::special(SpecialKey::Esc),
            KeyChord::special(SpecialKey::Enter),
            KeyChord::special(SpecialKey::Backspace),
            KeyChord {
                key: KeyKind::Special(SpecialKey::Tab),
                mods: KeyMods::SHIFT,
            },
            KeyChord::special(SpecialKey::F(1)),
            KeyChord::special(SpecialKey::F(12)),
            KeyChord::char('<'),
            KeyChord::char('>'),
        ];
        for c in cases {
            let s = c.to_string();
            let parsed: KeyChord = s
                .parse()
                .unwrap_or_else(|e| panic!("re-parse {s:?}: {e:?}"));
            assert_eq!(parsed, *c, "round-trip differs for {s:?}");
        }
    }

    #[test]
    fn parse_chord_sequence_walks_mixed_tokens() {
        let seq = parse_chord_sequence("<C-w>j").unwrap();
        assert_eq!(seq, vec![KeyChord::ctrl('w'), KeyChord::char('j')]);
    }

    #[test]
    fn parse_chord_sequence_handles_multi_key_built_in_chords() {
        assert_eq!(
            parse_chord_sequence("gg").unwrap(),
            vec![KeyChord::char('g'), KeyChord::char('g')]
        );
        assert_eq!(
            parse_chord_sequence("dw").unwrap(),
            vec![KeyChord::char('d'), KeyChord::char('w')]
        );
        assert_eq!(
            parse_chord_sequence("zt").unwrap(),
            vec![KeyChord::char('z'), KeyChord::char('t')]
        );
    }

    #[test]
    fn parse_chord_sequence_handles_lt_literal() {
        assert_eq!(
            parse_chord_sequence("<lt>").unwrap(),
            vec![KeyChord::char('<')]
        );
        // Mid-sequence too.
        assert_eq!(
            parse_chord_sequence("a<lt>b").unwrap(),
            vec![
                KeyChord::char('a'),
                KeyChord::char('<'),
                KeyChord::char('b')
            ]
        );
    }

    #[test]
    fn parse_chord_sequence_rejects_unterminated_angle() {
        assert!(matches!(
            parse_chord_sequence("<C-x"),
            Err(ChordParseError::UnterminatedAngle { .. })
        ));
    }

    #[test]
    fn parse_chord_sequence_rejects_stray_close() {
        assert!(matches!(
            parse_chord_sequence("a>b"),
            Err(ChordParseError::StrayClose { .. })
        ));
    }

    #[test]
    fn parse_chord_sequence_rejects_unknown_special() {
        assert!(matches!(
            parse_chord_sequence("<Foo>"),
            Err(ChordParseError::UnknownName { .. })
        ));
        assert!(matches!(
            parse_chord_sequence("<F99>"),
            Err(ChordParseError::UnknownName { .. })
        ));
    }

    #[test]
    fn parse_chord_sequence_rejects_dangling_modifier() {
        assert!(matches!(
            parse_chord_sequence("<C->"),
            Err(ChordParseError::DanglingModifier { .. })
        ));
    }

    #[test]
    fn parse_chord_sequence_rejects_duplicate_modifier() {
        assert!(matches!(
            parse_chord_sequence("<C-C-x>"),
            Err(ChordParseError::DuplicateModifier { .. })
        ));
    }

    #[test]
    fn parse_chord_sequence_accepts_uppercase_shifted_letter_via_s_prefix() {
        // `<S-a>` is a legacy form; canonicalises to `Char('A')`
        // (vim does the same).
        assert_eq!(
            parse_chord_sequence("<S-a>").unwrap(),
            vec![KeyChord::char('A')]
        );
    }

    #[test]
    fn last_chord_token_treats_angle_group_as_one_unit() {
        assert_eq!(last_chord_token_byte_len("<C-c>"), 5);
        assert_eq!(last_chord_token_byte_len("a<C-c>"), 5);
        assert_eq!(last_chord_token_byte_len("<Esc>"), 5);
    }

    #[test]
    fn last_chord_token_handles_plain_char() {
        assert_eq!(last_chord_token_byte_len("abc"), 1);
        assert_eq!(last_chord_token_byte_len("a"), 1);
    }

    #[test]
    fn last_chord_token_handles_empty() {
        assert_eq!(last_chord_token_byte_len(""), 0);
    }

    #[test]
    fn last_chord_token_handles_utf8_char() {
        // Two-byte UTF-8 char (é) should pop as one unit.
        assert_eq!(last_chord_token_byte_len("aé"), 2);
    }
}