@llui/lexical-loro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Ponticelli
+
+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.

package/README.md

@@ -0,0 +1,262 @@
+# @llui/lexical-loro
+
+Loro CRDT binding for the LLui ↔ Lexical editor.
+
+> **Status: document sync, both directions, plus peer-scoped CRDT undo — usable
+> end to end.** No presence and no remote cursors yet. Transport is yours to
+> supply. See [Scope](#scope).
+
+## Usage
+
+```ts
+import { markdownEditor } from '@llui/markdown-editor'
+import { loroCollab } from '@llui/lexical-loro'
+import { LoroDoc } from 'loro-crdt'
+
+const doc = new LoroDoc()
+// …attach your transport to `doc` (subscribeLocalUpdates / import / export)…
+
+markdownEditor({
+  defaultValue: '# Hello',
+  collab: (hooks) => loroCollab({ doc, seed: hooks.seed, shouldBootstrap: isCreator }),
+})
+```
+
+`loroCollab` returns `{ register, externalUndo, doc, root, mapping, bootstrap }`.
+`register` **and** `externalUndo` together satisfy `@llui/markdown-editor`'s
+`CollabBinding` structurally, so that package needs no Loro dependency of its own
+— and, because `externalUndo` is present, the editor turns its built-in
+`@lexical/history` stack off automatically and uses this binding's peer-scoped
+undo instead. Wiring `loroCollab` directly (without `@llui/markdown-editor`),
+pass both to `lexicalForeign`:
+
+```ts
+const collab = loroCollab({ doc })
+lexicalForeign({
+  seedMode: 'deferred',
+  register: collab.register,
+  externalUndo: collab.externalUndo,
+})
+```
+
+**There is no built-in transport, deliberately.** `LoroDoc` already exposes the
+whole wire surface, so a transport is a dozen lines against your own websocket or
+provider — and shipping one here would mean owning a connection lifecycle this
+package cannot test honestly. Call `collab.bootstrap(editor)` again after your
+transport's first sync: an unsynced document looks empty, and seeding one races
+the content about to arrive.
+
+## Design
+
+The two directions are mirror images, and both are built around one rule.
+
+**Never rebuild what you can mutate.** Lexical's `NodeKey` is a bare counter, so
+recreating a node instead of updating it tears down its DOM, its selection, its
+IME composition — and disposes the mounted LLui sub-app of every
+`LLuiDecoratorNode` inside it (`packages/lexical/src/decorator.ts` disposes on
+the `'destroyed'` mutation). So:
+
+- `to-lexical.ts` resolves each remote change to an existing `NodeKey` through
+  the registry and mutates that node in place. It never replaces the document,
+  which is what loro-prosemirror's inbound path does — ProseMirror tolerates
+  that; Lexical cannot.
+- `to-loro.ts` emits one `pos` register write per moved block for a reorder
+  (`n - LIS(n)` writes — the longest increasing subsequence stays put), a
+  cursor-biased single-region diff for a text edit, and explicit per-format
+  `mark`/`unmark` ops for formatting. It returns its op count, and the tests
+  assert on it — so a pruning regression fails a test instead of quietly becoming
+  a slower, mount-destroying binding.
+- `mapping.ts` holds the `ContainerID ↔ NodeKey` bijection the whole thing rests
+  on: `NodeKey` is per-session, `ContainerID` is the stable cross-peer address.
+
+### How sibling order works: fractional indexing
+
+Children are **not** stored in a list. Each child — element **or** text run — is a
+carrier `LoroMap` holding `{ uuid, pos, kind, … }`, filed in its parent's
+`children` map under its own random `uuid`; a text carrier holds its `LoroText`
+under a `text` key, created **once** and never recreated. The rendered order is a
+pure projection of replicated state: **sort by `(pos, uuid)`**.
+
+`pos` is a fractional index — a base-62 string key with one always available
+strictly between any two distinct keys — so a **same-parent move is one
+last-writer-wins write to `pos`**. Nothing is deleted, nothing is recreated, and
+nothing inside the moved subtree is touched. Hence `ContainerID`s (and therefore
+`NodeKey`s, and therefore mounted decorator sub-apps and local carets) survive a
+remote reorder; a move costs under 400 bytes regardless of subtree size; and a
+concurrent edit _into_ a moved block is preserved.
+
+Because order is derived by sorting replicated fields, peers holding the same
+state cannot disagree about it — convergence is true by construction.
+
+#### Why not `LoroMovableList`
+
+That was this package's original design. It was abandoned because `loro-crdt`
+1.13.7 (the latest release) has two defects in concurrent move/delete handling:
+an uncatchable WASM panic, and a silent convergence failure where peers that have
+exchanged full snapshots both ways still render different orders. Both are pinned
+as `it.fails` in `test/loro-upstream.test.ts` — kept as the recorded rationale for
+the schema, and to turn red if a future release fixes them.
+
+#### Accepted tradeoffs
+
+Real costs, deliberately chosen, each demonstrated in `test/constraints.test.ts`:
+
+- **The concurrent-edit guarantee is same-parent only.** A **cross-parent** move
+  is still delete + recreate and **does** lose a concurrent edit into the moved
+  subtree. Not a regression — `LoroMovableList#move` is also single-list.
+- **Delete beats move.** A delete concurrent with a move of the same block wins
+  and the block vanishes, convergently, in both delivery orders. A tombstone
+  mitigation was tried and **refuted by test**: the delete flag and `pos` are
+  separate map keys, so both survive and nothing is rescued. Do not re-add
+  tombstones.
+- **`pos` keys are never rebalanced, and must not be.** A peer that inserted
+  concurrently computed its key against the _old_ keys, so after a rebalance its
+  block lands somewhere unrelated to what the user pointed at — convergent, and
+  silently wrong about intent. It is also unnecessary: growth is linear and
+  bounded (2000 adversarial same-spot inserts reach a 401-character key).
+- **Two concurrent splits of the same text run garble the text.** Ordinal text
+  matching mints a fresh tail container on each peer, so the merge duplicates a
+  fragment. **Pre-existing** — the `LoroMovableList` binding produced the same
+  result on the same history — and a property of text matching, not of the
+  ordering model. Not fixed here.
+
+### Why text formats cannot be one Loro value
+
+`TextNode.__format` is a bitmask (`IS_BOLD = 1`, `IS_ITALIC = 1 << 1`, …).
+Storing it as a single CRDT value makes two peers concurrently toggling **bold**
+and **italic** a last-writer-wins conflict that silently drops one. They are
+therefore independent, named Loro marks, which converge to the union.
+
+Loro's `expand` rule cannot reproduce Lexical's boundary behaviour — a 51-test
+spike (`test/expand-semantics.test.ts`) proved no uniform table works and no
+per-format table can, because Lexical's caret is uniformly left-biased. So the
+outbound direction replays the RESULTING node state as explicit mark/unmark ops,
+and `expand` governs only what happens to text a remote peer inserts
+concurrently at a mark boundary.
+
+### Echo suppression
+
+Three layers, all required; `binding.ts` documents what breaks without each. 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.
+
+## Agent write (content-keyed rewrite)
+
+When an LLM rewrites a note's **whole markdown**, the naive route — reparse into
+the live editor, which does `root.clear()` + rebuild — mints a fresh `NodeKey`
+for every node, so the outbound sync matches nothing through the registry and
+**recreates every container**. A concurrent edit from another window merges into
+a container this side just deleted and is lost, and every mounted decorator
+sub-app is torn down. Measured at **0% ContainerID survival even for identical
+markdown**.
+
+`reconcileTargetIntoLoro` is the supported alternative — a **sibling** to
+`syncLexicalToLoro`, not a replacement. It reconciles a parsed **target tree**
+directly against the Loro document, matching existing carriers to target children
+by **content** (not by `NodeKey`). Unchanged blocks keep their `ContainerID`s — and
+therefore their `NodeKey`s, their mounted decorator sub-apps, and any concurrent
+peer edit into them; a text-changed block keeps its `LoroText` and diffs the
+characters; only genuinely new / removed / moved blocks touch the ordering.
+
+```ts
+import { reconcileTargetIntoLoro, targetFromEditorState } from '@llui/lexical-loro'
+import { createHeadlessEditor } from '@lexical/headless'
+import { $convertFromMarkdownString } from '@lexical/markdown'
+
+// The CALLER owns the markdown → target-tree parse, with ITS OWN nodes and
+// transformer set (custom nodes/transformers make the tree caller-specific).
+const parser = createHeadlessEditor({ nodes: MY_NODES, onError })
+parser.update(() => $convertFromMarkdownString(agentMarkdown, MY_TRANSFORMERS), {
+  discrete: true,
+})
+const target = targetFromEditorState(parser.getEditorState())
+
+// The reusable CORE takes the parsed tree and writes Loro under 'agent-write'.
+reconcileTargetIntoLoro(collab.doc, collab.root, target)
+```
+
+**Guarantees.** Identical markdown ⇒ **zero ops, 100% survival**. A one-paragraph
+edit ⇒ only that `LoroText` changes. Append / prepend / delete / move ⇒ every
+surviving block keeps its identity, and a move is one `pos` write. The commit
+carries the distinct origin `AGENT_WRITE_ORIGIN`, which `loroCollab` lists among
+the local origins the **inbound** path applies — so an agent write on the shared
+document **bounces into any live editor** bound to it, preserving `NodeKey`s and
+decorator mounts on the way in. It deliberately does **not** consult the
+`ContainerNodeMap`: content matching is the point, and the mapping self-heals on
+the inbound bounce.
+
+**Why the caller owns the markdown parse.** The reconciler is the reusable core;
+the markdown → target parse is caller-specific (custom nodes and transformer set).
+Keeping it in the caller is what lets this package depend on **neither
+`@lexical/markdown` nor `@lexical/headless`** at runtime — they are dev-only here.
+Project the caller's parsed editor state with `targetFromEditorState` (or
+`projectTarget` inside a read); both use only `lexical`.
+
+### The duplicate-block caveat (honest residual)
+
+Content matching cannot fully disambiguate **byte-identical sibling blocks** —
+they have no distinguishing content, and the agent path has no `NodeKey` identity
+to fall back on. The exact-match pass applies a **content + position bias**: among
+identical carriers, a target claims the one whose index is nearest its own. That
+**fixes the common case** — changing the first of two identical blocks now leaves
+that block's carrier free to absorb the change while the unchanged sibling keeps
+its own carrier, so a concurrent edit to the other identical block no longer
+collides.
+
+It is **not a complete solution, and does not claim to be.** When the **count** of
+an identical group changes (delete one of three identical paragraphs), content is
+by definition insufficient to say which carrier the user meant to keep, and
+position proximity is only a guess — the trailing carrier is dropped regardless of
+intent. `NodeKey` identity, unavailable on the agent path, is the only complete
+answer. `test/agent-write.test.ts` pins both the improvement and this residual.
+
+## Scope
+
+- **Document sync + peer-scoped undo.** No presence or remote cursors yet —
+  Loro's `EphemeralStore` makes those additive, later work.
+- **Undo is CRDT-aware and LOCAL-ONLY** (`src/undo.ts`, exposed as
+  `LoroCollab.externalUndo`). It is built on Loro's `UndoManager`, which is
+  operation-based and bound to this peer's PeerID: undo reverts exactly the local
+  user's own last change and **never** a peer's concurrent edit. That is why a
+  host must let the editor turn `@lexical/history` off — `lexicalForeign` does so
+  automatically the moment `externalUndo` is passed, so the snapshot-based local
+  stack (which would rewind remote work for everyone) can never run alongside it.
+  A same-parent block move undoes to its previous fractional index; a text edit,
+  insert, delete and format change each undo to exactly their prior state.
+  `test/undo.test.ts` pins all of it, including the local-scope property.
+  `test/harden.test.ts` keeps a contrast test showing why the built-in snapshot
+  history — deliberately NOT used here — is not collaboration-safe.
+
+- **Text-node `style`, `mode` and `detail` are not represented**; the run model
+  is `{ text, format }`.
+
+## Triaging a suspected convergence bug
+
+Exchange full snapshots between peers and compare `doc.toJSON()`. If the
+**documents** differ, the problem is below this binding and not fixable here.
+Only if the documents agree while the **editors** differ is it ours.
+
+## Testing
+
+`test/network.ts` is a multi-peer in-memory network with delay, reordering and
+disconnect knobs; `test/convergence.test.ts` and `test/convergence-attack.test.ts`
+drive the real binding through it, ending in randomized three-peer property
+tests. Raising their round counts is how you hunt for new bugs — it is what found
+every real defect fixed so far.
+
+`test/constraints.test.ts` is different in kind: rather than testing that the
+code honours the ordering rules, it demonstrates **what breaks without them**. A
+failure there may be the cost of a deliberate tradeoff rather than a bug — read
+the comment before "fixing" one.
+
+## Peer dependencies
+
+`lexical`, `@llui/lexical` and `loro-crdt` are peer dependencies — install them
+in the host application so exactly one copy of each is deduped across the app and
+this package.
+
+## License
+
+MIT

package/dist/agent-write.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Agent-write: reconcile an AGENT-AUTHORED full-document rewrite into an existing
+ * Loro document without tearing down history.
+ *
+ * ── The problem ────────────────────────────────────────────────────────────
+ *
+ * An LLM rewrites a note's WHOLE markdown. The naive route — reparse the new
+ * markdown into the live bound editor (`root.clear()` + rebuild) — mints a fresh
+ * `NodeKey` for every node, so the outbound sync (`to-loro.ts`) matches nothing
+ * through the `NodeKey → ContainerID` registry and recreates EVERY container.
+ * A concurrent edit from another window merges into a container this side just
+ * deleted and is lost; a mounted `LLuiDecoratorNode` sub-app under any block is
+ * torn down. Measured at 0% ContainerID survival even for IDENTICAL markdown.
+ *
+ * ── The design ─────────────────────────────────────────────────────────────
+ *
+ * Reconcile a PARSED TARGET TREE directly against the existing Loro document,
+ * matching existing child carriers to target children by CONTENT rather than by
+ * NodeKey. Unchanged blocks keep their `ContainerID`s (and therefore their
+ * `NodeKey`s and decorator mounts on the inbound bounce); a text-changed block
+ * keeps its `LoroText` and diffs the characters; only genuinely new/removed/moved
+ * blocks touch the ordering. This is the analog of loro-prosemirror's
+ * content-equality match (`eqLoroObjNode`), living where the reconciler already
+ * is.
+ *
+ * This is a SIBLING to the outbound sync ({@link import('./to-loro.js')}), not a
+ * replacement: it writes the Loro document directly under {@link
+ * AGENT_WRITE_ORIGIN}, and the existing inbound path ({@link
+ * import('./to-lexical.js')}) replicates that change into any live editor bound
+ * to the same document — preserving `NodeKey`s and decorator mounts on the
+ * bounce, and self-healing the `ContainerID ↔ NodeKey` mapping there. For that
+ * bounce to happen, {@link AGENT_WRITE_ORIGIN} must be on the inbound target's
+ * list of local origins to apply; `binding.ts` wires that.
+ *
+ * ── What this deliberately does NOT consult ────────────────────────────────
+ *
+ * The `ContainerNodeMap` registry is intentionally NOT read here — content
+ * matching is the whole point, and the mapping self-heals on the inbound bounce.
+ * (Contrast `to-loro.ts`, whose whole job is IDENTITY matching through that
+ * registry.)
+ *
+ * ── Where the markdown parse lives ─────────────────────────────────────────
+ *
+ * The markdown → target-tree PARSE is the CALLER's job, because it is
+ * caller-specific: the caller owns its custom nodes and its own `@lexical/markdown`
+ * transformer set, and that transformer set defines the tree. This module pulls
+ * neither `@lexical/markdown` nor `@lexical/headless` (both would otherwise become
+ * runtime dependencies of a binding whose core — the reconciler — needs neither).
+ * The caller parses markdown headlessly with its own transformers and projects the
+ * resulting Lexical tree with {@link projectTarget} (or {@link
+ * targetFromEditorState}), then hands the plain, serializable {@link TargetElement}
+ * to {@link reconcileTargetIntoLoro}. The reconciler is the reusable core; the
+ * markdown parse is not.
+ */
+import { type EditorState, type LexicalNode } from 'lexical';
+import type { LoroDoc } from 'loro-crdt';
+import { type ElementContainer, type PropValue } from './schema.js';
+import { type TextRun } from './text.js';
+/** A maximal run of adjacent text nodes — the schema's text unit (see `schema.ts`). */
+export interface TargetText {
+    readonly kind: 'text';
+    readonly runs: readonly TextRun[];
+}
+/**
+ * A Lexical element (paragraph/heading/list/…) or a leaf mirrored as an element
+ * (`LineBreakNode`, `LLuiDecoratorNode`) whose payload lives entirely in `props`.
+ */
+export interface TargetElement {
+    readonly kind: 'element';
+    readonly type: string;
+    readonly props: Readonly<Record<string, PropValue>>;
+    readonly children: readonly TargetChild[];
+}
+/** One child of a target element: a text run or a nested element. */
+export type TargetChild = TargetText | TargetElement;
+/**
+ * Project one Lexical element (or element-mirrored leaf) to a {@link TargetElement}.
+ *
+ * MUST be called inside a Lexical read (`editorState.read(() => …)`), because it
+ * reads node content. Uses only `lexical` (a peer dependency) — never
+ * `@lexical/markdown`. See {@link targetFromEditorState} for the common wrapper.
+ */
+export declare function projectTarget(node: LexicalNode): TargetElement;
+/**
+ * Project the root of an `EditorState` to a {@link TargetElement}, doing the read
+ * for you.
+ *
+ * The caller owns the markdown → editor-state parse (its own headless editor and
+ * `@lexical/markdown` transformer set); this projects the parsed tree into the
+ * plain, serializable shape {@link reconcileTargetIntoLoro} consumes. Uses only
+ * `lexical`.
+ */
+export declare function targetFromEditorState(state: EditorState): TargetElement;
+/**
+ * Commit origin stamped on the single agent-write commit.
+ *
+ * Distinct from `to-loro.ts`'s `OUTBOUND_ORIGIN` so the inbound path can tell an
+ * agent write apart from an echo of its own outbound write: `binding.ts` lists
+ * this origin among the LOCAL batches the inbound path must still APPLY, which is
+ * what bounces an agent write into a live editor (preserving `NodeKey`s and
+ * decorator mounts).
+ */
+export declare const AGENT_WRITE_ORIGIN = "agent-write";
+/**
+ * Reconcile a parsed target tree into an existing Loro document, preserving the
+ * `ContainerID`s of unchanged and text-edited blocks, and commit under `origin`.
+ *
+ * A SIBLING to `syncLexicalToLoro` — it writes Loro directly rather than mirroring
+ * a Lexical update, matches by CONTENT rather than by `NodeKey`, and does NOT
+ * consult the `ContainerNodeMap` (which self-heals on the inbound bounce).
+ *
+ * @param doc    the shared document.
+ * @param root   its root element container, as returned by `initDoc`.
+ * @param target the desired tree, from {@link targetFromEditorState} /
+ *               {@link projectTarget} (the caller owns the markdown parse).
+ * @param origin the commit origin. Defaults to {@link AGENT_WRITE_ORIGIN}; keep
+ *               it on the inbound target's applied-local-origins list, or a live
+ *               editor bound to the same doc will not see the change.
+ * @returns the number of Loro write ops emitted. `0` means the target already
+ *          matched the document — nothing committed, no peer sees an event.
+ */
+export declare function reconcileTargetIntoLoro(doc: LoroDoc, root: ElementContainer, target: TargetElement, origin?: string): number;
+//# sourceMappingURL=agent-write.d.ts.map

package/dist/agent-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-write.d.ts","sourceRoot":"","sources":["../src/agent-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAIL,KAAK,WAAW,EAEhB,KAAK,WAAW,EAEjB,MAAM,SAAS,CAAA;AAChB,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,WAAW,CAAA;AAGlD,OAAO,EAcL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACf,MAAM,aAAa,CAAA;AACpB,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,WAAW,CAAA;AAMlB,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAA;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,aAAa,CAAA;AA4CpD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,CAwB9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAQvE;AAkPD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,gBAAgB,CAAA;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,aAAa,EACrB,MAAM,GAAE,MAA2B,GAClC,MAAM,CAKR"}