Multiplayer Editing Feature Spec Template

OT (Operational Transform) transforms each operation against concurrent operations to maintain consistency. It requires a central server to sequence operations and is computationally complex for rich data types. CRDT (Conflict-free Replicated Data Types) defines data structures that merge automatically without coordination. CRDTs do not need a central server and handle offline editing naturally. For block-based editors, CRDTs (specifically Yjs) are the practical choice. For complex spreadsheet operations, OT may still be necessary due to formula dependencies.

With a well-implemented CRDT library (Yjs) and WebSocket transport, 15-25 concurrent editors is achievable without significant performance degradation. The bottleneck is usually cursor rendering, not data sync. Beyond 25, you need cursor aggregation (showing "5 others editing" instead of individual cursors) and more aggressive update batching. Google Docs supports 100+ but uses a custom OT engine with years of optimization.

If you use CRDTs, you get basic offline support almost for free. The client can continue editing locally, and changes merge automatically on reconnection. The main V1 investment is in the UX: showing a clear offline indicator, queuing and replaying operations, and handling the case where offline edits conflict with server state. Skip offline for OT-based systems. It requires a fundamentally different architecture.

Implement lazy loading. Send the client only the visible portion of the document initially, then load additional content as the user scrolls. For CRDT state, use document snapshots (periodic full-state saves) instead of replaying the entire operation history. A 50,000-block document with full operation history can take seconds to sync. A snapshot reduces initial load to hundreds of milliseconds.

Three layers: unit tests for individual conflict resolution scenarios (same-position insert, overlapping delete, etc.), integration tests with simulated concurrent clients (2, 5, 25 users), and fuzz tests that generate random operations and verify all clients converge. Run fuzz tests continuously in CI. Most multiplayer editing bugs are edge cases that only surface under specific operation ordering. ---