@syncular/tauri 0.4.1 → 0.5.1

package/README.md

@@ -2,6 +2,17 @@
 
 Tauri integration for the Syncular client.
 
+Install the bridge together with its required Tauri JavaScript API peer:
+
+```sh
+bun add @syncular/tauri @tauri-apps/api
+```
+
+Reactive snapshots use the plugin's independent read-only SQLite path, so
+local Tauri views remain responsive while the native client is syncing over
+HTTP/WebSocket. Mutations, sync, and all durable writes remain serialized on
+the single mutable core owner.
+
 Part of [Syncular](https://syncular.dev) — an offline-first sync framework.
 See the [Syncular repository](https://github.com/syncular/syncular) for docs.
 

package/dist/index.d.ts

@@ -13,18 +13,20 @@
  * Every method forwards to the plugin's `syncular_command` command (the whole
  * command surface in one JSON envelope — `{method, params}`), mirroring the FFI
  * and the conformance shim. `query` uses the dedicated `syncular_query` fast
- * path (one IPC round trip per live-query run — fine at Tauri IPC latency; see
- * the README's pagination note for very large result sets). Client-observable
- * events (`invalidate` / `presence` / `sync-needed` / `conflict` / …) arrive on
+ * path; atomic reactive reads use `syncular_query_snapshot`, backed by an
+ * independent read-only SQLite connection so network sync cannot stall local
+ * UI reads. Client-observable
+ * events (`change` / `presence`) arrive on
  * the `syncular://event` Tauri event and fan out to the registered listeners.
  *
  * Bytes cross the command JSON as the established `{$bytes: hex}` envelope, the
  * same convention the Rust command router and the driver protocol use.
  *
- * `@tauri-apps/api` is a PEER dependency: the bridge takes `invoke`/`listen`
- * either from the ambient `window.__TAURI__` or via injected doubles (tests).
+ * `@tauri-apps/api` is a required peer dependency: the bridge takes
+ * `invoke`/`listen` either from its ESM entry points, from the ambient
+ * `window.__TAURI__`, or via injected doubles (tests).
  */
-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';
 /** One event pushed on `syncular://event` (the derived client-observable set). */
 interface SyncularEvent {
     readonly type: string;
@@ -44,11 +46,11 @@ export interface TauriSyncClientConfig {
     /** The generated schema JSON (the app passes `schema` from typegen). */
     readonly schema: unknown;
     /**
-     * Client id for this device/actor. If omitted, a stable random id is
-     * generated and persisted by the caller (the bridge does not persist it —
-     * the native side owns the database, so pass the same id across launches).
+     * Client id for this device/actor. If omitted, the native client generates
+     * one and persists it in the database. Supplying a different id when opening
+     * an existing database fails with `client.identity_mismatch`.
      */
-    readonly clientId: string;
+    readonly clientId?: string;
     /** §4.2 client limits, forwarded to the native `create`. */
     readonly limits?: Record<string, unknown>;
     /**
@@ -74,9 +76,16 @@ export declare class TauriSyncClient {
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event: SyncularEvent): void;
     onInvalidate(listener: InvalidationListener): () => void;
+    onChange(listener: ClientChangeListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
+    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
+    localRevision(): Promise<bigint>;
+    statusSnapshot(): Promise<SyncStatusSnapshot>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
+    patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
+        readonly baseVersion?: number;
+    }): Promise<string>;
     /**
      * Replace the native transport's request headers at runtime — the auth
      * rotation path (RFC 0002 §2.3). Pass the FULL header set (it replaces,

package/dist/index.js

@@ -13,16 +13,18 @@
  * Every method forwards to the plugin's `syncular_command` command (the whole
  * command surface in one JSON envelope — `{method, params}`), mirroring the FFI
  * and the conformance shim. `query` uses the dedicated `syncular_query` fast
- * path (one IPC round trip per live-query run — fine at Tauri IPC latency; see
- * the README's pagination note for very large result sets). Client-observable
- * events (`invalidate` / `presence` / `sync-needed` / `conflict` / …) arrive on
+ * path; atomic reactive reads use `syncular_query_snapshot`, backed by an
+ * independent read-only SQLite connection so network sync cannot stall local
+ * UI reads. Client-observable
+ * events (`change` / `presence`) arrive on
  * the `syncular://event` Tauri event and fan out to the registered listeners.
  *
  * Bytes cross the command JSON as the established `{$bytes: hex}` envelope, the
  * same convention the Rust command router and the driver protocol use.
  *
- * `@tauri-apps/api` is a PEER dependency: the bridge takes `invoke`/`listen`
- * either from the ambient `window.__TAURI__` or via injected doubles (tests).
+ * `@tauri-apps/api` is a required peer dependency: the bridge takes
+ * `invoke`/`listen` either from its ESM entry points, from the ambient
+ * `window.__TAURI__`, or via injected doubles (tests).
  */
 /** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
 export const SYNCULAR_EVENT = 'syncular://event';
@@ -32,6 +34,11 @@ function isBytesEnvelope(value) {
         value !== null &&
         typeof value.$bytes === 'string');
 }
+function isBigIntEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.$bigint === 'string');
+}
 function bytesToHex(bytes) {
     let out = '';
     for (const b of bytes) {
@@ -52,13 +59,31 @@ function encodeParam(value) {
     if (value instanceof Uint8Array)
         return { $bytes: bytesToHex(value) };
     if (typeof value === 'bigint')
-        return Number(value);
+        return { $bigint: value.toString() };
+    return value;
+}
+function encodeJsonValue(value) {
+    if (value instanceof Uint8Array)
+        return { $bytes: bytesToHex(value) };
+    if (typeof value === 'bigint')
+        return { $bigint: value.toString() };
+    if (Array.isArray(value))
+        return value.map(encodeJsonValue);
+    if (value !== null && typeof value === 'object') {
+        const encoded = {};
+        for (const [key, member] of Object.entries(value)) {
+            encoded[key] = encodeJsonValue(member);
+        }
+        return encoded;
+    }
     return value;
 }
 /** Decode one query-result cell back to an `SqlValue` (`{$bytes}` → bytes). */
 function decodeCell(value) {
     if (isBytesEnvelope(value))
         return hexToBytes(value.$bytes);
+    if (isBigIntEnvelope(value))
+        return BigInt(value.$bigint);
     if (value === null ||
         typeof value === 'string' ||
         typeof value === 'number' ||
@@ -93,13 +118,14 @@ async function resolveTauri(injected) {
             listen: ambient.event.listen.bind(ambient.event),
         };
     }
-    // Fall back to the ESM package (the common path). The specifiers are built
-    // indirectly so this optional peer dependency is not a hard compile-time
-    // module resolution — apps that inject `tauri` (or use the ambient global)
-    // never need `@tauri-apps/api` type-resolvable at build.
-    const dynamicImport = (specifier) => import(/* @vite-ignore */ specifier);
-    const core = (await dynamicImport('@tauri-apps/api/core'));
-    const event = (await dynamicImport('@tauri-apps/api/event'));
+    // Fall back to the ESM package (the common path). These must remain literal,
+    // bundler-visible specifiers: hiding a bare package import behind
+    // `@vite-ignore` makes WebKit resolve it as a URL at runtime instead of
+    // letting Vite/Bun include the Tauri API in the webview bundle.
+    const [core, event] = await Promise.all([
+        import('@tauri-apps/api/core'),
+        import('@tauri-apps/api/event'),
+    ]);
     return { invoke: core.invoke, listen: event.listen };
 }
 /**
@@ -110,6 +136,7 @@ async function resolveTauri(injected) {
 export class TauriSyncClient {
     #tauri;
     #invalidationListeners = new Set();
+    #changeListeners = new Set();
     #presenceListeners = new Set();
     #unlisten;
     #closed = false;
@@ -129,13 +156,21 @@ export class TauriSyncClient {
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event) {
         switch (event.type) {
-            case 'invalidate': {
-                // The native side derives a coarse invalidate (table granularity is the
-                // honest floor — the plugin does not ship per-row scope keys over IPC).
-                const payload = {
-                    tables: toStringSet(event.tables),
-                    scopeKeys: toStringSet(event.scopeKeys),
-                };
+            case 'change': {
+                const batch = decodeChangeBatch(event.batch);
+                if (batch === undefined)
+                    break;
+                for (const listener of this.#changeListeners) {
+                    try {
+                        listener(batch);
+                    }
+                    catch {
+                        /* a UI listener must never break event dispatch */
+                    }
+                }
+                const payload = invalidationFromChange(batch);
+                if (payload === undefined)
+                    break;
                 for (const listener of this.#invalidationListeners) {
                     try {
                         listener(payload);
@@ -159,9 +194,8 @@ export class TauriSyncClient {
                 break;
             }
             default:
-                // sync-needed / conflict / rejection / schema-floor / lease / error:
-                // observable via the accessor methods; a coarse invalidate already
-                // accompanies data-changing events, so nothing else to fan out here.
+                // Unknown extension events are deliberately ignored. All durable
+                // observable state arrives in the revisioned `change` batch.
                 break;
         }
     }
@@ -170,6 +204,10 @@ export class TauriSyncClient {
         this.#invalidationListeners.add(listener);
         return () => this.#invalidationListeners.delete(listener);
     }
+    onChange(listener) {
+        this.#changeListeners.add(listener);
+        return () => this.#changeListeners.delete(listener);
+    }
     onPresence(listener) {
         this.#presenceListeners.add(listener);
         return () => this.#presenceListeners.delete(listener);
@@ -182,12 +220,46 @@ export class TauriSyncClient {
         const rows = reply.result.rows ?? [];
         return rows.map((r) => decodeRow(r));
     }
+    async querySnapshot(spec) {
+        const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query_snapshot`, {
+            sql: spec.sql,
+            params: (spec.params ?? []).map(encodeParam),
+            coverage: spec.coverage ?? [],
+        });
+        if (reply.error !== undefined) {
+            throw new TauriSyncError(reply.error.code, reply.error.message);
+        }
+        const result = reply.result;
+        return {
+            revision: BigInt(result.revision),
+            rows: result.rows.map(decodeRow),
+            coverage: result.coverage,
+        };
+    }
+    async localRevision() {
+        const result = (await this.#command('localRevision', {}));
+        return BigInt(result.revision);
+    }
+    async statusSnapshot() {
+        return (await this.#command('statusSnapshot', {}));
+    }
     async mutate(mutations) {
         const result = (await this.#command('mutate', {
             mutations: mutations.map(encodeMutation),
         }));
         return result.clientCommitId;
     }
+    async patch(table, rowId, partial, options) {
+        const result = (await this.#command('patch', {
+            table,
+            rowId,
+            partial: encodeJsonValue(partial),
+            ...(options?.baseVersion !== undefined
+                ? { baseVersion: options.baseVersion }
+                : {}),
+        }));
+        return result.clientCommitId;
+    }
     /**
      * Replace the native transport's request headers at runtime — the auth
      * rotation path (RFC 0002 §2.3). Pass the FULL header set (it replaces,
@@ -328,6 +400,7 @@ export class TauriSyncClient {
         this.#unlisten?.();
         this.#unlisten = undefined;
         this.#invalidationListeners.clear();
+        this.#changeListeners.clear();
         this.#presenceListeners.clear();
     }
 }
@@ -346,10 +419,82 @@ function toStringSet(value) {
     }
     return new Set();
 }
+function decodeChangeBatch(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    if (typeof raw.revision !== 'string')
+        return undefined;
+    const tables = Array.isArray(raw.tables)
+        ? raw.tables.flatMap((entry) => {
+            if (entry === null || typeof entry !== 'object')
+                return [];
+            const item = entry;
+            if (typeof item.table !== 'string')
+                return [];
+            return [
+                {
+                    table: item.table,
+                    ...(Array.isArray(item.scopeKeys)
+                        ? { scopeKeys: toStringSet(item.scopeKeys) }
+                        : {}),
+                },
+            ];
+        })
+        : [];
+    const windows = Array.isArray(raw.windows)
+        ? raw.windows.flatMap((entry) => {
+            if (entry === null || typeof entry !== 'object')
+                return [];
+            const item = entry;
+            if (typeof item.baseKey !== 'string' ||
+                typeof item.table !== 'string') {
+                return [];
+            }
+            return [
+                {
+                    baseKey: item.baseKey,
+                    table: item.table,
+                    units: toStringSet(item.units),
+                },
+            ];
+        })
+        : [];
+    return {
+        revision: BigInt(raw.revision),
+        tables,
+        windows,
+        ...(raw.status !== undefined
+            ? { status: raw.status }
+            : {}),
+        conflictsChanged: raw.conflictsChanged === true,
+        rejectionsChanged: raw.rejectionsChanged === true,
+    };
+}
+function invalidationFromChange(batch) {
+    if (batch.tables.length === 0 && batch.windows.length === 0)
+        return undefined;
+    const tables = new Set();
+    const scopeKeys = new Set();
+    for (const table of batch.tables) {
+        tables.add(table.table);
+        for (const key of table.scopeKeys ?? [])
+            scopeKeys.add(key);
+    }
+    for (const window of batch.windows)
+        tables.add(window.table);
+    return { tables, scopeKeys };
+}
 /** Encode one mutation for the command JSON (bytes inside `values` handled by
  * the native side; the driver form is already JSON-able). */
 function encodeMutation(mutation) {
-    return mutation;
+    if (mutation.op === 'delete')
+        return mutation;
+    const values = {};
+    for (const [key, value] of Object.entries(mutation.values)) {
+        values[key] = encodeJsonValue(value);
+    }
+    return { ...mutation, values };
 }
 /**
  * Construct the bridge and issue the native `create` (opening/attaching the
@@ -359,7 +504,7 @@ function encodeMutation(mutation) {
  */
 export async function createTauriSyncClient(config) {
     const tauri = await resolveTauri(config.tauri);
-    // Wire the event stream BEFORE create, so no early invalidate is missed.
+    // Wire the event stream BEFORE create, so no early change batch is missed.
     const clientRef = {
         client: undefined,
     };
@@ -374,7 +519,7 @@ export async function createTauriSyncClient(config) {
         command: {
             method: 'create',
             params: {
-                clientId: config.clientId,
+                ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
                 schema: config.schema,
                 ...(config.limits !== undefined ? { limits: config.limits } : {}),
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/tauri",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Tauri integration for the Syncular client",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,17 +48,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@syncular/client": "0.4.1"
+    "@syncular/client": "0.5.1"
   },
   "peerDependencies": {
     "@tauri-apps/api": ">=2.0.0"
   },
-  "peerDependenciesMeta": {
-    "@tauri-apps/api": {
-      "optional": true
-    }
-  },
   "devDependencies": {
-    "@syncular/react": "0.4.1"
+    "@syncular/react": "0.5.1"
   }
 }

package/src/index.ts

@@ -13,32 +13,39 @@
  * Every method forwards to the plugin's `syncular_command` command (the whole
  * command surface in one JSON envelope — `{method, params}`), mirroring the FFI
  * and the conformance shim. `query` uses the dedicated `syncular_query` fast
- * path (one IPC round trip per live-query run — fine at Tauri IPC latency; see
- * the README's pagination note for very large result sets). Client-observable
- * events (`invalidate` / `presence` / `sync-needed` / `conflict` / …) arrive on
+ * path; atomic reactive reads use `syncular_query_snapshot`, backed by an
+ * independent read-only SQLite connection so network sync cannot stall local
+ * UI reads. Client-observable
+ * events (`change` / `presence`) arrive on
  * the `syncular://event` Tauri event and fan out to the registered listeners.
  *
  * Bytes cross the command JSON as the established `{$bytes: hex}` envelope, the
  * same convention the Rust command router and the driver protocol use.
  *
- * `@tauri-apps/api` is a PEER dependency: the bridge takes `invoke`/`listen`
- * either from the ambient `window.__TAURI__` or via injected doubles (tests).
+ * `@tauri-apps/api` is a required peer dependency: the bridge takes
+ * `invoke`/`listen` either from its ESM entry points, from the ambient
+ * `window.__TAURI__`, or via injected doubles (tests).
  */
 
 // -- Types the bridge speaks (structurally the web-client's) -----------------
 // Imported as types only, so the bridge has no runtime dependency on
 // @syncular/client (the app already carries it via @syncular/react).
 import type {
+  ClientChangeBatch,
+  ClientChangeListener,
   ConflictRecord,
   InvalidationEvent,
   InvalidationListener,
   LeaseState,
   MutationInput,
   PresencePeer,
+  QueryReadSpec,
+  QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
   SqlRow,
   SqlValue,
+  SyncStatusSnapshot,
   WindowBase,
   WindowState,
 } from '@syncular/client';
@@ -74,11 +81,11 @@ export interface TauriSyncClientConfig {
   /** The generated schema JSON (the app passes `schema` from typegen). */
   readonly schema: unknown;
   /**
-   * Client id for this device/actor. If omitted, a stable random id is
-   * generated and persisted by the caller (the bridge does not persist it —
-   * the native side owns the database, so pass the same id across launches).
+   * Client id for this device/actor. If omitted, the native client generates
+   * one and persists it in the database. Supplying a different id when opening
+   * an existing database fails with `client.identity_mismatch`.
    */
-  readonly clientId: string;
+  readonly clientId?: string;
   /** §4.2 client limits, forwarded to the native `create`. */
   readonly limits?: Record<string, unknown>;
   /**
@@ -91,6 +98,7 @@ export interface TauriSyncClientConfig {
 
 /** The bytes envelope both sides share. */
 export type BytesEnvelope = { readonly $bytes: string };
+type BigIntEnvelope = { readonly $bigint: string };
 
 function isBytesEnvelope(value: unknown): value is BytesEnvelope {
   return (
@@ -100,6 +108,14 @@ function isBytesEnvelope(value: unknown): value is BytesEnvelope {
   );
 }
 
+function isBigIntEnvelope(value: unknown): value is BigIntEnvelope {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { $bigint?: unknown }).$bigint === 'string'
+  );
+}
+
 function bytesToHex(bytes: Uint8Array): string {
   let out = '';
   for (const b of bytes) {
@@ -120,13 +136,28 @@ function hexToBytes(hex: string): Uint8Array {
 /** Encode an SQL param for the command JSON (bytes → `{$bytes: hex}`). */
 function encodeParam(value: SqlValue): unknown {
   if (value instanceof Uint8Array) return { $bytes: bytesToHex(value) };
-  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'bigint') return { $bigint: value.toString() };
+  return value;
+}
+
+function encodeJsonValue(value: unknown): unknown {
+  if (value instanceof Uint8Array) return { $bytes: bytesToHex(value) };
+  if (typeof value === 'bigint') return { $bigint: value.toString() };
+  if (Array.isArray(value)) return value.map(encodeJsonValue);
+  if (value !== null && typeof value === 'object') {
+    const encoded: Record<string, unknown> = {};
+    for (const [key, member] of Object.entries(value)) {
+      encoded[key] = encodeJsonValue(member);
+    }
+    return encoded;
+  }
   return value;
 }
 
 /** Decode one query-result cell back to an `SqlValue` (`{$bytes}` → bytes). */
 function decodeCell(value: unknown): SqlValue {
   if (isBytesEnvelope(value)) return hexToBytes(value.$bytes);
+  if (isBigIntEnvelope(value)) return BigInt(value.$bigint);
   if (
     value === null ||
     typeof value === 'string' ||
@@ -170,18 +201,14 @@ async function resolveTauri(injected: TauriApi | undefined): Promise<TauriApi> {
       listen: ambient.event.listen.bind(ambient.event),
     };
   }
-  // Fall back to the ESM package (the common path). The specifiers are built
-  // indirectly so this optional peer dependency is not a hard compile-time
-  // module resolution — apps that inject `tauri` (or use the ambient global)
-  // never need `@tauri-apps/api` type-resolvable at build.
-  const dynamicImport = (specifier: string): Promise<unknown> =>
-    import(/* @vite-ignore */ specifier);
-  const core = (await dynamicImport('@tauri-apps/api/core')) as {
-    invoke: TauriApi['invoke'];
-  };
-  const event = (await dynamicImport('@tauri-apps/api/event')) as {
-    listen: TauriApi['listen'];
-  };
+  // Fall back to the ESM package (the common path). These must remain literal,
+  // bundler-visible specifiers: hiding a bare package import behind
+  // `@vite-ignore` makes WebKit resolve it as a URL at runtime instead of
+  // letting Vite/Bun include the Tauri API in the webview bundle.
+  const [core, event] = await Promise.all([
+    import('@tauri-apps/api/core'),
+    import('@tauri-apps/api/event'),
+  ]);
   return { invoke: core.invoke, listen: event.listen };
 }
 
@@ -193,6 +220,7 @@ async function resolveTauri(injected: TauriApi | undefined): Promise<TauriApi> {
 export class TauriSyncClient {
   readonly #tauri: TauriApi;
   readonly #invalidationListeners = new Set<InvalidationListener>();
+  readonly #changeListeners = new Set<ClientChangeListener>();
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
   #unlisten: (() => void) | undefined;
   #closed = false;
@@ -221,13 +249,18 @@ export class TauriSyncClient {
   /** @internal — fan an incoming plugin event out to the local listeners. */
   __dispatchEvent(event: SyncularEvent): void {
     switch (event.type) {
-      case 'invalidate': {
-        // The native side derives a coarse invalidate (table granularity is the
-        // honest floor — the plugin does not ship per-row scope keys over IPC).
-        const payload: InvalidationEvent = {
-          tables: toStringSet(event.tables),
-          scopeKeys: toStringSet(event.scopeKeys),
-        };
+      case 'change': {
+        const batch = decodeChangeBatch(event.batch);
+        if (batch === undefined) break;
+        for (const listener of this.#changeListeners) {
+          try {
+            listener(batch);
+          } catch {
+            /* a UI listener must never break event dispatch */
+          }
+        }
+        const payload = invalidationFromChange(batch);
+        if (payload === undefined) break;
         for (const listener of this.#invalidationListeners) {
           try {
             listener(payload);
@@ -250,9 +283,8 @@ export class TauriSyncClient {
         break;
       }
       default:
-        // sync-needed / conflict / rejection / schema-floor / lease / error:
-        // observable via the accessor methods; a coarse invalidate already
-        // accompanies data-changing events, so nothing else to fan out here.
+        // Unknown extension events are deliberately ignored. All durable
+        // observable state arrives in the revisioned `change` batch.
         break;
     }
   }
@@ -264,6 +296,11 @@ export class TauriSyncClient {
     return () => this.#invalidationListeners.delete(listener);
   }
 
+  onChange(listener: ClientChangeListener): () => void {
+    this.#changeListeners.add(listener);
+    return () => this.#changeListeners.delete(listener);
+  }
+
   onPresence(listener: (scopeKey: string) => void): () => void {
     this.#presenceListeners.add(listener);
     return () => this.#presenceListeners.delete(listener);
@@ -281,6 +318,43 @@ export class TauriSyncClient {
     return rows.map((r) => decodeRow(r as Record<string, unknown>));
   }
 
+  async querySnapshot<Row = SqlRow>(
+    spec: QueryReadSpec,
+  ): Promise<QuerySnapshot<Row>> {
+    const reply = await this.#tauri.invoke<CommandReply>(
+      `${PLUGIN}syncular_query_snapshot`,
+      {
+        sql: spec.sql,
+        params: (spec.params ?? []).map(encodeParam),
+        coverage: spec.coverage ?? [],
+      },
+    );
+    if (reply.error !== undefined) {
+      throw new TauriSyncError(reply.error.code, reply.error.message);
+    }
+    const result = reply.result as {
+      revision: string;
+      rows: Record<string, unknown>[];
+      coverage: QuerySnapshot['coverage'];
+    };
+    return {
+      revision: BigInt(result.revision),
+      rows: result.rows.map(decodeRow) as unknown as readonly Row[],
+      coverage: result.coverage,
+    };
+  }
+
+  async localRevision(): Promise<bigint> {
+    const result = (await this.#command('localRevision', {})) as {
+      revision: string;
+    };
+    return BigInt(result.revision);
+  }
+
+  async statusSnapshot(): Promise<SyncStatusSnapshot> {
+    return (await this.#command('statusSnapshot', {})) as SyncStatusSnapshot;
+  }
+
   async mutate(mutations: readonly MutationInput[]): Promise<string> {
     const result = (await this.#command('mutate', {
       mutations: mutations.map(encodeMutation),
@@ -288,6 +362,23 @@ export class TauriSyncClient {
     return result.clientCommitId;
   }
 
+  async patch(
+    table: string,
+    rowId: string,
+    partial: Readonly<Record<string, unknown>>,
+    options?: { readonly baseVersion?: number },
+  ): Promise<string> {
+    const result = (await this.#command('patch', {
+      table,
+      rowId,
+      partial: encodeJsonValue(partial),
+      ...(options?.baseVersion !== undefined
+        ? { baseVersion: options.baseVersion }
+        : {}),
+    })) as { clientCommitId: string };
+    return result.clientCommitId;
+  }
+
   /**
    * Replace the native transport's request headers at runtime — the auth
    * rotation path (RFC 0002 §2.3). Pass the FULL header set (it replaces,
@@ -499,6 +590,7 @@ export class TauriSyncClient {
     this.#unlisten?.();
     this.#unlisten = undefined;
     this.#invalidationListeners.clear();
+    this.#changeListeners.clear();
     this.#presenceListeners.clear();
   }
 }
@@ -520,10 +612,79 @@ function toStringSet(value: unknown): ReadonlySet<string> {
   return new Set<string>();
 }
 
+function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.revision !== 'string') return undefined;
+  const tables = Array.isArray(raw.tables)
+    ? raw.tables.flatMap((entry) => {
+        if (entry === null || typeof entry !== 'object') return [];
+        const item = entry as Record<string, unknown>;
+        if (typeof item.table !== 'string') return [];
+        return [
+          {
+            table: item.table,
+            ...(Array.isArray(item.scopeKeys)
+              ? { scopeKeys: toStringSet(item.scopeKeys) }
+              : {}),
+          },
+        ];
+      })
+    : [];
+  const windows = Array.isArray(raw.windows)
+    ? raw.windows.flatMap((entry) => {
+        if (entry === null || typeof entry !== 'object') return [];
+        const item = entry as Record<string, unknown>;
+        if (
+          typeof item.baseKey !== 'string' ||
+          typeof item.table !== 'string'
+        ) {
+          return [];
+        }
+        return [
+          {
+            baseKey: item.baseKey,
+            table: item.table,
+            units: toStringSet(item.units),
+          },
+        ];
+      })
+    : [];
+  return {
+    revision: BigInt(raw.revision),
+    tables,
+    windows,
+    ...(raw.status !== undefined
+      ? { status: raw.status as SyncStatusSnapshot }
+      : {}),
+    conflictsChanged: raw.conflictsChanged === true,
+    rejectionsChanged: raw.rejectionsChanged === true,
+  };
+}
+
+function invalidationFromChange(
+  batch: ClientChangeBatch,
+): InvalidationEvent | undefined {
+  if (batch.tables.length === 0 && batch.windows.length === 0) return undefined;
+  const tables = new Set<string>();
+  const scopeKeys = new Set<string>();
+  for (const table of batch.tables) {
+    tables.add(table.table);
+    for (const key of table.scopeKeys ?? []) scopeKeys.add(key);
+  }
+  for (const window of batch.windows) tables.add(window.table);
+  return { tables, scopeKeys };
+}
+
 /** Encode one mutation for the command JSON (bytes inside `values` handled by
  * the native side; the driver form is already JSON-able). */
 function encodeMutation(mutation: MutationInput): unknown {
-  return mutation;
+  if (mutation.op === 'delete') return mutation;
+  const values: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(mutation.values)) {
+    values[key] = encodeJsonValue(value);
+  }
+  return { ...mutation, values };
 }
 
 /**
@@ -537,7 +698,7 @@ export async function createTauriSyncClient(
 ): Promise<TauriSyncClient> {
   const tauri = await resolveTauri(config.tauri);
 
-  // Wire the event stream BEFORE create, so no early invalidate is missed.
+  // Wire the event stream BEFORE create, so no early change batch is missed.
   const clientRef: { client: TauriSyncClient | undefined } = {
     client: undefined,
   };
@@ -557,7 +718,7 @@ export async function createTauriSyncClient(
     command: {
       method: 'create',
       params: {
-        clientId: config.clientId,
+        ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         schema: config.schema,
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
       },