@lunora/client 1.0.0-alpha.66 → 1.0.0-alpha.68

package/dist/packem_shared/{lunora-client.d-DAbmOzH_.d.mts → lunora-client.d-BQ0ig3ih.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClientOptions, a as Unsubscribe, U as User, W as WsTokenProvider, S as ShardTrafficResult, b as ScheduleRecord, c as SchedulerStatus, d as WorkflowInstanceStatus, e as WorkflowInstancePage, f as WorkflowInstanceDetail, g as WorkflowInstanceAction, h as FunctionDescriptor, i as StorageListPage, G as GlobalTableInfo, j as GlobalFilterClause, k as GlobalTablePage, l as GlobalFacetResult, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf } from "./types.d-BOB755CV.mjs";
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClientOptions, a as Unsubscribe, U as User, W as WsTokenProvider, S as ShardTrafficResult, b as ScheduleRecord, c as SchedulerStatus, d as WorkflowInstanceStatus, e as WorkflowInstancePage, f as WorkflowInstanceDetail, g as WorkflowInstanceAction, h as FunctionDescriptor, i as StorageListPage, G as GlobalTableInfo, j as GlobalFilterClause, k as GlobalTablePage, l as GlobalFacetResult, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf } from "./types.d-Bsj5mGrj.js";
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
  * Reactive key-value store for local-only client state.
@@ -208,6 +208,14 @@ declare class SubscriptionRegistry {
   add(state: SubscriptionState): void;
   remove(state: SubscriptionState): void;
   all(): SubscriptionState[];
+  /**
+   * Drop every registration. Terminal — used by `LunoraClient.close()`, whose
+   * whole point is to release the callback closures each {@link SubscriptionState}
+   * holds (`callbacks`, `errorCallbacks`, `checkpointCallbacks` — React state
+   * setters and `@lunora/db` collection closures), which otherwise outlive the
+   * closed client for as long as the client object is reachable.
+   */
+  clear(): void;
 }
 /**
  * Read/write handle over the client's live query cache, handed to a mutation's
@@ -694,6 +702,31 @@ declare class LunoraClient {
    */
   private readonly streams;
   /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  /**
+   * Teardown callbacks for the admin sockets {@link LunoraClient.subscribeScheduledJobs}
+   * opens. Those run their own reconnect loop off a closure-local `closed`
+   * flag rather than `this.closed` (they predate `ensureSocket`'s guard), so
+   * without this registry a `close()` left every one of them reconnecting on
+   * its backoff forever — re-minting an ephemeral admin sub-token on each
+   * attempt when a `WsTokenProvider` is wired.
+   */
+  private readonly adminSocketTeardowns;
+  /**
+   * The in-flight offline-queue replay per shard (`connectionKey`), while one
+   * is running. Two jobs:
+   *
+   * 1. It serializes overlapping flushes for the same shard — two reconnect
+   *    events in quick succession used to drain and replay concurrently.
+   * 2. It is the barrier {@link LunoraClient.mutation} waits on before sending a FRESH
+   *    write directly. The socket's `open` handler flips `wsState` to `"open"`
+   *    first and calls the flush last, so from that instant `mutation()`'s
+   *    offline gate is false and a new write raced straight to `/rpc` against
+   *    the replay of the older, queued write for the same document — the newer
+   *    one could land first and then be overwritten by the older. Ordering
+   *    inside the replay (`replaySequential`) never covered this, because the
+   *    racing write was never in the queue.
+   */
+  private readonly offlineFlushes;
   private readonly shapeSubscriptions;
   /**
    * In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by
@@ -813,6 +846,10 @@ declare class LunoraClient {
    * Stored per shard and replayed on every (re)connect. When a socket for the
    * shard is already open, a fresh `connect` envelope is sent immediately so the
    * server sees the new context without waiting for a reconnect.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — the context rides the
+   * `connect` envelope of a socket a follower does not own, so it would be
+   * stored and never sent. Throws `NOT_IMPLEMENTED` there.
    */
   setConnectionContext(context: Record<string, unknown> | undefined, options?: {
     shardKey?: string;
@@ -852,6 +889,11 @@ declare class LunoraClient {
    * do not put data on a whisper topic that some shard members shouldn't see,
    * and don't trust a whisper's `data` as authorization. Use a query/mutation
    * (with RLS) for anything privileged; whispers are for transient awareness.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — whisper frames are not
+   * relayed over the cross-tab channel, so this throws `NOT_IMPLEMENTED`
+   * there rather than registering a handler nothing can ever reach. See
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   whisperSubscribe(topic: string, handler: (data: unknown, from?: string) => void, options?: {
     shardKey?: string;
@@ -863,6 +905,11 @@ declare class LunoraClient {
    * queued), and the server silently drops it if the sender exceeds its
    * whisper rate budget. The sender never receives its own whisper. Omitting
    * `data` delivers JSON `null` to receivers (not `undefined`).
+   *
+   * That best-effort drop is for a socket that is momentarily down. A
+   * `crossTabSync` FOLLOWER tab has no socket and never will (see
+   * {@link LunoraClientOptions.crossTabSync}), so every whisper from it would
+   * be dropped forever — it throws `NOT_IMPLEMENTED` instead.
    */
   whisper(topic: string, data?: unknown, options?: {
     shardKey?: string;
@@ -1069,6 +1116,22 @@ declare class LunoraClient {
    * Mutations issued before the very first WS connect to a shard fail fast.
    * Opt into queueing-before-first-connect via
    * `OfflineQueueOptions.queueBeforeFirstConnect`.
+   *
+   * **Return-value caveat — the queued paths do not carry the server's result.**
+   * The declared `Promise<ReturnOf<F>>` only holds when the write goes straight
+   * to the server. Once a write is queued:
+   *
+   * - with a durable `outbox` configured, this resolves **immediately with
+   *   `undefined`** (typed as `ReturnOf<F>`) the moment the write is handed to
+   *   the outbox — the replay happens later, out of band, with no awaiter;
+   * - with the built-in offline queue, it stays pending until the replay lands
+   *   and then resolves with the replayed call's value.
+   *
+   * So `const id = await client.mutation(api.todos.create, …)` is `undefined`
+   * for every write issued while offline under an outbox. Generate ids
+   * client-side (or read them back from a subscription) rather than depending
+   * on a mutation's return value in an offline-capable app —
+   * {@link LunoraClient.importRows} documents the same caveat for its counts.
    */
   mutation<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>): Promise<ReturnOf<F>>;
   action<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: ActionCallOptions): Promise<ReturnOf<F>>;
@@ -1309,6 +1372,11 @@ declare class LunoraClient {
    * `DELETE /_lunora/admin/storage?key=…` endpoint — the worker must be built
    * with a `storageDelete` function and `adminToken`. Powers the studio file
    * browser's per-row delete; resolves `{ deleted, key }`.
+   *
+   * An absent `deleted` field reads as `false`, matching every sibling admin
+   * verb (`runCronJob`'s `ran`, …): the studio renders this value as the row's
+   * outcome, so defaulting a missing field to success would report a delete
+   * that a mismatched/older worker never performed.
    */
   deleteStorageObject(key: string, options?: {
     bucket?: string;
@@ -1700,6 +1768,20 @@ declare class LunoraClient {
     offset?: number;
     userId?: string;
   }): Promise<AuthPage<AuthSession>>;
+  /**
+   * Subscribe to a live query. The callback fires with the current value (from
+   * the durable read cache, when one is hydrated) and again on every server
+   * frame; the returned function unsubscribes.
+   *
+   * Subscriptions are deduped by `(functionPath, args, shardKey)` — a second
+   * `subscribe` for the same triple joins the existing registration and shares
+   * its value, cursor and optimistic layers.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab: the cross-tab channel only
+   * carries the LEADER's own subscriptions outward, so a follower would receive
+   * this query's frames only if the leader happened to hold it too. Throws
+   * `NOT_IMPLEMENTED` there — see {@link LunoraClientOptions.crossTabSync}.
+   */
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
     onCheckpoint?: (watermark: SyncWatermark) => void;
     onError?: SubscriptionErrorCallback;
@@ -1716,6 +1798,11 @@ declare class LunoraClient {
    * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
    * (name, args): the server resolves them under the socket's verified identity,
    * so every call gets its own id + view. The returned function unsubscribes.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab: shape pokes are not part of
+   * the leader→follower broadcast set, so a follower's shape could never
+   * resolve. Throws `NOT_IMPLEMENTED` there — see
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   subscribeShape(shape: {
     args?: Record<string, unknown>;
@@ -1770,6 +1857,53 @@ declare class LunoraClient {
   close(): void;
   /** Guard shared by every public entry point: a closed client accepts no further calls. */
   private assertOpen;
+  /**
+   * `true` when this tab is a cross-tab FOLLOWER of a live leader — i.e. it
+   * will not open a socket of its own and another tab is known to hold one.
+   *
+   * Deliberately NOT just `!isLeader()`. Every `crossTabSync` client is a
+   * non-leader for the first `leaderTimeout` of its life, while its
+   * claim-leadership probe is outstanding; a lone tab self-promotes at the end
+   * of that window and `onBecomeLeader` opens the sockets and replays every
+   * registered subscription. That window is a legitimate, self-healing defer,
+   * not a failure. A KNOWN leader on another tab is the state that never heals.
+   */
+  private followsAnotherTab;
+  /**
+   * Reject a call that needs a socket this tab will never have.
+   *
+   * The cross-tab protocol is one-directional: a leader broadcasts
+   * `subscription-data` / `-error` / `-settled` / `connection-status` to
+   * followers, and a follower has no frame with which to tell the leader what
+   * it needs (see `cross-tab.ts`'s `WsFollowerMessage`, which is exactly
+   * heartbeat / claim-leadership / yield-leadership). `subscribeShape` /
+   * `whisper*` / `setConnectionContext` / `acquireConnectionContext` — none of
+   * which the leader broadcasts at all — therefore never worked on a follower
+   * under any circumstances: each returned a handle that looked live, fired no
+   * callback, raised no error, and reported `connectionStatus() ===
+   * "connected"` (mirrored from the leader).
+   *
+   * `subscribe` is deliberately NOT in that set. A follower's `subscribe`
+   * registers the key the leader's broadcast is matched against, so it is the
+   * mechanism the relay is built on rather than a surface that silently fails.
+   * A follower sees a query only while the leader holds the same
+   * `(fn, args, shardKey)` — that is the documented shape of the option, not a
+   * defect.
+   *
+   * `stream()` reaches the same outcome by a different route: it fails the
+   * handle it returns rather than throwing at the call. See
+   * {@link LunoraClientOptions.crossTabSync} for what the option does and does
+   * not cover.
+   */
+  private assertLeaderOwnedSurface;
+  /**
+   * Clear every timer a {@link ShardConnection} can have armed.
+   *
+   * One function because both teardown paths must clear all three and a fourth
+   * timer would otherwise have to be remembered in two places — which is how a
+   * leak gets added rather than written.
+   */
+  private clearConnectionTimers;
   /**
    * Tear down one {@link ShardConnection}'s live state: clear its reconnect/
    * connect timers, stop its heartbeat, and close its socket (if any).
@@ -1777,6 +1911,15 @@ declare class LunoraClient {
    * handler (demoted, but still alive) so a demoted leader can't leak a
    * pending `reconnectTimer` or an open socket's `heartbeatTimer` the way
    * an inline `conn.socket?.close()` — which skips both — used to.
+   *
+   * Settles this shard's in-flight streams first. The teardown clears
+   * `conn.socket` BEFORE the real `close` event fires, so that event trips
+   * `openManagedSocket`'s identity guard (`conn.socket !== socket`) and
+   * returns — meaning `handleDisconnect`, the only other place that settles a
+   * shard's streams, never runs for this connection again. `close()` already
+   * failed and cleared `this.streams` before it gets here, so this is a no-op
+   * on that path; the cross-tab demotion path is the one where a consumer's
+   * `for await` used to block forever with no error and no completion.
    */
   private teardownConnection;
   /**
@@ -2155,12 +2298,21 @@ declare class LunoraClient {
    */
   private rejectQueuedForIdentityChange;
   /**
-   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * Migrate every identity stamp from `from` to `to` — used when the auth
    * identity label changes but the underlying credential (token) does NOT, e.g.
    * the user id resolves a tick after the token was set. The in-memory
    * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
    * keeps the in-flight writes replayable under the new (more stable) identity
    * instead of the flush guard discarding them as a mismatch.
+   *
+   * That map alone was not enough: it is consumed and DELETED on the first
+   * flush attempt (`passesReplayIdentityGate`), while the queue entry and its
+   * persisted record keep the original stamp. So a reload, or a requeue after a
+   * transient failure, fell back to the old token hash — and once the token had
+   * been refreshed, `isSameCredentialUnderTokenHash` no longer recognised it
+   * and the write was rejected `OFFLINE_IDENTITY_CHANGED` for the very user
+   * `setAuthToken`'s sticky-`subject` contract promises to protect. The queue's
+   * own re-stamp covers both the entry and its durable record.
    */
   private restampQueuedIdentity;
   /**
@@ -2197,7 +2349,15 @@ declare class LunoraClient {
    * nothing), so over-inclusion here is harmless.
    */
   private flushAllOfflineQueues;
+  /**
+   * Replay a shard's queued writes, serialized per shard and published as
+   * {@link offlineFlushes} so a concurrent `mutation()` can wait behind it.
+   * Never rejects: every entry's outcome is settled individually inside
+   * {@link drainOfflineQueue}, and a poisoned chain would strand every later
+   * flush AND every write waiting on the barrier.
+   */
   private flushOfflineQueue;
+  private drainOfflineQueue;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
    * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp

package/dist/packem_shared/{lunora-client.d-Dz6Yx4By.d.ts → lunora-client.d-DafpbiD5.d.mts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClientOptions, a as Unsubscribe, U as User, W as WsTokenProvider, S as ShardTrafficResult, b as ScheduleRecord, c as SchedulerStatus, d as WorkflowInstanceStatus, e as WorkflowInstancePage, f as WorkflowInstanceDetail, g as WorkflowInstanceAction, h as FunctionDescriptor, i as StorageListPage, G as GlobalTableInfo, j as GlobalFilterClause, k as GlobalTablePage, l as GlobalFacetResult, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf } from "./types.d-BOB755CV.js";
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClientOptions, a as Unsubscribe, U as User, W as WsTokenProvider, S as ShardTrafficResult, b as ScheduleRecord, c as SchedulerStatus, d as WorkflowInstanceStatus, e as WorkflowInstancePage, f as WorkflowInstanceDetail, g as WorkflowInstanceAction, h as FunctionDescriptor, i as StorageListPage, G as GlobalTableInfo, j as GlobalFilterClause, k as GlobalTablePage, l as GlobalFacetResult, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf } from "./types.d-Bsj5mGrj.mjs";
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
  * Reactive key-value store for local-only client state.
@@ -208,6 +208,14 @@ declare class SubscriptionRegistry {
   add(state: SubscriptionState): void;
   remove(state: SubscriptionState): void;
   all(): SubscriptionState[];
+  /**
+   * Drop every registration. Terminal — used by `LunoraClient.close()`, whose
+   * whole point is to release the callback closures each {@link SubscriptionState}
+   * holds (`callbacks`, `errorCallbacks`, `checkpointCallbacks` — React state
+   * setters and `@lunora/db` collection closures), which otherwise outlive the
+   * closed client for as long as the client object is reachable.
+   */
+  clear(): void;
 }
 /**
  * Read/write handle over the client's live query cache, handed to a mutation's
@@ -694,6 +702,31 @@ declare class LunoraClient {
    */
   private readonly streams;
   /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  /**
+   * Teardown callbacks for the admin sockets {@link LunoraClient.subscribeScheduledJobs}
+   * opens. Those run their own reconnect loop off a closure-local `closed`
+   * flag rather than `this.closed` (they predate `ensureSocket`'s guard), so
+   * without this registry a `close()` left every one of them reconnecting on
+   * its backoff forever — re-minting an ephemeral admin sub-token on each
+   * attempt when a `WsTokenProvider` is wired.
+   */
+  private readonly adminSocketTeardowns;
+  /**
+   * The in-flight offline-queue replay per shard (`connectionKey`), while one
+   * is running. Two jobs:
+   *
+   * 1. It serializes overlapping flushes for the same shard — two reconnect
+   *    events in quick succession used to drain and replay concurrently.
+   * 2. It is the barrier {@link LunoraClient.mutation} waits on before sending a FRESH
+   *    write directly. The socket's `open` handler flips `wsState` to `"open"`
+   *    first and calls the flush last, so from that instant `mutation()`'s
+   *    offline gate is false and a new write raced straight to `/rpc` against
+   *    the replay of the older, queued write for the same document — the newer
+   *    one could land first and then be overwritten by the older. Ordering
+   *    inside the replay (`replaySequential`) never covered this, because the
+   *    racing write was never in the queue.
+   */
+  private readonly offlineFlushes;
   private readonly shapeSubscriptions;
   /**
    * In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by
@@ -813,6 +846,10 @@ declare class LunoraClient {
    * Stored per shard and replayed on every (re)connect. When a socket for the
    * shard is already open, a fresh `connect` envelope is sent immediately so the
    * server sees the new context without waiting for a reconnect.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — the context rides the
+   * `connect` envelope of a socket a follower does not own, so it would be
+   * stored and never sent. Throws `NOT_IMPLEMENTED` there.
    */
   setConnectionContext(context: Record<string, unknown> | undefined, options?: {
     shardKey?: string;
@@ -852,6 +889,11 @@ declare class LunoraClient {
    * do not put data on a whisper topic that some shard members shouldn't see,
    * and don't trust a whisper's `data` as authorization. Use a query/mutation
    * (with RLS) for anything privileged; whispers are for transient awareness.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — whisper frames are not
+   * relayed over the cross-tab channel, so this throws `NOT_IMPLEMENTED`
+   * there rather than registering a handler nothing can ever reach. See
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   whisperSubscribe(topic: string, handler: (data: unknown, from?: string) => void, options?: {
     shardKey?: string;
@@ -863,6 +905,11 @@ declare class LunoraClient {
    * queued), and the server silently drops it if the sender exceeds its
    * whisper rate budget. The sender never receives its own whisper. Omitting
    * `data` delivers JSON `null` to receivers (not `undefined`).
+   *
+   * That best-effort drop is for a socket that is momentarily down. A
+   * `crossTabSync` FOLLOWER tab has no socket and never will (see
+   * {@link LunoraClientOptions.crossTabSync}), so every whisper from it would
+   * be dropped forever — it throws `NOT_IMPLEMENTED` instead.
    */
   whisper(topic: string, data?: unknown, options?: {
     shardKey?: string;
@@ -1069,6 +1116,22 @@ declare class LunoraClient {
    * Mutations issued before the very first WS connect to a shard fail fast.
    * Opt into queueing-before-first-connect via
    * `OfflineQueueOptions.queueBeforeFirstConnect`.
+   *
+   * **Return-value caveat — the queued paths do not carry the server's result.**
+   * The declared `Promise<ReturnOf<F>>` only holds when the write goes straight
+   * to the server. Once a write is queued:
+   *
+   * - with a durable `outbox` configured, this resolves **immediately with
+   *   `undefined`** (typed as `ReturnOf<F>`) the moment the write is handed to
+   *   the outbox — the replay happens later, out of band, with no awaiter;
+   * - with the built-in offline queue, it stays pending until the replay lands
+   *   and then resolves with the replayed call's value.
+   *
+   * So `const id = await client.mutation(api.todos.create, …)` is `undefined`
+   * for every write issued while offline under an outbox. Generate ids
+   * client-side (or read them back from a subscription) rather than depending
+   * on a mutation's return value in an offline-capable app —
+   * {@link LunoraClient.importRows} documents the same caveat for its counts.
    */
   mutation<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>): Promise<ReturnOf<F>>;
   action<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: ActionCallOptions): Promise<ReturnOf<F>>;
@@ -1309,6 +1372,11 @@ declare class LunoraClient {
    * `DELETE /_lunora/admin/storage?key=…` endpoint — the worker must be built
    * with a `storageDelete` function and `adminToken`. Powers the studio file
    * browser's per-row delete; resolves `{ deleted, key }`.
+   *
+   * An absent `deleted` field reads as `false`, matching every sibling admin
+   * verb (`runCronJob`'s `ran`, …): the studio renders this value as the row's
+   * outcome, so defaulting a missing field to success would report a delete
+   * that a mismatched/older worker never performed.
    */
   deleteStorageObject(key: string, options?: {
     bucket?: string;
@@ -1700,6 +1768,20 @@ declare class LunoraClient {
     offset?: number;
     userId?: string;
   }): Promise<AuthPage<AuthSession>>;
+  /**
+   * Subscribe to a live query. The callback fires with the current value (from
+   * the durable read cache, when one is hydrated) and again on every server
+   * frame; the returned function unsubscribes.
+   *
+   * Subscriptions are deduped by `(functionPath, args, shardKey)` — a second
+   * `subscribe` for the same triple joins the existing registration and shares
+   * its value, cursor and optimistic layers.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab: the cross-tab channel only
+   * carries the LEADER's own subscriptions outward, so a follower would receive
+   * this query's frames only if the leader happened to hold it too. Throws
+   * `NOT_IMPLEMENTED` there — see {@link LunoraClientOptions.crossTabSync}.
+   */
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
     onCheckpoint?: (watermark: SyncWatermark) => void;
     onError?: SubscriptionErrorCallback;
@@ -1716,6 +1798,11 @@ declare class LunoraClient {
    * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
    * (name, args): the server resolves them under the socket's verified identity,
    * so every call gets its own id + view. The returned function unsubscribes.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab: shape pokes are not part of
+   * the leader→follower broadcast set, so a follower's shape could never
+   * resolve. Throws `NOT_IMPLEMENTED` there — see
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   subscribeShape(shape: {
     args?: Record<string, unknown>;
@@ -1770,6 +1857,53 @@ declare class LunoraClient {
   close(): void;
   /** Guard shared by every public entry point: a closed client accepts no further calls. */
   private assertOpen;
+  /**
+   * `true` when this tab is a cross-tab FOLLOWER of a live leader — i.e. it
+   * will not open a socket of its own and another tab is known to hold one.
+   *
+   * Deliberately NOT just `!isLeader()`. Every `crossTabSync` client is a
+   * non-leader for the first `leaderTimeout` of its life, while its
+   * claim-leadership probe is outstanding; a lone tab self-promotes at the end
+   * of that window and `onBecomeLeader` opens the sockets and replays every
+   * registered subscription. That window is a legitimate, self-healing defer,
+   * not a failure. A KNOWN leader on another tab is the state that never heals.
+   */
+  private followsAnotherTab;
+  /**
+   * Reject a call that needs a socket this tab will never have.
+   *
+   * The cross-tab protocol is one-directional: a leader broadcasts
+   * `subscription-data` / `-error` / `-settled` / `connection-status` to
+   * followers, and a follower has no frame with which to tell the leader what
+   * it needs (see `cross-tab.ts`'s `WsFollowerMessage`, which is exactly
+   * heartbeat / claim-leadership / yield-leadership). `subscribeShape` /
+   * `whisper*` / `setConnectionContext` / `acquireConnectionContext` — none of
+   * which the leader broadcasts at all — therefore never worked on a follower
+   * under any circumstances: each returned a handle that looked live, fired no
+   * callback, raised no error, and reported `connectionStatus() ===
+   * "connected"` (mirrored from the leader).
+   *
+   * `subscribe` is deliberately NOT in that set. A follower's `subscribe`
+   * registers the key the leader's broadcast is matched against, so it is the
+   * mechanism the relay is built on rather than a surface that silently fails.
+   * A follower sees a query only while the leader holds the same
+   * `(fn, args, shardKey)` — that is the documented shape of the option, not a
+   * defect.
+   *
+   * `stream()` reaches the same outcome by a different route: it fails the
+   * handle it returns rather than throwing at the call. See
+   * {@link LunoraClientOptions.crossTabSync} for what the option does and does
+   * not cover.
+   */
+  private assertLeaderOwnedSurface;
+  /**
+   * Clear every timer a {@link ShardConnection} can have armed.
+   *
+   * One function because both teardown paths must clear all three and a fourth
+   * timer would otherwise have to be remembered in two places — which is how a
+   * leak gets added rather than written.
+   */
+  private clearConnectionTimers;
   /**
    * Tear down one {@link ShardConnection}'s live state: clear its reconnect/
    * connect timers, stop its heartbeat, and close its socket (if any).
@@ -1777,6 +1911,15 @@ declare class LunoraClient {
    * handler (demoted, but still alive) so a demoted leader can't leak a
    * pending `reconnectTimer` or an open socket's `heartbeatTimer` the way
    * an inline `conn.socket?.close()` — which skips both — used to.
+   *
+   * Settles this shard's in-flight streams first. The teardown clears
+   * `conn.socket` BEFORE the real `close` event fires, so that event trips
+   * `openManagedSocket`'s identity guard (`conn.socket !== socket`) and
+   * returns — meaning `handleDisconnect`, the only other place that settles a
+   * shard's streams, never runs for this connection again. `close()` already
+   * failed and cleared `this.streams` before it gets here, so this is a no-op
+   * on that path; the cross-tab demotion path is the one where a consumer's
+   * `for await` used to block forever with no error and no completion.
    */
   private teardownConnection;
   /**
@@ -2155,12 +2298,21 @@ declare class LunoraClient {
    */
   private rejectQueuedForIdentityChange;
   /**
-   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * Migrate every identity stamp from `from` to `to` — used when the auth
    * identity label changes but the underlying credential (token) does NOT, e.g.
    * the user id resolves a tick after the token was set. The in-memory
    * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
    * keeps the in-flight writes replayable under the new (more stable) identity
    * instead of the flush guard discarding them as a mismatch.
+   *
+   * That map alone was not enough: it is consumed and DELETED on the first
+   * flush attempt (`passesReplayIdentityGate`), while the queue entry and its
+   * persisted record keep the original stamp. So a reload, or a requeue after a
+   * transient failure, fell back to the old token hash — and once the token had
+   * been refreshed, `isSameCredentialUnderTokenHash` no longer recognised it
+   * and the write was rejected `OFFLINE_IDENTITY_CHANGED` for the very user
+   * `setAuthToken`'s sticky-`subject` contract promises to protect. The queue's
+   * own re-stamp covers both the entry and its durable record.
    */
   private restampQueuedIdentity;
   /**
@@ -2197,7 +2349,15 @@ declare class LunoraClient {
    * nothing), so over-inclusion here is harmless.
    */
   private flushAllOfflineQueues;
+  /**
+   * Replay a shard's queued writes, serialized per shard and published as
+   * {@link offlineFlushes} so a concurrent `mutation()` can wait behind it.
+   * Never rejects: every entry's outcome is settled individually inside
+   * {@link drainOfflineQueue}, and a poisoned chain would strand every later
+   * flush AND every write waiting on the barrier.
+   */
   private flushOfflineQueue;
+  private drainOfflineQueue;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
    * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp

package/dist/packem_shared/offline-queue-Bmeyg5fy.mjs

@@ -0,0 +1 @@
+let h=0;const a=()=>{if(typeof crypto<"u"&&typeof crypto.randomUUID=="function")return crypto.randomUUID();h+=1;const r=typeof crypto<"u"&&typeof crypto.getRandomValues=="function"?Array.from(crypto.getRandomValues(new Uint8Array(8)),t=>t.toString(16).padStart(2,"0")).join(""):Math.random().toString(16).slice(2,12);return`id_${Date.now().toString(36)}_${h.toString(36)}_${r}`},f=(r,t)=>r!==void 0&&t!==r,u=a,o=(r,t,e,i)=>{if(r){r({error:e,mutationId:i,operation:t});return}console.warn(`[lunora] offline-queue persistence ${t} failed`,e)};class m{queueBeforeFirstConnect;maxItems;onPersistenceError;persistence;onEvict;onSizeChange;version;items=[];constructor(t={},e={}){this.maxItems=t.maxItems??1e3,this.queueBeforeFirstConnect=t.queueBeforeFirstConnect??!1,this.onPersistenceError=t.onPersistenceError,this.persistence=e.persistence,this.onEvict=e.onEvict,this.onSizeChange=e.onSizeChange,this.version=e.version}get size(){return this.items.length}enqueue(t){const e=t;e.id??=u(),this.items.push(e),this.persistence?.append({args:e.args,clientId:e.clientId,functionPath:e.functionPath,id:e.id,identity:e.identity,shardKey:e.shardKey,...this.version===void 0?{}:{version:this.version}}).catch(i=>{o(this.onPersistenceError,"append",i,e.id)}),this.evictOverflow(),this.notifySize()}async hydrate(){if(!this.persistence)return[];let t;try{t=await this.persistence.load()}catch(s){throw o(this.onPersistenceError,"load",s),s}const e=[],i=new Set(this.items.map(s=>s.id));for(const s of t)if(!i.has(s.id)){if(f(this.version,s.version)){this.persistence.remove(s.id).catch(d=>{o(this.onPersistenceError,"remove",d,s.id)});continue}i.add(s.id),e.push({args:s.args,clientId:s.clientId,functionPath:s.functionPath,id:s.id,identity:s.identity,reject:()=>{},resolve:()=>{},shardKey:s.shardKey})}this.items.unshift(...e),this.evictOverflow(),this.notifySize();const n=new Set(this.items),c=new Set;for(const s of e)n.has(s)&&c.add(s.shardKey);return[...c]}restampIdentity(t,e){for(const i of this.items){if(i.identity!==t)continue;i.identity=e;const{id:n}=i;if(!this.persistence||n===void 0)continue;const c={args:i.args,clientId:i.clientId,functionPath:i.functionPath,id:n,identity:e,shardKey:i.shardKey,...this.version===void 0?{}:{version:this.version}};this.persistence.remove(n).then(async()=>this.persistence?.append(c)).catch(s=>{o(this.onPersistenceError,"append",s,n)})}}drain(t){if(!t){const n=[...this.items];return this.items.length=0,this.notifySize(),n}const e=[],i=[];for(const n of this.items)(t(n)?e:i).push(n);return this.items.length=0,this.items.push(...i),this.notifySize(),e}requeue(t){t.length!==0&&(this.items.unshift(...t),this.notifySize())}drainConflict(){const t=[],e=[];for(const i of this.items)if(i.precondition!==void 0&&!i.precondition()){const n=new Error("offline mutation skipped: precondition failed before replay");n.code="OFFLINE_PRECONDITION_FAILED",i.reject(n),t.push(i)}else e.push(i);return t.length>0&&(this.items.length=0,this.items.push(...e),this.notifySize()),t}clear(){for(const t of this.items){const e=new Error("CLIENT_CLOSED");e.code="CLIENT_CLOSED",t.reject(e)}this.items.length=0,this.notifySize()}evictOverflow(){for(;this.items.length>this.maxItems;){const t=this.items.shift();if(t){t.id&&this.persistence?.remove(t.id).catch(i=>{o(this.onPersistenceError,"remove",i,t.id)});const e=new Error("offline queue overflow");e.code="OFFLINE_QUEUE_OVERFLOW",t.reject(e),this.onEvict?.(t,e)}}}notifySize(){this.onSizeChange?.(this.items.length)}}export{m as O,f as i,u as n,o as r};

package/dist/packem_shared/{preload.d-BmPMaxYW.d.mts → preload.d-C09vDOAR.d.mts}

@@ -1,5 +1,5 @@
-import { L as LunoraClient } from "./lunora-client.d-DAbmOzH_.mjs";
-import { F as FunctionReference, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./types.d-BOB755CV.mjs";
+import { L as LunoraClient } from "./lunora-client.d-DafpbiD5.mjs";
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./types.d-Bsj5mGrj.mjs";
 /**
  * Run a query once on the server (during SSR) and capture its result in a
  * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{preload.d-CN5mOiAj.d.ts → preload.d-DGiAgCkV.d.ts}

@@ -1,5 +1,5 @@
-import { L as LunoraClient } from "./lunora-client.d-Dz6Yx4By.js";
-import { F as FunctionReference, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./types.d-BOB755CV.js";
+import { L as LunoraClient } from "./lunora-client.d-BQ0ig3ih.js";
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./types.d-Bsj5mGrj.js";
 /**
  * Run a query once on the server (during SSR) and capture its result in a
  * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{types.d-BOB755CV.d.mts → types.d-Bsj5mGrj.d.mts}

@@ -322,13 +322,38 @@ interface LunoraClientOptions {
    */
   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.
+   * When `true`, tabs sharing the same origin (and the same signed-in identity)
+   * coordinate via BroadcastChannel so only one tab — the "leader" — opens
+   * WebSocket connections to the server. Reduces simultaneous WS connections,
+   * bandwidth, and cross-tab state drift. Requires `BroadcastChannel`
+   * (browser-only); silently ignored otherwise. Defaults to `false`.
    *
-   * Reduces simultaneous WS connections, bandwidth, and cross-tab state drift.
-   * Requires `BroadcastChannel` (browser-only); silently ignored otherwise.
-   * Defaults to `false`.
+   * **The channel is one-directional: leader → follower.** The leader
+   * broadcasts the values, errors, checkpoints and connection status of the
+   * subscriptions *it* holds; there is no frame with which a follower can ask
+   * the leader for anything.
+   *
+   * `subscribe` works on a follower and is how the relay delivers: the
+   * registration is what the leader's broadcast key is matched against, so a
+   * follower sees a value while the leader independently holds the same
+   * `(fn, args, shardKey)`.
+   *
+   * Nothing else is served, because the leader broadcasts nothing for it and a
+   * follower cannot ask. `subscribeShape` and `acquireConnectionContext` are
+   * inert on a follower — framework code (`@lunora/db`'s shape sync, every
+   * `usePresence` adapter) calls them from an effect the app cannot opt out
+   * of, so throwing would unwind the tab rather than degrade one feature.
+   * `whisper`, `whisperSubscribe`, `setConnectionContext` and `stream` are
+   * only ever called by app code, which can handle a failure, so those throw
+   * `NOT_IMPLEMENTED` rather than returning a handle that never fires. (The
+   * brief window every tab spends claiming leadership at startup is not a
+   * follower state: a lone tab self-promotes and its registered subscriptions
+   * are sent then.) HTTP surfaces — `query`, `mutation`, `action`, the offline
+   * queue's replay — are unaffected on every tab.
+   *
+   * So: enable this when your tabs run the SAME app views over plain
+   * `subscribe`, and leave it off if tabs can sit on different routes or you
+   * use shapes, whispers, streams, or connection context.
    */
   crossTabSync?: boolean;
   fetch?: typeof fetch;

package/dist/packem_shared/{types.d-BOB755CV.d.ts → types.d-Bsj5mGrj.d.ts}

@@ -322,13 +322,38 @@ interface LunoraClientOptions {
    */
   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.
+   * When `true`, tabs sharing the same origin (and the same signed-in identity)
+   * coordinate via BroadcastChannel so only one tab — the "leader" — opens
+   * WebSocket connections to the server. Reduces simultaneous WS connections,
+   * bandwidth, and cross-tab state drift. Requires `BroadcastChannel`
+   * (browser-only); silently ignored otherwise. Defaults to `false`.
    *
-   * Reduces simultaneous WS connections, bandwidth, and cross-tab state drift.
-   * Requires `BroadcastChannel` (browser-only); silently ignored otherwise.
-   * Defaults to `false`.
+   * **The channel is one-directional: leader → follower.** The leader
+   * broadcasts the values, errors, checkpoints and connection status of the
+   * subscriptions *it* holds; there is no frame with which a follower can ask
+   * the leader for anything.
+   *
+   * `subscribe` works on a follower and is how the relay delivers: the
+   * registration is what the leader's broadcast key is matched against, so a
+   * follower sees a value while the leader independently holds the same
+   * `(fn, args, shardKey)`.
+   *
+   * Nothing else is served, because the leader broadcasts nothing for it and a
+   * follower cannot ask. `subscribeShape` and `acquireConnectionContext` are
+   * inert on a follower — framework code (`@lunora/db`'s shape sync, every
+   * `usePresence` adapter) calls them from an effect the app cannot opt out
+   * of, so throwing would unwind the tab rather than degrade one feature.
+   * `whisper`, `whisperSubscribe`, `setConnectionContext` and `stream` are
+   * only ever called by app code, which can handle a failure, so those throw
+   * `NOT_IMPLEMENTED` rather than returning a handle that never fires. (The
+   * brief window every tab spends claiming leadership at startup is not a
+   * follower state: a lone tab self-promotes and its registered subscriptions
+   * are sent then.) HTTP surfaces — `query`, `mutation`, `action`, the offline
+   * queue's replay — are unaffected on every tab.
+   *
+   * So: enable this when your tabs run the SAME app views over plain
+   * `subscribe`, and leave it off if tabs can sit on different routes or you
+   * use shapes, whispers, streams, or connection context.
    */
   crossTabSync?: boolean;
   fetch?: typeof fetch;