@theia/core 1.77.0-next.56 → 1.77.0-next.57

package/src/common/keys.ts

@@ -75,7 +75,7 @@ export namespace KeySequence {
 
     export function parse(keybinding: string): KeySequence {
         const keyCodes = [];
-        const rawKeyCodes = keybinding.trim().split(/\s+/g);
+        const rawKeyCodes = splitKeySequence(keybinding.trim());
         for (const rawKeyCode of rawKeyCodes) {
             const keyCode = KeyCode.parse(rawKeyCode);
             if (keyCode !== undefined) {
@@ -97,6 +97,35 @@ export interface Keystroke {
     readonly modifiers?: KeyModifier[];
 }
 
+/**
+ * The keyboard-layout modifier layer used to produce a logical character, ordered by resolution cost.
+ */
+export type LayoutModifiers = 'none' | 'shift' | 'altGraph' | 'shiftAltGraph';
+
+export function layoutModifiersIncludeShift(layoutModifiers: LayoutModifiers): boolean {
+    return layoutModifiers === 'shift' || layoutModifiers === 'shiftAltGraph';
+}
+
+export function layoutModifiersIncludeAltGraph(layoutModifiers: LayoutModifiers): boolean {
+    return layoutModifiers === 'altGraph' || layoutModifiers === 'shiftAltGraph';
+}
+
+export function isPrintableKey(key: Key): boolean {
+    return isPrintableCharacter(key.easyString);
+}
+
+export function isPrintableCharacter(character: string | undefined): character is string {
+    return !!character && character !== ' ' && isSingleCharacter(character);
+}
+
+/**
+ * Identifies how a key code was derived for runtime matching.
+ * `authored` is the constructor default and represents an authored binding, even for manually constructed instances.
+ * `commandModifiers` preserves the event's modifiers as command modifiers, while `layoutModifiers` attributes them to
+ * the keyboard layout's character-producing layer.
+ */
+export type KeyCodeInterpretation = 'authored' | 'commandModifiers' | 'layoutModifiers';
+
 export interface KeyCodeSchema {
     key?: Partial<Key>;
     ctrl?: boolean;
@@ -104,6 +133,180 @@ export interface KeyCodeSchema {
     alt?: boolean;
     meta?: boolean;
     character?: string;
+    layoutModifiers?: LayoutModifiers;
+    interpretation?: KeyCodeInterpretation;
+    supportedByLayout?: boolean;
+    authoredToken?: string;
+    physical?: boolean;
+}
+
+/**
+ * Plain keyboard input data used by keybinding dispatch and diagnostics.
+ */
+export interface NormalizedKeyboardInput {
+    key?: string;
+    code?: string;
+    keyCode?: number;
+    charCode?: number;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    altGraph?: boolean;
+    repeat?: boolean;
+    isComposing?: boolean;
+    location?: number;
+    timeStamp?: number;
+    keyIdentifier?: string;
+    getModifierState?(keyArg: string): boolean;
+}
+
+/**
+ * Read AltGraph state, preferring explicitly transported state over native event state.
+ */
+export function readAltGraph(input: NormalizedKeyboardInput): boolean {
+    if (input.altGraph !== undefined) {
+        return input.altGraph;
+    }
+    return input.getModifierState?.('AltGraph') ?? false;
+}
+
+/**
+ * Copy native or transported keyboard input into a normalized, transport-independent representation.
+ * The parameter and result share this type because a native `KeyboardEvent` structurally satisfies the permissive input
+ * shape. The returned data always has AltGraph resolved even though the field is optional in the input type.
+ * `getModifierState` is retained for local diagnostics only and must not be relied on after transport.
+ */
+export function normalizeKeyboardInput(input: NormalizedKeyboardInput): NormalizedKeyboardInput {
+    return {
+        key: input.key,
+        code: input.code,
+        keyCode: input.keyCode,
+        charCode: input.charCode,
+        ctrlKey: input.ctrlKey,
+        shiftKey: input.shiftKey,
+        altKey: input.altKey,
+        metaKey: input.metaKey,
+        altGraph: readAltGraph(input),
+        repeat: input.repeat,
+        isComposing: input.isComposing,
+        location: input.location,
+        timeStamp: input.timeStamp,
+        keyIdentifier: input.keyIdentifier,
+        getModifierState: input.getModifierState?.bind(input)
+    };
+}
+
+function splitKeySequence(keybinding: string): string[] {
+    const result: string[] = [];
+    let current = '';
+    let bracketed = false;
+    for (let index = 0; index < keybinding.length; index++) {
+        const character = keybinding[index];
+        if (character === '[') {
+            const closingBracket = keybinding.indexOf(']', index + 1);
+            const nextWhitespace = keybinding.slice(index + 1).search(/\s/);
+            bracketed = closingBracket !== -1 && (nextWhitespace === -1 || closingBracket < index + 1 + nextWhitespace);
+        } else if (character === ']' && bracketed) {
+            bracketed = false;
+        }
+        if (/\s/.test(character) && !bracketed) {
+            if (current) {
+                result.push(current);
+                current = '';
+            }
+        } else {
+            current += character;
+        }
+    }
+    if (current) {
+        result.push(current);
+    }
+    return result;
+}
+
+function splitKeyCode(keybinding: string): string[] {
+    const result: string[] = [];
+    let current = '';
+    let bracketed = false;
+    for (let index = 0; index < keybinding.length; index++) {
+        const character = keybinding[index];
+        if (character === '[' && keybinding.indexOf(']', index + 1) !== -1) {
+            bracketed = true;
+        } else if (character === ']' && bracketed) {
+            bracketed = false;
+        }
+        if (!bracketed && current && (character === '+' || character === '-')) {
+            result.push(current);
+            current = '';
+        } else if (!bracketed && character === '+') {
+            continue;
+        } else {
+            current += character;
+        }
+    }
+    if (current) {
+        result.push(current);
+    }
+    return result;
+}
+
+function parseScanCode(token: string): Key | undefined {
+    const match = /^\[([^\]]+)\]$/.exec(token);
+    if (!match || match[1].toLocaleLowerCase().startsWith('char:')) {
+        return undefined;
+    }
+    const key = Key.getKey(match[1]) ?? Object.values(CODE_TO_KEY).find(candidate => candidate.code.toLocaleLowerCase() === match[1].toLocaleLowerCase());
+    if (!key) {
+        throw new Error(nls.localize('theia/core/keybinding/unknownScanCode', 'Unknown scan code {0}. Use a supported KeyboardEvent.code name.', match[1]));
+    }
+    return key;
+}
+
+/** Parse a logical-character token, rejecting bare grammar delimiters. */
+function parseCharacterToken(token: string): string | undefined {
+    const match = /^\[char:(.*)\]$/i.exec(token);
+    if (match) {
+        const payload = match[1];
+        let character: string;
+        if (/^0x[0-9a-f]+$/i.test(payload)) {
+            const value = Number.parseInt(payload.slice(2), 16);
+            if (value > 0x10ffff || value >= 0xd800 && value <= 0xdfff) {
+                throw new Error(nls.localize('theia/core/keybinding/invalidCharacter', 'Invalid Unicode character {0}.', payload));
+            }
+            character = String.fromCodePoint(value);
+        } else {
+            character = payload;
+        }
+        if (!isSingleCharacter(character) || !/^0x/i.test(payload) && RESERVED_BARE_CHARACTERS.has(character)) {
+            throw new Error(nls.localize('theia/core/keybinding/invalidCharacter', 'Invalid Unicode character {0}.', payload));
+        }
+        return character;
+    }
+    return isSingleCharacter(token) && !RESERVED_BARE_CHARACTERS.has(token) ? token : undefined;
+}
+
+function isSingleCharacter(value: string): boolean {
+    return Array.from(value).length === 1;
+}
+
+/** Characters reserved by the keybinding grammar and therefore unavailable as bare logical-character tokens. */
+const RESERVED_BARE_CHARACTERS = new Set([' ', '+', '-', '[', ']']);
+
+/**
+ * Serialize a logical character for the keybinding grammar.
+ * `+` and `-` are excluded from legacy bare spelling because they delimit key-code tokens. Uppercase ASCII letters are
+ * escaped so their case is not lost by case-insensitive legacy key lookup.
+ */
+export function characterToken(character: string): string {
+    if (!isSingleCharacter(character)) {
+        throw new Error(nls.localize('theia/core/keybinding/invalidCharacter', 'Invalid Unicode character {0}.', character));
+    }
+    const legacyCharacter = !!EASY_TO_KEY[character] && character !== '+' && character !== '-';
+    const requiresEscape = /^[A-Z]$/.test(character) || RESERVED_BARE_CHARACTERS.has(character) && !legacyCharacter;
+    return requiresEscape
+        ? `[char:0x${character.codePointAt(0)!.toString(16).toUpperCase()}]`
+        : character;
 }
 
 /**
@@ -117,6 +320,13 @@ export class KeyCode {
     public readonly alt: boolean;
     public readonly meta: boolean;
     public readonly character: string | undefined;
+    public readonly layoutModifiers: LayoutModifiers;
+    public readonly interpretation: KeyCodeInterpretation;
+    /** Whether the authored logical character is available on the active keyboard layout. */
+    public readonly supportedByLayout: boolean;
+    public readonly authoredToken: string | undefined;
+    /** Whether the authored token denotes a physical scan code rather than a logical character. */
+    public readonly physical: boolean;
 
     public constructor(schema: KeyCodeSchema) {
         const key = schema.key;
@@ -134,13 +344,18 @@ export class KeyCode {
         this.alt = !!schema.alt;
         this.meta = !!schema.meta;
         this.character = schema.character;
+        this.layoutModifiers = schema.layoutModifiers ?? 'none';
+        this.interpretation = schema.interpretation ?? 'authored';
+        this.supportedByLayout = schema.supportedByLayout !== false;
+        this.authoredToken = schema.authoredToken;
+        this.physical = !!schema.physical;
     }
 
     /**
      * Return true if this KeyCode only contains modifiers.
      */
     public isModifierOnly(): boolean {
-        return this.key === undefined;
+        return this.key === undefined && this.character === undefined;
     }
 
     /**
@@ -150,11 +365,11 @@ export class KeyCode {
         if (this.key && (!other.key || this.key.code !== other.key.code) || !this.key && other.key) {
             return false;
         }
-        return this.ctrl === other.ctrl && this.alt === other.alt && this.shift === other.shift && this.meta === other.meta;
+        return this.dispatchString() === other.dispatchString();
     }
 
-    /*
-     * Return a keybinding string compatible with the `Keybinding.keybinding` property.
+    /**
+     * Return a keybinding string that round-trips the authored spelling through {@link authoredToken}.
      */
     toString(): string {
         const result = [];
@@ -170,8 +385,69 @@ export class KeyCode {
         if (this.ctrl) {
             result.push(Key.CONTROL_LEFT.easyString);
         }
+        if (this.authoredToken) {
+            result.push(this.authoredToken);
+        } else if (this.key) {
+            result.push(this.key.easyString);
+        }
+        return result.join('+');
+    }
+
+    /**
+     * Return the runtime match identity used for keybinding dispatch.
+     * The interpretation is diagnostic metadata and does not affect this identity.
+     */
+    dispatchString(): string {
+        const result: string[] = [];
+        if (this.meta) {
+            result.push(SpecialCases.META);
+        }
+        if (this.shift) {
+            result.push(Key.SHIFT_LEFT.easyString);
+        }
+        if (this.alt) {
+            result.push(Key.ALT_LEFT.easyString);
+        }
+        if (this.ctrl) {
+            result.push(Key.CONTROL_LEFT.easyString);
+        }
         if (this.key) {
             result.push(this.key.easyString);
+        } else if (this.character) {
+            result.push(characterToken(this.character));
+        }
+        const suffix = this.layoutModifiers === 'shift' ? '@shift'
+            : this.layoutModifiers === 'altGraph' ? '@altgraph'
+                : this.layoutModifiers === 'shiftAltGraph' ? '@shift@altgraph' : '';
+        return result.join('+') + suffix;
+    }
+
+    /**
+     * Derive an authored keybinding stroke from a key event for recorder persistence.
+     * This cannot use {@link toString}: event-derived key codes have no {@link authoredToken}, so `toString` would persist
+     * the physical US key name instead of the committed logical character. Non-printable keys, Space and numpad keys are
+     * persisted by name; printable keys without a committed character are persisted as scan codes.
+     */
+    toAuthoredKeybindingString(): string {
+        const result: string[] = [];
+        if (this.meta) {
+            result.push(SpecialCases.META);
+        }
+        const character = isPrintableCharacter(this.character) && !this.key?.code.startsWith('Numpad') ? this.character : undefined;
+        const shiftedLetter = !!character && /^[A-Z]$/.test(character);
+        if (this.shift && (!character || shiftedLetter)) {
+            result.push(Key.SHIFT_LEFT.easyString);
+        }
+        if (this.alt) {
+            result.push(Key.ALT_LEFT.easyString);
+        }
+        if (this.ctrl) {
+            result.push(Key.CONTROL_LEFT.easyString);
+        }
+        if (character) {
+            result.push(characterToken(shiftedLetter ? character.toLocaleLowerCase() : character));
+        } else if (this.key) {
+            result.push(isPrintableKey(this.key) ? `[${this.key.code}]` : this.key.easyString);
         }
         return result.join('+');
     }
@@ -179,7 +455,7 @@ export class KeyCode {
     /**
      * Create a KeyCode from one of several input types.
      */
-    public static createKeyCode(input: KeyboardEvent | Keystroke | KeyCodeSchema | string, eventDispatch: 'code' | 'keyCode' = 'code'): KeyCode {
+    public static createKeyCode(input: KeyboardEvent | NormalizedKeyboardInput | Keystroke | KeyCodeSchema | string, eventDispatch: 'code' | 'keyCode' = 'code'): KeyCode {
         if (typeof input === 'string') {
             const parts = input.split('+');
             if (!KeyCode.isModifierString(parts[0])) {
@@ -189,7 +465,7 @@ export class KeyCode {
                 });
             }
             return KeyCode.createKeyCode({ modifiers: parts as KeyModifier[] });
-        } else if (KeyCode.isKeyboardEvent(input)) {
+        } else if (KeyCode.isKeyboardEvent(input) || KeyCode.isNormalizedKeyboardInput(input)) {
             const key = KeyCode.toKey(input, eventDispatch);
             return new KeyCode({
                 key: Key.isModifier(key.code) ? undefined : key,
@@ -238,25 +514,14 @@ export class KeyCode {
         }
 
         const schema: KeyCodeSchema = {};
-        const keys = [];
-        let currentKey = '';
-        for (const character of keybinding.trim().toLowerCase()) {
-            if (currentKey && (character === '-' || character === '+')) {
-                keys.push(currentKey);
-                currentKey = '';
-            } else if (character !== '+') {
-                currentKey += character;
-            }
-        }
-        if (currentKey) {
-            keys.push(currentKey);
-        }
+        const keys = splitKeyCode(keybinding.trim());
         /* If duplicates i.e ctrl+ctrl+a or alt+alt+b or b+alt+b it is invalid */
-        if (keys.length !== new Set(keys).size) {
+        if (keys.length !== new Set(keys.map(key => key.toLocaleLowerCase())).size) {
             throw new Error(nls.localize('theia/core/keybinding/duplicateModifierError', "Can't parse keybinding {0} Duplicate modifiers", keybinding));
         }
 
-        for (let keyString of keys) {
+        for (const token of keys) {
+            let keyString = token.toLocaleLowerCase();
             if (SPECIAL_ALIASES[keyString] !== undefined) {
                 keyString = SPECIAL_ALIASES[keyString];
             }
@@ -289,7 +554,20 @@ export class KeyCode {
                     schema.key = key;
                 }
             } else {
-                throw new Error(nls.localize('theia/core/keybinding/unrecognizedKeyError', 'Unrecognized key {0} in {1}', keyString, keybinding));
+                const scanCode = parseScanCode(token);
+                if (scanCode) {
+                    schema.key = scanCode;
+                    schema.authoredToken = `[${scanCode.code}]`;
+                    schema.physical = true;
+                    continue;
+                }
+                const character = parseCharacterToken(token);
+                if (character) {
+                    schema.character = character;
+                    schema.authoredToken = characterToken(character);
+                    continue;
+                }
+                throw new Error(nls.localize('theia/core/keybinding/unrecognizedKeyError', 'Unrecognized key {0} in {1}', token, keybinding));
             }
         }
 
@@ -339,6 +617,13 @@ export namespace KeyCode {
         return false;
     }
 
+    /**
+     * Return true if the given object carries normalized keyboard input fields.
+     */
+    export function isNormalizedKeyboardInput(input: object): input is NormalizedKeyboardInput {
+        return 'code' in input || 'keyCode' in input || 'charCode' in input || 'keyIdentifier' in input;
+    }
+
     /**
      * Determine the pressed key of a keyboard event. This key should correspond to the physical key according
      * to a standard US keyboard layout. International keyboard layouts are handled by `KeyboardLayoutService`.
@@ -346,7 +631,7 @@ export namespace KeyCode {
      * `keyIdentifier` is used to access this deprecated field:
      * https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyIdentifier
      */
-    export function toKey(event: KeyboardEvent, dispatch: 'code' | 'keyCode' = 'code'): Key {
+    export function toKey(event: NormalizedKeyboardInput, dispatch: 'code' | 'keyCode' = 'code'): Key {
         const code = event.code;
         if (code && dispatch === 'code') {
             if (isOSX) {
@@ -382,7 +667,7 @@ export namespace KeyCode {
             }
         }
 
-        const keyIdentifier = (event as KeyboardEvent & { keyIdentifier?: string }).keyIdentifier;
+        const keyIdentifier = event.keyIdentifier;
         if (keyIdentifier) {
             const key = Key.getKey(keyIdentifier);
             if (key) {
@@ -397,7 +682,7 @@ export namespace KeyCode {
      * If the key does not correspond to a printable character, `undefined` is returned.
      * The result may be altered by modifier keys.
      */
-    export function toCharacter(event: KeyboardEvent): string | undefined {
+    export function toCharacter(event: NormalizedKeyboardInput): string | undefined {
         const key = event.key;
         // Use the key property if it contains exactly one unicode character
         if (key && Array.from(key).length === 1) {

package/src/common/ternary-search-tree.spec.ts

@@ -15,6 +15,7 @@
 // *****************************************************************************
 
 import { expect } from 'chai';
+import * as sinon from 'sinon';
 import { TernarySearchTree, KeySequenceIterator } from './ternary-search-tree';
 import { KeyCode, KeySequence, Key, KeyModifier } from './keys';
 
@@ -69,6 +70,19 @@ describe('KeySequenceIterator', () => {
         // Different value should return non-zero
         expect(iterator.cmp('different')).to.not.equal(0);
     });
+
+    it('should use dispatch identity for values and comparisons', () => {
+        const keyCode = KeyCode.createKeyCode({ first: Key.KEY_A, modifiers: [KeyModifier.CtrlCmd] });
+        const dispatchString = sinon.stub(keyCode, 'dispatchString').returns('dispatch-a');
+        const toString = sinon.stub(keyCode, 'toString').returns('serialized-a');
+
+        iterator.reset([keyCode]);
+
+        expect(iterator.value()).to.equal('dispatch-a');
+        expect(iterator.cmp('dispatch-a')).to.equal(0);
+        expect(dispatchString.called).to.be.true;
+        expect(toString.called).to.be.false;
+    });
 });
 
 describe('TernarySearchTree for KeySequences', () => {

package/src/common/ternary-search-tree.ts

@@ -208,12 +208,12 @@ export class KeySequenceIterator implements IKeyIterator<KeySequence> {
     }
 
     cmp(a: string): number {
-        const current = this._value[this._index]?.toString() ?? '';
+        const current = this._value[this._index]?.dispatchString() ?? '';
         return compare(a, current);
     }
 
     value(): string {
-        return this._value[this._index]?.toString() ?? '';
+        return this._value[this._index]?.dispatchString() ?? '';
     }
 }
 

package/src/electron-browser/keyboard/electron-keyboard-module.spec.ts

@@ -0,0 +1,29 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { NativeKeyboardLayout } from '../../common/keyboard/keyboard-layout-provider';
+import { createElectronKeyboardLayoutProvider } from './electron-keyboard-module';
+
+describe('Electron keyboard layout provider', () => {
+    it('reports the native-keymap source and delegates layout retrieval', async () => {
+        const layout: NativeKeyboardLayout = { info: { id: 'test', lang: 'en' }, mapping: {} };
+        const provider = createElectronKeyboardLayoutProvider({ getNativeLayout: async () => layout });
+
+        expect(provider.layoutSource).to.equal('native-keymap');
+        expect(await provider.getNativeLayout()).to.equal(layout);
+    });
+});

package/src/electron-browser/keyboard/electron-keyboard-module.ts

@@ -19,10 +19,17 @@ import { KeyboardLayoutProvider, keyboardPath, KeyboardLayoutChangeNotifier } fr
 import { WebSocketConnectionProvider } from '../../browser/messaging/ws-connection-provider';
 import { ElectronKeyboardLayoutChangeNotifier } from './electron-keyboard-layout-change-notifier';
 
+export function createElectronKeyboardLayoutProvider(delegate: KeyboardLayoutProvider): KeyboardLayoutProvider {
+    return {
+        layoutSource: 'native-keymap',
+        getNativeLayout: () => delegate.getNativeLayout()
+    };
+}
+
 export default new ContainerModule((bind, unbind, isBound, rebind) => {
-    bind(KeyboardLayoutProvider).toDynamicValue(ctx =>
+    bind(KeyboardLayoutProvider).toDynamicValue(ctx => createElectronKeyboardLayoutProvider(
         WebSocketConnectionProvider.createLocalProxy<KeyboardLayoutProvider>(ctx.container, keyboardPath)
-    ).inSingletonScope();
+    )).inSingletonScope();
     bind(ElectronKeyboardLayoutChangeNotifier).toSelf().inSingletonScope();
     bind(KeyboardLayoutChangeNotifier).toService(ElectronKeyboardLayoutChangeNotifier);
 });

package/src/electron-browser/menu/electron-main-menu-factory.ts

@@ -22,7 +22,7 @@ import { CommonCommands } from '../../browser';
 import debounce = require('lodash.debounce');
 import { BrowserMainMenuFactory } from '../../browser/menu/browser-menu-plugin';
 import { ContextMatcher } from '../../browser/context-key-service';
-import { MenuDto, MenuRole } from '../../electron-common/electron-api';
+import { electronMenuAcceleratorMetadata, MenuDto, MenuRole } from '../../electron-common/electron-api';
 
 /**
  * Representation of possible electron menu options.
@@ -249,7 +249,7 @@ export class ElectronMainMenuFactory extends BrowserMainMenuFactory {
                 return parentItems;
             }
 
-            const accelerator = AcceleratorSource.is(menu) ? menu.getAccelerator(options.context).join(' ') : undefined;
+            const acceleratorSequence = AcceleratorSource.is(menu) ? menu.getAccelerator(options.context, 'physical') : [];
 
             const menuItem: MenuDto = {
                 id: menu.id,
@@ -258,7 +258,7 @@ export class ElectronMainMenuFactory extends BrowserMainMenuFactory {
                 checked: menu.isToggled(effectivePath, ...args),
                 enabled: !honorDisabled || menu.isEnabled(effectivePath, ...args), // see https://github.com/eclipse-theia/theia/issues/446
                 visible: true,
-                accelerator,
+                ...electronMenuAcceleratorMetadata(acceleratorSequence),
                 execute: async () => {
                     const wasToggled = menuItem.checked;
                     await menu.run(effectivePath, ...args);

package/src/electron-browser/menu/electron-menu-contribution.ts

@@ -362,6 +362,10 @@ export class ElectronMenuContribution extends BrowserMenuBarContribution impleme
                 command: ElectronCommands.RELOAD.id,
                 keybinding: 'ctrlcmd+r'
             },
+            {
+                command: ElectronCommands.ZOOM_IN.id,
+                keybinding: 'ctrlcmd+[char:0x2B]'
+            },
             {
                 command: ElectronCommands.ZOOM_IN.id,
                 keybinding: 'ctrlcmd+='

package/src/electron-common/electron-api.spec.ts

@@ -0,0 +1,42 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { electronMenuAccelerator, electronMenuAcceleratorMetadata, isElectronAcceleratorRepresentable } from './electron-api';
+
+describe('Electron menu accelerators', () => {
+    it('accepts only ASCII accelerators without AltGr', () => {
+        expect(isElectronAcceleratorRepresentable('Ctrl+8')).to.be.true;
+        expect(isElectronAcceleratorRepresentable('Ctrl+AltGr+8')).to.be.false;
+        expect(isElectronAcceleratorRepresentable('Ctrl+ä')).to.be.false;
+        expect(isElectronAcceleratorRepresentable('Ctrl++')).to.be.false;
+        expect(isElectronAcceleratorRepresentable('Ctrl+K Ctrl+S')).to.be.false;
+    });
+
+    it('forwards renderer accelerator text without precomputing representability', () => {
+        expect(electronMenuAcceleratorMetadata(['Ctrl+8'])).to.deep.equal({ accelerator: 'Ctrl+8' });
+        expect(electronMenuAcceleratorMetadata(['Ctrl+K', 'Ctrl+S'])).to.deep.equal({ accelerator: 'Ctrl+K Ctrl+S' });
+    });
+
+    it('omits unrepresentable accelerators', () => {
+        expect(electronMenuAccelerator({ accelerator: 'Ctrl+AltGr+8' })).to.deep.equal({});
+        expect(electronMenuAccelerator({ accelerator: 'Ctrl+K Ctrl+S' })).to.deep.equal({});
+    });
+
+    it('returns representable accelerators', () => {
+        expect(electronMenuAccelerator({ accelerator: 'Ctrl+8' })).to.deep.equal({ accelerator: 'Ctrl+8' });
+    });
+});

package/src/electron-common/electron-api.ts

@@ -22,6 +22,29 @@ import { LaunchArguments } from '../common/launch-arguments';
 
 export type MenuRole = ('undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'selectAll' | 'about' | 'services' | 'hide' | 'hideOthers' | 'unhide' | 'quit');
 
+export function isElectronAcceleratorRepresentable(accelerator: string | undefined): accelerator is string {
+    if (!accelerator || /altgr/i.test(accelerator) || /\s/.test(accelerator) || accelerator.split('+').some(token => !token)) {
+        return false;
+    }
+    for (let i = 0; i < accelerator.length; i++) {
+        if (accelerator.charCodeAt(i) > 127) {
+            return false;
+        }
+    }
+    return true;
+}
+
+export type ElectronMenuAccelerator = Pick<MenuDto, 'accelerator'>;
+
+export function electronMenuAcceleratorMetadata(acceleratorSequence: string[]): ElectronMenuAccelerator {
+    return { accelerator: acceleratorSequence.join(' ') || undefined };
+}
+
+/** Return an Electron accelerator only when the rendered single chord is representable. */
+export function electronMenuAccelerator(dto: ElectronMenuAccelerator): ElectronMenuAccelerator {
+    return isElectronAcceleratorRepresentable(dto.accelerator) ? { accelerator: dto.accelerator } : {};
+}
+
 export interface MenuDto {
     id?: string,
     label?: string,