@syncular/react 0.15.13 → 0.15.14

package/README.md

@@ -24,6 +24,9 @@ function Tasks({ projectId }: { projectId: string }) {
   const mutation = useMutation(tasksTable);
 
   if (tasks.phase === 'loading') return <p>Loading…</p>;
+  if (tasks.phase === 'blocked') {
+    return <p>Sync unavailable: {tasks.availability.reason}</p>;
+  }
   if (tasks.phase === 'error') return <p>{tasks.error?.message}</p>;
   if (tasks.phase === 'ready' && tasks.rows.length === 0) return <p>Empty</p>;
 
@@ -49,12 +52,17 @@ Typegen puts these facts on the descriptor:
 - a stable row key when the projection proves one.
 
 `useQuery` returns `{ rows, phase, revision, isLoading, isRefreshing, error,
-refresh }`. `phase` is:
+availability, refresh }`. `availability` is the typed `ready`, `migrating`, or
+`blocked` state shared by every client host. `phase` is:
 
 - `loading`: there is not yet a complete answer and there are no partial rows;
 - `partial`: rows exist, but some required window coverage is incomplete;
 - `ready`: the atomic snapshot says the answer is complete, including an
   honestly empty result;
+- `blocked`: sync cannot safely serve a fresh result because the generated
+  schema is incompatible or the browser leader is unreachable. `isLoading`
+  is `false`; previously read rows remain available for deliberate read-only
+  UI, and `availability.reason` identifies the boundary;
 - `error`: the initial read failed. A later refresh error keeps existing rows
   and phase visible through `error`/`isRefreshing`.
 
@@ -93,12 +101,41 @@ const clientResource = createSyncClientResource(() => createClient());
 Call `await clientResource.dispose()` from the application's real lifecycle
 owner, not from a StrictMode-sensitive child effect.
 
+Use `renderBoundary` as the canonical application guard across browser and
+native hosts. It covers resource startup/errors, migration, client upgrade,
+server-behind, incompatible-schema, and unreachable-leader states. The
+provider restores its children automatically when the public status becomes
+ready again:
+
+```tsx
+<SyncProvider
+  client={clientResource}
+  renderBoundary={(state, actions) => (
+    <SyncBlockedScreen state={state} onRetry={actions.retry} />
+  )}
+>
+  <App />
+</SyncProvider>
+```
+
+`fallback` and `renderError` retain their existing behavior when
+`renderBoundary` is absent. `useSyncStatus()` exposes the same classified
+`availability` plus `currentSchemaVersion`, `schemaFloor`, and the raw status
+fields for status chrome outside the provider guard.
+
 The resource is stable across React remounts, not JavaScript module replacement.
 During development, preserve it in the bundler's hot-module data or dispose the
 old resource before creating another one. Otherwise the old worker and the new
 worker can briefly compete for the same persistent OPFS directory. Never wipe
 or rename the database in response to a retryable startup error.
 
+For Vite, use `retainViteSyncClientResource(hot.data, schema.version,
+createClient)`. It retains a `{ schemaVersion, resource }` record, reuses it for
+same-schema HMR, and awaits old-resource disposal before creating a schema-bump
+replacement. Request `hot.invalidate()` only when its `schemaChanged` result is
+true and `disposalError` is absent; the official example and full explanation
+are in the [Vite guide](https://syncular.dev/guide-vite/).
+
 ## `useMutation`
 
 `useMutation()` retains the raw batch API. `useMutation(generatedTable)` adds
@@ -172,8 +209,9 @@ not need a custom retention effect.
 ## Other hooks
 
 - `useSyncStatus()` observes the status domain without a follow-up read after
-  every row change. `outbox` is local push work; `syncNeeded` specifically
-  means an inbound pull/catch-up signal.
+  every row change. It includes `availability` and `currentSchemaVersion`;
+  `outbox` is local push work, while `syncNeeded` specifically means an inbound
+  pull/catch-up signal.
 - `useConflicts()` observes conflicts and rejections only when that domain
   changes.
 - `useCommitOutcomes()` observes the durable newest-first final-outcome journal

package/dist/client.d.ts

@@ -11,7 +11,7 @@
  * value → read it) and wraps every result in `Promise.resolve`, so a hook
  * never has to care which core it holds.
  */
-import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /**
  * The structural union of `SyncClient` and `SyncClientHandle`. Members that
  * diverge are typed as "value or method, sync or promise"; {@link normalizeClient}
@@ -19,9 +19,12 @@ import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictR
  * never reach past this surface.
  */
 export interface SyncClientLike {
+    readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
+    onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
+    leadershipSnapshot?(): LeadershipState | undefined;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[] | Promise<SqlRow[]>;
     mutate(mutations: readonly MutationInput[]): string | Promise<string>;
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
@@ -49,9 +52,12 @@ export interface SyncClientLike {
 }
 /** The uniform async facade the hooks actually call. */
 export interface NormalizedClient {
+    readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
+    onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
+    leadershipSnapshot(): LeadershipState | undefined;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {

package/dist/client.js

@@ -12,9 +12,14 @@ function resolveMember(client, key) {
 }
 export function normalizeClient(client) {
     return {
+        ...(client.currentSchemaVersion !== undefined
+            ? { currentSchemaVersion: client.currentSchemaVersion }
+            : {}),
         onChange: (listener) => client.onChange(listener),
         onInvalidate: (listener) => client.onInvalidate(listener),
         onPresence: (listener) => client.onPresence(listener),
+        onLeadershipChange: (listener) => client.onLeadershipChange?.(listener) ?? (() => { }),
+        leadershipSnapshot: () => client.leadershipSnapshot?.(),
         query: (sql, params) => Promise.resolve(client.query(sql, params)),
         mutate: (mutations) => Promise.resolve(client.mutate(mutations)),
         patch: (table, rowId, partial, options) => Promise.resolve(client.patch(table, rowId, partial, options)),

package/dist/index.d.ts

@@ -10,7 +10,7 @@
 export type { NormalizedClient, SyncClientLike, } from './client.js';
 export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
-export { SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
+export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
 export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
@@ -21,3 +21,4 @@ export { type NamedQueryDescriptor, useQuery, } from './use-query.js';
 export { type UseRawSqlOptions, type UseRawSqlResult, useRawSql, } from './use-raw-sql.js';
 export { type SyncStatus, useSyncStatus } from './use-sync-status.js';
 export { type UseRetainedWindowResult, type UseWindowResult, useRetainedWindow, useWindow, } from './use-window.js';
+export { type RetainedSyncularResource, retainViteSyncClientResource, type ViteSyncClientResourceResult, } from './vite-hmr.js';

package/dist/index.js

@@ -14,3 +14,4 @@ export { useQuery, } from './use-query.js';
 export { useRawSql, } from './use-raw-sql.js';
 export { useSyncStatus } from './use-sync-status.js';
 export { useRetainedWindow, useWindow, } from './use-window.js';
+export { retainViteSyncClientResource, } from './vite-hmr.js';

package/dist/provider.d.ts

@@ -5,7 +5,7 @@
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
-import { ReactiveClientStore } from '@syncular/client';
+import { ReactiveClientStore, type SyncAvailability } from '@syncular/client';
 import { type ReactNode } from 'react';
 import { type NormalizedClient, type SyncClientLike } from './client.js';
 import { type SyncClientResource } from './resource.js';
@@ -17,5 +17,18 @@ export interface SyncProviderProps {
     readonly children?: ReactNode;
     readonly fallback?: ReactNode;
     readonly renderError?: (error: Error, retry: () => Promise<void>) => ReactNode;
+    readonly renderBoundary?: (state: SyncBoundaryState, actions: SyncBoundaryActions) => ReactNode;
+}
+export type SyncBoundaryState = {
+    readonly state: 'starting';
+} | {
+    readonly state: 'startup-error';
+    readonly error: Error;
+    readonly retryable: boolean;
+} | Exclude<SyncAvailability, {
+    readonly state: 'ready';
+}>;
+export interface SyncBoundaryActions {
+    readonly retry?: () => Promise<void>;
 }
 export declare function SyncProvider(props: SyncProviderProps): ReactNode;

package/dist/provider.js

@@ -5,7 +5,7 @@
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
-import { ReactiveClientStore } from '@syncular/client';
+import { ClientSyncError, ReactiveClientStore, } from '@syncular/client';
 import { createContext, createElement, useEffect, useMemo, useSyncExternalStore, } from 'react';
 import { normalizeClient, } from './client.js';
 import { isSyncClientResource } from './resource.js';
@@ -29,6 +29,7 @@ function recordFor(client) {
 function ReadySyncProvider(props) {
     const record = useMemo(() => recordFor(props.client), [props.client]);
     const { normalized, store } = record;
+    const status = useSyncExternalStore(store.status.subscribe, store.status.getSnapshot, store.status.getSnapshot);
     useEffect(() => {
         record.refs += 1;
         store.start();
@@ -40,6 +41,15 @@ function ReadySyncProvider(props) {
             });
         };
     }, [record, store]);
+    if (props.renderBoundary !== undefined) {
+        if (status.isLoading) {
+            return props.renderBoundary({ state: 'starting' }, props.retry === undefined ? {} : { retry: props.retry });
+        }
+        const availability = store.availabilitySnapshot();
+        if (availability.state !== 'ready') {
+            return props.renderBoundary(availability, props.retry === undefined ? {} : { retry: props.retry });
+        }
+    }
     return createElement(SyncContext.Provider, { value: normalized }, createElement(SyncStoreContext.Provider, { value: store }, props.children));
 }
 const noSubscribe = () => () => { };
@@ -53,12 +63,31 @@ export function SyncProvider(props) {
     const snapshot = useSyncExternalStore(resource?.subscribe ?? noSubscribe, resource?.getSnapshot ??
         (() => readySnapshot), resource?.getSnapshot ??
         (() => readySnapshot));
-    if (snapshot.phase === 'pending')
+    if (snapshot.phase === 'pending') {
+        if (props.renderBoundary !== undefined) {
+            return props.renderBoundary({ state: 'starting' }, resource === undefined ? {} : { retry: resource.retry });
+        }
         return props.fallback ?? null;
+    }
     if (snapshot.phase === 'error') {
+        if (props.renderBoundary !== undefined) {
+            return props.renderBoundary({
+                state: 'startup-error',
+                error: snapshot.error,
+                retryable: snapshot.error instanceof ClientSyncError
+                    ? snapshot.error.retryable
+                    : false,
+            }, resource === undefined ? {} : { retry: resource.retry });
+        }
         if (props.renderError !== undefined && resource !== undefined)
             return props.renderError(snapshot.error, resource.retry);
         throw snapshot.error;
     }
-    return createElement(ReadySyncProvider, { client: snapshot.client }, props.children);
+    return createElement(ReadySyncProvider, {
+        client: snapshot.client,
+        ...(props.renderBoundary !== undefined
+            ? { renderBoundary: props.renderBoundary }
+            : {}),
+        ...(resource !== undefined ? { retry: resource.retry } : {}),
+    }, props.children);
 }

package/dist/use-query.d.ts

@@ -26,6 +26,7 @@ export interface NamedQueryDescriptor<Row, Params> {
     readonly hasParams: boolean;
     readonly sql: string;
     readonly tables: readonly string[];
+    readonly mapRow?: (row: Readonly<Record<string, unknown>>) => Row;
     readonly bind: (params: Params) => readonly SqlValue[];
     /** §6 orderBy knob: composes the statement for the CHOSEN order from a
      * generate-time-checked allowlist (identifiers never come from runtime
@@ -37,7 +38,7 @@ export interface NamedQueryDescriptor<Row, Params> {
     /** Phantom row carrier (never read at runtime). */
     readonly __row?: Row;
 }
-type NamedQueryOptions<Row> = Omit<UseRawSqlOptions<Row>, 'tables' | 'scopeKeys' | 'dependencies' | 'coverage' | 'rowKey' | 'id'>;
+type NamedQueryOptions<Row> = Omit<UseRawSqlOptions<Row>, 'tables' | 'scopeKeys' | 'dependencies' | 'coverage' | 'mapRow' | 'rowKey' | 'id'>;
 /** Run a param-less named query live. */
 export declare function useQuery<Row>(query: NamedQueryDescriptor<Row, undefined>, options?: NamedQueryOptions<Row>): UseRawSqlResult<Row>;
 /** Run a named query live with its typed params. */

package/dist/use-query.js

@@ -14,6 +14,7 @@ export function useQuery(query, paramsOrOptions, maybeOptions) {
         id: query.id,
         dependencies,
         coverage,
+        ...(query.mapRow !== undefined ? { mapRow: query.mapRow } : {}),
         ...(query.rowKey !== undefined ? { rowKey: query.rowKey } : {}),
     });
 }

package/dist/use-raw-sql.d.ts

@@ -1,4 +1,4 @@
-import { type LiveQueryPhase, type QueryDependency, type SqlRow, type SqlValue, type WindowCoverage } from '@syncular/client';
+import { type LiveQueryPhase, type QueryDependency, type SqlRow, type SqlValue, type SyncAvailability, type WindowCoverage } from '@syncular/client';
 export interface UseRawSqlOptions<Row = SqlRow> {
     /** Legacy table list; prefer table-associated `dependencies`. */
     readonly tables?: readonly string[];
@@ -6,6 +6,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
     readonly scopeKeys?: readonly string[];
     readonly dependencies?: readonly QueryDependency[];
     readonly coverage?: readonly WindowCoverage[];
+    /** Optional semantic row decoder. Generated named queries provide this. */
+    readonly mapRow?: (row: Readonly<SqlRow>) => Row;
     readonly rowKey?: (row: Row) => readonly SqlValue[];
     /** Generated coverage claims its windows by default. */
     readonly claimCoverage?: boolean;
@@ -20,6 +22,7 @@ export interface UseRawSqlResult<Row> {
     readonly isLoading: boolean;
     readonly isRefreshing: boolean;
     readonly error: Error | undefined;
+    readonly availability: SyncAvailability;
     readonly refresh: () => void;
 }
 export declare function useRawSql<Row = SqlRow>(sql: string, params?: readonly SqlValue[], options?: UseRawSqlOptions<Row>): UseRawSqlResult<Row>;

package/dist/use-raw-sql.js

@@ -8,6 +8,7 @@ const DISABLED = {
     revision: undefined,
     error: undefined,
     isRefreshing: false,
+    availability: { state: 'ready' },
 };
 const noSubscribe = () => () => { };
 export function useRawSql(sql, params, options) {
@@ -31,7 +32,7 @@ export function useRawSql(sql, params, options) {
     });
     // `identity` canonically contains every value-shaped input. Depending on
     // the caller's array/object references would defeat value-stable query
-    // identity; executable rowKey intentionally follows function identity.
+    // identity; executable decoders and row keys follow function identity.
     // biome-ignore lint/correctness/useExhaustiveDependencies: canonical value identity is the dependency
     const entry = useMemo(() => store.query({
         id: options?.id ?? `raw:${identity}`,
@@ -39,9 +40,10 @@ export function useRawSql(sql, params, options) {
         ...(params !== undefined ? { params } : {}),
         dependencies,
         ...(coverage.length > 0 ? { coverage } : {}),
+        ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
         ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
         claimCoverage: options?.claimCoverage ?? true,
-    }), [store, identity, options?.rowKey]);
+    }), [store, identity, options?.mapRow, options?.rowKey]);
     const snapshot = useSyncExternalStore(enabled ? entry.subscribe : noSubscribe, enabled ? entry.getSnapshot : () => DISABLED, enabled ? entry.getSnapshot : () => DISABLED);
     const refresh = useCallback(() => {
         if (enabled)
@@ -54,6 +56,7 @@ export function useRawSql(sql, params, options) {
         isLoading: snapshot.phase === 'loading',
         isRefreshing: snapshot.isRefreshing,
         error: snapshot.error,
+        availability: snapshot.availability,
         refresh,
     };
 }

package/dist/use-sync-status.d.ts

@@ -1,5 +1,6 @@
-import type { LeaseState, SchemaFloor } from '@syncular/client';
+import type { LeaseState, SchemaFloor, SyncAvailability } from '@syncular/client';
 export interface SyncStatus {
+    readonly currentSchemaVersion: number | undefined;
     readonly outbox: number;
     readonly upgrading: boolean;
     readonly leaseState: LeaseState | undefined;
@@ -7,6 +8,7 @@ export interface SyncStatus {
     readonly syncNeeded: boolean;
     readonly isLoading: boolean;
     readonly error: Error | undefined;
+    readonly availability: SyncAvailability;
     readonly refresh: () => void;
 }
 export declare function useSyncStatus(): SyncStatus;

package/dist/use-sync-status.js

@@ -1,10 +1,12 @@
 import { useCallback, useSyncExternalStore } from 'react';
 import { useReactiveStore } from './use-client.js';
 export function useSyncStatus() {
-    const entry = useReactiveStore().status;
+    const store = useReactiveStore();
+    const entry = store.status;
     const snapshot = useSyncExternalStore(entry.subscribe, entry.getSnapshot, entry.getSnapshot);
     const refresh = useCallback(() => entry.refresh(), [entry]);
     return {
+        currentSchemaVersion: snapshot.status?.currentSchemaVersion,
         outbox: snapshot.status?.outbox ?? 0,
         upgrading: snapshot.status?.upgrading ?? false,
         leaseState: snapshot.status?.leaseState,
@@ -12,6 +14,7 @@ export function useSyncStatus() {
         syncNeeded: snapshot.status?.syncNeeded ?? false,
         isLoading: snapshot.isLoading,
         error: snapshot.error,
+        availability: store.availabilitySnapshot(),
         refresh,
     };
 }

package/dist/vite-hmr.d.ts

@@ -0,0 +1,22 @@
+import type { SyncClientLike } from './client.js';
+import { type SyncClientResource } from './resource.js';
+/** The exact value retained in `import.meta.hot.data.syncularClientResource`. */
+export interface RetainedSyncularResource {
+    readonly schemaVersion: number;
+    readonly resource: SyncClientResource;
+}
+export interface ViteSyncClientResourceResult {
+    readonly resource: SyncClientResource;
+    /** True only when an older captured schema identity was replaced. */
+    readonly schemaChanged: boolean;
+    /** A failed close is exposed by `resource` as a startup error. */
+    readonly disposalError?: Error;
+}
+type HotData = Record<string, unknown>;
+/**
+ * Reuse a Vite-owned client only while its captured generated schema matches.
+ * On a bump, the prior resource is fully disposed before the replacement
+ * resource (and therefore its worker) is constructed.
+ */
+export declare function retainViteSyncClientResource(hotData: HotData | undefined, schemaVersion: number, factory: () => SyncClientLike | Promise<SyncClientLike>): Promise<ViteSyncClientResourceResult>;
+export {};

package/dist/vite-hmr.js

@@ -0,0 +1,63 @@
+import { createSyncClientResource } from './resource.js';
+function errorOf(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+function isResource(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.kind === 'syncular-client-resource');
+}
+function retainedFrom(hotData) {
+    const value = hotData?.syncularClientResource;
+    if (isResource(value)) {
+        // Compatibility with the pre-RFC guide, which retained the bare resource.
+        return { resource: value };
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.schemaVersion !== 'number' ||
+        !Number.isInteger(candidate.schemaVersion) ||
+        !isResource(candidate.resource)) {
+        return undefined;
+    }
+    return {
+        schemaVersion: candidate.schemaVersion,
+        resource: candidate.resource,
+    };
+}
+/**
+ * Reuse a Vite-owned client only while its captured generated schema matches.
+ * On a bump, the prior resource is fully disposed before the replacement
+ * resource (and therefore its worker) is constructed.
+ */
+export async function retainViteSyncClientResource(hotData, schemaVersion, factory) {
+    if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
+        throw new TypeError('schemaVersion must be a positive integer');
+    }
+    const retained = retainedFrom(hotData);
+    if (retained?.schemaVersion === schemaVersion) {
+        return { resource: retained.resource, schemaChanged: false };
+    }
+    let disposalError;
+    if (retained !== undefined) {
+        try {
+            await retained.resource.dispose();
+        }
+        catch (error) {
+            disposalError = errorOf(error);
+        }
+    }
+    // A failed disposal must not open a competing owner. Publish a resource
+    // whose ordinary provider startup boundary reports the close failure.
+    const resource = createSyncClientResource(disposalError === undefined ? factory : () => Promise.reject(disposalError));
+    if (hotData !== undefined) {
+        const record = { schemaVersion, resource };
+        hotData.syncularClientResource = record;
+    }
+    return {
+        resource,
+        schemaChanged: retained !== undefined,
+        ...(disposalError !== undefined ? { disposalError } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.13",
+  "version": "0.15.14",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.13"
+    "@syncular/client": "0.15.14"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.15.13",
-    "@syncular/server": "0.15.13",
+    "@syncular/core": "0.15.14",
+    "@syncular/server": "0.15.14",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/client.ts

@@ -17,6 +17,7 @@ import type {
   CommitOutcomeQuery,
   ConflictRecord,
   InvalidationListener,
+  LeadershipState,
   LeaseState,
   LocalDataPurgeInput,
   LocalDataPurgeResult,
@@ -41,9 +42,12 @@ import type {
  * never reach past this surface.
  */
 export interface SyncClientLike {
+  readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
+  onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
+  leadershipSnapshot?(): LeadershipState | undefined;
   query(
     sql: string,
     params?: readonly SqlValue[],
@@ -120,9 +124,12 @@ function resolveMember<T>(
 
 /** The uniform async facade the hooks actually call. */
 export interface NormalizedClient {
+  readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
+  onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
+  leadershipSnapshot(): LeadershipState | undefined;
   query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
   mutate(mutations: readonly MutationInput[]): Promise<string>;
   patch(
@@ -157,9 +164,15 @@ export interface NormalizedClient {
 
 export function normalizeClient(client: SyncClientLike): NormalizedClient {
   return {
+    ...(client.currentSchemaVersion !== undefined
+      ? { currentSchemaVersion: client.currentSchemaVersion }
+      : {}),
     onChange: (listener) => client.onChange(listener),
     onInvalidate: (listener) => client.onInvalidate(listener),
     onPresence: (listener) => client.onPresence(listener),
+    onLeadershipChange: (listener) =>
+      client.onLeadershipChange?.(listener) ?? (() => {}),
+    leadershipSnapshot: () => client.leadershipSnapshot?.(),
     query: (sql, params) => Promise.resolve(client.query(sql, params)),
     mutate: (mutations) => Promise.resolve(client.mutate(mutations)),
     patch: (table, rowId, partial, options) =>

package/src/index.ts

@@ -17,6 +17,8 @@ export type {
 export { normalizeClient } from './client';
 export { inferTables } from './infer-tables';
 export {
+  type SyncBoundaryActions,
+  type SyncBoundaryState,
   SyncContext,
   SyncProvider,
   type SyncProviderProps,
@@ -58,3 +60,8 @@ export {
   useRetainedWindow,
   useWindow,
 } from './use-window';
+export {
+  type RetainedSyncularResource,
+  retainViteSyncClientResource,
+  type ViteSyncClientResourceResult,
+} from './vite-hmr';

package/src/provider.ts

@@ -5,7 +5,11 @@
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
-import { ReactiveClientStore } from '@syncular/client';
+import {
+  ClientSyncError,
+  ReactiveClientStore,
+  type SyncAvailability,
+} from '@syncular/client';
 import {
   createContext,
   createElement,
@@ -37,6 +41,23 @@ export interface SyncProviderProps {
     error: Error,
     retry: () => Promise<void>,
   ) => ReactNode;
+  readonly renderBoundary?: (
+    state: SyncBoundaryState,
+    actions: SyncBoundaryActions,
+  ) => ReactNode;
+}
+
+export type SyncBoundaryState =
+  | { readonly state: 'starting' }
+  | {
+      readonly state: 'startup-error';
+      readonly error: Error;
+      readonly retryable: boolean;
+    }
+  | Exclude<SyncAvailability, { readonly state: 'ready' }>;
+
+export interface SyncBoundaryActions {
+  readonly retry?: () => Promise<void>;
 }
 
 interface ClientRecord {
@@ -65,11 +86,18 @@ function recordFor(client: SyncClientLike): ClientRecord {
 interface ReadySyncProviderProps {
   readonly client: SyncClientLike;
   readonly children?: ReactNode;
+  readonly renderBoundary?: SyncProviderProps['renderBoundary'];
+  readonly retry?: () => Promise<void>;
 }
 
 function ReadySyncProvider(props: ReadySyncProviderProps): ReactNode {
   const record = useMemo(() => recordFor(props.client), [props.client]);
   const { normalized, store } = record;
+  const status = useSyncExternalStore(
+    store.status.subscribe,
+    store.status.getSnapshot,
+    store.status.getSnapshot,
+  );
   useEffect(() => {
     record.refs += 1;
     store.start();
@@ -80,6 +108,21 @@ function ReadySyncProvider(props: ReadySyncProviderProps): ReactNode {
       });
     };
   }, [record, store]);
+  if (props.renderBoundary !== undefined) {
+    if (status.isLoading) {
+      return props.renderBoundary(
+        { state: 'starting' },
+        props.retry === undefined ? {} : { retry: props.retry },
+      );
+    }
+    const availability = store.availabilitySnapshot();
+    if (availability.state !== 'ready') {
+      return props.renderBoundary(
+        availability,
+        props.retry === undefined ? {} : { retry: props.retry },
+      );
+    }
+  }
   return createElement(
     SyncContext.Provider,
     { value: normalized },
@@ -107,15 +150,42 @@ export function SyncProvider(props: SyncProviderProps): ReactNode {
     resource?.getSnapshot ??
       (() => readySnapshot as NonNullable<typeof readySnapshot>),
   );
-  if (snapshot.phase === 'pending') return props.fallback ?? null;
+  if (snapshot.phase === 'pending') {
+    if (props.renderBoundary !== undefined) {
+      return props.renderBoundary(
+        { state: 'starting' },
+        resource === undefined ? {} : { retry: resource.retry },
+      );
+    }
+    return props.fallback ?? null;
+  }
   if (snapshot.phase === 'error') {
+    if (props.renderBoundary !== undefined) {
+      return props.renderBoundary(
+        {
+          state: 'startup-error',
+          error: snapshot.error,
+          retryable:
+            snapshot.error instanceof ClientSyncError
+              ? snapshot.error.retryable
+              : false,
+        },
+        resource === undefined ? {} : { retry: resource.retry },
+      );
+    }
     if (props.renderError !== undefined && resource !== undefined)
       return props.renderError(snapshot.error, resource.retry);
     throw snapshot.error;
   }
   return createElement(
     ReadySyncProvider,
-    { client: snapshot.client },
+    {
+      client: snapshot.client,
+      ...(props.renderBoundary !== undefined
+        ? { renderBoundary: props.renderBoundary }
+        : {}),
+      ...(resource !== undefined ? { retry: resource.retry } : {}),
+    },
     props.children,
   );
 }

package/src/use-query.ts

@@ -35,6 +35,7 @@ export interface NamedQueryDescriptor<Row, Params> {
   readonly hasParams: boolean;
   readonly sql: string;
   readonly tables: readonly string[];
+  readonly mapRow?: (row: Readonly<Record<string, unknown>>) => Row;
   readonly bind: (params: Params) => readonly SqlValue[];
   /** §6 orderBy knob: composes the statement for the CHOSEN order from a
    * generate-time-checked allowlist (identifiers never come from runtime
@@ -49,7 +50,13 @@ export interface NamedQueryDescriptor<Row, Params> {
 
 type NamedQueryOptions<Row> = Omit<
   UseRawSqlOptions<Row>,
-  'tables' | 'scopeKeys' | 'dependencies' | 'coverage' | 'rowKey' | 'id'
+  | 'tables'
+  | 'scopeKeys'
+  | 'dependencies'
+  | 'coverage'
+  | 'mapRow'
+  | 'rowKey'
+  | 'id'
 >;
 
 /** Run a param-less named query live. */
@@ -85,6 +92,7 @@ export function useQuery<Row, Params>(
     id: query.id,
     dependencies,
     coverage,
+    ...(query.mapRow !== undefined ? { mapRow: query.mapRow } : {}),
     ...(query.rowKey !== undefined ? { rowKey: query.rowKey } : {}),
   });
 }

package/src/use-raw-sql.ts

@@ -4,6 +4,7 @@ import {
   type QueryDependency,
   type SqlRow,
   type SqlValue,
+  type SyncAvailability,
   type WindowCoverage,
 } from '@syncular/client';
 import { useCallback, useMemo, useSyncExternalStore } from 'react';
@@ -17,6 +18,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
   readonly scopeKeys?: readonly string[];
   readonly dependencies?: readonly QueryDependency[];
   readonly coverage?: readonly WindowCoverage[];
+  /** Optional semantic row decoder. Generated named queries provide this. */
+  readonly mapRow?: (row: Readonly<SqlRow>) => Row;
   readonly rowKey?: (row: Row) => readonly SqlValue[];
   /** Generated coverage claims its windows by default. */
   readonly claimCoverage?: boolean;
@@ -32,6 +35,7 @@ export interface UseRawSqlResult<Row> {
   readonly isLoading: boolean;
   readonly isRefreshing: boolean;
   readonly error: Error | undefined;
+  readonly availability: SyncAvailability;
   readonly refresh: () => void;
 }
 
@@ -41,6 +45,7 @@ const DISABLED = {
   revision: undefined,
   error: undefined,
   isRefreshing: false,
+  availability: { state: 'ready' },
 } as const;
 
 const noSubscribe = (): (() => void) => () => {};
@@ -71,7 +76,7 @@ export function useRawSql<Row = SqlRow>(
   });
   // `identity` canonically contains every value-shaped input. Depending on
   // the caller's array/object references would defeat value-stable query
-  // identity; executable rowKey intentionally follows function identity.
+  // identity; executable decoders and row keys follow function identity.
   // biome-ignore lint/correctness/useExhaustiveDependencies: canonical value identity is the dependency
   const entry = useMemo(
     () =>
@@ -81,10 +86,11 @@ export function useRawSql<Row = SqlRow>(
         ...(params !== undefined ? { params } : {}),
         dependencies,
         ...(coverage.length > 0 ? { coverage } : {}),
+        ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
         ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
         claimCoverage: options?.claimCoverage ?? true,
       }),
-    [store, identity, options?.rowKey],
+    [store, identity, options?.mapRow, options?.rowKey],
   );
   const snapshot = useSyncExternalStore(
     enabled ? entry.subscribe : noSubscribe,
@@ -101,6 +107,7 @@ export function useRawSql<Row = SqlRow>(
     isLoading: snapshot.phase === 'loading',
     isRefreshing: snapshot.isRefreshing,
     error: snapshot.error,
+    availability: snapshot.availability,
     refresh,
   };
 }

package/src/use-sync-status.ts

@@ -1,8 +1,13 @@
-import type { LeaseState, SchemaFloor } from '@syncular/client';
+import type {
+  LeaseState,
+  SchemaFloor,
+  SyncAvailability,
+} from '@syncular/client';
 import { useCallback, useSyncExternalStore } from 'react';
 import { useReactiveStore } from './use-client';
 
 export interface SyncStatus {
+  readonly currentSchemaVersion: number | undefined;
   readonly outbox: number;
   readonly upgrading: boolean;
   readonly leaseState: LeaseState | undefined;
@@ -10,11 +15,13 @@ export interface SyncStatus {
   readonly syncNeeded: boolean;
   readonly isLoading: boolean;
   readonly error: Error | undefined;
+  readonly availability: SyncAvailability;
   readonly refresh: () => void;
 }
 
 export function useSyncStatus(): SyncStatus {
-  const entry = useReactiveStore().status;
+  const store = useReactiveStore();
+  const entry = store.status;
   const snapshot = useSyncExternalStore(
     entry.subscribe,
     entry.getSnapshot,
@@ -22,6 +29,7 @@ export function useSyncStatus(): SyncStatus {
   );
   const refresh = useCallback(() => entry.refresh(), [entry]);
   return {
+    currentSchemaVersion: snapshot.status?.currentSchemaVersion,
     outbox: snapshot.status?.outbox ?? 0,
     upgrading: snapshot.status?.upgrading ?? false,
     leaseState: snapshot.status?.leaseState,
@@ -29,6 +37,7 @@ export function useSyncStatus(): SyncStatus {
     syncNeeded: snapshot.status?.syncNeeded ?? false,
     isLoading: snapshot.isLoading,
     error: snapshot.error,
+    availability: store.availabilitySnapshot(),
     refresh,
   };
 }

package/src/vite-hmr.ts

@@ -0,0 +1,102 @@
+import type { SyncClientLike } from './client';
+import { createSyncClientResource, type SyncClientResource } from './resource';
+
+/** The exact value retained in `import.meta.hot.data.syncularClientResource`. */
+export interface RetainedSyncularResource {
+  readonly schemaVersion: number;
+  readonly resource: SyncClientResource;
+}
+
+export interface ViteSyncClientResourceResult {
+  readonly resource: SyncClientResource;
+  /** True only when an older captured schema identity was replaced. */
+  readonly schemaChanged: boolean;
+  /** A failed close is exposed by `resource` as a startup error. */
+  readonly disposalError?: Error;
+}
+
+type HotData = Record<string, unknown>;
+
+function errorOf(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+function isResource(value: unknown): value is SyncClientResource {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { readonly kind?: unknown }).kind === 'syncular-client-resource'
+  );
+}
+
+function retainedFrom(
+  hotData: HotData | undefined,
+):
+  | { readonly schemaVersion?: number; readonly resource: SyncClientResource }
+  | undefined {
+  const value = hotData?.syncularClientResource;
+  if (isResource(value)) {
+    // Compatibility with the pre-RFC guide, which retained the bare resource.
+    return { resource: value };
+  }
+  if (typeof value !== 'object' || value === null) return undefined;
+  const candidate = value as {
+    readonly schemaVersion?: unknown;
+    readonly resource?: unknown;
+  };
+  if (
+    typeof candidate.schemaVersion !== 'number' ||
+    !Number.isInteger(candidate.schemaVersion) ||
+    !isResource(candidate.resource)
+  ) {
+    return undefined;
+  }
+  return {
+    schemaVersion: candidate.schemaVersion,
+    resource: candidate.resource,
+  };
+}
+
+/**
+ * Reuse a Vite-owned client only while its captured generated schema matches.
+ * On a bump, the prior resource is fully disposed before the replacement
+ * resource (and therefore its worker) is constructed.
+ */
+export async function retainViteSyncClientResource(
+  hotData: HotData | undefined,
+  schemaVersion: number,
+  factory: () => SyncClientLike | Promise<SyncClientLike>,
+): Promise<ViteSyncClientResourceResult> {
+  if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
+    throw new TypeError('schemaVersion must be a positive integer');
+  }
+
+  const retained = retainedFrom(hotData);
+  if (retained?.schemaVersion === schemaVersion) {
+    return { resource: retained.resource, schemaChanged: false };
+  }
+
+  let disposalError: Error | undefined;
+  if (retained !== undefined) {
+    try {
+      await retained.resource.dispose();
+    } catch (error) {
+      disposalError = errorOf(error);
+    }
+  }
+
+  // A failed disposal must not open a competing owner. Publish a resource
+  // whose ordinary provider startup boundary reports the close failure.
+  const resource = createSyncClientResource(
+    disposalError === undefined ? factory : () => Promise.reject(disposalError),
+  );
+  if (hotData !== undefined) {
+    const record: RetainedSyncularResource = { schemaVersion, resource };
+    hotData.syncularClientResource = record;
+  }
+  return {
+    resource,
+    schemaChanged: retained !== undefined,
+    ...(disposalError !== undefined ? { disposalError } : {}),
+  };
+}