cross-tab-worker-databus 0.11.0 → 0.20.7

package/dist/cjs/hooks.cjs

@@ -28,13 +28,16 @@ module.exports = __toCommonJS(hooks_exports);
 var import_react = require("react");
 function useCrossTabDataBus(create, deps = []) {
   const [bus, setBus] = (0, import_react.useState)(null);
+  const lifecycleGeneration = (0, import_react.useRef)(0);
   (0, import_react.useEffect)(() => {
+    const generation = ++lifecycleGeneration.current;
     const instance = create();
+    if (generation !== lifecycleGeneration.current) return;
     setBus(instance);
     void instance.ready().catch(() => {
     });
     return () => {
-      setBus(null);
+      if (generation === lifecycleGeneration.current) setBus(null);
       void instance.stop();
     };
   }, deps);

package/dist/cjs/hooks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks.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 */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\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  useEffect(() => {\n    const instance = create();\n    setBus(instance);\n    void instance.ready().catch(() => {});\n    return () => {\n      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>('connecting');\n  useEffect(() => {\n    if (!bus) {\n      setStatus('connecting');\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,mBAA4C;AAgBrC,SAAS,mBACd,QACA,OAAuB,CAAC,GACgB;AACxC,QAAM,CAAC,KAAK,MAAM,QAAI,uBAAiD,IAAI;AAC3E,8BAAU,MAAM;AACd,UAAM,WAAW,OAAO;AACxB,WAAO,QAAQ;AACf,SAAK,SAAS,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,WAAO,MAAM;AACX,aAAO,IAAI;AACX,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,YAAY;AAC/D,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,YAAY;AACtB;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,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 */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\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>('connecting');\n  useEffect(() => {\n    if (!bus) {\n      setStatus('connecting');\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,mBAA4C;AAgBrC,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,YAAY;AAC/D,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,YAAY;AACtB;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;",
   "names": []
 }

package/dist/cjs/index.cjs

@@ -1093,7 +1093,7 @@ var DataBusTraceReporter = class {
   latencySumMs = 0;
   dedupAccepted = 0;
   dedupSuppressed = 0;
-  constructor(options, now = Date.now) {
+  constructor(options, now = options?.now ?? Date.now) {
     this.enabled = options?.enabled ?? false;
     this.mode = options?.mode ?? "all";
     this.metricsIntervalMs = normalizeInterval(options?.metricsIntervalMs);
@@ -1255,6 +1255,12 @@ function roundMs(value) {
 // src/core/data-bus.ts
 var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
+var PersistenceRetryCancelledError = class extends Error {
+  constructor() {
+    super("Persistence retry cancelled by lifecycle transition.");
+    this.name = "PersistenceRetryCancelledError";
+  }
+};
 var CrossTabDataBus = class _CrossTabDataBus {
   transport;
   cluster;
@@ -1271,13 +1277,25 @@ var CrossTabDataBus = class _CrossTabDataBus {
   replayMaxPerTopic;
   replayPersistence;
   replayRetentionMs;
+  replayRetentionSweepMs;
+  persistenceRetryMaxAttempts;
+  persistenceRetryBackoffMs;
+  persistenceRetryGeneration = 0;
   replayHydration;
+  // Retention cleanup is coalesced so a burst of publications does not issue
+  // one IndexedDB read/write transaction per message. The newest cutoff wins.
+  replayRetentionCleanup = null;
+  replayRetentionCutoff = null;
+  replayRetentionTimer = null;
   initialConfig;
   hasInitialConfig;
   trace;
   dedupMaxEntries;
   dedupTtlMs;
+  dedupSweepMs;
+  dedupSweepTimer = null;
   dedupEnabled;
+  now;
   seenMessageIds = /* @__PURE__ */ new Map();
   dedupSuppressed = 0;
   dedupAccepted = 0;
@@ -1322,14 +1340,28 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (this.replayRetentionMs !== void 0 && (!Number.isFinite(this.replayRetentionMs) || this.replayRetentionMs <= 0)) {
       throw new TypeError("replay.retentionMs must be a positive finite number.");
     }
-    this.replayHydration = this.hydrateReplay();
+    this.replayRetentionSweepMs = replay?.retentionSweepMs;
+    if (this.replayRetentionSweepMs !== void 0 && (!Number.isFinite(this.replayRetentionSweepMs) || this.replayRetentionSweepMs <= 0)) {
+      throw new TypeError("replay.retentionSweepMs must be a positive finite number.");
+    }
+    this.persistenceRetryMaxAttempts = replay?.persistenceRetry?.maxAttempts ?? 1;
+    this.persistenceRetryBackoffMs = replay?.persistenceRetry?.backoffMs ?? 50;
+    if (!Number.isSafeInteger(this.persistenceRetryMaxAttempts) || this.persistenceRetryMaxAttempts <= 0) {
+      throw new TypeError("replay.persistenceRetry.maxAttempts must be a positive safe integer.");
+    }
+    if (!Number.isFinite(this.persistenceRetryBackoffMs) || this.persistenceRetryBackoffMs < 0) {
+      throw new TypeError("replay.persistenceRetry.backoffMs must be a non-negative finite number.");
+    }
     const { autoStart, initialConfig, trace, transport, dedup, ...clusterOptions } = options;
+    this.now = dedup?.now ?? Date.now;
+    this.replayHydration = this.hydrateReplay();
     this.transport = transport;
     this.initialConfig = initialConfig;
     this.hasInitialConfig = "initialConfig" in options;
     this.trace = new DataBusTraceReporter(trace);
     this.dedupMaxEntries = dedup?.maxEntries ?? 1e3;
     this.dedupTtlMs = dedup?.ttlMs ?? 6e4;
+    this.dedupSweepMs = dedup?.sweepMs;
     this.dedupEnabled = dedup !== void 0;
     if (!Number.isSafeInteger(this.dedupMaxEntries) || this.dedupMaxEntries <= 0) {
       throw new TypeError("dedup.maxEntries must be a positive safe integer.");
@@ -1337,6 +1369,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (!Number.isFinite(this.dedupTtlMs) || this.dedupTtlMs <= 0) {
       throw new TypeError("dedup.ttlMs must be a positive finite number.");
     }
+    if (this.dedupSweepMs !== void 0 && (!Number.isFinite(this.dedupSweepMs) || this.dedupSweepMs <= 0)) {
+      throw new TypeError("dedup.sweepMs must be a positive finite number.");
+    }
     this.cluster = new WorkerClusterRuntime({
       ...clusterOptions,
       handlers: {
@@ -1377,11 +1412,16 @@ var CrossTabDataBus = class _CrossTabDataBus {
         onSuspend: () => {
           if (!this.stopping) this.trace.event({ type: "lifecycle", action: "suspend" });
           this.trace.pause();
+          this.persistenceRetryGeneration += 1;
+          this.stopDedupSweep();
+          this.stopReplayRetentionSweep();
           this.suspendTransport();
         },
         onResume: () => {
           this.trace.event({ type: "lifecycle", action: "resume" });
           this.trace.start();
+          this.startDedupSweep();
+          this.startReplayRetentionSweep();
           this.resumeTransport();
         },
         onDiagnostic: (event) => {
@@ -1409,6 +1449,8 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.lastError = null;
     this.trace.event({ type: "lifecycle", action: "start" });
     this.trace.start();
+    this.startDedupSweep();
+    this.startReplayRetentionSweep();
     this.updateStatus("connecting");
     this.cluster.start();
     const opening = this.openTransport(config, this.pendingStop ?? Promise.resolve(), true);
@@ -1533,7 +1575,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.topicHandlers.delete(topic);
     this.replayBuffers?.delete(topic);
     if (this.replayPersistence?.clearTopic) {
-      void this.replayPersistence.clearTopic(topic).catch((error) => this.reportError(error));
+      void this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic)).catch((error) => this.reportPersistenceError(error));
     }
     this.cluster.unsubscribe(topic);
   }
@@ -1542,9 +1584,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayBuffers?.clear();
     if (this.replayPersistence?.clear) {
       try {
-        await this.replayPersistence.clear();
+        await this.withPersistenceRetry("clear", () => this.replayPersistence.clear());
       } catch (error) {
-        this.reportError(error);
+        this.reportPersistenceError(error);
         throw error;
       }
     }
@@ -1554,9 +1596,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayBuffers?.delete(topic);
     if (this.replayPersistence?.clearTopic) {
       try {
-        await this.replayPersistence.clearTopic(topic);
+        await this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic));
       } catch (error) {
-        this.reportError(error);
+        this.reportPersistenceError(error);
         throw error;
       }
     }
@@ -1566,12 +1608,19 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (!Number.isFinite(timestamp)) throw new TypeError("timestamp must be finite.");
     if (this.replayBuffers) {
       for (const [topic, messages] of this.replayBuffers) {
-        const kept = messages.filter((message) => (message.timestamp ?? 0) >= timestamp);
+        const kept = messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
         if (kept.length) this.replayBuffers.set(topic, kept);
         else this.replayBuffers.delete(topic);
       }
     }
-    if (this.replayPersistence?.clearBefore) await this.replayPersistence.clearBefore(timestamp);
+    if (this.replayPersistence?.clearBefore) {
+      try {
+        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(timestamp));
+      } catch (error) {
+        this.reportPersistenceError(error);
+        throw error;
+      }
+    }
   }
   /** Return bounded deduplication counters for diagnostics and health checks. */
   getDedupStats() {
@@ -1629,8 +1678,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
   async stop() {
     if (!this.started) return;
     this.stopping = true;
+    this.persistenceRetryGeneration += 1;
     this.trace.event({ type: "lifecycle", action: "stop" });
     this.trace.stop();
+    this.stopDedupSweep();
+    this.stopReplayRetentionSweep();
     this.topicHandlers.clear();
     this.replayBuffers?.clear();
     this.cluster.stop();
@@ -1641,7 +1693,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       else await this.transport.stop();
     } finally {
       this.transportSubscribedTopics.clear();
-      this.seenMessageIds.clear();
+      this.resetDedup();
       this.started = false;
       this.stopping = false;
       this.suspended = false;
@@ -1674,7 +1726,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
   }
   isDuplicate(message) {
     if (!this.dedupEnabled || !message.messageId) return false;
-    const now = Date.now();
+    const now = this.now();
     for (const [id, timestamp] of this.seenMessageIds) {
       if (now - timestamp > this.dedupTtlMs) this.seenMessageIds.delete(id);
     }
@@ -1694,6 +1746,20 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }
     return false;
   }
+  startDedupSweep() {
+    if (this.dedupSweepTimer || !this.dedupEnabled || !this.dedupSweepMs) return;
+    this.dedupSweepTimer = setInterval(() => this.pruneExpiredDedup(), this.dedupSweepMs);
+  }
+  stopDedupSweep() {
+    if (this.dedupSweepTimer) clearInterval(this.dedupSweepTimer);
+    this.dedupSweepTimer = null;
+  }
+  pruneExpiredDedup() {
+    const cutoff = this.now() - this.dedupTtlMs;
+    for (const [id, timestamp] of this.seenMessageIds) {
+      if (timestamp < cutoff) this.seenMessageIds.delete(id);
+    }
+  }
   /** Deliver a message to every local handler registered for its topic,
    * plus every handler registered with a wildcard subscription that matches
    * (e.g. a handler subscribed to "chat.*" receives "chat.room.1"). */
@@ -1720,9 +1786,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     buffer.push(storedMessage);
     if (buffer.length > this.replayMaxPerTopic) buffer.shift();
     if (this.replayPersistence) {
-      void this.replayPersistence.append(storedMessage).catch((error) => this.reportError(error));
+      void this.withPersistenceRetry("append", () => this.replayPersistence.append(storedMessage)).catch((error) => this.reportPersistenceError(error));
       if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
-        void this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs).catch((error) => this.reportError(error));
+        this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
       }
     }
   }
@@ -1732,9 +1798,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }
     try {
       if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
-        await this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs);
+        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(this.now() - this.replayRetentionMs));
       }
-      for (const message of await this.replayPersistence.load()) {
+      for (const message of await this.withPersistenceRetry("load", () => this.replayPersistence.load())) {
         let buffer = this.replayBuffers.get(message.topic);
         if (!buffer) {
           buffer = [];
@@ -1744,7 +1810,66 @@ var CrossTabDataBus = class _CrossTabDataBus {
         if (buffer.length > this.replayMaxPerTopic) buffer.shift();
       }
     } catch (error) {
-      this.reportError(error);
+      this.reportPersistenceError(error);
+    }
+  }
+  scheduleReplayRetentionCleanup(cutoff) {
+    if (!this.replayPersistence?.clearBefore) return;
+    if (this.replayRetentionCutoff === null || cutoff > this.replayRetentionCutoff) {
+      this.replayRetentionCutoff = cutoff;
+    }
+    if (this.replayRetentionCleanup) return;
+    this.replayRetentionCleanup = (async () => {
+      while (this.replayRetentionCutoff !== null) {
+        const nextCutoff = this.replayRetentionCutoff;
+        this.replayRetentionCutoff = null;
+        try {
+          await this.replayPersistence.clearBefore(nextCutoff);
+        } catch (error) {
+          this.reportPersistenceError(error);
+        }
+      }
+    })().finally(() => {
+      this.replayRetentionCleanup = null;
+      if (this.replayRetentionCutoff !== null) {
+        this.scheduleReplayRetentionCleanup(this.replayRetentionCutoff);
+      }
+    });
+  }
+  startReplayRetentionSweep() {
+    if (this.replayRetentionTimer || !this.replayRetentionMs || !this.replayRetentionSweepMs || !this.replayPersistence?.clearBefore) return;
+    this.replayRetentionTimer = setInterval(() => {
+      this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
+    }, this.replayRetentionSweepMs);
+  }
+  stopReplayRetentionSweep() {
+    if (this.replayRetentionTimer) clearInterval(this.replayRetentionTimer);
+    this.replayRetentionTimer = null;
+  }
+  async withPersistenceRetry(persistenceOperation, operation) {
+    const generation = this.persistenceRetryGeneration;
+    let attempt = 0;
+    let delay = this.persistenceRetryBackoffMs;
+    while (true) {
+      attempt += 1;
+      try {
+        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
+        return await operation();
+      } catch (error) {
+        if (error instanceof PersistenceRetryCancelledError || generation !== this.persistenceRetryGeneration) {
+          throw new PersistenceRetryCancelledError();
+        }
+        if (attempt >= this.persistenceRetryMaxAttempts) throw error;
+        this.trace.event({
+          type: "reliability",
+          operation: "persistence_retry",
+          persistenceOperation,
+          attempt
+        });
+        if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
+        delay = Math.min(delay * 2, 1600);
+      }
     }
   }
   /** Deliver buffered history to a newly-registered handler. For an exact
@@ -1782,7 +1907,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
     if (status === "error" && this.started && !this.stopping) {
-      const now = Date.now();
+      const now = this.now();
       if (now - this.lastRecoveryAt >= _CrossTabDataBus.RECOVERY_COOLDOWN_MS) {
         this.lastRecoveryAt = now;
         this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: 1 });
@@ -1799,6 +1924,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.trace.event({ type: "error", source: "transport" });
     this.invokeHandlers(this.errorHandlers, (handler) => handler(error), "error handler");
   }
+  reportPersistenceError(error) {
+    if (error instanceof PersistenceRetryCancelledError) return;
+    this.trace.event({ type: "reliability", operation: "persistence_cleanup" });
+    this.reportError(error);
+  }
   traceSubscription(action, topic) {
     this.trace.event({
       type: "subscription",
@@ -1952,74 +2082,165 @@ function createIndexedDbReplayPersistence(options) {
     throw new TypeError(`maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`);
   }
   let dbPromise = null;
+  const invalidate = (db) => {
+    if (dbPromise) {
+      void dbPromise.then((current) => {
+        if (current === db) {
+          current.close();
+          dbPromise = null;
+        }
+      }, () => void 0);
+    }
+  };
+  let mutationQueue = Promise.resolve();
+  const serializeMutation = (mutation) => {
+    const next = mutationQueue.then(mutation, mutation);
+    mutationQueue = next.catch(() => void 0);
+    return next;
+  };
   const open = () => {
     if (dbPromise) return dbPromise;
-    dbPromise = new Promise((resolve, reject) => {
+    const pending = new Promise((resolve, reject) => {
       const request = indexedDb.open(dbName, 1);
       request.onupgradeneeded = () => request.result.createObjectStore(storeName, { keyPath: "topic" });
-      request.onsuccess = () => resolve(request.result);
+      request.onsuccess = () => {
+        const db = request.result;
+        db.onversionchange = () => {
+          db.close();
+          if (dbPromise) dbPromise = null;
+        };
+        resolve(db);
+      };
       request.onerror = () => reject(request.error ?? new Error("Failed to open replay database."));
     });
-    return dbPromise;
+    dbPromise = pending;
+    void pending.catch(() => {
+      if (dbPromise === pending) dbPromise = null;
+    });
+    return pending;
   };
   return {
     async load() {
       const db = await open();
       return new Promise((resolve, reject) => {
-        const request = db.transaction(storeName, "readonly").objectStore(storeName).getAll();
+        let request;
+        try {
+          request = db.transaction(storeName, "readonly").objectStore(storeName).getAll();
+        } catch (error) {
+          invalidate(db);
+          reject(error);
+          return;
+        }
         request.onsuccess = () => resolve(request.result.flatMap((record) => record.messages));
-        request.onerror = () => reject(request.error ?? new Error("Failed to load replay history."));
+        request.onerror = () => {
+          invalidate(db);
+          reject(request.error ?? new Error("Failed to load replay history."));
+        };
       });
     },
-    async append(message) {
-      const db = await open();
-      await new Promise((resolve, reject) => {
-        const transaction = db.transaction(storeName, "readwrite");
-        const store = transaction.objectStore(storeName);
-        const request = store.get(message.topic);
-        request.onsuccess = () => {
-          const messages = (request.result?.messages ?? []).concat(message).slice(-maxPerTopic);
-          store.put({ topic: message.topic, messages });
-        };
-        request.onerror = () => reject(request.error ?? new Error("Failed to read replay history."));
-        transaction.oncomplete = () => resolve();
-        transaction.onerror = () => reject(transaction.error ?? new Error("Failed to persist replay history."));
+    append(message) {
+      return serializeMutation(async () => {
+        const db = await open();
+        await new Promise((resolve, reject) => {
+          let transaction;
+          try {
+            transaction = db.transaction(storeName, "readwrite");
+          } catch (error) {
+            invalidate(db);
+            reject(error);
+            return;
+          }
+          const store = transaction.objectStore(storeName);
+          const request = store.get(message.topic);
+          request.onsuccess = () => {
+            const messages = (request.result?.messages ?? []).concat(message).slice(-maxPerTopic);
+            store.put({ topic: message.topic, messages });
+          };
+          request.onerror = () => {
+            invalidate(db);
+            reject(request.error ?? new Error("Failed to read replay history."));
+          };
+          transaction.oncomplete = () => resolve();
+          transaction.onerror = () => {
+            invalidate(db);
+            reject(transaction.error ?? new Error("Failed to persist replay history."));
+          };
+        });
       });
     },
-    async clear() {
-      const db = await open();
-      await new Promise((resolve, reject) => {
-        const transaction = db.transaction(storeName, "readwrite");
-        transaction.objectStore(storeName).clear();
-        transaction.oncomplete = () => resolve();
-        transaction.onerror = () => reject(transaction.error ?? new Error("Failed to clear replay history."));
+    clear() {
+      return serializeMutation(async () => {
+        const db = await open();
+        await new Promise((resolve, reject) => {
+          let transaction;
+          try {
+            transaction = db.transaction(storeName, "readwrite");
+          } catch (error) {
+            invalidate(db);
+            reject(error);
+            return;
+          }
+          transaction.objectStore(storeName).clear();
+          transaction.oncomplete = () => resolve();
+          transaction.onerror = () => {
+            invalidate(db);
+            reject(transaction.error ?? new Error("Failed to clear replay history."));
+          };
+        });
       });
     },
-    async clearTopic(topic) {
-      const db = await open();
-      await new Promise((resolve, reject) => {
-        const transaction = db.transaction(storeName, "readwrite");
-        transaction.objectStore(storeName).delete(topic);
-        transaction.oncomplete = () => resolve();
-        transaction.onerror = () => reject(transaction.error ?? new Error("Failed to clear topic replay history."));
+    clearTopic(topic) {
+      return serializeMutation(async () => {
+        const db = await open();
+        await new Promise((resolve, reject) => {
+          let transaction;
+          try {
+            transaction = db.transaction(storeName, "readwrite");
+          } catch (error) {
+            invalidate(db);
+            reject(error);
+            return;
+          }
+          transaction.objectStore(storeName).delete(topic);
+          transaction.oncomplete = () => resolve();
+          transaction.onerror = () => {
+            invalidate(db);
+            reject(transaction.error ?? new Error("Failed to clear topic replay history."));
+          };
+        });
       });
     },
-    async clearBefore(timestamp) {
-      const db = await open();
-      await new Promise((resolve, reject) => {
-        const transaction = db.transaction(storeName, "readwrite");
-        const store = transaction.objectStore(storeName);
-        const request = store.getAll();
-        request.onsuccess = () => {
-          for (const record of request.result) {
-            const messages = record.messages.filter((message) => (message.timestamp ?? 0) >= timestamp);
-            if (messages.length === 0) store.delete(record.topic);
-            else if (messages.length !== record.messages.length) store.put({ topic: record.topic, messages });
+    clearBefore(timestamp) {
+      return serializeMutation(async () => {
+        const db = await open();
+        await new Promise((resolve, reject) => {
+          let transaction;
+          try {
+            transaction = db.transaction(storeName, "readwrite");
+          } catch (error) {
+            invalidate(db);
+            reject(error);
+            return;
           }
-        };
-        request.onerror = () => reject(request.error ?? new Error("Failed to read replay history."));
-        transaction.oncomplete = () => resolve();
-        transaction.onerror = () => reject(transaction.error ?? new Error("Failed to prune replay history."));
+          const store = transaction.objectStore(storeName);
+          const request = store.getAll();
+          request.onsuccess = () => {
+            for (const record of request.result) {
+              const messages = record.messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
+              if (messages.length === 0) store.delete(record.topic);
+              else if (messages.length !== record.messages.length) store.put({ topic: record.topic, messages });
+            }
+          };
+          request.onerror = () => {
+            invalidate(db);
+            reject(request.error ?? new Error("Failed to read replay history."));
+          };
+          transaction.oncomplete = () => resolve();
+          transaction.onerror = () => {
+            invalidate(db);
+            reject(transaction.error ?? new Error("Failed to prune replay history."));
+          };
+        });
       });
     }
   };
@@ -2037,11 +2258,13 @@ function parseDataBusPublication(value, fallbackTopic) {
   if (!topic) return null;
   const hasMetadataEnvelope = fallbackTopic !== void 0 && Object.prototype.hasOwnProperty.call(publication, "data") && (typeof publication.messageId === "string" || typeof publication.timestamp === "number");
   const data = nested || fallbackTopic === void 0 || hasMetadataEnvelope ? publication.data : value;
+  const messageId = typeof publication.messageId === "string" && publication.messageId.length > 0 ? publication.messageId : void 0;
+  const timestamp = typeof publication.timestamp === "number" && Number.isFinite(publication.timestamp) ? publication.timestamp : void 0;
   return {
     topic,
     data,
-    ...typeof publication.messageId === "string" ? { messageId: publication.messageId } : {},
-    ...typeof publication.timestamp === "number" ? { timestamp: publication.timestamp } : {}
+    ...messageId === void 0 ? {} : { messageId },
+    ...timestamp === void 0 ? {} : { timestamp }
   };
 }
 
@@ -2077,7 +2300,9 @@ var WebSocketTransport = class {
     };
     socket.onclose = () => handlers.onStatus("disconnected");
     socket.onerror = () => handlers.onStatus("error");
-    socket.onmessage = (event) => this.handleMessage(event.data);
+    socket.onmessage = (event) => {
+      void this.handleMessage(event.data);
+    };
     this.socket = socket;
   }
   /** Idempotent: re-subscribing an active topic re-sends the frame but does
@@ -2153,7 +2378,15 @@ var WebSocketTransport = class {
   /** Parse a server frame. Only objects carrying a string `topic` are
    * publications; malformed JSON and unknown shapes are ignored so a chatty
    * server cannot crash the message path. */
-  handleMessage(raw) {
+  async handleMessage(raw) {
+    if (typeof Blob !== "undefined" && raw instanceof Blob) {
+      try {
+        await this.handleMessage(await raw.arrayBuffer());
+      } catch (error) {
+        this.handlers?.onError(error);
+      }
+      return;
+    }
     let parsed;
     if (raw instanceof ArrayBuffer) {
       const bytes = new Uint8Array(raw);