muskitty-css-parser
A from-scratch CSS parser written in pure Rust, implementing the
parser layer of the CSS Syntax Module Level 3 §5
on top of muskitty-css-tokenizer.
Part of the MusKitty browser engine project.
Status
| Component | Spec Coverage | Test Pass Rate |
|---|---|---|
| Parser (§5) | 8 entry points + 13 consume algorithms | 62/62 tests |
- Zero
unsafecode - Zero C/C++ dependencies
- One runtime dependency:
muskitty-css-tokenizer - Rust stable toolchain only
- MSRV 1.82
Installation
Add this to your Cargo.toml:
[]
= "0.1.0"
Or run:
Quick Start
use ;
// Parse a full stylesheet (§5.4.3)
let ss = parse_stylesheet;
assert_eq!;
// Parse a single rule (§5.4.6)
let rule = parse_rule.unwrap;
assert!;
Architecture
muskitty-css-parser/
src/
types.rs Stylesheet, Rule, QualifiedRule, AtRule, Declaration,
ComponentValue, SimpleBlock, Function, ParseError, BlockKind
token_stream.rs TokenStream — §5.1 input stream wrapper over tokenizer
algorithms.rs §5.5 consume_* algorithms (qualified rule, at-rule,
declaration, simple block, function, unicode-range, etc.)
entry_points.rs §5.4 parse_* entry points
lib.rs Public API: 7 top-level functions + re-exports
What is a CSS Parser?
The CSS parser is the second stage of the two-stage model in CSS Syntax §3.1:
- Tokenization (delegated to
muskitty-css-tokenizer) — produces a token stream after §5.3 preprocessing. - Parsing (this crate) — consumes tokens and produces CSS objects such as stylesheets, rules, declarations, and component values.
The parser exposes 8 entry points (§5.4) and 13 consume algorithms (§5.5).
Spec Coverage
All §5 parser entry points and consume algorithms are implemented:
Entry points (§5.4):
- §5.4.1 Parse a stylesheet
- §5.4.2 Parse a list of rules
- §5.4.3 Parse a rule
- §5.4.4 Parse a declaration
- §5.4.5 Parse a list of declarations
- §5.4.6 Parse a component value
- §5.4.7 Parse a list of component values
- §5.4.8 Parse a comma-separated list of component values
Consume algorithms (§5.5):
- §5.5.1 Consume a stylesheet's contents
- §5.5.2 Consume a list of rules
- §5.5.3 Consume an at-rule
- §5.5.4 Consume a qualified rule
- §5.5.5 Consume a declaration
- §5.5.6 Consume the remnants of a bad declaration
- §5.5.7 Consume a list of component values
- §5.5.8 Consume a simple block
- §5.5.9 Consume a block's contents
- §5.5.10 Consume a component value
- §5.5.11 Consume a function
- §5.5.12 Consume a unicode-range value (referenced from §5.4.6)
Building
Testing
# Integration tests (55 tests across 6 files)
# Doctests (7 tests)
# All tests (62 tests)
Design Principles
- CSSWG is ground truth — Implementation follows the spec exactly.
- Spec-compliant, not test-compliant — Tests verify the code; code is never modified to pass a test unless the spec proves the test is wrong.
- Zero runtime dependencies (besides
muskitty-css-tokenizer) — Pure safe Rust. - Zero unsafe — Pure safe Rust.
- Surgical changes — Every diff is as small as the task requires.
Spec Reference
This implementation references:
- CSS Syntax Module Level 3 — Primary authority
- §3.1: CSS Parsing Overview (two-stage model)
- §5: Parser Algorithms (entry points + consume algorithms)
- §5.3: Input Stream Preprocessing (in tokenizer)
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Copyright 2026 MusCat / MusKitty Bit-Torch Community