superdoc 2.18.0-next.11 → 2.18.0-next.13

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.18.0-next.11",
+	superdocVersion: "2.18.0-next.13",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.18.0-next.11",
+	superdocVersion: "2.18.0-next.13",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/images/images.types.d.ts

@@ -181,6 +181,8 @@ export interface CreateImageSuccessResult {
     success: true;
     image: ImageAddress;
     trackedChangeRefs?: ReceiptInsert[];
+    /** Commit id for the insertion, including its alt text when that was set in the same call. */
+    txId?: string;
 }
 export interface CreateImageFailureResult {
     success: false;

package/dist/document-api/src/types/clipboard.d.ts

@@ -110,7 +110,26 @@ export type SDPasteLeafInline = {
     title?: string;
     sourcePath?: readonly (string | number)[];
 };
-export type SDPasteInline = SDPasteLeafInline | {
+export interface SDPasteSdtInline {
+    kind: 'sdt';
+    controlType: 'text' | 'richText';
+    tag?: string;
+    alias?: string;
+    lockMode?: 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+    multiline?: boolean;
+    sourcePath?: readonly (string | number)[];
+    inlines: readonly (SDPasteLeafInline | SDPasteSdtInline)[];
+}
+export interface SDPasteBlockSdt {
+    /** Clipboard-local wrapper identity shared by adjacent paragraphs. */
+    sourceId: string;
+    controlType: 'text' | 'richText';
+    tag?: string;
+    alias?: string;
+    lockMode?: 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+    multiline?: boolean;
+}
+export type SDPasteInline = SDPasteLeafInline | SDPasteSdtInline | {
     kind: 'hyperlink';
     target: {
         kind: 'external';
@@ -176,6 +195,8 @@ export interface SDPasteParagraphBlock {
      * paste anchor's paragraph, independent of whether they carry formatting.
      */
     complete?: boolean;
+    /** Outermost-first complete block content-control ancestry. */
+    blockSdts?: readonly SDPasteBlockSdt[];
     /** Transient conversion identity used to map mutation effects back to source nodes. */
     sourcePath?: readonly (string | number)[];
 }

package/dist/superdoc/src/core/SuperDoc.d.ts

@@ -9,7 +9,7 @@ import { normalizeInteractionConfig } from './config/normalize-interaction-confi
 import { normalizeSurfacesConfig } from './config/normalize-surfaces-config.js';
 import { EditorRuntimeFocusOptions } from './editor-runtime/types.js';
 import { BorrowedSuperDocUI } from '../public/ui/types.js';
-import { AwarenessUser, CanPerformPermissionParams, CollaborationProvider, Config, ContentControlActiveChangePayload, ContentControlClickPayload, DocumentMode, Editor, EditorUpdateEvent, ExportParams, FontsChangedPayload, FontsResolvedPayload, InternalConfig, ListDefinitionsPayload, NavigableAddress, DocumentRendererRuntime, SearchMatch, SuperDocAwarenessUpdatePayload, SuperDocCommentsUpdatePayload, SuperDocCommentsListChangePayload, SuperDocDocumentModeChangePayload, SuperDocDocumentReplacedPayload, SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocFontsApi, SuperDocFormattingMarksChangePayload, SuperDocLockedPayload, SuperDocCollaborationConnectionChangePayload, SuperDocMeasurementUnit, SuperDocMeasurementUnitChangePayload, SuperDocPageMarginsChangePayload, SuperDocPaginationUpdatePayload, SuperDocReadyPayload, SuperDocState, SuperDocTrackedChangesBulkDecisionPayload, SuperDocViewportChangePayload, SuperDocViewportMetrics, SuperDocZoomMode, SuperDocZoomPayload, SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, User, ViewingOptions } from './types/index.js';
+import { AwarenessUser, CanPerformPermissionParams, CollaborationProvider, Config, ContentControlActiveChangePayload, ContentControlClickPayload, DocumentMode, Editor, EditorUpdateEvent, ExportParams, FontsChangedPayload, FontsResolvedPayload, InternalConfig, ListDefinitionsPayload, NavigableAddress, DocumentRendererRuntime, SearchMatch, SuperDocAwarenessUpdatePayload, SuperDocCommentsUpdatePayload, SuperDocCommentsListChangePayload, SuperDocDocumentModeChangePayload, SuperDocDocumentReplacedPayload, SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocFontsApi, SuperDocFormattingMarksChangePayload, SuperDocLockedPayload, SuperDocCollaborationConnectionChangePayload, SuperDocMeasurementUnit, SuperDocMeasurementUnitChangePayload, SuperDocPageMarginsChangePayload, SuperDocPaginationUpdatePayload, SuperDocReadyPayload, SuperDocState, SuperDocTrackedChangesBulkDecisionPayload, SuperDocViewportChangePayload, SuperDocViewportMetrics, SuperDocZoomMode, SuperDocZoomPayload, SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, UpgradeToCollaborationResult, User, ViewingOptions } from './types/index.js';
 import { WhiteboardData } from './whiteboard/Whiteboard.js';
 type ToolbarLike = {
     activeEditor?: unknown;
@@ -367,9 +367,9 @@ export declare class SuperDoc extends EventEmitter<SuperDocEventMap> {
      * - 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
      */
-    upgradeToCollaboration(options: UpgradeToCollaborationOptions): Promise<void>;
+    upgradeToCollaboration(options: UpgradeToCollaborationOptions): Promise<UpgradeToCollaborationResult>;
     /**
      * Add a user to the shared users list. Requires the instance to be
      * ready; pre-ready mutations would be silently overwritten by the

package/dist/superdoc/src/core/types/index.d.ts

@@ -1193,6 +1193,15 @@ export interface UpgradeToCollaborationOptions {
      */
     provider?: CollaborationProvider;
 }
+/** Confirmed identities of the room and local document attached by a successful upgrade. */
+export interface UpgradeToCollaborationResult {
+    roomId: string;
+    documentId: string;
+}
+/** Machine-readable failures returned by a create-and-upgrade attempt. */
+export interface SuperDocCollaborationUpgradeError extends Error {
+    code: 'collaboration-v2-room-already-exists' | 'collaboration-upgrade-target-conflict';
+}
 /** Context passed to a hyperlink activation handler. */
 export interface HyperlinkActivationContext {
     /** The editor instance. */

package/dist/superdoc/src/public/index.d.cts

@@ -130,6 +130,7 @@ import type { SuperDocCharRange as __Cjs_SuperDocCharRange } from './index.js' w
 import type { SuperDocCollaborationConnectionChangePayload as __Cjs_SuperDocCollaborationConnectionChangePayload } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocCollaborationConnectionKind as __Cjs_SuperDocCollaborationConnectionKind } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocCollaborationConnectionState as __Cjs_SuperDocCollaborationConnectionState } from './index.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationUpgradeError as __Cjs_SuperDocCollaborationUpgradeError } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocCommandApi as __Cjs_SuperDocCommandApi } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocCommandExecuteContext as __Cjs_SuperDocCommandExecuteContext } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocCommandState as __Cjs_SuperDocCommandState } from './index.js' with { "resolution-mode": "import" };
@@ -273,6 +274,7 @@ import type { TrackedChangeSemanticColorKey as __Cjs_TrackedChangeSemanticColorK
 import type { TrackedChangeSemanticColorResolverInput as __Cjs_TrackedChangeSemanticColorResolverInput } from './index.js' with { "resolution-mode": "import" };
 import type { UIConfig as __Cjs_UIConfig } from './index.js' with { "resolution-mode": "import" };
 import type { UpgradeToCollaborationOptions as __Cjs_UpgradeToCollaborationOptions } from './index.js' with { "resolution-mode": "import" };
+import type { UpgradeToCollaborationResult as __Cjs_UpgradeToCollaborationResult } from './index.js' with { "resolution-mode": "import" };
 import type { User as __Cjs_User } from './index.js' with { "resolution-mode": "import" };
 import type { V2CollaborationConfig as __Cjs_V2CollaborationConfig } from './index.js' with { "resolution-mode": "import" };
 import type { ViewingOptions as __Cjs_ViewingOptions } from './index.js' with { "resolution-mode": "import" };
@@ -420,6 +422,7 @@ export type { __Cjs_SuperDocCharRange as SuperDocCharRange };
 export type { __Cjs_SuperDocCollaborationConnectionChangePayload as SuperDocCollaborationConnectionChangePayload };
 export type { __Cjs_SuperDocCollaborationConnectionKind as SuperDocCollaborationConnectionKind };
 export type { __Cjs_SuperDocCollaborationConnectionState as SuperDocCollaborationConnectionState };
+export type { __Cjs_SuperDocCollaborationUpgradeError as SuperDocCollaborationUpgradeError };
 export type { __Cjs_SuperDocCommandApi as SuperDocCommandApi };
 export type { __Cjs_SuperDocCommandExecuteContext as SuperDocCommandExecuteContext };
 export type { __Cjs_SuperDocCommandState as SuperDocCommandState };
@@ -563,6 +566,7 @@ export type { __Cjs_TrackedChangeSemanticColorKey as TrackedChangeSemanticColorK
 export type { __Cjs_TrackedChangeSemanticColorResolverInput as TrackedChangeSemanticColorResolverInput };
 export type { __Cjs_UIConfig as UIConfig };
 export type { __Cjs_UpgradeToCollaborationOptions as UpgradeToCollaborationOptions };
+export type { __Cjs_UpgradeToCollaborationResult as UpgradeToCollaborationResult };
 export type { __Cjs_User as User };
 export type { __Cjs_V2CollaborationConfig as V2CollaborationConfig };
 export type { __Cjs_ViewingOptions as ViewingOptions };

package/dist/superdoc/src/public/index.d.ts

@@ -181,6 +181,8 @@ export type { InteractionConfig } from '../core/types/index.js';
 export type { SurfacesConfig } from '../core/types/index.js';
 export type { UIConfig } from '../core/types/index.js';
 export type { UpgradeToCollaborationOptions } from '../core/types/index.js';
+export type { UpgradeToCollaborationResult } from '../core/types/index.js';
+export type { SuperDocCollaborationUpgradeError } from '../core/types/index.js';
 export type { V2CollaborationConfig } from '../core/types/index.js';
 export type { User } from '../core/types/index.js';
 export type { ViewOptions } from '../core/types/index.js';

package/dist/superdoc.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.11";
+		return "2.18.0-next.13";
 	} catch {
 		return "unknown";
 	}
@@ -45435,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;
 	/**
@@ -45540,6 +45541,7 @@ 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;
@@ -45744,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.11";
+		this.version = "2.18.0-next.13";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -46319,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 {
@@ -46668,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,
@@ -46686,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

@@ -315,7 +315,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.18.0-next.11";
+		return "2.18.0-next.13";
 	} catch {
 		return "unknown";
 	}
@@ -45366,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;
 	/**
@@ -45471,6 +45472,7 @@ 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;
@@ -45675,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.11";
+		this.version = "2.18.0-next.13";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];
@@ -46250,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 {
@@ -46599,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,
@@ -46617,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;