Skip to content

Commit 40a5e67

Browse files
committed
feat: bootstrap internet-exploder workspace
Cargo workspace with 10 crates for a from-scratch web browser: ie-dom, ie-html, ie-css, ie-js, ie-wasm, ie-net, ie-layout, ie-render, ie-sandbox, ie-shell. All crates compile with stub implementations. Includes mise tasks, CLAUDE.md with architecture/roadmap, and GPL-3.0-or-later license.
0 parents  commit 40a5e67

35 files changed

Lines changed: 6737 additions & 0 deletions

.gitignore

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/target
2+
**/*.rs.bk
3+
*.swp
4+
*.swo
5+
.DS_Store

CLAUDE.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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

Comments
 (0)