fix(cli): fix csiUPrefix error in Linux/Wayland

[qqqys]

TLDR

Fix CSI-u sequence parsing errors on Linux/Wayland (e.g., Kitty terminal). The regex for csiUPrefix did not account for optional colon-separated fields in the full Kitty keyboard protocol, causing keypress parsing failures. Also improve the Kitty buffer timeout handler to salvage parseable sequences before discarding the buffer.

Screenshots / Video Demo

N/A — no user-facing visual change. The fix resolves keypress parsing errors (e.g., keys not registering or producing errors) when running in terminals that send extended Kitty keyboard protocol sequences on Linux/Wayland.

Dive Deeper

The Kitty keyboard protocol defines an extended CSI-u format:

ESC [ code:shifted:base ; mods:event ; text u

The previous regex only handled the basic form ESC [ code ; mods (u|~), which broke when terminals sent the full format with colon-separated sub-fields (shifted key, base key, event type, text).

Changes:

1. Updated csiUPrefix regex — Now correctly matches the full Kitty CSI-u format with optional :shifted, :base, :event, and ;text fields, while still extracting only the key code, modifier, and terminator we need.

2. Improved Kitty buffer timeout handler — Instead of immediately discarding the entire buffer on timeout, the handler now attempts to parse any remaining sequences (via parseKittyPrefix and parsePlainTextPrefix) before clearing. This handles cases where chunked input left valid sequences in the buffer.

Reviewer Test Plan

1. Run on a Linux machine with Kitty terminal (or any terminal using the Kitty keyboard protocol)
2. Verify basic keystrokes work: typing text, Enter, Backspace, Delete, arrow keys
3. Verify modifier combos work: Ctrl+C, Ctrl+Z, Shift+Enter, Alt+key
4. Test on macOS terminal to ensure no regression
5. Enable debug keystroke logging and verify no csiUPrefix parse errors in the logs

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	✅
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

fix: #2885

[github-actions]

📋 Review Summary

This PR fixes CSI-u sequence parsing errors on Linux/Wayland (particularly Kitty terminal) by updating the regex to handle the full Kitty keyboard protocol format with optional colon-separated fields. The implementation is clean, well-documented, and addresses the root cause of issue #2885.

🔍 General Feedback

• The fix correctly addresses the Kitty protocol parsing issue by extending the regex to handle optional colon-separated fields (:shifted, :base, :event, ;text)
• Good defensive programming in the timeout handler to salvage parseable sequences before discarding the buffer
• Comments are comprehensive and reference the official Kitty keyboard protocol documentation
• The change is minimal and focused on the specific problem
• Regex capture group index updates are correctly handled (m[3] → m[2] for modifiers, m[4] → m[3] for terminator)

🎯 Specific Feedback

🟡 High

• File: packages/cli/src/ui/contexts/KeypressContext.tsx:365-367 - The new regex pattern uses non-capturing groups (?:...) for the colon-separated fields, which is correct. However, consider adding a test case or comment explaining why the regex uses (?::\\d+)* (zero or more) instead of (?::\\d+)? (zero or one) for the colon-separated fields. The current pattern allows multiple colon-separated fields which matches the Kitty protocol spec, but this could be clearer.

🟢 Medium

• File: packages/cli/src/ui/contexts/KeypressContext.tsx:193-217 - The new salvage loop in the timeout handler is a good improvement, but consider extracting this logic into a separate helper function (e.g., salvageParseableSequences()) to improve readability and testability. The inline while loop adds complexity to the timeout handler.

• File: packages/cli/src/ui/contexts/KeypressContext.tsx:365 - Consider adding a unit test for the updated csiUPrefix regex to verify it correctly parses:

  • Basic format: ESC [ code ; mods u
  • Extended format: ESC [ code:shifted:base ; mods:event ; text u
  • Edge cases with empty colon fields

🔵 Low

• File: packages/cli/src/ui/contexts/KeypressContext.tsx:356-359 - The comment now reads "3) CSI-u and tilde-coded functional keys with optional kitty extensions:" followed by two lines. Consider consolidating these comments into a single clearer line to reduce vertical space, or use a multi-line comment block format for better readability.

• File: packages/cli/src/ui/contexts/KeypressContext.tsx:193 - The comment "Before discarding, try to salvage any parseable sequences" could mention why this is needed (e.g., "handles chunked input where valid sequences may arrive just before timeout").

✅ Highlights

• Excellent fix for a subtle terminal protocol issue that was causing real user problems on Linux/Wayland
• The salvage logic in the timeout handler shows thoughtful consideration of edge cases in terminal input handling
• Good use of non-capturing groups in the regex to maintain backward compatibility while extending functionality
• The PR description is thorough with a clear testing matrix and reviewer test plan
• Properly handles the Kitty protocol's optional extension fields without breaking existing functionality

[LaZzyMan]

LGTM！