@llui/lexical-loro 0.1.0

package/src/binding.ts

@@ -0,0 +1,185 @@
+/**
+ * `loroCollab(config)` — the binding that drives both directions.
+ *
+ * It composes `to-loro.ts` (Lexical → Loro), `to-lexical.ts` (Loro → Lexical)
+ * and `seed.ts` (boot) into one `register(editor)` step you hand to
+ * `lexicalForeign({ history: false, seedMode: 'deferred', register })`. The
+ * returned handle satisfies `@llui/markdown-editor`'s `CollabBinding`
+ * structurally, so that package needs no Loro dependency of its own.
+ *
+ * ── Transport ──────────────────────────────────────────────────────────────
+ *
+ * There is none, deliberately. `LoroDoc` already exposes the whole wire surface
+ * (`subscribeLocalUpdates` / `import` / `export`), so a transport is a dozen
+ * lines the consumer writes against their own websocket, WebRTC channel or
+ * `loro-websocket` provider — and baking one in would make this package own a
+ * connection lifecycle it has no way to test honestly. Pass the same `LoroDoc`
+ * to your provider and to `loroCollab`.
+ *
+ * ── The three echo layers, and where each one lives ────────────────────────
+ *
+ * All three are required; any one missing produces an infinite loop or, worse,
+ * a silent data-loss bug:
+ *
+ *  a. Loro → us. A LOCAL Loro batch is our own outbound write completing its
+ *     commit. `applyLoroToLexical` drops it (`to-lexical.ts`). Without this the
+ *     binding re-enters `editor.update` from inside a Lexical update listener.
+ *  b. us → Lexical → us. Our inbound writeback is tagged `COLLABORATION_TAG`,
+ *     which `syncLexicalToLoro` skips (`to-loro.ts`). Without this every remote
+ *     keystroke is echoed straight back to its sender.
+ *  c. THE SEAM. This binding NEVER emits `PROGRAMMATIC_TAG`.
+ *     `packages/lexical/src/foreign.ts` treats that tag as "the host pushed new
+ *     content — cancel pending outbound work and rebase", so a remote writeback
+ *     carrying it would cancel the local user's in-flight debounced `onChange`
+ *     and the host's persistence would go dark whenever a peer types. There is
+ *     no code here to enforce this; there is simply no line that emits it, and
+ *     `test/to-lexical.test.ts` pins that.
+ *
+ * ── Undo ───────────────────────────────────────────────────────────────────
+ *
+ * This binding OWNS undo, via `externalUndo` (`undo.ts`, a Loro `UndoManager`
+ * scoped to this peer). Hosts must therefore turn their built-in
+ * `@lexical/history` stack off — `lexicalForeign` does that for you the moment
+ * `externalUndo` is present, so the two can never both be live.
+ *
+ * Loro's manager is operation-based and PeerID-scoped: undo reverts exactly the
+ * local user's own last change and never a peer's, which snapshot-based history
+ * cannot do at any tag setting. See `undo.ts` for why, and for the echo seam the
+ * undo batches travel through.
+ */
+
+import type { LexicalEditor } from 'lexical'
+import { LoroDoc } from 'loro-crdt'
+
+import { AGENT_WRITE_ORIGIN } from './agent-write.js'
+import { ContainerNodeMap } from './mapping.js'
+import { bootstrapDocument, type BootstrapOutcome } from './seed.js'
+import { initDoc, type ElementContainer } from './schema.js'
+import { LORO_TEXT_FORMATS } from './text.js'
+import { applyLoroToLexical } from './to-lexical.js'
+import { OUTBOUND_ORIGIN, syncLexicalToLoro } from './to-loro.js'
+import { registerLoroUndo, UNDO_ORIGINS, type LoroUndoOptions } from './undo.js'
+
+export interface LoroCollabConfig {
+  /** The shared document. Created if omitted — pass your provider's doc. */
+  readonly doc?: LoroDoc
+  /**
+   * Whether THIS peer may seed an empty shared document. Default `true`.
+   * Set `false` on peers that join rather than create, and on any peer whose
+   * transport has not completed its first sync — an unsynced document looks
+   * empty, and seeding one races the content about to arrive.
+   */
+  readonly shouldBootstrap?: boolean
+  /**
+   * Fill an empty shared document with this peer's default content. Runs once,
+   * inside a Lexical update. `@llui/markdown-editor` supplies this as
+   * `CollabHooks.seed`, which converts its `defaultValue` markdown.
+   */
+  readonly seed?: (editor: LexicalEditor) => void
+  /** Commit origin stamped on this binding's writes. Defaults to `'lexical-loro'`. */
+  readonly origin?: string
+  /** Called after boot with what happened — seeded, adopted, or still waiting. */
+  readonly onBootstrap?: (outcome: BootstrapOutcome) => void
+  /**
+   * Tuning for the peer-scoped undo manager installed by
+   * {@link LoroCollab.externalUndo} — merge window, stack depth, excluded
+   * origins. Defaults are in `undo.ts`; the `doc` is supplied by the binding.
+   */
+  readonly undo?: Omit<LoroUndoOptions, 'doc'>
+}
+
+/** Live handle returned by {@link loroCollab}. */
+export interface LoroCollab {
+  /**
+   * Wire the binding onto an editor; pass as `lexicalForeign({ register })`.
+   * Returns a disposer that unsubscribes both directions.
+   *
+   * Satisfies `@llui/markdown-editor`'s `CollabBinding` structurally.
+   */
+  register: (editor: LexicalEditor) => () => void
+  /** The shared document. Hand this to your transport. */
+  readonly doc: LoroDoc
+  /** The root element container mirroring Lexical's `RootNode`. */
+  readonly root: ElementContainer
+  /** The ContainerID ↔ NodeKey registry. Exposed for tests and diagnostics. */
+  readonly mapping: ContainerNodeMap
+  /**
+   * Install this binding's CRDT-aware undo/redo on the editor; pass as
+   * `lexicalForeign({ externalUndo })`. Returns a disposer.
+   *
+   * Undo is LOCAL-ONLY: it reverts this peer's own commits and leaves every
+   * other peer's concurrent edits standing (`undo.ts`). Registering it forces
+   * `lexicalForeign`'s built-in `@lexical/history` stack off, which is the point
+   * — a snapshot-based local stack would rewind remote work for everyone.
+   *
+   * Registration is SEPARATE from {@link LoroCollab.register} so a host that
+   * genuinely wants its own undo owner can decline it. Do not register it twice.
+   */
+  readonly externalUndo: (editor: LexicalEditor) => () => void
+  /** Re-run the boot decision — call after your transport's first sync. */
+  bootstrap: (editor: LexicalEditor) => BootstrapOutcome
+}
+
+/**
+ * Build a collaborative-editing binding over a Loro document.
+ *
+ * The document is configured for this package's schema (`initDoc`) immediately,
+ * not at `register` time, so a transport may be attached to `collab.doc` before
+ * any editor exists.
+ */
+export function loroCollab(config: LoroCollabConfig = {}): LoroCollab {
+  const doc = config.doc ?? new LoroDoc()
+  // Must run on EVERY peer: `configTextStyle` is local configuration, not
+  // replicated state, and a peer that skips it resolves marks under different
+  // expand rules and diverges. Idempotent, so a shared doc may be passed to
+  // more than one binding.
+  const root = initDoc(doc, LORO_TEXT_FORMATS)
+  const mapping = new ContainerNodeMap()
+  const origin = config.origin ?? OUTBOUND_ORIGIN
+
+  const bootstrap = (editor: LexicalEditor): BootstrapOutcome => {
+    const outcome = bootstrapDocument({
+      doc,
+      root,
+      mapping,
+      editor,
+      seed: config.seed,
+      shouldBootstrap: config.shouldBootstrap,
+    })
+    config.onBootstrap?.(outcome)
+    return outcome
+  }
+
+  const register = (editor: LexicalEditor): (() => void) => {
+    const outboundTarget = { doc, root, mapping, origin }
+    // `localOrigins` are the local batches the inbound path must still APPLY
+    // rather than drop as an echo (see `to-lexical.ts`). Both are passed
+    // unconditionally: only a Loro `UndoManager` produces `UNDO_ORIGINS` and only
+    // `reconcileTargetIntoLoro` produces `AGENT_WRITE_ORIGIN`, so listing them is
+    // inert until one occurs — and the inbound path stays independent of whether
+    // `externalUndo` was registered or an agent write ever happens.
+    const localOrigins = [...UNDO_ORIGINS, AGENT_WRITE_ORIGIN]
+    const inboundTarget = { doc, root, mapping, editor, localOrigins }
+
+    // Inbound BEFORE outbound: the subscription must be live before the
+    // bootstrap writes anything, or a document arriving mid-boot is missed.
+    const unsubscribe = doc.subscribe((batch) => {
+      applyLoroToLexical(inboundTarget, batch)
+    })
+    const unregister = editor.registerUpdateListener((payload) => {
+      syncLexicalToLoro(outboundTarget, payload)
+    })
+
+    bootstrap(editor)
+
+    return () => {
+      unregister()
+      unsubscribe()
+    }
+  }
+
+  const externalUndo = (editor: LexicalEditor): (() => void) =>
+    registerLoroUndo({ doc, ...config.undo }, editor)
+
+  return { register, doc, root, mapping, bootstrap, externalUndo }
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+/**
+ * `@llui/lexical-loro` — Loro CRDT binding for the LLui ↔ Lexical editor.
+ *
+ * Start at {@link loroCollab}: it composes everything below into a
+ * `register(editor)` plus an `externalUndo(editor)` you hand to
+ * `lexicalForeign({ seedMode: 'deferred', register, externalUndo })`, and it
+ * satisfies `@llui/markdown-editor`'s `CollabBinding` structurally.
+ *
+ * - `schema.ts`     — the Loro container shape mirroring a Lexical EditorState
+ * - `order.ts`      — fractional indexing: sibling order as a sortable property
+ * - `mapping.ts`    — the ContainerID ↔ NodeKey registry (the core invariant)
+ * - `text.ts`       — format-bitmask ↔ named-mark conversion, the run diff, and
+ *                     the cursor-biased text diff
+ * - `to-loro.ts`    — Lexical → Loro: the update-listener-driven mirror
+ * - `to-lexical.ts` — Loro → Lexical: the persistent, in-place mirror
+ * - `seed.ts`       — boot: seed an empty shared document, or adopt a populated one
+ * - `undo.ts`       — peer-scoped, CRDT-aware undo/redo over Loro's `UndoManager`
+ * - `binding.ts`    — `loroCollab`: both directions plus the echo guards
+ *
+ * ── Scope ──────────────────────────────────────────────────────────────────
+ *
+ * DOCUMENT SYNC plus LOCAL-ONLY UNDO. Undo is owned by this binding
+ * (`LoroCollab.externalUndo`), so a host MUST disable `@lexical/history` —
+ * `lexicalForeign` does that automatically once `externalUndo` is passed. Still
+ * out of scope: presence and remote cursors (additive, over Loro's
+ * `EphemeralStore`), and text-node `style` / `mode` / `detail` — the run model
+ * is `{text, format}`.
+ *
+ * ── Echo suppression ───────────────────────────────────────────────────────
+ *
+ * Three independent layers are ALL required; see `binding.ts` for where each
+ * one lives and what breaks without it. The one with no code to enforce it:
+ * this binding NEVER emits `PROGRAMMATIC_TAG`, because
+ * `packages/lexical/src/foreign.ts` reads that tag as "the host pushed content —
+ * cancel pending outbound work", which would make the host's persistence go dark
+ * whenever a peer types.
+ *
+ * `test/expand-semantics.test.ts` (51 tests) is the specification for the
+ * text-format half; read it before touching `text.ts`. `test/network.ts` is the
+ * multi-peer convergence harness, driven by `test/convergence.test.ts`.
+ */
+
+export {
+  ROOT_CONTAINER,
+  KEY_TYPE,
+  KEY_PROPS,
+  KEY_CHILDREN,
+  KEY_UUID,
+  KEY_POS,
+  KEY_KIND,
+  KEY_TEXT,
+  DECORATOR_TYPE,
+  KEY_BRIDGE_TYPE,
+  KEY_DATA,
+  ROOT_TYPE,
+  TEXT_MARK_EXPAND,
+  initDoc,
+  newUuid,
+  createElementChild,
+  createTextChild,
+  setChildPosition,
+  deleteChild,
+  orderedChildren,
+  childCount,
+  elementType,
+  elementProps,
+  elementChildren,
+  isElementContainer,
+  isTextContainer,
+  isDecoratorElement,
+  containerId,
+  containerIsLive,
+  type PropValue,
+  type PropsContainer,
+  type ElementContainer,
+  type ElementShape,
+  type ChildrenContainer,
+  type ChildContainer,
+  type ChildCarrier,
+  type CarrierShape,
+  type TextCarrier,
+  type TextCarrierShape,
+  type ChildEntry,
+  type ChildKind,
+  type ExpandType,
+} from './schema.js'
+
+export { DIGITS, between, allocate, allocateAt, jitterFor, comparePositions } from './order.js'
+
+export { ContainerNodeMap, type MappingEntry, type LivenessProbe } from './mapping.js'
+
+export {
+  LORO_TEXT_FORMATS,
+  FORMAT_BITS,
+  KNOWN_FORMAT_MASK,
+  formatBit,
+  formatsFromBitmask,
+  bitmaskFromFormats,
+  bitmaskFromAttributes,
+  runsText,
+  normalizeRuns,
+  runsFromDelta,
+  runsFromText,
+  diffRunFormats,
+  applyMarkOps,
+  diffTextWithCursor,
+  diffText,
+  applyTextDiff,
+  type LoroTextFormat,
+  type TextRun,
+  type TextDeltaItem,
+  type MarkOp,
+  type TextDiff,
+} from './text.js'
+
+export {
+  OUTBOUND_ORIGIN,
+  OUTBOUND_SKIP_TAGS,
+  syncLexicalToLoro,
+  seedLoroFromLexical,
+  longestIncreasingSubsequence,
+  type OutboundTarget,
+  type OutboundUpdate,
+} from './to-loro.js'
+
+export {
+  INBOUND_TAGS,
+  applyLoroToLexical,
+  adoptLoroDocument,
+  type InboundTarget,
+} from './to-lexical.js'
+
+export {
+  bootstrapDocument,
+  isSharedDocumentEmpty,
+  type BootstrapOutcome,
+  type BootstrapTarget,
+} from './seed.js'
+
+export {
+  LORO_UNDO_ORIGIN,
+  UNDO_ORIGINS,
+  DEFAULT_MERGE_INTERVAL,
+  DEFAULT_MAX_UNDO_STEPS,
+  registerLoroUndo,
+  type LoroUndoOptions,
+} from './undo.js'
+
+export { loroCollab, type LoroCollab, type LoroCollabConfig } from './binding.js'
+
+/**
+ * Agent-write: apply an LLM's full-document markdown REWRITE to the shared
+ * document by CONTENT, so unchanged blocks keep their `ContainerID`s (hence their
+ * `NodeKey`s and mounted decorator sub-apps, and any concurrent peer edit into
+ * them) instead of being recreated wholesale.
+ *
+ * `reconcileTargetIntoLoro` is a SIBLING to `syncLexicalToLoro`: it writes Loro
+ * directly under {@link AGENT_WRITE_ORIGIN} and does NOT consult the
+ * `ContainerNodeMap` (content matching is the point; the mapping self-heals on
+ * the inbound bounce into any live editor). The caller owns the markdown → target
+ * parse with its own `@lexical/markdown` transformer set — this package never
+ * depends on `@lexical/markdown` — and projects the parsed editor state with
+ * {@link targetFromEditorState} / {@link projectTarget}.
+ *
+ * Guarantees and the documented DUPLICATE-BLOCK caveat live on the functions and
+ * in the README.
+ */
+export {
+  AGENT_WRITE_ORIGIN,
+  reconcileTargetIntoLoro,
+  projectTarget,
+  targetFromEditorState,
+  type TargetElement,
+  type TargetText,
+  type TargetChild,
+} from './agent-write.js'

package/src/mapping.ts

@@ -0,0 +1,206 @@
+/**
+ * The ContainerID ↔ NodeKey registry — the core invariant of this package.
+ *
+ * ── Why it exists ──────────────────────────────────────────────────────────
+ *
+ * Lexical's `NodeKey` is a bare per-session counter
+ * (`LexicalUtils.ts`: `return '' + keyCounter++`). It is meaningless to a peer
+ * and unstable across reloads. Loro's `ContainerID` is the stable, replicated
+ * address. Every sync operation is therefore a translation between the two, and
+ * this registry is the only place that translation is allowed to happen.
+ *
+ * There is also NO stable node-object identity to key off: Lexical CLONES a node
+ * on every write, so `node === node` fails across an update. The NodeKey string
+ * survives cloning; the object does not. Hence a key↔id map, never a WeakMap.
+ *
+ * ── THE INVARIANT ──────────────────────────────────────────────────────────
+ *
+ * The two internal maps are always exact inverses of each other: a BIJECTION.
+ *
+ *     byContainer.get(id) === key   ⟺   byNode.get(key) === id
+ *
+ * No ContainerID ever addresses two NodeKeys, and no NodeKey ever addresses two
+ * ContainerIDs. `link()` enforces this by evicting BOTH stale directions before
+ * writing, so a re-link can never leave a half-entry behind. A violated
+ * bijection is the failure mode that silently corrupts a document: a stale
+ * reverse entry makes an inbound remote edit land on the wrong Lexical node.
+ *
+ * ── When it must be updated ────────────────────────────────────────────────
+ *
+ * - local create/delete   — the user edited; mirror the change outbound
+ * - remote create/delete  — an inbound event created/removed a container
+ * - TEXT NORMALIZATION    — Lexical silently merges/splits adjacent TextNodes
+ *   and reports it via `normalizedNodes`. This is the easiest one to forget and
+ *   the one that corrupts the document: the surviving node keeps ONE key and the
+ *   others are discarded, so their entries must be re-linked or dropped. This is
+ *   also why inbound application runs `discrete: true` — without a synchronous
+ *   flush the normalization happens after we have already read back keys, and
+ *   the mapping drifts.
+ *
+ * Entries are never implicitly expired. Use `sweep()` after a structural change
+ * to drop entries whose container or node no longer exists.
+ */
+
+import type { ContainerID } from 'loro-crdt'
+import type { NodeKey } from 'lexical'
+
+/** One direction of a mapping entry, as reported by iteration and sweeps. */
+export interface MappingEntry {
+  readonly id: ContainerID
+  readonly key: NodeKey
+}
+
+/** Liveness probes used by {@link ContainerNodeMap.sweep}. */
+export interface LivenessProbe {
+  /** True when the container still exists in the Loro document. */
+  readonly hasContainer: (id: ContainerID) => boolean
+  /** True when the node still exists in the Lexical editor state. */
+  readonly hasNode: (key: NodeKey) => boolean
+}
+
+/**
+ * A bijective, explicitly-invalidated registry mapping Loro `ContainerID`s to
+ * Lexical `NodeKey`s. See the file header for the invariant it maintains.
+ */
+export class ContainerNodeMap {
+  readonly #byContainer = new Map<ContainerID, NodeKey>()
+  readonly #byNode = new Map<NodeKey, ContainerID>()
+
+  /** Number of live entries. Both directions always agree on this. */
+  get size(): number {
+    return this.#byContainer.size
+  }
+
+  /**
+   * Link a container to a node, replacing any previous link on EITHER side.
+   *
+   * Evicting both directions first is what preserves the bijection: linking
+   * `id → k2` when `id → k1` existed must also drop `k1 → id`, or `k1` keeps
+   * resolving to a container it no longer owns.
+   */
+  link(id: ContainerID, key: NodeKey): void {
+    const previousKey = this.#byContainer.get(id)
+    if (previousKey !== undefined && previousKey !== key) this.#byNode.delete(previousKey)
+    const previousId = this.#byNode.get(key)
+    if (previousId !== undefined && previousId !== id) this.#byContainer.delete(previousId)
+    this.#byContainer.set(id, key)
+    this.#byNode.set(key, id)
+  }
+
+  /** The NodeKey addressed by a container, or `undefined` if unmapped. */
+  nodeKey(id: ContainerID): NodeKey | undefined {
+    return this.#byContainer.get(id)
+  }
+
+  /** The ContainerID addressing a node, or `undefined` if unmapped. */
+  containerId(key: NodeKey): ContainerID | undefined {
+    return this.#byNode.get(key)
+  }
+
+  /**
+   * The NodeKey addressed by a container. Throws when unmapped.
+   *
+   * Prefer this on paths where a missing entry means the registry is already
+   * corrupt — failing loudly beats writing to the wrong node.
+   */
+  expectNodeKey(id: ContainerID): NodeKey {
+    const key = this.#byContainer.get(id)
+    if (key === undefined) throw new Error(`lexical-loro: no NodeKey mapped for container ${id}`)
+    return key
+  }
+
+  /** The ContainerID addressing a node. Throws when unmapped. */
+  expectContainerId(key: NodeKey): ContainerID {
+    const id = this.#byNode.get(key)
+    if (id === undefined) throw new Error(`lexical-loro: no ContainerID mapped for node ${key}`)
+    return id
+  }
+
+  hasContainer(id: ContainerID): boolean {
+    return this.#byContainer.has(id)
+  }
+
+  hasNode(key: NodeKey): boolean {
+    return this.#byNode.has(key)
+  }
+
+  /**
+   * Move a container's link to a different NodeKey, keeping the bijection.
+   *
+   * This is the TEXT-NORMALIZATION path: Lexical merged our run's node into a
+   * sibling, so the container must now address the survivor. Returns false when
+   * the container was not mapped (nothing to move).
+   */
+  rekey(id: ContainerID, key: NodeKey): boolean {
+    if (!this.#byContainer.has(id)) return false
+    this.link(id, key)
+    return true
+  }
+
+  /** Drop the entry for a container. Returns whether one existed. */
+  unlinkContainer(id: ContainerID): boolean {
+    const key = this.#byContainer.get(id)
+    if (key === undefined) return false
+    this.#byContainer.delete(id)
+    this.#byNode.delete(key)
+    return true
+  }
+
+  /** Drop the entry for a node. Returns whether one existed. */
+  unlinkNode(key: NodeKey): boolean {
+    const id = this.#byNode.get(key)
+    if (id === undefined) return false
+    this.#byNode.delete(key)
+    this.#byContainer.delete(id)
+    return true
+  }
+
+  /** Every live entry, in insertion order. */
+  entries(): MappingEntry[] {
+    return [...this.#byContainer].map(([id, key]) => ({ id, key }))
+  }
+
+  /**
+   * Drop every entry whose container or node no longer exists, and return the
+   * entries removed.
+   *
+   * Deleting a subtree removes many containers at once; rather than making every
+   * caller walk the removed subtree, sweep after the structural change. An entry
+   * is stale if EITHER side is gone — a half-live entry is exactly the corrupt
+   * state the invariant forbids.
+   */
+  sweep(probe: LivenessProbe): MappingEntry[] {
+    const removed: MappingEntry[] = []
+    for (const [id, key] of this.#byContainer) {
+      if (probe.hasContainer(id) && probe.hasNode(key)) continue
+      removed.push({ id, key })
+    }
+    for (const { id } of removed) this.unlinkContainer(id)
+    return removed
+  }
+
+  /** Drop every entry. Used when the document is re-seeded from scratch. */
+  clear(): void {
+    this.#byContainer.clear()
+    this.#byNode.clear()
+  }
+
+  /**
+   * Assert the bijection holds. A debugging/test aid: production paths maintain
+   * it structurally, so a failure here means a bug in this class, not a caller.
+   *
+   * @internal
+   */
+  assertBijective(): void {
+    if (this.#byContainer.size !== this.#byNode.size) {
+      throw new Error(
+        `lexical-loro: mapping is not bijective — ${this.#byContainer.size} containers vs ${this.#byNode.size} nodes`,
+      )
+    }
+    for (const [id, key] of this.#byContainer) {
+      if (this.#byNode.get(key) !== id) {
+        throw new Error(`lexical-loro: mapping is not bijective at ${id} ↔ ${key}`)
+      }
+    }
+  }
+}