@chromahq/react 1.0.46 → 1.0.48

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;
@@ -291,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)
@@ -100,8 +100,17 @@ const CONFIG = {
   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
+  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) => {
@@ -318,7 +327,9 @@ function createBridgeInstance(deps) {
         resolve,
         reject,
         timeout,
-        timeoutDuration
+        timeoutDuration,
+        key,
+        payload
       });
       if (!isPortValid()) {
         if (isReconnectingRef.current) {
@@ -452,7 +463,67 @@ function createBridgeInstance(deps) {
         }
         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;
 }
@@ -613,22 +684,32 @@ const BridgeProvider = ({
     }
     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()
-        });
-      });
+      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 }) => {
@@ -667,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) {
@@ -725,6 +813,9 @@ const BridgeProvider = ({
         );
       }
       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);
         }
@@ -750,6 +841,12 @@ const BridgeProvider = ({
           }, retryDelay);
           return;
         }
+        {
+          console.error(
+            `[Bridge] \u274C Queued request failed after ${request.maxRetries} retries: ${request.key}`,
+            error2
+          );
+        }
         if (request.idempotencyKey) {
           activeIdempotencyKeysRef.current.delete(request.idempotencyKey);
         }
@@ -948,11 +1045,145 @@ const BridgeProvider = ({
       swRestartRetryCountRef.current = 0;
       consecutiveTimeoutsRef.current = 0;
       isConnectingRef.current = false;
-      setTimeout(() => {
-        if (isMountedRef.current && isConnectedRef.current) {
-          drainRequestQueue();
+      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...");
         }
-      }, 200);
+        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;
@@ -960,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) {
@@ -1259,7 +1481,7 @@ function broadcastHealthChange(status, isHealthy) {
   });
 }
 const ServiceWorkerHealthContext = createContext(null);
-const HEALTH_GRACE_PERIOD_MS = 3e3;
+const HEALTH_GRACE_PERIOD_MS = 1e3;
 const ServiceWorkerHealthProvider = ({
   children,
   onHealthChange
@@ -1289,7 +1511,7 @@ const ServiceWorkerHealthProvider = ({
         clearTimeout(graceTimeoutRef.current);
         graceTimeoutRef.current = null;
       }
-    } else if (rawStatus !== "healthy" && !unhealthyStartedAt) {
+    } else if (!unhealthyStartedAt) {
       setUnhealthyStartedAt(Date.now());
       graceTimeoutRef.current = setTimeout(() => {
         setGraceExpired(true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromahq/react",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "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"
   }
 }