html-minifier-setup 0.0.0-stage → 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Jens Oliver Meiert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# HTML Minifier Setup (Preview)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/html-minifier-setup.svg)](https://www.npmjs.com/package/html-minifier-setup) [![Build status](https://github.com/j9t/html-minifier-setup/workflows/Tests/badge.svg)](https://github.com/j9t/html-minifier-setup/actions) [![Socket](https://badge.socket.dev/npm/package/html-minifier-setup)](https://socket.dev/npm/package/html-minifier-setup) [![GitHub Sponsors](https://badgen.net/static/Support/Open%20Source/cyan)](https://github.com/sponsors/j9t)
+
+HTML Minifier Setup (HMS) helps you select the [HTML Minifier](https://www.npmjs.com/package/html-minifier) configuration that saves the most on your pages without changing how they render. It evaluates every option on a sample of your pages, sets aside those that don’t fit—i.e., that would change something your pages rely on—as well as those that save nothing, and provides a custom configuration for HTML Minifier.
+
+It also reports what each option saves, which is useful on its own: Which options pay off on your site, and which don’t?
+
+ℹ️ **This is an early release. Options, output, and API may change before 1.0.0. Feedback is welcome.**
+
+## Usage
+
+```shell
+npx html-minifier-setup [inputs...] [options]
+```
+
+(Like HTML Minifier, HTML Minifier Setup requires Node.js ≥22.13.)
+
+Inputs are HTML files, directories, or URLs (default: the current directory). From directories, up to 20 pages (`--sample`) are picked, spread across subdirectories to cover a site’s templates.
+
+The render check, which catches most of what static checks can’t, uses Playwright’s Chromium, or else Chrome or Edge, if installed. Where none is found, HTML Minifier Setup offers to download Chromium.
+
+Local pages are served to the browser from their folder. Symbolic links that lead outside it are followed only if you agree (or pass `--follow-links`), as a page’s scripts could send on what they lead to. Where nobody can answer, they aren’t followed.
+
+On a terminal, HTML Minifier Setup then offers to save the recommended configuration (as html-minifier.config.json, in the project of the pages evaluated or a folder of your choice) and, where it isn’t installed yet, to install HTML Minifier there (with the package manager the project uses), or to update it where a newer version is out. All offers default to no. Where one of HTML Minifier’s presets with a few changes has the same effect, it also offers to save the configuration that way—shorter, and following changes to the preset.
+
+```shell
+# Evaluate a build directory and write the configuration to html-minifier.config.json
+npx html-minifier-setup ./dist -o
+
+# Use it with HTML Minifier, which picks up html-minifier.config.json from the working directory
+npx html-minifier --input-dir ./dist --output-dir ./dist
+```
+
+| Option | Description |
+| --- | --- |
+| `-c, --config-file <file>` | Start from an HTML Minifier configuration (JSON or module; defaults to html-minifier.config.json in the working directory, if present): Options on how input is read (e.g., `ignoreCustomFragments`, `caseSensitive`, `continueOnParseError`) are carried over; values for candidates (e.g., `minifyJS: {"engine": "swc"}`) are evaluated instead of `true`; and `fileExt`, `ignoreDir`, and cache sizes are kept, with `fileExt` and `ignoreDir` also applying to directories read |
+| `-o, --output [file]` | Write the configuration to a file (default: html-minifier.config.json) rather than print it |
+| `-m, --metric <metric>` | Size that decides whether an option gains: `raw`, `gzip` (default), or `brotli`, compressed at Gzip level 6 and Brotli quality 6, common defaults for on-the-fly compression (as in HTML Minifier’s benchmarks) |
+| `-s, --sample <count>` | Pages to evaluate at most (default: 20) |
+| `--file-ext <list>` | File extensions to read in directories, `*` for all files (default: `html,htm,shtml,shtm`, as HTML Minifier, or the configuration’s `fileExt`) |
+| `--ignore-dir <list>` | Directory names to skip (default: `node_modules`, or the configuration’s `ignoreDir`) |
+| `--keep <list>` | Options to recommend regardless of risks and gains |
+| `--skip <list>` | Options not to evaluate |
+| `--no-render` | Skip the render check, not recommending options that need it |
+| `--no-equivalence` | Skip HTML Minifier’s equivalence check |
+| `--no-presets` | Skip comparing with HTML Minifier’s presets |
+| `--viewports <list>` | Viewports to render at (default: `1280x800,390x844`) |
+| `--concurrency <count>` | Pages to render at once, across viewports and options (default: 4) |
+| `--follow-links` | Follow symbolic links outside the site in the render check, without asking (do so only for sites you trust) |
+| `--json` | Print the full result as JSON |
+| `-v, --verbose` | Show every page and viewport in details (rather than a summary with an example), more notes, and progress line by line where STDERR isn’t a terminal |
+
+### Programmatic use
+
+HTML Minifier Setup is ESM-only.
+
+```js
+import { createRenderer, customize, loadPages, toConfig } from 'html-minifier-setup';
+
+const pages = await loadPages(['./dist']);
+const { renderer } = await createRenderer();
+try {
+  const result = await customize(pages, { renderer, metric: 'brotli' });
+  console.log(toConfig(result));
+} finally {
+  await renderer?.close();
+}
+```
+
+## How it works
+
+1. **Each option on its own:** Every candidate option is run on every page and measured against output without it. Options that change nothing (“no effect”), or don’t save anything by the chosen metric (“no gain”), are left out. What an option changes is then checked against what the page relies on (see below).
+2. **All recommended options together, rendered:** Pages are rendered as written and as minified, in Chromium (or Chrome or Edge) at each viewport, and compared by screenshot, text, and script errors. Where rendering differs, options are rendered on their own to find the culprit; where none breaks rendering on its own, options are added by savings until rendering holds.
+3. **Contributions:** Each option’s share of the final savings is measured by leaving it out. Options that save nothing alongside the others are dropped.
+4. **Presets:** HTML Minifier’s presets (`conservative` and `comprehensive`) are measured and rendered on the same pages, naming options they include that don’t fit, to show what the recommended configuration gains over them.
+
+Options that need another (e.g., `removeUnusedCSS` needs `minifyCSS`) are evaluated on top of it. Where the option needed is safe but saves nothing alone, both are evaluated together, and recommended together.
+
+Where full whitespace collapsing breaks a page, HTML Minifier Setup falls back to `conservativeCollapse`, and then to `preserveLineBreaks`.
+
+### Checks
+
+| Check | Catches | Needs |
+| --- | --- | --- |
+| Static | What scripts and style sheets of the page (including linked local or same-origin ones) rely on: comments that frameworks read (e.g., Knockout, Lit, hydration markers), empty elements scripts fill, classes scripts add after `removeUnusedCSS` removed their rules, attributes that style sheets or scripts select on, and CSS that keeps whitespace | Nothing |
+| Render | Anything that changes what the page looks like on load, or adds script errors | Chromium, Chrome, or Edge |
+| Equivalence | HTML Minifier bugs, as HTML Minifier’s own check finds output that means something else to browsers than its source—for the options that check models | An HTML Minifier checkout next to this one (for now) |
+
+In the report, options are **recommended**, **kept** (as asked), or not used because they **don’t fit** these pages, have **no gain** by the chosen metric, have **no effect**, or were **skipped**. With `--json`, statuses are `accepted`, `kept`, `rejected`, `no-gain`, `no-effect`, and `skipped`.
+
+Options flagged by the static check as a **risk** don’t fit and aren’t recommended. Options flagged for a **check** (e.g., whitespace collapsing where CSS keeps whitespace) are recommended only if they render the same—without a render check, they’re rejected. **Notes** don’t reject.
+
+Options that make pages look different are mostly doing what they’re designed to do—collapsing whitespace changes spacing where a layout relies on it—so they don’t fit these pages, without HTML Minifier being at fault. Where an option that isn’t meant to change how pages look does, the report suggests it may be an HTML Minifier bug worth reporting. The configuration recommended looks the same as the original pages at every viewport checked.
+
+### Limits
+
+The checks can show that options change pages, not that they never will:
+
+* The render check sees pages as they load, not after interaction (e.g., a menu a script opens, using classes `removeUnusedCSS` removed).
+* Scripts from other origins can’t be read, and classes or attributes a script builds at runtime (e.g., `'is-' + state`) can’t be found.
+* Rendering must match pixel for pixel, so lossy changes (e.g., SVG coordinates rounded by `minifySVG`) count as differences.
+* A page sample may miss templates the rest of the site uses.
+* Options that have no effect can’t be judged: On pages that are minified already, most options are left out, as there’s nothing left for them to do. Run HTML Minifier Setup on pages before minification instead.
+
+Test the configuration on your site before deploying it.
+
+Options that newer versions of HTML Minifier add are evaluated once HTML Minifier Setup knows them; until then, the report names them.
+
+Options HTML Minifier can’t express in one configuration are not evaluated: `minifyURLs` depends on each page’s URL, and `removeTagWhitespace` produces invalid HTML.
+
+Large pages take longer, especially by `brotli`.

package/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { Command, Option } from 'commander';
+import { splitConfig } from './src/catalog.js';
+import { paint, supportsColor } from './src/color.js';
+import { loadEquivalence } from './src/equivalence.js';
+import { METRICS } from './src/measure.js';
+import { EXTENSIONS_DEFAULT, findOutsideLinks, loadPages } from './src/pages.js';
+import { createProgress } from './src/progress.js';
+import { CONCURRENCY_DEFAULT, createRenderer, installChromium, VIEWPORTS_DEFAULT } from './src/render.js';
+import { formatReport, toConfig, toPresetConfig } from './src/report.js';
+import { customize } from './src/select.js';
+import { CONFIG_FILE as CONFIG_FILE_DEFAULT, fetchLatestVersion, isYes, offerSetup, projectOf } from './src/setup.js';
+
+let progress = createProgress();
+
+const { version } = JSON.parse(fs.readFileSync(new URL('package.json', import.meta.url), 'utf8'));
+
+/** @param {unknown} value */
+const list = (value) => (Array.isArray(value) ? value.map(String) : String(value).split(',')).map((item) => item.trim()).filter(Boolean);
+
+/** @param {string} value */
+const positiveInteger = (value) => {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) throw new Error(`Not a positive integer: ${value}`);
+  return number;
+};
+
+/** @param {string} value */
+const viewports = (value) => {
+  const items = list(value);
+  if (!items.length) throw new Error('No viewports given (e.g., 1280x800,390x844)');
+  return items.map((item) => {
+    const match = item.match(/^([1-9]\d*)x([1-9]\d*)$/);
+    if (!match) throw new Error(`Not a viewport (e.g., 1280x800): ${item}`);
+    return { width: Number(match[1]), height: Number(match[2]) };
+  });
+};
+
+/**
+ * @param {string} file
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function readConfig(file) {
+  const resolved = path.resolve(file);
+  if (/\.[cm]?js$/.test(resolved)) {
+    const module = await import(pathToFileURL(resolved).href);
+    return module.default ?? module;
+  }
+  return JSON.parse(await fs.promises.readFile(resolved, 'utf8'));
+}
+
+const program = new Command()
+  .name('html-minifier-setup')
+  .description('Identifies the HTML Minifier options that save the most on your pages without changing how they render')
+  .version(version)
+  .argument('[inputs...]', 'HTML files, directories, or URLs', ['.'])
+  .option('-c, --config-file <file>', `Start from an HTML Minifier configuration (JSON or module), carrying over its input handling options (defaults to ${CONFIG_FILE_DEFAULT} in the working directory, if present)`)
+  .option('-o, --output [file]', `Write the configuration to a file (default: ${CONFIG_FILE_DEFAULT}) rather than print it`)
+  .addOption(new Option('-m, --metric <metric>', 'Size that decides whether an option gains').choices(METRICS).default('gzip'))
+  .option('-s, --sample <count>', 'Pages to evaluate at most, spread across directories', positiveInteger, 20)
+  .option('--file-ext <list>', 'File extensions to read in directories (`*` for all files)', list, EXTENSIONS_DEFAULT)
+  .option('--ignore-dir <list>', 'Directory names to skip', list, ['node_modules'])
+  .option('--keep <list>', 'Options to recommend regardless of risks and gains', list, [])
+  .option('--skip <list>', 'Options not to evaluate', list, [])
+  .option('--no-render', 'Skip the render check (not recommending options that need it)')
+  .option('--no-equivalence', 'Skip HTML Minifier’s equivalence check')
+  .option('--no-presets', 'Skip comparing with HTML Minifier’s presets')
+  .option('--viewports <list>', 'Viewports to render at', viewports, VIEWPORTS_DEFAULT)
+  .option('--concurrency <count>', 'Pages to render at once', positiveInteger, CONCURRENCY_DEFAULT)
+  .option('--follow-links', 'Follow symbolic links outside the site in the render check, without asking (do so only for sites you trust)')
+  .option('--json', 'Print the full result as JSON')
+  .option('-v, --verbose', 'Show every page and viewport in details, progress line by line where STDERR isn’t a terminal, and more notes')
+  .action(async (inputs, settings, command) => {
+    if (settings.verbose) progress = createProgress({ verbose: true });
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !settings.output && !settings.json;
+    // Asked while pages are evaluated, for the offers at the end
+    const latest = interactive && !process.env.CI && !process.env.NO_UPDATE_NOTIFIER ? fetchLatestVersion('html-minifier') : null;
+
+    // As HTML Minifier does, a configuration in the working directory is used where none is given
+    let fileConfig = settings.configFile;
+    if (!fileConfig && fs.existsSync(path.resolve(CONFIG_FILE_DEFAULT))) {
+      fileConfig = CONFIG_FILE_DEFAULT;
+      progress.log(`Using config file ${CONFIG_FILE_DEFAULT}`);
+    }
+    const { base, values, preserved, ignored } = splitConfig(fileConfig ? await readConfig(fileConfig) : {});
+    if (ignored.length && settings.verbose) progress.log(`Not carried from ${fileConfig}: ${ignored.join(', ')}`);
+    /** @param {'fileExt' | 'ignoreDir'} name */
+    const fromConfig = (name) => command.getOptionValueSource(name) === 'default' && preserved[name] !== undefined ? list(preserved[name]) : settings[name];
+
+    progress.update({ phase: 'read', detail: inputs.join(', ') });
+    const pages = await loadPages(inputs, { extensions: fromConfig('fileExt'), ignore: fromConfig('ignoreDir'), sample: settings.sample });
+    if (!pages.length) throw new Error(`No pages found in ${inputs.join(', ')}`);
+
+    const followLinks = settings.render && (settings.followLinks || (interactive && await confirmLinks(pages, fromConfig('ignoreDir'))));
+    const settingsRenderer = { viewports: settings.viewports, concurrency: settings.concurrency, followLinks };
+    if (settings.render) progress.update({ phase: 'start' });
+    let rendering = settings.render ? await createRenderer(settingsRenderer) : { renderer: null, reason: 'skipped as asked' };
+    if ('missing' in rendering && rendering.missing && interactive) {
+      progress.stop({ ok: false });
+      const download = await withPrompt(async (ask) => isYes(await ask('No browser found for the render check. Download Chromium (about 150 MB)? (y/N) ')));
+      if (download && await installChromium()) {
+        progress.update({ phase: 'start' });
+        rendering = await createRenderer(settingsRenderer);
+      }
+    }
+    const { renderer, reason } = rendering;
+    const equivalence = settings.equivalence ? await loadEquivalence() : null;
+    try {
+      const result = await customize(pages, {
+        base,
+        values,
+        metric: settings.metric,
+        keep: settings.keep,
+        skip: settings.skip,
+        renderer,
+        equivalence,
+        presets: settings.presets,
+        onProgress: progress.update
+      });
+      // Sets the finished phases apart from the report
+      if (progress.stop() && process.stdout.isTTY) console.log('');
+      if (settings.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const color = supportsColor(process.stdout);
+      console.log(formatReport(result, { renderReason: reason, color, verbose: settings.verbose }));
+      const config = toConfig(result, preserved);
+      if (settings.output) {
+        const fileOutput = settings.output === true ? CONFIG_FILE_DEFAULT : settings.output;
+        await fs.promises.writeFile(fileOutput, `${JSON.stringify(config, null, 2)}\n`);
+        console.log(`\nWrote ${fileOutput}`);
+        return;
+      }
+      console.log(`\n${paint('bold', 'Recommended configuration:', color)}\n${JSON.stringify(config, null, 2)}\n`);
+      if (interactive) await promptSetup(config, toPresetConfig(result, preserved), latest, projectOf(inputs, process.cwd()));
+    } finally {
+      await renderer?.close();
+    }
+  });
+
+/**
+ * Whether to follow symbolic links outside the site, as a page’s scripts could send on what they
+ * lead to: asked where any are found (the report names files not gotten either way)
+ * @param {import('./src/pages.js').Page[]} pages
+ * @param {string[]} ignore
+ */
+async function confirmLinks(pages, ignore) {
+  const roots = [...new Set(pages.flatMap(({ root }) => root ? [root] : []))];
+  const links = (await Promise.all(roots.map((root) => findOutsideLinks(root, ignore)))).flat()
+    .map(({ link, target }) => ({ link: path.relative(process.cwd(), link), target }));
+  if (!links.length) return false;
+  progress.stop();
+  const named = `${links.slice(0, 3).map(({ link, target }) => `${link} → ${target}`).join(', ')}${links.length > 3 ? `, and ${links.length - 3} more` : ''}`;
+  return withPrompt(async (ask) => isYes(await ask(`The site links to files outside it (${named}). Follow these links in the render check? Only do so for sites you trust, as their scripts could send on what the links lead to (y/N) `)));
+}
+
+/**
+ * Asks on the terminal whether to save the configuration and install HTML Minifier
+ * @param {Record<string, unknown>} config
+ * @param {ReturnType<typeof toPresetConfig>} configPreset
+ * @param {Promise<string | null> | null} latest
+ * @param {string} dirProject
+ */
+async function promptSetup(config, configPreset, latest, dirProject) {
+  await withPrompt((ask) => offerSetup({ config, configPreset, latest, dirProject, cwd: process.cwd(), ask, log: (message) => console.log(message) }));
+}
+
+/**
+ * Runs `fn` with a way to ask questions on the terminal
+ * @template T
+ * @param {(ask: (question: string) => Promise<string>) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withPrompt(fn) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on('SIGINT', () => {
+    rl.close();
+    process.exit(130);
+  });
+  try {
+    return await fn((question) => rl.question(question));
+  } finally {
+    rl.close();
+  }
+}
+
+try {
+  await program.parseAsync();
+} catch (err) {
+  progress.stop({ ok: false });
+  console.error(`Error: ${err instanceof Error ? err.message : err}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,60 @@
 {
+  "author": "Jens Oliver Meiert",
+  "bin": {
+    "hms": "cli.js",
+    "html-minifier-setup": "cli.js"
+  },
+  "bugs": "https://github.com/j9t/html-minifier-setup/issues",
+  "dependencies": {
+    "commander": "^15.1.0",
+    "html-minifier": "^5.1.0",
+    "parse5": "^8.1.1",
+    "playwright": "^1.65.0"
+  },
+  "description": "Configuration wizard for HTML Minifier: Identify the options that save the most on your pages without changing how they render",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.6",
+    "eslint": "^10.14.0",
+    "globals": "^17.14.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cli.js",
+    "src"
+  ],
+  "funding": "https://github.com/j9t/html-minifier-setup?sponsor=1",
+  "homepage": "https://github.com/j9t/html-minifier-setup",
+  "keywords": [
+    "configuration",
+    "html",
+    "html-minifier",
+    "minification",
+    "minifier",
+    "optimization",
+    "setup"
+  ],
+  "license": "MIT",
   "name": "html-minifier-setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/j9t/html-minifier-setup.git"
+  },
+  "scripts": {
+    "benchmark": "node benchmark/benchmark.js",
+    "lint": "eslint .",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "test": "npm run test:types && node --test \"test/**/*.test.js\"",
+    "test:types": "tsc",
+    "test:watch": "node --test --watch \"test/**/*.test.js\""
+  },
+  "type": "module",
+  "version": "0.1.0"
 }

package/src/catalog.js

@@ -0,0 +1,158 @@
+// How each HTML Minifier option takes part in finding a configuration; a test checks that every
+// option of the installed version has a place here, and the report notes any that don’t
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * @typedef {object} Candidate
+ * @prop {string} name
+ * @prop {Record<string, unknown>} options What evaluating the candidate sets
+ * @prop {string} [requires] Candidate that must be accepted for this one to take effect
+ */
+
+/** @type {Candidate[]} */
+export const CANDIDATES = [
+  { name: 'collapseWhitespace', options: { collapseWhitespace: true } },
+  { name: 'collapseAttributeWhitespace', options: { collapseAttributeWhitespace: true } },
+  { name: 'collapseBooleanAttributes', options: { collapseBooleanAttributes: true } },
+  { name: 'collapseEmptyAttributes', options: { collapseEmptyAttributes: true } },
+  { name: 'decodeEntities', options: { decodeEntities: true } },
+  { name: 'mergeScripts', options: { mergeScripts: true } },
+  { name: 'mergeStyles', options: { mergeStyles: true } },
+  { name: 'minifyCSS', options: { minifyCSS: true } },
+  { name: 'minifyJS', options: { minifyJS: true } },
+  { name: 'minifyJSON', options: { minifyJSON: true } },
+  { name: 'minifySVG', options: { minifySVG: true } },
+  { name: 'removeAttributeQuotes', options: { removeAttributeQuotes: true } },
+  { name: 'removeComments', options: { removeComments: true } },
+  { name: 'removeDefaultTypeAttributes', options: { removeDefaultTypeAttributes: true } },
+  { name: 'removeEmptyAttributes', options: { removeEmptyAttributes: true } },
+  { name: 'removeEmptyElements', options: { removeEmptyElements: true } },
+  { name: 'removeOptionalTags', options: { removeOptionalTags: true } },
+  { name: 'removeRedundantAttributes', options: { removeRedundantAttributes: true } },
+  { name: 'selfCloseForeignElements', options: { selfCloseForeignElements: true } },
+  { name: 'sortAttributes', options: { sortAttributes: true } },
+  { name: 'sortClassNames', options: { sortClassNames: true } },
+  { name: 'useShortDoctype', options: { useShortDoctype: true } },
+  { name: 'collapseInlineTagWhitespace', options: { collapseInlineTagWhitespace: true }, requires: 'collapseWhitespace' },
+  { name: 'collapseNoBreakSpaces', options: { collapseNoBreakSpaces: true }, requires: 'collapseWhitespace' },
+  { name: 'trimCustomFragments', options: { trimCustomFragments: true }, requires: 'collapseWhitespace' },
+  { name: 'removeUnusedCSS', options: { removeUnusedCSS: true }, requires: 'minifyCSS' }
+];
+
+/**
+ * Gentler variants, tried in order where a candidate is rejected for what it changes
+ * @type {Record<string, {variant: string, options: Record<string, unknown>}[]>}
+ */
+export const FALLBACKS = {
+  collapseWhitespace: [
+    { variant: 'conservativeCollapse', options: { collapseWhitespace: true, conservativeCollapse: true } },
+    { variant: 'preserveLineBreaks', options: { collapseWhitespace: true, conservativeCollapse: true, preserveLineBreaks: true } }
+  ]
+};
+
+// Only set through fallbacks
+export const MODIFIERS = ['conservativeCollapse', 'preserveLineBreaks'];
+
+// How input is read and output written, which a starting configuration knows best
+export const CARRIED = [
+  'caseSensitive',
+  'continueOnMinifyError',
+  'continueOnParseError',
+  'customAttrAssign',
+  'customAttrCollapse',
+  'customAttrSurround',
+  'customEventAttributes',
+  'ignoreCustomComments',
+  'ignoreCustomFragments',
+  'includeAutoGeneratedTags',
+  'inlineCustomElements',
+  'keepClosingSlash',
+  'maxInputLength',
+  'maxLineLength',
+  'noNewlinesBeforeTagClose',
+  'partialMarkup',
+  'preventAttributesEscaping',
+  'processScripts',
+  'quoteCharacter',
+  'removeEmptyElementsExcept',
+  'strictCustomFragments'
+];
+
+// HTML Minifier CLI settings, which don’t change output but are kept when writing a configuration
+export const PRESERVED = ['cacheCSS', 'cacheJS', 'cacheSVG', 'fileExt', 'ignoreDir'];
+
+// What options can change on the page by design, where they look different
+/** @type {Record<string, string>} */
+export const VISIBLE_BY_DESIGN = {
+  collapseInlineTagWhitespace: 'Removes whitespace between inline elements, which can change the spacing between them',
+  collapseNoBreakSpaces: 'Collapses non-breaking spaces, which can change spacing',
+  collapseWhitespace: 'Collapses whitespace, which can change spacing where layout relies on it (e.g., between inline elements)',
+  minifySVG: 'Rounds numbers in SVG, which can shift shapes by fractions of a pixel',
+  removeEmptyElements: 'Removes empty elements, which can take up space or carry styling',
+  removeUnusedCSS: 'Removes CSS rules for elements not in the markup, which can include elements other markup or scripts add',
+  trimCustomFragments: 'Trims whitespace around custom fragments, which can change spacing',
+  useShortDoctype: 'Replaces the doctype, which can switch the document mode (e.g., from quirks mode to standards mode)'
+};
+
+/** @type {Record<string, string>} */
+export const EXCLUDED = {
+  $schema: 'set in the output',
+  minifyURLs: 'depends on each page’s URL, which one configuration can’t express',
+  preset: 'candidates are evaluated one by one instead',
+  removeTagWhitespace: 'produces invalid HTML'
+};
+
+const CLASSIFIED = new Set([...CANDIDATES.map((candidate) => candidate.name), ...MODIFIERS, ...CARRIED, ...PRESERVED, ...Object.keys(EXCLUDED)]);
+
+/**
+ * Options without a place here
+ * @param {string[]} options
+ */
+export const unclassified = (options) => options.filter((name) => !CLASSIFIED.has(name));
+
+/**
+ * The installed HTML Minifier’s version and options, by its schema, if readable
+ * @returns {{version: string, options: string[]} | null}
+ */
+export function readSchema() {
+  try {
+    const filePackage = fileURLToPath(import.meta.resolve('html-minifier/package.json'));
+    const { version } = JSON.parse(fs.readFileSync(filePackage, 'utf8'));
+    const schema = JSON.parse(fs.readFileSync(path.join(path.dirname(filePackage), 'html-minifier.schema.json'), 'utf8'));
+    return { version, options: Object.keys(schema.properties ?? {}) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Splits a starting configuration into what is carried into every run, candidate values to
+ * evaluate (other than `true`), CLI settings to keep, and what is dropped
+ * @param {Record<string, unknown>} config
+ */
+export function splitConfig(config) {
+  /** @type {Record<string, unknown>} */
+  const base = {};
+  /** @type {Record<string, unknown>} */
+  const values = {};
+  /** @type {Record<string, unknown>} */
+  const preserved = {};
+  /** @type {string[]} */
+  const ignored = [];
+  const names = new Set(CANDIDATES.map((candidate) => candidate.name));
+  for (const [name, value] of Object.entries(config)) {
+    if (CARRIED.includes(name)) {
+      base[name] = value;
+    } else if (PRESERVED.includes(name)) {
+      preserved[name] = value;
+    } else if (names.has(name) && value !== false && value !== true) {
+      values[name] = value;
+    } else if (!names.has(name) || value === false) {
+      ignored.push(name);
+    }
+  }
+  return { base, values, preserved, ignored };
+}

package/src/color.js

@@ -0,0 +1,17 @@
+// Terminal styles from the terminal’s own palette, which themes adapt to light and dark: standard
+// colors, bold, and dim only—never fixed black, white, or 256-color values
+
+export const ESC = '\u001b';
+export const CSI = `${ESC}[`;
+
+const STYLES = { bold: '1', dim: '2', accent: '36', success: '32', warning: '33', failure: '31' };
+
+/**
+ * @param {keyof typeof STYLES} name
+ * @param {string} text
+ * @param {boolean} color
+ */
+export const paint = (name, text, color) => color && text ? `${CSI}${STYLES[name]}m${text}${CSI}0m` : text;
+
+/** @param {{isTTY?: boolean}} stream */
+export const supportsColor = (stream) => Boolean(stream.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';

package/src/equivalence.js

@@ -0,0 +1,68 @@
+// HTML Minifier’s own check that output means the same to browsers as its source, which catches
+// minifier bugs rather than what a site relies on—used where available, never duplicated here
+
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/**
+ * @typedef {object} Equivalence
+ * @prop {string} source Where the check came from
+ * @prop {(name: string) => boolean} supports Whether the check models what an option changes—others would show as differences
+ * @prop {(input: string, output: string, options: Record<string, unknown>) => string[]} compare Differences found, if any
+ */
+
+// @@ Import `html-minifier/equivalence` alone once HTML Minifier exports its check
+const SPECIFIER_EXPORT = 'html-minifier/equivalence';
+const FILE_SIBLING = fileURLToPath(new URL('../../html-minifier/test/equivalence/compare.js', import.meta.url));
+// Lists the options the check is run with
+const FILE_SIBLING_RUNNER = fileURLToPath(new URL('../../html-minifier/test/equivalence/runner.js', import.meta.url));
+
+/**
+ * @param {unknown} difference
+ * @returns {string}
+ */
+function describe(difference) {
+  if (difference && typeof difference === 'object' && 'kind' in difference) {
+    const { kind, input, output } = /** @type {{kind: string, input?: string, output?: string}} */ (difference);
+    const clip = (/** @type {string | undefined} */ text) => (text ?? '').split('\u0001').join(' ').slice(0, 80);
+    return `${kind}: ${clip(input)} → ${clip(output)}`;
+  }
+  return String(difference);
+}
+
+/** @param {URL} url */
+function versionOf(url) {
+  try {
+    return JSON.parse(fs.readFileSync(url, 'utf8')).version ?? '?';
+  } catch {
+    return '?';
+  }
+}
+
+/**
+ * The installed HTML Minifier’s check, or that of an HTML Minifier checkout next to this
+ * package; `null` where neither is available
+ * @returns {Promise<Equivalence | null>}
+ */
+export async function loadEquivalence() {
+  /** @type {[string, () => Promise<any>][]} */
+  const sources = [
+    [SPECIFIER_EXPORT, () => import(SPECIFIER_EXPORT)],
+    [FILE_SIBLING, async () => {
+      if (!fs.existsSync(FILE_SIBLING) || !fs.existsSync(FILE_SIBLING_RUNNER)) return null;
+      const [compare, runner] = await Promise.all([import(pathToFileURL(FILE_SIBLING).href), import(pathToFileURL(FILE_SIBLING_RUNNER).href)]);
+      return { ...runner, ...compare };
+    }]
+  ];
+  for (const [source, load] of sources) {
+    const module = await load().catch(() => null);
+    if (typeof module?.compareMarkup !== 'function' || !module.OPTIONS_STRUCTURAL || !module.OPTIONS_CODE) continue;
+    const supported = new Set([...Object.keys(module.OPTIONS_STRUCTURAL), ...Object.keys(module.OPTIONS_CODE)]);
+    return {
+      source: source === FILE_SIBLING ? `${source} (HTML Minifier ${versionOf(new URL('../../package.json', pathToFileURL(FILE_SIBLING)))}, minifying with installed ${versionOf(new URL(import.meta.resolve('html-minifier/package.json')))})` : source,
+      supports: (name) => supported.has(name),
+      compare: (input, output, options) => /** @type {unknown[]} */ (module.compareMarkup(input, output, options)).map(describe)
+    };
+  }
+  return null;
+}