Collaboration Features

SPEAR provides real-time collaborative editing for report sections, allowing multiple team members to work simultaneously on the same content. This guide covers the technology stack, implementation details, and user experience of collaborative editing.

Overview

5:00

▶

Real-Time Collaboration in Action See multiple users editing simultaneously with live cursors, instant sync, and conflict-free merging 🎥 Demo Video

Real-time collaboration in SPEAR enables:

• Multiple users editing the same section simultaneously
• Live cursor positions showing where collaborators are working
• Instant synchronization of changes across all clients
• Conflict-free merging of concurrent edits
• Connection status visibility

Technology Stack

Y.js (CRDT Library)

Y.js is a Conflict-free Replicated Data Type (CRDT) implementation that enables real-time collaboration without conflicts. Key benefits:

• Conflict-free - Concurrent edits automatically merge correctly
• Offline support - Changes sync when connection restores
• Efficient - Only diffs are transmitted, not full documents

WebSocket Provider

WebSocket connections maintain real-time sync between clients:

• Persistent connection for instant updates
• Automatic reconnection on network issues
• Session persistence for seamless reconnection

Awareness Protocol

Tracks user presence and cursor positions:

• User identification (name, color)
• Cursor position in document
• Selection state
• Online/offline status

How It Works

🎨 Document Synchronization Flow Illustration

Document Synchronization

Each report section has a unique documentId that identifies it for collaboration:

documentId = `section-${sectionId}`

When multiple users open the same section:

1. Each client creates a Y.js document with the same documentId
2. WebSocket connection established to sync server
3. Document state syncs between all connected clients
4. Changes propagate instantly to all participants

Awareness State

The awareness protocol shares user information:

{
  user: {
    name: "John Doe",
    color: "#3498db",
    sessionId: "abc123"
  },
  cursor: {
    anchor: 150,  // Cursor position
    head: 150
  }
}

Connection Status

Three connection states are tracked:

Status	Description	Indicator
Connected	Active sync connection	Green
Connecting	Establishing connection	Yellow
Disconnected	No connection	Red

User Experience

🖥️ Live Cursors and Collaborator Avatars Screenshot

Live Cursors

When collaborators are editing:

• Colored cursor appears at their position
• Name label shows who is editing
• Cursor moves in real-time as they type
• Selection highlights show selected text

Collaborator Avatars

The editor toolbar displays:

• Avatar icons for each connected user
• Tooltips with user names
• Visual indicator of active collaborators

Real-Time Updates

Content changes are visible instantly:

• Text appears as collaborators type
• Formatting changes reflect immediately
• Images and media sync automatically
• No manual refresh required

Enabling Collaboration

BaseEdraEditor Configuration

Enable collaboration by setting props on BaseEdraEditor:

<script lang="ts">
  import BaseEdraEditor from '$lib/components/edra/BaseEdraEditor.svelte';

  const sectionId = 'unique-section-id';
</script>

<BaseEdraEditor
  collaboration={true}
  documentId={`section-${sectionId}`}
  content={initialContent}
  onUpdate={(html) => handleUpdate(html)}
/>

Required Props

Prop	Type	Description
collaboration	boolean	Must be true to enable
documentId	string	Unique identifier for the document

WebSocket Server

The backend must provide a WebSocket endpoint for Y.js sync. Configuration is handled by SPEAR’s backend infrastructure.

Collaboration UI Components

🖥️ Connection Status Badge Screenshot

Connection Status Badge

Displays current connection state in the editor toolbar:

{#if connectionStatus === 'connected'}
  <Badge variant="success">Connected</Badge>
{:else if connectionStatus === 'connecting'}
  <Badge variant="warning">Connecting...</Badge>
{:else}
  <Badge variant="destructive">Disconnected</Badge>
{/if}

Collaborator List

Shows active users with visual indicators:

<div class="collaborator-avatars">
  {#each collaborators as user}
    <Avatar
      style="border-color: {user.color}"
      title={user.name}
    >
      {user.initials}
    </Avatar>
  {/each}
</div>

Session Persistence

Reconnection Handling

When connection drops and restores:

1. WebSocket provider automatically reconnects
2. Y.js syncs local changes with server
3. Remote changes sync to local document
4. Awareness state re-establishes

Session Storage

Connection state persisted to sessionStorage for seamless page refresh:

// Store connection state
sessionStorage.setItem(`collab-${documentId}`, JSON.stringify({
  timestamp: Date.now(),
  userId: currentUser.id
}));

Limitations

Editor Support

Collaboration is only available in BaseEdraEditor. The following editors do not support collaboration:

• FindingsRichTextEditor
• ValidationNotesEditor
• SOWRichTextEditor

Authentication Required

• All collaborators must be authenticated users
• Anonymous collaboration is not supported
• User information displayed to other collaborators

Network Requirements

• WebSocket connection required for real-time sync
• Offline edits will sync when connection restores
• High latency may cause visible sync delays

Concurrent Edit Limits

• No hard limit on concurrent users
• Performance may degrade with 10+ simultaneous editors
• Recommended: 5 or fewer concurrent editors per section

Troubleshooting

3:30

▶

Troubleshooting Collaboration Issues Diagnosing connection problems, cursor visibility issues, and content sync failures 📚 Video Tutorial

Connection Issues

Symptom: Status shows “Disconnected” persistently

Solutions:

1. Check network connectivity
2. Verify WebSocket server is running
3. Check browser console for connection errors
4. Try refreshing the page

Cursors Not Visible

Symptom: Can’t see other users’ cursors

Solutions:

1. Verify both users have collaboration enabled
2. Check that documentId matches exactly
3. Ensure awareness state is being shared
4. Verify user information is set

Content Not Syncing

Symptom: Changes don’t appear for other users

Solutions:

1. Check connection status
2. Verify Y.js document is initialized
3. Check for JavaScript errors in console
4. Try refreshing both clients

Duplicate Cursors

Symptom: Multiple cursors appear for same user

Solutions:

1. Close duplicate browser tabs
2. Clear session storage
3. Refresh the page