docxmlater 10.1.3 → 10.1.5

package/src/formatting/StylesManager.ts

@@ -1,1130 +1,1090 @@
-/**
- * StylesManager - Manages the collection of styles in a document
- * Handles style registration, retrieval, and styles.xml generation
- */
-
-import { Paragraph } from "../elements/Paragraph";
-import { XMLBuilder } from "../xml/XMLBuilder";
-import { XMLParser } from "../xml/XMLParser";
-import { Style, StyleType } from "./Style";
-
-/**
- * Configuration for latent styles (w:latentStyles per ECMA-376 §17.7.4.6)
- * Controls which built-in styles are shown in the Word UI gallery
- */
-export interface LatentStylesConfig {
-  /** Default locked state for built-in styles */
-  defaultLockedState?: boolean;
-  /** Default UI priority for built-in styles */
-  defaultUiPriority?: number;
-  /** Default semi-hidden state */
-  defaultSemiHidden?: boolean;
-  /** Default unhide-when-used state */
-  defaultUnhideWhenUsed?: boolean;
-  /** Default quick format flag */
-  defaultQFormat?: boolean;
-  /** Total count of style definitions */
-  count?: number;
-}
-
-/**
- * Exception to latent style defaults (w:lsdException per ECMA-376 §17.7.4.7)
- */
-export interface LatentStyleException {
-  /** Style name */
-  name: string;
-  /** Override: locked state */
-  locked?: boolean;
-  /** Override: UI priority */
-  uiPriority?: number;
-  /** Override: semi-hidden */
-  semiHidden?: boolean;
-  /** Override: unhide when used */
-  unhideWhenUsed?: boolean;
-  /** Override: quick format */
-  qFormat?: boolean;
-}
-
-/**
- * Result of XML validation
- */
-export interface ValidationResult {
-  /** Whether the XML is valid */
-  isValid: boolean;
-  /** Validation errors if any */
-  errors: string[];
-  /** Validation warnings if any */
-  warnings: string[];
-  /** Number of styles found */
-  styleCount: number;
-  /** List of style IDs found */
-  styleIds: string[];
-}
-
-/**
- * Manages document styles
- */
-export class StylesManager {
-  private styles = new Map<string, Style>();
-  private includeBuiltInStyles: boolean;
-
-  // Track if styles have been modified (for XML preservation)
-  private _modified = false;
-
-  // Track which specific styles have been modified (for selective merging)
-  private _modifiedStyleIds = new Set<string>();
-
-  // Latent styles configuration
-  private latentStyles?: LatentStylesConfig;
-  private latentStyleExceptions: LatentStyleException[] = [];
-
-  /**
-   * Registry of built-in style factory functions
-   * Maps style ID to factory function for lazy loading
-   */
-  private static readonly BUILT_IN_STYLE_FACTORIES = new Map<
-    string,
-    () => Style
-  >([
-    ["Normal", () => Style.createNormalStyle()],
-    ["Heading1", () => Style.createHeadingStyle(1)],
-    ["Heading2", () => Style.createHeadingStyle(2)],
-    ["Heading3", () => Style.createHeadingStyle(3)],
-    ["Heading4", () => Style.createHeadingStyle(4)],
-    ["Heading5", () => Style.createHeadingStyle(5)],
-    ["Heading6", () => Style.createHeadingStyle(6)],
-    ["Heading7", () => Style.createHeadingStyle(7)],
-    ["Heading8", () => Style.createHeadingStyle(8)],
-    ["Heading9", () => Style.createHeadingStyle(9)],
-    ["Heading1Char", () => Style.createHeadingCharStyle(1)],
-    ["Heading2Char", () => Style.createHeadingCharStyle(2)],
-    ["Heading3Char", () => Style.createHeadingCharStyle(3)],
-    ["Heading4Char", () => Style.createHeadingCharStyle(4)],
-    ["Heading5Char", () => Style.createHeadingCharStyle(5)],
-    ["Heading6Char", () => Style.createHeadingCharStyle(6)],
-    ["Heading7Char", () => Style.createHeadingCharStyle(7)],
-    ["Heading8Char", () => Style.createHeadingCharStyle(8)],
-    ["Heading9Char", () => Style.createHeadingCharStyle(9)],
-    ["Title", () => Style.createTitleStyle()],
-    ["Subtitle", () => Style.createSubtitleStyle()],
-    ["ListParagraph", () => Style.createListParagraphStyle()],
-    ["TOCHeading", () => Style.createTOCHeadingStyle()],
-    ["TableNormal", () => Style.createTableNormalStyle()],
-    ["TableGrid", () => Style.createTableGridStyle()],
-  ]);
-
-  /**
-   * Creates a new StylesManager
-   * @param includeBuiltInStyles - Whether to include built-in styles (default: true)
-   */
-  constructor(includeBuiltInStyles = true) {
-    this.includeBuiltInStyles = includeBuiltInStyles;
-
-    // Always load Normal style if built-in styles are enabled
-    // Normal is required and referenced by most other styles
-    if (includeBuiltInStyles) {
-      this.ensureStyleLoaded("Normal");
-    }
-  }
-
-  /**
-   * Ensures a built-in style is loaded (lazy loading)
-   * @param styleId - Style ID to load
-   */
-  private ensureStyleLoaded(styleId: string): void {
-    // Already loaded?
-    if (this.styles.has(styleId)) {
-      return;
-    }
-
-    // Built-in styles disabled?
-    if (!this.includeBuiltInStyles) {
-      return;
-    }
-
-    // Is this a built-in style?
-    const factory = StylesManager.BUILT_IN_STYLE_FACTORIES.get(styleId);
-    if (factory) {
-      this.styles.set(styleId, factory());
-    }
-  }
-
-  /**
-   * Adds a style to the collection
-   * @param style - Style to add
-   * @returns This manager for chaining
-   */
-  addStyle(style: Style): this {
-    const existing = this.styles.get(style.getStyleId());
-    if (existing) {
-      // Preserve isDefault flag if replacing an existing default style
-      if (existing.getIsDefault() && !style.getIsDefault()) {
-        style.setIsDefault(true);
-      }
-      // Preserve structural properties from existing style if not explicitly set on new
-      const newProps = style.getProperties();
-      const existingProps = existing.getProperties();
-      if (newProps.basedOn === undefined && existingProps.basedOn !== undefined) {
-        style.setBasedOn(existingProps.basedOn);
-      }
-      if (newProps.next === undefined && existingProps.next !== undefined) {
-        style.setNext(existingProps.next);
-      }
-      if (newProps.link === undefined && existingProps.link !== undefined) {
-        style.setLink(existingProps.link);
-      }
-      if (newProps.uiPriority === undefined && existingProps.uiPriority !== undefined) {
-        style.setUiPriority(existingProps.uiPriority);
-      }
-    }
-    this.styles.set(style.getStyleId(), style);
-    this._modifiedStyleIds.add(style.getStyleId());
-    this._modified = true;
-    return this;
-  }
-
-  /**
-   * Gets a style by ID
-   * Lazy-loads built-in styles on first access
-   * @param styleId - Style ID to retrieve
-   * @returns The style, or undefined if not found
-   */
-  getStyle(styleId: string): Style | undefined {
-    // Ensure built-in style is loaded if applicable
-    this.ensureStyleLoaded(styleId);
-    return this.styles.get(styleId);
-  }
-
-  /**
-   * Checks if a style exists or can be loaded
-   * @param styleId - Style ID to check
-   * @returns True if the style exists or is a built-in style
-   */
-  hasStyle(styleId: string): boolean {
-    // Check if already loaded
-    if (this.styles.has(styleId)) {
-      return true;
-    }
-
-    // Check if it's a built-in style that can be loaded
-    return (
-      this.includeBuiltInStyles &&
-      StylesManager.BUILT_IN_STYLE_FACTORIES.has(styleId)
-    );
-  }
-
-  /**
-   * Removes a style from the collection
-   * @param styleId - Style ID to remove
-   * @returns True if the style was removed
-   */
-  removeStyle(styleId: string): boolean {
-    return this.styles.delete(styleId);
-  }
-
-  /**
-   * Gets all styles
-   * @returns Array of all styles
-   */
-  getAllStyles(): Style[] {
-    return Array.from(this.styles.values());
-  }
-
-  /**
-   * Checks if styles have been modified since loading
-   * Used for XML preservation optimization
-   * @returns True if styles were added or modified
-   */
-  isModified(): boolean {
-    return this._modified;
-  }
-
-  /**
-   * Resets the modified flag
-   * Called after parsing to indicate that loaded styles don't count as modifications
-   */
-  resetModified(): void {
-    this._modified = false;
-    this._modifiedStyleIds.clear();
-  }
-
-  /**
-   * Gets the IDs of styles that have been modified since loading
-   * Used for selective merging with original styles.xml
-   * @returns Set of modified style IDs
-   */
-  getModifiedStyleIds(): Set<string> {
-    return new Set(this._modifiedStyleIds);
-  }
-
-  /**
-   * Gets styles by type
-   * @param type - Style type to filter by
-   * @returns Array of styles matching the type
-   */
-  getStylesByType(type: StyleType): Style[] {
-    return this.getAllStyles().filter((style) => style.getType() === type);
-  }
-
-  /**
-   * Gets quick styles (styles that appear in the style gallery)
-   * A style appears in the gallery when qFormat=true AND semiHidden=false
-   * @returns Array of quick styles
-   */
-  getQuickStyles(): Style[] {
-    return this.getAllStyles().filter((style) => {
-      const props = style.getProperties();
-      const isQuick =
-        props.qFormat === true ||
-        (!props.customStyle && props.qFormat !== false);
-      const isVisible = !props.semiHidden;
-      return isQuick && isVisible;
-    });
-  }
-
-  /**
-   * Gets visible styles (not semi-hidden)
-   * @returns Array of visible styles
-   */
-  getVisibleStyles(): Style[] {
-    return this.getAllStyles().filter((style) => {
-      const props = style.getProperties();
-      return !props.semiHidden;
-    });
-  }
-
-  /**
-   * Gets styles sorted by UI priority
-   * Lower priority values appear first (higher importance)
-   * Styles without priority appear last
-   * @returns Array of styles sorted by priority
-   */
-  getStylesByPriority(): Style[] {
-    return this.getAllStyles().sort((a, b) => {
-      const propsA = a.getProperties();
-      const propsB = b.getProperties();
-
-      const priorityA = propsA.uiPriority ?? 999;
-      const priorityB = propsB.uiPriority ?? 999;
-
-      return priorityA - priorityB;
-    });
-  }
-
-  /**
-   * Gets the linked style for a given style
-   * @param styleId - Style ID to find the linked style for
-   * @returns The linked style, or undefined if not found
-   */
-  getLinkedStyle(styleId: string): Style | undefined {
-    const style = this.getStyle(styleId);
-    if (!style) {
-      return undefined;
-    }
-
-    const props = style.getProperties();
-    if (!props.link) {
-      return undefined;
-    }
-
-    return this.getStyle(props.link);
-  }
-
-  /**
-   * Gets all table styles (Phase 5.1)
-   * @returns Array of table styles
-   */
-  getTableStyles(): Style[] {
-    return this.getAllStyles().filter((style) => style.getType() === "table");
-  }
-
-  /**
-   * Creates and adds a table style (Phase 5.1)
-   * @param styleId - Style ID
-   * @param name - Style name
-   * @param basedOn - Base style ID (optional)
-   * @returns The created table style
-   */
-  createTableStyle(styleId: string, name: string, basedOn?: string): Style {
-    const style = Style.create({
-      styleId,
-      name,
-      type: "table",
-      basedOn,
-      customStyle: true,
-    });
-    this.addStyle(style);
-    return style;
-  }
-
-  /**
-   * Gets the number of styles
-   * @returns Number of styles
-   */
-  getStyleCount(): number {
-    return this.styles.size;
-  }
-
-  /**
-   * Clears all styles
-   * @returns This manager for chaining
-   */
-  clear(): this {
-    this.styles.clear();
-    return this;
-  }
-
-  /**
-   * Gets all available built-in style IDs
-   * @returns Array of built-in style IDs
-   */
-  static getBuiltInStyleIds(): string[] {
-    return Array.from(StylesManager.BUILT_IN_STYLE_FACTORIES.keys());
-  }
-
-  /**
-   * Checks if a style ID is a built-in style
-   * @param styleId - Style ID to check
-   * @returns True if the style is a built-in style
-   */
-  static isBuiltInStyle(styleId: string): boolean {
-    return StylesManager.BUILT_IN_STYLE_FACTORIES.has(styleId);
-  }
-
-  /**
-   * Gets statistics about loaded vs available styles
-   * @returns Object with style statistics
-   */
-  getStats(): {
-    loadedStyles: number;
-    availableBuiltInStyles: number;
-    customStyles: number;
-  } {
-    const loadedStyles = this.styles.size;
-    const customStyles = this.getAllStyles().filter(
-      (s) => s.getProperties().customStyle
-    ).length;
-
-    return {
-      loadedStyles,
-      availableBuiltInStyles: this.includeBuiltInStyles
-        ? StylesManager.BUILT_IN_STYLE_FACTORIES.size
-        : 0,
-      customStyles,
-    };
-  }
-
-  /**
-   * Creates a new paragraph style
-   * @param styleId - Unique style ID
-   * @param name - Display name
-   * @param basedOn - Parent style ID (optional)
-   * @returns The created style
-   */
-  createParagraphStyle(styleId: string, name: string, basedOn?: string): Style {
-    const style = Style.create({
-      styleId,
-      name,
-      type: "paragraph",
-      basedOn,
-      customStyle: true,
-    });
-    this.addStyle(style);
-    return style;
-  }
-
-  /**
-   * Creates a new character style
-   * @param styleId - Unique style ID
-   * @param name - Display name
-   * @param basedOn - Parent style ID (optional)
-   * @returns The created style
-   */
-  createCharacterStyle(styleId: string, name: string, basedOn?: string): Style {
-    const style = Style.create({
-      styleId,
-      name,
-      type: "character",
-      basedOn,
-      customStyle: true,
-    });
-    this.addStyle(style);
-    return style;
-  }
-
-  /**
-   * Sets the latent styles configuration
-   * @param config - Latent styles configuration
-   */
-  setLatentStyles(config: LatentStylesConfig): this {
-    this.latentStyles = config;
-    this._modified = true;
-    return this;
-  }
-
-  /**
-   * Gets the latent styles configuration
-   */
-  getLatentStyles(): LatentStylesConfig | undefined {
-    return this.latentStyles;
-  }
-
-  /**
-   * Adds a latent style exception
-   * @param exception - The exception to add
-   */
-  addLatentStyleException(exception: LatentStyleException): this {
-    // Replace existing exception for same name
-    const idx = this.latentStyleExceptions.findIndex(e => e.name === exception.name);
-    if (idx >= 0) {
-      this.latentStyleExceptions[idx] = exception;
-    } else {
-      this.latentStyleExceptions.push(exception);
-    }
-    this._modified = true;
-    return this;
-  }
-
-  /**
-   * Gets all latent style exceptions
-   */
-  getLatentStyleExceptions(): LatentStyleException[] {
-    return [...this.latentStyleExceptions];
-  }
-
-  /**
-   * Generates the complete styles.xml file
-   * @returns XML string for word/styles.xml
-   */
-  generateStylesXml(): string {
-    const builder = new XMLBuilder();
-
-    // Create styles element with namespace
-    const stylesChildren = [];
-
-    // Add document defaults
-    stylesChildren.push(this.generateDocDefaults());
-
-    // Add latent styles if configured (per ECMA-376 CT_Styles order: docDefaults, latentStyles, style*)
-    if (this.latentStyles) {
-      stylesChildren.push(this.generateLatentStyles());
-    }
-
-    // Add all styles
-    for (const style of this.getAllStyles()) {
-      stylesChildren.push(style.toXML());
-    }
-
-    builder.element(
-      "w:styles",
-      {
-        "xmlns:w":
-          "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
-        "xmlns:r":
-          "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
-      },
-      stylesChildren
-    );
-
-    return builder.build(true);
-  }
-
-  /**
-   * Generates document defaults
-   */
-  private generateDocDefaults() {
-    const rPrDefaultChildren = [
-      XMLBuilder.wSelf("rFonts", {
-        "w:ascii": "Calibri",
-        "w:hAnsi": "Calibri",
-        "w:eastAsia": "Calibri",
-        "w:cs": "Calibri",
-      }),
-      XMLBuilder.wSelf("sz", { "w:val": "22" }), // 11pt
-      XMLBuilder.wSelf("szCs", { "w:val": "22" }),
-      XMLBuilder.wSelf("lang", {
-        "w:val": "en-US",
-        "w:eastAsia": "en-US",
-        "w:bidi": "ar-SA",
-      }),
-    ];
-
-    const pPrDefaultChildren = [
-      XMLBuilder.wSelf("spacing", {
-        "w:after": "200",
-        "w:line": "276",
-        "w:lineRule": "auto",
-      }),
-    ];
-
-    return XMLBuilder.w("docDefaults", undefined, [
-      XMLBuilder.w("rPrDefault", undefined, [
-        XMLBuilder.w("rPr", undefined, rPrDefaultChildren),
-      ]),
-      XMLBuilder.w("pPrDefault", undefined, [
-        XMLBuilder.w("pPr", undefined, pPrDefaultChildren),
-      ]),
-    ]);
-  }
-
-  /**
-   * Generates the latent styles XML element
-   */
-  private generateLatentStyles() {
-    if (!this.latentStyles) return XMLBuilder.w("latentStyles", {}, []);
-
-    const attrs: Record<string, string> = {};
-    if (this.latentStyles.defaultLockedState !== undefined) {
-      attrs["w:defLockedState"] = this.latentStyles.defaultLockedState ? "1" : "0";
-    }
-    if (this.latentStyles.defaultUiPriority !== undefined) {
-      attrs["w:defUIPriority"] = this.latentStyles.defaultUiPriority.toString();
-    }
-    if (this.latentStyles.defaultSemiHidden !== undefined) {
-      attrs["w:defSemiHidden"] = this.latentStyles.defaultSemiHidden ? "1" : "0";
-    }
-    if (this.latentStyles.defaultUnhideWhenUsed !== undefined) {
-      attrs["w:defUnhideWhenUsed"] = this.latentStyles.defaultUnhideWhenUsed ? "1" : "0";
-    }
-    if (this.latentStyles.defaultQFormat !== undefined) {
-      attrs["w:defQFormat"] = this.latentStyles.defaultQFormat ? "1" : "0";
-    }
-    if (this.latentStyles.count !== undefined) {
-      attrs["w:count"] = this.latentStyles.count.toString();
-    }
-
-    const children = this.latentStyleExceptions.map(exc => {
-      const excAttrs: Record<string, string> = { "w:name": exc.name };
-      if (exc.locked !== undefined) excAttrs["w:locked"] = exc.locked ? "1" : "0";
-      if (exc.uiPriority !== undefined) excAttrs["w:uiPriority"] = exc.uiPriority.toString();
-      if (exc.semiHidden !== undefined) excAttrs["w:semiHidden"] = exc.semiHidden ? "1" : "0";
-      if (exc.unhideWhenUsed !== undefined) excAttrs["w:unhideWhenUsed"] = exc.unhideWhenUsed ? "1" : "0";
-      if (exc.qFormat !== undefined) excAttrs["w:qFormat"] = exc.qFormat ? "1" : "0";
-      return XMLBuilder.wSelf("lsdException", excAttrs);
-    });
-
-    return XMLBuilder.w("latentStyles", attrs, children);
-  }
-
-  /**
-   * Creates a new StylesManager with built-in styles
-   * @returns New StylesManager instance
-   */
-  static create(): StylesManager {
-    return new StylesManager(true);
-  }
-
-  /**
-   * Creates an empty StylesManager (no built-in styles)
-   * @returns New empty StylesManager instance
-   */
-  static createEmpty(): StylesManager {
-    return new StylesManager(false);
-  }
-
-  /**
-   * Validates styles.xml content for structure and correctness
-   *
-   * This performs string-based validation to avoid XML parsing corruption.
-   * It checks for:
-   * - Well-formed XML structure
-   * - Required w:styles root element
-   * - Valid style definitions
-   * - No duplicate style IDs
-   * - Required attributes
-   *
-   * @param xml - The raw styles.xml content to validate
-   * @returns ValidationResult with details about validity
-   */
-  static validate(xml: string): ValidationResult {
-    const result: ValidationResult = {
-      isValid: true,
-      errors: [],
-      warnings: [],
-      styleCount: 0,
-      styleIds: [],
-    };
-
-    // Check for empty or null
-    if (!xml || xml.trim().length === 0) {
-      result.isValid = false;
-      result.errors.push("Styles XML is empty or null");
-      return result;
-    }
-
-    // Check for common corruption patterns FIRST (before parsing)
-    // This catches double-encoding issues that would break the parser
-    if (xml.includes("&lt;w:") || xml.includes("&gt;")) {
-      result.isValid = false;
-      result.errors.push(
-        "XML contains escaped tags - possible double-encoding corruption"
-      );
-      return result;
-    }
-
-    // Skip complex XML structure validation - focus on w:styles specific validation
-    // Checking balanced tags with regex is unreliable and can give false positives
-
-    // Use XMLParser to extract root element
-    const stylesContent = XMLParser.extractBetweenTags(
-      xml,
-      "<w:styles",
-      "</w:styles>"
-    );
-    if (!stylesContent) {
-      result.isValid = false;
-      result.errors.push("Missing required <w:styles> root element");
-      return result;
-    }
-
-    // Check for namespace declaration
-    if (!xml.includes("xmlns:w=")) {
-      result.warnings.push("Missing WordprocessingML namespace declaration");
-    }
-
-    // Use XMLParser to extract all style elements
-    const styleElements = XMLParser.extractElements(stylesContent, "w:style");
-    result.styleCount = styleElements.length;
-
-    // Check if any styles found
-    if (styleElements.length === 0) {
-      result.warnings.push("No styles found in document");
-      return result;
-    }
-
-    // Check for styles without attributes (invalid)
-    const styleWithoutAttrs = styleElements.filter((el) => {
-      // Check if element has any attributes
-      const openTagEnd = el.indexOf(">");
-      const openTag = el.substring(0, openTagEnd);
-      return !openTag.includes("w:type") || !openTag.includes("w:styleId");
-    });
-
-    if (styleWithoutAttrs.length > 0) {
-      result.isValid = false;
-      result.errors.push(
-        "Style found without any attributes - w:type and w:styleId are required"
-      );
-    }
-
-    // Process each style element
-    const foundStyleIds = new Set<string>();
-
-    for (const styleElement of styleElements) {
-      // Extract styleId using XMLParser
-      const styleId = XMLParser.extractAttribute(styleElement, "w:styleId");
-      if (styleId) {
-        // Check for duplicates
-        if (foundStyleIds.has(styleId)) {
-          result.isValid = false;
-          result.errors.push(`Duplicate style ID found: "${styleId}"`);
-        } else {
-          foundStyleIds.add(styleId);
-          result.styleIds.push(styleId);
-        }
-      } else {
-        result.isValid = false;
-        result.errors.push("Style found without required w:styleId attribute");
-      }
-
-      // Extract and validate type using XMLParser
-      const type = XMLParser.extractAttribute(styleElement, "w:type");
-      if (type) {
-        if (!["paragraph", "character", "table", "numbering"].includes(type)) {
-          result.warnings.push(`Invalid style type: "${type}"`);
-        }
-      } else {
-        result.isValid = false;
-        result.errors.push("Style found without required w:type attribute");
-      }
-
-      // Check for circular references - extract basedOn value
-      const basedOnElement = XMLParser.extractElements(
-        styleElement,
-        "w:basedOn"
-      )[0];
-      if (basedOnElement && styleId) {
-        const basedOn = XMLParser.extractAttribute(basedOnElement, "w:val");
-        if (basedOn && styleId === basedOn) {
-          result.isValid = false;
-          result.errors.push(
-            `Circular reference detected: style "${styleId}" based on itself`
-          );
-        }
-      }
-    }
-
-    // Check for required Normal style
-    if (!foundStyleIds.has("Normal")) {
-      result.warnings.push(
-        'Missing "Normal" style - document may not render correctly'
-      );
-    }
-
-    // Check for BOM or invalid characters
-    if (xml.charCodeAt(0) === 0xfeff) {
-      result.warnings.push(
-        "XML contains BOM (Byte Order Mark) - may cause parsing issues"
-      );
-    }
-
-    // Summary
-    if (result.styleCount === 0) {
-      result.warnings.push("No styles found in document");
-    }
-
-    return result;
-  }
-
-  /**
-   * Searches styles by name (case-insensitive)
-   * @param searchTerm - Text to search for in style names
-   * @returns Array of styles whose names contain the search term
-   * @example
-   * ```typescript
-   * const headings = stylesManager.searchByName('heading');
-   * console.log(`Found ${headings.length} heading styles`);
-   * ```
-   */
-  searchByName(searchTerm: string): Style[] {
-    const term = searchTerm.toLowerCase();
-    return this.getAllStyles().filter((style) =>
-      style.getName().toLowerCase().includes(term)
-    );
-  }
-
-  /**
-   * Finds styles using a specific font
-   * @param fontName - Font family name to search for
-   * @returns Array of styles that use the specified font
-   * @example
-   * ```typescript
-   * const arialStyles = stylesManager.findByFont('Arial');
-   * console.log(`Found ${arialStyles.length} styles using Arial font`);
-   * ```
-   */
-  findByFont(fontName: string): Style[] {
-    return this.getAllStyles().filter((style) => {
-      const runFormatting = style.getRunFormatting();
-      return runFormatting?.font === fontName;
-    });
-  }
-
-  /**
-   * Finds styles with specific properties using a predicate function
-   * @param predicate - Filter function that returns true for styles to include
-   * @returns Array of styles matching the predicate
-   * @example
-   * ```typescript
-   * // Find all paragraph styles
-   * const paraStyles = stylesManager.findStyles(s => s.getType() === 'paragraph');
-   *
-   * // Find styles with custom formatting
-   * const customStyles = stylesManager.findStyles(s => s.getProperties().customStyle);
-   *
-   * // Find styles with specific formatting
-   * const boldStyles = stylesManager.findStyles(s => s.getRunFormatting()?.bold);
-   * ```
-   */
-  findStyles(predicate: (style: Style) => boolean): Style[] {
-    return this.getAllStyles().filter(predicate);
-  }
-
-  /**
-   * Finds unused styles (not referenced by any paragraphs)
-   * @param paragraphs - All paragraphs in the document to check against
-   * @returns Array of unused style IDs
-   * @example
-   * ```typescript
-   * const doc = Document.create();
-   * const unused = stylesManager.findUnusedStyles(doc.getAllParagraphs());
-   * console.log(`Found ${unused.length} unused styles: ${unused.join(', ')}`);
-   * ```
-   */
-  findUnusedStyles(paragraphs: Paragraph[]): string[] {
-    const usedStyles = new Set<string>();
-
-    // Collect all style IDs used by paragraphs
-    for (const para of paragraphs) {
-      const styleId = para.getStyle();
-      if (styleId) {
-        usedStyles.add(styleId);
-      }
-    }
-
-    // Get all style IDs and filter out used ones
-    const allStyleIds = this.getAllStyles().map((style) => style.getStyleId());
-    return allStyleIds.filter((styleId) => !usedStyles.has(styleId));
-  }
-
-  /**
-   * Removes all unused styles from the document
-   * @param paragraphs - All paragraphs in the document to check against
-   * @returns Number of styles removed
-   * @example
-   * ```typescript
-   * const doc = Document.create();
-   * const removedCount = stylesManager.cleanupUnusedStyles(doc.getAllParagraphs());
-   * console.log(`Cleaned up ${removedCount} unused styles`);
-   * ```
-   */
-  cleanupUnusedStyles(paragraphs: Paragraph[]): number {
-    const unused = this.findUnusedStyles(paragraphs);
-    let count = 0;
-
-    for (const styleId of unused) {
-      // Don't remove built-in styles
-      if (!StylesManager.isBuiltInStyle(styleId)) {
-        if (this.removeStyle(styleId)) {
-          count++;
-        }
-      }
-    }
-
-    return count;
-  }
-
-  /**
-   * Validates all style references for broken or circular dependencies
-   * @returns Validation result with broken references and circular dependencies
-   * @example
-   * ```typescript
-   * const validation = stylesManager.validateStyleReferences();
-   * if (!validation.valid) {
-   *   console.log('Broken references:', validation.brokenReferences);
-   *   console.log('Circular references:', validation.circularReferences);
-   * }
-   * ```
-   */
-  validateStyleReferences(): {
-    valid: boolean;
-    brokenReferences: { styleId: string; basedOn: string }[];
-    circularReferences: string[][];
-  } {
-    const broken: { styleId: string; basedOn: string }[] = [];
-    const circular: string[][] = [];
-    const checkedForCycles = new Set<string>();
-
-    for (const style of this.getAllStyles()) {
-      const props = style.getProperties();
-
-      // Check basedOn references exist
-      if (props.basedOn && !this.hasStyle(props.basedOn)) {
-        broken.push({ styleId: props.styleId, basedOn: props.basedOn });
-      }
-
-      // Check for circular references (only if not already checked as part of another cycle)
-      if (!checkedForCycles.has(props.styleId)) {
-        const result = this.hasCircularReference(props.styleId);
-        if (result.hasCircularRef && result.cyclePath) {
-          circular.push(result.cyclePath);
-          // Mark all styles in this cycle as checked
-          result.cyclePath.forEach((id) => checkedForCycles.add(id));
-        }
-      }
-    }
-
-    return {
-      valid: broken.length === 0 && circular.length === 0,
-      brokenReferences: broken,
-      circularReferences: circular,
-    };
-  }
-
-  /**
-   * Gets the complete inheritance chain for a style
-   * @param styleId - Style ID to analyze
-   * @returns Array of styles from base to derived (base style first)
-   * @throws Error if style doesn't exist or circular reference detected
-   * @example
-   * ```typescript
-   * const chain = stylesManager.getInheritanceChain('Heading1');
-   * console.log('Inheritance chain:', chain.map(s => s.getName()));
-   * // Output: ['Normal', 'Heading1'] (Normal is base, Heading1 inherits from it)
-   * ```
-   */
-  getInheritanceChain(styleId: string): Style[] {
-    const chain: Style[] = [];
-    const visited = new Set<string>(); // Track visited styles to detect cycles
-    let current = this.getStyle(styleId);
-
-    if (!current) {
-      throw new Error(`Style '${styleId}' not found`);
-    }
-
-    while (current) {
-      const currentId = current.getStyleId();
-
-      // Detect circular reference
-      if (visited.has(currentId)) {
-        const cycle = [...chain.map((s) => s.getStyleId()), currentId];
-        throw new Error(
-          `Circular style reference detected: ${cycle.join(" -> ")}. ` +
-            `Style '${currentId}' references itself through inheritance chain.`
-        );
-      }
-
-      visited.add(currentId);
-      chain.unshift(current); // Add to beginning to maintain base-to-derived order
-      const props = current.getProperties();
-      current = props.basedOn ? this.getStyle(props.basedOn) : undefined;
-    }
-
-    return chain;
-  }
-
-  /**
-   * Checks if a style has circular references in its inheritance chain
-   * @param styleId - Style ID to check
-   * @returns Object with hasCircularRef flag and the cycle path if found
-   * @example
-   * ```typescript
-   * const result = stylesManager.hasCircularReference('MyStyle');
-   * if (result.hasCircularRef) {
-   *   console.log('Circular reference found:', result.cyclePath?.join(' -> '));
-   * }
-   * ```
-   */
-  hasCircularReference(styleId: string): {
-    hasCircularRef: boolean;
-    cyclePath?: string[];
-  } {
-    const visited = new Set<string>();
-    const path: string[] = [];
-    let current = this.getStyle(styleId);
-
-    while (current) {
-      const currentId = current.getStyleId();
-
-      if (visited.has(currentId)) {
-        path.push(currentId);
-        return { hasCircularRef: true, cyclePath: path };
-      }
-
-      visited.add(currentId);
-      path.push(currentId);
-      const props = current.getProperties();
-      current = props.basedOn ? this.getStyle(props.basedOn) : undefined;
-    }
-
-    return { hasCircularRef: false };
-  }
-
-  /**
-   * Gets all styles that inherit from a base style
-   * @param baseStyleId - Base style ID to find children for
-   * @returns Array of styles that inherit from the base style
-   * @example
-   * ```typescript
-   * const children = stylesManager.getDerivedStyles('Normal');
-   * console.log(`Styles based on Normal: ${children.map(s => s.getName()).join(', ')}`);
-   * ```
-   */
-  getDerivedStyles(baseStyleId: string): Style[] {
-    return this.getAllStyles().filter(
-      (style) => style.getProperties().basedOn === baseStyleId
-    );
-  }
-
-  /**
-   * Exports a single style as JSON string
-   * @param styleId - Style ID to export
-   * @returns JSON representation of the style
-   * @throws Error if style doesn't exist
-   * @example
-   * ```typescript
-   * const json = stylesManager.exportStyle('Heading1');
-   * console.log('Style JSON:', json);
-   *
-   * // Save to file
-   * await fs.writeFile('heading1-style.json', json);
-   * ```
-   */
-  exportStyle(styleId: string): string {
-    const style = this.getStyle(styleId);
-    if (!style) {
-      throw new Error(`Style '${styleId}' not found`);
-    }
-    return JSON.stringify(style.getProperties(), null, 2);
-  }
-
-  /**
-   * Imports a style from JSON string
-   * @param json - JSON string containing style properties
-   * @returns The imported style
-   * @throws Error if JSON is invalid or style creation fails
-   * @example
-   * ```typescript
-   * const json = await fs.readFile('custom-style.json', 'utf8');
-   * const style = stylesManager.importStyle(json);
-   * console.log(`Imported style: ${style.getName()}`);
-   * ```
-   */
-  importStyle(json: string): Style {
-    try {
-      const props = JSON.parse(json);
-      const style = Style.create(props);
-      this.addStyle(style);
-      return style;
-    } catch (error: unknown) {
-      throw new Error(
-        `Failed to import style: ${
-          error instanceof Error ? error.message : "Invalid JSON"
-        }`
-      );
-    }
-  }
-
-  /**
-   * Exports all styles as JSON string
-   * @returns JSON array of all style properties
-   * @example
-   * ```typescript
-   * const allStylesJson = stylesManager.exportAllStyles();
-   * console.log('All styles exported');
-   *
-   * // Save to file
-   * await fs.writeFile('all-styles.json', allStylesJson);
-   * ```
-   */
-  exportAllStyles(): string {
-    const styles = this.getAllStyles().map((style) => style.getProperties());
-    return JSON.stringify(styles, null, 2);
-  }
-
-  /**
-   * Imports multiple styles from JSON array string
-   * @param json - JSON string containing array of style properties
-   * @returns Array of imported styles
-   * @throws Error if JSON is invalid or style creation fails
-   * @example
-   * ```typescript
-   * const json = await fs.readFile('styles-collection.json', 'utf8');
-   * const styles = stylesManager.importStyles(json);
-   * console.log(`Imported ${styles.length} styles`);
-   * ```
-   */
-  importStyles(json: string): Style[] {
-    try {
-      const propsArray = JSON.parse(json);
-      if (!Array.isArray(propsArray)) {
-        throw new Error("JSON must contain an array of style properties");
-      }
-
-      const styles: Style[] = [];
-      for (const props of propsArray) {
-        const style = Style.create(props);
-        this.addStyle(style);
-        styles.push(style);
-      }
-
-      return styles;
-    } catch (error: unknown) {
-      throw new Error(
-        `Failed to import styles: ${
-          error instanceof Error ? error.message : "Invalid JSON"
-        }`
-      );
-    }
-  }
-}
+/**
+ * StylesManager - Manages the collection of styles in a document
+ * Handles style registration, retrieval, and styles.xml generation
+ */
+
+import { Paragraph } from '../elements/Paragraph';
+import { XMLBuilder } from '../xml/XMLBuilder';
+import { XMLParser } from '../xml/XMLParser';
+import { Style, StyleType } from './Style';
+
+/**
+ * Configuration for latent styles (w:latentStyles per ECMA-376 §17.7.4.6)
+ * Controls which built-in styles are shown in the Word UI gallery
+ */
+export interface LatentStylesConfig {
+  /** Default locked state for built-in styles */
+  defaultLockedState?: boolean;
+  /** Default UI priority for built-in styles */
+  defaultUiPriority?: number;
+  /** Default semi-hidden state */
+  defaultSemiHidden?: boolean;
+  /** Default unhide-when-used state */
+  defaultUnhideWhenUsed?: boolean;
+  /** Default quick format flag */
+  defaultQFormat?: boolean;
+  /** Total count of style definitions */
+  count?: number;
+}
+
+/**
+ * Exception to latent style defaults (w:lsdException per ECMA-376 §17.7.4.7)
+ */
+export interface LatentStyleException {
+  /** Style name */
+  name: string;
+  /** Override: locked state */
+  locked?: boolean;
+  /** Override: UI priority */
+  uiPriority?: number;
+  /** Override: semi-hidden */
+  semiHidden?: boolean;
+  /** Override: unhide when used */
+  unhideWhenUsed?: boolean;
+  /** Override: quick format */
+  qFormat?: boolean;
+}
+
+/**
+ * Result of XML validation
+ */
+export interface ValidationResult {
+  /** Whether the XML is valid */
+  isValid: boolean;
+  /** Validation errors if any */
+  errors: string[];
+  /** Validation warnings if any */
+  warnings: string[];
+  /** Number of styles found */
+  styleCount: number;
+  /** List of style IDs found */
+  styleIds: string[];
+}
+
+/**
+ * Manages document styles
+ */
+export class StylesManager {
+  private styles = new Map<string, Style>();
+  private includeBuiltInStyles: boolean;
+
+  // Track if styles have been modified (for XML preservation)
+  private _modified = false;
+
+  // Track which specific styles have been modified (for selective merging)
+  private _modifiedStyleIds = new Set<string>();
+
+  // Latent styles configuration
+  private latentStyles?: LatentStylesConfig;
+  private latentStyleExceptions: LatentStyleException[] = [];
+
+  /**
+   * Registry of built-in style factory functions
+   * Maps style ID to factory function for lazy loading
+   */
+  private static readonly BUILT_IN_STYLE_FACTORIES = new Map<string, () => Style>([
+    ['Normal', () => Style.createNormalStyle()],
+    ['Heading1', () => Style.createHeadingStyle(1)],
+    ['Heading2', () => Style.createHeadingStyle(2)],
+    ['Heading3', () => Style.createHeadingStyle(3)],
+    ['Heading4', () => Style.createHeadingStyle(4)],
+    ['Heading5', () => Style.createHeadingStyle(5)],
+    ['Heading6', () => Style.createHeadingStyle(6)],
+    ['Heading7', () => Style.createHeadingStyle(7)],
+    ['Heading8', () => Style.createHeadingStyle(8)],
+    ['Heading9', () => Style.createHeadingStyle(9)],
+    ['Heading1Char', () => Style.createHeadingCharStyle(1)],
+    ['Heading2Char', () => Style.createHeadingCharStyle(2)],
+    ['Heading3Char', () => Style.createHeadingCharStyle(3)],
+    ['Heading4Char', () => Style.createHeadingCharStyle(4)],
+    ['Heading5Char', () => Style.createHeadingCharStyle(5)],
+    ['Heading6Char', () => Style.createHeadingCharStyle(6)],
+    ['Heading7Char', () => Style.createHeadingCharStyle(7)],
+    ['Heading8Char', () => Style.createHeadingCharStyle(8)],
+    ['Heading9Char', () => Style.createHeadingCharStyle(9)],
+    ['Title', () => Style.createTitleStyle()],
+    ['Subtitle', () => Style.createSubtitleStyle()],
+    ['ListParagraph', () => Style.createListParagraphStyle()],
+    ['TOCHeading', () => Style.createTOCHeadingStyle()],
+    ['TableNormal', () => Style.createTableNormalStyle()],
+    ['TableGrid', () => Style.createTableGridStyle()],
+  ]);
+
+  /**
+   * Creates a new StylesManager
+   * @param includeBuiltInStyles - Whether to include built-in styles (default: true)
+   */
+  constructor(includeBuiltInStyles = true) {
+    this.includeBuiltInStyles = includeBuiltInStyles;
+
+    // Always load Normal style if built-in styles are enabled
+    // Normal is required and referenced by most other styles
+    if (includeBuiltInStyles) {
+      this.ensureStyleLoaded('Normal');
+    }
+  }
+
+  /**
+   * Ensures a built-in style is loaded (lazy loading)
+   * @param styleId - Style ID to load
+   */
+  private ensureStyleLoaded(styleId: string): void {
+    // Already loaded?
+    if (this.styles.has(styleId)) {
+      return;
+    }
+
+    // Built-in styles disabled?
+    if (!this.includeBuiltInStyles) {
+      return;
+    }
+
+    // Is this a built-in style?
+    const factory = StylesManager.BUILT_IN_STYLE_FACTORIES.get(styleId);
+    if (factory) {
+      this.styles.set(styleId, factory());
+    }
+  }
+
+  /**
+   * Adds a style to the collection
+   * @param style - Style to add
+   * @returns This manager for chaining
+   */
+  addStyle(style: Style): this {
+    const existing = this.styles.get(style.getStyleId());
+    if (existing) {
+      // Preserve isDefault flag if replacing an existing default style
+      if (existing.getIsDefault() && !style.getIsDefault()) {
+        style.setIsDefault(true);
+      }
+      // Preserve structural properties from existing style if not explicitly set on new
+      const newProps = style.getProperties();
+      const existingProps = existing.getProperties();
+      if (newProps.basedOn === undefined && existingProps.basedOn !== undefined) {
+        style.setBasedOn(existingProps.basedOn);
+      }
+      if (newProps.next === undefined && existingProps.next !== undefined) {
+        style.setNext(existingProps.next);
+      }
+      if (newProps.link === undefined && existingProps.link !== undefined) {
+        style.setLink(existingProps.link);
+      }
+      if (newProps.uiPriority === undefined && existingProps.uiPriority !== undefined) {
+        style.setUiPriority(existingProps.uiPriority);
+      }
+    }
+    this.styles.set(style.getStyleId(), style);
+    this._modifiedStyleIds.add(style.getStyleId());
+    this._modified = true;
+    return this;
+  }
+
+  /**
+   * Gets a style by ID
+   * Lazy-loads built-in styles on first access
+   * @param styleId - Style ID to retrieve
+   * @returns The style, or undefined if not found
+   */
+  getStyle(styleId: string): Style | undefined {
+    // Ensure built-in style is loaded if applicable
+    this.ensureStyleLoaded(styleId);
+    return this.styles.get(styleId);
+  }
+
+  /**
+   * Checks if a style exists or can be loaded
+   * @param styleId - Style ID to check
+   * @returns True if the style exists or is a built-in style
+   */
+  hasStyle(styleId: string): boolean {
+    // Check if already loaded
+    if (this.styles.has(styleId)) {
+      return true;
+    }
+
+    // Check if it's a built-in style that can be loaded
+    return this.includeBuiltInStyles && StylesManager.BUILT_IN_STYLE_FACTORIES.has(styleId);
+  }
+
+  /**
+   * Removes a style from the collection
+   * @param styleId - Style ID to remove
+   * @returns True if the style was removed
+   */
+  removeStyle(styleId: string): boolean {
+    return this.styles.delete(styleId);
+  }
+
+  /**
+   * Gets all styles
+   * @returns Array of all styles
+   */
+  getAllStyles(): Style[] {
+    return Array.from(this.styles.values());
+  }
+
+  /**
+   * Checks if styles have been modified since loading
+   * Used for XML preservation optimization
+   * @returns True if styles were added or modified
+   */
+  isModified(): boolean {
+    return this._modified;
+  }
+
+  /**
+   * Resets the modified flag
+   * Called after parsing to indicate that loaded styles don't count as modifications
+   */
+  resetModified(): void {
+    this._modified = false;
+    this._modifiedStyleIds.clear();
+  }
+
+  /**
+   * Gets the IDs of styles that have been modified since loading
+   * Used for selective merging with original styles.xml
+   * @returns Set of modified style IDs
+   */
+  getModifiedStyleIds(): Set<string> {
+    return new Set(this._modifiedStyleIds);
+  }
+
+  /**
+   * Gets styles by type
+   * @param type - Style type to filter by
+   * @returns Array of styles matching the type
+   */
+  getStylesByType(type: StyleType): Style[] {
+    return this.getAllStyles().filter((style) => style.getType() === type);
+  }
+
+  /**
+   * Gets quick styles (styles that appear in the style gallery)
+   * A style appears in the gallery when qFormat=true AND semiHidden=false
+   * @returns Array of quick styles
+   */
+  getQuickStyles(): Style[] {
+    return this.getAllStyles().filter((style) => {
+      const props = style.getProperties();
+      const isQuick = props.qFormat === true || (!props.customStyle && props.qFormat !== false);
+      const isVisible = !props.semiHidden;
+      return isQuick && isVisible;
+    });
+  }
+
+  /**
+   * Gets visible styles (not semi-hidden)
+   * @returns Array of visible styles
+   */
+  getVisibleStyles(): Style[] {
+    return this.getAllStyles().filter((style) => {
+      const props = style.getProperties();
+      return !props.semiHidden;
+    });
+  }
+
+  /**
+   * Gets styles sorted by UI priority
+   * Lower priority values appear first (higher importance)
+   * Styles without priority appear last
+   * @returns Array of styles sorted by priority
+   */
+  getStylesByPriority(): Style[] {
+    return this.getAllStyles().sort((a, b) => {
+      const propsA = a.getProperties();
+      const propsB = b.getProperties();
+
+      const priorityA = propsA.uiPriority ?? 999;
+      const priorityB = propsB.uiPriority ?? 999;
+
+      return priorityA - priorityB;
+    });
+  }
+
+  /**
+   * Gets the linked style for a given style
+   * @param styleId - Style ID to find the linked style for
+   * @returns The linked style, or undefined if not found
+   */
+  getLinkedStyle(styleId: string): Style | undefined {
+    const style = this.getStyle(styleId);
+    if (!style) {
+      return undefined;
+    }
+
+    const props = style.getProperties();
+    if (!props.link) {
+      return undefined;
+    }
+
+    return this.getStyle(props.link);
+  }
+
+  /**
+   * Gets all table styles (Phase 5.1)
+   * @returns Array of table styles
+   */
+  getTableStyles(): Style[] {
+    return this.getAllStyles().filter((style) => style.getType() === 'table');
+  }
+
+  /**
+   * Creates and adds a table style (Phase 5.1)
+   * @param styleId - Style ID
+   * @param name - Style name
+   * @param basedOn - Base style ID (optional)
+   * @returns The created table style
+   */
+  createTableStyle(styleId: string, name: string, basedOn?: string): Style {
+    const style = Style.create({
+      styleId,
+      name,
+      type: 'table',
+      basedOn,
+      customStyle: true,
+    });
+    this.addStyle(style);
+    return style;
+  }
+
+  /**
+   * Gets the number of styles
+   * @returns Number of styles
+   */
+  getStyleCount(): number {
+    return this.styles.size;
+  }
+
+  /**
+   * Clears all styles
+   * @returns This manager for chaining
+   */
+  clear(): this {
+    this.styles.clear();
+    return this;
+  }
+
+  /**
+   * Gets all available built-in style IDs
+   * @returns Array of built-in style IDs
+   */
+  static getBuiltInStyleIds(): string[] {
+    return Array.from(StylesManager.BUILT_IN_STYLE_FACTORIES.keys());
+  }
+
+  /**
+   * Checks if a style ID is a built-in style
+   * @param styleId - Style ID to check
+   * @returns True if the style is a built-in style
+   */
+  static isBuiltInStyle(styleId: string): boolean {
+    return StylesManager.BUILT_IN_STYLE_FACTORIES.has(styleId);
+  }
+
+  /**
+   * Gets statistics about loaded vs available styles
+   * @returns Object with style statistics
+   */
+  getStats(): {
+    loadedStyles: number;
+    availableBuiltInStyles: number;
+    customStyles: number;
+  } {
+    const loadedStyles = this.styles.size;
+    const customStyles = this.getAllStyles().filter((s) => s.getProperties().customStyle).length;
+
+    return {
+      loadedStyles,
+      availableBuiltInStyles: this.includeBuiltInStyles
+        ? StylesManager.BUILT_IN_STYLE_FACTORIES.size
+        : 0,
+      customStyles,
+    };
+  }
+
+  /**
+   * Creates a new paragraph style
+   * @param styleId - Unique style ID
+   * @param name - Display name
+   * @param basedOn - Parent style ID (optional)
+   * @returns The created style
+   */
+  createParagraphStyle(styleId: string, name: string, basedOn?: string): Style {
+    const style = Style.create({
+      styleId,
+      name,
+      type: 'paragraph',
+      basedOn,
+      customStyle: true,
+    });
+    this.addStyle(style);
+    return style;
+  }
+
+  /**
+   * Creates a new character style
+   * @param styleId - Unique style ID
+   * @param name - Display name
+   * @param basedOn - Parent style ID (optional)
+   * @returns The created style
+   */
+  createCharacterStyle(styleId: string, name: string, basedOn?: string): Style {
+    const style = Style.create({
+      styleId,
+      name,
+      type: 'character',
+      basedOn,
+      customStyle: true,
+    });
+    this.addStyle(style);
+    return style;
+  }
+
+  /**
+   * Sets the latent styles configuration
+   * @param config - Latent styles configuration
+   */
+  setLatentStyles(config: LatentStylesConfig): this {
+    this.latentStyles = config;
+    this._modified = true;
+    return this;
+  }
+
+  /**
+   * Gets the latent styles configuration
+   */
+  getLatentStyles(): LatentStylesConfig | undefined {
+    return this.latentStyles;
+  }
+
+  /**
+   * Adds a latent style exception
+   * @param exception - The exception to add
+   */
+  addLatentStyleException(exception: LatentStyleException): this {
+    // Replace existing exception for same name
+    const idx = this.latentStyleExceptions.findIndex((e) => e.name === exception.name);
+    if (idx >= 0) {
+      this.latentStyleExceptions[idx] = exception;
+    } else {
+      this.latentStyleExceptions.push(exception);
+    }
+    this._modified = true;
+    return this;
+  }
+
+  /**
+   * Gets all latent style exceptions
+   */
+  getLatentStyleExceptions(): LatentStyleException[] {
+    return [...this.latentStyleExceptions];
+  }
+
+  /**
+   * Generates the complete styles.xml file
+   * @returns XML string for word/styles.xml
+   */
+  generateStylesXml(): string {
+    const builder = new XMLBuilder();
+
+    // Create styles element with namespace
+    const stylesChildren = [];
+
+    // Add document defaults
+    stylesChildren.push(this.generateDocDefaults());
+
+    // Add latent styles if configured (per ECMA-376 CT_Styles order: docDefaults, latentStyles, style*)
+    if (this.latentStyles) {
+      stylesChildren.push(this.generateLatentStyles());
+    }
+
+    // Add all styles
+    for (const style of this.getAllStyles()) {
+      stylesChildren.push(style.toXML());
+    }
+
+    builder.element(
+      'w:styles',
+      {
+        'xmlns:w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+        'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+      },
+      stylesChildren
+    );
+
+    return builder.build(true);
+  }
+
+  /**
+   * Generates document defaults
+   */
+  private generateDocDefaults() {
+    const rPrDefaultChildren = [
+      XMLBuilder.wSelf('rFonts', {
+        'w:ascii': 'Calibri',
+        'w:hAnsi': 'Calibri',
+        'w:eastAsia': 'Calibri',
+        'w:cs': 'Calibri',
+      }),
+      XMLBuilder.wSelf('sz', { 'w:val': '22' }), // 11pt
+      XMLBuilder.wSelf('szCs', { 'w:val': '22' }),
+      XMLBuilder.wSelf('lang', {
+        'w:val': 'en-US',
+        'w:eastAsia': 'en-US',
+        'w:bidi': 'ar-SA',
+      }),
+    ];
+
+    const pPrDefaultChildren = [
+      XMLBuilder.wSelf('spacing', {
+        'w:after': '200',
+        'w:line': '276',
+        'w:lineRule': 'auto',
+      }),
+    ];
+
+    return XMLBuilder.w('docDefaults', undefined, [
+      XMLBuilder.w('rPrDefault', undefined, [XMLBuilder.w('rPr', undefined, rPrDefaultChildren)]),
+      XMLBuilder.w('pPrDefault', undefined, [XMLBuilder.w('pPr', undefined, pPrDefaultChildren)]),
+    ]);
+  }
+
+  /**
+   * Generates the latent styles XML element
+   */
+  private generateLatentStyles() {
+    if (!this.latentStyles) return XMLBuilder.w('latentStyles', {}, []);
+
+    const attrs: Record<string, string> = {};
+    if (this.latentStyles.defaultLockedState !== undefined) {
+      attrs['w:defLockedState'] = this.latentStyles.defaultLockedState ? '1' : '0';
+    }
+    if (this.latentStyles.defaultUiPriority !== undefined) {
+      attrs['w:defUIPriority'] = this.latentStyles.defaultUiPriority.toString();
+    }
+    if (this.latentStyles.defaultSemiHidden !== undefined) {
+      attrs['w:defSemiHidden'] = this.latentStyles.defaultSemiHidden ? '1' : '0';
+    }
+    if (this.latentStyles.defaultUnhideWhenUsed !== undefined) {
+      attrs['w:defUnhideWhenUsed'] = this.latentStyles.defaultUnhideWhenUsed ? '1' : '0';
+    }
+    if (this.latentStyles.defaultQFormat !== undefined) {
+      attrs['w:defQFormat'] = this.latentStyles.defaultQFormat ? '1' : '0';
+    }
+    if (this.latentStyles.count !== undefined) {
+      attrs['w:count'] = this.latentStyles.count.toString();
+    }
+
+    const children = this.latentStyleExceptions.map((exc) => {
+      const excAttrs: Record<string, string> = { 'w:name': exc.name };
+      if (exc.locked !== undefined) excAttrs['w:locked'] = exc.locked ? '1' : '0';
+      if (exc.uiPriority !== undefined) excAttrs['w:uiPriority'] = exc.uiPriority.toString();
+      if (exc.semiHidden !== undefined) excAttrs['w:semiHidden'] = exc.semiHidden ? '1' : '0';
+      if (exc.unhideWhenUsed !== undefined)
+        excAttrs['w:unhideWhenUsed'] = exc.unhideWhenUsed ? '1' : '0';
+      if (exc.qFormat !== undefined) excAttrs['w:qFormat'] = exc.qFormat ? '1' : '0';
+      return XMLBuilder.wSelf('lsdException', excAttrs);
+    });
+
+    return XMLBuilder.w('latentStyles', attrs, children);
+  }
+
+  /**
+   * Creates a new StylesManager with built-in styles
+   * @returns New StylesManager instance
+   */
+  static create(): StylesManager {
+    return new StylesManager(true);
+  }
+
+  /**
+   * Creates an empty StylesManager (no built-in styles)
+   * @returns New empty StylesManager instance
+   */
+  static createEmpty(): StylesManager {
+    return new StylesManager(false);
+  }
+
+  /**
+   * Validates styles.xml content for structure and correctness
+   *
+   * This performs string-based validation to avoid XML parsing corruption.
+   * It checks for:
+   * - Well-formed XML structure
+   * - Required w:styles root element
+   * - Valid style definitions
+   * - No duplicate style IDs
+   * - Required attributes
+   *
+   * @param xml - The raw styles.xml content to validate
+   * @returns ValidationResult with details about validity
+   */
+  static validate(xml: string): ValidationResult {
+    const result: ValidationResult = {
+      isValid: true,
+      errors: [],
+      warnings: [],
+      styleCount: 0,
+      styleIds: [],
+    };
+
+    // Check for empty or null
+    if (!xml || xml.trim().length === 0) {
+      result.isValid = false;
+      result.errors.push('Styles XML is empty or null');
+      return result;
+    }
+
+    // Check for common corruption patterns FIRST (before parsing)
+    // This catches double-encoding issues that would break the parser
+    if (xml.includes('&lt;w:') || xml.includes('&gt;')) {
+      result.isValid = false;
+      result.errors.push('XML contains escaped tags - possible double-encoding corruption');
+      return result;
+    }
+
+    // Skip complex XML structure validation - focus on w:styles specific validation
+    // Checking balanced tags with regex is unreliable and can give false positives
+
+    // Use XMLParser to extract root element
+    const stylesContent = XMLParser.extractBetweenTags(xml, '<w:styles', '</w:styles>');
+    if (!stylesContent) {
+      result.isValid = false;
+      result.errors.push('Missing required <w:styles> root element');
+      return result;
+    }
+
+    // Check for namespace declaration
+    if (!xml.includes('xmlns:w=')) {
+      result.warnings.push('Missing WordprocessingML namespace declaration');
+    }
+
+    // Use XMLParser to extract all style elements
+    const styleElements = XMLParser.extractElements(stylesContent, 'w:style');
+    result.styleCount = styleElements.length;
+
+    // Check if any styles found
+    if (styleElements.length === 0) {
+      result.warnings.push('No styles found in document');
+      return result;
+    }
+
+    // Check for styles without attributes (invalid)
+    const styleWithoutAttrs = styleElements.filter((el) => {
+      // Check if element has any attributes
+      const openTagEnd = el.indexOf('>');
+      const openTag = el.substring(0, openTagEnd);
+      return !openTag.includes('w:type') || !openTag.includes('w:styleId');
+    });
+
+    if (styleWithoutAttrs.length > 0) {
+      result.isValid = false;
+      result.errors.push('Style found without any attributes - w:type and w:styleId are required');
+    }
+
+    // Process each style element
+    const foundStyleIds = new Set<string>();
+
+    for (const styleElement of styleElements) {
+      // Extract styleId using XMLParser
+      const styleId = XMLParser.extractAttribute(styleElement, 'w:styleId');
+      if (styleId) {
+        // Check for duplicates
+        if (foundStyleIds.has(styleId)) {
+          result.isValid = false;
+          result.errors.push(`Duplicate style ID found: "${styleId}"`);
+        } else {
+          foundStyleIds.add(styleId);
+          result.styleIds.push(styleId);
+        }
+      } else {
+        result.isValid = false;
+        result.errors.push('Style found without required w:styleId attribute');
+      }
+
+      // Extract and validate type using XMLParser
+      const type = XMLParser.extractAttribute(styleElement, 'w:type');
+      if (type) {
+        if (!['paragraph', 'character', 'table', 'numbering'].includes(type)) {
+          result.warnings.push(`Invalid style type: "${type}"`);
+        }
+      } else {
+        result.isValid = false;
+        result.errors.push('Style found without required w:type attribute');
+      }
+
+      // Check for circular references - extract basedOn value
+      const basedOnElement = XMLParser.extractElements(styleElement, 'w:basedOn')[0];
+      if (basedOnElement && styleId) {
+        const basedOn = XMLParser.extractAttribute(basedOnElement, 'w:val');
+        if (basedOn && styleId === basedOn) {
+          result.isValid = false;
+          result.errors.push(`Circular reference detected: style "${styleId}" based on itself`);
+        }
+      }
+    }
+
+    // Check for required Normal style
+    if (!foundStyleIds.has('Normal')) {
+      result.warnings.push('Missing "Normal" style - document may not render correctly');
+    }
+
+    // Check for BOM or invalid characters
+    if (xml.charCodeAt(0) === 0xfeff) {
+      result.warnings.push('XML contains BOM (Byte Order Mark) - may cause parsing issues');
+    }
+
+    // Summary
+    if (result.styleCount === 0) {
+      result.warnings.push('No styles found in document');
+    }
+
+    return result;
+  }
+
+  /**
+   * Searches styles by name (case-insensitive)
+   * @param searchTerm - Text to search for in style names
+   * @returns Array of styles whose names contain the search term
+   * @example
+   * ```typescript
+   * const headings = stylesManager.searchByName('heading');
+   * console.log(`Found ${headings.length} heading styles`);
+   * ```
+   */
+  searchByName(searchTerm: string): Style[] {
+    const term = searchTerm.toLowerCase();
+    return this.getAllStyles().filter((style) => style.getName().toLowerCase().includes(term));
+  }
+
+  /**
+   * Finds styles using a specific font
+   * @param fontName - Font family name to search for
+   * @returns Array of styles that use the specified font
+   * @example
+   * ```typescript
+   * const arialStyles = stylesManager.findByFont('Arial');
+   * console.log(`Found ${arialStyles.length} styles using Arial font`);
+   * ```
+   */
+  findByFont(fontName: string): Style[] {
+    return this.getAllStyles().filter((style) => {
+      const runFormatting = style.getRunFormatting();
+      return runFormatting?.font === fontName;
+    });
+  }
+
+  /**
+   * Finds styles with specific properties using a predicate function
+   * @param predicate - Filter function that returns true for styles to include
+   * @returns Array of styles matching the predicate
+   * @example
+   * ```typescript
+   * // Find all paragraph styles
+   * const paraStyles = stylesManager.findStyles(s => s.getType() === 'paragraph');
+   *
+   * // Find styles with custom formatting
+   * const customStyles = stylesManager.findStyles(s => s.getProperties().customStyle);
+   *
+   * // Find styles with specific formatting
+   * const boldStyles = stylesManager.findStyles(s => s.getRunFormatting()?.bold);
+   * ```
+   */
+  findStyles(predicate: (style: Style) => boolean): Style[] {
+    return this.getAllStyles().filter(predicate);
+  }
+
+  /**
+   * Finds unused styles (not referenced by any paragraphs)
+   * @param paragraphs - All paragraphs in the document to check against
+   * @returns Array of unused style IDs
+   * @example
+   * ```typescript
+   * const doc = Document.create();
+   * const unused = stylesManager.findUnusedStyles(doc.getAllParagraphs());
+   * console.log(`Found ${unused.length} unused styles: ${unused.join(', ')}`);
+   * ```
+   */
+  findUnusedStyles(paragraphs: Paragraph[]): string[] {
+    const usedStyles = new Set<string>();
+
+    // Collect all style IDs used by paragraphs
+    for (const para of paragraphs) {
+      const styleId = para.getStyle();
+      if (styleId) {
+        usedStyles.add(styleId);
+      }
+    }
+
+    // Get all style IDs and filter out used ones
+    const allStyleIds = this.getAllStyles().map((style) => style.getStyleId());
+    return allStyleIds.filter((styleId) => !usedStyles.has(styleId));
+  }
+
+  /**
+   * Removes all unused styles from the document
+   * @param paragraphs - All paragraphs in the document to check against
+   * @returns Number of styles removed
+   * @example
+   * ```typescript
+   * const doc = Document.create();
+   * const removedCount = stylesManager.cleanupUnusedStyles(doc.getAllParagraphs());
+   * console.log(`Cleaned up ${removedCount} unused styles`);
+   * ```
+   */
+  cleanupUnusedStyles(paragraphs: Paragraph[]): number {
+    const unused = this.findUnusedStyles(paragraphs);
+    let count = 0;
+
+    for (const styleId of unused) {
+      // Don't remove built-in styles
+      if (!StylesManager.isBuiltInStyle(styleId)) {
+        if (this.removeStyle(styleId)) {
+          count++;
+        }
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Validates all style references for broken or circular dependencies
+   * @returns Validation result with broken references and circular dependencies
+   * @example
+   * ```typescript
+   * const validation = stylesManager.validateStyleReferences();
+   * if (!validation.valid) {
+   *   console.log('Broken references:', validation.brokenReferences);
+   *   console.log('Circular references:', validation.circularReferences);
+   * }
+   * ```
+   */
+  validateStyleReferences(): {
+    valid: boolean;
+    brokenReferences: { styleId: string; basedOn: string }[];
+    circularReferences: string[][];
+  } {
+    const broken: { styleId: string; basedOn: string }[] = [];
+    const circular: string[][] = [];
+    const checkedForCycles = new Set<string>();
+
+    for (const style of this.getAllStyles()) {
+      const props = style.getProperties();
+
+      // Check basedOn references exist
+      if (props.basedOn && !this.hasStyle(props.basedOn)) {
+        broken.push({ styleId: props.styleId, basedOn: props.basedOn });
+      }
+
+      // Check for circular references (only if not already checked as part of another cycle)
+      if (!checkedForCycles.has(props.styleId)) {
+        const result = this.hasCircularReference(props.styleId);
+        if (result.hasCircularRef && result.cyclePath) {
+          circular.push(result.cyclePath);
+          // Mark all styles in this cycle as checked
+          result.cyclePath.forEach((id) => checkedForCycles.add(id));
+        }
+      }
+    }
+
+    return {
+      valid: broken.length === 0 && circular.length === 0,
+      brokenReferences: broken,
+      circularReferences: circular,
+    };
+  }
+
+  /**
+   * Gets the complete inheritance chain for a style
+   * @param styleId - Style ID to analyze
+   * @returns Array of styles from base to derived (base style first)
+   * @throws Error if style doesn't exist or circular reference detected
+   * @example
+   * ```typescript
+   * const chain = stylesManager.getInheritanceChain('Heading1');
+   * console.log('Inheritance chain:', chain.map(s => s.getName()));
+   * // Output: ['Normal', 'Heading1'] (Normal is base, Heading1 inherits from it)
+   * ```
+   */
+  getInheritanceChain(styleId: string): Style[] {
+    const chain: Style[] = [];
+    const visited = new Set<string>(); // Track visited styles to detect cycles
+    let current = this.getStyle(styleId);
+
+    if (!current) {
+      throw new Error(`Style '${styleId}' not found`);
+    }
+
+    while (current) {
+      const currentId = current.getStyleId();
+
+      // Detect circular reference
+      if (visited.has(currentId)) {
+        const cycle = [...chain.map((s) => s.getStyleId()), currentId];
+        throw new Error(
+          `Circular style reference detected: ${cycle.join(' -> ')}. ` +
+            `Style '${currentId}' references itself through inheritance chain.`
+        );
+      }
+
+      visited.add(currentId);
+      chain.unshift(current); // Add to beginning to maintain base-to-derived order
+      const props = current.getProperties();
+      current = props.basedOn ? this.getStyle(props.basedOn) : undefined;
+    }
+
+    return chain;
+  }
+
+  /**
+   * Checks if a style has circular references in its inheritance chain
+   * @param styleId - Style ID to check
+   * @returns Object with hasCircularRef flag and the cycle path if found
+   * @example
+   * ```typescript
+   * const result = stylesManager.hasCircularReference('MyStyle');
+   * if (result.hasCircularRef) {
+   *   console.log('Circular reference found:', result.cyclePath?.join(' -> '));
+   * }
+   * ```
+   */
+  hasCircularReference(styleId: string): {
+    hasCircularRef: boolean;
+    cyclePath?: string[];
+  } {
+    const visited = new Set<string>();
+    const path: string[] = [];
+    let current = this.getStyle(styleId);
+
+    while (current) {
+      const currentId = current.getStyleId();
+
+      if (visited.has(currentId)) {
+        path.push(currentId);
+        return { hasCircularRef: true, cyclePath: path };
+      }
+
+      visited.add(currentId);
+      path.push(currentId);
+      const props = current.getProperties();
+      current = props.basedOn ? this.getStyle(props.basedOn) : undefined;
+    }
+
+    return { hasCircularRef: false };
+  }
+
+  /**
+   * Gets all styles that inherit from a base style
+   * @param baseStyleId - Base style ID to find children for
+   * @returns Array of styles that inherit from the base style
+   * @example
+   * ```typescript
+   * const children = stylesManager.getDerivedStyles('Normal');
+   * console.log(`Styles based on Normal: ${children.map(s => s.getName()).join(', ')}`);
+   * ```
+   */
+  getDerivedStyles(baseStyleId: string): Style[] {
+    return this.getAllStyles().filter((style) => style.getProperties().basedOn === baseStyleId);
+  }
+
+  /**
+   * Exports a single style as JSON string
+   * @param styleId - Style ID to export
+   * @returns JSON representation of the style
+   * @throws Error if style doesn't exist
+   * @example
+   * ```typescript
+   * const json = stylesManager.exportStyle('Heading1');
+   * console.log('Style JSON:', json);
+   *
+   * // Save to file
+   * await fs.writeFile('heading1-style.json', json);
+   * ```
+   */
+  exportStyle(styleId: string): string {
+    const style = this.getStyle(styleId);
+    if (!style) {
+      throw new Error(`Style '${styleId}' not found`);
+    }
+    return JSON.stringify(style.getProperties(), null, 2);
+  }
+
+  /**
+   * Imports a style from JSON string
+   * @param json - JSON string containing style properties
+   * @returns The imported style
+   * @throws Error if JSON is invalid or style creation fails
+   * @example
+   * ```typescript
+   * const json = await fs.readFile('custom-style.json', 'utf8');
+   * const style = stylesManager.importStyle(json);
+   * console.log(`Imported style: ${style.getName()}`);
+   * ```
+   */
+  importStyle(json: string): Style {
+    try {
+      const props = JSON.parse(json);
+      const style = Style.create(props);
+      this.addStyle(style);
+      return style;
+    } catch (error: unknown) {
+      throw new Error(
+        `Failed to import style: ${error instanceof Error ? error.message : 'Invalid JSON'}`
+      );
+    }
+  }
+
+  /**
+   * Exports all styles as JSON string
+   * @returns JSON array of all style properties
+   * @example
+   * ```typescript
+   * const allStylesJson = stylesManager.exportAllStyles();
+   * console.log('All styles exported');
+   *
+   * // Save to file
+   * await fs.writeFile('all-styles.json', allStylesJson);
+   * ```
+   */
+  exportAllStyles(): string {
+    const styles = this.getAllStyles().map((style) => style.getProperties());
+    return JSON.stringify(styles, null, 2);
+  }
+
+  /**
+   * Imports multiple styles from JSON array string
+   * @param json - JSON string containing array of style properties
+   * @returns Array of imported styles
+   * @throws Error if JSON is invalid or style creation fails
+   * @example
+   * ```typescript
+   * const json = await fs.readFile('styles-collection.json', 'utf8');
+   * const styles = stylesManager.importStyles(json);
+   * console.log(`Imported ${styles.length} styles`);
+   * ```
+   */
+  importStyles(json: string): Style[] {
+    try {
+      const propsArray = JSON.parse(json);
+      if (!Array.isArray(propsArray)) {
+        throw new Error('JSON must contain an array of style properties');
+      }
+
+      const styles: Style[] = [];
+      for (const props of propsArray) {
+        const style = Style.create(props);
+        this.addStyle(style);
+        styles.push(style);
+      }
+
+      return styles;
+    } catch (error: unknown) {
+      throw new Error(
+        `Failed to import styles: ${error instanceof Error ? error.message : 'Invalid JSON'}`
+      );
+    }
+  }
+}