cross-tab-worker-databus 0.20.86 → 0.20.87

package/dist/cjs/hooks.cjs

@@ -79,6 +79,7 @@ function useCrossTabStatus(bus) {
 }
 function useCrossTabHealth(bus, options) {
   const [health, setHealth] = (0, import_react.useState)(null);
+  const intervalMs = options?.intervalMs ?? 1e3;
   (0, import_react.useEffect)(() => {
     if (!bus) {
       setHealth(null);
@@ -88,14 +89,13 @@ function useCrossTabHealth(bus, options) {
     refresh();
     const unsubscribeStatus = bus.onStatus(refresh);
     const unsubscribeError = bus.onError(refresh);
-    const intervalMs = options?.intervalMs ?? 1e3;
     const timer = intervalMs > 0 ? setInterval(refresh, intervalMs) : null;
     return () => {
       unsubscribeStatus();
       unsubscribeError();
       if (timer) clearInterval(timer);
     };
-  }, [bus]);
+  }, [bus, intervalMs]);
   return health;
 }
 //# sourceMappingURL=hooks.cjs.map

package/dist/cjs/hooks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks.ts", "../../src/utils/constants.ts"],
-  "sourcesContent": ["/**\n * React hooks adapter for cross-tab-worker-databus.\n *\n * A thin, transport-agnostic bridge between the imperative CrossTabDataBus\n * API and React component lifecycles. React is an optional peer dependency \u2014\n * this module is a separate entry point so consumers who don't use React\n * never load it.\n *\n * - `useCrossTabDataBus` owns the bus lifecycle: created on mount, stopped on\n *   unmount. It is StrictMode-safe: the double-invoked effect exercises the\n *   same stop/recreate path as BFCache suspend/resume.\n * - `useCrossTabSubscription` attaches a message handler with automatic\n *   cleanup; the handler is read through a ref, so you can pass inline\n *   closures without resubscribing on every render.\n * - `useCrossTabStatus` mirrors `bus.onStatus()` into React state.\n * - `useCrossTabHealth` polls `bus.getHealthSummary()` into React state,\n *   with event-driven refreshes on status changes and errors.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\nimport { WORKER_STATUS } from './utils/constants';\n\n/**\n * Create a CrossTabDataBus for the component's lifetime.\n *\n * @param create Factory invoked once per effect run. Return a fresh bus \u2014\n *   do not share a bus instance between effects, or StrictMode's\n *   mount \u2192 stop \u2192 mount cycle will stop the shared instance out from\n *   under the second mount.\n * @param deps Re-create the bus when these change (default: create once).\n * @returns The active bus, or `null` before the first effect has run (SSR\n *   and the initial render).\n */\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: DependencyList = []\n): CrossTabDataBus<TConfig, TData> | null {\n  const [bus, setBus] = useState<CrossTabDataBus<TConfig, TData> | null>(null);\n  const lifecycleGeneration = useRef(0);\n  useEffect(() => {\n    const generation = ++lifecycleGeneration.current;\n    const instance = create();\n    if (generation !== lifecycleGeneration.current) return;\n    setBus(instance);\n    void instance.ready().catch(() => {});\n    return () => {\n      if (generation === lifecycleGeneration.current) setBus(null);\n      void instance.stop();\n    };\n    // The factory is intentionally not a dependency: callers pass an inline\n    // closure and key recreation through `deps` instead.\n  }, deps);\n  return bus;\n}\n\n/**\n * Subscribe to `topic` for the component's lifetime. The handler is read\n * through a ref on each delivery, so inline closures are safe without\n * unsubscribing/resubscribing on re-renders.\n *\n * When `bus` is null (not yet created) the subscription is queued until the\n * bus appears \u2014 the bus itself queues it until the transport is ready.\n */\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  topic: string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    if (!bus) return;\n    return bus.subscribe(topic, message => handlerRef.current(message));\n  }, [bus, topic]);\n}\n\n/**\n * Mirror the bus connection status into React state. Reports the live value\n * via `onStatus` and reads the current value synchronously whenever `bus`\n * changes identity.\n */\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null\n): WorkerStatus {\n  const [status, setStatus] = useState<WorkerStatus>(WORKER_STATUS.CONNECTING);\n  useEffect(() => {\n    if (!bus) {\n      setStatus(WORKER_STATUS.CONNECTING);\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n\n/**\n * Mirror the bus health summary into React state.\n *\n * `getHealthSummary()` is a snapshot, not an event stream, so the hook polls\n * it on an interval (default 1000 ms) and refreshes immediately on status\n * changes and errors. Pass `intervalMs: 0` to rely on event-driven refreshes\n * only. Returns `null` while the bus has not been created yet.\n */\nexport function useCrossTabHealth<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  options?: { intervalMs?: number }\n): DataBusHealthSummary | null {\n  const [health, setHealth] = useState<DataBusHealthSummary | null>(null);\n  useEffect(() => {\n    if (!bus) {\n      setHealth(null);\n      return;\n    }\n    const refresh = () => setHealth(bus.getHealthSummary());\n    refresh();\n    const unsubscribeStatus = bus.onStatus(refresh);\n    const unsubscribeError = bus.onError(refresh);\n    const intervalMs = options?.intervalMs ?? 1_000;\n    const timer = intervalMs > 0 ? setInterval(refresh, intervalMs) : null;\n    return () => {\n      unsubscribeStatus();\n      unsubscribeError();\n      if (timer) clearInterval(timer);\n    };\n    // The options object is intentionally not a dependency: callers pass an\n    // inline literal and the interval only affects polling cadence.\n  }, [bus]);\n  return health;\n}\n", "/**\n * \u516C\u5171\u5B57\u7B26\u4E32\u5E38\u91CF \u2014\u2014 \u751F\u547D\u5468\u671F\u72B6\u6001\u3001\u89D2\u8272\u3001\u63A7\u5236\u52A8\u4F5C\u3001\u534F\u8BAE\u6D88\u606F\u7C7B\u578B\u3001\u679A\u4E3E\u4E0E\n * \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u3002\n *\n * \u6240\u6709\u8FD0\u884C\u65F6\u4F7F\u7528\u7684\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u96C6\u4E2D\u5728\u6B64\u4E00\u4EFD\u503C\uFF0C\u7C7B\u578B\u5B9A\u4E49\uFF08src/core/types.ts\n * \u7B49\uFF09\u901A\u8FC7 `(typeof X)[keyof typeof X]` \u4ECE\u8FD9\u4E9B\u5E38\u91CF\u6D3E\u751F\uFF0C\u6BD4\u8F83/switch \u5904\u5F15\u7528\n * \u540C\u4E00\u5BF9\u8C61\u6210\u5458\u3002\u8FD9\u6837\u65E2\u80FD\u6D88\u9664\u6563\u843D\u5728\u5404\u6587\u4EF6\u91CC\u7684\u91CD\u590D\u5B57\u7B26\u4E32\uFF08\u907F\u514D\u5927\u5C0F\u5199\u4E0D\u7EDF\u4E00\n * \u6216\u7B14\u8BEF\uFF09\uFF0C\u53C8\u4FDD\u8BC1\u7C7B\u578B\u4E0E\u503C\u6C38\u4E0D\u9519\u4F4D\u3002\n *\n * ## \u4F7F\u7528\u7EA6\u5B9A\n *\n * - **\u65B0\u589E\u6216\u4FEE\u6539\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u65F6\uFF0C\u5148\u5230\u8FD9\u91CC\u67E5\u627E/\u589E\u8865\uFF0C\u4E0D\u8981\u5728\u4E1A\u52A1\u6587\u4EF6\u91CC\u76F4\u63A5\u5199\n *   \u9B54\u6CD5\u5B57\u7B26\u4E32\u3002** \u626B\u63CF\u6B8B\u7559\u5B57\u9762\u91CF\uFF1A`rg \"'(['a-z]+)'\" src/`\u3002\n * - **\u53EA\u7528\u4E8E\u7C7B\u578B\u4F4D\u7F6E\u7684\u5E38\u91CF**\uFF08\u5982 `PERSISTENCE_OPERATION`\uFF09\u5728\u8C03\u7528\u65B9\u7528\n *   `import type`\uFF1B**\u5728\u8FD0\u884C\u65F6\u6BD4\u8F83/\u6784\u9020\u4E2D\u4F7F\u7528\u7684**\uFF08\u5982 `WORKER_STATUS.ERROR`\u3001\n *   `TRACE_EVENT_TYPE.LIFECYCLE`\uFF09\u5FC5\u987B\u7528\u503C\u5BFC\u5165\uFF0C\u5426\u5219\u4F1A\u62A5 \"cannot be used as\n *   a value because it was imported using 'import type'\"\u3002\n * - **\u503C\u6D3E\u751F\u7C7B\u578B**\uFF1A`export type WorkerStatus = (typeof WORKER_STATUS)[keyof\n *   typeof WORKER_STATUS]`\u3002\u8FD9\u6837\u65B0\u589E\u679A\u4E3E\u5206\u652F\u65F6\u7C7B\u578B\u81EA\u52A8\u6536\u7A84\uFF0C\u7F16\u8BD1\u5668\u4F1A\u6307\u51FA\n *   \u6BCF\u4E2A\u9057\u6F0F\u7684 switch \u5206\u652F\u3002\n * - \u5206\u7EC4\u7684\u987A\u5E8F\uFF08\u72B6\u6001 / \u89D2\u8272 / \u540E\u7AEF / \u6D88\u606F\u7C7B\u578B / \u679A\u4E3E / \u524D\u7F00\uFF09\u4FDD\u6301\u7A33\u5B9A\uFF0C\u65B9\u4FBF\n *   \u7EF4\u62A4\u8005\u4E00\u773C\u5B9A\u4F4D\u3002\n */\n\n// ---- \u751F\u547D\u5468\u671F\u72B6\u6001 / \u89D2\u8272 / \u53EF\u89C1\u6027 ----\nexport const WORKER_STATUS = {\n  CONNECTING: 'connecting',\n  CONNECTED: 'connected',\n  DISCONNECTED: 'disconnected',\n  ERROR: 'error',\n} as const;\n\nexport const WORKER_ROLE = {\n  ACTIVE: 'active',\n  STANDBY: 'standby',\n} as const;\n\nexport const TAB_VISIBILITY = {\n  VISIBLE: 'visible',\n  HIDDEN: 'hidden',\n} as const;\n\n// ---- Worker \u540E\u7AEF\u6A21\u5F0F\u4E0E\u89E3\u6790\u7ED3\u679C\uFF08WorkerMode / WorkerBackend\uFF09----\nexport const WORKER_MODE = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  AUTO: 'auto',\n} as const;\n\nexport const WORKER_BACKEND = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  LOCAL: 'local',\n} as const;\n\n// ---- \u5B58\u50A8\u4E8B\u4EF6\u901A\u9053\u56DE\u9000 ----\nexport const CHANNEL_FALLBACK = {\n  NONE: 'none',\n  STORAGE_EVENT: 'storage-event',\n} as const;\n\n// ---- Worker / MessagePort / BroadcastChannel \u7684 EventTarget \u4E8B\u4EF6\u540D\u5224\u522B ----\n// MessageEvent.type\uFF08'message' / 'messageerror'\uFF09\u4E0E Worker \u4E0A\u7684 'error' \u4E8B\u4EF6\u540D\uFF0C\n// \u7528\u4E8E\u73AF\u5883\u9002\u914D\u5668\u63A5\u53E3\u7B7E\u540D\u4E0E\u6D4B\u8BD5\u66FF\u8EAB\u7684 addEventListener \u771F\u5047\u5206\u652F\u3002\nexport const EVENT_TYPE = {\n  MESSAGE: 'message',\n  MESSAGEERROR: 'messageerror',\n  ERROR: 'error',\n} as const;\n\n// ---- \u63A7\u5236\u5E73\u9762\u52A8\u4F5C\uFF08WorkerControlAction\uFF09----\nexport const CONTROL_ACTION = {\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n} as const;\n\n// ---- BroadcastChannel \u96C6\u7FA4\u6D88\u606F\u7C7B\u578B ----\nexport const CLUSTER_MESSAGE_TYPE = {\n  CONTROL: 'CONTROL',\n  EVENT: 'EVENT',\n  REGISTRY: 'REGISTRY',\n  ROUTE_RELEASED: 'ROUTE_RELEASED',\n} as const;\n\n// ---- \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u4E0E\u4E8B\u4EF6\u540D ----\nexport const DEFAULT_STORAGE_PREFIX = 'cross-tab-worker-databus';\nexport const STORAGE_CHANNEL_PREFIX = `${DEFAULT_STORAGE_PREFIX}:channel:`;\nexport const TAB_ID_STORAGE_KEY = `${DEFAULT_STORAGE_PREFIX}:tab-id`;\nexport const PUBLICATION_EVENT = 'DATABUS_PUBLICATION';\n\n// ---- \u89C4\u8303 JSON \u4FE1\u5C01\u64CD\u4F5C\u7801 ----\nexport const PUBLICATION_ENVELOPE_OP = 'publication';\n\n// ---- trace \u4E8B\u4EF6\u7C7B\u578B ----\nexport const TRACE_EVENT_TYPE = {\n  LIFECYCLE: 'lifecycle',\n  STATUS: 'status',\n  SUBSCRIPTION: 'subscription',\n  COORDINATION: 'coordination',\n  ERROR: 'error',\n  RELIABILITY: 'reliability',\n  MESSAGE_METRICS: 'message_metrics',\n} as const;\n\n// ---- trace \u751F\u547D\u5468\u671F\u52A8\u4F5C ----\nexport const TRACE_LIFECYCLE_ACTION = {\n  START: 'start',\n  STOP: 'stop',\n  SUSPEND: 'suspend',\n  RESUME: 'resume',\n} as const;\n\n// ---- \u5185\u90E8 handler \u8C03\u7528\u6807\u7B7E\uFF08\u9694\u79BB\u5F02\u5E38\u65F6\u7684\u5206\u7C7B\u6765\u6E90\uFF09----\nexport const INVOKE_LABEL = {\n  DISPATCH: 'dispatch',\n  STATUS: 'status',\n  ERROR_HANDLER: 'error handler',\n} as const;\n\n// ---- trace \u6A21\u5F0F\uFF08DataBusTraceMode\uFF09----\nexport const TRACE_MODE = {\n  EVENTS: 'events',\n  METRICS: 'metrics',\n  ALL: 'all',\n} as const;\n\n// ---- trace \u9519\u8BEF\u6765\u6E90 ----\nexport const TRACE_ERROR_SOURCE = {\n  TRANSPORT: 'transport',\n  OPERATION: 'operation',\n} as const;\n\n// ---- reliability \u8BCA\u65AD\u64CD\u4F5C ----\nexport const RELIABILITY_OPERATION = {\n  TRANSPORT_RECOVERY: 'transport_recovery',\n  ROUTE_ACK: 'route_ack',\n  ROUTE_MIGRATION: 'route_migration',\n  // A re-election that recovered a stranded unconfirmed handoff (previous\n  // owner gone, ACK never arrived). Distinct from ROUTE_MIGRATION so trace\n  // consumers can tell recoveries apart from routine graceful handoffs.\n  ROUTE_MIGRATION_RECOVERY: 'route_migration_recovery',\n  PERSISTENCE_CLEANUP: 'persistence_cleanup',\n  PERSISTENCE_RETRY: 'persistence_retry',\n  DEDUP_SUPPRESSED: 'dedup_suppressed',\n} as const;\n\n// ---- \u81EA\u52A8\u6062\u590D\u5C1D\u8BD5\u7ED3\u679C ----\nexport const RECOVERY_OUTCOME = {\n  SCHEDULED: 'scheduled',\n  SUCCEEDED: 'succeeded',\n  FAILED: 'failed',\n  EXHAUSTED: 'exhausted',\n} as const;\n\n// ---- \u8BA2\u9605\u52A8\u4F5C ----\nexport const SUBSCRIPTION_ACTION = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n} as const;\n\n// ---- \u56DE\u653E\u4FEE\u526A\u7B56\u7565 ----\nexport const PRUNE_STRATEGY = {\n  COUNT: 'count',\n  AGE: 'age',\n  BOTH: 'both',\n} as const;\n\n// ---- \u6301\u4E45\u5316\u64CD\u4F5C ----\nexport const PERSISTENCE_OPERATION = {\n  LOAD: 'load',\n  APPEND: 'append',\n  CLEAR: 'clear',\n  CLEAR_TOPIC: 'clearTopic',\n  CLEAR_BEFORE: 'clearBefore',\n} as const;\n\n// ---- \u6545\u969C\u6765\u6E90\uFF08DataBusFailureSource\uFF09----\nexport const FAILURE_SOURCE = {\n  TRANSPORT: 'transport',\n  PERSISTENCE: 'persistence',\n  DISPATCH: 'dispatch',\n} as const;\n\n// ---- \u5065\u5EB7\u5224\u5B9A\u72B6\u6001\uFF08DataBusHealthSummary['state']\uFF09----\nexport const HEALTH_STATE = {\n  STOPPED: 'stopped',\n  STARTING: 'starting',\n  HEALTHY: 'healthy',\n  RECOVERING: 'recovering',\n  SUSPENDED: 'suspended',\n  DEGRADED: 'degraded',\n} as const;\n\n// ---- WebSocket wire \u534F\u8BAE\u64CD\u4F5C\u7801 ----\nexport const WS_OP = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n  PUBLISH: 'publish',\n  PUBLISH_BATCH: 'publishBatch',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u5165\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_INPUT_TYPE = {\n  INIT: 'INIT',\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n  PUBLISH_BIN: 'PUBLISH_BIN',\n  PING: 'PING',\n  STOP: 'STOP',\n  TOKEN_RESPONSE: 'TOKEN_RESPONSE',\n  TOKEN_ERROR: 'TOKEN_ERROR',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u51FA\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_OUTPUT_TYPE = {\n  STATUS: 'STATUS',\n  MESSAGE: 'MESSAGE',\n  MESSAGE_BIN: 'MESSAGE_BIN',\n  ERROR: 'ERROR',\n  TOKEN_REQUEST: 'TOKEN_REQUEST',\n} as const;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,mBAA4C;;;ACOrC,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,cAAc;AAAA,EACd,OAAO;AACT;AAwDO,IAAM,yBAAyB;AAC/B,IAAM,yBAAyB,GAAG,sBAAsB;AACxD,IAAM,qBAAqB,GAAG,sBAAsB;;;ADrDpD,SAAS,mBACd,QACA,OAAuB,CAAC,GACgB;AACxC,QAAM,CAAC,KAAK,MAAM,QAAI,uBAAiD,IAAI;AAC3E,QAAM,0BAAsB,qBAAO,CAAC;AACpC,8BAAU,MAAM;AACd,UAAM,aAAa,EAAE,oBAAoB;AACzC,UAAM,WAAW,OAAO;AACxB,QAAI,eAAe,oBAAoB,QAAS;AAChD,WAAO,QAAQ;AACf,SAAK,SAAS,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,WAAO,MAAM;AACX,UAAI,eAAe,oBAAoB,QAAS,QAAO,IAAI;AAC3D,WAAK,SAAS,KAAK;AAAA,IACrB;AAAA,EAGF,GAAG,IAAI;AACP,SAAO;AACT;AAUO,SAAS,wBACd,KACA,OACA,SACM;AACN,QAAM,iBAAa,qBAAO,OAAO;AACjC,aAAW,UAAU;AACrB,8BAAU,MAAM;AACd,QAAI,CAAC,IAAK;AACV,WAAO,IAAI,UAAU,OAAO,aAAW,WAAW,QAAQ,OAAO,CAAC;AAAA,EACpE,GAAG,CAAC,KAAK,KAAK,CAAC;AACjB;AAOO,SAAS,kBACd,KACc;AACd,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAuB,cAAc,UAAU;AAC3E,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,cAAc,UAAU;AAClC;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;AAUO,SAAS,kBACd,KACA,SAC6B;AAC7B,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAsC,IAAI;AACtE,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,IAAI;AACd;AAAA,IACF;AACA,UAAM,UAAU,MAAM,UAAU,IAAI,iBAAiB,CAAC;AACtD,YAAQ;AACR,UAAM,oBAAoB,IAAI,SAAS,OAAO;AAC9C,UAAM,mBAAmB,IAAI,QAAQ,OAAO;AAC5C,UAAM,aAAa,SAAS,cAAc;AAC1C,UAAM,QAAQ,aAAa,IAAI,YAAY,SAAS,UAAU,IAAI;AAClE,WAAO,MAAM;AACX,wBAAkB;AAClB,uBAAiB;AACjB,UAAI,MAAO,eAAc,KAAK;AAAA,IAChC;AAAA,EAGF,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;",
+  "sourcesContent": ["/**\n * React hooks adapter for cross-tab-worker-databus.\n *\n * A thin, transport-agnostic bridge between the imperative CrossTabDataBus\n * API and React component lifecycles. React is an optional peer dependency \u2014\n * this module is a separate entry point so consumers who don't use React\n * never load it.\n *\n * - `useCrossTabDataBus` owns the bus lifecycle: created on mount, stopped on\n *   unmount. It is StrictMode-safe: the double-invoked effect exercises the\n *   same stop/recreate path as BFCache suspend/resume.\n * - `useCrossTabSubscription` attaches a message handler with automatic\n *   cleanup; the handler is read through a ref, so you can pass inline\n *   closures without resubscribing on every render.\n * - `useCrossTabStatus` mirrors `bus.onStatus()` into React state.\n * - `useCrossTabHealth` polls `bus.getHealthSummary()` into React state,\n *   with event-driven refreshes on status changes and errors.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\nimport { WORKER_STATUS } from './utils/constants';\n\n/**\n * Create a CrossTabDataBus for the component's lifetime.\n *\n * @param create Factory invoked once per effect run. Return a fresh bus \u2014\n *   do not share a bus instance between effects, or StrictMode's\n *   mount \u2192 stop \u2192 mount cycle will stop the shared instance out from\n *   under the second mount.\n * @param deps Re-create the bus when these change (default: create once).\n * @returns The active bus, or `null` before the first effect has run (SSR\n *   and the initial render).\n */\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: DependencyList = []\n): CrossTabDataBus<TConfig, TData> | null {\n  const [bus, setBus] = useState<CrossTabDataBus<TConfig, TData> | null>(null);\n  const lifecycleGeneration = useRef(0);\n  useEffect(() => {\n    const generation = ++lifecycleGeneration.current;\n    const instance = create();\n    if (generation !== lifecycleGeneration.current) return;\n    setBus(instance);\n    void instance.ready().catch(() => {});\n    return () => {\n      if (generation === lifecycleGeneration.current) setBus(null);\n      void instance.stop();\n    };\n    // The factory is intentionally not a dependency: callers pass an inline\n    // closure and key recreation through `deps` instead.\n  }, deps);\n  return bus;\n}\n\n/**\n * Subscribe to `topic` for the component's lifetime. The handler is read\n * through a ref on each delivery, so inline closures are safe without\n * unsubscribing/resubscribing on re-renders.\n *\n * When `bus` is null (not yet created) the subscription is queued until the\n * bus appears \u2014 the bus itself queues it until the transport is ready.\n */\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  topic: string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    if (!bus) return;\n    return bus.subscribe(topic, message => handlerRef.current(message));\n  }, [bus, topic]);\n}\n\n/**\n * Mirror the bus connection status into React state. Reports the live value\n * via `onStatus` and reads the current value synchronously whenever `bus`\n * changes identity.\n */\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null\n): WorkerStatus {\n  const [status, setStatus] = useState<WorkerStatus>(WORKER_STATUS.CONNECTING);\n  useEffect(() => {\n    if (!bus) {\n      setStatus(WORKER_STATUS.CONNECTING);\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n\n/**\n * Mirror the bus health summary into React state.\n *\n * `getHealthSummary()` is a snapshot, not an event stream, so the hook polls\n * it on an interval (default 1000 ms) and refreshes immediately on status\n * changes and errors. Pass `intervalMs: 0` to rely on event-driven refreshes\n * only; changing the interval replaces the timer without recreating the bus.\n * Returns `null` while the bus has not been created yet.\n */\nexport function useCrossTabHealth<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  options?: { intervalMs?: number }\n): DataBusHealthSummary | null {\n  const [health, setHealth] = useState<DataBusHealthSummary | null>(null);\n  const intervalMs = options?.intervalMs ?? 1_000;\n  useEffect(() => {\n    if (!bus) {\n      setHealth(null);\n      return;\n    }\n    const refresh = () => setHealth(bus.getHealthSummary());\n    refresh();\n    const unsubscribeStatus = bus.onStatus(refresh);\n    const unsubscribeError = bus.onError(refresh);\n    const timer = intervalMs > 0 ? setInterval(refresh, intervalMs) : null;\n    return () => {\n      unsubscribeStatus();\n      unsubscribeError();\n      if (timer) clearInterval(timer);\n    };\n    // Depend on the normalized cadence rather than the options object so inline\n    // option literals do not restart the effect on every render, while a real\n    // intervalMs change still replaces the polling timer.\n  }, [bus, intervalMs]);\n  return health;\n}\n", "/**\n * \u516C\u5171\u5B57\u7B26\u4E32\u5E38\u91CF \u2014\u2014 \u751F\u547D\u5468\u671F\u72B6\u6001\u3001\u89D2\u8272\u3001\u63A7\u5236\u52A8\u4F5C\u3001\u534F\u8BAE\u6D88\u606F\u7C7B\u578B\u3001\u679A\u4E3E\u4E0E\n * \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u3002\n *\n * \u6240\u6709\u8FD0\u884C\u65F6\u4F7F\u7528\u7684\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u96C6\u4E2D\u5728\u6B64\u4E00\u4EFD\u503C\uFF0C\u7C7B\u578B\u5B9A\u4E49\uFF08src/core/types.ts\n * \u7B49\uFF09\u901A\u8FC7 `(typeof X)[keyof typeof X]` \u4ECE\u8FD9\u4E9B\u5E38\u91CF\u6D3E\u751F\uFF0C\u6BD4\u8F83/switch \u5904\u5F15\u7528\n * \u540C\u4E00\u5BF9\u8C61\u6210\u5458\u3002\u8FD9\u6837\u65E2\u80FD\u6D88\u9664\u6563\u843D\u5728\u5404\u6587\u4EF6\u91CC\u7684\u91CD\u590D\u5B57\u7B26\u4E32\uFF08\u907F\u514D\u5927\u5C0F\u5199\u4E0D\u7EDF\u4E00\n * \u6216\u7B14\u8BEF\uFF09\uFF0C\u53C8\u4FDD\u8BC1\u7C7B\u578B\u4E0E\u503C\u6C38\u4E0D\u9519\u4F4D\u3002\n *\n * ## \u4F7F\u7528\u7EA6\u5B9A\n *\n * - **\u65B0\u589E\u6216\u4FEE\u6539\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u65F6\uFF0C\u5148\u5230\u8FD9\u91CC\u67E5\u627E/\u589E\u8865\uFF0C\u4E0D\u8981\u5728\u4E1A\u52A1\u6587\u4EF6\u91CC\u76F4\u63A5\u5199\n *   \u9B54\u6CD5\u5B57\u7B26\u4E32\u3002** \u626B\u63CF\u6B8B\u7559\u5B57\u9762\u91CF\uFF1A`rg \"'(['a-z]+)'\" src/`\u3002\n * - **\u53EA\u7528\u4E8E\u7C7B\u578B\u4F4D\u7F6E\u7684\u5E38\u91CF**\uFF08\u5982 `PERSISTENCE_OPERATION`\uFF09\u5728\u8C03\u7528\u65B9\u7528\n *   `import type`\uFF1B**\u5728\u8FD0\u884C\u65F6\u6BD4\u8F83/\u6784\u9020\u4E2D\u4F7F\u7528\u7684**\uFF08\u5982 `WORKER_STATUS.ERROR`\u3001\n *   `TRACE_EVENT_TYPE.LIFECYCLE`\uFF09\u5FC5\u987B\u7528\u503C\u5BFC\u5165\uFF0C\u5426\u5219\u4F1A\u62A5 \"cannot be used as\n *   a value because it was imported using 'import type'\"\u3002\n * - **\u503C\u6D3E\u751F\u7C7B\u578B**\uFF1A`export type WorkerStatus = (typeof WORKER_STATUS)[keyof\n *   typeof WORKER_STATUS]`\u3002\u8FD9\u6837\u65B0\u589E\u679A\u4E3E\u5206\u652F\u65F6\u7C7B\u578B\u81EA\u52A8\u6536\u7A84\uFF0C\u7F16\u8BD1\u5668\u4F1A\u6307\u51FA\n *   \u6BCF\u4E2A\u9057\u6F0F\u7684 switch \u5206\u652F\u3002\n * - \u5206\u7EC4\u7684\u987A\u5E8F\uFF08\u72B6\u6001 / \u89D2\u8272 / \u540E\u7AEF / \u6D88\u606F\u7C7B\u578B / \u679A\u4E3E / \u524D\u7F00\uFF09\u4FDD\u6301\u7A33\u5B9A\uFF0C\u65B9\u4FBF\n *   \u7EF4\u62A4\u8005\u4E00\u773C\u5B9A\u4F4D\u3002\n */\n\n// ---- \u751F\u547D\u5468\u671F\u72B6\u6001 / \u89D2\u8272 / \u53EF\u89C1\u6027 ----\nexport const WORKER_STATUS = {\n  CONNECTING: 'connecting',\n  CONNECTED: 'connected',\n  DISCONNECTED: 'disconnected',\n  ERROR: 'error',\n} as const;\n\nexport const WORKER_ROLE = {\n  ACTIVE: 'active',\n  STANDBY: 'standby',\n} as const;\n\nexport const TAB_VISIBILITY = {\n  VISIBLE: 'visible',\n  HIDDEN: 'hidden',\n} as const;\n\n// ---- Worker \u540E\u7AEF\u6A21\u5F0F\u4E0E\u89E3\u6790\u7ED3\u679C\uFF08WorkerMode / WorkerBackend\uFF09----\nexport const WORKER_MODE = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  AUTO: 'auto',\n} as const;\n\nexport const WORKER_BACKEND = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  LOCAL: 'local',\n} as const;\n\n// ---- \u5B58\u50A8\u4E8B\u4EF6\u901A\u9053\u56DE\u9000 ----\nexport const CHANNEL_FALLBACK = {\n  NONE: 'none',\n  STORAGE_EVENT: 'storage-event',\n} as const;\n\n// ---- Worker / MessagePort / BroadcastChannel \u7684 EventTarget \u4E8B\u4EF6\u540D\u5224\u522B ----\n// MessageEvent.type\uFF08'message' / 'messageerror'\uFF09\u4E0E Worker \u4E0A\u7684 'error' \u4E8B\u4EF6\u540D\uFF0C\n// \u7528\u4E8E\u73AF\u5883\u9002\u914D\u5668\u63A5\u53E3\u7B7E\u540D\u4E0E\u6D4B\u8BD5\u66FF\u8EAB\u7684 addEventListener \u771F\u5047\u5206\u652F\u3002\nexport const EVENT_TYPE = {\n  MESSAGE: 'message',\n  MESSAGEERROR: 'messageerror',\n  ERROR: 'error',\n} as const;\n\n// ---- \u63A7\u5236\u5E73\u9762\u52A8\u4F5C\uFF08WorkerControlAction\uFF09----\nexport const CONTROL_ACTION = {\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n} as const;\n\n// ---- BroadcastChannel \u96C6\u7FA4\u6D88\u606F\u7C7B\u578B ----\nexport const CLUSTER_MESSAGE_TYPE = {\n  CONTROL: 'CONTROL',\n  EVENT: 'EVENT',\n  REGISTRY: 'REGISTRY',\n  ROUTE_RELEASED: 'ROUTE_RELEASED',\n} as const;\n\n// ---- \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u4E0E\u4E8B\u4EF6\u540D ----\nexport const DEFAULT_STORAGE_PREFIX = 'cross-tab-worker-databus';\nexport const STORAGE_CHANNEL_PREFIX = `${DEFAULT_STORAGE_PREFIX}:channel:`;\nexport const TAB_ID_STORAGE_KEY = `${DEFAULT_STORAGE_PREFIX}:tab-id`;\nexport const PUBLICATION_EVENT = 'DATABUS_PUBLICATION';\n\n// ---- \u89C4\u8303 JSON \u4FE1\u5C01\u64CD\u4F5C\u7801 ----\nexport const PUBLICATION_ENVELOPE_OP = 'publication';\n\n// ---- trace \u4E8B\u4EF6\u7C7B\u578B ----\nexport const TRACE_EVENT_TYPE = {\n  LIFECYCLE: 'lifecycle',\n  STATUS: 'status',\n  SUBSCRIPTION: 'subscription',\n  COORDINATION: 'coordination',\n  ERROR: 'error',\n  RELIABILITY: 'reliability',\n  MESSAGE_METRICS: 'message_metrics',\n} as const;\n\n// ---- trace \u751F\u547D\u5468\u671F\u52A8\u4F5C ----\nexport const TRACE_LIFECYCLE_ACTION = {\n  START: 'start',\n  STOP: 'stop',\n  SUSPEND: 'suspend',\n  RESUME: 'resume',\n} as const;\n\n// ---- \u5185\u90E8 handler \u8C03\u7528\u6807\u7B7E\uFF08\u9694\u79BB\u5F02\u5E38\u65F6\u7684\u5206\u7C7B\u6765\u6E90\uFF09----\nexport const INVOKE_LABEL = {\n  DISPATCH: 'dispatch',\n  STATUS: 'status',\n  ERROR_HANDLER: 'error handler',\n} as const;\n\n// ---- trace \u6A21\u5F0F\uFF08DataBusTraceMode\uFF09----\nexport const TRACE_MODE = {\n  EVENTS: 'events',\n  METRICS: 'metrics',\n  ALL: 'all',\n} as const;\n\n// ---- trace \u9519\u8BEF\u6765\u6E90 ----\nexport const TRACE_ERROR_SOURCE = {\n  TRANSPORT: 'transport',\n  OPERATION: 'operation',\n} as const;\n\n// ---- reliability \u8BCA\u65AD\u64CD\u4F5C ----\nexport const RELIABILITY_OPERATION = {\n  TRANSPORT_RECOVERY: 'transport_recovery',\n  ROUTE_ACK: 'route_ack',\n  ROUTE_MIGRATION: 'route_migration',\n  // A re-election that recovered a stranded unconfirmed handoff (previous\n  // owner gone, ACK never arrived). Distinct from ROUTE_MIGRATION so trace\n  // consumers can tell recoveries apart from routine graceful handoffs.\n  ROUTE_MIGRATION_RECOVERY: 'route_migration_recovery',\n  PERSISTENCE_CLEANUP: 'persistence_cleanup',\n  PERSISTENCE_RETRY: 'persistence_retry',\n  DEDUP_SUPPRESSED: 'dedup_suppressed',\n} as const;\n\n// ---- \u81EA\u52A8\u6062\u590D\u5C1D\u8BD5\u7ED3\u679C ----\nexport const RECOVERY_OUTCOME = {\n  SCHEDULED: 'scheduled',\n  SUCCEEDED: 'succeeded',\n  FAILED: 'failed',\n  EXHAUSTED: 'exhausted',\n} as const;\n\n// ---- \u8BA2\u9605\u52A8\u4F5C ----\nexport const SUBSCRIPTION_ACTION = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n} as const;\n\n// ---- \u56DE\u653E\u4FEE\u526A\u7B56\u7565 ----\nexport const PRUNE_STRATEGY = {\n  COUNT: 'count',\n  AGE: 'age',\n  BOTH: 'both',\n} as const;\n\n// ---- \u6301\u4E45\u5316\u64CD\u4F5C ----\nexport const PERSISTENCE_OPERATION = {\n  LOAD: 'load',\n  APPEND: 'append',\n  CLEAR: 'clear',\n  CLEAR_TOPIC: 'clearTopic',\n  CLEAR_BEFORE: 'clearBefore',\n} as const;\n\n// ---- \u6545\u969C\u6765\u6E90\uFF08DataBusFailureSource\uFF09----\nexport const FAILURE_SOURCE = {\n  TRANSPORT: 'transport',\n  PERSISTENCE: 'persistence',\n  DISPATCH: 'dispatch',\n} as const;\n\n// ---- \u5065\u5EB7\u5224\u5B9A\u72B6\u6001\uFF08DataBusHealthSummary['state']\uFF09----\nexport const HEALTH_STATE = {\n  STOPPED: 'stopped',\n  STARTING: 'starting',\n  HEALTHY: 'healthy',\n  RECOVERING: 'recovering',\n  SUSPENDED: 'suspended',\n  DEGRADED: 'degraded',\n} as const;\n\n// ---- WebSocket wire \u534F\u8BAE\u64CD\u4F5C\u7801 ----\nexport const WS_OP = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n  PUBLISH: 'publish',\n  PUBLISH_BATCH: 'publishBatch',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u5165\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_INPUT_TYPE = {\n  INIT: 'INIT',\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n  PUBLISH_BIN: 'PUBLISH_BIN',\n  PING: 'PING',\n  STOP: 'STOP',\n  TOKEN_RESPONSE: 'TOKEN_RESPONSE',\n  TOKEN_ERROR: 'TOKEN_ERROR',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u51FA\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_OUTPUT_TYPE = {\n  STATUS: 'STATUS',\n  MESSAGE: 'MESSAGE',\n  MESSAGE_BIN: 'MESSAGE_BIN',\n  ERROR: 'ERROR',\n  TOKEN_REQUEST: 'TOKEN_REQUEST',\n} as const;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,mBAA4C;;;ACOrC,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,cAAc;AAAA,EACd,OAAO;AACT;AAwDO,IAAM,yBAAyB;AAC/B,IAAM,yBAAyB,GAAG,sBAAsB;AACxD,IAAM,qBAAqB,GAAG,sBAAsB;;;ADrDpD,SAAS,mBACd,QACA,OAAuB,CAAC,GACgB;AACxC,QAAM,CAAC,KAAK,MAAM,QAAI,uBAAiD,IAAI;AAC3E,QAAM,0BAAsB,qBAAO,CAAC;AACpC,8BAAU,MAAM;AACd,UAAM,aAAa,EAAE,oBAAoB;AACzC,UAAM,WAAW,OAAO;AACxB,QAAI,eAAe,oBAAoB,QAAS;AAChD,WAAO,QAAQ;AACf,SAAK,SAAS,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,WAAO,MAAM;AACX,UAAI,eAAe,oBAAoB,QAAS,QAAO,IAAI;AAC3D,WAAK,SAAS,KAAK;AAAA,IACrB;AAAA,EAGF,GAAG,IAAI;AACP,SAAO;AACT;AAUO,SAAS,wBACd,KACA,OACA,SACM;AACN,QAAM,iBAAa,qBAAO,OAAO;AACjC,aAAW,UAAU;AACrB,8BAAU,MAAM;AACd,QAAI,CAAC,IAAK;AACV,WAAO,IAAI,UAAU,OAAO,aAAW,WAAW,QAAQ,OAAO,CAAC;AAAA,EACpE,GAAG,CAAC,KAAK,KAAK,CAAC;AACjB;AAOO,SAAS,kBACd,KACc;AACd,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAuB,cAAc,UAAU;AAC3E,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,cAAc,UAAU;AAClC;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;AAWO,SAAS,kBACd,KACA,SAC6B;AAC7B,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAsC,IAAI;AACtE,QAAM,aAAa,SAAS,cAAc;AAC1C,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,IAAI;AACd;AAAA,IACF;AACA,UAAM,UAAU,MAAM,UAAU,IAAI,iBAAiB,CAAC;AACtD,YAAQ;AACR,UAAM,oBAAoB,IAAI,SAAS,OAAO;AAC9C,UAAM,mBAAmB,IAAI,QAAQ,OAAO;AAC5C,UAAM,QAAQ,aAAa,IAAI,YAAY,SAAS,UAAU,IAAI;AAClE,WAAO,MAAM;AACX,wBAAkB;AAClB,uBAAiB;AACjB,UAAI,MAAO,eAAc,KAAK;AAAA,IAChC;AAAA,EAIF,GAAG,CAAC,KAAK,UAAU,CAAC;AACpB,SAAO;AACT;",
   "names": []
 }

package/dist/cjs/index.cjs

@@ -2329,7 +2329,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.20.86" : "";
+var SDK_VERSION = true ? "0.20.87" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2354,6 +2354,11 @@ var CrossTabDataBus = class {
   started = false;
   stopping = false;
   transportReady = false;
+  // Whether the installed transport has reported `connected` at least once
+  // since the current open began. A clean `disconnected` after this point is
+  // a lost working connection, not the pre-connect window of a worker-style
+  // backend whose start() resolves before it reports the connection.
+  transportHasConnected = false;
   // Last transport failure, retained so ready() can surface it to callers who
   // never awaited start() directly. Cleared on the next successful start.
   lastError = null;
@@ -2392,6 +2397,19 @@ var CrossTabDataBus = class {
   // a transport reopen succeeds so traces can correlate repeated failures.
   recoveryAttempt = 0;
   recoveryExhausted = false;
+  // Gate that holds transport operations issued after a runtime `error` until
+  // the scheduled recovery attempt has actually run. Without it, a dead
+  // transport still has `transportReady === true` during the cooldown, so
+  // publishes/subscribes would be written to the failed connection and lost.
+  recoveryGate = null;
+  recoveryGateRelease = null;
+  recoveryTimer = null;
+  recoveryTimerToken = 0;
+  // Once an automatic attempt fails, an explicit transport operation may
+  // recover immediately instead of waiting for the next paced attempt. The
+  // gate still stays closed so the operation cannot reach the failed
+  // transport; it is released by the successful on-demand reopen.
+  recoveryDemandAllowed = false;
   /** Monotonic generation incremented on every successful transport open.
    * Stays in lockstep with `lastSuccessAt` so callers can detect that the
    * transport has been reopened even if the timestamp window is short. */
@@ -2610,8 +2628,38 @@ var CrossTabDataBus = class {
     this.queuedStart = queued;
     return queued;
   }
+  /** Release every operation waiting on the scheduled recovery attempt. */
+  releaseRecoveryGate() {
+    const release = this.recoveryGateRelease;
+    this.recoveryGate = null;
+    this.recoveryGateRelease = null;
+    this.recoveryDemandAllowed = false;
+    release?.();
+  }
+  /** Cancel a pending automatic retry when an explicit lifecycle transition
+   * supersedes it. The released gate re-enters runTransport(), which then
+   * follows the newest start/stop/suspend intent. */
+  cancelScheduledRecovery() {
+    this.recoveryTimerToken += 1;
+    if (this.recoveryTimer !== null) {
+      clearTimeout(this.recoveryTimer);
+      this.recoveryTimer = null;
+    }
+    this.releaseRecoveryGate();
+  }
+  /** Keep the recovery gate closed after a failed attempt while allowing the
+   * next explicit transport operation to start an immediate on-demand reopen.
+   * If no gate/successor retry remains, release any waiters. */
+  allowDemandRecovery() {
+    if (this.recoveryGate !== null && this.started && !this.stopping && !this.suspended && this.status === WORKER_STATUS.ERROR) {
+      this.recoveryDemandAllowed = true;
+      return;
+    }
+    this.releaseRecoveryGate();
+  }
   /** Reset failure and recovery diagnostics for a new explicit start session. */
   resetFailureState() {
+    this.cancelScheduledRecovery();
     this.lastError = null;
     this.lastErrorAt = null;
     this.lastFailure = null;
@@ -2634,6 +2682,7 @@ var CrossTabDataBus = class {
     return before.catch(() => void 0).then(() => {
       if (!isCurrentLifecycle() || this.stopping || this.suspended) return;
       if (this.pendingStop === chainedPendingStop) this.pendingStop = null;
+      this.transportHasConnected = false;
       return Promise.resolve(
         this.transport.start(config, {
           onMessage: (message) => {
@@ -2655,6 +2704,7 @@ var CrossTabDataBus = class {
           this.recoveryGeneration += 1;
           this.lastSuccessAt = this.now();
           this.transportReady = true;
+          this.releaseRecoveryGate();
         }
       });
     }).catch((error) => {
@@ -2663,11 +2713,9 @@ var CrossTabDataBus = class {
       if (!this.pendingStop) {
         this.pendingStop = this.createStopPromise();
       }
+      this.transportReady = false;
       this.updateStatus(WORKER_STATUS.ERROR);
       this.reportError(error);
-      this.lastError = error;
-      this.lastErrorAt = this.now();
-      this.transportReady = false;
       if (stopClusterOnFailure) {
         this.stopping = true;
         this.cluster.stop();
@@ -2681,7 +2729,10 @@ var CrossTabDataBus = class {
    * Returns a rejected promise when the transport has failed and no start is in
    * flight — the caller can retry by calling start() or ready() again. While an
    * explicit stop() is settling, this rejects unless a restart is queued behind
-   * it; false readiness during teardown is never reported.
+   * it; false readiness during teardown is never reported. While the tab is
+   * BFCache-suspended (pagehide without a following pageshow), this also
+   * rejects: the suspended start promise is the transport-stop gate, not a
+   * readiness signal.
    */
   ready() {
     if (this.queuedStart) return this.getQueuedStartReady();
@@ -2690,6 +2741,11 @@ var CrossTabDataBus = class {
         "CrossTabDataBus is stopping; ready() cannot report readiness until stop() resolves. Wait for stop() to resolve, then call start() before awaiting ready()."
       ));
     }
+    if (this.suspended) {
+      return Promise.reject(new Error(
+        "CrossTabDataBus is suspended; ready() cannot report readiness until pageshow resumes the transport."
+      ));
+    }
     if (!this.started && !this.hasInitialConfig && this.lastError !== null) {
       return Promise.reject(this.lastError);
     }
@@ -2825,11 +2881,15 @@ var CrossTabDataBus = class {
   getStatus() {
     return this.status;
   }
-  /** Return the current automatic transport recovery state. `hasError` means a transport error is currently retained. */
   /** Return the current automatic transport recovery state plus diagnostics.
-   * `generation` increments on every successful transport open (initial start
-   * and every recovery); `lastSuccessAt` is the timestamp of the most recent
-   * successful open, or `null` until the transport reaches `ready`. */
+   * `hasError`/`errorMessage`/`errorAt` describe the most recent retained
+   * *transport* failure — from a transport open or a runtime `onError`. They
+   * share the lifetime of the unified `lastFailure` ledger: a successful
+   * recovery keeps the last failure visible, and only an explicit `start()`
+   * clears it. `generation` increments on every successful transport open
+   * (initial start and every recovery); `lastSuccessAt` is the timestamp of
+   * the most recent successful open, or `null` until the transport reaches
+   * `ready`. */
   getRecoveryStats() {
     const errorMessage = this.lastError instanceof Error ? this.lastError.message : this.lastError === null ? null : String(this.lastError);
     return {
@@ -2856,7 +2916,7 @@ var CrossTabDataBus = class {
    * unified failure ledger and recovery context that explains the verdict. */
   getHealthSummary() {
     const transport = this.transport;
-    const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
+    const transportDown = this.status !== WORKER_STATUS.CONNECTED;
     const state = !this.started ? HEALTH_STATE.STOPPED : this.suspended ? HEALTH_STATE.SUSPENDED : transportDown ? this.recoveryExhausted ? HEALTH_STATE.DEGRADED : this.status === WORKER_STATUS.CONNECTING && this.recoveryAttempt === 0 ? HEALTH_STATE.STARTING : HEALTH_STATE.RECOVERING : HEALTH_STATE.HEALTHY;
     return {
       healthy: state === HEALTH_STATE.HEALTHY,
@@ -2947,6 +3007,7 @@ var CrossTabDataBus = class {
   async performStop() {
     this.lifecycleEpoch += 1;
     this.stopping = true;
+    this.cancelScheduledRecovery();
     this.replayManager.suspend();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.STOP });
     this.trace.stop();
@@ -2959,6 +3020,8 @@ var CrossTabDataBus = class {
       const pendingStop = this.pendingStop;
       if (pendingStop) await pendingStop.catch(() => void 0);
       else await this.transport.stop();
+    } catch (error) {
+      this.reportError(error);
     } finally {
       this.transportSubscribedTopics.clear();
       this.resetDedup();
@@ -3024,10 +3087,12 @@ var CrossTabDataBus = class {
   updateStatus(status) {
     const previousStatus = this.status;
     this.status = status;
+    if (status === WORKER_STATUS.CONNECTED) this.transportHasConnected = true;
     if (previousStatus !== status) this.trace.event({ type: TRACE_EVENT_TYPE.STATUS, status });
     this.cluster.setStatus(status);
     if (status === WORKER_STATUS.DISCONNECTED || status === WORKER_STATUS.ERROR) this.transportSubscribedTopics.clear();
     if (status === WORKER_STATUS.CONNECTED && previousStatus !== WORKER_STATUS.CONNECTED) {
+      if (this.transportReady) this.releaseRecoveryGate();
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
     if (status === WORKER_STATUS.ERROR && this.started && !this.stopping) {
@@ -3040,23 +3105,49 @@ var CrossTabDataBus = class {
             this.recoveryExhausted = true;
             this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt: this.recoveryMaxAttempts, outcome: RECOVERY_OUTCOME.EXHAUSTED });
           }
+          this.releaseRecoveryGate();
           return;
         }
         this.trace.event({ type: TRACE_EVENT_TYPE.RELIABILITY, operation: RELIABILITY_OPERATION.TRANSPORT_RECOVERY, attempt, outcome: RECOVERY_OUTCOME.SCHEDULED });
-        setTimeout(() => {
-          if (this.stopping || !this.started || this.suspended) return;
-          if (this.status !== WORKER_STATUS.ERROR) return;
-          void this.reopenTransport(attempt);
+        if (this.recoveryGate === null) {
+          let release;
+          this.recoveryGate = new Promise((resolve) => {
+            release = resolve;
+          });
+          this.recoveryGateRelease = release;
+        }
+        this.recoveryDemandAllowed = false;
+        const timerToken = ++this.recoveryTimerToken;
+        this.recoveryTimer = setTimeout(() => {
+          if (timerToken !== this.recoveryTimerToken) return;
+          this.recoveryTimer = null;
+          if (this.stopping || !this.started || this.suspended || this.status !== WORKER_STATUS.ERROR) {
+            this.releaseRecoveryGate();
+            return;
+          }
+          this.recoveryDemandAllowed = false;
+          const opening = this.reopenTransport(attempt);
+          void opening.then(
+            () => this.releaseRecoveryGate(),
+            () => this.allowDemandRecovery()
+          );
         }, this.recoveryCooldownMs);
       }
+    } else if (status === WORKER_STATUS.ERROR) {
+      this.releaseRecoveryGate();
     }
     this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
   }
   reportError(error, source = FAILURE_SOURCE.TRANSPORT) {
+    const at = this.now();
+    if (source === FAILURE_SOURCE.TRANSPORT) {
+      this.lastError = error;
+      this.lastErrorAt = at;
+    }
     this.lastFailure = {
       source,
       message: error instanceof Error ? error.message : String(error),
-      at: this.now()
+      at
     };
     if (source === FAILURE_SOURCE.PERSISTENCE) {
       this.persistenceFailureCount += 1;
@@ -3139,6 +3230,7 @@ var CrossTabDataBus = class {
     if (this.stopping) return;
     this.lifecycleEpoch += 1;
     this.suspended = true;
+    this.cancelScheduledRecovery();
     this.transportReady = false;
     this.transportSubscribedTopics.clear();
     this.updateStatus(WORKER_STATUS.DISCONNECTED);
@@ -3208,7 +3300,24 @@ var CrossTabDataBus = class {
    */
   runTransport(operation) {
     if (this.suspended) return;
-    if (this.transportReady && !this.stopping) {
+    if (this.recoveryGate && !this.stopping) {
+      if (this.recoveryDemandAllowed && this.status === WORKER_STATUS.ERROR && !this.suspended) {
+        this.recoveryDemandAllowed = false;
+        const opening = this.reopenTransport();
+        void opening.then(
+          () => this.releaseRecoveryGate(),
+          () => this.allowDemandRecovery()
+        );
+      }
+      const gate = this.recoveryGate;
+      void gate.then(() => {
+        if (this.stopping || this.suspended) return;
+        this.runTransport(operation);
+      });
+      return;
+    }
+    const droppedAfterConnect = this.transportHasConnected && this.status === WORKER_STATUS.DISCONNECTED;
+    if (this.transportReady && this.status !== WORKER_STATUS.ERROR && !droppedAfterConnect && !this.stopping) {
       try {
         void Promise.resolve(operation()).catch((error) => this.reportError(error));
       } catch (error) {
@@ -3562,6 +3671,7 @@ function parseDataBusPublication(value, fallbackTopic) {
 }
 
 // src/websocket.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 var WS_OPEN = 1;
 var WebSocketTransport = class {
   constructor(connection) {
@@ -3571,12 +3681,27 @@ var WebSocketTransport = class {
   diagnosticsName = "websocket";
   diagnosticsBackend = "native-websocket";
   socket = null;
+  socketActive = false;
   handlers = null;
   subscribedTopics = /* @__PURE__ */ new Set();
-  /** Open the WebSocket and wire lifecycle listeners. A factory failure is
-   * reported through `onStatus('error')` so the DataBus can recover. */
+  // Handshake gate for the current start(). Resolves once the socket opens,
+  // rejects when the attempt fails, so the DataBus start Promise — and every
+  // operation parked behind it — settles at the real connection boundary.
+  connectPromise = null;
+  connectResolve = null;
+  connectReject = null;
+  connectTimer = null;
+  /** Open the WebSocket and wire lifecycle listeners. Resolves once the
+   * handshake completes and rejects when the attempt fails, matching the
+   * `DataBusTransport.start` contract ("resolves on connect or rejects on
+   * failure"). A factory failure is reported through `onStatus('error')` so
+   * the DataBus can recover. */
   start(config, handlers) {
-    if (this.socket) return;
+    if (this.socket && this.socketActive) {
+      return this.connectPromise ?? void 0;
+    }
+    this.socket = null;
+    this.socketActive = false;
     this.handlers = handlers;
     const factory = config.webSocketFactory ?? this.connection.webSocketFactory ?? defaultWebSocketFactory;
     const protocols = config.protocols ?? this.connection.protocols;
@@ -3588,23 +3713,66 @@ var WebSocketTransport = class {
       handlers.onError(error);
       return;
     }
-    socket.onopen = () => {
-      if (this.socket !== socket || this.handlers !== handlers) return;
-      for (const topic of this.subscribedTopics) {
-        this.sendFrame({ op: WS_OP.SUBSCRIBE, topic });
+    const opening = new Promise((resolve, reject) => {
+      this.connectResolve = resolve;
+      this.connectReject = reject;
+      let handshakeCompleted = false;
+      let handshakeFailed = false;
+      const timeoutMs = config.connectTimeoutMs ?? this.connection.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+      if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        this.connectTimer = setTimeout(() => {
+          if (this.socket !== socket || this.handlers !== handlers || handshakeCompleted) return;
+          handshakeFailed = true;
+          this.connectTimer = null;
+          this.socketActive = false;
+          const error = new Error(`WebSocket did not open within ${timeoutMs}ms.`);
+          handlers.onStatus(WORKER_STATUS.ERROR);
+          handlers.onError(error);
+          this.failConnect(error);
+          socket.close();
+        }, timeoutMs);
       }
-      handlers.onStatus(WORKER_STATUS.CONNECTED);
-    };
-    socket.onclose = () => {
-      if (this.socket === socket && this.handlers === handlers) handlers.onStatus(WORKER_STATUS.DISCONNECTED);
-    };
-    socket.onerror = () => {
-      if (this.socket === socket && this.handlers === handlers) handlers.onStatus(WORKER_STATUS.ERROR);
-    };
-    socket.onmessage = (event) => {
-      if (this.socket === socket && this.handlers === handlers) void this.handleMessage(event.data);
-    };
-    this.socket = socket;
+      socket.onopen = () => {
+        if (this.socket !== socket || this.handlers !== handlers || handshakeFailed) return;
+        this.socketActive = true;
+        this.clearConnectTimer();
+        for (const topic of this.subscribedTopics) {
+          this.sendFrame({ op: WS_OP.SUBSCRIBE, topic });
+        }
+        handlers.onStatus(WORKER_STATUS.CONNECTED);
+        if (!handshakeCompleted) {
+          handshakeCompleted = true;
+          this.settleConnect();
+        }
+      };
+      socket.onclose = () => {
+        if (this.socket !== socket || this.handlers !== handlers || !this.socketActive) return;
+        this.socketActive = false;
+        handlers.onStatus(WORKER_STATUS.DISCONNECTED);
+        if (!handshakeCompleted) {
+          handshakeFailed = true;
+          this.failConnect(new Error("WebSocket closed before the handshake completed."));
+        }
+      };
+      socket.onerror = () => {
+        if (this.socket !== socket || this.handlers !== handlers || !this.socketActive) return;
+        this.socketActive = false;
+        handlers.onStatus(WORKER_STATUS.ERROR);
+        if (!handshakeCompleted) {
+          handshakeFailed = true;
+          this.failConnect(new Error("WebSocket failed to open."));
+        }
+      };
+      socket.onmessage = (event) => {
+        if (this.socket === socket && this.handlers === handlers && this.socketActive) {
+          void this.handleMessage(event.data);
+        }
+      };
+      this.socket = socket;
+      this.socketActive = true;
+    });
+    this.connectPromise = opening;
+    return opening;
   }
   /** Idempotent: re-subscribing an active topic re-sends the frame but does
    * not duplicate the local tracking entry. */
@@ -3660,10 +3828,38 @@ var WebSocketTransport = class {
   /** Close the socket and drop all state. Safe to call multiple times. */
   stop() {
     const socket = this.socket;
+    const shouldClose = this.socketActive;
     this.socket = null;
+    this.socketActive = false;
     this.handlers = null;
     this.subscribedTopics.clear();
-    socket?.close();
+    this.settleConnect();
+    this.connectPromise = null;
+    if (shouldClose) socket?.close();
+  }
+  /** Resolve the in-flight handshake gate. Idempotent: once the socket has
+   * opened (or a newer attempt replaced it) later calls are no-ops. */
+  settleConnect() {
+    this.clearConnectTimer();
+    const resolve = this.connectResolve;
+    this.connectResolve = null;
+    this.connectReject = null;
+    resolve?.();
+  }
+  /** Reject the in-flight handshake gate. Idempotent on the same terms as
+   * {@link settleConnect}. */
+  failConnect(error) {
+    this.clearConnectTimer();
+    const reject = this.connectReject;
+    this.connectResolve = null;
+    this.connectReject = null;
+    reject?.(error);
+  }
+  clearConnectTimer() {
+    if (this.connectTimer !== null) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
   }
   /** Send one JSON frame. Frames are dropped with an `onError` report when
    * the socket is not open — subscribe frames are re-sent on open, so the