zhtml

High-throughput HTML parser + CSS selector engine for Zig.

⚠️ Conformance Warning

Performance numbers are not conformance claims. The parser is intentionally permissive and currently does not fully match browser-grade tree-construction behavior.

• Conformance details: Documentation#conformance-status
• Benchmark methodology: Documentation#performance-and-benchmarks
• Raw outputs: bench/results/latest.md, bench/results/latest.json

🏁 Performance

See the latest benchmark snapshot for more details

Source: bench/results/latest.json (stable profile).

Parse Throughput (Average Across Fixtures)

ours-compact │████████████████████│ 1736.88 MB/s (100.00%)
ours-full    │███████████████████░│ 1671.17 MB/s (96.22%)
lol-html     │███████████░░░░░░░░░│ 993.44 MB/s (57.20%)

Conformance Snapshot

Profile	nwmatcher	qwery_contextual	html5lib subset	WHATWG HTML parsing
strictest/fastest	20/20 (0 failed)	54/54 (0 failed)	524/600 (76 failed)	440/500 (60 failed)

Source: bench/results/external_suite_report.json

⚡ Features

• 🔎 CSS selector queries: comptime, runtime, and cached runtime selectors.
• 🧭 DOM navigation: parent, siblings, first/last child, and children iteration.
• 💤 Lazy decode/normalize path: attribute/entity decode and text normalization happen on query-time APIs.
• 🧪 Debug tooling: selector mismatch diagnostics and instrumentation wrappers.
• 🧰 Parse profiles: strictest and fastest option bundles for benchmarks/workloads.
• 🧵 Destructive parsing by default for throughput, with an opt-in non-destructive read-only mode.

🚀 Quick Start

const std = @import("std");
const html = @import("html");
const options: html.ParseOptions = .{};

test "basic parse + query" {
    var input = "<div id='app'><a class='nav' href='/docs'>Docs</a></div>".*;
    var doc = try options.parse(std.testing.allocator, &input);
    defer doc.deinit();

    var links = doc.query("div#app > a.nav");
    const a = links.next() orelse return error.TestUnexpectedResult;
    const href = (try a.getAttributeValue(std.testing.allocator, "href")) orelse return error.TestUnexpectedResult;
    defer href.free(&doc, std.testing.allocator);
    try std.testing.expectEqualStrings("/docs", href.value);
}

Parsing goes through options.parse(...). Use const options: html.ParseOptions = .{ .non_destructive = true }; when the caller bytes must remain unchanged, including file-backed memory maps. This mode reads the original source directly and does not make a full-source copy.

Raw nodes are compact by default. store_last_child enables O(1) children().last(), while store_prev_sibling enables O(1) previous-sibling traversal instead of fallback scans.

⚙️ Build Configuration

• -Dintlen=u16|u32|u64|usize selects the integer width used for document spans and node indexes.
• Smaller widths reduce memory use but also reduce the maximum parseable input size.
• u32 is the default. Use u64 for multi-gigabyte inputs.

📚 Documentation

• Full manual: Documentation
• API details: Documentation#core-api
• Selector grammar: Documentation#selector-support
• Parse mode guidance: Documentation#mode-guidance
• Non-destructive parsing: Documentation#non-destructive-parsing
• Conformance: Documentation#conformance-status
• Architecture: Documentation#architecture
• Troubleshooting: Documentation#troubleshooting

🧪 Build and Validation

zig build test
zig build docs-check
zig build examples-check
zig build ship-check

📎 Examples

• examples/basic_parse_query.zig
• examples/runtime_selector.zig
• examples/cached_selector.zig
• examples/query_time_decode.zig
• examples/inner_text_options.zig
• examples/non_destructive_parse.zig

📜 License

MIT. See LICENSE.