postcss-merge-rules 9.0.0 → 9.0.2

package/src/index.js

@@ -5,67 +5,28 @@ import {
   sameVendor,
   noVendor,
 } from './lib/ensureCompatibility.js';
-import { isConflictingProp } from './lib/propertyRelations.js';
+import {
+  filterRuleIntersections,
+  indexOfDeclaration,
+  intersect,
+  sameDeclarationsAndOrder,
+} from './lib/declarations.js';
+import { flush, getDecls, getMeta } from './lib/rule-meta.js';
+import {
+  buildMergedRule,
+  mergeParents,
+  mergeWithNextRule,
+} from './lib/rule-rewrite.js';
 
 /** @import browserslist from 'browserslist' */
 const { sameParent } = cssnanoUtils;
 /** @import {Declaration, Rule} from 'postcss' */
 /**
- * @param {Declaration} a
- * @param {Declaration} b
- * @return {boolean}
- */
-function declarationIsEqual(a, b) {
-  return (
-    a.important === b.important && a.prop === b.prop && a.value === b.value
-  );
-}
-
-/**
- * @param {Declaration[]} array
- * @param {Declaration} decl
- * @return {number}
- */
-function indexOfDeclaration(array, decl) {
-  return array.findIndex((d) => declarationIsEqual(d, decl));
-}
-
-/**
- * Returns filtered array of matched or unmatched declarations
- * @param {Declaration[]} a
- * @param {Declaration[]} b
- * @param {boolean} [not=false]
- * @return {Declaration[]}
- */
-function intersect(a, b, not) {
-  return a.filter((c) => {
-    const index = indexOfDeclaration(b, c) !== -1;
-    return not ? !index : index;
-  });
-}
-
-/**
- * @param {Declaration[]} a
- * @param {Declaration[]} b
- * @return {boolean}
- */
-function sameDeclarationsAndOrder(a, b) {
-  if (a.length !== b.length) {
-    return false;
-  }
-  return a.every((d, index) => declarationIsEqual(d, b[index]));
-}
-
-/**
- * RuleMeta stores metadata about a `Rule` during the merging process.
- * It tracks selectors and declarations without re-parsing the AST many times.
- *
  * @typedef {Object} RuleMeta
  * @property {string[]} selectors - Array of selector strings for the rule
  * @property {Declaration[]} declarations - Array of declaration nodes for the rule
  * @property {boolean} dirty - Whether the selectors have been modified and need flushing
  */
-
 /**
  * @param {Rule} ruleA
  * @param {Rule} ruleB
@@ -128,378 +89,24 @@ function canMerge(
 function isRuleOrAtRule(node) {
   return node.type === 'rule' || node.type === 'atrule';
 }
-/**
- * @param {import('postcss').ChildNode} node
- * @return {node is Declaration}
- */
-function isDeclaration(node) {
-  return node.type === 'decl';
-}
-
-/**
- * Retrieves or initializes virtual metadata for a PostCSS rule.
- *
- * This metadata caches selectors and declarations to avoid expensive AST
- * re-parsing, especially for the selectors.
- *
- * @param {Rule} rule The PostCSS rule to get metadata for.
- * @param {WeakMap<Rule, RuleMeta>} [ruleMeta] The metadata cache.
- * @return {RuleMeta} The rule's virtual metadata.
- */
-function getMeta(rule, ruleMeta) {
-  if (ruleMeta && rule) {
-    let meta = ruleMeta.get(rule);
-    if (!meta && rule.nodes) {
-      meta = {
-        selectors: rule.selectors,
-        declarations: rule.nodes.filter(isDeclaration),
-        dirty: false,
-      };
-      ruleMeta.set(rule, meta);
-    }
-    return meta ?? { selectors: [], declarations: [], dirty: false };
-  }
-  return {
-    selectors: rule?.selectors ?? [],
-    declarations: rule?.nodes?.filter(isDeclaration) ?? [],
-    dirty: false,
-  };
-}
-
-/**
- * Commits virtual metadata changes back to the actual PostCSS rule.
- *
- * @param {Rule} rule The PostCSS rule to flush.
- * @param {WeakMap<Rule, RuleMeta>} ruleMeta The metadata cache.
- */
-function flush(rule, ruleMeta) {
-  const meta = ruleMeta.get(rule);
-  if (meta && meta.dirty) {
-    rule.selector = meta.selectors.join(',');
-    meta.dirty = false;
-  }
-}
-
-/**
- * @param {Rule} rule
- * @return {Declaration[]}
- */
-function getDecls(rule) {
-  return rule.nodes.filter(isDeclaration);
-}
-
-/**
- * @param {...Rule} rules
- * @return {number}
- */
-function ruleLength(...rules) {
-  return rules.map((r) => (r.nodes.length ? String(r) : '')).join('').length;
-}
-
-/**
- * @param {Rule} first
- * @param {Rule} second
- * @return {boolean} merged
- */
-function mergeParents(first, second) {
-  // Null check for detached rules
-  if (!first.parent || !second.parent) {
-    return false;
-  }
-
-  // Check if parents share node
-  if (first.parent === second.parent) {
-    return false;
-  }
-
-  // sameParent() already called by canMerge()
-
-  second.remove();
-  first.parent.append(second);
-  return true;
-}
-
-/**
- * @param {Rule} second
- * @return {Rule | null}
- */
-function getNextRule(second) {
-  let nextRule = second.next();
-  if (!nextRule) {
-    // Grab next cousin
-    const parentSibling =
-      /** @type {import('postcss').Container | undefined} */ (
-        /** @type {import('postcss').Container<import('postcss').ChildNode>} */ (
-          second.parent
-        ).next()
-      );
-    nextRule = parentSibling && parentSibling.nodes && parentSibling.nodes[0];
-  }
-  return nextRule?.type === 'rule' ? nextRule : null;
-}
-
-/**
- * @param {Rule} first
- * @param {Rule} second
- * @param {Declaration[]} intersection
- * @param {string[]} browsers
- * @param {Map<string, boolean>} compatibilityCache
- * @param {WeakSet<Rule>} ruleCache
- * @param {WeakMap<Rule, RuleMeta>} ruleMeta
- * @return {{first: Rule, second: Rule, intersection: Declaration[]}}
- */
-function mergeWithNextRule(
-  first,
-  second,
-  intersection,
-  browsers,
-  compatibilityCache,
-  ruleCache,
-  ruleMeta
-) {
-  const nextRule = getNextRule(second);
-  if (
-    !nextRule ||
-    !canMerge(
-      second,
-      nextRule,
-      browsers,
-      compatibilityCache,
-      ruleCache,
-      ruleMeta
-    )
-  ) {
-    return { first, second, intersection };
-  }
-
-  const nextIntersection = intersect(
-    getMeta(second, ruleMeta).declarations,
-    getMeta(nextRule, ruleMeta).declarations
-  );
-  if (nextIntersection.length <= intersection.length) {
-    return { first, second, intersection };
-  }
-
-  mergeParents(second, nextRule);
-  return { first: second, second: nextRule, intersection: nextIntersection };
-}
 
 /**
- * Returns true if hoisting `candidate` cannot reverse the cascade: every
- * declaration that might override it is itself being
- * hoisted, in the same relative order, so declarations move together.
- *
- * @param {Declaration} candidate
- * @param {number} candidateIndex
- * @param {Declaration[]} hoistCandidates
- * @param {Declaration[]} earlierRuleDeclarations
- * @return {boolean}
+ * @param {Rule | import('postcss').Container<import('postcss').ChildNode>} node
+ * @return {import('postcss').Container<import('postcss').ChildNode> | undefined}
  */
-function hoistingPreservesOverrideOrder(
-  candidate,
-  candidateIndex,
-  hoistCandidates,
-  earlierRuleDeclarations
-) {
-  const indexInEarlierRule = indexOfDeclaration(
-    earlierRuleDeclarations,
-    candidate
-  );
-  const overridesInEarlierRule = earlierRuleDeclarations
-    .slice(indexInEarlierRule + 1)
-    .filter((d) => isConflictingProp(d.prop, candidate.prop));
-  if (overridesInEarlierRule.length === 0) {
-    return true;
-  }
-  const overridesAmongCandidates = hoistCandidates
-    .slice(candidateIndex + 1)
-    .filter((d) => isConflictingProp(d.prop, candidate.prop));
-  if (overridesInEarlierRule.length !== overridesAmongCandidates.length) {
-    return false;
-  }
-  return overridesInEarlierRule.every((d, index) =>
-    declarationIsEqual(d, overridesAmongCandidates[index])
+function getParent(node) {
+  return /** @type {import('postcss').Container<import('postcss').ChildNode> | undefined} */ (
+    node.parent
   );
 }
 
-/**
- * True if the later rule has an unclaimed declaration equal to `candidate`.
- * Records its index in `claimedIndices`, so no other candidate can match the
- * same declaration. Always false when the later rule contains `all`,
- * since `all` resets everything except `direction`/`unicode-bidi`.
- *
- * @param {Declaration} candidate
- * @param {Declaration[]} laterDeclarations
- * @param {Set<number>} claimedIndices
- * @return {boolean}
- */
-function claimMatchInLaterRule(candidate, laterDeclarations, claimedIndices) {
-  const matchIndex = laterDeclarations.findIndex(
-    (d, index) =>
-      !claimedIndices.has(index) && isConflictingProp(d.prop, candidate.prop)
-  );
-  if (matchIndex === -1) {
-    return false;
-  }
-  if (!declarationIsEqual(laterDeclarations[matchIndex], candidate)) {
-    return false;
-  }
-  if (
-    candidate.prop.toLowerCase() !== 'direction' &&
-    candidate.prop.toLowerCase() !== 'unicode-bidi' &&
-    laterDeclarations.some(
-      (declaration) => declaration.prop.toLowerCase() === 'all'
-    )
-  ) {
-    return false;
-  }
-  claimedIndices.add(matchIndex);
-  return true;
-}
-
-/**
- * Narrows the declarations shared by two adjacent rules down to those that can
- * safely move into a merged rule, along with the indices of the later rule's
- * declarations they claim.
- *
- * The merged rule is emitted after the earlier rule's remaining declarations,
- * so hoisting a declaration that a later declaration in the earlier rule
- * overrides would reverse the cascade and make the previously dead value
- * effective again, unless that overriding declaration is hoisted too, so both
- * move together and keep their relative order.
- *
- * Dropping a candidate can invalidate one that was only admitted because it
- * travelled with it, so the pass repeats until the surviving set stops
- * shrinking.
- *
- * @param {Declaration[]} hoistCandidates
- * @param {Declaration[]} earlierRuleDeclarations
- * @param {Declaration[]} laterRuleDeclarations
- * @return {{intersection: Declaration[], claimedIndices: Set<number>}}
- */
-function filterRuleIntersections(
-  hoistCandidates,
-  earlierRuleDeclarations,
-  laterRuleDeclarations
-) {
-  let remainingCandidates = hoistCandidates;
-  for (;;) {
-    // A candidate rejected by the override check never claims a match.
-    const claimedIndices = new Set();
-    const survivors = remainingCandidates.filter(
-      (candidate, candidateIndex) =>
-        hoistingPreservesOverrideOrder(
-          candidate,
-          candidateIndex,
-          remainingCandidates,
-          earlierRuleDeclarations
-        ) &&
-        claimMatchInLaterRule(candidate, laterRuleDeclarations, claimedIndices)
-    );
-    if (
-      survivors.length === remainingCandidates.length ||
-      survivors.length === 0
-    ) {
-      return { intersection: survivors, claimedIndices };
-    }
-    remainingCandidates = survivors;
+/** @param {Rule | null} rule @param {import('postcss').Container<import('postcss').ChildNode>} container */
+function isDescendant(rule, container) {
+  let parent = rule ? getParent(rule) : undefined;
+  for (; parent; parent = getParent(parent)) {
+    if (parent === container) return true;
   }
-}
-
-/**
- * @param {Rule} first
- * @param {Rule} second
- * @param {Declaration[]} intersection
- * @param {Set<number>} claimedIndices Positions of the declarations the
- * intersection claimed in `second`, which the merged rule replaces.
- * @param {WeakSet<Rule>} ruleCache
- * @param {WeakMap<Rule, RuleMeta>} ruleMeta
- * @return {Rule}
- */
-function buildMergedRule(
-  first,
-  second,
-  intersection,
-  claimedIndices,
-  ruleCache,
-  ruleMeta
-) {
-  const receivingBlock = second.clone();
-  const firstSelectors = getMeta(first, ruleMeta).selectors;
-  const secondSelectors = getMeta(second, ruleMeta).selectors;
-
-  receivingBlock.selector = [...firstSelectors, ...secondSelectors].join();
-  receivingBlock.nodes = [];
-
-  /** @type {import('postcss').Container<import('postcss').ChildNode>} */ (
-    second.parent
-  ).insertBefore(second, receivingBlock);
-
-  const firstClone = first.clone({ selectors: firstSelectors });
-  const secondClone = second.clone({ selectors: secondSelectors });
-
-  /**
-   * @param {(decl: Declaration) => void} callback
-   * @this void
-   * @return {(decl: Declaration) => void}
-   */
-  function moveDecl(callback) {
-    return (decl) => {
-      if (indexOfDeclaration(intersection, decl) !== -1) {
-        callback.call(this, decl);
-      }
-    };
-  }
-  firstClone.walkDecls(
-    moveDecl(
-      /**
-       * @param {Declaration} decl
-       */
-      (decl) => {
-        decl.remove();
-        receivingBlock.append(decl);
-      }
-    )
-  );
-  // Remove exactly the declarations that were claimed: matching by value would
-  // also delete a duplicate that re-asserts the value later in the rule, after
-  // an overriding declaration that stays behind.
-  let laterIndex = 0;
-  secondClone.walkDecls((decl) => {
-    if (claimedIndices.has(laterIndex++)) {
-      decl.remove();
-    }
-  });
-
-  // Ensure original rules are flushed for accurate length comparison
-  if (ruleMeta) {
-    flush(first, ruleMeta);
-    flush(second, ruleMeta);
-  }
-
-  const merged = ruleLength(firstClone, receivingBlock, secondClone);
-  const original = ruleLength(first, second);
-  if (merged < original) {
-    first.replaceWith(firstClone);
-    second.replaceWith(secondClone);
-    for (const r of [firstClone, receivingBlock, secondClone]) {
-      if (r.nodes.length === 0) {
-        r.remove();
-      }
-    }
-    if (!secondClone.parent) {
-      ruleCache?.add(receivingBlock);
-      return receivingBlock;
-    }
-    ruleCache?.add(receivingBlock);
-    ruleCache?.add(secondClone);
-    ruleMeta?.delete(first);
-    ruleMeta?.delete(second);
-    return secondClone;
-  }
-
-  receivingBlock.remove();
-  return second;
+  return false;
 }
 
 /**
@@ -509,7 +116,8 @@ function buildMergedRule(
  * @param {Map<string, boolean>} compatibilityCache
  * @param {WeakSet<Rule>} ruleCache
  * @param {WeakMap<Rule, RuleMeta>} ruleMeta
- * @return {Rule} mergedRule
+ * @param {(rule: Rule, oldParent: import('postcss').Container, newParent: import('postcss').Container) => void} [onMove]
+ * @return {{rule: Rule, replacements: Rule[], replaced: Rule[], changed: Rule[], moved: boolean}}
  */
 function partialMerge(
   first,
@@ -517,7 +125,8 @@ function partialMerge(
   browsers,
   compatibilityCache,
   ruleCache,
-  ruleMeta
+  ruleMeta,
+  onMove
 ) {
   if (ruleMeta) {
     flush(first, ruleMeta);
@@ -526,7 +135,13 @@ function partialMerge(
   const metaSecond = getMeta(second, ruleMeta);
   let intersection = intersect(metaFirst.declarations, metaSecond.declarations);
   if (intersection.length === 0) {
-    return second;
+    return {
+      rule: second,
+      replacements: [],
+      replaced: [],
+      changed: [],
+      moved: false,
+    };
   }
   const mergedNext = mergeWithNextRule(
     first,
@@ -535,7 +150,9 @@ function partialMerge(
     browsers,
     compatibilityCache,
     ruleCache,
-    ruleMeta
+    ruleMeta,
+    canMerge,
+    onMove
   );
   const mergedFirst = mergedNext.first;
   const mergedSecond = mergedNext.second;
@@ -555,10 +172,16 @@ function partialMerge(
 
   if (intersection.length === 0) {
     // Nothing to merge
-    return mergedSecond;
+    return {
+      rule: mergedSecond,
+      replacements: [],
+      replaced: [],
+      changed: mergedNext.moved ? [mergedFirst, mergedSecond] : [],
+      moved: mergedNext.moved,
+    };
   }
 
-  return buildMergedRule(
+  const merged = buildMergedRule(
     mergedFirst,
     mergedSecond,
     intersection,
@@ -566,6 +189,12 @@ function partialMerge(
     ruleCache,
     ruleMeta
   );
+  return {
+    ...merged,
+    replaced: merged.replacements.length ? [mergedFirst, mergedSecond] : [],
+    changed: mergedNext.moved ? [mergedFirst, mergedSecond] : [],
+    moved: mergedNext.moved,
+  };
 }
 
 /**
@@ -573,98 +202,501 @@ function partialMerge(
  * @param {Map<string, boolean>} compatibilityCache
  * @param {WeakSet<Rule>} ruleCache
  * @param {WeakMap<Rule, RuleMeta>} ruleMeta
- * @return {{ merger: (rule: Rule) => void, clean: () => void }}
+ * @return {{ run: (root: import('postcss').Root) => void }}
  */
 function selectorMerger(browsers, compatibilityCache, ruleCache, ruleMeta) {
-  /** @type {Rule | null} */
-  let cache = null;
-  return {
-    merger(rule) {
-      // Prime the cache with the first rule, or alternately ensure that it is
-      // safe to merge both declarations before continuing
-      if (
-        !cache ||
-        !canMerge(
-          rule,
-          cache,
-          browsers,
-          compatibilityCache,
-          ruleCache,
-          ruleMeta
-        )
+  /** @typedef {RuleMeta & {selectorKey: string, contentKey: string, declarationIds: number[], declarationIdSet: Set<number>, previous: Rule | null, next: Rule | null, active: boolean, version: number, sourceOrder: number}} ActiveMeta */
+  /** @type {WeakMap<Rule, ActiveMeta>} */
+  const active = new WeakMap();
+  /** @type {Map<string, number>} */
+  const declarationIds = new Map();
+  let nextDeclarationId = 0;
+  let nextSourceOrder = 0;
+  /** @typedef {{first: Rule | null, last: Rule | null}} Boundary */
+  /** @type {WeakMap<import('postcss').Container, Boundary>} */
+  const boundaries = new WeakMap();
+
+  /** @param {Declaration} declaration */
+  function getDeclarationId(declaration) {
+    const key = `${declaration.prop}:${declaration.value}:${declaration.important}`;
+    let id = declarationIds.get(key);
+    if (id === undefined) {
+      id = nextDeclarationId++;
+      declarationIds.set(key, id);
+    }
+    return id;
+  }
+
+  /** @param {Rule} rule @param {number} [sourceOrder] */
+  function refresh(rule, sourceOrder) {
+    const previous = active.get(rule);
+    const base = getMeta(rule, ruleMeta);
+    const ids = base.declarations.map(getDeclarationId);
+    /** @type {ActiveMeta} */
+    const meta = Object.assign(base, {
+      selectorKey: base.selectors.join(','),
+      contentKey: `${base.selectors.join(',')}|${ids.join(',')}`,
+      declarationIds: ids,
+      declarationIdSet: new Set(ids),
+      previous: previous?.previous ?? null,
+      next: previous?.next ?? null,
+      active: true,
+      version: (previous?.version ?? 0) + 1,
+      sourceOrder: sourceOrder ?? previous?.sourceOrder ?? nextSourceOrder++,
+    });
+    active.set(rule, meta);
+    return meta;
+  }
+  /** @param {Rule} first @param {Rule} second */
+  function hasPossibleSharedDeclaration(first, second) {
+    const a = active.get(first);
+    const b = active.get(second);
+    if (!a?.active || !b?.active) return false;
+    // Empty rules and equivalent at-rule boundaries retain the legacy
+    // structural rewrites even though they cannot share a declaration.
+    const structuralRewrite =
+      (a.declarations.length === 0 && b.declarations.length === 0) ||
+      (first.parent !== second.parent && sameParent(first, second));
+    if (a.selectorKey === b.selectorKey || structuralRewrite) return true;
+    for (const id of a.declarationIds) {
+      if (b.declarationIdSet.has(id)) return true;
+    }
+    return false;
+  }
+  /** @param {Rule} first @param {Rule} second */
+  function estimatedBenefit(first, second) {
+    const a = active.get(first);
+    const b = active.get(second);
+    if (!a || !b) return 0;
+    if (a.selectorKey === b.selectorKey) {
+      return a.declarationIds.length + b.declarationIds.length;
+    }
+    let benefit = 0;
+    for (const id of a.declarationIds) {
+      if (b.declarationIdSet.has(id)) benefit++;
+    }
+    return benefit;
+  }
+  /** @param {Rule} rule */
+  function detach(rule) {
+    const meta = active.get(rule);
+    if (!meta?.active) return;
+    const { previous, next } = meta;
+    let container = getParent(rule);
+    for (; container; container = getParent(container)) {
+      const boundary = boundaries.get(container);
+      if (!boundary) continue;
+      if (boundary.first === rule) {
+        boundary.first = next && isDescendant(next, container) ? next : null;
+      }
+      if (boundary.last === rule) {
+        boundary.last =
+          previous && isDescendant(previous, container) ? previous : null;
+      }
+    }
+    if (previous) {
+      const previousMeta = active.get(previous);
+      if (previousMeta) previousMeta.next = next;
+    }
+    if (next) {
+      const nextMeta = active.get(next);
+      if (nextMeta) nextMeta.previous = previous;
+    }
+    meta.active = false;
+  }
+  /** @param {Rule[]} rules */
+  function captureBoundaries(rules) {
+    const captured = new Map();
+    for (const rule of rules) {
+      for (
+        let container = getParent(rule);
+        container;
+        container = getParent(container)
       ) {
-        if (cache) {
-          flush(cache, ruleMeta);
+        const boundary = boundaries.get(container);
+        if (boundary && !captured.has(container)) {
+          captured.set(container, {
+            first: boundary.first,
+            last: boundary.last,
+          });
         }
-        cache = rule;
-        return;
       }
-      // Ensure that we don't deduplicate the same rule; this is sometimes
-      // caused by a partial merge
-      if (cache === rule) {
-        cache = rule;
-        return;
+    }
+    return captured;
+  }
+  /**
+   * Repair the active order for a rule moved by mergeParents. The old and new
+   * ancestor paths are the only paths whose first/last descendant can change.
+   * @param {Rule} rule
+   * @param {import('postcss').Container} oldParent
+   * @param {import('postcss').Container} newParent
+   */
+  // eslint-disable-next-line complexity
+  function repairMove(rule, oldParent, newParent) {
+    const oldAncestors = [];
+    /** @type {import('postcss').Container<import('postcss').ChildNode> | undefined} */
+    let container = oldParent;
+    for (; container; container = getParent(container)) {
+      oldAncestors.push(container);
+    }
+    const newAncestors = [];
+    container = newParent;
+    for (; container; container = getParent(container)) {
+      newAncestors.push(container);
+    }
+
+    const meta = active.get(rule);
+    if (!meta?.active) return;
+    const { previous, next } = meta;
+    if (previous) {
+      const previousMeta = active.get(previous);
+      if (previousMeta) previousMeta.next = next;
+    }
+    if (next) {
+      const nextMeta = active.get(next);
+      if (nextMeta) nextMeta.previous = previous;
+    }
+
+    for (const ancestor of oldAncestors) {
+      const boundary = boundaries.get(ancestor);
+      if (!boundary) continue;
+      if (boundary.first === rule) {
+        boundary.first = next && isDescendant(next, ancestor) ? next : null;
       }
+      if (boundary.last === rule) {
+        boundary.last =
+          previous && isDescendant(previous, ancestor) ? previous : null;
+      }
+    }
 
-      // Parents merge: check if the rules have same parents, but not same parent nodes
-      mergeParents(cache, rule);
+    const destinationBoundary = boundaries.get(newParent);
+    const destinationLast = destinationBoundary?.last ?? null;
+    meta.previous = destinationLast;
+    meta.next = destinationLast
+      ? (active.get(destinationLast)?.next ?? null)
+      : null;
+    if (destinationLast) {
+      const destinationMeta = active.get(destinationLast);
+      if (destinationMeta) destinationMeta.next = rule;
+    }
+    if (meta.next) {
+      const nextMeta = active.get(meta.next);
+      if (nextMeta) nextMeta.previous = rule;
+    }
 
-      // Merge when declarations are exactly equal
-      // e.g. h1 { color: red } h2 { color: red }
-      if (
-        sameDeclarationsAndOrder(
-          getMeta(rule, ruleMeta).declarations,
-          getMeta(cache, ruleMeta).declarations
-        )
-      ) {
-        const metaRule = getMeta(rule, ruleMeta);
-        const metaCache = getMeta(cache, ruleMeta);
-        metaRule.selectors = [...metaCache.selectors, ...metaRule.selectors];
-        metaRule.dirty = true;
-        cache.remove();
-        ruleMeta?.delete(cache);
-        cache = rule;
-        ruleCache?.add(rule);
-        return;
+    for (const ancestor of newAncestors) {
+      const boundary = boundaries.get(ancestor);
+      if (!boundary) continue;
+      boundary.first ??= rule;
+      boundary.last = rule;
+    }
+  }
+  /** @param {import('postcss').Container<import('postcss').ChildNode>} container @param {{previous: Rule | null}} state */
+  function indexContainer(container, state) {
+    /** @type {Rule | null} */
+    let first = null;
+    /** @type {Rule | null} */
+    let last = null;
+    for (const node of container.nodes ?? []) {
+      if (node.type === 'rule') {
+        const rule = /** @type {Rule} */ (node);
+        const meta = refresh(rule);
+        meta.previous = state.previous;
+        if (state.previous) {
+          /** @type {ActiveMeta} */ (active.get(state.previous)).next = rule;
+        }
+        meta.next = null;
+        first ??= rule;
+        state.previous = rule;
+        last = rule;
+        indexContainer(rule, state);
+        const nested = boundaries.get(rule);
+        if (nested?.last) last = nested.last;
+        state.previous = last;
+        boundaries.set(rule, { first: rule, last });
+        continue;
       }
-      // Merge when both selectors are exactly equal
-      // e.g. a { color: blue } a { font-weight: bold }
-      if (
-        getMeta(cache, ruleMeta).selectors.join(',') ===
-        getMeta(rule, ruleMeta).selectors.join(',')
-      ) {
-        const cachedDecls = getMeta(cache, ruleMeta).declarations;
-        rule.walk((node) => {
-          if (
-            node.type === 'decl' &&
-            indexOfDeclaration(cachedDecls, node) !== -1
-          ) {
-            node.remove();
-            return;
+      if ('nodes' in node && node.nodes) {
+        indexContainer(
+          /** @type {import('postcss').Container} */ (node),
+          state
+        );
+        const nested = boundaries.get(
+          /** @type {import('postcss').Container} */ (node)
+        );
+        if (nested?.first) {
+          if (!first) first = nested.first;
+          last = nested.last;
+        }
+      }
+    }
+    boundaries.set(container, { first, last });
+  }
+  /** @param {import('postcss').Root} root */
+  function seed(root) {
+    // indexContainer establishes links as it descends, then exposes the root
+    // entry point used to seed candidates.
+    indexContainer(root, { previous: null });
+    return boundaries.get(root)?.first ?? null;
+  }
+  return {
+    // Keep the heap scheduling and rewrite repair together for the AST mutation.
+    // eslint-disable-next-line complexity
+    run(root) {
+      /** @typedef {{first: Rule, second: Rule, firstVersion: number, secondVersion: number, benefit: number, firstSourceOrder: number, contentKey: string}} Candidate */
+      /** @type {Candidate[]} */
+      let candidates = [];
+      let needsGlobalReseed = false;
+      /** @param {Candidate} a @param {Candidate} b */
+      // The comparator stays local with the heap's candidate type and ordering contract.
+      // eslint-disable-next-line unicorn/consistent-function-scoping
+      const comesBefore = (a, b) => {
+        if (a.benefit !== b.benefit) return a.benefit > b.benefit;
+        if (a.firstSourceOrder !== b.firstSourceOrder) {
+          return a.firstSourceOrder < b.firstSourceOrder;
+        }
+        return a.contentKey < b.contentKey;
+      };
+      /** @param {Candidate} candidate */
+      const pushCandidate = (candidate) => {
+        let index = candidates.length;
+        candidates.push(candidate);
+        while (index > 0) {
+          const parent = Math.floor((index - 1) / 2);
+          if (comesBefore(candidates[parent], candidate)) break;
+          candidates[index] = candidates[parent];
+          index = parent;
+        }
+        candidates[index] = candidate;
+      };
+      const popCandidate = () => {
+        const candidate = candidates[0];
+        const last = candidates.pop();
+        if (last && candidates.length) {
+          let index = 0;
+          while (true) {
+            const left = index * 2 + 1;
+            if (left >= candidates.length) break;
+            let child = left;
+            const right = left + 1;
+            if (
+              right < candidates.length &&
+              comesBefore(candidates[right], candidates[left])
+            )
+              child = right;
+            if (!comesBefore(candidates[child], last)) break;
+            candidates[index] = candidates[child];
+            index = child;
           }
-          /** @type {Rule} */ (cache).append(node);
+          candidates[index] = last;
+        }
+        return candidate;
+      };
+      /** @param {Rule | null} first @param {Rule | null} second */
+      const enqueue = (first, second) => {
+        if (!first || !second || !hasPossibleSharedDeclaration(first, second)) {
+          return;
+        }
+        const firstMeta = active.get(first);
+        const secondMeta = active.get(second);
+        if (!firstMeta || !secondMeta) return;
+        pushCandidate({
+          first,
+          second,
+          firstVersion: firstMeta.version,
+          secondVersion: secondMeta.version,
+          benefit: estimatedBenefit(first, second),
+          firstSourceOrder: firstMeta.sourceOrder,
+          contentKey: `${firstMeta.contentKey}|${secondMeta.contentKey}`,
         });
-        getMeta(cache, ruleMeta).declarations = getDecls(cache);
-        rule.remove();
-        ruleMeta?.delete(rule);
-        return;
-      }
-      // Partial merge: check if the rule contains a subset of the last; if
-      // so create a joined selector with the subset, if smaller.
-      cache = partialMerge(
-        cache,
-        rule,
-        browsers,
-        compatibilityCache,
-        ruleCache,
-        ruleMeta
-      );
-    },
-    // Flushes any remaining rule in the cache to avoid memory leaks.
-    clean() {
-      if (cache) {
-        flush(cache, ruleMeta);
+      };
+      /** @param {Rule} rule */
+      const enqueueNeighbors = (rule) => {
+        const meta = active.get(rule);
+        if (!meta?.active) return;
+        enqueue(meta.previous, rule);
+        enqueue(rule, meta.next);
+      };
+      const reseedCandidates = () => {
+        candidates = [];
+        const initialRule = seed(root);
+        for (
+          let rule = initialRule;
+          rule;
+          rule = active.get(rule)?.next ?? null
+        ) {
+          enqueue(rule, active.get(rule)?.next ?? null);
+        }
+      };
+      reseedCandidates();
+      /** @param {Rule} first @param {Rule} second */
+      const checkedCanMerge = (first, second) => {
+        return canMerge(
+          first,
+          second,
+          browsers,
+          compatibilityCache,
+          ruleCache,
+          ruleMeta
+        );
+      };
+      while (candidates.length || needsGlobalReseed) {
+        if (!candidates.length) {
+          needsGlobalReseed = false;
+          reseedCandidates();
+          if (!candidates.length) break;
+        }
+        const candidate = popCandidate();
+        const first = candidate.first;
+        const second = candidate.second;
+        const firstMeta = active.get(first);
+        const secondMeta = active.get(second);
+        if (
+          !firstMeta?.active ||
+          !secondMeta?.active ||
+          firstMeta.next !== second ||
+          firstMeta.version !== candidate.firstVersion ||
+          secondMeta.version !== candidate.secondVersion
+        )
+          continue;
+        if (!checkedCanMerge(first, second)) continue;
+        // Equivalent at-rule moves preserve depth-first leaf-rule order.
+        const oldParent = second.parent;
+        const newParent = first.parent;
+        const moved = mergeParents(first, second);
+        if (moved && oldParent && newParent) {
+          repairMove(second, oldParent, newParent);
+        }
+        if (
+          sameDeclarationsAndOrder(
+            getMeta(second, ruleMeta).declarations,
+            getMeta(first, ruleMeta).declarations
+          )
+        ) {
+          const metaSecond = getMeta(second, ruleMeta);
+          metaSecond.selectors = [
+            ...getMeta(first, ruleMeta).selectors,
+            ...metaSecond.selectors,
+          ];
+          metaSecond.dirty = true;
+          flush(second, ruleMeta);
+          detach(first);
+          first.remove();
+          ruleMeta?.delete(first);
+          refresh(second);
+          ruleCache?.add(second);
+          enqueueNeighbors(second);
+          continue;
+        }
+        if (
+          getMeta(first, ruleMeta).selectors.join(',') ===
+          getMeta(second, ruleMeta).selectors.join(',')
+        ) {
+          const cachedDecls = getMeta(first, ruleMeta).declarations;
+          second.walk((node) => {
+            if (
+              node.type === 'decl' &&
+              indexOfDeclaration(cachedDecls, node) !== -1
+            )
+              node.remove();
+            else first.append(node);
+          });
+          getMeta(first, ruleMeta).declarations = getDecls(first);
+          detach(second);
+          second.remove();
+          ruleMeta?.delete(second);
+          refresh(first);
+          enqueueNeighbors(first);
+          continue;
+        }
+        const replacedRules = [first, second];
+        const capturedBoundaries = captureBoundaries(replacedRules);
+        const outcome = partialMerge(
+          first,
+          second,
+          browsers,
+          compatibilityCache,
+          ruleCache,
+          ruleMeta,
+          (rule, movedFrom, movedTo) => repairMove(rule, movedFrom, movedTo)
+        );
+        if (outcome.replacements.length) {
+          const firstWasBoundary =
+            !outcome.moved &&
+            outcome.replaced.some((rule) =>
+              [...capturedBoundaries.values()].some((b) => b.first === rule)
+            );
+          const lastWasBoundary =
+            !outcome.moved &&
+            outcome.replaced.some((rule) =>
+              [...capturedBoundaries.values()].some((b) => b.last === rule)
+            );
+          const previous = active.get(outcome.replaced[0])?.previous ?? null;
+          const lastReplaced = /** @type {Rule} */ (outcome.replaced.at(-1));
+          const next = active.get(lastReplaced)?.next ?? null;
+          const sourceOrder = active.get(outcome.replaced[0])?.sourceOrder;
+          for (const rule of outcome.replaced) {
+            detach(rule);
+            ruleMeta?.delete(rule);
+          }
+          let prior = previous;
+          for (const replacement of outcome.replacements) {
+            const meta = refresh(replacement, sourceOrder);
+            meta.previous = prior;
+            if (prior) {
+              /** @type {ActiveMeta} */ (active.get(prior)).next = replacement;
+            }
+            prior = replacement;
+          }
+          if (prior) {
+            /** @type {ActiveMeta} */ (active.get(prior)).next = next;
+          }
+          if (next) {
+            /** @type {ActiveMeta} */ (active.get(next)).previous = prior;
+          }
+          if (firstWasBoundary && outcome.replacements[0]?.parent) {
+            for (
+              let container = getParent(outcome.replacements[0]);
+              container;
+              container = getParent(container)
+            ) {
+              const boundary = boundaries.get(container);
+              if (boundary) boundary.first = outcome.replacements[0];
+            }
+          }
+          const lastReplacement = /** @type {Rule} */ (
+            outcome.replacements.at(-1)
+          );
+          if (lastWasBoundary && lastReplacement.parent) {
+            for (
+              let container = getParent(lastReplacement);
+              container;
+              container = getParent(container)
+            ) {
+              const boundary = boundaries.get(container);
+              if (boundary) boundary.last = lastReplacement;
+            }
+          }
+          if (outcome.moved) {
+            // repairMove keeps the current queue safe to drain. Rebuild once
+            // afterwards so a cascade of independent moves does not rescan
+            // the complete rule list after every boundary change.
+            needsGlobalReseed = true;
+          }
+          for (const replacement of outcome.replacements) {
+            enqueueNeighbors(replacement);
+          }
+          enqueue(previous, outcome.replacements[0] ?? next);
+          enqueue(outcome.replacements.at(-1) ?? previous, next);
+        } else if (moved || outcome.moved) {
+          for (const changed of [first, second, ...outcome.changed]) {
+            refresh(changed);
+            enqueueNeighbors(changed);
+          }
+          needsGlobalReseed = true;
+        }
       }
+      root.walkRules((rule) => flush(rule, ruleMeta));
     },
   };
 }
@@ -701,14 +733,13 @@ function pluginCreator(opts = {}) {
          * @param {import('postcss').Root} css
          */
         OnceExit(css) {
-          const { merger, clean } = selectorMerger(
+          const merger = selectorMerger(
             browsers,
             compatibilityCache,
             ruleCache,
             ruleMeta
           );
-          css.walkRules(merger);
-          clean();
+          merger.run(css);
         },
       };
     },