@thejaredwilcurt/csslop 0.0.10 → 0.0.11

package/package.json

@@ -2,7 +2,7 @@
   "name": "@thejaredwilcurt/csslop",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Experimental CSS minification",
   "scripts": {
     "prestart": "node ./scripts/prestart.js",

package/src/context.js

@@ -14,4 +14,47 @@ function createMinifyContext () {
   };
 }
 
-export { createMinifyContext };
+/**
+ * Module-level charset state used during a single synchronous minifyCSS call.
+ * Tracks whether the stylesheet declares a non-unicode charset, so that the
+ * value minifier can avoid resolving unicode escapes in non-unicode encodings.
+ */
+let activeCharset = '';
+
+/**
+ * Returns true when the active charset is a unicode-compatible encoding
+ * (UTF-8, UTF-16, or the default when no `@charset` is declared), meaning
+ * CSS unicode escapes can safely be resolved to literal characters.
+ *
+ * @return {boolean} True if the active charset supports unicode characters.
+ */
+function isUnicodeCharset () {
+  if (!activeCharset) {
+    return true;
+  }
+  const normalized = activeCharset.toLowerCase().replace(/["']/g, '');
+  return normalized === 'utf-8' || normalized.startsWith('utf-16');
+}
+
+/**
+ * Sets the active charset for the current minification pass.
+ *
+ * @param {string} charset  The `@charset` value (with quotes) from the stylesheet.
+ */
+function setActiveCharset (charset) {
+  activeCharset = charset || '';
+}
+
+/**
+ * Clears the active charset after a minification pass completes.
+ */
+function clearActiveCharset () {
+  activeCharset = '';
+}
+
+export {
+  clearActiveCharset,
+  createMinifyContext,
+  isUnicodeCharset,
+  setActiveCharset
+};

package/src/index.js

@@ -4,7 +4,11 @@
 
 import { parse } from '@node-projects/css-parser';
 
-import { createMinifyContext } from './context.js';
+import {
+  clearActiveCharset,
+  createMinifyContext,
+  setActiveCharset
+} from './context.js';
 import {
   analyzePositionTryRules,
   cleanPositionTryRules,
@@ -26,7 +30,8 @@ import {
   mergeMediaRules,
   mergeSelectorRules,
   nestFlatRules,
-  removeEmptyRules
+  removeEmptyRules,
+  removeOverriddenMultiSelectorProperties
 } from './rules/optimize.js';
 import { stringifyRule } from './rules/stringify.js';
 import { minifyValue } from './value/minify.js';
@@ -163,6 +168,22 @@ function mergeAdjacentRulesWithIdenticalBodies (ruleStrings) {
   return result;
 }
 
+/**
+ * Extracts the first `@charset` value from raw CSS text before parsing.
+ * Scans for `@charset` followed by a quoted string and semicolon.
+ *
+ * @param  {string} css  The raw CSS string to scan.
+ * @return {string}      The first charset value (with quotes), or empty string if none found.
+ */
+function detectCharset (css) {
+  // Match @charset followed by a quoted value and semicolon
+  const match = css.match(/@charset\s+(["'][^"']+["'])\s*;/i);
+  if (match) {
+    return match[1];
+  }
+  return '';
+}
+
 /**
  * Parses, optimizes, and minifies a CSS string by applying rule merging, declaration deduplication, value compression, and dead-code elimination.
  *
@@ -179,12 +200,16 @@ export const minifyCSS = function (input) {
   let ast;
   const output = [];
 
+  const detectedCharset = detectCharset(source);
+  setActiveCharset(detectedCharset);
+
   try {
     ast = parse(
       preprocessDeclarationBlocks(neutralizeEscapeSequences(source)),
       { preserveFormatting: true, silent: true }
     );
   } catch {
+    clearActiveCharset();
     return source;
   }
 
@@ -217,7 +242,9 @@ export const minifyCSS = function (input) {
     ast.stylesheet.rules = deduplicateKeyframes(ast.stylesheet.rules);
 
     const mergedRules = mergeSelectorRules(ast.stylesheet.rules);
-    const declarationMergedRules = mergeByDeclarations(mergedRules);
+    const overrideCleanedRules = removeOverriddenMultiSelectorProperties(mergedRules);
+    const preCleanedRules = removeEmptyRules(overrideCleanedRules);
+    const declarationMergedRules = mergeByDeclarations(preCleanedRules);
     const nestedRules = nestFlatRules(declarationMergedRules);
     const nonEmptyRules = removeEmptyRules(nestedRules);
     const factoredRules = factorCommonParents(nonEmptyRules);
@@ -229,8 +256,10 @@ export const minifyCSS = function (input) {
 
     const mergedOutput = mergeAdjacentRulesWithIdenticalBodies(output);
 
+    clearActiveCharset();
     return restoreEscapeSequences(mergedOutput.join(''));
   }
 
+  clearActiveCharset();
   return source;
 };

package/src/position-try.js

@@ -165,29 +165,33 @@ function filterUnusedPositionTry (rules, positionTryRules, positionTryUsage) {
 
 /**
  * Removes duplicate and redundant UTF-8 `@charset` rules, keeping only the first
- * non-UTF-8 charset declaration.
+ * non-UTF-8 charset declaration and moving it to the top of the document.
+ * Per the CSS specification, `@charset` must be the very first thing in a stylesheet.
  *
  * @param  {Array} rules  The top-level AST rule nodes to filter.
- * @return {Array}        A new array of rules with redundant `@charset` entries removed.
+ * @return {Array}        A new array of rules with the first non-UTF-8 `@charset` at the start and all others removed.
  */
 function filterRedundantCharsets (rules) {
-  let firstCharsetFound = false;
+  let keptCharset = null;
 
-  return rules.filter((rule) => {
-    if (rule.type === 'charset') {
-      if (!firstCharsetFound) {
-        firstCharsetFound = true;
-        // Strip surrounding quotes from the charset value for comparison
-        const normalizedCharset = rule.charset?.toLowerCase().replace(/["']/g, '');
-        if (normalizedCharset === 'utf-8') {
-          return false;
-        }
-        return true;
+  const filtered = rules.filter((rule) => {
+    if (rule.type !== 'charset') {
+      return true;
+    }
+    if (!keptCharset) {
+      // Strip surrounding quotes from the charset value for comparison
+      const normalizedCharset = rule.charset?.toLowerCase().replace(/["']/g, '');
+      if (normalizedCharset !== 'utf-8') {
+        keptCharset = rule;
       }
-      return false;
     }
-    return true;
+    return false;
   });
+
+  if (keptCharset) {
+    return [keptCharset, ...filtered];
+  }
+  return filtered;
 }
 
 export {

package/src/preprocess.js

@@ -2,6 +2,7 @@
  * @file Preprocesses CSS declaration blocks by converting Unicode escape sequences to their literal characters before parsing.
  */
 
+import { isUnicodeCharset } from './context.js';
 import { resolveUnicodeEscape } from './utilities.js';
 
 /**
@@ -91,20 +92,23 @@ function preprocessDeclarationBlocks (css) {
 
   // Match top-level declaration blocks (non-nested { ... })
   return processed.replace(/\{([^{}]*)\}/g, (match, content) => {
-    // First, remove semicolons after comments which cause parser errors
-    // Pattern: comment followed by optional whitespace and semicolon
-    let processed = content.replace(/\/\*.*?\*\/\s*;/g, (commentMatch) => {
+    // Remove semicolons after standalone comments (between declarations) which cause parser errors.
+    // Only match when preceded by a semicolon, so property values like --foo: /*...*/; keep their terminator.
+    let processed = content.replace(/(?<=;)\s*\/\*.*?\*\/\s*;/g, (commentMatch) => {
       // Remove the trailing semicolon from comment+semicolon combinations
       return commentMatch.replace(/;$/, '');
     });
     
-    // Then, skip quoted strings and match CSS unicode escapes (backslash + 1-6 hex digits + optional whitespace)
-    processed = processed.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\\([0-9a-fA-F]{1,6})\s?/g, (fullMatch, hex) => {
-      if (!hex) {
-        return fullMatch;
-      }
-      return resolveUnicodeEscape(hex) ?? fullMatch;
-    });
+    // Then, skip quoted strings and match CSS unicode escapes (backslash + 1-6 hex digits + optional whitespace).
+    // Only resolve when the charset is unicode-compatible.
+    if (isUnicodeCharset()) {
+      processed = processed.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\\([0-9a-fA-F]{1,6})\s?/g, (fullMatch, hex) => {
+        if (!hex) {
+          return fullMatch;
+        }
+        return resolveUnicodeEscape(hex) ?? fullMatch;
+      });
+    }
     
     return '{' + processed + '}';
   });

package/src/rules/optimize.js

@@ -525,6 +525,102 @@ function mergeLayerRules (rules, mergeSelectorRules) {
   return result;
 }
 
+/**
+ * Normalizes a selector string for consistent comparison by trimming
+ * and collapsing internal whitespace.
+ *
+ * @param  {string} selector  The raw selector string.
+ * @return {string}           The normalized selector.
+ */
+function normalizeSelector (selector) {
+  return selector.trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * Removes properties from multi-selector rules when every selector in
+ * the rule has that property overridden by a later rule. For example,
+ * if `h1,h2{color:red}` is followed by `h1{color:blue}` and
+ * `h2{color:green}`, the `color` in the first rule is redundant and
+ * can be removed. If all properties are removed, the empty rule will
+ * be cleaned up by `removeEmptyRules`.
+ *
+ * @param  {Array} rules  The flat list of AST rule nodes.
+ * @return {Array}        The rules with overridden multi-selector properties removed.
+ */
+function removeOverriddenMultiSelectorProperties (rules) {
+  for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex++) {
+    const rule = rules[ruleIndex];
+    if (rule.type !== 'rule' || !rule.selectors || rule.selectors.length < 2) {
+      continue;
+    }
+    const normalizedSelectors = rule.selectors.map(normalizeSelector);
+    const declarations = (rule.declarations || []).filter((declaration) => {
+      return declaration.type === 'declaration';
+    });
+    if (declarations.length === 0) {
+      continue;
+    }
+
+    // For each property in this multi-selector rule, check if ALL selectors
+    // get that property overridden in later rules
+    const propertiesToRemove = new Set();
+    for (const declaration of declarations) {
+      const property = declaration.property;
+      const allSelectorsOverridden = normalizedSelectors.every((selector) => {
+        return isSelectorPropertyOverriddenLater(rules, ruleIndex, selector, property);
+      });
+      if (allSelectorsOverridden) {
+        propertiesToRemove.add(property);
+      }
+    }
+
+    if (propertiesToRemove.size > 0) {
+      rule.declarations = (rule.declarations || []).filter((declaration) => {
+        if (declaration.type !== 'declaration') {
+          return true;
+        }
+        return !propertiesToRemove.has(declaration.property);
+      });
+    }
+  }
+  return rules;
+}
+
+/**
+ * Checks whether a given selector has a specific property overridden
+ * by any later rule in the stylesheet. A property is considered
+ * overridden if a subsequent rule contains that selector (as its only
+ * selector or among its selectors) and declares the same property.
+ *
+ * @param  {Array}   rules       The full list of AST rule nodes.
+ * @param  {number}  startIndex  The index of the current rule (search starts after this).
+ * @param  {string}  selector    The normalized selector to check.
+ * @param  {string}  property    The CSS property name to check.
+ * @return {boolean}             True if a later rule overrides this selector+property.
+ */
+function isSelectorPropertyOverriddenLater (rules, startIndex, selector, property) {
+  for (let laterIndex = startIndex + 1; laterIndex < rules.length; laterIndex++) {
+    const laterRule = rules[laterIndex];
+    if (laterRule.type !== 'rule' || !laterRule.selectors) {
+      continue;
+    }
+    const laterSelectors = laterRule.selectors.map(normalizeSelector);
+    if (!laterSelectors.includes(selector)) {
+      continue;
+    }
+    const laterDeclarations = (laterRule.declarations || []).filter((declaration) => {
+      return declaration.type === 'declaration';
+    });
+    const hasOverride = laterDeclarations.some((declaration) => {
+      return declaration.property === property;
+    });
+    if (hasOverride) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export {
   deduplicateKeyframes,
   expandPureNestedRules,
@@ -534,5 +630,6 @@ export {
   mergeMediaRules,
   mergeSelectorRules,
   nestFlatRules,
-  removeEmptyRules
+  removeEmptyRules,
+  removeOverriddenMultiSelectorProperties
 };

package/src/rules/stringify.js

@@ -404,6 +404,26 @@ function stripLeadingZerosFromDecimals (value) {
   return value.replace(/(^|\s|,|\()(-?)0+(\.\d+)/g, '$1$2$3');
 }
 
+/**
+ * Processes CSS comments within a custom property value. If the value
+ * consists entirely of a comment, the comment is removed (producing an
+ * empty value). If comments appear between other tokens, their content
+ * is stripped but empty comment delimiters are kept as zero-width
+ * token separators to preserve the token sequence.
+ *
+ * @param  {string} value  The raw custom property value string.
+ * @return {string}        The value with comments processed.
+ */
+function processCustomPropertyComments (value) {
+  // Match values that are entirely a comment (with optional surrounding whitespace)
+  const commentOnlyPattern = /^\s*\/\*.*?\*\/\s*$/s;
+  if (commentOnlyPattern.test(value)) {
+    return '';
+  }
+  // Strip comment content but keep empty markers as token separators
+  return value.replace(/\/\*.*?\*\//g, '/**/');
+}
+
 /**
  * Collapses whitespace in a custom property value while preserving
  * token boundaries. Each whitespace sequence is reduced to a single
@@ -488,8 +508,8 @@ function stringifyRule (rule, context, nested = false) {
 
         // Minify double-quoted attribute selectors: remove inner whitespace and escape when shorter
         minified = minified.replace(/\[\s*([^=]+)\s*=\s*"(.*?)"\s*\]/g, (match, attribute, value) => {
-          // Escape special characters that require quoting (spaces, #, ., :, /), and compare lengths
-          let escaped = value.replace(/([ #.:/])/g, '\\$1');
+          // Escape special characters that require quoting (spaces, #, ., :, /, ;), and compare lengths
+          let escaped = value.replace(/([ #.:/;])/g, '\\$1');
           if (escaped.length < value.length + 2) {
             return '[' + attribute + '=' + escaped + ']';
           }
@@ -497,8 +517,8 @@ function stringifyRule (rule, context, nested = false) {
         });
         // Minify single-quoted attribute selectors: remove inner whitespace and escape when shorter
         minified = minified.replace(/\[\s*([^=]+)\s*=\s*'(.*?)'\s*\]/g, (match, attribute, value) => {
-          // Escape special characters that require quoting (spaces, #, ., :, /), and compare lengths
-          let escaped = value.replace(/([ #.:/])/g, '\\$1');
+          // Escape special characters that require quoting (spaces, #, ., :, /, ;), and compare lengths
+          let escaped = value.replace(/([ #.:/;])/g, '\\$1');
           if (escaped.length < value.length + 2) {
             return '[' + attribute + '=' + escaped + ']';
           }
@@ -506,8 +526,8 @@ function stringifyRule (rule, context, nested = false) {
         });
         // Minify unquoted attribute selectors: quote when unescaping produces a shorter result
         minified = minified.replace(/\[\s*([^=]+)\s*=\s*([^"'].*?)\s*\]/g, (match, attribute, value) => {
-          // Unescape special characters (spaces, #, ., :, /) and compare with quoted form
-          let unescaped = value.replace(/\\([ #.:/])/g, '$1');
+          // Unescape special characters (spaces, #, ., :, /, ;) and compare with quoted form
+          let unescaped = value.replace(/\\([ #.:/;])/g, '$1');
           if (unescaped.length + 2 < value.length) {
             return '[' + attribute + '="' + unescaped + '"]';
           }
@@ -572,9 +592,23 @@ function stringifyRule (rule, context, nested = false) {
             value = minifyValue(declaration);
           } else {
             const rawValue = declaration.rawValue || declaration.value || '';
-            const trimmedRawValue = rawValue.trim();
+            const commentProcessedValue = processCustomPropertyComments(rawValue);
+            const trimmedRawValue = commentProcessedValue.trim();
             if (trimmedRawValue === '') {
-              value = ' ';
+              const hasExplicitValueContent = commentProcessedValue.length > 0;
+              // When the parser absorbs a whitespace-only value into
+              // rawBetween, trailing whitespace after the colon signals an
+              // intentionally empty custom property (e.g. `--foo: ;` sets
+              // the value to a space token, which differs from an absent
+              // value). Only apply this check when the original rawValue
+              // was already empty — not when it became empty after
+              // stripping a comment.
+              const originalValueWasEmpty = rawValue.trim() === '';
+              const colonBetween = declaration.rawBetween || '';
+              // Match whitespace after the colon character
+              const hasSpaceAfterColon = /:\s/.test(colonBetween);
+              const isExplicitlyEmptyValue = hasExplicitValueContent || (originalValueWasEmpty && hasSpaceAfterColon);
+              value = isExplicitlyEmptyValue ? ' ' : '';
             // Preserve leading space for rgb() space-syntax values in custom properties
             } else if (/^rgb\(\s*\d+\s+\d+\s+\d+\s*\)$/i.test(trimmedRawValue)) {
               value = ' ' + trimmedRawValue;
@@ -674,6 +708,13 @@ function stringifyRule (rule, context, nested = false) {
       .filter((keyframe) => {
         return keyframe.type === 'keyframe';
       })
+      .filter((keyframe) => {
+        // Skip keyframe stops that have no meaningful declarations
+        const meaningful = (keyframe.declarations || []).filter((declaration) => {
+          return declaration.type !== 'whitespace' && declaration.type !== 'comment';
+        });
+        return meaningful.length > 0;
+      })
       .map((keyframe) => {
         let output = [];
         let stopValues = keyframe.values.map((stopValue) => {
@@ -689,7 +730,7 @@ function stringifyRule (rule, context, nested = false) {
         output.push('{');
         const renderedKeyframeDeclarations = keyframe.declarations
           ?.filter((declaration) => {
-            return declaration.type !== 'whitespace';
+            return declaration.type !== 'whitespace' && declaration.type !== 'comment';
           })
           ?.map((declaration) => {
             return [declaration.property, ':', minifyValue(declaration)].join('');

package/src/value/minify.js

@@ -2,6 +2,7 @@
  * @file Minifies CSS declaration values by applying color conversion, math simplification, shorthand compression, and other property-specific optimizations.
  */
 
+import { isUnicodeCharset } from '../context.js';
 import { resolveUnicodeEscape } from '../utilities.js';
 
 import {
@@ -177,10 +178,13 @@ function replaceOutsideStringsAndUrls (value, replacer) {
  * @return {string}           The value with whitespace collapsed, quotes normalized, and unicode escapes resolved.
  */
 function normalizeWhitespaceAndQuotes (val, property) {
-  // Unescape unicode (skip control characters — they must stay escaped in CSS strings)
-  val = val.replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex) => {
-    return resolveUnicodeEscape(hex) ?? match;
-  });
+  // Unescape unicode (skip control characters — they must stay escaped in CSS strings).
+  // Only resolve escapes when the charset is unicode-compatible (UTF-8/UTF-16 or default).
+  if (isUnicodeCharset()) {
+    val = val.replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex) => {
+      return resolveUnicodeEscape(hex) ?? match;
+    });
+  }
   // Normalize single-quoted strings to double-quoted
   val = val.replace(/'((?:[^'\\]|\\.)*?)'/g, '"$1"');
 
@@ -444,7 +448,7 @@ function convertMillisecondsToSeconds (value) {
  * @return {string}           The value with property-specific optimizations applied.
  */
 function applyPropertyOptimizations (val, property) {
-  if (property === 'font-weight') {
+  if (property === 'font-weight' && isUnicodeCharset()) {
     // Replace font-weight keyword "bold" with its numeric equivalent
     val = val.replace(/\bbold\b/gi, '700');
     // Replace font-weight keyword "normal" with its numeric equivalent
@@ -482,6 +486,9 @@ function applyPropertyOptimizations (val, property) {
     // Replace steps() functions with their equivalent named timing-function keywords
     val = val.replace(/steps\(1,start\)/g, 'step-start');
     val = val.replace(/steps\(1,end\)/g, 'step-end');
+    // Restore space between step-start/step-end keyword and following token
+    // (the parenthesis whitespace stripping removes the space before replacement)
+    val = val.replace(/(step-start|step-end)(?=[a-zA-Z0-9#-])/g, '$1 ');
   }
 
   // Flex: remove " 0px" from flex shorthand (flex: 0 0 0px -> flex: 0 0)