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

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

@@ -1,13 +1,17 @@
 import { LunoraError } from '@lunora/errors';
-import { S as SubscriptionRegistry, s as stableStringify } from './subscription-BjynOXCU.mjs';
+import { s as stableWireKey, d as decodeWire, e as encodeWire } from './wire-key-Djie6aaR.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 { httpStream } from './httpStream-BJU-aflc.mjs';
+import { f as foldOptimistic, a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, c as createLocalStore } from './local-store-DIq-UWfD.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-CxS_Inha.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
 
@@ -21,229 +25,6 @@ const evictOldestEntry = (map, capacity) => {
   }
 };
 
-const TAG = "$lunora.wire$";
-const MAX_DEPTH = 64;
-const MAX_BIGINT_DIGITS = 1024;
-const UNSAFE_KEY = "__proto__";
-const TYPED_ARRAY_CTORS = {
-  BigInt64Array,
-  BigUint64Array,
-  Float32Array,
-  Float64Array,
-  Int8Array,
-  Int16Array,
-  Int32Array,
-  Uint8Array,
-  Uint8ClampedArray,
-  Uint16Array,
-  Uint32Array
-};
-const ERROR_CTORS = {
-  Error,
-  EvalError,
-  RangeError,
-  ReferenceError,
-  SyntaxError,
-  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`);
-  }
-  if (value === void 0) {
-    return [TAG, "undefined"];
-  }
-  if (value === null) {
-    return null;
-  }
-  const kind = typeof value;
-  if (kind === "bigint") {
-    return [TAG, "bigint", value.toString()];
-  }
-  if (kind === "number") {
-    const numeric = value;
-    if (Number.isNaN(numeric)) {
-      return [TAG, "nan"];
-    }
-    if (numeric === Infinity) {
-      return [TAG, "inf"];
-    }
-    if (numeric === -Infinity) {
-      return [TAG, "-inf"];
-    }
-    return numeric;
-  }
-  if (kind !== "object") {
-    return value;
-  }
-  if (value instanceof Date) {
-    return [TAG, "date", encodeWire(value.getTime(), depth + 1)];
-  }
-  if (value instanceof Error) {
-    const error = value;
-    const properties = {};
-    for (const key of Object.keys(error)) {
-      if (error[key] !== void 0) {
-        properties[key] = encodeWire(error[key], depth + 1);
-      }
-    }
-    const encodedError = [TAG, "error", error.name, error.message, properties];
-    if (error.cause !== void 0) {
-      encodedError.push(encodeWire(error.cause, depth + 1));
-    }
-    return encodedError;
-  }
-  if (value instanceof URL) {
-    return [TAG, "url", value.href];
-  }
-  if (value instanceof Map) {
-    return [TAG, "map", [...value.entries()].map(([k, v]) => [encodeWire(k, depth + 1), encodeWire(v, depth + 1)])];
-  }
-  if (value instanceof Set) {
-    return [TAG, "set", [...value].map((item) => encodeWire(item, depth + 1))];
-  }
-  if (value instanceof ArrayBuffer) {
-    return [TAG, "bytes", toBase64(new Uint8Array(value)), "ArrayBuffer"];
-  }
-  if (ArrayBuffer.isView(value)) {
-    const view = value;
-    const ctorName = view.constructor.name;
-    const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
-    return ctorName === "Uint8Array" ? [TAG, "bytes", toBase64(bytes)] : [TAG, "bytes", toBase64(bytes), ctorName];
-  }
-  if (Array.isArray(value)) {
-    const encoded = value.map((item) => encodeWire(item, depth + 1));
-    return encoded.length > 0 && encoded[0] === TAG ? [TAG, "arr", encoded] : encoded;
-  }
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== null && proto !== Object.prototype) {
-    const name = value.constructor?.name ?? "value";
-    throw new TypeError(
-      `wire-codec: cannot encode a ${name} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`
-    );
-  }
-  const source = value;
-  const result = {};
-  for (const key of Object.keys(source)) {
-    const field = source[key];
-    if (field !== void 0) {
-      result[key] = encodeWire(field, depth + 1);
-    }
-  }
-  return result;
-};
-const decodeWire = (value, depth = 0) => {
-  if (depth > MAX_DEPTH) {
-    throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
-  }
-  if (value === null || typeof value !== "object") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    if (value[0] === TAG) {
-      const tag = value[1];
-      switch (tag) {
-        case "-inf": {
-          return -Infinity;
-        }
-        case "arr": {
-          return value[2].map((item) => decodeWire(item, depth + 1));
-        }
-        case "bigint": {
-          const raw = value[2];
-          if (typeof raw !== "string" || raw.length > MAX_BIGINT_DIGITS || !/^-?\d+$/.test(raw)) {
-            throw new RangeError(`wire-codec: invalid or over-long bigint (max ${MAX_BIGINT_DIGITS} digits)`);
-          }
-          return BigInt(raw);
-        }
-        case "date": {
-          return new Date(decodeWire(value[2], depth + 1));
-        }
-        case "map": {
-          return new Map(value[2].map(([k, v]) => [decodeWire(k, depth + 1), decodeWire(v, depth + 1)]));
-        }
-        case "set": {
-          return new Set(value[2].map((item) => decodeWire(item, depth + 1)));
-        }
-        case "url": {
-          return new URL(value[2]);
-        }
-        case "error": {
-          const name = value[2];
-          const message = value[3];
-          const Ctor = (Object.hasOwn(ERROR_CTORS, name) ? ERROR_CTORS[name] : void 0) ?? Error;
-          const error = new Ctor(message);
-          if (error.name !== name) {
-            Object.defineProperty(error, "name", { configurable: true, value: name, writable: true });
-          }
-          const props = decodeWire(value[4], depth + 1);
-          for (const key of Object.keys(props)) {
-            if (key === UNSAFE_KEY) {
-              Object.defineProperty(error, key, { configurable: true, enumerable: true, value: props[key], writable: true });
-            } else {
-              error[key] = props[key];
-            }
-          }
-          if (value.length > 5) {
-            Object.defineProperty(error, "cause", { configurable: true, value: decodeWire(value[5], depth + 1), writable: true });
-          }
-          return error;
-        }
-        case "bytes": {
-          const bytes = fromBase64(value[2]);
-          const ctorName = value[3] ?? "Uint8Array";
-          if (ctorName === "ArrayBuffer") {
-            return bytes.buffer.byteLength === bytes.byteLength ? bytes.buffer : bytes.slice().buffer;
-          }
-          const Ctor = Object.hasOwn(TYPED_ARRAY_CTORS, ctorName) ? TYPED_ARRAY_CTORS[ctorName] : void 0;
-          return Ctor ? new Ctor(bytes.slice().buffer) : bytes;
-        }
-        case "inf": {
-          return Infinity;
-        }
-        case "nan": {
-          return Number.NaN;
-        }
-        case "undefined": {
-          return void 0;
-        }
-        default: {
-          return value.map((item) => decodeWire(item, depth + 1));
-        }
-      }
-    }
-    return value.map((item) => decodeWire(item, depth + 1));
-  }
-  const source = value;
-  const result = {};
-  for (const key of Object.keys(source)) {
-    const decoded = decodeWire(source[key], depth + 1);
-    if (key === UNSAFE_KEY) {
-      Object.defineProperty(result, key, { configurable: true, enumerable: true, value: decoded, writable: true });
-    } else {
-      result[key] = decoded;
-    }
-  }
-  return result;
-};
-
 class Listeners {
   listeners = /* @__PURE__ */ new Set();
   add(listener) {
@@ -463,11 +244,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 +283,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 +330,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 +431,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 +503,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(() => {
+        });
       });
     }
   }
@@ -791,8 +669,10 @@ class LunoraClient {
    * Replace the token appended to WS upgrade URLs as `?token=…` and close
    * every open shard socket so the reconnect picks up the new value. Call
    * this whenever the user's WS credential changes (rotating the admin token
-   * in the studio, switching workspaces, etc.). Bearer tokens for HTTP
-   * RPC are independent — see {@link setAuthToken}.
+   * in the studio, switching workspaces, etc.). Accepts a static string or a
+   * {@link WsTokenProvider} resolved fresh at every (re)connect — the channel
+   * for short-lived credentials like the minted ephemeral admin sub-token.
+   * Bearer tokens for HTTP RPC are independent — see {@link setAuthToken}.
    */
   setWsToken(token) {
     if (this.wsToken === token) {
@@ -1008,6 +888,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 : stableWireKey(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 stableWireKey(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 = stableWireKey(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 +1114,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;
@@ -1296,8 +1313,10 @@ class LunoraClient {
    * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
    * WebSocket. `onJobs` fires with the full list on connect and on every
    * change (schedule / cancel / alarm-fire). Reconnects with the client's
-   * configured backoff. Requires `wsToken` to be set to the admin token (the
-   * browser can't send an `Authorization` header on a WS). Returns an
+   * configured backoff. Requires `wsToken` to be set to an admin credential
+   * (the browser can't send an `Authorization` header on a WS) — the master
+   * token, or preferably a {@link WsTokenProvider} minting the ephemeral
+   * sub-token so the master credential stays out of the URL. Returns an
    * unsubscribe function that closes the socket and stops reconnecting.
    */
   subscribeScheduledJobs(onJobs) {
@@ -1312,11 +1331,11 @@ class LunoraClient {
     let socket;
     let timer;
     let closed = false;
-    const connect = () => {
+    const openWith = (token) => {
       if (closed || this.WebSocketImpl === void 0) {
         return;
       }
-      const url = this.wsToken === void 0 ? base : `${base}?token=${encodeURIComponent(this.wsToken)}`;
+      const url = token === void 0 ? base : `${base}?token=${encodeURIComponent(token)}`;
       socket = new this.WebSocketImpl(url);
       socket.addEventListener("open", () => {
         reconnect.reset();
@@ -1339,6 +1358,29 @@ class LunoraClient {
       socket.addEventListener("error", () => {
       });
     };
+    const connectWithProvider = async (provider) => {
+      let token;
+      try {
+        token = await provider();
+      } catch {
+        if (!closed) {
+          timer = setTimeout(connect, reconnect.next());
+        }
+        return;
+      }
+      openWith(token);
+    };
+    const connect = () => {
+      if (closed || this.WebSocketImpl === void 0) {
+        return;
+      }
+      const { wsToken } = this;
+      if (typeof wsToken === "function") {
+        connectWithProvider(wsToken).catch(() => void 0);
+        return;
+      }
+      openWith(wsToken);
+    };
     connect();
     return () => {
       closed = true;
@@ -1905,7 +1947,7 @@ class LunoraClient {
     if (!state) {
       this.nextSubId += 1;
       const id = `sub_${this.nextSubId.toString()}`;
-      const argsKey = stableStringify(argsRecord);
+      const argsKey = stableWireKey(argsRecord);
       const cached = this.takeHydratedCache(function_.__lunoraRef, argsKey, options.shardKey);
       state = {
         acked: false,
@@ -1985,7 +2027,10 @@ class LunoraClient {
       name: shape.name,
       onCheckpoint: options.onCheckpoint,
       rows: /* @__PURE__ */ new Map(),
-      shardKey: options.shardKey
+      shardKey: options.shardKey,
+      // Encode ONCE, here, so an unsupported arg value throws at this call
+      // site instead of inside a reconnect's open handler.
+      wireArgs: shape.args === void 0 ? void 0 : encodeCallArgs(shape.args, `shape args for '${shape.name}'`)
     };
     this.shapeSubscriptions.set(id, state);
     this.ensureSocket(options.shardKey);
@@ -2069,6 +2114,39 @@ class LunoraClient {
     }
     return iterable;
   }
+  /**
+   * Open a typed **HTTP-SSE route stream** (`httpRoute.&lt;verb>(path).stream()`).
+   * Distinct from {@link LunoraClient.stream}, which consumes the WS procedure
+   * stream (`kind: "stream"`): this one opens the route's own URL with `fetch`
+   * and parses the Server-Sent Events framing the route pump writes (`data:`
+   * chunks, a final `event: complete`, an `event: error` on throw).
+   *
+   * The reference comes from the generated `httpStreams.*` registry, so the
+   * yielded chunk type is the route handler's yielded type. Cancelling the
+   * returned iterable (or aborting `options.signal`) aborts the fetch, which
+   * the server handler observes via its `signal`. The client's bearer token
+   * (when set) rides as an `authorization` header.
+   * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+   */
+  httpStream(route, args, options = {}) {
+    if (this.closed) {
+      throw new LunoraError("CLIENT_CLOSED", "LunoraClient is closed");
+    }
+    if (!this.fetchImpl) {
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
+    }
+    const headers = {
+      ...this.authToken ? { authorization: `Bearer ${this.authToken}` } : {},
+      ...options.headers
+    };
+    return httpStream(route, args, {
+      baseUrl: this.url,
+      fetch: this.fetchImpl,
+      headers,
+      maxBuffer: options.maxBuffer,
+      signal: options.signal
+    });
+  }
   close() {
     this.closed = true;
     this.outboxLeaderRelease?.();
@@ -2113,6 +2191,8 @@ class LunoraClient {
     this.whisperHandlers.clear();
     this.shapeSubscriptions.clear();
     this.pokeBuffers.clear();
+    this.tabCoordinator?.stop();
+    this.tabCoordinator = void 0;
   }
   // --- Internals ----------------------------------------------------------
   /**
@@ -2126,7 +2206,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 +2244,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) => {
@@ -2424,13 +2506,13 @@ class LunoraClient {
     }
     return conn;
   }
-  wsUrlFor(shardKey) {
+  wsUrlFor(shardKey, token) {
     const params = [];
     if (shardKey !== void 0) {
       params.push(`shard=${encodeURIComponent(shardKey)}`);
     }
-    if (this.wsToken !== void 0) {
-      params.push(`token=${encodeURIComponent(this.wsToken)}`);
+    if (token !== void 0) {
+      params.push(`token=${encodeURIComponent(token)}`);
     }
     if (params.length === 0) {
       return this.wsUrl;
@@ -2618,13 +2700,49 @@ 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;
     }
     conn.wsState = "connecting";
     this.emitConnectionStatus();
-    const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey));
+    if (typeof this.wsToken === "function") {
+      this.openSocketWithProvidedToken(conn, shardKey, this.wsToken).catch(() => void 0);
+      return;
+    }
+    this.openSocket(conn, shardKey, this.wsToken);
+  }
+  /**
+   * Resolve the {@link WsTokenProvider} and open the shard socket with the
+   * minted token. The connection is already in the `connecting` state, so the
+   * async gap is race-guarded: a client `close()`, a `setWsToken` bounce, or a
+   * competing connect that landed first all abandon this attempt. A provider
+   * failure fails the attempt through {@link handleDisconnect}, which arms the
+   * normal reconnect backoff — a broken mint endpoint degrades to retries, not
+   * a silent tokenless socket the admin gate would reject.
+   */
+  async openSocketWithProvidedToken(conn, shardKey, provider) {
+    let token;
+    try {
+      token = await provider();
+    } catch {
+      this.handleDisconnect(conn);
+      return;
+    }
+    if (this.closed || this.WebSocketImpl === void 0 || conn.wsState !== "connecting" || conn.socket !== void 0) {
+      return;
+    }
+    this.openSocket(conn, shardKey, token);
+  }
+  /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  openSocket(conn, shardKey, token) {
+    if (this.WebSocketImpl === void 0) {
+      return;
+    }
+    const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey, token));
     conn.socket = socket;
     if (this.connectTimeoutMs > 0) {
       conn.connectTimer = setTimeout(() => {
@@ -2786,7 +2904,12 @@ class LunoraClient {
       // sub (a hydrated read or an earlier frame), so the server can
       // resume instead of re-snapshotting. Omitted on a cold sub.
       query: {
-        args: state.args,
+        // Wire-encode so a `bigint`/`Date`/bytes arg survives the frame's
+        // `JSON.stringify` (the shard `decodeWire`s at its subscribe entry
+        // point). Identity for pure-JSON args. Cannot throw here: the
+        // registry key (`stableWireKey`) already encoded these args at
+        // subscribe() time, so reconnect resends stay safe.
+        args: encodeWire(state.args),
         functionPath: state.fn.__lunoraRef,
         table,
         ...state.serverCursor === void 0 ? {} : { sinceSeq: state.serverCursor },
@@ -2802,7 +2925,11 @@ class LunoraClient {
     }
     sendOn(conn, {
       id: state.id,
-      shape: { name: state.name, ...state.args === void 0 ? {} : { args: state.args } },
+      // `wireArgs` is the pre-encoded form of `args` (computed at
+      // `subscribeShape` time) so a `bigint`/`Date`/bytes arg survives the
+      // frame's `JSON.stringify`; the shard `decodeWire`s it at its
+      // `shape_subscribe` entry point. Identity for pure-JSON args.
+      shape: { name: state.name, ...state.wireArgs === void 0 ? {} : { args: state.wireArgs } },
       type: "shape_subscribe",
       // Resume from the last applied checkpoint when we hold one; a cold
       // subscribe omits it and the server seeds the full membership.
@@ -2979,6 +3106,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 +3348,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) {