realtimecursor/UPGRADE.md

Real-time collaboration system with cursor tracking and approval workflow

# Upgrading to RealtimeCursor SDK v1.1.0

This guide will help you upgrade from the previous version of RealtimeCursor SDK to the fixed version (v1.1.0).

## What's Fixed

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

## Upgrade Steps

### 1. Update the package

```bash
# Using npm
npm uninstall realtimecursor-sdk
npm install realtimecursor-sdk-fixed

# Using yarn
yarn remove realtimecursor-sdk
yarn add realtimecursor-sdk-fixed
```

### 2. Update imports

```javascript
// Old import
import { RealtimeCursor, useRealtimeCursor } from 'realtimecursor-sdk';

// New import
import { RealtimeCursor, useRealtimeCursor, CursorOverlay, CollaboratorsList } from 'realtimecursor-sdk-fixed';
import 'realtimecursor-sdk-fixed/dist/cursor.css';
```

### 3. Update React components

The new SDK provides ready-to-use components for displaying cursors and collaborators:

```jsx
// Old way (manual rendering)
{Object.values(cursors).map(cursor => (
  <div key={cursor.id} style={{ position: 'absolute', left: cursor.x, top: cursor.y }}>
    {/* Custom cursor rendering */}
  </div>
))}

// New way (using components)
<CursorOverlay cursors={cursors} />
<CollaboratorsList collaborators={collaborators} />
```

### 4. Update connection handling

The new SDK provides better connection handling:

```jsx
// Old way
useEffect(() => {
  cursorClient.connect();
  return () => cursorClient.disconnect();
}, []);

// New way
const { connect, disconnect } = useRealtimeCursor({
  apiUrl: 'http://localhost:3001',
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6'
  }
});

useEffect(() => {
  connect();
  return () => disconnect();
}, [connect, disconnect]);
```

## Full Example

```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,
    connect,
    disconnect,
    updateCursor, 
    updateContent
  } = useRealtimeCursor({
    apiUrl: 'http://localhost:3001',
    projectId: 'your-project-id',
    user: {
      id: 'user-123',
      name: 'John Doe',
      color: '#3b82f6'
    }
  });

  // 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="connection-status">
        {connected ? 'Connected' : 'Disconnected'}
      </div>
      
      <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>
  );
}
```

## Need Help?

If you encounter any issues during the upgrade, please open an issue on the GitHub repository or contact support.