@syncular/tauri 0.2.0

package/README.md

@@ -0,0 +1,10 @@
+# @syncular/tauri
+
+Tauri integration for the Syncular client.
+
+Part of [Syncular](https://syncular.dev) — an offline-first sync framework.
+See the [Syncular repository](https://github.com/syncular/syncular) for docs.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @syncular/tauri — the JS bridge to the native syncular instance running
+ * inside the Tauri process (see `tauri-plugin-syncular`).
+ *
+ * The Tauri host runs a REAL Rust syncular client (file DB + native HTTP+WS
+ * transport). This module is a thin webview-side proxy that implements the SAME
+ * `SyncClientLike` interface the React package normalizes — so the hooks
+ * (`useSyncQuery`, `useMutation`, `usePresence`, …) work UNCHANGED against a
+ * Tauri app. It is the fourth host of one interface, after the direct
+ * `SyncClient`, the worker-leader `SyncClientHandle`, and the multi-tab
+ * follower (ROADMAP.md block 1).
+ *
+ * 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
+ * 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).
+ */
+import type { ConflictRecord, InvalidationListener, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
+/** One event pushed on `syncular://event` (the derived client-observable set). */
+interface SyncularEvent {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/** The two Tauri primitives the bridge needs — injectable for tests. */
+export interface TauriApi {
+    invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
+    listen<T>(event: string, handler: (event: {
+        payload: T;
+    }) => void): Promise<() => void>;
+}
+/** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
+export declare const SYNCULAR_EVENT = "syncular://event";
+/** Config for {@link createTauriSyncClient}. */
+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).
+     */
+    readonly clientId: string;
+    /** §4.2 client limits, forwarded to the native `create`. */
+    readonly limits?: Record<string, unknown>;
+    /**
+     * The Tauri primitives. Omit in a real Tauri webview to auto-resolve from
+     * `@tauri-apps/api` (peer dep) or the ambient `window.__TAURI__`; inject in
+     * tests. Resolution is async, so construction is a factory (below).
+     */
+    readonly tauri?: TauriApi;
+}
+/** The bytes envelope both sides share. */
+export type BytesEnvelope = {
+    readonly $bytes: string;
+};
+/**
+ * The webview-side proxy implementing `SyncClientLike` over the plugin. Every
+ * method is a promise (an IPC round trip); the React `normalizeClient` already
+ * wraps sync and async members uniformly, so the hooks accept it directly.
+ */
+export declare class TauriSyncClient {
+    #private;
+    /** @internal — use {@link createTauriSyncClient}. */
+    constructor(tauri: TauriApi, unlisten: () => void);
+    /** @internal — fan an incoming plugin event out to the local listeners. */
+    __dispatchEvent(event: SyncularEvent): 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>;
+    /** Materialize a `crdt` column's collaborative text — decoded from the
+     * stored (server-merged) Yjs bytes. `name` selects the shared text
+     * (default `"text"`). An absent row / NULL column is the empty document. */
+    crdtText(table: string, rowId: string, column: string, name?: string): Promise<string>;
+    /** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
+     * push the resulting Yjs update (baseVersion-less). Returns the commit id. */
+    crdtInsertText(table: string, rowId: string, column: string, index: number, value: string, name?: string): Promise<string>;
+    /** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
+    crdtDeleteText(table: string, rowId: string, column: string, index: number, len: number, name?: string): Promise<string>;
+    /** Escape hatch: apply an arbitrary Yjs update onto a `crdt` column. */
+    crdtApplyUpdate(table: string, rowId: string, column: string, update: Uint8Array): Promise<string>;
+    subscribe(input: {
+        readonly id: string;
+        readonly table: string;
+        readonly scopes?: Record<string, readonly string[]>;
+        readonly params?: string;
+    }): Promise<void>;
+    unsubscribe(id: string): Promise<void>;
+    setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
+    windowState(base: WindowBase): Promise<WindowState>;
+    sync(): Promise<unknown>;
+    syncUntilIdle(maxRounds?: number): Promise<unknown>;
+    conflicts(): Promise<readonly ConflictRecord[]>;
+    rejections(): Promise<readonly RejectionRecord[]>;
+    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>;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): Promise<void>;
+    /** Detach the event listener; the native core keeps running (host process). */
+    close(): Promise<void>;
+}
+/** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
+export declare class TauriSyncError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Construct the bridge and issue the native `create` (opening/attaching the
+ * file DB on the Rust side per the plugin config). Returns a ready
+ * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
+ * React `<SyncProvider client={…}>`.
+ */
+export declare function createTauriSyncClient(config: TauriSyncClientConfig): Promise<TauriSyncClient>;
+export {};

package/dist/index.js

@@ -0,0 +1,371 @@
+/**
+ * @syncular/tauri — the JS bridge to the native syncular instance running
+ * inside the Tauri process (see `tauri-plugin-syncular`).
+ *
+ * The Tauri host runs a REAL Rust syncular client (file DB + native HTTP+WS
+ * transport). This module is a thin webview-side proxy that implements the SAME
+ * `SyncClientLike` interface the React package normalizes — so the hooks
+ * (`useSyncQuery`, `useMutation`, `usePresence`, …) work UNCHANGED against a
+ * Tauri app. It is the fourth host of one interface, after the direct
+ * `SyncClient`, the worker-leader `SyncClientHandle`, and the multi-tab
+ * follower (ROADMAP.md block 1).
+ *
+ * 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
+ * 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).
+ */
+/** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
+export const SYNCULAR_EVENT = 'syncular://event';
+const PLUGIN = 'plugin:syncular|';
+function isBytesEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.$bytes === 'string');
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+function hexToBytes(hex) {
+    const clean = hex.length % 2 === 0 ? hex : `0${hex}`;
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/** Encode an SQL param for the command JSON (bytes → `{$bytes: hex}`). */
+function encodeParam(value) {
+    if (value instanceof Uint8Array)
+        return { $bytes: bytesToHex(value) };
+    if (typeof value === 'bigint')
+        return Number(value);
+    return value;
+}
+/** Decode one query-result cell back to an `SqlValue` (`{$bytes}` → bytes). */
+function decodeCell(value) {
+    if (isBytesEnvelope(value))
+        return hexToBytes(value.$bytes);
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    // Objects/arrays that are not the bytes envelope round-trip as their JSON
+    // string (SQLite json columns arrive as text already; this is defensive).
+    return JSON.stringify(value);
+}
+function decodeRow(row) {
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        out[key] = decodeCell(value);
+    }
+    return out;
+}
+/** Resolve the Tauri primitives from the ambient environment when not injected. */
+async function resolveTauri(injected) {
+    if (injected !== undefined)
+        return injected;
+    // Prefer the ambient global (present when `withGlobalTauri` is enabled).
+    const ambient = globalThis.__TAURI__;
+    if (ambient?.core?.invoke && ambient.event?.listen) {
+        return {
+            invoke: ambient.core.invoke.bind(ambient.core),
+            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'));
+    return { invoke: core.invoke, listen: event.listen };
+}
+/**
+ * The webview-side proxy implementing `SyncClientLike` over the plugin. Every
+ * method is a promise (an IPC round trip); the React `normalizeClient` already
+ * wraps sync and async members uniformly, so the hooks accept it directly.
+ */
+export class TauriSyncClient {
+    #tauri;
+    #invalidationListeners = new Set();
+    #presenceListeners = new Set();
+    #unlisten;
+    #closed = false;
+    /** @internal — use {@link createTauriSyncClient}. */
+    constructor(tauri, unlisten) {
+        this.#tauri = tauri;
+        this.#unlisten = unlisten;
+    }
+    /** Dispatch a `syncular_command` and unwrap `{result}` / throw on `{error}`. */
+    async #command(method, params) {
+        const reply = await this.#tauri.invoke(`${PLUGIN}syncular_command`, { command: { method, params } });
+        if (reply.error !== undefined) {
+            throw new TauriSyncError(reply.error.code, reply.error.message);
+        }
+        return reply.result;
+    }
+    /** @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),
+                };
+                for (const listener of this.#invalidationListeners) {
+                    try {
+                        listener(payload);
+                    }
+                    catch {
+                        /* a UI listener must never break event dispatch */
+                    }
+                }
+                break;
+            }
+            case 'presence': {
+                const scopeKey = typeof event.scopeKey === 'string' ? event.scopeKey : '';
+                for (const listener of this.#presenceListeners) {
+                    try {
+                        listener(scopeKey);
+                    }
+                    catch {
+                        /* never break dispatch */
+                    }
+                }
+                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.
+                break;
+        }
+    }
+    // -- SyncClientLike --------------------------------------------------------
+    onInvalidate(listener) {
+        this.#invalidationListeners.add(listener);
+        return () => this.#invalidationListeners.delete(listener);
+    }
+    onPresence(listener) {
+        this.#presenceListeners.add(listener);
+        return () => this.#presenceListeners.delete(listener);
+    }
+    async query(sql, params) {
+        const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query`, { sql, params: (params ?? []).map(encodeParam) });
+        if (reply.error !== undefined) {
+            throw new TauriSyncError(reply.error.code, reply.error.message);
+        }
+        const rows = reply.result.rows ?? [];
+        return rows.map((r) => decodeRow(r));
+    }
+    async mutate(mutations) {
+        const result = (await this.#command('mutate', {
+            mutations: mutations.map(encodeMutation),
+        }));
+        return result.clientCommitId;
+    }
+    // -- Native CRDT (SPEC.md §5.10.5; needs the plugin `crdt-yjs` feature) ------
+    /** Materialize a `crdt` column's collaborative text — decoded from the
+     * stored (server-merged) Yjs bytes. `name` selects the shared text
+     * (default `"text"`). An absent row / NULL column is the empty document. */
+    async crdtText(table, rowId, column, name = 'text') {
+        const result = (await this.#command('crdtText', {
+            table,
+            rowId,
+            column,
+            name,
+        }));
+        return result.text;
+    }
+    /** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
+     * push the resulting Yjs update (baseVersion-less). Returns the commit id. */
+    async crdtInsertText(table, rowId, column, index, value, name = 'text') {
+        const result = (await this.#command('crdtInsertText', {
+            table,
+            rowId,
+            column,
+            name,
+            index,
+            value,
+        }));
+        return result.clientCommitId;
+    }
+    /** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
+    async crdtDeleteText(table, rowId, column, index, len, name = 'text') {
+        const result = (await this.#command('crdtDeleteText', {
+            table,
+            rowId,
+            column,
+            name,
+            index,
+            len,
+        }));
+        return result.clientCommitId;
+    }
+    /** Escape hatch: apply an arbitrary Yjs update onto a `crdt` column. */
+    async crdtApplyUpdate(table, rowId, column, update) {
+        const result = (await this.#command('crdtApplyUpdate', {
+            table,
+            rowId,
+            column,
+            update: { $bytes: bytesToHex(update) },
+        }));
+        return result.clientCommitId;
+    }
+    async subscribe(input) {
+        await this.#command('subscribe', {
+            id: input.id,
+            table: input.table,
+            scopes: input.scopes ?? {},
+            ...(input.params !== undefined ? { params: input.params } : {}),
+        });
+    }
+    async unsubscribe(id) {
+        await this.#command('unsubscribe', { id });
+    }
+    async setWindow(base, units) {
+        await this.#command('setWindow', {
+            base: base,
+            units: units,
+        });
+    }
+    async windowState(base) {
+        const result = (await this.#command('windowState', {
+            base: base,
+        }));
+        return { units: result.units };
+    }
+    async sync() {
+        return this.#command('sync', {});
+    }
+    async syncUntilIdle(maxRounds) {
+        return this.#command('syncUntilIdle', {
+            ...(maxRounds !== undefined ? { maxRounds } : {}),
+        });
+    }
+    async conflicts() {
+        const result = (await this.#command('conflicts', {}));
+        return result.conflicts;
+    }
+    async rejections() {
+        const result = (await this.#command('rejections', {}));
+        return result.rejections;
+    }
+    async schemaFloor() {
+        const result = (await this.#command('schemaFloor', {}));
+        return result.floor ?? undefined;
+    }
+    async leaseState() {
+        const result = (await this.#command('leaseState', {}));
+        return result.lease ?? undefined;
+    }
+    async upgrading() {
+        const result = (await this.#command('upgrading', {}));
+        return result.value;
+    }
+    async syncNeeded() {
+        const result = (await this.#command('syncNeeded', {}));
+        return result.value;
+    }
+    async pendingCommits() {
+        const result = (await this.#command('pendingCommitIds', {}));
+        return result.ids;
+    }
+    async presence(scopeKey) {
+        const result = (await this.#command('presence', { scopeKey }));
+        return result.peers;
+    }
+    async setPresence(scopeKey, doc) {
+        await this.#command('setPresence', { scopeKey, doc });
+    }
+    async connectRealtime() {
+        await this.#command('connectRealtime', {});
+    }
+    async disconnectRealtime() {
+        await this.#command('disconnectRealtime', {});
+    }
+    /** Detach the event listener; the native core keeps running (host process). */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#unlisten?.();
+        this.#unlisten = undefined;
+        this.#invalidationListeners.clear();
+        this.#presenceListeners.clear();
+    }
+}
+/** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
+export class TauriSyncError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TauriSyncError';
+        this.code = code;
+    }
+}
+function toStringSet(value) {
+    if (Array.isArray(value)) {
+        return new Set(value.filter((v) => typeof v === 'string'));
+    }
+    return new Set();
+}
+/** 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;
+}
+/**
+ * Construct the bridge and issue the native `create` (opening/attaching the
+ * file DB on the Rust side per the plugin config). Returns a ready
+ * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
+ * React `<SyncProvider client={…}>`.
+ */
+export async function createTauriSyncClient(config) {
+    const tauri = await resolveTauri(config.tauri);
+    // Wire the event stream BEFORE create, so no early invalidate is missed.
+    const clientRef = {
+        client: undefined,
+    };
+    const unlisten = await tauri.listen(SYNCULAR_EVENT, (event) => {
+        clientRef.client?.__dispatchEvent(event.payload);
+    });
+    const client = new TauriSyncClient(tauri, unlisten);
+    clientRef.client = client;
+    // The native side owns the db path (plugin config); the JS side supplies the
+    // schema, clientId, and limits. `dbPath` is injected by the plugin.
+    const reply = await tauri.invoke(`${PLUGIN}syncular_command`, {
+        command: {
+            method: 'create',
+            params: {
+                clientId: config.clientId,
+                schema: config.schema,
+                ...(config.limits !== undefined ? { limits: config.limits } : {}),
+            },
+        },
+    });
+    if (reply.error !== undefined) {
+        unlisten();
+        throw new TauriSyncError(reply.error.code, reply.error.message);
+    }
+    return client;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@syncular/tauri",
+  "version": "0.2.0",
+  "description": "Tauri integration for the Syncular client",
+  "license": "Apache-2.0",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/tauri"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@syncular/client": "0.2.0"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@syncular/react": "0.2.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,552 @@
+/**
+ * @syncular/tauri — the JS bridge to the native syncular instance running
+ * inside the Tauri process (see `tauri-plugin-syncular`).
+ *
+ * The Tauri host runs a REAL Rust syncular client (file DB + native HTTP+WS
+ * transport). This module is a thin webview-side proxy that implements the SAME
+ * `SyncClientLike` interface the React package normalizes — so the hooks
+ * (`useSyncQuery`, `useMutation`, `usePresence`, …) work UNCHANGED against a
+ * Tauri app. It is the fourth host of one interface, after the direct
+ * `SyncClient`, the worker-leader `SyncClientHandle`, and the multi-tab
+ * follower (ROADMAP.md block 1).
+ *
+ * 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
+ * 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).
+ */
+
+// -- 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 {
+  ConflictRecord,
+  InvalidationEvent,
+  InvalidationListener,
+  LeaseState,
+  MutationInput,
+  PresencePeer,
+  RejectionRecord,
+  SchemaFloor,
+  SqlRow,
+  SqlValue,
+  WindowBase,
+  WindowState,
+} from '@syncular/client';
+
+/** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
+interface CommandReply {
+  readonly result?: unknown;
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+/** One event pushed on `syncular://event` (the derived client-observable set). */
+interface SyncularEvent {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** The two Tauri primitives the bridge needs — injectable for tests. */
+export interface TauriApi {
+  invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
+  listen<T>(
+    event: string,
+    handler: (event: { payload: T }) => void,
+  ): Promise<() => void>;
+}
+
+/** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
+export const SYNCULAR_EVENT = 'syncular://event';
+
+const PLUGIN = 'plugin:syncular|';
+
+/** Config for {@link createTauriSyncClient}. */
+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).
+   */
+  readonly clientId: string;
+  /** §4.2 client limits, forwarded to the native `create`. */
+  readonly limits?: Record<string, unknown>;
+  /**
+   * The Tauri primitives. Omit in a real Tauri webview to auto-resolve from
+   * `@tauri-apps/api` (peer dep) or the ambient `window.__TAURI__`; inject in
+   * tests. Resolution is async, so construction is a factory (below).
+   */
+  readonly tauri?: TauriApi;
+}
+
+/** The bytes envelope both sides share. */
+export type BytesEnvelope = { readonly $bytes: string };
+
+function isBytesEnvelope(value: unknown): value is BytesEnvelope {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { $bytes?: unknown }).$bytes === 'string'
+  );
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) {
+    out += b.toString(16).padStart(2, '0');
+  }
+  return out;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.length % 2 === 0 ? hex : `0${hex}`;
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/** 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);
+  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 (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  // Objects/arrays that are not the bytes envelope round-trip as their JSON
+  // string (SQLite json columns arrive as text already; this is defensive).
+  return JSON.stringify(value);
+}
+
+function decodeRow(row: Record<string, unknown>): SqlRow {
+  const out: SqlRow = {};
+  for (const [key, value] of Object.entries(row)) {
+    out[key] = decodeCell(value);
+  }
+  return out;
+}
+
+/** Resolve the Tauri primitives from the ambient environment when not injected. */
+async function resolveTauri(injected: TauriApi | undefined): Promise<TauriApi> {
+  if (injected !== undefined) return injected;
+  // Prefer the ambient global (present when `withGlobalTauri` is enabled).
+  const ambient = (
+    globalThis as {
+      __TAURI__?: {
+        core?: { invoke?: TauriApi['invoke'] };
+        event?: { listen?: TauriApi['listen'] };
+      };
+    }
+  ).__TAURI__;
+  if (ambient?.core?.invoke && ambient.event?.listen) {
+    return {
+      invoke: ambient.core.invoke.bind(ambient.core),
+      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'];
+  };
+  return { invoke: core.invoke, listen: event.listen };
+}
+
+/**
+ * The webview-side proxy implementing `SyncClientLike` over the plugin. Every
+ * method is a promise (an IPC round trip); the React `normalizeClient` already
+ * wraps sync and async members uniformly, so the hooks accept it directly.
+ */
+export class TauriSyncClient {
+  readonly #tauri: TauriApi;
+  readonly #invalidationListeners = new Set<InvalidationListener>();
+  readonly #presenceListeners = new Set<(scopeKey: string) => void>();
+  #unlisten: (() => void) | undefined;
+  #closed = false;
+
+  /** @internal — use {@link createTauriSyncClient}. */
+  constructor(tauri: TauriApi, unlisten: () => void) {
+    this.#tauri = tauri;
+    this.#unlisten = unlisten;
+  }
+
+  /** Dispatch a `syncular_command` and unwrap `{result}` / throw on `{error}`. */
+  async #command(
+    method: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    const reply = await this.#tauri.invoke<CommandReply>(
+      `${PLUGIN}syncular_command`,
+      { command: { method, params } },
+    );
+    if (reply.error !== undefined) {
+      throw new TauriSyncError(reply.error.code, reply.error.message);
+    }
+    return reply.result;
+  }
+
+  /** @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),
+        };
+        for (const listener of this.#invalidationListeners) {
+          try {
+            listener(payload);
+          } catch {
+            /* a UI listener must never break event dispatch */
+          }
+        }
+        break;
+      }
+      case 'presence': {
+        const scopeKey =
+          typeof event.scopeKey === 'string' ? event.scopeKey : '';
+        for (const listener of this.#presenceListeners) {
+          try {
+            listener(scopeKey);
+          } catch {
+            /* never break dispatch */
+          }
+        }
+        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.
+        break;
+    }
+  }
+
+  // -- SyncClientLike --------------------------------------------------------
+
+  onInvalidate(listener: InvalidationListener): () => void {
+    this.#invalidationListeners.add(listener);
+    return () => this.#invalidationListeners.delete(listener);
+  }
+
+  onPresence(listener: (scopeKey: string) => void): () => void {
+    this.#presenceListeners.add(listener);
+    return () => this.#presenceListeners.delete(listener);
+  }
+
+  async query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]> {
+    const reply = await this.#tauri.invoke<CommandReply>(
+      `${PLUGIN}syncular_query`,
+      { sql, params: (params ?? []).map(encodeParam) },
+    );
+    if (reply.error !== undefined) {
+      throw new TauriSyncError(reply.error.code, reply.error.message);
+    }
+    const rows = (reply.result as { rows?: unknown[] }).rows ?? [];
+    return rows.map((r) => decodeRow(r as Record<string, unknown>));
+  }
+
+  async mutate(mutations: readonly MutationInput[]): Promise<string> {
+    const result = (await this.#command('mutate', {
+      mutations: mutations.map(encodeMutation),
+    })) as { clientCommitId: string };
+    return result.clientCommitId;
+  }
+
+  // -- Native CRDT (SPEC.md §5.10.5; needs the plugin `crdt-yjs` feature) ------
+
+  /** Materialize a `crdt` column's collaborative text — decoded from the
+   * stored (server-merged) Yjs bytes. `name` selects the shared text
+   * (default `"text"`). An absent row / NULL column is the empty document. */
+  async crdtText(
+    table: string,
+    rowId: string,
+    column: string,
+    name = 'text',
+  ): Promise<string> {
+    const result = (await this.#command('crdtText', {
+      table,
+      rowId,
+      column,
+      name,
+    })) as { text: string };
+    return result.text;
+  }
+
+  /** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
+   * push the resulting Yjs update (baseVersion-less). Returns the commit id. */
+  async crdtInsertText(
+    table: string,
+    rowId: string,
+    column: string,
+    index: number,
+    value: string,
+    name = 'text',
+  ): Promise<string> {
+    const result = (await this.#command('crdtInsertText', {
+      table,
+      rowId,
+      column,
+      name,
+      index,
+      value,
+    })) as { clientCommitId: string };
+    return result.clientCommitId;
+  }
+
+  /** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
+  async crdtDeleteText(
+    table: string,
+    rowId: string,
+    column: string,
+    index: number,
+    len: number,
+    name = 'text',
+  ): Promise<string> {
+    const result = (await this.#command('crdtDeleteText', {
+      table,
+      rowId,
+      column,
+      name,
+      index,
+      len,
+    })) as { clientCommitId: string };
+    return result.clientCommitId;
+  }
+
+  /** Escape hatch: apply an arbitrary Yjs update onto a `crdt` column. */
+  async crdtApplyUpdate(
+    table: string,
+    rowId: string,
+    column: string,
+    update: Uint8Array,
+  ): Promise<string> {
+    const result = (await this.#command('crdtApplyUpdate', {
+      table,
+      rowId,
+      column,
+      update: { $bytes: bytesToHex(update) },
+    })) as { clientCommitId: string };
+    return result.clientCommitId;
+  }
+
+  async subscribe(input: {
+    readonly id: string;
+    readonly table: string;
+    readonly scopes?: Record<string, readonly string[]>;
+    readonly params?: string;
+  }): Promise<void> {
+    await this.#command('subscribe', {
+      id: input.id,
+      table: input.table,
+      scopes: input.scopes ?? {},
+      ...(input.params !== undefined ? { params: input.params } : {}),
+    });
+  }
+
+  async unsubscribe(id: string): Promise<void> {
+    await this.#command('unsubscribe', { id });
+  }
+
+  async setWindow(base: WindowBase, units: readonly string[]): Promise<void> {
+    await this.#command('setWindow', {
+      base: base as unknown as Record<string, unknown>,
+      units: units as string[],
+    });
+  }
+
+  async windowState(base: WindowBase): Promise<WindowState> {
+    const result = (await this.#command('windowState', {
+      base: base as unknown as Record<string, unknown>,
+    })) as { units: string[] };
+    return { units: result.units };
+  }
+
+  async sync(): Promise<unknown> {
+    return this.#command('sync', {});
+  }
+
+  async syncUntilIdle(maxRounds?: number): Promise<unknown> {
+    return this.#command('syncUntilIdle', {
+      ...(maxRounds !== undefined ? { maxRounds } : {}),
+    });
+  }
+
+  async conflicts(): Promise<readonly ConflictRecord[]> {
+    const result = (await this.#command('conflicts', {})) as {
+      conflicts: ConflictRecord[];
+    };
+    return result.conflicts;
+  }
+
+  async rejections(): Promise<readonly RejectionRecord[]> {
+    const result = (await this.#command('rejections', {})) as {
+      rejections: RejectionRecord[];
+    };
+    return result.rejections;
+  }
+
+  async schemaFloor(): Promise<SchemaFloor | undefined> {
+    const result = (await this.#command('schemaFloor', {})) as {
+      floor?: SchemaFloor;
+    };
+    return result.floor ?? undefined;
+  }
+
+  async leaseState(): Promise<LeaseState | undefined> {
+    const result = (await this.#command('leaseState', {})) as {
+      lease?: LeaseState;
+    };
+    return result.lease ?? undefined;
+  }
+
+  async upgrading(): Promise<boolean> {
+    const result = (await this.#command('upgrading', {})) as { value: boolean };
+    return result.value;
+  }
+
+  async syncNeeded(): Promise<boolean> {
+    const result = (await this.#command('syncNeeded', {})) as {
+      value: boolean;
+    };
+    return result.value;
+  }
+
+  async pendingCommits(): Promise<unknown[]> {
+    const result = (await this.#command('pendingCommitIds', {})) as {
+      ids: string[];
+    };
+    return result.ids;
+  }
+
+  async presence(scopeKey: string): Promise<readonly PresencePeer[]> {
+    const result = (await this.#command('presence', { scopeKey })) as {
+      peers: PresencePeer[];
+    };
+    return result.peers;
+  }
+
+  async setPresence(
+    scopeKey: string,
+    doc: Record<string, unknown> | null,
+  ): Promise<void> {
+    await this.#command('setPresence', { scopeKey, doc });
+  }
+
+  async connectRealtime(): Promise<void> {
+    await this.#command('connectRealtime', {});
+  }
+
+  async disconnectRealtime(): Promise<void> {
+    await this.#command('disconnectRealtime', {});
+  }
+
+  /** Detach the event listener; the native core keeps running (host process). */
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#unlisten?.();
+    this.#unlisten = undefined;
+    this.#invalidationListeners.clear();
+    this.#presenceListeners.clear();
+  }
+}
+
+/** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
+export class TauriSyncError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'TauriSyncError';
+    this.code = code;
+  }
+}
+
+function toStringSet(value: unknown): ReadonlySet<string> {
+  if (Array.isArray(value)) {
+    return new Set(value.filter((v): v is string => typeof v === 'string'));
+  }
+  return new Set<string>();
+}
+
+/** 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;
+}
+
+/**
+ * Construct the bridge and issue the native `create` (opening/attaching the
+ * file DB on the Rust side per the plugin config). Returns a ready
+ * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
+ * React `<SyncProvider client={…}>`.
+ */
+export async function createTauriSyncClient(
+  config: TauriSyncClientConfig,
+): Promise<TauriSyncClient> {
+  const tauri = await resolveTauri(config.tauri);
+
+  // Wire the event stream BEFORE create, so no early invalidate is missed.
+  const clientRef: { client: TauriSyncClient | undefined } = {
+    client: undefined,
+  };
+  const unlisten = await tauri.listen<SyncularEvent>(
+    SYNCULAR_EVENT,
+    (event) => {
+      clientRef.client?.__dispatchEvent(event.payload);
+    },
+  );
+
+  const client = new TauriSyncClient(tauri, unlisten);
+  clientRef.client = client;
+
+  // The native side owns the db path (plugin config); the JS side supplies the
+  // schema, clientId, and limits. `dbPath` is injected by the plugin.
+  const reply = await tauri.invoke<CommandReply>(`${PLUGIN}syncular_command`, {
+    command: {
+      method: 'create',
+      params: {
+        clientId: config.clientId,
+        schema: config.schema,
+        ...(config.limits !== undefined ? { limits: config.limits } : {}),
+      },
+    },
+  });
+  if (reply.error !== undefined) {
+    unlisten();
+    throw new TauriSyncError(reply.error.code, reply.error.message);
+  }
+
+  return client;
+}