the tests

Author: Carreau

docs/pages/advanced_topics/kitty_keyboard_protocol.rst

@@ -166,10 +166,12 @@ 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.
+    ``CSI > <flags> u`` pushes ``<flags>`` onto the terminal's stack so
+    the pop on exit restores the pre-push state. prompt_toolkit always
+    pushes ``flags=1`` (disambiguate). The spec also defines
+    ``CSI = <flags> ; <mode> u`` which *modifies* the top of the stack
+    in place (mode 1 set, 2 OR, 3 AND-NOT); we don't use it because it
+    offers no clean restore.
 
 **Pop flags.**
     ``CSI < u`` pops one entry. ``CSI < N u`` pops N.

src/prompt_toolkit/output/kitty_keyboard.py

@@ -6,10 +6,14 @@
 The protocol exposes progressive enhancement flags that a program pushes
 onto a terminal-maintained stack, then pops on exit:
 
-    CSI = <flags> ; 1 u    — push <flags>, mode 1 (set, not OR/AND)
+    CSI > <flags> u        — push <flags> onto the stack
     CSI < u                — pop one entry
     CSI ? u                — query current flags (response: CSI ? <flags> u)
 
+(`CSI = <flags> ; <mode> u` also exists — it *modifies* the top of the
+stack in place rather than pushing. We want a clean restore on exit, so
+we push.)
+
 Flag bits (from the spec):
 
     0b1     (1)   Disambiguate escape codes
@@ -86,8 +90,8 @@ def kitty_keyboard_protocol(
     # self-contained and the rest of the codebase has no mention of it.
     depth: int = getattr(output, "_kitty_keyboard_depth", 0)
     if depth == 0:
-        # Push: `CSI = <flags> ; 1 u` (mode 1 = set).
-        output.write_raw(f"\x1b[={flags};1u")
+        # Push: `CSI > <flags> u`.
+        output.write_raw(f"\x1b[>{flags}u")
         output.flush()
         output._kitty_keyboard_flags = flags  # type: ignore[attr-defined]
     else:

tests/test_kitty_keyboard.py

@@ -233,7 +233,7 @@ def test_output_push_and_pop():
     with kitty_keyboard_protocol(out):
         pass
     out.flush()
-    assert buf.getvalue() == "\x1b[=1;1u\x1b[<u"
+    assert buf.getvalue() == "\x1b[>1u\x1b[<u"
 
 
 def test_output_custom_flags():
@@ -242,7 +242,7 @@ def test_output_custom_flags():
     with kitty_keyboard_protocol(out, flags=flags):
         pass
     out.flush()
-    assert buf.getvalue() == f"\x1b[={flags};1u\x1b[<u"
+    assert buf.getvalue() == f"\x1b[>{flags}u\x1b[<u"
 
 
 def test_output_nested_does_not_double_push():
@@ -252,7 +252,7 @@ def test_output_nested_does_not_double_push():
             pass
     out.flush()
     # Push once, pop once — nested enter is invisible at the wire level.
-    assert buf.getvalue() == "\x1b[=1;1u\x1b[<u"
+    assert buf.getvalue() == "\x1b[>1u\x1b[<u"
 
 
 def test_output_pop_on_exception():
@@ -270,7 +270,7 @@ def test_output_push_is_flushed_before_yield():
     # stuck in the output buffer.
     buf, out = _buf_output()
     with kitty_keyboard_protocol(out):
-        assert "\x1b[=1;1u" in buf.getvalue()
+        assert "\x1b[>1u" in buf.getvalue()
 
 
 def test_output_nested_with_mismatched_flags_raises():