fix: actions ring dispatch, double-inversion guard, and desktop cycling fixes

Actions ring button (CID 0x00C3) was dispatching THUMB_BUTTON events
instead of ACTIONS_RING events, so the engine handler never fired.
Clarified the HID-to-config naming mismatch in comments across
mouse_hook_base, mouse_hook_types, and logi_device_catalog.

Guard OS-level scroll inversion with wheel_native_invert_active on all
three platforms to prevent double-inversion when firmware handles it.

Fix Windows Shift+wheel swallowing scroll when _ri_hwnd is unavailable.

Pass CGSMainConnectionID() to CGSGetActiveSpace() to prevent ARM64
segfault. Move desktop_direction to in-memory state and add optimistic
cache update to prevent rapid-press overshoot.

Add v17 config migration for hscroll_threshold (int 1 → float 0.1).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: David Noyes

core/config.py

@@ -101,7 +101,7 @@ def coerce_wheel_divert_setting(value: object) -> str:
 }
 
 DEFAULT_CONFIG = {
-    "version": 16,
+    "version": 17,
     "active_profile": "default",
     "profiles": {
         "default": {
@@ -538,6 +538,13 @@ def _migrate(cfg):
         cfg.setdefault("settings", {}).setdefault("force_sensitivity", None)
         cfg["version"] = 16
 
+    if version < 17:
+        # v16 -> v17: migrate hscroll_threshold from old default (int 1) to 0.1.
+        s = cfg.setdefault("settings", {})
+        if s.get("hscroll_threshold") == 1:
+            s["hscroll_threshold"] = 0.1
+        cfg["version"] = 17
+
     cfg.setdefault("settings", {})
     cfg["settings"].setdefault("appearance_mode", "system")
     cfg["settings"].setdefault("debug_mode", False)

core/engine.py

@@ -71,6 +71,7 @@ def __init__(self):
         self._hid_replay_requested_this_launch = False
         self._desktop_info_cache = None
         self._desktop_info_ts = 0.0
+        self._desktop_direction = "right"
         self._replay_inflight = False
         self._replay_pending_rerun = False
         self._replay_lock = threading.Lock()
@@ -473,8 +474,11 @@ def _get_macos_desktop_info():
             # CGSGetActiveSpace returns the current space id64 of the
             # display where the cursor is located.
             cg = ctypes.CDLL('/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics')
+            cg.CGSMainConnectionID.restype = ctypes.c_uint32
             cg.CGSGetActiveSpace.restype = ctypes.c_int64
-            current_id64 = cg.CGSGetActiveSpace()
+            cg.CGSGetActiveSpace.argtypes = [ctypes.c_uint32]
+            conn = cg.CGSMainConnectionID()
+            current_id64 = cg.CGSGetActiveSpace(conn)
 
             # Read spaces config
             result = subprocess.run(
@@ -560,8 +564,6 @@ def _cycle_desktops(self):
             print("[Engine] cycle_desktops only supported on macOS")
             return
 
-        settings = self.cfg.setdefault("settings", {})
-
         # Get desktop info (cached for 5 seconds to avoid subprocess per press)
         now = time.time()
         if self._desktop_info_cache is None or (now - self._desktop_info_ts) > 5.0:
@@ -574,20 +576,17 @@ def _cycle_desktops(self):
             print(f"[Engine] cycle_desktops: only {desktop_count} desktop, skipping")
             return
 
-        # Read direction state
-        direction = settings.get("desktop_direction", "right")
+        direction = self._desktop_direction
 
         # Calculate next position
         if direction == "right":
             if current >= desktop_count:
-                # At right edge, reverse
                 direction = "left"
                 next_pos = current - 1
             else:
                 next_pos = current + 1
         else:  # left
             if current <= 1:
-                # At left edge, reverse
                 direction = "right"
                 next_pos = current + 1
             else:
@@ -600,9 +599,8 @@ def _cycle_desktops(self):
         else:
             execute_action("space_left")
 
-        # Save direction state
-        settings["desktop_direction"] = direction
-        save_config(self.cfg)
+        self._desktop_direction = direction
+        self._desktop_info_cache = (desktop_count, next_pos)
 
     def _make_hscroll_handler(self, action_id):
         def handler(event):

core/logi_device_catalog.py

@@ -23,10 +23,11 @@
     "mode_shift",
 )
 
-# MX Master 4 layout: the standard MX Master set plus a third thumb-area
-# button. The MX Master 4 relocates the legacy gesture button (CID 0x00C3)
-# next to back/forward and adds a haptic Sense Panel (CID 0x01A0); the
-# "thumb_button" key gives the relocated button its own UI mapping target.
+# MX Master 4 layout: two gesture-area buttons instead of one.
+#  - Sense Panel (CID 0x01A0): large top surface → config key "gesture"
+#  - Actions Ring button (CID 0x00C3): small thumb-area button → config key
+#    "actions_ring".  The HID layer calls this "thumb_button" internally
+#    (after its physical location); the dispatch maps it to actions_ring events.
 MX_MASTER_4_BUTTONS = (
     "middle",
     "gesture",

core/mouse_hook_base.py

@@ -347,7 +347,9 @@ def _on_hid_actions_ring_up(self):
         self._dispatch(MouseEvent(MouseEvent.ACTIONS_RING_UP))
 
     def _on_hid_thumb_button_down(self):
-        self._dispatch(MouseEvent(MouseEvent.THUMB_BUTTON_DOWN))
+        # HID layer calls this "thumb_button" (physical location), but the
+        # UI/config key is "actions_ring" — dispatch the matching event type.
+        self._dispatch(MouseEvent(MouseEvent.ACTIONS_RING_DOWN))
 
     def _on_hid_thumb_button_up(self):
-        self._dispatch(MouseEvent(MouseEvent.THUMB_BUTTON_UP))
+        self._dispatch(MouseEvent(MouseEvent.ACTIONS_RING_UP))

core/mouse_hook_linux.py

@@ -773,13 +773,13 @@ def _handle_rel(self, event):
         if code == _ecodes.REL_WHEEL or code == rel_wheel_hi_res:
             if value != 0 and self._shift_held():
                 if code == _ecodes.REL_WHEEL:
-                    h_value = -value if self.invert_hscroll else value
+                    h_value = -value if (self.invert_hscroll and not self.wheel_native_invert_active) else value
                     self._uinput.write(_ecodes.EV_REL, _ecodes.REL_HWHEEL, h_value)
                 # REL_WHEEL_HI_RES events are suppressed while Shift is held so
                 # the vertical scroll doesn't double-fire alongside the
                 # translated horizontal scroll.
                 return
-            if self.invert_vscroll:
+            if self.invert_vscroll and not self.wheel_native_invert_active:
                 self._uinput.write(_ecodes.EV_REL, code, -value)
             else:
                 self._uinput.write_event(event)
@@ -801,7 +801,7 @@ def _handle_rel(self, event):
 
             if should_block:
                 return
-            if self.invert_hscroll:
+            if self.invert_hscroll and not self.wheel_native_invert_active:
                 self._uinput.write(_ecodes.EV_REL, code, -value)
             else:
                 self._uinput.write_event(event)

core/mouse_hook_macos.py

@@ -373,7 +373,7 @@ def _event_tap_callback(self, proxy, event_type, cg_event, refcon):
                     mouse_event = None
                 if should_block:
                     return None
-                if self.invert_vscroll or self.invert_hscroll:
+                if (self.invert_vscroll or self.invert_hscroll) and not self.wheel_native_invert_active:
                     if self._post_inverted_scroll_event(cg_event):
                         return None
 

core/mouse_hook_types.py

@@ -23,8 +23,9 @@ class MouseEvent:
     XBUTTON1_UP = "xbutton1_up"
     XBUTTON2_DOWN = "xbutton2_down"
     XBUTTON2_UP = "xbutton2_up"
-    # MX Master 4 Thumb button (small front-face button, HID++ CID 0x00c3).
-    # Distinct from the Sense Panel (CID 0x01a0), which is the gesture button.
+    # Reserved — currently unused.  The MX Master 4's small thumb-area
+    # button (CID 0x00C3) dispatches as ACTIONS_RING_DOWN/UP (see below)
+    # because the UI/config calls it "actions_ring", not "thumb_button".
     THUMB_BUTTON_DOWN = "thumb_button_down"
     THUMB_BUTTON_UP = "thumb_button_up"
     MIDDLE_DOWN = "middle_down"

core/mouse_hook_windows.py

@@ -355,14 +355,12 @@ def _low_level_handler_inner(self, nCode, wParam, lParam):
                             self._shift_hscroll_posted = True
                             return 1
                         self._pending_shift_hscroll -= h_delta
-                        return 1
                     else:
                         self._emit_debug(
                             "Shift+wheel translation skipped: "
                             "raw input window unavailable"
                         )
-                    return 1
-                if self.invert_vscroll:
+                if self.invert_vscroll and not self.wheel_native_invert_active:
                     if delta != 0 and self._ri_hwnd:
                         self._pending_vscroll += -delta
                         if self._vscroll_posted:
@@ -385,7 +383,7 @@ def _low_level_handler_inner(self, nCode, wParam, lParam):
                     event = MouseEvent(MouseEvent.HSCROLL_RIGHT, abs(delta))
                     should_block = MouseEvent.HSCROLL_RIGHT in self._blocked_events
 
-                if self.invert_hscroll:
+                if self.invert_hscroll and not self.wheel_native_invert_active:
                     if delta != 0 and self._ri_hwnd and not should_block:
                         self._pending_hscroll += -delta
                         if self._hscroll_posted:

tests/test_config.py

@@ -44,7 +44,7 @@ def test_migrate_v1_config_adds_profile_apps_and_gesture_defaults(self):
 
         migrated = config._migrate(legacy)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(migrated["profiles"]["default"]["apps"], [])
         self.assertFalse(migrated["settings"]["invert_hscroll"])
         self.assertFalse(migrated["settings"]["invert_vscroll"])
@@ -92,7 +92,7 @@ def test_migrate_updates_media_player_profile_apps(self):
 
         migrated = config._migrate(cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(
             migrated["profiles"]["media"]["apps"],
             ["Microsoft.Media.Player.exe", "VLC.exe"],
@@ -109,7 +109,7 @@ def test_migrate_updates_media_player_profile_apps(self):
     def test_default_hscroll_threshold_supports_fractional_mac_deltas(self):
         self.assertEqual(config.DEFAULT_CONFIG["settings"]["hscroll_threshold"], 0.1)
 
-    def test_load_config_preserves_integer_hscroll_threshold(self):
+    def test_load_config_migrates_integer_hscroll_threshold(self):
         partial = {
             "version": 9,
             "active_profile": "default",
@@ -135,7 +135,7 @@ def test_load_config_preserves_integer_hscroll_threshold(self):
             ):
                 loaded = config.load_config()
 
-        self.assertEqual(loaded["settings"]["hscroll_threshold"], 1)
+        self.assertEqual(loaded["settings"]["hscroll_threshold"], 0.1)
 
     def test_load_config_merges_missing_defaults_from_disk(self):
         partial = {
@@ -165,7 +165,7 @@ def test_load_config_merges_missing_defaults_from_disk(self):
             ):
                 loaded = config.load_config()
 
-        self.assertEqual(loaded["version"], 16)
+        self.assertEqual(loaded["version"], 17)
         self.assertEqual(loaded["settings"]["dpi"], 800)
         self.assertEqual(loaded["settings"]["action_haptic"], [])
         self.assertTrue(loaded["settings"]["haptic_enabled"])
@@ -197,7 +197,7 @@ def test_migrate_renames_start_with_windows_to_start_at_login(self):
 
         migrated = config._migrate(legacy)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertTrue(migrated["settings"]["start_at_login"])
         self.assertEqual(
             migrated["profiles"]["default"]["mappings"]["mode_shift"],
@@ -223,7 +223,7 @@ def test_migrate_v8_to_v9_adds_actions_ring_and_haptic(self):
 
         migrated = config._migrate(v8_cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(
             migrated["profiles"]["default"]["mappings"]["actions_ring"], "none"
         )
@@ -246,7 +246,7 @@ def test_migrate_v9_to_v10_adds_gesture_recognizer_params(self):
 
         migrated = config._migrate(v9_cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(migrated["settings"]["gesture_commit_window_ms"], 400)
         self.assertEqual(migrated["settings"]["gesture_settle_ms"], 90)
         self.assertEqual(migrated["settings"]["gesture_cross_ratio"], 0.5)
@@ -272,7 +272,7 @@ def test_migrate_v10_to_v11_adds_button_haptic(self):
 
         migrated = config._migrate(v10_cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(migrated["profiles"]["default"]["button_haptic"], {})
         self.assertEqual(migrated["profiles"]["work"]["button_haptic"], {})
 
@@ -292,7 +292,7 @@ def test_migrate_v12_to_v13_adds_action_haptic_list(self):
 
         migrated = config._migrate(v12_cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(migrated["settings"]["action_haptic"], [])
         # existing haptic settings preserved
         self.assertTrue(migrated["settings"]["haptic_enabled"])
@@ -343,7 +343,7 @@ def test_migrate_v13_to_v14_adds_button_haptic_and_dedup(self):
 
         migrated = config._migrate(v13_cfg)
 
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
         self.assertEqual(migrated["settings"]["button_haptic"], [])
         self.assertTrue(migrated["settings"]["haptic_dedup"])
         # existing settings preserved

tests/test_smart_shift.py

@@ -749,7 +749,7 @@ def test_multiple_profiles_all_migrated(self):
     def test_version_bumped_to_current(self):
         from core.config import _migrate
         migrated = _migrate(self._v6_config())
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
 
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -811,7 +811,7 @@ def test_multiple_profiles_all_migrated(self):
     def test_version_bumped_to_current(self):
         from core.config import _migrate
         migrated = _migrate(self._v7_config())
-        self.assertEqual(migrated["version"], 16)
+        self.assertEqual(migrated["version"], 17)
 
 
 class HidForceReconnectTests(unittest.TestCase):