@datalayer/lexical-loro 1.0.2 → 1.0.5

package/lib/collab/loro/utils/InitialContent.d.ts

@@ -0,0 +1,64 @@
+import { LoroDoc } from 'loro-crdt';
+/**
+ * Initial Lexical JSON structure that matches what the Python server uses
+ */
+export declare const INITIAL_LEXICAL_JSON: {
+    root: {
+        children: ({
+            children: {
+                detail: number;
+                format: number;
+                mode: string;
+                style: string;
+                text: string;
+                type: string;
+                version: number;
+            }[];
+            direction: any;
+            format: string;
+            indent: number;
+            type: string;
+            version: number;
+            tag: string;
+            textFormat?: undefined;
+            textStyle?: undefined;
+        } | {
+            children: {
+                detail: number;
+                format: number;
+                mode: string;
+                style: string;
+                text: string;
+                type: string;
+                version: number;
+            }[];
+            direction: any;
+            format: string;
+            indent: number;
+            type: string;
+            version: number;
+            textFormat: number;
+            textStyle: string;
+            tag?: undefined;
+        })[];
+        direction: any;
+        format: string;
+        indent: number;
+        type: string;
+        version: number;
+    };
+};
+/**
+ * Initialize a new Loro document with the initial Lexical content
+ * This ensures consistent starting state across all clients
+ */
+export declare function initializeLoroDocWithLexicalContent(doc: LoroDoc): void;
+/**
+ * Check if a Loro document is empty (has no tree content)
+ */
+export declare function isLoroDocumentEmpty(doc: LoroDoc): boolean;
+/**
+ * Check if a Loro document should be initialized (more robust check)
+ * This helps prevent race conditions where multiple clients try to initialize
+ */
+export declare function shouldInitializeLoroDoc(doc: LoroDoc): boolean;

package/lib/collab/loro/utils/InitialContent.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { lexicalToLoroTree } from './LexicalToLoro';
+/**
+ * Initial Lexical JSON structure that matches what the Python server uses
+ */
+export const INITIAL_LEXICAL_JSON = {
+    "root": {
+        "children": [
+            {
+                "children": [
+                    {
+                        "detail": 0,
+                        "format": 0,
+                        "mode": "normal",
+                        "style": "",
+                        "text": "Lexical with Loro",
+                        "type": "text",
+                        "version": 1
+                    }
+                ],
+                "direction": null,
+                "format": "",
+                "indent": 0,
+                "type": "heading",
+                "version": 1,
+                "tag": "h1"
+            },
+            {
+                "children": [
+                    {
+                        "detail": 0,
+                        "format": 0,
+                        "mode": "normal",
+                        "style": "",
+                        "text": "Type something...",
+                        "type": "text",
+                        "version": 1
+                    }
+                ],
+                "direction": null,
+                "format": "",
+                "indent": 0,
+                "type": "paragraph",
+                "version": 1,
+                "textFormat": 0,
+                "textStyle": ""
+            }
+        ],
+        "direction": null,
+        "format": "",
+        "indent": 0,
+        "type": "root",
+        "version": 1
+    }
+};
+/**
+ * Initialize a new Loro document with the initial Lexical content
+ * This ensures consistent starting state across all clients
+ */
+export function initializeLoroDocWithLexicalContent(doc) {
+    const tree = doc.getTree('tree');
+    tree.enableFractionalIndex(0.001);
+    // Convert the initial Lexical JSON to Loro tree structure
+    lexicalToLoroTree(INITIAL_LEXICAL_JSON, tree);
+}
+/**
+ * Check if a Loro document is empty (has no tree content)
+ */
+export function isLoroDocumentEmpty(doc) {
+    const tree = doc.getTree('tree');
+    try {
+        // Get all root nodes
+        const roots = tree.roots();
+        // Also check if the document has any nodes at all
+        const allNodes = tree.nodes();
+        return roots.length === 0 && allNodes.length === 0;
+    }
+    catch (error) {
+        // If there's an error accessing roots, consider it empty
+        return true;
+    }
+}
+/**
+ * Check if a Loro document should be initialized (more robust check)
+ * This helps prevent race conditions where multiple clients try to initialize
+ */
+export function shouldInitializeLoroDoc(doc) {
+    const tree = doc.getTree('tree');
+    try {
+        const allNodes = tree.nodes();
+        const roots = tree.roots();
+        // Only initialize if there are truly no nodes
+        const isEmpty = allNodes.length === 0;
+        // Additional check: look for any existing root nodes with our content
+        if (!isEmpty) {
+            // Check if any root has the expected initial structure
+            for (const root of roots) {
+                const data = Object.fromEntries(root.data.entries());
+                if (data.elementType === 'root') {
+                    return false;
+                }
+            }
+        }
+        return isEmpty;
+    }
+    catch (error) {
+        console.warn('Error checking if doc should be initialized:', error);
+        return false; // Don't initialize if there's an error
+    }
+}

package/lib/collab/loro/utils/Invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Assert a collaboration invariant.
+ *
+ * The Loro <-> Lexical sync engine relies on a set of structural invariants
+ * (a node's parent is already mapped, an insertion index is within range, a
+ * text node always has a parent, ...). When one of these does not hold the
+ * engine is in a state it cannot resolve correctly.
+ *
+ * Historically such cases were "handled" by logging a warning and skipping the
+ * operation (or clamping an index). That silently corrupts the shared document
+ * and hides the underlying bug. Instead we throw: the failure surfaces
+ * immediately, the surrounding `editor.update()` rolls back cleanly, and the
+ * root cause can be found and fixed rather than masked.
+ */
+export declare function invariant(condition: unknown, message: string, context?: Record<string, unknown>): asserts condition;

package/lib/collab/loro/utils/Invariant.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+/**
+ * Assert a collaboration invariant.
+ *
+ * The Loro <-> Lexical sync engine relies on a set of structural invariants
+ * (a node's parent is already mapped, an insertion index is within range, a
+ * text node always has a parent, ...). When one of these does not hold the
+ * engine is in a state it cannot resolve correctly.
+ *
+ * Historically such cases were "handled" by logging a warning and skipping the
+ * operation (or clamping an index). That silently corrupts the shared document
+ * and hides the underlying bug. Instead we throw: the failure surfaces
+ * immediately, the surrounding `editor.update()` rolls back cleanly, and the
+ * root cause can be found and fixed rather than masked.
+ */
+export function invariant(condition, message, context) {
+    if (!condition) {
+        const details = context ? ` ${JSON.stringify(context)}` : '';
+        throw new Error(`[loro-collab] Invariant failed: ${message}${details}`);
+    }
+}

package/lib/collab/loro/utils/LexicalToLoro.d.ts

@@ -0,0 +1,18 @@
+import { LoroTree, TreeID } from 'loro-crdt';
+/**
+ * Utility to convert Lexical JSON structure to Loro tree
+ */
+interface LexicalNodeJSON {
+    type: string;
+    children?: LexicalNodeJSON[];
+    [key: string]: any;
+}
+interface LexicalJSON {
+    root: LexicalNodeJSON;
+}
+/**
+ * Convert a Lexical JSON structure to a Loro tree
+ * This is used to initialize a Loro tree from existing Lexical content
+ */
+export declare function lexicalToLoroTree(lexicalJson: string | LexicalJSON, tree: LoroTree): TreeID;
+export {};

package/lib/collab/loro/utils/LexicalToLoro.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+/**
+ * Convert a Lexical JSON structure to a Loro tree
+ * This is used to initialize a Loro tree from existing Lexical content
+ */
+export function lexicalToLoroTree(lexicalJson, tree) {
+    let parsedJson;
+    if (typeof lexicalJson === 'string') {
+        try {
+            parsedJson = JSON.parse(lexicalJson);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse Lexical JSON: ${error}`);
+        }
+    }
+    else {
+        parsedJson = lexicalJson;
+    }
+    // Start with the root node - create it without a parent
+    const rootTreeNode = tree.createNode();
+    const rootTreeID = rootTreeNode.id;
+    processLexicalNode(parsedJson.root, tree, rootTreeNode);
+    return rootTreeID;
+}
+/**
+ * Recursively process a Lexical node and add it to the Loro tree
+ */
+function processLexicalNode(lexicalNode, tree, treeNode) {
+    // Store the lexical data in the tree node
+    const nodeData = treeNode.data;
+    if (nodeData) {
+        // Store element type for quick access
+        nodeData.set('elementType', lexicalNode.type);
+        // Store lexical node data directly as JSON object
+        const lexicalNodeData = createLexicalNodeFromJSON(lexicalNode);
+        const lexicalNodeJSON = lexicalNodeData.lexicalNode.exportJSON();
+        // Remove all key-related fields to avoid duplication (TreeID serves as the key)
+        if ('__key' in lexicalNodeJSON || 'key' in lexicalNodeJSON || 'lexicalKey' in lexicalNodeJSON) {
+            const { __key, key, lexicalKey, ...cleanedData } = lexicalNodeJSON;
+            nodeData.set('lexical', cleanedData);
+        }
+        else {
+            nodeData.set('lexical', lexicalNodeJSON);
+        }
+    }
+    // Process children if they exist
+    if (lexicalNode.children && Array.isArray(lexicalNode.children)) {
+        lexicalNode.children.forEach((child, childIndex) => {
+            // Create child node under current node
+            const childTreeNode = tree.createNode(treeNode.id, childIndex);
+            processLexicalNode(child, tree, childTreeNode);
+        });
+    }
+}
+/**
+ * Create a minimal Lexical node representation from JSON data
+ * This doesn't create actual Lexical nodes, just the data structure needed for serialization
+ */
+function createLexicalNodeFromJSON(nodeJson) {
+    // Create a minimal node-like object with the essential properties
+    const nodeData = {
+        __key: generateNodeKey(), // Generate a temporary key
+        __type: nodeJson.type,
+        __parent: null, // Will be set during tree construction
+        __text: nodeJson.text || undefined,
+        __format: nodeJson.format || 0,
+        __style: nodeJson.style || '',
+        __mode: nodeJson.mode || undefined,
+        __detail: nodeJson.detail || undefined,
+        __indent: nodeJson.indent || 0,
+        __direction: nodeJson.direction || null,
+        __tag: nodeJson.tag || undefined,
+        __textFormat: nodeJson.textFormat || undefined,
+        __textStyle: nodeJson.textStyle || undefined,
+        __version: nodeJson.version || 1
+    };
+    // Remove undefined properties
+    Object.keys(nodeData).forEach(key => {
+        if (nodeData[key] === undefined) {
+            delete nodeData[key];
+        }
+    });
+    // Return in the format expected by LexicalNodeDataHelper
+    return {
+        lexicalNode: {
+            getType: () => nodeJson.type,
+            exportJSON: () => nodeData,
+            getKey: () => nodeData.__key
+        }
+    };
+}
+/**
+ * Generate a simple node key for temporary use
+ */
+function generateNodeKey() {
+    return Math.random().toString(36).substr(2, 9);
+}

package/lib/collab/loro/utils/Utils.d.ts

@@ -0,0 +1,44 @@
+import { LoroDoc, TreeID } from 'loro-crdt';
+import { EditorState, LexicalNode, NodeKey, RangeSelection, TextNode } from 'lexical';
+export declare const DEFAULT_TREE_NAME = "lexical-tree";
+/**
+ * Generates a consistent client ID from a Loro document.
+ * Uses the numeric peer ID directly to ensure consistency across all components.
+ *
+ * @param doc - The Loro document
+ * @returns A number representing the client ID
+ */
+export declare function generateClientID(doc: LoroDoc): number;
+/**
+ * Generates a client ID for cases where no document is available.
+ * Creates a random ID within the safe integer range.
+ *
+ * @returns A randomly generated client ID
+ */
+export declare function generateRandomClientID(): number;
+/**
+ * Ensure doc has a LoroTree instance
+ */
+export declare function getLoroTree(doc: LoroDoc, treeName?: string): import("loro-crdt").LoroTree<Record<string, unknown>>;
+/**
+ * Helper function to parse TreeID back to nodeKey and peerId
+ */
+export declare function parseTreeID(treeId: TreeID): {
+    nodeKey: NodeKey;
+    peerId: number;
+};
+/**
+ * Helper function to get Lexical node information for Loro sync
+ */
+export declare function getLexicalNodeInfo(node: LexicalNode): {
+    parentKey?: string;
+    index?: number;
+};
+/**
+ * Check if a class extends another class (proper inheritance checking)
+ */
+export declare function isClassExtending(Klass: any, BaseClass: any): boolean;
+export declare function toKeyNodeNumber(nodeKey: NodeKey): number;
+export declare function $diffTextContentAndApplyDelta(textNode: TextNode, key: NodeKey, prevText: string, nextText: string): void;
+export declare function doesSelectionNeedRecovering(selection: RangeSelection): boolean;
+export declare function $moveSelectionToPreviousNode(anchorNodeKey: string, currentEditorState: EditorState): void;

package/lib/collab/loro/utils/Utils.js

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { $getNodeByKey, $getRoot, $getSelection, $isRangeSelection, $isTextNode } from 'lexical';
+import simpleDiffWithCursor from '../../utils/simpleDiffWithCursor';
+export const DEFAULT_TREE_NAME = 'lexical-tree';
+/**
+ * Generates a consistent client ID from a Loro document.
+ * Uses the numeric peer ID directly to ensure consistency across all components.
+ *
+ * @param doc - The Loro document
+ * @returns A number representing the client ID
+ */
+export function generateClientID(doc) {
+    return Number(doc.peerId);
+}
+/**
+ * Generates a client ID for cases where no document is available.
+ * Creates a random ID within the safe integer range.
+ *
+ * @returns A randomly generated client ID
+ */
+export function generateRandomClientID() {
+    return Math.floor(Math.random() * 2147483647);
+}
+/**
+ * Ensure doc has a LoroTree instance
+ */
+export function getLoroTree(doc, treeName = DEFAULT_TREE_NAME) {
+    const tree = doc.getTree(treeName);
+    // Enable fractional index for ordered siblings (useful for maintaining order)
+    // tree.enableFractionalIndex(0.001);
+    return tree;
+}
+/**
+ * Helper function to parse TreeID back to nodeKey and peerId
+ */
+export function parseTreeID(treeId) {
+    const [nodeKey, peerId] = treeId.split('@');
+    return {
+        nodeKey: nodeKey,
+        peerId: Number(peerId)
+    };
+}
+/**
+ * Helper function to get Lexical node information for Loro sync
+ */
+export function getLexicalNodeInfo(node) {
+    // TODO: Implement logic to get parent and index from Lexical node
+    // This is a placeholder that should be replaced with actual Lexical API calls
+    return {
+        parentKey: node.getParent()?.getKey(),
+        index: node.getIndexWithinParent()
+    };
+}
+/**
+ * Check if a class extends another class (proper inheritance checking)
+ */
+export function isClassExtending(Klass, BaseClass) {
+    // Direct class equality
+    if (Klass === BaseClass) {
+        return true;
+    }
+    // Check by name (for cases where classes might be different instances)
+    if (Klass.name === BaseClass.name) {
+        return true;
+    }
+    // Check prototype chain for inheritance
+    if (Klass.prototype && Object.prototype.isPrototypeOf.call(BaseClass, Klass)) {
+        return true;
+    }
+    return false;
+}
+export function toKeyNodeNumber(nodeKey) {
+    // Special case for root node
+    if (nodeKey === "root") {
+        return 0;
+    }
+    // Attempt to convert NodeKey (string) to a number
+    const keyAsNumber = Number(nodeKey);
+    if (!isNaN(keyAsNumber)) {
+        return keyAsNumber;
+    }
+    // If conversion fails, throw an error
+    throw new Error(`NodeKey "${nodeKey}" cannot be converted to a number. Expected numeric string or "root".`);
+}
+export function $diffTextContentAndApplyDelta(textNode, key, prevText, nextText) {
+    const selection = $getSelection();
+    let cursorOffset = nextText.length;
+    if ($isRangeSelection(selection) && selection.isCollapsed()) {
+        const anchor = selection.anchor;
+        if (anchor.key === key) {
+            // Ensure cursor offset doesn't exceed the new text length
+            // This prevents errors when text is split or content changes significantly
+            cursorOffset = Math.min(anchor.offset, nextText.length);
+        }
+    }
+    const diff = simpleDiffWithCursor(prevText, nextText, cursorOffset);
+    const beforeSplice = textNode.getTextContent();
+    textNode.spliceText(diff.index, diff.remove, diff.insert);
+    const afterSplice = textNode.getTextContent();
+}
+export function doesSelectionNeedRecovering(selection) {
+    const anchor = selection.anchor;
+    const focus = selection.focus;
+    let recoveryNeeded = false;
+    try {
+        const anchorNode = anchor.getNode();
+        const focusNode = focus.getNode();
+        if (
+        // We might have removed a node that no longer exists
+        !anchorNode.isAttached() ||
+            !focusNode.isAttached() ||
+            // If we've split a node, then the offset might not be right
+            ($isTextNode(anchorNode) &&
+                anchor.offset > anchorNode.getTextContentSize()) ||
+            ($isTextNode(focusNode) && focus.offset > focusNode.getTextContentSize())) {
+            recoveryNeeded = true;
+        }
+    }
+    catch (e) {
+        // Sometimes checking nor a node via getNode might trigger
+        // an error, so we need recovery then too.
+        recoveryNeeded = true;
+    }
+    return recoveryNeeded;
+}
+export function $moveSelectionToPreviousNode(anchorNodeKey, currentEditorState) {
+    const anchorNode = currentEditorState._nodeMap.get(anchorNodeKey);
+    if (!anchorNode) {
+        $getRoot().selectStart();
+        return;
+    }
+    // Get previous node
+    const prevNodeKey = anchorNode.__prev;
+    let prevNode = null;
+    if (prevNodeKey) {
+        prevNode = $getNodeByKey(prevNodeKey);
+    }
+    // If previous node not found, get parent node
+    if (prevNode === null && anchorNode.__parent !== null) {
+        prevNode = $getNodeByKey(anchorNode.__parent);
+    }
+    if (prevNode === null) {
+        $getRoot().selectStart();
+        return;
+    }
+    if (prevNode !== null && prevNode.isAttached()) {
+        prevNode.selectEnd();
+        return;
+    }
+    else {
+        // If the found node is also deleted, select the next one
+        $moveSelectionToPreviousNode(prevNode.__key, currentEditorState);
+    }
+}

package/lib/collab/loro/wsProvider.d.ts

@@ -0,0 +1,8 @@
+import { LoroDoc } from 'loro-crdt';
+import { Provider } from './State';
+/**
+ * Create a WebSocket provider for Loro collaboration with periodic ephemeral state synchronization.
+ * The resyncInterval enables client-side periodic querying to complement server-side cleanup,
+ * preventing stale user states from accumulating after browser refreshes.
+ */
+export declare function createWebsocketProvider(id: string, docMap: Map<string, LoroDoc>, websocketUrl?: string): Provider;

package/lib/collab/loro/wsProvider.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+import { LoroDoc } from 'loro-crdt';
+import { WebsocketProvider } from './provider/websocket';
+const url = new URL(window.location.href);
+const params = new URLSearchParams(url.search);
+const RESYNC_INTERVAL = parseInt(params.get('resyncInterval') || '30000', 10); // Default 30s, configurable via URL
+/**
+ * Create a WebSocket provider for Loro collaboration with periodic ephemeral state synchronization.
+ * The resyncInterval enables client-side periodic querying to complement server-side cleanup,
+ * preventing stale user states from accumulating after browser refreshes.
+ */
+export function createWebsocketProvider(id, docMap, websocketUrl) {
+    let doc = docMap.get(id);
+    if (doc === undefined) {
+        doc = new LoroDoc();
+        docMap.set(id, doc);
+    }
+    const providerInstanceId = Math.random().toString(36).substr(2, 9);
+    console.log(` Creating WebsocketProvider instance (ID: ${providerInstanceId}) for docId: ${id}`);
+    // Use provided websocketUrl or fallback to URL parameters/defaults
+    const rawWebsocketUrl = websocketUrl || (() => {
+        const url = new URL(window.location.href);
+        const params = new URLSearchParams(url.search);
+        return params.get('collabEndpoint') || 'ws://localhost:3002';
+    })();
+    // The WebsocketProvider builds the connection URL as
+    // `serverUrl + '/' + docId + '?' + params`. If the caller embedded a query
+    // string (for example `?token=<jwt>`) directly in the URL, the docId would be
+    // appended *after* the query string, corrupting the URL. Split any query
+    // string off the base URL and forward it through the provider `params` so the
+    // final URL is `serverUrl/docId?token=<jwt>` as the server expects.
+    let finalWebsocketUrl = rawWebsocketUrl;
+    const params = {};
+    const queryIndex = finalWebsocketUrl.indexOf('?');
+    if (queryIndex !== -1) {
+        const query = finalWebsocketUrl.slice(queryIndex + 1);
+        finalWebsocketUrl = finalWebsocketUrl.slice(0, queryIndex);
+        new URLSearchParams(query).forEach((value, key) => {
+            params[key] = value;
+        });
+    }
+    const websocketProvider = new WebsocketProvider(finalWebsocketUrl, id, doc, {
+        connect: false,
+        params,
+        resyncInterval: RESYNC_INTERVAL, // Poll ephemeral state periodically to prevent stale user accumulation
+    });
+    console.log(` WebsocketProvider created for: ${finalWebsocketUrl}/${id} with resyncInterval: ${RESYNC_INTERVAL}ms`);
+    return websocketProvider;
+}

package/lib/collab/utils/invariant.d.ts

@@ -0,0 +1 @@
+export default function invariant(cond?: boolean, message?: string, ...args: string[]): asserts cond;

package/lib/collab/utils/invariant.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+// invariant(condition, message) will refine types based on "condition", and
+// if "condition" is false will throw an error. This function is special-cased
+// in flow itself, so we can't name it anything else.
+export default function invariant(cond, message, ...args) {
+    if (cond) {
+        return;
+    }
+    throw new Error('Internal Lexical error: invariant() is meant to be replaced at compile ' +
+        'time. There is no runtime version. Error: ' +
+        message);
+}

package/lib/collab/utils/simpleDiffWithCursor.d.ts

@@ -0,0 +1,5 @@
+export default function simpleDiffWithCursor(a: string, b: string, cursor: number): {
+    index: number;
+    insert: string;
+    remove: number;
+};

package/lib/collab/utils/simpleDiffWithCursor.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+export default function simpleDiffWithCursor(a, b, cursor) {
+    const aLength = a.length;
+    const bLength = b.length;
+    let left = 0; // number of same characters counting from left
+    let right = 0; // number of same characters counting from right
+    // Iterate left to the right until we find a changed character
+    // First iteration considers the current cursor position
+    while (left < aLength &&
+        left < bLength &&
+        a[left] === b[left] &&
+        left < cursor) {
+        left++;
+    }
+    // Iterate right to the left until we find a changed character
+    while (right + left < aLength &&
+        right + left < bLength &&
+        a[aLength - right - 1] === b[bLength - right - 1]) {
+        right++;
+    }
+    // Try to iterate left further to the right without caring about the current cursor position
+    while (right + left < aLength &&
+        right + left < bLength &&
+        a[left] === b[left]) {
+        left++;
+    }
+    return {
+        index: left,
+        insert: b.slice(left, bLength - right),
+        remove: aLength - left - right,
+    };
+}