PRE-MERGE #19817 Implement the Kitty Keyboard Protocol

carlos-zamora · carlos-zamora · commit 91dbd6571284 · 2026-01-29T15:32:28.000-08:00
diff --git a/.github/actions/spelling/expect/expect.txt b/.github/actions/spelling/expect/expect.txt
@@ -866,6 +866,7 @@ KILLACTIVE
 KILLFOCUS
 kinda
 KIYEOK
+KKP
 KLF
 KLMNO
 KOK
@@ -885,6 +886,7 @@ LBUTTONDOWN
 LBUTTONUP
 lcb
 lci
+LCMAP
 LCONTROL
 LCTRL
 lcx
diff --git a/src/cascadia/TerminalCore/ICoreSettings.idl b/src/cascadia/TerminalCore/ICoreSettings.idl
@@ -121,6 +121,7 @@ namespace Microsoft.Terminal.Core
         String WordDelimiters { get; };
 
         Boolean ForceVTInput { get; };
+        Boolean AllowKittyKeyboardMode { get; };
         Boolean AllowVtChecksumReport { get; };
         Boolean AllowVtClipboardWrite { get; };
         Boolean TrimBlockSelection { get; };
diff --git a/src/cascadia/TerminalCore/Terminal.cpp b/src/cascadia/TerminalCore/Terminal.cpp
@@ -98,6 +98,7 @@ void Terminal::UpdateSettings(ICoreSettings settings)
     }
 
     _getTerminalInput().ForceDisableWin32InputMode(settings.ForceVTInput());
+    _getTerminalInput().ForceDisableKittyKeyboardProtocol(!settings.AllowKittyKeyboardMode());
 
     if (settings.TabColor() == nullptr)
     {
diff --git a/src/cascadia/TerminalSettingsAppAdapterLib/TerminalSettings.cpp b/src/cascadia/TerminalSettingsAppAdapterLib/TerminalSettings.cpp
@@ -349,6 +349,7 @@ namespace winrt::Microsoft::Terminal::Settings
         _ReloadEnvironmentVariables = profile.ReloadEnvironmentVariables();
         _RainbowSuggestions = profile.RainbowSuggestions();
         _ForceVTInput = profile.ForceVTInput();
+        _AllowKittyKeyboardMode = profile.AllowKittyKeyboardMode();
         _AllowVtChecksumReport = profile.AllowVtChecksumReport();
         _AllowVtClipboardWrite = profile.AllowVtClipboardWrite();
         _PathTranslationStyle = profile.PathTranslationStyle();
diff --git a/src/cascadia/TerminalSettingsEditor/ProfileViewModel.h b/src/cascadia/TerminalSettingsEditor/ProfileViewModel.h
@@ -145,6 +145,7 @@ namespace winrt::Microsoft::Terminal::Settings::Editor::implementation
         OBSERVABLE_PROJECTED_SETTING(_profile, AutoMarkPrompts);
         OBSERVABLE_PROJECTED_SETTING(_profile, RepositionCursorWithMouse);
         OBSERVABLE_PROJECTED_SETTING(_profile, ForceVTInput);
+        OBSERVABLE_PROJECTED_SETTING(_profile, AllowKittyKeyboardMode);
         OBSERVABLE_PROJECTED_SETTING(_profile, AllowVtChecksumReport);
         OBSERVABLE_PROJECTED_SETTING(_profile, AllowVtClipboardWrite);
         OBSERVABLE_PROJECTED_SETTING(_profile, AnswerbackMessage);
diff --git a/src/cascadia/TerminalSettingsEditor/ProfileViewModel.idl b/src/cascadia/TerminalSettingsEditor/ProfileViewModel.idl
@@ -134,6 +134,7 @@ namespace Microsoft.Terminal.Settings.Editor
         OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, AutoMarkPrompts);
         OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, RepositionCursorWithMouse);
         OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, ForceVTInput);
+        OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, AllowKittyKeyboardMode);
         OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, AllowVtChecksumReport);
         OBSERVABLE_PROJECTED_PROFILE_SETTING(String, AnswerbackMessage);
         OBSERVABLE_PROJECTED_PROFILE_SETTING(Boolean, RainbowSuggestions);
diff --git a/src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml b/src/cascadia/TerminalSettingsEditor/Profiles_Terminal.xaml
@@ -51,6 +51,16 @@
                               Style="{StaticResource ToggleSwitchInExpanderStyle}" />
             </local:SettingContainer>
 
+            <!--  Kitty Keyboard Mode  -->
+            <local:SettingContainer x:Name="AllowKittyKeyboardMode"
+                                    x:Uid="Profile_AllowKittyKeyboardMode"
+                                    ClearSettingValue="{x:Bind Profile.ClearAllowKittyKeyboardMode}"
+                                    HasSettingValue="{x:Bind Profile.HasAllowKittyKeyboardMode, Mode=OneWay}"
+                                    SettingOverrideSource="{x:Bind Profile.AllowKittyKeyboardModeOverrideSource, Mode=OneWay}">
+                <ToggleSwitch IsOn="{x:Bind Profile.AllowKittyKeyboardMode, Mode=TwoWay}"
+                              Style="{StaticResource ToggleSwitchInExpanderStyle}" />
+            </local:SettingContainer>
+
             <!--  Allow VT Checksum Report  -->
             <local:SettingContainer x:Name="AllowVtChecksumReport"
                                     x:Uid="Profile_AllowVtChecksumReport"
diff --git a/src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw b/src/cascadia/TerminalSettingsEditor/Resources/en-US/Resources.resw
@@ -546,6 +546,14 @@
     <value>Use the legacy input encoding</value>
     <comment>Header for a control to toggle legacy input encoding for the terminal.</comment>
   </data>
+  <data name="Profile_AllowKittyKeyboardMode.Header" xml:space="preserve">
+    <value>Kitty keyboard protocol mode</value>
+    <comment>Header for a control to set the kitty keyboard protocol mode.</comment>
+  </data>
+  <data name="Profile_AllowKittyKeyboardMode.HelpText" xml:space="preserve">
+    <value>Sets the baseline flags for the kitty keyboard protocol. Value is a sum of: 1=Disambiguate, 2=Report event types, 4=Report alternate keys, 8=Report all keys, 16=Report text.</value>
+    <comment>Additional description for what the "kitty keyboard mode" setting does.</comment>
+  </data>
   <data name="Profile_AllowVtChecksumReport.Header" xml:space="preserve">
     <value>Allow DECRQCRA (Request Checksum of Rectangular Area)</value>
     <comment>{Locked="DECRQCRA"}{Locked="Request Checksum of Rectangular Area"}Header for a control to toggle support for the DECRQCRA control sequence.</comment>
@@ -2583,19 +2591,19 @@
     <comment>An option to choose from for the "path translation" setting.</comment>
   </data>
   <data name="Profile_PathTranslationStyleWsl.Content" xml:space="preserve">
-    <value>WSL (C:\ -> /mnt/c)</value>
+    <value>WSL (C:\ -&gt; /mnt/c)</value>
     <comment>{Locked="WSL","C:\","/mnt/c"} An option to choose from for the "path translation" setting.</comment>
   </data>
   <data name="Profile_PathTranslationStyleCygwin.Content" xml:space="preserve">
-    <value>Cygwin (C:\ -> /cygdrive/c)</value>
+    <value>Cygwin (C:\ -&gt; /cygdrive/c)</value>
     <comment>{Locked="Cygwin","C:\","/cygdrive/c"} An option to choose from for the "path translation" setting.</comment>
   </data>
   <data name="Profile_PathTranslationStyleMsys2.Content" xml:space="preserve">
-    <value>MSYS2 (C:\ -> /c)</value>
+    <value>MSYS2 (C:\ -&gt; /c)</value>
     <comment>{Locked="MSYS2","C:\","/c"} An option to choose from for the "path translation" setting.</comment>
   </data>
   <data name="Profile_PathTranslationStyleMinGW.Content" xml:space="preserve">
-    <value>MinGW (C:\ -> C:/)</value>
+    <value>MinGW (C:\ -&gt; C:/)</value>
     <comment>{Locked="MinGW","C:\","C:/"} An option to choose from for the "path translation" setting.</comment>
   </data>
   <data name="Profile_Delete_Orphaned.Header" xml:space="preserve">
diff --git a/src/cascadia/TerminalSettingsModel/MTSMSettings.h b/src/cascadia/TerminalSettingsModel/MTSMSettings.h
@@ -103,6 +103,7 @@ Author(s):
     X(bool, ReloadEnvironmentVariables, "compatibility.reloadEnvironmentVariables", true)                                                                      \
     X(bool, RainbowSuggestions, "experimental.rainbowSuggestions", false)                                                                                      \
     X(bool, ForceVTInput, "compatibility.input.forceVT", false)                                                                                                \
+    X(bool, AllowKittyKeyboardMode, "compatibility.kittyKeyboardMode", true)                                                                                   \
     X(bool, AllowVtChecksumReport, "compatibility.allowDECRQCRA", false)                                                                                       \
     X(bool, AllowVtClipboardWrite, "compatibility.allowOSC52", true)                                                                                           \
     X(bool, AllowKeypadMode, "compatibility.allowDECNKM", false)                                                                                               \
diff --git a/src/cascadia/TerminalSettingsModel/Profile.idl b/src/cascadia/TerminalSettingsModel/Profile.idl
@@ -88,6 +88,7 @@ namespace Microsoft.Terminal.Settings.Model
         INHERITABLE_PROFILE_SETTING(Boolean, ReloadEnvironmentVariables);
         INHERITABLE_PROFILE_SETTING(Boolean, RainbowSuggestions);
         INHERITABLE_PROFILE_SETTING(Boolean, ForceVTInput);
+        INHERITABLE_PROFILE_SETTING(Boolean, AllowKittyKeyboardMode);
         INHERITABLE_PROFILE_SETTING(Boolean, AllowVtChecksumReport);
         INHERITABLE_PROFILE_SETTING(Boolean, AllowKeypadMode);
         INHERITABLE_PROFILE_SETTING(Boolean, AllowVtClipboardWrite);
diff --git a/src/cascadia/inc/ControlProperties.h b/src/cascadia/inc/ControlProperties.h
@@ -49,6 +49,7 @@
     X(bool, TrimBlockSelection, true)                                                                             \
     X(bool, SuppressApplicationTitle)                                                                             \
     X(bool, ForceVTInput, false)                                                                                  \
+    X(bool, AllowKittyKeyboardMode, true)                                                                         \
     X(winrt::hstring, StartingTitle)                                                                              \
     X(bool, DetectURLs, true)                                                                                     \
     X(bool, AutoMarkPrompts)                                                                                      \
diff --git a/src/renderer/atlas/AtlasEngine.cpp b/src/renderer/atlas/AtlasEngine.cpp
@@ -1151,6 +1151,8 @@ void AtlasEngine::_mapComplex(IDWriteFontFace2* mappedFontFace, u32 idx, u32 len
             const size_t col2 = _api.bufferLineColumn[a.textPosition + i];
             const auto fg = colors[col1 << shift];
 
+            // TODO: Instead of aligning each DWrite-cluster to the cell grid,
+            // we should align each grapheme cluster to the cell grid.
             const auto expectedAdvance = (col2 - col1) * _p.s->font->cellSize.x;
             f32 actualAdvance = 0;
             for (auto j = prevCluster; j < nextCluster; ++j)
diff --git a/src/terminal/adapter/ITermDispatch.hpp b/src/terminal/adapter/ITermDispatch.hpp
@@ -67,6 +67,10 @@ class Microsoft::Console::VirtualTerminal::ITermDispatch
     virtual void DeleteColumn(const VTInt distance) = 0; // DECDC
     virtual void SetKeypadMode(const bool applicationMode) = 0; // DECKPAM, DECKPNM
     virtual void SetAnsiMode(const bool ansiMode) = 0; // DECANM
+    virtual void SetKittyKeyboardProtocol(const VTParameter flags, const VTParameter mode) = 0; // CSI = flags ; mode u
+    virtual void QueryKittyKeyboardProtocol() = 0; // CSI ? u
+    virtual void PushKittyKeyboardProtocol(const VTParameter flags) = 0; // CSI > flags u
+    virtual void PopKittyKeyboardProtocol(const VTParameter count) = 0; // CSI < count u
     virtual void SetTopBottomScrollingMargins(const VTInt topMargin, const VTInt bottomMargin) = 0; // DECSTBM
     virtual void SetLeftRightScrollingMargins(const VTInt leftMargin, const VTInt rightMargin) = 0; // DECSLRM
     virtual void EnquireAnswerback() = 0; // ENQ
diff --git a/src/terminal/adapter/adaptDispatch.cpp b/src/terminal/adapter/adaptDispatch.cpp
@@ -2054,6 +2054,35 @@ void AdaptDispatch::SetKeypadMode(const bool fApplicationMode) noexcept
     _terminalInput.SetInputMode(TerminalInput::Mode::Keypad, fApplicationMode);
 }
 
+// CSI = flags ; mode u - Sets kitty keyboard protocol flags
+void AdaptDispatch::SetKittyKeyboardProtocol(const VTParameter flags, const VTParameter mode)
+{
+    const auto kittyFlags = static_cast<uint8_t>(flags.value_or(0));
+    const auto KittyKeyboardProtocol = static_cast<TerminalInput::KittyKeyboardProtocolMode>(mode.value_or(1));
+    _terminalInput.SetKittyKeyboardProtocol(kittyFlags, KittyKeyboardProtocol);
+}
+
+// CSI ? u - Queries current kitty keyboard protocol flags
+void AdaptDispatch::QueryKittyKeyboardProtocol()
+{
+    const auto flags = static_cast<VTInt>(_terminalInput.GetKittyFlags());
+    _ReturnCsiResponse(fmt::format(FMT_COMPILE(L"?{}u"), flags));
+}
+
+// CSI > flags u - Pushes current kitty keyboard flags onto the stack and sets new flags
+void AdaptDispatch::PushKittyKeyboardProtocol(const VTParameter flags)
+{
+    const auto kittyFlags = static_cast<uint8_t>(flags.value_or(0));
+    _terminalInput.PushKittyFlags(kittyFlags);
+}
+
+// CSI < count u - Pops one or more entries from the kitty keyboard stack
+void AdaptDispatch::PopKittyKeyboardProtocol(const VTParameter count)
+{
+    const auto popCount = static_cast<size_t>(count.value_or(1));
+    _terminalInput.PopKittyFlags(popCount);
+}
+
 // Routine Description:
 // - Internal logic for adding or removing lines in the active screen buffer.
 //   This also moves the cursor to the left margin, which is expected behavior for IL and DL.
diff --git a/src/terminal/adapter/adaptDispatch.hpp b/src/terminal/adapter/adaptDispatch.hpp
@@ -97,6 +97,10 @@ namespace Microsoft::Console::VirtualTerminal
         void RequestMode(const DispatchTypes::ModeParams param) override; // DECRQM
         void SetKeypadMode(const bool applicationMode) noexcept override; // DECKPAM, DECKPNM
         void SetAnsiMode(const bool ansiMode) override; // DECANM
+        void SetKittyKeyboardProtocol(const VTParameter flags, const VTParameter mode) override; // Kitty keyboard protocol CSI = flags ; mode u
+        void QueryKittyKeyboardProtocol() override; // Kitty keyboard protocol CSI ? u
+        void PushKittyKeyboardProtocol(const VTParameter flags) override; // Kitty keyboard protocol CSI > flags u
+        void PopKittyKeyboardProtocol(const VTParameter count) override; // Kitty keyboard protocol CSI < count u
         void SetTopBottomScrollingMargins(const VTInt topMargin,
                                           const VTInt bottomMargin) override; // DECSTBM
         void SetLeftRightScrollingMargins(const VTInt leftMargin,
diff --git a/src/terminal/adapter/termDispatch.hpp b/src/terminal/adapter/termDispatch.hpp
@@ -54,6 +54,10 @@ class Microsoft::Console::VirtualTerminal::TermDispatch : public Microsoft::Cons
     void DeleteColumn(const VTInt /*distance*/) override {} // DECDC
     void SetKeypadMode(const bool /*applicationMode*/) override {} // DECKPAM, DECKPNM
     void SetAnsiMode(const bool /*ansiMode*/) override {} // DECANM
+    void SetKittyKeyboardProtocol(const VTParameter /*flags*/, const VTParameter /*mode*/) override {} // CSI = flags ; mode u
+    void QueryKittyKeyboardProtocol() override {} // CSI ? u
+    void PushKittyKeyboardProtocol(const VTParameter /*flags*/) override {} // CSI > flags u
+    void PopKittyKeyboardProtocol(const VTParameter /*count*/) override {} // CSI < count u
     void SetTopBottomScrollingMargins(const VTInt /*topMargin*/, const VTInt /*bottomMargin*/) override {} // DECSTBM
     void SetLeftRightScrollingMargins(const VTInt /*leftMargin*/, const VTInt /*rightMargin*/) override {} // DECSLRM
     void EnquireAnswerback() override {} // ENQ
diff --git a/src/terminal/input/lib/terminalinput.vcxproj b/src/terminal/input/lib/terminalinput.vcxproj
@@ -12,7 +12,6 @@
   <Import Project="$(SolutionDir)src\common.nugetversions.props" />
   <ItemGroup>
     <ClCompile Include="..\mouseInput.cpp" />
-    <ClCompile Include="..\mouseInputState.cpp" />
     <ClCompile Include="..\terminalInput.cpp" />
     <ClCompile Include="..\precomp.cpp">
       <PrecompiledHeader>Create</PrecompiledHeader>
diff --git a/src/terminal/input/mouseInput.cpp b/src/terminal/input/mouseInput.cpp
@@ -487,7 +487,7 @@ TerminalInput::OutputType TerminalInput::_GenerateSGRSequence(const til::point p
 // True if the alternate buffer is active and alternate scroll mode is enabled and the event is a mouse wheel event.
 bool TerminalInput::ShouldSendAlternateScroll(const unsigned int button, const short delta) const noexcept
 {
-    const auto inAltBuffer{ _mouseInputState.inAlternateBuffer };
+    const auto inAltBuffer{ _inAlternateBuffer };
     const auto inAltScroll{ _inputMode.test(Mode::AlternateScroll) };
     const auto wasMouseWheel{ (button == WM_MOUSEWHEEL || button == WM_MOUSEHWHEEL) && delta != 0 };
     return inAltBuffer && inAltScroll && wasMouseWheel;
diff --git a/src/terminal/input/mouseInputState.cpp b/src/terminal/input/mouseInputState.cpp
diff --git a/src/terminal/input/sources.inc b/src/terminal/input/sources.inc
@@ -30,7 +30,6 @@ PRECOMPILED_INCLUDE     = ..\precomp.h
 SOURCES= \
     ..\terminalInput.cpp \
     ..\mouseInput.cpp \
-    ..\mouseInputState.cpp \
 
 INCLUDES = \
     $(INCLUDES); \
diff --git a/src/terminal/input/terminalInput.cpp b/src/terminal/input/terminalInput.cpp
diff --git a/src/terminal/input/terminalInput.hpp b/src/terminal/input/terminalInput.hpp
diff --git a/src/terminal/parser/OutputStateMachineEngine.cpp b/src/terminal/parser/OutputStateMachineEngine.cpp
diff --git a/src/terminal/parser/OutputStateMachineEngine.hpp b/src/terminal/parser/OutputStateMachineEngine.hpp

Original file line number	Diff line number	Diff line change
`@@ -98,6 +98,7 @@ void Terminal::UpdateSettings(ICoreSettings settings)`
`98`	`98`	`}`
`99`	`99`
`100`	`100`	`_getTerminalInput().ForceDisableWin32InputMode(settings.ForceVTInput());`
	`101`	`+ _getTerminalInput().ForceDisableKittyKeyboardProtocol(!settings.AllowKittyKeyboardMode());`
`101`	`102`
`102`	`103`	`if (settings.TabColor() == nullptr)`
`103`	`104`	`{`