@chromahq/react 1.0.24 → 1.0.26

package/dist/index.d.ts

@@ -81,14 +81,153 @@ interface ConnectionStatusResult {
     /** Whether the system is loading (bridge connecting/reconnecting OR store not ready) */
     isLoading: boolean;
 }
+/**
+ * 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 to include in readiness check
+ * 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;
 
-export { BridgeProvider, useBridge, useBridgeQuery, useConnectionStatus };
+/**
+ * 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, ServiceWorkerHealthProvider, getHealthStatus, subscribeToHealth, useBridge, useBridgeQuery, useConnectionStatus, useServiceWorkerHealth, useServiceWorkerHealthSimple };
+export type { HealthStatus, ServiceWorkerHealthContextValue };

package/dist/index.js

@@ -5,7 +5,8 @@ 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,
@@ -175,7 +176,8 @@ function startHealthMonitor(deps) {
     consecutivePingFailuresRef,
     pingInterval,
     setIsServiceWorkerAlive,
-    onReconnectNeeded
+    onReconnectNeeded,
+    rejectAllPendingRequests
   } = deps;
   clearIntervalSafe(pingIntervalRef);
   consecutivePingFailuresRef.current = 0;
@@ -202,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);
@@ -269,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);
@@ -286,7 +302,6 @@ const BridgeProvider = ({
       reject(new Error("Bridge disconnected"));
     });
     pendingRequestsRef.current.clear();
-    eventListenersRef.current.clear();
     setIsServiceWorkerAlive(false);
     setBridge(null);
     isConnectingRef.current = false;
@@ -506,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;
@@ -571,7 +595,7 @@ const BridgeProvider = ({
     return () => {
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       clearTimeoutSafe(maxRetryCooldownRef);
-      cleanup();
+      cleanup(false);
     };
   }, [connect, cleanup]);
   const contextValue = useMemo(
@@ -738,4 +762,94 @@ const useConnectionStatus = (store) => {
   };
 };
 
-export { BridgeProvider, useBridge, useBridgeMutation, useBridgeQuery, useConnectionStatus };
+const globalSubscribers = /* @__PURE__ */ new Set();
+function subscribeToHealth(callback) {
+  globalSubscribers.add(callback);
+  return () => {
+    globalSubscribers.delete(callback);
+  };
+}
+let currentHealthStatus = "unknown";
+let currentIsHealthy = false;
+function getHealthStatus() {
+  return { status: currentHealthStatus, isHealthy: currentIsHealthy };
+}
+function broadcastHealthChange(status, isHealthy) {
+  currentHealthStatus = status;
+  currentIsHealthy = isHealthy;
+  globalSubscribers.forEach((callback) => {
+    try {
+      callback(status, isHealthy);
+    } catch (e) {
+      console.error("[ServiceWorkerHealth] Subscriber error:", e);
+    }
+  });
+}
+const ServiceWorkerHealthContext = createContext(null);
+const ServiceWorkerHealthProvider = ({
+  children,
+  onHealthChange
+}) => {
+  const bridgeContext = useContext(BridgeContext);
+  const [lastHealthyAt, setLastHealthyAt] = useState(null);
+  const bridgeStatus = bridgeContext?.status;
+  const isServiceWorkerAlive = bridgeContext?.isServiceWorkerAlive ?? false;
+  const derivedStatus = useMemo(() => {
+    if (!bridgeStatus) return "unknown";
+    if (bridgeStatus === "connected" && isServiceWorkerAlive) {
+      return "healthy";
+    }
+    if (bridgeStatus === "reconnecting" || bridgeStatus === "connecting") {
+      return "recovering";
+    }
+    return "unhealthy";
+  }, [bridgeStatus, isServiceWorkerAlive]);
+  const isHealthy = derivedStatus === "healthy";
+  const isRecovering = derivedStatus === "recovering";
+  const isLoading = derivedStatus === "recovering" || derivedStatus === "unknown";
+  useEffect(() => {
+    if (isHealthy) {
+      setLastHealthyAt(Date.now());
+    }
+  }, [isHealthy]);
+  useEffect(() => {
+    broadcastHealthChange(derivedStatus, isHealthy);
+    onHealthChange?.(derivedStatus, isHealthy);
+  }, [derivedStatus, isHealthy, onHealthChange]);
+  const forceReconnect = useCallback(() => {
+    bridgeContext?.reconnect();
+  }, [bridgeContext]);
+  const value = useMemo(
+    () => ({
+      status: derivedStatus,
+      isHealthy,
+      isRecovering,
+      isLoading,
+      lastHealthyAt,
+      forceReconnect
+    }),
+    [derivedStatus, isHealthy, isRecovering, isLoading, lastHealthyAt, forceReconnect]
+  );
+  return /* @__PURE__ */ jsx(ServiceWorkerHealthContext.Provider, { value, children });
+};
+function useServiceWorkerHealth() {
+  const context = useContext(ServiceWorkerHealthContext);
+  if (!context) {
+    throw new Error(
+      "useServiceWorkerHealth must be used within a ServiceWorkerHealthProvider. Wrap your app with <ServiceWorkerHealthProvider> inside <BridgeProvider>."
+    );
+  }
+  return context;
+}
+function useServiceWorkerHealthSimple() {
+  const bridgeContext = useContext(BridgeContext);
+  const isHealthy = bridgeContext?.status === "connected" && bridgeContext?.isServiceWorkerAlive === true;
+  const isRecovering = bridgeContext?.status === "reconnecting" || bridgeContext?.status === "connecting";
+  const isLoading = !isHealthy && (isRecovering || !bridgeContext);
+  const reconnect = useCallback(() => {
+    bridgeContext?.reconnect();
+  }, [bridgeContext]);
+  return { isHealthy, isRecovering, isLoading, reconnect };
+}
+
+export { BridgeProvider, ServiceWorkerHealthProvider, getHealthStatus, subscribeToHealth, useBridge, useBridgeMutation, useBridgeQuery, useConnectionStatus, useServiceWorkerHealth, useServiceWorkerHealthSimple };

package/package.json

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