⭐ Football Update: microsoft/terminal/pull/

Leonard Hecker (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 ✅
US Intern. " + ' produces \' ✅
Hebrew base keys produce Unicode ✅
Hebrew AltGr combinations produce Unicode ✅
French AltGr+Space produces U+00A0 ✅
German AltGr+Decimals produce []{}... ✅

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


+{
+    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)));


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


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


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


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


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


Dustin L. Howett (DHowett)

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

Dustin L. Howett (DHowett)

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

Leonard Hecker (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.

Leonard Hecker (lhecker) · 2026-02-03T23:49:07Z

(cc: James Holderness (@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.

James Holderness (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.

Leonard Hecker (lhecker) · 2026-02-04T22:22:36Z

James Holderness (@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...)

James Holderness (j4james) · 2026-02-05T16:47:25Z

Leonard Hecker (@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.

Leonard Hecker (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.

Dustin L. Howett (DHowett)

reviewed everything except terminalInput itself

Dustin L. Howett (DHowett) · 2026-02-06T21:10:46Z

        CATCH_RETURN();
    }

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


todo - file a bug?

Dustin L. Howett (DHowett) · 2026-02-06T21:18:29Z

+            // 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.

Dustin L. Howett (DHowett)

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

Dustin L. Howett (DHowett) · 2026-02-14T04:31:59Z

+        // 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

Yeah, but we should keep it that way right?

Dustin L. Howett (DHowett) · 2026-02-14T04:32:41Z

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


Same note as for numpad input

Dustin L. Howett (DHowett) · 2026-02-14T04:56:20Z

-    // 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?

This check is for dead keys that produce two codepoints (e.g. ^^ for the German caret dead key). But the new implementation only supports single-codepoint keys, so it's implicitly rejected. I did this intentionally because it simplifies the design: A single input still only produces a single output.

I'll add a note for this, since it's very implicit.

Dustin L. Howett (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!

Leonard Hecker (lhecker) · 2026-02-16T17:04:02Z

Yeah, the old approach has its benefits and I'm glad its in the git history as backup. In fact I wouldn't necessarily mind reintroducing it and only using the switch case for the kitty mode.

However, the lack of clarity in the KKP specification makes me wary. For instance, it doesn't say what to do if the Ansi mode is disabled. You can also enable key-up notifications in KKP while the disambiguate-esc enhancement is disabled. Then we have logic like the keypad mode feature on our side.

I found it very annoying to deal with the complexity of this.

…ty-keyboard-protocol

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 []{}... ✅ Co-authored-by: Leonard Hecker <lhecker@microsoft.com>

The surface sends typed text to ConPTY as win32-input-mode VK_PACKET strokes, one per UTF-16 unit: a key-down carrying the unit and a key-up carrying none. A supplementary character such as an emoji therefore reaches ConPTY as leading-surrogate down, empty up, trailing-surrogate down, empty up. For a child that reads VT input, ConPTY converts those records into text itself. ConPTY 1.25 (microsoft/terminal#19817, "Implement the Kitty Keyboard Protocol") moved that conversion's surrogate bookkeeping ahead of its key-down check, so any record that is not a surrogate, including an empty key-up, forgets a pending leading surrogate. Such a child received only the trailing surrogate, which most readers turn into U+FFFD. ConPTY 1.24 is unaffected, and classic readers of input records receive the records unchanged on both. A VK_PACKET key-up now carries the same unit as its key-down, which is how ConPTY builds the records for typed text itself. ConPTY pairs the surrogates on both versions and, with the Kitty protocol off, emits nothing for a key-up, so no text is doubled. Keys with a real virtual key still release with no character. The escape-transport suite gains a VT-input case that reads UTF-16 with ReadConsoleW. A byte reader would also see the console's own UTF-8 conversion, which splits the pair on 1.24 whatever the records are. Before this change the case fails on 1.25.260930003 and passes on 1.24.260710001. After it, it passes on both. The packet stroke expectations in the encoder and escape-transport tests now include the key-up unit.

github-advanced-security AI 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

Leonard Hecker (lhecker) commented Jan 29, 2026

View reviewed changes

Comment thread src/cascadia/TerminalCore/Terminal.cpp Resolved

Dustin L. Howett (DHowett) reviewed Jan 29, 2026

View reviewed changes

Comment thread src/common.build.pre.props Resolved

Dustin L. Howett (DHowett) requested changes Jan 29, 2026

View reviewed changes

Comment thread src/terminal/input/mouseInputState.cpp Resolved

Comment thread src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw Resolved

Comment thread src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw 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 (carlos-zamora) reviewed Jan 29, 2026

View reviewed changes

Comment thread src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml Resolved

Carlos Zamora (carlos-zamora) added a commit that referenced this pull request Jan 29, 2026

PRE-MERGE #19817 Implement the Kitty Keyboard Protocol

91dbd65

Dustin L. Howett (DHowett) reviewed Jan 30, 2026

View reviewed changes

Comment thread src/terminal/input/terminalInput.cpp Resolved

Comment thread src/terminal/input/terminalInput.cpp Resolved

Leonard Hecker (lhecker) marked this pull request as draft January 30, 2026 14:38

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

View reviewed changes

This comment has been minimized.

Sign in to view

Implement the Kitty Keyboard Protocol

4f86d4c

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

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

View reviewed changes

Comment thread src/terminal/input/terminalInput.cpp Fixed

This comment has been minimized.

Sign in to view

Spel

59705d5

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

Dustin L. Howett (DHowett) reviewed Feb 6, 2026

View reviewed changes

Address feedback

877c7c6

Dustin L. Howett (DHowett) reviewed Feb 13, 2026

View reviewed changes

Comment thread src/terminal/adapter/ut_adapter/kittyKeyboardProtocol.cpp Resolved

Dustin L. Howett (DHowett) reviewed Feb 14, 2026

View reviewed changes

Dustin L. Howett (DHowett) mentioned this pull request Feb 15, 2026

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

Merged

Leonard Hecker (lhecker) added 2 commits February 16, 2026 18:06

Merge remote-tracking branch 'origin/main' into dev/lhecker/11509-kit…

a76cc9a

…ty-keyboard-protocol

docs

6374ef7

Dustin L. Howett (DHowett) approved these changes Feb 17, 2026

View reviewed changes

Dustin L. Howett (DHowett) merged commit c81c66b into main Feb 17, 2026
18 of 20 checks passed

Dustin L. Howett (DHowett) deleted the dev/lhecker/11509-kitty-keyboard-protocol branch February 17, 2026 01:53

Austin Schey (aschey) mentioned this pull request Feb 17, 2026

feat: implement legacy console API on Windows helix-editor/termina#16

Merged

Tommaso Sciortino (scidomino) mentioned this pull request Mar 2, 2026

Kitty support for Windows Terminal google-gemini/gemini-cli#20882

Closed

8LWXpg mentioned this pull request Mar 6, 2026

Windows: console: <C-2>, <C-/> neovim/neovim#8435

Closed

Stéphane (sboisvert) mentioned this pull request Mar 17, 2026

/terminal-setup error message contradicts itself regarding Windows Terminal support anthropics/claude-code#8208

Closed

3 tasks done

Alexander (TheColorman) mentioned this pull request Mar 19, 2026

Momentary layers not functioning correctly in some terminal emulators ki-editor/ki-editor#1350

Open

7ampon mentioned this pull request Mar 25, 2026

Garbage characters inserted in editor when double-clicking output text (Windows Terminal 1.25 + Kitty protocol) earendil-works/pi#2589

Closed

Bruno Heridet (Delapouite) mentioned this pull request Apr 30, 2026

Distinguish "<c-i> and <tab>", "<c-j> and <ret>" mawww/kakoune#2209

Closed

Bhavesh Ramburn (bramburn) mentioned this pull request Aug 26, 2026

Garbage characters inserted in editor when double-clicking output text (Windows Terminal 1.25 + Kitty protocol) bramburn/pi#814

Open

4 tasks

notelm (not-elm) mentioned this pull request Oct 19, 2026

[Feature] Support the kitty keyboard protocol not-elm/orzma#405

Open

YeonGyu-Kim (code-yeongyu) mentioned this pull request Nov 5, 2026

Alt+letter bindings ignore legacy ESC-prefixed input once the Kitty keyboard protocol is negotiated (Alt+Q dequeue dead on WSL + Windows Terminal 1.25) code-yeongyu/senpi#6058

Closed

Conversation

Leonard Hecker (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!

Dustin L. Howett (DHowett) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Dustin L. Howett (DHowett) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Leonard Hecker (lhecker) commented Jan 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Leonard Hecker (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.

James Holderness (j4james) commented Feb 4, 2026

Uh oh!

Uh oh!

This comment has been minimized.

Leonard Hecker (lhecker) commented Feb 4, 2026

Uh oh!

James Holderness (j4james) commented Feb 5, 2026

Uh oh!

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

Uh oh!

Uh oh!

Dustin L. Howett (DHowett) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Dustin L. Howett (DHowett) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Leonard Hecker (lhecker) commented Jan 29, 2026 •

edited

Loading

Leonard Hecker (lhecker) commented Feb 3, 2026 •

edited

Loading

Leonard Hecker (lhecker) commented Feb 5, 2026 •

edited

Loading

Leonard Hecker (lhecker) commented Feb 16, 2026 •

edited

Loading