docxmlater 10.0.2 → 10.0.4

package/src/core/CLAUDE.md

@@ -0,0 +1,109 @@
+# Core Module
+
+`src/core/` — Document lifecycle, XML parsing/generation, validation, relationships.
+
+## Classes
+
+### Document (`Document.ts`)
+
+Primary entry point. Factory pattern: `Document.create()` (new), `Document.load()`/`loadFromBuffer()` (existing). Disposal pattern: always call `dispose()` when done.
+
+**Load Options:**
+```typescript
+interface DocumentLoadOptions {
+  revisionHandling?: 'accept' | 'strip' | 'preserve';  // default: 'accept'
+  acceptRevisions?: boolean;  // true = parse then accept in-memory
+}
+```
+
+Use `revisionHandling: 'preserve'` to retain `pPrChange` and other revision elements during round-trip.
+
+### DocumentParser (`DocumentParser.ts`)
+
+Converts XML to JavaScript object models. Position-based parsing (ReDoS-safe).
+
+**Key behaviors:**
+- Hyperlink defragmentation (merges consecutive hyperlinks with same URL)
+- Special characters: `<w:tab/>`, `<w:br/>` → string equivalents
+- Multi-paragraph complex fields: assembles fields (like TOC) spanning multiple paragraphs into single `ComplexField` objects
+- Element order via `_orderedChildren` for correct tab/break ordering
+- Body-level bookmarks: `extractBodyLevelBookmarkStarts()`/`extractBodyLevelBookmarkEnds()`
+- Form field data: `parseFormFieldData()` with typed interfaces
+- Footnotes/endnotes: `parseFootnotesXml()`/`parseEndnotesXml()`
+- Unknown elements preserved for round-trip fidelity
+
+### DocumentGenerator (`DocumentGenerator.ts`)
+
+Converts object models to DOCX XML. Template-based, on-demand, validates before generation.
+
+Generates: `[Content_Types].xml`, `_rels/.rels`, `word/document.xml`, `word/styles.xml`, `word/numbering.xml`, `word/settings.xml`, `word/fontTable.xml`, `word/_rels/document.xml.rels`, `word/footnotes.xml`, `word/endnotes.xml`, `docProps/core.xml`, `docProps/app.xml`.
+
+### DocumentValidator (`DocumentValidator.ts`)
+
+Estimates final DOCX file size and validates memory usage. Size formula: `(base ~5KB + text*1.5 + images + cells*200) * 0.3 compression`.
+
+### RelationshipManager (`RelationshipManager.ts`)
+
+Manages relationships (images, hyperlinks, headers, footers, comments, footnotes, endnotes, people). Sequential IDs (`rId1`, `rId2`, ...). Singleton types (comments, footnotes, endnotes, people) need check-before-add guard to prevent duplicates on round-trip.
+
+### BaseManager (`BaseManager.ts`)
+
+Abstract base for all manager classes. Subclasses: StylesManager, NumberingManager, ImageManager, BookmarkManager, CommentManager, RevisionManager, FootnoteManager, EndnoteManager, DrawingManager, HeaderFooterManager.
+
+## Data Flow
+
+**Load:** `Document.load()` → `ZipHandler.load()` → extract XML → `DocumentParser.parse()` → parse styles/numbering/relationships → build object model → return Document
+
+**Save:** `Document.save()` → `DocumentValidator.estimateSize()` → `DocumentGenerator.generate()` → generate all XML → `RelationshipManager.generateXML()` → `ZipWriter.create()` → write ZIP
+
+## Revision Acceptance Architecture
+
+The framework implements the **industry-standard in-memory DOM transformation approach** (same as OpenXML PowerTools, Aspose.Words).
+
+**`acceptAllRevisions()` transforms Revision objects in the in-memory model:**
+1. **Insertions (`w:ins`)**: Unwrap — child Runs/Hyperlinks extracted into parent paragraph
+2. **Deletions (`w:del`)**: Remove — revision and content deleted from model
+3. **MoveFrom (`w:moveFrom`)**: Remove — content exists at moveTo destination
+4. **MoveTo (`w:moveTo`)**: Unwrap — keep content, remove wrapper
+5. **Property changes (`w:rPrChange`, etc.)**: Remove metadata, keep current formatting
+
+Because this transforms the in-memory model (not raw XML), standard `save()` regeneration includes both accepted changes AND subsequent modifications.
+
+**`acceptAllRevisionsRawXml()` (legacy):** Sets `skipDocumentXmlRegeneration = true`. Any modifications after this call will NOT be saved.
+
+**Helper Functions:**
+```typescript
+import { acceptRevisionsInMemory, paragraphHasRevisions, getRevisionsFromParagraph, countRevisionsByType } from 'docxmlater';
+
+// Selective acceptance
+const result = acceptRevisionsInMemory(doc, {
+  acceptInsertions: true,
+  acceptDeletions: true,
+  acceptMoves: true,
+  acceptPropertyChanges: false,
+});
+```
+
+## Sanitization & Cleanup Pipeline
+
+All methods below are explicitly called by user code. None run automatically. **Removals are intentional — do not treat as bugs.**
+
+**Post-Processing (`_postProcessDocumentXml`):** Runs during `prepareSave()`, after `updateDocumentXml()` and before `updateSettingsXml()`. Zero overhead when no flags set.
+
+| Method | Removes | Why |
+|--------|---------|-----|
+| `flattenFieldCodes()` | INCLUDEPICTURE fldChar/instrText runs | Outlook bloat. Preserves w:drawing. Other fields untouched. Sets `skipDocumentXmlRegeneration = true`. |
+| `stripOrphanRSIDs()` | Unreferenced RSIDs in settings.xml | 80%+ of settings.xml. Preserves `rsidRoot`. |
+| `clearDirectSpacingForStyles()` | Direct w:spacing on styled paragraphs | Lets style spacing take effect. Protects w:pPrChange/w:rPr. |
+| `cleanupUnusedNumbering()` | Unreferenced numbering defs | Scans 6 sources before removing. |
+| `consolidateNumbering()` | Duplicate abstract numberings | Copy-paste creates 10-50+ identical copies. |
+
+## Performance
+
+| Document Size | Load/Save Time |
+|--------------|----------------|
+| <100KB | <50ms |
+| 100KB-1MB | 100-500ms |
+| >1MB | 500ms-2s |
+
+Buffer operations are 20-30% faster than file I/O. Base memory: ~2MB per Document, ~2 bytes/char, full buffer per image, ~200 bytes/cell.