rust_browser/_bmad-output/project-context.md

---
project_name: 'rust_browser'
user_name: 'Zach'
date: '2026-03-05'
sections_completed: ['technology_stack', 'language_rules', 'framework_rules', 'testing_rules', 'code_quality', 'workflow_rules', 'critical_rules']
status: 'complete'
rule_count: 42
optimized_for_llm: true
---

# Project Context for AI Agents

_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._

---

## Technology Stack & Versions

- **Language:** Rust edition 2021, Cargo workspace with 21 crates
- **Build system:** `just` task runner — run `just ci` for full validation
- **Windowing:** `winit` 0.30 + `softbuffer` 0.4
- **Networking:** `ureq` 2.x (blocking HTTP client)
- **Parsing:** `logos` 0.14 (lexer generator, used for CSS tokenizer)
- **JS engine:** Custom — `js`, `js_vm`, `js_parser` crates + `regress` 0.10 (regex)
- **Image:** `image` 0.25 (PNG/JPEG/GIF/WebP), `resvg` 0.47 (SVG)
- **Text:** `unicode-segmentation` 1.x, `unicode-bidi` 0.3, `encoding_rs` 0.8
- **Error handling:** `thiserror` 1.x (domain errors) + `anyhow` 1.x (catch-all via `SharedResult<T>`)
- **Utilities:** `bitflags` 2.x, `smallvec` 1.x, `indexmap` 2.x
- **URL/encoding:** `url` 2.x, `base64` 0.22, `percent-encoding` 2.x
- **Testing:** `proptest` 1.x, `tiny_http` 0.12, golden tests, WPT harness, JS262 harness

## Critical Implementation Rules

### Language-Specific Rules (Rust)

**Arena ID Pattern:**
- Cross-crate identifiers are newtype structs wrapping `usize` (e.g., `NodeId(pub usize)`) defined in `shared`
- Use `NodeId::new(id)` / `.index()` — don't construct raw or unwrap the inner value directly
- DOM uses `Vec<Node>` arena on `Document`, indexed by `NodeId::index()`
- Layout boxes use owned `Vec<LayoutBox>` children (not a separate arena), linked back to DOM via `NodeId`

**Error Handling:**
- Domain errors: `#[derive(Debug, Error, Clone, PartialEq, Eq)]` using `thiserror`
- Include constructor helpers on error enums (e.g., `NavigationError::network(msg)`)
- Implement `From` conversions for related error types manually
- Catch-all: `SharedResult<T>` (alias for `anyhow::Result<T>`) in `shared`

**Import Conventions:**
- Use `crate::` paths within a crate (not `super::` except in test files)
- Import dependency crates by name directly (`use shared::NodeId;` — no `extern crate`)
- Prefer explicit named imports over globs (`pub use types::*` only for large type modules)

**Visibility:**
- `pub` for public API, `pub(crate)` for internal cross-module use — `pub(super)` is not used
- All public exports funneled through `lib.rs` via `pub use` re-exports; submodules are private `mod`

**Code Organization:**
- Use `// ===...===` section dividers to group related items within files
- Reference CSS/HTML spec sections in inline comments (e.g., `// Per CSS 2.1 §17.5.2.1`)

### Architecture & Engine Rules

**Crate Layering (enforced by `scripts/check_deps.sh`):**
- **Layer 0:** `shared` — common types, geometry, errors
- **Layer 1:** Engine crates — `js`, `js_vm`, `js_parser`, `html`, `dom`, `css`, `selectors`, `style`, `layout`, `display_list`, `render`, `net`, `storage`, `image`, `fonts`, `graphics`, `platform`, `web_api`
- **Layer 2:** `browser_runtime` — tabs, navigation, history
- **Layer 3:** `app_browser` — window, event loop, application entry
- Lower layers MUST NOT depend on higher layers. Layer 1 crates may depend horizontally and on Layer 0.

**Rendering Pipeline:**
- Strict sequence: HTML Parse → DOM Tree → CSS Parse → Style Computation → Layout → Display List → Render
- Each phase produces stable, self-contained representations — no skipping phases
- Display list always comes from layout, not directly from style

**Threading Model:**
- Single-threaded main thread for JS, DOM, style, layout, paint
- Worker threads ONLY for network I/O and image decoding
- No async runtime on the main thread — blocking is acceptable in the rendering path

**Unsafe Policy:**
- `unsafe` ONLY in `crates/platform/` and `crates/graphics/` (enforced by `scripts/check_unsafe.sh`)
- Workspace lints set `unsafe_code = "forbid"` — all other crates inherit this

### Testing Rules

**Test Organization:**
- Unit tests: inline `#[cfg(test)] mod tests` in source files for small/focused tests
- Separate `src/tests/` directory with `mod.rs` when tests are large/numerous
- Test helpers live in `pub(crate) mod common` within the test module
- Integration tests: `tests/*.rs` at repo root — each MUST have a `[[test]]` entry in root `Cargo.toml`

**Test Suites:**
- **Golden tests:** `tests/goldens.rs` — compares layout tree + display list dumps against `tests/goldens/expected/`
- **WPT harness:** `tests/wpt_harness.rs` — Web Platform Tests with TOML manifest
- **JS262:** `tests/js262_harness.rs` — vendored JS conformance tests with manifest at `tests/external/js262/js262_manifest.toml`
- **Test262:** Full TC39 Test262 conformance via `js262_full_manifest.toml` — two-tier system (Tier 1 vendored as PR gate, Tier 2 upstream clone for full suite)

**Test Conventions:**
- Test files use `use crate::*` or `use super::*` to import the module under test
- Full pipeline tests construct `HtmlParser` → `StyleContext` → `LayoutEngine` inline
- Every bug fix requires a regression test

**CI Gate:**
- `just ci` = fmt + lint + test + policy + metrics (~1 minute)
- Run once after changes, capture with `just ci 2>&1 | tee /tmp/ci-output.txt`

### Code Quality & Style Rules

**Formatting & Linting:**
- `cargo fmt --all` for formatting (checked by `just fmt`)
- `cargo xclippy -- -D warnings` — all warnings are errors
- Workspace clippy: `correctness`/`suspicious` = `deny`, `perf`/`complexity`/`style` = `warn`
- Allowed lints: `module_name_repetitions`, `missing_errors_doc`, `missing_panics_doc`

**File & Module Naming:**
- All source files use `snake_case` (e.g., `box_tree.rs`, `var_substitution.rs`)
- Test files use `_tests` suffix (e.g., `basic_tests.rs`, `flex_layout_tests.rs`)

**Documentation:**
- Module-level `//!` doc comments on files with meaningful API surface
- `///` doc comments on public structs, enums, and non-obvious methods
- No doc comments required on private/internal items

**File Size Policy:**
- Enforced by `scripts/check_file_size.sh` — keep files within limits

**New Dependencies:**
- Require rationale — prefer `std` where possible
- Pin versions at workspace level in root `Cargo.toml` under `[workspace.dependencies]`

### Development Workflow Rules

**Build Commands:**
- `just ci` — full validation (fmt, lint, test, policy, metrics)
- `just test` — tests only (skips full Test262 by default)
- `just fix` — auto-fix formatting
- `just policy` — safety checks (unsafe, deps, file sizes)

**Documentation Updates Required:**
- `docs/CSS2.1_Implementation_Checklist.md` — update when adding CSS support
- `docs/HTML5_Implementation_Checklist.md` — update when adding HTML support
- `docs/JS_Implementation_Checklist.md` — update when adding JS support (TODO: create this doc, following the same format as CSS and HTML checklists)

**Integration Test Registration:**
- New `tests/*.rs` files MUST have a corresponding `[[test]]` entry in root `Cargo.toml`

**JS262/Test262 Workflow:**
- Promote passing tests: `just js262-status promote --id <test-id>`
- Full Test262: `just test262-full` (requires `just clone-test262` first)
- Triage: `just triage-test262-full` to promote passing `known_fail` tests

### Critical Don't-Miss Rules

**Anti-Patterns to Avoid:**
- NEVER add `unsafe` outside `crates/platform/` or `crates/graphics/` — CI will reject it
- NEVER add a dependency from a lower layer crate to a higher layer crate — `check_deps.sh` enforces this
- NEVER add a new external dependency without workspace-level pinning and rationale
- NEVER skip `just ci` — it catches formatting, lint, safety, and layering violations in one pass

**Edge Cases:**
- CSS property values can be `inherit`, `initial`, or `unset` — always handle these in style computation
- `NodeId(0)` is typically the document root — don't use it as a sentinel/null value
- Layout boxes link back to DOM via `NodeId` but not all DOM nodes produce layout boxes (e.g., `display: none`)

**Spec Compliance:**
- Always cite the spec section when implementing CSS, HTML, or JS features (e.g., `// CSS 2.1 §8.3.1`, `// ECMAScript §13.15.3`)
- Check the implementation checklists before starting work to avoid duplicate effort
- WPT and Test262 results are the ground truth for conformance — not just unit tests

---

## Usage Guidelines

**For AI Agents:**
- Read this file before implementing any code
- Follow ALL rules exactly as documented
- When in doubt, prefer the more restrictive option
- Update this file if new patterns emerge

**For Humans:**
- Keep this file lean and focused on agent needs
- Update when technology stack changes
- Review periodically for outdated rules
- Remove rules that become obvious over time

Last Updated: 2026-03-05