@chromahq/react 1.0.44 → 1.0.46

package/dist/index.d.ts

@@ -36,6 +36,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;

package/dist/index.js

@@ -86,8 +86,22 @@ 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: 3e3
+  // Wait this long before showing unhealthy
 };
 const calculateBackoffDelay = (attempt, baseDelay, maxDelay) => Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
 const clearTimeoutSafe = (ref) => {
@@ -111,17 +125,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 +205,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 +240,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);
@@ -228,8 +320,28 @@ function createBridgeInstance(deps) {
         timeout,
         timeoutDuration
       });
-      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 +349,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,6 +433,25 @@ 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;
+      }
     }
   };
   return bridge;
@@ -387,8 +535,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 +586,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 +601,7 @@ const BridgeProvider = ({
     }
     clearTimeoutSafe(reconnectTimeoutRef);
     clearTimeoutSafe(triggerReconnectTimeoutRef);
+    clearTimeoutSafe(queueDrainTimeoutRef);
     clearIntervalSafe(errorCheckIntervalRef);
     clearIntervalSafe(pingIntervalRef);
     if (portRef.current) {
@@ -457,11 +611,40 @@ 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) {
+      pendingRequestsRef.current.forEach(({ resolve, reject, timeout, timeoutDuration }, id) => {
+        clearTimeout(timeout);
+        const key = id.split("_")[0] || "unknown";
+        requestQueueRef.current.push({
+          id,
+          key,
+          payload: void 0,
+          // We don't have the payload anymore, but the request is already in flight
+          timeoutDuration,
+          resolve,
+          reject,
+          retryCount: 0,
+          maxRetries: CONFIG.REQUEST_MAX_RETRIES,
+          queuedAt: Date.now()
+        });
+      });
+      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();
     }
@@ -499,6 +682,86 @@ 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) => {
+        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;
+        }
+        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 +809,7 @@ const BridgeProvider = ({
         }
         return;
       }
+      isReconnectingRef.current = true;
       swRestartRetryCountRef.current++;
       const delay = calculateBackoffDelay(
         swRestartRetryCountRef.current,
@@ -578,7 +842,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 +884,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 +893,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 +909,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 +948,11 @@ const BridgeProvider = ({
       swRestartRetryCountRef.current = 0;
       consecutiveTimeoutsRef.current = 0;
       isConnectingRef.current = false;
+      setTimeout(() => {
+        if (isMountedRef.current && isConnectedRef.current) {
+          drainRequestQueue();
+        }
+      }, 200);
       reconnectionGracePeriodRef.current = true;
       setTimeout(() => {
         reconnectionGracePeriodRef.current = false;
@@ -723,6 +1001,7 @@ const BridgeProvider = ({
     handleMessage,
     scheduleReconnect,
     scheduleSwRestartReconnect,
+    drainRequestQueue,
     defaultTimeout,
     updateStatus,
     pingInterval
@@ -980,15 +1259,19 @@ function broadcastHealthChange(status, isHealthy) {
   });
 }
 const ServiceWorkerHealthContext = createContext(null);
+const HEALTH_GRACE_PERIOD_MS = 3e3;
 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 +1281,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 (rawStatus !== "healthy" && !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.44",
+  "version": "1.0.46",
   "description": "React bindings for the Chroma Chrome extension framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",