@openmouse/protocol 0.1.0

package/dist/drivers/incott/hid.d.ts

@@ -0,0 +1,513 @@
+import type { MouseStatus } from "../mouse-types.ts";
+import { type IncottDpiAxis, type IncottFireKey, type IncottMacro } from "../../incott/index.ts";
+type LiftOffLevel = "Low" | "Medium" | "High";
+/**
+ * The slice of HIDDevice this layer needs for feature-report exchanges, so
+ * tests can supply a fake instead of a real WebHID device. A real HIDDevice
+ * satisfies this structurally.
+ */
+export interface FeatureTransport {
+    sendFeatureReport(reportId: number, data: BufferSource): Promise<void>;
+    receiveFeatureReport(reportId: number): Promise<DataView>;
+    /**
+     * OUTPUT report, used only by the macro upload — every other command in
+     * this protocol is an 8-byte FEATURE report. Optional because most
+     * transports (and the test fakes that predate macros) have no reason to
+     * implement it; `uploadMacro` reports a clear error when it is absent.
+     */
+    sendReport?(reportId: number, data: BufferSource): Promise<void>;
+}
+export interface IncottTransactionOptions {
+    /** Delay between sending a request and reading the response. */
+    settleMs?: number;
+    /** How many reads to attempt before giving up. */
+    attempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Serializes feature-report request/response pairs for the Incott protocol.
+ *
+ * The device exposes a single shared response buffer, so overlapping requests
+ * and leftover frames both produce values that belong to a different query —
+ * probing the same query three times in separate runs returned three
+ * different payloads on real hardware. Every request therefore runs alone,
+ * discards whatever was already latched, and accepts a frame only when its
+ * command and sub-command echo the request. Ported intact from IncottHub
+ * (`src/drivers/incott/transaction.ts`), including the stale-frame regression
+ * this exists to prevent — the prior-art Go implementation (IncottHIDApp)
+ * matches on the command byte alone and is fooled by exactly this.
+ */
+export declare class IncottTransactionQueue {
+    private readonly transport;
+    private readonly settleMs;
+    private readonly attempts;
+    private readonly sleep;
+    private tail;
+    constructor(transport: FeatureTransport, options?: IncottTransactionOptions);
+    /**
+     * Sends one request and returns the matching response frame, or null when
+     * no matching frame arrives. Never rejects: a device that stops answering
+     * yields null so the caller can render an em dash instead of a stale value.
+     */
+    request(payload: Uint8Array, cmd: number, sub: number | null, axis?: number | null): Promise<Uint8Array | null>;
+    /**
+     * Sends a write, which the device does not answer. Queued alongside
+     * requests so ordering holds, but it never reads: waiting for a response
+     * that will never arrive would spend the entire attempt budget per write.
+     */
+    send(payload: Uint8Array): Promise<void>;
+    /**
+     * Sends a 32-byte OUTPUT report, the macro upload's data path. Queued with
+     * everything else so it cannot interleave with the 8-byte header that
+     * announces it, and followed by a settle delay because the vendor waits
+     * 80 ms between the two halves of each chunk.
+     */
+    sendOutput(reportId: number, payload: Uint8Array): Promise<void>;
+    private exchange;
+    private read;
+}
+/**
+ * Sends the identity query (`09 8f 00`) directly against a transport and
+ * checks for a well-formed reply — byte 0 the report id (`0x09`), byte 1 the
+ * echoed command (`0x8f`). Never throws: a transport whose `sendFeatureReport`
+ * rejects, or that answers with something else entirely, both resolve to
+ * `false` (via `IncottTransactionQueue`'s own catch-and-return-null path),
+ * exactly like a device that is not there.
+ *
+ * WHY THIS EXISTS (BUG, hardware-verified 2026-09-08): wired, the mouse
+ * exposes TWO top-level collections on usage page `0xFF05` on the same
+ * interface — identical as far as vendor/product id and usage page go — but
+ * only one of them actually answers feature reports. The other rejects every
+ * one at the OS level (`HidD_SetFeature: (0x00000001) Incorrect function` on
+ * Windows). Usage page alone cannot tell them apart; only sending something
+ * and checking for a real reply can. See `incottSelectCollection` for the
+ * ordered probe-and-pick algorithm this backs, and the comment on
+ * `IncottHidClient.open()` for why a WebHID-based client can only apply this
+ * to the single collection it was handed, not choose between two.
+ */
+export declare function incottProbeCollection(transport: FeatureTransport, options?: IncottTransactionOptions): Promise<boolean>;
+/**
+ * Picks the first candidate transport whose collection actually answers the
+ * identity probe, trying candidates in the given order and moving on to the
+ * next one when a candidate throws, never replies, or replies with garbage.
+ * Returns `null` when no candidate answers.
+ *
+ * Candidates must be pre-ordered by the CALLER, most likely first — this
+ * function only probes in the order it is given, it does not itself inspect
+ * usage pages. This is the general form of the wired dead-collection fix
+ * (see `incottProbeCollection`): a transport layer that genuinely has more
+ * than one candidate to try (for example a Node-hid-based tool with access
+ * to every top-level collection's own path) can use this directly. WebHID
+ * cannot: it hands `IncottHidClient` exactly one `HIDDevice` per collection,
+ * already chosen by the browser's picker/filters before this driver ever
+ * sees it, so `IncottHidClient.open()` uses `incottProbeCollection` on
+ * itself instead of calling this with more than one candidate.
+ */
+export declare function incottSelectCollection<T extends FeatureTransport>(candidates: readonly T[], options?: IncottTransactionOptions): Promise<T | null>;
+/**
+ * WebHID client for the Incott protocol (vendor 0x093A, products 0x522C /
+ * 0x622C). Ported from IncottHub, adapted to mouse-protocol's driver
+ * interface: the client owns `device`, `open()` and `close()` directly
+ * instead of taking an externally-managed transport, matching every other
+ * driver in this registry.
+ *
+ * FOUR bugs fixed 2026-09-08 from an owner's hardware probes in BOTH wireless
+ * and wired modes (see `docs/incott-testing.md`):
+ *
+ *   1. WIRED MODE WAS COMPLETELY BROKEN. The wired mouse exposes two
+ *      identical-looking `0xFF05` collections; only one answers feature
+ *      reports, and usage page alone cannot tell them apart. See `open()`'s
+ *      identity probe and `incottProbeCollection`/`incottSelectCollection`.
+ *   2. `0x622C` means the connection is WIRED, not "charging" — charging is
+ *      a consequence of being plugged in, not what the id encodes. See
+ *      `incottIsWiredProduct` (renamed from `incottIsChargingProduct`) and
+ *      `MouseStatus.connectionType` below.
+ *   3. The polling-rate ceiling depends on the connection: the full
+ *      125-8000 Hz ladder is wireless-only, and the mouse only reaches
+ *      1000 Hz over the cable — see `INCOTT_POLLING_STEPS_HZ_WIRED`.
+ *   4. The real model name ("Esports G23V2Pro") is only in the WIRED product
+ *      string; wireless reports a generic name with no model in it at all.
+ *      See `incottNormalizeProductName`.
+ *
+ * Polling rate (0x81) is verified readable on hardware, but `readStatus()`
+ * must not throw (see the write-a-driver doc): when it cannot be read after
+ * the transaction queue's full retry budget, the client falls back to an
+ * identity-only status — real `name`, `brand`, and whatever else was
+ * genuinely readable — with `ui.settingsReady: false` and
+ * `ui.valuesVerified: false` so the app hides the settings grid instead of
+ * rendering fabricated values. `MouseStatus.pollingRateHz` is non-nullable,
+ * so the degraded path still assigns it a number; see the comment at that
+ * assignment for why that is not a fabricated reading.
+ *
+ * DPI USED to have no known read-back at all; that changed 2026-09-08. DPI
+ * lives in a six-stage table (see `INCOTT_DPI_STAGE_COUNT` in
+ * `src/incott/index.ts`) with FOUR independent operations, not one:
+ *
+ *   which stage is active   read: `0x83`/`0x06`     write: `0x03`/`0x06 <idx>`
+ *   what a stage holds      read: `0x82`/`<stage>`  write: `0x02 <stage> <lo> <hi>`
+ *
+ * `readStatus()` reads which stage is active (`incottDecodeDpiStageIndex`)
+ * and every one of the six stages' stored values (`incottDecodeDpiStage`),
+ * populating `dpiStages`/`activeDpiStage` for OpenMouse's shared multi-stage
+ * DPI editor (`MouseUiHints.dpiStageEditor`) and deriving `dpi` as the active
+ * stage's own value — a genuine live read, not a write cache.
+ *
+ * `setActiveDpiStage()` and `setDpiStageValue()` map onto the select and edit
+ * operations above respectively, matching OpenMouse's existing generic
+ * contract (`requireClientMethod` in `openmouse/src/device/controller.ts`).
+ * `setDpi()` is kept for the plain preset row and is defined as "set the
+ * ACTIVE stage's value" — i.e. it is exactly `setDpiStageValue` at whichever
+ * stage is currently active — since that is the only meaning left for it now
+ * that a real select operation exists.
+ *
+ * A SECOND DPI BUG, found from an owner report and fixed the same day
+ * (2026-09-08): `setDpi()` used to be the *only* way to touch DPI, so the app
+ * called it every time the user picked a value from the plain preset row —
+ * indistinguishable, from the user's point of view, from "select the stage
+ * that already holds this value." It never did that: it read the active
+ * stage and overwrote *that* stage's stored value with whatever was picked,
+ * one stage at a time destroying the mouse's factory-programmed table.
+ * (IncottHIDApp's own `0x03`/`0x06` write — which that project mislabels "set
+ * DPI" — is actually the active-stage SELECT and never touches the table;
+ * see `INCOTT_CMD_SET_DPI_STAGE` in `src/incott/index.ts`.) Wiring
+ * `dpiStages`/`activeDpiStage`/`dpiStageEditor` here gives the app a real
+ * select control (`setActiveDpiStage`) so `setDpi` is no longer asked to do a
+ * select's job.
+ *
+ * `valuesVerified` is true once both the polling-rate query and the active
+ * stage's DPI read have answered — see `readStatus()`.
+ *
+ * A FIFTH bug, fixed 2026-09-08: battery used to be read from the `0x8e`
+ * feature-report reply, byte 6. Charging a unit through a full cycle (roughly
+ * 60% to roughly 97%) while polling that reply showed byte 6 never move at
+ * all — a constant, not a live reading, the same failure mode `0x89` byte 8
+ * suffered before it (see `INCOTT_CMD_QUERY_BATTERY` in
+ * `src/incott/index.ts`). The real battery level lives in an UNSOLICITED
+ * INPUT report the mouse emits on report id 0x09 while it is actively being
+ * used — see `onInputReport` below and `incottDecodeInputStatus`. The device
+ * only emits these while in use, so `readStatus()` reports `batteryPercent:
+ * null` / `batteryState: "Unknown"` until the first one arrives; nothing here
+ * fabricates a number or falls back to the disproven feature-report bytes.
+ * `batteryState`'s charging flag comes from the report's own high bit
+ * (`raw > 100`), not from the product id: `incottIsWiredProduct` (0x622C)
+ * still means the CONNECTION is wired, which is what `connectionType` below
+ * uses, and being wired does imply charging in practice, but the input report
+ * is the authoritative source for the charging state, not an inference from
+ * the product id.
+ *
+ * A SIXTH addition, 2026-09-10: performance mode (HP/Corded/LP) is now wired
+ * into OpenMouse's shared `powerModes`/`powerMode`/`setPowerMode` contract.
+ * The value-to-label mapping was hardware-confirmed by labelling every click
+ * in the vendor tool before recording its write — see `getPowerModes`,
+ * `setPowerMode`, and `INCOTT_SUB_PERFORMANCE` in `src/incott/index.ts` for
+ * the capture and the REVERSED-vs-UI warning (HP=2, Corded=1, LP=0). `readStatus()`
+ * populates `powerMode` from a live `0x84`/`0x05` read, leaving it `undefined`
+ * (never fabricated) when the collection is dead or the read fails.
+ */
+export declare class IncottHidClient {
+    readonly device: HIDDevice;
+    private readonly queue;
+    /**
+     * Cached decode of the mouse's unsolicited input report (battery plus a
+     * packed DPI-stage/polling-rate snapshot) — see `onInputReport` and the
+     * class comment's battery section. `null` until the first report arrives
+     * (the mouse only emits them while actively in use), which is exactly when
+     * `readStatus()` must report `batteryPercent: null` / `batteryState:
+     * "Unknown"` rather than a fabricated value.
+     */
+    private lastInputStatus;
+    /**
+     * Whether `open()`'s identity probe got a well-formed reply from the
+     * collection WebHID handed this client. `null` until `open()` runs (every
+     * unit test that skips `open()` and calls `readStatus()` directly keeps
+     * this `null`, so it behaves exactly as before this field existed);
+     * `false` means this specific collection is the wired mouse's dead
+     * look-alike (see the class comment and `open()`).
+     */
+    private collectionVerified;
+    constructor(device: HIDDevice, options?: IncottTransactionOptions);
+    /**
+     * Decodes the mouse's unsolicited input report and caches the result for
+     * `readStatus()` — see the class comment's battery section and
+     * `incottDecodeInputStatus` in `src/incott/index.ts`.
+     *
+     * BYTE-INDEX CONVENTION: WebHID's `inputreport` event carries `reportId`
+     * separately from `data`, and `data` EXCLUDES the report id — unlike this
+     * driver's feature-report frames, which include it because
+     * `receiveFeatureReport` returns it at byte 0 (see the top-of-file comment
+     * in `src/incott/index.ts` for that asymmetry, which this mirrors). So
+     * `event.data.getUint8(0)`/`getUint8(1)` are this report's bytes 1/2 in
+     * node-hid terms — node-hid's raw buffer includes the report id at index 0,
+     * which is how `captures/incott-8k-wireless/input-report-battery.hex` is
+     * indexed. Get this backwards and every field reads off by one byte.
+     *
+     * Filtered to report id `INCOTT_INPUT_REPORT_ID` (0x09): the mouse's other
+     * HID collections (mouse/keyboard boot reports, etc.) are not this vendor
+     * collection's traffic and must not be mistaken for it.
+     */
+    private readonly onInputReport;
+    /**
+     * Usage page alone cannot tell the wired mouse's two look-alike `0xFF05`
+     * collections apart (see the class comment and `open()`), so this stays
+     * permissive on purpose: it accepts ANY device on a vendor-defined usage
+     * page with a matching product id, including the one that turns out to be
+     * the dead collection. Rejecting it here would also reject the live one,
+     * since WebHID hands this method one collection at a time and both look
+     * identical from `vendorId`/`productId`/`usagePage` alone. The actual
+     * distinction is made by probing after `open()` — see `open()` and
+     * `readStatus()`'s graceful degradation when the probe fails.
+     */
+    static isSupported(device: HIDDevice): boolean;
+    /**
+     * WebHID request filters for the vendor collection, one per product id —
+     * both the wireless dongle's `0x522C` (`INCOTT_PRODUCT_ID`) and the wired
+     * `0x622C` (`INCOTT_PRODUCT_ID_WIRED`), hardware-verified 2026-09-08, so
+     * the picker offers the mouse in either mode.
+     */
+    static get filters(): HIDDeviceFilter[];
+    /**
+     * The real writable range: 50-45000 DPI in steps of 50 (see `INCOTT_DPI_MIN`
+     * in `src/incott/index.ts`), returned densely so the shell's custom-DPI
+     * entry (which validates by exact membership, not by snapping to a nearby
+     * value) accepts any value in range — the same pattern already used for
+     * Razer's Viper V4 Pro (`100-50,000 in 50-DPI increments`) and for
+     * Zaunkoenig and Finalmouse. This is deliberately NOT
+     * `INCOTT_DPI_DEFAULT_STAGE_PRESETS` (the six round numbers the vendor
+     * calls default stage presets) — that list is too sparse for the shell to
+     * let a user dial in, say, 12000 DPI, which this mouse genuinely supports.
+     */
+    getDpiOptions(): number[];
+    /** The vendor's six default DPI stage presets — a convenience list, not the writable range. See `INCOTT_DPI_DEFAULT_STAGE_PRESETS`. */
+    getDpiDefaultStagePresets(): number[];
+    /** Longest debounce the firmware accepts, in milliseconds (verified: section 8 of the IncottHub spec). */
+    getDebounceMaxMs(): number;
+    /** The firmware accepts any integer 0-30 ms, so every value in range is offered. */
+    getDebounceOptions(): number[];
+    /** Curated presets within the verified 1-900s sleep-timer range; see INCOTT_SLEEP_OPTIONS. */
+    getSleepOptions(): number[];
+    /**
+     * Opens the device, then PROBES it with the identity query before trusting
+     * it for anything else — see `incottProbeCollection`.
+     *
+     * WIRED-MODE BUG, hardware-verified 2026-09-08: the wired mouse exposes
+     * two `0xFF05` collections on the same interface that are indistinguishable
+     * by vendor id, product id, or usage page; only one of them answers
+     * feature reports at all (the other fails every `HidD_SetFeature` call at
+     * the OS level). WebHID hands this client exactly ONE `HIDDevice`, already
+     * chosen by the browser's picker/filters before this driver ever sees
+     * it — a WebHID `HIDDevice` corresponds to a single collection, so there is
+     * no second candidate here for this method to fall back to the way
+     * `incottSelectCollection` can for a transport with real alternatives. All
+     * `open()` CAN do in the browser is find out, immediately and cheaply,
+     * whether the one collection it got is the live one.
+     *
+     * This never throws on a dead collection — it records the result in
+     * `collectionVerified` instead. `readStatus()` checks that flag and skips
+     * straight to a fully degraded, `ui.settingsReady: false` status (see
+     * there) rather than burning the full retry budget on roughly a dozen
+     * queries that a collection already known to be dead cannot answer either.
+     *
+     * Also attaches `onInputReport` (see the class comment's battery section):
+     * the mouse's battery lives only in an unsolicited input report it emits
+     * while actively in use, and WebHID delivers those solely as `inputreport`
+     * events on the device — there is no way to poll for one, so the listener
+     * must be attached here, before the device is ever read, or an in-use
+     * report could arrive and be missed before anything is listening.
+     */
+    open(): Promise<void>;
+    close(): Promise<void>;
+    readStatus(): Promise<MouseStatus>;
+    /**
+     * Sets the ACTIVE stage's stored DPI value — the only sane meaning left for
+     * a plain "set DPI" call now that a real stage-select operation exists (see
+     * `setActiveDpiStage` below and the class comment's account of the bug this
+     * used to have). This is exactly `setDpiStageValue(activeStage, dpi)`;
+     * confirms the write by reading that stage back, the same pattern every
+     * other setter in this client uses. Range/step are validated up front,
+     * before any device round-trip, so an invalid value never costs the query
+     * needed to find the active stage.
+     */
+    setDpi(dpi: number): Promise<number>;
+    /**
+     * Sets both DPI axes on the ACTIVE stage — the shape a generic X/Y control
+     * needs, where `setDpiStageAxis` is per-stage and per-axis.
+     *
+     * Mirrors the vendor's own `setResolution`: one write with the "both" flag
+     * when the axes match, two axis-flagged writes when they differ. Named to
+     * match the method proposed upstream for a brand-agnostic axis control; if
+     * the maintainers settle on a different name this is the one line to
+     * rename.
+     */
+    setAxisDpi(dpiX: number, dpiY: number): Promise<void>;
+    /**
+     * Uploads one macro into an on-device buffer.
+     *
+     * Ten 32-byte chunks, each announced by an 8-byte feature report and then
+     * carried by a 32-byte OUTPUT report on the same id — the only place this
+     * protocol uses an output report at all. Captured from the vendor tool
+     * 2026-09-11; see `captures/incott-8k-wireless/macro-upload-2026-09-11.hex`.
+     *
+     * The device does not acknowledge any of it, so unlike every other setter
+     * here there is nothing to verify against: there is no macro read command.
+     * Bind a button to `Macro <n>` and press it — that is the only confirmation
+     * available.
+     */
+    uploadMacro(macro: IncottMacro): Promise<void>;
+    /** Reads the DPI cycle (stage count + active stage) in one query. */
+    private readDpiCycle;
+    /**
+     * SELECTS which DPI stage is active (`09 03 <count> <idx>`) — distinct from
+     * `setDpi`/`setDpiStageValue`, which EDIT a stage's stored value. Confirmed
+     * on hardware 2026-09-08 that a select never touches any stage's stored
+     * value (see `INCOTT_CMD_SET_DPI_STAGE` in `src/incott/index.ts`), so
+     * unlike every value setter in this client this one reads back the active
+     * index rather than a DPI value.
+     *
+     * The stage count is READ FIRST and written back unchanged. It shares the
+     * write with the index, so sending a constant here would silently resize a
+     * cycle that is not six stages long — see
+     * `INCOTT_DPI_STAGE_COUNT_DEFAULT`.
+     */
+    setActiveDpiStage(stage: number): Promise<number>;
+    /**
+     * Sets how many stages the DPI cycle rotates through (`09 03 <count>
+     * <idx>`). The stored value of every stage is left alone — stages above
+     * the new count keep their values and simply stop being visited.
+     *
+     * The active stage rides along in the same write, so it is clamped into
+     * the new cycle rather than left pointing past the end.
+     */
+    setDpiStageCount(count: number): Promise<number>;
+    /**
+     * EDITS one stage's stored DPI value directly, by index — unlike `setDpi`,
+     * which always targets whichever stage happens to be active right now.
+     * This is the write OpenMouse's shared multi-stage DPI editor uses when the
+     * user edits a specific stage row rather than the active-stage preset.
+     */
+    setDpiStageValue(stage: number, dpi: number): Promise<number>;
+    setPollingRate(hz: number): Promise<number>;
+    setLiftOffDistance(level: LiftOffLevel): Promise<LiftOffLevel>;
+    setMotionSync(on: boolean): Promise<boolean>;
+    setAngleSnapping(on: boolean): Promise<boolean>;
+    setRippleControl(on: boolean): Promise<boolean>;
+    setDebounceTime(ms: number): Promise<number>;
+    setSleepTimeout(seconds: number): Promise<number>;
+    /**
+     * Not called generically by the app (no shared receiver-LED control exists
+     * yet), kept for protocol parity with IncottHub.
+     *
+     * NOTE for whoever wires this up: the receiver LED is a property of the
+     * 2.4 GHz dongle and is meaningless when `incottIsWiredProduct(device.productId)`
+     * is true (checked 2026-09-08) — there is no dongle in that mode. Checked
+     * `MouseUiHints` in `src/drivers/mouse-types.ts` for an existing `hide*`
+     * flag to gate this with and found none scoped to the receiver LED
+     * specifically (the closest, `hideSignalCard`, is about link-quality
+     * telemetry, a different control); a new hint was deliberately NOT added to
+     * that shared contract for a control this driver does not yet advertise
+     * anywhere. Whoever wires a shared receiver-LED control into `MouseStatus`
+     * should either add a scoped `hide*` flag there at that time, or simply
+     * omit the wiring outright when wired, matching the other wireless-only
+     * behavior in this driver (see `INCOTT_POLLING_STEPS_HZ_WIRED`).
+     */
+    /**
+     * Reads all six button bindings, keyed by the physical button name.
+     *
+     * Returns null unless every button answered: see the call site in
+     * `readStatus` for why a partial read is not published. A binding the
+     * action table does not know (a keyboard key, a macro) reports its raw code
+     * as `Unknown (0x...)` rather than being shown as one of the offered
+     * actions — the shared remapper writes back what it displays, so labelling
+     * an unknown binding as a known action would rewrite it on the next edit.
+     */
+    private readButtonMappings;
+    /**
+     * Reassigns one button, then reads it back and refuses to report success
+     * unless the device actually took the value.
+     *
+     * `button` is a physical name; the wire index it maps to is NOT the same
+     * number (Forward and Back are transposed — see
+     * `INCOTT_BUTTON_WIRE_INDEX`). This is a standalone command, so it cannot
+     * disturb DPI, polling or the other five buttons.
+     */
+    setButtonMapping(button: string, actionLabel: string): Promise<void>;
+    /**
+     * Reads the Fire Key (rapid-fire) parameters — how many clicks a button
+     * bound to "Rapid fire" sends, and how far apart. Global to the device: the
+     * command carries no button index.
+     */
+    getFireKey(): Promise<IncottFireKey | null>;
+    /**
+     * Writes the Fire Key parameters and verifies the read-back.
+     *
+     * Not advertised through `MouseStatus`: the shared contract has no
+     * rapid-fire field, so there is no generic control to publish this behind —
+     * the same position `setReceiverLed` is in. Kept for protocol parity and
+     * for whoever wires a control up.
+     */
+    setFireKey(times: number, intervalMs: number): Promise<IncottFireKey>;
+    setReceiverLed(mode: number): Promise<number>;
+    /**
+     * Low-level codec method: writes the RAW 0-2 performance-mode value. Kept
+     * for protocol parity and as the primitive `setPowerMode` below builds on.
+     * Most callers should use `setPowerMode(name)` instead, which validates a
+     * name against the hardware-confirmed HP/Corded/LP mapping (see
+     * `INCOTT_SUB_PERFORMANCE` in `src/incott/index.ts`) and requires a
+     * matching read-back before reporting success.
+     *
+     * This method is intentionally more lenient than `setPowerMode`: a `null`
+     * read-back (the device not answering) does not throw here, since a raw
+     * numeric call has no name to validate up front and existing callers/tests
+     * rely on this tolerance. See `setPowerMode` for the stricter contract.
+     */
+    setPerformanceMode(mode: number): Promise<number>;
+    /** See `setPerformanceMode`. Returns `null` when `0x84`/`0x05` does not answer. */
+    getPerformanceMode(): Promise<number | null>;
+    /**
+     * The named power/performance modes this mouse offers, in the vendor UI's
+     * own left-to-right display order (HP, Corded, LP) — see
+     * `INCOTT_PERFORMANCE_MODE_NAMES`. This order is deliberately NOT the wire
+     * value order: see `setPowerMode` and `INCOTT_SUB_PERFORMANCE` in
+     * `src/incott/index.ts` for the reversal this table exists to get right.
+     */
+    getPowerModes(): string[];
+    /**
+     * OpenMouse's shared power/performance-mode contract
+     * (`requireClientMethod("setPowerMode", …)` in
+     * `openmouse/src/device/controller.ts`) — takes the mode NAME, not the raw
+     * wire value. Maps name -> wire through `incottPerformanceModeToWire`
+     * (`INCOTT_PERFORMANCE_MODE_TO_WIRE` in `src/incott/index.ts`), the single
+     * table the HP=2/Corded=1/LP=0 reversal lives in — hardware-confirmed
+     * 2026-09-10 by labelling each click in the vendor tool before recording
+     * its write; see `INCOTT_SUB_PERFORMANCE`'s doc comment.
+     *
+     * Rejects an unknown name BEFORE writing anything (same pattern as
+     * `incottValidateDpi`/`setDpi` above), then writes and requires a matching,
+     * non-null read-back — unlike the lower-level `setPerformanceMode`, a
+     * `null` read-back here is treated as a failure, not tolerated: every
+     * setter in this driver verifies its write, and an unverifiable write must
+     * report failure rather than claim success.
+     */
+    setPowerMode(name: string): Promise<void>;
+    /** Queries return an all-zero frame on failure, which every decoder rejects. */
+    private query;
+    /**
+     * Reads ONE AXIS of one DPI stage. Separate from `query` because the axis
+     * has to be matched in the reply as well as sent: X and Y on the same stage
+     * are two requests with an identical command and sub-command, so the second
+     * would otherwise accept the first's latched frame.
+     */
+    private queryDpiAxis;
+    /** Reads one axis of one stage, or null when the device does not answer. */
+    readDpiStageAxis(stage: number, axis: IncottDpiAxis): Promise<number | null>;
+    /**
+     * Writes one axis of one stage and verifies it by reading that axis back.
+     *
+     * Independent X and Y are real on this device — hardware-verified
+     * 2026-09-11, see `INCOTT_DPI_AXIS`. Writing `"both"` is what the ordinary
+     * `setDpiStageValue` does.
+     */
+    setDpiStageAxis(stage: number, dpi: number, axis: IncottDpiAxis): Promise<number>;
+    private write;
+}
+export {};
+//# sourceMappingURL=hid.d.ts.map

package/dist/drivers/incott/hid.d.ts.map

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