@voltro/local-first 0.52.0 → 0.54.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/local-first itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (3 packages).
+Generated from the resolved runtime dependency closure (4 packages).
 
 ---
 
@@ -65,6 +65,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## y-protocols@1.0.7
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2019 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## yjs@13.6.32
 
 License: MIT

package/dist/editor.d.ts

@@ -0,0 +1,125 @@
+import * as awarenessProtocol from 'y-protocols/awareness';
+import { Editor } from '@tiptap/react';
+
+/**
+ * Bridge ONE client's awareness onto the latest-event transport. Outbound:
+ * every local change publishes ONLY this client's encoded state — the
+ * per-member payload budget that keeps a multi-range selection far inside
+ * the 7 500-byte event envelope cap (never the aggregated room). Inbound:
+ * received updates apply as remote states. Returns the detach, which also
+ * removes this client's state so peers see the caret leave.
+ */
+export declare const attachAwarenessBridge: (instance: awarenessProtocol.Awareness, transport: AwarenessTransport) => (() => void);
+
+export declare interface AwarenessTransport {
+    /** Publish THIS client's encoded awareness update (a small Uint8Array —
+     *  one member's caret/selection). Bind to a `delivery: 'latest'` event
+     *  publish; fire-and-forget. */
+    readonly send: (update: Uint8Array) => void;
+    /** Subscribe to OTHER clients' awareness updates. Returns unsubscribe. */
+    readonly onReceive: (handler: (update: Uint8Array) => void) => () => void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+/**
+ * A collaborative rich-text editor over a `crdtDoc()` column. Content edits
+ * mutate the shared Y.Doc (push them through the app's mutation via
+ * `doc.onUpdate`; remote deltas arrive through the subscription fold) —
+ * this hook owns only the EDITOR lifecycle: one Tiptap instance bound to the
+ * doc, carets bridged over the injected latest-event transport, everything
+ * destroyed with the component.
+ */
+export declare const useCrdtEditor: (options: UseCrdtEditorOptions) => Editor | null;
+
+export declare interface UseCrdtEditorOptions {
+    /** The document handle (from `createDoc` / the sync layer) — its `raw`
+     *  Y.Doc is what Tiptap's Collaboration extension binds. */
+    readonly doc: CrdtDocHandle;
+    /** This user's caret identity. */
+    readonly user?: {
+        readonly name: string;
+        readonly color: string;
+    };
+    /** Caret transport (the `delivery: 'latest'` event pair). Omit for a
+     *  single-user editor — the caret extension is then not mounted. */
+    readonly awareness?: AwarenessTransport;
+    /** Extra Tiptap extensions (tables, mentions, …). */
+    readonly extensions?: ReadonlyArray<unknown>;
+    readonly editable?: boolean;
+}
+
+export { }

package/dist/editor.js

@@ -0,0 +1,53 @@
+import { useEffect as e, useMemo as t, useRef as n, useState as r } from "react";
+import { Editor as i } from "@tiptap/react";
+import a from "@tiptap/starter-kit";
+import o from "@tiptap/extension-collaboration";
+import { CollaborationCaret as s } from "@tiptap/extension-collaboration-caret";
+import * as c from "y-protocols/awareness";
+//#region src/editor/useCrdtEditor.ts
+var l = (l) => {
+	let { doc: d, user: f, awareness: p, editable: m = !0 } = l, h = n(null), g = t(() => p === void 0 ? null : new c.Awareness(d.raw), [p, d]);
+	e(() => {
+		if (g !== null && p !== void 0) return u(g, p);
+	}, [g, p]);
+	let _ = n(l.extensions);
+	_.current = l.extensions;
+	let [v, y] = r(null);
+	return e(() => {
+		let e = [
+			a.configure({ undoRedo: !1 }),
+			o.configure({ document: d.raw }),
+			...g === null ? [] : [s.configure({
+				provider: { awareness: g },
+				...f === void 0 ? {} : { user: f }
+			})],
+			..._.current ?? []
+		], t = new i({
+			extensions: e,
+			editable: m
+		});
+		return h.current = t, y(t), () => {
+			t.destroy(), h.current === t && (h.current = null), y((e) => e === t ? null : e);
+		};
+	}, [
+		d,
+		g,
+		f,
+		m
+	]), e(() => () => {
+		g?.destroy();
+	}, [g]), v;
+}, u = (e, t) => {
+	let n = e.clientID, r = (r, i) => {
+		i !== "remote" && t.send(c.encodeAwarenessUpdate(e, [n]));
+	};
+	e.on("update", r);
+	let i = t.onReceive((t) => {
+		c.applyAwarenessUpdate(e, t, "remote");
+	});
+	return () => {
+		c.removeAwarenessStates(e, [n], "detach"), e.off("update", r), i();
+	};
+};
+//#endregion
+export { u as attachAwarenessBridge, l as useCrdtEditor };