superdoc 2.4.0 → 2.5.0

package/dist/chunks/{create-super-doc-ui-CmOSA_lN.es.js → create-super-doc-ui-DbzVC0rr.es.js}

@@ -13,6 +13,8 @@ var DOM_CLASS_NAMES = {
 	PAGE: "superdoc-page",
 	/** Fragment container (paragraph, table, image block, etc.). */
 	FRAGMENT: "superdoc-fragment",
+	/** Non-flowing fragment whose visual position must not define body flow geometry. */
+	FLOATING_FRAGMENT: "superdoc-floating-fragment",
 	/** Line container within a fragment. */
 	LINE: "superdoc-line",
 	/**
@@ -614,7 +616,6 @@ var SUPERDOC_UI_REASONS = {
 * No descriptor imports a v1 editor internal or a private v2 runtime package,
 * and no routed command mutates while the document is read-only / viewing.
 *
-* See `docs/architecture/custom-ui-command-matrix.md` for the per-id matrix.
 */
 /**
 * The 14 canonical v2-native command ids. These are the historically stable
@@ -1873,6 +1874,23 @@ INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry)
 * `false` when the surface is unavailable (view mode, a pre-ready editor, or a
 * host that has not exposed a Document API facade) rather than throwing.
 */
+function uiBenchNowMs() {
+	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function readUiBenchRuntime() {
+	const benchGlobal = globalThis;
+	return {
+		sink: typeof benchGlobal.__superdocV2BenchPipelineTiming === "function" ? benchGlobal.__superdocV2BenchPipelineTiming : null,
+		workerContext: benchGlobal.__superdocV2BenchWorkerMessageContext ?? null
+	};
+}
+function emitUiBenchTiming(event) {
+	const { sink } = readUiBenchRuntime();
+	if (!sink) return;
+	try {
+		sink(event);
+	} catch {}
+}
 var sharedUiTrackedChangesCatalogByHost = /* @__PURE__ */ new WeakMap();
 function acquireSharedUiTrackedChangesCatalog(host) {
 	let state = sharedUiTrackedChangesCatalogByHost.get(host);
@@ -3702,6 +3720,7 @@ function createSuperDocUI(options) {
 		if (options?.invalidateQueuedNavigation !== false) queuedTrackChangeNavigationInvalidation += 1;
 	};
 	const listeners = /* @__PURE__ */ new Set();
+	let state;
 	let disposed = false;
 	let controllerRef = null;
 	const asyncReads = /* @__PURE__ */ new Map();
@@ -3714,12 +3733,13 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
+	const pendingAsyncReadSettlements = [];
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
 		const run = () => {
 			asyncRefreshScheduled = false;
-			if (!disposed) recompute();
+			if (!disposed) recompute("async-read-settled");
 		};
 		if (typeof queueMicrotask === "function") queueMicrotask(run);
 		else Promise.resolve().then(run);
@@ -4273,6 +4293,24 @@ function createSuperDocUI(options) {
 				failureCount: 0,
 				retryAtMs: 0
 			});
+			const { sink, workerContext } = readUiBenchRuntime();
+			if (sink) {
+				const settledAtMs = uiBenchNowMs();
+				pendingAsyncReadSettlements.push({
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+				emitUiBenchTiming({
+					stage: "superdoc-ui-async-read-settled",
+					atMs: settledAtMs,
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+			}
 			scheduleAsyncRefresh();
 		}, () => {
 			const entry = asyncReads.get(key);
@@ -6533,31 +6571,57 @@ function createSuperDocUI(options) {
 			diagnostics
 		};
 	};
-	const computeState = () => {
-		const documentMode = readDocumentMode();
-		const selection = computeSelection();
+	const computeState = (reason = "direct") => {
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
+		const phaseMs = {};
+		const measure = (phase, run) => {
+			if (!sink) return run();
+			const phaseStartedAtMs = uiBenchNowMs();
+			try {
+				return run();
+			} finally {
+				phaseMs[phase] = uiBenchNowMs() - phaseStartedAtMs;
+			}
+		};
+		const documentMode = measure("documentMode", readDocumentMode);
+		const selection = measure("selection", computeSelection);
 		if (selection.status === "ready") pruneSelectionScopedAsyncReads(selection);
 		reconcilePendingInlineFormat(selection);
 		const selectionSignature = selectionInlineValueSignature(selection);
 		for (const [commandId, optimistic] of optimisticInlineToggles) if (!selectionSignature || optimistic.selectionSignature !== selectionSignature) optimisticInlineToggles.delete(commandId);
 		else if (optimistic.settled && selection.status === "ready") optimisticInlineToggles.delete(commandId);
-		return {
+		const nextState = {
 			ready: getEditor() != null,
 			documentMode,
-			document: computeDocument(),
+			document: measure("document", computeDocument),
 			selection,
 			toolbar: {
 				context: documentMode,
-				commands: computeCommandStates(selection),
+				commands: measure("toolbarCommands", () => computeCommandStates(selection)),
 				copyFormatActive: painter.mode !== "idle"
 			},
-			comments: computeComments(selection),
-			trackChanges: computeTrackChanges(selection),
-			contentControls: computeContentControls(selection),
-			zoom: computeZoom(),
-			fonts: computeFonts(),
-			styles: computeStyles(selection)
-		};
+			comments: measure("comments", () => computeComments(selection)),
+			trackChanges: measure("trackChanges", () => computeTrackChanges(selection)),
+			contentControls: measure("contentControls", () => computeContentControls(selection)),
+			zoom: measure("zoom", computeZoom),
+			fonts: measure("fonts", computeFonts),
+			styles: measure("styles", () => computeStyles(selection))
+		};
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-compute-state",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				phaseMs,
+				asyncReadSettlements: pendingAsyncReadSettlements.splice(0)
+			});
+		}
+		return nextState;
 	};
 	const syncOptimisticInlineSelection = (selection) => {
 		const nextSignature = selectionInlineValueSignature(selection);
@@ -6642,7 +6706,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				selectionEpoch += 1;
 				seedCaretSelectionFromHost(snapshot);
-				recompute();
+				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
 		} catch {
@@ -6667,15 +6731,24 @@ function createSuperDocUI(options) {
 		const target = rawTarget && typeof rawTarget === "object" ? rawTarget : null;
 		let next = null;
 		if (target?.entityType === "trackedChange" && typeof target.entityId === "string" && target.entityId.length > 0) {
-			const paintedEntityId = target.entityId;
 			const targetStory = target.story && typeof target.story === "object" ? target.story : void 0;
-			const allStoryItems = readAllStoryTrackChanges();
-			const entityId = (allStoryItems ? targetStory ? buildStoryScopedTrackedChangeIdContext(allStoryItems, targetStory).toPublicId(paintedEntityId) : buildTrackedChangeIdContext(allStoryItems).toPublicId(paintedEntityId) : null) ?? paintedEntityId;
 			const story = targetStory && storyLocatorSignature(targetStory) !== storyLocatorSignature(null) ? targetStory : void 0;
+			const rawPaintedEntityId = typeof target.paintedEntityId === "string" && target.paintedEntityId.length > 0 ? target.paintedEntityId : null;
+			const lookupEntityId = rawPaintedEntityId ?? target.entityId;
+			const publicId = (() => {
+				if (story) {
+					const allStoryItems = readAllStoryTrackChanges();
+					const storyContext = allStoryItems ? buildStoryScopedTrackedChangeIdContext(allStoryItems, story) : null;
+					return storyContext?.toPublicId(lookupEntityId) ?? storyContext?.toPublicId(target.entityId) ?? target.entityId;
+				}
+				const bodyContext = buildTrackedChangeIdContext(Array.isArray(state?.trackChanges.items) ? state.trackChanges.items : []);
+				return bodyContext.toPublicId(lookupEntityId) ?? bodyContext.toPublicId(target.entityId) ?? target.entityId;
+			})();
+			const paintedEntityId = rawPaintedEntityId ?? (lookupEntityId !== publicId ? lookupEntityId : null);
 			next = {
-				id: entityId,
+				id: publicId,
 				...story ? { story } : {},
-				...typeof target.paintedEntityId === "string" && target.paintedEntityId.length > 0 ? { paintedEntityId: target.paintedEntityId } : entityId !== paintedEntityId ? { paintedEntityId } : {}
+				...paintedEntityId && paintedEntityId !== publicId ? { paintedEntityId } : {}
 			};
 		}
 		if (rawTarget == null && next == null && explicitActiveChange != null && hasPendingTrackChangeRevealFocus(explicitActiveChange)) return false;
@@ -6741,7 +6814,7 @@ function createSuperDocUI(options) {
 	};
 	syncCoordinatorEditor();
 	syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(readHostReviewSource()));
-	let state = computeState();
+	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
 		const events = (getEditor()?.host)?.events;
@@ -6809,8 +6882,10 @@ function createSuperDocUI(options) {
 			currentHostEventsSource = null;
 		}
 	};
-	const recompute = () => {
+	const recompute = (reason = "unspecified") => {
 		if (disposed) return;
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
 		editCommandsRecomputeQueued = false;
 		syncCoordinatorEditor();
 		syncHostSelectionSubscription();
@@ -6819,10 +6894,36 @@ function createSuperDocUI(options) {
 		syncHostReviewSubscription();
 		syncDocumentSelectionFallbackSubscription();
 		syncHostEventsSubscription();
-		const nextState = computeState();
+		const nextState = computeState(reason);
 		syncOptimisticInlineSelection(nextState.selection);
 		state = nextState;
-		for (const listener of [...listeners]) listener(state);
+		let listenerTotalMs = 0;
+		let listenerMaxMs = 0;
+		for (const listener of [...listeners]) {
+			if (!sink) {
+				listener(state);
+				continue;
+			}
+			const listenerStartedAtMs = uiBenchNowMs();
+			listener(state);
+			const listenerMs = uiBenchNowMs() - listenerStartedAtMs;
+			listenerTotalMs += listenerMs;
+			listenerMaxMs = Math.max(listenerMaxMs, listenerMs);
+		}
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-recompute",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				listenerCount: listeners.size,
+				listenerTotalMs,
+				listenerMaxMs
+			});
+		}
 	};
 	/**
 	* Work that is bound to one specific active editor and cannot survive a swap.
@@ -7412,7 +7513,7 @@ function createSuperDocUI(options) {
 		if (options && options.success === false) return options;
 		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
-			...options ?? {},
+			...options,
 			offsetSpace: "selection"
 		});
 	};
@@ -8743,6 +8844,66 @@ function createSuperDocUI(options) {
 		}
 	};
 	/**
+	* Derive the browser-shell's `importedId` carrier-lookup alias from a
+	* public list row's `wordRevisionIds` / `sourceIds` provenance fields,
+	* mirroring `create-v2-tracked-changes-adapter.js`'s own derivation
+	* (`wordRevisionIds.insert ?? .delete ?? .format ?? sourceIds.wordIdInsert
+	* ?? .wordIdDelete ?? .wordIdOther[0]`). A carrier imported from a legacy
+	* Word revision id is painted with THIS id, not the canonical public id —
+	* `focusTrackedChange`'s carrier lookup only tries it when explicitly
+	* passed as `importedId` on an object input (see `scrollTrackChangeIntoView`).
+	*/
+	const deriveTrackedChangeImportedId = (row) => {
+		if (!row || typeof row !== "object") return null;
+		const record = row;
+		const wordRevisionIds = record.wordRevisionIds && typeof record.wordRevisionIds === "object" ? record.wordRevisionIds : null;
+		const sourceIds = record.sourceIds && typeof record.sourceIds === "object" ? record.sourceIds : null;
+		const wordIdOther = Array.isArray(sourceIds?.wordIdOther) ? sourceIds.wordIdOther : void 0;
+		const candidate = wordRevisionIds?.insert ?? wordRevisionIds?.delete ?? wordRevisionIds?.format ?? sourceIds?.wordIdInsert ?? sourceIds?.wordIdDelete ?? wordIdOther?.[0];
+		return typeof candidate === "string" && candidate.length > 0 ? candidate : null;
+	};
+	/**
+	* Scroll a tracked-change target into view, falling back to the v2
+	* browser-shell's `focusTrackedChange` (the same mechanism the built-in
+	* comments/tracked-changes sidebar uses via `CommentDialog.vue`'s
+	* `setFocus`) when the shared host geometry path can't resolve the target.
+	* The host's `normalizeGeometryTarget` only understands `text`/`replacement`
+	* targets (enriched with painted `segments`) and never `structural`/
+	* `formatting` targets, so those always fail the primary path and need this
+	* fallback.
+	*
+	* `story`, when present, is threaded into the fallback input as
+	* `trackedChangeStory` — a bare id always resolves to the body story in
+	* `focusTrackedChange`'s target resolver, which would collapse a non-body
+	* (footnote/header/footer) occurrence onto its body counterpart sharing the
+	* same raw id. `importedId`, when present, is threaded in too: the carrier
+	* lookup (`buildTrackChangeCarrierLookupIds`) tries it as an ADDITIONAL alias
+	* alongside the canonical id, for rows whose painted carrier only matches
+	* through a legacy-imported Word revision id, not the canonical public id
+	* (`create-v2-tracked-changes-adapter.test.js` pins this alias path as
+	* necessary for some rows).
+	*/
+	const scrollTrackChangeIntoView = async (changeId, target, story, importedId, options) => {
+		const primary = await scrollTargetIntoView(target, options);
+		if (primary.ok) return primary;
+		const trackedChanges = getV2TrackedChanges();
+		const focusTrackedChange = trackedChanges?.focusTrackedChange;
+		if (typeof focusTrackedChange !== "function") return primary;
+		const fallbackInput = story || importedId ? {
+			commentId: changeId,
+			...story ? { trackedChangeStory: story } : {},
+			...importedId ? { importedId } : {}
+		} : changeId;
+		try {
+			const fallbackResult = await Promise.resolve(focusTrackedChange.call(trackedChanges, fallbackInput));
+			if (fallbackResult && typeof fallbackResult === "object" && fallbackResult.ok === true) return {
+				success: true,
+				ok: true
+			};
+		} catch {}
+		return primary;
+	};
+	/**
 	* Resolve a document entity (comment / tracked change) to its anchor target.
 	* Prefers the already-loaded list row, falling back to a live `get({ id })`
 	* read when the list does not carry the row.
@@ -9004,9 +9165,11 @@ function createSuperDocUI(options) {
 				rollback();
 				return { success: false };
 			}
+			const activeRow = trackChangesSub.get().items.find((item) => entityRowMatchesRequest(item, activeId, optimisticActiveChange?.story)) ?? trackChangesSub.get().items.find((item) => readEntityId(item) === activeId);
+			const importedId = deriveTrackedChangeImportedId(activeRow);
 			trackedChangeNavigationInFlight += 1;
 			try {
-				const result = await scrollTargetIntoView(target, {
+				const result = await scrollTrackChangeIntoView(activeId, target, optimisticActiveChange?.story, importedId, {
 					behavior: "auto",
 					shouldContinue: isCurrent
 				});
@@ -9130,7 +9293,9 @@ function createSuperDocUI(options) {
 			const requestedAtInvalidation = trackChangeRevealInvalidation;
 			const loadedItems = trackChangesSub.get().items;
 			const publicId = buildTrackedChangeIdContext(loadedItems).toPublicId(changeId) ?? changeId;
-			const story = readEntityRequestStory(loadedItems.find((item) => readEntityId(item) === publicId));
+			const matchingRow = loadedItems.find((item) => readEntityId(item) === publicId);
+			const story = readEntityRequestStory(matchingRow);
+			const importedId = deriveTrackedChangeImportedId(matchingRow);
 			const previousActiveChange = explicitActiveChange;
 			const requestedActiveChange = {
 				id: publicId,
@@ -9162,7 +9327,7 @@ function createSuperDocUI(options) {
 				recompute();
 				trackedChangeNavigationInFlight += 1;
 				try {
-					const result = await scrollTargetIntoView(target, {
+					const result = await scrollTrackChangeIntoView(publicId, target, story, importedId, {
 						behavior: "auto",
 						shouldContinue: isCurrent
 					});

package/dist/chunks/{eventemitter3-DEIiXiH2.es.js → eventemitter3-CMOjDs74.es.js}

@@ -1,4 +1,4 @@
-import { i as __toESM, t as __commonJSMin } from "./rolldown-runtime-0pSA04fp.es.js";
+import { i as __toESM, t as __commonJSMin } from "./rolldown-runtime-B5TtN50X.es.js";
 //#endregion
 //#region ../../node_modules/.pnpm/eventemitter3@5.0.4/node_modules/eventemitter3/index.mjs
 var import_eventemitter3 = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {

package/dist/chunks/{eventemitter3-C_TAnXOl.cjs → eventemitter3-D38u8ta_.cjs}

@@ -1,4 +1,4 @@
-const require_rolldown_runtime = require("./rolldown-runtime-74VwNCz7.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-DtsSbkrh.cjs");
 //#region ../../node_modules/.pnpm/eventemitter3@5.0.4/node_modules/eventemitter3/index.js
 var require_eventemitter3 = /* @__PURE__ */ require_rolldown_runtime.__commonJSMin(((exports, module) => {
 	var has = Object.prototype.hasOwnProperty;

package/dist/chunks/{jszip-D8mAFF-r.cjs → jszip-RC64TPzL.cjs}

@@ -1,4 +1,4 @@
-const require_rolldown_runtime = require("./rolldown-runtime-74VwNCz7.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-DtsSbkrh.cjs");
 //#region ../../node_modules/.pnpm/vite-plugin-node-polyfills@0.28.0_rollup@4.60.2_vite@7.3.1_@types+node@25.6.0_jiti@2.7._79de22fafa9a94a397e22a8c8322f563/node_modules/vite-plugin-node-polyfills/shims/buffer/dist/index.js
 function getLens(b64) {
 	var len = b64.length;

package/dist/chunks/{jszip-BzJ3CyxR.es.js → jszip-VxCFV9YS.es.js}

@@ -1,4 +1,4 @@
-import { n as __esmMin, r as __require, t as __commonJSMin } from "./rolldown-runtime-0pSA04fp.es.js";
+import { n as __esmMin, r as __require, t as __commonJSMin } from "./rolldown-runtime-B5TtN50X.es.js";
 //#region ../../node_modules/.pnpm/vite-plugin-node-polyfills@0.28.0_rollup@4.60.2_vite@7.3.1_@types+node@25.6.0_jiti@2.7._79de22fafa9a94a397e22a8c8322f563/node_modules/vite-plugin-node-polyfills/shims/buffer/dist/index.js
 function getLens(b64) {
 	var len = b64.length;

package/dist/chunks/{rolldown-runtime-0pSA04fp.es.js → rolldown-runtime-B5TtN50X.es.js}

@@ -24,7 +24,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));

package/dist/chunks/{rolldown-runtime-74VwNCz7.cjs → rolldown-runtime-DtsSbkrh.cjs}

@@ -24,7 +24,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));

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.4.0",
+	superdocVersion: "2.5.0",
 	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.4.0",
+	superdocVersion: "2.5.0",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -457,6 +457,16 @@ export interface TrackChangeNavigationTarget {
     blockId: string;
     role: 'primary' | 'move-source' | 'move-destination' | 'formatting-carrier' | 'structural-carrier';
 }
+export interface TrackChangeCustomAttribute {
+    /** Source-qualified attribute name, preserving the prefix used by the carrier. */
+    name: string;
+    /** Resolved extension namespace URI. */
+    namespaceUri: string;
+    /** Attribute local name without its namespace prefix. */
+    localName: string;
+    /** Decoded XML attribute value. */
+    value: string;
+}
 export interface TrackChangeInfo {
     address: TrackedChangeAddress;
     /** Stable SuperDoc logical tracked-change id (spec §3 / §4). */
@@ -569,6 +579,11 @@ export interface TrackChangeInfo {
      * tracked changes. Absent when the change is standalone.
      */
     overlap?: TrackChangeOverlapInfo;
+    /**
+     * Unknown extension attributes attached to contributing OOXML revision carriers.
+     * Exact duplicates are removed in document order; conflicting values are retained.
+     */
+    readonly customAttributes?: readonly TrackChangeCustomAttribute[];
 }
 export interface TrackChangesListQuery {
     limit?: number;
@@ -694,6 +709,8 @@ export interface TrackChangeDomain {
      * stack without an extra `trackChanges.get` round trip.
      */
     overlap?: TrackChangeOverlapInfo;
+    /** Unknown extension attributes attached to the contributing OOXML revision carriers. */
+    readonly customAttributes?: readonly TrackChangeCustomAttribute[];
 }
 /**
  * Standardized discovery output for `trackChanges.list`.

package/dist/layout-engine/contracts/src/graphic-placement.d.ts

@@ -1,7 +1,19 @@
-type AnchorVRelative = 'paragraph' | 'page' | 'margin';
-type AnchorHRelative = 'column' | 'page' | 'margin';
-type AnchorAlignH = 'left' | 'center' | 'right';
-type AnchorAlignV = 'top' | 'center' | 'bottom';
+/** ECMA-376 Part 1 §20.4.3.4 (`ST_RelFromH`). */
+export declare const ANCHOR_H_RELATIVE_VALUES: readonly ["margin", "page", "column", "character", "leftMargin", "rightMargin", "insideMargin", "outsideMargin"];
+/** ECMA-376 Part 1 §20.4.3.5 (`ST_RelFromV`). */
+export declare const ANCHOR_V_RELATIVE_VALUES: readonly ["margin", "page", "paragraph", "line", "topMargin", "bottomMargin", "insideMargin", "outsideMargin"];
+/** ECMA-376 Part 1 §20.4.3.1 (`ST_AlignH`). */
+export declare const ANCHOR_H_ALIGN_VALUES: readonly ["left", "right", "center", "inside", "outside"];
+/** ECMA-376 Part 1 §20.4.3.2 (`ST_AlignV`). */
+export declare const ANCHOR_V_ALIGN_VALUES: readonly ["top", "bottom", "center", "inside", "outside"];
+export type AnchorHRelative = (typeof ANCHOR_H_RELATIVE_VALUES)[number];
+export type AnchorVRelative = (typeof ANCHOR_V_RELATIVE_VALUES)[number];
+export type AnchorAlignH = (typeof ANCHOR_H_ALIGN_VALUES)[number];
+export type AnchorAlignV = (typeof ANCHOR_V_ALIGN_VALUES)[number];
+export declare function isAnchorHRelative(value: unknown): value is AnchorHRelative;
+export declare function isAnchorVRelative(value: unknown): value is AnchorVRelative;
+export declare function isAnchorAlignH(value: unknown): value is AnchorAlignH;
+export declare function isAnchorAlignV(value: unknown): value is AnchorAlignV;
 export declare function isPositionedParagraphFrame<T extends {
     wrap?: string;
 }>(frame: T | undefined): frame is T & {
@@ -35,6 +47,10 @@ export type ColumnLayoutForAnchor = {
  */
 export type ResolveAnchoredGraphicYInput = {
     anchor?: {
+        simplePos?: {
+            x: number;
+            y: number;
+        };
         vRelativeFrom?: AnchorVRelative;
         alignV?: AnchorAlignV;
         offsetV?: number;
@@ -49,8 +65,12 @@ export type ResolveAnchoredGraphicYInput = {
      * Used for `paragraph` and legacy (undefined vRelativeFrom) positioning.
      */
     anchorParagraphY?: number;
+    /** Anchor line top Y. Falls back to the paragraph top when unavailable. */
+    anchorLineY?: number;
     /** First line height of the anchor paragraph (paragraph-relative alignV). */
     firstLineHeight?: number;
+    /** One-based physical page number, used by inside/outside placement. */
+    pageNumber?: number;
     /**
      * When true, anchor has no host paragraph (pre-registered / paragraphless layout).
      * For `vRelativeFrom: 'paragraph'`, use `contentTop + offsetV` instead of alignV on a
@@ -62,15 +82,24 @@ export type ResolveAnchoredGraphicYInput = {
  * Resolve the vertical paint position for an anchored graphic (image, drawing, or table).
  */
 export declare function resolveAnchoredGraphicY(input: ResolveAnchoredGraphicYInput): number;
+export type ResolveAnchoredGraphicXContext = {
+    /** One-based physical page number, used by inside/outside placement. */
+    pageNumber?: number;
+    /** Page-space X of the anchor character. Falls back to the column origin. */
+    anchorCharacterX?: number;
+};
 /**
  * Resolve horizontal paint position for an anchored graphic.
  */
 export declare function resolveAnchoredGraphicX(anchor: {
+    simplePos?: {
+        x: number;
+        y: number;
+    };
     hRelativeFrom?: AnchorHRelative;
     alignH?: AnchorAlignH;
     offsetH?: number;
 }, columnIndex: number, columns: ColumnLayoutForAnchor, objectWidth: number, margins?: {
     left?: number;
     right?: number;
-}, pageWidth?: number): number;
-export {};
+}, pageWidth?: number, context?: ResolveAnchoredGraphicXContext): number;