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#

# 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#

# 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#

Test data repos are git submodules under tests/.