|
| 1 | +# CLAUDE.md — Internet Exploder |
| 2 | + |
| 3 | +## What This Is |
| 4 | + |
| 5 | +A web browser from scratch in Rust. Performance, low memory, secure, private by default. Latest web standards only — no legacy/quirks support. GPL-3.0-or-later. |
| 6 | + |
| 7 | +## Architecture |
| 8 | + |
| 9 | +Multi-process with sandboxing: |
| 10 | +- **Browser process** (`ie-shell`): window, tabs, navigation, bookmarks |
| 11 | +- **Renderer process** (per tab): HTML, CSS, layout, JS, painting |
| 12 | +- **Network process** (singleton): all HTTP/TLS traffic |
| 13 | + |
| 14 | +Headless mode is a first-class requirement — the browser must be fully operable without a window, for e2e testing and automation. |
| 15 | + |
| 16 | +### Crate Map |
| 17 | + |
| 18 | +| Crate | Purpose | |
| 19 | +|-------|---------| |
| 20 | +| `ie-shell` | Main binary — browser chrome, event loop (winit), headless mode | |
| 21 | +| `ie-net` | HTTP/1.1, HTTP/2 via hyper + rustls | |
| 22 | +| `ie-html` | WHATWG HTML parser (tokenizer + tree builder) | |
| 23 | +| `ie-css` | CSS parser + style resolution | |
| 24 | +| `ie-dom` | Arena-allocated DOM tree | |
| 25 | +| `ie-js` | JavaScript via Boa engine | |
| 26 | +| `ie-wasm` | WebAssembly execution via wasmtime | |
| 27 | +| `ie-layout` | Layout engine (block, inline, flex, grid) | |
| 28 | +| `ie-render` | GPU rendering via wgpu | |
| 29 | +| `ie-sandbox` | Process spawning, sandboxing, IPC | |
| 30 | + |
| 31 | +### Dependency Flow |
| 32 | + |
| 33 | +``` |
| 34 | +ie-shell |
| 35 | +├── ie-render → ie-layout → ie-dom, ie-css → ie-dom |
| 36 | +├── ie-html → ie-dom |
| 37 | +├── ie-js → ie-dom, ie-wasm |
| 38 | +├── ie-net |
| 39 | +└── ie-sandbox |
| 40 | +``` |
| 41 | + |
| 42 | +## UX Rules |
| 43 | + |
| 44 | +Maximum viewport, minimum chrome: |
| 45 | +- No visible menu bar |
| 46 | +- Tabs hidden while browsing (shortcut to reveal) |
| 47 | +- Address bar on demand only |
| 48 | +- Bookmarks via shortcut, no persistent bar |
| 49 | +- No background prefetch/preload |
| 50 | +- No address bar completion |
| 51 | +- No spell checking |
| 52 | + |
| 53 | +## Roadmap |
| 54 | + |
| 55 | +### Phase 1 — Browser infrastructure (current) |
| 56 | + |
| 57 | +Everything that is NOT rendering a web page: |
| 58 | + |
| 59 | +- `ie-shell`: window management, headless mode, keyboard-driven UI, tab lifecycle, bookmarks storage, address bar overlay |
| 60 | +- `ie-net`: HTTP client, TLS, request/response pipeline |
| 61 | +- `ie-sandbox`: multi-process spawning, IPC protocol, OS-level sandboxing |
| 62 | +- `ie-dom`: data structures (arena allocator, node types, tree operations) |
| 63 | +- e2e test harness: headless browser driving, assertions on navigation and state |
| 64 | + |
| 65 | +### Phase 2 — Web page rendering |
| 66 | + |
| 67 | +Everything that IS rendering a web page: |
| 68 | + |
| 69 | +- `ie-html`: WHATWG tokenizer + tree builder |
| 70 | +- `ie-css`: CSS parsing, cascade, selector matching, computed styles |
| 71 | +- `ie-layout`: block, inline, flex, grid layout |
| 72 | +- `ie-render`: wgpu paint pipeline |
| 73 | +- `ie-js`: Boa integration, DOM bindings, event dispatch |
| 74 | +- `ie-wasm`: WebAssembly execution via wasmtime, JS↔Wasm interop |
| 75 | + |
| 76 | +## Testing |
| 77 | + |
| 78 | +Three levels, all run via `mise run test`: |
| 79 | + |
| 80 | +- **Unit tests**: per-crate `#[test]` modules. Test internals in isolation. |
| 81 | +- **Integration tests**: per-crate `tests/` directories. Test crate public APIs across module boundaries. |
| 82 | +- **E2E tests**: top-level `tests/` directory. Launch the browser in headless mode, navigate to pages (local test fixtures or test server), assert on DOM state, network activity, and tab/bookmark behavior. The headless mode must be fully functional from day one to enable this. |
| 83 | + |
| 84 | +## Build & Test |
| 85 | + |
| 86 | +```bash |
| 87 | +mise run build # Build all crates |
| 88 | +mise run test # Run all tests (unit + integration + e2e) |
| 89 | +mise run fmt:check # Check formatting |
| 90 | +mise run lint:check # Clippy checks |
| 91 | +mise run check # All of the above |
| 92 | +mise run run # Launch the browser |
| 93 | +``` |
| 94 | + |
| 95 | +## Key Design Decisions |
| 96 | + |
| 97 | +- **Latest standards only**: no quirks mode, no legacy HTML elements, no vendor-prefixed CSS |
| 98 | +- **Boa for JS**: pure Rust, no C/C++ FFI |
| 99 | +- **wasmtime for WebAssembly**: pure Rust, Bytecode Alliance, sandboxed execution |
| 100 | +- **wgpu for rendering**: GPU-accelerated, cross-platform; browser chrome uses the same pipeline as page content |
| 101 | +- **rustls over OpenSSL**: pure Rust TLS, no system dependency |
| 102 | +- **Arena-allocated DOM**: cache-friendly, low allocation overhead |
| 103 | +- **No preloading/prefetching**: every network request is explicit |
| 104 | +- **Headless from day one**: enables e2e testing and CI without a display |
0 commit comments