@datalayer/lexical-loro 1.0.2 → 1.0.5

package/lib/collab/loro/sync/SyncCursors.js

@@ -0,0 +1,501 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getNodeByKey, $getSelection, $isElementNode, $isLineBreakNode, $isRangeSelection, $isTextNode, } from 'lexical';
+import { createDOMRange, createRectsFromDOMRange } from '@lexical/selection';
+function getDisplayNameFromAwareness(awareness) {
+    const awarenessData = awareness.awarenessData;
+    if (!awarenessData || typeof awarenessData !== 'object') {
+        return awareness.name;
+    }
+    const data = awarenessData;
+    const user = data.user;
+    const userRecord = user && typeof user === 'object' ? user : undefined;
+    const candidates = [
+        userRecord?.display_name,
+        userRecord?.displayName,
+        userRecord?.name,
+        userRecord?.username,
+        userRecord?.handle,
+        data.display_name,
+        data.displayName,
+        data.name,
+        data.username,
+        data.handle,
+        awareness.name,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0) {
+            return candidate;
+        }
+    }
+    return awareness.name;
+}
+/*****************************************************************************/
+// Helper function to find Loro tree node for a Lexical NodeKey (read-only lookup)
+function findLoroTreeNodeForLexicalKey(nodeKey, binding) {
+    try {
+        const nodeMapper = binding.nodeMapper;
+        const treeId = nodeMapper.getTreeIDByLexicalKey(nodeKey);
+        if (!treeId) {
+            return null;
+        }
+        const tree = binding.tree;
+        if (tree.has(treeId)) {
+            return tree.getNodeByID(treeId) || null;
+        }
+        return null;
+    }
+    catch (error) {
+        console.warn('Failed to find Loro tree node for Lexical key:', nodeKey, error);
+        return null;
+    }
+}
+// Helper function to convert a Lexical Point to a Loro Cursor.
+// The cursor data uses TreeIDs (stable across all clients) instead of NodeKeys
+// (local to each editor instance) to ensure correct cross-client resolution.
+function convertLexicalPointToCursor(point, binding) {
+    try {
+        const node = $getNodeByKey(point.key);
+        if (!node) {
+            return null;
+        }
+        const nodeMapper = binding.nodeMapper;
+        // --- Text node ---
+        if ($isTextNode(node)) {
+            const treeId = nodeMapper.getTreeIDByLexicalKey(point.key);
+            if (!treeId) {
+                return null;
+            }
+            const textContent = node.getTextContent();
+            const offset = Math.min(point.offset, textContent.length);
+            return {
+                treeId,
+                offset,
+                pointType: 'text',
+            };
+        }
+        // --- Element node (paragraphs, headings, table cells, …) ---
+        if ($isElementNode(node)) {
+            const children = node.getChildren();
+            if (children.length === 0) {
+                // Empty element (e.g. freshly-created paragraph after Enter)
+                const treeId = nodeMapper.getTreeIDByLexicalKey(point.key);
+                if (!treeId)
+                    return null;
+                return { treeId, offset: point.offset, pointType: 'element' };
+            }
+            // Try to resolve the child at `point.offset`
+            if (point.offset < children.length) {
+                const child = children[point.offset];
+                if (child) {
+                    const childTreeId = nodeMapper.getTreeIDByLexicalKey(child.getKey());
+                    if (childTreeId) {
+                        return {
+                            treeId: childTreeId,
+                            offset: 0,
+                            pointType: $isTextNode(child) ? 'text' : 'element',
+                        };
+                    }
+                }
+            }
+            // Fallback: cursor is at/past the end of this element's children
+            const treeId = nodeMapper.getTreeIDByLexicalKey(point.key);
+            if (!treeId)
+                return null;
+            return { treeId, offset: point.offset, pointType: 'element' };
+        }
+        // --- Any other node type (decorator, linebreak, …) ---
+        const treeId = nodeMapper.getTreeIDByLexicalKey(point.key);
+        if (!treeId)
+            return null;
+        return { treeId, offset: point.offset, pointType: 'element' };
+    }
+    catch (error) {
+        console.warn('Failed to convert Lexical point to Loro cursor:', error);
+        return null;
+    }
+}
+// Helper function to convert Loro cursor data back to Lexical selection.
+// Always resolves via TreeID → NodeMapper → local NodeKey.
+// NodeKeys are never transmitted between clients because they are
+// editor-instance-local and would map to wrong nodes on the remote side.
+function convertLoroSelectionToLexical(anchorCursor, focusCursor, binding) {
+    try {
+        if (!anchorCursor || !focusCursor) {
+            return null;
+        }
+        const anchor = anchorCursor;
+        const focus = focusCursor;
+        const nodeMapper = binding.nodeMapper;
+        let anchorKey = null;
+        let focusKey = null;
+        if (anchor.treeId) {
+            anchorKey = nodeMapper.getLexicalKeyByLoroId(anchor.treeId);
+        }
+        if (focus.treeId) {
+            focusKey = nodeMapper.getLexicalKeyByLoroId(focus.treeId);
+        }
+        if (!anchorKey || !focusKey) {
+            // Mapping not yet available — tree operations may not have arrived yet.
+            // Cursors will be re-synced after the next tree integration.
+            return null;
+        }
+        return {
+            anchorKey,
+            anchorOffset: anchor.offset || 0,
+            focusKey,
+            focusOffset: focus.offset || 0,
+        };
+    }
+    catch (error) {
+        console.warn('Failed to convert Loro cursors to Lexical selection:', error);
+        return null;
+    }
+}
+// Helper function to set a point in Lexical selection
+function $setPoint(point, key, offset) {
+    if (point.key !== key || point.offset !== offset) {
+        let anchorNode = $getNodeByKey(key);
+        if (anchorNode !== null &&
+            !$isElementNode(anchorNode) &&
+            !$isTextNode(anchorNode)) {
+            const parent = anchorNode.getParentOrThrow();
+            key = parent.getKey();
+            offset = anchorNode.getIndexWithinParent();
+            anchorNode = parent;
+        }
+        point.set(key, offset, $isElementNode(anchorNode) ? 'element' : 'text');
+    }
+}
+// Helper functions for cursor UI management
+function createCollabCursor(name, color) {
+    return {
+        color: color,
+        name: name,
+        selection: null,
+    };
+}
+function createCursorSelection(cursor, anchorKey, anchorOffset, focusKey, focusOffset, isCurrentUser = false) {
+    const color = cursor.color;
+    const caretColor = color;
+    const nameBackgroundColor = color;
+    const caret = document.createElement('span');
+    caret.style.cssText = `position:absolute;top:0;bottom:0;right:-1px;width:2px;background-color:${caretColor};z-index:10;${isCurrentUser ? 'opacity:0.8;' : ''}`;
+    const name = document.createElement('span');
+    name.textContent = cursor.name;
+    name.style.cssText = `position:absolute;left:-2px;top:-16px;background-color:${nameBackgroundColor};color:#fff;line-height:12px;font-size:12px;padding:2px;font-family:Arial;font-weight:bold;white-space:nowrap;${isCurrentUser ? 'opacity:0.9;' : ''}`;
+    caret.appendChild(name);
+    return {
+        anchor: { key: anchorKey, offset: anchorOffset },
+        focus: { key: focusKey, offset: focusOffset },
+        caret,
+        color: cursor.color,
+        name,
+        selections: [],
+    };
+}
+function destroyCursor(binding, cursor) {
+    const selection = cursor.selection;
+    if (selection !== null) {
+        destroySelection(binding, selection);
+        cursor.selection = null;
+    }
+}
+function destroySelection(binding, selection) {
+    const cursorsContainer = binding.cursorsContainer;
+    if (cursorsContainer !== null) {
+        const selections = selection.selections;
+        const selectionsLength = selections.length;
+        for (let i = 0; i < selectionsLength; i++) {
+            cursorsContainer.removeChild(selections[i]);
+        }
+    }
+}
+/*****************************************************************************/
+export function syncCursorPositions(binding, provider, options) {
+    const { getAwarenessStates = getAwarenessStatesDefault } = options ?? {};
+    const awarenessStates = Array.from(getAwarenessStates(binding, provider));
+    const localClientID = binding.clientID;
+    const cursors = binding.cursors;
+    const editor = binding.editor;
+    const nodeMap = editor._editorState._nodeMap;
+    const visitedClientIDs = new Set();
+    // Process all cursor positions from awareness (including local user)
+    for (let i = 0; i < awarenessStates.length; i++) {
+        const awarenessState = awarenessStates[i];
+        const [clientID, awareness] = awarenessState;
+        visitedClientIDs.add(clientID);
+        const { color } = awareness;
+        const displayName = getDisplayNameFromAwareness(awareness);
+        const isCurrentUser = clientID === localClientID;
+        let selection = null;
+        let cursor = cursors.get(clientID);
+        if (cursor === undefined) {
+            // Add "(Me)" label for current user's cursor
+            const cursorName = isCurrentUser ? `${displayName} (Me)` : displayName;
+            cursor = createCollabCursor(cursorName, color);
+            cursors.set(clientID, cursor);
+        }
+        else if (cursor.name !== displayName) {
+            cursor.name = displayName;
+            if (cursor.selection) {
+                cursor.selection.name.textContent = isCurrentUser
+                    ? `${displayName} (Me)`
+                    : displayName;
+            }
+        }
+        // Render cursor/selection whenever valid anchorPos/focusPos exist.
+        // We intentionally do NOT gate on `focusing` because the FOCUS_COMMAND
+        // and selection-update can race — the selection update may broadcast
+        // before FOCUS_COMMAND fires, leaving `focusing: false` even though
+        // the user clearly has the editor focused (they are selecting text).
+        const { anchorPos, focusPos } = awareness;
+        if (anchorPos !== null && focusPos !== null) {
+            const selectionInfo = convertLoroSelectionToLexical(anchorPos, focusPos, binding);
+            if (selectionInfo) {
+                const { anchorKey, anchorOffset, focusKey, focusOffset } = selectionInfo;
+                selection = cursor.selection;
+                if (selection === null) {
+                    selection = createCursorSelection(cursor, anchorKey, anchorOffset, focusKey, focusOffset, isCurrentUser);
+                }
+                else {
+                    // Update existing selection
+                    const anchor = selection.anchor;
+                    const focus = selection.focus;
+                    anchor.key = anchorKey;
+                    anchor.offset = anchorOffset;
+                    focus.key = focusKey;
+                    focus.offset = focusOffset;
+                }
+            }
+        }
+        updateCursor(binding, cursor, selection, nodeMap, isCurrentUser);
+    }
+    // Clean up cursors for clients that are no longer present
+    const allClientIDs = Array.from(cursors.keys());
+    for (let i = 0; i < allClientIDs.length; i++) {
+        const clientID = allClientIDs[i];
+        if (!visitedClientIDs.has(clientID)) {
+            const cursor = cursors.get(clientID);
+            if (cursor !== undefined) {
+                destroyCursor(binding, cursor);
+                cursors.delete(clientID);
+            }
+        }
+    }
+}
+// Default function to get awareness states from provider
+function getAwarenessStatesDefault(binding, provider) {
+    return provider.awareness.getStates();
+}
+// Function to update cursor visualization in the DOM
+function updateCursor(binding, cursor, nextSelection, nodeMap, // LexicalEditor NodeMap type
+isCurrentUser = false) {
+    const editor = binding.editor;
+    const rootElement = editor.getRootElement();
+    const cursorsContainer = binding.cursorsContainer;
+    if (cursorsContainer === null || rootElement === null) {
+        return;
+    }
+    // The cursorsContainer is a position:fixed overlay covering the viewport.
+    // Use its own getBoundingClientRect() as the coordinate reference,
+    // so that absolute children are positioned correctly relative to it.
+    const containerRect = cursorsContainer.getBoundingClientRect();
+    const prevSelection = cursor.selection;
+    if (nextSelection === null) {
+        if (prevSelection === null) {
+            return;
+        }
+        else {
+            cursor.selection = null;
+            destroySelection(binding, prevSelection);
+            return;
+        }
+    }
+    else {
+        cursor.selection = nextSelection;
+    }
+    const caret = nextSelection.caret;
+    const color = nextSelection.color;
+    const selections = nextSelection.selections;
+    const anchor = nextSelection.anchor;
+    const focus = nextSelection.focus;
+    const anchorKey = anchor.key;
+    const focusKey = focus.key;
+    const anchorNode = nodeMap.get(anchorKey);
+    const focusNode = nodeMap.get(focusKey);
+    if (anchorNode == null || focusNode == null) {
+        return;
+    }
+    // Determine if the selection is collapsed (cursor only) or expanded (text selected)
+    const isCollapsed = anchorKey === focusKey && anchor.offset === focus.offset;
+    let selectionRects;
+    // Handle collapsed selection on a linebreak
+    if (anchorNode === focusNode && $isLineBreakNode(anchorNode)) {
+        const brElement = editor.getElementByKey(anchorKey);
+        if (brElement) {
+            const brRect = brElement.getBoundingClientRect();
+            selectionRects = [brRect];
+        }
+        else {
+            selectionRects = [];
+        }
+    }
+    else {
+        const range = createDOMRange(editor, anchorNode, anchor.offset, focusNode, focus.offset);
+        if (range === null) {
+            return;
+        }
+        if (isCollapsed) {
+            // For collapsed cursors, get all rects (including zero-width) to position the caret.
+            // createRectsFromDOMRange filters out rects with width < 1, so use the raw
+            // range rect as a fallback for caret positioning.
+            selectionRects = createRectsFromDOMRange(editor, range);
+            if (selectionRects.length === 0) {
+                // Fallback: use the bounding rect of the collapsed range
+                const boundingRect = range.getBoundingClientRect();
+                if (boundingRect.height > 0) {
+                    selectionRects = [boundingRect];
+                }
+            }
+        }
+        else {
+            selectionRects = createRectsFromDOMRange(editor, range);
+        }
+    }
+    const selectionsLength = selections.length;
+    const selectionRectsLength = selectionRects.length;
+    for (let i = 0; i < selectionRectsLength; i++) {
+        const selectionRect = selectionRects[i];
+        let selection = selections[i];
+        if (selection === undefined) {
+            selection = document.createElement('span');
+            selections[i] = selection;
+            const selectionBg = document.createElement('span');
+            selection.appendChild(selectionBg);
+            cursorsContainer.appendChild(selection);
+        }
+        const top = selectionRect.top - containerRect.top;
+        const left = selectionRect.left - containerRect.left;
+        // For collapsed cursors, give the wrapper a minimum width so the caret
+        // (positioned inside) is not clipped by some browsers.
+        const effectiveWidth = isCollapsed ? Math.max(selectionRect.width, 4) : selectionRect.width;
+        const style = `position:absolute;top:${top}px;left:${left}px;height:${selectionRect.height}px;width:${effectiveWidth}px;pointer-events:none;z-index:10;overflow:visible;`;
+        selection.style.cssText = style;
+        if (isCollapsed) {
+            // Collapsed cursor: hide the background span.
+            selection.firstChild.style.cssText =
+                `position:absolute;left:0;top:0;width:0;height:0;`;
+            // Make the caret clearly visible with explicit height and a bright border-left for contrast.
+            caret.style.cssText = `position:absolute;top:0;left:0;width:2px;height:${selectionRect.height}px;background-color:${color};z-index:10;`;
+        }
+        else if (isCurrentUser) {
+            // Current user's expanded selection: very subtle since the browser already
+            // shows the native selection highlight.
+            selection.firstChild.style.cssText =
+                `position:absolute;left:0;top:0;width:${selectionRect.width}px;height:${selectionRect.height}px;` +
+                    `background-color:${color};opacity:0.08;border-radius:2px;pointer-events:none;`;
+        }
+        else {
+            // Remote user's expanded selection: clearly visible with transparency.
+            // The user's color is shown as a translucent overlay so the text beneath
+            // remains readable.
+            selection.firstChild.style.cssText =
+                `position:absolute;left:0;top:0;width:${selectionRect.width}px;height:${selectionRect.height}px;` +
+                    `background-color:${color};opacity:0.25;border-radius:2px;pointer-events:none;`;
+        }
+        if (i === selectionRectsLength - 1) {
+            if (caret.parentNode !== selection) {
+                selection.appendChild(caret);
+            }
+        }
+    }
+    for (let i = selectionsLength - 1; i >= selectionRectsLength; i--) {
+        const selection = selections[i];
+        cursorsContainer.removeChild(selection);
+        selections.pop();
+    }
+}
+export function syncLexicalSelectionToLoro(binding, provider, prevSelection, nextSelection) {
+    const awareness = provider.awareness;
+    const localState = awareness.getLocalState();
+    if (localState === null) {
+        return;
+    }
+    const { anchorPos: currentAnchorPos, focusPos: currentFocusPos, name, color, focusing, awarenessData, } = localState;
+    let anchorPos = null;
+    let focusPos = null;
+    // Convert Lexical selection to Loro cursors if we have a range selection
+    if ($isRangeSelection(nextSelection)) {
+        anchorPos = convertLexicalPointToCursor(nextSelection.anchor, binding);
+        focusPos = convertLexicalPointToCursor(nextSelection.focus, binding);
+    }
+    else if (nextSelection === null) {
+        // Selection cleared — broadcast null positions
+    }
+    else {
+        // Not a range selection (e.g. NodeSelection) — skip
+        return;
+    }
+    // Always broadcast to keep remote cursors in sync.
+    // The shouldUpdatePosition check prevents redundant updates for unchanged positions.
+    const shouldUpdate = shouldUpdatePosition(currentAnchorPos, anchorPos) ||
+        shouldUpdatePosition(currentFocusPos, focusPos);
+    if (!shouldUpdate) {
+        return;
+    }
+    // When we have a valid selection to broadcast, the editor IS focused —
+    // force `focusing: true` to prevent the FOCUS_COMMAND race condition
+    // where the selection update fires before FOCUS_COMMAND sets the flag.
+    const effectiveFocusing = (anchorPos !== null && focusPos !== null) ? true : focusing;
+    // Update the local state in EphemeralStore via awareness
+    awareness.setLocalState({
+        ...localState,
+        anchorPos,
+        awarenessData,
+        color,
+        focusPos,
+        focusing: effectiveFocusing,
+        name,
+    });
+}
+// Helper function to determine if cursor position should be updated
+function shouldUpdatePosition(currentPos, pos) {
+    if (currentPos == null) {
+        return pos != null;
+    }
+    else if (pos == null) {
+        return true;
+    }
+    else {
+        // Compare using treeId (stable across clients) and offset
+        const current = currentPos;
+        const next = pos;
+        return current.treeId !== next.treeId || current.offset !== next.offset || current.pointType !== next.pointType;
+    }
+}
+/*****************************************************************************/
+export function $syncLocalCursorPosition(binding, provider) {
+    const awareness = provider.awareness;
+    const localState = awareness.getLocalState();
+    if (localState === null) {
+        return;
+    }
+    const { anchorPos, focusPos } = localState;
+    // Convert Loro cursors back to Lexical selection
+    if (anchorPos !== null && focusPos !== null) {
+        const selectionInfo = convertLoroSelectionToLexical(anchorPos, focusPos, binding);
+        if (selectionInfo) {
+            const { anchorKey, anchorOffset, focusKey, focusOffset } = selectionInfo;
+            const selection = $getSelection();
+            if (!$isRangeSelection(selection)) {
+                return;
+            }
+            // Update the Lexical selection to match the cursor positions
+            $setPoint(selection.anchor, anchorKey, anchorOffset);
+            $setPoint(selection.focus, focusKey, focusOffset);
+        }
+    }
+}

package/lib/collab/loro/sync/SyncLexicalToLoro.d.ts

@@ -0,0 +1,4 @@
+import { UpdateListenerPayload } from 'lexical';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+export declare function syncLexicalToLoro(binding: Binding, provider: Provider, update: UpdateListenerPayload): void;

package/lib/collab/loro/sync/SyncLexicalToLoro.js

@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { RootNode, ElementNode, TextNode, LineBreakNode, DecoratorNode, $getSelection, $getNodeByKey } from 'lexical';
+import { propagateRootNode } from '../propagators/RootNodePropagator';
+import { propagateLineBreakNode } from '../propagators/LineBreakNodePropagator';
+import { propagateElementNode } from '../propagators/ElementNodePropagator';
+import { propagateTextNode } from '../propagators/TextNodePropagator';
+import { propagateDecoratorNode } from '../propagators/DecoratorNodePropagator';
+import { isClassExtending, generateClientID } from '../utils/Utils';
+import { syncLexicalSelectionToLoro } from './SyncCursors';
+// import { scheduleAsyncCommit } from '../Bindings';
+// import { syncCursorPositions, SyncCursorPositionsFn } from './SyncCursors';
+export function syncLexicalToLoro(binding, provider, update) {
+    const { mutatedNodes, prevEditorState, editorState: currEditorState, } = update;
+    let __seedDebugMutationCount = 0;
+    if (mutatedNodes) {
+        mutatedNodes.forEach((nodeMap) => {
+            __seedDebugMutationCount += nodeMap.size;
+        });
+    }
+    console.log('[SEED-DEBUG] syncLexicalToLoro: mutatedNodes=', mutatedNodes ? 'map' : 'null', 'totalMutations=', __seedDebugMutationCount, 'tags=', Array.from(update.tags));
+    // Process node mutations if present.
+    // NOTE: mutatedNodes is null for selection-only updates (no DOM mutations).
+    // See Lexical docs: "Will be null if no DOM was mutated, such as when only
+    // the selection changed."
+    if (mutatedNodes) {
+        const tree = binding.tree;
+        // Ensure we have a numeric peerId for TreeID format
+        const peerId = generateClientID(binding.doc);
+        // Create options object for mutators
+        const mutatorOptions = {
+            binding,
+            tree,
+            peerId
+        };
+        // Process mutations in proper dependency order:
+        // 1. RootNode first
+        // 2. ElementNodes sorted by tree depth (parents before children)
+        // 3. TextNodes, LineBreakNodes, DecoratorNodes (leaf children)
+        //
+        // Depth sorting is critical: when a table is inserted, the mutations for
+        // table, tablerow, tablecell, and paragraph-inside-cell ALL fire in the
+        // same update. Without sorting, a tablecell may be propagated before its
+        // parent tablerow — causing `getTreeIDByLexicalKey(parent)` to return
+        // undefined and the cell to be created at the Loro tree root.
+        // Check if any nodes actually mutated (Map could be empty for selection-only changes)
+        let hasMutations = false;
+        mutatedNodes.forEach((nodeMap) => {
+            if (nodeMap.size > 0)
+                hasMutations = true;
+        });
+        if (hasMutations) {
+            // Phase 1: Process RootNode mutations
+            mutatedNodes.forEach((nodeMap, Klass) => {
+                if (isClassExtending(Klass, RootNode)) {
+                    nodeMap.forEach((mutation, nodeKey) => {
+                        propagateRootNode(update, mutation, nodeKey, mutatorOptions);
+                    });
+                }
+            });
+            const collected = [];
+            mutatedNodes.forEach((nodeMap, Klass) => {
+                let category = null;
+                if (isClassExtending(Klass, RootNode)) {
+                    return; // handled in Phase 1
+                }
+                else if (isClassExtending(Klass, ElementNode)) {
+                    category = 'element';
+                }
+                else if (isClassExtending(Klass, TextNode)) {
+                    category = 'text';
+                }
+                else if (isClassExtending(Klass, LineBreakNode)) {
+                    category = 'linebreak';
+                }
+                else if (isClassExtending(Klass, DecoratorNode)) {
+                    category = 'decorator';
+                }
+                if (category === null) {
+                    return;
+                }
+                const resolvedCategory = category;
+                nodeMap.forEach((mutation, nodeKey) => {
+                    // Compute depth (root=0, paragraph=1, inline element=2, …) and the
+                    // node's index within its parent from the current editor state.
+                    let depth = 0;
+                    let index = 0;
+                    currEditorState.read(() => {
+                        const node = $getNodeByKey(nodeKey);
+                        if (node) {
+                            index = node.getIndexWithinParent();
+                            let current = node.getParent();
+                            while (current) {
+                                depth++;
+                                current = current.getParent();
+                            }
+                        }
+                    });
+                    collected.push({ mutation, nodeKey, depth, index, category: resolvedCategory });
+                });
+            });
+            const dispatch = (info) => {
+                switch (info.category) {
+                    case 'element':
+                        propagateElementNode(update, info.mutation, info.nodeKey, mutatorOptions);
+                        break;
+                    case 'text':
+                        propagateTextNode(update, info.mutation, info.nodeKey, mutatorOptions);
+                        break;
+                    case 'linebreak':
+                        propagateLineBreakNode(update, info.mutation, info.nodeKey, mutatorOptions);
+                        break;
+                    case 'decorator':
+                        propagateDecoratorNode(update, info.mutation, info.nodeKey, mutatorOptions);
+                        break;
+                }
+            };
+            // Destroys first, deepest-first (children before parents), to avoid
+            // re-create/update races during bulk deletes.
+            collected
+                .filter(m => m.mutation === 'destroyed')
+                .sort((a, b) => b.depth - a.depth)
+                .forEach(dispatch);
+            // Creates next, shallow-first then ascending sibling index (see rationale
+            // above) so every Loro insertion index stays within range.
+            collected
+                .filter(m => m.mutation === 'created')
+                .sort((a, b) => a.depth - b.depth || a.index - b.index)
+                .forEach(dispatch);
+            // Updates last, parents-first for determinism. Updates never call
+            // createLoroNode (the mapping already exists) so their order is not
+            // index-sensitive.
+            collected
+                .filter(m => m.mutation === 'updated')
+                .sort((a, b) => a.depth - b.depth || a.index - b.index)
+                .forEach(dispatch);
+            // Commit only when there were actual node mutations (not selection-only changes)
+            binding.doc.commit({ origin: binding.doc.peerIdStr });
+        }
+    }
+    // Always sync selection/cursor state — even for selection-only changes
+    // (e.g. user clicks or drags to select text without editing).
+    // This MUST be outside the `if (mutatedNodes)` block because Lexical sets
+    // mutatedNodes to null when only the selection changed (no DOM mutations).
+    currEditorState.read(() => {
+        const selection = $getSelection();
+        const prevSelection = prevEditorState._selection;
+        syncLexicalSelectionToLoro(binding, provider, prevSelection, selection);
+    });
+}

package/lib/collab/loro/sync/SyncLoroToLexical.d.ts

@@ -0,0 +1,5 @@
+import { LoroEventBatch } from 'loro-crdt';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+import { SyncCursorPositionsFn } from './SyncCursors';
+export declare function syncLoroToLexical(binding: Binding, provider: Provider, eventBatch: LoroEventBatch, isFromUndoManger: boolean, syncCursorPositionsFn?: SyncCursorPositionsFn): void;