@ansonlai/docx-redline-js 0.2.0 → 0.4.0

package/engine/reconstruction-writer.js

@@ -11,8 +11,9 @@ import {
     markParagraphMarkDeleted,
     markParagraphMarkInserted
 } from './run-builders.js';
-import { getFirstElementByTag } from '../core/xml-query.js';
-import { createWordElement } from '../core/word-xml.js';
+import { getFirstElementByTagNSOrTag } from '../core/xml-query.js';
+import { NS_W } from '../core/types.js';
+import { createWordElement, isWordElement } from '../core/word-xml.js';
 
 /**
  * Applies diffs to reconstruction context and writes updated XML.
@@ -28,9 +29,8 @@ import { createWordElement } from '../core/word-xml.js';
  */
 export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, author, formatHints, generateRedlines = true) {
     const {
-        paragraphs,
-        paragraphMap,
-        containerFragments,
+        paragraphs,
+        containerFragments,
         sentinelMapByStart,
         referenceMap,
         replacementContainers,
@@ -55,12 +55,23 @@ 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).
+    let pendingReplacementStart = null;
     const emittedCommentMarkers = new WeakSet();
-
-    for (const [op, text] of diffs) {
-        if (op === 0 || op === -1) {
-            const type = op === 0 ? 'equal' : 'delete';
-            let offset = 0;
+
+    for (const [op, text] of diffs) {
+        if (op === 0 || op === -1) {
+            const type = op === 0 ? 'equal' : 'delete';
+            if (op === 0) {
+                pendingReplacementStart = null;
+            } else if (pendingReplacementStart === null) {
+                pendingReplacementStart = currentOriginalIndex;
+            }
+            let offset = 0;
 
             while (offset < text.length) {
                 const chunkStart = currentOriginalIndex + offset;
@@ -99,11 +110,14 @@ export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, aut
             currentOriginalIndex += text.length;
             continue;
         }
-
-        if (op === 1) {
-            const properties = currentOriginalIndex > 0 && !isParagraphStart(currentOriginalIndex)
-                ? getRunProperties(currentOriginalIndex - 1)
-                : getRunProperties(currentOriginalIndex);
+
+        if (op === 1) {
+            const propertyIndex = pendingReplacementStart !== null
+                ? pendingReplacementStart
+                : (currentOriginalIndex > 0 && !isParagraphStart(currentOriginalIndex)
+                    ? currentOriginalIndex - 1
+                    : currentOriginalIndex);
+            const properties = getRunProperties(propertyIndex);
 
             const appendResult = appendTextToCurrent(
                 xmlDoc,
@@ -127,69 +141,93 @@ export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, aut
             );
             currentParagraph = appendResult.currentParagraph;
             currentInsertOffset += text.length;
+            pendingReplacementStart = null;
         }
     }
 
-    paragraphs.forEach(paragraph => {
-        if (paragraph.parentNode) {
-            paragraph.parentNode.removeChild(paragraph);
-        }
-    });
-
-    containerFragments.forEach((fragment, container) => {
-        const replacement = replacementContainers.get(container);
-        const target = replacement || container;
-
-        if (target.nodeType === 9) {
-            const firstChild = fragment.firstChild;
-            if (firstChild) {
-                target.appendChild(firstChild);
-                while (fragment.firstChild) {
-                    target.documentElement.appendChild(fragment.firstChild);
-                }
-            }
-            return;
-        }
-
-        target.appendChild(fragment);
-    });
-
-    return { oxml: serializer.serializeToString(xmlDoc), hasChanges: true };
-}
-
-function appendTextToCurrent(
-    xmlDoc,
-    text,
-    type,
-    rPr,
-    wrapper,
-    baseIndex,
-    currentParagraphRef,
-    containerFragments,
-    sentinelMapByStart,
-    referenceMap,
-    replacementContainers,
-    getParagraphInfo,
-    createNewParagraph,
-    author,
-    formatHints = [],
-    insertOffset = 0,
+    const paragraphSet = new Set(paragraphs);
+    const insertionAnchors = new Map();
+    paragraphs.forEach(paragraph => {
+        const container = paragraph.parentNode;
+        if (!container || insertionAnchors.has(container)) return;
+        let anchor = paragraph.nextSibling;
+        while (anchor && paragraphSet.has(anchor)) anchor = anchor.nextSibling;
+        insertionAnchors.set(container, anchor);
+    });
+
+    paragraphs.forEach(paragraph => {
+        if (paragraph.parentNode) {
+            paragraph.parentNode.removeChild(paragraph);
+        }
+    });
+
+    let hasDocumentTarget = false;
+    let serializedDocumentOutput = '';
+
+    containerFragments.forEach((fragment, container) => {
+        const replacement = replacementContainers.get(container);
+        const target = replacement || container;
+
+        if (target.nodeType === 9) {
+            hasDocumentTarget = true;
+            if (fragment.childNodes.length === 1) {
+                target.appendChild(fragment.firstChild);
+            } else {
+                serializedDocumentOutput = Array.from(fragment.childNodes)
+                    .map(node => serializer.serializeToString(node))
+                    .join('');
+            }
+            return;
+        }
+
+        const anchor = replacement ? null : insertionAnchors.get(container);
+        if (anchor && anchor.parentNode === target) {
+            target.insertBefore(fragment, anchor);
+        } else {
+            target.appendChild(fragment);
+        }
+    });
+
+    const oxml = (hasDocumentTarget && serializedDocumentOutput)
+        ? serializedDocumentOutput
+        : serializer.serializeToString(xmlDoc);
+
+    return { oxml, hasChanges: true };
+}
+
+function appendTextToCurrent(
+    xmlDoc,
+    text,
+    type,
+    rPr,
+    wrapper,
+    baseIndex,
+    currentParagraphRef,
+    containerFragments,
+    sentinelMapByStart,
+    referenceMap,
+    replacementContainers,
+    getParagraphInfo,
+    createNewParagraph,
+    author,
+    formatHints = [],
+    insertOffset = 0,
     generateRedlines = true,
     emittedCommentMarkers = new WeakSet()
 ) {
-    let localBaseIndex = baseIndex;
-    let localInsertOffset = insertOffset;
-    let localParagraph = currentParagraphRef;
-
-    const parts = text.split(/([\n\uFFFC]|[\uE000-\uF8FF])/);
-
-    parts.forEach(part => {
-        const sentinelsAtOffset = sentinelMapByStart.get(localBaseIndex) || [];
+    let localBaseIndex = baseIndex;
+    let localInsertOffset = insertOffset;
+    let localParagraph = currentParagraphRef;
+
+    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));
 
         commentMarkers.forEach(marker => {
             emittedCommentMarkers.add(marker.node);
-            if (marker.node.nodeName === 'w:commentReference') {
+            if (isWordElement(marker.node, 'commentReference')) {
                 const run = createWordElement(xmlDoc, 'w:r');
                 run.appendChild(marker.node.cloneNode(true));
                 localParagraph.appendChild(run);
@@ -202,9 +240,9 @@ function appendTextToCurrent(
             const info = getParagraphInfo(localBaseIndex + 1);
             const nextParagraph = createNewParagraph(info.pPr);
             if (generateRedlines && type === 'insert') {
-                markParagraphMarkInserted(xmlDoc, nextParagraph, author);
+                markParagraphMarkInserted(xmlDoc, localParagraph, author);
             } else if (generateRedlines && type === 'delete') {
-                markParagraphMarkDeleted(xmlDoc, nextParagraph, author);
+                markParagraphMarkDeleted(xmlDoc, localParagraph, author);
             }
 
             const fragment = containerFragments.get(info.container);
@@ -222,13 +260,20 @@ function appendTextToCurrent(
             if (sentinel) {
                 const clone = sentinel.node.cloneNode(true);
                 if (sentinel.isTextBox && sentinel.originalContainer) {
-                    const newContainer = getFirstElementByTag(clone, 'w:txbxContent');
+                    const newContainer = getFirstElementByTagNSOrTag(clone, NS_W, 'txbxContent');
                     if (newContainer) {
                         while (newContainer.firstChild) newContainer.removeChild(newContainer.firstChild);
                         replacementContainers.set(sentinel.originalContainer, newContainer);
                     }
                 }
-                localParagraph.appendChild(clone);
+                if (sentinel.wrapInRun) {
+                    const run = createWordElement(xmlDoc, 'w:r');
+                    if (sentinel.rPr) run.appendChild(sentinel.rPr.cloneNode(true));
+                    run.appendChild(clone);
+                    localParagraph.appendChild(run);
+                } else {
+                    localParagraph.appendChild(clone);
+                }
             }
             localBaseIndex++;
             if (type !== 'delete') localInsertOffset++;

package/engine/run-builders.js

@@ -5,7 +5,7 @@
  * and `w:pPrChange` elements used by surgical and reconstruction modes.
  */
 
-import { RPR_SCHEMA_ORDER } from './rpr-helpers.js';
+import { extractFormatFromRPr, RPR_SCHEMA_ORDER } from './rpr-helpers.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { getFirstElementByTag } from '../core/xml-query.js';
 import { createWordElement } from '../core/word-xml.js';
@@ -21,7 +21,7 @@ import { createWordElement } from '../core/word-xml.js';
  */
 export function createTrackChange(xmlDoc, type, run, author) {
     const wrapper = createWordElement(xmlDoc, type === 'ins' ? 'w:ins' : 'w:del');
-    const metadata = createRevisionMetadata(author);
+    const metadata = createRevisionMetadata(author, xmlDoc);
     wrapper.setAttribute('w:id', String(metadata.id));
     wrapper.setAttribute('w:author', metadata.author);
     wrapper.setAttribute('w:date', metadata.date);
@@ -70,7 +70,7 @@ function markParagraphMark(xmlDoc, paragraph, author, type) {
     }
 
     const marker = createWordElement(xmlDoc, type === 'ins' ? 'w:ins' : 'w:del');
-    const metadata = createRevisionMetadata(author);
+    const metadata = createRevisionMetadata(author, xmlDoc);
     marker.setAttribute('w:id', String(metadata.id));
     marker.setAttribute('w:author', metadata.author);
     marker.setAttribute('w:date', metadata.date);
@@ -140,8 +140,8 @@ export function createTextRun(xmlDoc, text, rPr, isDelete) {
  * @param {boolean} [generateRedlines] - Whether to create rPrChange
  * @returns {Element[]}
  */
-export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffset, author, generateRedlines) {
-    if (!text) return [];
+export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffset, author, generateRedlines) {
+    if (!text) return [];
 
     const breaks = new Set([0, text.length]);
     for (const hint of formatHints) {
@@ -167,13 +167,17 @@ export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffs
             h.start <= segmentBaseOffset && h.end >= segmentEndOffset
         );
 
-        const combinedFormat = {};
-        applicableHints.forEach(h => {
-            if (h.format) Object.assign(combinedFormat, h.format);
-        });
-
-        const formattedRPr = injectFormattingToRPr(xmlDoc, baseRPr, combinedFormat, author, generateRedlines);
-        runs.push(createTextRunWithRPrElement(xmlDoc, segment, formattedRPr, false));
+        const combinedFormat = { ...extractFormatFromRPr(baseRPr) };
+        applicableHints.forEach(h => {
+            if (h.format) Object.assign(combinedFormat, h.format);
+        });
+
+        // During a text edit, missing Markdown is not an instruction to clear
+        // the source run's formatting. Only synchronize explicitly hinted spans.
+        const formattedRPr = applicableHints.length > 0
+            ? injectFormattingToRPr(xmlDoc, baseRPr, combinedFormat, author, generateRedlines)
+            : baseRPr?.cloneNode(true) || null;
+        runs.push(createTextRunWithRPrElement(xmlDoc, segment, formattedRPr, false));
     }
 
     return runs;
@@ -307,7 +311,7 @@ export function injectFormattingToRPr(xmlDoc, baseRPr, format, author, generateR
  */
 export function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceNode) {
     const rPrChange = createWordElement(xmlDoc, 'w:rPrChange');
-    const metadata = createRevisionMetadata(author);
+    const metadata = createRevisionMetadata(author, xmlDoc);
     rPrChange.setAttribute('w:id', String(metadata.id));
     rPrChange.setAttribute('w:author', metadata.author);
     rPrChange.setAttribute('w:date', dateStr || metadata.date);

package/engine/surgical-diff-application.js

@@ -1,5 +1,4 @@
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { isWordElement } from '../core/word-xml.js';
 import {
     createTrackChange,
     createTextRun,
@@ -20,30 +19,17 @@ import {
     findLastSpanEndingBeforeOrAt,
     forEachOverlappingSpan
 } from './surgical-spans.js';
+import { extractFormatFromRPr } from './rpr-helpers.js';
 
 export function reconcileFormattingForTextSpan(xmlDoc, span, start, end, applicableHints, author, generateRedlines) {
-    const desiredFormat = {};
-    if (applicableHints.length > 0) {
-        applicableHints.forEach(h => Object.assign(desiredFormat, h.format));
-    }
+    // Plain modified text carries no negative formatting instruction. Preserve
+    // unchanged source formatting unless Markdown explicitly targets this span.
+    if (applicableHints.length === 0) return false;
 
     const rPr = span.rPr;
-    const hasElement = (localName) => {
-        if (!rPr) return false;
-        for (let node = rPr.firstChild; node; node = node.nextSibling) {
-            if (isWordElement(node, localName)) {
-                return true;
-            }
-        }
-        return false;
-    };
-
-    const existingFormat = {
-        bold: hasElement('b'),
-        italic: hasElement('i'),
-        underline: hasElement('u'),
-        strikethrough: hasElement('strike')
-    };
+    const existingFormat = extractFormatFromRPr(rPr);
+    const desiredFormat = { ...existingFormat };
+    applicableHints.forEach(h => Object.assign(desiredFormat, h.format));
 
     const formatsToCheck = ['bold', 'italic', 'underline', 'strikethrough'];
     const changesNeeded = formatsToCheck.some(f => !!desiredFormat[f] !== existingFormat[f]);

package/engine/surgical-mode.js

@@ -27,9 +27,10 @@ import { withOoxmlSourceType } from '../core/word-xml.js';
  * @param {Array} formatHints - Format hints
  * @param {boolean} [generateRedlines=true] - Track change toggle
  * @param {Element|null} [targetParagraph=null] - Optional scope paragraph
+ * @param {{ diffTimeoutSeconds?: number }} [diffOptions={}] - Diff configuration
  * @returns {{ oxml: string, hasChanges: boolean, sourceType?: 'package'|'document'|'fragment' }}
  */
-export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null) {
+export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null, diffOptions = {}) {
     void originalText;
 
     const allParagraphs = targetParagraph
@@ -37,7 +38,7 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         : getDocumentParagraphs(xmlDoc);
 
     const { fullText, textSpans } = buildSurgicalTextSpans(allParagraphs);
-    const diffs = computeWordDiffs(fullText, modifiedText);
+    const diffs = computeWordDiffs(fullText, modifiedText, diffOptions);
     const spanIndex = buildSpanIndex(textSpans);
 
     let originalPos = 0;

package/engine/table-mode.js

@@ -2,16 +2,20 @@
  * Table-specific reconciliation and transformation flows.
  */
 
-import { NS_W, createRevisionMetadata } from '../core/types.js';
+import {
+    NS_W,
+    createRevisionMetadata,
+    getRevisionIdAllocatorForDocument,
+    setRevisionIdAllocatorForDocument
+} from '../core/types.js';
 import {
     getElementsByTagNS,
     getElementsByTagNSOrTag,
-    getFirstElementByTag,
     getFirstElementByTagNS,
     getFirstElementByTagNSOrTag,
     getXmlParseError
 } from '../core/xml-query.js';
-import { createParser } from '../adapters/xml-adapter.js';
+import { parseOoxmlSafe } from '../adapters/xml-adapter.js';
 import { log, error } from '../adapters/logger.js';
 import { diffTablesWithVirtualGrid, serializeVirtualGridToOoxml, generateTableOoxml } from '../services/table-reconciliation.js';
 import { parseTable } from '../pipeline/pipeline.js';
@@ -51,11 +55,15 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
         return noChanges(serializer, xmlDoc);
     }
 
-    const options = { generateRedlines, author };
+    const options = {
+        generateRedlines,
+        author,
+        revisionIdAllocator: getRevisionIdAllocatorForDocument(xmlDoc)
+    };
     const reconciledOxml = serializeVirtualGridToOoxml(oldGrid, operations, options);
     const wrappedOxml = `<root xmlns:w="${NS_W}">${reconciledOxml}</root>`;
-    const reconcileParser = parser || createParser();
-    const reconciledDoc = reconcileParser.parseFromString(wrappedOxml, 'application/xml');
+    const reconciledDoc = parseOoxmlSafe(wrappedOxml, 'application/xml').doc;
+    if (!reconciledDoc) return noChanges(serializer, xmlDoc);
 
     const parseError = getXmlParseError(reconciledDoc);
     if (parseError) {
@@ -86,16 +94,17 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
  * @param {boolean} generateRedlines - Track change toggle
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines) {
+export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines) {
+    const revisionIdAllocator = getRevisionIdAllocatorForDocument(xmlDoc);
     const tableData = parseTable(modifiedText);
     if (!tableData || (tableData.rows.length === 0 && tableData.headers.length === 0)) {
         log('[OxmlEngine] Failed to parse table data from Markdown');
         return noChanges(serializer, xmlDoc);
     }
 
-    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author });
-    const activeParser = parser || createParser();
-    const tableDoc = activeParser.parseFromString(`<root xmlns:w="${NS_W}">${tableOoxml}</root>`, 'application/xml');
+    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author, revisionIdAllocator });
+    const tableDoc = parseOoxmlSafe(`<root xmlns:w="${NS_W}">${tableOoxml}</root>`, 'application/xml').doc;
+    if (!tableDoc) return noChanges(serializer, xmlDoc);
 
     const tableParseError = getXmlParseError(tableDoc);
     if (tableParseError) {
@@ -123,14 +132,16 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
     let parent = firstParagraph.parentNode;
 
     if (parent && parent.nodeType === 9) {
-        const wrappedDoc = activeParser.parseFromString(
-            `<w:document xmlns:w="${NS_W}"><w:body/></w:document>`,
-            'application/xml'
-        );
+        const wrappedDoc = parseOoxmlSafe(
+            `<w:document xmlns:w="${NS_W}"><w:body/></w:document>`,
+            'application/xml'
+        ).doc;
+        if (!wrappedDoc) return noChanges(serializer, workingDoc);
         const wrappedBody = getFirstElementByTagNS(wrappedDoc, NS_W, 'body');
         paragraphs.forEach(p => wrappedBody.appendChild(wrappedDoc.importNode(p, true)));
 
-        workingDoc = wrappedDoc;
+        workingDoc = wrappedDoc;
+        setRevisionIdAllocatorForDocument(workingDoc, revisionIdAllocator);
         paragraphs = getElementsByTagNS(workingDoc, NS_W, 'p');
         firstParagraph = paragraphs[0];
         parent = firstParagraph.parentNode;
@@ -154,7 +165,7 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
                 });
 
                 const del = createWordElement(workingDoc, 'w:del');
-                const metadata = createRevisionMetadata(author);
+                const metadata = createRevisionMetadata(author, workingDoc);
                 del.setAttribute('w:id', String(metadata.id));
                 del.setAttribute('w:author', metadata.author);
                 del.setAttribute('w:date', metadata.date);

package/index.d.ts

@@ -1,9 +1,9 @@
 export type OoxmlSourceType = 'package' | 'document' | 'fragment';
 export type RedlineStatus = 'ok' | 'no-op' | 'error';
-export type ExistingRevisionsPolicy = 'reject-input' | 'accept-all-first';
+export type ExistingRevisionsPolicy = 'reject-input' | 'accept-all-first' | 'accept-all-first-keep-normalized';
 
 export interface RedlineError {
-  code: 'PARSE_ERROR' | 'TARGET_NOT_FOUND' | 'EXISTING_REVISIONS' | string;
+  code: 'PARSE_ERROR' | 'TARGET_NOT_FOUND' | 'EXISTING_REVISIONS' | 'DIFF_TOKEN_LIMIT' | string;
   message: string;
 }
 
@@ -12,6 +12,8 @@ export interface RedlineOptions {
   author?: string;
   targetParagraphId?: string | null;
   existingRevisions?: ExistingRevisionsPolicy;
+  removeFormatting?: boolean;
+  sanitizeInput?: boolean;
   [key: string]: unknown;
 }
 
@@ -46,6 +48,8 @@ export interface AcceptTrackedChangesResult {
   hasChanges: boolean;
   acceptedCount: number;
   warnings: string[];
+  status?: RedlineStatus;
+  error?: RedlineError;
 }
 
 export interface RejectTrackedChangesResult {
@@ -53,6 +57,8 @@ export interface RejectTrackedChangesResult {
   hasChanges: boolean;
   rejectedCount: number;
   warnings: string[];
+  status?: RedlineStatus;
+  error?: RedlineError;
 }
 
 export interface DeleteCommentsResult {
@@ -61,6 +67,15 @@ export interface DeleteCommentsResult {
   commentsRemoved: number;
   referencesRemoved: number;
   warnings: string[];
+  status?: RedlineStatus;
+  error?: RedlineError;
+}
+
+export interface IngestionTextResult {
+  text: string;
+  status: 'ok' | 'error';
+  error?: RedlineError;
+  warnings?: string[];
 }
 
 export interface XmlProvider {
@@ -85,6 +100,7 @@ export interface DocumentOperationResult {
 }
 
 export function configureXmlProvider(provider: XmlProvider): void;
+export function parseOoxmlSafe(oxml: unknown, contentType?: string): { doc: Document | null; error: RedlineError | null; warnings: string[] };
 export function configureLogger(logger: LoggerConfig): void;
 export function setDefaultAuthor(name: string): void;
 export function getDefaultAuthor(): string;
@@ -114,6 +130,8 @@ export function reconcileMarkdownTableOoxml(
 
 export function ingestWordOoxmlToPlainText(oxml: string): string;
 export function ingestWordOoxmlToMarkdown(oxml: string): string;
+export function ingestWordOoxmlToPlainTextResult(oxml: unknown): IngestionTextResult;
+export function ingestWordOoxmlToMarkdownResult(oxml: unknown): IngestionTextResult;
 export function ingestOoxml(oxml: string): unknown;
 export function preprocessMarkdown(text: string): { cleanText: string; formatHints: unknown[] };
 export function serializeToOoxml(runModel: unknown[], pPrXml?: string | null, formatHints?: unknown[], options?: Record<string, unknown>): string;
@@ -158,7 +176,7 @@ export function ensureNumberingArtifactsInZip(zip: unknown, numberingXml: string
 export function ensureCommentsArtifactsInZip(zip: unknown, commentsXml: string): Promise<unknown> | unknown;
 export function createDynamicNumberingIdState(numberingXml?: string): unknown;
 
-export function parseOoxml(ooxml: string): Document;
+export function parseOoxml(ooxml: string): Document | null;
 export function serializeOoxml(node: Node): string;
 export function sanitizeAiResponse(text: string): string;
 
@@ -170,3 +188,77 @@ export class ReconciliationPipeline {
 export class NumberingService {
   constructor(...args: unknown[]);
 }
+
+// Supporting public utilities. These declarations intentionally expose stable
+// boundary shapes while leaving internal planning records extensible.
+export const NS_W: string;
+export const WORD_MAIN_NS: string;
+export const DiffOp: Readonly<Record<'EQUAL' | 'DELETE' | 'INSERT', string>>;
+export const RunKind: Readonly<Record<string, string>>;
+export const ContainerKind: Readonly<Record<string, string>>;
+export const ContentType: Readonly<Record<string, string>>;
+export const RoutePlanKind: Readonly<Record<string, string>>;
+
+export function escapeXml(value: unknown): string;
+export function applyFormattingRemovalToOoxml(oxml: string, options?: Record<string, unknown>): string;
+export function removeFormattingFromRPr(rPr: Element, options?: Record<string, unknown>): Element;
+
+export function buildCommentElement(comment: Record<string, unknown>, id?: string | number): string;
+export function buildCommentsPartXml(comments: unknown[]): string;
+
+export function reserveNextNumberingId(state: unknown): number;
+export function reserveNextNumberingIdPair(state: unknown): { abstractNumId: number; numId: number };
+export function overwriteParagraphNumIds(oxml: string, numId: string | number): string;
+export function extractFirstParagraphNumId(oxml: string): string | null;
+export function buildExplicitDecimalMultilevelNumberingXml(options?: Record<string, unknown>): string;
+export function remapNumberingPayloadForDocument(numberingXml: string, state: unknown): unknown;
+export function mergeNumberingXmlBySchemaOrder(baseXml: string, incomingXml: string): string;
+
+export function buildListMarkdown(items: unknown[], options?: Record<string, unknown>): string;
+export function inferNumberingStyleFromMarker(marker: string): string;
+export function normalizeListItemsWithLevels(items: unknown[]): unknown[];
+export function parseMarkdownListContent(text: string): unknown;
+export function hasListItems(parsed: unknown): boolean;
+
+export function buildReconciliationPlan(params?: Record<string, unknown>): Record<string, unknown>;
+export function normalizeContentEscapesForRouting(content: string): string;
+export function buildSingleLineListStructuralFallbackPlan(options?: Record<string, unknown>): Record<string, unknown> | null;
+export function executeSingleLineListStructuralFallback(plan: unknown, options?: Record<string, unknown>): Promise<RedlineResult>;
+export function resolveSingleLineListFallbackNumberingAction(plan: unknown, sequenceState?: unknown): Record<string, unknown>;
+export function recordSingleLineListFallbackExplicitSequence(sequenceState: unknown, numberingKey: string | null, numId: string | number | null, startAt: number | null): void;
+export function clearSingleLineListFallbackExplicitSequence(sequenceState: unknown, numberingKey: string | null): void;
+export function enforceListBindingOnParagraphNodes(nodes: Node[], options?: Record<string, unknown>): number;
+export function stripSingleLineListMarkerPrefix(text: string): string;
+
+export function getParagraphText(paragraph: Element | null | undefined): string;
+export function getDocumentParagraphNodes(xmlDoc: Document | Element | null | undefined): Element[];
+export function normalizeWhitespaceForTargeting(text: string): string;
+export function isMarkdownTableText(text: string): boolean;
+export function parseParagraphReference(reference: unknown): unknown;
+export function stripLeadingParagraphMarker(text: string): string;
+export function splitLeadingParagraphMarker(text: string): Record<string, unknown>;
+export function findContainingWordElement(node: Node | null, localName: string): Element | null;
+export function findParagraphByReference(xmlDoc: Document | Element, reference: unknown): Element | null;
+export function findParagraphByStrictText(xmlDoc: Document | Element, text: string): Element | null;
+export function findParagraphByBestTextMatch(xmlDoc: Document | Element, text: string): Element | null;
+export function resolveTargetParagraph(xmlDoc: Document | Element, options?: Record<string, unknown>): Element | null;
+export function buildTargetReferenceSnapshot(paragraph: Element, options?: Record<string, unknown>): Record<string, unknown>;
+export function resolveTargetParagraphWithSnapshot(xmlDoc: Document | Element, snapshot: unknown): Element | null;
+export function resolveParagraphRangeByRefs(xmlDoc: Document | Element, references: unknown[]): Element[];
+export function extractParagraphIdFromOoxml(oxml: string): string | null;
+
+export function getParagraphListInfo(paragraph: Element): Record<string, unknown> | null;
+export function collectContiguousListParagraphBlock(paragraph: Element): Element[];
+export function synthesizeExpandedListScopeEdit(options: Record<string, unknown>): Record<string, unknown> | null;
+export function planListInsertionOnlyEdit(options: Record<string, unknown>): Record<string, unknown> | null;
+export function stripRedundantLeadingListMarkers(text: string): string;
+
+export function inferTableReplacementParagraphBlock(options: Record<string, unknown>): Record<string, unknown> | null;
+export function isLikelyStructuredTableSourceParagraph(paragraph: Element): boolean;
+export function synthesizeTableMarkdownFromMultilineCellEdit(options: Record<string, unknown>): string | null;
+
+export function getBodyElementFromDocument(xmlDoc: Document): Element | null;
+export function insertBodyElementBeforeSectPr(body: Element, element: Element): Element;
+export function normalizeBodySectionOrderStandalone(documentXml: string): string;
+export function sanitizeNestedParagraphsInTables(documentXml: string): string;
+export function getPackagePartName(part: unknown): string | null;