Preserve Kitty keyboard event metadata

src/event.rs

@@ -118,6 +118,36 @@ impl Event {
     }
 }
 
+/// Optional metadata carried by an enhanced keyboard protocol key event.
+///
+/// The Kitty keyboard protocol can report the shifted key, the key in the base keyboard layout,
+/// and the text generated by a key event in addition to its canonical key code.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct KeyEventEnhancements {
+    /// The character that would be produced with Shift applied.
+    pub shifted_key: Option<char>,
+
+    /// The character in the base keyboard layout (without modifiers/layout translations applied).
+    pub base_layout_key: Option<char>,
+
+    /// The Unicode text associated with the key event.
+    ///
+    /// `None` means the protocol omitted the associated-text field. An empty string means the
+    /// field was present but reported no generated text.
+    pub associated_text: Option<String>,
+}
+
+impl KeyEventEnhancements {
+    /// Creates a new, empty set of key event enhancements.
+    pub const fn new() -> Self {
+        Self {
+            shifted_key: None,
+            base_layout_key: None,
+            associated_text: None,
+        }
+    }
+}
+
 /// A key event plus modifiers and protocol state.
 ///
 /// `KeyEvent` appears inside [`Event::Key`], which is normally returned by [`EventReader::read`]
@@ -143,7 +173,7 @@ impl Event {
 ///
 /// [crossterm key events]: https://docs.rs/crossterm/latest/crossterm/event/struct.KeyEvent.html
 /// [missing key combinations]: https://github.com/crossterm-rs/crossterm/issues/685
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct KeyEvent {
     /// The key identity.
     pub code: KeyCode,
@@ -167,6 +197,9 @@ pub struct KeyEvent {
     /// This is empty unless the input source reports state outside the ordinary modifier mask,
     /// such as keypad-originated input, Caps Lock, or Num Lock.
     pub state: KeyEventState,
+
+    /// Optional metadata reported by an enhanced keyboard protocol.
+    pub enhancements: KeyEventEnhancements,
 }
 
 impl KeyEvent {
@@ -177,6 +210,7 @@ impl KeyEvent {
             modifiers,
             kind: KeyEventKind::Press,
             state: KeyEventState::NONE,
+            enhancements: KeyEventEnhancements::new(),
         }
     }
 }
@@ -188,6 +222,7 @@ impl From<KeyCode> for KeyEvent {
             kind: KeyEventKind::Press,
             modifiers: Modifiers::NONE,
             state: KeyEventState::NONE,
+            enhancements: KeyEventEnhancements::new(),
         }
     }
 }