feat: send granular CodeMirror deltas over WebSocket with 50ms debounce

templates/document_edit.html

···
                 if (update.docChanged && currentMode === 'source') {
                     const content = update.state.doc.toString();
                     updatePreview(content);
-                    // Skip broadcast if this change came from a remote edit
                     if (!update.transactions.some(tr => tr.annotation(remoteEditAnnotation))) {
                         scheduleAutoSave(content);
-                        sendEdit(content);
+                        // Extract granular deltas from the ChangeSet.
+                        // fromA/toA are positions in the OLD document (pre-change),
+                        // which is what the server's OT engine needs.
+                        const deltas = [];
+                        update.changes.iterChanges((fromA, toA, _fromB, _toB, inserted) => {
+                            deltas.push({ from: fromA, to: toA, insert: inserted.toString() });
+                        });
+                        if (deltas.length > 0) {
+                            queueDeltas(deltas);
+                        }
                     }
                 }
             }),
···
                 wsMissedPings = 0;
                 break;
             case 'edit':
-                applyRemoteEdit(msg.content);
+                applyRemoteEdit(msg);   // pass full message object
                 break;
             case 'sync':
-                applyRemoteEdit(msg.content);
+                applyRemoteEdit(msg.content);  // sync is always full-content string
                 break;
         }
     }
 
-    function applyRemoteEdit(content) {
-        if (!content || applyingRemote) return;
+    function applyRemoteEdit(msg) {
+        // msg may be a full-content string (legacy sync path) or an object with deltas.
+        if (applyingRemote) return;
         applyingRemote = true;
         try {
-            if (currentMode === 'source') {
-                const cur = cmView.state.doc.toString();
-                if (cur !== content) {
+            let content = typeof msg === 'string' ? msg : msg.content;
+            const deltas = (typeof msg === 'object' && msg.deltas) ? msg.deltas : null;
+
+            if (currentMode === 'source' && cmView) {
+                if (deltas && deltas.length > 0) {
+                    // Apply granular deltas as a single CodeMirror dispatch.
+                    // All from/to positions are relative to the original document
+                    // (before any delta in this batch), which is what CodeMirror
+                    // expects when changes are batched in a single dispatch call.
+                    const docLen = cmView.state.doc.length;
+                    const changes = deltas.map(d => ({
+                        from: Math.min(d.from < 0 ? 0 : d.from, docLen),
+                        to:   Math.min(d.to   < 0 ? docLen : d.to, docLen),
+                        insert: d.insert || '',
+                    }));
+                    cmView.dispatch({
+                        changes,
+                        annotations: [remoteEditAnnotation.of(true)],
+                    });
+                    // Use the server's full-content echo as a divergence check.
+                    if (content && cmView.state.doc.toString() !== content) {
+                        // State diverged — fall back to full replacement.
+                        cmView.dispatch({
+                            changes: { from: 0, to: cmView.state.doc.length, insert: content },
+                            annotations: [remoteEditAnnotation.of(true)],
+                        });
+                    }
+                } else if (content && cmView.state.doc.toString() !== content) {
+                    // Legacy full-replacement path (sync message or old server).
                     cmView.dispatch({
                         changes: { from: 0, to: cmView.state.doc.length, insert: content },
-                        // Don't trigger our own change listener
                         annotations: [remoteEditAnnotation.of(true)],
                     });
-                    updatePreview(content);
                 }
-            } else if (milkdownEditor) {
-                // Recreate Milkdown with the new content
+                if (content) updatePreview(content);
+            } else if (currentMode === 'rich' && milkdownEditor && content) {
                 createMilkdownEditor(content);
             }
         } finally {
···
         }
     }
 
-    // Send the full document content as an edit delta (full replacement).
+    // Debounce timer for WebSocket sends (50ms batches rapid keystrokes).
+    let wsEditTimer = null;
+    let pendingDeltas = [];
+
+    // Queue a set of deltas and flush after a short debounce.
+    function queueDeltas(deltas) {
+        if (!ws || ws.readyState !== WebSocket.OPEN || applyingRemote) return;
+        pendingDeltas = pendingDeltas.concat(deltas);
+        clearTimeout(wsEditTimer);
+        wsEditTimer = setTimeout(flushDeltas, 50);
+    }
+
+    function flushDeltas() {
+        if (!ws || ws.readyState !== WebSocket.OPEN || pendingDeltas.length === 0) {
+            pendingDeltas = [];
+            return;
+        }
+        ws.send(JSON.stringify({ type: 'edit', deltas: pendingDeltas }));
+        pendingDeltas = [];
+    }
+
+    // sendEdit is kept for any future callers; Milkdown switches to diffToOps
+    // in Chunk 4 and no longer calls this directly.
     function sendEdit(content) {
         if (!ws || ws.readyState !== WebSocket.OPEN || applyingRemote) return;
-        ws.send(JSON.stringify({
-            type: 'edit',
-            delta: { from: 0, to: -1, insert: content },
-        }));
+        queueDeltas([{ from: 0, to: -1, insert: content }]);
     }
 
     // ── Presence ──────────────────────────────────────────────────────────────