/**
 * Formats raw HTML string with proper indentation and line breaks for better readability.
 *
 * This utility takes minified or unformatted HTML and returns a human-readable version with:
 * - Line breaks between tags
 * - Proper indentation (2 spaces per nesting level)
 * - Preserved text content and attributes
 * - Correct handling of HTML comments (<!-- -->)
 * - Correct handling of CDATA sections (<![CDATA[...]]>)
 * - Correct handling of DOCTYPE declarations (<!DOCTYPE ...>)
 * - Safe handling of comparison operators (e.g., "5 < 10") in text content
 *
 * The formatter uses improved regex patterns that only match actual HTML tags
 * (starting with < followed by a letter or /), preventing false matches on
 * text content containing < characters. Special HTML constructs (comments,
 * CDATA, DOCTYPE) are temporarily replaced with placeholders during formatting
 * and restored afterward to preserve their exact content.
 *
 * @param html - Raw HTML string to format (can be minified or already formatted)
 * @returns Formatted HTML string with proper indentation and line breaks
 *
 * @example
 * ```typescript
 * const raw = '<div><p>Hello</p><p>World</p></div>';
 * const formatted = formatHtml(raw);
 * // Returns:
 * // <div>
 * //   <p>Hello</p>
 * //   <p>World</p>
 * // </div>
 *
 * // Handles text with < characters correctly
 * const withComparison = '<div>5 < 10 is true</div>';
 * const formatted2 = formatHtml(withComparison);
 * // Returns:
 * // <div>
 * //   5 < 10 is true
 * // </div>
 *
 * // Preserves HTML comments
 * const withComment = '<div><!-- Comment --><p>Text</p></div>';
 * const formatted3 = formatHtml(withComment);
 * // Returns:
 * // <div>
 * //   <!-- Comment -->
 * //   <p>Text</p>
 * // </div>
 * ```
 */
export default function formatHtml(html: string): string;