superdoc 2.20.0-next.9 → 2.20.1-next.1

package/README.md

@@ -28,3 +28,29 @@ See [package compatibility](https://docs.superdoc.dev/resources/package-compatib
 ## License
 
 AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
+
+## Navigate to a bookmark
+
+After the V2 browser editor is ready, navigate by an exact bookmark name:
+
+```js
+const result = await editor.ui.bookmarks.navigateTo('Terms');
+if (!result.success) console.log(result.reason);
+```
+
+You can also pass a `BookmarkAddress` returned by `editor.activeEditor.doc.bookmarks.get()`
+or `.list()`. The method reveals the bookmark's start and selects its complete range,
+including across paragraphs. A collapsed bookmark places a caret. It supports editing,
+suggesting, and viewing modes. Navigation stays local in a shared room and does not change
+content or another client's selection. It does not take native keyboard focus.
+
+Scrolling defaults to instant, centered navigation. Pass `{ block: 'start', behavior: 'auto' }`
+as a second argument to change alignment or scrolling behavior.
+
+The first release supports body bookmarks. Non-body and table-column bookmarks, malformed,
+missing, deleted, or ambiguous targets return `{ success: false, ok: false, reason: 'target-unresolved' }`.
+Name-only lookup requires a unique match across the document; an explicit body address scopes
+lookup to the body. Resolution or reveal failure preserves the existing selection. Navigation
+abandons stale work after content changes, document replacement, or a newer request, and times
+out after 15 seconds. Missing editor or host capabilities return their readiness or availability
+reason. The handle and address types are exported from `superdoc/ui`.

package/dist/chunks/{create-super-doc-ui-B8olYVBF.es.js → create-super-doc-ui-B4_V1haj.es.js}

@@ -4219,6 +4219,14 @@ function readCollapsedHostTrackChangeId(snapshot) {
 	const focusId = focusVisual?.trackChangeId;
 	return typeof anchorId === "string" && anchorId.length > 0 && anchorId === focusId ? anchorId : null;
 }
+function isNonCollapsedHostSelection(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") return false;
+	const record = snapshot;
+	const anchor = record.anchor;
+	const focus = record.focus;
+	if (typeof anchor?.blockId !== "string" || !anchor.blockId || typeof focus?.blockId !== "string" || !focus.blockId || !Number.isFinite(anchor.blockOffset) || !Number.isFinite(focus.blockOffset)) return false;
+	return anchor.blockId !== focus.blockId || anchor.blockOffset !== focus.blockOffset || Number.isFinite(anchor.trackedBlockOffset) && Number.isFinite(focus.trackedBlockOffset) && anchor.trackedBlockOffset !== focus.trackedBlockOffset;
+}
 var trackedChangeIdContextCache = /* @__PURE__ */ new WeakMap();
 /**
 * Collect the raw source-provenance ids a tracked-change list item exposes,
@@ -6250,7 +6258,7 @@ function createSuperDocUI(options) {
 				}
 				if (pendingPostPaintSelectionRefresh) continue;
 				selectionEpoch += 1;
-				seedCaretSelectionFromHost();
+				refreshSelectionFromHost();
 				recompute(paintCompleted ? "post-paint-selection" : "post-paint-selection-failed");
 			}
 		};
@@ -6647,8 +6655,9 @@ function createSuperDocUI(options) {
 	* effective font resolved from it) on the next recompute, instead of serving
 	* the previous selection until the worker `selection.current` round-trip lands
 	* (SD-3652). Only a resolvable COLLAPSED CARET is seeded - a range's snapshot
-	* cannot be resolved synchronously in worker mode, so ranges defer to the async
-	* read (seeding an empty value would wrongly disable range-only commands). The
+	* cannot be resolved synchronously in worker mode, so a new range starts an
+	* authoritative async read without waiting for the input-idle gate (SD-5394).
+	* Seeding an empty value would wrongly disable range-only commands. The
 	* authoritative async read still overwrites marks/text/review overlap, but
 	* foreground typing defers and coalesces that worker hop through the shared
 	* retry gate. Previous marks are carried forward for toolbar continuity. A
@@ -6656,14 +6665,19 @@ function createSuperDocUI(options) {
 	* same carrier, or while an active typing dispatch advances the same caret by
 	* one code point. Pending work alone never carries review command context.
 	*/
-	const seedCaretSelectionFromHost = (hostSelectionSnapshot) => {
+	const refreshSelectionFromHost = (hostSelectionSnapshot) => {
+		const foreground = foregroundMutationState();
+		if (isNonCollapsedHostSelection(hostSelectionSnapshot) && !(foreground && foreground.active > 0)) {
+			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));
 		if (!seed || !isCollapsedCaretSnapshot(seed)) return;
 		const token = selectionReadToken();
-		const foreground = foregroundMutationState();
 		const deferAuthoritativeRead = Boolean(foreground && (foreground.active > 0 || foreground.pending > 0));
 		if (!deferAuthoritativeRead) {
 			pendingSelectionSeedValidationToken = null;
@@ -8895,7 +8909,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				if (foregroundMutationActive() && caretSelectionNeedsProjectionPaint() && schedulePostPaintSelectionRefresh()) return;
 				selectionEpoch += 1;
-				seedCaretSelectionFromHost(snapshot);
+				refreshSelectionFromHost(snapshot);
 				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
@@ -11274,6 +11288,113 @@ function createSuperDocUI(options) {
 			};
 		}
 	};
+	let bookmarkNavigationGeneration = 0;
+	documentResetHooks.push(() => {
+		bookmarkNavigationGeneration += 1;
+	});
+	const bookmarks = { navigateTo: async (input, options) => {
+		const generation = ++bookmarkNavigationGeneration;
+		const unresolved = () => ({
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.targetUnresolved
+		});
+		const address = typeof input === "string" ? {
+			kind: "entity",
+			entityType: "bookmark",
+			name: input
+		} : input;
+		if (!address || address.kind !== "entity" || address.entityType !== "bookmark" || typeof address.name !== "string" || address.name.length === 0 || address.story !== void 0 && (!address.story || address.story.kind !== "story" || address.story.storyType !== "body")) return unresolved();
+		const editor = getEditor();
+		if (!editor || disposed) return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.notReady
+		};
+		const doc = getDoc();
+		const api = doc?.bookmarks;
+		if (typeof api?.list !== "function" || typeof api?.get !== "function") return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.operationUnavailable
+		};
+		const helper = getSelectionApplyHelper();
+		if (!("helper" in helper)) return {
+			success: false,
+			ok: false,
+			reason: helper.reason
+		};
+		const host = getHost();
+		if (typeof host?.scrollTargetIntoView !== "function") return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.hostCapabilityUnavailable
+		};
+		const token = metadataResolutionToken();
+		let active = true;
+		const current = () => active && !disposed && generation === bookmarkNavigationGeneration && getEditor() === editor && getDoc() === doc && getHost() === host && metadataResolutionToken() === token;
+		const run = async () => {
+			try {
+				const directory = await api.list.call(api, address.story ? { in: address.story } : {});
+				if (!current()) return unresolved();
+				if ((Array.isArray(directory?.items) ? directory.items : []).filter((item) => item?.name === address.name).length !== 1) return unresolved();
+				const info = await api.get.call(api, { target: address });
+				if (!current()) return unresolved();
+				const from = info?.range?.from;
+				const to = info?.range?.to;
+				const pointValid = (point) => typeof point?.blockId === "string" && point.blockId.length > 0 && Number.isInteger(point.offset) && point.offset >= 0;
+				if (info?.name !== address.name || info?.address?.story && info.address.story.storyType !== "body" || info?.tableColumn || !pointValid(from) || !pointValid(to) || from.blockId === to.blockId && from.offset > to.offset) return unresolved();
+				const result = await scrollTargetIntoView({
+					kind: "text",
+					segments: [{
+						blockId: from.blockId,
+						range: {
+							start: from.offset,
+							end: from.offset
+						}
+					}]
+				}, {
+					block: options?.block ?? "center",
+					behavior: options?.behavior ?? "instant",
+					shouldContinue: current
+				});
+				if (!current()) return unresolved();
+				if (!result.ok) return result;
+				const applied = selection.apply({
+					kind: "selection",
+					start: {
+						kind: "text",
+						blockId: from.blockId,
+						offset: from.offset
+					},
+					end: {
+						kind: "text",
+						blockId: to.blockId,
+						offset: to.offset
+					}
+				});
+				return {
+					...applied,
+					success: applied.ok
+				};
+			} catch {
+				return unresolved();
+			}
+		};
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				active = false;
+				resolve(unresolved());
+			}, 15e3);
+		});
+		try {
+			return await Promise.race([run(), timeout]);
+		} finally {
+			active = false;
+			clearTimeout(timer);
+		}
+	} };
 	/**
 	* Derive the browser-shell's `importedId` carrier-lookup alias from a
 	* public list row's `wordRevisionIds` / `sourceIds` provenance fields,
@@ -12507,6 +12628,7 @@ function createSuperDocUI(options) {
 	};
 	let searchRequestGeneration = 0;
 	let pendingFallbackGeneration = null;
+	let completedFallbackSearch = null;
 	/**
 	* How to tear down the session that is currently open, captured when it was
 	* opened.
@@ -12555,6 +12677,7 @@ function createSuperDocUI(options) {
 	* is deliberately not made here.
 	*/
 	const resetSearchForActiveEditorChange = () => {
+		completedFallbackSearch = null;
 		searchRequestGeneration += 1;
 		pendingFallbackGeneration = null;
 		shellFallbackOutstanding = false;
@@ -12608,8 +12731,8 @@ function createSuperDocUI(options) {
 		const editSearch = getEditCommandSearch();
 		if (editSearch && typeof editSearch.query === "function") safeCall(() => editSearch.query({ query: "" }), null);
 	};
-	const readEditCommandCanReplace = () => readEditCommandStateEntry("find.replace")?.enabled === true;
-	const readEditCommandCanReplaceAll = () => readEditCommandStateEntry("find.replaceAll")?.enabled === true;
+	const readEditCommandCanReplace = () => pendingFallbackGeneration !== searchRequestGeneration && readEditCommandStateEntry("find.replace")?.enabled === true;
+	const readEditCommandCanReplaceAll = () => pendingFallbackGeneration !== searchRequestGeneration && readEditCommandStateEntry("find.replaceAll")?.enabled === true;
 	const applyHostSearchResult = (result, fallbackCanReplace = false, fallbackCanReplaceAll = fallbackCanReplace) => {
 		const snapshot = normalizeHostSearchResult(result, fallbackCanReplace, fallbackCanReplaceAll);
 		if (!snapshot) {
@@ -12770,6 +12893,7 @@ function createSuperDocUI(options) {
 			return { ok: true };
 		},
 		close: () => {
+			completedFallbackSearch = null;
 			searchRequestGeneration += 1;
 			cancelRefreshShellSearch();
 			if (releaseActiveSearchSession) releaseSearchSession();
@@ -12794,6 +12918,16 @@ function createSuperDocUI(options) {
 			const caseSensitive = Boolean(options?.caseSensitive);
 			const includeDeletedText = (options?.includeTrackedDeletions ?? options?.includeDeletedText) === true;
 			const regex = options?.regex === true;
+			if ((!host || typeof host.setSession !== "function") && completedFallbackSearch !== null && completedFallbackSearch === getEditCommandSearch() && pendingFallbackGeneration !== searchRequestGeneration && searchRefreshTimer === null && searchState.open && searchState.available && !searchState.reason && searchState.query === query && searchState.caseSensitive === caseSensitive && searchState.includeDeletedText === includeDeletedText && searchState.regex === regex) {
+				syncSearchStateFromHost();
+				emitSearch();
+				return searchState;
+			}
+			completedFallbackSearch = null;
+			if (searchRefreshTimer !== null) {
+				clearTimeout(searchRefreshTimer);
+				searchRefreshTimer = null;
+			}
 			const generation = ++searchRequestGeneration;
 			cancelRefreshShellSearch();
 			cancelOutstandingShellFallback();
@@ -12829,6 +12963,7 @@ function createSuperDocUI(options) {
 							if (generation !== searchRequestGeneration) return;
 							shellFallbackOutstanding = false;
 							pendingFallbackGeneration = null;
+							completedFallbackSearch = editSearch;
 							applyHostSearchResult(resolved, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 						}, () => {
 							if (generation !== searchRequestGeneration) return;
@@ -12841,6 +12976,7 @@ function createSuperDocUI(options) {
 						return searchState;
 					}
 					pendingFallbackGeneration = null;
+					completedFallbackSearch = editSearch;
 					applyHostSearchResult(result, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 					applyHostSearchResult(safeCall(() => editSearch.getState(), null), readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 					return searchState;
@@ -12983,6 +13119,7 @@ function createSuperDocUI(options) {
 			return { ok: true };
 		},
 		clear: () => {
+			completedFallbackSearch = null;
 			searchRequestGeneration += 1;
 			cancelRefreshShellSearch();
 			cancelOutstandingShellFallback();
@@ -13098,6 +13235,7 @@ function createSuperDocUI(options) {
 	};
 	let searchRefreshTimer = null;
 	scheduleActiveSearchRefresh = () => {
+		completedFallbackSearch = null;
 		if (searchRefreshTimer !== null) clearTimeout(searchRefreshTimer);
 		if (!searchState.open || !searchState.query) return;
 		const scheduledGeneration = searchRequestGeneration;
@@ -13124,19 +13262,29 @@ function createSuperDocUI(options) {
 			const result = typeof editSearch?.refresh === "function" ? safeCall(() => editSearch.refresh(input), null) : safeCall(() => host.refresh(), null);
 			if (isPromiseLike(result)) {
 				pendingFallbackGeneration = generation;
+				setSearchState({
+					canReplace: false,
+					canReplaceAll: false
+				});
 				Promise.resolve(result).then((resolved) => {
 					if (generation !== searchRequestGeneration || disposed) return;
+					releaseRefreshShellSearch = null;
 					pendingFallbackGeneration = null;
+					completedFallbackSearch = editSearch;
 					applyHostSearchResult(resolved, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 				}, () => {
 					if (generation !== searchRequestGeneration || disposed) return;
-					pendingFallbackGeneration = null;
+					releaseRefreshShellSearch = null;
 					setSearchState({
 						available: false,
 						reason: SUPERDOC_UI_REASONS.searchUnavailable
 					});
 				});
-			} else if (result !== null) applyHostSearchResult(result);
+			} else if (result !== null) {
+				releaseRefreshShellSearch = null;
+				completedFallbackSearch = editSearch;
+				applyHostSearchResult(result);
+			}
 		}, 120);
 	};
 	const stylesSub = sliceHandle((s) => s.styles);
@@ -13186,6 +13334,7 @@ function createSuperDocUI(options) {
 		watermark.destroy();
 		clearContentControlHighlight();
 		disposed = true;
+		completedFallbackSearch = null;
 		if (searchRefreshTimer !== null) clearTimeout(searchRefreshTimer);
 		searchRefreshTimer = null;
 		cancelRefreshShellSearch();
@@ -13261,6 +13410,7 @@ function createSuperDocUI(options) {
 		comments,
 		trackChanges,
 		contentControls,
+		bookmarks,
 		fonts,
 		zoom,
 		document: documentHandle,

package/dist/chunks/{create-super-doc-ui-Dc2QEczb.cjs → create-super-doc-ui-DFCfYEpW.cjs}

@@ -4220,6 +4220,14 @@ function readCollapsedHostTrackChangeId(snapshot) {
 	const focusId = focusVisual?.trackChangeId;
 	return typeof anchorId === "string" && anchorId.length > 0 && anchorId === focusId ? anchorId : null;
 }
+function isNonCollapsedHostSelection(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") return false;
+	const record = snapshot;
+	const anchor = record.anchor;
+	const focus = record.focus;
+	if (typeof anchor?.blockId !== "string" || !anchor.blockId || typeof focus?.blockId !== "string" || !focus.blockId || !Number.isFinite(anchor.blockOffset) || !Number.isFinite(focus.blockOffset)) return false;
+	return anchor.blockId !== focus.blockId || anchor.blockOffset !== focus.blockOffset || Number.isFinite(anchor.trackedBlockOffset) && Number.isFinite(focus.trackedBlockOffset) && anchor.trackedBlockOffset !== focus.trackedBlockOffset;
+}
 var trackedChangeIdContextCache = /* @__PURE__ */ new WeakMap();
 /**
 * Collect the raw source-provenance ids a tracked-change list item exposes,
@@ -6251,7 +6259,7 @@ function createSuperDocUI(options) {
 				}
 				if (pendingPostPaintSelectionRefresh) continue;
 				selectionEpoch += 1;
-				seedCaretSelectionFromHost();
+				refreshSelectionFromHost();
 				recompute(paintCompleted ? "post-paint-selection" : "post-paint-selection-failed");
 			}
 		};
@@ -6648,8 +6656,9 @@ function createSuperDocUI(options) {
 	* effective font resolved from it) on the next recompute, instead of serving
 	* the previous selection until the worker `selection.current` round-trip lands
 	* (SD-3652). Only a resolvable COLLAPSED CARET is seeded - a range's snapshot
-	* cannot be resolved synchronously in worker mode, so ranges defer to the async
-	* read (seeding an empty value would wrongly disable range-only commands). The
+	* cannot be resolved synchronously in worker mode, so a new range starts an
+	* authoritative async read without waiting for the input-idle gate (SD-5394).
+	* Seeding an empty value would wrongly disable range-only commands. The
 	* authoritative async read still overwrites marks/text/review overlap, but
 	* foreground typing defers and coalesces that worker hop through the shared
 	* retry gate. Previous marks are carried forward for toolbar continuity. A
@@ -6657,14 +6666,19 @@ function createSuperDocUI(options) {
 	* same carrier, or while an active typing dispatch advances the same caret by
 	* one code point. Pending work alone never carries review command context.
 	*/
-	const seedCaretSelectionFromHost = (hostSelectionSnapshot) => {
+	const refreshSelectionFromHost = (hostSelectionSnapshot) => {
+		const foreground = foregroundMutationState();
+		if (isNonCollapsedHostSelection(hostSelectionSnapshot) && !(foreground && foreground.active > 0)) {
+			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));
 		if (!seed || !isCollapsedCaretSnapshot(seed)) return;
 		const token = selectionReadToken();
-		const foreground = foregroundMutationState();
 		const deferAuthoritativeRead = Boolean(foreground && (foreground.active > 0 || foreground.pending > 0));
 		if (!deferAuthoritativeRead) {
 			pendingSelectionSeedValidationToken = null;
@@ -8896,7 +8910,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				if (foregroundMutationActive() && caretSelectionNeedsProjectionPaint() && schedulePostPaintSelectionRefresh()) return;
 				selectionEpoch += 1;
-				seedCaretSelectionFromHost(snapshot);
+				refreshSelectionFromHost(snapshot);
 				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
@@ -11275,6 +11289,113 @@ function createSuperDocUI(options) {
 			};
 		}
 	};
+	let bookmarkNavigationGeneration = 0;
+	documentResetHooks.push(() => {
+		bookmarkNavigationGeneration += 1;
+	});
+	const bookmarks = { navigateTo: async (input, options) => {
+		const generation = ++bookmarkNavigationGeneration;
+		const unresolved = () => ({
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.targetUnresolved
+		});
+		const address = typeof input === "string" ? {
+			kind: "entity",
+			entityType: "bookmark",
+			name: input
+		} : input;
+		if (!address || address.kind !== "entity" || address.entityType !== "bookmark" || typeof address.name !== "string" || address.name.length === 0 || address.story !== void 0 && (!address.story || address.story.kind !== "story" || address.story.storyType !== "body")) return unresolved();
+		const editor = getEditor();
+		if (!editor || disposed) return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.notReady
+		};
+		const doc = getDoc();
+		const api = doc?.bookmarks;
+		if (typeof api?.list !== "function" || typeof api?.get !== "function") return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.operationUnavailable
+		};
+		const helper = getSelectionApplyHelper();
+		if (!("helper" in helper)) return {
+			success: false,
+			ok: false,
+			reason: helper.reason
+		};
+		const host = getHost();
+		if (typeof host?.scrollTargetIntoView !== "function") return {
+			success: false,
+			ok: false,
+			reason: SUPERDOC_UI_REASONS.hostCapabilityUnavailable
+		};
+		const token = metadataResolutionToken();
+		let active = true;
+		const current = () => active && !disposed && generation === bookmarkNavigationGeneration && getEditor() === editor && getDoc() === doc && getHost() === host && metadataResolutionToken() === token;
+		const run = async () => {
+			try {
+				const directory = await api.list.call(api, address.story ? { in: address.story } : {});
+				if (!current()) return unresolved();
+				if ((Array.isArray(directory?.items) ? directory.items : []).filter((item) => item?.name === address.name).length !== 1) return unresolved();
+				const info = await api.get.call(api, { target: address });
+				if (!current()) return unresolved();
+				const from = info?.range?.from;
+				const to = info?.range?.to;
+				const pointValid = (point) => typeof point?.blockId === "string" && point.blockId.length > 0 && Number.isInteger(point.offset) && point.offset >= 0;
+				if (info?.name !== address.name || info?.address?.story && info.address.story.storyType !== "body" || info?.tableColumn || !pointValid(from) || !pointValid(to) || from.blockId === to.blockId && from.offset > to.offset) return unresolved();
+				const result = await scrollTargetIntoView({
+					kind: "text",
+					segments: [{
+						blockId: from.blockId,
+						range: {
+							start: from.offset,
+							end: from.offset
+						}
+					}]
+				}, {
+					block: options?.block ?? "center",
+					behavior: options?.behavior ?? "instant",
+					shouldContinue: current
+				});
+				if (!current()) return unresolved();
+				if (!result.ok) return result;
+				const applied = selection.apply({
+					kind: "selection",
+					start: {
+						kind: "text",
+						blockId: from.blockId,
+						offset: from.offset
+					},
+					end: {
+						kind: "text",
+						blockId: to.blockId,
+						offset: to.offset
+					}
+				});
+				return {
+					...applied,
+					success: applied.ok
+				};
+			} catch {
+				return unresolved();
+			}
+		};
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				active = false;
+				resolve(unresolved());
+			}, 15e3);
+		});
+		try {
+			return await Promise.race([run(), timeout]);
+		} finally {
+			active = false;
+			clearTimeout(timer);
+		}
+	} };
 	/**
 	* Derive the browser-shell's `importedId` carrier-lookup alias from a
 	* public list row's `wordRevisionIds` / `sourceIds` provenance fields,
@@ -12508,6 +12629,7 @@ function createSuperDocUI(options) {
 	};
 	let searchRequestGeneration = 0;
 	let pendingFallbackGeneration = null;
+	let completedFallbackSearch = null;
 	/**
 	* How to tear down the session that is currently open, captured when it was
 	* opened.
@@ -12556,6 +12678,7 @@ function createSuperDocUI(options) {
 	* is deliberately not made here.
 	*/
 	const resetSearchForActiveEditorChange = () => {
+		completedFallbackSearch = null;
 		searchRequestGeneration += 1;
 		pendingFallbackGeneration = null;
 		shellFallbackOutstanding = false;
@@ -12609,8 +12732,8 @@ function createSuperDocUI(options) {
 		const editSearch = getEditCommandSearch();
 		if (editSearch && typeof editSearch.query === "function") safeCall(() => editSearch.query({ query: "" }), null);
 	};
-	const readEditCommandCanReplace = () => readEditCommandStateEntry("find.replace")?.enabled === true;
-	const readEditCommandCanReplaceAll = () => readEditCommandStateEntry("find.replaceAll")?.enabled === true;
+	const readEditCommandCanReplace = () => pendingFallbackGeneration !== searchRequestGeneration && readEditCommandStateEntry("find.replace")?.enabled === true;
+	const readEditCommandCanReplaceAll = () => pendingFallbackGeneration !== searchRequestGeneration && readEditCommandStateEntry("find.replaceAll")?.enabled === true;
 	const applyHostSearchResult = (result, fallbackCanReplace = false, fallbackCanReplaceAll = fallbackCanReplace) => {
 		const snapshot = normalizeHostSearchResult(result, fallbackCanReplace, fallbackCanReplaceAll);
 		if (!snapshot) {
@@ -12771,6 +12894,7 @@ function createSuperDocUI(options) {
 			return { ok: true };
 		},
 		close: () => {
+			completedFallbackSearch = null;
 			searchRequestGeneration += 1;
 			cancelRefreshShellSearch();
 			if (releaseActiveSearchSession) releaseSearchSession();
@@ -12795,6 +12919,16 @@ function createSuperDocUI(options) {
 			const caseSensitive = Boolean(options?.caseSensitive);
 			const includeDeletedText = (options?.includeTrackedDeletions ?? options?.includeDeletedText) === true;
 			const regex = options?.regex === true;
+			if ((!host || typeof host.setSession !== "function") && completedFallbackSearch !== null && completedFallbackSearch === getEditCommandSearch() && pendingFallbackGeneration !== searchRequestGeneration && searchRefreshTimer === null && searchState.open && searchState.available && !searchState.reason && searchState.query === query && searchState.caseSensitive === caseSensitive && searchState.includeDeletedText === includeDeletedText && searchState.regex === regex) {
+				syncSearchStateFromHost();
+				emitSearch();
+				return searchState;
+			}
+			completedFallbackSearch = null;
+			if (searchRefreshTimer !== null) {
+				clearTimeout(searchRefreshTimer);
+				searchRefreshTimer = null;
+			}
 			const generation = ++searchRequestGeneration;
 			cancelRefreshShellSearch();
 			cancelOutstandingShellFallback();
@@ -12830,6 +12964,7 @@ function createSuperDocUI(options) {
 							if (generation !== searchRequestGeneration) return;
 							shellFallbackOutstanding = false;
 							pendingFallbackGeneration = null;
+							completedFallbackSearch = editSearch;
 							applyHostSearchResult(resolved, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 						}, () => {
 							if (generation !== searchRequestGeneration) return;
@@ -12842,6 +12977,7 @@ function createSuperDocUI(options) {
 						return searchState;
 					}
 					pendingFallbackGeneration = null;
+					completedFallbackSearch = editSearch;
 					applyHostSearchResult(result, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 					applyHostSearchResult(safeCall(() => editSearch.getState(), null), readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 					return searchState;
@@ -12984,6 +13120,7 @@ function createSuperDocUI(options) {
 			return { ok: true };
 		},
 		clear: () => {
+			completedFallbackSearch = null;
 			searchRequestGeneration += 1;
 			cancelRefreshShellSearch();
 			cancelOutstandingShellFallback();
@@ -13099,6 +13236,7 @@ function createSuperDocUI(options) {
 	};
 	let searchRefreshTimer = null;
 	scheduleActiveSearchRefresh = () => {
+		completedFallbackSearch = null;
 		if (searchRefreshTimer !== null) clearTimeout(searchRefreshTimer);
 		if (!searchState.open || !searchState.query) return;
 		const scheduledGeneration = searchRequestGeneration;
@@ -13125,19 +13263,29 @@ function createSuperDocUI(options) {
 			const result = typeof editSearch?.refresh === "function" ? safeCall(() => editSearch.refresh(input), null) : safeCall(() => host.refresh(), null);
 			if (isPromiseLike(result)) {
 				pendingFallbackGeneration = generation;
+				setSearchState({
+					canReplace: false,
+					canReplaceAll: false
+				});
 				Promise.resolve(result).then((resolved) => {
 					if (generation !== searchRequestGeneration || disposed) return;
+					releaseRefreshShellSearch = null;
 					pendingFallbackGeneration = null;
+					completedFallbackSearch = editSearch;
 					applyHostSearchResult(resolved, readEditCommandCanReplace(), readEditCommandCanReplaceAll());
 				}, () => {
 					if (generation !== searchRequestGeneration || disposed) return;
-					pendingFallbackGeneration = null;
+					releaseRefreshShellSearch = null;
 					setSearchState({
 						available: false,
 						reason: SUPERDOC_UI_REASONS.searchUnavailable
 					});
 				});
-			} else if (result !== null) applyHostSearchResult(result);
+			} else if (result !== null) {
+				releaseRefreshShellSearch = null;
+				completedFallbackSearch = editSearch;
+				applyHostSearchResult(result);
+			}
 		}, 120);
 	};
 	const stylesSub = sliceHandle((s) => s.styles);
@@ -13187,6 +13335,7 @@ function createSuperDocUI(options) {
 		watermark.destroy();
 		clearContentControlHighlight();
 		disposed = true;
+		completedFallbackSearch = null;
 		if (searchRefreshTimer !== null) clearTimeout(searchRefreshTimer);
 		searchRefreshTimer = null;
 		cancelRefreshShellSearch();
@@ -13262,6 +13411,7 @@ function createSuperDocUI(options) {
 		comments,
 		trackChanges,
 		contentControls,
+		bookmarks,
 		fonts,
 		zoom,
 		document: documentHandle,

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.20.0-next.9",
+	superdocVersion: "2.20.1-next.1",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.20.0-next.9",
+	superdocVersion: "2.20.1-next.1",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -3649,7 +3649,7 @@ export declare const OPERATION_DEFINITIONS: {
     readonly find: {
         readonly memberPath: "find";
         readonly description: "Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results: for mutation targeting, use query.match instead.";
-        readonly expectedResult: "Returns an SDFindResult envelope ({ total, limit, offset, items }). Each item is an SDNodeResult ({ node, address }).";
+        readonly expectedResult: "Returns an SDFindResult envelope ({ total, limit, offset, items }). Each item is an SDNodeResult ({ node, address }). Text hits contain only the matched text; use getNode or getNodeById for the full containing node. Node selectors return full node projections.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
         readonly referenceDocPath: "find.mdx";