docs(v7): Parser header shows forward‑compat signature; clarify CommonJS on Node >=20.19 can require ESM

Author: CharlieHelps

README.md

@@ -27,7 +27,7 @@ npm install postcss-values-parser --save-dev
 - Node.js >= 20.19.0
 - PostCSS >= 8.4.14 (peer dependency)
 
-Note: This package is ESM‑only. Use `import` in Node.js. In CommonJS on Node.js 20.19.0+ you can `require()` it:
+Note: This package is ESM‑only. Use `import` in Node.js. In CommonJS on Node >= 20.19.0 you can `require()` it:
 
 ```js
 // CommonJS (Node >= 20.19.0)

docs/Parser.md

@@ -2,9 +2,11 @@
 
 The parser converts CSS value strings into an Abstract Syntax Tree (AST). It uses [css-tree](https://github.com/csstree/csstree) under the hood, then maps css-tree nodes to this package’s node classes.
 
-## parse(css)
+## parse(css, options?)
 
-Converts a CSS value string into an AST with a `Root` node.
+Converts a CSS value string into an AST with a `Root` node. The optional
+`options` parameter is accepted for forward‑compatibility in v7 but is
+currently ignored.
 
 ### Parameters
 
@@ -13,6 +15,7 @@ Converts a CSS value string into an AST with a `Root` node.
 Type: `string` (required)
 
 Any valid CSS value string, such as:
+
 - `10px solid red`
 - `calc(100% - 20px)`
 - `rgba(255, 0, 0, 0.5)`
@@ -68,12 +71,14 @@ Unknown or unrecognized node types are parsed as `Word` nodes to ensure the pars
 #### Source mapping
 
 The parser preserves source locations from the original CSS string, including:
+
 - Line and column positions
 - Start and end offsets
 - Original source text
 
 ```js
 import { parse } from 'postcss-values-parser';
+
 const root = parse('calc(100px + 20%)');
 // Each node maintains source position information
 ```
@@ -103,7 +108,7 @@ try {
 Thrown when the parsed AST is invalid or empty:
 
 ```js
-import { parse, AstError } from 'postcss-values-parser';
+import { AstError, parse } from 'postcss-values-parser';
 
 try {
   const root = parse('');
@@ -122,9 +127,9 @@ The parser creates nodes using the NodeOptions interface:
 
 ```typescript
 interface NodeOptions {
-  node?: CssNode;    // Original css-tree node
-  value?: string;    // String value
-  parent?: any;      // Parent node
+  node?: CssNode; // Original css-tree node
+  value?: string; // String value
+  parent?: any; // Parent node
 }
 ```
 
@@ -157,6 +162,7 @@ console.log(calcFunc.nodes.length); // Contains parsed parameters
 ## Browser and Environment Support
 
 The parser works in all environments where css-tree is supported:
+
 - Node.js (all supported versions)
 - Modern browsers (ES2015+)
 - Webpack/Rollup bundled applications
@@ -168,7 +174,7 @@ The parser works in all environments where css-tree is supported:
 
 ```js
 const root = parse('10px solid red');
-console.log(root.nodes.map(n => n.type)); // ['numeric', 'word', 'word']
+console.log(root.nodes.map((n) => n.type)); // ['numeric', 'word', 'word']
 ```
 
 ### Function Parsing
@@ -184,7 +190,7 @@ console.log(func.isColor); // true
 
 ```js
 const root = parse('calc(100% - 20px) url("bg.jpg") center/cover');
-root.walkFuncs(func => {
+root.walkFuncs((func) => {
   console.log(`Function: ${func.name}`);
 });
 ```

docs/README.md

@@ -16,7 +16,12 @@ Please see the [Exports](./Exports.md) documentation for further information.
 
 Parsing is powered by [css-tree](https://github.com/csstree/csstree). Nodes in this package extend PostCSS `Node`/`Container`/`Root` so the API feels familiar, but there is no PostCSS parser involved.
 
-> Note: This package is ESM‑only. Use `import` syntax in Node.js. If you must use CommonJS, load it via dynamic import: `const mod = await import('postcss-values-parser')`.
+> Note: This package is ESM‑only. Use `import` syntax in Node.js. In CommonJS on Node >= 20.19.0 you can `require()` ESM packages:
+>
+> ```js
+> // CommonJS (Node >= 20.19.0)
+> const { parse } = require('postcss-values-parser');
+> ```
 
 ## Nodes