rust_browser/docs/browser_milestone_plan.md

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