@v5x/serial 0.5.6 → 0.5.7

package/README.md

@@ -29,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()) {
@@ -81,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
 
@@ -112,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/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";
@@ -34,17 +35,29 @@ export declare class VexSerialConnection extends VexEventTarget<VexSerialConnect
     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;
     /**
@@ -52,14 +65,31 @@ export declare class VexSerialConnection extends VexEventTarget<VexSerialConnect
      * `"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, ...).
+     * port fails to open (permissions, dead device, ...). Concurrent calls
+     * join the same open attempt and receive its result.
      */
     open(use?: number, askUser?: boolean): ResultAsync<OpenResult, VexSerialError>;
     private _open;
     writeDataAsync(rawData: DeviceBoundPacket | Uint8Array, timeout?: number): Promise<HostBoundPacket | ArrayBuffer | AckType>;
+    /**
+     * 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: Uint8Array, expectedSize: number): Promise<Uint8Array>;
+    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>;
 }
@@ -122,4 +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,6 +6,10 @@ 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;
     pauseRefreshOnFileTransfer: boolean;
@@ -13,16 +18,26 @@ export declare class V5SerialDevice extends VexSerialDevice {
     private _refreshInterval;
     state: V5SerialDeviceState;
     private _disposed;
+    private _lifecycleGeneration;
+    private _disconnectListener;
     private _refreshGeneration;
     private _autoRefresh;
+    private _refreshIntervalMs;
     private _isLastRefreshComplete;
     private readonly _brain;
     private readonly _controllers;
     private readonly _radio;
     private readonly _deviceFacades;
-    constructor(defaultSerial: Serial, autoRefresh?: boolean);
+    /**
+     * 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;
@@ -56,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";
@@ -64,11 +65,18 @@ export declare class V5SerialDeviceState {
         systemVersion: VexFirmwareVersion;
         uniqueId: number;
     };
-    controllers: {
-        battery: number;
-        isAvailable: boolean;
-        isCharging: boolean;
-    }[];
+    controllers: [
+        {
+            battery: number;
+            isAvailable: boolean;
+            isCharging: boolean | undefined;
+        },
+        {
+            battery: number;
+            isAvailable: boolean;
+            isCharging: boolean | undefined;
+        }
+    ];
     devices: Array<ISmartDeviceInfo | undefined>;
     isFieldControllerConnected: boolean;
     matchMode: MatchMode;
@@ -169,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,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { type AckType } from "./Vex.js";
 /**
  * Typed error hierarchy for the serial protocol package.

package/dist/VexEvent.d.ts

@@ -16,6 +16,5 @@ export declare class VexEventTarget<TEvents extends object = Record<EventName, u
     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;
-    private normalizeEventName;
 }
 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";

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

@@ -11,6 +11,8 @@ export declare class PacketEncoder {
     allPacketsTable: Map<number, Map<number | undefined, typeof HostBoundPacket>>;
     static getInstance(): PacketEncoder;
     private constructor();
+    /** 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. */

package/dist/VexPacketModels.d.ts

@@ -235,7 +235,7 @@ export declare class ReadFileReplyD2HPacket extends HostBoundPacket {
     static COMMAND_EXTENDED_ID: number;
     addr: number;
     length: number;
-    buf: ArrayBuffer;
+    buf: Uint8Array;
     constructor(data: DataArray);
 }
 export declare class LinkFileReplyD2HPacket extends HostBoundPacket {

package/dist/VexPacketRegistry.d.ts

@@ -0,0 +1,3 @@
+import { type HostBoundPacket } from "./VexPacketBase.js";
+/** Default reply registry used by the complete serial entry point. */
+export declare const defaultReplyPacketTypes: readonly (typeof HostBoundPacket)[];

package/dist/VexScreenCapture.d.ts

@@ -0,0 +1,2 @@
+export declare const SCREEN_CAPTURE_FRAMEBUFFER_SIZE: number;
+export declare function convertScreenCapture(framebuffer: Uint8Array): Uint8Array;

package/dist/VexTransfers.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="dom-serial" preserve="true" />
 import { type IFileBasicInfo, type IFileHandle, FileVendor, type IProgramInfo, type IFileWriteRequest, FileDownloadTarget } from "./Vex.js";
 import { type ProgramIniConfig } from "./VexIniConfig.js";
 import type { V5SerialDeviceState } from "./VexDeviceState.js";