Skip to content

Implement the Kitty Keyboard Protocol (#19817)#10

Merged
Dargon789 merged 1 commit intoDargon789:revert-4-Dargon789-patch-1from
microsoft:main
Feb 17, 2026
Merged

Implement the Kitty Keyboard Protocol (#19817)#10
Dargon789 merged 1 commit intoDargon789:revert-4-Dargon789-patch-1from
microsoft:main

Conversation

@Dargon789
Copy link
Owner

This essentially rewrites TerminalInput from scratch. There's significant overlap between what kind of information the Kitty protocol needs from the OS and our existing code. The rewrite allows us to share large parts of the implementation.

Closes microsoft#11509

Validation Steps Performed

  • kitten show-key -m kitty
  • US Intern. " + ' produces \'
  • Hebrew base keys produce Unicode ✅
  • Hebrew AltGr combinations produce Unicode ✅
  • French AltGr+Space produces U+00A0 ✅
  • German AltGr+Decimals produce []{}... ✅

Summary of the Pull Request

References and Relevant Issues

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

PR Checklist

  • Closes #xxx
  • Tests added/passed
  • Documentation updated
    • If checked, please file a pull request on our docs repo and link it here: #xxx
  • Schema updated (if necessary)

This essentially rewrites `TerminalInput` from scratch.
There's significant overlap between what kind of information
the Kitty protocol needs from the OS and our existing code.
The rewrite allows us to share large parts of the implementation.

Closes #11509

## Validation Steps Performed
* `kitten show-key -m kitty` ✅
* US Intern. " + ' produces `\'` ✅
* Hebrew base keys produce Unicode ✅
* Hebrew AltGr combinations produce Unicode ✅
* French AltGr+Space produces U+00A0 ✅
* German AltGr+Decimals produce []{}... ✅
Copy link

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @Dargon789, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

@snyk-io
Copy link

snyk-io bot commented Feb 17, 2026

Snyk checks have passed. No issues have been found so far.

Status Scanner Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@gemini-code-assist
Copy link

Summary of Changes

Hello @Dargon789, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces the Kitty Keyboard Protocol to enhance keyboard input capabilities within the terminal. By rewriting the TerminalInput component, it provides a more robust and flexible system for handling complex key combinations and modifiers, improving compatibility with modern terminal applications. The changes include new configuration options and a refined internal architecture for processing keyboard events.

Highlights

  • Kitty Keyboard Protocol Implementation: Implemented the Kitty Keyboard Protocol, enabling advanced keyboard input handling for terminal applications. This includes support for disambiguating escape codes, reporting event types (press, repeat, release), alternate key values, and associated text.
  • TerminalInput Rewrite: The TerminalInput class was significantly refactored and rewritten to integrate the new Kitty Keyboard Protocol logic, replacing the old _keyMap system with a more dynamic encoding helper and dedicated structs for key event sanitization and encoding.
  • New Settings and UI: Introduced a new setting, AllowKittyKeyboardMode, to enable or disable the Kitty Keyboard Protocol. This setting is exposed in the ICoreSettings, TerminalSettings, ProfileViewModel, and the Profiles_Terminal.xaml UI.
  • VT Sequence Integration: Added new VT sequences to ITermDispatch and AdaptDispatch for setting, querying, pushing, and popping Kitty Keyboard Protocol flags, allowing terminal applications to dynamically control the protocol's behavior.
  • Comprehensive Unit Tests: Extensive unit tests were added for the Kitty Keyboard Protocol to ensure correct behavior across various key combinations, modifiers, and protocol flags.
  • Code Cleanup and Refactoring: Removed obsolete TAEF adapter classes from test files, integrated mouseInputState.cpp logic directly into terminalInput.cpp, and updated spelling expectation files.
Changelog
  • .github/actions/spelling/expect/expect.txt
    • Removed 'coordnew' and 'fwlink' from spelling exceptions.
    • Added 'KKP' and 'LCMAP' to spelling exceptions.
  • src/buffer/out/ut_textbuffer/ReflowTests.cpp
    • Removed local TAEF adapter classes, now using common ones from consoletaeftemplates.hpp.
  • src/cascadia/TerminalCore/ICoreSettings.idl
    • Added AllowKittyKeyboardMode boolean property.
  • src/cascadia/TerminalCore/Terminal.cpp
    • Added call to _getTerminalInput().ForceDisableKittyKeyboardProtocol() based on AllowKittyKeyboardMode setting.
  • src/cascadia/TerminalSettingsAppAdapterLib/TerminalSettings.cpp
    • Added _AllowKittyKeyboardMode to the internal settings structure.
  • src/cascadia/TerminalSettingsEditor/ProfileViewModel.h
    • Added AllowKittyKeyboardMode as an observable projected setting.
  • src/cascadia/TerminalSettingsEditor/ProfileViewModel.idl
    • Added AllowKittyKeyboardMode as an inheritable profile setting.
  • src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml
    • Added a ToggleSwitch UI element for the AllowKittyKeyboardMode setting.
  • src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw
    • Added string resources for the 'Allow Kitty Keyboard Protocol' setting header.
    • Updated path translation style values to use HTML entities for arrows.
  • src/cascadia/TerminalSettingsModel/MTSMSettings.h
    • Defined AllowKittyKeyboardMode with a default value of true.
  • src/cascadia/TerminalSettingsModel/Profile.idl
    • Added AllowKittyKeyboardMode as an inheritable profile setting.
  • src/cascadia/inc/ControlProperties.h
    • Added AllowKittyKeyboardMode as a control property with a default of true.
  • src/host/VtIo.cpp
    • Added temporary logic to force disable Kitty Keyboard Protocol in ConPTY, referencing GH#19847.
  • src/inc/consoletaeftemplates.hpp
    • Included IDataSource.h.
    • Added ArrayIndexTaefAdapterRow and ArrayIndexTaefAdapterSource structs for generic TAEF data source adaptation.
  • src/interactivity/win32/ut_interactivity_win32/UiaTextRangeTests.cpp
    • Removed redundant local ArrayIndexTaefAdapterRow and ArrayIndexTaefAdapterSource definitions, now using common ones.
  • src/terminal/adapter/ITermDispatch.hpp
    • Added virtual methods for SetKittyKeyboardProtocol, QueryKittyKeyboardProtocol, PushKittyKeyboardProtocol, and PopKittyKeyboardProtocol.
  • src/terminal/adapter/adaptDispatch.cpp
    • Implemented SetKittyKeyboardProtocol, QueryKittyKeyboardProtocol, PushKittyKeyboardProtocol, and PopKittyKeyboardProtocol methods.
    • Moved the implementation of SetAnsiMode to a new location within the file.
  • src/terminal/adapter/adaptDispatch.hpp
    • Added declarations for SetKittyKeyboardProtocol, QueryKittyKeyboardProtocol, PushKittyKeyboardProtocol, and PopKittyKeyboardProtocol.
  • src/terminal/adapter/termDispatch.hpp
    • Added empty override implementations for new Kitty Keyboard Protocol methods.
  • src/terminal/adapter/ut_adapter/Adapter.UnitTests.vcxproj
    • Added kittyKeyboardProtocol.cpp to the project's compilation items.
  • src/terminal/adapter/ut_adapter/Adapter.UnitTests.vcxproj.filters
    • Added kittyKeyboardProtocol.cpp to the 'Source Files' filter.
    • Added Natvis debugger visualization files.
  • src/terminal/adapter/ut_adapter/kittyKeyboardProtocol.cpp
    • Added a new file containing extensive unit tests for the Kitty Keyboard Protocol implementation.
  • src/terminal/adapter/ut_adapter/sources
    • Added kittyKeyboardProtocol.cpp to the list of source files.
  • src/terminal/input/lib/terminalinput.vcxproj
    • Removed mouseInputState.cpp from the project's compilation items.
  • src/terminal/input/mouseInput.cpp
    • Updated ShouldSendAlternateScroll to use the _inAlternateBuffer member directly.
    • Refactored _makeAlternateScrollOutput to use the new encoding helper.
  • src/terminal/input/sources.inc
    • Removed mouseInputState.cpp from the list of source files.
  • src/terminal/input/terminalInput.cpp
    • Rewrote the HandleKey method to incorporate Kitty Keyboard Protocol logic.
    • Removed the old _keyMap and associated defineKey helper functions.
    • Introduced SanitizedKeyEvent, KeyboardHelper, and EncodingHelper structs for improved key processing.
    • Added methods for managing Kitty Keyboard Protocol flags and stack (SetKittyKeyboardProtocol, GetKittyFlags, PushKittyFlags, PopKittyFlags, ResetKittyKeyboardProtocols).
    • Refactored _initKeyboardMap to only initialize CSI/SS3 introducers.
    • Updated _makeCtrlChar to handle uint32_t codepoints.
    • Removed _getKeyboardState and _escapeOutput methods.
    • Added _encodeKitty, _getKittyFunctionalKeyCode, _encodeRegular, _formatEncodingHelper, _formatFallback, _stringPushCodepoint, _codepointToLower methods for new encoding logic.
  • src/terminal/input/terminalInput.hpp
    • Added KittyKeyboardProtocolFlags and KittyKeyboardProtocolMode enums.
    • Added UseAlternateScreenBuffer and UseMainScreenBuffer methods.
    • Added ForceDisableKittyKeyboardProtocol method.
    • Added new Kitty Keyboard Protocol related methods: SetKittyKeyboardProtocol, GetKittyFlags, PushKittyFlags, PopKittyFlags, ResetKittyKeyboardProtocols.
    • Introduced nested structs CodepointBuffer, SanitizedKeyEvent, KeyboardHelper, and EncodingHelper for internal key processing.
    • Removed _keyMap and _getKeyboardState members and their associated methods.
    • Updated _csi, _ss3, _focusInSequence, _focusOutSequence to std::wstring_view.
    • Updated signatures for _makeCtrlChar and _makeCharOutput to use uint32_t.
  • src/terminal/parser/OutputStateMachineEngine.cpp
    • Added cases for new Kitty Keyboard Protocol CSI actions: KKP_KittyKeyboardSet, KKP_KittyKeyboardQuery, KKP_KittyKeyboardPush, and KKP_KittyKeyboardPop.
  • src/terminal/parser/OutputStateMachineEngine.hpp
    • Added new CsiActionCodes for Kitty Keyboard Protocol: KKP_KittyKeyboardSet, KKP_KittyKeyboardQuery, KKP_KittyKeyboardPush, and KKP_KittyKeyboardPop.
Activity
  • The pull request implements the Kitty Keyboard Protocol, addressing issue Add keyboard protocol support (the kitty one) microsoft/terminal#11509.
  • The TerminalInput class has been rewritten to support the new protocol.
  • Validation steps were performed using kitten show-key -m kitty and testing with various international keyboard layouts (US Intern., Hebrew, French, German).
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces support for the Kitty Keyboard Protocol, which is a significant enhancement. The implementation involves a major and well-executed refactoring of the TerminalInput class, moving from a map-based key lookup to a more flexible and performant encoding pipeline. This new structure is much clearer and more extensible. The addition of comprehensive unit tests for the Kitty protocol is also a great contribution to ensure correctness. I have a couple of minor suggestions for improving code clarity, but overall this is an excellent piece of work.

@github-actions
Copy link

@check-spelling-bot Report

🔴 Please review

See the 📂 files view, the 📜action log, or 📝 job summary for details.

Unrecognized words (2)

cimg
circleci

To accept these unrecognized words as correct, you could run the following commands

... in a clone of the git@github.com:microsoft/terminal.git repository
on the main branch (ℹ️ how do I use this?):

curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/v0.0.25/apply.pl' |
perl - 'https://github.com/Dargon789/terminal/actions/runs/22083979240/attempts/1' &&
git commit -m 'Update check-spelling metadata'
Pattern suggestions ✂️ (1)

You could add these patterns to .github/actions/spelling/patterns/83b9569ce0393f2de99ffa5ea17fdc869e699090.txt:

# Automatically suggested patterns

# hit-count: 1 file-count: 1
# container images
image: [-\w./:@]+

Alternatively, if a pattern suggestion doesn't make sense for this project, add a #
to the beginning of the line in the candidates file with the pattern to stop suggesting it.

Errors, Warnings, and Notices ❌ (3)

See the 📂 files view, the 📜action log, or 📝 job summary for details.

❌ Errors, Warnings, and Notices Count
ℹ️ candidate-pattern 1
❌ check-file-path 1
⚠️ ignored-expect-variant 1

See ❌ Event descriptions for more information.

✏️ Contributor please read this

By default the command suggestion will generate a file named based on your commit. That's generally ok as long as you add the file to your commit. Someone can reorganize it later.

If the listed items are:

  • ... misspelled, then please correct them instead of using the command.
  • ... names, please add them to .github/actions/spelling/allow/names.txt.
  • ... APIs, you can add them to a file in .github/actions/spelling/allow/.
  • ... just things you're using, please add them to an appropriate file in .github/actions/spelling/expect/.
  • ... tokens you only need in one place and shouldn't generally be used, you can add an item in an appropriate file in .github/actions/spelling/patterns/.

See the README.md in each directory for more information.

🔬 You can test your commits without appending to a PR by creating a new branch with that extra change and pushing it to your fork. The check-spelling action will run in response to your push -- it doesn't require an open pull request. By using such a branch, you can limit the number of typos your peers see you make. 😉

If the flagged items are 🤯 false positives

If items relate to a ...

  • binary file (or some other file you wouldn't want to check at all).

    Please add a file path to the excludes.txt file matching the containing file.

    File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

    ^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

  • well-formed pattern.

    If you can write a pattern that would match it,
    try adding it to the patterns.txt file.

    Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

    Note that patterns can't match multiline strings.

@Dargon789 Dargon789 merged commit 5b00e95 into Dargon789:revert-4-Dargon789-patch-1 Feb 17, 2026
12 of 14 checks passed
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.

2 participants