fix: smooth upgrade-to-collaboration remount and harden rollback (#2509)

harbournick · web-flow · commit 5c9f960b911c · 2026-03-20T20:44:10.000-07:00
diff --git a/packages/superdoc/src/core/SuperDoc.js b/packages/superdoc/src/core/SuperDoc.js
@@ -749,6 +749,8 @@ export class SuperDoc extends EventEmitter {
 
       // Capture state for rollback and visual continuity
       const rollbackJson = sourceEditor.getJSON();
+      const rollbackConvertedXml = JSON.parse(JSON.stringify(sourceEditor.converter?.convertedXml ?? {}));
+      const rollbackMediaFiles = { ...(sourceEditor.options?.mediaFiles ?? {}) };
       const hadCommentsList = Boolean(this.commentsList);
 
       // --- Snapshot live DOM before the point of no return ---
@@ -770,7 +772,8 @@ export class SuperDoc extends EventEmitter {
           throw remountError;
         }
 
-        // --- Rollback: keep snapshot visible, rebuild local runtime hidden ---
+        // --- Rollback: stop the failed collaborative runtime, rebuild local ---
+        this.#stopRuntime();
         this.#detachCollaboration();
         this.config.jsonOverride = rollbackJson;
 
@@ -785,6 +788,7 @@ export class SuperDoc extends EventEmitter {
         }
 
         this.config.jsonOverride = null;
+        this.#restoreRollbackDocumentState(rollbackConvertedXml, rollbackMediaFiles);
         this.#revealNewRuntime(snapshot);
 
         if (hadCommentsList) this.addCommentsList();
@@ -851,6 +855,29 @@ export class SuperDoc extends EventEmitter {
     }
   }
 
+  /**
+   * Restore non-PM document state (parts XML, media files) on the rollback
+   * editor. The PM JSON is restored via `jsonOverride`, but converter parts
+   * and media must be patched explicitly since they were lost during
+   * re-import from the original document source.
+   *
+   * @param {Record<string, unknown>} convertedXml
+   * @param {Record<string, unknown>} mediaFiles
+   */
+  #restoreRollbackDocumentState(convertedXml, mediaFiles) {
+    try {
+      const editor = this.#resolveSourceEditor();
+      if (editor.converter && convertedXml) {
+        editor.converter.convertedXml = convertedXml;
+      }
+      if (mediaFiles) {
+        editor.options.mediaFiles = mediaFiles;
+      }
+    } catch {
+      // Best-effort — editor may not be resolvable in edge cases
+    }
+  }
+
   /**
    * Wait for the provider to report synced, with a timeout.
    *
diff --git a/packages/superdoc/src/core/upgrade-collaboration.test.js b/packages/superdoc/src/core/upgrade-collaboration.test.js
@@ -1029,4 +1029,249 @@ describe('upgradeToCollaboration', () => {
     // After upgrade: callback cleared
     expect(instance._upgradeVisualReadyCallback).toBeNull();
   });
+
+  // -----------------------------------------------------------------------
+  // Rollback regression: leaked runtime (Fix 1)
+  // -----------------------------------------------------------------------
+
+  it('stops the failed collaborative runtime before starting rollback (mount throws)', async () => {
+    const harness = createAppHarness();
+    const instance = new SuperDoc({
+      selector: '#host',
+      documents: [{ id: 'doc-1', type: DOCX, data: new Blob() }],
+      modules: { comments: {} },
+      colors: [],
+      onException: vi.fn(),
+    });
+    await flushMicrotasks();
+    instance.readyEditors = 1;
+
+    const collabUnmount = vi.fn();
+    let callCount = 0;
+
+    createVueAppMock.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) {
+        // Collaborative runtime: app created but mount throws
+        return {
+          app: {
+            mount: vi.fn(() => {
+              throw new Error('Collaborative mount failed');
+            }),
+            unmount: collabUnmount,
+            config: { globalProperties: {} },
+          },
+          pinia: {},
+          superdocStore: harness.superdocStore,
+          commentsStore: harness.commentsStore,
+          highContrastModeStore: {},
+        };
+      }
+      // Rollback runtime: succeeds
+      return {
+        app: {
+          mount: vi.fn((wrapper) => {
+            const el = document.createElement('div');
+            el.className = 'superdoc';
+            wrapper.appendChild(el);
+            setTimeout(() => {
+              if (instance._upgradeVisualReadyCallback) {
+                instance._upgradeVisualReadyCallback();
+              }
+            }, 0);
+          }),
+          unmount: vi.fn(),
+          config: { globalProperties: {} },
+        },
+        pinia: {},
+        superdocStore: harness.superdocStore,
+        commentsStore: harness.commentsStore,
+        highContrastModeStore: {},
+      };
+    });
+
+    await expect(
+      instance.upgradeToCollaboration({
+        ydoc: createMockYDoc(),
+        provider: createMockProvider(),
+      }),
+    ).rejects.toThrow('Collaborative mount failed');
+
+    // The collaborative app must be unmounted via #stopRuntime() before rollback
+    expect(collabUnmount).toHaveBeenCalled();
+  });
+
+  it('stops a timed-out collaborative runtime before starting rollback', async () => {
+    vi.useFakeTimers();
+    try {
+      const harness = createAppHarness();
+      const instance = new SuperDoc({
+        selector: '#host',
+        documents: [{ id: 'doc-1', type: DOCX, data: new Blob() }],
+        modules: { comments: {} },
+        colors: [],
+        onException: vi.fn(),
+      });
+      await vi.advanceTimersByTimeAsync(0);
+      instance.readyEditors = 1;
+
+      const collabUnmount = vi.fn();
+      let callCount = 0;
+
+      createVueAppMock.mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          // Collaborative runtime: mounts but never fires visual-ready
+          return {
+            app: {
+              mount: vi.fn((wrapper) => {
+                const el = document.createElement('div');
+                el.className = 'superdoc';
+                wrapper.appendChild(el);
+                // visual-ready callback deliberately NOT called
+              }),
+              unmount: collabUnmount,
+              config: { globalProperties: {} },
+            },
+            pinia: {},
+            superdocStore: harness.superdocStore,
+            commentsStore: harness.commentsStore,
+            highContrastModeStore: {},
+          };
+        }
+        // Rollback runtime: fires visual-ready immediately
+        return {
+          app: {
+            mount: vi.fn((wrapper) => {
+              const el = document.createElement('div');
+              el.className = 'superdoc';
+              wrapper.appendChild(el);
+              // Fire visual-ready synchronously to avoid timer complications
+              if (instance._upgradeVisualReadyCallback) {
+                instance._upgradeVisualReadyCallback();
+              }
+            }),
+            unmount: vi.fn(),
+            config: { globalProperties: {} },
+          },
+          pinia: {},
+          superdocStore: harness.superdocStore,
+          commentsStore: harness.commentsStore,
+          highContrastModeStore: {},
+        };
+      });
+
+      const upgradePromise = instance.upgradeToCollaboration({
+        ydoc: createMockYDoc(),
+        provider: createMockProvider(),
+      });
+
+      // Attach rejection handler BEFORE advancing timers to avoid unhandled rejection
+      const resultPromise = expect(upgradePromise).rejects.toThrow('visually ready within 30 s');
+
+      // Advance past the 30s collaborative timeout
+      await vi.advanceTimersByTimeAsync(30_001);
+
+      await resultPromise;
+
+      // The timed-out collaborative app must be unmounted before rollback
+      expect(collabUnmount).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Rollback regression: incomplete state restoration (Fix 2)
+  // -----------------------------------------------------------------------
+
+  it('restores convertedXml and mediaFiles on the rollback editor', async () => {
+    const harness = createAppHarness();
+
+    // Simulate pre-upgrade edits that modified parts and media
+    harness.mockEditor.converter.convertedXml = {
+      'word/styles.xml': { tag: 'w:styles', children: [{ tag: 'w:style', attrs: { id: 'custom' } }] },
+      'word/numbering.xml': { tag: 'w:numbering', children: [{ tag: 'w:abstractNum' }] },
+    };
+    harness.mockEditor.options.mediaFiles = {
+      'word/media/image1.png': 'base64-data-here',
+    };
+
+    const instance = new SuperDoc({
+      selector: '#host',
+      documents: [{ id: 'doc-1', type: DOCX, data: new Blob() }],
+      modules: { comments: {} },
+      colors: [],
+      onException: vi.fn(),
+    });
+    await flushMicrotasks();
+    instance.readyEditors = 1;
+
+    // The rollback editor starts with empty/reimported state
+    const rollbackEditor = {
+      converter: { convertedXml: {} },
+      options: { mediaFiles: {}, fonts: {} },
+      state: harness.mockEditor.state,
+      getJSON: harness.mockEditor.getJSON,
+    };
+
+    let callCount = 0;
+    createVueAppMock.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) {
+        // Collaborative: fails during createSuperdocVueApp
+        throw new Error('Simulated collab failure');
+      }
+      // Rollback: succeeds, returns a store with the rollback editor
+      return {
+        app: {
+          mount: vi.fn((wrapper) => {
+            const el = document.createElement('div');
+            el.className = 'superdoc';
+            wrapper.appendChild(el);
+            setTimeout(() => {
+              if (instance._upgradeVisualReadyCallback) {
+                instance._upgradeVisualReadyCallback();
+              }
+            }, 0);
+          }),
+          unmount: vi.fn(),
+          config: { globalProperties: {} },
+        },
+        pinia: {},
+        superdocStore: {
+          documents: [
+            {
+              id: 'doc-1',
+              type: DOCX,
+              getEditor: () => rollbackEditor,
+              setEditor: vi.fn(),
+            },
+          ],
+          init: vi.fn(),
+          reset: vi.fn(),
+          setExceptionHandler: vi.fn(),
+          activeZoom: 100,
+        },
+        commentsStore: harness.commentsStore,
+        highContrastModeStore: {},
+      };
+    });
+
+    await expect(
+      instance.upgradeToCollaboration({
+        ydoc: createMockYDoc(),
+        provider: createMockProvider(),
+      }),
+    ).rejects.toThrow('Simulated collab failure');
+
+    // The rollback editor should have the pre-upgrade parts and media restored
+    expect(rollbackEditor.converter.convertedXml).toEqual({
+      'word/styles.xml': { tag: 'w:styles', children: [{ tag: 'w:style', attrs: { id: 'custom' } }] },
+      'word/numbering.xml': { tag: 'w:numbering', children: [{ tag: 'w:abstractNum' }] },
+    });
+    expect(rollbackEditor.options.mediaFiles).toEqual({
+      'word/media/image1.png': 'base64-data-here',
+    });
+  });
 });
