feat: chain source maps for all minimizers via the dispatcher

Move source-map composition out of each minimizer and into `minify.js`.
After every step in the `minify` array, the dispatcher composes the
step's `name → step-output` map with the accumulated `original → name`
map using a tiny in-house composer built on `@jridgewell/trace-mapping`
(already a direct dep) plus an inline VLQ encoder. No new packages.

This makes source-map chaining work uniformly across every built-in
minimizer — including the ones whose underlying tools don't accept an
input source map natively (`@swc/core`, `esbuild`, `csso`, `@swc/css`).
Previously, mixing such minimizers in a `minify: [...]` array silently
dropped the chain back to the original sources.

Adds three more multi-minimizer test cases (terser+swc, terser+esbuild,
and a CSS chain that runs `cssnano` → `csso` → `cleanCss` →
`lightningCss` → `swcMinifyCss` → `esbuildMinifyCss`); existing
snapshots that previously captured tool-internal chained maps are
updated to the dispatcher-chained equivalents.

Author: claude

src/minify.js

@@ -6,6 +6,286 @@
  * @typedef {import("./index.js").MinimizerOptions<T>} MinimizerOptions
  */
 
+const VLQ_BASE64 =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Encode a single integer as Base64 VLQ as used by the source-map spec.
+ * @param {number} value integer to encode
+ * @returns {string} encoded VLQ characters
+ */
+/* eslint-disable prefer-destructuring, no-eq-null, eqeqeq */
+/**
+ * @param {number} value integer to encode
+ * @returns {string} encoded VLQ characters
+ */
+function encodeVlq(value) {
+  let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
+  let out = "";
+
+  do {
+    let digit = vlq & 0b11111;
+
+    vlq >>>= 5;
+
+    if (vlq > 0) {
+      digit |= 0b100000;
+    }
+
+    out += VLQ_BASE64[digit];
+  } while (vlq > 0);
+
+  return out;
+}
+
+/**
+ * Encode decoded source-map mappings (per-line arrays of segments) back into
+ * the spec's `mappings` string.
+ * @param {number[][][]} decoded mappings as nested arrays of segments
+ * @returns {string} encoded `mappings` field
+ */
+function encodeMappings(decoded) {
+  let result = "";
+  let prevSourceIdx = 0;
+  let prevOriginalLine = 0;
+  let prevOriginalColumn = 0;
+  let prevNameIdx = 0;
+
+  for (let line = 0; line < decoded.length; line++) {
+    if (line > 0) {
+      result += ";";
+    }
+
+    let prevGeneratedColumn = 0;
+    const segments = decoded[line];
+
+    for (let i = 0; i < segments.length; i++) {
+      if (i > 0) {
+        result += ",";
+      }
+
+      const seg = segments[i];
+
+      result += encodeVlq(seg[0] - prevGeneratedColumn);
+      prevGeneratedColumn = seg[0];
+
+      if (seg.length >= 4) {
+        result += encodeVlq(seg[1] - prevSourceIdx);
+        prevSourceIdx = seg[1];
+        result += encodeVlq(seg[2] - prevOriginalLine);
+        prevOriginalLine = seg[2];
+        result += encodeVlq(seg[3] - prevOriginalColumn);
+        prevOriginalColumn = seg[3];
+
+        if (seg.length >= 5) {
+          result += encodeVlq(seg[4] - prevNameIdx);
+          prevNameIdx = seg[4];
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Compose a freshly-produced source map with the input source map fed to
+ * the minimizer. `currentMap` represents `name → step-output` and
+ * `prevMap` represents `original → name`; the result represents
+ * `original → step-output`.
+ * @param {RawSourceMap | undefined} currentMap map produced by the minimizer
+ * @param {RawSourceMap | undefined} prevMap input source map fed to the minimizer
+ * @param {string} name name of the asset that the current map points to
+ * @returns {RawSourceMap | undefined} composed map
+ */
+function composeSourceMaps(currentMap, prevMap, name) {
+  if (!currentMap || !prevMap) {
+    return currentMap;
+  }
+
+  const {
+    TraceMap,
+    decodedMappings,
+    originalPositionFor,
+    sourceContentFor,
+  } = require("@jridgewell/trace-mapping");
+
+  const current = new TraceMap(
+    /** @type {import("@jridgewell/trace-mapping").SourceMapInput} */ (
+      /** @type {unknown} */ (currentMap)
+    ),
+  );
+  const previous = new TraceMap(
+    /** @type {import("@jridgewell/trace-mapping").SourceMapInput} */ (
+      /** @type {unknown} */ (prevMap)
+    ),
+  );
+
+  /** @type {string[]} */
+  const sources = [];
+  /** @type {(string | null)[]} */
+  const sourcesContent = [];
+  /** @type {string[]} */
+  const names = [];
+  /** @type {Map<string, number>} */
+  const sourceIdx = new Map();
+  /** @type {Map<string, number>} */
+  const nameIdx = new Map();
+
+  /**
+   * @param {string | null | undefined} source source identifier
+   * @param {string | undefined} content source content (when available)
+   * @returns {number} index assigned in the composed map
+   */
+  const getSourceIdx = (source, content) => {
+    const key = source || "";
+    let idx = sourceIdx.get(key);
+
+    if (typeof idx === "undefined") {
+      idx = sources.length;
+      sources.push(key);
+      sourcesContent.push(typeof content === "string" ? content : null);
+      sourceIdx.set(key, idx);
+    } else if (typeof content === "string" && sourcesContent[idx] === null) {
+      sourcesContent[idx] = content;
+    }
+
+    return idx;
+  };
+
+  /**
+   * @param {string | null | undefined} value name
+   * @returns {number} index assigned in the composed map
+   */
+  const getNameIdx = (value) => {
+    if (typeof value !== "string") {
+      return -1;
+    }
+
+    let idx = nameIdx.get(value);
+
+    if (typeof idx === "undefined") {
+      idx = names.length;
+      names.push(value);
+      nameIdx.set(value, idx);
+    }
+
+    return idx;
+  };
+
+  const decoded = decodedMappings(current);
+  const currentSources = current.sources.map(
+    /**
+     * @param {string | null} source source from current map
+     * @returns {string} normalized source string
+     */
+    (source) => source || "",
+  );
+  const currentNames = current.names;
+
+  /** @type {number[][][]} */
+  const composed = [];
+
+  for (let line = 0; line < decoded.length; line++) {
+    /** @type {number[][]} */
+    const newSegments = [];
+
+    for (const rawSeg of decoded[line]) {
+      const seg = /** @type {number[]} */ (rawSeg);
+
+      // Single-element segment is just a generated column with no source info
+      if (seg.length < 4) {
+        newSegments.push([seg[0]]);
+        continue;
+      }
+
+      const sourceName = currentSources[seg[1]];
+      const origLine = /** @type {number} */ (seg[2]);
+      const origCol = /** @type {number} */ (seg[3]);
+      const segName =
+        seg.length >= 5
+          ? currentNames[seg[4]]
+          : /** @type {string | null} */ (null);
+
+      // When the segment points back at our intermediate `name`, look up
+      // the original position in the previous map and emit a mapping that
+      // points all the way back. Otherwise keep the segment as-is.
+      if (sourceName === name) {
+        const orig = originalPositionFor(previous, {
+          line: origLine + 1,
+          column: origCol,
+        });
+
+        if (
+          typeof orig.source !== "string" ||
+          orig.line == null ||
+          orig.column == null
+        ) {
+          continue;
+        }
+
+        const content = sourceContentFor(previous, orig.source) || undefined;
+        const newSrcIdx = getSourceIdx(orig.source, content);
+        const finalName =
+          typeof orig.name === "string" && orig.name ? orig.name : segName;
+
+        if (typeof finalName === "string") {
+          newSegments.push([
+            seg[0],
+            newSrcIdx,
+            orig.line - 1,
+            orig.column,
+            getNameIdx(finalName),
+          ]);
+        } else {
+          newSegments.push([seg[0], newSrcIdx, orig.line - 1, orig.column]);
+        }
+      } else {
+        const content = sourceContentFor(current, sourceName) || undefined;
+        const newSrcIdx = getSourceIdx(sourceName, content);
+
+        if (typeof segName === "string") {
+          newSegments.push([
+            seg[0],
+            newSrcIdx,
+            origLine,
+            origCol,
+            getNameIdx(segName),
+          ]);
+        } else {
+          newSegments.push([seg[0], newSrcIdx, origLine, origCol]);
+        }
+      }
+    }
+
+    composed.push(newSegments);
+  }
+
+  const result =
+    /** @type {RawSourceMap} */
+    (
+      /** @type {unknown} */ ({
+        version: 3,
+        sources,
+        names,
+        mappings: encodeMappings(composed),
+      })
+    );
+
+  if (currentMap.file) {
+    result.file = currentMap.file;
+  }
+
+  if (sourcesContent.some((value) => typeof value === "string")) {
+    result.sourcesContent =
+      /** @type {string[]} */
+      (/** @type {unknown} */ (sourcesContent));
+  }
+
+  return result;
+}
+/* eslint-enable no-bitwise, prefer-destructuring, no-eq-null, eqeqeq */
+
 /**
  * @template T
  * @param {import("./index.js").InternalOptions<T>} options options
@@ -74,7 +354,10 @@ async function minify(options) {
 
     if (typeof result.code === "string") {
       lastCode = result.code;
-      lastMap = result.map;
+      // The minimizer's output map is `name → step-output`. Chain it with
+      // the previous accumulated map so that across an array of minimizers
+      // the final map points back to the original sources.
+      lastMap = composeSourceMaps(result.map, currentMap, name);
     }
   }
 

src/utils.js

@@ -289,14 +289,10 @@ async function terserMinify(
   // Copy `terser` options
   const terserOptions = buildTerserOptions(minimizerOptions);
 
-  // Let terser generate a SourceMap. Pass the input source map so that
-  // chained minimizers produce a map back to the original sources.
+  // Let terser generate a SourceMap. The dispatcher in `minify.js`
+  // chains the previous step's map onto this one.
   if (sourceMap) {
-    terserOptions.sourceMap =
-      /** @type {import("terser").SourceMapOptions} */ ({
-        asObject: true,
-        content: sourceMap,
-      });
+    terserOptions.sourceMap = { asObject: true };
   }
 
   /** @type {ExtractedComments} */
@@ -543,13 +539,10 @@ async function uglifyJsMinify(
   // Copy `uglify-js` options
   const uglifyJsOptions = buildUglifyJsOptions(minimizerOptions);
 
-  // Let `uglify-js` generate a SourceMap, chaining through the input
-  // map so that combined minimizers map back to original sources.
+  // Let `uglify-js` generate a SourceMap. The dispatcher in `minify.js`
+  // chains the previous step's map onto this one.
   if (sourceMap) {
-    uglifyJsOptions.sourceMap =
-      /** @type {import("uglify-js").SourceMapOptions} */ (
-        /** @type {unknown} */ ({ content: sourceMap })
-      );
+    uglifyJsOptions.sourceMap = true;
   }
 
   /** @type {ExtractedComments} */
@@ -1310,7 +1303,7 @@ async function cssnanoMinify(
   }
 
   if (sourceMap) {
-    postcssOptions.map = { annotation: false, prev: sourceMap };
+    postcssOptions.map = { annotation: false };
   }
 
   const result = await postcss
@@ -1624,7 +1617,8 @@ async function lightningCssMinify(input, sourceMap, minimizerOptions) {
   // Copy `lightningCss` options
   const lightningCssOptions = buildLightningCssOptions(minimizerOptions);
 
-  // Let `lightningcss` generate a SourceMap
+  // Let `lightningcss` generate a SourceMap. The dispatcher in
+  // `minify.js` chains the previous step's map onto this one.
   if (sourceMap) {
     lightningCssOptions.sourceMap = true;
   }