@syncular/react 0.15.48 → 0.16.1

package/README.md

@@ -6,7 +6,10 @@ Tauri/React Native bridges.
 
 The store is client-scoped, not hook-scoped. Equal queries share one local SQL
 read per revision, rows and window completeness come from one SQLite snapshot,
-and stale promises cannot overwrite a newer revision. React is only a
+and stale promises cannot overwrite a newer revision. Status, conflict, and
+outcome refreshes discard older pending results after a newer read or event.
+Presence reads follow the same ordering and clear peers when the client or
+scope changes. React is only a
 `useSyncExternalStore` adapter over that renderer-independent state.
 
 ## Recommended query and mutation path
@@ -176,7 +179,7 @@ typed `upsert`, `patch`, and `remove` helpers:
 
 ```tsx
 const mutation = useMutation(tasksTable, {
-  onSuccess(commitId) {},
+  onEnqueued(commitId) {},
   onError(error) {},
 });
 
@@ -322,3 +325,21 @@ The snapshot deliberately excludes scopes, rows, clinical counts, SQL, paths,
 identities, credentials, mutation bodies, stack traces, and arbitrary prose.
 Do not enrich the copied bundle with database files, query results, or console
 dumps. See SPEC §7.6 for the complete contract.
+
+Query and window observers retain inactive entries only until the next
+microtask. The final unsubscribe removes the entry from change dispatch
+immediately; cleanup releases its rows and invalidates pending reads. A
+same-microtask remount preserves the shared snapshot. A later subscription
+starts a fresh read, including subscriptions held by an older React render.
+Releasing the final window owner removes the empty claim group after the
+core has applied the release. Disposing the store rejects unapplied retention
+handles with `client.reactive_store_disposed`.
+
+`SyncProvider` keeps the supplied client identity. `useSyncClient()` returns
+that client, whose read methods can return either values or promises. Use
+`await client.statusSnapshot()` in application code that supports multiple
+hosts. The `schemaFloor`, `leaseState`, `upgrading`, and `syncNeeded` fields
+come from that snapshot. Direct `conflicts`, `rejections`, and
+`securityLifecycle` reads are now method calls. `normalizeClient` has been
+removed; custom adapters must implement the canonical snapshot methods.
+See the [client migration](https://syncular.dev/platform-web/#snapshot-api-migration).

package/dist/client.d.ts

@@ -1,24 +1,6 @@
-/**
- * The ONE client interface the React bindings target. Both the direct
- * `SyncClient` (constructed on the current thread) and the worker-mode
- * `SyncClientHandle` (a promise proxy over the OPFS worker) satisfy it —
- * their public surfaces diverge (getters vs methods, sync vs promise), so
- * this module normalizes both into a single async-friendly facade the hooks
- * consume. That is the "one interface across direct and worker-handle modes"
- * the invalidation seam enables.
- *
- * The normalizer resolves each accessor at call time (function → call it,
- * value → read it) and wraps every result in `Promise.resolve`, so a hook
- * never has to care which core it holds.
- */
-import type { ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SecurityLifecycle, 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}
- * collapses the divergence. Only what the hooks use is listed — the bindings
- * never reach past this surface.
- */
-export interface SyncClientLike {
+/** The provider uses the supplied client identity and canonical snapshot methods. */
+import type { ClientSnapshotReader, ClientChangeListener, ClientDiagnosticsListener, InvalidationListener, LeadershipState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
+export interface SyncClientLike extends ClientSnapshotReader {
     readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     onDiagnostics(listener: ClientDiagnosticsListener): () => void;
@@ -26,7 +8,7 @@ export interface SyncClientLike {
     onPresence(listener: (scopeKey: string) => void): () => void;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
     leadershipSnapshot?(): LeadershipState | undefined;
-    securityLifecycle: SecurityLifecycle | (() => SecurityLifecycle | Promise<SecurityLifecycle>);
+    securityLifecycle(): SecurityLifecycle | Promise<SecurityLifecycle>;
     beginSecurityPreflight(): void | Promise<void>;
     /** Key-bearing activation remains available on each concrete host type. */
     activateSecurity(): void | Promise<void>;
@@ -38,17 +20,6 @@ export interface SyncClientLike {
     purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult | Promise<LocalDataPurgeResult>;
     rebootstrapLocalData(input: LocalDataRebootstrapInput): LocalDataRebootstrapResult | Promise<LocalDataRebootstrapResult>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
-    statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
-    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
-    conflicts: readonly ConflictRecord[] | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
-    rejections: readonly RejectionRecord[] | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
-    commitOutcome(clientCommitId: string): CommitOutcome | undefined | Promise<CommitOutcome | undefined>;
-    commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
-    resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome | Promise<CommitOutcome>;
-    schemaFloor: SchemaFloor | undefined | (() => SchemaFloor | undefined | Promise<SchemaFloor | undefined>);
-    leaseState: LeaseState | undefined | (() => LeaseState | undefined | Promise<LeaseState | undefined>);
-    upgrading: boolean | (() => boolean | Promise<boolean>);
-    syncNeeded: boolean | (() => boolean | Promise<boolean>);
     pendingCommits: () => unknown[] | Promise<unknown[]>;
     presence(scopeKey: string): readonly PresencePeer[] | Promise<readonly PresencePeer[]>;
     setPresence(scopeKey: string, doc: Record<string, unknown> | null): void | Promise<void>;
@@ -57,42 +28,3 @@ export interface SyncClientLike {
     /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
     windowState(base: WindowBase): WindowState | Promise<WindowState>;
 }
-/** The uniform async facade the hooks actually call. */
-export interface NormalizedClient {
-    readonly currentSchemaVersion?: number;
-    onChange(listener: ClientChangeListener): () => void;
-    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
-    onInvalidate(listener: InvalidationListener): () => void;
-    onPresence(listener: (scopeKey: string) => void): () => void;
-    onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
-    leadershipSnapshot(): LeadershipState | undefined;
-    securityLifecycle(): Promise<SecurityLifecycle>;
-    beginSecurityPreflight(): Promise<void>;
-    /** Key-bearing activation remains available on each concrete host type. */
-    activateSecurity(): Promise<void>;
-    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?: {
-        readonly baseVersion?: number;
-    }): Promise<string>;
-    purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
-    rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
-    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
-    statusSnapshot(): Promise<SyncStatusSnapshot>;
-    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
-    conflicts(): Promise<readonly ConflictRecord[]>;
-    rejections(): Promise<readonly RejectionRecord[]>;
-    commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
-    commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
-    resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
-    schemaFloor(): Promise<SchemaFloor | undefined>;
-    leaseState(): Promise<LeaseState | undefined>;
-    upgrading(): Promise<boolean>;
-    syncNeeded(): Promise<boolean>;
-    pendingCommits(): Promise<unknown[]>;
-    presence(scopeKey: string): Promise<readonly PresencePeer[]>;
-    setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
-    setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
-    windowState(base: WindowBase): Promise<WindowState>;
-}
-export declare function normalizeClient(client: SyncClientLike): NormalizedClient;

package/dist/client.js

@@ -1,65 +1 @@
-/**
- * The ONE client interface the React bindings target. Both the direct
- * `SyncClient` (constructed on the current thread) and the worker-mode
- * `SyncClientHandle` (a promise proxy over the OPFS worker) satisfy it —
- * their public surfaces diverge (getters vs methods, sync vs promise), so
- * this module normalizes both into a single async-friendly facade the hooks
- * consume. That is the "one interface across direct and worker-handle modes"
- * the invalidation seam enables.
- *
- * The normalizer resolves each accessor at call time (function → call it,
- * value → read it) and wraps every result in `Promise.resolve`, so a hook
- * never has to care which core it holds.
- */
-import { linkRealtimeSupervisorObservation } from '@syncular/client/realtime-supervisor-observation';
-/**
- * Read a member by key that is EITHER a value getter (SyncClient) or a
- * method returning a value/promise (SyncClientHandle). Read from the client
- * so a method keeps its `this` binding; if the read is a function, call it.
- */
-function resolveMember(client, key) {
-    const member = client[key];
-    const value = typeof member === 'function'
-        ? member.call(client)
-        : member;
-    return Promise.resolve(value);
-}
-export function normalizeClient(client) {
-    const normalized = {
-        ...(client.currentSchemaVersion !== undefined
-            ? { currentSchemaVersion: client.currentSchemaVersion }
-            : {}),
-        onChange: (listener) => client.onChange(listener),
-        onDiagnostics: (listener) => client.onDiagnostics(listener),
-        onInvalidate: (listener) => client.onInvalidate(listener),
-        onPresence: (listener) => client.onPresence(listener),
-        onLeadershipChange: (listener) => client.onLeadershipChange?.(listener) ?? (() => { }),
-        leadershipSnapshot: () => client.leadershipSnapshot?.(),
-        securityLifecycle: () => resolveMember(client, 'securityLifecycle'),
-        beginSecurityPreflight: () => Promise.resolve(client.beginSecurityPreflight()),
-        activateSecurity: () => Promise.resolve(client.activateSecurity()),
-        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)),
-        purgeLocalData: (input) => Promise.resolve(client.purgeLocalData(input)),
-        rebootstrapLocalData: (input) => Promise.resolve(client.rebootstrapLocalData(input)),
-        querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
-        statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
-        diagnosticsSnapshot: (request) => Promise.resolve(client.diagnosticsSnapshot(request)),
-        conflicts: () => resolveMember(client, 'conflicts'),
-        rejections: () => resolveMember(client, 'rejections'),
-        commitOutcome: (clientCommitId) => Promise.resolve(client.commitOutcome(clientCommitId)),
-        commitOutcomes: (query) => Promise.resolve(client.commitOutcomes(query)),
-        resolveCommitOutcome: (input) => Promise.resolve(client.resolveCommitOutcome(input)),
-        schemaFloor: () => resolveMember(client, 'schemaFloor'),
-        leaseState: () => resolveMember(client, 'leaseState'),
-        upgrading: () => resolveMember(client, 'upgrading'),
-        syncNeeded: () => resolveMember(client, 'syncNeeded'),
-        pendingCommits: () => resolveMember(client, 'pendingCommits'),
-        presence: (scopeKey) => Promise.resolve(client.presence(scopeKey)),
-        setPresence: (scopeKey, doc) => Promise.resolve(client.setPresence(scopeKey, doc)),
-        setWindow: (base, units) => Promise.resolve(client.setWindow(base, units)),
-        windowState: (base) => Promise.resolve(client.windowState(base)),
-    };
-    return linkRealtimeSupervisorObservation(normalized, client);
-}
+export {};

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 /**
  * @syncular/react — React bindings with fine-grained live queries
  * Works against BOTH `SyncClient`
- * (direct) and `SyncClientHandle` (worker) through one normalized client
+ * (direct) and `SyncClientHandle` (worker) through the canonical client
  * interface. React 18+ (react is a peer dependency); no other runtime deps.
  *
  * See README.md for the invalidation granularity truth and the `tables`
  * option.
  */
-export type { NormalizedClient, SyncClientLike } from './client.js';
-export { normalizeClient } from './client.js';
+export type { SyncClientLike } from './client.js';
 export { inferTables } from './infer-tables.js';
 export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';

package/dist/index.js

@@ -1,7 +1,3 @@
-// `normalizeClient` is the runtime facade the hooks consume; exported so
-// alternate hosts (e.g. `@syncular/tauri`) can assert shape-parity against
-// the exact normalizer the bindings use.
-export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
 export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, } from './resource.js';

package/dist/provider.d.ts

@@ -1,15 +1,15 @@
 /**
  * `SyncProvider` — supplies a `SyncClient` or `SyncClientHandle` to the
  * hook tree through React context. One provider per client; the hooks read
- * the normalized facade. Written with `createElement` (no JSX) so the whole
+ * the supplied client. Written with `createElement` (no JSX) so the whole
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
 import { ReactiveClientStore, type SyncAvailability } from '@syncular/client';
 import { type ReactNode } from 'react';
-import { type NormalizedClient, type SyncClientLike } from './client.js';
+import { type SyncClientLike } from './client.js';
 import { type SyncClientResource } from './resource.js';
-export declare const SyncContext: import("react").Context<NormalizedClient | undefined>;
+export declare const SyncContext: import("react").Context<SyncClientLike | undefined>;
 export declare const SyncStoreContext: import("react").Context<ReactiveClientStore | undefined>;
 export interface SyncProviderProps {
     /** A `SyncClient` (direct) or `SyncClientHandle` (worker) — both satisfy it. */

package/dist/provider.js

@@ -1,13 +1,13 @@
 /**
  * `SyncProvider` — supplies a `SyncClient` or `SyncClientHandle` to the
  * hook tree through React context. One provider per client; the hooks read
- * the normalized facade. Written with `createElement` (no JSX) so the whole
+ * the supplied client. Written with `createElement` (no JSX) so the whole
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
 import { ClientSyncError, ReactiveClientStore, } from '@syncular/client';
 import { createContext, createElement, useEffect, useMemo, useSyncExternalStore, } from 'react';
-import { normalizeClient, } from './client.js';
+import {} from './client.js';
 import { isSyncClientResource } from './resource.js';
 export const SyncContext = createContext(undefined);
 export const SyncStoreContext = createContext(undefined);
@@ -16,10 +16,8 @@ function recordFor(client) {
     const key = client;
     let record = stores.get(key);
     if (record === undefined) {
-        const normalized = normalizeClient(client);
         record = {
-            normalized,
-            store: new ReactiveClientStore(normalized),
+            store: new ReactiveClientStore(client),
             refs: 0,
         };
         stores.set(key, record);
@@ -28,7 +26,7 @@ function recordFor(client) {
 }
 function ReadySyncProvider(props) {
     const record = useMemo(() => recordFor(props.client), [props.client]);
-    const { normalized, store } = record;
+    const { store } = record;
     const status = useSyncExternalStore(store.status.subscribe, store.status.getSnapshot, store.status.getSnapshot);
     useEffect(() => {
         record.refs += 1;
@@ -50,7 +48,7 @@ function ReadySyncProvider(props) {
             return props.renderBoundary(availability, props.retry === undefined ? {} : { retry: props.retry });
         }
     }
-    return createElement(SyncContext.Provider, { value: normalized }, createElement(SyncStoreContext.Provider, { value: store }, props.children));
+    return createElement(SyncContext.Provider, { value: props.client }, createElement(SyncStoreContext.Provider, { value: store }, props.children));
 }
 const noSubscribe = () => () => { };
 export function SyncProvider(props) {

package/dist/runtime-version.d.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.15.48";
+export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.16.1";

package/dist/runtime-version.js

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.48';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.16.1';

package/dist/use-client.d.ts

@@ -1,5 +1,5 @@
 import type { ReactiveClientStore } from '@syncular/client';
-import type { NormalizedClient } from './client.js';
-/** Read the normalized client from context; throws outside a `SyncProvider`. */
-export declare function useSyncClient(): NormalizedClient;
+import type { SyncClientLike } from './client.js';
+/** Read the supplied client from context; throws outside a `SyncProvider`. */
+export declare function useSyncClient(): SyncClientLike;
 export declare function useReactiveStore(): ReactiveClientStore;

package/dist/use-client.js

@@ -1,6 +1,6 @@
 import { useContext } from 'react';
 import { SyncContext, SyncStoreContext } from './provider.js';
-/** Read the normalized client from context; throws outside a `SyncProvider`. */
+/** Read the supplied client from context; throws outside a `SyncProvider`. */
 export function useSyncClient() {
     const client = useContext(SyncContext);
     if (client === undefined) {

package/dist/use-diagnostics.js

@@ -19,7 +19,9 @@ export function useDiagnostics(options = {}) {
     const refresh = useCallback(() => {
         const current = ++generation.current;
         setIsLoading(true);
-        void client.diagnosticsSnapshot(request).then((next) => {
+        void Promise.resolve()
+            .then(() => client.diagnosticsSnapshot(request))
+            .then((next) => {
             if (generation.current !== current)
                 return;
             setSnapshot(next);

package/dist/use-mutation.d.ts

@@ -9,12 +9,14 @@ export interface SyncTableDescriptor<Row, Insert, Update, Id> {
     readonly __id?: Id;
 }
 export interface UseMutationOptions {
-    readonly onSuccess?: (clientCommitId: string) => void;
+    /** Runs after durable local enqueue. The server outcome can still reject this commit. */
+    readonly onEnqueued?: (clientCommitId: string) => void;
     readonly onError?: (error: Error) => void;
 }
 export interface UseMutationResult {
     mutate: (mutations: readonly MutationInput[]) => Promise<string>;
     readonly pendingCount: number;
+    /** True while at least one local enqueue is unresolved. */
     readonly isPending: boolean;
     readonly error: Error | undefined;
     readonly resetError: () => void;

package/dist/use-mutation.js

@@ -18,7 +18,7 @@ export function useMutation(tableOrOptions, maybeOptions) {
         setError(undefined);
         try {
             const id = await operation();
-            optionsRef.current?.onSuccess?.(id);
+            optionsRef.current?.onEnqueued?.(id);
             return id;
         }
         catch (caught) {

package/dist/use-presence.js

@@ -8,30 +8,41 @@
  */
 import { useEffect, useState } from 'react';
 import { useSyncClient } from './use-client.js';
+const EMPTY_PEERS = [];
 export function usePresence(scopeKey) {
     const client = useSyncClient();
-    const [peers, setPeers] = useState([]);
+    const [snapshot, setSnapshot] = useState(() => ({ client, scopeKey, peers: EMPTY_PEERS }));
+    if (snapshot.client !== client || snapshot.scopeKey !== scopeKey) {
+        setSnapshot({ client, scopeKey, peers: EMPTY_PEERS });
+    }
     useEffect(() => {
-        let cancelled = false;
+        let generation = 0;
         const read = () => {
-            Promise.resolve(client.presence(scopeKey))
-                .then((list) => {
-                if (!cancelled)
-                    setPeers(list);
+            const request = ++generation;
+            void Promise.resolve()
+                .then(() => client.presence(scopeKey))
+                .then((peers) => {
+                if (request === generation) {
+                    setSnapshot((previous) => previous.client === client && previous.scopeKey === scopeKey
+                        ? { client, scopeKey, peers }
+                        : previous);
+                }
             })
                 .catch(() => {
-                /* transient — the next presence event re-reads */
+                // Keep the current scope's last snapshot until the next event.
             });
         };
-        read();
         const unsubscribe = client.onPresence((changedKey) => {
             if (changedKey === scopeKey)
                 read();
         });
+        read();
         return () => {
-            cancelled = true;
+            generation += 1;
             unsubscribe();
         };
     }, [client, scopeKey]);
-    return peers;
+    return snapshot.client === client && snapshot.scopeKey === scopeKey
+        ? snapshot.peers
+        : EMPTY_PEERS;
 }

package/package.json

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

package/src/client.ts

@@ -1,28 +1,10 @@
-/**
- * The ONE client interface the React bindings target. Both the direct
- * `SyncClient` (constructed on the current thread) and the worker-mode
- * `SyncClientHandle` (a promise proxy over the OPFS worker) satisfy it —
- * their public surfaces diverge (getters vs methods, sync vs promise), so
- * this module normalizes both into a single async-friendly facade the hooks
- * consume. That is the "one interface across direct and worker-handle modes"
- * the invalidation seam enables.
- *
- * The normalizer resolves each accessor at call time (function → call it,
- * value → read it) and wraps every result in `Promise.resolve`, so a hook
- * never has to care which core it holds.
- */
-
+/** The provider uses the supplied client identity and canonical snapshot methods. */
 import type {
+  ClientSnapshotReader,
   ClientChangeListener,
   ClientDiagnosticsListener,
-  ClientDiagnosticsRequest,
-  ClientDiagnosticsSnapshot,
-  CommitOutcome,
-  CommitOutcomeQuery,
-  ConflictRecord,
   InvalidationListener,
   LeadershipState,
-  LeaseState,
   LocalDataPurgeInput,
   LocalDataPurgeResult,
   LocalDataRebootstrapInput,
@@ -31,25 +13,14 @@ import type {
   PresencePeer,
   QueryReadSpec,
   QuerySnapshot,
-  RejectionRecord,
-  ResolveCommitOutcomeInput,
-  SchemaFloor,
   SecurityLifecycle,
   SqlRow,
   SqlValue,
-  SyncStatusSnapshot,
   WindowBase,
   WindowState,
 } from '@syncular/client';
-import { linkRealtimeSupervisorObservation } from '@syncular/client/realtime-supervisor-observation';
 
-/**
- * The structural union of `SyncClient` and `SyncClientHandle`. Members that
- * diverge are typed as "value or method, sync or promise"; {@link normalizeClient}
- * collapses the divergence. Only what the hooks use is listed — the bindings
- * never reach past this surface.
- */
-export interface SyncClientLike {
+export interface SyncClientLike extends ClientSnapshotReader {
   readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
   onDiagnostics(listener: ClientDiagnosticsListener): () => void;
@@ -57,9 +28,7 @@ export interface SyncClientLike {
   onPresence(listener: (scopeKey: string) => void): () => void;
   onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
   leadershipSnapshot?(): LeadershipState | undefined;
-  securityLifecycle:
-    | SecurityLifecycle
-    | (() => SecurityLifecycle | Promise<SecurityLifecycle>);
+  securityLifecycle(): SecurityLifecycle | Promise<SecurityLifecycle>;
   beginSecurityPreflight(): void | Promise<void>;
   /** Key-bearing activation remains available on each concrete host type. */
   activateSecurity(): void | Promise<void>;
@@ -83,35 +52,6 @@ export interface SyncClientLike {
   querySnapshot<Row = SqlRow>(
     spec: QueryReadSpec,
   ): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
-  statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
-  diagnosticsSnapshot(
-    request?: ClientDiagnosticsRequest,
-  ): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
-  conflicts:
-    | readonly ConflictRecord[]
-    | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
-  rejections:
-    | readonly RejectionRecord[]
-    | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
-  commitOutcome(
-    clientCommitId: string,
-  ): CommitOutcome | undefined | Promise<CommitOutcome | undefined>;
-  commitOutcomes(
-    query?: CommitOutcomeQuery,
-  ): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
-  resolveCommitOutcome(
-    input: ResolveCommitOutcomeInput,
-  ): CommitOutcome | Promise<CommitOutcome>;
-  schemaFloor:
-    | SchemaFloor
-    | undefined
-    | (() => SchemaFloor | undefined | Promise<SchemaFloor | undefined>);
-  leaseState:
-    | LeaseState
-    | undefined
-    | (() => LeaseState | undefined | Promise<LeaseState | undefined>);
-  upgrading: boolean | (() => boolean | Promise<boolean>);
-  syncNeeded: boolean | (() => boolean | Promise<boolean>);
   pendingCommits: () => unknown[] | Promise<unknown[]>;
   presence(
     scopeKey: string,
@@ -125,119 +65,3 @@ export interface SyncClientLike {
   /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
   windowState(base: WindowBase): WindowState | Promise<WindowState>;
 }
-
-/**
- * Read a member by key that is EITHER a value getter (SyncClient) or a
- * method returning a value/promise (SyncClientHandle). Read from the client
- * so a method keeps its `this` binding; if the read is a function, call it.
- */
-function resolveMember<T>(
-  client: SyncClientLike,
-  key: keyof SyncClientLike,
-): Promise<T> {
-  const member = client[key] as unknown;
-  const value =
-    typeof member === 'function'
-      ? (member as (this: SyncClientLike) => T | Promise<T>).call(client)
-      : (member as T);
-  return Promise.resolve(value as T);
-}
-
-/** The uniform async facade the hooks actually call. */
-export interface NormalizedClient {
-  readonly currentSchemaVersion?: number;
-  onChange(listener: ClientChangeListener): () => void;
-  onDiagnostics(listener: ClientDiagnosticsListener): () => void;
-  onInvalidate(listener: InvalidationListener): () => void;
-  onPresence(listener: (scopeKey: string) => void): () => void;
-  onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
-  leadershipSnapshot(): LeadershipState | undefined;
-  securityLifecycle(): Promise<SecurityLifecycle>;
-  beginSecurityPreflight(): Promise<void>;
-  /** Key-bearing activation remains available on each concrete host type. */
-  activateSecurity(): Promise<void>;
-  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?: { readonly baseVersion?: number },
-  ): Promise<string>;
-  purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
-  rebootstrapLocalData(
-    input: LocalDataRebootstrapInput,
-  ): Promise<LocalDataRebootstrapResult>;
-  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
-  statusSnapshot(): Promise<SyncStatusSnapshot>;
-  diagnosticsSnapshot(
-    request?: ClientDiagnosticsRequest,
-  ): Promise<ClientDiagnosticsSnapshot>;
-  conflicts(): Promise<readonly ConflictRecord[]>;
-  rejections(): Promise<readonly RejectionRecord[]>;
-  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
-  commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
-  resolveCommitOutcome(
-    input: ResolveCommitOutcomeInput,
-  ): Promise<CommitOutcome>;
-  schemaFloor(): Promise<SchemaFloor | undefined>;
-  leaseState(): Promise<LeaseState | undefined>;
-  upgrading(): Promise<boolean>;
-  syncNeeded(): Promise<boolean>;
-  pendingCommits(): Promise<unknown[]>;
-  presence(scopeKey: string): Promise<readonly PresencePeer[]>;
-  setPresence(
-    scopeKey: string,
-    doc: Record<string, unknown> | null,
-  ): Promise<void>;
-  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
-  windowState(base: WindowBase): Promise<WindowState>;
-}
-
-export function normalizeClient(client: SyncClientLike): NormalizedClient {
-  const normalized: NormalizedClient = {
-    ...(client.currentSchemaVersion !== undefined
-      ? { currentSchemaVersion: client.currentSchemaVersion }
-      : {}),
-    onChange: (listener) => client.onChange(listener),
-    onDiagnostics: (listener) => client.onDiagnostics(listener),
-    onInvalidate: (listener) => client.onInvalidate(listener),
-    onPresence: (listener) => client.onPresence(listener),
-    onLeadershipChange: (listener) =>
-      client.onLeadershipChange?.(listener) ?? (() => {}),
-    leadershipSnapshot: () => client.leadershipSnapshot?.(),
-    securityLifecycle: () => resolveMember(client, 'securityLifecycle'),
-    beginSecurityPreflight: () =>
-      Promise.resolve(client.beginSecurityPreflight()),
-    activateSecurity: () => Promise.resolve(client.activateSecurity()),
-    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)),
-    purgeLocalData: (input) => Promise.resolve(client.purgeLocalData(input)),
-    rebootstrapLocalData: (input) =>
-      Promise.resolve(client.rebootstrapLocalData(input)),
-    querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
-    statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
-    diagnosticsSnapshot: (request) =>
-      Promise.resolve(client.diagnosticsSnapshot(request)),
-    conflicts: () => resolveMember(client, 'conflicts'),
-    rejections: () => resolveMember(client, 'rejections'),
-    commitOutcome: (clientCommitId) =>
-      Promise.resolve(client.commitOutcome(clientCommitId)),
-    commitOutcomes: (query) => Promise.resolve(client.commitOutcomes(query)),
-    resolveCommitOutcome: (input) =>
-      Promise.resolve(client.resolveCommitOutcome(input)),
-    schemaFloor: () => resolveMember(client, 'schemaFloor'),
-    leaseState: () => resolveMember(client, 'leaseState'),
-    upgrading: () => resolveMember(client, 'upgrading'),
-    syncNeeded: () => resolveMember(client, 'syncNeeded'),
-    pendingCommits: () => resolveMember(client, 'pendingCommits'),
-    presence: (scopeKey) => Promise.resolve(client.presence(scopeKey)),
-    setPresence: (scopeKey, doc) =>
-      Promise.resolve(client.setPresence(scopeKey, doc)),
-    setWindow: (base, units) => Promise.resolve(client.setWindow(base, units)),
-    windowState: (base) => Promise.resolve(client.windowState(base)),
-  };
-  return linkRealtimeSupervisorObservation(normalized, client);
-}

package/src/index.ts

@@ -1,17 +1,13 @@
 /**
  * @syncular/react — React bindings with fine-grained live queries
  * Works against BOTH `SyncClient`
- * (direct) and `SyncClientHandle` (worker) through one normalized client
+ * (direct) and `SyncClientHandle` (worker) through the canonical client
  * interface. React 18+ (react is a peer dependency); no other runtime deps.
  *
  * See README.md for the invalidation granularity truth and the `tables`
  * option.
  */
-export type { NormalizedClient, SyncClientLike } from './client';
-// `normalizeClient` is the runtime facade the hooks consume; exported so
-// alternate hosts (e.g. `@syncular/tauri`) can assert shape-parity against
-// the exact normalizer the bindings use.
-export { normalizeClient } from './client';
+export type { SyncClientLike } from './client';
 export { inferTables } from './infer-tables';
 export {
   type SyncBoundaryActions,

package/src/provider.ts

@@ -1,7 +1,7 @@
 /**
  * `SyncProvider` — supplies a `SyncClient` or `SyncClientHandle` to the
  * hook tree through React context. One provider per client; the hooks read
- * the normalized facade. Written with `createElement` (no JSX) so the whole
+ * the supplied client. Written with `createElement` (no JSX) so the whole
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
@@ -18,16 +18,10 @@ import {
   useMemo,
   useSyncExternalStore,
 } from 'react';
-import {
-  type NormalizedClient,
-  normalizeClient,
-  type SyncClientLike,
-} from './client';
+import { type SyncClientLike } from './client';
 import { isSyncClientResource, type SyncClientResource } from './resource';
 
-export const SyncContext = createContext<NormalizedClient | undefined>(
-  undefined,
-);
+export const SyncContext = createContext<SyncClientLike | undefined>(undefined);
 export const SyncStoreContext = createContext<ReactiveClientStore | undefined>(
   undefined,
 );
@@ -61,7 +55,6 @@ export interface SyncBoundaryActions {
 }
 
 interface ClientRecord {
-  readonly normalized: NormalizedClient;
   readonly store: ReactiveClientStore;
   refs: number;
 }
@@ -72,10 +65,8 @@ function recordFor(client: SyncClientLike): ClientRecord {
   const key = client as object;
   let record = stores.get(key);
   if (record === undefined) {
-    const normalized = normalizeClient(client);
     record = {
-      normalized,
-      store: new ReactiveClientStore(normalized),
+      store: new ReactiveClientStore(client),
       refs: 0,
     };
     stores.set(key, record);
@@ -92,7 +83,7 @@ interface ReadySyncProviderProps {
 
 function ReadySyncProvider(props: ReadySyncProviderProps): ReactNode {
   const record = useMemo(() => recordFor(props.client), [props.client]);
-  const { normalized, store } = record;
+  const { store } = record;
   const status = useSyncExternalStore(
     store.status.subscribe,
     store.status.getSnapshot,
@@ -125,7 +116,7 @@ function ReadySyncProvider(props: ReadySyncProviderProps): ReactNode {
   }
   return createElement(
     SyncContext.Provider,
-    { value: normalized },
+    { value: props.client },
     createElement(SyncStoreContext.Provider, { value: store }, props.children),
   );
 }

package/src/runtime-version.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.48';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.16.1';

package/src/use-client.ts

@@ -1,10 +1,10 @@
 import type { ReactiveClientStore } from '@syncular/client';
 import { useContext } from 'react';
-import type { NormalizedClient } from './client';
+import type { SyncClientLike } from './client';
 import { SyncContext, SyncStoreContext } from './provider';
 
-/** Read the normalized client from context; throws outside a `SyncProvider`. */
-export function useSyncClient(): NormalizedClient {
+/** Read the supplied client from context; throws outside a `SyncProvider`. */
+export function useSyncClient(): SyncClientLike {
   const client = useContext(SyncContext);
   if (client === undefined) {
     throw new Error(

package/src/use-diagnostics.ts

@@ -47,19 +47,23 @@ export function useDiagnostics(
   const refresh = useCallback(() => {
     const current = ++generation.current;
     setIsLoading(true);
-    void client.diagnosticsSnapshot(request).then(
-      (next) => {
-        if (generation.current !== current) return;
-        setSnapshot(next);
-        setError(undefined);
-        setIsLoading(false);
-      },
-      (reason: unknown) => {
-        if (generation.current !== current) return;
-        setError(reason instanceof Error ? reason : new Error(String(reason)));
-        setIsLoading(false);
-      },
-    );
+    void Promise.resolve()
+      .then(() => client.diagnosticsSnapshot(request))
+      .then(
+        (next) => {
+          if (generation.current !== current) return;
+          setSnapshot(next);
+          setError(undefined);
+          setIsLoading(false);
+        },
+        (reason: unknown) => {
+          if (generation.current !== current) return;
+          setError(
+            reason instanceof Error ? reason : new Error(String(reason)),
+          );
+          setIsLoading(false);
+        },
+      );
   }, [client, request]);
 
   useEffect(() => {

package/src/use-mutation.ts

@@ -13,13 +13,15 @@ export interface SyncTableDescriptor<Row, Insert, Update, Id> {
 }
 
 export interface UseMutationOptions {
-  readonly onSuccess?: (clientCommitId: string) => void;
+  /** Runs after durable local enqueue. The server outcome can still reject this commit. */
+  readonly onEnqueued?: (clientCommitId: string) => void;
   readonly onError?: (error: Error) => void;
 }
 
 export interface UseMutationResult {
   mutate: (mutations: readonly MutationInput[]) => Promise<string>;
   readonly pendingCount: number;
+  /** True while at least one local enqueue is unresolved. */
   readonly isPending: boolean;
   readonly error: Error | undefined;
   readonly resetError: () => void;
@@ -66,12 +68,12 @@ export function useMutation<Row, Insert, Update, Id>(
   const resetError = useCallback(() => setError(undefined), []);
 
   const run = useCallback(
-    async (operation: () => Promise<string>): Promise<string> => {
+    async (operation: () => string | Promise<string>): Promise<string> => {
       setPendingCount((count) => count + 1);
       setError(undefined);
       try {
         const id = await operation();
-        optionsRef.current?.onSuccess?.(id);
+        optionsRef.current?.onEnqueued?.(id);
         return id;
       } catch (caught) {
         const wrapped =

package/src/use-presence.ts

@@ -9,32 +9,52 @@
 
 import type { PresencePeer } from '@syncular/client';
 import { useEffect, useState } from 'react';
+import type { SyncClientLike } from './client';
 import { useSyncClient } from './use-client';
 
+const EMPTY_PEERS: readonly PresencePeer[] = [];
+
 export function usePresence(scopeKey: string): readonly PresencePeer[] {
   const client = useSyncClient();
-  const [peers, setPeers] = useState<readonly PresencePeer[]>([]);
+  const [snapshot, setSnapshot] = useState<{
+    client: SyncClientLike;
+    scopeKey: string;
+    peers: readonly PresencePeer[];
+  }>(() => ({ client, scopeKey, peers: EMPTY_PEERS }));
+  if (snapshot.client !== client || snapshot.scopeKey !== scopeKey) {
+    setSnapshot({ client, scopeKey, peers: EMPTY_PEERS });
+  }
 
   useEffect(() => {
-    let cancelled = false;
+    let generation = 0;
     const read = () => {
-      Promise.resolve(client.presence(scopeKey))
-        .then((list) => {
-          if (!cancelled) setPeers(list);
+      const request = ++generation;
+      void Promise.resolve()
+        .then(() => client.presence(scopeKey))
+        .then((peers) => {
+          if (request === generation) {
+            setSnapshot((previous) =>
+              previous.client === client && previous.scopeKey === scopeKey
+                ? { client, scopeKey, peers }
+                : previous,
+            );
+          }
         })
         .catch(() => {
-          /* transient — the next presence event re-reads */
+          // Keep the current scope's last snapshot until the next event.
         });
     };
-    read();
     const unsubscribe = client.onPresence((changedKey) => {
       if (changedKey === scopeKey) read();
     });
+    read();
     return () => {
-      cancelled = true;
+      generation += 1;
       unsubscribe();
     };
   }, [client, scopeKey]);
 
-  return peers;
+  return snapshot.client === client && snapshot.scopeKey === scopeKey
+    ? snapshot.peers
+    : EMPTY_PEERS;
 }