docxmlater 10.4.0 → 11.0.4

package/dist/esm/types/document-types.js.map

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

package/dist/esm/types/formatting.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=formatting.js.map

package/dist/esm/types/formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../../../src/types/formatting.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Additional formatting types for enhanced document manipulation\n */\n\n// Forward references to avoid circular dependencies\nimport type { Paragraph } from '../elements/Paragraph.js';\nimport type { Run } from '../elements/Run.js';\n\n/**\n * Border style options\n */\nexport type BorderStyleType = 'single' | 'double' | 'dashed' | 'dotted' | 'triple' | 'none';\n\n/**\n * Individual border configuration\n */\nexport interface BorderStyle {\n  /** Border style */\n  style: BorderStyleType;\n  /** Border width in eighths of a point */\n  width: number;\n  /** Border color in hex format */\n  color: string;\n  /** Space between border and text in points */\n  space?: number;\n}\n\n/**\n * Paragraph border configuration\n */\nexport interface ParagraphBorder {\n  /** Top border */\n  top?: BorderStyle;\n  /** Bottom border */\n  bottom?: BorderStyle;\n  /** Left border */\n  left?: BorderStyle;\n  /** Right border */\n  right?: BorderStyle;\n  /** Apply border between paragraphs */\n  between?: boolean;\n}\n\n/**\n * Shading patterns — re-exported from CommonTypes for backward compatibility.\n * @see CommonTypes.ShadingPattern for the canonical definition\n */\nexport type { ShadingPattern } from '../elements/CommonTypes.js';\n\n/**\n * Paragraph shading configuration — re-exported from CommonTypes for backward compatibility.\n * @see CommonTypes.ShadingConfig for the canonical definition (includes theme attributes)\n */\nexport type { ShadingConfig as ParagraphShading } from '../elements/CommonTypes.js';\n\n/**\n * Tab stop alignment\n */\nexport type TabAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';\n\n/**\n * Tab leader character\n */\nexport type TabLeader = 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';\n\n/**\n * Tab stop configuration\n */\nexport interface TabStop {\n  /** Position in twips from left margin */\n  position: number;\n  /** Tab alignment type */\n  type: TabAlignment;\n  /** Leader character */\n  leader?: TabLeader;\n}\n\n/**\n * Text search options\n */\nexport interface FindOptions {\n  /** Case sensitive search */\n  caseSensitive?: boolean;\n  /** Match whole words only */\n  wholeWord?: boolean;\n  /** Use regular expressions */\n  useRegex?: boolean;\n  /** Include headers and footers */\n  includeHeadersFooters?: boolean;\n  /** Include footnotes and endnotes */\n  includeNotes?: boolean;\n}\n\n/**\n * Text replacement options\n */\nexport interface ReplaceOptions extends FindOptions {\n  /** Maximum number of replacements (0 = unlimited) */\n  maxReplacements?: number;\n  /** Track changes for replacements */\n  trackChanges?: boolean;\n  /** Author for track changes */\n  author?: string;\n}\n\n/**\n * Search result\n */\nexport interface SearchResult {\n  /** The paragraph containing the match */\n  paragraph: Paragraph;\n  /** The run containing the match */\n  run?: Run;\n  /** Match start position in paragraph */\n  startIndex: number;\n  /** Match end position in paragraph */\n  endIndex: number;\n  /** The matched text */\n  match: string;\n}\n\n/**\n * Text emphasis options\n */\nexport type EmphasisType = 'bold' | 'italic' | 'underline';\n\n/**\n * List prefix configuration\n */\nexport interface ListPrefix {\n  /** List format type */\n  format: 'bullet' | 'number';\n  /** Custom style string (e.g., '•', '1.', 'a)') */\n  style: string;\n}\n\n/**\n * Format options for style application\n */\nexport interface FormatOptions {\n  // Text formatting\n  /** Font family name (e.g., 'Arial', 'Verdana') */\n  font?: string;\n  /** Font size in points */\n  size?: number;\n  /** Text color as 6-digit hex (e.g., 'FF0000' for red) */\n  color?: string;\n  /** Text emphasis (bold, italic, underline) */\n  emphasis?: EmphasisType[];\n\n  // Alignment\n  /** Paragraph alignment */\n  alignment?: 'left' | 'right' | 'center' | 'justify';\n\n  // Spacing (in points)\n  /** Space before paragraph in points */\n  spaceAbove?: number;\n  /** Space after paragraph in points */\n  spaceBelow?: number;\n  /** Line spacing in points or multiplier */\n  lineSpacing?: number;\n\n  // Indentation (in inches)\n  /** Left indentation in inches */\n  indentLeft?: number;\n  /** Right indentation in inches */\n  indentRight?: number;\n  /** First line indentation in inches */\n  indentFirst?: number;\n  /** Hanging indentation in inches */\n  indentHanging?: number;\n\n  // Padding (in points) - for table cells\n  /** Top padding in points */\n  paddingTop?: number;\n  /** Bottom padding in points */\n  paddingBottom?: number;\n  /** Left padding in points */\n  paddingLeft?: number;\n  /** Right padding in points */\n  paddingRight?: number;\n\n  // List formatting\n  /** List prefix style */\n  prefixList?: string | ListPrefix;\n\n  // Advanced options\n  /** Border color as 6-digit hex */\n  borderColor?: string;\n  /** Border width in points */\n  borderWidth?: number;\n  /** Background shading color as 6-digit hex */\n  shading?: string;\n  /** Keep with next paragraph */\n  keepWithNext?: boolean;\n  /** Keep lines together */\n  keepLines?: boolean;\n}\n\n/**\n * Options for applying styles to paragraphs\n */\nexport interface StyleApplyOptions {\n  /** Specific paragraphs to apply style to (default: auto-detect) */\n  paragraphs?: Paragraph[];\n  /** Properties to preserve from existing formatting */\n  keepProperties?: string[];\n  /** Custom formatting to apply */\n  format?: FormatOptions;\n}\n"]}

package/dist/esm/types/list-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=list-types.js.map

package/dist/esm/types/list-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-types.js","sourceRoot":"","sources":["../../../src/types/list-types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * List Normalization Types for docxmlater\n *\n * These types support detection and normalization of typed list prefixes\n * to proper Word list formatting.\n */\n\n/** High-level list category */\nexport type ListCategory = 'numbered' | 'bullet' | 'none';\n\n/** Specific number format patterns */\nexport type NumberFormat =\n  | 'decimal' // 1. 2. 3.\n  | 'lowerLetter' // a. b. c.\n  | 'upperLetter' // A. B. C.\n  | 'lowerRoman' // i. ii. iii.\n  | 'upperRoman'; // I. II. III.\n\n/** Specific bullet format patterns */\nexport type BulletFormat =\n  | 'bullet' // • ● ○\n  | 'dash' // - – —\n  | 'arrow'; // ► ▸\n\n/**\n * Result of detecting list type for a single paragraph\n */\nexport interface ListDetectionResult {\n  /** High-level category */\n  category: ListCategory;\n\n  /** True if paragraph has <w:numPr> (real Word list) */\n  isWordList: boolean;\n\n  /** The typed prefix found, e.g., \"1. \", \"a) \", \"• \" */\n  typedPrefix: string | null;\n\n  /** Inferred nesting level based on indentation */\n  inferredLevel: number;\n\n  /** Specific format detected */\n  format: NumberFormat | BulletFormat | null;\n\n  /** If Word list, the numId from <w:numPr> */\n  numId: number | null;\n\n  /** If Word list, the ilvl from <w:numPr> */\n  ilvl: number | null;\n\n  /** Raw indentation in twips for debugging */\n  indentationTwips: number;\n}\n\n/**\n * Analysis of all lists within a scope (cell, table, document)\n */\nexport interface ListAnalysis {\n  /** All analyzed paragraphs with their detection results */\n  paragraphs: {\n    paragraph: unknown; // Paragraph instance - using unknown to avoid circular dep\n    text: string;\n    detection: ListDetectionResult;\n  }[];\n\n  /** True if any typed (non-Word) lists found */\n  hasTypedLists: boolean;\n\n  /** True if any real Word lists found */\n  hasWordLists: boolean;\n\n  /** True if both numbered AND bullet lists present */\n  hasMixedCategories: boolean;\n\n  /** The dominant list type in this scope */\n  majorityCategory: ListCategory;\n\n  /** Count by category */\n  counts: {\n    numbered: number;\n    bullet: number;\n    none: number;\n  };\n\n  /** Recommended action */\n  recommendedAction: 'normalize' | 'none';\n}\n\n/**\n * User-defined indentation level configuration for list normalization\n */\nexport interface IndentationLevel {\n  level: number;\n  textIndent: number; // in inches\n  symbolIndent: number; // in inches\n  bulletChar?: string;\n  numberedFormat?: NumberFormat | string;\n}\n\n/**\n * Options for list normalization\n */\nexport interface ListNormalizationOptions {\n  /** numId to use for numbered lists (from numbering.xml) */\n  numberedStyleNumId?: number;\n\n  /** numId to use for bullet lists (from numbering.xml) */\n  bulletStyleNumId?: number;\n\n  /** Processing scope */\n  scope?: 'cell' | 'table' | 'document';\n\n  /**\n   * If true, convert ALL list items to majority type.\n   * If false, only convert typed lists (preserve existing Word lists).\n   */\n  forceMajority?: boolean;\n\n  /**\n   * If true, preserve original indentation instead of using level defaults.\n   */\n  preserveIndentation?: boolean;\n\n  /**\n   * User-defined indentation settings per list level.\n   * Used to configure symbol indent, text indent, and bullet characters.\n   */\n  indentationLevels?: IndentationLevel[];\n}\n\n/**\n * Report returned after normalization\n */\nexport interface ListNormalizationReport {\n  /** Number of paragraphs successfully normalized */\n  normalized: number;\n\n  /** Number of paragraphs skipped (already correct or non-list) */\n  skipped: number;\n\n  /** Any errors encountered */\n  errors: string[];\n\n  /** The majority category that was applied */\n  appliedCategory: ListCategory;\n\n  /** Detailed per-paragraph results */\n  details: {\n    originalText: string;\n    action: 'normalized' | 'skipped' | 'error';\n    reason?: string;\n  }[];\n}\n"]}

package/dist/esm/types/settings-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings-types.js.map

package/dist/esm/types/settings-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-types.js","sourceRoot":"","sources":["../../../src/types/settings-types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Shared type definitions for document settings (settings.xml)\n *\n * These types are used by both Document.ts (in-memory state) and\n * DocumentGenerator.ts (XML generation) to ensure consistency.\n */\n\n/**\n * Document protection settings per ECMA-376 CT_DocProtect\n */\nexport interface DocumentProtection {\n  edit: 'readOnly' | 'comments' | 'trackedChanges' | 'forms';\n  enforcement: boolean;\n  /**\n   * `w:formatting` per CT_DocProtect §17.15.1.29 — when true, formatting\n   * changes are still allowed even when edit protection is enforced.\n   * Directly relevant to the tracked-changes workflow: combined with\n   * `edit: 'trackedChanges'`, this forces all content edits to be tracked\n   * while still permitting formatting adjustments.\n   */\n  formatting?: boolean;\n  cryptProviderType?: string;\n  cryptAlgorithmClass?: string;\n  cryptAlgorithmType?: string;\n  cryptAlgorithmSid?: number;\n  cryptSpinCount?: number;\n  hash?: string;\n  salt?: string;\n  /**\n   * Modern crypto attributes per ISO/IEC 29500-4 §13 (Word 2013+):\n   * - `algorithmName` names the strong hash algorithm (e.g. \"SHA-512\"),\n   *   replacing the legacy `cryptAlgorithmSid` lookup-table reference.\n   * - `hashValue` is the base64-encoded password hash.\n   * - `saltValue` is the base64-encoded salt.\n   *\n   * These are emitted alongside / instead of the legacy `hash` / `salt`\n   * / `cryptAlgorithmSid` attributes. Previously dropped on round-trip.\n   */\n  algorithmName?: string;\n  hashValue?: string;\n  saltValue?: string;\n}\n\n/**\n * Revision view settings per ECMA-376 CT_TrackChangesView\n */\nexport interface RevisionViewSettings {\n  showInsertionsAndDeletions: boolean;\n  showFormatting: boolean;\n  showInkAnnotations: boolean;\n  /**\n   * `w:markup` per CT_TrackChangesView §17.15.1.77 — when false, all\n   * revision markup is hidden in the reviewer pane (no balloons, no\n   * strikethrough/inserted styling). Defaults to true when absent.\n   */\n  showMarkup?: boolean;\n  /**\n   * `w:comments` per CT_TrackChangesView §17.15.1.77 — when false,\n   * comment balloons are hidden. Defaults to true when absent.\n   */\n  showComments?: boolean;\n}\n\n/**\n * Track changes and related settings passed to DocumentGenerator.generateSettings()\n */\nexport interface TrackChangesSettings {\n  trackChangesEnabled?: boolean;\n  trackFormatting?: boolean;\n  revisionView?: RevisionViewSettings;\n  rsidRoot?: string;\n  rsids?: string[];\n  documentProtection?: DocumentProtection;\n}\n\n/**\n * Information about webSettings.xml per ECMA-376 CT_WebSettings\n */\nexport interface WebSettingsInfo {\n  divCount: number;\n  optimizeForBrowser: boolean;\n  allowPNG: boolean;\n  relyOnVML: boolean;\n  doNotRelyOnCSS: boolean;\n  doNotSaveAsSingleFile: boolean;\n  doNotOrganizeInFolder: boolean;\n  doNotUseLongFileNames: boolean;\n  pixelsPerInch?: number;\n  targetScreenSz?: string;\n  encoding?: string;\n}\n"]}

package/dist/esm/types/styleConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=styleConfig.js.map

package/dist/esm/types/styleConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styleConfig.js","sourceRoot":"","sources":["../../../src/types/styleConfig.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Configuration interfaces for customizable style formatting\n * Used by Document.applyCustomFormattingToExistingStyles()\n */\n\n/**\n * Run (character) formatting configuration for styles\n */\nexport interface StyleRunFormatting {\n  /** Font family name (e.g., 'Verdana', 'Arial', 'Times New Roman') */\n  font?: string;\n\n  /** Font size in points (e.g., 12, 14, 18) */\n  size?: number;\n\n  /** Whether text should be bold */\n  bold?: boolean;\n\n  /** Whether text should be italic */\n  italic?: boolean;\n\n  /** Whether text should be underlined */\n  underline?: boolean;\n\n  /** Text color as hex without # (e.g., '000000', 'FF0000') */\n  color?: string;\n\n  /** If true, preserve existing bold formatting (don't apply bold property) */\n  preserveBold?: boolean;\n\n  /** If true, preserve existing italic formatting (don't apply italic property) */\n  preserveItalic?: boolean;\n\n  /** If true, preserve existing underline formatting (don't apply underline property) */\n  preserveUnderline?: boolean;\n}\n\n/**\n * Paragraph formatting configuration for styles\n */\nexport interface StyleParagraphFormatting {\n  /** Text alignment */\n  alignment?: 'left' | 'center' | 'right' | 'justify';\n\n  /** Spacing configuration */\n  spacing?: {\n    /** Spacing before paragraph in twips (20 twips = 1 point) */\n    before?: number;\n\n    /** Spacing after paragraph in twips (20 twips = 1 point) */\n    after?: number;\n\n    /** Line spacing in twips (240 = single spacing when lineRule is 'auto') */\n    line?: number;\n\n    /** How to interpret the line spacing value */\n    lineRule?: 'auto' | 'exact' | 'atLeast';\n  };\n\n  /** Indentation configuration */\n  indentation?: {\n    /** Left indent in twips (1440 twips = 1 inch) */\n    left?: number;\n\n    /** Right indent in twips */\n    right?: number;\n\n    /** First line indent in twips (positive = indent, negative = outdent) */\n    firstLine?: number;\n\n    /** Hanging indent in twips (typically used for lists) */\n    hanging?: number;\n  };\n\n  /**\n   * Whether to remove spacing between consecutive paragraphs of the same style\n   * Per ECMA-376 Part 1 §17.3.1.8\n   */\n  contextualSpacing?: boolean;\n}\n\n/**\n * Table appearance options for Heading2 wrapping\n * Heading2 paragraphs are always wrapped in 1x1 tables with these settings\n */\nexport interface Heading2TableOptions {\n  /** Cell background color as hex without # (e.g., 'BFBFBF' for gray) */\n  shading?: string;\n\n  /** Top cell margin in twips */\n  marginTop?: number;\n\n  /** Bottom cell margin in twips */\n  marginBottom?: number;\n\n  /** Left cell margin in twips (115 twips = 0.08 inches) */\n  marginLeft?: number;\n\n  /** Right cell margin in twips (115 twips = 0.08 inches) */\n  marginRight?: number;\n\n  /** Table width as percentage (5000 = 100%) */\n  tableWidthPercent?: number;\n}\n\n/**\n * Base style configuration combining run and paragraph formatting\n */\nexport interface StyleConfig {\n  /** Character formatting for the style */\n  run?: StyleRunFormatting;\n\n  /** Paragraph formatting for the style */\n  paragraph?: StyleParagraphFormatting;\n}\n\n/**\n * Extended configuration for Heading2 style including table options\n * Heading2 paragraphs are always wrapped in tables\n */\nexport interface Heading2Config extends StyleConfig {\n  /** Table appearance options for wrapping Heading2 paragraphs */\n  tableOptions?: Heading2TableOptions;\n}\n\n/**\n * Extended configuration for Normal style with alignment preservation options\n */\nexport interface NormalConfig extends StyleConfig {\n  /**\n   * Whether to preserve center alignment during style application.\n   * When true, paragraphs that are center-aligned will retain their center alignment\n   * instead of being changed to the Normal style's alignment (typically 'left').\n   * This is useful for preserving intentional centering like image captions or table headers.\n   * @default false\n   */\n  preserveCenterAlignment?: boolean;\n}\n\n/**\n * Complete configuration for applyStyles()\n * All properties are optional - defaults will be used if not provided\n */\nexport interface ApplyStylesOptions {\n  /** Heading1 style configuration */\n  heading1?: StyleConfig;\n\n  /** Heading2 style configuration with table options */\n  heading2?: Heading2Config;\n\n  /** Heading3 style configuration */\n  heading3?: StyleConfig;\n\n  /** Normal style configuration with alignment preservation options */\n  normal?: NormalConfig;\n\n  /** List Paragraph style configuration */\n  listParagraph?: StyleConfig;\n\n  /**\n   * Whether to preserve blank lines added after 1x1 Heading 2 tables.\n   * When true, blank paragraphs added after Heading 2 tables are marked as preserved\n   * to prevent accidental removal by document processing operations (e.g., removing extra blank lines).\n   * @default true\n   */\n  preserveBlankLinesAfterHeading2Tables?: boolean;\n\n  /**\n   * Whether to preserve white font (FFFFFF) color during style application.\n   * When true, runs with white color will not have their color changed.\n   * This is useful for preserving hidden text like ID tags or overlay text.\n   * @default false\n   */\n  preserveWhiteFont?: boolean;\n\n  /**\n   * Whether to apply Normal style changes to NormalWeb (Normal (Web)) style as well.\n   * When true (default), if NormalWeb style exists in the document,\n   * it will receive the same formatting changes applied to Normal.\n   * This ensures consistency between Normal and Normal (Web) styles.\n   * @default true\n   */\n  linkNormalWebToNormal?: boolean;\n}\n\n/**\n * @deprecated Use {@link ApplyStylesOptions} instead (renamed in v4.0.0)\n */\nexport type ApplyCustomFormattingOptions = ApplyStylesOptions;\n"]}

package/dist/esm/utils/KeyedRegistry.js

@@ -0,0 +1,32 @@
+export class KeyedRegistry {
+    label;
+    entries = new Map();
+    constructor(label) {
+        this.label = label;
+    }
+    register(key, value) {
+        if (this.entries.has(key)) {
+            throw new Error(`${this.label}: "${key}" is already registered`);
+        }
+        this.entries.set(key, value);
+    }
+    unregister(key) {
+        return this.entries.delete(key);
+    }
+    has(key) {
+        return this.entries.has(key);
+    }
+    get(key) {
+        return this.entries.get(key);
+    }
+    keys() {
+        return [...this.entries.keys()];
+    }
+    values() {
+        return [...this.entries.values()];
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=KeyedRegistry.js.map

package/dist/esm/utils/KeyedRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyedRegistry.js","sourceRoot":"","sources":["../../../src/utils/KeyedRegistry.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,aAAa;IAGK;IAFZ,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;IAEhD,YAA6B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAE9C,QAAQ,CAAC,GAAW,EAAE,KAAQ;QAC5B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,MAAM,GAAG,yBAAyB,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF","sourcesContent":["/**\n * Map-backed keyed registry shared by ElementRegistry and ValidationRuleRegistry.\n * Throws on duplicate `register()` so callers cannot silently overwrite a\n * pre-existing entry.\n */\nexport class KeyedRegistry<V> {\n  private readonly entries = new Map<string, V>();\n\n  constructor(private readonly label: string) {}\n\n  register(key: string, value: V): void {\n    if (this.entries.has(key)) {\n      throw new Error(`${this.label}: \"${key}\" is already registered`);\n    }\n    this.entries.set(key, value);\n  }\n\n  unregister(key: string): boolean {\n    return this.entries.delete(key);\n  }\n\n  has(key: string): boolean {\n    return this.entries.has(key);\n  }\n\n  get(key: string): V | undefined {\n    return this.entries.get(key);\n  }\n\n  keys(): string[] {\n    return [...this.entries.keys()];\n  }\n\n  values(): V[] {\n    return [...this.entries.values()];\n  }\n\n  clear(): void {\n    this.entries.clear();\n  }\n}\n"]}

package/dist/esm/utils/corruptionDetection.js

@@ -0,0 +1,155 @@
+import { Paragraph } from '../elements/Paragraph.js';
+import { Run } from '../elements/Run.js';
+export function detectCorruptionInDocument(doc) {
+    const locations = [];
+    const stats = {
+        escapedXml: 0,
+        xmlTags: 0,
+        entities: 0,
+        mixed: 0,
+    };
+    const paragraphs = doc.getAllParagraphs ? doc.getAllParagraphs() : [];
+    for (let pIdx = 0; pIdx < paragraphs.length; pIdx++) {
+        const paragraph = paragraphs[pIdx];
+        if (!paragraph || !(paragraph instanceof Paragraph)) {
+            continue;
+        }
+        const runs = paragraph.getRuns();
+        for (let rIdx = 0; rIdx < runs.length; rIdx++) {
+            const run = runs[rIdx];
+            if (!run || !(run instanceof Run)) {
+                continue;
+            }
+            const text = run.getText();
+            if (!text || text.length === 0) {
+                continue;
+            }
+            const corruption = detectCorruptionInText(text);
+            if (corruption.isCorrupted) {
+                locations.push({
+                    paragraphIndex: pIdx,
+                    runIndex: rIdx,
+                    text: text,
+                    corruptionType: corruption.type,
+                    suggestedFix: corruption.suggestedFix,
+                    length: text.length,
+                });
+                if (corruption.type === 'escaped-xml')
+                    stats.escapedXml++;
+                else if (corruption.type === 'xml-tags')
+                    stats.xmlTags++;
+                else if (corruption.type === 'entities')
+                    stats.entities++;
+                else if (corruption.type === 'mixed')
+                    stats.mixed++;
+            }
+        }
+    }
+    const summary = generateSummary(locations, stats);
+    return {
+        isCorrupted: locations.length > 0,
+        totalLocations: locations.length,
+        locations,
+        summary,
+        statistics: stats,
+    };
+}
+export function detectCorruptionInText(text) {
+    if (!text || typeof text !== 'string') {
+        return { isCorrupted: false, type: 'mixed', suggestedFix: String(text || '') };
+    }
+    let hasEscapedXml = false;
+    let hasXmlTags = false;
+    let hasEntities = false;
+    const escapedXmlPattern = /&lt;\/?w:[a-z]+[^&]*&gt;/i;
+    if (escapedXmlPattern.test(text)) {
+        hasEscapedXml = true;
+    }
+    const xmlTagPattern = /<\/?w:[a-z]+[^>]*>/i;
+    if (xmlTagPattern.test(text)) {
+        hasXmlTags = true;
+    }
+    const wordXmlAttributePattern = /(&lt;(?:w|a|r|pic|wp|m|mc|wpc|wps|wpg|c|dgm|o|v):|xml:space=&quot;preserve&quot;)/i;
+    if (wordXmlAttributePattern.test(text)) {
+        hasEntities = true;
+    }
+    const corruptionCount = [hasEscapedXml, hasXmlTags, hasEntities].filter(Boolean).length;
+    if (corruptionCount === 0) {
+        return { isCorrupted: false, type: 'mixed', suggestedFix: text };
+    }
+    let type;
+    if (hasEscapedXml && (hasEntities || hasXmlTags)) {
+        type = 'escaped-xml';
+    }
+    else if (hasXmlTags && hasEntities) {
+        type = 'xml-tags';
+    }
+    else if (corruptionCount > 1) {
+        type = 'mixed';
+    }
+    else if (hasEscapedXml) {
+        type = 'escaped-xml';
+    }
+    else if (hasXmlTags) {
+        type = 'xml-tags';
+    }
+    else {
+        type = 'entities';
+    }
+    const suggestedFix = suggestFix(text);
+    return { isCorrupted: true, type, suggestedFix };
+}
+export function suggestFix(corruptedText) {
+    if (!corruptedText || typeof corruptedText !== 'string') {
+        return corruptedText;
+    }
+    let cleaned = corruptedText;
+    cleaned = cleaned
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+    cleaned = cleaned.replace(/<w:[^>]+>/g, '');
+    cleaned = cleaned.replace(/<\/w:[^>]+>/g, '');
+    cleaned = cleaned.replace(/<[^>]+>/g, '');
+    cleaned = cleaned.replace(/\s+/g, ' ').trim();
+    return cleaned;
+}
+function generateSummary(locations, stats) {
+    if (locations.length === 0) {
+        return 'No corruption detected. Document is clean.';
+    }
+    const lines = [];
+    lines.push(`Found ${locations.length} corrupted text location(s) in the document.`);
+    lines.push('');
+    lines.push('Corruption breakdown:');
+    if (stats.escapedXml > 0) {
+        lines.push(`  - Escaped XML: ${stats.escapedXml} location(s)`);
+    }
+    if (stats.xmlTags > 0) {
+        lines.push(`  - XML Tags: ${stats.xmlTags} location(s)`);
+    }
+    if (stats.entities > 0) {
+        lines.push(`  - XML Entities: ${stats.entities} location(s)`);
+    }
+    if (stats.mixed > 0) {
+        lines.push(`  - Mixed: ${stats.mixed} location(s)`);
+    }
+    lines.push('');
+    lines.push('This corruption typically occurs when XML strings are passed to text methods.');
+    lines.push('Instead of: paragraph.addText("Text<w:t>1</w:t>")');
+    lines.push('Use: paragraph.addText("Text"); paragraph.addText("1");');
+    lines.push('');
+    lines.push('To automatically clean text, use: new Run(text, { cleanXmlFromText: true })');
+    return lines.join('\n');
+}
+export function looksCorrupted(text) {
+    if (!text || typeof text !== 'string') {
+        return false;
+    }
+    return (/&lt;\/?(w|r|p):[a-z]+/i.test(text) ||
+        /<\/?(w|r|p):[a-z]+/i.test(text) ||
+        /xml:space=&quot;/i.test(text));
+}
+//# sourceMappingURL=corruptionDetection.js.map

package/dist/esm/utils/corruptionDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corruptionDetection.js","sourceRoot":"","sources":["../../../src/utils/corruptionDetection.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Corruption Detection - Utilities to detect and diagnose XML corruption in documents\n *\n * This module helps users identify when they've accidentally passed XML-like strings\n * to text methods instead of using the proper API. This is a common mistake that\n * results in escaped XML tags being displayed as literal text in Word.\n */\n\nimport { Paragraph } from '../elements/Paragraph.js';\nimport { Run } from '../elements/Run.js';\n\n/** Minimal interface for document corruption scanning (avoids circular import) */\ninterface DocumentLike {\n  getAllParagraphs?(): Paragraph[];\n}\n\n/**\n * Types of corruption that can be detected\n */\nexport type CorruptionType =\n  | 'escaped-xml' // &lt;w:t&gt; style escaping\n  | 'xml-tags' // <w:t> tags in text\n  | 'entities' // &quot; &apos; etc.\n  | 'mixed'; // Multiple types\n\n/**\n * Location of corruption within a document\n */\nexport interface CorruptionLocation {\n  /** Index of the paragraph containing corruption */\n  paragraphIndex: number;\n  /** Index of the run within the paragraph */\n  runIndex: number;\n  /** The corrupted text content */\n  text: string;\n  /** Type of corruption detected */\n  corruptionType: CorruptionType;\n  /** Suggested fix for the corruption */\n  suggestedFix: string;\n  /** Length of corrupted text */\n  length: number;\n}\n\n/**\n * Comprehensive corruption report for a document\n */\nexport interface CorruptionReport {\n  /** Whether any corruption was found */\n  isCorrupted: boolean;\n  /** Total number of corrupted locations */\n  totalLocations: number;\n  /** Detailed list of corruption locations */\n  locations: CorruptionLocation[];\n  /** Human-readable summary */\n  summary: string;\n  /** Statistics about corruption types */\n  statistics: {\n    escapedXml: number;\n    xmlTags: number;\n    entities: number;\n    mixed: number;\n  };\n}\n\n/**\n * Detects XML corruption in a document\n *\n * Scans all paragraphs and runs to find text that contains escaped XML\n * or XML-like patterns that suggest the user passed XML strings to text methods.\n *\n * @param doc - The document to scan\n * @returns Corruption report with locations and suggested fixes\n *\n * @example\n * ```typescript\n * const doc = await Document.load('corrupted.docx');\n * const report = detectCorruptionInDocument(doc);\n *\n * if (report.isCorrupted) {\n *   console.log(report.summary);\n *   report.locations.forEach(loc => {\n *     console.log(`Paragraph ${loc.paragraphIndex}, Run ${loc.runIndex}: ${loc.suggestedFix}`);\n *   });\n * }\n * ```\n */\nexport function detectCorruptionInDocument(doc: DocumentLike): CorruptionReport {\n  const locations: CorruptionLocation[] = [];\n  const stats = {\n    escapedXml: 0,\n    xmlTags: 0,\n    entities: 0,\n    mixed: 0,\n  };\n\n  // Get all paragraphs from the document\n  const paragraphs = doc.getAllParagraphs ? doc.getAllParagraphs() : [];\n\n  // Scan each paragraph\n  for (let pIdx = 0; pIdx < paragraphs.length; pIdx++) {\n    const paragraph = paragraphs[pIdx];\n    if (!paragraph || !(paragraph instanceof Paragraph)) {\n      continue;\n    }\n\n    // Get runs from paragraph\n    const runs = paragraph.getRuns();\n\n    // Scan each run\n    for (let rIdx = 0; rIdx < runs.length; rIdx++) {\n      const run = runs[rIdx];\n      if (!run || !(run instanceof Run)) {\n        continue;\n      }\n\n      const text = run.getText();\n      if (!text || text.length === 0) {\n        continue;\n      }\n\n      // Check for corruption in this text\n      const corruption = detectCorruptionInText(text);\n\n      if (corruption.isCorrupted) {\n        locations.push({\n          paragraphIndex: pIdx,\n          runIndex: rIdx,\n          text: text,\n          corruptionType: corruption.type,\n          suggestedFix: corruption.suggestedFix,\n          length: text.length,\n        });\n\n        // Update statistics\n        if (corruption.type === 'escaped-xml') stats.escapedXml++;\n        else if (corruption.type === 'xml-tags') stats.xmlTags++;\n        else if (corruption.type === 'entities') stats.entities++;\n        else if (corruption.type === 'mixed') stats.mixed++;\n      }\n    }\n  }\n\n  // Generate summary\n  const summary = generateSummary(locations, stats);\n\n  return {\n    isCorrupted: locations.length > 0,\n    totalLocations: locations.length,\n    locations,\n    summary,\n    statistics: stats,\n  };\n}\n\n/**\n * Internal result from text corruption detection\n */\ninterface TextCorruptionResult {\n  isCorrupted: boolean;\n  type: CorruptionType;\n  suggestedFix: string;\n}\n\n/**\n * Detects XML corruption in a single text string\n *\n * Checks for common patterns that indicate the user passed XML strings\n * instead of plain text.\n *\n * @param text - Text to check\n * @returns True if corruption detected\n *\n * @example\n * ```typescript\n * const corrupted = detectCorruptionInText('Hello &lt;w:t&gt;World');\n * // Returns: true\n *\n * const clean = detectCorruptionInText('Hello World');\n * // Returns: false\n * ```\n */\nexport function detectCorruptionInText(text: string): TextCorruptionResult {\n  if (!text || typeof text !== 'string') {\n    return { isCorrupted: false, type: 'mixed', suggestedFix: String(text || '') };\n  }\n\n  let hasEscapedXml = false;\n  let hasXmlTags = false;\n  let hasEntities = false;\n\n  // Pattern 1: Escaped XML tags (most common corruption)\n  // Matches: &lt;w:t&gt;, &lt;/w:t&gt;, &lt;w:r&gt;, etc.\n  const escapedXmlPattern = /&lt;\\/?w:[a-z]+[^&]*&gt;/i;\n  if (escapedXmlPattern.test(text)) {\n    hasEscapedXml = true;\n  }\n\n  // Pattern 2: Raw XML tags (less common, but possible)\n  // Matches: <w:t>, </w:t>, <w:r>, etc.\n  const xmlTagPattern = /<\\/?w:[a-z]+[^>]*>/i;\n  if (xmlTagPattern.test(text)) {\n    hasXmlTags = true;\n  }\n\n  // Pattern 3: Escaped entities combined with Word XML attributes\n  // ONLY flag if we see Word-specific patterns, not just any entities\n  // This avoids false positives from legitimate escaped characters\n  // Matches all OOXML namespaces: w: (word), a: (drawingML), pic: (picture), r: (relationships), wp: (word drawing)\n  const wordXmlAttributePattern =\n    /(&lt;(?:w|a|r|pic|wp|m|mc|wpc|wps|wpg|c|dgm|o|v):|xml:space=&quot;preserve&quot;)/i;\n  if (wordXmlAttributePattern.test(text)) {\n    hasEntities = true;\n  }\n\n  // Determine corruption type\n  const corruptionCount = [hasEscapedXml, hasXmlTags, hasEntities].filter(Boolean).length;\n\n  if (corruptionCount === 0) {\n    return { isCorrupted: false, type: 'mixed', suggestedFix: text };\n  }\n\n  // More precise type detection - check primary indicator first\n  let type: CorruptionType;\n  if (hasEscapedXml && (hasEntities || hasXmlTags)) {\n    // Escaped XML combined with other patterns - this is the classic corruption case\n    type = 'escaped-xml';\n  } else if (hasXmlTags && hasEntities) {\n    type = 'xml-tags';\n  } else if (corruptionCount > 1) {\n    type = 'mixed';\n  } else if (hasEscapedXml) {\n    type = 'escaped-xml';\n  } else if (hasXmlTags) {\n    type = 'xml-tags';\n  } else {\n    type = 'entities';\n  }\n\n  const suggestedFix = suggestFix(text);\n\n  return { isCorrupted: true, type, suggestedFix };\n}\n\n/**\n * Suggests a fix for corrupted text\n *\n * Attempts to clean XML patterns from text to restore the intended content.\n * Uses the same cleaning logic as cleanXmlFromText() from validation.ts.\n *\n * @param corruptedText - Text containing XML corruption\n * @returns Cleaned text with XML patterns removed\n *\n * @example\n * ```typescript\n * const fixed = suggestFix('Hello &lt;w:t&gt;World&lt;/w:t&gt;');\n * // Returns: 'Hello World'\n * ```\n */\nexport function suggestFix(corruptedText: string): string {\n  if (!corruptedText || typeof corruptedText !== 'string') {\n    return corruptedText;\n  }\n\n  let cleaned = corruptedText;\n\n  // Step 1: Unescape XML entities first\n  cleaned = cleaned\n    .replace(/&lt;/g, '<')\n    .replace(/&gt;/g, '>')\n    .replace(/&quot;/g, '\"')\n    .replace(/&apos;/g, \"'\")\n    .replace(/&amp;/g, '&');\n\n  // Step 2: Remove Word XML tags\n  // Matches: <w:t xml:space=\"preserve\">, </w:t>, <w:r>, etc.\n  cleaned = cleaned.replace(/<w:[^>]+>/g, '');\n  cleaned = cleaned.replace(/<\\/w:[^>]+>/g, '');\n\n  // Step 3: Remove any remaining XML-like tags\n  cleaned = cleaned.replace(/<[^>]+>/g, '');\n\n  // Step 4: Clean up whitespace\n  cleaned = cleaned.replace(/\\s+/g, ' ').trim();\n\n  return cleaned;\n}\n\n/**\n * Generates a human-readable summary of corruption\n */\nfunction generateSummary(\n  locations: CorruptionLocation[],\n  stats: { escapedXml: number; xmlTags: number; entities: number; mixed: number }\n): string {\n  if (locations.length === 0) {\n    return 'No corruption detected. Document is clean.';\n  }\n\n  const lines: string[] = [];\n  lines.push(`Found ${locations.length} corrupted text location(s) in the document.`);\n  lines.push('');\n  lines.push('Corruption breakdown:');\n\n  if (stats.escapedXml > 0) {\n    lines.push(`  - Escaped XML: ${stats.escapedXml} location(s)`);\n  }\n  if (stats.xmlTags > 0) {\n    lines.push(`  - XML Tags: ${stats.xmlTags} location(s)`);\n  }\n  if (stats.entities > 0) {\n    lines.push(`  - XML Entities: ${stats.entities} location(s)`);\n  }\n  if (stats.mixed > 0) {\n    lines.push(`  - Mixed: ${stats.mixed} location(s)`);\n  }\n\n  lines.push('');\n  lines.push('This corruption typically occurs when XML strings are passed to text methods.');\n  lines.push('Instead of: paragraph.addText(\"Text<w:t>1</w:t>\")');\n  lines.push('Use: paragraph.addText(\"Text\"); paragraph.addText(\"1\");');\n  lines.push('');\n  lines.push('To automatically clean text, use: new Run(text, { cleanXmlFromText: true })');\n\n  return lines.join('\\n');\n}\n\n/**\n * Checks if text looks like it might be corrupted (less strict check)\n *\n * This is a quick check that can be used for warnings without full analysis.\n *\n * @param text - Text to check\n * @returns True if text might be corrupted\n */\nexport function looksCorrupted(text: string): boolean {\n  if (!text || typeof text !== 'string') {\n    return false;\n  }\n\n  // Quick regex checks for common corruption patterns\n  return (\n    /&lt;\\/?(w|r|p):[a-z]+/i.test(text) ||\n    /<\\/?(w|r|p):[a-z]+/i.test(text) ||\n    /xml:space=&quot;/i.test(text)\n  );\n}\n"]}

package/dist/esm/utils/dateFormatting.js

@@ -0,0 +1,4 @@
+export function formatDateForXml(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+//# sourceMappingURL=dateFormatting.js.map

package/dist/esm/utils/dateFormatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateFormatting.js","sourceRoot":"","sources":["../../../src/utils/dateFormatting.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Date formatting utilities for OOXML XML generation\n *\n * ECMA-376 requires dates in ISO 8601 format WITHOUT milliseconds:\n *   Valid:   \"2024-01-01T12:00:00Z\"\n *   Invalid: \"2024-01-01T12:00:00.000Z\" (Word rejects milliseconds in w:date attributes)\n *\n * JavaScript's Date.toISOString() always includes milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ),\n * so we must strip the .sss portion for all w:date attributes in tracked changes.\n */\n\n/**\n * Formats a Date to ISO 8601 without milliseconds for OOXML w:date attributes.\n *\n * @param date - Date to format\n * @returns ISO 8601 date string without milliseconds (e.g., \"2024-01-01T12:00:00Z\")\n */\nexport function formatDateForXml(date: Date): string {\n  return date.toISOString().replace(/\\.\\d{3}Z$/, 'Z');\n}\n"]}

package/dist/esm/utils/deepClone.js

@@ -0,0 +1,40 @@
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        const arrCopy = [];
+        for (let i = 0; i < obj.length; i++) {
+            arrCopy[i] = deepClone(obj[i]);
+        }
+        return arrCopy;
+    }
+    if (obj instanceof Map) {
+        const mapCopy = new Map();
+        obj.forEach((value, key) => {
+            mapCopy.set(deepClone(key), deepClone(value));
+        });
+        return mapCopy;
+    }
+    if (obj instanceof Set) {
+        const setCopy = new Set();
+        obj.forEach((value) => {
+            setCopy.add(deepClone(value));
+        });
+        return setCopy;
+    }
+    if (obj instanceof RegExp) {
+        return new RegExp(obj.source, obj.flags);
+    }
+    const objCopy = Object.create(Object.getPrototypeOf(obj));
+    for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            objCopy[key] = deepClone(obj[key]);
+        }
+    }
+    return objCopy;
+}
+//# sourceMappingURL=deepClone.js.map

package/dist/esm/utils/deepClone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepClone.js","sourceRoot":"","sources":["../../../src/utils/deepClone.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,SAAS,CAAI,GAAM;IAEjC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAGD,IAAI,GAAG,YAAY,IAAI,EAAE,CAAC;QACxB,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAM,CAAC;IACtC,CAAC;IAGD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,OAAO,GAAc,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,OAAY,CAAC;IACtB,CAAC;IAGD,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACzB,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,OAAO,OAAY,CAAC;IACtB,CAAC;IAGD,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,OAAO,OAAY,CAAC;IACtB,CAAC;IAGD,IAAI,GAAG,YAAY,MAAM,EAAE,CAAC;QAC1B,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAM,CAAC;IAChD,CAAC;IAGD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAA4B,CAAC;IACrF,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,CAAE,GAA+B,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,OAAO,OAAY,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Deep clone utility for safely cloning objects\n * More efficient and type-safe than JSON.parse(JSON.stringify())\n */\n\n/**\n * Deep clone an object using structured cloning\n * Preserves most object types including Date, RegExp, Map, Set, etc.\n *\n * For simple objects (like formatting options), this is more efficient\n * than JSON.parse(JSON.stringify()) and doesn't lose non-serializable values.\n *\n * @param obj - Object to clone\n * @returns Deep cloned copy of the object\n *\n * @example\n * ```typescript\n * const original = { bold: true, color: \"FF0000\", date: new Date() };\n * const cloned = deepClone(original);\n * cloned.bold = false;\n * console.log(original.bold); // true (unchanged)\n * console.log(cloned.date instanceof Date); // true (preserved)\n * ```\n */\nexport function deepClone<T>(obj: T): T {\n  // Handle primitive types and null\n  if (obj === null || typeof obj !== 'object') {\n    return obj;\n  }\n\n  // Handle Date\n  if (obj instanceof Date) {\n    return new Date(obj.getTime()) as T;\n  }\n\n  // Handle Array\n  if (Array.isArray(obj)) {\n    const arrCopy: unknown[] = [];\n    for (let i = 0; i < obj.length; i++) {\n      arrCopy[i] = deepClone(obj[i]);\n    }\n    return arrCopy as T;\n  }\n\n  // Handle Map\n  if (obj instanceof Map) {\n    const mapCopy = new Map();\n    obj.forEach((value, key) => {\n      mapCopy.set(deepClone(key), deepClone(value));\n    });\n    return mapCopy as T;\n  }\n\n  // Handle Set\n  if (obj instanceof Set) {\n    const setCopy = new Set();\n    obj.forEach((value) => {\n      setCopy.add(deepClone(value));\n    });\n    return setCopy as T;\n  }\n\n  // Handle RegExp\n  if (obj instanceof RegExp) {\n    return new RegExp(obj.source, obj.flags) as T;\n  }\n\n  // Handle plain objects\n  const objCopy = Object.create(Object.getPrototypeOf(obj)) as Record<string, unknown>;\n  for (const key in obj) {\n    if (obj.hasOwnProperty(key)) {\n      objCopy[key] = deepClone((obj as Record<string, unknown>)[key]);\n    }\n  }\n\n  return objCopy as T;\n}\n"]}

package/dist/esm/utils/deepEqual.js

@@ -0,0 +1,47 @@
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    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;
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    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;
+    }
+    const objA = a;
+    const objB = b;
+    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;
+}
+//# sourceMappingURL=deepEqual.js.map

package/dist/esm/utils/deepEqual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepEqual.js","sourceRoot":"","sources":["../../../src/utils/deepEqual.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,SAAS,CAAC,CAAU,EAAE,CAAU;IAC9C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAIzB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC;IACvB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAGrC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QAC3C,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IAC/E,CAAC;IAGD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,CAAC,CAAC;QACf,MAAM,IAAI,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAGD,MAAM,IAAI,GAAG,CAA4B,CAAC;IAC1C,MAAM,IAAI,GAAG,CAA4B,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACjE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * Structural equality check for OOXML formatting objects.\n *\n * Replaces `JSON.stringify(a) === JSON.stringify(b)` in hot equality paths\n * (paragraph property merging, tracking-context consolidation). Avoids\n * allocating two large strings per comparison and short-circuits on the\n * first inequality.\n *\n * Handles the value shapes seen in formatting objects: primitives, plain\n * objects, arrays, Date, null/undefined. Symbols and class instances are\n * not part of the formatting model and are compared by reference.\n */\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  // NaN === NaN is false in JS; treat structurally as equal so a parse\n  // failure that produced two NaNs in equivalent slots doesn't dirty the\n  // tracking-context consolidation pass.\n  if (typeof a === 'number' && typeof b === 'number' && Number.isNaN(a) && Number.isNaN(b)) {\n    return true;\n  }\n  if (a == null || b == null) return a === b;\n\n  const typeA = typeof a;\n  const typeB = typeof b;\n  if (typeA !== typeB) return false;\n  if (typeA !== 'object') return false;\n\n  // Date values\n  if (a instanceof Date || b instanceof Date) {\n    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();\n  }\n\n  // Arrays: same length, element-wise equality.\n  const aIsArr = Array.isArray(a);\n  const bIsArr = Array.isArray(b);\n  if (aIsArr !== bIsArr) return false;\n  if (aIsArr && bIsArr) {\n    const arrA = a;\n    const arrB = b;\n    if (arrA.length !== arrB.length) return false;\n    for (let i = 0; i < arrA.length; i++) {\n      if (!deepEqual(arrA[i], arrB[i])) return false;\n    }\n    return true;\n  }\n\n  // Plain objects: same key set, deep-equal values.\n  const objA = a as Record<string, unknown>;\n  const objB = b as Record<string, unknown>;\n  const keysA = Object.keys(objA);\n  const keysB = Object.keys(objB);\n  if (keysA.length !== keysB.length) return false;\n  for (const k of keysA) {\n    if (!Object.prototype.hasOwnProperty.call(objB, k)) return false;\n    if (!deepEqual(objA[k], objB[k])) return false;\n  }\n  return true;\n}\n"]}

package/dist/esm/utils/diagnostics.js

@@ -0,0 +1,69 @@
+const defaultConfig = {
+    enabled: false,
+    logParsing: false,
+    logSerialization: false,
+    logTextDirection: false,
+    verbose: false,
+};
+let config = { ...defaultConfig };
+export function enableDiagnostics(options = {}) {
+    config = {
+        ...defaultConfig,
+        enabled: true,
+        ...options,
+    };
+}
+export function disableDiagnostics() {
+    config = { ...defaultConfig };
+}
+export function getDiagnosticConfig() {
+    return { ...config };
+}
+export function logParsing(message, data) {
+    if (config.enabled && config.logParsing) {
+        console.log(`[PARSE] ${message}`, data !== undefined ? data : '');
+    }
+}
+export function logSerialization(message, data) {
+    if (config.enabled && config.logSerialization) {
+        console.log(`[SERIALIZE] ${message}`, data !== undefined ? data : '');
+    }
+}
+export function logTextDirection(message, data) {
+    if (config.enabled && config.logTextDirection) {
+        console.log(`[TEXT-DIR] ${message}`, data !== undefined ? data : '');
+    }
+}
+export function logVerbose(message, data) {
+    if (config.enabled && config.verbose) {
+        console.log(`[VERBOSE] ${message}`, data !== undefined ? data : '');
+    }
+}
+export function logParagraphContent(source, paraIndex, runs, bidi) {
+    if (!config.enabled)
+        return;
+    const logger = source === 'parsing' ? logParsing : logSerialization;
+    logger(`Paragraph ${paraIndex}:`);
+    logger(`  BiDi: ${bidi !== undefined ? bidi : 'not set'}`);
+    logger(`  Runs (${runs.length}):`);
+    runs.forEach((run, idx) => {
+        const rtlStatus = run.rtl ? ' [RTL]' : '';
+        logger(`    ${idx + 1}. "${run.text}"${rtlStatus}`);
+    });
+    const fullText = runs.map((r) => r.text).join('');
+    logger(`  Combined text: "${fullText}"`);
+}
+export function logTextComparison(label, before, after) {
+    if (!config.enabled)
+        return;
+    if (before !== after) {
+        console.log(`[TEXT-CHANGE] ${label}:`);
+        console.log(`  Before: "${before}"`);
+        console.log(`  After:  "${after}"`);
+        console.log(`  MISMATCH DETECTED!`);
+    }
+    else if (config.verbose) {
+        logVerbose(`${label}: Text preserved correctly`);
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/esm/utils/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/utils/diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Diagnostic logging utilities for debugging document processing\n * @module diagnostics\n */\n\nexport interface DiagnosticConfig {\n  enabled: boolean;\n  logParsing: boolean;\n  logSerialization: boolean;\n  logTextDirection: boolean;\n  verbose: boolean;\n}\n\nconst defaultConfig: DiagnosticConfig = {\n  enabled: false,\n  logParsing: false,\n  logSerialization: false,\n  logTextDirection: false,\n  verbose: false,\n};\n\nlet config: DiagnosticConfig = { ...defaultConfig };\n\n/**\n * Enable diagnostic logging\n */\nexport function enableDiagnostics(options: Partial<DiagnosticConfig> = {}): void {\n  config = {\n    ...defaultConfig,\n    enabled: true,\n    ...options,\n  };\n}\n\n/**\n * Disable diagnostic logging\n */\nexport function disableDiagnostics(): void {\n  config = { ...defaultConfig };\n}\n\n/**\n * Get current diagnostic configuration\n */\nexport function getDiagnosticConfig(): DiagnosticConfig {\n  return { ...config };\n}\n\n/**\n * Log parsing activity\n */\nexport function logParsing(message: string, data?: unknown): void {\n  if (config.enabled && config.logParsing) {\n    console.log(`[PARSE] ${message}`, data !== undefined ? data : '');\n  }\n}\n\n/**\n * Log serialization activity\n */\nexport function logSerialization(message: string, data?: unknown): void {\n  if (config.enabled && config.logSerialization) {\n    console.log(`[SERIALIZE] ${message}`, data !== undefined ? data : '');\n  }\n}\n\n/**\n * Log text direction properties\n */\nexport function logTextDirection(message: string, data?: unknown): void {\n  if (config.enabled && config.logTextDirection) {\n    console.log(`[TEXT-DIR] ${message}`, data !== undefined ? data : '');\n  }\n}\n\n/**\n * Log verbose details\n */\nexport function logVerbose(message: string, data?: unknown): void {\n  if (config.enabled && config.verbose) {\n    console.log(`[VERBOSE] ${message}`, data !== undefined ? data : '');\n  }\n}\n\n/**\n * Log paragraph content summary\n */\nexport function logParagraphContent(\n  source: 'parsing' | 'serialization',\n  paraIndex: number,\n  runs: { text: string; rtl?: boolean }[],\n  bidi?: boolean\n): void {\n  if (!config.enabled) return;\n\n  const logger = source === 'parsing' ? logParsing : logSerialization;\n\n  logger(`Paragraph ${paraIndex}:`);\n  logger(`  BiDi: ${bidi !== undefined ? bidi : 'not set'}`);\n  logger(`  Runs (${runs.length}):`);\n\n  runs.forEach((run, idx) => {\n    const rtlStatus = run.rtl ? ' [RTL]' : '';\n    logger(`    ${idx + 1}. \"${run.text}\"${rtlStatus}`);\n  });\n\n  const fullText = runs.map((r) => r.text).join('');\n  logger(`  Combined text: \"${fullText}\"`);\n}\n\n/**\n * Compare text before and after processing\n */\nexport function logTextComparison(label: string, before: string, after: string): void {\n  if (!config.enabled) return;\n\n  if (before !== after) {\n    console.log(`[TEXT-CHANGE] ${label}:`);\n    console.log(`  Before: \"${before}\"`);\n    console.log(`  After:  \"${after}\"`);\n    console.log(`  MISMATCH DETECTED!`);\n  } else if (config.verbose) {\n    logVerbose(`${label}: Text preserved correctly`);\n  }\n}\n"]}

package/dist/esm/utils/errorHandling.js

@@ -0,0 +1,36 @@
+export function isError(error) {
+    return error instanceof Error;
+}
+export function toError(error) {
+    if (isError(error)) {
+        return error;
+    }
+    if (typeof error === 'string') {
+        return new Error(error);
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return new Error(String(error.message));
+    }
+    return new Error(String(error));
+}
+export function wrapError(error, context) {
+    const originalError = toError(error);
+    const wrappedError = new Error(`${context}: ${originalError.message}`);
+    if (originalError.stack) {
+        wrappedError.stack = `${wrappedError.message}\nCaused by: ${originalError.stack}`;
+    }
+    return wrappedError;
+}
+export function getErrorMessage(error, fallback = 'Unknown error occurred') {
+    if (isError(error)) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return fallback;
+}
+//# sourceMappingURL=errorHandling.js.map

package/dist/esm/utils/errorHandling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandling.js","sourceRoot":"","sources":["../../../src/utils/errorHandling.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,KAAK,YAAY,KAAK,CAAC;AAChC,CAAC;AAQD,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAGD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAGD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAC7D,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;IAGD,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAClC,CAAC;AASD,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,OAAe;IACvD,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,IAAI,KAAK,CAAC,GAAG,OAAO,KAAK,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAGvE,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC;QACxB,YAAY,CAAC,KAAK,GAAG,GAAG,YAAY,CAAC,OAAO,gBAAgB,aAAa,CAAC,KAAK,EAAE,CAAC;IACpF,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AASD,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,QAAQ,GAAG,wBAAwB;IACjF,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAC7D,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Error handling utilities for consistent error processing\n * Ensures all caught errors are properly typed and handled\n */\n\n/**\n * Type guard to check if a value is an Error object\n * @param error - The value to check\n * @returns True if the value is an Error instance\n */\nexport function isError(error: unknown): error is Error {\n  return error instanceof Error;\n}\n\n/**\n * Converts unknown error to Error object\n * Ensures we always have a proper Error with message property\n * @param error - The error to normalize (can be anything)\n * @returns Normalized Error object\n */\nexport function toError(error: unknown): Error {\n  if (isError(error)) {\n    return error;\n  }\n\n  // Handle string errors\n  if (typeof error === 'string') {\n    return new Error(error);\n  }\n\n  // Handle objects with message property\n  if (error && typeof error === 'object' && 'message' in error) {\n    return new Error(String(error.message));\n  }\n\n  // Fallback for any other type\n  return new Error(String(error));\n}\n\n/**\n * Wraps an error with additional context\n * Useful for adding file paths, operation names, etc.\n * @param error - The original error\n * @param context - Additional context to prepend to error message\n * @returns New Error with combined message and original stack\n */\nexport function wrapError(error: unknown, context: string): Error {\n  const originalError = toError(error);\n  const wrappedError = new Error(`${context}: ${originalError.message}`);\n\n  // Preserve original stack trace if available\n  if (originalError.stack) {\n    wrappedError.stack = `${wrappedError.message}\\nCaused by: ${originalError.stack}`;\n  }\n\n  return wrappedError;\n}\n\n/**\n * Safe error message extraction\n * Returns error message or generic fallback\n * @param error - The error to extract message from\n * @param fallback - Fallback message if extraction fails\n * @returns Error message string\n */\nexport function getErrorMessage(error: unknown, fallback = 'Unknown error occurred'): string {\n  if (isError(error)) {\n    return error.message;\n  }\n\n  if (typeof error === 'string') {\n    return error;\n  }\n\n  if (error && typeof error === 'object' && 'message' in error) {\n    return String(error.message);\n  }\n\n  return fallback;\n}\n"]}