[PROTOTYPE] CRDT Collaborative Editing with Yjs

[jkomoros]

⚠️ PROTOTYPE - NOT FOR LANDING

This is an exploration/proof-of-concept, not a proposal to merge. The goal was to understand how real-time collaborative editing could integrate with the existing architecture.

What This Explores

Adds CRDT-based real-time collaborative editing to ct-code-editor and a new ct-richtext-editor component using Yjs.

Key Components

Server (toolshed):

• Yjs WebSocket relay server at /api/collab/:roomId
• Cryptographic auth using existing identity system (Signer/VerifierIdentity)
• Generic design - no component-specific knowledge

Client (ui):

• ct-code-editor - added collaborative prop with y-codemirror.next
• ct-richtext-editor - new TipTap-based component with Yjs collaboration
• Auth token signing using cell.runtime.storageManager.as

Design Decisions Explored

1. Yjs over Automerge - Better ecosystem for text editing (y-codemirror, y-prosemirror)
2. Room ID = Cell entity ID - Natural mapping, debuggable
3. Auth extends existing identity - Components sign tokens with Cell's Signer
4. Presence = consent model - Collaborative mode shows cursors; visual indicator serves as consent signal

What's Working

• Real-time bidirectional sync between browser tabs
• Cursor presence with user names/colors
• Initial content sync from Cell value
• Reconnection handling (y-websocket built-in)

Open Questions / Not Addressed

• Persistence strategy (currently ephemeral - room state lost when all clients disconnect)
• Integration with Cell reactivity (sync back to Cell on changes?)
• Production scaling considerations
• Whether this is even the right approach for Common Tools

Files Changed

See docs/SESSION-crdt-collaborative-editing.md for detailed implementation notes and decisions.

---

🤖 Generated with Claude Code

---

Summary by cubic

Adds Yjs-based real-time collaboration to code and rich text editors, backed by a simple WebSocket relay in toolshed with optional identity-based auth. Enables multi-user live sync, cursors, and initial content sync from Cells without touching Chronicle.

• New Features

  • Server: Yjs WebSocket relay at /api/collab/:roomId with CORS and stats; verifies signed auth tokens via VerifierIdentity.
  • ct-code-editor: collaborative mode using y-codemirror.next; props for roomId, collabUrl, userName, userColor.
  • ct-richtext-editor: new TipTap editor with Collaboration and CollaborationCursor for live presence.
  • Client auth: helper to sign tokens using the Cell’s Signer and pass them to the server.
  • Working UX: real-time sync across tabs, cursor presence, initial content sync from Cell, reconnection handling.

• Refactors

  • Server simplified to a generic Yjs relay (no editor-specific logic); clients handle document initialization from Cell values.

^{Written for commit a1d3342. Summary will update automatically on new commits.}