@datalayer/lexical-loro 0.0.1 → 0.0.2

package/README.md

@@ -2,550 +2,667 @@
 
 [![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).
+This package provides two 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
+
+## Quick Start
+
+### Using the Lexical Plugin
+
+```tsx
+import { LoroCollaborativePlugin } from './src/LoroCollaborativePlugin';
+
+function MyEditor() {
+  return (
+    <LexicalComposer initialConfig={editorConfig}>
+      <RichTextPlugin />
+      <LoroCollaborativePlugin 
+        websocketUrl="ws://localhost:8081"
+        docId="my-document"
+        username="user1"
+      />
+    </LexicalComposer>
+  );
+}
+```
+
+### Using the Python Server
+
+```bash
+# Install the Python package
+pip install -e .
+
+# Start the server
+lexical-loro-server --port 8081
+```
 
-**NEW** Now supports both Node.js and Python WebSocket servers!
+## Examples
+
+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
+
+**DISCLAIMER** Collaborative Cursors still need fixes, see [this issue](https://github.com/datalayer/lexical-loro/issues/1).
 
 <div align="center" style="text-align: center">
   <img alt="" src="https://assets.datalayer.tech/lexical-loro.gif" />
 </div>
 
-## Features
+## Core 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
+- 🚀 **Conflict-free**: Uses Loro CRDT to automatically resolve conflicts  
+- 📝 **Lexical Integration**: Seamless integration with Lexical rich text editor
+- 🌐 **WebSocket Server**: Python server for maintaining document state
+- 📡 **Connection Management**: Robust WebSocket connection handling
+- ✨ **Rich Text Support**: Preserves formatting during collaborative editing
+- 🔧 **Extensible**: Plugin-based architecture for easy customization
 
 ## 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
+**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
 
-### Prerequisites
+**Development Dependencies:**
+- **TypeScript**: For type safety
+- **Vite**: For building and development (examples only)
+- **pytest**: Python testing
+- **ESLint**: Code linting
 
-- Node.js (v16 or higher)
-- npm or yarn
-- Python 3.8+ (for Python server option)
-- pip3 (for Python dependencies)
-
-### Installation
-
-1. Install Node.js dependencies:
-   ```bash
-   npm install
-   ```
+## Installation
 
-2. Install Python dependencies (optional - for Python server):
-   ```bash
-   pip3 install -r requirements.txt
-   # or run the setup script
-   ./setup-python.sh
-   ```
+### Core Plugin
 
-### Running the Application
+The Lexical plugin is a single TypeScript/React component that you can copy into your project:
 
-#### Option 1: All Servers (Recommended)
 ```bash
-npm run dev:all
+# Copy the plugin file
+cp src/LoroCollaborativePlugin.tsx your-project/src/
 ```
-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.
 
-#### Option 2: Python Server Only
+**Dependencies required:**
 ```bash
-npm run dev:all:py
+npm install lexical @lexical/react @lexical/selection loro-crdt react react-dom
 ```
-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.
+### Python Server
 
-#### Option 4: Run servers separately
+Install the Python WebSocket server:
 
-**All servers manually:**
 ```bash
-# Terminal 1: Start Node.js WebSocket server
-npm run server
-
-# Terminal 2: Start Python WebSocket server
-npm run server:py
+# Install from this repository
+pip install -e .
 
-# Terminal 3: Start React development server
-npm run dev
+# Or install specific dependencies
+pip install websockets click loro
 ```
 
-**Node.js Server only:**
-```bash
-# Terminal 1: Start Node.js WebSocket server
-npm run server
+## Usage
 
-# Terminal 2: Start React development server
-npm run dev
+### 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>
+  );
+}
 ```
 
-**Python Server only:**
-```bash
-# Terminal 1: Start Python WebSocket server
-npm run server:py
-# or directly: python3 server.py
-
-# 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
+### 2. Python Server Setup
 
-## Project Structure
+Start the WebSocket server:
 
-```
-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
+```bash
+# Default port (8081)
+lexical-loro-server
 
-server.ts                           # WebSocket server for real-time communication
-package.json                        # Dependencies and scripts
-```
+# Custom port
+lexical-loro-server --port 8082
 
-## How It Works
+# With debug logging
+lexical-loro-server --port 8081 --log-level DEBUG
+```
 
-### Loro CRDT Integration
+### 3. Programmatic Server Usage
 
-The application uses Loro CRDT to manage collaborative editing across two different editor types:
+```python
+import asyncio
+from lexical_loro import LoroWebSocketServer
 
-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
+async def main():
+    server = LoroWebSocketServer(port=8081)
+    await server.start()
+    print("Server running on ws://localhost:8081")
 
-The Complete Flow Diagram
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
+## Plugin API
 
-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
+### LoroCollaborativePlugin Props
 
-Protection Against Infinite Loops
+```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)
+}
+```
 
-The system uses several mechanisms to prevent loops:
+### 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>
+  );
+}
+```
 
-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
+### 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');
+    }
+  }}
+/>
+```
 
-When a Loro update is received, the Lexical state is updated through:
+### 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>
+  );
+}
+```
 
-WebSocket receives loro-update message
+### Common Anti-Patterns to Avoid
 
-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
+❌ **Don't** enable plugins immediately:
+```tsx
+// WRONG: Race condition risk
+<LoroCollaborativePlugin websocketUrl="..." />
+<HistoryPlugin /> {/* May interfere with initial sync */}
+```
 
-The bridge is the doc.subscribe() callback on line 1901 - this is what makes Lexical automatically reflect any Loro document changes!
+❌ **Don't** perform immediate document operations:
+```tsx
+// WRONG: May overwrite remote content
+useEffect(() => {
+  editor.update(() => {
+    $getRoot().clear(); // Dangerous before sync!
+  });
+}, []);
+```
 
-### Lexical Integration
+❌ **Don't** ignore initialization status:
+```tsx
+// WRONG: No feedback on connection issues
+<LoroCollaborativePlugin websocketUrl="..." />
+```
 
-The Lexical editor integration includes:
+### Debugging Initialization Issues
 
-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
+If initialization fails, check:
 
-### WebSocket Communication
+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
 
-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
+```bash
+# Enable debug logging
+export LEXICAL_LORO_LOG_LEVEL=DEBUG
+lexical-loro-server
+```
 
-### Real-time Updates
+## Server API
 
-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
+### LoroWebSocketServer Class
 
-### Initial Content Synchronization
+```python
+from lexical_loro import LoroWebSocketServer
 
-When a new collaborator joins:
+# Create server instance
+server = LoroWebSocketServer(
+    port=8081,           # Server port
+    host="localhost"     # Server host
+)
 
-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
+# Start server
+await server.start()
 
-The server maintains the latest document snapshot to ensure new collaborators always see existing content.
+# Shutdown server
+await server.shutdown()
+```
 
-## Configuration
+### Supported Message Types
 
-### WebSocket Server URL
+The server handles these WebSocket message types:
 
-You can configure the WebSocket server URL in the UI or by modifying the default in `CollaborativeEditor.tsx`:
+- `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
 
-```typescript
-const [websocketUrl, setWebsocketUrl] = useState('ws://localhost:8080')
-```
+## Examples
 
-### Server Port
+For complete working examples and demonstrations, see the `src/examples/` directory:
 
-To change the server port, modify `server.ts`:
+```bash
+# Run the example application
+npm install
+npm run example
 
-```typescript
-const server = new LoroWebSocketServer(8080); // Change port here
+# This starts both Node.js and Python servers plus a React demo app
+# Open http://localhost:5173 to see dual editor interface
 ```
 
-## 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
+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
 
-## Production Deployment
+See `src/examples/README.md` for detailed example documentation.
 
-1. Build the application:
-   ```bash
-   npm run build
-   ```
-
-2. Deploy the `dist` folder to your web server
+## Project Structure
 
-3. Deploy the WebSocket server to your backend infrastructure
+### Core Components
 
-4. Update the WebSocket URL in the application to point to your production server
+```
+src/
+├── LoroCollaborativePlugin.tsx         # Main Lexical plugin for collaboration
+└── vite-env.d.ts                       # TypeScript definitions
 
-## Contributing
+lexical_loro/                           # Python WebSocket server package
+├── __init__.py                         # Package exports
+├── server.py                           # WebSocket server implementation  
+├── cli.py                              # Command line interface
+└── tests/                              # Python test suite
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+pyproject.toml                          # Python package configuration
+```
 
-## License
+### Examples Directory
 
-This project is open source and available under the [MIT License](LICENSE).
+```
+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)
+```
 
-## Acknowledgments
+### Archive
 
-- [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)
+```
+src/archive/                            # Historical plugin implementations
+├── LoroCollaborativePlugin0.tsx        # Previous versions for reference
+├── LoroCollaborativePlugin1.tsx
+├── LoroCollaborativePlugin2.tsx
+├── LoroCollaborativePlugin3.tsx
+├── LoroCollaborativePlugin4.tsx
+└── LoroCollaborativePlugin5.tsx
+```
 
-# Lexical Loro Python Package
+## How It Works
 
-A Python package for Lexical + Loro CRDT integration, providing a WebSocket server for real-time collaborative text editing.
+### Architecture Overview
 
-## Features
+The collaboration system consists of two main components:
 
-- **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
+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
 
-## Installation
+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
 
-### From PyPI (when published)
+### Data Flow
 
-```bash
-pip install lexical-loro
 ```
-
-### Local Development
-
-```bash
-# Install in development mode
-pip install -e "python_src/[dev]"
+User Types → Lexical Editor → Plugin → Loro CRDT → WebSocket
+                                                        ↓
+WebSocket ← Loro CRDT ← Plugin ← Lexical Editor ← Other Users
 ```
 
-## Usage
+### CRDT Integration Process
 
-### Command Line
+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
 
-Start the server using the command line interface:
+### Connection Management
 
-```bash
-# Start server on default port (8081)
-lexical-loro-server
+- **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
 
-# Start server on custom port
-lexical-loro-server --port 8082
+### Lexical Integration
 
-# Start with debug logging
-lexical-loro-server --log-level DEBUG
-```
+The Lexical editor integration includes:
 
-### Programmatic Usage
+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
 
-```python
-import asyncio
-from lexical_loro import LoroWebSocketServer
+### WebSocket Communication
 
-async def main():
-    server = LoroWebSocketServer(port=8081)
-    await server.start()
+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
 
-if __name__ == "__main__":
-    asyncio.run(main())
-```
+### Real-time Updates
 
-### Integration with Node.js/TypeScript Projects
+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
 
-Update your `package.json` scripts:
+### Initial Content Synchronization
 
-```json
-{
-  "scripts": {
-    "server:py": "lexical-loro-server",
-    "dev:py": "concurrently \"lexical-loro-server\" \"npm run dev\""
-  }
-}
-```
+When a new collaborator joins:
 
-## API Reference
+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
 
-### LoroWebSocketServer
+The server maintains the latest document snapshot to ensure new collaborators always see existing content.
 
-Main server class for handling WebSocket connections and Loro document management.
+## Configuration
 
-#### Constructor
+### Plugin Configuration
 
-```python
-server = LoroWebSocketServer(port=8081)
+```tsx
+<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)
+/>
 ```
 
-#### Methods
+### Server Configuration
 
-- `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
-
-### Client
+```python
+# Via command line
+lexical-loro-server --port 8081 --host localhost --log-level DEBUG
 
-Represents a connected client with metadata.
+# Via environment variables
+export LEXICAL_LORO_PORT=8081
+export LEXICAL_LORO_HOST=localhost
+export LEXICAL_LORO_LOG_LEVEL=DEBUG
+lexical-loro-server
 
-```python
-class Client:
-    def __init__(self, websocket, client_id):
-        self.websocket = websocket
-        self.id = client_id
-        self.color = self._generate_color()
+# Programmatically
+server = LoroWebSocketServer(port=8081, host="localhost")
 ```
 
+### 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
 
-### Setup Development Environment
+### Core Components Development
 
+**Plugin Development:**
 ```bash
-# Install development dependencies
-pip install -e "python_src/[dev]"
+# The plugin is a single TypeScript file
+src/LoroCollaborativePlugin.tsx
 
-# Run tests
-pytest
-
-# Run tests with coverage
-pytest --cov=lexical_loro --cov-report=html
+# Dependencies for plugin development
+npm install lexical @lexical/react @lexical/selection loro-crdt
+```
 
-# Format code
-black python_src/
+**Server Development:**  
+```bash
+# Install Python package in development mode
+pip install -e ".[dev]"
 
-# Lint code
-ruff python_src/
+# Run tests
+pytest lexical_loro/tests/ -v
 
-# Type checking
-mypy python_src/
+# Start server in development mode  
+python3 -m lexical_loro.cli --port 8081 --log-level DEBUG
 ```
 
 ### Testing
 
-The package includes comprehensive tests for:
-
-- WebSocket connection handling
-- Loro document operations
-- Message processing
-- Client management
-- Error handling
-
-Run tests:
-
+**Plugin Testing:**
 ```bash
-pytest tests/ -v
+npm run test              # Run Vitest tests
+npm run test:js          # Run tests once
 ```
 
-### Building
-
-Build the package:
-
+**Server Testing:**
 ```bash
-pip install build
-python -m build
+npm run test:py          # Run Python tests
+npm run test:py:watch    # Run in watch mode
+npm run test:py:coverage # Run with coverage
 ```
 
-## Protocol
-
-The server communicates with clients using a JSON-based WebSocket protocol:
-
-### Message Types
-
-- `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
+### Example Development
 
-### Example Messages
-
-```json
-{
-  "type": "loro-update",
-  "docId": "lexical-shared-doc",
-  "updateHex": "deadbeef..."
-}
+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)
 ```
 
-## Configuration
-
-### Environment Variables
+## Contributing
 
-- `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)
+We welcome contributions to both the Lexical plugin and Python server:
 
-### Supported Documents
+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
+4. Add tests for new functionality
+5. Update documentation as needed
+6. Submit a pull request
 
-The server pre-initializes several document types:
+### Development Guidelines
 
-- `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
+- **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
 
 ## 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,7 @@ interface LoroCollaborativePluginProps {
         userName: string;
         isCurrentUser?: boolean;
     }>) => void;
+    onInitialization?: (success: boolean) => 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 }: 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 }) {
     const [editor] = useLexicalComposerContext();
     const wsRef = useRef(null);
     const loroDocRef = useRef(new LoroDoc());
@@ -1686,6 +1690,10 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                             loroDocRef.current.import(snapshot);
                             hasReceivedInitialSnapshot.current = true;
                             console.log('📄 Lexical editor received and applied initial snapshot');
+                            // Notify parent component about successful initialization
+                            if (onInitialization) {
+                                onInitialization(true);
+                            }
                             // Immediately reflect the current Loro text into the editor after import
                             try {
                                 const currentText = loroDocRef.current.getText(docId).toString();
@@ -1693,6 +1701,10 @@ export function LoroCollaborativePlugin({ websocketUrl, docId, onConnectionChang
                             }
                             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') {
@@ -1842,6 +1854,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.2",
   "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,28 +30,34 @@
   "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\" \"npm run example:vite\"",
+    "example:vite": "vite",
     "lint": "eslint .",
     "preview": "vite preview",
     "server": "tsx servers/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",
     "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-dom": "^18 || ^19.1.0",
+    "lexical": "^0.33.1",
+    "@lexical/react": "^0.33.1",
+    "@lexical/selection": "^0.33.1"
+  },
+  "peerDependencies": {
   },
   "devDependencies": {
     "@eslint/js": "^9.30.1",