html-minifier-next 7.5.2 → 7.6.0

package/src/lib/options.js

@@ -3,6 +3,7 @@ import { LRU, MAX_CACHE_ENTRY_SIZE, stableStringify, hashContent, identity, lowe
 import { RE_TRAILING_SEMICOLON } from './constants.js';
 import { canCollapseWhitespace, canTrimWhitespace } from './whitespace.js';
 import { wrapCSS, unwrapCSS } from './content.js';
+import { findUnusedSymbols, normalizeUnusedCSSOptions } from './unused-css.js';
 import { getPreset, getPresetNames } from '../presets.js';
 import { optionDefinitions, optionDefaults } from './option-definitions.js';
 
@@ -10,6 +11,21 @@ import { optionDefinitions, optionDefaults } from './option-definitions.js';
 
 // Type definitions
 
+/**
+ * Per-document state handed to `minifyCSS`. Its closure hangs off the memoized
+ * options object that every `minify()` call with those options shares, so state
+ * belonging to one document has to be passed in rather than captured.
+ *
+ * @typedef {{usedSymbols?: Set<string>, warned: Set<string>}} CSSContext
+ */
+
+/**
+ * Minified style sheet plus the warnings its transform produced, cached together
+ * so that a cache hit can report what the transform reported
+ *
+ * @typedef {{css: string, warnings: string[]}} CSSResult
+ */
+
 /**
  * Options object produced by `processOptions` and consumed by `minifyHTML` and
  * the `lib/` helpers; normalization guarantees that the function-valued options
@@ -17,16 +33,18 @@ import { optionDefinitions, optionDefaults } from './option-definitions.js';
  * minification adds writable internal state on top of the public options
  * (set on prototype-chain forks during SVG/MathML namespace transitions)
  *
- * @typedef {Omit<MinifierOptions, 'preset' | 'canCollapseWhitespace' | 'canTrimWhitespace' | 'ignoreCustomComments' | 'log' | 'minifyCSS' | 'minifyJS' | 'minifyURLs' | 'minifySVG'> & {
+ * @typedef {Omit<MinifierOptions, 'preset' | 'canCollapseWhitespace' | 'canTrimWhitespace' | 'ignoreCustomComments' | 'log' | 'minifyCSS' | 'minifyJS' | 'minifyURLs' | 'minifySVG' | 'removeUnusedCSS'> & {
  *   name: (name: string) => string,
  *   log: (message: any) => unknown,
  *   ignoreCustomComments: RegExp[],
  *   canCollapseWhitespace: (tag: string, attrs: HTMLAttribute[], defaultFn: (tag: string) => boolean) => boolean,
  *   canTrimWhitespace: (tag: string, attrs: HTMLAttribute[], defaultFn: (tag: string) => boolean) => boolean,
- *   minifyCSS: (text: string, type?: string) => string | Promise<string>,
+ *   minifyCSS: (text: string, type?: string, context?: CSSContext) => string | Promise<string>,
  *   minifyJS: (text: string, inline?: boolean, isModule?: boolean) => string | Promise<string>,
  *   minifyURLs: (text: string) => string | Promise<string>,
  *   minifySVG: ((svgContent: string) => string | Promise<string>) | null,
+ *   removeUnusedCSS: {safelist: Array<string | RegExp>, scripts: boolean} | null,
+ *   cssContext?: CSSContext,
  *   nameParent?: (name: string) => string,
  *   nameHTML?: (name: string) => string,
  *   insideSVG?: boolean,
@@ -82,6 +100,9 @@ const presetNamesWarned = new Set();
 // The custom-fragment ReDoS warning is security-relevant, so it reaches the
 // console even without a `log` hook—once per process, like the warnings above
 let customFragmentQuantifierWarned = false;
+const unusedCSSWarned = new Set();
+// Object-valued options handed a string, warned about once per distinct value
+const stringValuesWarned = new Set();
 
 // Main options processor
 
@@ -101,7 +122,8 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
     minifyCSS: identity,
     minifyJS: identity,
     minifyURLs: identity,
-    minifySVG: null
+    minifySVG: null,
+    removeUnusedCSS: null
   };
 
   const parseRegExpArray = (/** @type {unknown} */ arr) => {
@@ -136,7 +158,7 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
   Object.keys(inputOptions).forEach(function (key) {
     if (!Object.hasOwn(optionDefinitions, key) && !optionKeysExtra.has(key) && !optionKeysWarned.has(key)) {
       optionKeysWarned.add(key);
-      warn(`HTML Minifier Next: Ignoring unknown or deprecated option “${key}” (see README for available options)`);
+      warn(`HTML Minifier Next: Ignoring unknown or deprecated option \`${key}\` (see README for available options)`);
     }
   });
 
@@ -166,10 +188,30 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
       return;
     }
 
+    // A string carries no configuration for these options. The CLI parses config
+    // values as JSON first, so only a value that is not JSON reaches this from
+    // there. (`minifyURLs` is deliberately excluded—there, a string names the site.)
+    const definition = /** @type {Record<string, {type?: string}>} */ (optionDefinitions)[key];
+    if (typeof option === 'string' && definition?.type === 'jsonObject') {
+      const message = `HTML Minifier Next: Ignoring \`${key}\`—it takes a boolean or an object, not a string (“${option}”)`;
+      if (!stringValuesWarned.has(message)) {
+        stringValuesWarned.add(message);
+        warn(message);
+      }
+      return;
+    }
+
     if (key === 'caseSensitive') {
       if (option) {
         options.name = identity;
       }
+    } else if (key === 'removeUnusedCSS') {
+      optionsDynamic.removeUnusedCSS = normalizeUnusedCSSOptions(option, message => {
+        if (!unusedCSSWarned.has(message)) {
+          unusedCSSWarned.add(message);
+          warn(`HTML Minifier Next: ${message}`);
+        }
+      });
     } else if (key === 'log') {
       if (typeof option === 'function') {
         options.log = option;
@@ -184,12 +226,34 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
       const cssLoader = getLightningCSS;
       const cssCache = cssMinifyCache;
 
-      options.minifyCSS = async function (/** @type {string} */ text, /** @type {string | undefined} */ type) {
+      options.minifyCSS = async function (/** @type {string} */ text, /** @type {string | undefined} */ type, /** @type {CSSContext | undefined} */ context) {
         // Fast path: Nothing to minify
         if (!text || !text.trim()) {
           return text;
         }
 
+        // Warnings are stored with the minified result and replayed on every hit, so a
+        // second document with the same defect hears about it, too; `context.warned`
+        // then keeps one document from repeating itself. Reporting from the cache
+        // rather than only from the transform keeps the output independent of cache
+        // size and eviction. They are built and cached even when `log` is the default
+        // no-op, so a later document that does pass a `log` hook still gets them.
+        const report = (/** @type {string[]} */ messages) => {
+          if (!messages.length || options.log === identity) {
+            return;
+          }
+          const warned = context?.warned;
+          for (const message of messages) {
+            if (warned) {
+              if (warned.has(message)) {
+                continue;
+              }
+              warned.add(message);
+            }
+            options.log(message);
+          }
+        };
+
         // Optimization: Only process URLs if minification is enabled (not identity function)
         // This avoids expensive `replaceAsync` when URL minification is disabled
         if (options.minifyURLs !== identity) {
@@ -213,9 +277,22 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
           );
         }
 
-        // Cache key: Content + type + options signature; large inputs are hashed to avoid huge Map keys
+        // Unused-symbol removal applies to style sheets only
+        const unusedCSSConfig = type === undefined ? options.removeUnusedCSS : undefined;
+        const unusedSymbols = (unusedCSSConfig && context?.usedSymbols)
+          ? findUnusedSymbols(text, context.usedSymbols, unusedCSSConfig.safelist)
+          : undefined;
+
+        // Cache key: Content + type + options signature; large inputs are hashed to avoid huge Map keys.
+        // The symbol list belongs in the signature: The cache outlives a single `minify()` call, so
+        // identical style sheets in differently marked-up documents must not share an entry.
         const inputCSS = wrapCSS(text, type);
-        const cssSig = stableStringify({ type, opts: lightningCssOptions, cont: !!options.continueOnMinifyError });
+        const cssSig = stableStringify({
+          type,
+          opts: lightningCssOptions,
+          cont: !!options.continueOnMinifyError,
+          unused: unusedSymbols && unusedSymbols.length ? unusedSymbols.slice().sort() : undefined
+        });
         const isCacheable = inputCSS.length <= MAX_CACHE_ENTRY_SIZE;
         const cssKey = isCacheable
           ? (inputCSS.length > 2048
@@ -225,10 +302,12 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
 
         try {
           if (cssKey !== undefined) {
-            const cached = /** @type {string | Promise<string> | undefined} */ (cssCache.get(cssKey));
+            const cached = /** @type {CSSResult | Promise<CSSResult> | undefined} */ (cssCache.get(cssKey));
             if (cached !== undefined) {
               // Support both resolved values and in-flight promises
-              return await cached;
+              const settled = await cached;
+              report(settled.warnings);
+              return settled.css;
             }
           }
 
@@ -242,9 +321,26 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
               code: Buffer.from(inputCSS),
               minify: true,
               errorRecovery: !!options.continueOnMinifyError,
-              ...lightningCssOptions
+              ...lightningCssOptions,
+              // Union, so that a manually supplied `unusedSymbols` list survives
+              ...(unusedSymbols && unusedSymbols.length
+                ? { unusedSymbols: lightningCssOptions.unusedSymbols ? [...new Set([...lightningCssOptions.unusedSymbols, ...unusedSymbols])] : unusedSymbols }
+                : {})
             });
 
+            // With `errorRecovery` enabled, Lightning CSS reports what it takes issue
+            // with instead of throwing—dropping the rule in some cases (`@property`
+            // with a bad `syntax`) and passing it through in others (an unknown
+            // at-rule), which is why the wording stops at “reported”
+            /** @type {string[]} */
+            const warnings = [];
+            if (result.warnings) {
+              for (const warning of result.warnings) {
+                const at = warning.loc ? ` (line ${warning.loc.line}, column ${warning.loc.column})` : '';
+                warnings.push(`Warning: Lightning CSS reported invalid CSS${at}: ${warning.message}`);
+              }
+            }
+
             const outputCSS = unwrapCSS(result.code.toString(), type);
 
             // If Lightning CSS removed significant content that looks like template syntax or UIDs, return original
@@ -259,13 +355,15 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
 
             // Preserve if output is empty and input had template syntax or UIDs
             // This catches cases where Lightning CSS removed content that should be preserved
-            return (text.trim() && !outputCSS.trim() && (looksLikeTemplate || hasUID)) ? text : outputCSS;
+            const css = (text.trim() && !outputCSS.trim() && (looksLikeTemplate || hasUID)) ? text : outputCSS;
+            return { css, warnings };
           })();
 
           if (cssKey !== undefined) cssCache.set(cssKey, inFlight);
           const resolved = await inFlight;
           if (cssKey !== undefined) cssCache.set(cssKey, resolved);
-          return resolved;
+          report(resolved.warnings);
+          return resolved.css;
         } catch (err) {
           if (cssKey !== undefined) cssCache.delete(cssKey);
           if (!options.continueOnMinifyError) {
@@ -515,6 +613,23 @@ const processOptions = (inputOptions, { getLightningCSS, getTerser, getSwc, getS
       optionsDynamic[key] = option;
     }
   });
+
+  // Unused-CSS removal rides along with Lightning CSS, so it silently does nothing
+  // when `minifyCSS` is off or replaced by a function—say so rather than let it pass
+  if (options.removeUnusedCSS) {
+    const cssOption = /** @type {Record<string, any>} */ (effectiveInput).minifyCSS;
+    const reason = typeof cssOption === 'function'
+      ? 'it does not apply when `minifyCSS` is a function'
+      : (options.minifyCSS === identity ? 'it requires `minifyCSS` (`--minify-css`)' : '');
+    if (reason) {
+      if (!unusedCSSWarned.has(reason)) {
+        unusedCSSWarned.add(reason);
+        warn(`HTML Minifier Next: Ignoring \`removeUnusedCSS\`—${reason}`);
+      }
+      options.removeUnusedCSS = null;
+    }
+  }
+
   return options;
 };
 

package/src/lib/unused-css.js

@@ -0,0 +1,394 @@
+// Unused-CSS removal
+
+import { findTagEnd } from './utils.js';
+
+// Attributes whose values name elements by ID or hold space-separated ID lists
+const idReferenceAttributes = new Set([
+  'aria-activedescendant',
+  'aria-controls',
+  'aria-describedby',
+  'aria-details',
+  'aria-errormessage',
+  'aria-flowto',
+  'aria-labelledby',
+  'aria-owns',
+  'commandfor',
+  'contextmenu',
+  'for',
+  'form',
+  'headers',
+  'itemref',
+  'list',
+  'popovertarget'
+]);
+
+// Attributes whose value may be a same-document fragment URL (`#main`). `:target`
+// rules and SVG sprite references (`<use href="#icon">`) rest on these, so the ID
+// they name counts as used.
+const fragmentReferenceAttributes = new Set([
+  'action',
+  'cite',
+  'data',
+  'formaction',
+  'href',
+  'poster',
+  'src',
+  'usemap',
+  'xlink:href'
+]);
+
+// `srcdoc` can nest, and each level costs another scan of its own markup
+const SRCDOC_MAX_DEPTH = 3;
+
+const attributePattern = /(?:^|[\s/])([-\w:.]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+const identifierPattern = /--[\w-]*|-?[A-Za-z_][\w-]*/g;
+// SVG paints and filters reach elements by ID through `url(#gradient)`, in
+// presentation attributes as well as in `style`
+const fragmentURLPattern = /url\(\s*['"]?#([^)'"\s]+)/gi;
+// Class names routinely carry characters that end a CSS identifier (`md:flex`,
+// `w-1/2`, `p-[3px]`), so scripts and `data-*` values contribute whole tokens
+// besides identifiers; quoted strings are where scripts keep such names
+const stringLiteralPattern = /'((?:[^'\\\n]|\\.)*)'|"((?:[^"\\\n]|\\.)*)"|`((?:[^`\\]|\\.)*)`/g;
+
+// CSS identifiers may contain escapes (`.md\:flex`, `.w-1\/2`), which have to be
+// resolved before comparing them against the plain tokens found in the markup
+const cssIdentifierPattern = /(?<![\w\\-])[.#]((?:[-_a-zA-Z]|\\[0-9a-fA-F]{1,6}[ \t\n]?|\\[^\n0-9a-fA-F])(?:[-\w]|\\[0-9a-fA-F]{1,6}[ \t\n]?|\\[^\n0-9a-fA-F])*)/g;
+// `unusedSymbols` also drops `@keyframes` and `@counter-style` rules by name, so any
+// name used there is off limits even when no element carries it as a class or ID
+const reservedAtRulePattern = /@(?:-\w+-)?(?:keyframes|counter-style)\s+(-?[_a-zA-Z][\w-]*)/gi;
+const escapePattern = /\\(?:([0-9a-fA-F]{1,6})[ \t\n]?|(.))/g;
+
+/**
+ * Resolve CSS escape sequences in an identifier.
+ * @param {string} identifier
+ * @returns {string}
+ */
+function unescapeIdentifier(identifier) {
+  if (identifier.indexOf('\\') === -1) {
+    return identifier;
+  }
+  return identifier.replace(escapePattern, (_match, hex, literal) => {
+    if (!hex) {
+      return literal;
+    }
+    // Per CSS Syntax spec, a null, surrogate, or out-of-range escape becomes U+FFFD
+    const code = parseInt(hex, 16);
+    return (code === 0 || code > 0x10FFFF || (code >= 0xD800 && code <= 0xDFFF))
+      ? '\uFFFD'
+      : String.fromCodePoint(code);
+  });
+}
+
+/**
+ * Lowercase for matching without disturbing offsets.
+ *
+ * `toLowerCase()` can change a string's length—U+0130 becomes two code units—which
+ * would misalign every offset taken from the result. Folding just ASCII preserves
+ * length, and tag names are ASCII anyway.
+ *
+ * @param {string} text
+ * @returns {string} Same length as `text`
+ */
+function foldCase(text) {
+  const lowercased = text.toLowerCase();
+  return lowercased.length === text.length
+    ? lowercased
+    : text.replace(/[A-Z]+/g, uppercase => uppercase.toLowerCase());
+}
+
+/**
+ * Locate the bodies of a raw-text element (`style`, `script`).
+ *
+ * Scanning beats one regular expression here: A pattern permissive enough for the
+ * end tags browsers accept (`</script\t\n bar>`, `</script/>`) backtracks
+ * quadratically over a document full of near-matches, and bounding it would make
+ * long start tags go unrecognized.
+ *
+ * @param {string} haystack - Case-folded markup, as returned by `foldCase`
+ * @param {string} tagName - Lowercase element name
+ * @returns {Array<{start: number, bodyStart: number, bodyEnd: number, end: number, closed: boolean}>}
+ */
+function findRawTextElements(haystack, tagName) {
+  /** @type {Array<{start: number, bodyStart: number, bodyEnd: number, end: number, closed: boolean}>} */
+  const found = [];
+  const openTag = '<' + tagName;
+  const closeTag = '</' + tagName;
+  // A tag name ends at whitespace, a slash, or the closing bracket—so `<styles>`
+  // and `</scriptfoo>` name different elements and must not match
+  const endsName = (/** @type {string} */ character) =>
+    character === '' || character === '/' || character === '>' || /\s/.test(character);
+
+  let cursor = 0;
+  for (;;) {
+    const start = haystack.indexOf(openTag, cursor);
+    if (start === -1) {
+      break;
+    }
+    if (!endsName(haystack.charAt(start + openTag.length))) {
+      cursor = start + openTag.length;
+      continue;
+    }
+    // A quoted attribute value may hold a `>`, so the tag ends where the parser
+    // says it does, not at the next bracket
+    const startTagEnd = findTagEnd(haystack, start + openTag.length);
+    if (startTagEnd === -1) {
+      break;
+    }
+
+    const bodyStart = startTagEnd + 1;
+    let search = bodyStart;
+    let bodyEnd = -1;
+    let end = -1;
+    for (;;) {
+      const candidate = haystack.indexOf(closeTag, search);
+      if (candidate === -1) {
+        break;
+      }
+      if (endsName(haystack.charAt(candidate + closeTag.length))) {
+        const closeEnd = findTagEnd(haystack, candidate + closeTag.length);
+        if (closeEnd !== -1) {
+          bodyEnd = candidate;
+          end = closeEnd + 1;
+        }
+        break;
+      }
+      search = candidate + closeTag.length;
+    }
+
+    const closed = bodyEnd !== -1;
+    found.push({
+      start,
+      bodyStart,
+      bodyEnd: closed ? bodyEnd : haystack.length,
+      end: closed ? end : haystack.length,
+      closed
+    });
+    cursor = closed ? end : haystack.length;
+  }
+
+  return found;
+}
+
+/**
+ * Collect the class names and IDs a document references.
+ *
+ * Style sheet contents are excluded, so that a style sheet never counts as
+ * evidence for its own selectors. Over-collecting is safe here (a symbol wrongly
+ * considered used is merely kept), under-collecting is not.
+ *
+ * @param {string} html - Raw document markup
+ * @param {boolean} includeScripts - Also treat identifiers inside inline `script` elements as used
+ * @param {((text: string) => string)} [decode] - Resolves character references in attribute values
+ * @param {number} [depth] - Nesting level, counted through `srcdoc`
+ * @returns {Set<string>} Symbols to keep
+ */
+function collectUsedSymbols(html, includeScripts, decode, depth = 0) {
+  const used = new Set();
+  const haystack = foldCase(html);
+
+  // Style sheets are skipped rather than cut out, so both scans share one folded
+  // copy and offsets keep pointing into `html`. Only the body is skipped—the start
+  // tag carries ordinary attributes, and `<style id="theme">` could be what
+  // `#theme` refers to. An unclosed element is not skipped: Reading its contents
+  // as markup can only add symbols, whereas ignoring the rest of the document
+  // would lose them.
+  const skipped = findRawTextElements(haystack, 'style')
+    .filter(element => element.closed)
+    .map(element => ({ start: element.bodyStart, end: element.bodyEnd }));
+
+  const addIdentifiers = (/** @type {string} */ text) => {
+    identifierPattern.lastIndex = 0;
+    let identifier;
+    while ((identifier = identifierPattern.exec(text))) {
+      used.add(identifier[0]);
+    }
+  };
+
+  const addTokens = (/** @type {string} */ text) => {
+    for (const token of text.split(/\s+/)) {
+      if (token) {
+        used.add(token);
+      }
+    }
+  };
+
+  // Both loops below walk forward, so one cursor over the skipped ranges suffices
+  let skipCursor = 0;
+  const isSkipped = (/** @type {number} */ index) => {
+    while (skipCursor < skipped.length && (skipped[skipCursor]?.end ?? 0) <= index) {
+      skipCursor++;
+    }
+    const element = skipped[skipCursor];
+    return element !== undefined && index >= element.start;
+  };
+
+  /** @type {string[]} */
+  const nested = [];
+
+  attributePattern.lastIndex = 0;
+  let match;
+  while ((match = attributePattern.exec(html))) {
+    const raw = match[2] ?? match[3] ?? match[4] ?? '';
+    if (!raw || isSkipped(match.index)) {
+      continue;
+    }
+    const name = (match[1] ?? '').toLowerCase();
+    // `class="us&#101;d"` names the class `used`, so compare against the decoded value
+    const value = (decode && raw.indexOf('&') !== -1) ? decode(raw) : raw;
+    if (name === 'class' || name === 'id' || idReferenceAttributes.has(name)) {
+      addTokens(value);
+    } else if (name.startsWith('data-')) {
+      // Class names are commonly parked in `data-*` attributes for scripts to apply later
+      addIdentifiers(value);
+      addTokens(value);
+    } else if (fragmentReferenceAttributes.has(name) && value.charAt(0) === '#') {
+      // Only a leading `#`: `href="/page#sec"` names a section of another document
+      addTokens(value.slice(1));
+    } else if (name === 'srcdoc' && depth < SRCDOC_MAX_DEPTH) {
+      nested.push(value);
+    }
+    if (value.indexOf('(') !== -1) {
+      fragmentURLPattern.lastIndex = 0;
+      let reference;
+      while ((reference = fragmentURLPattern.exec(value))) {
+        addTokens(reference[1] ?? '');
+      }
+    }
+  }
+
+  // `iframe srcdoc` holds a document of its own, whose style sheets are minified
+  // against this very set—so what it references has to be in it. The scan runs here
+  // rather than at the attribute: The patterns it shares with this one are
+  // module-level, so no nested scan may start while one of their loops is open.
+  for (const markup of nested) {
+    for (const symbol of collectUsedSymbols(markup, includeScripts, decode, depth + 1)) {
+      used.add(symbol);
+    }
+  }
+
+  if (includeScripts) {
+    // Script contents are raw text, so character references stay literal;
+    // an unclosed `script` runs to the end of the document, as it does in a browser
+    skipCursor = 0;
+    for (const element of findRawTextElements(haystack, 'script')) {
+      if (isSkipped(element.start)) {
+        continue;
+      }
+      const body = html.slice(element.bodyStart, element.bodyEnd);
+      addIdentifiers(body);
+      stringLiteralPattern.lastIndex = 0;
+      let literal;
+      while ((literal = stringLiteralPattern.exec(body))) {
+        addTokens(literal[1] ?? literal[2] ?? literal[3] ?? '');
+      }
+    }
+  }
+
+  return used;
+}
+
+/**
+ * Determine which class/ID symbols a style sheet defines but the document never references.
+ * @param {string} css - Style sheet contents
+ * @param {Set<string>} used - Symbols the document references
+ * @param {Array<string | RegExp>} safelist - Symbols to keep regardless
+ * @returns {string[]} Symbols safe to remove
+ */
+function findUnusedSymbols(css, used, safelist) {
+  const reserved = new Set();
+  reservedAtRulePattern.lastIndex = 0;
+  let match;
+  while ((match = reservedAtRulePattern.exec(css))) {
+    if (match[1]) {
+      reserved.add(match[1]);
+    }
+  }
+
+  const unused = [];
+  const seen = new Set();
+  cssIdentifierPattern.lastIndex = 0;
+  while ((match = cssIdentifierPattern.exec(css))) {
+    const symbol = unescapeIdentifier(match[1] ?? '');
+    if (seen.has(symbol)) {
+      continue;
+    }
+    seen.add(symbol);
+    if (used.has(symbol) || reserved.has(symbol)) {
+      continue;
+    }
+    if (safelist.some(entry => {
+      if (!(entry instanceof RegExp)) {
+        return entry === symbol;
+      }
+      // `test()` advances `lastIndex` on global and sticky patterns, which would
+      // make a safelist entry match only every other symbol
+      entry.lastIndex = 0;
+      return entry.test(symbol);
+    })) {
+      continue;
+    }
+    unused.push(symbol);
+  }
+
+  return unused;
+}
+
+const unusedCSSKeys = new Set(['safelist', 'scripts']);
+
+/**
+ * Normalize the `removeUnusedCSS` option into a settled configuration.
+ *
+ * A misspelled key or a safelist that is not an array would otherwise protect
+ * nothing, and that only surfaces as a missing rule much later—so every value
+ * that gets dropped is reported.
+ *
+ * @param {boolean | {safelist?: Array<string | RegExp>, scripts?: boolean} | undefined} option
+ * @param {(message: string) => unknown} [warn] - Receives one message per ignored value
+ * @returns {{safelist: Array<string | RegExp>, scripts: boolean} | null} Null when disabled
+ */
+function normalizeUnusedCSSOptions(option, warn) {
+  if (!option) {
+    return null;
+  }
+  const report = warn ?? (() => {});
+  const config = /** @type {Record<string, any>} */ (typeof option === 'object' ? option : {});
+
+  for (const key of Object.keys(config)) {
+    if (!unusedCSSKeys.has(key)) {
+      report(`Ignoring unknown \`removeUnusedCSS\` key \`${key}\`—expected \`safelist\` or \`scripts\``);
+    }
+  }
+
+  /** @type {Array<string | RegExp>} */
+  let safelist = [];
+  if (config.safelist !== undefined) {
+    if (!Array.isArray(config.safelist)) {
+      report('Ignoring `removeUnusedCSS.safelist`—it takes an array of strings and regular expressions');
+    } else {
+      safelist = config.safelist.filter((/** @type {unknown} */ entry) => {
+        if (typeof entry === 'string' || entry instanceof RegExp) {
+          return true;
+        }
+        report(`Ignoring \`removeUnusedCSS.safelist\` entry of type ${typeof entry}—entries must be strings or regular expressions`);
+        return false;
+      });
+    }
+  }
+
+  if (config.scripts !== undefined && typeof config.scripts !== 'boolean') {
+    report('Ignoring `removeUnusedCSS.scripts`—it takes a boolean');
+  }
+
+  return {
+    safelist,
+    // Keeping identifiers seen in inline scripts costs a little of the reduction
+    // but avoids the most common breakage, so it is the default
+    scripts: typeof config.scripts === 'boolean' ? config.scripts : true
+  };
+}
+
+export {
+  collectUsedSymbols,
+  findUnusedSymbols,
+  normalizeUnusedCSSOptions
+};

package/src/lib/urls.js

@@ -12,7 +12,7 @@ const REJECTED_SCHEMES = new Set(['data:', 'javascript:', 'mailto:']);
 const DIRECTORY_INDEXES = ['index.html', 'index.htm'];
 
 /**
- * Get the directory portion of a pathname (up to and including the last `/`)
+ * Get the directory portion of a pathname (up to and including the last `/`).
  * @param {string} pathname
  * @returns {string}
  */
@@ -22,7 +22,7 @@ function getDirectory(pathname) {
 }
 
 /**
- * Compute a path-relative URL from a base directory to a target path
+ * Compute a path-relative URL from a base directory to a target path.
  * @param {string} baseDir - Base directory path (must end with `/`)
  * @param {string} targetPath - Target pathname
  * @returns {string}
@@ -63,7 +63,7 @@ function relativize(baseDir, targetPath) {
 }
 
 /**
- * Remove directory index from the end of a pathname
+ * Remove directory index from the end of a pathname.
  * @param {string} pathname
  * @returns {string}
  */
@@ -77,7 +77,7 @@ function removeDirectoryIndex(pathname) {
 }
 
 /**
- * Create a URL minifier function for the given site context
+ * Create a URL minifier function for the given site context.
  * @param {string} site - The site base URL (used to compute relative URLs)
  * @returns {(url: string) => string} Minifier function that returns the shortest URL
  */