@lunora/client 1.0.0-alpha.21 → 1.0.0-alpha.22

package/dist/packem_shared/{LunoraClient-kXpHNyaE.mjs → LunoraClient-Clb118SU.mjs}

@@ -1,13 +1,16 @@
 import { LunoraError } from '@lunora/errors';
-import { S as SubscriptionRegistry, s as stableStringify } from './subscription-BjynOXCU.mjs';
+import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
+import { ClientQueryStore } from './createClientQuery-CQ51bWAE.mjs';
+import { TabCoordinator } from './TabCoordinator-BwRR8H06.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-CRKZ1PBt.mjs';
-import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BveBeFEo.mjs';
-import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-B9vfdSqp.mjs';
+import { f as foldOptimistic, a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, c as createLocalStore } from './local-store-DtcIW4c0.mjs';
+import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-CF4_Co5k.mjs';
 import { resolvePersistenceAdapter } from './createInMemoryPersistence-DZ2VHWgm.mjs';
 import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-DiaGZkA2.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
+import { SubscriptionRegistry } from './SubscriptionRegistry-D4jfIzZu.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
 
@@ -21,6 +24,23 @@ const evictOldestEntry = (map, capacity) => {
   }
 };
 
+const toBase64 = (bytes) => {
+  let binary = "";
+  const chunk = 32768;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+};
+const fromBase64 = (base64) => {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return bytes;
+};
+
 const TAG = "$lunora.wire$";
 const MAX_DEPTH = 64;
 const MAX_BIGINT_DIGITS = 1024;
@@ -47,22 +67,6 @@ const ERROR_CTORS = {
   TypeError,
   URIError
 };
-const toBase64 = (bytes) => {
-  let binary = "";
-  const chunk = 32768;
-  for (let index = 0; index < bytes.length; index += chunk) {
-    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
-  }
-  return btoa(binary);
-};
-const fromBase64 = (base64) => {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.codePointAt(index) ?? 0;
-  }
-  return bytes;
-};
 const encodeWire = (value, depth = 0) => {
   if (depth > MAX_DEPTH) {
     throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
@@ -463,11 +467,25 @@ const demuxBatchResults = (rawResults, count) => {
   return slots.map((slot) => slot ?? { error: new Error("batch call returned no result"), ok: false });
 };
 const TRANSIENT_BATCH_ERROR_CODES = /* @__PURE__ */ new Set(["SHARD_ERROR", "SHARD_UNAVAILABLE"]);
+const RESOLVED_PROMISE = Promise.resolve();
 class LunoraClient {
   /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
   static MAX_POKE_BUFFERS = 256;
+  /**
+   * Create a typed {@link ClientQueryRef}. Convenience wrapper around
+   * {@link createClientQuery} so you don't need a separate import.
+   * @example
+   * ```ts
+   * const sidebarOpen = LunoraClient.createClientQuery("sidebarOpen", true);
+   * ```
+   */
+  static createClientQuery(key, defaultValue) {
+    return { defaultValue, key };
+  }
   url;
   wsUrl;
+  /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
+  clientQueryStore;
   wsToken;
   /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
   authBasePath;
@@ -488,6 +506,20 @@ class LunoraClient {
   outbox;
   /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
   clientId;
+  /**
+   * `true` when the constructor's hydration microtask has finished loading the
+   * durable read cache (Pillar 2) into `hydratedQueryCache`. Signals that
+   * the cache is ready for synchronous `peekHydratedQuery` reads.
+   */
+  readyResolved = false;
+  /** Resolvers for `whenReady()` — called once hydration completes. */
+  readyResolve;
+  /**
+   * Promise that resolves once the durable read cache has been loaded. When
+   * `hydrateOnStart` is not set or no query cache is configured, resolves
+   * immediately (the constructor creates an already-resolved promise).
+   */
+  readyPromise;
   /**
    * Highest custom-mutator watermark the server has echoed for this client,
    * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
@@ -521,6 +553,12 @@ class LunoraClient {
   pendingCacheWrites = /* @__PURE__ */ new Map();
   cacheFlushTimer;
   subscriptions = new SubscriptionRegistry();
+  /**
+   * Cross-tab coordinator; created only when `crossTabSync: true`. When the
+   * client is not the elected leader, all WebSocket operations are skipped.
+   * Not `readonly` — `close()` clears it (mirrors `outboxLeaderRelease`).
+   */
+  tabCoordinator;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   connections = /* @__PURE__ */ new Map();
   /** Default `connect`-envelope context applied to a shard with no explicit override. */
@@ -616,6 +654,59 @@ class LunoraClient {
     this.persistenceVersion = options.persistenceVersion;
     this.queryCache = resolveQueryCacheAdapter(options.queryCache);
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
+    this.clientQueryStore = new ClientQueryStore();
+    if (options.crossTabSync) {
+      this.tabCoordinator = new TabCoordinator({
+        onBecomeLeader: () => {
+          for (const state of this.subscriptions.all()) {
+            this.ensureSocket(state.shardKey);
+            this.sendSubscribeIfOpen(state);
+          }
+        },
+        onStopBeingLeader: () => {
+          for (const [key, conn] of this.connections) {
+            conn.socket?.close();
+            this.connections.delete(key);
+          }
+        },
+        onSubscriptionData: (key, data) => {
+          const state = this.subscriptions.get(key);
+          if (state) {
+            state.serverBase = data;
+            const folded = state.optimisticLayers.length === 0 ? data : foldOptimistic(data, state.optimisticLayers);
+            state.lastValue = folded;
+            for (const callback of state.callbacks) {
+              try {
+                callback(folded);
+              } catch {
+              }
+            }
+          }
+        },
+        onSubscriptionError: (key, error) => {
+          const state = this.subscriptions.get(key);
+          if (state) {
+            for (const callback of state.errorCallbacks) {
+              try {
+                callback(error);
+              } catch {
+              }
+            }
+          }
+        }
+      });
+      this.tabCoordinator.start();
+    } else {
+      this.tabCoordinator = void 0;
+    }
+    if (options.hydrateOnStart && this.queryCache) {
+      this.readyPromise = new Promise((resolve) => {
+        this.readyResolve = resolve;
+      });
+    } else {
+      this.readyResolved = true;
+      this.readyPromise = RESOLVED_PROMISE;
+    }
     this.offlineQueue = new OfflineQueue(options.offlineQueue, {
       onEvict: (entry, error) => {
         this.emitItemSettled(entry, "rejected", error);
@@ -635,7 +726,17 @@ class LunoraClient {
     }
     if (this.queryCache) {
       queueMicrotask(() => {
-        this.hydrateQueryCache().catch(() => void 0);
+        const hydration = async () => {
+          try {
+            await this.hydrateQueryCache();
+          } catch {
+          } finally {
+            this.readyResolved = true;
+            this.readyResolve?.();
+          }
+        };
+        hydration().catch(() => {
+        });
       });
     }
   }
@@ -1008,6 +1109,135 @@ class LunoraClient {
   onMutationSettled(listener) {
     return this.mutationSettledListeners.add(listener);
   }
+  // --- Client Query (local state) ----------------------------------------
+  /**
+   * Read the current value for a {@link ClientQueryRef}. Returns
+   * `ref.defaultValue` when no value has been explicitly set.
+   */
+  getClientQuery(ref) {
+    return this.clientQueryStore.get(ref);
+  }
+  /**
+   * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+   * to reset the slot to `ref.defaultValue`.
+   */
+  setClientQuery(ref, value) {
+    this.clientQueryStore.set(ref, value);
+  }
+  /**
+   * Subscribe to changes for `ref`. The callback is NOT invoked on
+   * registration — call {@link getClientQuery} for the current value.
+   * Returns an unsubscribe function.
+   */
+  subscribeClientQuery(ref, callback) {
+    return this.clientQueryStore.subscribe(ref, callback);
+  }
+  /**
+   * Reset a {@link ClientQueryRef} to its default value, notifying every
+   * subscriber. Equivalent to `setClientQuery(ref, ref.defaultValue)` but
+   * removes the stored entry so a future {@link getClientQuery} returns
+   * the default rather than an explicitly-set value.
+   */
+  resetClientQuery(ref) {
+    this.clientQueryStore.reset(ref);
+  }
+  /**
+   * Capture a snapshot of the current live query value at call time and
+   * produce a `() => boolean` precondition that compares it against the
+   * value at replay time (on queue drain / reconnect).
+   *
+   * When the precondition is checked it re-reads the query's current value
+   * via `peekActiveQueryValue`. If the value differs from what was
+   * captured at call time the precondition returns `false` and the offline
+   * mutation is dropped as stale.
+   *
+   * This is a method wrapper around `createSnapshotPrecondition` that
+   * binds the client instance for you — no need to pass `client` explicitly.
+   * @example
+   * ```ts
+   * client.mutation(api.todos.update, { id, text }, {
+   *   precondition: client.snapshotPrecondition(api.todos.list, { userId }),
+   * });
+   * ```
+   */
+  snapshotPrecondition(functionRef, args, shardKey) {
+    const snapshot = this.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
+    const snapshotKey = snapshot === void 0 ? void 0 : stableStringify(snapshot);
+    return () => {
+      const current = this.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
+      if (snapshotKey === void 0 && current === void 0) {
+        return true;
+      }
+      if (snapshotKey === void 0 || current === void 0) {
+        return false;
+      }
+      return stableStringify(current) === snapshotKey;
+    };
+  }
+  // --- Hydration helpers --------------------------------------------------
+  /**
+   * Resolves once the durable read cache has been loaded into memory. When
+   * `hydrateOnStart` is not configured or no query cache adapter is active,
+   * returns an already-resolved promise so callers can always await it
+   * unconditionally.
+   *
+   * Framework adapters (React, Vue, etc.) use this to gate the first
+   * (enabled) render of a live query behind hydration, so the user sees
+   * cached data instead of an undefined flash before the socket round-trip.
+   */
+  whenReady() {
+    return this.readyPromise;
+  }
+  /**
+   * Synchronously reports whether {@link whenReady} has already resolved (the
+   * durable read cache is loaded, or none is configured). Framework adapters
+   * read this to seed the hydration-gate state on the first render without
+   * awaiting, then subscribe via {@link whenReady} for the pending case.
+   */
+  get isReady() {
+    return this.readyResolved;
+  }
+  /**
+   * Synchronously peek at a value the durable read cache loaded for the given
+   * function path + args + shard key. Returns `undefined` when:
+   *
+   * - No query cache adapter is configured.
+   * - Hydration hasn't completed yet (race — await {@link whenReady} first).
+   * - The cached value's identity fingerprint doesn't match the current auth.
+   *
+   * Unlike the internal {@link takeHydratedCache}, this is a READ-ONLY peek:
+   * the cached entry stays in `hydratedQueryCache` so the subscription created
+   * later by {@link subscribe} consumes it normally.
+   */
+  peekHydratedQuery(functionPath, args, shardKey) {
+    if (!this.readyResolved) {
+      return void 0;
+    }
+    const argsKey = stableStringify(args);
+    const key = queryCacheKey(functionPath, argsKey, shardKey);
+    const entry = this.hydratedQueryCache.get(key);
+    if (entry === void 0) {
+      return void 0;
+    }
+    return entry.identity === this.identityFingerprint() ? entry.value : void 0;
+  }
+  /**
+   * Peek at the **current live value** of an active subscription, if one
+   * exists. Returns the subscription's `lastValue` (which includes any
+   * optimistic overlay) or `undefined` if no subscription is active for the
+   * given `(functionPath, args, shardKey)`.
+   *
+   * Unlike {@link peekHydratedQuery} (which reads from the durable read cache
+   * and is independent of active subscriptions), this method reflects the
+   * current in-memory state of an already-opened subscription — useful for
+   * offline mutation preconditions that need to snapshot the value at call time
+   * and compare it at replay time.
+   */
+  peekActiveQueryValue(functionPath, args, shardKey) {
+    const key = SubscriptionRegistry.key(functionPath, args, shardKey);
+    const state = this.subscriptions.get(key);
+    return state?.lastValue;
+  }
   // --- RPC ---------------------------------------------------------------
   async query(function_, args, options = {}) {
     if (this.closed) {
@@ -1105,7 +1335,15 @@ class LunoraClient {
     const shouldQueueOffline = this.WebSocketImpl !== void 0 && connectedGate;
     const midReconnect = wsState === "connecting" && connectedGate;
     if (wsState !== "open" && !hasSocket && shouldQueueOffline || midReconnect) {
-      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks, optimisticConfirms);
+      return this.enqueueOfflineMutation(
+        function_,
+        argsRecord,
+        options.shardKey,
+        mutationId,
+        optimisticRollbacks,
+        optimisticConfirms,
+        options.precondition
+      );
     }
     try {
       let commitCursor;
@@ -2113,6 +2351,8 @@ class LunoraClient {
     this.whisperHandlers.clear();
     this.shapeSubscriptions.clear();
     this.pokeBuffers.clear();
+    this.tabCoordinator?.stop();
+    this.tabCoordinator = void 0;
   }
   // --- Internals ----------------------------------------------------------
   /**
@@ -2126,7 +2366,7 @@ class LunoraClient {
    * optimistically (confirmation rides the synced view). Otherwise the
    * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
    */
-  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks, optimisticConfirms) {
+  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks, optimisticConfirms, precondition) {
     const issuingIdentity = this.identityFingerprint();
     if (this.outbox) {
       this.outboxMutationCounter += 1;
@@ -2164,6 +2404,8 @@ class LunoraClient {
         // Persist the stamp alongside the record so a hydrated write can
         // only replay under the identity that queued it.
         identity: issuingIdentity,
+        // Optional precondition checked before replay — see drainConflict.
+        precondition,
         // Confirm the per-call optimistic layer(s) against the commit cursor
         // the flush replay echoes (see flushOfflineQueue).
         onCommit: (commitCursor) => {
@@ -2618,6 +2860,9 @@ class LunoraClient {
     if (this.closed || this.WebSocketImpl === void 0) {
       return;
     }
+    if (this.tabCoordinator && !this.tabCoordinator.isLeader()) {
+      return;
+    }
     const conn = this.getOrCreateConnection(shardKey);
     if (conn.wsState === "open" || conn.wsState === "connecting") {
       return;
@@ -2979,6 +3224,10 @@ class LunoraClient {
     this.persistQueryValue(state);
     dropConfirmedLayers(state, state.serverCursor);
     notifySubscription(state, state.optimisticLayers.length === 0 ? payload : foldOptimistic(payload, state.optimisticLayers));
+    if (this.tabCoordinator?.isLeader()) {
+      const key = SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey);
+      this.tabCoordinator.broadcastSubscriptionData(key, payload);
+    }
   }
   /**
    * Handle a `resume` frame (Pillar 1b): the server proved nothing the
@@ -3217,6 +3466,14 @@ class LunoraClient {
     this.queryCache?.clear().catch(() => void 0);
   }
   async flushOfflineQueue(shardKey) {
+    const conflicted = this.offlineQueue.drainConflict();
+    for (const item of conflicted) {
+      this.unpersist(item.id);
+      this.queuedIdentities.delete(item.id ?? "");
+      const error = new Error("offline mutation skipped: precondition failed before replay");
+      error.code = "OFFLINE_PRECONDITION_FAILED";
+      this.emitItemSettled(item, "rejected", error);
+    }
     const key = connectionKey(shardKey);
     const drained = this.offlineQueue.drain((item) => connectionKey(item.shardKey) === key);
     if (drained.length === 0) {

package/dist/packem_shared/{OfflineQueue-GGYJRmhF.mjs → OfflineQueue-B4HUF7rt.mjs}

@@ -1 +1 @@
-export { O as OfflineQueue, n as nextId, r as reportPersistenceError } from './offline-queue-B9vfdSqp.mjs';
+export { O as OfflineQueue, n as nextId, r as reportPersistenceError } from './offline-queue-CF4_Co5k.mjs';

package/dist/packem_shared/SubscriptionRegistry-D4jfIzZu.mjs

@@ -0,0 +1,31 @@
+import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
+
+class SubscriptionRegistry {
+  static key(functionPath, args, shardKey) {
+    return `${functionPath}::${stableStringify(args)}::${shardKey ?? ""}`;
+  }
+  byKey = /* @__PURE__ */ new Map();
+  byId = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.byKey.get(key);
+  }
+  getById(id) {
+    return this.byId.get(id);
+  }
+  add(state) {
+    this.byKey.set(SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey), state);
+    this.byId.set(state.id, state);
+  }
+  remove(state) {
+    const key = SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey);
+    if (this.byKey.get(key) === state) {
+      this.byKey.delete(key);
+    }
+    this.byId.delete(state.id);
+  }
+  all() {
+    return [...this.byKey.values()];
+  }
+}
+
+export { SubscriptionRegistry };

package/dist/packem_shared/TabCoordinator-BwRR8H06.mjs

@@ -0,0 +1,222 @@
+let nextTabId = 0;
+const DEFAULT_CHANNEL = "lunora-bridge";
+const DEFAULT_HEARTBEAT_MS = 1e3;
+const DEFAULT_LEADER_TIMEOUT_MS = 3e3;
+class TabCoordinator {
+  bc;
+  tabId;
+  heartbeatInterval;
+  leaderTimeout;
+  /** The tab id of the current known leader, or `undefined` if no leader. */
+  knownLeader = void 0;
+  /** `true` when this tab believes it is the leader. */
+  leader = false;
+  /** `true` once `start()` has been called. */
+  running = false;
+  /** Timestamp of the most recent leader heartbeat. */
+  lastHeartbeat = 0;
+  heartbeatTimer = void 0;
+  leaderCheckTimer = void 0;
+  /** Callbacks set via constructor options. */
+  onBecomeLeader;
+  onStopBeingLeader;
+  onSubscriptionData;
+  onSubscriptionError;
+  constructor(options = {}) {
+    nextTabId += 1;
+    this.tabId = `tab_${String(nextTabId)}_${crypto.randomUUID()}`;
+    this.heartbeatInterval = options.heartbeatInterval ?? DEFAULT_HEARTBEAT_MS;
+    this.leaderTimeout = options.leaderTimeout ?? DEFAULT_LEADER_TIMEOUT_MS;
+    this.onBecomeLeader = options.onBecomeLeader;
+    this.onStopBeingLeader = options.onStopBeingLeader;
+    this.onSubscriptionData = options.onSubscriptionData;
+    this.onSubscriptionError = options.onSubscriptionError;
+    if (typeof BroadcastChannel === "undefined") {
+      this.bc = void 0;
+      return;
+    }
+    this.bc = new BroadcastChannel(options.channelName ?? DEFAULT_CHANNEL);
+    this.bc.addEventListener("message", (event) => {
+      this.handleMessage(event.data);
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /**
+   * Start the coordinator: attempt to claim leadership and begin the
+   * heartbeat/leader-check cycle. Safe to call multiple times.
+   */
+  start() {
+    if (this.running) {
+      return;
+    }
+    this.running = true;
+    if (this.bc === void 0) {
+      this.becomeLeader();
+      return;
+    }
+    this.broadcast({ type: "claim-leadership", tabId: this.tabId, ts: Date.now() });
+    setTimeout(() => {
+      if (!this.running) {
+        return;
+      }
+      if (this.knownLeader === void 0) {
+        this.becomeLeader();
+      }
+    }, this.leaderTimeout);
+    this.leaderCheckTimer = setInterval(() => {
+      this.checkLeaderHealth();
+    }, this.leaderTimeout);
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeat();
+    }, this.heartbeatInterval);
+  }
+  /**
+   * Stop the coordinator: yield leadership (if held), close the channel, and
+   * clear all timers. Safe to call multiple times.
+   */
+  stop() {
+    this.running = false;
+    if (this.leader) {
+      this.broadcast({ type: "yield-leadership", tabId: this.tabId });
+      this.leader = false;
+      this.knownLeader = void 0;
+      this.onStopBeingLeader?.();
+    }
+    if (this.heartbeatTimer !== void 0) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    if (this.leaderCheckTimer !== void 0) {
+      clearInterval(this.leaderCheckTimer);
+      this.leaderCheckTimer = void 0;
+    }
+    this.bc?.close();
+  }
+  /** `true` when this tab is the current WebSocket leader. */
+  isLeader() {
+    return this.leader;
+  }
+  /** The tab id of the current leader, or `undefined` if unknown / no leader. */
+  get leaderTabId() {
+    return this.knownLeader;
+  }
+  /** The id of this tab. */
+  get id() {
+    return this.tabId;
+  }
+  /** `true` when the coordinator has been started and is not yet stopped. */
+  get isRunning() {
+    return this.running;
+  }
+  // -----------------------------------------------------------------------
+  // Broadcasting
+  // -----------------------------------------------------------------------
+  /**
+   * Broadcast subscription data to all follower tabs. Only the leader should
+   * call this.
+   */
+  broadcastSubscriptionData(key, data) {
+    if (!this.leader) {
+      return;
+    }
+    this.broadcast({ type: "subscription-data", tabId: this.tabId, key, data });
+  }
+  /**
+   * Broadcast a subscription error to all follower tabs. Only the leader
+   * should call this.
+   */
+  broadcastSubscriptionError(key, error) {
+    if (!this.leader) {
+      return;
+    }
+    this.broadcast({ type: "subscription-error", tabId: this.tabId, key, error });
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  broadcast(message) {
+    this.bc?.postMessage(message);
+  }
+  handleMessage(message) {
+    switch (message.type) {
+      case "claim-leadership": {
+        if (message.tabId === this.tabId) {
+          break;
+        }
+        if (this.leader) {
+          this.broadcast({ type: "heartbeat", tabId: this.tabId, ts: Date.now() });
+          break;
+        }
+        if (this.knownLeader === void 0 && message.tabId < this.tabId) {
+          this.knownLeader = message.tabId;
+        }
+        break;
+      }
+      case "heartbeat": {
+        this.lastHeartbeat = message.ts;
+        this.knownLeader = message.tabId;
+        break;
+      }
+      case "subscription-data": {
+        if (this.leader || message.tabId === this.tabId) {
+          break;
+        }
+        this.onSubscriptionData?.(message.key, message.data);
+        break;
+      }
+      case "subscription-error": {
+        if (this.leader || message.tabId === this.tabId) {
+          break;
+        }
+        this.onSubscriptionError?.(message.key, message.error);
+        break;
+      }
+      case "yield-leadership": {
+        if (this.knownLeader === message.tabId) {
+          this.knownLeader = void 0;
+        }
+        break;
+      }
+    }
+  }
+  becomeLeader() {
+    if (this.leader) {
+      return;
+    }
+    this.leader = true;
+    this.knownLeader = this.tabId;
+    this.lastHeartbeat = Date.now();
+    this.onBecomeLeader?.();
+    this.broadcast({ type: "heartbeat", tabId: this.tabId, ts: Date.now() });
+  }
+  sendHeartbeat() {
+    if (!this.leader) {
+      return;
+    }
+    this.broadcast({ type: "heartbeat", tabId: this.tabId, ts: Date.now() });
+  }
+  checkLeaderHealth() {
+    if (!this.running) {
+      return;
+    }
+    if (this.leader) {
+      return;
+    }
+    if (this.knownLeader !== void 0) {
+      const elapsed = Date.now() - this.lastHeartbeat;
+      if (elapsed > this.leaderTimeout) {
+        this.knownLeader = void 0;
+        this.broadcast({ type: "claim-leadership", tabId: this.tabId, ts: Date.now() });
+        setTimeout(() => {
+          if (this.running && this.knownLeader === void 0) {
+            this.becomeLeader();
+          }
+        }, this.leaderTimeout);
+      }
+    }
+  }
+}
+
+export { TabCoordinator };