@haklex/rich-collab-loro 0.44.0

package/src/binding.ts

@@ -0,0 +1,282 @@
+import {
+  $getNodeByKey,
+  $getRoot,
+  $getSelection,
+  $isElementNode,
+  $isRangeSelection,
+  $isTextNode,
+  $parseSerializedNode,
+  type ElementNode,
+  type LexicalEditor,
+  type LexicalNode,
+  type NodeKey,
+  type SerializedLexicalNode,
+  type TextNode,
+} from 'lexical';
+import { type LoroDoc, LoroText, type LoroTreeNode, type TreeID } from 'loro-crdt';
+
+import { transformOffset } from './offset';
+import { $updateInPlace } from './reconcile';
+import { stable } from './stable';
+
+export const COLLAB_TAG = 'collab';
+export const TREE_NAME = 'lexical';
+const TEXT_KEY = '#text';
+
+export interface LoroBinding {
+  dispose: () => void;
+  idOf: (key: NodeKey) => TreeID | undefined;
+  import: (bytes: Uint8Array) => void;
+  keyOf: (id: TreeID) => NodeKey | undefined;
+}
+
+export interface LoroBindingOptions {
+  commitMessage?: string;
+}
+
+type Props = Record<string, unknown>;
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || stable(a) === stable(b);
+}
+
+function nodeProps(node: LexicalNode): Props {
+  const { children: _children, ...props } = node.exportJSON() as Props;
+  if ($isTextNode(node)) delete props.text;
+  return props;
+}
+
+function storedProps(treeNode: LoroTreeNode): Props {
+  const { [TEXT_KEY]: _text, ...props } = treeNode.data.toJSON() as Props;
+  return props;
+}
+
+export function createLoroBinding(
+  editor: LexicalEditor,
+  doc: LoroDoc,
+  options: LoroBindingOptions = {},
+): LoroBinding {
+  const tree = doc.getTree(TREE_NAME);
+  tree.enableFractionalIndex(0);
+  const keyToId = new Map<NodeKey, TreeID>();
+  const idToKey = new Map<TreeID, NodeKey>();
+
+  const link = (key: NodeKey, id: TreeID) => {
+    const previousId = keyToId.get(key);
+    if (previousId !== undefined) idToKey.delete(previousId);
+    const previousKey = idToKey.get(id);
+    if (previousKey !== undefined) keyToId.delete(previousKey);
+    keyToId.set(key, id);
+    idToKey.set(id, key);
+  };
+
+  const alive = (id: TreeID | undefined): id is TreeID =>
+    id !== undefined && tree.has(id) && !tree.isNodeDeleted(id);
+
+  // Peers may register different classes for one type (headless vs edit nodes) whose
+  // exportJSON disagree; writing only this peer's own prop changes stops them from
+  // endlessly overwriting each other's fields.
+  const synced = new Map<NodeKey, Props>();
+  const readBaseline = new Map<TreeID, string>();
+
+  const writeNode = (node: LexicalNode, treeNode: LoroTreeNode) => {
+    const data = treeNode.data;
+    const props = nodeProps(node);
+    const previous = synced.get(node.getKey()) ?? {};
+    let wrote = false;
+    for (const key of new Set([...Object.keys(previous), ...Object.keys(props)])) {
+      const value = props[key];
+      if (sameValue(previous[key], value) && (value === undefined || data.get(key) !== undefined)) {
+        continue;
+      }
+      if (value === undefined) {
+        if (data.get(key) !== undefined) {
+          data.delete(key);
+          wrote = true;
+        }
+      } else if (!sameValue(data.get(key), value)) {
+        data.set(key, value as never);
+        wrote = true;
+      }
+    }
+    synced.set(node.getKey(), props);
+    if (wrote) readBaseline.set(treeNode.id, stable(storedProps(treeNode)));
+    if ($isTextNode(node)) {
+      const text = data.getOrCreateContainer(TEXT_KEY, new LoroText());
+      const next = node.getTextContent();
+      if (text.toString() !== next) text.update(next);
+    }
+  };
+
+  const writeChildren = (parent: ElementNode, parentId: TreeID, visited: Set<TreeID>) => {
+    parent.getChildren().forEach((child, index) => {
+      let id = keyToId.get(child.getKey());
+      if (alive(id)) {
+        const current = tree.getNodeByID(id)!;
+        if (current.parent()?.id !== parentId || current.index() !== index) {
+          tree.move(id, parentId, index);
+        }
+      } else {
+        id = tree.createNode(parentId, index).id;
+        link(child.getKey(), id);
+      }
+      visited.add(id);
+      writeNode(child, tree.getNodeByID(id)!);
+      if ($isElementNode(child)) writeChildren(child, id, visited);
+    });
+  };
+
+  // ponytail: full-tree walk per update; switch to dirtyElements/dirtyLeaves if long drafts lag
+  const pushToDoc = () => {
+    editor.getEditorState().read(() => {
+      let rootId = keyToId.get('root');
+      if (!alive(rootId)) {
+        rootId = tree.roots()[0]?.id ?? tree.createNode().id;
+        link('root', rootId);
+      }
+      const visited = new Set<TreeID>([rootId]);
+      writeNode($getRoot(), tree.getNodeByID(rootId)!);
+      writeChildren($getRoot(), rootId, visited);
+      for (const treeNode of tree.nodes()) {
+        if (!visited.has(treeNode.id) && alive(treeNode.id)) {
+          tree.delete(treeNode.id);
+          const key = idToKey.get(treeNode.id);
+          if (key !== undefined) keyToId.delete(key);
+          idToKey.delete(treeNode.id);
+        }
+      }
+    });
+    doc.commit({ message: options.commitMessage });
+  };
+
+  const applyText = (node: TextNode, next: string) => {
+    const previous = node.getTextContent();
+    if (previous === next) return;
+    const selection = $getSelection();
+    const points = $isRangeSelection(selection)
+      ? [selection.anchor, selection.focus].filter(
+          (point) => point.type === 'text' && point.key === node.getKey(),
+        )
+      : [];
+    const offsets = points.map((point) => transformOffset(previous, next, point.offset));
+    node.setTextContent(next);
+    points.forEach((point, index) => point.set(node.getKey(), offsets[index], 'text'));
+  };
+
+  const readNode = (treeNode: LoroTreeNode): LexicalNode => {
+    const node = readNodeUnsynced(treeNode);
+    synced.set(node.getKey(), nodeProps(node));
+    return node;
+  };
+
+  const readNodeUnsynced = (treeNode: LoroTreeNode): LexicalNode => {
+    const props = storedProps(treeNode);
+    const text = $isTextLike(props) ? String(treeNode.data.get(TEXT_KEY) ?? '') : undefined;
+    const key = idToKey.get(treeNode.id);
+    const existing = key === undefined ? null : $getNodeByKey(key);
+    if (existing && existing.getType() === props.type) {
+      if ($isTextNode(existing)) {
+        if (!sameValue(nodeProps(existing), props)) {
+          existing.updateFromJSON({ ...props, text: existing.getTextContent() } as never);
+        }
+        applyText(existing, text ?? '');
+        return existing;
+      }
+      const storedKey = stable(props);
+      if (readBaseline.get(treeNode.id) === storedKey || sameValue(nodeProps(existing), props)) {
+        readBaseline.set(treeNode.id, storedKey);
+        return existing;
+      }
+      if ($updateInPlace(existing, props as never)) {
+        readBaseline.set(treeNode.id, storedKey);
+        return existing;
+      }
+      readBaseline.set(treeNode.id, storedKey);
+      const replacement = $parseSerializedNode({
+        ...props,
+        children: [],
+      } as unknown as SerializedLexicalNode);
+      existing.replace(replacement, $isElementNode(existing) && $isElementNode(replacement));
+      link(replacement.getKey(), treeNode.id);
+      return replacement;
+    }
+    const created = $parseSerializedNode({
+      ...props,
+      ...(text === undefined ? {} : { text }),
+      children: [],
+    } as unknown as SerializedLexicalNode);
+    readBaseline.set(treeNode.id, stable(props));
+    link(created.getKey(), treeNode.id);
+    return created;
+  };
+
+  const readChildren = (parent: ElementNode, treeNode: LoroTreeNode, visited: Set<NodeKey>) => {
+    (treeNode.children() ?? []).forEach((child, index) => {
+      const node = readNode(child);
+      visited.add(node.getKey());
+      const current = parent.getChildAtIndex(index);
+      if (!current || !current.is(node)) {
+        if (index === 0) {
+          const first = parent.getFirstChild();
+          if (first) first.insertBefore(node);
+          else parent.append(node);
+        } else {
+          parent.getChildAtIndex(index - 1)!.insertAfter(node);
+        }
+      }
+      if ($isElementNode(node)) readChildren(node, child, visited);
+    });
+  };
+
+  const $collectDescendants = (node: ElementNode, out: LexicalNode[]) => {
+    for (const child of node.getChildren()) {
+      out.push(child);
+      if ($isElementNode(child)) $collectDescendants(child, out);
+    }
+  };
+
+  const pullFromDoc = () => {
+    editor.update(
+      () => {
+        const rootTreeNode = tree.roots()[0];
+        if (!rootTreeNode) return;
+        link('root', rootTreeNode.id);
+        const rootProps = storedProps(rootTreeNode);
+        if (rootProps.type === 'root' && !sameValue(nodeProps($getRoot()), rootProps)) {
+          $getRoot().updateFromJSON(rootProps as never);
+        }
+        synced.set('root', nodeProps($getRoot()));
+        const visited = new Set<NodeKey>(['root']);
+        readChildren($getRoot(), rootTreeNode, visited);
+        const all: LexicalNode[] = [];
+        $collectDescendants($getRoot(), all);
+        for (const node of all) {
+          if (!visited.has(node.getKey()) && node.isAttached()) node.remove();
+        }
+      },
+      { discrete: true, tag: COLLAB_TAG },
+    );
+  };
+
+  if (tree.roots().length > 0) pullFromDoc();
+  else pushToDoc();
+
+  const unregister = editor.registerUpdateListener(({ dirtyElements, dirtyLeaves }) => {
+    if (dirtyElements.size === 0 && dirtyLeaves.size === 0) return;
+    pushToDoc();
+  });
+
+  return {
+    dispose: unregister,
+    idOf: (key) => keyToId.get(key),
+    keyOf: (id) => idToKey.get(id),
+    import: (bytes) => {
+      doc.import(bytes);
+      pullFromDoc();
+    },
+  };
+}
+
+function $isTextLike(props: Props): boolean {
+  return typeof props.format === 'number' && typeof props.detail === 'number' && 'mode' in props;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  COLLAB_TAG,
+  createLoroBinding,
+  type LoroBinding,
+  type LoroBindingOptions,
+  TREE_NAME,
+} from './binding';
+export { $reconcileRoot, editAtVersion } from './reconcile';
+export {
+  type Frame,
+  type FrameFocus,
+  planFrames,
+  streamAtVersion,
+  type StreamStep,
+} from './stream';

package/src/offset.ts

@@ -0,0 +1,15 @@
+export function transformOffset(previous: string, next: string, offset: number): number {
+  const limit = Math.min(previous.length, next.length);
+  let prefix = 0;
+  while (prefix < limit && previous[prefix] === next[prefix]) prefix++;
+  let suffix = 0;
+  while (
+    suffix < limit - prefix &&
+    previous[previous.length - 1 - suffix] === next[next.length - 1 - suffix]
+  ) {
+    suffix++;
+  }
+  if (offset <= prefix) return offset;
+  if (offset >= previous.length - suffix) return offset + next.length - previous.length;
+  return next.length - suffix;
+}

package/src/reconcile.ts

@@ -0,0 +1,174 @@
+import {
+  $getRoot,
+  $isElementNode,
+  $isTextNode,
+  $parseSerializedNode,
+  type ElementNode,
+  type LexicalEditor,
+  type LexicalNode,
+  type SerializedEditorState,
+  type SerializedLexicalNode,
+} from 'lexical';
+import type { LoroDoc } from 'loro-crdt';
+
+import { createLoroBinding } from './binding';
+import { stable } from './stable';
+
+export type Json = SerializedLexicalNode & {
+  $?: { blockId?: string };
+  children?: Json[];
+  text?: string;
+};
+
+export type Frontiers = ReturnType<LoroDoc['frontiers']>;
+
+const DERIVED_KEYS: Record<string, string[]> = { listitem: ['value'] };
+
+function withoutDerived(json: Json): Record<string, unknown> {
+  const { children: _children, text: _text, ...rest } = json;
+  for (const key of DERIVED_KEYS[json.type] ?? []) delete (rest as Record<string, unknown>)[key];
+  return rest;
+}
+
+function shallow(json: Json): string {
+  return stable(withoutDerived(json));
+}
+
+function $serialize(node: LexicalNode): Json {
+  const json = node.exportJSON() as Json;
+  if ($isElementNode(node)) json.children = node.getChildren().map($serialize);
+  return json;
+}
+
+// ponytail: O(n·m) LCS per element; fine for article-sized blocks, switch to Myers if docs grow huge
+export function lcs(a: string[], b: string[]): Array<[number, number]> {
+  const table = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i][j] =
+        a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+  const pairs: Array<[number, number]> = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) pairs.push([i++, j++]);
+    else if (table[i + 1][j] >= table[i][j + 1]) i++;
+    else j++;
+  }
+  return pairs;
+}
+
+// Replacing a node deletes its Loro tree node, and with it any child a peer
+// inserted concurrently; update in place whenever the node class can absorb the change.
+export function $updateInPlace(node: LexicalNode, target: Json): boolean {
+  const props = withoutDerived(target);
+  node.updateFromJSON(props as never);
+  return shallow(node.exportJSON() as Json) === shallow(target);
+}
+
+function $update(node: LexicalNode, current: Json, target: Json): LexicalNode {
+  if ($isTextNode(node)) {
+    if (shallow(current) !== shallow(target)) {
+      node.updateFromJSON({ ...target, text: node.getTextContent() } as never);
+    }
+    if (node.getTextContent() !== target.text) node.setTextContent(target.text ?? '');
+    return node;
+  }
+  if ($isElementNode(node)) {
+    let element: ElementNode = node;
+    if (shallow(current) !== shallow(target) && !$updateInPlace(node, target)) {
+      const replacement = $parseSerializedNode({ ...target, children: [] } as Json);
+      if (!$isElementNode(replacement)) return node;
+      node.replace(replacement, true);
+      element = replacement;
+    }
+    $reconcileChildren(element, target.children ?? []);
+    return element;
+  }
+  if (stable(current) === stable(target) || $updateInPlace(node, target)) return node;
+  const replacement = $parseSerializedNode(target);
+  node.replace(replacement);
+  return replacement;
+}
+
+export function pairable(current: Json, target: Json): boolean {
+  if (current.type !== target.type) return false;
+  const a = current.$?.blockId;
+  const b = target.$?.blockId;
+  return a === undefined || b === undefined || a === b;
+}
+
+function $reconcileChildren(parent: ElementNode, targets: Json[]): void {
+  const current = parent.getChildren();
+  const currentJson = current.map($serialize);
+  const pairs = lcs(currentJson.map(stable), targets.map(stable));
+  const result: LexicalNode[] = [];
+  let ci = 0;
+  let tj = 0;
+  for (const [i, j] of [...pairs, [current.length, targets.length] as [number, number]]) {
+    const pending = Array.from({ length: i - ci }, (_, k) => ci + k);
+    for (let t = tj; t < j; t++) {
+      const target = targets[t];
+      const blockId = target.$?.blockId;
+      let slot =
+        blockId === undefined
+          ? -1
+          : pending.findIndex(
+              (c) => currentJson[c].$?.blockId === blockId && pairable(currentJson[c], target),
+            );
+      if (slot === -1) slot = pending.findIndex((c) => pairable(currentJson[c], target));
+      if (slot === -1) {
+        result.push($parseSerializedNode(target));
+      } else {
+        const [c] = pending.splice(slot, 1);
+        result.push($update(current[c], currentJson[c], target));
+      }
+    }
+    if (i < current.length) result.push(current[i]);
+    ci = i + 1;
+    tj = j + 1;
+  }
+  const kept = new Set(result.map((node) => node.getKey()));
+  for (const node of parent.getChildren()) {
+    if (!kept.has(node.getKey())) node.remove(true);
+  }
+  result.forEach((node, index) => {
+    const at = parent.getChildAtIndex(index);
+    if (at && at.is(node)) return;
+    if (index === 0) {
+      const first = parent.getFirstChild();
+      if (first) first.insertBefore(node);
+      else parent.append(node);
+    } else {
+      result[index - 1].insertAfter(node);
+    }
+  });
+}
+
+export function $reconcileRoot(target: SerializedEditorState['root']): void {
+  const root = $getRoot();
+  const targetJson = target as unknown as Json;
+  if (shallow($serialize(root)) !== shallow(targetJson)) root.updateFromJSON(target);
+  const normalized = (targetJson.children ?? []).map((child) =>
+    $serialize($parseSerializedNode(child)),
+  );
+  $reconcileChildren(root, normalized);
+}
+
+export function editAtVersion(
+  doc: LoroDoc,
+  frontiers: Frontiers,
+  createEditor: () => LexicalEditor,
+  target: SerializedEditorState,
+  commitMessage?: string,
+): Uint8Array {
+  const fork = doc.forkAt(frontiers);
+  const editor = createEditor();
+  const binding = createLoroBinding(editor, fork, { commitMessage });
+  const from = fork.oplogVersion();
+  editor.update(() => $reconcileRoot(target.root), { discrete: true });
+  binding.dispose();
+  return fork.export({ from, mode: 'update' });
+}

package/src/stable.ts

@@ -0,0 +1,11 @@
+export function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .filter((key) => (value as Record<string, unknown>)[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stable((value as Record<string, unknown>)[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}