@syncular/client 0.15.12 → 0.15.14

package/README.md

@@ -73,7 +73,9 @@ const handle = await createSyncClientHandle({
   schema, database: { mode: 'persistent', name: 'app' }, endpoints,
   onRoleChange: (role) => console.log('now', role), // 'follower' → 'leader'
 });
-// handle.role is 'leader' or 'follower'; the API is identical either way.
+// Compatibility: handle.role is 'leader' or 'follower'.
+// Detailed state: handle.leadership / handle.leadershipSnapshot().
+handle.onLeadershipChange((state) => renderConnectionState(state));
 ```
 
 **Topology.** The tab that wins the Web Locks election is the **leader**:
@@ -105,6 +107,15 @@ flushed to the new leader on its announce; past the deadline they fail
 loudly with `client.follower_timeout` (never a silent hang), and an
 overflowing queue rejects rather than growing unbounded.
 
+Leader announcements continue as heartbeats while followers are attached. If
+a tab can acquire neither a response nor a new lock grant before the configured
+`followerCallTimeoutMs`, `handle.leadership` becomes
+`{ state: 'blocked', reason: 'leader-unreachable', code:
+'client.follower_timeout', retryable: true }`. Calls then reject immediately.
+A later announcement rebinds the same handle; a granted Web Lock promotes it.
+An unreachable `BroadcastChannel` is never treated as evidence that the lock
+owner is stale, so it never authorizes a second worker or database owner.
+
 **Presence semantics — one device, one peer.** All tabs share the leader's
 single connection, so a device is exactly ONE presence peer collectively:
 identity is `(actorId, leaderClientId)`. A follower's `setPresence`
@@ -112,8 +123,61 @@ forwards to the leader's single publisher; there is no per-tab presence
 peer. This is the honest model — the wire only ever sees one connection per
 device.
 
+The default is a **shared replica**: same-origin tabs must use the same
+persistent database name, lock name, and derived channel name. For an embed,
+preview, or history entry that is intentionally independent, derive the whole
+ownership tuple from one stable identity:
+
+```ts
+const preview = await createSyncClientHandle({
+  worker,
+  schema,
+  database: { mode: 'persistent', name: 'medical' },
+  endpoints,
+  replica: { mode: 'isolated', id: 'preview-42' },
+});
+```
+
+This derives a distinct database name and pool directory, Web Lock name, and
+`BroadcastChannel` name together. `isolatedReplicaNames()` exposes the same
+deterministic tuple for diagnostics and host integration. Replica IDs are
+stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
+
+During Vite development, retain the React client resource only while its
+captured generated schema version matches. The
+[schema-aware Vite guide](https://syncular.dev/guide-vite/) uses
+`retainViteSyncClientResource` to close the old worker before constructing a
+schema-bump replacement; hot-reloading query code alone does not migrate the
+worker-owned database.
+
 Set `multiTab: false` to opt out. A losing tab then becomes an
-`isLeader === false` handle whose calls reject with `client.not_leader`.
+`isLeader === false` handle whose calls reject with `client.not_leader`. This
+does not solve a coordination-partition mismatch by itself: an independent
+instance must also use an isolated database and lock identity. Changing only
+the channel, lock, or database name is unsafe or ineffective.
+
+## React availability guard
+
+The worker handle's schema and leadership snapshots feed the same public React
+boundary as native clients. Guard the application once instead of parsing
+errors or inspecting generated schema modules:
+
+```tsx
+<SyncProvider
+  client={clientResource}
+  renderBoundary={(state, actions) => (
+    <SyncBlockedScreen state={state} onRetry={actions.retry} />
+  )}
+>
+  <App />
+</SyncProvider>
+```
+
+The state is a discriminated union covering startup, migration,
+`client-upgrade-required`, `server-behind`, `incompatible-schema`, and
+`leader-unreachable`. Recovery changes the same handle/provider back to its
+children; a blocked live query has `phase === 'blocked'`, never an indefinite
+loading state.
 
 ## Durable commit outcomes
 

package/dist/availability.d.ts

@@ -0,0 +1,17 @@
+import type { SyncStatusSnapshot } from './invalidation.js';
+import type { LeadershipState } from './multi-tab.js';
+export type SyncAvailability = {
+    readonly state: 'ready';
+} | {
+    readonly state: 'migrating';
+    readonly currentSchemaVersion: number;
+} | {
+    readonly state: 'blocked';
+    readonly reason: 'client-upgrade-required' | 'server-behind' | 'incompatible-schema' | 'leader-unreachable';
+    readonly currentSchemaVersion: number;
+    readonly requiredSchemaVersion?: number;
+    readonly latestServerSchemaVersion?: number;
+    readonly retryable: boolean;
+};
+/** Classify schema and browser-ownership state without parsing diagnostics. */
+export declare function classifySyncAvailability(status: SyncStatusSnapshot, leadership?: LeadershipState): SyncAvailability;

package/dist/availability.js

@@ -0,0 +1,48 @@
+/** Classify schema and browser-ownership state without parsing diagnostics. */
+export function classifySyncAvailability(status, leadership) {
+    const currentSchemaVersion = status.currentSchemaVersion;
+    if (leadership?.state === 'blocked') {
+        return {
+            state: 'blocked',
+            reason: 'leader-unreachable',
+            currentSchemaVersion,
+            retryable: true,
+        };
+    }
+    const required = status.schemaFloor?.requiredSchemaVersion;
+    const latest = status.schemaFloor?.latestSchemaVersion;
+    if (required !== undefined && required > currentSchemaVersion) {
+        return {
+            state: 'blocked',
+            reason: 'client-upgrade-required',
+            currentSchemaVersion,
+            requiredSchemaVersion: required,
+            ...(latest !== undefined ? { latestServerSchemaVersion: latest } : {}),
+            retryable: false,
+        };
+    }
+    if (latest !== undefined && latest < currentSchemaVersion) {
+        return {
+            state: 'blocked',
+            reason: 'server-behind',
+            currentSchemaVersion,
+            ...(required !== undefined ? { requiredSchemaVersion: required } : {}),
+            latestServerSchemaVersion: latest,
+            retryable: false,
+        };
+    }
+    if (status.schemaFloor !== undefined) {
+        return {
+            state: 'blocked',
+            reason: 'incompatible-schema',
+            currentSchemaVersion,
+            ...(required !== undefined ? { requiredSchemaVersion: required } : {}),
+            ...(latest !== undefined ? { latestServerSchemaVersion: latest } : {}),
+            retryable: false,
+        };
+    }
+    if (status.upgrading) {
+        return { state: 'migrating', currentSchemaVersion };
+    }
+    return { state: 'ready' };
+}

package/dist/client.js

@@ -181,9 +181,7 @@ export class SyncClient {
         this.#detectAndResetSchema();
         // A registration remains app intent only while its table exists in the
         // running schema. Removed-table registrations would poison every pull.
-        this.#db.transaction(() => {
-            pruneUnknownSubscriptions(this.#db, new Set(this.#schema.tables.keys()));
-        });
+        const subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), new Set(this.#schema.tables.keys()));
         this.#started = true;
         // A persisted active subscription needs one catch-up round on every open:
         // realtime only covers changes after the socket connects, and an
@@ -193,7 +191,7 @@ export class SyncClient {
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
             (listOutbox(this.#db).length > 0 ||
-                loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
+                subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork) {
             this.#needsPull = true;
             this.#config.onSyncNeeded?.('startup');
@@ -393,6 +391,7 @@ export class SyncClient {
     }
     #statusSnapshot() {
         return {
+            currentSchemaVersion: this.#config.schema.version,
             outbox: listOutbox(this.#db).length,
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,

package/dist/index.d.ts

@@ -9,6 +9,7 @@
  * import no SQLite.
  */
 export * from './apply.js';
+export * from './availability.js';
 export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';

package/dist/index.js

@@ -9,6 +9,7 @@
  * import no SQLite.
  */
 export * from './apply.js';
+export * from './availability.js';
 export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';

package/dist/invalidation.d.ts

@@ -20,6 +20,7 @@ export interface WindowChange {
     readonly units: ReadonlySet<string>;
 }
 export interface SyncStatusSnapshot {
+    readonly currentSchemaVersion: number;
     readonly outbox: number;
     readonly upgrading: boolean;
     readonly leaseState: LeaseState | undefined;

package/dist/multi-tab.d.ts

@@ -5,6 +5,22 @@ export declare const FOLLOWER_TIMEOUT_CODE = "client.follower_timeout";
 export declare const DEFAULT_FOLLOWER_CALL_TIMEOUT_MS = 10000;
 /** Max follower calls queued across a handover before we fail loudly. */
 export declare const DEFAULT_FOLLOWER_QUEUE_LIMIT = 256;
+export type LeadershipState = {
+    readonly state: 'leader';
+    readonly clientId: string;
+} | {
+    readonly state: 'follower';
+    readonly leaderClientId: string;
+    readonly epoch: number;
+} | {
+    readonly state: 'waiting';
+    readonly reason: 'handover' | 'leader-announcement';
+} | {
+    readonly state: 'blocked';
+    readonly reason: 'leader-unreachable';
+    readonly code: typeof FOLLOWER_TIMEOUT_CODE;
+    readonly retryable: true;
+};
 interface HelloMessage {
     readonly t: 'hello';
     readonly fromId: string;
@@ -16,6 +32,10 @@ interface ByeMessage {
     readonly t: 'bye';
     readonly fromId: string;
 }
+interface BoundMessage {
+    readonly t: 'bound';
+    readonly fromId: string;
+}
 interface ReqMessage {
     readonly t: 'req';
     readonly epoch: number;
@@ -46,7 +66,7 @@ interface EventMessage {
     readonly epoch: number;
     readonly event: SyncWorkerEvent;
 }
-export type MultiTabMessage = HelloMessage | ByeMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
+export type MultiTabMessage = HelloMessage | ByeMessage | BoundMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
 /**
  * The tiny cross-tab channel surface we depend on — the DOM `BroadcastChannel`
  * satisfies it. Injectable so bun tests can pair two instances by name.
@@ -80,6 +100,7 @@ export declare class LeaderBridge {
         epoch: number;
         clientId: string;
         invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+        heartbeatMs?: number;
     });
     /** Re-announce leadership (on promotion and on a follower `hello`). */
     announce(): void;
@@ -101,12 +122,14 @@ export declare class FollowerLink {
         fromId: string;
         onEvent: (event: SyncWorkerEvent) => void;
         onLeaderChange: (clientId: string) => void;
+        onStateChange?: (state: LeadershipState) => void;
         callTimeoutMs?: number;
         queueLimit?: number;
     });
     get epoch(): number;
     get maxEpochSeen(): number;
     get leaderClientId(): string;
+    get leadershipState(): LeadershipState;
     /** Whether a leader is currently bound (an announce has been heard). */
     get bound(): boolean;
     /**

package/dist/multi-tab.js

@@ -73,12 +73,18 @@ export class LeaderBridge {
     #clientId;
     #invoke;
     #onMessage;
+    #heartbeatMs;
+    #followers = new Set();
+    #heartbeat;
     #closed = false;
     constructor(options) {
         this.#channel = options.channel;
         this.#epoch = options.epoch;
         this.#clientId = options.clientId;
         this.#invoke = options.invoke;
+        this.#heartbeatMs =
+            options.heartbeatMs ??
+                Math.max(50, Math.floor(DEFAULT_FOLLOWER_CALL_TIMEOUT_MS / 3));
         this.#onMessage = (event) => this.#handle(event.data);
         this.#channel.addEventListener('message', this.#onMessage);
         this.announce();
@@ -104,9 +110,22 @@ export class LeaderBridge {
             return;
         if (message.t === 'hello') {
             // A follower joined (or is contesting) — tell it who leads.
+            this.#trackFollower(message.fromId);
             this.announce();
             return;
         }
+        if (message.t === 'bound') {
+            this.#trackFollower(message.fromId);
+            return;
+        }
+        if (message.t === 'bye') {
+            this.#followers.delete(message.fromId);
+            if (this.#followers.size === 0 && this.#heartbeat !== undefined) {
+                clearInterval(this.#heartbeat);
+                this.#heartbeat = undefined;
+            }
+            return;
+        }
         if (message.t !== 'req')
             return;
         // Ignore requests stamped for a different (dead/older) leader; that
@@ -143,11 +162,21 @@ export class LeaderBridge {
             });
         });
     }
+    #trackFollower(fromId) {
+        this.#followers.add(fromId);
+        if (this.#heartbeat !== undefined)
+            return;
+        this.#heartbeat = setInterval(() => this.announce(), this.#heartbeatMs);
+    }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
+        if (this.#heartbeat !== undefined)
+            clearInterval(this.#heartbeat);
+        this.#heartbeat = undefined;
         this.#channel.removeEventListener('message', this.#onMessage);
+        this.#channel.close();
     }
 }
 /**
@@ -162,6 +191,7 @@ export class FollowerLink {
     #fromId;
     #onEvent;
     #onLeaderChange;
+    #onStateChange;
     #callTimeoutMs;
     #queueLimit;
     #onMessage;
@@ -174,6 +204,12 @@ export class FollowerLink {
     #inFlight = new Map();
     #queue = [];
     #closed = false;
+    #state = {
+        state: 'waiting',
+        reason: 'leader-announcement',
+    };
+    #waitingTimer;
+    #blockedTimer;
     /** Resolvers waiting for the first `announce` to bind a leader. */
     #bindWaiters = [];
     constructor(options) {
@@ -181,6 +217,7 @@ export class FollowerLink {
         this.#fromId = options.fromId;
         this.#onEvent = options.onEvent;
         this.#onLeaderChange = options.onLeaderChange;
+        this.#onStateChange = options.onStateChange ?? (() => { });
         this.#callTimeoutMs =
             options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
         this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
@@ -188,6 +225,7 @@ export class FollowerLink {
         this.#channel.addEventListener('message', this.#onMessage);
         // Ask the current leader to announce itself.
         this.#channel.postMessage({ t: 'hello', fromId: this.#fromId });
+        this.#armUnboundDeadline();
     }
     get epoch() {
         return this.#epoch;
@@ -198,6 +236,9 @@ export class FollowerLink {
     get leaderClientId() {
         return this.#leaderClientId;
     }
+    get leadershipState() {
+        return this.#state;
+    }
     /** Whether a leader is currently bound (an announce has been heard). */
     get bound() {
         return this.#epoch >= 0;
@@ -221,7 +262,8 @@ export class FollowerLink {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.#dropBindWaiter(settle);
-                reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout'));
+                this.#setBlocked();
+                reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout', true));
             }, timeoutMs);
             const settle = () => {
                 clearTimeout(timer);
@@ -248,6 +290,9 @@ export class FollowerLink {
         if (this.#closed) {
             return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'));
         }
+        if (this.#state.state === 'blocked') {
+            return Promise.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the follower cannot reach the tab that owns the database', true));
+        }
         return new Promise((resolve, reject) => {
             const queued = {
                 method,
@@ -259,12 +304,14 @@ export class FollowerLink {
             if (this.#epoch < 0) {
                 // No leader bound yet — queue with a deadline so we never hang.
                 if (this.#queue.length >= this.#queueLimit) {
-                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader'));
+                    this.#setBlocked();
+                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader', true));
                     return;
                 }
                 queued.timer = setTimeout(() => {
                     this.#dropQueued(queued);
-                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout'));
+                    this.#setBlocked();
+                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout', true));
                 }, this.#callTimeoutMs);
                 this.#queue.push(queued);
                 return;
@@ -279,7 +326,8 @@ export class FollowerLink {
             reject: queued.reject,
             timer: setTimeout(() => {
                 this.#inFlight.delete(reqId);
-                queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the leader did not answer within the follower call timeout'));
+                this.#setBlocked();
+                queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the leader did not answer within the follower call timeout', true));
             }, this.#callTimeoutMs),
         };
         this.#inFlight.set(reqId, inflight);
@@ -313,6 +361,15 @@ export class FollowerLink {
             this.#leaderClientId = message.clientId;
             if (changed)
                 this.#onLeaderChange(message.clientId);
+            this.#setState({
+                state: 'follower',
+                leaderClientId: message.clientId,
+                epoch: message.epoch,
+            });
+            this.#armBoundDeadline();
+            if (changed) {
+                this.#channel.postMessage({ t: 'bound', fromId: this.#fromId });
+            }
             this.#resolveBindWaiters();
             this.#flushQueue();
             return;
@@ -366,6 +423,8 @@ export class FollowerLink {
             return;
         this.#epoch = -1;
         this.#leaderClientId = '';
+        this.#setState({ state: 'waiting', reason: 'handover' });
+        this.#armUnboundDeadline();
         this.#channel.postMessage({
             t: 'hello',
             fromId: this.#fromId,
@@ -376,6 +435,7 @@ export class FollowerLink {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#clearReachabilityTimers();
         this.#channel.removeEventListener('message', this.#onMessage);
         this.#channel.postMessage({ t: 'bye', fromId: this.#fromId });
         const closedError = new ClientSyncError(WORKER_FAILED_CODE, 'the follower link was closed');
@@ -396,4 +456,53 @@ export class FollowerLink {
         this.#resolveBindWaiters();
         this.#channel.close();
     }
+    #setState(state) {
+        const previous = this.#state;
+        if (previous.state === state.state &&
+            (state.state === 'blocked' ||
+                (state.state === 'waiting' &&
+                    previous.state === 'waiting' &&
+                    previous.reason === state.reason) ||
+                (state.state === 'follower' &&
+                    previous.state === 'follower' &&
+                    previous.epoch === state.epoch &&
+                    previous.leaderClientId === state.leaderClientId))) {
+            return;
+        }
+        this.#state = state;
+        try {
+            this.#onStateChange(state);
+        }
+        catch {
+            // A status listener must never break cross-tab coordination.
+        }
+    }
+    #setBlocked() {
+        this.#clearReachabilityTimers();
+        this.#setState({
+            state: 'blocked',
+            reason: 'leader-unreachable',
+            code: FOLLOWER_TIMEOUT_CODE,
+            retryable: true,
+        });
+    }
+    #armUnboundDeadline() {
+        this.#clearReachabilityTimers();
+        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+    }
+    #armBoundDeadline() {
+        this.#clearReachabilityTimers();
+        this.#waitingTimer = setTimeout(() => {
+            this.#setState({ state: 'waiting', reason: 'leader-announcement' });
+        }, Math.max(1, Math.floor((this.#callTimeoutMs * 2) / 3)));
+        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+    }
+    #clearReachabilityTimers() {
+        if (this.#waitingTimer !== undefined)
+            clearTimeout(this.#waitingTimer);
+        if (this.#blockedTimer !== undefined)
+            clearTimeout(this.#blockedTimer);
+        this.#waitingTimer = undefined;
+        this.#blockedTimer = undefined;
+    }
 }

package/dist/reactive-store.d.ts

@@ -1,6 +1,8 @@
+import { type SyncAvailability } from './availability.js';
 import type { CommitOutcome, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
+import type { LeadershipState } from './multi-tab.js';
 import { type WindowBase } from './window.js';
 export interface QueryDependency {
     readonly table: string;
@@ -12,21 +14,26 @@ export interface ReactiveQuerySpec<Row> {
     readonly params?: readonly SqlValue[];
     readonly dependencies: readonly QueryDependency[];
     readonly coverage?: readonly WindowCoverage[];
+    readonly mapRow?: (row: Readonly<Record<string, SqlValue>>) => Row;
     readonly rowKey?: (row: Row) => readonly SqlValue[];
     readonly claimCoverage?: boolean;
 }
-export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'error';
+export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'blocked' | 'error';
 export interface LiveQueryResult<Row> {
     readonly rows: readonly Row[];
     readonly phase: LiveQueryPhase;
     readonly revision: bigint | undefined;
     readonly error: Error | undefined;
     readonly isRefreshing: boolean;
+    readonly availability: SyncAvailability;
 }
 export interface ReactiveQueryClient {
+    readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
     statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+    leadershipSnapshot?(): LeadershipState | undefined;
+    onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
     readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
     readonly rejections: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
     commitOutcomes(): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
@@ -46,6 +53,7 @@ export interface WindowRetention {
 }
 export interface StatusStoreSnapshot {
     readonly status: SyncStatusSnapshot | undefined;
+    readonly leadership: LeadershipState | undefined;
     readonly error: Error | undefined;
     readonly isLoading: boolean;
 }
@@ -70,6 +78,7 @@ export declare class ReactiveClientStore {
     readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
     constructor(client: ReactiveQueryClient);
     query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
+    availabilitySnapshot(): SyncAvailability;
     /** Retain a composable window working set outside React. The returned
      * handle exposes registration completion and releases only this owner. */
     retainWindow(base: WindowBase, units: readonly string[]): WindowRetention;