rust_browser/README.md

rust_browser

A modular, experimental web browser engine and desktop shell written in Rust.

This repository is organized as a Cargo workspace with focused crates for HTML/CSS parsing, DOM, style, layout, rendering, networking, and a desktop app shell.

Current Status

rust_browser is under active development. The project prioritizes:

• correctness before performance
• deterministic behavior and testability
• clear crate boundaries for long-term maintainability

Implemented today includes:

• HTML parsing and DOM construction
• CSS parsing, selector matching, and core style computation
• block/inline layout, flexbox support, table support (partial)
• display-list generation and CPU rasterization path
• local file and HTTP loading
• golden tests and WPT-based external conformance harnessing

Workspace Layout

Top-level crates in crates/:

• app_browser: desktop app binary (app_browser)
• browser_runtime: navigation/session/runtime orchestration
• web_api: browser-facing API surface
• js, js_vm, js_parser: JavaScript stack
• dom, html, css, selectors, style: document/style pipeline
• layout, display_list, render, graphics: layout and rendering pipeline
• net, storage, image, fonts: resource and media subsystems
• platform: platform integration
• shared: shared types/utilities

See docs/browser_project_structure_modularization_guide.md for dependency layering and crate ownership rules.

Prerequisites

• Rust toolchain from rust-toolchain.toml (currently stable)
• just command runner

Install just if needed:

cargo install just

Build

cargo build -p app_browser

Run

Show CLI help:

cargo run -p app_browser -- --help

Open a URL in windowed mode:

cargo run -p app_browser -- https://example.com

Render an input file/URL to layout and display-list dumps:

cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html

Render and emit PNG:

cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html --png

Pipeline Overview

The browser pipeline is intentionally staged and deterministic:

1. browser_runtime receives a navigation request and tracks lifecycle/history state.
2. net loads content (HTTP or file) and returns response bytes.
3. html parses markup into a dom document tree.
4. css parses stylesheets and selectors matches rules to DOM nodes.
5. style computes final values (UA + author + inline cascade).
6. layout builds and resolves the layout tree (box geometry/flow).
7. display_list converts layout output into backend-agnostic draw commands.
8. render rasterizes draw commands to pixels, and platform presents them in a window.

In --render mode, steps 3-7 are written to artifact dumps (.layout.txt and .dl.txt) to make regressions easy to diff and review in tests.

Development Commands

Primary workflow commands are defined in justfile:

• just fmt: check formatting
• just lint: run clippy (warnings denied)
• just test: run workspace tests + WPT manifest expectation test
• just policy: enforce unsafe/dependency/file-size policy checks
• just metrics: report project metrics
• just ci: run full local CI pipeline (fmt, lint, test, policy, metrics)
• just regen-wpt: regenerate expected WPT outputs
• just import-wpt ...: import WPT reftests into fixture form
• just wpt-status ...: summarize WPT status

Testing Strategy

Testing combines multiple layers:

• unit tests in crate source modules
• integration tests in tests/
• golden rendering regression tests (tests/goldens)
• external conformance fixtures and WPT harnessing (tests/external/wpt)

Details: docs/browser_testing_strategy_high_level_to_detailed.md.

Architecture Notes

Initial architecture is deliberately conservative:

• interpreter-first semantics
• deterministic single-threaded core pipeline
• worker threads for I/O-oriented work
• display-list abstraction between layout/paint and rendering backend

Details: docs/browser_architecture_initial_exploration.md.

Contributing

General expectations in this repo:

• keep crate boundaries clean (no cross-layer leaks)
• avoid introducing unsafe outside approved crates
• add regression tests for bug fixes
• run just ci before sending changes