@v5x/serial 0.5.5 → 0.5.7

package/README.md

@@ -4,9 +4,8 @@ TypeScript implementation of the VEX V5 serial protocol.
 
 See the [serial library documentation](https://docs.v5x.dev/serial/overview) for browser setup, guides, and high-level API reference.
 
-This package provides helpers for connecting to V5 devices over the Web Serial
-API, reading device state, transferring files, and working with protocol
-packets.
+It covers connecting to V5 devices over the Web Serial API, reading device
+state, transferring files, and working with protocol packets.
 
 ## Install
 
@@ -30,7 +29,10 @@ if (opened.isErr()) {
   console.error(opened.error); // VexSerialError with a stable .kind
   return;
 }
-// opened.value: true | false | undefined (opened / busy / no port selected)
+if (opened.value !== "opened") {
+  console.error(`Unable to open a compatible port: ${opened.value}`);
+  return;
+}
 
 const status = await connection.getSystemStatus();
 if (status.isOk()) {
@@ -47,7 +49,7 @@ can open.
 The package ships ESM, CommonJS, and TypeScript declarations. Packet and version
 utilities work in Bun or Node.js, but direct browser device connections require
 the Web Serial API. The `@v5x/cli` package is separate and currently supports
-Linux only.
+Linux and macOS. Windows requires a different CLI serial backend.
 
 ## Common Exports
 
@@ -64,10 +66,9 @@ Linux only.
 
 ## Result-returning async APIs
 
-All public async methods return `ResultAsync<T, VexSerialError>` (or
-`ResultAsync<T, VexSerialError>`-yielding helpers) so failures are explicit in
-the type system rather than thrown. State-changing operations are awaitable and
-report errors through the result channel:
+All public async methods return `ResultAsync<T, VexSerialError>`, so failures
+are explicit in the type system rather than thrown. State-changing operations
+are awaitable and report errors through the result channel:
 
 ```ts
 const r = await device.setMatchMode("disabled");
@@ -83,9 +84,9 @@ removed. Migrate to the corresponding `setMatchMode()` / `setActiveProgram()`
 methods and handle the returned `Result`.
 
 Legacy methods that resolved to `false`, `null`, or `undefined` on failure now
-return a typed `Err` instead, preserving the prior success value semantics on
-the `Ok` channel (e.g. `open()` still resolves to `Ok(true | false |
-undefined)`).
+return a typed `Err` instead. `open()` reports non-error connection outcomes on
+the `Ok` channel as `"opened"`, `"busy"`, or `"no-port"`; only `"opened"`
+indicates an established connection.
 
 ## Transfers and timeouts
 
@@ -97,7 +98,7 @@ transfer is active by default.
 Protocol requests default to a 1,000 ms response timeout. Individual transfer
 phases use longer timeouts where erase, write, or exit operations need them.
 `reconnect(0)` waits indefinitely, while a positive reconnect timeout is a total
-deadline in milliseconds. A timeout or NACK is reported as a `VexProtocolError`
+deadline in milliseconds. A timeout or NACK surfaces as a `VexProtocolError`
 (or a related `VexSerialError` subclass) through the `Result` error channel; it
 does not cancel work already running on the device.
 
@@ -114,3 +115,33 @@ bun run build
 ```
 
 The build emits JavaScript bundles and TypeScript declarations under `dist/`.
+
+### Packet registry and browser bundle measurement
+
+The complete entry point registers every reply class explicitly. Packet
+decoding no longer discovers classes by enumerating the packet-model module at
+runtime. Consumers that only need framing, CRC, packet base classes, and a
+custom reply registry can import `@v5x/serial/packet-core`; that entry point
+does not retain file-transfer, firmware, screenshot, or dashboard models.
+Register only the reply classes the application accepts with
+`PacketEncoder.getInstance().registerPacketTypes(...)`.
+
+Run `bun run measure:bundles` in this package to report reproducible minified
+byte sizes for the complete browser entry and the packet-core entry.
+
+### File-transfer window semantics
+
+The `windowSize` returned by `InitFileTransferReplyD2HPacket` is the maximum
+data size for one `ReadFile` or `WriteFile` block. It is not a count of blocks
+that may be outstanding. This follows from the wire model: read and write
+replies carry only the shared CDC2 command and function IDs; write replies have
+no address, sequence number, or request identifier with which to correlate an
+individual outstanding block. A read address can validate a reply after it is
+routed, but cannot make write failures unambiguous.
+
+Transfers therefore intentionally remain stop-and-wait. The advertised value
+is clamped to the library's 4096-byte block limit and used only as the chunk
+size. There is no safe before/after pipelining benchmark to run because the
+protocol does not expose the correlation needed to enable pipelining without
+risking data corruption. Hardware throughput remains dependent on one USB
+round trip per block.

package/dist/Vex.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { type VexFirmwareVersion } from "./VexFirmwareVersion.js";
 import { type HostBoundPacket } from "./VexPacket.js";
 export declare const USER_PROG_CHUNK_SIZE = 4096;
@@ -134,7 +135,8 @@ export declare enum AckType {
     CDC2_NACK_FILE_EXISTS = 219,
     CDC2_NACK_FILE_SYS_FULL = 220,
     TIMEOUT = 256,
-    WRITE_ERROR = 257
+    WRITE_ERROR = 257,
+    NOT_CONNECTED = 258
 }
 export declare enum SmartDeviceType {
     EMPTY = 0,

package/dist/VexCRC.d.ts

@@ -2,17 +2,6 @@ export declare class CrcGenerator {
     crc32Table: Uint32Array;
     static POLYNOMIAL_CRC32: number;
     static POLYNOMIAL_CRC16: number;
-    constructor();
-    /**
-     * Calculate CRC16 for buffer
-     */
     crc16(buf: Uint8Array, initValue: number): number;
-    /**
-     * Generate CRC32 reverse table
-     */
-    crc32GenTable(): void;
-    /**
-     * Calculate CRC32 for buffer
-     */
     crc32(buf: Uint8Array, initValue: number): number;
 }

package/dist/VexConnection.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { AckType, FileDownloadTarget, type IFileBasicInfo, type IFileWriteRequest, type IPacketCallback, type MatchMode, type SlotNumber, type SelectDashScreen } from "./Vex.js";
 import { VexSerialError } from "./VexError.js";
 import { VexEventTarget } from "./VexEvent.js";
@@ -5,40 +6,90 @@ import { type ProgramIniConfig } from "./VexIniConfig.js";
 import { Result, ResultAsync } from "neverthrow";
 import { MatchStatusReplyD2HPacket, DeviceBoundPacket, MatchModeReplyD2HPacket, GetSystemStatusReplyD2HPacket, type HostBoundPacket, Query1ReplyD2HPacket, LoadFileActionReplyD2HPacket, GetSystemFlagsReplyD2HPacket, GetRadioStatusReplyD2HPacket, GetDeviceStatusReplyD2HPacket, SendDashTouchReplyD2HPacket, SelectDashReplyD2HPacket, ScreenCaptureReplyD2HPacket } from "./VexPacket.js";
 import { type VexFirmwareVersion } from "./VexFirmwareVersion.js";
+type HostBoundPacketType<T extends HostBoundPacket> = {
+    new (data: ArrayBuffer | Uint8Array): T;
+    name: string;
+};
+/** Outcome of {@link VexSerialConnection.open}. */
+export type OpenResult = "opened" | "busy" | "no-port";
+/**
+ * Payload of the `warning` event: a non-fatal condition the library
+ * recovered from, surfaced so embedders can log or ignore it.
+ */
+export interface ConnectionWarning {
+    message: string;
+    details?: unknown;
+}
+export interface VexSerialConnectionEvents {
+    connected: undefined;
+    disconnected: undefined;
+    warning: ConnectionWarning;
+}
 /**
  * A connection to a V5 device.
- * Emit events: connected, disconnected
+ * Emit events: connected, disconnected, warning
  */
-export declare class VexSerialConnection extends VexEventTarget {
+export declare class VexSerialConnection extends VexEventTarget<VexSerialConnectionEvents> {
     filters: SerialPortFilter[];
     writer: WritableStreamDefaultWriter<unknown> | undefined;
     reader: ReadableStreamDefaultReader<unknown> | undefined;
     port: SerialPort | undefined;
     serial: Serial;
-    callbacksQueue: IPacketCallback[];
+    private pendingCallbacks;
+    private rawCallbacks;
+    private pendingCommandTails;
     private _onPortDisconnect;
     private _closePromise;
+    private _openPromise;
+    private _isClosing;
     private _wasConnected;
     protected fileTransferTail: Promise<unknown>;
     protected fileTransferDepth: number;
+    /** Pending callbacks, exposed as a snapshot for backwards compatibility. */
+    get callbacksQueue(): IPacketCallback[];
     get isConnected(): boolean;
     get isFileTransferring(): boolean;
     constructor(serial: Serial);
+    protected reportWarning(message: string, details?: unknown): void;
+    /**
+     * Connection events are notifications only: a consumer callback must not
+     * alter the lifecycle of the serial transport that produced it.
+     */
+    private emitSafely;
     close(): Promise<void>;
+    private _closeAfterOpen;
     private _hasOpenResources;
     private _doClose;
     /**
-     * Open a port. The result is `Err` only when a connection is already
-     * open (programmer error); otherwise the underlying `boolean |
-     * undefined` semantics are preserved: `true` = opened, `false` =
-     * the port was busy, `undefined` = no matching port was selected.
+     * Open a port. Resolves `"opened"` when a connection is established,
+     * `"busy"` when the matching port is already held elsewhere, and
+     * `"no-port"` when no matching port was selected. The result is `Err`
+     * when a connection is already open (programmer error) or when the
+     * port fails to open (permissions, dead device, ...). Concurrent calls
+     * join the same open attempt and receive its result.
      */
-    open(use?: number | undefined, askUser?: boolean): ResultAsync<boolean | undefined, VexSerialError>;
+    open(use?: number, askUser?: boolean): ResultAsync<OpenResult, VexSerialError>;
     private _open;
-    writeData(rawData: DeviceBoundPacket | Uint8Array, resolve: (data: HostBoundPacket | ArrayBuffer | AckType) => void, timeout?: number): void;
     writeDataAsync(rawData: DeviceBoundPacket | Uint8Array, timeout?: number): Promise<HostBoundPacket | ArrayBuffer | AckType>;
-    protected readData(cache: Uint8Array, expectedSize: number): Promise<Uint8Array>;
+    /**
+     * A command ID identifies a reply packet type, not an individual request.
+     * Keep requests with the same reply identifiers off the wire until the
+     * preceding request has resolved, while allowing unrelated commands to run
+     * concurrently.
+     */
+    private serializeCommand;
+    private writeDataAsyncUnserialized;
+    request<T extends HostBoundPacket>(packet: DeviceBoundPacket, ReplyType: HostBoundPacketType<T>, timeout?: number): ResultAsync<T, VexSerialError>;
+    protected readData(cache: ReceiveBuffer, expectedSize: number): Promise<void>;
     protected startReader(): Promise<void>;
+    private pendingKey;
+    private getPendingQueue;
+    private enqueuePendingCallback;
+    private removePendingCallback;
+    private shiftPendingCallback;
+    private shiftRawCallback;
+    private hasPendingCallbacks;
+    private drainPendingCallbacks;
     query1(): ResultAsync<Query1ReplyD2HPacket, VexSerialError>;
     getSystemVersion(): ResultAsync<VexFirmwareVersion, VexSerialError>;
 }
@@ -101,3 +152,19 @@ export declare class V5SerialConnection extends VexSerialConnection {
     mockTouch(x: number, y: number, press: boolean): ResultAsync<SendDashTouchReplyD2HPacket, VexSerialError>;
     openScreen(screen: number | SelectDashScreen, port: number): ResultAsync<SelectDashReplyD2HPacket, VexSerialError>;
 }
+/**
+ * A growable receive queue. Parsed packets are copied out before their bytes
+ * are discarded, so views into this reusable storage never escape the reader.
+ */
+declare class ReceiveBuffer {
+    private storage;
+    private start;
+    private end;
+    get byteLength(): number;
+    get bytes(): Uint8Array<ArrayBuffer>;
+    append(chunk: Uint8Array): void;
+    copy(length: number): Uint8Array<ArrayBuffer>;
+    discard(length: number): void;
+    private reserve;
+}
+export {};

package/dist/VexDevice.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { type MatchMode } from "./Vex.js";
 import { V5SerialConnection } from "./VexConnection.js";
 import { V5Brain, V5Controller, V5Radio, V5SerialDeviceState, V5SmartDevice, VexSerialDevice } from "./VexDeviceState.js";
@@ -5,17 +6,40 @@ import { VexSerialError } from "./VexError.js";
 import { ResultAsync } from "neverthrow";
 export { VexSerialDevice, V5Brain, V5Battery, V5BrainButton, V5BrainSettings, V5Controller, V5SmartDevice, V5Radio, V5SerialDeviceState, } from "./VexDeviceState.js";
 export { sleep, sleepUntil, sleepUntilAsync, downloadFileFromInternet, uploadFirmware, } from "./VexFirmware.js";
+export interface V5SerialDeviceOptions {
+    autoRefresh?: boolean;
+    refreshIntervalMs?: number;
+}
 export declare class V5SerialDevice extends VexSerialDevice {
     autoReconnect: boolean;
-    autoRefresh: boolean;
     pauseRefreshOnFileTransfer: boolean;
     protected _isReconnecting: boolean;
     private _isDisconnecting;
     private _refreshInterval;
     state: V5SerialDeviceState;
     private _disposed;
+    private _lifecycleGeneration;
+    private _disconnectListener;
     private _refreshGeneration;
-    constructor(defaultSerial: Serial);
+    private _autoRefresh;
+    private _refreshIntervalMs;
+    private _isLastRefreshComplete;
+    private readonly _brain;
+    private readonly _controllers;
+    private readonly _radio;
+    private readonly _deviceFacades;
+    /**
+     * Device lifecycle events are notifications only: consumer callbacks must
+     * not alter automatic refresh or reconnect work that produced them.
+     */
+    private _emitSafely;
+    constructor(defaultSerial: Serial, options?: boolean | V5SerialDeviceOptions);
+    get autoRefresh(): boolean;
+    set autoRefresh(value: boolean);
+    get refreshIntervalMs(): number;
+    set refreshIntervalMs(value: number);
+    private _startRefreshInterval;
+    private _stopRefreshInterval;
     get isV5Controller(): boolean;
     get brain(): V5Brain;
     get controllers(): [V5Controller, V5Controller];
@@ -47,7 +71,13 @@ export declare class V5SerialDevice extends VexSerialDevice {
     reconnect(timeout?: number): ResultAsync<void, VexSerialError>;
     private _reconnect;
     private waitForReconnectToFinish;
+    protected createConnection(): V5SerialConnection;
+    private _isLifecycleCurrent;
+    private _staleLifecycleResult;
+    private _commitConnection;
+    private _detachDisconnectListener;
     private doAfterConnect;
+    private _discardConnection;
     /**
      * Refresh the high-level device snapshot. All required replies are
      * collected before any public state is mutated, so callers never see

package/dist/VexDeviceState.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { type MatchMode, SerialDeviceType, type SlotNumber, type ISmartDeviceInfo, SmartDeviceType, FileVendor, type IProgramInfo, type IFileHandle, type IFileBasicInfo, type IFileWriteRequest, FileDownloadTarget, RadioChannelType } from "./Vex.js";
 import { type V5SerialConnection } from "./VexConnection.js";
 import { VexEventTarget } from "./VexEvent.js";
@@ -6,7 +7,11 @@ import { type ProgramIniConfig } from "./VexIniConfig.js";
 import { VexSerialError } from "./VexError.js";
 import { ResultAsync } from "neverthrow";
 import type { V5SerialDevice } from "./VexDevice.js";
-export declare abstract class VexSerialDevice extends VexEventTarget {
+export interface VexSerialDeviceEvents {
+    disconnected: undefined;
+    error: unknown;
+}
+export declare abstract class VexSerialDevice extends VexEventTarget<VexSerialDeviceEvents> {
     connection: V5SerialConnection | undefined;
     defaultSerial: Serial;
     get isConnected(): boolean;
@@ -19,18 +24,24 @@ export declare class V5SerialDeviceState {
     _instance: V5SerialDevice;
     /**
      * Counter used only to pause automatic refresh while a file transfer
-     * is in flight. This is not a mutex: serialisation of transfer
-     * operations lives on the {@link V5SerialConnection} transaction
-     * queue. The counter is exposed via {@link isFileTransferring} so the
-     * refresh loop can skip work during transfers.
+     * is in flight. This is not a mutex: serialization of transfer
+     * operations lives on the {@link V5SerialConnection} transaction queue.
      */
     private refreshPauseDepth;
+    get isRefreshPaused(): boolean;
+    /**
+     * @deprecated Use {@link isRefreshPaused}. This flag only means that
+     * automatic refresh is paused, not that transfer operations are locked.
+     */
     get isFileTransferring(): boolean;
     /**
      * Increment the refresh-pause depth, run the operation, and decrement
-     * the depth again. The actual transfer mutex lives on the connection,
-     * so this method does not serialise anything; it only signals the
-     * device that a transfer is in progress so refresh polling is paused.
+     * the depth again. The actual transfer mutex lives on the connection.
+     */
+    withRefreshPaused<T>(operation: () => PromiseLike<T>): Promise<T>;
+    /**
+     * @deprecated Use {@link withRefreshPaused}. This only pauses automatic
+     * refresh and does not lock file transfers.
      */
     withFileTransfer<T>(operation: () => PromiseLike<T>): Promise<T>;
     brain: {
@@ -54,15 +65,18 @@ export declare class V5SerialDeviceState {
         systemVersion: VexFirmwareVersion;
         uniqueId: number;
     };
-    controllers: ({
-        battery: number;
-        isAvailable: boolean;
-        isCharging: boolean;
-    } | {
-        battery: number;
-        isAvailable: boolean;
-        isCharging?: undefined;
-    })[];
+    controllers: [
+        {
+            battery: number;
+            isAvailable: boolean;
+            isCharging: boolean | undefined;
+        },
+        {
+            battery: number;
+            isAvailable: boolean;
+            isCharging: boolean | undefined;
+        }
+    ];
     devices: Array<ISmartDeviceInfo | undefined>;
     isFieldControllerConnected: boolean;
     matchMode: MatchMode;
@@ -80,6 +94,9 @@ export declare class V5SerialDeviceState {
 }
 export declare class V5Brain {
     private readonly state;
+    private readonly batteryFacade;
+    private readonly buttonFacade;
+    private readonly settingsFacade;
     constructor(state: V5SerialDeviceState);
     get isRunningProgram(): boolean;
     get activeProgram(): number;
@@ -160,6 +177,11 @@ export declare class V5Controller {
     get batteryPercent(): number;
     get isMasterController(): boolean;
     get isAvailable(): boolean;
+    /**
+     * Whether the controller is charging. The V5 system-status response only
+     * reports this state for the primary controller, so the partner controller
+     * returns `undefined`.
+     */
     get isCharging(): boolean | undefined;
 }
 export declare class V5SmartDevice {

package/dist/VexError.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="dom-serial" preserve="true" />
+import { type AckType } from "./Vex.js";
 /**
  * Typed error hierarchy for the serial protocol package.
  *
@@ -10,6 +12,7 @@ export type VexSerialErrorKind = "not-connected" | "invalid-argument" | "protoco
 /** Base class for every failure surfaced by the serial package. */
 export declare class VexSerialError extends Error {
     readonly kind: VexSerialErrorKind;
+    readonly ackType: AckType | undefined;
     constructor(kind: VexSerialErrorKind, message: string);
 }
 /** No connection is currently open to a device. */
@@ -22,7 +25,8 @@ export declare class VexInvalidArgumentError extends VexSerialError {
 }
 /** The device refused, timed out, or replied unexpectedly to a command. */
 export declare class VexProtocolError extends VexSerialError {
-    constructor(message: string);
+    readonly ackType: AckType | undefined;
+    constructor(message: string, ackType?: AckType);
 }
 /** A file-transfer handshake, read, write, or exit failed. */
 export declare class VexTransferError extends VexSerialError {

package/dist/VexEvent.d.ts

@@ -1,16 +1,20 @@
-export declare class VexEventEmitter {
-    handlerMap: Map<string | symbol, Array<(...args: unknown[]) => void>>;
+type EventName = string | symbol;
+type EventMapKey<TEvents> = Extract<keyof TEvents, EventName>;
+type EventListener<TValue> = (data: TValue) => void;
+export declare class VexEventEmitter<TEvents extends object = Record<EventName, unknown>> {
+    handlerMap: Map<EventName, Array<EventListener<unknown>>>;
     constructor();
-    on(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    remove(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    emit(eventName: string | symbol, data: unknown): void;
+    on<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    remove<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    emit<K extends EventMapKey<TEvents>>(eventName: K, data: TEvents[K]): void;
     clearListeners(): void;
 }
-export declare class VexEventTarget {
-    emitter: VexEventEmitter;
+export declare class VexEventTarget<TEvents extends object = Record<EventName, unknown>> {
+    emitter: VexEventEmitter<TEvents>;
     constructor();
-    emit(eventName: string | symbol, data: unknown): void;
-    on(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    remove(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
+    emit<K extends EventMapKey<TEvents>>(eventName: K, data: TEvents[K]): void;
+    on<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    remove<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
     clearListeners(): void;
 }
+export {};

package/dist/VexFirmware.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import type { V5SerialDeviceState } from "./VexDeviceState.js";
 import { VexSerialError } from "./VexError.js";
 import { ResultAsync } from "neverthrow";
@@ -36,10 +37,12 @@ export declare function sleepUntil(f: () => boolean, timeout: number, interval?:
  * when `ms` is negative.
  */
 export declare function sleep(ms: number): ResultAsync<void, VexSerialError>;
+type FirmwareProgressCallback = (state: string, current: number, total: number) => void;
 /**
  * Upload a VEXos firmware archive to a connected brain. Network and
  * archive validation failures are returned as {@link VexSerialError}
  * values rather than thrown; a device that refuses a step or a missing
- * connection surfaces as {@link VexProtocolError} / {@link VexNotConnectedError}.
+ * connection surfaces as {@link VexFirmwareError} / {@link VexNotConnectedError}.
  */
-export declare function uploadFirmware(state: V5SerialDeviceState, publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+export declare function uploadFirmware(state: V5SerialDeviceState, publicUrl?: string, usingVersion?: string, progressCallback?: FirmwareProgressCallback): ResultAsync<boolean, VexSerialError>;
+export {};

package/dist/VexFirmwareVersion.d.ts

@@ -1,55 +1,16 @@
-/**
- * This is a class to make it easier to handle passing the VEXos version
- * information around in the application. This provides ways to get any
- * form of the string representation and quickly compare versions.
- */
 export declare class VexFirmwareVersion {
-    major: number;
-    minor: number;
-    build: number;
-    beta: number;
+    readonly major: number;
+    readonly minor: number;
+    readonly build: number;
+    readonly beta: number;
     constructor(major: number, minor: number, build: number, beta: number);
-    /**
-     * Take a a string of MAJOR.MINOR.BUILD.bBETA and converts it to a
-     * VexFirmwareVersion instance
-     * @param version the string to process
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromString(version: string): VexFirmwareVersion;
-    /**
-     * Take a a Uint8Array and converts it to a VexFirmwareVersion instance
-     * @param data the array to process
-     * @param offset the offset to start at
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromUint8Array(data: Uint8Array, offset?: number, reverse?: boolean): VexFirmwareVersion;
     static allZero(): VexFirmwareVersion;
-    /**
-     * Take a a string of MAJOR_MINOR_BUILD_BETA and converts it to a
-     * VexFirmwareVersion instance
-     * @param version the string to process
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromCatalogString(version: string): VexFirmwareVersion;
     isBeta(): boolean;
-    /**
-     * returns version as Uint Array
-     */
     toUint8Array(reverse?: boolean): Uint8Array;
-    /**
-     * returns version as major.minor.build
-     */
     toUserString(): string;
-    /**
-     * returns version as ${major}.${minor}.{build}.b${beta}
-     */
     toInternalString(): string;
-    /**
-     * compares this version to the provided version.
-     * * if this < b: negative
-     * * if this = b: 0
-     * * if this > b: positive
-     * @param that the version to compare again
-     */
     compare(that: VexFirmwareVersion): number;
 }

package/dist/VexIniConfig.d.ts

@@ -20,7 +20,6 @@ export declare class ProgramIniConfig {
     config: Record<number, string>;
     controller1: Record<string, string>;
     controller2: Record<string, string>;
-    constructor();
     setProgramDate(date: Date): void;
     createIni(): string;
     dec2(value: number): string;

package/dist/VexPacketBase.d.ts

@@ -1,18 +1,21 @@
 import { AckType, type DataArray } from "./Vex.js";
 import type { PacketEncoder } from "./VexPacketEncoder.js";
 export declare abstract class Packet {
+    /** Raw bytes sent to or received from the device. */
     data: Uint8Array;
     static ENCODER: PacketEncoder;
     constructor(rawData: DataArray);
 }
 export declare class DeviceBoundPacket extends Packet {
-    get commandId(): number;
-    get commandExtendedId(): number | undefined;
     static COMMAND_ID: number;
     static COMMAND_EXTENDED_ID: number | undefined;
+    get commandId(): number;
+    get commandExtendedId(): number | undefined;
     constructor(payload?: Uint8Array);
 }
 export declare class HostBoundPacket extends Packet {
+    static COMMAND_ID: number;
+    static COMMAND_EXTENDED_ID: number | undefined;
     ack: AckType;
     payloadSize: number;
     ackIndex: number;

package/dist/VexPacketCore.d.ts

@@ -0,0 +1,5 @@
+export * from "./VexCRC.js";
+export * from "./VexFirmwareVersion.js";
+export * from "./VexPacketBase.js";
+export * from "./VexPacketEncoder.js";
+export * from "./VexPacketView.js";

package/dist/VexPacketEncoder.d.ts

@@ -8,46 +8,29 @@ export declare class PacketEncoder {
     static J2000_EPOCH: number;
     vexVersion: number;
     crcgen: CrcGenerator;
-    allPacketsTable: Record<string, typeof HostBoundPacket>;
+    allPacketsTable: Map<number, Map<number | undefined, typeof HostBoundPacket>>;
     static getInstance(): PacketEncoder;
     private constructor();
-    /**
-     * Create the vex CDC header
-     * @param buf the bytes to send
-     */
+    /** Register reply packet classes without retaining an entire module object. */
+    registerPacketTypes(types: Iterable<typeof HostBoundPacket>): void;
+    /** Look up the reply class registered for a command ID pair. */
+    getPacketType(commandId: number | undefined, commandExtendedId: number | undefined): typeof HostBoundPacket | undefined;
+    /** Create the vex CDC header. */
     createHeader(buf: ArrayBuffer | undefined): Uint8Array;
-    /**
-     * Create the vex CDC simple message
-     * @param cmd the CDC command byte
-     */
+    /** Create a simple CDC message. */
     cdcCommand(cmd: number): Uint8Array;
-    /**
-     * Create the vex CDC simple message
-     * @param cmd the CDC command byte
-     * @param data the data to send
-     */
+    /** Create a simple CDC message carrying data. */
     cdcCommandWithData(cmd: number, data: Uint8Array): Uint8Array;
-    /**
-     * Create the vex CDC extended message
-     * @param cmd the CDC command byte
-     * @param ext the CDC extended command byte
-     * @return a message
-     */
+    /** Create a CDC2 (extended) message with no payload. */
     cdc2Command(cmd: number, ext: number): Uint8Array;
     /**
-     * Calculate buffer length for new CDC extended command
-     * @param data the CDC extended command payload
-     * @returns the required buffer length of the command message
+     * Buffer length for a CDC2 command: header + command byte + function
+     * byte + length byte (two bytes when payload > 127) + payload + CRC16.
      */
     cdc2CommandBufferLength(data: Uint8Array): number;
-    /**
-     * Create the vex CDC extended message with some data
-     * @param cmd the CDC command byte
-     * @param ext the CDC extended command byte
-     * @param data the CDC extended command payload
-     * @return a message
-     */
+    /** Create a CDC2 (extended) message carrying a payload. */
     cdc2CommandWithData(cmd: number, ext: number, data: Uint8Array): Uint8Array;
+    private appendCrc16;
     validateHeader(data: Uint8Array): boolean;
     validateMessageCdc(data: Uint8Array): boolean;
     getPayloadSize(data: Uint8Array): number;