Global Hotkeys — System-Wide Keyboard Shortcuts

Critical Constraints

• ❌ DO NOT use only addGlobalMonitorForEvents → ✅ Also add addLocalMonitorForEvents (global doesn't fire when YOUR app is focused)
• ❌ DO NOT forget Accessibility permission → ✅ Global event monitoring requires AXIsProcessTrusted()
• ❌ DO NOT compare raw modifierFlags → ✅ Mask with .deviceIndependentFlagsMask first
• ❌ DO NOT use NSEvent for system-wide hotkeys in sandboxed apps → ✅ Use Carbon RegisterEventHotKey for reliability

Decision Tree

In-app shortcut only?
└── SwiftUI .onKeyPress or .keyboardShortcut

System-wide, non-sandboxed?
├── Simple → NSEvent global + local monitors
└── Reliable → Carbon RegisterEventHotKey