@superdoc/mcp 1.9.0-next.12 → 1.9.0-next.13

package/dist/index.js

@@ -31620,7 +31620,7 @@ var init_host = __esm(() => {
 });
 
 // ../../packages/sdk/langs/node/src/runtime/sdk-version.generated.ts
-var SDK_VERSION = "2.22.0-next.12";
+var SDK_VERSION = "2.22.0-next.13";
 
 // ../../packages/sdk/langs/node/src/runtime/embedded-platform.ts
 import { accessSync, chmodSync, constants, existsSync, statSync } from "node:fs";
@@ -87423,10 +87423,10 @@ var init_action_descriptors = __esm(() => {
       operations: ["create.heading"]
     },
     replace_text: {
-      hint: "edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode? — for EDITING existing wording only; the replaced span is rewritten as PLAIN text (intra-span bold/italic is dropped), so keep find/replace spans MINIMAL (the words that change, not the whole paragraph) and NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
+      hint: "edits[{find,replace,occurrence?}], optional selector to scope replacements to one inspected block, caseSensitive?, expectedRevision?, changeMode? — for EDITING existing wording only; keep find/replace spans MINIMAL (the words that change, not the whole paragraph). When the find appears more than once in the selected block and only one should change, set that edit's occurrence (1-based match number within the block; requires selector; this is not selector.occurrence, which picks a block). NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
       group: "Text/structure actions",
       groupOrder: 2,
-      args: ["edits", "selector", "caseSensitive", "changeMode"],
+      args: ["edits", "selector", "caseSensitive", "expectedRevision", "changeMode"],
       operations: ["replace"]
     },
     delete_text: {
@@ -93107,12 +93107,10 @@ function normalizeTitleLikeRewriteText(targetText, rewrittenText) {
   const displayTitle = toDisplayTitleCase(targetText);
   if (rewrittenText.includes(displayTitle))
     return rewrittenText;
-  const lowerTarget = targetText.toLocaleLowerCase();
-  const lowerRewrite = rewrittenText.toLocaleLowerCase();
-  const index = lowerRewrite.indexOf(lowerTarget);
-  if (index < 0)
+  const match = findRanges(rewrittenText, targetText, false)[0];
+  if (!match)
     return rewrittenText;
-  return `${rewrittenText.slice(0, index)}${displayTitle}${rewrittenText.slice(index + targetText.length)}`;
+  return `${rewrittenText.slice(0, match.start)}${displayTitle}${rewrittenText.slice(match.end)}`;
 }
 async function executeCreateParagraph(doc2, text, placement, changeMode) {
   const fn = maybeMethod2(doc2, ["create", "paragraph"]);
@@ -93417,6 +93415,7 @@ async function runReplaceTextUnchecked(doc2, args) {
   const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc2);
   const pre = requiresBlockSnapshot ? await buildMutationSnapshot(doc2, { includeDomains: selectorDomains ?? ["blocks"] }) : snapshotFromIdentity(preIdentity);
   try {
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
     assertReplacementTextPayloads(args.edits);
     if (args.edits.length === 0) {
       return failedReceipt("replace_text", new Error("edits must be non-empty"), pre);
@@ -93425,7 +93424,7 @@ async function runReplaceTextUnchecked(doc2, args) {
     const selectedTargets = [];
     let skippedEdits = [];
     let steps;
-    let applyExpectedRevision;
+    let applyExpectedRevision = args.expectedRevision != null ? pre.revision : undefined;
     if (args.selector) {
       const target = selectorToBlockTarget(args.selector, pre);
       if (!target) {
@@ -95411,18 +95410,25 @@ function findRanges(haystack, needle, caseSensitive) {
   const ranges = [];
   if (needle.length === 0)
     return ranges;
-  const source = caseSensitive ? haystack : haystack.toLocaleLowerCase();
-  const target = caseSensitive ? needle : needle.toLocaleLowerCase();
-  let offset = 0;
-  while (offset < source.length) {
-    const idx = source.indexOf(target, offset);
-    if (idx < 0)
-      break;
-    ranges.push({ start: idx, end: idx + target.length });
-    offset = idx + target.length;
+  if (caseSensitive) {
+    let offset = 0;
+    while (offset < haystack.length) {
+      const idx = haystack.indexOf(needle, offset);
+      if (idx < 0)
+        break;
+      ranges.push({ start: idx, end: idx + needle.length });
+      offset = idx + needle.length;
+    }
+    return ranges;
+  }
+  for (const match of haystack.matchAll(caseInsensitivePattern(needle))) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
   }
   return ranges;
 }
+function caseInsensitivePattern(needle) {
+  return new RegExp(needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "giu");
+}
 async function runApplyLetterSpacing(doc2, args) {
   const pre = await buildMutationSnapshot(doc2, { includeDomains: ["blocks"] });
   try {
@@ -96168,29 +96174,59 @@ function trackedChangeRefIds(result) {
     return entityId ? [entityId] : [];
   }));
 }
-function parseScopedReplaceArgs(args, changeMode) {
-  if (args.action !== "replace_text")
-    return null;
+function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
   if (!isRecord2(args.selector))
     return null;
-  if (!Array.isArray(args.edits) || args.edits.length === 0)
-    return null;
-  const edits = [];
-  for (const entry of args.edits) {
-    if (!isRecord2(entry) || typeof entry.find !== "string" || entry.find.length === 0)
-      return null;
-    edits.push({ find: entry.find, replace: typeof entry.replace === "string" ? entry.replace : "" });
-  }
   return {
     edits,
     selector: args.selector,
     caseSensitive: args.caseSensitive === true,
+    expectedRevision,
     changeMode
   };
 }
+function assertExpectedReplacementRevision(expected, actual) {
+  if (expected != null && expected !== actual) {
+    throw new SuperDocCliError("replace_text: expectedRevision is stale. Inspect this live document again before editing.", {
+      code: "REVISION_CONFLICT"
+    });
+  }
+}
+async function fieldResultRanges(doc2, nodeId, blockText) {
+  const fn = maybeMethod2(doc2, ["fields", "list"]);
+  if (!fn)
+    return null;
+  const results = [];
+  const limit = 500;
+  for (let offset = 0;offset < 1e5; offset += limit) {
+    const page = await fn({ limit, offset });
+    const items = isRecord2(page) && Array.isArray(page.items) ? page.items.filter(isRecord2) : [];
+    for (const item of items) {
+      const address = isRecord2(item.address) ? item.address : null;
+      const inBody = typeof address?.storyId !== "string" || address.storyId.startsWith("main:");
+      if (address?.blockId !== nodeId || !inBody)
+        continue;
+      if (typeof item.resolvedText !== "string" || item.resolvedText.length === 0) {
+        return [{ start: 0, end: blockText.length }];
+      }
+      results.push(item.resolvedText);
+    }
+    const total = isRecord2(page) && typeof page.total === "number" ? page.total : null;
+    if (items.length < limit || total != null && offset + limit >= total)
+      break;
+  }
+  const ranges = [];
+  for (const result of results) {
+    for (let at = blockText.indexOf(result);at >= 0; at = blockText.indexOf(result, at + 1)) {
+      ranges.push({ start: at, end: at + result.length });
+    }
+  }
+  return ranges;
+}
 async function runScopedReplaceUnchecked(doc2, args) {
   assertReplacementTextPayloads(args.edits);
   const pre = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+  assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
   const matched = resolveSnapshotSelector(pre, args.selector);
   if (matched.length !== 1) {
     const failure2 = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -96210,13 +96246,22 @@ async function runScopedReplaceUnchecked(doc2, args) {
     };
   }
   const caseSensitive = args.caseSensitive === true;
+  const hasExplicitOccurrence = args.edits.some((edit) => edit.occurrence != null);
   const perEdit = [];
   const allSpans = [];
   for (const edit of args.edits) {
-    const spans = findRanges(block.text, edit.find, caseSensitive);
-    perEdit.push({ find: edit.find, occurrences: spans.length });
+    const matches = findRanges(block.text, edit.find, caseSensitive);
+    const spans = edit.occurrence == null ? matches : matches.slice(edit.occurrence - 1, edit.occurrence);
+    if (hasExplicitOccurrence && spans.length === 0) {
+      return failedReceipt("replace_text", new SuperDocCliError(edit.occurrence == null ? `replace_text: ${JSON.stringify(edit.find)} not found in the selected block. Inspect and choose a valid target.` : `replace_text: ${JSON.stringify(edit.find)} occurrence ${edit.occurrence} not found in the selected block (${matches.length} matches). Inspect and choose a valid target.`, { code: "MATCH_NOT_FOUND" }), pre);
+    }
+    perEdit.push({
+      find: edit.find,
+      occurrences: spans.length,
+      ...edit.occurrence != null ? { occurrence: edit.occurrence } : {}
+    });
     for (const span of spans)
-      allSpans.push({ ...span, replace: edit.replace ?? "", find: edit.find });
+      allSpans.push({ ...span, replace: edit.replace, find: edit.find });
   }
   const appliedEdits = perEdit.filter((e) => e.occurrences > 0);
   const skippedEdits = perEdit.filter((e) => e.occurrences === 0);
@@ -96241,6 +96286,9 @@ async function runScopedReplaceUnchecked(doc2, args) {
   let lastEnd = -1;
   for (const span of allSpans) {
     if (span.start < lastEnd) {
+      if (hasExplicitOccurrence) {
+        return failedReceipt("replace_text", new SuperDocCliError("replace_text: explicit occurrence targets overlap. Choose non-overlapping edits in the pre-edit block.", { code: "INVALID_ARGUMENT" }), pre);
+      }
       droppedOverlaps.push(span);
       continue;
     }
@@ -96249,24 +96297,45 @@ async function runScopedReplaceUnchecked(doc2, args) {
   }
   const expected = planned.reduceRight((text, span) => text.slice(0, span.start) + span.replace + text.slice(span.end), block.text);
   const tracked = (args.changeMode ?? "direct") === "tracked";
-  let result = null;
   const uniqueFinds = new Set(planned.map((s) => caseSensitive ? s.find : s.find.toLowerCase()));
-  if (tracked && uniqueFinds.size === planned.length) {
-    const spanSteps = planned.map((span, index) => ({
+  const deletions = tracked ? [] : planned.filter((span) => span.replace.length === 0);
+  const fieldRanges = deletions.length > 0 ? await fieldResultRanges(doc2, nodeId, block.text) : [];
+  const fieldDeletionRisk = fieldRanges == null || deletions.some((span) => fieldRanges.some((range) => span.start < range.end && span.end > range.start));
+  const exactTargets = !fieldDeletionRisk && (hasExplicitOccurrence || tracked && uniqueFinds.size === planned.length);
+  let result = null;
+  let wroteExactTargets = false;
+  if (exactTargets) {
+    const targetedSpans = [...planned].reverse().filter((span) => block.text.slice(span.start, span.end) !== span.replace);
+    const steps = targetedSpans.map((span, index) => ({
       id: `scoped-replace-${index + 1}`,
       op: "text.rewrite",
       where: {
-        by: "select",
-        select: { type: "text", pattern: span.find, mode: "contains", caseSensitive },
-        require: "first",
-        within: { kind: "block", nodeType: block.nodeType, nodeId }
+        by: "target",
+        target: {
+          kind: "selection",
+          start: { kind: "text", blockId: nodeId, offset: span.start },
+          end: { kind: "text", blockId: nodeId, offset: span.end }
+        }
       },
       args: { replacement: { text: span.replace }, style: preserveRewriteStyle() }
     }));
-    try {
-      result = await executeMutations(doc2, spanSteps, args.changeMode, pre.revision);
-    } catch {
-      result = null;
+    if (steps.length === 0) {
+      result = { noop: true };
+    } else {
+      const preview = await previewMutations(doc2, steps, args.changeMode, pre.revision);
+      const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord2) : [];
+      const aligned = preview.valid === true && steps.every((step, index) => {
+        const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
+        const resolved = Array.isArray(resolutions) && isRecord2(resolutions[0]) ? resolutions[0].text : undefined;
+        const span = targetedSpans[index];
+        return resolved === block.text.slice(span.start, span.end);
+      });
+      if (aligned) {
+        result = await executeMutations(doc2, steps, args.changeMode, pre.revision);
+        wroteExactTargets = true;
+      } else if (hasExplicitOccurrence) {
+        return failedReceipt("replace_text", new SuperDocCliError("replace_text: the chosen occurrence does not resolve to the same text in the document. Inspect again before editing.", { code: "TARGET_NOT_FOUND" }), pre);
+      }
     }
   }
   if (result == null) {
@@ -96280,9 +96349,20 @@ async function runScopedReplaceUnchecked(doc2, args) {
     ];
     result = await executeMutations(doc2, steps, args.changeMode, pre.revision);
   }
-  const post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
-  const postBlock = findTextTarget(post, nodeId);
-  const passed = postBlock != null && (tracked ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace)) : postBlock.text === expected);
+  let post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+  let postBlock = findTextTarget(post, nodeId);
+  let rolledBack = false;
+  const appliedRevision = isRecord2(result) && isRecord2(result.revision) ? result.revision.after : undefined;
+  if (wroteExactTargets && postBlock != null && postBlock.text !== expected && postBlock.text !== block.text && typeof appliedRevision === "string" && appliedRevision === post.revision) {
+    const undoFn = maybeMethod2(doc2, ["history", "undo"]);
+    if (undoFn) {
+      await undoFn({});
+      post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+      postBlock = findTextTarget(post, nodeId);
+      rolledBack = postBlock?.text === block.text;
+    }
+  }
+  const passed = postBlock != null && !rolledBack && (tracked && !hasExplicitOccurrence && !wroteExactTargets ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace)) : postBlock.text === expected);
   const status = !passed ? "failed" : skippedEdits.length > 0 ? "partial" : "ok";
   return {
     status,
@@ -96291,6 +96371,14 @@ async function runScopedReplaceUnchecked(doc2, args) {
       nextStep: `${skippedEdits.length} of ${perEdit.length} edits were NOT applied — the find text is not in the selected block. ` + `Do not stop: call replace_text again for the remaining edits with a different selector (or no selector for a global replace).`,
       recovery: { kind: "retry" }
     } : {},
+    ...rolledBack ? {
+      errors: [
+        {
+          code: "ACTION_FAILED",
+          message: "replace_text: the engine changed more than the requested text, so the edit was undone. Inspect the block and retry with a larger find or rewrite the whole block."
+        }
+      ]
+    } : {},
     preSnapshot: { revision: pre.revision },
     postSnapshot: { revision: post.revision },
     selectedBlock: { nodeId, nodeType: block.nodeType },
@@ -97622,8 +97710,17 @@ async function dispatchSuperdocPerformAction(doc2, args) {
           code: "INVALID_ARGUMENT"
         });
       }
+      const expectedRevision = args.expectedRevision;
+      if (expectedRevision !== undefined && (typeof expectedRevision !== "string" || expectedRevision.length === 0)) {
+        throw new SuperDocCliError("replace_text: expectedRevision must be a non-empty string from this live document handle", { code: "INVALID_ARGUMENT" });
+      }
+      if (edits.some((edit) => edit.occurrence != null) && !isRecord2(args.selector)) {
+        throw new SuperDocCliError("replace_text: explicit occurrence requires a selector resolving to one block", {
+          code: "INVALID_ARGUMENT"
+        });
+      }
       const changeMode = parseReplaceTextChangeMode(args.changeMode);
-      const scoped = parseScopedReplaceArgs(args, changeMode);
+      const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision);
       if (scoped) {
         return runScopedReplace(doc2, scoped);
       }
@@ -97636,6 +97733,7 @@ async function dispatchSuperdocPerformAction(doc2, args) {
         edits,
         selector,
         caseSensitive: args.caseSensitive === true,
+        expectedRevision,
         changeMode
       });
     }
@@ -98281,7 +98379,11 @@ function parseEdits2(value) {
     const replace = asString2(entry.replace) ?? "";
     if (!find)
       return;
-    result.push({ find, replace });
+    const occurrence = entry.occurrence;
+    if (occurrence !== undefined && (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence) || occurrence < 1)) {
+      throw new SuperDocCliError("replace_text: occurrence must be a positive safe integer (one-based within the selected block)", { code: "INVALID_ARGUMENT" });
+    }
+    result.push({ find, replace, ...occurrence !== undefined ? { occurrence } : {} });
   }
   return result;
 }
@@ -98743,10 +98845,24 @@ var init_catalog = __esm(() => {
       type: "array",
       items: {
         type: "object",
-        properties: { find: { type: "string" }, replace: { type: "string" } },
+        properties: {
+          find: { type: "string" },
+          replace: { type: "string" },
+          occurrence: {
+            type: "integer",
+            minimum: 1,
+            maximum: Number.MAX_SAFE_INTEGER,
+            description: "Change only this match of find in the selected block (1 = first, counted on visible text). Requires selector; omit to replace every match."
+          }
+        },
         required: ["find"]
       }
     },
+    expectedRevision: {
+      type: "string",
+      minLength: 1,
+      description: "Revision from your latest superdoc_inspect or receipt (postSnapshot.revision) on this document. Pass it with occurrence: if the document changed since (another collaborator edited), the edit is refused with REVISION_CONFLICT; inspect again and recount. Not portable between peers or reopen."
+    },
     finds: { type: "array", items: { type: "string" } },
     caseSensitive: { type: "boolean" },
     evidence: {
@@ -99646,7 +99762,7 @@ var init_runtime = __esm(() => {
 var EMBEDDED_PROMPTS;
 var init_embedded_prompts_generated = __esm(() => {
   EMBEDDED_PROMPTS = {
-    "mcp-prompt.md": 'SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: "/path/to/file.docx"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool\'s own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n',
+    "mcp-prompt.md": 'SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: "/path/to/file.docx"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool\'s own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Target one repeated match.** For `replace_text`, scope to one block with a selector and set `occurrence` on the edit (1 = first match in that block) to change only that match. Also pass `expectedRevision` from your latest inspect or receipt; on `REVISION_CONFLICT`, inspect again and recount.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n',
     "system-prompt.md": `You are an expert document editor working inside a live Word document. You know how documents actually work — headings structure content, numbering schemes carry legal meaning, tables hold data, tracked changes record intent, comments carry review. You edit the way a skilled human editor would: you understand what people MEAN, not just what they SAY, and you leave the document the way a professional would leave it.
 
 ============================================================
@@ -99697,7 +99813,7 @@ ACTIONS (superdoc_perform_action with flat args)
 - undo_changes: untilMarker (rendered marker from the original state, e.g. "2.1.") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.
 - redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.
 - attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. "10."). Makes an EXISTING block a numbered clause at the same scheme/level — "make this the section 11 heading" in a clause-numbered document is exactly this (it will render as the next number).
-- replace_text: edits:[{find,replace}], caseSensitive default false. selector to scope. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
+- replace_text: edits:[{find,replace,occurrence?}], caseSensitive default false. selector to scope. Keep find/replace spans MINIMAL. If the find appears more than once in the selected block and only one should change, give that edit occurrence (1 = first match in the block; needs selector; not selector.occurrence). With occurrence, also pass expectedRevision from your latest inspect or receipt; on REVISION_CONFLICT inspect again and recount. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
 - delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:"tracked" if asked. Deletes TEXT ONLY: the block survives, so a list item keeps its bullet/number and an accepted tracked deletion leaves an empty numbered item behind. To remove the item itself use delete_blocks.
 - delete_blocks: selectors:[…], each resolving to ONE block (list item, paragraph or heading). changeMode:"tracked" if asked. THE way to DELETE a whole LIST ITEM, paragraph or heading — the bullet/number goes with it and the remaining items renumber. "Delete the first item under Article II" / "remove that clause" is exactly this, NOT delete_text. Pass every target in ONE call. Use delete_table for a whole table.
 - rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.
@@ -202071,6 +202187,7 @@ function commitResidentText(input, view) {
     return null;
   const range = { byteStart: paragraph.byteStart, byteEnd: paragraph.byteEnd };
   const collapsed = op.on.startOffset === op.on.endOffset;
+  const leadingBookmarkBoundary = collapsed && op.newText.length > 0 && edit.visibleStart === 0 && edit.before.model.leaves().some((piece) => piece.kind === "marker" && piece.visibleStart === 0 && (piece.markerKind === "bookmarkStart" || piece.markerKind === "bookmarkEnd"));
   const requiresCollaborationSessionSync = op.changeMode === "direct" && op.on.coordinateSpace === "tracked" && edit.visibleStart !== op.on.startOffset;
   return finalizeCommit({
     input,
@@ -202095,7 +202212,8 @@ function commitResidentText(input, view) {
       blockId: op.on.startBlockId,
       startOffset: edit.visibleStart,
       text: op.newText,
-      runPropertiesXml: leaf.runProperties ?? ""
+      runPropertiesXml: leaf.runProperties ?? "",
+      ...leadingBookmarkBoundary ? { afterLeadingMarkers: true } : {}
     } } : {},
     ...edit.insertionRsid && !collapsed ? { trackedTextRefinement: {
       kind: "trackedTextRefinement",
@@ -385326,6 +385444,7 @@ class V2ListsAdapter {
     if (insertReceipt.status === "rejected") {
       return failure8(mapRejectionReason(insertReceipt.rejectedReason ?? "internal-error"), insertReceipt.rejectedReason ?? "list insert: paragraph insert rejected");
     }
+    this.context.invalidate(insertReceipt);
     recordCommittedTxIdForHistory(this.context, insertReceipt.txId);
     const newParaId = readCreatedParagraphRefId(insertReceipt.createdRefs ?? [], insertReceipt.provisionalToFinal);
     if (!newParaId) {
@@ -385452,6 +385571,7 @@ class V2ListsAdapter {
       if (insertReceipt.status === "rejected") {
         return failure8(mapRejectionReason(insertReceipt.rejectedReason ?? "internal-error"), insertReceipt.rejectedReason ?? "list create: paragraph insert rejected");
       }
+      this.context.invalidate(insertReceipt);
       recordCommittedTxIdForHistory(this.context, insertReceipt.txId);
       const newParaId = readCreatedParagraphRefId(insertReceipt.createdRefs ?? [], insertReceipt.provisionalToFinal);
       if (!newParaId) {
@@ -387183,6 +387303,7 @@ function applyListSeed(adapter, storyId, paraId, kind, expectedRevision, changeM
   if (receipt3.status === "rejected") {
     return failure8(mapRejectionReason(receipt3.rejectedReason ?? "internal-error"), receipt3.rejectedReason ?? "list create rejected");
   }
+  adapter.context.invalidate(receipt3);
   recordCommittedTxIdForHistory(adapter.context, receipt3.txId);
   const summary = readListItemSummaryForSession(adapter.context.session, storyId, paraId);
   return {
@@ -419238,8 +419359,67 @@ async function compilePlan(context, input) {
   }
   detectTargetConflicts(context, steps, failures);
   detectUnsupportedRuntimeDrift(input.steps, failures);
-  detectTargetOffsetDriftRisk(steps, failures);
-  return { evaluatedRevision, steps, failures };
+  const exactProgram = failures.length === 0 ? compileDescendingExactTargets(context, steps) : undefined;
+  if (exactProgram) {
+    if (exactProgram.edits.length > 0) {
+      const preview = new V2SelectionMutationAdapter(context).executeResolvedTextRewrites(exactProgram.edits, { changeMode: changeMode ?? "direct", dryRun: true });
+      if (!preview.success)
+        failures.push({
+          code: preview.failure.code,
+          stepId: exactProgram.edits[0].ownerStepId,
+          phase: "compile",
+          message: preview.failure.message
+        });
+    }
+  } else
+    detectTargetOffsetDriftRisk(steps, failures);
+  return {
+    evaluatedRevision,
+    steps,
+    failures,
+    ...exactProgram ? { atomicTextProgram: exactProgram } : {}
+  };
+}
+function compileDescendingExactTargets(context, steps) {
+  const mutating = steps.filter((step3) => step3.op !== "assert");
+  if (mutating.length < 2)
+    return;
+  const edits = [];
+  let blockId;
+  let previousStart = Infinity;
+  const index2 = getSDDocumentSessionInternalParagraphIndex(context.session);
+  if (!index2)
+    return;
+  for (const step3 of mutating) {
+    const source = step3.source;
+    if (step3.op !== "text.rewrite" && step3.op !== "text.delete" || source.op === "assert" || !("where" in source) || source.where.by !== "target" || !step3.resolution || step3.request?.kind !== "replace")
+      return;
+    const target = source.where.target;
+    if (target.kind !== "selection" || target.start.kind !== "text" || target.end.kind !== "text" || target.coordinateSpace === "tracked" || !isSupportedMutationStoryScope(target.story) || !isSupportedMutationStoryScope(target.start.story) || !isSupportedMutationStoryScope(target.end.story) || target.start.blockId !== target.end.blockId)
+      return;
+    blockId ?? (blockId = target.start.blockId);
+    if (target.start.blockId !== blockId || step3.resolution.range.from >= step3.resolution.range.to || step3.resolution.range.to > previousStart)
+      return;
+    previousStart = step3.resolution.range.from;
+    const on = resolveSelectionTargetToRange({
+      target,
+      index: index2,
+      readPartBytes: (partUri) => getSDDocumentSessionInternalPartBytes(context.session, partUri),
+      readPartRange: (partUri, start, end) => getSDDocumentSessionInternalPartRange(context.session, partUri, start, end),
+      buildOffsetMap: buildOffsetMapForCoordinateSpace4
+    });
+    if ("error" in on)
+      throw new DocumentApiValidationError2(on.error, on.message);
+    if (step3.request.text !== step3.resolution.text)
+      edits.push({
+        on,
+        newText: step3.request.text,
+        resolution: step3.resolution,
+        ownerStepId: step3.stepId,
+        rewriteIntent: step3.op === "text.rewrite"
+      });
+  }
+  return { edits };
 }
 function isOrderedAtomicTextProgram(steps) {
   return steps.length > 1 && steps.every((step3) => (step3.op === "text.rewrite" || step3.op === "text.delete") && step3.where.by === "select" && step3.where.select.type === "text" && step3.where.require === "all");
@@ -420836,6 +421016,7 @@ var init_engine3 = __esm(() => {
   init_sd_document_session_internal();
   init_search();
   init_raw_block_ref();
+  init_selection_target();
   init_story_identity();
   init_story_surface();
   init_v2_search_ref();
@@ -475191,7 +475372,7 @@ function tryMirrorStoryText(prepared, extension2, options, admitted) {
             text: source.newText,
             txId: prepared.txId,
             directInsert: validation.directInsert,
-            preserveZeroLengthAtOffset: validation.inlineControl?.afterParagraphTail,
+            preserveZeroLengthAtOffset: validation.directInsert.afterLeadingMarkers || validation.inlineControl?.afterParagraphTail,
             acceptedTextInsertionSplit: validation.acceptedTextInsertionSplit
           });
         } else {
@@ -475622,7 +475803,7 @@ function validateDirectTextInsert(source, extension2) {
   if (!directInsert) {
     return { ok: false, failureReason: "direct insert requires typed storySurface metadata" };
   }
-  if (directInsert.kind !== "directTextInsert" || directInsert.blockId !== source.on.startBlockId || directInsert.startOffset !== source.on.startOffset || directInsert.text !== source.newText) {
+  if (directInsert.kind !== "directTextInsert" || directInsert.blockId !== source.on.startBlockId || directInsert.startOffset !== source.on.startOffset || directInsert.text !== source.newText || directInsert.afterLeadingMarkers !== undefined && (directInsert.afterLeadingMarkers !== true || directInsert.startOffset !== 0)) {
     return { ok: false, failureReason: "direct insert storySurface metadata does not match source" };
   }
   if (parsePreparedRunAttributes(directInsert.runPropertiesXml) === null) {
@@ -485392,8 +485573,12 @@ function jsonSchemaPropertyToZod(prop, definitions = {}, resolvingReferences = n
     return describe3(intersection3);
   }
   switch (type) {
-    case "string":
-      return describe3(exports_external.string());
+    case "string": {
+      let schema = exports_external.string();
+      if (typeof prop.minLength === "number")
+        schema = schema.min(prop.minLength);
+      return describe3(schema);
+    }
     case "number": {
       let schema = exports_external.number();
       if (typeof prop.exclusiveMinimum === "number")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/mcp",
-  "version": "1.9.0-next.12",
+  "version": "1.9.0-next.13",
   "description": "Model Context Protocol server for SuperDoc, giving an AI agent tools to read and edit .docx files.",
   "type": "module",
   "license": "AGPL-3.0",
@@ -24,13 +24,13 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@superdoc/sdk": "2.22.0-next.12",
+    "@superdoc/sdk": "2.22.0-next.13",
     "debug": "^4.4.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "superdoc": "2.25.0-next.12",
-    "@superdoc/docx-engine": "0.24.0-next.12",
+    "superdoc": "2.25.0-next.13",
+    "@superdoc/docx-engine": "0.24.0-next.13",
     "@superdoc/document-api": "0.1.0-alpha.0",
     "@types/bun": "^1.3.8",
     "@types/node": "22.19.2",