@superdoc/sdk 2.22.0-next.12 → 2.22.0-next.13

package/dist/agent/action-descriptors.json

@@ -14,10 +14,10 @@
         "operations": ["create.heading"]
     },
     "replace_text": {
-        "hint": "edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode? — for EDITING existing wording only; the replaced span is rewritten as PLAIN text (intra-span bold/italic is dropped), so keep find/replace spans MINIMAL (the words that change, not the whole paragraph) and NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
+        "hint": "edits[{find,replace,occurrence?}], optional selector to scope replacements to one inspected block, caseSensitive?, expectedRevision?, changeMode? — for EDITING existing wording only; keep find/replace spans MINIMAL (the words that change, not the whole paragraph). When the find appears more than once in the selected block and only one should change, set that edit's occurrence (1-based match number within the block; requires selector; this is not selector.occurrence, which picks a block). NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
         "group": "Text/structure actions",
         "groupOrder": 2,
-        "args": ["edits", "selector", "caseSensitive", "changeMode"],
+        "args": ["edits", "selector", "caseSensitive", "expectedRevision", "changeMode"],
         "operations": ["replace"]
     },
     "delete_text": {

package/dist/agent/actions.cjs

@@ -601,12 +601,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']);
@@ -975,6 +973,7 @@ async function runReplaceTextUnchecked(doc, args) {
         ? await docSnapshot.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);
@@ -983,7 +982,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) {
@@ -3437,18 +3436,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 docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
@@ -4279,29 +4288,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 errors.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 docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
     const matched = docSnapshot.resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -4321,13 +4365,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 errors.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);
@@ -4355,45 +4410,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 errors.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 errors.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) {
@@ -4409,12 +4501,34 @@ async function runScopedReplaceUnchecked(doc, args) {
         ];
         result = await executeMutations(doc, steps, args.changeMode, pre.revision);
     }
-    const post = await docSnapshot.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 docSnapshot.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 docSnapshot.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
@@ -4430,6 +4544,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 },
@@ -6215,12 +6339,21 @@ async function dispatchSuperdocPerformAction(doc, args) {
                     code: 'INVALID_ARGUMENT',
                 });
             }
+            const expectedRevision = args.expectedRevision;
+            if (expectedRevision !== undefined && (typeof expectedRevision !== 'string' || expectedRevision.length === 0)) {
+                throw new errors.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 errors.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);
             }
@@ -6233,6 +6366,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 edits,
                 selector,
                 caseSensitive: args.caseSensitive === true,
+                expectedRevision,
                 changeMode,
             });
         }
@@ -6912,7 +7046,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 errors.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;
 }

package/dist/agent/actions.d.ts

@@ -63,9 +63,12 @@ export type ReplaceTextArgs = {
     edits: ReadonlyArray<{
         find: string;
         replace: string;
+        occurrence?: number;
     }>;
     selector?: AgentSelector;
     caseSensitive?: boolean;
+    /** Opaque observation token from the same live document handle; refuses stale edits. */
+    expectedRevision?: string;
     changeMode?: AgentChangeMode;
 };
 export type DeleteTextArgs = {