@matter-server/ble-proxy 1.4.0 → 1.4.1-alpha.0-20261008-d619c2e

package/dist/esm/example/NobleBleProxyClient.js

@@ -7,9 +7,12 @@ import { WebSocket } from "ws";
 import {
   BLE_PROXY_PROTOCOL_VERSION,
   BinaryFrameOpcode,
+  BleProxyErrorCode,
   decodeBinaryFrame,
   encodeBinaryFrame
 } from "../BleProxyProtocol.js";
+const CONNECT_DISCOVERY_TIMEOUT_MS = 5e3;
+const SCAN_OPERATION_TIMEOUT_MS = 1e4;
 function withTimeout(promise, ms, message) {
   return Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms))]);
 }
@@ -38,14 +41,27 @@ class NobleBleProxyClient {
   #connections = /* @__PURE__ */ new Map();
   #nextHandle = 1;
   #discoveredPeripherals = /* @__PURE__ */ new Map();
+  #discoveryWaiters = /* @__PURE__ */ new Map();
   #lastDiscoverFingerprint = /* @__PURE__ */ new Map();
+  #desiredScan;
+  #scanPauses = 0;
+  #scanGeneration = 0;
+  #scanOperations = Promise.resolve();
+  #discoverListenerInstalled = false;
+  #scanOperationTimeoutMs;
   #commandHandlers = /* @__PURE__ */ new Map();
   #closing = false;
-  constructor(serverUrl, hciId) {
+  constructor(serverUrl, hciId, options = {}) {
     this.#serverUrl = serverUrl;
     this.#hciId = hciId;
+    this.#noble = options.noble;
+    this.#scanOperationTimeoutMs = options.scanOperationTimeoutMs ?? SCAN_OPERATION_TIMEOUT_MS;
     this.#registerCommandHandlers();
   }
+  /** Command names this client implements. Must cover every `BleProxyCommand` value. */
+  get supportedCommands() {
+    return [...this.#commandHandlers.keys()];
+  }
   async connect() {
     await this.#loadNoble();
     return new Promise((resolve, reject) => {
@@ -60,7 +76,17 @@ class NobleBleProxyClient {
           this.#handleBinaryFrame(Buffer.from(data));
           return;
         }
-        const msg = JSON.parse(data.toString());
+        let msg;
+        try {
+          msg = JSON.parse(data.toString());
+        } catch {
+          warn("Received invalid JSON from the server");
+          return;
+        }
+        if (typeof msg !== "object" || msg === null) {
+          warn("Ignoring non-object JSON message from the server");
+          return;
+        }
         if (!handshakeComplete) {
           if (msg.type === "hello_response") {
             if (msg.error) {
@@ -114,10 +140,20 @@ class NobleBleProxyClient {
       }
     }
     this.#connections.clear();
+    for (const waiters of this.#discoveryWaiters.values()) {
+      for (const waiter of waiters) {
+        clearTimeout(waiter.timer);
+        waiter.resolve(void 0);
+      }
+    }
+    this.#discoveryWaiters.clear();
     this.#noble?.stop();
     this.#ws?.close();
   }
   async #loadNoble() {
+    if (this.#noble) {
+      return;
+    }
     if (this.#hciId !== void 0) {
       process.env.NOBLE_HCI_DEVICE_ID = this.#hciId.toString();
     }
@@ -133,7 +169,7 @@ class NobleBleProxyClient {
     this.#noble.on("stateChange", (state) => log(`[NOBLE] stateChange: ${state}`));
   }
   #registerCommandHandlers() {
-    this.#commandHandlers.set("start_scan", (id, _args) => this.#handleStartScan(id));
+    this.#commandHandlers.set("start_scan", (id, args) => this.#handleStartScan(id, args));
     this.#commandHandlers.set("stop_scan", (id) => this.#handleStopScan(id));
     this.#commandHandlers.set("connect", (id, args) => this.#handleConnect(id, args));
     this.#commandHandlers.set(
@@ -160,6 +196,10 @@ class NobleBleProxyClient {
       "subscribe_characteristic",
       (id, args) => this.#handleSubscribeCharacteristic(id, args)
     );
+    this.#commandHandlers.set(
+      "write_and_subscribe",
+      (id, args) => this.#handleWriteAndSubscribe(id, args)
+    );
     this.#commandHandlers.set(
       "unsubscribe_characteristic",
       (id, args) => this.#handleUnsubscribeCharacteristic(id, args)
@@ -179,27 +219,56 @@ class NobleBleProxyClient {
     const handler = this.#commandHandlers.get(msg.command);
     if (!handler) {
       error(`[\u2192ERR] id=${msg.id} Unknown command: ${msg.command}`);
-      this.#sendError(msg.id, "internal_error", `Unknown command: ${msg.command}`);
+      this.#sendError(msg.id, BleProxyErrorCode.InternalError, `Unknown command: ${msg.command}`);
       return;
     }
     try {
       await handler(msg.id, msg.args ?? {});
     } catch (err) {
       error(`[\u2192ERR] id=${msg.id} ${msg.command} threw: ${err.message}`);
-      this.#sendError(msg.id, "internal_error", `${err.message}`);
+      this.#sendError(msg.id, BleProxyErrorCode.InternalError, `${err.message}`);
     }
   }
   // ─── Command Handlers ────────────────────────────────────────────────────
-  async #handleStartScan(id) {
+  async #handleStartScan(id, args) {
     if (!this.#noble) {
-      this.#sendError(id, "bluetooth_unavailable", "Noble not initialized");
+      this.#sendError(id, BleProxyErrorCode.BluetoothUnavailable, "Noble not initialized");
       return;
     }
+    const config = {
+      serviceUuids: args.service_uuids ?? [],
+      reportDuplicates: args.allow_duplicates ?? true
+    };
     this.#lastDiscoverFingerprint.clear();
-    this.#noble.removeAllListeners("discover");
+    this.#installDiscoverListener();
+    try {
+      await this.#requestScan(config);
+    } catch (err) {
+      this.#sendError(id, BleProxyErrorCode.InternalError, err.message);
+      return;
+    }
+    log(
+      `[SCAN] BLE scan started (filter: ${config.serviceUuids.join(",") || "none"} allowDuplicates=${config.reportDuplicates})`
+    );
+    this.#sendSuccess(id);
+  }
+  /** Installed once and kept: noble emits `discover` only while a scan is running. */
+  #installDiscoverListener() {
+    if (this.#discoverListenerInstalled) {
+      return;
+    }
+    this.#discoverListenerInstalled = true;
     this.#noble.on("discover", (peripheral) => {
       const address = peripheral.address || peripheral.id;
       this.#discoveredPeripherals.set(address, peripheral);
+      const waiters = this.#discoveryWaiters.get(address);
+      if (waiters) {
+        this.#discoveryWaiters.delete(address);
+        for (const waiter of waiters) {
+          clearTimeout(waiter.timer);
+          waiter.resolve(peripheral);
+        }
+      }
       const serviceData = {};
       for (const sd of peripheral.advertisement.serviceData ?? []) {
         serviceData[sd.uuid] = Buffer.from(sd.data).toString("base64");
@@ -215,7 +284,7 @@ class NobleBleProxyClient {
       };
       const prev = this.#lastDiscoverFingerprint.get(address);
       const changed = !prev || prev.name !== fingerprint.name || prev.connectable !== fingerprint.connectable || prev.serviceUuids !== fingerprint.serviceUuids || prev.serviceData !== fingerprint.serviceData;
-      if (!changed) {
+      if (!(this.#desiredScan?.reportDuplicates ?? true) && !changed) {
         return;
       }
       this.#lastDiscoverFingerprint.set(address, fingerprint);
@@ -232,22 +301,50 @@ class NobleBleProxyClient {
       };
       this.#sendEvent("device_discovered", event);
     });
-    await this.#noble.startScanningAsync(["fff6"], true);
-    log("[SCAN] BLE scan started (filter: fff6)");
-    this.#sendSuccess(id);
   }
   async #handleStopScan(id) {
-    await this.#noble?.stopScanningAsync();
+    try {
+      await this.#requestScan(void 0);
+    } catch (err) {
+      this.#sendError(id, BleProxyErrorCode.InternalError, err.message);
+      return;
+    }
     log("[SCAN] BLE scan stopped");
     this.#sendSuccess(id);
   }
+  /** Resolves once `address` is advertised, or undefined once the wait times out. */
+  #awaitDiscovered(address) {
+    const known = this.#discoveredPeripherals.get(address);
+    if (known) {
+      return Promise.resolve(known);
+    }
+    if (!this.#desiredScan) {
+      return Promise.resolve(void 0);
+    }
+    log(`[CONN] "${address}" not advertised yet, waiting up to ${CONNECT_DISCOVERY_TIMEOUT_MS}ms`);
+    return new Promise((resolve) => {
+      const waiters = this.#discoveryWaiters.get(address) ?? /* @__PURE__ */ new Set();
+      this.#discoveryWaiters.set(address, waiters);
+      const waiter = {
+        resolve,
+        timer: setTimeout(() => {
+          waiters.delete(waiter);
+          if (waiters.size === 0) {
+            this.#discoveryWaiters.delete(address);
+          }
+          resolve(void 0);
+        }, CONNECT_DISCOVERY_TIMEOUT_MS)
+      };
+      waiters.add(waiter);
+    });
+  }
   async #handleConnect(id, args) {
-    const peripheral = this.#discoveredPeripherals.get(args.address);
+    const peripheral = await this.#awaitDiscovered(args.address);
     if (!peripheral) {
       error(
-        `[CONN] No peripheral found for address "${args.address}". Known: ${[...this.#discoveredPeripherals.keys()].join(", ")}`
+        `[CONN] No peripheral found for address "${args.address}" after ${CONNECT_DISCOVERY_TIMEOUT_MS}ms. Known: ${[...this.#discoveredPeripherals.keys()].join(", ")}`
       );
-      this.#sendError(id, "device_not_found", `No device found for address ${args.address}`);
+      this.#sendError(id, BleProxyErrorCode.DeviceNotFound, `No device found for address ${args.address}`);
       return;
     }
     const handle = this.#nextHandle++;
@@ -267,9 +364,10 @@ class NobleBleProxyClient {
     };
     peripheral.once("disconnect", disconnectListener);
     log(`[CONN] Connecting to "${args.address}" (state=${peripheral.state})...`);
+    let releaseScanPause;
     try {
       log(`[SCAN] pausing scan for connect+interview...`);
-      await this.#noble.stopScanningAsync();
+      releaseScanPause = await this.#acquireScanPause();
       await peripheral.connectAsync();
       log(`[CONN] Connected handle=${handle} state=${peripheral.state} mtu=${peripheral.mtu ?? "?"}`);
       log(`[GATT] handle=${handle} discoverServicesAsync(["fff6"])...`);
@@ -297,8 +395,6 @@ class NobleBleProxyClient {
       }
       const mtu = peripheral.mtu ?? 23;
       log(`[GATT] handle=${handle} ready mtu=${mtu}`);
-      log(`[SCAN] resuming scan after connect+interview...`);
-      await this.#noble.startScanningAsync(["fff6"], true);
       this.#sendSuccess(id, { connection_handle: handle, mtu });
     } catch (err) {
       const reason = disconnectedReason ?? err.message;
@@ -312,16 +408,18 @@ class NobleBleProxyClient {
           (disconnectErr) => warn(`[CONN] handle=${handle} cleanup disconnect failed: ${disconnectErr.message}`)
         );
       }
-      this.#noble.startScanningAsync(["fff6"], true).catch(
-        (scanErr) => warn(`[SCAN] failed to resume scanning after connect failure: ${scanErr.message}`)
+      this.#sendError(id, BleProxyErrorCode.ConnectionFailed, reason);
+    } finally {
+      log(`[SCAN] resuming scan after connect+interview...`);
+      await releaseScanPause?.().catch(
+        (scanErr) => warn(`[SCAN] failed to resume scanning after connect: ${scanErr.message}`)
       );
-      this.#sendError(id, "internal_error", reason);
     }
   }
   async #handleDisconnect(id, connectionHandle) {
     const conn = this.#connections.get(connectionHandle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${connectionHandle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${connectionHandle}`);
       return;
     }
     if (conn.peripheral.state === "connected") {
@@ -333,7 +431,7 @@ class NobleBleProxyClient {
   async #handleDiscoverServices(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
     if (conn.services.size > 0) {
@@ -343,11 +441,17 @@ class NobleBleProxyClient {
       return;
     }
     log(`[GATT] handle=${args.connection_handle} discovering services (lazy)...`);
-    const services = await withTimeout(
-      conn.peripheral.discoverServicesAsync([]),
-      1e4,
-      "discoverServices timed out after 10s"
-    );
+    let services;
+    try {
+      services = await withTimeout(
+        conn.peripheral.discoverServicesAsync([]),
+        1e4,
+        "discoverServices timed out after 10s"
+      );
+    } catch (err) {
+      this.#sendError(id, BleProxyErrorCode.DiscoveryFailed, err.message);
+      return;
+    }
     for (const service of services) {
       conn.services.set(service.uuid, service);
     }
@@ -359,12 +463,12 @@ class NobleBleProxyClient {
   async #handleDiscoverCharacteristics(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
     const service = conn.services.get(args.service_uuid);
     if (!service) {
-      this.#sendError(id, "service_not_found", `Service ${args.service_uuid} not found`);
+      this.#sendError(id, BleProxyErrorCode.ServiceNotFound, `Service ${args.service_uuid} not found`);
       return;
     }
     const cachedChars = service.characteristics ?? [];
@@ -381,11 +485,17 @@ class NobleBleProxyClient {
       return;
     }
     log(`[GATT] handle=${args.connection_handle} discovering characteristics for ${args.service_uuid} (lazy)...`);
-    const characteristics = await withTimeout(
-      service.discoverCharacteristicsAsync([]),
-      1e4,
-      `discoverCharacteristics(${args.service_uuid}) timed out after 10s`
-    );
+    let characteristics;
+    try {
+      characteristics = await withTimeout(
+        service.discoverCharacteristicsAsync([]),
+        1e4,
+        `discoverCharacteristics(${args.service_uuid}) timed out after 10s`
+      );
+    } catch (err) {
+      this.#sendError(id, BleProxyErrorCode.DiscoveryFailed, err.message);
+      return;
+    }
     for (const char of characteristics) {
       conn.characteristics.set(char.uuid, char);
     }
@@ -402,78 +512,167 @@ class NobleBleProxyClient {
   async #handleReadCharacteristic(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
     const char = this.#findCharacteristic(conn, args.characteristic_uuid);
     if (!char) {
-      this.#sendError(id, "characteristic_not_found", `Characteristic ${args.characteristic_uuid} not found`);
+      this.#sendError(
+        id,
+        BleProxyErrorCode.CharacteristicNotFound,
+        `Characteristic ${args.characteristic_uuid} not found`
+      );
+      return;
+    }
+    let data;
+    try {
+      data = await char.readAsync();
+    } catch (err) {
+      this.#sendError(
+        id,
+        BleProxyErrorCode.ReadFailed,
+        `read(${args.characteristic_uuid}): ${err.message}`
+      );
       return;
     }
-    const data = await char.readAsync();
     log(`[GATT] read ${args.characteristic_uuid} \u2192 ${data.length} bytes`);
     this.#sendSuccess(id, { value: Buffer.from(data).toString("base64") });
   }
   async #handleWriteCharacteristic(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
     const char = this.#findCharacteristic(conn, args.characteristic_uuid);
     if (!char) {
-      this.#sendError(id, "characteristic_not_found", `Characteristic ${args.characteristic_uuid} not found`);
+      this.#sendError(
+        id,
+        BleProxyErrorCode.CharacteristicNotFound,
+        `Characteristic ${args.characteristic_uuid} not found`
+      );
       return;
     }
     const data = Buffer.from(args.value, "base64");
     const withResponse = args.response ?? false;
     log(`[GATT] write ${args.characteristic_uuid} ${data.length} bytes withResponse=${withResponse}`);
-    await char.writeAsync(data, !withResponse);
+    try {
+      await char.writeAsync(data, !withResponse);
+    } catch (err) {
+      this.#sendError(
+        id,
+        BleProxyErrorCode.WriteFailed,
+        `write(${args.characteristic_uuid}): ${err.message}`
+      );
+      return;
+    }
     conn.lastWriteCharacteristic = char;
     this.#sendSuccess(id);
   }
   async #handleSubscribeCharacteristic(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
     const char = this.#findCharacteristic(conn, args.characteristic_uuid);
     if (!char) {
-      this.#sendError(id, "characteristic_not_found", `Characteristic ${args.characteristic_uuid} not found`);
+      this.#sendError(
+        id,
+        BleProxyErrorCode.CharacteristicNotFound,
+        `Characteristic ${args.characteristic_uuid} not found`
+      );
       return;
     }
     const handle = args.connection_handle;
-    char.on("data", (data) => {
-      log(`[GATT] notify ${args.characteristic_uuid} handle=${handle} ${data.length} bytes`);
-      this.#sendBinaryFrame(BinaryFrameOpcode.Notification, handle, new Uint8Array(data));
-    });
-    await char.subscribeAsync();
-    conn.subscriptions.set(args.characteristic_uuid, char);
+    if (!await this.#subscribe(id, conn, handle, args.characteristic_uuid, char)) {
+      return;
+    }
     log(`[GATT] subscribe ${args.characteristic_uuid} handle=${handle}`);
     this.#sendSuccess(id);
   }
+  /** No-op when `uuid` is already subscribed. Returns false once an error response was sent. */
+  async #subscribe(id, conn, handle, uuid, char) {
+    const key = NobleBleProxyClient.#subscriptionKey(uuid);
+    if (conn.subscriptions.has(key)) {
+      return true;
+    }
+    const onData = this.#notificationForwarder(handle, uuid);
+    char.on("data", onData);
+    try {
+      await char.subscribeAsync();
+    } catch (err) {
+      char.removeListener("data", onData);
+      this.#sendError(id, BleProxyErrorCode.SubscribeFailed, `subscribe(${uuid}): ${err.message}`);
+      return false;
+    }
+    conn.subscriptions.set(key, { characteristic: char, onData });
+    return true;
+  }
+  async #handleWriteAndSubscribe(id, args) {
+    const conn = this.#connections.get(args.connection_handle);
+    if (!conn) {
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
+      return;
+    }
+    const writeChar = this.#findCharacteristic(conn, args.write_uuid);
+    if (!writeChar) {
+      this.#sendError(
+        id,
+        BleProxyErrorCode.CharacteristicNotFound,
+        `Characteristic ${args.write_uuid} not found`
+      );
+      return;
+    }
+    const subscribeChar = this.#findCharacteristic(conn, args.subscribe_uuid);
+    if (!subscribeChar) {
+      this.#sendError(
+        id,
+        BleProxyErrorCode.CharacteristicNotFound,
+        `Characteristic ${args.subscribe_uuid} not found`
+      );
+      return;
+    }
+    const handle = args.connection_handle;
+    const value = Buffer.from(args.write_value, "base64");
+    const withResponse = args.write_response ?? false;
+    log(
+      `[GATT] write_and_subscribe handle=${handle} write=${args.write_uuid} ${value.length} bytes withResponse=${withResponse} subscribe=${args.subscribe_uuid}`
+    );
+    try {
+      await writeChar.writeAsync(value, !withResponse);
+    } catch (err) {
+      this.#sendError(id, BleProxyErrorCode.WriteFailed, `write(${args.write_uuid}): ${err.message}`);
+      return;
+    }
+    conn.lastWriteCharacteristic = writeChar;
+    if (!await this.#subscribe(id, conn, handle, args.subscribe_uuid, subscribeChar)) {
+      return;
+    }
+    this.#sendSuccess(id);
+  }
   async #handleUnsubscribeCharacteristic(id, args) {
     const conn = this.#connections.get(args.connection_handle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${args.connection_handle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${args.connection_handle}`);
       return;
     }
-    const char = conn.subscriptions.get(args.characteristic_uuid);
-    if (!char) {
-      this.#sendError(id, "not_subscribed", `Not subscribed to ${args.characteristic_uuid}`);
+    const key = NobleBleProxyClient.#subscriptionKey(args.characteristic_uuid);
+    const subscription = conn.subscriptions.get(key);
+    if (!subscription) {
+      this.#sendError(id, BleProxyErrorCode.NotSubscribed, `Not subscribed to ${args.characteristic_uuid}`);
       return;
     }
-    await char.unsubscribeAsync();
-    char.removeAllListeners("data");
-    conn.subscriptions.delete(args.characteristic_uuid);
+    await subscription.characteristic.unsubscribeAsync();
+    subscription.characteristic.removeListener("data", subscription.onData);
+    conn.subscriptions.delete(key);
     log(`[GATT] unsubscribe ${args.characteristic_uuid} handle=${args.connection_handle}`);
     this.#sendSuccess(id);
   }
   async #handleRequestMtu(id, connectionHandle, mtu) {
     const conn = this.#connections.get(connectionHandle);
     if (!conn) {
-      this.#sendError(id, "not_connected", `No connection with handle ${connectionHandle}`);
+      this.#sendError(id, BleProxyErrorCode.NotConnected, `No connection with handle ${connectionHandle}`);
       return;
     }
     const actualMtu = conn.peripheral.mtu ?? mtu;
@@ -482,7 +681,13 @@ class NobleBleProxyClient {
   }
   // ─── Binary Frame Handling ───────────────────────────────────────────────
   #handleBinaryFrame(data) {
-    const frame = decodeBinaryFrame(new Uint8Array(data));
+    let frame;
+    try {
+      frame = decodeBinaryFrame(new Uint8Array(data));
+    } catch (err) {
+      warn(`[\u2190BIN] failed to decode binary frame: ${err.message}`);
+      return;
+    }
     log(`[\u2190BIN] opcode=${frame.opcode} handle=${frame.connectionHandle} payload=${frame.payload.length} bytes`);
     if (frame.opcode === BinaryFrameOpcode.WriteData) {
       const conn = this.#connections.get(frame.connectionHandle);
@@ -496,6 +701,88 @@ class NobleBleProxyClient {
     }
   }
   // ─── Helpers ─────────────────────────────────────────────────────────────
+  /** Records the scan the server wants, then drives noble to it. Resolves once that settled. */
+  #requestScan(config) {
+    this.#desiredScan = config;
+    return this.#reconcileScan(++this.#scanGeneration);
+  }
+  /**
+   * Suspends the running scan without forgetting it, so a resume restores the server's filter.
+   * Counted, not a flag: `connect` commands overlap, and the first to finish must not resume a
+   * scan while another is still interviewing — on macOS that reinstates the discovery hang the
+   * pause exists to prevent. Returns the release, which is safe to call more than once.
+   */
+  async #acquireScanPause() {
+    this.#scanPauses++;
+    let released = false;
+    const release = async () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      this.#scanPauses--;
+      await this.#reconcileScan(++this.#scanGeneration);
+    };
+    try {
+      await this.#reconcileScan(++this.#scanGeneration);
+    } catch (err) {
+      await release();
+      throw err;
+    }
+    return release;
+  }
+  /**
+   * Drives noble to the state `generation` asked for, or returns once a later request has taken
+   * ownership of the outcome. noble registers each scan call's completion callback with
+   * `onceExclusive`, which removes the previously registered one, so two overlapping calls leave
+   * the earlier promise unsettled forever — every scan call is therefore serialized here.
+   */
+  #reconcileScan(generation) {
+    return this.#serializeScanOperation(async () => {
+      if (generation !== this.#scanGeneration) {
+        return;
+      }
+      const target = this.#scanPauses > 0 ? void 0 : this.#desiredScan;
+      await this.#callNoble((noble) => noble.stopScanningAsync(), "stopScanning");
+      if (target) {
+        await this.#callNoble((noble) => noble.startScanningAsync(target.serviceUuids, true), "startScanning");
+      }
+    });
+  }
+  #serializeScanOperation(operation) {
+    const result = this.#scanOperations.then(operation);
+    this.#scanOperations = result.catch(() => void 0);
+    return result;
+  }
+  async #callNoble(call, description) {
+    const noble = this.#noble;
+    if (!noble) {
+      return;
+    }
+    const pending = call(noble);
+    pending.catch(() => void 0);
+    await withTimeout(
+      pending,
+      this.#scanOperationTimeoutMs,
+      `${description} did not settle within ${this.#scanOperationTimeoutMs}ms`
+    );
+  }
+  // Forwarded regardless of noble's `isNotification`: on macOS that flag is derived from a
+  // manager-wide pendingRead, so it reads false for a notification racing a read on any
+  // peripheral. Safe only while no subscribed characteristic is ever read.
+  #notificationForwarder(handle, uuid) {
+    return (payload) => {
+      if (payload === null) {
+        return;
+      }
+      log(`[GATT] notify ${uuid} handle=${handle} ${payload.length} bytes`);
+      this.#sendBinaryFrame(BinaryFrameOpcode.Notification, handle, new Uint8Array(payload));
+    };
+  }
+  /** Subscription key; `#findCharacteristic` resolves spellings that differ only in case or dashes. */
+  static #subscriptionKey(uuid) {
+    return uuid.replace(/-/g, "").toLowerCase();
+  }
   #findCharacteristic(conn, uuid) {
     return conn.characteristics.get(uuid) ?? conn.characteristics.get(uuid.toLowerCase()) ?? conn.characteristics.get(uuid.toUpperCase().replace(/-/g, "").toLowerCase());
   }