@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/engine/reconstruction-mode.js

@@ -6,21 +6,21 @@ import { computeWordDiffs } from '../pipeline/diff-engine.js';
 import { buildReconstructionMapping, findReconstructionParagraphRange } from './reconstruction-mapper.js';
 import { applyReconstructionDiffs } from './reconstruction-writer.js';
 import { withOoxmlSourceType } from '../core/word-xml.js';
-
-/**
- * Applies reconstruction mode reconciliation.
- *
- * @param {Document} xmlDoc - XML document
- * @param {string} originalText - Original text (kept for signature compatibility)
- * @param {string} modifiedText - Modified text
- * @param {XMLSerializer} serializer - Serializer instance
- * @param {string} author - Author name
- * @param {Array} formatHints - Format hints
- * @param {boolean} [generateRedlines=true] - Track change toggle
+
+/**
+ * Applies reconstruction mode reconciliation.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} originalText - Original text (kept for signature compatibility)
+ * @param {string} modifiedText - Modified text
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Author name
+ * @param {Array} formatHints - Format hints
+ * @param {boolean} [generateRedlines=true] - Track change toggle
  * @param {{ diffTimeoutSeconds?: number }} [diffOptions={}] - Diff configuration
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyReconstructionMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, diffOptions = {}) {
+export function applyReconstructionMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, diffOptions = {}, options = {}) {
     const selectedParagraphs = findReconstructionParagraphRange(xmlDoc, originalText);
     if (selectedParagraphs === null) {
         return withOoxmlSourceType({
@@ -38,7 +38,7 @@ export function applyReconstructionMode(xmlDoc, originalText, modifiedText, seri
     if (mapping.paragraphs.length === 0) {
         return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges: false });
     }
-
+
     const diffs = computeWordDiffs(mapping.originalFullText, mapping.processedModifiedText, diffOptions);
 
     return withOoxmlSourceType(applyReconstructionDiffs(
@@ -48,6 +48,7 @@ export function applyReconstructionMode(xmlDoc, originalText, modifiedText, seri
         serializer,
         author,
         formatHints,
-        generateRedlines
+        generateRedlines,
+        options
     ));
 }

package/engine/reconstruction-writer.js

@@ -1,9 +1,9 @@
-/**
- * Reconstruction writer.
- *
- * Applies diff segments to mapped reconstruction context and writes updated DOM content.
- */
-
+/**
+ * Reconstruction writer.
+ *
+ * Applies diff segments to mapped reconstruction context and writes updated DOM content.
+ */
+
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
 import {
     createTrackChange,
@@ -12,41 +12,49 @@ import {
     markParagraphMarkInserted
 } from './run-builders.js';
 import { getFirstElementByTagNSOrTag } from '../core/xml-query.js';
-import { NS_W } from '../core/types.js';
+import { NS_W, createReplacementRevisionEvent, createRevisionMetadata } from '../core/types.js';
 import { createWordElement, isWordElement } from '../core/word-xml.js';
-
-/**
- * Applies diffs to reconstruction context and writes updated XML.
- *
- * @param {Document} xmlDoc - XML document
- * @param {Array<[number, string]>} diffs - Diff tuples from diff-match-patch
- * @param {ReturnType<import('./reconstruction-mapper.js').buildReconstructionMapping>} context - Reconstruction mapping
- * @param {XMLSerializer} serializer - Serializer instance
- * @param {string} author - Author name
- * @param {Array} formatHints - Format hints
- * @param {boolean} [generateRedlines=true] - Track change toggle
- * @returns {{ oxml: string, hasChanges: boolean }}
- */
-export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, author, formatHints, generateRedlines = true) {
-    const {
+
+/**
+ * Applies diffs to reconstruction context and writes updated XML.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Array<[number, string]>} diffs - Diff tuples from diff-match-patch
+ * @param {ReturnType<import('./reconstruction-mapper.js').buildReconstructionMapping>} context - Reconstruction mapping
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Author name
+ * @param {Array} formatHints - Format hints
+ * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @returns {{ oxml: string, hasChanges: boolean }}
+ */
+export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, author, formatHints, generateRedlines = true, options = {}) {
+    const {
         paragraphs,
         containerFragments,
-        sentinelMapByStart,
-        referenceMap,
-        replacementContainers,
-        getParagraphInfo,
-        getRunProperties,
-        getPropertySpanLength,
-        isParagraphStart
+        sentinelMapByStart,
+        referenceMap,
+        replacementContainers,
+        getParagraphInfo,
+        getRunProperties,
+        getPropertySpanLength,
+        isParagraphStart
     } = context;
 
     const createNewParagraph = (pPr) => {
         const newParagraph = createWordElement(xmlDoc, 'w:p');
-        if (pPr) newParagraph.appendChild(pPr.cloneNode(true));
+        if (pPr) {
+            const clonedPPr = pPr.cloneNode(true);
+            // Safeguard: Never place w:sectPr on both paragraphs during split
+            const sectPr = getFirstElementByTagNSOrTag(clonedPPr, NS_W, 'sectPr');
+            if (sectPr) {
+                clonedPPr.removeChild(sectPr);
+            }
+            newParagraph.appendChild(clonedPPr);
+        }
         return newParagraph;
     };
-
-    const startInfo = getParagraphInfo(0);
+
+    const startInfo = getParagraphInfo(0);
     let currentParagraph = createNewParagraph(startInfo.pPr);
     const initialFragment = containerFragments.get(startInfo.container);
     if (initialFragment) {
@@ -55,61 +63,69 @@ export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, aut
 
     let currentOriginalIndex = 0;
     let currentInsertOffset = 0;
-    // A replacement is represented as one or more deletions followed by an
-    // insertion. Remember where that deleted range began so replacement text
-    // inherits the formatting at the start of the range, rather than the last
-    // deleted character (which may be a superscript ordinal, footnote-style
-    // run, or another narrow formatting boundary).
+    const pairReplacements = options?.pairReplacements === true;
     let pendingReplacementStart = null;
+    let pendingReplacementEvent = null;
     const emittedCommentMarkers = new WeakSet();
 
-    for (const [op, text] of diffs) {
+    for (let diffIndex = 0; diffIndex < diffs.length; diffIndex++) {
+        const [op, text] = diffs[diffIndex];
         if (op === 0 || op === -1) {
             const type = op === 0 ? 'equal' : 'delete';
             if (op === 0) {
                 pendingReplacementStart = null;
+                pendingReplacementEvent = null;
             } else if (pendingReplacementStart === null) {
                 pendingReplacementStart = currentOriginalIndex;
+                let hasInsert = false;
+                for (let k = diffIndex + 1; k < diffs.length; k++) {
+                    if (diffs[k][0] === 1) { hasInsert = true; break; }
+                    if (diffs[k][0] === 0) break;
+                }
+                if (pairReplacements && generateRedlines && hasInsert) {
+                    pendingReplacementEvent = createReplacementRevisionEvent(author, xmlDoc);
+                }
             }
             let offset = 0;
-
-            while (offset < text.length) {
-                const chunkStart = currentOriginalIndex + offset;
-                const properties = getRunProperties(chunkStart);
-                const chunkLength = getPropertySpanLength(chunkStart, text.length - offset);
-                const chunk = text.substring(offset, offset + chunkLength);
-
+
+            while (offset < text.length) {
+                const chunkStart = currentOriginalIndex + offset;
+                const properties = getRunProperties(chunkStart);
+                const chunkLength = getPropertySpanLength(chunkStart, text.length - offset);
+                const chunk = text.substring(offset, offset + chunkLength);
+
                 const appendResult = appendTextToCurrent(
                     xmlDoc,
                     chunk,
-                    type,
-                    properties.rPr,
-                    properties.wrapper,
-                    chunkStart,
-                    currentParagraph,
-                    containerFragments,
-                    sentinelMapByStart,
-                    referenceMap,
-                    replacementContainers,
-                    getParagraphInfo,
-                    createNewParagraph,
-                    author,
+                    type,
+                    properties.rPr,
+                    properties.wrapper,
+                    chunkStart,
+                    currentParagraph,
+                    containerFragments,
+                    sentinelMapByStart,
+                    referenceMap,
+                    replacementContainers,
+                    getParagraphInfo,
+                    createNewParagraph,
+                    author,
                     formatHints,
                     currentInsertOffset,
                     generateRedlines,
-                    emittedCommentMarkers
+                    emittedCommentMarkers,
+                    pendingReplacementEvent
                 );
                 currentParagraph = appendResult.currentParagraph;
 
                 if (op === 0) {
                     currentInsertOffset += chunkLength;
-                }
-                offset += chunkLength;
-            }
-
-            currentOriginalIndex += text.length;
-            continue;
-        }
+                }
+                offset += chunkLength;
+            }
+
+            currentOriginalIndex += text.length;
+            continue;
+        }
 
         if (op === 1) {
             const propertyIndex = pendingReplacementStart !== null
@@ -118,33 +134,69 @@ export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, aut
                     ? currentOriginalIndex - 1
                     : currentOriginalIndex);
             const properties = getRunProperties(propertyIndex);
-
+
             const appendResult = appendTextToCurrent(
                 xmlDoc,
                 text,
-                'insert',
-                properties.rPr,
-                properties.wrapper,
-                currentOriginalIndex,
-                currentParagraph,
-                containerFragments,
-                sentinelMapByStart,
-                referenceMap,
-                replacementContainers,
-                getParagraphInfo,
-                createNewParagraph,
-                author,
+                'insert',
+                properties.rPr,
+                properties.wrapper,
+                currentOriginalIndex,
+                currentParagraph,
+                containerFragments,
+                sentinelMapByStart,
+                referenceMap,
+                replacementContainers,
+                getParagraphInfo,
+                createNewParagraph,
+                author,
                 formatHints,
                 currentInsertOffset,
                 generateRedlines,
-                emittedCommentMarkers
+                emittedCommentMarkers,
+                pendingReplacementEvent,
+                pendingReplacementStart !== null
             );
             currentParagraph = appendResult.currentParagraph;
             currentInsertOffset += text.length;
             pendingReplacementStart = null;
+            pendingReplacementEvent = null;
         }
     }
-
+
+    if (generateRedlines) {
+        containerFragments.forEach(fragment => {
+            Array.from(fragment.childNodes).forEach(node => {
+                if (isWordElement(node, 'p')) {
+                    const hasVisibleText = Array.from(node.getElementsByTagNameNS(NS_W, 't')).length > 0;
+                    const hasDeletedText = Array.from(node.getElementsByTagNameNS(NS_W, 'delText')).length > 0;
+                    if (paragraphs.length === 1 && !hasVisibleText && (hasDeletedText || context.originalFullText.trim() !== '')) {
+                        markParagraphMarkDeleted(xmlDoc, node, author);
+                    }
+                }
+            });
+        });
+    }
+
+    containerFragments.forEach(fragment => {
+        const createdParagraphs = Array.from(fragment.childNodes).filter(node => isWordElement(node, 'p'));
+        if (createdParagraphs.length > 1) {
+            const firstP = createdParagraphs[0];
+            const lastP = createdParagraphs[createdParagraphs.length - 1];
+            const firstPPr = getFirstElementByTagNSOrTag(firstP, NS_W, 'pPr');
+            const sectPr = firstPPr ? getFirstElementByTagNSOrTag(firstPPr, NS_W, 'sectPr') : null;
+            if (sectPr) {
+                firstPPr.removeChild(sectPr);
+                let lastPPr = getFirstElementByTagNSOrTag(lastP, NS_W, 'pPr');
+                if (!lastPPr) {
+                    lastPPr = createWordElement(xmlDoc, 'w:pPr');
+                    lastP.insertBefore(lastPPr, lastP.firstChild || null);
+                }
+                lastPPr.appendChild(sectPr);
+            }
+        }
+    });
+
     const paragraphSet = new Set(paragraphs);
     const insertionAnchors = new Map();
     paragraphs.forEach(paragraph => {
@@ -213,29 +265,48 @@ function appendTextToCurrent(
     formatHints = [],
     insertOffset = 0,
     generateRedlines = true,
-    emittedCommentMarkers = new WeakSet()
+    emittedCommentMarkers = new WeakSet(),
+    replacementEvent = null,
+    deferClosingCommentMarkers = false
 ) {
     let localBaseIndex = baseIndex;
     let localInsertOffset = insertOffset;
     let localParagraph = currentParagraphRef;
+    const deferredCommentMarkers = [];
 
     const parts = text.split(/([\n\uFFFC]|[\uE000-\uF8FF])/);
 
     parts.forEach(part => {
         const sentinelsAtOffset = sentinelMapByStart.get(localBaseIndex) || [];
         const commentMarkers = sentinelsAtOffset.filter(sentinel => sentinel.isCommentMarker && !emittedCommentMarkers.has(sentinel.node));
+        const closingCommentIds = deferClosingCommentMarkers
+            ? new Set(commentMarkers
+                .filter(marker => isWordElement(marker.node, 'commentRangeEnd'))
+                .map(marker => marker.node.getAttributeNS?.(NS_W, 'id') || marker.node.getAttribute?.('w:id') || marker.node.getAttribute?.('id')))
+            : new Set();
 
         commentMarkers.forEach(marker => {
             emittedCommentMarkers.add(marker.node);
+            const markerId = marker.node.getAttributeNS?.(NS_W, 'id')
+                || marker.node.getAttribute?.('w:id')
+                || marker.node.getAttribute?.('id');
+            if (
+                deferClosingCommentMarkers
+                && closingCommentIds.has(markerId)
+                && (isWordElement(marker.node, 'commentRangeEnd') || isWordElement(marker.node, 'commentReference'))
+            ) {
+                deferredCommentMarkers.push(marker.node);
+                return;
+            }
             if (isWordElement(marker.node, 'commentReference')) {
                 const run = createWordElement(xmlDoc, 'w:r');
                 run.appendChild(marker.node.cloneNode(true));
                 localParagraph.appendChild(run);
             } else {
-                localParagraph.appendChild(marker.node.cloneNode(true));
-            }
-        });
-
+                localParagraph.appendChild(marker.node.cloneNode(true));
+            }
+        });
+
         if (part === '\n') {
             const info = getParagraphInfo(localBaseIndex + 1);
             const nextParagraph = createNewParagraph(info.pPr);
@@ -252,20 +323,20 @@ function appendTextToCurrent(
             }
             localBaseIndex++;
             if (type !== 'delete') localInsertOffset++;
-            return;
-        }
-
-        if (part === '\uFFFC') {
-            const sentinel = sentinelsAtOffset.find(entry => !entry.isCommentMarker) || sentinelsAtOffset[0];
-            if (sentinel) {
-                const clone = sentinel.node.cloneNode(true);
-                if (sentinel.isTextBox && sentinel.originalContainer) {
+            return;
+        }
+
+        if (part === '\uFFFC') {
+            const sentinel = sentinelsAtOffset.find(entry => !entry.isCommentMarker) || sentinelsAtOffset[0];
+            if (sentinel) {
+                const clone = sentinel.node.cloneNode(true);
+                if (sentinel.isTextBox && sentinel.originalContainer) {
                     const newContainer = getFirstElementByTagNSOrTag(clone, NS_W, 'txbxContent');
-                    if (newContainer) {
-                        while (newContainer.firstChild) newContainer.removeChild(newContainer.firstChild);
-                        replacementContainers.set(sentinel.originalContainer, newContainer);
-                    }
-                }
+                    if (newContainer) {
+                        while (newContainer.firstChild) newContainer.removeChild(newContainer.firstChild);
+                        replacementContainers.set(sentinel.originalContainer, newContainer);
+                    }
+                }
                 if (sentinel.wrapInRun) {
                     const run = createWordElement(xmlDoc, 'w:r');
                     if (sentinel.rPr) run.appendChild(sentinel.rPr.cloneNode(true));
@@ -274,14 +345,14 @@ function appendTextToCurrent(
                 } else {
                     localParagraph.appendChild(clone);
                 }
-            }
-            localBaseIndex++;
-            if (type !== 'delete') localInsertOffset++;
-            return;
-        }
-
-        if (referenceMap.has(part)) {
-            if (type !== 'delete') {
+            }
+            localBaseIndex++;
+            if (type !== 'delete') localInsertOffset++;
+            return;
+        }
+
+        if (referenceMap.has(part)) {
+            if (type !== 'delete') {
                 const refNode = referenceMap.get(part);
                 if (refNode) {
                     const clone = refNode.cloneNode(true);
@@ -289,21 +360,21 @@ function appendTextToCurrent(
                     if (rPr) run.appendChild(rPr.cloneNode(true));
                     run.appendChild(clone);
                     localParagraph.appendChild(run);
-                }
-            }
-            localBaseIndex++;
-            if (type !== 'delete') localInsertOffset++;
-            return;
-        }
-
-        if (part.length === 0) return;
-
-        let parent = localParagraph;
-        if (wrapper) {
-            const wrapperClone = wrapper.cloneNode(false);
-            parent = wrapperClone;
-            localParagraph.appendChild(wrapperClone);
-        }
+                }
+            }
+            localBaseIndex++;
+            if (type !== 'delete') localInsertOffset++;
+            return;
+        }
+
+        if (part.length === 0) return;
+
+        let parent = localParagraph;
+        if (wrapper) {
+            const wrapperClone = wrapper.cloneNode(false);
+            parent = wrapperClone;
+            localParagraph.appendChild(wrapperClone);
+        }
 
         if (type === 'delete') {
             const run = createWordElement(xmlDoc, 'w:r');
@@ -312,29 +383,63 @@ function appendTextToCurrent(
             delText.setAttribute('xml:space', 'preserve');
             delText.textContent = part;
             run.appendChild(delText);
-
-            if (generateRedlines) {
-                const del = createTrackChange(xmlDoc, 'del', run, author);
-                parent.appendChild(del);
-            }
-        } else {
-            const applicableHints = getApplicableFormatHints(formatHints, localInsertOffset, localInsertOffset + part.length);
-            const runs = createFormattedRuns(xmlDoc, part, rPr, applicableHints, localInsertOffset, author, generateRedlines);
-
-            if (type === 'insert' && generateRedlines) {
-                const ins = createTrackChange(xmlDoc, 'ins', null, author);
-                runs.forEach(run => ins.appendChild(run));
-                parent.appendChild(ins);
-            } else {
-                runs.forEach(run => parent.appendChild(run));
-            }
-        }
-
-        if (type !== 'delete') {
-            localInsertOffset += part.length;
-        }
+
+            if (generateRedlines) {
+                let metadata = null;
+                if (replacementEvent) {
+                    const id = replacementEvent.usedDeletionId
+                        ? createRevisionMetadata(author, xmlDoc, 'del').id
+                        : replacementEvent.deletionId;
+                    replacementEvent.usedDeletionId = true;
+                    metadata = {
+                        id,
+                        author: replacementEvent.author,
+                        date: replacementEvent.date
+                    };
+                }
+                const del = createTrackChange(xmlDoc, 'del', run, author, metadata);
+                parent.appendChild(del);
+            }
+        } else {
+            const applicableHints = getApplicableFormatHints(formatHints, localInsertOffset, localInsertOffset + part.length);
+            const runs = createFormattedRuns(xmlDoc, part, rPr, applicableHints, localInsertOffset, author, generateRedlines);
+
+            if (type === 'insert' && generateRedlines) {
+                let metadata = null;
+                if (replacementEvent) {
+                    const id = replacementEvent.usedInsertionId
+                        ? createRevisionMetadata(author, xmlDoc, 'ins').id
+                        : replacementEvent.insertionId;
+                    replacementEvent.usedInsertionId = true;
+                    metadata = {
+                        id,
+                        author: replacementEvent.author,
+                        date: replacementEvent.date
+                    };
+                }
+                const ins = createTrackChange(xmlDoc, 'ins', null, author, metadata);
+                runs.forEach(run => ins.appendChild(run));
+                parent.appendChild(ins);
+            } else {
+                runs.forEach(run => parent.appendChild(run));
+            }
+        }
+
+        if (type !== 'delete') {
+            localInsertOffset += part.length;
+        }
         localBaseIndex += part.length;
     });
 
+    deferredCommentMarkers.forEach(marker => {
+        if (isWordElement(marker, 'commentReference')) {
+            const run = createWordElement(xmlDoc, 'w:r');
+            run.appendChild(marker.cloneNode(true));
+            localParagraph.appendChild(run);
+        } else {
+            localParagraph.appendChild(marker.cloneNode(true));
+        }
+    });
+
     return { currentParagraph: localParagraph };
 }

package/engine/route-selection.js

@@ -0,0 +1,35 @@
+/**
+ * Accuracy-oriented capability record for the current reconciliation routes.
+ * This is internal instrumentation, not a routing policy API.
+ */
+export const RECONCILIATION_CAPABILITY_MATRIX = Object.freeze({
+    formatOnly: Object.freeze({ paragraphs: true, formatting: true, tables: 'scoped', hyperlinks: 'preserved', fields: 'preserved', comments: 'preserved' }),
+    surgical: Object.freeze({ paragraphs: true, tables: 'cell-scoped', hyperlinks: 'preserved', fields: 'preserved', comments: 'preserved', notes: 'preserved' }),
+    reconstruction: Object.freeze({ paragraphs: true, hyperlinks: 'sentinel-preserved', fields: 'sentinel-preserved', comments: 'marker-preserved', notes: 'reference-preserved' }),
+    table: Object.freeze({ tables: true, paragraphs: true, formatting: 'cell-dependent', numbering: false }),
+    listDirect: Object.freeze({ lists: true, numbering: true, paragraphs: 'single-source expansion', tables: 'embedded-markdown blocks', formatting: 'markdown hints' }),
+    listCompatibilityPipeline: Object.freeze({ lists: true, numbering: true, paragraphs: 'multi-source patching', compatibility: true })
+});
+
+export function recordRouteSelection(options, route, context = {}) {
+    const callback = options?._routeInstrumentation?.onRoute;
+    if (typeof callback !== 'function') return;
+    callback(Object.freeze({
+        route,
+        capabilities: RECONCILIATION_CAPABILITY_MATRIX[route] || null,
+        ...context
+    }));
+}
+
+export function createRouteFrequencyCollector() {
+    const counts = new Map();
+    return {
+        onRoute(event) {
+            const route = event?.route || 'unknown';
+            counts.set(route, (counts.get(route) || 0) + 1);
+        },
+        snapshot() {
+            return Object.fromEntries(Array.from(counts).sort(([a], [b]) => a.localeCompare(b)));
+        }
+    };
+}