[Bug]: Keybindings Editor does not respect users keyboard layout

[mbeckenbach]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/desktop

Steps to reproduce

1. Use a non english keyboard layout (e.g. German Mac)
2. Try to change a hotkey in settings (e.g. use shift+#)

Note: Same issue applies to the Snapshots feature hotkey editing.

Expected behavior

The UI should receive and display the actual kex/compo pressed on my physical keyboard.

Actual behavior

Hotkey from my example using german keyboard (shift+#) gets mapped to shift+\ which indicates a english/us keyboard layout.

Impact

Minor bug or occasional failure

Version or commit

0.0.43-nightly.20260923.2135

Environment

macOS 27

Logs or stack traces

Screenshots, recordings, or supporting files

No response

Workaround

No response

[juliusmarminge]

Triage

Confirmed on current main (f5ef0ddb9). The nightly in this report (0.0.43-nightly.20260923.2135) already contains it. Not already fixed.

What you reported. On a German Mac layout, recording Shift plus the # key in Settings → Keybindings shows shift+\. The same recorder is used for SnapShots. Letters are fine. This key is not.

That is what the recorder does. On the German ISO layout (including German on macOS), the key left of Return is labeled # unshifted and ' with Shift. The browser reports that physical key as KeyboardEvent.code === "Backslash". The recorder throws away both # and ' and stores the US name of that code, \, then adds shift because Shift was held. shift+\ is the only value in the shortcut map that produces a backslash.

What the code does

1. Any non-letter in the US code map is stored as the US glyph.

shortcutKeyFromEvent keeps event.key only when it is a–z. Everything else in EVENT_CODE_SHORTCUT_KEYS is replaced by the US character for that code:

t3code/apps/web/src/keybindings.ts

Lines 59 to 94 in f5ef0dd

	const EVENT_CODE_SHORTCUT_KEYS: Readonly<Record<string, string>> = {
	Backquote: "`",
	Backslash: "\\",
	BracketLeft: "[",
	BracketRight: "]",
	Comma: ",",
	Digit0: "0",
	Digit1: "1",
	Digit2: "2",
	Digit3: "3",
	Digit4: "4",
	Digit5: "5",
	Digit6: "6",
	Digit7: "7",
	Digit8: "8",
	Digit9: "9",
	Equal: "=",
	Minus: "-",
	Period: ".",
	Quote: "'",
	Semicolon: ";",
	Slash: "/",
	};
	function normalizeEventKey(key: string): string {
	const normalized = key.toLowerCase();
	if (normalized === "esc") return "escape";
	return normalized;
	}
	export function shortcutKeyFromEvent(event: Pick<ShortcutEventLike, "key" | "code">): string {
	const layoutKey = normalizeEventKey(event.key);
	if (/^[a-z]$/.test(layoutKey)) return layoutKey;
	const physicalKey = event.code ? EVENT_CODE_SHORTCUT_KEYS[event.code] : undefined;
	return physicalKey ?? layoutKey;
	}

Backslash is hardcoded to \. BracketLeft is [, Quote is ', Semicolon is ;, and the digit row is 0–9. A German ü key (BracketLeft) is recorded as [. The # key is recorded as \.

Latin letters stay layout-aware. That split landed in #4469. The punctuation table was expanded later in #8103 (2026-09-08), which is what turns this key into \.

2. Settings and SnapShots both save that string.

The keybinding editor writes it straight into the draft:

t3code/apps/web/src/components/settings/KeybindingsSettings.logic.ts

Lines 334 to 355 in f5ef0dd

	export function keybindingFromKeyboardEvent(
	event: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">,
	platform: string,
	): string | null {
	const keyToken = normalizeShortcutKeyToken(shortcutKeyFromEvent(event));
	if (!keyToken) return null;
	const parts: string[] = [];
	if (isMacPlatform(platform)) {
	if (event.metaKey) parts.push("mod");
	if (event.ctrlKey) parts.push("ctrl");
	} else {
	if (event.ctrlKey) parts.push("mod");
	if (event.metaKey) parts.push("meta");
	}
	if (event.altKey) parts.push("alt");
	if (event.shiftKey) parts.push("shift");
	if (parts.length === 0) {
	return null;
	}
	parts.push(keyToken);
	return parts.join("+");

t3code/apps/web/src/components/settings/KeybindingsSettings.tsx

Lines 770 to 779 in f5ef0dd

	const captureKeybinding = (event: KeyboardEvent<HTMLInputElement>) => {
	if (event.key === "Tab") return;
	event.preventDefault();
	if (event.key === "Escape") {
	setDraft({ keyDraft: row.key, isRecording: false });
	return;
	}
	const next = keybindingFromKeyboardEvent(event.nativeEvent, navigator.platform);
	if (!next) return;
	setDraft({ keyDraft: next, isRecording: false });

SnapShots call the same function:

t3code/apps/web/src/components/settings/useSnapShotShortcutRecorder.tsx

Line 109 in f5ef0dd

const input = keybindingFromKeyboardEvent(event, navigator.platform);

The project-script shortcut field does too (projectScriptEditor.tsx). One recorder, three surfaces.

The capture tests lock this in. Shift plus a key whose layout character is @ or " is saved as mod+shift+2 or mod+shift+', from Digit2 / Quote, not from the character you typed:

t3code/apps/web/src/components/settings/KeybindingsSettings.logic.test.ts

Lines 98 to 116 in f5ef0dd

	it.each([
	["@", "Digit2", "mod+shift+2"],
	['"', "Digit2", "mod+shift+2"],
	["@", "Quote", "mod+shift+'"],
	])("captures %s at %s by physical key", (key, code, expected) => {
	expect(
	keybindingFromKeyboardEvent(
	{
	key,
	code,
	metaKey: true,
	ctrlKey: false,
	altKey: false,
	shiftKey: true,
	},
	"MacIntel",
	),
	).toBe(expected);
	});

3. The saved chord still fires on that physical key.

Runtime matching keeps event.key and also adds the US code alias:

t3code/apps/web/src/keybindings.ts

Lines 96 to 109 in f5ef0dd

	function resolveEventKeys(event: ShortcutEventLike): Set<string> {
	const layoutKey = normalizeEventKey(event.key);
	const keys = new Set([layoutKey]);
	// The physical-position fallback exists for layouts that type non-Latin
	// letters (Cyrillic, Greek) and for Option-modified symbols on macOS.
	// When the layout already produces a Latin letter, match on it alone;
	// otherwise a remapped physical key triggers shortcuts for two different
	// letters at once and shadows system shortcuts on non-QWERTY layouts.
	const letterCode = event.code?.match(/^Key([A-Z])$/)?.[1];
	if (letterCode && !/^[a-z]$/.test(layoutKey)) {
	keys.add(letterCode.toLowerCase());
	}
	keys.add(shortcutKeyFromEvent(event));
	return keys;

So a binding stored as shift+\ matches Shift on the # key, because the code alias is \. The editor is mislabeling the key. It is not dropping the chord. SnapShots then register that stored key with Electron (Shift+\), which is again the US name of the same physical key.

Shift on that key does not type #. Unshifted is #, Shift types '. The recorder shows neither.

Not a duplicate

• Limit physical key fallback to non-Latin layout output #4469 (merged) — letter shortcuts follow the layout. Punctuation was left on the physical map. This report is the punctuation side.
• fix(web): respect keyboard layouts for command shortcuts #5021 (closed, not merged) — same letter-layout fix. It does not change shortcutKeyFromEvent.
• fix(web): capture digit shortcuts as numbers instead of shifted symbols #10174 (closed, not merged) — wanted shifted digits stored as 1 rather than !. Same US-physical idea, not this key.
• fix(web): recognize dead-key Backquote shortcuts #9815 and fix(web): prevent duplicate quotes from dead keys #12644 — dead-key Backquote handling. The # key is not that key.

No open issue covers the keybinding or SnapShot recorder replacing layout punctuation with the US code name.

Fix direction

Recording and matching should not share one US-only token if the label is supposed to be the key the layout produced.

Keep event.key when it is a single printable character (#, ', ü, +). Use the code map only as an extra match alias for default chords such as mod+[, which is what resolveEventKeys already does for letters. Today shortcutKeyFromEvent overwrites the layout character before the settings draft is saved, so the file never contains #.

The capture tests above have to change with that. They currently require the US name.

Workaround

The shift+\ shown in the editor is this physical key. Leave it if the chord only needs to fire there. It will not display #.

A hand-written shift+# in ~/.t3/userdata/keybindings.json does not match Shift on that key: with Shift held, event.key is ' and the code alias is \. The token that matches is shift+\.

Accepting as a keybinding-recorder bug. SnapShots are the same function, not a second defect.