@voltro/local-first 0.52.0 → 0.54.0

package/dist/index.js

@@ -1,16 +1,16 @@
-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";
+import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./room-24dGMM80.js";
 //#region src/conflict/policy.ts
-var h = (e) => {
+var g = (e) => {
 	if (e.writer !== void 0) return `w:${e.writer}`;
 	try {
 		return `v:${JSON.stringify(e.value)}`;
 	} catch {
 		return `v:${String(e.value)}`;
 	}
-}, 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) => {
+}, _ = (e, t) => t.updatedAt > e.updatedAt ? t.value : t.updatedAt < e.updatedAt ? e.value : g(t) > g(e) ? t.value : e.value, v = (e) => e === "lastWriteWins" ? _ : e, y = (e) => {
 	let t = (t, n, r) => {
 		let i = e[t];
-		return (i === void 0 ? g : _(i))(n, r);
+		return (i === void 0 ? _ : v(i))(n, r);
 	};
 	return {
 		resolveField: t,
@@ -31,32 +31,32 @@ var h = (e) => {
 			return r;
 		}
 	};
-}, y = (e, t) => `${e}
${t}`, b = () => {
+}, b = (e, t) => `${e}\u0001${t}`, x = () => {
 	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(y(t, n));
+			let i = e.get(b(t, n));
 			return Promise.resolve(i === void 0 ? void 0 : r(i));
 		},
-		saveCrdtState: (t, n, i) => (e.set(y(t, n), r(i)), Promise.resolve()),
+		saveCrdtState: (t, n, i) => (e.set(b(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(y(e, t)), Promise.resolve()),
-		isPinned: (e, t) => Promise.resolve(n.has(y(e, t)))
+		pin: (e, t) => (n.add(b(e, t)), Promise.resolve()),
+		isPinned: (e, t) => Promise.resolve(n.has(b(e, t)))
 	};
-}, 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) => {
+}, S = "voltro_local_first", C = "\0queue", w = "\0pin\0", T = (e, t) => `cell\u0000${e}\u0000${t}`, E = (e, t) => `${w}${e}\u0000${t}`, D = (e) => new Promise((t, n) => {
 	e.onsuccess = () => t(e.result), e.onerror = () => n(e.error ?? /* @__PURE__ */ Error("IndexedDB request failed"));
-}), D = async (e) => {
+}), O = 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(x) || e.createObjectStore(x);
+			e.objectStoreNames.contains(S) || e.createObjectStore(S);
 		}, r.onsuccess = () => e(r.result), r.onerror = () => t(r.error ?? /* @__PURE__ */ Error("IndexedDB open failed"));
-	}), 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));
+	}), a = async (e) => D(i.transaction(S, "readonly").objectStore(S).get(e)), o = async (e, t) => {
+		await D(i.transaction(S, "readwrite").objectStore(S).put(t, e));
 	}, s = (e) => {
 		if (e instanceof Uint8Array) return e.slice();
 		if (e instanceof ArrayBuffer) return new Uint8Array(e.slice(0));
@@ -64,33 +64,198 @@ var h = (e) => {
 	};
 	return {
 		kind: "indexeddb",
-		loadCrdtState: async (e, t) => s(await a(w(e, t))),
+		loadCrdtState: async (e, t) => s(await a(T(e, t))),
 		saveCrdtState: async (e, t, n) => {
-			await o(w(e, t), n.slice());
+			await o(T(e, t), n.slice());
 		},
 		loadQueue: async () => {
-			let e = await a(S);
+			let e = await a(C);
 			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(S, t);
+			await o(C, t);
 		},
 		pin: async (e, t) => {
-			await o(T(e, t), !0);
+			await o(E(e, t), !0);
 		},
-		isPinned: async (e, t) => await a(T(e, t)) === !0
+		isPinned: async (e, t) => await a(E(e, t)) === !0
 	};
-}, O = (e) => e.inFlight === void 0 ? e.pending : [e.inFlight, ...e.pending], k = async (e, t = !0) => {
+}, k = (e) => e.inFlight === void 0 ? e.pending : [e.inFlight, ...e.pending], A = async (e, t = !0) => {
 	let n = await e.loadQueue(), r = {
-		...f(t),
+		...p(t),
 		pending: n
 	};
 	return {
 		getState: () => r,
-		dispatch: async (t) => (r = o(r, t), await e.saveQueue(O(r)), r)
+		dispatch: async (t) => (r = s(r, t), await e.saveQueue(k(r)), r)
 	};
-}, A = () => ({ rooms: /* @__PURE__ */ new Map() }), j = (e = A()) => {
+}, j = (e) => {
+	let t = e;
+	return typeof t == "object" && !!t && typeof t.id == "string" && typeof t.tag == "string" && (t.status === "pending" || t.status === "sent" || t.status === "failed" || t.status === "conflict");
+}, M = (e, t = Date.now) => ({
+	load: async () => (await e.loadQueue()).map((e) => e.payload).filter(j),
+	save: async (n) => {
+		let r = n.map((e) => ({
+			id: e.id,
+			payload: e,
+			enqueuedAt: t(),
+			attempts: e.attempts
+		}));
+		await e.saveQueue(r);
+	}
+}), N = () => {
+	let e = /* @__PURE__ */ new Map();
+	return {
+		kind: "in-memory",
+		get: (t) => Promise.resolve(e.get(t)),
+		put: (t, n) => (e.set(t, n), Promise.resolve()),
+		del: (t) => (e.delete(t), Promise.resolve()),
+		keysWithPrefix: (t) => Promise.resolve([...e.keys()].filter((e) => e.startsWith(t)))
+	};
+}, P = (e) => new Promise((t, n) => {
+	e.onsuccess = () => t(e.result), e.onerror = () => n(e.error ?? /* @__PURE__ */ Error("IndexedDB request failed"));
+}), F = "kv", I = async (e) => {
+	let t = e?.factory ?? globalThis.indexedDB;
+	if (t === void 0) throw Error("createIndexedDbKv: no IndexedDB available. Pass options.factory or use createInMemoryKv().");
+	let n = t.open(e?.databaseName ?? "voltro-local-first-kv", 1), r = await new Promise((e, t) => {
+		n.onupgradeneeded = () => {
+			n.result.objectStoreNames.contains(F) || n.result.createObjectStore(F);
+		}, n.onsuccess = () => e(n.result), n.onerror = () => t(n.error ?? /* @__PURE__ */ Error("IndexedDB open failed"));
+	}), i = (e) => r.transaction(F, e).objectStore(F);
+	return {
+		kind: "indexeddb",
+		get: (e) => P(i("readonly").get(e)),
+		put: async (e, t) => {
+			await P(i("readwrite").put(t, e));
+		},
+		del: async (e) => {
+			await P(i("readwrite").delete(e));
+		},
+		keysWithPrefix: async (e) => {
+			let t = globalThis.IDBKeyRange;
+			return t === void 0 ? (await P(i("readonly").getAllKeys())).filter((t) => t.startsWith(e)) : await P(i("readonly").getAllKeys(t.bound(e, `${e}\uffff`)));
+		}
+	};
+}, L = async (e) => {
+	try {
+		return {
+			kv: await I(e),
+			durability: "durable"
+		};
+	} catch {
+		return {
+			kv: N(),
+			durability: "memory"
+		};
+	}
+}, R = "mirror", z = "\0", B = (e) => `${R}${z}${e.subjectId}${z}${e.tenantId}${z}`, V = (e, t) => `${B(e)}q${z}${t}`, H = (e, t) => {
+	if (t.length === 0) return e;
+	let n = (e) => {
+		if (typeof e != "object" || !e || Array.isArray(e)) return e;
+		let n = {};
+		for (let [r, i] of Object.entries(e)) t.includes(r) || (n[r] = i);
+		return n;
+	};
+	return Array.isArray(e) ? e.map(n) : n(e);
+}, U = (e) => {
+	try {
+		return JSON.stringify(e)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}, W = (e, t, n = {}, r = Date.now) => ({
+	partition: t,
+	save: async (i, a) => {
+		let o = n.encryptedColumnsOf?.(a.tag) ?? [], s = a.fingerprint, c = {
+			tag: a.tag,
+			data: H(a.data, o),
+			revision: a.revision,
+			savedAt: r(),
+			...s === void 0 ? {} : { fingerprint: s }
+		};
+		await e.put(V(t, i), c);
+	},
+	load: async (n) => {
+		let r = await e.get(V(t, n));
+		if (typeof r != "object" || !r) return;
+		let i = r;
+		return typeof i.revision == "number" && typeof i.tag == "string" ? i : void 0;
+	},
+	purge: async () => {
+		let n = await e.keysWithPrefix(B(t));
+		for (let t of n) await e.del(t);
+	},
+	enforceBudget: async (n) => {
+		let r = await e.keysWithPrefix(B(t)), i = [];
+		for (let t of r) {
+			let n = await e.get(t);
+			i.push({
+				key: t,
+				savedAt: n?.savedAt ?? 0,
+				bytes: U(n)
+			});
+		}
+		let a = i.reduce((e, t) => e + t.bytes, 0), o = [];
+		i.sort((e, t) => e.savedAt - t.savedAt);
+		for (let t of i) {
+			if (a <= n) break;
+			await e.del(t.key), a -= t.bytes, o.push(t.key);
+		}
+		return o;
+	}
+}), G = (e, t) => {
+	let n = (e) => {
+		let n = t.tags[e];
+		if (n !== void 0) return t.metadata?.[n]?.encryptedColumns;
+	};
+	return {
+		load: async (n) => {
+			let r = await e.load(n);
+			if (r === void 0 || t.tags[r.tag] === void 0) return;
+			let i = r.fingerprint;
+			if (t.schemaFingerprint === void 0 || i === t.schemaFingerprint) return {
+				data: r.data,
+				revision: r.revision
+			};
+		},
+		save: async (r, i) => {
+			if (i.tag === void 0 || t.tags[i.tag] === void 0) return;
+			let a = n(i.tag) ?? [], o = a.length === 0 ? i.data : K(i.data, a);
+			await e.save(r, {
+				tag: i.tag,
+				data: o,
+				revision: i.revision,
+				...t.schemaFingerprint === void 0 ? {} : { fingerprint: t.schemaFingerprint }
+			});
+		}
+	};
+}, K = (e, t) => {
+	let n = (e) => {
+		if (typeof e != "object" || !e || Array.isArray(e)) return e;
+		let n = {};
+		for (let [r, i] of Object.entries(e)) t.includes(r) || (n[r] = i);
+		return n;
+	};
+	return Array.isArray(e) ? e.map(n) : n(e);
+}, q = (e, t, n, r = {}) => {
+	let i = new Set(r.crdtColumns ?? []), o = r.backend ?? d, s = e.resolveRecord(Object.fromEntries(Object.entries(t).filter(([e]) => !i.has(e))), Object.fromEntries(Object.entries(n).filter(([e]) => !i.has(e))));
+	for (let e of i) {
+		let r = t[e]?.value, i = n[e]?.value;
+		r !== void 0 && i !== void 0 ? s[e] = a(r, i, o) : r === void 0 ? i !== void 0 && (s[e] = i) : s[e] = r;
+	}
+	return s;
+}, J = async (e, t) => {
+	let n = e.locks === null ? void 0 : e.locks ?? globalThis.navigator?.locks;
+	if (n === void 0) return await t(), "no-locks";
+	let r = "held-elsewhere";
+	return await n.request(`voltro:outbox:${e.name}`, {
+		mode: "exclusive",
+		ifAvailable: !0
+	}, async (e) => {
+		e !== null && (await t(), r = "drained");
+	}), r;
+}, Y = () => ({ rooms: /* @__PURE__ */ new Map() }), X = (e = Y()) => {
 	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;
@@ -112,16 +277,12 @@ var h = (e) => {
 			};
 		}
 	};
-}, M = [
+}, Z = [
 	"durable-persistence-indexeddb",
 	"sync-transport-syncclient",
 	"sync-transport-react-binding",
 	"presence-room",
 	"localFirst-mixin-discovery"
-], N = [
-	"sync-transport-app-tags",
-	"presence-broker-binding",
-	"wasm-sqlite-durable-adapter"
-];
+], Q = ["sync-transport-app-tags"];
 //#endregion
-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 };
+export { Z as IMPLEMENTED_SINCE_SEAMS, Q as RUNTIME_SEAMS, u as canDrain, y as conflictPolicy, f as connectionReducer, h as crdtMergeCell, n as crdtText, L as createDurableKv, N as createInMemoryKv, x as createInMemoryPersistence, Y as createInMemoryPresenceBus, X as createInMemoryPresenceChannel, I as createIndexedDbKv, O as createIndexedDbPersistence, m as createPresenceRoom, W as createQueryMirror, G as createSubscriptionMirrorBinding, l as createSyncClient, r as decodeCrdtText, d as defaultCrdtBackend, o as deriveSyncStatus, c as emptyCrdtState, e as initialConnection, p as initialSyncQueue, _ as lastWriteWins, A as loadPersistedSyncQueue, a as mergeCrdtStates, M as outboxPersistence, t as outstandingCount, q as resolveWithPolicy, s as syncQueueReducer, J as withDrainLock, i as yjsBackend };

package/dist/react.d.ts

@@ -6,18 +6,29 @@ 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;
+    /** Create a whole-document handle, optionally seeded from encoded state. */
+    createDoc: (initial?: CrdtState) => CrdtDocHandle;
+    /**
+     * Re-encode a state through a live document so the backend garbage-collects
+     * what it can (Yjs: `mergeUpdates` never GCs tombstones, so a hot document's
+     * blob grows monotonically without this). Loses UPDATE HISTORY by design —
+     * a version-history feature must snapshot BEFORE compacting.
+     */
+    compact: (state: CrdtState) => CrdtState;
+    /**
+     * HARD compaction for a text state: re-create the document from its
+     * MATERIALISED text, dropping all history, tombstones and client ids. The
+     * result is minimal — and a NEW EPOCH: it does not merge with updates from
+     * the old lineage, so the server treats a rebase as a fresh snapshot for
+     * every subscriber (which the subscription lane already handles as a
+     * reset). Use when `compact` no longer bounds a hot document.
+     */
+    rebaseText: (state: CrdtState) => CrdtState;
     /**
      * Merge two encoded states into one converged encoded state.
      *
@@ -33,6 +44,70 @@ declare interface CrdtBackend {
     emptyState: () => CrdtState;
 }
 
+/**
+ * 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.
+ */
+/**
+ * A live, mutable CRDT DOCUMENT — the whole-doc generalisation `crdtDoc()`
+ * stores (rich text, maps, arrays; whatever the backend's document model
+ * holds). `crdtText()` remains the single-field specialisation over the same
+ * backend.
+ */
+declare interface CrdtDocHandle {
+    /**
+     * The underlying library document (a `Y.Doc` for the yjs backend), typed
+     * opaquely: an EDITOR BINDING needs the real object (Tiptap's Collaboration
+     * extension takes a Y.Doc), while every sync-layer consumer only moves
+     * encoded bytes and must never reach in. Cast at the binding, nowhere else.
+     */
+    readonly raw: unknown;
+    /** Full state, encoded for transport or merge. */
+    encodeState: () => CrdtState;
+    /** This doc's state VECTOR — the compact "what I have" summary a peer
+     *  diffs against. */
+    stateVector: () => Uint8Array;
+    /**
+     * Encode only what a peer holding `sinceVector` is missing — the
+     * INCREMENTAL update lane. A 1-character edit against a 100 KB doc encodes
+     * to a few dozen bytes, not the full state.
+     */
+    encodeUpdateSince: (sinceVector: Uint8Array) => CrdtState;
+    /** Fold an encoded state or incremental update into this doc, in place. */
+    applyState: (state: CrdtState) => void;
+    /**
+     * Subscribe to update blobs this doc produces. Returns the unsubscribe.
+     *
+     * `local` distinguishes an edit made HERE from one produced by folding a
+     * remote state through `applyState`, and it is the difference between a
+     * working push loop and an echo: without it, applying a peer's update fires
+     * this handler, the app pushes it back, and every client re-broadcasts what
+     * it just received. Measured with three tabs open: one keystroke produced
+     * three server writes instead of one. It converges — the merge is
+     * idempotent — but the amplification scales with the session.
+     *
+     * It had to come from the BACKEND rather than an `applying` flag around
+     * `applyState` in app code: that flag is only correct while the backend emits
+     * synchronously, which `CrdtBackend` deliberately does not promise ("the
+     * backend decision lives behind our abstraction so it can change").
+     */
+    onUpdate: (handler: (update: CrdtState, meta: {
+        readonly local: boolean;
+    }) => void) => () => void;
+    /**
+     * Encode a stable ANCHOR at `index` of the named text field — a position
+     * that survives concurrent edits (the primitive an inline-comment UI pins
+     * threads with; the UI itself is the comments plugin's business).
+     */
+    encodeAnchor: (field: string, index: number) => Uint8Array;
+    /** Resolve an anchor back to its current index, or `undefined` when the
+     *  anchored region was deleted. */
+    resolveAnchor: (encoded: Uint8Array) => number | undefined;
+}
+
 /** Identifies one CRDT-managed cell: a `crdtText()` COLUMN of one ROW of one TABLE. */
 declare interface CrdtDocKey {
     readonly table: string;
@@ -41,9 +116,9 @@ declare interface CrdtDocKey {
 }
 
 /**
- * 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.
+ * One local edit, as a hook's `push` option 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
@@ -199,6 +274,95 @@ export declare interface UseConnectionStatus {
  */
 export declare const useConnectionStatus: (outstanding?: number) => UseConnectionStatus;
 
+export declare interface UseCrdtDoc {
+    /**
+     * The live document — pass it straight to `useCrdtEditor({ doc })`.
+     *
+     * `null` until the mount effect has run. That is not a papercut to design
+     * away: constructing it during render is what made the editor crash a
+     * prerender and leak an instance under StrictMode. Render the editor in a
+     * child component so its `useCrdtEditor` call is not conditional:
+     * `{doc.doc !== null ? <Editor doc={doc.doc} /> : null}`.
+     *
+     * Its encoded state is one call away (`doc.encodeState()`), which is why
+     * this hook exposes no separate `state` field — there would be two answers
+     * to one question.
+     */
+    readonly doc: CrdtDocHandle | null;
+    /**
+     * `true` once an authoritative state has been folded in. Distinguishes an
+     * EMPTY document from one that has not arrived yet — the same distinction
+     * `remote: null` makes on the way in, surfaced so a UI can show a skeleton
+     * instead of an empty editor a user might start typing into.
+     */
+    readonly loaded: boolean;
+    /** 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 rich-text document bound to one `crdtDoc()` cell.
+ *
+ * ```tsx
+ * const row = useSubscription('app', 'documents.byId', { id })
+ * const save = useMutation('app', 'documents.setBody')
+ * const shared = useCrdtDoc({
+ *   cell: { table: 'documents', id, column: 'body' },
+ *   remote: row.data?.body ?? null,
+ *   push: (w) => save.mutate({ id: w.id, update: w.update }),
+ * })
+ *
+ * // In a CHILD component, so `useCrdtEditor` is never called conditionally:
+ * const editor = useCrdtEditor({ doc })
+ * return <EditorContent editor={editor} />
+ * ```
+ */
+export declare const useCrdtDoc: (options: UseCrdtDocOptions) => UseCrdtDoc;
+
+export declare interface UseCrdtDocOptions {
+    /** The cell: table + row id + the `crdtDoc()` 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 let the first
+     * keystroke race the load and push a state that erases the stored document.
+     */
+    readonly remote?: CrdtState | null | undefined;
+    /**
+     * Deliver a local edit to the server. Bind it to the mutation that writes the
+     * `crdtDoc()` column; the server folds it into the stored state
+     * authoritatively, so this never has to read-modify-write.
+     *
+     * What it receives is an INCREMENTAL Yjs update, not the full document — a
+     * one-character edit in a 100 KB document is a few dozen bytes.
+     *
+     * 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 the document, dropping 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 UseCrdtText {
     /** The merged text — local edits and every peer's, converged. */
     readonly text: string;