@datalayer/lexical-loro 1.0.2 → 1.0.5

package/lib/collab/loro/integrators/MapIntegrator.js

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getNodeByKey, $isDecoratorNode } from 'lexical';
+import { $diffTextContentAndApplyDelta } from '../utils/Utils';
+/**
+ * Handles map data changes (node properties, metadata updates)
+ */
+export class MapIntegrator {
+    integrate(diff, binding, provider) {
+        // Handle updated properties
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdate(key, value, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    // Enhanced integrate method with TreeID context
+    integrateWithContext(diff, treeId, binding, provider) {
+        this.integrateWithContextInternal(diff, treeId, binding, provider);
+    }
+    // Internal method for use when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        // Handle updated properties
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdate(key, value, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    // Internal method for use when already inside editor.update() with context
+    integrateWithContextInternal(diff, treeId, binding, provider) {
+        // Handle updated properties with TreeID context
+        if (diff.updated) {
+            Object.entries(diff.updated).forEach(([key, value]) => {
+                this.integratePropertyUpdateWithContextInternal(key, value, treeId, binding, provider);
+            });
+        }
+        // Handle deleted properties
+        if (diff.deleted) {
+            diff.deleted.forEach((key) => {
+                this.integratePropertyDelete(key, binding, provider);
+            });
+        }
+    }
+    integratePropertyUpdateWithContext(key, value, treeId, binding, provider) {
+        // Handle specific property updates with TreeID context
+        switch (key) {
+            case 'lexical':
+                this.integrateLexicalDataUpdateWithContext(value, treeId, binding);
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+            //
+        }
+    }
+    // Internal version for use when already inside editor.update()
+    integratePropertyUpdateWithContextInternal(key, value, treeId, binding, provider) {
+        // Handle specific property updates with TreeID context
+        switch (key) {
+            case 'lexical':
+                // Extract TreeID and call internal method directly (already inside editor.update())
+                let actualTreeID = treeId;
+                if (typeof treeId === 'string' && treeId.startsWith('cid:')) {
+                    const parts = treeId.split(':');
+                    if (parts.length >= 3) {
+                        actualTreeID = parts[1];
+                    }
+                }
+                const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(actualTreeID);
+                if (lexicalKey) {
+                    this.integrateLexicalDataUpdateInternal(value, lexicalKey, actualTreeID, binding);
+                }
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+                // Generic property update with context
+                break;
+        }
+    }
+    integratePropertyUpdate(key, value, binding, provider) {
+        // Handle specific property updates
+        switch (key) {
+            case 'lexical':
+                // Use targeted update only - the broad heuristic causes scrambling
+                break;
+            case 'textContent':
+                // Text content updates should be integrated via lexical data updates
+                break;
+            case 'elementType':
+                // Element type changes are rare, mostly for debugging
+                break;
+            default:
+                // Generic property update
+                break;
+        }
+    }
+    integratePropertyDelete(key, binding, provider) {
+        // Handle specific property deletions
+        switch (key) {
+            case 'lexical':
+                break;
+            default:
+                // Generic property deleted
+                break;
+        }
+    }
+    integrateLexicalDataUpdateWithContext(lexicalData, treeId, binding) {
+        // Extract the actual TreeID from container ID format
+        // Container ID format: "cid:6@7648424808278730813:Map"
+        // TreeID format: "6@7648424808278730813"
+        let actualTreeID = treeId;
+        if (typeof treeId === 'string' && treeId.startsWith('cid:')) {
+            const parts = treeId.split(':');
+            if (parts.length >= 3) {
+                actualTreeID = parts[1]; // Extract "6@7648424808278730813" from "cid:6@7648424808278730813:Map"
+            }
+        }
+        // Use the TreeID to find the specific Lexical node
+        const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(actualTreeID);
+        if (!lexicalKey) {
+            return;
+        }
+        if (lexicalData && typeof lexicalData === 'object') {
+            binding.editor.update(() => {
+                this.integrateLexicalDataUpdateInternal(lexicalData, lexicalKey, actualTreeID, binding);
+            });
+        }
+    }
+    // Internal method for use when already inside editor.update()
+    integrateLexicalDataUpdateInternal(lexicalData, lexicalKey, treeId, binding) {
+        // Handle Loro container objects that need conversion to plain JS
+        let data = lexicalData;
+        if (data && typeof data === 'object' && typeof data.toJSON === 'function') {
+            data = data.toJSON();
+        }
+        const targetNode = $getNodeByKey(lexicalKey);
+        if (!targetNode) {
+            return;
+        }
+        const targetType = targetNode.getType();
+        const textContent = data.__text || data.text || data.textContent;
+        if (targetType === 'text' && textContent !== undefined) {
+            // Text nodes: use diff approach to preserve cursor position
+            const textNode = targetNode;
+            const currentText = textNode.getTextContent();
+            if (currentText !== textContent) {
+                $diffTextContentAndApplyDelta(textNode, lexicalKey, currentText, textContent);
+            }
+            // Apply text-specific properties
+            if (data.format !== undefined) {
+                textNode.setFormat(data.format);
+            }
+            if (data.style !== undefined) {
+                textNode.setStyle(data.style);
+            }
+        }
+        else if ($isDecoratorNode(targetNode)) {
+            // Decorator nodes (excalidraw, images, counters, JupyterCellNode, …):
+            // Many decorator implementations do NOT override `updateFromJSON` for
+            // their custom properties — they only set them in the constructor via
+            // `importJSON`.  Since decorators are leaf nodes (no children), it is
+            // safe to replace the whole node with a fresh `importJSON` instance.
+            try {
+                const registeredNodes = binding.editor._nodes;
+                const nodeInfo = registeredNodes.get(targetType);
+                if (!nodeInfo) {
+                    console.warn(` MapIntegrator: Node type '${targetType}' not registered`);
+                    return;
+                }
+                const serializedData = { ...data };
+                if (!serializedData.type)
+                    serializedData.type = targetType;
+                if (serializedData.version === undefined)
+                    serializedData.version = 1;
+                if (!('children' in serializedData))
+                    serializedData.children = [];
+                const newNode = nodeInfo.klass.importJSON(serializedData);
+                targetNode.replace(newNode);
+                // Update bidirectional mapping: old key → remove, new key → treeId
+                // Use removeMappingForKey (not deleteMapping) because we are on the
+                // integration side — the Loro tree node must NOT be deleted; we are
+                // only swapping which Lexical key points to it.
+                binding.nodeMapper.removeMappingForKey(lexicalKey);
+                binding.nodeMapper.setMapping(newNode.getKey(), treeId);
+            }
+            catch (error) {
+                console.warn(` MapIntegrator: importJSON+replace failed for decorator ${targetType} node ${lexicalKey}:`, error);
+            }
+        }
+        else {
+            try {
+                const serializedData = { ...data };
+                if (!serializedData.type) {
+                    serializedData.type = targetType;
+                }
+                if (serializedData.version === undefined) {
+                    serializedData.version = 1;
+                }
+                // Provide empty children (TreeIntegrator manages children separately)
+                if (!('children' in serializedData)) {
+                    serializedData.children = [];
+                }
+                const writable = targetNode.getWritable();
+                writable.updateFromJSON(serializedData);
+            }
+            catch (error) {
+                console.warn(` MapIntegrator: updateFromJSON failed for ${targetType} node ${lexicalKey}:`, error);
+            }
+        }
+    }
+}

package/lib/collab/loro/integrators/TextIntegrator.d.ts

@@ -0,0 +1,25 @@
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface TextDiff {
+    type: 'text';
+    diff?: Array<{
+        type: 'insert' | 'delete' | 'retain';
+        index?: number;
+        length?: number;
+        value?: string;
+        attributes?: any;
+    }>;
+}
+/**
+ * Handles text changes (character insertions, deletions, formatting)
+ */
+export declare class TextIntegrator implements BaseIntegrator<TextDiff> {
+    integrate(diff: TextDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: TextDiff, binding: Binding, provider: Provider): void;
+    private integrateTextInsert;
+    private integrateTextDelete;
+    private integrateTextRetain;
+    private applyTextFormatting;
+}
+export {};

package/lib/collab/loro/integrators/TextIntegrator.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+/**
+ * Handles text changes (character insertions, deletions, formatting)
+ */
+export class TextIntegrator {
+    integrate(diff, binding, provider) {
+        this.integrateInternal(diff, binding, provider);
+    }
+    // Internal method for use when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        if (diff.diff) {
+            diff.diff.forEach((change) => {
+                switch (change.type) {
+                    case 'insert':
+                        this.integrateTextInsert(change, binding, provider);
+                        break;
+                    case 'delete':
+                        this.integrateTextDelete(change, binding, provider);
+                        break;
+                    case 'retain':
+                        this.integrateTextRetain(change, binding, provider);
+                        break;
+                    default:
+                        console.warn(` Unknown text change type: ${change.type}`);
+                }
+            });
+        }
+    }
+    integrateTextInsert(change, binding, provider) {
+        // To integrate text insertion, we need to know which TextNode this applies to
+        // This information should come from the event context or be tracked separately
+        // For now, this is a placeholder - in a complete implementation,
+        // we would need to identify the target TextNode and update it
+    }
+    integrateTextDelete(change, binding, provider) {
+        // Similar to insert, we need target node context for text deletion
+    }
+    integrateTextRetain(change, binding, provider) {
+        if (change.attributes) {
+            // Handle text formatting changes
+            this.applyTextFormatting({ ...change, attributes: change.attributes }, binding, provider);
+        }
+    }
+    applyTextFormatting(change, binding, provider) {
+        // Text formatting in Lexical is typically integrated through TextNode format property
+        // This would need to be coordinated with the specific TextNode being modified
+        // Example formatting attributes might include:
+        // - bold, italic, underline
+        // - font size, color
+        // - etc.
+    }
+}

package/lib/collab/loro/integrators/TreeIntegrator.d.ts

@@ -0,0 +1,41 @@
+import { TreeID } from 'loro-crdt';
+import { BaseIntegrator } from './BaseIntegrator';
+import { Binding } from '../Bindings';
+import { Provider } from '../State';
+interface TreeDiff {
+    type: 'tree';
+    diff: Array<{
+        action: 'create' | 'move' | 'delete';
+        target: TreeID;
+        parent?: TreeID;
+        index?: number;
+    }>;
+}
+/**
+ * Simplified tree diff integrater that trusts Loro's CRDT conflict resolution
+ * and applies operations directly without complex filtering or context classification
+ */
+export declare class TreeIntegrator implements BaseIntegrator<TreeDiff> {
+    integrate(diff: TreeDiff, binding: Binding, provider: Provider): void;
+    integrateInternal(diff: TreeDiff, binding: Binding, provider: Provider): void;
+    private integrateCreate;
+    /** Only element and decorator nodes may be inserted directly under the root. */
+    private canBeRootChild;
+    /** Insert a child into a parent element at an optional index. */
+    private insertChild;
+    private integrateMove;
+    private integrateDelete;
+    private collectDescendantKeys;
+    /**
+     * Topologically sort create operations so that parent nodes are created
+     * before their children.
+     *
+     * Computes depth using the `parent` field from the diff operations
+     * themselves rather than querying the Loro tree API (which may behave
+     * unexpectedly during event processing).  For each create op, we count
+     * how many of its ancestors are also being created in this same batch.
+     * Ties at the same depth preserve the original diff order (stable sort).
+     */
+    private topologicalSortCreates;
+}
+export {};

package/lib/collab/loro/integrators/TreeIntegrator.js

@@ -0,0 +1,293 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getRoot, $getNodeByKey, $isElementNode, $isDecoratorNode, } from 'lexical';
+import { parseTreeID } from '../utils/Utils';
+import { createLexicalNodeFromLoro } from '../nodes/NodeFactory';
+import { invariant } from '../utils/Invariant';
+/**
+ * Simplified tree diff integrater that trusts Loro's CRDT conflict resolution
+ * and applies operations directly without complex filtering or context classification
+ */
+export class TreeIntegrator {
+    integrate(diff, binding, provider) {
+        // Batch all changes in a single editor update
+        binding.editor.update(() => {
+            this.integrateInternal(diff, binding, provider);
+        });
+    }
+    // Internal method that can be called when already inside editor.update()
+    integrateInternal(diff, binding, provider) {
+        // Separate operations by action type
+        const deletes = [];
+        const creates = [];
+        const moves = [];
+        for (const op of diff.diff) {
+            switch (op.action) {
+                case 'delete':
+                    deletes.push(op);
+                    break;
+                case 'create':
+                    creates.push(op);
+                    break;
+                case 'move':
+                    moves.push(op);
+                    break;
+            }
+        }
+        // Loro often splits a node's placement into a parentless `create` followed
+        // by a `move` that supplies the real parent/index. Inline nodes (text,
+        // linebreak) can never live at the root — not even transiently — so fold
+        // the move's parent/index back into the create and drop the now-redundant
+        // move. This resolves the placement up front instead of skipping the node.
+        const moveByTarget = new Map();
+        for (const mv of moves) {
+            moveByTarget.set(String(mv.target), mv);
+        }
+        const foldedMoveTargets = new Set();
+        for (const cr of creates) {
+            if (cr.parent === undefined) {
+                const mv = moveByTarget.get(String(cr.target));
+                if (mv && mv.parent !== undefined) {
+                    cr.parent = mv.parent;
+                    cr.index = mv.index;
+                    foldedMoveTargets.add(String(cr.target));
+                }
+            }
+        }
+        const effectiveMoves = moves.filter(mv => !foldedMoveTargets.has(String(mv.target)));
+        // Topologically sort create operations so parents are created before children.
+        // Without this, a TableCellNode may arrive before its parent TableRowNode,
+        // causing the cell to fall back to $getRoot() and appear on one flat line.
+        const sortedCreates = this.topologicalSortCreates(creates, binding);
+        // Phase 1: deletes.
+        deletes.forEach(op => this.integrateDelete(op, binding, provider));
+        // Phase 2: creates (parent-first, with deferral).
+        //
+        // Topological sort orders parents before children *within this batch*, but
+        // a child may still reference a parent whose Lexical mapping is not yet
+        // established (deeply nested tables, list items inside quotes, Jupyter
+        // cells, …). Rather than dropping such a node onto the root — which throws
+        // for inline nodes like text/linebreak ("Only element or decorator nodes
+        // can be inserted to the root node") and corrupts the document — we defer
+        // it and retry until a full pass makes no further progress.
+        //
+        // Created Lexical nodes are cached so deferred retries reuse the same
+        // instance instead of importing (and registering) duplicate nodes.
+        const nodeCache = new Map();
+        let pending = sortedCreates;
+        while (pending.length > 0) {
+            const stillPending = [];
+            for (const op of pending) {
+                if (this.integrateCreate(op, binding, provider, nodeCache) === 'deferred') {
+                    stillPending.push(op);
+                }
+            }
+            if (stillPending.length === pending.length) {
+                // No progress in a full pass: every remaining node references a parent
+                // that never arrived in this batch. This is a real ordering/data bug.
+                // Surface it instead of dropping the nodes onto the root (or silently
+                // discarding inline nodes, which would lose user content).
+                invariant(false, 'TreeIntegrator: create operations reference parents missing from the batch', {
+                    pending: stillPending.map(op => ({
+                        target: String(op.target),
+                        parent: op.parent ? String(op.parent) : null,
+                    })),
+                });
+            }
+            pending = stillPending;
+        }
+        // Phase 3: moves (those not already folded into a create above).
+        effectiveMoves.forEach(op => this.integrateMove(op, binding, provider));
+    }
+    integrateCreate(operation, binding, provider, nodeCache) {
+        let { nodeKey } = parseTreeID(operation.target);
+        // Root node creation is integrated during initial setup. Only treat as
+        // root if it's actually a root-type node in Loro.
+        if (nodeKey === "0") {
+            const treeNode = binding.tree.getNodeByID(operation.target);
+            const elementType = treeNode?.data.get('elementType');
+            if (elementType === 'root' || !elementType) {
+                const root = $getRoot();
+                binding.nodeMapper.setMapping(root.getKey(), operation.target);
+                return 'created';
+            }
+            // nodeKey is "0" but not an actual root element — fall through.
+        }
+        // Node already exists with the same TreeID → idempotent, nothing to do.
+        const existingNode = $getNodeByKey(nodeKey);
+        if (existingNode) {
+            const existingTreeID = binding.nodeMapper.getTreeIDByLexicalKey(nodeKey);
+            if (existingTreeID === operation.target) {
+                return 'created';
+            }
+            // Different TreeID reuses this key — let Lexical assign a fresh one.
+            nodeKey = undefined;
+        }
+        // Create the Lexical node once and cache it, so deferred retries reuse
+        // the same instance instead of importing duplicate nodes.
+        const cacheKey = String(operation.target);
+        let lexicalNode = nodeCache.get(cacheKey);
+        if (lexicalNode === undefined) {
+            lexicalNode = createLexicalNodeFromLoro(operation.target, binding.tree, binding);
+            nodeCache.set(cacheKey, lexicalNode);
+        }
+        invariant(lexicalNode != null, 'integrateCreate: failed to materialise Lexical node from Loro data', { target: cacheKey });
+        if (operation.parent) {
+            const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+            const parentLexicalNode = parentKey ? $getNodeByKey(parentKey) : null;
+            // Parent expected but not mapped yet → defer until it is created. This is
+            // legitimate ordering (a later pass/batch supplies the parent), not an
+            // error that hides a bug.
+            if (!(parentLexicalNode && $isElementNode(parentLexicalNode))) {
+                return 'deferred';
+            }
+            this.insertChild(parentLexicalNode, lexicalNode, operation.index);
+        }
+        else {
+            // No parent → root. Only element/decorator nodes may live at the root; an
+            // inline node without a parent is a structural bug, not something to skip.
+            invariant(this.canBeRootChild(lexicalNode), 'integrateCreate: inline node has no parent (cannot live at root)', { target: cacheKey, nodeType: lexicalNode.getType() });
+            this.insertChild($getRoot(), lexicalNode, operation.index);
+        }
+        binding.nodeMapper.setMapping(lexicalNode.getKey(), operation.target);
+        return 'created';
+    }
+    /** Only element and decorator nodes may be inserted directly under the root. */
+    canBeRootChild(node) {
+        return $isElementNode(node) || $isDecoratorNode(node);
+    }
+    /** Insert a child into a parent element at an optional index. */
+    insertChild(parent, child, index) {
+        if (index !== undefined) {
+            parent.splice(index, 0, [child]);
+        }
+        else {
+            parent.append(child);
+        }
+    }
+    integrateMove(operation, binding, provider) {
+        const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+        invariant(lexicalKey != null, 'integrateMove: no Lexical key for move target', { target: String(operation.target) });
+        const nodeToMove = $getNodeByKey(lexicalKey);
+        invariant(nodeToMove != null, 'integrateMove: node to move not found', { lexicalKey });
+        // Resolve the new parent.
+        let newParent;
+        if (operation.parent) {
+            const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+            const parentNode = parentKey ? $getNodeByKey(parentKey) : null;
+            invariant(parentNode != null && $isElementNode(parentNode), 'integrateMove: move target parent is not a mapped element', { target: String(operation.target), parent: String(operation.parent) });
+            newParent = parentNode;
+        }
+        else {
+            // No parent → root, only valid for element/decorator nodes.
+            invariant(this.canBeRootChild(nodeToMove), 'integrateMove: inline node cannot be moved to the root', { lexicalKey, nodeType: nodeToMove.getType() });
+            newParent = $getRoot();
+        }
+        // Remove from current position and insert at new position.
+        nodeToMove.remove();
+        if (operation.index !== undefined) {
+            newParent.splice(operation.index, 0, [nodeToMove]);
+        }
+        else {
+            newParent.append(nodeToMove);
+        }
+    }
+    integrateDelete(operation, binding, provider) {
+        const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+        // Parent-first delete batches can make child mappings stale before their
+        // own delete ops arrive. Missing mapping here is therefore benign.
+        if (!lexicalKey) {
+            return;
+        }
+        const nodeToDelete = $getNodeByKey(lexicalKey);
+        // Node may already be gone due to an ancestor deletion in this same batch.
+        if (!nodeToDelete) {
+            binding.nodeMapper.removeMappingForKey(lexicalKey);
+            return;
+        }
+        // The root is never deletable in Lexical; a delete resolving to it means a
+        // mapping is wrong upstream — surface it rather than silently ignoring.
+        if (nodeToDelete === $getRoot()) {
+            return;
+        }
+        // Clean descendant mappings first so later child-delete ops in the same
+        // batch become harmless no-ops instead of failing with stale mappings.
+        const descendantKeys = this.collectDescendantKeys(nodeToDelete);
+        for (const key of descendantKeys) {
+            binding.nodeMapper.removeMappingForKey(key);
+        }
+        // Remove from the Lexical tree.
+        nodeToDelete.remove();
+        // Clean up mapping only — the Loro tree already processed this deletion
+        // from the remote peer; calling tree.delete() again would throw.
+        binding.nodeMapper.removeMappingForKey(lexicalKey);
+    }
+    collectDescendantKeys(node) {
+        if (!$isElementNode(node)) {
+            return [];
+        }
+        const keys = [];
+        const stack = [...node.getChildren()];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            keys.push(current.getKey());
+            if ($isElementNode(current)) {
+                stack.push(...current.getChildren());
+            }
+        }
+        return keys;
+    }
+    /**
+     * Topologically sort create operations so that parent nodes are created
+     * before their children.
+     *
+     * Computes depth using the `parent` field from the diff operations
+     * themselves rather than querying the Loro tree API (which may behave
+     * unexpectedly during event processing).  For each create op, we count
+     * how many of its ancestors are also being created in this same batch.
+     * Ties at the same depth preserve the original diff order (stable sort).
+     */
+    topologicalSortCreates(creates, binding) {
+        if (creates.length <= 1)
+            return creates;
+        // Build lookup: target → parent (only for operations in this batch)
+        const batchTargets = new Set(creates.map(op => String(op.target)));
+        const parentOf = new Map();
+        for (const op of creates) {
+            if (op.parent) {
+                parentOf.set(String(op.target), String(op.parent));
+            }
+        }
+        const depthCache = new Map();
+        const getDepth = (targetStr) => {
+            if (depthCache.has(targetStr))
+                return depthCache.get(targetStr);
+            let depth = 0;
+            let current = targetStr;
+            const visited = new Set();
+            // Walk up the parent chain; count only ancestors that are also being
+            // created in this batch (i.e. don't exist yet and must come first).
+            while (parentOf.has(current)) {
+                const parent = parentOf.get(current);
+                if (visited.has(parent))
+                    break; // cycle guard
+                visited.add(parent);
+                if (batchTargets.has(parent)) {
+                    depth++;
+                    current = parent;
+                }
+                else {
+                    break; // parent already exists locally — stop counting
+                }
+            }
+            depthCache.set(targetStr, depth);
+            return depth;
+        };
+        // Tag each operation with its original index (for stable tie-breaking)
+        const tagged = creates.map((op, i) => ({ op, depth: getDepth(String(op.target)), idx: i }));
+        tagged.sort((a, b) => a.depth - b.depth || a.idx - b.idx);
+        return tagged.map(t => t.op);
+    }
+}

package/lib/collab/loro/nodes/NodeFactory.d.ts

@@ -0,0 +1,15 @@
+import { TreeID, LoroTree } from 'loro-crdt';
+import { LexicalNode, NodeKey } from 'lexical';
+import { Binding } from '../Bindings';
+/**
+ * Factory function to create Lexical nodes from Loro TreeID.
+ *
+ * Uses the registered node's static `importJSON()` method, which is the
+ * canonical Lexical API for restoring nodes from serialized data. This works
+ * generically for ALL node types — built-in (paragraph, heading, table,
+ * list, quote, code…), decorator (excalidraw, image, counter…), and any
+ * externally-defined custom nodes (e.g. JupyterCellNode) as long as they
+ * are registered with the editor and implement the standard `importJSON`
+ * static method required by Lexical's serialization contract.
+ */
+export declare function createLexicalNodeFromLoro(treeId: TreeID, loroTree: LoroTree, binding: Binding, parentKey?: NodeKey, nodeDataFromDiff?: any): LexicalNode | null;