931f17b70e
All checks were successful
ci / fast (linux) (push) Successful in 6m46s
Install BMAD workflow framework with agent commands and templates. Create product brief, PRD, project context, and architecture decision document covering networking/persistence strategy, JS engine evolution path, threading model, web_api scaling, system integration, and tab/process model. Add generated project documentation (architecture overview, component inventory, development guide, source tree analysis). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# 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](./architecture.md)
|
|
- [Source Tree Analysis](./source-tree-analysis.md)
|
|
- [Development Guide](./development-guide.md)
|
|
- [Component Inventory](./component-inventory.md)
|
|
|
|
### Existing Documentation
|
|
|
|
- [Architecture Exploration](./browser_architecture_initial_exploration.md) — Foundational vision and design decisions
|
|
- [Project Structure Guide](./browser_project_structure_modularization_guide.md) — Crate layout and dependency rules
|
|
- [Testing Strategy](./browser_testing_strategy_high_level_to_detailed.md) — 6-tier testing approach
|
|
- [Build/CI Contract](./build_ci_contract_gitea_ci_rust_monorepo.md) — CI pipeline and policy enforcement
|
|
- [Known Limitations](./known_limitations_log.md) — Intentionally deferred items
|
|
- [CSS2.1 Implementation Checklist](./CSS2.1_Implementation_Checklist.md) — CSS property support status
|
|
- [HTML5 Implementation Checklist](./HTML5_Implementation_Checklist.md) — HTML element/attribute support
|
|
- [JS Conformance Report](./js_conformance_report.md) — Test262 conformance results
|
|
- [JS Feature Matrix](./js_feature_matrix.md) — JS feature implementation status
|
|
- [Test262 Roadmap](./test262_roadmap.md) — JS conformance gap analysis
|
|
- [WPT Known Failures](./wpt_known_fail_analysis.md) — Web Platform Test failure analysis
|
|
- [External Conformance (WPT)](./external_conformance_wpt.md) — WPT integration details
|
|
- [Milestone Plan](./browser_milestone_plan.md) — Development milestones
|
|
- [Milestone 6 Plan](./milestone_6_phased_implementation_plan.md) — Current milestone details
|