Implement the Kitty Keyboard Protocol by lhecker · Pull Request #19817 · microsoft/terminal

lhecker · 2026-01-29T23:00:21Z

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 ✅
Hebrew base keys produce Unicode ✅
Hebrew AltGr combinations produce Unicode ✅
French AltGr+Space produces U+00A0 ✅
German AltGr+Decimals produce []{}... ✅

src/terminal/input/terminalInput.cpp

+uint32_t TerminalInput::_codepointToLower(uint32_t cp) noexcept
+{
+    auto cb = _codepointToBuffer(cp);
+    // NOTE: MSDN states that `lpSrcStr == lpDestStr` is valid for LCMAP_LOWERCASE.


src/terminal/input/terminalInput.cpp

+{
+    auto cb = _codepointToBuffer(cp);
+    // NOTE: MSDN states that `lpSrcStr == lpDestStr` is valid for LCMAP_LOWERCASE.
+    const auto len = LCMapStringW(LOCALE_INVARIANT, LCMAP_LOWERCASE, cb.buf, cb.len, cb.buf, gsl::narrow_cast<int>(std::size(cb.buf)));


src/terminal/parser/OutputStateMachineEngine.cpp

    case CsiActionCodes::ANSISYSRC_CursorRestore:
        _dispatch->CursorRestoreState();
        break;
+    case CsiActionCodes::KKP_KittyKeyboardSet:


src/terminal/parser/OutputStateMachineEngine.cpp

+    case CsiActionCodes::KKP_KittyKeyboardSet:
+        _dispatch->SetKittyKeyboardProtocol(parameters.at(0), parameters.at(1));
+        break;
+    case CsiActionCodes::KKP_KittyKeyboardQuery:


src/terminal/parser/OutputStateMachineEngine.cpp

+    case CsiActionCodes::KKP_KittyKeyboardQuery:
+        _dispatch->QueryKittyKeyboardProtocol();
+        break;
+    case CsiActionCodes::KKP_KittyKeyboardPush:


src/terminal/parser/OutputStateMachineEngine.cpp

+    case CsiActionCodes::KKP_KittyKeyboardPush:
+        _dispatch->PushKittyKeyboardProtocol(parameters.at(0));
+        break;
+    case CsiActionCodes::KKP_KittyKeyboardPop:


src/terminal/parser/OutputStateMachineEngine.hpp

            DECSLRM_SetLeftRightMargins = VTID("s"),
            DTTERM_WindowManipulation = VTID("t"), // NOTE: Overlaps with DECSLPP. Fix when/if implemented.
            ANSISYSRC_CursorRestore = VTID("u"),
+            KKP_KittyKeyboardSet = VTID("=u"),


src/cascadia/TerminalCore/Terminal.cpp

src/common.build.pre.props

DHowett

we are unfortunately going to need some tests. or something. of the weird corner cases.

src/terminal/input/mouseInputState.cpp

src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw

src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml

DHowett

Almost all the way done. Can you explain the conhost win32im thing? Should we actually use Kitty as our internal protocol?

src/terminal/input/terminalInput.cpp

lhecker · 2026-01-30T14:38:58Z

I'm working on a version that's a lot easier to read. The problem is that it also doesn't quite work. 😄 Still working on that.

src/terminal/input/terminalInput.cpp

lhecker · 2026-02-03T23:49:07Z

(cc: @j4james, as this completely restructures your code to fit in Kitty's event-type field into the classic CSI sequences.)

I think the logic and "idea of a structure" is solid now. If you want to test it, I think now it's ready for that. 🙂 The code is not final, however. I'm trying to further improve its structure, because this is still beyond ugly and unmaintainable.

j4james · 2026-02-04T21:16:23Z

I'm sorry, I never got around to writing unit tests for all the keyboard mapping edge cases, and I know from last time that there's a lot of testing that's required. I can't do a build myself, so I can't test an in-progress PR anyway, but even if I could, I just wouldn't have the time to do that level of testing.

My suggestion would be to go through all the linked issues on #16511, and also look for follow up issues like #16641 and #16642. You're going to want to test with lots of international keyboard layouts, looking out for things like dead keys, and AltGr key combos, especially when mixed all the Ctrl/Alt/Shift modifiers. Make sure you test Hebrew and Cyrillic.

The various touch-screen/on-screen keyboards can also cause issues - I think some things are not expected to work, but they should at least work as well as they did before. I also vaguely remember remote desktop introducing some complications, so that's possibly worth testing too.

src/terminal/input/terminalInput.cpp

lhecker · 2026-02-04T22:22:36Z

@j4james Thanks for the pointers! I hope I'll do your implementation justice. I wouldn't say that I'm happy with my new implementation, but I also hope it's not too awful.

(One thing I'm still uncertain about is my decision to let Kitty's encoding use your encoding table as a fallback. This is what required the rewrite from a hashmap --> a switch case in the first place. I could've also just duplicated the table into the Kitty path. Not sure what decision would've been better...)

j4james · 2026-02-05T16:47:25Z

@lhecker I had hoped you would just be able to add additional mappings to my encoding table for kitty's disambiguate mode, and then the more advanced "report everything" modes would get their own code path the same as win32 input mode. If that wasn't feasible, I would probably be inclined to implement all of the kitty functionality in its own code path.

I have to say I really don't like the switch/case approach - the whole reason for my mapping table refactor was to avoid that sort of thing. But maybe you can still come up with a better solution. I don't know enough about the kitty protocol to know what complications you need to deal with, but I can understand that it's probably a bit of a pain.

lhecker · 2026-02-05T18:10:04Z

I started with splitting up your encoding table into a switch case when I started implementing the "event type" enhancement flag. It requires reporting key up and repeat events as a sub-parameter to the modifier field, e.g. CSI 1 ; 2:3 A (key-repeat arrow up).

Looking at your encoding table for such CSI sequences, it looked very daunting. It gave me the impression that I may have to add complex encoding logic into the Kitty path. That sprouted the idea of turning your encoding table into a switch case and re-using it. At the time I didn't realize that Kitty only requires about a dozen or so "legacy" CSI sequences.

DHowett

reviewed everything except terminalInput itself

src/buffer/out/ut_textbuffer/ReflowTests.cpp

src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml

DHowett · 2026-02-06T21:10:46Z

src/host/VtIo.cpp

        CATCH_RETURN();
    }

+    // TODO: Avoid translating win32im sequences to Kitty Keyboard Protocol temporarily.


todo - file a bug?

src/terminal/adapter/ITermDispatch.hpp

src/terminal/adapter/ut_adapter/Adapter.UnitTests.vcxproj

DHowett · 2026-02-06T21:18:29Z

src/terminal/input/terminalInput.hpp

+            // The KKP CSI u sequence is a superset of other CSI sequences:
+            //   CSI unicode-key-code:alternate-key-code-shift:alternate-key-code-base ; modifiers:event-type ; text-as-codepoint u
+            uint32_t csiUnicodeKeyCode;
+            uint32_t csiAltKeyCodeShifted; // KKP-specific


if KKP-specific, we could call it kkpAltKey...?

Hmm no I'd like everything to have the same csi prefix. Makes it easier in my mind since all of them logically belong together.

src/terminal/adapter/ut_adapter/kittyKeyboardProtocol.cpp

lhecker · 2026-02-11T18:53:45Z

@j4james FWIW I made a small test utility for this: https://github.com/lhecker/keyboard-layout-switcher

src/host/VtIo.cpp

src/terminal/adapter/ut_adapter/kittyKeyboardProtocol.cpp

DHowett

I'm pretty much ready to sign off, having read the implementations side by side, but I have just a few questions.

DHowett · 2026-02-14T04:31:59Z

src/terminal/input/terminalInput.cpp

+        // it must be the generated character from an Alt-Numpad composition.
+        if (WI_IsFlagSet(key.controlKeyState, NUMLOCK_ON) && key.virtualKey == VK_MENU && key.codepoint != 0)
+        {
+            return _makeCharOutput(key.codepoint);


This means that alt numpad (raw Unicode) inputs will not be encoded in kitty's "everything is escape sequences and (optionally) includes text/codepoint" mode

DHowett · 2026-02-14T04:32:41Z

src/terminal/input/terminalInput.cpp

+        if (key.virtualKey == VK_PACKET || key.virtualKey == 0)
        {
-            _lastVirtualKeyCode = std::nullopt;
+            return _makeCharOutput(key.codepoint);


Same note as for numpad input

DHowett · 2026-02-14T04:56:20Z

src/terminal/input/terminalInput.cpp

-    // of length two, with two identical characters. This is because the system
-    // sees this as a second press of the dead key, which would typically result
-    // in the combining character representation being transmit twice.
-    auto length = ToUnicodeEx(virtualKeyCode, 0, keyState.data(), buffer.data(), bufferSize, flags, hkl);


How does the new implementation handle dead keys?

DHowett · 2026-02-14T04:59:03Z

I did appreciate the simplicity of the defineKey lambdas, but I also get that there's a lot of complexity here. I don't mind the switch/case but getting to the point where I was reading it was hard!

github-advanced-security bot found potential problems Jan 29, 2026

View reviewed changes

microsoft-github-policy-service bot added Issue-Task It's a feature request, but it doesn't really need a major design. Area-Input Related to input processing (key presses, mouse, etc.) Product-Conhost For issues in the Console codebase Product-Terminal The new Windows Terminal. labels Jan 29, 2026

lhecker commented Jan 29, 2026

View reviewed changes

src/cascadia/TerminalCore/Terminal.cpp Show resolved Hide resolved

DHowett reviewed Jan 29, 2026

View reviewed changes

src/common.build.pre.props Outdated Show resolved Hide resolved

DHowett requested changes Jan 29, 2026

View reviewed changes

src/terminal/input/mouseInputState.cpp Show resolved Hide resolved

src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw Outdated Show resolved Hide resolved

src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw Outdated Show resolved Hide resolved

microsoft-github-policy-service bot added Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something and removed Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something labels Jan 29, 2026

carlos-zamora reviewed Jan 29, 2026

View reviewed changes

src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml Outdated Show resolved Hide resolved

carlos-zamora added a commit that referenced this pull request Jan 29, 2026

PRE-MERGE #19817 Implement the Kitty Keyboard Protocol

91dbd65

DHowett reviewed Jan 30, 2026

View reviewed changes

src/terminal/input/terminalInput.cpp Outdated Show resolved Hide resolved

src/terminal/input/terminalInput.cpp Outdated Show resolved Hide resolved

lhecker marked this pull request as draft January 30, 2026 14:38

github-advanced-security bot found potential problems Feb 3, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

Implement the Kitty Keyboard Protocol

4f86d4c

lhecker force-pushed the dev/lhecker/11509-kitty-keyboard-protocol branch from a4df1f4 to 4f86d4c Compare February 4, 2026 22:02

github-advanced-security bot found potential problems Feb 4, 2026

View reviewed changes

src/terminal/input/terminalInput.cpp Fixed Show fixed Hide fixed

This comment has been minimized.

Sign in to view

Spel

59705d5

lhecker marked this pull request as ready for review February 4, 2026 22:10

DHowett reviewed Feb 6, 2026

View reviewed changes

Address feedback

877c7c6

Fix typo

efcc5f9

carlos-zamora added the zBugBash-Consider label Feb 10, 2026

carlos-zamora added a commit that referenced this pull request Feb 10, 2026

PRE-MERGE #19817 Implement the Kitty Keyboard Protocol

425a403

Fix shift+key

5db9517

DHowett reviewed Feb 13, 2026

View reviewed changes

src/host/VtIo.cpp Show resolved Hide resolved

DHowett reviewed Feb 13, 2026

View reviewed changes

src/terminal/adapter/ut_adapter/kittyKeyboardProtocol.cpp Show resolved Hide resolved

DHowett reviewed Feb 14, 2026

View reviewed changes

DHowett mentioned this pull request Feb 15, 2026

Fix Control+Space not sent to program running in terminal #16298

Merged

Conversation

lhecker commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Validation Steps Performed

Uh oh!

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Uh oh!

Uh oh!

DHowett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DHowett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lhecker commented Jan 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lhecker commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

j4james commented Feb 4, 2026

Uh oh!

Uh oh!

This comment has been minimized.

lhecker commented Feb 4, 2026

Uh oh!

j4james commented Feb 5, 2026

Uh oh!

lhecker commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DHowett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DHowett Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DHowett Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

lhecker Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lhecker commented Feb 11, 2026

Uh oh!

Uh oh!

Uh oh!

DHowett left a comment

Choose a reason for hiding this comment

Uh oh!

DHowett Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

DHowett Feb 14, 2026

lhecker commented Jan 29, 2026 •

edited

Loading

lhecker commented Feb 3, 2026 •

edited

Loading

lhecker commented Feb 5, 2026 •

edited

Loading