superdoc 2.28.0-next.6 → 2.28.0-next.8

package/dist/chunks/{create-super-doc-ui-D1eOhAjv.cjs → create-super-doc-ui-B4c55pFy.cjs}

@@ -3692,6 +3692,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);
 }
@@ -3763,6 +3782,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}`;
@@ -6153,6 +6182,7 @@ function createSuperDocUI(options) {
 		pointerSelecting: false,
 		keyboardSelecting: false
 	};
+	const paintedInlineTargets = /* @__PURE__ */ new WeakSet();
 	let painterCaptureEpoch = 0;
 	let painterCommandDoc = null;
 	const painterModeListeners = /* @__PURE__ */ new Set();
@@ -6249,7 +6279,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;
@@ -6463,7 +6493,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);
@@ -6474,15 +6504,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;
 		}
@@ -6490,10 +6520,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;
@@ -7553,15 +7595,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));
@@ -7570,21 +7650,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,
@@ -7742,7 +7808,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),
@@ -8387,12 +8453,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 } : {}
 		};
 	}
@@ -8530,7 +8597,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;
 	};
@@ -9076,7 +9147,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 {
@@ -9285,7 +9357,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 {
@@ -9962,14 +10038,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;
@@ -9990,10 +10067,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;
@@ -10018,7 +10120,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,
@@ -10396,11 +10498,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;
@@ -10554,7 +10661,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",
@@ -10894,25 +11001,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();
@@ -10932,10 +11049,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. */
@@ -11164,13 +11286,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;
@@ -11710,23 +11835,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;
@@ -12147,10 +12281,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));
@@ -12168,7 +12315,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) {
@@ -12176,10 +12323,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();
@@ -12197,7 +12344,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;
@@ -12435,13 +12582,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;
 		},
@@ -12467,7 +12617,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
@@ -12480,7 +12636,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,
@@ -12899,6 +13055,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,
@@ -12992,6 +13152,7 @@ function createSuperDocUI(options) {
 		setActive: (commentId) => {
 			if (commentId == null) {
 				explicitActiveCommentId = null;
+				mirrorReviewFocusToHost("comment", null);
 				recompute();
 				return true;
 			}
@@ -13004,7 +13165,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;
 		},
@@ -13064,7 +13227,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;
@@ -13072,7 +13235,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);
@@ -13092,10 +13255,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);
@@ -13226,7 +13387,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 } : {},
@@ -13254,7 +13415,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();
@@ -13268,10 +13429,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,
@@ -13606,14 +13765,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);
@@ -13628,6 +13787,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);
@@ -13641,7 +13811,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;
@@ -13665,6 +13835,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;
@@ -13820,6 +14002,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();
@@ -14911,6 +15236,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 {
@@ -14931,6 +15257,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);
@@ -15013,6 +15342,7 @@ function createSuperDocUI(options) {
 		zoom,
 		document: documentHandle,
 		viewport,
+		decorations,
 		metadata,
 		tables,
 		search,
@@ -15303,6 +15633,12 @@ Object.defineProperty(exports, "isPlainObject", {
 		return isPlainObject;
 	}
 });
+Object.defineProperty(exports, "isRecord", {
+	enumerable: true,
+	get: function() {
+		return isRecord;
+	}
+});
 Object.defineProperty(exports, "isSyntheticTrackedChangeCommentLaneItem", {
 	enumerable: true,
 	get: function() {