superdoc 2.0.0-next.27 → 2.0.0-next.28

package/dist/chunks/{create-super-doc-ui-pYMthdDn.cjs → create-super-doc-ui-CZBUMdjl.cjs}

@@ -311,7 +311,8 @@ const SUPERDOC_UI_REASONS = {
 	historyEmpty: "history-empty",
 	searchUnavailable: "search-unavailable",
 	searchInvalidPattern: "search-invalid-pattern",
-	replaceUnsupported: "replace-unsupported"
+	replaceUnsupported: "replace-unsupported",
+	contentControlLocked: "content-control-locked"
 };
 const BUILT_IN_COMMAND_IDS = {
 	bold: "bold",
@@ -2451,6 +2452,31 @@ function createSuperDocUI(options) {
 	let explicitActiveChange = null;
 	let explicitActiveChangeRevision = 0;
 	let queuedTrackChangeNavigationInvalidation = 0;
+	const mirrorTrackedChangeFocusToHost = (next) => {
+		const host = getHost();
+		if (typeof host?.getHandles !== "function") return;
+		const handles = safeCall(() => host.getHandles(), null);
+		const review = handles?.review;
+		if (!review) return;
+		if (next) {
+			if (typeof review.setActiveReviewTarget !== "function") return;
+			const layout = handles?.layout;
+			safeCall(() => review.setActiveReviewTarget({
+				entityType: "trackedChange",
+				entityId: next.id,
+				...next.paintedEntityId ? { paintedEntityId: next.paintedEntityId } : {},
+				origin: "panel",
+				layoutEpoch: typeof layout?.generation === "number" ? layout.generation : 0,
+				story: next.story ?? {
+					kind: "story",
+					storyType: "body"
+				}
+			}), null);
+			return;
+		}
+		if (typeof review.getActiveReviewTarget !== "function" || typeof review.clearActiveReviewTarget !== "function") return;
+		if (safeCall(() => review.getActiveReviewTarget(), null)?.entityType === "trackedChange") safeCall(() => review.clearActiveReviewTarget(), void 0);
+	};
 	const setExplicitActiveChange = (next, options$1) => {
 		explicitActiveChange = next;
 		explicitActiveChangeRevision += 1;
@@ -2464,6 +2490,8 @@ function createSuperDocUI(options) {
 	let lastEffectiveInlineReadKey = null;
 	let pendingEffectiveInlineRead = null;
 	let asyncRefreshScheduled = false;
+	let asyncReadFailureRetryTimer = null;
+	let asyncReadFailureRetryAtMs = 0;
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
@@ -2478,6 +2506,19 @@ function createSuperDocUI(options) {
 		if (typeof queueMicrotask === "function") queueMicrotask(run);
 		else Promise.resolve().then(run);
 	};
+	const ASYNC_READ_FAILURE_RETRY_BASE_MS = 250;
+	const ASYNC_READ_FAILURE_RETRY_MAX_MS = 5e3;
+	const scheduleAsyncReadFailureRetry = (retryAtMs) => {
+		if (disposed) return;
+		if (asyncReadFailureRetryTimer && asyncReadFailureRetryAtMs <= retryAtMs) return;
+		if (asyncReadFailureRetryTimer) clearTimeout(asyncReadFailureRetryTimer);
+		asyncReadFailureRetryAtMs = retryAtMs;
+		asyncReadFailureRetryTimer = setTimeout(() => {
+			asyncReadFailureRetryTimer = null;
+			asyncReadFailureRetryAtMs = 0;
+			if (!disposed) recompute();
+		}, Math.max(0, retryAtMs - Date.now()));
+	};
 	const editorIdentityIds = /* @__PURE__ */ new WeakMap();
 	let editorIdentityCounter = 0;
 	const editorIdentityId = (editor) => {
@@ -2714,7 +2755,7 @@ function createSuperDocUI(options) {
 		const read = host?.getDocumentLoadingSnapshot;
 		if (typeof read !== "function") return "unknown";
 		const stage = safeCall(() => read.call(host), null)?.sourceStage;
-		if (stage === "source-loading") return "loading";
+		if (stage === "opening" || stage === "ready-window" || stage === "source-loading") return "loading";
 		if (stage === "source-complete" || stage === "source-failed" || stage === "source-cancelled") return "complete";
 		return "unknown";
 	};
@@ -2880,17 +2921,24 @@ function createSuperDocUI(options) {
 				token,
 				value: normalize(raw),
 				hasSettled: true,
-				inflightToken: null
+				inflightToken: null,
+				failedToken: null,
+				failureCount: 0,
+				retryAtMs: 0
 			};
 			asyncReads.set(key, settled);
 			return settled;
 		}
 		const prev = asyncReads.get(key);
+		const retryingSameToken = prev?.failedToken === token;
 		asyncReads.set(key, {
 			token: prev?.token ?? null,
 			value: prev?.value ?? null,
 			hasSettled: prev?.hasSettled ?? false,
-			inflightToken: token
+			inflightToken: token,
+			failedToken: retryingSameToken ? token : null,
+			failureCount: retryingSameToken ? prev.failureCount ?? 0 : 0,
+			retryAtMs: 0
 		});
 		Promise.resolve(raw).then((resolved) => {
 			const entry = asyncReads.get(key);
@@ -2899,17 +2947,26 @@ function createSuperDocUI(options) {
 				token,
 				value: normalize(resolved),
 				hasSettled: true,
-				inflightToken: null
+				inflightToken: null,
+				failedToken: null,
+				failureCount: 0,
+				retryAtMs: 0
 			});
 			scheduleAsyncRefresh();
 		}, () => {
 			const entry = asyncReads.get(key);
 			if (!entry || entry.inflightToken !== token) return;
+			const failureCount = entry.failedToken === token ? (entry.failureCount ?? 0) + 1 : 1;
+			const retryDelayMs = Math.min(ASYNC_READ_FAILURE_RETRY_MAX_MS, ASYNC_READ_FAILURE_RETRY_BASE_MS * 2 ** Math.min(failureCount - 1, 8));
+			const retryAtMs = Date.now() + retryDelayMs;
 			asyncReads.set(key, {
 				...entry,
-				inflightToken: null
+				inflightToken: null,
+				failedToken: token,
+				failureCount,
+				retryAtMs
 			});
-			scheduleAsyncRefresh();
+			scheduleAsyncReadFailureRetry(retryAtMs);
 		});
 		return null;
 	};
@@ -2970,6 +3027,17 @@ function createSuperDocUI(options) {
 				status: "pending"
 			};
 		}
+		if (entry?.failedToken === token && entry.inflightToken == null && (entry.retryAtMs ?? 0) > Date.now()) {
+			scheduleAsyncReadFailureRetry(entry.retryAtMs);
+			if (entry.hasSettled) return {
+				value: entry.value,
+				status: "stale"
+			};
+			return {
+				value: null,
+				status: "pending"
+			};
+		}
 		if (!entry && key.startsWith("effInline:") && shouldDeferEffectiveInlineRead(key)) return {
 			value: null,
 			status: "pending"
@@ -3021,6 +3089,9 @@ function createSuperDocUI(options) {
 		reviewMutationReconciler.reset();
 		lastCoordinatorEditor = editor;
 		asyncReads.clear();
+		if (asyncReadFailureRetryTimer) clearTimeout(asyncReadFailureRetryTimer);
+		asyncReadFailureRetryTimer = null;
+		asyncReadFailureRetryAtMs = 0;
 		if (pendingEffectiveInlineRead?.timer) clearTimeout(pendingEffectiveInlineRead.timer);
 		pendingEffectiveInlineRead = null;
 		lastEffectiveInlineReadKey = null;
@@ -3284,22 +3355,29 @@ function createSuperDocUI(options) {
 			activeIds
 		};
 	};
-	const computeActiveContentControlIds = (ccApi, selection$1) => {
+	const computeActiveContentControlLockModes = (ccApi, selection$1) => {
 		if (!ccApi || typeof ccApi.listInRange !== "function") return {
-			ids: [],
+			lockModesById: /* @__PURE__ */ new Map(),
 			status: "ready"
 		};
 		const range = selectionBlockRange(selection$1);
 		if (!range) return {
-			ids: [],
+			lockModesById: /* @__PURE__ */ new Map(),
 			status: "ready"
 		};
 		const { value, status } = readAsync(`contentControls:inRange:${selectionSignature(selection$1)}`, contentToken(), () => ccApi.listInRange(range), (raw) => raw && Array.isArray(raw.items) ? raw.items : []);
 		const rows = value ?? [];
-		const ids = [];
-		for (const row of rows) if (typeof row?.id === "string") ids.push(row.id);
+		const lockModesById = /* @__PURE__ */ new Map();
+		for (const row of rows) if (typeof row?.id === "string") lockModesById.set(row.id, typeof row.lockMode === "string" ? row.lockMode : "unlocked");
+		return {
+			lockModesById,
+			status
+		};
+	};
+	const computeActiveContentControlIds = (ccApi, selection$1) => {
+		const { lockModesById, status } = computeActiveContentControlLockModes(ccApi, selection$1);
 		return {
-			ids,
+			ids: [...lockModesById.keys()],
 			status
 		};
 	};
@@ -3615,14 +3693,20 @@ function createSuperDocUI(options) {
 			frozenProjectedValues = projectedInlineValues;
 			frozenProjectedValuesKey = `${selectionKey(selection$1)}:${contentToken()}`;
 		}
+		const ccApi = doc?.contentControls;
+		const { lockModesById } = computeActiveContentControlLockModes(ccApi, selection$1);
 		const states = {};
-		for (const id of allCommandIds()) states[id] = computeCommandState(id, doc, selection$1, projectedInlineValues);
+		for (const id of allCommandIds()) states[id] = computeCommandState(id, doc, selection$1, projectedInlineValues, lockModesById);
 		return states;
 	};
 	const unavailableRouteReason = (doc) => {
 		if (doc) return SUPERDOC_UI_REASONS.operationUnavailable;
 		return getEditor() ? SUPERDOC_UI_REASONS.documentApiUnavailable : SUPERDOC_UI_REASONS.notReady;
 	};
+	const blocksContentStyling = (lockMode) => lockMode === "contentLocked" || lockMode === "sdtContentLocked";
+	const contentControlLockReason = (lockModesById) => {
+		for (const lockMode of lockModesById.values()) if (blocksContentStyling(lockMode)) return SUPERDOC_UI_REASONS.contentControlLocked;
+	};
 	const trackDecisionReason = (command, supported, readonly, selection$1, doc) => {
 		if (!supported) return command.scope === "all" ? SUPERDOC_UI_REASONS.bulkDecisionsDisabled : unavailableRouteReason(doc);
 		if (readonly) return SUPERDOC_UI_REASONS.documentReadonly;
@@ -3645,7 +3729,7 @@ function createSuperDocUI(options) {
 		if (support && (support.status === "supported" || support.enabled === true)) return void 0;
 		return SUPERDOC_UI_REASONS.bulkDecisionsDisabled;
 	};
-	const computeCommandState = (id, doc, selection$1, projectedInlineValues) => {
+	const computeCommandState = (id, doc, selection$1, projectedInlineValues, lockModesById = /* @__PURE__ */ new Map()) => {
 		if (customCommands.has(id)) return normalizeCommandState({
 			supported: true,
 			enabled: true,
@@ -3720,6 +3804,13 @@ function createSuperDocUI(options) {
 				supported: true,
 				reason: SUPERDOC_UI_REASONS.documentReadonly
 			}, "builtin");
+			const lockReason = contentControlLockReason(lockModesById);
+			if (lockReason) return normalizeCommandState({
+				enabled: false,
+				active: false,
+				supported: true,
+				reason: lockReason
+			}, "builtin");
 			const enabled = selectionBlockIds(selection$1).length > 0 || resolveInlineSelectionTarget(selection$1) != null;
 			return normalizeCommandState({
 				enabled,
@@ -3770,18 +3861,28 @@ function createSuperDocUI(options) {
 			value,
 			reason: SUPERDOC_UI_REASONS.documentReadonly
 		}, "builtin");
-		if (descriptor.inline && !resolveInlineSelectionTarget(selection$1)) return normalizeCommandState(selectionBlockIds(selection$1).length > 0 && typeof getHost()?.setPendingInlineFormat === "function" ? {
-			enabled: true,
-			active,
-			supported: true,
-			value
-		} : {
-			enabled: false,
-			active,
-			supported: true,
-			value,
-			reason: SUPERDOC_UI_REASONS.rangeSelectionRequired
-		}, "builtin");
+		if (descriptor.inline && !resolveInlineSelectionTarget(selection$1)) {
+			const lockReason = contentControlLockReason(lockModesById);
+			if (lockReason) return normalizeCommandState({
+				enabled: false,
+				active,
+				supported: true,
+				value,
+				reason: lockReason
+			}, "builtin");
+			return normalizeCommandState(selectionBlockIds(selection$1).length > 0 && typeof getHost()?.setPendingInlineFormat === "function" ? {
+				enabled: true,
+				active,
+				supported: true,
+				value
+			} : {
+				enabled: false,
+				active,
+				supported: true,
+				value,
+				reason: SUPERDOC_UI_REASONS.rangeSelectionRequired
+			}, "builtin");
+		}
 		if ((descriptor.blockParagraph || descriptor.list) && selectionBlockIds(selection$1).length === 0) return normalizeCommandState({
 			enabled: false,
 			active,
@@ -3795,6 +3896,16 @@ function createSuperDocUI(options) {
 			supported: true,
 			reason: SUPERDOC_UI_REASONS.rangeSelectionRequired
 		}, "builtin");
+		if (descriptor.inline) {
+			const lockReason = contentControlLockReason(lockModesById);
+			if (lockReason) return normalizeCommandState({
+				enabled: false,
+				active,
+				supported: true,
+				value,
+				reason: lockReason
+			}, "builtin");
+		}
 		return normalizeCommandState({
 			enabled: true,
 			active,
@@ -4753,7 +4864,10 @@ function createSuperDocUI(options) {
 	}
 	function executeTrackDecisionCommand(command, payload) {
 		if (command.scope === "id" && payload == null) {
-			if (state.selection.activeChangeIds.length > 1) return executeTrackDecisionTargets(command.kind, state.selection.activeChangeIds);
+			if (state.selection.activeChangeIds.length > 1) return executeTrackDecisionTarget(command.kind, {
+				kind: "ids",
+				ids: state.selection.activeChangeIds
+			}, null);
 			if (state.selection.activeChangeIds.length === 1 && !state.selection.empty && state.selection.selectionTarget) {
 				const route = activeChangePartialDecisionRoute();
 				if (route === "unavailable") return false;
@@ -5025,6 +5139,9 @@ function createSuperDocUI(options) {
 		return true;
 	};
 	const executeClearFormattingCommand = () => {
+		const doc = getDoc();
+		const { lockModesById } = computeActiveContentControlLockModes(doc?.contentControls, state.selection);
+		if (contentControlLockReason(lockModesById)) return false;
 		const immediateResults = [];
 		const settledResults = [];
 		const record = (result) => {
@@ -5040,7 +5157,6 @@ function createSuperDocUI(options) {
 				settledResults.push(Promise.resolve(false));
 			}
 		};
-		const doc = getDoc();
 		const defaultStyleId = getStyleCatalog().cache?.full.defaults.paragraphStyleId ?? DEFAULT_PARAGRAPH_STYLE_ID;
 		const rangeTarget = resolveInlineSelectionTarget(state.selection);
 		if (rangeTarget) {
@@ -5446,7 +5562,7 @@ function createSuperDocUI(options) {
 			const rows = Number(record.rows ?? record.rowCount);
 			const columns = Number(record.columns ?? record.cols ?? record.colCount);
 			if (!Number.isInteger(rows) || rows < 1 || !Number.isInteger(columns) || columns < 1) return false;
-			const caret = readDocumentMode() !== "suggesting" ? collapsedTextAddressFromSelection(state.selection) : null;
+			const caret = collapsedTextAddressFromSelection(state.selection);
 			const at = caret && typeof caret.blockId === "string" ? {
 				kind: "inParagraph",
 				target: paragraphTarget(caret.blockId),
@@ -5595,9 +5711,12 @@ function createSuperDocUI(options) {
 		const route = descriptor.docRoute;
 		if (!route) return false;
 		if (descriptor.mutates && readDocumentMode() === "viewing") return false;
-		const op = resolveDocOperation(getDoc(), route);
+		const doc = getDoc();
+		const op = resolveDocOperation(doc, route);
 		if (!op) return false;
 		if (descriptor.inline) {
+			const { lockModesById } = computeActiveContentControlLockModes(doc?.contentControls, state.selection);
+			if (contentControlLockReason(lockModesById)) return false;
 			const target = resolveInlineSelectionTarget(state.selection);
 			if (!target) {
 				if (state.selection.empty === false) return settleCommandExecution(false);
@@ -5855,6 +5974,12 @@ function createSuperDocUI(options) {
 		}
 		const doc = getDoc();
 		if (!doc) return;
+		const targetSelection = selectionSliceFromInfo(selection$1, "ready");
+		const { lockModesById } = computeActiveContentControlLockModes(doc.contentControls, targetSelection);
+		if (contentControlLockReason(lockModesById)) {
+			recompute();
+			return;
+		}
 		const selTarget = selection$1["target"];
 		const selectionTarget = selection$1["selectionTarget"];
 		if (!(selection$1["empty"] === true) && Object.keys(snap.inline).length > 0) {
@@ -6426,6 +6551,7 @@ function createSuperDocUI(options) {
 		setActive: (input) => {
 			if (input == null) {
 				setExplicitActiveChange(null);
+				mirrorTrackedChangeFocusToHost(null);
 				recompute();
 				return true;
 			}
@@ -6435,6 +6561,7 @@ function createSuperDocUI(options) {
 				story: input.story
 			};
 			if (typeof requested.id !== "string" || requested.id.length === 0) return false;
+			const paintedEntityId = requested.id;
 			if (requested.story) {
 				const allStoryItems = readAllStoryTrackChanges();
 				if (!allStoryItems) return false;
@@ -6447,7 +6574,9 @@ function createSuperDocUI(options) {
 				if (!bodyItems.some((item) => readEntityId(item) === publicId)) return false;
 				requested.id = publicId;
 			}
+			if (paintedEntityId !== requested.id) requested.paintedEntityId = paintedEntityId;
 			setExplicitActiveChange(requested);
+			mirrorTrackedChangeFocusToHost(requested);
 			recompute();
 			return true;
 		},
@@ -6466,10 +6595,11 @@ function createSuperDocUI(options) {
 				reason: SUPERDOC_UI_REASONS.targetUnresolved
 			};
 			const previousActiveChange = explicitActiveChange;
-			setExplicitActiveChange(story ? {
+			const requestedActiveChange = story ? {
 				id: changeId,
 				story
-			} : { id: changeId });
+			} : { id: changeId };
+			setExplicitActiveChange(requestedActiveChange);
 			recompute();
 			const optimisticActiveChange = explicitActiveChange;
 			const optimisticRevision = explicitActiveChangeRevision;
@@ -6485,6 +6615,7 @@ function createSuperDocUI(options) {
 				ok: false
 			};
 			if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) rollback();
+			else mirrorTrackedChangeFocusToHost(requestedActiveChange);
 			return result;
 		}
 	};
@@ -6511,12 +6642,13 @@ function createSuperDocUI(options) {
 		const tcApi = getDoc()?.trackChanges;
 		const isAllTarget = target.scope === "all";
 		const isRangeTarget = target.kind === "range";
+		const isMultiIdTarget = target.kind === "ids";
 		if (bulkTrackDecisionBlockedReason({
 			kind,
 			scope: isAllTarget ? "all" : "id"
 		}, tcApi)) return false;
 		const legacyName = isAllTarget ? `${kind}All` : kind;
-		const op = !isRangeTarget && !story && tcApi && typeof tcApi[legacyName] === "function" ? tcApi[legacyName] : null;
+		const op = !isRangeTarget && !isMultiIdTarget && !story && tcApi && typeof tcApi[legacyName] === "function" ? tcApi[legacyName] : null;
 		const decide = tcApi && typeof tcApi.decide === "function" ? tcApi.decide : null;
 		if (!op && !decide) return false;
 		return op ? op.call(tcApi, changeId ?? {}) : decide.call(tcApi, {
@@ -6524,23 +6656,6 @@ function createSuperDocUI(options) {
 			target
 		});
 	};
-	const executeTrackDecisionTargets = (kind, changeIds) => {
-		const immediateResults = [];
-		const settledResults = [];
-		for (const changeId of changeIds) try {
-			const result = settleOperationResult(callTrackDecisionTarget(kind, {
-				kind: "id",
-				id: changeId
-			}, changeId));
-			immediateResults.push(result.immediate);
-			settledResults.push(result.settled);
-		} catch {
-			immediateResults.push(false);
-			settledResults.push(Promise.resolve(false));
-		}
-		pendingCommandSettlement = Promise.all(settledResults).then((results) => combineCommandResults(results));
-		return settleCommandExecution(combineCommandResults(immediateResults));
-	};
 	const contentControlsSub = sliceHandle((s) => s.contentControls);
 	const findContentControl = (id) => {
 		return contentControlsSub.get().items.find((item) => item?.id === id) ?? null;
@@ -7468,6 +7583,11 @@ function createSuperDocUI(options) {
 			clearTimeout(foregroundAsyncRetryTimer);
 			foregroundAsyncRetryTimer = null;
 		}
+		if (asyncReadFailureRetryTimer) {
+			clearTimeout(asyncReadFailureRetryTimer);
+			asyncReadFailureRetryTimer = null;
+			asyncReadFailureRetryAtMs = 0;
+		}
 		if (pendingEffectiveInlineRead?.timer) {
 			clearTimeout(pendingEffectiveInlineRead.timer);
 			pendingEffectiveInlineRead.timer = null;

package/dist/collaboration-upgrade-engine.cjs

@@ -7,7 +7,7 @@ const 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.0.0-next.27",
+	superdocVersion: "2.0.0-next.28",
 	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

@@ -6,7 +6,7 @@ const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.0.0-next.27",
+	superdocVersion: "2.0.0-next.28",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -976,7 +976,7 @@ export declare const OPERATION_DEFINITIONS: {
     };
     readonly 'trackChanges.decide': {
         readonly memberPath: "trackChanges.decide";
-        readonly description: "Accept or reject tracked changes by logical id, by selected text range, by logical anchor range ({ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `{ id, range: { kind: \"partial\", ... } }` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.";
+        readonly description: "Accept or reject tracked changes by logical id, by several logical ids atomically, by selected text range, by logical anchor range ({ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `{ id, range: { kind: \"partial\", ... } }` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.";
         readonly expectedResult: "Returns a Receipt. `removed` lists retired tracked-change ids; `inserted` lists successor fragment ids produced by partial range splits; `invalidatedRefs` lists every retired tracked-change ref plus cascade-deleted comment ids; `remappedRefs` carries surviving comment anchors moved by the decision; `affectedStories` lists touched stories; `textRangeShifts` reports per-story visible-text deltas; `txId` correlates with history. Failures: SPAN_FRAGMENTED when a range crosses an indivisible boundary, CAPABILITY_UNAVAILABLE for formatting / structural / move targets (not yet supported), TARGET_NOT_FOUND for retired ids or zero overlap, STALE_REVISION for stale expectedRevision, REVISION_MISMATCH for stale range coverage, NO_OP when { kind: 'all' } resolves an empty target set.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;

package/dist/document-api/src/track-changes/track-changes.d.ts

@@ -72,6 +72,10 @@ export type ReviewDecideTarget = {
     story?: StoryLocator;
     side?: ReviewDecideIdTargetSide;
     moveRole?: ReviewDecideTargetMoveRole;
+} | {
+    /** Resolve several whole logical changes in one atomic history unit. */
+    kind: 'ids';
+    ids: string[];
 } | ReviewDecideTextRangeTarget | ReviewDecideLogicalRangeTarget | {
     kind: 'all';
     story?: StoryLocator | 'all';
@@ -153,7 +157,7 @@ export declare function executeTrackChangesGet(adapter: TrackChangesAdapter, inp
  * {@link RevisionGuardOptions} rather than `MutationOptions`.
  *
  * Validates the canonical discriminated target shape
- * (`{ kind: 'id' | 'range' | 'all' }`) and transparently promotes the
+ * (`{ kind: 'id' | 'ids' | 'range' | 'all' }`) and transparently promotes the
  * legacy `{ id, story? }` / `{ scope: 'all' }` shapes. Adapters that
  * implement the new {@link TrackChangesAdapter.decide} entrypoint receive
  * the normalized canonical input; older adapters that only expose
@@ -163,7 +167,7 @@ export declare function executeTrackChangesGet(adapter: TrackChangesAdapter, inp
 export declare function executeTrackChangesDecide(adapter: TrackChangesAdapter, rawInput: ReviewDecideInput, options?: RevisionGuardOptions): Receipt;
 /**
  * Validate and normalize a `trackChanges.decide` input into the canonical
- * `{ kind: 'id' | 'range' | 'all' }` target shape. Exposed for adapters /
+ * `{ kind: 'id' | 'ids' | 'range' | 'all' }` target shape. Exposed for adapters /
  * tests that need to share the same validation surface.
  */
 export declare function validateReviewDecideInput(rawInput: ReviewDecideInput): ReviewDecideRangeInput;

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

@@ -75,10 +75,14 @@ export interface SDPasteParagraphBlock {
      * Portable list membership intent. Without `numbering`, the kernel always
      * materializes a fresh definition. With `numbering`, the existing identity
      * is retained when the destination defines the same list kind; otherwise
-     * this intent is the cross-document fallback. Single-level.
+     * this intent is the cross-document fallback. `level` is zero-based and
+     * bounded to OOXML's nine list levels; omitted means level 0.
      */
     listIntent?: {
         kind: 'bullet' | 'ordered';
+        level?: number;
+        /** True on the first block of a distinct adjacent portable list. */
+        startsNewList?: boolean;
     };
     /**
      * Pre-validated direct `<w:pPr>` properties. Same-document copy carries the

package/dist/document-api/src/types/table-operations.types.d.ts

@@ -109,15 +109,17 @@ export type TableAnchorLocation = {
  */
 export type TableCreateLocation = TableAnchorLocation
 /**
- * Split the target paragraph at a visible-text offset and insert the table
- * as a standalone block between the head/tail halves (Word semantics: a
- * table cannot splice into a paragraph's runs). Body paragraphs only for
- * now; `changeMode: 'tracked'` is not supported for this location kind.
+ * Split the target paragraph at an offset and insert the table as a
+ * standalone block between the head/tail halves (Word semantics: a table
+ * cannot splice into a paragraph's runs). Offsets are visible-text by
+ * default; use `coordinateSpace: 'tracked'` for a deletion-inclusive caret
+ * coordinate. Body paragraphs only for now.
  */
  | {
     kind: 'inParagraph';
     target: BlockNodeAddress;
     offset: number;
+    coordinateSpace?: 'visible' | 'tracked';
 };
 /**
  * Generic success result for table mutation operations.

package/dist/document-api/src/types/track-changes.types.d.ts

@@ -448,6 +448,17 @@ export interface TrackChangeImagePreview {
     /** Accessible label for clients that render the preview. */
     alt?: string;
 }
+/**
+ * Authoritative block address for review navigation. Consumers use this
+ * instead of interpreting the shape-specific {@link TrackChangeTarget}
+ * union. `role` records which semantic carrier supplied the address.
+ */
+export interface TrackChangeNavigationTarget {
+    kind: 'block';
+    story: StoryLocator;
+    blockId: string;
+    role: 'primary' | 'move-source' | 'move-destination' | 'formatting-carrier' | 'structural-carrier';
+}
 export interface TrackChangeInfo {
     address: TrackedChangeAddress;
     /** Stable SuperDoc logical tracked-change id (spec §3 / §4). */
@@ -459,6 +470,8 @@ export interface TrackChangeInfo {
     state?: TrackChangeState;
     /** Logical target description. */
     target?: TrackChangeTarget;
+    /** Stable story/block address for focus and virtualized materialization. */
+    navigationTarget?: TrackChangeNavigationTarget;
     /** Semantic before-state needed to reject the change. */
     before?: TrackChangeSnapshot;
     /** Semantic after-state needed to accept the change. */
@@ -598,6 +611,8 @@ export interface TrackChangeDomain {
     state?: TrackChangeState;
     /** Logical target summary for list consumers when the compact projection can provide it safely. */
     target?: TrackChangeTarget;
+    /** Stable story/block address for focus and virtualized materialization. */
+    navigationTarget?: TrackChangeNavigationTarget;
     /** Move side metadata for paired tracked moves. */
     move?: TrackChangeMoveSides;
     /** Direction of a paired move in document order, when source/destination order is known. */

package/dist/layout-engine/contracts/src/incremental-dependency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable dependency classes that an incremental page checkpoint may fence.
+ *
+ * This list is proof metadata, never a feature switch. Producers must name
+ * every retained dependency that required the checkpoint; consumers reject
+ * empty, duplicate, or unknown lists instead of trusting a generic boolean.
+ */
+export type PageCheckpointDependencyClass = 'multiple-sections' | 'furniture-page-tokens' | 'non-balanceable-multi-column-sections' | 'body-anchored-objects' | 'footnotes' | 'page-references' | 'keep-constraints' | 'tables' | 'furniture-anchored-objects';
+export declare const PAGE_CHECKPOINT_DEPENDENCY_CLASSES: readonly ["multiple-sections", "furniture-page-tokens", "non-balanceable-multi-column-sections", "body-anchored-objects", "footnotes", "page-references", "keep-constraints", "tables", "furniture-anchored-objects"];
+export declare function areValidPageCheckpointDependencyClasses(value: unknown): value is readonly PageCheckpointDependencyClass[];