348 lines
7.0 KiB
Markdown
348 lines
7.0 KiB
Markdown
# Milestone Plan – Crates, Scope, Stubs vs Implement
|
||
|
||
## Purpose
|
||
|
||
This document proposes an incremental implementation plan that reaches a usable, testable browser quickly, while preserving clean architecture boundaries.
|
||
|
||
Each milestone is a **vertical slice** that ends in:
|
||
|
||
* a demoable capability (pixels on screen)
|
||
* a permanent test harness extension (goldens, unit tests, and/or fuzz targets)
|
||
|
||
For each milestone, we list:
|
||
|
||
* **Primary crates involved**
|
||
* **What to implement for real**
|
||
* **What to stub** (explicitly) to avoid premature complexity
|
||
|
||
## Global Constraints (Apply to Every Milestone)
|
||
|
||
### Determinism
|
||
|
||
* Headless pipeline must be deterministic (fixed fonts/config where possible).
|
||
* Prefer layout tree + display list dumps for stable golden testing.
|
||
|
||
### Testing Gate
|
||
|
||
Every milestone must add:
|
||
|
||
* at least **10 new golden pages** (HTML fixtures + expected outputs)
|
||
* at least **one unit/property test** in the touched subsystem
|
||
|
||
## Milestone 0 — Harness First: Headless Pipeline + Goldens
|
||
|
||
### Goal
|
||
|
||
A deterministic headless runner that can parse → style → layout → paint and produce stable outputs.
|
||
|
||
### Crates involved
|
||
|
||
* `app_browser` (optional: only for wiring)
|
||
* `browser_runtime` (minimal, optional)
|
||
* `shared`
|
||
* `dom`
|
||
* `html`
|
||
* `css`
|
||
* `selectors` (stubbed or minimal)
|
||
* `style`
|
||
* `layout`
|
||
* `display_list`
|
||
* `render` (CPU-only)
|
||
|
||
### Implement (for real)
|
||
|
||
* A command-line or internal harness entry point (can live in `app_browser` initially) that:
|
||
|
||
* loads HTML from a file/string
|
||
* runs the pipeline
|
||
* writes outputs:
|
||
|
||
* `*.layout.txt` (layout tree dump)
|
||
* `*.dl.txt` (display list dump)
|
||
* optional `*.png` (pixel snapshot) for a small curated set
|
||
* A golden test runner:
|
||
|
||
* input: `tests/goldens/*.html`
|
||
* expected: `tests/goldens/expected/*.layout.txt`, `*.dl.txt`
|
||
|
||
### Stub
|
||
|
||
* Networking (`net`) – not used yet
|
||
* Fonts shaping (`fonts`) – use a single built-in/test font or a simplified text measurer
|
||
* Images (`image`) – not used yet
|
||
* Advanced CSS selector engine – only what is needed for inline style and tag selectors
|
||
|
||
## Milestone 1 — Static HTML + Minimal CSS + Basic Painting
|
||
|
||
### Goal
|
||
|
||
View simple static pages (no network, no JS) with basic layout and paint.
|
||
|
||
### Crates involved
|
||
|
||
* `shared`
|
||
* `dom`, `html`
|
||
* `css`, `selectors`, `style`
|
||
* `layout`
|
||
* `display_list`, `render`
|
||
* `platform` (only if showing a window)
|
||
* `app_browser` (simple window or file open)
|
||
|
||
### Implement (for real)
|
||
|
||
**HTML/DOM**
|
||
|
||
* Elements: `html`, `head`, `body`, `div`, `p`, `span`, `h1/h2`, text nodes
|
||
* DOM tree construction and basic mutation APIs
|
||
|
||
**CSS**
|
||
|
||
* Sources:
|
||
|
||
* inline `style="..."`
|
||
* `<style>` tag
|
||
* Properties (initial set):
|
||
|
||
* `display` (block/inline)
|
||
* `margin`, `padding`, `border` (simple)
|
||
* `background-color`, `color`
|
||
* `font-size`
|
||
* `width`, `height` (simple absolute/auto)
|
||
|
||
**Selectors**
|
||
|
||
* Type selectors (tag)
|
||
* `.class` and `#id` (optional but high value)
|
||
* Specificity basics
|
||
|
||
**Layout**
|
||
|
||
* Normal flow block layout (vertical stacking)
|
||
* Inline text layout (simple line breaking is acceptable)
|
||
|
||
**Painting**
|
||
|
||
* Backgrounds, borders, text
|
||
* Display list generation normalized for stable diffs
|
||
|
||
**App**
|
||
|
||
* Open local HTML file and render it
|
||
* Minimal reload
|
||
|
||
### Stub
|
||
|
||
* Flexbox/grid
|
||
* Positioning beyond normal flow
|
||
* Full CSS cascade edge cases
|
||
* Fonts shaping: approximate text widths OK initially; keep it deterministic
|
||
* Images
|
||
* Networking
|
||
|
||
## Milestone 2 — Navigation + `file://` + Minimal `http://`
|
||
|
||
### Goal
|
||
|
||
A basic “type a URL” experience with stable navigation lifecycle.
|
||
|
||
### Crates involved
|
||
|
||
* `app_browser`
|
||
* `browser_runtime`
|
||
* `platform`
|
||
* `shared`
|
||
* `net` (minimal)
|
||
* Engine crates from Milestone 1
|
||
|
||
### Implement (for real)
|
||
|
||
**Runtime**
|
||
|
||
* Tabs/browsing context (single tab initially)
|
||
* Navigation lifecycle states:
|
||
|
||
* start → loading → committed → complete/failed
|
||
* History navigation:
|
||
|
||
* back
|
||
* forward
|
||
|
||
**URL**
|
||
|
||
* Parse/normalize URLs
|
||
* `file://` loading is required
|
||
|
||
**HTTP (minimal)**
|
||
|
||
* Basic GET with redirects (limited)
|
||
* Content-type sniffing simplified
|
||
|
||
**UI**
|
||
|
||
* Address bar
|
||
* Reload
|
||
* Stop
|
||
* Status bar (loading indicator)
|
||
* Progress bar (download/processing feedback)
|
||
|
||
### Stub
|
||
|
||
* Cache
|
||
* Cookies
|
||
* HTTPS/TLS edge handling beyond “works”
|
||
* Service workers
|
||
|
||
## Milestone 3 — Expand CSS for Real Pages
|
||
|
||
### Goal
|
||
|
||
Cover enough CSS to render many static sites without obvious breakage.
|
||
|
||
### Crates involved
|
||
|
||
* `css`, `selectors`, `style`
|
||
* `layout`
|
||
* `display_list`, `render`
|
||
* `shared`
|
||
|
||
### Implement (for real)
|
||
|
||
Add in slices:
|
||
|
||
1. Better selectors: descendant, child (`>`), attribute basics (optional)
|
||
2. `position: relative/absolute` (limited)
|
||
3. Stacking contexts and `z-index` where needed
|
||
4. `overflow: hidden` and clipping
|
||
5. Flexbox (high impact)
|
||
|
||
### Stub
|
||
|
||
* Grid
|
||
* Complex transforms
|
||
* Filters
|
||
|
||
## Milestone 4 — Images
|
||
|
||
### Goal
|
||
|
||
Support `<img>` with basic sizing, decode, and paint.
|
||
|
||
### Crates involved
|
||
|
||
* `html` (img element)
|
||
* `dom`
|
||
* `net` (if remote images)
|
||
* `image`
|
||
* `layout`
|
||
* `display_list`, `render`
|
||
* `shared`
|
||
|
||
### Implement (for real)
|
||
|
||
* `<img src>` element handling
|
||
* Image decode pipeline
|
||
* Layout as a replaced element:
|
||
|
||
* intrinsic size
|
||
* width/height attributes (optional)
|
||
* Paint image in display list
|
||
|
||
### Stub
|
||
|
||
* Advanced image formats
|
||
* Responsive images (`srcset`)
|
||
* Lazy loading
|
||
|
||
## Milestone 5 — Real Fonts + Text Shaping (Incremental)
|
||
|
||
### Goal
|
||
|
||
Move from the embedded monospace test font to real fonts and shaping, while keeping layout deterministic.
|
||
|
||
### Crates involved
|
||
|
||
* `fonts`
|
||
* `style`, `layout`
|
||
* `display_list`, `render`
|
||
* `shared`
|
||
|
||
### Implement (for real)
|
||
|
||
* Font loading (local font files)
|
||
* Text shaping and metrics (incremental: latin first)
|
||
* Font fallback (minimal)
|
||
* Deterministic font config for tests
|
||
|
||
### Stub
|
||
|
||
* Variable fonts
|
||
* Full internationalization coverage
|
||
|
||
## Milestone 6 — JavaScript (Interpreter-First) + Minimal DOM Bindings
|
||
|
||
### Goal
|
||
|
||
Run basic scripts that can manipulate DOM and respond to events.
|
||
|
||
### Crates involved
|
||
|
||
* `js`, `js_vm`, `js_parser`
|
||
* `web_api`
|
||
* `dom`
|
||
* `browser_runtime`
|
||
* `shared`
|
||
|
||
### Implement (for real)
|
||
|
||
* JS execution integrated with event loop
|
||
* Microtasks + Promises (minimal)
|
||
* DOM bindings:
|
||
|
||
* query selection (partial)
|
||
* text/content manipulation
|
||
* basic events (click)
|
||
|
||
### Stub
|
||
|
||
* Full Web APIs (fetch, WebRTC, etc.)
|
||
* JIT
|
||
* Workers
|
||
|
||
## Milestone 7 — Networking Maturity + Storage
|
||
|
||
### Goal
|
||
|
||
Move from “demo networking” to “usable networking.”
|
||
|
||
### Crates involved
|
||
|
||
* `net`
|
||
* `storage`
|
||
* `browser_runtime`
|
||
* `shared`
|
||
|
||
### Implement (for real)
|
||
|
||
* Cache basics
|
||
* Cookies and scoping rules
|
||
* Better redirect and error handling
|
||
* Basic HTTPS policy improvements
|
||
|
||
### Stub
|
||
|
||
* Service workers
|
||
* HTTP/3
|
||
|
||
## What to Measure at Each Milestone
|
||
|
||
* Golden pass rate (layout + display list)
|
||
* Crash-free runs under sanitizers (Linux)
|
||
* Flake rate (rerun goldens multiple times)
|
||
* Simple performance smoke (startup + render a fixed page)
|
||
|
||
## Suggested First Target
|
||
|
||
Aim for **Milestone 1 + file loading** as the first true “browser feels real” checkpoint.
|
||
|
||
This yields a visible demo and a stable test harness that accelerates all later work.
|