fix(collaboration): memory leaks, Vue stack overflow, and Liveblocks stability (SD-1924)

[tupizz]

Closes IT-474

CleanShot.2026-02-15.at.19.56.51.mp4

Summary

Fixes multiple collaboration bugs causing typing lag, room corruption, Vue stack overflow crashes, and user color flickering when using external providers (Liveblocks).

How SuperDoc Collaboration Works

SuperDoc collaboration uses Y.js (a CRDT library) to synchronize document state between multiple users. Here's the step-by-step flow:

1. Initialization

When a user opens a collaborative document, SuperDoc receives a Y.js Doc and a provider (e.g. Liveblocks, Hocuspocus) through the modules.collaboration config option:

User app → new SuperDoc({ modules: { collaboration: { ydoc, provider } } })
  → SuperDoc.js stores ydoc/provider on the instance
  → SuperDoc creates a Vue app (exposes itself as $superdoc global property)
  → Editor (ProseMirror) is created with ySyncPlugin bound to the ydoc

2. Real-time Editing Sync

When a user types, changes flow through two parallel sync paths:

Keystroke → ProseMirror transaction
  ├── Path A: Y.js CRDT sync (character-level)
  │   ySyncPlugin intercepts the transaction
  │   → converts PM steps to Y.js operations
  │   → provider broadcasts to other clients
  │   → remote clients receive Y.js update
  │   → ySyncPlugin converts back to PM transaction
  │   → remote editor applies the change
  │
  └── Path B: DOCX XML sync (document-level, debounced 1s)
      ydoc 'afterTransaction' listener fires
      → debounced updateYdocDocxData() runs after 1000ms
      → full DOCX export → stored in ydoc meta map
      → new joiners reconstruct document from this DOCX data

3. Cursor Awareness

Each user's cursor position is shared via the Y.js awareness protocol:

User moves cursor → PresentationEditor.#updateLocalAwarenessCursor()
  → awareness.setLocalStateField('user', { name, email, color, cursor })
  → provider broadcasts awareness state
  → remote clients receive awareness update
  → RemoteCursorManager renders colored cursors on their DomPainter overlay

4. Vue Rendering Bridge

SuperDoc uses dual rendering (hidden ProseMirror + visible DomPainter). Vue manages the toolbar and UI state:

PM transaction → SuperDoc.vue onEditorSelectionChange()
  → updates reactive refs (selectionPosition, activeSelection, toolsMenuPosition)
  → Vue re-renders toolbar with current formatting state

---

What Was Broken and How Each Fix Addresses It

Fix 1: Y.js Observer Memory Leaks (collaboration.js)

Problem: The collaboration extension registered 4 observers/listeners without cleanup:

• metaMap.observe() — media file sync
• headerFooterMap.observe() — header/footer sync
• ydoc.on('afterTransaction') — DOCX XML sync
• debounce timer — pending 1s timeout

When editors were destroyed and recreated (HMR, route changes, document switches), these accumulated. Each leaked afterTransaction handler ran a full DOCX export on every Y.js transaction.

Fix: Added onDestroy() lifecycle hook. Observer references are stored in a module-level WeakMap<Editor, CleanupData> (not in reactive this.options) and properly cleaned up on editor destruction. The debounce utility now supports .cancel().

Fix 2: yUndoPlugin Observer Leak (Editor.ts)

Problem: #prepareDocumentForExport created a throwaway EditorState to transform the document for DOCX export. EditorState.create() calls Plugin.init() for every plugin, and yUndoPlugin.init() registers a persistent Y.UndoManager observer on the shared ydoc. These observers were never cleaned up because the throwaway state was immediately discarded.

Fix: Use new Transform(doc) directly instead of EditorState.create(). All methods used by prepareCommentsForExport (removeMark, insert, addMark, setNodeMarkup, delete, mapping.map) are Transform methods — no Transaction-specific APIs are needed.

Fix 3: Vue traverse Stack Overflow (SuperDoc.js)

Problem: SuperDoc.js stores this.ydoc and this.provider on the instance. The instance is exposed to Vue as a global property ($superdoc). Vue's reactivity system deep-traverses all properties to make them reactive. Y.js objects have deep circular internal references (_item → parent → doc → _store → items → ...) that cause infinite recursion → RangeError: Maximum call stack size exceeded.

Fix: Wrap all Y.js object assignments with markRaw() from Vue. This adds a __v_skip flag that tells Vue to never traverse the object. Applied to all 4 assignment paths (external provider, internal single-doc, internal multi-doc, internal superdoc sync).

Fix 4: User Color Flickering (SuperDoc.js)

Problem: Three competing color systems with no coordination:

1. y-prosemirror's yCursorPlugin mutates user.color = '#ffa500' (orange) when no color is set in awareness state
2. RemoteCursorAwareness uses getFallbackCursorColor(clientId) which assigns from a palette
3. awarenessStatesToArray assigns from a shuffled palette via userColorMap

The external provider path in SuperDoc.js never set user.color before broadcasting awareness, so each system kept overwriting with different colors every render cycle.

Fix: Set this.config.user.color = this.colors[0] || '#4ECDC4' before calling setupAwarenessHandler, ensuring awareness state always has a stable color.

Fix 5: Liveblocks Room Corruption (App.tsx)

Problem: provider.on('sync') fires not only on initial connection but also on every reconnect. The original example code created a new SuperDoc instance on every sync event, resulting in duplicate editors writing to the same Y.js document — causing conflicting CRDT operations that permanently corrupted the Liveblocks room state (WebSocket code 1011).

Fix: Guard with if (superdocRef.current) return to ensure SuperDoc is only created once per component lifecycle.

Fix 6: Typing Lag — Cursor Awareness Overhead (PresentationEditor.ts)

Problem: Every keystroke triggered #updateLocalAwarenessCursor() synchronously, which calls awareness.setLocalStateField(). With Liveblocks, each call takes ~190ms to encode and sync awareness state over WebSocket.

Fix: Debounce cursor awareness updates to 100ms. Rapid keystrokes batch into a single update, keeping typing responsive while maintaining real-time cursor sharing.

Fix 7: Typing Lag — Vue flushJobs Blocking (SuperDoc.vue)

Problem: Each ProseMirror transaction synchronously updated Vue reactive refs (selectionPosition, activeSelection, toolsMenuPosition). Each mutation triggered Vue's flushJobs microtask, which re-evaluated hundreds of components — blocking the main thread for ~300ms per keystroke.

Fix: Defer selection state updates to requestAnimationFrame. RAF fires before the next paint, so the toolbar still reflects correct state by the time the user sees the rendered frame. Pending RAFs are cancelled on new transactions and on component unmount.

Fix 8: Repeated Full-Document Traversals (block-node.js)

Problem: The hasInitialized flag was only set to true when changes were detected. If the initial document had all valid sdBlockId values, the initialization traversal ran on every single transaction — potentially thousands of wasteful full-document walks.

Fix: Set hasInitialized = true unconditionally after the first appendTransaction call. The blockNodeInitialUpdate meta is only set when actual changes were made.

Fix 9: Liveblocks Example App (App.tsx, vite.config.js)

Problem: Multiple issues in the example app:

• states.filter((s) => s.user) filtered ALL users because awarenessStatesToArray returns flat objects (no nested .user)
• Badge rendering used u.user?.color instead of u.color
• Index-based React keys caused unnecessary re-renders
• No loading indicator while connecting
• No Vite alias configuration for local development
• Strict Mode cleanup didn't null refs — remount broke re-initialization

Fix: Extracted useSuperdocCollaboration custom hook, corrected property access to flat objects, stable clientId keys, proper cleanup for Strict Mode, hoisted static styles, added Vite alias config.

Test plan

• All existing tests pass (pnpm test — 810+ tests across packages)
• Pre-commit hooks pass (typecheck, format, lint, commitlint)
• Verified in browser: no Vue stack overflow, stable user colors, no room corruption
• Verified typing performance: 0.2-2ms dispatch latency, no degradation over 60s
• Verified no DOM node count growth (stable ~1350-1380 nodes)
• Code review: all changes verified safe by automated analysis (Transform API compatibility, lifecycle hook validity, markRaw safety, RAF edge cases)

[Copilot]

Pull request overview

This PR addresses multiple collaboration-related stability and performance issues in SuperDoc/Super Editor (Y.js observer leaks, Vue reactivity stack overflow, cursor awareness overhead, and Liveblocks reconnect behavior), plus a few example-app fixes.

Changes:

• Add cleanup paths for Y.js observers/listeners and avoid plugin-init observer leaks during export.
• Reduce UI/perf regressions by marking Y.js objects as non-reactive, deferring selection updates to requestAnimationFrame, and debouncing local awareness cursor updates.
• Fix repeated initialization/traversal behaviors and improve the Liveblocks example app reliability/config.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/superdoc/src/core/SuperDoc.js	Uses markRaw() for Y.js objects; assigns stable local user color for awareness.
packages/superdoc/src/SuperDoc.vue	Defers selection reactive updates via RAF; cancels RAF on unmount.
packages/superdoc/src/SuperDoc.test.js	Makes RAF synchronous in tests and restores mocks after each test.
packages/super-editor/src/extensions/collaboration/collaboration.js	Tracks Y.js observers/handlers and adds onDestroy() cleanup; debounce supports .cancel().
packages/super-editor/src/extensions/block-node/block-node.js	Ensures initialization traversal only happens once regardless of detected changes.
packages/super-editor/src/core/presentation-editor/PresentationEditor.ts	Debounces local awareness cursor updates; updates remote cursor refresh strategy after layout.
packages/super-editor/src/core/Editor.ts	Uses Transform directly for export prep to avoid plugin init/leaks.
examples/collaboration/liveblocks/vite.config.js	Adds local alias + fs allow-list for resolving built superdoc assets.
examples/collaboration/liveblocks/src/App.tsx	Prevents duplicate SuperDoc creation on reconnect; fixes awareness state rendering and adds “Connecting…” UI.

Comments suppressed due to low confidence (1)

packages/superdoc/src/SuperDoc.vue:287

• When returning early (e.g., skipSelectionUpdate or viewing mode), any previously scheduled requestAnimationFrame callback is left pending and can still call processSelectionChange, re-applying selection state after it was intentionally skipped/reset. Cancel selectionUpdateRafId at the start of this handler (before the early-return branches) so stale selection updates can’t run.

const onEditorSelectionChange = ({ editor, transaction }) => {
  if (skipSelectionUpdate.value) {
    // When comment is added selection will be equal to comment text
    // Should skip calculations to keep text selection for comments correct
    skipSelectionUpdate.value = false;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cce2b919a8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[linear]

IT-474 Superdoc Initialization issue with liveblocks (found in 1.11.0)

SD-1924 Fix Liveblocks initialization: typing unresponsive after refresh

[github-actions]

⚠️ AI Risk Review — potential issues found

• blockNodeInitialUpdate meta flag will never be set after first initialization due to hasInitialized guard being set unconditionally
• Potential null-reference if component destroyed during 100ms cursor debounce timeout (low probability but possible)

_{Via L3 deep analysis · critical risk}

[github-actions]

Visual diffs detected

Pixel differences were found in visual tests. This is not blocking — reproduce locally with cd tests/visual && pnpm docs:download && pnpm test to review diffs.

[harbournick]

LGTM

[superdoc-bot]

🎉 This PR is included in superdoc v1.15.0-next.4

The release is available on GitHub release

[harbournick]

🎉 This PR is included in superdoc v1.15.0

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.2.0

The release is available on GitHub release