realtimecursor/README.md

Real-time collaboration system with cursor tracking and approval workflow

# RealtimeCursor SDK

This repository contains multiple versions of the RealtimeCursor SDK for real-time collaboration features.

## Available Versions

### Fixed SDK (v1.1.0)

A fixed version of the original SDK that resolves critical issues:

1. **Infinite Loop Issue**: Prevents the infinite loop of `room-users` events by tracking project join status
2. **User Duplication**: Prevents duplicate users in the collaborators list
3. **Cursor Tracking**: Improves cursor position tracking and updates
4. **Connection Stability**: Better connection handling and reconnection logic

### Enhanced SDK (v1.2.0)

A user-friendly version with additional features:

1. **Typing Indicators**: Shows when users are typing in real-time
2. **Ready-to-use Components**: Includes a complete `CollaborativeEditor` component
3. **Better UI**: Improved cursor animations and collaborator list
4. **Dark Mode**: Supports light and dark themes
5. **Event System**: Better event handling for vanilla JavaScript

## Quick Start

### Fixed SDK Demo

```bash
# From the project root
./start-test.sh
```

This will:
- Build the fixed SDK
- Start the backend server
- Install dependencies for the React test
- Start the React test application

Open multiple browser windows to http://localhost:3000 to see the real-time collaboration in action.

### Enhanced SDK Demo

```bash
# From the project root
./run-enhanced-demo.sh
```

This will:
- Build the enhanced SDK
- Start the backend server
- Start a simple HTTP server for the demo

Open multiple browser windows to http://localhost:8080 to see the enhanced real-time collaboration features in action.

## Using the SDK in Your Project

### Fixed SDK

#### Install from Local

```bash
# From your project
npm install /path/to/realtimecursor/fixed-sdk
```

#### Install from npm

```bash
# From your project
npm install realtimecursor-sdk-fixed
```

### Enhanced SDK

#### Install from Local

```bash
# From your project
npm install /path/to/realtimecursor/enhanced-sdk
```

#### Install from npm

```bash
# From your project
npm install realtimecursor-enhanced
```

### React Usage

```jsx
import React, { useState, useRef, useEffect } from 'react';
import { useRealtimeCursor, CursorOverlay, CollaboratorsList } from 'realtimecursor-sdk-fixed';
import 'realtimecursor-sdk-fixed/dist/cursor.css';

function CollaborativeEditor() {
  const [content, setContent] = useState('');
  const editorRef = useRef(null);
  
  const { 
    cursors, 
    collaborators,
    connected,
    updateCursor, 
    updateContent,
    connect,
    disconnect
  } = useRealtimeCursor({
    apiUrl: 'http://localhost:3001',
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe',
      color: '#3b82f6' // Optional
    }
  });

  // Connect on mount
  useEffect(() => {
    connect();
    return () => disconnect();
  }, [connect, disconnect]);

  // Update cursor position on mouse move
  const handleMouseMove = (e) => {
    if (!editorRef.current) return;
    
    const rect = editorRef.current.getBoundingClientRect();
    updateCursor({
      x: e.clientX,
      y: e.clientY,
      relativeX: e.clientX - rect.left,
      relativeY: e.clientY - rect.top
    });
  };

  // Update content when changed
  const handleContentChange = (e) => {
    const newContent = e.target.value;
    setContent(newContent);
    updateContent(newContent);
  };

  return (
    <div className="collaborative-editor">
      <div className="editor-container" ref={editorRef} onMouseMove={handleMouseMove}>
        <textarea
          value={content}
          onChange={handleContentChange}
          placeholder="Start typing..."
        />
        <CursorOverlay cursors={cursors} />
      </div>
      
      <div className="collaborators-panel">
        <h3>Active Collaborators ({collaborators.length})</h3>
        <CollaboratorsList collaborators={collaborators} />
      </div>
    </div>
  );
}
```

### Vanilla JavaScript Usage

```javascript
import { RealtimeCursor } from 'realtimecursor-sdk-fixed';
import 'realtimecursor-sdk-fixed/dist/cursor.css';

// Initialize the cursor client
const cursorClient = new RealtimeCursor({
  apiUrl: 'http://localhost:3001',
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6' // Optional
  }
});

// Connect to the real-time service
cursorClient.connect();

// Set up event handlers
cursorClient.onConnect = () => {
  console.log('Connected to real-time service');
};

cursorClient.onDisconnect = () => {
  console.log('Disconnected from real-time service');
};

cursorClient.onCursorsChange = (cursors) => {
  console.log('Cursors updated:', cursors);
  // Render cursors
};

cursorClient.onCollaboratorsChange = (collaborators) => {
  console.log('Collaborators updated:', collaborators);
  // Update UI
};

// Update cursor position on mouse move
document.getElementById('editor').addEventListener('mousemove', (e) => {
  const rect = e.currentTarget.getBoundingClientRect();
  cursorClient.updateCursor({
    x: e.clientX,
    y: e.clientY,
    relativeX: e.clientX - rect.left,
    relativeY: e.clientY - rect.top
  });
});

// Update content when changed
document.getElementById('editor').addEventListener('input', (e) => {
  cursorClient.updateContent(e.target.value);
});
```

## Publishing to npm

### Fixed SDK

To publish the fixed SDK to npm:

```bash
# From the project root
./publish-npm.sh
```

### Enhanced SDK

To publish the enhanced SDK to npm:

```bash
# From the project root
./publish-enhanced.sh
```

## Integrating with Any React Project

Use the integration script to quickly add the SDK to any React project:

```bash
# From the project root
./integrate-sdk.sh /path/to/your/react-project
```

This will:
- Build the SDK
- Install it in your React project
- Create a sample component ready to use

## Directory Structure

- `/fixed-sdk` - The fixed version of the SDK (v1.1.0)
- `/enhanced-sdk` - The enhanced version of the SDK (v1.2.0)
- `/react-test` - A React test application using the fixed SDK
- `/enhanced-demo` - A demo page for the enhanced SDK
- `/api` - The backend server for real-time communication
- `/html-test` - A simple HTML test page for the fixed SDK

## Upgrading from Previous Version

If you're upgrading from a previous version of the SDK, see [UPGRADE.md](UPGRADE.md) for detailed instructions.

## Changelogs

- Fixed SDK: [CHANGELOG.md](fixed-sdk/CHANGELOG.md)
- Enhanced SDK: [CHANGELOG.md](enhanced-sdk/CHANGELOG.md)

## License

MIT