@chromahq/react 1.0.23 → 1.0.25

package/dist/index.d.ts

@@ -76,7 +76,158 @@ interface ConnectionStatusResult {
     reconnect: (() => void) | undefined;
     /** Any connection error */
     error: Error | null | undefined;
+    /** Whether the system is fully ready (bridge connected + optional store ready) */
+    isReady: boolean;
+    /** Whether the system is loading (bridge connecting/reconnecting OR store not ready) */
+    isLoading: boolean;
 }
-declare const useConnectionStatus: () => ConnectionStatusResult;
+/**
+ * Store interface for readiness checking.
+ * Pass the store instance directly (e.g., `appStore`), NOT via useStore() hook.
+ */
+interface StoreReadyMethods {
+    onReady: (callback: () => void) => () => void;
+    isReady: () => boolean;
+}
+/**
+ * Hook to get unified connection status.
+ *
+ * @param store Optional store INSTANCE to include in readiness check.
+ *              Pass the store directly (e.g., `appStore`), NOT via useStore() hook.
+ *
+ * @example
+ * ```tsx
+ * // Correct - pass store instance directly:
+ * import { appStore } from './stores/app';
+ * const { isLoading } = useConnectionStatus(appStore);
+ *
+ * // WRONG - don't use useStore() to get the store:
+ * const store = useStore(s => s); // This won't work!
+ * ```
+ */
+declare const useConnectionStatus: (store?: StoreReadyMethods) => ConnectionStatusResult;
+
+/**
+ * ServiceWorkerHealth - Single source of truth for service worker health status.
+ *
+ * This module provides a centralized health monitoring system that:
+ * 1. Monitors the service worker connection via the bridge
+ * 2. Broadcasts status changes to all subscribers (bridge, store, UI)
+ * 3. Provides a simple `isHealthy` boolean for UI components
+ *
+ * Usage:
+ * ```tsx
+ * // In your app root, wrap with ServiceWorkerHealthProvider:
+ * <BridgeProvider>
+ *   <ServiceWorkerHealthProvider>
+ *     <App />
+ *   </ServiceWorkerHealthProvider>
+ * </BridgeProvider>
+ *
+ * // In any component, use the hook:
+ * const { isHealthy, isRecovering } = useServiceWorkerHealth();
+ *
+ * if (!isHealthy) {
+ *   return <Spinner message="Reconnecting..." />;
+ * }
+ * ```
+ */
+
+type HealthStatus = 'healthy' | 'unhealthy' | 'recovering' | 'unknown';
+interface ServiceWorkerHealthContextValue {
+    /** Current health status */
+    status: HealthStatus;
+    /** Simple boolean: true when SW is connected and responsive */
+    isHealthy: boolean;
+    /** True when actively trying to reconnect */
+    isRecovering: boolean;
+    /** True during initial connection or recovery */
+    isLoading: boolean;
+    /** Timestamp of last successful ping (ms) */
+    lastHealthyAt: number | null;
+    /** Force a reconnection attempt */
+    forceReconnect: () => void;
+}
+interface ServiceWorkerHealthProviderProps {
+    children: ReactNode;
+    /**
+     * Optional callback when health status changes.
+     * Useful for stores to listen and react (e.g., pause operations).
+     */
+    onHealthChange?: (status: HealthStatus, isHealthy: boolean) => void;
+}
+type HealthSubscriber = (status: HealthStatus, isHealthy: boolean) => void;
+/**
+ * Subscribe to health status changes from outside React.
+ * Returns an unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * // In BridgeStore
+ * const unsubscribe = subscribeToHealth((status, isHealthy) => {
+ *   if (!isHealthy) {
+ *     // Pause operations, show loading state
+ *   } else {
+ *     // Resume operations
+ *   }
+ * });
+ * ```
+ */
+declare function subscribeToHealth(callback: HealthSubscriber): () => void;
+/**
+ * Get current health status synchronously.
+ * Useful for non-React code that needs immediate access.
+ */
+declare function getHealthStatus(): {
+    status: HealthStatus;
+    isHealthy: boolean;
+};
+declare const ServiceWorkerHealthProvider: FC<ServiceWorkerHealthProviderProps>;
+/**
+ * Hook to access service worker health status.
+ *
+ * @returns Health status object with `isHealthy` boolean
+ * @throws Error if used outside ServiceWorkerHealthProvider
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { isHealthy, isRecovering } = useServiceWorkerHealth();
+ *
+ *   if (!isHealthy) {
+ *     return (
+ *       <div className="loading-overlay">
+ *         <Spinner />
+ *         <p>{isRecovering ? 'Reconnecting...' : 'Connection lost'}</p>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return <MainApp />;
+ * }
+ * ```
+ */
+declare function useServiceWorkerHealth(): ServiceWorkerHealthContextValue;
+/**
+ * Lightweight hook that directly consumes BridgeContext without needing
+ * ServiceWorkerHealthProvider. Use this for simple cases where you don't
+ * need the global subscription API.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { isHealthy } = useServiceWorkerHealthSimple();
+ *   if (!isHealthy) return <Spinner />;
+ *   return <MainApp />;
+ * }
+ * ```
+ */
+declare function useServiceWorkerHealthSimple(): {
+    isHealthy: boolean;
+    isRecovering: boolean;
+    isLoading: boolean;
+    reconnect: () => void;
+};
 
-export { BridgeProvider, useBridge, useBridgeQuery, useConnectionStatus };
+export { BridgeProvider, ServiceWorkerHealthProvider, getHealthStatus, subscribeToHealth, useBridge, useBridgeQuery, useConnectionStatus, useServiceWorkerHealth, useServiceWorkerHealthSimple };
+export type { HealthStatus, ServiceWorkerHealthContextValue };

package/dist/index.js

@@ -1,11 +1,12 @@
 import { jsx } from 'react/jsx-runtime';
-import { createContext, useState, useRef, useEffect, useCallback, useMemo, useContext } from 'react';
+import { createContext, useState, useRef, useEffect, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
 
 const BRIDGE_ENABLE_LOGS = true;
 const CONFIG = {
   RETRY_AFTER: 1e3,
   MAX_RETRIES: 10,
-  PING_INTERVAL: 5e3,
+  PING_INTERVAL: 2e3,
+  // Check every 2s for faster SW death detection
   MAX_RETRY_COOLDOWN: 3e4,
   DEFAULT_TIMEOUT: 1e4,
   MAX_RETRY_DELAY: 3e4,
@@ -46,6 +47,7 @@ function createBridgeInstance(deps) {
     messageIdRef,
     isConnectedRef,
     consecutiveTimeoutsRef,
+    reconnectionGracePeriodRef,
     defaultTimeout,
     onReconnectNeeded
   } = deps;
@@ -66,11 +68,15 @@ function createBridgeInstance(deps) {
       const timeout = setTimeout(() => {
         if (!pendingRequestsRef.current.has(id)) return;
         pendingRequestsRef.current.delete(id);
-        consecutiveTimeoutsRef.current++;
+        if (!reconnectionGracePeriodRef.current) {
+          consecutiveTimeoutsRef.current++;
+        }
         {
-          console.warn(`[Bridge] Request timed out: ${key} (${timeoutDuration}ms)`);
+          console.warn(
+            `[Bridge] Request timed out: ${key} (${timeoutDuration}ms)${reconnectionGracePeriodRef.current ? " [grace period]" : ""}`
+          );
         }
-        if (consecutiveTimeoutsRef.current >= CONFIG.CONSECUTIVE_FAILURE_THRESHOLD) {
+        if (!reconnectionGracePeriodRef.current && consecutiveTimeoutsRef.current >= CONFIG.CONSECUTIVE_FAILURE_THRESHOLD) {
           {
             console.warn(
               `[Bridge] ${consecutiveTimeoutsRef.current} consecutive timeouts, reconnecting...`
@@ -170,7 +176,8 @@ function startHealthMonitor(deps) {
     consecutivePingFailuresRef,
     pingInterval,
     setIsServiceWorkerAlive,
-    onReconnectNeeded
+    onReconnectNeeded,
+    rejectAllPendingRequests
   } = deps;
   clearIntervalSafe(pingIntervalRef);
   consecutivePingFailuresRef.current = 0;
@@ -197,9 +204,12 @@ function startHealthMonitor(deps) {
     }
     if (consecutivePingFailuresRef.current >= CONFIG.CONSECUTIVE_FAILURE_THRESHOLD) {
       {
-        console.warn("[Bridge] Service worker unresponsive, reconnecting...");
+        console.warn(
+          "[Bridge] Service worker unresponsive, rejecting pending requests and reconnecting..."
+        );
       }
       consecutivePingFailuresRef.current = 0;
+      rejectAllPendingRequests("Service worker unresponsive");
       onReconnectNeeded();
     }
   }, pingInterval);
@@ -230,6 +240,7 @@ const BridgeProvider = ({
   const errorCheckIntervalRef = useRef(null);
   const consecutivePingFailuresRef = useRef(0);
   const consecutiveTimeoutsRef = useRef(0);
+  const reconnectionGracePeriodRef = useRef(false);
   const pendingRequestsRef = useRef(/* @__PURE__ */ new Map());
   const eventListenersRef = useRef(/* @__PURE__ */ new Map());
   const messageIdRef = useRef(0);
@@ -263,7 +274,18 @@ const BridgeProvider = ({
     },
     [onError, updateStatus]
   );
-  const cleanup = useCallback(() => {
+  const cleanup = useCallback((emitDisconnect = true) => {
+    if (emitDisconnect) {
+      eventListenersRef.current.get("bridge:disconnected")?.forEach((handler) => {
+        try {
+          handler(void 0);
+        } catch (err) {
+          {
+            console.warn("[Bridge] bridge:disconnected handler error:", err);
+          }
+        }
+      });
+    }
     clearTimeoutSafe(reconnectTimeoutRef);
     clearTimeoutSafe(triggerReconnectTimeoutRef);
     clearIntervalSafe(errorCheckIntervalRef);
@@ -280,7 +302,6 @@ const BridgeProvider = ({
       reject(new Error("Bridge disconnected"));
     });
     pendingRequestsRef.current.clear();
-    eventListenersRef.current.clear();
     setIsServiceWorkerAlive(false);
     setBridge(null);
     isConnectingRef.current = false;
@@ -471,6 +492,7 @@ const BridgeProvider = ({
         messageIdRef,
         isConnectedRef,
         consecutiveTimeoutsRef,
+        reconnectionGracePeriodRef,
         defaultTimeout,
         onReconnectNeeded: triggerReconnect
       });
@@ -483,6 +505,13 @@ const BridgeProvider = ({
       swRestartRetryCountRef.current = 0;
       consecutiveTimeoutsRef.current = 0;
       isConnectingRef.current = false;
+      reconnectionGracePeriodRef.current = true;
+      setTimeout(() => {
+        reconnectionGracePeriodRef.current = false;
+        if (BRIDGE_ENABLE_LOGS) {
+          console.log("[Bridge] Grace period ended, timeout monitoring active");
+        }
+      }, 3e3);
       eventListenersRef.current.get("bridge:connected")?.forEach((handler) => {
         try {
           handler({ timestamp: Date.now() });
@@ -492,13 +521,22 @@ const BridgeProvider = ({
           }
         }
       });
+      const rejectAllPendingRequests = (message) => {
+        pendingRequestsRef.current.forEach(({ reject, timeout }) => {
+          clearTimeout(timeout);
+          reject(new Error(message));
+        });
+        pendingRequestsRef.current.clear();
+        consecutiveTimeoutsRef.current = 0;
+      };
       startHealthMonitor({
         bridge: bridgeInstance,
         pingIntervalRef,
         consecutivePingFailuresRef,
         pingInterval,
         setIsServiceWorkerAlive,
-        onReconnectNeeded: triggerReconnect
+        onReconnectNeeded: triggerReconnect,
+        rejectAllPendingRequests
       });
     } catch (e) {
       isConnectingRef.current = false;
@@ -557,7 +595,7 @@ const BridgeProvider = ({
     return () => {
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       clearTimeoutSafe(maxRetryCooldownRef);
-      cleanup();
+      cleanup(false);
     };
   }, [connect, cleanup]);
   const contextValue = useMemo(
@@ -701,14 +739,26 @@ function useBridgeMutation(key, options = {}) {
   return { mutate, data, loading, error, reset };
 }
 
-const useConnectionStatus = () => {
+const useConnectionStatus = (store) => {
   const context = useContext(BridgeContext);
+  const storeReady = useSyncExternalStore(
+    store?.onReady ?? (() => () => {
+    }),
+    store?.isReady ?? (() => true),
+    () => false
+    // Server-side fallback
+  );
+  const bridgeConnected = context?.status === "connected";
+  const isReady = bridgeConnected && storeReady;
+  const isLoading = !isReady && (context?.status === "connecting" || context?.status === "reconnecting" || bridgeConnected && !storeReady);
   return {
     status: context?.status,
-    isConnected: context?.status === "connected",
+    isConnected: bridgeConnected,
     isServiceWorkerAlive: context?.isServiceWorkerAlive ?? false,
     reconnect: context?.reconnect,
-    error: context?.error
+    error: context?.error,
+    isReady,
+    isLoading
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromahq/react",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "React bindings for the Chroma Chrome extension framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",