Caps Lock remains held in guest after key is released

[lprazdnik]

Describe the issue

When Caps Lock is treated as a key is enabled, Caps Lock can be used as a held modifier in a guest, but releasing the physical Caps Lock key does not appear to release it in the guest.

This is reliably reproducible with NVDA in a Windows 11 ARM QEMU guest when Caps Lock is configured as the NVDA modifier. After using a Caps Lock-based NVDA command and releasing the key, the next key is still interpreted as though Caps Lock is held. Pressing Caps Lock once more clears the state.

This is particularly noticeable with screen readers because they use Caps Lock as a held modifier rather than only as a toggle. I have not confirmed whether other software that depends on Caps Lock key-down/key-up events is affected.

Related to #4330, which was closed after the Caps Lock is treated as a key preference was available as a workaround for screen-reader use.

Steps to reproduce

1. In UTM settings, enable Caps Lock is treated as a key.
2. Start a Windows 11 ARM QEMU guest.
3. In NVDA, configure Caps Lock as the NVDA modifier.
4. Hold Caps Lock and press an NVDA command, for example Caps Lock+N, then release both keys.
5. Press a normal key such as T.

Expected behavior

After Caps Lock is physically released, the next key should be handled normally. In the example above, T should be a normal T.

Actual behavior

The next key is still interpreted as though Caps Lock is being held. In the example above, NVDA handles T as NVDA+T. Pressing and releasing Caps Lock again clears the stuck modifier state.

Configuration

• UTM Version: 4.7.5 (118)
• macOS Version: 26.6.2
• Mac Chip: Apple M5 Max
• Guest: Windows 11 ARM, QEMU

Crash log

Not applicable; UTM does not crash.

Debug log

Not attached. The issue is reliably reproducible as described above; I can provide a debug log if it would help diagnose the input event handling.

Upload VM

Not attached. The issue is reproducible in a standard Windows 11 ARM QEMU guest.

[lprazdnik]

I investigated this further with guest-side and QEMU-side tracing.

Findings:

• A Windows WH_KEYBOARD_LL hook initially received one Caps Lock KEYDOWN (vkCode 0x14, scan code 0x3A) followed by normal Windows auto-repeat key-down events, but no KEYUP.
• QEMU tracing showed caps_lock, down 1 with no matching down 0. The USB HID queue was empty throughout, so the release was not being dropped by queue pressure or by the Windows guest.
• Synthesizing an immediate press/release pair produced a correct Windows KEYDOWN/KEYUP, but Caps Lock could no longer function as a held NVDA modifier.
• Releasing Caps Lock when the other key in a chord was released fixed the stuck state and allowed one NVDA command, but incorrectly prevented a second command while Caps Lock remained physically held.
• I also tested GCKeyboard, polling its Caps Lock button state, and a process-local Core Graphics event tap. In a focused/captured keyboard view these exposed the toggled Caps Lock state rather than a reliable physical release. The Core Graphics stream produced only one flagsChanged event for a physical press/release cycle.

This appears to be a macOS input-layer limitation: the permission-free APIs available to the focused view do not expose the physical Caps Lock release. A fully correct implementation may require raw HID input, which likely means requiring macOS Input Monitoring permission, or another lower-level input path already approved for UTM.

Is an opt-in raw-HID/Input Monitoring implementation acceptable for this preference, or is there another input API/path the project would prefer?

[lprazdnik]

I found a permission-free way around the macOS Caps Lock limitation. Temporarily remapping Caps Lock to an ordinary key while guest input is captured preserves the physical key-down/key-up behavior, and UTM can translate it back to Caps Lock for the guest. The original host mapping is restored when VM input is released.

I tested this with NVDA in a Windows 11 ARM guest, including repeated commands while Caps Lock remained held and normal input after releasing it.

PR #7840 implements the fix.