docxmlater 11.0.9 → 12.0.1

package/src/formatting/NumberingLevel.ts

@@ -171,12 +171,28 @@ export class NumberingLevel {
   private properties: Required<
     Omit<
       NumberingLevelProperties,
-      'lvlRestart' | 'underline' | 'pStyle' | 'tentative' | 'tplc' | 'lvlPicBulletId' | 'legacy'
+      | 'fontSize'
+      | 'color'
+      | 'lvlRestart'
+      | 'underline'
+      | 'pStyle'
+      | 'tentative'
+      | 'tplc'
+      | 'lvlPicBulletId'
+      | 'legacy'
     >
   > &
     Pick<
       NumberingLevelProperties,
-      'lvlRestart' | 'underline' | 'pStyle' | 'tentative' | 'tplc' | 'lvlPicBulletId' | 'legacy'
+      | 'fontSize'
+      | 'color'
+      | 'lvlRestart'
+      | 'underline'
+      | 'pStyle'
+      | 'tentative'
+      | 'tplc'
+      | 'lvlPicBulletId'
+      | 'legacy'
     >;
 
   /**
@@ -195,11 +211,14 @@ export class NumberingLevel {
         properties.leftIndent !== undefined ? properties.leftIndent : 720 + properties.level * 360,
       hangingIndent: properties.hangingIndent !== undefined ? properties.hangingIndent : 360,
       font: properties.font || 'Calibri',
-      fontSize: properties.fontSize || 22, // 11pt default
+      // undefined = inherit per ECMA-376 (absent w:sz/w:color rPr child);
+      // forcing defaults here would inject explicit size/color into
+      // re-serialized levels that the source document never specified
+      fontSize: properties.fontSize,
       isLegalNumberingStyle:
         properties.isLegalNumberingStyle !== undefined ? properties.isLegalNumberingStyle : false,
       suffix: properties.suffix || 'tab',
-      color: properties.color || '000000',
+      color: properties.color,
       bold: properties.bold !== undefined ? properties.bold : false,
       italic: properties.italic !== undefined ? properties.italic : false,
       underline: properties.underline,
@@ -310,12 +329,28 @@ export class NumberingLevel {
   getProperties(): Required<
     Omit<
       NumberingLevelProperties,
-      'lvlRestart' | 'underline' | 'pStyle' | 'tentative' | 'tplc' | 'lvlPicBulletId' | 'legacy'
+      | 'fontSize'
+      | 'color'
+      | 'lvlRestart'
+      | 'underline'
+      | 'pStyle'
+      | 'tentative'
+      | 'tplc'
+      | 'lvlPicBulletId'
+      | 'legacy'
     >
   > &
     Pick<
       NumberingLevelProperties,
-      'lvlRestart' | 'underline' | 'pStyle' | 'tentative' | 'tplc' | 'lvlPicBulletId' | 'legacy'
+      | 'fontSize'
+      | 'color'
+      | 'lvlRestart'
+      | 'underline'
+      | 'pStyle'
+      | 'tentative'
+      | 'tplc'
+      | 'lvlPicBulletId'
+      | 'legacy'
     > {
     return { ...this.properties };
   }
@@ -616,13 +651,15 @@ export class NumberingLevel {
     // ... b, bCs, i, iCs, ... color (#19), ... sz (#24), szCs (#25), ... u (#27)
 
     // Color (#19)
-    if (this.properties.color) {
+    if (this.properties.color !== undefined) {
       rPrChildren.push(XMLBuilder.wSelf('color', { 'w:val': this.properties.color }));
     }
 
-    // Font size (#24, #25)
-    rPrChildren.push(XMLBuilder.wSelf('sz', { 'w:val': this.properties.fontSize.toString() }));
-    rPrChildren.push(XMLBuilder.wSelf('szCs', { 'w:val': this.properties.fontSize.toString() }));
+    // Font size (#24, #25) — omit when unset so the level inherits size
+    if (this.properties.fontSize !== undefined) {
+      rPrChildren.push(XMLBuilder.wSelf('sz', { 'w:val': this.properties.fontSize.toString() }));
+      rPrChildren.push(XMLBuilder.wSelf('szCs', { 'w:val': this.properties.fontSize.toString() }));
+    }
 
     // Underline (#27)
     if (this.properties.underline) {
@@ -1123,9 +1160,10 @@ export class NumberingLevel {
       if (hangingMatch?.[1]) hangingIndent = parseInt(hangingMatch[1], 10);
     }
 
-    // Extract font and size from <w:rPr>
+    // Extract font and size from <w:rPr>. An absent w:sz means the level
+    // inherits its size — keep it undefined so toXML doesn't fabricate one.
     let font = 'Calibri';
-    let fontSize = 22;
+    let fontSize: number | undefined;
 
     const rFontsMatch = /<w:rFonts[^>]*\/>/.exec(xml);
     if (rFontsMatch) {

package/src/formatting/NumberingManager.ts

@@ -542,6 +542,10 @@ export class NumberingManager {
     numLevel.setLeftIndent(leftIndent);
     numLevel.setHangingIndent(hangingIndent);
 
+    // NumberingLevel setters don't notify the manager; without this flag the
+    // save pipeline preserves the original numbering.xml and drops the change
+    this.markAbstractNumberingModified(instance.getAbstractNumId());
+
     return true;
   }
 
@@ -585,6 +589,10 @@ export class NumberingManager {
       level.setHangingIndent(standardIndent.hangingIndent);
     }
 
+    // NumberingLevel setters don't notify the manager; without this flag the
+    // save pipeline preserves the original numbering.xml and drops the change
+    this.markAbstractNumberingModified(instance.getAbstractNumId());
+
     return true;
   }
 
@@ -708,8 +716,10 @@ export class NumberingManager {
    * For each group with >1 member, picks the lowest abstractNumId as canonical,
    * remaps all instances pointing to non-canonical IDs, and removes duplicates.
    *
-   * This is safe because multiple num instances can reference the same abstractNum —
-   * each instance maintains its own independent counter via level overrides.
+   * Numbering counters belong to the abstract numbering definition: instances
+   * sharing an abstractNum continue one sequence in document order unless a
+   * startOverride restarts them (ECMA-376 §17.9.27). Remapped instances get a
+   * startOverride per counted level so each list keeps its independent restart.
    *
    * @param options Optional configuration (e.g., protected IDs to skip)
    * @returns Summary of what was consolidated
@@ -748,9 +758,23 @@ export class NumberingManager {
       groupsConsolidated++;
 
       // Remap instances pointing to duplicate abstractNums
+      const canonicalAbstract = this.abstractNumberings.get(canonicalId);
       for (const instance of this.instances.values()) {
         if (duplicateIds.has(instance.getAbstractNumId())) {
           instance.setAbstractNumId(canonicalId);
+
+          // Counters live on the abstractNum, so without a startOverride the
+          // remapped list would continue the canonical sequence instead of
+          // restarting — bullets carry no counter and are skipped
+          if (canonicalAbstract) {
+            for (const level of canonicalAbstract.getAllLevels()) {
+              const levelIndex = level.getLevel();
+              if (level.getFormat() === 'bullet') continue;
+              if (instance.getLevelOverride(levelIndex) !== undefined) continue;
+              instance.setLevelOverride(levelIndex, level.getProperties().start);
+            }
+          }
+
           this._modifiedNumIds.add(instance.getNumId());
           instancesRemapped++;
         }
@@ -785,11 +809,16 @@ export class NumberingManager {
 
     for (const level of abstractNum.getAllLevels()) {
       const props = level.getProperties();
+      // pStyle, lvlPicBulletId, and legacy all affect rendering (style-to-level
+      // linkage, picture bullet image, legacy indentation), so definitions
+      // differing on any of them must not be treated as duplicates
       parts.push(
         `${props.level}|${props.format}|${props.text}|${props.font}|${props.fontSize}|` +
           `${props.color}|${props.leftIndent}|${props.hangingIndent}|${props.alignment}|` +
           `${props.start}|${props.bold}|${props.italic}|${props.underline ?? ''}|` +
-          `${props.suffix}|${props.isLegalNumberingStyle}|${props.lvlRestart ?? ''}`
+          `${props.suffix}|${props.isLegalNumberingStyle}|${props.lvlRestart ?? ''}|` +
+          `${props.pStyle ?? ''}|${props.lvlPicBulletId ?? ''}|` +
+          `${JSON.stringify(props.legacy ?? null)}`
       );
     }
 

package/src/formatting/Style.ts

@@ -1636,6 +1636,8 @@ export class Style {
       },
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: 12,
         color: '000000',
       },
@@ -1684,6 +1686,8 @@ export class Style {
       },
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: sizes[level - 1],
         bold: true,
         color: '000000',
@@ -1713,6 +1717,8 @@ export class Style {
       uiPriority: 9,
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: sizes[level - 1],
         bold: true,
         color: '000000',
@@ -1738,6 +1744,8 @@ export class Style {
       },
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: 28,
         color: '000000',
       },
@@ -1762,6 +1770,8 @@ export class Style {
       },
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: 14,
         color: '000000',
         italic: true,
@@ -1798,6 +1808,8 @@ export class Style {
       },
       runFormatting: {
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: 12,
         color: '000000',
       },
@@ -1818,6 +1830,8 @@ export class Style {
       runFormatting: {
         bold: true,
         font: 'Verdana',
+        fontHAnsi: 'Verdana',
+        fontCs: 'Verdana',
         size: 14,
         color: '000000', // Black
       },

package/src/formatting/StylesManager.ts

@@ -74,6 +74,9 @@ export class StylesManager {
   // Track which specific styles have been modified (for selective merging)
   private _modifiedStyleIds = new Set<string>();
 
+  // Track which styles have been removed (for removal from original XML during merge)
+  private _removedStyleIds = new Set<string>();
+
   // Latent styles configuration
   private latentStyles?: LatentStylesConfig;
   private latentStyleExceptions: LatentStyleException[] = [];
@@ -176,6 +179,9 @@ export class StylesManager {
     }
     this.styles.set(style.getStyleId(), style);
     this._modifiedStyleIds.add(style.getStyleId());
+    // Re-adding a previously removed style cancels the pending removal —
+    // otherwise the merge would strip the style right after appending it
+    this._removedStyleIds.delete(style.getStyleId());
     this._modified = true;
     return this;
   }
@@ -218,7 +224,10 @@ export class StylesManager {
     const source = this.getStyle(sourceId);
     if (!source) return undefined;
 
-    const props = source.getProperties();
+    // Use Style.clone()'s deepClone path so nested formatting (runFormatting,
+    // paragraphFormatting, tableStyle) is fully copied — not reference-shared
+    // with the source — matching this method's documented deep-copy guarantee.
+    const props = source.clone().getProperties();
     props.styleId = newId;
     props.name = newName ?? newId;
     props.isDefault = false; // Clones should never be default
@@ -249,7 +258,15 @@ export class StylesManager {
    * @returns True if the style was removed
    */
   removeStyle(styleId: string): boolean {
-    return this.styles.delete(styleId);
+    const deleted = this.styles.delete(styleId);
+    if (deleted) {
+      // Drop from the modified set so the merge cannot resurrect the style
+      // (getStyle lazily re-creates built-ins, which would re-append it)
+      this._modifiedStyleIds.delete(styleId);
+      this._removedStyleIds.add(styleId);
+      this._modified = true;
+    }
+    return deleted;
   }
 
   /**
@@ -276,6 +293,7 @@ export class StylesManager {
   resetModified(): void {
     this._modified = false;
     this._modifiedStyleIds.clear();
+    this._removedStyleIds.clear();
   }
 
   /**
@@ -287,6 +305,15 @@ export class StylesManager {
     return new Set(this._modifiedStyleIds);
   }
 
+  /**
+   * Gets the IDs of styles that have been removed since loading
+   * Used for removal from original styles.xml during merge
+   * @returns Set of removed style IDs
+   */
+  getRemovedStyleIds(): Set<string> {
+    return new Set(this._removedStyleIds);
+  }
+
   /**
    * Gets styles by type
    * @param type - Style type to filter by

package/src/helpers/CleanupHelper.ts

@@ -21,6 +21,7 @@ import { Hyperlink } from '../elements/Hyperlink.js';
 import { Paragraph } from '../elements/Paragraph.js';
 import { Table } from '../elements/Table.js';
 import { StructuredDocumentTag } from '../elements/StructuredDocumentTag.js';
+import { StylesManager } from '../formatting/StylesManager.js';
 
 export interface CleanupOptions {
   /** Unlock all SDTs to enable editing */
@@ -264,24 +265,98 @@ export class CleanupHelper {
   }
 
   private cleanupStyles(): number {
-    // Implementation for unused styles removal
-    // Scan all paragraphs and runs for used styles
+    const stylesManager = this.doc.getStylesManager();
     const usedStyles = new Set<string>();
-    for (const para of this.doc.getAllParagraphs()) {
+
+    const collectParagraph = (para: Paragraph): void => {
       const paraStyle = para.getFormatting().style;
       if (paraStyle) usedStyles.add(paraStyle);
       for (const run of para.getRuns()) {
         const runStyle = run.getFormatting().characterStyle;
         if (runStyle) usedStyles.add(runStyle);
       }
+    };
+
+    // Body paragraphs (getAllParagraphs walks table cells and nested SDTs)
+    for (const para of this.doc.getAllParagraphs()) {
+      collectParagraph(para);
+    }
+
+    // Table styles (w:tblStyle) — tables reference styles without any
+    // paragraph carrying the ID, so a paragraph-only scan misses them
+    for (const table of this.doc.getAllTables()) {
+      const tableStyle = table.getFormatting().style;
+      if (tableStyle) usedStyles.add(tableStyle);
+    }
+
+    // Headers and footers live outside the body walk
+    const headerFooterManager = this.doc.getHeaderFooterManager();
+    const headerFooterElements = [
+      ...headerFooterManager.getAllHeaders().flatMap((entry) => entry.header.getElements()),
+      ...headerFooterManager.getAllFooters().flatMap((entry) => entry.footer.getElements()),
+    ];
+    for (const element of headerFooterElements) {
+      if (element instanceof Paragraph) {
+        collectParagraph(element);
+      } else if (element instanceof Table) {
+        const tableStyle = element.getFormatting().style;
+        if (tableStyle) usedStyles.add(tableStyle);
+        for (const row of element.getRows()) {
+          for (const cell of row.getCells()) {
+            for (const para of cell.getParagraphs()) {
+              collectParagraph(para);
+            }
+          }
+        }
+      }
+    }
+
+    // Footnotes and endnotes also live outside the body walk
+    for (const footnote of this.doc.getFootnoteManager().getAllFootnotes()) {
+      for (const para of footnote.getParagraphs()) {
+        collectParagraph(para);
+      }
+    }
+    for (const endnote of this.doc.getEndnoteManager().getAllEndnotes()) {
+      for (const para of endnote.getParagraphs()) {
+        collectParagraph(para);
+      }
+    }
+
+    // Numbering levels can bind a paragraph style (w:pStyle, ECMA-376 §17.9.23)
+    for (const abstractNum of this.doc.getNumberingManager().getAllAbstractNumberings()) {
+      for (const level of abstractNum.getAllLevels()) {
+        const pStyle = level.getParagraphStyle();
+        if (pStyle) usedStyles.add(pStyle);
+      }
+    }
+
+    // Expand to basedOn/link/next ancestors transitively — removing a chain
+    // member leaves dangling references that break style resolution in Word
+    const allStyles = stylesManager.getAllStyles();
+    const stylesById = new Map(allStyles.map((style) => [style.getStyleId(), style]));
+    const pending = [...usedStyles];
+    while (pending.length > 0) {
+      const style = stylesById.get(pending.pop()!);
+      if (!style) continue;
+      const props = style.getProperties();
+      for (const ref of [props.basedOn, props.link, props.next]) {
+        if (ref && !usedStyles.has(ref)) {
+          usedStyles.add(ref);
+          pending.push(ref);
+        }
+      }
     }
 
-    // Remove unused styles
+    // Remove unused styles — but never built-ins or part defaults, which
+    // apply without being referenced (mirrors StylesManager.cleanupUnusedStyles)
     let removed = 0;
-    const allStyles = this.doc.getStylesManager().getAllStyles();
     for (const style of allStyles) {
-      if (!usedStyles.has(style.getStyleId())) {
-        this.doc.getStylesManager().removeStyle(style.getStyleId());
+      const styleId = style.getStyleId();
+      if (usedStyles.has(styleId)) continue;
+      if (StylesManager.isBuiltInStyle(styleId)) continue;
+      if (style.getProperties().isDefault) continue;
+      if (stylesManager.removeStyle(styleId)) {
         removed++;
       }
     }
@@ -330,38 +405,55 @@ export class CleanupHelper {
     return removed;
   }
 
+  // Lock state must be cleared on the in-memory model, not the ZIP copy of
+  // word/document.xml: prepareSave() regenerates document.xml from the model,
+  // so raw-XML edits here would be overwritten and the locks re-emitted.
   private unlockFields(): number {
-    const zipHandler = this.doc.getZipHandler();
-    const docXml = zipHandler.getFileAsString('word/document.xml');
-    if (!docXml) return 0;
+    let count = 0;
 
-    // Count matches first, then replace (avoid regex re-execution)
-    const pattern = /w:fldLock="(1|true)"/g;
-    const matches = docXml.match(pattern) || [];
-    if (matches.length === 0) return 0;
+    for (const para of this.doc.getAllParagraphs()) {
+      // w:fldChar w:fldLock on complex-field runs (ECMA-376 §17.16.18).
+      // getRuns() includes runs inside revisions and hyperlinks; the
+      // returned content elements are live references, so clearing the
+      // flag mutates the run itself.
+      for (const run of para.getRuns()) {
+        for (const item of run.getContent()) {
+          if (item.type === 'fieldChar' && item.fieldCharLocked === true) {
+            item.fieldCharLocked = undefined;
+            count++;
+          }
+        }
+      }
 
-    // Remove w:fldLock="1" or w:fldLock="true"
-    const updatedXml = docXml.replace(pattern, '');
-    zipHandler.updateFile('word/document.xml', updatedXml);
+      // w:fldLock on simple fields (w:fldSimple, ECMA-376 §17.16.16).
+      // Field keeps the flag private with no mutator, so clear it
+      // structurally — the regenerated fldSimple then omits the attribute.
+      for (const item of para.getContent()) {
+        if (item instanceof Field) {
+          const lockable = item as unknown as { fldLock?: boolean };
+          if (lockable.fldLock === true) {
+            lockable.fldLock = undefined;
+            count++;
+          }
+        }
+      }
+    }
 
-    return matches.length;
+    return count;
   }
 
   private unlockFrames(): number {
-    const zipHandler = this.doc.getZipHandler();
-    const docXml = zipHandler.getFileAsString('word/document.xml');
-    if (!docXml) return 0;
-
-    // Count matches first, then replace (avoid regex re-execution)
-    const pattern = /w:anchorLock="(1|true)"/g;
-    const matches = docXml.match(pattern) || [];
-    if (matches.length === 0) return 0;
+    let count = 0;
 
-    // Remove w:anchorLock="1" or w:anchorLock="true"
-    const updatedXml = docXml.replace(pattern, '');
-    zipHandler.updateFile('word/document.xml', updatedXml);
+    for (const para of this.doc.getAllParagraphs()) {
+      const framePr = para.getFormatting().framePr;
+      if (framePr?.anchorLock === true) {
+        para.setFrameProperties({ ...framePr, anchorLock: undefined });
+        count++;
+      }
+    }
 
-    return matches.length;
+    return count;
   }
 
   private sanitizeTables(): number {

package/src/images/ImageOptimizer.ts

@@ -144,6 +144,26 @@ export function optimizePng(buffer: Buffer): Buffer | null {
 // BMP → PNG Conversion
 // =============================================================================
 
+/**
+ * Maps a 32-bit BI_BITFIELDS channel mask to its byte index within a
+ * little-endian pixel. Only byte-aligned 8-bit masks map losslessly onto
+ * PNG's 8-bit channels; anything else returns null.
+ */
+function maskToByteIndex(mask: number): number | null {
+  switch (mask) {
+    case 0x000000ff:
+      return 0;
+    case 0x0000ff00:
+      return 1;
+    case 0x00ff0000:
+      return 2;
+    case 0xff000000:
+      return 3;
+    default:
+      return null;
+  }
+}
+
 /**
  * Converts a BMP buffer to PNG format. Lossless conversion.
  * Supports 24-bit (RGB) and 32-bit (RGBA) uncompressed BMPs.
@@ -186,6 +206,45 @@ export function convertBmpToPng(buffer: Buffer): Buffer | null {
   // Validate buffer has enough pixel data
   if (pixelDataOffset + absHeight * rowSize > buffer.length) return null;
 
+  // Channel byte offsets within a pixel; defaults match the standard BGR(A) layout
+  let rOff = 2;
+  let gOff = 1;
+  let bOff = 0;
+  let aOff = 3;
+  let forceOpaqueAlpha = false;
+
+  if (bitsPerPixel === 32) {
+    if (compression === 3) {
+      // BI_BITFIELDS: channel masks follow BITMAPINFOHEADER (the same file
+      // offsets hold the masks inside V4/V5 headers), so they must be honored
+      // to keep the conversion lossless
+      if (buffer.length < 66) return null;
+      const rIdx = maskToByteIndex(buffer.readUInt32LE(54));
+      const gIdx = maskToByteIndex(buffer.readUInt32LE(58));
+      const bIdx = maskToByteIndex(buffer.readUInt32LE(62));
+      if (rIdx === null || gIdx === null || bIdx === null) return null;
+      if (rIdx === gIdx || rIdx === bIdx || gIdx === bIdx) return null;
+      rOff = rIdx;
+      gOff = gIdx;
+      bOff = bIdx;
+      aOff = 6 - rIdx - gIdx - bIdx; // the byte not claimed by R/G/B carries alpha
+    } else {
+      // BI_RGB: the 4th byte is reserved and writers commonly zero it, so
+      // copying it as alpha would render the whole image transparent. Treat it
+      // as alpha only when at least one pixel carries a non-zero value.
+      forceOpaqueAlpha = true;
+      for (let y = 0; forceOpaqueAlpha && y < absHeight; y++) {
+        const rowOffset = pixelDataOffset + y * rowSize;
+        for (let x = 0; x < width; x++) {
+          if (buffer[rowOffset + x * 4 + 3] !== 0) {
+            forceOpaqueAlpha = false;
+            break;
+          }
+        }
+      }
+    }
+  }
+
   // PNG color type: 2 = RGB (24-bit), 6 = RGBA (32-bit)
   const colorType = bitsPerPixel === 32 ? 6 : 2;
   const pngBytesPerPixel = bitsPerPixel === 32 ? 4 : 3;
@@ -216,13 +275,13 @@ export function convertBmpToPng(buffer: Buffer): Buffer | null {
       const bmpPixelOffset = bmpRowOffset + x * bytesPerPixel;
       const pngPixelOffset = pngRowOffset + 1 + x * pngBytesPerPixel;
 
-      // Convert BGR(A) → RGB(A)
-      rawData[pngPixelOffset] = buffer[bmpPixelOffset + 2]!; // R
-      rawData[pngPixelOffset + 1] = buffer[bmpPixelOffset + 1]!; // G
-      rawData[pngPixelOffset + 2] = buffer[bmpPixelOffset]!; // B
+      // Route channels by resolved byte offsets (BGR(A) unless masks say otherwise)
+      rawData[pngPixelOffset] = buffer[bmpPixelOffset + rOff]!; // R
+      rawData[pngPixelOffset + 1] = buffer[bmpPixelOffset + gOff]!; // G
+      rawData[pngPixelOffset + 2] = buffer[bmpPixelOffset + bOff]!; // B
 
       if (bitsPerPixel === 32) {
-        rawData[pngPixelOffset + 3] = buffer[bmpPixelOffset + 3]!; // A
+        rawData[pngPixelOffset + 3] = forceOpaqueAlpha ? 0xff : buffer[bmpPixelOffset + aOff]!; // A
       }
     }
   }

package/src/index.ts

@@ -13,6 +13,7 @@ export {
   DocumentOptions,
   DocumentLoadOptions,
   DocumentPart,
+  MarkdownConversionOptions,
 } from './core/Document.js';
 
 // =============================================================================
@@ -411,6 +412,12 @@ export {
   CorruptionType,
 } from './utils/corruptionDetection.js';
 export { isError, toError, wrapError, getErrorMessage } from './utils/errorHandling.js';
+// Deliberately on the stable path: ResourceLimitError is the security-relevant,
+// catchable error thrown by Document.load/loadFromBuffer for oversized/zip-bomb
+// untrusted input, and SizeLimitOptions is its tuning type. The rest of the
+// DocxError hierarchy stays on the `docxmlater/internal` subpath.
+export { ResourceLimitError } from './zip/errors.js';
+export type { SizeLimitOptions } from './zip/types.js';
 export {
   REVISION_RULES,
   ValidationSeverity,

package/src/internal.ts

@@ -46,6 +46,7 @@ export {
   CorruptedArchiveError,
   MissingRequiredFileError,
   FileOperationError,
+  ResourceLimitError,
 } from './zip/errors.js';
 
 // XML layer

package/src/processors/CompatibilityUpgrader.ts

@@ -67,9 +67,22 @@ export class CompatibilityUpgrader {
     const selfClosingCompat = /<w:compat\s*\/>/.exec(settingsXml);
 
     if (!compatBlockMatch && !selfClosingCompat) {
-      // No w:compat block — insert a full modern block before </w:settings>
+      // No w:compat block — insert a full modern block. CT_Settings is an
+      // xsd:sequence where w:compat must precede rsids, mathPr, themeFontLang,
+      // clrSchemeMapping, shapeDefaults, decimalSymbol, and listSeparator, so
+      // anchor before the earliest of those; append before </w:settings> only
+      // when none are present.
       const modernBlock = CompatibilityUpgrader.buildModernCompatBlock(MODERN_COMPAT_SETTINGS);
-      const xml = settingsXml.replace(/<\/w:settings>/, modernBlock + '\n</w:settings>');
+      const followingSibling =
+        /<(?:w:rsids|m:mathPr|w:themeFontLang|w:clrSchemeMapping|w:shapeDefaults|w:decimalSymbol|w:listSeparator)[\s/>]/.exec(
+          settingsXml
+        );
+      const xml = followingSibling
+        ? settingsXml.slice(0, followingSibling.index) +
+          modernBlock +
+          '\n  ' +
+          settingsXml.slice(followingSibling.index)
+        : settingsXml.replace(/<\/w:settings>/, modernBlock + '\n</w:settings>');
 
       for (const s of MODERN_COMPAT_SETTINGS) {
         addedSettings.push(s.name);