cross-tab-worker-databus 0.2.1 → 0.4.0

package/dist/cjs/centrifuge.cjs

@@ -0,0 +1,2205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/centrifuge.ts
+var centrifuge_exports = {};
+__export(centrifuge_exports, {
+  CentrifugeWorkerTransport: () => CentrifugeWorkerTransport,
+  createCentrifugeDataBus: () => createCentrifugeDataBus
+});
+module.exports = __toCommonJS(centrifuge_exports);
+
+// src/core/environment.ts
+function getStorage(name) {
+  try {
+    return typeof window === "undefined" ? null : window[name];
+  } catch {
+    return null;
+  }
+}
+function randomId() {
+  try {
+    return globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2);
+  } catch {
+    return Math.random().toString(36).slice(2);
+  }
+}
+var tabIdentityInitialized = false;
+function createBrowserEnvironment() {
+  return {
+    storage: getStorage("localStorage"),
+    sessionStorage: getStorage("sessionStorage"),
+    now: Date.now,
+    randomId,
+    createChannel: (name) => {
+      try {
+        return typeof BroadcastChannel === "undefined" ? null : new BroadcastChannel(name);
+      } catch {
+        return null;
+      }
+    },
+    setInterval: (callback, intervalMs) => globalThis.setInterval(callback, intervalMs),
+    clearInterval: (handle) => globalThis.clearInterval(handle),
+    getVisibilityState: () => typeof document !== "undefined" && document.visibilityState === "hidden" ? "hidden" : "visible",
+    addVisibilityChangeListener: (listener) => {
+      if (typeof document !== "undefined") document.addEventListener("visibilitychange", listener);
+    },
+    removeVisibilityChangeListener: (listener) => {
+      if (typeof document !== "undefined") document.removeEventListener("visibilitychange", listener);
+    },
+    addPageHideListener: (listener) => {
+      if (typeof window !== "undefined") window.addEventListener("pagehide", listener);
+    },
+    removePageHideListener: (listener) => {
+      if (typeof window !== "undefined") window.removeEventListener("pagehide", listener);
+    },
+    addPageShowListener: (listener) => {
+      if (typeof window !== "undefined") window.addEventListener("pageshow", listener);
+    },
+    removePageShowListener: (listener) => {
+      if (typeof window !== "undefined") window.removeEventListener("pageshow", listener);
+    }
+  };
+}
+function canUseStorage(storage, probeKey) {
+  if (!storage) return false;
+  try {
+    storage.setItem(probeKey, "1");
+    storage.removeItem(probeKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getOrCreateTabId(environment, key = "cross-tab-worker-databus:tab-id") {
+  const storage = environment.sessionStorage;
+  try {
+    const existing = storage?.getItem(key);
+    const hasOpener = typeof window !== "undefined" && Boolean(window.opener);
+    if (existing && (!hasOpener || tabIdentityInitialized)) {
+      tabIdentityInitialized = true;
+      return existing;
+    }
+    const created = `tab-${environment.randomId()}`;
+    storage?.setItem(key, created);
+    tabIdentityInitialized = true;
+    return created;
+  } catch {
+    return `tab-${environment.randomId()}`;
+  }
+}
+
+// src/core/hash.ts
+function createOpaqueKey(value) {
+  let h1 = SEED_H1 ^ value.length;
+  let h2 = SEED_H2 ^ value.length;
+  let h3 = SEED_H3 ^ value.length;
+  let h4 = SEED_H4 ^ value.length;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    h1 = Math.imul(h1 ^ code, PRIME_H1);
+    h2 = Math.imul(h2 ^ code, PRIME_H2);
+    h3 = Math.imul(h3 ^ code, PRIME_H3);
+    h4 = Math.imul(h4 ^ code, PRIME_H4);
+  }
+  h1 = avalancheMix(h1, h2);
+  h2 = avalancheMix(h2, h3);
+  h3 = avalancheMix(h3, h4);
+  h4 = avalancheMix(h4, h1);
+  return [h1, h2, h3, h4].map((hash) => (hash >>> 0).toString(16).padStart(8, "0")).join("");
+}
+var SEED_H1 = 3735928559;
+var SEED_H2 = 1103547991;
+var SEED_H3 = 3235826430;
+var SEED_H4 = 2654435769;
+var PRIME_H1 = 2654435761;
+var PRIME_H2 = 1597334677;
+var PRIME_H3 = 2246822519;
+var PRIME_H4 = 3266489917;
+var AVALANCHE_PRIME = 2246822507;
+var AVALANCHE_CROSS = 3266489909;
+function avalancheMix(self, neighbor) {
+  return Math.imul(self ^ self >>> 16, AVALANCHE_PRIME) ^ Math.imul(neighbor ^ neighbor >>> 13, AVALANCHE_CROSS);
+}
+
+// src/core/routing.ts
+var DEFAULT_MAX_ACTIVE_WORKERS = 3;
+function selectLeastLoadedWorker(workers, preferredWorkerId) {
+  const preferred = workers.find((worker) => worker.workerId === preferredWorkerId);
+  if (preferred) return preferred;
+  return workers.reduce((least, worker) => {
+    if (!least) return worker;
+    const byLoad = worker.load - least.load;
+    if (byLoad !== 0) return byLoad < 0 ? worker : least;
+    if (worker.workerId < least.workerId) return worker;
+    return least;
+  }, void 0);
+}
+function selectActiveWorkers(workers, maxActiveWorkers = DEFAULT_MAX_ACTIVE_WORKERS) {
+  const healthyWorkers = workers.filter((worker) => worker.status === "connecting" || worker.status === "connected");
+  const availableWorkers = healthyWorkers.length > 0 ? healthyWorkers : [...workers];
+  const visibleWorkers = availableWorkers.filter((worker) => worker.visibilityState === "visible");
+  const candidates = visibleWorkers.length > 0 ? visibleWorkers : availableWorkers;
+  return candidates.sort(
+    (left, right) => left.registeredAt - right.registeredAt || (left.workerId < right.workerId ? -1 : left.workerId > right.workerId ? 1 : 0)
+  ).slice(0, maxActiveWorkers);
+}
+function isWildcardTopic(pattern) {
+  return pattern === "*" || pattern.endsWith(".*");
+}
+function topicMatchesPattern(pattern, topic) {
+  if (!pattern || !topic) return false;
+  if (pattern === topic) return true;
+  if (pattern === "*") return true;
+  if (!pattern.endsWith(".*")) return false;
+  return topic.startsWith(pattern.slice(0, -1));
+}
+
+// src/core/storage-batch.ts
+var INITIAL_RETRY_DELAY_MS = 50;
+var MAX_RETRY_DELAY_MS = 1600;
+var MAX_RETRY_ATTEMPTS = 5;
+var BatchingStorageWriter = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /** Coalesced write set. A `null` value represents a pending delete. */
+  pending = /* @__PURE__ */ new Map();
+  /** Per-key retry counter, reset on a successful write. */
+  retryCount = /* @__PURE__ */ new Map();
+  flushScheduled = false;
+  retryHandle = null;
+  retryDelayMs = INITIAL_RETRY_DELAY_MS;
+  /** Number of writes queued in memory but not yet flushed to storage.
+   * Used by tests to assert the coalescing window and by flush() to detect
+   * the all-drained state. */
+  get pendingSize() {
+    return this.pending.size;
+  }
+  get length() {
+    return this.keys().length;
+  }
+  clear() {
+    this.pending.clear();
+    this.flushScheduled = false;
+    this.storage.clear();
+    this.cancelRetry();
+    this.retryCount.clear();
+    this.retryDelayMs = INITIAL_RETRY_DELAY_MS;
+  }
+  // Reads always see the pending value first (task-local consistency), then
+  // fall back to the underlying storage.
+  getItem(key) {
+    if (this.pending.has(key)) return this.pending.get(key) ?? null;
+    return this.storage.getItem(key);
+  }
+  key(index) {
+    return this.keys()[index] ?? null;
+  }
+  removeItem(key) {
+    this.pending.set(key, null);
+    this.scheduleFlush();
+  }
+  setItem(key, value) {
+    this.pending.set(key, value);
+    this.scheduleFlush();
+  }
+  flush() {
+    this.flushScheduled = false;
+    this.cancelRetry();
+    for (const [key, value] of Array.from(this.pending)) {
+      try {
+        if (value === null) this.storage.removeItem(key);
+        else this.storage.setItem(key, value);
+        this.pending.delete(key);
+        this.retryCount.delete(key);
+      } catch {
+        const attempts = (this.retryCount.get(key) ?? 0) + 1;
+        if (attempts >= MAX_RETRY_ATTEMPTS) {
+          this.pending.delete(key);
+          this.retryCount.delete(key);
+          if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn("[cross-tab-worker-databus] storage write gave up after retries, dropping key:", key);
+          }
+          continue;
+        }
+        this.retryCount.set(key, attempts);
+        this.scheduleRetry();
+        break;
+      }
+    }
+    if (this.pending.size === 0) {
+      this.retryDelayMs = INITIAL_RETRY_DELAY_MS;
+      this.retryCount.clear();
+    }
+  }
+  /** Union of persisted keys and pending writes, minus pending deletes. */
+  keys() {
+    const keys = /* @__PURE__ */ new Set();
+    for (let index = 0; index < this.storage.length; index += 1) {
+      const key = this.storage.key(index);
+      if (key !== null) keys.add(key);
+    }
+    for (const [key, value] of this.pending) {
+      if (value === null) keys.delete(key);
+      else keys.add(key);
+    }
+    return Array.from(keys);
+  }
+  // Coalesce all synchronous writes within one task into a single microtask
+  // flush, avoiding a localStorage write per heartbeat/route/subscriber update.
+  // The queueMicrotask fallback to setTimeout handles older runtimes and
+  // non-browser environments where queueMicrotask is absent.
+  scheduleFlush() {
+    if (this.flushScheduled) return;
+    this.flushScheduled = true;
+    const flush = () => {
+      this.flushScheduled = false;
+      this.flush();
+    };
+    if (typeof queueMicrotask === "function") queueMicrotask(flush);
+    else setTimeout(flush, 0);
+  }
+  // Schedule a single retry timer. The guard ensures only one retry is in
+  // flight at a time; subsequent scheduleRetry calls during the wait are
+  // no-ops because the first retry will re-flush all pending keys together.
+  scheduleRetry() {
+    if (this.retryHandle !== null) return;
+    this.retryHandle = setTimeout(() => {
+      this.retryHandle = null;
+      this.flush();
+    }, this.retryDelayMs);
+    this.retryDelayMs = Math.min(MAX_RETRY_DELAY_MS, this.retryDelayMs * 2);
+  }
+  cancelRetry() {
+    if (this.retryHandle !== null) {
+      clearTimeout(this.retryHandle);
+      this.retryHandle = null;
+    }
+  }
+};
+
+// src/core/cluster.ts
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 3e3;
+var DEFAULT_WORKER_TTL_MS = 1e4;
+var DEFAULT_STORAGE_PREFIX = "cross-tab-worker-databus";
+var MAX_KNOWN_TOPICS = 500;
+function readJson(storage, key) {
+  try {
+    const value = storage.getItem(key);
+    return value ? JSON.parse(value) : null;
+  } catch {
+    return null;
+  }
+}
+function writeJson(storage, key, value) {
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function listKeys(storage, prefix) {
+  try {
+    return Array.from({ length: storage.length }, (_, index) => storage.key(index)).filter(
+      (key) => Boolean(key?.startsWith(prefix))
+    );
+  } catch {
+    return [];
+  }
+}
+function readAllByPrefix(storage, prefix) {
+  return listKeys(storage, prefix).map((key) => ({ key, value: readJson(storage, key) })).filter((entry) => entry.value !== null);
+}
+var WorkerClusterRuntime = class {
+  tabId;
+  workerId;
+  environment;
+  handlers;
+  storage;
+  maxActiveWorkers;
+  heartbeatIntervalMs;
+  workerTtlMs;
+  workerPrefix;
+  routePrefix;
+  subscriberPrefix;
+  channelName;
+  // Topics this tab has subscribed to (local interest, plaintext).
+  subscribedTopics = /* @__PURE__ */ new Set();
+  // Topics assigned to this Worker as owner (topicKey → topic). Authoritative:
+  // membership drives isAssigned() and load. Grows only via CONTROL/SUBSCRIBE
+  // (or local self-subscribe), never via the reverse cache.
+  assignedTopics = /* @__PURE__ */ new Map();
+  // Reverse mapping: opaque topicKey → plaintext topic. A bounded cache with
+  // FIFO eviction — NOT authoritative. It can hold a topicKey that is also in
+  // assignedTopics (the owned guard prevents evicting those), because it is
+  // the only source of plaintext when storage is unavailable. See the
+  // rememberTopic() doc for the eviction contract.
+  knownTopics = /* @__PURE__ */ new Map();
+  channel = null;
+  heartbeatHandle = null;
+  started = false;
+  suspended = false;
+  lifecycleListening = false;
+  currentRecord;
+  constructor(options) {
+    this.environment = options.environment ?? createBrowserEnvironment();
+    this.handlers = options.handlers;
+    this.maxActiveWorkers = options.maxActiveWorkers ?? DEFAULT_MAX_ACTIVE_WORKERS;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.workerTtlMs = options.workerTtlMs ?? DEFAULT_WORKER_TTL_MS;
+    const clusterHash = createOpaqueKey(options.clusterKey || "__default__");
+    const prefix = options.storagePrefix ?? DEFAULT_STORAGE_PREFIX;
+    const baseKey = `${prefix}:${clusterHash}`;
+    this.workerPrefix = `${baseKey}:worker:`;
+    this.routePrefix = `${baseKey}:route:`;
+    this.subscriberPrefix = `${baseKey}:subscriber:`;
+    this.channelName = `${prefix}:bus:${clusterHash}`;
+    this.storage = canUseStorage(this.environment.storage, `${baseKey}:probe`) ? new BatchingStorageWriter(this.environment.storage) : null;
+    this.tabId = options.tabId ?? getOrCreateTabId(this.environment, `${prefix}:tab-id`);
+    this.workerId = options.workerId ?? `worker-${this.tabId}-${this.environment.randomId()}`;
+    const now = this.environment.now();
+    this.currentRecord = {
+      workerId: this.workerId,
+      tabId: this.tabId,
+      load: 0,
+      role: "standby",
+      status: "connecting",
+      visibilityState: this.environment.getVisibilityState(),
+      heartbeatAt: now,
+      registeredAt: now
+    };
+  }
+  /** Start the cluster: register, listen for lifecycle events, and begin heartbeats. */
+  start() {
+    if (this.started) return;
+    this.suspended = false;
+    this.addLifecycleListeners();
+    this.activate();
+  }
+  /**
+   * Stop the cluster: pause heartbeats, hand off assigned topics, remove
+   * the worker record, and clean up lifecycle listeners. Idempotent.
+   * The .clear() calls after pause() are safe no-ops when pause already
+   * cleared the maps (the handoff path), but ensure a full teardown in the
+   * stop() path where callers expect every Set/Map to be empty afterwards.
+   */
+  stop() {
+    if (!this.started && !this.suspended) return;
+    this.pause();
+    this.flushStorage();
+    this.removeLifecycleListeners();
+    this.subscribedTopics.clear();
+    this.assignedTopics.clear();
+    this.knownTopics.clear();
+    this.suspended = false;
+  }
+  /**
+   * Activate the cluster: open the BroadcastChannel, register the worker record,
+   * subscribe to topics, and start the heartbeat interval.
+   */
+  activate() {
+    if (this.started) return;
+    this.started = true;
+    this.channel = this.storage ? this.environment.createChannel(this.channelName) : null;
+    if (!this.channel) this.storage = null;
+    this.channel?.addEventListener("message", this.handleMessage);
+    const now = this.environment.now();
+    this.currentRecord = {
+      ...this.currentRecord,
+      heartbeatAt: now,
+      registeredAt: now,
+      visibilityState: this.environment.getVisibilityState()
+    };
+    this.refreshRole(this.readWorkers());
+    this.writeRecord(true);
+    for (const topic of this.subscribedTopics) {
+      const topicKey = this.rememberTopic(topic);
+      if (!this.storage) this.sendControl(this.workerId, "SUBSCRIBE", topic, topicKey);
+      else this.writeSubscriber(topicKey);
+    }
+    this.reconcile();
+    this.heartbeatHandle = this.environment.setInterval(() => {
+      this.writeRecord(false);
+      this.reconcile();
+    }, this.heartbeatIntervalMs);
+  }
+  /**
+   * Pause the cluster on pagehide: stop heartbeats, hand off assigned topics
+   * to other workers, remove our worker record, and close the channel.
+   */
+  pause() {
+    if (!this.started) return;
+    this.started = false;
+    this.suspended = true;
+    if (this.heartbeatHandle !== null) this.environment.clearInterval(this.heartbeatHandle);
+    this.heartbeatHandle = null;
+    this.channel?.removeEventListener("message", this.handleMessage);
+    for (const topic of this.subscribedTopics) this.releaseSubscription(topic, false);
+    this.handoffAssignedTopics();
+    this.assignedTopics.clear();
+    this.removeStorage(this.workerStorageKey(this.workerId));
+    this.flushStorage();
+    this.notifyRegistry();
+    this.channel?.close();
+    this.channel = null;
+    this.handlers.onSuspend?.();
+  }
+  /** Update the worker's connection status and persist the change. */
+  setStatus(status) {
+    if (this.currentRecord.status === status) return;
+    this.currentRecord = { ...this.currentRecord, status };
+    if (this.started) this.writeRecord(true);
+  }
+  /**
+   * Subscribe to a topic. Returns true if this worker becomes the assigned owner.
+   * The topic is recorded locally and the cluster is notified via storage or
+   * direct control message.
+   */
+  subscribe(topic) {
+    const topicKey = this.rememberTopic(topic);
+    this.subscribedTopics.add(topic);
+    if (!this.started) return false;
+    if (!this.storage) {
+      this.sendControl(this.workerId, "SUBSCRIBE", topic, topicKey);
+      return true;
+    }
+    this.writeSubscriber(topicKey);
+    const workers = this.readWorkers();
+    const existingRoute = this.readRoute(topicKey);
+    if (this.routeOwnerIsLive(existingRoute, workers)) {
+      return existingRoute?.workerId === this.workerId;
+    }
+    const activeWorkers = selectActiveWorkers(workers, this.maxActiveWorkers);
+    const owner = selectLeastLoadedWorker(activeWorkers) ?? this.currentRecord;
+    this.writeRoute(topicKey, owner, void 0, (existingRoute?.generation ?? 0) + 1);
+    this.sendControl(owner.workerId, "SUBSCRIBE", topic, topicKey);
+    this.notifyRegistry();
+    return owner.workerId === this.workerId;
+  }
+  /**
+   * Remove the local subscription. Cleans up the subscriber record and, if no
+   * subscribers remain, deletes the route so the owning Worker can unsubscribe.
+   */
+  unsubscribe(topic) {
+    this.subscribedTopics.delete(topic);
+    const topicKey = this.releaseSubscription(topic);
+    if (topicKey && !this.assignedTopics.has(topicKey)) this.knownTopics.delete(topicKey);
+  }
+  /** Remove this tab's subscriber record and, when it was the last one, delete
+   * the route. Returns the topicKey (so callers like `unsubscribe` can reuse
+   * it instead of re-hashing the topic to evict the reverse cache). */
+  releaseSubscription(topic, notifyOwner = true) {
+    const topicKey = this.rememberTopic(topic);
+    this.removeStorage(this.subscriberStorageKey(topicKey, this.tabId));
+    const route = this.readRoute(topicKey);
+    if (!route) return topicKey;
+    const subscribers = this.readSubscriberTabIds(topicKey, this.readWorkers());
+    if (subscribers.length === 0) {
+      this.removeStorage(this.routeStorageKey(topicKey));
+      if (notifyOwner) this.sendControl(route.workerId, "UNSUBSCRIBE", topic, topicKey);
+    }
+    return topicKey;
+  }
+  /** Transfer assigned topics to other active workers so subscribers are not orphaned during pause. */
+  handoffAssignedTopics() {
+    if (!this.storage || this.assignedTopics.size === 0) return;
+    const remainingWorkers = this.readWorkers().filter((worker) => worker.workerId !== this.workerId);
+    const activeWorkers = selectActiveWorkers(remainingWorkers, this.maxActiveWorkers);
+    const projectedLoads = new Map(activeWorkers.map((worker) => [worker.workerId, worker.load]));
+    for (const [topicKey, topic] of this.assignedTopics) {
+      const previous = this.readRoute(topicKey);
+      if (previous?.workerId !== this.workerId) continue;
+      const subscribers = this.readSubscriberTabIds(topicKey, remainingWorkers);
+      if (subscribers.length === 0) {
+        this.removeStorage(this.routeStorageKey(topicKey));
+        continue;
+      }
+      const owner = selectLeastLoadedWorker(
+        activeWorkers.map((worker) => ({ ...worker, load: projectedLoads.get(worker.workerId) ?? worker.load }))
+      );
+      if (!owner) continue;
+      projectedLoads.set(owner.workerId, (projectedLoads.get(owner.workerId) ?? owner.load) + 1);
+      const generation = (previous?.generation ?? 0) + 1;
+      this.writeRoute(topicKey, owner, previous?.workerId, generation);
+      this.flushStorage();
+      this.handlers.onControl("UNSUBSCRIBE", topic);
+      this.sendRouteReleased(owner.workerId, topic, topicKey, generation);
+    }
+  }
+  /**
+   * Publish a message to `topic`, routing through the owning Worker (or self if
+   * no owner is found). Returns false when the control message could not be
+   * posted to a remote owner, so the caller can surface the failure instead of
+   * silently dropping the publication.
+   */
+  publish(topic, data) {
+    const topicKey = this.rememberTopic(topic);
+    const workers = this.readWorkers();
+    const route = this.readRoute(topicKey);
+    const target = this.routeOwnerIsLive(route, workers) ? route?.workerId ?? this.workerId : this.workerId;
+    return this.sendControl(target, "PUBLISH", topic, topicKey, data);
+  }
+  /** True when `route` exists and its owner worker is among `workers`.
+   * Shared by subscribe (skip re-assignment) and publish (route to owner).
+   * Intentionally returns a plain boolean (not a type guard) so the caller
+   * can still access `route?.generation` in the false branch. */
+  routeOwnerIsLive(route, workers) {
+    return Boolean(route && workers.some((worker) => worker.workerId === route.workerId));
+  }
+  /** Broadcast an event to every tab — used to fan out transport publications. */
+  broadcastEvent(eventType, payload) {
+    this.send({ type: "EVENT", sourceWorkerId: this.workerId, eventType, payload });
+  }
+  isAssigned(topic) {
+    const topicKey = createOpaqueKey(topic);
+    if (this.assignedTopics.has(topicKey)) return true;
+    for (const pattern of this.assignedTopics.values()) {
+      if (pattern !== topic && topicMatchesPattern(pattern, topic)) return true;
+    }
+    return this.readRoute(topicKey)?.workerId === this.workerId;
+  }
+  /** True if this worker is among the active set (eligible to own topics). */
+  isActiveWorker() {
+    return this.isActiveAmong(this.readWorkers());
+  }
+  /** True when this workerId is in the active subset of `workers`. Shared by
+   * isActiveWorker() and refreshRole() so both compute role identically. */
+  isActiveAmong(workers) {
+    return selectActiveWorkers(workers, this.maxActiveWorkers).some(
+      (worker) => worker.workerId === this.workerId
+    );
+  }
+  /** True when this tab has a local subscriber registered for `topic` —
+   * exactly, or via a wildcard subscription that matches it. */
+  hasLocalSubscriber(topic) {
+    if (this.subscribedTopics.has(topic)) return true;
+    for (const pattern of this.subscribedTopics) {
+      if (pattern !== topic && topicMatchesPattern(pattern, topic)) return true;
+    }
+    return false;
+  }
+  /** Read-only snapshot of the cluster state (workers, routes, assignments). */
+  getSnapshot() {
+    const routes = this.storage ? readAllByPrefix(this.storage, this.routePrefix).map(({ value }) => ({
+      ...value,
+      topic: this.knownTopics.get(value.topicKey) ?? null
+    })) : [];
+    return {
+      coordinated: Boolean(this.storage && this.channel),
+      suspended: this.suspended,
+      currentWorker: { ...this.currentRecord },
+      workers: this.readWorkers().map((worker) => ({ ...worker })),
+      routes,
+      subscribedTopics: Array.from(this.subscribedTopics),
+      assignedTopics: Array.from(this.assignedTopics.values()),
+      knownTopics: Array.from(this.knownTopics.entries(), ([topicKey, topic]) => ({ topicKey, topic }))
+    };
+  }
+  handlePageHide = () => this.pause();
+  handlePageShow = () => {
+    if (!this.suspended) return;
+    this.suspended = false;
+    this.handlers.onResume?.();
+    this.activate();
+  };
+  handleVisibilityChange = () => {
+    const visibilityState = this.environment.getVisibilityState();
+    if (visibilityState === this.currentRecord.visibilityState) return;
+    this.currentRecord = { ...this.currentRecord, visibilityState };
+    if (this.started) {
+      this.writeRecord(true);
+      this.reconcile();
+    }
+  };
+  addLifecycleListeners() {
+    if (this.lifecycleListening) return;
+    this.lifecycleListening = true;
+    this.environment.addPageHideListener(this.handlePageHide);
+    this.environment.addPageShowListener(this.handlePageShow);
+    this.environment.addVisibilityChangeListener(this.handleVisibilityChange);
+  }
+  removeLifecycleListeners() {
+    if (!this.lifecycleListening) return;
+    this.lifecycleListening = false;
+    this.environment.removePageHideListener(this.handlePageHide);
+    this.environment.removePageShowListener(this.handlePageShow);
+    this.environment.removeVisibilityChangeListener(this.handleVisibilityChange);
+  }
+  /** Handle an incoming cluster message: dispatch by type to the per-type handlers. */
+  handleMessage = (event) => {
+    const message = event.data;
+    if (!message || message.sourceWorkerId === this.workerId) return;
+    switch (message.type) {
+      case "CONTROL":
+        return this.handleControlMessage(message);
+      case "ROUTE_RELEASED":
+        return this.handleRouteReleasedMessage(message);
+      case "EVENT":
+        this.handlers.onEvent(message.eventType, message.payload, message.sourceWorkerId);
+        return;
+      case "REGISTRY":
+      default:
+        this.reconcile();
+        return;
+    }
+  };
+  /** Handle a point-to-point CONTROL message (SUBSCRIBE / UNSUBSCRIBE / PUBLISH). */
+  handleControlMessage(message) {
+    if (message.targetWorkerId !== this.workerId) return;
+    this.rememberTopic(message.topic);
+    switch (message.action) {
+      case "SUBSCRIBE":
+        this.assignedTopics.set(message.topicKey, message.topic);
+        this.confirmRoute(message.topicKey);
+        break;
+      case "UNSUBSCRIBE":
+        if (this.releaseHandoffOnUnsubscribe(message)) return;
+        break;
+      case "PUBLISH":
+      default:
+        break;
+    }
+    this.handlers.onControl(message.action, message.topic, message.data);
+    if (message.action !== "PUBLISH") this.updateLoad();
+  }
+  /**
+   * When this worker is the previous owner in a graceful handoff and the new
+   * owner asks us to unsubscribe, release the old transport subscription and
+   * ACK the handoff with ROUTE_RELEASED. Returns true when the message was a
+   * handoff release (the generic CONTROL dispatch must not run as well).
+   */
+  releaseHandoffOnUnsubscribe(message) {
+    this.assignedTopics.delete(message.topicKey);
+    const route = this.readRoute(message.topicKey);
+    if (route?.handoffFromWorkerId !== this.workerId) return false;
+    this.handlers.onControl("UNSUBSCRIBE", message.topic, void 0);
+    this.sendRouteReleased(route.workerId, message.topic, message.topicKey, route.generation);
+    this.updateLoad();
+    return true;
+  }
+  /** Post a ROUTE_RELEASED ACK to the new owner, carrying the current route
+   * generation so only the matching new owner may act on it. */
+  sendRouteReleased(targetWorkerId, topic, topicKey, generation) {
+    this.send({
+      type: "ROUTE_RELEASED",
+      sourceWorkerId: this.workerId,
+      targetWorkerId,
+      topic,
+      topicKey,
+      generation
+    });
+  }
+  /**
+   * 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.
+   */
+  handleRouteReleasedMessage(message) {
+    if (message.targetWorkerId !== this.workerId) return;
+    const route = this.readRoute(message.topicKey);
+    if (!route || this.isStaleRouteRelease(route, message)) return;
+    this.assignedTopics.set(message.topicKey, message.topic);
+    this.confirmRoute(message.topicKey);
+    this.handlers.onControl("SUBSCRIBE", message.topic, void 0);
+    this.updateLoad();
+  }
+  /** 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. */
+  isStaleRouteRelease(route, message) {
+    return route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || route.generation < message.generation;
+  }
+  /** Full reconciliation cycle: workers, subscriptions, and assigned topics. */
+  reconcile() {
+    if (!this.started) return;
+    const workers = this.reconcileWorkers();
+    const activeWorkers = selectActiveWorkers(workers, this.maxActiveWorkers);
+    this.reconcileSubscriptions(workers, activeWorkers);
+    this.reconcileAssignedTopics();
+    this.updateLoad();
+  }
+  /** Prune stale workers/subscribers/routes and refresh role. Returns the live worker list.
+   * Subscribers are cleaned before routes so cleanupOrphanedRoutes sees the
+   * updated subscriber set when deciding whether a route is truly orphaned. */
+  reconcileWorkers() {
+    const workers = this.readWorkers();
+    this.cleanupOrphanedSubscribers(workers);
+    this.cleanupOrphanedRoutes(workers);
+    const roleChanged = this.refreshRole(workers);
+    if (roleChanged) this.writeRecord(false);
+    return workers;
+  }
+  /**
+   * Ensure every local subscription has a route and write subscriber records.
+   *
+   * Existing routes are deliberately sticky while their owner Worker is alive.
+   * Load and visibility only influence placement of a new route; they must not
+   * move an already-subscribed Topic merely because another Tab joins or becomes
+   * visible. Ownership changes only after the owner leaves or its heartbeat
+   * expires, which avoids unnecessary transport subscribe/unsubscribe churn.
+   */
+  reconcileSubscriptions(workers, activeWorkers) {
+    const liveWorkerIds = new Set(workers.map((worker) => worker.workerId));
+    for (const topic of this.subscribedTopics) {
+      const topicKey = this.rememberTopic(topic);
+      this.writeSubscriber(topicKey);
+      const route = this.readRoute(topicKey);
+      if (!route || !liveWorkerIds.has(route.workerId)) {
+        const owner = selectLeastLoadedWorker(activeWorkers) ?? this.currentRecord;
+        this.writeRoute(topicKey, owner, void 0, (route?.generation ?? 0) + 1);
+        this.sendControl(owner.workerId, "SUBSCRIBE", topic, topicKey);
+        this.notifyRegistry();
+        continue;
+      }
+      if (route.confirmedAt === void 0) {
+        if (!route.handoffFromWorkerId) {
+          this.sendControl(route.workerId, "SUBSCRIBE", topic, topicKey);
+        }
+      }
+    }
+  }
+  /** Drop assignments where the route no longer points to this worker. */
+  reconcileAssignedTopics() {
+    for (const [topicKey, topic] of [...this.assignedTopics]) {
+      const route = this.readRoute(topicKey);
+      if (route?.workerId === this.workerId) continue;
+      this.assignedTopics.delete(topicKey);
+      this.handlers.onControl("UNSUBSCRIBE", topic, void 0);
+      if (route?.handoffFromWorkerId === this.workerId) {
+        this.sendRouteReleased(route.workerId, topic, topicKey, route.generation);
+      }
+      if (!this.subscribedTopics.has(topic)) this.knownTopics.delete(topicKey);
+    }
+  }
+  /**
+   * Send a control message to `targetWorkerId`, or execute locally when targeting self.
+   * Local execution updates the assignment map and route synchronously, bypassing
+   * the BroadcastChannel latency.
+   */
+  sendControl(targetWorkerId, action, topic, topicKey, data) {
+    if (targetWorkerId === this.workerId) {
+      switch (action) {
+        case "SUBSCRIBE":
+          this.assignedTopics.set(topicKey, topic);
+          this.confirmRoute(topicKey);
+          break;
+        case "UNSUBSCRIBE":
+          this.assignedTopics.delete(topicKey);
+          break;
+        case "PUBLISH":
+        default:
+          break;
+      }
+      this.handlers.onControl(action, topic, data);
+      if (action !== "PUBLISH") this.updateLoad();
+      return true;
+    }
+    return this.send({
+      type: "CONTROL",
+      sourceWorkerId: this.workerId,
+      targetWorkerId,
+      action,
+      topic,
+      topicKey,
+      ...data === void 0 ? {} : { data }
+    });
+  }
+  /** Post a message on the BroadcastChannel. Returns false on postMessage failure. */
+  send(message) {
+    if (!this.channel) return false;
+    try {
+      this.channel.postMessage(message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Read all live worker records from storage, pruning stale entries past the TTL. */
+  readWorkers() {
+    if (!this.storage) return [this.currentRecord];
+    const now = this.environment.now();
+    const workers = [];
+    for (const { key, value: worker } of readAllByPrefix(this.storage, this.workerPrefix)) {
+      if (worker.workerId !== this.workerId && now - worker.heartbeatAt > this.workerTtlMs) {
+        this.removeStorage(key);
+        continue;
+      }
+      workers.push(worker);
+    }
+    if (this.started && !workers.some((worker) => worker.workerId === this.workerId)) workers.push(this.currentRecord);
+    return workers;
+  }
+  /** Enumerate all tab IDs that have a subscriber record for `topicKey`. */
+  readSubscriberTabIds(topicKey, workers) {
+    if (!this.storage) {
+      const topic = this.knownTopics.get(topicKey);
+      return topic && this.subscribedTopics.has(topic) ? [this.tabId] : [];
+    }
+    const activeTabIds = new Set(workers.map((worker) => worker.tabId));
+    const subscribers = /* @__PURE__ */ new Set();
+    for (const { key, value: record } of readAllByPrefix(
+      this.storage,
+      `${this.subscriberPrefix}${topicKey}:`
+    )) {
+      if (!activeTabIds.has(record.tabId)) {
+        this.removeStorage(key);
+        continue;
+      }
+      subscribers.add(record.tabId);
+    }
+    return Array.from(subscribers);
+  }
+  /** Read the current route for `topicKey`, returning null when no storage layer exists. */
+  readRoute(topicKey) {
+    if (!this.storage) return this.buildLocalRoute(topicKey);
+    return readJson(this.storage, this.routeStorageKey(topicKey));
+  }
+  /** Synthesize a self-owned route when storage is unavailable (degraded mode).
+   * The plaintext topic must be recoverable from the knownTopics cache; a
+   * missing entry means we never subscribed to or were assigned the topic,
+   * so there is no route to report. */
+  buildLocalRoute(topicKey) {
+    const topic = this.knownTopics.get(topicKey);
+    if (!topic) return null;
+    if (!this.subscribedTopics.has(topic) && !this.assignedTopics.has(topicKey)) return null;
+    return {
+      topicKey,
+      workerId: this.workerId,
+      tabId: this.tabId,
+      updatedAt: this.environment.now(),
+      generation: 1
+    };
+  }
+  /** Persist a route assignment, mapping `topicKey` to the owning Worker. */
+  writeRoute(topicKey, owner, handoffFromWorkerId, generation = 1) {
+    if (!this.storage) return;
+    writeJson(this.storage, this.routeStorageKey(topicKey), this.buildRouteRecord(topicKey, owner, handoffFromWorkerId, generation));
+  }
+  /** Construct a WorkerRoute record from the owner + handoff fields. Extracted
+   * so writeRoute and confirmRoute share the same shape; confirmedAt is added
+   * by confirmRoute via spread. */
+  buildRouteRecord(topicKey, owner, handoffFromWorkerId, generation) {
+    return {
+      topicKey,
+      workerId: owner.workerId,
+      tabId: owner.tabId,
+      updatedAt: this.environment.now(),
+      generation,
+      ...handoffFromWorkerId ? { handoffFromWorkerId } : {}
+    };
+  }
+  /** Stamp a route as confirmed once the owning Worker has acknowledged the assignment. */
+  confirmRoute(topicKey) {
+    if (!this.storage) return;
+    const route = this.readRoute(topicKey);
+    if (!route || route.workerId !== this.workerId || route.confirmedAt !== void 0) return;
+    writeJson(this.storage, this.routeStorageKey(topicKey), {
+      ...route,
+      confirmedAt: this.environment.now()
+    });
+  }
+  /** Remove routes whose topic has no subscribers and whose TTL has expired. */
+  cleanupOrphanedRoutes(workers) {
+    if (!this.storage) return;
+    const now = this.environment.now();
+    for (const { key, value: route } of readAllByPrefix(this.storage, this.routePrefix)) {
+      if (now - route.updatedAt <= this.workerTtlMs) continue;
+      if (this.readSubscriberTabIds(route.topicKey, workers).length > 0) continue;
+      this.removeStorage(key);
+    }
+  }
+  /** Remove subscriber records for tabs that are no longer active. */
+  cleanupOrphanedSubscribers(workers) {
+    if (!this.storage) return;
+    const activeTabIds = new Set(workers.map((worker) => worker.tabId));
+    for (const { key, value: record } of readAllByPrefix(this.storage, this.subscriberPrefix)) {
+      if (!activeTabIds.has(record.tabId)) this.removeStorage(key);
+    }
+  }
+  /** Persist a subscriber record for this tab on `topicKey`. */
+  writeSubscriber(topicKey) {
+    if (!this.storage) return;
+    writeJson(this.storage, this.subscriberStorageKey(topicKey, this.tabId), {
+      tabId: this.tabId,
+      updatedAt: this.environment.now()
+    });
+  }
+  /** Persist the current worker record with an updated heartbeat timestamp.
+   * @param notify — when true, broadcast a REGISTRY nudge so peers reconcile
+   *   immediately instead of waiting for the next heartbeat. False on the
+   *   periodic heartbeat tick (peers will notice on their own heartbeat) to
+   *   avoid a REGISTRY storm every 3 s; true on status/role changes that
+   *   peers should observe promptly. */
+  writeRecord(notify) {
+    this.currentRecord = { ...this.currentRecord, heartbeatAt: this.environment.now() };
+    if (this.storage) writeJson(this.storage, this.workerStorageKey(this.workerId), this.currentRecord);
+    if (notify) this.notifyRegistry();
+  }
+  /** Broadcast a REGISTRY message to trigger reconciliation on other tabs. */
+  notifyRegistry() {
+    this.send({ type: "REGISTRY", sourceWorkerId: this.workerId });
+  }
+  /** Recompute whether this worker is active (eligible to own topics) or standby. Returns true when changed. */
+  refreshRole(workers) {
+    const role = this.isActiveAmong(workers) ? "active" : "standby";
+    if (role === this.currentRecord.role) return false;
+    this.currentRecord = { ...this.currentRecord, role };
+    return true;
+  }
+  /** Persist the current topic load count (number of assigned topics) for load-balanced routing. */
+  updateLoad() {
+    const load = this.assignedTopics.size;
+    if (load === this.currentRecord.load) return;
+    this.currentRecord = { ...this.currentRecord, load };
+    if (this.started) this.writeRecord(true);
+  }
+  /**
+   * Hash `topic` into its opaque key and populate the reverse-lookup cache.
+   *
+   * Despite the name, this is NOT a cache lookup — it unconditionally writes
+   * the `topicKey → topic` pair. Hashing is cheap enough that a caller needing
+   * the key should always call this rather than check `knownTopics` first;
+   * the cache's FIFO eviction below keeps it bounded. Only `isAssigned`
+   * deliberately bypasses this (it must not pollute the cache on a read-only
+   * query), so if you add a new call site, prefer `rememberTopic` unless you
+   * have the same "read-only query" reason.
+   */
+  rememberTopic(topic) {
+    const topicKey = createOpaqueKey(topic);
+    this.knownTopics.set(topicKey, topic);
+    if (this.knownTopics.size > MAX_KNOWN_TOPICS) {
+      for (const candidate of this.knownTopics.keys()) {
+        if (candidate === topicKey || this.assignedTopics.has(candidate)) continue;
+        this.knownTopics.delete(candidate);
+        break;
+      }
+    }
+    return topicKey;
+  }
+  workerStorageKey(workerId) {
+    return `${this.workerPrefix}${workerId}`;
+  }
+  routeStorageKey(topicKey) {
+    return `${this.routePrefix}${topicKey}`;
+  }
+  subscriberStorageKey(topicKey, tabId) {
+    return `${this.subscriberPrefix}${topicKey}:${tabId}`;
+  }
+  removeStorage(key) {
+    try {
+      this.storage?.removeItem(key);
+    } catch {
+    }
+  }
+  /** Force-flush any pending batched writes (used during shutdown/teardown). */
+  flushStorage() {
+    if (this.storage instanceof BatchingStorageWriter) this.storage.flush();
+  }
+};
+
+// src/core/trace.ts
+var DEFAULT_METRICS_INTERVAL_MS = 5e3;
+var MAX_PENDING_TOPICS = 1e3;
+var MAX_PENDING_MESSAGES_PER_TOPIC = 256;
+var LATENCY_BUCKET_COUNT = 20;
+var LATENCY_BUCKET_SIZE_MS = 50;
+var DataBusTraceReporter = class {
+  enabled;
+  mode;
+  metricsIntervalMs;
+  sink;
+  now;
+  intervalHandle = null;
+  intervalStartedAt = 0;
+  received = 0;
+  dispatched = 0;
+  latencySamples = 0;
+  topics = /* @__PURE__ */ new Set();
+  // Per-topic FIFO of received timestamps, used to compute dispatch latency.
+  receivedAt = /* @__PURE__ */ new Map();
+  // Bucketed histogram: bucket index = floor(delayMs / 50), capped at 19.
+  latencyBuckets = new Array(LATENCY_BUCKET_COUNT).fill(0);
+  latencySumMs = 0;
+  constructor(options, now = Date.now) {
+    this.enabled = options?.enabled ?? false;
+    this.mode = options?.mode ?? "all";
+    this.metricsIntervalMs = normalizeInterval(options?.metricsIntervalMs);
+    this.sink = options?.sink ?? (() => void 0);
+    this.now = now;
+  }
+  /** Start the periodic metrics flush interval. No-op when mode is 'events'
+   * (no metrics to emit), when disabled, or when already running. */
+  start() {
+    if (!this.enabled || this.intervalHandle || this.mode === "events") return;
+    this.intervalStartedAt = this.now();
+    this.intervalHandle = setInterval(() => this.flush(), this.metricsIntervalMs);
+  }
+  /** Pause the metrics interval and reset accumulated counters. */
+  pause() {
+    if (this.intervalHandle) clearInterval(this.intervalHandle);
+    this.intervalHandle = null;
+    this.intervalStartedAt = 0;
+    this.resetMetrics();
+  }
+  stop() {
+    this.pause();
+  }
+  /** Record an instantaneous trace event (lifecycle, status, error, etc.). */
+  event(event) {
+    if (!this.enabled || this.mode === "metrics") return;
+    this.emit({ ...event, timestamp: this.now() });
+  }
+  /** Record that a message was received on `topic`; stores its timestamp for latency tracking. */
+  recordReceived(topic) {
+    if (!this.metricsActive) return;
+    this.received += 1;
+    this.topics.add(topic);
+    const queue = this.receivedAt.get(topic);
+    if (!queue) {
+      if (this.receivedAt.size >= MAX_PENDING_TOPICS) return;
+      this.receivedAt.set(topic, [this.now()]);
+      return;
+    }
+    if (queue.length >= MAX_PENDING_MESSAGES_PER_TOPIC) return;
+    queue.push(this.now());
+  }
+  /**
+   * Record that a received message will never be dispatched locally. Pops the
+   * matching FIFO slot so a later dispatch on the same topic does not pair
+   * with a stale receive timestamp.
+   */
+  recordDiscarded(topic) {
+    if (!this.metricsActive) return;
+    const queue = this.receivedAt.get(topic);
+    if (!queue) return;
+    queue.shift();
+    if (queue.length === 0) this.receivedAt.delete(topic);
+  }
+  /**
+   * Record that a message was dispatched on `topic`. Pops the oldest receive
+   * timestamp (FIFO) and increments the latency histogram. Dispatches without
+   * a matching receive (e.g. broadcast fan-out from another tab) still count
+   * as dispatched but do not produce a latency sample.
+   */
+  recordDispatched(topic) {
+    if (!this.metricsActive) return;
+    this.dispatched += 1;
+    this.topics.add(topic);
+    const queue = this.receivedAt.get(topic);
+    const receivedTimestamp = queue?.shift();
+    if (queue && queue.length === 0) this.receivedAt.delete(topic);
+    if (receivedTimestamp === void 0) return;
+    this.latencySamples += 1;
+    const delayMs = Math.max(0, this.now() - receivedTimestamp);
+    const bucketIndex = Math.min(LATENCY_BUCKET_COUNT - 1, Math.floor(delayMs / LATENCY_BUCKET_SIZE_MS));
+    this.latencyBuckets[bucketIndex] = (this.latencyBuckets[bucketIndex] ?? 0) + 1;
+    this.latencySumMs += delayMs;
+  }
+  /** True when metrics recording is active: enabled and mode includes metrics.
+   * Extracted so the four record / flush methods share one guard expression
+   * instead of repeating `!this.enabled || this.mode === 'events'` at each. */
+  get metricsActive() {
+    return this.enabled && this.mode !== "events";
+  }
+  /** Emit the accumulated metrics snapshot if the interval is active. */
+  flush() {
+    if (!this.metricsActive) return;
+    this.flushNow();
+  }
+  flushNow() {
+    const timestamp = this.now();
+    if (this.received > 0 || this.dispatched > 0) {
+      const samples = this.latencySamples;
+      this.emit({
+        type: "message_metrics",
+        durationMs: Math.max(0, timestamp - this.intervalStartedAt),
+        received: this.received,
+        dispatched: this.dispatched,
+        topics: this.topics.size,
+        dispatchSamples: samples,
+        dispatchAvgMs: roundMs(samples === 0 ? 0 : this.latencySumMs / samples),
+        // Percentiles are derived from the histogram, not sorted samples.
+        dispatchP50Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.5)),
+        dispatchP95Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.95)),
+        dispatchMaxMs: roundMs(percentileMs(this.latencyBuckets, samples, 1)),
+        timestamp
+      });
+      this.resetMetrics();
+    }
+    this.intervalStartedAt = timestamp;
+  }
+  resetMetrics() {
+    this.received = 0;
+    this.dispatched = 0;
+    this.latencySamples = 0;
+    this.topics.clear();
+    this.receivedAt.clear();
+    this.latencyBuckets.fill(0);
+    this.latencySumMs = 0;
+  }
+  emit(event) {
+    try {
+      this.sink(event);
+    } catch (error) {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn("[cross-tab-worker-databus] trace sink threw:", error);
+      }
+    }
+  }
+};
+function normalizeInterval(value) {
+  if (value === void 0) return DEFAULT_METRICS_INTERVAL_MS;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError("trace.metricsIntervalMs must be a positive finite number.");
+  }
+  return value;
+}
+function percentileMs(buckets, sampleCount, percentile) {
+  if (sampleCount <= 0) return 0;
+  const rank = Math.max(1, Math.ceil(percentile * sampleCount));
+  let seen = 0;
+  for (let index = 0; index < buckets.length; index += 1) {
+    seen += buckets[index] ?? 0;
+    if (seen >= rank) return (index + 0.5) * LATENCY_BUCKET_SIZE_MS;
+  }
+  return buckets.length * LATENCY_BUCKET_SIZE_MS;
+}
+function roundMs(value) {
+  return Math.round(value * 10) / 10;
+}
+
+// src/core/data-bus.ts
+var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
+var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
+var CrossTabDataBus = class _CrossTabDataBus {
+  transport;
+  cluster;
+  // Map of topic → set of local subscribers.
+  topicHandlers = /* @__PURE__ */ new Map();
+  // Topics for which the transport has been asked to subscribe (used to avoid
+  // duplicate subscribe calls during reconnection).
+  transportSubscribedTopics = /* @__PURE__ */ new Set();
+  statusHandlers = /* @__PURE__ */ new Set();
+  errorHandlers = /* @__PURE__ */ new Set();
+  // Bounded per-topic ring of recent dispatched publications. Null unless
+  // replay is enabled — buffering is opt-in and must cost nothing otherwise.
+  replayBuffers;
+  replayMaxPerTopic;
+  initialConfig;
+  hasInitialConfig;
+  trace;
+  activeConfig;
+  status = "disconnected";
+  started = false;
+  stopping = false;
+  transportReady = 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;
+  // Gate that serialises start/stop/suspend/resume — only one lifecycle
+  // transition at a time. Resets to null once the operation settles.
+  startPromise = null;
+  // Timestamp of the last automatic transport recovery attempt.
+  // Used to avoid a tight retry loop when the transport fails repeatedly.
+  lastRecoveryAt = 0;
+  // True while the tab is hidden so an in-flight transport start does not mark
+  // the transport ready after suspendTransport() has stopped it.
+  suspended = false;
+  // Single gate for async transport.stop() cleanup, shared by failed opens and
+  // page-hide suspension. Kept separate from startPromise so ready() still
+  // surfaces a failure while later opens and automatic recovery wait for the
+  // stop to settle.
+  pendingStop = null;
+  // Minimum interval in ms between automatic recovery attempts.
+  static RECOVERY_COOLDOWN_MS = 1e3;
+  constructor(options) {
+    const replay = options.replay;
+    if (replay) {
+      const maxPerTopic = replay.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
+      if (!Number.isSafeInteger(maxPerTopic) || maxPerTopic <= 0) {
+        throw new TypeError(
+          `replay.maxPerTopic must be a positive safe integer, got ${String(maxPerTopic)}.`
+        );
+      }
+    }
+    this.replayMaxPerTopic = replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
+    this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
+    const { autoStart, initialConfig, trace, transport, ...clusterOptions } = options;
+    this.transport = transport;
+    this.initialConfig = initialConfig;
+    this.hasInitialConfig = "initialConfig" in options;
+    this.trace = new DataBusTraceReporter(trace);
+    this.cluster = new WorkerClusterRuntime({
+      ...clusterOptions,
+      handlers: {
+        // The cluster calls `onControl` when it receives a SUBSCRIBE/UNSUBSCRIBE/PUBLISH
+        // control message — meaning the owning Worker has delegated the action to us.
+        onControl: (action, topic, data) => {
+          switch (action) {
+            case "SUBSCRIBE":
+              if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
+              break;
+            case "UNSUBSCRIBE":
+              if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
+              break;
+            case "PUBLISH":
+              this.runTransport(() => this.transport.publish(topic, data));
+              break;
+            default:
+              break;
+          }
+        },
+        // The cluster calls `onEvent` when a publication broadcast arrives from
+        // another tab. Dispatch locally if we have subscribers. The payload is
+        // typed `unknown` at the cluster boundary (the cluster is transport-
+        // agnostic); here we narrow it to DataBusMessage — the sender is our
+        // own broadcastEvent call, which always posts a DataBusMessage.
+        onEvent: (eventType, payload) => {
+          if (eventType !== PUBLICATION_EVENT) return;
+          const message = payload;
+          if (this.cluster.hasLocalSubscriber(message.topic)) this.dispatch(message);
+        },
+        onSuspend: () => {
+          if (!this.stopping) this.trace.event({ type: "lifecycle", action: "suspend" });
+          this.trace.pause();
+          this.suspendTransport();
+        },
+        onResume: () => {
+          this.trace.event({ type: "lifecycle", action: "resume" });
+          this.trace.start();
+          this.resumeTransport();
+        }
+      }
+    });
+    if (autoStart ?? this.hasInitialConfig) this.ensureStarted();
+  }
+  /**
+   * Start the DataBus with the given transport config.
+   *
+   * The first call starts the cluster and opens the transport. Concurrent calls
+   * during an in-flight start return the same promise. Once the operation
+   * settles (success or failure) the promise gate is cleared so a subsequent
+   * start() or resumeTransport() can open a fresh lifecycle.
+   */
+  start(config) {
+    if (this.startPromise) return this.startPromise;
+    if (this.started) return Promise.resolve();
+    this.started = true;
+    this.stopping = false;
+    this.suspended = false;
+    this.activeConfig = config;
+    this.lastError = null;
+    this.trace.event({ type: "lifecycle", action: "start" });
+    this.trace.start();
+    this.updateStatus("connecting");
+    this.cluster.start();
+    const opening = this.openTransport(config, this.pendingStop ?? Promise.resolve(), true);
+    this.startPromise = opening;
+    for (const topic of this.topicHandlers.keys()) {
+      this.cluster.subscribe(topic);
+    }
+    const snapshot = this.cluster.getSnapshot();
+    this.trace.event({
+      type: "coordination",
+      coordinated: snapshot.coordinated,
+      activeWorkers: snapshot.workers.filter((worker) => worker.role === "active").length,
+      workers: snapshot.workers.map(formatWorkerTrace),
+      routes: snapshot.routes.map(formatRouteTrace)
+    });
+    void opening.then(
+      () => {
+        if (this.startPromise === opening) this.startPromise = null;
+      },
+      () => {
+        if (this.startPromise === opening) this.startPromise = null;
+      }
+    );
+    return opening;
+  }
+  /**
+   * Open the transport, chained after `before` to ensure lifecycle ordering.
+   * When `stopClusterOnFailure` is true (initial start), a transport failure
+   * tears down the cluster as well.
+   */
+  openTransport(config, before, stopClusterOnFailure) {
+    this.transportReady = false;
+    const chainedPendingStop = this.pendingStop;
+    return before.catch(() => void 0).then(() => {
+      if (this.stopping || this.suspended) return;
+      if (this.pendingStop === chainedPendingStop) this.pendingStop = null;
+      return Promise.resolve(
+        this.transport.start(config, {
+          onMessage: (message) => this.handleTransportMessage(message),
+          onStatus: (status) => this.updateStatus(status),
+          onError: (error) => this.reportError(error)
+        })
+      ).then(() => {
+        if (this.status === "error") {
+          throw new Error("Transport failed during startup.");
+        }
+        if (!this.suspended && !this.stopping) this.transportReady = true;
+      });
+    }).catch((error) => {
+      if (stopClusterOnFailure) this.started = false;
+      if (!this.pendingStop) {
+        this.pendingStop = this.createStopPromise();
+      }
+      this.updateStatus("error");
+      this.reportError(error);
+      this.lastError = error;
+      this.transportReady = false;
+      if (stopClusterOnFailure) {
+        this.stopping = true;
+        this.cluster.stop();
+        this.stopping = false;
+      }
+      this.startPromise = null;
+      throw error;
+    });
+  }
+  /**
+   * Await the DataBus to be fully started (lazy init when using initialConfig).
+   * 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.
+   */
+  ready() {
+    try {
+      this.ensureStarted();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    if (this.startPromise) return this.startPromise;
+    if (this.transportReady) return Promise.resolve();
+    if (this.lastError !== null) return Promise.reject(this.lastError);
+    return Promise.reject(
+      new Error("Transport is not ready and no start operation is in flight")
+    );
+  }
+  /**
+   * Register a handler for `topic`. The handler fires on every publication
+   * delivered to this tab, regardless of which tab published it. Returns an
+   * unsubscribe function for convenience.
+   */
+  subscribe(topic, handler, options) {
+    this.ensureStarted();
+    const handlers = this.topicHandlers.get(topic) ?? /* @__PURE__ */ new Set();
+    const wasUnused = handlers.size === 0;
+    handlers.add(handler);
+    this.topicHandlers.set(topic, handlers);
+    if (wasUnused) this.cluster.subscribe(topic);
+    if (options?.replay) {
+      const limit = Math.min(
+        typeof options.replay === "number" ? Math.floor(options.replay) : this.replayMaxPerTopic,
+        this.replayMaxPerTopic
+      );
+      this.deliverReplay(topic, limit, handler);
+    }
+    return () => this.unsubscribe(topic, handler);
+  }
+  /** Remove a specific handler, or all handlers for `topic`.
+   * When `handler` is omitted, clears every handler for the topic — the
+   * caller used the `unsubscribe(topic)` form expecting a full teardown.
+   * The cluster is only notified on the n→0 transition (handlers.size === 0). */
+  unsubscribe(topic, handler) {
+    const handlers = this.topicHandlers.get(topic);
+    if (!handlers) return;
+    if (handler) handlers.delete(handler);
+    else handlers.clear();
+    if (handlers.size > 0) return;
+    this.topicHandlers.delete(topic);
+    this.replayBuffers?.delete(topic);
+    this.cluster.unsubscribe(topic);
+  }
+  /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
+  publish(topic, data) {
+    this.ensureStarted();
+    if (!this.cluster.publish(topic, data)) {
+      this.reportError(
+        new Error("Failed to send the publish control message to the owning worker.")
+      );
+    }
+  }
+  /** Register a handler that fires on every transport status change. Immediately invoked with the current status. */
+  onStatus(handler) {
+    this.statusHandlers.add(handler);
+    try {
+      handler(this.status);
+    } catch (error) {
+      this.reportError(error);
+    }
+    return () => this.statusHandlers.delete(handler);
+  }
+  /** Register a handler for transport errors. */
+  onError(handler) {
+    this.errorHandlers.add(handler);
+    return () => this.errorHandlers.delete(handler);
+  }
+  /** Current transport connection status. */
+  getStatus() {
+    return this.status;
+  }
+  /** Snapshot of the cluster state (workers, routes, assignments).
+   * For diagnostics only — the returned object is a shallow copy but
+   * nested arrays are snapshots at call time. */
+  getClusterSnapshot() {
+    return this.cluster.getSnapshot();
+  }
+  /**
+   * Gracefully stop the DataBus: unsubscribe all topics, stop the cluster,
+   * and close the transport. Idempotent.
+   */
+  async stop() {
+    if (!this.started) return;
+    this.stopping = true;
+    this.trace.event({ type: "lifecycle", action: "stop" });
+    this.trace.stop();
+    this.topicHandlers.clear();
+    this.replayBuffers?.clear();
+    this.cluster.stop();
+    try {
+      await this.startPromise?.catch(() => void 0);
+      const pendingStop = this.pendingStop;
+      if (pendingStop) await pendingStop.catch(() => void 0);
+      else await this.transport.stop();
+    } finally {
+      this.transportSubscribedTopics.clear();
+      this.started = false;
+      this.stopping = false;
+      this.suspended = false;
+      this.transportReady = false;
+      this.startPromise = null;
+      this.pendingStop = null;
+      this.lastError = null;
+      this.activeConfig = void 0;
+      this.updateStatus("disconnected");
+    }
+  }
+  /**
+   * Incoming message from the transport.
+   * Records metrics, checks ownership via the cluster, broadcasts to other tabs,
+   * and dispatches locally.
+   */
+  handleTransportMessage(message) {
+    this.trace.recordReceived(message.topic);
+    if (!this.cluster.isAssigned(message.topic)) {
+      this.trace.recordDiscarded(message.topic);
+      return;
+    }
+    this.cluster.broadcastEvent(PUBLICATION_EVENT, message);
+    if (this.cluster.hasLocalSubscriber(message.topic)) {
+      this.dispatch(message);
+      return;
+    }
+    this.trace.recordDiscarded(message.topic);
+  }
+  /** 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"). */
+  dispatch(message) {
+    this.trace.recordDispatched(message.topic);
+    this.invokeHandlers(this.topicHandlers.get(message.topic) ?? [], (handler) => handler(message));
+    for (const [pattern, handlers] of this.topicHandlers) {
+      if (pattern !== message.topic && topicMatchesPattern(pattern, message.topic)) {
+        this.invokeHandlers(handlers, (handler) => handler(message));
+      }
+    }
+    this.recordReplay(message);
+  }
+  /** Append a dispatched publication to the topic's replay ring buffer.
+   * No-op when replay is disabled. */
+  recordReplay(message) {
+    if (!this.replayBuffers) return;
+    let buffer = this.replayBuffers.get(message.topic);
+    if (!buffer) {
+      buffer = [];
+      this.replayBuffers.set(message.topic, buffer);
+    }
+    buffer.push(message);
+    if (buffer.length > this.replayMaxPerTopic) buffer.shift();
+  }
+  /** Deliver buffered history to a newly-registered handler. For an exact
+   * topic this is that topic's ring; for a wildcard subscription every
+   * buffered topic matching the pattern contributes (in buffer insertion
+   * order). Replay deliveries are marked `replayed: true` and are not
+   * counted into trace metrics. */
+  deliverReplay(topic, limit, handler) {
+    if (!this.replayBuffers || limit <= 0) return;
+    const deliver = (buffer2) => {
+      for (const message of buffer2.slice(-limit)) {
+        this.invokeHandlers([handler], (h) => h({ ...message, replayed: true }));
+      }
+    };
+    if (isWildcardTopic(topic)) {
+      for (const [bufferedTopic, buffer2] of this.replayBuffers) {
+        if (topicMatchesPattern(topic, bufferedTopic)) deliver(buffer2);
+      }
+      return;
+    }
+    const buffer = this.replayBuffers.get(topic);
+    if (buffer) deliver(buffer);
+  }
+  /**
+   * Propagate a status change to the cluster, trace, and all registered
+   * status handlers. On reconnect, re-subscribe any topics assigned to us.
+   */
+  updateStatus(status) {
+    const previousStatus = this.status;
+    this.status = status;
+    if (previousStatus !== status) this.trace.event({ type: "status", status });
+    this.cluster.setStatus(status);
+    if (status === "disconnected" || status === "error") this.transportSubscribedTopics.clear();
+    if (status === "connected" && previousStatus !== "connected") {
+      for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
+    }
+    if (status === "error" && this.started && !this.stopping) {
+      const now = Date.now();
+      if (now - this.lastRecoveryAt >= _CrossTabDataBus.RECOVERY_COOLDOWN_MS) {
+        this.lastRecoveryAt = now;
+        setTimeout(() => {
+          if (this.stopping || !this.started || this.suspended) return;
+          if (this.status !== "error") return;
+          void this.reopenTransport();
+        }, _CrossTabDataBus.RECOVERY_COOLDOWN_MS);
+      }
+    }
+    this.invokeHandlers(this.statusHandlers, (handler) => handler(status));
+  }
+  reportError(error) {
+    this.trace.event({ type: "error", source: "transport" });
+    this.invokeHandlers(this.errorHandlers, (handler) => handler(error), "error handler");
+  }
+  traceSubscription(action, topic) {
+    this.trace.event({
+      type: "subscription",
+      action,
+      topic,
+      activeTopics: this.transportSubscribedTopics.size
+    });
+  }
+  /** Ask the transport to subscribe to a topic (idempotent). */
+  subscribeTransport(topic) {
+    if (this.transportSubscribedTopics.has(topic)) return false;
+    this.transportSubscribedTopics.add(topic);
+    this.runTransport(() => this.transport.subscribe(topic));
+    return true;
+  }
+  unsubscribeTransport(topic) {
+    if (!this.transportSubscribedTopics.delete(topic)) return false;
+    this.runTransport(() => this.transport.unsubscribe(topic));
+    return true;
+  }
+  /** Invoke `callback` for each item in `handlers`, isolating a throwing
+   * callback so the remaining ones still run. Dispatch/status handler failures
+   * are routed to `reportError` (which surfaces them to error subscribers);
+   * error-handler failures are logged to the console to avoid infinite
+   * recursion through reportError itself. */
+  invokeHandlers(handlers, callback, label = "dispatch") {
+    for (const handler of handlers) {
+      try {
+        callback(handler);
+      } catch (error) {
+        if (label === "error handler") {
+          if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn("[cross-tab-worker-databus] error handler threw:", error);
+          }
+        } else {
+          this.reportError(error);
+        }
+      }
+    }
+  }
+  /**
+   * Suspend the transport when the tab goes hidden. Stops the transport and
+   * clears subscription state so it will be re-established on resume.
+   */
+  suspendTransport() {
+    if (this.stopping) return;
+    this.suspended = true;
+    this.transportReady = false;
+    this.transportSubscribedTopics.clear();
+    this.updateStatus("disconnected");
+    if (this.pendingStop) return;
+    const pending = this.startPromise ?? Promise.resolve();
+    const stopping = pending.catch(() => void 0).then(() => this.transport.stop()).catch((error) => this.reportError(error));
+    this.startPromise = stopping;
+    this.pendingStop = stopping;
+  }
+  /** Create an immediate stop promise (no prior chain). Used by openTransport's
+   * failure path where there is no in-flight start to wait for. */
+  createStopPromise() {
+    return Promise.resolve().then(() => this.transport.stop()).catch((stopError) => this.reportError(stopError));
+  }
+  /**
+   * Resume the transport when the tab becomes visible again, or recover from a
+   * runtime transport failure. Re-opens the transport with the stored active
+   * config, chained after any pending operation so an async transport stop
+   * completes before the new start. Returns the opening promise.
+   */
+  resumeTransport() {
+    void this.reopenTransport();
+  }
+  /**
+   * Re-open the transport with the previously stored active config. Chains
+   * after any in-flight lifecycle operation (e.g. a suspend stop), swallowing
+   * its rejection so the reopen is not blocked. Returns the opening promise so
+   * callers can queue operations behind it.
+   */
+  reopenTransport() {
+    if (this.stopping || this.activeConfig === void 0) return Promise.resolve();
+    if (this.startPromise && this.startPromise !== this.pendingStop) return this.startPromise;
+    const config = this.activeConfig;
+    this.started = true;
+    this.suspended = false;
+    this.updateStatus("connecting");
+    const pending = this.startPromise ?? this.pendingStop ?? Promise.resolve();
+    const opening = pending.catch(() => void 0).then(() => this.openTransport(config, Promise.resolve(), false));
+    this.startPromise = opening;
+    void opening.then(
+      () => {
+        if (this.startPromise === opening) this.startPromise = null;
+      },
+      () => void 0
+    );
+    void opening.catch(() => void 0);
+    return opening;
+  }
+  /**
+   * Run a transport operation now if the transport is ready, otherwise queue
+   * it behind the start promise. This ensures subscribe/unsubscribe calls made
+   * during startup are not lost.
+   */
+  runTransport(operation) {
+    if (this.suspended) return;
+    if (this.transportReady && !this.stopping) {
+      try {
+        void Promise.resolve(operation()).catch((error) => this.reportError(error));
+      } catch (error) {
+        this.reportError(error);
+      }
+      return;
+    }
+    let ready = this.startPromise;
+    if (!ready && this.started && !this.stopping && this.activeConfig !== void 0) {
+      ready = this.reopenTransport();
+    }
+    if (!ready || this.stopping) return;
+    void ready.then(() => {
+      if (!this.started || this.stopping || this.suspended) return;
+      return operation();
+    }).catch((error) => this.reportError(error));
+  }
+  /**
+   * Ensure the DataBus is started, throwing if no initialConfig was provided.
+   * Called automatically by subscribe/publish/ready when autoStart is true.
+   */
+  ensureStarted() {
+    if (this.started) return;
+    if (!this.hasInitialConfig) {
+      throw new Error(
+        "CrossTabDataBus requires initialConfig for automatic startup, or an explicit start(config) call."
+      );
+    }
+    const starting = this.start(this.initialConfig);
+    void starting.catch(() => void 0);
+  }
+};
+function formatWorkerTrace(worker) {
+  return `${worker.workerId}|${worker.status}|load=${worker.load}|tab=${worker.tabId}`;
+}
+function formatRouteTrace(route) {
+  return `${route.topicKey}@${route.workerId}|confirmed=${route.confirmedAt !== void 0}`;
+}
+
+// src/centrifuge-session.ts
+var import_centrifuge = require("centrifuge");
+var CentrifugeSession = class {
+  constructor(sink) {
+    this.sink = sink;
+  }
+  client = null;
+  subscriptions = /* @__PURE__ */ new Map();
+  transferable = false;
+  /** Dispatch an incoming Worker message to the matching operation.
+   * Unknown message types are ignored rather than thrown, so a future protocol
+   * extension adding a new variant cannot crash an older session. */
+  handle(message) {
+    switch (message.type) {
+      case "INIT":
+        this.initialize(message.url, message.config, message.transferable === true);
+        return;
+      case "SUBSCRIBE":
+        this.subscribe(message.topic);
+        return;
+      case "UNSUBSCRIBE":
+        this.unsubscribe(message.topic);
+        return;
+      case "PUBLISH":
+      case "PUBLISH_BIN":
+        this.publish(message.topic, message.data);
+        return;
+      case "STOP":
+        this.stop();
+        return;
+      default:
+        return;
+    }
+  }
+  /** Create the Centrifuge client, wire up lifecycle listeners, and connect. */
+  initialize(url, config, transferable) {
+    if (this.client) return;
+    this.transferable = transferable;
+    const client = new import_centrifuge.Centrifuge(url, config);
+    this.client = client;
+    client.on("state", (context) => {
+      this.post({ type: "STATUS", status: normalizeStatus(context.newState) });
+    });
+    client.on("connected", () => this.post({ type: "STATUS", status: "connected" }));
+    client.on("disconnected", () => this.post({ type: "STATUS", status: "disconnected" }));
+    client.on("error", (context) => this.postError(context));
+    client.on("publication", (context) => {
+      const topic = context.channel || getPayloadTopic(context.data);
+      if (!topic || this.subscriptions.has(topic)) return;
+      this.postPublication(topic, context.data);
+    });
+    client.connect();
+  }
+  /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists.
+   * Listeners are only registered once per subscription object — a repeated
+   * SUBSCRIBE for an already-tracked topic skips the listener wiring entirely,
+   * avoiding the removeAllListeners + re-on churn on every duplicate message. */
+  subscribe(topic) {
+    if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
+    const existing = this.subscriptions.get(topic);
+    if (existing) {
+      existing.subscribe();
+      return;
+    }
+    let subscription = this.client.getSubscription(topic);
+    if (!subscription) subscription = this.client.newSubscription(topic);
+    subscription.removeAllListeners("publication");
+    subscription.removeAllListeners("error");
+    subscription.removeAllListeners("unsubscribed");
+    this.subscriptions.set(topic, subscription);
+    subscription.on("publication", (context) => {
+      this.postPublication(topic, context.data);
+    });
+    subscription.on("error", (context) => this.postError(context));
+    subscription.on("unsubscribed", () => this.subscriptions.delete(topic));
+    subscription.subscribe();
+  }
+  /** Unsubscribe from a Centrifuge channel and clean up the local reference.
+   * Listeners are removed before unsubscribing so a late `unsubscribed` event
+   * cannot delete a subscription that a subsequent `subscribe()` re-added. */
+  unsubscribe(topic) {
+    const subscription = this.subscriptions.get(topic) ?? this.client?.getSubscription(topic);
+    if (!subscription) return;
+    subscription.removeAllListeners("publication");
+    subscription.removeAllListeners("error");
+    subscription.removeAllListeners("unsubscribed");
+    this.subscriptions.delete(topic);
+    subscription.unsubscribe();
+  }
+  /** Publish a message to the Centrifuge channel. */
+  publish(topic, data) {
+    if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
+    void this.client.publish(topic, data).catch((error) => this.postError(error));
+  }
+  /** Forward a publication to the transport. Binary payloads take the
+   * zero-copy `MESSAGE_BIN` path when `transferable` is enabled; everything
+   * else is structured-cloned via `MESSAGE`. An empty topic means the
+   * publication carried no channel info and is silently dropped. */
+  postPublication(topic, data) {
+    if (!topic) return;
+    if (this.transferable && data instanceof ArrayBuffer) {
+      this.post({ type: "MESSAGE_BIN", topic, data }, [data]);
+      return;
+    }
+    this.post({ type: "MESSAGE", topic, data });
+  }
+  /** Disconnect the client and clear all subscriptions. */
+  stop() {
+    this.client?.disconnect();
+    this.subscriptions.clear();
+    this.client = null;
+    this.post({ type: "STATUS", status: "disconnected" });
+  }
+  /** Forward a message to the sink (the transport layer). */
+  post(message, transfer) {
+    this.sink.post(message, transfer);
+  }
+  /** Serialise and report an error. The Centrifuge client handles reconnection
+   * internally, so a transient error should not trigger a `STATUS: error` that
+   * would cause `selectActiveWorkers()` to exclude this worker from routing.
+   * Fatal errors are distinguished by the client eventually emitting
+   * `disconnected` without a subsequent `connected`. */
+  postError(error) {
+    this.post({ type: "ERROR", error: serializeError(error) });
+  }
+};
+function getPayloadTopic(data) {
+  if (!data || typeof data !== "object") return "";
+  const payload = data;
+  const push = payload.push;
+  const nested = typeof push === "object" && push !== null ? push.channel : void 0;
+  const topic = nested ?? payload.channel;
+  return typeof topic === "string" ? topic : "";
+}
+var LIVE_STATES = /* @__PURE__ */ new Set(["connecting", "connected"]);
+function normalizeStatus(status) {
+  return LIVE_STATES.has(status) ? status : "disconnected";
+}
+function serializeError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      ...error.stack ? { stack: error.stack } : {}
+    };
+  }
+  return {
+    name: "CentrifugeError",
+    message: typeof error === "string" ? error : "Centrifuge worker operation failed.",
+    ...error === void 0 ? {} : { context: error }
+  };
+}
+
+// src/worker-mode.ts
+function selectWorkerBackend(mode, availability = {}) {
+  const hasDedicated = availability.worker ?? typeof Worker !== "undefined";
+  const hasShared = availability.sharedWorker ?? typeof SharedWorker !== "undefined";
+  if (mode === "shared" || mode === "auto") {
+    return hasShared ? "shared" : hasDedicated ? "dedicated" : "local";
+  }
+  return hasDedicated ? "dedicated" : hasShared ? "shared" : "local";
+}
+
+// src/centrifuge-protocol.ts
+var DEFAULT_HEARTBEAT_INTERVAL_MS2 = 1e4;
+var DEFAULT_SESSION_TIMEOUT_MULTIPLIER = 3;
+var DEFAULT_SESSION_TIMEOUT_MS = DEFAULT_HEARTBEAT_INTERVAL_MS2 * DEFAULT_SESSION_TIMEOUT_MULTIPLIER;
+
+// src/centrifuge.ts
+var import_meta = {};
+var CentrifugeWorkerTransport = class {
+  workerMode;
+  transferable;
+  heartbeatIntervalMs;
+  workerFactory;
+  sharedWorkerFactory;
+  backend = null;
+  worker = null;
+  sharedWorker = null;
+  port = null;
+  heartbeatHandle = null;
+  localSession = null;
+  handlers = null;
+  // Monotonically increasing counter, bumped each time a backend is created.
+  // Used to ignore late error events from a superseded Worker.
+  generation = 0;
+  // Generation captured when the current backend was created. Error handlers
+  // only act when the backend that registered them is still current.
+  backendGeneration = 0;
+  constructor(options = {}) {
+    this.workerMode = options.workerMode ?? "dedicated";
+    this.transferable = options.transferable ?? false;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS2;
+    assertHeartbeatInterval(this.heartbeatIntervalMs);
+    this.workerFactory = options.workerFactory;
+    this.sharedWorkerFactory = options.sharedWorkerFactory;
+  }
+  /**
+   * Start the transport: select a backend, initialise the Worker (or local
+   * session), and send the INIT message with connection parameters.
+   */
+  start(config, handlers) {
+    if (this.backend) return;
+    assertStructuredCloneable(config.options ?? {});
+    this.handlers = handlers;
+    const backend = selectWorkerBackend(this.workerMode, {
+      worker: this.workerFactory !== void 0,
+      sharedWorker: this.sharedWorkerFactory !== void 0
+    });
+    const input = this.buildInitInput(config);
+    if (backend === "shared") {
+      this.startSharedWorker(input);
+      this.backend = "shared";
+      return;
+    }
+    if (backend === "dedicated") {
+      this.startDedicatedWorker(input);
+      this.backend = "dedicated";
+      return;
+    }
+    this.localSession = new CentrifugeSession({ post: this.handleSessionOutput });
+    this.localSession.handle(input);
+    this.backend = "local";
+  }
+  subscribe(topic) {
+    this.post({ type: "SUBSCRIBE", topic });
+  }
+  unsubscribe(topic) {
+    this.post({ type: "UNSUBSCRIBE", topic });
+  }
+  /**
+   * Publish data to `topic`. Binary data (ArrayBuffer) is sent via Transferable
+   * when `transferable` is enabled, avoiding a structured-clone cycle.
+   */
+  publish(topic, data) {
+    if (this.transferable && data instanceof ArrayBuffer) {
+      this.post({ type: "PUBLISH_BIN", topic, data }, [data]);
+      return;
+    }
+    this.post({ type: "PUBLISH", topic, data });
+  }
+  /**
+   * Gracefully stop the transport: send STOP, clean up event listeners, and
+   * terminate the Worker (or close the SharedWorker port).
+   */
+  stop() {
+    if (!this.backend) return;
+    this.generation++;
+    this.post({ type: "STOP" });
+    this.clearHeartbeat();
+    if (this.worker) {
+      this.worker.removeEventListener("message", this.handleMessage);
+      this.worker.removeEventListener("error", this.handleWorkerError);
+      this.worker.terminate();
+    }
+    if (this.sharedWorker) {
+      this.detachSharedWorkerListeners();
+      this.port?.close();
+    }
+    this.resetBackend();
+    this.handlers = null;
+  }
+  /** Build the INIT payload sent to the Worker / local session. Optional fields
+   * are only included when they deviate from the defaults, so the Worker's own
+   * default-resolution logic kicks in for the common case. */
+  buildInitInput(config) {
+    return {
+      type: "INIT",
+      url: config.url,
+      config: config.options ?? {},
+      ...this.transferable ? { transferable: true } : {},
+      ...this.heartbeatIntervalMs !== DEFAULT_HEARTBEAT_INTERVAL_MS2 ? { heartbeatIntervalMs: this.heartbeatIntervalMs } : {}
+    };
+  }
+  /** Create and initialise a dedicated Worker, then send the INIT message. */
+  startDedicatedWorker(input) {
+    this.backendGeneration = ++this.generation;
+    const worker = (this.workerFactory ?? createDefaultWorker)();
+    this.worker = worker;
+    worker.addEventListener("message", this.handleMessage);
+    worker.addEventListener("error", this.handleWorkerError);
+    worker.postMessage(input);
+  }
+  /** Create and initialise a SharedWorker, open the MessagePort, and send the INIT message. */
+  startSharedWorker(input) {
+    this.backendGeneration = ++this.generation;
+    const shared = (this.sharedWorkerFactory ?? createDefaultSharedWorker)();
+    this.sharedWorker = shared;
+    const port = shared.port;
+    this.port = port;
+    port.addEventListener("message", this.handleMessage);
+    port.addEventListener("messageerror", this.handlePortError);
+    shared.addEventListener("error", this.handleSharedWorkerError);
+    port.start();
+    port.postMessage(input);
+    this.startHeartbeat();
+  }
+  /** Handle a message event from the Worker (dedicated or shared). */
+  handleMessage = (event) => {
+    this.handleOutput(event.data);
+  };
+  /** Handle a message from the in-process CentrifugeSession (local fallback). */
+  handleSessionOutput = (message) => {
+    this.handleOutput(message);
+  };
+  /** Route a Worker output message to the appropriate handler callback.
+   * Shared by the Worker message listener, the SharedWorker port listener,
+   * and the local-session sink — all three feed into this single dispatcher. */
+  handleOutput(message) {
+    if (message.type === "STATUS") this.handlers?.onStatus(message.status);
+    if (message.type === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data });
+    if (message.type === "MESSAGE_BIN") this.handlers?.onMessage({ topic: message.topic, data: message.data });
+    if (message.type === "ERROR") this.handlers?.onError(deserializeWorkerError(message.error));
+  }
+  /** Handle a Worker-level failure (crash, message decode error). Discards the
+   * dead backend so a later start()/reopen can rebuild from scratch, and
+   * signals an error status so the DataBus can trigger recovery.
+   * Only invoked when the generation guard confirms the failing backend is
+   * still current — late errors from a superseded Worker are silently dropped. */
+  onWorkerFailed(message) {
+    this.worker?.removeEventListener("message", this.handleMessage);
+    this.worker?.removeEventListener("error", this.handleWorkerError);
+    this.worker?.terminate();
+    this.detachSharedWorkerListeners();
+    this.port?.close();
+    this.clearHeartbeat();
+    this.resetBackend();
+    this.handlers?.onError(new Error(message));
+    this.handlers?.onStatus("error");
+  }
+  /** Remove every listener attached to the current SharedWorker and its port. */
+  detachSharedWorkerListeners() {
+    this.port?.removeEventListener("message", this.handleMessage);
+    this.port?.removeEventListener("messageerror", this.handlePortError);
+    this.sharedWorker?.removeEventListener("error", this.handleSharedWorkerError);
+  }
+  /** Periodically ping the SharedWorker so its session reaper can detect a dead tab. */
+  startHeartbeat() {
+    if (this.heartbeatHandle !== null) return;
+    if (this.heartbeatIntervalMs === Infinity) return;
+    this.heartbeatHandle = setInterval(() => {
+      this.post({ type: "PING" });
+    }, this.heartbeatIntervalMs);
+  }
+  clearHeartbeat() {
+    if (this.heartbeatHandle !== null) clearInterval(this.heartbeatHandle);
+    this.heartbeatHandle = null;
+  }
+  handleWorkerError = () => {
+    if (this.generation !== this.backendGeneration) return;
+    this.onWorkerFailed("Centrifuge worker failed.");
+  };
+  handlePortError = () => {
+    if (this.generation !== this.backendGeneration) return;
+    this.onWorkerFailed("Centrifuge shared worker message decoding failed.");
+  };
+  handleSharedWorkerError = () => {
+    if (this.generation !== this.backendGeneration) return;
+    this.onWorkerFailed("Centrifuge shared worker failed.");
+  };
+  /** Clear the Worker/port/backend references after a failure or stop. */
+  resetBackend() {
+    this.worker = null;
+    this.sharedWorker = null;
+    this.port = null;
+    this.backend = null;
+    this.localSession = null;
+  }
+  /**
+   * Post a message to the active backend. Accepts optional Transferable buffers
+   * for zero-copy ArrayBuffer transfer.
+   */
+  post(message, transfer) {
+    if (this.worker) {
+      postToPortLike(this.worker, message, transfer);
+      return;
+    }
+    if (this.port) {
+      postToPortLike(this.port, message, transfer);
+      return;
+    }
+    if (this.localSession) {
+      this.localSession.handle(message);
+      return;
+    }
+    throw new Error("CentrifugeWorkerTransport.start() must be called first.");
+  }
+};
+function createCentrifugeDataBus(options) {
+  const {
+    clusterKey,
+    connection,
+    heartbeatIntervalMs,
+    sharedWorkerFactory,
+    transferable,
+    workerFactory,
+    workerMode,
+    ...dataBusOptions
+  } = options;
+  return new CrossTabDataBus({
+    ...dataBusOptions,
+    autoStart: true,
+    clusterKey: clusterKey ?? connection.url,
+    initialConfig: connection,
+    transport: new CentrifugeWorkerTransport({
+      ...workerFactory ? { workerFactory } : {},
+      ...sharedWorkerFactory ? { sharedWorkerFactory } : {},
+      ...transferable === void 0 ? {} : { transferable },
+      ...workerMode ? { workerMode } : {},
+      ...heartbeatIntervalMs === void 0 ? {} : { heartbeatIntervalMs }
+    })
+  });
+}
+function createDefaultWorker() {
+  if (typeof Worker === "undefined") {
+    throw new Error("CentrifugeWorkerTransport requires a browser Worker implementation.");
+  }
+  let workerUrl;
+  try {
+    workerUrl = new URL("./centrifuge.worker.js", import_meta.url);
+  } catch {
+    throw new Error(
+      "The default Centrifuge Worker URL is unavailable in this module format; provide workerFactory explicitly."
+    );
+  }
+  return new Worker(workerUrl, {
+    name: "cross-tab-worker-databus",
+    type: "module"
+  });
+}
+function createDefaultSharedWorker() {
+  if (typeof SharedWorker === "undefined") {
+    throw new Error("CentrifugeWorkerTransport requires a browser SharedWorker implementation.");
+  }
+  let workerUrl;
+  try {
+    workerUrl = new URL("./centrifuge.shared.worker.js", import_meta.url);
+  } catch {
+    throw new Error(
+      "The default Centrifuge SharedWorker URL is unavailable in this module format; provide sharedWorkerFactory explicitly."
+    );
+  }
+  return new SharedWorker(workerUrl, {
+    name: "cross-tab-worker-databus-shared",
+    type: "module"
+  });
+}
+function assertHeartbeatInterval(value) {
+  if (value === Infinity) return;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return;
+  throw new TypeError(
+    `Centrifuge heartbeatIntervalMs must be a positive number or Infinity, got ${String(value)}.`
+  );
+}
+function assertStructuredCloneable(value) {
+  if (typeof structuredClone !== "function") return;
+  try {
+    structuredClone(value);
+  } catch (error) {
+    throw new TypeError(
+      "Centrifuge Worker configuration and published data must be structured-cloneable.",
+      { cause: error }
+    );
+  }
+}
+function postToPortLike(target, message, transfer) {
+  if (transfer) target.postMessage(message, transfer);
+  else target.postMessage(message);
+}
+function deserializeWorkerError(error) {
+  const result = new Error(error.message);
+  result.name = error.name;
+  if (error.stack) result.stack = error.stack;
+  if (error.context !== void 0) Object.assign(result, { context: error.context });
+  return result;
+}
+//# sourceMappingURL=centrifuge.cjs.map