@llui/lexical-loro 0.1.0

package/dist/to-loro.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Outbound sync: a Lexical `EditorState` → the Loro mirror.
+ *
+ * ── What this must get right ───────────────────────────────────────────────
+ *
+ * Converging is the easy half. The hard requirement is emitting a MINIMAL,
+ * IDENTITY-PRESERVING op set, because in this stack a container that is
+ * recreated instead of updated has visible, expensive consequences:
+ *
+ *  - a recreated `LoroText` discards a peer's concurrent insertion into it;
+ *  - a recreated element `LoroMap` mints a new `ContainerID`, which (via the
+ *    registry in `mapping.ts`) forces the peer's whole subtree to be rebuilt
+ *    with fresh `NodeKey`s — tearing down every mounted `LLuiDecoratorNode`
+ *    sub-app in it (`packages/lexical/src/decorator.ts` disposes on the
+ *    'destroyed' mutation) along with selection and IME state.
+ *
+ * So: a reorder emits ONE `pos` register write per displaced block (never a
+ * delete+recreate — see `order.ts` and the schema header), text edits emit a
+ * cursor-biased single-region diff, and format changes emit explicit per-format
+ * `mark`/`unmark` ops. Every function here returns the number of writes it made,
+ * and `syncLexicalToLoro` returns the total — the tests assert on it, which is
+ * how a regression in the pruning shows up as a failure rather than as a
+ * silently slower, mount-destroying binding.
+ *
+ * ── Pruning: what is actually sound in Lexical ─────────────────────────────
+ *
+ * loro-prosemirror prunes with reference equality because ProseMirror's tree is
+ * PERSISTENT: changing a leaf rebuilds every ancestor, so `parent === parent`
+ * really does mean "this whole subtree is unchanged".
+ *
+ * LEXICAL IS NOT LIKE THAT, and assuming it is produces permanently stale
+ * remote documents. `getWritable()` (`LexicalNode.ts`) clones ONLY the node
+ * being written; ancestors are left alone and merely recorded in
+ * `dirtyElements` by `internalMarkParentElementsAsDirty` (`LexicalUtils.ts`).
+ * A paragraph whose text node was just rewritten is therefore the SAME object
+ * in both editor states. Reference equality prunes a subtree in ProseMirror; in
+ * Lexical it proves only that the node's OWN properties and its OWN child list
+ * are unchanged.
+ *
+ * This module therefore uses two different, individually sound facts:
+ *
+ *  1. `prevNodeMap.get(key) === node` ⟹ this node's props and the identity and
+ *     order of its children are unchanged. Used to skip the prop diff and the
+ *     whole children RECONCILIATION (matching, deletes, moves, inserts) and
+ *     descend positionally instead. Sound because any child list change goes
+ *     through the parent's `getWritable()`.
+ *  2. `dirtyElements ∪ dirtyLeaves` contains every changed node AND every
+ *     ancestor of one. Used to decide which children to descend into at all.
+ *     Sound because `internalMarkNodeAsDirty` walks the parent chain to the
+ *     root.
+ *
+ * Fact 2 only holds when a dirty walk actually ran. `editor.setEditorState()`
+ * — which Lexical's own history uses for undo/redo, and which the LLui host
+ * push path uses — swaps the state wholesale with EMPTY dirty sets while
+ * potentially SHARING node objects with the previous state. Trusting empty
+ * dirty sets there would silently sync nothing. So when both sets are empty the
+ * dirty gate is dropped entirely and the walk falls back to a full structural
+ * diff against Loro, which is correct regardless of provenance and costs only
+ * on that rare path. Combined, a keystroke costs O(tree depth); a wholesale
+ * state swap costs O(document) and still emits only the ops that differ.
+ *
+ * ── Echo suppression ───────────────────────────────────────────────────────
+ *
+ * This is layer (b) of the three: an update we ourselves wrote back into
+ * Lexical carries `COLLABORATION_TAG` and must not bounce back out. See
+ * `index.ts` for the full three-layer contract — in particular that this
+ * binding must NEVER emit `PROGRAMMATIC_TAG`.
+ *
+ * `HISTORIC_TAG` is deliberately NOT suppressed, and must stay that way — even
+ * though this binding DOES ship CRDT-aware undo. The reason it can be left
+ * unsuppressed is that the Loro undo owner (`undo.ts`) never routes through
+ * Lexical's history: `manager.undo()` mutates the shared document directly, and
+ * the resulting writeback into the editor carries `COLLABORATION_TAG` (echo
+ * layer b), not `HISTORIC_TAG`. So the CRDT undo path emits no historic update
+ * for this module to see. `lexicalForeign` also forces `@lexical/history` off
+ * whenever `externalUndo` is present, so a shipped app produces no `HISTORIC_TAG`
+ * update at all. Suppressing it here would be inert in that configuration and
+ * actively WRONG for a host that deliberately runs `@lexical/history` without an
+ * `externalUndo` owner (as `test/harden.test.ts` does): there a historic update
+ * is a genuine local edit no peer has seen, and dropping it would make that
+ * undo invisible to everyone else. This differs from `@lexical/yjs`, where undo
+ * IS a historic writeback of the CRDT's own and re-syncing it would echo.
+ */
+import { type EditorState, type UpdateListenerPayload } from 'lexical';
+import { type LoroDoc } from 'loro-crdt';
+import { ContainerNodeMap } from './mapping.js';
+import { type ElementContainer } from './schema.js';
+/** Commit origin stamped on every write this module makes. */
+export declare const OUTBOUND_ORIGIN = "lexical-loro";
+/**
+ * Update tags that mean "this update did not originate with the local user, do
+ * not mirror it".
+ *
+ * `COLLABORATION_TAG` is our own inbound writeback (echo layer b);
+ * `SKIP_COLLAB_TAG` is Lexical's standard opt-out, which hosts use for local-only
+ * decoration. `HISTORIC_TAG` is NOT here — see the file header.
+ */
+export declare const OUTBOUND_SKIP_TAGS: readonly string[];
+/** The Loro side of the binding: the document, its root mirror, and the registry. */
+export interface OutboundTarget {
+    readonly doc: LoroDoc;
+    /** The root element container, as returned by `initDoc`. */
+    readonly root: ElementContainer;
+    /** The ContainerID ↔ NodeKey registry, owned by the binding and mutated here. */
+    readonly mapping: ContainerNodeMap;
+    /** Commit origin. Defaults to {@link OUTBOUND_ORIGIN}. */
+    readonly origin?: string;
+    /** Tags that suppress the sync. Defaults to {@link OUTBOUND_SKIP_TAGS}. */
+    readonly skipTags?: readonly string[];
+}
+/**
+ * The slice of `UpdateListenerPayload` this direction consumes. Declared as a
+ * `Pick` so an update listener can pass its payload straight through.
+ *
+ * Register it with a BLOCK body, never an expression body:
+ *
+ * ```ts
+ * editor.registerUpdateListener((payload) => {
+ *   syncLexicalToLoro(target, payload)
+ * })
+ * ```
+ *
+ * Lexical 0.48 stores whatever an update listener RETURNS and calls it as a
+ * cleanup before the next invocation (`triggerListeners` in `LexicalUpdates`),
+ * so the concise `(payload) => syncLexicalToLoro(target, payload)` hands it this
+ * function's op count and the second update dies with
+ * "unregister is not a function".
+ */
+export type OutboundUpdate = Pick<UpdateListenerPayload, 'prevEditorState' | 'editorState' | 'dirtyElements' | 'dirtyLeaves' | 'normalizedNodes' | 'tags'>;
+/**
+ * Mirror one Lexical update into the Loro document and commit it.
+ *
+ * @returns the number of Loro write operations emitted. `0` means the update
+ * was a genuine no-op for the shared document — nothing was committed, so no
+ * peer sees an event. Tests assert on this to catch pruning regressions.
+ */
+export declare function syncLexicalToLoro(target: OutboundTarget, update: OutboundUpdate): number;
+/**
+ * Fill the Loro document from an editor state with no previous state to diff
+ * against — the bootstrapping peer's initial seed.
+ *
+ * Structurally a full-fidelity diff, so it is also idempotent: seeding a
+ * document that already matches emits nothing and returns `0`.
+ */
+export declare function seedLoroFromLexical(target: OutboundTarget, editorState: EditorState): number;
+/**
+ * The indices of a longest strictly-increasing subsequence of `values`.
+ *
+ * Patience sorting with a predecessor chain: O(n log n). Exported because it is
+ * the part of the reorder planner worth testing in isolation — the number of
+ * `pos` writes a drag-reorder costs is exactly `matched.length - lis.length`.
+ */
+export declare function longestIncreasingSubsequence(values: readonly number[]): number[];
+//# sourceMappingURL=to-loro.d.ts.map

package/dist/to-loro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-loro.d.ts","sourceRoot":"","sources":["../src/to-loro.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,EAQL,KAAK,WAAW,EAMhB,KAAK,qBAAqB,EAC3B,MAAM,SAAS,CAAA;AAChB,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,WAAW,CAAA;AAEpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAgBL,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAA;AAgBpB,8DAA8D;AAC9D,eAAO,MAAM,eAAe,iBAAiB,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAyC,CAAA;AAEzF,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,qBAAqB,EACrB,iBAAiB,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,iBAAiB,GAAG,MAAM,CACjG,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAoBxF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,MAAM,CAE5F;AAqjBD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CA0BhF"}