docs: add granular delta edits implementation plan

docs/superpowers/plans/2026-03-13-granular-delta-edits.md

···
+# Granular Delta Edits Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace full-document WebSocket broadcasts with granular character-level deltas, reducing per-keystroke payload from O(document size) to O(change size).
+
+**Architecture:** CodeMirror exposes `update.changes` (a `ChangeSet`) directly — iterate it to extract precise `{from, to, insert}` operations. Milkdown only exposes the new markdown string, so we string-diff the previous vs new content using a bundled Myers diff to produce the same operation shape. The server-side `Operation` struct and `OTEngine` already handle granular ops correctly (after the `Insert==""` fix). Add a WebSocket send debounce (50ms) to batch rapid keystrokes. Receivers apply each delta in order using CodeMirror's `ChangeSet` API rather than replacing the whole document.
+
+**Tech Stack:** Go 1.22, CodeMirror 6 (`ChangeSet`, `ChangeDesc`), vanilla JS Myers diff (bundled inline, no new npm dep), existing `gorilla/websocket`, existing `Operation` / `OTEngine` types.
+
+---
+
+## Chunk 1: Server — accept and broadcast multiple deltas per message
+
+The current server receives one `Operation` per `edit` message. Granular edits from a single keystroke may produce multiple operations (e.g. CodeMirror reports each change in a transaction separately). We need the server to accept an array.
+
+### Task 1: Update `Operation` and `ClientMessage` to support delta arrays
+
+**Files:**
+- Modify: `internal/collaboration/client.go`
+- Modify: `internal/collaboration/hub.go`
+- Test: `internal/collaboration/client_test.go` (create)
+
+The wire format changes from:
+```json
+{ "type": "edit", "delta": { "from": 5, "to": 10, "insert": "hello" } }
+```
+to:
+```json
+{ "type": "edit", "deltas": [{ "from": 5, "to": 10, "insert": "hello" }] }
+```
+
+`delta` (singular) is kept as a fallback field so existing clients don't break during the transition.
+
+- [ ] **Step 1: Write failing test for multi-delta parsing**
+
+Add `internal/collaboration/client_test.go`:
+
+```go
+package collaboration
+
+import (
+    "encoding/json"
+    "testing"
+)
+
+func TestClientMessage_ParseDeltas_Multiple(t *testing.T) {
+    raw := `{"type":"edit","deltas":[{"from":0,"to":5,"insert":"hello"},{"from":10,"to":10,"insert":"!"}]}`
+    var msg ClientMessage
+    if err := json.Unmarshal([]byte(raw), &msg); err != nil {
+        t.Fatalf("unmarshal: %v", err)
+    }
+    if len(msg.Deltas) != 2 {
+        t.Fatalf("expected 2 deltas, got %d", len(msg.Deltas))
+    }
+    if msg.Deltas[0].From != 0 || msg.Deltas[0].To != 5 || msg.Deltas[0].Insert != "hello" {
+        t.Errorf("delta[0]: %+v", msg.Deltas[0])
+    }
+    if msg.Deltas[1].From != 10 || msg.Deltas[1].Insert != "!" {
+        t.Errorf("delta[1]: %+v", msg.Deltas[1])
+    }
+}
+
+func TestClientMessage_ParseDeltas_SingleFallback(t *testing.T) {
+    // Old wire format: singular "delta" field — must still work.
+    raw := `{"type":"edit","delta":{"from":3,"to":7,"insert":"xyz"}}`
+    var msg ClientMessage
+    if err := json.Unmarshal([]byte(raw), &msg); err != nil {
+        t.Fatalf("unmarshal: %v", err)
+    }
+    ops := msg.Operations()
+    if len(ops) != 1 {
+        t.Fatalf("expected 1 op from fallback, got %d", len(ops))
+    }
+    if ops[0].From != 3 || ops[0].To != 7 || ops[0].Insert != "xyz" {
+        t.Errorf("op: %+v", ops[0])
+    }
+}
+
+func TestClientMessage_ParseDeltas_EmptyDeltas(t *testing.T) {
+    raw := `{"type":"edit","deltas":[]}`
+    var msg ClientMessage
+    if err := json.Unmarshal([]byte(raw), &msg); err != nil {
+        t.Fatalf("unmarshal: %v", err)
+    }
+    if len(msg.Operations()) != 0 {
+        t.Errorf("expected 0 ops for empty deltas")
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+go test -v ./internal/collaboration/ -run TestClientMessage
+```
+
+Expected: `FAIL` — `msg.Deltas` field doesn't exist, `msg.Operations()` method doesn't exist.
+
+- [ ] **Step 3: Update `ClientMessage` in `internal/collaboration/client.go`**
+
+Replace the existing `ClientMessage` struct and add the `Operations()` helper:
+
+```go
+type ClientMessage struct {
+    Type    string          `json:"type"`
+    RKey    string          `json:"rkey,omitempty"`
+    DID     string          `json:"did,omitempty"`
+    // Deltas is the new plural field — a single edit message may carry
+    // multiple operations (e.g. one per CodeMirror ChangeDesc).
+    Deltas  []Operation     `json:"deltas,omitempty"`
+    // Delta is the legacy singular field. Kept for backward compatibility.
+    Delta   json.RawMessage `json:"delta,omitempty"`
+    Cursor  *CursorPos      `json:"cursor,omitempty"`
+    Comment *CommentMsg     `json:"comment,omitempty"`
+}
+
+// Operations returns the ops from this message, preferring Deltas over the
+// legacy singular Delta field.
+func (m *ClientMessage) Operations() []Operation {
+    if len(m.Deltas) > 0 {
+        return m.Deltas
+    }
+    if len(m.Delta) > 0 {
+        var op Operation
+        if err := json.Unmarshal(m.Delta, &op); err == nil {
+            return []Operation{op}
+        }
+    }
+    return nil
+}
+```
+
+- [ ] **Step 4: Update the `"edit"` case in `ReadPump` in `internal/collaboration/client.go`**
+
+Replace:
+```go
+case "edit":
+    var op Operation
+    if err := json.Unmarshal(msg.Delta, &op); err != nil {
+        log.Printf("Failed to parse delta from %s: %v", c.DID, err)
+        continue
+    }
+    op.Author = c.DID
+    room := c.hub.GetRoom(c.roomKey)
+    if room != nil {
+        room.ApplyEdit(op, c)
+    }
+```
+
+With:
+```go
+case "edit":
+    ops := msg.Operations()
+    if len(ops) == 0 {
+        continue
+    }
+    room := c.hub.GetRoom(c.roomKey)
+    if room == nil {
+        continue
+    }
+    for i := range ops {
+        ops[i].Author = c.DID
+    }
+    room.ApplyEdits(ops, c)
+```
+
+- [ ] **Step 5: Add `ApplyEdits` to `Room` in `internal/collaboration/hub.go`**
+
+Add alongside the existing `ApplyEdit` method:
+
+```go
+// ApplyEdits applies a sequence of operations in order and broadcasts one
+// combined message to all other clients. Each op is applied to the text
+// resulting from the previous op, so positions in each op must be relative
+// to the document state after all prior ops in the same batch have been
+// applied — which is exactly what CodeMirror's iterChanges produces (fromA/toA
+// are positions in the pre-change document, already adjusted for prior changes
+// within the same transaction by CodeMirror itself).
+func (r *Room) ApplyEdits(ops []Operation, sender *Client) {
+    if len(ops) == 0 {
+        return
+    }
+
+    for i := range ops {
+        r.ot.ApplyWithVersion(ops[i])
+    }
+
+    // Include the full document text so receivers can detect and recover from
+    // divergence without a reconnect.
+    finalText := r.ot.GetText()
+    type editsMsg struct {
+        Type    string      `json:"type"`
+        Deltas  []Operation `json:"deltas"`
+        Author  string      `json:"author"`
+        Content string      `json:"content"`
+    }
+    msg := editsMsg{
+        Type:    "edit",
+        Deltas:  ops,
+        Author:  sender.DID,
+        Content: finalText,
+    }
+    data, err := json.Marshal(msg)
+    if err != nil {
+        log.Printf("ApplyEdits: marshal: %v", err)
+        return
+    }
+    r.BroadcastExcept(data, sender)
+}
+```
+
+Note: `Content` (full text) is included in the broadcast so receivers can sanity-check their state. The client applies deltas directly but falls back to full replacement if its local state diverges.
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+```bash
+go test -v -race ./internal/collaboration/ -run TestClientMessage
+```
+
+Expected: all 3 `TestClientMessage_*` tests PASS.
+
+- [ ] **Step 7: Run full suite**
+
+```bash
+go test -v -race ./internal/collaboration/
+```
+
+Expected: all tests PASS (no regressions).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/collaboration/client.go internal/collaboration/hub.go internal/collaboration/client_test.go
+git commit -m "feat: support multi-delta edit messages on server"
+```
+
+---
+
+## Chunk 2: Server — OT tests for multi-delta sequences
+
+Before touching the frontend, verify the server applies multi-op sequences correctly.
+
+### Task 2: Tests for `ApplyEdits` on `Room`
+
+**Files:**
+- Modify: `internal/collaboration/hub_test.go`
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `internal/collaboration/hub_test.go`:
+
+```go
+func TestRoom_ApplyEdits_MultipleOpsAppliedInOrder(t *testing.T) {
+    hub := NewHub()
+    room := hub.GetOrCreateRoom("doc-multi-ops")
+
+    alice := stubClient(hub, "did:plc:alice", "Alice", "#ff0000", "doc-multi-ops")
+    bob   := stubClient(hub, "did:plc:bob",   "Bob",   "#0000ff", "doc-multi-ops")
+    room.RegisterClient(alice)
+    room.RegisterClient(bob)
+    time.Sleep(100 * time.Millisecond)
+    drain(alice, 200*time.Millisecond)
+    drain(bob,   200*time.Millisecond)
+
+    // Two ops: set text to "hello", then append " world"
+    ops := []Operation{
+        {From: 0, To: -1, Insert: "hello"},
+        {From: 5, To:  5, Insert: " world"},
+    }
+    room.ApplyEdits(ops, alice)
+
+    bobMsgs := waitForMessages(bob, 1, time.Second)
+    if len(bobMsgs) == 0 {
+        t.Fatal("bob: expected edit message")
+    }
+
+    var msg struct {
+        Type    string      `json:"type"`
+        Deltas  []Operation `json:"deltas"`
+        Content string      `json:"content"`
+        Author  string      `json:"author"`
+    }
+    if err := json.Unmarshal(bobMsgs[0], &msg); err != nil {
+        t.Fatalf("unmarshal: %v", err)
+    }
+    if msg.Type != "edit" {
+        t.Errorf("type: got %q, want edit", msg.Type)
+    }
+    if msg.Content != "hello world" {
+        t.Errorf("content: got %q, want %q", msg.Content, "hello world")
+    }
+    if len(msg.Deltas) != 2 {
+        t.Errorf("deltas: got %d, want 2", len(msg.Deltas))
+    }
+    if msg.Author != "did:plc:alice" {
+        t.Errorf("author: got %q", msg.Author)
+    }
+}
+
+func TestRoom_ApplyEdits_UpdatesOTState(t *testing.T) {
+    hub := NewHub()
+    room := hub.GetOrCreateRoom("doc-multi-ot")
+    alice := stubClient(hub, "did:plc:alice", "Alice", "#ff0000", "doc-multi-ot")
+    room.RegisterClient(alice)
+    time.Sleep(100 * time.Millisecond)
+    drain(alice, 200*time.Millisecond)
+
+    room.ApplyEdits([]Operation{
+        {From: 0, To: -1, Insert: "abc"},
+        {From: 3, To:  3, Insert: "def"},
+    }, alice)
+
+    time.Sleep(50 * time.Millisecond)
+    if got := room.ot.GetText(); got != "abcdef" {
+        t.Errorf("OT state: got %q, want %q", got, "abcdef")
+    }
+}
+
+func TestRoom_ApplyEdits_EmptyOpsIsNoop(t *testing.T) {
+    hub := NewHub()
+    room := hub.GetOrCreateRoom("doc-empty-ops")
+    alice := stubClient(hub, "did:plc:alice", "Alice", "#ff0000", "doc-empty-ops")
+    bob   := stubClient(hub, "did:plc:bob",   "Bob",   "#0000ff", "doc-empty-ops")
+    room.RegisterClient(alice)
+    room.RegisterClient(bob)
+    time.Sleep(100 * time.Millisecond)
+    drain(alice, 200*time.Millisecond)
+    drain(bob,   200*time.Millisecond)
+
+    room.ApplyEdits(nil, alice)
+
+    bobMsgs := drain(bob, 300*time.Millisecond)
+    if len(bobMsgs) > 0 {
+        t.Errorf("expected no broadcast for empty ops, got %d messages", len(bobMsgs))
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to confirm they pass**
+
+```bash
+go test -v ./internal/collaboration/ -run TestRoom_ApplyEdits
+```
+
+Expected: PASS — `ApplyEdits` was added in Chunk 1 Task 1 Step 5.
+
+- [ ] **Step 3: Run tests to verify they pass**
+
+```bash
+go test -v -race ./internal/collaboration/ -run TestRoom_ApplyEdits
+```
+
+Expected: all 3 tests PASS.
+
+- [ ] **Step 4: Run full suite**
+
+```bash
+go test -v -race ./internal/collaboration/
+```
+
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/collaboration/hub_test.go
+git commit -m "test: add multi-delta ApplyEdits tests"
+```
+
+---
+
+## Chunk 3: Frontend — CodeMirror granular deltas
+
+CodeMirror 6's `update.changes` is a `ChangeSet`. Iterating it with `iterChanges` gives `(fromA, toA, fromB, toB, inserted)` — exactly the `{from, to, insert}` we need.
+
+### Task 3: Send granular deltas from CodeMirror source mode
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+The change is in the `EditorView.updateListener.of(...)` callback and the `sendEdit` / new `sendDeltas` functions.
+
+- [ ] **Step 1: Add `sendDeltas` function and debounce timer**
+
+In `document_edit.html`, find the `sendEdit` function (around line 608) and replace it with:
+
+```js
+    // 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;
+        queueDeltas([{ from: 0, to: -1, insert: content }]);
+    }
+```
+
+- [ ] **Step 2: Update the CodeMirror `updateListener` to use granular deltas**
+
+Find the `EditorView.updateListener.of(...)` block (around line 180) and replace it:
+
+```js
+            EditorView.updateListener.of((update) => {
+                if (update.docChanged && currentMode === 'source') {
+                    const content = update.state.doc.toString();
+                    updatePreview(content);
+                    if (!update.transactions.some(tr => tr.annotation(remoteEditAnnotation))) {
+                        scheduleAutoSave(content);
+                        // Extract granular deltas from the ChangeSet.
+                        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);
+                        }
+                    }
+                }
+            }),
+```
+
+Note: `fromA`/`toA` are positions in the **old** document (before the change), which is what the server's OT engine needs. `fromB`/`toB` are positions in the new document — not needed here.
+
+- [ ] **Step 3: Update `applyRemoteEdit` to apply deltas when available**
+
+Find `applyRemoteEdit` (around line 582) and replace:
+
+```js
+    function applyRemoteEdit(msg) {
+        // msg may be a full-content string (legacy) or an object with deltas.
+        if (applyingRemote) return;
+        applyingRemote = true;
+        try {
+            // Determine content and deltas from the message.
+            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 each delta as a discrete CodeMirror change.
+                    // Build changes array, adjusting positions for prior changes.
+                    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 full-content echo from the server as a sanity-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.
+                    cmView.dispatch({
+                        changes: { from: 0, to: cmView.state.doc.length, insert: content },
+                        annotations: [remoteEditAnnotation.of(true)],
+                    });
+                }
+                if (content) updatePreview(content);
+            } else if (currentMode === 'rich' && milkdownEditor && content) {
+                createMilkdownEditor(content);
+            }
+        } finally {
+            applyingRemote = false;
+        }
+    }
+```
+
+- [ ] **Step 4: Update `handleWSMessage` to pass the full message object to `applyRemoteEdit`**
+
+Find `handleWSMessage` (around line 567) and update the `'edit'` and `'sync'` cases:
+
+```js
+    function handleWSMessage(msg) {
+        switch (msg.type) {
+            case 'presence':
+                updatePresence(msg.users || []);
+                break;
+            case 'pong':
+                wsMissedPings = 0;
+                break;
+            case 'edit':
+                applyRemoteEdit(msg);   // pass full message object, not just msg.content
+                break;
+            case 'sync':
+                applyRemoteEdit(msg.content);  // sync is always full-content
+                break;
+        }
+    }
+```
+
+- [ ] **Step 5: Manual smoke test**
+
+```bash
+# In the collaboration worktree:
+make run
+```
+
+1. Open two browser tabs, both logged in as different ATProto users on the same document.
+2. Type in tab A (source mode) — tab B should receive and apply the edit without full-page flicker.
+3. Type simultaneously — verify no echo loop (your own edits don't come back).
+4. Switch tab A to rich mode, type — tab B should still update (via legacy full-replacement path).
+5. Open browser devtools → Network → WS — verify messages are small (just the changed characters) not full document.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "feat: send granular CodeMirror deltas over WebSocket with 50ms debounce"
+```
+
+---
+
+## Chunk 4: Frontend — Milkdown string-diff deltas
+
+Milkdown only exposes the complete new markdown string. We compute a Myers diff between the previous and current string to produce `{from, to, insert}` operations.
+
+### Task 4: Inline Myers diff and wire up Milkdown listener
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+The Myers diff algorithm produces the minimal edit script between two strings. We inline a small implementation rather than adding an npm dependency, keeping the bundle unchanged.
+
+- [ ] **Step 1: Add inline Myers diff function**
+
+Just before the `queueDeltas` function added in Task 3, insert:
+
+```js
+    /**
+     * Compute the minimal edit operations to transform `oldStr` into `newStr`.
+     * Returns an array of {from, to, insert} suitable for the OT engine.
+     *
+     * Uses a line-level diff for performance, then falls back to a single
+     * full-replacement op if the diff produces more than 20 operations
+     * (pathological case — not worth the complexity).
+     */
+    function diffToOps(oldStr, newStr) {
+        if (oldStr === newStr) return [];
+
+        const oldLines = oldStr.split('\n');
+        const newLines = newStr.split('\n');
+
+        // Build line-level LCS table (Myers / Wagner-Fischer).
+        const m = oldLines.length, n = newLines.length;
+        const dp = Array.from({length: m + 1}, () => new Array(n + 1).fill(0));
+        for (let i = m - 1; i >= 0; i--) {
+            for (let j = n - 1; j >= 0; j--) {
+                dp[i][j] = oldLines[i] === newLines[j]
+                    ? dp[i+1][j+1] + 1
+                    : Math.max(dp[i+1][j], dp[i][j+1]);
+            }
+        }
+
+        // Trace back to produce diff hunks.
+        const ops = [];
+        let i = 0, j = 0;
+        // Track character offset into oldStr.
+        let charOffset = 0;
+        // +1 for the \n separator. The last line has no trailing \n, so its
+        // length is exact; however the OT engine clamps out-of-range positions,
+        // so an off-by-one on the final line is safe in practice.
+        const oldLineLengths = oldLines.map(l => l.length + 1);
+
+        while (i < m || j < n) {
+            if (i < m && j < n && oldLines[i] === newLines[j]) {
+                charOffset += oldLineLengths[i];
+                i++; j++;
+            } else if (j < n && (i >= m || dp[i+1][j] <= dp[i][j+1])) {
+                // Insert newLines[j]
+                const insertText = newLines[j] + (j < n - 1 ? '\n' : '');
+                ops.push({ from: charOffset, to: charOffset, insert: insertText });
+                j++;
+            } else {
+                // Delete oldLines[i]
+                const deleteLen = oldLineLengths[i];
+                ops.push({ from: charOffset, to: charOffset + deleteLen, insert: '' });
+                charOffset += deleteLen;
+                i++;
+            }
+        }
+
+        // Fallback: if diff is too fragmented, send a single full replacement.
+        if (ops.length > 20) {
+            return [{ from: 0, to: -1, insert: newStr }];
+        }
+
+        return ops;
+    }
+```
+
+- [ ] **Step 2: Update the Milkdown `markdownUpdated` listener to use `diffToOps`**
+
+Find the Milkdown listener (around line 246):
+
+```js
+                ctx.get(listenerCtx).markdownUpdated((_ctx, markdown, prevMarkdown) => {
+                    if (markdown !== prevMarkdown && !applyingRemote) {
+                        scheduleAutoSave(markdown);
+                        sendEdit(markdown);
+                    }
+                });
+```
+
+Replace with:
+
+```js
+                ctx.get(listenerCtx).markdownUpdated((_ctx, markdown, prevMarkdown) => {
+                    if (markdown !== prevMarkdown && !applyingRemote) {
+                        scheduleAutoSave(markdown);
+                        const ops = diffToOps(prevMarkdown || '', markdown);
+                        if (ops.length > 0) {
+                            queueDeltas(ops);
+                        }
+                    }
+                });
+```
+
+- [ ] **Step 3: Manual smoke test for rich text mode**
+
+```bash
+make run
+```
+
+1. Open two browser tabs on the same document, both in **rich** mode.
+2. Type in tab A — tab B should update.
+3. In devtools → Network → WS: verify messages contain `deltas` arrays (not a single large `insert`).
+4. Make a large edit (paste a paragraph) — verify fallback fires (single full-replacement op) rather than 20+ tiny ops.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "feat: diff-based granular deltas for Milkdown rich text mode"
+```
+
+---
+
+## Chunk 5: Cleanup and edge cases
+
+### Task 5: Handle pending deltas on WebSocket close
+
+If the browser tab closes or the WebSocket drops while `pendingDeltas` is non-empty, those changes are lost silently. Flush synchronously on close.
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+- [ ] **Step 1: Extract `closeWS` helper and wire it up**
+
+There is no named `closeWS` function in the current code. `ws.close()` is called in two places:
+- `ws.onerror` callback (around line 533)
+- Inside `startHeartbeat`'s ping timer when missed pings ≥ 3 (around line 553)
+
+Replace both call sites with a shared `closeWS` helper. Add the helper alongside `flushDeltas`:
+
+```js
+    function closeWS() {
+        if (!ws) return;
+        clearTimeout(wsEditTimer);
+        flushDeltas();   // send any buffered deltas before closing
+        ws.close();
+        ws = null;
+        clearInterval(wsPingTimer);
+    }
+```
+
+Then update `ws.onerror`:
+```js
+        ws.onerror = () => {
+            closeWS();
+        };
+```
+
+And update the heartbeat missed-ping branch:
+```js
+                if (wsMissedPings >= 3) {
+                    closeWS();
+                }
+```
+
+Also update `ws.onclose` to call `stopHeartbeat()` only (not `clearInterval` directly, since `closeWS` handles that when called from onerror/heartbeat; onclose fires for all close paths and should remain lightweight):
+```js
+        ws.onclose = () => {
+            ws = null;
+            updatePresence([]);
+            scheduleReconnect();
+        };
+```
+
+- [ ] **Step 2: Flush on page unload**
+
+Add a `beforeunload` handler at the end of the `{{define "scripts"}}` block, after the `connectWebSocket()` call:
+
+```js
+    window.addEventListener('beforeunload', () => {
+        clearTimeout(wsEditTimer);
+        flushDeltas();
+    });
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "fix: flush pending WS deltas on close and page unload"
+```
+
+### Task 6: OT engine — add `SetText` for room initialisation
+
+Currently `GetOrCreateRoom` initialises the OT engine with `""`. When a room is first created, the server fetches the document but doesn't seed the engine. If two users join simultaneously, the first edit from user A resets the OT state, which is fine for the current full-replacement protocol but wrong for granular deltas (user B's deltas will have stale offsets).
+
+**Files:**
+- Modify: `internal/collaboration/ot.go`
+- Modify: `internal/collaboration/hub.go`
+- Modify: `internal/handler/handler.go`
+- Test: `internal/collaboration/ot_test.go`
+
+- [ ] **Step 1: Write failing test for `SetText`**
+
+Add to `internal/collaboration/ot_test.go`:
+
+```go
+func TestOTEngine_SetText(t *testing.T) {
+    ot := NewOTEngine("")
+    ot.SetText("initial content")
+    if ot.GetText() != "initial content" {
+        t.Errorf("SetText: got %q, want %q", ot.GetText(), "initial content")
+    }
+    // SetText should not change the version counter.
+    if ot.GetVersion() != 0 {
+        t.Errorf("SetText should not increment version: got %d", ot.GetVersion())
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+go test -v ./internal/collaboration/ -run TestOTEngine_SetText
+```
+
+Expected: FAIL — `SetText` undefined.
+
+- [ ] **Step 3: Add `SetText` to `internal/collaboration/ot.go`**
+
+```go
+// SetText replaces the canonical document text without incrementing the version.
+// Call this once when a room is first created, before any edits are applied.
+func (ot *OTEngine) SetText(text string) {
+    ot.mu.Lock()
+    defer ot.mu.Unlock()
+    ot.documentText = text
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+go test -v -race ./internal/collaboration/ -run TestOTEngine_SetText
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Seed the OT engine in `CollaboratorWebSocket` handler**
+
+In `internal/handler/handler.go`, find `CollaboratorWebSocket` (search for `GetOrCreateRoom`). After fetching the document and before registering the client, seed the room's OT engine if it's a new room:
+
+```go
+    room := h.CollaborationHub.GetOrCreateRoom(rKey)
+    // Seed OT engine with the current document text on first join.
+    // GetOrCreateRoom returns existing rooms unchanged — SetText is idempotent
+    // only if called before the first edit, which is guaranteed here because
+    // we check IsNewRoom() before seeding.
+    if room.IsNewRoom() {
+        var initialText string
+        if doc.Content != nil {
+            initialText = doc.Content.Text.RawMarkdown
+        }
+        room.SeedText(initialText)
+    }
+```
+
+This requires adding `IsNewRoom()` and `SeedText()` to `Room`.
+
+- [ ] **Step 6: Add `IsNewRoom` and `SeedText` to `Room` in `internal/collaboration/hub.go`**
+
+Add a `seeded` field to `Room`:
+
+```go
+type Room struct {
+    documentRKey string
+    clients      map[*Client]bool
+    broadcast    chan *broadcastMsg
+    register     chan *Client
+    unregister   chan *Client
+    mu           sync.RWMutex
+    ot           *OTEngine
+    seeded       bool  // true after SeedText has been called
+}
+```
+
+Add methods:
+
+```go
+// IsNewRoom returns true if SeedText has not yet been called on this room.
+func (r *Room) IsNewRoom() bool {
+    r.mu.RLock()
+    defer r.mu.RUnlock()
+    return !r.seeded
+}
+
+// SeedText sets the initial document text for the OT engine.
+// Safe to call only before the first edit is applied.
+func (r *Room) SeedText(text string) {
+    r.mu.Lock()
+    defer r.mu.Unlock()
+    if !r.seeded {
+        r.ot.SetText(text)
+        r.seeded = true
+    }
+}
+```
+
+- [ ] **Step 7: Write test for `SeedText`**
+
+Add to `internal/collaboration/hub_test.go`:
+
+```go
+func TestRoom_SeedText_SetsInitialOTState(t *testing.T) {
+    hub := NewHub()
+    room := hub.GetOrCreateRoom("doc-seed")
+    if !room.IsNewRoom() {
+        t.Fatal("new room should report IsNewRoom=true")
+    }
+    room.SeedText("initial document content")
+    if room.IsNewRoom() {
+        t.Error("IsNewRoom should be false after seeding")
+    }
+    if got := room.ot.GetText(); got != "initial document content" {
+        t.Errorf("OT text after seed: got %q, want %q", got, "initial document content")
+    }
+}
+
+func TestRoom_SeedText_IdempotentAfterFirstCall(t *testing.T) {
+    hub := NewHub()
+    room := hub.GetOrCreateRoom("doc-seed-idem")
+    room.SeedText("first")
+    room.SeedText("second") // should be ignored
+    if got := room.ot.GetText(); got != "first" {
+        t.Errorf("second SeedText should be ignored: got %q, want %q", got, "first")
+    }
+}
+```
+
+- [ ] **Step 8: Run all tests**
+
+```bash
+go test -v -race ./internal/collaboration/
+```
+
+Expected: all tests PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add internal/collaboration/ot.go internal/collaboration/hub.go \
+        internal/collaboration/ot_test.go internal/collaboration/hub_test.go \
+        internal/handler/handler.go
+git commit -m "feat: seed OT engine with document text on room creation"
+```
+
+---
+
+## Chunk 6: Final verification
+
+- [ ] **Run full test suite with race detector**
+
+```bash
+go test -v -race ./...
+```
+
+Expected: all tests PASS, no race conditions.
+
+- [ ] **Build**
+
+```bash
+make build
+```
+
+Expected: builds cleanly, no warnings.
+
+- [ ] **Lint**
+
+```bash
+make lint
+```
+
+Expected: no lint errors.
+
+- [ ] **End-to-end smoke test**
+
+```bash
+make run
+```
+
+1. Two users, same document, source mode: type rapidly — verify small WS messages (devtools → Network → WS frames).
+2. Two users, same document, rich mode: type — verify updates propagate correctly.
+3. Disconnect one user mid-edit — verify reconnect gets `sync` message with correct state.
+4. Empty the document entirely — verify the other user sees an empty document (tests the `Insert=""` deletion fix).
+
+- [ ] **Commit any fixups, then push**
+
+```bash
+git push origin feature/collaboration
+```