fix(macos): modifier-key injection for apps & VM guests, scroll, and Caps Lock (#450)

[jtjones09]

Problem

On macOS, lan-mouse injects keystrokes via CGEvent posted to the HID tap. Plain typing worked, but modifier chords were broken in several ways (#450):

• holding a modifier injected a phantom "A" (a bare CGEvent defaults to keycode 0 = kVK_ANSI_A), breaking hotkey listeners and shortcut recorders;
• modifiers were torn down by the single-slot key-repeat task (sticky / dropped modifiers — also [Linux client + MacOS server] Sticky modifier keys #357);
• AltGr / Mod5 was dropped, so Alt/Option chords silently lost Option;
• and even with correct flags, modifier chords did not register inside Apple Virtualization.framework guest windows (VZVirtualMachineView) — e.g. Shift+2 produced 2, Cmd/Ctrl combos did nothing.

Scroll direction was also wrong on the receiving Mac — it ignored the Mac's own Natural scrolling setting.

Fix

Modifiers (commit 1)

Layer 1 — the four CGEvent bugs from #450 (diagnosed and originally patched by @bmajewski):

1. FlagsChanged events now carry the modifier's real keycode (was a bare CGEvent → keycode 0 → phantom "A").
2. Modifier keys no longer enter the key-repeat machinery, so a second modifier no longer releases the first while it's still held.
3. The wholesale Modifiers state handler only updates internal state now (no duplicate / phantom-"A" post).
4. to_cgevent_flags() maps both Mod1 and Mod5 (AltGr) to Option.

Layer 2 — Virtualization.framework guest modifiers:
VZVirtualMachineView derives guest modifier state from AppKit's flagsChanged(with:) and reads the device-dependent low-word flag bits, which macOS does not synthesize for posted (synthetic) events. The synthetic FlagsChanged now also sets the IOKit NX_DEVICE*KEYMASK bits + CGEventFlagNonCoalesced, making it byte-faithful to a real hardware modifier event. Ordinary apps mask incoming events to the device-independent word and ignore these bits, so this is safe for every app and needs no VM/bundle-id detection.

Note: the forums-documented NSEvent / NSWindow.postEvent approach is in-process only and can't work from a separate process like lan-mouse. Setting the device-dependent bits on the CGEvent is the cross-process equivalent. See https://developer.apple.com/forums/thread/766014

Scroll (commit 2 — separable)

macOS applies Natural scrolling to real input devices but not to synthetic events. The receiver now reads its own com.apple.swipescrolldirection and flips the scroll sign accordingly — honouring the receiver's preference (Synergy-style) rather than the sender's convention. Kept as its own commit so it can be dropped independently.

Known limitation: this fixes the common cross-OS case (a non-macOS sender → macOS receiver, where the wire delta is in a fixed convention). When both peers are macOS with natural scrolling enabled, the macOS sender already forwards a natural-oriented delta, so the receiver-side flip double-inverts; fixing that cleanly needs scroll normalization on the macOS capture side, which is out of scope for this PR. The same double-inversion shows up when scrolling into a nested macOS VM guest (e.g. a Parallels macOS guest), since the guest OS applies its own natural-scrolling on top of the receiver-side flip — workaround: disable Natural Scrolling in the guest.

Caps Lock (commit 3)

Rerouting modifiers out of the key-repeat path (above) made Caps Lock momentary, because it's classified as a modifier. Caps Lock is a locking modifier, so update_modifiers() now toggles it on key-down and ignores key-up — it latches correctly. (A synthetic CGEvent can't flip the hardware Caps Lock LED, but the typed output is correct, and number-row symbols stay unshifted like real Caps Lock.)

Hypervisor coverage

Layer 2 targets VZVirtualMachineView specifically, so it covers every Apple Virtualization.framework guest: UTM's Apple-Virtualization backend, Parallels Desktop macOS guests, VirtualBuddy, and Apple's own Virtualization samples. Hypervisors with their own input layers (UTM-QEMU, VMware Fusion, VirtualBox) use different code paths and aren't addressed here — though Layer 1 still improves normal modifier handling everywhere.

Testing

Tested end-to-end on a Windows 11 sender → macOS client:

• modifier chords (Shift+2 → @, Cmd+C/Cmd+V, Ctrl and Option combos) in normal macOS apps and inside a Parallels macOS guest ✅
• scroll direction correct on the Mac, and it tracks the macOS Natural scrolling toggle ✅
• Caps Lock latches (tap → capitals, tap again → lowercase) ✅ — the hardware LED doesn't light (synthetic-event limitation), but typed output is correct

References

• Issue: macOS emulation: keyboard shortcuts with modifiers don't work (phantom "A" key events, modifiers released early, Mod5 dropped) #450 (root-cause analysis and original patch by @bmajewski)
• Apple Developer Forums: https://developer.apple.com/forums/thread/766014

---

Co-developed with Claude Opus 4.8 · 🤖 Generated with Claude Code