@datalayer/lexical-loro 0.0.2 → 0.0.3

package/README.md

@@ -8,10 +8,11 @@ A collaborative editing plugin for [Lexical](https://github.com/facebook/lexical
 
 ## Core Components
 
-This package provides two main components for building collaborative text editors:
+This package provides three main components for building collaborative text editors:
 
 1. **`LoroCollaborativePlugin.tsx`** - A Lexical plugin that integrates Loro CRDT for real-time collaborative editing
-2. **`lexical-loro` Python package** - A WebSocket server using [loro-py](https://github.com/loro-dev/loro-py) for maintaining document state server-side
+2. **`LexicalModel` Python Library** - A standalone document model for Lexical content with CRDT capabilities
+3. **`lexical-loro` WebSocket Server** - A Python server using [loro-py](https://github.com/loro-dev/loro-py) for real-time collaboration
 
 ## Quick Start
 
@@ -34,6 +35,34 @@ function MyEditor() {
 }
 ```
 
+### Using the LexicalModel Library
+
+```python
+from lexical_loro import LexicalModel
+
+# Create a new document
+model = LexicalModel.create_document("my-document")
+
+# Add content
+model.add_block({
+    "text": "My Document",
+    "format": 0,
+    "style": ""
+}, "heading1")
+
+model.add_block({
+    "text": "This is a paragraph.",
+    "format": 0,
+    "style": ""
+}, "paragraph")
+
+# Save to file
+model.save_to_file("document.json")
+
+# Load from file
+loaded_model = LexicalModel.load_from_file("document.json")
+```
+
 ### Using the Python Server
 
 ```bash
@@ -63,9 +92,11 @@ For complete working examples, see the `src/examples/` directory which contains:
 - 🔄 **Real-time Collaboration**: Multiple users can edit the same document simultaneously
 - 🚀 **Conflict-free**: Uses Loro CRDT to automatically resolve conflicts  
 - 📝 **Lexical Integration**: Seamless integration with Lexical rich text editor
+- 📚 **Standalone Library**: Use LexicalModel independently for document management
 - 🌐 **WebSocket Server**: Python server for maintaining document state
 - 📡 **Connection Management**: Robust WebSocket connection handling
 - ✨ **Rich Text Support**: Preserves formatting during collaborative editing
+- 💾 **Serialization**: JSON export/import and file persistence
 - 🔧 **Extensible**: Plugin-based architecture for easy customization
 
 ## Technology Stack
@@ -148,7 +179,56 @@ function CollaborativeEditor() {
 }
 ```
 
-### 2. Python Server Setup
+### 2. Standalone LexicalModel Library
+
+Use the LexicalModel library independently for document management:
+
+```python
+from lexical_loro import LexicalModel
+
+# Create a new document
+model = LexicalModel.create_document("my-document")
+
+# Add different types of content
+model.add_block({
+    "text": "My Document",
+    "format": 0,
+    "style": ""
+}, "heading1")
+
+model.add_block({
+    "text": "This is a paragraph with **bold** text.",
+    "format": 0,
+    "style": ""
+}, "paragraph")
+
+model.add_block({
+    "text": "",
+    "format": 0,
+    "style": ""
+}, "list")
+
+# Serialize to JSON
+json_data = model.to_json()
+
+# Save to file
+model.save_to_file("document.json")
+
+# Load from file
+loaded_model = LexicalModel.load_from_file("document.json")
+
+# Access blocks
+for block in loaded_model.get_blocks():
+    print(f"{block['type']}: {block.get('text', '')}")
+```
+
+For more examples, see:
+- `examples/memory_only_example.py` - Basic document creation and manipulation
+- `examples/file_sync_example.py` - File persistence and batch operations  
+- `examples/collaboration_example.py` - Simulating collaborative editing
+- `docs/LEXICAL_MODEL_GUIDE.md` - Comprehensive documentation
+
+### 3. Python Server Setup
 
 Start the WebSocket server:
 
@@ -163,7 +243,7 @@ lexical-loro-server --port 8082
 lexical-loro-server --port 8081 --log-level DEBUG
 ```
 
-### 3. Programmatic Server Usage
+### 4. Programmatic Server Usage
 
 ```python
 import asyncio
@@ -180,7 +260,9 @@ if __name__ == "__main__":
 
 ## Plugin API
 
-### LoroCollaborativePlugin Props
+For detailed API documentation, see [`docs/API.md`](docs/API.md).
+
+### Quick Reference
 
 ```tsx
 interface LoroCollaborativePluginProps {
@@ -192,213 +274,15 @@ interface LoroCollaborativePluginProps {
 }
 ```
 
-### Plugin Features
-
-- **Real-time Sync**: Automatically syncs all text changes via Loro CRDT
-- **Cursor Tracking**: Shows other users' cursor positions (experimental)
-- **Connection Management**: Handles reconnection and error states
-- **Rich Text Preservation**: Maintains formatting during collaborative edits
-- **Conflict Resolution**: Automatic conflict-free merging via CRDT
-
-
 ## Initialization Best Practices
 
-⚠️ **Important**: To avoid race conditions and initial state corruption, always wait for collaboration initialization to complete before enabling other Lexical plugins or performing document operations.
-
-### Why Initialization Matters
-
-Collaborative editing involves complex synchronization between:
-- Local Lexical editor state
-- Remote CRDT document state  
-- WebSocket connection establishment
-- Initial document snapshot loading
-
-Enabling other plugins or performing operations before this synchronization completes can cause:
-- Document state corruption
-- Lost edits
-- Inconsistent collaborative state
-- Race conditions between local and remote changes
-
-### Proper Plugin Ordering
-
-```tsx
-function MyEditor() {
-  const [isCollabInitialized, setIsCollabInitialized] = useState(false);
-
-  return (
-    <LexicalComposer initialConfig={editorConfig}>
-      <div>
-        {/* ALWAYS load collaborative plugin first */}
-        <LoroCollaborativePlugin
-          websocketUrl="ws://localhost:8081"
-          docId="my-document"
-          onInitialization={(success) => {
-            setIsCollabInitialized(success);
-            console.log('Collaboration ready:', success);
-          }}
-        />
-        
-        {/* WAIT for collaboration before enabling other plugins */}
-        {isCollabInitialized && (
-          <>
-            <HistoryPlugin />
-            <AutoLinkPlugin />
-            <ListPlugin />
-            <CheckListPlugin />
-            {/* Other plugins... */}
-          </>
-        )}
-        
-        <RichTextPlugin
-          contentEditable={<ContentEditable />}
-          placeholder={<div>Loading collaborative editor...</div>}
-          ErrorBoundary={LexicalErrorBoundary}
-        />
-      </div>
-    </LexicalComposer>
-  );
-}
-```
-
-### Initialization Callback
-
-The `onInitialization` callback provides essential feedback:
-
-```tsx
-<LoroCollaborativePlugin
-  websocketUrl="ws://localhost:8081"
-  docId="document-123"
-  onInitialization={(success: boolean) => {
-    if (success) {
-      // ✅ Safe to enable other plugins and features
-      console.log('Collaboration initialized successfully');
-      enableOtherFeatures();
-    } else {
-      // ❌ Handle initialization failure
-      console.error('Collaboration failed to initialize');
-      showErrorMessage('Failed to connect to collaborative server');
-    }
-  }}
-/>
-```
-
-### Visual Status Indicators
-
-Provide users with clear feedback about initialization status:
-
-```tsx
-function CollaborativeEditor() {
-  const [isInitialized, setIsInitialized] = useState(false);
-
-  return (
-    <div>
-      <div className="status-bar">
-        Collaboration: {isInitialized ? '✅ Ready' : '⏳ Connecting...'}
-      </div>
-      
-      <LexicalComposer initialConfig={editorConfig}>
-        <LoroCollaborativePlugin
-          websocketUrl="ws://localhost:8081"
-          docId="document-123"
-          onInitialization={setIsInitialized}
-        />
-        
-        {/* Editor becomes fully functional only after initialization */}
-        <RichTextPlugin
-          contentEditable={
-            <ContentEditable 
-              style={{ 
-                opacity: isInitialized ? 1 : 0.5,
-                pointerEvents: isInitialized ? 'auto' : 'none'
-              }} 
-            />
-          }
-          placeholder={
-            <div>
-              {isInitialized 
-                ? 'Start typing...' 
-                : 'Connecting to collaboration server...'
-              }
-            </div>
-          }
-          ErrorBoundary={LexicalErrorBoundary}
-        />
-      </LexicalComposer>
-    </div>
-  );
-}
-```
-
-### Common Anti-Patterns to Avoid
-
-❌ **Don't** enable plugins immediately:
-```tsx
-// WRONG: Race condition risk
-<LoroCollaborativePlugin websocketUrl="..." />
-<HistoryPlugin /> {/* May interfere with initial sync */}
-```
-
-❌ **Don't** perform immediate document operations:
-```tsx
-// WRONG: May overwrite remote content
-useEffect(() => {
-  editor.update(() => {
-    $getRoot().clear(); // Dangerous before sync!
-  });
-}, []);
-```
-
-❌ **Don't** ignore initialization status:
-```tsx
-// WRONG: No feedback on connection issues
-<LoroCollaborativePlugin websocketUrl="..." />
-```
-
-### Debugging Initialization Issues
+⚠️ **Important**: Always wait for collaboration initialization before enabling other plugins.
 
-If initialization fails, check:
-
-1. **WebSocket Connection**: Ensure server is running and accessible
-2. **Network Issues**: Check browser network tab for connection errors
-3. **CORS Settings**: Verify server allows cross-origin WebSocket connections
-4. **Document ID**: Ensure unique document IDs for different documents
-5. **Server Logs**: Enable debug logging on server side
-
-```bash
-# Enable debug logging
-export LEXICAL_LORO_LOG_LEVEL=DEBUG
-lexical-loro-server
-```
-
-## Server API
-
-### LoroWebSocketServer Class
-
-```python
-from lexical_loro import LoroWebSocketServer
-
-# Create server instance
-server = LoroWebSocketServer(
-    port=8081,           # Server port
-    host="localhost"     # Server host
-)
-
-# Start server
-await server.start()
-
-# Shutdown server
-await server.shutdown()
-```
-
-### Supported Message Types
-
-The server handles these WebSocket message types:
-
-- `loro-update`: Apply CRDT document updates
-- `snapshot`: Full document state snapshots  
-- `request-snapshot`: Request current document state
-- `ephemeral-update`: Cursor and selection updates
-- `awareness-update`: User presence information
+See [`docs/INITIALIZATION_GUIDE.md`](docs/INITIALIZATION_GUIDE.md) for comprehensive guidance on:
+- Proper plugin ordering
+- Initialization callbacks
+- Error handling
+- Common anti-patterns to avoid
 
 ## Examples
 
@@ -434,8 +318,19 @@ lexical_loro/                           # Python WebSocket server package
 ├── __init__.py                         # Package exports
 ├── server.py                           # WebSocket server implementation  
 ├── cli.py                              # Command line interface
+├── model/
+│   └── lexical_model.py                # Standalone LexicalModel library
 └── tests/                              # Python test suite
 
+docs/
+└── LEXICAL_MODEL_GUIDE.md              # Comprehensive library documentation
+
+examples/
+├── memory_only_example.py              # Basic LexicalModel usage
+├── file_sync_example.py                # File persistence example
+├── collaboration_example.py            # Collaborative editing simulation
+└── README.md                           # Examples documentation
+
 pyproject.toml                          # Python package configuration
 ```
 
@@ -467,23 +362,17 @@ src/archive/                            # Historical plugin implementations
 └── LoroCollaborativePlugin5.tsx
 ```
 
-## How It Works
+## Architecture
 
-### Architecture Overview
+For detailed architecture documentation, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
-The collaboration system consists of two main components:
+### System Overview
 
-1. **LoroCollaborativePlugin** (Client-side)
-   - Integrates with Lexical editor as a React plugin
-   - Captures text changes and applies them to Loro CRDT document
-   - Sends/receives updates via WebSocket connection
-   - Handles cursor positioning and user awareness
+The collaboration system consists of three main components:
 
-2. **LoroWebSocketServer** (Server-side)  
-   - Python WebSocket server using loro-py
-   - Maintains authoritative document state
-   - Broadcasts updates to all connected clients
-   - Handles client connections and disconnections
+1. **LoroCollaborativePlugin** (Client-side) - Lexical integration
+2. **LoroWebSocketServer** (Server-side) - Real-time synchronization  
+3. **LexicalModel** (Standalone Library) - Independent document model
 
 ### Data Flow
 
@@ -493,168 +382,66 @@ User Types → Lexical Editor → Plugin → Loro CRDT → WebSocket
 WebSocket ← Loro CRDT ← Plugin ← Lexical Editor ← Other Users
 ```
 
-### CRDT Integration Process
-
-1. **Document Creation**: Plugin creates a Loro document with unique identifier
-2. **Local Changes**: User edits trigger Lexical change events  
-3. **CRDT Application**: Changes are applied to local Loro document
-4. **Synchronization**: Updates are serialized and sent via WebSocket
-5. **Remote Application**: Other clients receive and apply updates
-6. **Conflict Resolution**: Loro CRDT automatically merges changes without conflicts
-
-### Connection Management
-
-- **Auto-reconnection**: Plugin handles connection drops gracefully
-- **State Synchronization**: New clients receive full document snapshot
-- **Error Handling**: Connection errors are logged and displayed
-- **User Awareness**: Track online users and cursor positions
-
-### Lexical Integration
-
-The Lexical editor integration includes:
-
-1. **LoroCollaborativePlugin**: A custom Lexical plugin that bridges Lexical and Loro CRDT
-2. **Bidirectional Sync**: Changes flow from Lexical → Loro → WebSocket and vice versa
-3. **Rich Text Preservation**: The plugin maintains rich text formatting during collaborative editing
-4. **Independent State**: Lexical editor maintains separate document state from simple text editor
-
-### WebSocket Communication
-
-The WebSocket server:
-- Maintains connections to all clients
-- Broadcasts Loro document updates to all connected clients with document ID filtering
-- Handles client connections and disconnections
-- Provides connection status feedback
-- Stores separate snapshots for each document type
-
-### Real-time Updates
-
-1. User types in the text area
-2. Change is applied to local Loro document
-3. Document update is serialized and sent via WebSocket
-4. Other clients receive the update and apply it to their documents
-5. UI is updated to reflect the changes
-
-### Initial Content Synchronization
-
-When a new collaborator joins:
-
-1. **Connection**: New client connects to WebSocket server
-2. **Welcome**: Server sends welcome message to new client
-3. **Snapshot Request**: New client requests current document state
-4. **Snapshot Delivery**: Server sends stored snapshot or requests one from existing clients
-5. **Content Sync**: New client applies snapshot and sees current document content
-6. **Ready to Collaborate**: New client can now participate in real-time editing
-
-The server maintains the latest document snapshot to ensure new collaborators always see existing content.
-
 ## Configuration
 
-### Plugin Configuration
+For detailed configuration options, see [`docs/API.md`](docs/API.md).
+
+### Quick Configuration
 
 ```tsx
+// Plugin configuration
 <LoroCollaborativePlugin 
-  websocketUrl="ws://localhost:8081"    // Server URL
-  docId="my-document"                   // Document identifier  
-  username="user123"                    // User identifier
-  userColor="#ff0000"                   // Cursor color (optional)
-  debug={true}                          // Enable debug logs (optional)
+  websocketUrl="ws://localhost:8081"
+  docId="my-document"
+  username="user123"
+  debug={true}
 />
 ```
 
-### Server Configuration
-
-```python
-# Via command line
-lexical-loro-server --port 8081 --host localhost --log-level DEBUG
-
-# Via environment variables
-export LEXICAL_LORO_PORT=8081
-export LEXICAL_LORO_HOST=localhost
-export LEXICAL_LORO_LOG_LEVEL=DEBUG
-lexical-loro-server
-
-# Programmatically
-server = LoroWebSocketServer(port=8081, host="localhost")
+```bash
+# Server configuration
+lexical-loro-server --port 8081 --log-level DEBUG
 ```
 
-### Supported Document Types
-
-The server supports multiple document types with different IDs:
-- `shared-text`: Basic text collaboration
-- `lexical-shared-doc`: Rich text with Lexical  
-- Custom document IDs for multiple simultaneous documents
-
 ## Development
 
-### Core Components Development
+For comprehensive development guidelines, see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
 
-**Plugin Development:**
-```bash
-# The plugin is a single TypeScript file
-src/LoroCollaborativePlugin.tsx
+### Quick Start
 
-# Dependencies for plugin development
-npm install lexical @lexical/react @lexical/selection loro-crdt
-```
-
-**Server Development:**  
 ```bash
-# Install Python package in development mode
+# Install dependencies
+npm install
 pip install -e ".[dev]"
 
 # Run tests
-pytest lexical_loro/tests/ -v
+npm test
+npm run test:py
 
-# Start server in development mode  
-python3 -m lexical_loro.cli --port 8081 --log-level DEBUG
-```
-
-### Testing
-
-**Plugin Testing:**
-```bash
-npm run test              # Run Vitest tests
-npm run test:js          # Run tests once
-```
-
-**Server Testing:**
-```bash
-npm run test:py          # Run Python tests
-npm run test:py:watch    # Run in watch mode
-npm run test:py:coverage # Run with coverage
-```
-
-### Example Development
-
-To work on the examples:
-```bash
-npm install                    # Install all dependencies
-npm run example               # Start example app with both servers  
-npm run example:py            # Start with Python server only
-npm run example:js            # Start with Node.js server only
-npm run example:vite          # Start example app only (no servers)
+# Start development server
+lexical-loro-server --log-level DEBUG
 ```
 
 ## Contributing
 
-We welcome contributions to both the Lexical plugin and Python server:
+We welcome contributions! Please see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for detailed guidelines.
+
+### Quick Contributing Guide
 
 1. Fork the repository
 2. Create a feature branch  
-3. Focus changes on core components:
-   - `src/LoroCollaborativePlugin.tsx` for plugin improvements
-   - `lexical_loro/` for server enhancements
+3. Focus changes on core components
 4. Add tests for new functionality
 5. Update documentation as needed
 6. Submit a pull request
 
-### Development Guidelines
+## Documentation
 
-- **Plugin**: Keep the plugin self-contained and dependency-light
-- **Server**: Maintain compatibility with loro-py and WebSocket standards  
-- **Examples**: Use examples to demonstrate new features
-- **Tests**: Ensure both JavaScript and Python tests pass
+- **[API Documentation](docs/API.md)** - Complete API reference
+- **[Initialization Guide](docs/INITIALIZATION_GUIDE.md)** - Best practices for setup
+- **[Architecture](docs/ARCHITECTURE.md)** - System design and data flow
+- **[Development Guide](docs/DEVELOPMENT.md)** - Contributing and development setup
+- **[LexicalModel Guide](docs/LEXICAL_MODEL_GUIDE.md)** - Standalone library documentation
 
 ## License
 

package/lib/LoroCollaborativePlugin.d.ts

@@ -10,6 +10,7 @@ interface LoroCollaborativePluginProps {
         isCurrentUser?: boolean;
     }>) => void;
     onInitialization?: (success: boolean) => void;
+    onSendMessageReady?: (sendMessageFn: (message: any) => void) => void;
 }
-export declare function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange, onInitialization }: LoroCollaborativePluginProps): import("react/jsx-runtime").JSX.Element;
+export declare function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange, onInitialization, onSendMessageReady }: LoroCollaborativePluginProps): import("react/jsx-runtime").JSX.Element;
 export default LoroCollaborativePlugin;

package/lib/LoroCollaborativePlugin.js

@@ -627,7 +627,7 @@ class CursorAwareness {
         return this.ephemeralStore.getAllStates();
     }
 }
-export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange, onInitialization }) {
+export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange, onInitialization, onSendMessageReady }) {
     const [editor] = useLexicalComposerContext();
     const wsRef = useRef(null);
     const loroDocRef = useRef(new LoroDoc());
@@ -898,13 +898,29 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                     console.log('🎯 Set awareness with stable cursor data:', { userWithCursorData, clientId });
                     // Send ephemeral update to other clients via WebSocket
                     if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN && awarenessRef.current) {
-                        const ephemeralData = awarenessRef.current.encode();
-                        const hexData = Array.from(ephemeralData).map(b => b.toString(16).padStart(2, '0')).join('');
-                        wsRef.current.send(JSON.stringify({
-                            type: 'ephemeral-update',
-                            docId: docId,
-                            data: hexData // Convert to hex string
-                        }));
+                        try {
+                            const ephemeralData = awarenessRef.current.encode();
+                            // Validate ephemeral data before sending
+                            if (!ephemeralData || ephemeralData.length === 0) {
+                                console.warn('⚠️ Empty ephemeral data, skipping send');
+                                return;
+                            }
+                            const hexData = Array.from(ephemeralData).map(b => b.toString(16).padStart(2, '0')).join('');
+                            // Validate hex data
+                            if (!hexData || hexData.length === 0) {
+                                console.warn('⚠️ Empty hex data, skipping send');
+                                return;
+                            }
+                            wsRef.current.send(JSON.stringify({
+                                type: 'ephemeral-update',
+                                docId: docId,
+                                data: hexData // Convert to hex string
+                            }));
+                            console.log('📤 Sent ephemeral update:', { docId, dataLength: hexData.length });
+                        }
+                        catch (error) {
+                            console.error('❌ Error encoding/sending ephemeral data:', error);
+                        }
                     }
                 }
                 catch (error) {
@@ -1595,10 +1611,12 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
     // WebSocket connection management with stable dependencies
     const stableOnConnectionChange = useRef(onConnectionChange);
     const stableOnDisconnectReady = useRef(onDisconnectReady);
+    const stableOnSendMessageReady = useRef(onSendMessageReady);
     // Update refs when props change without triggering effect
     useEffect(() => {
         stableOnConnectionChange.current = onConnectionChange;
         stableOnDisconnectReady.current = onDisconnectReady;
+        stableOnSendMessageReady.current = onSendMessageReady;
     });
     useEffect(() => {
         // Close any existing connection before creating a new one
@@ -1664,6 +1682,13 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                         }
                     };
                     stableOnDisconnectReady.current?.(disconnectFn);
+                    // Provide sendMessage function to parent component
+                    const sendMessageFn = (message) => {
+                        if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+                            wsRef.current.send(JSON.stringify(message));
+                        }
+                    };
+                    stableOnSendMessageReady.current?.(sendMessageFn);
                 };
                 ws.onmessage = (event) => {
                     try {
@@ -1694,10 +1719,27 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                             if (onInitialization) {
                                 onInitialization(true);
                             }
-                            // Immediately reflect the current Loro text into the editor after import
+                            // Immediately reflect the current Loro content into the editor after import
                             try {
-                                const currentText = loroDocRef.current.getText(docId).toString();
-                                updateLexicalFromLoro(editor, currentText);
+                                // For lexical-shared-doc, we need to get the structured JSON from the content container
+                                let currentContent = '';
+                                try {
+                                    // Try to get from 'content' container first (structured JSON)
+                                    currentContent = loroDocRef.current.getText('content').toString();
+                                    console.log('📋 Got structured content from "content" container:', currentContent.slice(0, 100) + '...');
+                                }
+                                catch {
+                                    // Fallback to docId container if content doesn't exist
+                                    currentContent = loroDocRef.current.getText(docId).toString();
+                                    console.log('📋 Fallback to docId container:', currentContent.slice(0, 100) + '...');
+                                }
+                                if (currentContent && currentContent.trim().length > 0) {
+                                    updateLexicalFromLoro(editor, currentContent);
+                                    console.log('✅ Successfully updated Lexical editor from snapshot');
+                                }
+                                else {
+                                    console.warn('⚠️ Empty content received from snapshot');
+                                }
                             }
                             catch (e) {
                                 console.warn('⚠️ Could not immediately reflect snapshot to editor:', e);
@@ -1827,6 +1869,30 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                                 console.warn('🧹 Cannot cleanup - missing client ID or awareness ref');
                             }
                         }
+                        else if (data.type === 'paragraph-added') {
+                            // Handle server broadcast when a new paragraph was added
+                            console.log('➕ Received paragraph-added broadcast:', {
+                                docId: data.docId,
+                                message: data.message,
+                                addedBy: data.addedBy
+                            });
+                            // Trigger a sync from Loro to Lexical to reflect the new paragraph
+                            if (data.docId === docId) {
+                                try {
+                                    // Request fresh snapshot to get the updated content
+                                    if (ws.readyState === WebSocket.OPEN) {
+                                        ws.send(JSON.stringify({
+                                            type: 'request-snapshot',
+                                            docId: docId
+                                        }));
+                                        console.log('📞 Requested fresh snapshot after paragraph addition');
+                                    }
+                                }
+                                catch (error) {
+                                    console.warn('Error handling paragraph-added message:', error);
+                                }
+                            }
+                        }
                     }
                     catch (err) {
                         console.error('Error processing WebSocket message in Lexical plugin:', err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@datalayer/lexical-loro",
   "private": false,
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "Collaborative editing plugin for Lexical based on Loro CRDT",
   "main": "lib/index.js",
@@ -35,14 +35,15 @@
     "dev:all:py": "npm run example:py",
     "dev:vite": "npm run example:vite",
     "example": "concurrently \"npm run server\" \"npm run server:py\" \"npm run example:vite\"",
-    "example:js": "concurrently \"npm run server\" \"npm run example:vite\"",    
-    "example:py": "concurrently \"npm run server:py\" \"npm run example:vite\"",
+    "example:js": "concurrently \"npm run server\" \"npm run example:vite\"",
+    "example:py": "concurrently \"npm run server:py:dev\" \"npm run server:py:minimal\" \"npm run example:vite\"",
     "example:vite": "vite",
     "lint": "eslint .",
     "preview": "vite preview",
-    "server": "tsx servers/server.ts",
+    "server": "tsx node-js/server.ts",
     "server:py": "lexical-loro-server",
     "server:py:dev": "python3 -m lexical_loro.cli",
+    "server:py:minimal": "python3 -m lexical_loro.cli_minimal",
     "test": "vitest",
     "test:js": "vitest run",
     "test:py": "python3 -m pytest lexical_loro/tests/ -v",
@@ -51,18 +52,16 @@
   },
   "dependencies": {
     "loro-crdt": "^1.5.10",
-    "react": "^18 || ^19.1.0",
-    "react-dom": "^18 || ^19.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "lexical": "^0.33.1",
     "@lexical/react": "^0.33.1",
     "@lexical/selection": "^0.33.1"
   },
-  "peerDependencies": {
-  },
   "devDependencies": {
     "@eslint/js": "^9.30.1",
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
+    "@types/react": "18.3.20",
+    "@types/react-dom": "18.3.6",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^4.6.0",
     "concurrently": "^9.2.0",