@onekeyfe/hwk-desktop-noble-ble 1.2.3-alpha.2

package/dist/index.mjs

@@ -0,0 +1,900 @@
+import {
+  THIRD_PARTY_BLE_CHANNELS,
+  THIRD_PARTY_BLE_DEVICE_TTL_MS,
+  THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS,
+  THIRD_PARTY_BLE_SCAN_DURATION_MS,
+  THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS,
+  __require
+} from "./chunk-RNZYQRXV.mjs";
+
+// src/debugLog.ts
+var REDACTED_KEYS = /* @__PURE__ */ new Set([
+  "credential",
+  "credentials",
+  "privateKey",
+  "publicKey",
+  "hostKey",
+  "pin",
+  "passphrase",
+  "hexData",
+  "payload",
+  "bytes"
+]);
+function redactBleDebugLogData(data) {
+  if (!data) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(data)) {
+    out[key] = REDACTED_KEYS.has(key) ? "[redacted]" : value;
+  }
+  return out;
+}
+
+// src/NobleBleHandler.ts
+var DEFAULT_NOBLE_FACTORY = () => {
+  const noble = __require("@stoprocent/noble");
+  return noble;
+};
+var normalizeUuid = (uuid) => uuid.replace(/-/g, "").toLowerCase();
+var matchesPeripheral = (p, match) => {
+  if (!match) return false;
+  const adv = p.advertisement ?? {};
+  const advertised = adv.serviceUuids ?? [];
+  if (match.serviceUuids?.length && advertised.some(
+    (uuid) => match.serviceUuids?.some((wanted) => normalizeUuid(wanted) === normalizeUuid(uuid))
+  )) {
+    return true;
+  }
+  const name = adv.localName;
+  if (!match.namePatterns?.length || !name) return false;
+  return match.namePatterns.every((pattern) => new RegExp(pattern, "i").test(name));
+};
+var peripheralToInfo = (p) => {
+  const adv = p.advertisement ?? {};
+  return {
+    id: p.id,
+    name: adv.localName,
+    localName: adv.localName,
+    rssi: p.rssi,
+    isConnectable: p.connectable ?? null,
+    advertisedServiceUuids: adv.serviceUuids,
+    serviceSolicitationUuids: adv.serviceSolicitationUuids,
+    txPowerLevel: adv.txPowerLevel,
+    manufacturerDataHex: adv.manufacturerData ? Buffer.from(adv.manufacturerData).toString("hex") : void 0,
+    serviceData: adv.serviceData?.map((entry) => ({
+      uuid: entry.uuid,
+      dataHex: Buffer.from(entry.data).toString("hex")
+    })),
+    address: p.address,
+    addressType: p.addressType,
+    state: p.state
+  };
+};
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var BLE_CONNECT_SETTLE_MS = 300;
+var BLE_CONNECT_TIMEOUT_MS = 31e3;
+var BLE_DISCONNECT_TIMEOUT_MS = 2e3;
+var NOBLE_RECOVER_COOLDOWN_MS = 1e4;
+var NobleBleHandler = class {
+  constructor(options = {}) {
+    this._discovered = /* @__PURE__ */ new Map();
+    // id -> last advertisement time (snapshot TTL).
+    this._lastSeen = /* @__PURE__ */ new Map();
+    this._connected = /* @__PURE__ */ new Map();
+    this._scanning = false;
+    this._initialized = false;
+    this._disposed = false;
+    this._nobleInstances = /* @__PURE__ */ new Set();
+    this._pendingCancellations = /* @__PURE__ */ new Set();
+    this._connectAttempts = /* @__PURE__ */ new Set();
+    this._nativeReleased = false;
+    this._factory = options.nobleFactory ?? DEFAULT_NOBLE_FACTORY;
+    this._connectTimeoutMs = options.connectTimeoutMs ?? BLE_CONNECT_TIMEOUT_MS;
+    this._logger = options.logger;
+  }
+  setNotificationListener(handler) {
+    this._onNotification = handler;
+  }
+  setDisconnectedListener(handler) {
+    this._onDeviceDisconnected = handler;
+  }
+  async init() {
+    this._assertActive();
+    if (this._initialized) return;
+    if (this._initPromise) return this._initPromise;
+    this._initPromise = (async () => {
+      this._noble ?? (this._noble = this._factory());
+      this._nobleInstances.add(this._noble);
+      this._discoverHandler ?? (this._discoverHandler = (peripheral) => {
+        this._discovered.set(peripheral.id, peripheral);
+        this._lastSeen.set(peripheral.id, Date.now());
+      });
+      this._noble.removeListener("discover", this._discoverHandler);
+      this._noble.on("discover", this._discoverHandler);
+      await this._waitForPoweredOn(THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS);
+      this._assertActive();
+      this._initialized = true;
+    })();
+    try {
+      await this._initPromise;
+    } finally {
+      this._initPromise = void 0;
+    }
+  }
+  async checkAvailability() {
+    this._assertActive();
+    if (!this._noble) {
+      try {
+        this._noble = this._factory();
+        this._nobleInstances.add(this._noble);
+      } catch {
+        return { available: false, state: "unsupported", initialized: false };
+      }
+    }
+    const state = this._noble?.state ?? "unknown";
+    return {
+      available: state === "poweredOn",
+      state,
+      initialized: this._initialized
+    };
+  }
+  /**
+   * Lazy-start a continuous scan and return the current snapshot immediately.
+   *
+   * Scans UNFILTERED and applies the caller's match criteria in `_snapshot()` instead. A
+   * service-UUID filter cannot be used here: noble's Windows backend applies it
+   * per RECEIVED PACKET (`BLEManager::OnScanResult`, lib/win/src/ble_manager.cc),
+   * and a Safe 7's ADV packet carries only its name — the service UUID lives in
+   * the scan response, which arrives as a separate, irregularly-timed event. So
+   * a filtered scan drops every ADV packet and the device appears to be
+   * undiscoverable for minutes at a time while it is plainly on air. (OneKey's
+   * own devices do advertise their service UUID, which is why the same filter is
+   * safe in `hd-transport-electron` and was copied here by mistake.)
+   */
+  async scan(options) {
+    await this.init();
+    if (!this._scanning) {
+      this._scanning = true;
+      try {
+        await this._requireNoble().startScanningAsync([], true);
+        this._log("warn", "scan.start", {
+          ignoredServiceUuids: options?.serviceUuids,
+          allowDuplicates: true
+        });
+      } catch (error) {
+        this._scanning = false;
+        this._log("warn", "scan.start.error", { error: String(error) });
+        await this._recoverNobleIfStuck(String(error));
+      }
+    }
+    this._assertActive();
+    this._armIdleStop();
+    const devices = this._snapshot(options);
+    if (devices.length === 0) {
+      this._log("warn", "scan.empty", {
+        raw: this._discovered.size,
+        kept: 0,
+        named: [...this._discovered.values()].filter((p) => p.advertisement?.localName).length
+      });
+    }
+    return devices;
+  }
+  /**
+   * Current in-range devices for the asking vendor, dropping any that aged past
+   * the liveness TTL. The match test replaces the service-UUID scan filter we cannot use
+   * (see `scan`): it matches the name from the ADV packet, or the service UUID
+   * once a scan response has merged into the same peripheral.
+   *
+   * Note the TTL only prunes what the CALLER sees. `_discovered` is a cache, not
+   * the source of truth for reachability — a device missing from here can still
+   * be connected to by id (`_directConnect`).
+   */
+  _snapshot(options) {
+    const now = Date.now();
+    const result = [];
+    for (const [id, peripheral] of this._discovered) {
+      if (now - (this._lastSeen.get(id) ?? 0) > THIRD_PARTY_BLE_DEVICE_TTL_MS) {
+        this._discovered.delete(id);
+        this._lastSeen.delete(id);
+        continue;
+      }
+      const match = options?.match ?? { serviceUuids: options?.serviceUuids };
+      if (!matchesPeripheral(peripheral, match)) continue;
+      result.push(peripheralToInfo(peripheral));
+    }
+    for (const [id, entry] of this._connected) {
+      if (entry.vendor !== options?.vendor) continue;
+      if (result.some((info) => info.id === id)) continue;
+      result.push(peripheralToInfo(entry.peripheral));
+    }
+    return result;
+  }
+  /** A noble instance with its own bindings, so a stuck one can be replaced. */
+  _createFreshNoble() {
+    const candidate = this._factory();
+    return typeof candidate.withBindings === "function" ? candidate.withBindings() : candidate;
+  }
+  /**
+   * Rebuild noble when its adapter state is stuck. Re-enumerating the Windows
+   * BLE stack (pairing, or removing the device from OS settings) can catch
+   * noble's RadioWatcher mid-churn: it latches `unsupported` and never
+   * re-evaluates, so every later scan fails until the process restarts. Fresh
+   * bindings restart that watcher, which is the in-process equivalent of the
+   * app restart that is otherwise the only cure.
+   */
+  async _recoverNobleIfStuck(reason) {
+    if (this._disposed) return;
+    const state = this._noble?.state;
+    if (state === "poweredOn" || !this._initialized) return;
+    if (this._connected.size > 0) {
+      this._log("warn", "noble.recover.skip", {
+        reason,
+        state,
+        connected: this._connected.size
+      });
+      return;
+    }
+    const now = Date.now();
+    if (this._lastNobleRecoverAt && now - this._lastNobleRecoverAt < NOBLE_RECOVER_COOLDOWN_MS) {
+      return;
+    }
+    this._lastNobleRecoverAt = now;
+    this._log("warn", "noble.recover.start", { reason, state });
+    try {
+      const previous = this._noble;
+      if (previous && this._discoverHandler) {
+        previous.removeListener("discover", this._discoverHandler);
+      }
+      const fresh = this._createFreshNoble();
+      this._noble = fresh;
+      this._nobleInstances.add(fresh);
+      if (this._discoverHandler) {
+        fresh.on("discover", this._discoverHandler);
+      }
+      this._scanning = false;
+      this._discovered.clear();
+      this._lastSeen.clear();
+      await this._waitForPoweredOn(THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS);
+      this._log("warn", "noble.recover.done", { state: this._noble?.state });
+    } catch (error) {
+      this._log("warn", "noble.recover.error", { error: String(error) });
+    }
+  }
+  _armIdleStop() {
+    if (this._disposed) return;
+    this._clearIdleStop();
+    this._idleStopTimer = setTimeout(() => {
+      void this._stopContinuousScan();
+    }, THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS);
+  }
+  _clearIdleStop() {
+    if (this._idleStopTimer) {
+      clearTimeout(this._idleStopTimer);
+      this._idleStopTimer = void 0;
+    }
+  }
+  /** Stop scanning but keep the discovered cache (used before connect). */
+  async _pauseScan() {
+    this._clearIdleStop();
+    if (!this._scanning) return;
+    this._scanning = false;
+    await this._noble?.stopScanningAsync().catch(() => void 0);
+  }
+  /** Stop scanning and forget discovered devices (idle timeout / teardown). */
+  async _stopContinuousScan() {
+    await this._pauseScan();
+    this._discovered.clear();
+    this._lastSeen.clear();
+  }
+  /**
+   * Stops the process-wide scan no matter which vendor asked. Scan *results*
+   * are filtered per vendor, but the radio is not: one vendor's stopScan ends
+   * the other's discovery too. That is safe only because the adapter job queue
+   * serializes discovery across vendors, so two are never scanning at once.
+   * Anything that breaks that — a background presence probe, say — needs
+   * per-vendor refcounting here first.
+   */
+  async stopScan() {
+    await this._stopContinuousScan();
+  }
+  /**
+   * Look up a previously-scanned device by id (no extra BLE traffic).
+   * Returns null if the device hasn't been seen by a recent scan.
+   */
+  getDevice(id) {
+    const p = this._discovered.get(id);
+    if (!p) return null;
+    return peripheralToInfo(p);
+  }
+  /**
+   * Read the current RSSI (in dBm) for a connected peripheral. Requires
+   * the device to be connected — noble can't read RSSI off a scan-only
+   * peripheral. Falls back to the cached scan-time rssi when the noble
+   * peripheral doesn't expose updateRssiAsync.
+   */
+  async readRssi(id) {
+    const entry = this._requireEntry(id);
+    if (entry.peripheral.updateRssiAsync) {
+      return entry.peripheral.updateRssiAsync();
+    }
+    return entry.peripheral.rssi;
+  }
+  /**
+   * Abort the in-flight pairing flow: abandon a connect that is still running,
+   * stop scanning, disconnect every peripheral the host currently has open.
+   * Caller is responsible for surfacing the cancellation to the upper UI layer.
+   *
+   * Abandoning the connect is what actually ends the flow. Pairing happens
+   * inside connectAsync and the entry only reaches _connected after service
+   * discovery, so the loop below never sees the device being paired — without
+   * the abandon the caller waits out the full connect timeout, which is sized
+   * to the OS pairing window and so feels like a hang.
+   */
+  async cancelPairing() {
+    const attempt = this._activeConnect;
+    if (attempt) {
+      this._activeConnect = void 0;
+      attempt.abandon(new Error(`connect cancelled: ${attempt.id}`));
+    }
+    await this.stopScan();
+    for (const id of Array.from(this._connected.keys())) {
+      await this.disconnect(id).catch(() => void 0);
+    }
+  }
+  /**
+   * Scan for a specific peripheral id and resolve THE MOMENT it's discovered,
+   * stopping the scan immediately (don't wait out the full window). The fast
+   * reconnect path for a stored connectId when the device IS advertising.
+   *
+   * This used to be the only reconnect path, on two assumptions that are both
+   * false: that noble cannot connect by id without a scan (it can — see
+   * `_directConnect`), and that "the device advertises continuously" (a bonded
+   * Safe 7 does not — it holds the link and goes silent). Callers must fall
+   * back to `_directConnect` when this returns undefined.
+   */
+  async _scanUntilFound(id, timeoutMs) {
+    await this.init();
+    const existing = this._discovered.get(id);
+    if (existing) return existing;
+    const noble = this._requireNoble();
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = (p) => {
+        if (done) return;
+        done = true;
+        this._pendingCancellations.delete(cancel);
+        clearTimeout(timer);
+        noble.removeListener("discover", onDiscover);
+        void noble.stopScanningAsync().catch(() => void 0);
+        resolve(p);
+      };
+      const onDiscover = (peripheral) => {
+        this._discovered.set(peripheral.id, peripheral);
+        if (peripheral.id === id) finish(peripheral);
+      };
+      const timer = setTimeout(() => finish(this._discovered.get(id)), timeoutMs);
+      const cancel = () => finish();
+      this._pendingCancellations.add(cancel);
+      noble.on("discover", onDiscover);
+      void noble.startScanningAsync([], false).catch(() => finish());
+    });
+  }
+  /**
+   * Connect by id with no scan and no advertisement.
+   *
+   * This is the ONLY path that reaches a device which is connected but silent.
+   * A linked peripheral stops advertising while it HOLDS A LINK (standard BLE; a Safe 7's
+   * screen says "wait connection") — field-verified: bonding/THP handshake
+   * alone does NOT silence it, holding the connection does. So while a link is
+   * up, no amount of scanning will rediscover it — `_scanUntilFound` alone
+   * dead-ends with "device not found" on a device that is sitting right there,
+   * connected and reachable.
+   *
+   * noble supports this: `noble.connectAsync(id)` needs no prior `discover`,
+   * because both native backends materialize the peripheral themselves (Windows
+   * synthesizes one for an unknown address, macOS retrieves it by identifier)
+   * and then emit a `discover`, which our own handler turns back into a
+   * `_discovered` entry. OneKey's own noble handler calls this "direct
+   * connection mode"; Trezor Suite's equivalent is asking the adapter for its
+   * peripheral list instead of keeping a cache.
+   *
+   * Returns undefined (not throw) so the caller reports the normal
+   * "device not found" rather than a confusing noble-internal error.
+   */
+  async _directConnect(id) {
+    const noble = this._requireNoble();
+    if (typeof noble.connectAsync !== "function") {
+      this._log("warn", "connect.direct.unavailable", { id });
+      return void 0;
+    }
+    this._log("warn", "connect.direct.start", { id });
+    const startedAt = Date.now();
+    try {
+      const peripheral = await noble.connectAsync(id);
+      const resolved = peripheral ?? this._discovered.get(id);
+      this._log("warn", "connect.direct.done", {
+        id,
+        elapsedMs: Date.now() - startedAt,
+        found: Boolean(resolved),
+        // The one field that says whether the fix actually worked: an open link,
+        // or merely an object. Anything other than 'connected' is a failure that
+        // would otherwise surface later as a confusing service-discovery error.
+        state: resolved?.state,
+        fromNoble: Boolean(peripheral)
+      });
+      return resolved;
+    } catch (error) {
+      this._log("warn", "connect.direct.error", {
+        id,
+        elapsedMs: Date.now() - startedAt,
+        error: String(error)
+      });
+      return void 0;
+    }
+  }
+  // noble's disconnectAsync hangs on a peripheral whose connect just failed (it
+  // waits for a CoreBluetooth disconnect event that never comes); bound it so a
+  // cleanup disconnect can't hang the connect flow.
+  async _safeDisconnect(peripheral) {
+    if (this._nativeReleased) return;
+    let timeout;
+    try {
+      await Promise.race([
+        peripheral.disconnectAsync().catch(() => void 0),
+        new Promise((resolve) => {
+          timeout = setTimeout(resolve, BLE_DISCONNECT_TIMEOUT_MS);
+        })
+      ]);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // noble has no connect timeout, so a stale bond hangs anywhere — connectAsync
+  // OR the post-connect (encrypted) service discovery. One overall timeout
+  // covers the whole flow. Two distinct failures reach the connector: a `timed
+  // out` reject (device unreachable) vs a connectAsync `connection failed`
+  // reject (link refused / stale bond) — mapped to different error codes there.
+  async connect(id, options) {
+    if (!options || !options.vendor || ![options.serviceUuid, options.writeUuid, options.notifyUuid].every(
+      (uuid) => typeof uuid === "string" && /^[0-9a-f]{32}$/i.test(normalizeUuid(uuid))
+    )) {
+      throw new Error("Invalid BLE GATT profile");
+    }
+    this._assertActive();
+    const claim = { abandoned: false };
+    let abandon;
+    const abandoned = new Promise((_, reject) => {
+      abandon = (error) => {
+        claim.abandoned = true;
+        reject(error);
+      };
+    });
+    const timer = setTimeout(
+      () => abandon(new Error(`connect timed out after ${this._connectTimeoutMs}ms`)),
+      this._connectTimeoutMs
+    );
+    const attempt = {
+      id,
+      abandon,
+      cancelNative: () => claim.cancelNative?.(),
+      settled: Promise.resolve(void 0)
+    };
+    this._activeConnect = attempt;
+    this._connectAttempts.add(attempt);
+    const nativeOperation = this._connectInner(id, claim, options);
+    const caller = (async () => {
+      try {
+        return await Promise.race([nativeOperation, abandoned]);
+      } catch (error) {
+        const peripheral = this._discovered.get(id);
+        if (peripheral) await this._safeDisconnect(peripheral);
+        throw error;
+      } finally {
+        clearTimeout(timer);
+        if (this._activeConnect === attempt) this._activeConnect = void 0;
+      }
+    })();
+    attempt.settled = Promise.allSettled([nativeOperation, caller]).finally(() => {
+      this._connectAttempts.delete(attempt);
+    });
+    return caller;
+  }
+  async _connectInner(id, claim, options) {
+    await this.init();
+    await this._pauseScan();
+    await delay(BLE_CONNECT_SETTLE_MS);
+    this._assertActive();
+    let route = "cache";
+    let peripheral = this._discovered.get(id);
+    if (!peripheral) {
+      route = "scan";
+      peripheral = await this._scanUntilFound(id, THIRD_PARTY_BLE_SCAN_DURATION_MS);
+    }
+    if (!peripheral) {
+      route = "direct";
+    }
+    if (!peripheral) {
+      const native2 = this._requireNoble();
+      claim.cancelNative = () => native2.cancelConnect?.(id);
+      peripheral = await this._directConnect(id);
+    }
+    if (!peripheral) {
+      this._log("warn", "connect.notFound", {
+        id,
+        route: "none",
+        discoveredCount: this._discovered.size
+      });
+      throw new Error(`BLE device not found: ${id}`);
+    }
+    const abortIfAbandoned = async (stage) => {
+      if (!claim.abandoned && !this._disposed) return;
+      if (peripheral && peripheral.state === "connected" && !this._connected.has(id)) {
+        await this._safeDisconnect(peripheral);
+      }
+      this._log("warn", "connect.abandoned", { id, route, stage });
+      throw new Error(`connect abandoned after timeout: ${id}`);
+    };
+    await abortIfAbandoned("resolve");
+    const wasConnected = peripheral.state === "connected";
+    const connectingPeripheral = peripheral;
+    const native = this._requireNoble();
+    claim.cancelNative = () => {
+      if (connectingPeripheral.state === "connecting" && connectingPeripheral.cancelConnect) {
+        connectingPeripheral.cancelConnect();
+      } else {
+        native.cancelConnect?.(id);
+      }
+    };
+    this._log("warn", "connect.route", {
+      id,
+      route,
+      wasConnected,
+      name: peripheral.advertisement?.localName
+    });
+    if (!wasConnected) {
+      await peripheral.connectAsync();
+      await abortIfAbandoned("link");
+    }
+    try {
+      const uuids = {
+        service: options.serviceUuid,
+        write: options.writeUuid,
+        notify: options.notifyUuid
+      };
+      const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
+        [uuids.service],
+        [uuids.write, uuids.notify]
+      );
+      const writeUuid = normalizeUuid(uuids.write);
+      const notifyUuid = normalizeUuid(uuids.notify);
+      const writeChar = characteristics.find((c) => normalizeUuid(c.uuid) === writeUuid);
+      const notifyChar = characteristics.find((c) => normalizeUuid(c.uuid) === notifyUuid);
+      if (!writeChar || !notifyChar) {
+        throw new Error(`BLE characteristics not found on device ${id}`);
+      }
+      await abortIfAbandoned("discovery");
+      const disconnectHandler = () => {
+        if (this._connected.get(id)?.disconnectHandler !== disconnectHandler) return;
+        this._cleanupDevice(
+          id,
+          /* unexpected */
+          true
+        );
+      };
+      peripheral.on("disconnect", disconnectHandler);
+      this._connected.set(id, {
+        peripheral,
+        writeChar,
+        notifyChar,
+        disconnectHandler,
+        vendor: options.vendor,
+        write: options.write
+      });
+      this._log("info", "connect.done", { id, name: peripheral.advertisement.localName });
+      return { id, name: peripheral.advertisement.localName };
+    } catch (error) {
+      if (!wasConnected) await this._safeDisconnect(peripheral);
+      throw error;
+    }
+  }
+  async disconnect(id) {
+    const entry = this._connected.get(id);
+    if (!entry) return;
+    if (entry.disconnectHandler) {
+      entry.peripheral.removeListener("disconnect", entry.disconnectHandler);
+    }
+    try {
+      await entry.peripheral.disconnectAsync();
+    } catch (error) {
+      this._log("warn", "disconnect.error", { id, error: String(error) });
+    }
+    this._cleanupDevice(
+      id,
+      /* unexpected */
+      false
+    );
+  }
+  async subscribe(id) {
+    const entry = this._requireEntry(id);
+    if (!entry.notifyChar) throw new Error(`BLE notify characteristic missing for ${id}`);
+    if (entry.notifyHandler) return;
+    const handler = (data) => {
+      this._onNotification?.(id, data.toString("hex"));
+    };
+    entry.notifyHandler = handler;
+    entry.notifyChar.on("data", handler);
+    await entry.notifyChar.subscribeAsync();
+  }
+  async unsubscribe(id) {
+    const entry = this._connected.get(id);
+    if (!entry?.notifyChar) return;
+    if (entry.notifyHandler) {
+      entry.notifyChar.removeListener("data", entry.notifyHandler);
+      entry.notifyHandler = void 0;
+    }
+    try {
+      await entry.notifyChar.unsubscribeAsync();
+    } catch (error) {
+      this._log("warn", "unsubscribe.error", { id, error: String(error) });
+    }
+  }
+  async write(id, hexData) {
+    const entry = this._requireEntry(id);
+    if (!entry.writeChar) throw new Error(`BLE write characteristic missing for ${id}`);
+    const buffer = Buffer.from(hexData, "hex");
+    const framing = entry.write;
+    if (!framing) throw new Error(`No BLE write framing recorded for ${id}`);
+    if (framing.mode === "raw") {
+      const maxLength = framing.maxLength ?? buffer.length;
+      if (!/^(?:[0-9a-f]{2})+$/i.test(hexData) || buffer.length > maxLength) {
+        throw new Error(`Invalid BLE frame for ${entry.vendor ?? "device"}`);
+      }
+      await entry.writeChar.writeAsync(buffer, false);
+      return;
+    }
+    const chunkSize = framing.chunkSize;
+    if (!chunkSize) throw new Error(`Padded BLE writes need a chunkSize for ${id}`);
+    for (let offset = 0; offset < buffer.length; offset += chunkSize) {
+      this._assertActive();
+      const slice = buffer.subarray(offset, offset + chunkSize);
+      const chunk = Buffer.alloc(chunkSize);
+      slice.copy(chunk);
+      await entry.writeChar.writeAsync(chunk, false);
+      if (offset + chunkSize < buffer.length && framing.chunkDelayMs) {
+        await delay(framing.chunkDelayMs);
+      }
+    }
+  }
+  /** Retire a renderer's handler without stopping a process-wide native manager. */
+  dispose() {
+    if (this._disposePromise) return this._disposePromise;
+    this._disposed = true;
+    this._clearIdleStop();
+    this._scanning = false;
+    this._onNotification = void 0;
+    this._onDeviceDisconnected = void 0;
+    const connections = Array.from(this._connectAttempts);
+    for (const attempt of connections) {
+      attempt.abandon(new Error("Desktop BLE is shutting down"));
+      try {
+        attempt.cancelNative();
+      } catch (error) {
+        this._log("warn", "dispose.cancelConnect.error", { error: String(error) });
+      }
+    }
+    for (const cancel of this._pendingCancellations) cancel();
+    if (this._noble && this._discoverHandler) {
+      this._noble.removeListener("discover", this._discoverHandler);
+    }
+    const entries = Array.from(this._connected.entries());
+    for (const [id, entry] of entries) {
+      if (entry.disconnectHandler) {
+        entry.peripheral.removeListener("disconnect", entry.disconnectHandler);
+      }
+      this._cleanupDevice(id, false);
+    }
+    let timeout;
+    this._disposePromise = (async () => {
+      try {
+        await Promise.race([
+          Promise.allSettled([
+            ...connections.map((attempt) => attempt.settled),
+            ...Array.from(this._nobleInstances, async (instance) => instance.stopScanningAsync()),
+            ...entries.map(async ([, entry]) => {
+              let unsubscribeTimeout;
+              try {
+                await Promise.race([
+                  entry.notifyChar?.unsubscribeAsync().catch(() => void 0),
+                  new Promise((resolve) => {
+                    unsubscribeTimeout = setTimeout(resolve, 250);
+                  })
+                ]);
+              } finally {
+                clearTimeout(unsubscribeTimeout);
+                await this._safeDisconnect(entry.peripheral);
+              }
+            })
+          ]),
+          new Promise((resolve) => {
+            timeout = setTimeout(() => {
+              this._log("warn", "dispose.timeout");
+              resolve();
+            }, 3500);
+          })
+        ]);
+      } finally {
+        clearTimeout(timeout);
+        this._discovered.clear();
+        this._lastSeen.clear();
+        this._initialized = false;
+      }
+    })();
+    return this._disposePromise;
+  }
+  /**
+   * Terminal native release, including instances replaced by adapter recovery.
+   * A host sharing Noble must defer stop() until all transports have disposed,
+   * and deduplicate instances passed to releaseNoble across those transports.
+   */
+  disposeForAppQuit(releaseNoble = (instance) => instance.stop?.()) {
+    if (!this._releasePromise) {
+      this._releasePromise = this.dispose().finally(() => {
+        this._nativeReleased = true;
+        let releaseError;
+        for (const instance of this._nobleInstances) {
+          try {
+            releaseNoble(instance);
+          } catch (error) {
+            releaseError = error instanceof Error ? error : new Error(String(error));
+          }
+        }
+        this._nobleInstances.clear();
+        if (releaseError) throw releaseError;
+        this._log("info", "dispose.native.done");
+      });
+    }
+    return this._releasePromise;
+  }
+  _assertActive() {
+    if (this._disposed) throw new Error("Desktop BLE is shutting down");
+  }
+  _cleanupDevice(id, unexpected) {
+    const entry = this._connected.get(id);
+    if (!entry) return;
+    if (entry.notifyChar && entry.notifyHandler) {
+      entry.notifyChar.removeListener("data", entry.notifyHandler);
+    }
+    if (entry.disconnectHandler) {
+      entry.peripheral.removeListener("disconnect", entry.disconnectHandler);
+    }
+    this._connected.delete(id);
+    if (unexpected) {
+      this._log("warn", "disconnect.unexpected", { id });
+      this._onDeviceDisconnected?.(id);
+    }
+  }
+  _requireEntry(id) {
+    this._assertActive();
+    const entry = this._connected.get(id);
+    if (!entry) throw new Error(`BLE device is not connected: ${id}`);
+    return entry;
+  }
+  _requireNoble() {
+    this._assertActive();
+    if (!this._noble) throw new Error("Desktop BLE: noble was not initialized");
+    return this._noble;
+  }
+  async _waitForPoweredOn(timeoutMs) {
+    const noble = this._requireNoble();
+    if (noble.state === "poweredOn") return;
+    await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        noble.removeListener("stateChange", handler);
+        this._pendingCancellations.delete(cancel);
+      };
+      const cancel = () => {
+        cleanup();
+        reject(new Error("Desktop BLE is shutting down"));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            `Desktop BLE: noble did not reach poweredOn within ${timeoutMs}ms (last state: ${noble.state})`
+          )
+        );
+      }, timeoutMs);
+      const handler = (state) => {
+        if (state === "poweredOn") {
+          cleanup();
+          resolve();
+        } else if (state === "unsupported" || state === "unauthorized") {
+          cleanup();
+          reject(new Error(`Desktop BLE: noble state ${state}`));
+        }
+      };
+      this._pendingCancellations.add(cancel);
+      noble.on("stateChange", handler);
+    });
+  }
+  _log(level, event, data) {
+    this._logger?.({
+      level,
+      scope: "desktop-noble-ble",
+      event,
+      data: redactBleDebugLogData(data)
+    });
+  }
+};
+
+// src/main.ts
+var DEFAULT_IPC_MAIN = () => {
+  const { ipcMain } = __require("electron");
+  return ipcMain;
+};
+function initThirdPartyBleSupport(webContents, options = {}) {
+  const ipcMain = options.ipcMain ?? DEFAULT_IPC_MAIN();
+  const handler = new NobleBleHandler(options);
+  let disposed = false;
+  handler.setNotificationListener((id, hexData) => {
+    webContents.send(THIRD_PARTY_BLE_CHANNELS.notification, id, hexData);
+  });
+  handler.setDisconnectedListener((id) => {
+    webContents.send(THIRD_PARTY_BLE_CHANNELS.disconnected, id);
+  });
+  const handle = (channel, fn) => {
+    ipcMain.handle(channel, async (_event, ...args) => {
+      if (disposed) throw new Error("Third-party BLE is shutting down");
+      return fn(...args);
+    });
+  };
+  handle(
+    THIRD_PARTY_BLE_CHANNELS.scan,
+    (options2) => handler.scan(options2)
+  );
+  handle(THIRD_PARTY_BLE_CHANNELS.stopScan, () => handler.stopScan());
+  handle(
+    THIRD_PARTY_BLE_CHANNELS.connect,
+    (id, options2) => handler.connect(id, options2)
+  );
+  handle(THIRD_PARTY_BLE_CHANNELS.disconnect, (id) => handler.disconnect(id));
+  handle(
+    THIRD_PARTY_BLE_CHANNELS.write,
+    (id, hexData) => handler.write(id, hexData)
+  );
+  handle(THIRD_PARTY_BLE_CHANNELS.subscribe, (id) => handler.subscribe(id));
+  handle(THIRD_PARTY_BLE_CHANNELS.unsubscribe, (id) => handler.unsubscribe(id));
+  handle(THIRD_PARTY_BLE_CHANNELS.availability, () => handler.checkAvailability());
+  handle(THIRD_PARTY_BLE_CHANNELS.getDevice, (id) => handler.getDevice(id));
+  handle(THIRD_PARTY_BLE_CHANNELS.readRssi, (id) => handler.readRssi(id));
+  handle(THIRD_PARTY_BLE_CHANNELS.cancelPairing, () => handler.cancelPairing());
+  const removeHandlers = () => {
+    if (disposed) return;
+    disposed = true;
+    for (const channel of Object.values(THIRD_PARTY_BLE_CHANNELS)) {
+      ipcMain.removeHandler(channel);
+    }
+  };
+  return {
+    handler,
+    dispose: () => {
+      removeHandlers();
+      return handler.dispose();
+    },
+    disposeForAppQuit: (releaseNoble) => {
+      removeHandlers();
+      return handler.disposeForAppQuit(releaseNoble);
+    }
+  };
+}
+export {
+  NobleBleHandler,
+  THIRD_PARTY_BLE_CHANNELS,
+  THIRD_PARTY_BLE_DEVICE_TTL_MS,
+  THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS,
+  THIRD_PARTY_BLE_SCAN_DURATION_MS,
+  THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS,
+  initThirdPartyBleSupport,
+  redactBleDebugLogData
+};
+//# sourceMappingURL=index.mjs.map