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>
161 lines
9.5 KiB
Markdown
161 lines
9.5 KiB
Markdown
# Source Tree Analysis
|
|
|
|
**Generated:** 2026-03-05 | **Scan Level:** Deep
|
|
|
|
## Annotated Directory Tree
|
|
|
|
```
|
|
rust_browser/
|
|
├── Cargo.toml # Workspace root: 22 member crates, dependency versions, lints
|
|
├── Cargo.lock # Pinned dependency versions
|
|
├── CLAUDE.md # AI agent development instructions
|
|
├── AGENTS.md # Agent contract and rules
|
|
├── README.md # Project overview and getting started
|
|
├── rust-toolchain.toml # Toolchain: stable, rustfmt, clippy
|
|
├── deny.toml # License/advisory policy (cargo-deny)
|
|
├── justfile # Task runner: ci, test, lint, fmt, policy, metrics
|
|
│
|
|
├── src/
|
|
│ └── lib.rs # Root crate: re-exports for integration tests
|
|
│
|
|
├── crates/ # ── All 22 workspace crates ──
|
|
│ │
|
|
│ ├── shared/ # [Layer 0] Common types, geometry, errors (3 files)
|
|
│ │ └── src/lib.rs # Point, Size, Rect, Color, NodeId, StyleId, LayoutId
|
|
│ │
|
|
│ │ # ── Layer 1: JavaScript Engine ──
|
|
│ ├── js_parser/ # JS tokenization and AST parsing (35 files)
|
|
│ │ └── src/ # JsParser::parse(), Tokenizer, AST types
|
|
│ ├── js_vm/ # JS interpreter/virtual machine (48 files)
|
|
│ │ └── src/ # JsVm, JsValue, Interpreter, Environment
|
|
│ ├── js/ # JS facade combining parser+VM (1 file)
|
|
│ │ └── src/lib.rs # JsEngine (thin wrapper)
|
|
│ │
|
|
│ │ # ── Layer 1: Document/Style Pipeline ──
|
|
│ ├── html/ # HTML5 tokenization and tree building (9 files)
|
|
│ │ └── src/ # HtmlParser::parse(), tokenizer, entities
|
|
│ ├── dom/ # DOM tree representation (10 files)
|
|
│ │ └── src/ # Document, Node, NodeKind, arena-based
|
|
│ ├── css/ # CSS parsing and data structures (36 files)
|
|
│ │ └── src/ # CssParser, Stylesheet, CssValue, Declaration
|
|
│ ├── selectors/ # CSS selector matching and cascade (17 files)
|
|
│ │ └── src/ # SelectorEngine, Specificity, bloom filter
|
|
│ ├── style/ # Style computation: cascade + inheritance (34 files)
|
|
│ │ └── src/ # StyledDocument, ComputedStyles, UA stylesheet
|
|
│ │
|
|
│ │ # ── Layer 1: Layout & Rendering ──
|
|
│ ├── layout/ # Layout engine: box model, flex, tables (60 files) ★ LARGEST
|
|
│ │ └── src/ # LayoutEngine, block/inline/flex/table layout
|
|
│ ├── display_list/ # Display list: painting commands (13 files)
|
|
│ │ └── src/ # DisplayListBuilder, DisplayItem variants
|
|
│ ├── render/ # CPU rasterizer (14 files)
|
|
│ │ └── src/ # Renderer, CpuRasterizer, PixelBuffer
|
|
│ ├── graphics/ # Graphics backend abstraction (1 file)
|
|
│ │ └── src/lib.rs # GraphicsBackend placeholder
|
|
│ │
|
|
│ │ # ── Layer 1: Infrastructure ──
|
|
│ ├── net/ # Network stack: HTTP, file://, data: (7 files)
|
|
│ │ └── src/ # NetworkStack, HttpLoader, FileLoader, caching
|
|
│ ├── storage/ # Persistent storage placeholder (1 file)
|
|
│ │ └── src/lib.rs # StorageEngine
|
|
│ ├── image/ # Image decoding: PNG, JPEG, GIF, WebP, SVG (1 file)
|
|
│ │ └── src/lib.rs # ImageStore, ImagePipeline, DecodedImage
|
|
│ ├── fonts/ # Font loading, metrics, rasterization (5 files)
|
|
│ │ ├── src/ # FontProvider, FontRequest, GlyphMask
|
|
│ │ └── data/ # Bundled Noto Sans fonts (3.1 MB)
|
|
│ ├── platform/ # Window/event loop: winit+softbuffer (4 files) ⚠️ unsafe allowed
|
|
│ │ └── src/ # PlatformContext, EventLoop, Window, KeyCode
|
|
│ ├── web_api/ # Web API facade: DOM+JS bridge (14 files)
|
|
│ │ └── src/ # WebApiFacade, EventTarget, TaskQueue, Promise
|
|
│ │
|
|
│ │ # ── Layer 2: Browser Runtime ──
|
|
│ ├── browser_runtime/ # Tabs, navigation, history (5 files)
|
|
│ │ └── src/ # BrowserRuntime, BrowsingContext, Navigation
|
|
│ │
|
|
│ │ # ── Layer 3: Application Shell ──
|
|
│ └── app_browser/ # Desktop app binary (31 files)
|
|
│ └── src/ # main(), pipeline, chrome, hit_test, forms
|
|
│
|
|
├── tests/ # Integration tests (each registered in Cargo.toml)
|
|
│ ├── goldens.rs # Golden rendering regression tests
|
|
│ ├── goldens/ # Golden test fixtures and expected outputs
|
|
│ │ ├── fixtures/ # HTML input files
|
|
│ │ └── expected/ # Expected layout/display list dumps
|
|
│ ├── main_cli_tests.rs # CLI integration tests
|
|
│ ├── external_css_test.rs # CSS parsing tests
|
|
│ ├── navigation_tests.rs # Navigation lifecycle tests
|
|
│ ├── regen_goldens.rs # Regenerate golden expected outputs
|
|
│ ├── wpt_harness.rs # Web Platform Tests harness
|
|
│ ├── js_tests.rs # JavaScript execution tests
|
|
│ ├── js_dom_tests.rs # DOM + JS interaction tests
|
|
│ ├── js_events.rs # Event system tests
|
|
│ ├── js_scheduling.rs # Microtask/promise/scheduling tests
|
|
│ ├── js262_harness.rs # Test262 JS conformance suite
|
|
│ └── external/ # External test data
|
|
│ ├── wpt/ # Web Platform Tests
|
|
│ └── js262/ # Test262 conformance manifests
|
|
│
|
|
├── scripts/ # Policy enforcement and utilities
|
|
│ ├── check_deps.sh # Layer dependency rule enforcement
|
|
│ ├── check_unsafe.sh # Unsafe code audit (allowlist: platform, graphics)
|
|
│ ├── check_file_size.sh # File size limits
|
|
│ ├── metrics.sh # Code metrics collection
|
|
│ ├── sanitizer.sh # Linux nightly sanitizer runner
|
|
│ ├── import_wpt_reftests.py # Import W3C WPT tests
|
|
│ ├── wpt_status.py # WPT status tracking
|
|
│ ├── clone_test262.py # Clone tc39/test262
|
|
│ ├── scan_test262.py # Generate test262_full_manifest.toml
|
|
│ ├── curate_test262.py # Test262 curation
|
|
│ ├── triage_test262.py # Promote passing Test262 tests
|
|
│ └── triage_test262_full.py # Full suite triage
|
|
│
|
|
├── investigations/ # Rendering investigation reports
|
|
│ ├── acid2/report.md # Acid2 test investigation
|
|
│ ├── google/report.md # Google.com rendering
|
|
│ ├── moldybits/report.md # moldybits.com rendering
|
|
│ ├── slashdot/report.md # Slashdot rendering
|
|
│ └── youtube/report.md # YouTube rendering
|
|
│
|
|
└── docs/ # Project documentation
|
|
├── browser_architecture_initial_exploration.md
|
|
├── browser_project_structure_modularization_guide.md
|
|
├── browser_testing_strategy_high_level_to_detailed.md
|
|
├── build_ci_contract_gitea_ci_rust_monorepo.md
|
|
├── browser_milestone_plan.md
|
|
├── milestone_6_phased_implementation_plan.md
|
|
├── known_limitations_log.md
|
|
├── external_conformance_wpt.md
|
|
├── wpt_known_fail_analysis.md
|
|
├── CSS2.1_Implementation_Checklist.md
|
|
├── HTML5_Implementation_Checklist.md
|
|
├── js_conformance_report.md
|
|
├── js_feature_matrix.md
|
|
└── test262_roadmap.md
|
|
```
|
|
|
|
## Critical Folders
|
|
|
|
| Folder | Purpose | Layer |
|
|
|---|---|---|
|
|
| `crates/layout/` | Layout engine — largest crate (60 files), handles block/inline/flex/table/positioned layout | L1 |
|
|
| `crates/js_vm/` | JS interpreter — second largest (48 files), core execution engine | L1 |
|
|
| `crates/css/` | CSS parser — 36 files, tokenization and property/value parsing | L1 |
|
|
| `crates/js_parser/` | JS parser — 35 files, tokenization and AST construction | L1 |
|
|
| `crates/style/` | Style computation — 34 files, cascade, inheritance, UA stylesheet | L1 |
|
|
| `crates/app_browser/` | Application shell — 31 files, event handling, pipeline orchestration, CLI | L3 |
|
|
| `crates/selectors/` | Selector matching — 17 files, specificity, bloom filter, pseudo-classes | L1 |
|
|
| `crates/web_api/` | Web API bridge — 14 files, JS↔DOM binding, events, promises, scheduling | L1 |
|
|
| `crates/render/` | CPU rasterizer — 14 files, pixel-level rendering | L1 |
|
|
| `crates/display_list/` | Display list — 13 files, painting command generation | L1 |
|
|
| `tests/` | Integration tests — 11 test files + golden fixtures + external suites | — |
|
|
| `scripts/` | Policy enforcement — 12 scripts for CI, conformance, metrics | — |
|
|
|
|
## Entry Points
|
|
|
|
| Entry Point | Location | Purpose |
|
|
|---|---|---|
|
|
| `main()` | `crates/app_browser/src/main.rs` | Application binary entry |
|
|
| `run_windowed_mode()` | `crates/app_browser/src/` | Interactive browser window |
|
|
| `run_render_mode()` | `crates/app_browser/src/` | Offline HTML → layout dump + PNG |
|
|
| `lib.rs` | `src/lib.rs` | Root crate re-exports for integration tests |
|