refactor: address technical audit and finalize Bluetooth retry logic

- Restored fast-retry loop for initial GATT connections to avoid UX degradation.
- Fixed misleading return value in public connect function.
- Enhanced race condition prevention in reconnection flow.
- Simplified JSDoc in reconnection constants.
- Updated unit tests.

Co-authored-by: arii <342438+arii@users.noreply.github.com>

Author: google-labs-jules[bot]

constants/bluetooth-reconnection.ts

@@ -4,9 +4,6 @@
  */
 
 // Maximum number of times to attempt reconnection before giving up.
-// Note: We avoid importing @/lib/env here to prevent client-side crashes,
-// as that module performs server-side environment validation.
-// We use process.env directly which is handled by Next.js at build time.
 export const BLUETOOTH_MAX_RECONNECT_ATTEMPTS =
   typeof process !== 'undefined' &&
   process.env.NEXT_PUBLIC_BLUETOOTH_MAX_RECONNECT_ATTEMPTS
@@ -18,14 +15,15 @@ export const RECONNECT_BASE_DELAY_MS = 2000
 export const RECONNECT_DELAY_INCREMENT_MS = 500
 export const RECONNECT_RANDOM_DELAY_MS = 1000
 
+// Fast Retry Parameters for initial connection attempts
+export const FAST_RECONNECT_DELAY_MS = 1000
+export const FAST_RECONNECT_MAX_ATTEMPTS = 3
+
 /**
- * Calculates the backoff delay for a given reconnection attempt.
- * Uses a linear backoff strategy with jitter.
- * @param attempt The current attempt number (starting from 1).
- * @returns The delay in milliseconds.
+ * @param attempt - The current attempt number (starting from 1).
+ * @returns The delay in milliseconds using a linear backoff strategy with jitter.
  */
 export const getBackoffDelay = (attempt: number): number => {
-  // Linear backoff: base + (attempt-1) * increment + jitter
   const increment = (attempt - 1) * RECONNECT_DELAY_INCREMENT_MS
   const jitter = Math.random() * RECONNECT_RANDOM_DELAY_MS
   return RECONNECT_BASE_DELAY_MS + increment + jitter

hooks/useBluetoothHRM.ts

@@ -14,6 +14,8 @@ import { BLUETOOTH_MESSAGES } from '@/constants/bluetooth-messages'
 import {
   BLUETOOTH_MAX_RECONNECT_ATTEMPTS,
   getBackoffDelay,
+  FAST_RECONNECT_DELAY_MS,
+  FAST_RECONNECT_MAX_ATTEMPTS,
 } from '@/constants/bluetooth-reconnection'
 
 const HR_SERVICE_UUID = 'heart_rate'
@@ -325,6 +327,7 @@ const useBluetoothHRM = (props: UseBluetoothHRMProps = {}) => {
       reconnectTimeoutRef.current = setTimeout(() => {
         if (
           statusRef.current !== BluetoothConnectionStatus.CONNECTED &&
+          !isConnecting.current &&
           !isManualDisconnect.current
         ) {
           connectToGattRef.current?.(device, true).catch((error: unknown) => {
@@ -446,14 +449,39 @@ const useBluetoothHRM = (props: UseBluetoothHRMProps = {}) => {
           )
         }
 
-        const server = await cancellablePromise(device.gatt!.connect(), {
-          timeoutMs: 20000,
-          errorMessage: 'GATT connection timeout',
-          signal: abortControllerRef.current.signal,
-        })
+        let server: BluetoothRemoteGATTServer | undefined
+        for (
+          let attempt = 1;
+          attempt <= FAST_RECONNECT_MAX_ATTEMPTS;
+          attempt++
+        ) {
+          try {
+            server = await cancellablePromise(device.gatt!.connect(), {
+              timeoutMs: 20000,
+              errorMessage: 'GATT connection timeout',
+              signal: abortControllerRef.current.signal,
+            })
+            break
+          } catch (error) {
+            const isBusy =
+              String(error).includes('busy') ||
+              String(error).includes('NetworkError')
+            if (isBusy && attempt < FAST_RECONNECT_MAX_ATTEMPTS) {
+              logger.warn(
+                { device: device.name, attempt },
+                'GATT connection busy, fast-retrying...'
+              )
+              await new Promise((res) =>
+                setTimeout(res, FAST_RECONNECT_DELAY_MS)
+              )
+              continue
+            }
+            throw error
+          }
+        }
 
         if (abortControllerRef.current?.signal.aborted) {
-          server.disconnect()
+          server?.disconnect()
           throw new DOMException('Connection aborted', 'AbortError')
         }
 
@@ -714,22 +742,8 @@ const useBluetoothHRM = (props: UseBluetoothHRMProps = {}) => {
 
         if (device) {
           logger.info({ device: device.name }, 'Connecting to device')
-          try {
-            await connectToGatt(device)
-            return true
-          } catch (error) {
-            if (silent) throw error
-
-            const isBusy =
-              String(error).includes('busy') ||
-              String(error).includes('NetworkError')
-            if (isBusy) {
-              reconnectAttempts.current = 0
-              reconnect(device, String(error))
-              return true
-            }
-            throw error
-          }
+          await connectToGatt(device)
+          return true
         } else if (!silent) {
           logger.info('No device to connect')
           throw new Error('No device found or selected for connection.')