Support the Kitty keyboard protocol (flag 1, disambiguate)

Push the Kitty keyboard protocol on startup and pop it on exit so
supporting terminals deliver modified keys — Ctrl-Enter, Shift-Enter,
Ctrl-Shift-Enter, Alt-letter, and full modifier coverage on the
navigation block — as distinct CSI u sequences instead of being
collapsed into their unmodified equivalents. Terminals that don't
implement the protocol silently ignore the push, so there is no
regression for them.

Detection mirrors the existing CPR machinery: the renderer emits
`CSI ? u`, a new binding under key_binding/bindings/ consumes the
response and flips `Renderer.kitty_support` from UNKNOWN to SUPPORTED,
letting callers branch on capability if they want.

The bulk of the code lives in new files:
- input/kitty_keyboard.py — CSI u decoder, functional-key table,
  query-response parser
- output/kitty_keyboard.py — push/pop context manager with
  reference-counted depth, sequence constants
- key_binding/bindings/kitty_keyboard.py — response-consuming binding
- docs/pages/advanced_topics/kitty_keyboard_protocol.rst — maintainer
  notes on wire format, capability detection, and known sharp edges

Touch-points in existing code are small and mirror the CPR pattern:
one import + one regex + one dispatch branch in vt100_parser.py, a
push/query/pop trio in renderer.py, one binding registration in
key_binding/defaults.py, four new enum values in keys.py.

prompt_toolkit does not push xterm's modifyOtherKeys. Users whose
terminal or tmux has it enabled independently still get the existing
`CSI 27` Enter fallback in ansi_escape_sequences.py, which folds all
three modifier+Enter variants to plain Keys.ControlM so the form at
least submits rather than silently doing nothing.

New Keys: ControlEnter, ControlShiftEnter, ShiftEnter,
KittyKeyboardResponse. Bindings registered as `c-enter` / `s-enter` /
`c-s-enter` fire on Kitty-capable terminals; on non-Kitty terminals
they don't fire (plain Enter fires instead, as before).

Author: Carreau

CHANGELOG

@@ -1,6 +1,22 @@
 CHANGELOG
 =========
 
+Unreleased
+----------
+
+New features:
+- Support the Kitty keyboard protocol (flag 1, "disambiguate") on
+  terminals that implement it — kitty, ghostty, wezterm, foot,
+  Alacritty, iTerm2 (with "Report modifiers using CSI u" enabled in
+  Preferences → Profiles → Keys), and others. The renderer pushes the
+  protocol on startup and pops it on exit, so modified keys like
+  Ctrl-Enter, Shift-Enter, Ctrl-Shift-Enter, and Alt-letter arrive as
+  distinct `CSI u` sequences. New key values `Keys.ControlEnter`,
+  `Keys.ControlShiftEnter`, and `Keys.ShiftEnter` can be used in
+  bindings (e.g. `@bindings.add("c-enter")`). Terminals that don't
+  implement the protocol silently ignore the push — no regression,
+  plain Enter continues to submit.
+
 3.0.52: 2025-08-27
 ------------------
 

docs/pages/advanced_topics/index.rst

@@ -8,6 +8,7 @@ Advanced topics
     :maxdepth: 1
 
     key_bindings
+    kitty_keyboard_protocol
     styling
     filters
     rendering_flow

docs/pages/advanced_topics/kitty_keyboard_protocol.rst

@@ -0,0 +1,214 @@
+.. _kitty_keyboard_protocol:
+
+
+Kitty keyboard protocol
+=======================
+
+Maintainer-facing notes on prompt_toolkit's support for the `Kitty
+keyboard protocol <https://sw.kovidgoyal.net/kitty/keyboard-protocol/>`_.
+
+Note that despite it's name, the kitty protocol is support by a wide range of
+terminal emulator on various platform and is far from being limited to only
+the kitty terminal emulator.
+
+Currently only part of the protocol is implemented (to disambiguate modifiers
+on some keys), but it is could be possible to request progressive enhancement,
+allowing to actually receive key press, and release as well as many other
+distinctions, but this is not implemented
+
+
+Why
+---
+
+Under legacy terminal encodings, many modifier+key combinations are
+ambiguous or impossible — :kbd:`c-enter` sends the same ``\r`` as plain
+:kbd:`enter`, :kbd:`s-enter` is indistinguishable from :kbd:`enter` on
+most terminals, :kbd:`m-b` (Alt-b) is reported as an Esc-prefix that
+collides with pressing :kbd:`escape` followed by ``b``. The Kitty
+protocol fixes all of this by escaping modified keys into ``CSI u``
+sequences with explicit modifier bits.
+
+prompt_toolkit pushes flag 1 ("disambiguate escape codes") on startup
+and pops it on exit, so supporting terminals deliver modified keys as
+distinct ``Keys`` values, and non-supporting terminals silently keep
+their existing behavior.
+
+
+
+What the code does
+------------------
+
+Output
+~~~~~~
+
+``src/prompt_toolkit/output/kitty_keyboard.py`` owns the wire-format
+constants and exposes ``kitty_keyboard_protocol(output, flags)`` — a
+context manager that pushes the given flags on entry and pops on exit.
+A depth counter (lazily attached to the ``Output`` instance by the
+context manager, not a first-class field on ``Output``) ensures nested
+holders compose correctly: outermost enter pushes and flushes,
+outermost exit pops and flushes. Entering a nested context with a
+different ``flags`` value raises ``ValueError`` rather than silently
+corrupting the terminal's flag stack.
+
+Input
+~~~~~
+
+``src/prompt_toolkit/input/kitty_keyboard.py`` owns the ``CSI u``
+decoder. Covered:
+
+- Functional keys from the Kitty spec: :kbd:`enter`, :kbd:`tab`,
+  :kbd:`escape`, :kbd:`backspace`, arrows, navigation block
+  (:kbd:`home` / :kbd:`end` / :kbd:`pageup` / :kbd:`pagedown` /
+  :kbd:`insert` / :kbd:`delete`), :kbd:`f1`–:kbd:`f12`. Mapped to the
+  nearest existing ``Keys`` value with Shift / Ctrl / Ctrl-Shift
+  promotion where an enum exists.
+- Printable Unicode keys with Ctrl (mapped to ``Keys.ControlX``) and
+  Ctrl+Shift digits (mapped to ``Keys.ControlShift1`` …).
+- Alt as a meta prefix: emitted as ``(Keys.Escape, base_key)`` to match
+  prompt_toolkit's long-standing convention for meta-prefixed keys, so
+  existing bindings like ``('escape', 'b')`` keep working.
+- CapsLock and NumLock modifier bits are stripped before decoding so
+  terminals that report them don't break bindings.
+
+``src/prompt_toolkit/input/vt100_parser.py`` dispatches ``CSI … u``
+sequences to the decoder (after the static ``ANSI_SEQUENCES`` lookup,
+so pre-existing fixed-form entries still win) and recognizes the
+``CSI ? <flags> u`` query response as ``Keys.KittyKeyboardResponse``.
+
+Renderer and capability detection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Renderer`` pushes flag 1 on first render and pops it on reset. At the
+same time it writes a ``CSI ? u`` query. The binding in
+``src/prompt_toolkit/key_binding/bindings/kitty_keyboard.py`` consumes
+the response and flips ``renderer.kitty_support`` from ``UNKNOWN`` to
+``SUPPORTED``. Terminals that don't implement the protocol silently
+ignore both the push and the query; ``kitty_support`` stays at
+``UNKNOWN`` and the terminal keeps sending legacy byte sequences.
+Callers that want to branch on capability (e.g. to surface a hint to
+the user) can read ``app.renderer.kitty_support`` — ``Application``
+exposes its renderer as a public attribute, and the value is one of
+``KittySupport.UNKNOWN`` or ``KittySupport.SUPPORTED`` (imported from
+``prompt_toolkit.renderer``).
+
+Legacy xterm ``modifyOtherKeys`` fallback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+prompt_toolkit does **not** push ``\x1b[>4;Nm`` to enable xterm's
+``modifyOtherKeys``. But the parser still folds
+``CSI 27 ; <mods> ; 13 ~`` (Shift-, Ctrl-, and Ctrl-Shift-Enter under
+``modifyOtherKeys``) back to ``Keys.ControlM``. That's a passive
+compatibility shim: if a user's terminal or tmux has
+``modifyOtherKeys`` enabled independently, modified :kbd:`enter` still
+submits the form instead of silently doing nothing. Users who want
+distinct bindings for :kbd:`c-enter` / :kbd:`s-enter` need a
+Kitty-capable terminal.
+
+New ``Keys`` values
+~~~~~~~~~~~~~~~~~~~
+
+- ``Keys.ControlEnter``, ``Keys.ControlShiftEnter``,
+  ``Keys.ShiftEnter`` — Kitty-only modifier+Enter distinctions. On
+  non-Kitty terminals these bindings don't fire; plain :kbd:`enter`
+  fires instead (the protocol-less fallback).
+- ``Keys.ControlTab``, ``Keys.ControlShiftTab`` — Kitty-only
+  modifier+Tab distinctions. Plain :kbd:`tab` (``Keys.ControlI``) and
+  Shift-Tab (``Keys.BackTab``) were already distinguishable; Ctrl-Tab
+  and Ctrl-Shift-Tab only come through under the protocol. On
+  non-Kitty terminals they fold back to their legacy equivalents.
+- ``Keys.ControlEscape``, ``Keys.ControlShiftEscape`` — Kitty-only
+  modifier+Escape distinctions, alongside the pre-existing
+  ``Keys.ShiftEscape``. Same non-Kitty fallback behavior.
+- ``Keys.KittyKeyboardResponse`` — internal sentinel for the query
+  response parser-to-binding dispatch.
+
+
+What could be done in the future
+--------------------------------
+
+Higher flags
+~~~~~~~~~~~~
+
+The protocol defines further enhancement flags beyond "disambiguate":
+
+- **Flag 2 — report event types.** Distinguishes press / release /
+  repeat. Useful for full-screen apps and tooling; not for a shell.
+  Would require adding an ``event_type`` field to ``KeyPress``, which
+  is a coordinated API change.
+- **Flag 4 — report alternate keys.** Sends the base-layout keycode
+  alongside the current-layout one; helpful for non-US keyboard
+  layouts where a binding is conceptually on the "unshifted key at
+  that position".
+- **Flag 8 — report all keys as escape codes.** Even unmodified
+  letters arrive as ``CSI u``. Dramatically changes input and needs
+  corresponding decoder work.
+- **Flag 16 — report associated text.** Only meaningful with flag 8.
+
+More functional keys
+~~~~~~~~~~~~~~~~~~~~
+
+The decoder's ``_FUNCTIONAL`` table stops at :kbd:`f12` and omits
+keypad / media / system keys (Play, Mute, brightness, Left Super, …)
+that Kitty can report. Extending the table and adding matching
+``Keys`` values is mechanical.
+
+Press/release-aware bindings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bindings today fire on press only. If flag 2 support is ever added,
+``KeyBindings.add`` would need an opt-in parameter for release/repeat
+events, and the key processor would need to carry the event type. A
+large surface; best tackled together with any flag-2 work.
+
+
+Wire format reference
+---------------------
+
+**Push flags.**
+    ``CSI = <flags> ; <mode> u``. The spec defines mode 1 (set),
+    mode 2 (OR into current), and mode 3 (AND-NOT into current).
+    prompt_toolkit always hardcodes mode 1 with ``flags=1``; the other
+    modes exist in the spec but aren't used here.
+
+**Pop flags.**
+    ``CSI < u`` pops one entry. ``CSI < N u`` pops N.
+
+**Query flags.**
+    ``CSI ? u``; terminal answers ``CSI ? <flags> u`` if supported,
+    silence otherwise.
+
+**Key event.**
+    ``CSI <keycode>[:<alt>] ; <modifiers>[:<event-type>] ;
+    <text-codepoints> u``. Every key, functional or not, terminates in
+    ``u`` — that's the whole point of the protocol versus the legacy
+    ``CSI <n> ~`` encoding it replaces. Modifiers encode as
+    ``1 + bitmask`` — the ``+1`` ensures an omitted modifier field
+    can't be confused with "Shift pressed". Keycode is a Unicode
+    codepoint for printable keys, functional-key codes otherwise
+    (Enter=13, Escape=27, F1=57364, …). Event-type is ``1`` for press,
+    ``2`` for repeat, ``3`` for release; under flag 1 only press
+    events are sent, but the decoder defensively drops the other two.
+
+
+Known sharp edges
+-----------------
+
+- **Tmux pass-through.** Requires ``set -g extended-keys on`` *and* an
+  underlying terminal that supports the protocol. If the underlying
+  terminal doesn't, tmux swallows the query and ``kitty_support``
+  stays at ``UNKNOWN``.
+- **Detection latency.** The query response is asynchronous; if a
+  terminal is slow, the first few keys may arrive before
+  ``kitty_support`` flips to ``SUPPORTED``. That only affects the
+  capability signal — the push itself applies immediately, so the
+  terminal's first keystroke is already in the new encoding.
+- **Functional-key codes are not universal.** The Kitty spec pins
+  Enter=13 (which coincides with ``\r``) but implementations disagree
+  on some rarer functional codes. Worth spot-checking new ones against
+  kitty, ghostty, wezterm, foot.
+- **Alt vs. Esc-prefix.** Kitty reports Alt as a modifier; the legacy
+  path reports it as ``(Esc, letter)``. The decoder emits
+  ``(Keys.Escape, base_key)`` for Alt-prefixed keys to match legacy
+  convention — so a binding registered as ``('escape', 'b')`` matches
+  Alt-b either way.

examples/prompts/modified-enter.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+"""
+Demo for modified-Enter key bindings (Ctrl-Enter, Ctrl-Shift-Enter,
+Shift-Enter).
+
+prompt_toolkit pushes the Kitty keyboard protocol (flag 1) on startup,
+so terminals that implement it (kitty, ghostty, wezterm, foot,
+Alacritty, recent iTerm2 with CSI u reporting enabled, …) can
+distinguish these from plain Enter.
+
+Run this and try pressing each combination. Plain Enter still submits
+(the `c-m` / `enter` binding shipped by ``PromptSession`` defaults
+fires as usual — our custom bindings below don't override it).
+Terminals that don't support the protocol will just submit on any Enter
+variant — that's the expected fallback.
+"""
+
+from prompt_toolkit import prompt
+from prompt_toolkit.application import run_in_terminal
+from prompt_toolkit.key_binding import KeyBindings
+
+
+def main():
+    bindings = KeyBindings()
+
+    def _announce(label):
+        def _print():
+            print(f"[{label}] pressed")
+
+        run_in_terminal(_print)
+
+    @bindings.add("c-enter")
+    def _(event):
+        _announce("Ctrl-Enter")
+
+    @bindings.add("s-enter")
+    def _(event):
+        _announce("Shift-Enter")
+
+    @bindings.add("c-s-enter")
+    def _(event):
+        _announce("Ctrl-Shift-Enter")
+
+    print("Try Ctrl-Enter, Shift-Enter, Ctrl-Shift-Enter. Plain Enter submits.")
+    text = prompt("> ", key_bindings=bindings)
+    print(f"You said: {text!r}")
+
+
+if __name__ == "__main__":
+    main()

src/prompt_toolkit/input/ansi_escape_sequences.py

@@ -122,10 +122,17 @@
     "\x1b[23;2~": Keys.F23,
     "\x1b[24;2~": Keys.F24,
     # --
-    # CSI 27 disambiguated modified "other" keys (xterm)
+    # xterm `modifyOtherKeys` CSI 27 disambiguated modified Enter.
+    # prompt_toolkit does not implement xterm's modifyOtherKeys protocol
+    # itself
     # Ref: https://invisible-island.net/xterm/modified-keys.html
-    # These are currently unsupported, so just re-map some common ones to the
-    # unmodified versions
+    # (we disambiguate via the Kitty keyboard protocol instead),
+    # but a user whose terminal or tmux has it enabled independently
+    # will still send these sequences. Map them all to plain Enter so
+    # modifier+Enter at least submits the form, rather than doing
+    # nothing at all. Users who want a distinct Ctrl-Enter / Shift-Enter
+    # binding need a Kitty-capable terminal, where the `CSI u` decoder
+    # produces the richer Keys.
     "\x1b[27;2;13~": Keys.ControlM,  # Shift + Enter
     "\x1b[27;5;13~": Keys.ControlM,  # Ctrl + Enter
     "\x1b[27;6;13~": Keys.ControlM,  # Ctrl + Shift + Enter