superdoc 2.18.0-next.8 → 2.18.0

package/dist/superdoc/src/public/ui/create-super-doc-ui.d.ts

@@ -1,4 +1,11 @@
-import { SuperDocUI, SuperDocUIOptions } from './types.js';
+import { CommandExecutionResult, SuperDocUI, SuperDocUIOptions } from './types.js';
+type FirstPartyCommandMutation = {
+    supports: (memberPath: string) => boolean;
+    run: (memberPath: string, args: readonly unknown[]) => unknown;
+    runListApply: (input: unknown) => Promise<boolean>;
+};
+export declare function registerFirstPartyCommandMutation(superdoc: object, host: object, mutation: FirstPartyCommandMutation): void;
+export declare function executeFirstPartyCommandAsync(ui: Pick<SuperDocUI, 'commands'>, id: string, payload?: unknown): Promise<CommandExecutionResult>;
 /**
  * Heavy-read policy for the async read coordinator (source-loading deferral).
  * One shared table: the coordinator's gate and the table-driven policy tests
@@ -16,3 +23,4 @@ export declare const HEAVY_DOC_READ_POLICY: readonly HeavyDocReadPolicyEntry[];
 /** Whether a coordinator cache key falls under the heavy-read policy. */
 export declare function isHeavyDocReadKey(key: string): boolean;
 export declare function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI;
+export {};

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-wDvhW9Tz.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.8";
+		return "2.18.0";
 	} catch {
 		return "unknown";
 	}
@@ -14979,6 +14979,79 @@ function useViewportFit({ getSuperdoc, superdocContainerWidth, isReady, activeZo
 	return { evaluateViewport };
 }
 //#endregion
+//#region ../layout-engine/contracts/src/author-colors.ts
+/**
+* Curated, high-contrast fallback palette. Used when neither `overrides` nor
+* `resolve` produces a color so imported/discovered authors the host did not
+* configure ahead of time still get a stable, distinct color.
+*/
+var FALLBACK_PALETTE = [
+	"#1f6feb",
+	"#d1242f",
+	"#8250df",
+	"#bf3989",
+	"#1a7f37",
+	"#9a6700",
+	"#bc4c00",
+	"#0969da",
+	"#cf222e",
+	"#6639ba",
+	"#116329",
+	"#7d4e00"
+];
+/** Stable identity string for an author (used for hashing + dedupe). */
+var authorIdentityKey = (author) => {
+	if (!author) return "";
+	return `${typeof author.name === "string" ? author.name : ""} ${typeof author.email === "string" ? author.email : ""}`;
+};
+/** Deterministic 32-bit FNV-1a hash of a string. */
+var hashString = (value) => {
+	let hash = 2166136261;
+	for (let i = 0; i < value.length; i += 1) {
+		hash ^= value.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+};
+/**
+* Deterministic fallback color derived from the author identity. The same
+* identity always maps to the same palette entry, so colors stay stable across
+* reloads and across the paint / snapshot surfaces.
+*/
+var fallbackAuthorColor = (author) => {
+	return FALLBACK_PALETTE[hashString(authorIdentityKey(author)) % FALLBACK_PALETTE.length];
+};
+var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+/**
+* Composes the host `authorColors` config into a single resolver.
+*
+* Resolution order per author:
+* 1. `overrides` by identity — `email` first, then `name` (exact match).
+* 2. `resolve(author)`.
+* 3. A deterministic fallback color from the author identity.
+*
+* Returns `undefined` when colors are disabled (`enabled === false`) or no
+* config was provided, so callers can leave the existing default palette in
+* place by simply not threading a resolver.
+*/
+var composeAuthorColorResolver = (config) => {
+	if (!config || config.enabled === false) return void 0;
+	const overrides = config.overrides && typeof config.overrides === "object" ? config.overrides : void 0;
+	const resolve = typeof config.resolve === "function" ? config.resolve : void 0;
+	return (author) => {
+		const safeAuthor = author ?? {};
+		if (overrides) {
+			if (isNonEmptyString(safeAuthor.email) && isNonEmptyString(overrides[safeAuthor.email])) return overrides[safeAuthor.email];
+			if (isNonEmptyString(safeAuthor.name) && isNonEmptyString(overrides[safeAuthor.name])) return overrides[safeAuthor.name];
+		}
+		if (resolve) try {
+			const resolved = resolve(safeAuthor);
+			if (isNonEmptyString(resolved)) return resolved;
+		} catch {}
+		return fallbackAuthorColor(safeAuthor);
+	};
+};
+//#endregion
 //#region src/components/CommentsLayer/floating-comment-positioning.js
 var isPersistentReviewSidebarItem = (comment) => {
 	return Boolean(comment?.trackedChange);
@@ -16392,79 +16465,6 @@ var _sfc_main$27 = {
 };
 var WhiteboardLayer_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_vue_export_helper_default(_sfc_main$27, [["__scopeId", "data-v-54546c3d"]]);
 //#endregion
-//#region ../layout-engine/contracts/src/author-colors.ts
-/**
-* Curated, high-contrast fallback palette. Used when neither `overrides` nor
-* `resolve` produces a color so imported/discovered authors the host did not
-* configure ahead of time still get a stable, distinct color.
-*/
-var FALLBACK_PALETTE = [
-	"#1f6feb",
-	"#d1242f",
-	"#8250df",
-	"#bf3989",
-	"#1a7f37",
-	"#9a6700",
-	"#bc4c00",
-	"#0969da",
-	"#cf222e",
-	"#6639ba",
-	"#116329",
-	"#7d4e00"
-];
-/** Stable identity string for an author (used for hashing + dedupe). */
-var authorIdentityKey = (author) => {
-	if (!author) return "";
-	return `${typeof author.name === "string" ? author.name : ""} ${typeof author.email === "string" ? author.email : ""}`;
-};
-/** Deterministic 32-bit FNV-1a hash of a string. */
-var hashString = (value) => {
-	let hash = 2166136261;
-	for (let i = 0; i < value.length; i += 1) {
-		hash ^= value.charCodeAt(i);
-		hash = Math.imul(hash, 16777619);
-	}
-	return hash >>> 0;
-};
-/**
-* Deterministic fallback color derived from the author identity. The same
-* identity always maps to the same palette entry, so colors stay stable across
-* reloads and across the paint / snapshot surfaces.
-*/
-var fallbackAuthorColor = (author) => {
-	return FALLBACK_PALETTE[hashString(authorIdentityKey(author)) % FALLBACK_PALETTE.length];
-};
-var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
-/**
-* Composes the host `authorColors` config into a single resolver.
-*
-* Resolution order per author:
-* 1. `overrides` by identity — `email` first, then `name` (exact match).
-* 2. `resolve(author)`.
-* 3. A deterministic fallback color from the author identity.
-*
-* Returns `undefined` when colors are disabled (`enabled === false`) or no
-* config was provided, so callers can leave the existing default palette in
-* place by simply not threading a resolver.
-*/
-var composeAuthorColorResolver = (config) => {
-	if (!config || config.enabled === false) return void 0;
-	const overrides = config.overrides && typeof config.overrides === "object" ? config.overrides : void 0;
-	const resolve = typeof config.resolve === "function" ? config.resolve : void 0;
-	return (author) => {
-		const safeAuthor = author ?? {};
-		if (overrides) {
-			if (isNonEmptyString(safeAuthor.email) && isNonEmptyString(overrides[safeAuthor.email])) return overrides[safeAuthor.email];
-			if (isNonEmptyString(safeAuthor.name) && isNonEmptyString(overrides[safeAuthor.name])) return overrides[safeAuthor.name];
-		}
-		if (resolve) try {
-			const resolved = resolve(safeAuthor);
-			if (isNonEmptyString(resolved)) return resolved;
-		} catch {}
-		return fallbackAuthorColor(safeAuthor);
-	};
-};
-//#endregion
 //#region src/components/HtmlViewer/HtmlViewer.vue
 var _hoisted_1$20 = { class: "superdoc-html-viewer" };
 var _hoisted_2$16 = { class: "superdoc-html-viewer__document" };
@@ -22171,7 +22171,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 					executeAsync: (commandId, payload) => {
 						const ui = getSuperDocUI();
 						if (!ui) return Promise.resolve(UNAVAILABLE_COMMAND_RESULT);
-						return ui.commands.executeAsync(commandId, payload);
+						return require_create_super_doc_ui.executeFirstPartyCommandAsync(ui, commandId, payload);
 					},
 					getState: (commandId) => getSuperDocUI()?.commands.get(commandId).getState() ?? UNAVAILABLE_COMMAND_STATE
 				},
@@ -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, firstPartyCommandMutation, 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(),
@@ -22687,6 +22688,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				if (doc) doc.provider = provider;
 			}
 			proxy.$superdoc.broadcastEditorCreate(facade);
+			if (host && firstPartyCommandMutation) require_create_super_doc_ui.registerFirstPartyCommandMutation(proxy.$superdoc, host, firstPartyCommandMutation);
 			installV2CommandShortcutBinding({
 				documentId,
 				bindEditShortcuts
@@ -23247,7 +23249,8 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				case "collaboration-room-corrupt": return "SuperDoc v2 found a structurally invalid collaboration room. No changes were made.";
 				case "collaboration-v2-room-missing": return "SuperDoc v2 could not find a committed v2 collaboration room. No changes were made. Use roomMode: \"create\" only when creating a new room.";
 				case "collaboration-v2-room-already-exists": return "SuperDoc v2 was asked to create a collaboration room that already exists. Use roomMode: \"join\" to open it.";
-				case "collaboration-v2-room-initializing": return "The SuperDoc v2 collaboration room is still initializing. Join mode did not modify it.";
+				case "collaboration-v2-room-initializing": return "The SuperDoc v2 collaboration room has not completed initialization. This open attempt did not modify it.";
+				case "collaboration-v2-room-bootstrap-stalled": return "The SuperDoc v2 collaboration room bootstrap appears stalled. This open attempt did not modify it. Preserve the room data if a create retry cannot recover it.";
 				case "collaboration-open-intent-invalid": return "SuperDoc v2 received an invalid collaboration room mode. No provider was connected.";
 				case "collaboration-config-invalid": return "SuperDoc v2 received an invalid collaboration configuration. No provider was connected.";
 				default: return "SuperDoc could not load the document editor.";
@@ -23274,7 +23277,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				...workerFailure ? { workerFailure } : {},
 				reason
 			};
-			if (reason === "collaboration-v1-config-unsupported" || reason === "collaboration-room-format-unsupported" || reason === "collaboration-room-format-conflict" || reason === "collaboration-room-corrupt" || reason === "collaboration-v2-room-missing" || reason === "collaboration-v2-room-already-exists" || reason === "collaboration-v2-room-initializing" || reason === "collaboration-open-intent-invalid" || reason === "collaboration-config-invalid") console.warn(`[SuperDoc] ${message}`, logContext);
+			if (reason === "collaboration-v1-config-unsupported" || reason === "collaboration-room-format-unsupported" || reason === "collaboration-room-format-conflict" || reason === "collaboration-room-corrupt" || reason === "collaboration-v2-room-missing" || reason === "collaboration-v2-room-already-exists" || reason === "collaboration-v2-room-initializing" || reason === "collaboration-v2-room-bootstrap-stalled" || reason === "collaboration-open-intent-invalid" || reason === "collaboration-config-invalid") console.warn(`[SuperDoc] ${message}`, logContext);
 			else console.error(`[SuperDoc] ${message}`, logContext);
 			proxy.$superdoc.emit("exception", collaborationException ?? {
 				error: new Error(message),
@@ -24494,7 +24497,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-4efb0cab"]]);
+}, [["__scopeId", "data-v-77e0209a"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -44367,7 +44370,7 @@ function executeCommand(ui, commandId, argument, options = {}) {
 	if (typeof ui.commands.has === "function" && !ui.commands.has(commandId)) return false;
 	const execute = typeof ui.commands.executeAsync === "function" ? ui.commands.executeAsync : ui.commands.execute;
 	if (typeof execute !== "function") return false;
-	const result = argument === void 0 ? execute.call(ui.commands, commandId) : execute.call(ui.commands, commandId, argument);
+	const result = options.firstParty ? require_create_super_doc_ui.executeFirstPartyCommandAsync(ui, commandId, argument) : argument === void 0 ? execute.call(ui.commands, commandId) : execute.call(ui.commands, commandId, argument);
 	const reportFailure = (settled) => {
 		if (!options.reportUnhandled || settled !== false) return;
 		options.onError?.(/* @__PURE__ */ new Error(`[superdoc toolbar] Command "${commandId}" did not run. Check that it is enabled and has the required input.`));
@@ -45015,6 +45018,7 @@ var BuiltInToolbar = class extends require_eventemitter3.import_eventemitter3.de
 		const name = item?.name?.value;
 		if (!name) return false;
 		const callbacks = {
+			firstParty: true,
 			onSettled: () => this.updateToolbarState(),
 			onError: (error) => this.#emitCommandException(error, name)
 		};
@@ -45043,6 +45047,7 @@ var BuiltInToolbar = class extends require_eventemitter3.import_eventemitter3.de
 			onPick: async (file) => {
 				const src = await resolveImageSrc(file, this.superdoc?.config?.handleImageUpload);
 				executeCommand(this.ui, "image", { src }, {
+					firstParty: true,
 					onSettled: () => this.updateToolbarState(),
 					onError: (error) => this.#emitCommandException(error, "image")
 				});
@@ -45370,6 +45375,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 +45439,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 +45451,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 +45545,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 +45750,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.8";
+		this.version = "2.18.0";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -45828,7 +45852,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 +46094,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 +46185,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 +46325,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 +46723,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 +46745,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;