fix(shortcuts): accept bare Return as a macOS shortcut key - #183

Description

On macOS the Return key sends kVK_Return, which is keycode 36, but MAC_KEYCODES.ENTER in apps/desktop/src/utils/keycodes.ts was 52. So recording Return on its own in the shortcut editor is rejected with "add a modifier", even though bare Space, Tab, Escape and the function keys are all accepted, and Windows accepts its own bare Enter.

Root cause

apps/desktop/src/utils/keycode-map.ts already knows the right answer. Line 52 maps 36: "Enter" and calls it the canonical kVK_Return, keeping 52: "Enter" below it as a legacy alias, and ShortcutManager.swift line 40 declares enterKeyCodes: Set<Int> = [36, 52, 76]. So keycode 36 travels all the way through isKnownKeycode and addActiveKey in apps/desktop/src/main/managers/shortcut-manager.ts and reaches validation as a normal chord.

apps/desktop/src/utils/shortcut-constants.ts was the one place left behind. MAC_SPECIAL_KEYCODES on line 87 listed MAC_KEYCODES.ENTER, which was only 52, so keycode 36 never matched the hasSpecialKey branch of checkAlphanumericOnly in apps/desktop/src/utils/shortcut-validation.ts line 169 and fell through to the addModifier error.

Keypad Enter, keycode 76, was missing for the same reason. keycode-map.ts names it KeypadEnter and shortcut-manager.ts line 610 treats Enter and KeypadEnter alike, and on Windows VK_RETURN covers both the main and numpad keys so WINDOWS_SPECIAL_KEYCODES already accepted numpad Enter. macOS did not.

Fix

MAC_KEYCODES.ENTER is now 36, with ENTER_LEGACY 52 and KEYPAD_ENTER 76 beside it, and MAC_SPECIAL_KEYCODES lists all three. MAC_SPECIAL_KEYCODES was the only consumer of MAC_KEYCODES.ENTER, and the reserved-shortcut tables never referenced it, so changing its value affects nothing else.

Verification

pnpm --filter @amical/desktop test on macOS 26.2 arm64 with Node 24.8.0 and pnpm 10.15.0 gives 119 of 120 files and 1112 of 1113 tests passing. The one failure, tests/vite/posthog-source-maps.test.ts > uses a stable app release and deletes uploaded maps from the bundle, fails identically on main at 14a62ea with nothing of mine applied, so it is not from this change.

The three new assertions in apps/desktop/tests/utils/shortcut-validation.test.ts fail on main and pass with this change. Checking out just the two source files from main and rerunning that file gives 3 failed | 11 passed, with each failure reporting settings.shortcuts.validation.addModifier. The two control cases in the same block, the legacy alias 52 on macOS and VK_RETURN on Windows, pass both before and after, which is what pins this to the missing keycodes rather than to the check itself.

pnpm --filter @amical/desktop type:check reports no errors, prettier --check reports no changes for the three files, and eslint on the two changed source files is clean.

Summary by CodeRabbit

• Bug Fixes

  • Improved shortcut handling for macOS Return, legacy Return, and keypad Enter keys.
  • Bare Return shortcuts on macOS are now validated correctly.
  • Enter keys are consistently recognized as special keys without requiring modifiers.

• Tests

  • Added coverage for Enter and Return key handling across macOS and Windows.