superdoc 2.13.0-next.1 → 2.13.0-next.11

package/dist/chunks/{create-super-doc-ui-BWWWNPP8.cjs → create-super-doc-ui-DNfQTF2k.cjs}

@@ -115,7 +115,9 @@ var DATA_ATTRS = {
 	/** Encoded story locator (e.g. `body`, `header:rId4`, `footer:rId7`). */
 	LAYOUT_STORY: "data-layout-story",
 	/** Source block reference (today: producer's `blockId`). */
-	LAYOUT_BLOCK_REF: "data-layout-block-ref"
+	LAYOUT_BLOCK_REF: "data-layout-block-ref",
+	/** Zero-based flow-column index that owns the rendered fragment. */
+	LAYOUT_COLUMN_INDEX: "data-layout-column-index"
 };
 /**
 * Decode the dataset string back into a `LayoutStoryLocator`-shaped object.
@@ -3109,6 +3111,18 @@ function commandResultFromOperationResult(result) {
 function isSuccessfulReceipt(result) {
 	return Boolean(result) && typeof result === "object" && result.success === true;
 }
+/**
+* The host also emits `mutation:committed` for previews and no-op receipts;
+* those events must not mark the document as having unsaved edits.
+*/
+function mutationCommittedEventChangedDocument(event) {
+	if (event.dryRun === true) return false;
+	const receipt = event.receipt;
+	if (receipt && typeof receipt === "object" && receipt.changed === false) return false;
+	if (receipt && typeof receipt === "object" && receipt.noop === true) return false;
+	if (receipt && typeof receipt === "object" && receipt.status === "NO_OP") return false;
+	return true;
+}
 function commandResultSucceeded(result) {
 	if (result === false) return false;
 	if (result && typeof result === "object" && result.success === false) return false;
@@ -3915,6 +3929,30 @@ function createSuperDocUI(options) {
 	let allTrackedChangesResolvedToken = null;
 	let selectionEpoch = 0;
 	let lastCoordinatorEditor = null;
+	/**
+	* Fallback dirty state for editors that do not expose `isDirty` (V2). Kept
+	* per host so switching the active editor away and back does not forget an
+	* edit, and seeded from the host's local mutation revision so a controller
+	* created after the first edit still reports it. A document replacement or
+	* a verified zero revision clears an entry: `save:completed` fires for every DOCX export,
+	* including a download, and producing bytes is not persistence.
+	*/
+	const dirtyHosts = /* @__PURE__ */ new WeakSet();
+	const hostSeededMutationRevision = /* @__PURE__ */ new WeakMap();
+	const seedLocalDocumentMutation = (host) => {
+		if (hostSeededMutationRevision.has(host)) return;
+		const revision = typeof host.getLocalMutationRevision === "function" ? safeCall(() => host.getLocalMutationRevision(), null) : null;
+		const seeded = typeof revision === "number" ? revision : 0;
+		hostSeededMutationRevision.set(host, seeded);
+		if (seeded > 0) dirtyHosts.add(host);
+		else if (revision === 0) dirtyHosts.delete(host);
+	};
+	const hasLocalDocumentMutation = () => {
+		const host = getHost();
+		if (!host) return false;
+		seedLocalDocumentMutation(host);
+		return dirtyHosts.has(host);
+	};
 	/** Token shared by document-content reads (editor identity + mutation revision). */
 	const contentToken = () => `${editorIdentityId(getEditor())}|m${documentMutationRevision}`;
 	const clearPostDecisionTrackChanges = () => {
@@ -5182,10 +5220,11 @@ function createSuperDocUI(options) {
 	};
 	const computeDocument = () => {
 		const editor = getEditor();
+		const editorDirty = editor ? editor.isDirty : void 0;
 		return {
 			ready: editor != null,
 			mode: readDocumentMode(),
-			dirty: editor ? Boolean(editor.isDirty) : false
+			dirty: editor ? editorDirty === void 0 ? hasLocalDocumentMutation() : Boolean(editorDirty) : false
 		};
 	};
 	/**
@@ -7112,7 +7151,8 @@ function createSuperDocUI(options) {
 	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
-		const events = (getEditor()?.host)?.events;
+		const host = getEditor()?.host;
+		const events = host?.events;
 		const next = events && typeof events.subscribe === "function" ? events : null;
 		if (next === currentHostEventsSource) return;
 		if (detachHostEvents) {
@@ -7121,9 +7161,24 @@ function createSuperDocUI(options) {
 		}
 		currentHostEventsSource = next;
 		if (!next) return;
+		if (host) {
+			hostSeededMutationRevision.delete(host);
+			seedLocalDocumentMutation(host);
+		}
 		try {
 			const off = next.subscribe((event) => {
 				const type = event?.type;
+				const isStandaloneDocumentMutation = type === "document:mutated" && event.hasCommitEvent !== true;
+				if ((type === "document:mutated" || type === "mutation:committed" && mutationCommittedEventChangedDocument(event)) && host && !dirtyHosts.has(host)) {
+					dirtyHosts.add(host);
+					recompute("document-dirty");
+				}
+				if (type === "collaboration:document-replaced" && host) {
+					dirtyHosts.delete(host);
+					hostSeededMutationRevision.delete(host);
+					seedLocalDocumentMutation(host);
+					recompute("document-dirty");
+				}
 				if (type === "review-mutation:started") {
 					beginUiReviewMutation(event.reviewMutation?.token);
 					return;
@@ -7143,8 +7198,8 @@ function createSuperDocUI(options) {
 					refreshIncompleteTrackChangesDirectories();
 					return;
 				}
-				if (type === "mutation:committed" || type === "collaboration:remote-changed") lastEditableMutationAtMs = Date.now();
-				if (type === "mutation:committed" || type === "save:completed" || type === "collaboration:remote-changed") {
+				if (isStandaloneDocumentMutation || type === "mutation:committed" || type === "collaboration:remote-changed") lastEditableMutationAtMs = Date.now();
+				if (isStandaloneDocumentMutation || type === "mutation:committed" || type === "save:completed" || type === "collaboration:remote-changed") {
 					const impact = type === "mutation:committed" ? getV2TrackedChangeMutationImpact(event) : null;
 					if (impact?.allResolved) {
 						replaceTrackedChangeItemsInCache([]);
@@ -7159,7 +7214,7 @@ function createSuperDocUI(options) {
 						return;
 					}
 					if (impact?.removedIds.size && impact.upsertIds.size === 0) return;
-					if (type === "collaboration:remote-changed" || type === "mutation:committed" && !isTypingBurst) schedulePostPaintContentRefresh();
+					if (isStandaloneDocumentMutation || type === "collaboration:remote-changed" || type === "mutation:committed" && !isTypingBurst) schedulePostPaintContentRefresh();
 					const remoteCommentsPartChanged = type === "collaboration:remote-changed" && Array.isArray(event.changedPartUris) && event.changedPartUris.some((partUri) => typeof partUri === "string" && COMMENTS_CATALOG_PART_URIS.has(partUri));
 					const loadedCommentAnchorsMayHaveChanged = type === "collaboration:remote-changed" && Array.isArray(event.changedStoryIds) && event.changedStoryIds.length > 0 && commentsCatalogMayHaveRows();
 					if (remoteCommentsPartChanged && !isTypingBurst) heavyReadsHeldUntilIdle = true;
@@ -7273,6 +7328,11 @@ function createSuperDocUI(options) {
 				const matchesEditor = Boolean(replacedEditor) && replacedEditor === getEditor();
 				const matchesHost = Boolean(replacedHost) && replacedHost === getHost();
 				if (!matchesEditor && !matchesHost) return;
+				const replacedDirtyHost = matchesHost ? replacedHost : getHost();
+				if (replacedDirtyHost) {
+					dirtyHosts.delete(replacedDirtyHost);
+					hostSeededMutationRevision.delete(replacedDirtyHost);
+				}
 				runDocumentResetHooks();
 				asyncReads.clear();
 				invalidateDocumentContent();

package/dist/chunks/{create-super-doc-ui-FnwgTkUv.es.js → create-super-doc-ui-XWtQHPGP.es.js}

@@ -115,7 +115,9 @@ var DATA_ATTRS = {
 	/** Encoded story locator (e.g. `body`, `header:rId4`, `footer:rId7`). */
 	LAYOUT_STORY: "data-layout-story",
 	/** Source block reference (today: producer's `blockId`). */
-	LAYOUT_BLOCK_REF: "data-layout-block-ref"
+	LAYOUT_BLOCK_REF: "data-layout-block-ref",
+	/** Zero-based flow-column index that owns the rendered fragment. */
+	LAYOUT_COLUMN_INDEX: "data-layout-column-index"
 };
 /**
 * Decode the dataset string back into a `LayoutStoryLocator`-shaped object.
@@ -3109,6 +3111,18 @@ function commandResultFromOperationResult(result) {
 function isSuccessfulReceipt(result) {
 	return Boolean(result) && typeof result === "object" && result.success === true;
 }
+/**
+* The host also emits `mutation:committed` for previews and no-op receipts;
+* those events must not mark the document as having unsaved edits.
+*/
+function mutationCommittedEventChangedDocument(event) {
+	if (event.dryRun === true) return false;
+	const receipt = event.receipt;
+	if (receipt && typeof receipt === "object" && receipt.changed === false) return false;
+	if (receipt && typeof receipt === "object" && receipt.noop === true) return false;
+	if (receipt && typeof receipt === "object" && receipt.status === "NO_OP") return false;
+	return true;
+}
 function commandResultSucceeded(result) {
 	if (result === false) return false;
 	if (result && typeof result === "object" && result.success === false) return false;
@@ -3915,6 +3929,30 @@ function createSuperDocUI(options) {
 	let allTrackedChangesResolvedToken = null;
 	let selectionEpoch = 0;
 	let lastCoordinatorEditor = null;
+	/**
+	* Fallback dirty state for editors that do not expose `isDirty` (V2). Kept
+	* per host so switching the active editor away and back does not forget an
+	* edit, and seeded from the host's local mutation revision so a controller
+	* created after the first edit still reports it. A document replacement or
+	* a verified zero revision clears an entry: `save:completed` fires for every DOCX export,
+	* including a download, and producing bytes is not persistence.
+	*/
+	const dirtyHosts = /* @__PURE__ */ new WeakSet();
+	const hostSeededMutationRevision = /* @__PURE__ */ new WeakMap();
+	const seedLocalDocumentMutation = (host) => {
+		if (hostSeededMutationRevision.has(host)) return;
+		const revision = typeof host.getLocalMutationRevision === "function" ? safeCall(() => host.getLocalMutationRevision(), null) : null;
+		const seeded = typeof revision === "number" ? revision : 0;
+		hostSeededMutationRevision.set(host, seeded);
+		if (seeded > 0) dirtyHosts.add(host);
+		else if (revision === 0) dirtyHosts.delete(host);
+	};
+	const hasLocalDocumentMutation = () => {
+		const host = getHost();
+		if (!host) return false;
+		seedLocalDocumentMutation(host);
+		return dirtyHosts.has(host);
+	};
 	/** Token shared by document-content reads (editor identity + mutation revision). */
 	const contentToken = () => `${editorIdentityId(getEditor())}|m${documentMutationRevision}`;
 	const clearPostDecisionTrackChanges = () => {
@@ -5182,10 +5220,11 @@ function createSuperDocUI(options) {
 	};
 	const computeDocument = () => {
 		const editor = getEditor();
+		const editorDirty = editor ? editor.isDirty : void 0;
 		return {
 			ready: editor != null,
 			mode: readDocumentMode(),
-			dirty: editor ? Boolean(editor.isDirty) : false
+			dirty: editor ? editorDirty === void 0 ? hasLocalDocumentMutation() : Boolean(editorDirty) : false
 		};
 	};
 	/**
@@ -7112,7 +7151,8 @@ function createSuperDocUI(options) {
 	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
-		const events = (getEditor()?.host)?.events;
+		const host = getEditor()?.host;
+		const events = host?.events;
 		const next = events && typeof events.subscribe === "function" ? events : null;
 		if (next === currentHostEventsSource) return;
 		if (detachHostEvents) {
@@ -7121,9 +7161,24 @@ function createSuperDocUI(options) {
 		}
 		currentHostEventsSource = next;
 		if (!next) return;
+		if (host) {
+			hostSeededMutationRevision.delete(host);
+			seedLocalDocumentMutation(host);
+		}
 		try {
 			const off = next.subscribe((event) => {
 				const type = event?.type;
+				const isStandaloneDocumentMutation = type === "document:mutated" && event.hasCommitEvent !== true;
+				if ((type === "document:mutated" || type === "mutation:committed" && mutationCommittedEventChangedDocument(event)) && host && !dirtyHosts.has(host)) {
+					dirtyHosts.add(host);
+					recompute("document-dirty");
+				}
+				if (type === "collaboration:document-replaced" && host) {
+					dirtyHosts.delete(host);
+					hostSeededMutationRevision.delete(host);
+					seedLocalDocumentMutation(host);
+					recompute("document-dirty");
+				}
 				if (type === "review-mutation:started") {
 					beginUiReviewMutation(event.reviewMutation?.token);
 					return;
@@ -7143,8 +7198,8 @@ function createSuperDocUI(options) {
 					refreshIncompleteTrackChangesDirectories();
 					return;
 				}
-				if (type === "mutation:committed" || type === "collaboration:remote-changed") lastEditableMutationAtMs = Date.now();
-				if (type === "mutation:committed" || type === "save:completed" || type === "collaboration:remote-changed") {
+				if (isStandaloneDocumentMutation || type === "mutation:committed" || type === "collaboration:remote-changed") lastEditableMutationAtMs = Date.now();
+				if (isStandaloneDocumentMutation || type === "mutation:committed" || type === "save:completed" || type === "collaboration:remote-changed") {
 					const impact = type === "mutation:committed" ? getV2TrackedChangeMutationImpact(event) : null;
 					if (impact?.allResolved) {
 						replaceTrackedChangeItemsInCache([]);
@@ -7159,7 +7214,7 @@ function createSuperDocUI(options) {
 						return;
 					}
 					if (impact?.removedIds.size && impact.upsertIds.size === 0) return;
-					if (type === "collaboration:remote-changed" || type === "mutation:committed" && !isTypingBurst) schedulePostPaintContentRefresh();
+					if (isStandaloneDocumentMutation || type === "collaboration:remote-changed" || type === "mutation:committed" && !isTypingBurst) schedulePostPaintContentRefresh();
 					const remoteCommentsPartChanged = type === "collaboration:remote-changed" && Array.isArray(event.changedPartUris) && event.changedPartUris.some((partUri) => typeof partUri === "string" && COMMENTS_CATALOG_PART_URIS.has(partUri));
 					const loadedCommentAnchorsMayHaveChanged = type === "collaboration:remote-changed" && Array.isArray(event.changedStoryIds) && event.changedStoryIds.length > 0 && commentsCatalogMayHaveRows();
 					if (remoteCommentsPartChanged && !isTypingBurst) heavyReadsHeldUntilIdle = true;
@@ -7273,6 +7328,11 @@ function createSuperDocUI(options) {
 				const matchesEditor = Boolean(replacedEditor) && replacedEditor === getEditor();
 				const matchesHost = Boolean(replacedHost) && replacedHost === getHost();
 				if (!matchesEditor && !matchesHost) return;
+				const replacedDirtyHost = matchesHost ? replacedHost : getHost();
+				if (replacedDirtyHost) {
+					dirtyHosts.delete(replacedDirtyHost);
+					hostSeededMutationRevision.delete(replacedDirtyHost);
+				}
 				runDocumentResetHooks();
 				asyncReads.clear();
 				invalidateDocumentContent();

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.13.0-next.1",
+	superdocVersion: "2.13.0-next.11",
 	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.13.0-next.1",
+	superdocVersion: "2.13.0-next.11",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/blocks/blocks.d.ts

@@ -1,7 +1,8 @@
 import { MutationOptions } from '../write/write.js';
-import { BlocksDeleteInput, BlocksDeleteResult, BlocksListInput, BlocksListResult, BlocksDeleteRangeInput, BlocksDeleteRangeResult, BlocksMergeInput, BlocksMergeResult, BlocksMoveInput, BlocksMoveResult, BlocksSplitInput, BlocksSplitResult } from '../types/blocks.types.js';
+import { BlocksDeleteInput, BlocksDeleteResult, BlocksListInput, BlocksListResult, BlocksFindTextInput, BlocksFindTextResult, BlocksDeleteRangeInput, BlocksDeleteRangeResult, BlocksMergeInput, BlocksMergeResult, BlocksMoveInput, BlocksMoveResult, BlocksSplitInput, BlocksSplitResult } from '../types/blocks.types.js';
 export interface BlocksApi {
     list(input?: BlocksListInput): BlocksListResult;
+    findText(input: BlocksFindTextInput): BlocksFindTextResult;
     delete(input: BlocksDeleteInput, options?: MutationOptions): BlocksDeleteResult;
     deleteRange(input: BlocksDeleteRangeInput, options?: MutationOptions): BlocksDeleteRangeResult;
     /** Split a paragraph at a visible-text offset. */
@@ -12,6 +13,7 @@ export interface BlocksApi {
     move(input: BlocksMoveInput, options?: MutationOptions): BlocksMoveResult;
 }
 export interface BlocksAdapter {
+    readonly supportsIdentityFilter?: boolean;
     list(input?: BlocksListInput): BlocksListResult;
     delete(input: BlocksDeleteInput, options?: MutationOptions): BlocksDeleteResult;
     deleteRange(input: BlocksDeleteRangeInput, options?: MutationOptions): BlocksDeleteRangeResult;

package/dist/document-api/src/blocks/find-text.d.ts

@@ -0,0 +1,3 @@
+import { BlocksAdapter } from './blocks.js';
+import { BlocksFindTextInput, BlocksFindTextResult } from '../types/blocks.types.js';
+export declare function executeBlocksFindText(adapter: BlocksAdapter, input: BlocksFindTextInput): BlocksFindTextResult;

package/dist/document-api/src/content-controls/content-controls.types.d.ts

@@ -284,7 +284,7 @@ export interface ContentControlsGetContentResult {
 export interface ContentControlsReplaceContentInput {
     target: ContentControlTarget;
     content: string;
-    format?: 'text' | 'html';
+    format?: 'text' | 'html' | 'ooxml';
 }
 export interface ContentControlsClearContentInput {
     target: ContentControlTarget;

package/dist/document-api/src/contract/command-catalog.d.ts

@@ -1,7 +1,7 @@
 import { CommandCatalog, CommandStaticMetadata, OperationId } from './types.js';
 export declare const COMMAND_CATALOG: CommandCatalog;
 /** Operation IDs whose catalog entry has `mutates: true`. */
-export declare const MUTATING_OPERATION_IDS: ("replace" | "find" | "insert" | "delete" | "info" | "projectHtml" | "projectMarkdown" | "capabilities.check" | "format.apply" | "blocks.split" | "blocks.merge" | "blocks.move" | "lists.getState" | "lists.apply" | "lists.continue" | "lists.restart" | "lists.remove" | "format.paragraph.setMarkRunProps" | "tables.moveRow" | "format.bold" | "format.strike" | "format.color" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.italic" | "format.underline" | "format.caps" | "format.smallCaps" | "format.outline" | "format.shadow" | "format.emboss" | "format.imprint" | "format.vanish" | "format.webHidden" | "format.specVanish" | "format.border" | "format.fitText" | "format.dstrike" | "format.vertAlign" | "format.position" | "format.bCs" | "format.iCs" | "format.snapToGrid" | "format.oMath" | "format.letterSpacing" | "format.charScale" | "format.kerning" | "format.rStyle" | "format.rFonts" | "format.eastAsianLayout" | "format.em" | "format.ligatures" | "format.numForm" | "format.numSpacing" | "format.stylisticSets" | "format.contextualAlternates" | "get" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "htmlToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.list" | "blocks.delete" | "blocks.deleteRange" | "styles.apply" | "styles.getCatalog" | "templates.apply" | "create.paragraph" | "create.heading" | "create.sectionBreak" | "sections.list" | "sections.get" | "sections.setBreakType" | "sections.setPageMargins" | "sections.setHeaderFooterMargins" | "sections.setPageSetup" | "sections.setColumns" | "sections.setLineNumbering" | "sections.setPageNumbering" | "sections.setTitlePage" | "sections.setOddEvenHeadersFooters" | "sections.setVerticalAlign" | "sections.setSectionDirection" | "sections.setHeaderFooterRef" | "sections.clearHeaderFooterRef" | "sections.setLinkToPrevious" | "sections.setPageBorders" | "sections.clearPageBorders" | "styles.paragraph.setStyle" | "styles.paragraph.setStyleRef" | "styles.paragraph.clearStyle" | "format.paragraph.resetDirectFormatting" | "format.paragraph.setAlignment" | "format.paragraph.clearAlignment" | "format.paragraph.setIndentation" | "format.paragraph.clearIndentation" | "format.paragraph.setSpacing" | "format.paragraph.clearSpacing" | "format.paragraph.setKeepOptions" | "format.paragraph.setOutlineLevel" | "format.paragraph.setFlowOptions" | "format.paragraph.setTabStop" | "format.paragraph.clearTabStop" | "format.paragraph.clearAllTabStops" | "format.paragraph.setBorder" | "format.paragraph.clearBorder" | "format.paragraph.setShading" | "format.paragraph.clearShading" | "format.paragraph.setDirection" | "format.paragraph.clearDirection" | "format.paragraph.setNumbering" | "lists.list" | "lists.get" | "lists.insert" | "lists.create" | "lists.attach" | "lists.detach" | "lists.delete" | "lists.indent" | "lists.outdent" | "lists.join" | "lists.canJoin" | "lists.separate" | "lists.merge" | "lists.split" | "lists.setLevel" | "lists.setValue" | "lists.continuePrevious" | "lists.canContinuePrevious" | "lists.setLevelRestart" | "lists.convertToText" | "lists.applyTemplate" | "lists.applyPreset" | "lists.setType" | "lists.captureTemplate" | "lists.setLevelNumbering" | "lists.setLevelBullet" | "lists.setLevelPictureBullet" | "lists.setLevelAlignment" | "lists.setLevelIndents" | "lists.setLevelTrailingCharacter" | "lists.setLevelMarkerFont" | "lists.clearLevelOverrides" | "lists.getStyle" | "lists.applyStyle" | "lists.restartAt" | "lists.setLevelNumberStyle" | "lists.setLevelText" | "lists.setLevelStart" | "lists.setLevelLayout" | "comments.create" | "comments.patch" | "comments.delete" | "comments.get" | "comments.list" | "trackChanges.list" | "trackChanges.get" | "trackChanges.decide" | "query.match" | "ranges.resolve" | "selection.current" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "create.table" | "tables.convertFromText" | "tables.delete" | "tables.clearContents" | "tables.move" | "tables.split" | "tables.convertToText" | "tables.setLayout" | "tables.insertRow" | "tables.deleteRow" | "tables.setRowHeight" | "tables.distributeRows" | "tables.setRowOptions" | "tables.insertColumn" | "tables.deleteColumn" | "tables.setColumnWidth" | "tables.distributeColumns" | "tables.insertCell" | "tables.deleteCell" | "tables.mergeCells" | "tables.unmergeCells" | "tables.splitCell" | "tables.setCellProperties" | "tables.setCellText" | "tables.sort" | "tables.setAltText" | "tables.setStyle" | "tables.clearStyle" | "tables.setStyleOption" | "tables.setBorder" | "tables.clearBorder" | "tables.applyBorderPreset" | "tables.setShading" | "tables.clearShading" | "tables.setTablePadding" | "tables.setCellPadding" | "tables.setCellSpacing" | "tables.clearCellSpacing" | "tables.applyStyle" | "tables.setBorders" | "tables.setTableOptions" | "tables.applyPreset" | "tables.get" | "tables.getCells" | "tables.getProperties" | "tables.getStyles" | "tables.setDefaultStyle" | "tables.clearDefaultStyle" | "create.tableOfContents" | "toc.list" | "toc.get" | "toc.configure" | "toc.update" | "toc.remove" | "toc.markEntry" | "toc.unmarkEntry" | "toc.listEntries" | "toc.getEntry" | "toc.editEntry" | "history.get" | "history.undo" | "history.redo" | "create.image" | "images.list" | "images.get" | "images.delete" | "images.move" | "images.convertToInline" | "images.convertToFloating" | "images.setSize" | "images.setWrapType" | "images.setWrapSide" | "images.setWrapDistances" | "images.setPosition" | "images.setAnchorOptions" | "images.setZOrder" | "images.scale" | "images.setLockAspectRatio" | "images.rotate" | "images.flip" | "images.crop" | "images.resetCrop" | "images.replaceSource" | "images.setAltText" | "images.setDecorative" | "images.setName" | "images.setHyperlink" | "images.insertCaption" | "images.updateCaption" | "images.removeCaption" | "hyperlinks.list" | "hyperlinks.get" | "hyperlinks.wrap" | "hyperlinks.insert" | "hyperlinks.patch" | "hyperlinks.remove" | "headerFooters.list" | "headerFooters.get" | "headerFooters.resolve" | "headerFooters.refs.set" | "headerFooters.refs.clear" | "headerFooters.refs.setLinkedToPrevious" | "headerFooters.parts.list" | "headerFooters.parts.create" | "headerFooters.parts.delete" | "create.contentControl" | "contentControls.list" | "contentControls.get" | "contentControls.listInRange" | "contentControls.selectByTag" | "contentControls.selectByTitle" | "contentControls.listChildren" | "contentControls.getParent" | "contentControls.wrap" | "contentControls.unwrap" | "contentControls.delete" | "contentControls.copy" | "contentControls.move" | "contentControls.patch" | "contentControls.setLockMode" | "contentControls.setType" | "contentControls.getContent" | "contentControls.replaceContent" | "contentControls.clearContent" | "contentControls.appendContent" | "contentControls.prependContent" | "contentControls.insertBefore" | "contentControls.insertAfter" | "contentControls.getBinding" | "contentControls.setBinding" | "contentControls.clearBinding" | "contentControls.getRawProperties" | "contentControls.patchRawProperties" | "contentControls.validateWordCompatibility" | "contentControls.normalizeWordCompatibility" | "contentControls.normalizeTagPayload" | "contentControls.text.setMultiline" | "contentControls.text.setValue" | "contentControls.text.clearValue" | "contentControls.date.setValue" | "contentControls.date.clearValue" | "contentControls.date.setDisplayFormat" | "contentControls.date.setDisplayLocale" | "contentControls.date.setStorageFormat" | "contentControls.date.setCalendar" | "contentControls.checkbox.getState" | "contentControls.checkbox.setState" | "contentControls.checkbox.toggle" | "contentControls.checkbox.setSymbolPair" | "contentControls.choiceList.getItems" | "contentControls.choiceList.setItems" | "contentControls.choiceList.setSelected" | "contentControls.repeatingSection.listItems" | "contentControls.repeatingSection.insertItemBefore" | "contentControls.repeatingSection.insertItemAfter" | "contentControls.repeatingSection.cloneItem" | "contentControls.repeatingSection.deleteItem" | "contentControls.repeatingSection.setAllowInsertDelete" | "contentControls.group.wrap" | "contentControls.group.ungroup" | "bookmarks.list" | "bookmarks.get" | "bookmarks.insert" | "bookmarks.rename" | "bookmarks.remove" | "footnotes.list" | "footnotes.get" | "footnotes.insert" | "footnotes.update" | "footnotes.remove" | "footnotes.configure" | "clipboard.parse" | "clipboard.insert" | "clipboard.serializeSelection" | "crossRefs.list" | "crossRefs.get" | "crossRefs.insert" | "crossRefs.rebuild" | "crossRefs.remove" | "index.list" | "index.get" | "index.insert" | "index.configure" | "index.rebuild" | "index.remove" | "index.entries.list" | "index.entries.get" | "index.entries.insert" | "index.entries.update" | "index.entries.remove" | "captions.list" | "captions.get" | "captions.insert" | "captions.update" | "captions.remove" | "captions.configure" | "fields.list" | "fields.get" | "fields.insert" | "fields.rebuild" | "fields.remove" | "citations.list" | "citations.get" | "citations.insert" | "citations.update" | "citations.remove" | "citations.sources.list" | "citations.sources.get" | "citations.sources.insert" | "citations.sources.update" | "citations.sources.remove" | "citations.bibliography.get" | "citations.bibliography.insert" | "citations.bibliography.rebuild" | "citations.bibliography.configure" | "citations.bibliography.remove" | "authorities.list" | "authorities.get" | "authorities.insert" | "authorities.configure" | "authorities.rebuild" | "authorities.remove" | "authorities.entries.list" | "authorities.entries.get" | "authorities.entries.insert" | "authorities.entries.update" | "authorities.entries.remove" | "diff.capture" | "diff.compare" | "diff.apply" | "export.toDocx" | "protection.get" | "protection.setEditingRestriction" | "protection.clearEditingRestriction" | "permissionRanges.list" | "permissionRanges.get" | "permissionRanges.create" | "permissionRanges.remove" | "permissionRanges.updatePrincipal" | "customXml.parts.list" | "customXml.parts.get" | "customXml.parts.create" | "customXml.parts.patch" | "customXml.parts.remove" | "metadata.attach" | "metadata.list" | "metadata.get" | "metadata.update" | "metadata.remove" | "metadata.resolve")[];
+export declare const MUTATING_OPERATION_IDS: ("replace" | "find" | "insert" | "delete" | "info" | "projectHtml" | "projectMarkdown" | "capabilities.check" | "format.apply" | "blocks.split" | "blocks.merge" | "blocks.move" | "lists.getState" | "lists.apply" | "lists.continue" | "lists.restart" | "lists.remove" | "format.paragraph.setMarkRunProps" | "tables.moveRow" | "format.bold" | "format.strike" | "format.color" | "format.rtl" | "format.cs" | "format.shading" | "format.fontFamily" | "format.lang" | "format.fontSize" | "format.fontSizeCs" | "format.highlight" | "format.italic" | "format.underline" | "format.caps" | "format.smallCaps" | "format.outline" | "format.shadow" | "format.emboss" | "format.imprint" | "format.vanish" | "format.webHidden" | "format.specVanish" | "format.border" | "format.fitText" | "format.dstrike" | "format.vertAlign" | "format.position" | "format.bCs" | "format.iCs" | "format.snapToGrid" | "format.oMath" | "format.letterSpacing" | "format.charScale" | "format.kerning" | "format.rStyle" | "format.rFonts" | "format.eastAsianLayout" | "format.em" | "format.ligatures" | "format.numForm" | "format.numSpacing" | "format.stylisticSets" | "format.contextualAlternates" | "get" | "getNode" | "getNodeById" | "getText" | "getMarkdown" | "getHtml" | "markdownToFragment" | "htmlToFragment" | "extract" | "clearContent" | "formatRange" | "blocks.findText" | "blocks.list" | "blocks.delete" | "blocks.deleteRange" | "styles.apply" | "styles.getCatalog" | "templates.apply" | "create.paragraph" | "create.heading" | "create.sectionBreak" | "sections.list" | "sections.get" | "sections.setBreakType" | "sections.setPageMargins" | "sections.setHeaderFooterMargins" | "sections.setPageSetup" | "sections.setColumns" | "sections.setLineNumbering" | "sections.setPageNumbering" | "sections.setTitlePage" | "sections.setOddEvenHeadersFooters" | "sections.setVerticalAlign" | "sections.setSectionDirection" | "sections.setHeaderFooterRef" | "sections.clearHeaderFooterRef" | "sections.setLinkToPrevious" | "sections.setPageBorders" | "sections.clearPageBorders" | "styles.paragraph.setStyle" | "styles.paragraph.setStyleRef" | "styles.paragraph.clearStyle" | "format.paragraph.resetDirectFormatting" | "format.paragraph.setAlignment" | "format.paragraph.clearAlignment" | "format.paragraph.setIndentation" | "format.paragraph.clearIndentation" | "format.paragraph.setSpacing" | "format.paragraph.clearSpacing" | "format.paragraph.setKeepOptions" | "format.paragraph.setOutlineLevel" | "format.paragraph.setFlowOptions" | "format.paragraph.setTabStop" | "format.paragraph.clearTabStop" | "format.paragraph.clearAllTabStops" | "format.paragraph.setBorder" | "format.paragraph.clearBorder" | "format.paragraph.setShading" | "format.paragraph.clearShading" | "format.paragraph.setDirection" | "format.paragraph.clearDirection" | "format.paragraph.setNumbering" | "lists.list" | "lists.get" | "lists.insert" | "lists.create" | "lists.attach" | "lists.detach" | "lists.delete" | "lists.indent" | "lists.outdent" | "lists.join" | "lists.canJoin" | "lists.separate" | "lists.merge" | "lists.split" | "lists.setLevel" | "lists.setValue" | "lists.continuePrevious" | "lists.canContinuePrevious" | "lists.setLevelRestart" | "lists.convertToText" | "lists.applyTemplate" | "lists.applyPreset" | "lists.setType" | "lists.captureTemplate" | "lists.setLevelNumbering" | "lists.setLevelBullet" | "lists.setLevelPictureBullet" | "lists.setLevelAlignment" | "lists.setLevelIndents" | "lists.setLevelTrailingCharacter" | "lists.setLevelMarkerFont" | "lists.clearLevelOverrides" | "lists.getStyle" | "lists.applyStyle" | "lists.restartAt" | "lists.setLevelNumberStyle" | "lists.setLevelText" | "lists.setLevelStart" | "lists.setLevelLayout" | "comments.create" | "comments.patch" | "comments.delete" | "comments.get" | "comments.list" | "trackChanges.list" | "trackChanges.get" | "trackChanges.decide" | "query.match" | "ranges.resolve" | "selection.current" | "mutations.preview" | "mutations.apply" | "plan.execute" | "capabilities.get" | "create.table" | "tables.convertFromText" | "tables.delete" | "tables.clearContents" | "tables.move" | "tables.split" | "tables.convertToText" | "tables.setLayout" | "tables.insertRow" | "tables.deleteRow" | "tables.setRowHeight" | "tables.distributeRows" | "tables.setRowOptions" | "tables.insertColumn" | "tables.deleteColumn" | "tables.setColumnWidth" | "tables.distributeColumns" | "tables.insertCell" | "tables.deleteCell" | "tables.mergeCells" | "tables.unmergeCells" | "tables.splitCell" | "tables.setCellProperties" | "tables.setCellText" | "tables.sort" | "tables.setAltText" | "tables.setStyle" | "tables.clearStyle" | "tables.setStyleOption" | "tables.setBorder" | "tables.clearBorder" | "tables.applyBorderPreset" | "tables.setShading" | "tables.clearShading" | "tables.setTablePadding" | "tables.setCellPadding" | "tables.setCellSpacing" | "tables.clearCellSpacing" | "tables.applyStyle" | "tables.setBorders" | "tables.setTableOptions" | "tables.applyPreset" | "tables.get" | "tables.getCells" | "tables.getProperties" | "tables.getStyles" | "tables.setDefaultStyle" | "tables.clearDefaultStyle" | "create.tableOfContents" | "toc.list" | "toc.get" | "toc.configure" | "toc.update" | "toc.remove" | "toc.markEntry" | "toc.unmarkEntry" | "toc.listEntries" | "toc.getEntry" | "toc.editEntry" | "history.get" | "history.undo" | "history.redo" | "create.image" | "images.list" | "images.get" | "images.delete" | "images.move" | "images.convertToInline" | "images.convertToFloating" | "images.setSize" | "images.setWrapType" | "images.setWrapSide" | "images.setWrapDistances" | "images.setPosition" | "images.setAnchorOptions" | "images.setZOrder" | "images.scale" | "images.setLockAspectRatio" | "images.rotate" | "images.flip" | "images.crop" | "images.resetCrop" | "images.replaceSource" | "images.setAltText" | "images.setDecorative" | "images.setName" | "images.setHyperlink" | "images.insertCaption" | "images.updateCaption" | "images.removeCaption" | "hyperlinks.list" | "hyperlinks.get" | "hyperlinks.wrap" | "hyperlinks.insert" | "hyperlinks.patch" | "hyperlinks.remove" | "headerFooters.list" | "headerFooters.get" | "headerFooters.resolve" | "headerFooters.refs.set" | "headerFooters.refs.clear" | "headerFooters.refs.setLinkedToPrevious" | "headerFooters.parts.list" | "headerFooters.parts.create" | "headerFooters.parts.delete" | "create.contentControl" | "contentControls.list" | "contentControls.get" | "contentControls.listInRange" | "contentControls.selectByTag" | "contentControls.selectByTitle" | "contentControls.listChildren" | "contentControls.getParent" | "contentControls.wrap" | "contentControls.unwrap" | "contentControls.delete" | "contentControls.copy" | "contentControls.move" | "contentControls.patch" | "contentControls.setLockMode" | "contentControls.setType" | "contentControls.getContent" | "contentControls.replaceContent" | "contentControls.clearContent" | "contentControls.appendContent" | "contentControls.prependContent" | "contentControls.insertBefore" | "contentControls.insertAfter" | "contentControls.getBinding" | "contentControls.setBinding" | "contentControls.clearBinding" | "contentControls.getRawProperties" | "contentControls.patchRawProperties" | "contentControls.validateWordCompatibility" | "contentControls.normalizeWordCompatibility" | "contentControls.normalizeTagPayload" | "contentControls.text.setMultiline" | "contentControls.text.setValue" | "contentControls.text.clearValue" | "contentControls.date.setValue" | "contentControls.date.clearValue" | "contentControls.date.setDisplayFormat" | "contentControls.date.setDisplayLocale" | "contentControls.date.setStorageFormat" | "contentControls.date.setCalendar" | "contentControls.checkbox.getState" | "contentControls.checkbox.setState" | "contentControls.checkbox.toggle" | "contentControls.checkbox.setSymbolPair" | "contentControls.choiceList.getItems" | "contentControls.choiceList.setItems" | "contentControls.choiceList.setSelected" | "contentControls.repeatingSection.listItems" | "contentControls.repeatingSection.insertItemBefore" | "contentControls.repeatingSection.insertItemAfter" | "contentControls.repeatingSection.cloneItem" | "contentControls.repeatingSection.deleteItem" | "contentControls.repeatingSection.setAllowInsertDelete" | "contentControls.group.wrap" | "contentControls.group.ungroup" | "bookmarks.list" | "bookmarks.get" | "bookmarks.insert" | "bookmarks.rename" | "bookmarks.remove" | "footnotes.list" | "footnotes.get" | "footnotes.insert" | "footnotes.update" | "footnotes.remove" | "footnotes.configure" | "clipboard.parse" | "clipboard.insert" | "clipboard.serializeSelection" | "crossRefs.list" | "crossRefs.get" | "crossRefs.insert" | "crossRefs.rebuild" | "crossRefs.remove" | "index.list" | "index.get" | "index.insert" | "index.configure" | "index.rebuild" | "index.remove" | "index.entries.list" | "index.entries.get" | "index.entries.insert" | "index.entries.update" | "index.entries.remove" | "captions.list" | "captions.get" | "captions.insert" | "captions.update" | "captions.remove" | "captions.configure" | "fields.list" | "fields.get" | "fields.insert" | "fields.rebuild" | "fields.remove" | "citations.list" | "citations.get" | "citations.insert" | "citations.update" | "citations.remove" | "citations.sources.list" | "citations.sources.get" | "citations.sources.insert" | "citations.sources.update" | "citations.sources.remove" | "citations.bibliography.get" | "citations.bibliography.insert" | "citations.bibliography.rebuild" | "citations.bibliography.configure" | "citations.bibliography.remove" | "authorities.list" | "authorities.get" | "authorities.insert" | "authorities.configure" | "authorities.rebuild" | "authorities.remove" | "authorities.entries.list" | "authorities.entries.get" | "authorities.entries.insert" | "authorities.entries.update" | "authorities.entries.remove" | "diff.capture" | "diff.compare" | "diff.apply" | "export.toDocx" | "protection.get" | "protection.setEditingRestriction" | "protection.clearEditingRestriction" | "permissionRanges.list" | "permissionRanges.get" | "permissionRanges.create" | "permissionRanges.remove" | "permissionRanges.updatePrincipal" | "customXml.parts.list" | "customXml.parts.get" | "customXml.parts.create" | "customXml.parts.patch" | "customXml.parts.remove" | "metadata.attach" | "metadata.list" | "metadata.get" | "metadata.update" | "metadata.remove" | "metadata.resolve")[];
 /** Maps each operation to its human-readable description. */
 export declare const OPERATION_DESCRIPTION_MAP: Record<OperationId, string>;
 /** Maps each operation to whether it requires an open document to execute. */

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

@@ -3606,9 +3606,19 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceGroup: "format";
         readonly skipAsATool: true;
     };
+    readonly 'blocks.findText': {
+        readonly memberPath: "blocks.findText";
+        readonly description: "Find top-level body blocks containing a literal case-insensitive substring. Matches flattened block text, coalescing repeated hits and nested table paragraphs into one block. Scans at most 20,000 blocks inside the document host and returns compact previews without transferring full-text pages.";
+        readonly expectedResult: "Returns matching-block total within the scan, limited matches with zero-based ordinals and 100-character previews, firstMatchOrdinal even for limit:0, scannedBlocks, truncated, and revision. A failed read retains completed pages and reports scanError; revision is unknown if no page succeeded. Whitespace and Unicode are not normalized.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "blocks/find-text.mdx";
+        readonly referenceGroup: "blocks";
+        readonly skipAsATool: true;
+    };
     readonly 'blocks.list': {
         readonly memberPath: "blocks.list";
-        readonly description: "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, single-story scoping via `in: <StoryLocator>`, and final/original/redline projection of numbering metadata without changing block membership.";
+        readonly description: "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit after optional nodeTypes, nodeIds, and literal textSearch filtering, single-story scoping via `in: <StoryLocator>`, and final/original/redline projection of numbering metadata without changing block membership.";
         readonly expectedResult: "Returns a BlocksListResult with total block count, an ordered array of block entries, the effective numbering reviewMode, and the current document revision.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;

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

@@ -6,7 +6,7 @@ import { SDHtmlToFragmentResult, SDMutationReceipt, SDMarkdownToFragmentResult }
 import { DocumentInfo } from '../types/info.types.js';
 import { SDDocument } from '../types/fragment.js';
 import { CreateParagraphInput, CreateParagraphResult, CreateHeadingInput, CreateHeadingResult } from '../types/create.types.js';
-import { BlocksDeleteInput, BlocksDeleteResult, BlocksListInput, BlocksListResult, BlocksDeleteRangeInput, BlocksDeleteRangeResult, BlocksMergeInput, BlocksMergeResult, BlocksMoveInput, BlocksMoveResult, BlocksSplitInput, BlocksSplitResult } from '../types/blocks.types.js';
+import { BlocksDeleteInput, BlocksDeleteResult, BlocksListInput, BlocksListResult, BlocksFindTextInput, BlocksFindTextResult, BlocksDeleteRangeInput, BlocksDeleteRangeResult, BlocksMergeInput, BlocksMergeResult, BlocksMoveInput, BlocksMoveResult, BlocksSplitInput, BlocksSplitResult } from '../types/blocks.types.js';
 import { GetNodeByIdInput } from '../get-node/get-node.js';
 import { GetTextInput } from '../get-text/get-text.js';
 import { GetMarkdownInput } from '../get-markdown/get-markdown.js';
@@ -165,6 +165,11 @@ export interface OperationRegistry extends FormatInlineAliasOperationRegistry {
         options: never;
         output: BlocksListResult;
     };
+    'blocks.findText': {
+        input: BlocksFindTextInput;
+        options: never;
+        output: BlocksFindTextResult;
+    };
     'blocks.delete': {
         input: BlocksDeleteInput;
         options: MutationOptions;
@@ -2012,7 +2017,7 @@ export type InvokeRequest<T extends OperationId> = OperationRegistry[T]['options
 /**
  * Typed invoke result, narrowed by operationId.
  */
-export type InvokeResult<T extends OperationId> = OperationRegistry[T]['output'];
+export type InvokeResult<T extends OperationId> = T extends 'mutations.preview' | 'mutations.apply' ? Promise<OperationRegistry[T]['output']> : T extends 'plan.execute' ? OperationRegistry[T]['output'] | Promise<OperationRegistry[T]['output']> : OperationRegistry[T]['output'];
 /**
  * Loose invoke request for dynamic callers who don't know the operation at compile time.
  * Invalid inputs will produce adapter-level errors, not input-validation errors.

package/dist/document-api/src/index.d.ts

@@ -36,7 +36,7 @@ import { CapabilitiesAdapter, DocumentApiCapabilities } from './capabilities/cap
 import { SDHtmlMarkdownSupportCheckInput, SDHtmlMarkdownSupportCheckResult } from './capabilities/html-markdown-support.js';
 import { OperationId } from './contract/types.js';
 import { DynamicInvokeRequest, InvokeRequest, InvokeResult } from './contract/operation-registry.js';
-import { PlanApi } from './plan/plan.js';
+import { PlanApi, PlanExecuteResult } from './plan/plan.js';
 import { HistoryAdapter, HistoryApi } from './history/history.js';
 import { DiffAdapter, DiffApi } from './diff/diff.js';
 import { ExportAdapter, ExportApi } from './export/export.js';
@@ -161,6 +161,7 @@ export type { CommentsCreateReceipt, CommentsCreateInput, CommentCreateAttributi
 export { executeCommentsCreate, executeCommentsPatch, executeCommentsDelete, executeGetComment, executeListComments, } from './comments/comments.js';
 export type { CommentInfo, CommentDomain, CommentMetadata, CommentMetadataValue, CommentsListQuery, CommentsListResult, CommentTrackedChangeSide, CommentTrackedChangeLink, CommentTarget, } from './comments/comments.types.js';
 export type { BlocksApi } from './blocks/blocks.js';
+export { executeBlocksFindText } from './blocks/find-text.js';
 export { executeBlocksList, executeBlocksDelete, executeBlocksDeleteRange, executeBlocksSplit, executeBlocksMerge, executeBlocksMove, } from './blocks/blocks.js';
 export { executeListsIndent, executeListsOutdent, executeListsGetState, executeListsApply, executeListsContinueV2, executeListsRestartV2, executeListsRemoveV2, } from './lists/lists.js';
 export { DocumentApiValidationError } from './errors.js';
@@ -242,8 +243,8 @@ export interface QueryApi {
     match(input: QueryMatchInput | TextSelector | NodeSelector): QueryMatchOutput;
 }
 export interface MutationsApi {
-    preview(input: MutationsPreviewInput): MutationsPreviewOutput;
-    apply(input: MutationsApplyInput): PlanReceipt;
+    preview(input: MutationsPreviewInput): Promise<MutationsPreviewOutput>;
+    apply(input: MutationsApplyInput): Promise<PlanReceipt>;
 }
 export interface RangesApi {
     resolve(input: ResolveRangeInput): ResolveRangeOutput;
@@ -255,8 +256,8 @@ export interface QueryAdapter {
     match(input: QueryMatchInput): QueryMatchOutput;
 }
 export interface MutationsAdapter {
-    preview(input: MutationsPreviewInput): MutationsPreviewOutput;
-    apply(input: MutationsApplyInput): PlanReceipt;
+    preview(input: MutationsPreviewInput): Promise<MutationsPreviewOutput>;
+    apply(input: MutationsApplyInput): Promise<PlanReceipt>;
 }
 /**
  * The Document API interface for querying and inspecting document nodes.
@@ -460,7 +461,7 @@ export interface DocumentApi {
     /**
      * Throughput-oriented batch executor with stepwise operation semantics.
      */
-    plan: PlanApi;
+    plan: PlanApi<PlanExecuteResult | Promise<PlanExecuteResult>>;
     /**
      * Snapshot-based document comparison and replay.
      */

package/dist/document-api/src/invoke/invoke.d.ts

@@ -1,7 +1,8 @@
 import { OperationId } from '../contract/types.js';
 import { OperationRegistry } from '../contract/operation-registry.js';
 import { DocumentApi } from '../index.js';
-type TypedDispatchHandler<K extends OperationId> = OperationRegistry[K]['options'] extends never ? (input: OperationRegistry[K]['input']) => OperationRegistry[K]['output'] : (input: OperationRegistry[K]['input'], options?: OperationRegistry[K]['options']) => OperationRegistry[K]['output'];
+type DispatchOutput<K extends OperationId> = K extends 'mutations.preview' | 'mutations.apply' ? Promise<OperationRegistry[K]['output']> : K extends 'plan.execute' ? OperationRegistry[K]['output'] | Promise<OperationRegistry[K]['output']> : OperationRegistry[K]['output'];
+type TypedDispatchHandler<K extends OperationId> = OperationRegistry[K]['options'] extends never ? (input: OperationRegistry[K]['input']) => DispatchOutput<K> : (input: OperationRegistry[K]['input'], options?: OperationRegistry[K]['options']) => DispatchOutput<K>;
 export type TypedDispatchTable = {
     [K in OperationId]: TypedDispatchHandler<K>;
 };

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

@@ -50,6 +50,14 @@ export interface BlockListEntry {
     ref?: string;
 }
 export interface BlocksListInput {
+    /** Filter top-level blocks by identity before pagination. Cell paragraphs do not match body blocks. */
+    nodeIds?: string[];
+    /** Literal terms matched against complete block text before pagination; occurrences are blocks. */
+    textSearch?: {
+        terms: string[];
+        match?: 'all' | 'any';
+        caseSensitive?: boolean;
+    };
     offset?: number;
     limit?: number;
     nodeTypes?: BlockNodeType[];
@@ -72,6 +80,36 @@ export interface BlocksListResult {
     /** Effective numbering review mode. Defaults to final when omitted from the request. */
     reviewMode: SDProjectionReviewMode;
 }
+export interface BlocksFindTextInput {
+    /** Literal, case-insensitive substring; whitespace and Unicode are not normalized. */
+    text: string;
+    /** Maximum matching blocks to return. Defaults to 8; zero returns counts only. */
+    limit?: number;
+}
+export interface BlocksFindTextMatch {
+    /** Zero-based top-level body ordinal, as in blocks.list. */
+    ordinal: number;
+    nodeId: string;
+    nodeType: BlockNodeType;
+    /** First 100 UTF-16 code units of the flattened block text. */
+    preview: string;
+}
+export interface BlocksFindTextResult {
+    /** Matching blocks, not occurrences, within the first 20,000 body blocks. */
+    total: number;
+    matches: BlocksFindTextMatch[];
+    /** Present even with limit: 0 so callers can locate a reading window. */
+    firstMatchOrdinal?: number;
+    scannedBlocks: number;
+    /** True when blocks beyond the scan cap were not searched. */
+    truncated: boolean;
+    /** A failed page read leaves preceding matches/counts intact; the scan is incomplete. */
+    scanError?: {
+        message: string;
+    };
+    /** Last successfully read revision, or "unknown" when the first page failed. */
+    revision: string;
+}
 export interface BlocksDeleteInput {
     target: DeletableBlockNodeAddress;
 }

package/dist/document-api/src/types/mutation-plan.types.d.ts

@@ -66,6 +66,10 @@ export type TextRewriteStep = {
     where: StepWhere;
     args: {
         replacement: ReplacementPayload;
+        /** Interpret positional `$1`…`$99` and `$&` tokens for regex matches. */
+        replacementMode?: 'literal' | 'regex-template';
+        /** Preserve the matched text's casing pattern instead of using replacement casing verbatim. */
+        caseHandling?: 'exact' | 'preserve-match';
         /**
          * Style policy for the replacement text.
          * When omitted, defaults to preserve mode:
@@ -157,10 +161,18 @@ export type MutationsPreviewInput = {
     atomic: true;
     changeMode: ChangeMode;
     steps: MutationStep[];
+    /** Optional page over verbose resolved-target details. Defaults to the first 100 targets. */
+    detail?: {
+        offset?: number;
+        limit?: number;
+    };
 };
 /** Maximum number of steps per mutation plan. */
 export declare const MAX_PLAN_STEPS = 200;
-/** Maximum total resolved targets across all steps in a plan. */
+/**
+ * @deprecated Historical compatibility metadata. Text replacement no longer
+ * enforces this value; callers must not treat it as a supported target limit.
+ */
 export declare const MAX_PLAN_RESOLVED_TARGETS = 500;
 export type StepEffect = 'changed' | 'noop' | 'error' | 'assert_passed' | 'assert_failed';
 /** Resolution for a single-block (range) target. */
@@ -189,9 +201,14 @@ export type SelectionStepResolution = {
 };
 export type TextStepData = {
     domain: 'text';
-    resolutions: TextStepResolution[];
-    spanResolutions?: SpanStepResolution[];
-    selectionResolutions?: SelectionStepResolution[];
+    /** Exact number of targets selected from the step's input revision. */
+    matchedCount: number;
+    /** Exact number of targets whose content changed. */
+    changedCount: number;
+    /** Exact number of targets already equal to their requested replacement. */
+    noopCount: number;
+    /** Exact number of tracked-change identities authored by this step. */
+    trackedChangeCount: number;
 };
 export type AssertStepData = {
     domain: 'assert';
@@ -247,7 +264,14 @@ export type PreviewFailure = {
 export type StepPreview = {
     stepId: string;
     op: string;
+    /** Exact number of targets resolved for this step. */
+    matchCount?: number;
     resolutions?: TextStepResolution[];
+    detailPage?: {
+        offset: number;
+        limit: number;
+        returned: number;
+    };
     spanResolutions?: SpanStepResolution[];
     selectionResolutions?: SelectionStepResolution[];
     style?: unknown;