@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/core/paragraph-targeting.js

@@ -15,6 +15,13 @@ function createTargetNotFoundError(message) {
     return error;
 }
 
+function createTargetError(code, message, candidates = null) {
+    const error = new Error(message);
+    error.code = code;
+    if (Array.isArray(candidates)) error.candidates = candidates;
+    return error;
+}
+
 export const WORD_MAIN_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 
 function getElementsByLocalName(node, localName) {
@@ -33,26 +40,8 @@ function getElementsByLocalName(node, localName) {
     return toArray(node.getElementsByTagName(localName));
 }
 
-function toParagraphText(paragraph) {
-    let text = '';
-
-    const visit = node => {
-        for (const child of toArray(node?.childNodes)) {
-            if (child?.nodeType !== 1) continue;
-            const localName = String(child.localName || child.nodeName || '').replace(/^.*:/, '');
-            if (localName === 't') {
-                text += child.textContent || '';
-            } else if (localName === 'tab') {
-                text += '\t';
-            } else {
-                visit(child);
-            }
-        }
-    };
-
-    visit(paragraph);
-    return text;
-}
+import { extractCanonicalParagraphText } from './paragraph-text.js';
+import { isWordElement } from './word-xml.js';
 
 /**
  * Reads visible text from a paragraph by concatenating `w:t` nodes and mapping
@@ -63,7 +52,7 @@ function toParagraphText(paragraph) {
  */
 export function getParagraphText(paragraph) {
     if (!paragraph) return '';
-    return toParagraphText(paragraph);
+    return extractCanonicalParagraphText(paragraph);
 }
 
 /**
@@ -79,6 +68,94 @@ export function getDocumentParagraphNodes(xmlDoc) {
     return getElementsByLocalName(searchRoot, 'p');
 }
 
+export function getParagraphId(paragraph) {
+    if (!paragraph) return null;
+    const attribute = toArray(paragraph.attributes).find(candidate =>
+        String(candidate?.localName || candidate?.name || '').replace(/^.*:/, '') === 'paraId'
+    );
+    return attribute?.value || null;
+}
+
+export function createParagraphFingerprint(paragraph, metadata = {}) {
+    if (!paragraph) return null;
+    const revisionView = metadata.revisionView === 'rejected' ? 'rejected' : 'accepted';
+    const text = typeof metadata.text === 'string'
+        ? metadata.text
+        : extractCanonicalParagraphText(paragraph, { revisionView });
+    const documentIndex = Number.isInteger(metadata.index)
+        ? metadata.index
+        : getDocumentParagraphNodes(paragraph.ownerDocument || paragraph).indexOf(paragraph) + 1;
+    const paragraphId = metadata.paragraphId === undefined ? getParagraphId(paragraph) : metadata.paragraphId;
+    const inTable = typeof metadata.inTable === 'boolean' ? metadata.inTable : isParagraphInTable(paragraph);
+    const viewPart = revisionView === 'rejected' ? 'rejected\u001f' : '';
+    const identity = `${paragraphId || ''}\u001f${documentIndex}\u001f${inTable ? 'table' : 'body'}\u001f${viewPart}${text}`;
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < identity.length; i++) {
+        hash ^= identity.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `fnv1a32:${hash.toString(16).padStart(8, '0')}`;
+}
+
+/**
+ * Builds immutable paragraph metadata and grouped lookup maps for one document
+ * state. The index is intentionally session-scoped because it retains DOM
+ * nodes and must be discarded after a mutation.
+ *
+ * @param {Document|Element|null|undefined} xmlDoc - OOXML document root
+ * @param {Object} [options={}] - Options
+ * @param {'accepted'|'rejected'} [options.revisionView='accepted'] - Revision view
+ * @returns {{revisionView: 'accepted'|'rejected', entries: ReadonlyArray<Object>, byParagraph: Map<Element,Object>, byId: Map<string,Object>, byNormalizedText: Map<string,ReadonlyArray<Object>>}}
+ */
+export function buildParagraphMetadataIndex(xmlDoc, options = {}) {
+    const revisionView = options.revisionView === 'rejected' ? 'rejected' : 'accepted';
+    const paragraphs = getDocumentParagraphNodes(xmlDoc);
+    const entries = [];
+    const byParagraph = new Map();
+    const byId = new Map();
+    const grouped = new Map();
+
+    for (let offset = 0; offset < paragraphs.length; offset++) {
+        const paragraph = paragraphs[offset];
+        const text = extractCanonicalParagraphText(paragraph, { revisionView });
+        const paragraphId = getParagraphId(paragraph);
+        const inTable = isParagraphInTable(paragraph);
+        const normalizedText = normalizeWhitespaceForTargeting(text);
+        const entry = Object.freeze({
+            paragraph,
+            index: offset + 1,
+            paragraphId,
+            text,
+            normalizedText,
+            revisionView,
+            fingerprint: createParagraphFingerprint(paragraph, {
+                text,
+                index: offset + 1,
+                paragraphId,
+                inTable,
+                revisionView
+            }),
+            inTable
+        });
+        entries.push(entry);
+        byParagraph.set(paragraph, entry);
+        if (paragraphId && !byId.has(paragraphId)) byId.set(paragraphId, entry);
+        if (normalizedText) {
+            if (!grouped.has(normalizedText)) grouped.set(normalizedText, []);
+            grouped.get(normalizedText).push(entry);
+        }
+    }
+
+    for (const [key, values] of grouped) grouped.set(key, Object.freeze(values));
+    return Object.freeze({
+        revisionView,
+        entries: Object.freeze(entries),
+        byParagraph,
+        byId,
+        byNormalizedText: grouped
+    });
+}
+
 /**
  * Normalizes whitespace for paragraph-comparison matching.
  *
@@ -157,10 +234,12 @@ export function splitLeadingParagraphMarker(text) {
  * @param {number|null|undefined} targetRef - 1-based paragraph number
  * @returns {Element|null}
  */
-export function findParagraphByReference(xmlDoc, targetRef) {
+export function findParagraphByReference(xmlDoc, targetRef, paragraphMetadataIndex = null) {
     if (!Number.isInteger(targetRef) || targetRef < 1) return null;
-    const paragraphs = getDocumentParagraphNodes(xmlDoc);
-    return paragraphs[targetRef - 1] || null;
+    if (paragraphMetadataIndex?.entries) {
+        return paragraphMetadataIndex.entries[targetRef - 1]?.paragraph || null;
+    }
+    return getDocumentParagraphNodes(xmlDoc)[targetRef - 1] || null;
 }
 
 /**
@@ -193,15 +272,22 @@ export function findContainingWordElement(node, localName, namespaceUri = WORD_M
  * @param {string} targetText - Target paragraph text
  * @returns {Element|null}
  */
-export function findParagraphByStrictText(xmlDoc, targetText) {
-    const paragraphs = getDocumentParagraphNodes(xmlDoc);
+export function findParagraphByStrictText(xmlDoc, targetText, options = {}) {
+    const metadataIndex = options.paragraphMetadataIndex || null;
+    const entries = metadataIndex?.entries || null;
+    const paragraphs = entries ? null : getDocumentParagraphNodes(xmlDoc);
     const normalizedTarget = String(targetText || '').trim();
     if (!normalizedTarget) return null;
 
-    const exact = paragraphs.find(p => getParagraphText(p).trim() === normalizedTarget);
+    const exact = entries
+        ? entries.find(entry => entry.text.trim() === normalizedTarget)?.paragraph
+        : paragraphs.find(p => getParagraphText(p).trim() === normalizedTarget);
     if (exact) return exact;
 
     const normTarget = normalizeWhitespaceForTargeting(normalizedTarget);
+    if (metadataIndex?.byNormalizedText) {
+        return metadataIndex.byNormalizedText.get(normTarget)?.[0]?.paragraph || null;
+    }
     return paragraphs.find(p => normalizeWhitespaceForTargeting(getParagraphText(p)) === normTarget) || null;
 }
 
@@ -215,28 +301,34 @@ export function findParagraphByStrictText(xmlDoc, targetText) {
  */
 export function findParagraphByBestTextMatch(xmlDoc, targetText, options = {}) {
     const onInfo = typeof options.onInfo === 'function' ? options.onInfo : () => {};
-    const paragraphs = getDocumentParagraphNodes(xmlDoc);
+    const metadataIndex = options.paragraphMetadataIndex || null;
+    const entries = metadataIndex?.entries || null;
+    const paragraphs = entries ? null : getDocumentParagraphNodes(xmlDoc);
     const normalizedTarget = String(targetText || '').trim();
     if (!normalizedTarget) return null;
 
-    const strictMatch = findParagraphByStrictText(xmlDoc, normalizedTarget);
+    const strictMatch = findParagraphByStrictText(xmlDoc, normalizedTarget, { paragraphMetadataIndex: metadataIndex });
     if (strictMatch) return strictMatch;
 
     const normTarget = normalizeWhitespaceForTargeting(normalizedTarget);
 
-    const startsWithMatch = paragraphs.find(p => {
-        const paragraphText = normalizeWhitespaceForTargeting(getParagraphText(p));
-        return paragraphText.length > 10 && normTarget.startsWith(paragraphText);
-    });
+    const startsWithMatch = entries
+        ? (entries.find(entry => entry.normalizedText.length > 10 && normTarget.startsWith(entry.normalizedText))?.paragraph || null)
+        : paragraphs.find(p => {
+            const paragraphText = normalizeWhitespaceForTargeting(getParagraphText(p));
+            return paragraphText.length > 10 && normTarget.startsWith(paragraphText);
+        });
     if (startsWithMatch) {
         onInfo(`[Fuzzy] Prefix match (target starts with paragraph): "${getParagraphText(startsWithMatch).trim().slice(0, 60)}..."`);
         return startsWithMatch;
     }
 
-    const containsMatch = paragraphs.find(p => {
-        const paragraphText = normalizeWhitespaceForTargeting(getParagraphText(p));
-        return paragraphText.length > 15 && normTarget.includes(paragraphText);
-    });
+    const containsMatch = entries
+        ? (entries.find(entry => entry.normalizedText.length > 15 && normTarget.includes(entry.normalizedText))?.paragraph || null)
+        : paragraphs.find(p => {
+            const paragraphText = normalizeWhitespaceForTargeting(getParagraphText(p));
+            return paragraphText.length > 15 && normTarget.includes(paragraphText);
+        });
     if (containsMatch) {
         onInfo(`[Fuzzy] Contains match: "${getParagraphText(containsMatch).trim().slice(0, 60)}..."`);
         return containsMatch;
@@ -245,8 +337,10 @@ export function findParagraphByBestTextMatch(xmlDoc, targetText, options = {}) {
     let bestScore = 0;
     let bestParagraph = null;
     const targetWords = new Set(normTarget.toLowerCase().split(/\s+/).filter(word => word.length > 2));
-    for (const paragraph of paragraphs) {
-        const paragraphText = getParagraphText(paragraph).trim();
+    const candidateCount = entries?.length ?? paragraphs.length;
+    for (let index = 0; index < candidateCount; index++) {
+        const paragraph = entries?.[index]?.paragraph ?? paragraphs[index];
+        const paragraphText = (entries?.[index]?.text ?? getParagraphText(paragraph)).trim();
         if (!paragraphText) continue;
 
         const paragraphWords = normalizeWhitespaceForTargeting(paragraphText)
@@ -291,15 +385,173 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
     const onInfo = typeof options.onInfo === 'function' ? options.onInfo : () => {};
     const onWarn = typeof options.onWarn === 'function' ? options.onWarn : () => {};
     const opType = options.opType || 'operation';
-    const cleanTargetText = String(options.targetText || '').trim();
-    const parsedRef = parseParagraphReference(options.targetRef);
+    const descriptor = options.targetDescriptor && typeof options.targetDescriptor === 'object'
+        ? options.targetDescriptor
+        : null;
+    const revisionView = descriptor?.revisionView === 'rejected' ? 'rejected' : 'accepted';
+    const cleanTargetText = String(descriptor?.exactText ?? descriptor?.text ?? options.targetText ?? '').trim();
+    const parsedRef = parseParagraphReference(descriptor?.index ?? descriptor?.paragraphIndex ?? options.targetRef);
+    const strictAmbiguity = options.strictAmbiguity === true;
+    let paragraphMetadataIndex = options.paragraphMetadataIndex || null;
+    if (paragraphMetadataIndex && paragraphMetadataIndex.revisionView !== revisionView) {
+        paragraphMetadataIndex = options.metadataIndices?.[revisionView]
+            || buildParagraphMetadataIndex(xmlDoc, { revisionView });
+    } else if (!paragraphMetadataIndex) {
+        paragraphMetadataIndex = buildParagraphMetadataIndex(xmlDoc, { revisionView });
+    }
+
+    if (descriptor?.paragraphId) {
+        const byId = findParagraphById(xmlDoc, descriptor.paragraphId, paragraphMetadataIndex);
+        if (!byId) {
+            throw createTargetError(
+                'TARGET_NOT_FOUND',
+                `Target paragraphId not found: "${descriptor.paragraphId}".`
+            );
+        }
+        const cachedEntry = paragraphMetadataIndex?.byParagraph?.get(byId) || null;
+        const actualIndex = cachedEntry?.index ?? getDocumentParagraphNodes(xmlDoc).indexOf(byId) + 1;
+        const actualFingerprint = cachedEntry?.fingerprint
+            || createParagraphFingerprint(byId, { revisionView });
+        const actualInTable = cachedEntry?.inTable ?? isParagraphInTable(byId);
+        const actualText = cachedEntry?.normalizedText
+            || normalizeWhitespaceForTargeting(extractCanonicalParagraphText(byId, { revisionView }));
+
+        if (parsedRef != null && parsedRef !== actualIndex) {
+            throw createTargetError(
+                'TARGET_INDEX_MISMATCH',
+                `Target paragraphId "${descriptor.paragraphId}" (index ${actualIndex}) does not match requested index ${parsedRef}.`,
+                cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
+            );
+        }
+        if (descriptor.fingerprint && descriptor.fingerprint !== actualFingerprint) {
+            throw createTargetError(
+                'TARGET_FINGERPRINT_MISMATCH',
+                `Target paragraphId "${descriptor.paragraphId}" no longer matches its source fingerprint.`,
+                cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
+            );
+        }
+        if (typeof descriptor.inTable === 'boolean' && descriptor.inTable !== actualInTable) {
+            throw createTargetError(
+                'TARGET_CONTEXT_MISMATCH',
+                `Target paragraphId "${descriptor.paragraphId}" does not match the requested table context.`,
+                cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
+            );
+        }
+        if (cleanTargetText && actualText !== normalizeWhitespaceForTargeting(cleanTargetText)) {
+            throw createTargetError(
+                'TARGET_TEXT_MISMATCH',
+                `Target paragraphId "${descriptor.paragraphId}" no longer matches the supplied text.`,
+                cachedEntry ? [serializeTargetCandidate(cachedEntry)] : null
+            );
+        }
+        if (descriptor.occurrence != null) {
+            const textToFind = cleanTargetText || actualText;
+            const textCandidates = findStrictTargetCandidates(xmlDoc, textToFind, paragraphMetadataIndex);
+            const actualOccurrence = textCandidates.findIndex(c => c.paragraph === byId) + 1;
+            if (actualOccurrence === 0 || actualOccurrence !== descriptor.occurrence) {
+                throw createTargetError(
+                    'TARGET_OCCURRENCE_MISMATCH',
+                    `Target paragraphId "${descriptor.paragraphId}" matches occurrence ${actualOccurrence}, not requested occurrence ${descriptor.occurrence}.`,
+                    textCandidates.map(serializeTargetCandidate)
+                );
+            }
+        }
+        return { paragraph: byId, resolvedBy: 'paragraph_id' };
+    }
+
+    let candidates = [];
+    if (cleanTargetText) {
+        const unfilteredCandidates = findStrictTargetCandidates(xmlDoc, cleanTargetText, paragraphMetadataIndex);
+        candidates = filterTargetCandidates(unfilteredCandidates, descriptor);
+
+        if (descriptor?.fingerprint && unfilteredCandidates.length > 0 && candidates.length === 0) {
+            throw createTargetError(
+                'TARGET_FINGERPRINT_MISMATCH',
+                'Target text matched, but no paragraph matched the supplied source fingerprint.',
+                unfilteredCandidates.map(serializeTargetCandidate)
+            );
+        }
+
+        if (
+            typeof descriptor?.inTable === 'boolean'
+            && unfilteredCandidates.length > 0
+            && candidates.length === 0
+        ) {
+            throw createTargetError(
+                'TARGET_CONTEXT_MISMATCH',
+                'Target text matched, but no paragraph matched the requested table context.',
+                unfilteredCandidates.map(serializeTargetCandidate)
+            );
+        }
+
+
+        if (descriptor?.occurrence) {
+            const occurrenceMatch = candidates[descriptor.occurrence - 1] || null;
+            if (!occurrenceMatch) {
+                throw createTargetError(
+                    'TARGET_NOT_FOUND',
+                    `Target occurrence ${descriptor.occurrence} was not found.`,
+                    candidates.map(serializeTargetCandidate)
+                );
+            }
+            return { paragraph: occurrenceMatch.paragraph, resolvedBy: 'occurrence' };
+        }
+
+        if (strictAmbiguity) {
+            if (parsedRef) {
+                const byReference = candidates.find(candidate => candidate.index === parsedRef) || null;
+                if (byReference) return { paragraph: byReference.paragraph, resolvedBy: 'ref' };
+                if (descriptor?.fingerprint && candidates.length > 0) {
+                    throw createTargetError(
+                        'TARGET_FINGERPRINT_MISMATCH',
+                        `Target fingerprint does not match paragraph reference [P${parsedRef}].`,
+                        candidates.map(serializeTargetCandidate)
+                    );
+                }
+                if (candidates.length === 1) {
+                    return { paragraph: candidates[0].paragraph, resolvedBy: 'strict_text_after_ref_drift' };
+                }
+            }
+            if (candidates.length > 1) {
+                throw createTargetError(
+                    'AMBIGUOUS_TARGET',
+                    `Target text matched ${candidates.length} paragraphs; provide paragraphId, index, occurrence, or fingerprint.`,
+                    candidates.map(serializeTargetCandidate)
+                );
+            }
+            if (candidates.length === 0) {
+                throw createTargetNotFoundError(`Target paragraph not found: "${cleanTargetText}"`);
+            }
+        }
+
+        if (!parsedRef && candidates.length === 1) {
+            const candidate = candidates[0];
+            return {
+                paragraph: candidate.paragraph,
+                resolvedBy: descriptor?.fingerprint ? 'fingerprint' : 'strict_text'
+            };
+        }
+    }
 
     if (parsedRef) {
-        const byRef = findParagraphByReference(xmlDoc, parsedRef);
+        const byRef = findParagraphByReference(xmlDoc, parsedRef, paragraphMetadataIndex);
         if (byRef) {
+            const cached = paragraphMetadataIndex?.byParagraph?.get(byRef) || null;
+            if (descriptor?.fingerprint && descriptor.fingerprint !== cached?.fingerprint) {
+                throw createTargetError(
+                    'TARGET_FINGERPRINT_MISMATCH',
+                    `Target fingerprint does not match paragraph reference [P${parsedRef}].`
+                );
+            }
+            if (typeof descriptor?.inTable === 'boolean' && descriptor.inTable !== cached?.inTable) {
+                throw createTargetError(
+                    'TARGET_CONTEXT_MISMATCH',
+                    `Target paragraph reference [P${parsedRef}] does not match requested table context.`
+                );
+            }
             if (cleanTargetText) {
-                const strictMatch = findParagraphByStrictText(xmlDoc, cleanTargetText);
-                const byRefText = getParagraphText(byRef).trim();
+                const strictMatch = findParagraphByStrictText(xmlDoc, cleanTargetText, { paragraphMetadataIndex });
+                const byRefText = (cached?.text || extractCanonicalParagraphText(byRef, { revisionView })).trim();
                 const byRefNorm = normalizeWhitespaceForTargeting(byRefText);
                 const targetNorm = normalizeWhitespaceForTargeting(cleanTargetText);
                 const hasDrift = byRefNorm !== targetNorm;
@@ -310,7 +562,7 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
                 }
 
                 if (hasDrift) {
-                    const fuzzyMatch = findParagraphByBestTextMatch(xmlDoc, cleanTargetText, { onInfo });
+                    const fuzzyMatch = findParagraphByBestTextMatch(xmlDoc, cleanTargetText, { onInfo, paragraphMetadataIndex });
                     if (fuzzyMatch && fuzzyMatch !== byRef) {
                         onInfo(`[Target] [P${parsedRef}] drifted for ${opType}; using fuzzy text rematch.`);
                         return { paragraph: fuzzyMatch, resolvedBy: 'fuzzy_text_after_ref_drift' };
@@ -328,11 +580,23 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
         onWarn(`[WARN] Target reference [P${parsedRef}] not found; falling back to text matching for ${opType}.`);
     }
 
-    if (cleanTargetText) {
-        const strictMatch = findParagraphByStrictText(xmlDoc, cleanTargetText);
-        if (strictMatch) return { paragraph: strictMatch, resolvedBy: 'strict_text' };
+    if (cleanTargetText && !strictAmbiguity) {
+        const strictMatch = findParagraphByStrictText(xmlDoc, cleanTargetText, { paragraphMetadataIndex });
+        if (strictMatch) {
+            const candidateCount = candidates.length;
+            if (candidateCount > 1) {
+                const warningMsg = `AMBIGUOUS_TARGET_HEURISTIC_USED: Target text matched ${candidateCount} paragraphs; permissive resolution chose candidate 1. Migrate to strict targeting (e.g. strictTargets: true with paragraphId, index, occurrence, or fingerprint) before v1.0.0.`;
+                onWarn(warningMsg);
+                return {
+                    paragraph: strictMatch,
+                    resolvedBy: 'strict_text',
+                    warnings: [warningMsg]
+                };
+            }
+            return { paragraph: strictMatch, resolvedBy: 'strict_text' };
+        }
 
-        const fuzzyMatch = findParagraphByBestTextMatch(xmlDoc, cleanTargetText, { onInfo });
+        const fuzzyMatch = findParagraphByBestTextMatch(xmlDoc, cleanTargetText, { onInfo, paragraphMetadataIndex });
         if (fuzzyMatch) return { paragraph: fuzzyMatch, resolvedBy: 'fuzzy_text' };
     }
 
@@ -345,26 +609,76 @@ function isParagraphInTable(paragraph) {
     return !!findContainingWordElement(paragraph, 'tbl');
 }
 
-function findStrictTargetCandidates(xmlDoc, targetText) {
+export function findStrictTargetCandidates(xmlDoc, targetText, optionsOrIndex = null) {
     const normalizedTarget = normalizeWhitespaceForTargeting(targetText);
     if (!normalizedTarget) return [];
 
+    const metadataIndex = optionsOrIndex?.byNormalizedText
+        ? optionsOrIndex
+        : (optionsOrIndex?.paragraphMetadataIndex || null);
+    const revisionView = optionsOrIndex?.revisionView
+        || metadataIndex?.revisionView
+        || 'accepted';
+
+    if (metadataIndex?.byNormalizedText && metadataIndex.revisionView === revisionView) {
+        return Array.from(metadataIndex.byNormalizedText.get(normalizedTarget) || []);
+    }
+
     const paragraphs = getDocumentParagraphNodes(xmlDoc);
     const candidates = [];
     for (let i = 0; i < paragraphs.length; i++) {
         const paragraph = paragraphs[i];
-        const paragraphText = getParagraphText(paragraph).trim();
+        const paragraphText = extractCanonicalParagraphText(paragraph, { revisionView }).trim();
         if (!paragraphText) continue;
         if (normalizeWhitespaceForTargeting(paragraphText) !== normalizedTarget) continue;
         candidates.push({
             paragraph,
             index: i + 1,
-            inTable: isParagraphInTable(paragraph)
+            inTable: isParagraphInTable(paragraph),
+            paragraphId: getParagraphId(paragraph),
+            fingerprint: createParagraphFingerprint(paragraph, {
+                text: paragraphText,
+                index: i + 1,
+                revisionView
+            }),
+            text: paragraphText,
+            revisionView
         });
     }
     return candidates;
 }
 
+function serializeTargetCandidate(candidate) {
+    return {
+        index: candidate.index,
+        paragraphId: candidate.paragraphId || null,
+        text: candidate.text,
+        inTable: candidate.inTable,
+        fingerprint: candidate.fingerprint,
+        revisionView: candidate.revisionView || 'accepted'
+    };
+}
+
+function filterTargetCandidates(candidates, descriptor) {
+    let scoped = candidates.slice();
+    if (descriptor?.paragraphId) {
+        scoped = scoped.filter(candidate => candidate.paragraphId === descriptor.paragraphId);
+    }
+    if (typeof descriptor?.inTable === 'boolean') {
+        scoped = scoped.filter(candidate => candidate.inTable === descriptor.inTable);
+    }
+    if (descriptor?.fingerprint) {
+        scoped = scoped.filter(candidate => candidate.fingerprint === descriptor.fingerprint);
+    }
+    return scoped;
+}
+
+function findParagraphById(xmlDoc, paragraphId, paragraphMetadataIndex = null) {
+    if (!paragraphId) return null;
+    if (paragraphMetadataIndex?.byId) return paragraphMetadataIndex.byId.get(paragraphId)?.paragraph || null;
+    return getDocumentParagraphNodes(xmlDoc).find(paragraph => getParagraphId(paragraph) === paragraphId) || null;
+}
+
 function selectBestTargetCandidate(candidates, parsedRef, expectedInTable = null) {
     if (!Array.isArray(candidates) || candidates.length === 0) return null;
 
@@ -390,16 +704,18 @@ function selectBestTargetCandidate(candidates, parsedRef, expectedInTable = null
  * @param {Document|Element|null|undefined} xmlDoc - OOXML document root
  * @returns {Map<number, { text: string, normalizedText: string, inTable: boolean }>}
  */
-export function buildTargetReferenceSnapshot(xmlDoc) {
-    const paragraphs = getDocumentParagraphNodes(xmlDoc);
+export function buildTargetReferenceSnapshot(xmlDoc, paragraphMetadataIndex = null) {
+    const entries = paragraphMetadataIndex?.entries || null;
+    const paragraphs = entries ? null : getDocumentParagraphNodes(xmlDoc);
     const snapshot = new Map();
-    for (let i = 0; i < paragraphs.length; i++) {
-        const paragraph = paragraphs[i];
-        const text = getParagraphText(paragraph).trim();
+    const paragraphCount = entries?.length ?? paragraphs.length;
+    for (let i = 0; i < paragraphCount; i++) {
+        const paragraph = entries?.[i]?.paragraph ?? paragraphs[i];
+        const text = (entries?.[i]?.text ?? getParagraphText(paragraph)).trim();
         snapshot.set(i + 1, {
             text,
-            normalizedText: normalizeWhitespaceForTargeting(text),
-            inTable: isParagraphInTable(paragraph)
+            normalizedText: entries?.[i]?.normalizedText ?? normalizeWhitespaceForTargeting(text),
+            inTable: entries?.[i]?.inTable ?? isParagraphInTable(paragraph)
         });
     }
     return snapshot;
@@ -437,7 +753,8 @@ export function resolveTargetParagraphWithSnapshot(xmlDoc, options = {}) {
     const expectedNorm = normalizeWhitespaceForTargeting(expectedText);
     if (!expectedNorm) return resolved;
 
-    const resolvedNorm = normalizeWhitespaceForTargeting(getParagraphText(resolved.paragraph));
+    const resolvedNorm = options.paragraphMetadataIndex?.byParagraph?.get(resolved.paragraph)?.normalizedText
+        || normalizeWhitespaceForTargeting(getParagraphText(resolved.paragraph));
     if (resolvedNorm === expectedNorm) return resolved;
 
     const candidateTexts = [];
@@ -451,7 +768,7 @@ export function resolveTargetParagraphWithSnapshot(xmlDoc, options = {}) {
 
     let bestCandidate = null;
     for (const candidateText of candidateTexts) {
-        const candidates = findStrictTargetCandidates(xmlDoc, candidateText);
+        const candidates = findStrictTargetCandidates(xmlDoc, candidateText, options.paragraphMetadataIndex || null);
         const selected = selectBestTargetCandidate(candidates, parsedRef, snapshotEntry.inTable);
         if (!selected) continue;
         if (!bestCandidate) bestCandidate = selected;
@@ -525,3 +842,126 @@ export function resolveParagraphRangeByRefs(xmlDoc, startRef, endRef, options =
     if (!range.every(node => node && node.parentNode === parent)) return null;
     return range;
 }
+
+/**
+ * Validates a paragraph boundary operation (split, delete, join) before mutation.
+ * Returns { valid: true } or { valid: false, code: 'UNSAFE_PARAGRAPH_BOUNDARY', message: string }.
+ *
+ * @param {Element} targetParagraph - Target paragraph node
+ * @param {string} modifiedText - Replacement text
+ * @param {Object} [options={}] - Options
+ * @returns {{ valid: boolean, code?: string, message?: string }}
+ */
+export function validateParagraphBoundaryMutation(targetParagraph, modifiedText, options = {}) {
+    if (!targetParagraph || !targetParagraph.parentNode) {
+        return { valid: true };
+    }
+
+    const isDelete = modifiedText === '' || options.operationKind === 'delete';
+    const isSplit = typeof modifiedText === 'string' && modifiedText.includes('\n');
+    const targetEndParagraph = options.targetEndParagraph || null;
+
+    // 1. Table cell boundary checks
+    const containingTc = findContainingWordElement(targetParagraph, 'tc');
+    if (containingTc) {
+        if (isDelete) {
+            const cellParagraphs = Array.from(containingTc.childNodes).filter(node => isWordElement(node, 'p'));
+            if (cellParagraphs.length <= 1) {
+                return {
+                    valid: false,
+                    code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                    message: 'Refusing to delete the sole terminal paragraph of a table cell.'
+                };
+            }
+        }
+        if (targetEndParagraph) {
+            const endTc = findContainingWordElement(targetEndParagraph, 'tc');
+            if (endTc !== containingTc) {
+                return {
+                    valid: false,
+                    code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                    message: 'Refusing paragraph boundary join across different table cells.'
+                };
+            }
+        }
+    } else if (targetEndParagraph) {
+        const endTc = findContainingWordElement(targetEndParagraph, 'tc');
+        if (endTc) {
+            return {
+                valid: false,
+                code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                message: 'Refusing paragraph boundary join across table boundaries.'
+            };
+        }
+    }
+
+    // 2. Section break (w:sectPr) checks
+    const hasSectPr = targetParagraph.getElementsByTagNameNS(WORD_MAIN_NS, 'sectPr').length > 0;
+    if (hasSectPr && isDelete) {
+        return {
+            valid: false,
+            code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+            message: 'Refusing to delete paragraph containing section properties (w:sectPr).'
+        };
+    }
+
+    if (targetEndParagraph) {
+        let cursor = targetParagraph;
+        while (cursor && cursor !== targetEndParagraph) {
+            if (isWordElement(cursor, 'p') && cursor.getElementsByTagNameNS(WORD_MAIN_NS, 'sectPr').length > 0) {
+                return {
+                    valid: false,
+                    code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                    message: 'Refusing paragraph boundary join across section break.'
+                };
+            }
+            cursor = cursor.nextSibling;
+        }
+    }
+
+    // 3. Field instruction checks during split
+    if (isSplit) {
+        const fldSimples = targetParagraph.getElementsByTagNameNS(WORD_MAIN_NS, 'fldSimple');
+        if (fldSimples.length > 0) {
+            return {
+                valid: false,
+                code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                message: 'Refusing to split paragraph containing a simple field instruction (w:fldSimple).'
+            };
+        }
+
+        const fldChars = Array.from(targetParagraph.getElementsByTagNameNS(WORD_MAIN_NS, 'fldChar'));
+        if (fldChars.length > 0) {
+            let activeFields = 0;
+            for (const fc of fldChars) {
+                const fldCharType = fc.getAttributeNS(WORD_MAIN_NS, 'fldCharType') || fc.getAttribute('w:fldCharType');
+                if (fldCharType === 'begin') activeFields++;
+                else if (fldCharType === 'end') activeFields = Math.max(0, activeFields - 1);
+            }
+            if (activeFields > 0) {
+                return {
+                    valid: false,
+                    code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                    message: 'Refusing to split paragraph across an unclosed field instruction.'
+                };
+            }
+        }
+
+        // 4. Bookmark range boundary checks
+        const bookmarkStarts = Array.from(targetParagraph.getElementsByTagNameNS(WORD_MAIN_NS, 'bookmarkStart'));
+        const bookmarkEnds = Array.from(targetParagraph.getElementsByTagNameNS(WORD_MAIN_NS, 'bookmarkEnd'));
+        const bStartIds = new Set(bookmarkStarts.map(b => b.getAttributeNS(WORD_MAIN_NS, 'id') || b.getAttribute('w:id')));
+        const bEndIds = new Set(bookmarkEnds.map(b => b.getAttributeNS(WORD_MAIN_NS, 'id') || b.getAttribute('w:id')));
+        for (const id of bStartIds) {
+            if (id && !bEndIds.has(id)) {
+                return {
+                    valid: false,
+                    code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                    message: `Refusing to split paragraph across open bookmark range (ID: ${id}).`
+                };
+            }
+        }
+    }
+
+    return { valid: true };
+}