@onekeyfe/hd-transport-electron 1.2.2-alpha.101 → 1.2.2-alpha.102

package/src/noble-ble-handler.ts

@@ -40,6 +40,16 @@ import type { CharacteristicPair, DeviceInfo, Logger, NobleModule } from './type
 // Noble will be dynamically imported to avoid bundling issues
 let noble: NobleModule | null = null;
 let logger: Logger | null = null;
+let disposing = false;
+let disposePromise: Promise<void> | undefined;
+let removeIpcHandlers: (() => void) | undefined;
+const pendingCancellations = new Set<() => void>();
+
+function assertBleActive(): void {
+  if (disposing) {
+    throw ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down');
+  }
+}
 
 type NobleBleNativeError = Error & {
   nativeErrorCode?: number;
@@ -49,7 +59,8 @@ type NobleBleNativeError = Error & {
 export function createNobleBleConnectionError(error: NobleBleNativeError, messagePrefix = '') {
   const errorMessage = error.message;
   const isInvalidMacOsBond =
-    error.nativeErrorCode === 14 && error.nativeErrorDomain === 'CBErrorDomain';
+    (error.nativeErrorCode === 14 && error.nativeErrorDomain === 'CBErrorDomain') ||
+    (error.nativeErrorCode === 15 && error.nativeErrorDomain === 'CBATTErrorDomain');
   if (isInvalidMacOsBond) {
     const nativeErrorMessage = `${messagePrefix}${errorMessage}`;
     return ERRORS.TypedError(
@@ -116,6 +127,74 @@ let persistentDiscoverListener: ((peripheral: Peripheral) => void) | null = null
 // Device cache and connection state
 const discoveredDevices = new Map<string, Peripheral>();
 const connectedDevices = new Map<string, Peripheral>();
+type PendingDeviceConnection = {
+  peripheral: Peripheral;
+  generation: number;
+  cancel: (error: unknown) => void;
+};
+const connectingDevices = new Map<string, PendingDeviceConnection>();
+let nextConnectionGeneration = 0;
+
+function connectPeripheralWithCancellation(
+  peripheral: Peripheral,
+  deviceId: string,
+  messagePrefix = ''
+): Promise<void> {
+  assertBleActive();
+  return new Promise<void>((resolve, reject) => {
+    const generation = ++nextConnectionGeneration;
+    let settled = false;
+    const settle = (settler: () => void): boolean => {
+      if (settled) return false;
+      settled = true;
+      if (connectingDevices.get(deviceId)?.generation === generation) {
+        connectingDevices.delete(deviceId);
+      }
+      settler();
+      return true;
+    };
+    const pendingConnection: PendingDeviceConnection = {
+      peripheral,
+      generation,
+      cancel: error => {
+        settle(() => reject(error));
+      },
+    };
+    connectingDevices
+      .get(deviceId)
+      ?.cancel(
+        ERRORS.TypedError(
+          HardwareErrorCode.BleDeviceDisconnected,
+          `Device ${deviceId} connect attempt was superseded`
+        )
+      );
+    connectingDevices.set(deviceId, pendingConnection);
+
+    peripheral.connect(error => {
+      if (error) {
+        settle(() => reject(createNobleBleConnectionError(error, messagePrefix)));
+        return;
+      }
+
+      if (
+        !settle(() => {
+          connectedDevices.set(deviceId, peripheral);
+          resolve();
+        })
+      ) {
+        const activeConnection = connectingDevices.get(deviceId);
+        if (!activeConnection || activeConnection.peripheral !== peripheral) {
+          try {
+            peripheral.removeAllListeners('disconnect');
+            peripheral.disconnect(() => undefined);
+          } catch {
+            // Best-effort cleanup for a stale native callback.
+          }
+        }
+      }
+    });
+  });
+}
 const pairedDevices = new Set<string>(); // Windows BLE device pairing status tracking
 const deviceCharacteristics = new Map<string, CharacteristicPair>();
 const notificationCallbacks = new Map<string, (data: string) => void>();
@@ -320,6 +399,7 @@ function updateBluetoothState(state: string): void {
 
 // Initialize Noble
 async function initializeNoble(): Promise<void> {
+  assertBleActive();
   if (noble) return;
 
   try {
@@ -345,12 +425,14 @@ async function initializeNoble(): Promise<void> {
       }
 
       const timeout = setTimeout(() => {
+        cleanup();
         reject(
           ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Bluetooth initialization timeout')
         );
       }, BLUETOOTH_INIT_TIMEOUT);
 
       const cleanup = () => {
+        pendingCancellations.delete(cancel);
         clearTimeout(timeout);
         if (noble) {
           noble.removeListener('stateChange', onStateChange);
@@ -375,9 +457,17 @@ async function initializeNoble(): Promise<void> {
         }
       };
 
+      const cancel = () => {
+        cleanup();
+        reject(
+          ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down')
+        );
+      };
+      pendingCancellations.add(cancel);
       noble.on('stateChange', onStateChange);
     });
 
+    assertBleActive();
     // Set up device discovery
     if (!persistentDiscoverListener) {
       persistentDiscoverListener = (peripheral: Peripheral) => {
@@ -462,6 +552,7 @@ function armIdleDisconnect(
   reason: 'idle' | 'busy-backstop' = 'idle'
 ): void {
   clearIdleDisconnect(deviceId);
+  if (disposing) return;
   idleDisconnectTimers.set(
     deviceId,
     setTimeout(() => {
@@ -544,6 +635,14 @@ function cleanupDevice(
 
   // 1. Clean up connection state
   if (cleanupConnection) {
+    connectingDevices
+      .get(deviceId)
+      ?.cancel(
+        ERRORS.TypedError(
+          HardwareErrorCode.BleDeviceDisconnected,
+          `Device ${deviceId} disconnected while connecting`
+        )
+      );
     const disconnectEntry = deviceDisconnectListeners.get(deviceId);
     if (disconnectEntry) {
       disconnectEntry.peripheral.removeListener('disconnect', disconnectEntry.listener);
@@ -653,6 +752,7 @@ async function writeCharacteristicWithoutResponse(
   writeCharacteristic: Characteristic,
   buffer: Buffer
 ): Promise<void> {
+  assertBleActive();
   return new Promise((resolve, reject) => {
     writeCharacteristic.write(buffer, true, (error?: Error) => {
       if (error) {
@@ -937,6 +1037,7 @@ async function performTargetedScan(
   targetDeviceId: string,
   timeoutMs: number = NOBLE_BLE_TARGETED_SCAN_TIMEOUT_MS
 ): Promise<Peripheral | null> {
+  assertBleActive();
   if (!noble) {
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Noble not available');
   }
@@ -952,6 +1053,7 @@ async function performTargetedScan(
     const finish = async (peripheral: Peripheral | null, error?: Error) => {
       if (settled) return;
       settled = true;
+      pendingCancellations.delete(cancel);
       if (timeoutId) clearTimeout(timeoutId);
       nobleInstance.removeListener('discover', onDiscover);
       await waitForNobleScanStop(nobleInstance);
@@ -961,6 +1063,7 @@ async function performTargetedScan(
         reject(ERRORS.TypedError(HardwareErrorCode.BleScanError, error.message));
         return;
       }
+      assertBleActive();
       if (peripheral) {
         discoveredDevices.set(peripheral.id, peripheral);
       }
@@ -983,6 +1086,11 @@ async function performTargetedScan(
       finish(null).catch(reject);
     }, timeoutMs);
 
+    const cancel = () => {
+      finish(null, new Error('Noble BLE is shutting down')).catch(reject);
+    };
+    pendingCancellations.add(cancel);
+
     // Add local listener for this scan
     nobleInstance.on('discover', onDiscover);
 
@@ -1008,6 +1116,7 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
     throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Noble not available');
   }
 
+  assertBleActive();
   // Capture noble reference for use in closures (TypeScript narrowing)
   const nobleInstance = noble;
 
@@ -1022,12 +1131,15 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
 
   return new Promise((resolve, reject) => {
     const devices: DeviceInfo[] = [];
+    let settled = false;
     let intervalId: ReturnType<typeof setInterval> | undefined;
 
     // Cleanup function: clears timers and waits until Noble confirms scanning
     // has stopped. Resolving enumerate before this callback creates a race with
     // an immediately-following connection attempt.
     const cleanup = async () => {
+      settled = true;
+      pendingCancellations.delete(cancel);
       clearTimeout(timeoutId);
       if (intervalId) clearInterval(intervalId);
       await waitForNobleScanStop(nobleInstance);
@@ -1051,6 +1163,7 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
 
     // Set timeout for scanning — use longer timeout to catch slow-advertising devices like Pro2
     const timeoutId = setTimeout(async () => {
+      if (settled) return;
       // Final collection before resolving — catches devices discovered near the deadline
       checkDevices();
       await cleanup();
@@ -1058,11 +1171,17 @@ async function enumerateDevices(): Promise<DeviceInfo[]> {
       resolve(devices);
     }, DEVICE_SCAN_TIMEOUT);
 
+    const cancel = () => {
+      cleanup().then(() => resolve([]), reject);
+    };
+    pendingCancellations.add(cancel);
+
     // Start scanning without a service UUID filter so Pro2 advertisements with
     // short vendor UUIDs can be found. Repeated advertisements are required when
     // the local name arrives in a later scan response; discoveredDevices handles deduplication.
     logger?.info('[NobleBLE] Scanning for OneKey BLE devices');
     nobleInstance.startScanning([], true, async (error?: Error) => {
+      if (settled) return;
       if (error) {
         await cleanup();
         logger?.error('[NobleBLE] Failed to start scanning:', error);
@@ -1153,13 +1272,17 @@ function getDevice(deviceId: string): DeviceInfo | null {
 async function discoverServicesAndCharacteristics(
   peripheral: Peripheral
 ): Promise<CharacteristicPair> {
+  assertBleActive();
   // Cleanup resources - will be set up and cleaned in try/finally
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
   let onDisconnect: (() => void) | undefined;
 
   const cleanup = () => {
     if (timeoutId) clearTimeout(timeoutId);
-    if (onDisconnect) peripheral.removeListener('disconnect', onDisconnect);
+    if (onDisconnect) {
+      peripheral.removeListener('disconnect', onDisconnect);
+      pendingCancellations.delete(onDisconnect);
+    }
   };
 
   // Racing promises for timeout and disconnect
@@ -1180,6 +1303,7 @@ async function discoverServicesAndCharacteristics(
         )
       );
     };
+    pendingCancellations.add(onDisconnect);
     peripheral.once('disconnect', onDisconnect);
   });
 
@@ -1205,6 +1329,7 @@ async function discoverServicesAndCharacteristics(
       });
     });
 
+    assertBleActive();
     if (!services || services.length === 0) {
       throw ERRORS.TypedError(HardwareErrorCode.BleServiceNotFound, 'No OneKey services found');
     }
@@ -1311,17 +1436,8 @@ async function forceReconnectPeripheral(peripheral: Peripheral, deviceId: string
   }
 
   // Step 3: Re-establish connection
-  await new Promise<void>((resolve, reject) => {
-    peripheral.connect(error => {
-      if (error) {
-        reject(createNobleBleConnectionError(error));
-        return;
-      }
-      resolve();
-    });
-  });
+  await connectPeripheralWithCancellation(peripheral, deviceId);
   logger?.info('[NobleBLE] Force reconnect successful');
-  connectedDevices.set(deviceId, peripheral);
 
   // Wait for connection to stabilize
   await wait(500);
@@ -1357,16 +1473,11 @@ async function freshScanAndDiscover(
   discoveredDevices.set(deviceId, freshPeripheral);
 
   // Connect to fresh peripheral
-  await new Promise<void>((resolve, reject) => {
-    freshPeripheral.connect((error: Error | undefined) => {
-      if (error) {
-        reject(createNobleBleConnectionError(error, 'Fresh peripheral connection failed: '));
-      } else {
-        connectedDevices.set(deviceId, freshPeripheral);
-        resolve();
-      }
-    });
-  });
+  await connectPeripheralWithCancellation(
+    freshPeripheral,
+    deviceId,
+    'Fresh peripheral connection failed: '
+  );
 
   // Setup disconnect listener for fresh peripheral
   setupDisconnectListener(freshPeripheral, deviceId, webContents);
@@ -1438,6 +1549,7 @@ async function discoverServicesAndCharacteristicsWithRetry(
       minTimeout: 500,
       maxTimeout: 3000,
       onFailedAttempt: error => {
+        assertBleActive();
         // This runs after each failed attempt
         logger?.error(`[NobleBLE] Service discovery attempt ${error.attemptNumber} failed:`, {
           message: error.message,
@@ -1473,13 +1585,17 @@ async function setupConnectionAndDiscoverServices(
   try {
     await forceReconnectPeripheral(peripheral, deviceId);
   } catch (resetError) {
-    if (isBleStaleBondHardwareError(resetError)) {
+    if (
+      isBleStaleBondHardwareError(resetError) ||
+      (resetError as { errorCode?: unknown })?.errorCode === HardwareErrorCode.BleDeviceDisconnected
+    ) {
       throw resetError;
     }
     // A failed reset must not abort the attempt: discovery on the existing
     // link, then the fresh-scan fallback, still have a chance to recover.
     logger?.error('[NobleBLE] Connection reset before discovery failed, continuing', resetError);
   }
+  assertBleActive();
   setupDisconnectListener(peripheral, deviceId, webContents);
 
   try {
@@ -1522,6 +1638,7 @@ const directConnectCooldownUntil = new Map<string, number>();
  * Ported from the Trezor connector, where it is field-proven.
  */
 async function tryDirectConnectById(deviceId: string): Promise<Peripheral | undefined> {
+  assertBleActive();
   const nobleInstance = noble as
     | (typeof noble & {
         connectAsync?: (id: string) => Promise<Peripheral | undefined>;
@@ -1532,16 +1649,20 @@ async function tryDirectConnectById(deviceId: string): Promise<Peripheral | unde
   const cooldownUntil = directConnectCooldownUntil.get(deviceId) ?? 0;
   if (Date.now() < cooldownUntil) return undefined;
 
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cancel: (() => void) | undefined;
   try {
     // The late-orphan guard must attach to THIS pending connect.
     const directPromise = nobleInstance.connectAsync(deviceId);
     const raced = await Promise.race([
       directPromise,
       new Promise<'timeout'>(resolve => {
-        setTimeout(() => resolve('timeout'), DIRECT_CONNECT_TIMEOUT_MS);
+        cancel = () => resolve('timeout');
+        pendingCancellations.add(cancel);
+        timer = setTimeout(cancel, DIRECT_CONNECT_TIMEOUT_MS);
       }),
     ]);
-    if (raced === 'timeout') {
+    if (raced === 'timeout' || disposing) {
       directConnectCooldownUntil.set(deviceId, Date.now() + DIRECT_CONNECT_COOLDOWN_MS);
       logger?.info('[NobleBLE] Direct connect-by-id timed out, falling back to scan', {
         deviceId,
@@ -1574,6 +1695,9 @@ async function tryDirectConnectById(deviceId: string): Promise<Peripheral | unde
       error: String(error),
     });
     return undefined;
+  } finally {
+    clearTimeout(timer);
+    if (cancel) pendingCancellations.delete(cancel);
   }
 }
 
@@ -1644,6 +1768,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     }
   }
 
+  assertBleActive();
   // At this point, peripheral is guaranteed to be defined
   if (!peripheral) {
     throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `Device ${deviceId} not found`);
@@ -1666,6 +1791,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     // Re-bind unconditionally (idempotent): on a kept-alive link the disconnect
     // and MTU listeners may still hold the webContents of a soft-restarted
     // renderer, and the reuse fast path below returns before any other setup.
+    assertBleActive();
     setupDisconnectListener(peripheral, deviceId, webContents);
 
     // Check if we already have characteristics for this device
@@ -1716,6 +1842,7 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
         deviceId,
         webContents
       );
+      assertBleActive();
       deviceCharacteristics.set(deviceId, characteristics);
       logger?.info('[NobleBLE] Device ready for communication:', deviceId);
     } catch (setupError) {
@@ -1727,51 +1854,42 @@ async function connectDevice(deviceId: string, webContents: WebContents): Promis
     return;
   }
 
-  return new Promise((resolve, reject) => {
-    // TypeScript type assertion - peripheral is guaranteed to be defined at this point
-    const connectedPeripheral = peripheral as Peripheral;
-    connectedPeripheral.connect(async (error: Error | undefined) => {
-      if (error) {
-        logger?.error('[NobleBLE] Connection failed:', error);
-        reject(createNobleBleConnectionError(error));
-        return;
-      }
+  const connectedPeripheral = peripheral;
+  await connectPeripheralWithCancellation(connectedPeripheral, deviceId);
+  logger?.info('[NobleBLE] Connected to device:', deviceId);
 
-      logger?.info('[NobleBLE] Connected to device:', deviceId);
-      connectedDevices.set(deviceId, connectedPeripheral);
-
-      // Setup connection and discover services
-      try {
-        const characteristics = await setupConnectionAndDiscoverServices(
-          connectedPeripheral,
-          deviceId,
-          webContents
-        );
-        deviceCharacteristics.set(deviceId, characteristics);
-        logger?.info('[NobleBLE] Device ready for communication:', deviceId);
-        resolve();
-      } catch (setupError) {
-        logger?.error('[NobleBLE] Connection setup failed:', setupError);
-        // Never reject from inside a raw disconnect callback: noble only fires
-        // it on a real 'disconnect' event, so a peripheral that is already
-        // down leaves this promise — and the renderer acquire awaiting it —
-        // pending forever. disconnectDevice always settles (it no-ops on an
-        // unknown peripheral and caps the confirm wait).
-        disconnectDevice(deviceId)
-          .catch(() => undefined)
-          .then(() => reject(setupError));
-      }
-    });
-  });
+  // Setup connection and discover services
+  try {
+    const characteristics = await setupConnectionAndDiscoverServices(
+      connectedPeripheral,
+      deviceId,
+      webContents
+    );
+    assertBleActive();
+    deviceCharacteristics.set(deviceId, characteristics);
+    logger?.info('[NobleBLE] Device ready for communication:', deviceId);
+  } catch (setupError) {
+    logger?.error('[NobleBLE] Connection setup failed:', setupError);
+    await disconnectDevice(deviceId).catch(() => undefined);
+    throw setupError;
+  }
 }
 
 // Disconnect device
 async function disconnectDevice(deviceId: string): Promise<void> {
-  const peripheral = connectedDevices.get(deviceId);
+  const pendingConnection = connectingDevices.get(deviceId);
+  const peripheral = connectedDevices.get(deviceId) ?? pendingConnection?.peripheral;
   if (!peripheral) {
     return;
   }
 
+  pendingConnection?.cancel(
+    ERRORS.TypedError(
+      HardwareErrorCode.BleDeviceDisconnected,
+      `Device ${deviceId} connection cancelled`
+    )
+  );
+
   const disconnectEntry = deviceDisconnectListeners.get(deviceId);
   if (disconnectEntry) {
     disconnectEntry.peripheral.removeListener('disconnect', disconnectEntry.listener);
@@ -1826,7 +1944,7 @@ async function unsubscribeNotifications(deviceId: string): Promise<void> {
     subscribedDevices.delete(deviceId);
   } finally {
     // 🔒 CRITICAL: Always clear operation state (even on error)
-    subscriptionOperations.set(deviceId, 'idle');
+    if (!disposing) subscriptionOperations.set(deviceId, 'idle');
   }
 }
 
@@ -1915,11 +2033,13 @@ async function subscribeNotifications(
       timeoutMs: BLE_CLEANUP_TIMEOUT,
       timeoutBehavior: 'resolve',
     });
+    assertBleActive();
     await runBleCallbackOperation(callback => notifyCharacteristic.subscribe(callback), {
       timeoutMs: NOBLE_BLE_SUBSCRIBE_TIMEOUT_MS,
       timeoutBehavior: 'reject',
     });
 
+    assertBleActive();
     notifyCharacteristic.on('data', (data: Buffer) => {
       // Windows BLE pairing detection: receiving any data means device is paired
       if (!pairedDevices.has(deviceId)) {
@@ -1934,19 +2054,26 @@ async function subscribeNotifications(
   const subscribeStartedAt = Date.now();
   try {
     await rebuildAppSubscription(deviceId, notifyCharacteristic);
+    assertBleActive();
     subscribedDevices.set(deviceId, true);
     logger?.info('[NobleBLE] Notification subscription active', {
       deviceId,
       ms: Date.now() - subscribeStartedAt,
     });
+  } catch (error) {
+    throw createNobleBleConnectionError(
+      error as NobleBleNativeError,
+      'Notification subscription failed: '
+    );
   } finally {
     // 🔒 CRITICAL: Always clear operation state (even on error)
-    subscriptionOperations.set(deviceId, 'idle');
+    if (!disposing) subscriptionOperations.set(deviceId, 'idle');
   }
 }
 
 // Setup IPC handlers
 export function setupNobleBleHandlers(webContents: WebContents): void {
+  if (disposing) return;
   try {
     // @ts-ignore – electron-log is only available at runtime
     // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
@@ -1956,11 +2083,16 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
     // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
     const { ipcMain } = require('electron') as { ipcMain: IpcMain };
 
+    const channels = new Set<string>();
+    removeIpcHandlers = () => channels.forEach(channel => ipcMain.removeHandler(channel));
+
     // Electron throws on duplicate channels and setup re-runs on soft restart.
     const handle: IpcMain['handle'] = (channel, listener) => {
+      channels.add(channel);
       ipcMain.removeHandler(channel);
       ipcMain.handle(channel, async (...args) => {
         try {
+          assertBleActive();
           return await Promise.resolve(listener(...args));
         } catch (error) {
           return createNobleBleIpcErrorResponse(error);
@@ -2116,8 +2248,9 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
       }
     });
 
-    // Cleanup on app quit
+    // Window cleanup also runs during renderer soft restart; native release belongs to app quit.
     webContents.on('destroyed', () => {
+      if (disposing) return;
       safeLog(logger, 'info', 'Cleaning up Noble BLE handlers');
       (async () => {
         const deviceIds = Array.from(connectedDevices.keys());
@@ -2147,3 +2280,65 @@ export function setupNobleBleHandlers(webContents: WebContents): void {
     throw error;
   }
 }
+
+/**
+ * Terminal, bounded cleanup while the Node environment is still alive.
+ * If Noble is shared with another transport, releaseNoble must queue the instance
+ * and call stop() once after every transport has finished its cleanup.
+ */
+export function disposeNobleBleSupport(
+  releaseNoble: (instance: { stop(): void }) => void = instance => instance.stop()
+): Promise<void> {
+  if (disposePromise) return disposePromise;
+  disposing = true;
+  removeIpcHandlers?.();
+  const instance = noble;
+  const deviceIds = new Set([...connectedDevices.keys(), ...connectingDevices.keys()]);
+  const pendingPeripherals = Array.from(connectingDevices.values(), pending => pending.peripheral);
+  for (const cancel of pendingCancellations) cancel();
+  for (const id of idleDisconnectTimers.keys()) clearIdleDisconnect(id);
+  for (const pending of connectingDevices.values()) {
+    pending.cancel(
+      ERRORS.TypedError(HardwareErrorCode.BleDeviceDisconnected, 'Noble BLE is shutting down')
+    );
+  }
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  disposePromise = (async () => {
+    try {
+      await Promise.race([
+        Promise.allSettled([
+          stopScanning(),
+          ...pendingPeripherals.map(peripheral =>
+            runBleCallbackOperation(callback => peripheral.disconnect(() => callback()), {
+              timeoutMs: BLE_DISCONNECT_CONFIRM_TIMEOUT_MS,
+              timeoutBehavior: 'resolve',
+            })
+          ),
+          ...Array.from(deviceIds, async id => {
+            await unsubscribeNotifications(id).catch(() => undefined);
+            await disconnectDevice(id).catch(() => undefined);
+          }),
+        ]),
+        new Promise<void>(resolve => {
+          timeout = setTimeout(() => {
+            logger?.warn('[NobleBLE] Process dispose timed out; releasing native manager');
+            resolve();
+          }, 3500);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timeout);
+      cleanupNobleListeners();
+      if (instance && persistentStateListener) {
+        instance.removeListener('stateChange', persistentStateListener);
+        persistentStateListener = null;
+      }
+      for (const id of deviceIds) cleanupDevice(id);
+      discoveredDevices.clear();
+      directConnectCooldownUntil.clear();
+      if (instance) releaseNoble(instance);
+      logger?.info('[NobleBLE] Process dispose completed');
+    }
+  })();
+  return disposePromise;
+}

package/src/types/desktop-api.ts

@@ -23,6 +23,37 @@ export type NobleBleIpcErrorResponse = {
   error: NobleBleIpcErrorPayload;
 };
 
+export function isNobleBleIpcErrorResponse(
+  response: unknown
+): response is NobleBleIpcErrorResponse {
+  if (!response || typeof response !== 'object') {
+    return false;
+  }
+  const candidate = response as Partial<NobleBleIpcErrorResponse>;
+  return (
+    candidate.type === 'NobleBleIpcError' &&
+    candidate.success === false &&
+    Boolean(candidate.error) &&
+    typeof candidate.error?.name === 'string' &&
+    typeof candidate.error.message === 'string' &&
+    typeof candidate.error.errorCode === 'number'
+  );
+}
+
+/**
+ * Keeps structured Noble errors intact across Electron's IPC and contextBridge
+ * boundaries. Every preload implementation must use this for Noble invokes.
+ */
+export async function invokeNobleBleIpc<T>(
+  request: Promise<T | NobleBleIpcErrorResponse>
+): Promise<T> {
+  const response = await request;
+  if (isNobleBleIpcErrorResponse(response)) {
+    return Promise.reject(response.error);
+  }
+  return response;
+}
+
 export interface NobleBleAPI {
   enumerate: () => Promise<{ id: string; name: string }[]>;
   getDevice: (uuid: string) => Promise<{ id: string; name: string; mtu?: number } | null>;

package/src/types/noble-extended.ts

@@ -29,6 +29,7 @@ export interface NobleModule {
     callback?: (error?: Error) => void
   ): void;
   stopScanning(callback?: () => void): void;
+  stop(): void;
   on(event: 'stateChange', listener: (state: string) => void): void;
   on(event: 'discover', listener: (peripheral: Peripheral) => void): void;
   removeListener(event: 'stateChange', listener: (state: string) => void): void;