open-agreements 0.3.1 → 0.5.0

package/dist/core/recipe/downloader.js

@@ -2,9 +2,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
-const CACHE_ROOT = join(homedir(), '.open-agreements', 'cache');
+// Lazy — must be a function so ESM import hoisting doesn't evaluate before
+// api/_shared.ts sets OPEN_AGREEMENTS_CACHE_ROOT for Vercel.
+function getCacheRoot() {
+    return process.env['OPEN_AGREEMENTS_CACHE_ROOT']
+        ?? join(homedir(), '.open-agreements', 'cache');
+}
 function getCachePath(recipeId) {
-    return join(CACHE_ROOT, recipeId, 'source.docx');
+    return join(getCacheRoot(), recipeId, 'source.docx');
 }
 function verifyHash(buf, expected) {
     const actual = createHash('sha256').update(buf).digest('hex');
@@ -49,7 +54,7 @@ export async function ensureSourceDocx(recipeId, metadata) {
         }
     }
     // Write to cache
-    const cacheDir = join(CACHE_ROOT, recipeId);
+    const cacheDir = join(getCacheRoot(), recipeId);
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(cachePath, buf);
     console.log(`Cached: ${cachePath}`);

package/dist/core/recipe/downloader.js.map

@@ -1 +1 @@
-{"version":3,"file":"downloader.js","sourceRoot":"","sources":["../../../src/core/recipe/downloader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"downloader.js","sourceRoot":"","sources":["../../../src/core/recipe/downloader.ts"],"names":[],"mappings":"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"}

package/dist/core/recipe/index.d.ts

@@ -7,7 +7,8 @@ export declare function runRecipe(options: RecipeRunOptions): Promise<RecipeRunR
 export { cleanDocument } from './cleaner.js';
 export type { CleanResult, CleanOptions } from './cleaner.js';
 export { patchDocument } from './patcher.js';
-export { verifyOutput, normalizeText, extractAllText } from './verifier.js';
+export type { PatchResult } from './patcher.js';
+export { verifyOutput, normalizeText, extractAllText, countFormattingAnomalies } from './verifier.js';
 export { ensureSourceDocx } from './downloader.js';
 export { checkRecipeSourceDrift, computeSourceStructureSignature } from './source-drift.js';
 export { enumerateTextParts, getGeneralTextPartNames } from './ooxml-parts.js';

package/dist/core/recipe/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/recipe/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8EnF;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC/E,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC/F,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/recipe/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqFnF;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACtG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC/E,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC/F,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/recipe/index.js

@@ -1,6 +1,7 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadRecipeMetadata, loadCleanConfig, loadNormalizeConfig } from '../metadata.js';
+import { loadSelectionsConfig } from '../selector.js';
 import { resolveRecipeDir } from '../../utils/paths.js';
 import { verifyOutput } from './verifier.js';
 import { ensureSourceDocx } from './downloader.js';
@@ -17,6 +18,11 @@ export async function runRecipe(options) {
     const metadata = loadRecipeMetadata(recipeDir);
     const cleanConfig = loadCleanConfig(recipeDir);
     const normalizeConfig = loadNormalizeConfig(recipeDir);
+    // Load selectionsConfig if selections.json exists (mirrors engine.ts template path)
+    const selectionsPath = join(recipeDir, 'selections.json');
+    const selectionsConfig = existsSync(selectionsPath)
+        ? loadSelectionsConfig(selectionsPath)
+        : undefined;
     // Resolve input: explicit path or auto-download
     const inputPath = options.inputPath ?? await ensureSourceDocx(recipeId, metadata);
     // Load replacements.json
@@ -53,14 +59,15 @@ export async function runRecipe(options) {
     if (computedOutPath && computedArtifact) {
         writeComputedArtifact(computedOutPath, computedArtifact);
     }
-    const shouldNormalizeBracketArtifacts = options.normalizeBracketArtifacts ?? recipeId === 'nvca-stock-purchase-agreement';
+    const shouldNormalizeBracketArtifacts = options.normalizeBracketArtifacts ?? normalizeConfig.paragraph_rules.length > 0;
     const result = await runFillPipeline({
         inputPath,
         outputPath,
         values: effectiveValues,
         fields: metadata.fields,
-        requiredFieldNames: metadata.required_fields,
+        priorityFieldNames: metadata.priority_fields,
         cleanPatch: { cleanConfig, replacements },
+        selectionsConfig,
         postProcess: shouldNormalizeBracketArtifacts
             ? async (outputDocPath) => {
                 await normalizeBracketArtifacts(outputDocPath, outputDocPath, {
@@ -83,7 +90,7 @@ export async function runRecipe(options) {
 }
 export { cleanDocument } from './cleaner.js';
 export { patchDocument } from './patcher.js';
-export { verifyOutput, normalizeText, extractAllText } from './verifier.js';
+export { verifyOutput, normalizeText, extractAllText, countFormattingAnomalies } from './verifier.js';
 export { ensureSourceDocx } from './downloader.js';
 export { checkRecipeSourceDrift, computeSourceStructureSignature } from './source-drift.js';
 export { enumerateTextParts, getGeneralTextPartNames } from './ooxml-parts.js';

package/dist/core/recipe/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/recipe/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/recipe/index.ts"],"names":[],"mappings":"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"}

package/dist/core/recipe/patcher.d.ts

@@ -1,15 +1,19 @@
 import type { Element } from '@xmldom/xmldom';
+export interface PatchResult {
+    outputPath: string;
+    zeroMatchKeys: string[];
+}
 /**
  * Patch a DOCX document by replacing bracketed placeholders with template tags.
  * Uses a char_map algorithm to handle cross-run replacements where Word splits
  * placeholder text across multiple XML run elements.
  *
- * Supports three key syntax types:
+ * Supports two key syntax types:
  * - Simple: "search text" → replaces all occurrences
- * - Context: "label > placeholder" → replaces placeholder only in matching table rows
- * - Nth: "text#N" → replaces only the Nth occurrence across the document
+ * - Context: "context > placeholder" → in tables, replaces placeholder in rows
+ *   where label matches; in paragraphs, replaces first placeholder after context
  *
- * Processing order: context keys first, nth keys second, simple keys last.
+ * Processing order: context keys first, simple keys last.
  * This ensures qualified rules claim their targets before simple rules sweep up the rest.
  */
 export interface PatchOptions {
@@ -18,7 +22,7 @@ export interface PatchOptions {
      *  overriding any inherited placeholder styling (e.g. gray). */
     replacementColor?: string;
 }
-export declare function patchDocument(inputPath: string, outputPath: string, replacements: Record<string, string>, options?: PatchOptions): Promise<string>;
+export declare function patchDocument(inputPath: string, outputPath: string, replacements: Record<string, string>, options?: PatchOptions): Promise<PatchResult>;
 /**
  * Get the text content of the first table cell (label cell) in the same row
  * as the paragraph. Returns null if the paragraph is not inside a table cell.

package/dist/core/recipe/patcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patcher.d.ts","sourceRoot":"","sources":["../../../src/core/recipe/patcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAY,OAAO,EAAQ,MAAM,gBAAgB,CAAC;AAwB9D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;oEAEgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,CA+HjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwB/D;AA0BD,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAO/C;AAuFD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAcvD"}
+{"version":3,"file":"patcher.d.ts","sourceRoot":"","sources":["../../../src/core/recipe/patcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAY,OAAO,EAAQ,MAAM,gBAAgB,CAAC;AA4B9D,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAcD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;oEAEgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,CAsItB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwB/D;AA0BD,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAO/C;AAuFD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAcvD"}

package/dist/core/recipe/patcher.js

@@ -1,9 +1,20 @@
 import AdmZip from 'adm-zip';
 import { writeFileSync } from 'node:fs';
 import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { replaceParagraphTextRange, getParagraphText, SafeDocxError, } from '@usejunior/docx-core';
 import { enumerateTextParts, getGeneralTextPartNames } from './ooxml-parts.js';
 import { parseReplacementKey } from './replacement-keys.js';
 const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+/**
+ * Normalize smart/typographic quotes to ASCII equivalents for matching.
+ * Uses the same canonical quote set as verifier's normalizeText().
+ * This is a 1-to-1 character mapping so charMap positions remain valid.
+ */
+function normalizeQuotes(text) {
+    return text
+        .replace(/[\u2018\u2019\u2039\u203A]/g, "'")
+        .replace(/[\u201C\u201D\u201A\u201E\u00AB\u00BB]/g, '"');
+}
 /** Maximum replacement iterations per key per paragraph to prevent infinite loops. */
 const MAX_REPLACEMENTS_PER_KEY = 200;
 /**
@@ -23,30 +34,48 @@ export async function patchDocument(inputPath, outputPath, replacements, options
     if (partNames.length === 0) {
         throw new Error('No OOXML text parts found in DOCX');
     }
-    // Parse and classify all keys
+    // Parse and classify all keys, normalizing smart quotes
     const parsedKeys = [];
     for (const [key, value] of Object.entries(replacements)) {
-        parsedKeys.push(parseReplacementKey(key, value));
+        const parsed = parseReplacementKey(key, value);
+        // Normalize smart quotes in search text and context for matching
+        if (parsed.type === 'context') {
+            parsed.searchText = normalizeQuotes(parsed.searchText);
+            parsed.context = normalizeQuotes(parsed.context);
+        }
+        else {
+            parsed.searchText = normalizeQuotes(parsed.searchText);
+        }
+        parsedKeys.push(parsed);
+    }
+    // Deduplicate keys that collide after quote normalization
+    const seenSearchKeys = new Map();
+    const deduplicatedKeys = [];
+    for (const pk of parsedKeys) {
+        const dedupKey = pk.type === 'context' ? `${pk.context} > ${pk.searchText}` : pk.searchText;
+        const existing = seenSearchKeys.get(dedupKey);
+        if (existing) {
+            if (existing.value !== pk.value) {
+                console.warn(`Patcher: quote-normalized key collision for "${dedupKey}" with different values`);
+            }
+            // Skip duplicate
+        }
+        else {
+            seenSearchKeys.set(dedupKey, pk);
+            deduplicatedKeys.push(pk);
+        }
     }
     // Separate by type and sort
-    const contextKeys = parsedKeys
+    const contextKeys = deduplicatedKeys
         .filter((k) => k.type === 'context')
         .sort((a, b) => b.searchText.length - a.searchText.length);
-    const nthKeys = parsedKeys
-        .filter((k) => k.type === 'nth')
-        .sort((a, b) => {
-        // Group by searchText, then by N ascending
-        if (a.searchText !== b.searchText)
-            return b.searchText.length - a.searchText.length;
-        return a.n - b.n;
-    });
-    const simpleKeys = parsedKeys
+    const simpleKeys = deduplicatedKeys
         .filter((k) => k.type === 'simple')
         .sort((a, b) => b.searchText.length - a.searchText.length);
     // Track which parts we modify so we can rebuild the zip cleanly
     const modifiedParts = new Map();
-    // Occurrence counter for nth keys (shared across all parts, reset per patchDocument call)
-    const nthCounters = new Map();
+    // Collect all pre-patch paragraph text for zero-match detection
+    const preMatchTexts = [];
     for (const partName of partNames) {
         const entry = zip.getEntry(partName);
         if (!entry)
@@ -54,53 +83,38 @@ export async function patchDocument(inputPath, outputPath, replacements, options
         const xml = entry.getData().toString('utf-8');
         const doc = parser.parseFromString(xml, 'text/xml');
         const allParagraphs = doc.getElementsByTagNameNS(W_NS, 'p');
+        // Collect paragraph text before any replacements for zero-match detection
+        for (let i = 0; i < allParagraphs.length; i++) {
+            const text = getParagraphText(allParagraphs[i]);
+            if (!text)
+                continue;
+            preMatchTexts.push(normalizeQuotes(text));
+        }
         // Phase 1: Context keys
         for (const ck of contextKeys) {
             for (let i = 0; i < allParagraphs.length; i++) {
                 const para = allParagraphs[i];
-                const runs = getRunElements(para);
-                if (runs.length === 0)
+                const paraText = getParagraphText(para);
+                if (!paraText)
                     continue;
-                const { fullText } = buildCharMap(runs);
-                if (!fullText.includes(ck.searchText))
+                const normalizedText = normalizeQuotes(paraText);
+                if (!normalizedText.includes(ck.searchText))
                     continue;
                 const rowContext = getTableRowContext(para);
-                if (rowContext === null || !rowContext.includes(ck.context))
-                    continue;
-                replaceInParagraph(para, { [ck.searchText]: ck.value }, [ck.searchText], options?.replacementColor);
-            }
-        }
-        // Phase 2: Nth occurrence keys — group by searchText for a single pass each
-        const nthGroups = new Map();
-        for (const nk of nthKeys) {
-            const group = nthGroups.get(nk.searchText) ?? [];
-            group.push(nk);
-            nthGroups.set(nk.searchText, group);
-        }
-        for (const [searchText, group] of nthGroups) {
-            // Build a map from occurrence number → value for this group
-            const nthMap = new Map();
-            for (const nk of group) {
-                nthMap.set(nk.n, nk.value);
-            }
-            let counter = nthCounters.get(searchText) ?? 0;
-            for (let i = 0; i < allParagraphs.length; i++) {
-                const para = allParagraphs[i];
-                const runs = getRunElements(para);
-                if (runs.length === 0)
-                    continue;
-                const { fullText } = buildCharMap(runs);
-                if (!fullText.includes(searchText))
-                    continue;
-                counter++;
-                const value = nthMap.get(counter);
-                if (value !== undefined) {
-                    replaceInParagraphOnce(para, searchText, value, options?.replacementColor);
+                if (rowContext !== null) {
+                    const normalizedRowContext = normalizeQuotes(rowContext);
+                    if (!normalizedRowContext.includes(ck.context))
+                        continue;
+                    replaceInParagraph(para, { [ck.searchText]: ck.value }, [ck.searchText], options?.replacementColor);
+                }
+                else {
+                    if (!normalizedText.includes(ck.context))
+                        continue;
+                    replaceFirstAfterContext(para, ck.searchText, ck.context, ck.value, options?.replacementColor);
                 }
             }
-            nthCounters.set(searchText, counter);
         }
-        // Phase 3: Simple keys
+        // Phase 2: Simple keys
         if (simpleKeys.length > 0) {
             const simpleReplacements = {};
             const simpleSortedKeys = [];
@@ -114,6 +128,15 @@ export async function patchDocument(inputPath, outputPath, replacements, options
         }
         modifiedParts.set(partName, Buffer.from(serializer.serializeToString(doc), 'utf-8'));
     }
+    // Compute zero-match keys by checking pre-patch paragraph text
+    const preMatchFullText = preMatchTexts.join('\n');
+    const zeroMatchKeys = [];
+    for (const pk of deduplicatedKeys) {
+        const keyLabel = pk.type === 'context' ? `${pk.context} > ${pk.searchText}` : pk.searchText;
+        if (!preMatchFullText.includes(pk.searchText)) {
+            zeroMatchKeys.push(keyLabel);
+        }
+    }
     // Rebuild the zip from scratch using addFile() to avoid adm-zip data
     // descriptor issues. Some DOCX files use streaming (bit 3) flags which
     // adm-zip's updateFile/writeZip/toBuffer handle incorrectly.
@@ -123,7 +146,7 @@ export async function patchDocument(inputPath, outputPath, replacements, options
         outZip.addFile(entry.entryName, data);
     }
     writeFileSync(outputPath, outZip.toBuffer());
-    return outputPath;
+    return { outputPath, zeroMatchKeys };
 }
 /**
  * Get the text content of the first table cell (label cell) in the same row
@@ -288,44 +311,16 @@ export function isRunSafeToRemove(run) {
     return true;
 }
 /**
- * Compute the length of the common prefix between two strings.
- */
-function commonPrefixLen(a, b) {
-    let i = 0;
-    while (i < a.length && i < b.length && a[i] === b[i])
-        i++;
-    return i;
-}
-/**
- * Compute the length of the common suffix between two strings,
- * not overlapping with a known common prefix.
- */
-function commonSuffixLen(a, b, prefixLen) {
-    let i = 0;
-    while (i < a.length - prefixLen &&
-        i < b.length - prefixLen &&
-        a[a.length - 1 - i] === b[b.length - 1 - i])
-        i++;
-    return i;
-}
-/**
- * Perform a single replacement of searchText with value in the paragraph.
- * Does NOT loop — replaces only the first match found.
- * Used for nth-occurrence keys where the value may contain the searchText.
+ * Legacy charMap-based splice: replace `searchTextLength` characters starting at
+ * `matchStart` with `value`, cleaning up empty runs afterwards.
+ * Used as a fallback when replaceParagraphTextRange throws UNSAFE_CONTAINER_BOUNDARY
+ * (e.g. replacements spanning across hyperlinks or SDTs) or UNSUPPORTED_EDIT
+ * (e.g. replacement spans field results).
  */
-function replaceInParagraphOnce(para, searchText, value, replacementColor) {
-    const runs = getRunElements(para);
-    if (runs.length === 0)
-        return;
-    const rebuilt = buildCharMap(runs);
-    const matchStart = rebuilt.fullText.indexOf(searchText);
-    if (matchStart === -1)
-        return;
-    // Always use full replacement for single-shot mode
-    const start = matchStart;
-    const end = matchStart + searchText.length;
-    const firstEntry = rebuilt.charMap[start];
-    const lastEntry = rebuilt.charMap[end - 1];
+function replaceAtPositionLegacy(runs, charMap, matchStart, searchTextLength, value, replacementColor) {
+    const end = matchStart + searchTextLength;
+    const firstEntry = charMap[matchStart];
+    const lastEntry = charMap[end - 1];
     if (firstEntry.runIndex === lastEntry.runIndex) {
         const runText = getRunText(runs[firstEntry.runIndex]);
         setRunText(runs[firstEntry.runIndex], runText.slice(0, firstEntry.charOffset) + value + runText.slice(lastEntry.charOffset + 1));
@@ -349,74 +344,126 @@ function replaceInParagraphOnce(para, searchText, value, replacementColor) {
         }
     }
 }
+/**
+ * Perform a single replacement of searchText with value in the paragraph.
+ * Does NOT loop — replaces only the first match found.
+ * Uses docx-core's replaceParagraphTextRange for correct formatting preservation,
+ * with a legacy charMap fallback for container-boundary cases (hyperlinks, SDTs).
+ */
+function replaceInParagraphOnce(para, searchText, value, replacementColor) {
+    const fullText = getParagraphText(para);
+    const matchStart = normalizeQuotes(fullText).indexOf(searchText);
+    if (matchStart === -1)
+        return;
+    try {
+        replaceParagraphTextRange(para, matchStart, matchStart + searchText.length, replacementColor
+            ? [{ text: value, addRunProps: { color: replacementColor } }]
+            : value);
+    }
+    catch (e) {
+        if (e instanceof SafeDocxError && (e.code === 'UNSAFE_CONTAINER_BOUNDARY' || e.code === 'UNSUPPORTED_EDIT')) {
+            const runs = getRunElements(para);
+            const { fullText: legacyText, charMap } = buildCharMap(runs);
+            const legacyPos = normalizeQuotes(legacyText).indexOf(searchText);
+            if (legacyPos === -1)
+                return;
+            replaceAtPositionLegacy(runs, charMap, legacyPos, searchText.length, value, replacementColor);
+        }
+        else {
+            throw e;
+        }
+    }
+}
+/**
+ * Replace the first occurrence of searchText that appears AFTER contextText
+ * in the same paragraph. Each call is self-contained — no chaining or order dependency.
+ * Uses docx-core's replaceParagraphTextRange with legacy charMap fallback.
+ */
+function replaceFirstAfterContext(para, searchText, contextText, value, replacementColor) {
+    const fullText = getParagraphText(para);
+    const normalizedFull = normalizeQuotes(fullText);
+    const ctxPos = normalizedFull.indexOf(contextText);
+    if (ctxPos === -1)
+        return;
+    const matchStart = normalizedFull.indexOf(searchText, ctxPos + contextText.length);
+    if (matchStart === -1)
+        return;
+    try {
+        replaceParagraphTextRange(para, matchStart, matchStart + searchText.length, replacementColor
+            ? [{ text: value, addRunProps: { color: replacementColor } }]
+            : value);
+    }
+    catch (e) {
+        if (e instanceof SafeDocxError && (e.code === 'UNSAFE_CONTAINER_BOUNDARY' || e.code === 'UNSUPPORTED_EDIT')) {
+            const runs = getRunElements(para);
+            const { fullText: legacyText, charMap } = buildCharMap(runs);
+            const normalizedLegacy = normalizeQuotes(legacyText);
+            const legacyCtxPos = normalizedLegacy.indexOf(contextText);
+            if (legacyCtxPos === -1)
+                return;
+            const legacyPos = normalizedLegacy.indexOf(searchText, legacyCtxPos + contextText.length);
+            if (legacyPos === -1)
+                return;
+            replaceAtPositionLegacy(runs, charMap, legacyPos, searchText.length, value, replacementColor);
+        }
+        else {
+            throw e;
+        }
+    }
+}
 function replaceInParagraph(para, replacements, sortedKeys, replacementColor) {
-    const runs = getRunElements(para);
-    if (runs.length === 0)
+    // Quick check: skip if no keys match
+    const initialText = getParagraphText(para);
+    if (!initialText)
         return;
-    const { fullText } = buildCharMap(runs);
-    if (!sortedKeys.some((key) => fullText.includes(key)))
+    const normalizedInitial = normalizeQuotes(initialText);
+    if (!sortedKeys.some((key) => normalizedInitial.includes(key)))
         return;
     for (const key of sortedKeys) {
-        let rebuilt = buildCharMap(runs);
         let iterations = 0;
-        while (rebuilt.fullText.includes(key)) {
+        let paraText = getParagraphText(para);
+        while (normalizeQuotes(paraText).includes(key)) {
             iterations++;
             if (iterations > MAX_REPLACEMENTS_PER_KEY) {
                 throw new Error(`Patcher: exceeded ${MAX_REPLACEMENTS_PER_KEY} replacements for key "${key}" ` +
                     `in a single paragraph. This usually means the replacement value contains ` +
                     `the search key, creating an infinite loop.`);
             }
-            const prevText = rebuilt.fullText;
-            const matchStart = rebuilt.fullText.indexOf(key);
+            const prevText = paraText;
+            const matchStart = normalizeQuotes(paraText).indexOf(key);
             const replacement = replacements[key];
-            // Surgical replacement: compute common prefix/suffix between key and value
-            // so we only modify the differing middle, preserving formatting on context text.
-            const cpLen = commonPrefixLen(key, replacement);
-            const csLen = commonSuffixLen(key, replacement, cpLen);
-            let start;
-            let end;
-            let replText;
-            if (cpLen + csLen >= key.length || cpLen + csLen >= replacement.length) {
-                // No useful common prefix/suffix — full replacement (current behavior)
-                start = matchStart;
-                end = matchStart + key.length;
-                replText = replacement;
+            try {
+                replaceParagraphTextRange(para, matchStart, matchStart + key.length, replacementColor
+                    ? [{ text: replacement, addRunProps: { color: replacementColor } }]
+                    : replacement);
             }
-            else {
-                // Surgical: only replace the differing middle
-                start = matchStart + cpLen;
-                end = matchStart + key.length - csLen;
-                replText = replacement.slice(cpLen, replacement.length - csLen);
-            }
-            const firstEntry = rebuilt.charMap[start];
-            const lastEntry = rebuilt.charMap[end - 1];
-            if (firstEntry.runIndex === lastEntry.runIndex) {
-                const runText = getRunText(runs[firstEntry.runIndex]);
-                setRunText(runs[firstEntry.runIndex], runText.slice(0, firstEntry.charOffset) + replText + runText.slice(lastEntry.charOffset + 1));
-            }
-            else {
-                const firstRunText = getRunText(runs[firstEntry.runIndex]);
-                setRunText(runs[firstEntry.runIndex], firstRunText.slice(0, firstEntry.charOffset) + replText);
-                const lastRunText = getRunText(runs[lastEntry.runIndex]);
-                setRunText(runs[lastEntry.runIndex], lastRunText.slice(lastEntry.charOffset + 1));
-                for (let mid = firstEntry.runIndex + 1; mid < lastEntry.runIndex; mid++) {
-                    setRunText(runs[mid], '');
+            catch (e) {
+                if (e instanceof SafeDocxError && (e.code === 'UNSAFE_CONTAINER_BOUNDARY' || e.code === 'UNSUPPORTED_EDIT')) {
+                    // Fallback: use legacy charMap splice for this specific match
+                    const runs = getRunElements(para);
+                    const { fullText: legacyText, charMap } = buildCharMap(runs);
+                    const legacyPos = normalizeQuotes(legacyText).indexOf(key);
+                    if (legacyPos === -1)
+                        break;
+                    replaceAtPositionLegacy(runs, charMap, legacyPos, key.length, replacement, replacementColor);
+                }
+                else {
+                    throw e;
                 }
             }
-            if (replacementColor) {
-                setRunColor(runs[firstEntry.runIndex], replacementColor);
-            }
-            rebuilt = buildCharMap(runs);
+            // Re-read paragraph text after DOM modification
+            paraText = getParagraphText(para);
             // Progress guard: if text didn't change, we're stuck
-            if (rebuilt.fullText === prevText) {
+            if (paraText === prevText) {
                 throw new Error(`Patcher: no progress replacing key "${key}" — replacement value may contain the search key.`);
             }
         }
     }
     // Sweep: remove empty runs that are safe to remove (no drawings, fields, etc.)
-    for (let i = runs.length - 1; i >= 0; i--) {
-        if (getRunText(runs[i]) === '' && isRunSafeToRemove(runs[i])) {
-            runs[i].parentNode?.removeChild(runs[i]);
+    const finalRuns = getRunElements(para);
+    for (let i = finalRuns.length - 1; i >= 0; i--) {
+        if (getRunText(finalRuns[i]) === '' && isRunSafeToRemove(finalRuns[i])) {
+            finalRuns[i].parentNode?.removeChild(finalRuns[i]);
         }
     }
 }