rust_browser/_bmad-output/project-context.md

project_name, user_name, date, sections_completed, status, rule_count, optimized_for_llm

project_name	user_name	date	sections_completed	status	rule_count	optimized_for_llm
rust_browser	Zach	2026-03-05	technology_stack language_rules framework_rules testing_rules code_quality workflow_rules critical_rules	complete	42	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