@voltro/local-first 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -303,10 +303,20 @@ declare interface IDBTransactionLike {
  *   a `SyncTransport`: a local edit → optimistic merge + queued write; reconnect
  *   → drain to `push`; incoming merged state → local CRDT merge; convergence.
  *   Tested against an in-memory dispatcher that mirrors the server's
- *   authoritative merge. REMAINING (runtime binding, NOT this package): supply
- *   the two transport functions from a running app — `push` from the client's
- *   mutation caller (`useMutation` / `resolveByTag` writing the `crdtText()`
- *   column), `onRemoteState` from the reactive subscription that streams the row.
+ *   authoritative merge.
+ *
+ * DONE — The React binding over that wire.
+ *   `useCrdtText` (./react/useCrdtText) owns the client's LIFECYCLE for one
+ *   `crdtText()` cell: one client per (table,id,column) created and closed with
+ *   the component, re-render on local edit / ack / incoming state, the streamed
+ *   row folded back in, and — the part every consumer would otherwise hand-roll
+ *   wrong — `setText` as a prefix/suffix span diff rather than a
+ *   delete-all/insert-all, which is what silently turns a CRDT column back into
+ *   last-write-wins. What is left of this seam is NOT lifecycle code: it is the
+ *   two app-specific names (`push` → the mutation that writes the column,
+ *   `remote` → the reactive query that streams the row). There is no generated
+ *   per-table CRUD surface to derive those from, so the app supplies them — the
+ *   same shape as `usePresence`'s injected `channel`.
  *
  * DONE — Presence / awareness.
  *   `createPresenceRoom` (./presence/room) + the `usePresence` hook implement
@@ -325,7 +335,7 @@ declare interface IDBTransactionLike {
  *   like any column type). `crdtText()` was already a real column type with an
  *   authoritative server merge on the write path.
  */
-export declare const IMPLEMENTED_SINCE_SEAMS: readonly ["durable-persistence-indexeddb", "sync-transport-syncclient", "presence-room", "localFirst-mixin-discovery"];
+export declare const IMPLEMENTED_SINCE_SEAMS: readonly ["durable-persistence-indexeddb", "sync-transport-syncclient", "sync-transport-react-binding", "presence-room", "localFirst-mixin-discovery"];
 
 export declare type ImplementedSeam = (typeof IMPLEMENTED_SINCE_SEAMS)[number];
 
@@ -478,13 +488,14 @@ export declare interface RemoteCrdtState extends CrdtDocKey {
 }
 
 /**
- * The genuinely REMAINING runtime seams — provisioned infra + the thin app-level
- * binding to it, not un-built framework code:
- *   - a `SyncTransport` bound to a specific running app's mutation/subscription
+ * The genuinely REMAINING runtime seams — provisioned infra + the two app-level
+ * NAMES nothing can derive, not un-built framework code:
+ *   - the mutation tag / query tag `useCrdtText` is pointed at (the lifecycle
+ *     around them ships; see the DONE entry above)
  *   - a `PresenceChannel` bound to a provisioned Redis/NATS broker at scale
  *   - (optional) a wa-sqlite/Turso durable adapter for cross-tab SQL
  */
-export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-binding", "presence-broker-binding", "wasm-sqlite-durable-adapter"];
+export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-tags", "presence-broker-binding", "wasm-sqlite-durable-adapter"];
 
 export declare type RuntimeSeam = (typeof RUNTIME_SEAMS)[number];
 

package/dist/index.js

@@ -1,53 +1,16 @@
-import { a as e, c as t, i as n, n as r, o as i, r as a, s as o, t as s } from "./room-CzWRYppA.js";
-import * as c from "yjs";
-//#region src/crdt/yjsBackend.ts
-var l = "t", u = (e) => c.encodeStateAsUpdate(e), d = (e) => {
-	let t = new c.Doc();
-	return e.length > 0 && c.applyUpdate(t, e), t;
-}, f = (e) => {
-	let t = e.getText(l);
-	return {
-		toString: () => t.toString(),
-		insert: (e, n) => t.insert(e, n),
-		delete: (e, n) => t.delete(e, n),
-		encodeState: () => u(e),
-		applyState: (t) => {
-			t.length > 0 && c.applyUpdate(e, t);
-		}
-	};
-}, p = {
-	name: "yjs",
-	createText: (e) => {
-		let t = new c.Doc();
-		return e !== void 0 && e.length > 0 && t.getText(l).insert(0, e), f(t);
-	},
-	merge: (e, t) => c.mergeUpdates([e, t]),
-	decodeText: (e) => {
-		let t = d(e), n = t.getText(l).toString();
-		return t.destroy(), n;
-	},
-	emptyState: () => u(new c.Doc())
-}, m = p, h = (e, t = m) => {
-	let n = t.createText(e), r = {
-		backend: t.name,
-		toString: () => n.toString(),
-		insert: (e, t) => (n.insert(e, t), r),
-		delete: (e, t) => (n.delete(e, t), r),
-		merge: (e) => (n.applyState(e), r),
-		encode: () => n.encodeState()
-	};
-	return r;
-}, g = (e, t, n = m) => n.merge(e, t), _ = (e, t = m) => t.decodeText(e), v = (e = m) => e.emptyState(), y = (e) => {
+import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, n as c, o as l, p as u, r as d, s as f, t as p, u as m } from "./room-wFNUwEgi.js";
+//#region src/conflict/policy.ts
+var h = (e) => {
 	if (e.writer !== void 0) return `w:${e.writer}`;
 	try {
 		return `v:${JSON.stringify(e.value)}`;
 	} catch {
 		return `v:${String(e.value)}`;
 	}
-}, b = (e, t) => t.updatedAt > e.updatedAt ? t.value : t.updatedAt < e.updatedAt ? e.value : y(t) > y(e) ? t.value : e.value, x = (e) => e === "lastWriteWins" ? b : e, S = (e) => {
+}, g = (e, t) => t.updatedAt > e.updatedAt ? t.value : t.updatedAt < e.updatedAt ? e.value : h(t) > h(e) ? t.value : e.value, _ = (e) => e === "lastWriteWins" ? g : e, v = (e) => {
 	let t = (t, n, r) => {
 		let i = e[t];
-		return (i === void 0 ? b : x(i))(n, r);
+		return (i === void 0 ? g : _(i))(n, r);
 	};
 	return {
 		resolveField: t,
@@ -68,32 +31,32 @@ var l = "t", u = (e) => c.encodeStateAsUpdate(e), d = (e) => {
 			return r;
 		}
 	};
-}, C = (e, t) => `${e}
${t}`, w = () => {
+}, y = (e, t) => `${e}
${t}`, b = () => {
 	let e = /* @__PURE__ */ new Map(), t = [], n = /* @__PURE__ */ new Set(), r = (e) => e.slice();
 	return {
 		kind: "in-memory",
 		loadCrdtState: (t, n) => {
-			let i = e.get(C(t, n));
+			let i = e.get(y(t, n));
 			return Promise.resolve(i === void 0 ? void 0 : r(i));
 		},
-		saveCrdtState: (t, n, i) => (e.set(C(t, n), r(i)), Promise.resolve()),
+		saveCrdtState: (t, n, i) => (e.set(y(t, n), r(i)), Promise.resolve()),
 		loadQueue: () => Promise.resolve(t.map((e) => ({ ...e }))),
 		saveQueue: (e) => (t = e.map((e) => ({ ...e })), Promise.resolve()),
-		pin: (e, t) => (n.add(C(e, t)), Promise.resolve()),
-		isPinned: (e, t) => Promise.resolve(n.has(C(e, t)))
+		pin: (e, t) => (n.add(y(e, t)), Promise.resolve()),
+		isPinned: (e, t) => Promise.resolve(n.has(y(e, t)))
 	};
-}, T = "voltro_local_first", E = "\0queue", D = "\0pin\0", O = (e, t) => `cell\u0000${e}\u0000${t}`, k = (e, t) => `${D}${e}\u0000${t}`, A = (e) => new Promise((t, n) => {
+}, x = "voltro_local_first", S = "\0queue", C = "\0pin\0", w = (e, t) => `cell\u0000${e}\u0000${t}`, T = (e, t) => `${C}${e}\u0000${t}`, E = (e) => new Promise((t, n) => {
 	e.onsuccess = () => t(e.result), e.onerror = () => n(e.error ?? /* @__PURE__ */ Error("IndexedDB request failed"));
-}), j = async (e) => {
+}), D = async (e) => {
 	let t = e?.factory ?? globalThis.indexedDB;
 	if (t === void 0) throw Error("createIndexedDbPersistence: no IndexedDB available. Pass options.factory (e.g. in a non-browser host) or use createInMemoryPersistence().");
 	let n = e?.databaseName ?? "voltro-local-first", r = t.open(n, 1), i = await new Promise((e, t) => {
 		r.onupgradeneeded = () => {
 			let e = r.result;
-			e.objectStoreNames.contains(T) || e.createObjectStore(T);
+			e.objectStoreNames.contains(x) || e.createObjectStore(x);
 		}, r.onsuccess = () => e(r.result), r.onerror = () => t(r.error ?? /* @__PURE__ */ Error("IndexedDB open failed"));
-	}), a = async (e) => A(i.transaction(T, "readonly").objectStore(T).get(e)), o = async (e, t) => {
-		await A(i.transaction(T, "readwrite").objectStore(T).put(t, e));
+	}), a = async (e) => E(i.transaction(x, "readonly").objectStore(x).get(e)), o = async (e, t) => {
+		await E(i.transaction(x, "readwrite").objectStore(x).put(t, e));
 	}, s = (e) => {
 		if (e instanceof Uint8Array) return e.slice();
 		if (e instanceof ArrayBuffer) return new Uint8Array(e.slice(0));
@@ -101,113 +64,33 @@ var l = "t", u = (e) => c.encodeStateAsUpdate(e), d = (e) => {
 	};
 	return {
 		kind: "indexeddb",
-		loadCrdtState: async (e, t) => s(await a(O(e, t))),
+		loadCrdtState: async (e, t) => s(await a(w(e, t))),
 		saveCrdtState: async (e, t, n) => {
-			await o(O(e, t), n.slice());
+			await o(w(e, t), n.slice());
 		},
 		loadQueue: async () => {
-			let e = await a(E);
+			let e = await a(S);
 			return e === void 0 || !Array.isArray(e.writes) ? [] : e.writes.map((e) => ({ ...e }));
 		},
 		saveQueue: async (e) => {
 			let t = { writes: e.map((e) => ({ ...e })) };
-			await o(E, t);
+			await o(S, t);
 		},
 		pin: async (e, t) => {
-			await o(k(e, t), !0);
+			await o(T(e, t), !0);
 		},
-		isPinned: async (e, t) => await a(k(e, t)) === !0
+		isPinned: async (e, t) => await a(T(e, t)) === !0
 	};
-}, M = (e) => e.inFlight === void 0 ? e.pending : [e.inFlight, ...e.pending], N = async (e, n = !0) => {
-	let r = await e.loadQueue(), a = {
-		...i(n),
-		pending: r
+}, O = (e) => e.inFlight === void 0 ? e.pending : [e.inFlight, ...e.pending], k = async (e, t = !0) => {
+	let n = await e.loadQueue(), r = {
+		...f(t),
+		pending: n
 	};
 	return {
-		getState: () => a,
-		dispatch: async (n) => (a = t(a, n), await e.saveQueue(M(a)), a)
-	};
-}, P = (e) => `${e.table}\u0000${e.id}\u0000${e.column}`, F = 0, I = () => {
-	let e = typeof crypto < "u" ? crypto : void 0;
-	return e && typeof e.randomUUID == "function" ? e.randomUUID() : `w_${Date.now().toString(36)}_${F += 1}`;
-}, L = (n) => {
-	let { transport: r, adapter: a } = n, s = n.backend ?? m, c = n.now ?? Date.now, l = n.maxAttempts ?? 5, u = i(n.online ?? !0), d = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Set(), p = () => {
-		for (let e of f) try {
-			e();
-		} catch {}
-	}, h = (e, t) => {
-		let n = P(e), r = d.get(n), i = r === void 0 ? t : g(r, t, s);
-		d.set(n, i), a?.saveCrdtState(e.table, e.id, i).catch(() => void 0);
-	}, _ = () => {
-		if (a === void 0) return;
-		let e = u.inFlight === void 0 ? u.pending : [u.inFlight, ...u.pending];
-		a.saveQueue(e).catch(() => void 0);
-	}, v = !1, y = async () => {
-		if (!v) {
-			v = !0;
-			try {
-				for (; e(u);) {
-					u = t(u, { type: "drain-start" });
-					let e = u.inFlight;
-					if (e === void 0) break;
-					try {
-						await r.push(e), u = t(u, {
-							type: "ack",
-							id: e.id
-						}), _(), p();
-					} catch (n) {
-						if (u = t(u, {
-							type: "fail",
-							id: e.id,
-							error: n instanceof Error ? n.message : String(n)
-						}), _(), p(), e.attempts + 1 >= l) break;
-					}
-				}
-			} finally {
-				v = !1;
-			}
-		}
-	}, b = r.onRemoteState((e) => {
-		h(e, e.state), p();
-	});
-	return {
-		enqueue: (e) => {
-			h(e, e.update);
-			let n = {
-				id: I(),
-				payload: e,
-				enqueuedAt: c(),
-				attempts: 0
-			};
-			u = t(u, {
-				type: "enqueue",
-				write: n
-			}), _(), p(), y();
-		},
-		setOnline: (e) => {
-			u = t(u, e ? { type: "online" } : { type: "offline" }), _(), p(), e && y();
-		},
-		queueState: () => u,
-		outstanding: () => o(u),
-		getState: (e) => {
-			let t = d.get(P(e));
-			return t === void 0 ? void 0 : t.slice();
-		},
-		getText: (e) => {
-			let t = d.get(P(e));
-			return t === void 0 ? "" : s.decodeText(t);
-		},
-		subscribe: (e) => (f.add(e), () => {
-			f.delete(e);
-		}),
-		flush: async () => {
-			await y();
-		},
-		close: () => {
-			b(), f.clear();
-		}
+		getState: () => r,
+		dispatch: async (t) => (r = o(r, t), await e.saveQueue(O(r)), r)
 	};
-}, R = () => ({ rooms: /* @__PURE__ */ new Map() }), z = (e = R()) => {
+}, A = () => ({ rooms: /* @__PURE__ */ new Map() }), j = (e = A()) => {
 	let t = /* @__PURE__ */ new Set(), n = (t) => {
 		let n = e.rooms.get(t);
 		return n === void 0 && (n = /* @__PURE__ */ new Set(), e.rooms.set(t, n)), n;
@@ -229,15 +112,16 @@ var l = "t", u = (e) => c.encodeStateAsUpdate(e), d = (e) => {
 			};
 		}
 	};
-}, B = [
+}, M = [
 	"durable-persistence-indexeddb",
 	"sync-transport-syncclient",
+	"sync-transport-react-binding",
 	"presence-room",
 	"localFirst-mixin-discovery"
-], V = [
-	"sync-transport-app-binding",
+], N = [
+	"sync-transport-app-tags",
 	"presence-broker-binding",
 	"wasm-sqlite-durable-adapter"
 ];
 //#endregion
-export { B as IMPLEMENTED_SINCE_SEAMS, V as RUNTIME_SEAMS, e as canDrain, S as conflictPolicy, r as connectionReducer, h as crdtText, w as createInMemoryPersistence, R as createInMemoryPresenceBus, z as createInMemoryPresenceChannel, j as createIndexedDbPersistence, s as createPresenceRoom, L as createSyncClient, _ as decodeCrdtText, m as defaultCrdtBackend, a as deriveSyncStatus, v as emptyCrdtState, n as initialConnection, i as initialSyncQueue, b as lastWriteWins, N as loadPersistedSyncQueue, g as mergeCrdtStates, o as outstandingCount, t as syncQueueReducer, p as yjsBackend };
+export { M as IMPLEMENTED_SINCE_SEAMS, N as RUNTIME_SEAMS, l as canDrain, v as conflictPolicy, d as connectionReducer, m as crdtText, b as createInMemoryPersistence, A as createInMemoryPresenceBus, j as createInMemoryPresenceChannel, D as createIndexedDbPersistence, p as createPresenceRoom, c as createSyncClient, n as decodeCrdtText, r as defaultCrdtBackend, a as deriveSyncStatus, u as emptyCrdtState, e as initialConnection, f as initialSyncQueue, g as lastWriteWins, k as loadPersistedSyncQueue, s as mergeCrdtStates, t as outstandingCount, o as syncQueueReducer, i as yjsBackend };

package/dist/react.d.ts

@@ -6,6 +6,128 @@ declare interface ConnectionState {
     readonly attempt: number;
 }
 
+/**
+ * A CRDT implementation. One per library. The default is {@link yjsBackend}.
+ *
+ * `merge` and `decodeText` are STATELESS with respect to any live handle: they
+ * operate purely on encoded bytes, which is what lets the sync layer and tests
+ * converge two states without holding a document open.
+ */
+declare interface CrdtBackend {
+    /** Identifies the library, e.g. `"yjs"`. Surfaced for diagnostics/telemetry. */
+    readonly name: string;
+    /** Create a fresh text buffer, optionally seeded with `initial`. */
+    createText: (initial?: string) => CrdtTextHandle;
+    /**
+     * Merge two encoded states into one converged encoded state.
+     *
+     * The core primitive. MUST be:
+     *  - commutative up to convergence: `decodeText(merge(a,b)) === decodeText(merge(b,a))`
+     *  - idempotent: `decodeText(merge(m,a)) === decodeText(m)` when `m` already contains `a`
+     *  - an identity over the empty state: `merge(empty, a)` decodes to `a`'s text
+     */
+    merge: (a: CrdtState, b: CrdtState) => CrdtState;
+    /** The plain-string view of an encoded state. */
+    decodeText: (state: CrdtState) => string;
+    /** The encoded state of an empty document — the merge identity element. */
+    emptyState: () => CrdtState;
+}
+
+/** Identifies one CRDT-managed cell: a `crdtText()` COLUMN of one ROW of one TABLE. */
+declare interface CrdtDocKey {
+    readonly table: string;
+    readonly id: string;
+    readonly column: string;
+}
+
+/**
+ * One local edit, as {@link UseCrdtTextOptions.push} receives it: the cell it
+ * belongs to, the encoded update to write, and how many times delivering it has
+ * already failed.
+ *
+ * `attempts` is carried because the sync client deliberately has no built-in
+ * backoff delay — spacing or jittering a retry is the transport's lever, and it
+ * cannot make that decision without knowing which attempt this is.
+ */
+export declare interface CrdtPush extends CrdtDocKey {
+    /** The encoded CRDT state to write into the column. */
+    readonly update: CrdtState;
+    /** Failed delivery attempts before this one. `0` on the first try. */
+    readonly attempts: number;
+}
+
+/**
+ * An encoded CRDT state or delta, as opaque bytes. Produced by
+ * {@link CrdtBackend.encodeState} / {@link CrdtTextHandle.encodeState},
+ * consumed by {@link CrdtBackend.merge} and {@link CrdtBackend.decodeText}.
+ *
+ * It is opaque ON PURPOSE: the shape is the backend's business. Yjs emits a
+ * v1 update blob; Loro would emit its own. Consumers only ever move these
+ * bytes around and hand them back.
+ */
+declare type CrdtState = Uint8Array;
+
+/**
+ * The minimal single-span edit that turns `before` into `after`: the common
+ * prefix and the common suffix are kept, and everything between them is
+ * replaced.
+ *
+ * Pure and exported because it is the load-bearing half of `setText` — a naive
+ * "delete everything, insert the new string" makes every concurrent edit lose,
+ * which is the failure a CRDT is chosen to prevent, and it fails silently
+ * (the text is right on the peer that typed last).
+ *
+ * Returns `null` when the strings are equal.
+ */
+export declare const crdtTextEdit: (before: string, after: string) => {
+    readonly index: number;
+    readonly deleteLength: number;
+    readonly insert: string;
+} | null;
+
+/**
+ * A live, mutable CRDT text buffer. Edits are local until you
+ * {@link CrdtTextHandle.encodeState | encode} them for transport/merge.
+ */
+declare interface CrdtTextHandle {
+    /** The current text as a plain string — the view a UI renders. */
+    toString: () => string;
+    /** Insert `text` at UTF-16 code-unit `index`. */
+    insert: (index: number, text: string) => void;
+    /** Delete `length` code units starting at `index`. */
+    delete: (index: number, length: number) => void;
+    /** This buffer's full state, encoded for transport or merge. */
+    encodeState: () => CrdtState;
+    /**
+     * Fold another buffer's encoded state into this one. Concurrent edits
+     * converge — this is the CRDT property, applied in place.
+     */
+    applyState: (state: CrdtState) => void;
+}
+
+/**
+ * Durable local storage for a local-first client. Every method is async because
+ * the real backings (WASM SQLite, Turso, IndexedDB) are — the in-memory impl
+ * resolves immediately but keeps the same shape so tests exercise the real
+ * contract, not a synchronous shortcut.
+ */
+declare interface PersistenceAdapter {
+    /** Identifies the backing, e.g. `"in-memory"` / `"wa-sqlite"`. Diagnostics. */
+    readonly kind: string;
+    /** The stored CRDT state for a record, or `undefined` if none is persisted. */
+    loadCrdtState: (table: string, id: string) => Promise<CrdtState | undefined>;
+    /** Persist a record's CRDT state, replacing any prior value. */
+    saveCrdtState: (table: string, id: string, state: CrdtState) => Promise<void>;
+    /** The persisted offline write queue (oldest first). Empty when none saved. */
+    loadQueue: () => Promise<readonly QueuedWrite[]>;
+    /** Persist the entire offline write queue, replacing the prior snapshot. */
+    saveQueue: (writes: readonly QueuedWrite[]) => Promise<void>;
+    /** Mark a record as never-evict (the plan's "pinned" records). */
+    pin: (table: string, id: string) => Promise<void>;
+    /** Whether a record is pinned. */
+    isPinned: (table: string, id: string) => Promise<boolean>;
+}
+
 /**
  * A dumb ephemeral pub/sub channel. Publish a string payload to a room;
  * subscribe to a room and get every payload (from other peers) back.
@@ -77,6 +199,83 @@ export declare interface UseConnectionStatus {
  */
 export declare const useConnectionStatus: (outstanding?: number) => UseConnectionStatus;
 
+export declare interface UseCrdtText {
+    /** The merged text — local edits and every peer's, converged. */
+    readonly text: string;
+    /** Insert at a UTF-16 code-unit index. */
+    readonly insert: (index: number, text: string) => void;
+    /** Delete `length` code units at `index`. */
+    readonly delete: (index: number, length: number) => void;
+    /**
+     * Replace the whole text — the shape a `<textarea>`'s `onChange` hands you.
+     * Diffed to the minimal single-span edit, so a concurrent edit elsewhere in
+     * the document is not erased.
+     */
+    readonly setText: (next: string) => void;
+    /** The encoded merged state, or `undefined` before anything has been folded. */
+    readonly state: CrdtState | undefined;
+    /** Writes not yet acknowledged. `0` means every local edit has landed. */
+    readonly outstanding: number;
+    /** `outstanding === 0`. */
+    readonly synced: boolean;
+    /** Report reachability. Going online drains the queue. */
+    readonly setOnline: (online: boolean) => void;
+}
+
+/**
+ * A collaborative text field bound to one `crdtText()` cell.
+ *
+ * ```tsx
+ * const row = useSubscription('app', 'documents.byId', { id })
+ * const save = useMutation('app', 'documents.setBody')
+ * const body = useCrdtText({
+ *   cell: { table: 'documents', id, column: 'body' },
+ *   remote: row.data?.body ?? null,
+ *   push: (w) => save.mutate({ id: w.id, body: w.update }),
+ * })
+ *
+ * <textarea value={body.text} onChange={(e) => body.setText(e.target.value)} />
+ * ```
+ */
+export declare const useCrdtText: (options: UseCrdtTextOptions) => UseCrdtText;
+
+export declare interface UseCrdtTextOptions {
+    /** The cell: table + row id + the `crdtText()` column. */
+    readonly cell: CrdtDocKey;
+    /**
+     * The authoritative state as the app currently sees it — the column's value
+     * from the reactive query streaming this row.
+     *
+     * `null`/`undefined` means "not loaded yet" and is folded as nothing, NOT as
+     * an empty document: treating a loading row as empty would make the first
+     * keystroke race the load and could push a state that erases the stored text.
+     */
+    readonly remote?: CrdtState | null | undefined;
+    /**
+     * Deliver a local edit to the server. Bind it to the mutation that writes the
+     * `crdtText()` column; the server folds it into the stored state
+     * authoritatively, so this never has to read-modify-write.
+     *
+     * REJECT to trigger the queue's retry — a resolved promise is an ack.
+     */
+    readonly push: (write: CrdtPush) => Promise<unknown>;
+    /**
+     * Durable local storage. Omit for an ephemeral (in-memory) client.
+     *
+     * Must be a STABLE reference — it is a construction option, so a new object
+     * each render rebuilds the sync client and drops the queue. Build it once
+     * (`await createIndexedDbPersistence(…)`) and hold it in state or a module
+     * constant. Same for `backend`, `online` and `maxAttempts`.
+     */
+    readonly adapter?: PersistenceAdapter;
+    /** CRDT backend for the local optimistic merge. Defaults to Yjs. */
+    readonly backend?: CrdtBackend;
+    /** Seed the connection belief (default `true`). */
+    readonly online?: boolean;
+    /** Stop re-driving a write after this many failed attempts. Default 5. */
+    readonly maxAttempts?: number;
+}
+
 export declare interface UsePresence<TPresence> {
     /** This peer's current presence. */
     readonly presence: TPresence;