@ansonlai/docx-redline-js

Host-independent OOXML reconciliation engine for .docx manipulation with track changes (redlines).

Converts AI-generated or programmatic text/markdown edits into valid Office Open XML (OOXML) with w:ins/w:del revision markup that Microsoft Word renders as native tracked changes.

Features

• Text reconciliation with word-level diffing and native-looking redlines
• Formatting updates (bold, italic, underline, strikethrough) via surgical w:rPrChange
• Lists: generate and edit real Word lists (w:numPr) from markdown
• Tables: virtual-grid diffing for cell-level edits with merge safety
• Comments: inject OOXML comments anchored to text ranges
• Revision management: accept/reject tracked changes by author or for all authors
• Comment management: delete comments by author or for all authors
• Highlights: apply highlight colors to runs
• Markdown and OOXML conversion in both directions
• Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
• Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support

Install

npm / Node.js

npm install @ansonlai/docx-redline-js

CDN (browser <script type="module">)

<script type="module">
  import { applyRedlineToOxml } from 'https://esm.sh/@ansonlai/docx-redline-js';
</script>

Or use the pre-bundled file (no import map needed, diff-match-patch is inlined):

<script type="module">
  import { applyRedlineToOxml } from 'https://cdn.jsdelivr.net/npm/@ansonlai/docx-redline-js/dist/docx-redline-js.esm.min.js';
</script>

Local git clone

git clone https://github.com/AnsonLai/docx-redline-js.git

import { applyRedlineToOxml } from './docx-redline-js/index.js';

Quick Start

Node.js

import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
import {
  configureXmlProvider,
  setDefaultAuthor,
  applyRedlineToOxml
} from '@ansonlai/docx-redline-js';

configureXmlProvider({ DOMParser, XMLSerializer });
setDefaultAuthor('My App');

const result = await applyRedlineToOxml(
  paragraphOoxml,
  'Original sentence.',
  'Updated sentence.',
  { generateRedlines: true, author: 'Editor' }
);

console.log(result.hasChanges);
console.log(result.oxml);

Browser

import {
  setDefaultAuthor,
  applyRedlineToOxml
} from '@ansonlai/docx-redline-js';

setDefaultAuthor('Browser Editor');

const result = await applyRedlineToOxml(oxml, original, modified, {
  generateRedlines: true
});

API Reference

Configuration (call once at startup)

| Function | Purpose | |----------|---------| | configureXmlProvider({ DOMParser, XMLSerializer }) | Inject XML parser. Required in Node.js; browsers usually provide native support. | | configureLogger({ log, warn, error }) | Replace default console logger. | | setDefaultAuthor(name) | Set fallback track-change author (default: 'Author'). | | setPlatform(label) | Set platform label for diagnostics (default: 'Unknown'). |

Engine (primary reconciliation APIs)

| Function | Purpose | |----------|---------| | applyRedlineToOxml(oxml, original, modified, options) | Core engine entry point for text/markdown reconciliation with optional redlines. | | applyRedlineToOxmlWithListFallback(oxml, original, modified, options) | Core engine with automatic single-line list structural fallback. | | reconcileMarkdownTableOoxml(oxml, original, markdownTable, options) | Table-specific reconciliation helper. |

Pipeline (lower-level access)

| Function | Purpose | |----------|---------| | ReconciliationPipeline | Direct pipeline access (ingest, diff, patch, serialize). | | ingestWordOoxmlToPlainText(oxml) | Extract plain text from OOXML. | | ingestWordOoxmlToMarkdown(oxml) | Convert OOXML to markdown. | | ingestOoxml(oxml) | Flatten OOXML into an internal run model with offsets. | | preprocessMarkdown(text) | Normalize markdown and extract format hints. |

Services

| Function | Purpose | |----------|---------| | injectCommentsIntoOoxml(oxml, comments, options) | Add comments anchored to text ranges. | | acceptTrackedChangesInOoxml(oxml, { author?, allAuthors? }) | Accept w:ins / w:del / *PrChange revisions for one author or all authors. | | rejectTrackedChangesInOoxml(oxml, { author?, allAuthors? }) | Reject w:ins / w:del / *PrChange revisions for one author or all authors. | | deleteCommentsByAuthorInOoxml(oxml, { author?, allAuthors? }) | Delete comments and matching anchors/references for one author or all authors. | | generateTableOoxml(headers, rows, options) | Generate a w:tbl from tabular data. | | createDynamicNumberingIdState(numberingXml) | Allocate numbering IDs without collisions. | | ensureNumberingArtifactsInZip(zip, numberingXml) | Merge numbering artifacts into a .docx package. | | ensureCommentsArtifactsInZip(zip, commentsXml) | Merge comments artifacts into a .docx package. | | validateDocxPackage(zip) | Validate .docx structural consistency. |

Deep Imports

For advanced usage, import specific submodules:

import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
import { getParagraphText } from '@ansonlai/docx-redline-js/core/paragraph-targeting.js';

Output Shape Matrix

Different APIs return different OOXML shapes. Use this as a packaging safety check.

| API | Typical input scope | Output field | Possible root/output shape | Safe to write directly into word/document.xml | |-----|----------------------|--------------|----------------------------|--------------------------------------------------| | applyRedlineToOxml(...) | Paragraph, range, or table-scope OOXML | result.oxml | Fragment, <w:document>, or package payload (<pkg:package>) | No. Inspect first. | | applyRedlineToOxmlWithListFallback(...) | Paragraph or range-scope OOXML | result.oxml | Fragment, <w:document>, or package payload (<pkg:package>) | No. Inspect first. | | reconcileMarkdownTableOoxml(...) | Table or paragraph-scope OOXML | result.oxml | Same shapes as applyRedlineToOxml(...) for the supplied scope | No. Inspect first. | | applyOperationToDocumentXml(...) | Full word/document.xml string | result.documentXml | <w:document> | Yes. This is the document-safe helper. | | extractReplacementNodesFromOoxml(...) | Any OOXML payload | { replacementNodes, numberingXml, sourceType } | Normalized to fragment, document, or package | Yes. Use this when consuming result.oxml. |

Do / Don't for Packaging

• Do use applyOperationToDocumentXml(...).documentXml when your intent is to replace word/document.xml.
• Do use extractReplacementNodesFromOoxml(...) when you are consuming result.oxml from paragraph/range/table APIs.
• Do merge numbering/comments artifacts with ensureNumberingArtifactsInZip(...) and ensureCommentsArtifactsInZip(...) when those parts are present.
• Don't write payloads that start with <pkg:package directly into word/document.xml.
• Don't assume every result.oxml payload is a raw paragraph fragment.

Working With .docx Files

This package operates on OOXML strings (XML parts inside .docx zip archives), not raw .docx binaries.

Typical flow:

1. Extract the .docx zip (for example with JSZip, fflate, or similar)
2. Read word/document.xml
3. Apply reconciliation APIs to XML strings
4. Merge numbering/comments artifacts when needed
5. Write the archive back to a .docx file

import JSZip from 'jszip';
import {
  applyRedlineToOxml,
  extractReplacementNodesFromOoxml,
  ensureNumberingArtifactsInZip,
  validateDocxPackage
} from '@ansonlai/docx-redline-js';
import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';

const zip = await JSZip.loadAsync(docxBuffer);
const documentXml = await zip.file('word/document.xml').async('string');

const opResult = await applyOperationToDocumentXml(
  documentXml,
  { type: 'redline', target: 'old text', modified: 'new text' },
  'Editor'
);

// applyOperationToDocumentXml(...) returns a full w:document payload.
zip.file('word/document.xml', opResult.documentXml);

const fragmentResult = await applyRedlineToOxml(
  paragraphOoxml,
  'Item text',
  '1. Item text',
  { generateRedlines: true, author: 'Editor' }
);
const normalized = extractReplacementNodesFromOoxml(fragmentResult.oxml);

// If sourceType === 'package', merge extracted content/artifacts instead of
// writing the raw pkg:package payload into word/document.xml.
if (normalized.numberingXml) {
  await ensureNumberingArtifactsInZip(zip, normalized.numberingXml);
}

await validateDocxPackage(zip);
const output = await zip.generateAsync({ type: 'nodebuffer' });

Architecture

See ARCHITECTURE.md for module layout, data flow, and contributor guidance.

See AGENTS.md for a concise reference for AI coding agents.