@openmouse/protocol 0.1.0

package/dist/gearhub/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * GearHub-V5 codec — the transport-independent half of support for the
+ * MicLink/mlzn ODM platform on VID 0x3151 (qmk.top's "GearHub-V5" web tool).
+ *
+ * This layer knows packet shapes, command ids, the Bit7 checksum, the report-
+ * rate table, and the device catalog. It knows nothing about WebHID or the
+ * 2.4 GHz relay — that lives in `src/drivers/gearhub/hid.ts`.
+ *
+ * VID 0x3151 belongs to the ODM, not to any one brand: several unrelated
+ * makers ship on it. A GearHub-V5 mouse is identified by the GET_USB_VERSION
+ * *device id* (the same key GearHub's own bundle looks its model table up by),
+ * never by product id — the receiver's VID:PID is shared. The product id only
+ * settles transport (2.4 GHz receiver vs. direct cable).
+ *
+ * Everything here was read out of GearHub-V5's own JS bundle and confirmed
+ * byte for byte on hardware: a Lingbao M5 Pro (PAW3395, device id 2285) and an
+ * Attack Shark R2 (PAW3950, device id 1893), both on the 2.4 GHz receiver
+ * (0x3151:0x402D), Windows 11.
+ */
+export declare const GEARHUB_VENDOR_ID = 12625;
+export declare const GEARHUB_REPORT_ID = 0;
+export declare const GEARHUB_REPORT_SIZE = 64;
+export declare const GEARHUB_CMD_SIZE = 9;
+/** DPI stages the report layout has room for. */
+export declare const GEARHUB_MAX_DPI_STAGES = 8;
+/**
+ * Mouse-class command ids. GearHub groups settings into two 64-byte "option
+ * param" blocks that are read whole and written back whole:
+ *
+ *   OPTIONPARAM1 (GET 0xD4 / SET 0x54) — the DPI stage table.
+ *   OPTIONPARAM0 (GET 0xD3 / SET 0x53) — report rate (byte 9), debounce
+ *     (byte 10), lift-off / "silent height" (byte 52), sleep, sensitivity.
+ *
+ * There is no standalone GET/SET report-rate command — an earlier version of
+ * this driver used one (0x83 / 0x03) and the firmware silently ignored it.
+ */
+export declare const CMD: {
+    readonly GET_FIRMWARE: 128;
+    readonly GET_USB_VERSION: 143;
+    readonly GET_OPTIONPARAM0: 211;
+    readonly SET_OPTIONPARAM0: 83;
+    readonly GET_DPI: 212;
+    readonly SET_DPI: 84;
+    readonly GET_KEYMATRIX: 208;
+    readonly SET_KEYMATRIX: 80;
+};
+/**
+ * Receiver-level relay commands. Raw — the Bit7 checksum is NOT applied to
+ * these. The relay sequencing itself is the driver's job.
+ */
+export declare const DONGLE_CMD: {
+    readonly SELECT_TARGET: 246;
+    readonly GET_STATUS: 247;
+    readonly NOTICE_READ: 252;
+};
+export declare const TARGET_MOUSE = 5;
+/**
+ * OPTIONPARAM0 report-rate field (byte 9) encoding, from GearHub's
+ * `___utils_reportRateToNum` / `___utils_numToReportRate`. NOT a plain 0..6
+ * index — a bitmask-style code. Verified on hardware: an R2 at 1000 Hz read
+ * back code 1, and writing code 129 set it to 8000 Hz.
+ */
+export declare const REPORT_RATE_ENCODE: Record<number, number>;
+export declare const REPORT_RATE_DECODE: Record<number, number>;
+/** Every rate the codec can express, ascending. */
+export declare const GEARHUB_RATES: number[];
+/**
+ * OPTIONPARAM0 byte offsets (GET reply layout == SET payload layout), from
+ * GearHub's `___getMouseOption0` / `___cmdSetMouseOption0`.
+ */
+export declare const OPT0_REPORT_RATE = 9;
+export declare const OPT0_DEBOUNCE = 10;
+/** 16-bit LE flags word. Bit 2 is ripple correction ("wave repair"). */
+export declare const OPT0_FLAGS = 12;
+export declare const OPT0_FLAG_RIPPLE: number;
+/** LE16 idle-before-standby, in seconds. GearHub exposes a per-link timer. */
+export declare const OPT0_SLEEP_BT = 40;
+export declare const OPT0_SLEEP_24G = 44;
+/** Straight-line / angle-snapping correction ("line repair"): 0 or 1. */
+export declare const OPT0_STRAIGHT_CORRECTION = 53;
+/** Lift-off / "silent height": an index into the sensor's lift-off list. */
+export declare const OPT0_SILENT_HEIGHT = 52;
+/** GearHub's Debounce slider runs 1-10 (ms). */
+export declare const GEARHUB_DEBOUNCE_MAX_MS = 10;
+/**
+ * Standby-time stops offered to the UI, in seconds; 0 = never sleep. GearHub
+ * itself takes a free-form seconds value — this is the discrete set the
+ * OpenMouse sleep card renders, chosen to cover the useful range.
+ */
+export declare const GEARHUB_SLEEP_OPTIONS: number[];
+/** DPI table (OPTIONPARAM1) byte offsets, confirmed on hardware:
+ *   [2] active stage index, [3] stage count,
+ *   [8 + i*2] X as LE uint16, [24 + i*2] Y as LE uint16,
+ *   [40 + i*3] that stage's indicator colour as r, g, b. */
+export declare const DPI_X_OFFSET = 8;
+export declare const DPI_Y_OFFSET = 24;
+export declare const DPI_RGB_OFFSET = 40;
+export type LiftOffLevel = "Low" | "Medium" | "High";
+/**
+ * Lift-off stops per sensor, ordered by the OPTIONPARAM0 byte-52 index
+ * (ascending height). Derived from GearHub's `getLiftOffDistance()`:
+ * PAW3950/3955 offer 0.7 / 1 / 2 mm; PAW3395 offers 1 / 2 mm.
+ */
+export declare const GEARHUB_LIFT_OFF_LEVELS: Record<string, readonly LiftOffLevel[]>;
+/**
+ * The GET_KEYMATRIX reply is 14 slots of 4 bytes. These are the slots that map
+ * to a physical R2 button, in the order OpenMouse shows them. Verified on
+ * hardware: slots 0-4 hold Left/Right/Middle/Back/Forward by default, slot 5
+ * holds DPI Loop (the bottom DPI button).
+ */
+export interface GearHubButton {
+    /** Name shown in the remapper. */
+    name: string;
+    /** Slot index into the keymatrix (also the SET_KEYMATRIX button arg). */
+    slot: number;
+}
+export declare const GEARHUB_BUTTONS: readonly GearHubButton[];
+/**
+ * Assignable actions, label → 4-byte matrix value, from GearHub's `ia` table.
+ * Mouse functions only (no keyboard keys, combos or macros — OpenMouse's
+ * generic remapper is a single-choice dropdown). Left…Forward and DPI Loop
+ * were confirmed on hardware; DPI ± come straight from the bundle.
+ */
+export declare const GEARHUB_BUTTON_ACTIONS: ReadonlyArray<readonly [string, readonly [number, number, number, number]]>;
+/** Decode a 4-byte slot to an action label; "Custom" for anything else
+ *  (a keyboard key / macro set in GearHub — left untouched). */
+export declare function decodeButtonAction(bytes: readonly number[]): string;
+/** Encode an action label to its 4-byte slot value, or null if unknown. */
+export declare function encodeButtonAction(label: string): readonly [number, number, number, number] | null;
+/** Pad to 9 bytes and stamp the Bit7 checksum into byte 7. */
+export declare function encodeCommand(bytes: readonly number[]): Uint8Array;
+/** What a product id settles on its own: how the mouse is reached. */
+export interface GearHubTransport {
+    transport: "dongle" | "direct";
+    /** Polling ceiling this link imposes regardless of the sensor. */
+    wiredPollingCeilingHz?: number;
+}
+/**
+ * Product ids on VID 0x3151 for this family, and the only thing the id itself
+ * settles: transport. The M5 Pro presents the 2.4 GHz receiver (0x402D) and,
+ * by cable, the mouse directly (0x4026).
+ *
+ * Bluetooth is a third mode not listed here: over BLE the device enumerates on
+ * a different usage page entirely (0xFF35/0xFF66) and GearHub drives it through
+ * a separate read path this driver does not implement.
+ */
+export declare const GEARHUB_PRODUCTS: ReadonlyMap<number, GearHubTransport>;
+/**
+ * Per-model identity, keyed by the GET_USB_VERSION device id. The receiver's
+ * VID:PID is shared across GearHub-V5 mice, so it cannot carry any of this —
+ * only the device id can. `brand` names the maker that ships this id.
+ */
+export interface GearHubProfile {
+    deviceId: number;
+    brand: "Lingbao" | "Attack Shark" | "GearHub";
+    model: string;
+    sensor: string;
+    maxPollingHz: number;
+    minDpi: number;
+    maxDpi: number;
+    dpiStep: number;
+}
+/**
+ * The M5 Pro receiver is an 8K part — GearHub flags 0x402D `reportRate: 8e3`
+ * and the mouse answered code 0 (8000 Hz) live. Lingbao's own base-M5-Pro
+ * sheet says 1000 Hz, so either it undersells the receiver or the bundle
+ * varies; this follows the hardware. Wired mode is capped to 1000 Hz by the
+ * `GEARHUB_PRODUCTS` entry, not here.
+ */
+export declare const LINGBAO_M5_PRO_PROFILE: GearHubProfile;
+/**
+ * Attack Shark R2. Same GearHub-V5 platform and VID:PID as the M5 Pro,
+ * distinguished only by device id 1893 (Attack Shark's own web driver shows it
+ * as `ID1893_v201`). Verified on retail hardware, both over the 2.4 GHz
+ * receiver and by cable (PID 0x4026): identity, firmware v2.01, the
+ * six-stage DPI table (top stage ~42000), 8000 Hz polling, DPI / lift-off /
+ * debounce / correction / sleep read + write, and 6-button remapping.
+ *
+ * qmk.top's catalog carries three R2 device ids: 1893 and 3009 on the
+ * original 0x40xx MCU (PID 0x4026 / 0x402D), and 3016 on the newer 0x50xx
+ * MCU (PID 0x5043). 1893 and 3009 share this profile; 3016 is not handled
+ * here - its PID is not in GEARHUB_PRODUCTS and it is most likely the
+ * individual-command firmware this block-protocol driver cannot drive.
+ */
+export declare const ATTACK_SHARK_R2_PROFILE: GearHubProfile;
+/**
+ * Attack Shark R3. Same GearHub-V5 platform, VID:PID and block protocol as
+ * the R2. qmk.top's catalog carries it under four device ids: 1643 and 3485
+ * with the PixArt PAW3395 (26000 DPI), 3309 and 3310 with the PAW3950
+ * (42000 DPI). Device id 1643 confirmed from a user diagnostic - firmware
+ * v3.00, on 0x3151:0x402D, every relay read (D3/D4/D0/8F/80) answering and
+ * a full status; it was falling back to the M5 Pro name only. The other
+ * three ids are catalog-derived.
+ */
+export declare const ATTACK_SHARK_R3_PROFILE: GearHubProfile;
+/** The PixArt PAW3950 R3 revision (device ids 3309 / 3310, catalog-derived). */
+export declare const ATTACK_SHARK_R3_3950_PROFILE: GearHubProfile;
+export declare const GEARHUB_DEVICE_PROFILES: ReadonlyMap<number, GearHubProfile>;
+/**
+ * Identity for a GearHub-V5 device this driver reached but could not name:
+ * GET_USB_VERSION failed, or it answered a device id not in the catalog.
+ * Deliberately generic - naming a concrete model here (it used to borrow the
+ * M5 Pro's) is a guess that is wrong for every sibling that is not an M5 Pro.
+ * The DPI/polling bounds are the platform ceilings so a real device's range
+ * is never clamped; the live DPI stages still come from the device's table.
+ */
+export declare const GEARHUB_FALLBACK_PROFILE: GearHubProfile;
+/** Resolve a device id to its profile, or the fallback. */
+export declare function gearHubProfileFor(deviceId: number | null | undefined): GearHubProfile;
+//# sourceMappingURL=index.d.ts.map

package/dist/gearhub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gearhub/index.ts"],"names":[],"mappings":"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"}

package/dist/gearhub/index.js

@@ -0,0 +1,282 @@
+/**
+ * GearHub-V5 codec — the transport-independent half of support for the
+ * MicLink/mlzn ODM platform on VID 0x3151 (qmk.top's "GearHub-V5" web tool).
+ *
+ * This layer knows packet shapes, command ids, the Bit7 checksum, the report-
+ * rate table, and the device catalog. It knows nothing about WebHID or the
+ * 2.4 GHz relay — that lives in `src/drivers/gearhub/hid.ts`.
+ *
+ * VID 0x3151 belongs to the ODM, not to any one brand: several unrelated
+ * makers ship on it. A GearHub-V5 mouse is identified by the GET_USB_VERSION
+ * *device id* (the same key GearHub's own bundle looks its model table up by),
+ * never by product id — the receiver's VID:PID is shared. The product id only
+ * settles transport (2.4 GHz receiver vs. direct cable).
+ *
+ * Everything here was read out of GearHub-V5's own JS bundle and confirmed
+ * byte for byte on hardware: a Lingbao M5 Pro (PAW3395, device id 2285) and an
+ * Attack Shark R2 (PAW3950, device id 1893), both on the 2.4 GHz receiver
+ * (0x3151:0x402D), Windows 11.
+ */
+export const GEARHUB_VENDOR_ID = 0x3151;
+export const GEARHUB_REPORT_ID = 0x00;
+export const GEARHUB_REPORT_SIZE = 64;
+export const GEARHUB_CMD_SIZE = 9;
+/** DPI stages the report layout has room for. */
+export const GEARHUB_MAX_DPI_STAGES = 8;
+/**
+ * Mouse-class command ids. GearHub groups settings into two 64-byte "option
+ * param" blocks that are read whole and written back whole:
+ *
+ *   OPTIONPARAM1 (GET 0xD4 / SET 0x54) — the DPI stage table.
+ *   OPTIONPARAM0 (GET 0xD3 / SET 0x53) — report rate (byte 9), debounce
+ *     (byte 10), lift-off / "silent height" (byte 52), sleep, sensitivity.
+ *
+ * There is no standalone GET/SET report-rate command — an earlier version of
+ * this driver used one (0x83 / 0x03) and the firmware silently ignored it.
+ */
+export const CMD = {
+    GET_FIRMWARE: 0x80,
+    GET_USB_VERSION: 0x8f,
+    GET_OPTIONPARAM0: 0xd3,
+    SET_OPTIONPARAM0: 0x53,
+    GET_DPI: 0xd4, // GET_OPTIONPARAM1
+    SET_DPI: 0x54, // SET_OPTIONPARAM1
+    GET_KEYMATRIX: 0xd0, // [0xD0, profile] -> 14 slots x 4-byte action, in one reply
+    SET_KEYMATRIX: 0x50, // [0x50, profile, slot, 0,0,0,0,0, d0,d1,d2,d3] -> one button
+};
+/**
+ * Receiver-level relay commands. Raw — the Bit7 checksum is NOT applied to
+ * these. The relay sequencing itself is the driver's job.
+ */
+export const DONGLE_CMD = {
+    SELECT_TARGET: 0xf6,
+    GET_STATUS: 0xf7,
+    NOTICE_READ: 0xfc,
+};
+export const TARGET_MOUSE = 0x05;
+/**
+ * OPTIONPARAM0 report-rate field (byte 9) encoding, from GearHub's
+ * `___utils_reportRateToNum` / `___utils_numToReportRate`. NOT a plain 0..6
+ * index — a bitmask-style code. Verified on hardware: an R2 at 1000 Hz read
+ * back code 1, and writing code 129 set it to 8000 Hz.
+ */
+export const REPORT_RATE_ENCODE = {
+    8000: 129,
+    4000: 130,
+    2000: 132,
+    1000: 1,
+    500: 2,
+    250: 4,
+    125: 8,
+};
+export const REPORT_RATE_DECODE = Object.fromEntries(Object.entries(REPORT_RATE_ENCODE).map(([hz, code]) => [code, Number(hz)]));
+/** Every rate the codec can express, ascending. */
+export const GEARHUB_RATES = Object.keys(REPORT_RATE_ENCODE)
+    .map(Number)
+    .sort((a, b) => a - b);
+/**
+ * OPTIONPARAM0 byte offsets (GET reply layout == SET payload layout), from
+ * GearHub's `___getMouseOption0` / `___cmdSetMouseOption0`.
+ */
+export const OPT0_REPORT_RATE = 9;
+export const OPT0_DEBOUNCE = 10;
+/** 16-bit LE flags word. Bit 2 is ripple correction ("wave repair"). */
+export const OPT0_FLAGS = 12;
+export const OPT0_FLAG_RIPPLE = 1 << 2;
+/** LE16 idle-before-standby, in seconds. GearHub exposes a per-link timer. */
+export const OPT0_SLEEP_BT = 40;
+export const OPT0_SLEEP_24G = 44;
+/** Straight-line / angle-snapping correction ("line repair"): 0 or 1. */
+export const OPT0_STRAIGHT_CORRECTION = 53;
+/** Lift-off / "silent height": an index into the sensor's lift-off list. */
+export const OPT0_SILENT_HEIGHT = 52;
+/** GearHub's Debounce slider runs 1-10 (ms). */
+export const GEARHUB_DEBOUNCE_MAX_MS = 10;
+/**
+ * Standby-time stops offered to the UI, in seconds; 0 = never sleep. GearHub
+ * itself takes a free-form seconds value — this is the discrete set the
+ * OpenMouse sleep card renders, chosen to cover the useful range.
+ */
+export const GEARHUB_SLEEP_OPTIONS = [0, 15, 30, 60, 120, 300];
+/** DPI table (OPTIONPARAM1) byte offsets, confirmed on hardware:
+ *   [2] active stage index, [3] stage count,
+ *   [8 + i*2] X as LE uint16, [24 + i*2] Y as LE uint16,
+ *   [40 + i*3] that stage's indicator colour as r, g, b. */
+export const DPI_X_OFFSET = 8;
+export const DPI_Y_OFFSET = 24;
+export const DPI_RGB_OFFSET = 40;
+/**
+ * Lift-off stops per sensor, ordered by the OPTIONPARAM0 byte-52 index
+ * (ascending height). Derived from GearHub's `getLiftOffDistance()`:
+ * PAW3950/3955 offer 0.7 / 1 / 2 mm; PAW3395 offers 1 / 2 mm.
+ */
+export const GEARHUB_LIFT_OFF_LEVELS = {
+    "PixArt PAW3950": ["Low", "Medium", "High"],
+    "PixArt PAW3955": ["Low", "Medium", "High"],
+    "PixArt PAW3395": ["Low", "High"],
+    // Unidentified GearHub-V5 device: offer the common three stops. The
+    // firmware clamps the index if its sensor only has two.
+    "PixArt (GearHub-V5)": ["Low", "Medium", "High"],
+};
+export const GEARHUB_BUTTONS = [
+    { name: "Left", slot: 0 },
+    { name: "Right", slot: 1 },
+    { name: "Middle", slot: 2 },
+    { name: "Back", slot: 3 },
+    { name: "Forward", slot: 4 },
+    { name: "DPI", slot: 5 },
+];
+/**
+ * Assignable actions, label → 4-byte matrix value, from GearHub's `ia` table.
+ * Mouse functions only (no keyboard keys, combos or macros — OpenMouse's
+ * generic remapper is a single-choice dropdown). Left…Forward and DPI Loop
+ * were confirmed on hardware; DPI ± come straight from the bundle.
+ */
+export const GEARHUB_BUTTON_ACTIONS = [
+    ["Left Click", [1, 0, 0xf0, 0]],
+    ["Right Click", [1, 0, 0xf1, 0]],
+    ["Middle Click", [1, 0, 0xf2, 0]],
+    ["Back", [1, 0, 0xf3, 0]],
+    ["Forward", [1, 0, 0xf4, 0]],
+    ["DPI Loop", [20, 0, 0, 0]],
+    ["DPI +", [20, 0, 1, 0]],
+    ["DPI -", [0, 2, 0, 20]],
+    ["Disabled", [0, 0, 0, 0]],
+];
+/** Decode a 4-byte slot to an action label; "Custom" for anything else
+ *  (a keyboard key / macro set in GearHub — left untouched). */
+export function decodeButtonAction(bytes) {
+    for (const [label, value] of GEARHUB_BUTTON_ACTIONS) {
+        if (value.every((b, i) => b === bytes[i]))
+            return label;
+    }
+    return "Custom";
+}
+/** Encode an action label to its 4-byte slot value, or null if unknown. */
+export function encodeButtonAction(label) {
+    return GEARHUB_BUTTON_ACTIONS.find(([l]) => l === label)?.[1] ?? null;
+}
+/** Pad to 9 bytes and stamp the Bit7 checksum into byte 7. */
+export function encodeCommand(bytes) {
+    const out = new Uint8Array(Math.max(GEARHUB_CMD_SIZE, bytes.length));
+    out.set(bytes);
+    let sum = 0;
+    for (let i = 0; i < 7; i++)
+        sum = (sum + out[i]) & 0xff;
+    out[7] = (255 - sum) & 0xff;
+    return out;
+}
+/**
+ * Product ids on VID 0x3151 for this family, and the only thing the id itself
+ * settles: transport. The M5 Pro presents the 2.4 GHz receiver (0x402D) and,
+ * by cable, the mouse directly (0x4026).
+ *
+ * Bluetooth is a third mode not listed here: over BLE the device enumerates on
+ * a different usage page entirely (0xFF35/0xFF66) and GearHub drives it through
+ * a separate read path this driver does not implement.
+ */
+export const GEARHUB_PRODUCTS = new Map([
+    [0x402d, { transport: "dongle" }],
+    [0x4026, { transport: "direct", wiredPollingCeilingHz: 1000 }],
+]);
+/**
+ * The M5 Pro receiver is an 8K part — GearHub flags 0x402D `reportRate: 8e3`
+ * and the mouse answered code 0 (8000 Hz) live. Lingbao's own base-M5-Pro
+ * sheet says 1000 Hz, so either it undersells the receiver or the bundle
+ * varies; this follows the hardware. Wired mode is capped to 1000 Hz by the
+ * `GEARHUB_PRODUCTS` entry, not here.
+ */
+export const LINGBAO_M5_PRO_PROFILE = {
+    deviceId: 2285,
+    brand: "Lingbao",
+    model: "M5 Pro",
+    sensor: "PixArt PAW3395",
+    maxPollingHz: 8000,
+    minDpi: 50,
+    maxDpi: 26000,
+    dpiStep: 50,
+};
+/**
+ * Attack Shark R2. Same GearHub-V5 platform and VID:PID as the M5 Pro,
+ * distinguished only by device id 1893 (Attack Shark's own web driver shows it
+ * as `ID1893_v201`). Verified on retail hardware, both over the 2.4 GHz
+ * receiver and by cable (PID 0x4026): identity, firmware v2.01, the
+ * six-stage DPI table (top stage ~42000), 8000 Hz polling, DPI / lift-off /
+ * debounce / correction / sleep read + write, and 6-button remapping.
+ *
+ * qmk.top's catalog carries three R2 device ids: 1893 and 3009 on the
+ * original 0x40xx MCU (PID 0x4026 / 0x402D), and 3016 on the newer 0x50xx
+ * MCU (PID 0x5043). 1893 and 3009 share this profile; 3016 is not handled
+ * here - its PID is not in GEARHUB_PRODUCTS and it is most likely the
+ * individual-command firmware this block-protocol driver cannot drive.
+ */
+export const ATTACK_SHARK_R2_PROFILE = {
+    deviceId: 1893,
+    brand: "Attack Shark",
+    model: "R2",
+    sensor: "PixArt PAW3950",
+    maxPollingHz: 8000,
+    minDpi: 50,
+    maxDpi: 42000,
+    dpiStep: 50,
+};
+/**
+ * Attack Shark R3. Same GearHub-V5 platform, VID:PID and block protocol as
+ * the R2. qmk.top's catalog carries it under four device ids: 1643 and 3485
+ * with the PixArt PAW3395 (26000 DPI), 3309 and 3310 with the PAW3950
+ * (42000 DPI). Device id 1643 confirmed from a user diagnostic - firmware
+ * v3.00, on 0x3151:0x402D, every relay read (D3/D4/D0/8F/80) answering and
+ * a full status; it was falling back to the M5 Pro name only. The other
+ * three ids are catalog-derived.
+ */
+export const ATTACK_SHARK_R3_PROFILE = {
+    deviceId: 1643,
+    brand: "Attack Shark",
+    model: "R3",
+    sensor: "PixArt PAW3395",
+    maxPollingHz: 8000,
+    minDpi: 50,
+    maxDpi: 26000,
+    dpiStep: 50,
+};
+/** The PixArt PAW3950 R3 revision (device ids 3309 / 3310, catalog-derived). */
+export const ATTACK_SHARK_R3_3950_PROFILE = {
+    ...ATTACK_SHARK_R3_PROFILE,
+    deviceId: 3309,
+    sensor: "PixArt PAW3950",
+    maxDpi: 42000,
+};
+export const GEARHUB_DEVICE_PROFILES = new Map([
+    [LINGBAO_M5_PRO_PROFILE.deviceId, LINGBAO_M5_PRO_PROFILE],
+    [ATTACK_SHARK_R2_PROFILE.deviceId, ATTACK_SHARK_R2_PROFILE],
+    // A later R2 firmware batch on the same 0x40xx silicon, PID and PAW3950
+    // sensor as 1893. Block protocol assumed identical; not hardware-verified.
+    [3009, ATTACK_SHARK_R2_PROFILE],
+    [ATTACK_SHARK_R3_PROFILE.deviceId, ATTACK_SHARK_R3_PROFILE],
+    [3485, ATTACK_SHARK_R3_PROFILE],
+    [ATTACK_SHARK_R3_3950_PROFILE.deviceId, ATTACK_SHARK_R3_3950_PROFILE],
+    [3310, ATTACK_SHARK_R3_3950_PROFILE],
+]);
+/**
+ * Identity for a GearHub-V5 device this driver reached but could not name:
+ * GET_USB_VERSION failed, or it answered a device id not in the catalog.
+ * Deliberately generic - naming a concrete model here (it used to borrow the
+ * M5 Pro's) is a guess that is wrong for every sibling that is not an M5 Pro.
+ * The DPI/polling bounds are the platform ceilings so a real device's range
+ * is never clamped; the live DPI stages still come from the device's table.
+ */
+export const GEARHUB_FALLBACK_PROFILE = {
+    deviceId: 0,
+    brand: "GearHub",
+    model: "V5 mouse",
+    sensor: "PixArt (GearHub-V5)",
+    maxPollingHz: 8000,
+    minDpi: 50,
+    maxDpi: 42000,
+    dpiStep: 50,
+};
+/** Resolve a device id to its profile, or the fallback. */
+export function gearHubProfileFor(deviceId) {
+    return (deviceId != null && GEARHUB_DEVICE_PROFILES.get(deviceId)) || GEARHUB_FALLBACK_PROFILE;
+}
+//# sourceMappingURL=index.js.map

package/dist/gearhub/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gearhub/index.ts"],"names":[],"mappings":"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"}

package/dist/glorious/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure encoding rules of the Glorious Model O 2 / I 2 family (Pixart firmware,
+ * VID 0x093a). The configuration interface is write-only: the firmware accepts
+ * a 256-byte settings payload assembled from four 64-byte feature reports
+ * (report ID 0x03) on USB interface 1, but never echoes settings back.
+ * Reverse-engineered layout: https://github.com/zeppybabe/gloriousctl-linux.
+ */
+export declare const GLORIOUS_CONFIG_REPORT_ID = 3;
+export declare const GLORIOUS_PACKET_LENGTH = 64;
+export declare const GLORIOUS_DPI_UNIT = 50;
+export declare const GLORIOUS_DPI_MIN = 100;
+export declare const GLORIOUS_DPI_MAX = 26000;
+/** Payload byte [9]: 0x01(1k), 0x02(125), 0x03(250), 0x04(500). */
+export declare const GLORIOUS_POLLING_RATES: ReadonlyArray<readonly [code: number, hertz: number]>;
+/** Payload byte [7]: 0x01 (1 mm) or 0x02 (2 mm); 0.7 mm is not exposed. */
+export declare const GLORIOUS_LOD_MEDIUM_MM = 1;
+export declare const GLORIOUS_LOD_HIGH_MM = 2;
+/** Payload byte [8]: debounce in milliseconds, even numbers, 0x00-0x10. */
+export declare const GLORIOUS_DEBOUNCE_MAX_MS = 16;
+export declare const GLORIOUS_MAX_STAGES = 6;
+/** Lighting payload (cmd 02 fb) RGB effect ids ([5]). */
+export declare const GLORIOUS_RGB_EFFECTS: {
+    readonly off: 0;
+    readonly glorious: 1;
+    readonly seamlessBreathing: 2;
+    readonly breathing: 3;
+    readonly normallyOn: 4;
+    readonly breathingSingle: 5;
+    readonly tail: 6;
+    readonly rave: 7;
+    readonly wave: 8;
+};
+export type GloriousRgbEffectId = keyof typeof GLORIOUS_RGB_EFFECTS;
+export declare const GLORIOUS_EFFECT_OPTIONS: ReadonlyArray<readonly [id: GloriousRgbEffectId, label: string]>;
+/** Brightness ([6]/[7]) and speed ([9]) map onto five/four CORE levels. */
+export declare const GLORIOUS_BRIGHTNESS_LEVELS: ReadonlyArray<number>;
+export declare const GLORIOUS_SPEED_LEVELS: ReadonlyArray<number>;
+export interface GloriousLighting {
+    /** One of GLORIOUS_RGB_EFFECTS values. */
+    effect: number;
+    brightnessWired: number;
+    brightnessWireless: number;
+    speed: number;
+    /** "#rrggbb" strings: [0] primary plus up to six cycle colors. */
+    colors: string[];
+}
+export declare const GLORIOUS_DEFAULT_LIGHTING: GloriousLighting;
+/** Number of palette slots an effect consumes ([8]): solid 1, rave 2, rainbow 7. */
+export declare function gloriousLightingColorCount(effect: number): number;
+/**
+ * Builds the three 64-byte feature-report fragments of the lighting payload:
+ * fragment 0 carries effect, wireless/wired brightness, color count, speed,
+ * modifier, and the primary color; fragment 1 echoes the effect and holds the
+ * six-cycle palette; fragment 2 echoes the effect again.
+ */
+export declare function buildGloriousLightingPayload(lighting: GloriousLighting): Uint8Array<ArrayBuffer>[];
+/** Repairs untrusted persisted lighting state into a payload-safe object. */
+export declare function gloriousNormalizeLighting(value: unknown): GloriousLighting;
+export interface GloriousSettings {
+    /** Zero-indexed active DPI stage ([5]). */
+    activeStage: number;
+    /** Enabled stages, 4-6 ([6]). */
+    stageCount: number;
+    /** Six DPI stage values; unused stages stay at 0. */
+    stageDpis: number[];
+    /** "#rrggbb" LED color shown while the DPI button cycles through a stage. */
+    stageColors: string[];
+    lodMm: number;
+    debounceMs: number;
+    pollingCode: number;
+}
+/** Factory per-stage indicator colors (red, blue, green, yellow), then unset. */
+export declare const GLORIOUS_DEFAULT_STAGE_COLORS: ReadonlyArray<string>;
+export declare const GLORIOUS_DEFAULT_SETTINGS: GloriousSettings;
+export declare function gloriousEncodeDpi(dpi: number): number;
+export declare function gloriousIsSupportedDpi(dpi: number): boolean;
+export declare function gloriousEncodePolling(hertz: number): number | null;
+export declare function gloriousDecodePolling(code: number): number | null;
+export declare function gloriousSanitizeDebounce(milliseconds: number): number;
+/**
+ * Builds the four 64-byte feature-report fragments of the settings payload:
+ * header (report ID 0x03, cmd 04 fb, sequence, pad 0x01), then the global
+ * bytes ([5] active stage, [6] total stages, [7] LOD, [8] debounce, [9]
+ * polling) followed by little-endian DPI u16 divided by 50 plus RGB per stage.
+ */
+export declare function buildGloriousSettingsPayload(settings: GloriousSettings): Uint8Array<ArrayBuffer>[];
+/** Repairs untrusted persisted state into a payload-safe settings object. */
+export declare function gloriousNormalizeSettings(value: unknown): GloriousSettings;
+//# sourceMappingURL=index.d.ts.map

package/dist/glorious/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/glorious/index.ts"],"names":[],"mappings":"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"}