AI-powered Microsoft Word add-in that applies word-level tracked changes using a structure-aware diff strategy — plus document summarization with comment extraction and tracked changes analysis.

Project history: This library was extracted from a private codebase and open-sourced as a standalone project in Jan 2026.

• Word-level diffs with tracked changes via office-word-diff
• Token map strategy with sentence fallback, block replace as last resort
• Configurable LLM backends: Ollama and vLLM (OpenAI-compatible)

Three-Category Prompt System

• Context, Amendment, and Comment prompt categories with dedicated tabs
• Full CRUD: create, save, update, delete prompts per category
• Per-category activation with {selection} placeholder replacement
• Prompts persist in localStorage across sessions

Document Comment Summary

• 4th "Summary" tab — extract all document comments, send to LLM, generate a formatted Word document
• {comments} placeholder inserts structured comment data (author, annotated text, comment text)
• {whole document} placeholder extracts full document text with configurable richness:
  • Plain — raw paragraph text
  • Headings — markdown-style heading markers (## Section Title)
  • Structured — headings + list item numbering and indentation
• {tracked changes} placeholder extracts revision marks via OOXML parsing (w:ins, w:del, w:moveFrom, w:moveTo)
• Generated summary document includes annex with numbered source comments
• LLM markdown output auto-converted to HTML via marked
• Tables in generated documents render with visible borders

Tracked Changes Extraction (OOXML)

• Parses body.getOoxml() with browser DOMParser — no external dependencies
• Handles pkg:package wrapper, w:proofErr normalization
• Pairs adjacent w:del + w:ins from same author as replacements
• Detects move operations (w:moveFrom / w:moveTo)
• Skips table row revision markers (w:ins/w:del inside w:trPr)
• Namespace-aware querying with prefix fallback for cross-browser compatibility
• Author identity prominently included in LLM-formatted output

Async Comment Queue

• Bookmark-based range persistence for async comment insertion
• Comment status bar with pending count and retry-on-error
• WordApi 1.4 detection with graceful degradation

Settings & UX

• Settings auto-save on every change (no Save button)
• Live token estimation with real document metrics (async Word API read, cached, debounced)
• Document extraction richness dropdown (Summary mode only)
• Tracked changes extraction toggle (Summary mode only)
• Mode switching: Amendment/Comment tabs disabled when Summary is active
• Review button relabels to "Generate Summary" in Summary mode

Backend Selector

• Ollama and vLLM backends with unified OpenAI-compatible API
• Model dropdown auto-populated from backend /v1/models endpoint
• Configurable endpoint URL and optional API key
• Track Changes and Line Diff toggles

Parallel LLM Orchestration

• Full-document amendment and commenting: parse, chunk, dispatch to LLM in parallel, reassemble
• Worker-pool concurrency with configurable limits (auto-tuned: 4 workers for large chunks, 6 for smaller)
• AbortController-based cancellation stops pending chunks immediately
• Progress tracking with per-chunk ETA estimation
• Retry failed chunks without re-processing successful ones

Document Parsing & Chunking

• Paragraph-level document parsing with style and heading detection
• Token-aware chunking with configurable max size (default 6K tokens)
• Heading-based chunk boundaries (H1/H2 trigger splits; H3+ stay coherent)
• Overlap paragraphs provide preceding context to each chunk
• Tiny trailing chunks merged into previous chunk to prevent orphans

Context Extraction

• Automatic definition extraction via regex (means/shall-mean/is-defined-as, the-X, hereinafter-X patterns)
• Abbreviation expansion via word-initial matching heuristic
• Document outline generation from heading hierarchy
• Context prefix formatted and injected into each chunk's LLM system message

Formatting-Preserving Reassembly

• Paragraph-level amendment strategy: aligns LLM output paragraphs to original document paragraphs using LCS + word-level similarity matching
• Within-paragraph word-level diff via token map strategy preserves run-level formatting (bold, italic, font, color)
• Paragraph properties (styles, numbering, indentation) preserved through paragraph-scoped operations
• Graceful degradation chain: paragraph-level -> word-level diff -> sentence diff -> block replace
• Line ending normalization (\r <-> \n) throughout the pipeline
• Content validation rejects severely truncated LLM output before applying
• Amendments applied in reverse document order to prevent range invalidation
• Bookmarks persist chunk ranges across LLM processing time

Merged Amendment + Comment Mode

• Comment instructions persisted with prompt data (save/restore across sessions)
• When comment instructions are provided in amendment mode, LLM produces delimited ===AMENDMENT=== / ===COMMENT=== output
• Response parser extracts both sections; comments inserted on bookmarked ranges after all amendments
• Fallback: undelimited responses treated as amendment-only

LLM Output Quality

• Critical output rules appended to amendment prompts: no commentary, no markdown, preserve structure
• stripMarkdown() post-processor as safety net for amendment responses
• stripThinkTags() removes <think> reasoning blocks from LLM output

Testing

• 388 unit tests across 13 test suites (Jest)
• TDD workflow: failing tests written before implementation
• Covers: prompt state/persistence/composition, comment extraction, document generation, tracked changes OOXML parsing, orchestrator dispatch/concurrency, reassembler paragraph alignment, document chunking, context extraction

There are two ways to run this add-in:

Both methods require HTTPS certificates trusted by the machine running Word.

• Docker and Docker Compose
• HTTPS certificate files (see Create HTTPS Certificates)

1. Clone the repository

git clone https://github.com/yuch85/word-ai-redliner.git
cd word-ai-redliner

2. Create HTTPS certificates (see Create HTTPS Certificates)

   Place server.pem and server-key.pem in the project root.

3. Configure environment variables

   Copy the Docker example and edit it:

cp .env.docker.example .env

On Windows PowerShell:

Copy-Item .env.docker.example .env

Important: Edit .env and set HOST to the hostname or IP address that the Word client can reach. If Word runs on a different machine, do not use localhost.

4. Start the container

docker compose up -d

The container automatically generates manifest.xml on first startup using your .env values. The manifest is written to the project root.

5. Trust the certificate on Windows (see Trust the Certificate on Windows)

6. Sideload the add-in (see Sideload the Add-in)

   Use the manifest.xml file in the project root.

• Node.js 18+
• HTTPS certificate files (see Create HTTPS Certificates)

1. Clone the repository

git clone https://github.com/yuch85/word-ai-redliner.git
cd word-ai-redliner

2. Install dependencies

npm install

3. Create HTTPS certificates (see Create HTTPS Certificates)

   Place server.pem and server-key.pem in the project root.

4. Configure environment variables

   Copy the example and edit it:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Important: Edit .env and set HOST to the hostname or IP address that the Word client can reach. If Word runs on a different machine, do not use localhost.

5. Start the dev server

npm start

This generates manifest.xml from your .env values and starts the webpack dev server with hot reload.

6. Trust the certificate on Windows (see Trust the Certificate on Windows)

7. Sideload the add-in (see Sideload the Add-in)

   Use the manifest.xml file in the project root.

The add-in must be served over HTTPS. Word will block untrusted certificates.

Place your cert files in the project root:

• server.pem (certificate)
• server-key.pem (private key)

1. Install mkcert.
2. Create a local CA and generate a cert:

mkcert -install

# For localhost (same machine):
mkcert localhost

# For a remote server (use your actual IP or hostname):
mkcert <your-server-ip-or-hostname>

3. Rename the output files:

cp localhost.pem server.pem
cp localhost-key.pem server-key.pem

On Windows PowerShell:

Copy-Item localhost.pem server.pem
Copy-Item localhost-key.pem server-key.pem

# Replace <YOUR_HOST> with localhost or your server IP/hostname
openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout server-key.pem \
  -out server.pem \
  -subj "/CN=<YOUR_HOST>"

On the Windows PC running Word:

1. Copy the .pem cert file to the Windows PC.
2. Convert PEM to CRT (if needed):

openssl x509 -in server.pem -out server.crt

3. Open certmgr.msc (run as Administrator).
4. Navigate to Trusted Root Certification Authorities → Certificates.
5. Right-click → All Tasks → Import...
6. Select the .crt file and finish the wizard.

If you used mkcert, you can install the mkcert root CA on Windows instead:

• Copy the root CA from the server machine (find it via mkcert -CAROOT)
• Import it into Trusted Root Certification Authorities

Method 1: Add from file

1. Open Word → Insert → Get Add-ins → My Add-ins.
2. Click Add a custom add-in → Add from file....
3. Select manifest.xml and confirm.

Method 2: Network shared folder (Windows only)

1. Create a shared folder and note the network path.
2. In Word: File → Options → Trust Center → Trust Center Settings → Trusted Add-in Catalogs → Add catalog (check Show in Menu).
3. Copy manifest.xml into the shared folder.
4. In Word: Home → Add-ins → Advanced → Shared Folder → select the add-in → Add.

For full details, see the Microsoft sideloading guide.

1. Start the server (docker compose up -d or npm start).
2. Open Word → Insert → Add-ins → My Add-ins.
3. Click Add a custom add-in → Add from file... → select manifest.xml.
4. Trust the certificate in Keychain if prompted.

Users can override DEFAULT_OLLAMA_URL and DEFAULT_MODEL via the add-in settings UI; those overrides persist in localStorage.

Pre-built images are available on GitHub Container Registry:

docker pull ghcr.io/yuch85/word-ai-redliner:0.2.0
docker pull ghcr.io/yuch85/word-ai-redliner:latest

See ARCHITECTURE.md for details.

npx jest --no-coverage    # 388 tests across 13 suites
npx webpack --mode development   # verify build

Test suites cover:

• prompt-state.spec.js — PromptManager CRUD, activation, persistence, summary category
• prompt-persistence.spec.js — localStorage round-trip, migration, edge cases
• prompt-composition.spec.js — composeMessages, composeSummaryMessages, placeholder replacement, output rules
• comment-extractor.spec.js — extractAllComments, extractDocumentStructured, estimateTokenCount, extractTrackedChanges (OOXML parsing)
• document-generator.spec.js — buildSummaryHtml (markdown conversion, table borders, escaping), createSummaryDocument (Word API)
• comment-queue.spec.js — CommentQueue state management, bookmark naming
• llm-client.spec.js — sendPrompt, stripThinkTags, stripMarkdown, testConnection
• document-parser.spec.js — parseDocument, paragraph extraction, heading detection, style mapping
• document-chunker.spec.js — chunkDocument, heading-based splitting, overlap, token limits
• context-extractor.spec.js — extractContext, definitions, abbreviations, outline generation
• orchestrator.spec.js — processChunksParallel, concurrency, cancellation, merged mode parsing
• reassembler.spec.js — paragraph alignment, line ending normalization, content validation
• response-parser.spec.js — parseDelimitedResponse, fallback classification

Word AI Redliner's formatting-preserving reassembly draws on insights from several excellent open-source projects in the document editing space. We are grateful to their authors for sharing their work:

• docx-redline-js by Anson Lai -- A JavaScript OOXML-level redlining engine whose surgical mode, paragraph property cloning, and reconstruction writer patterns informed our approach to preserving paragraph and run formatting during document reassembly.

• safe-docx by UseJunior -- A safe OOXML manipulation library whose paragraph shell cloning, template run selection, multi-stage text matching, and run splitting patterns guided our thinking on formatting fidelity and style resolution.

• adeu by Dealfluence Oy (Mikko Korpela, Uzair Ahmed) -- A Python OOXML redlining tool whose virtual text contract, run coalescing, and deep-copy w:pPr/w:rPr preservation patterns shaped our understanding of how to maintain formatting coherence through tracked change operations.

• @xmldom/xmldom -- A W3C-compliant XML DOM implementation whose namespace-aware manipulation patterns and whitespace preservation mechanisms underpin correct OOXML handling.

This project is dual-licensed:

• MIT License applies to the Word add-in codebase.
• Apache 2.0 License applies to the office-word-diff library (used as a dependency).

See LICENSE and LICENSE-APACHE for details.