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.