docxmlater 10.0.1 → 10.0.3

package/src/xml/XMLParser.ts

@@ -0,0 +1,919 @@
+/**
+ * XMLParser - Simple position-based XML parser
+ * Avoids regex backtracking issues that can cause ReDoS attacks
+ * Completes the DocXML framework (XMLBuilder + XMLParser)
+ */
+
+import { getGlobalLogger, createScopedLogger, ILogger } from "../utils/logger";
+import { XMLBuilder } from "./XMLBuilder";
+
+// Create scoped logger for XMLParser operations
+function getLogger(): ILogger {
+  return createScopedLogger(getGlobalLogger(), 'XMLParser');
+}
+
+/**
+ * Default maximum nesting depth for XML parsing.
+ * Prevents stack overflow on deeply nested documents.
+ */
+export const DEFAULT_MAX_NESTING_DEPTH = 256;
+
+/**
+ * Options for XML-to-object parsing
+ */
+export interface ParseToObjectOptions {
+  /** Ignore attributes (default: false) */
+  ignoreAttributes?: boolean;
+
+  /** Attribute name prefix (default: '@_') */
+  attributeNamePrefix?: string;
+
+  /** Text node property name (default: '#text') */
+  textNodeName?: string;
+
+  /** Remove namespace prefixes from element names (default: false) */
+  ignoreNamespace?: boolean;
+
+  /** Parse numeric attribute values (default: true) */
+  parseAttributeValue?: boolean;
+
+  /** Trim whitespace from text values (default: true) */
+  trimValues?: boolean;
+
+  /** Always return arrays for elements (default: false) */
+  alwaysArray?: boolean;
+
+  /** Maximum nesting depth (default: 256). Prevents stack overflow on deeply nested documents. */
+  maxNestingDepth?: number;
+}
+
+/**
+ * Parsed XML object structure
+ * Can be a string, object, array, or nested structure
+ */
+export type ParsedXMLValue =
+  | string
+  | number
+  | boolean
+  | ParsedXMLObject
+  | ParsedXMLObject[]
+  | null
+  | undefined;
+
+/**
+ * Parsed XML object with dynamic keys
+ */
+export interface ParsedXMLObject {
+  [key: string]: ParsedXMLValue;
+}
+
+/**
+ * Internal structure for tracking parsed elements during parsing
+ */
+interface ParsedElement {
+  name: string;
+  value: ParsedXMLValue;
+}
+
+/**
+ * Simple XML parser using position-based parsing instead of regex
+ * Prevents catastrophic backtracking (ReDoS attacks) by avoiding nested regex patterns
+ */
+export class XMLParser {
+  /**
+   * Extracts the body content from a Word document XML
+   * @param docXml - The complete document.xml content
+   * @returns The body content, or empty string if not found
+   */
+  static extractBody(docXml: string): string {
+    const startTag = "<w:body";
+    const endTag = "</w:body>";
+
+    const startIdx = docXml.indexOf(startTag);
+    if (startIdx === -1) return "";
+
+    // Find the closing > of opening tag
+    const openEnd = docXml.indexOf(">", startIdx);
+    if (openEnd === -1) return "";
+
+    // Find matching closing tag
+    const endIdx = docXml.indexOf(endTag, openEnd);
+    if (endIdx === -1) return "";
+
+    return docXml.substring(openEnd + 1, endIdx);
+  }
+
+  /**
+   * Extracts all elements of a given type using position-based parsing
+   * Handles nested tags correctly by tracking depth
+   * @param xml - XML content to parse
+   * @param tagName - Tag name to extract (e.g., 'w:p', 'w:r')
+   * @returns Array of XML strings for each element
+   */
+  static extractElements(xml: string, tagName: string): string[] {
+    const elements: string[] = [];
+    const openTag = `<${tagName}`;
+    const closeTag = `</${tagName}>`;
+    const selfClosingEnd = "/>";
+
+    let pos = 0;
+    while (pos < xml.length) {
+      const startIdx = xml.indexOf(openTag, pos);
+      if (startIdx === -1) break;
+
+      // Verify this is the exact tag (not a prefix match like <w:p matching <w:pPr>)
+      // The character after the tag name must be either '>', '/', whitespace, or '=' (for attributes)
+      const charAfterTag = xml[startIdx + openTag.length];
+      if (
+        charAfterTag &&
+        charAfterTag !== ">" &&
+        charAfterTag !== "/" &&
+        charAfterTag !== " " &&
+        charAfterTag !== "\t" &&
+        charAfterTag !== "\n" &&
+        charAfterTag !== "\r" &&
+        charAfterTag !== "="
+      ) {
+        // This is a prefix match (e.g., <w:pPr> when looking for <w:p>), skip it (Issue #5)
+        pos = startIdx + openTag.length;
+        continue;
+      }
+
+      // Find the end of opening tag
+      const openEnd = xml.indexOf(">", startIdx);
+      if (openEnd === -1) break;
+
+      // Check if self-closing
+      if (xml.substring(openEnd - 1, openEnd + 1) === selfClosingEnd) {
+        elements.push(xml.substring(startIdx, openEnd + 1));
+        pos = openEnd + 1;
+        continue;
+      }
+
+      // Find matching closing tag (handle nesting)
+      let depth = 1;
+      let searchPos = openEnd + 1;
+
+      while (depth > 0 && searchPos < xml.length) {
+        // Find next potential opening tag
+        let nextOpen = -1;
+        let openSearchPos = searchPos;
+        while (true) {
+          const candidateOpen = xml.indexOf(openTag, openSearchPos);
+          if (candidateOpen === -1) {
+            break;
+          }
+          // Verify it's an exact match (not a prefix)
+          const charAfter = xml[candidateOpen + openTag.length];
+          if (
+            charAfter &&
+            charAfter !== ">" &&
+            charAfter !== "/" &&
+            charAfter !== " " &&
+            charAfter !== "\t" &&
+            charAfter !== "\n" &&
+            charAfter !== "\r"
+          ) {
+            // Prefix match, keep searching
+            openSearchPos = candidateOpen + openTag.length;
+            continue;
+          }
+          nextOpen = candidateOpen;
+          break;
+        }
+
+        const nextClose = xml.indexOf(closeTag, searchPos);
+
+        if (nextClose === -1) break;
+
+        if (nextOpen !== -1 && nextOpen < nextClose) {
+          depth++;
+          searchPos = nextOpen + openTag.length;
+        } else {
+          depth--;
+          if (depth === 0) {
+            elements.push(xml.substring(startIdx, nextClose + closeTag.length));
+            pos = nextClose + closeTag.length;
+          } else {
+            searchPos = nextClose + closeTag.length;
+          }
+        }
+      }
+
+      if (depth > 0) {
+        // Unclosed tag - skip it
+        pos = startIdx + openTag.length;
+      }
+    }
+
+    return elements;
+  }
+
+  /**
+   * Extracts attribute value from an XML string
+   * @param xml - XML content
+   * @param attributeName - Attribute name (e.g., 'w:val')
+   * @returns Attribute value or undefined
+   */
+  static extractAttribute(
+    xml: string,
+    attributeName: string
+  ): string | undefined {
+    // Use simple indexOf for bounded string search (safe)
+    const attrPattern = `${attributeName}="`;
+    const startIdx = xml.indexOf(attrPattern);
+    if (startIdx === -1) return undefined;
+
+    const valueStart = startIdx + attrPattern.length;
+    const valueEnd = xml.indexOf('"', valueStart);
+    if (valueEnd === -1) return undefined;
+
+    const rawValue = xml.substring(valueStart, valueEnd);
+    // Unescape XML entities to get the actual value
+    // This prevents double-escaping when the value is later re-serialized
+    return XMLBuilder.unescapeXml(rawValue);
+  }
+
+  /**
+   * Checks if an XML string contains a self-closing tag
+   * @param xml - XML content
+   * @param tagName - Tag name to check
+   * @returns True if the tag exists as self-closing
+   */
+  static hasSelfClosingTag(xml: string, tagName: string): boolean {
+    return xml.includes(`<${tagName}/>`) || xml.includes(`<${tagName} `);
+  }
+
+  /**
+   * Checks if a boolean property tag is enabled (w:val="1" or w:val="true")
+   * Per ECMA-376, boolean properties can be:
+   * - Present with w:val="1" or w:val="true" (enabled)
+   * - Present with w:val="0" or w:val="false" (explicitly disabled)
+   * - Absent (disabled by default)
+   *
+   * @param xml - XML content to search
+   * @param tagName - Tag name (e.g., 'w:keepNext')
+   * @returns True if tag exists with w:val="1" or w:val="true", false otherwise
+   *
+   * @example
+   * hasBooleanProperty('<w:pPr><w:keepNext w:val="1"/></w:pPr>', 'w:keepNext'); // true
+   * hasBooleanProperty('<w:pPr><w:keepNext w:val="0"/></w:pPr>', 'w:keepNext'); // false
+   * hasBooleanProperty('<w:pPr><w:spacing/></w:pPr>', 'w:keepNext'); // false
+   */
+  static hasBooleanProperty(xml: string, tagName: string): boolean {
+    // Check for tag with w:val="1" or w:val="true"
+    if (
+      xml.includes(`<${tagName} w:val="1"`) ||
+      xml.includes(`<${tagName} w:val="true"`)
+    ) {
+      return true;
+    }
+
+    // Check for self-closing tag without w:val attribute (means true per ECMA-376)
+    // Example: <w:b/> means bold=true
+    if (xml.includes(`<${tagName}/>`)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Extracts text content from within tags
+   * Finds all <w:t>...</w:t> tags and extracts their text
+   * @param xml - XML content
+   * @returns Combined text content
+   */
+  static extractText(xml: string): string {
+    const texts: string[] = [];
+    const openTag = "<w:t";
+    const closeTag = "</w:t>";
+
+    let pos = 0;
+    while (pos < xml.length) {
+      const startIdx = xml.indexOf(openTag, pos);
+      if (startIdx === -1) break;
+
+      // Find the end of opening tag
+      const openEnd = xml.indexOf(">", startIdx);
+      if (openEnd === -1) break;
+
+      // Find closing tag
+      const closeIdx = xml.indexOf(closeTag, openEnd);
+      if (closeIdx === -1) break;
+
+      // Extract text between tags
+      const text = xml.substring(openEnd + 1, closeIdx);
+      texts.push(text);
+
+      pos = closeIdx + closeTag.length;
+    }
+
+    return texts.join("");
+  }
+
+  /**
+   * Validates input size to prevent excessive memory usage
+   * @param xml - XML content
+   * @param maxSize - Maximum size in bytes (default: 10MB)
+   * @throws Error if XML exceeds max size
+   */
+  static validateSize(xml: string, maxSize: number = 10 * 1024 * 1024): void {
+    if (xml.length > maxSize) {
+      throw new Error(
+        `XML content too large for parsing (${(
+          xml.length /
+          1024 /
+          1024
+        ).toFixed(1)}MB). ` +
+          `Maximum allowed: ${(maxSize / 1024 / 1024).toFixed(0)}MB`
+      );
+    }
+  }
+
+  /**
+   * Extracts content between two specific tags
+   * More efficient than regex for large documents
+   * @param xml - XML content
+   * @param startTag - Opening tag (e.g., '<w:pPr')
+   * @param endTag - Closing tag (e.g., '</w:pPr>')
+   * @returns Content between tags, or undefined if not found
+   */
+  static extractBetweenTags(
+    xml: string,
+    startTag: string,
+    endTag: string
+  ): string | undefined {
+    const startIdx = xml.indexOf(startTag);
+    if (startIdx === -1) return undefined;
+
+    // Find the end of the opening tag
+    const openEnd = xml.indexOf(">", startIdx);
+    if (openEnd === -1) return undefined;
+
+    // Find the closing tag
+    const endIdx = xml.indexOf(endTag, openEnd);
+    if (endIdx === -1) return undefined;
+
+    return xml.substring(openEnd + 1, endIdx);
+  }
+
+  /**
+   * Extracts a complete self-closing tag with its attributes
+   * Handles cases where multiple similar tags exist (e.g., <w:sz.../> and <w:szCs.../>)
+   *
+   * @param xml - XML string to search
+   * @param tagName - Tag name to find (e.g., "w:color", "w:sz")
+   * @returns The complete tag content (attributes portion) or undefined if not found
+   *
+   * @example
+   * const xml = '<w:sz w:val="36"/><w:color w:val="FF0000"/>';
+   * const colorTag = XMLParser.extractSelfClosingTag(xml, 'w:color');
+   * // Returns: ' w:val="FF0000"'
+   */
+  static extractSelfClosingTag(
+    xml: string,
+    tagName: string
+  ): string | undefined {
+    const startPattern = `<${tagName}`;
+    let searchPos = 0;
+
+    // Search for the exact tag (not tags that start with this pattern)
+    while (true) {
+      const startIdx = xml.indexOf(startPattern, searchPos);
+      if (startIdx === -1) return undefined;
+
+      // Check what character follows the tag name
+      const charAfterTag = xml[startIdx + startPattern.length];
+
+      // Valid separators after tag name: space, '/', or '>'
+      if (charAfterTag === ' ' || charAfterTag === '/' || charAfterTag === '>') {
+        // Found the exact tag, now find its end
+        const endIdx = xml.indexOf('/>', startIdx);
+        if (endIdx === -1) {
+          // Try finding a closing tag instead (non-self-closing)
+          const closeTagStart = xml.indexOf('>', startIdx);
+          if (closeTagStart === -1) return undefined;
+
+          // Return attributes portion
+          return xml.substring(startIdx + startPattern.length, closeTagStart);
+        }
+
+        // Return attributes portion (between tag name and />)
+        return xml.substring(startIdx + startPattern.length, endIdx);
+      }
+
+      // Not the exact tag (e.g., found "w:sz" when looking for "w:s")
+      // Continue searching
+      searchPos = startIdx + 1;
+    }
+  }
+
+  /**
+   * Parse XML string to JavaScript object
+   * Compatible with fast-xml-parser output format
+   *
+   * @param xml - XML string to parse
+   * @param options - Parsing options
+   * @returns Parsed JavaScript object
+   *
+   * @example
+   * const xml = '<Relationships><Relationship Id="rId1" Target="https://example.com"/></Relationships>';
+   * const obj = XMLParser.parseToObject(xml);
+   * // Returns: { Relationships: { Relationship: { '@_Id': 'rId1', '@_Target': 'https://example.com' } } }
+   *
+   * @example
+   * // Multiple elements become arrays
+   * const xml = '<Items><Item id="1"/><Item id="2"/></Items>';
+   * const obj = XMLParser.parseToObject(xml);
+   * // Returns: { Items: { Item: [{ '@_id': '1' }, { '@_id': '2' }] } }
+   */
+  static parseToObject(
+    xml: string,
+    options?: ParseToObjectOptions
+  ): ParsedXMLObject {
+    const logger = getLogger();
+    logger.debug('Parsing XML to object', { xmlSize: xml.length });
+
+    // Default options
+    const opts: Required<ParseToObjectOptions> = {
+      ignoreAttributes: options?.ignoreAttributes ?? false,
+      attributeNamePrefix: options?.attributeNamePrefix ?? "@_",
+      textNodeName: options?.textNodeName ?? "#text",
+      ignoreNamespace: options?.ignoreNamespace ?? false,
+      parseAttributeValue: options?.parseAttributeValue ?? true,
+      trimValues: options?.trimValues ?? true,
+      alwaysArray: options?.alwaysArray ?? false,
+      maxNestingDepth: options?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH,
+    };
+
+    // Validate input size
+    XMLParser.validateSize(xml);
+
+    // Remove XML declaration and trim
+    xml = xml.replace(/<\?xml[^>]*\?>\s*/g, "").trim();
+
+    if (!xml) {
+      return {};
+    }
+
+    // Parse root element (start at depth 0)
+    const result = XMLParser.parseElementToObject(xml, 0, opts, 0);
+    logger.debug('XML parsed to object');
+    return result.value as ParsedXMLObject;
+  }
+
+  /**
+   * Parses a single XML element into an object
+   * @private
+   */
+  private static parseElementToObject(
+    xml: string,
+    startPos: number,
+    options: Required<ParseToObjectOptions>,
+    depth: number
+  ): { value: ParsedXMLValue; endPos: number } {
+    // Check nesting depth to prevent stack overflow
+    if (depth > options.maxNestingDepth) {
+      throw new Error(
+        `XML nesting depth exceeds maximum of ${options.maxNestingDepth}. ` +
+        `This may indicate malformed XML or an attack attempt. ` +
+        `Use the maxNestingDepth option to increase the limit if needed.`
+      );
+    }
+
+    // Find opening tag
+    const openTagStart = xml.indexOf("<", startPos);
+    if (openTagStart === -1) {
+      return { value: {}, endPos: xml.length };
+    }
+
+    // Skip comments
+    if (xml.substring(openTagStart, openTagStart + 4) === "<!--") {
+      const commentEnd = xml.indexOf("-->", openTagStart + 4);
+      if (commentEnd !== -1) {
+        return XMLParser.parseElementToObject(xml, commentEnd + 3, options, depth);
+      }
+      return { value: {}, endPos: xml.length };
+    }
+
+    // Extract element name
+    const nameMatch = /^([a-zA-Z0-9:_-]+)/.exec(xml
+      .substring(openTagStart + 1));
+    if (!nameMatch) {
+      return { value: {}, endPos: openTagStart + 1 };
+    }
+
+    const originalElementName: string = nameMatch[1] || "";
+    let elementName: string = originalElementName;
+    const tagHeaderEnd = xml.indexOf(">", openTagStart);
+    if (tagHeaderEnd === -1) {
+      return { value: {}, endPos: xml.length };
+    }
+
+    // Remove namespace if requested (but keep original for offset calculations)
+    if (options.ignoreNamespace && elementName.includes(":")) {
+      elementName = elementName.split(":")[1] || elementName;
+    }
+
+    // Extract attributes using ORIGINAL element name length for correct offset
+    const tagHeader = xml.substring(
+      openTagStart + 1 + originalElementName.length,
+      tagHeaderEnd
+    );
+    const attributes = XMLParser.extractAttributesFromTag(tagHeader, options);
+
+    // Check if self-closing
+    const isSelfClosing =
+      tagHeader.trim().endsWith("/") || xml[tagHeaderEnd - 1] === "/";
+
+    if (isSelfClosing) {
+      // Self-closing tag - return object with attributes only
+      const elementValue: ParsedXMLObject = { ...attributes };
+      return {
+        value: { [elementName]: elementValue },
+        endPos: tagHeaderEnd + 1,
+      };
+    }
+
+    // Find closing tag (use original name with namespace for correct matching)
+    const closingTag = `</${originalElementName}>`;
+    const contentStart = tagHeaderEnd + 1;
+    const closingTagPos = XMLParser.findClosingTag(
+      xml,
+      originalElementName,
+      contentStart
+    );
+
+    if (closingTagPos === -1) {
+      // No closing tag found - treat as self-closing
+      return {
+        value: { [elementName]: { ...attributes } },
+        endPos: tagHeaderEnd + 1,
+      };
+    }
+
+    // Extract content between tags
+    const content = xml.substring(contentStart, closingTagPos);
+
+    // Parse content (children or text)
+    const children: ParsedElement[] = [];
+    let textContent = "";
+    let pos = 0;
+
+    while (pos < content.length) {
+      const nextTag = content.indexOf("<", pos);
+
+      if (nextTag === -1) {
+        // No more tags - rest is text
+        const text = content.substring(pos);
+        // When trimValues is false, preserve whitespace-only text
+        // When trimValues is true, only include text that has non-whitespace content
+        if (text.length > 0 && (!options.trimValues || text.trim())) {
+          // Unescape XML entities in text content (e.g., &lt; -> <)
+          textContent += XMLBuilder.unescapeXml(text);
+        }
+        break;
+      }
+
+      // Collect text before next tag
+      if (nextTag > pos) {
+        const text = content.substring(pos, nextTag);
+        // When trimValues is false, preserve whitespace-only text
+        // When trimValues is true, only include text that has non-whitespace content
+        if (text.length > 0 && (!options.trimValues || text.trim())) {
+          // Unescape XML entities in text content (e.g., &lt; -> <)
+          textContent += XMLBuilder.unescapeXml(text);
+        }
+      }
+
+      // Parse child element (increment depth for children)
+      const childResult = XMLParser.parseElementToObject(
+        content,
+        nextTag,
+        options,
+        depth + 1
+      );
+      const childObj = childResult.value as ParsedXMLObject;
+
+      // Extract child name and value
+      const childKeys = Object.keys(childObj);
+      if (childKeys.length > 0) {
+        const childName = childKeys[0];
+        if (childName) {
+          const childValue = childObj[childName];
+          children.push({ name: childName, value: childValue });
+        }
+      }
+
+      pos = childResult.endPos;
+    }
+
+    // Build element value
+    let elementValue: ParsedXMLValue = {};
+
+    // Add attributes
+    if (!options.ignoreAttributes && Object.keys(attributes).length > 0) {
+      elementValue = { ...attributes };
+    }
+
+    // Add text content
+    // When trimValues is false, include whitespace-only text
+    // When trimValues is true, only include text with non-whitespace content
+    if (textContent.length > 0 && (!options.trimValues || textContent.trim())) {
+      const text = options.trimValues ? textContent.trim() : textContent;
+      if (typeof elementValue === "object" && !Array.isArray(elementValue)) {
+        if (Object.keys(elementValue).length === 0) {
+          // Only text, no attributes - return as direct value if simple
+          elementValue = text;
+        } else {
+          // Text with attributes
+          (elementValue)[options.textNodeName] = text;
+        }
+      }
+    }
+
+    // Add children
+    if (children.length > 0) {
+      const coalescedChildren = XMLParser.coalesceChildren(children, options);
+      if (typeof elementValue === "object" && !Array.isArray(elementValue)) {
+        elementValue = { ...elementValue, ...coalescedChildren };
+      } else {
+        elementValue = coalescedChildren;
+      }
+    }
+
+    // If element has no content, attributes, or children - return empty object
+    if (
+      typeof elementValue === "object" &&
+      !Array.isArray(elementValue) &&
+      Object.keys(elementValue).length === 0
+    ) {
+      elementValue = {};
+    }
+
+    return {
+      value: { [elementName]: elementValue },
+      endPos: closingTagPos + closingTag.length,
+    };
+  }
+
+  /**
+   * Extracts attributes from a tag header
+   * @private
+   */
+  private static extractAttributesFromTag(
+    tagHeader: string,
+    options: Required<ParseToObjectOptions>
+  ): Record<string, string | number | boolean> {
+    const attributes: Record<string, string | number | boolean> = {};
+
+    if (options.ignoreAttributes) {
+      return attributes;
+    }
+
+    // Simple attribute extraction using position-based parsing
+    let pos = 0;
+    while (pos < tagHeader.length) {
+      // Skip whitespace
+      while (pos < tagHeader.length) {
+        const char = tagHeader[pos];
+        if (char && /\s/.test(char)) {
+          pos++;
+        } else {
+          break;
+        }
+      }
+
+      if (pos >= tagHeader.length || tagHeader[pos] === "/") {
+        break;
+      }
+
+      // Extract attribute name
+      const nameStart = pos;
+      while (pos < tagHeader.length) {
+        const char = tagHeader[pos];
+        if (char && /[a-zA-Z0-9:_-]/.test(char)) {
+          pos++;
+        } else {
+          break;
+        }
+      }
+
+      if (pos === nameStart) {
+        break;
+      }
+
+      let attrName = tagHeader.substring(nameStart, pos);
+
+      // Skip whitespace and '='
+      while (pos < tagHeader.length) {
+        const char = tagHeader[pos];
+        if (char && /[\s=]/.test(char)) {
+          pos++;
+        } else {
+          break;
+        }
+      }
+
+      // Extract attribute value
+      let attrValue = "";
+      if (
+        pos < tagHeader.length &&
+        (tagHeader[pos] === '"' || tagHeader[pos] === "'")
+      ) {
+        const quote = tagHeader[pos];
+        pos++; // Skip opening quote
+        const valueStart = pos;
+
+        while (pos < tagHeader.length && tagHeader[pos] !== quote) {
+          pos++;
+        }
+
+        attrValue = tagHeader.substring(valueStart, pos);
+        pos++; // Skip closing quote
+      }
+
+      // Remove namespace from attribute name if requested
+      if (options.ignoreNamespace && attrName.includes(":")) {
+        attrName = attrName.split(":")[1] || attrName;
+      }
+
+      // Add prefix to attribute name
+      const prefixedName = options.attributeNamePrefix + attrName;
+
+      // Parse attribute value
+      attributes[prefixedName] = options.parseAttributeValue
+        ? XMLParser.parseValue(attrValue)
+        : attrValue;
+    }
+
+    return attributes;
+  }
+
+  /**
+   * Finds the closing tag for an element, handling nesting
+   * @private
+   */
+  private static findClosingTag(
+    xml: string,
+    elementName: string,
+    startPos: number
+  ): number {
+    const openTag = `<${elementName}`;
+    const closeTag = `</${elementName}>`;
+    let depth = 1;
+    let pos = startPos;
+
+    while (depth > 0 && pos < xml.length) {
+      const nextClose = xml.indexOf(closeTag, pos);
+
+      if (nextClose === -1) {
+        return -1; // No closing tag found
+      }
+
+      // Find the next REAL opening tag (not a prefix match like <w:pPrChange for <w:pPr)
+      // Must search for all potential matches and verify each one
+      let realOpenPos = -1;
+      let searchPos = pos;
+      while (searchPos < nextClose) {
+        const candidateOpen = xml.indexOf(openTag, searchPos);
+        if (candidateOpen === -1 || candidateOpen >= nextClose) {
+          break; // No more candidates before the closing tag
+        }
+
+        const charAfter = xml[candidateOpen + openTag.length];
+        if (
+          charAfter === ">" ||
+          charAfter === " " ||
+          charAfter === "/" ||
+          charAfter === "\t" ||
+          charAfter === "\n" ||
+          charAfter === "\r"
+        ) {
+          // This looks like a real opening tag - but check if it's self-closing
+          // Self-closing tags like <w:rPr/> should NOT increase depth
+          const tagEnd = xml.indexOf(">", candidateOpen);
+          if (tagEnd !== -1 && xml[tagEnd - 1] === "/") {
+            // Self-closing tag - skip it (don't affect depth)
+            searchPos = tagEnd + 1;
+            continue;
+          }
+          // This is a real opening tag (not self-closing)
+          realOpenPos = candidateOpen;
+          break;
+        }
+
+        // False positive (e.g., <w:pPrChange when looking for <w:pPr)
+        // Keep searching from after this position
+        searchPos = candidateOpen + openTag.length;
+      }
+
+      if (realOpenPos !== -1) {
+        // Found a real opening tag before the closing tag - increase depth
+        depth++;
+        pos = realOpenPos + openTag.length;
+      } else {
+        // No real opening tag before this closing tag - decrease depth
+        depth--;
+        if (depth === 0) {
+          return nextClose;
+        }
+        pos = nextClose + closeTag.length;
+      }
+    }
+
+    return -1;
+  }
+
+  /**
+   * Coalesces children with duplicate names into arrays
+   * @private
+   */
+  private static coalesceChildren(
+    children: ParsedElement[],
+    options: Required<ParseToObjectOptions>
+  ): ParsedXMLObject {
+    const result: ParsedXMLObject = {};
+    const nameCounts: Record<string, number> = {};
+    const nameIndices: Record<string, number> = {};
+
+    // Track element order for correct run content parsing (tabs, breaks, text)
+    // This is critical for preserving the order of mixed content like: text -> tab -> text
+    const orderedChildren: { type: string; index: number }[] = [];
+
+    // Count occurrences of each child name
+    for (const child of children) {
+      nameCounts[child.name] = (nameCounts[child.name] || 0) + 1;
+    }
+
+    // Build result object while tracking order
+    for (const child of children) {
+      const shouldBeArray =
+        options.alwaysArray || (nameCounts[child.name] || 0) > 1;
+
+      // Track element order with its index in the array
+      const currentIndex = nameIndices[child.name] || 0;
+      orderedChildren.push({ type: child.name, index: currentIndex });
+      nameIndices[child.name] = currentIndex + 1;
+
+      if (shouldBeArray) {
+        if (!result[child.name]) {
+          result[child.name] = [];
+        }
+        (result[child.name] as ParsedXMLValue[]).push(child.value);
+      } else {
+        result[child.name] = child.value;
+      }
+    }
+
+    // Add _orderedChildren to track element order (used by DocumentParser for runs)
+    if (orderedChildren.length > 0) {
+      result._orderedChildren = orderedChildren;
+    }
+
+    return result;
+  }
+
+  /**
+   * Parses a string value to number or boolean if applicable
+   * @private
+   */
+  private static parseValue(value: string): string | number | boolean {
+    if (value === "true") return true;
+    if (value === "false") return false;
+
+    // Preserve 6-character hex color codes (OpenXML standard for colors)
+    // This includes "000000" (black) which should stay as a string
+    if (/^[0-9A-Fa-f]{6}$/.test(value)) {
+      return value.toUpperCase(); // Normalize to uppercase per Microsoft convention
+    }
+
+    // Preserve long digit-only strings (e.g., cnfStyle binary strings like "100000000000")
+    // These should not be converted to numbers to avoid losing leading zeros
+    if (/^\d{7,}$/.test(value)) {
+      return value; // Keep as string for values with 7+ digits
+    }
+
+    // Try parsing as number
+    // 3-character values like "240" will be parsed as numbers
+    // 6-character hex values are already handled above
+    if (/^-?\d+$/.test(value)) {
+      const num = parseInt(value, 10);
+      if (!isNaN(num)) return num;
+    }
+
+    if (/^-?\d+\.\d+$/.test(value)) {
+      const num = parseFloat(value);
+      if (!isNaN(num)) return num;
+    }
+
+    // Preserve 3-character hex codes (like "F0A") that have letters
+    // Pure numeric 3-char values (like "240") are already parsed as numbers above
+    if (/^[0-9A-Fa-f]{3}$/.test(value) && /[A-Fa-f]/.test(value)) {
+      return value.toUpperCase();
+    }
+
+    return value;
+  }
+}