docxmlater 10.0.2 → 10.0.3

package/src/constants/legacyCompatFlags.ts

@@ -0,0 +1,138 @@
+/**
+ * Complete catalog of legacy boolean compat elements defined in
+ * ECMA-376 4th Edition Part 4 (Transitional) and [MS-DOCX] specification.
+ *
+ * These elements are direct children of <w:compat> with complex type CT_OnOff.
+ * They emulate rendering quirks of older word processors. When compatibilityMode
+ * is upgraded to 15, Word's modern layout engine no longer needs them and they
+ * should be removed.
+ *
+ * Source: ECMA-376 4th Edition Part 4 sections 2.15.3.1 through 2.15.3.65
+ * and the [MS-DOCX] specification section 2.15.3.
+ * Verified against: http://www.datypic.com/sc/ooxml/t-w_CT_Compat.html (65 elements)
+ *
+ * Element names include the w: namespace prefix as they appear in XML.
+ */
+export const LEGACY_COMPAT_ELEMENTS: string[] = [
+  // Word 6/95 emulation
+  'w:useSingleBorderforContiguousCells',
+  'w:wpJustification',
+  'w:noTabHangInd',
+  'w:noLeading',
+  'w:spaceForUL',
+  'w:noColumnBalance',
+  'w:balanceSingleByteDoubleByteWidth',
+  'w:noExtraLineSpacing',
+  'w:doNotLeaveBackslashAlone',
+  'w:ulTrailSpace',
+  'w:doNotExpandShiftReturn',
+  'w:spacingInWholePoints',
+  'w:lineWrapLikeWord6',
+  'w:printBodyTextBeforeHeader',
+  'w:printColBlack',
+  'w:wpSpaceWidth',
+  'w:showBreaksInFrames',
+  'w:subFontBySize',
+  'w:suppressBottomSpacing',
+  'w:suppressTopSpacing',
+  'w:suppressSpacingAtTopOfPage',
+  'w:suppressTopSpacingWP',
+  'w:suppressSpBfAfterPgBrk',
+  'w:swapBordersFacingPages',
+  'w:convMailMergeEsc',
+  'w:truncateFontHeightsLikeWP6',
+  'w:mwSmallCaps',
+
+  // Word 97/2000 emulation
+  'w:usePrinterMetrics',
+  'w:doNotSuppressParagraphBorders',
+  'w:wrapTrailSpaces',
+  'w:footnoteLayoutLikeWW8',
+  'w:shapeLayoutLikeWW8',
+  'w:alignTablesRowByRow',
+  'w:forgetLastTabAlignment',
+  'w:adjustLineHeightInTable',
+  'w:autoSpaceLikeWord95',
+  'w:noSpaceRaiseLower',
+  'w:doNotUseHTMLParagraphAutoSpacing',
+  'w:layoutRawTableWidth',
+  'w:layoutTableRowsApart',
+  'w:useWord97LineBreakRules',
+  'w:doNotBreakWrappedTables',
+  'w:doNotSnapToGridInCell',
+  'w:selectFldWithFirstOrLastChar',
+  'w:applyBreakingRules',
+  'w:doNotWrapTextWithPunct',
+  'w:doNotUseEastAsianBreakRules',
+  'w:useWord2002TableStyleRules',
+
+  // Word 2003+ additions
+  'w:growAutofit',
+  'w:useFELayout',
+  'w:useNormalStyleForList',
+  'w:doNotUseIndentAsNumberingTabStop',
+  'w:useAltKinsokuLineBreakRules',
+  'w:allowSpaceOfSameStyleInTable',
+  'w:doNotSuppressIndentation',
+  'w:doNotAutofitConstrainedTables',
+  'w:autofitToFirstFixedWidthCell',
+  'w:underlineTabInNumList',
+  'w:displayHangulFixedWidth',
+  'w:splitPgBreakAndParaMark',
+  'w:doNotVertAlignCellWithSp',
+  'w:doNotBreakConstrainedForcedTable',
+  'w:doNotVertAlignInTxbx',
+  'w:useAnsiKerningPairs',
+  'w:cachedColBalance',
+];
+
+/**
+ * Set of legacy compat element names without the w: prefix,
+ * for efficient lookup during parsing and filtering.
+ */
+export const LEGACY_COMPAT_ELEMENT_NAMES = new Set<string>(
+  LEGACY_COMPAT_ELEMENTS.map(e => e.replace('w:', ''))
+);
+
+import type { CompatSetting } from '../types/compatibility-types';
+
+/**
+ * The w:compatSetting entries that Word 2013+ includes for
+ * fully modern documents. These are the settings emitted when
+ * a user clicks File > Info > Convert in Word.
+ *
+ * Note: useWord2013TrackBottomHyphenation is intentionally omitted.
+ * Its default value varies across Word versions and its presence
+ * could change hyphenation behavior. Real Word 2016+ documents
+ * sometimes include it as "0" and sometimes as "1".
+ */
+export const MODERN_COMPAT_SETTINGS: CompatSetting[] = [
+  {
+    name: 'compatibilityMode',
+    uri: 'http://schemas.microsoft.com/office/word',
+    val: '15',
+  },
+  {
+    name: 'overrideTableStyleFontSizeAndJustification',
+    uri: 'http://schemas.microsoft.com/office/word',
+    val: '1',
+  },
+  {
+    name: 'enableOpenTypeFeatures',
+    uri: 'http://schemas.microsoft.com/office/word',
+    val: '1',
+  },
+  {
+    name: 'doNotFlipMirrorIndents',
+    uri: 'http://schemas.microsoft.com/office/word',
+    val: '1',
+  },
+  {
+    name: 'differentiateMultirowTableHeaders',
+    uri: 'http://schemas.microsoft.com/office/word',
+    val: '1',
+  },
+];
+
+/** The Microsoft Office Word URI used for w:compatSetting entries */
+export const MS_WORD_COMPAT_URI = 'http://schemas.microsoft.com/office/word';

package/src/constants/limits.ts

@@ -0,0 +1,50 @@
+/**
+ * Document validation and processing limits
+ * These constants define thresholds for memory usage, file sizes, and content limits
+ * Based on Microsoft Word compatibility constraints and practical performance testing
+ */
+
+const PROPERTY_LIMITS = {
+  MAX_STRING_LENGTH: 10000,
+  MAX_REVISION: 999999,
+} as const;
+
+const FILE_SIZE_LIMITS = {
+  WARNING_SIZE_MB: 50,
+  ERROR_SIZE_MB: 150,
+} as const;
+
+const XML_LIMITS = {
+  MAX_PARSE_SIZE_MB: 10,
+  MAX_PARSE_SIZE_BYTES: 10 * 1024 * 1024,
+} as const;
+
+const MEMORY_LIMITS = {
+  DEFAULT_MAX_HEAP_PERCENT: 80,
+  DEFAULT_MAX_RSS_MB: 2048,
+  DEFAULT_USE_ABSOLUTE_LIMIT: true,
+} as const;
+
+const IMAGE_LIMITS = {
+  DEFAULT_MAX_IMAGE_COUNT: 20,
+  DEFAULT_MAX_TOTAL_SIZE_MB: 100,
+  DEFAULT_MAX_SINGLE_SIZE_MB: 20,
+} as const;
+
+const SIZE_ESTIMATES = {
+  BYTES_PER_PARAGRAPH: 200,
+  BYTES_PER_TABLE: 1000,
+  BASE_STRUCTURE_BYTES: 50000,
+} as const;
+
+/**
+ * All limits combined for easy import
+ */
+export const LIMITS = {
+  ...PROPERTY_LIMITS,
+  ...FILE_SIZE_LIMITS,
+  ...XML_LIMITS,
+  ...MEMORY_LIMITS,
+  ...IMAGE_LIMITS,
+  ...SIZE_ESTIMATES,
+} as const;

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.