feat: add MX Master 4 support with Actions Ring and haptic feedback

Phase 1 implementation:

Core Device Support:
- Register MX Master 4 (PID 0xB042) as variant of MX Master 3S
- Add Actions Ring button (CID 0x01A0) as fully remappable control
- Add dedicated device layout with 7 hotspots including Actions Ring
- Use mxm4.png image asset for visual representation

Haptic Feedback Backend:
- Implement HID++ 2.0 HAPTIC feature (0x19B0) with:
  - getCapabilities (function 0)
  - getState (function 1)
  - setState with 4 discrete levels: subtle/low/medium/high
  - playWaveform for test feedback
- Detect FORCE_SENSING_BUTTON feature (0x19C0) as placeholder
- Add queue+wait pattern for HID++ command processing
- Replay saved haptic level on device reconnect

UI & Configuration:
- Add Haptic Feedback page in sidebar (conditional on MX Master 4 connection)
- Haptic Feedback page: intensity selector (4 buttons) + test button + note
- Config migration v8->v9: register actions_ring button, add haptic_level setting
- Add i18n strings for haptic UI (en, zh_CN, zh_TW)

Mouse Hook:
- Add ACTIONS_RING_DOWN/UP events for actions ring button presses
- Implement divert handlers in all platform impls (Windows/macOS/Linux)
- Actions ring integration follows existing gesture button patterns

Testing:
- 16 new tests across 5 test files:
  - Device registry: button definition, product ID lookup, image asset
  - Device layouts: dedicated layout exists, hotspots correct, no fallback
  - Config migration: v8->v9 adds actions_ring and haptic_level
  - HID++: KNOWN_CID_NAMES includes Actions Ring, feature constants defined
  - Mouse hook: ACTIONS_RING event constants exist

No regressions for MX Master 3S -- all existing behavior unchanged.

Phase 1 excludes:
- Per-event haptic routing policy (phase 2)
- Force Sensing Button configuration (detection only)
- Swipe gesture actions (future)

Author: TomBadash

core/config.py

@@ -33,6 +33,7 @@
     "hscroll_right": "Horizontal scroll right",
     "mode_shift":    "Mode shift button",
     "dpi_switch":    "DPI switch button",
+    "actions_ring":  "Actions Ring button",
 }
 
 GESTURE_DIRECTION_BUTTONS = (
@@ -64,10 +65,11 @@
     "hscroll_right": ("hscroll_right",),
     "mode_shift":    ("mode_shift_down", "mode_shift_up"),
     "dpi_switch":    ("dpi_switch_down", "dpi_switch_up"),
+    "actions_ring":  ("actions_ring_down", "actions_ring_up"),
 }
 
 DEFAULT_CONFIG = {
-    "version": 8,
+    "version": 9,
     "active_profile": "default",
     "profiles": {
         "default": {
@@ -85,6 +87,7 @@
                 "hscroll_left": "browser_back",
                 "hscroll_right": "browser_forward",
                 "mode_shift": "switch_scroll_mode",
+                "actions_ring": "none",
             },
         }
     },
@@ -106,6 +109,7 @@
         "debug_mode": False,
         "device_layout_overrides": {},
         "language": "en",
+        "haptic_level": 2,          # 0=subtle, 1=low, 2=medium, 3=high
     },
 }
 
@@ -321,6 +325,16 @@ def _migrate(cfg):
                 mappings["mode_shift"] = "switch_scroll_mode"
         cfg["version"] = 8
 
+    if version < 9:
+        # v8 -> v9: add Actions Ring button mapping for MX Master 4,
+        # add haptic feedback level setting.
+        for pdata in cfg.get("profiles", {}).values():
+            mappings = pdata.setdefault("mappings", {})
+            mappings.setdefault("actions_ring", "none")
+        settings = cfg.setdefault("settings", {})
+        settings.setdefault("haptic_level", 2)
+        cfg["version"] = 9
+
     cfg.setdefault("settings", {})
     cfg["settings"].setdefault("appearance_mode", "system")
     cfg["settings"].setdefault("debug_mode", False)

core/device_layouts.py

@@ -84,6 +84,90 @@
     ],
 }
 
+MX_MASTER_4_LAYOUT = {
+    "key": "mx_master_4",
+    "label": "MX Master 4",
+    "image_asset": "mxm4.png",
+    "image_width": 460,
+    "image_height": 360,
+    "interactive": True,
+    "manual_selectable": True,
+    "note": "",
+    "hotspots": [
+        {
+            "buttonKey": "middle",
+            "label": "Middle button",
+            "summaryType": "mapping",
+            "normX": 0.37,
+            "normY": 0.27,
+            "labelSide": "left",
+            "labelOffX": -80,
+            "labelOffY": -100,
+        },
+        {
+            "buttonKey": "gesture",
+            "label": "Gesture button",
+            "summaryType": "gesture",
+            "normX": 0.44,
+            "normY": 0.56,
+            "labelSide": "left",
+            "labelOffX": -240,
+            "labelOffY": 60,
+        },
+        {
+            "buttonKey": "xbutton2",
+            "label": "Forward button",
+            "summaryType": "mapping",
+            "normX": 0.48,
+            "normY": 0.62,
+            "labelSide": "left",
+            "labelOffX": -300,
+            "labelOffY": 0,
+        },
+        {
+            "buttonKey": "xbutton1",
+            "label": "Back button",
+            "summaryType": "mapping",
+            "normX": 0.53,
+            "normY": 0.50,
+            "labelSide": "right",
+            "labelOffX": 200,
+            "labelOffY": 50,
+        },
+        {
+            "buttonKey": "hscroll_left",
+            "label": "Horizontal scroll",
+            "summaryType": "hscroll",
+            "isHScroll": True,
+            "normX": 0.25,
+            "normY": 0.46,
+            "labelSide": "left",
+            "labelOffX": -200,
+            "labelOffY": -30,
+        },
+        {
+            "buttonKey": "mode_shift",
+            "label": "Mode shift button",
+            "summaryType": "mapping",
+            "normX": 0.38,
+            "normY": 0.40,
+            "labelSide": "right",
+            "labelOffX": 150,
+            "labelOffY": -80,
+        },
+        {
+            "buttonKey": "actions_ring",
+            "label": "Actions Ring",
+            "summaryType": "mapping",
+            "normX": 0.62,
+            "normY": 0.70,
+            "labelSide": "right",
+            "labelOffX": 160,
+            "labelOffY": 50,
+        },
+    ],
+}
+
 GENERIC_MOUSE_LAYOUT = {
     "key": "generic_mouse",
     "label": "Generic mouse",
@@ -208,6 +292,7 @@
 
 DEVICE_LAYOUTS = {
     "mx_master": MX_MASTER_LAYOUT,
+    "mx_master_4": MX_MASTER_4_LAYOUT,
     "mx_anywhere": MX_ANYWHERE_LAYOUT,
     "mx_vertical": MX_VERTICAL_LAYOUT,
     "generic_mouse": GENERIC_MOUSE_LAYOUT,
@@ -217,7 +302,6 @@
 # Entries here let per-device keys fall back to the family layout until a
 # dedicated layout is added.  Extend this dict as new devices are cataloged.
 _FAMILY_FALLBACKS = {
-    "mx_master_4": "mx_master",
     "mx_master_3s": "mx_master",
     "mx_master_3": "mx_master",
     "mx_master_2s": "mx_master",

core/engine.py

@@ -118,6 +118,16 @@ def _setup_hooks(self):
             )
         )
 
+        # Divert Actions Ring CID (0x01A0) on MX Master 4 when mapped.
+        has_actions_ring = device_buttons is None or "actions_ring" in device_buttons
+        self.hook.divert_actions_ring = (
+            has_actions_ring
+            and any(
+                pdata.get("mappings", {}).get("actions_ring", "none") != "none"
+                for pdata in self.cfg.get("profiles", {}).values()
+            )
+        )
+
         self._emit_mapping_snapshot("Hook mappings refreshed", mappings)
 
         for btn_key, action_id in mappings.items():
@@ -491,6 +501,11 @@ def _replay_saved_settings_once(self):
                         pass
             else:
                 replay_ok = False
+
+        saved_haptic = self.cfg.get("settings", {}).get("haptic_level")
+        if saved_haptic is not None and getattr(hg, "haptic_supported", False):
+            if hasattr(hg, "set_haptic_level"):
+                hg.set_haptic_level(saved_haptic)
         return replay_ok
 
     def _replay_saved_settings_worker(self):
@@ -667,6 +682,30 @@ def smart_shift_supported(self):
         hg = self.hook._hid_gesture
         return hg.smart_shift_supported if hg else False
 
+    @property
+    def haptic_supported(self):
+        hg = self.hook._hid_gesture
+        return hg.haptic_supported if hg else False
+
+    def set_haptic_level(self, level):
+        """Send haptic level to the mouse and persist to config."""
+        level = max(0, min(3, int(level)))
+        settings = self.cfg.setdefault("settings", {})
+        settings["haptic_level"] = level
+        save_config(self.cfg)
+        hg = self.hook._hid_gesture
+        if hg:
+            return hg.set_haptic_level(level)
+        print("[Engine] No HID++ connection -- haptic level not applied")
+        return False
+
+    def play_haptic_waveform(self, waveform_id=0):
+        """Trigger a haptic waveform on the mouse."""
+        hg = self.hook._hid_gesture
+        if hg:
+            return hg.play_haptic_waveform(waveform_id)
+        return False
+
     def reload_mappings(self):
         """
         Called by the UI when the user changes a mapping.