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

package/src/WebSerial.ts

@@ -1,19 +1,19 @@
-import {
-  ByteLengthQueuingStrategy,
-  ReadableStream,
-  WritableStream,
-} from 'web-streams-polyfill';
 import {DOMException} from './lib/dom-exception';
-import {Event, EventTarget} from './lib/event-target';
+import {Event, EventTarget, setEventParent} from './lib/event-target';
 import {createDeferredPromise} from './lib/promise';
+import {
+  ByteLengthQueuingStrategyImpl as ByteLengthQueuingStrategy,
+  ReadableStreamImpl as ReadableStream,
+  WritableStreamImpl as WritableStream,
+} from './lib/web-streams';
 import type {
   ConnectEvent,
   DataEvent,
   ErrorEvent,
   OpenOptions,
   PortId,
-  UsbSerialModule,
-} from './UsbSerial';
+  SerialTransport,
+} from './transport';
 import {getUsbSerial} from './UsbSerial';
 
 /**
@@ -23,14 +23,14 @@ import {getUsbSerial} from './UsbSerial';
  * even - Data word plus parity bit has even parity.
  * odd - Data word plus parity bit has odd parity.
  */
-type ParityType = 'none' | 'even' | 'odd';
+export type Parity = 'none' | 'even' | 'odd';
 
 /**
  * @see https://wicg.github.io/serial/#dom-flowcontroltype
  * none - No flow control is enabled.
  * hardware - Hardware flow control using the RTS and CTS signals is enabled.
  */
-type FlowControlType = 'none' | 'hardware';
+type FlowControl = 'none' | 'hardware';
 
 /**
  * @see https://wicg.github.io/serial/#dom-serialoptions
@@ -60,7 +60,7 @@ export type SerialOptions = {
   /**
    * The parity mode.
    */
-  parity?: ParityType;
+  parity?: Parity;
   /**
    * A positive, non-zero value indicating the size of the read and write
    * buffers that should be created.
@@ -69,7 +69,7 @@ export type SerialOptions = {
   /**
    * The flow control mode.
    */
-  flowControl?: FlowControlType;
+  flowControl?: FlowControl;
 };
 
 /**
@@ -171,24 +171,27 @@ type PortInternals = {
   getVid(): number | undefined;
   getPid(): number | undefined;
   getPortNumber(): number;
-  getDeviceId(): number;
+  isForgotten(): boolean;
   setDeviceId(id: number): void;
   /** Reset to a closed, re-openable state after the device is physically lost. */
   handleDeviceLost(): void;
+  /** Reset to a closed, re-openable state after a clean physical detach. */
+  handleDeviceDetached(): void;
 };
 const portInternals = new WeakMap<SerialPort, PortInternals>();
 
 const kDefaultDataBits = 8;
 const kDefaultStopBits = 1;
-const kDefaultParity: ParityType = 'none';
+const kDefaultParity: Parity = 'none';
 const kDefaultBufferSize = 255;
-const kDefaultFlowControl: FlowControlType = 'none';
+const kDefaultFlowControl: FlowControl = 'none';
 
 const kAcceptableDataBits = [7, 8] as const;
 const kAcceptableStopBits = [1, 2] as const;
-const kAcceptableParity: ParityType[] = ['none', 'even', 'odd'];
+const kAcceptableParity: Parity[] = ['none', 'even', 'odd'];
+const kAcceptableFlowControl: FlowControl[] = ['none', 'hardware'];
 
-function parityToNative(parity: ParityType): number {
+function parityToNative(parity: Parity): number {
   switch (parity) {
     case 'odd':
       return 1;
@@ -199,8 +202,32 @@ function parityToNative(parity: ParityType): number {
   }
 }
 
-function flowControlToNative(flowControl: FlowControlType): 'RTS_CTS' | 'NONE' {
-  return flowControl === 'hardware' ? 'RTS_CTS' : 'NONE';
+const FLOW_CONTROL_NATIVE: Readonly<Record<FlowControl, 'RTS_CTS' | 'NONE'>> = {
+  none: 'NONE',
+  hardware: 'RTS_CTS',
+};
+
+function flowControlToNative(flowControl: FlowControl): 'RTS_CTS' | 'NONE' {
+  return FLOW_CONTROL_NATIVE[flowControl];
+}
+
+/**
+ * Normalise a writable chunk to a plain byte array. The Web Serial writable
+ * accepts any BufferSource — a bare `ArrayBuffer` or any `ArrayBufferView`
+ * (`DataView`, typed arrays, including views with a non-zero `byteOffset`). A
+ * naive `Array.from(chunk)` only works for the iterable typed arrays and
+ * silently yields `[]` for an `ArrayBuffer`/`DataView`, so handle each shape.
+ */
+function bufferSourceToBytes(chunk: ArrayBufferView | ArrayBuffer): number[] {
+  if (chunk instanceof Uint8Array) {
+    return Array.from(chunk);
+  }
+  if (ArrayBuffer.isView(chunk)) {
+    return Array.from(
+      new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength),
+    );
+  }
+  return Array.from(new Uint8Array(chunk as ArrayBuffer));
 }
 
 /**
@@ -239,24 +266,60 @@ export class SerialPort extends EventTarget {
   #pendingClosePromise: ReturnType<typeof createDeferredPromise<void>> | null =
     null; // [[pendingClosePromise]] = null
 
-  #usb: UsbSerialModule;
+  #usb: SerialTransport;
   #deviceId: number;
   #portNumber: number;
   #usbVendorId?: number;
   #usbProductId?: number;
-
-  // Tracks the current state of output signals for partial updates
-  #outputSignals: Required<SerialOutputSignals> = {
-    dataTerminalReady: false,
-    requestToSend: false,
-    break: false,
-  };
+  // Baud rate of the current open(), used to size the native write timeout.
+  #baudRate: number = 0;
 
   #dataSubscription: {remove: () => void} | null = null;
   #errorSubscription: {remove: () => void} | null = null;
 
+  // The live stream controllers, captured in the readable/writable getters, so
+  // a device loss can error the in-flight read/write with a "NetworkError".
+  #readableController: ReadableStreamDefaultController<Uint8Array> | null =
+    null;
+  #writableController: WritableStreamDefaultController | null = null;
+  #forgetRequested: boolean = false;
+
+  #resetToClosedState(state: 'closed' | 'forgotten' = 'closed'): void {
+    this.#dataSubscription?.remove();
+    this.#errorSubscription?.remove();
+    this.#dataSubscription = null;
+    this.#errorSubscription = null;
+    this.#readableController = null;
+    this.#writableController = null;
+
+    this.#readable = null;
+    this.#writable = null;
+    this.#readFatal = false;
+    this.#writeFatal = false;
+    this.#pendingClosePromise = null;
+    this.#bufferSize = undefined;
+    this.#baudRate = 0;
+    this.#state = state;
+    this.#connected = false;
+    this.#forgetRequested = state === 'forgotten';
+  }
+
+  /**
+   * Compute a native write timeout (ms) large enough to actually drain `length`
+   * bytes at the negotiated baud rate. A fixed 2 s timeout spuriously fails
+   * large writes on slow links; this scales with the payload while keeping a 2 s
+   * floor. ~10 bits per byte (start + 8 data + stop) with a 2× safety margin.
+   */
+  #writeTimeoutFor(length: number): number {
+    const kMinTimeoutMs = 2000;
+    /* istanbul ignore next — baudRate is always > 0 when the port is open */
+    const baud = this.#baudRate > 0 ? this.#baudRate : 9600;
+    const estimatedMs = Math.ceil((length * 10 * 1000) / baud) * 2;
+    return Math.max(kMinTimeoutMs, estimatedMs);
+  }
+
   constructor(
-    usb: UsbSerialModule,
+    usb: SerialTransport,
     deviceId: number,
     portNumber: number,
     usbVendorId: number,
@@ -275,12 +338,13 @@ export class SerialPort extends EventTarget {
       getVid: () => this.#usbVendorId,
       getPid: () => this.#usbProductId,
       getPortNumber: () => this.#portNumber,
-      getDeviceId: () => this.#deviceId,
+      isForgotten: () => this.#state === 'forgotten',
       setDeviceId: (id: number) => {
         this.#deviceId = id;
         serialPortDeviceIds.set(this, id);
       },
       handleDeviceLost: () => this.#handleDeviceLost(),
+      handleDeviceDetached: () => this.#handleDeviceDetached(),
     });
   }
 
@@ -291,35 +355,75 @@ export class SerialPort extends EventTarget {
    * After this, a later open() (e.g. when the device is re-attached) succeeds.
    */
   #handleDeviceLost(): void {
-    // Tear down read/write streams without invoking the OS on the dead device.
+    const wasForgotten = this.#state === 'forgotten';
+
+    // Reject any in-flight read/write with a "NetworkError" (per spec), erroring
+    // the stream controllers directly. We must NOT cancel()/abort() the streams:
+    // cancel() rejects on a reader-locked stream (leaving the read orphaned) and
+    // both would try to invoke the OS on the now-gone device.
+    const lost = new DOMException('The device has been lost.', 'NetworkError');
     if (this.#readable) {
       this.#readFatal = true;
       try {
-        // No active reader is required for cancel(); errors are non-fatal here.
-        this.#readable.cancel().catch(() => {});
+        this.#readableController?.error(lost);
       } catch {}
     }
     if (this.#writable) {
       this.#writeFatal = true;
       try {
-        this.#writable.abort().catch(() => {});
+        this.#writableController?.error(lost);
       } catch {}
     }
-    this.#dataSubscription?.remove();
-    this.#errorSubscription?.remove();
-    this.#dataSubscription = null;
-    this.#errorSubscription = null;
+    this.#resetToClosedState(wasForgotten ? 'forgotten' : 'closed');
 
+    this.dispatchEvent(new Event('disconnect'));
+  }
+
+  /**
+   * Reset this port to a closed, re-openable state after a clean physical
+   * detach. Unlike device loss, buffered readable bytes should still be
+   * observable before the stream ends.
+   */
+  #handleDeviceDetached(): void {
+    const wasForgotten = this.#state === 'forgotten';
+    const readable = this.#readable;
+    const writable = this.#writable;
+
+    // Keep the public event and state transition synchronous so existing
+    // callers observe the detach immediately, but defer the stream teardown by
+    // one microtask to let already-queued data drain first.
+    this.#state = wasForgotten ? 'forgotten' : 'closed';
+    this.#connected = false;
     this.#readable = null;
     this.#writable = null;
-    this.#readFatal = false;
-    this.#writeFatal = false;
-    this.#pendingClosePromise = null;
-    this.#bufferSize = undefined;
-    this.#state = 'closed';
-    this.#connected = false;
-
     this.dispatchEvent(new Event('disconnect'));
+
+    queueMicrotask(() => {
+      // Close the readable stream so any bytes already queued can still be
+      // drained by the consumer before EOF.
+      try {
+        if (readable) this.#readableController?.close();
+      } catch {}
+
+      // A detached device can no longer accept writes, so reject any writable
+      // traffic and clear local state.
+      const lost = new DOMException(
+        'The device has been lost.',
+        'NetworkError',
+      );
+      if (writable) {
+        this.#writeFatal = true;
+        try {
+          this.#writableController?.error(lost);
+        } catch {}
+      }
+
+      // Mirror the stream-closing bookkeeping without treating this as a hard
+      // read fatal error.
+      this.#handleClosingReadableStream();
+      this.#handleClosingWritableStream();
+      this.#resetToClosedState(wasForgotten ? 'forgotten' : 'closed');
+    });
   }
 
   /**
@@ -394,12 +498,21 @@ export class SerialPort extends EventTarget {
     const stream = new ReadableStream<Uint8Array>(
       {
         start(controller) {
+          self.#readableController = controller;
           self.#dataSubscription = self.#usb.onData((event: DataEvent) => {
             if (
               event.deviceId === deviceId &&
               event.portNumber === portNumber
             ) {
-              controller.enqueue(new Uint8Array(event.data));
+              try {
+                controller.enqueue(new Uint8Array(event.data));
+              } catch {
+                // The stream may already be closing/closed — e.g. a data event
+                // racing cancel()/close(), where the stream is closed but this
+                // subscription is not yet torn down. Dropping the chunk is
+                // correct (the consumer has stopped reading) and avoids throwing
+                // out of the transport's event-dispatch loop.
+              }
             }
           });
 
@@ -409,7 +522,15 @@ export class SerialPort extends EventTarget {
               event.portNumber === portNumber
             ) {
               self.#readFatal = true; // Set this.[[readFatal]] to true.
-              controller.error(new DOMException(event.error, 'NetworkError'));
+              // Surface the spec error type (BreakError, BufferOverrunError,
+              // FramingError, ParityError, …) when the transport reports one;
+              // fall back to NetworkError otherwise.
+              controller.error(
+                new DOMException(
+                  event.error,
+                  event.errorName ?? 'NetworkError',
+                ),
+              );
               self.#handleClosingReadableStream();
             }
           });
@@ -456,9 +577,18 @@ export class SerialPort extends EventTarget {
 
     const stream = new WritableStream<Uint8Array>(
       {
+        start(controller) {
+          self.#writableController = controller;
+        },
         async write(chunk) {
+          const bytes = bufferSourceToBytes(chunk);
           try {
-            await self.#usb.write(deviceId, portNumber, Array.from(chunk));
+            await self.#usb.write(
+              deviceId,
+              portNumber,
+              bytes,
+              self.#writeTimeoutFor(bytes.length),
+            );
           } catch (e) {
             // If the port was disconnected, set this.[[writeFatal]] to true.
             self.#writeFatal = true;
@@ -541,7 +671,7 @@ export class SerialPort extends EventTarget {
 
     // 3. If options["baudRate"] is 0, reject promise with a TypeError and
     // return promise.
-    if (options.baudRate === 0) {
+    if (!Number.isFinite(options.baudRate) || options.baudRate <= 0) {
       throw new TypeError('baudRate must be a positive, non-zero value.');
     }
 
@@ -562,7 +692,7 @@ export class SerialPort extends EventTarget {
     // 6. If options["bufferSize"] is 0, reject promise with a TypeError and
     // return promise.
     const bufferSize = options.bufferSize ?? kDefaultBufferSize;
-    if (bufferSize === 0) {
+    if (!Number.isFinite(bufferSize) || bufferSize <= 0) {
       throw new TypeError('bufferSize must be a positive, non-zero value.');
     }
 
@@ -574,6 +704,11 @@ export class SerialPort extends EventTarget {
     }
 
     const flowControl = options.flowControl ?? kDefaultFlowControl;
+    if (!kAcceptableFlowControl.includes(flowControl)) {
+      throw new TypeError(
+        `flowControl must be one of: ${kAcceptableFlowControl.join(', ')}.`,
+      );
+    }
 
     // 8. Set this.[[state]] to "opening".
     this.#state = 'opening';
@@ -599,18 +734,60 @@ export class SerialPort extends EventTarget {
       );
     }
 
-    if (flowControl !== 'none') {
-      await this.#usb.setFlowControl(
-        this.#deviceId,
-        this.#portNumber,
-        flowControlToNative(flowControl),
+    try {
+      if (flowControl !== 'none') {
+        await this.#usb.setFlowControl(
+          this.#deviceId,
+          this.#portNumber,
+          flowControlToNative(flowControl),
+        );
+      }
+
+      await this.#usb.startReading(this.#deviceId, this.#portNumber);
+    } catch (e) {
+      // If post-open setup fails (flow-control/read pump), best-effort close
+      // and reset local state so a subsequent open() can succeed cleanly.
+      try {
+        await this.#usb.close(this.#deviceId, this.#portNumber);
+      } catch {
+        // ignore
+      }
+
+      this.#resetToClosedState(this.#forgetRequested ? 'forgotten' : 'closed');
+
+      throw new DOMException(
+        `Failed to open serial port: ${(e as Error).message}`,
+        'NetworkError',
+      );
+    }
+
+    // Guard against lifecycle races (e.g. forget() called while open() is
+    // still awaiting native setup). Do not revive a forgotten/changed state.
+    if (this.#state !== 'opening') {
+      try {
+        await this.#usb.close(this.#deviceId, this.#portNumber);
+      } catch {
+        // ignore
+      }
+
+      if (this.#state === 'forgotten' || this.#state === 'forgetting') {
+        this.#resetToClosedState('forgotten');
+        throw new DOMException(
+          'The port has been forgotten while opening.',
+          'InvalidStateError',
+        );
+      }
+
+      this.#resetToClosedState();
+      throw new DOMException(
+        'Failed to open serial port: state changed while opening.',
+        'NetworkError',
       );
     }
 
     this.#state = 'opened'; // 9.3. Set this.[[state]] to "opened".
     this.#bufferSize = bufferSize; // 9.4. Set this.[[bufferSize]] to options["bufferSize"].
-
-    await this.#usb.startReading(this.#deviceId, this.#portNumber);
+    this.#baudRate = options.baudRate;
 
     // When the port becomes logically connected:
     this.#connected = true; // 2. Set port.[[connected]] to true.
@@ -618,6 +795,13 @@ export class SerialPort extends EventTarget {
     // device presence (attach/detach), dispatched by Serial from the native
     // USB state events — not logical open()/close(). So we do not dispatch them
     // here; that also avoids re-entrancy with auto-reconnect listeners.
+
+    // Materialise the readable eagerly so its data subscription is live the
+    // instant the native read pump (startReading, above) begins emitting. The
+    // device may transmit immediately on open; without an active subscription
+    // those first bytes would be delivered to no listener and silently lost in
+    // the window between open() resolving and the first port.readable access.
+    void this.readable;
   }
 
   /**
@@ -676,18 +860,10 @@ export class SerialPort extends EventTarget {
       // ignore
     }
 
-    this.#dataSubscription?.remove();
-    this.#errorSubscription?.remove();
-    this.#dataSubscription = null;
-    this.#errorSubscription = null;
-
-    this.#state = 'closed'; // 10.1.2. Set this.[[state]] to "closed".
-    this.#readFatal = false; // 10.1.3. Set this.[[readFatal]] and this.[[writeFatal]] to false.
-    this.#writeFatal = false; // 10.1.3. (continued)
-    this.#pendingClosePromise = null; // 10.1.4. Set this.[[pendingClosePromise]] to null.
-
-    // When the port is no longer logically connected:
-    this.#connected = false; // 2. Set port.[[connected]] to false.
+    // 10.1.2-10.1.4 and logical disconnect bookkeeping.
+    // If forget() was requested while close() was in flight, preserve
+    // forgotten semantics instead of reviving the port to "closed".
+    this.#resetToClosedState(this.#forgetRequested ? 'forgotten' : 'closed');
     // (No port-level "disconnect" dispatch here — that event signals physical
     // detach, fired by Serial from the native USB state events. See open().)
   }
@@ -698,6 +874,14 @@ export class SerialPort extends EventTarget {
   async forget(): Promise<void> {
     // The forget() method steps are:
 
+    this.#forgetRequested = true;
+
+    // Forgetting an open port must not leave active streams/native resources
+    // behind. Close first so the instance becomes cleanly unusable afterwards.
+    if (this.#state === 'opened') {
+      await this.close();
+    }
+
     // 2.1. Set this.[[state]] to "forgetting".
     this.#state = 'forgetting';
     // 2.2. Remove this from the sequence of serial ports on the system which
@@ -729,9 +913,6 @@ export class SerialPort extends EventTarget {
       throw new TypeError('At least one signal must be specified.');
     }
 
-    // Merge with current output signal state for partial updates
-    this.#outputSignals = {...this.#outputSignals, ...signals};
-
     const promises: Promise<void>[] = [];
 
     // 4.1. If signals["dataTerminalReady"] is present, invoke the operating
@@ -824,6 +1005,17 @@ export class SerialPort extends EventTarget {
   #handleClosingReadableStream(): void {
     // To handle closing the readable stream perform the following steps:
 
+    // Drop the native data/error subscription tied to this readable. Without
+    // this a later readable (after cancel() + re-acquire) would coexist with the
+    // old subscription, which then enqueues into the cancelled controller and
+    // throws. close()/handleDeviceLost() also clear these; doing it here covers
+    // a standalone readable.cancel().
+    this.#dataSubscription?.remove();
+    this.#errorSubscription?.remove();
+    this.#dataSubscription = null;
+    this.#errorSubscription = null;
+    this.#readableController = null;
+
     // 1. Set this.[[readable]] to null.
     this.#readable = null;
 
@@ -840,6 +1032,8 @@ export class SerialPort extends EventTarget {
   #handleClosingWritableStream(): void {
     // To handle closing the writable stream perform the following steps:
 
+    this.#writableController = null;
+
     // 1. Set this.[[writable]] to null.
     this.#writable = null;
 
@@ -860,9 +1054,23 @@ export class Serial extends EventTarget {
     disconnect: null as ((event: Event) => void) | null,
   };
 
-  #usb: UsbSerialModule | null = null;
+  #usb: SerialTransport | null = null;
   #knownPorts: Map<string, SerialPort> = new Map();
   #initialized = false;
+  #injected: SerialTransport | null;
+
+  /**
+   * @param transport Optional transport override. When provided, this `Serial`
+   * talks to it instead of the global native module — the transport override used by tests
+   * and the virtual serial device harness (`new Serial(new InMemorySerialTransport())`).
+   * Omit it for the normal native-backed instance; the singleton `serial`
+   * export is created this way and can still be redirected globally via
+   * `setUsbSerial()`.
+   */
+  constructor(transport?: SerialTransport) {
+    super();
+    this.#injected = transport ?? null;
+  }
 
   /**
    * Subscribing to "connect"/"disconnect" must wire up the native USB state
@@ -880,42 +1088,49 @@ export class Serial extends EventTarget {
    * Deferring native access out of the module-import path avoids touching the
    * TurboModule before the runtime is ready.
    */
-  #ensureInit(): UsbSerialModule | null {
+  #ensureInit(): SerialTransport | null {
     if (this.#initialized) return this.#usb;
     this.#initialized = true;
     try {
-      this.#usb = getUsbSerial();
+      this.#usb = this.#injected ?? getUsbSerial();
 
       // A USB device was attached. Android assigns a NEW deviceId on every
       // attach, so match previously-known ports of the same physical device by
       // VID/PID, update their deviceId, re-key them, and fire "connect" on the
       // same SerialPort instance (W3C spec model: the port is reused).
       this.#usb.onConnect((event: ConnectEvent) => {
-        let matched = false;
-        for (const [key, port] of [...this.#knownPorts.entries()]) {
-          const internals = portInternals.get(port);
-          if (!internals) continue;
-          if (
-            internals.getVid() === event.usbVendorId &&
-            internals.getPid() === event.usbProductId
-          ) {
-            internals.setDeviceId(event.deviceId);
-            const newKey = this.#portKey(
-              event.deviceId,
-              internals.getPortNumber(),
-            );
-            if (newKey !== key) {
-              this.#knownPorts.delete(key);
-              this.#knownPorts.set(newKey, port);
-            }
-            port.dispatchEvent(new Event('connect'));
-            matched = true;
-          }
+        // Native connect events expose VID/PID but not a stable unique
+        // identifier. To avoid mis-associating identical devices, remap only
+        // when there is exactly one disconnected candidate.
+        const candidates = Array.from(this.#knownPorts.entries()).filter(
+          ([, port]) => {
+            const internals = portInternals.get(port)!;
+            if (internals.getVid() !== event.usbVendorId) return false;
+            if (internals.getPid() !== event.usbProductId) return false;
+            if (internals.isForgotten()) return false;
+            return !port.connected;
+          },
+        );
+
+        if (candidates.length === 1) {
+          const [key, port] = candidates[0];
+          const internals = portInternals.get(port)!;
+          internals.setDeviceId(event.deviceId);
+          const newKey = this.#portKey(
+            event.deviceId,
+            internals.getPortNumber(),
+          );
+          this.#knownPorts.delete(key);
+          this.#knownPorts.set(newKey, port);
+          // Dispatched on the port; it bubbles to this Serial (event.target
+          // stays the port, per spec — see setEventParent below).
+          port.dispatchEvent(new Event('connect'));
+          return;
         }
+
+        // No known port matched (or matching is ambiguous): fire a Serial-level
+        // "connect" so listeners refresh; getPorts() surfaces the new port.
         this.dispatchEvent(new Event('connect'));
-        // If we matched no known port this is a brand-new device; getPorts()
-        // will surface it on the next refresh.
-        void matched;
       });
 
       // A USB device was detached. Reset the matching port(s) to a closed,
@@ -923,13 +1138,22 @@ export class Serial extends EventTarget {
       // SerialPort instance so a re-attach can reuse it. handleDeviceLost()
       // dispatches "disconnect" on the port.
       this.#usb.onDisconnect((event: ConnectEvent) => {
+        const wasLost = (event as ConnectEvent & {lost?: boolean}).lost ?? true;
         const prefix = `${event.deviceId}:`;
+        let matched = false;
         for (const [key, port] of [...this.#knownPorts.entries()]) {
           if (key.startsWith(prefix)) {
-            portInternals.get(port)?.handleDeviceLost();
+            // Physical loss tears down the stream immediately; a clean detach
+            // lets any already-buffered bytes drain before EOF.
+            const internals = portInternals.get(port);
+            if (wasLost) internals?.handleDeviceLost();
+            else internals?.handleDeviceDetached();
+            matched = true;
           }
         }
-        this.dispatchEvent(new Event('disconnect'));
+        // No known port matched (e.g. a device never opened): fire a
+        // Serial-level "disconnect" so listeners can still refresh.
+        if (!matched) this.dispatchEvent(new Event('disconnect'));
       });
     } catch {
       this.#usb = null;
@@ -1007,11 +1231,18 @@ export class Serial extends EventTarget {
     } of portIds) {
       if (!hasPermission) continue;
       const key = this.#portKey(deviceId, portNumber);
-      if (!this.#knownPorts.has(key)) {
-        this.#knownPorts.set(
-          key,
-          new SerialPort(usb, deviceId, portNumber, usbVendorId, usbProductId),
+      const known = this.#knownPorts.get(key);
+      if (!known || portInternals.get(known)?.isForgotten()) {
+        const port = new SerialPort(
+          usb,
+          deviceId,
+          portNumber,
+          usbVendorId,
+          usbProductId,
         );
+        // The port's connect/disconnect events bubble to this Serial.
+        setEventParent(port, this);
+        this.#knownPorts.set(key, port);
       }
       ports.push(this.#knownPorts.get(key)!);
     }
@@ -1036,6 +1267,12 @@ export class Serial extends EventTarget {
       );
     }
 
+    if ((options.allowedBluetoothServiceClassIds?.length ?? 0) > 0) {
+      throw new TypeError(
+        'allowedBluetoothServiceClassIds is not supported in Android USB mode.',
+      );
+    }
+
     // 4. If options["filters"] is present, then for each filter in
     // options["filters"] run the following steps:
     if (options.filters) {
@@ -1083,17 +1320,18 @@ export class Serial extends EventTarget {
 
     // 5.6. Let port be a SerialPort representing the port chosen by the user.
     const key = `${portId.deviceId}:${portId.portNumber}`;
-    if (!this.#knownPorts.has(key)) {
-      this.#knownPorts.set(
-        key,
-        new SerialPort(
-          usb,
-          portId.deviceId,
-          portId.portNumber,
-          portId.usbVendorId,
-          portId.usbProductId,
-        ),
+    const known = this.#knownPorts.get(key);
+    if (!known || portInternals.get(known)?.isForgotten()) {
+      const port = new SerialPort(
+        usb,
+        portId.deviceId,
+        portId.portNumber,
+        portId.usbVendorId,
+        portId.usbProductId,
       );
+      // The port's connect/disconnect events bubble to this Serial.
+      setEventParent(port, this);
+      this.#knownPorts.set(key, port);
     }
 
     // 5.7. Resolve promise with port.