feat: add upgradeToCollaboration api to promose local documents into collab mode (#2508)

* feat: add upgradeToCollaboration() to promote local documents into collaborative rooms

* chore: update docs for collab upgrade

Author: harbournick

apps/docs/core/superdoc/methods.mdx

@@ -130,6 +130,77 @@ const superdoc = new SuperDoc({
 
 </CodeGroup>
 
+## Collaboration methods
+
+### `upgradeToCollaboration`
+
+Promote a local SuperDoc instance into collaboration without creating a new instance.
+
+<Warning>
+  This is a promotion flow, not a passive join flow. SuperDoc seeds the target
+  room with the current local document state, comments, and lock state.
+</Warning>
+
+<ParamField path="options" type="Object" required>
+  Upgrade configuration
+
+  <Expandable title="properties" defaultOpen>
+    <ParamField path="ydoc" type="Y.Doc" required>
+      The Yjs document for the target room
+    </ParamField>
+    <ParamField path="provider" type="Object" required>
+      The collaboration provider connected to the same room as `ydoc`
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Requirements:**
+
+- The SuperDoc instance must already be ready
+- The instance must not already be collaborative
+- The current instance must contain a single DOCX document
+- You must provide a matching `{ ydoc, provider }` pair
+
+<Note>
+  SuperDoc waits for provider sync internally. You do not need to wait for the
+  provider's `sync` event before calling this method.
+</Note>
+
+<CodeGroup>
+
+```javascript Usage
+await superdoc.upgradeToCollaboration({ ydoc, provider });
+```
+
+```javascript Full Example
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: file,
+  user: {
+    name: 'John Smith',
+    email: 'john@example.com',
+  },
+});
+
+superdoc.on('ready', async () => {
+  const ydoc = new Y.Doc();
+  const provider = new WebsocketProvider('wss://collab.example.com', 'document-123', ydoc);
+
+  await superdoc.upgradeToCollaboration({ ydoc, provider });
+});
+```
+
+</CodeGroup>
+
+See [Upgrade to Collaboration](/modules/collaboration/upgrade-to-collaboration) for the full workflow guide.
+
 ## Mode control
 
 ### `setDocumentMode`

apps/docs/docs.json

@@ -135,6 +135,7 @@
                 "pages": [
                   "modules/collaboration/overview",
                   "modules/collaboration/quickstart",
+                  "modules/collaboration/upgrade-to-collaboration",
                   "modules/collaboration/configuration"
                 ]
               },

apps/docs/modules/collaboration/configuration.mdx

@@ -27,6 +27,14 @@ new SuperDoc({
 });
 ```
 
+<Note>
+  Use `modules.collaboration = { ydoc, provider }` when the editor should start
+  in collaboration mode. If you want to open the document locally first and
+  create a shared room later, use
+  [`superdoc.upgradeToCollaboration()`](/modules/collaboration/upgrade-to-collaboration)
+  instead.
+</Note>
+
 <ParamField path="modules.collaboration.ydoc" type="Y.Doc" required>
   Your Yjs document instance
 </ParamField>

apps/docs/modules/collaboration/overview.mdx

@@ -70,4 +70,19 @@ provider.on("sync", (synced) => {
 
 See the [full quickstart guide](/modules/collaboration/quickstart) for framework-specific examples (React, Vue, Vanilla JS).
 
+## Start collaborative immediately or later
+
+<CardGroup cols={2}>
+  <Card title="Start in collaboration mode" href="/modules/collaboration/quickstart">
+    Create your Yjs provider first, then pass `{ ydoc, provider }` in
+    `modules.collaboration` when you construct `SuperDoc`.
+  </Card>
+
+  <Card title="Upgrade later" href="/modules/collaboration/upgrade-to-collaboration">
+    Mount a local `SuperDoc` first, then call
+    `superdoc.upgradeToCollaboration({ ydoc, provider })` when the user creates
+    a shared room.
+  </Card>
+</CardGroup>
+
 If you are also using the SDK for backend automation, see [SDK collaboration sessions](/document-engine/sdks#collaboration-sessions).

apps/docs/modules/collaboration/quickstart.mdx

@@ -10,6 +10,11 @@ Get real-time collaboration working in 5 minutes using [Liveblocks](https://live
 This guide uses Liveblocks because it's the fastest way to get started. See [all providers](/modules/collaboration/overview#choose-your-approach) for alternatives.
 </Note>
 
+<Note>
+  Need to start local and create the room later? See
+  [Upgrade to Collaboration](/modules/collaboration/upgrade-to-collaboration).
+</Note>
+
 ## Prerequisites
 
 - SuperDoc installed in your project

apps/docs/modules/collaboration/upgrade-to-collaboration.mdx

@@ -0,0 +1,95 @@
+---
+title: Upgrade to Collaboration
+sidebarTitle: Upgrade Later
+keywords: "upgrade to collaboration, runtime collaboration, late collaboration, yjs room promotion, superdoc upgradeToCollaboration"
+---
+
+Use `superdoc.upgradeToCollaboration()` when you want to render a document locally first and turn that same SuperDoc instance into a collaborative room later.
+
+This is useful for flows like:
+
+- A user opens a document privately, then clicks `Share`
+- You only provision collaboration infrastructure when someone requests it
+- You want the document visible immediately, then enable real-time editing on demand
+
+<Warning>
+  `upgradeToCollaboration()` promotes the current local document into the target
+  room. It seeds the room with the current document state, comments, and lock
+  state. Use it to create a new shared room from local state, not to join an
+  existing room you need to preserve as-is.
+</Warning>
+
+## Before you start
+
+- Wait until the SuperDoc instance is ready
+- Call it only on a local instance that is not already collaborative
+- The current implementation supports a single DOCX document
+- Provide a matching `{ ydoc, provider }` pair for the room you want to create
+- You do not need to wait for provider sync yourself; SuperDoc waits internally
+
+## Example
+
+This example starts with a local editor and upgrades it when the user clicks a button.
+
+```javascript
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: file,
+  user: {
+    name: 'John Smith',
+    email: 'john@example.com',
+  },
+});
+
+superdoc.on('ready', () => {
+  document.querySelector('#share-button').addEventListener('click', async () => {
+    const roomId = `document-${crypto.randomUUID()}`;
+    const ydoc = new Y.Doc();
+    const provider = new WebsocketProvider('wss://collab.example.com', roomId, ydoc);
+
+    try {
+      await superdoc.upgradeToCollaboration({ ydoc, provider });
+      console.log('Collaboration enabled:', roomId);
+    } catch (error) {
+      provider.destroy();
+      ydoc.destroy();
+      throw error;
+    }
+  });
+});
+```
+
+## What happens during the upgrade
+
+1. SuperDoc waits for the collaboration provider to connect and sync
+2. The current local document state is written into the target room
+3. Comments and lock state are copied into the room
+4. The editor runtime is rebuilt in collaboration mode
+5. The same `superdoc` instance continues running, now backed by Yjs
+
+## Constructor-time collaboration vs late upgrade
+
+<CardGroup cols={2}>
+  <Card title="Start collaborative immediately" href="/modules/collaboration/quickstart">
+    Create the provider first, then pass `{ ydoc, provider }` in
+    `modules.collaboration` when you construct `SuperDoc`.
+  </Card>
+  <Card title="Start local, upgrade later" href="/core/superdoc/methods">
+    Create a local `SuperDoc` first, then call
+    `superdoc.upgradeToCollaboration({ ydoc, provider })` when you want to
+    create a shared room.
+  </Card>
+</CardGroup>
+
+## Related docs
+
+- [Collaboration quickstart](/modules/collaboration/quickstart)
+- [Collaboration configuration](/modules/collaboration/configuration)
+- [SuperDoc methods](/core/superdoc/methods)
+- [Liveblocks guide](/guides/collaboration/liveblocks)
+- [SuperDoc Yjs guide](/guides/collaboration/superdoc-yjs)

packages/super-editor/src/components/SuperEditor.vue

@@ -922,6 +922,51 @@ const initEditor = async ({ content, media = {}, mediaFiles = {}, fonts = {} } =
     presentationEditor: editor.value instanceof PresentationEditor ? editor.value : null,
   });
 
+  // Upgrade visual-readiness signal: during upgradeToCollaboration, SuperDoc
+  // threads this callback so it knows when the rebuilt runtime has actually
+  // painted AND collaboration is ready, not just when editors are created.
+  // For collaborative remounts the provider is already synced so the
+  // collaboration extension will emit collaborationReady after a 250ms delay.
+  // We must wait for BOTH that event AND the first layout paint before
+  // signalling that the upgrade transition can reveal the new runtime.
+  const onUpgradeVisualReady = props.options?.onUpgradeVisualReady;
+  if (typeof onUpgradeVisualReady === 'function') {
+    const hasCollabProvider = Boolean(props.options?.collaborationProvider);
+    const isPresentationEditor = editor.value instanceof PresentationEditor;
+
+    let collabReady = !hasCollabProvider; // no provider → already satisfied
+    let layoutReady = !isPresentationEditor; // no layout engine → already satisfied
+
+    const tryFire = () => {
+      if (collabReady && layoutReady) {
+        nextTick(() => onUpgradeVisualReady());
+      }
+    };
+
+    if (!collabReady) {
+      editor.value.once('collaborationReady', () => {
+        collabReady = true;
+        tryFire();
+      });
+    }
+
+    if (!layoutReady) {
+      const pe = editor.value;
+      if (pe.getPages().length > 0) {
+        layoutReady = true;
+      } else {
+        const onFirstLayout = () => {
+          pe.off('layoutUpdated', onFirstLayout);
+          layoutReady = true;
+          tryFire();
+        };
+        pe.on('layoutUpdated', onFirstLayout);
+      }
+    }
+
+    tryFire();
+  }
+
   // Attach layout-engine specific image selection listeners
   if (editor.value instanceof PresentationEditor) {
     const presentationEditor = editor.value;

packages/super-editor/src/extensions/collaboration/index.js

@@ -1 +1,2 @@
 export * from './collaboration.js';
+export { seedEditorStateToYDoc } from './seed-editor-to-ydoc.js';