rust_browser/docs/development-guide.md

# Development Guide — rust_browser

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

## Prerequisites

- **Rust toolchain** — Stable channel (pinned via `rust-toolchain.toml`)
  - Components: `rustfmt`, `clippy`
- **`just`** command runner
  ```bash
  cargo install just
  ```
- **Python 3** — Required for WPT/Test262 scripts only

## Getting Started

### Clone and Build

```bash
git clone <repo-url> rust_browser
cd rust_browser
cargo build -p app_browser
```

### Run the Browser

```bash
# Show CLI help
cargo run -p app_browser -- --help

# Open a URL in windowed mode
cargo run -p app_browser -- https://example.com

# Open with dark mode
cargo run -p app_browser -- --dark https://example.com

# Render to layout dump (no window)
cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html

# Render to PNG
cargo run -p app_browser -- --render tests/goldens/fixtures/001-empty.html --png
```

## Development Commands

All primary commands are in the `justfile`:

| Command | Purpose | Duration |
|---|---|---|
| `just ci` | Full CI pipeline (fmt + lint + test + policy + metrics) | ~1 min |
| `just test` | Run all tests (workspace + WPT + JS262 manifests) | ~30s |
| `just lint` | Run clippy with warnings denied | ~15s |
| `just fmt` | Check formatting (no changes) | ~5s |
| `just fix` | Auto-fix formatting | ~5s |
| `just policy` | Run safety checks (unsafe, deps, file sizes) | ~5s |
| `just metrics` | Report project metrics | ~5s |
| `just san` | Run sanitizers (Linux nightly only) | ~5min |

### CI Workflow

**Always run `just ci` after every code change.** It takes about 1 minute.

```bash
# Capture output for review
just ci 2>&1 | tee /tmp/ci-output.txt
```

## Testing

### Test Layers

1. **Unit tests** — Inline `#[cfg(test)] mod tests` in crate source files
   ```bash
   cargo test -p <crate_name>
   ```

2. **Integration tests** — `tests/*.rs` (each registered as `[[test]]` in root `Cargo.toml`)
   ```bash
   cargo test -p rust_browser --test goldens
   cargo test -p rust_browser --test js_tests
   ```

3. **Golden tests** — Layout tree and display list regression tests
   ```bash
   cargo test -p rust_browser --test goldens
   # Regenerate expected outputs:
   cargo test -p rust_browser --test regen_goldens -- --ignored --nocapture
   ```

4. **JS262 conformance** — Test262-inspired JavaScript conformance suite
   ```bash
   # Run vendored tier-1 suite
   cargo test -p rust_browser --test js262_harness js262_suite_matches_manifest_expectations -- --nocapture

   # Promote passing known_fail tests
   just js262-status promote --id <test-id>
   ```

5. **WPT harness** — Web Platform Tests
   ```bash
   cargo test -p rust_browser --test wpt_harness wpt_suite_matches_manifest_expectations -- --nocapture
   ```

6. **Full Test262 suite** (requires upstream clone)
   ```bash
   just clone-test262    # Clone tc39/test262
   just test262-scan     # Generate manifest
   just test262-full     # Run full suite
   just triage-test262-full  # Promote newly passing tests
   ```

### Adding New Integration Tests

1. Create `tests/my_test.rs`
2. Add to root `Cargo.toml`:
   ```toml
   [[test]]
   name = "my_test"
   path = "tests/my_test.rs"
   ```

### Test Principles

- **Every bug fix requires a regression test**
- Unit tests go inline in the source module (test private APIs)
- Integration tests go in `tests/` (test public cross-crate behavior)
- Golden tests for any rendering behavior change

## Project Structure Rules

### Layer Dependencies

```
Layer 3: app_browser    → can depend on anything below
Layer 2: browser_runtime → can depend on Layer 1 and 0
Layer 1: engine crates   → can depend on Layer 1 and 0 (no upward deps)
Layer 0: shared          → no internal dependencies
```

**Enforced by `scripts/check_deps.sh`** — runs in CI.

### Unsafe Code Policy

- **Forbidden by default** — `unsafe_code = "forbid"` in workspace lints
- **Allowed only in**: `crates/platform/` and `crates/graphics/`
- **Enforced by `scripts/check_unsafe.sh`** — runs in CI

### New Dependencies

- Require rationale in PR description
- Must pass `deny.toml` license/advisory checks

## Common Development Tasks

### Adding a New CSS Property

1. Add parsing in `crates/css/` (tokenizer + parser)
2. Add selector/cascade support in `crates/selectors/` if needed
3. Add computed style type in `crates/style/` (`ComputedStyles`)
4. Implement layout behavior in `crates/layout/`
5. Add display list generation in `crates/display_list/` if visual
6. Update `docs/CSS2.1_Implementation_Checklist.md`
7. Add golden tests for the new property
8. Run `just ci`

### Adding a New JavaScript Feature

1. Add tokenization in `crates/js_parser/` (if new syntax)
2. Add AST node in `crates/js_parser/`
3. Implement execution in `crates/js_vm/`
4. Add unit tests inline
5. Add Test262 conformance tests to the manifest
6. Update `docs/js_feature_matrix.md`
7. Run `just ci`

### Adding a New HTML Element

1. Add parsing support in `crates/html/`
2. Add DOM representation in `crates/dom/` if needed
3. Add default styling in `crates/style/` (UA stylesheet)
4. Implement layout behavior in `crates/layout/`
5. Update `docs/HTML5_Implementation_Checklist.md`
6. Add golden tests
7. Run `just ci`

### Investigating Rendering Issues

Use the investigation workflow:
```bash
# Creates a report at investigations/<site>/report.md
```

Existing investigations: acid2, google, moldybits, slashdot, youtube

## Code Style

- **Formatting**: `rustfmt` (checked by `just fmt`)
- **Linting**: `clippy` with all warnings denied
- **Naming**: Standard Rust conventions (snake_case functions, PascalCase types)
- **Error handling**: `anyhow` for application errors, `thiserror` for library errors
- **Logging**: `tracing` crate for structured logging

## Project Metrics

Run `just metrics` to see:
- Lines of code per crate
- Test count
- Dependency count
- File sizes