@datalayer/lexical-loro 0.2.4 → 0.2.5

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

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) 2023-2025 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) 2023-2025 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,36 @@
+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;
+    private integrateMove;
+    private integrateDelete;
+    /**
+     * 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,251 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getRoot, $getNodeByKey, $isElementNode } from 'lexical';
+import { parseTreeID } from '../utils/Utils';
+import { createLexicalNodeFromLoro } from '../nodes/NodeFactory';
+/**
+ * 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;
+            }
+        }
+        // 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);
+        // Execute: deletes → creates (parent-first) → moves
+        const operations = [...deletes, ...sortedCreates, ...moves];
+        operations.forEach(operation => {
+            switch (operation.action) {
+                case 'create':
+                    this.integrateCreate(operation, binding, provider);
+                    break;
+                case 'move':
+                    this.integrateMove(operation, binding, provider);
+                    break;
+                case 'delete':
+                    this.integrateDelete(operation, binding, provider);
+                    break;
+                default:
+                    console.warn(`🌳 Unknown tree operation: ${operation.action}`);
+            }
+        });
+    }
+    integrateCreate(operation, binding, provider) {
+        try {
+            let { nodeKey } = parseTreeID(operation.target);
+            // Skip root node creation - root is integrated during initial setup
+            // But ensure the root mapping exists
+            // 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;
+                }
+                // If nodeKey is "0" but it's not actually a root element, continue with normal processing
+            }
+            // Check if node already exists and if it's the same TreeID
+            const existingNode = $getNodeByKey(nodeKey);
+            if (existingNode) {
+                const existingTreeID = binding.nodeMapper.getTreeIDByLexicalKey(nodeKey);
+                if (existingTreeID === operation.target) {
+                    return;
+                }
+                else {
+                    // Don't reuse existing keys for different TreeIDs - let Lexical generate a fresh one
+                    nodeKey = undefined; // Let createLexicalNodeFromLoro generate a fresh key
+                }
+            }
+            // Create Lexical node from Loro data
+            const lexicalNode = createLexicalNodeFromLoro(operation.target, binding.tree, binding);
+            if (!lexicalNode) {
+                return;
+            }
+            // Find parent node
+            let parentNode;
+            if (operation.parent) {
+                const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+                const parentLexicalNode = parentKey ? $getNodeByKey(parentKey) : null;
+                if (parentLexicalNode && $isElementNode(parentLexicalNode)) {
+                    parentNode = parentLexicalNode;
+                }
+                else {
+                    console.warn(`🌳 Parent NOT found for ${lexicalNode.getType()} target=${operation.target} parent=${operation.parent} parentKey=${parentKey} parentFound=${!!parentLexicalNode} isElement=${parentLexicalNode ? $isElementNode(parentLexicalNode) : 'N/A'}`);
+                    // For text nodes, we MUST have a proper parent element
+                    if (lexicalNode.getType() === 'text') {
+                        return;
+                    }
+                    parentNode = $getRoot();
+                }
+            }
+            else {
+                parentNode = $getRoot();
+            }
+            // Normal insertion
+            if (operation.index !== undefined) {
+                parentNode.splice(operation.index, 0, [lexicalNode]);
+            }
+            else {
+                parentNode.append(lexicalNode);
+            }
+            // Set up mapping
+            binding.nodeMapper.setMapping(lexicalNode.getKey(), operation.target);
+        }
+        catch (error) {
+            console.warn(`🌳 Error creating node for ${operation.target}:`, error);
+        }
+    }
+    integrateMove(operation, binding, provider) {
+        try {
+            const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+            if (!lexicalKey) {
+                console.warn(`🌳 No Lexical key found for move target ${operation.target}`);
+                return;
+            }
+            const nodeToMove = $getNodeByKey(lexicalKey);
+            if (!nodeToMove) {
+                console.warn(`🌳 Node to move not found: ${lexicalKey}`);
+                return;
+            }
+            // Find new parent
+            let newParent;
+            if (operation.parent) {
+                const parentKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.parent);
+                const parentNode = parentKey ? $getNodeByKey(parentKey) : null;
+                if (parentNode && $isElementNode(parentNode)) {
+                    newParent = parentNode;
+                }
+                else {
+                    // For text nodes, we can't move them to root - skip this move operation
+                    // The node is already in the correct position from our create fix
+                    if (nodeToMove.getType() === 'text') {
+                        return;
+                    }
+                    newParent = $getRoot();
+                }
+            }
+            else {
+                // For text nodes without a parent, skip the move
+                if (nodeToMove.getType() === 'text') {
+                    return;
+                }
+                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);
+            }
+        }
+        catch (error) {
+            console.warn(`🌳 Error moving node ${operation.target}:`, error);
+        }
+    }
+    integrateDelete(operation, binding, provider) {
+        try {
+            const lexicalKey = binding.nodeMapper.getLexicalKeyByLoroId(operation.target);
+            if (!lexicalKey) {
+                console.warn(`🌳 No Lexical key found for delete target ${operation.target}`);
+                return;
+            }
+            const nodeToDelete = $getNodeByKey(lexicalKey);
+            if (!nodeToDelete) {
+                console.warn(`🌳 Node to delete not found: ${lexicalKey}`);
+                return;
+            }
+            // Remove from Lexical tree
+            nodeToDelete.remove();
+            // Clean up mapping only — do NOT call deleteMapping() here because
+            // the Loro tree has already processed this deletion from the remote
+            // peer.  Calling tree.delete() again would throw "is deleted or does
+            // not exist".
+            binding.nodeMapper.removeMappingForKey(lexicalKey);
+        }
+        catch (error) {
+            console.warn(`🌳 Error deleting node ${operation.target}:`, error);
+        }
+    }
+    /**
+     * 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;