80 lines
4.1 KiB
Markdown
80 lines
4.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
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
|
|
|
|
1. **No unsafe code** except in `crates/platform/` and `crates/graphics/`
|
|
2. **No upward dependencies** between layers
|
|
3. **Every bug fix requires a regression test**
|
|
4. **New dependencies require rationale in PR**
|
|
5. **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
|