CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

just ci        # Full validation: fmt, lint, test, policy, metrics
just test      # Run tests only (cargo xtest)
just lint      # Run clippy (cargo xclippy -- -D warnings)
just fmt       # Check formatting (cargo fmt --all --check)
just fix       # Auto-fix formatting (cargo fmt --all)
just policy    # Run safety checks (unsafe, deps, file sizes)
just san       # Run sanitizers (Linux nightly only)

# Test262 full-suite (requires upstream clone)
just clone-test262       # Clone tc39/test262 to tests/external/js262/upstream/
just test262-scan        # Clone + scan → generate js262_full_manifest.toml
just test262-full        # Scan + run full suite
just triage-test262-full # Promote passing known_fail tests in full suite

Integration tests in tests/ require [[test]] entries in root Cargo.toml.

Architecture

Crate Layers (enforced by `scripts/check_deps.sh`)

Layer 0: shared - Common types, geometry, errors
Layer 1: Engine crates - No upward dependencies allowed
- JS: js, js_vm, js_parser
- Rendering: html, dom, css, selectors, style, layout, display_list, render
- Infrastructure: net, storage, image, fonts, graphics, platform, web_api
Layer 2: browser_runtime - Tabs, navigation, history
Layer 3: app_browser - Window, event loop, application entry

Rendering Pipeline

HTML Parse → DOM Tree → CSS Parse → Style Computation → Layout → Display List → Render

Each phase produces stable representations. Uses arena-based storage with IDs (NodeId, StyleId, LayoutId) instead of lifetimes for cross-crate APIs.

Threading Model

Single-threaded main thread (JS, DOM, style, layout, paint). Worker threads for network I/O and image decoding only.

Critical Rules

No unsafe code except in crates/platform/ and crates/graphics/
No upward dependencies between layers
Every bug fix requires a regression test
New dependencies require rationale in PR
Run just ci after every code change — it takes ~1 minute, so only run it once per change. Capture output with just ci 2>&1 | tee /tmp/ci-output.txt and read/grep the file for different checks rather than re-running.

Testing

Unit tests: Inline #[cfg(test)] mod tests in crate source files, broken into multiple files when they get large
Integration tests: tests/*.rs - each needs [[test]] in root Cargo.toml
Golden tests: tests/goldens.rs - compares layout tree and display list dumps against expected outputs in tests/goldens/expected/
JS262 conformance: tests/js262_harness.rs - Test262-inspired suite with TOML manifest at tests/external/js262/js262_manifest.toml
- Run suite: cargo test -p rust_browser --test js262_harness js262_suite_matches_manifest_expectations -- --nocapture
- Manage status: just js262-status promote --id <test-id> (promote known_fail to pass)
JS262 full suite: Full tc39/test262 conformance via js262_full_manifest.toml (auto-generated)
- Two-tier system: Tier 1 (vendored, PR gate) + Tier 2 (upstream clone, full suite)
- Status overrides in tests/external/js262/js262_full_status.toml (checked in)
- Run: just test262-full; triage: just triage-test262-full

Key Documentation

docs/browser_architecture_initial_exploration.md - Design principles, threading model
docs/browser_project_structure_modularization_guide.md - Crate layout, dependency rules
docs/browser_testing_strategy_high_level_to_detailed.md - Testing approach
docs/js_conformance_report.md - JS262 conformance test results by feature area
docs/test262_roadmap.md - Gap analysis and implementation plan for real Test262 support
docs/CSS2.1_Implementation_Checklist.md - CSS2.1 implementation status. Make sure to update when new CSS support is added.
docs/HTML5_Implementation_Checklist.md - HTML5 implementation status. Make sure to update when new CSS support is added.
AGENTS.md - Agent contract and rules

4.1 KiB Raw Permalink Blame History