143 lines
4.3 KiB
Markdown
143 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
cargo install just
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cargo build -p app_browser
|
|
```
|
|
|
|
## Run
|
|
|
|
Show CLI help:
|
|
|
|
```bash
|
|
cargo run -p app_browser -- --help
|
|
```
|
|
|
|
Open a URL in windowed mode:
|
|
|
|
```bash
|
|
cargo run -p app_browser -- https://example.com
|
|
```
|
|
|
|
Render an input file/URL to layout and display-list dumps:
|
|
|
|
```bash
|
|
cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html
|
|
```
|
|
|
|
Render and emit PNG:
|
|
|
|
```bash
|
|
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
|