@superdoc/sdk 2.10.0-next.1 → 2.10.0-next.3

package/dist/agent/actions.cjs

@@ -775,13 +775,28 @@ async function executeCreateHeading(doc, text, level, placement, changeMode) {
     // Dual dialect — see executeCreateParagraph.
     return fn(params, changeMode ? { changeMode } : undefined);
 }
-async function executeMutations(doc, steps, changeMode) {
+async function executeMutations(doc, steps, changeMode, expectedRevision) {
     const fn = maybeMethod(doc, ['mutations', 'apply']);
     if (!fn)
         throw new errors.SuperDocCliError('doc.mutations.apply is not available on the document handle.', {
             code: 'TOOL_DISPATCH_NOT_FOUND',
         });
-    return fn({ atomic: true, changeMode: changeMode ?? 'direct', steps });
+    return fn({
+        atomic: true,
+        changeMode: changeMode ?? 'direct',
+        steps,
+        ...(expectedRevision ? { expectedRevision } : {}),
+    });
+}
+async function previewMutations(doc, steps, changeMode, expectedRevision) {
+    const fn = maybeMethod(doc, ['mutations', 'preview']);
+    if (!fn) {
+        throw new errors.SuperDocCliError('doc.mutations.preview is not available on the document handle.', {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+        });
+    }
+    const result = await fn({ atomic: true, changeMode: changeMode ?? 'direct', expectedRevision, steps });
+    return isRecord(result) ? result : {};
 }
 async function executeCreateTable(doc, args, placement) {
     const fn = maybeMethod(doc, ['create', 'table']);
@@ -1136,7 +1151,7 @@ async function runInsertHeading(doc, args) {
 }
 async function runReplaceText(doc, args) {
     const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
-    const requiresBlockSnapshot = args.selector != null || args.edits.length > 1;
+    const requiresBlockSnapshot = args.selector != null;
     const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
     const pre = requiresBlockSnapshot
         ? await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
@@ -1149,6 +1164,7 @@ async function runReplaceText(doc, args) {
         const selectedTargets = [];
         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
@@ -1200,98 +1216,9 @@ async function runReplaceText(doc, args) {
             });
         }
         else {
-            const matchingEdits = args.edits.length === 1
-                ? args.edits
-                : args.edits.filter((edit) => pre.blocks.some((block) => textIncludes(block.text, edit.find, caseSensitive)));
-            skippedEdits = args.edits.filter((edit) => !matchingEdits.includes(edit));
-            if (matchingEdits.length === 0) {
-                return {
-                    status: 'failed',
-                    intent: 'replace_text',
-                    preSnapshot: { revision: pre.revision, counts: pre.counts },
-                    selectedTargets: [],
-                    executedOperations: [],
-                    verification: [],
-                    errors: [
-                        {
-                            code: 'ACTION_FAILED',
-                            message: 'none of the requested text replacements matched the current document',
-                        },
-                    ],
-                };
-            }
-            // Rewrite affected BODY blocks with block-targeted rewrites. The select
-            // (matched-range) rewrite lane flattens the WHOLE paragraph's runs in
-            // collaborative sessions and leaves format.apply inert on the block
-            // afterwards, so per-block rewrites + the preserve pass below are the
-            // only path that keeps intra-paragraph formatting alive. Bounded; edits
-            // that touch no scanned body block (e.g. header/footer text) fall back
-            // to a select-rewrite step.
-            // Tracked mode keeps the matched-range lane. A block rewrite asks the
-            // engine to delete and re-insert the WHOLE paragraph, so a reviewer sees
-            // the entire block struck and re-added instead of the words that changed,
-            // and each block contributes its own replacement/deletion pair. The
-            // per-block lane exists to keep intra-paragraph formatting alive, which
-            // is a direct-mode concern; under tracked mode the revision itself is the
-            // reviewable unit and must stay scoped to the edit.
-            const scanBlocks = args.changeMode === 'tracked'
-                ? []
-                : pre.blocks.length > 0
-                    ? pre.blocks
-                    : (await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] })).blocks;
-            // An edit counts as covered only when EVERY block holding it got a
-            // rewrite target. The per-block lane is bounded (run capture costs a read
-            // each), so a find present in more blocks than the cap must fall through
-            // to the select lane below, which carries `require: 'all'`. Marking such
-            // an edit covered after its first match would replace only the first
-            // PRESERVE_TARGET_CAP blocks and still report success.
-            const blocksHoldingEdit = matchingEdits.map((edit) => scanBlocks.filter((block) => block.nodeId && block.text && textIncludes(block.text, edit.find, caseSensitive))
-                .length);
-            const blocksCoveredForEdit = Array.from({ length: matchingEdits.length }, () => 0);
-            for (const block of scanBlocks) {
-                if (preserveTargets.length >= PRESERVE_TARGET_CAP)
-                    break;
-                if (!block.nodeId || !block.text)
-                    continue;
-                let newText = block.text;
-                const touched = [];
-                matchingEdits.forEach((edit, editIndex) => {
-                    if (textIncludes(newText, edit.find, caseSensitive)) {
-                        newText = replaceAllText(newText, edit.find, edit.replace, caseSensitive);
-                        touched.push(editIndex);
-                    }
-                });
-                if (newText === block.text)
-                    continue;
-                preserveTargets.push({
-                    nodeId: block.nodeId,
-                    nodeType: block.nodeType ?? 'paragraph',
-                    oldText: block.text,
-                    newText,
-                    runs: await captureBlockRuns(doc, block.nodeId, block.text),
-                });
-                for (const editIndex of touched)
-                    blocksCoveredForEdit[editIndex] += 1;
-            }
-            const coveredEdits = new Set(matchingEdits
-                .map((_edit, editIndex) => editIndex)
-                .filter((editIndex) => blocksHoldingEdit[editIndex] > 0 && blocksCoveredForEdit[editIndex] >= blocksHoldingEdit[editIndex]));
-            steps = [
-                ...preserveTargets.map((entry, index) => ({
-                    id: `replace-block-${index + 1}`,
-                    op: 'text.rewrite',
-                    where: { by: 'block', nodeType: entry.nodeType, nodeId: entry.nodeId },
-                    args: {
-                        replacement: { text: entry.newText },
-                        style: preserveRewriteStyle(),
-                    },
-                })),
-                // Edits that touched no scanned body block (header/footer text, or a
-                // doc larger than the scan window) keep the original select-rewrite.
-                ...matchingEdits
-                    .map((edit, editIndex) => ({ edit, editIndex }))
-                    .filter(({ editIndex }) => !coveredEdits.has(editIndex))
-                    .map(({ edit, editIndex }) => ({
+            let candidates = args.edits.map((edit, editIndex) => ({
+                edit,
+                step: {
                     id: `replace-${editIndex + 1}`,
                     op: 'text.rewrite',
                     where: {
@@ -1308,10 +1235,42 @@ async function runReplaceText(doc, args) {
                         replacement: { text: edit.replace },
                         style: preserveRewriteStyle(),
                     },
-                })),
-            ];
+                },
+            }));
+            if (candidates.length > 1) {
+                applyExpectedRevision = pre.revision;
+                while (candidates.length > 0) {
+                    const preview = await previewMutations(doc, candidates.map((candidate) => candidate.step), args.changeMode, pre.revision);
+                    if (preview.valid === true)
+                        break;
+                    const failures = Array.isArray(preview.failures) ? preview.failures.filter(isRecord) : [];
+                    const absent = failures.find((failure) => failure.code === 'MATCH_NOT_FOUND' && typeof failure.stepId === 'string');
+                    if (!absent) {
+                        throw new Error(typeof failures[0]?.message === 'string' ? failures[0].message : 'replacement plan could not be prepared');
+                    }
+                    const absentIndex = candidates.findIndex((candidate) => candidate.step.id === absent.stepId);
+                    if (absentIndex < 0)
+                        throw new Error('replacement preview returned an unknown step id');
+                    skippedEdits.push({ find: candidates[absentIndex].edit.find });
+                    candidates = candidates.filter((_candidate, index) => index !== absentIndex);
+                }
+            }
+            if (candidates.length === 0) {
+                return {
+                    status: 'failed',
+                    intent: 'replace_text',
+                    preSnapshot: { revision: pre.revision, counts: pre.counts },
+                    selectedTargets: [],
+                    executedOperations: [],
+                    verification: [],
+                    errors: [
+                        { code: 'ACTION_FAILED', message: 'none of the requested text replacements matched the current document' },
+                    ],
+                };
+            }
+            steps = candidates.map((candidate) => candidate.step);
         }
-        const result = await executeMutations(doc, steps, args.changeMode);
+        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);
@@ -4839,12 +4798,6 @@ function paragraphMarkRunPropsOf(payload) {
  * Spaced dashes are listed separately from bare ones because the label run
  * usually stops BEFORE the space ("JavaScript / TypeScript" + " — SuperDoc…").
  */
-/**
- * How many blocks the per-block replace lane will capture runs for. Each target
- * costs a `query.match` read, so the lane is bounded; edits reaching past it
- * fall through to the select lane rather than being silently truncated.
- */
-const PRESERVE_TARGET_CAP = 20;
 const LEAD_IN_DELIMITERS = [':', ' — ', ' – ', ' - ', '—', '–'];
 /** A lead-in is a LABEL, not a sentence — longer spans are prose, not a pattern. */
 const LEAD_IN_MAX_CHARS = 90;

package/dist/agent/actions.js

@@ -772,13 +772,28 @@ async function executeCreateHeading(doc, text, level, placement, changeMode) {
     // Dual dialect — see executeCreateParagraph.
     return fn(params, changeMode ? { changeMode } : undefined);
 }
-async function executeMutations(doc, steps, changeMode) {
+async function executeMutations(doc, steps, changeMode, expectedRevision) {
     const fn = maybeMethod(doc, ['mutations', 'apply']);
     if (!fn)
         throw new SuperDocCliError('doc.mutations.apply is not available on the document handle.', {
             code: 'TOOL_DISPATCH_NOT_FOUND',
         });
-    return fn({ atomic: true, changeMode: changeMode ?? 'direct', steps });
+    return fn({
+        atomic: true,
+        changeMode: changeMode ?? 'direct',
+        steps,
+        ...(expectedRevision ? { expectedRevision } : {}),
+    });
+}
+async function previewMutations(doc, steps, changeMode, expectedRevision) {
+    const fn = maybeMethod(doc, ['mutations', 'preview']);
+    if (!fn) {
+        throw new SuperDocCliError('doc.mutations.preview is not available on the document handle.', {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+        });
+    }
+    const result = await fn({ atomic: true, changeMode: changeMode ?? 'direct', expectedRevision, steps });
+    return isRecord(result) ? result : {};
 }
 async function executeCreateTable(doc, args, placement) {
     const fn = maybeMethod(doc, ['create', 'table']);
@@ -1133,7 +1148,7 @@ async function runInsertHeading(doc, args) {
 }
 async function runReplaceText(doc, args) {
     const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
-    const requiresBlockSnapshot = args.selector != null || args.edits.length > 1;
+    const requiresBlockSnapshot = args.selector != null;
     const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
     const pre = requiresBlockSnapshot
         ? await buildDocumentSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
@@ -1146,6 +1161,7 @@ async function runReplaceText(doc, args) {
         const selectedTargets = [];
         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
@@ -1197,98 +1213,9 @@ async function runReplaceText(doc, args) {
             });
         }
         else {
-            const matchingEdits = args.edits.length === 1
-                ? args.edits
-                : args.edits.filter((edit) => pre.blocks.some((block) => textIncludes(block.text, edit.find, caseSensitive)));
-            skippedEdits = args.edits.filter((edit) => !matchingEdits.includes(edit));
-            if (matchingEdits.length === 0) {
-                return {
-                    status: 'failed',
-                    intent: 'replace_text',
-                    preSnapshot: { revision: pre.revision, counts: pre.counts },
-                    selectedTargets: [],
-                    executedOperations: [],
-                    verification: [],
-                    errors: [
-                        {
-                            code: 'ACTION_FAILED',
-                            message: 'none of the requested text replacements matched the current document',
-                        },
-                    ],
-                };
-            }
-            // Rewrite affected BODY blocks with block-targeted rewrites. The select
-            // (matched-range) rewrite lane flattens the WHOLE paragraph's runs in
-            // collaborative sessions and leaves format.apply inert on the block
-            // afterwards, so per-block rewrites + the preserve pass below are the
-            // only path that keeps intra-paragraph formatting alive. Bounded; edits
-            // that touch no scanned body block (e.g. header/footer text) fall back
-            // to a select-rewrite step.
-            // Tracked mode keeps the matched-range lane. A block rewrite asks the
-            // engine to delete and re-insert the WHOLE paragraph, so a reviewer sees
-            // the entire block struck and re-added instead of the words that changed,
-            // and each block contributes its own replacement/deletion pair. The
-            // per-block lane exists to keep intra-paragraph formatting alive, which
-            // is a direct-mode concern; under tracked mode the revision itself is the
-            // reviewable unit and must stay scoped to the edit.
-            const scanBlocks = args.changeMode === 'tracked'
-                ? []
-                : pre.blocks.length > 0
-                    ? pre.blocks
-                    : (await buildDocumentSnapshot(doc, { includeDomains: ['blocks'] })).blocks;
-            // An edit counts as covered only when EVERY block holding it got a
-            // rewrite target. The per-block lane is bounded (run capture costs a read
-            // each), so a find present in more blocks than the cap must fall through
-            // to the select lane below, which carries `require: 'all'`. Marking such
-            // an edit covered after its first match would replace only the first
-            // PRESERVE_TARGET_CAP blocks and still report success.
-            const blocksHoldingEdit = matchingEdits.map((edit) => scanBlocks.filter((block) => block.nodeId && block.text && textIncludes(block.text, edit.find, caseSensitive))
-                .length);
-            const blocksCoveredForEdit = Array.from({ length: matchingEdits.length }, () => 0);
-            for (const block of scanBlocks) {
-                if (preserveTargets.length >= PRESERVE_TARGET_CAP)
-                    break;
-                if (!block.nodeId || !block.text)
-                    continue;
-                let newText = block.text;
-                const touched = [];
-                matchingEdits.forEach((edit, editIndex) => {
-                    if (textIncludes(newText, edit.find, caseSensitive)) {
-                        newText = replaceAllText(newText, edit.find, edit.replace, caseSensitive);
-                        touched.push(editIndex);
-                    }
-                });
-                if (newText === block.text)
-                    continue;
-                preserveTargets.push({
-                    nodeId: block.nodeId,
-                    nodeType: block.nodeType ?? 'paragraph',
-                    oldText: block.text,
-                    newText,
-                    runs: await captureBlockRuns(doc, block.nodeId, block.text),
-                });
-                for (const editIndex of touched)
-                    blocksCoveredForEdit[editIndex] += 1;
-            }
-            const coveredEdits = new Set(matchingEdits
-                .map((_edit, editIndex) => editIndex)
-                .filter((editIndex) => blocksHoldingEdit[editIndex] > 0 && blocksCoveredForEdit[editIndex] >= blocksHoldingEdit[editIndex]));
-            steps = [
-                ...preserveTargets.map((entry, index) => ({
-                    id: `replace-block-${index + 1}`,
-                    op: 'text.rewrite',
-                    where: { by: 'block', nodeType: entry.nodeType, nodeId: entry.nodeId },
-                    args: {
-                        replacement: { text: entry.newText },
-                        style: preserveRewriteStyle(),
-                    },
-                })),
-                // Edits that touched no scanned body block (header/footer text, or a
-                // doc larger than the scan window) keep the original select-rewrite.
-                ...matchingEdits
-                    .map((edit, editIndex) => ({ edit, editIndex }))
-                    .filter(({ editIndex }) => !coveredEdits.has(editIndex))
-                    .map(({ edit, editIndex }) => ({
+            let candidates = args.edits.map((edit, editIndex) => ({
+                edit,
+                step: {
                     id: `replace-${editIndex + 1}`,
                     op: 'text.rewrite',
                     where: {
@@ -1305,10 +1232,42 @@ async function runReplaceText(doc, args) {
                         replacement: { text: edit.replace },
                         style: preserveRewriteStyle(),
                     },
-                })),
-            ];
+                },
+            }));
+            if (candidates.length > 1) {
+                applyExpectedRevision = pre.revision;
+                while (candidates.length > 0) {
+                    const preview = await previewMutations(doc, candidates.map((candidate) => candidate.step), args.changeMode, pre.revision);
+                    if (preview.valid === true)
+                        break;
+                    const failures = Array.isArray(preview.failures) ? preview.failures.filter(isRecord) : [];
+                    const absent = failures.find((failure) => failure.code === 'MATCH_NOT_FOUND' && typeof failure.stepId === 'string');
+                    if (!absent) {
+                        throw new Error(typeof failures[0]?.message === 'string' ? failures[0].message : 'replacement plan could not be prepared');
+                    }
+                    const absentIndex = candidates.findIndex((candidate) => candidate.step.id === absent.stepId);
+                    if (absentIndex < 0)
+                        throw new Error('replacement preview returned an unknown step id');
+                    skippedEdits.push({ find: candidates[absentIndex].edit.find });
+                    candidates = candidates.filter((_candidate, index) => index !== absentIndex);
+                }
+            }
+            if (candidates.length === 0) {
+                return {
+                    status: 'failed',
+                    intent: 'replace_text',
+                    preSnapshot: { revision: pre.revision, counts: pre.counts },
+                    selectedTargets: [],
+                    executedOperations: [],
+                    verification: [],
+                    errors: [
+                        { code: 'ACTION_FAILED', message: 'none of the requested text replacements matched the current document' },
+                    ],
+                };
+            }
+            steps = candidates.map((candidate) => candidate.step);
         }
-        const result = await executeMutations(doc, steps, args.changeMode);
+        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);
@@ -4836,12 +4795,6 @@ function paragraphMarkRunPropsOf(payload) {
  * Spaced dashes are listed separately from bare ones because the label run
  * usually stops BEFORE the space ("JavaScript / TypeScript" + " — SuperDoc…").
  */
-/**
- * How many blocks the per-block replace lane will capture runs for. Each target
- * costs a `query.match` read, so the lane is bounded; edits reaching past it
- * fall through to the select lane rather than being silently truncated.
- */
-const PRESERVE_TARGET_CAP = 20;
 const LEAD_IN_DELIMITERS = [':', ' — ', ' – ', ' - ', '—', '–'];
 /** A lead-in is a LABEL, not a sentence — longer spans are prose, not a pattern. */
 const LEAD_IN_MAX_CHARS = 90;