superdoc 2.18.0-next.10 → 2.18.0-next.12

package/dist/superdoc.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./chunks/rolldown-runtime-74VwNCz7.cjs");
 const require_blank_docx = require("./chunks/blank-docx-BuFAbRjs.cjs");
-const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-D9JWPXRh.cjs");
+const require_create_super_doc_ui = require("./chunks/create-super-doc-ui-BwM3I7-G.cjs");
 const require_eventemitter3 = require("./chunks/eventemitter3-C_TAnXOl.cjs");
 const require_uuid = require("./chunks/uuid-BhG0ngwk.cjs");
 const require_jszip = require("./chunks/jszip-D8mAFF-r.cjs");
@@ -316,7 +316,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.18.0-next.10";
+		return "2.18.0-next.12";
 	} catch {
 		return "unknown";
 	}
@@ -22372,7 +22372,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			if (!payload) return;
 			clearV2EditorFailure(payload.documentId ?? null);
 			clearV2MutationRejectionNotifications(payload.documentId ?? null);
-			const { host, mount, documentId, capabilities, editCommands, bindEditShortcuts, bindSessionShortcuts, commentsAdapter, trackedChangesAdapter, contextMenu, documentApi, documentMutationReadiness, documentApiUnavailableReason, pageMetrics, pageLayout, pageFurniture, presence, lock, collaborationProvider, fonts, replaceFile, upgradeToCollaboration, documentOpenToken } = payload;
+			const { host, mount, documentId, capabilities, editCommands, bindEditShortcuts, bindSessionShortcuts, commentsAdapter, trackedChangesAdapter, contextMenu, documentApi, documentMutationReadiness, documentApiUnavailableReason, pageMetrics, pageLayout, pageFurniture, presence, lock, connection, collaborationProvider, fonts, replaceFile, upgradeToCollaboration, documentOpenToken } = payload;
 			documentOpenTelemetry?.trackDocumentOpen(documentOpenToken ?? null, documentId ?? null);
 			const saveV2Bytes = createV2SaveQueue(async (saveOptions = {}) => {
 				if (!host || typeof host.save !== "function") throw new Error("v2-editor: save unavailable");
@@ -22649,6 +22649,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				pageFurniture: pageFurniture ?? null,
 				presence: presence ?? null,
 				lock: lock ?? null,
+				connection: connection ?? null,
 				provider: collaborationProvider ?? null,
 				reviewWindow: {
 					getDiagnostics: () => v2ReviewWindowController.getDiagnostics(),
@@ -24494,7 +24495,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-4efb0cab"]]);
+}, [["__scopeId", "data-v-9da02d58"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -45370,6 +45371,14 @@ function contentControlSelectionKey(selection) {
 		return null;
 	}
 }
+function deriveCollaborationConnectionKind(snapshot, hasSyncedBefore) {
+	switch (snapshot.state) {
+		case "failed": return "failed";
+		case "degraded": return snapshot.detail === "reconnecting" ? "reconnecting" : "lost";
+		case "synced": return hasSyncedBefore ? "recovered" : "initial";
+		default: return hasSyncedBefore ? "reconnecting" : "initial";
+	}
+}
 function isV2ActiveEditorFacade(editor) {
 	return Boolean(editor && typeof editor === "object" && editor.editorVersion === 2);
 }
@@ -45426,6 +45435,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 	#destroyed;
 	#diagnostics;
 	#isUpgrading;
+	#pendingUpgrade;
 	/** Aborts an in-flight upgrade (sync wait or ready wait). */
 	#abortUpgrade;
 	/**
@@ -45437,6 +45447,12 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 	#v2AwarenessUnsub;
 	/** Unsubscribe handle for the v2 root-doc lock observer. */
 	#v2LockUnsub;
+	/** Unsubscribe handle for the v2 collaboration connection observer. */
+	#v2ConnectionUnsub;
+	/** Latest `collaboration-connection-change` payload, for late readers. */
+	#v2ConnectionState;
+	/** Whether the current collaboration room has completed a sync at least once. */
+	#v2ConnectionHasSynced;
 	/** Lock state captured before a local → v2 collaboration promotion remount. */
 	#pendingV2LockSeed;
 	#mountWrapper;
@@ -45525,9 +45541,13 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		super();
 		this.#destroyed = false;
 		this.#isUpgrading = false;
+		this.#pendingUpgrade = null;
 		this.#abortUpgrade = null;
 		this.#v2AwarenessUnsub = null;
 		this.#v2LockUnsub = null;
+		this.#v2ConnectionUnsub = null;
+		this.#v2ConnectionState = null;
+		this.#v2ConnectionHasSynced = false;
 		this.#pendingV2LockSeed = null;
 		this.#mountWrapper = null;
 		this.#contentControlClickRoot = null;
@@ -45726,7 +45746,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.18.0-next.10";
+		this.version = "2.18.0-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -45828,7 +45848,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		return this.#diagnostics;
 	}
 	emit(event, ...args) {
-		if (event === "exception" || event === "document-replaced" || event === "ready" || event === "active-editor-change" || event === "collaboration-ready" || event === "locked") require_create_super_doc_ui.recordInteraction(this, event, () => args[0]);
+		if (event === "exception" || event === "document-replaced" || event === "ready" || event === "active-editor-change" || event === "collaboration-ready" || event === "collaboration-connection-change" || event === "locked") require_create_super_doc_ui.recordInteraction(this, event, () => args[0]);
 		return super.emit(event, ...args);
 	}
 	on(event, fn, context) {
@@ -46070,6 +46090,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.#onConfig("pdf:document-ready", this.config.onPdfDocumentReady);
 		this.#onConfig("sidebar-toggle", this.config.onSidebarToggle);
 		this.#onConfig("collaboration-ready", this.config.onCollaborationReady);
+		this.#onConfig("collaboration-connection-change", this.config.onCollaborationConnectionChange);
 		this.on("collaboration-ready", (payload) => this.#startV2CollaborationEventBridge(payload?.editor ?? null));
 		this.#onConfig("editor-update", this.config.onEditorUpdate);
 		this.#onConfig("tracked-changes:bulk-decision", this.config.onTrackedChangesBulkDecision);
@@ -46160,12 +46181,59 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			} catch {}
 			this.#v2LockUnsub = null;
 		}
+		if (this.#v2ConnectionUnsub) {
+			try {
+				this.#v2ConnectionUnsub();
+			} catch {}
+			this.#v2ConnectionUnsub = null;
+		}
 	}
 	#startV2CollaborationEventBridge(editor) {
 		this.#stopV2CollaborationEventBridge();
 		if (!isV2ActiveEditorFacade(editor)) return;
 		this.#startV2AwarenessBridge(editor);
 		this.#startV2LockBridge(editor);
+		this.#startV2ConnectionBridge(editor);
+	}
+	#startV2ConnectionBridge(editor) {
+		const connection = editor.connection;
+		if (!connection || typeof connection.subscribe !== "function") return;
+		const { documentId } = connection;
+		if (this.#v2ConnectionState?.documentId !== documentId) {
+			this.#v2ConnectionState = null;
+			this.#v2ConnectionHasSynced = false;
+		}
+		const publish = (snapshot) => {
+			if (this.#destroyed) return;
+			const previous = this.#v2ConnectionState;
+			if (previous && previous.state === snapshot.state && previous.detail === (snapshot.detail ?? null)) return;
+			const payload = {
+				documentId,
+				state: snapshot.state,
+				previousState: previous?.state ?? null,
+				kind: deriveCollaborationConnectionKind(snapshot, this.#v2ConnectionHasSynced),
+				detail: snapshot.detail ?? null,
+				superdoc: this
+			};
+			this.#v2ConnectionState = payload;
+			if (snapshot.state === "synced") this.#v2ConnectionHasSynced = true;
+			this.emit("collaboration-connection-change", payload);
+		};
+		try {
+			const initialSnapshot = connection.getSnapshot?.();
+			if (initialSnapshot) publish(initialSnapshot);
+			this.#v2ConnectionUnsub = connection.subscribe(publish);
+		} catch (err) {
+			console.warn("[SuperDoc] v2 connection bridge failed to subscribe", err);
+		}
+	}
+	/**
+	* Latest v2 collaboration connection change, or `null` when no v2
+	* collaboration session has reported one. Same payload as the
+	* `collaboration-connection-change` event.
+	*/
+	getCollaborationConnectionState() {
+		return this.#v2ConnectionState;
 	}
 	#startV2AwarenessBridge(editor) {
 		const presence = editor.presence;
@@ -46253,29 +46321,78 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 	* - A supported v2 single-doc `v2Collaboration` target
 	* - Create-and-upgrade only (no merge semantics)
 	*
-	* @returns Resolves once the collaborative runtime is ready
+	* @returns The attached room and document once the collaborative runtime is ready
 	*/
 	async upgradeToCollaboration(options) {
+		if (this.#pendingUpgrade) {
+			const { target } = this.#resolveCollaborationUpgradeTarget(options);
+			if (this.#sameUpgradeTarget(target, this.#pendingUpgrade.target)) return this.#pendingUpgrade.promise;
+			throw Object.assign(/* @__PURE__ */ new Error("SuperDoc: a different collaboration target is already upgrading"), { code: "collaboration-upgrade-target-conflict" });
+		}
 		const { target } = this.#validateUpgradePrerequisites(options);
 		this.#isUpgrading = true;
-		try {
-			const localSource = await this.#captureCurrentDocxSourceForUpgrade();
-			const rollback = this.#snapshotV2UpgradeState();
-			const lockSeed = this.#snapshotV2LockSeed();
-			this.#assertNotDestroyed();
+		const operation = (async () => {
 			try {
-				this.#pendingV2LockSeed = lockSeed;
-				const promotion = await this.#promoteSingleDocumentToV2Collaboration(target, localSource);
-				this.#finalizeSingleDocumentV2Collaboration(promotion, target);
-				this.#pendingV2LockSeed = null;
-			} catch (err) {
-				this.#rollbackV2UpgradeState(rollback);
-				throw err;
-			}
-		} finally {
-			this.#abortUpgrade = null;
-			this.#isUpgrading = false;
-		}
+				const localSource = await this.#captureCurrentDocxSourceForUpgrade();
+				const rollback = this.#snapshotV2UpgradeState();
+				const lockSeed = this.#snapshotV2LockSeed();
+				this.#assertNotDestroyed();
+				try {
+					this.#pendingV2LockSeed = lockSeed;
+					const promotion = await this.#promoteSingleDocumentToV2Collaboration(target, localSource);
+					this.#finalizeSingleDocumentV2Collaboration(promotion, target);
+					this.#pendingV2LockSeed = null;
+					const attachedDocumentId = this.activeEditor?.options?.documentId;
+					const attachedRoomId = promotion.configDoc.v2Collaboration?.documentId;
+					if (typeof attachedDocumentId !== "string" || attachedDocumentId !== promotion.configDoc.id || typeof attachedRoomId !== "string" || attachedRoomId !== target.documentId) throw new Error("SuperDoc: collaboration upgrade did not attach the expected room and document");
+					return {
+						roomId: attachedRoomId,
+						documentId: attachedDocumentId
+					};
+				} catch (err) {
+					this.#rollbackV2UpgradeState(rollback);
+					throw err;
+				}
+			} finally {
+				this.#abortUpgrade = null;
+				this.#isUpgrading = false;
+				this.#pendingUpgrade = null;
+			}
+		})();
+		this.#pendingUpgrade = {
+			target,
+			promise: operation
+		};
+		return operation;
+	}
+	#sameUpgradeTarget(left, right) {
+		if (left.token !== right.token) return false;
+		const seen = /* @__PURE__ */ new WeakMap();
+		const sameValue = (first, second) => {
+			if (Object.is(first, second)) return true;
+			if (!first || !second || typeof first !== "object" || typeof second !== "object") return false;
+			if (Object.getPrototypeOf(first) !== Object.getPrototypeOf(second)) return false;
+			if (seen.has(first)) return seen.get(first) === second;
+			seen.set(first, second);
+			if (first instanceof Date && second instanceof Date) return first.getTime() === second.getTime();
+			if (first instanceof RegExp && second instanceof RegExp) return first.source === second.source && first.flags === second.flags;
+			if (first instanceof ArrayBuffer && second instanceof ArrayBuffer) return sameValue(Array.from(new Uint8Array(first)), Array.from(new Uint8Array(second)));
+			if (ArrayBuffer.isView(first) && ArrayBuffer.isView(second)) return first.constructor === second.constructor && sameValue(Array.from(new Uint8Array(first.buffer, first.byteOffset, first.byteLength)), Array.from(new Uint8Array(second.buffer, second.byteOffset, second.byteLength)));
+			if (first instanceof Map && second instanceof Map) return first.size === second.size && sameValue(Array.from(first.entries()), Array.from(second.entries()));
+			if (first instanceof Set && second instanceof Set) return first.size === second.size && sameValue(Array.from(first.values()), Array.from(second.values()));
+			if (Array.isArray(first) && Array.isArray(second)) return first.length === second.length && first.every((value, index) => sameValue(value, second[index]));
+			if (Object.getPrototypeOf(first) !== Object.prototype && Object.getPrototypeOf(first) !== null) return false;
+			const keys = Object.keys(first).sort();
+			const otherKeys = Object.keys(second).sort();
+			return keys.length === otherKeys.length && keys.every((key, index) => key === otherKeys[index] && sameValue(first[key], second[key]));
+		};
+		return sameValue({
+			...left,
+			token: void 0
+		}, {
+			...right,
+			token: void 0
+		});
 	}
 	#snapshotV2LockSeed() {
 		return {
@@ -46602,9 +46719,13 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		if (docxDocs.length > 1) throw new Error("SuperDoc: upgradeToCollaboration() only supports a single DOCX document");
 		if (cfg.documents.length !== docxDocs.length) throw new Error("SuperDoc: upgradeToCollaboration() only supports single-DOCX instances");
 		if (!isV2ActiveEditorFacade(this.#resolveSourceEditor())) throw new Error("SuperDoc: upgradeToCollaboration() requires a ready v2 DOCX editor");
-		const configDoc = docxDocs[0];
-		const mountedDocumentId = configDoc.id;
+		const mountedDocumentId = docxDocs[0].id;
 		if (typeof mountedDocumentId !== "string" || mountedDocumentId.length === 0) throw new Error("SuperDoc: source document is missing its mounted document identity");
+		return this.#resolveCollaborationUpgradeTarget(options);
+	}
+	#resolveCollaborationUpgradeTarget(options) {
+		const cfg = this.config;
+		const configDoc = cfg.documents.find((doc) => doc.type === DOCX);
 		const collaborationModule = cfg.modules?.collaboration;
 		const legacyCollaboration = options.ydoc || options.provider ? {
 			ydoc: options.ydoc,
@@ -46620,7 +46741,10 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			...typeof window !== "undefined" ? { authEndpointBaseUrl: window.location.href } : {}
 		});
 		if (!resolution.ok) throw new Error(`SuperDoc: upgradeToCollaboration() ${resolution.reason}: ${resolution.message}`);
-		return { target: resolution.target };
+		return { target: {
+			...resolution.target,
+			roomMode: "create"
+		} };
 	}
 	#unwrapMaybeRef(value) {
 		if (value && typeof value === "object" && "value" in value) return value.value;

package/dist/superdoc.es.js

@@ -1,6 +1,6 @@
 import { i as __toESM$2 } from "./chunks/rolldown-runtime-0pSA04fp.es.js";
 import { t as blank_default } from "./chunks/blank-docx-DzQccOlW.es.js";
-import { a as getV2TrackedChangeMutationImpact, c as createInteractionHistory, i as applyV2CommentInvalidationFromMutation, l as recordInteraction, o as DOM_CLASS_NAMES, s as closeInteractionHistory, t as createSuperDocUI } from "./chunks/create-super-doc-ui-qTSa0PbD.es.js";
+import { a as getV2TrackedChangeMutationImpact, c as createInteractionHistory, i as applyV2CommentInvalidationFromMutation, l as recordInteraction, o as DOM_CLASS_NAMES, s as closeInteractionHistory, t as createSuperDocUI } from "./chunks/create-super-doc-ui-Ci7OxbXV.es.js";
 import { t as import_eventemitter3 } from "./chunks/eventemitter3-DEIiXiH2.es.js";
 import { t as v4 } from "./chunks/uuid-H0Xcmmhy.es.js";
 import { a as init_dist$1, i as global, n as init_dist$2, o as Buffer, r as process$1, s as init_dist, t as require_jszip_min } from "./chunks/jszip-BzJ3CyxR.es.js";
@@ -315,7 +315,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.18.0-next.10";
+		return "2.18.0-next.12";
 	} catch {
 		return "unknown";
 	}
@@ -22332,7 +22332,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			if (!payload) return;
 			clearV2EditorFailure(payload.documentId ?? null);
 			clearV2MutationRejectionNotifications(payload.documentId ?? null);
-			const { host, mount, documentId, capabilities, editCommands, bindEditShortcuts, bindSessionShortcuts, commentsAdapter, trackedChangesAdapter, contextMenu, documentApi, documentMutationReadiness, documentApiUnavailableReason, pageMetrics, pageLayout, pageFurniture, presence, lock, collaborationProvider, fonts, replaceFile, upgradeToCollaboration, documentOpenToken } = payload;
+			const { host, mount, documentId, capabilities, editCommands, bindEditShortcuts, bindSessionShortcuts, commentsAdapter, trackedChangesAdapter, contextMenu, documentApi, documentMutationReadiness, documentApiUnavailableReason, pageMetrics, pageLayout, pageFurniture, presence, lock, connection, collaborationProvider, fonts, replaceFile, upgradeToCollaboration, documentOpenToken } = payload;
 			documentOpenTelemetry?.trackDocumentOpen(documentOpenToken ?? null, documentId ?? null);
 			const saveV2Bytes = createV2SaveQueue(async (saveOptions = {}) => {
 				if (!host || typeof host.save !== "function") throw new Error("v2-editor: save unavailable");
@@ -22609,6 +22609,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 				pageFurniture: pageFurniture ?? null,
 				presence: presence ?? null,
 				lock: lock ?? null,
+				connection: connection ?? null,
 				provider: collaborationProvider ?? null,
 				reviewWindow: {
 					getDiagnostics: () => v2ReviewWindowController.getDiagnostics(),
@@ -24454,7 +24455,7 @@ var SuperDoc_default = /*#__PURE__*/ _plugin_vue_export_helper_default({
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-4efb0cab"]]);
+}, [["__scopeId", "data-v-9da02d58"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -45301,6 +45302,14 @@ function contentControlSelectionKey(selection) {
 		return null;
 	}
 }
+function deriveCollaborationConnectionKind(snapshot, hasSyncedBefore) {
+	switch (snapshot.state) {
+		case "failed": return "failed";
+		case "degraded": return snapshot.detail === "reconnecting" ? "reconnecting" : "lost";
+		case "synced": return hasSyncedBefore ? "recovered" : "initial";
+		default: return hasSyncedBefore ? "reconnecting" : "initial";
+	}
+}
 function isV2ActiveEditorFacade(editor) {
 	return Boolean(editor && typeof editor === "object" && editor.editorVersion === 2);
 }
@@ -45357,6 +45366,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 	#destroyed;
 	#diagnostics;
 	#isUpgrading;
+	#pendingUpgrade;
 	/** Aborts an in-flight upgrade (sync wait or ready wait). */
 	#abortUpgrade;
 	/**
@@ -45368,6 +45378,12 @@ var SuperDoc = class extends import_eventemitter3.default {
 	#v2AwarenessUnsub;
 	/** Unsubscribe handle for the v2 root-doc lock observer. */
 	#v2LockUnsub;
+	/** Unsubscribe handle for the v2 collaboration connection observer. */
+	#v2ConnectionUnsub;
+	/** Latest `collaboration-connection-change` payload, for late readers. */
+	#v2ConnectionState;
+	/** Whether the current collaboration room has completed a sync at least once. */
+	#v2ConnectionHasSynced;
 	/** Lock state captured before a local → v2 collaboration promotion remount. */
 	#pendingV2LockSeed;
 	#mountWrapper;
@@ -45456,9 +45472,13 @@ var SuperDoc = class extends import_eventemitter3.default {
 		super();
 		this.#destroyed = false;
 		this.#isUpgrading = false;
+		this.#pendingUpgrade = null;
 		this.#abortUpgrade = null;
 		this.#v2AwarenessUnsub = null;
 		this.#v2LockUnsub = null;
+		this.#v2ConnectionUnsub = null;
+		this.#v2ConnectionState = null;
+		this.#v2ConnectionHasSynced = false;
 		this.#pendingV2LockSeed = null;
 		this.#mountWrapper = null;
 		this.#contentControlClickRoot = null;
@@ -45657,7 +45677,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.18.0-next.10";
+		this.version = "2.18.0-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];
@@ -45759,7 +45779,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		return this.#diagnostics;
 	}
 	emit(event, ...args) {
-		if (event === "exception" || event === "document-replaced" || event === "ready" || event === "active-editor-change" || event === "collaboration-ready" || event === "locked") recordInteraction(this, event, () => args[0]);
+		if (event === "exception" || event === "document-replaced" || event === "ready" || event === "active-editor-change" || event === "collaboration-ready" || event === "collaboration-connection-change" || event === "locked") recordInteraction(this, event, () => args[0]);
 		return super.emit(event, ...args);
 	}
 	on(event, fn, context) {
@@ -46001,6 +46021,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.#onConfig("pdf:document-ready", this.config.onPdfDocumentReady);
 		this.#onConfig("sidebar-toggle", this.config.onSidebarToggle);
 		this.#onConfig("collaboration-ready", this.config.onCollaborationReady);
+		this.#onConfig("collaboration-connection-change", this.config.onCollaborationConnectionChange);
 		this.on("collaboration-ready", (payload) => this.#startV2CollaborationEventBridge(payload?.editor ?? null));
 		this.#onConfig("editor-update", this.config.onEditorUpdate);
 		this.#onConfig("tracked-changes:bulk-decision", this.config.onTrackedChangesBulkDecision);
@@ -46091,12 +46112,59 @@ var SuperDoc = class extends import_eventemitter3.default {
 			} catch {}
 			this.#v2LockUnsub = null;
 		}
+		if (this.#v2ConnectionUnsub) {
+			try {
+				this.#v2ConnectionUnsub();
+			} catch {}
+			this.#v2ConnectionUnsub = null;
+		}
 	}
 	#startV2CollaborationEventBridge(editor) {
 		this.#stopV2CollaborationEventBridge();
 		if (!isV2ActiveEditorFacade(editor)) return;
 		this.#startV2AwarenessBridge(editor);
 		this.#startV2LockBridge(editor);
+		this.#startV2ConnectionBridge(editor);
+	}
+	#startV2ConnectionBridge(editor) {
+		const connection = editor.connection;
+		if (!connection || typeof connection.subscribe !== "function") return;
+		const { documentId } = connection;
+		if (this.#v2ConnectionState?.documentId !== documentId) {
+			this.#v2ConnectionState = null;
+			this.#v2ConnectionHasSynced = false;
+		}
+		const publish = (snapshot) => {
+			if (this.#destroyed) return;
+			const previous = this.#v2ConnectionState;
+			if (previous && previous.state === snapshot.state && previous.detail === (snapshot.detail ?? null)) return;
+			const payload = {
+				documentId,
+				state: snapshot.state,
+				previousState: previous?.state ?? null,
+				kind: deriveCollaborationConnectionKind(snapshot, this.#v2ConnectionHasSynced),
+				detail: snapshot.detail ?? null,
+				superdoc: this
+			};
+			this.#v2ConnectionState = payload;
+			if (snapshot.state === "synced") this.#v2ConnectionHasSynced = true;
+			this.emit("collaboration-connection-change", payload);
+		};
+		try {
+			const initialSnapshot = connection.getSnapshot?.();
+			if (initialSnapshot) publish(initialSnapshot);
+			this.#v2ConnectionUnsub = connection.subscribe(publish);
+		} catch (err) {
+			console.warn("[SuperDoc] v2 connection bridge failed to subscribe", err);
+		}
+	}
+	/**
+	* Latest v2 collaboration connection change, or `null` when no v2
+	* collaboration session has reported one. Same payload as the
+	* `collaboration-connection-change` event.
+	*/
+	getCollaborationConnectionState() {
+		return this.#v2ConnectionState;
 	}
 	#startV2AwarenessBridge(editor) {
 		const presence = editor.presence;
@@ -46184,29 +46252,78 @@ var SuperDoc = class extends import_eventemitter3.default {
 	* - A supported v2 single-doc `v2Collaboration` target
 	* - Create-and-upgrade only (no merge semantics)
 	*
-	* @returns Resolves once the collaborative runtime is ready
+	* @returns The attached room and document once the collaborative runtime is ready
 	*/
 	async upgradeToCollaboration(options) {
+		if (this.#pendingUpgrade) {
+			const { target } = this.#resolveCollaborationUpgradeTarget(options);
+			if (this.#sameUpgradeTarget(target, this.#pendingUpgrade.target)) return this.#pendingUpgrade.promise;
+			throw Object.assign(/* @__PURE__ */ new Error("SuperDoc: a different collaboration target is already upgrading"), { code: "collaboration-upgrade-target-conflict" });
+		}
 		const { target } = this.#validateUpgradePrerequisites(options);
 		this.#isUpgrading = true;
-		try {
-			const localSource = await this.#captureCurrentDocxSourceForUpgrade();
-			const rollback = this.#snapshotV2UpgradeState();
-			const lockSeed = this.#snapshotV2LockSeed();
-			this.#assertNotDestroyed();
+		const operation = (async () => {
 			try {
-				this.#pendingV2LockSeed = lockSeed;
-				const promotion = await this.#promoteSingleDocumentToV2Collaboration(target, localSource);
-				this.#finalizeSingleDocumentV2Collaboration(promotion, target);
-				this.#pendingV2LockSeed = null;
-			} catch (err) {
-				this.#rollbackV2UpgradeState(rollback);
-				throw err;
-			}
-		} finally {
-			this.#abortUpgrade = null;
-			this.#isUpgrading = false;
-		}
+				const localSource = await this.#captureCurrentDocxSourceForUpgrade();
+				const rollback = this.#snapshotV2UpgradeState();
+				const lockSeed = this.#snapshotV2LockSeed();
+				this.#assertNotDestroyed();
+				try {
+					this.#pendingV2LockSeed = lockSeed;
+					const promotion = await this.#promoteSingleDocumentToV2Collaboration(target, localSource);
+					this.#finalizeSingleDocumentV2Collaboration(promotion, target);
+					this.#pendingV2LockSeed = null;
+					const attachedDocumentId = this.activeEditor?.options?.documentId;
+					const attachedRoomId = promotion.configDoc.v2Collaboration?.documentId;
+					if (typeof attachedDocumentId !== "string" || attachedDocumentId !== promotion.configDoc.id || typeof attachedRoomId !== "string" || attachedRoomId !== target.documentId) throw new Error("SuperDoc: collaboration upgrade did not attach the expected room and document");
+					return {
+						roomId: attachedRoomId,
+						documentId: attachedDocumentId
+					};
+				} catch (err) {
+					this.#rollbackV2UpgradeState(rollback);
+					throw err;
+				}
+			} finally {
+				this.#abortUpgrade = null;
+				this.#isUpgrading = false;
+				this.#pendingUpgrade = null;
+			}
+		})();
+		this.#pendingUpgrade = {
+			target,
+			promise: operation
+		};
+		return operation;
+	}
+	#sameUpgradeTarget(left, right) {
+		if (left.token !== right.token) return false;
+		const seen = /* @__PURE__ */ new WeakMap();
+		const sameValue = (first, second) => {
+			if (Object.is(first, second)) return true;
+			if (!first || !second || typeof first !== "object" || typeof second !== "object") return false;
+			if (Object.getPrototypeOf(first) !== Object.getPrototypeOf(second)) return false;
+			if (seen.has(first)) return seen.get(first) === second;
+			seen.set(first, second);
+			if (first instanceof Date && second instanceof Date) return first.getTime() === second.getTime();
+			if (first instanceof RegExp && second instanceof RegExp) return first.source === second.source && first.flags === second.flags;
+			if (first instanceof ArrayBuffer && second instanceof ArrayBuffer) return sameValue(Array.from(new Uint8Array(first)), Array.from(new Uint8Array(second)));
+			if (ArrayBuffer.isView(first) && ArrayBuffer.isView(second)) return first.constructor === second.constructor && sameValue(Array.from(new Uint8Array(first.buffer, first.byteOffset, first.byteLength)), Array.from(new Uint8Array(second.buffer, second.byteOffset, second.byteLength)));
+			if (first instanceof Map && second instanceof Map) return first.size === second.size && sameValue(Array.from(first.entries()), Array.from(second.entries()));
+			if (first instanceof Set && second instanceof Set) return first.size === second.size && sameValue(Array.from(first.values()), Array.from(second.values()));
+			if (Array.isArray(first) && Array.isArray(second)) return first.length === second.length && first.every((value, index) => sameValue(value, second[index]));
+			if (Object.getPrototypeOf(first) !== Object.prototype && Object.getPrototypeOf(first) !== null) return false;
+			const keys = Object.keys(first).sort();
+			const otherKeys = Object.keys(second).sort();
+			return keys.length === otherKeys.length && keys.every((key, index) => key === otherKeys[index] && sameValue(first[key], second[key]));
+		};
+		return sameValue({
+			...left,
+			token: void 0
+		}, {
+			...right,
+			token: void 0
+		});
 	}
 	#snapshotV2LockSeed() {
 		return {
@@ -46533,9 +46650,13 @@ var SuperDoc = class extends import_eventemitter3.default {
 		if (docxDocs.length > 1) throw new Error("SuperDoc: upgradeToCollaboration() only supports a single DOCX document");
 		if (cfg.documents.length !== docxDocs.length) throw new Error("SuperDoc: upgradeToCollaboration() only supports single-DOCX instances");
 		if (!isV2ActiveEditorFacade(this.#resolveSourceEditor())) throw new Error("SuperDoc: upgradeToCollaboration() requires a ready v2 DOCX editor");
-		const configDoc = docxDocs[0];
-		const mountedDocumentId = configDoc.id;
+		const mountedDocumentId = docxDocs[0].id;
 		if (typeof mountedDocumentId !== "string" || mountedDocumentId.length === 0) throw new Error("SuperDoc: source document is missing its mounted document identity");
+		return this.#resolveCollaborationUpgradeTarget(options);
+	}
+	#resolveCollaborationUpgradeTarget(options) {
+		const cfg = this.config;
+		const configDoc = cfg.documents.find((doc) => doc.type === DOCX);
 		const collaborationModule = cfg.modules?.collaboration;
 		const legacyCollaboration = options.ydoc || options.provider ? {
 			ydoc: options.ydoc,
@@ -46551,7 +46672,10 @@ var SuperDoc = class extends import_eventemitter3.default {
 			...typeof window !== "undefined" ? { authEndpointBaseUrl: window.location.href } : {}
 		});
 		if (!resolution.ok) throw new Error(`SuperDoc: upgradeToCollaboration() ${resolution.reason}: ${resolution.message}`);
-		return { target: resolution.target };
+		return { target: {
+			...resolution.target,
+			roomMode: "create"
+		} };
 	}
 	#unwrapMaybeRef(value) {
 		if (value && typeof value === "object" && "value" in value) return value.value;