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

# 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

# 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

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

Install from npm

# From your project
npm install realtimecursor-sdk-fixed

Enhanced SDK

Install from Local

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

Install from npm

# From your project
npm install realtimecursor-enhanced

React Usage

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

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:

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

Enhanced SDK

To publish the enhanced SDK to npm:

# 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:

# 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 for detailed instructions.

Changelogs

• Fixed SDK: CHANGELOG.md
• Enhanced SDK: CHANGELOG.md

License

MIT