Add real-time multiplayer collaboration

[espetro]

TL;DR

Enable real-time multi-user editing with cursor tracking, conflict resolution, and room-based workspaces. Transform Calca from a solo tool into a collaborative design platform.

User Story

As a team, we want to edit designs together in real-time, so we can iterate faster without exporting/importing files.

Scope

• Real-time sync via WebSocket
• Cursor presence (see other users' cursors)
• Conflict resolution (OT or CRDT)
• Room-based workspaces (shareable links)
• Permission levels (owner, editor, viewer)

Tradeoffs / Optionality

Conflict Resolution: OT vs CRDT

Operational Transformation (OT):

• Pros: Mature (Google Docs), good for text
• Cons: Complex server logic, harder with structured data (frames, positions)

CRDT (Conflict-free Replicated Data Types):

• Pros: Peer-to-peer friendly, simpler mental model, great for Figma-like apps
• Cons: Memory overhead, harder to implement from scratch

Decision: CRDT recommended for frame-level data. Use yjs or automerge library. OT only if we need granular text collaboration within designs.

Architecture: Central Server vs P2P

Central WebSocket Server:

• Pros: Simpler, authoritative source, easy permissions
• Cons: Server cost, single point of failure

P2P (WebRTC):

• Pros: No server cost, resilient
• Cons: Complex NAT traversal, hard to moderate

Decision: Central server for MVP. P2P as optimization later.

Technical Considerations

• WebSocket Server: Bun's built-in WebSocket support or socket.io
• State Sync: CRDT library (yjs recommended) for frame positions and properties
• Auth: Even anonymous users need identity (random ID + display name)
• Canvas Integration:
  • If React Flow: built-in collaborative features
  • If CSS transforms: custom sync layer via Zustand middleware
• Dependencies: Database persistence (Implement SQLite database layer with Drizzle ORM #10), user identity system

References

• Original spec: docs/prd-v2.md P1-1 (Multi-User Collaboration)