cross-tab-worker-databus 0.20.91 → 0.20.93

package/dist/cjs/index.cjs

@@ -229,6 +229,7 @@ function createStorageEventChannel(options) {
   };
 }
 var tabIdentityInitialized = false;
+var cachedTabId = null;
 function createBrowserEnvironment(options) {
   const channelFallback = options?.channelFallback ?? CHANNEL_FALLBACK.NONE;
   return {
@@ -274,8 +275,9 @@ function canUseStorage(storage, probeKey) {
   if (!storage) return false;
   try {
     storage.setItem(probeKey, "1");
+    const readable = storage.getItem(probeKey) === "1";
     storage.removeItem(probeKey);
-    return true;
+    return readable;
   } catch {
     return false;
   }
@@ -287,14 +289,21 @@ function getOrCreateTabId(environment, key = TAB_ID_STORAGE_KEY) {
     const hasOpener = typeof window !== "undefined" && Boolean(window.opener);
     if (existing && (!hasOpener || tabIdentityInitialized)) {
       tabIdentityInitialized = true;
+      cachedTabId = existing;
       return existing;
     }
+    if (tabIdentityInitialized && cachedTabId) return cachedTabId;
     const created = `tab-${environment.randomId()}`;
     storage?.setItem(key, created);
     tabIdentityInitialized = true;
+    cachedTabId = created;
     return created;
   } catch {
-    return `tab-${environment.randomId()}`;
+    if (cachedTabId) return cachedTabId;
+    const created = `tab-${environment.randomId()}`;
+    tabIdentityInitialized = true;
+    cachedTabId = created;
+    return created;
   }
 }
 
@@ -455,7 +464,17 @@ var BatchingStorageWriter = class {
   clear() {
     this.pending.clear();
     this.flushScheduled = false;
+    this.cancelRetry();
+    this.retryCount.clear();
+    this.retryDelayMs = INITIAL_RETRY_DELAY_MS;
     this.storage.clear();
+  }
+  /** Drop queued mutations and cancel retry state without clearing storage.
+   * Used when the owning runtime is torn down: final best-effort writes have
+   * already been flushed, and failed writes must not keep timers alive. */
+  discardPending() {
+    this.pending.clear();
+    this.flushScheduled = false;
     this.cancelRetry();
     this.retryCount.clear();
     this.retryDelayMs = INITIAL_RETRY_DELAY_MS;
@@ -738,6 +757,9 @@ var WorkerClusterRuntime = class {
   started = false;
   suspended = false;
   lifecycleListening = false;
+  /** Invalidates an in-flight pageshow resume when a synchronous onResume
+   * callback stops or pauses the cluster before activate() is reached. */
+  lifecycleGeneration = 0;
   currentRecord;
   constructor(options) {
     assertClusterOptions(options);
@@ -774,8 +796,14 @@ var WorkerClusterRuntime = class {
   /** Start the cluster: register, listen for lifecycle events, and begin heartbeats. */
   start() {
     if (this.started) return;
-    this.suspended = false;
+    this.lifecycleGeneration += 1;
     this.addLifecycleListeners();
+    if (this.environment.getVisibilityState() === TAB_VISIBILITY.HIDDEN) {
+      this.suspended = true;
+      this.handlers.onSuspend?.();
+      return;
+    }
+    this.suspended = false;
     this.activate();
   }
   /**
@@ -786,6 +814,7 @@ var WorkerClusterRuntime = class {
    * stop() path where callers expect every Set/Map to be empty afterwards.
    */
   stop() {
+    this.lifecycleGeneration += 1;
     if (!this.started && !this.suspended) return;
     this.pause();
     this.flushStorage();
@@ -804,7 +833,15 @@ var WorkerClusterRuntime = class {
   activate() {
     if (this.started) return;
     this.started = true;
-    this.channel = this.storage ? this.environment.createChannel(this.channelName) : null;
+    if (this.storage) {
+      try {
+        this.channel = this.environment.createChannel(this.channelName);
+      } catch {
+        this.channel = null;
+      }
+    } else {
+      this.channel = null;
+    }
     if (!this.channel) this.storage = null;
     this.channel?.addEventListener("message", this.handleMessage);
     const now = this.environment.now();
@@ -832,7 +869,11 @@ var WorkerClusterRuntime = class {
    * to other workers, remove our worker record, and close the channel.
    */
   pause() {
-    if (!this.started) return;
+    this.lifecycleGeneration += 1;
+    if (!this.started) {
+      if (this.lifecycleListening) this.suspended = true;
+      return;
+    }
     this.started = false;
     this.suspended = true;
     if (this.heartbeatHandle !== null) this.environment.clearInterval(this.heartbeatHandle);
@@ -846,6 +887,7 @@ var WorkerClusterRuntime = class {
     this.removeStorage(this.workerStorageKey(this.workerId));
     this.flushStorage();
     this.notifyRegistry();
+    if (this.storage instanceof BatchingStorageWriter) this.storage.discardPending();
     const channel = this.channel;
     this.channel = null;
     this.handlers.onSuspend?.();
@@ -1147,8 +1189,10 @@ var WorkerClusterRuntime = class {
   handlePageHide = () => this.pause();
   handlePageShow = () => {
     if (!this.suspended) return;
+    const generation = ++this.lifecycleGeneration;
     this.suspended = false;
     this.handlers.onResume?.();
+    if (generation !== this.lifecycleGeneration) return;
     this.activate();
   };
   handleVisibilityChange = () => {
@@ -1203,10 +1247,16 @@ var WorkerClusterRuntime = class {
     if (message.targetWorkerId !== this.workerId) return;
     this.rememberTopic(message.topic);
     switch (message.action) {
-      case CONTROL_ACTION.SUBSCRIBE:
+      case CONTROL_ACTION.SUBSCRIBE: {
+        const route = this.readRoute(message.topicKey);
+        if (route && route.workerId !== this.workerId) return;
+        if (route?.workerId === this.workerId && route.handoffFromWorkerId !== void 0 && route.confirmedAt === void 0) {
+          return;
+        }
         this.assignedTopics.set(message.topicKey, message.topic);
         this.confirmRoute(message.topicKey);
         break;
+      }
       case CONTROL_ACTION.UNSUBSCRIBE:
         if (this.releaseHandoffOnUnsubscribe(message)) return;
         break;
@@ -1267,8 +1317,8 @@ var WorkerClusterRuntime = class {
   }
   /**
    * Accept a graceful handoff only when the route still points to this worker,
-   * the release comes from the recorded previous owner, and the generation is
-   * at least as new as ours. Any other ROUTE_RELEASED is stale and dropped.
+   * the release comes from the recorded previous owner, and the generation
+   * exactly matches ours. Any other ROUTE_RELEASED is stale and dropped.
    */
   handleRouteReleasedMessage(message) {
     if (message.targetWorkerId !== this.workerId) return;
@@ -1281,11 +1331,11 @@ var WorkerClusterRuntime = class {
   }
   /** A ROUTE_RELEASED is stale (and must be dropped) unless the route still
    * points to us, the release comes from the recorded previous owner, and
-   * the release generation is at least as new as ours. A replayed ACK from an
-   * earlier handoff round (e.g. an a↔b ping-pong) carries an older generation
-   * and must not confirm the current round. */
+   * the release generation exactly matches ours. A delayed ACK from either an
+   * earlier or later handoff round belongs to a different route and must not
+   * confirm the current round. */
   isStaleRouteRelease(route, message) {
-    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || message.generation < route.generation;
+    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || message.generation !== route.generation;
   }
   /** True when an unconfirmed handoff route has been stuck longer than a
    * worker TTL. The ACK for a live handoff is posted synchronously with the
@@ -1912,7 +1962,7 @@ var ReplayManager = class {
     this.trace = deps.trace;
     this.onPersistenceError = deps.onPersistenceError;
     this.onDispatchError = deps.onDispatchError;
-    this.hydration = this.hydrate();
+    void this.requestHydration();
   }
   deps;
   buffers;
@@ -1931,7 +1981,18 @@ var ReplayManager = class {
   retryGeneration = 0;
   pendingReplayPersistence = [];
   persistenceFlushScheduled = false;
-  hydration;
+  /** Current hydration operation, if one belongs to the active lifecycle. */
+  hydration = null;
+  /** Invalidates a load from a superseded suspend/reset lifecycle. */
+  hydrationEpoch = 0;
+  /** Whether the active lifecycle has finished (or deliberately skipped) hydration. */
+  hydrationComplete = false;
+  /** A failed load is retried by the next explicit start(), not every replay request. */
+  hydrationFailed = false;
+  /** Mutations that must be applied to a load already in flight. */
+  hydrationClearAll = false;
+  hydrationClearedTopics = /* @__PURE__ */ new Set();
+  hydrationClearBefore = null;
   /** Coalesced retention cleanup: the newest cutoff wins while one is running. */
   retentionCleanup = null;
   retentionCutoff = null;
@@ -1985,7 +2046,7 @@ var ReplayManager = class {
     if (!this.buffers) return;
     const limit = typeof replayOption === "number" ? Math.min(Math.floor(replayOption), this.maxPerTopic) : this.maxPerTopic;
     if (this.persistence) {
-      void this.hydration.then(() => {
+      void this.requestHydration().then(() => {
         if (isHandlerActive?.() ?? true) this.deliver(topic, limit, handler);
       });
       return;
@@ -1997,22 +2058,24 @@ var ReplayManager = class {
    * clearTopic), and prune durable history. */
   onTopicUnsubscribed(topic) {
     if (!this.buffers) return;
+    const clearing = this.persistence?.clearTopic ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)) : null;
+    this.hydrationClearedTopics.add(topic);
     this.buffers.delete(topic);
     this.pendingReplayPersistence = this.pendingReplayPersistence.filter((message) => message.topic !== topic);
-    if (this.persistence?.clearTopic) {
-      void this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)).catch((error) => this.onPersistenceError(error));
-    }
+    if (clearing) void clearing.catch((error) => this.onPersistenceError(error));
   }
   /** Clear all in-memory replay buffers and, when supported, durable history.
    * Reports persistence failures and rethrows, mirroring the public API
    * contract that callers can observe a failed clear. */
   async clearAll() {
     if (!this.buffers) return;
+    const clearing = this.persistence?.clear ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR, () => this.persistence.clear()) : null;
+    this.hydrationClearAll = true;
     this.buffers.clear();
     this.pendingReplayPersistence = [];
-    if (this.persistence?.clear) {
+    if (clearing) {
       try {
-        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR, () => this.persistence.clear());
+        await clearing;
       } catch (error) {
         this.onPersistenceError(error);
         throw error;
@@ -2022,11 +2085,13 @@ var ReplayManager = class {
   /** Clear replay history for one exact topic, including durable storage. */
   async clearTopic(topic) {
     if (!this.buffers) return;
+    const clearing = this.persistence?.clearTopic ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)) : null;
+    this.hydrationClearedTopics.add(topic);
     this.buffers.delete(topic);
     this.pendingReplayPersistence = this.pendingReplayPersistence.filter((message) => message.topic !== topic);
-    if (this.persistence?.clearTopic) {
+    if (clearing) {
       try {
-        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic));
+        await clearing;
       } catch (error) {
         this.onPersistenceError(error);
         throw error;
@@ -2036,7 +2101,9 @@ var ReplayManager = class {
   /** Remove replay entries older than an epoch-millisecond cutoff. */
   async clearBefore(timestamp) {
     if (!Number.isFinite(timestamp)) throw new TypeError("timestamp must be finite.");
+    const clearing = this.persistence?.clearBefore ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(timestamp)) : null;
     if (this.buffers) {
+      this.hydrationClearBefore = this.hydrationClearBefore === null ? timestamp : Math.max(this.hydrationClearBefore, timestamp);
       for (const [topic, messages] of this.buffers) {
         const kept = messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
         if (kept.length) this.buffers.set(topic, kept);
@@ -2046,9 +2113,9 @@ var ReplayManager = class {
     this.pendingReplayPersistence = this.pendingReplayPersistence.filter(
       (message) => message.timestamp === void 0 || message.timestamp >= timestamp
     );
-    if (this.persistence?.clearBefore) {
+    if (clearing) {
       try {
-        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(timestamp));
+        await clearing;
       } catch (error) {
         this.onPersistenceError(error);
         throw error;
@@ -2058,6 +2125,11 @@ var ReplayManager = class {
   /** Start the periodic retention sweep. No-op when no durable retention
    * config makes it necessary. */
   start() {
+    if (this.hydrationFailed) {
+      this.hydrationComplete = false;
+      this.hydrationFailed = false;
+    }
+    void this.requestHydration();
     if (this.retentionTimer || !this.retentionMs || !this.retentionSweepMs || !this.persistence?.clearBefore) return;
     this.retentionTimer = setInterval(() => {
       this.scheduleRetentionCleanup(this.now() - this.retentionMs);
@@ -2072,13 +2144,25 @@ var ReplayManager = class {
    * or stopped bus does not keep hammering the store) and stop the sweep. */
   suspend() {
     this.retryGeneration += 1;
+    if (this.hydration) {
+      this.hydrationEpoch += 1;
+      this.hydration = null;
+      this.hydrationComplete = false;
+    }
     this.pendingReplayPersistence = [];
     this.retentionCutoff = null;
     this.stop();
   }
-  /** Drop all in-memory buffers (used on full teardown). */
+  /** Drop all in-memory buffers and require hydration for the next lifecycle. */
   resetBuffers() {
     this.buffers?.clear();
+    this.hydrationEpoch += 1;
+    this.hydration = null;
+    this.hydrationComplete = false;
+    this.hydrationFailed = false;
+    this.hydrationClearAll = false;
+    this.hydrationClearedTopics.clear();
+    this.hydrationClearBefore = null;
   }
   /** Buffer occupancy for diagnostics. `bytes` is an approximate in-memory
    * payload footprint (same heuristic as adaptive load weighting), computed on
@@ -2130,38 +2214,78 @@ var ReplayManager = class {
       void this.withPersistenceRetry(PERSISTENCE_OPERATION.APPEND, () => this.persistence.appendBatch(batch)).catch((error) => this.onPersistenceError(error));
     });
   }
-  /** Load durable history into the in-memory rings once at startup, pruning
+  /** Start the active lifecycle's one-shot hydration, if it has not completed
+   * or deliberately skipped hydration already. */
+  requestHydration() {
+    if (!this.buffers || !this.persistence) {
+      this.hydrationComplete = true;
+      return Promise.resolve();
+    }
+    if (this.hydration) return this.hydration;
+    if (this.hydrationComplete) return Promise.resolve();
+    const epoch = this.hydrationEpoch;
+    const generation = this.retryGeneration;
+    const operation = this.hydrate(epoch, generation);
+    this.hydration = operation;
+    return operation;
+  }
+  /** Load durable history into the in-memory rings once per lifecycle, pruning
    * entries past the retention window first. Failures are reported but do not
    * block startup — the bus runs with whatever survived. */
-  async hydrate() {
+  async hydrate(epoch, generation) {
     if (!this.buffers || !this.persistence) {
       return;
     }
     try {
-      if (this.retentionMs !== void 0 && this.persistence.clearBefore) {
-        await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(this.now() - this.retentionMs));
-      }
-      const loaded = await this.withPersistenceRetry(PERSISTENCE_OPERATION.LOAD, () => this.persistence.load());
-      for (const message of loaded) {
-        let buffer = this.buffers.get(message.topic);
-        if (!buffer) {
-          buffer = [];
-          this.buffers.set(message.topic, buffer);
+      try {
+        if (this.retentionMs !== void 0 && this.persistence.clearBefore) {
+          await this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_BEFORE, () => this.persistence.clearBefore(this.now() - this.retentionMs));
+        }
+        const loaded = await this.withPersistenceRetry(PERSISTENCE_OPERATION.LOAD, () => this.persistence.load());
+        if (generation !== this.retryGeneration) throw new PersistenceRetryCancelledError();
+        if (epoch !== this.hydrationEpoch) return;
+        const loadedByTopic = /* @__PURE__ */ new Map();
+        for (const message of loaded) {
+          if (this.hydrationClearAll || this.hydrationClearedTopics.has(message.topic) || this.hydrationClearBefore !== null && message.timestamp !== void 0 && message.timestamp < this.hydrationClearBefore) continue;
+          let buffer = loadedByTopic.get(message.topic);
+          if (!buffer) {
+            buffer = [];
+            loadedByTopic.set(message.topic, buffer);
+          }
+          buffer.push(message);
+        }
+        for (const [topic, durableBuffer] of loadedByTopic) {
+          const liveBuffer = this.buffers.get(topic);
+          this.buffers.set(topic, liveBuffer ? [...durableBuffer, ...liveBuffer] : durableBuffer);
+        }
+        const hydrationNow = this.now();
+        for (const [topic, buffer] of this.buffers) {
+          const pruned = pruneReplayHistory(buffer, {
+            maxPerTopic: this.maxPerTopic,
+            pruneStrategy: this.pruneStrategy,
+            retentionMs: this.retentionMs,
+            now: hydrationNow
+          });
+          if (pruned !== buffer) this.buffers.set(topic, pruned);
+        }
+        this.hydrationComplete = true;
+        this.hydrationFailed = false;
+      } catch (error) {
+        if (generation !== this.retryGeneration) {
+          this.onPersistenceError(
+            error instanceof PersistenceRetryCancelledError ? error : new PersistenceRetryCancelledError()
+          );
+          return;
         }
-        buffer.push(message);
+        if (epoch !== this.hydrationEpoch) return;
+        this.onPersistenceError(error);
+        this.hydrationComplete = true;
+        this.hydrationFailed = true;
       }
-      const hydrationNow = this.now();
-      for (const [topic, buffer] of this.buffers) {
-        const pruned = pruneReplayHistory(buffer, {
-          maxPerTopic: this.maxPerTopic,
-          pruneStrategy: this.pruneStrategy,
-          retentionMs: this.retentionMs,
-          now: hydrationNow
-        });
-        if (pruned !== buffer) this.buffers.set(topic, pruned);
+    } finally {
+      if (this.hydrationEpoch === epoch && this.retryGeneration === generation) {
+        this.hydration = null;
       }
-    } catch (error) {
-      this.onPersistenceError(error);
     }
   }
   /** Coalesce retention cleanup: the newest cutoff wins while one pass runs,
@@ -2185,7 +2309,7 @@ var ReplayManager = class {
       }
     })().finally(() => {
       this.retentionCleanup = null;
-      if (this.retentionCutoff !== null && generation === this.retryGeneration) {
+      if (this.retentionCutoff !== null) {
         this.scheduleRetentionCleanup(this.retentionCutoff);
       }
     });
@@ -2338,7 +2462,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.20.91" : "";
+var SDK_VERSION = true ? "0.20.93" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -2414,11 +2538,21 @@ var CrossTabDataBus = class {
   recoveryGateRelease = null;
   recoveryTimer = null;
   recoveryTimerToken = 0;
+  // Invalidates operations parked on the recovery gate when a hide/stop
+  // supersedes the recovery cycle. Their microtask may run after an immediate
+  // explicit start has cleared `suspended`, so a state check alone is not
+  // enough to keep stale work from reaching the replacement transport.
+  recoveryCancellationToken = 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;
+  // Number of transport operations currently parked behind `recoveryGate`.
+  // When an automatic attempt fails, these already-parked operations are
+  // themselves demand: the failure path starts an on-demand reopen instead of
+  // stranding them until some unrelated future operation arrives.
+  recoveryWaiters = 0;
   /** 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. */
@@ -2533,7 +2667,7 @@ var CrossTabDataBus = class {
           this.suspendTransport();
         },
         onResume: () => {
-          this.resumeSuspendedResources();
+          if (!this.resumeSuspendedResources()) return;
           this.resumeTransport();
         },
         onDiagnostic: (event) => {
@@ -2562,11 +2696,13 @@ var CrossTabDataBus = class {
       const transportDown = !this.transportReady || this.status === WORKER_STATUS.ERROR || this.status === WORKER_STATUS.DISCONNECTED;
       if (!transportDown) return Promise.resolve();
       this.activeConfig = config;
-      this.resetFailureState();
+      this.resetFailureState(true);
       const resumingFromSuspend = this.suspended;
-      if (resumingFromSuspend) this.resumeSuspendedResources();
+      if (resumingFromSuspend && !this.resumeSuspendedResources()) {
+        return this.stopPromise ?? Promise.resolve();
+      }
       const opening2 = this.reopenTransport();
-      if (resumingFromSuspend) this.cluster.start();
+      if (resumingFromSuspend && !this.stopping && !this.suspended) this.cluster.start();
       return opening2;
     }
     this.started = true;
@@ -2574,12 +2710,6 @@ var CrossTabDataBus = class {
     this.suspended = false;
     this.activeConfig = config;
     this.resetFailureState();
-    this.trace.start();
-    this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.START });
-    this.startDedupSweep();
-    this.replayManager.start();
-    this.updateStatus(WORKER_STATUS.CONNECTING);
-    this.cluster.start();
     const lifecycleEpoch = ++this.lifecycleEpoch;
     const opening = this.openTransport(
       config,
@@ -2588,7 +2718,17 @@ var CrossTabDataBus = class {
       lifecycleEpoch
     );
     this.startPromise = opening;
+    this.trace.start();
+    this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.START });
+    if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping) return opening;
+    this.startDedupSweep();
+    this.replayManager.start();
+    this.updateStatus(WORKER_STATUS.CONNECTING);
+    if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping) return opening;
+    this.cluster.start();
+    if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping) return opening;
     for (const topic of this.topicHandlers.keys()) {
+      if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping) break;
       this.cluster.subscribe(topic);
     }
     void opening.then(
@@ -2650,27 +2790,49 @@ var CrossTabDataBus = class {
   /** 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() {
+  cancelScheduledRecovery(invalidateParkedOperations = false, releaseGate = true) {
     this.recoveryTimerToken += 1;
+    if (invalidateParkedOperations) this.recoveryCancellationToken += 1;
     if (this.recoveryTimer !== null) {
       clearTimeout(this.recoveryTimer);
       this.recoveryTimer = null;
     }
-    this.releaseRecoveryGate();
+    if (releaseGate) 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 no gate/successor retry remains, release any waiters.
+   *
+   * `kickParkedWaiters` is set only when the failure is an automatic attempt: an
+   * operation that was already parked on the gate is itself demand, so it must
+   * not wait for some unrelated future operation. A failed *on-demand* reopen
+   * passes `false`, so it re-arms the flag for a later operation instead of
+   * looping on its own failure. */
+  allowDemandRecovery(kickParkedWaiters = false) {
     if (this.recoveryGate !== null && this.started && !this.stopping && !this.suspended && this.status === WORKER_STATUS.ERROR) {
       this.recoveryDemandAllowed = true;
+      if (kickParkedWaiters && this.recoveryWaiters > 0) this.startDemandRecovery();
       return;
     }
     this.releaseRecoveryGate();
   }
+  /** Start one on-demand reopen if a failed attempt has left parked operations
+   * and enabled demand recovery. Consumes the demand token so at most one
+   * reopen is issued; every waiter stays behind the gate until it succeeds. */
+  startDemandRecovery() {
+    if (!this.recoveryDemandAllowed) return;
+    if (this.status !== WORKER_STATUS.ERROR || this.suspended || this.stopping) return;
+    this.recoveryDemandAllowed = false;
+    const opening = this.reopenTransport();
+    void opening.then(
+      () => this.releaseRecoveryGate(),
+      () => this.allowDemandRecovery()
+    );
+  }
   /** Reset failure and recovery diagnostics for a new explicit start session. */
-  resetFailureState() {
-    this.cancelScheduledRecovery();
+  resetFailureState(preserveRecoveryGate = false) {
+    this.cancelScheduledRecovery(false, !preserveRecoveryGate);
+    if (preserveRecoveryGate) this.recoveryDemandAllowed = false;
     this.lastError = null;
     this.lastErrorAt = null;
     this.lastFailure = null;
@@ -3010,22 +3172,36 @@ var CrossTabDataBus = class {
     if (!this.started && !this.startPromise && !this.pendingStop && !this.transportReady) {
       return Promise.resolve();
     }
+    let resolveGate;
+    const stopGate = new Promise((resolve) => {
+      resolveGate = resolve;
+    });
+    this.stopPromise = stopGate;
+    this.beginStop();
     const stopPromise = this.performStop();
-    this.stopPromise = stopPromise;
     void stopPromise.then(
       () => {
-        if (this.stopPromise === stopPromise) this.stopPromise = null;
+        if (this.stopPromise === stopGate) this.stopPromise = null;
+        resolveGate();
       },
       () => {
-        if (this.stopPromise === stopPromise) this.stopPromise = null;
+        if (this.stopPromise === stopGate) this.stopPromise = null;
+        resolveGate();
       }
     );
-    return stopPromise;
+    return stopGate;
   }
-  async performStop() {
+  /**
+   * Synchronous teardown prelude. Flips `stopping` (the authoritative
+   * in-flight signal), cancels scheduled work, releases handlers, and emits the
+   * observable STOP lifecycle event. stop() calls it after the shared gate is
+   * installed but in the same tick, so the stop still takes effect immediately
+   * while a re-entrant stop() from the STOP event shares the one teardown.
+   */
+  beginStop() {
     this.lifecycleEpoch += 1;
     this.stopping = true;
-    this.cancelScheduledRecovery();
+    this.cancelScheduledRecovery(true);
     this.replayManager.suspend();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.STOP });
     this.trace.stop();
@@ -3033,6 +3209,8 @@ var CrossTabDataBus = class {
     this.topicHandlers.clear();
     this.replayManager.resetBuffers();
     this.cluster.stop();
+  }
+  async performStop() {
     try {
       await this.startPromise?.catch(() => void 0);
       const pendingStop = this.pendingStop;
@@ -3049,8 +3227,6 @@ var CrossTabDataBus = class {
       this.transportReady = false;
       this.startPromise = null;
       this.pendingStop = null;
-      this.lastError = null;
-      this.lastErrorAt = null;
       this.activeConfig = void 0;
       this.recoveryAttempt = 0;
       this.recoveryExhausted = false;
@@ -3147,7 +3323,9 @@ var CrossTabDataBus = class {
           const opening = this.reopenTransport(attempt);
           void opening.then(
             () => this.releaseRecoveryGate(),
-            () => this.allowDemandRecovery()
+            // Operations already parked on the gate are demand: run one
+            // on-demand reopen now instead of waiting for an unrelated event.
+            () => this.allowDemandRecovery(true)
           );
         }, this.recoveryCooldownMs);
       }
@@ -3250,10 +3428,13 @@ var CrossTabDataBus = class {
    * pageshow path and explicit start() must run this so an explicit resume
    * cannot leave trace metrics and periodic cleanup timers permanently off. */
   resumeSuspendedResources() {
+    const lifecycleEpoch = this.lifecycleEpoch;
     this.trace.start();
     this.trace.event({ type: TRACE_EVENT_TYPE.LIFECYCLE, action: TRACE_LIFECYCLE_ACTION.RESUME });
+    if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping) return false;
     this.startDedupSweep();
     this.replayManager.start();
+    return lifecycleEpoch === this.lifecycleEpoch && !this.stopping;
   }
   /**
    * Suspend the transport when the tab goes hidden. Stops the transport and
@@ -3261,12 +3442,13 @@ var CrossTabDataBus = class {
    */
   suspendTransport() {
     if (this.stopping) return;
-    this.lifecycleEpoch += 1;
+    const suspensionEpoch = ++this.lifecycleEpoch;
     this.suspended = true;
-    this.cancelScheduledRecovery();
+    this.cancelScheduledRecovery(true);
     this.transportReady = false;
     this.transportSubscribedTopics.clear();
     this.updateStatus(WORKER_STATUS.DISCONNECTED);
+    if (suspensionEpoch !== this.lifecycleEpoch || this.stopping || !this.suspended) return;
     if (this.pendingStop && (this.startPromise === null || this.startPromise === this.pendingStop)) {
       this.startPromise = this.pendingStop;
       return;
@@ -3301,13 +3483,18 @@ var CrossTabDataBus = class {
     if (this.startPromise && this.startPromise !== this.pendingStop) return this.startPromise;
     const config = this.activeConfig;
     const traceAttempt = recoveryAttempt ?? (this.recoveryAttempt > 0 ? this.recoveryAttempt : void 0);
-    this.started = true;
-    this.suspended = false;
-    this.updateStatus(WORKER_STATUS.CONNECTING);
     const lifecycleEpoch = ++this.lifecycleEpoch;
     const pending = this.startPromise ?? this.pendingStop ?? Promise.resolve();
     const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false, lifecycleEpoch));
     this.startPromise = opening;
+    this.started = true;
+    this.suspended = false;
+    this.transportReady = false;
+    this.updateStatus(WORKER_STATUS.CONNECTING);
+    if (lifecycleEpoch !== this.lifecycleEpoch || this.stopping || this.suspended) {
+      void opening.catch(() => void 0);
+      return opening;
+    }
     void opening.then(
       () => {
         if (this.startPromise === opening) this.startPromise = null;
@@ -3337,17 +3524,13 @@ var CrossTabDataBus = class {
   runTransport(operation) {
     if (this.suspended) return;
     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;
+      const cancellationToken = this.recoveryCancellationToken;
+      this.startDemandRecovery();
+      this.recoveryWaiters += 1;
       void gate.then(() => {
-        if (this.stopping || this.suspended) return;
+        this.recoveryWaiters -= 1;
+        if (this.stopping || this.suspended || cancellationToken !== this.recoveryCancellationToken) return;
         this.runTransport(operation);
       });
       return;