docxmlater 10.4.1 → 11.0.4

package/src/tracking/DocumentTrackingContext.ts

@@ -7,16 +7,17 @@
  * @module DocumentTrackingContext
  */
 
-import { Revision, RevisionType } from '../elements/Revision';
-import { RevisionManager } from '../elements/RevisionManager';
-import { Run, type RunFormatting } from '../elements/Run';
-import { Paragraph } from '../elements/Paragraph';
-import { Table } from '../elements/Table';
-import { TableRow } from '../elements/TableRow';
-import { TableCell } from '../elements/TableCell';
-import { Section } from '../elements/Section';
-import type { TrackingContext, PendingChange, TrackableElement } from './TrackingContext';
-import { formatDateForXml } from '../utils/dateFormatting';
+import { Revision, RevisionType } from '../elements/Revision.js';
+import { RevisionManager } from '../elements/RevisionManager.js';
+import { Run, type RunFormatting } from '../elements/Run.js';
+import { Paragraph } from '../elements/Paragraph.js';
+import { Table } from '../elements/Table.js';
+import { TableRow } from '../elements/TableRow.js';
+import { TableCell } from '../elements/TableCell.js';
+import { Section } from '../elements/Section.js';
+import type { TrackingContext, PendingChange, TrackableElement } from './TrackingContext.js';
+import { formatDateForXml } from '../utils/dateFormatting.js';
+import { deepEqual } from '../utils/deepEqual.js';
 
 /**
  * Enable options for tracking context
@@ -684,10 +685,7 @@ export class DocumentTrackingContext implements TrackingContext {
    * Deep equality check for tracking values (handles objects, primitives, null/undefined)
    */
   private valuesEqual(a: unknown, b: unknown): boolean {
-    if (a === b) return true;
-    if (a == null || b == null) return false;
-    if (typeof a !== 'object' || typeof b !== 'object') return false;
-    return JSON.stringify(a) === JSON.stringify(b);
+    return deepEqual(a, b);
   }
 
   /**

package/src/tracking/TrackingContext.ts

@@ -7,14 +7,14 @@
  * @module TrackingContext
  */
 
-import type { Revision, RevisionType } from '../elements/Revision';
-import type { RevisionManager } from '../elements/RevisionManager';
-import type { Run } from '../elements/Run';
-import type { Paragraph } from '../elements/Paragraph';
-import type { Table } from '../elements/Table';
-import type { TableRow } from '../elements/TableRow';
-import type { TableCell } from '../elements/TableCell';
-import type { Section } from '../elements/Section';
+import type { Revision, RevisionType } from '../elements/Revision.js';
+import type { RevisionManager } from '../elements/RevisionManager.js';
+import type { Run } from '../elements/Run.js';
+import type { Paragraph } from '../elements/Paragraph.js';
+import type { Table } from '../elements/Table.js';
+import type { TableRow } from '../elements/TableRow.js';
+import type { TableCell } from '../elements/TableCell.js';
+import type { Section } from '../elements/Section.js';
 
 /** Union of element types that can be tracked */
 export type TrackableElement =

package/src/types/document-types.ts

@@ -0,0 +1,53 @@
+/**
+ * Document-shaped types extracted out of `src/core/Document.ts` so that
+ * `DocumentParser`, `DocumentGenerator`, and `DocumentValidator` can
+ * import them without re-introducing a circular dependency back to the
+ * Document class.
+ *
+ * `Document.ts` re-exports these for backward compatibility — existing
+ * `import { DocumentProperties } from 'docxmlater'` continues to work.
+ */
+
+/** Document properties (core and extended). */
+export interface DocumentProperties {
+  // Core Properties (docProps/core.xml)
+  title?: string;
+  subject?: string;
+  creator?: string;
+  keywords?: string;
+  description?: string;
+  lastModifiedBy?: string;
+  revision?: number;
+  created?: Date;
+  modified?: Date;
+  language?: string;
+  category?: string;
+  contentStatus?: string;
+
+  // Extended Properties (docProps/app.xml)
+  application?: string;
+  appVersion?: string;
+  company?: string;
+  manager?: string;
+  version?: string;
+
+  // Custom Properties (docProps/custom.xml)
+  customProperties?: Record<string, string | number | boolean | Date>;
+}
+
+/**
+ * Document part representation. Any part inside the DOCX package
+ * (XML, binary).
+ */
+export interface DocumentPart {
+  /** Part name/path within the package */
+  name: string;
+  /** Part content (string for XML/text, Buffer for binary) */
+  content: string | Buffer;
+  /** MIME content type */
+  contentType?: string;
+  /** Whether the part is binary */
+  isBinary?: boolean;
+  /** Part size in bytes */
+  size?: number;
+}

package/src/types/formatting.ts

@@ -3,8 +3,8 @@
  */
 
 // Forward references to avoid circular dependencies
-import type { Paragraph } from '../elements/Paragraph';
-import type { Run } from '../elements/Run';
+import type { Paragraph } from '../elements/Paragraph.js';
+import type { Run } from '../elements/Run.js';
 
 /**
  * Border style options
@@ -45,13 +45,13 @@ export interface ParagraphBorder {
  * Shading patterns — re-exported from CommonTypes for backward compatibility.
  * @see CommonTypes.ShadingPattern for the canonical definition
  */
-export type { ShadingPattern } from '../elements/CommonTypes';
+export type { ShadingPattern } from '../elements/CommonTypes.js';
 
 /**
  * Paragraph shading configuration — re-exported from CommonTypes for backward compatibility.
  * @see CommonTypes.ShadingConfig for the canonical definition (includes theme attributes)
  */
-export type { ShadingConfig as ParagraphShading } from '../elements/CommonTypes';
+export type { ShadingConfig as ParagraphShading } from '../elements/CommonTypes.js';
 
 /**
  * Tab stop alignment

package/src/types/settings-types.ts

@@ -11,6 +11,14 @@
 export interface DocumentProtection {
   edit: 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
   enforcement: boolean;
+  /**
+   * `w:formatting` per CT_DocProtect §17.15.1.29 — when true, formatting
+   * changes are still allowed even when edit protection is enforced.
+   * Directly relevant to the tracked-changes workflow: combined with
+   * `edit: 'trackedChanges'`, this forces all content edits to be tracked
+   * while still permitting formatting adjustments.
+   */
+  formatting?: boolean;
   cryptProviderType?: string;
   cryptAlgorithmClass?: string;
   cryptAlgorithmType?: string;
@@ -18,6 +26,19 @@ export interface DocumentProtection {
   cryptSpinCount?: number;
   hash?: string;
   salt?: string;
+  /**
+   * Modern crypto attributes per ISO/IEC 29500-4 §13 (Word 2013+):
+   * - `algorithmName` names the strong hash algorithm (e.g. "SHA-512"),
+   *   replacing the legacy `cryptAlgorithmSid` lookup-table reference.
+   * - `hashValue` is the base64-encoded password hash.
+   * - `saltValue` is the base64-encoded salt.
+   *
+   * These are emitted alongside / instead of the legacy `hash` / `salt`
+   * / `cryptAlgorithmSid` attributes. Previously dropped on round-trip.
+   */
+  algorithmName?: string;
+  hashValue?: string;
+  saltValue?: string;
 }
 
 /**
@@ -27,6 +48,17 @@ export interface RevisionViewSettings {
   showInsertionsAndDeletions: boolean;
   showFormatting: boolean;
   showInkAnnotations: boolean;
+  /**
+   * `w:markup` per CT_TrackChangesView §17.15.1.77 — when false, all
+   * revision markup is hidden in the reviewer pane (no balloons, no
+   * strikethrough/inserted styling). Defaults to true when absent.
+   */
+  showMarkup?: boolean;
+  /**
+   * `w:comments` per CT_TrackChangesView §17.15.1.77 — when false,
+   * comment balloons are hidden. Defaults to true when absent.
+   */
+  showComments?: boolean;
 }
 
 /**

package/src/utils/KeyedRegistry.ts

@@ -0,0 +1,41 @@
+/**
+ * Map-backed keyed registry shared by ElementRegistry and ValidationRuleRegistry.
+ * Throws on duplicate `register()` so callers cannot silently overwrite a
+ * pre-existing entry.
+ */
+export class KeyedRegistry<V> {
+  private readonly entries = new Map<string, V>();
+
+  constructor(private readonly label: string) {}
+
+  register(key: string, value: V): void {
+    if (this.entries.has(key)) {
+      throw new Error(`${this.label}: "${key}" is already registered`);
+    }
+    this.entries.set(key, value);
+  }
+
+  unregister(key: string): boolean {
+    return this.entries.delete(key);
+  }
+
+  has(key: string): boolean {
+    return this.entries.has(key);
+  }
+
+  get(key: string): V | undefined {
+    return this.entries.get(key);
+  }
+
+  keys(): string[] {
+    return [...this.entries.keys()];
+  }
+
+  values(): V[] {
+    return [...this.entries.values()];
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}

package/src/utils/corruptionDetection.ts

@@ -6,8 +6,8 @@
  * results in escaped XML tags being displayed as literal text in Word.
  */
 
-import { Paragraph } from '../elements/Paragraph';
-import { Run } from '../elements/Run';
+import { Paragraph } from '../elements/Paragraph.js';
+import { Run } from '../elements/Run.js';
 
 /** Minimal interface for document corruption scanning (avoids circular import) */
 interface DocumentLike {

package/src/utils/deepEqual.ts

@@ -0,0 +1,58 @@
+/**
+ * Structural equality check for OOXML formatting objects.
+ *
+ * Replaces `JSON.stringify(a) === JSON.stringify(b)` in hot equality paths
+ * (paragraph property merging, tracking-context consolidation). Avoids
+ * allocating two large strings per comparison and short-circuits on the
+ * first inequality.
+ *
+ * Handles the value shapes seen in formatting objects: primitives, plain
+ * objects, arrays, Date, null/undefined. Symbols and class instances are
+ * not part of the formatting model and are compared by reference.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  // NaN === NaN is false in JS; treat structurally as equal so a parse
+  // failure that produced two NaNs in equivalent slots doesn't dirty the
+  // tracking-context consolidation pass.
+  if (typeof a === 'number' && typeof b === 'number' && Number.isNaN(a) && Number.isNaN(b)) {
+    return true;
+  }
+  if (a == null || b == null) return a === b;
+
+  const typeA = typeof a;
+  const typeB = typeof b;
+  if (typeA !== typeB) return false;
+  if (typeA !== 'object') return false;
+
+  // Date values
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  }
+
+  // Arrays: same length, element-wise equality.
+  const aIsArr = Array.isArray(a);
+  const bIsArr = Array.isArray(b);
+  if (aIsArr !== bIsArr) return false;
+  if (aIsArr && bIsArr) {
+    const arrA = a;
+    const arrB = b;
+    if (arrA.length !== arrB.length) return false;
+    for (let i = 0; i < arrA.length; i++) {
+      if (!deepEqual(arrA[i], arrB[i])) return false;
+    }
+    return true;
+  }
+
+  // Plain objects: same key set, deep-equal values.
+  const objA = a as Record<string, unknown>;
+  const objB = b as Record<string, unknown>;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  for (const k of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(objB, k)) return false;
+    if (!deepEqual(objA[k], objB[k])) return false;
+  }
+  return true;
+}

package/src/utils/list-detection.ts

@@ -5,13 +5,13 @@
  * paragraph list properties.
  */
 
-import type { Paragraph } from '../elements/Paragraph';
+import type { Paragraph } from '../elements/Paragraph.js';
 import type {
   ListCategory,
   ListDetectionResult,
   NumberFormat,
   BulletFormat,
-} from '../types/list-types';
+} from '../types/list-types.js';
 
 // =============================================================================
 // CONSTANTS

package/src/utils/parsingHelpers.ts

@@ -54,6 +54,10 @@ export function safeParseInt(value: unknown, defaultValue = 0): number {
  * - Absent element = false (handled by caller checking for property existence)
  *
  * @param prop - The parsed XML property object (e.g., pPrObj["w:bold"])
+ * @param valAttr - The attribute key that carries the ST_OnOff literal.
+ *   Defaults to `"@_w:val"` for the main WordprocessingML namespace.
+ *   Pass `"@_w14:val"` for w14 extension elements such as
+ *   `<w14:checked w14:val="1"/>` (CT_OnOff in the Word 2010+ namespace).
  * @returns Boolean value
  *
  * @example
@@ -66,17 +70,21 @@ export function safeParseInt(value: unknown, defaultValue = 0): number {
  * // For XML: <w:bold w:val="0"/>
  * parseOoxmlBoolean({ "@_w:val": "0" }) // false
  *
+ * // For XML: <w14:checked w14:val="on"/>
+ * parseOoxmlBoolean({ "@_w14:val": "on" }, "@_w14:val") // true
+ *
  * // For absent element
  * parseOoxmlBoolean(undefined) // false
  */
-export function parseOoxmlBoolean(prop: unknown): boolean {
+export function parseOoxmlBoolean(prop: unknown, valAttr = '@_w:val'): boolean {
   // Absent element = false
   if (!prop) {
     return false;
   }
 
-  // Get the w:val attribute value
-  const val = (prop as Record<string, unknown>)['@_w:val'];
+  // Get the val attribute value (w:val by default, w14:val or similar for
+  // extension namespaces).
+  const val = (prop as Record<string, unknown>)[valAttr];
 
   // Self-closing tag without w:val attribute = true
   // Per ECMA-376, presence of element without val means "on"

package/src/utils/validation.ts

@@ -2,9 +2,9 @@
  * Validation utilities for DOCX files
  */
 
-import { REQUIRED_DOCX_FILES } from '../zip/types';
-import { MissingRequiredFileError } from '../zip/errors';
-import { defaultLogger } from './logger';
+import { REQUIRED_DOCX_FILES } from '../zip/types.js';
+import { MissingRequiredFileError } from '../zip/errors.js';
+import { defaultLogger } from './logger.js';
 
 /**
  * Validates that all required DOCX files are present

package/src/utils/xmlSanitization.ts

@@ -18,7 +18,7 @@
  * @module xmlSanitization
  */
 
-import { getGlobalLogger } from './logger';
+import { getGlobalLogger } from './logger.js';
 
 /**
  * Regular expression matching invalid XML 1.0 control characters.

package/src/validation/RevisionAutoFixer.ts

@@ -7,17 +7,17 @@
  * @module RevisionAutoFixer
  */
 
-import type { Document } from '../core/Document';
-import type { Revision } from '../elements/Revision';
-import type { RevisionManager } from '../elements/RevisionManager';
+import type { Document } from '../core/Document.js';
+import type { Revision } from '../elements/Revision.js';
+import type { RevisionManager } from '../elements/RevisionManager.js';
 import {
   REVISION_RULES,
   AutoFixOptions,
   AutoFixResult,
   FixAction,
   ValidationIssue,
-} from './ValidationRules';
-import { RevisionValidator } from './RevisionValidator';
+} from './ValidationRules.js';
+import { RevisionValidator } from './RevisionValidator.js';
 
 /**
  * Automatically fixes revision validation issues.

package/src/validation/RevisionValidator.ts

@@ -7,15 +7,16 @@
  * @module RevisionValidator
  */
 
-import type { Document } from '../core/Document';
-import type { Revision } from '../elements/Revision';
+import type { Document } from '../core/Document.js';
+import type { Revision } from '../elements/Revision.js';
 import {
   REVISION_RULES,
   ValidationIssue,
   ValidationOptions,
   ValidationResult,
   createIssueFromRule,
-} from './ValidationRules';
+} from './ValidationRules.js';
+import { ValidationRuleRegistry } from './ValidationRuleRegistry.js';
 
 /**
  * Validates document revisions for ECMA-376 compliance.
@@ -41,12 +42,18 @@ export class RevisionValidator {
    */
   static validate(doc: Document, options?: ValidationOptions): ValidationResult {
     const revisionManager = doc.getRevisionManager();
+    const allIssues: ValidationIssue[] = [];
+
+    // Custom rules from ValidationRuleRegistry run regardless of whether
+    // the document has a revision manager — they validate document-level
+    // properties, not just revisions.
+    allIssues.push(...this.runCustomRules(doc));
+
     if (!revisionManager) {
-      return this.createEmptyResult();
+      return this.finalize(allIssues, options);
     }
 
     const revisions = revisionManager.getAllRevisions();
-    const allIssues: ValidationIssue[] = [];
 
     // Skip certain rules if lenient mode
     const skipRules = new Set(options?.skipRules || []);
@@ -82,16 +89,40 @@ export class RevisionValidator {
       allIssues.push(...this.validateRevisionDates(revisions));
     }
 
-    // Apply max issues limit
+    return this.finalize(allIssues, options);
+  }
+
+  /**
+   * Run every rule in `ValidationRuleRegistry` against `doc` and convert
+   * the produced `CustomValidationIssue`s into the built-in
+   * `ValidationIssue` shape so they can be merged into the final result.
+   */
+  private static runCustomRules(doc: Document): ValidationIssue[] {
+    const customIssues = ValidationRuleRegistry.runAll(doc);
+    return customIssues.map((c) => ({
+      code: c.ruleCode,
+      severity: c.severity,
+      message: c.message,
+      location: c.location ? { element: c.location } : undefined,
+      autoFixable: false,
+    }));
+  }
+
+  /**
+   * Apply maxIssues / warningsAsErrors options and bucket the issues
+   * into the standard `ValidationResult` shape.
+   */
+  private static finalize(
+    allIssues: ValidationIssue[],
+    options?: ValidationOptions
+  ): ValidationResult {
     const limitedIssues = options?.maxIssues ? allIssues.slice(0, options.maxIssues) : allIssues;
 
-    // Separate by severity
     let errors = limitedIssues.filter((i) => i.severity === 'error');
     let warnings = limitedIssues.filter((i) => i.severity === 'warning');
     const infos = limitedIssues.filter((i) => i.severity === 'info');
     const autoFixable = limitedIssues.filter((i) => i.autoFixable);
 
-    // Handle warningsAsErrors option
     if (options?.warningsAsErrors) {
       errors = [...errors, ...warnings];
       warnings = [];
@@ -113,26 +144,6 @@ export class RevisionValidator {
     };
   }
 
-  /**
-   * Creates an empty validation result (for documents with no revisions).
-   */
-  private static createEmptyResult(): ValidationResult {
-    return {
-      valid: true,
-      errors: [],
-      warnings: [],
-      infos: [],
-      autoFixable: [],
-      summary: {
-        totalIssues: 0,
-        errorCount: 0,
-        warningCount: 0,
-        infoCount: 0,
-        autoFixableCount: 0,
-      },
-    };
-  }
-
   /**
    * Validates revision ID uniqueness.
    *

package/src/validation/ValidationRuleRegistry.ts

@@ -0,0 +1,86 @@
+/**
+ * Plugin extension point for custom validation rules. Built-in rules
+ * live in `ValidationRules.ts`; this registry lets consumers add their
+ * own without modifying framework code. Custom rules run alongside the
+ * built-ins when `RevisionValidator.validate()` executes — the validator
+ * appends `runAll()` issues to its `infos`/`warnings`/`errors` buckets
+ * based on each rule's declared severity.
+ */
+import type { Document } from '../core/Document.js';
+import { KeyedRegistry } from '../utils/KeyedRegistry.js';
+
+/**
+ * Severity for custom validation rules. Distinct from the built-in
+ * `ValidationSeverity` enum so the public API surface has no name
+ * collision.
+ */
+export type CustomValidationSeverity = 'error' | 'warning' | 'info';
+
+export interface CustomValidationIssue {
+  ruleCode: string;
+  severity: CustomValidationSeverity;
+  message: string;
+  /** Optional element identifier or path for navigation in tooling. */
+  location?: string;
+}
+
+export interface CustomValidationRule {
+  /** Unique rule identifier — must not collide with built-in rule codes. */
+  code: string;
+  /** Human-readable description of what the rule checks. */
+  description: string;
+  severity: CustomValidationSeverity;
+  /**
+   * Run the rule against a document and return any issues found.
+   * Synchronous — async rules should be wrapped externally.
+   */
+  validate(doc: Document): CustomValidationIssue[];
+}
+
+class ValidationRuleRegistryImpl {
+  private readonly inner = new KeyedRegistry<CustomValidationRule>('ValidationRuleRegistry');
+
+  register(rule: CustomValidationRule): void {
+    this.inner.register(rule.code, rule);
+  }
+
+  unregister(code: string): boolean {
+    return this.inner.unregister(code);
+  }
+
+  has(code: string): boolean {
+    return this.inner.has(code);
+  }
+
+  get(code: string): CustomValidationRule | undefined {
+    return this.inner.get(code);
+  }
+
+  getAll(): CustomValidationRule[] {
+    return this.inner.values();
+  }
+
+  /** Run every registered rule and concatenate the issues. A throwing
+   *  rule is captured as a synthetic 'error' issue so consumers see it. */
+  runAll(doc: Document): CustomValidationIssue[] {
+    const out: CustomValidationIssue[] = [];
+    for (const rule of this.inner.values()) {
+      try {
+        out.push(...rule.validate(doc));
+      } catch {
+        out.push({
+          ruleCode: rule.code,
+          severity: 'error',
+          message: `Rule "${rule.code}" threw during validation`,
+        });
+      }
+    }
+    return out;
+  }
+
+  clear(): void {
+    this.inner.clear();
+  }
+}
+
+export const ValidationRuleRegistry = new ValidationRuleRegistryImpl();

package/src/validation/index.ts

@@ -21,10 +21,10 @@ export {
   getRuleByCode,
   getRulesBySeverity,
   getAutoFixableRules,
-} from './ValidationRules';
+} from './ValidationRules.js';
 
 // Validator class
-export { RevisionValidator } from './RevisionValidator';
+export { RevisionValidator } from './RevisionValidator.js';
 
 // Auto-fixer class
-export { RevisionAutoFixer } from './RevisionAutoFixer';
+export { RevisionAutoFixer } from './RevisionAutoFixer.js';

package/src/xml/XMLBuilder.ts

@@ -3,9 +3,9 @@
  * Provides a simple fluent API for generating WordprocessingML XML
  */
 
-import { removeInvalidXmlChars } from '../utils/xmlSanitization';
-import type { ShadingConfig } from '../elements/CommonTypes';
-import { buildShadingAttributes } from '../elements/CommonTypes';
+import { removeInvalidXmlChars } from '../utils/xmlSanitization.js';
+import type { ShadingConfig } from '../elements/CommonTypes.js';
+import { buildShadingAttributes } from '../elements/CommonTypes.js';
 
 /** Represents a parsed XML object from XMLParser.parseToObject() */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- parsed XML has dynamic keys and recursive structure
@@ -759,6 +759,11 @@ export class XMLBuilder {
       size?: number;
       color?: string;
       space?: number;
+      themeColor?: string;
+      themeTint?: string;
+      themeShade?: string;
+      shadow?: boolean;
+      frame?: boolean;
     }
   ): XMLElement {
     const attrs = XMLBuilder.buildAttributes({
@@ -766,6 +771,11 @@ export class XMLBuilder {
       'w:sz': border.size,
       'w:color': border.color,
       'w:space': border.space,
+      'w:themeColor': border.themeColor,
+      'w:themeTint': border.themeTint,
+      'w:themeShade': border.themeShade,
+      'w:shadow': border.shadow === undefined ? undefined : border.shadow ? '1' : '0',
+      'w:frame': border.frame === undefined ? undefined : border.frame ? '1' : '0',
     });
 
     return XMLBuilder.wSelf(side, attrs);

package/src/xml/XMLParser.ts

@@ -4,8 +4,8 @@
  * Completes the DocXML framework (XMLBuilder + XMLParser)
  */
 
-import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger';
-import { XMLBuilder } from './XMLBuilder';
+import { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';
+import { XMLBuilder } from './XMLBuilder.js';
 
 // Create scoped logger for XMLParser operations
 function getLogger(): ILogger {