superdoc 2.27.0 → 2.28.0-next.10

package/dist/chunks/{create-super-doc-ui-cHUUipYM.es.js → create-super-doc-ui-C4Ka5Ph3.es.js}

@@ -2458,6 +2458,69 @@ function createDialogWorkflow(editor, options, onSuccess) {
 	};
 }
 //#endregion
+//#region src/public/ui/style-match-patch.ts
+var STYLE_MATCH_KEYS = [
+	["bold", "bold"],
+	["italic", "italic"],
+	["underline", "underline"],
+	["color", "color"],
+	["fontSize", "fontSize"],
+	["rFonts", "fontFamily"]
+];
+var STYLE_MATCH_READ_KEYS = [...STYLE_MATCH_KEYS.map(([readKey]) => readKey), "rStyle"];
+function buildStyleMatchPatch(effective, direct, options) {
+	const patch = {};
+	const characterStyle = direct.properties.rStyle;
+	const hasCharacterStyle = characterStyle != null && characterStyle.state !== "unset";
+	for (const [readKey, styleKey] of STYLE_MATCH_KEYS) {
+		const read = effective.properties[readKey];
+		if (read?.state !== "uniform") continue;
+		if (options.selectionUsesStyle && !hasCharacterStyle && direct.properties[readKey]?.state === "unset") continue;
+		patch[styleKey] = toStyleValue(readKey, read.value);
+	}
+	return patch;
+}
+function toStyleValue(key, value) {
+	switch (key) {
+		case "bold":
+		case "italic": return value === true;
+		case "underline": return underlineValue(value);
+		case "color": return typeof value === "string" && value.length > 0 ? { val: value.replace(/^#/, "") } : null;
+		case "fontSize": return typeof value === "number" && Number.isFinite(value) ? Math.round(value * 2) : null;
+		case "rFonts": return fontsValue(value);
+		default: return null;
+	}
+}
+function underlineValue(value) {
+	if (value === true) return { val: "single" };
+	if (!value || typeof value !== "object") return { val: "none" };
+	const underline = value;
+	const result = { val: typeof underline.style === "string" && underline.style ? underline.style : "single" };
+	if (typeof underline.color === "string") result.color = underline.color;
+	if (typeof underline.themeColor === "string") result.themeColor = underline.themeColor;
+	return result;
+}
+var FONT_SLOTS = {
+	ascii: "ascii",
+	hAnsi: "hAnsi",
+	eastAsia: "eastAsia",
+	cs: "cs",
+	asciiTheme: "asciiTheme",
+	hAnsiTheme: "hAnsiTheme",
+	eastAsiaTheme: "eastAsiaTheme",
+	csTheme: "cstheme",
+	hint: "hint"
+};
+function fontsValue(value) {
+	if (!value || typeof value !== "object") return null;
+	const result = {};
+	for (const [slot, styleSlot] of Object.entries(FONT_SLOTS)) {
+		const font = value[slot];
+		if (typeof font === "string" && font.length > 0) result[styleSlot] = font;
+	}
+	return Object.keys(result).length > 0 ? result : null;
+}
+//#endregion
 //#region src/public/ui/format-painter-helpers.js
 /**
 * Maps SDRunProps field names to InlineRunPatch field names.
@@ -3628,6 +3691,25 @@ function getCommandDescriptor(id) {
 }
 //#endregion
 //#region src/public/ui/entity-at.ts
+function readDecorationProviders(node) {
+	const encoded = node.getAttribute("data-superdoc-extension-decorations");
+	if (encoded) try {
+		const parsed = JSON.parse(encoded);
+		if (Array.isArray(parsed)) return parsed.filter((id) => typeof id === "string");
+	} catch {
+		return [];
+	}
+	const single = node.getAttribute("data-superdoc-extension-decoration");
+	return single ? [single] : [];
+}
+function collectDecorationProvidersFromChain(start, stopAt) {
+	const providers = /* @__PURE__ */ new Set();
+	for (let element = start; element; element = element.parentElement) {
+		for (const provider of readDecorationProviders(element)) providers.add(provider);
+		if (element === stopAt) break;
+	}
+	return [...providers];
+}
 function parseCommaSeparatedIds(value) {
 	return value.split(",").map((id) => id.trim()).filter(Boolean);
 }
@@ -3699,6 +3781,16 @@ function collectEntityHitsFromChain(start, stopAt) {
 			for (const hit of pendingStory) hit.story = layoutStory;
 			pendingStory = [];
 		}
+		for (const decorationProvider of readDecorationProviders(node)) {
+			const key = `decoration:${decorationProvider}`;
+			if (!seen.has(key)) {
+				seen.add(key);
+				hits.push({
+					type: "decoration",
+					id: decorationProvider
+				});
+			}
+		}
 		const citationId = node.getAttribute("data-citation-id");
 		if (citationId) {
 			const key = `citation:${citationId}`;
@@ -6089,6 +6181,7 @@ function createSuperDocUI(options) {
 		pointerSelecting: false,
 		keyboardSelecting: false
 	};
+	const paintedInlineTargets = /* @__PURE__ */ new WeakSet();
 	let painterCaptureEpoch = 0;
 	let painterCommandDoc = null;
 	const painterModeListeners = /* @__PURE__ */ new Set();
@@ -6185,7 +6278,7 @@ function createSuperDocUI(options) {
 	const readHostSelectionSnapshot = () => {
 		const handles = safeCall(() => hostMethod(getHost(), "getHandles")?.() ?? null, null);
 		const editing = isPlainObject(handles) ? handles.editing : void 0;
-		const getSnapshot = hostMethod(isPlainObject(editing) ? editing.selection : void 0, "getSnapshot");
+		const getSnapshot = hostMethod(isPlainObject(editing) ? editing.selection : void 0, "getSnapshot") ?? hostMethod(isPlainObject(handles) ? handles.selection : void 0, "getSnapshot");
 		if (!getSnapshot) return null;
 		const snapshot = safeCall(() => getSnapshot(), null);
 		return snapshot && typeof snapshot === "object" ? snapshot : null;
@@ -6399,7 +6492,7 @@ function createSuperDocUI(options) {
 		return left.id === right.id && left.paintedEntityId === right.paintedEntityId && storyLocatorSignature(left.story) === storyLocatorSignature(right.story);
 	};
 	const hasPendingTrackChangeRevealFocus = (focus) => Array.from(pendingTrackChangeRevealFocuses).some((pendingFocus) => explicitActiveChangesEqual(pendingFocus, focus));
-	const mirrorTrackedChangeFocusToHost = (next) => {
+	const mirrorReviewFocusToHost = (entityType, next) => {
 		const readHandles = hostMethod(getHost(), "getHandles");
 		if (!readHandles) return;
 		const handles = safeCall(() => readHandles(), null);
@@ -6410,15 +6503,15 @@ function createSuperDocUI(options) {
 			if (!setActiveReviewTarget) return;
 			const layout = isPlainObject(handles.layout) ? handles.layout : void 0;
 			safeCall(() => setActiveReviewTarget({
-				entityType: "trackedChange",
+				entityType,
 				entityId: next.id,
 				...next.paintedEntityId ? { paintedEntityId: next.paintedEntityId } : {},
 				origin: "panel",
 				layoutEpoch: typeof layout?.generation === "number" ? layout.generation : 0,
-				story: next.story ?? {
+				...entityType === "trackedChange" ? { story: next.story ?? {
 					kind: "story",
 					storyType: "body"
-				}
+				} } : {}
 			}), null);
 			return;
 		}
@@ -6426,10 +6519,22 @@ function createSuperDocUI(options) {
 		const clearActiveReviewTarget = hostMethod(review, "clearActiveReviewTarget");
 		if (!getActiveReviewTarget || !clearActiveReviewTarget) return;
 		const activeTarget = safeCall(() => getActiveReviewTarget(), null);
-		if (isPlainObject(activeTarget) && activeTarget.entityType === "trackedChange") safeCall(() => clearActiveReviewTarget(), void 0);
+		if (isPlainObject(activeTarget) && activeTarget.entityType === entityType) safeCall(() => clearActiveReviewTarget(), void 0);
+	};
+	const mirrorTrackedChangeFocusToHost = (next) => mirrorReviewFocusToHost("trackedChange", next);
+	const readReviewFocus = () => ({
+		change: explicitActiveChange,
+		commentId: explicitActiveCommentId
+	});
+	const restoreReviewFocus = (previous) => {
+		setExplicitActiveChange(previous.change, { invalidateQueuedNavigation: false });
+		explicitActiveCommentId = previous.commentId;
+		if (previous.commentId) mirrorReviewFocusToHost("comment", { id: previous.commentId });
+		else mirrorTrackedChangeFocusToHost(previous.change);
 	};
 	const setExplicitActiveChange = (next, options) => {
 		explicitActiveChange = next;
+		if (next) explicitActiveCommentId = null;
 		explicitActiveChangeRevision += 1;
 		trackChangeRevealInvalidation += 1;
 		if (options?.invalidateQueuedNavigation !== false) queuedTrackChangeNavigationInvalidation += 1;
@@ -7099,7 +7204,7 @@ function createSuperDocUI(options) {
 			failureCount: retryingSameToken ? prev.failureCount ?? 0 : 0,
 			retryAtMs: 0
 		});
-		Promise.resolve(raw).then((resolved) => {
+		const settled = Promise.resolve(raw).then((resolved) => {
 			const entry = asyncReads.get(key);
 			if (!entry || entry.inflightToken !== token) return;
 			asyncReads.set(key, {
@@ -7138,6 +7243,7 @@ function createSuperDocUI(options) {
 			const retryAtMs = Date.now() + retryDelayMs;
 			asyncReads.set(key, {
 				...entry,
+				settled: void 0,
 				inflightToken: null,
 				failedToken: token,
 				failureCount,
@@ -7145,6 +7251,8 @@ function createSuperDocUI(options) {
 			});
 			scheduleAsyncReadFailureRetry(retryAtMs);
 		});
+		const entry = asyncReads.get(key);
+		if (entry?.inflightToken === token) entry.settled = settled;
 		return null;
 	};
 	/**
@@ -7486,15 +7594,53 @@ function createSuperDocUI(options) {
 	* Explicit whole-table changes have a complete local source range and also
 	* seed clears, so a delayed worker read cannot retain a cleared table target.
 	*/
-	const refreshSelectionFromHost = (hostSelectionSnapshot, afterTypingPaint = false, wholeTableSelectionChanged = false) => {
+	function captureWholeTableParagraphSeed(host, seed, nativeSelection) {
+		const editor = getEditor();
+		const rawLifetime = safeCall(() => hostMethod(host, "getForegroundInteractionLifetime")?.() ?? null, null);
+		const lifetime = hasAbortedFlag(rawLifetime) ? rawLifetime : null;
+		const mount = safeCall(() => hostMethod(host, "getMountedHandle")?.() ?? null, null);
+		const mode = readDocumentMode();
+		if (!host || !editor || !mount || !lifetime || lifetime.aborted || mode === null || seed.empty || seed.tableSelection?.kind !== "tableCells" || seed.tableSelection.type !== "table" || seed.target?.kind !== "text" || !seed.target.segments.length) return false;
+		if (nativeSelection) {
+			const presentation = safeCall(() => hostMethod(host, "readAppliedSelectionPresentation")?.(), null);
+			const applied = normalizeSelectionInfo(isPlainObject(presentation) ? presentation.selection : null);
+			if (readHostSelectionSnapshot() !== nativeSelection || !isNonCollapsedHostSelection(nativeSelection) || !applied || selectionSignature(selectionSliceFromInfo(applied, "ready")) !== selectionSignature(selectionSliceFromInfo(seed, "ready")) || JSON.stringify(applied.tableSelection) !== JSON.stringify(seed.tableSelection)) return false;
+			const snapshot = nativeSelection;
+			const first = seed.target.segments[0]?.blockId, last = seed.target.segments.at(-1)?.blockId;
+			const matches = (point, blockId) => !!blockId && isPlainObject(point) && point.blockId === blockId && storyLocatorSignature(point.story ?? snapshot.story) === storyLocatorSignature(seed.target?.story);
+			if (!(matches(snapshot.anchor, first) && matches(snapshot.focus, last) || matches(snapshot.focus, first) && matches(snapshot.anchor, last))) return false;
+		}
+		wholeTableParagraphSeed = {
+			editor,
+			host,
+			doc: editor.doc,
+			mount,
+			lifetime,
+			sourceToken: contentToken(),
+			mode,
+			info: seed,
+			nativeSelection
+		};
+		return true;
+	}
+	const refreshSelectionFromHost = (hostSelectionSnapshot, afterTypingPaint = false, wholeTableSelectionChanged = false, initialTableSelection = null) => {
+		const host = getHost();
 		const foreground = foregroundMutationState();
+		if (isNonCollapsedHostSelection(hostSelectionSnapshot) && readHostSelectionSnapshot() === hostSelectionSnapshot) {
+			const seed = normalizeSelectionInfo(safeCall(() => hostMethod(host, "readLiveSelectionSyncSnapshot")?.(), null));
+			if (seed && !seed.selectionTarget && captureWholeTableParagraphSeed(host, seed, hostSelectionSnapshot)) asyncReads.set("selection", {
+				token: asyncReads.get("selection")?.token ?? null,
+				value: seed,
+				hasSettled: true,
+				inflightToken: null
+			});
+		}
 		if (isNonCollapsedHostSelection(hostSelectionSnapshot) && !(foreground && foreground.active > 0)) {
 			typedCaretValidationHeld = false;
 			pendingSelectionSeedValidationToken = null;
 			issueAsyncRead("selection", selectionReadToken(), selectionCurrentRun, normalizeSelectionInfo);
 			return;
 		}
-		const host = getHost();
 		const read = host?.readLiveSelectionSyncSnapshot;
 		if (typeof read !== "function") return;
 		const seed = normalizeSelectionInfo(safeCall(() => read.call(host), null));
@@ -7503,21 +7649,7 @@ function createSuperDocUI(options) {
 			typedCaretValidationHeld = false;
 			pendingSelectionSeedValidationToken = null;
 			wholeTableParagraphSeed = null;
-			const editor = getEditor();
-			const rawLifetime = safeCall(() => hostMethod(host, "getForegroundInteractionLifetime")?.() ?? null, null);
-			const lifetime = hasAbortedFlag(rawLifetime) ? rawLifetime : null;
-			const mount = safeCall(() => hostMethod(host, "getMountedHandle")?.() ?? null, null);
-			const mode = readDocumentMode();
-			if (host && editor && mount && lifetime && !lifetime.aborted && mode !== null && !seed.empty && seed.tableSelection?.kind === "tableCells" && seed.tableSelection.type === "table" && seed.target?.segments.length && seed.selectionTarget) wholeTableParagraphSeed = {
-				editor,
-				host,
-				doc: editor.doc,
-				mount,
-				lifetime,
-				sourceToken: contentToken(),
-				mode,
-				info: seed
-			};
+			captureWholeTableParagraphSeed(host, seed, initialTableSelection);
 			const token = selectionReadToken();
 			asyncReads.set("selection", {
 				token,
@@ -7675,7 +7807,7 @@ function createSuperDocUI(options) {
 		const directory = asyncReads.get("comments");
 		const directoryItems = directory?.token === contentToken() && directory.hasSettled && Array.isArray(directory.value) ? directory.value : null;
 		const activeValidationItems = directoryLeaseCounts.comments > 0 ? directoryItems : items;
-		if (explicitActiveCommentId && activeValidationItems && !activeValidationItems.some((item) => readEntityId(item) === explicitActiveCommentId)) explicitActiveCommentId = null;
+		if (explicitActiveCommentId && activeValidationItems && (activeValidationItems !== items || listStatus === "ready")) explicitActiveCommentId = resolveActiveCommentId(activeValidationItems, explicitActiveCommentId);
 		const activeId = explicitActiveCommentId ?? activeIds[0] ?? null;
 		return {
 			status: combineStatus(listStatus, selection.status),
@@ -8320,12 +8452,13 @@ function createSuperDocUI(options) {
 	];
 	function effectiveInlineUniformityInput(selection) {
 		const cellTarget = currentCellSelectionTarget();
-		const target = cellTarget ?? selection.selectionTarget;
+		const paintedTarget = cellTarget ? null : currentUnrepresentableSelectionTarget(selection);
+		const target = cellTarget ?? paintedTarget ?? selection.selectionTarget;
 		if (!target) return null;
 		const tableCellSelection = cellTarget ? tableCellSelectionForTarget(cellTarget) : null;
 		return {
 			target,
-			offsetSpace: "selection",
+			offsetSpace: cellTarget || paintedTarget ? "selection" : "kernel",
 			...tableCellSelection ? { tableCellSelection } : {}
 		};
 	}
@@ -8463,7 +8596,11 @@ function createSuperDocUI(options) {
 		const getNodeById = hostMethod(doc, "getNodeById");
 		const raw = await Promise.resolve(getNode ? getNode(address) : getNodeById?.({
 			nodeId: address["nodeId"],
-			nodeType: address["nodeType"]
+			nodeType: address["nodeType"],
+			story: address["story"] ?? {
+				kind: "story",
+				storyType: "body"
+			}
 		}));
 		return isPlainObject(raw) ? raw : void 0;
 	};
@@ -9009,7 +9146,8 @@ function createSuperDocUI(options) {
 		const token = contentToken();
 		const read = readAsync(key, token, () => isBodyStory ? doc.getNodeById({
 			nodeId: blockId,
-			nodeType: "paragraph"
+			nodeType: "paragraph",
+			story
 		}) : doc.getNode(paragraphTarget(blockId, story)), (raw) => raw && typeof raw === "object" ? raw : null);
 		const entry = asyncReads.get(key);
 		return {
@@ -9218,7 +9356,11 @@ function createSuperDocUI(options) {
 			const isBodyStory = !story || story.storyType === "body";
 			const raw = story && typeof doc.getNode === "function" ? await doc.getNode(paragraphTarget(blockId, story)) : isBodyStory && typeof doc.getNodeById === "function" ? await doc.getNodeById({
 				nodeId: blockId,
-				nodeType: "paragraph"
+				nodeType: "paragraph",
+				story: {
+					kind: "story",
+					storyType: "body"
+				}
 			}) : null;
 			return readParagraphIndentationFromResult(raw && typeof raw === "object" ? raw : null);
 		} catch {
@@ -9895,14 +10037,15 @@ function createSuperDocUI(options) {
 			const tableSelection = isPlainObject(handles) ? handles.selection : void 0;
 			const subscribeWholeTable = hostMethod(tableSelection, "subscribeWholeTable");
 			if (subscribeWholeTable) {
-				const refreshWholeTable = () => {
+				const refreshWholeTable = (initial = false) => {
+					const native = initial ? readHostSelectionSnapshot() : null;
 					selectionEpoch += 1;
-					refreshSelectionFromHost(void 0, false, true);
+					refreshSelectionFromHost(void 0, false, true, native);
 					recompute("host-selection");
 				};
-				const detach = subscribeWholeTable(refreshWholeTable);
+				const detach = subscribeWholeTable(() => refreshWholeTable());
 				if (typeof detach === "function") unsubscribeCallbacks.push(() => detach());
-				if (hostMethod(tableSelection, "getWholeTableNodeId")?.()) refreshWholeTable();
+				if (hostMethod(tableSelection, "getWholeTableNodeId")?.()) refreshWholeTable(true);
 			}
 		} catch {
 			currentHostSelectionSource = null;
@@ -9923,10 +10066,35 @@ function createSuperDocUI(options) {
 	};
 	let trackedChangeNavigationInFlight = 0;
 	let lastPublishedHostReviewTarget;
+	const isRepublishedHostReviewTarget = (left, right) => left === right || isPlainObject(left) && isPlainObject(right) && left.layoutEpoch !== right.layoutEpoch && left.origin === right.origin && left.entityType === right.entityType && left.entityId === right.entityId && left.paintedEntityId === right.paintedEntityId && storyLocatorSignature(left.story) === storyLocatorSignature(right.story);
 	const syncTrackedChangeFocusFromHostReviewTarget = (rawTarget, rawSnapshot) => {
 		const rejection = (rawSnapshot && typeof rawSnapshot === "object" ? rawSnapshot : null)?.lastInteractionRejection;
-		if (rawTarget == null && rejection && typeof rejection === "object" && rejection.code === "review-target-invalidated" && rejection.detail === "not-painted" && explicitActiveChange) return false;
+		if (rawTarget == null && rejection && typeof rejection === "object" && rejection.code === "review-target-invalidated" && rejection.detail === "not-painted" && (explicitActiveChange || explicitActiveCommentId)) return false;
 		const target = rawTarget && typeof rawTarget === "object" ? rawTarget : null;
+		if (target?.entityType === "comment" && typeof target.entityId === "string" && target.entityId.length > 0) {
+			const commentId = resolveActiveCommentId(state?.comments.items ?? [], target.entityId) ?? target.entityId;
+			const republished = isRepublishedHostReviewTarget(rawTarget, lastPublishedHostReviewTarget?.raw);
+			lastPublishedHostReviewTarget = {
+				raw: rawTarget,
+				focus: null,
+				origin: target.origin
+			};
+			if (republished || explicitActiveCommentId === commentId && !explicitActiveChange) return false;
+			setExplicitActiveChange(null);
+			explicitActiveCommentId = commentId;
+			return true;
+		}
+		const previousTarget = lastPublishedHostReviewTarget?.raw;
+		if (!target && isPlainObject(previousTarget) && previousTarget.entityType === "comment") {
+			lastPublishedHostReviewTarget = {
+				raw: rawTarget,
+				focus: null,
+				origin: void 0
+			};
+			if (!explicitActiveCommentId) return false;
+			explicitActiveCommentId = null;
+			return true;
+		}
 		let next = null;
 		if (target?.entityType === "trackedChange" && typeof target.entityId === "string" && target.entityId.length > 0) {
 			const targetStory = target.story && typeof target.story === "object" ? target.story : void 0;
@@ -9951,7 +10119,7 @@ function createSuperDocUI(options) {
 		}
 		if (rawTarget == null && next == null && explicitActiveChange != null && hasPendingTrackChangeRevealFocus(explicitActiveChange)) return false;
 		const previousPublication = lastPublishedHostReviewTarget;
-		if (previousPublication && (rawTarget === previousPublication.raw || target?.origin === "panel" && previousPublication.origin === "panel" && next && previousPublication.focus && explicitActiveChangesEqual(previousPublication.focus, next))) return false;
+		if (previousPublication && (isRepublishedHostReviewTarget(rawTarget, previousPublication.raw) || target?.origin === "panel" && previousPublication.origin === "panel" && next && previousPublication.focus && explicitActiveChangesEqual(previousPublication.focus, next))) return false;
 		lastPublishedHostReviewTarget = {
 			raw: rawTarget,
 			focus: next,
@@ -10329,11 +10497,16 @@ function createSuperDocUI(options) {
 	* ordinary/insertion selections are visible-space, while a selection that
 	* reaches painted deleted text is projected in tracked space by the host.
 	*
-	* Cross-block coverage must come from the model-backed tracked target;
-	* intermediate block lengths cannot be inferred from the endpoints.
+	* Cross-block and object-containing coverage use the model-backed tracked
+	* target when the explicit text selection cannot represent the range.
 	*/
 	function trackDecisionRangeFromSelection(selection) {
 		if (selection.empty) return null;
+		if (!selection.selectionTarget && selection.trackedTarget) return {
+			kind: "range",
+			coordinateSpace: "tracked",
+			range: selection.trackedTarget
+		};
 		const explicit = selection.selectionTarget;
 		const start = explicit?.start;
 		const end = explicit?.end;
@@ -10487,7 +10660,7 @@ function createSuperDocUI(options) {
 			kind: "blocked",
 			reason: SUPERDOC_UI_REASONS.operationUnavailable
 		};
-		if (!selection.selectionTarget) return null;
+		if (!selection.selectionTarget && !selection.trackedTarget && selection.target?.kind !== "text") return null;
 		const target = trackDecisionRangeFromSelection(selection);
 		if (!target && route() !== "id") return {
 			kind: "blocked",
@@ -10827,25 +11000,35 @@ function createSuperDocUI(options) {
 		pendingCommandSettlement = settledResults.length ? Promise.all(settledResults).then((results) => combineCommandResults(results)) : null;
 		return combineCommandResults(immediateResults);
 	};
-	/**
-	* Call an inline `format.*` operation against the live selection. Mirrors
-	* `callEditorMutation` (suggesting mode adds `changeMode: 'tracked'`), and
-	* when the target is the host's own editable `selectionTarget` it also
-	* carries the PRIVATE V2 option `offsetSpace: 'selection'` (browser
-	* selection offsets count an inline object as one caret position). The
-	* option is not part of public `MutationOptions`; this is the same cast
-	* pattern the delete/replace callers use.
-	*/
 	function currentCellSelectionTarget() {
+		return captureInputSelectionTarget(true);
+	}
+	function captureInputSelectionTarget(requireTableCells = false) {
 		const handles = safeCall(() => hostMethod(getHost(), "getHandles")?.(), null);
 		const selection = isPlainObject(handles) ? handles.selection : void 0;
 		const held = hostMethod(selection, "getSnapshot")?.();
-		if (!isPlainObject(held) || !held.tableCells) return null;
+		if (requireTableCells && (!isPlainObject(held) || !held.tableCells)) return null;
 		const resolved = hostMethod(selection, "toSelectionTarget")?.();
 		return isPlainObject(resolved) && resolved.kind === "ok" && resolved.mode === "range" ? capturedTableCellTarget(resolved.target) : null;
 	}
+	function currentUnrepresentableSelectionTarget(selection) {
+		if (selection.empty || selection.selectionTarget || selection.target?.kind !== "text") return null;
+		return heldPaintedTextSelectionTarget();
+	}
+	function heldPaintedTextSelectionTarget() {
+		const target = captureInputSelectionTarget();
+		if (target) paintedInlineTargets.add(target);
+		return target;
+	}
 	function resolveInlineCommandTarget(selection) {
-		return currentCellSelectionTarget() ?? resolveInlineSelectionTarget(selection);
+		const cells = currentCellSelectionTarget();
+		if (cells) return cells;
+		if (!selection.empty && !selection.selectionTarget && selection.target?.kind === "text") {
+			const snapshot = readHostSelectionSnapshot();
+			const painted = currentUnrepresentableSelectionTarget(selection);
+			if (painted) return snapshot && appliedSelectionPresentation(selection) && readHostSelectionSnapshot() === snapshot ? painted : null;
+		}
+		return resolveInlineSelectionTarget(selection);
 	}
 	function tableCellSelectionForTarget(target) {
 		const cellTarget = currentCellSelectionTarget();
@@ -10865,10 +11048,15 @@ function createSuperDocUI(options) {
 			offsetSpace: "selection",
 			tableCellSelection
 		});
+		const paintedTarget = input?.target;
+		if (paintedTarget !== null && typeof paintedTarget === "object" && (paintedInlineTargets.has(paintedTarget) || paintedTarget.coordinateSpace === "tracked")) return op(input, {
+			...options,
+			offsetSpace: "selection"
+		});
 		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
 			...options,
-			offsetSpace: "selection"
+			offsetSpace: "kernel"
 		});
 	};
 	/** Build the `format.paragraph.*` / `styles.paragraph.*` input for a block. */
@@ -11097,13 +11285,16 @@ function createSuperDocUI(options) {
 		};
 		pendingCommandSettlement = (async () => {
 			const plans = await Promise.all(blockIds.map((blockId) => planBlock(blockId).catch(() => null)));
-			if (plans.length === blockIds.length && plans.every((plan) => plan?.kind === "list") && readDocumentMode() !== "suggesting") {
+			const allListItems = plans.length === blockIds.length && plans.every((plan) => plan?.kind === "list");
+			const preserveFirstItemLevel = blockIds.length === 1 && story.storyType === "body";
+			if (allListItems && (readDocumentMode() !== "suggesting" || preserveFirstItemLevel)) {
 				const rangeRoute = mode === "indent" ? "lists.indentRange" : "lists.outdentRange";
 				const rangeOp = resolveDocOperation(doc, rangeRoute);
 				if (rangeOp) try {
 					return await settleOperationResult(callEditorMutation(rangeRoute, rangeOp, {
 						paraIds: blockIds,
-						story
+						story,
+						...preserveFirstItemLevel ? { preserveFirstItemLevel: true } : {}
 					})).settled;
 				} catch {
 					return false;
@@ -11643,23 +11834,32 @@ function createSuperDocUI(options) {
 		const record = readLinkPayloadRecord(payload);
 		return Boolean(readLinkPayloadTarget(payload) || isPlainObject(record.hyperlinkTarget) || isPlainObject(record.textTarget));
 	};
-	const currentWholeTableParagraphSelection = () => {
+	const currentWholeTableParagraphOwner = () => {
 		const owner = wholeTableParagraphSeed, host = getHost();
-		if (!owner || disposed || owner.lifetime.aborted || owner.host !== host || owner.editor !== getEditor() || owner.editor.doc !== owner.doc || owner.sourceToken !== contentToken() || owner.mode !== readDocumentMode() || safeCall(() => hostMethod(host, "getMountedHandle")?.(), null) !== owner.mount) return false;
+		if (!owner || disposed || owner.lifetime.aborted || owner.host !== host || owner.editor !== getEditor() || owner.editor.doc !== owner.doc || owner.sourceToken !== contentToken() || owner.mode !== readDocumentMode() || safeCall(() => hostMethod(host, "getMountedHandle")?.(), null) !== owner.mount) return null;
 		const tableId = owner.info.tableSelection?.tableId;
 		const activeTable = safeCall(() => {
 			const handles = hostMethod(host, "getHandles")?.();
 			return hostMethod(isPlainObject(handles) ? handles.selection : void 0, "getWholeTableNodeId")?.();
 		}, null);
-		if (!tableId || activeTable !== tableId || state.selection.tableSelection?.type !== "table" || state.selection.tableSelection.tableId !== tableId || selectionSignature(state.selection) !== selectionSignature(selectionSliceFromInfo(owner.info, "ready"))) return false;
+		if (!tableId || activeTable !== tableId || state.selection.tableSelection?.type !== "table" || state.selection.tableSelection.tableId !== tableId || selectionSignature(state.selection) !== selectionSignature(selectionSliceFromInfo(owner.info, "ready"))) return null;
 		const applied = appliedSelectionPresentation(state.selection);
 		const info = normalizeSelectionInfo(applied?.selection);
-		return !!info && selectionInfoMatchesHost(info) && JSON.stringify(info.tableSelection) === JSON.stringify(owner.info.tableSelection);
+		return info && JSON.stringify(info.tableSelection) === JSON.stringify(owner.info.tableSelection) ? {
+			owner,
+			info
+		} : null;
+	};
+	const currentWholeTableParagraphSelection = () => {
+		const current = currentWholeTableParagraphOwner();
+		if (!current) return false;
+		return current.owner.info.selectionTarget ? selectionInfoMatchesHost(current.info) : current.owner.nativeSelection !== null && readHostSelectionSnapshot() === current.owner.nativeSelection;
 	};
 	const commandSelectionIsReady = (id, descriptor, payload) => {
 		const foreground = foregroundMutationState();
 		if (foreground && (foreground.active > 0 || foreground.pending > 0)) return false;
 		if (descriptor?.blockParagraph && currentWholeTableParagraphSelection()) return true;
+		if (descriptor?.blockParagraph && state.selection.tableSelection?.type === "table" && !state.selection.selectionTarget) return false;
 		if (state.selection.status !== "ready") return false;
 		if (trackDecisionCommand(id)?.scope === "id") return true;
 		if (!descriptor || descriptor.disposition !== "routed") return true;
@@ -12080,10 +12280,23 @@ function createSuperDocUI(options) {
 			const cellTarget = currentCellSelectionTarget();
 			const tableCellSelection = tableCellSelectionForTarget(cellTarget);
 			const rawSelection = typeof selectionApi?.["current"] === "function" ? await Promise.resolve(selectionApi["current"]({ includeText: true })) : readSelectionInfoLive().value;
+			const selection = normalizeSelectionInfo(rawSelection);
+			let paintedTarget = null;
+			if (selection && !selection.empty && !selection.selectionTarget && selection.target?.kind === "text" && !cellTarget) {
+				const nativeSelection = readHostSelectionSnapshot();
+				paintedTarget = heldPaintedTextSelectionTarget();
+				if (paintedTarget && (!nativeSelection || !appliedSelectionPresentation(selectionSliceFromInfo(selection, "ready")) || readHostSelectionSnapshot() !== nativeSelection)) return {
+					selection: null,
+					cellTarget: null,
+					tableCellSelection: null,
+					paintedTarget: null
+				};
+			}
 			return {
-				selection: normalizeSelectionInfo(rawSelection),
+				selection,
 				cellTarget,
-				tableCellSelection
+				tableCellSelection,
+				paintedTarget
 			};
 		};
 		const waitForSelectionSettle = () => new Promise((resolve) => setTimeout(resolve, 16));
@@ -12101,7 +12314,7 @@ function createSuperDocUI(options) {
 			break;
 		}
 		if (selectionRead?.selection && !selectionRead.selection.empty && key !== painter.sourceSelectionKey) {
-			await applyFormatPainter(selectionRead.selection, selectionRead.cellTarget, selectionRead.tableCellSelection);
+			await applyFormatPainter(selectionRead.selection, selectionRead.cellTarget, selectionRead.tableCellSelection, selectionRead.paintedTarget);
 			return;
 		}
 		if (painter.snapshot?.paragraph) {
@@ -12109,10 +12322,10 @@ function createSuperDocUI(options) {
 			const caretSel = caretRead.selection;
 			if (!caretSel) return;
 			if (selectionKey(caretSel) === painter.sourceSelectionKey) return;
-			await applyFormatPainter(caretSel, caretRead.cellTarget, caretRead.tableCellSelection);
+			await applyFormatPainter(caretSel, caretRead.cellTarget, caretRead.tableCellSelection, caretRead.paintedTarget);
 		}
 	};
-	const applyFormatPainter = async (selection, cellTarget, tableCellSelection) => {
+	const applyFormatPainter = async (selection, cellTarget, tableCellSelection, paintedTarget) => {
 		const snap = painter.snapshot;
 		if (!snap) {
 			if (painter.mode === "armed") exitFormatPainter();
@@ -12130,7 +12343,7 @@ function createSuperDocUI(options) {
 			return;
 		}
 		const selTarget = selection.target;
-		const selectionTarget = cellTarget ?? selection.selectionTarget;
+		const selectionTarget = cellTarget ?? paintedTarget ?? selection.selectionTarget;
 		const selectionIsEmpty = selection.empty === true;
 		const segments = Array.isArray(selTarget?.segments) ? selTarget.segments : [];
 		const targetStory = selTarget?.story;
@@ -12368,13 +12581,16 @@ function createSuperDocUI(options) {
 			const snapshot = selectionSub.get();
 			if (snapshot.empty) return null;
 			const cells = currentCellSelectionTarget();
+			const painted = cells ? null : currentUnrepresentableSelectionTarget(snapshot);
+			const hostSelection = selectionHostSnapshots.get(snapshot);
+			if ((cells || painted || hostSelection && !snapshot.selectionTarget) && (!hostSelection || readHostSelectionSnapshot() !== hostSelection)) return null;
 			if (!snapshot.target && !snapshot.selectionTarget && !cells) return null;
 			const capture = {
 				...snapshot,
 				capturedAt: Date.now(),
-				...cells ? { _tableCellSelectionTarget: cells } : {}
+				...cells ? { _tableCellSelectionTarget: cells } : {},
+				...painted ? { _paintedSelectionTarget: painted } : {}
 			};
-			const hostSelection = selectionHostSnapshots.get(snapshot);
 			if (hostSelection) selectionHostSnapshots.set(capture, hostSelection);
 			return capture;
 		},
@@ -12400,7 +12616,13 @@ function createSuperDocUI(options) {
 				ok: false,
 				reason: SUPERDOC_UI_REASONS.targetUnresolved
 			});
-			const target = cellTarget ?? selectionTargetForRestore(capture);
+			const hasPaintedTarget = "_paintedSelectionTarget" in capture;
+			const paintedTarget = hasPaintedTarget ? capturedTableCellTarget(capture._paintedSelectionTarget) : null;
+			if (hasPaintedTarget && !paintedTarget) return done({
+				ok: false,
+				reason: SUPERDOC_UI_REASONS.targetUnresolved
+			});
+			const target = cellTarget ?? paintedTarget ?? selectionTargetForRestore(capture);
 			if (!target) return done({
 				ok: false,
 				reason: SUPERDOC_UI_REASONS.targetUnresolved
@@ -12413,7 +12635,7 @@ function createSuperDocUI(options) {
 				reason: resolved.reason
 			});
 			try {
-				return done(normalizeHostSelectionApplyResult(hostMethod(resolved.helper, "apply")?.(target, ...cellTarget ? [{ tableCells: true }] : [])));
+				return done(normalizeHostSelectionApplyResult(hostMethod(resolved.helper, "apply")?.(target, ...cellTarget ? [{ tableCells: true }] : paintedTarget ? [{ offsetSpace: "selection" }] : [])));
 			} catch {
 				return done({
 					ok: false,
@@ -12832,6 +13054,10 @@ function createSuperDocUI(options) {
 	};
 	const commentsSub = sliceHandle((s) => s.comments);
 	const commentsSnap = directorySnapshotHandle(commentsSub, select((s) => computeCommentsDirectorySnapshot(s.selection, s.comments)), "comments");
+	documentResetHooks.push(() => {
+		setExplicitActiveChange(null);
+		explicitActiveCommentId = null;
+	});
 	const comments = {
 		get: commentsSnap.get,
 		getSnapshot: commentsSnap.getSnapshot,
@@ -12925,6 +13151,7 @@ function createSuperDocUI(options) {
 		setActive: (commentId) => {
 			if (commentId == null) {
 				explicitActiveCommentId = null;
+				mirrorReviewFocusToHost("comment", null);
 				recompute();
 				return true;
 			}
@@ -12937,7 +13164,9 @@ function createSuperDocUI(options) {
 			const resolvedId = resolveActiveCommentId(items, commentId);
 			if (!resolvedId) return false;
 			if (!items.some((entry) => readEntityId(entry) === resolvedId)) return false;
+			setExplicitActiveChange(null);
 			explicitActiveCommentId = resolvedId;
+			mirrorReviewFocusToHost("comment", { id: resolvedId });
 			recompute();
 			return true;
 		},
@@ -12997,7 +13226,7 @@ function createSuperDocUI(options) {
 	};
 	const navigateAndScrollCurrentRequest = async (step, requestedAtInvalidation) => {
 		if (queuedTrackChangeNavigationInvalidation !== requestedAtInvalidation) return { success: false };
-		const previousActiveChange = explicitActiveChange;
+		const previousFocus = readReviewFocus();
 		const activeId = navigateTrackChange(step, { invalidateQueuedNavigation: false });
 		if (activeId == null) return { success: false };
 		const optimisticActiveChange = explicitActiveChange;
@@ -13005,7 +13234,7 @@ function createSuperDocUI(options) {
 		const isCurrent = () => queuedTrackChangeNavigationInvalidation === requestedAtInvalidation && explicitActiveChange === optimisticActiveChange && explicitActiveChangeRevision === optimisticRevision;
 		const rollback = () => {
 			if (!isCurrent()) return;
-			setExplicitActiveChange(previousActiveChange, { invalidateQueuedNavigation: false });
+			restoreReviewFocus(previousFocus);
 			recompute();
 		};
 		if (optimisticActiveChange) pendingTrackChangeRevealFocuses.add(optimisticActiveChange);
@@ -13025,10 +13254,8 @@ function createSuperDocUI(options) {
 					shouldContinue: isCurrent
 				});
 				if (!isCurrent()) return { success: false };
-				if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) {
-					rollback();
-					mirrorTrackedChangeFocusToHost(previousActiveChange);
-				} else {
+				if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) rollback();
+				else {
 					if (result.ok) await restampVisibleTrackedChangeCarrierAliases(activeId);
 					if (!isCurrent()) return { success: false };
 					mirrorTrackedChangeFocusToHost(optimisticActiveChange);
@@ -13159,7 +13386,7 @@ function createSuperDocUI(options) {
 			const matchingRow = matchStory ? loadedItems.find((item) => entityRowMatchesRequest(item, publicId, matchStory)) : loadedItems.find((item) => readEntityId(item) === publicId);
 			const story = matchStory ? requestedStory : readEntityRequestStory(matchingRow);
 			const importedId = deriveTrackedChangeImportedId(matchingRow);
-			const previousActiveChange = explicitActiveChange;
+			const previousFocus = readReviewFocus();
 			const requestedActiveChange = {
 				id: publicId,
 				...story ? { story } : {},
@@ -13187,7 +13414,7 @@ function createSuperDocUI(options) {
 				const isCurrent = () => trackChangeRevealInvalidation === revealInvalidation && explicitActiveChange === optimisticActiveChange && explicitActiveChangeRevision === optimisticRevision;
 				const rollback = () => {
 					if (!isCurrent()) return;
-					setExplicitActiveChange(previousActiveChange, { invalidateQueuedNavigation: false });
+					restoreReviewFocus(previousFocus);
 					recompute();
 				};
 				recompute();
@@ -13201,10 +13428,8 @@ function createSuperDocUI(options) {
 						success: false,
 						ok: false
 					};
-					if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) {
-						rollback();
-						mirrorTrackedChangeFocusToHost(previousActiveChange);
-					} else {
+					if (!result.ok && result.reason !== SUPERDOC_UI_REASONS.targetNotVisible) rollback();
+					else {
 						if (result.ok) await restampVisibleTrackedChangeCarrierAliases(publicId);
 						if (!isCurrent()) return {
 							success: false,
@@ -13539,14 +13764,14 @@ function createSuperDocUI(options) {
 		if (root instanceof HTMLElement) return root;
 		return null;
 	};
-	const pointEntityHits = (x, y) => {
-		if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return [];
+	const pointHitElements = (x, y) => {
+		if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return null;
 		const dom = globalThis.document;
-		if (!dom || typeof dom.elementFromPoint !== "function") return [];
+		if (!dom || typeof dom.elementFromPoint !== "function") return null;
 		const container = resolveVisibleHost();
-		if (!container) return [];
+		if (!container) return null;
 		const startEl = dom.elementFromPoint(x, y);
-		if (!startEl || !container.contains(startEl)) return [];
+		if (!startEl || !container.contains(startEl)) return null;
 		const primaryEls = [startEl];
 		const addPrimaryEl = (el) => {
 			if (el && container.contains(el) && !primaryEls.includes(el)) primaryEls.push(el);
@@ -13561,6 +13786,17 @@ function createSuperDocUI(options) {
 			}
 			for (const el of stacked) addPrimaryEl(el);
 		}
+		return {
+			container,
+			elements: primaryEls,
+			x,
+			y
+		};
+	};
+	const pointEntityHits = (x, y) => {
+		const point = pointHitElements(x, y);
+		if (!point) return [];
+		const { container, elements: primaryEls } = point;
 		const markerEls = [];
 		const addMarkerEl = (el) => {
 			if (el && container.contains(el) && !markerEls.includes(el) && !primaryEls.includes(el)) markerEls.push(el);
@@ -13574,7 +13810,7 @@ function createSuperDocUI(options) {
 			} catch {
 				return false;
 			}
-			return rect != null && x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;
+			return rect != null && point.x >= rect.left && point.x <= rect.right && point.y >= rect.top && point.y <= rect.bottom;
 		};
 		for (const el of primaryEls) {
 			const queryAll = el.querySelectorAll;
@@ -13598,6 +13834,18 @@ function createSuperDocUI(options) {
 		const seen = /* @__PURE__ */ new Set();
 		const hits = [];
 		for (const hit of rawHits) {
+			if (hit.type === "decoration") {
+				const owner = decorationOwnerForProvider(hit.id);
+				if (!owner) continue;
+				const key = `decoration:${owner.id}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				hits.push({
+					type: "decoration",
+					id: owner.id
+				});
+				continue;
+			}
 			if (hit.type !== "trackedChange") {
 				const layoutStory = hit.type === "contentControl" ? layoutStoryDatasetToStoryLocator(hit.story) : void 0;
 				const story = hit.type === "contentControl" ? isTextboxStory(layoutStory) ? layoutStory : storyKeyToStoryLocator(hit.storyKey) ?? layoutStory : void 0;
@@ -13753,6 +14001,149 @@ function createSuperDocUI(options) {
 		if (status !== "ready") return { reason: "not-ready" };
 		return value ? { target: value } : { reason: "unresolved" };
 	};
+	const liveDecorations = /* @__PURE__ */ new Map();
+	const decorationOwnerForProvider = (providerId) => {
+		const owner = currentHostVisuals()?.providerOwner?.(providerId);
+		return isPlainObject(owner) && typeof owner.id === "string" ? owner : null;
+	};
+	const currentHostVisuals = () => getEditor()?.visuals ?? null;
+	const decorationListeners = /* @__PURE__ */ new Set();
+	let detachDecorationPointer = null;
+	let hoveredDecorations = [];
+	let lastPointer = {
+		clientX: 0,
+		clientY: 0
+	};
+	const decorationIdsAt = (x, y) => {
+		const point = pointHitElements(x, y);
+		if (!point) return [];
+		const ids = /* @__PURE__ */ new Set();
+		for (const element of point.elements) for (const provider of collectDecorationProvidersFromChain(element, point.container)) {
+			const owner = decorationOwnerForProvider(provider);
+			if (owner) ids.add(owner.id);
+		}
+		return [...ids];
+	};
+	const decorationData = (id) => {
+		const owner = currentHostVisuals()?.ownerById?.(id);
+		return isPlainObject(owner?.data) ? owner.data : void 0;
+	};
+	const emitDecorationEvent = (type, decoration, point) => {
+		const payload = {
+			type,
+			id: decoration.id,
+			...decoration.data ? { data: decoration.data } : {},
+			clientX: point.clientX,
+			clientY: point.clientY
+		};
+		for (const listener of Array.from(decorationListeners)) safeCall(() => listener(payload), void 0);
+	};
+	const leaveHoveredDecorations = (onlyId) => {
+		const leaving = hoveredDecorations.filter((decoration) => onlyId === void 0 || decoration.id === onlyId);
+		hoveredDecorations = hoveredDecorations.filter((decoration) => !leaving.includes(decoration));
+		for (const decoration of leaving) emitDecorationEvent("hover-leave", decoration, lastPointer);
+	};
+	const attachDecorationPointer = () => {
+		if (detachDecorationPointer || decorationListeners.size === 0) return;
+		const host = resolveVisibleHost();
+		if (!host) return;
+		const onClick = (event) => {
+			for (const id of decorationIdsAt(event.clientX, event.clientY)) emitDecorationEvent("click", {
+				id,
+				data: decorationData(id)
+			}, event);
+		};
+		const onMove = (event) => {
+			lastPointer = {
+				clientX: event.clientX,
+				clientY: event.clientY
+			};
+			const nextIds = decorationIdsAt(event.clientX, event.clientY);
+			const leaving = hoveredDecorations.filter((decoration) => !nextIds.includes(decoration.id));
+			const kept = hoveredDecorations.filter((decoration) => nextIds.includes(decoration.id));
+			const entering = nextIds.filter((id) => !kept.some((decoration) => decoration.id === id)).map((id) => ({
+				id,
+				data: decorationData(id)
+			}));
+			hoveredDecorations = [...kept, ...entering];
+			for (const decoration of leaving) emitDecorationEvent("hover-leave", decoration, event);
+			for (const decoration of entering) emitDecorationEvent("hover-enter", decoration, event);
+		};
+		const onLeave = (event) => {
+			lastPointer = {
+				clientX: event.clientX,
+				clientY: event.clientY
+			};
+			leaveHoveredDecorations();
+		};
+		host.addEventListener("click", onClick);
+		host.addEventListener("pointermove", onMove);
+		host.addEventListener("pointerleave", onLeave);
+		detachDecorationPointer = () => {
+			host.removeEventListener("click", onClick);
+			host.removeEventListener("pointermove", onMove);
+			host.removeEventListener("pointerleave", onLeave);
+			leaveHoveredDecorations();
+			detachDecorationPointer = null;
+		};
+	};
+	const subscribeDecorationPointer = (listener) => {
+		if (disposed) throw new Error("ui.decorations.subscribe called on a destroyed UI controller.");
+		decorationListeners.add(listener);
+		attachDecorationPointer();
+		return () => {
+			decorationListeners.delete(listener);
+			if (decorationListeners.size === 0) detachDecorationPointer?.();
+		};
+	};
+	documentResetHooks.push(() => {
+		leaveHoveredDecorations();
+		const current = currentHostVisuals();
+		for (const [handle, owner] of Array.from(liveDecorations)) if (owner.visuals !== current || owner.generation !== current.generation()) handle.dispose();
+	});
+	activeEditorResetHooks.push(() => {
+		detachDecorationPointer?.();
+		attachDecorationPointer();
+	});
+	const createDecorationsHandle = (track) => ({
+		subscribe: (listener) => {
+			const unsubscribe = subscribeDecorationPointer(listener);
+			track?.({ dispose: unsubscribe });
+			return unsubscribe;
+		},
+		highlight: (id, options) => {
+			if (disposed) throw new Error("ui.decorations.highlight called on a destroyed UI controller.");
+			const visuals = currentHostVisuals();
+			if (!visuals) throw new Error("ui.decorations.highlight requires a ready document.");
+			const inner = visuals.highlight(id, options);
+			let handleDisposed = false;
+			const handle = {
+				id: inner.id,
+				replace: (targets) => inner.replace(targets),
+				add: (targets) => inner.add(targets),
+				clear: () => {
+					if (handleDisposed) return;
+					inner.clear();
+					leaveHoveredDecorations(inner.id);
+				},
+				invalidate: () => inner.invalidate(),
+				dispose: () => {
+					if (handleDisposed) return;
+					handleDisposed = true;
+					liveDecorations.delete(handle);
+					inner.dispose();
+					leaveHoveredDecorations(inner.id);
+				}
+			};
+			liveDecorations.set(handle, {
+				visuals,
+				generation: visuals.generation()
+			});
+			track?.(handle);
+			return handle;
+		}
+	});
+	const decorations = createDecorationsHandle();
 	const viewport = {
 		getRects: async (input) => {
 			const initialHost = getHost();
@@ -14730,6 +15121,92 @@ function createSuperDocUI(options) {
 			}
 		}, 120);
 	};
+	const updateStyleToMatchSelection = (input) => {
+		const mode = readDocumentMode();
+		if (mode === "viewing") return failedReceipt("The document is read-only.", "DOCUMENT_READONLY");
+		if (mode === "suggesting") return failedReceipt("A style definition cannot be changed as a tracked suggestion.", "PRECONDITION_FAILED");
+		const sourceToken = contentToken();
+		const readPositionKey = () => {
+			const snapshot = readHostSelectionSnapshot();
+			if (!snapshot) return null;
+			return JSON.stringify({
+				story: snapshot.story,
+				tableCells: snapshot.tableCells,
+				points: ["anchor", "focus"].map((side) => {
+					const point = snapshot[side];
+					return point ? [
+						point.blockId,
+						point.blockOffset,
+						point.trackedBlockOffset,
+						point.story,
+						point.inlineAffinity,
+						point.outsideContentControl,
+						point.visualCaret
+					] : null;
+				})
+			});
+		};
+		const requestedPosition = readPositionKey();
+		const stale = failedReceipt("The selection or document changed while reading its style.", "REVISION_MISMATCH");
+		return readSelectionInfoFresh().then((selection) => {
+			const selectionToken = selectionKey(selection);
+			const isCurrent = () => !disposed && contentToken() === sourceToken && readPositionKey() === requestedPosition && selectionKey(state.selection) === selectionToken && readDocumentMode() === mode;
+			if (!isCurrent()) return stale;
+			const active = computeActiveParagraphStyle(selection, getStyleCatalog().cache).style;
+			const story = storyLocatorSignature(selectionStory(selection));
+			const keys = [styleCatalogReadKey({ includePreview: true }), ...selectionBlockIds(selection).map((id) => `node:${story}:${id}`)];
+			const unreadable = failedReceipt("The selection formatting could not be read.", "PRECONDITION_FAILED");
+			const run = (active) => {
+				if (keys.some((key) => {
+					const entry = asyncReads.get(key);
+					return entry && (!entry.hasSettled || entry.token !== sourceToken || entry.failedToken === sourceToken);
+				})) return unreadable;
+				const styleId = input?.styleId ?? active.styleId;
+				if (!styleId) return failedReceipt("Choose a style to update: the selection does not have a single paragraph style.", "INVALID_TARGET");
+				const doc = getDoc();
+				const readSelection = resolveDocOperation(doc, "format.readSelection");
+				const apply = resolveDocOperation(doc, "styles.apply");
+				if (!readSelection || !apply) return failedReceipt("Updating a style to match the selection is unavailable.");
+				let reads;
+				try {
+					reads = [readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "effective"
+					}), readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "direct"
+					})];
+				} catch {
+					return unreadable;
+				}
+				return Promise.all(reads).then(([effective, direct]) => {
+					if (!isCurrent()) return stale;
+					const patch = buildStyleMatchPatch(effective, direct, { selectionUsesStyle: !active.mixed && active.styleId === styleId });
+					if (Object.keys(patch).length === 0) return failedReceipt("The selection already matches the style.", "NO_OP");
+					const fallback = failedReceipt("Updating the style failed.");
+					return safeCall(() => settleWorkflowReceipt(apply({
+						target: {
+							scope: "style",
+							styleId,
+							channel: "run"
+						},
+						patch
+					}), fallback), fallback);
+				}, () => unreadable);
+			};
+			const pending = keys.flatMap((key) => {
+				const entry = asyncReads.get(key);
+				return entry?.inflightToken === sourceToken && entry.settled ? [entry.settled] : [];
+			});
+			if (pending.length === 0) return run(active);
+			return Promise.all(pending).then(() => {
+				if (!isCurrent()) return stale;
+				return run(computeActiveParagraphStyle(selection, getStyleCatalog().cache).style);
+			});
+		});
+	};
 	const stylesSub = sliceHandle((s) => s.styles);
 	const stylesSnap = snapshotHandle(stylesSub);
 	const styles = {
@@ -14742,7 +15219,8 @@ function createSuperDocUI(options) {
 			return readStyleCatalogLive(options).value;
 		},
 		getQuickGallery: () => stylesSub.get().quickGallery,
-		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style
+		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style,
+		updateToMatchSelection: (input) => updateStyleToMatchSelection(input)
 	};
 	const openWatermarkSurface = hostMethod(superdoc, "openSurface");
 	const watermark = createWatermarkController({
@@ -14757,6 +15235,7 @@ function createSuperDocUI(options) {
 	const createScope = () => {
 		const scopeUnsubs = [];
 		return {
+			decorations: createDecorationsHandle((handle) => scopeUnsubs.push(() => handle.dispose())),
 			select: (selector, equality) => {
 				const sub = select(selector, equality);
 				return {
@@ -14777,6 +15256,9 @@ function createSuperDocUI(options) {
 		if (disposed) return;
 		watermark.destroy();
 		clearContentControlHighlight();
+		for (const handle of Array.from(liveDecorations.keys())) handle.dispose();
+		detachDecorationPointer?.();
+		decorationListeners.clear();
 		disposed = true;
 		completedFallbackSearch = null;
 		if (searchRefreshTimer !== null) clearTimeout(searchRefreshTimer);
@@ -14859,6 +15341,7 @@ function createSuperDocUI(options) {
 		zoom,
 		document: documentHandle,
 		viewport,
+		decorations,
 		metadata,
 		tables,
 		search,
@@ -15077,4 +15560,4 @@ function commandIsActive(descriptor, selection) {
 	return descriptor.activeMark ? selection.activeMarks.includes(descriptor.activeMark) : false;
 }
 //#endregion
-export { getWorkflowRecording as _, registerFirstPartyCommandMutation as a, getV2TrackedChangeMutationImpact as c, resolveImageSrc as d, shallowEqual as f, createInteractionHistory as g, closeInteractionHistory as h, readFirstPartyPageNumbers as i, isPlainObject as l, DOM_CLASS_NAMES as m, executeFirstPartyCommandAsync as n, BUILT_IN_COMMAND_IDS as o, isSyntheticTrackedChangeCommentLaneItem as p, executeFirstPartyShortcutAsync as r, applyV2CommentInvalidationFromMutation as s, createSuperDocUI as t, createImageFilePicker as u, isWorkflowRecordingEnabled as v, recordInteraction as y };
+export { createInteractionHistory as _, registerFirstPartyCommandMutation as a, recordInteraction as b, applyV2CommentInvalidationFromMutation as c, createImageFilePicker as d, resolveImageSrc as f, closeInteractionHistory as g, DOM_CLASS_NAMES as h, readFirstPartyPageNumbers as i, getV2TrackedChangeMutationImpact as l, isSyntheticTrackedChangeCommentLaneItem as m, executeFirstPartyCommandAsync as n, isRecord as o, shallowEqual as p, executeFirstPartyShortcutAsync as r, BUILT_IN_COMMAND_IDS as s, createSuperDocUI as t, isPlainObject as u, getWorkflowRecording as v, isWorkflowRecordingEnabled as y };