fix(hotkey): resolve modifier-mask mismatch causing bare-key global hotkeys

[davidyoung8196504567-sudo]

Summary

Fixes #449 — the bare C key was being registered as a global system hotkey, swallowing the letter C in every application while the IDE ran.

Rebased since first review: the unrelated key == 0 change has been lifted out (see below), so this PR is now scoped to the #449 fix and its tests — 4 files, 2 production classes.

Root cause

Not a keymaster/Carbon defect (initial hypothesis, ruled out). KeyModifier.getModifierNames() recognized only the legacy InputEvent.*_MASK bit values, while the stored STOP_HOTKEY_MODIFIERS uses the extended *_DOWN_MASK convention (320 = SHIFT_DOWN_MASK + META_DOWN_MASK). No bits matched, so the modifier string resolved to "", HotkeyController composed KeyStroke.getKeyStroke("C") instead of "shift meta C", and keymaster faithfully registered exactly what it was asked for.

Full trace, plus @julienmerconsulting's archaeology on where 320 comes from (a SikuliX 2.0.x → OculiX preferences-migration hazard, latent until b159a252/#388 correctly made the getter read the key the setter writes), is in #449.

Changes

• KeyModifier.getModifierNames() — recognize both the legacy *_MASK and extended *_DOWN_MASK bit pattern for each modifier. The two ranges are disjoint (1/2/4/8/32 vs 64/128/256/512/8192), so this cannot produce a false positive.
• HotkeyController.addHotkey(HotkeyListener, int, int) — refuse to register when a non-zero modifier resolves to no known modifier name, instead of silently degrading to an unmodified global hotkey. This is the more durable half: it prevents this class of bug regardless of what future convention or data issue appears.

Tests

• KeyModifierTest — broadened 4 → 9 cases per review: legacy Shift+Meta (5), extended Shift+Meta (320, the observed value), extended Shift+Alt (576, the Windows-side equivalent), extended Ctrl, extended AltGraph, a mixed legacy/extended value, and a non-modifier bit (BUTTON1_DOWN_MASK) that must still resolve to nothing.
• HotkeyControllerTest (new) — direct coverage of the refusal safety net, which previously had no test of its own.

Review feedback

#	Ask	Status
1	Refresh the issue write-up	Done — #449 now carries the full origin timeline
2	Broaden regression tests	Done — 9 modifier cases + the safety net now tested directly
3	Isolate or justify key == 0	Isolated — dropped from this PR

On key == 0

Lifted out per your item 3 rather than justified, because the rationale I would have given does not hold up on macOS.

Java's MacOSXPreferences reads and writes ~/Library/Preferences/org.sikuli.script.plist through cfprefsd, which caches and owns that file. Direct edits (plutil, Python plistlib) never reach the JVM — verified: the JVM reports STOP_HOTKEY = 67 after the file was set to 0, and the file has since been rewritten back to 67 by the daemon. So there is no route a user can actually take to set a key code to 0 on macOS today, given the Preferences UI exposes a binding control for Capture but not Stop.

The escape hatch needs a supported path — UI, defaults write, or something else — before it is worth proposing. Happy to open it separately if you think it is wanted.

Test plan

• mvn test -pl API — full suite green, 50 tests, 0 failures, 0 errors
• Manual: oculixide-4.0.0-complete-mac.jar on macOS 26.6 / Apple M4 Pro — bare C types normally in other applications while the IDE runs; Abort and Capture hotkeys still fire on their real combinations
• Manual: oculixide-4.0.0-complete-lux.jar on Ubuntu 24.04 (x86-64, X11 session) — Abort (Shift+Alt+C) and Capture (Shift+Ctrl+2) both fire correctly, no bare-key capture. Linux routes through LinuxHotkeyManager/jxgrabkey rather than keymaster, so this exercises getModifierNames() on a completely separate registration path and confirms the change is not macOS-shaped. Wayland untested — global grabs there are a separate question, unaffected by this PR.
• CI (compile-API/IDE workflows)

[julienmerconsulting]

@davidyoung8196504567-sudo — long overdue reply, apologies for the 3-week silence after you pushed the revisions on 04/08.

Honest reason: coming out of four intense months on the v4.0.0 + post-release work, I took actual vacation, and then @uwekoenig's #444 status-bar note turned into a full Region-provenance architectural pass — 24 commits, two external review passes, a new invariant model, a 44-test suite. That shipped yesterday as v4.1.0-rc1. Between the vacation reset and the #444 marathon, your PR did not get the attention it deserved. No excuse, just what happened.

Reviewed now. The diff is clean end to end:

• HotkeyController.addHotkey — the refusal safety net is exactly the right shape. Non-zero modifier resolving to empty must not fall back to a bare-key global hotkey.
• KeyModifier.getModifierNames — recognizing both legacy *_MASK and extended *_DOWN_MASK in parallel is the conservative fix. I verified the bit ranges are disjoint (CTRL=2 vs 128, SHIFT=1 vs 64, ALT=8 vs 512, ALTGR=32 vs 8192, META=4 vs 256), so no false positive is possible.
• Tests — 9 modifier cases + the direct safety-net test using a fresh HotkeyController instance (great call, avoids the native provider entirely). Coverage is exactly on the bug shape.

I moved the base branch to `chore/global-bug-fixes` a few minutes ago (that's where fixes accumulate before syncing to master on the next release), and synced `master` into `chore` so the merge itself will be clean. GitHub cache is still catching up on the display side.

Merging now. Bug #449 closes automatically via the "Fixes #449" line. Your fix will land in the upcoming v4.1.0-rc2 pre-release alongside the #444 work.

Thank you for the follow-through on this one — the root-cause chain in #449, the 2.0.x archaeology confirmation, the revisions delivered in less than 24 hours after review comments. This is exactly the kind of contribution the project needs, and I owe you a faster turnaround next time.

🦎