@datalayer/lexical-loro 0.0.1 → 0.0.3

package/README.md

@@ -2,386 +2,248 @@
 
 [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
 
-# Collaborative Plugin for Lexical based on Loro CRDT
+# ✍️ 🦜 Lexical Loro - Collaborative Plugin for Lexical with Loro CRDT
 
-A real-time collaborative editing application for [Lexical](https://github.com/facebook/lexical) built with [Loro CRDT](https://github.com/loro-dev), React, TypeScript, Vite with a Python WebSocket server using [loro-py](https://github.com/loro-dev/loro-py) to maintain the Lexical JSON model sever-side
+A collaborative editing plugin for [Lexical](https://github.com/facebook/lexical) Rich Editor built with [Loro](https://github.com/loro-dev) CRDT, providing real-time collaborative editing capabilities with conflict-free synchronization.
 
-Features both simple text editing and rich text editing with Lexical. Multiple users can edit the same documents simultaneously with conflict-free collaborative editing powered by Conflict-free Replicated Data Types (CRDTs).
+## Core Components
 
-**DISCLAIMER** Collaborative Cursors still need fixes, see [this issue](https://github.com/datalayer/lexical-loro/issues/1).
-
-**NEW** Now supports both Node.js and Python WebSocket servers!
-
-<div align="center" style="text-align: center">
-  <img alt="" src="https://assets.datalayer.tech/lexical-loro.gif" />
-</div>
-
-## Features
-
-- 🔄 **Real-time Collaboration**: Multiple users can edit the same document simultaneously
-- 🚀 **Conflict-free**: Uses Loro CRDT to automatically resolve conflicts
-- 📝 **Dual Editor Support**: Choose between simple text area or rich text Lexical editor
-- 🌐 **Multi-server Support**: Choose between Node.js and Python WebSocket servers
-- ⚡ **Fast Development**: Built with Vite for lightning-fast development
-- 🎨 **Responsive Design**: Works on desktop and mobile devices
-- 📡 **Connection Status**: Visual indicators for connection state
-- ✨ **Rich Text Features**: Bold, italic, underline with real-time formatting sync
-- 🔧 **Server Selection**: Switch between Node.js and Python backends
+This package provides three main components for building collaborative text editors:
 
-## Technology Stack
-
-- **Frontend**: React 19 + TypeScript + Vite
-- **CRDT Library**: Loro CRDT
-- **Rich Text Editor**: Lexical (Facebook's extensible text editor)
-- **Backend Options**: 
-  - Node.js + TypeScript + ws library
-  - Python + loro-py + websockets library
-- **Real-time Communication**: WebSockets (ws)
-- **Styling**: CSS3 with responsive design
-- **Development Tools**: ESLint, tsx, concurrently
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js (v16 or higher)
-- npm or yarn
-- Python 3.8+ (for Python server option)
-- pip3 (for Python dependencies)
+1. **`LoroCollaborativePlugin.tsx`** - A Lexical plugin that integrates Loro CRDT for real-time collaborative editing
+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
 
-### Installation
+## Quick Start
 
-1. Install Node.js dependencies:
-   ```bash
-   npm install
-   ```
+### Using the Lexical Plugin
 
-2. Install Python dependencies (optional - for Python server):
-   ```bash
-   pip3 install -r requirements.txt
-   # or run the setup script
-   ./setup-python.sh
-   ```
-
-### Running the Application
-
-#### Option 1: All Servers (Recommended)
-```bash
-npm run dev:all
-```
-This starts **both** WebSocket servers (Node.js on port 8080 and Python on port 8081) plus the React development server (port 5173). You can then switch between servers using the UI.
+```tsx
+import { LoroCollaborativePlugin } from './src/LoroCollaborativePlugin';
 
-#### Option 2: Python Server Only
-```bash
-npm run dev:all:py
+function MyEditor() {
+  return (
+    <LexicalComposer initialConfig={editorConfig}>
+      <RichTextPlugin />
+      <LoroCollaborativePlugin 
+        websocketUrl="ws://localhost:8081"
+        docId="my-document"
+        username="user1"
+      />
+    </LexicalComposer>
+  );
+}
 ```
-This starts only the Python WebSocket server (port 8081) and React development server.
 
-#### Option 3: Node.js Server Only
-```bash
-npm run dev:all:js
-```
-This starts only the Node.js WebSocket server (port 8080) and React development server.
+### Using the LexicalModel Library
 
-#### Option 4: Run servers separately
+```python
+from lexical_loro import LexicalModel
 
-**All servers manually:**
-```bash
-# Terminal 1: Start Node.js WebSocket server
-npm run server
+# Create a new document
+model = LexicalModel.create_document("my-document")
 
-# Terminal 2: Start Python WebSocket server
-npm run server:py
+# Add content
+model.add_block({
+    "text": "My Document",
+    "format": 0,
+    "style": ""
+}, "heading1")
 
-# Terminal 3: Start React development server
-npm run dev
-```
+model.add_block({
+    "text": "This is a paragraph.",
+    "format": 0,
+    "style": ""
+}, "paragraph")
 
-**Node.js Server only:**
-```bash
-# Terminal 1: Start Node.js WebSocket server
-npm run server
+# Save to file
+model.save_to_file("document.json")
 
-# Terminal 2: Start React development server
-npm run dev
+# Load from file
+loaded_model = LexicalModel.load_from_file("document.json")
 ```
 
-**Python Server only:**
-```bash
-# Terminal 1: Start Python WebSocket server
-npm run server:py
-# or directly: python3 server.py
+### Using the Python Server
 
-# Terminal 2: Start React development server
-npm run dev
-```
-
-2. In another terminal, start the React development server:
-   ```bash
-   npm run dev
-   ```
-
-### Usage
-
-1. Open your browser and navigate to the development server URL (typically `http://localhost:5173`)
-2. **Select Server Type**: Use the server selection radio buttons to choose:
-   - **Node.js Server**: `ws://localhost:8080` (TypeScript implementation)
-   - **Python Server**: `ws://localhost:8081` (Python + loro-py implementation)
-   
-   💡 **Tip**: When using `npm run dev:all`, both servers are running simultaneously, so you can switch between them in real-time!
-
-3. **Choose Editor Type**: Click the tabs to select:
-   - **Simple Text Editor**: A basic textarea for plain text collaboration
-   - **Rich Text Editor (Lexical)**: A full-featured rich text editor with Bold/Italic/Underline formatting
-4. Start typing in either editor
-5. Open another browser window/tab or share the URL with others
-6. All users will see real-time updates as they type in the same editor type
-7. Each editor maintains its own document state (they are separate collaborative spaces)
-
-**Note**: You must disconnect from the current server before switching to a different server type.
-
-### Testing Collaboration
-
-To test the real-time collaboration:
-
-1. Open multiple browser tabs/windows to the development server URL
-2. **Select the same server** in all tabs (Node.js or Python)
-3. **Test Simple Text Editor**:
-   - Keep all tabs on the "Simple Text Editor" tab
-   - Start typing in one window - you'll see the changes appear in other windows instantly
-4. **Test Lexical Rich Text Editor**:
-   - Switch all tabs to the "Rich Text Editor (Lexical)" tab
-   - Try formatting text with the toolbar buttons (Bold, Italic, Underline)
-   - Changes and formatting will sync in real-time across all tabs
-5. **Test Cross-Server Compatibility**: 
-   - Verify that documents are properly synchronized between Node.js and Python servers
-   - Each server maintains its own document state
-6. **Test Independent Documents**:
-   - Have some tabs on "Simple Text Editor" and others on "Lexical Editor"
-   - Notice that each editor type maintains its own separate document
-5. **New collaborators will automatically receive the current document content** when they join
-
-**Note**: The application now properly synchronizes initial content:
-- When a new collaborator joins, they automatically receive the current document state for both editors
-- If no snapshot is available on the server, existing clients will provide their current state
-- The first client to join with content will automatically share their document state
-- Each editor type (simple text vs Lexical) maintains separate collaborative documents
-
-## Project Structure
+```bash
+# Install the Python package
+pip install -e .
 
+# Start the server
+lexical-loro-server --port 8081
 ```
-src/
-├── App.tsx                         # Main application component with tabbed interface
-├── App.css                         # Application styles
-├── CollaborativeEditor.tsx         # Simple text editor component with Loro CRDT integration
-├── CollaborativeEditor.css         # Simple editor styles
-├── LexicalCollaborativeEditor.tsx  # Lexical rich text editor component
-├── LexicalCollaborativeEditor.css  # Lexical editor styles
-├── LoroCollaborativePlugin.tsx     # Lexical plugin for Loro CRDT integration
-├── main.tsx                        # React application entry point
-└── vite-env.d.ts                   # Vite type definitions
-
-server.ts                           # WebSocket server for real-time communication
-package.json                        # Dependencies and scripts
-```
-
-## How It Works
 
-### Loro CRDT Integration
+## Examples
 
-The application uses Loro CRDT to manage collaborative editing across two different editor types:
+For complete working examples, see the `src/examples/` directory which contains:
+- Full React application with dual editor support
+- Server selection interface
+- Connection status indicators
+- Rich text formatting examples
 
-1. **Document Creation**: Each editor type creates its own Loro document with a unique identifier:
-   - Simple Text Editor: `shared-text`
-   - Lexical Editor: `lexical-shared-doc`
-2. **Local Changes**: When a user types, changes are applied to the corresponding local Loro document
-3. **Change Detection**: The application detects insertions, deletions, and replacements
-4. **Synchronization**: Changes are serialized and sent to other clients via WebSocket with document ID
-5. **Conflict Resolution**: Loro CRDT automatically merges changes without conflicts
-
-The Complete Flow Diagram
-
-
-Remote User Types
-       ↓
-WebSocket Message
-       ↓
-loro-update received
-       ↓ 
-loroDocRef.current.import(update)
-       ↓
-doc.subscribe() callback fires
-       ↓
-updateLexicalFromLoro(editor, newText)
-       ↓
-editor.update() with new content
-       ↓
-Lexical State Updated
-       ↓
-UI Re-renders with New Content
-
-Protection Against Infinite Loops
-
-The system uses several mechanisms to prevent loops:
-
-isLocalChange.current flag - Prevents local changes from triggering remote updates
-{ tag: 'collaboration' } on editor.update() - Allows the update listener to ignore these changes
-JSON comparison in updateLexicalFromLoro to avoid redundant updates
-
-When a Loro update is received, the Lexical state is updated through:
-
-WebSocket receives loro-update message
-
-loroDocRef.current.import(update) applies the change to Loro
-doc.subscribe() callback automatically fires
-updateLexicalFromLoro() converts Loro text to Lexical state
-editor.setEditorState() or DOM manipulation updates the editor
-
-The bridge is the doc.subscribe() callback on line 1901 - this is what makes Lexical automatically reflect any Loro document changes!
-
-### 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
+**DISCLAIMER** Collaborative Cursors still need fixes, see [this issue](https://github.com/datalayer/lexical-loro/issues/1).
 
-### Real-time Updates
+<div align="center" style="text-align: center">
+  <img alt="" src="https://assets.datalayer.tech/lexical-loro.gif" />
+</div>
 
-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
+## Core Features
 
-### Initial Content Synchronization
+- 🔄 **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
 
-When a new collaborator joins:
+## Technology Stack
 
-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
+**Core Dependencies:**
+- **Lexical**: v0.33.1 (Facebook's extensible text editor framework)
+- **Loro CRDT**: v1.5.10 (Conflict-free replicated data types)
+- **React**: 18/19 (for plugin hooks and components)
+- **Python**: 3.8+ with loro-py and websockets
 
-The server maintains the latest document snapshot to ensure new collaborators always see existing content.
+**Development Dependencies:**
+- **TypeScript**: For type safety
+- **Vite**: For building and development (examples only)
+- **pytest**: Python testing
+- **ESLint**: Code linting
 
-## Configuration
+## Installation
 
-### WebSocket Server URL
+### Core Plugin
 
-You can configure the WebSocket server URL in the UI or by modifying the default in `CollaborativeEditor.tsx`:
+The Lexical plugin is a single TypeScript/React component that you can copy into your project:
 
-```typescript
-const [websocketUrl, setWebsocketUrl] = useState('ws://localhost:8080')
+```bash
+# Copy the plugin file
+cp src/LoroCollaborativePlugin.tsx your-project/src/
 ```
 
-### Server Port
-
-To change the server port, modify `server.ts`:
-
-```typescript
-const server = new LoroWebSocketServer(8080); // Change port here
+**Dependencies required:**
+```bash
+npm install lexical @lexical/react @lexical/selection loro-crdt react react-dom
 ```
 
-## Development Scripts
-
-- `npm run dev` - Start React development server
-- `npm run server` - Start WebSocket server
-- `npm run dev:all` - Start both server and client
-- `npm run build` - Build for production
-- `npm run lint` - Run ESLint
-- `npm run preview` - Preview production build
-
-## Production Deployment
-
-1. Build the application:
-   ```bash
-   npm run build
-   ```
+### Python Server
 
-2. Deploy the `dist` folder to your web server
-
-3. Deploy the WebSocket server to your backend infrastructure
-
-4. Update the WebSocket URL in the application to point to your production server
-
-## Contributing
+Install the Python WebSocket server:
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## License
-
-This project is open source and available under the [MIT License](LICENSE).
-
-## Acknowledgments
-
-- [Loro CRDT](https://loro.dev/) - The CRDT library powering collaborative editing
-- [Vite](https://vitejs.dev/) - Fast development build tool
-- [React](https://reactjs.org/) - UI library
-- [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
-
-# Lexical Loro Python Package
-
-A Python package for Lexical + Loro CRDT integration, providing a WebSocket server for real-time collaborative text editing.
-
-## Features
-
-- **Real-time collaboration**: WebSocket server for live document collaboration
-- **Loro CRDT integration**: Uses Loro CRDT for conflict-free replicated data types
-- **Lexical compatibility**: Designed to work with Lexical rich text editor
-- **Ephemeral data support**: Handles cursor positions and selections
-- **Multiple document support**: Manages multiple collaborative documents
+```bash
+# Install from this repository
+pip install -e .
 
-## Installation
+# Or install specific dependencies
+pip install websockets click loro
+```
 
-### From PyPI (when published)
+## Usage
 
-```bash
-pip install lexical-loro
+### 1. Lexical Plugin Integration
+
+Add the plugin to your Lexical editor:
+
+```tsx
+import { LexicalComposer } from '@lexical/react/LexicalComposer';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable';
+import { LoroCollaborativePlugin } from './LoroCollaborativePlugin';
+
+const editorConfig = {
+  namespace: 'MyEditor',
+  theme: {},
+  onError: console.error,
+};
+
+function CollaborativeEditor() {
+  return (
+    <LexicalComposer initialConfig={editorConfig}>
+      <div className="editor-container">
+        <RichTextPlugin
+          contentEditable={<ContentEditable className="editor-input" />}
+          placeholder={<div className="editor-placeholder">Start typing...</div>}
+          ErrorBoundary={() => <div>Error occurred</div>}
+        />
+        <LoroCollaborativePlugin 
+          websocketUrl="ws://localhost:8081"
+          docId="shared-document"
+          username="user123"
+        />
+      </div>
+    </LexicalComposer>
+  );
+}
 ```
 
-### Local Development
+### 2. Standalone LexicalModel Library
 
-```bash
-# Install in development mode
-pip install -e "python_src/[dev]"
+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', '')}")
 ```
 
-## Usage
+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
 
-### Command Line
+### 3. Python Server Setup
 
-Start the server using the command line interface:
+Start the WebSocket server:
 
 ```bash
-# Start server on default port (8081)
+# Default port (8081)
 lexical-loro-server
 
-# Start server on custom port
+# Custom port
 lexical-loro-server --port 8082
 
-# Start with debug logging
-lexical-loro-server --log-level DEBUG
+# With debug logging
+lexical-loro-server --port 8081 --log-level DEBUG
 ```
 
-### Programmatic Usage
+### 4. Programmatic Server Usage
 
 ```python
 import asyncio
@@ -390,162 +252,204 @@ from lexical_loro import LoroWebSocketServer
 async def main():
     server = LoroWebSocketServer(port=8081)
     await server.start()
+    print("Server running on ws://localhost:8081")
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### Integration with Node.js/TypeScript Projects
+## Plugin API
 
-Update your `package.json` scripts:
+For detailed API documentation, see [`docs/API.md`](docs/API.md).
 
-```json
-{
-  "scripts": {
-    "server:py": "lexical-loro-server",
-    "dev:py": "concurrently \"lexical-loro-server\" \"npm run dev\""
-  }
+### Quick Reference
+
+```tsx
+interface LoroCollaborativePluginProps {
+  websocketUrl: string;          // WebSocket server URL
+  docId: string;                 // Unique document identifier
+  username: string;              // User identifier
+  userColor?: string;            // User cursor color (optional)
+  debug?: boolean;               // Enable debug logging (optional)
 }
 ```
 
-## API Reference
+## Initialization Best Practices
 
-### LoroWebSocketServer
+⚠️ **Important**: Always wait for collaboration initialization before enabling other plugins.
 
-Main server class for handling WebSocket connections and Loro document management.
+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
 
-#### Constructor
+## Examples
 
-```python
-server = LoroWebSocketServer(port=8081)
+For complete working examples and demonstrations, see the `src/examples/` directory:
+
+```bash
+# Run the example application
+npm install
+npm run example
+
+# This starts both Node.js and Python servers plus a React demo app
+# Open http://localhost:5173 to see dual editor interface
 ```
 
-#### Methods
+The examples include:
+- **Complete React App**: Full collaborative editor with UI
+- **Server Selection**: Switch between Node.js and Python backends  
+- **Dual Editors**: Simple text area and rich Lexical editor
+- **Real-time Demo**: Multi-user collaboration testing
 
-- `start()`: Start the WebSocket server
-- `shutdown()`: Gracefully shutdown the server
-- `handle_client(websocket)`: Handle new client connections
-- `handle_message(client_id, message)`: Process messages from clients
+See `src/examples/README.md` for detailed example documentation.
 
-### Client
+## Project Structure
 
-Represents a connected client with metadata.
+### Core Components
 
-```python
-class Client:
-    def __init__(self, websocket, client_id):
-        self.websocket = websocket
-        self.id = client_id
-        self.color = self._generate_color()
+```
+src/
+├── LoroCollaborativePlugin.tsx         # Main Lexical plugin for collaboration
+└── vite-env.d.ts                       # TypeScript definitions
+
+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
 ```
 
-## Development
+### Examples Directory
 
-### Setup Development Environment
+```
+src/examples/                           # Complete demo application
+├── App.tsx                             # Demo app with dual editors
+├── LexicalCollaborativeEditor.tsx      # Rich text editor example
+├── TextAreaCollaborativeEditor.tsx     # Simple text editor example
+├── ServerSelector.tsx                  # Server selection UI
+├── LexicalToolbar.tsx                  # Rich text toolbar
+├── main.tsx                            # Demo app entry point
+└── *.css                               # Styling for examples
+
+servers/
+└── server.ts                           # Node.js server (for comparison)
+```
 
-```bash
-# Install development dependencies
-pip install -e "python_src/[dev]"
+### Archive
 
-# Run tests
-pytest
+```
+src/archive/                            # Historical plugin implementations
+├── LoroCollaborativePlugin0.tsx        # Previous versions for reference
+├── LoroCollaborativePlugin1.tsx
+├── LoroCollaborativePlugin2.tsx
+├── LoroCollaborativePlugin3.tsx
+├── LoroCollaborativePlugin4.tsx
+└── LoroCollaborativePlugin5.tsx
+```
 
-# Run tests with coverage
-pytest --cov=lexical_loro --cov-report=html
+## Architecture
 
-# Format code
-black python_src/
+For detailed architecture documentation, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
-# Lint code
-ruff python_src/
+### System Overview
 
-# Type checking
-mypy python_src/
-```
+The collaboration system consists of three main components:
 
-### Testing
+1. **LoroCollaborativePlugin** (Client-side) - Lexical integration
+2. **LoroWebSocketServer** (Server-side) - Real-time synchronization  
+3. **LexicalModel** (Standalone Library) - Independent document model
 
-The package includes comprehensive tests for:
+### Data Flow
 
-- WebSocket connection handling
-- Loro document operations
-- Message processing
-- Client management
-- Error handling
+```
+User Types → Lexical Editor → Plugin → Loro CRDT → WebSocket
+                                                        ↓
+WebSocket ← Loro CRDT ← Plugin ← Lexical Editor ← Other Users
+```
 
-Run tests:
+## Configuration
 
-```bash
-pytest tests/ -v
-```
+For detailed configuration options, see [`docs/API.md`](docs/API.md).
 
-### Building
+### Quick Configuration
 
-Build the package:
+```tsx
+// Plugin configuration
+<LoroCollaborativePlugin 
+  websocketUrl="ws://localhost:8081"
+  docId="my-document"
+  username="user123"
+  debug={true}
+/>
+```
 
 ```bash
-pip install build
-python -m build
+# Server configuration
+lexical-loro-server --port 8081 --log-level DEBUG
 ```
 
-## Protocol
+## Development
 
-The server communicates with clients using a JSON-based WebSocket protocol:
+For comprehensive development guidelines, see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
 
-### Message Types
+### Quick Start
 
-- `loro-update`: Apply Loro CRDT updates
-- `snapshot`: Full document snapshots
-- `request-snapshot`: Request current document state
-- `ephemeral-update`: Cursor and selection updates
-- `awareness-update`: User presence information
+```bash
+# Install dependencies
+npm install
+pip install -e ".[dev]"
 
-### Example Messages
+# Run tests
+npm test
+npm run test:py
 
-```json
-{
-  "type": "loro-update",
-  "docId": "lexical-shared-doc",
-  "updateHex": "deadbeef..."
-}
+# Start development server
+lexical-loro-server --log-level DEBUG
 ```
 
-## Configuration
+## Contributing
 
-### Environment Variables
+We welcome contributions! Please see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for detailed guidelines.
 
-- `LEXICAL_LORO_PORT`: Default server port (default: 8081)
-- `LEXICAL_LORO_HOST`: Host to bind to (default: localhost)
-- `LEXICAL_LORO_LOG_LEVEL`: Logging level (default: INFO)
+### Quick Contributing Guide
 
-### Supported Documents
+1. Fork the repository
+2. Create a feature branch  
+3. Focus changes on core components
+4. Add tests for new functionality
+5. Update documentation as needed
+6. Submit a pull request
 
-The server pre-initializes several document types:
+## Documentation
 
-- `shared-text`: Basic text document
-- `lexical-shared-doc-v0`: Minimal plugin document
-- `lexical-shared-doc-v1`: Full-featured plugin document
-- `lexical-shared-doc-v2`: Clean JSON plugin document
-- `lexical-shared-doc-v3`: Text-only plugin document
-- `lexical-shared-doc-v4`: Smart hybrid plugin document
+- **[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
 
-MIT License - see LICENSE file for details.
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Run the test suite
-6. Submit a pull request
-
-## Support
-
-For issues and questions:
+This project is open source and available under the [MIT License](LICENSE).
 
-- GitHub Issues: https://github.com/datalayer/lexical-loro/issues
-- Documentation: https://github.com/datalayer/lexical-loro#readme
+## Acknowledgments
 
+- [Loro CRDT](https://loro.dev/) - The CRDT library powering collaborative editing
+- [Lexical](https://lexical.dev/) - Facebook's extensible text editor framework  
+- [React](https://reactjs.org/) - UI library for plugin hooks
+- [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) - Real-time communication

package/lib/LoroCollaborativePlugin.d.ts

@@ -9,6 +9,8 @@ interface LoroCollaborativePluginProps {
         userName: string;
         isCurrentUser?: boolean;
     }>) => void;
+    onInitialization?: (success: boolean) => void;
+    onSendMessageReady?: (sendMessageFn: (message: any) => void) => void;
 }
-export declare function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange }: 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

@@ -1,4 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
 import { useEffect, useRef, useCallback, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { $createParagraphNode, $getRoot, $getSelection, $isRangeSelection, $getNodeByKey, $isTextNode, $isElementNode, $isLineBreakNode, $createTextNode, createState, $getState, $setState } from 'lexical';
@@ -623,7 +627,7 @@ class CursorAwareness {
         return this.ephemeralStore.getAllStates();
     }
 }
-export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange }) {
+export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChange, onDisconnectReady, onPeerIdChange, onAwarenessChange, onInitialization, onSendMessageReady }) {
     const [editor] = useLexicalComposerContext();
     const wsRef = useRef(null);
     const loroDocRef = useRef(new LoroDoc());
@@ -894,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) {
@@ -1591,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
@@ -1660,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 {
@@ -1686,13 +1715,38 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                             loroDocRef.current.import(snapshot);
                             hasReceivedInitialSnapshot.current = true;
                             console.log('📄 Lexical editor received and applied initial snapshot');
-                            // Immediately reflect the current Loro text into the editor after import
+                            // Notify parent component about successful initialization
+                            if (onInitialization) {
+                                onInitialization(true);
+                            }
+                            // 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);
+                                // Notify parent component about failed initialization
+                                if (onInitialization) {
+                                    onInitialization(false);
+                                }
                             }
                         }
                         else if (data.type === 'ephemeral-update' || data.type === 'ephemeral-event') {
@@ -1815,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);
@@ -1842,6 +1920,10 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                 ws.onerror = (err) => {
                     isConnectingRef.current = false;
                     console.error('WebSocket error in Lexical plugin:', err);
+                    // Notify initialization failure if we haven't received initial content yet
+                    if (!hasReceivedInitialSnapshot.current && onInitialization) {
+                        onInitialization(false);
+                    }
                 };
             }
             catch (err) {

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from "./LoroCollaborativePlugin";

package/lib/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the MIT License.
+ */
+export * from "./LoroCollaborativePlugin";

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@datalayer/lexical-loro",
   "private": false,
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
+  "description": "Collaborative editing plugin for Lexical based on Loro CRDT",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
-    "lib/**/*"
+    "lib/**/*.*"
+  ],
+  "keywords": [
+    "lexical",
+    "loro",
+    "crdt",
+    "collaborative",
+    "editor",
+    "plugin",
+    "react"
   ],
   "repository": {
     "type": "git",
@@ -18,33 +30,38 @@
   "scripts": {
     "build": "tsc -b && vite build",
     "clean": "rimraf dist lib",
+    "dev": "npm run example",
+    "dev:all:js": "npm run example:js",
+    "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: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",
-    "test:py": "python3 -m pytest lexical_loro/tests/ -v",
-    "test:py:watch": "python3 -m pytest lexical_loro/tests/ -v --tb=short -f",
-    "test:py:coverage": "python3 -m pytest lexical_loro/tests/ --cov=. --cov-report=html --cov-report=term",
+    "server:py:minimal": "python3 -m lexical_loro.cli_minimal",
     "test": "vitest",
     "test:js": "vitest run",
-    "dev": "concurrently \"npm run server\" \"npm run server:py\" \"npm run dev:vite\"",
-    "dev:vite": "vite",
-    "dev:all:py": "concurrently \"npm run server:py\" \"npm run dev:vite\"",
-    "dev:all:js": "concurrently \"npm run server\" \"npm run dev:vite\""
+    "test:py": "python3 -m pytest lexical_loro/tests/ -v",
+    "test:py:coverage": "python3 -m pytest lexical_loro/tests/ --cov=. --cov-report=html --cov-report=term",
+    "test:py:watch": "python3 -m pytest lexical_loro/tests/ -v --tb=short -f"
   },
   "dependencies": {
-    "@lexical/react": "^0.33.1",
-    "@lexical/selection": "^0.33.1",
-    "lexical": "^0.33.1",
     "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"
   },
   "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",