cross-tab-worker-databus 0.1.0

package/dist/chunk-GABYBK7I.js

@@ -0,0 +1,1527 @@
+// 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 = 3735928559 ^ value.length;
+  let h2 = 1103547991 ^ value.length;
+  let h3 = 3235826430 ^ value.length;
+  let h4 = 2654435769 ^ value.length;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    h1 = Math.imul(h1 ^ code, 2654435761);
+    h2 = Math.imul(h2 ^ code, 1597334677);
+    h3 = Math.imul(h3 ^ code, 2246822519);
+    h4 = Math.imul(h4 ^ code, 3266489917);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h3 ^ h3 >>> 13, 3266489909);
+  h3 = Math.imul(h3 ^ h3 >>> 16, 2246822507) ^ Math.imul(h4 ^ h4 >>> 13, 3266489909);
+  h4 = Math.imul(h4 ^ h4 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  return [h1, h2, h3, h4].map((hash) => (hash >>> 0).toString(16).padStart(8, "0")).join("");
+}
+
+// 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;
+    return worker.workerId.localeCompare(least.workerId) < 0 ? worker : 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.localeCompare(right.workerId)
+  ).slice(0, maxActiveWorkers);
+}
+function selectRebalanceTarget(workers, currentWorkerId) {
+  const currentWorker = workers.find((worker) => worker.workerId === currentWorkerId);
+  const leastLoadedWorker = selectLeastLoadedWorker(workers);
+  if (!currentWorker || !leastLoadedWorker || currentWorker.workerId === leastLoadedWorker.workerId || currentWorker.load <= leastLoadedWorker.load + 1) {
+    return null;
+  }
+  return leastLoadedWorker;
+}
+function hasActiveOwner(route, workers) {
+  return Boolean(route && workers.some((worker) => worker.workerId === route.workerId));
+}
+
+// src/core/storage-batch.ts
+var INITIAL_RETRY_DELAY_MS = 50;
+var MAX_RETRY_DELAY_MS = 1600;
+var BatchingStorageWriter = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /** Coalesced write set. A `null` value represents a pending delete. */
+  pending = /* @__PURE__ */ new Map();
+  flushScheduled = false;
+  retryHandle = null;
+  retryDelayMs = INITIAL_RETRY_DELAY_MS;
+  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.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 [...this.pending]) {
+      try {
+        if (value === null) this.storage.removeItem(key);
+        else this.storage.setItem(key, value);
+        this.pending.delete(key);
+      } catch {
+        this.scheduleRetry();
+        break;
+      }
+    }
+    if (this.pending.size === 0) this.retryDelayMs = INITIAL_RETRY_DELAY_MS;
+  }
+  /** 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 [...keys];
+  }
+  // Coalesce all synchronous writes within one task into a single microtask
+  // flush, avoiding a localStorage write per heartbeat/route/subscriber update.
+  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);
+  }
+  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 [];
+  }
+}
+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.
+   */
+  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);
+    if (!this.storage) {
+      for (const topic of this.subscribedTopics) {
+        this.sendControl(this.workerId, "SUBSCRIBE", topic, this.rememberTopic(topic));
+      }
+    } else {
+      for (const topic of this.subscribedTopics) this.writeSubscriber(this.rememberTopic(topic));
+    }
+    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 (existingRoute && workers.some((worker) => worker.workerId === existingRoute.workerId)) {
+      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) {
+    const topicKey = this.rememberTopic(topic);
+    this.subscribedTopics.delete(topic);
+    this.releaseSubscription(topic);
+    if (!this.assignedTopics.has(topicKey)) this.knownTopics.delete(topicKey);
+  }
+  /** Remove this tab's subscriber record and, when it was the last one, delete the route. */
+  releaseSubscription(topic, notifyOwner = true) {
+    const topicKey = this.rememberTopic(topic);
+    this.removeStorage(this.subscriberStorageKey(topicKey, this.tabId));
+    const route = this.readRoute(topicKey);
+    if (!route) return;
+    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);
+    }
+  }
+  /** 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) {
+      if (this.readRoute(topicKey)?.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 previous = this.readRoute(topicKey);
+      this.writeRoute(topicKey, owner, previous?.workerId, (previous?.generation ?? 0) + 1);
+      this.flushStorage();
+      const generation = (previous?.generation ?? 0) + 1;
+      this.handlers.onControl("UNSUBSCRIBE", topic);
+      this.send({
+        type: "ROUTE_RELEASED",
+        sourceWorkerId: this.workerId,
+        targetWorkerId: 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 = route && workers.some((worker) => worker.workerId === route.workerId) ? route.workerId : this.workerId;
+    return this.sendControl(target ?? this.workerId, "PUBLISH", topic, topicKey, data);
+  }
+  /** 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;
+    return this.readRoute(topicKey)?.workerId === this.workerId;
+  }
+  /** True if this worker is among the active set (eligible to own topics). */
+  isActiveWorker() {
+    return selectActiveWorkers(this.readWorkers(), this.maxActiveWorkers).some(
+      (worker) => worker.workerId === this.workerId
+    );
+  }
+  /** True when this tab has a local subscriber registered for `topic`. */
+  hasLocalSubscriber(topic) {
+    return this.subscribedTopics.has(topic);
+  }
+  /** Read-only snapshot of the cluster state (workers, routes, assignments). */
+  getSnapshot() {
+    const routes = listKeysSafe(this.storage, this.routePrefix).map((key) => this.storage ? readJson(this.storage, key) : null).filter((route) => Boolean(route)).map((route) => ({
+      ...route,
+      topic: this.knownTopics.get(route.topicKey) ?? null
+    }));
+    return {
+      coordinated: Boolean(this.storage && this.channel),
+      suspended: this.suspended,
+      currentWorker: { ...this.currentRecord },
+      workers: this.readWorkers().map((worker) => ({ ...worker })),
+      routes,
+      subscribedTopics: [...this.subscribedTopics],
+      assignedTopics: [...this.assignedTopics.values()],
+      knownTopics: [...this.knownTopics.entries()].map(([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;
+    if (message.type === "CONTROL") return this.handleControlMessage(message);
+    if (message.type === "ROUTE_RELEASED") return this.handleRouteReleasedMessage(message);
+    if (message.type === "EVENT") {
+      this.handlers.onEvent(message.eventType, message.payload, message.sourceWorkerId);
+      return;
+    }
+    this.reconcile();
+  };
+  /** Handle a point-to-point CONTROL message (SUBSCRIBE / UNSUBSCRIBE / PUBLISH). */
+  handleControlMessage(message) {
+    if (message.targetWorkerId !== this.workerId) return;
+    this.rememberTopic(message.topic);
+    if (message.action === "SUBSCRIBE") {
+      this.assignedTopics.set(message.topicKey, message.topic);
+      this.confirmRoute(message.topicKey);
+    }
+    if (message.action === "UNSUBSCRIBE") {
+      if (this.releaseHandoffOnUnsubscribe(message)) return;
+    }
+    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.send({
+      type: "ROUTE_RELEASED",
+      sourceWorkerId: this.workerId,
+      targetWorkerId: route.workerId,
+      topic: message.topic,
+      topicKey: message.topicKey,
+      generation: route.generation
+    });
+    this.updateLoad();
+    return true;
+  }
+  /**
+   * 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 || route.workerId !== this.workerId || route.handoffFromWorkerId !== message.sourceWorkerId || route.generation < message.generation) return;
+    this.assignedTopics.set(message.topicKey, message.topic);
+    this.confirmRoute(message.topicKey);
+    this.handlers.onControl("SUBSCRIBE", message.topic, void 0);
+    this.updateLoad();
+  }
+  /** 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. */
+  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]) {
+      if (this.readRoute(topicKey)?.workerId === this.workerId) continue;
+      this.assignedTopics.delete(topicKey);
+      this.handlers.onControl("UNSUBSCRIBE", topic, void 0);
+      const route = this.readRoute(topicKey);
+      if (route?.handoffFromWorkerId === this.workerId) {
+        this.send({
+          type: "ROUTE_RELEASED",
+          sourceWorkerId: this.workerId,
+          targetWorkerId: route.workerId,
+          topic,
+          topicKey,
+          generation: 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) {
+      if (action === "SUBSCRIBE") {
+        this.assignedTopics.set(topicKey, topic);
+        this.confirmRoute(topicKey);
+      }
+      if (action === "UNSUBSCRIBE") this.assignedTopics.delete(topicKey);
+      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 of listKeys(this.storage, this.workerPrefix)) {
+      const worker = readJson(this.storage, key);
+      if (!worker) continue;
+      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) return this.subscribedTopics.has(this.knownTopics.get(topicKey) ?? "") ? [this.tabId] : [];
+    const activeTabIds = new Set(workers.map((worker) => worker.tabId));
+    const subscribers = /* @__PURE__ */ new Set();
+    for (const key of listKeys(this.storage, `${this.subscriberPrefix}${topicKey}:`)) {
+      const record = readJson(this.storage, key);
+      if (!record || !activeTabIds.has(record.tabId)) {
+        this.removeStorage(key);
+        continue;
+      }
+      subscribers.add(record.tabId);
+    }
+    return [...subscribers];
+  }
+  /** Read the current route for `topicKey`, returning null when no storage layer exists. */
+  readRoute(topicKey) {
+    if (!this.storage) {
+      const topic = this.knownTopics.get(topicKey);
+      return topic && (this.subscribedTopics.has(topic) || this.assignedTopics.has(topicKey)) ? {
+        topicKey,
+        workerId: this.workerId,
+        tabId: this.tabId,
+        updatedAt: this.environment.now(),
+        generation: 1
+      } : null;
+    }
+    return readJson(this.storage, this.routeStorageKey(topicKey));
+  }
+  /** 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), {
+      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 of listKeys(this.storage, this.routePrefix)) {
+      const route = readJson(this.storage, key);
+      if (!route || 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 of listKeys(this.storage, this.subscriberPrefix)) {
+      const record = readJson(this.storage, key);
+      if (!record || !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. */
+  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 = selectActiveWorkers(workers, this.maxActiveWorkers).some((worker) => worker.workerId === this.workerId) ? "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) {
+      const oldest = this.knownTopics.keys().next().value;
+      if (oldest !== void 0 && oldest !== topicKey && !this.assignedTopics.has(oldest)) {
+        this.knownTopics.delete(oldest);
+      }
+    }
+    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();
+  }
+};
+function listKeysSafe(storage, prefix) {
+  return storage ? listKeys(storage, prefix) : [];
+}
+
+// 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'. */
+  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.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.enabled || this.mode === "events") 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.enabled || this.mode === "events") 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.enabled || this.mode === "events") 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;
+  }
+  /** Emit the accumulated metrics snapshot if the interval is active. */
+  flush() {
+    if (!this.enabled || this.mode === "events") 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 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();
+  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 { 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) => {
+          if (action === "SUBSCRIBE") {
+            if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
+          }
+          if (action === "UNSUBSCRIBE") {
+            if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
+          }
+          if (action === "PUBLISH") this.runTransport(() => this.transport.publish(topic, data));
+        },
+        // The cluster calls `onEvent` when a publication broadcast arrives from
+        // another tab. Dispatch locally if we have subscribers.
+        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((w) => `${w.workerId}|${w.status}|load=${w.load}|tab=${w.tabId}`),
+      routes: snapshot.routes.map((r) => `${r.topicKey}@${r.workerId}|confirmed=${r.confirmedAt !== void 0}`)
+    });
+    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 = Promise.resolve().then(() => this.transport.stop()).catch((stopError) => this.reportError(stopError));
+      }
+      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) {
+    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);
+    return () => this.unsubscribe(topic, handler);
+  }
+  /** Remove a specific handler, or all handlers for `topic`. */
+  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.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). */
+  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.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. */
+  dispatch(message) {
+    this.trace.recordDispatched(message.topic);
+    for (const handler of this.topicHandlers.get(message.topic) ?? []) {
+      try {
+        handler(message);
+      } catch (error) {
+        this.reportError(error);
+      }
+    }
+  }
+  /**
+   * 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);
+      }
+    }
+    for (const handler of this.statusHandlers) {
+      try {
+        handler(status);
+      } catch (error) {
+        this.reportError(error);
+      }
+    }
+  }
+  reportError(error) {
+    this.trace.event({ type: "error", source: "transport" });
+    for (const handler of this.errorHandlers) {
+      try {
+        handler(error);
+      } catch (handlerError) {
+        if (typeof console !== "undefined" && typeof console.warn === "function") {
+          console.warn("[cross-tab-worker-databus] error handler threw:", handlerError);
+        }
+      }
+    }
+  }
+  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;
+  }
+  /**
+   * 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;
+  }
+  /**
+   * 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);
+  }
+};
+
+// 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";
+}
+
+export {
+  createBrowserEnvironment,
+  getOrCreateTabId,
+  createOpaqueKey,
+  DEFAULT_MAX_ACTIVE_WORKERS,
+  selectLeastLoadedWorker,
+  selectActiveWorkers,
+  selectRebalanceTarget,
+  hasActiveOwner,
+  WorkerClusterRuntime,
+  CrossTabDataBus,
+  selectWorkerBackend
+};
+//# sourceMappingURL=chunk-GABYBK7I.js.map