@chromahq/react 1.0.45 → 1.0.47

package/dist/index.d.ts

@@ -23,8 +23,58 @@ declare global {
     }
 }
 type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error' | 'reconnecting';
+/**
+ * Options for critical operations that need acknowledgment and deduplication.
+ */
+interface CriticalOperationOptions {
+    /**
+     * Client-generated nonce for idempotency. If not provided, one will be generated.
+     * The SW should store processed nonces and reject duplicates.
+     */
+    nonce?: string;
+    /**
+     * If true, the request will NOT be queued during disconnection - it will fail immediately.
+     * Use this for operations where you want explicit user retry rather than automatic retry.
+     * Default: false (requests are queued)
+     */
+    noQueue?: boolean;
+    /**
+     * Callback fired when SW acknowledges receipt of the request (before processing).
+     * Use this to update UI to show "processing" state.
+     */
+    onAcknowledged?: () => void;
+}
+/**
+ * Result of a critical operation, including metadata about the request.
+ */
+interface CriticalOperationResult<T> {
+    data: T;
+    nonce: string;
+    acknowledged: boolean;
+}
 interface Bridge {
     send: <Req = unknown, Res = unknown>(key: string, payload?: Req, timeoutDuration?: number) => Promise<Res>;
+    /**
+     * Send a critical operation that requires acknowledgment and idempotency.
+     * Use this for transfers, signing, and other non-idempotent operations.
+     *
+     * @example
+     * ```ts
+     * const result = await bridge.sendCritical('transfer', {
+     *   to: '0x...',
+     *   amount: '1000000',
+     * }, {
+     *   onAcknowledged: () => setStatus('processing'),
+     *   noQueue: true, // Don't auto-retry transfers
+     * });
+     * ```
+     */
+    /** Alias: clearer naming for nonce/idempotency semantics */
+    sendWithNonce: <Req = unknown, Res = unknown>(key: string, payload?: Req, options?: CriticalOperationOptions, timeoutDuration?: number) => Promise<CriticalOperationResult<Res>>;
+    /** Alias for callers that think in idempotency terms */
+    sendIdempotent: <Req = unknown, Res = unknown>(key: string, payload?: Req, options?: CriticalOperationOptions, timeoutDuration?: number) => Promise<CriticalOperationResult<Res>>;
+    /** Back-compat name (kept) */
+    sendCritical: <Req = unknown, Res = unknown>(key: string, payload?: Req, options?: CriticalOperationOptions, timeoutDuration?: number) => Promise<CriticalOperationResult<Res>>;
     broadcast: (key: string, payload: unknown) => void;
     on: (key: string, handler: (payload: unknown) => void) => void;
     off: (key: string, handler: (payload: unknown) => void) => void;
@@ -36,6 +86,23 @@ interface Bridge {
      * @param durationMs - How long to pause health checks in milliseconds
      */
     pauseHealthChecks: (durationMs: number) => void;
+    /**
+     * Ensure the service worker is connected and responsive before performing a heavy operation.
+     * This performs a quick ping and returns true if successful.
+     * On Windows/Brave, use this before crypto operations to verify the SW hasn't silently restarted.
+     *
+     * @example
+     * ```ts
+     * const ready = await bridge.ensureConnected();
+     * if (!ready) {
+     *   showToast('Connection lost. Please try again.');
+     *   return;
+     * }
+     * bridge.pauseHealthChecks(30000);
+     * await bridge.send('unlock', { password });
+     * ```
+     */
+    ensureConnected: () => Promise<boolean>;
 }
 interface BridgeContextValue {
     bridge: Bridge | null;
@@ -274,4 +341,4 @@ declare function useServiceWorkerHealthSimple(options?: ServiceWorkerHealthOptio
 };
 
 export { BridgeProvider, ServiceWorkerHealthProvider, getHealthStatus, subscribeToHealth, useBridge, useBridgeQuery, useConnectionStatus, useServiceWorkerHealth, useServiceWorkerHealthSimple };
-export type { HealthStatus, ServiceWorkerHealthContextValue };
+export type { CriticalOperationOptions, CriticalOperationResult, HealthStatus, ServiceWorkerHealthContextValue };

package/dist/index.js

@@ -67,18 +67,18 @@ const recordDiagnostics = {
 const CONFIG = {
   RETRY_AFTER: 1e3,
   MAX_RETRIES: 10,
-  PING_INTERVAL: 15e3,
-  // Check every 15s (tolerant of long operations)
+  PING_INTERVAL: 5e3,
+  // Check every 5s for faster SW down detection
   MAX_RETRY_COOLDOWN: 3e4,
   DEFAULT_TIMEOUT: 6e4,
   // 60s default for slow operations
   MAX_RETRY_DELAY: 3e4,
-  PING_TIMEOUT: 2e4,
-  // Give SW 20s to respond to ping
+  PING_TIMEOUT: 8e3,
+  // Give SW 8s to respond to ping (reduced from 20s)
   ERROR_CHECK_INTERVAL: 100,
   MAX_ERROR_CHECKS: 10,
-  CONSECUTIVE_FAILURE_THRESHOLD: 5,
-  // Require 5 consecutive failures (75s total) before reconnecting
+  CONSECUTIVE_FAILURE_THRESHOLD: 2,
+  // Require 2 consecutive failures (~10s total) before reconnecting
   RECONNECT_DELAY: 100,
   PORT_NAME: "chroma-bridge",
   // Service worker restart retry settings (indefinite retries)
@@ -86,8 +86,31 @@ const CONFIG = {
   SW_RESTART_MAX_DELAY: 5e3,
   // Threshold for counting timeouts toward reconnection (only count fast timeouts as failures)
   // Requests with timeout > this value are considered intentional long operations
-  TIMEOUT_FAILURE_THRESHOLD_MS: 3e4
+  TIMEOUT_FAILURE_THRESHOLD_MS: 3e4,
   // Only count timeouts < 30s as potential SW issues
+  // Request queue settings for transparent retry
+  REQUEST_QUEUE_MAX_SIZE: 50,
+  // Maximum queued requests during disconnection
+  REQUEST_MAX_RETRIES: 3,
+  // Max retries per request before giving up
+  REQUEST_RETRY_BASE_DELAY: 200,
+  // Base delay for request retry backoff
+  REQUEST_RETRY_MAX_DELAY: 2e3,
+  // Max delay for request retry backoff
+  QUEUE_DRAIN_DELAY: 50,
+  // Delay between processing queued requests
+  // Optimistic health - don't surface unhealthy state immediately
+  HEALTH_GRACE_PERIOD_MS: 1e3,
+  // Wait this long before showing unhealthy (reduced from 3s)
+  // Critical operation settings
+  CRITICAL_OP_TIMEOUT: 12e4
+  // 2 minutes for critical operations (transfers, signing)
+};
+const generateNonce = () => {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
 };
 const calculateBackoffDelay = (attempt, baseDelay, maxDelay) => Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
 const clearTimeoutSafe = (ref) => {
@@ -111,17 +134,74 @@ const BridgeContext = createContext(null);
 function createBridgeInstance(deps) {
   const {
     portRef,
+    portDisconnectedRef,
     pendingRequestsRef,
+    requestQueueRef,
+    activeIdempotencyKeysRef,
     eventListenersRef,
     messageIdRef,
     isConnectedRef,
+    isReconnectingRef,
     consecutiveTimeoutsRef,
     reconnectionGracePeriodRef,
     healthPausedUntilRef,
     defaultTimeout,
     timeoutFailureThreshold,
-    onReconnectNeeded
-  } = deps;
+    onReconnectNeeded} = deps;
+  const isPortValid = () => {
+    if (!portRef.current) return false;
+    if (portDisconnectedRef.current) return false;
+    if (!isConnectedRef.current) return false;
+    return true;
+  };
+  const generateIdempotencyKey = (key, payload) => {
+    const isWriteOperation = !key.startsWith("get") && !key.startsWith("fetch") && key !== "__ping__";
+    if (!isWriteOperation) return "";
+    try {
+      return `${key}:${JSON.stringify(payload)}`;
+    } catch {
+      return `${key}:${Date.now()}`;
+    }
+  };
+  const queueRequest = (id, key, payload, timeoutDuration, resolve, reject, idempotencyKey) => {
+    if (key === "__ping__" || key === "__bridge_diagnostics__") {
+      return false;
+    }
+    if (requestQueueRef.current.length >= CONFIG.REQUEST_QUEUE_MAX_SIZE) {
+      {
+        console.warn("[Bridge] Request queue full, rejecting request");
+      }
+      return false;
+    }
+    if (idempotencyKey && activeIdempotencyKeysRef.current.has(idempotencyKey)) {
+      {
+        console.log(`[Bridge] Duplicate request detected, skipping: ${key}`);
+      }
+      return true;
+    }
+    if (idempotencyKey) {
+      activeIdempotencyKeysRef.current.add(idempotencyKey);
+    }
+    const queuedRequest = {
+      id,
+      key,
+      payload,
+      timeoutDuration,
+      resolve,
+      reject,
+      retryCount: 0,
+      maxRetries: CONFIG.REQUEST_MAX_RETRIES,
+      queuedAt: Date.now(),
+      idempotencyKey
+    };
+    requestQueueRef.current.push(queuedRequest);
+    {
+      console.log(
+        `[Bridge] Request queued: ${key} (queue size: ${requestQueueRef.current.length})`
+      );
+    }
+    return true;
+  };
   const rejectAllPending = (message) => {
     pendingRequestsRef.current.forEach(({ reject, timeout, timeoutDuration }, id) => {
       if (timeoutDuration <= timeoutFailureThreshold) {
@@ -134,19 +214,29 @@ function createBridgeInstance(deps) {
   const send = (key, payload, timeoutDuration = defaultTimeout) => {
     return new Promise((resolve, reject) => {
       const id = `msg_${++messageIdRef.current}`;
+      const idempotencyKey = generateIdempotencyKey(key, payload);
       const finalizePendingWithError = (error) => {
         const pending = pendingRequestsRef.current.get(id);
         if (!pending) return;
         clearTimeout(pending.timeout);
         pendingRequestsRef.current.delete(id);
+        if (idempotencyKey) {
+          activeIdempotencyKeysRef.current.delete(idempotencyKey);
+        }
         pending.reject(error instanceof Error ? error : new Error(error));
       };
-      const triggerRuntimeFallback = (reason) => {
+      const triggerRuntimeFallback = (reason, retryCount = 0) => {
+        const MAX_FALLBACK_RETRIES = 2;
+        const FALLBACK_RETRY_DELAY = 300;
         {
-          console.warn(`[Bridge] Falling back to runtime.sendMessage (${reason})`);
+          console.warn(
+            `[Bridge] Falling back to runtime.sendMessage (${reason})${retryCount > 0 ? ` [retry ${retryCount}]` : ""}`
+          );
         }
         recordDiagnostics.fallbackSent(reason);
-        onReconnectNeeded();
+        if (retryCount === 0) {
+          onReconnectNeeded();
+        }
         if (!chrome?.runtime?.sendMessage) {
           const message = "chrome.runtime.sendMessage not available";
           recordDiagnostics.fallbackError(message);
@@ -159,13 +249,24 @@ function createBridgeInstance(deps) {
               id,
               key,
               payload,
-              metadata: { transport: "direct", fallbackReason: reason },
+              metadata: { transport: "direct", fallbackReason: reason, retryCount },
               [DIRECT_MESSAGE_FLAG]: true
             },
             (response) => {
               const runtimeError = consumeRuntimeError();
               const pending = pendingRequestsRef.current.get(id);
               if (!pending) return;
+              if (runtimeError?.includes("Receiving end does not exist") && retryCount < MAX_FALLBACK_RETRIES) {
+                if (BRIDGE_ENABLE_LOGS) {
+                  console.warn(
+                    `[Bridge] SW not ready, retrying fallback in ${FALLBACK_RETRY_DELAY}ms...`
+                  );
+                }
+                setTimeout(() => {
+                  triggerRuntimeFallback(reason, retryCount + 1);
+                }, FALLBACK_RETRY_DELAY);
+                return;
+              }
               if (runtimeError) {
                 recordDiagnostics.fallbackError(runtimeError);
                 clearTimeout(pending.timeout);
@@ -226,10 +327,32 @@ function createBridgeInstance(deps) {
         resolve,
         reject,
         timeout,
-        timeoutDuration
+        timeoutDuration,
+        key,
+        payload
       });
-      if (!portRef.current) {
-        triggerRuntimeFallback("port-unavailable");
+      if (!isPortValid()) {
+        if (isReconnectingRef.current) {
+          clearTimeout(timeout);
+          pendingRequestsRef.current.delete(id);
+          const queued = queueRequest(
+            id,
+            key,
+            payload,
+            timeoutDuration,
+            resolve,
+            reject,
+            idempotencyKey
+          );
+          if (queued) {
+            {
+              console.log(`[Bridge] Request queued during reconnection: ${key}`);
+            }
+            return;
+          }
+        }
+        const reason = !portRef.current ? "port-unavailable" : portDisconnectedRef.current ? "port-disconnected" : "port-not-connected";
+        triggerRuntimeFallback(reason);
         return;
       }
       try {
@@ -237,6 +360,23 @@ function createBridgeInstance(deps) {
         setTimeout(() => {
           const errorMessage = consumeRuntimeError();
           if (errorMessage && pendingRequestsRef.current.has(id)) {
+            if (isReconnectingRef.current) {
+              const pending = pendingRequestsRef.current.get(id);
+              if (pending) {
+                clearTimeout(pending.timeout);
+                pendingRequestsRef.current.delete(id);
+                const queued = queueRequest(
+                  id,
+                  key,
+                  payload,
+                  timeoutDuration,
+                  pending.resolve,
+                  pending.reject,
+                  idempotencyKey
+                );
+                if (queued) return;
+              }
+            }
             finalizePendingWithError(errorMessage);
           }
         }, 0);
@@ -304,7 +444,86 @@ function createBridgeInstance(deps) {
       {
         console.log(`[Bridge] Health checks paused for ${Math.round(durationMs / 1e3)}s`);
       }
-    }
+    },
+    ensureConnected: async () => {
+      if (!isPortValid()) {
+        {
+          console.warn("[Bridge] ensureConnected: Port invalid, triggering reconnect");
+        }
+        onReconnectNeeded();
+        return false;
+      }
+      const QUICK_PING_TIMEOUT = 5e3;
+      try {
+        await send("__ping__", void 0, QUICK_PING_TIMEOUT);
+        return true;
+      } catch {
+        {
+          console.warn("[Bridge] ensureConnected: Ping failed, SW may be unresponsive");
+        }
+        return false;
+      }
+    },
+    sendCritical: async (key, payload, options, timeoutDuration = CONFIG.CRITICAL_OP_TIMEOUT) => {
+      const nonce = options?.nonce || generateNonce();
+      const noQueue = options?.noQueue ?? false;
+      if (noQueue && !isPortValid()) {
+        throw new Error("Not connected. Please try again.");
+      }
+      const criticalPayload = {
+        __critical__: true,
+        __nonce__: nonce,
+        __timestamp__: Date.now(),
+        data: payload
+      };
+      let acknowledged = false;
+      const ackKey = `__ack__:${nonce}`;
+      const ackPromise = new Promise((resolveAck) => {
+        const ackHandler = () => {
+          acknowledged = true;
+          options?.onAcknowledged?.();
+          resolveAck();
+          off(ackKey, ackHandler);
+        };
+        on(ackKey, ackHandler);
+        setTimeout(() => {
+          off(ackKey, ackHandler);
+          resolveAck();
+        }, 5e3);
+      });
+      {
+        console.log(`[Bridge] Sending critical operation: ${key} (nonce: ${nonce})`);
+      }
+      try {
+        const [data] = await Promise.all([
+          send(key, criticalPayload, timeoutDuration),
+          ackPromise
+        ]);
+        if (BRIDGE_ENABLE_LOGS) {
+          console.log(
+            `[Bridge] Critical operation completed: ${key} (nonce: ${nonce}, acked: ${acknowledged})`
+          );
+        }
+        return {
+          data,
+          nonce,
+          acknowledged
+        };
+      } catch (error) {
+        {
+          console.error(
+            `[Bridge] Critical operation failed: ${key} (nonce: ${nonce}, acked: ${acknowledged})`,
+            error
+          );
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        err.nonce = nonce;
+        err.acknowledged = acknowledged;
+        throw err;
+      }
+    },
+    sendWithNonce: async (key, payload, options, timeoutDuration) => bridge.sendCritical(key, payload, options, timeoutDuration),
+    sendIdempotent: async (key, payload, options, timeoutDuration) => bridge.sendCritical(key, payload, options, timeoutDuration)
   };
   return bridge;
 }
@@ -387,8 +606,13 @@ const BridgeProvider = ({
   const [error, setError] = useState(null);
   const [isServiceWorkerAlive, setIsServiceWorkerAlive] = useState(false);
   const portRef = useRef(null);
+  const portDisconnectedRef = useRef(false);
   const isConnectedRef = useRef(false);
   const isConnectingRef = useRef(false);
+  const isReconnectingRef = useRef(false);
+  const requestQueueRef = useRef([]);
+  const activeIdempotencyKeysRef = useRef(/* @__PURE__ */ new Set());
+  const queueDrainTimeoutRef = useRef(null);
   const retryCountRef = useRef(0);
   const reconnectTimeoutRef = useRef(null);
   const maxRetryCooldownRef = useRef(null);
@@ -433,7 +657,7 @@ const BridgeProvider = ({
     },
     [onError, updateStatus]
   );
-  const cleanup = useCallback((emitDisconnect = true) => {
+  const cleanup = useCallback((emitDisconnect = true, preserveQueue = false) => {
     const wasConnected = isConnectedRef.current || portRef.current !== null;
     if (emitDisconnect && wasConnected) {
       eventListenersRef.current.get("bridge:disconnected")?.forEach((handler) => {
@@ -448,6 +672,7 @@ const BridgeProvider = ({
     }
     clearTimeoutSafe(reconnectTimeoutRef);
     clearTimeoutSafe(triggerReconnectTimeoutRef);
+    clearTimeoutSafe(queueDrainTimeoutRef);
     clearIntervalSafe(errorCheckIntervalRef);
     clearIntervalSafe(pingIntervalRef);
     if (portRef.current) {
@@ -457,11 +682,50 @@ const BridgeProvider = ({
       }
       portRef.current = null;
     }
-    pendingRequestsRef.current.forEach(({ reject, timeout }) => {
-      clearTimeout(timeout);
-      reject(new Error("Bridge disconnected"));
-    });
-    pendingRequestsRef.current.clear();
+    portDisconnectedRef.current = false;
+    if (preserveQueue) {
+      const pendingCount = pendingRequestsRef.current.size;
+      if (pendingCount > 0 && BRIDGE_ENABLE_LOGS) {
+        console.log(
+          `[Bridge] Preserving ${pendingCount} pending requests for retry after reconnect`
+        );
+      }
+      pendingRequestsRef.current.forEach(
+        ({ resolve, reject, timeout, timeoutDuration, key, payload }, id) => {
+          clearTimeout(timeout);
+          requestQueueRef.current.push({
+            id,
+            key,
+            payload,
+            // Preserve the original payload for retry
+            timeoutDuration,
+            resolve,
+            reject,
+            retryCount: 0,
+            maxRetries: CONFIG.REQUEST_MAX_RETRIES,
+            queuedAt: Date.now()
+          });
+          {
+            console.log(`[Bridge] Queued pending request for retry: ${key}`);
+          }
+        }
+      );
+      pendingRequestsRef.current.clear();
+    } else {
+      pendingRequestsRef.current.forEach(({ reject, timeout }) => {
+        clearTimeout(timeout);
+        reject(new Error("Bridge disconnected"));
+      });
+      pendingRequestsRef.current.clear();
+      requestQueueRef.current.forEach(({ reject, idempotencyKey }) => {
+        if (idempotencyKey) {
+          activeIdempotencyKeysRef.current.delete(idempotencyKey);
+        }
+        reject(new Error("Bridge disconnected"));
+      });
+      requestQueueRef.current = [];
+      activeIdempotencyKeysRef.current.clear();
+    }
     if (!emitDisconnect) {
       eventListenersRef.current.clear();
     }
@@ -484,7 +748,14 @@ const BridgeProvider = ({
       return;
     }
     if (message.type === "broadcast" && message.key) {
-      eventListenersRef.current.get(message.key)?.forEach((handler) => {
+      const listeners = eventListenersRef.current.get(message.key);
+      const listenerCount = listeners?.size ?? 0;
+      {
+        console.log(
+          `[Bridge] \u{1F4E1} Received broadcast: ${message.key}, dispatching to ${listenerCount} listeners`
+        );
+      }
+      listeners?.forEach((handler) => {
         try {
           handler(message.payload);
         } catch (err) {
@@ -499,6 +770,95 @@ const BridgeProvider = ({
       console.warn("[Bridge] Received response for unknown/expired request:", message.id);
     }
   }, []);
+  const drainRequestQueue = useCallback(() => {
+    if (requestQueueRef.current.length === 0) {
+      {
+        console.log("[Bridge] Request queue empty, nothing to drain");
+      }
+      return;
+    }
+    if (!bridgeRef.current || !isConnectedRef.current) {
+      {
+        console.log("[Bridge] Cannot drain queue - not connected");
+      }
+      return;
+    }
+    {
+      console.log(`[Bridge] Draining request queue (${requestQueueRef.current.length} requests)`);
+    }
+    const processNextRequest = () => {
+      if (!isMountedRef.current || !isConnectedRef.current) return;
+      const request = requestQueueRef.current.shift();
+      if (!request) {
+        {
+          console.log("[Bridge] Request queue drained successfully");
+        }
+        return;
+      }
+      const queuedDuration = Date.now() - request.queuedAt;
+      if (queuedDuration > request.timeoutDuration) {
+        {
+          console.warn(`[Bridge] Queued request expired: ${request.key}`);
+        }
+        if (request.idempotencyKey) {
+          activeIdempotencyKeysRef.current.delete(request.idempotencyKey);
+        }
+        request.reject(new Error(`Request expired while queued: ${request.key}`));
+        queueDrainTimeoutRef.current = setTimeout(processNextRequest, CONFIG.QUEUE_DRAIN_DELAY);
+        return;
+      }
+      {
+        console.log(
+          `[Bridge] Re-sending queued request: ${request.key} (retry ${request.retryCount + 1}/${request.maxRetries})`
+        );
+      }
+      bridgeRef.current.send(request.key, request.payload, request.timeoutDuration - queuedDuration).then((data) => {
+        {
+          console.log(`[Bridge] \u2705 Queued request succeeded: ${request.key}`);
+        }
+        if (request.idempotencyKey) {
+          activeIdempotencyKeysRef.current.delete(request.idempotencyKey);
+        }
+        request.resolve(data);
+      }).catch((error2) => {
+        request.retryCount++;
+        if (request.retryCount < request.maxRetries && isConnectedRef.current) {
+          const retryDelay = calculateBackoffDelay(
+            request.retryCount,
+            CONFIG.REQUEST_RETRY_BASE_DELAY,
+            CONFIG.REQUEST_RETRY_MAX_DELAY
+          );
+          {
+            console.log(
+              `[Bridge] Request failed, re-queuing: ${request.key} (retry in ${retryDelay}ms)`
+            );
+          }
+          setTimeout(() => {
+            if (isMountedRef.current) {
+              requestQueueRef.current.unshift(request);
+              processNextRequest();
+            }
+          }, retryDelay);
+          return;
+        }
+        {
+          console.error(
+            `[Bridge] \u274C Queued request failed after ${request.maxRetries} retries: ${request.key}`,
+            error2
+          );
+        }
+        if (request.idempotencyKey) {
+          activeIdempotencyKeysRef.current.delete(request.idempotencyKey);
+        }
+        request.reject(error2);
+      }).finally(() => {
+        if (isMountedRef.current) {
+          queueDrainTimeoutRef.current = setTimeout(processNextRequest, CONFIG.QUEUE_DRAIN_DELAY);
+        }
+      });
+    };
+    processNextRequest();
+  }, []);
   const scheduleReconnect = useCallback(
     (connectFn) => {
       if (!isMountedRef.current) return;
@@ -546,6 +906,7 @@ const BridgeProvider = ({
         }
         return;
       }
+      isReconnectingRef.current = true;
       swRestartRetryCountRef.current++;
       const delay = calculateBackoffDelay(
         swRestartRetryCountRef.current,
@@ -578,7 +939,7 @@ const BridgeProvider = ({
       return;
     }
     isConnectingRef.current = true;
-    cleanup(false);
+    cleanup(false, true);
     if (!chrome?.runtime?.connect) {
       handleError(new Error("Chrome runtime not available"));
       isConnectingRef.current = false;
@@ -620,6 +981,7 @@ const BridgeProvider = ({
         if (BRIDGE_ENABLE_LOGS) {
           console.warn("[Bridge] *** onDisconnect FIRED ***");
         }
+        portDisconnectedRef.current = true;
         isConnectingRef.current = false;
         const disconnectError = consumeRuntimeError();
         recordDiagnostics.portDisconnect(disconnectError);
@@ -628,7 +990,7 @@ const BridgeProvider = ({
           console.warn("[Bridge] isMounted:", isMountedRef.current);
         }
         updateStatus("disconnected");
-        cleanup();
+        cleanup(true, true);
         if (isMountedRef.current) {
           if (BRIDGE_ENABLE_LOGS) {
             console.log("[Bridge] Scheduling SW restart reconnect...");
@@ -644,28 +1006,36 @@ const BridgeProvider = ({
         if (!isMountedRef.current) return;
         setIsServiceWorkerAlive(false);
         updateStatus("reconnecting");
+        isReconnectingRef.current = true;
         retryCountRef.current = 0;
         isConnectingRef.current = false;
         clearTimeoutSafe(triggerReconnectTimeoutRef);
         triggerReconnectTimeoutRef.current = setTimeout(() => {
           if (!isMountedRef.current) return;
-          cleanup(false);
+          cleanup(false, true);
           connect();
         }, CONFIG.RECONNECT_DELAY);
       };
       const bridgeInstance = createBridgeInstance({
         portRef,
+        portDisconnectedRef,
         pendingRequestsRef,
+        requestQueueRef,
+        activeIdempotencyKeysRef,
         eventListenersRef,
         messageIdRef,
         isConnectedRef,
+        isReconnectingRef,
         consecutiveTimeoutsRef,
         reconnectionGracePeriodRef,
         healthPausedUntilRef,
         defaultTimeout,
         timeoutFailureThreshold,
-        onReconnectNeeded: triggerReconnect
+        onReconnectNeeded: triggerReconnect,
+        drainRequestQueue
       });
+      portDisconnectedRef.current = false;
+      isReconnectingRef.current = false;
       setBridge(bridgeInstance);
       isConnectedRef.current = true;
       updateStatus("connected");
@@ -675,6 +1045,145 @@ const BridgeProvider = ({
       swRestartRetryCountRef.current = 0;
       consecutiveTimeoutsRef.current = 0;
       isConnectingRef.current = false;
+      if (BRIDGE_ENABLE_LOGS) {
+        const queueSize = requestQueueRef.current.length;
+        const pendingSize = pendingRequestsRef.current.size;
+        console.log(`[Bridge] \u2705 PORT CONNECTED | Queued: ${queueSize} | Pending: ${pendingSize}`);
+      }
+      const verifyConnection = (targetPort) => {
+        const VERIFY_PING_TIMEOUT = 8e3;
+        const MAX_VERIFY_RETRIES = 3;
+        const VERIFY_RETRY_DELAY = 2e3;
+        const attemptVerify = (attempt) => {
+          if (portRef.current !== targetPort) {
+            if (BRIDGE_ENABLE_LOGS) {
+              console.log(`[Bridge] Verification aborted - port changed (attempt ${attempt})`);
+            }
+            return Promise.resolve(false);
+          }
+          if (attempt > MAX_VERIFY_RETRIES) {
+            return Promise.resolve(false);
+          }
+          if (BRIDGE_ENABLE_LOGS) {
+            console.log(
+              `[Bridge] Verifying connection (attempt ${attempt}/${MAX_VERIFY_RETRIES})...`
+            );
+          }
+          const pingId = `verify_${Date.now()}_${attempt}`;
+          return new Promise((resolve) => {
+            if (portRef.current !== targetPort) {
+              resolve(false);
+              return;
+            }
+            const timeout = setTimeout(() => {
+              pendingRequestsRef.current.delete(pingId);
+              if (portRef.current !== targetPort) {
+                resolve(false);
+                return;
+              }
+              if (BRIDGE_ENABLE_LOGS) {
+                console.warn(`[Bridge] Verification ping timeout (attempt ${attempt})`);
+              }
+              setTimeout(() => {
+                attemptVerify(attempt + 1).then(resolve);
+              }, VERIFY_RETRY_DELAY);
+            }, VERIFY_PING_TIMEOUT);
+            pendingRequestsRef.current.set(pingId, {
+              resolve: () => {
+                clearTimeout(timeout);
+                if (portRef.current !== targetPort) {
+                  resolve(false);
+                  return;
+                }
+                if (BRIDGE_ENABLE_LOGS) {
+                  console.log("[Bridge] \u2705 VERIFIED - SW is responding");
+                }
+                resolve(true);
+              },
+              reject: () => {
+                clearTimeout(timeout);
+                if (portRef.current !== targetPort) {
+                  resolve(false);
+                  return;
+                }
+                if (BRIDGE_ENABLE_LOGS) {
+                  console.warn(`[Bridge] Verification ping error (attempt ${attempt})`);
+                }
+                setTimeout(() => {
+                  attemptVerify(attempt + 1).then(resolve);
+                }, VERIFY_RETRY_DELAY);
+              },
+              timeout,
+              timeoutDuration: VERIFY_PING_TIMEOUT,
+              key: "__ping__",
+              payload: void 0
+            });
+            try {
+              targetPort.postMessage({ id: pingId, key: "__ping__", payload: void 0 });
+            } catch (e) {
+              clearTimeout(timeout);
+              pendingRequestsRef.current.delete(pingId);
+              if (portRef.current !== targetPort) {
+                resolve(false);
+                return;
+              }
+              if (BRIDGE_ENABLE_LOGS) {
+                console.warn(`[Bridge] Verification postMessage error (attempt ${attempt}):`, e);
+              }
+              setTimeout(() => {
+                attemptVerify(attempt + 1).then(resolve);
+              }, VERIFY_RETRY_DELAY);
+            }
+          });
+        };
+        return attemptVerify(1);
+      };
+      const startVerification = () => {
+        if (BRIDGE_ENABLE_LOGS) {
+          console.log("[Bridge] Starting verification after initial delay...");
+        }
+        verifyConnection(port).then((verified) => {
+          if (!isMountedRef.current || portRef.current !== port) {
+            if (BRIDGE_ENABLE_LOGS) {
+              console.log("[Bridge] Verification callback aborted - context changed");
+            }
+            return;
+          }
+          if (!verified) {
+            if (BRIDGE_ENABLE_LOGS) {
+              console.error("[Bridge] \u274C Connection verification failed - SW not responding");
+            }
+            isConnectingRef.current = false;
+            isReconnectingRef.current = true;
+            scheduleSwRestartReconnect(connect);
+            return;
+          }
+          if (BRIDGE_ENABLE_LOGS) {
+            const queueSize = requestQueueRef.current.length;
+            console.log(
+              `[Bridge] \u2705 RECONNECTED SUCCESSFULLY | Queue: ${queueSize} requests to drain`
+            );
+          }
+          setTimeout(() => {
+            if (isMountedRef.current && isConnectedRef.current) {
+              drainRequestQueue();
+            }
+          }, 200);
+          if (BRIDGE_ENABLE_LOGS) {
+            console.log("[Bridge] Emitting bridge:connected event to stores");
+          }
+          eventListenersRef.current.get("bridge:connected")?.forEach((handler) => {
+            try {
+              handler({ timestamp: Date.now() });
+            } catch (err) {
+              if (BRIDGE_ENABLE_LOGS) {
+                console.warn("[Bridge] bridge:connected handler error:", err);
+              }
+            }
+          });
+        });
+      };
+      setTimeout(startVerification, 2e3);
       reconnectionGracePeriodRef.current = true;
       setTimeout(() => {
         reconnectionGracePeriodRef.current = false;
@@ -682,15 +1191,6 @@ const BridgeProvider = ({
           console.log("[Bridge] Grace period ended, timeout monitoring active");
         }
       }, 1e4);
-      eventListenersRef.current.get("bridge:connected")?.forEach((handler) => {
-        try {
-          handler({ timestamp: Date.now() });
-        } catch (err) {
-          if (BRIDGE_ENABLE_LOGS) {
-            console.warn("[Bridge] bridge:connected handler error:", err);
-          }
-        }
-      });
       const rejectAllPendingRequests = (message) => {
         pendingRequestsRef.current.forEach(({ reject, timeout, timeoutDuration }, id) => {
           if (timeoutDuration <= timeoutFailureThreshold) {
@@ -723,6 +1223,7 @@ const BridgeProvider = ({
     handleMessage,
     scheduleReconnect,
     scheduleSwRestartReconnect,
+    drainRequestQueue,
     defaultTimeout,
     updateStatus,
     pingInterval
@@ -980,15 +1481,19 @@ function broadcastHealthChange(status, isHealthy) {
   });
 }
 const ServiceWorkerHealthContext = createContext(null);
+const HEALTH_GRACE_PERIOD_MS = 1e3;
 const ServiceWorkerHealthProvider = ({
   children,
   onHealthChange
 }) => {
   const bridgeContext = useContext(BridgeContext);
   const [lastHealthyAt, setLastHealthyAt] = useState(null);
+  const [unhealthyStartedAt, setUnhealthyStartedAt] = useState(null);
+  const [graceExpired, setGraceExpired] = useState(false);
+  const graceTimeoutRef = useRef(null);
   const bridgeStatus = bridgeContext?.status;
   const isServiceWorkerAlive = bridgeContext?.isServiceWorkerAlive ?? false;
-  const derivedStatus = useMemo(() => {
+  const rawStatus = useMemo(() => {
     if (!bridgeStatus) return "unknown";
     if (bridgeStatus === "connected" && isServiceWorkerAlive) {
       return "healthy";
@@ -998,14 +1503,41 @@ const ServiceWorkerHealthProvider = ({
     }
     return "unhealthy";
   }, [bridgeStatus, isServiceWorkerAlive]);
+  useEffect(() => {
+    if (rawStatus === "healthy") {
+      setUnhealthyStartedAt(null);
+      setGraceExpired(false);
+      if (graceTimeoutRef.current) {
+        clearTimeout(graceTimeoutRef.current);
+        graceTimeoutRef.current = null;
+      }
+    } else if (!unhealthyStartedAt) {
+      setUnhealthyStartedAt(Date.now());
+      graceTimeoutRef.current = setTimeout(() => {
+        setGraceExpired(true);
+      }, HEALTH_GRACE_PERIOD_MS);
+    }
+    return () => {
+      if (graceTimeoutRef.current) {
+        clearTimeout(graceTimeoutRef.current);
+      }
+    };
+  }, [rawStatus, unhealthyStartedAt]);
+  const derivedStatus = useMemo(() => {
+    if (rawStatus === "healthy") return "healthy";
+    if (!graceExpired && lastHealthyAt) {
+      return "healthy";
+    }
+    return rawStatus;
+  }, [rawStatus, graceExpired, lastHealthyAt]);
   const isHealthy = derivedStatus === "healthy";
   const isRecovering = derivedStatus === "recovering";
   const isLoading = derivedStatus === "recovering" || derivedStatus === "unknown";
   useEffect(() => {
-    if (isHealthy) {
+    if (rawStatus === "healthy") {
       setLastHealthyAt(Date.now());
     }
-  }, [isHealthy]);
+  }, [rawStatus]);
   useEffect(() => {
     broadcastHealthChange(derivedStatus, isHealthy);
     onHealthChange?.(derivedStatus, isHealthy);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromahq/react",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "description": "React bindings for the Chroma Chrome extension framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,16 +41,20 @@
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-typescript": "^12.1.3",
+    "@testing-library/react": "^16.0.0",
     "@types/react": "^18.2.7",
+    "jsdom": "^25.0.0",
     "rollup": "^4.8.0",
     "rollup-plugin-dts": "^6.1.0",
     "rollup-plugin-esbuild": "^6.1.0",
     "typescript": "^5.6.0",
     "react": "^19.1.0",
-    "react-dom": "^19.1.0"
+    "react-dom": "^19.1.0",
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "rollup -c",
-    "dev": "rollup -c --watch"
+    "dev": "rollup -c --watch",
+    "test": "vitest run"
   }
 }