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

package/dist/packem_shared/createClientQuery-CQ51bWAE.mjs

@@ -0,0 +1,71 @@
+class ClientQueryStore {
+  /** Current values, keyed by the ref's stable key. Absent = never set. */
+  values = /* @__PURE__ */ new Map();
+  /** Subscribers keyed by ref key — notified on every set. */
+  subscribers = /* @__PURE__ */ new Map();
+  /**
+   * Return the current value for `ref`, or `ref.defaultValue` if none has
+   * been set explicitly. Returns `ref.defaultValue` when the slot has been
+   * set to `undefined` (which is distinct from "never set").
+   */
+  get(ref) {
+    if (this.values.has(ref.key)) {
+      return this.values.get(ref.key);
+    }
+    return ref.defaultValue;
+  }
+  /**
+   * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+   * to reset the slot to `ref.defaultValue`.
+   */
+  set(ref, value) {
+    this.values.set(ref.key, value);
+    this.notify(ref.key);
+  }
+  /**
+   * Delete the stored value for `ref`, resetting to `ref.defaultValue` and
+   * notifying subscribers.
+   */
+  reset(ref) {
+    this.values.delete(ref.key);
+    this.notify(ref.key);
+  }
+  /**
+   * Subscribe to changes for `ref`. The callback is NOT invoked on
+   * registration — callers should read the current value via
+   * {@link get} first. Returns an unsubscribe function.
+   */
+  subscribe(ref, callback) {
+    let subs = this.subscribers.get(ref.key);
+    if (!subs) {
+      subs = /* @__PURE__ */ new Set();
+      this.subscribers.set(ref.key, subs);
+    }
+    subs.add(callback);
+    return () => {
+      subs.delete(callback);
+      if (subs.size === 0) {
+        this.subscribers.delete(ref.key);
+      }
+    };
+  }
+  /** Notify every subscriber of a value change for the given key. */
+  notify(key) {
+    const subs = this.subscribers.get(key);
+    if (!subs) {
+      return;
+    }
+    const value = this.values.get(key);
+    for (const callback of subs) {
+      try {
+        callback(value);
+      } catch {
+      }
+    }
+  }
+}
+const createClientQuery = (key, defaultValue) => {
+  return { defaultValue, key };
+};
+
+export { ClientQueryStore, createClientQuery };

package/dist/packem_shared/createLocalStore-BDbbkoXw.mjs

@@ -0,0 +1,2 @@
+export { c as createLocalStore } from './local-store-DtcIW4c0.mjs';
+import './SubscriptionRegistry-D4jfIzZu.mjs';

package/dist/packem_shared/createReply-lI4tVS2w.mjs

@@ -0,0 +1,36 @@
+const sendToSw = (sw, message, expectResponse = false) => new Promise((resolve, reject) => {
+  if (!sw) {
+    reject(new Error("No active service worker"));
+    return;
+  }
+  const id = message.correlationId ?? crypto.randomUUID();
+  const outgoingMessage = { ...message, correlationId: id };
+  if (expectResponse) {
+    let timer;
+    const handler = (event) => {
+      if (event.data.correlationId === id) {
+        clearTimeout(timer);
+        navigator.serviceWorker.removeEventListener("message", handler);
+        resolve(event.data.payload);
+      }
+    };
+    timer = setTimeout(() => {
+      navigator.serviceWorker.removeEventListener("message", handler);
+      reject(new Error(`SW message ${id} timed out`));
+    }, 3e4);
+    navigator.serviceWorker.addEventListener("message", handler);
+    sw.postMessage(outgoingMessage);
+  } else {
+    sw.postMessage(outgoingMessage);
+    resolve(void 0);
+  }
+});
+const createReply = (original, payload) => {
+  return {
+    type: `${original.type}:reply`,
+    payload,
+    correlationId: original.correlationId
+  };
+};
+
+export { createReply, sendToSw };

package/dist/packem_shared/{createServerClient-DF-3mLmb.mjs → createServerClient-Dxemst5C.mjs}

@@ -1,4 +1,4 @@
-import { LunoraClient } from './LunoraClient-kXpHNyaE.mjs';
+import { LunoraClient } from './LunoraClient-Clb118SU.mjs';
 
 const createServerClient = (options) => {
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });

package/dist/packem_shared/createSnapshotPrecondition-CBwnVz6r.mjs

@@ -0,0 +1,18 @@
+import { s as stableStringify } from './stable-key-wv6eP48B.mjs';
+
+const createSnapshotPrecondition = (client, functionRef, args, shardKey) => {
+  const snapshot = client.peekActiveQueryValue(functionRef.__lunoraRef, args, shardKey);
+  const snapshotKey = snapshot === void 0 ? void 0 : stableStringify(snapshot);
+  return () => {
+    const current = client.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;
+  };
+};
+
+export { createSnapshotPrecondition as default };

package/dist/packem_shared/{local-store-BveBeFEo.mjs → local-store-DtcIW4c0.mjs}

@@ -1,4 +1,4 @@
-import { S as SubscriptionRegistry } from './subscription-BjynOXCU.mjs';
+import { SubscriptionRegistry } from './SubscriptionRegistry-D4jfIzZu.mjs';
 
 const foldOptimistic = (base, layers) => {
   let value = base;

package/dist/packem_shared/{lunora-client.d-BYkEjCEJ.d.mts → lunora-client.d-pw-9sLl0.d.mts}

@@ -1,5 +1,42 @@
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
+* Reactive key-value store for local-only client state.
+*
+* Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
+* an `acked` flag, `serverBase`, optimistic layers, and the full subscription
+* machinery), a `ClientQueryRef` is purely local — no server round-trip, no
+* WebSocket, no persistence. It exists so framework adapters can offer a
+* `useClientQuery` hook whose values survive component remounts and are shared
+* across every consumer of the same ref, with none of the ceremony or coupling
+* of a dedicated context provider.
+*
+* The store lives inside `LunoraClient` (a private field) and is surfaced through
+* `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
+* `subscribeClientQuery(ref, callback)`.
+*/
+/** Opaque handle for a typed client-local query slot. */
+interface ClientQueryRef<T = unknown> {
+  /** Default value when no value has been set explicitly. */
+  readonly defaultValue: T;
+  /** Stable identity for the slot. Must be unique within a client instance. */
+  readonly key: string;
+}
+/** A subscriber callback for value changes to a {@link ClientQueryRef}. */
+
+/**
+* Create a typed {@link ClientQueryRef}. Call once per slot at module scope
+* (or inside a component module) — the ref object is the stable identity.
+* @example
+* ```ts
+* // lunora/client-queries.ts
+* import { createClientQuery } from "@lunora/client";
+*
+* export const sidebarOpen = createClientQuery("sidebarOpen", true);
+* export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
+* ```
+*/
+declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
+/**
 * The machine-readable error codes a client can observe on a failed
 * RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
 * (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
@@ -308,6 +345,16 @@ interface LunoraClientOptions {
   * Defaults to 10000 (10s); set to `0` (or negative) to disable.
   */
   connectTimeoutMs?: number;
+  /**
+  * When `true`, tabs sharing the same origin coordinate via BroadcastChannel
+  * so only one tab (the "leader") opens WebSocket connections to the server.
+  * Follower tabs receive subscription data through the channel instead.
+  *
+  * Reduces simultaneous WS connections, bandwidth, and cross-tab state drift.
+  * Requires `BroadcastChannel` (browser-only); silently ignored otherwise.
+  * Defaults to `false`.
+  */
+  crossTabSync?: boolean;
   fetch?: typeof fetch;
   /**
   * Interval (ms) between keepalive pings sent on each open subscription
@@ -317,6 +364,15 @@ interface LunoraClientOptions {
   * `0` (or a negative value) to disable the heartbeat entirely.
   */
   heartbeatIntervalMs?: number;
+  /**
+  * When `true` and a `queryCache` is active, framework hooks (React, Vue, …)
+  * wait for the durable cache to finish hydrating before their first render
+  * with an enabled subscription, so users see cached data instead of an
+  * undefined flash before the socket round-trip. Defaults to `false`.
+  *
+  * Requires `queryCache` to be set (not `false`); silently ignored otherwise.
+  */
+  hydrateOnStart?: boolean;
   offlineQueue?: OfflineQueueOptions;
   /**
   * Durable outbox seam for offline writes. When supplied (the `@lunora/db`
@@ -1178,6 +1234,14 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
   * once; every write is rolled back atomically if the mutation fails.
   */
   optimisticUpdate?: OptimisticUpdate<TArgs>;
+  /**
+  * Sync predicate evaluated just before the offline queue replays this
+  * write on reconnect. When it returns `false` the mutation is dropped
+  * instead of replayed — use it to guard against replaying writes whose
+  * assumptions are no longer valid (e.g. the document it referred to was
+  * deleted by another client while this tab was offline).
+  */
+  precondition?: () => boolean;
   shardKey?: string;
 }
 /** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
@@ -1226,8 +1290,19 @@ type BatchSlot = {
 declare 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. */
   private static readonly MAX_POKE_BUFFERS;
+  /**
+  * 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<T>(key: string, defaultValue: T): ClientQueryRef<T>;
   readonly url: string;
   readonly wsUrl: string;
+  /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
+  private readonly clientQueryStore;
   private wsToken;
   /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
   private readonly authBasePath;
@@ -1249,6 +1324,20 @@ declare class LunoraClient {
   /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
   private readonly 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.
+  */
+  private readyResolved;
+  /** Resolvers for `whenReady()` — called once hydration completes. */
+  private 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).
+  */
+  private readonly readyPromise;
+  /**
   * Highest custom-mutator watermark the server has echoed for this client,
   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
   * `__client_watermark` per shard. `callMutator` bumps it from every
@@ -1281,6 +1370,12 @@ declare class LunoraClient {
   private readonly pendingCacheWrites;
   private cacheFlushTimer;
   private readonly subscriptions;
+  /**
+  * 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`).
+  */
+  private tabCoordinator;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   private readonly connections;
   /** Default `connect`-envelope context applied to a shard with no explicit override. */
@@ -1559,6 +1654,93 @@ declare class LunoraClient {
   * unsubscribe function. See {@link MutationSettledEvent}.
   */
   onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
+  /**
+  * Read the current value for a {@link ClientQueryRef}. Returns
+  * `ref.defaultValue` when no value has been explicitly set.
+  */
+  getClientQuery<T>(ref: ClientQueryRef<T>): T;
+  /**
+  * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+  * to reset the slot to `ref.defaultValue`.
+  */
+  setClientQuery<T>(ref: ClientQueryRef<T>, value: T): void;
+  /**
+  * 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: ClientQueryRef, callback: (value: unknown) => void): Unsubscribe;
+  /**
+  * 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: ClientQueryRef): void;
+  /**
+  * 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: FunctionReference, args: Record<string, unknown>, shardKey?: string): () => boolean;
+  /**
+  * 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(): Promise<void>;
+  /**
+  * 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(): boolean;
+  /**
+  * 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: string, args: Record<string, unknown>, shardKey?: string): unknown;
+  /**
+  * 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: string, args: Record<string, unknown>, shardKey?: string): unknown;
   query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
     shardKey?: string;
   }): Promise<ReturnOf<F>>;
@@ -2537,4 +2719,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { StreamHandle as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RpcEnvelope as E, FunctionReference as F, GlobalFacetResult as G, RpcResponseBody as H, ScheduleRecord as I, SchedulerPoolStatus as J, SchedulerStatus as K, LunoraClient as L, MutationCallOptions as M, ServerMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeEndMessage as T, User as U, ServerPokePartMessage as V, ServerPokeStartMessage as W, ShardTrafficEntry as X, ShardTrafficResult as Y, StorageListPage as Z, StorageObject as _, Unsubscribe as a, StreamIterable as a0, SubscriptionCallback as a1, SubscriptionRegistry as a2, SubscriptionState as a3, SyncWatermark as a4, WorkflowInstanceAction as a5, WorkflowInstanceDetail as a6, WorkflowInstancePage as a7, WorkflowInstanceStatus as a8, WorkflowInstanceSummary as a9, WorkflowStepDetail as aa, createLocalStore as ab, createStream as ac, getErrorCode as ad, getRetryAfterMs as ae, isConflictError as af, isForbiddenError as ag, isRateLimitedError as ah, isUnauthorizedError as ai, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientShapeSubscribeMessage as h, ClientShapeUnsubscribeMessage as i, ConnectionStatus as j, FunctionArgumentDescriptor as k, FunctionDescriptor as l, GlobalFacetValue as m, GlobalFilterClause as n, GlobalTableInfo as o, GlobalTablePage as p, LunoraClientError as q, LunoraClientOptions as r, LunoraErrorCode as s, MutationSettledEvent as t, OptimisticLocalStore as u, OptimisticUpdate as v, OutboxMutation as w, OutboxSink as x, PersistedMutation as y, RowOp as z };
+export { StorageObject as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RowOp as E, FunctionReference as F, GlobalFacetResult as G, RpcEnvelope as H, RpcResponseBody as I, ScheduleRecord as J, SchedulerPoolStatus as K, LunoraClient as L, MutationCallOptions as M, SchedulerStatus as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerMessage as T, User as U, ServerPokeEndMessage as V, ServerPokePartMessage as W, ServerPokeStartMessage as X, ShardTrafficEntry as Y, ShardTrafficResult as Z, StorageListPage as _, Unsubscribe as a, StreamHandle as a0, StreamIterable as a1, SubscriptionCallback as a2, SubscriptionRegistry as a3, SubscriptionState as a4, SyncWatermark as a5, WorkflowInstanceAction as a6, WorkflowInstanceDetail as a7, WorkflowInstancePage as a8, WorkflowInstanceStatus as a9, WorkflowInstanceSummary as aa, WorkflowStepDetail as ab, createClientQuery as ac, createLocalStore as ad, createStream as ae, getErrorCode as af, getRetryAfterMs as ag, isConflictError as ah, isForbiddenError as ai, isRateLimitedError as aj, isUnauthorizedError as ak, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientQueryRef as h, ClientShapeSubscribeMessage as i, ClientShapeUnsubscribeMessage as j, ConnectionStatus as k, FunctionArgumentDescriptor as l, FunctionDescriptor as m, GlobalFacetValue as n, GlobalFilterClause as o, GlobalTableInfo as p, GlobalTablePage as q, LunoraClientError as r, LunoraClientOptions as s, LunoraErrorCode as t, MutationSettledEvent as u, OptimisticLocalStore as v, OptimisticUpdate as w, OutboxMutation as x, OutboxSink as y, PersistedMutation as z };

package/dist/packem_shared/{lunora-client.d-BYkEjCEJ.d.ts → lunora-client.d-pw-9sLl0.d.ts}

@@ -1,5 +1,42 @@
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
+* Reactive key-value store for local-only client state.
+*
+* Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
+* an `acked` flag, `serverBase`, optimistic layers, and the full subscription
+* machinery), a `ClientQueryRef` is purely local — no server round-trip, no
+* WebSocket, no persistence. It exists so framework adapters can offer a
+* `useClientQuery` hook whose values survive component remounts and are shared
+* across every consumer of the same ref, with none of the ceremony or coupling
+* of a dedicated context provider.
+*
+* The store lives inside `LunoraClient` (a private field) and is surfaced through
+* `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
+* `subscribeClientQuery(ref, callback)`.
+*/
+/** Opaque handle for a typed client-local query slot. */
+interface ClientQueryRef<T = unknown> {
+  /** Default value when no value has been set explicitly. */
+  readonly defaultValue: T;
+  /** Stable identity for the slot. Must be unique within a client instance. */
+  readonly key: string;
+}
+/** A subscriber callback for value changes to a {@link ClientQueryRef}. */
+
+/**
+* Create a typed {@link ClientQueryRef}. Call once per slot at module scope
+* (or inside a component module) — the ref object is the stable identity.
+* @example
+* ```ts
+* // lunora/client-queries.ts
+* import { createClientQuery } from "@lunora/client";
+*
+* export const sidebarOpen = createClientQuery("sidebarOpen", true);
+* export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
+* ```
+*/
+declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
+/**
 * The machine-readable error codes a client can observe on a failed
 * RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
 * (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
@@ -308,6 +345,16 @@ interface LunoraClientOptions {
   * Defaults to 10000 (10s); set to `0` (or negative) to disable.
   */
   connectTimeoutMs?: number;
+  /**
+  * When `true`, tabs sharing the same origin coordinate via BroadcastChannel
+  * so only one tab (the "leader") opens WebSocket connections to the server.
+  * Follower tabs receive subscription data through the channel instead.
+  *
+  * Reduces simultaneous WS connections, bandwidth, and cross-tab state drift.
+  * Requires `BroadcastChannel` (browser-only); silently ignored otherwise.
+  * Defaults to `false`.
+  */
+  crossTabSync?: boolean;
   fetch?: typeof fetch;
   /**
   * Interval (ms) between keepalive pings sent on each open subscription
@@ -317,6 +364,15 @@ interface LunoraClientOptions {
   * `0` (or a negative value) to disable the heartbeat entirely.
   */
   heartbeatIntervalMs?: number;
+  /**
+  * When `true` and a `queryCache` is active, framework hooks (React, Vue, …)
+  * wait for the durable cache to finish hydrating before their first render
+  * with an enabled subscription, so users see cached data instead of an
+  * undefined flash before the socket round-trip. Defaults to `false`.
+  *
+  * Requires `queryCache` to be set (not `false`); silently ignored otherwise.
+  */
+  hydrateOnStart?: boolean;
   offlineQueue?: OfflineQueueOptions;
   /**
   * Durable outbox seam for offline writes. When supplied (the `@lunora/db`
@@ -1178,6 +1234,14 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
   * once; every write is rolled back atomically if the mutation fails.
   */
   optimisticUpdate?: OptimisticUpdate<TArgs>;
+  /**
+  * Sync predicate evaluated just before the offline queue replays this
+  * write on reconnect. When it returns `false` the mutation is dropped
+  * instead of replayed — use it to guard against replaying writes whose
+  * assumptions are no longer valid (e.g. the document it referred to was
+  * deleted by another client while this tab was offline).
+  */
+  precondition?: () => boolean;
   shardKey?: string;
 }
 /** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
@@ -1226,8 +1290,19 @@ type BatchSlot = {
 declare 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. */
   private static readonly MAX_POKE_BUFFERS;
+  /**
+  * 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<T>(key: string, defaultValue: T): ClientQueryRef<T>;
   readonly url: string;
   readonly wsUrl: string;
+  /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
+  private readonly clientQueryStore;
   private wsToken;
   /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
   private readonly authBasePath;
@@ -1249,6 +1324,20 @@ declare class LunoraClient {
   /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
   private readonly 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.
+  */
+  private readyResolved;
+  /** Resolvers for `whenReady()` — called once hydration completes. */
+  private 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).
+  */
+  private readonly readyPromise;
+  /**
   * Highest custom-mutator watermark the server has echoed for this client,
   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
   * `__client_watermark` per shard. `callMutator` bumps it from every
@@ -1281,6 +1370,12 @@ declare class LunoraClient {
   private readonly pendingCacheWrites;
   private cacheFlushTimer;
   private readonly subscriptions;
+  /**
+  * 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`).
+  */
+  private tabCoordinator;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   private readonly connections;
   /** Default `connect`-envelope context applied to a shard with no explicit override. */
@@ -1559,6 +1654,93 @@ declare class LunoraClient {
   * unsubscribe function. See {@link MutationSettledEvent}.
   */
   onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
+  /**
+  * Read the current value for a {@link ClientQueryRef}. Returns
+  * `ref.defaultValue` when no value has been explicitly set.
+  */
+  getClientQuery<T>(ref: ClientQueryRef<T>): T;
+  /**
+  * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+  * to reset the slot to `ref.defaultValue`.
+  */
+  setClientQuery<T>(ref: ClientQueryRef<T>, value: T): void;
+  /**
+  * 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: ClientQueryRef, callback: (value: unknown) => void): Unsubscribe;
+  /**
+  * 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: ClientQueryRef): void;
+  /**
+  * 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: FunctionReference, args: Record<string, unknown>, shardKey?: string): () => boolean;
+  /**
+  * 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(): Promise<void>;
+  /**
+  * 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(): boolean;
+  /**
+  * 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: string, args: Record<string, unknown>, shardKey?: string): unknown;
+  /**
+  * 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: string, args: Record<string, unknown>, shardKey?: string): unknown;
   query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
     shardKey?: string;
   }): Promise<ReturnOf<F>>;
@@ -2537,4 +2719,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { StreamHandle as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RpcEnvelope as E, FunctionReference as F, GlobalFacetResult as G, RpcResponseBody as H, ScheduleRecord as I, SchedulerPoolStatus as J, SchedulerStatus as K, LunoraClient as L, MutationCallOptions as M, ServerMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeEndMessage as T, User as U, ServerPokePartMessage as V, ServerPokeStartMessage as W, ShardTrafficEntry as X, ShardTrafficResult as Y, StorageListPage as Z, StorageObject as _, Unsubscribe as a, StreamIterable as a0, SubscriptionCallback as a1, SubscriptionRegistry as a2, SubscriptionState as a3, SyncWatermark as a4, WorkflowInstanceAction as a5, WorkflowInstanceDetail as a6, WorkflowInstancePage as a7, WorkflowInstanceStatus as a8, WorkflowInstanceSummary as a9, WorkflowStepDetail as aa, createLocalStore as ab, createStream as ac, getErrorCode as ad, getRetryAfterMs as ae, isConflictError as af, isForbiddenError as ag, isRateLimitedError as ah, isUnauthorizedError as ai, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientShapeSubscribeMessage as h, ClientShapeUnsubscribeMessage as i, ConnectionStatus as j, FunctionArgumentDescriptor as k, FunctionDescriptor as l, GlobalFacetValue as m, GlobalFilterClause as n, GlobalTableInfo as o, GlobalTablePage as p, LunoraClientError as q, LunoraClientOptions as r, LunoraErrorCode as s, MutationSettledEvent as t, OptimisticLocalStore as u, OptimisticUpdate as v, OutboxMutation as w, OutboxSink as x, PersistedMutation as y, RowOp as z };
+export { StorageObject as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RowOp as E, FunctionReference as F, GlobalFacetResult as G, RpcEnvelope as H, RpcResponseBody as I, ScheduleRecord as J, SchedulerPoolStatus as K, LunoraClient as L, MutationCallOptions as M, SchedulerStatus as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerMessage as T, User as U, ServerPokeEndMessage as V, ServerPokePartMessage as W, ServerPokeStartMessage as X, ShardTrafficEntry as Y, ShardTrafficResult as Z, StorageListPage as _, Unsubscribe as a, StreamHandle as a0, StreamIterable as a1, SubscriptionCallback as a2, SubscriptionRegistry as a3, SubscriptionState as a4, SyncWatermark as a5, WorkflowInstanceAction as a6, WorkflowInstanceDetail as a7, WorkflowInstancePage as a8, WorkflowInstanceStatus as a9, WorkflowInstanceSummary as aa, WorkflowStepDetail as ab, createClientQuery as ac, createLocalStore as ad, createStream as ae, getErrorCode as af, getRetryAfterMs as ag, isConflictError as ah, isForbiddenError as ai, isRateLimitedError as aj, isUnauthorizedError as ak, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientQueryRef as h, ClientShapeSubscribeMessage as i, ClientShapeUnsubscribeMessage as j, ConnectionStatus as k, FunctionArgumentDescriptor as l, FunctionDescriptor as m, GlobalFacetValue as n, GlobalFilterClause as o, GlobalTableInfo as p, GlobalTablePage as q, LunoraClientError as r, LunoraClientOptions as s, LunoraErrorCode as t, MutationSettledEvent as u, OptimisticLocalStore as v, OptimisticUpdate as w, OutboxMutation as x, OutboxSink as y, PersistedMutation as z };