@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/engine/surgical-diff-application.js

@@ -6,6 +6,7 @@ import {
     createTextRunWithRPrElement,
     injectFormattingToRPr
 } from './run-builders.js';
+import { createRevisionMetadata } from '../core/types.js';
 import {
     createRunFromPieces,
     getRunContentPieces,
@@ -17,9 +18,12 @@ import {
     findContainingSpan,
     findFirstSpanEndingAt,
     findLastSpanEndingBeforeOrAt,
-    forEachOverlappingSpan
+    forEachOverlappingSpan,
+    describeInsertionBoundary
 } from './surgical-spans.js';
 import { extractFormatFromRPr } from './rpr-helpers.js';
+import { isWordElement } from '../core/word-xml.js';
+import { NS_W } from '../core/types.js';
 
 export function reconcileFormattingForTextSpan(xmlDoc, span, start, end, applicableHints, author, generateRedlines) {
     // Plain modified text carries no negative formatting instruction. Preserve
@@ -67,7 +71,7 @@ export function reconcileFormattingForTextSpan(xmlDoc, span, start, end, applica
     return true;
 }
 
-export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, generateRedlines) {
+export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, generateRedlines, revisionMetadata = null) {
     const spans = [];
     forEachOverlappingSpan(spanIndex, startPos, endPos, span => {
         spans.push(span);
@@ -83,6 +87,7 @@ export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, gener
     });
 
     let changed = false;
+    let usedDelMetadata = false;
     spansByRun.forEach((runSpans, runElement) => {
         const parent = runElement.parentNode;
         if (!parent) return;
@@ -114,7 +119,11 @@ export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, gener
 
         if (generateRedlines && deletedPieces.length > 0) {
             const delRun = createRunFromPieces(xmlDoc, deletedPieces, runSpans[0].rPr);
-            const delWrapper = createTrackChange(xmlDoc, 'del', delRun, author);
+            const metadata = revisionMetadata
+                ? (usedDelMetadata ? { ...revisionMetadata, id: createRevisionMetadata(author, xmlDoc).id } : revisionMetadata)
+                : null;
+            usedDelMetadata = true;
+            const delWrapper = createTrackChange(xmlDoc, 'del', delRun, author, metadata);
             parent.insertBefore(delWrapper, runElement);
         }
 
@@ -126,63 +135,239 @@ export function processDelete(xmlDoc, spanIndex, startPos, endPos, author, gener
     return changed;
 }
 
-export function processInsert(xmlDoc, spanIndex, pos, text, author, formatHints = [], insertOffset = 0, generateRedlines = true, fallbackParagraph = null) {
-    let targetSpan = findContainingSpan(spanIndex, pos);
+export function processInsert(xmlDoc, spanIndex, pos, text, author, formatHints = [], insertOffset = 0, generateRedlines = true, fallbackParagraph = null, revisionMetadata = null, affinity = null) {
+    if (!affinity) {
+        let targetSpan = findContainingSpan(spanIndex, pos);
 
-    if (!targetSpan && pos > 0) {
-        targetSpan = findFirstSpanEndingAt(spanIndex, pos);
+        if (!targetSpan && pos > 0) {
+            targetSpan = findFirstSpanEndingAt(spanIndex, pos);
+        }
+
+        if (!targetSpan && pos > 0) {
+            targetSpan = findLastSpanEndingBeforeOrAt(spanIndex, pos);
+        }
+
+        if (!targetSpan && spanIndex.spans.length > 0) {
+            targetSpan = spanIndex.spans[spanIndex.spans.length - 1];
+        }
+
+        if (!targetSpan) {
+            if (!fallbackParagraph) return false;
+            insertTextRuns(xmlDoc, fallbackParagraph, null, text, null, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+            return true;
+        }
+
+        const parent = targetSpan.runElement.parentNode;
+        if (!parent) {
+            if (!fallbackParagraph) return false;
+            insertTextRuns(xmlDoc, fallbackParagraph, null, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+            return true;
+        }
+
+        const pieces = getRunContentPieces(targetSpan.runElement);
+        const targetPiece = pieces.find(piece => piece.node === targetSpan.textElement);
+        const localInsertPos = targetPiece
+            ? targetPiece.start + Math.max(0, Math.min(pos - targetSpan.charStart, targetSpan.charEnd - targetSpan.charStart))
+            : (pos <= targetSpan.charStart ? 0 : getRunTextLength(pieces));
+
+        if (localInsertPos > 0 && localInsertPos < getRunTextLength(pieces)) {
+            const beforePieces = sliceRunPieces(xmlDoc, pieces, 0, localInsertPos, false);
+            const afterPieces = sliceRunPieces(xmlDoc, pieces, localInsertPos, getRunTextLength(pieces), false);
+
+            insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, beforePieces, targetSpan.rPr);
+            insertTextRuns(xmlDoc, parent, targetSpan.runElement, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+            insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, afterPieces, targetSpan.rPr);
+            parent.removeChild(targetSpan.runElement);
+            return true;
+        }
+
+        const referenceNode = pos <= targetSpan.charStart ? targetSpan.runElement : targetSpan.runElement.nextSibling;
+        insertTextRuns(xmlDoc, parent, referenceNode, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+        return true;
     }
 
-    if (!targetSpan && pos > 0) {
-        targetSpan = findLastSpanEndingBeforeOrAt(spanIndex, pos);
+    const boundary = describeInsertionBoundary(spanIndex, pos, fallbackParagraph);
+
+    // Validate hyperlink affinity
+    const isLeftInHyperlink = boundary.leftSpan && isWordElement(boundary.leftSpan.runElement?.parentNode, 'hyperlink');
+    const isRightInHyperlink = boundary.rightSpan && isWordElement(boundary.rightSpan.runElement?.parentNode, 'hyperlink');
+    const isContainingInHyperlink = boundary.containingSpan && isWordElement(boundary.containingSpan.runElement?.parentNode, 'hyperlink');
+
+    if (affinity.hyperlink === 'outside') {
+        if (boundary.isInterior && isContainingInHyperlink) {
+            return {
+                error: {
+                    code: 'UNSUPPORTED_INSERTION_AFFINITY',
+                    message: 'Cannot place insertion outside hyperlink from strictly interior position.'
+                }
+            };
+        }
+    } else if (affinity.hyperlink === 'inside') {
+        if (!isLeftInHyperlink && !isRightInHyperlink && !isContainingInHyperlink) {
+            return {
+                error: {
+                    code: 'UNSUPPORTED_INSERTION_AFFINITY',
+                    message: 'Cannot place insertion inside hyperlink when no hyperlink is present at boundary.'
+                }
+            };
+        }
     }
 
-    if (!targetSpan && spanIndex.spans.length > 0) {
-        targetSpan = spanIndex.spans[spanIndex.spans.length - 1];
+    // Determine formatting (baseRPr)
+    let baseRPr = null;
+    if (affinity.formatting === 'none') {
+        baseRPr = null;
+    } else if (affinity.formatting === 'right') {
+        baseRPr = boundary.rightSpan?.rPr || null;
+    } else if (affinity.formatting === 'left') {
+        baseRPr = boundary.leftSpan?.rPr || null;
+    } else {
+        baseRPr = (boundary.containingSpan || boundary.leftSpan || boundary.rightSpan)?.rPr || null;
     }
 
-    if (!targetSpan) {
-        if (!fallbackParagraph) return false;
-        insertTextRuns(xmlDoc, fallbackParagraph, null, text, null, author, formatHints, insertOffset, generateRedlines);
-        return true;
+    // Check interior of a run
+    if (boundary.isInterior) {
+        const targetSpan = boundary.containingSpan;
+        const parent = targetSpan.runElement.parentNode || fallbackParagraph;
+        if (!parent) return false;
+
+        const pieces = getRunContentPieces(targetSpan.runElement);
+        const targetPiece = pieces.find(piece => piece.node === targetSpan.textElement);
+        const localInsertPos = targetPiece
+            ? targetPiece.start + Math.max(0, Math.min(pos - targetSpan.charStart, targetSpan.charEnd - targetSpan.charStart))
+            : (pos <= targetSpan.charStart ? 0 : getRunTextLength(pieces));
+
+        if (localInsertPos > 0 && localInsertPos < getRunTextLength(pieces)) {
+            const beforePieces = sliceRunPieces(xmlDoc, pieces, 0, localInsertPos, false);
+            const afterPieces = sliceRunPieces(xmlDoc, pieces, localInsertPos, getRunTextLength(pieces), false);
+
+            insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, beforePieces, targetSpan.rPr);
+            insertTextRuns(xmlDoc, parent, targetSpan.runElement, text, baseRPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
+            insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, afterPieces, targetSpan.rPr);
+            parent.removeChild(targetSpan.runElement);
+            return true;
+        }
+    }
+
+    // Boundary between runs or at start/end of paragraph
+    let parent = null;
+    let referenceNode = null;
+
+    if (affinity.hyperlink === 'outside') {
+        if (isRightInHyperlink) {
+            const hyperlinkNode = boundary.rightSpan.runElement.parentNode;
+            parent = hyperlinkNode.parentNode || fallbackParagraph;
+            referenceNode = hyperlinkNode;
+        } else if (isLeftInHyperlink) {
+            const hyperlinkNode = boundary.leftSpan.runElement.parentNode;
+            parent = hyperlinkNode.parentNode || fallbackParagraph;
+            referenceNode = hyperlinkNode.nextSibling;
+        }
+    } else if (affinity.hyperlink === 'inside') {
+        if (isRightInHyperlink) {
+            parent = boundary.rightSpan.runElement.parentNode;
+            referenceNode = boundary.rightSpan.runElement;
+        } else if (isLeftInHyperlink) {
+            parent = boundary.leftSpan.runElement.parentNode;
+            referenceNode = boundary.leftSpan.runElement.nextSibling;
+        }
     }
 
-    const parent = targetSpan.runElement.parentNode;
     if (!parent) {
-        if (!fallbackParagraph) return false;
-        insertTextRuns(xmlDoc, fallbackParagraph, null, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines);
-        return true;
+        if (boundary.rightSpan) {
+            parent = boundary.rightSpan.runElement.parentNode || fallbackParagraph;
+            referenceNode = boundary.rightSpan.runElement;
+        } else if (boundary.leftSpan) {
+            parent = boundary.leftSpan.runElement.parentNode || fallbackParagraph;
+            referenceNode = boundary.leftSpan.runElement.nextSibling;
+        } else {
+            parent = fallbackParagraph;
+            referenceNode = null;
+        }
     }
 
-    const pieces = getRunContentPieces(targetSpan.runElement);
-    const targetPiece = pieces.find(piece => piece.node === targetSpan.textElement);
-    const localInsertPos = targetPiece
-        ? targetPiece.start + Math.max(0, Math.min(pos - targetSpan.charStart, targetSpan.charEnd - targetSpan.charStart))
-        : (pos <= targetSpan.charStart ? 0 : getRunTextLength(pieces));
+    // Check bookmark range affinity
+    if (affinity.bookmark && parent) {
+        if (affinity.bookmark === 'outside') {
+            if (referenceNode && isWordElement(referenceNode.previousSibling, 'bookmarkStart')) {
+                referenceNode = referenceNode.previousSibling;
+            }
+            if (boundary.leftSpan && isWordElement(boundary.leftSpan.runElement.nextSibling, 'bookmarkEnd')) {
+                referenceNode = boundary.leftSpan.runElement.nextSibling.nextSibling;
+            }
+        } else if (affinity.bookmark === 'inside') {
+            if (referenceNode && isWordElement(referenceNode, 'bookmarkStart')) {
+                referenceNode = referenceNode.nextSibling;
+            }
+            if (boundary.leftSpan && isWordElement(boundary.leftSpan.runElement.nextSibling, 'bookmarkEnd')) {
+                referenceNode = boundary.leftSpan.runElement.nextSibling;
+            }
+        }
+    }
+
+    // Check comment range affinity
+    if (affinity.comment && parent) {
+        if (affinity.comment === 'outside') {
+            if (referenceNode && isWordElement(referenceNode.previousSibling, 'commentRangeStart')) {
+                referenceNode = referenceNode.previousSibling;
+            }
+            if (boundary.leftSpan && isWordElement(boundary.leftSpan.runElement.nextSibling, 'commentRangeEnd')) {
+                let afterComment = boundary.leftSpan.runElement.nextSibling.nextSibling;
+                if (afterComment && (isWordElement(afterComment, 'commentReference') || isWordElement(afterComment, 'r'))) {
+                    const hasCRef = Array.from(afterComment.childNodes || []).some(n => isWordElement(n, 'commentReference'));
+                    if (hasCRef) afterComment = afterComment.nextSibling;
+                }
+                referenceNode = afterComment;
+            }
+        } else if (affinity.comment === 'inside') {
+            if (referenceNode && isWordElement(referenceNode, 'commentRangeStart')) {
+                referenceNode = referenceNode.nextSibling;
+            }
+            if (boundary.leftSpan && isWordElement(boundary.leftSpan.runElement.nextSibling, 'commentRangeEnd')) {
+                referenceNode = boundary.leftSpan.runElement.nextSibling;
+            }
+        }
+    }
 
-    if (localInsertPos > 0 && localInsertPos < getRunTextLength(pieces)) {
-        const beforePieces = sliceRunPieces(xmlDoc, pieces, 0, localInsertPos, false);
-        const afterPieces = sliceRunPieces(xmlDoc, pieces, localInsertPos, getRunTextLength(pieces), false);
+    // Check revision affinity (coalesce_same_author)
+    if (generateRedlines && affinity.revision === 'coalesce_same_author') {
+        let insElem = null;
+        let insRef = null;
+
+        if (boundary.leftSpan && isWordElement(boundary.leftSpan.runElement.parentNode, 'ins')) {
+            const candidate = boundary.leftSpan.runElement.parentNode;
+            const candAuthor = candidate.getAttribute('w:author') || candidate.getAttributeNS(NS_W, 'author');
+            if (candAuthor === author) {
+                insElem = candidate;
+                insRef = boundary.leftSpan.runElement.nextSibling;
+            }
+        } else if (boundary.rightSpan && isWordElement(boundary.rightSpan.runElement.parentNode, 'ins')) {
+            const candidate = boundary.rightSpan.runElement.parentNode;
+            const candAuthor = candidate.getAttribute('w:author') || candidate.getAttributeNS(NS_W, 'author');
+            if (candAuthor === author) {
+                insElem = candidate;
+                insRef = boundary.rightSpan.runElement;
+            }
+        }
 
-        insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, beforePieces, targetSpan.rPr);
-        insertTextRuns(xmlDoc, parent, targetSpan.runElement, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines);
-        insertRunPiecesBefore(xmlDoc, parent, targetSpan.runElement, afterPieces, targetSpan.rPr);
-        parent.removeChild(targetSpan.runElement);
-        return true;
+        if (insElem) {
+            const insRun = createTextRun(xmlDoc, text, baseRPr, false);
+            insElem.insertBefore(insRun, insRef);
+            return true;
+        }
     }
 
-    const referenceNode = pos <= targetSpan.charStart ? targetSpan.runElement : targetSpan.runElement.nextSibling;
-    insertTextRuns(xmlDoc, parent, referenceNode, text, targetSpan.rPr, author, formatHints, insertOffset, generateRedlines);
+    insertTextRuns(xmlDoc, parent, referenceNode, text, baseRPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata);
     return true;
 }
 
-function insertTextRuns(xmlDoc, parent, referenceNode, text, baseRPr, author, formatHints, insertOffset, generateRedlines) {
+function insertTextRuns(xmlDoc, parent, referenceNode, text, baseRPr, author, formatHints, insertOffset, generateRedlines, revisionMetadata = null) {
     const applicableHints = getApplicableFormatHints(formatHints, insertOffset, insertOffset + text.length);
 
     if (applicableHints.length === 0) {
         const insRun = createTextRun(xmlDoc, text, baseRPr, false);
         if (generateRedlines) {
-            const insWrapper = createTrackChange(xmlDoc, 'ins', insRun, author);
+            const insWrapper = createTrackChange(xmlDoc, 'ins', insRun, author, revisionMetadata);
             parent.insertBefore(insWrapper, referenceNode);
         } else {
             parent.insertBefore(insRun, referenceNode);
@@ -193,7 +378,7 @@ function insertTextRuns(xmlDoc, parent, referenceNode, text, baseRPr, author, fo
     const runs = createFormattedRuns(xmlDoc, text, baseRPr, applicableHints, insertOffset, author, generateRedlines);
 
     if (generateRedlines) {
-        const insWrapper = createTrackChange(xmlDoc, 'ins', null, author);
+        const insWrapper = createTrackChange(xmlDoc, 'ins', null, author, revisionMetadata);
         runs.forEach(run => insWrapper.appendChild(run));
         parent.insertBefore(insWrapper, referenceNode);
     } else {

package/engine/surgical-mode.js

@@ -15,6 +15,75 @@ import {
     reconcileFormattingForTextSpan
 } from './surgical-diff-application.js';
 import { withOoxmlSourceType } from '../core/word-xml.js';
+import { createReplacementRevisionEvent } from '../core/types.js';
+
+function checkSafeAdjacencyForPairing(spanIndex, startPos, endPos) {
+    const spans = [];
+    forEachOverlappingSpan(spanIndex, startPos, endPos, span => spans.push(span));
+    if (spans.length === 0) return { safe: false };
+
+    const firstRun = spans[0].runElement;
+    const parent = firstRun?.parentNode;
+    if (!parent) return { safe: false };
+
+    // All overlapping runs must share the exact same parent element
+    const sameParent = spans.every(s => s.runElement?.parentNode === parent);
+    if (!sameParent) return { safe: false, structuralBoundary: true };
+
+    // Parent container itself cannot be an existing revision or unsupported container
+    const parentLocal = (parent.localName || parent.nodeName.replace(/^.*:/, ''));
+    if (['hyperlink', 'sdt', 'ins', 'del', 'moveFrom', 'moveTo'].includes(parentLocal)) {
+        return { safe: false, structuralBoundary: true };
+    }
+
+    const structuralTags = new Set([
+        'hyperlink', 'fldSimple', 'sdt',
+        'commentRangeStart', 'commentRangeEnd', 'commentReference',
+        'bookmarkStart', 'bookmarkEnd',
+        'moveFrom', 'moveTo', 'ins', 'del'
+    ]);
+
+    for (const span of spans) {
+        const run = span.runElement;
+        for (const child of Array.from(run.childNodes || [])) {
+            if (child.nodeType === 1) {
+                const tag = child.localName || child.nodeName.replace(/^.*:/, '');
+                if (structuralTags.has(tag) || tag === 'fldChar') {
+                    return { safe: false, structuralBoundary: true };
+                }
+            }
+        }
+    }
+
+    const lastRun = spans[spans.length - 1].runElement;
+    let curr = firstRun;
+    while (curr && curr !== lastRun) {
+        if (curr !== firstRun) {
+            const tag = curr.localName || curr.nodeName.replace(/^.*:/, '');
+            if (structuralTags.has(tag)) {
+                return { safe: false, structuralBoundary: true };
+            }
+        }
+        curr = curr.nextSibling;
+    }
+
+    function hasStructuralDescendant(node) {
+        if (!node || node.nodeType !== 1) return false;
+        const tag = node.localName || node.nodeName.replace(/^.*:/, '');
+        if (structuralTags.has(tag) || tag === 'fldChar') return true;
+        for (const child of Array.from(node.childNodes || [])) {
+            if (child.nodeType === 1 && hasStructuralDescendant(child)) return true;
+        }
+        return false;
+    }
+
+    // Inspect immediate adjacent siblings of the deleted range
+    if (hasStructuralDescendant(firstRun.previousSibling) || hasStructuralDescendant(lastRun.nextSibling)) {
+        return { safe: false, structuralBoundary: true };
+    }
+
+    return { safe: true };
+}
 
 /**
  * Applies surgical mode reconciliation.
@@ -28,9 +97,10 @@ import { withOoxmlSourceType } from '../core/word-xml.js';
  * @param {boolean} [generateRedlines=true] - Track change toggle
  * @param {Element|null} [targetParagraph=null] - Optional scope paragraph
  * @param {{ diffTimeoutSeconds?: number }} [diffOptions={}] - Diff configuration
- * @returns {{ oxml: string, hasChanges: boolean, sourceType?: 'package'|'document'|'fragment' }}
+ * @param {Object} [options={}] - Additional reconciliation options (e.g. pairReplacements)
+ * @returns {{ oxml: string, hasChanges: boolean, warnings?: string[], sourceType?: 'package'|'document'|'fragment' }}
  */
-export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null, diffOptions = {}) {
+export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null, diffOptions = {}, options = {}) {
     void originalText;
 
     const allParagraphs = targetParagraph
@@ -40,12 +110,15 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     const { fullText, textSpans } = buildSurgicalTextSpans(allParagraphs);
     const diffs = computeWordDiffs(fullText, modifiedText, diffOptions);
     const spanIndex = buildSpanIndex(textSpans);
+    const pairReplacements = options.pairReplacements === true;
+    const warnings = [];
 
     let originalPos = 0;
     let newPos = 0;
     let hasChanges = false;
 
-    for (const [op, text] of diffs) {
+    for (let i = 0; i < diffs.length; i++) {
+        const [op, text] = diffs[i];
         if (op === 0) {
             const len = text.length;
             const startPos = originalPos;
@@ -67,14 +140,65 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             originalPos += len;
             newPos += len;
         } else if (op === -1) {
-            if (processDelete(xmlDoc, spanIndex, originalPos, originalPos + text.length, author, generateRedlines)) {
+            const hasNextInsert = (i + 1 < diffs.length) && (diffs[i + 1][0] === 1);
+            let paired = false;
+            let delMetadata = null;
+            let insMetadata = null;
+
+            if (pairReplacements && generateRedlines && hasNextInsert) {
+                const nextText = diffs[i + 1][1];
+                const textWithoutNewlines = nextText.replace(/\n/g, ' ');
+                if (textWithoutNewlines.trim().length > 0) {
+                    const checkResult = checkSafeAdjacencyForPairing(spanIndex, originalPos, originalPos + text.length);
+                    if (checkResult.safe) {
+                        const event = createReplacementRevisionEvent(author, xmlDoc);
+                        delMetadata = { id: event.deletionId, author: event.author, date: event.date };
+                        insMetadata = { id: event.insertionId, author: event.author, date: event.date };
+                        paired = true;
+                    } else if (checkResult.structuralBoundary) {
+                        warnings.push('PAIRING_SKIPPED_STRUCTURAL_BOUNDARY');
+                    }
+                }
+            }
+
+            if (processDelete(xmlDoc, spanIndex, originalPos, originalPos + text.length, author, generateRedlines, delMetadata)) {
                 hasChanges = true;
             }
             originalPos += text.length;
+
+            if (paired) {
+                i++;
+                const [, nextText] = diffs[i];
+                const textWithoutNewlines = nextText.replace(/\n/g, ' ');
+                if (textWithoutNewlines.trim().length > 0) {
+                    const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, insMetadata, options?.insertionAffinity || null);
+                    if (insertResult && typeof insertResult === 'object' && insertResult.error) {
+                        return withOoxmlSourceType({
+                            oxml: serializer.serializeToString(xmlDoc),
+                            hasChanges: false,
+                            status: 'error',
+                            error: insertResult.error
+                        });
+                    }
+                    if (insertResult === true) {
+                        hasChanges = true;
+                    }
+                }
+                newPos += nextText.length;
+            }
         } else if (op === 1) {
             const textWithoutNewlines = text.replace(/\n/g, ' ');
             if (textWithoutNewlines.trim().length > 0) {
-                if (processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null)) {
+                const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, null, options?.insertionAffinity || null);
+                if (insertResult && typeof insertResult === 'object' && insertResult.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: insertResult.error
+                    });
+                }
+                if (insertResult === true) {
                     hasChanges = true;
                 }
             }
@@ -82,5 +206,9 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         }
     }
 
-    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges });
+    return withOoxmlSourceType({
+        oxml: serializer.serializeToString(xmlDoc),
+        hasChanges,
+        ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
+    });
 }

package/engine/surgical-spans.js

@@ -7,6 +7,7 @@ export function getRunChildText(child) {
     if (isWordElement(child, 'br') || isWordElement(child, 'cr')) return '\n';
     if (isWordElement(child, 'tab')) return '\t';
     if (isWordElement(child, 'noBreakHyphen')) return '\u2011';
+    if (isWordElement(child, 'softHyphen')) return '\u00ad';
     return '';
 }
 
@@ -15,7 +16,8 @@ export function isTextLikeRunChild(child) {
         || isWordElement(child, 'br')
         || isWordElement(child, 'cr')
         || isWordElement(child, 'tab')
-        || isWordElement(child, 'noBreakHyphen');
+        || isWordElement(child, 'noBreakHyphen')
+        || isWordElement(child, 'softHyphen');
 }
 
 export function buildSurgicalTextSpans(paragraphs) {
@@ -34,6 +36,27 @@ export function buildSurgicalTextSpans(paragraphs) {
                         fullText += processRunElement(hc, paragraph, container, fullText.length, textSpans).text;
                     }
                 }
+            } else if (isWordElement(child, 'ins')) {
+                for (let ic = child.firstChild; ic; ic = ic.nextSibling) {
+                    if (isWordElement(ic, 'r')) {
+                        fullText += processRunElement(ic, paragraph, container, fullText.length, textSpans).text;
+                    }
+                }
+            } else if (isWordElement(child, 'sdt')) {
+                const sdtContent = Array.from(child.childNodes || []).find(n => isWordElement(n, 'sdtContent'));
+                if (sdtContent) {
+                    for (let sc = sdtContent.firstChild; sc; sc = sc.nextSibling) {
+                        if (isWordElement(sc, 'r')) {
+                            fullText += processRunElement(sc, paragraph, container, fullText.length, textSpans).text;
+                        }
+                    }
+                }
+            } else if (isWordElement(child, 'smartTag')) {
+                for (let st = child.firstChild; st; st = st.nextSibling) {
+                    if (isWordElement(st, 'r')) {
+                        fullText += processRunElement(st, paragraph, container, fullText.length, textSpans).text;
+                    }
+                }
             }
         }
 
@@ -167,3 +190,31 @@ function lowerBound(values, target) {
 
     return left;
 }
+
+export function describeInsertionBoundary(spanIndex, pos, fallbackParagraph = null) {
+    if (!spanIndex || !spanIndex.spans || spanIndex.spans.length === 0) {
+        return {
+            leftSpan: null,
+            rightSpan: null,
+            containingSpan: null,
+            isInterior: false,
+            fallbackParagraph
+        };
+    }
+
+    const containingSpan = findContainingSpan(spanIndex, pos);
+    const isInterior = containingSpan !== null && pos > containingSpan.charStart && pos < containingSpan.charEnd;
+
+    // leftSpan ends at or before pos
+    const leftSpan = findFirstSpanEndingAt(spanIndex, pos) || (pos > 0 ? findLastSpanEndingBeforeOrAt(spanIndex, pos) : null);
+    // rightSpan starts at or after pos
+    const rightSpan = spanIndex.spans.find(s => s.charStart === pos) || (pos === 0 ? spanIndex.spans[0] : null);
+
+    return {
+        leftSpan,
+        rightSpan,
+        containingSpan,
+        isInterior,
+        fallbackParagraph
+    };
+}

package/engine/table-cell-context.js

@@ -11,6 +11,7 @@ import { buildParagraphOnlyPackage } from '../services/package-builder.js';
 import { getElementsByTagNSOrTag } from '../core/xml-query.js';
 import { NS_W } from '../core/types.js';
 import { isWordElement } from '../core/word-xml.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 
 const W14_NS = 'http://schemas.microsoft.com/office/word/2010/wordml';
 
@@ -69,12 +70,8 @@ export function detectTableCellContext(xmlDoc, originalText, options = {}) {
     if (originalText && originalText.trim()) {
         const normalizedTarget = originalText.trim();
         if (!targetParagraph) {
-            for (const p of paragraphsInCells) {
-                const textNodes = getElementsByTagNSOrTag(p, NS_W, 't');
-                let paragraphText = '';
-                for (const t of textNodes) {
-                    paragraphText += t.textContent || '';
-                }
+            for (const p of paragraphsInCells) {
+                const paragraphText = extractCanonicalParagraphText(p);
 
                 if (paragraphText.trim() === normalizedTarget) {
                     targetParagraph = p;

package/engine/table-mode.js

@@ -165,7 +165,7 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
                 });
 
                 const del = createWordElement(workingDoc, 'w:del');
-                const metadata = createRevisionMetadata(author, workingDoc);
+                const metadata = createRevisionMetadata(author, workingDoc, 'del');
                 del.setAttribute('w:id', String(metadata.id));
                 del.setAttribute('w:author', metadata.author);
                 del.setAttribute('w:date', metadata.date);