Upstream: Bluetooth and Logitech mice disabled or stuck when Kanata runs

[malpern]

Summary

Kanata on macOS intercepts HID events from Bluetooth mice and certain Logitech receivers that register as keyboard devices. Since the DriverKit virtual keyboard cannot re-emit mouse events (pointing reports), mice become completely unresponsive or the cursor gets stuck at the screen edge.

This combines two upstream issues that share the same root cause:

• #739: Bluetooth mouse input completely disabled
• #1636: Logitech MX Master / M720 cursor stuck at screen edge

Upstream Issues

• jtroo/kanata#739 — kanata on macOS disables input from bluetooth mouse while running
• jtroo/kanata#1636 — Mouse cursor stuck on specific Bluetooth mouse

Root Cause

Two layers of the problem:

1. Kanata grabs too broadly: By default, Kanata opens all HID devices matching keyboard usage pages. Many BT mice and Logitech receivers also register keyboard HID interfaces, so they get intercepted.
2. DriverKit can't relay mouse events: The virtual keyboard driver only handles keyboard HID reports. Mouse movement events (HID Generic Desktop page 0x01, usage codes 0x30/0x31/0x38) are unrecognized and silently dropped. Debug logs show floods of InputEvent is unrecognized! for these events.

Affected Hardware

Confirmed:

• Logitech MX Master series (all generations)
• Logitech M720 Triathlon
• Generic Bluetooth mice
• Logitech Unifying receivers

Likely affected:

• Any Bluetooth mouse that exposes a keyboard HID interface
• Multi-device receivers (Logitech Bolt, Unifying) that combine keyboard + mouse

Workaround

Use macos-dev-names-include in Kanata config to whitelist only keyboard devices:

(defcfg
  macos-dev-names-include (
    "Apple Internal Keyboard / Trackpad"
  )
)

Critical conflict: This workaround causes sleep/wake crashes (see kanata#1357 / related Linear issue). Users currently cannot have both working BT mice AND reliable sleep/wake.

Impact on KeyPath

Severity: Medium-High

• Logitech mice are extremely popular — MX Master is arguably the most common productivity mouse
• Users will blame KeyPath when their mouse stops working
• The workaround/sleep conflict creates an impossible trade-off

Potential Mitigations

Upstream

• Kanata: Smarter device detection — filter out devices that are primarily mice even if they expose keyboard HID
• DriverKit: Add pointing device report passthrough so mouse events aren't dropped

KeyPath-side

• Add a device filtering UI that makes macos-dev-names-include discoverable and easy to configure
• Auto-detect connected mice and suggest appropriate device filtering
• Surface a clear warning when BT mouse issues are likely (based on device enumeration)
• Document the sleep/wake trade-off until both upstream issues are fixed

Upstream Status

• #739: Workaround documented, no code fix. A driverkit-level patch filtering "Mouse" devices was shared but not PR'd due to edge cases.
• #1636: Active discussion, same workaround. Some combo devices (Logitech K380 + mouse) share device names, making filtering harder.