chore: remove custom OT engine and legacy delta WebSocket protocol

docs/superpowers/plans/2026-03-16-prosemirror-collab.md

···
+# ProseMirror-Collab 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 Diffdown's custom text-offset OT engine with `prosemirror-collab`'s step-based rebasing protocol, eliminating full-document replacement on every remote edit and enabling proper cursor preservation, undo, and conflict-free collaborative typing.
+
+**Architecture:** The Go server becomes a step authority: it stores an append-only log of ProseMirror `Step` JSON objects per document and a monotonically incrementing version counter. Clients submit `[steps, clientVersion]`; if the server version has advanced, the server rejects and the client fetches `GET /ws/docs/{rkey}/steps?since={v}`, rebases locally via `prosemirror-collab`, and resubmits. The WebSocket channel is kept for low-latency broadcasting of confirmed steps to other peers. The existing Hub/Room/Client goroutine structure and ATProto auth are unchanged.
+
+**Tech Stack:** Go 1.22 (server), `prosemirror-collab` npm package (client), CodeMirror 6 (source mode — kept as-is, receives text patches derived from confirmed steps), Milkdown/ProseMirror (rich mode — speaks native PM steps), SQLite (step log), existing Gorilla WebSocket.
+
+---
+
+## Chunk 1: Server — Step Storage
+
+### Task 1: Migration — `doc_steps` table
+
+**Files:**
+- Create: `migrations/006_doc_steps.sql`
+
+Steps must survive server restarts. One row per confirmed step; `version` is the 1-based ordinal within a document's history.
+
+- [ ] **Step 1: Write the migration**
+
+```sql
+-- migrations/006_doc_steps.sql
+CREATE TABLE IF NOT EXISTS doc_steps (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    doc_rkey  TEXT    NOT NULL,
+    version   INTEGER NOT NULL,
+    step_json TEXT    NOT NULL,
+    client_id TEXT    NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(doc_rkey, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_doc_steps_rkey_version ON doc_steps(doc_rkey, version);
+```
+
+- [ ] **Step 2: Run migration**
+
+```bash
+make migrate-up
+```
+
+Expected: `Applied migration: 006_doc_steps.sql` in server log.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add migrations/006_doc_steps.sql
+git commit -m "feat(db): add doc_steps table for prosemirror-collab step log"
+```
+
+---
+
+### Task 2: DB methods — `AppendSteps`, `GetStepsSince`, `GetDocVersion`
+
+**Files:**
+- Modify: `internal/db/db.go`
+
+Follow the existing pattern: raw SQL, no ORM, wrap errors with `fmt.Errorf`.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `internal/db/db_steps_test.go`:
+
+```go
+package db_test
+
+import (
+    "os"
+    "testing"
+
+    "github.com/limeleaf/diffdown/internal/db"
+)
+
+func openTestDB(t *testing.T) *db.DB {
+    t.Helper()
+    f, err := os.CreateTemp("", "diffdown-test-*.db")
+    if err != nil {
+        t.Fatal(err)
+    }
+    t.Cleanup(func() { os.Remove(f.Name()) })
+    f.Close()
+
+    database, err := db.Open(f.Name())
+    if err != nil {
+        t.Fatal(err)
+    }
+    db.SetMigrationsDir("../../migrations")
+    if err := database.Migrate(); err != nil {
+        t.Fatal(err)
+    }
+    return database
+}
+
+func TestGetDocVersion_Empty(t *testing.T) {
+    d := openTestDB(t)
+    v, err := d.GetDocVersion("rkey1")
+    if err != nil {
+        t.Fatal(err)
+    }
+    if v != 0 {
+        t.Errorf("expected version 0 for new doc, got %d", v)
+    }
+}
+
+func TestAppendSteps_IncreasesVersion(t *testing.T) {
+    d := openTestDB(t)
+    steps := []string{`{"stepType":"replace"}`, `{"stepType":"replace"}`}
+    newVersion, err := d.AppendSteps("rkey1", 0, steps, "client-a")
+    if err != nil {
+        t.Fatal(err)
+    }
+    if newVersion != 2 {
+        t.Errorf("expected version 2, got %d", newVersion)
+    }
+}
+
+func TestAppendSteps_VersionConflict(t *testing.T) {
+    d := openTestDB(t)
+    _, err := d.AppendSteps("rkey1", 0, []string{`{}`}, "client-a")
+    if err != nil {
+        t.Fatal(err)
+    }
+    // Submit again from clientVersion=0 (stale) — must fail.
+    _, err = d.AppendSteps("rkey1", 0, []string{`{}`}, "client-b")
+    if err == nil {
+        t.Fatal("expected conflict error, got nil")
+    }
+}
+
+func TestGetStepsSince(t *testing.T) {
+    d := openTestDB(t)
+    steps := []string{`{"a":1}`, `{"a":2}`, `{"a":3}`}
+    d.AppendSteps("rkey1", 0, steps, "client-a")
+
+    rows, err := d.GetStepsSince("rkey1", 1)
+    if err != nil {
+        t.Fatal(err)
+    }
+    if len(rows) != 2 {
+        t.Errorf("expected 2 steps since v1, got %d", len(rows))
+    }
+    if rows[0].JSON != `{"a":2}` {
+        t.Errorf("unexpected step: %s", rows[0].JSON)
+    }
+}
+```
+
+- [ ] **Step 2: Run tests — expect FAIL (functions not defined)**
+
+```bash
+go test -v ./internal/db/...
+```
+
+Expected: compile error — `db.GetDocVersion`, `db.AppendSteps`, `db.GetStepsSince` undefined.
+
+- [ ] **Step 3: Implement the DB methods**
+
+Add to `internal/db/db.go`:
+
+```go
+// --- Document Steps (prosemirror-collab) ---
+
+// StepRow is a confirmed ProseMirror step from the step log.
+type StepRow struct {
+    Version int
+    JSON    string
+}
+
+// GetDocVersion returns the current highest version for the given document.
+// Returns 0 if no steps have been recorded yet.
+func (db *DB) GetDocVersion(docRKey string) (int, error) {
+    var v int
+    err := db.QueryRow(
+        `SELECT COALESCE(MAX(version), 0) FROM doc_steps WHERE doc_rkey = ?`, docRKey,
+    ).Scan(&v)
+    if err != nil {
+        return 0, fmt.Errorf("GetDocVersion: %w", err)
+    }
+    return v, nil
+}
+
+// AppendSteps atomically appends steps starting at clientVersion+1.
+// Returns ErrVersionConflict if the server version has advanced past clientVersion.
+// Returns the new server version on success.
+func (db *DB) AppendSteps(docRKey string, clientVersion int, stepsJSON []string, clientID string) (int, error) {
+    tx, err := db.Begin()
+    if err != nil {
+        return 0, fmt.Errorf("AppendSteps begin: %w", err)
+    }
+    defer tx.Rollback()
+
+    var current int
+    tx.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM doc_steps WHERE doc_rkey = ?`, docRKey).Scan(&current)
+    if current != clientVersion {
+        return 0, fmt.Errorf("version conflict: server=%d client=%d", current, clientVersion)
+    }
+
+    for i, stepJSON := range stepsJSON {
+        version := clientVersion + i + 1
+        _, err := tx.Exec(
+            `INSERT INTO doc_steps (doc_rkey, version, step_json, client_id) VALUES (?, ?, ?, ?)`,
+            docRKey, version, stepJSON, clientID,
+        )
+        if err != nil {
+            return 0, fmt.Errorf("AppendSteps insert v%d: %w", version, err)
+        }
+    }
+
+    if err := tx.Commit(); err != nil {
+        return 0, fmt.Errorf("AppendSteps commit: %w", err)
+    }
+    return clientVersion + len(stepsJSON), nil
+}
+
+// GetStepsSince returns all steps with version > sinceVersion, ordered ascending.
+func (db *DB) GetStepsSince(docRKey string, sinceVersion int) ([]StepRow, error) {
+    rows, err := db.Query(
+        `SELECT version, step_json FROM doc_steps WHERE doc_rkey = ? AND version > ? ORDER BY version ASC`,
+        docRKey, sinceVersion,
+    )
+    if err != nil {
+        return nil, fmt.Errorf("GetStepsSince: %w", err)
+    }
+    defer rows.Close()
+    var result []StepRow
+    for rows.Next() {
+        var r StepRow
+        if err := rows.Scan(&r.Version, &r.JSON); err != nil {
+            return nil, err
+        }
+        result = append(result, r)
+    }
+    return result, rows.Err()
+}
+```
+
+- [ ] **Step 4: Run tests — expect PASS**
+
+```bash
+go test -v ./internal/db/...
+```
+
+Expected: all `TestGetDocVersion_*`, `TestAppendSteps_*`, `TestGetStepsSince` PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/db/db.go internal/db/db_steps_test.go
+git commit -m "feat(db): add AppendSteps, GetStepsSince, GetDocVersion for step log"
+```
+
+---
+
+## Chunk 2: Server — Step Authority HTTP Endpoint
+
+The step-exchange protocol uses two new HTTP endpoints:
+
+- `POST /api/docs/{rkey}/steps` — submit steps from client; returns `{version, steps}` on conflict or `{version}` on success
+- `GET  /api/docs/{rkey}/steps?since={v}` — fetch steps the client missed
+
+The WebSocket channel continues to broadcast `{type:"steps", steps:[...], version:N}` messages to peers in real-time.
+
+### Task 3: `SubmitSteps` and `GetSteps` HTTP handlers
+
+**Files:**
+- Modify: `internal/handler/handler.go`
+- Modify: `cmd/server/main.go` (route registration)
+
+- [ ] **Step 1: Write the handlers**
+
+Add to `internal/handler/handler.go` (below the existing `CollaboratorWebSocket`):
+
+```go
+// SubmitSteps receives ProseMirror steps from a collaborator, appends them
+// to the step log, and broadcasts confirmed steps to the room.
+//
+// POST /api/docs/{rkey}/steps
+// Body: {"clientVersion": N, "steps": ["...json..."], "clientID": "did:..."}
+// Response 200: {"version": N}
+// Response 409: {"version": N, "steps": ["...json..."]} — client must rebase
+func (h *Handler) SubmitSteps(w http.ResponseWriter, r *http.Request) {
+    user := h.currentUser(r)
+    if user == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+    rkey := r.PathValue("rkey")
+
+    var body struct {
+        ClientVersion int      `json:"clientVersion"`
+        Steps         []string `json:"steps"`
+        ClientID      string   `json:"clientID"`
+    }
+    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+        http.Error(w, "Bad request", http.StatusBadRequest)
+        return
+    }
+    if len(body.Steps) == 0 {
+        http.Error(w, "No steps", http.StatusBadRequest)
+        return
+    }
+
+    newVersion, err := h.DB.AppendSteps(rkey, body.ClientVersion, body.Steps, body.ClientID)
+    if err != nil {
+        // Version conflict — return steps the client missed.
+        missed, dbErr := h.DB.GetStepsSince(rkey, body.ClientVersion)
+        if dbErr != nil {
+            log.Printf("SubmitSteps: GetStepsSince: %v", dbErr)
+            http.Error(w, "Internal error", http.StatusInternalServerError)
+            return
+        }
+        currentVersion, _ := h.DB.GetDocVersion(rkey)
+        stepJSONs := make([]string, len(missed))
+        for i, s := range missed {
+            stepJSONs[i] = s.JSON
+        }
+        w.Header().Set("Content-Type", "application/json")
+        w.WriteHeader(http.StatusConflict)
+        json.NewEncoder(w).Encode(map[string]interface{}{
+            "version": currentVersion,
+            "steps":   stepJSONs,
+        })
+        return
+    }
+
+    // Broadcast to other room members via WebSocket.
+    if room := h.CollaborationHub.GetRoom(rkey); room != nil {
+        type stepsMsg struct {
+            Type     string   `json:"type"`
+            Steps    []string `json:"steps"`
+            Version  int      `json:"version"`
+            ClientID string   `json:"clientID"`
+        }
+        data, _ := json.Marshal(stepsMsg{
+            Type:     "steps",
+            Steps:    body.Steps,
+            Version:  newVersion,
+            ClientID: body.ClientID,
+        })
+        room.Broadcast(data)
+    }
+
+    h.jsonResponse(w, map[string]int{"version": newVersion}, http.StatusOK)
+}
+
+// GetSteps returns all steps since the given version.
+//
+// GET /api/docs/{rkey}/steps?since={v}
+// Response 200: {"version": N, "steps": ["...json..."]}
+func (h *Handler) GetSteps(w http.ResponseWriter, r *http.Request) {
+    user := h.currentUser(r)
+    if user == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+    rkey := r.PathValue("rkey")
+
+    sinceStr := r.URL.Query().Get("since")
+    var since int
+    if sinceStr != "" {
+        fmt.Sscanf(sinceStr, "%d", &since)
+    }
+
+    rows, err := h.DB.GetStepsSince(rkey, since)
+    if err != nil {
+        log.Printf("GetSteps: %v", err)
+        http.Error(w, "Internal error", http.StatusInternalServerError)
+        return
+    }
+    version, _ := h.DB.GetDocVersion(rkey)
+    stepJSONs := make([]string, len(rows))
+    for i, s := range rows {
+        stepJSONs[i] = s.JSON
+    }
+    h.jsonResponse(w, map[string]interface{}{
+        "version": version,
+        "steps":   stepJSONs,
+    }, http.StatusOK)
+}
+```
+
+- [ ] **Step 2: Register routes in `cmd/server/main.go`**
+
+Find the route block and add after the existing `/ws/docs/{rkey}` line:
+
+```go
+mux.HandleFunc("POST /api/docs/{rkey}/steps", middleware.RequireAuth(h.SubmitSteps))
+mux.HandleFunc("GET /api/docs/{rkey}/steps", middleware.RequireAuth(h.GetSteps))
+```
+
+- [ ] **Step 3: Build to catch type errors**
+
+```bash
+make build
+```
+
+Expected: `bin/server` produced, zero errors.
+
+- [ ] **Step 4: Smoke-test manually**
+
+```bash
+make run
+# In another terminal:
+curl -s -b 'session=<valid-cookie>' http://localhost:8080/api/docs/somekey/steps?since=0
+# Expected: {"steps":[],"version":0}
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/handler/handler.go cmd/server/main.go
+git commit -m "feat(handler): add SubmitSteps and GetSteps HTTP endpoints"
+```
+
+---
+
+### Task 4: Handler tests for `SubmitSteps` and `GetSteps`
+
+**Files:**
+- Create: `internal/handler/steps_test.go`
+
+The existing handler tests use `httptest` with a real in-memory SQLite DB. Follow that pattern.
+
+- [ ] **Step 1: Write tests**
+
+```go
+package handler_test
+
+import (
+    "bytes"
+    "encoding/json"
+    "net/http"
+    "net/http/httptest"
+    "os"
+    "testing"
+
+    "github.com/limeleaf/diffdown/internal/db"
+    "github.com/limeleaf/diffdown/internal/handler"
+    "github.com/limeleaf/diffdown/internal/collaboration"
+)
+
+func setupHandler(t *testing.T) (*handler.Handler, *db.DB) {
+    t.Helper()
+    f, _ := os.CreateTemp("", "diffdown-handler-*.db")
+    t.Cleanup(func() { os.Remove(f.Name()) })
+    f.Close()
+    database, _ := db.Open(f.Name())
+    db.SetMigrationsDir("../../migrations")
+    database.Migrate()
+    hub := collaboration.NewHub()
+    h := handler.New(database, nil, "http://localhost:8080", hub)
+    return h, database
+}
+
+func TestGetSteps_Empty(t *testing.T) {
+    h, _ := setupHandler(t)
+    req := httptest.NewRequest("GET", "/api/docs/rkey1/steps?since=0", nil)
+    req.SetPathValue("rkey", "rkey1")
+    rr := httptest.NewRecorder()
+    // Inject a fake user into context so currentUser() passes.
+    // (Reuse the test helper from existing handler tests if one exists,
+    //  or set the session key directly on the request context.)
+    h.GetSteps(rr, req) // will return 401 without auth — adjust with auth helper
+    // For now verify content-type at minimum:
+    if rr.Code != http.StatusUnauthorized {
+        t.Errorf("expected 401 without auth, got %d", rr.Code)
+    }
+}
+
+func TestSubmitSteps_Success(t *testing.T) {
+    h, d := setupHandler(t)
+    _ = d // seed a user/session if needed for auth
+
+    body, _ := json.Marshal(map[string]interface{}{
+        "clientVersion": 0,
+        "steps":         []string{`{"stepType":"replace"}`},
+        "clientID":      "did:plc:test",
+    })
+    req := httptest.NewRequest("POST", "/api/docs/rkey1/steps", bytes.NewReader(body))
+    req.SetPathValue("rkey", "rkey1")
+    req.Header.Set("Content-Type", "application/json")
+    rr := httptest.NewRecorder()
+    h.SubmitSteps(rr, req) // 401 without auth — add auth helper before expanding
+    if rr.Code != http.StatusUnauthorized {
+        t.Errorf("expected 401, got %d", rr.Code)
+    }
+}
+```
+
+> **Note:** These are skeleton tests that verify the 401 path. Full integration tests (with authenticated requests) require the existing `setUserContext` test helper from the handler package. Expand once you confirm the handlers build and the 401 path works.
+
+- [ ] **Step 2: Run tests**
+
+```bash
+go test -v ./internal/handler/...
+```
+
+Expected: new tests PASS (401 assertions).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add internal/handler/steps_test.go
+git commit -m "test(handler): skeleton tests for SubmitSteps and GetSteps"
+```
+
+---
+
+## Chunk 3: Client — Install `prosemirror-collab`
+
+### Task 5: Add npm dependency and bundle
+
+**Files:**
+- Modify: `package.json`
+- Modify: `milkdown-entry.js` (re-export collab plugin for rich mode)
+- Create: `static/vendor/collab.js` (built artifact — gitignored or committed)
+
+`prosemirror-collab` is the official ProseMirror collaboration plugin. It exports `collab(config)`, `sendableSteps(state)`, and `receiveTransaction(state, steps, clientIDs)`.
+
+- [ ] **Step 1: Install the package**
+
+```bash
+npm install prosemirror-collab prosemirror-state prosemirror-transform
+```
+
+- [ ] **Step 2: Verify the package is available**
+
+```bash
+node -e "require('prosemirror-collab'); console.log('ok')"
+```
+
+Expected: `ok`.
+
+- [ ] **Step 3: Bundle a collab module for the browser**
+
+Add a build script to `package.json` (merge into existing scripts if present):
+
+```json
+{
+  "scripts": {
+    "build:collab": "npx esbuild node_modules/prosemirror-collab/dist/index.js --bundle --format=esm --outfile=static/vendor/collab.js"
+  }
+}
+```
+
+Run it:
+
+```bash
+npm run build:collab
+```
+
+Expected: `static/vendor/collab.js` created (~20KB).
+
+- [ ] **Step 4: Confirm exports**
+
+```bash
+node -e "
+const src = require('fs').readFileSync('static/vendor/collab.js','utf8');
+['collab','sendableSteps','receiveTransaction','getVersion'].forEach(name => {
+  if (!src.includes(name)) throw new Error('missing: ' + name);
+});
+console.log('all exports present');
+"
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json package-lock.json static/vendor/collab.js
+git commit -m "feat(frontend): bundle prosemirror-collab for browser"
+```
+
+---
+
+## Chunk 4: Client — Source Mode (CodeMirror) Integration
+
+The source editor (CodeMirror) operates on plain text. `prosemirror-collab` works at the ProseMirror document level; for the source mode we keep the existing send-deltas-on-change approach but replace the full-document-replace on receive with a proper `ChangeSet`-based patch derived from confirmed steps.
+
+**Protocol for source mode:**
+1. On local change: send `POST /api/docs/{rkey}/steps` with `[{type:"text-patch", from, to, insert}]` step objects (a lightweight custom step shape — source mode does not use PM's schema-aware steps).
+2. On `409 Conflict`: fetch missed steps from response, apply them to local text first, then resubmit.
+3. On WebSocket `steps` message: apply the text patches to the CM editor using a minimal `ChangeSet` that skips the sender's own steps.
+
+This is logically equivalent to `prosemirror-collab` but for a flat-text editor. It gives us the rebasing guarantee without requiring a ProseMirror schema in source mode.
+
+### Task 6: Client-side collab state manager (`collab-client.js`)
+
+**Files:**
+- Create: `static/collab-client.js`
+
+This module encapsulates all step-submission and rebasing logic and is shared between source and rich modes.
+
+- [ ] **Step 1: Write the module**
+
+```js
+// static/collab-client.js
+//
+// Lightweight step-authority client for Diffdown's prosemirror-collab protocol.
+// Works with both source (text-patch steps) and rich (PM steps) modes.
+
+export class CollabClient {
+    /**
+     * @param {string} rkey - Document rkey
+     * @param {number} initialVersion - Version the client started at
+     * @param {function(steps: object[]): void} applyRemoteSteps - Called when server confirms steps from others
+     */
+    constructor(rkey, initialVersion, applyRemoteSteps) {
+        this.rkey = rkey;
+        this.version = initialVersion;
+        this.applyRemoteSteps = applyRemoteSteps;
+        this._inflight = false;
+        this._queue = [];
+    }
+
+    /**
+     * Queue local steps and attempt to flush to the server.
+     * @param {object[]} steps - Array of step objects (text-patch or PM step JSON)
+     */
+    sendSteps(steps) {
+        this._queue.push(...steps);
+        this._flush();
+    }
+
+    async _flush() {
+        if (this._inflight || this._queue.length === 0) return;
+        this._inflight = true;
+        const toSend = this._queue.slice();
+        try {
+            const resp = await fetch(`/api/docs/${this.rkey}/steps`, {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({
+                    clientVersion: this.version,
+                    steps: toSend.map(s => JSON.stringify(s)),
+                    clientID: this._clientID || '',
+                }),
+            });
+
+            if (resp.ok) {
+                const {version} = await resp.json();
+                this.version = version;
+                // Remove the steps we just confirmed.
+                this._queue = this._queue.slice(toSend.length);
+            } else if (resp.status === 409) {
+                // Server has steps we haven't seen yet.
+                const {version, steps: missedJSON} = await resp.json();
+                const missed = missedJSON.map(s => JSON.parse(s));
+                // Let the editor rebase local steps on top of missed ones.
+                this.applyRemoteSteps(missed);
+                this.version = version;
+                // Don't clear _queue — resubmit after rebase.
+            } else {
+                console.error('CollabClient: unexpected status', resp.status);
+            }
+        } catch (e) {
+            console.error('CollabClient: fetch error', e);
+        } finally {
+            this._inflight = false;
+            if (this._queue.length > 0) {
+                setTimeout(() => this._flush(), 50);
+            }
+        }
+    }
+
+    /**
+     * Call when a WebSocket "steps" message arrives from the server.
+     * Advances local version and notifies the editor.
+     * @param {object} msg - {type:"steps", steps:[...], version:N, clientID:string}
+     * @param {string} myClientID
+     */
+    handleWSMessage(msg, myClientID) {
+        if (msg.type !== 'steps') return;
+        if (msg.clientID === myClientID) {
+            // Our own steps confirmed — just advance version.
+            this.version = msg.version;
+            return;
+        }
+        const steps = msg.steps.map(s => JSON.parse(s));
+        this.version = msg.version;
+        this.applyRemoteSteps(steps);
+    }
+
+    setClientID(id) { this._clientID = id; }
+}
+```
+
+- [ ] **Step 2: Verify it parses without errors**
+
+```bash
+node --input-type=module < static/collab-client.js 2>&1 || true
+```
+
+Expected: no syntax errors (will emit a fetch-not-defined error at runtime in Node, that's fine).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add static/collab-client.js
+git commit -m "feat(frontend): CollabClient — step-submission and rebase coordinator"
+```
+
+---
+
+### Task 7: Wire `CollabClient` into source mode (CodeMirror)
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+The existing source-mode flow:
+1. `update.changes.iterChanges` → `queueDeltas` → WebSocket `edit` message
+2. `handleWSMessage({type:'edit'})` → `applyRemoteEdit` → full CM replace
+
+New flow:
+1. `update.changes.iterChanges` → `CollabClient.sendSteps` (text-patch steps via HTTP)
+2. WebSocket `steps` message → `CollabClient.handleWSMessage` → `applyTextPatchSteps` (apply only the changed ranges)
+
+- [ ] **Step 1: Fetch server version on page load**
+
+At the top of the `<script type="module">` block, after constants, add:
+
+```js
+import { CollabClient } from '/static/collab-client.js';
+
+// Fetch the authoritative version for this document.
+let serverVersion = 0;
+try {
+    const vResp = await fetch(`/api/docs/${rkey}/steps?since=-1`);
+    if (vResp.ok) {
+        const vData = await vResp.json();
+        serverVersion = vData.version || 0;
+    }
+} catch(e) { /* start at 0 */ }
+
+const myClientID = accessToken || Math.random().toString(36).slice(2);
+```
+
+- [ ] **Step 2: Replace `queueDeltas` in source mode with `CollabClient.sendSteps`**
+
+Replace the `EditorView.updateListener.of` callback block for source mode:
+
+Old code (in `document_edit.html`, inside the CM `updateListener`):
+```js
+if (deltas.length > 0) {
+    queueDeltas(deltas);
+}
+```
+
+New code — instead of `queueDeltas`, call `collabClient.sendSteps`:
+```js
+if (deltas.length > 0 && currentMode === 'source') {
+    const pmSteps = deltas.map(d => ({type: 'text-patch', from: d.from, to: d.to, insert: d.insert}));
+    collabClient.sendSteps(pmSteps);
+}
+```
+
+- [ ] **Step 3: Initialize `collabClient` after `cmView` is created**
+
+```js
+const collabClient = new CollabClient(rkey, serverVersion, (remoteSteps) => {
+    // Apply text-patch steps to CM without triggering our own send.
+    if (currentMode !== 'source' || !cmView) return;
+    const changes = [];
+    let offset = 0;
+    for (const step of remoteSteps) {
+        if (step.type !== 'text-patch') continue;
+        const from = step.from + offset;
+        const to   = step.to   + offset;
+        const insert = step.insert || '';
+        changes.push({ from, to, insert });
+        offset += insert.length - (step.to - step.from);
+    }
+    if (changes.length === 0) return;
+    applyingRemote = true;
+    try {
+        cmView.dispatch({
+            changes,
+            annotations: [remoteEditAnnotation.of(true)],
+        });
+    } finally {
+        applyingRemote = false;
+    }
+});
+collabClient.setClientID(myClientID);
+```
+
+- [ ] **Step 4: Wire WebSocket messages into `CollabClient`**
+
+In `handleWSMessage`, add a case for `'steps'`:
+
+```js
+case 'steps':
+    collabClient.handleWSMessage(msg, myClientID);
+    break;
+```
+
+Keep the existing `'edit'` case temporarily (for backward compat during rollout), but stop relying on `msg.content` for source mode when `msg.type === 'edit'` AND `msg.steps` is present.
+
+- [ ] **Step 5: Build and manually test source mode collab**
+
+```bash
+make run
+```
+
+Open two browser tabs on the same document (two different accounts). Type in source mode in tab 1 — verify tab 2 updates without full-document flash. Cursor position in tab 2 should not reset.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "feat(frontend): source mode uses CollabClient step protocol instead of full-replace"
+```
+
+---
+
+## Chunk 5: Client — Rich Mode (Milkdown/ProseMirror) Integration
+
+Milkdown wraps ProseMirror. The `prosemirror-collab` plugin integrates directly at the ProseMirror `EditorState` level using `collab({version})` and `sendableSteps(state)` / `receiveTransaction(state, steps, clientIDs)`.
+
+This replaces the `createMilkdownEditor(content)` full-recreate on remote edit.
+
+### Task 8: Wire `prosemirror-collab` plugin into Milkdown
+
+**Files:**
+- Modify: `templates/document_edit.html`
+- Modify: `milkdown-entry.js` (re-export PM collab helpers)
+
+- [ ] **Step 1: Re-export collab helpers from `milkdown-entry.js`**
+
+`milkdown-entry.js` is bundled into `static/vendor/milkdown.js`. Add the collab exports:
+
+```js
+// milkdown-entry.js — add at bottom:
+export { collab, sendableSteps, receiveTransaction, getVersion } from 'prosemirror-collab';
+export { Step } from 'prosemirror-transform';
+```
+
+Rebuild:
+
+```bash
+npx esbuild milkdown-entry.js --bundle --format=esm --minify --outfile=static/vendor/milkdown.js \
+  node_modules/prosemirror-collab/dist/index.js \
+  node_modules/prosemirror-transform/dist/index.js
+```
+
+> Check your existing esbuild command in `package.json` or `Dockerfile` and update accordingly. The Dockerfile uses `npx esbuild milkdown-entry.js ...` — update that line too.
+
+- [ ] **Step 2: Import in the editor script**
+
+In `document_edit.html`, update the Milkdown import line:
+
+```js
+import {
+    Editor, rootCtx, defaultValueCtx, editorViewCtx, serializerCtx,
+    commonmark,
+    listener, listenerCtx,
+    history, undoCommand, redoCommand, callCommand,
+    collab, sendableSteps, receiveTransaction, getVersion, Step,
+} from '/static/vendor/milkdown.js';
+```
+
+- [ ] **Step 3: Replace `createMilkdownEditor` to use `collab` plugin**
+
+The key change: pass `collab({version: serverVersion})` as a ProseMirror plugin. When `markdownUpdated` fires (local edit), use `sendableSteps` to get the pending steps and send them through `CollabClient`. When remote steps arrive, use `receiveTransaction` to apply them to the PM state surgically — **no re-create**.
+
+```js
+async function createMilkdownEditor(initialMarkdown) {
+    const container = document.getElementById('editor-rich');
+    container.innerHTML = '';
+
+    milkdownEditor = await Editor.make()
+        .config((ctx) => {
+            ctx.set(rootCtx, container);
+            ctx.set(defaultValueCtx, initialMarkdown);
+        })
+        .use(commonmark)
+        .use(history)
+        .use(listener)
+        .config((ctx) => {
+            ctx.get(listenerCtx).markdownUpdated((_ctx, markdown, prevMarkdown) => {
+                if (markdown === prevMarkdown || applyingRemote) return;
+                scheduleAutoSave(markdown);
+                // Use prosemirror-collab to extract pending steps.
+                const pmView = milkdownEditor.action(c => c.get(editorViewCtx));
+                const sendable = sendableSteps(pmView.state);
+                if (sendable) {
+                    const stepsJSON = sendable.steps.map(s => JSON.stringify(s.toJSON()));
+                    collabClient.sendSteps(stepsJSON.map(j => ({type: 'pm-step', json: j})));
+                }
+            });
+        })
+        .create();
+
+    return milkdownEditor;
+}
+```
+
+- [ ] **Step 4: Apply remote PM steps without re-creating the editor**
+
+Update `CollabClient`'s `applyRemoteSteps` callback for rich mode:
+
+```js
+// In the CollabClient constructor call (Task 7), update the callback to handle rich mode:
+const collabClient = new CollabClient(rkey, serverVersion, (remoteSteps) => {
+    if (currentMode === 'source' && cmView) {
+        // ... existing text-patch logic from Task 7 ...
+    } else if (currentMode === 'rich' && milkdownEditor) {
+        const pmView = milkdownEditor.action(c => c.get(editorViewCtx));
+        const schema = pmView.state.schema;
+        const pmSteps = [];
+        const clientIDs = [];
+        for (const step of remoteSteps) {
+            if (step.type !== 'pm-step') continue;
+            try {
+                pmSteps.push(Step.fromJSON(schema, JSON.parse(step.json)));
+                clientIDs.push('remote');
+            } catch(e) {
+                console.warn('CollabClient: failed to parse step', e);
+            }
+        }
+        if (pmSteps.length === 0) return;
+        applyingRemote = true;
+        try {
+            const tr = receiveTransaction(pmView.state, pmSteps, clientIDs);
+            pmView.dispatch(tr);
+        } finally {
+            applyingRemote = false;
+        }
+    }
+});
+```
+
+- [ ] **Step 5: Remove `createMilkdownEditor(content)` call in `applyRemoteEdit`**
+
+The old `applyRemoteEdit` called `createMilkdownEditor(content)` (full recreate) for rich mode. Now that `CollabClient` handles remote steps, remove that branch. The `applyRemoteEdit` function should only handle the legacy `sync` message type as a fallback:
+
+```js
+function applyRemoteEdit(msg) {
+    // Legacy sync fallback — only used on initial join if the room sends full content.
+    if (applyingRemote) return;
+    const content = typeof msg === 'string' ? msg : msg.content;
+    if (!content) return;
+
+    if (currentMode === 'source' && cmView) {
+        if (cmView.state.doc.toString() !== content) {
+            applyingRemote = true;
+            try {
+                cmView.dispatch({
+                    changes: { from: 0, to: cmView.state.doc.length, insert: content },
+                    annotations: [remoteEditAnnotation.of(true)],
+                });
+            } finally {
+                applyingRemote = false;
+            }
+        }
+    }
+    // Rich mode no longer falls back to full recreate.
+}
+```
+
+- [ ] **Step 6: Build and manually test rich mode collab**
+
+```bash
+npm run build:collab
+make build && make run
+```
+
+Open two tabs, both in rich mode. Type in one — verify the other updates without the editor flicker (no DOM teardown). Undo in each tab should only undo local edits.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add milkdown-entry.js static/vendor/milkdown.js static/vendor/collab.js templates/document_edit.html
+git commit -m "feat(frontend): rich mode uses prosemirror-collab steps, no full editor recreate"
+```
+
+---
+
+## Chunk 6: Cleanup and Deprecate Old Code
+
+### Task 9: Remove the custom OT engine (server)
+
+Once `prosemirror-collab` is the only collab protocol in production, the custom `OTEngine` and the `edit`-type WebSocket message handler become dead code.
+
+- [ ] **Step 1: Verify no active callers**
+
+```bash
+grep -rn "OTEngine\|ApplyEdits\|applyInternal\|type.*edit.*delta" internal/ templates/ --include="*.go" --include="*.html"
+```
+
+Review the output. If `ApplyEdits` or `OTEngine` are still called by the WebSocket handler (`client.go`), leave them in place and just stop broadcasting `edit`-type messages; otherwise delete.
+
+- [ ] **Step 2: Remove `ot.go` and `ot_test.go` if unused**
+
+```bash
+# Only if grep above shows zero active callers:
+git rm internal/collaboration/ot.go internal/collaboration/ot_test.go
+```
+
+- [ ] **Step 3: Remove `ot *OTEngine` field from `Room`**
+
+In `internal/collaboration/hub.go`, delete:
+- `ot *OTEngine` field on `Room`
+- `NewOTEngine("")` call in `GetOrCreateRoom`
+- `ApplyEdits` method on `Room`
+- `SeedText`, `IsNewRoom` methods (no longer needed — initial version is fetched from DB)
+
+- [ ] **Step 4: Remove `seeded` guard from WebSocket handler**
+
+In `internal/handler/handler.go`, in `CollaboratorWebSocket`, delete the `room.IsNewRoom()` / `room.SeedText(initialText)` block. The server no longer needs to seed an in-memory text state.
+
+- [ ] **Step 5: Remove legacy `edit`-type message handling from `client.go`**
+
+In `internal/collaboration/client.go`, delete the `case "edit":` branch in `ReadPump`. The WebSocket channel now only carries `steps`, `presence`, and `ping/pong`.
+
+- [ ] **Step 6: Remove `queueDeltas`, `diffToOps`, `sendEdit`, `pendingDeltas` from frontend**
+
+In `templates/document_edit.html`, delete:
+- `function diffToOps(...)` (~60 lines)
+- `function queueDeltas(...)` (~15 lines)
+- `function sendEdit(...)` (~5 lines)
+- `let pendingDeltas`, `let wsEditTimer`
+
+- [ ] **Step 7: Build and run all tests**
+
+```bash
+make build
+make test
+```
+
+Expected: all tests PASS, no compile errors.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add -A
+git commit -m "chore: remove custom OT engine and legacy delta WebSocket protocol"
+```
+
+---
+
+### Task 10: Update Dockerfile build step for new bundles
+
+**Files:**
+- Modify: `Dockerfile`
+
+The Dockerfile has a `jsbuilder` stage with an `esbuild` command. The `milkdown-entry.js` bundle command needs the new `prosemirror-collab` and `prosemirror-transform` packages in scope.
+
+- [ ] **Step 1: Check current jsbuilder stage**
+
+```bash
+grep -A 20 "jsbuilder" Dockerfile
+```
+
+- [ ] **Step 2: Add collab bundle step**
+
+After the existing `RUN npx esbuild milkdown-entry.js ...` line, add:
+
+```dockerfile
+RUN npx esbuild node_modules/prosemirror-collab/dist/index.js \
+    --bundle --format=esm --minify --outfile=collab.min.js
+```
+
+And in the `COPY --from=jsbuilder` lines in the final stage, add:
+
+```dockerfile
+COPY --from=jsbuilder /build/collab.min.js ./static/vendor/collab.js
+```
+
+- [ ] **Step 3: Build Docker image locally**
+
+```bash
+docker build -t diffdown-test .
+```
+
+Expected: successful build, no missing module errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "chore(docker): build prosemirror-collab bundle in jsbuilder stage"
+```
+
+---
+
+## Chunk 7: End-to-End Testing
+
+### Task 11: Manual collab regression checklist
+
+Run through these scenarios with two browser windows logged in as different users on the same document:
+
+- [ ] **Scenario A — Concurrent typing (source mode)**
+  - Both users type simultaneously. After a brief pause, both editors show identical text.
+  - **Pass condition:** No full-page flash, no cursor jump in the non-typing window.
+
+- [ ] **Scenario B — Concurrent typing (rich mode)**
+  - Same as A but in rich mode. Bold/italic marks applied by one user appear in the other.
+  - **Pass condition:** Editor does not tear down and recreate on each remote step.
+
+- [ ] **Scenario C — Undo isolation**
+  - User A types "hello", User B types "world". User A presses undo.
+  - **Pass condition:** Only "hello" is removed; "world" remains.
+
+- [ ] **Scenario D — Network reconnect**
+  - User A types while User B's tab is in the background (WebSocket dormant).
+  - User B foregrounds — page catches up via `GET /api/docs/{rkey}/steps?since={v}`.
+  - **Pass condition:** B's editor converges without a reload.
+
+- [ ] **Scenario E — Single user, no collaborators**
+  - Open a document alone. Type normally. Auto-save fires.
+  - **Pass condition:** Behavior is identical to before; no regressions.
+
+---
+
+### Task 12: Deploy to staging
+
+- [ ] **Step 1: Push to origin**
+
+```bash
+git push origin main
+```
+
+- [ ] **Step 2: Deploy to staging**
+
+```bash
+flyctl deploy --config fly-staging.toml
+```
+
+- [ ] **Step 3: Run manual regression checklist against staging**
+
+Repeat the scenarios in Task 11 against `https://staging.diffdown.com`.
+
+- [ ] **Step 4: Deploy to production**
+
+```bash
+flyctl deploy --config fly-production.toml
+```
+
+---
+
+## Appendix: Protocol Reference
+
+### WebSocket message types (post-migration)
+
+| Direction | Type | Payload | Purpose |
+|---|---|---|---|
+| Server → Client | `steps` | `{steps: string[], version: int, clientID: string}` | Broadcast confirmed steps to room peers |
+| Server → Client | `presence` | `{users: [{did, name, color}]}` | Room membership changes |
+| Server → Client | `pong` | `{}` | Keepalive reply |
+| Client → Server | `ping` | `{}` | Keepalive |
+
+### HTTP endpoints (post-migration)
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/api/docs/{rkey}/steps` | Submit steps; 200 on accept, 409 on conflict |
+| `GET` | `/api/docs/{rkey}/steps?since={v}` | Fetch missed steps |
+
+### Step shapes
+
+**Source mode** (text-patch):
+```json
+{"type": "text-patch", "from": 5, "to": 8, "insert": "foo"}
+```
+
+**Rich mode** (PM step):
+```json
+{"type": "pm-step", "json": "{\"stepType\":\"replace\",...}"}
+```

internal/collaboration/client.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
+	Type    string      `json:"type"`
+	RKey    string      `json:"rkey,omitempty"`
+	DID     string      `json:"did,omitempty"`
+	Cursor  *CursorPos  `json:"cursor,omitempty"`
+	Comment *CommentMsg `json:"comment,omitempty"`
 }
 
 type CursorPos struct {
···
 		}
 
 		switch msg.Type {
-		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)
 		case "ping":
 			pong, _ := json.Marshal(map[string]string{"type": "pong"})
 			c.send <- pong

internal/collaboration/client_test.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")
-	}
-}

internal/collaboration/hub.go

···
 	register     chan *Client
 	unregister   chan *Client
 	mu           sync.RWMutex
-	ot           *OTEngine
-	seeded       bool // true after SeedText has been called
 }
 
 // broadcastMsg carries a message and an optional sender to exclude.
···
 		broadcast:    make(chan *broadcastMsg, 256),
 		register:     make(chan *Client),
 		unregister:   make(chan *Client),
-		ot:           NewOTEngine(""),
 	}
 	h.rooms[rkey] = room
 	go room.run()
···
 	r.broadcast <- &broadcastMsg{data: data, except: except}
 }
 
-// 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
-	}
-
-	// Capture the text returned by the final ApplyWithVersion so we don't
-	// race against another goroutine calling GetText() separately.
-	var finalText string
-	for i := range ops {
-		finalText, _ = r.ot.ApplyWithVersion(ops[i])
-	}
-
-	// Include the full document text so receivers can detect and recover from
-	// divergence without a reconnect.
-	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)
-}
-
 func (r *Room) RegisterClient(client *Client) {
 	r.register <- client
 }
···
 	}
 	r.Broadcast(data)
 }
-
-// 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.
-// Idempotent — only the first call has effect.
-func (r *Room) SeedText(text string) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	if !r.seeded {
-		r.ot.SetText(text)
-		r.seeded = true
-	}
-}

internal/collaboration/hub_test.go

···
 	}
 }
 
-// --- Room ApplyEdits tests ---
-
-func TestRoom_ApplyEdit_BroadcastsToOthers(t *testing.T) {
-	hub := NewHub()
-	room := hub.GetOrCreateRoom("doc-edit")
-
-	alice := stubClient(hub, "did:plc:alice", "Alice", "#ff0000", "doc-edit")
-	bob := stubClient(hub, "did:plc:bob", "Bob", "#0000ff", "doc-edit")
-
-	room.RegisterClient(alice)
-	room.RegisterClient(bob)
-	time.Sleep(100 * time.Millisecond)
-	drain(alice, 200*time.Millisecond)
-	drain(bob, 200*time.Millisecond)
-
-	room.ApplyEdits([]Operation{{From: 0, To: -1, Insert: "hello world"}}, alice)
-
-	// Bob should receive the edit message; alice should not
-	bobMsgs := waitForMessages(bob, 1, time.Second)
-	aliceMsgs := drain(alice, 300*time.Millisecond)
-
-	if len(bobMsgs) == 0 {
-		t.Fatal("bob: expected edit message, got none")
-	}
-	if len(aliceMsgs) > 0 {
-		t.Errorf("alice: should not receive her own edit, got %d messages", len(aliceMsgs))
-	}
-
-	var msg map[string]interface{}
-	if err := json.Unmarshal(bobMsgs[0], &msg); err != nil {
-		t.Fatalf("unmarshal edit msg: %v", err)
-	}
-	if msg["type"] != "edit" {
-		t.Errorf("expected type=edit, got %q", msg["type"])
-	}
-	if msg["author"] != "did:plc:alice" {
-		t.Errorf("expected author did:plc:alice, got %q", msg["author"])
-	}
-	if msg["content"] != "hello world" {
-		t.Errorf("expected content %q, got %q", "hello world", msg["content"])
-	}
-}
-
-func TestRoom_ApplyEdit_UpdatesOTState(t *testing.T) {
-	hub := NewHub()
-	room := hub.GetOrCreateRoom("doc-ot-state")
-
-	alice := stubClient(hub, "did:plc:alice", "Alice", "#ff0000", "doc-ot-state")
-	room.RegisterClient(alice)
-	time.Sleep(100 * time.Millisecond)
-	drain(alice, 200*time.Millisecond)
-
-	room.ApplyEdits([]Operation{{From: 0, To: -1, Insert: "first"}}, alice)
-	room.ApplyEdits([]Operation{{From: 5, To: 5, Insert: " second"}}, alice)
-
-	// Give room goroutine time to process
-	time.Sleep(100 * time.Millisecond)
-
-	if got := room.ot.GetText(); got != "first second" {
-		t.Errorf("OT state: got %q, want %q", got, "first second")
-	}
-}
-
-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)
-
-	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))
-	}
-}
-
-// --- SeedText / IsNewRoom ---
-
-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")
-	}
-}
-
 // --- GetPresence ---
 
 func TestRoom_GetPresence_Empty(t *testing.T) {

internal/collaboration/ot.go

···
-package collaboration
-
-import "sync"
-
-type OTEngine struct {
-	mu           sync.Mutex
-	documentText string
-	version      int
-}
-
-func NewOTEngine(initialText string) *OTEngine {
-	return &OTEngine{
-		documentText: initialText,
-		version:      0,
-	}
-}
-
-type Operation struct {
-	From   int    `json:"from"`
-	To     int    `json:"to"`
-	Insert string `json:"insert"`
-	// Author is set by the client and used for logging/debugging purposes
-	// to identify which user performed an operation
-	Author string `json:"author"`
-}
-
-func (ot *OTEngine) Apply(op Operation) string {
-	ot.mu.Lock()
-	defer ot.mu.Unlock()
-
-	newText, _ := ot.applyInternal(op)
-	return newText
-}
-
-func (ot *OTEngine) ApplyWithVersion(op Operation) (string, int) {
-	ot.mu.Lock()
-	defer ot.mu.Unlock()
-
-	newText, changed := ot.applyInternal(op)
-	if !changed {
-		return newText, ot.version
-	}
-	return newText, ot.version
-}
-
-func (ot *OTEngine) applyInternal(op Operation) (string, bool) {
-	if op.From < 0 {
-		op.From = 0
-	}
-	// -1 means "end of document" — treat as a full replacement when From==0.
-	if op.To < 0 {
-		op.To = len(ot.documentText)
-	}
-	if op.From > len(ot.documentText) {
-		op.From = len(ot.documentText)
-	}
-	if op.To > len(ot.documentText) {
-		op.To = len(ot.documentText)
-	}
-	if op.From > op.To {
-		return ot.documentText, false
-	}
-
-	// True no-op: nothing deleted and nothing inserted.
-	if op.From == op.To && op.Insert == "" {
-		return ot.documentText, false
-	}
-
-	newText := ot.documentText[:op.From] + op.Insert + ot.documentText[op.To:]
-	ot.documentText = newText
-	ot.version++
-
-	return newText, true
-}
-
-// 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
-}
-
-func (ot *OTEngine) GetText() string {
-	ot.mu.Lock()
-	defer ot.mu.Unlock()
-	return ot.documentText
-}
-
-func (ot *OTEngine) GetVersion() int {
-	ot.mu.Lock()
-	defer ot.mu.Unlock()
-	return ot.version
-}

internal/collaboration/ot_test.go

···
-package collaboration
-
-import (
-	"sync"
-	"testing"
-)
-
-func TestOTEngine_NewEngine(t *testing.T) {
-	ot := NewOTEngine("hello world")
-	if ot.GetText() != "hello world" {
-		t.Errorf("expected initial text %q, got %q", "hello world", ot.GetText())
-	}
-	if ot.GetVersion() != 0 {
-		t.Errorf("expected initial version 0, got %d", ot.GetVersion())
-	}
-}
-
-func TestOTEngine_Apply_Insert(t *testing.T) {
-	ot := NewOTEngine("hello world")
-	result := ot.Apply(Operation{From: 5, To: 5, Insert: " beautiful"})
-	want := "hello beautiful world"
-	if result != want {
-		t.Errorf("Apply insert: got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_Replace(t *testing.T) {
-	ot := NewOTEngine("hello world")
-	result := ot.Apply(Operation{From: 6, To: 11, Insert: "Go"})
-	want := "hello Go"
-	if result != want {
-		t.Errorf("Apply replace: got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_Delete(t *testing.T) {
-	ot := NewOTEngine("hello world")
-	// Delete " world" by replacing with empty string.
-	result := ot.Apply(Operation{From: 5, To: 11, Insert: ""})
-	want := "hello"
-	if result != want {
-		t.Errorf("Apply delete (empty insert): got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_DeleteIncrementsVersion(t *testing.T) {
-	ot := NewOTEngine("hello world")
-	ot.Apply(Operation{From: 5, To: 11, Insert: ""})
-	if ot.GetVersion() != 1 {
-		t.Errorf("delete should increment version: got %d, want 1", ot.GetVersion())
-	}
-}
-
-func TestOTEngine_Apply_EmptyInsertAtSamePosition_IsNoOp(t *testing.T) {
-	ot := NewOTEngine("hello")
-	result := ot.Apply(Operation{From: 3, To: 3, Insert: ""})
-	if result != "hello" {
-		t.Errorf("From==To and Insert==\"\" should be no-op: got %q", result)
-	}
-	if ot.GetVersion() != 0 {
-		t.Errorf("no-op should not increment version: got %d", ot.GetVersion())
-	}
-}
-
-func TestOTEngine_Apply_FullReplace(t *testing.T) {
-	ot := NewOTEngine("old text")
-	result := ot.Apply(Operation{From: 0, To: -1, Insert: "brand new content"})
-	want := "brand new content"
-	if result != want {
-		t.Errorf("Apply full replace (To=-1): got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_FromBeyondEnd_Clamps(t *testing.T) {
-	ot := NewOTEngine("hi")
-	// From beyond length should be clamped to len(text)
-	result := ot.Apply(Operation{From: 100, To: 200, Insert: "!"})
-	want := "hi!"
-	if result != want {
-		t.Errorf("Apply clamped From: got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_NegativeFrom_Clamps(t *testing.T) {
-	ot := NewOTEngine("hello")
-	result := ot.Apply(Operation{From: -5, To: 0, Insert: ">> "})
-	want := ">> hello"
-	if result != want {
-		t.Errorf("Apply negative From: got %q, want %q", result, want)
-	}
-}
-
-func TestOTEngine_Apply_FromGreaterThanTo_NoOp(t *testing.T) {
-	ot := NewOTEngine("hello")
-	result := ot.Apply(Operation{From: 3, To: 1, Insert: "X"})
-	// From > To → no-op
-	if result != "hello" {
-		t.Errorf("Apply From>To should be no-op: got %q, want %q", result, "hello")
-	}
-}
-
-func TestOTEngine_VersionIncrements(t *testing.T) {
-	ot := NewOTEngine("abc")
-	if ot.GetVersion() != 0 {
-		t.Fatalf("initial version should be 0")
-	}
-	ot.Apply(Operation{From: 0, To: 0, Insert: "X"})
-	if ot.GetVersion() != 1 {
-		t.Errorf("version after apply: got %d, want 1", ot.GetVersion())
-	}
-	ot.Apply(Operation{From: 0, To: 0, Insert: "Y"})
-	if ot.GetVersion() != 2 {
-		t.Errorf("version after second apply: got %d, want 2", ot.GetVersion())
-	}
-}
-
-func TestOTEngine_NoOpDoesNotIncrementVersion(t *testing.T) {
-	ot := NewOTEngine("abc")
-	ot.Apply(Operation{From: 1, To: 1, Insert: ""}) // no-op
-	if ot.GetVersion() != 0 {
-		t.Errorf("no-op should not increment version: got %d, want 0", ot.GetVersion())
-	}
-}
-
-func TestOTEngine_ApplyWithVersion(t *testing.T) {
-	ot := NewOTEngine("hello")
-	text, ver := ot.ApplyWithVersion(Operation{From: 5, To: 5, Insert: "!"})
-	if text != "hello!" {
-		t.Errorf("ApplyWithVersion text: got %q, want %q", text, "hello!")
-	}
-	if ver != 1 {
-		t.Errorf("ApplyWithVersion version: got %d, want 1", ver)
-	}
-}
-
-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())
-	}
-}
-
-func TestOTEngine_ConcurrentApply_DataRace(t *testing.T) {
-	// Run with -race to catch races. This test just verifies no panic / race.
-	ot := NewOTEngine("start")
-	var wg sync.WaitGroup
-	for i := 0; i < 20; i++ {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			ot.Apply(Operation{From: 0, To: 0, Insert: "x"})
-		}()
-	}
-	wg.Wait()
-	// After 20 inserts of "x" at position 0, we have 20 extra chars
-	text := ot.GetText()
-	if len(text) != len("start")+20 {
-		t.Errorf("concurrent apply: expected length %d, got %d (text=%q)", len("start")+20, len(text), text)
-	}
-}

internal/handler/handler.go

···
 	}
 
 	room := h.CollaborationHub.GetOrCreateRoom(rKey)
-	if room.IsNewRoom() {
-		var initialText string
-		if doc.Content != nil {
-			initialText = doc.Content.Text.RawMarkdown
-		}
-		room.SeedText(initialText)
-	}
 	wsClient := collaboration.NewClient(h.CollaborationHub, conn, did, name, color, rKey)
 	room.RegisterClient(wsClient)
 

node_modules/.package-lock.json

···
         "prosemirror-transform": "^1.0.0"
       }
     },
+    "node_modules/prosemirror-collab": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-collab/-/prosemirror-collab-1.3.1.tgz",
+      "integrity": "sha512-4SnynYR9TTYaQVXd/ieUvsVV4PDMBzrq2xPUWutHivDuOshZXqQ5rGbZM84HEaXKbLdItse7weMGOUdDVcLKEQ==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-state": "^1.0.0"
+      }
+    },
     "node_modules/prosemirror-commands": {
       "version": "1.7.1",
       "resolved": "https://registry.npmjs.org/prosemirror-commands/-/prosemirror-commands-1.7.1.tgz",

templates/document_edit.html

···
         };
 
         ws.onclose = () => {
-            clearTimeout(wsEditTimer);
             stopHeartbeat();
             ws = null;
             updatePresence([]);
···
         // remote steps are applied via CollabClient in Task 8.
     }
 
-    // Debounce timer for WebSocket sends (50ms batches rapid keystrokes).
-    let wsEditTimer = null;
-    let pendingDeltas = [];
-
-    /**
-     * 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');
-
-        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]);
-            }
-        }
-
-        // Line length in old string. Last line has no trailing \n.
-        const oldLineLengths = oldLines.map((l, idx) =>
-            l.length + (idx < oldLines.length - 1 ? 1 : 0));
-
-        const ops = [];
-        let i = 0, j = 0, charOffset = 0;
-
-        while (i < m || j < n) {
-            if (i < m && j < n && oldLines[i] === newLines[j]) {
-                // Matching line — advance past it.
-                charOffset += oldLineLengths[i];
-                i++; j++;
-            } else {
-                // Non-matching run: collect all consecutive deletions and
-                // insertions into a single replace op so positions stay consistent.
-                const hunkFrom = charOffset;
-                let hunkTo = charOffset;
-                let hunkInsert = '';
-
-                while (i < m && (j >= n || dp[i][j] === dp[i+1][j])) {
-                    hunkTo += oldLineLengths[i];
-                    charOffset += oldLineLengths[i];
-                    i++;
-                }
-                while (j < n && (i >= m || dp[i][j] === dp[i][j+1])) {
-                    hunkInsert += newLines[j] + (j < newLines.length - 1 || hunkTo > hunkFrom ? '\n' : '');
-                    j++;
-                }
-
-                // Only emit if something actually changed.
-                if (hunkTo > hunkFrom || hunkInsert !== '') {
-                    ops.push({ from: hunkFrom, to: hunkTo, insert: hunkInsert });
-                }
-            }
-        }
-
-        if (ops.length > 20) return [{ from: 0, to: -1, insert: newStr }];
-        return ops;
-    }
-
-    // Queue a set of deltas and flush after a short debounce.
-    function queueDeltas(deltas) {
-        if (!ws || ws.readyState !== WebSocket.OPEN) 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 = [];
-    }
-
     function closeWS() {
         if (!ws) return;
-        clearTimeout(wsEditTimer);
-        flushDeltas();   // send any buffered deltas before closing
         ws.close();
         ws = null;
         stopHeartbeat();
-    }
-
-    // sendEdit sends a full-document replacement via the granular-delta path.
-    // to: -1 is a sentinel meaning "end of document" — the server OT engine
-    // clamps it to len(documentText), and applyRemoteEdit clamps it to docLen.
-    // Milkdown switches to diffToOps in Chunk 4 and no longer calls this directly.
-    function sendEdit(content) {
-        if (!ws || ws.readyState !== WebSocket.OPEN) return;
-        queueDeltas([{ from: 0, to: -1, insert: content }]);
     }
 
     // ── Presence ──────────────────────────────────────────────────────────────
···
     }
 
     window.addEventListener('beforeunload', () => {
-        clearTimeout(wsEditTimer);
-        flushDeltas();
+        closeWS();
     });
 </script>
 {{end}}