docxmlater 10.4.1 → 11.0.6

package/README.md

@@ -1,116 +1,89 @@
-# docXMLater
+# docxmlater
 
-A comprehensive, production-ready TypeScript/JavaScript framework for creating, reading, and manipulating Microsoft Word (.docx) documents programmatically.
+**The TypeScript library for editing existing Word documents with full tracked-changes, comment, and bookmark fidelity.**
 
-## When to Use docxmlater
+Most DOCX libraries can generate documents from scratch. docxmlater is built for the harder problem: loading an existing `.docx`, modifying it, and saving it back without corrupting it. That includes documents that already contain tracked changes, comments, or bookmarks - which most other libraries silently break on round-trip.
 
-docxmlater is designed for **editing existing Word documents** with full round-trip XML fidelity. It excels at:
+[Try it in your browser](https://stackblitz.com/github/ItMeDiaTech/docXMLater/tree/main/playground) | [Why docxmlater](#why-docxmlater) | [Quick Start](#quick-start) | [API Reference](#api-reference)
 
-- Loading a .docx, making targeted modifications, and saving without losing formatting or structure
-- Working with tracked changes, comments, and revision history
-- Preserving complex elements (math equations, charts, SmartArt) through raw XML passthrough
-- Programmatic batch processing of corporate documents
-
-If you only need to **generate documents from scratch** and don't need to load/edit existing files, consider the [docx](https://www.npmjs.com/package/docx) package which has a declarative builder API optimized for document creation.
-
-## Features
-
-### Core Document Operations
-
-- Create DOCX files from scratch
-- Read and modify existing DOCX files
-- Buffer-based operations (load/save from memory)
-- Document properties (core, extended, custom)
-- Memory management with dispose pattern
-- Bookmark pair validation and auto-repair (`validateBookmarkPairs()`)
-- App.xml metadata preservation (HeadingPairs, TotalTime, etc.)
-- Document background color/theme support
-
-### Text & Paragraph Formatting
-
-- Character formatting: bold, italic, underline, strikethrough, subscript, superscript
-- Font properties: family, size, color (RGB and theme colors), highlight
-- Text effects: small caps, all caps, shadow, emboss, engrave
-- Paragraph alignment, indentation, spacing, borders, shading
-- Text search and replace with regex support
-- Custom styles (paragraph, character, table)
-- CJK/East Asian paragraph properties (kinsoku, wordWrap, overflowPunct, topLinePunct)
-- Underline color and theme color attributes
-- Theme font references (asciiTheme, hAnsiTheme, eastAsiaTheme, csTheme)
-
-### Lists & Tables
-
-- Numbered lists (decimal, roman, alpha)
-- Bulleted lists with various bullet styles
-- Multi-level lists with custom numbering and restart control
-- Tables with formatting, borders, shading
-- Cell spanning (merge cells horizontally and vertically)
-- Advanced table properties (margins, widths, alignment)
-- Table navigation helpers (`getFirstParagraph()`, `getLastParagraph()`)
-- Legacy horizontal merge (`hMerge`) support
-- Table layout parsing (`fixed`/`auto`)
-- Table style shading updates (modify styles.xml colors)
-- Cell content management (trailing blank removal with structure preservation)
-
-### Rich Content
-
-- Images (PNG, JPEG, GIF, SVG, EMF, WMF) with positioning, text wrapping, and full ECMA-376 DrawingML attribute coverage
-- Headers & footers (different first page, odd/even pages)
-- Hyperlinks (external URLs, internal bookmarks)
-- Hyperlink defragmentation utility (fixes fragmented links from Google Docs)
-- Hyperlink URL sanitization (strips browser extension prefixes from corrupted URLs)
-- Bookmarks and cross-references
-- Body-level bookmark support (bookmarks between block elements)
-- Shapes and text boxes
+```bash
+npm install docxmlater
+```
 
-### Advanced Features
-
-- Track changes (revisions for insertions, deletions, formatting)
-- Granular character-level tracked changes (text diff-based)
-- Comments and annotations
-- Compatibility mode detection and upgrade (Word 2003/2007/2010/2013+ modes)
-- Table of contents generation with customizable heading levels and relative indentation
-- Fields: merge fields, date/time, page numbers, TOC fields
-- Footnotes and endnotes (full round-trip with save pipeline, parsing, and clear API)
-- Content controls (Structured Document Tags)
-- Form field data preservation (text input, checkbox, dropdown per ECMA-376 §17.16)
-- w14 run effects passthrough (Word 2010+ ligatures, numForm, textOutline, etc.)
-- Expanded document settings (evenAndOddHeaders, mirrorMargins, autoHyphenation, decimalSymbol)
-- People.xml auto-registration for tracked changes authors
-- Style default attribute preservation (`w:default="1"`)
-- Namespace order preservation in generated XML
-- Multiple sections with different page layouts
-- Page orientation, size, and margins
-- Preserved element round-trip (math equations, alternate content, custom XML)
-- Unified shading model with theme color support and inheritance resolution
-- Lossless image optimization (PNG re-compression, BMP-to-PNG conversion)
-- Run property change tracking (w:rPrChange) with direct API access
-- Paragraph mark revision tracking (w:del/w:ins in w:pPr/w:rPr) for full tracked-changes fidelity
-- Normal/NormalWeb style linking with preservation flags
-
-### Developer Tools
-
-- Complete XML generation and parsing (ReDoS-safe, position-based parser)
-- 40+ unit conversion functions (twips, EMUs, points, pixels, inches, cm)
-- Validation utilities and corruption detection
-- Text diff utility for character-level comparisons
-- webSettings.xml auto-generation
-- Safe OOXML parsing helpers (zero-value handling, boolean parsing)
-- Full TypeScript support with comprehensive type definitions
-- Error handling utilities with custom error types (`DocxError`, `InvalidDocxError`, `CorruptedArchiveError`)
-- Logging infrastructure with multiple log levels (`DOCXMLATER_LOG_LEVEL=debug|info|warn|error`)
-- Plain text extraction (`doc.toPlainText()`) and heading hierarchy (`doc.getHeadingHierarchy()`)
-- Accessibility auditing (`doc.findImagesWithoutAltText()`)
-
-### Unsupported OOXML Features
-
-The following features are preserved as raw XML on round-trip but have no editing API:
-
-- **Charts** (c:chartSpace) -- preserved but not editable
-- **SmartArt** -- preserved as raw XML passthrough
-- **OLE embedded objects** (`<w:object>`) -- preserved, no API
-- **Glossary document** (glossary.xml) -- not handled
-- **DrawingML advanced features** -- gradient fills, pattern fills, group shapes, 3D effects, shape effects (shadow, reflection, glow)
+---
+
+## Why docxmlater
+
+|                                 | `docx` |       `docxtemplater`        | **docxmlater** |
+| ------------------------------- | :----: | :--------------------------: | :------------: |
+| Generate documents from scratch |   ✓    |              ✓               |       ✓        |
+| Load and edit existing files    |   ✗    |   partial (templates only)   |       ✓        |
+| Round-trip XML fidelity         |   ✗    |           partial            |       ✓        |
+| Tracked-changes preservation    |   ✗    |              ✗               |       ✓        |
+| Comments (resolve / unresolve)  |   ✗    |              ✗               |       ✓        |
+| Bookmarks (block and inline)    |   ✗    |           partial            |       ✓        |
+| Compatibility-mode upgrade      |   ✗    |              ✗               |       ✓        |
+| Free / open-source              |   ✓    | partial (commercial modules) |       ✓        |
+
+### When docxmlater is the right choice
+
+- You need to **load existing Word documents** and modify any element with full fidelity.
+- You're working with documents that contain **tracked changes**, **comments**, or **bookmarks** that must round-trip cleanly.
+- You programmatically apply formatting on top of someone else's drafted document.
+- You're processing documents from older Word versions and need **compatibility-mode upgrade**.
+- You want a single library with no commercial tier behind features you actually need.
+
+### When you might want something else
+
+- If you only need to **generate a document from scratch** with no edit or round-trip requirement, the `docx` package has a more declarative builder API.
+- If your entire workflow is **template-fill** (placeholders in a designer-authored docx), `docxtemplater` may fit better.
+- If you only need to **convert docx to HTML or Markdown for display**, `mammoth` is purpose-built.
+
+---
+
+## About the Project
+
+docxmlater began in early 2025 as a personal effort to build a TypeScript framework capable of full programmatic interaction with `.docx` files. What started as a focused side project grew into a much larger undertaking as the depth of the OOXML specification revealed itself. The work is implemented directly against the 6,000+ page ECMA-376 standard, with attention paid to round-trip fidelity, schema correctness, and the practical edge cases real-world Word documents introduce.
+
+The library is in active production use on a small team for day-to-day document formatting workflows. The aim is to provide a free, capable alternative to commercial DOCX engines that charge thousands of dollars per year per seat.
+
+What distinguishes docxmlater from existing libraries is its first-class support for revision workflows. Tracked changes, comments, and bookmarks are fully integrated. Documents that already contain tracked changes can be processed without corruption, preserving the existing revision history where required while still applying new formatting on top.
+
+If you encounter a use case that is not yet implemented and would be broadly useful, please open an issue.
+
+---
+
+## Table of Contents
+
+- [Why docxmlater](#why-docxmlater)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Feature Overview](#feature-overview)
+- [API Reference](#api-reference)
+  - [Document](#document)
+  - [Paragraph](#paragraph)
+  - [Run](#run)
+  - [Table](#table)
+  - [TableCell](#tablecell)
+  - [Section](#section)
+  - [Comment & CommentManager](#comment--commentmanager)
+  - [Utilities](#utilities)
+- [Advanced Topics](#advanced-topics)
+  - [Tracked Changes](#tracked-changes)
+  - [Custom Styles](#custom-styles)
+  - [Hyperlink Management](#hyperlink-management)
+  - [Compatibility Mode](#compatibility-mode)
+  - [Templates](#templates)
+  - [Document Conversion](#document-conversion)
+- [Performance & Memory Management](#performance--memory-management)
+- [Architecture](#architecture)
+- [Security](#security)
+- [TypeScript Support](#typescript-support)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
 
 ## Installation
 
@@ -118,69 +91,51 @@ The following features are preserved as raw XML on round-trip but have no editin
 npm install docxmlater
 ```
 
+Requires Node.js **18.0.0** or higher. TypeScript 5.0+ is recommended for development.
+
+The only runtime dependency is `jszip` for ZIP archive handling.
+
+---
+
 ## Quick Start
 
-### Creating a New Document
+### Create a new document
 
 ```typescript
 import { Document } from 'docxmlater';
 
-// Create a new document
 const doc = Document.create();
-
-// Add a paragraph
 const para = doc.createParagraph();
 para.addText('Hello, World!', { bold: true, fontSize: 24 });
 
-// Save to file
 await doc.save('hello.docx');
-
-// Don't forget to dispose
 doc.dispose();
 ```
 
-### Loading and Modifying Documents
+### Load and modify an existing document
 
 ```typescript
 import { Document } from 'docxmlater';
 
-// Load existing document
 const doc = await Document.load('input.docx');
 
-// Find and replace text
 doc.replaceText(/old text/g, 'new text');
+doc.createParagraph().addText('Added paragraph', { italic: true });
 
-// Add a new paragraph
-const para = doc.createParagraph();
-para.addText('Added paragraph', { italic: true });
-
-// Save modifications
 await doc.save('output.docx');
 doc.dispose();
 ```
 
-### Working with Tables
+### Tables
 
 ```typescript
-import { Document } from 'docxmlater';
-
 const doc = Document.create();
-
-// Create a 3x4 table
 const table = doc.createTable(3, 4);
 
-// Set header row
-const headerRow = table.getRow(0);
-headerRow.getCell(0).addParagraph().addText('Column 1', { bold: true });
-headerRow.getCell(1).addParagraph().addText('Column 2', { bold: true });
-headerRow.getCell(2).addParagraph().addText('Column 3', { bold: true });
-headerRow.getCell(3).addParagraph().addText('Column 4', { bold: true });
+const header = table.getRow(0);
+header.getCell(0).createParagraph().addText('Column 1', { bold: true });
+header.getCell(1).createParagraph().addText('Column 2', { bold: true });
 
-// Add data
-table.getRow(1).getCell(0).addParagraph().addText('Data 1');
-table.getRow(1).getCell(1).addParagraph().addText('Data 2');
-
-// Apply borders
 table.setBorders({
   top: { style: 'single', size: 4, color: '000000' },
   bottom: { style: 'single', size: 4, color: '000000' },
@@ -194,563 +149,397 @@ await doc.save('table.docx');
 doc.dispose();
 ```
 
-### Adding Images
+### Images
 
 ```typescript
 import { Document } from 'docxmlater';
 import { readFileSync } from 'fs';
 
 const doc = Document.create();
-
-// Load image from file
 const imageBuffer = readFileSync('photo.jpg');
 
-// Add image to document
 const para = doc.createParagraph();
-await para.addImage(imageBuffer, {
-  width: 400,
-  height: 300,
-  format: 'jpg',
-});
+await para.addImage(imageBuffer, { width: 400, height: 300, format: 'jpg' });
 
 await doc.save('with-image.docx');
 doc.dispose();
 ```
 
-### Hyperlink Management
-
-```typescript
-import { Document } from 'docxmlater';
-
-const doc = await Document.load('document.docx');
-
-// Get all hyperlinks
-const hyperlinks = doc.getHyperlinks();
-console.log(`Found ${hyperlinks.length} hyperlinks`);
-
-// Update URLs in batch (30-50% faster than manual iteration)
-doc.updateHyperlinkUrls('http://old-domain.com', 'https://new-domain.com');
-
-// Fix fragmented hyperlinks from Google Docs
-const mergedCount = doc.defragmentHyperlinks({
-  resetFormatting: true, // Fix corrupted fonts
-});
-console.log(`Merged ${mergedCount} fragmented hyperlinks`);
-
-await doc.save('updated.docx');
-doc.dispose();
-```
-
-### Custom Styles
-
-```typescript
-import { Document, Style } from 'docxmlater';
-
-const doc = Document.create();
-
-// Create custom paragraph style
-const customStyle = new Style('CustomHeading', 'paragraph');
-customStyle.setName('Custom Heading');
-customStyle.setRunFormatting({
-  bold: true,
-  fontSize: 32,
-  color: '0070C0',
-});
-customStyle.setParagraphFormatting({
-  alignment: 'center',
-  spacingAfter: 240,
-});
-
-// Add style to document
-doc.getStylesManager().addStyle(customStyle);
-
-// Apply style to paragraph
-const para = doc.createParagraph();
-para.addText('Styled Heading');
-para.applyStyle('CustomHeading');
-
-await doc.save('styled.docx');
-doc.dispose();
-```
-
-### Compatibility Mode Detection and Upgrade
+---
 
-```typescript
-import { Document, CompatibilityMode } from 'docxmlater';
+## Feature Overview
 
-const doc = await Document.load('legacy.docx');
+### Document Operations
 
-// Check compatibility mode
-console.log(`Mode: ${doc.getCompatibilityMode()}`); // e.g., 12 (Word 2007)
+Create, load, and save documents from files or buffers. Manage core, extended, and custom document properties. Validate and auto-repair bookmark pairs. Preserve `app.xml` metadata (HeadingPairs, TotalTime, etc.). Configurable document background color and theme support.
 
-if (doc.isCompatibilityMode()) {
-  // Get detailed compatibility info
-  const info = doc.getCompatibilityInfo();
-  console.log(`Legacy flags: ${info.legacyFlags.length}`);
-
-  // Upgrade to Word 2013+ mode (equivalent to File > Info > Convert)
-  const report = doc.upgradeToModernFormat();
-  console.log(`Removed ${report.removedFlags.length} legacy flags`);
-  console.log(`Added ${report.addedSettings.length} modern settings`);
-}
-
-await doc.save('modern.docx');
-doc.dispose();
-```
-
-## API Overview
-
-### Document Class
+### Text & Paragraph Formatting
 
-**Creation & Loading:**
+- Character formatting: bold, italic, underline, strikethrough, sub/superscript, small caps, all caps, shadow, emboss, engrave
+- Font properties: family, size, color (RGB and theme), highlight, underline color
+- Theme font references (`asciiTheme`, `hAnsiTheme`, `eastAsiaTheme`, `csTheme`)
+- Paragraph alignment, indentation, spacing, borders, shading
+- CJK / East Asian properties (kinsoku, wordWrap, overflowPunct, topLinePunct)
+- Cross-run text search and replace, regex supported
 
-- `Document.create(options?)` - Create new document
-- `Document.load(filepath, options?)` - Load from file
-- `Document.loadFromBuffer(buffer, options?)` - Load from memory
+### Lists & Tables
 
-**Handling Tracked Changes:**
+- Numbered (decimal, roman, alpha) and bulleted lists
+- Multi-level lists with custom numbering and restart control
+- Tables with borders, shading, alignment, and width control
+- Horizontal and vertical cell merging, including legacy `hMerge`
+- Fixed and auto table layouts
+- Cell content management with structure preservation
 
-By default, docXMLater accepts all tracked changes during document loading to prevent corruption:
+### Rich Content
 
-```typescript
-// Default: Accepts all changes (recommended)
-const doc = await Document.load('document.docx');
+- Images: PNG, JPEG, GIF, SVG, EMF, WMF - with positioning, text wrapping, and full DrawingML attribute coverage
+- Headers and footers with first-page and odd/even variants
+- Hyperlinks (external and internal), with defragmentation and URL sanitization utilities
+- Bookmarks (block and inline level) and cross-references
+- Shapes and text boxes
 
-// Explicit control
-const doc = await Document.load('document.docx', {
-  revisionHandling: 'accept'  // Accept all changes (default)
-  // OR
-  revisionHandling: 'strip'   // Remove all revision markup
-  // OR
-  revisionHandling: 'preserve' // Keep tracked changes (may cause corruption, but should not do so - report errors if found)
-});
-```
+### Revisions & Collaboration
 
-**Revision Handling Options:**
+- Track changes (insertions, deletions, formatting)
+- Character-level granular revisions via text diffing
+- Comments with resolve/unresolve workflow
+- Run property change tracking (`w:rPrChange`)
+- Paragraph mark revision tracking (`w:del`/`w:ins` in `w:pPr`/`w:rPr`)
+- People.xml auto-registration for revision authors
+- Full round-trip preservation of pre-existing tracked changes
 
-- `'accept'` (default): Removes revision markup, keeps inserted content, removes deleted content
-- `'strip'`: Removes all revision markup completely
-- `'preserve'`: Keeps tracked changes as-is (may cause Word "unreadable content" errors)
+### Advanced Features
 
-**Why Accept By Default?**
+- Compatibility mode detection and upgrade (Word 2003 / 2007 / 2010 / 2013+)
+- Table of contents generation with customizable heading levels
+- Fields: merge fields, date/time, page numbers, TOC fields
+- Footnotes and endnotes (full round-trip and dedicated API)
+- Content controls (Structured Document Tags)
+- Form field data preservation (text, checkbox, dropdown per ECMA-376 §17.16)
+- `w14` run effects passthrough (Word 2010+ ligatures, numForm, textOutline)
+- Multiple sections with independent page layouts and orientations
+- Lossless image optimization (PNG re-compression, BMP-to-PNG conversion)
+- Unified shading model with theme color support and inheritance resolution
 
-Documents with tracked changes can cause Word corruption errors during round-trip processing due to revision ID conflicts. Accepting changes automatically prevents this issue while preserving document content.
+### Document Conversion
 
-**Content Management:**
+Export to Markdown, HTML (fragment or full page), Base64, or Data URI. Create documents from Markdown.
 
-- `createParagraph()` - Add paragraph
-- `createTable(rows, cols)` - Add table
-- `createSection()` - Add section
-- `getBodyElements()` - Get all body content
+### Preserved (round-trip only)
 
-**Search & Replace:**
+The following features round-trip safely as raw XML but have no editing API:
 
-- `findText(pattern)` - Find text matches
-- `replaceText(pattern, replacement)` - Replace text
-- `findParagraphsByText(pattern)` - Find paragraphs containing text/regex
-- `getParagraphsByStyle(styleId)` - Get paragraphs with specific style
-- `getRunsByFont(fontName)` - Get runs using a specific font
-- `getRunsByColor(color)` - Get runs with a specific color
+- Charts (`c:chartSpace`)
+- SmartArt
+- OLE embedded objects (`w:object`)
+- Math equations
+- Glossary documents (`glossary.xml`)
+- Advanced DrawingML (gradient/pattern fills, group shapes, 3D effects)
 
-**Bulk Formatting:**
+---
 
-- `setAllRunsFont(fontName)` - Apply font to all text
-- `setAllRunsSize(size)` - Apply font size to all text
-- `setAllRunsColor(color)` - Apply color to all text
-- `getFormattingReport()` - Get document formatting statistics
+## API Reference
 
-**Hyperlinks:**
+### Document
 
-- `getHyperlinks()` - Get all hyperlinks
-- `updateHyperlinkUrls(oldUrl, newUrl)` - Batch URL update
-- `defragmentHyperlinks(options?)` - Fix fragmented links
-- `collectAllReferencedHyperlinkIds()` - Comprehensive scan of all hyperlink relationship IDs (includes nested tables, headers/footers, footnotes/endnotes)
+**Creation & Loading**
 
-**Statistics:**
+| Method                                      | Description                 |
+| ------------------------------------------- | --------------------------- |
+| `Document.create(options?)`                 | Create a new document       |
+| `Document.load(path, options?)`             | Load from a file path       |
+| `Document.loadFromBuffer(buffer, options?)` | Load from a `Buffer`        |
+| `Document.fromMarkdown(md)`                 | Create from Markdown source |
+| `Document.loadFromBase64(b64)`              | Load from a Base64 string   |
 
-- `getWordCount()` - Count words
-- `getCharacterCount(includeSpaces?)` - Count characters
-- `estimateSize()` - Estimate file size
+**Content Management**
 
-**Compatibility Mode:**
+- `createParagraph()`, `createTable(rows, cols)`, `createSection()`
+- `addHeading(text, level?)`, `addPageBreak()`, `addHorizontalRule(color?, size?)`
+- `addBulletListFromArray(items)`, `addNumberedListFromArray(items)`
+- `createTableFromCSV(csv, delimiter?)`
+- `getBodyElements()`, `clear()`, `clone()`
+- `insertAfter(ref, el)`, `insertBefore(ref, el)`, `replaceElement(old, new)`, `removeElement(el)`
+- `forEachParagraph(cb)`, `forEachTable(cb)`, `extractByHeading(maxLevel?)`, `getElementsBetween(start, end)`
 
-- `getCompatibilityMode()` - Get document's Word version mode (11/12/14/15)
-- `isCompatibilityMode()` - Check if document targets a legacy Word version
-- `getCompatibilityInfo()` - Get full parsed compat settings
-- `upgradeToModernFormat()` - Upgrade to Word 2013+ mode (removes legacy flags)
+**Search & Replace**
 
-**Footnotes & Endnotes:**
+- `findText(pattern)`, `replaceText(pattern, replacement)`
+- `findParagraphsByText(pattern)`, `getParagraphsByStyle(styleId)`
+- `getRunsByFont(name)`, `getRunsByColor(color)`
 
-- `createFootnote(paragraph, text)` - Add footnote
-- `createEndnote(paragraph, text)` - Add endnote
-- `clearFootnotes()` / `clearEndnotes()` - Remove all notes
-- `getFootnoteManager()` / `getEndnoteManager()` - Access note managers
+**Bulk Formatting**
 
-**Numbering:**
+- `setAllRunsFont(name)`, `setAllRunsSize(size)`, `setAllRunsColor(color)`
+- `setDefaultFont(name, size?)`, `setDefaultFontSize(size)`
+- `getFormattingReport()`
 
-- `restartNumbering(numId, level?, startValue?)` - Restart list numbering (creates new instance with startOverride)
-- `cleanupUnusedNumbering()` - Remove unused numbering definitions (scans body, headers, footers, footnotes, endnotes)
-- `consolidateNumbering(options?)` - Merge duplicate abstract numbering definitions
-- `validateNumberingReferences()` - Fix orphaned numId references
+**Hyperlinks**
 
-**Shading:**
+- `getHyperlinks()`, `updateHyperlinkUrls(oldUrl, newUrl)`
+- `defragmentHyperlinks(options?)`, `collectAllReferencedHyperlinkIds()`
 
-- `getComputedCellShading(table, row, col)` - Resolve effective cell shading with inheritance
+**Statistics**
 
-**Document Sanitization:**
+- `getWordCount()`, `getCharacterCount(includeSpaces?)`
+- `estimateSize()`, `getStatistics()`
 
-- `flattenFieldCodes()` - Strip INCLUDEPICTURE field markup, preserving embedded images
-- `stripOrphanRSIDs()` - Remove orphan RSIDs from settings.xml
-- `clearDirectSpacingForStyles(styleIds)` - Remove direct spacing overrides from styled paragraphs
+**Compatibility**
 
-**Image Optimization:**
+- `getCompatibilityMode()`, `isCompatibilityMode()`
+- `getCompatibilityInfo()`, `upgradeToModernFormat()`
 
-- `optimizeImages()` - Lossless PNG re-compression and BMP-to-PNG conversion (zero dependencies)
+**Footnotes & Endnotes**
 
-**Document Convenience:**
+- `createFootnote(paragraph, text)`, `createEndnote(paragraph, text)`
+- `clearFootnotes()`, `clearEndnotes()`
+- `getFootnoteManager()`, `getEndnoteManager()`
 
-- `addHeading(text, level?)` - Add heading paragraph (H1-H9)
-- `addPageBreak()` - Insert page break
-- `addHorizontalRule(color?, size?)` - Insert horizontal line
-- `setDefaultFont(name, size?)` - Set document default font via Normal style
-- `setDefaultFontSize(size)` - Set document default font size
-- `clear()` - Remove all body content (preserves styles/settings)
-- `clone()` - Deep copy document for template batch generation
-- `addBulletListFromArray(items)` - Create bullet list from string array
-- `addNumberedListFromArray(items)` - Create numbered list from string array
-- `createTableFromCSV(csv, delimiter?)` - Create table from CSV data
+**Numbering**
 
-**Template Engine:**
+- `restartNumbering(numId, level?, startValue?)`
+- `cleanupUnusedNumbering()`, `consolidateNumbering(options?)`
+- `validateNumberingReferences()`
 
-- `fillTemplate(data, options?)` - Replace `{{key}}` placeholders across runs
-- `findAndHighlight(text, color?)` - Highlight all text occurrences
-- `findAndFormat(text, formatting)` - Apply formatting to all text occurrences
+**Sanitization & Optimization**
 
-**Document Conversion:**
+- `flattenFieldCodes()` - strip INCLUDEPICTURE markup, keep images
+- `stripOrphanRSIDs()` - remove unused RSIDs from `settings.xml`
+- `clearDirectSpacingForStyles(ids)` - remove direct spacing on styled paragraphs
+- `optimizeImages()` - lossless PNG re-compression, BMP-to-PNG
 
-- `toMarkdown()` - Export as Markdown
-- `toHTML(options?)` - Export as HTML (fragment or full page)
-- `toBase64()` - Export as base64 string
-- `toDataUri()` - Export as data URI
-- `fromMarkdown(md)` - Create document from Markdown (static)
-- `loadFromBase64(base64)` - Load document from base64 (static)
+**Templates & Highlighting**
 
-**Content Structure:**
+- `fillTemplate(data, options?)` - replace `{{key}}` placeholders across runs
+- `findAndHighlight(text, color?)`, `findAndFormat(text, formatting)`
 
-- `insertAfter(reference, element)` - Insert element after reference
-- `insertBefore(reference, element)` - Insert element before reference
-- `replaceElement(old, new)` - Replace body element in-place
-- `removeElement(element)` - Remove body element by reference
-- `extractByHeading(maxLevel?)` - Group content by heading sections
-- `getElementsBetween(start, end)` - Get elements between two references
-- `forEachParagraph(callback)` - Iterate top-level paragraphs
-- `forEachTable(callback)` - Iterate top-level tables
-- `getStatistics()` - Comprehensive document metrics
+**Conversion**
 
-**Saving:**
+- `toMarkdown()`, `toHTML(options?)`, `toPlainText()`
+- `toBase64()`, `toDataUri()`, `getHeadingHierarchy()`
+- `findImagesWithoutAltText()` (accessibility audit)
 
-- `save(filepath)` - Save to file
-- `toBuffer()` - Save to Buffer
-- `dispose()` - Free resources (important!)
+**Saving**
 
-### Paragraph Class
+- `save(path)`, `toBuffer()`, `dispose()` - _always call `dispose()` when finished_
 
-**Content:**
+### Paragraph
 
-- `addText(text, formatting?)` - Add text run
-- `addRun(run)` - Add custom run
-- `addHyperlink(hyperlink)` - Add hyperlink
-- `addImage(buffer, options)` - Add image
+**Content**: `addText(text, formatting?)`, `addRun(run)`, `addHyperlink(link)`, `addImage(buffer, options)`
 
-**Formatting:**
+**Formatting**: `setAlignment`, `setIndentation`, `setSpacing`, `setBorders`, `setShading`, `applyStyle`, `setKeepNext`, `setKeepLines`, `setPageBreakBefore`, `clearSpacing`
 
-- `setAlignment(alignment)` - Left, center, right, justify
-- `setIndentation(options)` - First line, hanging, left, right
-- `setSpacing(options)` - Line spacing, before/after
-- `setBorders(borders)` - Paragraph borders
-- `setShading(shading)` - Background color
-- `applyStyle(styleId)` - Apply paragraph style
+**Text manipulation**: `applyFormattingToRange`, `deleteRange`, `truncate`, `wrap`, `splitAt`, `consolidateRuns`, `replaceAll`, `findTextCrossRun`, `getRunAtOffset`, `getFormattingAtOffset`, `contains`, `toJSON` / `fromJSON`
 
-**Properties:**
+**Numbering**: `setNumbering(numId, level)`
 
-- `setKeepNext(value)` - Keep with next paragraph
-- `setKeepLines(value)` - Keep lines together
-- `setPageBreakBefore(value)` - Page break before
-- `clearSpacing()` - Remove direct spacing (inherit from style)
+### Run
 
-**Text Manipulation:**
+**Text**: `setText`, `getText`, `getPlainText`, `splitAt`
 
-- `applyFormattingToRange(start, end, formatting)` - Apply formatting to character range
-- `deleteRange(start, end)` - Delete character range
-- `truncate(maxLength, suffix?)` - Truncate text with ellipsis
-- `wrap(prefix, suffix, formatting?)` - Wrap content with prefix/suffix
-- `splitAt(offset)` - Split paragraph into two at character position
-- `consolidateRuns()` - Merge adjacent runs with identical formatting
-- `replaceAll(find, replace)` - Cross-run find and replace
-- `findTextCrossRun(find)` - Cross-run text search with offsets
-- `getRunAtOffset(offset)` - Get run at character position
-- `getFormattingAtOffset(offset)` - Get formatting at character position
-- `contains(text, caseSensitive?)` - Check if paragraph contains text
-- `toJSON()` / `fromJSON(data)` - Serialize/deserialize paragraph
+**Character formatting**: `setBold`, `setItalic`, `setUnderline`, `setStrikethrough`, `setFont`, `setFontSize`, `setColor`, `setHighlight`
 
-**Numbering:**
+**Advanced**: `setSubscript`, `setSuperscript`, `setSmallCaps`, `setAllCaps`, `clearMatchingFormatting`, `equals`, `hasSameFormatting`, `clone`
 
-- `setNumbering(numId, level)` - Apply list numbering
+### Table
 
-### Run Class
+**Structure**: `addRow`, `addRowFromArray`, `getRow`, `getCell`, `setCell`, `duplicateRow`, `addSummaryRow`
 
-**Text:**
+**Data**: `fromArray` / `toArray`, `fromCSV` / `toCSV`, `toPlainText`, `transpose`, `clone`, `sortRows`
 
-- `setText(text)` - Set run text
-- `getText()` - Get run text
-- `getPlainText()` - Get text only (no tabs/breaks)
-- `splitAt(offset)` - Split run at character position
+**Queries**: `getColumnCells`, `getColumnTexts`, `findCell`, `filterRows`, `forEachCell`, `mapColumn`
 
-**Character Formatting:**
+**Formatting**: `setBorders`, `setAlignment`, `setWidth`, `setLayout`, `applyStyle`
 
-- `setBold(value)` - Bold text
-- `setItalic(value)` - Italic text
-- `setUnderline(style?)` - Underline
-- `setStrikethrough(value)` - Strikethrough
-- `setFont(name)` - Font family
-- `setFontSize(size)` - Font size in points
-- `setColor(color)` - Text color (hex)
-- `setHighlight(color)` - Highlight color
+**Cleanup**: `removeEmptyRows`, `removeEmptyColumns`
 
-**Advanced:**
+### TableCell
 
-- `setSubscript(value)` - Subscript
-- `setSuperscript(value)` - Superscript
-- `setSmallCaps(value)` - Small capitals
-- `setAllCaps(value)` - All capitals
-- `clearMatchingFormatting(styleFormatting)` - Remove formatting matching a style (for inheritance)
-- `equals(other)` - Compare text and formatting equality
-- `hasSameFormatting(other)` - Compare formatting only
-- `clone()` - Deep copy run
+**Content**: `addParagraph`, `getParagraphs`, `removeTrailingBlankParagraphs`, `removeParagraph`, `addParagraphAt`
 
-### Table Class
+**Formatting**: `setBorders`, `setShading`, `setBackgroundColor` / `getBackgroundColor`, `setVerticalAlignment`, `setWidth`
 
-**Structure:**
+**Spanning**: `setHorizontalMerge`, `setVerticalMerge`
 
-- `addRow()` - Add row
-- `addRowFromArray(cells)` - Add row from string array
-- `getRow(index)` - Get row by index
-- `getCell(row, col)` - Get specific cell
-- `setCell(row, col, text)` - Set cell text by coordinates
-- `duplicateRow(index, count?)` - Clone a row in-place
-- `addSummaryRow(options?)` - Add computed totals row
+**Convenience**: `setTextAlignment`, `setAllParagraphsStyle`, `setAllRunsFont`, `setAllRunsSize`, `setAllRunsColor`
 
-**Data Conversion:**
+### Section
 
-- `fromArray(data)` / `toArray()` - 2D string array I/O
-- `fromCSV(csv, delimiter?)` / `toCSV(delimiter?)` - CSV round-trip
-- `toPlainText(colSep?, rowSep?)` - Delimited text export
-- `transpose()` - Swap rows and columns
-- `clone()` - Deep copy table
+**Line numbering**: `setLineNumbering(options)`, `getLineNumbering()`, `clearLineNumbering()`
 
-**Queries:**
+### Comment & CommentManager
 
-- `getColumnCells(colIndex)` - Get cells in a column
-- `getColumnTexts(colIndex)` - Get text values in a column
-- `findCell(predicate)` - Find first matching cell with coordinates
-- `filterRows(predicate)` - Get indices of matching rows
-- `forEachCell(callback)` - Iterate all cells with row/col
-- `mapColumn(colIndex, transform)` - Transform column values
+**Comment**: `resolve()`, `unresolve()`, `isResolved()`
 
-**Cleanup:**
+**CommentManager**: `getResolvedComments()`, `getUnresolvedComments()`
 
-- `removeEmptyRows()` - Remove rows with no text
-- `removeEmptyColumns()` - Remove columns with no text
+### Utilities
 
-**Formatting:**
+**Unit conversion**
 
-- `setBorders(borders)` - Table borders
-- `setAlignment(alignment)` - Table alignment
-- `setWidth(width)` - Table width
-- `setLayout(layout)` - Fixed or auto layout
+```typescript
+import { twipsToPoints, inchesToTwips, emusToPixels } from 'docxmlater';
 
-**Style:**
+twipsToPoints(240); // 12 points
+inchesToTwips(1); // 1440 twips
+emusToPixels(914400, 96); // 96 pixels at 96 DPI
+```
 
-- `applyStyle(styleId)` - Apply table style
+40+ conversion helpers across twips, EMUs, points, pixels, inches, and centimeters.
 
-### TableCell Class
+**Validation**
 
-**Content:**
+```typescript
+import { validateRunText, cleanXmlFromText } from 'docxmlater';
 
-- `addParagraph()` - Add paragraph to cell
-- `getParagraphs()` - Get all paragraphs
+const result = validateRunText('Some <w:t>text</w:t>');
+if (result.hasXml) {
+  const cleaned = cleanXmlFromText(result.text);
+}
+```
 
-**Formatting:**
+**Corruption detection**
 
-- `setBorders(borders)` - Cell borders
-- `setShading(shading)` - Cell shading/background
-- `setBackgroundColor(hex)` / `getBackgroundColor()` - Simple color shortcut
-- `setVerticalAlignment(alignment)` - Top, center, bottom
-- `setWidth(width)` - Cell width
+```typescript
+import { detectCorruptionInDocument } from 'docxmlater';
 
-**Spanning:**
+const doc = await Document.load('suspect.docx');
+const report = detectCorruptionInDocument(doc);
 
-- `setHorizontalMerge(mergeType)` - Horizontal merge
-- `setVerticalMerge(mergeType)` - Vertical merge
+if (report.isCorrupted) {
+  report.locations.forEach((loc) => {
+    console.log(`Line ${loc.lineNumber}: ${loc.issue}`);
+  });
+}
+```
 
-**Convenience Methods:**
+---
 
-- `setTextAlignment(alignment)` - Set alignment for all paragraphs
-- `setAllParagraphsStyle(styleId)` - Apply style to all paragraphs
-- `setAllRunsFont(fontName)` - Apply font to all runs
-- `setAllRunsSize(size)` - Apply font size to all runs
-- `setAllRunsColor(color)` - Apply color to all runs
+## Advanced Topics
 
-**Content Management:**
+### Tracked Changes
 
-- `removeTrailingBlankParagraphs(options?)` - Remove trailing blank paragraphs from cell
-- `removeParagraph(index)` - Remove paragraph at index (updates nested content positions)
-- `addParagraphAt(index, paragraph)` - Insert paragraph at index (updates nested content positions)
+By default, `Document.load()` accepts all tracked changes during loading. This prevents revision-ID conflicts that can cause Word to report "unreadable content" on round-trip.
 
-### Document Class
+```typescript
+const doc = await Document.load('document.docx', {
+  revisionHandling: 'accept', // default - keep insertions, drop deletions
+  // revisionHandling: 'strip',    - remove all revision markup entirely
+  // revisionHandling: 'preserve', - keep tracked changes verbatim (advanced)
+});
+```
 
-**Table Style Shading:**
+| Mode               | Behavior                                                                 |
+| ------------------ | ------------------------------------------------------------------------ |
+| `accept` (default) | Removes revision markup, keeps inserted content, removes deleted content |
+| `strip`            | Removes all revision markup completely                                   |
+| `preserve`         | Keeps tracked changes intact for advanced workflows                      |
 
-- `updateTableStyleShading(oldColor, newColor)` - Update shading colors in styles.xml
-- `updateTableStyleShadingBulk(settings)` - Bulk update table style shading
-- `removeTrailingBlanksInTableCells(options?)` - Remove trailing blanks from all table cells
+### Custom Styles
 
-### Table Class
+```typescript
+import { Document, Style } from 'docxmlater';
 
-**Sorting:**
+const doc = Document.create();
 
-- `sortRows(columnIndex, options?)` - Sort table rows by column
+const heading = new Style('CustomHeading', 'paragraph');
+heading.setName('Custom Heading');
+heading.setRunFormatting({ bold: true, fontSize: 32, color: '0070C0' });
+heading.setParagraphFormatting({ alignment: 'center', spacingAfter: 240 });
 
-### Section Class
+doc.getStylesManager().addStyle(heading);
 
-**Line Numbering:**
+const para = doc.createParagraph();
+para.addText('Styled Heading');
+para.applyStyle('CustomHeading');
 
-- `setLineNumbering(options)` - Enable line numbering
-- `getLineNumbering()` - Get line numbering settings
-- `clearLineNumbering()` - Disable line numbering
+await doc.save('styled.docx');
+doc.dispose();
+```
 
-### Comment Class
+### Hyperlink Management
 
-**Resolution:**
+```typescript
+const doc = await Document.load('document.docx');
 
-- `resolve()` - Mark comment as resolved
-- `unresolve()` - Mark comment as unresolved
-- `isResolved()` - Check if comment is resolved
+const links = doc.getHyperlinks();
+console.log(`Found ${links.length} hyperlinks`);
 
-### CommentManager Class
+doc.updateHyperlinkUrls('http://old-domain.com', 'https://new-domain.com');
 
-**Filtering:**
+const merged = doc.defragmentHyperlinks({ resetFormatting: true });
+console.log(`Merged ${merged} fragmented hyperlinks`);
 
-- `getResolvedComments()` - Get all resolved comments
-- `getUnresolvedComments()` - Get all unresolved comments
+await doc.save('updated.docx');
+doc.dispose();
+```
 
-### Utilities
+`defragmentHyperlinks` repairs fragmented links commonly produced by Google Docs exports. Batch URL updates run 30-50% faster than manual iteration.
 
-**Unit Conversions:**
+### Compatibility Mode
 
 ```typescript
-import { twipsToPoints, inchesToTwips, emusToPixels } from 'docxmlater';
-
-const points = twipsToPoints(240); // 240 twips = 12 points
-const twips = inchesToTwips(1); // 1 inch = 1440 twips
-const pixels = emusToPixels(914400, 96); // 914400 EMUs = 96 pixels at 96 DPI
-```
+const doc = await Document.load('legacy.docx');
 
-**Validation:**
+console.log(`Mode: ${doc.getCompatibilityMode()}`); // e.g. 12 (Word 2007)
 
-```typescript
-import { validateRunText, detectXmlInText, cleanXmlFromText } from 'docxmlater';
+if (doc.isCompatibilityMode()) {
+  const info = doc.getCompatibilityInfo();
+  console.log(`Legacy flags: ${info.legacyFlags.length}`);
 
-// Detect XML patterns in text
-const result = validateRunText('Some <w:t>text</w:t>');
-if (result.hasXml) {
-  console.warn(result.message);
-  const cleaned = cleanXmlFromText(result.text);
+  const report = doc.upgradeToModernFormat();
+  console.log(`Removed ${report.removedFlags.length} legacy flags`);
+  console.log(`Added ${report.addedSettings.length} modern settings`);
 }
-```
-
-**Corruption Detection:**
-
-```typescript
-import { detectCorruptionInDocument } from 'docxmlater';
-
-const doc = await Document.load('suspect.docx');
-const report = detectCorruptionInDocument(doc);
 
-if (report.isCorrupted) {
-  console.log(`Found ${report.locations.length} corruption issues`);
-  report.locations.forEach((loc) => {
-    console.log(`Line ${loc.lineNumber}: ${loc.issue}`);
-    console.log(`Suggested fix: ${loc.suggestedFix}`);
-  });
-}
+await doc.save('modern.docx');
+doc.dispose();
 ```
 
-## TypeScript Support
+`upgradeToModernFormat()` is the programmatic equivalent of _File → Info → Convert_ in Word.
 
-Full TypeScript definitions included:
+### Templates
 
 ```typescript
-import {
-  Document,
-  Paragraph,
-  Run,
-  Table,
-  RunFormatting,
-  ParagraphFormatting,
-  DocumentProperties,
-} from 'docxmlater';
+const doc = await Document.load('template.docx');
 
-// Type-safe formatting
-const formatting: RunFormatting = {
-  bold: true,
-  fontSize: 12,
-  color: 'FF0000',
-};
+doc.fillTemplate({
+  customer: 'Acme Corp',
+  date: '2025-04-25',
+  total: '$12,400.00',
+});
 
-// Type-safe document properties
-const properties: DocumentProperties = {
-  title: 'My Document',
-  author: 'John Doe',
-  created: new Date(),
-};
+await doc.save('invoice-acme.docx');
+doc.dispose();
 ```
 
-## Version History
+Placeholders use `{{key}}` syntax and are replaced safely across run boundaries.
 
-**Current Version: 10.4.0**
+### Document Conversion
 
-See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
-
-## Testing
-
-The framework includes comprehensive test coverage:
-
-- **4,134 test cases** across 195 test suites
-- Tests cover all phases of implementation
-- Integration tests for complex scenarios
-- Performance benchmarks
-- Edge case validation
+```typescript
+const doc = await Document.load('report.docx');
 
-Run tests:
+const md = doc.toMarkdown();
+const html = doc.toHTML({ fullPage: true });
+const base64 = doc.toBase64();
 
-```bash
-npm test              # Run all tests
-npm run test:watch   # Watch mode
-npm run test:coverage # Coverage report
+doc.dispose();
 ```
 
-## Performance Considerations
+---
 
-- Use `dispose()` to free resources after document operations
-- Buffer-based operations are faster than file I/O
-- Batch hyperlink updates are 30-50% faster than manual iteration
-- Large documents (1000+ pages) supported with memory management
-- Streaming support for very large files
+## Performance & Memory Management
 
-## Error Handling
+- **Always call `dispose()`** to release ZIP handles and image buffers
+- Buffer-based I/O (`loadFromBuffer` / `toBuffer`) is 20-30% faster than file-path I/O
+- Default size limits: warn at 50 MB, error at 150 MB (configurable via `LoadOptions.sizeLimits`)
+- Memory footprint: ~2 MB per `Document`, ~2 bytes/character, full buffer per embedded image, ~200 bytes/cell
+- For repeated paragraph access, cache `getAllParagraphs()` rather than calling it inside a loop
+- Large documents (1,000+ pages) are supported
 
-All document operations should be wrapped in try/finally to ensure proper cleanup:
+### Recommended Pattern
 
 ```typescript
 import { Document } from 'docxmlater';
@@ -767,11 +556,11 @@ try {
 }
 ```
 
-For buffer-based workflows (common in web servers):
+For server-side buffer workflows:
 
 ```typescript
-async function processDocument(inputBuffer: Buffer): Promise<Buffer> {
-  const doc = await Document.loadFromBuffer(inputBuffer);
+async function processDocument(input: Buffer): Promise<Buffer> {
+  const doc = await Document.loadFromBuffer(input);
   try {
     doc.replaceText(/placeholder/g, 'actual value');
     return await doc.toBuffer();
@@ -781,132 +570,116 @@ async function processDocument(inputBuffer: Buffer): Promise<Buffer> {
 }
 ```
 
-Custom error types from `docxmlater` include `InvalidDocxError`, `CorruptedArchiveError`, and `FileOperationError` — all extend `DocxError`.
+Custom error types are available from `docxmlater/internal`. These include `DocxError`, `InvalidDocxError`, `CorruptedArchiveError`, and `FileOperationError`.
 
-## Working with Large Documents
+Logging is configurable via `DOCXMLATER_LOG_LEVEL=debug|info|warn|error`.
 
-- Use buffer operations (`loadFromBuffer`/`toBuffer`) for 20-30% faster I/O
-- Call `dispose()` promptly to release ZIP handles and image buffers
-- Size limits default to warning at 50MB and error at 150MB (configurable via `LoadOptions.sizeLimits`)
-- Memory usage: ~2MB base per Document, ~2 bytes/char, full buffer per embedded image, ~200 bytes/cell
-- For repeated paragraph access, cache the result of `getAllParagraphs()` rather than calling it in a loop
+---
 
 ## Architecture
 
-The framework follows a modular architecture:
-
 ```
 src/
-├── core/          # Document, Parser, Generator, Validator
-├── elements/      # Paragraph, Run, Table, Image, etc.
-├── formatting/    # Style, Numbering managers
-├── managers/      # Drawing, Image, Relationship managers
-├── constants/     # Compatibility mode constants, limits
-├── types/         # Type definitions (compatibility, formatting, lists)
-├── tracking/      # Change tracking context
-├── validation/    # Revision validation rules
-├── helpers/       # Cleanup utilities
-├── xml/           # XML generation and parsing
-├── zip/           # ZIP archive handling
-└── utils/         # Validation, units, error handling
+├── core/          Document, Parser, Generator, Validator
+├── elements/      Paragraph, Run, Table, Image, Section, ...
+├── formatting/    Style and Numbering managers
+├── managers/      Drawing, Image, Relationship managers
+├── tracking/      Revision tracking context
+├── validation/    Revision and structural validation
+├── helpers/       Cleanup utilities
+├── xml/           XML generation and parsing (ReDoS-safe)
+├── zip/           ZIP archive handling
+├── constants/     Compatibility flags, limits, schema constants
+├── types/         TypeScript type definitions
+└── utils/         Units, validation, error handling
 ```
 
-Key design principles:
+**Design principles**
 
-- KISS (Keep It Simple, Stupid) - no over-engineering
-- Position-based XML parsing (ReDoS-safe)
-- Defensive programming with comprehensive validation
-- Memory-efficient with explicit disposal pattern
-- Full ECMA-376 (OpenXML) compliance
+- Strict adherence to ECMA-376 (Office Open XML)
+- Position-based XML parsing (not regex) to prevent ReDoS
+- Round-trip XML fidelity through `_originalXml` preservation and dirty-flag regeneration
+- Explicit memory management via the `dispose()` pattern
+- Defensive validation with comprehensive type coverage
 
-## Security
+---
 
-docXMLater includes multiple security measures to protect against common attack vectors:
-
-### ReDoS Prevention
-
-The XML parser uses position-based parsing instead of regular expressions, preventing catastrophic backtracking attacks that can cause denial of service.
-
-### Input Validation
-
-**Size Limits:**
+## Security
 
-- Default document size limit: 150 MB (configurable)
-- Warning threshold: 50 MB
-- XML content size validation before parsing
+- **ReDoS protection** - position-based XML parsing eliminates catastrophic backtracking
+- **Path traversal prevention** - DOCX archive entries are validated against `../`, absolute paths, and URL-encoded traversal
+- **XML injection prevention** - all text and attribute content is escaped via `XMLBuilder.escapeXmlText()` and `XMLBuilder.escapeXmlAttribute()`
+- **Size limits** - configurable warning (50 MB) and hard cap (150 MB) on document size
+- **Nesting limits** - XML parser caps nesting depth at 256 levels (configurable) to prevent stack overflow
+- **UTF-8 enforcement** - all text content is explicitly UTF-8 encoded per ECMA-376
 
 ```typescript
-// Configure size limits
 const doc = await Document.load('large.docx', {
-  sizeLimits: {
-    warningSizeMB: 100,
-    maxSizeMB: 500,
-  },
+  sizeLimits: { warningSizeMB: 100, maxSizeMB: 500 },
 });
 ```
 
-**Nesting Depth:**
-
-- Maximum XML nesting depth: 256 (configurable)
-- Prevents stack overflow attacks
-
 ```typescript
-import { XMLParser } from 'docxmlater';
+import { XMLParser } from 'docxmlater/internal';
 
-// Parse with custom depth limit
-const obj = XMLParser.parseToObject(xml, {
-  maxNestingDepth: 512, // Increase if needed
-});
+const obj = XMLParser.parseToObject(xml, { maxNestingDepth: 512 });
 ```
 
-### Path Traversal Prevention
-
-File paths within DOCX archives are validated to prevent directory traversal attacks:
+---
 
-- Blocks `../` path sequences
-- Blocks absolute paths
-- Validates URL-encoded path components
-
-### XML Injection Prevention
+## TypeScript Support
 
-All text content is properly escaped using:
+Full type definitions are bundled with the package:
 
-- `XMLBuilder.escapeXmlText()` for element content
-- `XMLBuilder.escapeXmlAttribute()` for attribute values
+```typescript
+import {
+  Document,
+  Paragraph,
+  Run,
+  Table,
+  RunFormatting,
+  ParagraphFormatting,
+  DocumentProperties,
+} from 'docxmlater';
 
-This prevents injection of malicious XML elements through user-provided text content.
+const formatting: RunFormatting = {
+  bold: true,
+  fontSize: 12,
+  color: 'FF0000',
+};
 
-### UTF-8 Encoding
+const properties: DocumentProperties = {
+  title: 'My Document',
+  author: 'Jane Doe',
+  created: new Date(),
+};
+```
 
-All text files are explicitly UTF-8 encoded per ECMA-376 specification, preventing encoding-related vulnerabilities.
+---
 
 ## Requirements
 
 - Node.js 18.0.0 or higher
 - TypeScript 5.0+ (for development)
 
-## Dependencies
-
-- `jszip` - ZIP archive handling
+Single runtime dependency: `jszip`.
 
-## License
-
-MIT
+---
 
 ## Contributing
 
-Contributions welcome! Please:
+Contributions are welcome. Please:
 
 1. Fork the repository
 2. Create a feature branch
-3. Add tests for new features
-4. Ensure all tests pass
-5. Submit a pull request
+3. Add tests for any new functionality
+4. Ensure the full test suite passes (`npm test`)
+5. Open a pull request
 
-## Support
+If you have a use case that is not yet supported, opening an issue first is the best way to discuss design before code.
 
-- GitHub Issues: https://github.com/ItMeDiaTech/docXMLater/issues
+---
 
-## Acknowledgments
+## License
 
-Built with careful attention to the ECMA-376 Office Open XML specification. Special thanks to the OpenXML community for comprehensive documentation and examples.
+MIT