rust_browser/docs/project-overview.md

rust_browser — Project Overview

Generated: 2026-03-05 | Scan Level: Deep | Workflow Version: 1.2.0

Executive Summary

rust_browser is a modular, experimental web browser engine and desktop shell written in Rust. It implements a complete rendering pipeline from HTML/CSS parsing through layout and CPU rasterization, a custom JavaScript engine (interpreter-first), and a desktop windowing shell. The project emphasizes correctness before performance, deterministic behavior, clear crate boundaries, and testability.

Project Classification

Attribute	Value
Repository Type	Monolith (Cargo workspace)
Project Type	Desktop Application — Web Browser Engine
Primary Language	Rust (edition 2021, stable toolchain)
Architecture	Layered pipeline with arena-based data flow
Workspace Members	22 crates
Approximate Size	~340 Rust source files across all crates

Technology Stack

Category	Technology	Version	Purpose
Language	Rust	stable (edition 2021)	Core implementation
Windowing	winit	0.30	Cross-platform window/event loop
Pixel Blitting	softbuffer	0.4	CPU-rendered pixel buffer presentation
SVG Rendering	resvg	0.47	SVG image rendering
Image Decoding	image	0.25	PNG, JPEG, GIF, WebP decoding
Font Rasterization	ab_glyph	—	TrueType font loading and rasterization
HTTP Client	ureq	2	Synchronous HTTP/HTTPS
URL Parsing	url	2	URL/URI handling
Text Encoding	encoding_rs	0.8	Character encoding detection/conversion
Regex (JS)	regress	0.10	ECMAScript-compatible regular expressions
CSS Tokenization	logos	0.14	Lexer generation
Error Handling	anyhow + thiserror	1	Error propagation and definition
Logging	tracing	0.1	Structured logging/tracing
Build Runner	just	—	Task runner (justfile)
Testing	proptest + tiny_http	—	Property-based testing + test HTTP server

Architecture Pattern

Layered Pipeline Architecture — The browser is organized as a strict 4-layer pipeline where each phase produces stable, deterministic intermediate representations:

Layer 3: app_browser (Desktop shell, event loop, CLI)
Layer 2: browser_runtime (Tabs, navigation, history)
Layer 1: Engine crates (Parser → DOM → CSS → Style → Layout → Display List → Render)
Layer 0: shared (Common types, geometry, errors)

Dependencies flow strictly downward. No upward dependencies are allowed (enforced by scripts/check_deps.sh).

Key Design Principles

1. Correctness before performance — Interpreter-first JS, CPU rasterization, single-threaded core
2. Determinism — Controllable clocks, deterministic task ordering, explicit GC hooks
3. Clear separation — Each crate owns one concern with well-defined public APIs
4. Arena-based data flow — Uses NodeId, StyleId, LayoutId instead of lifetimes across crate boundaries
5. Phase-based mutation — Parse → DOM → Style → Layout → Paint (each phase produces stable output)
6. Safety — unsafe forbidden except in platform/ and graphics/ crates

Current Status

The browser can render real web pages with:

• HTML parsing and DOM construction
• CSS parsing, selector matching, and core style computation
• Block/inline layout, flexbox, and partial table support
• Display list generation and CPU rasterization
• Local file and HTTP loading
• Custom JavaScript engine with ES5+ features
• Event handling (click, keyboard, form events)
• Navigation and history
• Dark mode support

Links to Detailed Documentation

• Architecture
• Source Tree Analysis
• Development Guide
• Component Inventory

Existing Documentation

• Architecture Exploration — Foundational vision and design decisions
• Project Structure Guide — Crate layout and dependency rules
• Testing Strategy — 6-tier testing approach
• Build/CI Contract — CI pipeline and policy enforcement
• Known Limitations — Intentionally deferred items
• CSS2.1 Implementation Checklist — CSS property support status
• HTML5 Implementation Checklist — HTML element/attribute support
• JS Conformance Report — Test262 conformance results
• JS Feature Matrix — JS feature implementation status
• Test262 Roadmap — JS conformance gap analysis
• WPT Known Failures — Web Platform Test failure analysis
• External Conformance (WPT) — WPT integration details
• Milestone Plan — Development milestones
• Milestone 6 Plan — Current milestone details