we / CLAUDE.md

# we — Agent Guide

## Architecture

`we` is a from-scratch web browser engine in pure Rust targeting macOS ARM (aarch64-apple-darwin). Zero external crate dependencies. Every subsystem — crypto, TLS, font parsing, image decoding, JS engine — is implemented in Rust.

### Crate Map

```
browser ─┬─ platform    (macOS FFI: libobjc, AppKit, CoreGraphics, Metal)
         ├─ net ──────── url ──── encoding
         │   └── crypto
         ├─ html ─────── dom
         │   └── encoding
         ├─ css
         ├─ dom
         ├─ style ────── dom, css
         ├─ layout ───── dom, style, css, text
         ├─ text         (standalone: font parsing, shaping, rasterization)
         ├─ render ───── platform, layout, dom, css, text, image
         ├─ js ───────── dom
         ├─ url
         ├─ encoding
         └─ image        (standalone: PNG, JPEG, GIF, WebP)
```

Standalone crates (no workspace deps): `platform`, `encoding`, `css`, `dom`, `crypto`, `text`, `image`.

## Commands

```sh
# Build
cargo build --workspace

# Run the browser
cargo run -p we-browser

# Test
cargo test --workspace

# Clippy (treat warnings as errors)
cargo clippy --workspace -- -D warnings

# Format
cargo fmt --all
cargo fmt --all --check   # CI check

# Single crate
cargo test -p we-html
cargo clippy -p we-css -- -D warnings
```

## Conventions

### Zero External Dependencies
No crates.io dependencies. Everything is implemented in workspace crates. If you need functionality, build it.

### Rust Edition
Rust 2021. Workspace-level `edition = "2021"`.

### `unsafe` Policy
`unsafe` is allowed ONLY in:
- `platform` — macOS FFI calls (Obj-C runtime, CoreGraphics, Metal)
- `crypto` — constant-time operations, assembly optimizations
- `js` — JIT compiler (writing/executing machine code), GC pointer manipulation

All other crates must be 100% safe Rust. If you think you need `unsafe` elsewhere, find another way.

### Pure Rust Mandate
We own the full stack. The following are **forbidden**:
- ImageIO (use `image` crate)
- CoreText (use `text` crate)
- Security.framework (use `crypto` crate)
- Any other system framework for functionality we can implement

The ONLY allowed system APIs are:
- `libobjc.dylib` — Objective-C runtime
- AppKit — windowing and event loop
- CoreGraphics — bitmap rendering surface
- Metal — GPU compositor

### JavaScript Engine
- Register-based bytecode (not stack-based) — designed for JIT from day one
- Bytecode format encodes register operands directly
- GC: tri-color mark-and-sweep (white/gray/black)
- JIT: AArch64 baseline compiler (Phase 15)

### Code Style
- Run `cargo fmt` before committing
- Run `cargo clippy --workspace -- -D warnings` — must pass clean
- Keep functions short and focused
- Prefer `Result<T, E>` over panics for recoverable errors
- Tests go in `#[cfg(test)] mod tests` in the same file, or in `tests/` directories for integration tests

## Workflow

1. Pick an issue from tangled
2. Create a worktree: `git worktree add ../we-<branch> -b <branch>`
3. Implement, write tests
4. `cargo clippy --workspace -- -D warnings`
5. `cargo fmt --all --check`
6. `cargo test --workspace`
7. Commit and push
8. Create PR via tangled: `tangled pr create --title "..." --body "..."`
9. After merge, clean up: `git worktree remove ../we-<branch>`

## Tangled CLI Cheat Sheet

```sh
# Issues
tangled issue list
tangled issue create --title "..." --body "..."
tangled issue show <id>

# Pull requests
tangled pr list
tangled pr create --title "..." --body "..."
tangled pr show <id>

# Repo
tangled repo show
```

## Test Suites

| Suite | Location | Run |
|-------|----------|-----|
| html5lib-tests | `tests/html5lib-tests/` | `cargo test -p we-html` |
| Test262 | `tests/test262/` | `cargo test -p we-js` |
| Acid1/Acid2 | loaded via URL | manual: `cargo run -p we-browser -- <url>` |
| WPT | `tests/wpt/` | `cargo test -p we-browser --test wpt` |
| Unit tests | each crate | `cargo test --workspace` |

Test data repos are git submodules under `tests/`.