Merge pull request #5791 from zeertzjq/kitty

Fix kitty keyboard "Report event types" behavior not matching spec
2026-05-11 06:42:32 -07:00
parent 6ba731d73b e0add7fe4b
commit c5c6fc2a64
2 changed files with 138 additions and 25 deletions
@@ -453,9 +453,29 @@ describe('KittyKeyboard', () => {
    describe('event types (press/repeat/release)', () => {
      const flags = KittyKeyboardFlags.DISAMBIGUATE_ESCAPE_CODES | KittyKeyboardFlags.REPORT_EVENT_TYPES;

-      it('press event (default, no suffix)', () => {
+      it('UTF-8 text press event', () => {
        const result = kitty.evaluate(createEvent({ key: 'a' }), flags, KittyKeyboardEventType.PRESS);
-        assert.strictEqual(result.key, '\x1b[97u');
+        assert.strictEqual(result.key, 'a');
+      });
+
+      it('Escape key press event (default, no suffix)', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Escape' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\x1b[27u');
+      });
+
+      it('Enter key press event → legacy \\r', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\r');
+      });
+
+      it('Tab key press event → legacy \\t', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\t');
+      });
+
+      it('Backspace key press event → legacy \\x7f', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\x7f');
      });

      it('press event explicit :1 when modifiers present', () => {
@@ -463,9 +483,29 @@ describe('KittyKeyboard', () => {
        assert.strictEqual(result.key, '\x1b[97;5u');
      });

-      it('repeat event → :2 suffix', () => {
+      it('UTF-8 text repeat event', () => {
        const result = kitty.evaluate(createEvent({ key: 'a' }), flags, KittyKeyboardEventType.REPEAT);
-        assert.strictEqual(result.key, '\x1b[97;1:2u');
+        assert.strictEqual(result.key, 'a');
+      });
+
+      it('Escape key repeat event → :2 suffix', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Escape' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\x1b[27;1:2u');
+      });
+
+      it('Enter key repeat event → legacy \\r', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\r');
+      });
+
+      it('Tab key repeat event → legacy \\t', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\t');
+      });
+
+      it('Backspace key repeat event → legacy \\x7f', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\x7f');
      });

      it('release event → :3 suffix', () => {
@@ -473,6 +513,26 @@ describe('KittyKeyboard', () => {
        assert.strictEqual(result.key, '\x1b[97;1:3u');
      });

+      it('Escape key release event → :3 suffix', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Escape' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, '\x1b[27;1:3u');
+      });
+
+      it('Enter key release event is not reported', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, undefined);
+      });
+
+      it('Tab key release event is not reported', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, undefined);
+      });
+
+      it('Backspace key release event is not reported', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, undefined);
+      });
+
      it('release with modifier → mod:3', () => {
        const result = kitty.evaluate(createEvent({ key: 'a', ctrlKey: true }), flags, KittyKeyboardEventType.RELEASE);
        assert.strictEqual(result.key, '\x1b[97;5:3u');
@@ -563,6 +623,55 @@ describe('KittyKeyboard', () => {
      });
    });

+    describe('REPORT_ALL_KEYS_AS_ESCAPE_CODES flag with REPORT_EVENT_TYPES', () => {
+      const flags = KittyKeyboardFlags.REPORT_ALL_KEYS_AS_ESCAPE_CODES | KittyKeyboardFlags.REPORT_EVENT_TYPES;
+
+      it('Enter key press event → CSI 13 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\x1b[13u');
+      });
+
+      it('Tab key press event → CSI 9 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\x1b[9u');
+      });
+
+      it('Backspace key press event → CSI 127 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.PRESS);
+        assert.strictEqual(result.key, '\x1b[127u');
+      });
+
+      it('Enter key repeat event → CSI 13;1:2 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\x1b[13;1:2u');
+      });
+
+      it('Tab key repeat event → CSI 9;1:2 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\x1b[9;1:2u');
+      });
+
+      it('Backspace key repeat event → CSI 127;1:2 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.REPEAT);
+        assert.strictEqual(result.key, '\x1b[127;1:2u');
+      });
+
+      it('Enter key release event → CSI 13;1:3 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Enter' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, '\x1b[13;1:3u');
+      });
+
+      it('Tab key release event → CSI 9;1:3 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Tab' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, '\x1b[9;1:3u');
+      });
+
+      it('Backspace key release event → CSI 127;1:3 u', () => {
+        const result = kitty.evaluate(createEvent({ key: 'Backspace' }), flags, KittyKeyboardEventType.RELEASE);
+        assert.strictEqual(result.key, '\x1b[127;1:3u');
+      });
+    });
+
    describe('REPORT_ASSOCIATED_TEXT flag', () => {
      const flags = KittyKeyboardFlags.REPORT_ALL_KEYS_AS_ESCAPE_CODES | KittyKeyboardFlags.REPORT_ASSOCIATED_TEXT;

@@ -471,29 +471,33 @@ export class KittyKeyboard {
      return result;
    }

+    // Special handling for Enter/Tab/Backspace.
+    const specialKey = keyCode === 13 || keyCode === 9 || keyCode === 127;
+
+    // Per spec, Enter/Tab/Backspace will not have release events unless "Report all keys as escape
+    // codes" is also set.
+    if (specialKey && eventType === KittyKeyboardEventType.RELEASE && !(flags & KittyKeyboardFlags.REPORT_ALL_KEYS_AS_ESCAPE_CODES)) {
+      return result;
+    }
+
    const isFunc = this._functionalKeyCodes[ev.key] !== undefined || this._getNumpadKeyCode(ev) !== undefined;

-    let useCsiU = false;
-
-    if (flags & KittyKeyboardFlags.REPORT_ALL_KEYS_AS_ESCAPE_CODES) {
-      useCsiU = true;
-    } else if (reportEventTypes) {
-      useCsiU = true;
-    } else if (flags & KittyKeyboardFlags.DISAMBIGUATE_ESCAPE_CODES) {
-      // Per spec, Enter/Tab/Backspace "still generate the same bytes as in legacy
-      // mode" and consider space to be a text-generating key, so these skip the isFunc fast-path
-      // and only get CSI u when modifiers are present (handled below).
-      const isDisambiguateLegacy = keyCode === 13 || keyCode === 9 || keyCode === 127;
-      if (isFunc && !isDisambiguateLegacy) {
-        useCsiU = true;
-      } else if (modifiers > 0) {
-        if (ev.shiftKey && !ev.ctrlKey && !ev.altKey && !ev.metaKey && ev.key.length === 1) {
-          useCsiU = false;
-        } else {
-          useCsiU = true;
-        }
-      }
-    }
+    const useCsiU = !!(
+      flags & KittyKeyboardFlags.REPORT_ALL_KEYS_AS_ESCAPE_CODES ||
+      (reportEventTypes && eventType === KittyKeyboardEventType.RELEASE) ||
+      (flags & KittyKeyboardFlags.DISAMBIGUATE_ESCAPE_CODES &&
+        (
+          // Per spec, Enter/Tab/Backspace "still generate the same bytes as in legacy mode" and
+          // consider space to be a text-generating key, so these skip the isFunc fast-path and only
+          // get CSI u when modifiers are present (handled below).
+          (isFunc && !specialKey) ||
+          (
+            (modifiers > 0 && ev.key.length !== 1) ||
+            modifiers - 1 > KittyKeyboardModifiers.SHIFT
+          )
+        )
+      )
+    );

    if (useCsiU) {
      result.key = this._buildCsiUSequence(ev, keyCode, modifiers, eventType, flags, isFunc, isMod);