@syncular/react 0.4.1 → 0.5.0

package/README.md

@@ -1,154 +1,171 @@
 # @syncular/react
 
-React bindings for the syncular client, with **fine-grained live
-queries** designed in from day one (TODO 3.1 / `DESIGN-eviction.md` I1–I4).
-A `useRawSql` re-runs **only** when a table it depends on is touched by an
-apply batch — never "re-run everything on any change".
+React 18+ bindings for Syncular's revisioned reactive store. The same hooks
+work with the direct TypeScript client, the browser worker handle, and the
+Tauri/React Native bridges.
 
-Works against **both** client cores through one interface:
+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
+`useSyncExternalStore` adapter over that renderer-independent state.
 
-- `SyncClient` — the direct core (constructed on the current thread), and
-- `SyncClientHandle` — the worker-mode proxy (the whole core in an OPFS
-  worker).
+## Recommended query and mutation path
 
-Their public surfaces diverge (getters vs methods, sync vs promise); the
-bindings normalize both, so a component never cares which it holds.
-
-React 18+ is a **peer dependency**. There are no other runtime dependencies.
-
-## Quick start
+Author reads in `queries/*.sql` or `queries/*.syql`, run `syncular generate`,
+and pass the generated descriptor to `useQuery`:
 
 ```tsx
-import { SyncProvider, useRawSql, useMutation } from '@syncular/react';
-
-// `client` is a SyncClient or a SyncClientHandle you already started.
-function App({ client }) {
-  return (
-    <SyncProvider client={client}>
-      <Tasks />
-    </SyncProvider>
-  );
-}
+import { SyncProvider, useMutation, useQuery } from '@syncular/react';
+import { tasksTable } from './syncular.generated';
+import { listTasksQuery } from './syncular.queries';
 
-function Tasks() {
-  const { rows, isLoading, error, refresh } = useRawSql(
-    'SELECT id, title, done FROM tasks ORDER BY id',
-  );
-  const { mutate } = useMutation();
+function Tasks({ projectId }: { projectId: string }) {
+  const tasks = useQuery(listTasksQuery, { projectId });
+  const mutation = useMutation(tasksTable);
 
-  if (isLoading) return <p>Loading…</p>;
-  if (error) return <p>Query failed: {error.message}</p>;
+  if (tasks.phase === 'loading') return <p>Loading…</p>;
+  if (tasks.phase === 'error') return <p>{tasks.error?.message}</p>;
+  if (tasks.phase === 'ready' && tasks.rows.length === 0) return <p>Empty</p>;
 
   return (
     <ul>
-      {rows.map((r) => (
-        <li key={r.id}>{r.title}</li>
+      {tasks.rows.map((task) => (
+        <li key={task.id}>
+          <button onClick={() => mutation.patch(task.id, { done: !task.done })}>
+            {task.title}
+          </button>
+        </li>
       ))}
-      <button
-        onClick={() =>
-          mutate([
-            {
-              table: 'tasks',
-              op: 'upsert',
-              values: { id: crypto.randomUUID(), project_id: 'p1', title: 'new', done: false },
-            },
-          ])
-        }
-      >
-        Add
-      </button>
     </ul>
   );
 }
 ```
 
-The mutate applies optimistically (§7.1) and fires the invalidation batch, so
-the list updates immediately — no manual refetch.
+Typegen puts these facts on the descriptor:
 
-## The invalidation granularity truth
+- a QueryIR-derived cache id, so SQL-only edits cannot reuse old state;
+- exact table/scope dependencies for change routing;
+- provable window coverage, claimed automatically while observed;
+- a stable row key when the projection proves one.
 
-This is the honest granularity the wire actually provides — read it before
-relying on scope-key narrowing.
+`useQuery` returns `{ rows, phase, revision, isLoading, isRefreshing, error,
+refresh }`. `phase` is:
 
-The web-client emits **exactly one** `{ tables, scopeKeys }` invalidation event
-per apply batch (a pull/delta round, a local `mutate`, a purge, or a
-schema-bump reset — the ONE choke point). Never one event per row.
+- `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;
+- `error`: the initial read failed. A later refresh error keeps existing rows
+  and phase visible through `error`/`isRefreshing`.
 
-- **`tables`** — the set of tables whose local rows changed this batch. This
-  is the **reliable floor**: it is always present and always correct.
-- **`scopeKeys`** — `prefix:value` scope keys (§3.1), present **where the
-  source carried them**:
-  - `COMMIT` frames carry per-row stored scopes (§4.5), so commit-driven
-    invalidation carries **precise** scope keys.
-  - **Segments carry no per-row scope keys** — only a table + a scope digest.
-    A segment (bootstrap / re-bootstrap) invalidation therefore carries the
-    table plus the **subscription's effective scope keys**, the coarsest
-    honest key for bulk data. It never fabricates per-row keys the wire did
-    not deliver.
-  - Purge / reset / optimistic writes are keyed by table (and by effective
-    scope keys where a scope map is in hand).
+## Provider and async initialization
 
-**Consequence for `useRawSql`:** by default a query re-runs whenever a
-depended-on **table** is touched. You may narrow further with `scopeKeys`
-(below), but a **table-level** event (a segment bootstrap, a reset — one that
-carries no scope keys) **always** re-runs a matching query, because it carries
-no key to discriminate on. This is deliberate: under-running is a stale query,
-the one thing a live-query layer must never do.
+A ready client can be passed directly:
 
-## `useRawSql(sql, params?, options?)`
+```tsx
+<SyncProvider client={client}><Tasks projectId="p1" /></SyncProvider>
+```
 
-Runs a local SQL query and keeps it live.
+For async engines, create one resource outside React render. It owns one
+initialization attempt across StrictMode remounts and closes the client exactly
+once when explicitly disposed:
 
-Returns `{ rows, isLoading, error, refresh }`.
+```tsx
+import { createSyncClientResource, SyncProvider } from '@syncular/react';
 
-### Dependency tables — inference and the escape hatch
+const clientResource = createSyncClientResource(() => createClient());
 
-By default the hook infers its dependency tables with a **conservative scan**
-of the SQL text (the identifiers after `FROM`/`JOIN`). This is a heuristic,
-**not** a SQL parser — it is intentionally over-inclusive at the edges (an
-extra harmless re-run) rather than under-inclusive (a stale query).
+<SyncProvider
+  client={clientResource}
+  fallback={<p>Starting local database…</p>}
+  renderError={(error) => <p>{error.message}</p>}
+>
+  <App />
+</SyncProvider>
+```
+
+Call `await clientResource.dispose()` from the application's real lifecycle
+owner, not from a StrictMode-sensitive child effect.
+
+## `useMutation`
 
-When the text cannot be read (dynamic SQL, views, unusual syntax), pass the
-explicit **`tables`** option — it always wins:
+`useMutation()` retains the raw batch API. `useMutation(generatedTable)` adds
+typed `upsert`, `patch`, and `remove` helpers:
 
 ```tsx
-useRawSql(buildDynamicSql(), params, { tables: ['tasks', 'projects'] });
+const mutation = useMutation(tasksTable, {
+  onSuccess(commitId) {},
+  onError(error) {},
+});
+
+await mutation.upsert({ id, projectId, title, done: false });
+await mutation.patch(id, { title: 'Renamed' });
+await mutation.remove(id);
 ```
 
-### Options
+It returns `pendingCount`, `isPending`, `error`, and `resetError`. Overlapping
+writes remain pending until all calls settle. Every method still returns a
+promise and rejects on failure; callbacks do not replace error handling.
 
-| Option      | Meaning                                                                                                                             |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `tables`    | Explicit dependency tables. Overrides the SQL-text inference (the escape hatch).                                                    |
-| `scopeKeys` | Narrow re-runs to specific `prefix:value` keys. A dependency-table event still re-runs if it carries **no** scope keys (see above). |
-| `enabled`   | Skip running while `false` (e.g. inputs not ready).                                                                                 |
+## `useRawSql`
+
+`useRawSql(sql, params?, options?)` is the read-only escape hatch for dynamic
+SQL. It returns the same phase/revision result as `useQuery`.
+
+```tsx
+const summary = useRawSql<{ total: number }>(
+  'SELECT count(*) AS total FROM tasks WHERE project_id = ?',
+  [projectId],
+  {
+    dependencies: [{ table: 'tasks', scopeKeys: [`project:${projectId}`] }],
+  },
+);
+```
+
+Options:
+
+| Option | Meaning |
+| --- | --- |
+| `dependencies` | Exact table-associated dependencies. |
+| `coverage` | Required window units read atomically with the rows. |
+| `rowKey` | Stable identity fields used to retain unchanged row objects. |
+| `claimCoverage` | Claim declared coverage while observed; default `true`. |
+| `enabled` | Disable observation and reads while `false`. |
+| `id` | Stable cache identity for a raw query. |
+| `tables`, `scopeKeys` | Compatibility shorthand; prefer `dependencies`. |
+
+Without explicit dependencies, raw SQL uses a conservative `FROM`/`JOIN`
+scan. Generated queries are preferred whenever the statement is known at
+build time because typegen can prove more.
+
+## Exact changes and windows
+
+Both cores emit one revisioned `ClientChangeBatch` per observer transaction.
+Table changes keep scope keys associated with their table; window changes can
+complete a zero-row unit without inventing a row change; status/conflict-only
+batches do not rerun SQL. Bridges forward this batch unchanged.
+
+Generated query coverage uses composable claims. Multiple consumers of the
+same window base contribute a union, and unmounting one removes only its own
+units. `useWindow(base)` remains the lower-level imperative interface for
+prefetching or dynamic query builders. Applications normally do not need it
+beside a generated `useQuery`.
+
+For a small known navigation working set,
+`useRetainedWindow(base, units)` prefetches and retains those units through the
+same coordinator. It returns `{ isPending, error }`, normalizes duplicate
+units, and releases only its own claim on unmount, so application code does
+not need a custom retention effect.
 
 ## Other hooks
 
-- **`useSyncStatus()`** → `{ outbox, upgrading, leaseState, schemaFloor,
-  syncNeeded, isLoading, refresh }`. Re-reads after every apply batch.
-  (`online` is not a value the core exposes — §1.3 transport-owned — so it is
-  not reported rather than guessed.)
-- **`useConflicts()`** → `{ conflicts, rejections, refresh }` (§6.2/§6.3).
-- **`usePresence(scopeKey)`** → the ephemeral peers present on a §8.6 scope
-  key; updates on join/update/leave. Empty (and never crashes) without a
-  connected realtime socket.
-- **`useMutation()`** → `{ mutate, isPending, error }`. `mutate(mutations)`
-  resolves to the `clientCommitId`; the optimistic overlay is applied
-  immediately, and dependent `useRawSql`s re-run on the resulting batch.
-
-## SSR
-
-The hooks are SSR-safe: on the server they render their initial state and the
-query fires only in the client-side mount effect. `renderToString` never
-crashes.
-
-## Design note — the window registry (forward-looking)
-
-Per `DESIGN-eviction.md` I3, query bindings must be able to route a query's
-scope footprint through the window registry once windowed sync (TODO §5
-item 2) lands, so a query can report **completeness** (answerable from the
-local replica vs a window miss). Today the registry trivially contains
-"everything subscribed", so `useRawSql` always answers from the local
-replica. The `scopeKeys` option is the seam through which per-scope
-completeness will be surfaced without an API break.
+- `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.
+- `useConflicts()` observes conflicts and rejections only when that domain
+  changes.
+- `usePresence(scopeKey)` observes ephemeral realtime peers.
+- `useSyncClient()` and `useReactiveStore()` expose the normalized low-level
+  surfaces for integrations.
+
+The hooks are SSR-safe: no local query runs during server rendering.

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 { ConflictRecord, InvalidationListener, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, ConflictRecord, InvalidationListener, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, 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,10 +19,16 @@ import type { ConflictRecord, InvalidationListener, LeaseState, MutationInput, P
  * never reach past this surface.
  */
 export interface SyncClientLike {
+    onChange(listener: ClientChangeListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     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?: {
+        readonly baseVersion?: number;
+    }): string | Promise<string>;
+    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
+    statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
     conflicts: readonly ConflictRecord[] | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
     rejections: readonly RejectionRecord[] | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
     schemaFloor: SchemaFloor | undefined | (() => SchemaFloor | undefined | Promise<SchemaFloor | undefined>);
@@ -39,10 +45,16 @@ export interface SyncClientLike {
 }
 /** The uniform async facade the hooks actually call. */
 export interface NormalizedClient {
+    onChange(listener: ClientChangeListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => 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>;
+    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
+    statusSnapshot(): Promise<SyncStatusSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
     schemaFloor(): Promise<SchemaFloor | undefined>;

package/dist/client.js

@@ -12,10 +12,14 @@ function resolveMember(client, key) {
 }
 export function normalizeClient(client) {
     return {
+        onChange: (listener) => client.onChange(listener),
         onInvalidate: (listener) => client.onInvalidate(listener),
         onPresence: (listener) => client.onPresence(listener),
         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)),
+        querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
+        statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
         conflicts: () => resolveMember(client, 'conflicts'),
         rejections: () => resolveMember(client, 'rejections'),
         schemaFloor: () => resolveMember(client, 'schemaFloor'),

package/dist/index.d.ts

@@ -10,12 +10,13 @@
 export type { NormalizedClient, SyncClientLike, } from './client.js';
 export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
-export { SyncContext, SyncProvider, type SyncProviderProps } from './provider.js';
-export { useSyncClient } from './use-client.js';
+export { 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 UseConflictsResult, useConflicts } from './use-conflicts.js';
-export { type UseMutationResult, useMutation } from './use-mutation.js';
+export { type SyncTableDescriptor, type UseMutationOptions, type UseMutationResult, type UseTableMutationResult, useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';
 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 UseWindowResult, useWindow } from './use-window.js';
+export { type UseRetainedWindowResult, type UseWindowResult, useRetainedWindow, useWindow, } from './use-window.js';

package/dist/index.js

@@ -3,12 +3,13 @@
 // the exact normalizer the bindings use.
 export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
-export { SyncContext, SyncProvider } from './provider.js';
-export { useSyncClient } from './use-client.js';
+export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
+export { createSyncClientResource, isSyncClientResource, } from './resource.js';
+export { useReactiveStore, useSyncClient } from './use-client.js';
 export { useConflicts } from './use-conflicts.js';
-export { useMutation } from './use-mutation.js';
+export { useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';
 export { useQuery, } from './use-query.js';
 export { useRawSql, } from './use-raw-sql.js';
 export { useSyncStatus } from './use-sync-status.js';
-export { useWindow } from './use-window.js';
+export { useRetainedWindow, useWindow, } from './use-window.js';

package/dist/provider.d.ts

@@ -5,12 +5,17 @@
  * 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 { type ReactNode } from 'react';
 import { type NormalizedClient, type SyncClientLike } from './client.js';
+import { type SyncClientResource } from './resource.js';
 export declare const SyncContext: import("react").Context<NormalizedClient | undefined>;
+export declare const SyncStoreContext: import("react").Context<ReactiveClientStore | undefined>;
 export interface SyncProviderProps {
     /** A `SyncClient` (direct) or `SyncClientHandle` (worker) — both satisfy it. */
-    readonly client: SyncClientLike;
+    readonly client: SyncClientLike | SyncClientResource;
     readonly children?: ReactNode;
+    readonly fallback?: ReactNode;
+    readonly renderError?: (error: Error) => ReactNode;
 }
 export declare function SyncProvider(props: SyncProviderProps): ReactNode;

package/dist/provider.js

@@ -5,11 +5,60 @@
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
-import { createContext, createElement, useMemo } from 'react';
+import { ReactiveClientStore } from '@syncular/client';
+import { createContext, createElement, useEffect, useMemo, useSyncExternalStore, } from 'react';
 import { normalizeClient, } from './client.js';
+import { isSyncClientResource } from './resource.js';
 export const SyncContext = createContext(undefined);
+export const SyncStoreContext = createContext(undefined);
+const stores = new WeakMap();
+function recordFor(client) {
+    const key = client;
+    let record = stores.get(key);
+    if (record === undefined) {
+        const normalized = normalizeClient(client);
+        record = {
+            normalized,
+            store: new ReactiveClientStore(normalized),
+            refs: 0,
+        };
+        stores.set(key, record);
+    }
+    return record;
+}
+function ReadySyncProvider(props) {
+    const record = useMemo(() => recordFor(props.client), [props.client]);
+    const { normalized, store } = record;
+    useEffect(() => {
+        record.refs += 1;
+        store.start();
+        return () => {
+            record.refs -= 1;
+            queueMicrotask(() => {
+                if (record.refs === 0)
+                    store.dispose();
+            });
+        };
+    }, [record, store]);
+    return createElement(SyncContext.Provider, { value: normalized }, createElement(SyncStoreContext.Provider, { value: store }, props.children));
+}
+const noSubscribe = () => () => { };
 export function SyncProvider(props) {
-    // Re-normalize only when the client identity changes.
-    const normalized = useMemo(() => normalizeClient(props.client), [props.client]);
-    return createElement(SyncContext.Provider, { value: normalized }, props.children);
+    const resource = isSyncClientResource(props.client)
+        ? props.client
+        : undefined;
+    const readySnapshot = useMemo(() => resource === undefined
+        ? { phase: 'ready', client: props.client }
+        : undefined, [props.client, resource]);
+    const snapshot = useSyncExternalStore(resource?.subscribe ?? noSubscribe, resource?.getSnapshot ??
+        (() => readySnapshot), resource?.getSnapshot ??
+        (() => readySnapshot));
+    if (snapshot.phase === 'pending')
+        return props.fallback ?? null;
+    if (snapshot.phase === 'error') {
+        if (props.renderError !== undefined)
+            return props.renderError(snapshot.error);
+        throw snapshot.error;
+    }
+    return createElement(ReadySyncProvider, { client: snapshot.client }, props.children);
 }

package/dist/resource.d.ts

@@ -0,0 +1,18 @@
+import type { SyncClientLike } from './client.js';
+export type SyncClientResourceSnapshot = {
+    readonly phase: 'pending';
+} | {
+    readonly phase: 'ready';
+    readonly client: SyncClientLike;
+} | {
+    readonly phase: 'error';
+    readonly error: Error;
+};
+export interface SyncClientResource {
+    readonly kind: 'syncular-client-resource';
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): SyncClientResourceSnapshot;
+    dispose(): Promise<void>;
+}
+export declare function createSyncClientResource(factory: () => SyncClientLike | Promise<SyncClientLike>): SyncClientResource;
+export declare function isSyncClientResource(value: SyncClientLike | SyncClientResource): value is SyncClientResource;

package/dist/resource.js

@@ -0,0 +1,56 @@
+export function createSyncClientResource(factory) {
+    const listeners = new Set();
+    let snapshot = { phase: 'pending' };
+    let disposed = false;
+    let closed = false;
+    const initialized = Promise.resolve()
+        .then(factory)
+        .then(async (client) => {
+        if (disposed) {
+            const close = client
+                .close;
+            if (close !== undefined && !closed) {
+                closed = true;
+                await close.call(client);
+            }
+            return;
+        }
+        snapshot = { phase: 'ready', client };
+        for (const listener of listeners)
+            listener();
+    }, (error) => {
+        if (disposed)
+            return;
+        snapshot = {
+            phase: 'error',
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+        for (const listener of listeners)
+            listener();
+    });
+    return {
+        kind: 'syncular-client-resource',
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot: () => snapshot,
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await initialized;
+            if (snapshot.phase === 'ready' && !closed) {
+                const close = snapshot.client.close;
+                if (close !== undefined) {
+                    closed = true;
+                    await close.call(snapshot.client);
+                }
+            }
+            listeners.clear();
+        },
+    };
+}
+export function isSyncClientResource(value) {
+    return value.kind === 'syncular-client-resource';
+}

package/dist/use-client.d.ts

@@ -1,3 +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;
+export declare function useReactiveStore(): ReactiveClientStore;

package/dist/use-client.js

@@ -1,5 +1,5 @@
 import { useContext } from 'react';
-import { SyncContext } from './provider.js';
+import { SyncContext, SyncStoreContext } from './provider.js';
 /** Read the normalized client from context; throws outside a `SyncProvider`. */
 export function useSyncClient() {
     const client = useContext(SyncContext);
@@ -8,3 +8,10 @@ export function useSyncClient() {
     }
     return client;
 }
+export function useReactiveStore() {
+    const store = useContext(SyncStoreContext);
+    if (store === undefined) {
+        throw new Error('@syncular/react: no client in context (reactive store unavailable) — wrap your tree in <SyncProvider client={…}>');
+    }
+    return store;
+}

package/dist/use-conflicts.d.ts

@@ -1,12 +1,9 @@
-/**
- * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
- * rejections (§6.3) the client has surfaced. Re-read after every apply
- * batch (a push result lands through the same choke point) plus on mount.
- */
 import type { ConflictRecord, RejectionRecord } from '@syncular/client';
 export interface UseConflictsResult {
     readonly conflicts: readonly ConflictRecord[];
     readonly rejections: readonly RejectionRecord[];
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
     readonly refresh: () => void;
 }
 export declare function useConflicts(): UseConflictsResult;

package/dist/use-conflicts.js

@@ -1,37 +1,14 @@
-/**
- * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
- * rejections (§6.3) the client has surfaced. Re-read after every apply
- * batch (a push result lands through the same choke point) plus on mount.
- */
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { useSyncClient } from './use-client.js';
+import { useCallback, useSyncExternalStore } from 'react';
+import { useReactiveStore } from './use-client.js';
 export function useConflicts() {
-    const client = useSyncClient();
-    const [conflicts, setConflicts] = useState([]);
-    const [rejections, setRejections] = useState([]);
-    const readRef = useRef(() => { });
-    const refresh = useCallback(() => readRef.current(), []);
-    useEffect(() => {
-        let cancelled = false;
-        const read = () => {
-            Promise.all([client.conflicts(), client.rejections()])
-                .then(([c, r]) => {
-                if (cancelled)
-                    return;
-                setConflicts(c);
-                setRejections(r);
-            })
-                .catch(() => {
-                /* transient read failure — the next batch re-reads */
-            });
-        };
-        readRef.current = read;
-        read();
-        const unsubscribe = client.onInvalidate(read);
-        return () => {
-            cancelled = true;
-            unsubscribe();
-        };
-    }, [client]);
-    return { conflicts, rejections, refresh };
+    const entry = useReactiveStore().conflicts;
+    const snapshot = useSyncExternalStore(entry.subscribe, entry.getSnapshot, entry.getSnapshot);
+    const refresh = useCallback(() => entry.refresh(), [entry]);
+    return {
+        conflicts: snapshot.conflicts,
+        rejections: snapshot.rejections,
+        isLoading: snapshot.isLoading,
+        error: snapshot.error,
+        refresh,
+    };
 }