Skip to content
James Conway edited this page Nov 19, 2026 · 20 revisions

Parsec: a line-drawn rocket leaving HTML tags in its exhaust

Parsec is an HTML parser written in Rust. It reads a page the way a browser does, following the WHATWG HTML Standard, gives you a tree you can walk and change, finds what you're after with CSS selectors from Selectors Level 4, and writes the tree back out as HTML.

It's being built for the people who use Lexbor today, directly or through selectolax, PHP's Dom\HTMLDocument, nokolexbor or lazy_html. Lexbor is fast and follows the spec. What Parsec adds, or plans to, is the list Lexbor's users keep asking for: positions on nodes, a worst case that doesn't blow up, documents you can share across threads, XPath, selectors that match everything a static page can decide, and memory safety.

This wiki is Parsec's only documentation. There's no website and no rustdoc site yet, so the reference pages here list every public item, taken from the source on main.

Where things stand

Note

Parsec isn't released. There's nothing on crates.io yet, and the API can still change before 0.1.0.

You depend on it from git:

[dependencies]
parsec-html = { git = "https://github.com/parsec-html/parsec" }

The package is parsec-html; the crate you use is parsec. You need Rust 1.88 or newer.

use parsec::css::SelectorList;

let doc = parsec::parse("<ul><li class=hit>one<li>two</ul>", false);
let hits = SelectorList::parse("li.hit").unwrap().select(&doc, doc.root());
assert_eq!(doc.text(hits[0]), "one");

What works today, and what's next

Everything marked ✅ ships on main, and cargo test checks it. The rest has an issue and a milestone, and Roadmap has the order.

Area Where it stands
✅ Whole documents The HTML Standard's tokenizer and tree builder, scripting on or off. Passes the html5lib tokenizer suite and every web-platform-tests tree-construction case that doesn't need JavaScript; Conformance has the counts.
✅ Fragments Parsed in the context of any element as innerHTML does, SVG and MathML included. See Parsing.
✅ A tree you can walk Nodes in one arena, addressed by NodeId, with parent, child and sibling links. See The document tree.
✅ Editing Create, insert, move and remove nodes; set, add, rename and remove attributes; rename elements. See Editing.
✅ Serialization innerHTML, outerHTML, a start tag alone, or text. See Serialization.
✅ CSS selectors from Level 4 :has(), :is(), :where(), :not() with lists, :nth-child(An+B of S), :scope, :lang(), :dir(), attribute case flags, the form states and validity (:valid, :in-range, :default and the rest); :target and :local-link given the page's URL; queries that stop at the first match, and specificity. See Selectors.
✅ The tokenizer on its own Feeding a Sink you write. See Tokenizer.
✅ Bytes in, encoding sniffed parse_bytes finds the encoding from the BOM, the HTTP charset, the <meta> prescan or a fallback, and reparses once if a later <meta> disagrees with a guess. Passes the html5lib encoding/ cases. See Encoding.
✅ Every encoding the web uses Decoding and encoding through encoding_rs, Firefox's implementation, passing the web-platform-tests encoding data. See Encoding.
✅ WHATWG URL parsec-url: every getter and setter of URL, URLSearchParams, IDNA, Punycode and Unicode normalization, in a parser of its own that passes all 4,565 web-platform-tests URL cases and beats Ada on real links. See URL.
✅ A C API Shared and static libraries, parsec.h, pkg-config and CMake files, with prebuilt packages for Linux, macOS and Windows, x86-64 and ARM, built for each release. Opaque handles, node numbers that can't dangle, and error codes. See C API.
✅ Limits you choose A time budget per parse, a maximum tree depth, and a fixed cap on input size. See Limits and hostile input.
✅ Declarative shadow DOM <template shadowrootmode> attaches a shadow root as browsers do, with slots, the flat tree, :host and ::slotted(); all 7,590 WPT declarative shadow DOM cases pass. See Shadow DOM.
✅ Chunked input Parser::feed and finish build exactly the tree the whole page would, tested at every cut of every test input. See Parsing.
✅ Parse errors With the HTML Standard's names, byte offset, line and column. See Parsing.
✅ Source positions A byte range for every node and attribute, with line and column. See Parsing.
✅ A Python package selectolax's API, documents shared across threads, free-threaded Python with the GIL off, plus XPath that answers as lxml's does, positions and parse errors; pytest checks it in CI. See Python. Wheels go to PyPI with 0.1.0.
✅ WebAssembly The npm package parsec-html, with TypeScript types, XPath, spans and parse errors; tested in Node and Firefox. See WASM. It goes to npm with 0.1.0.
✅ XPath XPath 1.0 in parsec-xpath, shared with Netweir, passing libxml2's expression tests; a work limit stops queries that stay quadratic. See XPath.
✅ CSS Syntax parsec-html-css: the tokenizer, every parser entry point of the current draft with nesting, An+B, <urange> and serialization, with a byte span on every rule, declaration and token. Passes css-parsing-tests but for 12 cases that predate the draft, and every CSS tokenizer test. See CSS.
✅ Typed CSS values Every property in the specs (822, generated from w3c/webref), each value parsed against its grammar; units, math functions, CSS Color 4 and most of 5; shorthands into longhands; custom properties and var(). Each value written in the shortest form CSSOM gives it. 14,758 of WPT's 14,893 static CSS parsing cases pass. See CSS values.
✅ The cascade, media queries, computed values Origins, layers, specificity, !important and style="" on a Parsec document; @media and @supports against an environment you give; @scope, @container against sizes you give, with style() ranges and container query units, @import through your fetch, @property; @keyframes and @counter-style parsed; computed values as getComputedStyle() writes them, for pseudo-elements too (::before, ::after, ::marker, ::first-line and the rest). All 1,370 of WPT's media query cases pass, and 11,356 of its 12,111 computed-value cases. See Cascade.

The marks mean the same on every page of this wiki:

  • ✅ shipped, and cargo test checks it;
  • 🚧 in progress;
  • 📋 planned, with an issue.

Parsec has one dependency (memchr) and one unsafe block. That's a fact about the code rather than something a test checks, so it gets no mark; Thread safety and memory safety explains both. Comparison with Lexbor lays the whole picture out module by module.

Page map

Start here

  • Getting started: add Parsec, parse, select, read, edit, write out.
  • FAQ
  • Glossary: the HTML Standard's terms, and Parsec's own, in a sentence or two each.

Reference

  • Parsing: parse, parse_with, Options, ParseError, MAX_INPUT, parse_fragment, quirks, scripting, input.
  • The document tree: Document, NodeId, Kind, Ns, AttrNs, Quirks, navigation, attributes, templates, the name helpers.
  • Editing: every edit function, EditError, and the rules edits keep.
  • Serialization: inner_html, outer_html, html_alone, text.
  • Selectors: what parses, what matches, what's refused, and where Lexbor differs.
  • Tokenizer: Tokenizer, Sink, TextMode, Tag, Attrs, Doctype, preprocess.
  • CSS: parsec-html-css, CSS Syntax Level 3: every entry point, the tree, spans and lines, An+B, serialization, its suite counts and every case it fails.
  • Cascade: parsec_css::cascade, ::media and ::supports: styling a document, media queries, @supports, computed values, the WPT counts and what fails.
  • CSS values: parsec_css::values: the property table, typed values, colors, math functions, shorthands, custom properties and var(), with WPT's counts and what fails.
  • URL: parsec-url's Url, SearchParams, IDNA, Punycode and normalization, how it's built, its WPT counts and its speed.
  • Python: parsec_html, the selectolax-style package: HTMLParser, Node, Attributes, threads, and what differs from selectolax.
  • C API: parsec.h, linking with CMake or pkg-config, ownership and strings, every function and status code.

How it works

Coming from Lexbor

The project

  • Contributing: the Netweir sync, building, testing, fuzzing, the CLA.
  • Roadmap
  • Changelog: what's on main, and every release once there is one.

See also

Clone this wiki locally