rust_browser/docs/architecture.md

# Architecture — rust_browser

**Generated:** 2026-03-05 | **Scan Level:** Deep

## Executive Summary

rust_browser is a from-scratch web browser engine built as a Rust Cargo workspace with 22 crates organized in a strict 4-layer hierarchy. The architecture follows a deterministic, single-threaded rendering pipeline (HTML → DOM → CSS → Style → Layout → Display List → Render) with arena-based data flow between phases. Worker threads handle only network I/O and image decoding. The project prioritizes correctness, testability, and clear separation of concerns over early performance optimization.

## Architecture Overview

```
┌────────────────────────────────────────────────────────────────┐
│ Layer 3: app_browser                                           │
│   Desktop shell, CLI, event loop, pipeline orchestration       │
├────────────────────────────────────────────────────────────────┤
│ Layer 2: browser_runtime                                       │
│   Tab management, navigation lifecycle, history, browsing ctx  │
├────────────────────────────────────────────────────────────────┤
│ Layer 1: Engine Crates                                         │
│                                                                │
│  ┌─── JS Engine ───┐  ┌──── Rendering Pipeline ─────────────┐ │
│  │ js_parser (AST)  │  │ html → dom → css → selectors        │ │
│  │ js_vm (interp)   │  │   → style → layout → display_list   │ │
│  │ js (facade)      │  │   → render → graphics                │ │
│  └──────────────────┘  └─────────────────────────────────────┘ │
│                                                                │
│  ┌─── Infrastructure ──┐  ┌── Web APIs ──┐                    │
│  │ net (HTTP/file)      │  │ web_api      │                    │
│  │ image (decode)       │  │ (JS↔DOM      │                    │
│  │ fonts (rasterize)    │  │  bridge)     │                    │
│  │ storage (placeholder)│  └──────────────┘                    │
│  │ platform (windowing) │                                      │
│  └──────────────────────┘                                      │
├────────────────────────────────────────────────────────────────┤
│ Layer 0: shared                                                │
│   Common types: Point, Size, Rect, Color, NodeId, StyleId,    │
│   LayoutId, BrowserUrl, errors                                 │
└────────────────────────────────────────────────────────────────┘
```

## Rendering Pipeline

The pipeline is intentionally staged and deterministic. Each phase produces a stable intermediate representation:

```
1. Input          → HTML source string
2. html crate     → DOM Tree (arena-based, NodeId indices)
3. css crate      → Parsed Stylesheets (Rules, Selectors, Declarations)
4. selectors      → Matched Rules per node (with Specificity)
5. style crate    → StyledDocument (NodeId → ComputedStyles)
6. layout crate   → Layout Tree (LayoutNode, box geometry, positioning)
7. display_list   → Display List (Vec<DisplayItem>: rects, text, borders, images)
8. render crate   → Pixel Buffer (RGBA8 pixels)
9. platform       → On-screen presentation (via softbuffer + winit)
```

In `--render` mode, steps 2-7 produce artifact dumps (`.layout.txt` and `.dl.txt`) for golden regression testing.

## Crate Dependency Graph

### Layer Rules (enforced by `scripts/check_deps.sh`)
- **No upward dependencies** — Layer 1 cannot depend on Layer 2 or 3
- **Lateral dependencies within Layer 1** are allowed where necessary (e.g., `style` depends on `css`, `dom`, `selectors`)
- **Layer 0 (`shared`)** has no internal dependencies

### Key Dependencies

| Crate | Depends On |
|---|---|
| `app_browser` (L3) | browser_runtime, platform, shared, net, html, dom, css, style, layout, display_list, render, image |
| `browser_runtime` (L2) | web_api, dom, net, storage, shared |
| `web_api` (L1) | dom, html, js, js_parser, shared |
| `style` (L1) | css, dom, selectors, shared |
| `layout` (L1) | dom, style, image, fonts, shared |
| `display_list` (L1) | layout, style, shared |
| `render` (L1) | display_list, fonts, graphics, image, shared |
| `selectors` (L1) | dom, shared |
| `js_vm` (L1) | js_parser |
| `js` (L1) | js_parser, js_vm |

## Data Flow Patterns

### Arena-Based Storage
Each crate uses arena-based storage with integer IDs for cross-crate references:
- **`NodeId`** — DOM node identity (used by dom, html, style, layout, display_list)
- **`StyleId`** — Style identity
- **`LayoutId`** — Layout node identity
- **`ImageId`** — Decoded image identity (used by image, render)

This avoids lifetime-based references across crate boundaries, simplifying the API surface.

### Phase-Based Mutation
The pipeline follows a strict phase model:
1. **Parse phase** — HTML parser builds DOM tree (mutable)
2. **Style phase** — Style engine reads DOM, produces `StyledDocument` (DOM is immutable)
3. **Layout phase** — Layout engine reads styled DOM, produces layout tree
4. **Paint phase** — Display list builder reads layout tree, produces draw commands
5. **Render phase** — Rasterizer reads display list, produces pixels

Each phase reads the previous phase's output and produces new, stable output.

## JavaScript Engine Architecture

```
┌─────────────────────────────────────────────────┐
│ js crate (facade)                               │
│   JsEngine: combines parser + VM                │
├─────────────────────────────────────────────────┤
│ js_vm crate                                     │
│   JsVm: runtime state machine                   │
│   bytecode::Compiler: AST → bytecode (Chunk)    │
│   bytecode_exec: bytecode execution loop         │
│   Environment: variable scoping                  │
│   JsValue: value representation                  │
│   HostEnvironment: host object binding           │
│   Runtime: builtins, coercion, property access   │
│   [deprecated] AST interpreter: statements.rs,  │
│     expressions/ (see note below)                │
├─────────────────────────────────────────────────┤
│ js_parser crate (parsing)                       │
│   JsParser: source → AST                         │
│   Tokenizer: source → tokens                     │
│   AST types: Program, Statement, Expression      │
└─────────────────────────────────────────────────┘
```

- **Bytecode pipeline** — `JsParser` produces an AST, `bytecode::Compiler` compiles it
  to a `Chunk` (bytecode + constant pool), `bytecode_exec` runs the bytecode.
  The old AST-walking interpreter (`execute_program`, `execute_stmt`, `eval_expr`)
  is deprecated. It still exists because `call_function` (used by the bytecode
  executor for function invocations) delegates to `execute_function_body` →
  `execute_stmt`. Once function calls are fully compiled to bytecode, the AST
  interpreter can be removed.
- **Configurable limits** — `VmConfig` with `max_statements`, `max_call_depth`
- **Host bindings** — `HostEnvironment` trait for injecting browser APIs
- **Regex** — ECMAScript-compatible via `regress` crate

## Web API Bridge

The `web_api` crate connects the JS engine to the DOM:

- **DOM Host Objects** — `window`, `document` exposed as JS host objects
- **Event System** — `EventTarget`, `EventListenerRegistry`, `DispatchResult`
- **Scheduling** — `TaskQueue` (setTimeout/setInterval), `MicrotaskQueue` (Promise callbacks)
- **Promises** — `PromiseRegistry` for async operation tracking
- **Script Execution** — `WebApiFacade::execute_script()` as the unified entry point

## Threading Model

```
Main Thread (single-threaded):
  ├── JavaScript execution (bytecode VM)
  ├── DOM manipulation
  ├── Style computation
  ├── Layout
  ├── Display list generation
  ├── CPU rasterization
  └── Event dispatch

Worker Threads (I/O only):
  ├── Network requests (HTTP via ureq)
  └── Image decoding
```

The single-threaded model ensures determinism and simplifies reasoning about state. Worker threads are used only for operations that would block the main thread.

## State Management

### Navigation Lifecycle
```
BrowserRuntime
  └── BrowsingContext
        ├── NavigationState: Loading → ReceivingData → Complete | Failed
        ├── Current URL
        └── WebApiFacade
              ├── JS Engine
              ├── DOM Document
              ├── Event Listeners
              ├── Task Queue
              └── Microtask Queue
```

### Application State (app_browser)
- `AppState` — mutable browser state (current page, scroll position, input focus)
- `BrowserChrome` — UI chrome overlay (URL bar, status)
- `HitTest` — Click target resolution from display list
- `FocusOutline` — Keyboard focus visualization
- `FormState` — Form input handling

## Platform Abstraction

Platform-specific code is isolated in `crates/platform/`:
- **Windowing** — `winit` for cross-platform window creation
- **Pixel presentation** — `softbuffer` for CPU-rendered pixel blitting
- **Event mapping** — OS events → `WindowEvent` enum
- **Text input** — IME state management

The `platform` and `graphics` crates are the only ones allowed to use `unsafe` code.

## Testing Architecture

| Layer | Type | Location | Purpose |
|---|---|---|---|
| Unit | `#[cfg(test)] mod tests` | Inline in crate source | Private API testing |
| Integration | `tests/*.rs` | Root `tests/` directory | Cross-crate behavior |
| Golden | `tests/goldens.rs` | Golden fixtures | Layout/display list regression |
| JS Conformance | `tests/js262_harness.rs` | Test262 manifests | ECMAScript spec compliance |
| Web Platform | `tests/wpt_harness.rs` | WPT fixtures | CSS/HTML spec compliance |

## Safety Guarantees

1. **`unsafe` forbidden globally** — workspace lint `unsafe_code = "forbid"`
2. **Exceptions**: `platform/` and `graphics/` crates only (via per-crate lint override)
3. **Enforced by CI** — `scripts/check_unsafe.sh` audits unsafe usage
4. **Dependency layering** — `scripts/check_deps.sh` prevents architecture violations
5. **License policy** — `deny.toml` prevents license/advisory issues