html-minifier-next 6.2.8 → 6.2.9

package/dist/htmlminifier.cjs

@@ -4,14 +4,18 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 // Stringify for options signatures (sorted keys, shallow, nested objects)
 
+/**
+ * @param {unknown} obj
+ * @returns {string}
+ */
 function stableStringify(obj) {
   if (obj == null || typeof obj !== 'object') return JSON.stringify(obj);
   if (Array.isArray(obj)) return '[' + obj.map(stableStringify).join(',') + ']';
   const keys = Object.keys(obj).sort();
   let out = '{';
   for (let i = 0; i < keys.length; i++) {
-    const k = keys[i];
-    out += JSON.stringify(k) + ':' + stableStringify(obj[k]) + (i < keys.length - 1 ? ',' : '');
+    const k = keys[i] ?? '';
+    out += JSON.stringify(k) + ':' + stableStringify(/** @type {Record<string, unknown>} */ (obj)[k]) + (i < keys.length - 1 ? ',' : '');
   }
   return out + '}';
 }
@@ -21,8 +25,10 @@ function stableStringify(obj) {
 class LRU {
   constructor(limit = 200) {
     this.limit = limit;
+    /** @type {Map<string, unknown>} */
     this.map = new Map();
   }
+  /** @param {string} key */
   get(key) {
     if (this.map.has(key)) {
       const v = this.map.get(key);
@@ -32,19 +38,25 @@ class LRU {
     }
     return undefined;
   }
+  /**
+   * @param {string} key
+   * @param {unknown} value
+   */
   set(key, value) {
     if (this.map.has(key)) this.map.delete(key);
     this.map.set(key, value);
     if (this.map.size > this.limit) {
       const first = this.map.keys().next().value;
-      this.map.delete(first);
+      if (first !== undefined) this.map.delete(first);
     }
   }
+  /** @param {string} key */
   delete(key) { this.map.delete(key); }
 }
 
 // FNV-1a 32-bit hash for large-input cache keys
 
+/** @param {string} str */
 function hashContent(str) {
   let hash = 2166136261;
   for (let i = 0; i < str.length; i++) {
@@ -56,6 +68,7 @@ function hashContent(str) {
 
 // Unique ID generator
 
+/** @param {string} value */
 function uniqueId(value) {
   let id;
   do {
@@ -66,14 +79,17 @@ function uniqueId(value) {
 
 // Identity and transform functions
 
+/** @param {string} value */
 function identity(value) {
   return value;
 }
 
+/** @param {unknown} value */
 function isThenable(value) {
-  return value != null && typeof value === 'object' && typeof value.then === 'function';
+  return value != null && typeof value === 'object' && typeof /** @type {any} */ (value).then === 'function';
 }
 
+/** @param {string} value */
 function lowercase(value) {
   return value.toLowerCase();
 }
@@ -88,25 +104,28 @@ function lowercase(value) {
  * @returns {Promise<string>} Processed string
  */
 async function replaceAsync(str, regex, asyncFn) {
+  /** @type {Promise<string>[]} */
   const promises = [];
 
-  str.replace(regex, (match, ...args) => {
+  str.replace(regex, /** @returns {string} */ (match, ...args) => {
     const promise = asyncFn(match, ...args);
     promises.push(promise);
+    return match;
   });
 
   const data = await Promise.all(promises);
-  return str.replace(regex, () => data.shift());
+  return str.replace(regex, () => data.shift() ?? '');
 }
 
 // String patterns to RegExp conversion (for JSON config support)
 
+/** @param {string | RegExp} value */
 function parseRegExp(value) {
   if (typeof value === 'string') {
     if (!value) return undefined; // Empty string = not configured
     const match = value.match(/^\/(.+)\/([dgimsuvy]*)$/);
     if (match) {
-      return new RegExp(match[1], match[2]);
+      return new RegExp(match[1] ?? '', match[2] ?? '');
     }
     return new RegExp(value);
   }
@@ -121,6 +140,25 @@ function parseRegExp(value) {
  */
 
 
+/** @import { HTMLAttribute } from './lib/attributes.js' */
+
+// Type definitions
+
+/**
+ * @typedef {{
+ *   start?: Function,
+ *   end?: Function,
+ *   chars?: Function,
+ *   comment?: Function,
+ *   doctype?: Function,
+ *   continueOnParseError?: boolean | undefined,
+ *   partialMarkup?: boolean | undefined,
+ *   wantsNextTag?: boolean | undefined,
+ *   customAttrSurround?: RegExp[][] | undefined,
+ *   customAttrAssign?: RegExp[] | undefined
+ * }} HTMLParserHandler
+ */
+
 /*
  * Use like so:
  *
@@ -133,7 +171,8 @@ function parseRegExp(value) {
  */
 
 class CaseInsensitiveSet extends Set {
-  has(str) {
+  /** @override */
+  has(/** @type {string} */ str) {
     return super.has(str.toLowerCase());
   }
 }
@@ -168,8 +207,9 @@ const startTagOpen = new RegExp('^<' + qnameCapture);
 const endTag = new RegExp('^</' + qnameCapture + '[^>]*>');
 
 let IS_REGEX_CAPTURING_BROKEN = false;
-'x'.replace(/x(.)?/g, function (m, g) {
+'x'.replace(/x(.)?/g, function (/** @type {string} */ m, /** @type {string | undefined} */ g) {
   IS_REGEX_CAPTURING_BROKEN = g === '';
+  return m;
 });
 
 // Empty elements
@@ -203,6 +243,11 @@ const attrRegexCache = new WeakMap();
 
 // O(n) helper: Strip all occurrences of `open…close` delimiters, keeping inner content
 // Used instead of a regex replace to avoid O(n²) behavior on adversarial inputs
+/**
+ * @param {string} str
+ * @param {string} open
+ * @param {string} close
+ */
 function stripDelimited(str, open, close) {
   let result = '';
   let i = 0;
@@ -218,6 +263,7 @@ function stripDelimited(str, open, close) {
   return result;
 }
 
+/** @param {HTMLParserHandler} handler */
 function buildAttrRegex(handler) {
   const unquotedValue = handler.continueOnParseError ? singleAttrValueLenientUnquoted : singleAttrValues[2];
   const attrValues = [singleAttrValues[0], singleAttrValues[1], unquotedValue];
@@ -225,12 +271,19 @@ function buildAttrRegex(handler) {
     '(?:\\s*(' + joinSingleAttrAssigns(handler) + ')' +
     '[ \\t\\n\\f\\r]*(?:' + attrValues.join('|') + '))?';
   if (handler.customAttrSurround) {
+    if (!Array.isArray(handler.customAttrSurround)) {
+      throw new Error('`customAttrSurround` must be an array of `[RegExp, RegExp]` pairs');
+    }
     const attrClauses = [];
     for (let i = handler.customAttrSurround.length - 1; i >= 0; i--) {
+      const pair = handler.customAttrSurround[i];
+      if (!Array.isArray(pair) || !(pair[0] instanceof RegExp) || !(pair[1] instanceof RegExp)) {
+        throw new Error('`customAttrSurround` entries must be `[RegExp, RegExp]` pairs');
+      }
       attrClauses[i] = '(?:' +
-        '(' + handler.customAttrSurround[i][0].source + ')\\s*' +
+        '(' + pair[0].source + ')\\s*' +
         pattern +
-        '\\s*(' + handler.customAttrSurround[i][1].source + ')' +
+        '\\s*(' + pair[1].source + ')' +
         ')';
     }
     attrClauses.push('(?:' + pattern + ')');
@@ -239,6 +292,7 @@ function buildAttrRegex(handler) {
   return new RegExp('^\\s*' + pattern);
 }
 
+/** @param {HTMLParserHandler} handler */
 function getAttrRegexForHandler(handler) {
   let cached = attrRegexCache.get(handler);
   if (cached) return cached;
@@ -250,6 +304,7 @@ function getAttrRegexForHandler(handler) {
 // Cache for sticky attribute regexes (`y` flag for position-based matching on full string)
 const attrRegexStickyCache = new WeakMap();
 
+/** @param {HTMLParserHandler} handler */
 function getAttrRegexStickyForHandler(handler) {
   let cached = attrRegexStickyCache.get(handler);
   if (cached) return cached;
@@ -260,6 +315,7 @@ function getAttrRegexStickyForHandler(handler) {
   return compiled;
 }
 
+/** @param {HTMLParserHandler} handler */
 function joinSingleAttrAssigns(handler) {
   return singleAttrAssigns.concat(
     handler.customAttrAssign || []
@@ -272,6 +328,10 @@ function joinSingleAttrAssigns(handler) {
 const NCP = 7;
 
 class HTMLParser {
+  /**
+   * @param {string} html
+   * @param {HTMLParserHandler} handler
+   */
   constructor(html, handler) {
     this.html = html;
     this.handler = handler;
@@ -282,12 +342,21 @@ class HTMLParser {
     const fullHtml = this.html;
     const fullLength = fullHtml.length;
 
-    const stack = []; let lastTag;
+    /** @type {Array<{tag: string, lowerTag: string, attrs: HTMLAttribute[]}>} */
+    const stack = [];
+    /** @type {string} */
+    let lastTag = '';
     // Use cached attribute regex for this handler configuration
     const attribute = getAttrRegexForHandler(handler);
     const attributeY = getAttrRegexStickyForHandler(handler);
-    let prevTag = undefined, nextTag = undefined;
-    let prevAttrs = [], nextAttrs = [];
+    /** @type {string | undefined} */
+    let prevTag;
+    /** @type {string | undefined} */
+    let nextTag;
+    /** @type {HTMLAttribute[]} */
+    let prevAttrs = [];
+    /** @type {HTMLAttribute[]} */
+    let nextAttrs = [];
 
     // Sticky regex versions for position-based matching (avoids string slicing)
     const startTagOpenY = new RegExp(startTagOpen.source.slice(1), 'y');
@@ -307,10 +376,10 @@ class HTMLParser {
     let lastPos;
 
     // Helper to advance position
-    const advance = (n) => { pos += n; };
+    const advance = (/** @type {number} */ n) => { pos += n; };
 
     // Lazy line/column calculation—only compute on actual errors
-    const getLineColumn = (position) => {
+    const getLineColumn = (/** @type {number} */ position) => {
       let line = 1;
       let column = 1;
       for (let i = 0; i < position; i++) {
@@ -325,7 +394,7 @@ class HTMLParser {
     };
 
     // Helper to safely extract substring when needed for stacked tag content
-    const sliceFromPos = (startPos) => {
+    const sliceFromPos = (/** @type {number} */ startPos) => {
       return fullHtml.slice(startPos);
     };
 
@@ -353,9 +422,9 @@ class HTMLParser {
             const endTagMatch = cachedNextEndTag.match;
             cachedNextStartTag = null;
             cachedNextEndTag = null;
-            advance(endTagMatch[0].length);
-            await parseEndTag(endTagMatch[0], endTagMatch[1]);
-            prevTag = '/' + endTagMatch[1].toLowerCase();
+            advance((endTagMatch[0] ?? '').length);
+            await parseEndTag(endTagMatch[0] ?? '', endTagMatch[1] ?? '');
+            prevTag = '/' + (endTagMatch[1] ?? '').toLowerCase();
             prevAttrs = [];
             continue;
           }
@@ -413,9 +482,9 @@ class HTMLParser {
           endTagY.lastIndex = pos;
           const endTagMatch = endTagY.exec(fullHtml);
           if (endTagMatch) {
-            advance(endTagMatch[0].length);
-            await parseEndTag(endTagMatch[0], endTagMatch[1]);
-            prevTag = '/' + endTagMatch[1].toLowerCase();
+            advance((endTagMatch[0] ?? '').length);
+            await parseEndTag(endTagMatch[0] ?? '', endTagMatch[1] ?? '');
+            prevTag = '/' + (endTagMatch[1] ?? '').toLowerCase();
             prevAttrs = [];
             continue;
           }
@@ -473,12 +542,12 @@ class HTMLParser {
       } else {
         const stackedTag = lastTag.toLowerCase();
         // Use pre-compiled regex for common tags (`script`, `style`, `noscript`) to avoid regex creation overhead
-        const reStackedTag = preCompiledStackedTags[stackedTag] || reCache[stackedTag] || (reCache[stackedTag] = new RegExp('([\\s\\S]*?)\\x3c/' + stackedTag + '[^>]*>', 'i'));
+        const reStackedTag = /** @type {Record<string, RegExp>} */ (preCompiledStackedTags)[stackedTag] || /** @type {Record<string, RegExp>} */ (reCache)[stackedTag] || (/** @type {Record<string, RegExp>} */ (reCache)[stackedTag] = new RegExp('([\\s\\S]*?)\\x3c/' + stackedTag + '[^>]*>', 'i'));
 
         const remaining = sliceFromPos(pos);
         const m = reStackedTag.exec(remaining);
         if (m && m.index === 0) {
-          let text = m[1];
+          let text = m[1] ?? '';
           if (stackedTag !== 'script' && stackedTag !== 'style' && stackedTag !== 'noscript') {
             text = stripDelimited(stripDelimited(text, '<!--', '-->'), '<![CDATA[', ']]>');
           }
@@ -518,40 +587,39 @@ class HTMLParser {
         const CONTEXT_BEFORE = 50;
         const startPos = Math.max(0, pos - CONTEXT_BEFORE);
         const snippet = fullHtml.slice(startPos, startPos + 200).replace(/\n/g, ' ');
-        throw new Error(
-          `Parse error at line ${loc.line}, column ${loc.column}:\n${snippet}${fullHtml.length > startPos + 200 ? '…' : ''}`
-        );
+        throw new Error(`Parse error at line ${loc.line}, column ${loc.column}:\n${snippet}${fullHtml.length > startPos + 200 ? '…' : ''}`);
       }
     }
 
     if (!handler.partialMarkup) {
       // Clean up any remaining tags
-      await parseEndTag();
+      await parseEndTag('', '');
     }
 
     // Helper to extract minimal attribute info (name/value pairs) from raw attribute matches
     // Used for whitespace collapsing logic—doesn’t need full processing
-    function extractAttrInfo(rawAttrs) {
+    function extractAttrInfo(/** @type {Array<Array<string | undefined>>} */ rawAttrs) {
       if (!rawAttrs || !rawAttrs.length) return [];
 
       const numCustomParts = handler.customAttrSurround ? handler.customAttrSurround.length * NCP : 0;
       const baseIndex = 1 + numCustomParts;
 
-      return rawAttrs.map(args => {
+      return /** @type {HTMLAttribute[]} */ (rawAttrs.map((/** @type {Array<string | undefined>} */ args) => {
         // Extract attribute name (always at `baseIndex`)
         const name = args[baseIndex];
         // Extract value from double-quoted (`baseIndex + 2`), single-quoted (`baseIndex + 3`), or unquoted (`baseIndex + 4`)
         const value = args[baseIndex + 2] ?? args[baseIndex + 3] ?? args[baseIndex + 4];
-        return { name: name?.toLowerCase(), value };
-      }).filter(attr => attr.name); // Filter out invalid entries
+        return { name: name?.toLowerCase() ?? '', value };
+      }).filter(attr => attr.name)); // Filter out invalid entries
     }
 
-    function parseStartTag(startPos) {
+    function parseStartTag(/** @type {number} */ startPos) {
       startTagOpenY.lastIndex = startPos;
       const start = startTagOpenY.exec(fullHtml);
       if (start) {
+        /** @type {{tagName: string, attrs: Array<Array<string|undefined>>, advance: number, unarySlash?: string}} */
         const match = {
-          tagName: start[1],
+          tagName: start[1] ?? '',
           attrs: [],
           advance: 0
         };
@@ -694,19 +762,21 @@ class HTMLParser {
         startTagCloseY.lastIndex = currentPos;
         end = startTagCloseY.exec(fullHtml);
         if (end) {
-          match.unarySlash = end[1];
-          consumed += end[0].length;
+          match.unarySlash = end[1] ?? '';
+          consumed += (end[0] ?? '').length;
           match.advance = consumed;
           return match;
         }
       }
+      return undefined;
     }
 
-    function findTagInCurrentTable(tagName) {
+    function findTagInCurrentTable(/** @type {string} */ tagName) {
       let pos;
       const needle = tagName.toLowerCase();
       for (pos = stack.length - 1; pos >= 0; pos--) {
-        const currentTag = stack[pos].lowerTag;
+        const entry = stack[pos];
+        const currentTag = entry?.lowerTag;
         if (currentTag === needle) {
           return pos;
         }
@@ -718,18 +788,19 @@ class HTMLParser {
       return -1;
     }
 
-    async function parseEndTagAt(pos) {
+    async function parseEndTagAt(/** @type {number} */ pos) {
       // Close all open elements up to `pos` (mirrors `parseEndTag`’s core branch)
       for (let i = stack.length - 1; i >= pos; i--) {
+        const entry = /** @type {NonNullable<(typeof stack)[number]>} */ (stack[i]);
         if (handler.end) {
-          await handler.end(stack[i].tag, stack[i].attrs, true);
+          await handler.end(entry.tag, entry.attrs, true);
         }
       }
       stack.length = pos;
-      lastTag = pos && stack[pos - 1].tag;
+      lastTag = pos ? (stack[pos - 1]?.tag ?? '') : '';
     }
 
-    async function closeIfFoundInCurrentTable(tagName) {
+    async function closeIfFoundInCurrentTable(/** @type {string} */ tagName) {
       const pos = findTagInCurrentTable(tagName);
       if (pos >= 0) {
         // Close at the specific index to avoid re-searching
@@ -739,7 +810,7 @@ class HTMLParser {
       return false;
     }
 
-    async function handleStartTag(match) {
+    async function handleStartTag(/** @type {{tagName: string, attrs: Array<Array<string | undefined>>, advance: number, unarySlash?: string}} */ match) {
       const tagName = match.tagName;
       let unarySlash = match.unarySlash;
 
@@ -781,17 +852,18 @@ class HTMLParser {
 
       const unary = empty.has(tagName) || (tagName === 'html' && lastTag === 'head') || !!unarySlash;
 
-      const attrs = match.attrs.map(function (args) {
+      const attrs = /** @type {HTMLAttribute[]} */ (match.attrs.map(function (/** @type {Array<string | undefined>} */ args) {
+        /** @type {string | undefined} */
         let name, value, customOpen, customClose, customAssign, quote;
 
         // Hackish workaround for Firefox bug, https://bugzilla.mozilla.org/show_bug.cgi?id=369778
-        if (IS_REGEX_CAPTURING_BROKEN && args[0].indexOf('""') === -1) {
+        if (IS_REGEX_CAPTURING_BROKEN && (args[0] ?? '').indexOf('""') === -1) {
           if (args[3] === '') { delete args[3]; }
           if (args[4] === '') { delete args[4]; }
           if (args[5] === '') { delete args[5]; }
         }
 
-        function populate(index) {
+        function populate(/** @type {number} */ index) {
           customAssign = args[index];
           value = args[index + 1];
           if (typeof value !== 'undefined') {
@@ -802,7 +874,7 @@ class HTMLParser {
             return '\'';
           }
           value = args[index + 3];
-          if (typeof value === 'undefined' && fillAttrs.has(name)) {
+          if (typeof value === 'undefined' && name && fillAttrs.has(name)) {
             value = name;
           }
           return '';
@@ -826,14 +898,14 @@ class HTMLParser {
         }
 
         return {
-          name,
+          name: name ?? '',
           value,
           customAssign: customAssign || '=',
           customOpen: customOpen || '',
           customClose: customClose || '',
           quote: quote || ''
         };
-      });
+      }));
 
       if (!unary) {
         stack.push({ tag: tagName, lowerTag: tagName.toLowerCase(), attrs });
@@ -849,18 +921,18 @@ class HTMLParser {
       }
     }
 
-    function findTag(tagName) {
+    function findTag(/** @type {string} */ tagName) {
       let pos;
       const needle = tagName.toLowerCase();
       for (pos = stack.length - 1; pos >= 0; pos--) {
-        if (stack[pos].lowerTag === needle) {
+        if (stack[pos]?.lowerTag === needle) {
           break;
         }
       }
       return pos;
     }
 
-    async function parseEndTag(tag, tagName) {
+    async function parseEndTag(/** @type {string} */ tag, /** @type {string} */ tagName) {
       let pos;
 
       // Find the closest opened tag of the same type
@@ -874,13 +946,13 @@ class HTMLParser {
         // Close all the open elements, up the stack
         for (let i = stack.length - 1; i >= pos; i--) {
           if (handler.end) {
-            handler.end(stack[i].tag, stack[i].attrs, i > pos || !tag);
+            handler.end(stack[i]?.tag, stack[i]?.attrs, i > pos || !tag);
           }
         }
 
         // Remove the open elements from the stack
         stack.length = pos;
-        lastTag = pos && stack[pos - 1].tag;
+        lastTag = pos ? (stack[pos - 1]?.tag ?? '') : '';
       } else if (handler.partialMarkup && tagName) {
         // In partial markup mode, preserve stray end tags
         if (handler.end) {
@@ -903,19 +975,31 @@ class HTMLParser {
 }
 
 class Sorter {
+  constructor() {
+    /** @type {string[]} */
+    this.keys = [];
+    /** @type {Map<string, Sorter>} */
+    this.sorterMap = new Map();
+  }
+
+  /**
+   * @param {string[]} tokens
+   * @param {number} fromIndex
+   * @returns {string[]}
+   */
   sort(tokens, fromIndex = 0) {
-    for (let i = 0, len = this.keys.length; i < len; i++) {
-      const token = this.keys[i];
+    for (const token of this.keys) {
 
       // Single pass: Count matches and collect non-matches
       let matchCount = 0;
       const others = [];
 
       for (let j = fromIndex; j < tokens.length; j++) {
-        if (tokens[j] === token) {
+        const t = /** @type {string} */ (tokens[j]);
+        if (t === token) {
           matchCount++;
         } else {
-          others.push(tokens[j]);
+          others.push(t);
         }
       }
 
@@ -925,12 +1009,12 @@ class Sorter {
         for (let j = 0; j < matchCount; j++) {
           tokens[writeIdx++] = token;
         }
-        for (let j = 0; j < others.length; j++) {
-          tokens[writeIdx++] = others[j];
+        for (const other of others) {
+          tokens[writeIdx++] = other;
         }
 
         const newFromIndex = fromIndex + matchCount;
-        return this.sorterMap.get(token).sort(tokens, newFromIndex);
+        return this.sorterMap.get(token)?.sort(tokens, newFromIndex) ?? tokens;
       }
     }
     return tokens;
@@ -939,22 +1023,24 @@ class Sorter {
 
 class TokenChain {
   constructor() {
-    // Use map instead of object properties for better performance
+    /** @type {Map<string, {arrays: string[][], processed: number}>} */
     this.map = new Map();
   }
 
+  /** @param {string[]} tokens */
   add(tokens) {
     tokens.forEach((token) => {
-      if (!this.map.has(token)) {
-        this.map.set(token, { arrays: [], processed: 0 });
+      let entry = this.map.get(token);
+      if (!entry) {
+        entry = { arrays: [], processed: 0 };
+        this.map.set(token, entry);
       }
-      this.map.get(token).arrays.push(tokens);
+      entry.arrays.push(tokens);
     });
   }
 
   createSorter() {
     const sorter = new Sorter();
-    sorter.sorterMap = new Map();
 
     // Convert map entries to array and sort by frequency (descending), then alphabetically
     const entries = Array.from(this.map.entries()).sort((a, b) => {
@@ -967,18 +1053,17 @@ class TokenChain {
       return a[0].localeCompare(b[0]);
     });
 
-    sorter.keys = [];
-
     entries.forEach(([token, data]) => {
       if (data.processed < data.arrays.length) {
         const chain = new TokenChain();
 
         data.arrays.forEach((tokens) => {
           // Build new array without the current token instead of splicing
+          /** @type {string[]} */
           const filtered = [];
-          for (let i = 0; i < tokens.length; i++) {
-            if (tokens[i] !== token) {
-              filtered.push(tokens[i]);
+          for (const t of tokens) {
+            if (t !== token) {
+              filtered.push(t);
             }
           }
 
@@ -1053,7 +1138,7 @@ const presets = {
 function getPreset(name) {
   if (!name) return null;
   const normalizedName = name.toLowerCase();
-  return presets[normalizedName] || null;
+  return /** @type {Record<string, object>} */ (presets)[normalizedName] || null;
 }
 
 /**
@@ -1238,11 +1323,9 @@ const reEmptyAttribute = new RegExp(
 
 const specialContentElements = new Set(['script', 'style']);
 
-// Imports
-
-
 // Trim whitespace
 
+/** @param {string} str */
 const trimWhitespace = str => {
   if (!str) return str;
   // Fast path: If no whitespace at start or end, return early
@@ -1254,6 +1337,7 @@ const trimWhitespace = str => {
 
 // Collapse all whitespace
 
+/** @param {string} str */
 function collapseWhitespaceAll(str) {
   if (!str) return str;
   // Fast path: If there are no common whitespace characters, return early
@@ -1261,7 +1345,7 @@ function collapseWhitespaceAll(str) {
     return str;
   }
   // No-break space is specifically handled inside the replacer function here:
-  return str.replace(RE_ALL_WS_NBSP, function (spaces) {
+  return str.replace(RE_ALL_WS_NBSP, function (/** @param {string} spaces */ spaces) {
     // Preserve standalone tabs
     if (spaces === '\t') return '\t';
     // Fast path: No no-break space, common case—just collapse to single space
@@ -1274,7 +1358,14 @@ function collapseWhitespaceAll(str) {
 
 // Collapse whitespace with options
 
-function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
+/**
+ * @param {string} str
+ * @param {{preserveLineBreaks?: boolean | undefined, conservativeCollapse?: boolean | undefined}} options
+ * @param {boolean} trimLeft
+ * @param {boolean} trimRight
+ * @param {boolean} [collapseAll]
+ */
+function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll = false) {
   let lineBreakBefore = ''; let lineBreakAfter = '';
 
   if (!str) return str;
@@ -1294,7 +1385,7 @@ function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
     // (avoids polynomial backtracking with end-anchored lazy quantifiers)
     const WS_CHARS = ' \n\r\t\f';
     let leadEnd = 0;
-    while (leadEnd < str.length && WS_CHARS.includes(str[leadEnd])) {
+    while (leadEnd < str.length && WS_CHARS.includes(str.charAt(leadEnd))) {
       leadEnd++;
     }
     if (leadEnd > 0) {
@@ -1305,7 +1396,7 @@ function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
       }
     }
     let trailStart = str.length;
-    while (trailStart > 0 && WS_CHARS.includes(str[trailStart - 1])) {
+    while (trailStart > 0 && WS_CHARS.includes(str.charAt(trailStart - 1))) {
       trailStart--;
     }
     if (trailStart < str.length) {
@@ -1319,7 +1410,7 @@ function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
 
   if (trimLeft) {
     // No-break space is specifically handled inside the replacer function
-    str = str.replace(/^[ \n\r\t\f\xA0]+/, function (spaces) {
+    str = str.replace(/^[ \n\r\t\f\xA0]+/, function (/** @type {string} */ spaces) {
       const conservative = !lineBreakBefore && options.conservativeCollapse;
       if (conservative && spaces === '\t') {
         return '\t';
@@ -1332,7 +1423,7 @@ function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
     // Find trailing whitespace boundary manually (avoids polynomial backtracking
     // with `/[ \n\r\t\f\xA0]+$/` on strings with long internal whitespace runs)
     let end = str.length;
-    while (end > 0 && ' \n\r\t\f\xA0'.includes(str[end - 1])) {
+    while (end > 0 && ' \n\r\t\f\xA0'.includes(str.charAt(end - 1))) {
       end--;
     }
     if (end < str.length) {
@@ -1363,14 +1454,24 @@ function collapseWhitespace(str, options, trimLeft, trimRight, collapseAll) {
 
 // Collapse whitespace smartly based on surrounding tags
 
+/**
+ * @param {string} str
+ * @param {string} prevTag
+ * @param {string} nextTag
+ * @param {Array<{name: string, value?: string}>} prevAttrs
+ * @param {Array<{name: string, value?: string}>} nextAttrs
+ * @param {{preserveLineBreaks?: boolean, conservativeCollapse?: boolean, collapseInlineTagWhitespace?: boolean}} options
+ * @param {Set<string>} inlineElements
+ * @param {Set<string>} inlineTextSet
+ */
 function collapseWhitespaceSmart(str, prevTag, nextTag, prevAttrs, nextAttrs, options, inlineElements, inlineTextSet) {
   const prevTagName = prevTag && (prevTag.charAt(0) === '/' ? prevTag.slice(1) : prevTag);
   const nextTagName = nextTag && (nextTag.charAt(0) === '/' ? nextTag.slice(1) : nextTag);
 
   // Helper: Check if an input element has `type="hidden"`
-  const isHiddenInput = (tagName, attrs) => {
+  const isHiddenInput = (/** @type {string} */ tagName, /** @type {Array<{name: string, value?: string}>} */ attrs) => {
     if (tagName !== 'input' || !attrs || !attrs.length) return false;
-    const typeAttr = attrs.find(attr => attr.name === 'type');
+    const typeAttr = attrs.find((/** @type {{name: string, value?: string}} */ attr) => attr.name === 'type');
     return typeAttr && typeAttr.value === 'hidden';
   };
 
@@ -1434,7 +1535,7 @@ function collapseWhitespaceSmart(str, prevTag, nextTag, prevAttrs, nextAttrs, op
     }
   }
 
-  return collapseWhitespace(str, options, trimLeft, trimRight, prevTag && nextTag);
+  return collapseWhitespace(str, options, Boolean(trimLeft), Boolean(trimRight), Boolean(prevTag && nextTag));
 }
 
 // Collapse/trim whitespace for given tag
@@ -1442,10 +1543,12 @@ function collapseWhitespaceSmart(str, prevTag, nextTag, prevAttrs, nextAttrs, op
 const noCollapseWhitespaceTags = new Set(['script', 'style', 'pre', 'textarea']);
 const noTrimWhitespaceTags = new Set(['pre', 'textarea']);
 
+/** @param {string} tag */
 function canCollapseWhitespace(tag) {
   return !noCollapseWhitespaceTags.has(tag);
 }
 
+/** @param {string} tag */
 function canTrimWhitespace(tag) {
   return !noTrimWhitespaceTags.has(tag);
 }
@@ -1606,13 +1709,14 @@ function createUrlMinifier(site) {
   };
 }
 
-// Imports
-
-
 // CSS processing
 
 // Wrap CSS declarations for inline styles and media queries
 // This ensures proper context for CSS minification
+/**
+ * @param {string} text
+ * @param {string} type
+ */
 function wrapCSS(text, type) {
   switch (type) {
     case 'inline':
@@ -1624,6 +1728,10 @@ function wrapCSS(text, type) {
   }
 }
 
+/**
+ * @param {string} text
+ * @param {string} type
+ */
 function unwrapCSS(text, type) {
   let matches;
   switch (type) {
@@ -1634,11 +1742,15 @@ function unwrapCSS(text, type) {
       matches = text.match(/^@media ([\s\S]*?)\s*{[\s\S]*}$/);
       break;
   }
-  return matches ? matches[1] : text;
+  return matches ? matches[1] ?? text : text;
 }
 
 // Script processing
 
+/**
+ * @param {string} text
+ * @param {{continueOnMinifyError?: boolean, log?: Function}} options
+ */
 function minifyJson(text, options) {
   try {
     return JSON.stringify(JSON.parse(text));
@@ -1652,11 +1764,11 @@ function minifyJson(text, options) {
   }
 }
 
+/** @param {Array<{name: string, value?: string}>} attrs */
 function hasJsonScriptType(attrs) {
-  for (let i = 0, len = attrs.length; i < len; i++) {
-    const attrName = attrs[i].name.toLowerCase();
-    if (attrName === 'type') {
-      const attrValue = trimWhitespace((attrs[i].value || '').split(/;/, 2)[0]).toLowerCase();
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'type') {
+      const attrValue = trimWhitespace((attr.value || '').split(/;/, 2)[0] ?? '').toLowerCase();
       if (jsonScriptTypes.has(attrValue)) {
         return true;
       }
@@ -1665,18 +1777,24 @@ function hasJsonScriptType(attrs) {
   return false;
 }
 
+/**
+ * @param {string} text
+ * @param {{continueOnMinifyError?: boolean, log?: Function, processScripts?: string[]}} options
+ * @param {Array<{name: string, value?: string | undefined}>} currentAttrs
+ * @param {Function} minifyHTML
+ */
 async function processScript(text, options, currentAttrs, minifyHTML) {
-  for (let i = 0, len = currentAttrs.length; i < len; i++) {
-    const attrName = currentAttrs[i].name.toLowerCase();
+  for (const attr of currentAttrs) {
+    const attrName = attr.name.toLowerCase();
     if (attrName === 'type') {
-      const rawValue = currentAttrs[i].value;
-      const normalizedValue = trimWhitespace((rawValue || '').split(/;/, 2)[0]).toLowerCase();
+      const rawValue = attr.value;
+      const normalizedValue = trimWhitespace((rawValue || '').split(/;/, 2)[0] ?? '').toLowerCase();
       // Minify JSON script types automatically
       if (jsonScriptTypes.has(normalizedValue)) {
         return minifyJson(text, options);
       }
       // Process custom script types if specified
-      if (options.processScripts && options.processScripts.indexOf(rawValue) > -1) {
+      if (options.processScripts && rawValue && options.processScripts.indexOf(rawValue) > -1) {
         return await minifyHTML(text, options);
       }
     }
@@ -1700,11 +1818,17 @@ const optionDefaults = {
   includeAutoGeneratedTags: false
 };
 
-// Imports
+// Type definitions
+
+/**
+ * @typedef {Record<string, any>} MinifierOptions
+ */
 
+// @@ Extract a `ProcessedOptions` typedef (with `name`, `log`, `canCollapseWhitespace`, `canTrimWhitespace`,`minifyCSS`, `minifyJS`, `minifyURLs` typed as required, non-optional) to replace the current `Record<string, any>` escape hatch and eliminate the `/** @type {Function} */` casts in htmlminifier.js
 
 // Helper functions
 
+/** @param {MinifierOptions} options */
 function shouldMinifyInnerHTML(options) {
   return Boolean(
     options.collapseWhitespace ||
@@ -1720,18 +1844,12 @@ function shouldMinifyInnerHTML(options) {
 // Main options processor
 
 /**
- * @param {Partial<MinifierOptions>} inputOptions - User-provided options
- * @param {Object} deps - Dependencies from htmlminifier.js
- * @param {Function} deps.getLightningCSS - Function to lazily load Lightning CSS
- * @param {Function} deps.getTerser - Function to lazily load Terser
- * @param {Function} deps.getSwc - Function to lazily load @swc/core
- * @param {Function} deps.getSvgo - Function to lazily load SVGO
- * @param {LRU} deps.cssMinifyCache - CSS minification cache
- * @param {LRU} deps.jsMinifyCache - JS minification cache
- * @param {LRU} deps.svgMinifyCache - SVG minification cache
+ * @param {MinifierOptions} inputOptions - User-provided options
+ * @param {{getLightningCSS?: Function | undefined, getTerser?: Function | undefined, getSwc?: Function | undefined, getSvgo?: Function | undefined, cssMinifyCache?: LRU | undefined, jsMinifyCache?: LRU | undefined, svgMinifyCache?: LRU | undefined}} [deps] - Dependencies from htmlminifier.js
  * @returns {MinifierOptions} Normalized options with defaults applied
  */
 const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getSvgo, cssMinifyCache, jsMinifyCache, svgMinifyCache } = {}) => {
+  /** @type {MinifierOptions} */
   const options = {
     name: lowercase,
     canCollapseWhitespace,
@@ -1744,13 +1862,13 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
     minifySVG: null
   };
 
-  const parseRegExpArray = (arr) => {
-    return Array.isArray(arr) ? arr.map(parseRegExp) : arr;
+  const parseRegExpArray = (/** @type {unknown} */ arr) => {
+    return Array.isArray(arr) ? arr.map(parseRegExp) : [];
   };
 
   // Helper for nested arrays (e.g., `customAttrSurround: [[start, end], …]`)
-  const parseNestedRegExpArray = (arr) => {
-    if (!Array.isArray(arr)) return arr;
+  const parseNestedRegExpArray = (/** @type {unknown} */ arr) => {
+    if (!Array.isArray(arr)) return [];
     return arr.map(item => {
       // If item is an array (a pair), recursively convert each element
       if (Array.isArray(item)) {
@@ -1791,13 +1909,16 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
         options.log = option;
       }
     } else if (key === 'minifyCSS' && typeof option !== 'function') {
-      if (!option) {
+      if (!option || !getLightningCSS || !cssMinifyCache) {
         return;
       }
 
       const lightningCssOptions = typeof option === 'object' ? option : {};
+      // Capture to preserve TypeScript narrowing across the async closure boundary below
+      const cssLoader = getLightningCSS;
+      const cssCache = cssMinifyCache;
 
-      options.minifyCSS = async function (text, type) {
+      options.minifyCSS = async function (/** @type {string} */ text, /** @type {string} */ type) {
         // Fast path: Nothing to minify
         if (!text || !text.trim()) {
           return text;
@@ -1809,7 +1930,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           text = await replaceAsync(
             text,
             /(url\s*\(\s*)(?:"([^"]*)"|'([^']*)'|([^\s)]+))(\s*\))/ig,
-            async function (match, prefix, dq, sq, unq, suffix) {
+            async function (/** @type {string} */ match, /** @type {string} */ prefix, /** @type {string | undefined} */ dq, /** @type {string | undefined} */ sq, /** @type {string | undefined} */ unq, /** @type {string} */ suffix) {
               const quote = dq != null ? '"' : (sq != null ? "'" : '');
               const url = dq ?? sq ?? unq ?? '';
               try {
@@ -1834,8 +1955,8 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           : (inputCSS + '|' + type + '|' + cssSig);
 
         try {
-          const cached = cssMinifyCache.get(cssKey);
-          if (cached) {
+          const cached = cssCache.get(cssKey);
+          if (cached !== undefined) {
             // Support both resolved values and in-flight promises
             return await cached;
           }
@@ -1843,7 +1964,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           // In-flight promise caching: Prevent duplicate concurrent minifications
           // of the same CSS content (same pattern as JS minification)
           const inFlight = (async () => {
-            const transformCSS = await getLightningCSS();
+            const transformCSS = await cssLoader();
             // Note: `Buffer.from()` is required—Lightning CSS API expects Uint8Array
             const result = transformCSS({
               filename: 'input.css',
@@ -1870,12 +1991,12 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
             return (text.trim() && !outputCSS.trim() && (looksLikeTemplate || hasUID)) ? text : outputCSS;
           })();
 
-          cssMinifyCache.set(cssKey, inFlight);
+          cssCache.set(cssKey, inFlight);
           const resolved = await inFlight;
-          cssMinifyCache.set(cssKey, resolved);
+          cssCache.set(cssKey, resolved);
           return resolved;
         } catch (err) {
-          cssMinifyCache.delete(cssKey);
+          cssCache.delete(cssKey);
           if (!options.continueOnMinifyError) {
             throw err;
           }
@@ -1884,10 +2005,15 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
         }
       };
     } else if (key === 'minifyJS' && typeof option !== 'function') {
-      if (!option) {
+      if (!option || !getTerser || !getSwc || !jsMinifyCache) {
         return;
       }
 
+      // Capture to preserve TypeScript narrowing across the async closure boundary below
+      const loadTerser = getTerser;
+      const loadSwc = getSwc;
+      const jsCache = jsMinifyCache;
+
       // Parse configuration
       const config = typeof option === 'object' ? option : {};
       const engine = (config.engine || 'terser').toLowerCase();
@@ -1922,7 +2048,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
         cont: !!options.continueOnMinifyError
       });
 
-      options.minifyJS = async function (text, inline, isModule) {
+      options.minifyJS = async function (/** @type {string} */ text, /** @type {boolean} */ inline, /** @type {boolean} */ isModule) {
         const start = text.match(/^\s*<!--.*/);
         const code = start ? text.slice(start[0].length).replace(/\n\s*-->\s*$/, '') : text;
 
@@ -1944,8 +2070,8 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           jsKey = (code.length > 2048 ? (hashContent(code) + '|') : (code + '|'))
             + (inline ? '1' : '0') + '|' + (isModule ? 'm' : '') + '|' + useEngine + '|' + optsSig;
 
-          const cached = jsMinifyCache.get(jsKey);
-          if (cached) {
+          const cached = jsCache.get(jsKey);
+          if (cached !== undefined) {
             return await cached;
           }
 
@@ -1961,11 +2087,11 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
                 },
                 ...(isModule ? { module: true } : {}) // Overrides user options: module detection takes precedence for `<script type=module>`
               };
-              const terser = await getTerser();
+              const terser = await loadTerser();
               const result = await terser(code, terserCallOptions);
               return result.code.replace(RE_TRAILING_SEMICOLON, '');
             } else if (useEngine === 'swc') {
-              const swc = await getSwc();
+              const swc = await loadSwc();
               // `swc.minify()` takes compress and mangle directly as options
               const result = await swc.minify(code, {
                 compress: true,
@@ -1978,12 +2104,12 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
             throw new Error(`Unknown JS minifier engine: ${useEngine}`);
           })();
 
-          jsMinifyCache.set(jsKey, inFlight);
+          jsCache.set(jsKey, inFlight);
           const resolved = await inFlight;
-          jsMinifyCache.set(jsKey, resolved);
+          jsCache.set(jsKey, resolved);
           return resolved;
         } catch (err) {
-          if (jsKey) jsMinifyCache.delete(jsKey);
+          if (jsKey) jsCache.delete(jsKey);
           if (!options.continueOnMinifyError) {
             throw err;
           }
@@ -2009,7 +2135,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
       // Create instance-specific cache (results depend on site configuration)
       const instanceCache = new LRU(500);
 
-      options.minifyURLs = function (text) {
+      options.minifyURLs = function (/** @type {string} */ text) {
         // Fast-path: Skip if text doesn’t look like a URL that needs processing
         // Only process if contains URL-like characters (`/`, `:`, `#`, `?`) or spaces that need encoding
         if (!/[/:?#\s]/.test(text)) {
@@ -2036,10 +2162,14 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
         }
       };
     } else if (key === 'minifySVG' && typeof option !== 'function') {
-      if (!option) {
+      if (!option || !getSvgo || !svgMinifyCache) {
         return;
       }
 
+      // Capture to preserve TypeScript narrowing across the async closure boundary below
+      const loadSvgo = getSvgo;
+      const svgCache = svgMinifyCache;
+
       const svgoOptions = typeof option === 'object' ? option : {};
 
       // Pre-compute option signature for cache keys
@@ -2048,7 +2178,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
         cont: !!options.continueOnMinifyError
       });
 
-      options.minifySVG = async function (svgContent) {
+      options.minifySVG = async function (/** @type {string} */ svgContent) {
         if (!svgContent || !svgContent.trim()) {
           return svgContent;
         }
@@ -2059,23 +2189,23 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           : (svgContent + '|' + svgSig);
 
         try {
-          const cached = svgMinifyCache.get(svgKey);
-          if (cached) {
+          const cached = svgCache.get(svgKey);
+          if (cached !== undefined) {
             return await cached;
           }
 
           const inFlight = (async () => {
-            const optimize = await getSvgo();
+            const optimize = await loadSvgo();
             const result = optimize(svgContent, svgoOptions);
             return result.data;
           })();
 
-          svgMinifyCache.set(svgKey, inFlight);
+          svgCache.set(svgKey, inFlight);
           const resolved = await inFlight;
-          svgMinifyCache.set(svgKey, resolved);
+          svgCache.set(svgKey, resolved);
           return resolved;
         } catch (err) {
-          svgMinifyCache.delete(svgKey);
+          svgCache.delete(svgKey);
           if (!options.continueOnMinifyError) {
             throw err;
           }
@@ -2099,11 +2229,16 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
   return options;
 };
 
-// Imports
+// Type definitions
 
+/**
+ * @typedef {{ name: string, value?: string | undefined, quote?: string, customAssign?: string, customOpen?: string, customClose?: string }} HTMLAttribute
+ *  Internal counterpart of the public typedef in `htmlminifier.js`—keep in sync.
+ */
 
 // Lazy-load entities (used for `decodeEntities` and event-handler attribute decode before `minifyJS`)
 
+/** @type {Promise<Function> | undefined} */
 let decodeHTMLStrictPromise;
 async function getDecodeHTMLStrict() {
   if (!decodeHTMLStrictPromise) {
@@ -2114,20 +2249,30 @@ async function getDecodeHTMLStrict() {
 
 // Validators
 
+/**
+ * @param {string} text
+ * @param {{ignoreCustomComments: RegExp[]}} options
+ */
 function isIgnoredComment(text, options) {
-  for (let i = 0, len = options.ignoreCustomComments.length; i < len; i++) {
-    if (options.ignoreCustomComments[i].test(text)) {
+  // @@ Optimize: `Array.isArray(options.ignoreCustomComments)` runs on every comment node; it could be eliminated once `parseRegExpArray` is tightened to coerce non-arrays to `[]` at setup time
+  if (!Array.isArray(options.ignoreCustomComments)) return false;
+  for (const pattern of options.ignoreCustomComments) {
+    if (pattern.test(text)) {
       return true;
     }
   }
   return false;
 }
 
+/**
+ * @param {string} attrName
+ * @param {{customEventAttributes?: RegExp[]}} options
+ */
 function isEventAttribute(attrName, options) {
   const patterns = options.customEventAttributes;
   if (patterns) {
-    for (let i = patterns.length; i--;) {
-      if (patterns[i].test(attrName)) {
+    for (const pattern of patterns) {
+      if (pattern.test(attrName)) {
         return true;
       }
     }
@@ -2136,14 +2281,19 @@ function isEventAttribute(attrName, options) {
   return RE_EVENT_ATTR_DEFAULT.test(attrName);
 }
 
+/** @param {string} value */
 function canRemoveAttributeQuotes(value) {
   // https://mathiasbynens.be/notes/unquoted-attribute-values
   return RE_CAN_REMOVE_ATTR_QUOTES.test(value);
 }
 
+/**
+ * @param {HTMLAttribute[]} attributes
+ * @param {string} attribute
+ */
 function attributesInclude(attributes, attribute) {
-  for (let i = attributes.length; i--;) {
-    if (attributes[i].name.toLowerCase() === attribute) {
+  for (const attr of attributes) {
+    if (attr.name.toLowerCase() === attribute) {
       return true;
     }
   }
@@ -2154,9 +2304,9 @@ function attributesInclude(attributes, attribute) {
  * Remove duplicate attributes from an attribute list.
  * Per HTML spec, when an attribute appears multiple times, the first occurrence wins.
  * Duplicate attributes result in invalid HTML, so only the first is kept.
- * @param {Array} attrs - Array of attribute objects with `name` property
+ * @param {HTMLAttribute[]} attrs - Array of attribute objects with `name` property
  * @param {boolean} caseSensitive - Whether to compare names case-sensitively (for XML/SVG)
- * @returns {Array} Deduplicated attribute array (modifies in place and returns)
+ * @returns {HTMLAttribute[]} Deduplicated attribute array (modifies in place and returns)
  */
 function deduplicateAttributes(attrs, caseSensitive) {
   if (attrs.length < 2) {
@@ -2166,8 +2316,7 @@ function deduplicateAttributes(attrs, caseSensitive) {
   const seen = new Set();
   let writeIndex = 0;
 
-  for (let i = 0; i < attrs.length; i++) {
-    const attr = attrs[i];
+  for (const attr of attrs) {
     const key = caseSensitive ? attr.name : attr.name.toLowerCase();
 
     if (!seen.has(key)) {
@@ -2180,6 +2329,12 @@ function deduplicateAttributes(attrs, caseSensitive) {
   return attrs;
 }
 
+/**
+ * @param {string} tag
+ * @param {string} attrName
+ * @param {string} attrValue
+ * @param {HTMLAttribute[]} attrs
+ */
 function isAttributeRedundant(tag, attrName, attrValue, attrs) {
   // Fast-path: Check if this element–attribute combination can possibly be redundant
   // before doing expensive string operations
@@ -2213,32 +2368,35 @@ function isAttributeRedundant(tag, attrName, attrValue, attrs) {
   }
 
   // Check general defaults
-  if (hasGeneralDefault && generalDefaults[attrName] === attrValue) {
+  if (hasGeneralDefault && /** @type {Record<string, string>} */ (generalDefaults)[attrName] === attrValue) {
     return true;
   }
 
   // Check tag-specific defaults
-  return tagHasDefaults && tagDefaults[tag][attrName] === attrValue;
+  return tagHasDefaults && /** @type {Record<string, string>} */ (/** @type {Record<string, unknown>} */ (tagDefaults)[tag])[attrName] === attrValue;
 }
 
 function isScriptTypeAttribute(attrValue = '') {
-  attrValue = trimWhitespace(attrValue.split(/;/, 2)[0]).toLowerCase();
+  attrValue = trimWhitespace(attrValue.split(/;/, 2)[0] ?? '').toLowerCase();
   return attrValue === '' || executableScriptsMimetypes.has(attrValue);
 }
 
 function keepScriptTypeAttribute(attrValue = '') {
-  attrValue = trimWhitespace(attrValue.split(/;/, 2)[0]).toLowerCase();
+  attrValue = trimWhitespace(attrValue.split(/;/, 2)[0] ?? '').toLowerCase();
   return keepScriptsMimetypes.has(attrValue);
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ */
 function isExecutableScript(tag, attrs) {
   if (tag !== 'script') {
     return false;
   }
-  for (let i = 0, len = attrs.length; i < len; i++) {
-    const attrName = attrs[i].name.toLowerCase();
-    if (attrName === 'type') {
-      return isScriptTypeAttribute(attrs[i].value);
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'type') {
+      return isScriptTypeAttribute(attr.value);
     }
   }
   return true;
@@ -2249,23 +2407,30 @@ function isStyleLinkTypeAttribute(attrValue = '') {
   return attrValue === '' || attrValue === 'text/css';
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ */
 function isStyleElement(tag, attrs) {
   if (tag !== 'style') {
     return false;
   }
-  for (let i = 0, len = attrs.length; i < len; i++) {
-    const attrName = attrs[i].name.toLowerCase();
-    if (attrName === 'type') {
-      return isStyleLinkTypeAttribute(attrs[i].value);
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'type') {
+      return isStyleLinkTypeAttribute(attr.value);
     }
   }
   return true;
 }
 
+/**
+ * @param {string} attrName
+ * @param {string} attrValue
+ */
 function isBooleanAttribute(attrName, attrValue) {
   return isSimpleBoolean.has(attrName) ||
     (attrName === 'draggable' && !isBooleanValue.has(attrValue)) ||
-    (collapsibleValues.has(attrName) && collapsibleValues.get(attrName).has(attrValue));
+    (collapsibleValues.has(attrName) && collapsibleValues.get(attrName)?.has(attrValue));
 }
 
 const uriTypeAttributes = new Map([
@@ -2285,6 +2450,10 @@ const uriTypeAttributes = new Map([
   ['script', new Set(['src', 'for'])]
 ]);
 
+/**
+ * @param {string} attrName
+ * @param {string} tag
+ */
 function isUriTypeAttribute(attrName, tag) {
   const set = uriTypeAttributes.get(tag);
   return set ? set.has(attrName) : false;
@@ -2304,55 +2473,87 @@ const numberTypeAttributes = new Map([
   ['td', new Set(['rowspan', 'colspan'])]
 ]);
 
+/**
+ * @param {string} attrName
+ * @param {string} tag
+ */
 function isNumberTypeAttribute(attrName, tag) {
   const set = numberTypeAttributes.get(tag);
   return set ? set.has(attrName) : false;
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ * @param {string} value
+ */
 function isLinkType(tag, attrs, value) {
   if (tag !== 'link') return false;
   const needle = String(value).toLowerCase();
-  for (let i = 0; i < attrs.length; i++) {
-    if (attrs[i].name.toLowerCase() === 'rel') {
-      const tokens = String(attrs[i].value).toLowerCase().split(/\s+/);
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'rel') {
+      const tokens = String(attr.value).toLowerCase().split(/\s+/);
       if (tokens.includes(needle)) return true;
     }
   }
   return false;
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ * @param {string} attrName
+ */
 function isMediaQuery(tag, attrs, attrName) {
   return attrName === 'media' && (isLinkType(tag, attrs, 'stylesheet') || isStyleElement(tag, attrs));
 }
 
+/**
+ * @param {string} attrName
+ * @param {string} tag
+ */
 function isSrcset(attrName, tag) {
   return attrName === 'srcset' && srcsetElements.has(tag);
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ */
 function isMetaViewport(tag, attrs) {
   if (tag !== 'meta') {
     return false;
   }
-  for (let i = 0, len = attrs.length; i < len; i++) {
-    if (attrs[i].name.toLowerCase() === 'name' && attrs[i].value.toLowerCase() === 'viewport') {
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'name' && (attr.value || '').toLowerCase() === 'viewport') {
       return true;
     }
   }
   return false;
 }
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ */
 function isContentSecurityPolicy(tag, attrs) {
   if (tag !== 'meta') {
     return false;
   }
-  for (let i = 0, len = attrs.length; i < len; i++) {
-    if (attrs[i].name.toLowerCase() === 'http-equiv' && attrs[i].value.toLowerCase() === 'content-security-policy') {
+  for (const attr of attrs) {
+    if (attr.name.toLowerCase() === 'http-equiv' && (attr.value || '').toLowerCase() === 'content-security-policy') {
       return true;
     }
   }
   return false;
 }
 
+/**
+ * @param {string} tag
+ * @param {string} attrName
+ * @param {string | undefined} attrValue
+ * @param {{removeEmptyAttributes?: boolean | Function}} options
+ */
 function canDeleteEmptyAttribute(tag, attrName, attrValue, options) {
   const isValueEmpty = !attrValue || attrValue.trim() === '';
   if (!isValueEmpty) {
@@ -2364,9 +2565,13 @@ function canDeleteEmptyAttribute(tag, attrName, attrValue, options) {
   return (tag === 'input' && attrName === 'value') || reEmptyAttribute.test(attrName);
 }
 
+/**
+ * @param {string} name
+ * @param {HTMLAttribute[]} attrs
+ */
 function hasAttrName(name, attrs) {
-  for (let i = attrs.length - 1; i >= 0; i--) {
-    if (attrs[i].name === name) {
+  for (const attr of attrs) {
+    if (attr.name === name) {
       return true;
     }
   }
@@ -2381,6 +2586,14 @@ const valueWhitespaceExemptElements = new Set(['button', 'data', 'input', 'optio
 
 // Returns the cleaned attribute value directly (sync) or as a Promise (async);
 // callers must handle both cases—use `isThenable()` to distinguish
+/**
+ * @param {string} tag
+ * @param {string} attrName
+ * @param {string} attrValue
+ * @param {Record<string, any>} options
+ * @param {HTMLAttribute[]} attrs
+ * @param {Function} minifyHTMLSelf
+ */
 function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTMLSelf) {
   const isEventAttr = isEventAttribute(attrName, options);
 
@@ -2404,9 +2617,9 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       return getDecodeHTMLStrict().then(decode => {
         const decoded = decode(attrValue);
         const result = options.minifyJS(decoded, true);
-        const reEncode = v => (v && v.indexOf('&') !== -1) ? v.replace(RE_AMP_ENTITY, '&amp;$1') : v;
+        const reEncode = (/** @type {string} */ v) => (v && v.indexOf('&') !== -1) ? v.replace(RE_AMP_ENTITY, '&amp;$1') : v;
         if (isThenable(result)) {
-          return result.then(reEncode, err => {
+          return result.then(reEncode, (/** @type {Error} */ err) => {
             if (!options.continueOnMinifyError) throw err;
             options.log && options.log(err);
             return attrValue;
@@ -2417,7 +2630,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
     }
     const result = options.minifyJS(attrValue, true);
     if (isThenable(result)) {
-      return result.catch(err => {
+      return result.catch((/** @type {Error} */ err) => {
         if (!options.continueOnMinifyError) throw err;
         options.log && options.log(err);
         return attrValue;
@@ -2444,8 +2657,8 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
     const result = options.minifyURLs(attrValue);
     if (isThenable(result)) {
       return result
-        .then(out => typeof out === 'string' ? out : attrValue)
-        .catch(err => {
+        .then((/** @type {unknown} */ out) => typeof out === 'string' ? out : attrValue)
+        .catch((/** @type {Error} */ err) => {
           if (!options.continueOnMinifyError) throw err;
           options.log && options.log(err);
           return attrValue;
@@ -2468,13 +2681,13 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       const cssResult = options.minifyCSS(attrValue, 'inline');
       if (isThenable(cssResult)) {
         return cssResult
-          .then(minified => {
+          .then((/** @type {string} */ minified) => {
             // After minification, check if CSS consists entirely of invalid properties (no values)
             // I.e., `color:` or `margin:;padding:` should be treated as empty
             if (minified && /^(?:[a-z-]+:[;\s]*)+$/i.test(minified)) return '';
             return minified;
           })
-          .catch(err => {
+          .catch((/** @type {Error} */ err) => {
             if (!options.continueOnMinifyError) throw err;
             options.log && options.log(err);
             return originalAttrValue;
@@ -2496,8 +2709,9 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       const match = candidate.match(/\s+([1-9][0-9]*w|[0-9]+(?:\.[0-9]+)?x)$/);
       if (match) {
         url = url.slice(0, -match[0].length);
-        const num = +match[1].slice(0, -1);
-        const suffix = match[1].slice(-1);
+        const group = match[1] ?? '';
+        const num = +group.slice(0, -1);
+        const suffix = group.slice(-1);
         if (num !== 1 || suffix !== 'x') {
           descriptor = ' ' + num + suffix;
         }
@@ -2505,8 +2719,8 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
       const out = options.minifyURLs(url);
       if (isThenable(out)) {
         return out
-          .then(result => (typeof result === 'string' ? result : url) + descriptor)
-          .catch(err => {
+          .then((/** @type {unknown} */ result) => (typeof result === 'string' ? result : url) + descriptor)
+          .catch((/** @type {Error} */ err) => {
             if (!options.continueOnMinifyError) throw err;
             options.log && options.log(err);
             return url + descriptor;
@@ -2551,7 +2765,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
     const originalAttrValue = attrValue;
     const cssResult = options.minifyCSS(attrValue, 'media');
     if (isThenable(cssResult)) {
-      return cssResult.catch(err => {
+      return cssResult.catch((/** @type {Error} */ err) => {
         if (!options.continueOnMinifyError) throw err;
         options.log && options.log(err);
         return originalAttrValue;
@@ -2575,7 +2789,7 @@ function cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTM
 /**
  * Choose appropriate quote character for an attribute value
  * @param {string} attrValue - The attribute value
- * @param {Object} options - Minifier options
+ * @param {{quoteCharacter?: string}} options - Minifier options
  * @returns {string} The chosen quote character (`"` or `'`)
  */
 function chooseAttributeQuote(attrValue, options) {
@@ -2594,6 +2808,13 @@ function chooseAttributeQuote(attrValue, options) {
 
 // Returns the normalized attribute object directly (sync) or as a Promise (async);
 // callers must handle both cases—use `isThenable()` to distinguish
+/**
+ * @param {HTMLAttribute} attr
+ * @param {HTMLAttribute[]} attrs
+ * @param {string} tag
+ * @param {Record<string, any>} options
+ * @param {Function} minifyHTML
+ */
 function normalizeAttr(attr, attrs, tag, options, minifyHTML) {
   const attrName = options.name(attr.name);
   let attrValue = attr.value;
@@ -2609,9 +2830,18 @@ function normalizeAttr(attr, attrs, tag, options, minifyHTML) {
 }
 
 // Internal: Handles attribute normalization after entity decoding (if any)
+/**
+ * @param {string} attrName
+ * @param {string | undefined} attrValue
+ * @param {HTMLAttribute} attr
+ * @param {HTMLAttribute[]} attrs
+ * @param {string} tag
+ * @param {Record<string, any>} options
+ * @param {Function} minifyHTML
+ */
 function normalizeAttrContinue(attrName, attrValue, attr, attrs, tag, options, minifyHTML) {
   if ((options.removeRedundantAttributes &&
-       isAttributeRedundant(tag, attrName, attrValue, attrs)) ||
+       isAttributeRedundant(tag, attrName, attrValue ?? '', attrs)) ||
       (options.removeScriptTypeAttributes && tag === 'script' &&
        attrName === 'type' && isScriptTypeAttribute(attrValue) && !keepScriptTypeAttribute(attrValue)) ||
       (options.removeStyleLinkTypeAttributes && (tag === 'style' || tag === 'link') &&
@@ -2622,7 +2852,7 @@ function normalizeAttrContinue(attrName, attrValue, attr, attrs, tag, options, m
   if (attrValue) {
     const cleaned = cleanAttributeValue(tag, attrName, attrValue, options, attrs, minifyHTML);
     if (isThenable(cleaned)) {
-      return cleaned.then(v => normalizeAttrFinish(attrName, v, attr, tag, options));
+      return cleaned.then((/** @type {string | undefined} */ v) => normalizeAttrFinish(attrName, v, attr, tag, options));
     }
     return normalizeAttrFinish(attrName, cleaned, attr, tag, options);
   }
@@ -2631,6 +2861,13 @@ function normalizeAttrContinue(attrName, attrValue, attr, attrs, tag, options, m
 }
 
 // Internal: Final checks and result assembly after value cleaning
+/**
+ * @param {string} attrName
+ * @param {string | undefined} attrValue
+ * @param {HTMLAttribute} attr
+ * @param {string} tag
+ * @param {Record<string, any>} options
+ */
 function normalizeAttrFinish(attrName, attrValue, attr, tag, options) {
   if (options.removeEmptyAttributes &&
       canDeleteEmptyAttribute(tag, attrName, attrValue, options)) {
@@ -2648,6 +2885,13 @@ function normalizeAttrFinish(attrName, attrValue, attr, tag, options) {
   };
 }
 
+/**
+ * @param {{name: string, value?: string, attr: HTMLAttribute}} normalized
+ * @param {string | boolean | undefined} hasUnarySlash
+ * @param {Record<string, any>} options
+ * @param {boolean} isLast
+ * @param {string | undefined} uidAttr
+ */
 function buildAttr(normalized, hasUnarySlash, options, isLast, uidAttr) {
   const attrName = normalized.name;
   let attrValue = normalized.value;
@@ -2659,7 +2903,7 @@ function buildAttr(normalized, hasUnarySlash, options, isLast, uidAttr) {
   // Determine if need to add/keep quotes
   const shouldAddQuotes = typeof attrValue !== 'undefined' && (
     // If `removeAttributeQuotes` is enabled, add quotes only if they can’t be removed
-    (options.removeAttributeQuotes && (attrValue.indexOf(uidAttr) !== -1 || !canRemoveAttributeQuotes(attrValue))) ||
+    (options.removeAttributeQuotes && ((uidAttr ? attrValue.indexOf(uidAttr) !== -1 : false) || !canRemoveAttributeQuotes(attrValue))) ||
     // If `removeAttributeQuotes` is not enabled, preserve original quote style or add quotes if value requires them
     (!options.removeAttributeQuotes && (attrQuote !== '' || !canRemoveAttributeQuotes(attrValue) ||
       // Special case: With `removeTagWhitespace`, unquoted values that aren’t last will have space added,
@@ -2668,6 +2912,7 @@ function buildAttr(normalized, hasUnarySlash, options, isLast, uidAttr) {
   );
 
   if (shouldAddQuotes) {
+    attrValue = attrValue ?? '';
     // Determine the appropriate quote character
     if (!options.preventAttributesEscaping) {
       // Normal mode: Choose optimal quote type to minimize escaping
@@ -2769,11 +3014,20 @@ function buildAttr(normalized, hasUnarySlash, options, isLast, uidAttr) {
   return attr.customOpen + attrFragment + attr.customClose;
 }
 
-// Imports
+/** @import { HTMLAttribute } from './attributes.js' */
+
+// Type definitions
 
+/**
+ * @typedef {{ name: (str: string) => string, log?: Function }} MinifierOptions
+ */
 
 // Tag omission rules
 
+/**
+ * @param {string} optionalStartTag
+ * @param {string} tag
+ */
 function canRemoveParentTag(optionalStartTag, tag) {
   switch (optionalStartTag) {
     case 'html':
@@ -2789,6 +3043,10 @@ function canRemoveParentTag(optionalStartTag, tag) {
   return false;
 }
 
+/**
+ * @param {string} optionalEndTag
+ * @param {string} tag
+ */
 function isStartTagMandatory(optionalEndTag, tag) {
   switch (tag) {
     case 'colgroup':
@@ -2799,6 +3057,10 @@ function isStartTagMandatory(optionalEndTag, tag) {
   return false;
 }
 
+/**
+ * @param {string} optionalEndTag
+ * @param {string} tag
+ */
 function canRemovePrecedingTag(optionalEndTag, tag) {
   switch (optionalEndTag) {
     case 'html':
@@ -2838,6 +3100,10 @@ function canRemovePrecedingTag(optionalEndTag, tag) {
 
 // Element removal logic
 
+/**
+ * @param {string} tag
+ * @param {HTMLAttribute[]} attrs
+ */
 function canRemoveElement(tag, attrs) {
   // Elements with `id` attribute must never be removed—they serve as:
   // - Navigation targets (skip links, URL fragments)
@@ -2905,20 +3171,21 @@ function parseElementSpec(str, options) {
     return null;
   }
 
-  const tag = options.name(match[1]);
-  const attrString = match[2];
+  const tag = options.name(match[1] ?? '');
+  const attrString = match[2] ?? '';
 
   if (!attrString.trim()) {
     return { tag, attrs: null };
   }
 
   // Parse attributes from string
+  /** @type {{[key: string]: string | undefined}} */
   const attrs = {};
   const attrRegex = /([a-zA-Z][\w:-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>/]+)))?/g;
   let attrMatch;
 
   while ((attrMatch = attrRegex.exec(attrString))) {
-    const attrName = options.name(attrMatch[1]);
+    const attrName = options.name(attrMatch[1] ?? '');
     const attrValue = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4];
     // Boolean attributes have no value (undefined)
     attrs[attrName] = attrValue;
@@ -2940,7 +3207,7 @@ function parseRemoveEmptyElementsExcept(input, options) {
     return [];
   }
 
-  return input.map(item => {
+  return /** @type {Array<{tag: string, attrs: {[x: string]: string | undefined} | null}>} */ (input.map(item => {
     if (typeof item === 'string') {
       const spec = parseElementSpec(item, options);
       if (!spec && options.log) {
@@ -2952,7 +3219,7 @@ function parseRemoveEmptyElementsExcept(input, options) {
       options.log('Warning: “removeEmptyElementsExcept” specification must be a string, received: ' + typeof item);
     }
     return null;
-  }).filter(Boolean);
+  }).filter(Boolean));
 }
 
 /**
@@ -2995,261 +3262,29 @@ function shouldPreserveEmptyElement(tag, attrs, preserveList) {
   return false;
 }
 
-// Imports
-
-
-// Lazy-load heavy dependencies only when needed
-
-let lightningCSSPromise;
-async function getLightningCSS() {
-  if (!lightningCSSPromise) {
-    lightningCSSPromise = import('lightningcss').then(m => m.transform);
-  }
-  return lightningCSSPromise;
-}
-
-let terserPromise;
-async function getTerser() {
-  if (!terserPromise) {
-    terserPromise = import('terser').then(m => m.minify);
-  }
-  return terserPromise;
-}
-
-let swcPromise;
-async function getSwc() {
-  if (!swcPromise) {
-    swcPromise = import('@swc/core')
-      .then(m => m.default || m)
-      .catch(() => {
-        throw new Error(
-          'The swc minifier requires @swc/core to be installed.\n' +
-          'Install it with: npm install @swc/core'
-        );
-      });
-  }
-  return swcPromise;
-}
-
-let svgoPromise;
-async function getSvgo() {
-  if (!svgoPromise) {
-    svgoPromise = import('svgo').then(m => m.optimize);
-  }
-  return svgoPromise;
-}
-
-let decodeHTMLPromise;
-async function getDecodeHTML() {
-  if (!decodeHTMLPromise) {
-    decodeHTMLPromise = import('entities').then(m => m.decodeHTML);
-  }
-  return decodeHTMLPromise;
-}
-
-// Minification caches (initialized on first use with configurable sizes)
-let cssMinifyCache = null;
-let jsMinifyCache = null;
-let svgMinifyCache = null;
-
-// Pre-compiled patterns for script merging (avoid repeated allocation in hot path)
-const RE_SCRIPT_ATTRS = /([^\s=]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
-const RE_SCRIPT_OPEN = /<script(?=[\s>])/gi; // Finds tag start; use `findTagEnd()` for the actual closing `>`
-const RE_SCRIPT_CLOSE = /<\/script\s*>/gi;
-const SCRIPT_BOOL_ATTRS = new Set(['async', 'defer', 'nomodule']);
-const DEFAULT_JS_TYPES = new Set(['', 'text/javascript', 'application/javascript']);
-
-// Pre-compiled patterns for buffer scanning
-const RE_START_TAG = /^<[^/!]/;
-const RE_END_TAG = /^<\//;
-
-// Pre-compiled patterns for `htmlmin:ignore` block content analysis
-const RE_HTML_COMMENT_START = /^\s*<!--/;
-const RE_CLOSING_TAG_START = /^\s*<\/([a-zA-Z][\w:-]*)/;
-const RE_LAST_HTML_TAG = /[\s\S]*<(\/?[a-zA-Z][\w:-]*)/;
-
-// HTML encoding types for annotation-xml (MathML)
-const RE_HTML_ENCODING = /^(text\/html|application\/xhtml\+xml)$/i;
-
-// Script merging
+// Type definitions
 
 /**
- * Find the index of the `>` that closes an opening tag, correctly skipping
- * over quoted attribute values (which may contain `>`).
- * @param {string} html
- * @param {number} pos - Start position (just after the tag name)
- * @returns {number} Index of the closing `>`, or -1 if not found
+ * @typedef {Object} HTMLAttribute
+ *  Representation of an attribute from the HTML parser.
+ *  Internal counterpart: `HTMLAttribute` in `lib/attributes.js`—keep in sync.
+ *
+ * @prop {string} name
+ * @prop {string} [value]
+ * @prop {string} [quote]
+ * @prop {string} [customAssign]
+ * @prop {string} [customOpen]
+ * @prop {string} [customClose]
  */
-function findTagEnd(html, pos) {
-  let i = pos;
-  while (i < html.length) {
-    const ch = html[i];
-    if (ch === '>') return i;
-    if (ch === '"' || ch === "'") {
-      const q = ch;
-      i++;
-      while (i < html.length && html[i] !== q) i++;
-    }
-    i++;
-  }
-  return -1;
-}
 
 /**
- * Merge consecutive inline script tags into one (`mergeConsecutiveScripts`).
- * Only merges scripts that are compatible:
- * - Both inline (no `src` attribute)
- * - Same `type` (or both default JavaScript)
- * - No conflicting attributes (`async`, `defer`, `nomodule`, different `nonce`)
+ * @typedef {Object} MinifierOptions
+ *  Options that control how HTML is minified. All of these are optional
+ *  and usually default to a disabled/safe value unless noted.
  *
- * Uses a scanner rather than a regex to locate script boundaries, so literal
- * `</script>` strings inside script content are handled correctly per the HTML
- * spec (raw text ends at the first `</script>`).
- *
- * @param {string} html - The HTML string to process
- * @returns {string} HTML with consecutive scripts merged
- */
-function mergeConsecutiveScripts(html) {
-  // Parse an attribute string into a name→value map
-  const parseAttrs = (attrStr) => {
-    const attrs = {};
-    RE_SCRIPT_ATTRS.lastIndex = 0;
-    let m;
-    while ((m = RE_SCRIPT_ATTRS.exec(attrStr)) !== null) {
-      const name = m[1].toLowerCase();
-      const value = m[2] ?? m[3] ?? m[4] ?? '';
-      attrs[name] = value;
-    }
-    return attrs;
-  };
-
-  let changed = true;
-
-  // Keep merging until no more changes (handles chains of 3+ scripts)
-  while (changed) {
-    changed = false;
-    RE_SCRIPT_OPEN.lastIndex = 0;
-    let m1;
-
-    while ((m1 = RE_SCRIPT_OPEN.exec(html)) !== null) {
-      // Use findTagEnd() to get the real closing '>', skipping quoted attribute values
-      const tagEnd1 = findTagEnd(html, m1.index + 7);
-      if (tagEnd1 === -1) break;
-
-      const attrs1Str = html.slice(m1.index + 7, tagEnd1);
-      const contentStart1 = tagEnd1 + 1;
-
-      // Find end of this script’s content (first `</script>`—per HTML spec, raw text ends here)
-      RE_SCRIPT_CLOSE.lastIndex = contentStart1;
-      const close1 = RE_SCRIPT_CLOSE.exec(html);
-      if (!close1) break;
-
-      const content1 = html.slice(contentStart1, close1.index);
-      const afterClose1 = close1.index + close1[0].length;
-
-      // Skip optional whitespace and check for a consecutive <script> tag
-      let i = afterClose1;
-      while (i < html.length && (html[i] === ' ' || html[i] === '\t' || html[i] === '\n' || html[i] === '\r' || html[i] === '\f')) i++;
-      if (html.slice(i, i + 7).toLowerCase() !== '<script' || (html[i + 7] !== '>' && !/\s/.test(html[i + 7]))) {
-        RE_SCRIPT_OPEN.lastIndex = afterClose1;
-        continue;
-      }
-
-      const tagStart2 = i;
-      const tagEnd2 = findTagEnd(html, tagStart2 + 7);
-      if (tagEnd2 === -1) break;
-
-      const attrs2Str = html.slice(tagStart2 + 7, tagEnd2);
-      const contentStart2 = tagEnd2 + 1;
-
-      // Find end of second script’s content
-      RE_SCRIPT_CLOSE.lastIndex = contentStart2;
-      const close2 = RE_SCRIPT_CLOSE.exec(html);
-      if (!close2) break;
-
-      const content2 = html.slice(contentStart2, close2.index);
-      const afterClose2 = close2.index + close2[0].length;
-
-      const a1 = parseAttrs(attrs1Str);
-      const a2 = parseAttrs(attrs2Str);
-
-      // Check for `src`—cannot merge external scripts
-      if ('src' in a1 || 'src' in a2) {
-        RE_SCRIPT_OPEN.lastIndex = afterClose1;
-        continue;
-      }
-
-      // Check `type` compatibility (both must be default JS)
-      // Non-JS types (modules, JSON, etc.) must not be merged:
-      // Module scripts have per-script lexical scope, and non-JS content (e.g., JSON)
-      // is not concatenable; even identical non-JS types are incompatible
-      const type1 = (a1.type || '').toLowerCase();
-      const type2 = (a2.type || '').toLowerCase();
-      if (!DEFAULT_JS_TYPES.has(type1) || !DEFAULT_JS_TYPES.has(type2)) {
-        RE_SCRIPT_OPEN.lastIndex = afterClose1;
-        continue;
-      }
-
-      // Check for conflicting boolean attributes
-      let boolConflict = false;
-      for (const attr of SCRIPT_BOOL_ATTRS) {
-        if ((attr in a1) !== (attr in a2)) { boolConflict = true; break; }
-      }
-
-      // Check `nonce`—must be same or both absent
-      if (boolConflict || a1.nonce !== a2.nonce) {
-        RE_SCRIPT_OPEN.lastIndex = afterClose1;
-        continue;
-      }
-
-      // Scripts are compatible—merge them
-      changed = true;
-
-      // Combine content—use semicolon normally, newline only for trailing `//` comments
-      const c1 = content1.trim();
-      const c2 = content2.trim();
-      let mergedContent;
-      if (c1 && c2) {
-        // Check if last line of c1 contains `//` (single-line comment)
-        // If so, use newline to terminate it; otherwise use semicolon (if not already present)
-        const lastLine = c1.slice(c1.lastIndexOf('\n') + 1);
-        const separator = lastLine.includes('//') ? '\n' : (c1.endsWith(';') ? '' : ';');
-        mergedContent = c1 + separator + c2;
-      } else {
-        mergedContent = c1 || c2;
-      }
-
-      // Use first script’s attributes (they should be compatible)
-      html = html.slice(0, m1.index) + `<script${attrs1Str}>${mergedContent}</script>` + html.slice(afterClose2);
-      break; // Restart scanning (outer while loop)
-    }
-  }
-
-  return html;
-}
-
-// Type definitions
-
-/**
- * @typedef {Object} HTMLAttribute
- *  Representation of an attribute from the HTML parser.
- *
- * @prop {string} name
- * @prop {string} [value]
- * @prop {string} [quote]
- * @prop {string} [customAssign]
- * @prop {string} [customOpen]
- * @prop {string} [customClose]
- */
-
-/**
- * @typedef {Object} MinifierOptions
- *  Options that control how HTML is minified. All of these are optional
- *  and usually default to a disabled/safe value unless noted.
- *
- * @prop {(tag: string, attrs: HTMLAttribute[], canCollapseWhitespace: (tag: string) => boolean) => boolean} [canCollapseWhitespace]
- *  Predicate that determines whether whitespace inside a given element
- *  can be collapsed.
+ * @prop {(tag: string, attrs: HTMLAttribute[], canCollapseWhitespace: (tag: string) => boolean) => boolean} [canCollapseWhitespace]
+ *  Predicate that determines whether whitespace inside a given element
+ *  can be collapsed.
  *
  *  Default: Built-in `canCollapseWhitespace` function
  *
@@ -3642,23 +3677,275 @@ function mergeConsecutiveScripts(html) {
  *  See also: https://perfectionkills.com/experimenting-with-html-minifier/#use_short_doctype
  *
  *  Default: `false`
+ *
+ * @prop {boolean} [insideSVG] - Internal: Set when inside SVG/MathML context
+ * @prop {boolean} [insideForeignContent] - Internal: Set when inside SVG `foreignObject`
+ * @prop {Function} [parentName] - Internal: Preserved name function during namespace transitions
+ * @prop {Function} [htmlName] - Internal: HTML name function preserved from outer context
  */
 
+// Lazy-load heavy dependencies only when needed
+
+/** @type {Promise<Function> | undefined} */
+let lightningCSSPromise;
+async function getLightningCSS() {
+  if (!lightningCSSPromise) {
+    lightningCSSPromise = import('lightningcss').then(m => m.transform);
+  }
+  return lightningCSSPromise;
+}
+
+/** @type {Promise<Function> | undefined} */
+let terserPromise;
+async function getTerser() {
+  if (!terserPromise) {
+    terserPromise = import('terser').then(m => m.minify);
+  }
+  return terserPromise;
+}
+
+/** @type {Promise<any> | undefined} */
+let swcPromise;
+async function getSwc() {
+  if (!swcPromise) {
+    swcPromise = import('@swc/core')
+      .then(m => m.default || m)
+      .catch(() => {
+        throw new Error(
+          'The swc minifier requires @swc/core to be installed.\n' +
+          'Install it with: npm install @swc/core'
+        );
+      });
+  }
+  return swcPromise;
+}
+
+/** @type {Promise<Function> | undefined} */
+let svgoPromise;
+async function getSvgo() {
+  if (!svgoPromise) {
+    svgoPromise = import('svgo').then(m => m.optimize);
+  }
+  return svgoPromise;
+}
+
+/** @type {Promise<Function> | undefined} */
+let decodeHTMLPromise;
+async function getDecodeHTML() {
+  if (!decodeHTMLPromise) {
+    decodeHTMLPromise = import('entities').then(m => m.decodeHTML);
+  }
+  return decodeHTMLPromise;
+}
+
+// Minification caches (initialized on first use with configurable sizes)
+/** @type {LRU | null} */
+let cssMinifyCache = null;
+/** @type {LRU | null} */
+let jsMinifyCache = null;
+/** @type {LRU | null} */
+let svgMinifyCache = null;
+
+// Pre-compiled patterns for script merging (avoid repeated allocation in hot path)
+const RE_SCRIPT_ATTRS = /([^\s=]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+const RE_SCRIPT_OPEN = /<script(?=[\s>])/gi; // Finds tag start; use `findTagEnd()` for the actual closing `>`
+const RE_SCRIPT_CLOSE = /<\/script\s*>/gi;
+const SCRIPT_BOOL_ATTRS = new Set(['async', 'defer', 'nomodule']);
+const DEFAULT_JS_TYPES = new Set(['', 'text/javascript', 'application/javascript']);
+
+// Pre-compiled patterns for buffer scanning
+const RE_START_TAG = /^<[^/!]/;
+const RE_END_TAG = /^<\//;
+
+// Pre-compiled patterns for `htmlmin:ignore` block content analysis
+const RE_HTML_COMMENT_START = /^\s*<!--/;
+const RE_CLOSING_TAG_START = /^\s*<\/([a-zA-Z][\w:-]*)/;
+const RE_LAST_HTML_TAG = /[\s\S]*<(\/?[a-zA-Z][\w:-]*)/;
+
+// HTML encoding types for annotation-xml (MathML)
+const RE_HTML_ENCODING = /^(text\/html|application\/xhtml\+xml)$/i;
+
+// Script merging
+
+/**
+ * Find the index of the `>` that closes an opening tag, correctly skipping
+ * over quoted attribute values (which may contain `>`).
+ * @param {string} html
+ * @param {number} pos - Start position (just after the tag name)
+ * @returns {number} Index of the closing `>`, or -1 if not found
+ */
+function findTagEnd(html, pos) {
+  let i = pos;
+  while (i < html.length) {
+    const ch = html[i];
+    if (ch === '>') return i;
+    if (ch === '"' || ch === "'") {
+      const q = ch;
+      i++;
+      while (i < html.length && html[i] !== q) i++;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Merge consecutive inline script tags into one (`mergeConsecutiveScripts`).
+ * Only merges scripts that are compatible:
+ * - Both inline (no `src` attribute)
+ * - Same `type` (or both default JavaScript)
+ * - No conflicting attributes (`async`, `defer`, `nomodule`, different `nonce`)
+ *
+ * Uses a scanner rather than a regex to locate script boundaries, so literal
+ * `</script>` strings inside script content are handled correctly per the HTML
+ * spec (raw text ends at the first `</script>`).
+ *
+ * @param {string} html - The HTML string to process
+ * @returns {string} HTML with consecutive scripts merged
+ */
+function mergeConsecutiveScripts(html) {
+  // Parse an attribute string into a name→value map
+  const parseAttrs = (/** @type {string} */ attrStr) => {
+    /** @type {Record<string, string>} */
+    const attrs = {};
+    RE_SCRIPT_ATTRS.lastIndex = 0;
+    let m;
+    while ((m = RE_SCRIPT_ATTRS.exec(attrStr)) !== null) {
+      const name = (m[1] ?? '').toLowerCase();
+      const value = m[2] ?? m[3] ?? m[4] ?? '';
+      attrs[name] = value;
+    }
+    return attrs;
+  };
+
+  let changed = true;
+
+  // Keep merging until no more changes (handles chains of 3+ scripts)
+  while (changed) {
+    changed = false;
+    RE_SCRIPT_OPEN.lastIndex = 0;
+    let m1;
+
+    while ((m1 = RE_SCRIPT_OPEN.exec(html)) !== null) {
+      // Use findTagEnd() to get the real closing '>', skipping quoted attribute values
+      const tagEnd1 = findTagEnd(html, m1.index + 7);
+      if (tagEnd1 === -1) break;
+
+      const attrs1Str = html.slice(m1.index + 7, tagEnd1);
+      const contentStart1 = tagEnd1 + 1;
+
+      // Find end of this script’s content (first `</script>`—per HTML spec, raw text ends here)
+      RE_SCRIPT_CLOSE.lastIndex = contentStart1;
+      const close1 = RE_SCRIPT_CLOSE.exec(html);
+      if (!close1) break;
+
+      const content1 = html.slice(contentStart1, close1.index);
+      const afterClose1 = close1.index + close1[0].length;
+
+      // Skip optional whitespace and check for a consecutive <script> tag
+      let i = afterClose1;
+      while (i < html.length && (html[i] === ' ' || html[i] === '\t' || html[i] === '\n' || html[i] === '\r' || html[i] === '\f')) i++;
+      if (html.slice(i, i + 7).toLowerCase() !== '<script' || (html.charAt(i + 7) !== '>' && !/\s/.test(html.charAt(i + 7)))) {
+        RE_SCRIPT_OPEN.lastIndex = afterClose1;
+        continue;
+      }
+
+      const tagStart2 = i;
+      const tagEnd2 = findTagEnd(html, tagStart2 + 7);
+      if (tagEnd2 === -1) break;
+
+      const attrs2Str = html.slice(tagStart2 + 7, tagEnd2);
+      const contentStart2 = tagEnd2 + 1;
+
+      // Find end of second script’s content
+      RE_SCRIPT_CLOSE.lastIndex = contentStart2;
+      const close2 = RE_SCRIPT_CLOSE.exec(html);
+      if (!close2) break;
+
+      const content2 = html.slice(contentStart2, close2.index);
+      const afterClose2 = close2.index + close2[0].length;
+
+      const a1 = parseAttrs(attrs1Str);
+      const a2 = parseAttrs(attrs2Str);
+
+      // Check for `src`—cannot merge external scripts
+      if ('src' in a1 || 'src' in a2) {
+        RE_SCRIPT_OPEN.lastIndex = afterClose1;
+        continue;
+      }
+
+      // Check `type` compatibility (both must be default JS)
+      // Non-JS types (modules, JSON, etc.) must not be merged:
+      // Module scripts have per-script lexical scope, and non-JS content (e.g., JSON)
+      // is not concatenable; even identical non-JS types are incompatible
+      const type1 = (a1.type || '').toLowerCase();
+      const type2 = (a2.type || '').toLowerCase();
+      if (!DEFAULT_JS_TYPES.has(type1) || !DEFAULT_JS_TYPES.has(type2)) {
+        RE_SCRIPT_OPEN.lastIndex = afterClose1;
+        continue;
+      }
+
+      // Check for conflicting boolean attributes
+      let boolConflict = false;
+      for (const attr of SCRIPT_BOOL_ATTRS) {
+        if ((attr in a1) !== (attr in a2)) { boolConflict = true; break; }
+      }
+
+      // Check `nonce`—must be same or both absent
+      if (boolConflict || a1.nonce !== a2.nonce) {
+        RE_SCRIPT_OPEN.lastIndex = afterClose1;
+        continue;
+      }
+
+      // Scripts are compatible—merge them
+      changed = true;
+
+      // Combine content—use semicolon normally, newline only for trailing `//` comments
+      const c1 = content1.trim();
+      const c2 = content2.trim();
+      let mergedContent;
+      if (c1 && c2) {
+        // Check if last line of c1 contains `//` (single-line comment)
+        // If so, use newline to terminate it; otherwise use semicolon (if not already present)
+        const lastLine = c1.slice(c1.lastIndexOf('\n') + 1);
+        const separator = lastLine.includes('//') ? '\n' : (c1.endsWith(';') ? '' : ';');
+        mergedContent = c1 + separator + c2;
+      } else {
+        mergedContent = c1 || c2;
+      }
+
+      // Use first script’s attributes (they should be compatible)
+      html = html.slice(0, m1.index) + `<script${attrs1Str}>${mergedContent}</script>` + html.slice(afterClose2);
+      break; // Restart scanning (outer while loop)
+    }
+  }
+
+  return html;
+}
+
+/**
+ * @param {string} value
+ * @param {MinifierOptions} options
+ * @param {string} uidIgnore
+ * @param {string} uidAttr
+ * @param {string[]} ignoredMarkupChunks
+ */
 async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupChunks) {
   const attrChains = options.sortAttributes && typeof options.sortAttributes !== 'function' && Object.create(null);
   const classChain = options.sortClassNames && typeof options.sortClassNames !== 'function' && new TokenChain();
+  const resolveName = /** @type {(name: string) => string} */ (options.name);
 
-  function attrNames(attrs) {
+  function attrNames(/** @type {HTMLAttribute[]} */ attrs) {
     return attrs.map(function (attr) {
-      return options.name(attr.name);
+      return resolveName(attr.name);
     });
   }
 
-  function shouldSkipUID(token, uid) {
+  function shouldSkipUID(/** @type {string} */ token, /** @type {string} */ uid) {
     return !uid || token.indexOf(uid) === -1;
   }
 
-  function shouldKeepToken(token) {
+  function shouldKeepToken(/** @type {string} */ token) {
     // Filter out any HTML comment tokens (UID placeholders)
     // These are temporary markers created by `htmlmin:ignore` and `ignoreCustomFragments`
     if (token.startsWith('<!--') && token.endsWith('-->')) {
@@ -3672,10 +3959,13 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
   const whitespaceSplitPatternScan = /[ \t\n\f\r]+/;
   const whitespaceSplitPatternSort = /[ \n\f\r]+/;
 
-  async function scan(input) {
-    let currentTag, currentType;
+  async function scan(/** @type {string} */ input) {
+    /** @type {string} */
+    let currentTag;
+    /** @type {string | undefined} */
+    let currentType;
     const parser = new HTMLParser(input, {
-      start: function (tag, attrs) {
+      start: function (/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs) {
         if (attrChains) {
           if (!attrChains[tag]) {
             attrChains[tag] = new TokenChain();
@@ -3683,9 +3973,8 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
           const attrNamesList = attrNames(attrs).filter(shouldKeepToken);
           attrChains[tag].add(attrNamesList);
         }
-        for (let i = 0, len = attrs.length; i < len; i++) {
-          const attr = attrs[i];
-          if (classChain && attr.value && options.name(attr.name) === 'class') {
+        for (const attr of attrs) {
+          if (classChain && attr.value && resolveName(attr.name) === 'class') {
             const classes = trimWhitespace(attr.value).split(whitespaceSplitPatternScan).filter(shouldKeepToken);
             classChain.add(classes);
           } else if (options.processScripts && attr.name.toLowerCase() === 'type') {
@@ -3697,11 +3986,11 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
       end: function () {
         currentTag = '';
       },
-      chars: async function (text) {
+      chars: async function (/** @type {string} */ text) {
         // Only recursively scan HTML content, not JSON-LD or other non-HTML script types
         // `scan()` is for analyzing HTML attribute order, not for parsing JSON
         if (options.processScripts && specialContentElements.has(currentTag) &&
-            options.processScripts.indexOf(currentType) > -1 &&
+            options.processScripts.indexOf(currentType ?? '') > -1 &&
             currentType === 'text/html') {
           await scan(text);
         }
@@ -3760,7 +4049,7 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
     // Expand UID tokens back to the original content for frequency analysis
     let expandedValue = value;
     if (uidReplacePattern) {
-      expandedValue = value.replace(uidReplacePattern, function (match, index) {
+      expandedValue = value.replace(uidReplacePattern, function (/** @type {string} */ _match, /** @type {string} */ index) {
         return ignoredMarkupChunks[+index] || '';
       });
       // Reset `lastIndex` for pattern reuse
@@ -3781,7 +4070,11 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
     await scan(scanValue);
   } finally {
     // Restore original option
-    options.continueOnParseError = originalContinueOnParseError;
+    if (originalContinueOnParseError !== undefined) {
+      options.continueOnParseError = originalContinueOnParseError;
+    } else {
+      delete options.continueOnParseError;
+    }
   }
   if (attrChains) {
     const attrSorters = Object.create(null);
@@ -3791,14 +4084,14 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
     // Memoize sorted attribute orders—attribute sets often repeat in templates
     const attrOrderCache = new LRU(500);
 
-    options.sortAttributes = function (tag, attrs) {
+    options.sortAttributes = function (/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs) {
       const sorter = attrSorters[tag];
       if (sorter) {
         const names = attrNames(attrs);
 
         // Create order-independent cache key from tag and sorted attribute names
         const cacheKey = tag + ':' + names.slice().sort().join(',');
-        let sortedNames = attrOrderCache.get(cacheKey);
+        let sortedNames = /** @type {string[] | undefined} */ (attrOrderCache.get(cacheKey));
 
         if (sortedNames === undefined) {
           // Only sort if not in cache—need to clone names since sort mutates in place
@@ -3808,10 +4101,10 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
 
         // Apply the sorted order to `attrs`
         const attrMap = Object.create(null);
-        names.forEach(function (name, index) {
+        names.forEach(function (/** @type {string} */ name, /** @type {number} */ index) {
           (attrMap[name] || (attrMap[name] = [])).push(attrs[index]);
         });
-        sortedNames.forEach(function (name, index) {
+        /** @type {string[]} */ (sortedNames).forEach(function (/** @type {string} */ name, /** @type {number} */ index) {
           attrs[index] = attrMap[name].shift();
         });
       }
@@ -3822,14 +4115,14 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
     // Memoize `sortClassNames` results—class lists often repeat in templates
     const classNameCache = new LRU(500);
 
-    options.sortClassNames = function (value) {
+    options.sortClassNames = function (/** @type {string} */ value) {
       // Fast path: Single class (no spaces) needs no sorting
       if (value.indexOf(' ') === -1) {
         return value;
       }
 
       // Check cache first
-      const cached = classNameCache.get(value);
+      const cached = /** @type {string | undefined} */ (classNameCache.get(value));
       if (cached !== undefined) {
         return cached;
       }
@@ -3838,13 +4131,13 @@ async function createSortFns(value, options, uidIgnore, uidAttr, ignoredMarkupCh
       // Fast path: Skip if no HTML comments (UID markers) present
       let expandedValue = value;
       if (uidReplacePattern && value.indexOf('<!--') !== -1) {
-        expandedValue = value.replace(uidReplacePattern, function (match, index) {
+        expandedValue = value.replace(uidReplacePattern, function (/** @type {string} */ _match, /** @type {string} */ index) {
           return ignoredMarkupChunks[+index] || '';
         });
         // Reset `lastIndex` for pattern reuse
         uidReplacePattern.lastIndex = 0;
       }
-      const classes = expandedValue.split(whitespaceSplitPatternSort).filter(function(cls) {
+      const classes = expandedValue.split(whitespaceSplitPatternSort).filter(function(/** @type {string} */ cls) {
         return cls !== '';
       });
       const sorted = sorter.sort(classes);
@@ -3873,29 +4166,46 @@ async function minifyHTML(value, options, partialMarkup) {
     value = collapseWhitespace(value, options, true, true);
   }
 
+  const resolveName = /** @type {(name: string) => string} */ (options.name);
+  /** @type {HTMLAttribute[]} */
+  const emptyAttrs = [];
+
+  /** @type {string[]} */
   const buffer = [];
-  let charsPrevTag;
+  /** @type {string} */
+  let charsPrevTag = '';
   let currentChars = '';
-  let hasChars;
+  /** @type {boolean} */
+  let hasChars = false;
   let currentTag = '';
+  /** @type {Array<{name: string, value?: string, quote?: string, customAssign?: string, customOpen?: string, customClose?: string}>} */
   let currentAttrs = [];
+  /** @type {string[]} */
   const stackNoTrimWhitespace = [];
+  /** @type {string[]} */
   const stackNoCollapseWhitespace = [];
   let preTextareaDepth = 0; // Count of `pre`/`textarea` entries in `stackNoTrimWhitespace`
   let optionalStartTag = '';
   let optionalEndTag = '';
   let optionalEndTagEmitted = false;
+  /** @type {string[]} */
   const ignoredMarkupChunks = [];
+  /** @type {Array<RegExpExecArray | null>} */
   const ignoredCustomMarkupChunks = [];
+  /** @type {string | undefined} */
   let uidIgnore;
+  /** @type {RegExp | undefined} */
   let uidIgnorePlaceholderPattern;
+  /** @type {string | undefined} */
   let uidAttr;
+  /** @type {RegExp | undefined} */
   let uidPattern;
+  /** @type {RegExp | undefined} */
   let uidAttrLeadingPattern;
   // Create inline tags/text sets with custom elements
   const customElementsInput = options.inlineCustomElements ?? [];
   const customElementsArr = Array.isArray(customElementsInput) ? customElementsInput : Array.from(customElementsInput);
-  const normalizedCustomElements = customElementsArr.map(name => options.name(name));
+  const normalizedCustomElements = customElementsArr.map(name => resolveName(name));
   // Fast path: Reuse base sets if no custom elements
   const inlineTextSet = normalizedCustomElements.length
     ? new Set([...inlineElementsToKeepWhitespaceWithin, ...normalizedCustomElements])
@@ -3905,6 +4215,7 @@ async function minifyHTML(value, options, partialMarkup) {
     : inlineElementsToKeepWhitespaceAround;
 
   // Parse `removeEmptyElementsExcept` option
+  /** @type {Array<{tag: string, attrs: {[x: string]: string | undefined} | null}>} */
   let removeEmptyElementsExcept;
   if (options.removeEmptyElementsExcept && !Array.isArray(options.removeEmptyElementsExcept)) {
     if (options.log) {
@@ -3912,7 +4223,7 @@ async function minifyHTML(value, options, partialMarkup) {
     }
     removeEmptyElementsExcept = [];
   } else {
-    removeEmptyElementsExcept = parseRemoveEmptyElementsExcept(options.removeEmptyElementsExcept, options) || [];
+    removeEmptyElementsExcept = parseRemoveEmptyElementsExcept(options.removeEmptyElementsExcept || [], /** @type {any} */ (options)) || [];
   }
 
   // Temporarily replace ignored chunks with comments, so that there’s no need to worry what’s there;
@@ -3954,17 +4265,17 @@ async function minifyHTML(value, options, partialMarkup) {
   // This allows proper frequency analysis with access to ignored content via UID tokens
   if ((options.sortAttributes && typeof options.sortAttributes !== 'function') ||
       (options.sortClassNames && typeof options.sortClassNames !== 'function')) {
-    await createSortFns(value, options, uidIgnore, null, ignoredMarkupChunks);
+    await createSortFns(value, options, uidIgnore ?? '', uidAttr ?? '', ignoredMarkupChunks);
   }
 
-  const customFragments = options.ignoreCustomFragments.map(function (re) {
+  const customFragments = (options.ignoreCustomFragments || []).map(function (/** @type {RegExp} */ re) {
     return re.source;
   });
   if (customFragments.length) {
     // Warn about potential ReDoS if custom fragments use unlimited quantifiers
-    for (let i = 0; i < customFragments.length; i++) {
-      if (/[*+]/.test(customFragments[i])) {
-        options.log('Warning: Custom fragment contains unlimited quantifiers (“*” or “+”) which may cause ReDoS vulnerability');
+    for (const fragment of customFragments) {
+      if (/[*+]/.test(fragment)) {
+        options.log?.('Warning: Custom fragment contains unlimited quantifiers (“*” or “+”) which may cause ReDoS vulnerability');
         break;
       }
     }
@@ -3992,28 +4303,28 @@ async function minifyHTML(value, options, partialMarkup) {
           uidPattern = new RegExp('(\\s*)' + uidAttr + '([0-9]+)' + uidAttr + '(\\s*)', 'g');
           uidAttrLeadingPattern = new RegExp('^\\s*' + uidAttr + '(\\d+)' + uidAttr);
 
-          if (options.minifyCSS) {
-            options.minifyCSS = (function (fn) {
-              return function (text, type) {
-                text = text.replace(uidPattern, function (match, prefix, index) {
+          if (options.minifyCSS !== identity) {
+            /** @type {any} */ (options).minifyCSS = (function (/** @type {Function} */ fn) {
+              return function (/** @type {string} */ text, /** @type {string} */ type) {
+                text = text.replace(/** @type {RegExp} */ (uidPattern), function (/** @type {string} */ _match, /** @type {string} */ _prefix, /** @type {string} */ index) {
                   const chunks = ignoredCustomMarkupChunks[+index];
-                  return chunks[1] + uidAttr + index + uidAttr + chunks[2];
+                  return (chunks?.[1] ?? '') + uidAttr + index + uidAttr + (chunks?.[2] ?? '');
                 });
 
                 return fn(text, type);
               };
-            })(options.minifyCSS);
+            })(/** @type {Function} */ (options.minifyCSS));
           }
 
-          if (options.minifyJS) {
-            options.minifyJS = (function (fn) {
-              return function (text, inline, isModule) {
-                return fn(text.replace(uidPattern, function (match, prefix, index) {
+          if (options.minifyJS !== identity) {
+            options.minifyJS = (function (/** @type {Function} */ fn) {
+              return function (/** @type {string} */ text, /** @type {boolean} */ inline, /** @type {boolean} */ isModule) {
+                return fn(text.replace(/** @type {RegExp} */ (uidPattern), function (/** @type {string} */ _match, /** @type {string} */ _prefix, /** @type {string} */ index) {
                   const chunks = ignoredCustomMarkupChunks[+index];
-                  return chunks[1] + uidAttr + index + uidAttr + chunks[2];
+                  return (chunks?.[1] ?? '') + uidAttr + index + uidAttr + (chunks?.[2] ?? '');
                 }), inline, isModule);
               };
-            })(options.minifyJS);
+            })(/** @type {Function} */ (options.minifyJS));
           }
         }
 
@@ -4024,17 +4335,17 @@ async function minifyHTML(value, options, partialMarkup) {
     }
   }
 
-  function canCollapseWhitespace$1(tag, attrs) {
-    return options.canCollapseWhitespace(tag, attrs, canCollapseWhitespace);
+  function canCollapseWhitespace$1(/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs) {
+    return /** @type {Function} */ (options.canCollapseWhitespace)(tag, attrs, canCollapseWhitespace);
   }
 
-  function canTrimWhitespace$1(tag, attrs) {
-    return options.canTrimWhitespace(tag, attrs, canTrimWhitespace);
+  function canTrimWhitespace$1(/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs) {
+    return /** @type {Function} */ (options.canTrimWhitespace)(tag, attrs, canTrimWhitespace);
   }
 
   function removeStartTag() {
     let index = buffer.length - 1;
-    while (index > 0 && !RE_START_TAG.test(buffer[index])) {
+    while (index > 0 && !RE_START_TAG.test(buffer[index] ?? '')) {
       index--;
     }
     buffer.length = Math.max(0, index);
@@ -4042,20 +4353,20 @@ async function minifyHTML(value, options, partialMarkup) {
 
   function removeEndTag() {
     let index = buffer.length - 1;
-    while (index > 0 && !RE_END_TAG.test(buffer[index])) {
+    while (index > 0 && !RE_END_TAG.test(buffer[index] ?? '')) {
       index--;
     }
     buffer.length = Math.max(0, index);
   }
 
   // Look for trailing whitespaces, bypass any inline tags
-  function trimTrailingWhitespace(index, nextTag) {
-    for (let endTag = null; index >= 0 && canTrimWhitespace$1(endTag); index--) {
-      const str = buffer[index];
+  function trimTrailingWhitespace(/** @type {number} */ index, /** @type {string} */ nextTag) {
+    for (let endTag = ''; index >= 0 && canTrimWhitespace$1(endTag, emptyAttrs); index--) {
+      const str = buffer[index] ?? '';
       const match = str.match(/^<\/([\w:-]+)>$/);
       if (match) {
-        endTag = match[1];
-      } else if (/>$/.test(str) || (buffer[index] = collapseWhitespaceSmart(str, null, nextTag, [], [], options, inlineElements, inlineTextSet))) {
+        endTag = match[1] ?? '';
+      } else if (/>$/.test(str) || (buffer[index] = collapseWhitespaceSmart(str, '', nextTag, emptyAttrs, emptyAttrs, options, inlineElements, inlineTextSet))) {
         break;
       }
     }
@@ -4064,10 +4375,10 @@ async function minifyHTML(value, options, partialMarkup) {
   // Look for trailing whitespaces from previously processed text
   // which may not be trimmed due to a following comment or an empty
   // element which has now been removed
-  function squashTrailingWhitespace(nextTag) {
+  function squashTrailingWhitespace(/** @type {string} */ nextTag) {
     let charsIndex = buffer.length - 1;
     if (buffer.length > 1) {
-      const item = buffer[buffer.length - 1];
+      const item = buffer[buffer.length - 1] ?? '';
       if (/^(?:<!|$)/.test(item) && (!uidIgnore || item.indexOf(uidIgnore) === -1)) {
         charsIndex--;
       }
@@ -4076,6 +4387,7 @@ async function minifyHTML(value, options, partialMarkup) {
   }
 
   // SVG subtree capture: When SVGO is active, record buffer positions for post-processing
+  /** @type {Array<{start: number, end: number}>} */
   const svgBlocks = []; // Array of { start, end } buffer indices
   let svgBufferStartIndex = -1;
   let svgDepth = 0;
@@ -4088,7 +4400,7 @@ async function minifyHTML(value, options, partialMarkup) {
     // Compute `nextTag` only when whitespace collapse features require it
     wantsNextTag: !!(options.collapseWhitespace || options.collapseInlineTagWhitespace || options.conservativeCollapse),
 
-    start: async function (tag, attrs, unary, unarySlash, autoGenerated) {
+    start: async function (/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs, /** @type {boolean} */ unary, /** @type {string} */ unarySlash, /** @type {boolean} */ autoGenerated) {
       const lowerTag = tag.toLowerCase();
       if (lowerTag === 'svg' || lowerTag === 'math') {
         options = Object.create(options);
@@ -4110,21 +4422,21 @@ async function minifyHTML(value, options, partialMarkup) {
       // Note: The element itself is in SVG/MathML namespace, only its children are HTML
       let useParentNameForTag = false;
       if (options.insideForeignContent && (lowerTag === 'foreignobject' ||
-          (lowerTag === 'annotation-xml' && attrs.some(a => a.name.toLowerCase() === 'encoding' &&
-            RE_HTML_ENCODING.test(a.value))))) {
-        const parentName = options.name;
+          (lowerTag === 'annotation-xml' && attrs.some((/** @type {HTMLAttribute} */ a) => a.name.toLowerCase() === 'encoding' &&
+            RE_HTML_ENCODING.test(a.value ?? ''))))) {
+        const parentName = /** @type {(name: string) => string} */ (options.name);
         options = Object.create(options);
         options.caseSensitive = false;
         options.keepClosingSlash = false;
         options.parentName = parentName; // Preserve for the element tag itself
-        options.name = options.htmlName || lowercase;
+        options.name = /** @type {(name: string) => string} */ (options.htmlName ?? lowercase);
         options.insideForeignContent = false;
         // Note: `removeAttributeQuotes`, `removeTagWhitespace`, and `decodeEntities`
         // stay disabled (inherited from SVG context) because the entire SVG block
         // must be valid XML for SVGO processing
         useParentNameForTag = true;
       }
-      tag = (useParentNameForTag ? options.parentName : options.name)(tag);
+      tag = /** @type {(name: string) => string} */ (useParentNameForTag ? options.parentName : options.name)(tag);
       currentTag = tag;
       charsPrevTag = tag;
       if (!inlineTextSet.has(tag)) {
@@ -4190,10 +4502,10 @@ async function minifyHTML(value, options, partialMarkup) {
       // Remove duplicate attributes (per HTML spec, first occurrence wins)
       // Duplicate attributes result in invalid HTML
       // https://html.spec.whatwg.org/multipage/parsing.html#attribute-name-state
-      deduplicateAttributes(attrs, options.caseSensitive);
+      deduplicateAttributes(attrs, Boolean(options.caseSensitive));
 
       if (options.sortAttributes) {
-        options.sortAttributes(tag, attrs);
+        /** @type {Function} */ (options.sortAttributes)(tag, attrs);
       }
 
       const attrResults = attrs.map(attr => normalizeAttr(attr, attrs, tag, options, minifyHTML));
@@ -4223,7 +4535,7 @@ async function minifyHTML(value, options, partialMarkup) {
         currentTag = '';
       }
     },
-    end: function (tag, attrs, autoGenerated) {
+    end: function (/** @type {string} */ tag, /** @type {HTMLAttribute[]} */ attrs, /** @type {boolean} */ autoGenerated) {
       const lowerTag = tag.toLowerCase();
       // Restore parent context when exiting SVG/MathML or HTML-in-foreign-content elements
       if (lowerTag === 'svg' || lowerTag === 'math') {
@@ -4232,7 +4544,7 @@ async function minifyHTML(value, options, partialMarkup) {
                  !options.insideForeignContent && Object.getPrototypeOf(options).insideForeignContent) {
         options = Object.getPrototypeOf(options);
       }
-      tag = options.name(tag);
+      tag = /** @type {Function} */ (options.name)(tag);
 
       // Check if current tag is in a whitespace stack
       if (options.collapseWhitespace) {
@@ -4278,7 +4590,7 @@ async function minifyHTML(value, options, partialMarkup) {
         let preserve = false;
         if (removeEmptyElementsExcept.length) {
           // Normalize attribute names for comparison with specs
-          const normalizedAttrs = attrs.map(attr => ({ ...attr, name: options.name(attr.name) }));
+          const normalizedAttrs = attrs.map((/** @type {HTMLAttribute} */ attr) => ({ ...attr, name: resolveName(attr.name) }));
           preserve = shouldPreserveEmptyElement(tag, normalizedAttrs, removeEmptyElementsExcept);
         }
 
@@ -4325,7 +4637,7 @@ async function minifyHTML(value, options, partialMarkup) {
         }
       }
     },
-    chars: function (text, prevTag, nextTag, prevAttrs, nextAttrs) {
+    chars: function (/** @type {string} */ text, /** @type {string} */ prevTag, /** @type {string} */ nextTag, /** @type {HTMLAttribute[]} */ prevAttrs, /** @type {HTMLAttribute[]} */ nextAttrs) {
       prevTag = prevTag === '' ? 'comment' : prevTag;
       nextTag = nextTag === '' ? 'comment' : nextTag;
       prevAttrs = prevAttrs || [];
@@ -4341,7 +4653,7 @@ async function minifyHTML(value, options, partialMarkup) {
       const needsMinifyCSS = options.minifyCSS !== identity && isStyleElement(currentTag, currentAttrs);
 
       // Whitespace collapsing phase (sync); captures `prevTag`/`nextTag`/`prevAttrs`/`nextAttrs` from outer scope
-      function charsCollapse(text) {
+      function charsCollapse(/** @type {string} */ text) {
         // Trim outermost newline-based whitespace inside `pre`/`textarea` elements
         // This removes trailing newlines often added by template engines before closing tags
         // Only trims single trailing newlines (multiple newlines are likely intentional formatting)
@@ -4363,7 +4675,7 @@ async function minifyHTML(value, options, partialMarkup) {
             // to avoid side effects on the `inlineTextSet` branch below
             let effectivePrevTag = prevTag;
             if (prevTag === 'comment') {
-              const prevComment = buffer[buffer.length - 1];
+              const prevComment = buffer[buffer.length - 1] ?? '';
               if (!uidIgnore || prevComment.indexOf(uidIgnore) === -1) {
                 if (!prevComment) {
                   prevTag = charsPrevTag;
@@ -4371,7 +4683,7 @@ async function minifyHTML(value, options, partialMarkup) {
                 }
                 if (buffer.length > 1 && (!prevComment || (!options.conservativeCollapse && / $/.test(currentChars)))) {
                   const charsIndex = buffer.length - 2;
-                  buffer[charsIndex] = buffer[charsIndex].replace(/\s+$/, function (trailingSpaces) {
+                  buffer[charsIndex] = (buffer[charsIndex] ?? '').replace(/\s+$/, function (trailingSpaces) {
                     text = trailingSpaces + text;
                     return '';
                   });
@@ -4382,13 +4694,14 @@ async function minifyHTML(value, options, partialMarkup) {
                 // when `nextTag` is `comment` (another UID placeholder), `commentFinalize` handles it
                 const match = prevComment.match(uidIgnorePlaceholderPattern);
                 if (match) {
-                  const idx = +match[1];
+                  const idx = +(match[1] ?? '');
                   if (idx < ignoredMarkupChunks.length) {
                     const content = ignoredMarkupChunks[idx];
                     const lastTagMatch = content && RE_LAST_HTML_TAG.exec(content);
                     if (lastTagMatch) {
-                      const isClose = lastTagMatch[1].charAt(0) === '/';
-                      const tagName = options.name(isClose ? lastTagMatch[1].slice(1) : lastTagMatch[1]);
+                      const group = lastTagMatch[1] ?? '';
+                      const isClose = group.charAt(0) === '/';
+                      const tagName = resolveName(isClose ? group.slice(1) : group);
                       effectivePrevTag = isClose ? '/' + tagName : tagName;
                     }
                   }
@@ -4399,13 +4712,13 @@ async function minifyHTML(value, options, partialMarkup) {
               if (prevTag === '/nobr' || prevTag === 'wbr') {
                 if (/^\s/.test(text)) {
                   let tagIndex = buffer.length - 1;
-                  while (tagIndex > 0 && buffer[tagIndex].lastIndexOf('<' + prevTag) !== 0) {
+                  while (tagIndex > 0 && (buffer[tagIndex] ?? '').lastIndexOf('<' + prevTag) !== 0) {
                     tagIndex--;
                   }
                   trimTrailingWhitespace(tagIndex - 1, 'br');
                 }
               } else if (inlineTextSet.has(prevTag.charAt(0) === '/' ? prevTag.slice(1) : prevTag)) {
-                text = collapseWhitespace(text, options, /(?:^|\s)$/.test(currentChars));
+                text = collapseWhitespace(text, options, /(?:^|\s)$/.test(currentChars), false);
               }
             }
             if (prevTag || nextTag) {
@@ -4425,18 +4738,18 @@ async function minifyHTML(value, options, partialMarkup) {
       }
 
       // Finalization phase (sync): Optional tag handling, entity re-encoding, buffer push
-      function charsFinalize(text) {
+      function charsFinalize(/** @type {string} */ text) {
         if (options.removeOptionalTags && text) {
           // UID-attr tokens are padded with `\t`, which would falsely look like leading whitespace;
           // resolve single-token text to its actual content for the space/comment checks below
           let effectiveText = text;
-          if (uidAttrLeadingPattern && text.includes(uidAttr)) {
+          if (uidAttrLeadingPattern && uidAttr && text.includes(uidAttr)) {
             const uidMatch = uidAttrLeadingPattern.exec(text);
             if (uidMatch) {
-              const idx = +uidMatch[1];
+              const idx = +(uidMatch[1] ?? 0);
               const chunks = idx < ignoredCustomMarkupChunks.length ? ignoredCustomMarkupChunks[idx] : null;
               if (chunks != null) {
-                effectiveText = chunks[0];
+                effectiveText = chunks[0] ?? '';
               }
             }
           }
@@ -4472,8 +4785,8 @@ async function minifyHTML(value, options, partialMarkup) {
           }
         }
         if (uidPattern && options.collapseWhitespace && stackNoTrimWhitespace.length) {
-          text = text.replace(uidPattern, function (match, prefix, index) {
-            return ignoredCustomMarkupChunks[+index][0];
+          text = text.replace(/** @type {RegExp} */ (uidPattern), function (/** @type {string} */ match, /** @type {string} */ _prefix, /** @type {string} */ index) {
+            return ignoredCustomMarkupChunks[+index]?.[0] ?? match;
           });
         }
         currentChars += text;
@@ -4499,20 +4812,20 @@ async function minifyHTML(value, options, partialMarkup) {
           text = await processScript(text, options, currentAttrs, minifyHTML);
         }
         if (needsMinifyJS) {
-          text = await options.minifyJS(text, false, isModuleScript);
+          text = await /** @type {Function} */ (options.minifyJS)(text, false, isModuleScript);
         }
         if (needsMinifyCSS) {
-          text = await options.minifyCSS(text);
+          text = await /** @type {Function} */ (options.minifyCSS)(text);
         }
         charsFinalize(text);
       })();
     },
-    comment: function (text, nonStandard) {
+    comment: function (/** @type {string} */ text, /** @type {boolean} */ nonStandard) {
       const prefix = nonStandard ? '<!' : '<!--';
       const suffix = nonStandard ? '>' : '-->';
 
       // Finalization phase (sync): Optional tag handling, `htmlmin:ignore` whitespace collapsing, buffer push
-      function commentFinalize(comment) {
+      function commentFinalize(/** @type {string} */ comment) {
         if (options.removeOptionalTags && comment) {
           if (uidIgnorePlaceholderPattern) {
             const match = uidIgnorePlaceholderPattern.exec(comment);
@@ -4521,11 +4834,12 @@ async function minifyHTML(value, options, partialMarkup) {
               // if there’s a pending optional end tag and the ignored content isn’t itself
               // a comment (which per the HTML spec prevents omission), resolve it now,
               // before the UID is pushed to the buffer
-              const idx = +match[1];
+              const idx = +(match[1] ?? 0);
               const content = idx < ignoredMarkupChunks.length ? ignoredMarkupChunks[idx] : null;
               if (optionalEndTag && optionalEndTagEmitted && content != null && !/^\s*<!--/.test(content)) {
                 const firstTagMatch = content.match(/^\s*<([a-zA-Z][^\s/>]*)/);
-                const firstTag = firstTagMatch ? options.name(firstTagMatch[1]) : '';
+                const firstTagGroup = firstTagMatch?.[1] ?? '';
+                const firstTag = firstTagGroup ? resolveName(firstTagGroup) : '';
                 if (canRemovePrecedingTag(optionalEndTag, firstTag)) {
                   removeEndTag();
                 }
@@ -4553,8 +4867,8 @@ async function minifyHTML(value, options, partialMarkup) {
                 const prevMatch = prevComment.match(uidIgnorePlaceholderPattern);
 
                 if (currentMatch && prevMatch) {
-                  const currentIndex = +currentMatch[1];
-                  const prevIndex = +prevMatch[1];
+                  const currentIndex = +(currentMatch[1] ?? 0);
+                  const prevIndex = +(prevMatch[1] ?? 0);
 
                   // Defensive bounds check to ensure indices are valid
                   if (currentIndex < ignoredMarkupChunks.length && prevIndex < ignoredMarkupChunks.length) {
@@ -4577,13 +4891,13 @@ async function minifyHTML(value, options, partialMarkup) {
                       // Collapse if both sides are element/closing tags or HTML comments, and neither is inline
                       if ((currentTagMatch || currentIsHtmlComment || currentClosingTagMatch) &&
                           (prevTagMatch || prevIsHtmlComment || prevClosingTagMatch)) {
-                        const currentTag = currentTagMatch ? options.name(currentTagMatch[1])
-                          : currentClosingTagMatch ? options.name(currentClosingTagMatch[1]) : null;
-                        const prevTag = prevTagMatch ? options.name(prevTagMatch[1])
-                          : prevClosingTagMatch ? options.name(prevClosingTagMatch[1]) : null;
+                        const currentTag = currentTagMatch ? resolveName(currentTagMatch[1] ?? '')
+                          : currentClosingTagMatch ? resolveName(currentClosingTagMatch[1] ?? '') : null;
+                        const prevTag = prevTagMatch ? resolveName(prevTagMatch[1] ?? '')
+                          : prevClosingTagMatch ? resolveName(prevClosingTagMatch[1] ?? '') : null;
 
                         // Don’t collapse between inline elements (HTML comments count as non-inline)
-                        if (!inlineElements.has(currentTag) && !inlineElements.has(prevTag)) {
+                        if (!inlineElements.has(currentTag ?? '') && !inlineElements.has(prevTag ?? '')) {
                           // Collapse whitespace respecting context rules
                           let collapsedText = prevText;
 
@@ -4618,7 +4932,7 @@ async function minifyHTML(value, options, partialMarkup) {
       }
 
       if (options.removeComments) {
-        if (isIgnoredComment(text, options)) {
+        if (isIgnoredComment(text, /** @type {any} */ (options))) {
           text = prefix + text + suffix;
         } else {
           text = '';
@@ -4628,7 +4942,7 @@ async function minifyHTML(value, options, partialMarkup) {
       }
       commentFinalize(text);
     },
-    doctype: function (doctype) {
+    doctype: function (/** @type {string} */ doctype) {
       buffer.push(options.useShortDoctype
         ? '<!doctype' +
         (options.removeTagWhitespace ? '' : ' ') + 'html>'
@@ -4643,11 +4957,12 @@ async function minifyHTML(value, options, partialMarkup) {
   if (options.minifySVG && svgBlocks.length) {
     const optimized = await Promise.all(
       svgBlocks.map(({ start, end }) =>
-        options.minifySVG(buffer.slice(start, end).join(''))
+        /** @type {Function} */ (options.minifySVG)(buffer.slice(start, end).join(''))
       )
     );
     for (let i = svgBlocks.length - 1; i >= 0; i--) {
-      buffer.splice(svgBlocks[i].start, svgBlocks[i].end - svgBlocks[i].start, optimized[i]);
+      const block = svgBlocks[i];
+      if (block) buffer.splice(block.start, block.end - block.start, optimized[i] ?? '');
     }
   }
 
@@ -4667,9 +4982,9 @@ async function minifyHTML(value, options, partialMarkup) {
   }
 
   return joinResultSegments(buffer, options, uidPattern
-    ? function (str) {
-      return str.replace(uidPattern, function (match, prefix, index, suffix) {
-        let chunk = ignoredCustomMarkupChunks[+index][0];
+    ? function (/** @type {string} */ str) {
+      return str.replace(/** @type {RegExp} */ (uidPattern), function (/** @type {string} */ match, /** @type {string} */ prefix, /** @type {string} */ index, /** @type {string} */ suffix) {
+        let chunk = ignoredCustomMarkupChunks[+index]?.[0] ?? match;
         if (options.collapseWhitespace) {
           if (prefix !== '\t') {
             chunk = prefix + chunk;
@@ -4686,14 +5001,20 @@ async function minifyHTML(value, options, partialMarkup) {
       });
     }
     : identity, uidIgnore
-    ? function (str) {
-      return str.replace(new RegExp('<!--' + uidIgnore + '([0-9]+)-->', 'g'), function (match, index) {
-        return ignoredMarkupChunks[+index];
+    ? function (/** @type {string} */ str) {
+      return str.replace(new RegExp('<!--' + uidIgnore + '([0-9]+)-->', 'g'), function (/** @type {string} */ _match, /** @type {string} */ index) {
+        return ignoredMarkupChunks[+index] ?? '';
       });
     }
     : identity);
 }
 
+/**
+ * @param {string[]} results
+ * @param {MinifierOptions} options
+ * @param {Function} restoreCustom
+ * @param {Function} restoreIgnore
+ */
 function joinResultSegments(results, options, restoreCustom, restoreIgnore) {
   let str;
   const maxLineLength = options.maxLineLength;
@@ -4703,15 +5024,16 @@ function joinResultSegments(results, options, restoreCustom, restoreIgnore) {
     let line = ''; const lines = [];
     while (results.length) {
       const len = line.length;
-      const end = results[0].indexOf('\n');
-      const isClosingTag = Boolean(results[0].match(endTag));
+      const cur = results[0] ?? '';
+      const end = cur.indexOf('\n');
+      const isClosingTag = Boolean(cur.match(endTag));
       const shouldKeepSameLine = noNewlinesBeforeTagClose && isClosingTag;
 
       if (end < 0) {
-        line += restoreIgnore(restoreCustom(results.shift()));
+        line += restoreIgnore(restoreCustom(results.shift() ?? ''));
       } else {
-        line += restoreIgnore(restoreCustom(results[0].slice(0, end)));
-        results[0] = results[0].slice(end + 1);
+        line += restoreIgnore(restoreCustom(cur.slice(0, end)));
+        results[0] = cur.slice(end + 1);
       }
       if (len > 0 && line.length > maxLineLength && !shouldKeepSameLine) {
         lines.push(line.slice(0, len));
@@ -4741,13 +5063,14 @@ function joinResultSegments(results, options, restoreCustom, restoreIgnore) {
  * - The first call’s options determine the cache sizes for subsequent calls
  * - Invalid values (NaN, Infinity) fall back to the default size (500); values below `1` are clamped to `1`
  */
+/** @param {MinifierOptions} options */
 function initCaches(options) {
   // Only create caches once (on first call)—sizes are locked after this
   if (!cssMinifyCache) {
     const defaultSize = 500;
 
     // Helper to parse env var—returns parsed number (including 0) or undefined if absent, invalid, or negative
-    const parseEnvCacheSize = (envVar) => {
+    const parseEnvCacheSize = (/** @type {string | undefined} */ envVar) => {
       if (envVar === undefined) return undefined;
       const parsed = Number(envVar);
       if (Number.isNaN(parsed) || !Number.isFinite(parsed) || parsed < 0) {
@@ -4757,7 +5080,7 @@ function initCaches(options) {
     };
 
     // Sanitize a cache size: Non-finite/NaN falls back to `defaultSize`; otherwise clamped to min 1 and floored
-    const sanitizeSize = (size) => Number.isFinite(size) ? Math.max(1, Math.floor(size)) : defaultSize;
+    const sanitizeSize = (/** @type {number} */ size) => Number.isFinite(size) ? Math.max(1, Math.floor(size)) : defaultSize;
 
     // Get cache sizes with precedence: Options > env > default
     const cssSize = options.cacheCSS !== undefined ? options.cacheCSS
@@ -4795,7 +5118,9 @@ const minify = async function (value, options) {
     getTerser,
     getSwc,
     getSvgo,
-    ...caches
+    cssMinifyCache: caches.cssMinifyCache ?? undefined,
+    jsMinifyCache: caches.jsMinifyCache ?? undefined,
+    svgMinifyCache: caches.svgMinifyCache ?? undefined
   });
   let result = await minifyHTML(value, options);
 
@@ -4804,7 +5129,7 @@ const minify = async function (value, options) {
     result = mergeConsecutiveScripts(result);
   }
 
-  options.log('minified in: ' + (Date.now() - start) + 'ms');
+  /** @type {Function} */ (options.log)('minified in: ' + (Date.now() - start) + 'ms');
   return result;
 };