pierrelf.com
web engine - experimental web browser
1# we — Development Plan
2
3A from-scratch web browser engine in pure Rust. macOS ARM only. Zero external crate dependencies.
4
5---
6
7## Phase 1: Platform Layer
8
9**Goal:** Open a window on macOS, draw pixels, handle input events.
10
11- Objective-C runtime FFI (`objc_msgSend`, `objc_getClass`, `sel_registerName`, `class_addMethod`, `objc_allocateClassPair/registerClassPair`)
12- Rust wrappers: `msg_send!` macro, `Class`, `Sel`, `Id` types
13- CoreFoundation minimal bindings (`CFString`, `CFRetain`/`CFRelease`)
14- AppKit FFI: `NSApplication`, `NSWindow`, `NSView`, `NSAutoreleasePool`
15- CoreGraphics rendering surface: `CGContext`, `CGBitmapContext`, `CGColorSpace`
16- Custom `NSView` subclass overriding `drawRect:`
17- Basic event handling: window close, resize, key/mouse events
18- `cargo run -p browser` opens a blank window with a colored rectangle
19
20## Phase 2: Pure Rust Font Engine
21
22**Goal:** Parse system fonts and rasterize glyphs without CoreText.
23
24- OTF/TTF parser: read `cmap`, `glyf`, `loca`, `head`, `hhea`, `hmtx`, `maxp`, `OS/2`, `name` tables
25- Glyph outline extraction (TrueType quadratic beziers)
26- Rasterizer: scanline fill of glyph outlines to grayscale bitmaps
27- Basic shaping: horizontal advance, kern table lookups
28- Glyph cache (HashMap of rasterized bitmaps)
29- Load fonts from `/System/Library/Fonts/` or `/Library/Fonts/`
30
31## Phase 3: HTML Parsing + Basic DOM + Block Layout + Software Rendering
32
33**Goal:** Parse HTML, build a DOM, do basic block layout, render text to the window.
34
35- HTML5 tokenizer (per spec state machine)
36- Tree builder (subset: `<html>`, `<head>`, `<body>`, `<p>`, `<h1>`–`<h6>`, `<div>`, `<span>`, `<a>`, `<br>`, `<pre>`, `<title>`, text nodes)
37- DOM tree: `Document`, `Element`, `Text`, `Comment` node types
38- Basic block layout: stack blocks vertically, wrap text into lines
39- Software renderer: paint text glyphs and block backgrounds into CG bitmap
40- Display painted bitmap in the AppKit window
41
42**Test milestone:** Pass html5lib tokenizer tests.
43
44## Phase 4: CSS Parsing + Selector Matching + Cascade + Inline/Text Layout
45
46**Goal:** Parse CSS, match selectors, resolve styles, lay out inline content.
47
48- CSS tokenizer (per spec)
49- CSS parser: selectors, declarations, `@`-rules (at least `@media`, `@import`)
50- Selector matching: type, class, ID, attribute, combinators (descendant, child, sibling)
51- Cascade: origin, specificity, source order
52- Computed style resolution
53- Inline layout: inline boxes, line boxes, text wrapping, vertical alignment
54- Handle `<style>` elements and `style` attributes
55
56**Test milestone:** Pass Acid1.
57
58## Phase 5: Pure Rust Crypto
59
60**Goal:** Implement the cryptographic primitives needed for TLS 1.3.
61
62- SHA-256, SHA-384, SHA-512 (FIPS 180-4)
63- HMAC (RFC 2104)
64- HKDF (RFC 5869)
65- AES-128-GCM, AES-256-GCM (NIST SP 800-38D)
66- ChaCha20-Poly1305 (RFC 8439)
67- X25519 key exchange (RFC 7748)
68- RSA PKCS#1 v1.5 signature verification (RFC 8017)
69- ECDSA signature verification (P-256, P-384) (FIPS 186-4)
70- ASN.1 DER parser
71- X.509 certificate parsing and chain validation
72
73## Phase 6: Pure Rust TLS 1.3 + TCP + DNS + HTTP/1.1 + URL Parser
74
75**Goal:** Fetch resources over HTTPS.
76
77- WHATWG URL parser (full spec compliance)
78- DNS stub resolver (UDP, A/AAAA records, system resolver config)
79- TCP socket wrapper (std::net)
80- TLS 1.3 client (RFC 8446): handshake, record layer, key schedule, certificate verification
81- HTTP/1.1 client: request/response parsing, chunked transfer encoding, keep-alive
82- Connection pooling
83- Content-Length and Transfer-Encoding handling
84
85## Phase 7: Image Decoders
86
87**Goal:** Decode common image formats in pure Rust.
88
89- DEFLATE decompressor (RFC 1951)
90- zlib wrapper (RFC 1950)
91- PNG decoder (RFC 2083): IHDR, IDAT, PLTE, tRNS, interlacing
92- JPEG decoder: baseline DCT, Huffman, JFIF/EXIF markers
93- GIF decoder: LZW, frames, transparency
94- Pixel format conversion (RGBA8)
95
96## Phase 8: Resource Loading + Character Encoding + Real Page Loading
97
98**Goal:** Load and render real web pages.
99
100- WHATWG Encoding Standard: UTF-8, UTF-16, ISO-8859-1, Windows-1252, and other legacy encodings
101- Encoding sniffing (BOM, HTTP header, meta tag, prescan)
102- Resource loader: fetch HTML, CSS, images via `net` crate
103- `<link rel="stylesheet">` and `<img>` loading
104- Data URLs
105- about:blank
106
107## Phase 9: Advanced Layout
108
109**Goal:** Handle modern CSS layout modes.
110
111- Positioned layout: relative, absolute, fixed, sticky
112- Flexbox (CSS Flexible Box Layout Level 1)
113- Floats and clear
114- Overflow and scrolling (scroll bars, `overflow: auto/scroll/hidden`)
115- `display: none`, `visibility: hidden`
116- `box-sizing`, margin collapsing
117- Viewport units, percentage resolution
118
119**Test milestone:** Pass Acid2.
120
121## Phase 10: JavaScript Engine
122
123**Goal:** Execute JavaScript with a JIT-ready architecture.
124
125- Lexer/tokenizer (ECMAScript 2024)
126- Parser → AST
127- Bytecode compiler: register-based bytecode format designed for JIT
128- Register-based VM: instruction dispatch, operand stack
129- Garbage collector: tri-color mark-and-sweep
130- Core built-ins: Object, Array, String, Number, Boolean, Function, Math, Date, RegExp, JSON, Error, Map, Set, Promise, Symbol
131- `typeof`, `instanceof`, prototype chain, closures, `this` binding
132- `var`/`let`/`const` scoping
133- Iterators, generators, async/await
134
135**Test milestone:** Pass Test262 core language subset.
136
137## Phase 11: DOM-JS Bindings + Events + Timers + Fetch API
138
139**Goal:** Connect JavaScript to the DOM and web APIs.
140
141- DOM bindings: `document.getElementById`, `querySelector`, `createElement`, `appendChild`, `textContent`, `innerHTML`
142- Event system: `addEventListener`, `removeEventListener`, `dispatchEvent`, bubbling/capturing
143- `setTimeout`, `setInterval`, `requestAnimationFrame`
144- Fetch API (backed by `net` crate)
145- Console API (`console.log`, `console.error`, `console.warn`)
146- `<script>` element loading and execution (defer, async)
147
148**Test milestone:** Begin WPT pass rate tracking.
149
150## Phase 12: Metal GPU Compositor
151
152**Goal:** GPU-accelerated rendering.
153
154- Metal device/command queue setup via `platform` crate
155- Texture atlas for glyph cache
156- Display list → Metal render passes
157- Compositing layers (for transforms, opacity, will-change)
158- Double-buffered presentation
159- Fallback to software rendering when Metal unavailable
160
161## Phase 13: Advanced CSS
162
163**Goal:** Modern CSS features.
164
165- CSS Grid Layout (Level 1)
166- CSS Animations (`@keyframes`, `animation-*`)
167- CSS Transitions (`transition-*`)
168- CSS Custom Properties (`--var`, `var()`)
169- `@font-face` (load and parse web fonts via `text` + `net`)
170- `calc()`, `min()`, `max()`, `clamp()`
171- Media queries (screen width, prefers-color-scheme)
172- SVG basics: `<svg>`, `<rect>`, `<circle>`, `<path>`, `<text>`
173
174## Phase 14: Security + Storage
175
176**Goal:** Web security model and client-side storage.
177
178- Same-Origin Policy enforcement
179- CORS (preflight, simple requests, credentialed requests)
180- Content Security Policy (CSP Level 2)
181- Cookie jar (`Set-Cookie` parsing, `Cookie` header, SameSite, Secure, HttpOnly)
182- `localStorage` / `sessionStorage`
183- IndexedDB (basic subset)
184- `<iframe>` isolation and `postMessage`
185- Referrer Policy
186
187## Phase 15: Performance
188
189**Goal:** Production-grade performance.
190
191- Baseline JIT compiler: bytecode → AArch64 machine code
192- Inline caches for property access
193- Incremental layout (dirty bit propagation)
194- HTTP/2 (HPACK, multiplexed streams, flow control)
195- Speculative HTML parsing (off-main-thread tokenization)
196- Style sharing cache
197- Layer tree and damage tracking for minimal repaints
198- Memory profiling and optimization pass
199
200---
201
202## Test Suites
203
204| Suite | Crate(s) | Phase |
205|-------|----------|-------|
206| html5lib-tests (tokenizer) | `html` | 3 |
207| Acid1 | `css`, `style`, `layout`, `render` | 4 |
208| Acid2 | `layout`, `render` | 9 |
209| Test262 (core language) | `js` | 10 |
210| WPT (progressive) | all | 11+ |