fix: remove all as any casts, add rawSource to types, make CssWhitespaceAST extend CssCommonPositionAST, remove unused closeWithPos, update docs

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

Author: Copilot

README.md

@@ -55,7 +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`)
+  - `preserveFormatting` (boolean) - Insert whitespace AST nodes and store raw formatting properties for identity round-trip (default: `false`)
 
 **Returns:** `CssStylesheetAST` - The parsed CSS as an AST
 

docs/API.md

@@ -22,7 +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`
+  - `preserveFormatting` (boolean) - Insert whitespace AST nodes and store raw formatting properties on nodes for identity round-trip. When `true`, whitespace between siblings is preserved as `CssWhitespaceAST` nodes, and raw formatting properties (`rawPrelude`, `rawBetween`, `rawValue`, `rawSource`) are stored on relevant nodes. Default: `false`
 
 #### Returns
 
@@ -54,7 +54,7 @@ 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`
+  - `identity` (boolean) - Reproduce the original CSS exactly as parsed. Requires `preserveFormatting: true` during parsing. Walks the AST including whitespace nodes and uses raw formatting properties to reconstruct the original output. Inserted or modified nodes without raw properties are emitted in beautified format. Falls back to beautified output when `preserveFormatting` was not used. Default: `false`
   - `removeEmptyRules` (boolean) - Remove rules with empty declaration blocks from the output. Works in all modes (beautified, compressed, identity). Default: `false`
 
 #### Returns
@@ -95,9 +95,8 @@ type CssStylesheetAST = {
   type: CssTypes.stylesheet;
   stylesheet: {
     source?: string;
-    rules: CssRuleAST[];
+    rules: Array<CssAtRuleAST | CssWhitespaceAST>;
     parsingErrors?: CssParseError[];
-    originalSource?: string; // Set when preserveFormatting is true
   };
 };
 ```
@@ -163,12 +162,10 @@ 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
   };
 };
 ```

docs/AST.md

@@ -18,14 +18,12 @@ Position information for the node in the source code:
 
 ```typescript
 {
-  start: { line: number; column: number; offset?: number };
-  end: { line: number; column: number; offset?: number };
+  start: { line: number; column: number };
+  end: { line: number; column: 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,9 +36,8 @@ The root node representing an entire CSS document.
 
 **Properties:**
 - `stylesheet.source` (optional): Source file path
-- `stylesheet.rules`: Array of top-level rules
+- `stylesheet.rules`: Array of top-level rules (may include `whitespace` nodes when `preserveFormatting: true`)
 - `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
@@ -109,6 +106,21 @@ A CSS comment.
 }
 ```
 
+### `whitespace`
+
+A whitespace node that preserves original formatting between sibling nodes. Only present when `preserveFormatting: true` is used during parsing.
+
+**Properties:**
+- `value`: The whitespace text (spaces, newlines, tabs, etc.)
+
+**Example:**
+```json
+{
+  "type": "whitespace",
+  "value": "\n\n"
+}
+```
+
 ### `media`
 
 A `@media` rule.
@@ -367,3 +379,39 @@ This is useful for:
 - Source mapping
 - Code analysis tools
 - IDE integration
+
+## Formatting Properties (`preserveFormatting: true`)
+
+When parsing with `preserveFormatting: true`, the parser stores additional formatting metadata on AST nodes to support exact round-trip via identity mode. These properties are optional and only present when formatting is preserved.
+
+### Whitespace Nodes
+
+`CssWhitespaceAST` nodes are inserted between sibling nodes in all arrays (rules, declarations, keyframes) to preserve the original whitespace and line breaks.
+
+### Raw Properties on Nodes
+
+- **`rawPrelude`** (on rules, at-rules with blocks): The exact original text before `{`, preserving whitespace between selector/condition and brace
+- **`rawBetween`** (on declarations): The text between the property name and value, including `:` and any surrounding whitespace (e.g., `": "` or `":  "`)
+- **`rawValue`** (on declarations): The untrimmed original value text
+- **`rawSource`** (on statement at-rules: import, charset, namespace, custom-media, layer statement): The exact original text of the entire at-rule
+
+### AST Modification with Identity Mode
+
+Because formatting data is stored per-node rather than as a single cached string, you can freely insert, remove, or modify AST nodes and identity mode will reflect the changes:
+
+```typescript
+const ast = parse(css, { preserveFormatting: true });
+
+// Insert a new rule — it will be beautified since it has no raw properties
+ast.stylesheet.rules.push({
+  type: CssTypes.rule,
+  selectors: ['.new'],
+  declarations: [{ type: CssTypes.declaration, property: 'color', value: 'blue' }]
+});
+
+// Remove a rule — the surrounding whitespace nodes naturally adapt
+ast.stylesheet.rules.splice(1, 1);
+
+// Identity mode outputs original formatting for untouched nodes + beautified for new nodes
+stringify(ast, { identity: true });
+```

docs/CHANGELOG.md

@@ -8,12 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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 `preserveFormatting` parser option to insert whitespace AST nodes and store raw formatting properties for identity round-trip
+- Add `CssTypes.whitespace` node type (`CssWhitespaceAST`) to represent whitespace between sibling nodes
+- Add `identity` compiler option to reproduce original CSS exactly as parsed (round-trip fidelity), with support for AST modifications
 - 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
+- Add raw formatting properties: `rawPrelude`, `rawBetween`, `rawValue`, `rawSource` on relevant AST nodes
+- Export `CompilerOptions`, `ParseOptions`, and `CssWhitespaceAST` types from the public API
 
 ## [4.4.4] - 2025-07-22
 

src/parse/index.ts

@@ -232,14 +232,6 @@ export const parse = (
     return { ok: lexer.tryOpenBrace(), afterOpen };
   }
 
-  /**
-   * Track brace position and call close().
-   */
-  function closeWithPos(): { ok: boolean; beforeClose: number } {
-    const beforeClose = lexer.pos;
-    return { ok: lexer.tryCloseBrace(), beforeClose };
-  }
-
   /**
    * Closing brace.
    */

src/stringify/compiler.ts

@@ -338,8 +338,8 @@ class Compiler {
         this.emit('}')
       );
     }
-    if (this.identity && !node.rules && (node as any).rawSource) {
-      return this.emit((node as any).rawSource, node.position);
+    if (this.identity && !node.rules && node.rawSource) {
+      return this.emit(node.rawSource, node.position);
     }
     const rules = node.rules
       ? this.stripWhitespace(<CssAllNodesAST[]>node.rules)
@@ -364,8 +364,8 @@ class Compiler {
    * Visit import node.
    */
   import(node: CssImportAST) {
-    if (this.identity && (node as any).rawSource) {
-      return this.emit((node as any).rawSource, node.position);
+    if (this.identity && node.rawSource) {
+      return this.emit(node.rawSource, node.position);
     }
     return this.emit(`@import ${node.import};`, node.position);
   }
@@ -416,8 +416,8 @@ class Compiler {
    * Visit charset node.
    */
   charset(node: CssCharsetAST) {
-    if (this.identity && (node as any).rawSource) {
-      return this.emit((node as any).rawSource, node.position);
+    if (this.identity && node.rawSource) {
+      return this.emit(node.rawSource, node.position);
     }
     return this.emit(`@charset ${node.charset};`, node.position);
   }
@@ -426,8 +426,8 @@ class Compiler {
    * Visit namespace node.
    */
   namespace(node: CssNamespaceAST) {
-    if (this.identity && (node as any).rawSource) {
-      return this.emit((node as any).rawSource, node.position);
+    if (this.identity && node.rawSource) {
+      return this.emit(node.rawSource, node.position);
     }
     return this.emit(`@namespace ${node.namespace};`, node.position);
   }
@@ -631,8 +631,8 @@ class Compiler {
    * Visit custom-media node.
    */
   customMedia(node: CssCustomMediaAST) {
-    if (this.identity && (node as any).rawSource) {
-      return this.emit((node as any).rawSource, node.position);
+    if (this.identity && node.rawSource) {
+      return this.emit(node.rawSource, node.position);
     }
     return this.emit(
       `@custom-media ${node.name} ${node.media};`,

src/type.ts

@@ -41,11 +41,9 @@ export type CssCommonPositionAST = CssCommonAST & {
   parent?: unknown;
 };
 
-export type CssWhitespaceAST = CssCommonAST & {
+export type CssWhitespaceAST = CssCommonPositionAST & {
   type: CssTypes.whitespace;
   value: string;
-  position?: Position;
-  parent?: unknown;
 };
 
 export type CssStylesheetAST = CssCommonAST & {
@@ -88,11 +86,13 @@ export type CssContainerAST = CssCommonPositionAST & {
 export type CssCharsetAST = CssCommonPositionAST & {
   type: CssTypes.charset;
   charset: string;
+  rawSource?: string;
 };
 export type CssCustomMediaAST = CssCommonPositionAST & {
   type: CssTypes.customMedia;
   name: string;
   media: string;
+  rawSource?: string;
 };
 export type CssDocumentAST = CssCommonPositionAST & {
   type: CssTypes.document;
@@ -114,6 +114,7 @@ export type CssHostAST = CssCommonPositionAST & {
 export type CssImportAST = CssCommonPositionAST & {
   type: CssTypes.import;
   import: string;
+  rawSource?: string;
 };
 export type CssKeyframesAST = CssCommonPositionAST & {
   type: CssTypes.keyframes;
@@ -133,6 +134,7 @@ export type CssLayerAST = CssCommonPositionAST & {
   layer: string;
   rules?: Array<CssAtRuleAST | CssDeclarationAST | CssWhitespaceAST>;
   rawPrelude?: string;
+  rawSource?: string;
 };
 export type CssMediaAST = CssCommonPositionAST & {
   type: CssTypes.media;
@@ -143,6 +145,7 @@ export type CssMediaAST = CssCommonPositionAST & {
 export type CssNamespaceAST = CssCommonPositionAST & {
   type: CssTypes.namespace;
   namespace: string;
+  rawSource?: string;
 };
 export type CssPageAST = CssCommonPositionAST & {
   type: CssTypes.page;