docxmlater 10.4.0 → 11.0.4

package/src/core/Document.ts

@@ -3,31 +3,32 @@
  * Provides a simple interface for creating DOCX files without managing ZIP and XML manually
  */
 
-import { Bookmark } from '../elements/Bookmark';
-import { BookmarkManager } from '../elements/BookmarkManager';
-import { Comment } from '../elements/Comment';
-import { PreservedElement } from '../elements/PreservedElement';
-import { CommentManager } from '../elements/CommentManager';
-import { Endnote } from '../elements/Endnote';
-import { EndnoteManager } from '../elements/EndnoteManager';
-import { Field, ComplexField } from '../elements/Field';
-import { Footnote } from '../elements/Footnote';
-import { FootnoteManager } from '../elements/FootnoteManager';
-import { Footer } from '../elements/Footer';
-import { Header } from '../elements/Header';
-import { HeaderFooterManager } from '../elements/HeaderFooterManager';
-import { Hyperlink } from '../elements/Hyperlink';
-import { Image } from '../elements/Image';
-import { ImageManager } from '../elements/ImageManager';
-import { ImageRun } from '../elements/ImageRun';
-import { Paragraph, ParagraphContent, FieldLike } from '../elements/Paragraph';
-import { RangeMarker } from '../elements/RangeMarker';
-import { Revision, RevisionType } from '../elements/Revision';
-import { RevisionManager } from '../elements/RevisionManager';
-import { RevisionLocation } from '../elements/PropertyChangeTypes';
-import { Run, RunFormatting } from '../elements/Run';
-import { Shape } from '../elements/Shape';
-import { TextBox } from '../elements/TextBox';
+import { parseOnOffAttribute } from '../utils/parsingHelpers.js';
+import { Bookmark } from '../elements/Bookmark.js';
+import { BookmarkManager } from '../elements/BookmarkManager.js';
+import { Comment } from '../elements/Comment.js';
+import { PreservedElement } from '../elements/PreservedElement.js';
+import { CommentManager } from '../elements/CommentManager.js';
+import { Endnote } from '../elements/Endnote.js';
+import { EndnoteManager } from '../elements/EndnoteManager.js';
+import { Field, ComplexField } from '../elements/Field.js';
+import { Footnote } from '../elements/Footnote.js';
+import { FootnoteManager } from '../elements/FootnoteManager.js';
+import { Footer } from '../elements/Footer.js';
+import { Header } from '../elements/Header.js';
+import { HeaderFooterManager } from '../elements/HeaderFooterManager.js';
+import { Hyperlink } from '../elements/Hyperlink.js';
+import { Image } from '../elements/Image.js';
+import { ImageManager } from '../elements/ImageManager.js';
+import { ImageRun } from '../elements/ImageRun.js';
+import { Paragraph, ParagraphContent, FieldLike } from '../elements/Paragraph.js';
+import { RangeMarker } from '../elements/RangeMarker.js';
+import { Revision, RevisionType } from '../elements/Revision.js';
+import { RevisionManager } from '../elements/RevisionManager.js';
+import { RevisionLocation } from '../elements/PropertyChangeTypes.js';
+import { Run, RunFormatting } from '../elements/Run.js';
+import { Shape } from '../elements/Shape.js';
+import { TextBox } from '../elements/TextBox.js';
 import {
   RevisionValidator,
   RevisionAutoFixer,
@@ -35,25 +36,33 @@ import {
   AutoFixOptions,
   ValidationResult,
   AutoFixResult,
-} from '../validation';
-import { Section } from '../elements/Section';
-import { StructuredDocumentTag } from '../elements/StructuredDocumentTag';
-import { Table, TableBorder } from '../elements/Table';
-import { TableCell } from '../elements/TableCell';
-import { TableOfContentsElement } from '../elements/TableOfContentsElement';
-import { resolveCellShading } from '../utils/ShadingResolver';
+} from '../validation/index.js';
+import { Section } from '../elements/Section.js';
+import { StructuredDocumentTag } from '../elements/StructuredDocumentTag.js';
+import { Table, TableBorder } from '../elements/Table.js';
+import { TableCell } from '../elements/TableCell.js';
+import { TableOfContentsElement } from '../elements/TableOfContentsElement.js';
+import { resolveCellShading } from '../processors/ShadingResolver.js';
 import {
   NumberingManager,
   NumberingConsolidationOptions,
   NumberingConsolidationResult,
-} from '../formatting/NumberingManager';
-import { Style, StyleProperties } from '../formatting/Style';
-import { StylesManager } from '../formatting/StylesManager';
-import { FormatOptions, StyleApplyOptions } from '../types/formatting';
-import { CompatibilityMode, CompatibilityInfo, CompatSetting } from '../types/compatibility-types';
-import { DocumentProtection, RevisionViewSettings, WebSettingsInfo } from '../types/settings-types';
-import { CompatibilityUpgrader, UpgradeReport } from '../utils/CompatibilityUpgrader';
-import { MODERN_COMPAT_SETTINGS } from '../constants/legacyCompatFlags';
+} from '../formatting/NumberingManager.js';
+import { Style, StyleProperties } from '../formatting/Style.js';
+import { StylesManager } from '../formatting/StylesManager.js';
+import { FormatOptions, StyleApplyOptions } from '../types/formatting.js';
+import {
+  CompatibilityMode,
+  CompatibilityInfo,
+  CompatSetting,
+} from '../types/compatibility-types.js';
+import {
+  DocumentProtection,
+  RevisionViewSettings,
+  WebSettingsInfo,
+} from '../types/settings-types.js';
+import { CompatibilityUpgrader, UpgradeReport } from '../processors/CompatibilityUpgrader.js';
+import { MODERN_COMPAT_SETTINGS } from '../constants/legacyCompatFlags.js';
 // ListNormalizationOptions and ListNormalizationReport removed - normalizeTableLists moved to consumer
 import {
   ApplyStylesOptions,
@@ -61,10 +70,10 @@ import {
   StyleConfig,
   StyleRunFormatting,
   StyleParagraphFormatting,
-} from '../types/styleConfig';
+} from '../types/styleConfig.js';
 // ListNormalizer import removed - moved to consumer
-import { defaultLogger, ILogger, getGlobalLogger, createScopedLogger } from '../utils/logger';
-import { UNITS } from '../utils/units';
+import { defaultLogger, ILogger, getGlobalLogger, createScopedLogger } from '../utils/logger.js';
+import { UNITS } from '../utils/units.js';
 
 // Create scoped logger for Document operations
 function getLogger(): ILogger {
@@ -72,71 +81,36 @@ function getLogger(): ILogger {
 }
 // Raw XML revision acceptance - used at load time BEFORE parsing
 // cleanupRevisionMetadata - cleanup metadata files after in-memory acceptance
-import { acceptAllRevisions, cleanupRevisionMetadata } from '../utils/acceptRevisions';
+import { acceptAllRevisions, cleanupRevisionMetadata } from '../processors/acceptRevisions.js';
 // In-memory revision acceptance - used AFTER parsing, allows subsequent modifications
-import { acceptRevisionsInMemory } from '../utils/InMemoryRevisionAcceptor';
-import { stripTrackedChanges } from '../utils/stripTrackedChanges';
-import { diffText, diffHasUnchangedParts } from '../utils/textDiff';
-import { XMLBuilder } from '../xml/XMLBuilder';
-import { XMLParser } from '../xml/XMLParser';
-import { DocumentTrackingContext } from '../tracking/DocumentTrackingContext';
-import type { TrackingContext } from '../tracking/TrackingContext';
-import { ZipHandler } from '../zip/ZipHandler';
-import { DOCX_PATHS } from '../zip/types';
-import { DocumentGenerator } from './DocumentGenerator';
-import { DocumentIdManager } from './DocumentIdManager';
-import { DocumentParser } from './DocumentParser';
-import { DocumentValidator } from './DocumentValidator';
-import { RelationshipManager } from './RelationshipManager';
-import { RelationshipType } from './Relationship';
-import { BodyElement } from './DocumentContent';
-import { optimizeImage, ImageOptimizationResult } from '../images/ImageOptimizer';
-
-/**
- * Document properties (core and extended)
- */
-export interface DocumentProperties {
-  // Core Properties (docProps/core.xml)
-  title?: string;
-  subject?: string;
-  creator?: string;
-  keywords?: string;
-  description?: string;
-  lastModifiedBy?: string;
-  revision?: number;
-  created?: Date;
-  modified?: Date;
-  language?: string;
-  category?: string;
-  contentStatus?: string;
-
-  // Extended Properties (docProps/app.xml)
-  application?: string;
-  appVersion?: string;
-  company?: string;
-  manager?: string;
-  version?: string;
-
-  // Custom Properties (docProps/custom.xml)
-  customProperties?: Record<string, string | number | boolean | Date>;
-}
-
-/**
- * Document part representation
- * Represents any part within a DOCX package (XML, binary, etc.)
- */
-export interface DocumentPart {
-  /** Part name/path within the package */
-  name: string;
-  /** Part content (string for XML/text, Buffer for binary) */
-  content: string | Buffer;
-  /** MIME content type */
-  contentType?: string;
-  /** Whether the part is binary */
-  isBinary?: boolean;
-  /** Part size in bytes */
-  size?: number;
-}
+import { acceptRevisionsInMemory } from '../processors/InMemoryRevisionAcceptor.js';
+import { stripTrackedChanges } from '../processors/stripTrackedChanges.js';
+import { diffText, diffHasUnchangedParts } from '../utils/textDiff.js';
+import { XMLBuilder } from '../xml/XMLBuilder.js';
+import { XMLParser } from '../xml/XMLParser.js';
+import { DocumentTrackingContext } from '../tracking/DocumentTrackingContext.js';
+import type { TrackingContext } from '../tracking/TrackingContext.js';
+import { ZipHandler } from '../zip/ZipHandler.js';
+import { DOCX_PATHS } from '../zip/types.js';
+import { DocumentGenerator } from './DocumentGenerator.js';
+import { DocumentIdManager } from './DocumentIdManager.js';
+import { DocumentParser } from './DocumentParser.js';
+import { DocumentValidator } from './DocumentValidator.js';
+import {
+  DocumentEventEmitter,
+  type DocumentEventListener,
+  type DocumentEventType,
+} from './DocumentEvents.js';
+import { RelationshipManager } from './RelationshipManager.js';
+import { RelationshipType } from './Relationship.js';
+import { BodyElement } from './DocumentContent.js';
+import { optimizeImage, ImageOptimizationResult } from '../images/ImageOptimizer.js';
+
+// DocumentProperties / DocumentPart now live in `src/types/document-types.ts`
+// to break the Document ↔ DocumentParser/Generator/Validator cycle.
+// They are re-exported below for backward compat.
+export type { DocumentProperties, DocumentPart } from '../types/document-types.js';
+import type { DocumentProperties, DocumentPart } from '../types/document-types.js';
 
 /**
  * Document creation options
@@ -355,6 +329,23 @@ export class Document {
   private _originalCommentsXml?: string;
   private _commentsModified = false;
   private _originalCommentCompanionFiles = new Map<string, string>();
+
+  /** Event emitter for lifecycle and mutation events. */
+  private _events = new DocumentEventEmitter();
+
+  /**
+   * Serialization queue for save / toBuffer operations.
+   *
+   * Document is single-threaded by design — `prepareSave()` mutates shared
+   * managers (StylesManager, NumberingManager, ImageManager) without
+   * locking, so two concurrent saves would race on those managers and on
+   * the shared `zipHandler` files. The lock chains save / toBuffer calls
+   * onto a serial Promise so callers can fire `Promise.all([save(a),
+   * save(b)])` without corrupting state. Errors do not poison the queue —
+   * a failed save still releases the next waiter.
+   */
+  private _saveQueue: Promise<unknown> = Promise.resolve();
+
   /** Parts explicitly removed via removePart() — skip regeneration during save */
   private _removedParts = new Set<string>();
 
@@ -796,7 +787,9 @@ export class Document {
     const zipHandler = new ZipHandler();
     await zipHandler.load(filePath);
 
-    return Document.initializeFromZip(zipHandler, options);
+    const doc = await Document.initializeFromZip(zipHandler, options);
+    doc._events.emit('afterLoad', { source: 'file', path: filePath });
+    return doc;
   }
 
   /**
@@ -834,7 +827,9 @@ export class Document {
     const zipHandler = new ZipHandler();
     await zipHandler.loadFromBuffer(buffer);
 
-    return Document.initializeFromZip(zipHandler, options);
+    const doc = await Document.initializeFromZip(zipHandler, options);
+    doc._events.emit('afterLoad', { source: 'buffer' });
+    return doc;
   }
 
   /**
@@ -975,32 +970,67 @@ export class Document {
       }
     }
 
-    // Parse w:doNotTrackFormatting - presence means formatting tracking is disabled
-    const hasDoNotTrackFormatting = /<w:doNotTrackFormatting\b[^>]*\/?>/.test(settingsXml);
-    if (hasDoNotTrackFormatting) {
+    // Helper: parse a settings-level CT_OnOff flag. Returns undefined when the
+    // element is absent, or the actual boolean (respecting w:val's ST_OnOff
+    // value — "0"/"1"/"true"/"false"/"on"/"off") when present. A bare element
+    // without w:val defaults to true per ECMA-376 §17.17.4.
+    const parseSettingCtOnOff = (tagName: string): boolean | undefined => {
+      const re = new RegExp(`<${tagName}\\b([^>]*)\\/?>`);
+      const m = re.exec(settingsXml);
+      if (!m) return undefined;
+      const attrs = m[1] ?? '';
+      const valMatch = /w:val\s*=\s*"([^"]*)"/.exec(attrs);
+      if (!valMatch || valMatch[1] === undefined) return true;
+      const v = valMatch[1].toLowerCase();
+      return v !== '0' && v !== 'false' && v !== 'off';
+    };
+
+    // Parse w:doNotTrackFormatting - CT_OnOff; when true, formatting tracking
+    // is disabled. (Previously tested presence only, so `<w:doNotTrackFormatting
+    // w:val="0"/>` was silently taken to disable tracking even though it means
+    // "do not [do not track formatting]" = track formatting normally.)
+    const doNotTrackFormattingVal = parseSettingCtOnOff('w:doNotTrackFormatting');
+    if (doNotTrackFormattingVal === true) {
       this.trackFormatting = false;
-    }
-    // Parse w:trackFormatting - explicit presence means formatting tracking is enabled
-    const hasTrackFormatting = /<w:trackFormatting\b[^>]*\/?>/.test(settingsXml);
-    if (hasTrackFormatting) {
+    } else if (doNotTrackFormattingVal === false) {
       this.trackFormatting = true;
     }
+    // Parse w:trackFormatting - CT_OnOff; explicit true enables formatting tracking.
+    const trackFormattingVal = parseSettingCtOnOff('w:trackFormatting');
+    if (trackFormattingVal !== undefined) {
+      this.trackFormatting = trackFormattingVal;
+    }
 
-    // Parse w:revisionView
+    // Parse w:revisionView per ECMA-376 §17.15.1.77 (CT_TrackChangesView).
+    // @w:insDel / @w:formatting / @w:inkAnnotations are ST_OnOff attributes;
+    // accept every literal (1/0/true/false/on/off). Prior code used `!== '0'`
+    // which flipped "false" and "off" to true, silently misreporting the
+    // tracked-changes display configuration.
     const revisionViewMatch = /<w:revisionView\b([^>]*)\/?>/.exec(settingsXml);
     if (revisionViewMatch) {
       const attrs = revisionViewMatch[1] || '';
       const insDelMatch = /w:insDel\s*=\s*"([^"]*)"/.exec(attrs);
       const formattingMatch = /w:formatting\s*=\s*"([^"]*)"/.exec(attrs);
       const inkMatch = /w:inkAnnotations\s*=\s*"([^"]*)"/.exec(attrs);
+      // CT_TrackChangesView also carries w:markup (all revision markup)
+      // and w:comments (balloon visibility). Both were previously dropped
+      // on the parser even though the element was already extracted.
+      const markupMatch = /w:markup\s*=\s*"([^"]*)"/.exec(attrs);
+      const commentsMatch = /w:comments\s*=\s*"([^"]*)"/.exec(attrs);
       if (insDelMatch?.[1] !== undefined) {
-        this.revisionViewSettings.showInsertionsAndDeletions = insDelMatch[1] !== '0';
+        this.revisionViewSettings.showInsertionsAndDeletions = parseOnOffAttribute(insDelMatch[1]);
       }
       if (formattingMatch?.[1] !== undefined) {
-        this.revisionViewSettings.showFormatting = formattingMatch[1] !== '0';
+        this.revisionViewSettings.showFormatting = parseOnOffAttribute(formattingMatch[1]);
       }
       if (inkMatch?.[1] !== undefined) {
-        this.revisionViewSettings.showInkAnnotations = inkMatch[1] !== '0';
+        this.revisionViewSettings.showInkAnnotations = parseOnOffAttribute(inkMatch[1]);
+      }
+      if (markupMatch?.[1] !== undefined) {
+        this.revisionViewSettings.showMarkup = parseOnOffAttribute(markupMatch[1]);
+      }
+      if (commentsMatch?.[1] !== undefined) {
+        this.revisionViewSettings.showComments = parseOnOffAttribute(commentsMatch[1]);
       }
     }
 
@@ -1012,9 +1042,19 @@ export class Document {
       const enforcementMatch = /w:enforcement\s*=\s*"([^"]*)"/.exec(attrs);
       if (editMatch?.[1]) {
         const edit = editMatch[1] as 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
-        const enforcement = enforcementMatch?.[1] ? enforcementMatch[1] !== '0' : true;
+        // @w:enforcement is ST_OnOff — honour every literal. Default true when absent
+        // per ECMA-376 §17.15.1.29. Prior `!== '0'` missed "false" and "off".
+        const enforcement = enforcementMatch?.[1] ? parseOnOffAttribute(enforcementMatch[1]) : true;
         this.documentProtection = { edit, enforcement };
 
+        // `w:formatting` per CT_DocProtect §17.15.1.29 — ST_OnOff. When true,
+        // formatting changes are allowed even under edit protection. Parse
+        // with parseOnOffAttribute so every ST_OnOff literal maps correctly.
+        const formattingMatch = /w:formatting\s*=\s*"([^"]*)"/.exec(attrs);
+        if (formattingMatch?.[1] !== undefined) {
+          this.documentProtection.formatting = parseOnOffAttribute(formattingMatch[1]);
+        }
+
         // Parse optional crypto attributes
         const cryptProviderMatch = /w:cryptProviderType\s*=\s*"([^"]*)"/.exec(attrs);
         const cryptAlgClassMatch = /w:cryptAlgorithmClass\s*=\s*"([^"]*)"/.exec(attrs);
@@ -1036,6 +1076,20 @@ export class Document {
           this.documentProtection.cryptSpinCount = parseInt(cryptSpinMatch[1], 10);
         if (hashMatch?.[1]) this.documentProtection.hash = hashMatch[1];
         if (saltMatch?.[1]) this.documentProtection.salt = saltMatch[1];
+
+        // Modern Word 2013+ crypto attributes (ISO/IEC 29500-4 §13).
+        // Previously dropped on parse — a password-protected document
+        // saved by modern Word lost its hash/salt on any programmatic
+        // resave because the legacy `hash`/`salt` regex no longer matches
+        // the modern `hashValue`/`saltValue` attribute names.
+        const algorithmNameMatch = /w:algorithmName\s*=\s*"([^"]*)"/.exec(attrs);
+        const hashValueMatch = /w:hashValue\s*=\s*"([^"]*)"/.exec(attrs);
+        const saltValueMatch = /w:saltValue\s*=\s*"([^"]*)"/.exec(attrs);
+        if (algorithmNameMatch?.[1]) {
+          this.documentProtection.algorithmName = algorithmNameMatch[1];
+        }
+        if (hashValueMatch?.[1]) this.documentProtection.hashValue = hashValueMatch[1];
+        if (saltValueMatch?.[1]) this.documentProtection.saltValue = saltValueMatch[1];
       }
     }
 
@@ -1069,30 +1123,25 @@ export class Document {
       this._documentView = viewMatch[1];
     }
 
-    // Parse w:evenAndOddHeaders per ECMA-376 Part 1 §17.15.1.28
-    if (/<w:evenAndOddHeaders\b[^>]*\/?>/.test(settingsXml)) {
-      this._evenAndOddHeaders = true;
-    }
+    // CT_OnOff settings flags (ECMA-376 §17.15.1). Each honours w:val via the
+    // parseSettingCtOnOff helper defined above — previously these used a simple
+    // presence-detect regex and silently flipped explicit `<w:X w:val="0"/>` to
+    // true, corrupting any source document that recorded an explicit-off state.
+    const evenAndOddHeadersVal = parseSettingCtOnOff('w:evenAndOddHeaders');
+    if (evenAndOddHeadersVal !== undefined) this._evenAndOddHeaders = evenAndOddHeadersVal;
 
-    // Parse w:mirrorMargins per ECMA-376 Part 1 §17.15.1.57
-    if (/<w:mirrorMargins\b[^>]*\/?>/.test(settingsXml)) {
-      this._mirrorMargins = true;
-    }
+    const mirrorMarginsVal = parseSettingCtOnOff('w:mirrorMargins');
+    if (mirrorMarginsVal !== undefined) this._mirrorMargins = mirrorMarginsVal;
 
-    // Parse w:autoHyphenation per ECMA-376 Part 1 §17.15.1.10
-    if (/<w:autoHyphenation\b[^>]*\/?>/.test(settingsXml)) {
-      this._autoHyphenation = true;
-    }
+    const autoHyphenationVal = parseSettingCtOnOff('w:autoHyphenation');
+    if (autoHyphenationVal !== undefined) this._autoHyphenation = autoHyphenationVal;
 
-    // Parse w:hideSpellingErrors per ECMA-376 Part 1 §17.15.1.43
-    if (/<w:hideSpellingErrors\b[^>]*\/?>/.test(settingsXml)) {
-      this._hideSpellingErrors = true;
-    }
+    const hideSpellingErrorsVal = parseSettingCtOnOff('w:hideSpellingErrors');
+    if (hideSpellingErrorsVal !== undefined) this._hideSpellingErrors = hideSpellingErrorsVal;
 
-    // Parse w:hideGrammaticalErrors per ECMA-376 Part 1 §17.15.1.42
-    if (/<w:hideGrammaticalErrors\b[^>]*\/?>/.test(settingsXml)) {
-      this._hideGrammaticalErrors = true;
-    }
+    const hideGrammaticalErrorsVal = parseSettingCtOnOff('w:hideGrammaticalErrors');
+    if (hideGrammaticalErrorsVal !== undefined)
+      this._hideGrammaticalErrors = hideGrammaticalErrorsVal;
 
     // Parse w:defaultTabStop per ECMA-376 Part 1 §17.15.1.25
     const defaultTabStopMatch = /<w:defaultTabStop\s+w:val\s*=\s*"(\d+)"\s*\/?>/.exec(settingsXml);
@@ -1100,25 +1149,18 @@ export class Document {
       this._defaultTabStop = parseInt(defaultTabStopMatch[1], 10);
     }
 
-    // Parse w:updateFields per ECMA-376 Part 1 §17.15.1.85
-    if (/<w:updateFields\b[^>]*\/?>/.test(settingsXml)) {
-      this._updateFields = true;
-    }
+    const updateFieldsVal = parseSettingCtOnOff('w:updateFields');
+    if (updateFieldsVal !== undefined) this._updateFields = updateFieldsVal;
 
-    // Parse w:embedTrueTypeFonts per ECMA-376 Part 1 §17.15.1.24
-    if (/<w:embedTrueTypeFonts\b[^>]*\/?>/.test(settingsXml)) {
-      this._embedTrueTypeFonts = true;
-    }
+    const embedTrueTypeFontsVal = parseSettingCtOnOff('w:embedTrueTypeFonts');
+    if (embedTrueTypeFontsVal !== undefined) this._embedTrueTypeFonts = embedTrueTypeFontsVal;
 
-    // Parse w:saveSubsetFonts per ECMA-376 Part 1 §17.15.1.78
-    if (/<w:saveSubsetFonts\b[^>]*\/?>/.test(settingsXml)) {
-      this._saveSubsetFonts = true;
-    }
+    const saveSubsetFontsVal = parseSettingCtOnOff('w:saveSubsetFonts');
+    if (saveSubsetFontsVal !== undefined) this._saveSubsetFonts = saveSubsetFontsVal;
 
-    // Parse w:doNotTrackMoves per ECMA-376 Part 1 §17.15.1.35
-    if (/<w:doNotTrackMoves\b[^>]*\/?>/.test(settingsXml)) {
-      this._doNotTrackMoves = true;
-    }
+    // w:doNotTrackMoves — tracked-changes-specific CT_OnOff flag.
+    const doNotTrackMovesVal = parseSettingCtOnOff('w:doNotTrackMoves');
+    if (doNotTrackMovesVal !== undefined) this._doNotTrackMoves = doNotTrackMovesVal;
 
     // Parse w:decimalSymbol per ECMA-376 Part 1 §17.15.1.23
     const decimalMatch = /<w:decimalSymbol\s+w:val\s*=\s*"([^"]*)"\s*\/?>/.exec(settingsXml);
@@ -1615,6 +1657,7 @@ export class Document {
     }
 
     this.bodyElements.push(paragraph);
+    this._emitElementAdded(paragraph, this.bodyElements.length - 1);
     return this;
   }
 
@@ -1656,7 +1699,10 @@ export class Document {
     if (text) {
       para.addText(text);
     }
+    // Apply global defaults (font / size) if registered.
+    Document.applyGlobalDefaultsToParagraph(para);
     this.bodyElements.push(para);
+    this._emitElementAdded(para, this.bodyElements.length - 1);
     return para;
   }
 
@@ -1762,6 +1808,7 @@ export class Document {
     }
 
     this.bodyElements.push(table);
+    this._emitElementAdded(table, this.bodyElements.length - 1);
     return this;
   }
 
@@ -1783,6 +1830,7 @@ export class Document {
    */
   addStructuredDocumentTag(sdt: StructuredDocumentTag): this {
     this.bodyElements.push(sdt);
+    this._emitElementAdded(sdt, this.bodyElements.length - 1);
     return this;
   }
 
@@ -1818,6 +1866,7 @@ export class Document {
     const table = new Table(rows, columns);
     table._setStylesManager(this.stylesManager);
     this.bodyElements.push(table);
+    this._emitElementAdded(table, this.bodyElements.length - 1);
     return table;
   }
 
@@ -1844,6 +1893,7 @@ export class Document {
     const table = Table.fromCSV(csv, delimiter);
     table._setStylesManager(this.stylesManager);
     this.bodyElements.push(table);
+    this._emitElementAdded(table, this.bodyElements.length - 1);
     return table;
   }
 
@@ -1949,6 +1999,75 @@ export class Document {
     return result;
   }
 
+  /**
+   * Lazy iterator over every paragraph in the document. Yields the same
+   * set as `getAllParagraphs()` (including paragraphs inside table cells
+   * and nested SDTs) without materialising the full array — for memory
+   * pipelines over very large documents.
+   *
+   * Mutations during iteration are not protected — callers must not
+   * structurally mutate the document while iterating.
+   */
+  *iterateParagraphs(): IterableIterator<Paragraph> {
+    yield* Document.walkParagraphs(this.bodyElements);
+  }
+
+  private static *walkParagraphs(elements: BodyElement[]): IterableIterator<Paragraph> {
+    for (const element of elements) {
+      if (element instanceof Paragraph) {
+        yield element;
+      } else if (element instanceof Table) {
+        for (const row of element.getRows()) {
+          for (const cell of row.getCells()) {
+            for (const cellPara of cell.getParagraphs()) {
+              yield cellPara;
+            }
+          }
+        }
+      } else if (element instanceof StructuredDocumentTag) {
+        yield* Document.walkParagraphs(element.getContent() as BodyElement[]);
+      }
+    }
+  }
+
+  /**
+   * Lazy iterator over the top-level body elements (paragraphs, tables,
+   * SDTs, custom XML blocks) in document order. Use this when table or
+   * SDT boundaries matter to your pipeline.
+   */
+  *iterateBodyElements(): IterableIterator<BodyElement> {
+    for (const element of this.bodyElements) {
+      yield element;
+    }
+  }
+
+  /**
+   * Lazy iterator that yields each section in the document along with
+   * the body elements belonging to it. A section break is identified by
+   * a paragraph carrying its own `sectPr` (CT_SectPr); the document's
+   * root `Section` closes the final group.
+   *
+   * @yields `{ sectPr, elements }` where `sectPr` is the raw section-
+   *   properties marker (string or parsed object) for inline section
+   *   breaks, or the document's root `Section` for the trailing group.
+   */
+  *iterateSections(): IterableIterator<{
+    sectPr: string | Record<string, unknown> | Section | null;
+    elements: BodyElement[];
+  }> {
+    let current: BodyElement[] = [];
+    for (const element of this.bodyElements) {
+      current.push(element);
+      if (element instanceof Paragraph && element.formatting.sectPr) {
+        yield { sectPr: element.formatting.sectPr, elements: current };
+        current = [];
+      }
+    }
+    if (current.length > 0) {
+      yield { sectPr: this.section ?? null, elements: current };
+    }
+  }
+
   /**
    * Gets all paragraphs in the document (alias for getAllParagraphs)
    * @returns Array of all paragraphs recursively
@@ -2065,6 +2184,7 @@ export class Document {
    */
   addBodyElement(element: BodyElement): this {
     this.bodyElements.push(element);
+    this._emitElementAdded(element, this.bodyElements.length - 1);
     return this;
   }
 
@@ -2510,8 +2630,25 @@ export class Document {
    * ```
    */
   async save(filePath: string): Promise<void> {
+    return this.withSaveLock(() => this.saveImpl(filePath));
+  }
+
+  /**
+   * Chains an operation onto the serial save queue. Concurrent callers
+   * (e.g., `Promise.all([doc.save(a), doc.save(b)])`) are serialised so
+   * `prepareSave()` and the underlying ZIP cannot race. The chain
+   * survives errors — a failed operation releases the next waiter.
+   */
+  private withSaveLock<T>(operation: () => Promise<T>): Promise<T> {
+    const next = this._saveQueue.then(operation, operation);
+    this._saveQueue = next.catch(() => undefined);
+    return next;
+  }
+
+  private async saveImpl(filePath: string): Promise<void> {
     const logger = getLogger();
     logger.info('Saving document', { path: filePath, paragraphs: this.getParagraphCount() });
+    this._events.emit('beforeSave', { filePath });
 
     // Use atomic save pattern: save to temp file, then rename
     // This prevents partial/corrupted saves if operation fails mid-way
@@ -2542,6 +2679,7 @@ export class Document {
       saveSucceeded = true;
       this.clearSaveStateSnapshot();
       logger.info('Document saved', { path: filePath });
+      this._events.emit('afterSave', { filePath });
     } catch (error: unknown) {
       // Restore state snapshot on failure - allows retry without data loss
       this.restoreSaveStateSnapshot();
@@ -2592,8 +2730,13 @@ export class Document {
    * ```
    */
   async toBuffer(): Promise<Buffer> {
+    return this.withSaveLock(() => this.toBufferImpl());
+  }
+
+  private async toBufferImpl(): Promise<Buffer> {
     const logger = getLogger();
     logger.info('Generating document buffer', { paragraphs: this.getParagraphCount() });
+    this._events.emit('beforeSave', {});
 
     // Track whether generation succeeded for proper cleanup
     let generateSucceeded = false;
@@ -2621,6 +2764,7 @@ export class Document {
       generateSucceeded = true;
       this.clearSaveStateSnapshot();
       logger.info('Document buffer generated', { bufferSize: buffer.length });
+      this._events.emit('afterSave', { bufferSize: buffer.length });
       return buffer;
     } catch (error: unknown) {
       // Restore state snapshot on failure - allows retry without data loss
@@ -3335,17 +3479,46 @@ export class Document {
     if (!this._originalWebSettingsXml) {
       return 0;
     }
-    const matches = this._originalWebSettingsXml.match(/<w:div\b/g);
+    const original = this._originalWebSettingsXml;
+    const matches = original.match(/<w:div\b/g);
     const count = matches ? matches.length : 0;
     if (count === 0) {
       return 0;
     }
-    this._originalWebSettingsXml = this._originalWebSettingsXml.replace(
-      /<w:divs>[\s\S]*?<\/w:divs>/g,
-      ''
-    );
-    this._webSettingsModified = true;
-    return count;
+    // Mutate via try/catch + post-mutation validation. If the regex match
+    // accidentally produces malformed XML (e.g., a partial `<w:divs>` open
+    // tag with no close), revert to the pre-mutation snapshot rather than
+    // persisting corruption.
+    try {
+      const mutated = original.replace(/<w:divs>[\s\S]*?<\/w:divs>/g, '');
+      // Sanity check: result must still parse as well-formed root XML.
+      // `<?xml ...?>` prologue must survive, and tag balance must match.
+      if (!Document.isWellFormedXml(mutated)) {
+        getLogger().warn('stripWebDivs produced malformed XML; reverting');
+        return 0;
+      }
+      this._originalWebSettingsXml = mutated;
+      this._webSettingsModified = true;
+      return count;
+    } catch (err) {
+      getLogger().warn('stripWebDivs failed; reverting', { error: String(err) });
+      this._originalWebSettingsXml = original;
+      return 0;
+    }
+  }
+
+  /**
+   * Lightweight well-formedness check for in-place XML mutations.
+   * Verifies tag balance (open/close counts match for each element name)
+   * and that any XML prologue remains intact. Sufficient for catching
+   * regex string.replace() failures that bisect a tag.
+   */
+  private static isWellFormedXml(xml: string): boolean {
+    if (xml.length === 0) return true;
+    // Count opening and closing tags. Self-closing tags don't need a closer.
+    const openTags = xml.match(/<([a-zA-Z_][^\s/>]*)\b[^>]*[^/]>/g) || [];
+    const closeTags = xml.match(/<\/([a-zA-Z_][^\s>]*)\s*>/g) || [];
+    return openTags.length === closeTags.length;
   }
 
   /**
@@ -4137,7 +4310,7 @@ export class Document {
     table: Table,
     row: number,
     col: number
-  ): import('../elements/CommonTypes').ShadingConfig | undefined {
+  ): import('../elements/CommonTypes.js').ShadingConfig | undefined {
     const tableRow = table.getRow(row);
     if (!tableRow) return undefined;
     const cell = tableRow.getCell(col);
@@ -6835,6 +7008,15 @@ export class Document {
    * });
    * ```
    */
+  private static stripThemeFontsIfExplicitFont(runConfig: any): void {
+    if (runConfig?.font) {
+      delete runConfig.fontAsciiTheme;
+      delete runConfig.fontHAnsiTheme;
+      delete runConfig.fontEastAsiaTheme;
+      delete runConfig.fontCsTheme;
+    }
+  }
+
   public applyStyles(options?: ApplyStylesOptions): {
     heading1: boolean;
     heading2: boolean;
@@ -6915,6 +7097,14 @@ export class Document {
       },
     };
 
+    // Strip theme font attributes when an explicit font is provided,
+    // because Word prioritizes theme fonts over explicit font names.
+    Document.stripThemeFontsIfExplicitFont(h1Config.run);
+    Document.stripThemeFontsIfExplicitFont(h2Config.run);
+    Document.stripThemeFontsIfExplicitFont(h3Config.run);
+    Document.stripThemeFontsIfExplicitFont(normalConfig.run);
+    Document.stripThemeFontsIfExplicitFont(listParaConfig.run);
+
     // Extract preserve blank lines option (defaults to true)
     const preserveBlankLines = options?.preserveBlankLinesAfterHeading2Tables ?? true;
 
@@ -13031,10 +13221,118 @@ export class Document {
    * Call this after saving in long-running processes to free memory
    * Especially important for API servers processing many documents
    */
+  // ============================================================================
+  // Event API
+  // ============================================================================
+
+  /**
+   * Subscribe to a document lifecycle / mutation event. Returns an
+   * unsubscribe function so callers don't have to retain the listener
+   * reference for `off()`.
+   *
+   * Listener errors are caught and logged via the global logger — a
+   * misbehaving listener cannot abort `save()` or break document state.
+   *
+   * @example
+   * ```typescript
+   * const dispose = doc.on('paragraphAdded', ({ paragraph }) => {
+   *   audit.append(paragraph.getText());
+   * });
+   * // later
+   * dispose();
+   * ```
+   */
+  on<T extends DocumentEventType>(event: T, listener: DocumentEventListener<T>): () => void {
+    return this._events.on(event, listener);
+  }
+
+  /** Remove a previously registered event listener. */
+  off<T extends DocumentEventType>(event: T, listener: DocumentEventListener<T>): void {
+    this._events.off(event, listener);
+  }
+
+  /** Number of listeners registered for a given event. Useful for tests. */
+  listenerCount(event: DocumentEventType): number {
+    return this._events.listenerCount(event);
+  }
+
+  /**
+   * Emit the appropriate mutation event for `element`. No-op for body
+   * element types that don't have a dedicated event (SDT, TOC, custom XML).
+   * Centralised so every public add/insert path emits consistently.
+   */
+  private _emitElementAdded(element: BodyElement, index: number): void {
+    if (element instanceof Paragraph) {
+      this._events.emit('paragraphAdded', { paragraph: element, index });
+    } else if (element instanceof Table) {
+      this._events.emit('tableAdded', { table: element });
+    }
+  }
+
+  private _emitElementRemoved(element: BodyElement | undefined): void {
+    if (!element) return;
+    if (element instanceof Paragraph) {
+      this._events.emit('paragraphRemoved', { paragraph: element });
+    } else if (element instanceof Table) {
+      this._events.emit('tableRemoved', { table: element });
+    }
+  }
+
+  // ============================================================================
+  // Global defaults
+  // ============================================================================
+
+  /**
+   * Default font, size, and margins applied to paragraphs created via
+   * `createParagraph()` after `Document.setDefaults(...)` is called.
+   * These are runtime defaults — they do not modify document XML directly,
+   * they pre-populate run formatting on newly created elements only.
+   */
+  private static globalDefaults: {
+    font?: string;
+    fontSize?: number;
+    fontColor?: string;
+  } = {};
+
+  /**
+   * Set framework-wide defaults applied to every new paragraph created
+   * via `Document.create()` + `createParagraph()`. Existing documents and
+   * existing paragraphs are not retroactively modified. Pass an empty
+   * object to clear.
+   */
+  static setDefaults(defaults: { font?: string; fontSize?: number; fontColor?: string }): void {
+    Document.globalDefaults = { ...defaults };
+  }
+
+  /** Returns the currently registered global defaults (read-only copy). */
+  static getDefaults(): Readonly<{ font?: string; fontSize?: number; fontColor?: string }> {
+    return { ...Document.globalDefaults };
+  }
+
+  /** Reset all global defaults. */
+  static resetDefaults(): void {
+    Document.globalDefaults = {};
+  }
+
+  /** Apply globalDefaults to runs already on a freshly-created paragraph. */
+  private static applyGlobalDefaultsToParagraph(para: Paragraph): void {
+    const d = Document.globalDefaults;
+    if (!d.font && d.fontSize === undefined && !d.fontColor) return;
+    for (const run of para.getRuns()) {
+      const fmt = run.getFormatting();
+      if (d.font && !fmt.font) run.setFont(d.font);
+      if (d.fontSize !== undefined && fmt.size === undefined) run.setSize(d.fontSize);
+      if (d.fontColor && !fmt.color) run.setColor(d.fontColor);
+    }
+  }
+
   dispose(): void {
     // Clear all internal state to free memory
     // NOTE: Use clear() methods instead of creating new instances to properly free memory
 
+    // Remove all event listeners to free closure references
+    this._events.removeAllListeners();
+
     // Clear body elements
     this.bodyElements = [];
 
@@ -15582,7 +15880,9 @@ export class Document {
     if (index >= 0 && index < this.bodyElements.length) {
       const element = this.bodyElements[index];
       if (element instanceof Paragraph) {
-        // When tracking enabled, wrap content in w:del instead of removing
+        // When tracking enabled, wrap content in w:del instead of removing.
+        // No paragraphRemoved event in this branch — the paragraph is still
+        // structurally present, just marked deleted via revision.
         if (this.trackChangesEnabled && this.trackingContext.isEnabled()) {
           const runs = element.getRuns();
           if (runs.length > 0) {
@@ -15594,6 +15894,7 @@ export class Document {
           return true;
         }
         this.bodyElements.splice(index, 1);
+        this._emitElementRemoved(element);
         return true;
       }
     }
@@ -15628,6 +15929,7 @@ export class Document {
       const element = this.bodyElements[index];
       if (element instanceof Table) {
         this.bodyElements.splice(index, 1);
+        this._emitElementRemoved(element);
         return true;
       }
     }
@@ -15771,6 +16073,7 @@ export class Document {
 
     // Insert the paragraph
     this.bodyElements.splice(index, 0, paragraph);
+    this._emitElementAdded(paragraph, index);
     return this;
   }
 
@@ -15795,6 +16098,7 @@ export class Document {
 
     // Insert the table
     this.bodyElements.splice(index, 0, table);
+    this._emitElementAdded(table, index);
     return this;
   }
 
@@ -16002,7 +16306,8 @@ export class Document {
    */
   removeBodyElementAt(index: number): boolean {
     if (index >= 0 && index < this.bodyElements.length) {
-      this.bodyElements.splice(index, 1);
+      const [removed] = this.bodyElements.splice(index, 1);
+      this._emitElementRemoved(removed);
       return true;
     }
     return false;
@@ -16034,6 +16339,7 @@ export class Document {
     const index = this.bodyElements.indexOf(element);
     if (index === -1) return false;
     this.bodyElements.splice(index, 1);
+    this._emitElementRemoved(element);
     return true;
   }
 
@@ -16065,6 +16371,7 @@ export class Document {
     const index = this.bodyElements.indexOf(reference);
     if (index === -1) return false;
     this.bodyElements.splice(index + 1, 0, element);
+    this._emitElementAdded(element, index + 1);
     return true;
   }
 
@@ -16092,6 +16399,7 @@ export class Document {
     const index = this.bodyElements.indexOf(reference);
     if (index === -1) return false;
     this.bodyElements.splice(index, 0, element);
+    this._emitElementAdded(element, index);
     return true;
   }
 
@@ -16121,6 +16429,8 @@ export class Document {
     const index = this.bodyElements.indexOf(oldElement);
     if (index === -1) return false;
     this.bodyElements[index] = newElement;
+    this._emitElementRemoved(oldElement);
+    this._emitElementAdded(newElement, index);
     return true;
   }
 
@@ -16138,6 +16448,7 @@ export class Document {
   insertBodyElementAt(index: number, element: BodyElement): void {
     const clampedIndex = Math.max(0, Math.min(index, this.bodyElements.length));
     this.bodyElements.splice(clampedIndex, 0, element);
+    this._emitElementAdded(element, clampedIndex);
   }
 
   /**