docs: update documentation for identity mode, preserveFormatting, and removeEmptyRules

- README.md: add identity and removeEmptyRules usage examples, update parse/stringify option docs, update features list
- docs/API.md: document preserveFormatting parse option, identity and removeEmptyRules compiler options, update CssStylesheetAST and CssPosition types, add advanced usage examples
- docs/AST.md: document offset field on position nodes, document originalSource on stylesheet
- docs/EXAMPLES.md: add identity round-trip and removeEmptyRules examples
- docs/CHANGELOG.md: add Unreleased section with new features

Co-authored-by: jogibear9988 <364896+jogibear9988@users.noreply.github.com>

Author: Copilot

README.md

@@ -32,6 +32,16 @@ const formatted = stringify(ast, { indent: '  ' })
 // Minify output
 const minified = stringify(ast, { compress: true })
 // => "body{font-size:12px}"
+
+// Identity mode: round-trip CSS exactly as written
+const original = 'body  { font-size:  12px;  }'
+const ast2 = parse(original, { preserveFormatting: true })
+stringify(ast2, { identity: true }) === original // true
+
+// Remove empty rules
+const ast3 = parse('.empty {} .keep { color: red; }')
+stringify(ast3, { removeEmptyRules: true })
+// => ".keep {\n  color: red;\n}"
 ```
 
 ## API
@@ -45,6 +55,7 @@ Parses CSS code and returns an Abstract Syntax Tree (AST).
 - `options` (object, optional) - Parsing options
   - `silent` (boolean) - Silently fail on parse errors instead of throwing
   - `source` (string) - File path for better error reporting
+  - `preserveFormatting` (boolean) - Store source offsets and original CSS text for identity round-trip (default: `false`)
 
 **Returns:** `CssStylesheetAST` - The parsed CSS as an AST
 
@@ -57,6 +68,8 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - `options` (object, optional) - Stringification options
   - `indent` (string) - Indentation string (default: `'  '`)
   - `compress` (boolean) - Whether to compress/minify the output (default: `false`)
+  - `identity` (boolean) - Reproduce the original CSS exactly as parsed; requires `preserveFormatting` during parsing (default: `false`)
+  - `removeEmptyRules` (boolean) - Remove rules with empty declaration blocks (default: `false`)
 
 **Returns:** `string` - The formatted CSS string
 
@@ -65,7 +78,9 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - **Complete CSS Support**: All standard CSS features including selectors, properties, values, at-rules, and comments
 - **TypeScript Support**: Full type definitions for all AST nodes and functions
 - **Error Handling**: Configurable error handling with detailed position information
-- **Formatting Options**: Pretty print, minify, or custom formatting
+- **Formatting Options**: Pretty print, minify, identity (round-trip), or custom formatting
+- **Identity Round-Trip**: Parse and stringify CSS back to the exact original formatting
+- **Empty Rule Removal**: Optionally strip rules with empty declaration blocks
 - **Performance Optimized**: Efficient parsing and stringification for large CSS files
 - **Source Maps**: Track original source positions for debugging and tooling
 

docs/API.md

@@ -22,6 +22,7 @@ Parses CSS code and returns an Abstract Syntax Tree (AST).
 - `options` (object, optional) - Parsing options
   - `silent` (boolean) - Silently fail on parse errors instead of throwing. When `true`, errors are collected in `ast.stylesheet.parsingErrors`
   - `source` (string) - File path for better error reporting
+  - `preserveFormatting` (boolean) - Store source character offsets and original CSS text on the AST for identity round-trip. When `true`, position nodes include an `offset` field and `ast.stylesheet.originalSource` is set. Default: `false`
 
 #### Returns
 
@@ -53,6 +54,8 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - `options` (CompilerOptions, optional) - Stringification options
   - `indent` (string) - Indentation string (default: `'  '`)
   - `compress` (boolean) - Whether to compress/minify the output (default: `false`)
+  - `identity` (boolean) - Reproduce the original CSS exactly as parsed. Requires `preserveFormatting: true` during parsing. Falls back to beautified output when original source is not available. Default: `false`
+  - `removeEmptyRules` (boolean) - Remove rules with empty declaration blocks from the output. Works in all modes (beautified, compressed, identity). Default: `false`
 
 #### Returns
 
@@ -94,6 +97,7 @@ type CssStylesheetAST = {
     source?: string;
     rules: CssRuleAST[];
     parsingErrors?: CssParseError[];
+    originalSource?: string; // Set when preserveFormatting is true
   };
 };
 ```
@@ -159,10 +163,12 @@ type CssPosition = {
   start: {
     line: number;
     column: number;
+    offset?: number; // Set when preserveFormatting is true
   };
   end: {
     line: number;
     column: number;
+    offset?: number; // Set when preserveFormatting is true
   };
 };
 ```
@@ -188,8 +194,10 @@ Options for the stringifier.
 
 ```typescript
 type CompilerOptions = {
-  indent?: string;    // Default: '  '
-  compress?: boolean; // Default: false
+  indent?: string;          // Default: '  '
+  compress?: boolean;       // Default: false
+  identity?: boolean;       // Default: false
+  removeEmptyRules?: boolean; // Default: false
 };
 ```
 
@@ -290,6 +298,49 @@ console.log(compressed);
 // Output: .example{color:red;font-size:16px}
 ```
 
+### Identity Round-Trip
+
+Reproduce the original CSS exactly as it was written, preserving all whitespace, comments, and formatting:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = '.example  {  color:  red;  font-size:16px  }';
+
+// Parse with preserveFormatting to store original source
+const ast = parse(css, { preserveFormatting: true });
+
+// Stringify with identity mode to reproduce the original CSS
+const output = stringify(ast, { identity: true });
+console.log(output === css); // true
+```
+
+When `preserveFormatting` was not used during parsing, identity mode falls back to beautified output.
+
+### Removing Empty Rules
+
+Strip rules with empty declaration blocks from the output:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = '.empty {} .keep { color: red; }';
+const ast = parse(css);
+
+// Beautified without empty rules
+const output = stringify(ast, { removeEmptyRules: true });
+console.log(output);
+// Output:
+// .keep {
+//   color: red;
+// }
+
+// Also works with compressed mode
+const compressed = stringify(ast, { compress: true, removeEmptyRules: true });
+console.log(compressed);
+// Output: .keep{color:red;}
+```
+
 ## TypeScript Integration
 
 The library provides comprehensive TypeScript support with full type definitions for all AST nodes and functions:

docs/AST.md

@@ -18,12 +18,14 @@ Position information for the node in the source code:
 
 ```typescript
 {
-  start: { line: number; column: number };
-  end: { line: number; column: number };
+  start: { line: number; column: number; offset?: number };
+  end: { line: number; column: number; offset?: number };
   source?: string;
 }
 ```
 
+The `offset` field is a character offset into the original source string, present when `preserveFormatting: true` is used during parsing.
+
 ### `parent` (optional)
 
 Reference to the parent node in the AST.
@@ -38,6 +40,7 @@ The root node representing an entire CSS document.
 - `stylesheet.source` (optional): Source file path
 - `stylesheet.rules`: Array of top-level rules
 - `stylesheet.parsingErrors` (optional): Array of parse errors when `silent` option is used
+- `stylesheet.originalSource` (optional): The original CSS source string, present when `preserveFormatting: true` is used during parsing
 
 **Example:**
 ```json

docs/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Add `preserveFormatting` parser option to store source character offsets and original CSS text on the AST
+- Add `identity` compiler option to reproduce original CSS exactly as parsed (round-trip fidelity)
+- Add `removeEmptyRules` compiler option to strip rules with empty declaration blocks
+- Add optional `offset` field to position `start`/`end` for source reconstruction
+- Add `originalSource` field to `CssStylesheetAST` for identity mode
+- Export `CompilerOptions` and `ParseOptions` types from the public API
+
 ## [4.4.4] - 2025-07-22
 
 ### Changed

docs/EXAMPLES.md

@@ -245,6 +245,53 @@ console.log(formatted);
 // }
 ```
 
+### Identity Round-Trip
+
+Reproduce the original CSS exactly as it was written, preserving all whitespace,
+comments, and formatting:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = `body  {
+  font-size:  12px;
+  color:  #333;
+}`;
+
+// Parse with preserveFormatting to store original source
+const ast = parse(css, { preserveFormatting: true });
+
+// Stringify with identity mode
+const output = stringify(ast, { identity: true });
+console.log(output === css); // true — exact round-trip
+```
+
+### Removing Empty Rules
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = `
+  .unused {}
+  .active { color: red; }
+`;
+
+const ast = parse(css);
+
+// Remove empty rules in beautified output
+const output = stringify(ast, { removeEmptyRules: true });
+console.log(output);
+// Output:
+// .active {
+//   color: red;
+// }
+
+// Also works with compressed mode
+const compressed = stringify(ast, { compress: true, removeEmptyRules: true });
+console.log(compressed);
+// Output: .active{color:red;}
+```
+
 ## Working with Complex CSS
 
 ### Nested Rules and At-Rules