@xterm/xterm 6.1.0-beta.98 → 6.1.0-beta.99

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xterm/xterm",
   "description": "Full xterm terminal, in your browser",
-  "version": "6.1.0-beta.98",
+  "version": "6.1.0-beta.99",
   "main": "lib/xterm.js",
   "module": "lib/xterm.mjs",
   "style": "css/xterm.css",
@@ -116,5 +116,5 @@
     "ws": "^8.2.3",
     "xterm-benchmark": "^0.3.1"
   },
-  "commit": "934b5dc8faa8897398075e782f5a246544928feb"
+  "commit": "91c4761b8229e76f420e728b5f6ace1976bd42ec"
 }

package/src/browser/CoreBrowserTerminal.ts

@@ -39,8 +39,9 @@ import { LinkProviderService } from 'browser/services/LinkProviderService';
 import { MouseService } from 'browser/services/MouseService';
 import { RenderService } from 'browser/services/RenderService';
 import { SelectionService } from 'browser/services/SelectionService';
-import { ICharSizeService, ICharacterJoinerService, ICoreBrowserService, ILinkProviderService, IMouseService, IRenderService, ISelectionService, IThemeService } from 'browser/services/Services';
+import { ICharSizeService, ICharacterJoinerService, ICoreBrowserService, IKeyboardService, ILinkProviderService, IMouseService, IRenderService, ISelectionService, IThemeService } from 'browser/services/Services';
 import { ThemeService } from 'browser/services/ThemeService';
+import { KeyboardService } from 'browser/services/KeyboardService';
 import { channels, color } from 'common/Color';
 import { CoreTerminal } from 'common/CoreTerminal';
 import * as Browser from 'common/Platform';
@@ -48,7 +49,6 @@ import { ColorRequestType, CoreMouseAction, CoreMouseButton, CoreMouseEventType,
 import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
 import { IBuffer } from 'common/buffer/Types';
 import { C0, C1_ESCAPED } from 'common/data/EscapeSequences';
-import { evaluateKeyboardEvent } from 'common/input/Keyboard';
 import { toRgbString } from 'common/input/XParseColor';
 import { DecorationService } from 'common/services/DecorationService';
 import { IDecorationService } from 'common/services/Services';
@@ -80,8 +80,9 @@ export class CoreBrowserTerminal extends CoreTerminal implements ITerminal {
   private _customWheelEventHandler: CustomWheelEventHandler | undefined;
 
   // Browser services
-  private _decorationService: DecorationService;
-  private _linkProviderService: ILinkProviderService;
+  private readonly _decorationService: DecorationService;
+  private readonly _keyboardService: IKeyboardService;
+  private readonly _linkProviderService: ILinkProviderService;
 
   // Optional browser services
   private _charSizeService: ICharSizeService | undefined;
@@ -173,6 +174,8 @@ export class CoreBrowserTerminal extends CoreTerminal implements ITerminal {
 
     this._decorationService = this._instantiationService.createInstance(DecorationService);
     this._instantiationService.setService(IDecorationService, this._decorationService);
+    this._keyboardService = this._instantiationService.createInstance(KeyboardService);
+    this._instantiationService.setService(IKeyboardService, this._keyboardService);
     this._linkProviderService = this._instantiationService.createInstance(LinkProviderService);
     this._instantiationService.setService(ILinkProviderService, this._linkProviderService);
     this._linkProviderService.registerLinkProvider(this._instantiationService.createInstance(OscLinkProvider));
@@ -1081,7 +1084,7 @@ export class CoreBrowserTerminal extends CoreTerminal implements ITerminal {
       this._unprocessedDeadKey = true;
     }
 
-    const result = evaluateKeyboardEvent(event, this.coreService.decPrivateModes.applicationCursorKeys, this.browser.isMac, this.options.macOptionIsMeta);
+    const result = this._keyboardService.evaluateKeyDown(event);
 
     this.updateCursorStyle(event);
 
@@ -1109,8 +1112,9 @@ export class CoreBrowserTerminal extends CoreTerminal implements ITerminal {
     }
 
     // HACK: Process A-Z in the keypress event to fix an issue with macOS IMEs where lower case
-    // letters cannot be input while caps lock is on.
-    if (event.key && !event.ctrlKey && !event.altKey && !event.metaKey && event.key.length === 1) {
+    // letters cannot be input while caps lock is on. Skip this hack when using kitty protocol
+    // as it needs to send proper CSI u sequences for all key events.
+    if (!this._keyboardService.useKitty && event.key && !event.ctrlKey && !event.altKey && !event.metaKey && event.key.length === 1) {
       if (event.key.charCodeAt(0) >= 65 && event.key.charCodeAt(0) <= 90) {
         return true;
       }
@@ -1168,6 +1172,12 @@ export class CoreBrowserTerminal extends CoreTerminal implements ITerminal {
       this.focus();
     }
 
+    // Handle key release for Kitty keyboard protocol
+    const result = this._keyboardService.evaluateKeyUp(ev);
+    if (result?.key) {
+      this.coreService.triggerDataEvent(result.key, true);
+    }
+
     this.updateCursorStyle(ev);
     this._keyPressHandled = false;
   }

package/src/browser/services/KeyboardService.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2025 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IKeyboardService } from 'browser/services/Services';
+import { evaluateKeyboardEvent } from 'common/input/Keyboard';
+import { evaluateKeyboardEventKitty, KittyKeyboardEventType, KittyKeyboardFlags, shouldUseKittyProtocol } from 'common/input/KittyKeyboard';
+import { isMac } from 'common/Platform';
+import { ICoreService, IOptionsService } from 'common/services/Services';
+import { IKeyboardResult } from 'common/Types';
+
+export class KeyboardService implements IKeyboardService {
+  public serviceBrand: undefined;
+
+  constructor(
+    @ICoreService private readonly _coreService: ICoreService,
+    @IOptionsService private readonly _optionsService: IOptionsService
+  ) {
+  }
+
+  public evaluateKeyDown(event: KeyboardEvent): IKeyboardResult {
+    const kittyFlags = this._coreService.kittyKeyboard.flags;
+    return this.useKitty
+      ? evaluateKeyboardEventKitty(event, kittyFlags, event.repeat ? KittyKeyboardEventType.REPEAT : KittyKeyboardEventType.PRESS)
+      : evaluateKeyboardEvent(event, this._coreService.decPrivateModes.applicationCursorKeys, isMac, this._optionsService.rawOptions.macOptionIsMeta);
+  }
+
+  public evaluateKeyUp(event: KeyboardEvent): IKeyboardResult | undefined {
+    const kittyFlags = this._coreService.kittyKeyboard.flags;
+    if (this.useKitty && (kittyFlags & KittyKeyboardFlags.REPORT_EVENT_TYPES)) {
+      return evaluateKeyboardEventKitty(event, kittyFlags, KittyKeyboardEventType.RELEASE);
+    }
+    return undefined;
+  }
+
+  public get useKitty(): boolean {
+    const kittyFlags = this._coreService.kittyKeyboard.flags;
+    return !!(this._optionsService.rawOptions.vtExtensions?.kittyKeyboard && shouldUseKittyProtocol(kittyFlags));
+  }
+}

package/src/browser/services/Services.ts

@@ -7,7 +7,7 @@ import { IRenderDimensions, IRenderer } from 'browser/renderer/shared/Types';
 import { IColorSet, ILink, ReadonlyColorSet } from 'browser/Types';
 import { ISelectionRedrawRequestEvent as ISelectionRequestRedrawEvent, ISelectionRequestScrollLinesEvent } from 'browser/selection/Types';
 import { createDecorator } from 'common/services/ServiceRegistry';
-import { AllColorIndex, IDisposable } from 'common/Types';
+import { AllColorIndex, IDisposable, IKeyboardResult } from 'common/Types';
 import type { Event } from 'vs/base/common/event';
 
 export const ICharSizeService = createDecorator<ICharSizeService>('CharSizeService');
@@ -156,3 +156,11 @@ export interface ILinkProviderService extends IDisposable {
 export interface ILinkProvider {
   provideLinks(y: number, callback: (links: ILink[] | undefined) => void): void;
 }
+
+export const IKeyboardService = createDecorator<IKeyboardService>('KeyboardService');
+export interface IKeyboardService {
+  serviceBrand: undefined;
+  evaluateKeyDown(event: KeyboardEvent): IKeyboardResult;
+  evaluateKeyUp(event: KeyboardEvent): IKeyboardResult | undefined;
+  readonly useKitty: boolean;
+}

package/src/common/InputHandler.ts

@@ -270,6 +270,12 @@ export class InputHandler extends Disposable implements IInputHandler {
     this._parser.registerCsiHandler({ intermediates: '$', final: 'p' }, params => this.requestMode(params, true));
     this._parser.registerCsiHandler({ prefix: '?', intermediates: '$', final: 'p' }, params => this.requestMode(params, false));
 
+    // Kitty keyboard protocol handlers
+    this._parser.registerCsiHandler({ prefix: '=', final: 'u' }, params => this.kittyKeyboardSet(params));
+    this._parser.registerCsiHandler({ prefix: '?', final: 'u' }, params => this.kittyKeyboardQuery(params));
+    this._parser.registerCsiHandler({ prefix: '>', final: 'u' }, params => this.kittyKeyboardPush(params));
+    this._parser.registerCsiHandler({ prefix: '<', final: 'u' }, params => this.kittyKeyboardPop(params));
+
     /**
      * execute handler
      */
@@ -2003,6 +2009,12 @@ export class InputHandler extends Disposable implements IInputHandler {
         // FALL-THROUGH
         case 47: // alt screen buffer
         case 1047: // alt screen buffer
+          // Swap kitty keyboard flags: save main, restore alt
+          if (this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+            const state = this._coreService.kittyKeyboard;
+            state.mainFlags = state.flags;
+            state.flags = state.altFlags;
+          }
           this._bufferService.buffers.activateAltBuffer(this._eraseAttrData());
           this._coreService.isCursorInitialized = true;
           this._onRequestRefreshRows.fire(undefined);
@@ -2232,6 +2244,12 @@ export class InputHandler extends Disposable implements IInputHandler {
         // FALL-THROUGH
         case 47: // normal screen buffer
         case 1047: // normal screen buffer - clearing it first
+          // Swap kitty keyboard flags: save alt, restore main
+          if (this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+            const state = this._coreService.kittyKeyboard;
+            state.altFlags = state.flags;
+            state.flags = state.mainFlags;
+          }
           // Ensure the selection manager has the correct buffer
           this._bufferService.buffers.activateNormalBuffer();
           if (params.params[i] === 1049) {
@@ -2654,10 +2672,10 @@ export class InputHandler extends Disposable implements IInputHandler {
       } else if (p === 55) {
         // not overline
         attr.bg &= ~BgFlags.OVERLINE;
-      } else if (p === 221) {
+      } else if (p === 221 && (this._optionsService.rawOptions.vtExtensions?.kittySgrBoldFaintControl ?? true)) {
         // not bold (kitty extension)
         attr.fg &= ~FgFlags.BOLD;
-      } else if (p === 222) {
+      } else if (p === 222 && (this._optionsService.rawOptions.vtExtensions?.kittySgrBoldFaintControl ?? true)) {
         // not faint (kitty extension)
         attr.bg &= ~BgFlags.DIM;
       } else if (p === 59) {
@@ -2984,7 +3002,6 @@ export class InputHandler extends Disposable implements IInputHandler {
     return true;
   }
 
-
   /**
    * OSC 2; <data> ST (set window title)
    *   Proxy to set window title.
@@ -3496,6 +3513,107 @@ export class InputHandler extends Disposable implements IInputHandler {
   public markRangeDirty(y1: number, y2: number): void {
     this._dirtyRowTracker.markRangeDirty(y1, y2);
   }
+
+  // #region Kitty keyboard
+
+  /**
+   * CSI = flags ; mode u
+   * Set Kitty keyboard protocol flags.
+   * mode: 1=set, 2=set-only-specified, 3=reset-only-specified
+   *
+   * @vt: #Y CSI KKBDSET "Kitty Keyboard Set" "CSI = Ps ; Pm u" "Set Kitty keyboard protocol flags."
+   */
+  public kittyKeyboardSet(params: IParams): boolean {
+    if (!this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+      return true;
+    }
+    const flags = params.params[0] || 0;
+    const mode = params.params[1] || 1;
+    const state = this._coreService.kittyKeyboard;
+
+    switch (mode) {
+      case 1: // Set all flags
+        state.flags = flags;
+        break;
+      case 2: // Set only specified flags (OR)
+        state.flags |= flags;
+        break;
+      case 3: // Reset only specified flags (AND NOT)
+        state.flags &= ~flags;
+        break;
+    }
+    return true;
+  }
+
+  /**
+   * CSI ? u
+   * Query Kitty keyboard protocol flags.
+   * Terminal responds with CSI ? flags u
+   *
+   * @vt: #Y CSI KKBDQUERY "Kitty Keyboard Query" "CSI ? u" "Query Kitty keyboard protocol flags."
+   */
+  public kittyKeyboardQuery(params: IParams): boolean {
+    if (!this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+      return true;
+    }
+    const flags = this._coreService.kittyKeyboard.flags;
+    this._coreService.triggerDataEvent(`${C0.ESC}[?${flags}u`);
+    return true;
+  }
+
+  /**
+   * CSI > flags u
+   * Push Kitty keyboard flags onto stack and set new flags.
+   *
+   * @vt: #Y CSI KKBDPUSH "Kitty Keyboard Push" "CSI > Ps u" "Push keyboard flags to stack and set new flags."
+   */
+  public kittyKeyboardPush(params: IParams): boolean {
+    if (!this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+      return true;
+    }
+    const flags = params.params[0] || 0;
+    const state = this._coreService.kittyKeyboard;
+    const isAlt = this._bufferService.buffer === this._bufferService.buffers.alt;
+    const stack = isAlt ? state.altStack : state.mainStack;
+
+    // Evict oldest entry if stack is full (DoS protection, limit of 16)
+    if (stack.length >= 16) {
+      stack.shift();
+    }
+
+    // Push current flags onto stack and set new flags
+    stack.push(state.flags);
+    state.flags = flags;
+    return true;
+  }
+
+  /**
+   * CSI < count u
+   * Pop Kitty keyboard flags from stack.
+   *
+   * @vt: #Y CSI KKBDPOP "Kitty Keyboard Pop" "CSI < Ps u" "Pop keyboard flags from stack."
+   */
+  public kittyKeyboardPop(params: IParams): boolean {
+    if (!this._optionsService.rawOptions.vtExtensions?.kittyKeyboard) {
+      return true;
+    }
+    const count = Math.max(1, params.params[0] || 1);
+    const state = this._coreService.kittyKeyboard;
+    const isAlt = this._bufferService.buffer === this._bufferService.buffers.alt;
+    const stack = isAlt ? state.altStack : state.mainStack;
+
+    // Pop specified number of entries from stack
+    for (let i = 0; i < count && stack.length > 0; i++) {
+      state.flags = stack.pop()!;
+    }
+    // If stack is empty after popping, reset to 0
+    if (stack.length === 0 && count > 0) {
+      state.flags = 0;
+    }
+    return true;
+  }
+
+  // #endregion
 }
 
 export interface IDirtyRowTracker {

package/src/common/Types.ts

@@ -277,6 +277,23 @@ export interface IDecPrivateModes {
   wraparound: boolean; // defaults: xterm - true, vt100 - false
 }
 
+/**
+ * Kitty keyboard protocol state.
+ * Maintains per-screen stacks of enhancement flags.
+ */
+export interface IKittyKeyboardState {
+  /** Current active enhancement flags (for current screen) */
+  flags: number;
+  /** Saved flags for main screen when alt is active */
+  mainFlags: number;
+  /** Saved flags for alternate screen when main is active */
+  altFlags: number;
+  /** Stack of flags for main screen */
+  mainStack: number[];
+  /** Stack of flags for alternate screen */
+  altStack: number[];
+}
+
 export interface IRowRange {
   start: number;
   end: number;

package/src/common/Version.ts

@@ -6,4 +6,4 @@
 /**
  * The xterm.js version. This is updated by the publish script from package.json.
  */
-export const XTERM_VERSION = '6.1.0-beta.98';
+export const XTERM_VERSION = '6.1.0-beta.99';