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

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-BYkEjCEJ.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-pw-9sLl0.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-BYkEjCEJ.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-pw-9sLl0.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-BYkEjCEJ.mjs";
-export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-BYkEjCEJ.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DrfuisCE.mjs";
+import { c as PersistenceAdapter, B as BookmarkStorage, S as SubscriptionError, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions, L as LunoraClient } from "./packem_shared/lunora-client.d-pw-9sLl0.mjs";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientQueryRef, type i as ClientShapeSubscribeMessage, type j as ClientShapeUnsubscribeMessage, type k as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type l as FunctionArgumentDescriptor, type m as FunctionDescriptor, type G as GlobalFacetResult, type n as GlobalFacetValue, type o as GlobalFilterClause, type p as GlobalTableInfo, type q as GlobalTablePage, type r as LunoraClientError, type s as LunoraClientOptions, type t as LunoraErrorCode, type u as MutationSettledEvent, type v as OptimisticLocalStore, type w as OptimisticUpdate, type x as OutboxMutation, type y as OutboxSink, type z as PersistedMutation, type P as Preloaded, type E as RowOp, type H as RpcEnvelope, type I as RpcResponseBody, type J as ScheduleRecord, type K as SchedulerPoolStatus, type N as SchedulerStatus, type T as ServerMessage, type V as ServerPokeEndMessage, type W as ServerPokePartMessage, type X as ServerPokeStartMessage, type Y as ShardTrafficEntry, type Z as ShardTrafficResult, type _ as StorageListPage, type $ as StorageObject, type a0 as StreamHandle, type a1 as StreamIterable, type a2 as SubscriptionCallback, type b as SubscriptionErrorCallback, a3 as SubscriptionRegistry, type a4 as SubscriptionState, type a5 as SyncWatermark, type a as Unsubscribe, type U as User, type a6 as WorkflowInstanceAction, type a7 as WorkflowInstanceDetail, type a8 as WorkflowInstancePage, type a9 as WorkflowInstanceStatus, type aa as WorkflowInstanceSummary, type ab as WorkflowStepDetail, ac as createClientQuery, ad as createLocalStore, ae as createStream, af as getErrorCode, ag as getRetryAfterMs, ah as isConflictError, ai as isForbiddenError, aj as isRateLimitedError, ak as isUnauthorizedError } from "./packem_shared/lunora-client.d-pw-9sLl0.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-6ME5ubgq.mjs";
 export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -33,6 +33,92 @@ interface AsyncStoragePersistenceOptions {
 declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => PersistenceAdapter;
 /** Default in-memory bookmark store. Survives the lifetime of the client. */
 declare const createInMemoryBookmarkStorage: () => BookmarkStorage;
+interface TabCoordinatorOptions {
+  /**
+  * BroadcastChannel name. Defaults to `"lunora-bridge"`.
+  */
+  channelName?: string;
+  /**
+  * Interval (ms) between leader heartbeats. Defaults to 1000.
+  */
+  heartbeatInterval?: number;
+  /**
+  * Milliseconds without a heartbeat to consider the leader dead. Must be
+  * larger than `heartbeatInterval`. Defaults to 3000.
+  */
+  leaderTimeout?: number;
+  /**
+  * Called when this tab becomes the leader (should open WS connections).
+  */
+  onBecomeLeader?: () => void;
+  /**
+  * Called when this tab loses leadership (should close WS connections).
+  */
+  onStopBeingLeader?: () => void;
+  /**
+  * Called when the leader broadcasts subscription data.
+  */
+  onSubscriptionData?: (key: string, data: unknown) => void;
+  /**
+  * Called when the leader broadcasts a subscription error.
+  */
+  onSubscriptionError?: (key: string, error: SubscriptionError) => void;
+}
+declare class TabCoordinator {
+  private readonly bc;
+  private readonly tabId;
+  private readonly heartbeatInterval;
+  private readonly leaderTimeout;
+  /** The tab id of the current known leader, or `undefined` if no leader. */
+  private knownLeader;
+  /** `true` when this tab believes it is the leader. */
+  private leader;
+  /** `true` once `start()` has been called. */
+  private running;
+  /** Timestamp of the most recent leader heartbeat. */
+  private lastHeartbeat;
+  private heartbeatTimer;
+  private leaderCheckTimer;
+  /** Callbacks set via constructor options. */
+  private readonly onBecomeLeader;
+  private readonly onStopBeingLeader;
+  private readonly onSubscriptionData;
+  private readonly onSubscriptionError;
+  constructor(options?: TabCoordinatorOptions);
+  /**
+  * Start the coordinator: attempt to claim leadership and begin the
+  * heartbeat/leader-check cycle. Safe to call multiple times.
+  */
+  start(): void;
+  /**
+  * Stop the coordinator: yield leadership (if held), close the channel, and
+  * clear all timers. Safe to call multiple times.
+  */
+  stop(): void;
+  /** `true` when this tab is the current WebSocket leader. */
+  isLeader(): boolean;
+  /** The tab id of the current leader, or `undefined` if unknown / no leader. */
+  get leaderTabId(): string | undefined;
+  /** The id of this tab. */
+  get id(): string;
+  /** `true` when the coordinator has been started and is not yet stopped. */
+  get isRunning(): boolean;
+  /**
+  * Broadcast subscription data to all follower tabs. Only the leader should
+  * call this.
+  */
+  broadcastSubscriptionData(key: string, data: unknown): void;
+  /**
+  * Broadcast a subscription error to all follower tabs. Only the leader
+  * should call this.
+  */
+  broadcastSubscriptionError(key: string, error: SubscriptionError): void;
+  private broadcast;
+  private handleMessage;
+  private becomeLeader;
+  private sendHeartbeat;
+  private checkLeaderHealth;
+}
 /**
 * Client-side incremental merging of structured mutation deltas.
 *
@@ -202,6 +288,14 @@ interface QueuedMutation<T = unknown> {
   * Absent on hydrated records (the optimistic write lived in a prior session).
   */
   readonly onCommit?: (commitCursor: number | undefined) => void;
+  /**
+  * Optional sync predicate evaluated just before replay. When it returns
+  * `false` the write is dropped instead of replaying, handling the case
+  * where the mutation's preconditions are no longer valid (e.g. the
+  * document it referred to was deleted while offline). Absent or `true`
+  * means "ok to replay".
+  */
+  readonly precondition?: () => boolean;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
@@ -288,6 +382,16 @@ declare class OfflineQueue {
   * transport failure: the unreplayed writes stay queued for the next reconnect.
   */
   requeue(items: QueuedMutation[]): void;
+  /**
+  * Remove mutations whose precondition evaluates to `false` (stale/dirty
+  * writes that should not replay) and reject each with an
+  * `OFFLINE_PRECONDITION_FAILED` error. The valid (admitted) mutations stay
+  * queued in FIFO order. Returns the drained stale entries.
+  *
+  * Called during reconnect before the flush cycle to weed out writes whose
+  * assumptions no longer hold (e.g. a document was deleted by another client).
+  */
+  drainConflict(): QueuedMutation[];
   clear(): void;
   /** Notify the size observer (the client's pending-sync count) after any change. */
   private notifySize;
@@ -398,4 +502,108 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };
+/**
+* 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.
+*
+* When the precondition is checked (on queue drain / reconnect) it re-reads the
+* query's current value via {@link LunoraClient.peekActiveQueryValue}. If the
+* value differs from what was captured at call time the precondition returns
+* `false` and the offline mutation is dropped as stale.
+* @example
+* ```ts
+* client.mutation(api.todos.update, { id, text }, {
+*   precondition: createSnapshotPrecondition(client, api.todos.list, { userId }),
+* });
+* ```
+*/
+declare const createSnapshotPrecondition: (client: LunoraClient, functionRef: FunctionReference, args: Record<string, unknown>, shardKey?: string) => (() => boolean);
+/**
+* Client-side service-worker registration and lifecycle management.
+*
+* Usage:
+* ```ts
+* const sw = new ClientServiceWorker({ swUrl: "/sw.js" });
+* await sw.register();
+*
+* if (sw.active) {
+*   sw.postMessage({ type: "sync" });
+* }
+* ```
+*/
+type ServiceWorkerStatus = "unsupported" | "unregistered" | "registering" | "active" | "error";
+interface ClientSwOptions {
+  /** Called when the status changes. */
+  onStatusChange?: (status: ServiceWorkerStatus) => void;
+  /** Optional registration scope. Defaults to `/`. */
+  scope?: string;
+  /** URL of the service worker script (relative to origin). */
+  swUrl: string;
+}
+/**
+* Manages service-worker registration and provides a simple API for
+* sending messages and listening for responses.
+*/
+declare class ClientServiceWorker {
+  #private;
+  readonly swUrl: string;
+  readonly scope: string;
+  constructor(options: ClientSwOptions);
+  /** Current registration status. */
+  get status(): ServiceWorkerStatus;
+  /** The underlying `ServiceWorkerRegistration`, if registered. */
+  get registration(): ServiceWorkerRegistration | undefined;
+  /** Whether the SW is currently controlling this page. */
+  get active(): boolean;
+  /**
+  * Register the service worker.
+  *
+  * Returns `false` when the browser does not support service workers.
+  */
+  register(): Promise<boolean>;
+  /**
+  * Remove the active service worker registration and clear listeners.
+  *
+  * Returns `false` when no registration is currently held.
+  */
+  unregister(): Promise<boolean>;
+  /**
+  * Send a message to the active service worker.
+  */
+  postMessage(message: unknown): void;
+  /**
+  * Register a handler for messages **from** the service worker.
+  * @returns Unsubscribe function.
+  */
+  onMessage(handler: (event: MessageEvent) => void): () => void;
+}
+/**
+* Outbound message from the client to the SW.
+*/
+interface ClientToSwMessage {
+  /** Opaque correlation ID for request/response patterns. */
+  correlationId?: string;
+  payload?: unknown;
+  type: string;
+}
+/**
+* Inbound message from the SW to the client.
+*/
+interface SwToClientMessage {
+  /** Echoes the correlation ID from the client request, if any. */
+  correlationId?: string;
+  payload?: unknown;
+  type: string;
+}
+/**
+* Send a typed message to the service worker and optionally await a
+* matching response.
+* @returns A promise that resolves when the SW sends a reply with the
+* same `correlationId` (if `expectResponse` is true).
+*/
+declare const sendToSw: (sw: ServiceWorker | null, message: ClientToSwMessage, expectResponse?: boolean) => Promise<unknown>;
+/**
+* Create a reply for a client message (call from inside the SW).
+*/
+declare const createReply: (original: ClientToSwMessage, payload?: unknown) => SwToClientMessage;
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, ClientServiceWorker, type ClientSwOptions, type ClientToSwMessage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, LunoraClient, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, type ServiceWorkerStatus, type SubscriptionError, type SwToClientMessage, TabCoordinator, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, createReply, createSnapshotPrecondition, isMutationDelta, queryCacheKey, sendToSw };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-BYkEjCEJ.js";
-export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-BYkEjCEJ.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-B-vyHnml.js";
+import { c as PersistenceAdapter, B as BookmarkStorage, S as SubscriptionError, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions, L as LunoraClient } from "./packem_shared/lunora-client.d-pw-9sLl0.js";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientQueryRef, type i as ClientShapeSubscribeMessage, type j as ClientShapeUnsubscribeMessage, type k as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type l as FunctionArgumentDescriptor, type m as FunctionDescriptor, type G as GlobalFacetResult, type n as GlobalFacetValue, type o as GlobalFilterClause, type p as GlobalTableInfo, type q as GlobalTablePage, type r as LunoraClientError, type s as LunoraClientOptions, type t as LunoraErrorCode, type u as MutationSettledEvent, type v as OptimisticLocalStore, type w as OptimisticUpdate, type x as OutboxMutation, type y as OutboxSink, type z as PersistedMutation, type P as Preloaded, type E as RowOp, type H as RpcEnvelope, type I as RpcResponseBody, type J as ScheduleRecord, type K as SchedulerPoolStatus, type N as SchedulerStatus, type T as ServerMessage, type V as ServerPokeEndMessage, type W as ServerPokePartMessage, type X as ServerPokeStartMessage, type Y as ShardTrafficEntry, type Z as ShardTrafficResult, type _ as StorageListPage, type $ as StorageObject, type a0 as StreamHandle, type a1 as StreamIterable, type a2 as SubscriptionCallback, type b as SubscriptionErrorCallback, a3 as SubscriptionRegistry, type a4 as SubscriptionState, type a5 as SyncWatermark, type a as Unsubscribe, type U as User, type a6 as WorkflowInstanceAction, type a7 as WorkflowInstanceDetail, type a8 as WorkflowInstancePage, type a9 as WorkflowInstanceStatus, type aa as WorkflowInstanceSummary, type ab as WorkflowStepDetail, ac as createClientQuery, ad as createLocalStore, ae as createStream, af as getErrorCode, ag as getRetryAfterMs, ah as isConflictError, ai as isForbiddenError, aj as isRateLimitedError, ak as isUnauthorizedError } from "./packem_shared/lunora-client.d-pw-9sLl0.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-BkQr-3Vh.js";
 export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -33,6 +33,92 @@ interface AsyncStoragePersistenceOptions {
 declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => PersistenceAdapter;
 /** Default in-memory bookmark store. Survives the lifetime of the client. */
 declare const createInMemoryBookmarkStorage: () => BookmarkStorage;
+interface TabCoordinatorOptions {
+  /**
+  * BroadcastChannel name. Defaults to `"lunora-bridge"`.
+  */
+  channelName?: string;
+  /**
+  * Interval (ms) between leader heartbeats. Defaults to 1000.
+  */
+  heartbeatInterval?: number;
+  /**
+  * Milliseconds without a heartbeat to consider the leader dead. Must be
+  * larger than `heartbeatInterval`. Defaults to 3000.
+  */
+  leaderTimeout?: number;
+  /**
+  * Called when this tab becomes the leader (should open WS connections).
+  */
+  onBecomeLeader?: () => void;
+  /**
+  * Called when this tab loses leadership (should close WS connections).
+  */
+  onStopBeingLeader?: () => void;
+  /**
+  * Called when the leader broadcasts subscription data.
+  */
+  onSubscriptionData?: (key: string, data: unknown) => void;
+  /**
+  * Called when the leader broadcasts a subscription error.
+  */
+  onSubscriptionError?: (key: string, error: SubscriptionError) => void;
+}
+declare class TabCoordinator {
+  private readonly bc;
+  private readonly tabId;
+  private readonly heartbeatInterval;
+  private readonly leaderTimeout;
+  /** The tab id of the current known leader, or `undefined` if no leader. */
+  private knownLeader;
+  /** `true` when this tab believes it is the leader. */
+  private leader;
+  /** `true` once `start()` has been called. */
+  private running;
+  /** Timestamp of the most recent leader heartbeat. */
+  private lastHeartbeat;
+  private heartbeatTimer;
+  private leaderCheckTimer;
+  /** Callbacks set via constructor options. */
+  private readonly onBecomeLeader;
+  private readonly onStopBeingLeader;
+  private readonly onSubscriptionData;
+  private readonly onSubscriptionError;
+  constructor(options?: TabCoordinatorOptions);
+  /**
+  * Start the coordinator: attempt to claim leadership and begin the
+  * heartbeat/leader-check cycle. Safe to call multiple times.
+  */
+  start(): void;
+  /**
+  * Stop the coordinator: yield leadership (if held), close the channel, and
+  * clear all timers. Safe to call multiple times.
+  */
+  stop(): void;
+  /** `true` when this tab is the current WebSocket leader. */
+  isLeader(): boolean;
+  /** The tab id of the current leader, or `undefined` if unknown / no leader. */
+  get leaderTabId(): string | undefined;
+  /** The id of this tab. */
+  get id(): string;
+  /** `true` when the coordinator has been started and is not yet stopped. */
+  get isRunning(): boolean;
+  /**
+  * Broadcast subscription data to all follower tabs. Only the leader should
+  * call this.
+  */
+  broadcastSubscriptionData(key: string, data: unknown): void;
+  /**
+  * Broadcast a subscription error to all follower tabs. Only the leader
+  * should call this.
+  */
+  broadcastSubscriptionError(key: string, error: SubscriptionError): void;
+  private broadcast;
+  private handleMessage;
+  private becomeLeader;
+  private sendHeartbeat;
+  private checkLeaderHealth;
+}
 /**
 * Client-side incremental merging of structured mutation deltas.
 *
@@ -202,6 +288,14 @@ interface QueuedMutation<T = unknown> {
   * Absent on hydrated records (the optimistic write lived in a prior session).
   */
   readonly onCommit?: (commitCursor: number | undefined) => void;
+  /**
+  * Optional sync predicate evaluated just before replay. When it returns
+  * `false` the write is dropped instead of replaying, handling the case
+  * where the mutation's preconditions are no longer valid (e.g. the
+  * document it referred to was deleted while offline). Absent or `true`
+  * means "ok to replay".
+  */
+  readonly precondition?: () => boolean;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
@@ -288,6 +382,16 @@ declare class OfflineQueue {
   * transport failure: the unreplayed writes stay queued for the next reconnect.
   */
   requeue(items: QueuedMutation[]): void;
+  /**
+  * Remove mutations whose precondition evaluates to `false` (stale/dirty
+  * writes that should not replay) and reject each with an
+  * `OFFLINE_PRECONDITION_FAILED` error. The valid (admitted) mutations stay
+  * queued in FIFO order. Returns the drained stale entries.
+  *
+  * Called during reconnect before the flush cycle to weed out writes whose
+  * assumptions no longer hold (e.g. a document was deleted by another client).
+  */
+  drainConflict(): QueuedMutation[];
   clear(): void;
   /** Notify the size observer (the client's pending-sync count) after any change. */
   private notifySize;
@@ -398,4 +502,108 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };
+/**
+* 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.
+*
+* When the precondition is checked (on queue drain / reconnect) it re-reads the
+* query's current value via {@link LunoraClient.peekActiveQueryValue}. If the
+* value differs from what was captured at call time the precondition returns
+* `false` and the offline mutation is dropped as stale.
+* @example
+* ```ts
+* client.mutation(api.todos.update, { id, text }, {
+*   precondition: createSnapshotPrecondition(client, api.todos.list, { userId }),
+* });
+* ```
+*/
+declare const createSnapshotPrecondition: (client: LunoraClient, functionRef: FunctionReference, args: Record<string, unknown>, shardKey?: string) => (() => boolean);
+/**
+* Client-side service-worker registration and lifecycle management.
+*
+* Usage:
+* ```ts
+* const sw = new ClientServiceWorker({ swUrl: "/sw.js" });
+* await sw.register();
+*
+* if (sw.active) {
+*   sw.postMessage({ type: "sync" });
+* }
+* ```
+*/
+type ServiceWorkerStatus = "unsupported" | "unregistered" | "registering" | "active" | "error";
+interface ClientSwOptions {
+  /** Called when the status changes. */
+  onStatusChange?: (status: ServiceWorkerStatus) => void;
+  /** Optional registration scope. Defaults to `/`. */
+  scope?: string;
+  /** URL of the service worker script (relative to origin). */
+  swUrl: string;
+}
+/**
+* Manages service-worker registration and provides a simple API for
+* sending messages and listening for responses.
+*/
+declare class ClientServiceWorker {
+  #private;
+  readonly swUrl: string;
+  readonly scope: string;
+  constructor(options: ClientSwOptions);
+  /** Current registration status. */
+  get status(): ServiceWorkerStatus;
+  /** The underlying `ServiceWorkerRegistration`, if registered. */
+  get registration(): ServiceWorkerRegistration | undefined;
+  /** Whether the SW is currently controlling this page. */
+  get active(): boolean;
+  /**
+  * Register the service worker.
+  *
+  * Returns `false` when the browser does not support service workers.
+  */
+  register(): Promise<boolean>;
+  /**
+  * Remove the active service worker registration and clear listeners.
+  *
+  * Returns `false` when no registration is currently held.
+  */
+  unregister(): Promise<boolean>;
+  /**
+  * Send a message to the active service worker.
+  */
+  postMessage(message: unknown): void;
+  /**
+  * Register a handler for messages **from** the service worker.
+  * @returns Unsubscribe function.
+  */
+  onMessage(handler: (event: MessageEvent) => void): () => void;
+}
+/**
+* Outbound message from the client to the SW.
+*/
+interface ClientToSwMessage {
+  /** Opaque correlation ID for request/response patterns. */
+  correlationId?: string;
+  payload?: unknown;
+  type: string;
+}
+/**
+* Inbound message from the SW to the client.
+*/
+interface SwToClientMessage {
+  /** Echoes the correlation ID from the client request, if any. */
+  correlationId?: string;
+  payload?: unknown;
+  type: string;
+}
+/**
+* Send a typed message to the service worker and optionally await a
+* matching response.
+* @returns A promise that resolves when the SW sends a reply with the
+* same `correlationId` (if `expectResponse` is true).
+*/
+declare const sendToSw: (sw: ServiceWorker | null, message: ClientToSwMessage, expectResponse?: boolean) => Promise<unknown>;
+/**
+* Create a reply for a client message (call from inside the SW).
+*/
+declare const createReply: (original: ClientToSwMessage, payload?: unknown) => SwToClientMessage;
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, ClientServiceWorker, type ClientSwOptions, type ClientToSwMessage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, LunoraClient, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, type ServiceWorkerStatus, type SubscriptionError, type SwToClientMessage, TabCoordinator, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, createReply, createSnapshotPrecondition, isMutationDelta, queryCacheKey, sendToSw };

package/dist/index.mjs

@@ -1,15 +1,20 @@
 export { createAsyncStoragePersistence } from './packem_shared/createAsyncStoragePersistence-1Z5BZ8RC.mjs';
 export { default as createInMemoryBookmarkStorage } from './packem_shared/createInMemoryBookmarkStorage-BoN7a7TH.mjs';
+export { createClientQuery } from './packem_shared/createClientQuery-CQ51bWAE.mjs';
+export { TabCoordinator } from './packem_shared/TabCoordinator-BwRR8H06.mjs';
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-CRKZ1PBt.mjs';
 export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from './packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs';
-export { c as createLocalStore } from './packem_shared/local-store-BveBeFEo.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-kXpHNyaE.mjs';
+export { c as createLocalStore } from './packem_shared/local-store-DtcIW4c0.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-Clb118SU.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
 export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
-export { O as OfflineQueue } from './packem_shared/offline-queue-B9vfdSqp.mjs';
+export { O as OfflineQueue } from './packem_shared/offline-queue-CF4_Co5k.mjs';
 export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-DZ2VHWgm.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
 export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-DiaGZkA2.mjs';
 export { createReconnect } from './packem_shared/createReconnect-Di_-oHH7.mjs';
+export { default as createSnapshotPrecondition } from './packem_shared/createSnapshotPrecondition-CBwnVz6r.mjs';
 export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
-export { S as SubscriptionRegistry } from './packem_shared/subscription-BjynOXCU.mjs';
+export { SubscriptionRegistry } from './packem_shared/SubscriptionRegistry-D4jfIzZu.mjs';
+export { ClientServiceWorker } from './packem_shared/ClientServiceWorker-C3PAFwy0.mjs';
+export { createReply, sendToSw } from './packem_shared/createReply-lI4tVS2w.mjs';

package/dist/packem_shared/ClientServiceWorker-C3PAFwy0.mjs

@@ -0,0 +1,100 @@
+class ClientServiceWorker {
+  swUrl;
+  scope;
+  #registration = void 0;
+  #status = "unregistered";
+  #onStatusChange;
+  #messageHandlers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.swUrl = options.swUrl;
+    this.scope = options.scope ?? "/";
+    this.#onStatusChange = options.onStatusChange;
+  }
+  // ── Status ──────────────────────────────────────────────────────────
+  /** Current registration status. */
+  get status() {
+    return this.#status;
+  }
+  /** The underlying `ServiceWorkerRegistration`, if registered. */
+  get registration() {
+    return this.#registration;
+  }
+  /** Whether the SW is currently controlling this page. */
+  get active() {
+    return this.#registration?.active !== null && this.#registration?.active !== void 0;
+  }
+  // ── Registration ────────────────────────────────────────────────────
+  /**
+   * Register the service worker.
+   *
+   * Returns `false` when the browser does not support service workers.
+   */
+  async register() {
+    if (!("serviceWorker" in navigator)) {
+      this.#setStatus("unsupported");
+      return false;
+    }
+    this.#setStatus("registering");
+    try {
+      this.#registration = await navigator.serviceWorker.register(this.swUrl, {
+        scope: this.scope
+      });
+      this.#setStatus("active");
+      navigator.serviceWorker.addEventListener("message", this.#onMessage);
+    } catch {
+      this.#setStatus("error");
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Remove the active service worker registration and clear listeners.
+   *
+   * Returns `false` when no registration is currently held.
+   */
+  async unregister() {
+    if (!this.#registration) {
+      return false;
+    }
+    navigator.serviceWorker.removeEventListener("message", this.#onMessage);
+    const ok = await this.#registration.unregister();
+    this.#registration = void 0;
+    this.#setStatus("unregistered");
+    return ok;
+  }
+  // ── Messaging ───────────────────────────────────────────────────────
+  /**
+   * Send a message to the active service worker.
+   */
+  postMessage(message) {
+    const active = this.#registration?.active;
+    if (active) {
+      active.postMessage(message);
+    }
+  }
+  /**
+   * Register a handler for messages **from** the service worker.
+   * @returns Unsubscribe function.
+   */
+  onMessage(handler) {
+    this.#messageHandlers.add(handler);
+    return () => {
+      this.#messageHandlers.delete(handler);
+    };
+  }
+  // ── Internals ───────────────────────────────────────────────────────
+  #setStatus(status) {
+    this.#status = status;
+    this.#onStatusChange?.(status);
+  }
+  #onMessage = (event) => {
+    for (const handler of this.#messageHandlers) {
+      try {
+        handler(event);
+      } catch {
+      }
+    }
+  };
+}
+
+export { ClientServiceWorker };