@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/engine/oxml-engine.js

@@ -1,46 +1,48 @@
-/**
- * OOXML Engine V5.1 - Hybrid Mode
- *
- * Router/orchestrator for formatting/text reconciliation modes.
- */
-
-import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
-import { isListTargetLoose } from '../pipeline/list-markers.js';
-import { ReconciliationPipeline } from '../pipeline/pipeline.js';
-import { ingestOoxml, detectNumberingContext } from '../pipeline/ingestion.js';
-import { executeListGeneration } from '../pipeline/list-generation.js';
-import { analyzeStructuredContent } from '../pipeline/structured-content.js';
-import { wrapInDocumentFragment } from '../pipeline/serialization.js';
-import {
-    getElementsByTagNSOrTag,
-    getXmlParseError
-} from '../core/xml-query.js';
-import { createSerializer, parseOoxmlSafe, serializeXml } from '../adapters/xml-adapter.js';
-import { log, error } from '../adapters/logger.js';
-import { extractFormattingFromOoxml } from './format-extraction.js';
-import {
-    applyFormatRemovalAsSurgicalReplacement,
-    applyFormatOnlyChangesSurgical
-} from './format-application.js';
-import { buildParagraphInfos, findMatchingParagraphInfo, getContainingParagraph } from './format-paragraph-targeting.js';
-import { detectTableCellContext, serializeParagraphOnly } from './table-cell-context.js';
-import { applySurgicalMode } from './surgical-mode.js';
-import { applyReconstructionMode } from './reconstruction-mode.js';
-import { applyTableReconciliation, applyTextToTableTransformation } from './table-mode.js';
-import { getDefaultAuthor } from '../adapters/config.js';
-import { containsTrackedChanges, createWordElement, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+/**
+ * OOXML Engine V5.1 - Hybrid Mode
+ *
+ * Router/orchestrator for formatting/text reconciliation modes.
+ */
+
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { isListTargetLoose } from '../pipeline/list-markers.js';
+import { ReconciliationPipeline } from '../pipeline/pipeline.js';
+import { ingestOoxml, detectNumberingContext } from '../pipeline/ingestion.js';
+import { executeListGeneration } from '../pipeline/list-generation.js';
+import { analyzeStructuredContent } from '../pipeline/structured-content.js';
+import { wrapInDocumentFragment } from '../pipeline/serialization.js';
+import {
+    getElementsByTagNSOrTag,
+    getXmlParseError
+} from '../core/xml-query.js';
+import { createSerializer, parseOoxmlSafe, serializeXml } from '../adapters/xml-adapter.js';
+import { log, error } from '../adapters/logger.js';
+import { buildTextSpansFromParagraphs, extractFormattingFromOoxml } from './format-extraction.js';
+import {
+    applyFormatRemovalAsSurgicalReplacement,
+    applyFormatOnlyChangesSurgical
+} from './format-application.js';
+import { buildParagraphInfos, findMatchingParagraphInfo, getContainingParagraph } from './format-paragraph-targeting.js';
+import { detectTableCellContext, serializeParagraphOnly } from './table-cell-context.js';
+import { applySurgicalMode } from './surgical-mode.js';
+import { applyReconstructionMode } from './reconstruction-mode.js';
+import { applyTableReconciliation, applyTextToTableTransformation } from './table-mode.js';
+import { getDefaultAuthor } from '../adapters/config.js';
+import { containsTrackedChanges, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
 import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
-import {
-    NS_W,
-    RevisionIdAllocator,
-    seedRevisionIdsFromDocument
-} from '../core/types.js';
-import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml } from '../services/revision-comment-management.js';
-import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
-import { getDocumentParagraphs } from './format-extraction.js';
-import { isDiffTokenLimitError } from '../pipeline/diff-engine.js';
-import { NumberingService } from '../services/numbering-service.js';
+import {
+    NS_W,
+    RevisionIdAllocator,
+    seedRevisionIdsFromDocument
+} from '../core/types.js';
+import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml } from '../services/revision-comment-management.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+import { getCurrentParagraphProperties } from '../core/current-properties.js';
+import { getDocumentParagraphs } from './format-extraction.js';
+import { isDiffTokenLimitError } from '../pipeline/diff-engine.js';
+import { NumberingService } from '../services/numbering-service.js';
 import { recordRouteSelection } from './route-selection.js';
+import { restoreParagraphMarkInserted } from './paragraph-mark-revisions.js';
 import { inspectForeignDeletedParagraphTarget } from '../core/paragraph-revision-safety.js';
 
 function getCommentIdsInOoxml(node) {
@@ -90,79 +92,63 @@ function restoreInsertedParagraphMark(oxml, metadata) {
         : getDocumentParagraphs(parsed.doc)[0];
     if (!paragraph) return oxml;
 
-    let pPr = directWordChild(paragraph, 'pPr');
-    if (!pPr) {
-        pPr = createWordElement(parsed.doc, 'w:pPr');
-        paragraph.insertBefore(pPr, paragraph.firstChild);
-    }
-    let rPr = directWordChild(pPr, 'rPr');
-    if (!rPr) {
-        rPr = createWordElement(parsed.doc, 'w:rPr');
-        pPr.appendChild(rPr);
-    }
-    if (!directWordChild(rPr, 'ins')) {
-        const marker = createWordElement(parsed.doc, 'w:ins');
-        if (metadata.id) marker.setAttribute('w:id', metadata.id);
-        marker.setAttribute('w:author', metadata.author);
-        if (metadata.date) marker.setAttribute('w:date', metadata.date);
-        rPr.appendChild(marker);
-    }
+    restoreParagraphMarkInserted(paragraph, metadata);
     return serializeXml(parsed.doc);
 }
-
-/**
- * Applies redline track changes to OOXML by modifying the DOM in-place.
- *
- * @param {string} oxml - Original OOXML string
- * @param {string} originalText - Original plain text
- * @param {string} modifiedText - New text (may contain markdown)
- * @param {Object} [options={}] - Options
- * @param {string} [options.author='AI'] - Author for track changes
- * @param {string|null} [options.targetParagraphId=null] - Preferred paragraph identity for table wrappers
+
+/**
+ * Applies redline track changes to OOXML by modifying the DOM in-place.
+ *
+ * @param {string} oxml - Original OOXML string
+ * @param {string} originalText - Original plain text
+ * @param {string} modifiedText - New text (may contain markdown)
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.author='AI'] - Author for track changes
+ * @param {string|null} [options.targetParagraphId=null] - Preferred paragraph identity for table wrappers
  * @param {'merge-same-author'|'slice-cross-author'|'reject-input'|'accept-all-first'|'accept-all-first-keep-normalized'} [options.existingRevisions='merge-same-author'] - Policy for source OOXML with tracked changes
- * @param {boolean} [options.removeFormatting=false] - Remove existing core formatting when text is otherwise unchanged
- * @param {boolean} [options.sanitizeInput=false] - Strip a standalone leading assistant preface line
- * @returns {Promise<{ oxml: string, hasChanges: boolean, sourceType?: 'package'|'document'|'fragment', status?: 'ok'|'no-op'|'error', error?: { code: string, message: string } }>}
- */
-export async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}) {
-    const inputOoxml = oxml;
-    let workingOoxml = oxml;
-    originalText = typeof originalText === 'string' ? originalText : String(originalText ?? '');
-    modifiedText = typeof modifiedText === 'string' ? modifiedText : String(modifiedText ?? '');
-    const generateRedlines = options.generateRedlines ?? true;
-    const author = options.author || getDefaultAuthor();
-    const serializer = createSerializer();
-    let parseWarnings = [];
-    const operationWarnings = [];
+ * @param {boolean} [options.removeFormatting=false] - Remove existing core formatting when text is otherwise unchanged
+ * @param {boolean} [options.sanitizeInput=false] - Strip a standalone leading assistant preface line
+ * @returns {Promise<{ oxml: string, hasChanges: boolean, sourceType?: 'package'|'document'|'fragment', status?: 'ok'|'no-op'|'error', error?: { code: string, message: string } }>}
+ */
+export async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}) {
+    const inputOoxml = oxml;
+    let workingOoxml = oxml;
+    originalText = typeof originalText === 'string' ? originalText : String(originalText ?? '');
+    modifiedText = typeof modifiedText === 'string' ? modifiedText : String(modifiedText ?? '');
+    const generateRedlines = options.generateRedlines ?? true;
+    const author = options.author || getDefaultAuthor();
+    const serializer = createSerializer();
+    let parseWarnings = [];
+    const operationWarnings = [];
     let normalizedExistingRevisions = false;
     let preservedInsertedParagraphMark = null;
-    const existingRevisionsPolicy = options.existingRevisions || 'merge-same-author';
-    const keepNormalizedNoOp = existingRevisionsPolicy === 'accept-all-first-keep-normalized';
+    const existingRevisionsPolicy = options.existingRevisions || 'merge-same-author';
+    const keepNormalizedNoOp = existingRevisionsPolicy === 'accept-all-first-keep-normalized';
     const finalize = result => {
         const withStatus = { ...result };
-        if (normalizedExistingRevisions && withStatus.hasChanges === false && withStatus.status !== 'error') {
+        if (normalizedExistingRevisions && withStatus.hasChanges === false && withStatus.status !== 'error') {
             if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
-                withStatus.oxml = workingOoxml;
-                withStatus.hasChanges = true;
-                withStatus.warnings = [
-                    ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : []),
-                    'Previous revisions by the same author were reverted to baseline.'
-                ];
-            } else if (keepNormalizedNoOp) {
-                withStatus.oxml = workingOoxml;
-                withStatus.hasChanges = true;
-                withStatus.warnings = [
-                    ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : []),
-                    'Existing revisions were accepted before redlining.'
-                ];
-            } else {
-                withStatus.oxml = inputOoxml;
-            }
-        }
-        const warnings = [...parseWarnings, ...operationWarnings, ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : [])];
-        if (warnings.length > 0) {
-            withStatus.warnings = [...new Set(warnings)];
-        }
+                withStatus.oxml = workingOoxml;
+                withStatus.hasChanges = true;
+                withStatus.warnings = [
+                    ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : []),
+                    'Previous revisions by the same author were reverted to baseline.'
+                ];
+            } else if (keepNormalizedNoOp) {
+                withStatus.oxml = workingOoxml;
+                withStatus.hasChanges = true;
+                withStatus.warnings = [
+                    ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : []),
+                    'Existing revisions were accepted before redlining.'
+                ];
+            } else {
+                withStatus.oxml = inputOoxml;
+            }
+        }
+        const warnings = [...parseWarnings, ...operationWarnings, ...(Array.isArray(withStatus.warnings) ? withStatus.warnings : [])];
+        if (warnings.length > 0) {
+            withStatus.warnings = [...new Set(warnings)];
+        }
         if (!withStatus.status) {
             withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
         }
@@ -170,36 +156,36 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
             withStatus.oxml = restoreInsertedParagraphMark(withStatus.oxml, preservedInsertedParagraphMark);
         }
         return withOoxmlSourceType(withStatus);
-    };
-    const finalizeUnchanged = () => {
-        if (normalizedExistingRevisions && keepNormalizedNoOp) {
-            return finalize({
-                oxml: workingOoxml,
-                hasChanges: true,
-                warnings: ['Existing revisions were accepted before redlining.']
-            });
-        }
-        return finalize({ oxml: inputOoxml, hasChanges: false });
-    };
-
-    const parsed = parseOoxmlSafe(inputOoxml, 'text/xml');
-    parseWarnings = parsed.warnings;
-    let xmlDoc = parsed.doc;
-
-    const parseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
-    if (parsed.error || parseError) {
-        const message = parsed.error?.message || parseError?.textContent || 'Could not parse OOXML input.';
-        error('[OxmlEngine] XML parse error:', message);
-        return finalize({
-            oxml: inputOoxml,
-            hasChanges: false,
-            status: 'error',
-            error: { code: 'PARSE_ERROR', message }
-        });
-    }
-    const revisionIdAllocator = options?._revisionIdAllocator instanceof RevisionIdAllocator
-        ? options._revisionIdAllocator
-        : new RevisionIdAllocator();
+    };
+    const finalizeUnchanged = () => {
+        if (normalizedExistingRevisions && keepNormalizedNoOp) {
+            return finalize({
+                oxml: workingOoxml,
+                hasChanges: true,
+                warnings: ['Existing revisions were accepted before redlining.']
+            });
+        }
+        return finalize({ oxml: inputOoxml, hasChanges: false });
+    };
+
+    const parsed = parseOoxmlSafe(inputOoxml, 'text/xml');
+    parseWarnings = parsed.warnings;
+    let xmlDoc = parsed.doc;
+
+    const parseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
+    if (parsed.error || parseError) {
+        const message = parsed.error?.message || parseError?.textContent || 'Could not parse OOXML input.';
+        error('[OxmlEngine] XML parse error:', message);
+        return finalize({
+            oxml: inputOoxml,
+            hasChanges: false,
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message }
+        });
+    }
+    const revisionIdAllocator = options?._revisionIdAllocator instanceof RevisionIdAllocator
+        ? options._revisionIdAllocator
+        : new RevisionIdAllocator();
     seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
 
     const inputParagraphs = xmlDoc.documentElement && String(xmlDoc.documentElement.localName || '').toLowerCase() === 'p'
@@ -224,7 +210,7 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
 
     if (containsTrackedChanges(xmlDoc)) {
         if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
-            const authors = getTrackedChangeAuthors(xmlDoc);
+            const authors = getTrackedChangeAuthors(xmlDoc);
             const currentAuthor = String(author || '').trim().toLowerCase();
             const isSameAuthor = authors.length > 0 && authors.every(a => a.trim().toLowerCase() === currentAuthor);
             if (isSameAuthor) {
@@ -249,21 +235,21 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                 workingOoxml = preservedInsertedParagraphMark && !String(rejected.oxml || '').trim()
                     ? emptyParagraphBaseline(soleParagraph, serializer)
                     : rejected.oxml;
-                normalizedExistingRevisions = true;
-                const rejectedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
-                parseWarnings.push(...rejectedParsed.warnings);
-                xmlDoc = rejectedParsed.doc;
-                const rejectedParseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
+                normalizedExistingRevisions = true;
+                const rejectedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
+                parseWarnings.push(...rejectedParsed.warnings);
+                xmlDoc = rejectedParsed.doc;
+                const rejectedParseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
                 if (rejectedParsed.error || rejectedParseError) {
-                    const message = rejectedParsed.error?.message || rejectedParseError?.textContent || 'Could not parse OOXML after rejecting same-author revisions.';
-                    error('[OxmlEngine] XML parse error after rejecting same-author revisions:', message);
-                    return finalize({
-                        oxml: inputOoxml,
-                        hasChanges: false,
-                        status: 'error',
-                        error: {
-                            code: 'PARSE_ERROR',
-                            message
+                    const message = rejectedParsed.error?.message || rejectedParseError?.textContent || 'Could not parse OOXML after rejecting same-author revisions.';
+                    error('[OxmlEngine] XML parse error after rejecting same-author revisions:', message);
+                    return finalize({
+                        oxml: inputOoxml,
+                        hasChanges: false,
+                        status: 'error',
+                        error: {
+                            code: 'PARSE_ERROR',
+                            message
                         }
                     });
                 }
@@ -279,28 +265,28 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     });
                 }
                 seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
-
-                // Re-derive baseline text from the restored baseline OOXML:
-                const paragraphsInDoc = xmlDoc.documentElement && String(xmlDoc.documentElement.localName || '').toLowerCase() === 'p'
-                    ? [xmlDoc.documentElement]
-                    : getDocumentParagraphs(xmlDoc);
-                const baselineText = paragraphsInDoc.length > 0
-                    ? paragraphsInDoc.map(p => extractCanonicalParagraphText(p)).join('\n')
-                    : '';
-                originalText = baselineText;
+
+                // Re-derive baseline text from the restored baseline OOXML:
+                const paragraphsInDoc = xmlDoc.documentElement && String(xmlDoc.documentElement.localName || '').toLowerCase() === 'p'
+                    ? [xmlDoc.documentElement]
+                    : getDocumentParagraphs(xmlDoc);
+                const baselineText = paragraphsInDoc.length > 0
+                    ? paragraphsInDoc.map(p => extractCanonicalParagraphText(p)).join('\n')
+                    : '';
+                originalText = baselineText;
             } else if (existingRevisionsPolicy === 'merge-same-author') {
                 log('[OxmlEngine] Existing revisions detected from another/unattributed author; refusing per merge-same-author policy');
-                return finalize({
-                    oxml: inputOoxml,
-                    hasChanges: false,
-                    status: 'error',
-                    error: {
+                return finalize({
+                    oxml: inputOoxml,
+                    hasChanges: false,
+                    status: 'error',
+                    error: {
                         code: 'EXISTING_REVISIONS',
                         message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
                         revisionAuthors: authors,
                         currentPolicy: existingRevisionsPolicy
-                    }
-                });
+                    }
+                });
             } else {
                 const hasMoveRevision = ['moveFrom', 'moveTo'].some(localName => {
                     return getElementsByTagNSOrTag(xmlDoc, NS_W, localName).length > 0;
@@ -319,279 +305,292 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                 log('[OxmlEngine] Existing revisions retained for cross-author surgical slicing');
             }
         } else if (existingRevisionsPolicy === 'accept-all-first' || existingRevisionsPolicy === 'accept-all-first-keep-normalized') {
-            log('[OxmlEngine] Existing revisions detected; accepting all input revisions before redlining');
-            const accepted = acceptTrackedChangesInOoxml(inputOoxml, { allAuthors: true });
-            if (accepted.status === 'error') return finalize(accepted);
-            workingOoxml = accepted.oxml;
-            normalizedExistingRevisions = true;
-            const acceptedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
-            parseWarnings.push(...acceptedParsed.warnings);
-            xmlDoc = acceptedParsed.doc;
-            const acceptedParseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
-            if (acceptedParsed.error || acceptedParseError) {
-                const message = acceptedParsed.error?.message || acceptedParseError?.textContent || 'Could not parse OOXML after accepting existing revisions.';
-                error('[OxmlEngine] XML parse error after accepting existing revisions:', message);
-                return finalize({
-                    oxml: inputOoxml,
-                    hasChanges: false,
-                    status: 'error',
-                    error: {
-                        code: 'PARSE_ERROR',
-                        message
-                    }
-                });
-            }
-            seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
-        } else {
-            log('[OxmlEngine] Existing revisions detected; rejecting input per existingRevisions policy');
-            return finalize({
-                oxml: inputOoxml,
-                hasChanges: false,
-                status: 'error',
-                error: {
-                    code: 'EXISTING_REVISIONS',
-                    message: 'Input OOXML contains existing tracked changes and existingRevisions is "reject-input".'
-                }
-            });
-        }
-    }
-
-    const initialTableCellContext = detectTableCellContext(xmlDoc, originalText, options);
-    if (initialTableCellContext.hasTableWrapper && initialTableCellContext.targetParagraph && !options._isolatedTableCell) {
-        log('[OxmlEngine] Isolating table-cell paragraph before diff');
-        const isolatedOxml = serializeParagraphOnly(xmlDoc, initialTableCellContext.targetParagraph, serializer);
-        const isolatedResult = await applyRedlineToOxml(isolatedOxml, originalText, modifiedText, {
-            ...options,
-            _isolatedTableCell: true
-        });
-        if (!isolatedResult.hasChanges && isolatedResult.status === 'no-op') {
-            return finalizeUnchanged();
-        }
-        return isolatedResult;
-    }
-
-    let sanitizedText = options.sanitizeInput === true ? sanitizeAiResponse(modifiedText) : modifiedText;
-    if (sanitizedText !== modifiedText) {
-        operationWarnings.push('Input was sanitized; pass sanitizeInput: false to disable.');
-    }
-    let structuredAnalysis = null;
-    if (options.structuredContent !== false) {
-        structuredAnalysis = analyzeStructuredContent(sanitizedText);
-        if (!structuredAnalysis.valid) {
-            if (options.explicitStructuredContent === true) {
-                const message = structuredAnalysis.issues.map(issue => `${issue.code}: ${issue.message}`).join(' ');
-                return finalize({
-                    oxml: inputOoxml,
-                    hasChanges: false,
-                    status: 'error',
-                    error: { code: 'STRUCTURED_CONTENT_INVALID', message },
-                    warnings: structuredAnalysis.issues.map(issue => issue.message)
-                });
-            }
-            structuredAnalysis = null;
-        } else if (structuredAnalysis.requiresStructuredContent) {
-            sanitizedText = structuredAnalysis.normalizedMarkdown;
-        }
-    }
-    const { cleanText: cleanModifiedText, formatHints } = preprocessMarkdown(sanitizedText);
-
-    const hasTextChanges = existingRevisionsPolicy === 'slice-cross-author'
+            log('[OxmlEngine] Existing revisions detected; accepting all input revisions before redlining');
+            const accepted = acceptTrackedChangesInOoxml(inputOoxml, { allAuthors: true });
+            if (accepted.status === 'error') return finalize(accepted);
+            workingOoxml = accepted.oxml;
+            normalizedExistingRevisions = true;
+            const acceptedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
+            parseWarnings.push(...acceptedParsed.warnings);
+            xmlDoc = acceptedParsed.doc;
+            const acceptedParseError = xmlDoc ? getXmlParseError(xmlDoc) : null;
+            if (acceptedParsed.error || acceptedParseError) {
+                const message = acceptedParsed.error?.message || acceptedParseError?.textContent || 'Could not parse OOXML after accepting existing revisions.';
+                error('[OxmlEngine] XML parse error after accepting existing revisions:', message);
+                return finalize({
+                    oxml: inputOoxml,
+                    hasChanges: false,
+                    status: 'error',
+                    error: {
+                        code: 'PARSE_ERROR',
+                        message
+                    }
+                });
+            }
+            seedRevisionIdsFromDocument(xmlDoc, revisionIdAllocator);
+        } else {
+            log('[OxmlEngine] Existing revisions detected; rejecting input per existingRevisions policy');
+            return finalize({
+                oxml: inputOoxml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: 'EXISTING_REVISIONS',
+                    message: 'Input OOXML contains existing tracked changes and existingRevisions is "reject-input".'
+                }
+            });
+        }
+    }
+
+    const initialTableCellContext = detectTableCellContext(xmlDoc, originalText, options);
+    if (initialTableCellContext.hasTableWrapper && initialTableCellContext.targetParagraph && !options._isolatedTableCell) {
+        log('[OxmlEngine] Isolating table-cell paragraph before diff');
+        const isolatedOxml = serializeParagraphOnly(xmlDoc, initialTableCellContext.targetParagraph, serializer);
+        const isolatedResult = await applyRedlineToOxml(isolatedOxml, originalText, modifiedText, {
+            ...options,
+            _isolatedTableCell: true
+        });
+        if (!isolatedResult.hasChanges && isolatedResult.status === 'no-op') {
+            return finalizeUnchanged();
+        }
+        return isolatedResult;
+    }
+
+    let sanitizedText = options.sanitizeInput === true ? sanitizeAiResponse(modifiedText) : modifiedText;
+    if (sanitizedText !== modifiedText) {
+        operationWarnings.push('Input was sanitized; pass sanitizeInput: false to disable.');
+    }
+    let structuredAnalysis = null;
+    if (options.structuredContent !== false && options.literalTextEdit !== true) {
+        structuredAnalysis = analyzeStructuredContent(sanitizedText);
+        if (!structuredAnalysis.valid) {
+            if (options.explicitStructuredContent === true) {
+                const message = structuredAnalysis.issues.map(issue => `${issue.code}: ${issue.message}`).join(' ');
+                return finalize({
+                    oxml: inputOoxml,
+                    hasChanges: false,
+                    status: 'error',
+                    error: { code: 'STRUCTURED_CONTENT_INVALID', message },
+                    warnings: structuredAnalysis.issues.map(issue => issue.message)
+                });
+            }
+            structuredAnalysis = null;
+        } else if (structuredAnalysis.requiresStructuredContent) {
+            sanitizedText = structuredAnalysis.normalizedMarkdown;
+        }
+    }
+    const { cleanText: cleanModifiedText, formatHints } = preprocessMarkdown(sanitizedText);
+
+    const { existingFormatHints, textSpans, paragraphs } = extractFormattingFromOoxml(xmlDoc);
+    const hasLiteralTextChanges = existingRevisionsPolicy === 'slice-cross-author'
         ? cleanModifiedText !== originalText
         : cleanModifiedText.trim() !== originalText.trim();
-    const hasFormatHints = formatHints.length > 0;
-
-    const { existingFormatHints, textSpans, paragraphs } = extractFormattingFromOoxml(xmlDoc);
-    const hasExistingFormatting = existingFormatHints.length > 0;
-    const visibleText = textSpans.map(span => textSpanVisibleText(span)).join('');
-    const targetFound = originalText.includes('\n') || originalText.includes('\r')
-        ? originalText
-            .split(/\r?\n/)
-            .map(normalizeTargetText)
-            .filter(Boolean)
-            .every(line => paragraphs.some(paragraph => {
-                const paragraphText = textSpans
-                    .filter(span => span.paragraph === paragraph)
-                    .map(textSpanVisibleText)
-                    .join('');
-                return normalizeTargetText(paragraphText).includes(line);
-            }))
-        : visibleText.includes(originalText.trim())
-            || visibleText.replace(/[\t\n\u2011]/g, '').includes(originalText.trim().replace(/[\t\n\u2011]/g, ''))
-            || normalizeTargetText(visibleText).includes(normalizeTargetText(originalText));
-    if (
-        hasTextChanges
-        && typeof originalText === 'string'
-        && originalText.trim()
-        && !targetFound
-    ) {
-        log('[OxmlEngine] Target text not found in OOXML');
-        return finalize({
-            oxml: inputOoxml,
-            hasChanges: false,
-            status: 'error',
-            error: {
-                code: 'TARGET_NOT_FOUND',
-                message: 'Original text was not found in the supplied OOXML.'
-            }
-        });
-    }
-    let paragraphInfos = null;
-    const getParagraphInfos = () => {
-        if (!paragraphInfos) {
-            paragraphInfos = buildParagraphInfos(xmlDoc, paragraphs, textSpans);
-        }
-        return paragraphInfos;
-    };
-    const applyFormatOnlyWithOoxmlFallback = (precomputedContext = null) => {
-        const formatResult = applyFormatOnlyChangesSurgical(
-            xmlDoc,
-            originalText,
-            formatHints,
-            serializer,
-            author,
-            generateRedlines,
-            precomputedContext
-        );
-        if (!formatResult.useNativeApi) {
-            return formatResult;
-        }
-
-        log('[OxmlEngine] Format-only surgical fallback signal encountered; retrying with OOXML reconstruction fallback');
-        return applyReconstructionMode(
-            xmlDoc,
-            originalText,
-            cleanModifiedText,
-            serializer,
-            author,
-            formatHints,
-            generateRedlines
-        );
-    };
-
-    log(`[OxmlEngine] Text changes: ${hasTextChanges}, New format hints: ${formatHints.length}, Existing format hints: ${existingFormatHints.length}`);
-
-    const needsFormatRemoval = options.removeFormatting === true
-        && !hasTextChanges
-        && !hasFormatHints
-        && hasExistingFormatting;
-
-    if (!hasTextChanges && !hasFormatHints && !hasExistingFormatting) {
-        recordRouteSelection(options, 'noChange');
-        log('[OxmlEngine] No text changes, no format hints, and no existing formatting detected');
-        return finalizeUnchanged();
-    }
-
-    if (!hasTextChanges && !hasFormatHints && hasExistingFormatting && !needsFormatRemoval) {
-        log('[OxmlEngine] No text or explicit formatting changes; preserving existing formatting');
-        return finalizeUnchanged();
-    }
-
-    if (needsFormatRemoval) {
-        recordRouteSelection(options, 'formatOnly', { removeFormatting: true });
-        log('[OxmlEngine] Format REMOVAL detected: applying surgical replacement in OOXML');
-
-        const tableCellCtx = initialTableCellContext;
-        let targetParagraph = tableCellCtx.targetParagraph || null;
-
-        if (!targetParagraph) {
-            const matchedInfo = findMatchingParagraphInfo(getParagraphInfos(), originalText);
-            if (matchedInfo) {
-                targetParagraph = matchedInfo.paragraph;
-            }
-        }
-
-        let filteredHints = existingFormatHints;
-        if (targetParagraph) {
-            filteredHints = existingFormatHints.filter(hint => {
-                const hintParagraph = getContainingParagraph(hint.run);
-                return hintParagraph === targetParagraph;
-            });
-        }
-
-        const removalResult = applyFormatRemovalAsSurgicalReplacement(
-            xmlDoc,
-            textSpans,
-            filteredHints,
-            serializer,
-            author,
-            generateRedlines
-        );
-
-        if (tableCellCtx.hasTableWrapper && targetParagraph) {
-            return finalize({
-                oxml: serializeParagraphOnly(xmlDoc, targetParagraph, serializer),
-                hasChanges: removalResult.hasChanges
-            });
-        }
-
-        return finalize(removalResult);
-    }
-
-    if (!hasTextChanges && hasFormatHints) {
-        recordRouteSelection(options, 'formatOnly', { removeFormatting: false });
-        log(`[OxmlEngine] Format-only change detected: ${formatHints.length} format hints`);
-
-        const tableCellCtx = initialTableCellContext;
-        const precomputedFormatContext = {
-            textSpans,
-            paragraphs,
-            paragraphInfos: getParagraphInfos()
-        };
-        if (tableCellCtx.hasTableWrapper && tableCellCtx.targetParagraph) {
-            log('[OxmlEngine] Table cell context: applying formatting to target paragraph only');
-
-            const formatResult = applyFormatOnlyWithOoxmlFallback(precomputedFormatContext);
-
-            log('[OxmlEngine] Stripping table wrapper for table cell paragraph (format-only)');
-            return finalize({
-                oxml: serializeParagraphOnly(xmlDoc, tableCellCtx.targetParagraph, serializer),
-                hasChanges: formatResult.hasChanges
-            });
-        }
-
-        return finalize(applyFormatOnlyWithOoxmlFallback(precomputedFormatContext));
-    }
-
-    const tables = getElementsByTagNSOrTag(xmlDoc, NS_W, 'tbl');
-    const hasTables = tables.length > 0;
-    const isMarkdownTable = /^\|.+\|/.test(cleanModifiedText.trim()) && cleanModifiedText.includes('\n');
-    const isTargetList = isListTargetLoose(cleanModifiedText);
-    const isStructuredContent = options.structuredContent !== false && structuredAnalysis?.requiresStructuredContent === true;
-    const tableCellContext = initialTableCellContext;
-
+    // Markdown list markers can equal manually typed ones ("A. ..." lines), so
+    // an explicit structured-content request that turns plain paragraphs or
+    // soft-break lines into a list is a change even when the text is identical.
+    const hasListStructureChange = !hasLiteralTextChanges
+        && options.explicitStructuredContent === true
+        && isListTargetLoose(cleanModifiedText)
+        && !sourceMatchesListShape(paragraphs, cleanModifiedText);
+    const hasTextChanges = hasLiteralTextChanges || hasListStructureChange;
+    const hasFormatHints = formatHints.length > 0;
+    const hasExistingFormatting = existingFormatHints.length > 0;
+    // Formatting spans carry only w:t text. Target matching also needs w:br,
+    // w:cr and w:tab so host text with soft line breaks (Word's Paragraph.text
+    // reports them as "\v") still matches its source paragraph.
+    const { textSpans: targetSpans } = buildTextSpansFromParagraphs(paragraphs);
+    const visibleText = targetSpans.map(span => textSpanVisibleText(span)).join('');
+    const targetFound = originalText.includes('\n') || originalText.includes('\r')
+        ? originalText
+            .split(/\r?\n/)
+            .map(normalizeTargetText)
+            .filter(Boolean)
+            .every(line => paragraphs.some(paragraph => {
+                const paragraphText = targetSpans
+                    .filter(span => span.paragraph === paragraph)
+                    .map(textSpanVisibleText)
+                    .join('');
+                return normalizeTargetText(paragraphText).includes(line);
+            }))
+        : visibleText.includes(originalText.trim())
+            || visibleText.replace(/[\t\n\u2011]/g, '').includes(originalText.trim().replace(/[\t\n\u2011]/g, ''))
+            || normalizeTargetText(visibleText).includes(normalizeTargetText(originalText));
+    if (
+        hasTextChanges
+        && typeof originalText === 'string'
+        && originalText.trim()
+        && !targetFound
+    ) {
+        log('[OxmlEngine] Target text not found in OOXML');
+        return finalize({
+            oxml: inputOoxml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'TARGET_NOT_FOUND',
+                message: 'Original text was not found in the supplied OOXML.'
+            }
+        });
+    }
+    let paragraphInfos = null;
+    const getParagraphInfos = () => {
+        if (!paragraphInfos) {
+            paragraphInfos = buildParagraphInfos(xmlDoc, paragraphs, textSpans);
+        }
+        return paragraphInfos;
+    };
+    const applyFormatOnlyWithOoxmlFallback = (precomputedContext = null) => {
+        const formatResult = applyFormatOnlyChangesSurgical(
+            xmlDoc,
+            originalText,
+            formatHints,
+            serializer,
+            author,
+            generateRedlines,
+            precomputedContext
+        );
+        if (!formatResult.useNativeApi) {
+            return formatResult;
+        }
+
+        log('[OxmlEngine] Format-only surgical fallback signal encountered; retrying with OOXML reconstruction fallback');
+        return applyReconstructionMode(
+            xmlDoc,
+            originalText,
+            cleanModifiedText,
+            serializer,
+            author,
+            formatHints,
+            generateRedlines
+        );
+    };
+
+    log(`[OxmlEngine] Text changes: ${hasTextChanges}, New format hints: ${formatHints.length}, Existing format hints: ${existingFormatHints.length}`);
+
+    const needsFormatRemoval = options.removeFormatting === true
+        && !hasTextChanges
+        && !hasFormatHints
+        && hasExistingFormatting;
+
+    if (!hasTextChanges && !hasFormatHints && !hasExistingFormatting) {
+        recordRouteSelection(options, 'noChange');
+        log('[OxmlEngine] No text changes, no format hints, and no existing formatting detected');
+        return finalizeUnchanged();
+    }
+
+    if (!hasTextChanges && !hasFormatHints && hasExistingFormatting && !needsFormatRemoval) {
+        log('[OxmlEngine] No text or explicit formatting changes; preserving existing formatting');
+        return finalizeUnchanged();
+    }
+
+    if (needsFormatRemoval) {
+        recordRouteSelection(options, 'formatOnly', { removeFormatting: true });
+        log('[OxmlEngine] Format REMOVAL detected: applying surgical replacement in OOXML');
+
+        const tableCellCtx = initialTableCellContext;
+        let targetParagraph = tableCellCtx.targetParagraph || null;
+
+        if (!targetParagraph) {
+            const matchedInfo = findMatchingParagraphInfo(getParagraphInfos(), originalText);
+            if (matchedInfo) {
+                targetParagraph = matchedInfo.paragraph;
+            }
+        }
+
+        let filteredHints = existingFormatHints;
+        if (targetParagraph) {
+            filteredHints = existingFormatHints.filter(hint => {
+                const hintParagraph = getContainingParagraph(hint.run);
+                return hintParagraph === targetParagraph;
+            });
+        }
+
+        const removalResult = applyFormatRemovalAsSurgicalReplacement(
+            xmlDoc,
+            textSpans,
+            filteredHints,
+            serializer,
+            author,
+            generateRedlines
+        );
+
+        if (tableCellCtx.hasTableWrapper && targetParagraph) {
+            return finalize({
+                oxml: serializeParagraphOnly(xmlDoc, targetParagraph, serializer),
+                hasChanges: removalResult.hasChanges
+            });
+        }
+
+        return finalize(removalResult);
+    }
+
+    if (!hasTextChanges && hasFormatHints) {
+        recordRouteSelection(options, 'formatOnly', { removeFormatting: false });
+        log(`[OxmlEngine] Format-only change detected: ${formatHints.length} format hints`);
+
+        const tableCellCtx = initialTableCellContext;
+        const precomputedFormatContext = {
+            textSpans,
+            paragraphs,
+            paragraphInfos: getParagraphInfos()
+        };
+        if (tableCellCtx.hasTableWrapper && tableCellCtx.targetParagraph) {
+            log('[OxmlEngine] Table cell context: applying formatting to target paragraph only');
+
+            const formatResult = applyFormatOnlyWithOoxmlFallback(precomputedFormatContext);
+
+            log('[OxmlEngine] Stripping table wrapper for table cell paragraph (format-only)');
+            return finalize({
+                oxml: serializeParagraphOnly(xmlDoc, tableCellCtx.targetParagraph, serializer),
+                hasChanges: formatResult.hasChanges
+            });
+        }
+
+        return finalize(applyFormatOnlyWithOoxmlFallback(precomputedFormatContext));
+    }
+
+    const tables = getElementsByTagNSOrTag(xmlDoc, NS_W, 'tbl');
+    const hasTables = tables.length > 0;
+    const isMarkdownTable = /^\|.+\|/.test(cleanModifiedText.trim()) && cleanModifiedText.includes('\n');
+    // Localized replacements are literal text edits: marker-like lines ("A. ..." separated by
+    // soft breaks) must not be re-interpreted as a request to build a numbered list.
+    const isTargetList = options.literalTextEdit !== true && isListTargetLoose(cleanModifiedText);
+    const isStructuredContent = options.structuredContent !== false && structuredAnalysis?.requiresStructuredContent === true;
+    const tableCellContext = initialTableCellContext;
+
     const usesSurgicalTextMode = hasTables || existingRevisionsPolicy === 'slice-cross-author';
     log(`[OxmlEngine] Mode: ${usesSurgicalTextMode ? 'SURGICAL' : 'RECONSTRUCTION'}, formatHints: ${formatHints.length}, isMarkdownTable: ${isMarkdownTable}, isTargetList: ${isTargetList}, isTableCellParagraph: ${tableCellContext.isTableCellParagraph}`);
-
-    try {
-    if (isMarkdownTable && !hasTables) {
-        recordRouteSelection(options, 'table', { transformation: 'text-to-table' });
-        log('[OxmlEngine] Text-to-table transformation: generating new table from Markdown');
-        return finalize(applyTextToTableTransformation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
-    }
-
-    if (hasTables && isMarkdownTable) {
-        recordRouteSelection(options, 'table', { transformation: 'table-reconciliation' });
-        return finalize(applyTableReconciliation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
-    }
+
+    try {
+    if (isMarkdownTable && !hasTables) {
+        recordRouteSelection(options, 'table', { transformation: 'text-to-table' });
+        log('[OxmlEngine] Text-to-table transformation: generating new table from Markdown');
+        return finalize(applyTextToTableTransformation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
+    }
+
+    if (hasTables && isMarkdownTable) {
+        recordRouteSelection(options, 'table', { transformation: 'table-reconciliation' });
+        return finalize(applyTableReconciliation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
+    }
     if (usesSurgicalTextMode) {
         recordRouteSelection(options, 'surgical', { tableScoped: hasTables });
-        const surgicalTarget = tableCellContext.hasTableWrapper && tableCellContext.targetParagraph
-            ? tableCellContext.targetParagraph
-            : null;
-        if (surgicalTarget) {
-            log('[OxmlEngine] Table cell edit: scoping surgical mode to target paragraph');
-        }
-
+        const surgicalTarget = tableCellContext.hasTableWrapper && tableCellContext.targetParagraph
+            ? tableCellContext.targetParagraph
+            : null;
+        if (surgicalTarget) {
+            log('[OxmlEngine] Table cell edit: scoping surgical mode to target paragraph');
+        }
+
         const result = applySurgicalMode(
-            xmlDoc,
-            originalText,
-            cleanModifiedText,
-            serializer,
-            author,
-            formatHints,
-            generateRedlines,
-            surgicalTarget,
-            {},
+            xmlDoc,
+            originalText,
+            cleanModifiedText,
+            serializer,
+            author,
+            formatHints,
+            generateRedlines,
+            surgicalTarget,
+            {},
             options
         );
 
@@ -600,130 +599,138 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
         }
 
         if (tableCellContext.hasTableWrapper && result.hasChanges && tableCellContext.targetParagraph) {
-            log('[OxmlEngine] Stripping table wrapper for table cell paragraph (surgical mode)');
-            return finalize({ oxml: serializeParagraphOnly(xmlDoc, tableCellContext.targetParagraph, serializer), hasChanges: true });
-        }
-        return finalize(result);
-    }
-    if (isTargetList || isStructuredContent) {
-        const sourceParagraphs = getElementsByTagNSOrTag(xmlDoc, NS_W, 'p');
-        const useDirectListGeneration = sourceParagraphs.length === 1;
-        recordRouteSelection(options, useDirectListGeneration ? 'listDirect' : 'listCompatibilityPipeline', {
-            sourceParagraphCount: sourceParagraphs.length
-        });
-        log(`[OxmlEngine] 🎯 Using ${useDirectListGeneration ? 'direct list generation' : 'compatibility pipeline'} for list reconciliation`);
-        let result;
-        if (useDirectListGeneration) {
-            const ingested = ingestOoxml(workingOoxml, { xmlDoc });
-            const numberingContext = detectNumberingContext(sourceParagraphs[0]);
-            result = await executeListGeneration({
-                cleanText: cleanModifiedText,
-                numberingContext,
-                originalRunModel: ingested.runModel,
-                originalText: ingested.acceptedText,
-                generateRedlines,
-                author,
-                font: options.font || null,
-                revisionIdAllocator,
-                numberingService: new NumberingService()
-            });
-        } else {
-            const pipeline = new ReconciliationPipeline({
-                author,
-                generateRedlines,
-                revisionIdAllocator
-            });
-            result = await pipeline.execute(workingOoxml, sanitizedText, { xmlDoc });
-        }
-
-        if (result.error?.code === 'DIFF_TOKEN_LIMIT') {
-            return finalize({ oxml: inputOoxml, hasChanges: false, status: 'error', error: result.error });
-        }
-
-        if (result.isValid && result.ooxml && result.ooxml !== workingOoxml) {
-            const includeNumbering = result.includeNumbering === true;
-            log(`[OxmlEngine] Wrapping list OOXML with numbering definitions, includeNumbering=${includeNumbering}`);
-            const wrapped = wrapInDocumentFragment(result.ooxml, {
-                includeNumbering,
-                numberingXml: result.numberingXml
-            });
-            log(`[OxmlEngine] ✅ Wrapped OOXML length: ${wrapped.length}`);
-            return finalize({
-                oxml: wrapped,
-                hasChanges: true,
-                ...(Array.isArray(result.warnings) ? { warnings: result.warnings } : {})
-            });
-        }
-        return finalizeUnchanged();
-    }
-
-    recordRouteSelection(options, 'reconstruction');
-    return finalize(applyReconstructionMode(
-        xmlDoc,
-        originalText,
-        cleanModifiedText,
-        serializer,
-        author,
-        formatHints,
-        generateRedlines,
-        {},
-        options
-    ));
-    } catch (caught) {
-        if (isDiffTokenLimitError(caught)) {
-            return finalize({
-                oxml: inputOoxml,
-                hasChanges: false,
-                status: 'error',
-                error: { code: caught.code, message: caught.message }
-            });
-        }
-        throw caught;
-    }
-}
-
-function normalizeTargetText(text) {
-    return String(text || '').replace(/[\t\n\u2011]/g, ' ').replace(/\s+/g, ' ').trim();
-}
-
-function textSpanVisibleText(span) {
-    const node = span?.textElement;
-    const localName = String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
-    if (localName === 'tab') return '\t';
-    if (localName === 'br' || localName === 'cr') return '\n';
-    if (localName === 'noBreakHyphen') return '\u2011';
-    return node?.textContent || '';
-}
-
-/**
- * Sanitizes AI response text by removing common prefixes.
- *
- * @param {string} text - AI response text
- * @returns {string}
- */
-export function sanitizeAiResponse(text) {
-    return String(text ?? '').replace(
-        /^(?:Here is the redline:|Here is the text:|Sure, I can help:|Here's the updated text:)[ \t]*\r?\n/i,
-        ''
-    );
-}
-
-/**
- * Parses OOXML into a DOM document.
- *
- * @param {string} ooxmlString - OOXML text
- * @returns {Document}
- */
-export function parseOoxml(ooxmlString) {
-    return parseOoxmlSafe(ooxmlString, 'application/xml').doc;
-}
-
-/**
- * Serializes a DOM document to OOXML text.
- *
- * @param {Node} doc - XML document/node
- * @returns {string}
- */
-export function serializeOoxml(doc) {
-    return serializeXml(doc);
-}
+            log('[OxmlEngine] Stripping table wrapper for table cell paragraph (surgical mode)');
+            return finalize({ oxml: serializeParagraphOnly(xmlDoc, tableCellContext.targetParagraph, serializer), hasChanges: true });
+        }
+        return finalize(result);
+    }
+    if (isTargetList || isStructuredContent) {
+        const sourceParagraphs = getElementsByTagNSOrTag(xmlDoc, NS_W, 'p');
+        const useDirectListGeneration = sourceParagraphs.length === 1;
+        recordRouteSelection(options, useDirectListGeneration ? 'listDirect' : 'listCompatibilityPipeline', {
+            sourceParagraphCount: sourceParagraphs.length
+        });
+        log(`[OxmlEngine] 🎯 Using ${useDirectListGeneration ? 'direct list generation' : 'compatibility pipeline'} for list reconciliation`);
+        let result;
+        if (useDirectListGeneration) {
+            const ingested = ingestOoxml(workingOoxml, { xmlDoc });
+            const numberingContext = detectNumberingContext(sourceParagraphs[0]);
+            result = await executeListGeneration({
+                cleanText: cleanModifiedText,
+                numberingContext,
+                originalRunModel: ingested.runModel,
+                originalText: ingested.acceptedText,
+                generateRedlines,
+                author,
+                font: options.font || null,
+                revisionIdAllocator,
+                numberingService: new NumberingService()
+            });
+        } else {
+            const pipeline = new ReconciliationPipeline({
+                author,
+                generateRedlines,
+                revisionIdAllocator
+            });
+            result = await pipeline.execute(workingOoxml, sanitizedText, { xmlDoc });
+        }
+
+        if (result.error?.code === 'DIFF_TOKEN_LIMIT') {
+            return finalize({ oxml: inputOoxml, hasChanges: false, status: 'error', error: result.error });
+        }
+
+        if (result.isValid && result.ooxml && result.ooxml !== workingOoxml) {
+            const includeNumbering = result.includeNumbering === true;
+            log(`[OxmlEngine] Wrapping list OOXML with numbering definitions, includeNumbering=${includeNumbering}`);
+            const wrapped = wrapInDocumentFragment(result.ooxml, {
+                includeNumbering,
+                numberingXml: result.numberingXml
+            });
+            log(`[OxmlEngine] ✅ Wrapped OOXML length: ${wrapped.length}`);
+            return finalize({
+                oxml: wrapped,
+                hasChanges: true,
+                ...(Array.isArray(result.warnings) ? { warnings: result.warnings } : {})
+            });
+        }
+        return finalizeUnchanged();
+    }
+
+    recordRouteSelection(options, 'reconstruction');
+    return finalize(applyReconstructionMode(
+        xmlDoc,
+        originalText,
+        cleanModifiedText,
+        serializer,
+        author,
+        formatHints,
+        generateRedlines,
+        {},
+        options
+    ));
+    } catch (caught) {
+        if (isDiffTokenLimitError(caught)) {
+            return finalize({
+                oxml: inputOoxml,
+                hasChanges: false,
+                status: 'error',
+                error: { code: caught.code, message: caught.message }
+            });
+        }
+        throw caught;
+    }
+}
+
+function sourceMatchesListShape(paragraphs, listText) {
+    const itemCount = String(listText).split(/\r?\n/).filter(line => line.trim()).length;
+    return paragraphs.length === itemCount && paragraphs.every(paragraph => (
+        // Current numPr only; a pPrChange snapshot does not make the source a list.
+        getCurrentParagraphProperties(paragraph).numPr != null
+    ));
+}
+
+function normalizeTargetText(text) {
+    return String(text || '').replace(/[\t\n\u2011]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function textSpanVisibleText(span) {
+    const node = span?.textElement;
+    const localName = String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
+    if (localName === 'tab') return '\t';
+    if (localName === 'br' || localName === 'cr') return '\n';
+    if (localName === 'noBreakHyphen') return '\u2011';
+    return node?.textContent || '';
+}
+
+/**
+ * Sanitizes AI response text by removing common prefixes.
+ *
+ * @param {string} text - AI response text
+ * @returns {string}
+ */
+export function sanitizeAiResponse(text) {
+    return String(text ?? '').replace(
+        /^(?:Here is the redline:|Here is the text:|Sure, I can help:|Here's the updated text:)[ \t]*\r?\n/i,
+        ''
+    );
+}
+
+/**
+ * Parses OOXML into a DOM document.
+ *
+ * @param {string} ooxmlString - OOXML text
+ * @returns {Document}
+ */
+export function parseOoxml(ooxmlString) {
+    return parseOoxmlSafe(ooxmlString, 'application/xml').doc;
+}
+
+/**
+ * Serializes a DOM document to OOXML text.
+ *
+ * @param {Node} doc - XML document/node
+ * @returns {string}
+ */
+export function serializeOoxml(doc) {
+    return serializeXml(doc);
+}