Collaborative Rich Text

Real-time collaborative rich text editing with TinyMCE, Yjs CRDTs, and the collab_docs backend.

Overview

collab_richtext provides a Google Docs-style WYSIWYG editing experience on top of the collab_docs persistence and permission system. The server is intentionally thin (two page routes), delegating all document lifecycle, Yjs sync, and permissions to collab_docs_server. The client pairs TinyMCE with a custom TinyMCEBinding class that bridges the editor's HTML content model to Yjs text CRDTs for real-time multi-user collaboration.

Architecture

collab_richtext.doh.yaml
├── collab_docs              (nodejs — shared backend: Yjs lifecycle, permissions, DB)
├── collab_richtext_server   (nodejs — page routes only)
└── collab_richtext_client   (browser)
    ├── TinyMCEBinding       (Yjs ↔ TinyMCE HTML sync)
    ├── CollabRichtextEditor  (editor container + provider lifecycle)
    ├── CollabRichtextToolbar (title, export, print, delete, user avatars)
    ├── CollabRichtextStatusBar (sync indicator, client count)
    └── CollabRichtextList    (document list + create)

Depends on: collab_docs (server), collab_shared (browser), tinymce (browser) Loaded by: chat.doh.yaml

File Structure

Page Routes

Both routes serve HTML pages that bootstrap browser modules. All document CRUD, permissions, and Yjs sync are handled by collab_docs_server.

TinyMCEBinding

Bridges TinyMCE's HTML content model to a Yjs Y.Text instance using character-level diff.

Constructor

new TinyMCEBinding(ytext, editor, awareness)

Properties

Sync Algorithm

Local → Remote (_applyLocalChange):

1. Get current HTML from editor via getContent({ format: 'raw' })
2. Compute longest common prefix and suffix with _lastHtml
3. Calculate delete range and insert text from the diff
4. Apply as Yjs transaction: ytext.delete() + ytext.insert()

Remote → Local (_applyRemoteChange):

1. Read ytext.toString() for new content
2. Save cursor position via TinyMCE bookmark
3. Set editor content with setContent(newContent, { format: 'raw' })
4. Restore cursor via moveToBookmark()

TinyMCE Events Listened

Methods

destroy() — Unobserves Yjs text, removes all TinyMCE event listeners.

Socket Events

All socket events are handled by collab_docs_server. The richtext client uses the same protocol as collab_docs_client.

Emitted by Client

Listened by Client

Client Patterns

CollabRichtextEditor

Main editor container managing the Yjs provider lifecycle.

Key Properties:

Sub-objects:

Lifecycle:

1. object_phase — Create Y.Doc and CollabSocketProvider, wire socket listeners
2. post_builder_phase — Connect toolbar to editor instance
3. html_phase — Emit collab:doc:open, initialize TinyMCE on response, create binding

TinyMCE Configuration:

• Plugins: lists, link, table, code, wordcount, searchreplace, autolink, image, charmap, emoticons
• Toolbar: undo/redo, blocks, fonts, text formatting, colors, alignment, lists, media, search
• Custom File menu items: Rename, Download as HTML, Print, Delete document
• Google Docs-inspired content styling

Key Methods:

CollabRichtextToolbar

Title editing, document actions, and collaborator avatars.

Sub-objects: back_btn, title_display, spacer, users_container, fullscreen_btn

Key Methods:

CollabRichtextStatusBar

Sync state indicator, collaborator count, read-only badge.

Sub-objects: sync_status, client_count, readonly_indicator

Methods:

CollabRichtextList

Document browser with create functionality.

Key Properties:

Sub-objects: header (with title_area and create_btn), list_container

Key Methods:

Bootstrap Modules

Module Exports

return { TinyMCEBinding };

Integration Notes

• All document persistence, permissions, and Yjs sync are delegated to collab_docs_server
• Documents created with type: 'richtext' use this editor; type: 'plaintext' uses the Monaco editor from collab_docs
• The document list shows both richtext and plaintext documents, routing to the appropriate editor
• CollabSocketProvider from collab_shared handles the Yjs ↔ Socket.IO bridge

Testing

1. Open /richtext — verify document list loads
2. Create a new document — verify it appears in the list
3. Open document — verify TinyMCE loads with toolbar
4. Type formatted text — verify it persists on refresh
5. Open in two browsers — verify real-time sync
6. Test toolbar actions: rename, download HTML, print, delete
7. Verify collaborator avatars appear when multiple users edit
8. Check status bar: sync dot (gold → green), client count, read-only badge