docxmlater 11.0.9 → 12.0.1

package/src/core/Document.ts

@@ -86,12 +86,13 @@ import { acceptAllRevisions, cleanupRevisionMetadata } from '../processors/accep
 import { acceptRevisionsInMemory } from '../processors/InMemoryRevisionAcceptor.js';
 import { stripTrackedChanges } from '../processors/stripTrackedChanges.js';
 import { diffText, diffHasUnchangedParts } from '../utils/textDiff.js';
+import { reorderRunPropertyChildren } from '../utils/xmlSanitization.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 { DOCX_PATHS, SizeLimitOptions } from '../zip/types.js';
 import { DocumentGenerator } from './DocumentGenerator.js';
 import { DocumentIdManager } from './DocumentIdManager.js';
 import { DocumentParser } from './DocumentParser.js';
@@ -102,7 +103,7 @@ import {
   type DocumentEventType,
 } from './DocumentEvents.js';
 import { RelationshipManager } from './RelationshipManager.js';
-import { RelationshipType } from './Relationship.js';
+import { Relationship, RelationshipType } from './Relationship.js';
 import { BodyElement } from './DocumentContent.js';
 import { optimizeImage, ImageOptimizationResult } from '../images/ImageOptimizer.js';
 
@@ -156,7 +157,7 @@ export interface DocumentLoadOptions extends DocumentOptions {
    *
    * - 'preserve': Keep tracked changes as-is (may cause corruption if IDs conflict)
    * - 'accept': Accept all changes - removes revision markup, keeps inserted content, removes deleted content (default)
-   * - 'strip': Remove all revision markup completely
+   * - 'strip': Remove all revision markup, keeping inserted content and removing deleted content (same resulting text as 'accept')
    *
    * Default: 'accept' (prevents corruption from revision ID conflicts)
    *
@@ -209,6 +210,68 @@ export interface DocumentLoadOptions extends DocumentOptions {
    * ```
    */
   acceptRevisions?: boolean;
+
+  /**
+   * Resource limits applied while reading the DOCX archive.
+   *
+   * Forwarded to the underlying ZIP reader to guard against availability
+   * attacks (zip bombs, entry-count amplification) when loading untrusted
+   * input. Defaults are intentionally generous so legitimate documents load
+   * unchanged; tighten the fields on {@link SizeLimitOptions} for untrusted
+   * sources.
+   *
+   * @example
+   * ```typescript
+   * const doc = await Document.load('untrusted.docx', {
+   *   sizeLimits: { maxTotalUncompressedMB: 100, maxEntryCount: 500 },
+   * });
+   * ```
+   */
+  sizeLimits?: SizeLimitOptions;
+}
+
+/**
+ * Options controlling {@link Document.toMarkdown} conversion fidelity.
+ *
+ * Markdown cannot natively express every Word construct, so the converter
+ * falls back to inline HTML (when {@link htmlFallback} is enabled) for things
+ * like underline, super/subscript, highlight and color, and collects
+ * footnotes/endnotes as GFM-style references. These options let callers tune
+ * how aggressively that extra information is preserved.
+ */
+export interface MarkdownConversionOptions {
+  /**
+   * Emit inline HTML for character formatting Markdown cannot represent:
+   * underline (`<u>`), superscript (`<sup>`), subscript (`<sub>`), highlight
+   * (`<mark>`) and text color (`<span style="color:#…">`). Tracked deletions
+   * (in `'preserve'` mode) are wrapped in `<del>`. When `false`, that
+   * formatting is dropped but the text itself is still emitted. Default: `true`.
+   */
+  htmlFallback?: boolean;
+  /**
+   * Collect footnote/endnote references as GFM footnote markers (`[^fn1]`,
+   * `[^en1]`) and append their definitions at the end of the output.
+   * Default: `true`.
+   */
+  footnotes?: boolean;
+  /**
+   * Emit inline images as `![alt](src)` where `src` is the image's
+   * relationship id (or a placeholder for unsaved documents). When `false`,
+   * images are skipped. Default: `true`.
+   */
+  images?: boolean;
+}
+
+/**
+ * Internal state threaded through a single Markdown conversion pass.
+ * @internal
+ */
+interface MarkdownContext {
+  opts: Required<MarkdownConversionOptions>;
+  /** Ordered, de-duplicated footnote/endnote definitions to append at the end. */
+  notes: { marker: string; text: string }[];
+  /** Markers already emitted, to avoid duplicate definitions. */
+  noteMarkers: Set<string>;
 }
 
 /**
@@ -249,6 +312,12 @@ export class Document {
       () => this.documentIdManager.getNextId(),
       (existingId) => this.documentIdManager.ensureNextIdAbove(existingId)
     );
+    // Instance-level comment edits (resolve, setAuthor, addRun, ...) must
+    // flip the dirty flag, otherwise saveComments() takes the passthrough
+    // branch and writes the original comments.xml, silently dropping them
+    this.commentManager.setModifiedNotifier(() => {
+      this._commentsModified = true;
+    });
 
     this.trackingContext = new DocumentTrackingContext(this.revisionManager);
     this.parser = new DocumentParser();
@@ -324,6 +393,7 @@ export class Document {
   private _originalNumberingXml?: string;
   private _originalSettingsXml?: string;
   private _originalAppPropsXml?: string;
+  private _originalCorePropsXml?: string;
   private _originalFootnotesXml?: string;
   private _originalEndnotesXml?: string;
   private _originalCommentsXml?: string;
@@ -352,6 +422,9 @@ export class Document {
   // Track whether app properties have been programmatically modified since load
   private _appPropsModified = false;
 
+  // Track whether core properties have been programmatically modified since load
+  private _corePropsModified = false;
+
   // Track whether footnotes/endnotes have been programmatically modified since load
   private _footnotesModified = false;
   private _endnotesModified = false;
@@ -785,7 +858,7 @@ export class Document {
     logger.info('Loading document from file', { path: filePath });
 
     const zipHandler = new ZipHandler();
-    await zipHandler.load(filePath);
+    await zipHandler.load(filePath, { sizeLimits: options?.sizeLimits });
 
     const doc = await Document.initializeFromZip(zipHandler, options);
     doc._events.emit('afterLoad', { source: 'file', path: filePath });
@@ -825,7 +898,7 @@ export class Document {
     logger.info('Loading document from buffer', { bufferSize: buffer.length });
 
     const zipHandler = new ZipHandler();
-    await zipHandler.loadFromBuffer(buffer);
+    await zipHandler.loadFromBuffer(buffer, { sizeLimits: options?.sizeLimits });
 
     const doc = await Document.initializeFromZip(zipHandler, options);
     doc._events.emit('afterLoad', { source: 'buffer' });
@@ -890,7 +963,10 @@ export class Document {
 
     const numberingXml = zipHandler.getFileAsString(DOCX_PATHS.NUMBERING);
     if (numberingXml) {
-      doc._originalNumberingXml = numberingXml;
+      // Numbering definitions are written back verbatim for fidelity, so repair
+      // any out-of-order w:rPr children here (e.g. w:b/w:bCs appended after
+      // w:color/w:sz by some producers) — Word flags such ordering as corrupt.
+      doc._originalNumberingXml = reorderRunPropertyChildren(numberingXml);
     }
 
     // Preserve original settings.xml and parse managed settings into in-memory state
@@ -907,6 +983,15 @@ export class Document {
       doc._originalAppPropsXml = appPropsXml;
     }
 
+    // Preserve original core.xml for round-trip fidelity. parseProperties only
+    // extracts a fixed subset of OPC core properties; optional elements like
+    // cp:lastPrinted, dc:identifier, and cp:version would otherwise be dropped
+    // on a plain load→save round-trip.
+    const corePropsXml = zipHandler.getFileAsString(DOCX_PATHS.CORE_PROPS);
+    if (corePropsXml) {
+      doc._originalCorePropsXml = corePropsXml;
+    }
+
     // Preserve original webSettings.xml for round-trip fidelity (w:divs, flags, etc.)
     const webSettingsXml = zipHandler.getFileAsString(DOCX_PATHS.WEB_SETTINGS);
     if (webSettingsXml) {
@@ -1306,18 +1391,20 @@ export class Document {
 
       // Register headers with HeaderFooterManager (deduplicate by rId)
       // Multiple section property types may reference the same rId
+      // The parsed filename (relationship target) is preserved so saveHeaders()
+      // writes content back to the part the relationship actually points at
       const registeredHeaderRIds = new Set<string>();
-      for (const { header, relationshipId } of headersFooters.headers) {
+      for (const { header, relationshipId, filename } of headersFooters.headers) {
         if (registeredHeaderRIds.has(relationshipId)) continue;
-        this.headerFooterManager.registerHeader(header, relationshipId);
+        this.headerFooterManager.registerHeader(header, relationshipId, filename);
         registeredHeaderRIds.add(relationshipId);
       }
 
       // Register footers with HeaderFooterManager (deduplicate by rId)
       const registeredFooterRIds = new Set<string>();
-      for (const { footer, relationshipId } of headersFooters.footers) {
+      for (const { footer, relationshipId, filename } of headersFooters.footers) {
         if (registeredFooterRIds.has(relationshipId)) continue;
-        this.headerFooterManager.registerFooter(footer, relationshipId);
+        this.headerFooterManager.registerFooter(footer, relationshipId, filename);
         registeredFooterRIds.add(relationshipId);
       }
     } catch (headerFooterError) {
@@ -1413,7 +1500,13 @@ export class Document {
     }
 
     const parser = new DocumentParser();
-    const comments = parser.parseCommentsXml(commentsXml);
+    // commentsExtended.xml carries the resolved state (w15:done) keyed by
+    // each comment's last-paragraph paraId — CT_Comment itself declares no
+    // done attribute, so isResolved() needs the companion part
+    const comments = parser.parseCommentsXml(
+      commentsXml,
+      this._originalCommentCompanionFiles.get(DOCX_PATHS.COMMENTS_EXTENDED)
+    );
 
     // Register each comment with its existing ID
     for (const comment of comments) {
@@ -1435,7 +1528,12 @@ export class Document {
 
     try {
       const parser = new DocumentParser();
-      const footnotes = parser.parseFootnotesXml(footnotesXml);
+      // Hyperlink r:id targets live in the part-scoped rels file per OPC;
+      // resolving them at parse time lets a real footnote edit regenerate
+      // working links instead of dangling r:id references
+      const relsXml = this.zipHandler.getFileAsString('word/_rels/footnotes.xml.rels');
+      const partRels = relsXml ? RelationshipManager.fromXml(relsXml) : undefined;
+      const footnotes = parser.parseFootnotesXml(footnotesXml, partRels);
 
       for (const footnote of footnotes) {
         const id = footnote.getId();
@@ -1461,7 +1559,9 @@ export class Document {
 
     try {
       const parser = new DocumentParser();
-      const endnotes = parser.parseEndnotesXml(endnotesXml);
+      const relsXml = this.zipHandler.getFileAsString('word/_rels/endnotes.xml.rels');
+      const partRels = relsXml ? RelationshipManager.fromXml(relsXml) : undefined;
+      const endnotes = parser.parseEndnotesXml(endnotesXml, partRels);
 
       for (const endnote of endnotes) {
         const id = endnote.getId();
@@ -1647,12 +1747,18 @@ export class Document {
     // When tracking enabled, bind context and wrap existing content in w:ins revisions
     if (this.trackChangesEnabled && this.trackingContext.isEnabled()) {
       this.bindTrackingToElement(paragraph);
-      const runs = paragraph.getRuns();
-      if (runs.length > 0) {
-        const author = this.trackingContext.getAuthor();
-        const insertion = Revision.createInsertion(author, runs);
-        this.trackingContext.getRevisionManager().register(insertion);
-        paragraph.addRevision(insertion);
+      const author = this.trackingContext.getAuthor();
+      // Each top-level Run/Hyperlink is REPLACED by its insert revision in
+      // place. Wrapping paragraph.getRuns() and appending the revision would
+      // leave the originals live alongside the w:ins copy (text serialized
+      // twice, unremovable by accept/reject) and would re-wrap runs already
+      // inside existing revisions or hyperlinks.
+      for (const item of paragraph.getContent()) {
+        if (item instanceof Run || item instanceof Hyperlink) {
+          const insertion = Revision.createInsertion(author, item);
+          this.trackingContext.getRevisionManager().register(insertion);
+          paragraph.replaceContent(item, [insertion]);
+        }
       }
     }
 
@@ -2307,6 +2413,7 @@ export class Document {
    */
   setTitle(title: string): this {
     this.properties.title = title;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2317,6 +2424,7 @@ export class Document {
    */
   setSubject(subject: string): this {
     this.properties.subject = subject;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2327,6 +2435,7 @@ export class Document {
    */
   setCreator(creator: string): this {
     this.properties.creator = creator;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2351,6 +2460,7 @@ export class Document {
    */
   setKeywords(keywords: string): this {
     this.properties.keywords = keywords;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2361,6 +2471,7 @@ export class Document {
    */
   setDescription(description: string): this {
     this.properties.description = description;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2371,6 +2482,7 @@ export class Document {
    */
   setCategory(category: string): this {
     this.properties.category = category;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2381,6 +2493,7 @@ export class Document {
    */
   setContentStatus(status: string): this {
     this.properties.contentStatus = status;
+    this._corePropsModified = true;
     return this;
   }
 
@@ -2845,7 +2958,7 @@ export class Document {
    * console.log(doc.toPlainText());
    * ```
    */
-  static async loadFromBase64(base64: string, options?: DocumentOptions): Promise<Document> {
+  static async loadFromBase64(base64: string, options?: DocumentLoadOptions): Promise<Document> {
     const buffer = Buffer.from(base64, 'base64');
     return Document.loadFromBuffer(buffer, options);
   }
@@ -3327,6 +3440,7 @@ export class Document {
 
   /**
    * Updates the core properties with current values
+   * Uses preservation strategy to maintain original metadata when unmodified
    */
   private updateCoreProps(): void {
     if (
@@ -3334,8 +3448,65 @@ export class Document {
       this._removedParts.has('docProps/core.xml')
     )
       return;
-    const xml = this.generator.generateCoreProps(this.properties);
-    this.zipHandler.updateFile(DOCX_PATHS.CORE_PROPS, xml);
+    if (this._originalCorePropsXml && !this._corePropsModified) {
+      // Preserve original as-is — no changes to core properties. Keeps
+      // unparsed elements (cp:lastPrinted, dc:identifier, cp:version) intact.
+      return;
+    }
+    if (this._originalCorePropsXml && this._corePropsModified) {
+      // Merge: update only changed fields in original XML
+      const mergedXml = this.mergeCorePropsWithOriginal();
+      this.zipHandler.updateFile(DOCX_PATHS.CORE_PROPS, mergedXml);
+    } else {
+      // New document — generate from scratch
+      const xml = this.generator.generateCoreProps(this.properties);
+      this.zipHandler.updateFile(DOCX_PATHS.CORE_PROPS, xml);
+    }
+  }
+
+  /**
+   * Merges modified core properties with the original core.xml.
+   * Updates only fields that have been programmatically changed, preserving
+   * unparsed OPC core properties (cp:lastPrinted, dc:identifier, cp:version,
+   * dcterms:created/modified, etc.) that the parser never extracts.
+   */
+  private mergeCorePropsWithOriginal(): string {
+    if (!this._originalCorePropsXml) {
+      return this.generator.generateCoreProps(this.properties);
+    }
+
+    let xml = this._originalCorePropsXml;
+
+    // Each parsed core property maps to a single OOXML element. Replace the
+    // existing element's text in place; if the element is absent, insert it
+    // before the closing tag so the new value is not silently dropped.
+    const mergeField = (tag: string, value: string | undefined): void => {
+      if (value === undefined) return;
+      const escaped = XMLBuilder.sanitizeXmlContent(value);
+      const openClose = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?</${tag}>`);
+      const selfClosing = new RegExp(`<${tag}\\b[^>]*/>`);
+      if (openClose.test(xml)) {
+        xml = xml.replace(openClose, `<${tag}>${escaped}</${tag}>`);
+      } else if (selfClosing.test(xml)) {
+        xml = xml.replace(selfClosing, `<${tag}>${escaped}</${tag}>`);
+      } else {
+        xml = xml.replace(
+          /<\/cp:coreProperties>/,
+          `  <${tag}>${escaped}</${tag}>\n</cp:coreProperties>`
+        );
+      }
+    };
+
+    mergeField('dc:title', this.properties.title);
+    mergeField('dc:subject', this.properties.subject);
+    mergeField('dc:creator', this.properties.creator);
+    mergeField('cp:keywords', this.properties.keywords);
+    mergeField('dc:description', this.properties.description);
+    mergeField('cp:category', this.properties.category);
+    mergeField('cp:contentStatus', this.properties.contentStatus);
+    mergeField('dc:language', this.properties.language);
+
+    return xml;
   }
 
   /**
@@ -3379,6 +3550,9 @@ export class Document {
         xml = xml.replace(/<Company>[^<]*<\/Company>/, `<Company>${escaped}</Company>`);
       } else if (xml.includes('<Company/>')) {
         xml = xml.replace(/<Company\/>/, `<Company>${escaped}</Company>`);
+      } else {
+        // Tag fully absent: insert so the value is not silently dropped on save
+        xml = xml.replace(/<\/Properties>/, `  <Company>${escaped}</Company>\n</Properties>`);
       }
     }
 
@@ -3390,6 +3564,12 @@ export class Document {
           /<Application>[^<]*<\/Application>/,
           `<Application>${escaped}</Application>`
         );
+      } else {
+        // Tag fully absent: insert so the value is not silently dropped on save
+        xml = xml.replace(
+          /<\/Properties>/,
+          `  <Application>${escaped}</Application>\n</Properties>`
+        );
       }
     }
 
@@ -3398,6 +3578,9 @@ export class Document {
       const escaped = XMLBuilder.sanitizeXmlContent(this.properties.appVersion);
       if (xml.includes('<AppVersion>')) {
         xml = xml.replace(/<AppVersion>[^<]*<\/AppVersion>/, `<AppVersion>${escaped}</AppVersion>`);
+      } else {
+        // Tag fully absent: insert so the value is not silently dropped on save
+        xml = xml.replace(/<\/Properties>/, `  <AppVersion>${escaped}</AppVersion>\n</Properties>`);
       }
     }
 
@@ -3406,6 +3589,9 @@ export class Document {
       const escaped = XMLBuilder.sanitizeXmlContent(this.properties.manager);
       if (xml.includes('<Manager>')) {
         xml = xml.replace(/<Manager>[^<]*<\/Manager>/, `<Manager>${escaped}</Manager>`);
+      } else {
+        // Tag fully absent: insert so the value is not silently dropped on save
+        xml = xml.replace(/<\/Properties>/, `  <Manager>${escaped}</Manager>\n</Properties>`);
       }
     }
 
@@ -3592,9 +3778,10 @@ export class Document {
    * Merges modified styles with the original styles.xml
    *
    * This preserves all styles from the original document while only updating
-   * styles that have been explicitly modified via addStyle().
+   * styles that have been explicitly modified via addStyle() and stripping
+   * styles that have been removed via removeStyle().
    *
-   * @returns Merged XML string with original styles + modified styles
+   * @returns Merged XML string with original styles + modified styles - removed styles
    * @private
    */
   private mergeStylesWithOriginal(): string {
@@ -3603,9 +3790,10 @@ export class Document {
     }
 
     const modifiedStyleIds = this.stylesManager.getModifiedStyleIds();
+    const removedStyleIds = this.stylesManager.getRemovedStyleIds();
 
-    // If nothing was modified, return original as-is
-    if (modifiedStyleIds.size === 0) {
+    // If nothing was modified or removed, return original as-is
+    if (modifiedStyleIds.size === 0 && removedStyleIds.size === 0) {
       return this._originalStylesXml;
     }
 
@@ -3646,6 +3834,16 @@ export class Document {
       }
     }
 
+    // Strip removed style definitions — without this, removals never reach
+    // the saved styles.xml (mirrors the numbering merge's removed-ID handling)
+    for (const styleId of removedStyleIds) {
+      const escapedStyleId = styleId.replace(/[.*+?^${}()|[\]\\"]/g, '\\$&');
+      const removedPattern = new RegExp(
+        `\\s*<w:style[^>]*\\sw:styleId="${escapedStyleId}"[^>]*>[\\s\\S]*?</w:style>`
+      );
+      resultXml = resultXml.replace(removedPattern, '');
+    }
+
     return resultXml;
   }
 
@@ -4003,9 +4201,22 @@ export class Document {
 
     // w:revisionView (#31 in CT_Settings)
     const view = this.revisionViewSettings;
-    // Only emit revisionView if it differs from defaults (all true)
-    if (!view.showInsertionsAndDeletions || !view.showFormatting || !view.showInkAnnotations) {
-      trackBlock += `\n  <w:revisionView w:insDel="${view.showInsertionsAndDeletions ? '1' : '0'}" w:formatting="${view.showFormatting ? '1' : '0'}" w:inkAnnotations="${view.showInkAnnotations ? '1' : '0'}"/>`;
+    // Only emit revisionView if it differs from defaults (all true). showMarkup
+    // and showComments default true when absent, so a parsed w:markup="0" /
+    // w:comments="0" must also trigger emission or it would be dropped here.
+    if (
+      !view.showInsertionsAndDeletions ||
+      !view.showFormatting ||
+      !view.showInkAnnotations ||
+      view.showMarkup === false ||
+      view.showComments === false
+    ) {
+      // CT_TrackChangesView §17.15.1.77: append w:markup / w:comments only when
+      // explicitly false (absent = default true) so the reviewer's default
+      // markup view survives round-trip, mirroring DocumentGenerator.
+      const markupAttr = view.showMarkup === false ? ' w:markup="0"' : '';
+      const commentsAttr = view.showComments === false ? ' w:comments="0"' : '';
+      trackBlock += `\n  <w:revisionView w:insDel="${view.showInsertionsAndDeletions ? '1' : '0'}" w:formatting="${view.showFormatting ? '1' : '0'}" w:inkAnnotations="${view.showInkAnnotations ? '1' : '0'}"${markupAttr}${commentsAttr}/>`;
     }
 
     // w:trackRevisions (#32)
@@ -4062,6 +4273,8 @@ export class Document {
     const prot = this.documentProtection;
     const esc = XMLBuilder.escapeXmlAttribute;
     let protXml = `\n  <w:documentProtection w:edit="${esc(prot.edit)}" w:enforcement="${prot.enforcement ? '1' : '0'}"`;
+    // w:formatting (CT_DocProtect §17.15.1.29) — tri-state, emit explicit 0/1
+    if (prot.formatting !== undefined) protXml += ` w:formatting="${prot.formatting ? '1' : '0'}"`;
     if (prot.cryptProviderType) protXml += ` w:cryptProviderType="${esc(prot.cryptProviderType)}"`;
     if (prot.cryptAlgorithmClass)
       protXml += ` w:cryptAlgorithmClass="${esc(prot.cryptAlgorithmClass)}"`;
@@ -4072,6 +4285,12 @@ export class Document {
     if (prot.cryptSpinCount) protXml += ` w:cryptSpinCount="${esc(String(prot.cryptSpinCount))}"`;
     if (prot.hash) protXml += ` w:hash="${esc(prot.hash)}"`;
     if (prot.salt) protXml += ` w:salt="${esc(prot.salt)}"`;
+    // Modern Word 2013+ crypto attributes (ISO/IEC 29500-4 §13) — without
+    // these a modern password-protected document loses its password material
+    // whenever any settings-modifying API runs before save.
+    if (prot.algorithmName) protXml += ` w:algorithmName="${esc(prot.algorithmName)}"`;
+    if (prot.hashValue) protXml += ` w:hashValue="${esc(prot.hashValue)}"`;
+    if (prot.saltValue) protXml += ` w:saltValue="${esc(prot.saltValue)}"`;
     protXml += '/>';
 
     // Insert before w:autoFormatOverride (#36) if exists,
@@ -5597,7 +5816,10 @@ export class Document {
    * - numId references inside body-level tracked deletions (w:del blocks
    *   that were skipped during parsing)
    * - Header, footer, footnote, and endnote XML files
-   * - Raw XML safety net scan of all relevant ZIP entries
+   * - Style definitions (w:numPr in a style's pPr), since styles attach
+   *   list numbering without any paragraph carrying a direct numId
+   * - Raw XML safety net scan of all relevant ZIP entries, including
+   *   styles.xml and comments.xml
    *
    * A definition is only removed if it appears in NONE of these sources.
    *
@@ -5663,6 +5885,25 @@ export class Document {
       }
     }
 
+    // 7. Scan style definitions for numPr references — Word attaches multilevel
+    //    list numbering to paragraph styles (e.g., Headings, list styles), so a
+    //    numId can be in use while no paragraph carries a direct w:numPr
+    for (const style of this.stylesManager.getAllStyles()) {
+      const styleNumId = style.getProperties().numPr?.numId;
+      if (styleNumId !== undefined) {
+        usedNumIds.add(styleNumId);
+      }
+    }
+
+    // 8. Raw safety net for styles.xml and comments.xml — preserved XML can
+    //    carry numId references not represented in the in-memory model
+    for (const filePath of [DOCX_PATHS.STYLES, 'word/comments.xml']) {
+      const xml = this.zipHandler.getFileAsString(filePath);
+      if (xml) {
+        this.collectNumIdsFromXml(xml, usedNumIds);
+      }
+    }
+
     // Clean up numbering definitions not found in any of the above scans
     this.numberingManager.cleanupUnusedNumbering(usedNumIds);
   }
@@ -5868,7 +6109,69 @@ export class Document {
     }
     const registeredSet = new Set(existingRevisions);
 
-    let docPrId = 1;
+    // Preserved raw XML (revision-nested image runs, w:pict/chart passthrough run
+    // content, preserved elements, nested-table passthrough) is emitted verbatim
+    // with its original wp:docPr id, outside the renumbering below. Reassigned ids
+    // must start above every id that survives serialization unchanged, otherwise a
+    // renumbered drawing can duplicate a preserved one (wp:docPr/@id must be
+    // unique per ECMA-376 Part 1 §20.4.2.5).
+    let maxPreservedDocPrId = 0;
+    const collectPreservedDocPrIds = (rawXml: string | undefined): void => {
+      if (!rawXml || !rawXml.includes('wp:docPr')) return;
+      const docPrPattern = /<wp:docPr\b[^>]*\bid="(\d+)"/g;
+      let match: RegExpExecArray | null;
+      while ((match = docPrPattern.exec(rawXml)) !== null) {
+        const id = parseInt(match[1]!, 10);
+        if (id > maxPreservedDocPrId) maxPreservedDocPrId = id;
+      }
+    };
+    const collectFromRun = (run: Run): void => {
+      if (run instanceof ImageRun) {
+        collectPreservedDocPrIds(run.getRawRunXml());
+        return;
+      }
+      for (const contentItem of run.getContent()) {
+        collectPreservedDocPrIds(contentItem.rawXml);
+      }
+    };
+    const collectFromParagraph = (para: Paragraph): void => {
+      for (const item of para.getContent()) {
+        if (item instanceof Revision) {
+          for (const revItem of item.getContent()) {
+            if (revItem instanceof Run) collectFromRun(revItem);
+          }
+        } else if (item instanceof Run) {
+          collectFromRun(item);
+        } else if (item instanceof PreservedElement) {
+          collectPreservedDocPrIds(item.getRawXml());
+        }
+      }
+    };
+    for (const element of this.bodyElements) {
+      if (element instanceof Paragraph) {
+        collectFromParagraph(element);
+      } else if (element instanceof Table) {
+        for (const row of element.getRows()) {
+          for (const cell of row.getCells()) {
+            for (const para of cell.getParagraphs()) {
+              collectFromParagraph(para);
+            }
+            for (const nested of cell.getRawNestedContent()) {
+              collectPreservedDocPrIds(nested.xml);
+            }
+          }
+        }
+      } else {
+        // Raw-XML passthrough body elements (AlternateContent, MathParagraph,
+        // CustomXmlBlock, PreservedElement, registered elements) expose getRawXml().
+        const passthrough = element as { getRawXml?: () => string };
+        if (typeof passthrough.getRawXml === 'function') {
+          collectPreservedDocPrIds(passthrough.getRawXml());
+        }
+      }
+    }
+
+    let docPrId = maxPreservedDocPrId + 1;
 
     // Collect existing paraIds to avoid collisions when generating new ones
     const existingParaIds = new Set<string>();
@@ -5906,6 +6209,16 @@ export class Document {
           item.setDocPrId(docPrId++);
         } else if (item instanceof ImageRun) {
           item.getImageElement().setDocPrId(docPrId++);
+        } else if (item instanceof Revision) {
+          // Revision-nested images serialize from the model when no raw run XML
+          // was captured (programmatic) or after a mutation splices a regenerated
+          // w:drawing — give them fresh ids so they cannot collide with the
+          // renumbered top-level drawings. Unmutated raw runs ignore the model id.
+          for (const revItem of item.getContent()) {
+            if (revItem instanceof ImageRun) {
+              revItem.getImageElement().setDocPrId(docPrId++);
+            }
+          }
         }
       }
 
@@ -6631,6 +6944,10 @@ export class Document {
         numLevel.setHangingIndent(360);
       }
 
+      // Level setters don't propagate dirty state; without this the save
+      // pipeline writes the original numbering.xml verbatim for loaded docs
+      this.numberingManager.markAbstractNumberingModified(abstractNumId);
+
       // Apply paragraph formatting to all paragraphs using this list
       this.applyFormattingToListParagraphs(instance.getNumId());
       count++;
@@ -6697,6 +7014,10 @@ export class Document {
         numLevel.setAlignment('left');
       }
 
+      // Level setters don't propagate dirty state; without this the save
+      // pipeline writes the original numbering.xml verbatim for loaded docs
+      this.numberingManager.markAbstractNumberingModified(abstractNumId);
+
       // Apply paragraph formatting to all paragraphs using this list
       this.applyFormattingToListParagraphs(instance.getNumId());
       count++;
@@ -9778,8 +10099,11 @@ export class Document {
    * @returns This document for chaining
    */
   setHeader(header: Header): this {
-    // Generate relationship for header
-    const relationship = this.relationshipManager.addHeader(`${header.getFilename(1)}`);
+    // The relationship must target the part name the manager assigns,
+    // otherwise saveHeaders() writes content to a part nothing references
+    const relationship = this.relationshipManager.addHeader(
+      this.headerFooterManager.peekHeaderFilename(header)
+    );
 
     // Register with manager
     this.headerFooterManager.registerHeader(header, relationship.getId());
@@ -9799,9 +10123,9 @@ export class Document {
     // Enable title page
     this.section.setTitlePage(true);
 
-    // Generate relationship for header
+    // Target the part name the manager will assign on registration
     const relationship = this.relationshipManager.addHeader(
-      `${header.getFilename(this.headerFooterManager.getHeaderCount() + 1)}`
+      this.headerFooterManager.peekHeaderFilename(header)
     );
 
     // Register with manager
@@ -9819,9 +10143,9 @@ export class Document {
    * @returns This document for chaining
    */
   setEvenPageHeader(header: Header): this {
-    // Generate relationship for header
+    // Target the part name the manager will assign on registration
     const relationship = this.relationshipManager.addHeader(
-      `${header.getFilename(this.headerFooterManager.getHeaderCount() + 1)}`
+      this.headerFooterManager.peekHeaderFilename(header)
     );
 
     // Register with manager
@@ -9839,8 +10163,11 @@ export class Document {
    * @returns This document for chaining
    */
   setFooter(footer: Footer): this {
-    // Generate relationship for footer
-    const relationship = this.relationshipManager.addFooter(`${footer.getFilename(1)}`);
+    // The relationship must target the part name the manager assigns,
+    // otherwise saveFooters() writes content to a part nothing references
+    const relationship = this.relationshipManager.addFooter(
+      this.headerFooterManager.peekFooterFilename(footer)
+    );
 
     // Register with manager
     this.headerFooterManager.registerFooter(footer, relationship.getId());
@@ -9860,9 +10187,9 @@ export class Document {
     // Enable title page
     this.section.setTitlePage(true);
 
-    // Generate relationship for footer
+    // Target the part name the manager will assign on registration
     const relationship = this.relationshipManager.addFooter(
-      `${footer.getFilename(this.headerFooterManager.getFooterCount() + 1)}`
+      this.headerFooterManager.peekFooterFilename(footer)
     );
 
     // Register with manager
@@ -9880,9 +10207,9 @@ export class Document {
    * @returns This document for chaining
    */
   setEvenPageFooter(footer: Footer): this {
-    // Generate relationship for footer
+    // Target the part name the manager will assign on registration
     const relationship = this.relationshipManager.addFooter(
-      `${footer.getFilename(this.headerFooterManager.getFooterCount() + 1)}`
+      this.headerFooterManager.peekFooterFilename(footer)
     );
 
     // Register with manager
@@ -10188,6 +10515,26 @@ export class Document {
       }
       // Remove companion files since regenerated comments lack w14:paraId
       this.removeCommentCompanionFiles();
+
+      // Resolved state lives in commentsExtended.xml (w15:commentEx
+      // w15:done) — CT_Comment declares no done attribute, so the part is
+      // regenerated alongside comments.xml whenever a comment is resolved
+      const extendedXml = this.commentManager.generateCommentsExtendedXml();
+      if (extendedXml) {
+        this.zipHandler.addFile(DOCX_PATHS.COMMENTS_EXTENDED, extendedXml);
+        const hasExtendedRel = this.relationshipManager
+          .getAllRelationships()
+          .some((rel) => rel.getTarget() === 'commentsExtended.xml');
+        if (!hasExtendedRel) {
+          this.relationshipManager.addRelationship(
+            Relationship.create({
+              id: this.relationshipManager.generateId(),
+              type: 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended',
+              target: 'commentsExtended.xml',
+            })
+          );
+        }
+      }
     } else if (this._originalCommentsXml) {
       // Passthrough — preserve original comments.xml exactly
       this.zipHandler.addFile('word/comments.xml', this._originalCommentsXml);
@@ -10236,7 +10583,14 @@ export class Document {
   }
 
   private saveFootnotes(): void {
-    if (this._footnotesModified || this.footnoteManager.getCount() > 0) {
+    // Dirty flag gates regeneration (mirrors saveComments) so an unmodified
+    // loaded footnotes.xml round-trips via passthrough; the count check only
+    // covers footnotes registered directly on the manager for documents that
+    // never had a footnotes part.
+    if (
+      this._footnotesModified ||
+      (!this._originalFootnotesXml && this.footnoteManager.getCount() > 0)
+    ) {
       const xml = this.footnoteManager.generateFootnotesXml();
       this.zipHandler.addFile(DOCX_PATHS.FOOTNOTES, xml);
 
@@ -10267,7 +10621,11 @@ export class Document {
   }
 
   private saveEndnotes(): void {
-    if (this._endnotesModified || this.endnoteManager.getCount() > 0) {
+    // Same passthrough gating as saveFootnotes
+    if (
+      this._endnotesModified ||
+      (!this._originalEndnotesXml && this.endnoteManager.getCount() > 0)
+    ) {
       const xml = this.endnoteManager.generateEndnotesXml();
       this.zipHandler.addFile(DOCX_PATHS.ENDNOTES, xml);
 
@@ -10364,10 +10722,21 @@ export class Document {
 
       this.zipHandler.addFile(relsPath, xml);
 
-      // Remove these relationships from the main RelationshipManager
-      // so they don't appear in document.xml.rels
+      // Remove these relationships from the main RelationshipManager so they
+      // don't appear in document.xml.rels. Per OPC, relationship IDs are
+      // part-scoped: a loaded header/footnote hyperlink keeps an ID from its
+      // own .rels file that may collide with an unrelated document.xml.rels
+      // entry (styles, settings, an image). Only remove when the main entry
+      // is genuinely the same hyperlink (type and target match).
       for (const rel of hyperlinkRels) {
-        this.relationshipManager.removeRelationship(rel.id);
+        const mainRel = this.relationshipManager.getRelationship(rel.id);
+        if (
+          mainRel &&
+          mainRel.getType() === RelationshipType.HYPERLINK &&
+          mainRel.getTarget() === rel.url
+        ) {
+          this.relationshipManager.removeRelationship(rel.id);
+        }
       }
     }
   }
@@ -10531,20 +10900,32 @@ export class Document {
     const defaults = new Set<string>();
     const overrides = new Set<string>();
 
-    // Extract all <Default Extension="..." ContentType="..."/> entries
-    const defaultMatches = xml.matchAll(
-      /<Default\s+Extension="([^"]+)"\s+ContentType="([^"]+)"\s*\/>/g
-    );
-    for (const match of defaultMatches) {
-      defaults.add(`${match[1]}|${match[2]}`); // Store as "ext|mimetype"
+    // Per XML 1.0, attribute order is insignificant, values may use single or
+    // double quotes, and empty elements may be expanded (<Override ...></Override>).
+    // Match each opening tag and pull attributes out individually so spec-valid
+    // packages from non-Word producers keep their entries on save (the generator
+    // regenerates [Content_Types].xml; unmatched entries would be silently lost).
+    const readAttr = (tag: string, name: string): string | undefined => {
+      const match = tag.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*("([^"]*)"|'([^']*)')`));
+      if (!match) return undefined;
+      // Unescape so re-serialization (which escapes) doesn't double-escape
+      return XMLBuilder.unescapeXml(match[2] ?? match[3] ?? '');
+    };
+
+    for (const tagMatch of xml.matchAll(/<Default\b[^>]*>/g)) {
+      const ext = readAttr(tagMatch[0], 'Extension');
+      const contentType = readAttr(tagMatch[0], 'ContentType');
+      if (ext && contentType) {
+        defaults.add(`${ext}|${contentType}`); // Store as "ext|mimetype"
+      }
     }
 
-    // Extract all <Override PartName="..." ContentType="..."/> entries
-    const overrideMatches = xml.matchAll(
-      /<Override\s+PartName="([^"]+)"\s+ContentType="([^"]+)"\s*\/>/g
-    );
-    for (const match of overrideMatches) {
-      overrides.add(`${match[1]}|${match[2]}`); // Store as "path|mimetype"
+    for (const tagMatch of xml.matchAll(/<Override\b[^>]*>/g)) {
+      const partName = readAttr(tagMatch[0], 'PartName');
+      const contentType = readAttr(tagMatch[0], 'ContentType');
+      if (partName && contentType) {
+        overrides.add(`${partName}|${contentType}`); // Store as "path|mimetype"
+      }
     }
 
     return { defaults, overrides };
@@ -11509,6 +11890,12 @@ export class Document {
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private bindTrackingToElement(element: any): void {
+    // Two-arm coverage: the getContent() arm below binds any paragraph-content
+    // item exposing _setTrackingContext (Hyperlink, ComplexField, etc.) so their
+    // own setText() emits tracked markup; the getRuns() arm binds the inner Runs
+    // that actually carry the text. Both arms are required — neither subsumes the
+    // other — to fully wire a paragraph's tracking context.
+
     // Set tracking context on element if it supports it
     if (element && typeof element._setTrackingContext === 'function') {
       element._setTrackingContext(this.trackingContext);
@@ -11528,14 +11915,13 @@ export class Document {
       }
     }
 
-    // Bind to ComplexField instances in paragraph content
+    // Bind to content items that accept a tracking context (Hyperlink,
+    // ComplexField, etc.). Hyperlink.setText() consults its own
+    // trackingContext, so it must be bound here too; re-binding the inner
+    // Runs handled above is idempotent.
     if (element && typeof element.getContent === 'function') {
       for (const item of element.getContent()) {
-        if (
-          item &&
-          typeof item._setTrackingContext === 'function' &&
-          typeof item.getInstruction === 'function'
-        ) {
+        if (item && typeof item._setTrackingContext === 'function') {
           item._setTrackingContext(this.trackingContext);
         }
       }
@@ -11876,6 +12262,10 @@ export class Document {
       updated.size = sizeInPoints;
     }
     normalStyle.setRunFormatting(updated);
+    // Re-register so the style lands in _modifiedStyleIds — otherwise
+    // mergeStylesWithOriginal() returns the original styles.xml verbatim
+    // for loaded documents and the change is silently dropped
+    this.stylesManager.addStyle(normalStyle);
     return this;
   }
 
@@ -11904,6 +12294,10 @@ export class Document {
 
     const existing = normalStyle.getRunFormatting() ?? {};
     normalStyle.setRunFormatting({ ...existing, size: sizeInPoints });
+    // Re-register so the style lands in _modifiedStyleIds — otherwise
+    // mergeStylesWithOriginal() returns the original styles.xml verbatim
+    // for loaded documents and the change is silently dropped
+    this.stylesManager.addStyle(normalStyle);
     return this;
   }
 
@@ -12438,6 +12832,70 @@ export class Document {
     this._endnotesModified = true;
   }
 
+  /**
+   * Removes a footnote definition and every w:footnoteReference run pointing
+   * at it in the body. Per ECMA-376 §17.11.14 each reference must resolve to
+   * a footnote definition, so the references are stripped together with the
+   * definition; the dirty flag ensures footnotes.xml is regenerated instead
+   * of being restored from the original passthrough XML.
+   * @param id - Footnote ID
+   * @returns True if removed, false if not found or a special separator type
+   */
+  removeFootnote(id: number): boolean {
+    const removed = this.footnoteManager.removeFootnote(id);
+    if (removed) {
+      this._footnotesModified = true;
+      this.removeNoteReferenceRuns('footnoteReference', id);
+    }
+    return removed;
+  }
+
+  /**
+   * Removes an endnote definition and every w:endnoteReference run pointing
+   * at it in the body. Same reference-consistency contract as
+   * {@link removeFootnote} (ECMA-376 §17.11.3).
+   * @param id - Endnote ID
+   * @returns True if removed, false if not found or a special separator type
+   */
+  removeEndnote(id: number): boolean {
+    const removed = this.endnoteManager.removeEndnote(id);
+    if (removed) {
+      this._endnotesModified = true;
+      this.removeNoteReferenceRuns('endnoteReference', id);
+    }
+    return removed;
+  }
+
+  /**
+   * Strips body runs containing a footnote/endnote reference to the given
+   * note ID so the saved document.xml never references a deleted definition.
+   */
+  private removeNoteReferenceRuns(
+    refType: 'footnoteReference' | 'endnoteReference',
+    id: number
+  ): void {
+    for (const para of this.getAllParagraphs()) {
+      const content = para.getContent();
+      // Iterate backwards so removals don't shift pending indices
+      for (let i = content.length - 1; i >= 0; i--) {
+        const item = content[i];
+        if (!(item instanceof Run)) {
+          continue;
+        }
+        const matches = item
+          .getContent()
+          .some(
+            (c) =>
+              c.type === refType &&
+              (refType === 'footnoteReference' ? c.footnoteId === id : c.endnoteId === id)
+          );
+        if (matches) {
+          para.removeContentAt(i);
+        }
+      }
+    }
+  }
+
   /**
    * Adds a comment to a paragraph (wraps the entire paragraph)
    * Creates the comment if text is provided, or uses an existing comment object
@@ -12594,13 +13052,70 @@ export class Document {
    * @returns True if the comment was removed
    */
   removeComment(id: number): boolean {
+    // Capture reply IDs before removal — CommentManager.removeComment deletes
+    // them too, and their body anchors must be scrubbed along with the parent's
+    const replyIds = this.commentManager.getReplies(id).map((reply) => reply.getId());
     const removed = this.commentManager.removeComment(id);
     if (removed) {
+      this.removeCommentAnchors([id, ...replyIds]);
       this._commentsModified = true;
     }
     return removed;
   }
 
+  /**
+   * Strips comment anchors (range markers and reference runs) for the given
+   * comment IDs from every paragraph in the body, headers, footers, footnotes,
+   * and endnotes. Without this, deleting a comment definition leaves
+   * w:commentRangeStart/End and w:commentReference pointing at a comment that
+   * no longer exists in comments.xml — Word reports such documents as
+   * containing unreadable content.
+   */
+  private removeCommentAnchors(commentIds: number[]): void {
+    const strip = (paragraphs: Paragraph[]): boolean => {
+      let removed = false;
+      for (const paragraph of paragraphs) {
+        for (const commentId of commentIds) {
+          if (paragraph.removeCommentAnchor(commentId)) {
+            removed = true;
+          }
+        }
+      }
+      return removed;
+    };
+
+    strip(this.getAllParagraphs());
+
+    for (const entry of this.headerFooterManager.getAllHeaders()) {
+      strip(this.extractParagraphsFromElements(entry.header.getElements()));
+    }
+    for (const entry of this.headerFooterManager.getAllFooters()) {
+      strip(this.extractParagraphsFromElements(entry.footer.getElements()));
+    }
+
+    // Footnote/endnote parts are raw-XML passthrough unless flagged modified,
+    // so anchor removal must mark them dirty to take effect on save
+    let footnotesChanged = false;
+    for (const footnote of this.footnoteManager.getAllFootnotes()) {
+      if (strip(footnote.getParagraphs())) {
+        footnotesChanged = true;
+      }
+    }
+    if (footnotesChanged) {
+      this._footnotesModified = true;
+    }
+
+    let endnotesChanged = false;
+    for (const endnote of this.endnoteManager.getAllEndnotes()) {
+      if (strip(endnote.getParagraphs())) {
+        endnotesChanged = true;
+      }
+    }
+    if (endnotesChanged) {
+      this._endnotesModified = true;
+    }
+  }
+
   /**
    * Checks if there are any revisions in the document
    * @returns True if there are no revisions
@@ -13342,8 +13857,10 @@ export class Document {
     // Clear all managers using their clear() methods
     this.stylesManager.clear();
     this.numberingManager.clear();
-    this.imageManager.clear();
+    // Release buffers before clear() empties the images map; the reverse order
+    // would leave releaseAllImageData() iterating zero entries.
     this.imageManager.releaseAllImageData();
+    this.imageManager.clear();
     this.relationshipManager.clear();
     this.headerFooterManager.clear();
     this.bookmarkManager.clear();
@@ -13364,6 +13881,7 @@ export class Document {
     this._originalNumberingXml = undefined;
     this._originalSettingsXml = undefined;
     this._originalAppPropsXml = undefined;
+    this._originalCorePropsXml = undefined;
     this._originalFootnotesXml = undefined;
     this._originalEndnotesXml = undefined;
     this._originalCommentsXml = undefined;
@@ -13372,6 +13890,7 @@ export class Document {
     this._originalContentTypes = undefined;
     this._settingsModified = false;
     this._appPropsModified = false;
+    this._corePropsModified = false;
     this._footnotesModified = false;
     this._endnotesModified = false;
     this._originalWebSettingsXml = undefined;
@@ -14614,7 +15133,9 @@ export class Document {
           const matches = originalText.match(wordPattern);
           if (matches) {
             replacementCount += matches.length;
-            newText = originalText.replace(wordPattern, replace);
+            // Replacer function inserts `replace` literally; passing the raw
+            // string would expand $-substitution tokens ($&, $', $`, $$).
+            newText = originalText.replace(wordPattern, () => replace);
           }
         } else {
           // Simple substring replacement
@@ -14625,7 +15146,9 @@ export class Document {
           const matches = originalText.match(searchPattern);
           if (matches) {
             replacementCount += matches.length;
-            newText = originalText.replace(searchPattern, replace);
+            // Replacer function inserts `replace` literally; passing the raw
+            // string would expand $-substitution tokens ($&, $', $`, $$).
+            newText = originalText.replace(searchPattern, () => replace);
           }
         }
 
@@ -15253,6 +15776,13 @@ export class Document {
    * @param separator - String to insert between paragraphs (default: '\n')
    * @returns Plain text content of the entire document
    *
+   * @remarks
+   * The output depends on the `revisionHandling` mode the document was loaded with, and reflects any tracked changes applied to the document after loading.
+   * In `'preserve'` mode the result now includes BOTH tracked-inserted (`w:ins`) and
+   * tracked-deleted (`w:delText`) text, interleaved in document order. In
+   * `'accept'`/`'strip'` modes (the default) the output is the post-acceptance plain
+   * text — inserted content kept, deleted content dropped.
+   *
    * @example
    * ```typescript
    * const text = doc.toPlainText();
@@ -15264,23 +15794,37 @@ export class Document {
    */
   toPlainText(separator = '\n'): string {
     const paragraphs = this.getAllParagraphs();
-    return paragraphs.map((p) => p.getText()).join(separator);
+    // Use the revision-aware path so preserve-mode documents retain the text
+    // carried by tracked changes (inserted w:t and deleted w:delText) instead
+    // of silently dropping it.
+    return paragraphs.map((p) => p.getTextIncludingRevisions()).join(separator);
   }
 
   /**
    * Converts the document to Markdown format
    *
-   * Iterates body elements in order and converts them to Markdown syntax:
-   * - Headings → `#` / `##` / `###` etc.
-   * - Bold/italic runs → `**bold**` / `*italic*`
-   * - Hyperlinks → `[text](url)`
-   * - Tables → pipe-delimited Markdown tables with alignment row
-   * - Numbered/bulleted lists → `1.` / `-` prefixes
-   * - Regular paragraphs → plain text with blank lines between
-   *
-   * Useful for AI/LLM pipelines, content migration, documentation
+   * Walks the body in order and renders every information-bearing construct,
+   * falling back to inline HTML where Markdown has no native equivalent so
+   * that no content is silently dropped:
+   * - Headings → `#` … `######`
+   * - Bold/italic/strikethrough → `**` / `*` / `~~`; monospace fonts → `` `code` ``
+   * - Underline/super/subscript/highlight/color → inline HTML (`<u>`, `<sup>`,
+   *   `<sub>`, `<mark>`, `<span style="color:#…">`) when {@link MarkdownConversionOptions.htmlFallback}
+   * - Hyperlinks → `[text](url)` (internal links resolve to `#anchor`)
+   * - Inline images → `![alt](src)`
+   * - Footnote/endnote references → `[^fn1]` / `[^en1]` with definitions appended
+   * - Line breaks → `<br>` (or newline), tabs preserved
+   * - Numbered/bulleted lists → `1.` / `-` with two-space indentation per nesting level
+   * - Block quotes (Quote styles) → `>` prefixes
+   * - Tables → GFM pipe tables; tables with merged or nested cells → inline HTML
+   * - Field results, shapes, text boxes, structured document tags and preserved
+   *   elements → their textual content
+   * - Tracked insertions (preserve mode) render inline; deletions wrap in `~~`/`<del>`
+   *
+   * Useful for document processing pipelines, content migration, documentation
    * generation, and plain-text extraction with structure preserved.
    *
+   * @param options - Conversion fidelity options (see {@link MarkdownConversionOptions})
    * @returns Markdown string representation of the document
    *
    * @example
@@ -15298,139 +15842,495 @@ export class Document {
    * // | Alice | 30 |
    * ```
    */
-  toMarkdown(): string {
-    const lines: string[] = [];
+  toMarkdown(options?: MarkdownConversionOptions): string {
+    const ctx: MarkdownContext = {
+      opts: {
+        htmlFallback: options?.htmlFallback ?? true,
+        footnotes: options?.footnotes ?? true,
+        images: options?.images ?? true,
+      },
+      notes: [],
+      noteMarkers: new Set<string>(),
+    };
 
+    const lines: string[] = [];
     for (const element of this.bodyElements) {
-      if (element instanceof Paragraph) {
-        const mdLine = this.paragraphToMarkdown(element);
-        if (mdLine !== null) {
-          lines.push(mdLine);
-          lines.push('');
-        }
-      } else if (element instanceof Table) {
-        lines.push(...this.tableToMarkdown(element));
-        lines.push('');
-      }
-      // Other element types (SDT, AlternateContent, etc.) are skipped
+      this.bodyElementToMarkdown(element, ctx, lines);
     }
 
-    // Remove trailing blank line
+    // Remove trailing blank line(s)
     while (lines.length > 0 && lines[lines.length - 1] === '') {
       lines.pop();
     }
 
-    return lines.join('\n');
+    let out = lines.join('\n');
+
+    // Append footnote/endnote definitions in first-reference order.
+    if (ctx.opts.footnotes && ctx.notes.length > 0) {
+      const defs = ctx.notes.map((n) => `[^${n.marker}]: ${n.text}`).join('\n');
+      out = out ? `${out}\n\n${defs}` : defs;
+    }
+
+    return out;
+  }
+
+  /**
+   * Renders a single body element into the running Markdown line buffer.
+   * Recurses into block-level structured document tags.
+   * @internal
+   */
+  private bodyElementToMarkdown(element: BodyElement, ctx: MarkdownContext, lines: string[]): void {
+    if (element instanceof Paragraph) {
+      const md = this.paragraphToMarkdown(element, ctx);
+      if (md !== null) {
+        lines.push(md);
+        lines.push('');
+      }
+    } else if (element instanceof Table) {
+      const tableLines = this.tableToMarkdown(element, ctx);
+      if (tableLines.length > 0) {
+        lines.push(...tableLines);
+        lines.push('');
+      }
+    } else if (element instanceof StructuredDocumentTag) {
+      // Block SDT: render its inner content (paragraphs/tables/nested SDTs).
+      for (const child of element.getContent()) {
+        this.bodyElementToMarkdown(child, ctx, lines);
+      }
+    } else if (element instanceof PreservedElement) {
+      // Best-effort: surface any text so round-trip-preserved blocks are not lost.
+      const text = this.extractTextFromRawXml(element.getRawXml());
+      if (text) {
+        lines.push(this.escapeMarkdown(text));
+        lines.push('');
+      }
+    }
+    // TableOfContentsElement is intentionally skipped: its content is generated
+    // from the headings, which are already represented in the Markdown output.
   }
 
   /**
-   * Converts a paragraph to a Markdown line.
+   * Converts a paragraph to a Markdown block (heading, list item, block quote,
+   * or plain paragraph). Returns null for empty, non-list paragraphs.
    * @internal
    */
-  private paragraphToMarkdown(para: Paragraph): string | null {
-    const text = this.paragraphContentToMarkdown(para);
-    if (!text && !para.hasNumbering()) return null;
+  private paragraphToMarkdown(para: Paragraph, ctx: MarkdownContext): string | null {
+    const inline = this.paragraphContentToMarkdown(para, ctx);
+    const hasNumbering = para.hasNumbering();
+    if (!inline && !hasNumbering) return null;
 
-    // Headings
+    // Headings take precedence over every other block style.
     const headingLevel = para.detectHeadingLevel();
     if (headingLevel !== null && headingLevel >= 1 && headingLevel <= 6) {
-      return '#'.repeat(headingLevel) + ' ' + text;
+      return '#'.repeat(headingLevel) + ' ' + this.toSingleLine(inline);
     }
 
-    // Numbered/bulleted lists
-    if (para.hasNumbering()) {
-      const style = para.getStyle();
-      const isBullet =
-        style?.toLowerCase().includes('bullet') || style?.toLowerCase().includes('list bullet');
-      return isBullet ? `- ${text}` : `1. ${text}`;
+    const style = (para.getStyle() ?? '').toLowerCase();
+    const isListStyle =
+      style.includes('listbullet') ||
+      style.includes('list bullet') ||
+      style.includes('listnumber') ||
+      style.includes('list number');
+
+    if (hasNumbering || isListStyle) {
+      const level = para.getNumbering()?.level ?? 0;
+      const indent = '  '.repeat(Math.max(0, level));
+      const marker = this.isOrderedList(para) ? '1.' : '-';
+      return `${indent}${marker} ${this.toSingleLine(inline)}`;
     }
 
-    return text;
+    // Block quote (Quote / IntenseQuote styles).
+    if (style.includes('quote')) {
+      return this.toSingleLine(inline)
+        .split('\n')
+        .map((l) => `> ${l}`)
+        .join('\n');
+    }
+
+    return inline;
+  }
+
+  /**
+   * Determines whether a numbered paragraph uses an ordered (decimal/letter/
+   * roman) format rather than a bullet. Resolves the numbering definition when
+   * available, falling back to the paragraph's style name.
+   * @internal
+   */
+  private isOrderedList(para: Paragraph): boolean {
+    const numbering = para.getNumbering();
+    if (numbering) {
+      const instance = this.numberingManager.getInstance(numbering.numId);
+      if (instance) {
+        const abstract = this.numberingManager.getAbstractNumbering(instance.getAbstractNumId());
+        const levelDef = abstract?.getLevel(numbering.level);
+        const format = levelDef?.getFormat();
+        if (format) return format !== 'bullet';
+      }
+    }
+    const style = (para.getStyle() ?? '').toLowerCase();
+    if (style.includes('bullet')) return false;
+    if (style.includes('number')) return true;
+    return true;
   }
 
   /**
    * Converts paragraph inline content to Markdown with formatting.
    * @internal
    */
-  private paragraphContentToMarkdown(para: Paragraph): string {
-    const parts: string[] = [];
+  private paragraphContentToMarkdown(para: Paragraph, ctx: MarkdownContext): string {
+    return this.inlineContentToMarkdown(para.getContent(), ctx);
+  }
 
-    for (const item of para.getContent()) {
-      if (item instanceof Run) {
-        const runText = item.getText();
-        if (!runText) continue;
+  /**
+   * Converts a sequence of inline content items (runs, hyperlinks, fields,
+   * revisions, shapes, text boxes, preserved elements) to Markdown.
+   * @internal
+   */
+  private inlineContentToMarkdown(items: ParagraphContent[], ctx: MarkdownContext): string {
+    const parts: string[] = [];
 
-        const fmt = item.getFormatting();
-        let md = runText;
-
-        // Apply inline formatting (bold + italic combined)
-        if (fmt.bold && fmt.italic) {
-          md = `***${md}***`;
-        } else if (fmt.bold) {
-          md = `**${md}**`;
-        } else if (fmt.italic) {
-          md = `*${md}*`;
+    for (const item of items) {
+      // ImageRun extends Run, so it must be checked first.
+      if (item instanceof ImageRun) {
+        if (ctx.opts.images) {
+          const image = item.getImageElement();
+          const alt = this.escapeMarkdown(image.getAltText() || 'image');
+          const src = image.getRelationshipId() ?? 'image';
+          parts.push(`![${alt}](${src})`);
         }
-
-        if (fmt.strike) {
-          md = `~~${md}~~`;
+      } else if (item instanceof Run) {
+        parts.push(this.runToMarkdown(item, ctx));
+      } else if (item instanceof Hyperlink) {
+        const runs = item.getRuns();
+        let label =
+          runs.length > 0
+            ? runs.map((r) => this.runToMarkdown(r, ctx, true)).join('')
+            : this.escapeMarkdown(item.getText());
+        if (!label) label = this.escapeMarkdown(item.getText());
+        let url = item.getUrl() ?? '';
+        const anchor = item.getAnchor();
+        if (anchor) url = url ? `${url}#${anchor}` : `#${anchor}`;
+        parts.push(`[${label}](${url})`);
+      } else if (item instanceof Revision) {
+        const inner = this.inlineContentToMarkdown(item.getContent(), ctx);
+        if (!inner) continue;
+        const type = item.getType();
+        if (type === 'delete' || type === 'moveFrom') {
+          // Deleted/moved-away content (only present in 'preserve' mode): mark it
+          // so the information survives without claiming it as final body text.
+          parts.push(ctx.opts.htmlFallback ? `<del>${inner}</del>` : `~~${inner}~~`);
+        } else {
+          parts.push(inner);
         }
-
-        // Inline code (monospace font detection)
-        if (
-          fmt.font &&
-          /^(courier|consolas|monaco|menlo|source code|fira code|jetbrains mono)/i.test(fmt.font)
-        ) {
-          md = `\`${runText}\``;
+      } else if (item instanceof ComplexField) {
+        const result = item.getResult();
+        if (result) parts.push(this.escapeMarkdown(result));
+      } else if (item instanceof Field) {
+        const result = item.getCachedResult();
+        if (result) parts.push(this.escapeMarkdown(result));
+      } else if (item instanceof TextBox) {
+        const text = item
+          .getParagraphs()
+          .map((p) => this.paragraphContentToMarkdown(p, ctx))
+          .filter((s) => s !== '')
+          .join(' ');
+        if (text) parts.push(text);
+      } else if (item instanceof Shape) {
+        const text = item.getText();
+        if (text) parts.push(this.escapeMarkdown(text));
+      } else if (item instanceof PreservedElement) {
+        const type = item.getElementType();
+        // Comment range/reference markers carry no inline body text.
+        if (!type.startsWith('w:comment')) {
+          const text = this.extractTextFromRawXml(item.getRawXml());
+          if (text) parts.push(this.escapeMarkdown(text));
         }
-
-        parts.push(md);
-      } else if (item instanceof Hyperlink) {
-        const url = item.getUrl() || '';
-        const linkText = item.getText() || url;
-        parts.push(`[${linkText}](${url})`);
       }
-      // Revisions, fields, shapes, etc. — extract text if possible
+      // RangeMarker (bookmarks) carry no display text and are skipped.
     }
 
     return parts.join('');
   }
 
   /**
-   * Converts a table to Markdown table lines.
+   * Converts a single run to Markdown, applying inline formatting and emitting
+   * footnote/endnote markers. Tabs, breaks and symbols are preserved.
    * @internal
    */
-  private tableToMarkdown(table: Table): string[] {
-    const data = table.toArray();
-    if (data.length === 0) return [];
+  private runToMarkdown(run: Run, ctx: MarkdownContext, inLink = false): string {
+    const fmt = run.getFormatting();
+    const isMono = !!(
+      fmt.font &&
+      /^(courier|consolas|monaco|menlo|source code|fira code|jetbrains mono)/i.test(fmt.font)
+    );
+    const escape = (s: string): string => (isMono ? s : this.escapeMarkdown(s));
 
-    const colCount = Math.max(...data.map((row) => row.length));
+    const segments: string[] = [];
+    const markers: string[] = [];
+
+    for (const content of run.getContent()) {
+      switch (content.type) {
+        case 'text':
+        case 'instructionText':
+          segments.push(escape(content.value ?? ''));
+          break;
+        case 'tab':
+          segments.push('\t');
+          break;
+        case 'carriageReturn':
+          segments.push('\n');
+          break;
+        case 'break':
+          // Page/column breaks are layout-only; line breaks become hard breaks.
+          if (content.breakType !== 'page' && content.breakType !== 'column') {
+            segments.push(ctx.opts.htmlFallback ? '<br>' : '\n');
+          }
+          break;
+        case 'noBreakHyphen':
+          segments.push('‑');
+          break;
+        case 'symbol':
+          if (content.symbolChar) {
+            const code = parseInt(content.symbolChar, 16);
+            if (!Number.isNaN(code)) segments.push(escape(String.fromCharCode(code)));
+          }
+          break;
+        case 'footnoteReference':
+          if (ctx.opts.footnotes && content.footnoteId !== undefined) {
+            markers.push(this.noteMarker(content.footnoteId, 'fn', ctx));
+          }
+          break;
+        case 'endnoteReference':
+          if (ctx.opts.footnotes && content.endnoteId !== undefined) {
+            markers.push(this.noteMarker(content.endnoteId, 'en', ctx));
+          }
+          break;
+        // Field chars, VML, soft hyphens and other layout markers contribute no text.
+        default:
+          break;
+      }
+    }
+
+    let text = segments.join('');
+    if (text) {
+      if (isMono) {
+        text = `\`${text}\``;
+      }
+      // Emphasis (bold/italic innermost, strikethrough outermost).
+      if (fmt.bold && fmt.italic) text = `***${text}***`;
+      else if (fmt.bold) text = `**${text}**`;
+      else if (fmt.italic) text = `*${text}*`;
+      if (fmt.strike || fmt.dstrike) text = `~~${text}~~`;
+
+      if (ctx.opts.htmlFallback) {
+        if (fmt.superscript) text = `<sup>${text}</sup>`;
+        else if (fmt.subscript) text = `<sub>${text}</sub>`;
+        if (fmt.highlight && fmt.highlight !== 'none') text = `<mark>${text}</mark>`;
+        // Underline and color are the conventional appearance of a hyperlink, so
+        // suppress them inside link labels to avoid redundant markup; elsewhere
+        // they carry real information and are preserved as inline HTML.
+        if (!inLink) {
+          if (fmt.underline && fmt.underline !== 'none') text = `<u>${text}</u>`;
+          if (fmt.color && fmt.color !== 'auto' && /^[0-9a-fA-F]{6}$/.test(fmt.color)) {
+            text = `<span style="color:#${fmt.color}">${text}</span>`;
+          }
+        }
+      }
+    }
+
+    // Footnote/endnote markers follow the text, unaffected by run formatting.
+    return text + markers.join('');
+  }
+
+  /**
+   * Resolves a footnote/endnote reference to a GFM marker and records its
+   * definition (once) for later emission.
+   * @internal
+   */
+  private noteMarker(id: number, kind: 'fn' | 'en', ctx: MarkdownContext): string {
+    const marker = `${kind}${id}`;
+    if (!ctx.noteMarkers.has(marker)) {
+      ctx.noteMarkers.add(marker);
+      const note =
+        kind === 'fn' ? this.footnoteManager.getFootnote(id) : this.endnoteManager.getEndnote(id);
+      let text = '';
+      if (note) {
+        text = note
+          .getParagraphs()
+          .map((p) => this.paragraphContentToMarkdown(p, ctx))
+          .filter((s) => s !== '')
+          .join(' ')
+          .replace(/\s*\n\s*/g, ' ')
+          .trim();
+      }
+      ctx.notes.push({ marker, text });
+    }
+    return `[^${marker}]`;
+  }
+
+  /**
+   * Converts a table to Markdown. Simple grid tables become GFM pipe tables;
+   * tables with merged or nested cells fall back to inline HTML (when enabled)
+   * so structural information is preserved.
+   * @internal
+   */
+  private tableToMarkdown(table: Table, ctx: MarkdownContext): string[] {
+    const rows = table.getRows();
+    if (rows.length === 0) return [];
+
+    const isComplex = rows.some((row) =>
+      row
+        .getCells()
+        .some(
+          (cell) =>
+            (cell.getColumnSpan() ?? 1) > 1 ||
+            cell.getVerticalMerge() !== undefined ||
+            cell.hasNestedTables()
+        )
+    );
+
+    if (isComplex && ctx.opts.htmlFallback) {
+      return this.tableToHtmlBlock(table);
+    }
+
+    const matrix = rows.map((row) => row.getCells().map((cell) => this.cellToMarkdown(cell, ctx)));
+    const colCount = Math.max(...matrix.map((row) => row.length));
     if (colCount === 0) return [];
 
-    // Normalize all rows to same column count
-    const normalized = data.map((row) => {
+    const normalized = matrix.map((row) => {
       const padded = [...row];
       while (padded.length < colCount) padded.push('');
-      // Escape pipes and normalize whitespace in cell text
-      return padded.map((cell) => cell.replace(/\|/g, '\\|').replace(/\n/g, ' ').trim());
+      return padded;
     });
 
     const lines: string[] = [];
-
-    // Header row
     lines.push('| ' + normalized[0]!.join(' | ') + ' |');
-
-    // Separator row
     lines.push('| ' + normalized[0]!.map(() => '---').join(' | ') + ' |');
-
-    // Data rows
     for (let i = 1; i < normalized.length; i++) {
       lines.push('| ' + normalized[i]!.join(' | ') + ' |');
     }
-
     return lines;
   }
 
+  /**
+   * Renders a single table cell as inline Markdown text (formatting preserved),
+   * with pipes escaped and line breaks collapsed for pipe-table compatibility.
+   * @internal
+   */
+  private cellToMarkdown(cell: TableCell, ctx: MarkdownContext): string {
+    const text = cell
+      .getParagraphs()
+      .map((p) => this.paragraphContentToMarkdown(p, ctx))
+      .filter((s) => s !== '')
+      .join(' ');
+    return text.replace(/\|/g, '\\|').replace(/<br>/g, ' ').replace(/\n/g, ' ').trim();
+  }
+
+  /**
+   * Renders a table with merged or nested cells as an inline HTML table,
+   * honoring `colspan`/`rowspan` from grid and vertical-merge information.
+   * @internal
+   */
+  private tableToHtmlBlock(table: Table): string[] {
+    const rows = table.getRows();
+
+    // Precompute each cell's starting grid column (accounting for column spans).
+    const rowCells = rows.map((row) => {
+      let gridStart = 0;
+      return row.getCells().map((cell) => {
+        const span = cell.getColumnSpan() ?? 1;
+        const entry = { cell, gridStart, span };
+        gridStart += span;
+        return entry;
+      });
+    });
+
+    const html: string[] = ['<table>'];
+    for (let ri = 0; ri < rowCells.length; ri++) {
+      html.push('<tr>');
+      for (const { cell, gridStart, span } of rowCells[ri]!) {
+        // Cells continuing a vertical merge are covered by the rowspan above.
+        if (cell.getVerticalMerge() === 'continue') continue;
+
+        let rowspan = 1;
+        if (cell.getVerticalMerge() === 'restart') {
+          for (let rj = ri + 1; rj < rowCells.length; rj++) {
+            const below = rowCells[rj]!.find((e) => e.gridStart === gridStart);
+            if (below?.cell.getVerticalMerge() === 'continue') rowspan++;
+            else break;
+          }
+        }
+
+        const tag = ri === 0 ? 'th' : 'td';
+        const attrs =
+          (span > 1 ? ` colspan="${span}"` : '') + (rowspan > 1 ? ` rowspan="${rowspan}"` : '');
+
+        let content =
+          cell
+            .getParagraphs()
+            .map((p) => this.paragraphContentToHTML(p))
+            .filter((s) => s !== '')
+            .join('<br>') || this.escapeHTML(cell.getText());
+
+        if (cell.hasNestedTables()) {
+          const nestedText = cell
+            .getRawNestedContent()
+            .map((n) => this.extractTextFromRawXml(n.xml))
+            .filter((s) => s)
+            .join(' ');
+          if (nestedText) content += `<br>${this.escapeHTML(nestedText)}`;
+        }
+
+        html.push(`<${tag}${attrs}>${content}</${tag}>`);
+      }
+      html.push('</tr>');
+    }
+    html.push('</table>');
+    return html;
+  }
+
+  /**
+   * Escapes Markdown-significant characters in literal text so they render
+   * verbatim rather than as formatting.
+   * @internal
+   */
+  private escapeMarkdown(text: string): string {
+    return text.replace(/([\\`*_[\]<>])/g, '\\$1');
+  }
+
+  /**
+   * Collapses hard/soft line breaks to single spaces for contexts that must
+   * stay on one line (headings, list items, table cells).
+   * @internal
+   */
+  private toSingleLine(text: string): string {
+    return text.replace(/<br>/g, ' ').replace(/\s*\n\s*/g, ' ');
+  }
+
+  /**
+   * Extracts visible text from a raw OOXML fragment by concatenating the
+   * contents of its `w:t` elements and decoding XML entities. Used as a
+   * last-resort so preserved/round-trip elements never silently lose text.
+   * @internal
+   */
+  private extractTextFromRawXml(xml: string): string {
+    if (!xml.includes('<w:t')) return '';
+    const parts: string[] = [];
+    const regex = /<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>/g;
+    let match: RegExpExecArray | null;
+    while ((match = regex.exec(xml)) !== null) {
+      parts.push(match[1] ?? '');
+    }
+    return parts
+      .join('')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&amp;/g, '&')
+      .trim();
+  }
+
   /**
    * Converts the document to an HTML string
    *
@@ -15567,8 +16467,13 @@ export class Document {
 
         parts.push(html);
       } else if (item instanceof Hyperlink) {
-        const url = this.escapeHTML(item.getUrl() || '');
-        const linkText = this.escapeHTML(item.getText() || url);
+        // Word stores the fragment/anchor (e.g. "!/view?docid=…") separately
+        // from the base URL; recombine them so deep links are not truncated.
+        let rawUrl = item.getUrl() ?? '';
+        const anchor = item.getAnchor();
+        if (anchor) rawUrl = rawUrl ? `${rawUrl}#${anchor}` : `#${anchor}`;
+        const url = this.escapeHTML(rawUrl);
+        const linkText = this.escapeHTML(item.getText() || rawUrl);
         parts.push(`<a href="${url}">${linkText}</a>`);
       }
     }
@@ -15871,7 +16776,12 @@ export class Document {
     let index: number;
 
     if (typeof paragraphOrIndex === 'number') {
-      index = paragraphOrIndex;
+      // Numeric index is paragraph-ordinal (matching getParagraphAt /
+      // getParagraphIndex), not a bodyElements index — tables or SDTs before
+      // the target would otherwise shift it onto the wrong paragraph.
+      const para = this.getParagraphAt(paragraphOrIndex);
+      if (!para) return false;
+      index = this.bodyElements.indexOf(para);
     } else {
       // Find the index of the paragraph
       index = this.bodyElements.indexOf(paragraphOrIndex);
@@ -15884,13 +16794,12 @@ export class Document {
         // 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) {
-            const author = this.trackingContext.getAuthor();
-            const deletion = Revision.createDeletion(author, runs);
-            this.trackingContext.getRevisionManager().register(deletion);
-            element.addRevision(deletion);
-          }
+          // clearContent with tracking bound REPLACES each Run/Hyperlink with
+          // its delete revision in place. Appending a revision built from
+          // getRuns() would leave the originals live alongside the w:del copy,
+          // so the text would serialize twice and survive an accept-all.
+          this.bindTrackingToElement(element);
+          element.clearContent();
           return true;
         }
         this.bodyElements.splice(index, 1);
@@ -16511,23 +17420,12 @@ export class Document {
       }
     };
 
+    // getAllParagraphs() already walks table-cell paragraphs, so a separate
+    // table pass would report each table hyperlink twice.
     for (const paragraph of this.getAllParagraphs()) {
       extractHyperlinksFromParagraph(paragraph);
     }
 
-    // Also check in tables
-    for (const table of this.getTables()) {
-      for (const row of table.getRows()) {
-        for (const cell of row.getCells()) {
-          // TableCell has getParagraphs method
-          const cellParagraphs = cell instanceof TableCell ? cell.getParagraphs() : [];
-          for (const para of cellParagraphs) {
-            extractHyperlinksFromParagraph(para);
-          }
-        }
-      }
-    }
-
     return hyperlinks;
   }
 
@@ -16721,6 +17619,8 @@ export class Document {
   getBookmarks(): { bookmark: Bookmark; paragraph: Paragraph }[] {
     const bookmarks: { bookmark: Bookmark; paragraph: Paragraph }[] = [];
 
+    // getAllParagraphs() already walks table-cell paragraphs, so a separate
+    // table pass would report each table bookmark twice.
     for (const paragraph of this.getAllParagraphs()) {
       // Get bookmarks that start in this paragraph
       for (const bookmark of paragraph.getBookmarksStart()) {
@@ -16728,19 +17628,6 @@ export class Document {
       }
     }
 
-    // Also check in tables
-    for (const table of this.getTables()) {
-      for (const row of table.getRows()) {
-        for (const cell of row.getCells()) {
-          for (const para of cell.getParagraphs()) {
-            for (const bookmark of para.getBookmarksStart()) {
-              bookmarks.push({ bookmark, paragraph: para });
-            }
-          }
-        }
-      }
-    }
-
     return bookmarks;
   }
 
@@ -16780,27 +17667,14 @@ export class Document {
   getFields(): { field: FieldLike; paragraph: Paragraph; table?: Table }[] {
     const results: { field: FieldLike; paragraph: Paragraph; table?: Table }[] = [];
 
-    // Get fields from all body paragraphs
+    // getAllParagraphs() already walks table-cell paragraphs, so a separate
+    // table pass would report each table field twice.
     for (const paragraph of this.getAllParagraphs()) {
       for (const field of paragraph.getFields()) {
         results.push({ field, paragraph });
       }
     }
 
-    // Get fields from paragraphs inside table cells
-    for (const table of this.getTables()) {
-      for (const row of table.getRows()) {
-        for (const cell of row.getCells()) {
-          const cellParagraphs = cell instanceof TableCell ? cell.getParagraphs() : [];
-          for (const para of cellParagraphs) {
-            for (const field of para.getFields()) {
-              results.push({ field, paragraph: para, table });
-            }
-          }
-        }
-      }
-    }
-
     return results;
   }
 
@@ -16892,7 +17766,14 @@ export class Document {
 
       // 5. If format changed (e.g., bmp → png), update filename + relationships
       if (result.newExtension !== extension) {
-        const newFilename = filename.replace(/\.[^.]+$/, `.${result.newExtension}`);
+        // Swapping the extension can collide with a distinct existing media
+        // part (e.g. image1.bmp → image1.png when image1.png already exists;
+        // non-Word producers don't share Word's global numbering). Resolve to
+        // a fresh, unused name before renaming so neither image is clobbered.
+        const newFilename = this.resolveUniqueMediaFilename(
+          filename.replace(/\.[^.]+$/, `.${result.newExtension}`),
+          filename
+        );
         this.imageManager.updateEntryFilename(image, newFilename);
 
         // Update relationship targets across all relationship managers
@@ -16908,6 +17789,33 @@ export class Document {
     return { optimizedCount, totalSavedBytes: totalSaved };
   }
 
+  /**
+   * Resolves a media filename that does not collide with an existing ZIP media
+   * part or another registered image entry. If the candidate is free, it is
+   * returned unchanged; otherwise a numeric suffix is appended to the base name
+   * (image1.png → image1-1.png → image1-2.png …) until a unique name is found.
+   * @param candidate The desired filename (base name + extension, no directory)
+   * @param currentFilename The filename being renamed away from (excluded from collision check)
+   * @private
+   */
+  private resolveUniqueMediaFilename(candidate: string, currentFilename: string): string {
+    const dotIndex = candidate.lastIndexOf('.');
+    const base = dotIndex === -1 ? candidate : candidate.slice(0, dotIndex);
+    const ext = dotIndex === -1 ? '' : candidate.slice(dotIndex);
+
+    const isTaken = (name: string): boolean =>
+      this.zipHandler.hasFile(`word/media/${name}`) ||
+      this.imageManager.isFilenameOwnedByOther(name, currentFilename);
+
+    let name = candidate;
+    let counter = 1;
+    while (isTaken(name)) {
+      name = `${base}-${counter}${ext}`;
+      counter++;
+    }
+    return name;
+  }
+
   /**
    * Updates an image relationship target when the image format changes.
    * Handles both document body and header/footer relationships.
@@ -17296,7 +18204,7 @@ export class Document {
 
       this.bodyElements.forEach((element, index) => {
         if (element instanceof Paragraph) {
-          const isEmpty = element.getText().trim() === '';
+          const isEmpty = this.isParagraphRemovableBlank(element);
           if (isEmpty && lastWasEmpty) {
             toRemove.push(index);
           }
@@ -17392,6 +18300,44 @@ export class Document {
     return { removed, normalized };
   }
 
+  /**
+   * Determines whether a body paragraph is safely removable as a duplicate
+   * empty paragraph. Text emptiness alone is insufficient: a paragraph with no
+   * visible text can still carry a bookmark/comment anchor, an inline image or
+   * shape, a range marker, or a section break (sectPr) in its formatting.
+   * Removing such a paragraph silently destroys that content. Mirrors the
+   * richer blankness standard used by TableCell.isParaBlank.
+   * @private
+   */
+  private isParagraphRemovableBlank(para: Paragraph): boolean {
+    if (para.getText().trim() !== '') return false;
+
+    // Inline section break — removing it merges sections and drops that
+    // section's page setup / headers / margins.
+    if (para.formatting.sectPr !== undefined) return false;
+
+    // Bookmark anchors — destroying them breaks REF fields / internal hyperlinks
+    // targeting them ("Error! Bookmark not defined.").
+    if (para.getBookmarksStart().length > 0 || para.getBookmarksEnd().length > 0) {
+      return false;
+    }
+
+    // Comment anchors.
+    if (para.getCommentsStart().length > 0 || para.getCommentsEnd().length > 0) {
+      return false;
+    }
+
+    // Inline images, shapes, and range markers (bookmark/comment range markers)
+    // are invisible to getText() but are real content.
+    for (const item of para.getContent()) {
+      if (item instanceof ImageRun || item instanceof Shape || item instanceof RangeMarker) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
   /**
    * Sets the document language
    * @param language - Language code (e.g., 'en-US', 'es-ES', 'fr-FR')
@@ -17403,6 +18349,7 @@ export class Document {
       this.properties = {};
     }
     this.properties.language = language;
+    this._corePropsModified = true;
 
     return this;
   }
@@ -17701,7 +18648,9 @@ export class Document {
       ? new RegExp(find.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')
       : new RegExp(find.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
 
-    // Process body paragraphs
+    // getAllParagraphs() walks recursively and already includes every
+    // table-cell paragraph, so a separate table loop would re-apply the
+    // replacement to the same Run instances (e.g. 'cat'->'cats' => 'catss')
     for (const para of this.getAllParagraphs()) {
       for (const run of para.getRuns()) {
         const text = run.getText();
@@ -17725,36 +18674,6 @@ export class Document {
       }
     }
 
-    // Process paragraphs inside table cells
-    for (const table of this.getTables()) {
-      for (const row of table.getRows()) {
-        for (const cell of row.getCells()) {
-          for (const para of cell.getParagraphs()) {
-            for (const run of para.getRuns()) {
-              const text = run.getText();
-              if (!text) continue;
-
-              // Check formatting constraints
-              const runFormatting = run.getFormatting();
-              if (matchBold && !runFormatting.bold) continue;
-              if (matchItalic && !runFormatting.italic) continue;
-
-              // Perform replacement
-              if (pattern.test(text)) {
-                const newText = text.replace(pattern, replace);
-                if (newText !== text) {
-                  run.setText(newText);
-                  replacedCount++;
-                }
-              }
-              // Reset regex lastIndex for next iteration
-              pattern.lastIndex = 0;
-            }
-          }
-        }
-      }
-    }
-
     return replacedCount;
   }