feat: support extended keyboard enhancements (#1626)

aymanbagabas · web-flow · commit 05df5aecf81f · 2026-04-07T11:03:32.000-04:00
This adds support for the Kitty keyboard protocol's extended enhancements, allowing applications to request that the terminal report additional information about key events, such as whether they're part of a repeat sequence, alternate key values, and associated text. Supersedes: #1622 Fixes: #1621 Fixes: #1623
diff --git a/cursed_renderer.go b/cursed_renderer.go
@@ -131,10 +131,7 @@ func (s *cursedRenderer) start() {
 	// Both can coexist; terminals ignore what they don't support.
 	_, _ = s.scr.WriteString(ansi.SetModifyOtherKeys2)
 
-	kittyFlags := ansi.KittyDisambiguateEscapeCodes
-	if s.lastView.KeyboardEnhancements.ReportEventTypes {
-		kittyFlags |= ansi.KittyReportEventTypes
-	}
+	kittyFlags := keyboardEnhancementsFlags(s.lastView.KeyboardEnhancements)
 	_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
 }
 
@@ -379,10 +376,7 @@ func (s *cursedRenderer) flush(closing bool) error {
 		// Enable modifyOtherKeys and Kitty keyboard protocol.
 		_, _ = s.scr.WriteString(ansi.SetModifyOtherKeys2)
 
-		kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
-		if view.KeyboardEnhancements.ReportEventTypes {
-			kittyFlags |= ansi.KittyReportEventTypes
-		}
+		kittyFlags := keyboardEnhancementsFlags(view.KeyboardEnhancements)
 		_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
 		if !closing {
 			// Request keyboard enhancements when they change
@@ -828,3 +822,20 @@ func viewEquals(a, b *View) bool {
 
 	return true
 }
+
+func keyboardEnhancementsFlags(ke KeyboardEnhancements) int {
+	flags := 1 // always enable basic key disambiguation
+	if ke.ReportEventTypes {
+		flags |= ansi.KittyReportEventTypes
+	}
+	if ke.ReportAlternateKeys {
+		flags |= ansi.KittyReportAlternateKeys
+	}
+	if ke.ReportAllKeysAsEscapeCodes {
+		flags |= ansi.KittyReportAllKeysAsEscapeCodes
+	}
+	if ke.ReportAssociatedText {
+		flags |= ansi.KittyReportAssociatedKeys
+	}
+	return flags
+}
diff --git a/keyboard.go b/keyboard.go
@@ -39,3 +39,21 @@ func (k KeyboardEnhancementsMsg) SupportsKeyDisambiguation() bool {
 func (k KeyboardEnhancementsMsg) SupportsEventTypes() bool {
 	return k.Flags&ansi.KittyReportEventTypes != 0
 }
+
+// SupportsAlternateKeys returns whether the terminal supports reporting
+// alternate key codes.
+func (k KeyboardEnhancementsMsg) SupportsAlternateKeys() bool {
+	return k.Flags&ansi.KittyReportAlternateKeys != 0
+}
+
+// SupportsAllKeysAsEscapeCodes returns whether the terminal supports reporting
+// all keys as escape codes.
+func (k KeyboardEnhancementsMsg) SupportsAllKeysAsEscapeCodes() bool {
+	return k.Flags&ansi.KittyReportAllKeysAsEscapeCodes != 0
+}
+
+// SupportsAssociatedText returns whether the terminal supports reporting
+// associated text with key events.
+func (k KeyboardEnhancementsMsg) SupportsAssociatedText() bool {
+	return k.Flags&ansi.KittyReportAssociatedKeys != 0
+}
diff --git a/tea.go b/tea.go
@@ -245,6 +245,25 @@ type KeyboardEnhancements struct {
 	// [KeyPressMsg] with the [Key.IsRepeat] field set indicating that this is
 	// a it's part of a key repeat sequence.
 	ReportEventTypes bool
+
+	// ReportAlternateKeys requests the terminal to report alternate key values
+	// in addition to the main ones.
+	// Note that only key events represented as escape codes will affected by
+	// this enhancement.
+	ReportAlternateKeys bool
+
+	// ReportAllKeysAsEscapeCodes requests the terminal to report all key
+	// events, including plain text keys, as escape codes.
+	// When this is enabled, text won't be sent as plain text but instead as
+	// escape codes that encode the key value and modifiers.
+	ReportAllKeysAsEscapeCodes bool
+
+	// ReportAssociatedText requests the terminal to report the text associated
+	// with key events.
+	// Note that this is an enhancement to
+	// [KeyboardEnhancements.ReportAllKeysAsEscapeCodes] and only has an effect
+	// if that is enabled.
+	ReportAssociatedText bool
 }
 
 // SetContent is a helper method to set the content of a [View] with a styled
