superdoc 2.16.1-next.2 → 2.16.1-next.4

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.16.1-next.2",
+	superdocVersion: "2.16.1-next.4",
 	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.16.1-next.2",
+	superdocVersion: "2.16.1-next.4",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/clear-content/clear-content.d.ts

@@ -1,5 +1,5 @@
 import { Receipt } from '../types/receipt.js';
-import { RevisionGuardOptions } from '../write/write.js';
+import { MutationOptions } from '../write/write.js';
 export type ClearContentInput = Record<string, never>;
 /**
  * Engine-specific adapter that clears all document body content.
@@ -8,18 +8,14 @@ export interface ClearContentAdapter {
     /**
      * Clear the document body, replacing all content with a single empty paragraph.
      */
-    clearContent(input: ClearContentInput, options?: RevisionGuardOptions): Receipt;
+    clearContent(input: ClearContentInput, options?: MutationOptions): Receipt;
 }
 /**
  * Execute a clearContent operation through the provided adapter.
  *
- * clearContent is a destructive reset: tracked mode and dry run are not
- * meaningful, so this accepts {@link RevisionGuardOptions} rather than
- * `MutationOptions`.
- *
  * @param adapter - Engine-specific clear-content adapter.
  * @param input - Canonical clear-content input (empty object).
- * @param options - Optional revision guard options.
+ * @param options - Optional change mode, preview and revision guard options.
  * @returns A Receipt indicating success or NO_OP if already empty.
  */
-export declare function executeClearContent(adapter: ClearContentAdapter, input: ClearContentInput, options?: RevisionGuardOptions): Receipt;
+export declare function executeClearContent(adapter: ClearContentAdapter, input: ClearContentInput, options?: MutationOptions): Receipt;

package/dist/document-api/src/contract/operation-definitions.d.ts

@@ -1689,7 +1689,7 @@ export declare const OPERATION_DEFINITIONS: {
     readonly 'create.image': {
         readonly memberPath: "create.image";
         readonly description: "Insert a new image at the target position.";
-        readonly expectedResult: "Returns a CreateImageResult with the new image address. Tracked-mode results include `trackedChangeRefs` pointing at the tracked insertion review entity.";
+        readonly expectedResult: "Returns a CreateImageResult with the new image address. Tracked-mode results include `trackedChangeRefs` pointing at the tracked insertion review entity. When the target is an inherited or missing header/footer slot, Word-compatible ownership materialization applies immediately; review controls the inserted image.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
         readonly referenceDocPath: "create/image.mdx";

package/dist/document-api/src/contract/operation-registry.d.ts

@@ -138,7 +138,7 @@ export interface OperationRegistry extends FormatInlineAliasOperationRegistry {
     };
     clearContent: {
         input: ClearContentInput;
-        options: RevisionGuardOptions;
+        options: MutationOptions;
         output: Receipt;
     };
     insert: {

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

@@ -111,4 +111,6 @@ export type DiffChangeMode = 'direct' | 'tracked';
 /** Options for `diff.apply`. Omitted `changeMode` applies story content directly. */
 export interface DiffApplyOptions {
     changeMode?: DiffChangeMode;
+    /** Requires the current document revision; a mismatch fails before any diff operation applies. */
+    expectedRevision?: string;
 }

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

@@ -34,7 +34,7 @@ export interface HyperlinkSpec {
     tooltip?: string;
     /** Link target frame (_blank, _self, etc.). */
     target?: string;
-    /** Relationship attribute string. */
+    /** Browser relationship tokens kept for the current editing session; not persisted in DOCX or reviewed by Word. */
     rel?: string;
 }
 /**
@@ -49,15 +49,17 @@ export interface HyperlinkPatch {
     docLocation?: string | null;
     tooltip?: string | null;
     target?: string | null;
+    /** Session-only browser relationship tokens. Null or an empty string clears them; omission preserves them. */
     rel?: string | null;
 }
-/** All readable hyperlink properties: faithfully reports document state. */
+/** Native hyperlink properties and browser metadata for the current editing session. */
 export interface HyperlinkReadProperties {
     href?: string;
     anchor?: string;
     docLocation?: string;
     tooltip?: string;
     target?: string;
+    /** Browser relationship tokens for this session. A fresh DOCX open does not restore them. */
     rel?: string;
 }
 /** Domain payload for discovery items in hyperlinks.list. */

package/dist/document-api/src/index.d.ts

@@ -30,7 +30,7 @@ import { CreateAdapter, CreateApi } from './create/create.js';
 import { BlocksAdapter, BlocksApi } from './blocks/blocks.js';
 import { TableLocator, TableMutationResult, TablesConvertFromTextInput, TablesMoveInput, TablesSplitInput, TablesConvertToTextInput, TablesSetLayoutInput, TablesInsertRowInput, TablesDeleteRowInput, TablesMoveRowInput, TablesSetRowHeightInput, TablesDistributeRowsInput, TablesSetRowOptionsInput, TablesInsertColumnInput, TablesDeleteColumnInput, TablesMoveColumnInput, TablesSetColumnWidthInput, TablesDistributeColumnsInput, TablesInsertCellInput, TablesDeleteCellInput, TablesMergeCellsInput, TablesUnmergeCellsInput, TablesSplitCellInput, TablesSetCellPropertiesInput, TablesSetCellTextInput, TablesSortInput, TablesSetAltTextInput, TablesSetStyleInput, TablesClearStyleInput, TablesSetStyleOptionInput, TablesSetBorderInput, TablesClearBorderInput, TablesApplyBorderPresetInput, TablesSetShadingInput, TablesClearShadingInput, TablesSetTablePaddingInput, TablesSetCellPaddingInput, TablesSetCellSpacingInput, TablesClearCellSpacingInput, TablesApplyStyleInput, TablesSetBordersInput, TablesSetTableOptionsInput, TablesApplyPresetInput, TablesGetInput, TablesGetOutput, TablesGetCellsInput, TablesGetCellsOutput, TablesGetPropertiesInput, TablesGetPropertiesOutput, TablesGetStylesInput, TablesGetStylesOutput, TablesSetDefaultStyleInput, TablesClearDefaultStyleInput } from './types/table-operations.types.js';
 import { TrackChangesAdapter, TrackChangesApi } from './track-changes/track-changes.js';
-import { MutationOptions, RevisionGuardOptions, RichContentMutationOptions, WriteAdapter } from './write/write.js';
+import { MutationOptions, RichContentMutationOptions, WriteAdapter } from './write/write.js';
 import { SelectionMutationAdapter } from './selection-mutation.js';
 import { CapabilitiesAdapter, DocumentApiCapabilities } from './capabilities/capabilities.js';
 import { SDHtmlMarkdownSupportCheckInput, SDHtmlMarkdownSupportCheckResult } from './capabilities/html-markdown-support.js';
@@ -326,7 +326,7 @@ export interface DocumentApi {
     /**
      * Clear all document body content, leaving a single empty paragraph.
      */
-    clearContent(input: ClearContentInput, options?: RevisionGuardOptions): Receipt;
+    clearContent(input: ClearContentInput, options?: MutationOptions): Receipt;
     /**
      * Comment operations.
      */

package/dist/document-api/src/write/write.d.ts

@@ -8,9 +8,8 @@ export type ChangeMode = 'direct' | 'tracked';
  * Shared semantic validation for the `changeMode` mutation option.
  *
  * Error-code policy (v2-tracked-change-decision-error-contract plan, WS3):
- *   - A `changeMode` value of the wrong *type* is a malformed shape and is left
- *     to upstream structural/schema validation (which surfaces
- *     `VALIDATION_ERROR`). This validator does not touch non-string values.
+ *   - A `changeMode` value of the wrong type is a malformed shape and surfaces
+ *     `VALIDATION_ERROR`, including dynamic calls without upstream schema validation.
  *   - A `changeMode` *string* outside the accepted enum is a semantic option
  *     error and fails closed with `INVALID_INPUT`, not the generic
  *     `VALIDATION_ERROR`. This keeps semantic option failures distinct from

package/dist/superdoc/src/core/collaboration/resolve-v2-collaboration-target.d.ts

@@ -20,7 +20,7 @@ export type SupportedV2ProviderFamily = 'y-websocket' | 'hocuspocus' | 'livebloc
  * collaboration room. These strings are part of the diagnostic contract and are
  * safe to assert against in tests; they never carry caller-provided values.
  */
-export type V2CollaborationUnsupportedReason = 'missing-target' | 'invalid-document-id' | 'invalid-server-url' | 'invalid-room-mode' | 'invalid-auth-endpoint' | 'invalid-adapter-id' | 'invalid-provider-options' | 'missing-auth' | 'mixed-auth' | 'unsupported-document-type' | 'unsupported-multi-document' | 'unsupported-legacy-provider' | 'unsupported-provider-family';
+export type V2CollaborationUnsupportedReason = 'missing-target' | 'invalid-document-id' | 'invalid-server-url' | 'invalid-room-mode' | 'invalid-auth-endpoint' | 'invalid-adapter-id' | 'invalid-provider-options' | 'invalid-sync-timeout' | 'missing-auth' | 'mixed-auth' | 'unsupported-document-type' | 'unsupported-multi-document' | 'unsupported-legacy-provider' | 'unsupported-provider-family';
 /**
  * Normalized, supported v2 collaboration room target.
  *
@@ -47,6 +47,8 @@ export interface NormalizedV2CollaborationTarget {
     adapterId?: string;
     /** Structured-clone-safe options interpreted by the registered adapter. */
     providerOptions?: unknown;
+    /** Maximum initial synchronization wait in milliseconds. */
+    syncTimeoutMs?: number;
     /** Explicit room operation; join is the default at the untrusted input boundary. */
     roomMode: 'join' | 'create';
 }

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

@@ -644,6 +644,8 @@ export interface V2YWebsocketCollaborationConfig {
      * an auth token). Values are strings.
      */
     params?: Record<string, string> | null;
+    /** Maximum initial synchronization wait in milliseconds. Defaults to 30,000. */
+    syncTimeoutMs?: number;
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }
@@ -660,6 +662,8 @@ export interface V2HocuspocusCollaborationConfig {
     params?: Record<string, string> | null;
     /** Static auth token or resolver invoked for every Hocuspocus connection. */
     token?: string | (() => string | Promise<string>);
+    /** Maximum initial synchronization wait in milliseconds. Defaults to 30,000. */
+    syncTimeoutMs?: number;
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }
@@ -683,6 +687,8 @@ export interface V2LiveblocksCollaborationConfig {
      * page; non-browser SDK/CLI callers must use an absolute HTTP(S) URL.
      */
     authEndpoint?: string;
+    /** Maximum initial synchronization wait in milliseconds. Defaults to 30,000. */
+    syncTimeoutMs?: number;
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }
@@ -697,6 +703,8 @@ export interface V2ProviderExtensionCollaborationConfig {
     providerOptions?: unknown;
     /** Optional host-owned credential resolver available to the adapter. */
     token?: string | (() => string | Promise<string>);
+    /** Maximum initial synchronization wait in milliseconds. Defaults to 30,000. */
+    syncTimeoutMs?: number;
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }

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.16.1-next.2";
+		return "2.16.1-next.4";
 	} catch {
 		return "unknown";
 	}
@@ -5380,6 +5380,20 @@ function normalizeRoomMode(value) {
 	if (value === void 0) return "join";
 	return value === "join" || value === "create" ? value : null;
 }
+function normalizeSyncTimeoutMs(value) {
+	if (value === void 0) return void 0;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 2147483647 ? value : null;
+}
+function withSyncTimeout(resolution, syncTimeoutMs) {
+	if (!resolution.ok || syncTimeoutMs === void 0) return resolution;
+	return {
+		ok: true,
+		target: {
+			...resolution.target,
+			syncTimeoutMs
+		}
+	};
+}
 function invalidRoomMode() {
 	return {
 		ok: false,
@@ -5567,11 +5581,17 @@ function resolveV2CollaborationTarget(input) {
 		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 syncTimeoutMs = normalizeSyncTimeoutMs(candidate.syncTimeoutMs);
+	if (syncTimeoutMs === null) return {
+		ok: false,
+		reason: "invalid-sync-timeout",
+		message: "SuperDoc v2 collaboration syncTimeoutMs must be a finite positive number within the JavaScript timer range."
+	};
 	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);
+	if (providerType === null || providerType === "y-websocket") return withSyncTimeout(resolveWebsocketFamily("y-websocket", candidate), syncTimeoutMs);
+	if (providerType === "hocuspocus") return withSyncTimeout(resolveWebsocketFamily("hocuspocus", candidate), syncTimeoutMs);
+	if (providerType === "liveblocks") return withSyncTimeout(resolveLiveblocksFamily(candidate, authEndpointBaseUrl), syncTimeoutMs);
+	if (providerType === "extension") return withSyncTimeout(resolveProviderExtension(candidate), syncTimeoutMs);
 	return {
 		ok: false,
 		reason: "unsupported-provider-family",
@@ -45690,7 +45710,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.16.1-next.2";
+		this.version = "2.16.1-next.4";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];
@@ -46351,11 +46371,13 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		storeDoc.v2Collaboration = value;
 	}
 	#toV2CollaborationConfig(target) {
+		const syncTimeoutOption = target.syncTimeoutMs === void 0 ? {} : { syncTimeoutMs: target.syncTimeoutMs };
 		if (target.providerFamily === "extension") return {
 			providerType: "extension",
 			adapterId: target.adapterId,
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.providerOptions !== void 0 ? { providerOptions: target.providerOptions } : {},
 			...target.token ? { token: target.token } : {}
 		};
@@ -46363,6 +46385,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			providerType: "liveblocks",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.publicApiKey ? { publicApiKey: target.publicApiKey } : {},
 			...target.authEndpoint ? { authEndpoint: target.authEndpoint } : {}
 		};
@@ -46370,6 +46393,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			providerType: "hocuspocus",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.serverUrl ? { serverUrl: target.serverUrl } : {},
 			...target.params ? { params: target.params } : {},
 			...target.token ? { token: target.token } : {}
@@ -46378,6 +46402,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 			providerType: "y-websocket",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.serverUrl ? { serverUrl: target.serverUrl } : {},
 			...target.params ? { params: target.params } : {}
 		};

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.16.1-next.2";
+		return "2.16.1-next.4";
 	} catch {
 		return "unknown";
 	}
@@ -5379,6 +5379,20 @@ function normalizeRoomMode(value) {
 	if (value === void 0) return "join";
 	return value === "join" || value === "create" ? value : null;
 }
+function normalizeSyncTimeoutMs(value) {
+	if (value === void 0) return void 0;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 2147483647 ? value : null;
+}
+function withSyncTimeout(resolution, syncTimeoutMs) {
+	if (!resolution.ok || syncTimeoutMs === void 0) return resolution;
+	return {
+		ok: true,
+		target: {
+			...resolution.target,
+			syncTimeoutMs
+		}
+	};
+}
 function invalidRoomMode() {
 	return {
 		ok: false,
@@ -5566,11 +5580,17 @@ function resolveV2CollaborationTarget(input) {
 		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 syncTimeoutMs = normalizeSyncTimeoutMs(candidate.syncTimeoutMs);
+	if (syncTimeoutMs === null) return {
+		ok: false,
+		reason: "invalid-sync-timeout",
+		message: "SuperDoc v2 collaboration syncTimeoutMs must be a finite positive number within the JavaScript timer range."
+	};
 	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);
+	if (providerType === null || providerType === "y-websocket") return withSyncTimeout(resolveWebsocketFamily("y-websocket", candidate), syncTimeoutMs);
+	if (providerType === "hocuspocus") return withSyncTimeout(resolveWebsocketFamily("hocuspocus", candidate), syncTimeoutMs);
+	if (providerType === "liveblocks") return withSyncTimeout(resolveLiveblocksFamily(candidate, authEndpointBaseUrl), syncTimeoutMs);
+	if (providerType === "extension") return withSyncTimeout(resolveProviderExtension(candidate), syncTimeoutMs);
 	return {
 		ok: false,
 		reason: "unsupported-provider-family",
@@ -45621,7 +45641,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.16.1-next.2";
+		this.version = "2.16.1-next.4";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];
@@ -46282,11 +46302,13 @@ var SuperDoc = class extends import_eventemitter3.default {
 		storeDoc.v2Collaboration = value;
 	}
 	#toV2CollaborationConfig(target) {
+		const syncTimeoutOption = target.syncTimeoutMs === void 0 ? {} : { syncTimeoutMs: target.syncTimeoutMs };
 		if (target.providerFamily === "extension") return {
 			providerType: "extension",
 			adapterId: target.adapterId,
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.providerOptions !== void 0 ? { providerOptions: target.providerOptions } : {},
 			...target.token ? { token: target.token } : {}
 		};
@@ -46294,6 +46316,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 			providerType: "liveblocks",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.publicApiKey ? { publicApiKey: target.publicApiKey } : {},
 			...target.authEndpoint ? { authEndpoint: target.authEndpoint } : {}
 		};
@@ -46301,6 +46324,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 			providerType: "hocuspocus",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.serverUrl ? { serverUrl: target.serverUrl } : {},
 			...target.params ? { params: target.params } : {},
 			...target.token ? { token: target.token } : {}
@@ -46309,6 +46333,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 			providerType: "y-websocket",
 			documentId: target.documentId,
 			roomMode: target.roomMode,
+			...syncTimeoutOption,
 			...target.serverUrl ? { serverUrl: target.serverUrl } : {},
 			...target.params ? { params: target.params } : {}
 		};