fix(razer): explain macOS Input Monitoring on open failure

Author: jazzstack

src/devices/razer/TESTING.md

@@ -3,6 +3,14 @@
 Test in Chrome or Edge over HTTPS. Quit Razer Synapse first — it holds the
 control interface open and reads then time out.
 
+On macOS the browser itself must be granted Input Monitoring permission
+(System Settings → Privacy & Security → Input Monitoring) **before** the first
+connection, and then quit and reopened. Razer's control interface is a Generic
+Desktop Mouse collection, which macOS reserves for its own input stack; without
+the permission the browser's `IOHIDDeviceOpen` call is refused and the app
+shows "Failed to open the device." while the device still appears in the
+picker. This is a system grant, not an app setting.
+
 Supported identifiers:
 
 - `1532:00a5` — Viper V2 Pro, wired
@@ -144,6 +152,18 @@ answers, add the device again and choose another.
 The V2 has RGB lighting, but like every other model the panel offers no Razer
 lighting controls and device mode is never sent.
 
+## DeathAdder V2 on macOS
+
+Confirmed on macOS: the mouse enumerates as four HID interfaces, the
+configuration channel sits on the Generic Desktop Mouse interface, and the
+browser is refused from opening it unless it holds the Input Monitoring
+permission. The device still shows up in the picker, so the failure looks like
+a driver bug: the sidebar lists the mouse as available, and connecting fails
+with `NotAllowedError: Failed to open the device.` before any feature report is
+exchanged — no Synapse installed. Granting the browser Input Monitoring
+(System Settings → Privacy & Security → Input Monitoring) and restarting it is
+the fix; the app now says exactly that when the open is refused on macOS.
+
 ## Verified against firmware 1.12
 
 | Read | Class / ID | Notes |

src/devices/razer/hid-open.ts

@@ -0,0 +1,29 @@
+const IS_MAC = typeof navigator !== "undefined" && /Mac/i.test(navigator.userAgent);
+
+const MACOS_INPUT_MONITORING_HINT =
+  "On macOS the browser is refused access to mouse-class HID interfaces unless it"
+  + " has Input Monitoring permission. Enable it in System Settings → Privacy &"
+  + " Security → Input Monitoring, then quit and reopen the browser.";
+
+/**
+ * Opens a Razer control interface, and turns the browser's bare "Failed to open
+ * the device." on macOS into an actionable message.
+ *
+ * Razer's configuration channel lives on a Generic Desktop Mouse collection,
+ * which macOS reserves for its own input stack: without the Input Monitoring
+ * TCC permission the browser's `IOHIDDeviceOpen` call fails with
+ * `kIOReturnNotPermitted`, which WebHID surfaces as a generic NotAllowedError.
+ * Nothing in the app can grant that — it is a system permission on the browser
+ * itself — so the hint is the whole fix.
+ */
+export async function openRazerDevice(device: HIDDevice): Promise<void> {
+  if (device.opened) return;
+  try {
+    await device.open();
+  } catch (error) {
+    if (IS_MAC && error instanceof Error) {
+      throw new Error(`${error.message} ${MACOS_INPUT_MONITORING_HINT}`);
+    }
+    throw error;
+  }
+}

src/devices/razer/hid.ts

@@ -1,5 +1,6 @@
 import type { MouseStatus } from "../mouse-types.ts";
 import { VENDOR_ID } from "../vendors.ts";
+import { openRazerDevice } from "./hid-open.ts";
 import {
   RAZER_LANDING_MAX,
   RAZER_LANDING_MIN,
@@ -188,7 +189,7 @@ export class RazerHidClient {
   }
 
   async open(): Promise<void> {
-    if (!this.device.opened) await this.device.open();
+    await openRazerDevice(this.device);
   }
 
   async close(): Promise<void> {

src/devices/razer/viper-mini-hid.ts

@@ -1,5 +1,6 @@
 import type { MouseStatus } from "../mouse-types.ts";
 import { VENDOR_ID } from "../vendors.ts";
+import { openRazerDevice } from "./hid-open.ts";
 import {
   RAZER_READ,
   RAZER_REPORT_ID,
@@ -69,8 +70,9 @@ export class RazerViperMiniHidClient {
     // On Linux "Failed to open the device" means the hidraw node for 1532:008a
     // is root-owned or the razermouse kernel driver claimed the interface.
     // Fix: udev rule granting plugdev access to that vendor/product, then
-    // `sudo rmmod razermouse`.
-    if (!this.device.opened) await this.device.open();
+    // `sudo rmmod razermouse`. On macOS the same message means the browser
+    // lacks Input Monitoring permission — see `openRazerDevice`.
+    await openRazerDevice(this.device);
   }
 
   async close(): Promise<void> {

src/devices/razer/viper-v4-pro-hid.ts

@@ -1,4 +1,5 @@
 import type { MouseStatus } from "../mouse-types.ts";
+import { openRazerDevice } from "./hid-open.ts";
 
 export const RAZER_VENDOR_ID = 0x1532;
 export const VIPER_V4_PRO_PRODUCTS = new Map<number, { wireless: boolean }>([
@@ -79,7 +80,7 @@ export class RazerViperV4ProHidClient {
   }
 
   async open(): Promise<void> {
-    if (!this.device.opened) await this.device.open();
+    await openRazerDevice(this.device);
   }
 
   async close(): Promise<void> {