@openmouse/protocol 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to Mouse Protocol
+
+Thank you for helping make gaming mouse hardware more open. This repository
+contains the protocol and WebHID driver layers used by OpenMouse: packet
+layouts, commands, checksums, encoders, decoders, protocol value types, device
+catalogs, discovery filters, and hardware-facing clients.
+
+## Before you start
+
+For a new device or a substantial protocol change, open an issue or draft pull
+request early. Include the mouse model, USB vendor and product IDs, connection
+type, and what you have verified on real hardware. Early discussion helps avoid
+duplicating reverse-engineering work and establishes where the transport and
+protocol boundaries belong.
+
+Only contribute material that you have permission to share. Do not commit
+vendor binaries, proprietary source code, account information, device serial
+numbers, or captures containing personal data.
+
+## Development setup
+
+Requirements:
+
+- Node.js 20 or newer
+- npm
+
+Clone the repository and run:
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` performs a strict TypeScript build and verifies the contents of
+the npm package. Generated `dist/` files are not committed.
+
+## What belongs here
+
+The codec layer under the brand folders in `src/` must work without knowing how
+bytes are transported. Good examples include:
+
+- report IDs, packet sizes, commands, status values, and offsets;
+- checksums and packet framing;
+- pure encoders and decoders;
+- conversions between wire values and protocol-level values;
+- product IDs and capabilities that determine which commands are valid.
+
+The WebHID driver layer under `src/drivers/` owns:
+
+- WebHID discovery and permissions;
+- opening devices and sending or receiving reports;
+- retries, delays, queues, connection recovery, and read-back verification;
+- conversion from wire values into shared `MouseStatus` values;
+- the supported-device registry and browser request filters.
+
+Keep rendering, DOM access, application state, notifications, and saved UI
+preferences in the consuming application. A driver may provide declarative UI
+hints, but it must not render or query application elements.
+
+Protocol functions should be deterministic wherever possible. Prefer functions
+that accept bytes or plain values and return a new `Uint8Array`, object, or
+primitive. Do not mutate caller-owned buffers unless the API explicitly says it
+does so.
+
+## Adding or changing a protocol
+
+1. Add or update a focused module under the brand's `src/<brand>/` folder. Put
+   genuinely shared wire framing under a protocol-family folder such as
+   `src/compx/`, then re-export it through each applicable brand entry point.
+2. Export new public APIs from a package subpath in `package.json`.
+3. Add the module namespace to `src/index.ts` when it should be available from
+   the package root.
+4. Keep exported names vendor-specific when a generic name could collide. For
+   example, prefer `razerSetDpiCommand` over `setDpiCommand`.
+5. Build the package and integrate the packed API into OpenMouse.
+
+Use `.js` extensions for relative imports in TypeScript source. The package uses
+NodeNext module resolution and publishes ECMAScript modules.
+
+Treat existing exports as a public API. Avoid renaming or changing their
+meaning without explaining the migration and updating all known consumers.
+
+For a WebHID driver, add the implementation under
+`src/drivers/<brand>/`, register it in `src/drivers/registry.ts`, and update
+`src/drivers/vendors.ts` when the browser picker needs a new filter. Drivers
+should use the public codec entry point for their brand rather than duplicating
+packet logic.
+
+## Evidence and hardware verification
+
+Protocol changes should state where the information came from. Useful evidence
+includes public documentation, links to compatible open-source drivers,
+sanitized USB captures, and before/after observations from vendor software.
+Clearly separate observed facts from hypotheses.
+
+When a catalog has a `verified` field, set it to `true` only after that exact
+product ID and connection path have been exercised on hardware. Recognizing a
+USB ID or sharing a protocol family is not sufficient.
+
+For write commands:
+
+- begin with read-only discovery when possible;
+- preserve unknown bytes during read-modify-write operations;
+- validate ranges and packet lengths before encoding;
+- verify writes by reading the value back;
+- document whether a setting is volatile or stored in device memory;
+- avoid speculative commands that could alter firmware or calibration data.
+
+## Testing with OpenMouse
+
+Codec and driver tests live beside their driver modules under `src/drivers/`.
+Add or update focused tests for known captured packets, invalid or truncated
+replies, supported value boundaries, encode/decode round trips, discovery
+filters, and read-back behavior.
+
+To verify the consuming application, check out the `openmouse` and
+`mouse-protocol` repositories as siblings, then install your local build into
+OpenMouse without changing its manifest:
+
+```sh
+cd mouse-protocol
+npm run build
+
+cd ../openmouse
+npm install --no-save --package-lock=false ../mouse-protocol
+npm run check
+```
+
+Before submitting a driver pull request, run both the package check and the
+OpenMouse check against your local package. A new product entry must also keep
+the driver registry overlap tests passing.
+
+## Pull requests
+
+Keep a pull request focused on one protocol family or closely related change.
+In its description, include:
+
+- the device models, product IDs, firmware versions, and connection paths;
+- what was tested on physical hardware;
+- the evidence or public references supporting the packet format;
+- any unknown fields or assumptions that remain;
+- the matching OpenMouse pull request when application changes are required.
+
+Commit subjects on `main` are release inputs and must follow Conventional
+Commits. When a pull request is squash-merged, its title becomes that subject.
+Use `fix:` for a patch release, `feat:` for a minor release, and `!` or a
+`BREAKING CHANGE:` footer for an incompatible API change. Documentation, test,
+and maintenance-only changes do not publish a package release.
+
+Before requesting review, confirm that:
+
+- `npm run check` passes in this repository;
+- OpenMouse builds and its full test suite passes with the local package;
+- every new module is exported through the intended package subpath;
+- no generated files, captures with identifiers, or unrelated changes are
+  included.
+
+Small, evidence-backed improvements are welcome even when a protocol is not yet
+fully understood. Documenting an unknown accurately is better than assigning it
+a guessed meaning.
+
+## Releases
+
+Release Please collects releasable commits into a version pull request. Merging
+that pull request creates the matching GitHub release and publishes the exact
+commit as `@openmouse/protocol`. Do not edit package versions or create release
+tags by hand.

package/README.md

@@ -0,0 +1,89 @@
+# `@openmouse/protocol`
+
+Transport-independent gaming mouse protocol codecs used by OpenMouse.
+
+The package owns packet layouts, command constants, checksums, encoders,
+decoders, protocol-specific value types, device catalogs, and the WebHID
+drivers used by OpenMouse. Pure codec entry points do not depend on WebHID, so
+browser, Node.js, and TypeScript projects can use them independently from the
+optional driver layer.
+
+```ts
+import { buildFinalmouseReport } from "@openmouse/protocol/finalmouse";
+import { encodeRazerRequest } from "@openmouse/protocol/razer";
+import { RAZER_PRODUCTS } from "@openmouse/protocol/razer-devices";
+
+import {
+  createSupportedClient,
+  SUPPORTED_HID_FILTERS,
+} from "@openmouse/protocol/drivers";
+```
+
+## Development
+
+```sh
+npm install
+npm run check
+```
+
+The `prepare` script builds `dist` automatically when this package is installed
+directly from Git. Codec sources are grouped by brand under `src/`; WebHID
+drivers, discovery filters, the driver registry, and shared status types live
+under `src/drivers/`. OpenMouse retains application orchestration and UI code.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for protocol boundaries, hardware
+evidence requirements, local OpenMouse integration, and the pull-request
+checklist.
+
+## Protocol entry points
+
+| Brand | Import |
+| --- | --- |
+| ATK | `@openmouse/protocol/atk` |
+| Corsair | `@openmouse/protocol/corsair` |
+| Dareu | `@openmouse/protocol/dareu` |
+| Endgame Gear OP1/XM2 8K | `@openmouse/protocol/endgame-gear-op1` |
+| Endgame Gear wireless | `@openmouse/protocol/endgame-gear-we` |
+| Fantech | `@openmouse/protocol/fantech` |
+| Finalmouse | `@openmouse/protocol/finalmouse` |
+| G-Wolves | `@openmouse/protocol/gwolves` |
+| GearHub (Attack Shark / Lingbao) | `@openmouse/protocol/gearhub` |
+| Glorious | `@openmouse/protocol/glorious` |
+| Glorious classic (Model O/D/I) | `@openmouse/protocol/glorious-classic` |
+| HyperX | `@openmouse/protocol/hyperx` |
+| Incott | `@openmouse/protocol/incott` |
+| K-snake | `@openmouse/protocol/ksnake` |
+| Keychron | `@openmouse/protocol/keychron` |
+| Lamzu / CRDRAKO / Attack Shark | `@openmouse/protocol/lamzu` |
+| Logitech | `@openmouse/protocol/logitech` |
+| MCHOSE | `@openmouse/protocol/mchose` |
+| Microsoft | `@openmouse/protocol/microsoft` |
+| moddoMOUSE | `@openmouse/protocol/moddo` |
+| Ninjutso | `@openmouse/protocol/ninjutso` |
+| Orbital | `@openmouse/protocol/orbital` |
+| RAWM | `@openmouse/protocol/rawm` |
+| Pulsar | `@openmouse/protocol/pulsar` |
+| Razer legacy/current | `@openmouse/protocol/razer` |
+| Razer V4 | `@openmouse/protocol/razer-v4` |
+| SteelSeries Rival 3 (Gen 1) | `@openmouse/protocol/steelseries` |
+| Teevolution | `@openmouse/protocol/teevolution` |
+| VGN | `@openmouse/protocol/vgn` |
+| WALLHACK | `@openmouse/protocol/wallhack` |
+| WLMouse | `@openmouse/protocol/wlmouse` |
+| Wooting | `@openmouse/protocol/wooting` |
+| Zaunkoenig | `@openmouse/protocol/zaunkoenig` |
+
+An exported protocol means OpenMouse implements that wire format. It does not
+claim every mouse from that brand works. When a catalog provides a `verified`
+field, use it to distinguish hardware-tested support from USB recognition.
+
+The Ninjutso catalog and packet layouts are derived from the JavaScript shipped
+by the official NinjaForce WebHID panel. They have automated transport and
+codec coverage, but are not marked as hardware-verified until tested on the
+corresponding Sora V2/V3 and TEN-family devices.
+
+The SteelSeries Rival 3 Gen 1 codec and driver are derived from the public
+rivalcfg project, corroborated against libratbag and OpenRGB. The device is
+write-only — only the firmware version can be read back — and no entry is
+marked hardware-verified yet. See
+[docs/steelseries-testing.md](docs/steelseries-testing.md).

package/dist/asus/index.d.ts

@@ -0,0 +1,52 @@
+export declare const ASUS_VENDOR_ID = 2821;
+export declare const ROG_GLADIUS_II_PRODUCT_ID = 6213;
+export declare const ASUS_GLADIUS_II_USAGE_PAGE = 65281;
+export declare const ASUS_GLADIUS_II_USAGE = 1;
+export declare const ASUS_REPORT_ID = 0;
+export declare const ASUS_REPORT_SIZE = 64;
+export declare const GLADIUS_II_MIN_DPI = 100;
+export declare const GLADIUS_II_MAX_DPI = 12000;
+export declare const GLADIUS_II_DPI_STEP = 100;
+export declare const GLADIUS_II_PROFILE_COUNT = 3;
+export declare const GLADIUS_II_POLLING_RATES: readonly [125, 250, 500, 1000];
+export declare const GLADIUS_II_DEBOUNCE_MS: readonly [12, 16, 20, 24, 28, 32];
+export type GladiusIILiftOffDistance = "Low" | "High";
+export interface GladiusIISettings {
+    dpiStages: [number, number];
+    pollingRateHz: number;
+    debounceMs: number | null;
+    angleSnapping: boolean;
+}
+export interface GladiusIIProfile {
+    onboardProfile: number;
+    activeDpiStage: number;
+}
+export interface GladiusIIRawLightingZone {
+    zone: number;
+    mode: number;
+    brightness: number;
+    red: number;
+    green: number;
+    blue: number;
+    direction: number;
+    randomColor: boolean;
+    speed: number;
+}
+export declare function decodeGladiusIISettings(data: Uint8Array): GladiusIISettings;
+export declare function decodeGladiusIIProfile(data: Uint8Array): GladiusIIProfile;
+export declare function decodeGladiusIILiftOffDistance(data: Uint8Array): GladiusIILiftOffDistance;
+export declare function decodeGladiusIILighting(data: Uint8Array): GladiusIIRawLightingZone[];
+export declare function gladiusIIReadSettingsRequest(): Uint8Array;
+export declare function gladiusIIReadProfileRequest(): Uint8Array;
+export declare function gladiusIIReadLiftOffRequest(): Uint8Array;
+export declare function gladiusIIReadLightingRequest(): Uint8Array;
+export declare function gladiusIISetDpiRequest(stage: number, dpi: number): Uint8Array;
+export declare function gladiusIISetActiveDpiStageRequest(stage: number): Uint8Array;
+export declare function gladiusIISetPollingRateRequest(pollingRateHz: number): Uint8Array;
+export declare function gladiusIISetProfileRequest(profile: number): Uint8Array;
+export declare function gladiusIISetAngleSnappingRequest(enabled: boolean): Uint8Array;
+export declare function gladiusIISetDebounceRequest(milliseconds: number): Uint8Array;
+export declare function gladiusIISetLiftOffRequest(value: GladiusIILiftOffDistance): Uint8Array;
+export declare function gladiusIISetLightingRequest(zone: number, mode: number, brightness: number, red: number, green: number, blue: number, direction?: number, randomColor?: number, speed?: number): Uint8Array;
+export declare function gladiusIISaveRequest(): Uint8Array;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asus/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,OAAS,CAAC;AAErC,eAAO,MAAM,yBAAyB,OAAS,CAAC;AAEhD,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,qBAAqB,IAAS,CAAC;AAE5C,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,eAAO,MAAM,wBAAwB,gCAK3B,CAAC;AAEX,eAAO,MAAM,sBAAsB,mCAOzB,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAChC,KAAK,GACL,MAAM,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAgED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,UAAU,GACf,iBAAiB,CAsDnB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,GACf,gBAAgB,CAmClB;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,UAAU,GACf,wBAAwB,CA0B1B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,UAAU,GACf,wBAAwB,EAAE,CAwC5B;AAMD,wBAAgB,4BAA4B,IAAI,UAAU,CAMzD;AAED,wBAAgB,2BAA2B,IAAI,UAAU,CAKxD;AAED,wBAAgB,2BAA2B,IAAI,UAAU,CAKxD;AAED,wBAAgB,4BAA4B,IAAI,UAAU,CAMzD;AAMD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,UAAU,CAqCZ;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,MAAM,GACZ,UAAU,CAkBZ;AAMD,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,MAAM,GACpB,UAAU,CAoBZ;AAMD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GACd,UAAU,CAiBZ;AAMD,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,OAAO,GACf,UAAU,CAQZ;AAMD,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GACnB,UAAU,CAsBZ;AAMD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,UAAU,CAcZ;AAMD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,SAAI,EACb,WAAW,SAAI,EACf,KAAK,SAAI,GACR,UAAU,CAkCZ;AAMD,wBAAgB,oBAAoB,IAAI,UAAU,CAKjD"}

package/dist/asus/index.js

@@ -0,0 +1,248 @@
+export const ASUS_VENDOR_ID = 0x0b05;
+export const ROG_GLADIUS_II_PRODUCT_ID = 0x1845;
+export const ASUS_GLADIUS_II_USAGE_PAGE = 0xff01;
+export const ASUS_GLADIUS_II_USAGE = 0x0001;
+export const ASUS_REPORT_ID = 0;
+export const ASUS_REPORT_SIZE = 64;
+export const GLADIUS_II_MIN_DPI = 100;
+export const GLADIUS_II_MAX_DPI = 12000;
+export const GLADIUS_II_DPI_STEP = 100;
+export const GLADIUS_II_PROFILE_COUNT = 3;
+export const GLADIUS_II_POLLING_RATES = [
+    125,
+    250,
+    500,
+    1000,
+];
+export const GLADIUS_II_DEBOUNCE_MS = [
+    12,
+    16,
+    20,
+    24,
+    28,
+    32,
+];
+function requirePrefix(data, expected, name) {
+    if (data.length < expected.length) {
+        throw new Error(`${name} reply is too short.`);
+    }
+    for (let i = 0; i < expected.length; i++) {
+        if (data[i] !== expected[i]) {
+            throw new Error(`${name} reply has unexpected byte ${i}: ` +
+                `0x${data[i]
+                    ?.toString(16)
+                    .padStart(2, "0")}`);
+        }
+    }
+}
+function readUint16LE(data, offset) {
+    return (data[offset] |
+        (data[offset + 1] << 8));
+}
+function decodeDpiWord(value) {
+    return ((value + 1) *
+        GLADIUS_II_DPI_STEP);
+}
+function request(...bytes) {
+    const data = new Uint8Array(ASUS_REPORT_SIZE);
+    data.set(bytes);
+    return data;
+}
+/* ---------------------------------
+ * READ DECODERS
+ * --------------------------------- */
+export function decodeGladiusIISettings(data) {
+    requirePrefix(data, [0x12, 0x04, 0x00], "Gladius II settings");
+    if (data.length < 13) {
+        throw new Error("Gladius II settings reply is incomplete.");
+    }
+    const dpi1 = decodeDpiWord(readUint16LE(data, 4));
+    const dpi2 = decodeDpiWord(readUint16LE(data, 6));
+    const pollingRaw = data[8];
+    const pollingRateHz = GLADIUS_II_POLLING_RATES[pollingRaw];
+    if (pollingRateHz === undefined) {
+        throw new Error(`Unknown Gladius II polling value 0x${pollingRaw
+            .toString(16)
+            .padStart(2, "0")}.`);
+    }
+    const debounceRaw = data[10];
+    const debounceMs = debounceRaw >= 0x02 &&
+        debounceRaw <= 0x07
+        ? debounceRaw * 4 + 4
+        : null;
+    return {
+        dpiStages: [dpi1, dpi2],
+        pollingRateHz,
+        debounceMs,
+        angleSnapping: data[12] === 0x01,
+    };
+}
+export function decodeGladiusIIProfile(data) {
+    requirePrefix(data, [0x12, 0x00, 0x00], "Gladius II profile");
+    if (data.length < 12) {
+        throw new Error("Gladius II profile reply is incomplete.");
+    }
+    const onboardProfileRaw = data[10];
+    const dpiStageRaw = data[11];
+    if (dpiStageRaw < 1 ||
+        dpiStageRaw > 2) {
+        throw new Error(`Invalid Gladius II DPI stage ${dpiStageRaw}.`);
+    }
+    return {
+        onboardProfile: onboardProfileRaw + 1,
+        activeDpiStage: dpiStageRaw - 1,
+    };
+}
+export function decodeGladiusIILiftOffDistance(data) {
+    requirePrefix(data, [0x12, 0x06], "Gladius II lift-off");
+    if (data.length < 8) {
+        throw new Error("Gladius II lift-off reply is incomplete.");
+    }
+    const raw = data[7];
+    if (raw === 0) {
+        return "Low";
+    }
+    if (raw === 1) {
+        return "High";
+    }
+    throw new Error(`Unknown Gladius II lift-off value ${raw}.`);
+}
+export function decodeGladiusIILighting(data) {
+    requirePrefix(data, [0x12, 0x03, 0x00], "Gladius II lighting");
+    if (data.length < 23) {
+        throw new Error("Gladius II lighting reply is incomplete.");
+    }
+    const direction = data[20];
+    const randomColor = data[21] === 0x01;
+    const speed = data[22];
+    const zones = [];
+    for (let zone = 0; zone < 3; zone++) {
+        const offset = 4 + zone * 5;
+        zones.push({
+            zone,
+            mode: data[offset],
+            brightness: data[offset + 1],
+            red: data[offset + 2],
+            green: data[offset + 3],
+            blue: data[offset + 4],
+            direction,
+            randomColor,
+            speed,
+        });
+    }
+    return zones;
+}
+/* ---------------------------------
+ * READ REQUESTS
+ * --------------------------------- */
+export function gladiusIIReadSettingsRequest() {
+    return request(0x12, 0x04, 0x00);
+}
+export function gladiusIIReadProfileRequest() {
+    return request(0x12, 0x00);
+}
+export function gladiusIIReadLiftOffRequest() {
+    return request(0x12, 0x06);
+}
+export function gladiusIIReadLightingRequest() {
+    return request(0x12, 0x03, 0x00);
+}
+/* ---------------------------------
+ * DPI
+ * --------------------------------- */
+export function gladiusIISetDpiRequest(stage, dpi) {
+    if (!Number.isInteger(stage) ||
+        stage < 0 ||
+        stage > 1) {
+        throw new Error("Gladius II DPI stage must be 0 or 1.");
+    }
+    if (!Number.isInteger(dpi) ||
+        dpi < GLADIUS_II_MIN_DPI ||
+        dpi > GLADIUS_II_MAX_DPI ||
+        dpi %
+            GLADIUS_II_DPI_STEP !==
+            0) {
+        throw new Error(`Gladius II DPI must be ${GLADIUS_II_MIN_DPI}-${GLADIUS_II_MAX_DPI} in ${GLADIUS_II_DPI_STEP}-DPI steps.`);
+    }
+    const encoded = (dpi -
+        GLADIUS_II_DPI_STEP) /
+        GLADIUS_II_DPI_STEP;
+    return request(0x51, 0x31, stage, 0x00, encoded & 0xff, (encoded >> 8) & 0xff);
+}
+export function gladiusIISetActiveDpiStageRequest(stage) {
+    if (!Number.isInteger(stage) ||
+        stage < 0 ||
+        stage > 1) {
+        throw new Error("Gladius II DPI stage must be 0 or 1.");
+    }
+    return request(0x51, 0x31, 0x09, 0x00, stage + 1);
+}
+/* ---------------------------------
+ * POLLING
+ * --------------------------------- */
+export function gladiusIISetPollingRateRequest(pollingRateHz) {
+    const rateIndex = GLADIUS_II_POLLING_RATES.findIndex((rate) => rate === pollingRateHz);
+    if (rateIndex === -1) {
+        throw new Error(`Unsupported Gladius II polling rate: ${pollingRateHz} Hz.`);
+    }
+    return request(0x51, 0x31, 0x02, 0x00, rateIndex);
+}
+/* ---------------------------------
+ * ONBOARD PROFILE
+ * --------------------------------- */
+export function gladiusIISetProfileRequest(profile) {
+    if (!Number.isInteger(profile) ||
+        profile < 1 ||
+        profile >
+            GLADIUS_II_PROFILE_COUNT) {
+        throw new Error(`Gladius II profile must be 1-${GLADIUS_II_PROFILE_COUNT}.`);
+    }
+    return request(0x50, 0x02, profile - 1);
+}
+/* ---------------------------------
+ * ANGLE SNAPPING
+ * --------------------------------- */
+export function gladiusIISetAngleSnappingRequest(enabled) {
+    return request(0x51, 0x31, 0x04, 0x00, enabled ? 0x01 : 0x00);
+}
+/* ---------------------------------
+ * DEBOUNCE
+ * --------------------------------- */
+export function gladiusIISetDebounceRequest(milliseconds) {
+    if (!GLADIUS_II_DEBOUNCE_MS.some((value) => value === milliseconds)) {
+        throw new Error(`Gladius II debounce must be one of: ${GLADIUS_II_DEBOUNCE_MS.join(", ")} ms.`);
+    }
+    const raw = milliseconds / 4 - 1;
+    return request(0x51, 0x31, 0x03, 0x00, raw);
+}
+/* ---------------------------------
+ * LIFT-OFF DISTANCE
+ * --------------------------------- */
+export function gladiusIISetLiftOffRequest(value) {
+    const raw = value === "High"
+        ? 1
+        : 0;
+    return request(0x51, 0x35, 0xff, 0x00, 0xff, raw);
+}
+/* ---------------------------------
+ * RGB
+ * --------------------------------- */
+export function gladiusIISetLightingRequest(zone, mode, brightness, red, green, blue, direction = 0, randomColor = 0, speed = 0) {
+    if (!Number.isInteger(zone) ||
+        zone < 0 ||
+        zone > 2) {
+        throw new Error("Gladius II RGB zone must be 0, 1, or 2.");
+    }
+    if (brightness < 0 ||
+        brightness > 4) {
+        throw new Error("Gladius II RGB brightness must be 0-4.");
+    }
+    return request(0x51, 0x28, zone, 0x00, mode, brightness, red, green, blue, direction, randomColor, speed);
+}
+/* ---------------------------------
+ * SAVE
+ * --------------------------------- */
+export function gladiusIISaveRequest() {
+    return request(0x50, 0x03);
+}
+//# sourceMappingURL=index.js.map

package/dist/asus/index.js.map

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