@openmouse/protocol 0.1.0

package/dist/incott/index.d.ts

@@ -0,0 +1,1067 @@
+/**
+ * Incott HID protocol — transport-independent codec.
+ *
+ * Derived from IncottHIDApp (`romkazor/IncottHIDApp`, MIT licensed; this
+ * module reuses its protocol knowledge, not its code) and verified against
+ * an "incott 8K wireless mouse" (093A:522C) on real hardware. Ported from
+ * IncottHub (https://github.com/vladidraganov/IncottHub), which documents the
+ * verification in `docs/superpowers/specs/2026-09-07-incotthub-design.md`
+ * sections 4, 5, 8 and 13.
+ *
+ * DPI and battery were corrected on 2026-09-07 against a second, higher-trust
+ * source: the owner instrumented Incott's own WebHID configurator
+ * (incott.net/mouse/, hooking HIDDevice.prototype.sendFeatureReport /
+ * receiveFeatureReport) and captured real traffic to a G23V2Pro. That capture
+ * is ground truth and disproved two assumptions this driver inherited from
+ * IncottHIDApp — see `captures/incott-8k-wireless/vendor-tool-session.hex`
+ * and `docs/incott-testing.md`.
+ *
+ * A THIRD round of verification on 2026-09-08 used node-hid directly against
+ * an "incott 8K wireless mouse" and, uniquely among the capture sessions
+ * above, performed real WRITES and read every one back before restoring the
+ * original value. It fixed the DPI stage-index write bug (see
+ * `INCOTT_DPI_STAGE_COUNT`), confirmed `0x82` is the per-stage DPI value read
+ * and that it echoes its sub-command, confirmed the polling-rate byte at
+ * `0x81`, confirmed the packed byte-7 nibble reads for lift-off and motion
+ * sync agree with their symmetric `0x84` single-purpose reads, and added a
+ * button-binding codec. See
+ * `captures/incott-8k-wireless/write-roundtrip.hex` and
+ * `docs/incott-testing.md`.
+ *
+ * A FIFTH round, 2026-09-08, RELOCATED battery entirely. Charging a unit
+ * through a full cycle (roughly 60% to roughly 97%) while polling the
+ * `0x8e`/sub `0x01` feature-report reply showed byte 6 never move at all —
+ * the exact frame `09 8e 01 5a 04 84 38 01` the entire time. A constant is
+ * not a battery reading; see `INCOTT_CMD_QUERY_BATTERY` and
+ * `incottDecodeBattery` for what this disproves and why the codec is kept
+ * anyway (regression coverage), and `docs/incott-testing.md` for the write-up.
+ * The real level lives in an UNSOLICITED INPUT report the mouse emits on
+ * report id 0x09 while it is actively being used — not a feature-report
+ * reply to any request this driver sends. See `incottDecodeInputStatus` for
+ * the codec and `src/drivers/incott/hid.ts`'s `onInputReport` for how the
+ * WebHID client listens for it and caches the result.
+ *
+ * A FOURTH fix, same day, closed a second DPI bug found by an owner report:
+ * `IncottHidClient.setDpi` was reading the active stage and then writing the
+ * requested DPI *into* that stage, silently overwriting whatever value the
+ * stage held — repeated use progressively destroyed the mouse's factory
+ * table (one owner's stage 2 was found changed from 1600 to 800 this way).
+ * DPI is genuinely four independent operations, not one: select the active
+ * stage (`INCOTT_CMD_SET_DPI_STAGE`/`incottEncodeSetActiveDpiStage`, `09 03
+ * 06 <idx>`), edit a stage's value (`INCOTT_CMD_SET_DPI`/`incottEncodeSetDpi`,
+ * `09 02 <idx> <lo> <hi>`), read which stage is active
+ * (`INCOTT_CMD_QUERY_DPI_STAGE`, `09 83 06`), and read a stage's value
+ * (`INCOTT_CMD_QUERY_DPI_STAGE_VALUE`, `09 82 <idx>`). Select and edit were
+ * verified as genuinely distinct operations: selecting stages 0, 3, 5, then 1
+ * in turn each read back correctly via `0x83`/`0x06`, and reading all six
+ * stages via `0x82` before and after showed the table's contents completely
+ * unchanged by those selects. See `INCOTT_CMD_SET_DPI_STAGE` for the full
+ * writeup, `src/drivers/incott/hid.ts` for how the driver now exposes
+ * `setActiveDpiStage`/`setDpiStageValue` as OpenMouse's existing generic
+ * multi-stage DPI editor contract, and
+ * `captures/incott-8k-wireless/write-roundtrip.hex` /
+ * `docs/incott-testing.md` for the capture.
+ *
+ * All traffic is HID feature reports on report ID 0x09. Requests are 9 bytes
+ * `[0x09, cmd, sub, ...args]`; WebHID's `sendFeatureReport` takes the report
+ * ID as a separate argument, so the payloads this module builds are 8 bytes
+ * and omit it. Responses are read with `receiveFeatureReport(0x09)`, which
+ * returns the report ID at byte 0, so decoders index frames that include it.
+ *
+ * Opcodes are paired: `0x0N` sets a value, `0x8N` queries it. The device
+ * latches a single shared response buffer — see `incottFrameMatches` and
+ * `src/drivers/incott/hid.ts` for how the driver layer avoids decoding a
+ * frame left over from a previous query.
+ *
+ * A SIXTH round, 2026-09-10, instrumented Incott's own web configurator again,
+ * this time with every click LABELLED, settling the performance-mode
+ * value-to-label mapping left open by the 2026-09-07 capture: HP=2, Corded=1,
+ * LP=0 — the REVERSE of the vendor UI's own left-to-right display order. See
+ * `INCOTT_SUB_PERFORMANCE` for the labelled capture,
+ * `INCOTT_PERFORMANCE_MODE_TO_WIRE`/`incottPerformanceModeToWire` for the
+ * table it lives in, and `src/drivers/incott/hid.ts`'s `setPowerMode`/
+ * `getPowerModes` for where it is now wired into OpenMouse's shared
+ * `powerMode`/`powerModes` contract. The same session also verified the
+ * receiver LED labels (previously prior art, now confirmed — see
+ * `INCOTT_RECEIVER_LED_MODES`), found a DPI-write axis byte at payload index
+ * 7 (see `incottEncodeSetDpi`), and established that onboard profiles are a
+ * vendor-software construct with no on-device select command. See
+ * `docs/incott-testing.md` and
+ * `captures/incott-8k-wireless/vendor-tool-session-2026-09-10.hex`.
+ *
+ * This module must not import WebHID types or talk to a device; see
+ * `src/drivers/incott/hid.ts` for the WebHID client.
+ */
+export declare const INCOTT_VENDOR_ID = 2362;
+/** The 2.4 GHz dongle's product id — "incott 8K wireless mouse" in its product string. */
+export declare const INCOTT_PRODUCT_ID = 21036;
+/**
+ * The WIRED product id — hardware-verified 2026-09-08 by plugging the mouse
+ * in over USB and reading `device.productId` directly: it enumerates as
+ * `0x622C`, not `0x522C`. This used to be named `INCOTT_PRODUCT_ID_CHARGING`
+ * and `incottIsChargingProduct` treated it as a charging FLAG — that was the
+ * wrong axis. `0x622C` means the CONNECTION is wired; charging is a
+ * consequence of being plugged in, not the thing this id actually encodes.
+ * See `incottIsWiredProduct` (the renamed helper) and
+ * `IncottHidClient.readStatus`, which now derives both `connectionType` and
+ * `batteryState: "Charging"` from wired-ness rather than from a constant
+ * that claimed to mean "charging."
+ */
+export declare const INCOTT_PRODUCT_ID_WIRED = 25132;
+export declare const INCOTT_PRODUCT_IDS: readonly number[];
+/** The vendor collection that answers protocol requests. */
+export declare const INCOTT_USAGE_PAGE = 65285;
+/** Any vendor-defined page, used as a fallback when 0xFF05 is absent. */
+export declare const INCOTT_VENDOR_USAGE_PAGE_MIN = 65280;
+export declare const INCOTT_REPORT_ID = 9;
+/** Payload length excluding the report ID (WebHID sends it separately). */
+export declare const INCOTT_PAYLOAD_LENGTH = 8;
+/** Length requested from receiveFeatureReport, including the report ID. */
+export declare const INCOTT_RESPONSE_LENGTH = 64;
+/** Set opcodes. Query opcodes are the same value with bit 7 set. */
+export declare const INCOTT_CMD_SET_POLLING = 1;
+/**
+ * Writes the actual DPI value (see `incottEncodeSetDpi`), NOT a preset index.
+ * Proven on hardware 2026-09-07 against a real G23V2Pro; this used to be
+ * `0x03`, which was never verified and is not what the vendor tool sends.
+ */
+export declare const INCOTT_CMD_SET_DPI = 2;
+export declare const INCOTT_CMD_SET_SENSOR = 4;
+export declare const INCOTT_CMD_SET_TIMING = 5;
+/**
+ * Button binding write, `09 06 <button 0..5> <...payload>` — round-trip
+ * confirmed on hardware 2026-09-08: the vendor tool wrote
+ * `09 06 00 01 00 f0` to button 0, and reading it back via `0x86`/sub `00`
+ * afterwards returned the identical three payload bytes. See
+ * `incottEncodeSetButtonBinding` — this only encodes the raw binding; the
+ * meaning of its bytes (key code vs. macro vs. remap) is NOT established, so
+ * nothing here interprets them.
+ */
+export declare const INCOTT_CMD_SET_BUTTON = 6;
+/**
+ * Announces one 32-byte chunk of a macro buffer:
+ * `09 07 <chunks> <chunk index> <bytes per chunk> <buffer id>`.
+ *
+ * Each header is followed by the chunk itself as a 32-byte OUTPUT report on
+ * the same id — see `IncottHidClient.uploadMacro`.
+ */
+export declare const INCOTT_CMD_MACRO_CHUNK = 7;
+export declare const INCOTT_CMD_SET_RECEIVER_LED = 8;
+/**
+ * Selects which of the six DPI stages is ACTIVE: `09 03 06 <idx>` (command
+ * `0x03`, sub-command `INCOTT_SUB_DPI_STAGE`, then the stage index). Pairs
+ * with `INCOTT_CMD_QUERY_DPI_STAGE` (`0x83`), which reads the active index
+ * back at the same sub-command — see `incottEncodeSetActiveDpiStage`.
+ *
+ * This is a SELECT, not an EDIT: it never touches the six-stage table's
+ * stored values. Verified on hardware 2026-09-08 — selecting stage 0, 3, 5,
+ * then 1 in turn each read back identically via `0x83`/`0x06`, and reading
+ * all six stages via `0x82` before and after showed the table completely
+ * unchanged by those selects.
+ *
+ * IMPORTANT MISLABEL TO NOT REPEAT: IncottHIDApp calls this command "set
+ * DPI" and treats its six "DPI presets" as if picking one changes the DPI
+ * value. It does not — it only changes which already-stored stage answers
+ * as active. The bug this driver used to have (`setDpi` writing the
+ * requested value into whichever stage happened to be active, silently
+ * overwriting the factory table one stage at a time) came directly from
+ * conflating this select with `INCOTT_CMD_SET_DPI` (`0x02`), the command
+ * that actually edits a stage's stored value. See `incottEncodeSetDpi` and
+ * `docs/incott-testing.md`.
+ */
+export declare const INCOTT_CMD_SET_DPI_STAGE = 3;
+/**
+ * Returns the active DPI *stage index* (0-5), not a DPI value — see
+ * `incottDecodeDpiStageIndex`. Still `0x83`; only the interpretation of its
+ * payload changed.
+ */
+export declare const INCOTT_CMD_QUERY_DPI_STAGE = 131;
+/**
+ * Reads the numeric DPI value stored in one of the six stages,
+ * `09 82 <stage 0..5>` -> little-endian uint16 at RESPONSE bytes 3-4 (same
+ * `wire = dpi/50 - 1` encoding as the write). Verified on hardware
+ * 2026-09-08 by reading all six stages back as 400/800/1600/2400/3200/6400
+ * (wire 0x07/0x0f/0x1f/0x2f/0x3f/0x7f), then writing 25000 to stage 2 and
+ * reading it back as exactly 25000, then restoring 1600 and reading that
+ * back too — six independent points on `dpi = (wire + 1) * 50`, plus a
+ * write/restore round-trip. This was previously `INCOTT_CMD_UNKNOWN_82`: an
+ * earlier opcode sweep only ever tried sub `0x00` and got back an
+ * uninterpreted payload (`09 82 00 07 00 …`) — the same "sub-commands are
+ * not optional" lesson `0x8e` (battery) taught. See `incottDecodeDpiStage`.
+ */
+export declare const INCOTT_CMD_QUERY_DPI_STAGE_VALUE = 130;
+export declare const INCOTT_CMD_QUERY_POLLING = 129;
+export declare const INCOTT_CMD_QUERY_SENSOR = 132;
+export declare const INCOTT_CMD_QUERY_TIMING = 133;
+export declare const INCOTT_CMD_QUERY_RECEIVER_LED = 136;
+/**
+ * Answers, but byte 8 of the reply returned the same constant `0x5a` (90) on
+ * every capture ever taken, across every device state and both capture
+ * sessions (2026-09-07 read-only sweep and the later vendor-tool traffic).
+ * That is disproof, not confirmation, that byte 8 is a battery percentage —
+ * see `docs/incott-testing.md`. Nothing in this driver decodes this response
+ * any more. DISPROVEN A SECOND TIME on 2026-09-08: `0x8e`/sub `0x01` byte 6
+ * (see below), the value this comment used to point to as "the real battery
+ * percentage," is ALSO a constant — see `INCOTT_CMD_QUERY_BATTERY`. The real
+ * battery level lives in an unsolicited input report; see
+ * `incottDecodeInputStatus`. Kept only because the opcode itself still
+ * answers and its real meaning is an open question worth recording.
+ */
+export declare const INCOTT_CMD_QUERY_STATUS = 137;
+export declare const INCOTT_CMD_QUERY_IDENTITY = 143;
+/**
+ * Battery percentage, but ONLY on sub-command `0x01` — the original opcode
+ * sweep swept every command with sub `0x00` and concluded `0x8e` was
+ * unimplemented because it never answered. Sub-commands are not optional on
+ * this opcode (or on `0x86`, which the vendor tool queries as `09 86 09`).
+ *
+ * DISPROVEN 2026-09-08, the same way `0x89` byte 8 was disproven before it
+ * (see `INCOTT_CMD_QUERY_STATUS`): charging a unit through a full cycle from
+ * roughly 60% to roughly 97% while polling this response showed byte 6 NEVER
+ * CHANGE — the identical frame `09 8e 01 5a 04 84 38 01` the entire time,
+ * `0x38` = 56 throughout. A value that does not move while the real battery
+ * level visibly does cannot be a battery reading; it is a constant of unknown
+ * meaning, exactly like `0x89` byte 8 before it. `incottDecodeBattery` is
+ * kept only as a codec (its mechanical byte-6 decode is unchanged and still
+ * tested) and for the driver-level regression test that battery is no longer
+ * sourced from here — see `IncottHidClient.readStatus` and
+ * `docs/incott-testing.md`. The real battery percentage is a field of the
+ * unsolicited input report the mouse emits while in use — see
+ * `incottDecodeInputStatus`.
+ */
+export declare const INCOTT_CMD_QUERY_BATTERY = 142;
+export declare const INCOTT_SUB_BATTERY = 1;
+/**
+ * The report id the mouse's UNSOLICITED input reports arrive on — the same
+ * value as `INCOTT_REPORT_ID` (`0x09`), which this module otherwise uses only
+ * for feature-report request/response pairs. These input reports are NOT a
+ * reply to anything this driver sends: the device emits them on its own,
+ * only while it is actively being used (moved or clicked), carrying battery
+ * and a packed DPI-stage/polling-rate snapshot. See `incottDecodeInputStatus`
+ * and `src/drivers/incott/hid.ts`'s `onInputReport`.
+ */
+export declare const INCOTT_INPUT_REPORT_ID = 9;
+/**
+ * Button binding read, `09 86 <button 0..5>` -> response bytes 3-5 = the raw
+ * three-byte binding written by `INCOTT_CMD_SET_BUTTON` at the same index.
+ * Round-trip confirmed on hardware 2026-09-08 (see `INCOTT_CMD_SET_BUTTON`).
+ * The device has six buttons; reading indices 0-5 on the unit under test
+ * returned:
+ *   0 -> 01 00 f0    3 -> 01 00 f3
+ *   1 -> 01 00 f1    4 -> 01 00 f4
+ *   2 -> 01 00 f2    5 -> 07 00 03
+ * (left, right, middle, forward, back, DPI — physically, in some order).
+ * This was previously `INCOTT_CMD_UNKNOWN_86`. Sub-command `0x09` on the
+ * same command reads the onboard profile index instead — see
+ * `INCOTT_SUB_PROFILE_INDEX`. The binding itself is a 32-bit little-endian
+ * action word; see `incottDecodeButtonBinding`.
+ */
+export declare const INCOTT_CMD_QUERY_BUTTON = 134;
+/** Button count: left, right, middle, forward, back, DPI. */
+export declare const INCOTT_BUTTON_COUNT = 6;
+/**
+ * Reads the onboard profile INDEX, `09 86 09` — not a button index, since
+ * buttons only go up to 5. Counterpart of the `09 06 09 <index>` write.
+ *
+ * Neither is implemented, and that is a finding rather than an omission: the
+ * index is real and sticks (0-3), but it gates nothing. Writing a setting
+ * while on one slot changes what every other slot reports, so there is a
+ * single settings store and the vendor replays every setting on a switch
+ * because the mouse holds none of them. Publishing OpenMouse's
+ * `profileCount`/`setProfile` contract — which describes ONBOARD profiles —
+ * would hand the user a selector that appears to work and does not. See
+ * `captures/incott-8k-wireless/profile-index-2026-09-11.hex`.
+ */
+export declare const INCOTT_SUB_PROFILE_INDEX = 9;
+/**
+ * Physical buttons, in left-to-right display order.
+ */
+export declare const INCOTT_BUTTON_NAMES: readonly ["Left", "Right", "Middle", "Forward", "Back", "DPI"];
+export type IncottButtonName = (typeof INCOTT_BUTTON_NAMES)[number];
+/**
+ * Display order -> WIRE index. **These are not the same**, and assuming they
+ * were would silently swap two buttons.
+ *
+ * The vendor's per-model key table carries an explicit `matrix` field and
+ * addresses the device with it (`setMsK(dvar.key[i].matrix, code)`), not with
+ * the array position. For this family Forward sits at array index 3 with
+ * `matrix = 4`, and Back at array index 4 with `matrix = 3` — the two are
+ * transposed. Every other button's matrix equals its position.
+ */
+export declare const INCOTT_BUTTON_WIRE_INDEX: Readonly<Record<IncottButtonName, number>>;
+/**
+ * A keyboard action word, from the vendor's `kf_hw()` keyboard branch:
+ *
+ *     no modifier:   (keycode & 255) << 8  | 128
+ *     with modifier: (keycode & 255) << 16 | (modifiers & 255) << 8
+ *
+ * The two forms are genuinely different shapes, not one with a zero
+ * modifier — an unmodified key sets the `0x80` marker in the low byte and
+ * puts the keycode one byte lower than a chord does.
+ */
+export declare function incottKeyboardActionCode(keycode: number, modifiers?: number): number;
+/**
+ * Everything a button can be set to, in display order: the mouse, DPI and
+ * media actions above, then individual keys, then common chords.
+ *
+ * Keyboard bindings are enumerated rather than left out. The encoding is
+ * parametric (any of 256 keycodes against any of 256 modifier masks) and the
+ * shared `buttonOptions` contract is a flat list of labels, so the full space
+ * cannot be offered — but a curated list covers what people actually bind,
+ * and it is the same approach the MCHOSE driver in this repo already takes.
+ */
+export declare const INCOTT_BUTTON_ACTIONS: ReadonlyArray<readonly [string, number]>;
+/** Macro loop modes, in wire order. */
+export declare const INCOTT_MACRO_LOOP_MODES: readonly ["untilKeyRelease", "untilAnyKey", "cycle"];
+export type IncottMacroLoop = (typeof INCOTT_MACRO_LOOP_MODES)[number];
+/** One key event in a macro: a press or a release, then a delay. */
+export interface IncottMacroStep {
+    /** HID keyboard usage code. */
+    key: number;
+    /** True for a key-down event, false for key-up. */
+    press: boolean;
+    /** Delay after this event, milliseconds, 16-bit. */
+    delayMs: number;
+}
+export interface IncottMacro {
+    /** Which of the ten on-device macro buffers this occupies, 0-9. */
+    bufferId: number;
+    loop: IncottMacroLoop;
+    /** Repeat count, used by the `cycle` loop mode. */
+    cycles: number;
+    steps: readonly IncottMacroStep[];
+    /** The vendor's own identifier for the macro; echoed back in the buffer. */
+    uid: number;
+}
+/** A macro buffer is always this long, in ten 32-byte chunks. */
+export declare const INCOTT_MACRO_BUFFER_BYTES = 320;
+export declare const INCOTT_MACRO_CHUNK_BYTES = 32;
+export declare const INCOTT_MACRO_CHUNK_COUNT: number;
+export declare const INCOTT_MACRO_BUFFER_COUNT = 10;
+/** Steps occupy bytes 4..287 at four bytes each, so 71 fit. */
+export declare const INCOTT_MACRO_MAX_STEPS = 71;
+/**
+ * Builds the 320-byte macro buffer, transcribed from the vendor bundle's
+ * `juji_to_hw()`.
+ *
+ *     [0]        buffer id
+ *     [1]        loop mode (0 until key release, 1 until any key, 2 cycle)
+ *     [2..3]     cycle count, LE16
+ *     [4+4n]     event flags: bit 0 always set, bit 7 set for a RELEASE
+ *     [5+4n]     HID keyboard usage code
+ *     [6..7+4n]  delay after the event, LE16 milliseconds
+ *     [288..293] the ASCII name "Macro" followed by '1' + buffer id
+ *     [304..307] (steps + 1) * 4 + 128, LE32
+ *     [308..311] 16, 0, 232, 232 — constant in every buffer the vendor builds
+ *     [312..315] uid, LE32
+ *     [316..317] steps * 2, LE16
+ *     [318]      step count
+ *
+ * The buffer goes out as ten 32-byte chunks, each announced by
+ * `incottEncodeMacroChunkHeader` and then carried by a 32-byte OUTPUT report
+ * on the same report id — the only place this protocol uses an output report
+ * at all. That transport is not recoverable from the vendor bundle (the call
+ * carrying each chunk is defined in none of the files its page loads, and the
+ * HID method names resolve through variables at runtime), so it was captured
+ * from the running tool instead: see
+ * `captures/incott-8k-wireless/macro-upload-2026-09-11.hex`, and
+ * `IncottHidClient.uploadMacro` for the sender.
+ *
+ * Pinned byte-for-byte to that capture. There is no macro READ command, so
+ * nothing here can be verified against the device after the fact.
+ */
+export declare function incottEncodeMacroBuffer(macro: IncottMacro): Uint8Array;
+/**
+ * The 8-byte header announcing one chunk of a macro buffer:
+ * `09 07 0a <chunk index> 20 <buffer id>`.
+ *
+ * See `incottEncodeMacroBuffer` for why nothing sends this yet. Note the
+ * vendor slices its own payload as `mda.slice(i * 32, i * 64)`, which yields
+ * an EMPTY chunk for `i = 0` and over-long ones after — visibly a bug in its
+ * own uploader, and not reproduced here.
+ */
+export declare function incottEncodeMacroChunkHeader(chunkIndex: number, bufferId: number): Uint8Array;
+/** Splits a macro buffer into the ten chunks the upload sends. */
+export declare function incottMacroChunks(buffer: Uint8Array): Uint8Array[];
+/**
+ * Label for a 32-bit action word, or null when it is not one this driver
+ * knows.
+ *
+ * Macro bindings are named rather than listed: the vendor encodes them as
+ * `slot << 16 | 9` (confirmed 2026-09-11, where binding a button to macro
+ * slot 3 wrote `0x00030009`), so a label can be derived for any slot without
+ * putting ten entries in the picker. `incottButtonActionCode` deliberately
+ * does NOT reverse these — nothing can assign a macro until there is a UI to
+ * author one — so a macro binding reads back correctly and is left alone.
+ */
+export declare function incottButtonActionLabel(code: number): string | null;
+/** Low half of a macro button binding: `slot << 16 | 9`. */
+export declare const INCOTT_BUTTON_MACRO_MARKER = 9;
+/** 32-bit action word for a label, or null when the label is not in the table. */
+export declare function incottButtonActionCode(label: string): number | null;
+/**
+ * How many DPI stages the cycle uses by default — and the value this driver
+ * spent two sessions mistaking for a sub-command.
+ *
+ * `0x83`'s reply byte 2 is the stage COUNT, not an echo. Proven by the
+ * captures: the vendor sends `09 83 00` and gets `09 83 06 01` back, and a
+ * bare `09 83` sweep with no sub-command gets the same `06` — a byte the
+ * request never contained cannot be an echo. Byte 3 is the active index,
+ * which varies (`00`/`01`/`03`/`05`) while byte 2 stays `06`.
+ *
+ * This matters twice over:
+ *   - `0x83` must NOT be treated as sub-echoing when matching responses. It
+ *     belongs with `0x81`/`0x88`/`0x89`/`0x8f`, where byte 2 is data.
+ *   - the `0x03` write carries the count alongside the index
+ *     (`09 03 <count> <stage>`), so writing a hardcoded `06` while selecting
+ *     a stage would reset a four-stage cycle back to six — the same shape of
+ *     bug as the old `INCOTT_SUB_SET_DPI` constant below.
+ */
+export declare const INCOTT_DPI_STAGE_COUNT_DEFAULT = 6;
+/**
+ * Number of DPI stages the table holds. Both the `0x02` write and the `0x82`
+ * read take a stage index in this range as their second payload byte — see
+ * `incottEncodeSetDpi` and `incottDecodeDpiStage`.
+ *
+ * THIS WAS WRONG until 2026-09-08: the driver used to hardcode that byte as a
+ * constant `INCOTT_SUB_SET_DPI = 0x01`, which could only ever write stage 1
+ * of the table. Reading stages 0-5 on real hardware returned six independent
+ * points on the DPI line (wire 0x07/0x0f/0x1f/0x2f/0x3f/0x7f ->
+ * 400/800/1600/2400/3200/6400), proving the byte is a stage index, not a
+ * fixed sub-command.
+ */
+export declare const INCOTT_DPI_STAGE_COUNT = 6;
+export declare const INCOTT_SUB_LOD = 1;
+export declare const INCOTT_SUB_RIPPLE = 2;
+export declare const INCOTT_SUB_ANGLE_SNAP = 3;
+export declare const INCOTT_SUB_MOTION_SYNC = 4;
+/**
+ * Sub-command for the "Performance mode" sensor setting (labelled HP / Corded
+ * / LP in the vendor tool, described as trading performance for battery
+ * life). The value-to-label mapping is now CONFIRMED: captured 2026-09-10 by
+ * instrumenting Incott's own WebHID configurator with each click labelled
+ * (unlike the 2026-09-07 capture, which only recorded the raw writes):
+ *
+ *   clicked "HP"      -> TX 09 04 05 02
+ *   clicked "Corded"  -> TX 09 04 05 01
+ *   clicked "LP"      -> TX 09 04 05 00
+ *
+ * i.e. HP=2, Corded=1, LP=0. **This is the REVERSE of the vendor UI's
+ * left-to-right display order (HP | Corded | LP)** — exactly why this was
+ * captured with each click labelled rather than assumed from the on-screen
+ * order. See `INCOTT_PERFORMANCE_MODE_TO_WIRE`/`INCOTT_PERFORMANCE_MODE_FROM_WIRE`
+ * for the single named table this reversal lives in, and
+ * `incottEncodeSetPerformanceMode`.
+ */
+export declare const INCOTT_SUB_PERFORMANCE = 5;
+export declare const INCOTT_SUB_DEBOUNCE = 1;
+/**
+ * Fire Key (rapid-fire) parameters, `09 05 02 <times> <interval ms>`.
+ *
+ * The last unidentified command in this protocol, settled 2026-09-11. The
+ * vendor calls it `setFKeyPm(lp, ir)` and only ever calls it for a button
+ * bound to `favFIRE`, deriving both values from that button's `itemdata` and
+ * clamping them to 3 and 255 respectively. Its own UI names the two fields:
+ * "Fire Key" / "Keep left-clicking according to the interval and times".
+ *
+ * Read back at `0x85`/`0x02`. On this hardware: `09 85 02 03 0a` — three
+ * clicks, 10 ms apart.
+ */
+export declare const INCOTT_SUB_FIRE_KEY = 2;
+/**
+ * Clicks per press, 1-3 — the ceiling the vendor clamps to.
+ *
+ * `INCOTT_FIRE_KEY_TIMES_HOLD` (0) is a real fourth setting, not an absence
+ * of one: it switches the button from a fixed burst to firing continuously
+ * while held. Confirmed against the vendor software 2026-09-11 by the device
+ * owner, which is the only way it could have been established — the value is
+ * in range for the write either way, so a round-trip proves nothing about
+ * what it MEANS.
+ */
+export declare const INCOTT_FIRE_KEY_MAX_TIMES = 3;
+/**
+ * Fire key "times" value that means hold-to-fire: the button keeps clicking
+ * at the configured interval for as long as it is held, and stops on
+ * release. See `INCOTT_FIRE_KEY_MAX_TIMES`.
+ */
+export declare const INCOTT_FIRE_KEY_TIMES_HOLD = 0;
+/** Milliseconds between clicks in a burst, one byte. */
+export declare const INCOTT_FIRE_KEY_MAX_INTERVAL_MS = 255;
+export declare const INCOTT_SUB_SLEEP = 3;
+export declare const INCOTT_SUB_NONE = 0;
+/**
+ * DPI lives in a six-stage table, each stage a linear value — not an index
+ * into a preset table. The wire value is little-endian at payload bytes 2-3
+ * (write) / response bytes 3-4 (read):
+ *   wire = dpi / 50 - 1        dpi = (wire + 1) * 50
+ *
+ * Verified on hardware 2026-09-08 by reading all six stages back as
+ * 400/800/1600/2400/3200/6400 (wire 0x07/0x0f/0x1f/0x2f/0x3f/0x7f) — six
+ * independent points on this line — then writing 25000 to stage 2 (wire 499)
+ * and reading back exactly 25000, then restoring 1600 and reading that back
+ * too. (An earlier, narrower proof from 2026-09-07 against a G23V2Pro only
+ * ever exercised stage 1: `TX 09 02 01 0f 00` -> 800 DPI, `TX 09 02 01 f3 01`
+ * -> 25000 DPI.) See `incottEncodeSetDpi` and `incottDecodeDpiStage`.
+ *
+ * The vendor's own device definition (js/gvarG23-v102.js) pairs two PixArt
+ * sensor variants with different ceilings, both counting up from 50 in steps
+ * of 50:
+ *   sensor 0x3395 (PAW3395): 32000
+ *   sensor 0x3950 (PAW3950): 45000
+ * The fitted sensor IS readable — the identity reply carries it (see
+ * `incottDecodeIdentity`) — so `readStatus` narrows the ceiling it OFFERS to
+ * whichever sensor answered, via `incottDpiMaxForSensor`. This constant stays
+ * the higher of the two: it is the bound on what the protocol can express,
+ * and the encoder must keep accepting a value the app is entitled to send.
+ * That mirrors the polling rate, where `supportedPollingRates` narrows by
+ * connection while `incottEncodeSetPollingRate` still accepts the full
+ * ladder.
+ */
+export declare const INCOTT_DPI_MIN = 50;
+export declare const INCOTT_DPI_MAX = 45000;
+/** The PAW3395's ceiling in the vendor's own DPI table. */
+export declare const INCOTT_DPI_MAX_PAW3395 = 32000;
+/**
+ * The DPI ceiling to OFFER for a fitted sensor, matching the table the vendor
+ * builds in `getStDPI`.
+ *
+ * Worth being precise about what this is and is not. It is the vendor's UI
+ * limit, not a proven firmware limit: this contributor's PAW3950 accepted
+ * 45000 over the cable even though the connection-indexed sensor byte read
+ * PAW3395 there (see `captures/incott-8k-wireless/wired-dpi-ceiling-2026-09-11.hex`),
+ * so a real PAW3395 unit has never been tested and may well accept more. It
+ * is used because offering exactly what the vendor offers cannot surprise
+ * anyone, and because the alternative — advertising 45000 to a Ghero — risks
+ * a silent refusal on a model nobody here can test.
+ */
+export declare function incottDpiMaxForSensor(sensorId: number | null): number;
+export declare const INCOTT_DPI_STEP = 50;
+/**
+ * NOT the writable DPI range (see `INCOTT_DPI_MIN`/`INCOTT_DPI_MAX` above for
+ * that) — the vendor's device definition calls this list the six DEFAULT
+ * STAGE PRESETS. `0x83`/`0x06` reports which of these six stages is active as
+ * an index 0-5 (see `incottDecodeDpiStageIndex`), not a DPI value. Kept as a
+ * convenience list of round numbers; do not use it to validate or decode a
+ * DPI write.
+ */
+export declare const INCOTT_DPI_DEFAULT_STAGE_PRESETS: readonly number[];
+/**
+ * The full polling-rate ladder, available only over the 2.4 GHz wireless
+ * connection (`INCOTT_PRODUCT_ID`, `0x522C`). See
+ * `INCOTT_POLLING_STEPS_HZ_WIRED` for the lower ceiling the owner confirmed
+ * on hardware when the mouse is plugged in.
+ */
+export declare const INCOTT_POLLING_STEPS_HZ: readonly number[];
+/**
+ * Wired ceiling — HARDWARE-VERIFIED: the owner confirmed the mouse only
+ * reaches 1000 Hz over the USB cable (`INCOTT_PRODUCT_ID_WIRED`, `0x622C`);
+ * 2000/4000/8000 Hz are wireless-only. Offering one of those over the cable
+ * would produce a write the device silently refuses, which
+ * `IncottHidClient.setPollingRate`'s read-back verification would then
+ * report as a failure on every attempt — so `readStatus()` publishes this
+ * narrower list instead of the full one whenever `incottIsWiredProduct` is
+ * true. See `docs/incott-testing.md`.
+ */
+export declare const INCOTT_POLLING_STEPS_HZ_WIRED: readonly number[];
+export declare const INCOTT_POLLING_WIRE_TO_HZ: Readonly<Record<number, number>>;
+export declare const INCOTT_POLLING_HZ_TO_WIRE: Readonly<Record<number, number>>;
+/**
+ * Lift-off distance is carried in tenths of a millimetre.
+ *
+ * VERIFIED ON HARDWARE 2026-09-08. Setting 0.7 mm in Incott's own web
+ * configurator and then reading `0x84`/sub `0x01` returned byte 3 = `2`,
+ * so hardware 2 = 0.7 mm. That confirms IncottHIDApp's mapping, which is
+ * what `INCOTT_LOD_WIRE_TO_TENTHS` below encodes.
+ *
+ * It also disproves a reading of the vendor's own device definition
+ * (js/gvarG23-v102.js), which pairs `lodUI = [0.7, 1, 2]` with
+ * `lodHW = [0, 1, 2]`. Those two arrays are NOT index-aligned — taking
+ * them as a pair implies hardware 0 = 0.7 mm, which the device
+ * contradicts. Do not 'fix' this mapping from that file.
+ *
+ * Remaining nuance: only the 0.7 mm point was read directly. Hardware 0
+ * and 1 are 1 mm and 2 mm in that order per IncottHIDApp; since the
+ * mapping is a bijection over {0,1,2} and its 0.7 mm claim proved correct,
+ * the other two follow, but neither has been read back individually.
+ */
+export declare const INCOTT_LOD_STEPS_TENTHS: readonly number[];
+export declare const INCOTT_LOD_WIRE_TO_TENTHS: Readonly<Record<number, number>>;
+export declare const INCOTT_LOD_TENTHS_TO_WIRE: Readonly<Record<number, number>>;
+export declare const INCOTT_DEBOUNCE_MIN_MS = 0;
+export declare const INCOTT_DEBOUNCE_MAX_MS = 30;
+export declare const INCOTT_SLEEP_MIN_S = 1;
+export declare const INCOTT_SLEEP_MAX_S = 900;
+/** All three raw wire values (LP/Corded/HP) are now hardware-confirmed — see `INCOTT_SUB_PERFORMANCE`. */
+export declare const INCOTT_PERFORMANCE_MODE_MIN = 0;
+export declare const INCOTT_PERFORMANCE_MODE_MAX = 2;
+/**
+ * The single named table the HP/Corded/LP value-to-label reversal lives in —
+ * see `INCOTT_SUB_PERFORMANCE` for the capture that confirmed it. Keys are the
+ * vendor tool's own display labels; `INCOTT_PERFORMANCE_MODE_NAMES` lists them
+ * in the vendor UI's own left-to-right order (HP, Corded, LP) for advertising
+ * to the app, while this table (and its inverse,
+ * `INCOTT_PERFORMANCE_MODE_FROM_WIRE`) hold the REVERSED wire values.
+ * `incottPerformanceModeToWire`/`incottPerformanceModeFromWire` are the
+ * intended entry points; the raw tables are exported for tests.
+ */
+export declare const INCOTT_PERFORMANCE_MODE_NAMES: readonly string[];
+/** name -> raw wire value. See `INCOTT_PERFORMANCE_MODE_NAMES`'s doc comment for the reversal warning. */
+export declare const INCOTT_PERFORMANCE_MODE_TO_WIRE: Readonly<Record<string, number>>;
+/** raw wire value -> name. The inverse of `INCOTT_PERFORMANCE_MODE_TO_WIRE`. */
+export declare const INCOTT_PERFORMANCE_MODE_FROM_WIRE: Readonly<Record<number, string>>;
+/** Validated name -> wire lookup for `incottEncodeSetPerformanceMode`/`IncottHidClient.setPowerMode`. Returns `null` for an unknown name rather than throwing, so callers can reject before writing anything. */
+export declare function incottPerformanceModeToWire(name: string): number | null;
+/** Wire -> validated name lookup, the inverse of `incottPerformanceModeToWire`. Returns `null` for a value outside 0-2. */
+export declare function incottPerformanceModeFromWire(wire: number): string | null;
+/**
+ * A curated subset of the verified 1-900s sleep-timer range to offer in the
+ * app's dropdown, in the same style as GEARHUB_SLEEP_OPTIONS and
+ * MCHOSE_SLEEP_OPTIONS: the firmware accepts any integer second count in
+ * range (see `incottEncodeSetSleep`), this is just a sane list of presets.
+ * 900s (15 minutes) is the documented maximum.
+ */
+export declare const INCOTT_SLEEP_OPTIONS: readonly number[];
+export declare const INCOTT_RECEIVER_LED_MODES: readonly string[];
+export type IncottToggleKind = "motionSync" | "angleSnapping" | "rippleControl";
+export declare const INCOTT_TOGGLE_SUB: Readonly<Record<IncottToggleKind, number>>;
+/**
+ * Throws `RangeError` unless `dpi` is a value the six-stage table can hold.
+ * Split out from `incottEncodeSetDpi` so `IncottHidClient.setDpi` can reject
+ * an invalid value before touching the device — determining which stage is
+ * active requires a query, and an obviously-invalid DPI should never cost a
+ * round-trip.
+ */
+export declare function incottValidateDpi(dpi: number): void;
+/**
+ * EDITS the DPI value stored in one stage — distinct from
+ * `incottEncodeSetActiveDpiStage`, which only SELECTS which stage is active
+ * and never touches a stored value. `stage` is a table index 0-5, NOT a
+ * sub-command — see `INCOTT_DPI_STAGE_COUNT` for the hardware proof that this
+ * byte varies (the driver used to hardcode it as a constant `0x01`, which
+ * could only ever reach stage 1). The value itself is a plain little-endian
+ * uint16 "wire" value — see the comment on `INCOTT_DPI_MIN` for the
+ * conversion and the captured proof.
+ *
+ * PAYLOAD INDEX 7 IS AN AXIS BYTE, discovered 2026-09-10: the full write is
+ * `02 <stage> <lo> <hi> 00 00 00 <axis>`, where `axis` 0 = both axes, 1 = X
+ * only, 2 = Y only. This encoder always emits trailing zeros (see `payload`),
+ * and the `axis` argument selects it. Independent X/Y IS implemented and
+ * hardware-verified — the matching per-axis read is `incottEncodeQueryDpiAxis`,
+ * which an earlier probe concluded did not exist because X and Y happened to
+ * be equal at the time.
+ */
+/**
+ * Which axis a DPI write targets, and which one a read asks for.
+ *
+ * On the WRITE the value rides at payload byte 7; on the READ it is request
+ * byte 2 and the reply echoes it back at byte 8. Hardware-verified
+ * 2026-09-11: writing X=800/Y=1600, X=2400/Y=400 and X=1000/Y=1000 to one
+ * stage read back exactly, each axis independently.
+ *
+ * `both` is what a plain `incottEncodeSetDpi` sends, and what reading with no
+ * axis byte returns.
+ */
+export declare const INCOTT_DPI_AXIS: {
+    readonly both: 0;
+    readonly x: 1;
+    readonly y: 2;
+};
+export type IncottDpiAxis = keyof typeof INCOTT_DPI_AXIS;
+export declare function incottEncodeSetDpi(stage: number, dpi: number, axis?: IncottDpiAxis): Uint8Array;
+/**
+ * `09 82 <stage> <axis>` — reads one axis of one stage.
+ *
+ * WHY THIS EXISTS, given a plain `09 82 <stage>` already reads a value: this
+ * driver previously recorded that no per-axis read existed, on the strength
+ * of a probe where all three axis values came back identical. They were
+ * identical because X and Y were BOTH at the factory 1600 at the time — the
+ * probe could not tell "no per-axis read" from "per-axis read whose axes
+ * happen to match". Confirmed 2026-09-11 by setting them apart first.
+ */
+export declare function incottEncodeQueryDpiAxis(stage: number, axis: IncottDpiAxis): Uint8Array;
+/**
+ * Writes the DPI cycle: `09 03 <count> <stage>` — how many stages the cycle
+ * uses, and which one is active. Does NOT write a DPI value and does NOT
+ * alter any stage's stored value; see `INCOTT_CMD_SET_DPI_STAGE` for the
+ * hardware proof (select 0/3/5/1, table unchanged) and for why this is a
+ * distinct operation from `incottEncodeSetDpi`, which edits a stage's stored
+ * value.
+ *
+ * `count` IS REQUIRED, and callers must pass what the device currently
+ * reports rather than a constant — the byte used to be hardcoded `0x06` in
+ * the belief that it was a sub-command, which would silently reset a
+ * four-stage cycle to six every time a stage was selected. See
+ * `INCOTT_DPI_STAGE_COUNT_DEFAULT`.
+ */
+export declare function incottEncodeSetDpiCycle(count: number, stage: number): Uint8Array;
+export declare function incottEncodeSetPollingRate(hz: number): Uint8Array;
+export declare function incottEncodeSetLiftOff(tenthsMm: number): Uint8Array;
+export declare function incottEncodeSetToggle(kind: IncottToggleKind, on: boolean): Uint8Array;
+/**
+ * Encodes a button binding write, `09 06 <button 0..5> <32-bit action, LE>`.
+ *
+ * The action is a 32-bit little-endian word — see `INCOTT_BUTTON_ACTIONS`
+ * for the labelled codes. Confirmed against hardware: this unit's factory
+ * binding for the DPI button reads back `07 00 03`, and the vendor's own
+ * encoder returns `0x00030007` for that function, which is the same word.
+ *
+ * `button` is the WIRE index, which is not the physical left-to-right order
+ * — see `INCOTT_BUTTON_WIRE_INDEX`.
+ */
+export declare function incottEncodeSetButtonBinding(button: number, code: number): Uint8Array;
+/**
+ * Encodes the raw 0-2 performance-mode value. The value-to-label mapping
+ * (HP=2 / Corded=1 / LP=0) is now CONFIRMED — see `INCOTT_SUB_PERFORMANCE`
+ * for the labelled capture and its REVERSED-vs-UI warning. Most callers
+ * should go through `incottPerformanceModeToWire`/`IncottHidClient.setPowerMode`
+ * with a name instead of a raw value; this function is the low-level codec
+ * both build on.
+ */
+export declare function incottEncodeSetPerformanceMode(mode: number): Uint8Array;
+export declare function incottEncodeSetDebounce(ms: number): Uint8Array;
+export declare function incottEncodeSetSleep(seconds: number): Uint8Array;
+export declare function incottEncodeSetReceiverLed(mode: number): Uint8Array;
+export declare function incottEncodeQuery(cmd: number, sub?: number): Uint8Array;
+/**
+ * The models that share `093A:522C`/`093A:622C`. All six enumerate under the
+ * same two product ids, so the USB descriptor cannot tell them apart — the
+ * model is carried in the identity reply instead (`incottDecodeIdentity`).
+ *
+ * "Zero 29"/"Zero 39" are the English series names the vendor's own
+ * `text_en` bundle uses (`msg94`/`msg95`); its code calls the same two models
+ * `G29` and `FM23` internally and renders them as 零29/零39.
+ */
+export type IncottModel = "Ghero" | "G23" | "G24" | "G23V2" | "Zero 29" | "Zero 39";
+/** PixArt PAW3395 — capped at 32000 DPI in the vendor's own DPI table. */
+export declare const INCOTT_SENSOR_PAW3395 = 13205;
+/** PixArt PAW3950 — capped at 45000 DPI, and what the "Pro" suffix means. */
+export declare const INCOTT_SENSOR_PAW3950 = 14672;
+export interface IncottDeviceIdentity {
+    /** Space-separated hex of the identity payload, for the details panel. */
+    raw: string;
+    /** Decoded model, or null when byte 3 carries a code this table does not know. */
+    model: IncottModel | null;
+    /** Raw byte 3, kept even when unrecognised so an unknown model can still be reported. */
+    modelCode: number | null;
+    /** Model plus a " Pro" suffix when the PAW3950 is fitted, e.g. "G23V2 Pro". */
+    displayName: string | null;
+    /** The FITTED sensor: `INCOTT_SENSOR_PAW3395` or `INCOTT_SENSOR_PAW3950`. */
+    sensorId: number | null;
+    /** True when the PAW3950 is fitted — what the vendor's "Pro" suffix means. */
+    isPro: boolean;
+    /** True when byte 4 reports the 8 KHz receiver. */
+    is8KReceiver: boolean;
+}
+/**
+ * A response frame is trustworthy only when the report ID, the command echo
+ * and (when one was sent) the sub-command echo all agree with the request.
+ * The device latches a single shared response buffer, so a frame left over
+ * from an earlier query will otherwise be decoded as a real value.
+ */
+export declare function incottFrameMatches(frame: Uint8Array, cmd: number, sub: number | null, axis?: number | null): boolean;
+/** The DPI cycle as the device reports it: how many stages, and which is live. */
+export interface IncottDpiCycle {
+    /** Stages in the cycle, 1..`INCOTT_DPI_STAGE_COUNT`. */
+    count: number;
+    /** Active stage, 0-based and always below `count`. */
+    active: number;
+}
+/**
+ * `09 83` -> `<count> <active>` at response bytes 2 and 3.
+ *
+ * Byte 3 was proven not to be a DPI-value index on hardware 2026-09-07:
+ * decoding it through `INCOTT_DPI_DEFAULT_STAGE_PRESETS` used to yield 800
+ * DPI, matching the vendor UI only by coincidence (the device happened to be
+ * on stage 1 of 6). Combine with `incottDecodeDpiStage` at `active` to get
+ * the actual DPI value — see `IncottHidClient.readStatus`.
+ *
+ * Byte 2 was then mistaken for a sub-command echo, because the count on the
+ * only device available is 6 and the driver happened to send `06`. It is
+ * data: `09 83 00` and a bare `09 83` both answer `06`. Matching it as an
+ * echo would reject every reply from a mouse whose cycle is not six stages
+ * long, so this decoder matches on the COMMAND ONLY — see
+ * `INCOTT_DPI_STAGE_COUNT_DEFAULT`.
+ */
+export declare function incottDecodeDpiCycle(frame: Uint8Array): IncottDpiCycle | null;
+/**
+ * `09 82 <stage>` -> the DPI value stored in that stage, little-endian at
+ * response bytes 3-4. This opcode used to be `INCOTT_CMD_UNKNOWN_82` — see
+ * the comment on `INCOTT_CMD_QUERY_DPI_STAGE_VALUE` for the hardware proof
+ * (six independent stage reads plus a write/read-back/restore round-trip on
+ * stage 2). `0x82` echoes its sub-command like `0x83`/`0x84`/`0x85`/`0x8e`
+ * (verified: `09 82 03` replies `09 82 03 …`), so `incottFrameMatches`
+ * checking byte 2 against `stage` is safe here.
+ */
+export declare function incottDecodeDpiStage(frame: Uint8Array, stage: number): number | null;
+/**
+ * One axis of one stage, from a reply to `incottEncodeQueryDpiAxis`. The
+ * requested axis MUST be matched at byte 8 — see `incottFrameMatches`.
+ */
+export declare function incottDecodeDpiStageAxis(frame: Uint8Array, stage: number, axis: IncottDpiAxis): number | null;
+/**
+ * The polling value sits in byte 2, mirroring the write, which also carries
+ * its value in the sub-command slot. CONFIRMED on hardware 2026-09-08: writing
+ * wire `1` then wire `0` and reading back showed byte 2 follow, `0 -> 1 -> 0`.
+ * `0x81` does NOT echo a sub-command the way `0x82`-`0x86`/`0x8e` do — byte 2
+ * here is data, not an echo — which is why it stays out of
+ * `SUB_ECHOING_QUERIES` in `src/drivers/incott/hid.ts`.
+ */
+export declare function incottDecodePollingRate(frame: Uint8Array): number | null;
+/**
+ * Reads lift-off from the packed byte 7 of the `0x84`/sub `0x00` response
+ * (high nibble). Superseded as the driver's primary read by
+ * `incottDecodeLiftOffDirect` (see `INCOTT_SUB_LOD`'s symmetric
+ * `0x84`/`0x01` read), which is clearer, but kept and still exercised: it was
+ * cross-checked against the symmetric read on hardware 2026-09-08 — hardware
+ * values 0, 1, 2 round-tripped identically through both forms — so this is
+ * not wrong, just less direct.
+ */
+export declare function incottDecodeLiftOff(frame: Uint8Array): number | null;
+/**
+ * Symmetric single-purpose read for lift-off: `09 84 01` -> response byte 3
+ * is the raw hardware value (0-2), matching the sub-command the `0x04`/`0x01`
+ * write uses (see `incottEncodeSetLiftOff`). PREFERRED over
+ * `incottDecodeLiftOff`'s packed byte-7 nibble read: verified on hardware
+ * 2026-09-08 by round-tripping hw 0, 1, 2 through both this form and the
+ * nibble form and finding they agree at every step. The hw-to-millimetre
+ * label mapping is still an open question — see `INCOTT_LOD_WIRE_TO_TENTHS`.
+ */
+export declare function incottDecodeLiftOffDirect(frame: Uint8Array): number | null;
+/**
+ * Reads motion sync from the packed byte 7 of the `0x84`/sub `0x00` response
+ * (low nibble). Superseded as the driver's primary read by
+ * `incottDecodeToggle(frame, INCOTT_SUB_MOTION_SYNC)` (the symmetric
+ * `0x84`/`0x04` read), which is clearer, but kept and still exercised: it was
+ * cross-checked against the symmetric read on hardware 2026-09-08 — 0/1/0
+ * round-tripped identically through both forms — so this is not wrong, just
+ * less direct.
+ */
+export declare function incottDecodeMotionSync(frame: Uint8Array): boolean | null;
+export declare function incottDecodeToggle(frame: Uint8Array, sub?: number): boolean | null;
+/**
+ * `09 84 05` -> response byte 3 carries the current raw 0-2 performance-mode
+ * value. This follows the symmetric-read pattern every other `0x04`/`0x84`
+ * sensor sub-command uses (lift-off, ripple, angle snap and motion sync all
+ * pair a `0x04` write with an `0x84` read at the same sub-command), and
+ * `0x84` is already in the sub-echoing set (`SUB_ECHOING_QUERIES` in
+ * `src/drivers/incott/hid.ts`), so the existing transaction discipline covers
+ * it. Callers must still treat `null` as "unreadable," not as a confirmed
+ * value — see `IncottHidClient.setPowerMode`, which requires a non-null,
+ * matching read-back before reporting success.
+ */
+export declare function incottDecodePerformanceMode(frame: Uint8Array): number | null;
+export declare function incottDecodeDebounce(frame: Uint8Array): number | null;
+export declare function incottDecodeSleep(frame: Uint8Array): number | null;
+/** How a Fire Key button behaves: how many clicks it sends, and how fast. */
+export interface IncottFireKey {
+    /** Clicks sent per press, 0-3. */
+    times: number;
+    /** Milliseconds between those clicks, 0-255. */
+    intervalMs: number;
+}
+/**
+ * `09 05 02 <times> <interval ms>` — see `INCOTT_SUB_FIRE_KEY`.
+ *
+ * These are the settings for whichever button is bound to "Rapid fire"; they
+ * are global to the device rather than per-button, since the command carries
+ * no button index.
+ */
+export declare function incottEncodeSetFireKey(times: number, intervalMs: number): Uint8Array;
+/** `09 85 02` -> times at byte 3, interval at byte 4. */
+export declare function incottDecodeFireKey(frame: Uint8Array): IncottFireKey | null;
+export declare function incottDecodeReceiverLed(frame: Uint8Array): number | null;
+/**
+ * DISPROVEN AS A BATTERY READING, 2026-09-08 — kept as a codec only (its
+ * mechanical byte-6 decode is unchanged and still exercised by tests) and for
+ * `IncottHidClient.readStatus`'s regression test that battery is no longer
+ * sourced from this frame. See `INCOTT_CMD_QUERY_BATTERY` for the full
+ * write-up: a full charge cycle from roughly 60% to roughly 97% left this
+ * frame's byte 6 completely unchanged (`09 8e 01 5a 04 84 38 01`, `0x38` = 56
+ * throughout), the same disproof `0x89` byte 8 suffered earlier. Originally
+ * "proven" on hardware 2026-09-07 against a single static capture
+ * (`TX 09 8e 01` -> `RX 09 8e 01 5a 04 84 38 01 00`) that only ever showed one
+ * reading was never distinguished from a constant until the later
+ * full-cycle test. The real battery percentage is a field of the unsolicited
+ * input report the mouse emits while in use — see `incottDecodeInputStatus`
+ * and `IncottHidClient`'s class comment.
+ */
+export declare function incottDecodeBattery(frame: Uint8Array): number | null;
+/**
+ * Raw byte 1 (this module's convention — see below) of the mouse's
+ * unsolicited input report, above which the mouse is charging. At or below
+ * this, the raw byte IS the battery percentage; above it, subtract
+ * `INCOTT_INPUT_BATTERY_CHARGING_OFFSET` to get the percentage. See
+ * `incottDecodeInputStatus`.
+ */
+export declare const INCOTT_INPUT_BATTERY_CHARGING_THRESHOLD = 100;
+/** See `INCOTT_INPUT_BATTERY_CHARGING_THRESHOLD`. */
+export declare const INCOTT_INPUT_BATTERY_CHARGING_OFFSET = 128;
+/**
+ * Decoded fields of the mouse's unsolicited vendor-collection INPUT report
+ * (report id `INCOTT_INPUT_REPORT_ID`) — see `incottDecodeInputStatus`.
+ */
+export interface IncottInputStatus {
+    /** 0-100. */
+    batteryPercent: number;
+    /** True when `byte0 > INCOTT_INPUT_BATTERY_CHARGING_THRESHOLD`. */
+    charging: boolean;
+    /** High nibble of byte 1: which of the six DPI stages is active (0-5). Corroborates, but does not replace, the `0x83`/`0x06` feature-report read. */
+    dpiStageIndex: number;
+    /** Low nibble of byte 1: index into `INCOTT_POLLING_WIRE_TO_HZ`. Corroborates, but does not replace, the `0x81` feature-report read. */
+    pollingIndex: number;
+}
+/**
+ * Decodes the mouse's UNSOLICITED input report — battery plus a packed
+ * DPI-stage/polling-rate snapshot. This is NOT a feature-report reply (no
+ * request triggers it): the device emits it on report id
+ * `INCOTT_INPUT_REPORT_ID` on its own, only while it is actively being used.
+ *
+ * BYTE-INDEX CONVENTION, mirroring the asymmetry this module's top-of-file
+ * comment already documents for feature reports (WebHID's `sendFeatureReport`
+ * takes the report id separately, so encoded payloads omit it, while
+ * `receiveFeatureReport` returns it at byte 0, so decoded frames include it):
+ * this function's `byte0`/`byte1` parameters EXCLUDE the report id, matching
+ * WebHID's `inputreport` event, whose `data` DataView excludes it too
+ * (`event.reportId` carries it separately). So `byte0` is
+ * `event.data.getUint8(0)`, `byte1` is `event.data.getUint8(1)`.
+ *
+ * node-hid's raw input buffer, by contrast, INCLUDES the report id at index
+ * 0 — the two hardware captures below were taken that way, so in node-hid
+ * terms `byte0` is `buf[1]` and `byte1` is `buf[2]`. Get this backwards and
+ * every field reads off by one byte. See
+ * `captures/incott-8k-wireless/input-report-battery.hex` and
+ * `src/drivers/incott/hid.ts`'s `onInputReport`, which unwraps the WebHID
+ * event into this convention before calling this function.
+ *
+ * Hardware-verified 2026-09-08 across a full charge cycle (~60% to ~97%):
+ * ```
+ * discharging: 09 5f 10 04 00 0f 0f 10   (node-hid)  byte0=0x5f=95  -> 95%
+ * charging:    09 e1 10 04 00 0f 0f 10   (node-hid)  byte0=0xe1=225 -> charging, 225-128=97%
+ * ```
+ * `raw > 100` means charging (subtract `INCOTT_INPUT_BATTERY_CHARGING_OFFSET`
+ * for the percent); `raw <= 100` means discharging (raw IS the percent). This
+ * is the same convention IncottHIDApp's `parseStatus` uses, and unlike that
+ * project's other claims, this one is now independently hardware-verified in
+ * both states — see `docs/incott-testing.md`.
+ *
+ * Byte 1's `0x10` on the unit under test decoded to DPI stage 1 / polling
+ * index 0, and both independently matched what the feature reads returned at
+ * the same moment (`09 83 06` -> stage 1, `09 81` byte 2 -> 0) — a
+ * corroborating cross-check only; `IncottHidClient` still treats the feature
+ * reads as authoritative for DPI stage and polling rate.
+ *
+ * Returns `null` when either byte is out of range, or when the derived
+ * percent would fall outside 0-100 (a malformed or unrelated report).
+ */
+export declare function incottDecodeInputStatus(byte0: number, byte1: number): IncottInputStatus | null;
+/**
+ * A button's current binding: the raw 32-bit action word, plus the label
+ * when it is one this driver knows.
+ *
+ * `label` is null for a binding the action table does not cover — a keyboard
+ * key, a macro, or an action from a model this contributor cannot test. The
+ * `code` is always reported so an unrecognised binding round-trips
+ * unchanged rather than being flattened to a default.
+ */
+export interface IncottButtonBinding {
+    button: number;
+    code: number;
+    label: string | null;
+}
+/**
+ * `09 86 <button 0..5>` -> response bytes 3-6 = the binding, 32-bit
+ * little-endian.
+ *
+ * PREVIOUSLY A BUG: this read only bytes 3-5 and reported them as three
+ * unnamed bytes, silently truncating the top byte. Every action in
+ * `INCOTT_BUTTON_ACTIONS` whose code exceeds 24 bits — "Rapid fire"
+ * (`0x0218F00A`) among them — decoded to a different value than was
+ * written. The vendor reads the same four bytes
+ * (`rData[5]<<24|rData[4]<<16|rData[3]<<8|rData[2]`).
+ */
+export declare function incottDecodeButtonBinding(frame: Uint8Array, button: number): IncottButtonBinding | null;
+/**
+ * Decodes the identity reply (`09 8f 00` -> `09 8f 01 0e 02 f0 f1 00 ff`).
+ *
+ * Byte map, transcribed from the vendor configurator's `readDps()` and
+ * confirmed byte-for-byte against this contributor's G23V2 (capture
+ * 2026-09-07, `captures/incott-8k-wireless/query-sweep-0x80-0x8f.hex`):
+ *
+ *     byte 2  guard, always 0x01   -- the vendor abandons the device otherwise
+ *     byte 3  model code           -- 0x0e = G23V2, see INCOTT_MODEL_BY_CODE
+ *     byte 4  receiver type        -- 0x02 = 8 KHz receiver
+ *     byte 5  sensor slot A          -- 0xF0 -> PAW3395, 0xF1 -> PAW3950
+ *     byte 6  sensor slot B          -- same encoding, 0x00 when unpopulated
+ *
+ * THE SENSOR SLOT MOVES WITH THE RECEIVER, so neither byte alone is "the"
+ * sensor. Two wired captures of the same mouse:
+ *
+ *     cable + dongle (2026-09-08):  09 8f 01 0e 02 f0 f1 00 ff
+ *     cable only     (2026-09-11):  09 8f 01 0e 00 f1 00 00 00
+ *
+ * With the dongle present, byte 4 reports the receiver and the `0xF1` sits at
+ * byte 6; with the dongle gone, byte 4 is `0x00` and the same `0xF1` sits at
+ * byte 5. This is why the vendor indexes by connection
+ * (`let i = this.iswireless ? 5 : 4` over its report-id-less buffer, i.e.
+ * frame bytes 6:5) — that is correct behaviour, not the cosmetic bug an
+ * earlier version of this comment claimed.
+ *
+ * WHY ANY SLOT, NOT THE CONNECTION-INDEXED ONE: the fitted sensor is settled
+ * independently of this frame. A PAW3395 stops at 32000 DPI in the vendor's
+ * own table, and this mouse stored and read back 45000 over the CABLE
+ * (`captures/incott-8k-wireless/wired-dpi-ceiling-2026-09-11.hex`). It is a
+ * PAW3950 on every link, so the answer is whichever slot carries `0xF1`. The
+ * vendor's index disagrees in exactly one configuration — cable AND dongle
+ * attached, where it reads byte 5's `0xF0` and drops the "Pro" — and that is
+ * the one case where a capability byte cannot be describing this mouse.
+ *
+ * The same capture also shows there is NO wired DPI ceiling to model: 45000
+ * is accepted over the cable, so `INCOTT_DPI_MAX` stays flat across links,
+ * unlike the polling rate (`INCOTT_POLLING_STEPS_HZ_WIRED`).
+ *
+ * Returns `null` ONLY when the report id or command echo is wrong — `open()`
+ * uses that as its collection-liveness probe. A frame that is well-formed
+ * but too short, or whose guard byte is not `0x01`, still yields an identity
+ * carrying `raw` with every decoded field left null: an unreadable model is
+ * reported as unknown, never guessed.
+ */
+export declare function incottDecodeIdentity(frame: Uint8Array): IncottDeviceIdentity | null;
+/**
+ * True when this product id is the WIRED one (`0x622C`) rather than the 2.4
+ * GHz dongle's (`0x522C`, `INCOTT_PRODUCT_ID`) — hardware-verified 2026-09-08,
+ * see `INCOTT_PRODUCT_ID_WIRED`. Formerly `incottIsChargingProduct`: it
+ * always returned exactly this, but under a name that mislabelled the
+ * connection as a charging flag. Charging is real for this product id, but
+ * it is a CONSEQUENCE of being plugged in, not what the id itself encodes —
+ * see `IncottHidClient.readStatus`, which now sets `connectionType` from
+ * this helper directly and derives `batteryState: "Charging"` from it rather
+ * than from a same-named constant.
+ */
+export declare function incottIsWiredProduct(productId: number): boolean;
+/**
+ * Tidies the raw HID product string for display: drops a single leading
+ * vendor word ("incott") and a single trailing "mouse", case-insensitively,
+ * leaving whatever sits between. Falls back to the untouched raw string if
+ * stripping both would leave nothing.
+ *
+ * "incott Esports G23V2Pro mouse" -> "Esports G23V2Pro"
+ * "incott 8K wireless mouse"      -> "8K wireless"
+ *
+ * WHY THIS EXISTS: the product string names a model only over the CABLE
+ * ("incott Esports G23V2Pro mouse", hardware-verified 2026-09-08); the
+ * wireless dongle reports a generic "incott 8K wireless mouse" with no model
+ * in it at all. This function only TIDIES whatever raw string the device
+ * actually reported; it never invents one.
+ *
+ * This is now the FALLBACK, not the primary source. The identity reply's
+ * byte layout has since been decoded (`incottDecodeIdentity`), so
+ * `IncottHidClient.readStatus` prefers the model read from the device —
+ * which works wirelessly too — and drops back to this function only when the
+ * identity query fails or reports a model code the table does not know.
+ */
+export declare function incottNormalizeProductName(raw: string): string;
+/** Maps the lift-off wire value (in tenths of a millimetre) to the shared Low/Medium/High stops. */
+export declare function incottLiftOffLabel(tenthsMm: number): "Low" | "Medium" | "High" | null;
+/** Maps a Low/Medium/High stop back to tenths of a millimetre for `incottEncodeSetLiftOff`. */
+export declare function incottLiftOffTenths(level: "Low" | "Medium" | "High"): number;
+//# sourceMappingURL=index.d.ts.map