@ac-kit/format-hid 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# @ac-kit/format-hid
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [aca1cb1]
+  - @ac-kit/core@0.4.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 992cbbb: New package: USB HID 1.11 report descriptors, from the raw items to the bits of
+  a single field.
+  
+  - `decodeHidItems`/`encodeHidItems` split a descriptor into its short and long
+    items and spell them back byte for byte, with `HidMainTag`, `HidGlobalTag` and
+    `HidLocalTag` naming every tag and `hidItemUnsigned`/`hidItemSigned` reading
+    an item's value.
+  - `parseHidReportDescriptor` runs the HID 1.11 §6.2.2 state machine — Push/Pop,
+    local state cleared at every main item, extended usages, delimited sets,
+    Report IDs — into the collections, the reports with their length as
+    transferred, and the fields tiling each report, padding included. It reads
+    descriptors the way the Linux HID core does where devices and the
+    specification disagree: a Maximum is unsigned unless its Minimum is negative,
+    a one-byte Unit Exponent is a 4-bit nibble, and physical bounds both 0 mean
+    the logical range. Usage ranges stay ranges, so a whole-page range costs one
+    slot; `hidFieldUsage` resolves the usage of one element. A malformed
+    descriptor throws `HidDescriptorError` with the byte offset of the offending
+    item.
+  - `readHidFieldValue`, `writeHidFieldValueInPlace` and `createHidReport` read
+    and build report buffers at the field offsets the parser returns, Report ID
+    byte included, and `hidLogicalToPhysical` converts a value to its physical
+    quantity. `decodeHidUnit`/`encodeHidUnit` split the unit word into its system
+    and the exponent of each base quantity.

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @ac-kit/format-hid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+USB HID 1.11 report descriptors: what a device's reports look like, read from
+the descriptor it publishes, and the bit-level access to read and build those
+reports.
+
+A HID device describes its own reports in a compact item language. Before a
+single input report can be decoded, or an output report built, that language has
+to be run through the state machine of HID 1.11 §6.2.2 — global state with
+Push/Pop, local state cleared after every main item, Report IDs, usage ranges,
+delimited sets. This package does that once and hands back a plain layout:
+which reports exist, how long each is on the wire, and where every field sits.
+
+```ts
+import {
+  createHidReport,
+  parseHidReportDescriptor,
+  readHidFieldValue,
+  writeHidFieldValueInPlace,
+} from "@ac-kit/format-hid";
+
+const { reports } = parseHidReportDescriptor(descriptorBytes);
+
+const input = reports.find((report) => report.kind === "input" && report.reportId === 0x01)!;
+readHidFieldValue(received, input.fields[2]!, 0); // logical value of element 0
+
+const lights = reports.find((report) => report.kind === "output" && report.reportId === 0x82)!;
+const bytes = createHidReport(lights); // zeroed, bytes[0] === 0x82
+writeHidFieldValueInPlace(bytes, lights.fields[0]!, 182, 127);
+```
+
+It reads no device: get the descriptor from wherever the platform exposes it —
+`/sys/class/hidraw/*/device/report_descriptor` on Linux, a USB `GET_DESCRIPTOR`
+request — and move reports with whatever transport you already have.
+
+## Three levels
+
+- **Items** — `decodeHidItems` splits a descriptor into raw `HidItem`s and
+  `encodeHidItems` spells them back, byte for byte. Use it to inspect, patch or
+  generate a descriptor. `HidMainTag`, `HidGlobalTag` and `HidLocalTag` name
+  every tag; `hidItemUnsigned`/`hidItemSigned` read an item's value.
+- **Descriptor** — `parseHidReportDescriptor` returns the `collections`, the
+  `reports` and whether the device `usesReportIds`. Each `HidReportField` carries
+  its position, size, count, data flags, logical and physical ranges, unit, and
+  its usages, designators and strings as slots. `hidFieldUsage` gives the usage
+  an element refers to.
+- **Field values** — `readHidFieldValue`, `writeHidFieldValueInPlace`,
+  `createHidReport` and `hidLogicalToPhysical` work on a report buffer.
+  `decodeHidUnit`/`encodeHidUnit` split the unit word into its system and
+  exponents.
+
+## Reports as transferred
+
+Every position is counted from the first bit of the report **as it travels on
+the wire**: when the descriptor uses Report IDs, the ID is byte 0, the first
+field starts at bit 8, and `byteLength` includes it. That is what `read()` on a
+Linux `hidraw` node returns, and what `write()` on one takes for a device using
+Report IDs (for one that does not, `hidraw` wants an extra leading 0 byte).
+WebHID strips the ID byte from `inputreport` events and takes it as a separate
+argument to `sendReport`; put it back in front, or build the buffer with
+`createHidReport`, before using the field offsets.
+
+Padding and constant fields are kept, so a report's fields tile it completely.
+
+## Where real devices and the specification disagree
+
+The parser reads descriptors the way the Linux HID core does, because that is
+what devices are tested against:
+
+- A Logical or Physical Maximum is **unsigned unless its Minimum is negative**:
+  `Logical Minimum (0)`, `Logical Maximum (0xFF)` is 0–255, not 0 to -1.
+- A one-byte Unit Exponent of 0–15 is a 4-bit two's-complement nibble, so
+  `0x0E` is -2.
+- A Usage declared before a later Usage Page takes the page in effect at the
+  main item.
+- Physical Minimum and Maximum both 0 means the physical range is the logical
+  one.
+
+## Usages
+
+A usage is an unsigned 32-bit number, `page << 16 | id`; a 4-byte Usage item is
+taken whole as such an extended usage. `Usage Minimum`/`Usage Maximum` pairs stay
+ranges — a field covering a whole 65 536-usage page costs one slot — and a
+delimited set becomes one slot whose first usage is preferred and whose others
+are its `aliases`. For a variable field with fewer usages than values, the last
+usage applies to every remaining element.
+
+## Errors
+
+A malformed descriptor throws `HidDescriptorError`, a `SyntaxError` carrying the
+byte `offset` of the item the parser gave up at. An argument the caller built
+that cannot be honoured — an item `encodeHidItems` cannot spell, a value that
+does not fit its field, an index past `count` — is a `RangeError`.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/format-hid/)
+for the full reference.

package/dist/descriptor/hid-field-usage.d.ts

@@ -0,0 +1,35 @@
+import type { HidFieldFlags, HidReportField, HidSlot } from "./hid-report-descriptor.js";
+/**
+ * The value at position `index` of a slot list once its ranges are expanded, or
+ * `undefined` past the end. Ranges are never materialized.
+ *
+ * Use {@link hidFieldUsage} for a field's usages, which applies the HID rule for
+ * a variable field with fewer usages than values.
+ *
+ * O(n) time in `slots.length`, O(1) memory.
+ *
+ * @throws {RangeError} When `index` is not a non-negative integer.
+ */
+export declare function hidSlotValue(slots: readonly HidSlot[], index: number): number | undefined;
+/**
+ * The usage a field's value refers to.
+ *
+ * - **Variable field** — `index` is the element, `0 ≤ index < count`. When the
+ *   field declares fewer usages than values, the last usage applies to every
+ *   remaining element (HID 1.11 §6.2.2.8).
+ * - **Array field** — `index` is a position in the usage list, i.e. a received
+ *   value minus `logicalMinimum`. A position past the list is `undefined`, as
+ *   is any position in a field declaring no usage (padding).
+ *
+ * Aliases of a delimited set are on {@link HidReportField.usages}; this answers
+ * the preferred usage only.
+ *
+ * O(n) time in `field.usages.length`, O(1) memory.
+ *
+ * @throws {RangeError} When `index` is negative or not an integer, or is
+ *   `count` or more for a variable field.
+ */
+export declare function hidFieldUsage(field: Pick<HidReportField, "count" | "usages"> & {
+    flags: Pick<HidFieldFlags, "variable">;
+}, index: number): number | undefined;
+//# sourceMappingURL=hid-field-usage.d.ts.map

package/dist/descriptor/hid-field-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-field-usage.d.ts","sourceRoot":"","sources":["../../src/descriptor/hid-field-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,aAAa,EACb,cAAc,EACd,OAAO,EACP,MAAM,4BAA4B,CAAC;AAMpC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAiBpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,QAAQ,CAAC,GAAG;IACjD,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;CACvC,EACD,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAoBpB"}

package/dist/descriptor/hid-field-usage.js

@@ -0,0 +1,63 @@
+function slotLength_(slot) {
+    return slot.kind === "single" ? 1 : slot.maximum - slot.minimum + 1;
+}
+/**
+ * The value at position `index` of a slot list once its ranges are expanded, or
+ * `undefined` past the end. Ranges are never materialized.
+ *
+ * Use {@link hidFieldUsage} for a field's usages, which applies the HID rule for
+ * a variable field with fewer usages than values.
+ *
+ * O(n) time in `slots.length`, O(1) memory.
+ *
+ * @throws {RangeError} When `index` is not a non-negative integer.
+ */
+export function hidSlotValue(slots, index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new RangeError(`hidSlotValue: index ${index} is not a non-negative integer`);
+    }
+    let remaining = index;
+    for (const slot of slots) {
+        const length = slotLength_(slot);
+        if (remaining < length) {
+            return slot.kind === "single" ? slot.value : slot.minimum + remaining;
+        }
+        remaining -= length;
+    }
+    return undefined;
+}
+/**
+ * The usage a field's value refers to.
+ *
+ * - **Variable field** — `index` is the element, `0 ≤ index < count`. When the
+ *   field declares fewer usages than values, the last usage applies to every
+ *   remaining element (HID 1.11 §6.2.2.8).
+ * - **Array field** — `index` is a position in the usage list, i.e. a received
+ *   value minus `logicalMinimum`. A position past the list is `undefined`, as
+ *   is any position in a field declaring no usage (padding).
+ *
+ * Aliases of a delimited set are on {@link HidReportField.usages}; this answers
+ * the preferred usage only.
+ *
+ * O(n) time in `field.usages.length`, O(1) memory.
+ *
+ * @throws {RangeError} When `index` is negative or not an integer, or is
+ *   `count` or more for a variable field.
+ */
+export function hidFieldUsage(field, index) {
+    if (!field.flags.variable) {
+        return hidSlotValue(field.usages, index);
+    }
+    if (!Number.isInteger(index) || index < 0 || index >= field.count) {
+        throw new RangeError(`hidFieldUsage: index ${index} is outside 0–${field.count - 1}`);
+    }
+    let total = 0;
+    for (const slot of field.usages) {
+        total += slotLength_(slot);
+    }
+    if (total === 0) {
+        return undefined;
+    }
+    return hidSlotValue(field.usages, Math.min(index, total - 1));
+}
+//# sourceMappingURL=hid-field-usage.js.map

package/dist/descriptor/hid-field-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-field-usage.js","sourceRoot":"","sources":["../../src/descriptor/hid-field-usage.ts"],"names":[],"mappings":"AAMA,SAAS,WAAW,CAAC,IAAa;IACjC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAyB,EACzB,KAAa;IAEb,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,UAAU,CACnB,uBAAuB,KAAK,gCAAgC,CAC5D,CAAC;IACH,CAAC;IAED,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,SAAS,GAAG,MAAM,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACvE,CAAC;QACD,SAAS,IAAI,MAAM,CAAC;IACrB,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAC5B,KAEC,EACD,KAAa;IAEb,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC3B,OAAO,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QACnE,MAAM,IAAI,UAAU,CACnB,wBAAwB,KAAK,iBAAiB,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAC/D,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QACjB,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,OAAO,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/descriptor/hid-report-descriptor.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Collection types of the Collection main item (HID 1.11 §6.2.2.6). 0x07–0x7F
+ * are reserved, 0x80–0xFF vendor-defined.
+ */
+export declare enum HidCollectionType {
+    PHYSICAL = 0,
+    APPLICATION = 1,
+    LOGICAL = 2,
+    REPORT = 3,
+    NAMED_ARRAY = 4,
+    USAGE_SWITCH = 5,
+    USAGE_MODIFIER = 6
+}
+/** Which of the three report kinds a field belongs to. */
+export type HidReportKind = "input" | "output" | "feature";
+/**
+ * One position, or a run of positions, in a field's list of usages, designators
+ * or strings.
+ *
+ * Usages are 32-bit extended usages, `page << 16 | id`, read as unsigned.
+ * Designators and strings are plain indexes and never carry aliases.
+ */
+export type HidSlot = {
+    kind: "single";
+    value: number;
+    /**
+     * The other usages of a delimited set (HID 1.11 §6.2.2.8), in declaration
+     * order.
+     */
+    aliases: number[];
+} | {
+    kind: "range";
+    /** First value of the range, inclusive. */
+    minimum: number;
+    /** Last value of the range, inclusive. Never below `minimum`. */
+    maximum: number;
+};
+/** One collection, in a flat table in descriptor (pre-)order. */
+export type HidCollection = {
+    /**
+     * A {@link HidCollectionType}, or the raw number of a reserved or
+     * vendor-defined type.
+     */
+    type: number;
+    /**
+     * The first usage declared before the Collection item, or `undefined` when
+     * there was none.
+     */
+    usage: number | undefined;
+    /**
+     * Index of the enclosing collection in the same table, or -1 at the top
+     * level.
+     */
+    parentIndex: number;
+};
+/**
+ * The data bits of an Input, Output or Feature main item (HID 1.11 §6.2.2.5),
+ * one boolean per bit.
+ */
+export type HidFieldFlags = {
+    /** Bit 0: the values are fixed padding rather than data. */
+    constant: boolean;
+    /**
+     * Bit 1: one value per usage (variable) rather than a list of active usages
+     * (array).
+     */
+    variable: boolean;
+    /** Bit 2: values are deltas from the previous report rather than absolute. */
+    relative: boolean;
+    /** Bit 3: values wrap from one extreme to the other. */
+    wrap: boolean;
+    /** Bit 4: the data is not linear in what it measures. */
+    nonLinear: boolean;
+    /** Bit 5: the control has no rest position. */
+    noPreferredState: boolean;
+    /** Bit 6: a value outside the logical range means "no data". */
+    nullState: boolean;
+    /**
+     * Bit 7: the device may change the value on its own. Always `false` for an
+     * input field, whose bit 7 is reserved.
+     */
+    volatile: boolean;
+    /** Bit 8: the field is a byte stream rather than a number. */
+    bufferedBytes: boolean;
+};
+/**
+ * One Input, Output or Feature main item: `count` values of `bitSize` bits
+ * each, packed little-endian and least significant bit first.
+ */
+export type HidReportField = {
+    kind: HidReportKind;
+    /**
+     * The report this field belongs to, or 0 when the descriptor declares no
+     * Report ID.
+     */
+    reportId: number;
+    /**
+     * Position of the field's first bit from the first bit of the report as
+     * transferred — the Report ID byte included when there is one.
+     */
+    bitOffset: number;
+    /** Report Size: bits per value. */
+    bitSize: number;
+    /** Report Count: number of values. */
+    count: number;
+    flags: HidFieldFlags;
+    logicalMinimum: number;
+    logicalMaximum: number;
+    /** Equal to `logicalMinimum` when the descriptor leaves both physical bounds 0. */
+    physicalMinimum: number;
+    /** Equal to `logicalMaximum` when the descriptor leaves both physical bounds 0. */
+    physicalMaximum: number;
+    /** The raw unit word; see {@link decodeHidUnit}. */
+    unit: number;
+    /** Base-10 exponent applied to physical values. */
+    unitExponent: number;
+    /**
+     * Usage slots in declaration order; see {@link hidFieldUsage}. Empty for
+     * padding.
+     */
+    usages: HidSlot[];
+    designators: HidSlot[];
+    strings: HidSlot[];
+    /**
+     * Index in {@link HidReportDescriptor.collections} of the innermost enclosing
+     * collection, or -1.
+     */
+    collectionIndex: number;
+};
+/** Every field one report carries, and its size on the wire. */
+export type HidReport = {
+    kind: HidReportKind;
+    /** 0 when the descriptor declares no Report ID. */
+    reportId: number;
+    /** Bytes as transferred, the Report ID byte included. */
+    byteLength: number;
+    /** In descriptor order, padding included, so the fields tile the report. */
+    fields: HidReportField[];
+};
+/** The reports and collections a report descriptor declares. */
+export type HidReportDescriptor = {
+    collections: HidCollection[];
+    /** In order of first appearance. */
+    reports: HidReport[];
+    /** Whether every report starts with a Report ID byte. */
+    usesReportIds: boolean;
+};
+//# sourceMappingURL=hid-report-descriptor.d.ts.map

package/dist/descriptor/hid-report-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-report-descriptor.d.ts","sourceRoot":"","sources":["../../src/descriptor/hid-report-descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,iBAAiB;IAC5B,QAAQ,IAAO;IACf,WAAW,IAAO;IAClB,OAAO,IAAO;IACd,MAAM,IAAO;IACb,WAAW,IAAO;IAClB,YAAY,IAAO;IACnB,cAAc,IAAO;CACrB;AAED,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAChB;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACjB,GACD;IACA,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACf,CAAC;AAEL,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,WAAW,EAAE,OAAO,EAAE,CAAC;IACvB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,aAAa,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,MAAM,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG;IACjC,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,oCAAoC;IACpC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,yDAAyD;IACzD,aAAa,EAAE,OAAO,CAAC;CACvB,CAAC"}

package/dist/descriptor/hid-report-descriptor.js

@@ -0,0 +1,15 @@
+/**
+ * Collection types of the Collection main item (HID 1.11 §6.2.2.6). 0x07–0x7F
+ * are reserved, 0x80–0xFF vendor-defined.
+ */
+export var HidCollectionType;
+(function (HidCollectionType) {
+    HidCollectionType[HidCollectionType["PHYSICAL"] = 0] = "PHYSICAL";
+    HidCollectionType[HidCollectionType["APPLICATION"] = 1] = "APPLICATION";
+    HidCollectionType[HidCollectionType["LOGICAL"] = 2] = "LOGICAL";
+    HidCollectionType[HidCollectionType["REPORT"] = 3] = "REPORT";
+    HidCollectionType[HidCollectionType["NAMED_ARRAY"] = 4] = "NAMED_ARRAY";
+    HidCollectionType[HidCollectionType["USAGE_SWITCH"] = 5] = "USAGE_SWITCH";
+    HidCollectionType[HidCollectionType["USAGE_MODIFIER"] = 6] = "USAGE_MODIFIER";
+})(HidCollectionType || (HidCollectionType = {}));
+//# sourceMappingURL=hid-report-descriptor.js.map

package/dist/descriptor/hid-report-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-report-descriptor.js","sourceRoot":"","sources":["../../src/descriptor/hid-report-descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAN,IAAY,iBAQX;AARD,WAAY,iBAAiB;IAC5B,iEAAe,CAAA;IACf,uEAAkB,CAAA;IAClB,+DAAc,CAAA;IACd,6DAAa,CAAA;IACb,uEAAkB,CAAA;IAClB,yEAAmB,CAAA;IACnB,6EAAqB,CAAA;AACtB,CAAC,EARW,iBAAiB,KAAjB,iBAAiB,QAQ5B"}

package/dist/descriptor/parse-hid-report-descriptor.d.ts

@@ -0,0 +1,30 @@
+import type { HidReportDescriptor } from "./hid-report-descriptor.js";
+/**
+ * Reads a report descriptor into the reports a device sends and accepts, the
+ * fields that tile each one, and the collections around them — the HID 1.11
+ * §6.2.2 item state machine, with Push/Pop, delimited sets and extended
+ * usages.
+ *
+ * Use {@link decodeHidItems} instead to see or rewrite the items themselves.
+ *
+ * Follows the Linux reading wherever real devices and the letter of the spec
+ * disagree: a Logical or Physical Maximum is unsigned unless its Minimum is
+ * negative, so `0xFF` means 255; a one-byte Unit Exponent of 0–15 is a 4-bit
+ * two's-complement nibble; a Usage declared before a later Usage Page takes the
+ * page in effect at the main item. Long items, reserved main and local tags and
+ * reserved item types are skipped.
+ *
+ * Usage ranges are kept as ranges, so a field declaring `Usage Minimum (0)`,
+ * `Usage Maximum (0xFFFF)` costs one slot, not 65 536.
+ *
+ * O(n) time and memory in `bytes.length`.
+ *
+ * @throws {HidDescriptorError} When an item is truncated, a collection is left
+ *   open or closed twice, `Pop` meets an empty stack, a data item has no Report
+ *   Size or Report Count, a report grows past 65 535 bytes, a Report ID is 0, a
+ *   data item carries no Report ID in a descriptor that declares one, a usage,
+ *   designator or string range is unpaired or reversed, a delimited set is
+ *   nested or unbalanced, or a reserved global tag appears.
+ */
+export declare function parseHidReportDescriptor(bytes: Uint8Array): HidReportDescriptor;
+//# sourceMappingURL=parse-hid-report-descriptor.d.ts.map

package/dist/descriptor/parse-hid-report-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-hid-report-descriptor.d.ts","sourceRoot":"","sources":["../../src/descriptor/parse-hid-report-descriptor.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAGX,mBAAmB,EAInB,MAAM,4BAA4B,CAAC;AAokBpC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,UAAU,GACf,mBAAmB,CAErB"}