Skip to content

Added: Add basic kitty keyboard protocol disambiguation support - #5366

Open
JM-FRANK wants to merge 1 commit into
termux:masterfrom
JM-FRANK:feat/kitty-keyboard-basic
Open

JM-FRANK wants to merge 1 commit into
termux:masterfrom
JM-FRANK:feat/kitty-keyboard-basic

Conversation

@JM-FRANK

@JM-FRANK JM-FRANK commented Oct 6, 2026 •

Copy link
Copy Markdown

Termux currently sends overlapping legacy encodings for Ctrl+I/Tab and unmodified/modified Enter. This adds negotiated kitty keyboard disambiguation (flag 1), so applications can distinguish these combinations, Ctrl+digits such as Ctrl+0, and Escape.

Refs #5300 and #5198.

Changes

  • Handle CSI ? u, CSI > flags u, CSI < count u, and CSI = flags ; mode u, with separate bounded mode stacks for the main and alternate screens and reset handling.
  • Encode modified text keys using their unshifted layout character; add canonical functional/keypad encodings, including modified Enter/Tab and the non-conflicting F3 encoding.
  • Connect hardware input, soft input/extra modifiers, and existing virtual Fn mappings to the negotiated mode. Preserve legacy input when the mode is disabled and retain plain Enter/Tab/Backspace recovery bytes.
  • Add parser/encoding regression tests, Android input-path tests, and validation documentation with expected/actual device bytes.

Review fixes and current validation

  • Resolve printable Space through the active Android layout before encoding, preserving AltGr layout text while retaining Ctrl/left-Alt+Space shortcuts.
  • Restore existing Shift+PageUp/PageDown scroll-action precedence; ordinary/Ctrl+Page keys still reach the application.
  • Centralize functional-key mode selection in KeyHandler.getCode for view and virtual Fn consumers.
  • The branch is consolidated into one feature commit following the repository convention. Squashing preserved the complete file tree; validation reports retain the original tested source identifiers.
  • 150 terminal-emulator tests and 10 app tests passed locally (160 total, zero failures/errors/skips). Four new input regressions cover AltGr layout characters, Ctrl/left-Alt+Space, scrollback precedence in both modes, and other Page-key delivery. AltGr uses a synthetic layout fixture.
  • Current fix source: 65c625b2. Complete Debug APK assembly passed for arm64-v8a, armeabi-v7a, x86, x86_64 and universal output. APKs, checksums, local test reports and a device-retest checklist are retained locally.
  • Review-fix APK 0.118.0+kitty.65c625b2 is now installed on the Android 16 arm64 test phone. All 96 recorded checks passed: 83 Android framework KeyEvents delivered directly to production TerminalView/native PTY with scroll checks, 2 checks of the current virtual AltGr+Space mapping (no character), and 11 real Rime touch/modifier/lifecycle checks. The direct framework-event checks do not cover physical HID or OS input dispatch.
  • The user reports completing manual combination retests on review-fix source 65c625b2, across on-device/external physical keyboards, local Termux/SSH, and Zellij/tmux. This is user-reported verification; versions and raw captures were not supplied.
  • Current virtual AltGr+Space maps to no character. An external layout producing NBSP or another character remains unverified; the combination retest report does not specifically confirm this layout case.
  • Review-fix device methods and exact byte results.
  • git diff --check passed.

Historical validation before review fixes

  • 150 terminal-emulator tests and 6 app tests passed, including 4 Robolectric input-path tests.
  • Debug APK assembly passed for arm64-v8a, armeabi-v7a, x86, x86_64 and universal output.
  • On a physical Android 16 arm64 device, 52 comparisons passed using system-injected key events through the installed Termux, native PTY and foreground shell capture. Mode queries also checked stack restoration and main/alternate-screen isolation.
  • 7 additional device checks passed using real Rime keyboard touches and the Termux CTRL extra key, including app background/foreground and keyboard close/open.
  • The user reports successful manual tests combining on-device/external physical keyboards, local Termux/SSH, and Zellij/tmux, with kitty-encoded input reaching the receiver. Versions and raw captures for these manual tests were not supplied.
  • Runtime validation above used pre-fix source commit 91ae4885. It does not validate the review fixes below.

Protocol scope and validation records.

Protocol scope and limitations

Only disambiguation flag 1 is implemented. Repeat/release events (2), alternate key codes (4), reporting all keys (8), and associated text (16) are not implemented; unsupported flags are masked out and are not advertised as enabled. This PR references the feature requests without closing the full-protocol request.

Text-only IME commits cannot preserve physical modifier/key identity that Android does not deliver. Termux application shortcuts retain precedence over terminal input.

Known limitation deferred to future work: virtual Fn (volume-up shortcut) mappings do not preserve Ctrl on the resulting key. For example, Ctrl+virtual Fn+W sends an unmodified Up rather than Ctrl+Up. That combination is not covered by the recorded passing checks.

@JM-FRANK
JM-FRANK force-pushed the feat/kitty-keyboard-basic branch from 25dc6dd to 65c625b Compare October 6, 2026 15:36
…port

Add negotiated flag 1 keyboard encoding, independent screen mode stacks,
layout-aware text handling and existing scroll shortcut precedence.
Include input regression tests and documented local and device validation.

Virtual Fn combinations currently do not preserve Ctrl modifiers.

Refs termux#5300 and termux#5198.
@JM-FRANK
JM-FRANK force-pushed the feat/kitty-keyboard-basic branch from a2abaaf to 60a581a Compare October 6, 2026 16:36
@JM-FRANK
JM-FRANK marked this pull request as ready for review October 6, 2026 16:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant