react-native-web-serial-api 0.0.3 → 0.1.0

package/src/lib/dom-exception.ts

@@ -33,7 +33,7 @@ const DOM_EXCEPTION_CODES: Record<string, number> = {
 };
 
 const DOM_EXCEPTION_NAMES: Record<number, string> = Object.fromEntries(
-  Object.entries(DOM_EXCEPTION_CODES).map(([name, code]) => [code, name])
+  Object.entries(DOM_EXCEPTION_CODES).map(([name, code]) => [code, name]),
 );
 
 export interface DOMExceptionConstructor {
@@ -78,74 +78,134 @@ class DOMExceptionPolyfill extends Error {
   readonly name: string;
 
   // --- Static legacy-code constants ---
-  static readonly INDEX_SIZE_ERR             = 1  as const;
-  static readonly DOMSTRING_SIZE_ERR         = 2  as const;
-  static readonly HIERARCHY_REQUEST_ERR      = 3  as const;
-  static readonly WRONG_DOCUMENT_ERR         = 4  as const;
-  static readonly INVALID_CHARACTER_ERR      = 5  as const;
-  static readonly NO_DATA_ALLOWED_ERR        = 6  as const;
+  static readonly INDEX_SIZE_ERR = 1 as const;
+  static readonly DOMSTRING_SIZE_ERR = 2 as const;
+  static readonly HIERARCHY_REQUEST_ERR = 3 as const;
+  static readonly WRONG_DOCUMENT_ERR = 4 as const;
+  static readonly INVALID_CHARACTER_ERR = 5 as const;
+  static readonly NO_DATA_ALLOWED_ERR = 6 as const;
   static readonly NO_MODIFICATION_ALLOWED_ERR = 7 as const;
-  static readonly NOT_FOUND_ERR              = 8  as const;
-  static readonly NOT_SUPPORTED_ERR          = 9  as const;
-  static readonly INUSE_ATTRIBUTE_ERR        = 10 as const;
-  static readonly INVALID_STATE_ERR          = 11 as const;
-  static readonly SYNTAX_ERR                 = 12 as const;
-  static readonly INVALID_MODIFICATION_ERR   = 13 as const;
-  static readonly NAMESPACE_ERR              = 14 as const;
-  static readonly INVALID_ACCESS_ERR         = 15 as const;
-  static readonly VALIDATION_ERR             = 16 as const;
-  static readonly TYPE_MISMATCH_ERR          = 17 as const;
-  static readonly SECURITY_ERR               = 18 as const;
-  static readonly NETWORK_ERR                = 19 as const;
-  static readonly ABORT_ERR                  = 20 as const;
-  static readonly URL_MISMATCH_ERR           = 21 as const;
-  static readonly QUOTA_EXCEEDED_ERR         = 22 as const;
-  static readonly TIMEOUT_ERR                = 23 as const;
-  static readonly INVALID_NODE_TYPE_ERR      = 24 as const;
-  static readonly DATA_CLONE_ERR             = 25 as const;
+  static readonly NOT_FOUND_ERR = 8 as const;
+  static readonly NOT_SUPPORTED_ERR = 9 as const;
+  static readonly INUSE_ATTRIBUTE_ERR = 10 as const;
+  static readonly INVALID_STATE_ERR = 11 as const;
+  static readonly SYNTAX_ERR = 12 as const;
+  static readonly INVALID_MODIFICATION_ERR = 13 as const;
+  static readonly NAMESPACE_ERR = 14 as const;
+  static readonly INVALID_ACCESS_ERR = 15 as const;
+  static readonly VALIDATION_ERR = 16 as const;
+  static readonly TYPE_MISMATCH_ERR = 17 as const;
+  static readonly SECURITY_ERR = 18 as const;
+  static readonly NETWORK_ERR = 19 as const;
+  static readonly ABORT_ERR = 20 as const;
+  static readonly URL_MISMATCH_ERR = 21 as const;
+  static readonly QUOTA_EXCEEDED_ERR = 22 as const;
+  static readonly TIMEOUT_ERR = 23 as const;
+  static readonly INVALID_NODE_TYPE_ERR = 24 as const;
+  static readonly DATA_CLONE_ERR = 25 as const;
 
-  constructor(message = "", name = "Error") {
+  constructor(message = '', name = 'Error') {
     super(message);
 
     // Restore the correct prototype chain when transpiled to ES5
     Object.setPrototypeOf(this, new.target.prototype);
 
-    this.name    = name;
+    this.name = name;
     this.message = message;
-    this.code    = DOM_EXCEPTION_CODES[name] ?? 0;
+    this.code = DOM_EXCEPTION_CODES[name] ?? 0;
 
     // Provide a useful stack trace in V8 / SpiderMonkey
-    if (typeof (Error as any).captureStackTrace === "function") {
-      (Error as any).captureStackTrace(this, new.target);
+    const ErrorWithStack = Error as ErrorConstructor & {
+      captureStackTrace?: (
+        target: object,
+        constructorOpt?:
+          | ((...args: never[]) => unknown)
+          | (abstract new (
+              ...args: never[]
+            ) => unknown),
+      ) => void;
+    };
+    if (typeof ErrorWithStack.captureStackTrace === 'function') {
+      ErrorWithStack.captureStackTrace(this, new.target);
     }
   }
 
   /** Mirror static constants on the prototype (spec §3.1.2) */
-  get INDEX_SIZE_ERR()              { return 1; }
-  get DOMSTRING_SIZE_ERR()          { return 2; }
-  get HIERARCHY_REQUEST_ERR()       { return 3; }
-  get WRONG_DOCUMENT_ERR()          { return 4; }
-  get INVALID_CHARACTER_ERR()       { return 5; }
-  get NO_DATA_ALLOWED_ERR()         { return 6; }
-  get NO_MODIFICATION_ALLOWED_ERR() { return 7; }
-  get NOT_FOUND_ERR()               { return 8; }
-  get NOT_SUPPORTED_ERR()           { return 9; }
-  get INUSE_ATTRIBUTE_ERR()         { return 10; }
-  get INVALID_STATE_ERR()           { return 11; }
-  get SYNTAX_ERR()                  { return 12; }
-  get INVALID_MODIFICATION_ERR()    { return 13; }
-  get NAMESPACE_ERR()               { return 14; }
-  get INVALID_ACCESS_ERR()          { return 15; }
-  get VALIDATION_ERR()              { return 16; }
-  get TYPE_MISMATCH_ERR()           { return 17; }
-  get SECURITY_ERR()                { return 18; }
-  get NETWORK_ERR()                 { return 19; }
-  get ABORT_ERR()                   { return 20; }
-  get URL_MISMATCH_ERR()            { return 21; }
-  get QUOTA_EXCEEDED_ERR()          { return 22; }
-  get TIMEOUT_ERR()                 { return 23; }
-  get INVALID_NODE_TYPE_ERR()       { return 24; }
-  get DATA_CLONE_ERR()              { return 25; }
+  get INDEX_SIZE_ERR() {
+    return 1;
+  }
+  get DOMSTRING_SIZE_ERR() {
+    return 2;
+  }
+  get HIERARCHY_REQUEST_ERR() {
+    return 3;
+  }
+  get WRONG_DOCUMENT_ERR() {
+    return 4;
+  }
+  get INVALID_CHARACTER_ERR() {
+    return 5;
+  }
+  get NO_DATA_ALLOWED_ERR() {
+    return 6;
+  }
+  get NO_MODIFICATION_ALLOWED_ERR() {
+    return 7;
+  }
+  get NOT_FOUND_ERR() {
+    return 8;
+  }
+  get NOT_SUPPORTED_ERR() {
+    return 9;
+  }
+  get INUSE_ATTRIBUTE_ERR() {
+    return 10;
+  }
+  get INVALID_STATE_ERR() {
+    return 11;
+  }
+  get SYNTAX_ERR() {
+    return 12;
+  }
+  get INVALID_MODIFICATION_ERR() {
+    return 13;
+  }
+  get NAMESPACE_ERR() {
+    return 14;
+  }
+  get INVALID_ACCESS_ERR() {
+    return 15;
+  }
+  get VALIDATION_ERR() {
+    return 16;
+  }
+  get TYPE_MISMATCH_ERR() {
+    return 17;
+  }
+  get SECURITY_ERR() {
+    return 18;
+  }
+  get NETWORK_ERR() {
+    return 19;
+  }
+  get ABORT_ERR() {
+    return 20;
+  }
+  get URL_MISMATCH_ERR() {
+    return 21;
+  }
+  get QUOTA_EXCEEDED_ERR() {
+    return 22;
+  }
+  get TIMEOUT_ERR() {
+    return 23;
+  }
+  get INVALID_NODE_TYPE_ERR() {
+    return 24;
+  }
+  get DATA_CLONE_ERR() {
+    return 25;
+  }
 
   /** Canonical string representation */
   toString(): string {
@@ -153,9 +213,18 @@ class DOMExceptionPolyfill extends Error {
   }
 }
 
-export const DOMExceptionImpl = (globalThis as any).DOMException
-    ? (globalThis as any).DOMException as DOMExceptionConstructor
-    : DOMExceptionPolyfill as DOMExceptionConstructor;
+export const DOMExceptionImpl = (globalThis as Record<string, unknown>)
+  .DOMException
+  ? ((globalThis as Record<string, unknown>)
+      .DOMException as DOMExceptionConstructor)
+  : (DOMExceptionPolyfill as DOMExceptionConstructor);
 
-export { DOM_EXCEPTION_CODES, DOM_EXCEPTION_NAMES };
-export { DOMExceptionImpl as DOMException };
+export {
+  DOM_EXCEPTION_CODES,
+  DOM_EXCEPTION_NAMES,
+  DOMExceptionImpl as DOMException,
+  // Exported for testing: in environments that already provide a global
+  // DOMException (Node, modern browsers) the export above is the native one, so
+  // the polyfill class would otherwise never run.
+  DOMExceptionPolyfill,
+};

package/src/lib/event-target.ts

@@ -1,4 +1,3 @@
-
 export interface EventInit {
   bubbles?: boolean;
   cancelable?: boolean;
@@ -66,7 +65,7 @@ export class Event {
   }
 }
 
-type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+type Mutable<T> = {-readonly [P in keyof T]: T[P]};
 
 type EventListener = (event: Event) => void;
 
@@ -77,7 +76,7 @@ interface EventListenerObject {
 type EventListenerOrEventListenerObject = EventListener | EventListenerObject;
 
 type ListenerOptions =
-  | { once?: boolean; capture?: boolean; passive?: boolean }
+  | {once?: boolean; capture?: boolean; passive?: boolean}
   | boolean
   | undefined;
 
@@ -91,7 +90,23 @@ type SecretMap = Record<string, ListenerInfo[]>;
 
 const wm = new WeakMap<object, SecretMap>();
 
-function define<T extends object>(target: T, name: string, value: unknown): void {
+// Optional event-propagation parents. An event dispatched on a child also runs
+// its parent's listeners, while event.target stays the original child. This
+// models the W3C "SerialPort's parent is the Serial" relationship, so a
+// connect/disconnect observed on `serial` reports event.target === the
+// SerialPort (per the Web Serial spec and WPT).
+const eventParents = new WeakMap<EventTarget, EventTarget>();
+
+/** Make events dispatched on `child` also bubble to `parent`'s listeners. */
+export function setEventParent(child: EventTarget, parent: EventTarget): void {
+  eventParents.set(child, parent);
+}
+
+function define<T extends object>(
+  target: T,
+  name: string,
+  value: unknown,
+): void {
   Object.defineProperty(target, name, {
     configurable: true,
     writable: true,
@@ -102,13 +117,13 @@ function define<T extends object>(target: T, name: string, value: unknown): void
 function dispatch(this: Event, info: ListenerInfo): boolean {
   const options = info.options;
   const once =
-    typeof options === "object" && options !== null ? options.once : false;
+    typeof options === 'object' && options !== null ? options.once : false;
 
   if (once) {
     info.target.removeEventListener(this.type, info.listener);
   }
 
-  if (typeof info.listener === "function") {
+  if (typeof info.listener === 'function') {
     info.listener.call(info.target, this);
   } else {
     info.listener.handleEvent(this);
@@ -125,40 +140,50 @@ export class EventTarget {
   addEventListener(
     type: string,
     listener: EventListenerOrEventListenerObject,
-    options?: ListenerOptions
+    options?: ListenerOptions,
   ): void {
     const secret = wm.get(this)!;
-    const listeners: ListenerInfo[] = secret[type] ?? (secret[type] = []);
+    let listeners = secret[type];
+    if (!listeners) {
+      listeners = [];
+      secret[type] = listeners;
+    }
 
     for (let i = 0; i < listeners.length; i++) {
       if (listeners[i].listener === listener) return;
     }
 
-    listeners.push({ target: this, listener, options });
+    listeners.push({target: this, listener, options});
   }
 
   dispatchEvent(event: Event): boolean {
-    const secret = wm.get(this)!;
-    const listeners = secret[event.type];
-
-    if (listeners) {
-      define(event, "target", this);
-      define(event, "currentTarget", this);
-      listeners.slice(0).some(dispatch, event);
-      define(event, "target", null);
-      define(event, "currentTarget", null);
+    // The event's target is the node it was dispatched on; it then bubbles up
+    // the eventParents chain (currentTarget changes, target does not).
+    define(event, 'target', this);
+    let node: EventTarget | null = this;
+    while (node) {
+      const listeners = wm.get(node)?.[event.type];
+      if (listeners?.length) {
+        define(event, 'currentTarget', node);
+        listeners.slice(0).some(dispatch, event);
+      }
+      if (event.cancelBubble) break;
+      node = eventParents.get(node) ?? null;
     }
-
+    // Per the DOM, target persists after dispatch (a re-dispatch overwrites it
+    // at the top of this method); only currentTarget is cleared.
+    define(event, 'currentTarget', null);
     return true;
   }
 
   removeEventListener(
     type: string,
     listener: EventListenerOrEventListenerObject,
-    _options?: ListenerOptions
+    _options?: ListenerOptions,
   ): void {
     const secret = wm.get(this)!;
-    const listeners: ListenerInfo[] = secret[type] ?? (secret[type] = []);
+    const listeners = secret[type];
+    if (!listeners) return;
 
     for (let i = 0; i < listeners.length; i++) {
       if (listeners[i].listener === listener) {

package/src/lib/promise.ts

@@ -1,19 +1,19 @@
 type DeferredPromise<T> = {
   promise: Promise<T>;
   resolve: (value?: T) => void;
-  reject: (reason?: any) => void;
+  reject: (reason?: unknown) => void;
 };
 
 /**
  * @returns An object containing a promise and its resolve/reject methods.
  */
 export function createDeferredPromise<T>(): DeferredPromise<T> {
-  let res: any;
-  let rej: any;
+  let res: unknown;
+  let rej: unknown;
   const promise = new Promise<T>((resolve, reject) => {
-    res = resolve
-    rej = reject
-  })
+    res = resolve;
+    rej = reject;
+  });
 
-  return { promise, resolve: res, reject: rej } as DeferredPromise<T>;
+  return {promise, resolve: res, reject: rej} as DeferredPromise<T>;
 }

package/src/testing/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Testing & on-device-demo entry point.
+ *
+ * Imported via the package subpath:
+ *
+ *   import {VirtualSerialTransport, installSerialMock}
+ *     from 'react-native-web-serial-api/testing';
+ *
+ * These are reusable building blocks for *consumers'* tests and demos — an
+ * in-memory transport and an authorable `SerialDevice` peripheral model — so
+ * they ship with the package. The library's own spec-compliance suite is NOT
+ * here: it lives in `src/__tests__/conformance-suite.ts` (test-only, excluded
+ * from the build and the published package). None of this is in the main bundle.
+ */
+
+export type {SerialTransport} from '../transport';
+// The injection seam, re-exported here for convenience so a test or the
+// example's demo mode can flip the global transport from one import.
+export {getUsbSerial, resetUsbSerial, setUsbSerial} from '../UsbSerial';
+export type {InstallSerialMockOptions, SerialMockDevice} from './install';
+// Inject a mock device set into a running app (for on-device / emulator E2E).
+export {installSerialMock} from './install';
+export type {
+  DeviceIdentity,
+  SerialDeviceHost,
+  SerialDeviceOpenOptions,
+  SerialHostSignals,
+  SerialInputSignals,
+} from './serial-device';
+// Author a whole simulated peripheral by extending SerialDevice.
+export {
+  EchoDevice,
+  LineDevice,
+  SerialDevice,
+  SilentDevice,
+} from './serial-device';
+export type {
+  FailableOp,
+  VirtualDeviceOptions,
+  VirtualSerialOptions,
+} from './virtual-serial';
+export {VirtualDevice, VirtualSerialTransport} from './virtual-serial';

package/src/testing/install.ts

@@ -0,0 +1,65 @@
+/**
+ * installSerialMock — point the library at a virtual device set in one call.
+ *
+ * Built for E2E: call it once at app startup, behind your own env/build flag, to
+ * make `navigator.serial` / this library's `serial` talk to simulated
+ * {@link SerialDevice}s instead of real USB hardware while a test driver
+ * (Maestro, Detox, …) exercises the app on a device/emulator.
+ *
+ * @example
+ * // index.js (debug/E2E build only)
+ * import {installSerialMock, EchoDevice} from 'react-native-web-serial-api/testing';
+ * installSerialMock({
+ *   enabled: process.env.RNWS_SERIAL_MOCK === '1',
+ *   devices: [new EchoDevice(), new MyThermometer()],
+ * });
+ */
+import {setUsbSerial} from '../UsbSerial';
+import {SerialDevice} from './serial-device';
+import type {
+  VirtualDeviceOptions,
+  VirtualSerialOptions,
+} from './virtual-serial';
+import {VirtualSerialTransport} from './virtual-serial';
+
+/** A device to register: a SerialDevice, optionally with transport options. */
+export type SerialMockDevice =
+  | SerialDevice
+  | {device: SerialDevice; options?: VirtualDeviceOptions};
+
+export type InstallSerialMockOptions = {
+  /** The simulated devices to expose. */
+  devices: SerialMockDevice[];
+  /** When false, no mock is installed and `null` is returned. Defaults to true. */
+  enabled?: boolean;
+  /** Transport-level options (latency, chunkSize, …). */
+  transport?: VirtualSerialOptions;
+};
+
+/**
+ * Build a {@link VirtualSerialTransport} from `devices` and install it globally
+ * via {@link setUsbSerial}. SerialDevices default to granted USB permission (so
+ * they show up immediately); pass the `{device, options}` form to override.
+ * Returns the transport (handy for driving devices in-test), or `null` when
+ * disabled.
+ */
+export function installSerialMock(
+  options: InstallSerialMockOptions,
+): VirtualSerialTransport | null {
+  if (options.enabled === false) return null;
+
+  const transport = new VirtualSerialTransport(options.transport);
+  for (const entry of options.devices) {
+    if (entry instanceof SerialDevice) {
+      transport.addDevice(entry, {hasPermission: true});
+    } else {
+      transport.addDevice(entry.device, {
+        hasPermission: true,
+        ...entry.options,
+      });
+    }
+  }
+
+  setUsbSerial(transport);
+  return transport;
+}

package/src/testing/serial-device.ts

@@ -0,0 +1,193 @@
+/**
+ * SerialDevice — author a complete simulated serial peripheral.
+ *
+ * Extend the class and override the lifecycle hooks to model a real device's
+ * whole behaviour (firmware/protocol): react to `open()`, to bytes the host
+ * writes, to control-signal changes, and stream data back over time. It is
+ * hosted by a {@link VirtualSerialTransport} ({@link ./virtual-serial}) and is
+ * free of any `react-native` dependency, so the same device runs under Jest,
+ * in a browser, and inside a React Native app on a device/emulator (for E2E).
+ *
+ * @example
+ * class Thermometer extends SerialDevice {
+ *   usbVendorId = 0x0403;
+ *   usbProductId = 0x6001;
+ *   #timer?: ReturnType<typeof setInterval>;
+ *   onOpen() {
+ *     this.#timer = setInterval(() => this.send(`${20 + Math.random()}C\r\n`), 1000);
+ *   }
+ *   onData(bytes) {                       // host wrote a command
+ *     if (String.fromCharCode(...bytes).trim() === 'ID?') this.send('ACME-TEMP\r\n');
+ *   }
+ *   onClose() { clearInterval(this.#timer); }
+ * }
+ * transport.addDevice(new Thermometer(), {hasPermission: true});
+ */
+import type {OpenOptions} from '../transport';
+
+/** The negotiated connection parameters (native parity code: 0 none/1 odd/2 even). */
+export type SerialDeviceOpenOptions = Required<OpenOptions>;
+
+/** Device-asserted input signals — what the host reads via getSignals(). */
+export type SerialInputSignals = {
+  dataCarrierDetect?: boolean;
+  clearToSend?: boolean;
+  ringIndicator?: boolean;
+  dataSetReady?: boolean;
+};
+
+/** Host-asserted output signals (DTR/RTS/break) the device observes. */
+export type SerialHostSignals = {
+  dataTerminalReady: boolean;
+  requestToSend: boolean;
+  break: boolean;
+};
+
+/**
+ * The handle a {@link SerialDevice} uses to talk back to the host. Provided by
+ * the transport; you normally use the `protected` helpers on `SerialDevice`
+ * rather than this directly.
+ */
+export interface SerialDeviceHost {
+  readonly deviceId: number;
+  readonly portNumber: number;
+  readonly isOpen: boolean;
+  readonly openOptions: SerialDeviceOpenOptions | null;
+  send(bytes: number[]): void;
+  raiseError(message: string, name?: string): void;
+  setSignals(signals: SerialInputSignals): void;
+}
+
+/** Coerce a payload into a byte array (string → char codes, & 0xff). */
+export function toBytes(data: number[] | Uint8Array | string): number[] {
+  if (typeof data === 'string') {
+    return Array.from(data, c => c.charCodeAt(0) & 0xff);
+  }
+  if (data instanceof Uint8Array) return Array.from(data);
+  return data.map(n => n & 0xff);
+}
+
+/**
+ * Base class for a simulated serial peripheral. Override the `on*` hooks you
+ * care about (all default to no-ops and may be async) and use the `protected`
+ * helpers to drive the host.
+ */
+export abstract class SerialDevice {
+  /** USB Vendor ID this device reports for enumeration. */
+  abstract readonly usbVendorId: number;
+  /** USB Product ID this device reports for enumeration. */
+  abstract readonly usbProductId: number;
+  /** Optional USB serial number. */
+  readonly serialNumber?: string;
+
+  #host: SerialDeviceHost | null = null;
+
+  /** @internal Bind the transport host (called by VirtualSerialTransport). */
+  _bind(host: SerialDeviceHost): void {
+    this.#host = host;
+  }
+
+  /** Send bytes to the host (they appear on `port.readable`). */
+  protected send(data: number[] | Uint8Array | string): void {
+    this.#host?.send(toBytes(data));
+  }
+
+  /**
+   * Raise a typed read error on the host's readable stream. `name` is the W3C
+   * error type, e.g. "BreakError", "BufferOverrunError", "FramingError",
+   * "ParityError" (defaults to "NetworkError").
+   */
+  protected raiseError(message: string, name?: string): void {
+    this.#host?.raiseError(message, name);
+  }
+
+  /** Set device-asserted input signals (DCD/CTS/RI/DSR) the host can read. */
+  protected setSignals(signals: SerialInputSignals): void {
+    this.#host?.setSignals(signals);
+  }
+
+  /** The parameters the host opened the port with, or null when closed. */
+  protected get openOptions(): SerialDeviceOpenOptions | null {
+    return this.#host?.openOptions ?? null;
+  }
+
+  protected get deviceId(): number {
+    return this.#host?.deviceId ?? -1;
+  }
+
+  protected get portNumber(): number {
+    return this.#host?.portNumber ?? 0;
+  }
+
+  /** The host opened the port. */
+  onOpen(_options: SerialDeviceOpenOptions): void | Promise<void> {}
+  /** The host wrote bytes to the device. */
+  onData(_data: Uint8Array): void | Promise<void> {}
+  /** The host changed DTR/RTS/break. */
+  onHostSignals(_signals: SerialHostSignals): void | Promise<void> {}
+  /** The host closed the port. */
+  onClose(): void | Promise<void> {}
+}
+
+/** Optional USB identity for the built-in devices. */
+export type DeviceIdentity = {
+  usbVendorId?: number;
+  usbProductId?: number;
+  serialNumber?: string;
+};
+
+/** A loopback device: every byte written is echoed straight back. */
+export class EchoDevice extends SerialDevice {
+  readonly usbVendorId: number;
+  readonly usbProductId: number;
+  readonly serialNumber?: string;
+
+  constructor(identity: DeviceIdentity = {}) {
+    super();
+    this.usbVendorId = identity.usbVendorId ?? 0x0403;
+    this.usbProductId = identity.usbProductId ?? 0x6001;
+    this.serialNumber = identity.serialNumber;
+  }
+
+  onData(data: Uint8Array): void {
+    this.send(data);
+  }
+}
+
+/**
+ * Base for a line-oriented command/response device: buffers incoming bytes and
+ * calls {@link onLine} for each `\n`-terminated line (trailing CR/LF stripped).
+ */
+export abstract class LineDevice extends SerialDevice {
+  #buffer = '';
+
+  /** Handle one line received from the host. */
+  abstract onLine(line: string): void | Promise<void>;
+
+  onData(data: Uint8Array): void {
+    for (let i = 0; i < data.length; i++) {
+      this.#buffer += String.fromCharCode(data[i]);
+    }
+    let nl = this.#buffer.indexOf('\n');
+    while (nl >= 0) {
+      const line = this.#buffer.slice(0, nl).replace(/\r$/, '');
+      this.#buffer = this.#buffer.slice(nl + 1);
+      void this.onLine(line);
+      nl = this.#buffer.indexOf('\n');
+    }
+  }
+}
+
+/** A device that accepts writes but never sends anything back. */
+export class SilentDevice extends SerialDevice {
+  readonly usbVendorId: number;
+  readonly usbProductId: number;
+  readonly serialNumber?: string;
+
+  constructor(identity: DeviceIdentity = {}) {
+    super();
+    this.usbVendorId = identity.usbVendorId ?? 0x0403;
+    this.usbProductId = identity.usbProductId ?? 0x6001;
+    this.serialNumber = identity.serialNumber;
+  }
+}