@v5x/serial 0.5.4 → 0.5.5

package/README.md

@@ -2,6 +2,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.
@@ -14,16 +16,27 @@ bun add @v5x/serial
 
 ## Usage
 
+Every public async API returns a `neverthrow` `ResultAsync` whose error channel
+is a `VexSerialError`. Inspect the result with `.isOk()` / `.isErr()` or
+`.match()` instead of using `try`/`catch`:
+
 ```ts
 import { V5SerialConnection } from "@v5x/serial";
 
 const connection = new V5SerialConnection(navigator.serial);
 
-const connected = await connection.open();
+const opened = await connection.open();
+if (opened.isErr()) {
+  console.error(opened.error); // VexSerialError with a stable .kind
+  return;
+}
+// opened.value: true | false | undefined (opened / busy / no port selected)
 
-if (connected) {
-  const status = await connection.getSystemStatus();
-  console.log(status);
+const status = await connection.getSystemStatus();
+if (status.isOk()) {
+  console.log(status.value);
+} else {
+  console.error(status.error.kind, status.error.message);
 }
 ```
 
@@ -31,20 +44,73 @@ Web Serial is browser-only and requires a secure context, such as HTTPS or
 `localhost`. The user must grant access to a serial device before the connection
 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.
+
 ## Common Exports
 
 - `V5SerialConnection` for opening and managing a serial connection.
 - `V5SerialDevice` for higher-level device operations.
+- `VexSerialError` and its subclasses (`VexNotConnectedError`,
+  `VexProtocolError`, `VexTransferError`, `VexDownloadError`,
+  `VexFirmwareError`, `VexIoError`, `VexInvalidArgumentError`) for typed failure
+  handling. Each carries a stable `kind` discriminator.
 - `PacketEncoder`, `DeviceBoundPacket`, and `HostBoundPacket` for low-level
   protocol work.
 - `ProgramIniConfig` for creating VEX program metadata.
 - Protocol enums and types from `Vex.ts`.
 
+## 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:
+
+```ts
+const r = await device.setMatchMode("disabled");
+if (r.isErr()) console.error(r.error);
+
+await device.brain.setActiveProgram(1).mapErr((e) => console.error(e));
+await device.brain.setActiveProgram(0);
+```
+
+The former `device.matchMode = value` and
+`device.brain.activeProgram = value` setters were fire-and-forget and have been
+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)`).
+
+## Transfers and timeouts
+
+Bulk uploads and downloads on one `V5SerialConnection` are queued and run one at
+a time. Await each high-level transfer; do not interleave manual low-level file
+packets. A `V5SerialDevice` pauses its background refresh while a high-level
+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`
+(or a related `VexSerialError` subclass) through the `Result` error channel; it
+does not cancel work already running on the device.
+
+User QSPI files are limited to `USER_FLASH_MAX_FILE_SIZE` (2 MiB). Firmware
+updates download an archive containing non-empty `BOOT.bin` and `assets.bin`
+images whose sizes must match the archive metadata. Firmware writes can render a
+device unusable if power or communication is interrupted; keep them out of
+normal application flows and validate the target VEXos version first.
+
 ## Build
 
 ```sh
 bun run build
 ```
 
-The build emits JavaScript bundles to `dist/` and TypeScript declarations to
-`dts/` and `index.d.ts`.
+The build emits JavaScript bundles and TypeScript declarations under `dist/`.

package/dist/Vex.d.ts

@@ -1,5 +1,5 @@
-import { type VexFirmwareVersion } from "./VexFirmwareVersion";
-import { type HostBoundPacket } from "./VexPacket";
+import { type VexFirmwareVersion } from "./VexFirmwareVersion.js";
+import { type HostBoundPacket } from "./VexPacket.js";
 export declare const USER_PROG_CHUNK_SIZE = 4096;
 export declare const USER_FLASH_START = 50331648;
 export declare const USER_FLASH_SYS_CODE_START = 54525952;
@@ -86,8 +86,8 @@ export declare enum FileDownloadTarget {
     FILE_TARGET_VBUF = 3,
     FILE_TARGET_DDRC = 4,
     FILE_TARGET_DDRE = 5,
-    FILE_TARGET_FLASH = 6,
-    FILE_TARGET_RADIO = 7,
+    FILE_TARGET_FLASH = 6,// for IQ2
+    FILE_TARGET_RADIO = 7,// for IQ2
     FILE_TARGET_A1 = 13,
     FILE_TARGET_B1 = 14,
     FILE_TARGET_B2 = 15

package/dist/VexCRC.d.ts

@@ -1,5 +1,4 @@
 export declare class CrcGenerator {
-    crc16Table: Uint32Array;
     crc32Table: Uint32Array;
     static POLYNOMIAL_CRC32: number;
     static POLYNOMIAL_CRC16: number;

package/dist/VexConnection.d.ts

@@ -1,9 +1,10 @@
-/// <reference types="dom-serial" />
-import { AckType, FileDownloadTarget, type IFileBasicInfo, type IFileWriteRequest, type IPacketCallback, type MatchMode, type SlotNumber, type SelectDashScreen } from "./Vex";
-import { VexEventTarget } from "./VexEvent";
-import { type ProgramIniConfig } from "./VexIniConfig";
-import { MatchStatusReplyD2HPacket, DeviceBoundPacket, MatchModeReplyD2HPacket, GetSystemStatusReplyD2HPacket, type HostBoundPacket, Query1ReplyD2HPacket, LoadFileActionReplyD2HPacket, GetSystemFlagsReplyD2HPacket, GetRadioStatusReplyD2HPacket, GetDeviceStatusReplyD2HPacket, SendDashTouchReplyD2HPacket, type SelectDashReplyD2HPacket } from "./VexPacket";
-import { type VexFirmwareVersion } from "./VexFirmwareVersion";
+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";
+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";
 /**
  * A connection to a V5 device.
  * Emit events: connected, disconnected
@@ -15,31 +16,88 @@ export declare class VexSerialConnection extends VexEventTarget {
     port: SerialPort | undefined;
     serial: Serial;
     callbacksQueue: IPacketCallback[];
+    private _onPortDisconnect;
+    private _closePromise;
+    private _wasConnected;
+    protected fileTransferTail: Promise<unknown>;
+    protected fileTransferDepth: number;
     get isConnected(): boolean;
+    get isFileTransferring(): boolean;
     constructor(serial: Serial);
     close(): Promise<void>;
-    open(use?: number | undefined, askUser?: boolean): Promise<boolean | undefined>;
+    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(use?: number | undefined, askUser?: boolean): ResultAsync<boolean | undefined, 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>;
     protected startReader(): Promise<void>;
-    query1(): Promise<Query1ReplyD2HPacket | null>;
-    getSystemVersion(): Promise<VexFirmwareVersion | null>;
+    query1(): ResultAsync<Query1ReplyD2HPacket, VexSerialError>;
+    getSystemVersion(): ResultAsync<VexFirmwareVersion, VexSerialError>;
 }
 export declare class V5SerialConnection extends VexSerialConnection {
     filters: SerialPortFilter[];
-    getDeviceStatus(): Promise<GetDeviceStatusReplyD2HPacket | null>;
-    getRadioStatus(): Promise<GetRadioStatusReplyD2HPacket | null>;
-    getSystemFlags(): Promise<GetSystemFlagsReplyD2HPacket | null>;
-    getSystemStatus(timeout?: number): Promise<GetSystemStatusReplyD2HPacket | null>;
-    getMatchStatus(): Promise<MatchStatusReplyD2HPacket | null>;
-    uploadProgramToDevice(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    downloadFileToHost(request: IFileBasicInfo, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): Promise<Uint8Array>;
-    uploadFileToDevice(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): Promise<boolean>;
-    setMatchMode(mode: MatchMode): Promise<MatchModeReplyD2HPacket | null>;
-    loadProgram(value: SlotNumber | string): Promise<LoadFileActionReplyD2HPacket | null>;
-    stopProgram(): Promise<LoadFileActionReplyD2HPacket | null>;
-    mockTouch(x: number, y: number, press: boolean): Promise<SendDashTouchReplyD2HPacket | null>;
-    /** @param port untested */
-    openScreen(screen: number | SelectDashScreen, port: number): Promise<SelectDashReplyD2HPacket | null>;
+    /**
+     * Serialize every transfer that touches the device's file-transfer mode
+     * through a single connection-level queue. Each call returns the prior
+     * tail and chains after it, so transfers always execute in request
+     * order without packet interleaving.
+     */
+    withFileTransfer<T>(operation: () => Promise<T>): Promise<T>;
+    getDeviceStatus(): ResultAsync<GetDeviceStatusReplyD2HPacket, VexSerialError>;
+    getRadioStatus(): ResultAsync<GetRadioStatusReplyD2HPacket, VexSerialError>;
+    getSystemFlags(): ResultAsync<GetSystemFlagsReplyD2HPacket, VexSerialError>;
+    getSystemStatus(timeout?: number): ResultAsync<GetSystemStatusReplyD2HPacket, VexSerialError>;
+    getMatchStatus(): ResultAsync<MatchStatusReplyD2HPacket, VexSerialError>;
+    /**
+     * Upload an entire program (INI, optional cold binary, and the user
+     * binary) under a single connection-level transaction so that no other
+     * file-transfer request can interleave with the multi-file write.
+     */
+    uploadProgramToDevice(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    private _uploadProgramToDevice;
+    downloadFileToHost(request: IFileBasicInfo, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
+    /**
+     * Run a download without acquiring the connection-level transfer lock.
+     * Intended for callers that already hold a transaction (such as
+     * `captureScreen`) and need to issue the download within a larger
+     * queued operation.
+     */
+    downloadFileToHostUnlocked(request: IFileBasicInfo, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
+    private _downloadFileToHostUnlocked;
+    uploadFileToDevice(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    uploadFileToDeviceUnlocked(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): Promise<Result<boolean, VexSerialError>>;
+    /**
+     * Erase a single file under a single transfer-mode session, exiting
+     * file-transfer mode in a `finally` block regardless of how the
+     * operation completes.
+     */
+    removeFile(request: IFileBasicInfo | string): ResultAsync<void, VexSerialError>;
+    /**
+     * Erase every file in the user vendor namespace under a single
+     * transfer-mode session.
+     */
+    removeAllFiles(): ResultAsync<void, VexSerialError>;
+    /**
+     * Issue the screen-capture command and validate that the device
+     * acknowledged it. Callers must inspect the returned packet (or the
+     * error result on NACK) before downloading the framebuffer so that a
+     * rejected request performs no download.
+     */
+    captureScreenSetup(): ResultAsync<ScreenCaptureReplyD2HPacket, VexSerialError>;
+    captureScreen(progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
+    private _captureScreen;
+    setMatchMode(mode: MatchMode): ResultAsync<MatchModeReplyD2HPacket, VexSerialError>;
+    runProgram(value: SlotNumber | string): ResultAsync<LoadFileActionReplyD2HPacket, VexSerialError>;
+    loadProgram(value: SlotNumber | string): ResultAsync<LoadFileActionReplyD2HPacket, VexSerialError>;
+    stopProgram(): ResultAsync<LoadFileActionReplyD2HPacket, VexSerialError>;
+    mockTouch(x: number, y: number, press: boolean): ResultAsync<SendDashTouchReplyD2HPacket, VexSerialError>;
+    openScreen(screen: number | SelectDashScreen, port: number): ResultAsync<SelectDashReplyD2HPacket, VexSerialError>;
 }

package/dist/VexDevice.d.ts

@@ -1,158 +1,20 @@
-/// <reference types="dom-serial" />
-import { type MatchMode, SerialDeviceType, type ISmartDeviceInfo, SmartDeviceType, FileVendor, type IProgramInfo, type IFileHandle, FileDownloadTarget, type IFileBasicInfo, type IFileWriteRequest, RadioChannelType } from "./Vex";
-import { V5SerialConnection } from "./VexConnection";
-import { VexEventTarget } from "./VexEvent";
-import { VexFirmwareVersion } from "./VexFirmwareVersion";
-import { type ProgramIniConfig } from "./VexIniConfig";
-export declare function downloadFileFromInternet(link: string): Promise<ArrayBuffer>;
-export declare function sleepUntilAsync(f: () => Promise<boolean>, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleepUntil(f: () => boolean, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleep(ms: number): Promise<unknown>;
-export declare abstract class VexSerialDevice extends VexEventTarget {
-    connection: V5SerialConnection | undefined;
-    defaultSerial: Serial;
-    get isConnected(): boolean;
-    get deviceType(): SerialDeviceType | undefined;
-    constructor(defaultSerial: Serial);
-    abstract connect(conn?: V5SerialConnection): Promise<boolean>;
-    abstract disconnect(): void;
-}
-declare class V5SerialDeviceState {
-    _instance: V5SerialDevice;
-    _isFileTransferring: boolean;
-    brain: {
-        activeProgram: number;
-        battery: {
-            batteryPercent: number;
-            isCharging: boolean;
-        };
-        button: {
-            isPressed: boolean;
-            isDoublePressed: boolean;
-        };
-        cpu0Version: VexFirmwareVersion;
-        cpu1Version: VexFirmwareVersion;
-        isAvailable: boolean;
-        settings: {
-            isScreenReversed: boolean;
-            isWhiteTheme: boolean;
-            usingLanguage: number;
-        };
-        systemVersion: VexFirmwareVersion;
-        uniqueId: number;
-    };
-    controllers: ({
-        battery: number;
-        isAvailable: boolean;
-        isCharging: boolean;
-    } | {
-        battery: number;
-        isAvailable: boolean;
-        isCharging?: undefined;
-    })[];
-    devices: Array<ISmartDeviceInfo | undefined>;
-    isFieldControllerConnected: boolean;
-    matchMode: MatchMode;
-    radio: {
-        channel: number;
-        isAvailable: boolean;
-        isConnected: boolean;
-        isVexNet: boolean;
-        isRadioData: boolean;
-        latency: number;
-        signalQuality: number;
-        signalStrength: number;
-    };
-    constructor(instance: V5SerialDevice);
-}
-export declare class V5Brain {
-    private readonly state;
-    constructor(state: V5SerialDeviceState);
-    get isRunningProgram(): boolean;
-    get activeProgram(): number;
-    set activeProgram(value: number);
-    get battery(): V5Battery;
-    get button(): V5BrainButton;
-    get cpu0Version(): VexFirmwareVersion;
-    get cpu1Version(): VexFirmwareVersion;
-    get isAvailable(): boolean;
-    get settings(): V5BrainSettings;
-    get systemVersion(): VexFirmwareVersion;
-    get uniqueId(): number;
-    getValue(key: string): Promise<string | undefined>;
-    setValue(key: string, value: string): Promise<boolean>;
-    listFiles(vendor?: FileVendor): Promise<IFileHandle[] | undefined>;
-    listProgram(): Promise<IProgramInfo[] | undefined>;
-    readFile(request: IFileBasicInfo | string, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
-    removeFile(request: IFileBasicInfo | string): Promise<boolean | undefined>;
-    removeAllFiles(): Promise<boolean | undefined>;
-    uploadFirmware(publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    uploadProgram(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    writeFile(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): Promise<boolean | undefined>;
-    /**
-     *
-     * @param progressCallback Informs the progress of the download.
-     * @returns array of bytes where each pixel is represented by 3 consecutive bytes (rgb).
-     * This array's length is 272 width * 480 height * 3 channels = 391680 bytes.
-     */
-    captureScreen(progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
-}
-export declare class V5Battery {
-    private readonly state;
-    constructor(state: V5SerialDeviceState);
-    get batteryPercent(): number;
-    get isCharging(): boolean;
-}
-export declare class V5BrainButton {
-    private readonly state;
-    constructor(state: V5SerialDeviceState);
-    get isPressed(): boolean;
-    get isDoublePressed(): boolean;
-}
-export declare class V5BrainSettings {
-    private readonly state;
-    constructor(state: V5SerialDeviceState);
-    get isScreenReversed(): boolean;
-    get isWhiteTheme(): boolean;
-    get usingLanguage(): number;
-}
-export declare class V5Controller {
-    private readonly state;
-    private readonly controllerIndex;
-    constructor(state: V5SerialDeviceState, controllerIndex: number);
-    get batteryPercent(): number;
-    get isMasterController(): boolean;
-    get isAvailable(): boolean;
-    get isCharging(): boolean | undefined;
-}
-export declare class V5SmartDevice {
-    private readonly state;
-    private readonly deviceIndex;
-    constructor(state: V5SerialDeviceState, index: number);
-    protected getDeviceInfo(): ISmartDeviceInfo | undefined;
-    get isAvailable(): boolean;
-    get port(): number;
-    get type(): SmartDeviceType;
-    get version(): number;
-}
-export declare class V5Radio {
-    private readonly state;
-    constructor(state: V5SerialDeviceState);
-    get channel(): number;
-    get isAvailable(): boolean;
-    get isConnected(): boolean;
-    get isVexNet(): boolean;
-    get isRadioData(): boolean;
-    get latency(): number;
-    changeChannel(channel: RadioChannelType): Promise<boolean>;
-}
+import { type MatchMode } from "./Vex.js";
+import { V5SerialConnection } from "./VexConnection.js";
+import { V5Brain, V5Controller, V5Radio, V5SerialDeviceState, V5SmartDevice, VexSerialDevice } from "./VexDeviceState.js";
+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 declare class V5SerialDevice extends VexSerialDevice {
     autoReconnect: boolean;
     autoRefresh: boolean;
     pauseRefreshOnFileTransfer: boolean;
     protected _isReconnecting: boolean;
+    private _isDisconnecting;
     private _refreshInterval;
     state: V5SerialDeviceState;
+    private _disposed;
+    private _refreshGeneration;
     constructor(defaultSerial: Serial);
     get isV5Controller(): boolean;
     get brain(): V5Brain;
@@ -160,18 +22,42 @@ export declare class V5SerialDevice extends VexSerialDevice {
     get devices(): V5SmartDevice[];
     get isFieldControllerConnected(): boolean;
     get matchMode(): MatchMode;
+    /**
+     * @deprecated Setting this property dispatches a fire-and-forget
+     * request whose result cannot be observed. Use {@link setMatchMode}
+     * instead, which returns a {@link ResultAsync} that resolves to an
+     * error result when the device refuses or is disconnected.
+     */
     set matchMode(value: MatchMode);
+    /**
+     * Update the match mode and resolve only after the device
+     * acknowledges the command. Resolves to an error result when the
+     * device NACKs, the request times out, or no connection is open.
+     */
+    setMatchMode(mode: MatchMode): ResultAsync<void, VexSerialError>;
     get radio(): V5Radio;
-    mockTouch(x: number, y: number, press: boolean): Promise<boolean>;
-    connect(conn?: V5SerialConnection): Promise<boolean>;
+    mockTouch(x: number, y: number, press: boolean): ResultAsync<void, VexSerialError>;
+    connect(conn?: V5SerialConnection): ResultAsync<void, VexSerialError>;
+    private _connect;
     disconnect(): Promise<void>;
     dispose(): Promise<void>;
     /**
-     * @param timeout defaults to 0. If timeout is 0, then it will attempt to reconnect forever
-     * @returns
+     * @param timeout defaults to 0. If timeout is 0, then it will attempt to reconnect forever.
      */
-    reconnect(timeout?: number): Promise<boolean>;
+    reconnect(timeout?: number): ResultAsync<void, VexSerialError>;
+    private _reconnect;
+    private waitForReconnectToFinish;
     private doAfterConnect;
-    refresh(): Promise<boolean>;
+    /**
+     * Refresh the high-level device snapshot. All required replies are
+     * collected before any public state is mutated, so callers never see
+     * a half-updated view. A failed or missing reply resolves to an `Ok`
+     * of `false` (the previous snapshot is preserved and only the
+     * `isAvailable` flag is updated) so transient communication loss does
+     * not surface as a hard error result.
+     */
+    refresh(): ResultAsync<boolean, VexSerialError>;
+    private _refresh;
+    private _buildSnapshot;
+    private _applySnapshotIfCurrent;
 }
-export {};

package/{dts/VexDevice.d.ts → dist/VexDeviceState.d.ts}

@@ -1,25 +1,38 @@
-/// <reference types="dom-serial" />
-import { type MatchMode, SerialDeviceType, type ISmartDeviceInfo, SmartDeviceType, FileVendor, type IProgramInfo, type IFileHandle, FileDownloadTarget, type IFileBasicInfo, type IFileWriteRequest, RadioChannelType } from "./Vex";
-import { V5SerialConnection } from "./VexConnection";
-import { VexEventTarget } from "./VexEvent";
-import { VexFirmwareVersion } from "./VexFirmwareVersion";
-import { type ProgramIniConfig } from "./VexIniConfig";
-export declare function downloadFileFromInternet(link: string): Promise<ArrayBuffer>;
-export declare function sleepUntilAsync(f: () => Promise<boolean>, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleepUntil(f: () => boolean, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleep(ms: number): Promise<unknown>;
+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";
+import { VexFirmwareVersion } from "./VexFirmwareVersion.js";
+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 {
     connection: V5SerialConnection | undefined;
     defaultSerial: Serial;
     get isConnected(): boolean;
     get deviceType(): SerialDeviceType | undefined;
     constructor(defaultSerial: Serial);
-    abstract connect(conn?: V5SerialConnection): Promise<boolean>;
-    abstract disconnect(): void;
+    abstract connect(conn?: V5SerialConnection): ResultAsync<void, VexSerialError>;
+    abstract disconnect(): Promise<void>;
 }
-declare class V5SerialDeviceState {
+export declare class V5SerialDeviceState {
     _instance: V5SerialDevice;
-    _isFileTransferring: boolean;
+    /**
+     * 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.
+     */
+    private refreshPauseDepth;
+    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.
+     */
+    withFileTransfer<T>(operation: () => PromiseLike<T>): Promise<T>;
     brain: {
         activeProgram: number;
         battery: {
@@ -70,7 +83,31 @@ export declare class V5Brain {
     constructor(state: V5SerialDeviceState);
     get isRunningProgram(): boolean;
     get activeProgram(): number;
+    /**
+     * @deprecated Setting this property dispatches a fire-and-forget
+     * request that cannot be awaited. Use {@link setActiveProgram}
+     * instead, which returns a {@link ResultAsync} that resolves to an
+     * error result when the device refuses or is disconnected.
+     */
     set activeProgram(value: number);
+    /**
+     * Load a program slot on the brain, or stop the currently running
+     * program when called with `0`. Resolves to an error result when the
+     * device refuses, the request times out, or no connection is open.
+     */
+    setActiveProgram(value: SlotNumber | 0): ResultAsync<void, VexSerialError>;
+    /**
+     * Request that the brain start running the program in the given slot.
+     * Resolves to an error result when the device refuses, the request
+     * times out, or no connection is open.
+     */
+    runProgram(slot: SlotNumber | string): ResultAsync<void, VexSerialError>;
+    /**
+     * Request that the brain stop the currently running program. Resolves
+     * to an error result when the device refuses, the request times out,
+     * or no connection is open.
+     */
+    stopProgram(): ResultAsync<void, VexSerialError>;
     get battery(): V5Battery;
     get button(): V5BrainButton;
     get cpu0Version(): VexFirmwareVersion;
@@ -79,23 +116,23 @@ export declare class V5Brain {
     get settings(): V5BrainSettings;
     get systemVersion(): VexFirmwareVersion;
     get uniqueId(): number;
-    getValue(key: string): Promise<string | undefined>;
-    setValue(key: string, value: string): Promise<boolean>;
-    listFiles(vendor?: FileVendor): Promise<IFileHandle[] | undefined>;
-    listProgram(): Promise<IProgramInfo[] | undefined>;
-    readFile(request: IFileBasicInfo | string, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
-    removeFile(request: IFileBasicInfo | string): Promise<boolean | undefined>;
-    removeAllFiles(): Promise<boolean | undefined>;
-    uploadFirmware(publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    uploadProgram(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    writeFile(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): Promise<boolean | undefined>;
+    getValue(key: string): ResultAsync<string | undefined, VexSerialError>;
+    setValue(key: string, value: string): ResultAsync<void, VexSerialError>;
+    listFiles(vendor?: FileVendor): ResultAsync<IFileHandle[], VexSerialError>;
+    listProgram(): ResultAsync<IProgramInfo[], VexSerialError>;
+    readFile(request: IFileBasicInfo | string, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
+    removeFile(request: IFileBasicInfo | string): ResultAsync<void, VexSerialError>;
+    removeAllFiles(): ResultAsync<void, VexSerialError>;
+    uploadFirmware(publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    uploadProgram(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    writeFile(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
     /**
      *
      * @param progressCallback Informs the progress of the download.
      * @returns array of bytes where each pixel is represented by 3 consecutive bytes (rgb).
      * This array's length is 272 width * 480 height * 3 channels = 391680 bytes.
      */
-    captureScreen(progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
+    captureScreen(progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
 }
 export declare class V5Battery {
     private readonly state;
@@ -144,34 +181,5 @@ export declare class V5Radio {
     get isVexNet(): boolean;
     get isRadioData(): boolean;
     get latency(): number;
-    changeChannel(channel: RadioChannelType): Promise<boolean>;
-}
-export declare class V5SerialDevice extends VexSerialDevice {
-    autoReconnect: boolean;
-    autoRefresh: boolean;
-    pauseRefreshOnFileTransfer: boolean;
-    protected _isReconnecting: boolean;
-    private _refreshInterval;
-    state: V5SerialDeviceState;
-    constructor(defaultSerial: Serial);
-    get isV5Controller(): boolean;
-    get brain(): V5Brain;
-    get controllers(): [V5Controller, V5Controller];
-    get devices(): V5SmartDevice[];
-    get isFieldControllerConnected(): boolean;
-    get matchMode(): MatchMode;
-    set matchMode(value: MatchMode);
-    get radio(): V5Radio;
-    mockTouch(x: number, y: number, press: boolean): Promise<boolean>;
-    connect(conn?: V5SerialConnection): Promise<boolean>;
-    disconnect(): Promise<void>;
-    dispose(): Promise<void>;
-    /**
-     * @param timeout defaults to 0. If timeout is 0, then it will attempt to reconnect forever
-     * @returns
-     */
-    reconnect(timeout?: number): Promise<boolean>;
-    private doAfterConnect;
-    refresh(): Promise<boolean>;
+    changeChannel(channel: RadioChannelType): ResultAsync<void, VexSerialError>;
 }
-export {};