superdoc 2.13.0-next.7 → 2.13.0-next.9

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.13.0-next.7";
+		return "2.13.0-next.9";
 	} catch {
 		return "unknown";
 	}
@@ -5311,6 +5311,274 @@ function storeToRefs(store) {
 	return refs;
 }
 //#endregion
+//#region src/core/collaboration/resolve-v2-collaboration-target.ts
+/** Select the public spelling before validation; do not merge settings from different rooms. */
+function readCollaborationConfig(input) {
+	return input.collaboration !== void 0 ? input.collaboration : input.v2Collaboration;
+}
+/**
+* Redact a connection URL for safe inclusion in diagnostics and artifacts.
+*
+* Strips the query string, fragment, and any embedded credentials (userinfo)
+* because those commonly carry auth tokens. Falls back to a coarse string scrub
+* when the value is not a parseable absolute URL so a malformed value with an
+* inline `?token=...` still cannot leak.
+*/
+function redactCollaborationUrl(url) {
+	if (typeof url !== "string" || url.length === 0) return "<none>";
+	try {
+		const parsed = new URL(url);
+		parsed.search = "";
+		parsed.hash = "";
+		parsed.username = "";
+		parsed.password = "";
+		const redactedQuery = url.includes("?") ? "?<redacted>" : "";
+		return `${parsed.toString().replace(/\?$/, "")}${redactedQuery}`;
+	} catch {
+		const withoutCredentials = url.replace(/\/\/[^/@]+@/, "//");
+		const cut = withoutCredentials.search(/[?#]/);
+		if (cut === -1) return withoutCredentials;
+		return `${withoutCredentials.slice(0, cut)}?<redacted>`;
+	}
+}
+function normalizeNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+function normalizeWebsocketUrl(value) {
+	if (typeof value !== "string" || value.length === 0) return null;
+	try {
+		const parsed = new URL(value);
+		return parsed.protocol === "ws:" || parsed.protocol === "wss:" ? value : null;
+	} catch {
+		return null;
+	}
+}
+function normalizeHttpUrl(value, baseUrl) {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim();
+	if (normalized.length === 0) return null;
+	try {
+		const parsed = new URL(normalized);
+		return parsed.protocol === "http:" || parsed.protocol === "https:" ? normalized : null;
+	} catch {
+		if (typeof baseUrl !== "string" || baseUrl.trim().length === 0) return null;
+		try {
+			const parsed = new URL(normalized, baseUrl);
+			return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
+		} catch {
+			return null;
+		}
+	}
+}
+function normalizeParams(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const params = {};
+	for (const [key, raw] of Object.entries(value)) if (typeof raw === "string") params[key] = raw;
+	return Object.keys(params).length > 0 ? params : void 0;
+}
+function normalizeRoomMode(value) {
+	if (value === void 0) return "join";
+	return value === "join" || value === "create" ? value : null;
+}
+function invalidRoomMode() {
+	return {
+		ok: false,
+		reason: "invalid-room-mode",
+		message: "SuperDoc v2 collaboration roomMode must be either \"join\" or \"create\"."
+	};
+}
+/** Provider-family token recognized on a v2Collaboration config object. */
+function readProviderType(candidate) {
+	const raw = candidate.providerType;
+	return typeof raw === "string" && raw.length > 0 ? raw.toLowerCase() : null;
+}
+/**
+* Detect whether a legacy collaboration block names a provider family that the
+* shipped single-doc v2 runtime cannot drive. Returns the offending family name
+* (for diagnostics) or `null` when the block carries no recognizable family.
+*/
+function detectUnsupportedLegacyFamily(legacy) {
+	if (!legacy || typeof legacy !== "object") return null;
+	const providerType = typeof legacy.providerType === "string" ? legacy.providerType.toLowerCase() : "";
+	if (providerType === "hocuspocus") return "hocuspocus";
+	if (providerType === "liveblocks") return "liveblocks";
+	if (providerType === "superdoc") return "superdoc";
+	if (legacy.ydoc != null || legacy.provider != null) return "external-ydoc-provider";
+	return null;
+}
+/** Resolve a websocket-backed family (y-websocket / Hocuspocus). */
+function resolveWebsocketFamily(family, candidate) {
+	const documentId = normalizeNonEmptyString(candidate.documentId);
+	if (!documentId) return {
+		ok: false,
+		reason: "invalid-document-id",
+		message: `SuperDoc v2 collaboration requires a non-empty collaboration.documentId for the "${family}" provider.`
+	};
+	const rawUrl = candidate.url ?? candidate.serverUrl;
+	const serverUrl = normalizeWebsocketUrl(rawUrl);
+	if (!serverUrl) return {
+		ok: false,
+		reason: "invalid-server-url",
+		message: `SuperDoc v2 collaboration requires a valid ws:// or wss:// URL for the "${family}" provider (received: ${redactCollaborationUrl(rawUrl)}).`
+	};
+	const params = normalizeParams(candidate.params);
+	const token = family === "hocuspocus" && typeof candidate.token === "function" ? candidate.token : family === "hocuspocus" ? normalizeNonEmptyString(candidate.token) : null;
+	const roomMode = normalizeRoomMode(candidate.roomMode);
+	if (!roomMode) return invalidRoomMode();
+	return {
+		ok: true,
+		target: {
+			providerFamily: family,
+			documentId,
+			roomMode,
+			serverUrl,
+			...params ? { params } : {},
+			...token ? { token } : {}
+		}
+	};
+}
+function resolveProviderExtension(candidate) {
+	const adapterId = normalizeNonEmptyString(candidate.adapterId);
+	if (!adapterId) return {
+		ok: false,
+		reason: "invalid-adapter-id",
+		message: "SuperDoc v2 provider extensions require a non-empty v2Collaboration.adapterId."
+	};
+	const documentId = normalizeNonEmptyString(candidate.documentId);
+	if (!documentId) return {
+		ok: false,
+		reason: "invalid-document-id",
+		message: "SuperDoc v2 provider extensions require a non-empty v2Collaboration.documentId."
+	};
+	const roomMode = normalizeRoomMode(candidate.roomMode);
+	if (!roomMode) return invalidRoomMode();
+	if (Object.prototype.hasOwnProperty.call(candidate, "providerOptions")) try {
+		structuredClone(candidate.providerOptions);
+	} catch {
+		return {
+			ok: false,
+			reason: "invalid-provider-options",
+			message: "SuperDoc v2 provider extension options must be structured-clone-safe."
+		};
+	}
+	const token = typeof candidate.token === "function" ? candidate.token : normalizeNonEmptyString(candidate.token);
+	return {
+		ok: true,
+		target: {
+			providerFamily: "extension",
+			adapterId,
+			documentId,
+			roomMode,
+			...Object.prototype.hasOwnProperty.call(candidate, "providerOptions") ? { providerOptions: candidate.providerOptions } : {},
+			...token ? { token } : {}
+		}
+	};
+}
+/** Resolve the Liveblocks family (exactly one of publicApiKey / authEndpoint). */
+function resolveLiveblocksFamily(candidate, authEndpointBaseUrl) {
+	const documentId = normalizeNonEmptyString(candidate.documentId ?? candidate.roomId);
+	if (!documentId) return {
+		ok: false,
+		reason: "invalid-document-id",
+		message: "SuperDoc v2 collaboration requires a non-empty collaboration.documentId (or roomId) for the \"liveblocks\" provider."
+	};
+	const publicApiKey = normalizeNonEmptyString(candidate.publicApiKey);
+	const roomMode = normalizeRoomMode(candidate.roomMode);
+	if (!roomMode) return invalidRoomMode();
+	const authEndpointRaw = candidate.authEndpoint;
+	const hasAuthEndpoint = typeof authEndpointRaw === "string" && authEndpointRaw.length > 0;
+	if (!publicApiKey && !hasAuthEndpoint) return {
+		ok: false,
+		reason: "missing-auth",
+		message: "SuperDoc v2 Liveblocks collaboration requires exactly one auth mode: a publicApiKey or an authEndpoint. None was provided."
+	};
+	if (publicApiKey && hasAuthEndpoint) return {
+		ok: false,
+		reason: "mixed-auth",
+		message: "SuperDoc v2 Liveblocks collaboration accepts exactly one auth mode; pass either publicApiKey or authEndpoint, not both."
+	};
+	if (publicApiKey) return {
+		ok: true,
+		target: {
+			providerFamily: "liveblocks",
+			documentId,
+			roomMode,
+			publicApiKey
+		}
+	};
+	const authEndpoint = normalizeHttpUrl(authEndpointRaw, authEndpointBaseUrl);
+	if (!authEndpoint) return {
+		ok: false,
+		reason: "invalid-auth-endpoint",
+		message: "SuperDoc v2 Liveblocks collaboration requires a valid http(s) authEndpoint URL (received: <redacted>)."
+	};
+	return {
+		ok: true,
+		target: {
+			providerFamily: "liveblocks",
+			documentId,
+			roomMode,
+			authEndpoint
+		}
+	};
+}
+/**
+* Resolve a constructor-time or upgrade-time collaboration request into a
+* supported v2 room target, or a stable redacted diagnostic.
+*/
+function resolveV2CollaborationTarget(input) {
+	const { legacyCollaboration, documentType, documentCount, authEndpointBaseUrl } = input;
+	const v2Collaboration = readCollaborationConfig(input);
+	if (typeof documentCount === "number" && documentCount > 1) return {
+		ok: false,
+		reason: "unsupported-multi-document",
+		message: `SuperDoc v2 collaboration supports exactly one document per room; received ${documentCount}.`
+	};
+	if (documentType != null && documentType !== "application/vnd.openxmlformats-officedocument.wordprocessingml.document") return {
+		ok: false,
+		reason: "unsupported-document-type",
+		message: "SuperDoc v2 collaboration supports DOCX documents only."
+	};
+	if (!(v2Collaboration != null && typeof v2Collaboration === "object")) {
+		const family = detectUnsupportedLegacyFamily(legacyCollaboration);
+		if (family) {
+			const reason = family === "external-ydoc-provider" ? "unsupported-legacy-provider" : "unsupported-provider-family";
+			const redactedUrl = redactCollaborationUrl(legacyCollaboration?.url);
+			return {
+				ok: false,
+				reason,
+				message: family === "external-ydoc-provider" ? "SuperDoc v2 collaboration cannot use an external { ydoc, provider } pair. Provide a collaboration target (e.g. { providerType, documentId, url }) instead." : `SuperDoc v2 collaboration does not accept "${family}" through the legacy modules.collaboration block (server: ${redactedUrl}). Configure it as a document.collaboration target ({ providerType: "${family}", documentId, ... }) instead.`
+			};
+		}
+		return {
+			ok: false,
+			reason: "missing-target",
+			message: "SuperDoc v2 collaboration requires a collaboration target ({ documentId, serverUrl } or { providerType, ... }). None was provided."
+		};
+	}
+	const candidate = v2Collaboration;
+	if (Object.prototype.hasOwnProperty.call(candidate, "createIfMissing")) return {
+		ok: false,
+		reason: "invalid-room-mode",
+		message: "SuperDoc v2 collaboration createIfMissing has been removed. Use roomMode: \"create\" for creation or roomMode: \"join\" for normal opens."
+	};
+	if (candidate.ydoc != null || candidate.provider != null) return {
+		ok: false,
+		reason: "unsupported-legacy-provider",
+		message: "SuperDoc v2 collaboration cannot use an external { ydoc, provider } pair. v2 owns its provider; pass a collaboration target ({ providerType, documentId, serverUrl | publicApiKey | authEndpoint }) instead."
+	};
+	const providerType = readProviderType(candidate);
+	if (providerType === null || providerType === "y-websocket") return resolveWebsocketFamily("y-websocket", candidate);
+	if (providerType === "hocuspocus") return resolveWebsocketFamily("hocuspocus", candidate);
+	if (providerType === "liveblocks") return resolveLiveblocksFamily(candidate, authEndpointBaseUrl);
+	if (providerType === "extension") return resolveProviderExtension(candidate);
+	return {
+		ok: false,
+		reason: "unsupported-provider-family",
+		message: `SuperDoc v2 collaboration does not support the "${providerType}" provider family. Supported families are y-websocket, hocuspocus, liveblocks, and extension.`
+	};
+}
+//#endregion
 //#region src/core/helpers/file.js
 /**
 * @typedef {Object} UploadWrapper
@@ -5434,6 +5702,14 @@ var GENERIC_BINARY_MIME = "application/octet-stream";
 * @returns {DocumentEntry|any} A normalized entry, or the original value when it is unsupported or unchanged
 */
 var normalizeDocumentEntry = (entry) => {
+	if (entry && typeof entry === "object" && Object.prototype.hasOwnProperty.call(entry, "collaboration")) {
+		const source = { ...entry };
+		delete source.collaboration;
+		entry = {
+			...source,
+			v2Collaboration: readCollaborationConfig(entry)
+		};
+	}
 	if (isDocumentByteSource(entry)) return {
 		type: DOCX,
 		data: documentByteSourceToUint8Array(entry),
@@ -5455,6 +5731,7 @@ var normalizeDocumentEntry = (entry) => {
 		});
 		else if (hasGenericType && inferredType && typeof Blob === "function" && maybeFile instanceof Blob) data = new Blob([maybeFile], { type });
 		return {
+			...entry.v2Collaboration !== void 0 ? { v2Collaboration: entry.v2Collaboration } : {},
 			type,
 			data,
 			name
@@ -20472,266 +20749,31 @@ function unmarkRuntimeRoot(root) {
 	root.removeAttribute(RUNTIME_ROOT_ATTRIBUTE);
 }
 //#endregion
-//#region src/core/collaboration/resolve-v2-collaboration-target.ts
-/**
-* Redact a connection URL for safe inclusion in diagnostics and artifacts.
-*
-* Strips the query string, fragment, and any embedded credentials (userinfo)
-* because those commonly carry auth tokens. Falls back to a coarse string scrub
-* when the value is not a parseable absolute URL so a malformed value with an
-* inline `?token=...` still cannot leak.
-*/
-function redactCollaborationUrl(url) {
-	if (typeof url !== "string" || url.length === 0) return "<none>";
-	try {
-		const parsed = new URL(url);
-		parsed.search = "";
-		parsed.hash = "";
-		parsed.username = "";
-		parsed.password = "";
-		const redactedQuery = url.includes("?") ? "?<redacted>" : "";
-		return `${parsed.toString().replace(/\?$/, "")}${redactedQuery}`;
-	} catch {
-		const withoutCredentials = url.replace(/\/\/[^/@]+@/, "//");
-		const cut = withoutCredentials.search(/[?#]/);
-		if (cut === -1) return withoutCredentials;
-		return `${withoutCredentials.slice(0, cut)}?<redacted>`;
-	}
-}
-function normalizeNonEmptyString(value) {
-	return typeof value === "string" && value.length > 0 ? value : null;
-}
-function normalizeWebsocketUrl(value) {
-	if (typeof value !== "string" || value.length === 0) return null;
-	try {
-		const parsed = new URL(value);
-		return parsed.protocol === "ws:" || parsed.protocol === "wss:" ? value : null;
-	} catch {
-		return null;
-	}
-}
-function normalizeHttpUrl(value, baseUrl) {
-	if (typeof value !== "string") return null;
-	const normalized = value.trim();
-	if (normalized.length === 0) return null;
-	try {
-		const parsed = new URL(normalized);
-		return parsed.protocol === "http:" || parsed.protocol === "https:" ? normalized : null;
-	} catch {
-		if (typeof baseUrl !== "string" || baseUrl.trim().length === 0) return null;
-		try {
-			const parsed = new URL(normalized, baseUrl);
-			return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
-		} catch {
-			return null;
-		}
-	}
-}
-function normalizeParams(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
-	const params = {};
-	for (const [key, raw] of Object.entries(value)) if (typeof raw === "string") params[key] = raw;
-	return Object.keys(params).length > 0 ? params : void 0;
-}
-function normalizeRoomMode(value) {
-	if (value === void 0) return "join";
-	return value === "join" || value === "create" ? value : null;
-}
-function invalidRoomMode() {
-	return {
-		ok: false,
-		reason: "invalid-room-mode",
-		message: "SuperDoc v2 collaboration roomMode must be either \"join\" or \"create\"."
-	};
-}
-/** Provider-family token recognized on a v2Collaboration config object. */
-function readProviderType(candidate) {
-	const raw = candidate.providerType;
-	return typeof raw === "string" && raw.length > 0 ? raw.toLowerCase() : null;
-}
-/**
-* Detect whether a legacy collaboration block names a provider family that the
-* shipped single-doc v2 runtime cannot drive. Returns the offending family name
-* (for diagnostics) or `null` when the block carries no recognizable family.
-*/
-function detectUnsupportedLegacyFamily(legacy) {
-	if (!legacy || typeof legacy !== "object") return null;
-	const providerType = typeof legacy.providerType === "string" ? legacy.providerType.toLowerCase() : "";
-	if (providerType === "hocuspocus") return "hocuspocus";
-	if (providerType === "liveblocks") return "liveblocks";
-	if (providerType === "superdoc") return "superdoc";
-	if (legacy.ydoc != null || legacy.provider != null) return "external-ydoc-provider";
-	return null;
-}
-/** Resolve a websocket-backed family (y-websocket / Hocuspocus). */
-function resolveWebsocketFamily(family, candidate) {
-	const documentId = normalizeNonEmptyString(candidate.documentId);
-	if (!documentId) return {
-		ok: false,
-		reason: "invalid-document-id",
-		message: `SuperDoc v2 collaboration requires a non-empty v2Collaboration.documentId for the "${family}" provider.`
-	};
-	const rawUrl = candidate.url ?? candidate.serverUrl;
-	const serverUrl = normalizeWebsocketUrl(rawUrl);
-	if (!serverUrl) return {
-		ok: false,
-		reason: "invalid-server-url",
-		message: `SuperDoc v2 collaboration requires a valid ws:// or wss:// URL for the "${family}" provider (received: ${redactCollaborationUrl(rawUrl)}).`
-	};
-	const params = normalizeParams(candidate.params);
-	const token = family === "hocuspocus" && typeof candidate.token === "function" ? candidate.token : family === "hocuspocus" ? normalizeNonEmptyString(candidate.token) : null;
-	const roomMode = normalizeRoomMode(candidate.roomMode);
-	if (!roomMode) return invalidRoomMode();
-	return {
-		ok: true,
-		target: {
-			providerFamily: family,
-			documentId,
-			roomMode,
-			serverUrl,
-			...params ? { params } : {},
-			...token ? { token } : {}
-		}
-	};
-}
-function resolveProviderExtension(candidate) {
-	const adapterId = normalizeNonEmptyString(candidate.adapterId);
-	if (!adapterId) return {
-		ok: false,
-		reason: "invalid-adapter-id",
-		message: "SuperDoc v2 provider extensions require a non-empty v2Collaboration.adapterId."
-	};
-	const documentId = normalizeNonEmptyString(candidate.documentId);
-	if (!documentId) return {
-		ok: false,
-		reason: "invalid-document-id",
-		message: "SuperDoc v2 provider extensions require a non-empty v2Collaboration.documentId."
-	};
-	const roomMode = normalizeRoomMode(candidate.roomMode);
-	if (!roomMode) return invalidRoomMode();
-	if (Object.prototype.hasOwnProperty.call(candidate, "providerOptions")) try {
-		structuredClone(candidate.providerOptions);
-	} catch {
-		return {
-			ok: false,
-			reason: "invalid-provider-options",
-			message: "SuperDoc v2 provider extension options must be structured-clone-safe."
-		};
-	}
-	const token = typeof candidate.token === "function" ? candidate.token : normalizeNonEmptyString(candidate.token);
-	return {
-		ok: true,
-		target: {
-			providerFamily: "extension",
-			adapterId,
-			documentId,
-			roomMode,
-			...Object.prototype.hasOwnProperty.call(candidate, "providerOptions") ? { providerOptions: candidate.providerOptions } : {},
-			...token ? { token } : {}
-		}
-	};
-}
-/** Resolve the Liveblocks family (exactly one of publicApiKey / authEndpoint). */
-function resolveLiveblocksFamily(candidate, authEndpointBaseUrl) {
-	const documentId = normalizeNonEmptyString(candidate.documentId ?? candidate.roomId);
-	if (!documentId) return {
-		ok: false,
-		reason: "invalid-document-id",
-		message: "SuperDoc v2 collaboration requires a non-empty v2Collaboration.documentId (or roomId) for the \"liveblocks\" provider."
-	};
-	const publicApiKey = normalizeNonEmptyString(candidate.publicApiKey);
-	const roomMode = normalizeRoomMode(candidate.roomMode);
-	if (!roomMode) return invalidRoomMode();
-	const authEndpointRaw = candidate.authEndpoint;
-	const hasAuthEndpoint = typeof authEndpointRaw === "string" && authEndpointRaw.length > 0;
-	if (!publicApiKey && !hasAuthEndpoint) return {
-		ok: false,
-		reason: "missing-auth",
-		message: "SuperDoc v2 Liveblocks collaboration requires exactly one auth mode: a publicApiKey or an authEndpoint. None was provided."
-	};
-	if (publicApiKey && hasAuthEndpoint) return {
-		ok: false,
-		reason: "mixed-auth",
-		message: "SuperDoc v2 Liveblocks collaboration accepts exactly one auth mode; pass either publicApiKey or authEndpoint, not both."
-	};
-	if (publicApiKey) return {
-		ok: true,
-		target: {
-			providerFamily: "liveblocks",
-			documentId,
-			roomMode,
-			publicApiKey
-		}
-	};
-	const authEndpoint = normalizeHttpUrl(authEndpointRaw, authEndpointBaseUrl);
-	if (!authEndpoint) return {
-		ok: false,
-		reason: "invalid-auth-endpoint",
-		message: "SuperDoc v2 Liveblocks collaboration requires a valid http(s) authEndpoint URL (received: <redacted>)."
-	};
-	return {
-		ok: true,
-		target: {
-			providerFamily: "liveblocks",
-			documentId,
-			roomMode,
-			authEndpoint
-		}
-	};
-}
-/**
-* Resolve a constructor-time or upgrade-time collaboration request into a
-* supported v2 room target, or a stable redacted diagnostic.
-*/
-function resolveV2CollaborationTarget(input) {
-	const { v2Collaboration, legacyCollaboration, documentType, documentCount, authEndpointBaseUrl } = input;
-	if (typeof documentCount === "number" && documentCount > 1) return {
-		ok: false,
-		reason: "unsupported-multi-document",
-		message: `SuperDoc v2 collaboration supports exactly one document per room; received ${documentCount}.`
-	};
-	if (documentType != null && documentType !== "application/vnd.openxmlformats-officedocument.wordprocessingml.document") return {
-		ok: false,
-		reason: "unsupported-document-type",
-		message: "SuperDoc v2 collaboration supports DOCX documents only."
-	};
-	if (!(v2Collaboration != null && typeof v2Collaboration === "object")) {
-		const family = detectUnsupportedLegacyFamily(legacyCollaboration);
-		if (family) {
-			const reason = family === "external-ydoc-provider" ? "unsupported-legacy-provider" : "unsupported-provider-family";
-			const redactedUrl = redactCollaborationUrl(legacyCollaboration?.url);
-			return {
-				ok: false,
-				reason,
-				message: family === "external-ydoc-provider" ? "SuperDoc v2 collaboration cannot use an external { ydoc, provider } pair. Provide a v2Collaboration target (e.g. { providerType, documentId, url }) instead." : `SuperDoc v2 collaboration does not accept "${family}" through the legacy modules.collaboration block (server: ${redactedUrl}). Configure it as a v2Collaboration target ({ providerType: "${family}", documentId, ... }) instead.`
-			};
-		}
-		return {
-			ok: false,
-			reason: "missing-target",
-			message: "SuperDoc v2 collaboration requires a v2Collaboration target ({ documentId, serverUrl } or { providerType, ... }). None was provided."
-		};
+//#region src/core/collaboration/collaboration-exception.ts
+function createCollaborationException(code, documentId) {
+	let collaborationReason;
+	let message;
+	switch (code) {
+		case "collaboration-access-denied":
+			collaborationReason = "access-denied";
+			message = "The collaboration server rejected access to this room.";
+			break;
+		case "collaboration-connection-failed":
+			collaborationReason = "connection-failed";
+			message = "The collaboration connection failed.";
+			break;
+		case "collaboration-sync-timeout":
+			collaborationReason = "sync-timeout";
+			message = "The collaboration room did not finish synchronizing in time.";
+			break;
+		default: return null;
 	}
-	const candidate = v2Collaboration;
-	if (Object.prototype.hasOwnProperty.call(candidate, "createIfMissing")) return {
-		ok: false,
-		reason: "invalid-room-mode",
-		message: "SuperDoc v2 collaboration createIfMissing has been removed. Use roomMode: \"create\" for creation or roomMode: \"join\" for normal opens."
-	};
-	if (candidate.ydoc != null || candidate.provider != null) return {
-		ok: false,
-		reason: "unsupported-legacy-provider",
-		message: "SuperDoc v2 collaboration cannot use an external { ydoc, provider } pair. v2 owns its provider; pass a v2Collaboration target ({ providerType, documentId, url | publicApiKey | authEndpoint }) instead."
-	};
-	const providerType = readProviderType(candidate);
-	if (providerType === null || providerType === "y-websocket") return resolveWebsocketFamily("y-websocket", candidate);
-	if (providerType === "hocuspocus") return resolveWebsocketFamily("hocuspocus", candidate);
-	if (providerType === "liveblocks") return resolveLiveblocksFamily(candidate, authEndpointBaseUrl);
-	if (providerType === "extension") return resolveProviderExtension(candidate);
 	return {
-		ok: false,
-		reason: "unsupported-provider-family",
-		message: `SuperDoc v2 collaboration does not support the "${providerType}" provider family. Supported families are y-websocket, hocuspocus, liveblocks, and extension.`
+		error: new Error(message),
+		code,
+		collaborationReason,
+		documentId,
+		editor: null
 	};
 }
 //#endregion
@@ -22950,7 +22992,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 				case "worker-init-failed": return "SuperDoc could not load the document editor because the browser worker failed to start.";
 				case "input-too-large-for-inline-review": return "SuperDoc could not load the document editor because this document is too large to open without the browser worker.";
 				case "collaboration-unsupported-huge-document": return "SuperDoc could not load the document editor because large documents cannot be opened with collaboration enabled yet.";
-				case "collaboration-v1-config-unsupported": return "SuperDoc v2 cannot use modules.collaboration because it is the SuperDoc v1 collaboration API. SuperDoc did not attach the provider or change the document. Configure Document.v2Collaboration with a v2 room instead.";
+				case "collaboration-v1-config-unsupported": return "SuperDoc v2 cannot use modules.collaboration because it is the SuperDoc v1 collaboration API. SuperDoc did not attach the provider or change the document. Configure Document.collaboration with a v2 room instead.";
 				case "collaboration-room-format-unsupported": return "SuperDoc v2 cannot open this collaboration state because it is not stored in the SuperDoc v2 room format. No changes were made.";
 				case "collaboration-room-format-conflict": return "SuperDoc v2 found conflicting room formats in one collaboration document. No changes were made.";
 				case "collaboration-room-corrupt": return "SuperDoc v2 found a structurally invalid collaboration room. No changes were made.";
@@ -22968,7 +23010,8 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			const reason = typeof payload?.reason === "string" && payload.reason.length > 0 ? payload.reason : "open-failed";
 			const detail = normalizeV2EditorFailureDetail(payload?.detail);
 			const documentId = typeof payload?.documentId === "string" && payload.documentId.length > 0 ? payload.documentId : null;
-			const message = getV2EditorFailureMessage(reason);
+			const collaborationException = createCollaborationException(reason, documentId);
+			const message = collaborationException?.error.message ?? getV2EditorFailureMessage(reason);
 			const workerFailure = payload?.workerFailure && typeof payload.workerFailure === "object" ? payload.workerFailure : null;
 			setV2EditorFailure(documentId, {
 				reason,
@@ -22984,7 +23027,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			};
 			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);
 			else console.error(`[SuperDoc] ${message}`, logContext);
-			proxy.$superdoc.emit("exception", {
+			proxy.$superdoc.emit("exception", collaborationException ?? {
 				error: new Error(message),
 				code: reason,
 				...documentId ? { documentId } : {},
@@ -24208,7 +24251,7 @@ var SuperDoc_default = /*#__PURE__*/ require__plugin_vue_export_helper._plugin_v
 			], 38);
 		};
 	}
-}, [["__scopeId", "data-v-f0b56abb"]]);
+}, [["__scopeId", "data-v-ebe9a1fb"]]);
 //#endregion
 //#region src/core/create-app.js
 var PINIA_DEVTOOLS_SETUP_EVENT = "devtools-plugin:setup";
@@ -45399,7 +45442,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.13.0-next.7";
+		this.version = "2.13.0-next.9";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -46269,8 +46312,10 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			ydoc: options.ydoc,
 			provider: options.provider
 		} : collaborationModule ? { ...collaborationModule } : null;
+		const v2Collaboration = options.v2Collaboration ?? this.#unwrapMaybeRef(configDoc.v2Collaboration) ?? collaborationModule?.v2Collaboration ?? collaborationModule?.v2 ?? null;
 		const resolution = resolveV2CollaborationTarget({
-			v2Collaboration: options.v2Collaboration ?? this.#unwrapMaybeRef(configDoc.v2Collaboration) ?? collaborationModule?.v2Collaboration ?? collaborationModule?.v2 ?? null,
+			collaboration: options.collaboration,
+			v2Collaboration,
 			legacyCollaboration,
 			documentType: DOCX,
 			documentCount: cfg.documents.length,