@thejaredwilcurt/csslop 0.0.11 → 0.0.13

package/package.json

@@ -2,7 +2,7 @@
   "name": "@thejaredwilcurt/csslop",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Experimental CSS minification",
   "scripts": {
     "prestart": "node ./scripts/prestart.js",
@@ -26,7 +26,7 @@
   "devDependencies": {
     "@codemirror/autocomplete": "^6.20.3",
     "@codemirror/lang-css": "^6.3.1",
-    "@codemirror/view": "^6.43.2",
+    "@codemirror/view": "^6.43.6",
     "@eslint/js": "^10.0.1",
     "@stylistic/eslint-plugin": "^5.10.0",
     "codemirror": "^6.0.2",
@@ -36,7 +36,7 @@
     "eslint-config-tjw-import-x": "^1.0.1",
     "eslint-config-tjw-jsdoc": "^2.0.1",
     "eslint-plugin-import-x": "^4.17.0",
-    "eslint-plugin-jsdoc": "^63.0.7",
+    "eslint-plugin-jsdoc": "^63.0.12",
     "fflate": "^0.8.3",
     "globals": "^17.7.0",
     "pretty-ms": "^9.3.0",

package/src/declarations/config.js

@@ -20,7 +20,8 @@ const shorthandMap = {
   'border-right': ['border-right-width', 'border-right-style', 'border-right-color'],
   'border-bottom': ['border-bottom-width', 'border-bottom-style', 'border-bottom-color'],
   'border-left': ['border-left-width', 'border-left-style', 'border-left-color'],
-  background: ['background-color', 'background-image', 'background-repeat', 'background-position', 'background-attachment'],
+  'background-position': ['background-position-x', 'background-position-y'],
+  background: ['background-color', 'background-image', 'background-repeat', 'background-position', 'background-position-x', 'background-position-y', 'background-attachment', 'background-size', 'background-origin', 'background-clip'],
   'text-decoration': ['text-decoration-line', 'text-decoration-style', 'text-decoration-color'],
   'place-items': ['align-items', 'justify-items'],
   'place-content': ['align-content', 'justify-content'],

package/src/declarations/process.js

@@ -71,6 +71,13 @@ function getMergeProps (shorthand, longhands, declarations) {
     }
     return null;
   }
+  if (shorthand === 'background-position') {
+    const hasBothAxes = presentLonghands.includes('background-position-x') && presentLonghands.includes('background-position-y');
+    if (hasBothAxes) {
+      return presentLonghands;
+    }
+    return null;
+  }
   if (shorthand === 'background') {
     const hasBackgroundProp = presentLonghands.includes('background-color') || presentLonghands.includes('background-image');
     if (hasBackgroundProp) {
@@ -169,6 +176,316 @@ function canMergeVarValue (value, context) {
   });
 }
 
+/**
+ * Resolves the background position from a value map. Prefers the combined
+ * `background-position` property if present, otherwise combines
+ * `background-position-x` and `background-position-y` into a single value.
+ *
+ * @param  {Map}         valueMap  A map of property names to their minified values.
+ * @return {string|null}           The resolved position string, or null if no position data is available.
+ */
+function resolveBackgroundPosition (valueMap) {
+  const position = valueMap.get('background-position');
+  if (position) {
+    return position;
+  }
+  const positionX = valueMap.get('background-position-x');
+  const positionY = valueMap.get('background-position-y');
+  if (positionX && positionY) {
+    return positionX + ' ' + positionY;
+  }
+  return null;
+}
+
+const BACKGROUND_POSITION_KEYWORDS = new Set(['left', 'center', 'right', 'top', 'bottom']);
+const BACKGROUND_REPEAT_KEYWORDS = new Set(['repeat', 'no-repeat', 'repeat-x', 'repeat-y', 'space', 'round']);
+const BACKGROUND_ATTACHMENT_KEYWORDS = new Set(['scroll', 'fixed', 'local']);
+const BACKGROUND_BOX_KEYWORDS = new Set(['border-box', 'padding-box', 'content-box']);
+
+/**
+ * Determines whether a token is a background image component such as `none`,
+ * `url(...)`, or an image-producing function like `linear-gradient(...)`.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a background image token.
+ */
+function isBackgroundImageToken (token) {
+  if (token === 'none' || token.startsWith('url(')) {
+    return true;
+  }
+  if (!token.endsWith(')')) {
+    return false;
+  }
+  const functionNameMatch = token.match(/^([a-z-]+)\(/i);
+  if (!functionNameMatch) {
+    return false;
+  }
+  const functionName = functionNameMatch[1].toLowerCase();
+  return !['calc', 'min', 'max', 'clamp', 'var', 'env', 'rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color'].includes(functionName);
+}
+
+/**
+ * Determines whether a token can participate in a background-position value.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a valid background-position token.
+ */
+function isBackgroundPositionToken (token) {
+  const lowercaseToken = token.toLowerCase();
+  if (BACKGROUND_POSITION_KEYWORDS.has(lowercaseToken)) {
+    return true;
+  }
+  if (/^[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?$/i.test(token)) {
+    return true;
+  }
+  return /^(?:calc|min|max|clamp|var|env)\(/i.test(token);
+}
+
+/**
+ * Determines whether a token is a background color component after excluding
+ * known image, position, repeat, attachment, and box tokens.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a background color token.
+ */
+function isBackgroundColorToken (token) {
+  if (token === '/' || isBackgroundImageToken(token) || isBackgroundPositionToken(token)) {
+    return false;
+  }
+  const lowercaseToken = token.toLowerCase();
+  if (BACKGROUND_REPEAT_KEYWORDS.has(lowercaseToken) || BACKGROUND_ATTACHMENT_KEYWORDS.has(lowercaseToken) || BACKGROUND_BOX_KEYWORDS.has(lowercaseToken)) {
+    return false;
+  }
+  return /^#/i.test(token) || /^[a-z-]+$/i.test(token) || /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\(/i.test(token);
+}
+
+/**
+ * Splits a token like `linear-gradient(...)100%` into separate image and
+ * position tokens when the function output is immediately followed by a
+ * background-position token.
+ *
+ * @param  {string} token  The token to inspect.
+ * @return {Array}         The original token, or separate image/position tokens.
+ */
+function splitAttachedBackgroundImageToken (token) {
+  const lastCloseParenthesis = token.lastIndexOf(')');
+  if (lastCloseParenthesis === -1 || lastCloseParenthesis === token.length - 1) {
+    return [token];
+  }
+  const imageToken = token.slice(0, lastCloseParenthesis + 1);
+  const followingToken = token.slice(lastCloseParenthesis + 1);
+  if (!isBackgroundImageToken(imageToken) || !isBackgroundPositionToken(followingToken)) {
+    return [token];
+  }
+  return [imageToken, followingToken];
+}
+
+/**
+ * Splits a single-layer background shorthand into top-level tokens while
+ * respecting nested parentheses and preserving `/` as its own token.
+ *
+ * @param  {string} value  The background shorthand value.
+ * @return {Array}         The extracted top-level tokens.
+ */
+function splitBackgroundTokens (value) {
+  const tokens = [];
+  let currentToken = '';
+  let parenthesisDepth = 0;
+
+  for (const character of value) {
+    if (character === '(') {
+      parenthesisDepth++;
+    } else if (character === ')') {
+      parenthesisDepth--;
+    }
+
+    if (parenthesisDepth === 0 && character === '/') {
+      if (currentToken) {
+        tokens.push(currentToken);
+        currentToken = '';
+      }
+      tokens.push('/');
+      continue;
+    }
+
+    if (parenthesisDepth === 0 && /\s/.test(character)) {
+      if (currentToken) {
+        tokens.push(currentToken);
+        currentToken = '';
+      }
+      continue;
+    }
+
+    currentToken += character;
+  }
+
+  if (currentToken) {
+    tokens.push(currentToken);
+  }
+
+  const normalizedTokens = [];
+  for (const token of tokens) {
+    normalizedTokens.push(...splitAttachedBackgroundImageToken(token));
+  }
+  return normalizedTokens;
+}
+
+/**
+ * Extracts the simple image/color base from an existing background shorthand.
+ * Returns null for shorthands that already contain size, position, or any
+ * token that cannot be safely reconstructed by the background builder.
+ *
+ * @param  {string}   value  The background shorthand value.
+ * @return {Map|null}        A component map for safe reconstruction, or null.
+ */
+function extractSimpleBackgroundBase (value) {
+  const tokens = splitBackgroundTokens(value);
+  const componentMap = new Map();
+
+  for (const token of tokens) {
+    if (token === '/') {
+      return null;
+    }
+    if (isBackgroundImageToken(token)) {
+      if (componentMap.has('background-image')) {
+        return null;
+      }
+      componentMap.set('background-image', token);
+      continue;
+    }
+    if (isBackgroundColorToken(token)) {
+      if (componentMap.has('background-color')) {
+        return null;
+      }
+      componentMap.set('background-color', token);
+      continue;
+    }
+    return null;
+  }
+
+  return componentMap;
+}
+
+/**
+ * Serializes normalized background components into a minified background
+ * shorthand value while omitting default sub-values.
+ *
+ * @param  {Map}         valueMap         The normalized background component map.
+ * @param  {string}      importantSuffix  A trailing `!important` suffix, if needed.
+ * @return {string|null}                  The minified background shorthand, or null.
+ */
+function buildBackgroundShorthandValue (valueMap, importantSuffix) {
+  const color = valueMap.get('background-color');
+  const image = valueMap.get('background-image');
+  const repeat = valueMap.get('background-repeat');
+  const attachment = valueMap.get('background-attachment');
+  const size = valueMap.get('background-size');
+  const origin = valueMap.get('background-origin');
+  const clip = valueMap.get('background-clip');
+  const position = resolveBackgroundPosition(valueMap);
+
+  const result = [];
+  if (color && color !== 'transparent') {
+    result.push(color);
+  }
+  if (image && image !== 'none') {
+    result.push(image);
+  }
+  if (position && position !== '0 0' && position !== '0% 0%') {
+    result.push(position);
+  }
+  if (size && size !== 'auto') {
+    if (position && position !== '0 0' && position !== '0% 0%') {
+      result.push('/' + size);
+    } else {
+      result.push('0 0/' + size);
+    }
+  }
+  if (repeat && repeat !== 'repeat') {
+    result.push(repeat);
+  }
+  if (attachment && attachment !== 'scroll') {
+    result.push(attachment);
+  }
+  const hasNonDefaultOrigin = origin && origin !== 'padding-box';
+  const hasNonDefaultClip = clip && clip !== 'border-box';
+  if (hasNonDefaultOrigin && hasNonDefaultClip) {
+    result.push(origin);
+    result.push(clip);
+  } else if (hasNonDefaultOrigin || hasNonDefaultClip) {
+    if (origin) {
+      result.push(origin);
+    }
+    if (clip) {
+      result.push(clip);
+    }
+  }
+  if (!result.length) {
+    return null;
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Merges later background longhands into an earlier simple background shorthand
+ * when their combined value can be reconstructed without changing semantics.
+ *
+ * @param  {Array} declarations  The declarations in source order.
+ * @return {Array}               The updated declarations with absorbed longhands.
+ */
+function absorbBackgroundLonghandsIntoShorthand (declarations) {
+  const backgroundIndex = declarations.findIndex((declaration) => {
+    return declaration.property === 'background';
+  });
+  if (backgroundIndex === -1) {
+    return declarations;
+  }
+
+  const backgroundDeclaration = declarations[backgroundIndex];
+  const backgroundValue = minifyValue(backgroundDeclaration);
+  const backgroundIsImportant = backgroundValue.includes('!important');
+  const simpleBase = extractSimpleBackgroundBase(backgroundValue.replace('!important', '').trim());
+  if (!simpleBase) {
+    return declarations;
+  }
+
+  const absorbableProperties = new Set(shorthandMap.background.filter((property) => {
+    return property !== 'background';
+  }));
+  const relevantDeclarations = declarations.filter((declaration, index) => {
+    return index > backgroundIndex && absorbableProperties.has(declaration.property);
+  });
+  if (!relevantDeclarations.length) {
+    return declarations;
+  }
+
+  const sharesImportance = relevantDeclarations.every((declaration) => {
+    return minifyValue(declaration).includes('!important') === backgroundIsImportant;
+  });
+  if (!sharesImportance) {
+    return declarations;
+  }
+
+  for (const declaration of relevantDeclarations) {
+    simpleBase.set(declaration.property, minifyValue(declaration).replace('!important', '').trim());
+  }
+
+  const mergedValue = buildBackgroundShorthandValue(simpleBase, backgroundIsImportant ? '!important' : '');
+  if (!mergedValue) {
+    return declarations;
+  }
+
+  return declarations.flatMap((declaration, index) => {
+    if (index === backgroundIndex) {
+      return [{ ...declaration, value: mergedValue }];
+    }
+    if (index > backgroundIndex && absorbableProperties.has(declaration.property)) {
+      return [];
+    }
+    return [declaration];
+  });
+}
+
 /**
  * Try to merge longhand properties into a shorthand.
  *
@@ -307,32 +624,17 @@ function tryMergeToShorthand (properties, declarations, shorthandName = '', cont
     return result.join(' ') + importantSuffix;
   }
 
-  if (shorthandName === 'background') {
-    const color = valueMap.get('background-color');
-    const image = valueMap.get('background-image');
-    const repeat = valueMap.get('background-repeat');
-    const position = valueMap.get('background-position');
-    const attachment = valueMap.get('background-attachment');
-    const result = [];
-    if (color && color !== 'transparent') {
-      result.push(color);
-    }
-    if (image && image !== 'none') {
-      result.push(image);
-    }
-    if (position && position !== '0 0' && position !== '0% 0%') {
-      result.push(position);
-    }
-    if (repeat && repeat !== 'repeat') {
-      result.push(repeat);
-    }
-    if (attachment && attachment !== 'scroll') {
-      result.push(attachment);
-    }
-    if (!result.length) {
+  if (shorthandName === 'background-position') {
+    const positionX = valueMap.get('background-position-x');
+    const positionY = valueMap.get('background-position-y');
+    if (!positionX || !positionY) {
       return null;
     }
-    return result.join(' ') + importantSuffix;
+    return positionX + ' ' + positionY + importantSuffix;
+  }
+
+  if (shorthandName === 'background') {
+    return buildBackgroundShorthandValue(valueMap, importantSuffix);
   }
 
   if (shorthandName === 'mask') {
@@ -595,6 +897,7 @@ function processDeclarations (declarations, context) {
   result = result.filter((declaration) => {
     return !propertiesToRemove.has(declaration.property);
   });
+  result = absorbBackgroundLonghandsIntoShorthand(result);
 
   // Try to merge remaining longhands into shorthands
   let changed = true;
@@ -654,10 +957,34 @@ function processDeclarations (declarations, context) {
     }
 
     if (newDeclarations.length) {
+      // Filter out intermediate shorthands whose longhands are entirely
+      // consumed by a higher-level shorthand created in the same iteration.
+      // For example, background-position (x + y) is redundant when
+      // background already consumed those same longhands.
+      const filteredDeclarations = newDeclarations.filter((declaration) => {
+        const longhands = shorthandMap[declaration.property];
+        if (!longhands) {
+          return true;
+        }
+        const isSubsumedByOtherShorthand = newDeclarations.some((other) => {
+          if (other === declaration) {
+            return false;
+          }
+          const otherLonghands = shorthandMap[other.property];
+          if (!otherLonghands) {
+            return false;
+          }
+          return longhands.every((longhand) => {
+            return otherLonghands.includes(longhand);
+          });
+        });
+        return !isSubsumedByOtherShorthand;
+      });
+
       result = result.filter((declaration) => {
         return !mergedProperties.has(declaration.property);
       });
-      result = [...result, ...newDeclarations];
+      result = [...result, ...filteredDeclarations];
       changed = true;
     }
   }

package/src/rules/optimize.js

@@ -456,8 +456,7 @@ function mergeSelectorRules (rules) {
     if (rule.type === 'rule') {
       const selectorKey = rule.selectors ?
         rule.selectors.map((selector) => {
-          // Normalize selector whitespace for consistent comparison
-          return selector.trim().replace(/\s+/g, ' ');
+          return normalizeSelector(selector);
         }).sort().join(',') :
         '';
       if (selectorKey && selectorMap.has(selectorKey)) {
@@ -533,7 +532,12 @@ function mergeLayerRules (rules, mergeSelectorRules) {
  * @return {string}           The normalized selector.
  */
 function normalizeSelector (selector) {
-  return selector.trim().replace(/\s+/g, ' ');
+  return selector
+    .trim()
+    .replace(/\s+/g, ' ')
+    // Convert double-colon ::before/::after to single-colon legacy form
+    .replace(/::before\b/g, ':before')
+    .replace(/::after\b/g, ':after');
 }
 
 /**

package/src/value/gradients.js

@@ -2,6 +2,11 @@
  * @file Parses and minifies CSS gradient function calls by splitting arguments, normalizing default directions, and removing redundant stop positions.
  */
 
+import {
+  parseHex,
+  shortestColor
+} from './colors.js';
+
 /**
  * Splits a gradient function's argument string at top-level commas, correctly handling nested parentheses.
  *
@@ -32,7 +37,299 @@ function splitGradientArgs (argumentString) {
 }
 
 /**
- * Optimizes gradient arguments by removing default direction or shape keywords and trimming redundant 0% or 100% stop positions from the first and last stops.
+ * Checks whether a string is a valid gradient stop position consisting of one
+ * or two numeric tokens with optional CSS units.
+ *
+ * @param  {string}  positionText  The potential stop position text.
+ * @return {boolean}               Whether the text is a valid stop position.
+ */
+function isGradientStopPosition (positionText) {
+  // Match one or two numeric stop-position tokens, such as `50%`, `10px`, or `0 50%`.
+  return /^[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?(?:\s+[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?)?$/i.test(positionText);
+}
+
+/**
+ * Splits a hex color stop that has an attached position with no separating
+ * whitespace back into distinct color and position parts.
+ *
+ * @param  {string}      stop  The raw gradient stop text.
+ * @return {object|null}       Parsed `color` and `position` parts, or null.
+ */
+function splitAttachedHexColorStop (stop) {
+  if (!stop.startsWith('#')) {
+    return null;
+  }
+
+  const hexLengths = [8, 6, 4, 3];
+  for (const hexLength of hexLengths) {
+    const colorLength = hexLength + 1;
+    if (stop.length <= colorLength) {
+      continue;
+    }
+
+    const colorCandidate = stop.slice(0, colorLength);
+    const positionCandidate = stop.slice(colorLength).trim();
+    const hexDigits = colorCandidate.slice(1);
+    const isHexColor = hexDigits.length === hexLength && /^[0-9a-f]+$/i.test(hexDigits);
+    if (!isHexColor || !isGradientStopPosition(positionCandidate)) {
+      continue;
+    }
+
+    return {
+      color: colorCandidate,
+      position: positionCandidate
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Splits a function-based color stop that has an attached position with no
+ * separating whitespace back into distinct color and position parts.
+ *
+ * @param  {string}      stop  The raw gradient stop text.
+ * @return {object|null}       Parsed `color` and `position` parts, or null.
+ */
+function splitAttachedFunctionColorStop (stop) {
+  const lastCloseParenthesis = stop.lastIndexOf(')');
+  if (lastCloseParenthesis === -1 || lastCloseParenthesis === stop.length - 1) {
+    return null;
+  }
+
+  const colorCandidate = stop.slice(0, lastCloseParenthesis + 1).trim();
+  const positionCandidate = stop.slice(lastCloseParenthesis + 1).trim();
+  if (!isGradientStopPosition(positionCandidate)) {
+    return null;
+  }
+
+  return {
+    color: colorCandidate,
+    position: positionCandidate
+  };
+}
+
+/**
+ * Normalizes a gradient stop color token to the same shortest representation
+ * used by the general value minifier so equivalent adjacent stops can merge.
+ *
+ * @param  {string} colorToken  The parsed stop color token.
+ * @return {string}             The normalized color token.
+ */
+function normalizeStopColorToken (colorToken) {
+  if (!colorToken.startsWith('#')) {
+    return colorToken;
+  }
+
+  const channels = parseHex(colorToken);
+  if (!channels) {
+    return colorToken;
+  }
+
+  return shortestColor(channels[0], channels[1], channels[2], channels[3]);
+}
+
+/**
+ * Splits a gradient color stop into its color value and optional position.
+ * The position is the trailing percentage/length token(s), while the color
+ * is everything before it. Handles colors with parentheses like rgb() and hsl().
+ *
+ * @param  {string} stop  A single gradient color stop string (e.g. "red 50%").
+ * @return {object}       An object with `color` and `position` string properties.
+ */
+function parseColorStop (stop) {
+  const trimmed = stop.trim();
+  // Match a trailing position: one or two values that are numbers with optional units
+  // like "50%", "10px", or "0". Captures the last position token(s) after the color.
+  const positionMatch = trimmed.match(/^(.+?)\s+((?:\d+(?:\.\d+)?(?:%|[a-z]+)?\s*){1,2})$/i);
+  if (positionMatch) {
+    return {
+      color: positionMatch[1].trim(),
+      position: positionMatch[2].trim()
+    };
+  }
+  const attachedHexStop = splitAttachedHexColorStop(trimmed);
+  if (attachedHexStop) {
+    return attachedHexStop;
+  }
+  const attachedFunctionStop = splitAttachedFunctionColorStop(trimmed);
+  if (attachedFunctionStop) {
+    return attachedFunctionStop;
+  }
+  return {
+    color: trimmed,
+    position: null
+  };
+}
+
+/**
+ * Splits a stop position into individual start and end tokens.
+ *
+ * @param  {string|null} position  The raw stop position text.
+ * @return {Array}                 The normalized position tokens.
+ */
+function splitStopPositionTokens (position) {
+  if (position === null) {
+    return [];
+  }
+
+  return position.split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Serializes a color stop from its color and normalized position tokens.
+ *
+ * @param  {string} color           The normalized stop color.
+ * @param  {Array}  positionTokens  The normalized stop positions.
+ * @return {string}                 The serialized color stop.
+ */
+function serializeColorStop (color, positionTokens) {
+  if (positionTokens.length === 0) {
+    return color;
+  }
+
+  return color + ' ' + positionTokens.join(' ');
+}
+
+/**
+ * Merges consecutive stops with the same color into a single logical stop.
+ *
+ * @param  {Array}  group  The adjacent parsed stops for one color.
+ * @return {object}        The merged stop data.
+ */
+function mergeIdenticalStopGroup (group) {
+  const firstStop = group[0];
+  const lastStop = group[group.length - 1];
+  const firstPositionTokens = splitStopPositionTokens(firstStop.position);
+  const lastPositionTokens = splitStopPositionTokens(lastStop.position);
+
+  let positionTokens;
+  if (group.length === 1) {
+    positionTokens = firstPositionTokens;
+  } else {
+    const mergedTokens = [];
+    const startPosition = firstPositionTokens[0] || null;
+    const endPosition = lastPositionTokens[lastPositionTokens.length - 1] || null;
+
+    if (startPosition !== null) {
+      mergedTokens.push(startPosition);
+    }
+    if (endPosition !== null && endPosition !== startPosition) {
+      mergedTokens.push(endPosition);
+    }
+
+    positionTokens = mergedTokens;
+  }
+
+  return {
+    color: firstStop.color,
+    effectiveEndPosition: lastPositionTokens[lastPositionTokens.length - 1] || null,
+    positionTokens
+  };
+}
+
+/**
+ * Removes implied edge positions and rewrites repeated starts as `0`.
+ *
+ * @param  {Array} mergedStops  The merged stops to normalize.
+ * @return {Array}              The serialized normalized stops.
+ */
+function normalizeBoundaryPositionTokens (mergedStops) {
+  const result = [];
+  let previousEndPosition = null;
+
+  for (let stopIndex = 0; stopIndex < mergedStops.length; stopIndex++) {
+    const stop = mergedStops[stopIndex];
+    const isFirstStop = stopIndex === 0;
+    const isLastStop = stopIndex === mergedStops.length - 1;
+    const positionTokens = [...stop.positionTokens];
+
+    if (isFirstStop && positionTokens[0] === '0%') {
+      positionTokens.shift();
+    }
+    if (isLastStop && positionTokens[positionTokens.length - 1] === '100%') {
+      positionTokens.pop();
+    }
+    if (positionTokens.length > 0 && positionTokens[0] === previousEndPosition) {
+      positionTokens[0] = '0';
+    }
+
+    previousEndPosition = stop.effectiveEndPosition;
+    result.push(serializeColorStop(stop.color, positionTokens));
+  }
+
+  return result;
+}
+
+/**
+ * Serializes a parsed gradient stop back into normalized CSS text, ensuring a
+ * separating space is preserved when a stop position is present.
+ *
+ * @param  {string} stop  The raw gradient stop string.
+ * @return {string}       The normalized gradient stop string.
+ */
+function normalizeColorStop (stop) {
+  const parsedStop = parseColorStop(stop);
+  const normalizedColor = normalizeStopColorToken(parsedStop.color);
+  if (parsedStop.position === null) {
+    return normalizedColor;
+  }
+
+  return normalizedColor + ' ' + parsedStop.position;
+}
+
+/**
+ * Groups consecutive gradient stops that share the same color value into
+ * arrays. Each group contains one or more stops with an identical color.
+ *
+ * @param  {Array} stops  An array of parsed stop objects with `color` and `position`.
+ * @return {Array}        An array of groups, each being an array of stop objects with the same color.
+ */
+function groupConsecutiveIdenticalStops (stops) {
+  const groups = [];
+  let currentGroup = [stops[0]];
+  for (let index = 1; index < stops.length; index++) {
+    if (stops[index].color === currentGroup[0].color) {
+      currentGroup.push(stops[index]);
+    } else {
+      groups.push(currentGroup);
+      currentGroup = [stops[index]];
+    }
+  }
+  groups.push(currentGroup);
+  return groups;
+}
+
+/**
+ * Combines groups of identical adjacent color stops into single stops with
+ * merged position ranges. Also removes implied 0% at the start and 100%
+ * at the end, and replaces a start position with unitless `0` when it
+ * matches the previous group's end position.
+ *
+ * @param  {Array} args  The gradient stop strings (already split by comma).
+ * @return {Array}       The optimized gradient stop strings.
+ */
+function combineAdjacentIdenticalStops (args) {
+  const stops = args.map((arg) => {
+    return parseColorStop(arg);
+  });
+  const hasPositions = stops.some((stop) => {
+    return stop.position !== null;
+  });
+  if (!hasPositions) {
+    return args;
+  }
+
+  const groups = groupConsecutiveIdenticalStops(stops);
+  const mergedStops = groups.map((group) => {
+    return mergeIdenticalStopGroup(group);
+  });
+
+  return normalizeBoundaryPositionTokens(mergedStops);
+}
+
+/**
+ * Optimizes gradient arguments by removing default direction or shape keywords, combining adjacent identical color stops, and trimming redundant 0% or 100% stop positions from the first and last stops.
  *
  * @param  {string} func     The gradient function name (e.g. "linear-gradient").
  * @param  {string} argsStr  The raw comma-separated gradient arguments string.
@@ -42,6 +339,8 @@ function processGradientArgs (func, argsStr) {
   const args = splitGradientArgs(argsStr);
   const functionLower = func.toLowerCase();
 
+  let directionArgCount = 0;
+
   if (functionLower.includes('linear')) {
     if (args.length > 1) {
       const firstDirection = args[0].toLowerCase().replace(/\s+/g, ' ').trim();
@@ -49,18 +348,31 @@ function processGradientArgs (func, argsStr) {
         args.shift();
       } else if (firstDirection === 'to top') {
         args[0] = '0deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to right') {
         args[0] = '90deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to left') {
         args[0] = '270deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to top right' || firstDirection === 'to right top') {
         args[0] = '45deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to bottom right' || firstDirection === 'to right bottom') {
         args[0] = '135deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to bottom left' || firstDirection === 'to left bottom') {
         args[0] = '225deg';
+        directionArgCount = 1;
       } else if (firstDirection === 'to top left' || firstDirection === 'to left top') {
         args[0] = '315deg';
+        directionArgCount = 1;
+      } else {
+        // Check if first arg looks like a direction (angle or "to ..." keyword)
+        const looksLikeDirection = /^\d+(\.\d+)?deg$/i.test(firstDirection) || firstDirection.startsWith('to ');
+        if (looksLikeDirection) {
+          directionArgCount = 1;
+        }
       }
     }
   } else if (functionLower.includes('radial')) {
@@ -68,15 +380,34 @@ function processGradientArgs (func, argsStr) {
       const firstShape = args[0].toLowerCase().replace(/\s+/g, ' ').trim();
       if (firstShape === 'ellipse at center' || firstShape === 'circle at center') {
         args.shift();
+      } else {
+        // Check if first arg is a radial shape/size descriptor
+        const looksLikeShape = /\b(circle|ellipse|closest|farthest|at)\b/i.test(firstShape);
+        if (looksLikeShape) {
+          directionArgCount = 1;
+        }
       }
     }
   }
 
-  if (args.length > 0) {
+  // Extract color stop args (everything after the direction/shape argument)
+  const colorStopArgs = args.slice(directionArgCount).map((arg) => {
+    return normalizeColorStop(arg);
+  });
+  if (colorStopArgs.length > 0) {
+    const normalizedStops = colorStopArgs.length >= 2 ?
+      combineAdjacentIdenticalStops(colorStopArgs) :
+      colorStopArgs;
+    args.splice(directionArgCount, colorStopArgs.length, ...normalizedStops);
+  }
+
+  if (args.length > directionArgCount) {
+    const firstStopIndex = directionArgCount;
+    const lastStopIndex = args.length - 1;
     // Remove default 0% stop position from the first gradient stop
-    args[0] = args[0].replace(/^(.*\S)\s+0%$/, '$1');
+    args[firstStopIndex] = args[firstStopIndex].replace(/^(.*\S)\s+0%$/, '$1');
     // Remove default 100% stop position from the last gradient stop
-    args[args.length - 1] = args[args.length - 1].replace(/^(.*\S)\s+100%$/, '$1');
+    args[lastStopIndex] = args[lastStopIndex].replace(/^(.*\S)\s+100%$/, '$1');
   }
 
   return args.join(',');

package/src/value/minify.js

@@ -651,6 +651,10 @@ function applyPropertyOptimizations (val, property) {
     if (normalized) {
       val = normalized;
     }
+    // Restore the required separator between an image function and a following
+    // background-position when that position is not immediately followed by `/size`.
+    val = val.replace(/\)((?:left|center|right|top|bottom|[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?)(?:\s+(?:left|center|right|top|bottom|[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?))?)(?!\/)/gi, ') $1');
+    val = val.replace(/\)\s+((?:left|center|right|top|bottom|[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?)(?:\s+(?:left|center|right|top|bottom|[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?))?)(?=\/)/gi, ')$1');
   }
 
   if (property === 'border') {