@voltro/local-first 0.53.0 → 0.55.0

package/dist/index.d.ts

@@ -113,7 +113,7 @@ export declare interface CrdtBackend {
  * holds). `crdtText()` remains the single-field specialisation over the same
  * backend.
  */
-declare interface CrdtDocHandle {
+export 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
@@ -134,9 +134,25 @@ declare interface CrdtDocHandle {
     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 (local edits AND applied
-     *  remote states). Returns the unsubscribe. */
-    onUpdate: (handler: (update: CrdtState) => void) => () => 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
@@ -765,14 +781,30 @@ export declare interface ResolveWithPolicyOptions {
 }
 
 /**
- * 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
+ * The genuinely REMAINING runtime seam — the two app-level NAMES nothing can
+ * derive, not un-built framework code: the mutation tag that writes the
+ * `crdtText()` column and the reactive query tag that streams the row, which
+ * `useCrdtText` is pointed at. The lifecycle around them ships; see the DONE
+ * entry above.
+ *
+ * **Two entries left this list, in opposite directions, and the distinction is
+ * the reason this comment is longer than the array.** A seam is work somebody
+ * still has to do. Neither of these was:
+ *
+ *   - `presence-broker-binding` is BUILT (`usePresenceChannel` in
+ *     `@voltro/plugin-presence/web`, riding the framework's own presence lane;
+ *     shape pinned by `presence/channelParity.test-d.ts`). The DONE entry above
+ *     has said so since plan 02 phase 1 while this array said the opposite —
+ *     one file claiming both, which is worse than either claim alone.
+ *   - `wasm-sqlite-durable-adapter` was REJECTED, with the reasoning recorded
+ *     in `mirror/queryMirror.ts`: the client's query surface is `(tag, input)`
+ *     and predicates never exist client-side, so a browser SQL engine would
+ *     evaluate a language the client never sees. A decision we made is not a
+ *     gap in the framework, and listing it as one invites somebody to close it.
+ *     The `KvStore` seam still admits a SQLite BACKING (mobile's expo-sqlite
+ *     adapter takes exactly that) — that is a different, already-open door.
  */
-export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-tags", "presence-broker-binding", "wasm-sqlite-durable-adapter"];
+export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-tags"];
 
 export declare type RuntimeSeam = (typeof RUNTIME_SEAMS)[number];
 

package/dist/index.js

@@ -1,4 +1,4 @@
-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-DZzqWoJq.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 g = (e) => {
 	if (e.writer !== void 0) return `w:${e.writer}`;
@@ -283,10 +283,6 @@ var g = (e) => {
 	"sync-transport-react-binding",
 	"presence-room",
 	"localFirst-mixin-discovery"
-], Q = [
-	"sync-transport-app-tags",
-	"presence-broker-binding",
-	"wasm-sqlite-durable-adapter"
-];
+], Q = ["sync-transport-app-tags"];
 //#endregion
 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

@@ -78,9 +78,25 @@ declare interface CrdtDocHandle {
     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 (local edits AND applied
-     *  remote states). Returns the unsubscribe. */
-    onUpdate: (handler: (update: CrdtState) => void) => () => 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
@@ -100,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
@@ -258,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;

package/dist/react.js

@@ -1,4 +1,4 @@
-import { a as e, c as t, i as n, l as r, n as i, p as a, r as o, s, t as c } from "./room-DZzqWoJq.js";
+import { a as e, c as t, i as n, l as r, n as i, p as a, r as o, s, t as c } from "./room-24dGMM80.js";
 import { useCallback as l, useEffect as u, useMemo as d, useReducer as f, useRef as p, useState as m } from "react";
 //#region src/react/useSyncQueue.ts
 var h = (e = !0) => {
@@ -97,7 +97,43 @@ var h = (e = !0) => {
 		_,
 		f
 	]);
-}, x = (e, t) => {
+}, x = (e) => {
+	let { cell: t } = e, n = null, r = i({
+		transport: {
+			kind: "sync-transport",
+			push: async (t) => {
+				await e.push({
+					table: t.payload.table,
+					id: t.payload.id,
+					column: t.payload.column,
+					update: t.payload.update,
+					attempts: t.attempts
+				});
+			},
+			onRemoteState: (e) => (n = (n) => {
+				e({
+					...t,
+					state: n
+				});
+			}, () => {
+				n = null;
+			})
+		},
+		...e.adapter === void 0 ? {} : { adapter: e.adapter },
+		...e.backend === void 0 ? {} : { backend: e.backend },
+		...e.online === void 0 ? {} : { online: e.online },
+		...e.maxAttempts === void 0 ? {} : { maxAttempts: e.maxAttempts }
+	});
+	return {
+		client: r,
+		deliverRemote: (e) => {
+			n?.(e);
+		},
+		close: () => {
+			r.close();
+		}
+	};
+}, S = (e) => `${e.table}\u0000${e.id}\u0000${e.column}`, C = (e, t) => {
 	if (e === t) return null;
 	let n = Math.min(e.length, t.length), r = 0;
 	for (; r < n && e[r] === t[r];) r += 1;
@@ -108,71 +144,53 @@ var h = (e = !0) => {
 		deleteLength: e.length - r - i,
 		insert: t.slice(r, t.length - i)
 	};
-}, S = (e) => `${e.table}\u0000${e.id}\u0000${e.column}`, C = {
+}, w = {
 	text: "",
 	state: void 0,
 	outstanding: 0
-}, w = (e) => {
-	let { cell: t, remote: n, adapter: r, online: o, maxAttempts: s } = e, c = e.backend ?? a, f = S(t), h = p(e.push);
-	h.current = e.push;
-	let g = p(t);
-	g.current = t;
-	let _ = p(null), v = p(null), y = p(null), [b, w] = m(C);
+}, T = (e) => {
+	let { cell: t, remote: n, adapter: r, online: i, maxAttempts: o } = e, s = e.backend ?? a, c = S(t), f = p(e.push);
+	f.current = e.push;
+	let h = p(t);
+	h.current = t;
+	let g = p(null), _ = p(null), v = p(null), [y, b] = m(w);
 	u(() => {
-		let t = g.current, n = i({
-			transport: {
-				kind: "sync-transport",
-				push: async (e) => {
-					await h.current({
-						table: e.payload.table,
-						id: e.payload.id,
-						column: e.payload.column,
-						update: e.payload.update,
-						attempts: e.attempts
-					});
-				},
-				onRemoteState: (e) => (v.current = (n) => {
-					e({
-						...t,
-						state: n
-					});
-				}, () => {
-					v.current = null;
-				})
-			},
+		let t = h.current, n = x({
+			cell: t,
+			push: (e) => f.current(e),
 			...r === void 0 ? {} : { adapter: r },
 			...e.backend === void 0 ? {} : { backend: e.backend },
-			...o === void 0 ? {} : { online: o },
-			...s === void 0 ? {} : { maxAttempts: s }
-		});
-		_.current = n, y.current = c.createText();
-		let a = () => {
-			let e = n.getText(t), r = n.outstanding();
-			w((i) => i.text === e && i.outstanding === r ? i : {
+			...i === void 0 ? {} : { online: i },
+			...o === void 0 ? {} : { maxAttempts: o }
+		}), a = n.client;
+		g.current = a, _.current = n.deliverRemote, v.current = s.createText();
+		let c = () => {
+			let e = a.getText(t), n = a.outstanding();
+			b((r) => r.text === e && r.outstanding === n ? r : {
 				text: e,
-				state: n.getState(t),
-				outstanding: r
+				state: a.getState(t),
+				outstanding: n
 			});
-		}, l = n.subscribe(a);
-		return a(), () => {
-			l(), n.close(), _.current = null, y.current = null, v.current = null, w(C);
+		}, l = a.subscribe(c);
+		return c(), () => {
+			l(), n.close(), g.current = null, v.current = null, _.current = null, b(w);
 		};
 	}, [
-		f,
-		r,
 		c,
+		r,
+		s,
 		e.backend,
-		o,
-		s
+		i,
+		o
 	]), u(() => {
-		n != null && v.current?.(n);
-	}, [f, n]);
+		n != null && _.current?.(n);
+	}, [c, n]);
 	let T = l((e) => {
-		let t = _.current, n = y.current;
+		let t = g.current, n = v.current;
 		if (t === null || n === null) return;
-		let r = t.getState(g.current);
+		let r = t.getState(h.current);
 		r !== void 0 && n.applyState(r), e(n), t.enqueue({
-			...g.current,
+			...h.current,
 			update: n.encodeState()
 		});
 	}, []), E = l((e, t) => {
@@ -180,31 +198,85 @@ var h = (e = !0) => {
 	}, [T]), D = l((e, t) => {
 		t <= 0 || T((n) => n.delete(e, t));
 	}, [T]), O = l((e) => {
-		let t = _.current;
+		let t = g.current;
 		if (t === null) return;
-		let n = x(t.getText(g.current), e);
+		let n = C(t.getText(h.current), e);
 		n !== null && T((e) => {
 			n.deleteLength > 0 && e.delete(n.index, n.deleteLength), n.insert !== "" && e.insert(n.index, n.insert);
 		});
 	}, [T]), k = l((e) => {
-		_.current?.setOnline(e);
+		g.current?.setOnline(e);
 	}, []);
 	return d(() => ({
-		text: b.text,
-		state: b.state,
-		outstanding: b.outstanding,
-		synced: b.outstanding === 0,
+		text: y.text,
+		state: y.state,
+		outstanding: y.outstanding,
+		synced: y.outstanding === 0,
 		insert: E,
 		delete: D,
 		setText: O,
 		setOnline: k
 	}), [
-		b,
+		y,
 		E,
 		D,
 		O,
 		k
 	]);
+}, E = (e) => {
+	let { cell: t, remote: n, adapter: r, online: i, maxAttempts: o } = e, s = e.backend ?? a, c = S(t), f = p(e.push);
+	f.current = e.push;
+	let h = p(t);
+	h.current = t;
+	let g = p(n);
+	g.current = n;
+	let _ = p(null), v = p(null), y = p(null), [b, C] = m(null), [w, T] = m(!1), [E, D] = m(0);
+	u(() => {
+		let t = h.current, n = x({
+			cell: t,
+			push: (e) => f.current(e),
+			...r === void 0 ? {} : { adapter: r },
+			...e.backend === void 0 ? {} : { backend: e.backend },
+			...i === void 0 ? {} : { online: i },
+			...o === void 0 ? {} : { maxAttempts: o }
+		}), a = n.client, c = s.createDoc();
+		_.current = a, y.current = c, v.current = n.deliverRemote;
+		let l = c.onUpdate((e, t) => {
+			t.local && a.enqueue({
+				...h.current,
+				update: e
+			});
+		}), u = () => {
+			D(a.outstanding());
+		}, d = a.subscribe(u), p = g.current;
+		return p != null && (n.deliverRemote(p), c.applyState(p), T(!0)), C(c), u(), () => {
+			l(), d(), n.close(), _.current = null, y.current = null, v.current = null, C(null), T(!1), D(0);
+		};
+	}, [
+		c,
+		r,
+		s,
+		e.backend,
+		i,
+		o
+	]), u(() => {
+		n != null && (v.current?.(n), y.current?.applyState(n), T(!0));
+	}, [c, n]);
+	let O = l((e) => {
+		_.current?.setOnline(e);
+	}, []);
+	return d(() => ({
+		doc: b,
+		loaded: w,
+		outstanding: E,
+		synced: E === 0,
+		setOnline: O
+	}), [
+		b,
+		w,
+		E,
+		O
+	]);
 };
 //#endregion
-export { x as crdtTextEdit, _ as useConnectionStatus, w as useCrdtText, b as usePresence, h as useSyncQueue };
+export { C as crdtTextEdit, _ as useConnectionStatus, E as useCrdtDoc, T as useCrdtText, b as usePresence, h as useSyncQueue };