@ansonlai/docx-redline-js 0.5.1 → 0.5.3

package/engine/surgical-mode.js

@@ -6,7 +6,7 @@
  */
 
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { computeWordDiffs } from '../pipeline/diff-engine.js';
+import { computeInsertionOnlyDiffs, computeWordDiffs } from '../pipeline/diff-engine.js';
 import { getDocumentParagraphs } from './format-extraction.js';
 import { buildSpanIndex, buildSurgicalTextSpans, forEachOverlappingSpan } from './surgical-spans.js';
 import {
@@ -16,6 +16,7 @@ import {
 } from './surgical-diff-application.js';
 import { withOoxmlSourceType } from '../core/word-xml.js';
 import { createReplacementRevisionEvent } from '../core/types.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 
 function checkSafeAdjacencyForPairing(spanIndex, startPos, endPos, allowInsertionCarrier = false) {
     const spans = [];
@@ -111,7 +112,10 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         : getDocumentParagraphs(xmlDoc);
 
     const { fullText, textSpans } = buildSurgicalTextSpans(allParagraphs);
-    const diffs = computeWordDiffs(fullText, modifiedText, diffOptions);
+    const insertionOnlyDiffs = options.existingRevisions === 'slice-cross-author'
+        ? computeInsertionOnlyDiffs(fullText, modifiedText)
+        : null;
+    const diffs = insertionOnlyDiffs || computeWordDiffs(fullText, modifiedText, diffOptions);
     const spanIndex = buildSpanIndex(textSpans);
     const pairReplacements = options.pairReplacements === true;
     const warnings = [];
@@ -120,7 +124,42 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     let newPos = 0;
     let hasChanges = false;
 
-    for (let i = 0; i < diffs.length; i++) {
+    const insertionOperations = insertionOnlyDiffs
+        ? collectInsertionOperations(insertionOnlyDiffs)
+        : [];
+    if (insertionOperations.length > 1 && formatHints.length === 0) {
+        for (const operation of insertionOperations.slice().reverse()) {
+            const liveSpans = buildSurgicalTextSpans(allParagraphs).textSpans;
+            const liveSpanIndex = buildSpanIndex(liveSpans);
+            const textWithoutNewlines = operation.text.replace(/\n/g, ' ');
+            if (textWithoutNewlines.length === 0) continue;
+            const insertResult = processInsert(
+                xmlDoc,
+                liveSpanIndex,
+                operation.originalPos,
+                textWithoutNewlines,
+                author,
+                formatHints,
+                operation.newPos,
+                generateRedlines,
+                allParagraphs[0] || null,
+                null,
+                options?.insertionAffinity || null,
+                options?.existingRevisions || 'merge-same-author'
+            );
+            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;
+        }
+    } else {
+
+      for (let i = 0; i < diffs.length; i++) {
         const [op, text] = diffs[i];
         if (op === 0) {
             const len = text.length;
@@ -151,7 +190,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             if (pairReplacements && generateRedlines && hasNextInsert) {
                 const nextText = diffs[i + 1][1];
                 const textWithoutNewlines = nextText.replace(/\n/g, ' ');
-                if (textWithoutNewlines.trim().length > 0) {
+                if (textWithoutNewlines.length > 0) {
                     const checkResult = checkSafeAdjacencyForPairing(
                         spanIndex,
                         originalPos,
@@ -178,7 +217,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
                 i++;
                 const [, nextText] = diffs[i];
                 const textWithoutNewlines = nextText.replace(/\n/g, ' ');
-                if (textWithoutNewlines.trim().length > 0) {
+                if (textWithoutNewlines.length > 0) {
                     const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, insMetadata, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
                     if (insertResult && typeof insertResult === 'object' && insertResult.error) {
                         return withOoxmlSourceType({
@@ -196,7 +235,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             }
         } else if (op === 1) {
             const textWithoutNewlines = text.replace(/\n/g, ' ');
-            if (textWithoutNewlines.trim().length > 0) {
+            if (textWithoutNewlines.length > 0) {
                 const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, null, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
                 if (insertResult && typeof insertResult === 'object' && insertResult.error) {
                     return withOoxmlSourceType({
@@ -212,6 +251,26 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             }
             newPos += text.length;
         }
+      }
+    }
+
+    const actualText = allParagraphs.map(paragraph => extractCanonicalParagraphText(paragraph)).join('\n');
+    const expectedText = String(modifiedText).replace(/\r\n/g, '\n');
+    if (options.existingRevisions === 'slice-cross-author' && actualText !== expectedText) {
+        const mismatchOffset = firstMismatchOffset(expectedText, actualText);
+        return withOoxmlSourceType({
+            oxml: serializer.serializeToString(xmlDoc),
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                message: 'Generated OOXML accepted-view text does not match the requested modified text; the mutation was rejected.',
+                mismatchOffset,
+                expectedExcerpt: excerptAt(expectedText, mismatchOffset),
+                actualExcerpt: excerptAt(actualText, mismatchOffset)
+            },
+            ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
+        });
     }
 
     return withOoxmlSourceType({
@@ -220,3 +279,35 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
     });
 }
+
+function firstMismatchOffset(expected, actual) {
+    const limit = Math.min(expected.length, actual.length);
+    for (let index = 0; index < limit; index++) {
+        if (expected[index] !== actual[index]) return index;
+    }
+    return limit;
+}
+
+function excerptAt(text, offset, radius = 40) {
+    const start = Math.max(0, offset - radius);
+    const end = Math.min(text.length, offset + radius);
+    return text.slice(start, end);
+}
+
+function collectInsertionOperations(diffs) {
+    const operations = [];
+    let originalPos = 0;
+    let newPos = 0;
+    for (const [op, text] of diffs) {
+        if (op === 0) {
+            originalPos += text.length;
+            newPos += text.length;
+        } else if (op === -1) {
+            originalPos += text.length;
+        } else if (op === 1) {
+            operations.push({ originalPos, newPos, text });
+            newPos += text.length;
+        }
+    }
+    return operations;
+}

package/index.d.ts

@@ -29,6 +29,7 @@ export type {
   OperationPreflightResult,
   ParagraphTargetDescriptor,
   RedlineDocumentOperation,
+  RestoreDocumentOperation,
   ResolvedCommentAnchor,
   ResolvedDocumentTarget,
   StandaloneRunnerOptions
@@ -43,6 +44,13 @@ export interface RedlineError {
     | 'UNSUPPORTED_REVISION_VIEW_MUTATION'
     | 'UNSUPPORTED_INSERTION_AFFINITY'
     | 'UNSAFE_PARAGRAPH_BOUNDARY'
+    | 'FOREIGN_PARAGRAPH_MARK_DELETION'
+    | 'RESTORATION_STATE_REQUIRED'
+    | 'RESTORATION_COUNT_MISMATCH'
+    | 'UNSAFE_DELETED_TABLE_ROW'
+    | 'UNSUPPORTED_MOVE_REVISION'
+    | 'SECTION_BREAK_PARAGRAPH'
+    | 'UNSAFE_PARAGRAPH_PLACEMENT'
     | 'TARGET_INDEX_MISMATCH'
     | 'REVISION_MISMATCH'
     | 'REVISION_TOKEN_SCOPE_MISMATCH'
@@ -54,6 +62,10 @@ export interface RedlineError {
     | 'CAPTURE_STALE'
     | string;
   message: string;
+  ownerAuthor?: string;
+  stage?: string;
+  expected?: unknown;
+  actual?: unknown;
   commentIds?: string[];
   comments?: Array<{ id: string; author: string; text: string }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",

package/pipeline/diff-engine.js

@@ -232,6 +232,28 @@ export function computeWordDiffs(originalText, newText, options = {}) {
     return decodeBmpDiffs(charDiffs, wordArray);
 }
 
+/**
+ * Returns a character-local diff only when the modified string can be made
+ * solely by inserting into the original. This prevents word-token cleanup
+ * from relocating small insertions between repeated phrases or containers.
+ *
+ * @param {string} originalText
+ * @param {string} newText
+ * @returns {Array<[number, string]>|null}
+ */
+export function computeInsertionOnlyDiffs(originalText, newText) {
+    if (originalText === newText) return [[0, originalText]];
+    if (!originalText) return [[1, newText]];
+    let originalIndex = 0;
+    for (let modifiedIndex = 0; modifiedIndex < newText.length && originalIndex < originalText.length; modifiedIndex++) {
+        if (newText[modifiedIndex] === originalText[originalIndex]) originalIndex++;
+    }
+    if (originalIndex !== originalText.length) return null;
+
+    const diffs = createDiffEngine().diff_main(originalText, newText);
+    return diffs.some(([op]) => op === -1) ? null : diffs;
+}
+
 /**
  * Computes word-level diff operations with offset tracking.
  * 

package/services/document-operation-applier.js

@@ -14,8 +14,9 @@ import {
     applyCommentToParagraphByExactText,
     applyFormattingToParagraphByExactText,
     applyHighlightToParagraphByExactText,
-    applyParagraphFormatToParagraphByExactText,
-    applyToParagraphByExactText
+    applyParagraphFormatToParagraphByExactText,
+    restoreDeletedParagraphByExactText,
+    applyToParagraphByExactText
 } from './document-operation-mutations.js';
 import { applyCommentReplyToParts } from './comment-replies.js';
 import {
@@ -58,7 +59,13 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
     const operation = validation.operation || normalizeDocumentOperation(op);
     const authorUsed = resolveDocumentOperationAuthor(operation, author, getDefaultAuthor());
 
-    if (operation.operationKind !== 'comment_reply' && operation.targetDescriptor?.revisionView === 'rejected') {
+    if (
+        operation.operationKind !== 'comment_reply'
+        && (
+            operation.targetDescriptor?.revisionView === 'rejected'
+            || operation.targetEndDescriptor?.revisionView === 'rejected'
+        )
+    ) {
         return {
             documentXml,
             hasChanges: false,
@@ -159,7 +166,8 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         pairReplacements: typeof operation.pairReplacements === 'boolean' ? operation.pairReplacements : (options.pairReplacements !== false),
         ...(operation.insertionAffinity ? { insertionAffinity: operation.insertionAffinity } : {}),
         ...(operation.formattingRevisionPolicy ? { formattingRevisionPolicy: operation.formattingRevisionPolicy } : {}),
-        targetDescriptor: operation.targetDescriptor,
+        targetDescriptor: operation.targetDescriptor,
+        targetEndDescriptor: operation.targetEndDescriptor,
         _resolutionCapture: resolutionCapture,
         _revisionIdAllocator: session.revisionIdAllocator,
         _documentOperationSession: session,
@@ -242,7 +250,18 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 runtimeContext,
                 operationOptions
             );
-        } else {
+        } else if (operation.operationKind === 'restore') {
+            result = await restoreDeletedParagraphByExactText(
+                documentXml,
+                operation.target,
+                operation.modified,
+                authorUsed,
+                operation.targetRef,
+                operation.targetEndRef,
+                runtimeContext,
+                operationOptions
+            );
+        } else {
             result = await applyToParagraphByExactText(
                 documentXml,
                 operation.target,

package/services/document-operation-contract.js

@@ -14,6 +14,7 @@ const SUPPORTED_OPERATION_TYPES = new Set([
     'list-change',
     'table-reconciliation',
     'insert',
+    'restore',
     'delete',
     'comment',
     'comment_reply',
@@ -42,6 +43,7 @@ function nonEmptyString(value) {
 
 export function getCanonicalOperationType(operation) {
     const type = operation?.type;
+    if (type === 'restore') return 'restore';
     if (type === 'comment' || type === 'comment_reply' || type === 'highlight') return type;
     if (type === 'paragraph-format') return 'paragraph-format';
     if (type === 'character-format' || (type === 'format' && (operation?.textToFormat != null || operation?.properties != null))) return 'format';
@@ -83,7 +85,7 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
 export function normalizeDocumentOperation(operation) {
     const source = isRecord(operation) ? operation : {};
     const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef);
-    const targetEndDescriptor = isRecord(source.targetEnd)
+    const targetEndDescriptor = source.targetEnd != null
         ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef)
         : null;
     const kind = getCanonicalOperationType(source);
@@ -94,6 +96,7 @@ export function normalizeDocumentOperation(operation) {
         captureKey: nonEmptyString(source.captureKey) ? source.captureKey.trim() : null,
         operationKind: kind,
         targetDescriptor,
+        targetEndDescriptor,
         target: targetDescriptor.text,
         targetRef: targetDescriptor.index,
         targetEndRef: targetEndDescriptor?.index ?? source.targetEndRef ?? null,
@@ -174,7 +177,14 @@ export function validateDocumentOperation(operation) {
     }
 
     const target = normalized.targetDescriptor;
-    if (normalized.operationKind !== 'comment_reply' && !nonEmptyString(target.text) && target.index == null && !target.paragraphId && !target.captureRef) {
+    if (
+        normalized.operationKind !== 'comment_reply'
+        && !nonEmptyString(target.text)
+        && target.index == null
+        && !target.paragraphId
+        && !target.fingerprint
+        && !target.captureRef
+    ) {
         return {
             valid: false,
             error: {
@@ -201,6 +211,31 @@ export function validateDocumentOperation(operation) {
         };
     }
 
+    if (normalized.operationKind === 'restore') {
+        const validSingle = nonEmptyString(normalized.modified);
+        const validRange = Array.isArray(normalized.modified)
+            && normalized.modified.length > 0
+            && normalized.modified.every(nonEmptyString);
+        if (!validSingle && !validRange) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore operations require a non-empty string or non-empty string array in "modified".'
+                }
+            };
+        }
+        if (normalized.generateRedlines === false) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Restore operations require tracked changes and cannot set generateRedlines to false.'
+                }
+            };
+        }
+    }
+
     if (normalized.structuredContent != null && typeof normalized.structuredContent !== 'boolean') {
         return {
             valid: false,