PSA/ee/docs/plans/2026-02-24-collab-editor-document-integration/PRD.md

PRD — Integrate Collaborative Editor into In-App Documents

• Slug: 2026-02-24-collab-editor-document-integration
• Date: 2026-02-24
• Status: Draft
• Predecessor: 2026-02-20-editor-improvements (Phase 1 — test page, completed)

Summary

Replace the single-user TextEditor (BlockNote) in the documents drawer with the CollaborativeEditor (Tiptap + Y.js + Hocuspocus) so that multiple users can edit the same document simultaneously with live cursors and auto-sync. Falls back gracefully to single-user mode when Hocuspocus is unavailable.

Problem

Phase 1 validated the collaborative editing stack on /msp/collab-test. But in-app documents still use the BlockNote-based TextEditor with manual save — so real users don't get collaborative editing. Two users editing the same document still risk last-write-wins data loss.

Goals

1. Replace the TextEditor in the document drawer (Documents.tsx) with CollaborativeEditor for in-app document editing.
2. Graceful fallback: if Hocuspocus is unreachable, fall back to a single-user Tiptap editor with manual save (the existing DocumentEditor pattern).
3. Keep a manual Save/Snapshot button alongside auto-sync for user confidence.
4. Handle existing documents that were stored in BlockNote JSON format — convert to ProseMirror JSON on first collaborative open.
5. Preserve presence indicators (connected users, cursors) and connection status in the drawer.

Non-goals

• Changing the drawer-based UX to a full-page editor (keep current UX).
• Collaborative editing for BlockNote-based editors (ticket comments, task comments) — those stay as-is.
• Offline-first / offline editing.
• Version history UI.
• Document-level permissions beyond existing tenant isolation.
• Presence indicators in the document list ("2 people editing" badge).

Users and Primary Flows

Persona: MSP team members editing shared documents (runbooks, SOPs, client notes).

Flow 1 — Collaborative edit (Hocuspocus available)

1. User clicks a document in the documents list.
2. Drawer opens with CollaborativeEditor.
3. Editor connects to Hocuspocus room document:<tenantId>:<documentId>.
4. If the document has existing content in document_block_content, the Y.js document is initialized from it (on first connection to a room with no prior Y.js state).
5. User edits. Changes auto-sync via Y.js.
6. If a second user opens the same document, both see each other's cursors.
7. Presence bar shows connected users.
8. Status bar shows "All changes saved" / "Saving..." / "Offline".
9. User can click "Save" to force-snapshot current state to document_block_content.
10. On drawer close, a final snapshot is triggered.

Flow 2 — Fallback (Hocuspocus unavailable)

1. User clicks a document.
2. Drawer opens, CollaborativeEditor attempts Hocuspocus connection.
3. Connection times out (e.g., 3 seconds).
4. Editor falls back to single-user Tiptap mode (no Y.js, no presence).
5. Status bar shows "Offline — manual save mode".
6. User edits and clicks "Save" to persist manually.

Flow 3 — New document creation

1. User clicks "Create New Document" in the documents page.
2. Drawer opens with CollaborativeEditor in a new room.
3. A new document record and document_block_content row are created.
4. User types and auto-syncs. On close, snapshot persists.

UX / UI Notes

Drawer changes

• Replace TextEditor (BlockNote) with CollaborativeEditor (Tiptap) in edit mode.
• Replace RichTextViewer (BlockNote) with a read-only Tiptap view in view mode (or keep RichTextViewer for non-editable contexts).
• Add presence bar at top of editor area (already built into CollaborativeEditor).
• Add connection/save status bar (already built into CollaborativeEditor).
• Keep the "Save" button in the drawer footer (triggers syncCollabSnapshot).
• Keep the document name input at the top.

Content format handling

• Existing documents stored in BlockNote JSON need conversion to ProseMirror JSON.
• Conversion happens lazily on first open: detect format, convert if needed, save in new format.
• Detection heuristic: BlockNote JSON is an array starting with [{ type: "paragraph", props: {...} }]; ProseMirror JSON is { type: "doc", content: [...] }.

Requirements

Functional

F01: Documents.tsx drawer renders CollaborativeEditor instead of TextEditor when editing an in-app document.

F02: CollaborativeEditor connects to Hocuspocus room document:<tenantId>:<documentId> on mount.

F03: On first connection to a room with no Y.js state, existing document_block_content.block_data is loaded and used to initialize the Y.js document (already implemented in CollaborativeEditor).

F04: Content format detection: if block_data is in BlockNote JSON format, convert to ProseMirror JSON before initializing the Y.js document.

F05: Format conversion function: blockNoteJsonToProsemirrorJson() that maps BlockNote block types (paragraph, heading, bulletListItem, numberedListItem, etc.) to ProseMirror equivalents.

F06: Auto-sync via Y.js — changes propagate to all connected clients in real-time.

F07: Manual "Save" button triggers syncCollabSnapshot() to write current Y.js state to document_block_content.block_data.

F08: On drawer close, trigger a final snapshot to persist content.

F09: Graceful fallback: if Hocuspocus connection fails (timeout after ~3s), switch to single-user mode using a standalone Tiptap editor with manual save via updateBlockContent().

F10: Fallback mode shows a status indicator: "Offline — manual save mode".

F11: Presence bar shows connected users with avatars and names (existing CollaborativeEditor feature).

F12: Collaboration cursors show user name and distinct color (existing feature).

F13: New document creation flow creates the document record and document_block_content row, then opens CollaborativeEditor in the new room.

F14: Read-only view mode: when the drawer is in view mode (non-editable), render a read-only Tiptap editor or keep using RichTextViewer.

F15: The DocumentEditor component (single-user Tiptap) is reused as the fallback editor, sharing the same toolbar and styling as CollaborativeEditor.

Non-functional

NF01: Hocuspocus connection timeout for fallback detection: 3 seconds.

NF02: Snapshot on close should be best-effort — don't block drawer close if it fails.

NF03: Tenant isolation enforced via room name validation (already implemented in Hocuspocus server).

Data / API

Content format detection and conversion

Input: block_data from document_block_content (JSONB)
If Array.isArray(block_data) && block_data[0]?.props  → BlockNote format → convert
If block_data?.type === "doc"                          → ProseMirror format → use directly
Otherwise                                              → empty document

Existing actions used

• getBlockContent(documentId) — load existing content
• updateBlockContent(documentId, data) — manual save in fallback mode
• syncCollabSnapshot(documentId) — snapshot Y.js state to DB
• createBlockDocument(data) — create new document + block content

No new tables needed

• Hocuspocus manages its own persistence
• document_block_content.block_data stores the snapshot (format changes from BlockNote JSON to ProseMirror JSON)

Risks

1. Content format mismatch: Existing documents in BlockNote JSON must be correctly converted. A buggy conversion could corrupt document content. Mitigation: write thorough conversion tests, preserve original data in a _legacy_block_data field or log.

2. RichTextViewer compatibility: RichTextViewer (BlockNote-based) is used elsewhere to render document content. After migration, block_data will be in ProseMirror format — RichTextViewer needs to handle both formats or be replaced for document contexts.

3. Hocuspocus availability: In production, Hocuspocus must be reliably available. The fallback exists, but if it triggers frequently it degrades the user experience.

Acceptance Criteria

• Opening a document in the drawer loads the CollaborativeEditor
• Two users opening the same document see each other's cursors
• Changes sync in real-time between users
• Existing documents (BlockNote format) load correctly after conversion
• "Save" button writes content to document_block_content
• Closing the drawer triggers a snapshot
• When Hocuspocus is down, editor falls back to single-user mode with manual save
• New document creation works end-to-end
• Presence bar shows connected users
• Connection/save status is visible