muskitty-html5-parser
A from-scratch HTML5 parser written in pure Rust, implementing the WHATWG HTML Living Standard with zero runtime dependencies.
Part of the MusKitty browser engine project.
Status
| Component | Spec Coverage | Test Pass Rate |
|---|---|---|
| Tokenizer (§13.2.5) | 85/85 states | 99.8% (7022/7036) |
| Tree Construction (§13.2.6) | 21/21 insertion modes | 100% (1716/1716) |
- Zero
unsafecode - Zero C/C++ dependencies
- Rust stable toolchain only
- html5lib-tests suite as ground truth
Installation
Add this to your Cargo.toml:
[]
= "0.1.0"
Or run:
Quick Start
use parse;
let document = parse;
// Returns an Rc<RefCell<Node>> DOM tree
Architecture
muskitty-html5-parser/
src/
tokenizer/
types.rs Token, TagToken, DoctypeToken, State definitions
trait_def.rs Tokenizer trait (supports reentrancy)
impls.rs HtmlTokenizer — 85-state machine (~6000 lines)
entities.rs 2231 WHATWG named character references
parser/
mod.rs HtmlTreeConstructor entry point
dispatch.rs Insertion mode dispatcher (21 modes)
helpers.rs Scope checks, foster parenting, adoption agency
insertion_mode.rs InsertionMode enum
foreign.rs SVG/MathML foreign content handling
dom/ DOM node types (via muskitty-dom)
lib.rs Public API: parse() entry point
Two-Stage Pipeline
Input codepoints → Tokenizer (§13.2.5) → Token stream → Tree Construction (§13.2.6) → DOM
- Tokenizer: Deterministic state machine consuming Unicode codepoints, emitting Tokens (Doctype, Tag, Comment, Character, EOF, ProcessingInstruction).
- Tree Construction: Consumes Tokens, applies insertion mode logic, builds DOM tree using open elements stack, active formatting elements, and foster parenting.
What's Implemented
Tokenizer (§13.2.5)
- All 85 tokenization states
- Content model switching (RCDATA, RAWTEXT, ScriptData, PLAINTEXT)
- Character reference resolution (named + numeric, decimal + hex)
- 2231 WHATWG named entities with binary search lookup
- Windows-1252 replacement table
- Processing instruction states
- CDATA section states (foreign content)
- Reentrant design: tree construction can pause/resume tokenizer
Tree Construction (§13.2.6)
- All 21 insertion modes
- Adoption agency algorithm (formatting elements)
- Foster parenting (table context)
- Foreign content (SVG/MathML) with namespace handling
- Template insertion mode
- Reset insertion mode
- Scope checks (button, list, table, default)
Building
Testing
# Unit tests (145 tests)
# html5lib tokenizer suite (7036 tests)
# html5lib tree construction suite (1920 tests, 1716 non-skipped)
# All tests
Test Fixtures
Tests use the html5lib-tests suite:
tests/data/tokenizer/*.test— 14 tokenizer fixture filestests/data/tree_construction/*.test— 68 tree construction fixture files
Design Principles
- WHATWG is ground truth — Implementation follows the spec exactly. WPT and Chromium are secondary references.
- 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.
- Minimal dependencies — Only
muskitty-dom(sibling crate) andserde_json(dev-dependency for test fixtures). - Zero unsafe — Pure safe Rust.
- Surgical changes — Every diff is as small as the task requires.
Spec Reference
This implementation references:
- WHATWG HTML Living Standard — Primary authority
- §13.2.5: Tokenization
- §13.2.6: Tree Construction
- html5lib-tests — Test ground truth
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Copyright 2026 MusCat / MusKitty Bit-Torch Community