@superdoc/sdk 2.22.0-next.9 → 2.23.0-next.1

package/dist/agent/actions.js

@@ -162,13 +162,15 @@ function findSnapshotTextByNodeId(snapshot, nodeId) {
 }
 function createdBlockTarget(result) {
     const rec = asRecord(result);
-    const paragraph = asRecord(rec?.paragraph);
-    if (typeof paragraph?.nodeId === 'string' && paragraph.nodeId.length > 0) {
-        return { nodeId: paragraph.nodeId, nodeType: 'paragraph' };
-    }
-    const heading = asRecord(rec?.heading);
-    if (typeof heading?.nodeId === 'string' && heading.nodeId.length > 0) {
-        return { nodeId: heading.nodeId, nodeType: 'heading' };
+    for (const [key, nodeType] of [
+        ['paragraph', 'paragraph'],
+        ['heading', 'heading'],
+        ['item', 'listItem'],
+    ]) {
+        const block = asRecord(rec?.[key]);
+        if (typeof block?.nodeId === 'string' && block.nodeId.length > 0) {
+            return { nodeId: block.nodeId, nodeType };
+        }
     }
     return null;
 }
@@ -598,12 +600,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(doc, text, placement, changeMode) {
     const fn = maybeMethod(doc, ['create', 'paragraph']);
@@ -972,6 +972,7 @@ async function runReplaceTextUnchecked(doc, args) {
         ? await buildMutationSnapshot(doc, { 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);
@@ -980,7 +981,7 @@ async function runReplaceTextUnchecked(doc, 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) {
@@ -1545,7 +1546,7 @@ async function runInsertListItems(doc, args) {
     }
 }
 async function runAddListItems(doc, args, opts) {
-    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
     try {
         const needle = args.anchorText?.trim();
         const anchorNodeId = args.anchorNodeId?.trim();
@@ -1596,25 +1597,47 @@ async function runAddListItems(doc, args, opts) {
         }
         const anchorPath = blockNumbering(anchor)?.path;
         const anchorLevel = Array.isArray(anchorPath) ? Math.max(0, anchorPath.length - 1) : 0;
+        const listByNodeId = new Map((pre.lists ?? []).flatMap((list) => list.items.map((item) => [item.nodeId, list.listId])));
+        const anchorListId = listByNodeId.get(anchor.nodeId);
+        // The lists snapshot is paged, so a missing item is unknown, not foreign.
+        const belongsToAnchorList = (row) => {
+            const rowListId = row.nodeId == null ? undefined : listByNodeId.get(row.nodeId);
+            return anchorListId == null || rowListId == null || rowListId === anchorListId;
+        };
         // Place new items AFTER the anchor's whole sub-tree — every following item
         // whose numbering PATH is nested under the anchor's path (e.g. [12] ⊂ [12,4]).
         // Match by path prefix, not merely "deeper level", and SKIP interleaved
         // non-numbered paragraphs (list-item continuations) rather than stopping at
         // them — real lists wrap sub-items across plain paragraphs. Stop at the first
         // numbered item that is NOT a descendant (a sibling/ancestor, or a different
-        // list). Without this, a new same-level item wedges in among the anchor's
+        // unrelated list). Without this, a new same-level item wedges in among the anchor's
         // children and steals the ones after it. No descendants → the anchor itself.
         let subtreeEnd = anchor;
         const anchorPathArr = Array.isArray(anchorPath) ? anchorPath : null;
         const anchorIdx = rows.findIndex((r) => r.nodeId === anchor.nodeId);
         if (anchorPathArr && anchorIdx >= 0) {
             const isDescendant = (p) => Array.isArray(p) && p.length > anchorPathArr.length && anchorPathArr.every((v, k) => p[k] === v);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = anchorIdx;
             for (let i = anchorIdx + 1; i < rows.length; i += 1) {
                 const p = blockNumbering(rows[i])?.path;
-                if (isDescendant(p)) {
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                const foreign = !belongsToAnchorList(rows[i]) && listId != null;
+                // A separate numbering definition counts on its own, so its path need
+                // not start with the anchor's path ([1, 2] under [2]); go by depth.
+                const nestedForeign = foreign && Array.isArray(p) && p.length > anchorPathArr.length;
+                if (isDescendant(p) || nestedForeign) {
+                    if (foreign && !descendantListIds.has(listId)) {
+                        // Nested bullets can use a separate numbering definition. Its first
+                        // item must be contiguous; a new list after plain text is unrelated.
+                        if (i !== lastDescendantIdx + 1)
+                            break;
+                        descendantListIds.add(listId);
+                    }
                     subtreeEnd = rows[i]; // a nested child/grandchild of the anchor
+                    lastDescendantIdx = i;
                 }
-                else if (Array.isArray(p)) {
+                else if (Array.isArray(p) || (blockNumbering(rows[i]) && !belongsToAnchorList(rows[i]))) {
                     break; // a numbered item that is NOT a descendant → sub-tree ended
                 }
                 // else: non-numbered paragraph (a continuation) — skip and keep scanning
@@ -1632,30 +1655,55 @@ async function runAddListItems(doc, args, opts) {
         if (firstRelative < 0) {
             const firstTargetLevel = Math.max(0, anchorLevel + firstRelative);
             const startIdx = rows.findIndex((r) => r.nodeId === subtreeEnd.nodeId);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = startIdx;
             for (let i = startIdx + 1; i >= 1 && i < rows.length; i += 1) {
                 const level = levelOfRow(rows[i]);
                 if (level == null)
                     continue; // non-numbered continuation paragraph
                 if (level <= firstTargetLevel)
                     break;
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                if (!belongsToAnchorList(rows[i]) && listId != null && !descendantListIds.has(listId)) {
+                    if (i !== lastDescendantIdx + 1)
+                        break;
+                    descendantListIds.add(listId);
+                }
                 subtreeEnd = rows[i];
+                lastDescendantIdx = i;
             }
         }
+        const anchorKind = blockNumbering(anchor)?.kind ?? null;
+        // Search nearest first within the destination level. A known list may mix
+        // ordered and bullet levels. Keep the numbering-kind fallback only when
+        // the paged snapshot cannot establish that both items share a list.
+        const findSiblingAt = (level) => {
+            const usable = (r) => !!r?.nodeId &&
+                belongsToAnchorList(r) &&
+                levelOfRow(r) === level &&
+                ((anchorListId != null && listByNodeId.get(r.nodeId) === anchorListId) ||
+                    (blockNumbering(r)?.kind ?? null) === anchorKind);
+            for (let delta = 1; delta <= rows.length; delta += 1) {
+                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
+                if (usable(before))
+                    return before;
+                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
+                if (usable(after))
+                    return after;
+            }
+            return undefined;
+        };
+        /** The existing item a new one should look like: same level, nearest first. */
+        const formattingSourceForLevel = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
         const attachFn = maybeMethod(doc, ['lists', 'attach']);
-        if (!attachFn) {
-            throw new SuperDocCliError('doc.lists.attach is not available on the document handle.', {
+        const insertFn = maybeMethod(doc, ['lists', 'insert']);
+        if (!attachFn || !insertFn) {
+            throw new SuperDocCliError('doc.lists.insert and doc.lists.attach are required on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
         }
         const executed = [];
-        let placement = {
-            kind: 'after',
-            target: {
-                kind: 'block',
-                nodeType: subtreeEnd.nodeType ?? 'listItem',
-                nodeId: subtreeEnd.nodeId ?? anchor.nodeId,
-            },
-        };
+        let insertionAnchorId = subtreeEnd.nodeId ?? anchor.nodeId;
         const createdItems = [];
         for (const entry of args.entries) {
             // Styled items carry ordered `runs`; a plain item is a single run. The
@@ -1668,11 +1716,25 @@ async function runAddListItems(doc, args, opts) {
             // outline level is clamped at 0 (can't go above the root).
             const rel = typeof entry?.level === 'number' ? Math.floor(entry.level) : 0;
             const targetLevel = Math.max(0, anchorLevel + rel);
-            const created = await executeCreateParagraph(doc, text, placement, args.changeMode);
+            const formattingSource = formattingSourceForLevel(targetLevel) ?? anchor;
+            // Placement can follow a child with different direction. Inherit from
+            // the intended list level independently of that insertion point.
+            const created = await insertFn({
+                target: { kind: 'block', nodeType: 'listItem', nodeId: insertionAnchorId },
+                position: 'after',
+                text,
+                ...(formattingSource.nodeId !== insertionAnchorId
+                    ? { inheritFrom: { kind: 'block', nodeType: 'listItem', nodeId: formattingSource.nodeId } }
+                    : {}),
+                ...(args.changeMode ? { changeMode: args.changeMode } : {}),
+            }, args.changeMode ? { changeMode: args.changeMode } : undefined);
             const target = createdBlockTarget(created);
-            executed.push({ operationId: 'doc.create.paragraph', result: created });
-            if (!target)
-                continue;
+            if (!target || target.nodeType !== 'listItem') {
+                throw new SuperDocCliError('doc.lists.insert did not return a created list item.', {
+                    code: 'ACTION_FAILED',
+                });
+            }
+            executed.push({ operationId: 'doc.lists.insert', result: created });
             // changeMode is a MutationOption — pass it in the second options arg, not
             // the input (lists.attach reads options.changeMode; input.changeMode is ignored).
             const attachResult = await attachFn({
@@ -1688,53 +1750,10 @@ async function runAddListItems(doc, args, opts) {
                 rationale: `level ${targetLevel}`,
             });
             createdItems.push({ nodeId: target.nodeId, targetLevel, text, runs, itemMarks: entry?.marks });
-            // After attach the block is a listItem (same nodeId) — the next placement
-            // must address it as such or the create resolver rejects the anchor.
-            placement = { kind: 'after', target: { kind: 'block', nodeType: 'listItem', nodeId: target.nodeId } };
-        }
-        // A new item is created next to the ANCHOR, so it inherits the anchor's
-        // direct indentation — correct at the same level, wrong at any other one.
-        // `lists.attach` sets the numbering level (`w:ilvl`) but leaves that direct
-        // `w:ind` alone, so a level-changing add renders with a sub-item's indent
-        // under a top-level number: e.g. an item promoted to level 0 kept
-        // left=1800 while its "1./2./3." siblings sit at 1080. Copy the indentation
-        // from an EXISTING sibling at the item's own level. Best-effort: an
-        // unmatched indent is cosmetic and must not fail an item that landed.
-        const createdIds = new Set(createdItems.map((ci) => ci.nodeId));
-        const anchorKind = blockNumbering(anchor)?.kind ?? null;
-        // Search OUTWARD from the anchor, nearest first, and only accept items
-        // of the anchor's own numbering kind: a document holds several lists,
-        // and the first level-0 item in document order usually belongs to a
-        // different one (here: a bullet list far above the ordered list being
-        // extended), whose indentation is unrelated.
-        const findSiblingAt = (level) => {
-            const usable = (r) => !!r?.nodeId &&
-                !createdIds.has(r.nodeId) &&
-                levelOfRow(r) === level &&
-                (blockNumbering(r)?.kind ?? null) === anchorKind;
-            for (let delta = 1; delta <= rows.length; delta += 1) {
-                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
-                if (usable(before))
-                    return before;
-                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
-                if (usable(after))
-                    return after;
-            }
-            return undefined;
-        };
-        /** The existing item a new one should look like: same level, nearest first. */
-        const lookSourceFor = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
-        // Most Word documents keep a list's look in a paragraph STYLE, not in direct
-        // properties: "MB Agr 2", "Quick 1.", even Heading3 carry the numbering, the
-        // indentation and the face. A created paragraph does not get the sibling's
-        // style — it gets the anchor's `next` style (Heading3 → BodyText), a default
-        // (ListParagraph, whose contextualSpacing changes the spacing), or the
-        // anchor's own style when the new item belongs to a DIFFERENT level (keeping
-        // "MB Agr 3" on an item whose numbering now says level 2). Reconcile it with
-        // the sibling at the item's own level.
-        //
-        // setStyleRef, not setStyle: setStyle clears direct run formatting, which
-        // would wipe the sampled run look applied below.
+            insertionAnchorId = target.nodeId;
+        }
+        // Insertion may select a style's `next` style; keep the destination list level's
+        // style instead. setStyleRef preserves the inherited direct run formatting.
         const styledItems = [];
         const styleSkipped = await bestEffort(async () => {
             const setStyleRefFn = maybeMethod(doc, ['styles', 'paragraph', 'setStyleRef']);
@@ -1743,7 +1762,7 @@ async function runAddListItems(doc, args, opts) {
                 return;
             let current = null;
             for (const ci of createdItems) {
-                const source = lookSourceFor(ci.targetLevel);
+                const source = formattingSourceForLevel(ci.targetLevel);
                 if (!source)
                     continue;
                 const wanted = source.styleId ?? null;
@@ -1761,6 +1780,8 @@ async function runAddListItems(doc, args, opts) {
                 styledItems.push({ nodeId: ci.nodeId, styleId: wanted });
             }
         });
+        // lists.attach changes numbering level without normalizing direct indentation.
+        // Match the existing destination level when its indentation is available.
         const indentedItems = [];
         const indentSkipped = await bestEffort(async () => {
             const setIndentFn = maybeMethod(doc, ['format', 'paragraph', 'setIndentation']);
@@ -1768,7 +1789,7 @@ async function runAddListItems(doc, args, opts) {
             if (!setIndentFn || !getNodeFn)
                 return;
             for (const ci of createdItems) {
-                const sibling = lookSourceFor(ci.targetLevel);
+                const sibling = formattingSourceForLevel(ci.targetLevel);
                 if (!sibling?.nodeId)
                     continue;
                 const node = (await getNodeFn({ id: sibling.nodeId }));
@@ -1851,7 +1872,7 @@ async function runAddListItems(doc, args, opts) {
             // The BASE layer must come from the row the item will sit beside, not
             // from the anchor: a promoted or demoted item crosses levels, and the
             // anchor's font/size/colour/emphasis is then the wrong level's look.
-            // `lookSourceFor(targetLevel)` already picks the destination sibling for
+            // `formattingSourceForLevel(targetLevel)` already picks the destination sibling for
             // style and indent, so the look follows the same source. Falls back to
             // the anchor only when the destination level has no sibling to sample.
             const anchorBase = inlineLookFromRow(anchor);
@@ -1889,7 +1910,7 @@ async function runAddListItems(doc, args, opts) {
                     // An item the agent styled itself is left alone by layers 1–2: its
                     // marks describe the whole intent, and sampling would fight them.
                     const unstyled = ci.itemMarks == null && !ci.runs.some((r) => r.marks);
-                    const source = unstyled ? lookSourceFor(ci.targetLevel) : undefined;
+                    const source = unstyled ? formattingSourceForLevel(ci.targetLevel) : undefined;
                     const sourceText = source?.nodeId ? fullTextById.get(source.nodeId) : undefined;
                     const pattern = source?.nodeId && sourceText ? await listItemRunPattern(doc, sourceText, source.nodeId) : null;
                     // 1. sampled base over the whole item (row fields first, run-level
@@ -1969,7 +1990,7 @@ async function runAddListItems(doc, args, opts) {
                 // promotion keeps the plain marker until that read lands.
                 let markProps = markRunPropsFromMarks({ ...ci.itemMarks, ...ci.runs[0]?.marks });
                 if (!markProps && getNodeFn) {
-                    const source = lookSourceFor(ci.targetLevel);
+                    const source = formattingSourceForLevel(ci.targetLevel);
                     if (source?.nodeId)
                         markProps = paragraphMarkRunPropsOf(await getNodeFn({ id: source.nodeId }));
                 }
@@ -3434,18 +3455,28 @@ 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;
+    }
+    // Match case-insensitively on the original string. Lowercasing a copy first
+    // changes its length for characters such as "İ", which shifts every later
+    // offset onto the wrong text.
+    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(doc, args) {
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
@@ -4276,29 +4307,64 @@ function trackedChangeRefIds(result) {
         return entityId ? [entityId] : [];
     }));
 }
-function parseScopedReplaceArgs(args, changeMode) {
-    if (args.action !== 'replace_text')
-        return null;
+function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
     if (!isRecord(args.selector))
         return null;
-    if (!Array.isArray(args.edits) || args.edits.length === 0)
-        return null;
-    const edits = [];
-    for (const entry of args.edits) {
-        if (!isRecord(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',
+        });
+    }
+}
+// Ranges of the block text that may show a body field's result. Field
+// results carry no offsets, so every place the result text occurs counts,
+// overlapping ones included. A field whose result text is not reported (some
+// imported fields expose an empty result while displaying cached text) covers
+// the whole block. Returns null when the field catalog cannot be read.
+async function fieldResultRanges(doc, nodeId, blockText) {
+    const fn = maybeMethod(doc, ['fields', 'list']);
+    if (!fn)
+        return null;
+    const results = [];
+    const limit = 500;
+    for (let offset = 0; offset < 100_000; offset += limit) {
+        const page = await fn({ limit, offset });
+        const items = isRecord(page) && Array.isArray(page.items) ? page.items.filter(isRecord) : [];
+        for (const item of items) {
+            const address = isRecord(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 = isRecord(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(doc, args) {
     assertReplacementTextPayloads(args.edits);
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
     const matched = resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -4318,13 +4384,24 @@ async function runScopedReplaceUnchecked(doc, 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);
@@ -4352,45 +4429,82 @@ async function runScopedReplaceUnchecked(doc, 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;
         }
         planned.push(span);
         lastEnd = span.end;
     }
-    // The v2 engine resolves `where` by block/select/ref only — a
-    // selection-targeted step ("by: 'target'") dies in resolveStepRef with
-    // "requires a ref produced by query.match/find".
+    // The block text once every planned span is replaced: the whole-block
+    // rewrite writes it, and exact-target writes must produce it.
     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';
     // Unique tracked finds can be resolved within the block. Repeated finds
     // use one whole-block rewrite, whose engine diff preserves unchanged runs.
-    let result = null;
-    // Dedupe on the same basis the selector will match on: under a
-    // case-sensitive request `Foo` and `foo` are distinct targets, and folding
-    // them together would push a legitimately unique pair onto the fallback.
+    // Dedupe on the same basis the planner matched on: under a case-sensitive
+    // request `Foo` and `foo` are distinct targets, and folding them together
+    // would push a legitimately unique pair onto the fallback.
     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) => ({
+    // Explicit occurrences and unique tracked finds are written at the offsets
+    // matched above. A whole-block diff could redline a different identical
+    // occurrence while producing the same final text, and the engine's own text
+    // search would match again with its own case rules.
+    // A direct deletion through an exact target that touches a field deletes
+    // the whole field. Such deletions keep the whole-block rewrite, whose
+    // planned text is exact for explicit occurrences too; every other span keeps
+    // its exact target and with it the chosen occurrence and its formatting.
+    const deletions = tracked ? [] : planned.filter((span) => span.replace.length === 0);
+    const fieldRanges = deletions.length > 0 ? await fieldResultRanges(doc, 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) {
+        // A span already equal to its replacement has nothing to write, and the
+        // engine refuses a no-op target, which would sink its sibling edits.
+        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',
-                // The planner honours caseSensitive, so the selector must match on the
-                // same terms. Without it a case-sensitive request can redline a
-                // differently cased occurrence and still verify, because verification
-                // only looks for the replacement text somewhere in the block.
-                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(doc, spanSteps, args.changeMode, pre.revision);
+        if (steps.length === 0) {
+            result = { noop: true };
         }
-        catch {
-            result = null; // select lane unavailable (e.g. case mismatch) — fall back
+        else {
+            // The engine resolves these offsets against its own paragraph text. Check
+            // that each one still covers the text matched in the snapshot, so a
+            // projection mismatch never rewrites other text.
+            const preview = await previewMutations(doc, steps, args.changeMode, pre.revision);
+            const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord) : [];
+            const aligned = preview.valid === true &&
+                steps.every((step, index) => {
+                    const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
+                    const resolved = Array.isArray(resolutions) && isRecord(resolutions[0]) ? resolutions[0].text : undefined;
+                    const span = targetedSpans[index];
+                    return resolved === block.text.slice(span.start, span.end);
+                });
+            if (aligned) {
+                result = await executeMutations(doc, 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) {
@@ -4406,12 +4520,34 @@ async function runScopedReplaceUnchecked(doc, args) {
         ];
         result = await executeMutations(doc, steps, args.changeMode, pre.revision);
     }
-    const post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
-    const postBlock = findTextTarget(post, nodeId);
-    // In tracked mode the deleted text is still present in the block, so only
-    // require the inserted text to be visible.
+    let post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    let postBlock = findTextTarget(post, nodeId);
+    // Exact-target edits must leave exactly the planned visible text. If the
+    // engine changed more than the requested spans, undo the edit, which is one
+    // atomic history step. Only do so while the document is still at the
+    // revision this plan produced, so the undo cannot reach any other change.
+    let rolledBack = false;
+    const appliedRevision = isRecord(result) && isRecord(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 = maybeMethod(doc, ['history', 'undo']);
+        if (undoFn) {
+            await undoFn({});
+            post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+            postBlock = findTextTarget(post, nodeId);
+            rolledBack = postBlock?.text === block.text;
+        }
+    }
+    // Block text is the visible (final) text. Exact-offset edits must produce
+    // exactly the planned text; tracked edits that fell back to a whole-block
+    // rewrite only need each inserted text to be visible.
     const passed = postBlock != null &&
-        (tracked
+        !rolledBack &&
+        (tracked && !hasExplicitOccurrence && !wroteExactTargets
             ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace))
             : postBlock.text === expected);
     // Partially-applied requests must NOT read as success: a model that asked
@@ -4427,6 +4563,16 @@ async function runScopedReplaceUnchecked(doc, args) {
                 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 },
@@ -6212,12 +6358,21 @@ async function dispatchSuperdocPerformAction(doc, 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) && !isRecord(args.selector)) {
+                throw new SuperDocCliError('replace_text: explicit occurrence requires a selector resolving to one block', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
             const changeMode = parseReplaceTextChangeMode(args.changeMode);
             // Selector-scoped replaces take the span-targeted path: per-find
             // text.rewrite spans inside the one selected block, so tabs/breaks/
             // images outside the spans survive and the receipt reports per-edit
             // applied/skipped truth.
-            const scoped = parseScopedReplaceArgs(args, changeMode);
+            const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision);
             if (scoped) {
                 return runScopedReplace(doc, scoped);
             }
@@ -6230,6 +6385,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 edits,
                 selector,
                 caseSensitive: args.caseSensitive === true,
+                expectedRevision,
                 changeMode,
             });
         }
@@ -6911,7 +7067,12 @@ function parseEdits(value) {
         const replace = asString(entry.replace) ?? '';
         if (!find)
             return undefined;
-        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;
 }