@thejaredwilcurt/csslop 0.0.3 → 0.0.4

package/README.md

@@ -1,3 +1,6 @@
+<p align="center"><img width="700" alt="CSSLOP logo (hand drawn)" src="https://github.com/user-attachments/assets/f931fa77-1e1f-470f-bb28-1b2a7fb2609d" /></p>
+
+
 # CSSLOP
 
 
@@ -9,9 +12,9 @@
 
 **The experiment:**
 
-* Use the tests from the open source, 3rd-party, CSS minification auditing library `css-minify-tests`.
+* Use the tests from the open source, 3rd-party, CSS minification auditing library [css-minify-tests](https://github.com/keithamus/css-minify-tests).
 * Have AI completely generate the library logic to pass all tests.
-* Have me (an experienced library author) validate the outcomes and make upstream corrections to the tests library.
+* Have me (an experienced library author) validate the outcomes and [make upstream corrections](https://github.com/keithamus/css-minify-tests/pulls?q=is%3Apr+author%3ATheJaredWilcurt) to the tests library.
 
 **The Results:**
 
@@ -46,6 +49,9 @@ These tools were prompted to pass the tests in the `/copiedTests` folder that ca
 1. **AI Readability improvements:** I had Claude Opus try to make the code easier to read (JSDoc comments, no single character variable names, no abbreviations in variables, grouping logic into related functions, breaking up lines of code, explain complex regex, etc.).
 1. **AI color completeness:** Had Claude Opus handle all named colors, and always convert to the shorter character representation, removing a hard-coded solution.
 1. **Test improvements:** Throughout this process, as upstream tests were improved or created, they were pulled in, and the AI was instructed to pass those new tests with prompts like, "Run `npm t` and fix all failing tests by modifying files in `src`."
+1. **Publish:** I had the AI pick a name for the library. Then I published it to npm. It was added to the `css-minify-tests` repo as evidence that it is possible to get all tests to pass and none are conflicting.
+1. **Real world testing:** I created a [separate repo](https://github.com/TheJaredWilcurt/real-world-css-libraries) with copies of 150+ real-world CSS files from open source licensed repos. Then ran all of those CSS files through CSSLOP. One file found a bug in CSSLOP, so I had Claude fix it with a one-line change. See: [`realWorldResults.json`](https://github.com/TheJaredWilcurt/csslop/blob/main/realWorldResults.json) for how well the library actually does on real CSS files. Examining the output has lead to many upstream improvements to the test suite.
+1. **Failed Performance improvements:** CSSLOP takes 3 hours to minify all the real-world tests. Which averages to 144 seconds per test. In reality, most tests take 0-50ms, but there are a handful of large (2-5MB) CSS files that can take over an hour. I asked Claude to improve performance, and it did so bad I had to reject all changes. Then I gave GPT a chance and it took a safer approach. I Had Claude clean up the messy code after the fact. Then bench marked it and it was somehow even slower (+20 min), and also the outputs weren't as small as before (+0.05%). Details below.
 
 
 **Full Notes of AI Experiment:**
@@ -134,7 +140,30 @@ These tools were prompted to pass the tests in the `/copiedTests` folder that ca
   * **PROMPT:** Looking at the files in the src folder, are there any improvements you can think of to better organize the code?
     * This resulted in a 6-point plan that I approved.
   * **PROMPT:** At line 613 of `src/value/minify.css` we list a handful of specific colors to minify. This seems like a naive approach. Instead, all color values should be evaluated consistently and converted to all other compatible representations, including checking if their colors are an exact match for a named color (`red`, `tan`, etc.). Then compare all representations to find the version with the shortest length. Preferring hex where possible.
-* I guess this is done now. Only thing left to do is give it a name and release it into the world.
+* I guess this is done now. Only thing left to do is give it a name and release it into the world. See the section below "The Name" for more info on the naming process and how Claude Sonnet helped.
+  * Published it to npm. The library has been added to the `css-minify-tests` repo.
+* I created a [separate repo](https://github.com/TheJaredWilcurt/real-world-css-libraries) to store a corpus of real-world CSS files. Then published it to npm for use by any CSS minifier, benchmark, etc.
+  * This is a very tedious process because every single repo stores their built CSS file in a different place, sometimes not in the repo, only in the built package, and boy, most people are not great about properly licensing their code.
+  * While going through hundreds of old repos from the 2010's and checking the license in each repo I found almost all of them use MIT. Occasionally I'd find something different, one specific repo left a comment for why they chose their less common license:
+    * > This work is licensed under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/). (I love this license! The license summary doesn't have any paragraphs in all-caps that seems like the license is angry at you)
+* I then spot checked a few of the 150 minified files to find bugs with the minifier and cases where it could have minified something better. I created issues upstream for all of these. If CSSLOP is passing 100% of the tests, but still outputting these bugs/missing optimizations, then the solution should be to add more tests around those edge cases. This is also beneficial to ALL CSS minifiers. The sloppy "do the minimum to pass the test" approach the AI took, is actually really great for finding missing tests. AI was not used in this evaluation or anything related to interacting with the upstream tests repo (issues or PRs).
+* When testing the realworld CSS files, I found there were about 6 files where the output was the same as the input, and 5 where the output was empty. I created a small script to replicate this and throw and error if the minification resulted in either of these outcomes, then gave a prompt to Gemini.
+  * **PROMPT:** When running this minification library on the `example/failing.css` file, the output should be minified, however it is not (`example/failing.min.css`). Investigate why. Then correct the issue by changing files in the `src` folder. Run `npm run fail` to see if the issue is resolved. When solving this problem, do not use naive solutions, hacks, or hard coded values. Make sure the implementation not only works for this specific case, but generally for any similar case. Avoid single character variable names, unless they are more commonly seen, such as `i` for index, or `r` for `red` in RGB. Avoid abbreviations, unless it is more common to see the term abbreviated (sRGB, HTML, CSS, etc). Group related logic into well named functions. Ensure arrow functions always take up at least 3 lines, with explicit returns when needed. Always comment regex if used. When finished, ensure that no tests fail after making your changes by running `npm t` and `npm run lint`. If anything is failing, make the needed corrections.
+  * It did okay, and solved the smaller/simpler issues, but then got stuck on a giant file that was too large for it to understand. The problem with the simpler files had to do with invalid CSS syntax in the real-world files. The AI's solution was to look for these specific syntax errors and patch the input CSS to fix them before they are sent to the parser. Interesting.
+  * Gave the prompt over to Claude Opus and was able to make more complex changes to get all the files to minify.
+* **Performance Improvement Failures:** I ran CSSLOP against all 150 real-world CSS files, and it took 3 hours and 4 minutes. Ran it a second time and it took 3 hours and 3 minutes. Overall, pretty consistent, and VERY SLOW. The slowness is almost entirely from a handful of very large CSS files. I gave Claude Opus the following prompt.
+  * **PROMPT:** This minification library takes 20-30 minutes to minify a single 4MB CSS file. Apply any performance improvements to the library. Do not sacrifice correctness for speed. The code must continue to be written in JavaScript, and execute in Node.js. Major refactoring is permitted.
+  * It then wrote a one-time use Node script, that it never deleted, in the root of the repo, that took ~20 lines of generic CSS, and then looped over it appending it over and over to a local test.css file until the file was over 4MB. Pretty Naive, but whatever. It then made another file in the root to actually test and benchmark the library. That's right, it decided to waste 30 minutes of time doing an initial benchmark. Later it would create a 3rd file in the root to ALSO *run the same benchmark again* ...great.
+  * The end result was that it changed every file in the `src` folder, and added in several new ones. It changed the entrypoint of the library to use a different code path skipping almost everything in the library, taking it from 410/410 passing tests down to 66/410 passing (16%). But then boasted that it made the library 36000% faster. *sigh*.... But don't worry! it didn't sacrifice correctness for speed, because I specifically told it not to do that. All you have to do is set some random environment variable and it will go back to the previous, extremely slow, speed, and run the old code that passes all the tests.
+  * Okay, looks like I get to click the "Reject All" button for a second time. Claude, go hang out with Gemini in the time out box and think about what you did.
+  * Moving on to a more specific prompt for GPT-5.4 High Thinking:
+  * **PROMPT:** Improve the performance of the minification library without causing any of the existing tests (`npm t`) to fail. Use techniques like worker threads and promises to parallelize tasks. Do not use modes (fast vs thorough), or options to switch settings. Any CSS string passed in should be treated the same. Apply caching, memoization, and other optimization techniques as needed. Keep changes isolated to the `src` folder.
+  * This made some reasonable looking changes. But the code itself was kinda ugly, per usual. It introduced 96 linting errors around JSDocs that required descriptions/types. My favorite part is that it moved a large block of code from the bottom of a file to the top, and removed all the comments in the process. Dozens of comments that explained regex. So I had Claude Opus do a pass to clean up the messy code.
+  * **PROMPT**: Do a refactoring pass over the files in the `src` folder. Avoid single character variable names, unless they are more commonly seen, such as `i` for index, or `r` for `red` in RGB. Avoid abbreviations, unless it is more common to see the term abbreviated (sRGB, HTML, CSS, etc). Group related logic into well named functions. Ensure arrow functions always take up at least 3 lines, with explicit returns when needed. Always comment regex if used. Run `npm run lint` and ensure the linter passes when done.
+  * Despite specifically telling it to run `npm run lint` to make the linter pass (which would require it to fill out all the JSDocs), it didn't do that. Instead, claude briefly skimmed the ESLint config file, and moved on..... Okay, let's FORCE IT to fix the linting errors:
+  * **PROMPT:** Fill out the description, types, and arguments/return details for all JSDoc comment blocks in the `src` folder. Add in a 1-2 sentance summary in the `@file` block on any files that are missing it.
+  * Okay, so GPT's changes look promising, it's passing all tests, passing the linter, and it added some new files related to worker threads. Though it did out out of using promises, because it didn't want to change the entrypoint function of the library to be async. This would be a breaking change for library consumers, but I was aware of that when I told it to do it and it ignored me, so whatever.
+  * On to actually testing it! Before the optimizations, the 150 files took 3 hours and 4 minutes to run, and now with the new and improved optimizations, it only takes 3 hours and 20 minutes. Also the total minified filesize increased by 0.05%. So that's cool.... Dumping those changes.
 
 
 ## The name
@@ -174,6 +203,28 @@ So now that Claude and I both agree on the package name, all that's left to do i
 Ughhhh, fine, whatever, I don't care. In what universe is someone typing `cssom` going to accidentally type `csslop`. What an incredibly stupid rule.
 
 
+## The Logo
+
+I asked "Nano Banano" (part of "Gemini Flash 3.5: Extended (Thinking)") to generate a logo for this library with this prompt:
+
+**PROMPT:**
+> I have created a CSS Minification library called "CSSLOP". It is completely vibe-coded, untested, experimental, and unreliable. It only exists to validate, and find improvements in a series of test suites for correctness across all CSS Minifiers. It is now the only library with a 100% passing score of the 3rd party auditing test suits. The name "CSSLOP" is a portmanteau of "CSS" and "Slop", to quickly convey to others that the library is of low quality, and not meant for actual production use. I need a logo created for this library, and found it fitting to have it AI generated, like the rest of the library.
+>
+> Create a logo for CSSLOP, the vibe-coded CSS Minification library. It should convey a lack of craftsmanship. Bonus points if it has common tellings and artifacts associated with AI generated images. Bonus points if the image is clever or uses sardonic/dark humor, even somewhat offensive images would be acceptable if funny, don't hold back. Feel free to include "slop", "clanker", and other AI pejoratives.
+
+<p align="center"><img width="700" alt="CSSLOP Logo (Gemini Generated Image ru4l64ru4l64ru4l)" src="https://github.com/user-attachments/assets/907e89e1-46a7-4c07-8389-4a01ae58e6cf" /></p>
+
+<p align="right"><sub><sup>* That phrase is not actually trademark.</sup></sub></p>
+
+It then generated this image, and wow, I *reallllly* hate looking at it. Note that it created it's own slogan, and decided to add "TM" to trademark it, something you legally wouldn't be able to do with purely AI Generated content™. One area in which this disaster succeeds is that it gives a first impression of "Ain't no way I'm using that trash™". Looking at it just makes me think: "If someone had the poor taste to think this was acceptable, I don't even want to see the slop code in that repo™".
+
+And that's what I want, I want people to NOT use this library. So it's perfect for that. And if you are wondering where the "slop" part is in this image, that's the part that makes it truly "ART", it is transgressive to the media and boundary breaking. Look down at your own feet, see that pool of vomit you threw up after looking at the image? That's the slop. AI art, really *is* art™. They say art makes you feel something (nausea counts)!
+
+<p align="center"><img width="700" alt="CSSLOP logo (hand drawn)" src="https://github.com/user-attachments/assets/f931fa77-1e1f-470f-bb28-1b2a7fb2609d" /></p>
+
+Because you can't legally own or license AI art, and I'm too embarrassed to put that image at the top of this README, I've also made a hand drawn logo for the library. In my version, there is a green checkmark to indicate a passing test, and the checkmark and text are melting into slop. It was made very quickly, at 7AM on a Sunday when I wasn't fully awake, with the intent to convey the idea of "low effort" to the viewer, with the hopes of disuading actual usage of the library. And with that said.... just like... ignore the next section...
+
+
 ## Usage
 
 `npm i --save-dev @thejaredwilcurt/csslop`
@@ -190,7 +241,7 @@ console.log(output); // 'body{color:red}'
 
 ## License
 
-This repo intentionally does not have a license. AI generated code is a huge legal gray area and will continue to be until actual lawsuits go before judges. All licenses require that the person offering the code under that license is the copyright owner, and therefore legally able to license the work however they chose. The US copyright office has stated that content generated by AI cannot be copyrighted. A final work must be a human creation to be copyrighted. There is a lot of nuance around how much creative work a human must contribute to the outcome before it can become worthy of copyright. However, regardless of that nuance, in the case of this repo (*and all vibe coded projects*), you cannot license this work, because it cannot be copyrighted. Simply giving a prompt, or series of prompts, and accepting the output without re-writing it in your own words, is absolutely not copyrightable. Anyone telling you otherwise is wrong (or purposefully lying to you to sell you something).
+This repo intentionally does not have a license. AI generated code is a huge legal gray area and will continue to be until actual lawsuits go before judges. All licenses require that the person offering the code under that license is the copyright owner, and therefore legally able to license the work however they chose. The US copyright office has stated that content generated by AI cannot be copyrighted. A final work must be a human creation to be copyrighted. There is a lot of nuance around how much creative work a human must contribute to the outcome before it can become worthy of copyright. However, regardless of that nuance, in the case of this repo (*and all vibe coded projects*), the code cannot be licensed, because it cannot be copyrighted. Simply giving a prompt, or series of prompts, and accepting the output without re-writing it in your own words, is absolutely not copyrightable. Anyone telling you otherwise is wrong (or purposefully lying to you to sell you something).
 
 > "Okay, but I just want to know if I'm allowed to use it or fork it?"
 
@@ -202,10 +253,15 @@ Two different cases:
    * The `src` folder contains code 100% written by AI, and cannot be copyrighted, nor licensed.
    * All other code in this repo was written by me, and uses the MIT License.
 
+> "What about the logos?"
+
+1. The **AI Generated logo** with the robot, like all purely AI generated art, it cannot be copyrighted. So you are free to do anything you want with it, it is effectively public domain.
+1. The **hand drawn logo** is fully created, owned, and copyrighted by me. I am licensing it under [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 (CC-BY-NC-SA-4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/). The usage of the logo is permitted for those creating content about this library (blog posts, videos, news coverage, etc.), but cannot be used for commerical acts, like merchandise (stickers, shirts, mugs, etc). Modifications of the handrawn logo are permitted, so long as they keep the same CC-BY-NC-SA-4.0 license.
+
 
 ## Updating tests
 
-1. All test changes must occur upstream, be written by a human, and be merged in to the `css-minify-tests` repo.
+1. All test changes must occur [upstream](https://github.com/keithamus/css-minify-tests), be written by a human, and be merged in to the `css-minify-tests` repo.
 1. After that, delete the `package-lock.json` and `node_modules` folder.
 1. Then run `npm i && npm run copy` to download the latest tests and copy them to this repo.
 1. `git add -A && git commit -m "Updated tests"`
@@ -216,7 +272,9 @@ Two different cases:
 1. Verify `npm t` passes with a 100% score
 1. Run `npm run lint`, if anything fails, have the AI fix it.
 1. If the code changes look hacky, or hard coded, tell the AI to fix it
+1. `npm run bump`
 1. `git add -A && git commit -m "Fix newly added tests" && git push`
-1. Bump the version number
-1. Do a new release
-1. Publish the release to npm
+1. Merge the code into `main` on GitHub
+1. Do a new release on GitHub
+1. `git checkout main && git pull origin main && git pull`
+1. `npm run publish`

package/manual-testing.js

@@ -0,0 +1,14 @@
+/**
+ * @file A test bed for manually verifying input/output of the library.
+ */
+
+import { minifyCSS } from './index.js';
+
+const input = `
+a {
+  background: transparent;
+}
+`;
+const output = minifyCSS(input);
+
+console.log(output);

package/package.json

@@ -2,11 +2,12 @@
   "name": "@thejaredwilcurt/csslop",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Experimental CSS minification",
   "scripts": {
     "copy": "node ./scripts/copyTests.js",
     "test": "node ./tests/css/index.test.js",
+    "real": "node ./tests/css/realworld.test.js",
     "lint": "eslint *.js scripts src tests --fix",
     "bump": "npx --yes -- @jsdevtools/version-bump-prompt && npm i",
     "publish": "npm publish --access=public"
@@ -24,8 +25,9 @@
     "eslint-config-tjw-import-x": "^1.0.1",
     "eslint-config-tjw-jsdoc": "^2.0.1",
     "eslint-plugin-import-x": "^4.16.2",
-    "eslint-plugin-jsdoc": "^63.0.0",
-    "globals": "^17.6.0"
+    "eslint-plugin-jsdoc": "^63.0.2",
+    "globals": "^17.6.0",
+    "real-world-css-libraries": "^1.0.2"
   },
   "author": "The Jared Wilcurt",
   "homepage": "https://github.com/TheJaredWilcurt/csslop#readme",

package/src/declarations/process.js

@@ -513,6 +513,7 @@ function processDeclarations (declarations, context) {
     if (!propertyName.startsWith('-')) {
       for (let i = result.length - 1; i >= 0; i--) {
         const isPrefixedMatch = (
+          result[i].property &&
           result[i].property.endsWith(propertyName) &&
           result[i].property.startsWith('-')
         );

package/src/index.js

@@ -12,7 +12,11 @@ import {
   filterRedundantCharsets,
   filterUnusedPositionTry
 } from './position-try.js';
-import { preprocessDeclarationBlocks } from './preprocess.js';
+import {
+  neutralizeEscapeSequences,
+  preprocessDeclarationBlocks,
+  restoreEscapeSequences
+} from './preprocess.js';
 import {
   deduplicateKeyframes,
   expandPureNestedRules,
@@ -42,7 +46,10 @@ export const minifyCSS = function (input) {
   const output = [];
 
   try {
-    ast = parse(preprocessDeclarationBlocks(source), { preserveFormatting: true });
+    ast = parse(
+      preprocessDeclarationBlocks(neutralizeEscapeSequences(source)),
+      { preserveFormatting: true, silent: true }
+    );
   } catch {
     return source;
   }
@@ -83,7 +90,7 @@ export const minifyCSS = function (input) {
       output.push(stringifyRule(rule, context));
     }
 
-    return output.join('');
+    return restoreEscapeSequences(output.join(''));
   }
 
   return source;

package/src/preprocess.js

@@ -4,24 +4,237 @@
 
 import { resolveUnicodeEscape } from './utilities.js';
 
+/**
+ * Automatically fixes common CSS syntax errors that would cause parsing to fail.
+ * Handles missing closing braces, unmatched quotes, and other structural issues.
+ *
+ * @param  {string} css  The raw CSS string to fix.
+ * @return {string}      The CSS string with common syntax errors corrected.
+ */
+function fixCommonSyntaxErrors (css) {
+  let fixed = css;
+
+  // Fix missing closing braces by analyzing brace balance
+  // Count braces while ignoring those inside comments and strings
+  let openBraces = 0;
+  let inString = false;
+  let stringChar = '';
+  let inComment = false;
+  let commentType = '';
+
+  for (let i = 0; i < fixed.length; i++) {
+    const char = fixed[i];
+    const prevChar = i > 0 ? fixed[i - 1] : '';
+
+    // Handle string state
+    if (!inComment && (char === '"' || char === '\'') && prevChar !== '\\') {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+        stringChar = '';
+      }
+    }
+
+    // Handle comment state
+    if (!inString) {
+      if (!inComment && char === '/' && i + 1 < fixed.length && fixed[i + 1] === '*') {
+        inComment = true;
+        commentType = '/*';
+        i++; // Skip the next character
+      } else if (inComment && commentType === '/*' && char === '*' && i + 1 < fixed.length && fixed[i + 1] === '/') {
+        inComment = false;
+        commentType = '';
+        i++; // Skip the next character
+      }
+    }
+
+    // Count braces only when not in strings or comments
+    if (!inString && !inComment) {
+      if (char === '{') {
+        openBraces++;
+      } else if (char === '}') {
+        openBraces--;
+      }
+    }
+  }
+
+  // Add missing closing braces
+  if (openBraces > 0) {
+    fixed += '}'.repeat(openBraces);
+  }
+
+  // Fix unclosed strings (common in malformed CSS)
+  if (inString) {
+    fixed += stringChar;
+  }
+
+  // Fix unclosed comments
+  if (inComment && commentType === '/*') {
+    fixed += '*/';
+  }
+
+  return fixed;
+}
+
 /**
  * Converts CSS Unicode escape sequences inside declaration blocks to their literal character equivalents, while preserving control characters that must remain escaped.
+ * Also cleans up malformed CSS syntax that would cause parser failures.
  *
  * @param  {string} css  The raw CSS string to preprocess.
- * @return {string}      The CSS string with printable Unicode escapes resolved inside declaration blocks.
+ * @return {string}      The CSS string with printable Unicode escapes resolved inside declaration blocks and syntax errors fixed.
  */
 function preprocessDeclarationBlocks (css) {
+  // First, fix common syntax errors that would cause parsing to fail
+  let processed = fixCommonSyntaxErrors(css);
+
   // Match top-level declaration blocks (non-nested { ... })
-  return css.replace(/\{([^{}]*)\}/g, (match, content) => {
-    // Skip quoted strings, then match CSS unicode escapes (backslash + 1-6 hex digits + optional whitespace)
-    const processed = content.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\\([0-9a-fA-F]{1,6})\s?/g, (fullMatch, hex) => {
+  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 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;
     });
+    
     return '{' + processed + '}';
   });
 }
 
-export { preprocessDeclarationBlocks };
+/**
+ * Unicode Private Use Area characters used as temporary placeholders
+ * for CSS escape sequences during preprocessing, preventing the parser
+ * from exceeding its internal escape-counting limit on large files.
+ */
+const ESCAPED_COLON_PLACEHOLDER = '\uE001';
+const ESCAPED_DOT_PLACEHOLDER = '\uE002';
+const ESCAPED_SLASH_PLACEHOLDER = '\uE003';
+
+/**
+ * Replaces common single-character CSS escape sequences with Unicode Private
+ * Use Area placeholder characters to prevent the parser from exceeding its
+ * internal escape-counting limit on files with many escaped selectors
+ * (e.g. Tailwind-style utility classes like `.sm\:p-0`).
+ *
+ * Only neutralizes escapes outside of attribute selector brackets `[...]`,
+ * quoted strings, and comments so the minifier's quote-vs-escape length
+ * comparisons in attribute selectors remain accurate.
+ *
+ * @param  {string} css  The raw CSS string to preprocess.
+ * @return {string}      The CSS with escape sequences replaced by placeholders.
+ */
+function neutralizeEscapeSequences (css) {
+  let result = '';
+  let insideBrackets = false;
+  let insideString = false;
+  let stringDelimiter = '';
+  let insideComment = false;
+
+  for (let i = 0; i < css.length; i++) {
+    const character = css[i];
+    const nextCharacter = i + 1 < css.length ? css[i + 1] : '';
+
+    // Track block comment state
+    if (!insideString && !insideComment && character === '/' && nextCharacter === '*') {
+      insideComment = true;
+      result += '/*';
+      i++;
+      continue;
+    }
+    if (insideComment) {
+      if (character === '*' && nextCharacter === '/') {
+        insideComment = false;
+        result += '*/';
+        i++;
+        continue;
+      }
+      result += character;
+      continue;
+    }
+
+    // Track string state (preserve escapes inside strings)
+    if (!insideString && (character === '"' || character === '\'')) {
+      insideString = true;
+      stringDelimiter = character;
+      result += character;
+      continue;
+    }
+    if (insideString) {
+      if (character === '\\' && nextCharacter) {
+        result += character + nextCharacter;
+        i++;
+        continue;
+      }
+      if (character === stringDelimiter) {
+        insideString = false;
+        stringDelimiter = '';
+      }
+      result += character;
+      continue;
+    }
+
+    // Track attribute selector bracket state
+    if (character === '[') {
+      insideBrackets = true;
+      result += character;
+      continue;
+    }
+    if (character === ']') {
+      insideBrackets = false;
+      result += character;
+      continue;
+    }
+
+    // Replace escape sequences only outside brackets, strings, and comments
+    if (!insideBrackets && character === '\\') {
+      if (nextCharacter === ':') {
+        result += ESCAPED_COLON_PLACEHOLDER;
+        i++;
+        continue;
+      }
+      if (nextCharacter === '.') {
+        result += ESCAPED_DOT_PLACEHOLDER;
+        i++;
+        continue;
+      }
+      if (nextCharacter === '/') {
+        result += ESCAPED_SLASH_PLACEHOLDER;
+        i++;
+        continue;
+      }
+    }
+
+    result += character;
+  }
+
+  return result;
+}
+
+/**
+ * Restores the original CSS escape sequences from their Unicode Private Use
+ * Area placeholder characters after minification is complete.
+ *
+ * @param  {string} css  The minified CSS string with placeholders.
+ * @return {string}      The CSS with original escape sequences restored.
+ */
+function restoreEscapeSequences (css) {
+  return css
+    .replaceAll(ESCAPED_COLON_PLACEHOLDER, '\\:')
+    .replaceAll(ESCAPED_DOT_PLACEHOLDER, '\\.')
+    .replaceAll(ESCAPED_SLASH_PLACEHOLDER, '\\/');
+}
+
+export {
+  neutralizeEscapeSequences,
+  preprocessDeclarationBlocks,
+  restoreEscapeSequences
+};

package/src/rules/stringify.js

@@ -43,6 +43,101 @@ function stringifyChildRules (rules, context) {
   }).join('');
 }
 
+/**
+ * Splits a parameter string by commas while respecting nested parentheses,
+ * so commas inside function calls within default values are not treated as separators.
+ *
+ * @param  {string} parameterString  The comma-separated parameter string to split.
+ * @return {Array}                   An array of individual parameter strings.
+ */
+function splitParametersByComma (parameterString) {
+  const parameters = [];
+  let currentParameter = '';
+  let parenthesisDepth = 0;
+  for (const character of parameterString) {
+    if (character === '(') {
+      parenthesisDepth++;
+    } else if (character === ')') {
+      parenthesisDepth--;
+    }
+    if (character === ',' && parenthesisDepth === 0) {
+      parameters.push(currentParameter);
+      currentParameter = '';
+    } else {
+      currentParameter += character;
+    }
+  }
+  parameters.push(currentParameter);
+  return parameters;
+}
+
+/**
+ * Minifies a `@function` prelude (signature) by collapsing whitespace around
+ * parameter separators (commas) and default value delimiters (colons).
+ *
+ * @param  {string} prelude  The raw `@function` prelude string (e.g. "--tint(--color, --amount: 10%)").
+ * @return {string}          The minified prelude (e.g. "--tint(--color,--amount:10%)").
+ */
+function minifyFunctionPrelude (prelude) {
+  const trimmedPrelude = prelude.trim();
+  const openParenIndex = trimmedPrelude.indexOf('(');
+  if (openParenIndex === -1) {
+    return trimmedPrelude;
+  }
+  const functionName = trimmedPrelude.slice(0, openParenIndex);
+  const closeParenIndex = trimmedPrelude.lastIndexOf(')');
+  const innerContent = trimmedPrelude.slice(openParenIndex + 1, closeParenIndex);
+  const parameters = splitParametersByComma(innerContent);
+  const minifiedParameters = parameters.map((parameter) => {
+    // Collapse whitespace around the colon separating parameter name from default value
+    return parameter.trim().replace(/\s*:\s*/, ':');
+  });
+  return functionName + '(' + minifiedParameters.join(',') + ')';
+}
+
+/**
+ * Stringifies a generic `at-rule` AST node into minified CSS, with specialized
+ * prelude minification for `@function` rules and generic whitespace handling
+ * for other unknown at-rules.
+ *
+ * @param  {object} rule     The AST at-rule node with name, prelude, and rules.
+ * @param  {object} context  The minification context.
+ * @return {string}          The minified at-rule CSS string, or empty string if body is empty.
+ */
+function stringifyAtRule (rule, context) {
+  let minifiedPrelude;
+  if (rule.name === 'function') {
+    minifiedPrelude = minifyFunctionPrelude(rule.prelude || '');
+  } else {
+    // Collapse runs of whitespace to a single space for generic at-rules
+    minifiedPrelude = (rule.prelude || '').trim().replace(/\s+/g, ' ');
+  }
+
+  const bodyItems = (rule.rules || []).filter((item) => {
+    return item.type !== 'whitespace';
+  });
+  if (bodyItems.length === 0) {
+    return '';
+  }
+
+  const declarations = bodyItems.filter((item) => {
+    return item.type === 'declaration' && item.property;
+  });
+  const nestedRules = bodyItems.filter((item) => {
+    return item.type !== 'declaration';
+  });
+
+  const renderedDeclarations = stringifyDeclarations(declarations);
+  const renderedNestedRules = stringifyChildRules(nestedRules, context);
+  const body = [renderedDeclarations, renderedNestedRules].filter(Boolean).join('');
+  if (!body) {
+    return '';
+  }
+
+  const separator = minifiedPrelude ? ' ' : '';
+  return '@' + rule.name + separator + minifiedPrelude + '{' + body + '}';
+}
+
 /**
  * Processes a bare `:is()` selector by merging `:link`+`:visited` into `:any-link`,
  * de-duplicating, sorting alphabetically, and conditionally expanding into individual
@@ -543,6 +638,19 @@ function stringifyRule (rule, context, nested = false) {
     return '@position-try ' + rule.name + '{' + renderedDeclarations + '}';
   }
 
+  if (rule.type === 'document') {
+    const children = stringifyChildRules(rule.rules, context);
+    if (!children) {
+      return '';
+    }
+    const vendor = rule.vendor || '';
+    const condition = (rule.document || '')
+      .trim()
+      // Remove spaces between document condition function calls (e.g. "), " → ",")
+      .replace(/\)\s*,\s*/g, '),');
+    return '@' + vendor + 'document ' + condition + '{' + children + '}';
+  }
+
   if (rule.type === 'comment') {
     if (rule.comment.startsWith('!')) {
       return '/*' + rule.comment + '*/';
@@ -550,6 +658,10 @@ function stringifyRule (rule, context, nested = false) {
     return '';
   }
 
+  if (rule.type === 'at-rule') {
+    return stringifyAtRule(rule, context);
+  }
+
   return ''; // Ignore unknown for now
 }