@ansonlai/docx-redline-js 0.5.2 → 0.5.4

package/services/document-operation-mutations.js

@@ -20,7 +20,20 @@ import {
 } from '../engine/rpr-helpers.js';
 import { refreshRunPropertyChangeIds } from '../core/revision-cloning.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { applyRedlineToOxml as applyRedlineToOxmlEngine } from '../engine/oxml-engine.js';
+import { applyRedlineToOxml as applyRedlineToOxmlEngine } from '../engine/oxml-engine.js';
+import {
+    getParagraphRestorationRefusal,
+    inspectForeignDeletedParagraphTarget
+} from '../core/paragraph-revision-safety.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
+import {
+    getRunContentPieces,
+    getRunTextLength,
+    splitTrackChangeCarrier
+} from '../engine/surgical-run-splitting.js';
 import { applyHighlightToOoxml } from '../engine/formatting-removal.js';
 import { parseTable as parseMarkdownTable } from '../pipeline/pipeline.js';
 import { injectCommentsIntoOoxml } from './comment-engine.js';
@@ -30,10 +43,11 @@ import {
     createParagraphFingerprint,
     isMarkdownTableText,
     findContainingWordElement,
-    resolveTargetParagraphWithSnapshot as resolveTargetParagraphWithSnapshotShared,
-    resolveParagraphRangeByRefs,
-    validateParagraphBoundaryMutation
-} from '../core/paragraph-targeting.js';
+    resolveTargetParagraphWithSnapshot as resolveTargetParagraphWithSnapshotShared,
+    resolveParagraphRangeByRefs,
+    getDocumentParagraphNodes,
+    validateParagraphBoundaryMutation
+} from '../core/paragraph-targeting.js';
 import {
     synthesizeExpandedListScopeEdit,
     planListInsertionOnlyEdit,
@@ -70,9 +84,14 @@ import {
     deriveSingleParagraphListAdjacencyInsertion,
     deriveSingleParagraphPlainAdjacencyInsertion
 } from './operation-heuristics.js';
-import { resolveTargetFromCapture, ensureParagraphIdsOnImportedNode } from './capture-engine.js';
-
-const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+import { resolveTargetFromCapture, ensureParagraphIdsOnImportedNode } from './capture-engine.js';
+import {
+    acceptTrackedChangesInOoxml,
+    rejectTrackedChangesInOoxml
+} from './revision-comment-management.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const NS_W14 = 'http://schemas.microsoft.com/office/word/2010/wordml';
 
 function getCommentIdsInElement(element) {
     const ids = new Set();
@@ -150,9 +169,60 @@ async function reconcileMarkdownTableOoxml(oxml, originalText, markdownTable, op
     };
 }
 
-function getParagraphText(paragraph) {
-    return getParagraphTextFromOxml(paragraph);
-}
+function getParagraphText(paragraph) {
+    return getParagraphTextFromOxml(paragraph);
+}
+
+function escapeInvisibleText(value, maxLength = 96) {
+    const text = String(value ?? '');
+    const bounded = text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+    return bounded
+        .replace(/\\/g, '\\\\')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t')
+        .replace(/\u00a0/g, '\\u00A0')
+        .replace(/\u202f/g, '\\u202F')
+        .replace(/\u2060/g, '\\u2060');
+}
+
+function codePointLabel(value, offset) {
+    if (offset >= value.length) return 'END';
+    return `U+${value.codePointAt(offset).toString(16).toUpperCase().padStart(4, '0')}`;
+}
+
+function describeTargetTextMatch(actualText, requestedText) {
+    const actual = String(actualText ?? '');
+    const requested = String(requestedText ?? '');
+    if (actual === requested) return { mode: 'exact' };
+
+    const differences = [];
+    const limit = Math.min(actual.length, requested.length);
+    for (let offset = 0; offset < limit && differences.length < 8; offset++) {
+        if (actual[offset] === requested[offset]) continue;
+        differences.push({
+            offset,
+            sourceCodePoint: codePointLabel(actual, offset),
+            requestedCodePoint: codePointLabel(requested, offset)
+        });
+    }
+    if (actual.length !== requested.length && differences.length < 8) {
+        differences.push({
+            offset: limit,
+            sourceCodePoint: codePointLabel(actual, limit),
+            requestedCodePoint: codePointLabel(requested, limit)
+        });
+    }
+
+    const spaceEquivalent = actual.length === requested.length
+        && actual.replace(/\u00a0/g, ' ') === requested.replace(/\u00a0/g, ' ');
+    return {
+        mode: spaceEquivalent ? 'space_equivalent' : 'normalized',
+        differences,
+        sourceExcerpt: escapeInvisibleText(actual),
+        requestedExcerpt: escapeInvisibleText(requested)
+    };
+}
 
 function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeContext = null, options = {}) {
     const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => { };
@@ -166,16 +236,20 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
             if (options?._resolutionCapture && resolved?.paragraph) {
                 const paragraph = resolved.paragraph;
                 const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
-                Object.assign(options._resolutionCapture, {
-                    resolvedBy: resolved.resolvedBy,
-                    resolvedTarget: {
+                Object.assign(options._resolutionCapture, {
+                    resolvedBy: resolved.resolvedBy,
+                    resolvedTarget: {
                         index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).indexOf(paragraph) + 1,
                         paragraphId: metadata?.paragraphId ?? getParagraphId(paragraph),
                         text: metadata?.text ?? getParagraphText(paragraph),
                         fingerprint: metadata?.fingerprint ?? createParagraphFingerprint(paragraph),
-                        inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl')
-                    }
-                });
+                        inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl'),
+                        targetTextMatch: describeTargetTextMatch(
+                            metadata?.text ?? getParagraphText(paragraph),
+                            options?.targetDescriptor?.exactText ?? targetText
+                        )
+                    }
+                });
             }
             return resolved;
         } catch (error) {
@@ -204,14 +278,18 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
         const metadata = paragraphMetadataIndex?.byParagraph?.get(paragraph) || null;
         Object.assign(options._resolutionCapture, {
             resolvedBy: resolved.resolvedBy,
-            resolvedTarget: {
+            resolvedTarget: {
                 index: metadata?.index ?? Array.from(xmlDoc.getElementsByTagNameNS(NS_W, 'p')).indexOf(paragraph) + 1,
                 paragraphId: metadata?.paragraphId ?? getParagraphId(paragraph),
                 text: metadata?.text ?? getParagraphText(paragraph),
                 fingerprint: metadata?.fingerprint ?? createParagraphFingerprint(paragraph),
-                inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl')
-            }
-        });
+                inTable: metadata?.inTable ?? !!findContainingWordElement(paragraph, 'tbl'),
+                targetTextMatch: describeTargetTextMatch(
+                    metadata?.text ?? getParagraphText(paragraph),
+                    options?.targetDescriptor?.exactText ?? targetText
+                )
+            }
+        });
     }
     return resolved;
 }
@@ -248,7 +326,7 @@ function preprocessRedlineTargetParagraph(targetParagraph) {
     removeProofErrNodes(targetParagraph);
 }
 
-function getDirectWordChild(element, localName) {
+function getDirectWordChild(element, localName) {
     if (!element) return null;
     return Array.from(element.childNodes || []).find(
         node => node && node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === localName
@@ -313,7 +391,7 @@ function buildInsertedListParagraph(xmlDoc, anchorParagraph, entry, revisionMeta
 
     const anchorPPr = getDirectWordChild(anchorParagraph, 'pPr');
     if (anchorPPr) {
-        paragraph.appendChild(anchorPPr.cloneNode(true));
+        paragraph.appendChild(clonePropertiesWithoutRevisionHistory(anchorPPr));
     }
     ensureListProperties(xmlDoc, paragraph, entry.ilvl, entry.numId);
 
@@ -329,7 +407,7 @@ function buildInsertedListParagraph(xmlDoc, anchorParagraph, entry, revisionMeta
     const anchorFirstRun = Array.from(anchorParagraph.getElementsByTagNameNS(NS_W, 'r'))[0] || null;
     const anchorRunPr = anchorFirstRun ? getDirectWordChild(anchorFirstRun, 'rPr') : null;
     if (anchorRunPr) {
-        run.appendChild(anchorRunPr.cloneNode(true));
+        run.appendChild(clonePropertiesWithoutRevisionHistory(anchorRunPr));
     }
 
     const textNode = createWordElement(xmlDoc, 'w:t');
@@ -402,18 +480,21 @@ function applyExplicitRangeListInsertions({
     normalizeBodySectionOrder(xmlDoc);
     return true;
 }
-function buildFallbackInsertedPlainParagraph(xmlDoc, text, revisionMetadata, author, options = {}) {
+function buildFallbackInsertedPlainParagraph(xmlDoc, text, revisionMetadata, author, options = {}) {
     const generateRedlines = options.generateRedlines !== false;
     const paragraph = createWordElement(xmlDoc, 'w:p');
     const run = createWordElement(xmlDoc, 'w:r');
     const textNode = createWordElement(xmlDoc, 'w:t');
     const safeText = String(text || '');
     if (/^\s|\s$/.test(safeText)) textNode.setAttribute('xml:space', 'preserve');
-    textNode.textContent = safeText;
-    run.appendChild(textNode);
-
-    if (generateRedlines) {
-        const metadata = revisionMetadata || createRevisionMetadata(author, xmlDoc);
+    textNode.textContent = safeText;
+    run.appendChild(textNode);
+
+    if (generateRedlines) {
+        if (options.trackParagraphMark === true) {
+            markParagraphMarkInserted(xmlDoc, paragraph, author);
+        }
+        const metadata = revisionMetadata || createRevisionMetadata(author, xmlDoc, 'ins');
         const ins = createWordElement(xmlDoc, 'w:ins');
         ins.setAttribute('w:id', String(metadata.id));
         ins.setAttribute('w:author', metadata.author);
@@ -430,12 +511,12 @@ function buildFallbackInsertedPlainParagraph(xmlDoc, text, revisionMetadata, aut
 function buildEmptyParagraphTemplateFromAnchor(xmlDoc, anchorParagraph) {
     const paragraph = createWordElement(xmlDoc, 'w:p');
     const anchorPPr = getDirectWordChild(anchorParagraph, 'pPr');
-    if (anchorPPr) paragraph.appendChild(anchorPPr.cloneNode(true));
+    if (anchorPPr) paragraph.appendChild(clonePropertiesWithoutRevisionHistory(anchorPPr));
 
     const run = createWordElement(xmlDoc, 'w:r');
     const anchorFirstRun = Array.from(anchorParagraph.getElementsByTagNameNS(NS_W, 'r'))[0] || null;
     const anchorRunPr = anchorFirstRun ? getDirectWordChild(anchorFirstRun, 'rPr') : null;
-    if (anchorRunPr) run.appendChild(anchorRunPr.cloneNode(true));
+    if (anchorRunPr) run.appendChild(clonePropertiesWithoutRevisionHistory(anchorRunPr));
 
     const textNode = createWordElement(xmlDoc, 'w:t');
     textNode.textContent = '';
@@ -444,13 +525,19 @@ function buildEmptyParagraphTemplateFromAnchor(xmlDoc, anchorParagraph) {
     return paragraph;
 }
 
-function wrapParagraphContentInInsertion(xmlDoc, paragraph, revisionMetadata, author) {
-    const wrappedParagraph = createWordElement(xmlDoc, 'w:p');
-    const pPr = getDirectWordChild(paragraph, 'pPr');
-    if (pPr) wrappedParagraph.appendChild(pPr.cloneNode(true));
-
-    const ins = createWordElement(xmlDoc, 'w:ins');
-    const metadata = revisionMetadata || createRevisionMetadata(author, xmlDoc);
+function wrapParagraphContentInInsertion(xmlDoc, paragraph, revisionMetadata, author, options = {}) {
+    const wrappedParagraph = createWordElement(xmlDoc, 'w:p');
+    const pPr = options.sanitizeParagraphProperties === true
+        ? createSanitizedRestorationPPr(xmlDoc, paragraph)
+        : clonePropertiesWithoutRevisionHistory(getDirectWordChild(paragraph, 'pPr'));
+    if (pPr) wrappedParagraph.appendChild(pPr);
+    if (options.paragraphId) wrappedParagraph.setAttributeNS(NS_W14, 'w14:paraId', options.paragraphId);
+    if (options.trackParagraphMark === true) {
+        markParagraphMarkInserted(xmlDoc, wrappedParagraph, author);
+    }
+
+    const ins = createWordElement(xmlDoc, 'w:ins');
+    const metadata = revisionMetadata || createRevisionMetadata(author, xmlDoc, 'ins');
     ins.setAttribute('w:id', String(metadata.id));
     ins.setAttribute('w:author', metadata.author);
     ins.setAttribute('w:date', metadata.date);
@@ -491,9 +578,9 @@ async function buildInsertedPlainParagraph(xmlDoc, anchorParagraph, text, revisi
         return buildFallbackInsertedPlainParagraph(
             xmlDoc,
             text,
-            revisionMetadata,
-            author,
-            { generateRedlines }
+            revisionMetadata,
+            author,
+            { ...options, generateRedlines }
         );
     }
 
@@ -501,10 +588,10 @@ async function buildInsertedPlainParagraph(xmlDoc, anchorParagraph, text, revisi
         return sourceParagraph;
     }
 
-    return wrapParagraphContentInInsertion(xmlDoc, sourceParagraph, revisionMetadata, author);
+    return wrapParagraphContentInInsertion(xmlDoc, sourceParagraph, revisionMetadata, author, options);
 }
 
-function collectNumberingIdsFromNodes(nodes) {
+function collectNumberingIdsFromNodes(nodes) {
     const ids = new Set();
     for (const node of nodes || []) {
         const numIdNodes = Array.from(node?.getElementsByTagNameNS?.('*', 'numId') || []);
@@ -516,7 +603,700 @@ function collectNumberingIdsFromNodes(nodes) {
         }
     }
     return Array.from(ids);
-}
+}
+
+function directDeletionCarrierText(carrier) {
+    return Array.from(carrier?.childNodes || []).reduce((text, child) => {
+        return text + (child?.nodeType === 1 && child.namespaceURI === NS_W && child.localName === 'r'
+            ? getRunContentPieces(child).map(piece => piece.text).join('')
+            : '');
+    }, '');
+}
+
+function findOccurrenceOffset(text, needle, occurrence) {
+    let from = 0;
+    let found = -1;
+    for (let index = 0; index < occurrence; index++) {
+        found = text.indexOf(needle, from);
+        if (found < 0) return -1;
+        from = found + Math.max(needle.length, 1);
+    }
+    return found;
+}
+
+function countNonOverlappingOccurrences(text, needle) {
+    if (!needle) return 0;
+    let count = 0;
+    let from = 0;
+    while (from <= text.length) {
+        const found = text.indexOf(needle, from);
+        if (found < 0) break;
+        count += 1;
+        from = found + needle.length;
+    }
+    return count;
+}
+
+function hasUnsupportedDeletionSplitMarkup(paragraph, carrier) {
+    const unsafeParagraphNames = new Set([
+        'commentRangeStart', 'commentRangeEnd', 'commentReference',
+        'bookmarkStart', 'bookmarkEnd', 'moveFromRangeStart', 'moveFromRangeEnd',
+        'moveToRangeStart', 'moveToRangeEnd'
+    ]);
+    if (Array.from(paragraph.getElementsByTagName?.('*') || []).some(node => unsafeParagraphNames.has(node.localName))) {
+        return true;
+    }
+    for (const child of Array.from(carrier?.childNodes || [])) {
+        if (child.nodeType !== 1) continue;
+        if (!(child.namespaceURI === NS_W && child.localName === 'r')) return true;
+        for (const runChild of Array.from(child.childNodes || [])) {
+            if (runChild.nodeType !== 1 || runChild.namespaceURI !== NS_W) continue;
+            if (!['rPr', 'delText', 't', 'tab', 'br', 'cr', 'noBreakHyphen', 'softHyphen'].includes(runChild.localName)) return true;
+        }
+    }
+    return false;
+}
+
+function insertedRunPropertiesAtDeletionOffset(carrier, localOffset) {
+    let offset = 0;
+    for (const child of Array.from(carrier?.childNodes || [])) {
+        if (!(child?.nodeType === 1 && child.namespaceURI === NS_W && child.localName === 'r')) continue;
+        const length = getRunTextLength(getRunContentPieces(child));
+        if (localOffset <= offset + length) {
+            return clonePropertiesWithoutRevisionHistory(getDirectWordChild(child, 'rPr'));
+        }
+        offset += length;
+    }
+    return null;
+}
+
+const RESTORATION_PPR_ALLOWLIST = new Set([
+    'pStyle', 'numPr', 'ind', 'jc', 'spacing', 'tabs',
+    'keepNext', 'keepLines', 'outlineLvl', 'contextualSpacing'
+]);
+
+function wordAttribute(node, localName) {
+    return node?.getAttribute?.(`w:${localName}`) || node?.getAttribute?.(localName) || '';
+}
+
+function normalizedAuthor(author) {
+    return String(author || '').trim().toLowerCase();
+}
+
+function directWordParagraphSibling(paragraph, direction = 'nextSibling') {
+    let cursor = paragraph?.[direction] || null;
+    while (cursor) {
+        if (cursor.nodeType === 1 && cursor.namespaceURI === NS_W && cursor.localName === 'p') return cursor;
+        cursor = cursor[direction] || null;
+    }
+    return null;
+}
+
+function createSanitizedRestorationPPr(xmlDoc, sourceParagraph) {
+    const sourcePPr = getDirectWordChild(sourceParagraph, 'pPr');
+    const pPr = createWordElement(xmlDoc, 'w:pPr');
+    if (!sourcePPr) return pPr;
+    for (const child of Array.from(sourcePPr.childNodes || [])) {
+        if (child.nodeType !== 1 || child.namespaceURI !== NS_W) continue;
+        if (!RESTORATION_PPR_ALLOWLIST.has(child.localName)) continue;
+        pPr.appendChild(xmlDoc.importNode(child, true));
+    }
+    return pPr;
+}
+
+function collectRestorationAnchorWarnings(sourceParagraph) {
+    const warnings = [];
+    const bookmarkNames = new Set();
+    for (const node of Array.from(sourceParagraph?.getElementsByTagNameNS?.(NS_W, 'bookmarkStart') || [])) {
+        const name = wordAttribute(node, 'name') || '(unnamed)';
+        bookmarkNames.add(name);
+    }
+    for (const name of bookmarkNames) warnings.push(`RESTORATION_DROPPED_BOOKMARK:${name}`);
+
+    const commentIds = new Set();
+    for (const localName of ['commentRangeStart', 'commentRangeEnd', 'commentReference']) {
+        for (const node of Array.from(sourceParagraph?.getElementsByTagNameNS?.(NS_W, localName) || [])) {
+            const id = wordAttribute(node, 'id');
+            if (id !== '') commentIds.add(id);
+        }
+    }
+    for (const id of commentIds) warnings.push(`RESTORATION_DROPPED_COMMENT:${id}`);
+    return warnings;
+}
+
+function removeRestorationAnchors(paragraph) {
+    const anchorNames = [
+        'bookmarkStart', 'bookmarkEnd',
+        'commentRangeStart', 'commentRangeEnd', 'commentReference'
+    ];
+    for (const localName of anchorNames) {
+        for (const node of Array.from(paragraph?.getElementsByTagNameNS?.(NS_W, localName) || [])) {
+            node.parentNode?.removeChild(node);
+        }
+    }
+    for (const run of Array.from(paragraph?.getElementsByTagNameNS?.(NS_W, 'r') || [])) {
+        const meaningful = Array.from(run.childNodes || []).some(child => (
+            child.nodeType === 1 && child.namespaceURI === NS_W && child.localName !== 'rPr'
+        ));
+        if (!meaningful) run.parentNode?.removeChild(run);
+    }
+}
+
+function buildRejectedRestorationTemplate(xmlDoc, sourceParagraph, serializer) {
+    const rejected = rejectTrackedChangesInOoxml(serializer.serializeToString(sourceParagraph), { allAuthors: true });
+    const parsed = parseOoxmlSafe(rejected.oxml, 'application/xml');
+    const rejectedParagraph = parsed.doc?.getElementsByTagNameNS?.(NS_W, 'p')?.[0] || null;
+    if (!rejectedParagraph) return null;
+
+    const paragraph = createWordElement(xmlDoc, 'w:p');
+    paragraph.appendChild(createSanitizedRestorationPPr(xmlDoc, sourceParagraph));
+    for (const child of Array.from(rejectedParagraph.childNodes || [])) {
+        if (child.nodeType === 1 && child.namespaceURI === NS_W && child.localName === 'pPr') continue;
+        paragraph.appendChild(xmlDoc.importNode(child, true));
+    }
+    removeRestorationAnchors(paragraph);
+    return paragraph;
+}
+
+async function editRestorationTemplate(xmlDoc, template, modifiedText, author, serializer) {
+    const originalText = extractCanonicalParagraphText(template);
+    if (originalText === modifiedText) return template;
+    const result = await applyRedlineToOxml(
+        serializer.serializeToString(template),
+        originalText,
+        modifiedText,
+        {
+            author,
+            generateRedlines: false,
+            structuredContent: false
+        }
+    );
+    if (result?.status === 'error' || typeof result?.oxml !== 'string') return null;
+    const extracted = extractReplacementNodes(result.oxml);
+    const paragraph = (extracted.replacementNodes || []).find(node => (
+        node?.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
+    ));
+    return paragraph ? xmlDoc.importNode(paragraph, true) : null;
+}
+
+function allocateFreshParagraphId(xmlDoc, operationSession) {
+    const used = new Set(getDocumentParagraphNodes(xmlDoc)
+        .map(paragraph => paragraph.getAttributeNS?.(NS_W14, 'paraId') || paragraph.getAttribute?.('w14:paraId') || '')
+        .filter(Boolean)
+        .map(value => value.toUpperCase()));
+    let candidate = null;
+    do {
+        candidate = operationSession?.generateParagraphId?.()
+            || (0x40000000 + used.size + 1).toString(16).toUpperCase();
+    } while (used.has(candidate.toUpperCase()));
+    return candidate;
+}
+
+function trackRestoredParagraph(xmlDoc, paragraph, author, operationSession) {
+    const root = xmlDoc.documentElement;
+    if (root && !root.getAttribute('xmlns:w14')) root.setAttribute('xmlns:w14', NS_W14);
+    return wrapParagraphContentInInsertion(xmlDoc, paragraph, null, author, {
+        paragraphId: allocateFreshParagraphId(xmlDoc, operationSession),
+        sanitizeParagraphProperties: true,
+        trackParagraphMark: true
+    });
+}
+
+function isInsertedParagraphByAuthor(paragraph, author) {
+    const pPr = getDirectWordChild(paragraph, 'pPr');
+    const rPr = getDirectWordChild(pPr, 'rPr');
+    const marker = getDirectWordChild(rPr, 'ins');
+    return !!marker && normalizedAuthor(wordAttribute(marker, 'author')) === normalizedAuthor(author);
+}
+
+function followingParagraphBlock(lastSource, count) {
+    const paragraphs = [];
+    let cursor = lastSource;
+    for (let i = 0; i < count; i++) {
+        cursor = directWordParagraphSibling(cursor, 'nextSibling');
+        if (!cursor) return [];
+        paragraphs.push(cursor);
+    }
+    return paragraphs;
+}
+
+function paragraphTextVector(oxml) {
+    const parsed = parseOoxmlSafe(oxml, 'application/xml');
+    if (parsed.error || !parsed.doc) return null;
+    return getDocumentParagraphNodes(parsed.doc).map(paragraph => extractCanonicalParagraphText(paragraph));
+}
+
+function sameTextVector(left, right) {
+    return Array.isArray(left) && Array.isArray(right)
+        && left.length === right.length
+        && left.every((value, index) => value === right[index]);
+}
+
+function lifecycleTextVector(oxml, action) {
+    const result = action === 'accept'
+        ? acceptTrackedChangesInOoxml(oxml, { allAuthors: true })
+        : rejectTrackedChangesInOoxml(oxml, { allAuthors: true });
+    return paragraphTextVector(result.oxml);
+}
+
+function buildExpectedRestorationDocument(beforeXml, sourceStartIndex, existingIndexes, templates) {
+    const parsed = parseOoxmlSafe(beforeXml, 'application/xml');
+    if (parsed.error || !parsed.doc) return null;
+    const expectedDoc = parsed.doc;
+    const originalParagraphs = getDocumentParagraphNodes(expectedDoc);
+    const lastSource = originalParagraphs[sourceStartIndex + templates.length - 1] || null;
+    if (!lastSource?.parentNode) return null;
+
+    for (const index of [...existingIndexes].sort((a, b) => b - a)) {
+        const paragraph = originalParagraphs[index];
+        paragraph?.parentNode?.removeChild(paragraph);
+    }
+    const insertionPoint = lastSource.nextSibling;
+    for (const template of templates) {
+        lastSource.parentNode.insertBefore(expectedDoc.importNode(template, true), insertionPoint);
+    }
+    return createSerializer().serializeToString(expectedDoc);
+}
+
+function verifyParagraphRestorationLifecycle(beforeXml, outputXml, sourceStartIndex, existingIndexes, templates, insertedParagraphs = []) {
+    const baselineValidation = validateRedlineOoxml(beforeXml);
+    const outputValidation = validateRedlineOoxml(outputXml);
+    const generatedIssues = subtractValidationIssueMultiset(outputValidation.issues, baselineValidation.issues);
+    const envelopeIssues = insertedParagraphs.flatMap(paragraph => (
+        validateRedlineOoxml(createSerializer().serializeToString(paragraph)).issues
+            .filter(issue => issue.severity === 'error')
+    ));
+    const generatedErrors = validationErrors(generatedIssues);
+    if (generatedErrors.length > 0 || envelopeIssues.length > 0) {
+        return {
+            valid: false,
+            stage: 'validation',
+            code: 'GENERATED_OOXML_INVALID',
+            generatedIssues,
+            envelopeIssues,
+            message: [...generatedErrors, ...envelopeIssues].map(issue => issue.message).join(' ')
+        };
+    }
+
+    const expectedXml = buildExpectedRestorationDocument(beforeXml, sourceStartIndex, existingIndexes, templates);
+    if (!expectedXml) return { valid: false, stage: 'expected-document', message: 'Could not construct the restoration lifecycle oracle.' };
+
+    const comparisons = [
+        ['current', paragraphTextVector(expectedXml), paragraphTextVector(outputXml)],
+        ['accept-all', lifecycleTextVector(expectedXml, 'accept'), lifecycleTextVector(outputXml, 'accept')],
+        ['reject-all', lifecycleTextVector(beforeXml, 'reject'), lifecycleTextVector(outputXml, 'reject')]
+    ];
+    for (const [stage, expected, actual] of comparisons) {
+        if (!sameTextVector(expected, actual)) {
+            return {
+                valid: false,
+                stage,
+                expected,
+                actual,
+                message: `Paragraph restoration ${stage} lifecycle text did not match the expected body-scoped paragraph sequence.`
+            };
+        }
+    }
+    return { valid: true };
+}
+
+/**
+ * Inserts a new tracked run at an exact offset inside text visible only in the
+ * rejected view of a wholly deleted paragraph. The foreign deletion is split,
+ * never rewritten or re-authored.
+ */
+export async function insertIntoRejectedDeletedText(
+    documentXml,
+    targetText,
+    anchor,
+    modified,
+    author,
+    targetRef = null,
+    runtimeContext = null,
+    options = {}
+) {
+    const { serializer, xmlDoc, operationSession } = resolveMutationDocument(documentXml, options);
+    if (!xmlDoc) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message: 'Could not parse document OOXML.' }
+        };
+    }
+
+    const resolved = resolveTargetParagraph(xmlDoc, targetText, targetRef, 'insert', runtimeContext, options);
+    if (resolved?.error || !resolved?.paragraph) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: resolved?.error || { code: 'TARGET_NOT_FOUND', message: 'Rejected-view insertion target was not found.' }
+        };
+    }
+
+    const paragraph = resolved.paragraph;
+    const state = inspectForeignDeletedParagraphTarget(paragraph, author);
+    if (!state.matches) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'REJECTED_INSERTION_STATE_REQUIRED',
+                message: 'Rejected-view insertion requires a wholly deleted paragraph owned by another author.'
+            }
+        };
+    }
+    const structuralRefusal = getParagraphRestorationRefusal(paragraph, { requireFollowingParagraph: false });
+    if (structuralRefusal) {
+        return { documentXml, hasChanges: false, status: 'error', error: structuralRefusal };
+    }
+    if (/\r|\n/.test(modified)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_PARAGRAPH_BOUNDARY',
+                message: 'Rejected-view insertion supports run-level text only; use restore for paragraph boundaries.'
+            }
+        };
+    }
+
+    const rejectedText = extractCanonicalParagraphText(paragraph, { revisionView: 'rejected' });
+    if (!anchor.occurrenceExplicit && countNonOverlappingOccurrences(rejectedText, anchor.exactText) > 1) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'AMBIGUOUS_ANCHOR',
+                message: 'The rejected-view insertion anchor is repeated; provide anchor.occurrence explicitly.'
+            }
+        };
+    }
+    const anchorStart = findOccurrenceOffset(rejectedText, anchor.exactText, anchor.occurrence);
+    if (anchorStart < 0) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'ANCHOR_NOT_FOUND', message: 'The rejected-view insertion anchor was not found at the requested occurrence.' }
+        };
+    }
+    const insertionOffset = anchorStart + anchor.offset;
+    const carriers = Array.from(paragraph.childNodes || []).filter(
+        node => node?.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'del'
+    );
+    if (carriers.some(carrier => hasUnsupportedDeletionSplitMarkup(paragraph, carrier))) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_REVISION_BOUNDARY',
+                message: 'The rejected-view insertion boundary contains comments, bookmarks, fields, hyperlinks, moves, or non-text run markup that cannot be split safely.'
+            }
+        };
+    }
+    let carrierStart = 0;
+    let targetCarrier = null;
+    let carrierOffset = 0;
+    for (const carrier of carriers) {
+        const length = directDeletionCarrierText(carrier).length;
+        if (insertionOffset >= carrierStart && insertionOffset <= carrierStart + length) {
+            targetCarrier = carrier;
+            carrierOffset = insertionOffset - carrierStart;
+            break;
+        }
+        carrierStart += length;
+    }
+    if (!targetCarrier || carriers.map(directDeletionCarrierText).join('') !== rejectedText) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_REVISION_NESTING',
+                message: 'The rejected-view anchor is not contained in a supported direct deletion carrier.'
+            }
+        };
+    }
+
+    const runProperties = insertedRunPropertiesAtDeletionOffset(targetCarrier, carrierOffset);
+    const { leftCarrier, rightCarrier } = splitTrackChangeCarrier(
+        xmlDoc,
+        targetCarrier,
+        carrierOffset,
+        options._revisionIdAllocator || null
+    );
+    const insertion = createWordElement(xmlDoc, 'w:ins');
+    const metadata = createRevisionMetadata(author, options._revisionIdAllocator || xmlDoc, 'ins');
+    insertion.setAttribute('w:id', String(metadata.id));
+    insertion.setAttribute('w:author', metadata.author);
+    insertion.setAttribute('w:date', metadata.date);
+    const run = createWordElement(xmlDoc, 'w:r');
+    if (runProperties) run.appendChild(runProperties);
+    const textNode = createWordElement(xmlDoc, 'w:t');
+    if (/^\s|\s$/.test(modified)) textNode.setAttribute('xml:space', 'preserve');
+    textNode.textContent = modified;
+    run.appendChild(textNode);
+    insertion.appendChild(run);
+
+    const parent = targetCarrier.parentNode;
+    if (leftCarrier) parent.insertBefore(leftCarrier, targetCarrier);
+    parent.insertBefore(insertion, targetCarrier);
+    if (rightCarrier) parent.insertBefore(rightCarrier, targetCarrier);
+    options?._mutationRemovedNodes?.push(targetCarrier);
+    parent.removeChild(targetCarrier);
+    options?._mutationLiveNodes?.push(paragraph, insertion);
+    operationSession?.invalidateParagraphMetadata?.();
+
+    const outputXml = serializer.serializeToString(xmlDoc);
+    const outputRejected = extractCanonicalParagraphText(paragraph, { revisionView: 'rejected' });
+    const outputAccepted = extractCanonicalParagraphText(paragraph, { revisionView: 'accepted' });
+    if (outputRejected !== rejectedText || !outputAccepted.includes(modified)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                message: 'Rejected-view insertion did not preserve the deleted source and expose the requested inserted text.'
+            }
+        };
+    }
+    return { documentXml: outputXml, hasChanges: true, status: 'ok' };
+}
+
+/**
+ * Materializes an explicit counterproposal for one or more paragraphs wholly
+ * deleted (content and paragraph mark) by another author.
+ */
+export async function restoreDeletedParagraphByExactText(
+    documentXml,
+    targetText,
+    modified,
+    author,
+    targetRef = null,
+    targetEndRef = null,
+    runtimeContext = null,
+    options = {}
+) {
+    const { serializer, xmlDoc, operationSession } = resolveMutationDocument(documentXml, options);
+    if (!xmlDoc) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message: 'Could not parse document OOXML.' }
+        };
+    }
+
+    const resolved = resolveTargetParagraph(xmlDoc, targetText, targetRef, 'restore', runtimeContext, options);
+    if (resolved?.error || !resolved?.paragraph) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: resolved?.error || { code: 'TARGET_NOT_FOUND', message: 'Restoration target paragraph not found.' }
+        };
+    }
+
+    const firstSource = resolved.paragraph;
+    let sourceParagraphs = [firstSource];
+    if (targetEndRef) {
+        sourceParagraphs = resolveParagraphRangeByRefs(xmlDoc, targetRef, targetEndRef, {
+            opType: 'restore',
+            targetRefSnapshot: runtimeContext?.targetRefSnapshot || null,
+            onInfo: options.onInfo,
+            onWarn: options.onWarn
+        });
+    } else if (options.targetEndDescriptor) {
+        const endResolved = resolveTargetParagraph(
+            xmlDoc,
+            options.targetEndDescriptor.text,
+            options.targetEndDescriptor.index,
+            'restore',
+            runtimeContext,
+            { ...options, targetDescriptor: options.targetEndDescriptor }
+        );
+        const allParagraphs = endResolved?.paragraph ? getDocumentParagraphNodes(xmlDoc) : [];
+        const startIndex = allParagraphs.indexOf(firstSource);
+        const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
+        sourceParagraphs = startIndex >= 0 && endIndex >= startIndex
+            ? allParagraphs.slice(startIndex, endIndex + 1)
+            : null;
+    }
+    if (!Array.isArray(sourceParagraphs) || sourceParagraphs.length === 0 || sourceParagraphs[0] !== firstSource) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'RESTORATION_COUNT_MISMATCH',
+                message: 'The restoration range could not be resolved as a contiguous paragraph block.'
+            }
+        };
+    }
+
+    const replacements = Array.isArray(modified) ? modified.map(String) : [String(modified || '')];
+    if (replacements.length !== sourceParagraphs.length || replacements.some(text => text.length === 0)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'RESTORATION_COUNT_MISMATCH',
+                message: `Restoration requires exactly one non-empty replacement per source paragraph (${sourceParagraphs.length} expected, ${replacements.length} received).`
+            }
+        };
+    }
+
+    const parent = firstSource.parentNode;
+    if (!parent || sourceParagraphs.some(paragraph => paragraph.parentNode !== parent)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'UNSAFE_PARAGRAPH_PLACEMENT',
+                message: 'Restoration source paragraphs must be a contiguous block in one structural container.'
+            }
+        };
+    }
+
+    for (const paragraph of sourceParagraphs) {
+        const structuralRefusal = getParagraphRestorationRefusal(paragraph);
+        if (structuralRefusal?.code === 'UNSUPPORTED_MOVE_REVISION') {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: structuralRefusal
+            };
+        }
+        const state = inspectForeignDeletedParagraphTarget(paragraph, author);
+        if (!state.matches) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: 'RESTORATION_STATE_REQUIRED',
+                    message: state.hasParagraphMarkDeletion && !state.foreignParagraphMarkDeletion
+                        ? 'Explicit cross-author restoration does not apply to a paragraph deleted by the current author; use merge-same-author.'
+                        : 'Explicit restoration requires a foreign paragraph-mark deletion with every pre-existing content node deleted.',
+                    ...(state.ownerAuthor ? { ownerAuthor: state.ownerAuthor } : {})
+                }
+            };
+        }
+        const refusal = structuralRefusal || getParagraphRestorationRefusal(paragraph);
+        if (refusal) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: refusal
+            };
+        }
+    }
+
+    const lastSource = sourceParagraphs[sourceParagraphs.length - 1];
+    const existingBlock = followingParagraphBlock(lastSource, sourceParagraphs.length);
+    const hasExistingRestoration = existingBlock.length === sourceParagraphs.length
+        && existingBlock.every(paragraph => isInsertedParagraphByAuthor(paragraph, author));
+    if (
+        hasExistingRestoration
+        && existingBlock.every((paragraph, index) => extractCanonicalParagraphText(paragraph) === replacements[index])
+    ) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'no-op',
+            warnings: ['An identical same-author paragraph restoration already exists.']
+        };
+    }
+
+    const beforeXml = serializer.serializeToString(xmlDoc);
+    const beforeParagraphs = getDocumentParagraphNodes(xmlDoc);
+    const sourceStartIndex = beforeParagraphs.indexOf(firstSource);
+    const existingIndexes = hasExistingRestoration
+        ? existingBlock.map(paragraph => beforeParagraphs.indexOf(paragraph))
+        : [];
+    const templates = [];
+    const warnings = [];
+    for (let index = 0; index < sourceParagraphs.length; index++) {
+        const source = sourceParagraphs[index];
+        warnings.push(...collectRestorationAnchorWarnings(source));
+        const template = buildRejectedRestorationTemplate(xmlDoc, source, serializer);
+        const edited = template
+            ? await editRestorationTemplate(xmlDoc, template, replacements[index], author, serializer)
+            : null;
+        if (!edited) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: 'PATCH_ROUNDTRIP_MISMATCH',
+                    message: `Could not reconstruct restoration paragraph ${index + 1} from its rejected revision view.`
+                }
+            };
+        }
+        templates.push(edited);
+    }
+
+    const insertedParagraphs = templates.map(template => {
+        const paragraph = xmlDoc.importNode(template, true);
+        return trackRestoredParagraph(xmlDoc, paragraph, author, operationSession);
+    });
+    const insertionPoint = lastSource.nextSibling;
+    for (const paragraph of insertedParagraphs) parent.insertBefore(paragraph, insertionPoint);
+    if (hasExistingRestoration) {
+        for (const paragraph of existingBlock) {
+            options?._mutationRemovedNodes?.push(paragraph);
+            paragraph.parentNode?.removeChild(paragraph);
+        }
+    }
+    options?._mutationLiveNodes?.push(...insertedParagraphs);
+    normalizeBodySectionOrder(xmlDoc);
+
+    const outputXml = serializer.serializeToString(xmlDoc);
+    const oracle = verifyParagraphRestorationLifecycle(
+        beforeXml,
+        outputXml,
+        sourceStartIndex,
+        existingIndexes,
+        templates,
+        insertedParagraphs
+    );
+    if (!oracle.valid) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: oracle.code || 'PATCH_ROUNDTRIP_MISMATCH',
+                message: oracle.message,
+                stage: oracle.stage,
+                ...(oracle.generatedIssues ? { generatedIssues: oracle.generatedIssues } : {}),
+                ...(oracle.envelopeIssues ? { envelopeIssues: oracle.envelopeIssues } : {}),
+                ...(oracle.expected ? { expected: oracle.expected } : {}),
+                ...(oracle.actual ? { actual: oracle.actual } : {})
+            }
+        };
+    }
+
+    return {
+        documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
+        hasChanges: true,
+        status: 'ok',
+        numberingXml: null,
+        ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
+    };
+}
 
 async function tryExplicitDecimalHeaderListConversion({
     xmlDoc,
@@ -819,8 +1599,25 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
             error: resolved?.error || { code: 'TARGET_NOT_FOUND', message: 'Target paragraph not found.' }
         };
     }
-    const targetParagraph = resolved.paragraph;
-    preprocessRedlineTargetParagraph(targetParagraph);
+    const targetParagraph = resolved.paragraph;
+    if (typeof modifiedText === 'string' && modifiedText.length > 0) {
+        const resurrectionTarget = inspectForeignDeletedParagraphTarget(targetParagraph, author);
+        if (resurrectionTarget.matches) {
+            const ownerAuthor = resurrectionTarget.ownerAuthor || 'unattributed';
+            return {
+                documentXml,
+                hasChanges: false,
+                numberingXml: null,
+                status: 'error',
+                error: {
+                    code: 'FOREIGN_PARAGRAPH_MARK_DELETION',
+                    message: `Refusing to add visible text to a paragraph whose paragraph mark is deleted by another author (${ownerAuthor}). Use explicit paragraph restoration when supported.`,
+                    ownerAuthor
+                }
+            };
+        }
+    }
+    preprocessRedlineTargetParagraph(targetParagraph);
     const currentParagraphText = getParagraphText(targetParagraph);
     if (modifiedText === '') {
         const commentIds = getCommentIdsInElement(targetParagraph);
@@ -1235,8 +2032,8 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
                 ? explicitRangeParagraphs.map(paragraph => getParagraphText(paragraph)).join('\n')
                 : (inferredTableRangeParagraphs
                     ? inferredTableRangeParagraphs.map(paragraph => getParagraphText(paragraph)).join('\n')
-                    : (currentParagraphText || targetText))
-        );
+                    : (currentParagraphText || targetText))
+        );
     const scopedXml = useTableScope
         ? serializer.serializeToString(containingTable)
         : (