@lanexio/parser-grammar-css

This page documents @lanexio/parser-grammar-css, the CSS grammar package implementing CSS Syntax Module Level 3 with two-pass tokenization and tree construction.

• Version: Stable
• Module name: parser-grammar-css
• Package: @lanexio/parser-grammar-css
• Import path: @lanexio/parser-grammar-css
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse CSS stylesheets into a flat AST.

Layer contract

Layer 2 dependency rules

This package depends only on Layer 1 core packages. It does not import from query, bridge, devtools, or entry packages. Grammar packs never depend on other grammar packs.

When to use this module

• You need to parse CSS stylesheets into a traversable AST.
• You need to extract CSS from HTML documents (inline <style> blocks).
• You need to validate CSS property values.
• You need a spec-conformant CSS object-model projection (use cssConformanceGrammar).

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseCssOptions
Outputs	LexTree (flat AST rooted at CssKind.Stylesheet)
Side effects	None
Determinism	Yes
External dependencies	@lanexio/parser-core
Never-throw guarantee	Yes
Security surface	None (parse only, no output generation)

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-css

   npm

   npm install @lanexio/parser-grammar-css

   yarn

   yarn add @lanexio/parser-grammar-css

2. Import the named export.

   import { parseCss } from '@lanexio/parser-grammar-css';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

import { parseCss } from '@lanexio/parser-grammar-css';

const encoder = new TextEncoder();
const bytes = encoder.encode('body { color: red; font-size: 16px; }');

const tree = parseCss(bytes);

console.log(tree.nodeCount);
console.log(tree.root.kind);   // CssKind.Stylesheet

Comments preserved in tooling mode

import { parseCss, CssKind } from '@lanexio/parser-grammar-css';

const encoder = new TextEncoder();
const tree = parseCss(encoder.encode('/* header */\nbody { color: red; }'));

for (const node of tree.root.children()) {
  if (node.kind === CssKind.Comment) {
    console.log('comment found');
  }
}

Exports

Export	Type	Description
parseCss	(bytes: Uint8Array, options?: ParseCssOptions) => LexTree	Parse CSS. Never throws.
normalizeCSSInput	(bytes: Uint8Array) => Uint8Array	Normalize CSS input (CR/FF/CRLF to LF, surrogates to U+FFFD).
extractCSS	(tree: LexTree) => CSSExtract[]	Extract CSS from HTML document tree (style elements).
parseAllCSS	(html: LexTree, cssOptions?: ParseCssOptions) => LexTree	Parse all CSS found in HTML document.
validateValues	(tree: LexTree) => void	Validate CSS property values against known property list.
CssKind	const object	Numeric kind IDs for all CSS node types.
CssField	const object	Numeric field IDs for CSS value slots.
CSS_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
CSS_KIND_NAMES_BY_ID	readonly Record<number, string>	Kind-name lookup by numeric ID.
cssGrammar	LanexioParserPureGrammar	Tooling grammar (preserves comments, whitespace).
cssConformanceGrammar	LanexioParserPureGrammar	Conformance grammar (strips trivia, conformant CSSOM projection).
cssRegistration	GrammarRegistration	Registration for the unified grammar registry.
cssReuseOracle	ReuseOracle	Incremental reuse oracle for CSS.
DECL_FLAG_IMPORTANT	number	Flag for !important declarations.
TOKEN_NAMES	object	Token type names for CSS tokenizer.
getTokenMetadata	(token: number) => TokenMeta	Get metadata for a CSS token type.

Options

ParseCssOptions

Field	Type	Required	Default	Description
conformance	boolean	No	undefined	When true, produce spec-conformant CSSOM projection (omit comments, whitespace. discard invalid rules).
validateProperties	boolean	No	undefined	When true, flag unknown property names with LEX_NODE_HAS_ERROR.

Return shape

Property	Type	Description
root	LexNode	Root node (CssKind.Stylesheet).
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes (after normalization).

Exported types

Type	Purpose	Notes
ParseCssOptions	Options for parseCss	{ conformance?: boolean; validateProperties?: boolean }
CssKindType	Union of all CssKind values	Type-safe kind reference
CssFieldType	Union of all CssField values	Type-safe field reference
CSSExtract	Extracted CSS from HTML	Contains CSS source and position info
TokenMeta	Metadata for a CSS token type	Token classification

Configuration and Extension

Tooling vs Conformance mode

The default cssGrammar preserves comments, whitespace, and unknown at-rules for tooling workflows. Use cssConformanceGrammar for a spec-conformant CSS object model projection that strips trivia and discards invalid rules.

CSS extraction

extractCSS finds <style> elements in an HTML tree and returns their CSS source. parseAllCSS combines extraction and parsing in a single step.

Accessibility

Accessibility requirements

• No direct accessibility surface. The CSS parser produces flat AST data structures.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (stylesheet format)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• parseCss never throws on any byte sequence.
• parseCss does not validate property values against known CSS property lists.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce CssKind.Error AST nodes	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser	Consumes	6	Unified entry point

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

Parsing CSS Guide: parse CSS with options and kind constants.

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.