feat(event): report the kitty protocol's base layout key

The kitty keyboard protocol's "report alternate keys" enhancement sends up to
two extra codepoints with each key: the shifted key and the base layout key -
the key at the same physical position on a standard PC-101 keyboard. The parser
read the shifted one (only when shift was held) and dropped the rest, so
applications had no way to match shortcuts by physical key: under a Cyrillic,
Greek or Hebrew layout every Ctrl+<letter> binding is dead, because the reported
character is the layout's, not the label's.

Parse both alternates positionally (either may be empty, e.g. `CSI 1076::108;5u`)
and expose the base layout key as `KeyEvent::base_layout_code`, alongside the
existing flag-gated `kind`/`state` fields.

The new field takes no part in `PartialEq`/`Hash`: it is metadata about the same
key press, and including it would silently break the ubiquitous
`event == KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL)` comparison as
soon as the enhancement is enabled. Existing behaviour, including the shifted-key
substitution, is unchanged - no existing test needed updating.

Closes #968.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

CHANGELOG.md

@@ -1,11 +1,22 @@
 # Unreleased
 
+## Added ⭐
+
+- Report the Kitty keyboard protocol's *base layout key* as
+  `KeyEvent::base_layout_code`, so shortcuts can be matched by physical key
+  regardless of the active keyboard layout (#968). Set only when
+  `KeyboardEnhancementFlags::REPORT_ALTERNATE_KEYS` is enabled.
+
 ## Breaking ⚠️
 
 - Raise the minimum supported Rust version from 1.63 to 1.85.
 - Remove `IsTty` trait.
   Use the standard library's [`std::io::IsTerminal`](https://doc.rust-lang.org/std/io/trait.IsTerminal.html) trait instead,
   which provides equivalent functionality.
+- `KeyEvent` gained a `base_layout_code` field: struct-literal construction and
+  exhaustive destructuring need updating. The `KeyEvent::new*` constructors,
+  `PartialEq` and `Hash` are unaffected — the new field takes no part in
+  equality, so comparisons against manually built events keep working.
 
 ## Changed ⚙️
 

src/event.rs

@@ -933,6 +933,24 @@ pub struct KeyEvent {
     /// Only set if [`KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES`] has been enabled with
     /// [`PushKeyboardEnhancementFlags`].
     pub state: KeyEventState,
+    /// The key at the same physical position on a standard PC-101 keyboard,
+    /// independent of the active keyboard layout.
+    ///
+    /// This is what makes layout-independent shortcuts possible: with a Cyrillic
+    /// layout active, the physical `C` key reports `KeyCode::Char('с')` in
+    /// [`code`](Self::code) and `Some(KeyCode::Char('c'))` here, so an
+    /// application can match `Ctrl+C` regardless of the layout the user types in.
+    ///
+    /// Only set if [`KeyboardEnhancementFlags::REPORT_ALTERNATE_KEYS`] has been
+    /// enabled with [`PushKeyboardEnhancementFlags`], and only on Unix — the
+    /// Windows console API does not report it.
+    ///
+    /// This field deliberately takes no part in [`PartialEq`]/[`Hash`], so that
+    /// comparing against a manually constructed event — the common
+    /// `event == KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL)`
+    /// pattern — keeps working once the enhancement is enabled.
+    #[cfg_attr(feature = "serde", serde(default))]
+    pub base_layout_code: Option<KeyCode>,
 }
 
 impl KeyEvent {
@@ -942,6 +960,7 @@ impl KeyEvent {
             modifiers,
             kind: KeyEventKind::Press,
             state: KeyEventState::empty(),
+            base_layout_code: None,
         }
     }
 
@@ -955,6 +974,7 @@ impl KeyEvent {
             modifiers,
             kind,
             state: KeyEventState::empty(),
+            base_layout_code: None,
         }
     }
 
@@ -969,9 +989,17 @@ impl KeyEvent {
             modifiers,
             kind,
             state,
+            base_layout_code: None,
         }
     }
 
+    /// Returns the event with [`base_layout_code`](Self::base_layout_code) set.
+    #[must_use = "this returns a new event instead of modifying the original"]
+    pub fn with_base_layout_code(mut self, base_layout_code: Option<KeyCode>) -> KeyEvent {
+        self.base_layout_code = base_layout_code;
+        self
+    }
+
     // modifies the KeyEvent,
     // so that KeyModifiers::SHIFT is present iff
     // an uppercase char is present.
@@ -1012,23 +1040,29 @@ impl From<KeyCode> for KeyEvent {
             modifiers: KeyModifiers::empty(),
             kind: KeyEventKind::Press,
             state: KeyEventState::empty(),
+            base_layout_code: None,
         }
     }
 }
 
 impl PartialEq for KeyEvent {
     fn eq(&self, other: &KeyEvent) -> bool {
+        // `base_layout_code` is metadata about the same key press, not part of
+        // its identity: including it would break `event == KeyEvent::new(...)`
+        // comparisons as soon as `REPORT_ALTERNATE_KEYS` is enabled.
         let KeyEvent {
             code: lhs_code,
             modifiers: lhs_modifiers,
             kind: lhs_kind,
             state: lhs_state,
+            base_layout_code: _,
         } = self.normalize_case();
         let KeyEvent {
             code: rhs_code,
             modifiers: rhs_modifiers,
             kind: rhs_kind,
             state: rhs_state,
+            base_layout_code: _,
         } = other.normalize_case();
         (lhs_code == rhs_code)
             && (lhs_modifiers == rhs_modifiers)
@@ -1041,11 +1075,14 @@ impl Eq for KeyEvent {}
 
 impl Hash for KeyEvent {
     fn hash<H: Hasher>(&self, hash_state: &mut H) {
+        // Excluded for the same reason as in `PartialEq`, and to keep `Hash`
+        // consistent with it.
         let KeyEvent {
             code,
             modifiers,
             kind,
             state,
+            base_layout_code: _,
         } = self.normalize_case();
         code.hash(hash_state);
         modifiers.hash(hash_state);

src/event/sys/unix/parse.rs

@@ -590,31 +590,50 @@ pub(crate) fn parse_csi_u_encoded_key_code(buffer: &[u8]) -> io::Result<Option<I
         }
     }
 
-    // When the "report alternate keys" flag is enabled in the Kitty Keyboard Protocol
-    // and the terminal sends a keyboard event containing shift, the sequence will
-    // contain an additional codepoint separated by a ':' character which contains
-    // the shifted character according to the keyboard layout.
+    // When the "report alternate keys" flag is enabled in the Kitty Keyboard Protocol,
+    // the first field carries up to two more codepoints separated by ':' characters:
+    // the shifted key and the base layout key, in that order. Either may be absent or
+    // empty (`CSI 1076::108;5u` reports a base layout key but no shifted key), so both
+    // are read positionally, before either is used.
+    let shifted_key = next_alternate_key(&mut codepoints);
+    let base_layout_key = next_alternate_key(&mut codepoints);
+
+    // The shifted key is the character the active layout produces with shift held, so
+    // it replaces the key code and consumes the modifier.
     if modifiers.contains(KeyModifiers::SHIFT) {
-        if let Some(shifted_c) = codepoints
-            .next()
-            .and_then(|codepoint| codepoint.parse::<u32>().ok())
-            .and_then(char::from_u32)
-        {
+        if let Some(shifted_c) = shifted_key {
             keycode = KeyCode::Char(shifted_c);
             modifiers.set(KeyModifiers::SHIFT, false);
         }
     }
 
-    let input_event = Event::Key(KeyEvent::new_with_kind_and_state(
-        keycode,
-        modifiers,
-        kind,
-        state_from_keycode | state_from_modifiers,
-    ));
+    let input_event = Event::Key(
+        KeyEvent::new_with_kind_and_state(
+            keycode,
+            modifiers,
+            kind,
+            state_from_keycode | state_from_modifiers,
+        )
+        // The base layout key is the key at the same physical position on a standard
+        // PC-101 keyboard, which lets applications match shortcuts by physical key
+        // regardless of the layout the user types in.
+        .with_base_layout_code(base_layout_key.map(KeyCode::Char)),
+    );
 
     Ok(Some(InternalEvent::Event(input_event)))
 }
 
+/// Reads the next `:`-separated alternate key of a `CSI u` key field.
+///
+/// Returns `None` when the alternate is absent or empty, which the Kitty Keyboard
+/// Protocol allows for any of them.
+fn next_alternate_key<'a>(codepoints: &mut impl Iterator<Item = &'a str>) -> Option<char> {
+    codepoints
+        .next()
+        .and_then(|codepoint| codepoint.parse::<u32>().ok())
+        .and_then(char::from_u32)
+}
+
 pub(crate) fn parse_csi_special_key_code(buffer: &[u8]) -> io::Result<Option<InternalEvent>> {
     assert!(buffer.starts_with(b"\x1B[")); // ESC [
     assert!(buffer.ends_with(b"~"));
@@ -864,10 +883,24 @@ pub(crate) fn parse_utf8_char(buffer: &[u8]) -> io::Result<Option<char>> {
 
 #[cfg(test)]
 mod tests {
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+
     use crate::event::{KeyEventState, KeyModifiers, MouseButton, MouseEvent};
 
     use super::*;
 
+    /// Parses a sequence that is expected to yield exactly one key event.
+    ///
+    /// Needed where a field is asserted directly instead of through
+    /// `assert_eq!` on the whole event, which compares by key identity only.
+    fn key_event(bytes: &[u8]) -> KeyEvent {
+        match parse_event(bytes, false).unwrap() {
+            Some(InternalEvent::Event(Event::Key(key))) => key,
+            other => panic!("expected a key event, got {:?}", other),
+        }
+    }
+
     #[test]
     fn test_esc_key() {
         assert_eq!(
@@ -1547,6 +1580,44 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_parse_csi_u_with_base_layout_key() {
+        // The physical `L` key pressed with ctrl on a Cyrillic layout: the layout
+        // reports `д` (U+0434), its shifted form is `Д` (U+0414), and the key at the
+        // same position on a PC-101 keyboard is `l` (U+006C).
+        let event = key_event(b"\x1B[1076:1044:108;5u");
+        assert_eq!(event.code, KeyCode::Char('\u{434}'));
+        assert_eq!(event.modifiers, KeyModifiers::CONTROL);
+        assert_eq!(event.base_layout_code, Some(KeyCode::Char('l')));
+
+        // The shifted key may be omitted while the base layout key is present.
+        let event = key_event(b"\x1B[1076::108;5u");
+        assert_eq!(event.code, KeyCode::Char('\u{434}'));
+        assert_eq!(event.base_layout_code, Some(KeyCode::Char('l')));
+
+        // Without the enhancement (or on a layout where the key is its own base),
+        // no alternates are reported.
+        assert_eq!(key_event(b"\x1B[97;5u").base_layout_code, None);
+        assert_eq!(key_event(b"\x1B[97:65;2u").base_layout_code, None);
+    }
+
+    #[test]
+    fn test_base_layout_key_does_not_affect_equality() {
+        // Applications compare against manually built events; reporting alternates
+        // must not break that, so the base layout key is not part of the identity.
+        let reported = key_event(b"\x1B[1076:1044:108;5u");
+        assert_eq!(
+            reported,
+            KeyEvent::new(KeyCode::Char('\u{434}'), KeyModifiers::CONTROL)
+        );
+
+        let mut with_base = DefaultHasher::new();
+        reported.hash(&mut with_base);
+        let mut without_base = DefaultHasher::new();
+        KeyEvent::new(KeyCode::Char('\u{434}'), KeyModifiers::CONTROL).hash(&mut without_base);
+        assert_eq!(with_base.finish(), without_base.finish());
+    }
+
     #[test]
     fn test_parse_csi_special_key_code_with_types() {
         assert_eq!(