docxmlater 10.4.1 → 11.0.4

package/src/elements/Hyperlink.ts

@@ -48,11 +48,11 @@
  * @see {@link https://www.ecma-international.org/publications-and-standards/standards/ecma-376/ | ECMA-376 Part 1 §17.16.22}
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
-import { Run, RunFormatting } from './Run';
-import { Revision } from './Revision';
-import { validateRunText, sanitizeHyperlinkUrl } from '../utils/validation';
-import { defaultLogger } from '../utils/logger';
+import { XMLElement } from '../xml/XMLBuilder.js';
+import { Run, RunFormatting } from './Run.js';
+import { Revision } from './Revision.js';
+import { validateRunText, sanitizeHyperlinkUrl } from '../utils/validation.js';
+import { defaultLogger } from '../utils/logger.js';
 
 /**
  * Hyperlink properties
@@ -100,9 +100,9 @@ export class Hyperlink {
   /** Document location for within-document navigation in external files */
   private docLocation?: string;
   /** Tracking context for automatic change tracking */
-  private trackingContext?: import('../tracking/TrackingContext').TrackingContext;
+  private trackingContext?: import('../tracking/TrackingContext.js').TrackingContext;
   /** Parent paragraph reference for automatic tracking */
-  private _parentParagraph?: import('./Paragraph').Paragraph;
+  private _parentParagraph?: import('./Paragraph.js').Paragraph;
   /** Baseline formatting captured before first tracked formatting change */
   private _preTrackingFormatting?: RunFormatting;
 
@@ -176,7 +176,7 @@ export class Hyperlink {
    * Called by Document when track changes is enabled.
    * @internal
    */
-  _setTrackingContext(context: import('../tracking/TrackingContext').TrackingContext): void {
+  _setTrackingContext(context: import('../tracking/TrackingContext.js').TrackingContext): void {
     this.trackingContext = context;
   }
 
@@ -185,7 +185,7 @@ export class Hyperlink {
    * Called by Paragraph when hyperlink is added.
    * @internal
    */
-  _setParentParagraph(paragraph: import('./Paragraph').Paragraph): void {
+  _setParentParagraph(paragraph: import('./Paragraph.js').Paragraph): void {
     this._parentParagraph = paragraph;
   }
 
@@ -193,7 +193,7 @@ export class Hyperlink {
    * Gets the parent paragraph reference.
    * @internal
    */
-  _getParentParagraph(): import('./Paragraph').Paragraph | undefined {
+  _getParentParagraph(): import('./Paragraph.js').Paragraph | undefined {
     return this._parentParagraph;
   }
 
@@ -1208,8 +1208,12 @@ export class Hyperlink {
       attributes['w:tgtFrame'] = this.tgtFrame;
     }
 
-    // History tracking attribute
-    if (this.history) {
+    // History tracking attribute (CT_OnOff per ECMA-376 §17.16.22).
+    // Use `!== undefined` rather than a truthy check so explicit "0" /
+    // "false" / "off" overrides survive round-trip — the parser
+    // normalises to "1"/"0", but external callers may still set any
+    // ST_OnOff literal.
+    if (this.history !== undefined) {
       attributes['w:history'] = this.history;
     }
 

package/src/elements/Image.ts

@@ -6,9 +6,9 @@
  */
 
 import { promises as fs } from 'fs';
-import { defaultLogger } from '../utils/logger';
-import { inchesToEmus, UNITS } from '../utils/units';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { defaultLogger } from '../utils/logger.js';
+import { inchesToEmus, UNITS } from '../utils/units.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Supported image formats

package/src/elements/ImageManager.ts

@@ -5,8 +5,8 @@
  * with the RelationshipManager for image relationships.
  */
 
-import { Image } from './Image';
-import { defaultLogger } from '../utils/logger';
+import { Image } from './Image.js';
+import { defaultLogger } from '../utils/logger.js';
 
 /**
  * Image file entry

package/src/elements/ImageRun.ts

@@ -6,9 +6,9 @@
  * It generates proper w:r (run) XML with w:drawing child element.
  */
 
-import { Run } from './Run';
-import { Image } from './Image';
-import { XMLElement } from '../xml/XMLBuilder';
+import { Run } from './Run.js';
+import { Image } from './Image.js';
+import { XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * ImageRun - A run containing an embedded image

package/src/elements/MathElement.ts

@@ -8,7 +8,7 @@
  * internal structure (fractions, radicals, matrices, etc.).
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
+import { XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Block-level math paragraph (m:oMathPara)

package/src/elements/Paragraph.ts

@@ -3,18 +3,20 @@
  * Contains one or more runs of formatted text
  */
 
-import { deepClone } from '../utils/deepClone';
-import { formatDateForXml } from '../utils/dateFormatting';
-import { logParagraphContent, logTextDirection } from '../utils/diagnostics';
-import { isEqualFormatting } from '../utils/formatting';
-import { defaultLogger } from '../utils/logger';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-import { Bookmark } from './Bookmark';
-import type { Comment } from './Comment';
+import { deepClone } from '../utils/deepClone.js';
+import { deepEqual } from '../utils/deepEqual.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
+import { logParagraphContent, logTextDirection } from '../utils/diagnostics.js';
+import { isEqualFormatting } from '../utils/formatting.js';
+import { defaultLogger } from '../utils/logger.js';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder.js';
+import { Bookmark } from './Bookmark.js';
+import type { Comment } from './Comment.js';
 import {
   // Import common types
   ParagraphAlignment as CommonParagraphAlignment,
   BorderStyle as CommonBorderStyle,
+  FullBorderStyle as CommonFullBorderStyle,
   BasicShadingPattern,
   TabAlignment as CommonTabAlignment,
   TabLeader as CommonTabLeader,
@@ -22,15 +24,15 @@ import {
   TextVerticalAlignment,
   ShadingConfig,
   buildShadingAttributes,
-} from './CommonTypes';
-import { ComplexField, Field } from './Field';
-import { Hyperlink } from './Hyperlink';
-import { RangeMarker } from './RangeMarker';
-import { Revision } from './Revision';
-import { Run, RunFormatting } from './Run';
-import { Shape } from './Shape';
-import { TextBox } from './TextBox';
-import { PreservedElement } from './PreservedElement';
+} from './CommonTypes.js';
+import { ComplexField, Field } from './Field.js';
+import { Hyperlink } from './Hyperlink.js';
+import { RangeMarker } from './RangeMarker.js';
+import { Revision } from './Revision.js';
+import { Run, RunFormatting } from './Run.js';
+import { Shape } from './Shape.js';
+import { TextBox } from './TextBox.js';
+import { PreservedElement } from './PreservedElement.js';
 
 // ============================================================================
 // RE-EXPORTED TYPES (for backward compatibility)
@@ -126,8 +128,12 @@ export interface FrameProperties {
   y?: number;
   /** Relative horizontal alignment */
   xAlign?: 'left' | 'center' | 'right' | 'inside' | 'outside';
-  /** Relative vertical alignment */
-  yAlign?: 'top' | 'center' | 'bottom' | 'inside' | 'outside';
+  /**
+   * Relative vertical alignment per ECMA-376 Part 1 §17.18.110 ST_YAlign.
+   * `inline` anchors the frame in line with the surrounding text rather
+   * than offsetting it vertically.
+   */
+  yAlign?: 'top' | 'center' | 'bottom' | 'inline' | 'inside' | 'outside';
   /** Horizontal anchor/positioning base */
   hAnchor?: 'page' | 'margin' | 'text';
   /** Vertical anchor/positioning base */
@@ -147,17 +153,30 @@ export interface FrameProperties {
 }
 
 /**
- * Single border definition
+ * Single paragraph-border definition. `style` uses FullBorderStyle (25+
+ * ST_Border values per ECMA-376 §17.18.2) — paragraph borders support
+ * the full multi-line-gap / triple / inset / outset set, not just the
+ * narrow 6-value BorderStyle subset that this field previously used.
  */
 export interface BorderDefinition {
-  /** Border style */
-  style?: BorderStyle;
+  /** Border style (full ST_Border enumeration) */
+  style?: CommonFullBorderStyle;
   /** Border width in eighths of a point (1-96) */
   size?: number;
   /** Border color (hex without #) */
   color?: string;
   /** Space between border and text in points (0-31) */
   space?: number;
+  /** Theme color reference (ST_ThemeColor per §17.18.97) */
+  themeColor?: string;
+  /** Theme tint (2-hex-digit string) */
+  themeTint?: string;
+  /** Theme shade (2-hex-digit string) */
+  themeShade?: string;
+  /** Border casts a shadow (ST_OnOff attribute on CT_Border §17.18.2) */
+  shadow?: boolean;
+  /** Border is part of a frame around the content (ST_OnOff) */
+  frame?: boolean;
 }
 
 /**
@@ -184,6 +203,18 @@ export interface ParagraphFormatting {
     right?: number;
     firstLine?: number;
     hanging?: number;
+    /**
+     * CJK character-unit indentation attributes per ECMA-376 §17.3.1.12.
+     * Values are in hundredths of a character unit (200 = 2 character widths).
+     * Used alongside (not instead of) the twips attributes: Word authors
+     * specify one or the other based on document language, and both are
+     * preserved on round-trip so downstream consumers keep the author's
+     * original intent.
+     */
+    leftChars?: number;
+    rightChars?: number;
+    firstLineChars?: number;
+    hangingChars?: number;
   };
   /** Spacing per ECMA-376 §17.3.1.33 (CT_Spacing) */
   spacing?: {
@@ -278,6 +309,19 @@ export interface ParagraphFormatting {
   pPrChange?: ParagraphPropertiesChange;
   /** Run properties for the paragraph mark (¶ symbol formatting) */
   paragraphMarkRunProperties?: RunFormatting;
+  /**
+   * Paragraph mark run-properties change tracking (w:rPrChange inside
+   * <w:pPr><w:rPr>), per ECMA-376 Part 1 §17.3.1.30 / CT_ParaRPrChange.
+   * Stores the previous rPr of the pilcrow glyph when its formatting has
+   * been modified under track changes. Emitted as the LAST child of the
+   * paragraph-mark <w:rPr> per CT_ParaRPr schema.
+   */
+  paragraphMarkRunPropertiesChange?: {
+    id: number;
+    author: string;
+    date: Date;
+    previousProperties: Partial<RunFormatting>;
+  };
   /** Paragraph mark deletion tracking (for deleted ¶ symbols) */
   paragraphMarkDeletion?: {
     /** Unique revision ID */
@@ -412,11 +456,11 @@ export class Paragraph {
   /** Internal flag to mark paragraph as preserved from removal operations */
   private _isPreserved = false;
   /** Tracking context for automatic change tracking */
-  private trackingContext?: import('../tracking/TrackingContext').TrackingContext;
+  private trackingContext?: import('../tracking/TrackingContext.js').TrackingContext;
   /** Parent table cell reference (if paragraph is inside a table cell) */
-  private _parentCell?: import('./TableCell').TableCell;
+  private _parentCell?: import('./TableCell.js').TableCell;
   /** StylesManager reference for conditional formatting resolution */
-  private _stylesManager?: import('../formatting/StylesManager').StylesManager;
+  private _stylesManager?: import('../formatting/StylesManager.js').StylesManager;
   /**
    * Internal flag to mark paragraph as part of a multi-paragraph field (e.g., TOC)
    * When true, assembleComplexFields() will skip processing this paragraph
@@ -438,7 +482,7 @@ export class Paragraph {
    * Called by Document when track changes is enabled.
    * @internal
    */
-  _setTrackingContext(context: import('../tracking/TrackingContext').TrackingContext): void {
+  _setTrackingContext(context: import('../tracking/TrackingContext.js').TrackingContext): void {
     this.trackingContext = context;
   }
 
@@ -447,7 +491,7 @@ export class Paragraph {
    * Called by TableCell when adding paragraphs.
    * @internal
    */
-  _setParentCell(cell: import('./TableCell').TableCell | undefined): void {
+  _setParentCell(cell: import('./TableCell.js').TableCell | undefined): void {
     this._parentCell = cell;
   }
 
@@ -455,7 +499,7 @@ export class Paragraph {
    * Gets the parent cell reference for this paragraph.
    * @internal
    */
-  _getParentCell(): import('./TableCell').TableCell | undefined {
+  _getParentCell(): import('./TableCell.js').TableCell | undefined {
     return this._parentCell;
   }
 
@@ -489,7 +533,7 @@ export class Paragraph {
    * Called by Document/Table when adding paragraphs.
    * @internal
    */
-  _setStylesManager(manager: import('../formatting/StylesManager').StylesManager): void {
+  _setStylesManager(manager: import('../formatting/StylesManager.js').StylesManager): void {
     this._stylesManager = manager;
   }
 
@@ -497,7 +541,7 @@ export class Paragraph {
    * Gets the StylesManager reference for conditional formatting resolution.
    * @internal
    */
-  _getStylesManager(): import('../formatting/StylesManager').StylesManager | undefined {
+  _getStylesManager(): import('../formatting/StylesManager.js').StylesManager | undefined {
     return this._stylesManager;
   }
 
@@ -3169,15 +3213,25 @@ export class Paragraph {
         border: BorderDefinition | undefined
       ): XMLElement | null => {
         if (!border) return null;
-        const attributes: Record<string, string | number> = {};
-        if (border.style) attributes['w:val'] = border.style;
+        // CT_Border §17.18.2: `w:val` (ST_Border) is REQUIRED. Default to
+        // "nil" (the "no visible border" sentinel) when the consumer set
+        // only size/color/space — otherwise strict OOXML validators reject
+        // the document with "The required attribute 'val' is missing".
+        const attributes: Record<string, string | number> = {
+          'w:val': border.style ?? 'nil',
+        };
         if (border.size !== undefined) attributes['w:sz'] = border.size;
         if (border.color) attributes['w:color'] = border.color;
         if (border.space !== undefined) attributes['w:space'] = border.space;
-        if (Object.keys(attributes).length > 0) {
-          return XMLBuilder.wSelf(borderType, attributes);
-        }
-        return null;
+        // Full CT_Border attribute set (§17.18.2): themeColor / themeTint /
+        // themeShade / shadow / frame. Round-trips themed paragraph borders
+        // authored by Word — previously all five were silently stripped.
+        if (border.themeColor) attributes['w:themeColor'] = border.themeColor;
+        if (border.themeTint) attributes['w:themeTint'] = border.themeTint;
+        if (border.themeShade) attributes['w:themeShade'] = border.themeShade;
+        if (border.shadow !== undefined) attributes['w:shadow'] = border.shadow ? '1' : '0';
+        if (border.frame !== undefined) attributes['w:frame'] = border.frame ? '1' : '0';
+        return XMLBuilder.wSelf(borderType, attributes);
       };
 
       // Add borders in order: top, left, bottom, right, between, bar
@@ -3212,13 +3266,18 @@ export class Paragraph {
       }
     }
 
-    // 11. Tab stops
+    // 11. Tab stops. CT_TabStop §17.3.1.37 declares BOTH `w:val` (ST_TabJc)
+    // and `w:pos` (ST_SignedTwipsMeasure) as REQUIRED attributes. Default
+    // `w:val` to "left" (ST_TabJc default and Word's authored default) when
+    // caller didn't specify — otherwise strict OOXML validation rejects
+    // the output with "The required attribute 'val' is missing".
     if (this.formatting.tabs && this.formatting.tabs.length > 0) {
       const tabChildren: XMLElement[] = [];
       for (const tab of this.formatting.tabs) {
-        const attributes: Record<string, string | number> = {};
-        attributes['w:pos'] = tab.position;
-        if (tab.val) attributes['w:val'] = tab.val;
+        const attributes: Record<string, string | number> = {
+          'w:val': tab.val ?? 'left',
+          'w:pos': tab.position,
+        };
         if (tab.leader) attributes['w:leader'] = tab.leader;
         tabChildren.push(XMLBuilder.wSelf('tab', attributes));
       }
@@ -3301,8 +3360,11 @@ export class Paragraph {
       }
     }
 
-    // 17. Indentation (left/right/firstLine/hanging)
-    // Per ECMA-376 §17.3.1.12, firstLine and hanging are mutually exclusive — hanging takes precedence
+    // 17. Indentation (left/right/firstLine/hanging + CJK character-unit variants)
+    // Per ECMA-376 §17.3.1.12, firstLine and hanging are mutually exclusive —
+    // hanging takes precedence. The *Chars attributes (ST_DecimalNumber, in
+    // hundredths of a character unit) are independent of the twips variants;
+    // Word authors in CJK locales emit them alongside — preserve both on save.
     if (this.formatting.indentation) {
       const ind = this.formatting.indentation;
       const attributes: Record<string, number> = {};
@@ -3313,6 +3375,15 @@ export class Paragraph {
       } else if (ind.firstLine !== undefined) {
         attributes['w:firstLine'] = ind.firstLine;
       }
+      if (ind.leftChars !== undefined) attributes['w:leftChars'] = ind.leftChars;
+      if (ind.rightChars !== undefined) attributes['w:rightChars'] = ind.rightChars;
+      // Same mutual-exclusive treatment: hangingChars wins over firstLineChars
+      // when both are set, mirroring the twips behaviour above.
+      if (ind.hangingChars !== undefined) {
+        attributes['w:hangingChars'] = ind.hangingChars;
+      } else if (ind.firstLineChars !== undefined) {
+        attributes['w:firstLineChars'] = ind.firstLineChars;
+      }
       if (Object.keys(attributes).length > 0) {
         pPrChildren.push(XMLBuilder.wSelf('ind', attributes));
       }
@@ -3397,30 +3468,29 @@ export class Paragraph {
     }
 
     // 19. Paragraph mark run properties per ECMA-376 Part 1 §17.3.1.29
-    // Per CT_PPr, w:rPr comes after all CT_PPrBase elements and before w:sectPr/w:pPrChange
+    // Per CT_PPr, w:rPr comes after all CT_PPrBase elements and before w:sectPr/w:pPrChange.
+    //
+    // CT_ParaRPr content model (ECMA-376 Part 1, Annex A / wml.xsd):
+    //   <xsd:sequence>
+    //     <xsd:group ref="EG_ParaRPrTrackChanges" minOccurs="0"/>   <!-- ins, del, moveFrom, moveTo -->
+    //     <xsd:group ref="EG_RPrBase" minOccurs="0" maxOccurs="unbounded"/>  <!-- rStyle, rFonts, b, bCs, i, ... -->
+    //     <xsd:element name="rPrChange" type="CT_ParaRPrChange" minOccurs="0"/>
+    //   </xsd:sequence>
+    //
+    // The track-change markers (w:ins / w:del) must precede the EG_RPrBase
+    // run-property children. Earlier revisions of this code emitted run
+    // properties first and then ins/del, which is a schema violation — strict
+    // validators reject the inverted order, and tracked-change-aware tools
+    // may misinterpret the revision state of the paragraph mark.
     if (
       this.formatting.paragraphMarkRunProperties ||
       this.formatting.paragraphMarkDeletion ||
-      this.formatting.paragraphMarkInsertion
+      this.formatting.paragraphMarkInsertion ||
+      this.formatting.paragraphMarkRunPropertiesChange
     ) {
       const rPrChildren: XMLElement[] = [];
 
-      // Add run properties for the paragraph mark if they exist
-      if (this.formatting.paragraphMarkRunProperties) {
-        const rPr = Run.generateRunPropertiesXML(this.formatting.paragraphMarkRunProperties);
-        if (rPr?.children) {
-          // Filter to only XMLElement types (children can be XMLElement or string)
-          for (const child of rPr.children) {
-            if (typeof child !== 'string') {
-              rPrChildren.push(child);
-            }
-          }
-        }
-      }
-
-      // Per CT_ParaRPr schema, w:ins precedes w:del in the sequence
-      // Add insertion marker if the paragraph mark is inserted (w:ins)
-      // Per ECMA-376 Part 1 §17.13.5.18 - tracks insertion of paragraph mark
+      // EG_ParaRPrTrackChanges (ins → del → moveFrom → moveTo) — FIRST per CT_ParaRPr.
       if (this.formatting.paragraphMarkInsertion) {
         const ins = this.formatting.paragraphMarkInsertion;
         rPrChildren.push(
@@ -3432,8 +3502,6 @@ export class Paragraph {
         );
       }
 
-      // Add deletion marker if the paragraph mark is deleted (w:del)
-      // Per ECMA-376 Part 1 §17.13.5.14 - tracks deletion of paragraph mark
       if (this.formatting.paragraphMarkDeletion) {
         const del = this.formatting.paragraphMarkDeletion;
         rPrChildren.push(
@@ -3445,6 +3513,44 @@ export class Paragraph {
         );
       }
 
+      // EG_RPrBase run properties — AFTER the track-change markers.
+      if (this.formatting.paragraphMarkRunProperties) {
+        const rPr = Run.generateRunPropertiesXML(this.formatting.paragraphMarkRunProperties);
+        if (rPr?.children) {
+          // Filter to only XMLElement types (children can be XMLElement or string)
+          for (const child of rPr.children) {
+            if (typeof child !== 'string') {
+              rPrChildren.push(child);
+            }
+          }
+        }
+      }
+
+      // <w:rPrChange> (CT_ParaRPrChange, §17.3.1.30) — LAST per CT_ParaRPr.
+      // Contains a single <w:rPr> child with the previous run properties of
+      // the paragraph mark. Reuses Run.generateRunPropertiesXML for full
+      // CT_RPr coverage in the previous-properties block.
+      const paraRPrChange = this.formatting.paragraphMarkRunPropertiesChange;
+      if (paraRPrChange) {
+        const prevRPr = Run.generateRunPropertiesXML(
+          paraRPrChange.previousProperties as RunFormatting
+        );
+        const prevRPrElement: XMLElement = prevRPr ?? {
+          name: 'w:rPr',
+          attributes: {},
+          children: [],
+        };
+        rPrChildren.push({
+          name: 'w:rPrChange',
+          attributes: {
+            'w:id': paraRPrChange.id.toString(),
+            'w:author': paraRPrChange.author,
+            'w:date': formatDateForXml(paraRPrChange.date),
+          },
+          children: [prevRPrElement],
+        });
+      }
+
       // Add w:rPr element if there are any run properties
       if (rPrChildren.length > 0) {
         pPrChildren.push(XMLBuilder.w('rPr', undefined, rPrChildren));
@@ -3583,28 +3689,37 @@ export class Paragraph {
           );
         }
 
-        // 7. suppressLineNumbers
+        // 7. suppressLineNumbers — CT_OnOff. Emit w:val="0" for explicit false so the
+        // tracked "previous" value round-trips losslessly (see main generator line ~3154).
         if (prev.suppressLineNumbers !== undefined) {
-          if (prev.suppressLineNumbers) {
-            prevPPrChildren.push(XMLBuilder.wSelf('suppressLineNumbers'));
-          }
+          prevPPrChildren.push(
+            XMLBuilder.wSelf('suppressLineNumbers', {
+              'w:val': prev.suppressLineNumbers ? '1' : '0',
+            })
+          );
         }
 
-        // 8. pBdr (paragraph borders)
+        // 8. pBdr (paragraph borders) — CT_Border §17.18.2 requires w:val.
+        // Default to "nil" when style undefined so pPrChange's previous
+        // border set round-trips through strict validation. Full CT_Border
+        // attribute set (themeColor/themeTint/themeShade/shadow/frame) is
+        // preserved so Word's themed borders survive tracked-change history.
         if (prev.borders) {
           const borderChildren: XMLElement[] = [];
           const borderSides = ['top', 'left', 'bottom', 'right', 'between', 'bar'] as const;
           for (const side of borderSides) {
             const border = prev.borders[side];
             if (border) {
-              const attrs: Record<string, string> = {};
-              if (border.style) attrs['w:val'] = border.style;
+              const attrs: Record<string, string> = { 'w:val': border.style ?? 'nil' };
               if (border.size !== undefined) attrs['w:sz'] = border.size.toString();
               if (border.color) attrs['w:color'] = border.color;
               if (border.space !== undefined) attrs['w:space'] = border.space.toString();
-              if (Object.keys(attrs).length > 0) {
-                borderChildren.push(XMLBuilder.wSelf(side, attrs));
-              }
+              if (border.themeColor) attrs['w:themeColor'] = border.themeColor;
+              if (border.themeTint) attrs['w:themeTint'] = border.themeTint;
+              if (border.themeShade) attrs['w:themeShade'] = border.themeShade;
+              if (border.shadow !== undefined) attrs['w:shadow'] = border.shadow ? '1' : '0';
+              if (border.frame !== undefined) attrs['w:frame'] = border.frame ? '1' : '0';
+              borderChildren.push(XMLBuilder.wSelf(side, attrs));
             }
           }
           if (borderChildren.length > 0) {
@@ -3620,24 +3735,28 @@ export class Paragraph {
           }
         }
 
-        // 10. tabs
+        // 10. tabs — CT_TabStop §17.3.1.37 requires w:val AND w:pos. Default
+        // w:val to "left" when pPrChange's previous state didn't record one.
         if (prev.tabs && prev.tabs.length > 0) {
           const tabChildren: XMLElement[] = prev.tabs.map((tab) => {
             const tabAttrs: Record<string, string> = {
+              'w:val': tab.val ?? 'left',
               'w:pos': tab.position.toString(),
             };
-            if (tab.val) tabAttrs['w:val'] = tab.val;
             if (tab.leader) tabAttrs['w:leader'] = tab.leader;
             return XMLBuilder.wSelf('tab', tabAttrs);
           });
           prevPPrChildren.push(XMLBuilder.w('tabs', undefined, tabChildren));
         }
 
-        // 11. suppressAutoHyphens
+        // 11. suppressAutoHyphens — CT_OnOff. Emit w:val="0" for explicit false so the
+        // tracked "previous" value round-trips losslessly (see main generator line ~3231).
         if (prev.suppressAutoHyphens !== undefined) {
-          if (prev.suppressAutoHyphens) {
-            prevPPrChildren.push(XMLBuilder.wSelf('suppressAutoHyphens', { 'w:val': '1' }));
-          }
+          prevPPrChildren.push(
+            XMLBuilder.wSelf('suppressAutoHyphens', {
+              'w:val': prev.suppressAutoHyphens ? '1' : '0',
+            })
+          );
         }
 
         // 12. CJK paragraph properties
@@ -3707,17 +3826,31 @@ export class Paragraph {
           }
         }
 
-        // 15. ind (indentation)
+        // 15. ind (indentation + CJK character-unit variants per ECMA-376 §17.3.1.12)
+        // hanging / firstLine are conceptually mutually exclusive (opposite-
+        // direction first-line indents). Mirror the direct paragraph generator's
+        // precedence: hanging wins when both are set. Previously this path emitted
+        // BOTH attributes, producing ambiguous tracked-change history that Word
+        // renders inconsistently across versions.
         if (prev.indentation) {
           const indAttrs: Record<string, string> = {};
-          if (prev.indentation.left !== undefined)
-            indAttrs['w:left'] = prev.indentation.left.toString();
-          if (prev.indentation.right !== undefined)
-            indAttrs['w:right'] = prev.indentation.right.toString();
-          if (prev.indentation.firstLine !== undefined)
-            indAttrs['w:firstLine'] = prev.indentation.firstLine.toString();
-          if (prev.indentation.hanging !== undefined)
-            indAttrs['w:hanging'] = prev.indentation.hanging.toString();
+          const indentation = prev.indentation as Record<string, number | undefined>;
+          if (indentation.left !== undefined) indAttrs['w:left'] = indentation.left.toString();
+          if (indentation.right !== undefined) indAttrs['w:right'] = indentation.right.toString();
+          if (indentation.hanging !== undefined) {
+            indAttrs['w:hanging'] = indentation.hanging.toString();
+          } else if (indentation.firstLine !== undefined) {
+            indAttrs['w:firstLine'] = indentation.firstLine.toString();
+          }
+          if (indentation.leftChars !== undefined)
+            indAttrs['w:leftChars'] = indentation.leftChars.toString();
+          if (indentation.rightChars !== undefined)
+            indAttrs['w:rightChars'] = indentation.rightChars.toString();
+          if (indentation.hangingChars !== undefined) {
+            indAttrs['w:hangingChars'] = indentation.hangingChars.toString();
+          } else if (indentation.firstLineChars !== undefined) {
+            indAttrs['w:firstLineChars'] = indentation.firstLineChars.toString();
+          }
           prevPPrChildren.push(XMLBuilder.wSelf('ind', indAttrs));
         }
 
@@ -5313,7 +5446,7 @@ export class Paragraph {
         const paraValue = this.formatting[propKey];
         const styleValue = styleParagraphFormatting[propKey];
 
-        if (JSON.stringify(paraValue) !== JSON.stringify(styleValue)) {
+        if (!deepEqual(paraValue, styleValue)) {
           conflictingParaProps.push(propKey);
         }
       } else {

package/src/elements/PreservedElement.ts

@@ -7,7 +7,7 @@
  * Examples: w:proofErr, w:permStart, w:permEnd, w:altChunk, w:ruby
  */
 
-import { XMLElement } from '../xml/XMLBuilder';
+import { XMLElement } from '../xml/XMLBuilder.js';
 
 /**
  * Element context where it can appear

package/src/elements/PropertyChangeTypes.ts

@@ -15,8 +15,8 @@
  * @module PropertyChangeTypes
  */
 
-import type { RunFormatting } from './Run';
-import type { ShadingConfig } from './CommonTypes';
+import type { RunFormatting } from './Run.js';
+import type { ShadingConfig } from './CommonTypes.js';
 
 /**
  * Common base for all property change types