@onekeyfe/hwk-desktop-noble-ble 1.2.3-alpha.4 → 1.2.5-alpha.0

package/dist/{chunk-RNZYQRXV.mjs → chunk-A5AENDC2.mjs}

@@ -36,4 +36,4 @@ export {
   THIRD_PARTY_BLE_DEVICE_TTL_MS,
   THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS
 };
-//# sourceMappingURL=chunk-RNZYQRXV.mjs.map
+//# sourceMappingURL=chunk-A5AENDC2.mjs.map

package/dist/chunk-A5AENDC2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Renderer/main IPC channels shared by every third-party BLE vendor; prefixed to\n * avoid clashing with the OneKey handler (`$onekey-noble-ble-*`) in one app.\n */\nexport const THIRD_PARTY_BLE_CHANNELS = {\n  scan: '$onekey-3p-ble-scan',\n  stopScan: '$onekey-3p-ble-stop-scan',\n  connect: '$onekey-3p-ble-connect',\n  disconnect: '$onekey-3p-ble-disconnect',\n  write: '$onekey-3p-ble-write',\n  subscribe: '$onekey-3p-ble-subscribe',\n  unsubscribe: '$onekey-3p-ble-unsubscribe',\n  availability: '$onekey-3p-ble-availability',\n  getDevice: '$onekey-3p-ble-get-device',\n  readRssi: '$onekey-3p-ble-read-rssi',\n  cancelPairing: '$onekey-3p-ble-cancel-pairing',\n  /** push event: main → renderer with assembled BLE notification payload */\n  notification: '$onekey-3p-ble-notification',\n  /** push event: main → renderer when device disconnects unexpectedly */\n  disconnected: '$onekey-3p-ble-disconnected',\n} as const;\n\nexport type ThirdPartyBleChannel =\n  (typeof THIRD_PARTY_BLE_CHANNELS)[keyof typeof THIRD_PARTY_BLE_CHANNELS];\n\n/** Reconnect scan window for `connect(id)`. */\nexport const THIRD_PARTY_BLE_SCAN_DURATION_MS = 5_000;\n\n/** Continuous scan auto-stops this long after the last poll (reset, not accumulated). */\nexport const THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS = 10_000;\n\n/** Drop a device from the snapshot if it hasn't re-advertised within this window. */\nexport const THIRD_PARTY_BLE_DEVICE_TTL_MS = 5_000;\n\n/** Time we'll wait for noble to reach `poweredOn` before failing init. */\nexport const THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS = 10_000;\n"],"mappings":";;;;;;;;AAIO,IAAM,2BAA2B;AAAA,EACtC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,aAAa;AAAA,EACb,cAAc;AAAA,EACd,WAAW;AAAA,EACX,UAAU;AAAA,EACV,eAAe;AAAA;AAAA,EAEf,cAAc;AAAA;AAAA,EAEd,cAAc;AAChB;AAMO,IAAM,mCAAmC;AAGzC,IAAM,oCAAoC;AAG1C,IAAM,gCAAgC;AAGtC,IAAM,sCAAsC;","names":[]}

package/dist/constants.d.mts

@@ -1,10 +1,6 @@
 /**
- * IPC channel names exchanged between renderer and main process, shared by
- * every third-party vendor that talks BLE on desktop — Ledger reaches the same
- * handler through `desktopApi.thirdPartyBle`, it does not register its own.
- * Namespaced under `$onekey-3p-ble-…` to avoid clashing with the
- * existing OneKey BLE handler (`$onekey-noble-ble-…`) when both run in
- * the same Electron app.
+ * Renderer/main IPC channels shared by every third-party BLE vendor; prefixed to
+ * avoid clashing with the OneKey handler (`$onekey-noble-ble-*`) in one app.
  */
 declare const THIRD_PARTY_BLE_CHANNELS: {
     readonly scan: "$onekey-3p-ble-scan";

package/dist/constants.d.ts

@@ -1,10 +1,6 @@
 /**
- * IPC channel names exchanged between renderer and main process, shared by
- * every third-party vendor that talks BLE on desktop — Ledger reaches the same
- * handler through `desktopApi.thirdPartyBle`, it does not register its own.
- * Namespaced under `$onekey-3p-ble-…` to avoid clashing with the
- * existing OneKey BLE handler (`$onekey-noble-ble-…`) when both run in
- * the same Electron app.
+ * Renderer/main IPC channels shared by every third-party BLE vendor; prefixed to
+ * avoid clashing with the OneKey handler (`$onekey-noble-ble-*`) in one app.
  */
 declare const THIRD_PARTY_BLE_CHANNELS: {
     readonly scan: "$onekey-3p-ble-scan";

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["/**\n * IPC channel names exchanged between renderer and main process, shared by\n * every third-party vendor that talks BLE on desktop — Ledger reaches the same\n * handler through `desktopApi.thirdPartyBle`, it does not register its own.\n * Namespaced under `$onekey-3p-ble-…` to avoid clashing with the\n * existing OneKey BLE handler (`$onekey-noble-ble-…`) when both run in\n * the same Electron app.\n */\nexport const THIRD_PARTY_BLE_CHANNELS = {\n  scan: '$onekey-3p-ble-scan',\n  stopScan: '$onekey-3p-ble-stop-scan',\n  connect: '$onekey-3p-ble-connect',\n  disconnect: '$onekey-3p-ble-disconnect',\n  write: '$onekey-3p-ble-write',\n  subscribe: '$onekey-3p-ble-subscribe',\n  unsubscribe: '$onekey-3p-ble-unsubscribe',\n  availability: '$onekey-3p-ble-availability',\n  getDevice: '$onekey-3p-ble-get-device',\n  readRssi: '$onekey-3p-ble-read-rssi',\n  cancelPairing: '$onekey-3p-ble-cancel-pairing',\n  /** push event: main → renderer with assembled BLE notification payload */\n  notification: '$onekey-3p-ble-notification',\n  /** push event: main → renderer when device disconnects unexpectedly */\n  disconnected: '$onekey-3p-ble-disconnected',\n} as const;\n\nexport type ThirdPartyBleChannel =\n  (typeof THIRD_PARTY_BLE_CHANNELS)[keyof typeof THIRD_PARTY_BLE_CHANNELS];\n\n/** Reconnect scan window for `connect(id)`. */\nexport const THIRD_PARTY_BLE_SCAN_DURATION_MS = 5_000;\n\n/** Continuous scan auto-stops this long after the last poll (reset, not accumulated). */\nexport const THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS = 10_000;\n\n/** Drop a device from the snapshot if it hasn't re-advertised within this window. */\nexport const THIRD_PARTY_BLE_DEVICE_TTL_MS = 5_000;\n\n/** Time we'll wait for noble to reach `poweredOn` before failing init. */\nexport const THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS = 10_000;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQO,IAAM,2BAA2B;AAAA,EACtC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,aAAa;AAAA,EACb,cAAc;AAAA,EACd,WAAW;AAAA,EACX,UAAU;AAAA,EACV,eAAe;AAAA;AAAA,EAEf,cAAc;AAAA;AAAA,EAEd,cAAc;AAChB;AAMO,IAAM,mCAAmC;AAGzC,IAAM,oCAAoC;AAG1C,IAAM,gCAAgC;AAGtC,IAAM,sCAAsC;","names":[]}
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Renderer/main IPC channels shared by every third-party BLE vendor; prefixed to\n * avoid clashing with the OneKey handler (`$onekey-noble-ble-*`) in one app.\n */\nexport const THIRD_PARTY_BLE_CHANNELS = {\n  scan: '$onekey-3p-ble-scan',\n  stopScan: '$onekey-3p-ble-stop-scan',\n  connect: '$onekey-3p-ble-connect',\n  disconnect: '$onekey-3p-ble-disconnect',\n  write: '$onekey-3p-ble-write',\n  subscribe: '$onekey-3p-ble-subscribe',\n  unsubscribe: '$onekey-3p-ble-unsubscribe',\n  availability: '$onekey-3p-ble-availability',\n  getDevice: '$onekey-3p-ble-get-device',\n  readRssi: '$onekey-3p-ble-read-rssi',\n  cancelPairing: '$onekey-3p-ble-cancel-pairing',\n  /** push event: main → renderer with assembled BLE notification payload */\n  notification: '$onekey-3p-ble-notification',\n  /** push event: main → renderer when device disconnects unexpectedly */\n  disconnected: '$onekey-3p-ble-disconnected',\n} as const;\n\nexport type ThirdPartyBleChannel =\n  (typeof THIRD_PARTY_BLE_CHANNELS)[keyof typeof THIRD_PARTY_BLE_CHANNELS];\n\n/** Reconnect scan window for `connect(id)`. */\nexport const THIRD_PARTY_BLE_SCAN_DURATION_MS = 5_000;\n\n/** Continuous scan auto-stops this long after the last poll (reset, not accumulated). */\nexport const THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS = 10_000;\n\n/** Drop a device from the snapshot if it hasn't re-advertised within this window. */\nexport const THIRD_PARTY_BLE_DEVICE_TTL_MS = 5_000;\n\n/** Time we'll wait for noble to reach `poweredOn` before failing init. */\nexport const THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS = 10_000;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,IAAM,2BAA2B;AAAA,EACtC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,WAAW;AAAA,EACX,aAAa;AAAA,EACb,cAAc;AAAA,EACd,WAAW;AAAA,EACX,UAAU;AAAA,EACV,eAAe;AAAA;AAAA,EAEf,cAAc;AAAA;AAAA,EAEd,cAAc;AAChB;AAMO,IAAM,mCAAmC;AAGzC,IAAM,oCAAoC;AAG1C,IAAM,gCAAgC;AAGtC,IAAM,sCAAsC;","names":[]}

package/dist/constants.mjs

@@ -4,7 +4,7 @@ import {
   THIRD_PARTY_BLE_POWER_ON_TIMEOUT_MS,
   THIRD_PARTY_BLE_SCAN_DURATION_MS,
   THIRD_PARTY_BLE_SCAN_IDLE_STOP_MS
-} from "./chunk-RNZYQRXV.mjs";
+} from "./chunk-A5AENDC2.mjs";
 export {
   THIRD_PARTY_BLE_CHANNELS,
   THIRD_PARTY_BLE_DEVICE_TTL_MS,

package/dist/index.d.mts

@@ -12,12 +12,7 @@ type BleDebugLogger = (entry: BleDebugLogEntry) => void;
 /** Replace sensitive values at any depth; everything else is forwarded verbatim. */
 declare function redactBleDebugLogData(data?: Record<string, unknown>): Record<string, unknown> | undefined;
 
-/**
- * Shape of the API the renderer process talks to. In a real Electron app
- * this is normally exposed via `contextBridge.exposeInMainWorld('desktopApi',
- * { trezorBle: ... })`, but the transport accepts the bridge directly so
- * non-Electron hosts (and unit tests) can plug in their own implementation.
- */
+/** Device info the main process returns to the renderer over IPC. */
 interface ThirdPartyBleDeviceInfo {
     /** Stable id (noble peripheral.id) used as connectId. */
     id: string;
@@ -53,7 +48,7 @@ interface ThirdPartyBleAvailability {
 type ThirdPartyBleScanOptions = ElectronBleScanOptions;
 interface ThirdPartyBleApi {
     scan(options?: ThirdPartyBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
-    stopScan(): Promise<void>;
+    stopScan(vendor?: string): Promise<void>;
     connect(id: string, options: ElectronBleConnectOptions): Promise<{
         id: string;
         name?: string;
@@ -62,19 +57,18 @@ interface ThirdPartyBleApi {
     /** Subscribe to the BLE notify characteristic for `id`. */
     subscribe(id: string): Promise<void>;
     unsubscribe(id: string): Promise<void>;
-    /**
-     * Write an already-framed payload. The main process applies the framing rule
-     * recorded at connect time — splitting and zero-padding for `padded`, or
-     * writing the buffer as given for `raw`.
-     */
+    /** Write a framed payload; main chunks and zero-pads `padded`, writes `raw` as-is. */
     write(id: string, hexData: string): Promise<void>;
     checkAvailability(): Promise<ThirdPartyBleAvailability>;
     /** Look up a previously-scanned device by id without re-scanning. */
     getDevice(id: string): Promise<ThirdPartyBleDeviceInfo | null>;
     /** Read current RSSI (dBm) of a *connected* peripheral. */
     readRssi(id: string): Promise<number>;
-    /** Stop scan + disconnect every in-flight connection. */
-    cancelPairing(): Promise<void>;
+    /** Cancel only the named vendor/device; omitting the argument cancels everything. */
+    cancelPairing(options?: {
+        vendor: string;
+        id?: string;
+    }): Promise<void>;
     /** Register a listener for incoming BLE notifications. Returns an unsubscribe fn. */
     onNotification(handler: (id: string, hexData: string) => void): () => void;
     /** Register a listener for unexpected disconnects. Returns an unsubscribe fn. */
@@ -93,11 +87,8 @@ interface NobleLike {
     stopScanningAsync(): Promise<void>;
     stop?(): void;
     /**
-     * Connect by id/address with NO scan. Both native backends support this and
-     * emit a `discover` for the peripheral as a side effect: Windows synthesizes
-     * one for an unknown address (`BLEManager::Connect`, lib/win/src/ble_manager.cc)
-     * and macOS resolves it via `retrievePeripheralsWithIdentifiers`
-     * (lib/mac/src/ble_manager.mm). Optional so a stub noble can omit it.
+     * Connect by id with no scan; both backends emit `discover` as a side effect
+     * (win `BLEManager::Connect`, mac `retrievePeripheralsWithIdentifiers`).
      */
     connectAsync?(idOrAddress: string): Promise<NoblePeripheralLike | undefined>;
     cancelConnect?(idOrAddress: string): void;
@@ -149,12 +140,7 @@ interface NobleBleHandlerOptions {
     connectTimeoutMs?: number;
     logger?: BleDebugLogger;
 }
-/**
- * Core BLE logic, decoupled from Electron's IPC layer so it can be unit
- * tested with a fake noble. Mirrors the OneKey `noble-ble-handler.ts`
- * pattern (a single class that owns the peripheral cache + disconnect
- * callbacks), but trimmed to the minimum surface we expose.
- */
+/** Noble BLE logic decoupled from Electron IPC, so tests can use a fake noble. */
 declare class NobleBleHandler {
     private _noble;
     private readonly _factory;
@@ -165,6 +151,8 @@ declare class NobleBleHandler {
     private readonly _connected;
     private _discoverHandler?;
     private _scanning;
+    private readonly _scanOwners;
+    private _scanTransition;
     private _idleStopTimer?;
     private _onNotification?;
     private _onDeviceDisconnected?;
@@ -178,121 +166,57 @@ declare class NobleBleHandler {
     private readonly _connectAttempts;
     private _nativeReleased;
     private _lastNobleRecoverAt?;
-    /** The connect currently in flight, so cancelPairing can abandon it. */
-    private _activeConnect?;
     constructor(options?: NobleBleHandlerOptions);
     setNotificationListener(handler: (id: string, hexData: string) => void): void;
     setDisconnectedListener(handler: (id: string) => void): void;
     init(): Promise<void>;
     checkAvailability(): Promise<ThirdPartyBleAvailability>;
     /**
-     * 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.)
+     * Lazy-start an unfiltered scan and return the current snapshot. noble-win filters per
+     * packet, and a Safe 7 ADV carries only its name (UUID is in the scan response).
      */
     scan(options?: ElectronBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
     /**
-     * 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`).
+     * In-range devices matching the caller, minus TTL-expired ones. `_discovered`
+     * is only a cache; a missing device can still be reached by `_directConnect`.
      */
     private _snapshot;
     /** A noble instance with its own bindings, so a stuck one can be replaced. */
     private _createFreshNoble;
     /**
-     * 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.
+     * Rebuild noble when Windows BLE re-enumeration latched its RadioWatcher at
+     * `unsupported`; fresh bindings restart the watcher without an app restart.
      */
     private _recoverNobleIfStuck;
     private _armIdleStop;
     private _clearIdleStop;
+    private _setScanning;
     /** Stop scanning but keep the discovered cache (used before connect). */
     private _pauseScan;
     /** Stop scanning and forget discovered devices (idle timeout / teardown). */
     private _stopContinuousScan;
-    /**
-     * 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 host mounts one
-     * vendor's flow at a time; queues are per adapter, not shared. Anything
-     * that breaks that — a background presence probe, say — needs per-vendor
-     * refcounting here first.
-     */
-    stopScan(): Promise<void>;
+    /** A vendor releasing discovery must not stop another vendor's scan. */
+    stopScan(vendor?: string): Promise<void>;
     /**
      * 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: string): ThirdPartyBleDeviceInfo | null;
-    /**
-     * 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.
-     */
+    /** Live RSSI (dBm) of a connected peripheral, else the cached scan-time value. */
     readRssi(id: string): Promise<number>;
+    /** Abandon matching pairing attempts without touching another owner's links. */
+    cancelPairing(options?: {
+        vendor: string;
+        id?: string;
+    }): Promise<void>;
     /**
-     * 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.
-     */
-    cancelPairing(): Promise<void>;
-    /**
-     * 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.
+     * Scan until `id` is discovered, releasing only its own scan ownership. A
+     * bonded Safe 7 goes silent, so callers fall back to `_directConnect`.
      */
     private _scanUntilFound;
     /**
-     * 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.
+     * Connect by id without advertisement: the only route to a linked, silent device.
+     * Returns undefined instead of throwing so the caller reports "device not found".
      */
     private _directConnect;
     private _safeDisconnect;
@@ -308,9 +232,8 @@ declare class NobleBleHandler {
     /** Retire a renderer's handler without stopping a process-wide native manager. */
     dispose(): Promise<void>;
     /**
-     * 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.
+     * Terminal native release, including recovered instances. A host sharing noble
+     * must defer stop() until every transport disposed, and dedupe the instances.
      */
     disposeForAppQuit(releaseNoble?: (instance: {
         stop?(): void;
@@ -346,11 +269,8 @@ interface ThirdPartyBleSupportHandle {
     }) => void): Promise<void>;
 }
 /**
- * Wire a `NobleBleHandler` to Electron's IPC so the renderer can drive BLE
- * via `window.desktopApi.trezorBle`. Call once from the main process after
- * `BrowserWindow` is ready.
- *
- * Call dispose() when retiring a renderer and disposeForAppQuit() before Node teardown.
+ * Wire a `NobleBleHandler` to Electron IPC once `BrowserWindow` is ready. Call dispose()
+ * when retiring a renderer and disposeForAppQuit() before Node teardown.
  */
 declare function initThirdPartyBleSupport(webContents: WebContentsLike, options?: InitThirdPartyBleSupportOptions): ThirdPartyBleSupportHandle;
 

package/dist/index.d.ts

@@ -12,12 +12,7 @@ type BleDebugLogger = (entry: BleDebugLogEntry) => void;
 /** Replace sensitive values at any depth; everything else is forwarded verbatim. */
 declare function redactBleDebugLogData(data?: Record<string, unknown>): Record<string, unknown> | undefined;
 
-/**
- * Shape of the API the renderer process talks to. In a real Electron app
- * this is normally exposed via `contextBridge.exposeInMainWorld('desktopApi',
- * { trezorBle: ... })`, but the transport accepts the bridge directly so
- * non-Electron hosts (and unit tests) can plug in their own implementation.
- */
+/** Device info the main process returns to the renderer over IPC. */
 interface ThirdPartyBleDeviceInfo {
     /** Stable id (noble peripheral.id) used as connectId. */
     id: string;
@@ -53,7 +48,7 @@ interface ThirdPartyBleAvailability {
 type ThirdPartyBleScanOptions = ElectronBleScanOptions;
 interface ThirdPartyBleApi {
     scan(options?: ThirdPartyBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
-    stopScan(): Promise<void>;
+    stopScan(vendor?: string): Promise<void>;
     connect(id: string, options: ElectronBleConnectOptions): Promise<{
         id: string;
         name?: string;
@@ -62,19 +57,18 @@ interface ThirdPartyBleApi {
     /** Subscribe to the BLE notify characteristic for `id`. */
     subscribe(id: string): Promise<void>;
     unsubscribe(id: string): Promise<void>;
-    /**
-     * Write an already-framed payload. The main process applies the framing rule
-     * recorded at connect time — splitting and zero-padding for `padded`, or
-     * writing the buffer as given for `raw`.
-     */
+    /** Write a framed payload; main chunks and zero-pads `padded`, writes `raw` as-is. */
     write(id: string, hexData: string): Promise<void>;
     checkAvailability(): Promise<ThirdPartyBleAvailability>;
     /** Look up a previously-scanned device by id without re-scanning. */
     getDevice(id: string): Promise<ThirdPartyBleDeviceInfo | null>;
     /** Read current RSSI (dBm) of a *connected* peripheral. */
     readRssi(id: string): Promise<number>;
-    /** Stop scan + disconnect every in-flight connection. */
-    cancelPairing(): Promise<void>;
+    /** Cancel only the named vendor/device; omitting the argument cancels everything. */
+    cancelPairing(options?: {
+        vendor: string;
+        id?: string;
+    }): Promise<void>;
     /** Register a listener for incoming BLE notifications. Returns an unsubscribe fn. */
     onNotification(handler: (id: string, hexData: string) => void): () => void;
     /** Register a listener for unexpected disconnects. Returns an unsubscribe fn. */
@@ -93,11 +87,8 @@ interface NobleLike {
     stopScanningAsync(): Promise<void>;
     stop?(): void;
     /**
-     * Connect by id/address with NO scan. Both native backends support this and
-     * emit a `discover` for the peripheral as a side effect: Windows synthesizes
-     * one for an unknown address (`BLEManager::Connect`, lib/win/src/ble_manager.cc)
-     * and macOS resolves it via `retrievePeripheralsWithIdentifiers`
-     * (lib/mac/src/ble_manager.mm). Optional so a stub noble can omit it.
+     * Connect by id with no scan; both backends emit `discover` as a side effect
+     * (win `BLEManager::Connect`, mac `retrievePeripheralsWithIdentifiers`).
      */
     connectAsync?(idOrAddress: string): Promise<NoblePeripheralLike | undefined>;
     cancelConnect?(idOrAddress: string): void;
@@ -149,12 +140,7 @@ interface NobleBleHandlerOptions {
     connectTimeoutMs?: number;
     logger?: BleDebugLogger;
 }
-/**
- * Core BLE logic, decoupled from Electron's IPC layer so it can be unit
- * tested with a fake noble. Mirrors the OneKey `noble-ble-handler.ts`
- * pattern (a single class that owns the peripheral cache + disconnect
- * callbacks), but trimmed to the minimum surface we expose.
- */
+/** Noble BLE logic decoupled from Electron IPC, so tests can use a fake noble. */
 declare class NobleBleHandler {
     private _noble;
     private readonly _factory;
@@ -165,6 +151,8 @@ declare class NobleBleHandler {
     private readonly _connected;
     private _discoverHandler?;
     private _scanning;
+    private readonly _scanOwners;
+    private _scanTransition;
     private _idleStopTimer?;
     private _onNotification?;
     private _onDeviceDisconnected?;
@@ -178,121 +166,57 @@ declare class NobleBleHandler {
     private readonly _connectAttempts;
     private _nativeReleased;
     private _lastNobleRecoverAt?;
-    /** The connect currently in flight, so cancelPairing can abandon it. */
-    private _activeConnect?;
     constructor(options?: NobleBleHandlerOptions);
     setNotificationListener(handler: (id: string, hexData: string) => void): void;
     setDisconnectedListener(handler: (id: string) => void): void;
     init(): Promise<void>;
     checkAvailability(): Promise<ThirdPartyBleAvailability>;
     /**
-     * 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.)
+     * Lazy-start an unfiltered scan and return the current snapshot. noble-win filters per
+     * packet, and a Safe 7 ADV carries only its name (UUID is in the scan response).
      */
     scan(options?: ElectronBleScanOptions): Promise<ThirdPartyBleDeviceInfo[]>;
     /**
-     * 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`).
+     * In-range devices matching the caller, minus TTL-expired ones. `_discovered`
+     * is only a cache; a missing device can still be reached by `_directConnect`.
      */
     private _snapshot;
     /** A noble instance with its own bindings, so a stuck one can be replaced. */
     private _createFreshNoble;
     /**
-     * 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.
+     * Rebuild noble when Windows BLE re-enumeration latched its RadioWatcher at
+     * `unsupported`; fresh bindings restart the watcher without an app restart.
      */
     private _recoverNobleIfStuck;
     private _armIdleStop;
     private _clearIdleStop;
+    private _setScanning;
     /** Stop scanning but keep the discovered cache (used before connect). */
     private _pauseScan;
     /** Stop scanning and forget discovered devices (idle timeout / teardown). */
     private _stopContinuousScan;
-    /**
-     * 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 host mounts one
-     * vendor's flow at a time; queues are per adapter, not shared. Anything
-     * that breaks that — a background presence probe, say — needs per-vendor
-     * refcounting here first.
-     */
-    stopScan(): Promise<void>;
+    /** A vendor releasing discovery must not stop another vendor's scan. */
+    stopScan(vendor?: string): Promise<void>;
     /**
      * 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: string): ThirdPartyBleDeviceInfo | null;
-    /**
-     * 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.
-     */
+    /** Live RSSI (dBm) of a connected peripheral, else the cached scan-time value. */
     readRssi(id: string): Promise<number>;
+    /** Abandon matching pairing attempts without touching another owner's links. */
+    cancelPairing(options?: {
+        vendor: string;
+        id?: string;
+    }): Promise<void>;
     /**
-     * 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.
-     */
-    cancelPairing(): Promise<void>;
-    /**
-     * 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.
+     * Scan until `id` is discovered, releasing only its own scan ownership. A
+     * bonded Safe 7 goes silent, so callers fall back to `_directConnect`.
      */
     private _scanUntilFound;
     /**
-     * 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.
+     * Connect by id without advertisement: the only route to a linked, silent device.
+     * Returns undefined instead of throwing so the caller reports "device not found".
      */
     private _directConnect;
     private _safeDisconnect;
@@ -308,9 +232,8 @@ declare class NobleBleHandler {
     /** Retire a renderer's handler without stopping a process-wide native manager. */
     dispose(): Promise<void>;
     /**
-     * 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.
+     * Terminal native release, including recovered instances. A host sharing noble
+     * must defer stop() until every transport disposed, and dedupe the instances.
      */
     disposeForAppQuit(releaseNoble?: (instance: {
         stop?(): void;
@@ -346,11 +269,8 @@ interface ThirdPartyBleSupportHandle {
     }) => void): Promise<void>;
 }
 /**
- * Wire a `NobleBleHandler` to Electron's IPC so the renderer can drive BLE
- * via `window.desktopApi.trezorBle`. Call once from the main process after
- * `BrowserWindow` is ready.
- *
- * Call dispose() when retiring a renderer and disposeForAppQuit() before Node teardown.
+ * Wire a `NobleBleHandler` to Electron IPC once `BrowserWindow` is ready. Call dispose()
+ * when retiring a renderer and disposeForAppQuit() before Node teardown.
  */
 declare function initThirdPartyBleSupport(webContents: WebContentsLike, options?: InitThirdPartyBleSupportOptions): ThirdPartyBleSupportHandle;