@superdoc/sdk 2.12.1-next.1 → 2.13.0-next.10

package/dist/agent/actions.cjs

@@ -65,7 +65,7 @@ const ACTION_HINTS = {
     delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:"tracked" makes the table insertion itself a tracked change',
-    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text; the block's intra-paragraph run pattern is preserved best-effort over the unchanged prefix/suffix. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
+    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text using the document API's formatting preservation. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
     fill_placeholders: 'values[] and/or fields[{label?,value}], changeMode?',
     move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
     comment_paragraphs: 'commentText, scope?: all|body, excludeBlockQuotes?',
@@ -1133,7 +1133,7 @@ async function runInsertHeading(doc, args) {
         return failedReceipt('insert_heading', err, pre);
     }
 }
-async function runReplaceText(doc, args) {
+async function runReplaceTextUnchecked(doc, args) {
     const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
     const requiresBlockSnapshot = args.selector != null;
     const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
@@ -1149,11 +1149,6 @@ async function runReplaceText(doc, args) {
         let skippedEdits = [];
         let steps;
         let applyExpectedRevision;
-        // Blocks whose text this call rewrites, with their pre-mutation run layout:
-        // the engine replace lane renders the replaced range as uniform runs, so a
-        // whole-paragraph find/replace flattens intra-paragraph formatting (bold
-        // lead-ins). Restore it positionally after the mutation.
-        const preserveTargets = [];
         if (args.selector) {
             const target = selectorToBlockTarget(args.selector, pre);
             if (!target) {
@@ -1192,13 +1187,6 @@ async function runReplaceText(doc, args) {
             ];
             applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
-            preserveTargets.push({
-                nodeId: target.nodeId,
-                nodeType: target.nodeType ?? 'paragraph',
-                oldText: target.text,
-                newText: rewrittenText,
-                runs: await captureBlockRuns(doc, target.nodeId, target.text),
-            });
         }
         else {
             let candidates = args.edits.map((edit, editIndex) => ({
@@ -1256,12 +1244,6 @@ async function runReplaceText(doc, args) {
             steps = candidates.map((candidate) => candidate.step);
         }
         const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
-        const preserved = [];
-        for (const entry of preserveTargets) {
-            const restored = await preserveRunPatternAfterRewrite(doc, entry.nodeId, entry.oldText, entry.runs, entry.newText);
-            if (restored)
-                preserved.push({ nodeId: entry.nodeId, ...restored });
-        }
         if (args.selector && selectedTargets[0]) {
             const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
             const blockId = selectedTargets[0].matched[0];
@@ -1290,10 +1272,7 @@ async function runReplaceText(doc, args) {
                 preSnapshot: { revision: pre.revision, counts: pre.counts },
                 postSnapshot: { revision: post.revision, counts: post.counts },
                 selectedTargets,
-                executedOperations: [
-                    { operationId: 'doc.mutations.apply', result },
-                    ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
-                ],
+                executedOperations: [{ operationId: 'doc.mutations.apply', result }],
                 verification,
             };
         }
@@ -1317,7 +1296,6 @@ async function runReplaceText(doc, args) {
                     ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
                     result,
                 },
-                ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
             ],
             verification,
         };
@@ -1326,6 +1304,13 @@ async function runReplaceText(doc, args) {
         return failedReceipt('replace_text', err, pre);
     }
 }
+async function runReplaceText(doc, args) {
+    const changeMode = args.changeMode ?? 'direct';
+    return {
+        ...(await runReplaceTextUnchecked(doc, { ...args, changeMode })),
+        changeMode,
+    };
+}
 async function runDeleteText(doc, args) {
     const caseSensitive = args.caseSensitive === true;
     // Scoped form: delete finds within ONE block (mirrors replace_text's selector
@@ -2583,7 +2568,6 @@ async function runRewriteBlock(doc, args) {
             throw new Error('selector did not resolve to a body block');
         context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
         const text = normalizeTitleLikeRewriteText(target.text, args.text);
-        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
         await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
@@ -2592,7 +2576,6 @@ async function runRewriteBlock(doc, args) {
                 args: { replacement: { text }, style: preserveRewriteStyle() },
             },
         ], args.changeMode, pre.revision);
-        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
         const post = await context.finish();
         const rewritten = await post.block(target.nodeId);
         const verification = [
@@ -2665,23 +2648,8 @@ async function captureBlockRuns(doc, nodeId, text) {
     }
 }
 /**
- * Re-apply a block's pre-rewrite run pattern after a whole-block text.rewrite.
- * The engine renders the rewritten block as a single uniform run, which both
- * drops intra-paragraph formatting AND can smear the first run's marks over
- * everything. Marks are restored positionally over the parts of the text the
- * rewrite did NOT change (the common prefix and suffix of old vs new text),
- * and the changed middle takes the marks of the run it continues from —
- * Word's "typing continues formatting" rule. Best-effort: never fails the
- * rewrite.
- */
-/**
- * Span-aware run-pattern restore for scoped replaces. The generic
- * preserveRunPatternAfterRewrite diffs prefix/suffix and treats everything
- * between the FIRST and LAST change as one modified middle — with two
- * separated replacements that flattens independently-styled runs between
- * them. Here the exact spans are known, so every untouched interval keeps its
- * original run formatting at the offset-mapped position, and each replacement
- * inherits the marks of the run it starts in.
+ * Restore scoped replacements from their known spans: each untouched interval
+ * keeps its run formatting, and replacements inherit the marks at their start.
  * `spans` are FULL-TEXT coordinates, ascending, non-overlapping.
  */
 async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
@@ -2774,74 +2742,6 @@ async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
         return { skipped: reasonOf(err) };
     }
 }
-async function preserveRunPatternAfterRewrite(doc, nodeId, oldText, oldRuns, newText) {
-    // Nothing to restore when the block was uniformly plain; a single STYLED run
-    // still needs restoring (whole-block replaces drop even uniform marks).
-    if (!oldRuns || oldRuns.length === 0)
-        return null;
-    if (!oldRuns.some((run) => Object.keys(inlineFromSnapshotRun(run, new Set())).length > 0))
-        return null;
-    const formatFn = maybeMethod(doc, ['format', 'apply']);
-    if (!formatFn)
-        return null;
-    // Boolean marks any old run carried: plain ranges must explicitly clear
-    // these, because the rewritten single run may have smeared them everywhere.
-    const normalize = new Set(RUN_BOOL_MARKS.filter((key) => oldRuns.some((run) => run[key])));
-    // query.match run offsets are relative to the trimmed text used to match.
-    const oldTrim = oldText.trim();
-    const newTrimStart = newText.length - newText.trimStart().length;
-    const newTrim = newText.trim();
-    let prefix = 0;
-    const maxCommon = Math.min(oldTrim.length, newTrim.length);
-    while (prefix < maxCommon && oldTrim[prefix] === newTrim[prefix])
-        prefix += 1;
-    let suffix = 0;
-    while (suffix < maxCommon - prefix && oldTrim[oldTrim.length - 1 - suffix] === newTrim[newTrim.length - 1 - suffix])
-        suffix += 1;
-    const delta = newTrim.length - oldTrim.length;
-    let applied = 0;
-    const applyRange = async (start, end, inline) => {
-        if (end <= start || Object.keys(inline).length === 0)
-            return;
-        // Always direct, even under tracked mode. This pass RESTORES the marks the
-        // rewrite flattened; it is not new authorial formatting, and the text
-        // revision already owns the span's accept/reject fate. Applying it tracked
-        // adds a second reviewable change per rewrite (SD-4309's conformance matrix
-        // counts one per action), and rejecting that change alone would strand the
-        // text in the flattened look the rewrite produced.
-        const changed = await applyInlineQuiet(formatFn, {
-            blockId: nodeId,
-            start: newTrimStart + start,
-            end: newTrimStart + end,
-            inline,
-        });
-        if (changed)
-            applied += 1;
-    };
-    try {
-        for (const run of oldRuns) {
-            const inline = inlineFromSnapshotRun(run, normalize);
-            // Portion of the run inside the unchanged prefix.
-            await applyRange(run.start, Math.min(run.end, prefix), inline);
-            // Portion inside the unchanged suffix, shifted by the length delta.
-            const sufStart = Math.max(run.start, oldTrim.length - suffix);
-            if (run.end > sufStart)
-                await applyRange(sufStart + delta, run.end + delta, inline);
-        }
-        // The CHANGED middle keeps whatever the engine smeared; give it the marks
-        // of the run the change continues from (the one containing the last
-        // unchanged prefix character).
-        const middleEnd = newTrim.length - suffix;
-        if (middleEnd > prefix) {
-            const anchorRun = oldRuns.find((run) => prefix > run.start && prefix <= run.end) ?? oldRuns[oldRuns.length - 1];
-            await applyRange(prefix, middleEnd, inlineFromSnapshotRun(anchorRun, normalize));
-        }
-        return applied > 0 ? { restoredRunRanges: applied } : null;
-    }
-    catch (err) {
-        return { skipped: reasonOf(err) };
-    }
-}
 const NAMED_COLORS = {
     black: '000000',
     blue: '0000FF',
@@ -4613,7 +4513,7 @@ function compactOpResult(result) {
         compact.stepCount = result.steps.length;
     return compact;
 }
-function parseScopedReplaceArgs(args) {
+function parseScopedReplaceArgs(args, changeMode) {
     if (args.action !== 'replace_text')
         return null;
     if (!isRecord(args.selector))
@@ -4630,7 +4530,7 @@ function parseScopedReplaceArgs(args) {
         edits,
         selector: args.selector,
         caseSensitive: args.caseSensitive === true,
-        changeMode: args.changeMode === 'tracked' ? 'tracked' : 'direct',
+        changeMode,
     };
 }
 async function runScopedReplaceUnchecked(doc, args) {
@@ -4726,9 +4626,8 @@ async function runScopedReplaceUnchecked(doc, args) {
             },
             args: { replacement: { text: span.replace } },
         }));
-        // Select rewrites flatten the block's runs, so the tracked lane needs the
-        // same restoration the whole-block lane below performs. The preserve pass
-        // applies directly, so restoring marks adds no second reviewable change.
+        // Restore the known edit spans directly so the formatting pass adds no
+        // separate tracked change.
         const trackedPreRuns = await captureBlockRuns(doc, nodeId, block.text);
         try {
             result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
@@ -4796,11 +4695,15 @@ async function runScopedReplaceUnchecked(doc, args) {
     };
 }
 async function runScopedReplace(doc, args) {
+    const changeMode = args.changeMode ?? 'direct';
     try {
-        return await runScopedReplaceUnchecked(doc, args);
+        return {
+            ...(await runScopedReplaceUnchecked(doc, { ...args, changeMode })),
+            changeMode,
+        };
     }
     catch (error) {
-        return failedReceipt('replace_text', error);
+        return { ...failedReceipt('replace_text', error), changeMode };
     }
 }
 /**
@@ -6526,11 +6429,12 @@ async function dispatchSuperdocPerformAction(doc, args) {
                     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);
+            const scoped = parseScopedReplaceArgs(args, changeMode);
             if (scoped) {
                 return runScopedReplace(doc, scoped);
             }
@@ -6543,7 +6447,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 edits,
                 selector,
                 caseSensitive: args.caseSensitive === true,
-                changeMode: parseChangeMode(args.changeMode),
+                changeMode,
             });
         }
         case 'delete_text': {
@@ -7171,6 +7075,17 @@ function parseChangeMode(value) {
         return value;
     return undefined;
 }
+function parseReplaceTextChangeMode(value) {
+    if (value === undefined)
+        return 'direct';
+    const changeMode = parseChangeMode(value);
+    if (changeMode)
+        return changeMode;
+    throw new errors.SuperDocCliError('replace_text: "changeMode" must be "direct" or "tracked"', {
+        code: 'INVALID_ARGUMENT',
+        details: { changeMode: value },
+    });
+}
 function parseTrackedChangeKind(value) {
     if (value === 'insert' || value === 'delete' || value === 'replacement' || value === 'format')
         return value;

package/dist/agent/actions.js

@@ -62,7 +62,7 @@ export const ACTION_HINTS = {
     delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:"tracked" makes the table insertion itself a tracked change',
-    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text; the block's intra-paragraph run pattern is preserved best-effort over the unchanged prefix/suffix. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
+    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text using the document API's formatting preservation. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
     fill_placeholders: 'values[] and/or fields[{label?,value}], changeMode?',
     move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
     comment_paragraphs: 'commentText, scope?: all|body, excludeBlockQuotes?',
@@ -1130,7 +1130,7 @@ async function runInsertHeading(doc, args) {
         return failedReceipt('insert_heading', err, pre);
     }
 }
-async function runReplaceText(doc, args) {
+async function runReplaceTextUnchecked(doc, args) {
     const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
     const requiresBlockSnapshot = args.selector != null;
     const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
@@ -1146,11 +1146,6 @@ async function runReplaceText(doc, args) {
         let skippedEdits = [];
         let steps;
         let applyExpectedRevision;
-        // Blocks whose text this call rewrites, with their pre-mutation run layout:
-        // the engine replace lane renders the replaced range as uniform runs, so a
-        // whole-paragraph find/replace flattens intra-paragraph formatting (bold
-        // lead-ins). Restore it positionally after the mutation.
-        const preserveTargets = [];
         if (args.selector) {
             const target = selectorToBlockTarget(args.selector, pre);
             if (!target) {
@@ -1189,13 +1184,6 @@ async function runReplaceText(doc, args) {
             ];
             applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
-            preserveTargets.push({
-                nodeId: target.nodeId,
-                nodeType: target.nodeType ?? 'paragraph',
-                oldText: target.text,
-                newText: rewrittenText,
-                runs: await captureBlockRuns(doc, target.nodeId, target.text),
-            });
         }
         else {
             let candidates = args.edits.map((edit, editIndex) => ({
@@ -1253,12 +1241,6 @@ async function runReplaceText(doc, args) {
             steps = candidates.map((candidate) => candidate.step);
         }
         const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
-        const preserved = [];
-        for (const entry of preserveTargets) {
-            const restored = await preserveRunPatternAfterRewrite(doc, entry.nodeId, entry.oldText, entry.runs, entry.newText);
-            if (restored)
-                preserved.push({ nodeId: entry.nodeId, ...restored });
-        }
         if (args.selector && selectedTargets[0]) {
             const post = await buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
             const blockId = selectedTargets[0].matched[0];
@@ -1287,10 +1269,7 @@ async function runReplaceText(doc, args) {
                 preSnapshot: { revision: pre.revision, counts: pre.counts },
                 postSnapshot: { revision: post.revision, counts: post.counts },
                 selectedTargets,
-                executedOperations: [
-                    { operationId: 'doc.mutations.apply', result },
-                    ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
-                ],
+                executedOperations: [{ operationId: 'doc.mutations.apply', result }],
                 verification,
             };
         }
@@ -1314,7 +1293,6 @@ async function runReplaceText(doc, args) {
                     ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
                     result,
                 },
-                ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
             ],
             verification,
         };
@@ -1323,6 +1301,13 @@ async function runReplaceText(doc, args) {
         return failedReceipt('replace_text', err, pre);
     }
 }
+async function runReplaceText(doc, args) {
+    const changeMode = args.changeMode ?? 'direct';
+    return {
+        ...(await runReplaceTextUnchecked(doc, { ...args, changeMode })),
+        changeMode,
+    };
+}
 async function runDeleteText(doc, args) {
     const caseSensitive = args.caseSensitive === true;
     // Scoped form: delete finds within ONE block (mirrors replace_text's selector
@@ -2580,7 +2565,6 @@ async function runRewriteBlock(doc, args) {
             throw new Error('selector did not resolve to a body block');
         context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
         const text = normalizeTitleLikeRewriteText(target.text, args.text);
-        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
         await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
@@ -2589,7 +2573,6 @@ async function runRewriteBlock(doc, args) {
                 args: { replacement: { text }, style: preserveRewriteStyle() },
             },
         ], args.changeMode, pre.revision);
-        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
         const post = await context.finish();
         const rewritten = await post.block(target.nodeId);
         const verification = [
@@ -2662,23 +2645,8 @@ async function captureBlockRuns(doc, nodeId, text) {
     }
 }
 /**
- * Re-apply a block's pre-rewrite run pattern after a whole-block text.rewrite.
- * The engine renders the rewritten block as a single uniform run, which both
- * drops intra-paragraph formatting AND can smear the first run's marks over
- * everything. Marks are restored positionally over the parts of the text the
- * rewrite did NOT change (the common prefix and suffix of old vs new text),
- * and the changed middle takes the marks of the run it continues from —
- * Word's "typing continues formatting" rule. Best-effort: never fails the
- * rewrite.
- */
-/**
- * Span-aware run-pattern restore for scoped replaces. The generic
- * preserveRunPatternAfterRewrite diffs prefix/suffix and treats everything
- * between the FIRST and LAST change as one modified middle — with two
- * separated replacements that flattens independently-styled runs between
- * them. Here the exact spans are known, so every untouched interval keeps its
- * original run formatting at the offset-mapped position, and each replacement
- * inherits the marks of the run it starts in.
+ * Restore scoped replacements from their known spans: each untouched interval
+ * keeps its run formatting, and replacements inherit the marks at their start.
  * `spans` are FULL-TEXT coordinates, ascending, non-overlapping.
  */
 async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
@@ -2771,74 +2739,6 @@ async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
         return { skipped: reasonOf(err) };
     }
 }
-async function preserveRunPatternAfterRewrite(doc, nodeId, oldText, oldRuns, newText) {
-    // Nothing to restore when the block was uniformly plain; a single STYLED run
-    // still needs restoring (whole-block replaces drop even uniform marks).
-    if (!oldRuns || oldRuns.length === 0)
-        return null;
-    if (!oldRuns.some((run) => Object.keys(inlineFromSnapshotRun(run, new Set())).length > 0))
-        return null;
-    const formatFn = maybeMethod(doc, ['format', 'apply']);
-    if (!formatFn)
-        return null;
-    // Boolean marks any old run carried: plain ranges must explicitly clear
-    // these, because the rewritten single run may have smeared them everywhere.
-    const normalize = new Set(RUN_BOOL_MARKS.filter((key) => oldRuns.some((run) => run[key])));
-    // query.match run offsets are relative to the trimmed text used to match.
-    const oldTrim = oldText.trim();
-    const newTrimStart = newText.length - newText.trimStart().length;
-    const newTrim = newText.trim();
-    let prefix = 0;
-    const maxCommon = Math.min(oldTrim.length, newTrim.length);
-    while (prefix < maxCommon && oldTrim[prefix] === newTrim[prefix])
-        prefix += 1;
-    let suffix = 0;
-    while (suffix < maxCommon - prefix && oldTrim[oldTrim.length - 1 - suffix] === newTrim[newTrim.length - 1 - suffix])
-        suffix += 1;
-    const delta = newTrim.length - oldTrim.length;
-    let applied = 0;
-    const applyRange = async (start, end, inline) => {
-        if (end <= start || Object.keys(inline).length === 0)
-            return;
-        // Always direct, even under tracked mode. This pass RESTORES the marks the
-        // rewrite flattened; it is not new authorial formatting, and the text
-        // revision already owns the span's accept/reject fate. Applying it tracked
-        // adds a second reviewable change per rewrite (SD-4309's conformance matrix
-        // counts one per action), and rejecting that change alone would strand the
-        // text in the flattened look the rewrite produced.
-        const changed = await applyInlineQuiet(formatFn, {
-            blockId: nodeId,
-            start: newTrimStart + start,
-            end: newTrimStart + end,
-            inline,
-        });
-        if (changed)
-            applied += 1;
-    };
-    try {
-        for (const run of oldRuns) {
-            const inline = inlineFromSnapshotRun(run, normalize);
-            // Portion of the run inside the unchanged prefix.
-            await applyRange(run.start, Math.min(run.end, prefix), inline);
-            // Portion inside the unchanged suffix, shifted by the length delta.
-            const sufStart = Math.max(run.start, oldTrim.length - suffix);
-            if (run.end > sufStart)
-                await applyRange(sufStart + delta, run.end + delta, inline);
-        }
-        // The CHANGED middle keeps whatever the engine smeared; give it the marks
-        // of the run the change continues from (the one containing the last
-        // unchanged prefix character).
-        const middleEnd = newTrim.length - suffix;
-        if (middleEnd > prefix) {
-            const anchorRun = oldRuns.find((run) => prefix > run.start && prefix <= run.end) ?? oldRuns[oldRuns.length - 1];
-            await applyRange(prefix, middleEnd, inlineFromSnapshotRun(anchorRun, normalize));
-        }
-        return applied > 0 ? { restoredRunRanges: applied } : null;
-    }
-    catch (err) {
-        return { skipped: reasonOf(err) };
-    }
-}
 const NAMED_COLORS = {
     black: '000000',
     blue: '0000FF',
@@ -4610,7 +4510,7 @@ function compactOpResult(result) {
         compact.stepCount = result.steps.length;
     return compact;
 }
-function parseScopedReplaceArgs(args) {
+function parseScopedReplaceArgs(args, changeMode) {
     if (args.action !== 'replace_text')
         return null;
     if (!isRecord(args.selector))
@@ -4627,7 +4527,7 @@ function parseScopedReplaceArgs(args) {
         edits,
         selector: args.selector,
         caseSensitive: args.caseSensitive === true,
-        changeMode: args.changeMode === 'tracked' ? 'tracked' : 'direct',
+        changeMode,
     };
 }
 async function runScopedReplaceUnchecked(doc, args) {
@@ -4723,9 +4623,8 @@ async function runScopedReplaceUnchecked(doc, args) {
             },
             args: { replacement: { text: span.replace } },
         }));
-        // Select rewrites flatten the block's runs, so the tracked lane needs the
-        // same restoration the whole-block lane below performs. The preserve pass
-        // applies directly, so restoring marks adds no second reviewable change.
+        // Restore the known edit spans directly so the formatting pass adds no
+        // separate tracked change.
         const trackedPreRuns = await captureBlockRuns(doc, nodeId, block.text);
         try {
             result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
@@ -4793,11 +4692,15 @@ async function runScopedReplaceUnchecked(doc, args) {
     };
 }
 async function runScopedReplace(doc, args) {
+    const changeMode = args.changeMode ?? 'direct';
     try {
-        return await runScopedReplaceUnchecked(doc, args);
+        return {
+            ...(await runScopedReplaceUnchecked(doc, { ...args, changeMode })),
+            changeMode,
+        };
     }
     catch (error) {
-        return failedReceipt('replace_text', error);
+        return { ...failedReceipt('replace_text', error), changeMode };
     }
 }
 /**
@@ -6523,11 +6426,12 @@ async function dispatchSuperdocPerformAction(doc, args) {
                     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);
+            const scoped = parseScopedReplaceArgs(args, changeMode);
             if (scoped) {
                 return runScopedReplace(doc, scoped);
             }
@@ -6540,7 +6444,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 edits,
                 selector,
                 caseSensitive: args.caseSensitive === true,
-                changeMode: parseChangeMode(args.changeMode),
+                changeMode,
             });
         }
         case 'delete_text': {
@@ -7170,6 +7074,17 @@ function parseChangeMode(value) {
         return value;
     return undefined;
 }
+function parseReplaceTextChangeMode(value) {
+    if (value === undefined)
+        return 'direct';
+    const changeMode = parseChangeMode(value);
+    if (changeMode)
+        return changeMode;
+    throw new SuperDocCliError('replace_text: "changeMode" must be "direct" or "tracked"', {
+        code: 'INVALID_ARGUMENT',
+        details: { changeMode: value },
+    });
+}
 function parseTrackedChangeKind(value) {
     if (value === 'insert' || value === 'delete' || value === 'replacement' || value === 'format')
         return value;