rust_browser/docs/browser_architecture_initial_exploration.md

Browser Architecture – Initial Exploration

Purpose of this Document

This document captures an initial, intentionally incomplete architecture for a new desktop web browser targeting macOS and Linux. The goal is not to lock in design decisions, but to establish shared assumptions, define system boundaries, and explain why certain early choices are preferred.

The guiding principles at this stage are:

• Correctness before performance
• Determinism before concurrency
• Clear separation of concerns
• Designs that can evolve without large rewrites

Scope and Non-Goals

In Scope (Initial Phases)

• Desktop browser (macOS, Linux)
• Custom JavaScript engine (interpreter-first)
• Core web platform: JS, DOM, HTML, CSS, networking
• Emphasis on testability, debuggability, and maintainability

Explicit Non-Goals (Initial Phases)

• Mobile platforms
• Full standards completeness
• Maximum performance on day one
• Early JIT or aggressive multi-threading

High-Level Architecture Overview

Major Subsystems

• JavaScript Engine

  • Interpreter-first execution
  • Spec-correct language semantics as primary goal
  • Designed to support future JIT modes

• DOM & Web Platform Layer

  • DOM tree, events, WebIDL bindings
  • Integration point between JS and rendering

• HTML / CSS Parsing & Styling

  • Tokenizers and parsers treated as untrusted input handlers
  • Style computation and selector matching

• Layout Engine

  • Block/inline layout as initial focus
  • Deterministic, single-threaded layout passes

• Rendering & Graphics

  • Display list abstraction
  • CPU execution initially, GPU-backed presentation
  • Backend-swappable design

• Networking & Resource Loading

  • Asynchronous resource fetching
  • Isolated from main execution via worker threads

Threading Model (Initial)

Phase 1: Simplicity and Determinism

• Main thread owns:

  • JavaScript execution
  • DOM mutations
  • Style computation
  • Layout
  • Display list generation

• Worker threads limited to:

  • Network I/O
  • Image decoding
  • Optional font shaping / raster prep (later)

Rationale:

• Minimizes race conditions
• Simplifies debugging and testing
• Enables deterministic replay and flake reduction

Phase 2: Incremental Concurrency (Future)

• Add a compositor/render thread
• Main thread produces immutable display lists
• Renderer consumes display lists asynchronously

Multi-threaded DOM or layout is explicitly avoided early due to complexity and maintenance cost.

Graphics Pipeline Strategy

Display List as a Core Abstraction

• Layout and paint produce a normalized display list
• Display list is:
  • Deterministic
  • Serializable (for debugging/testing)
  • Backend-agnostic

Execution Strategy

• Initial execution via CPU rasterization
• Final presentation via GPU upload
• GPU-native execution can be added later without rewriting layout/paint

JavaScript Engine Integration

Interpreter-First Strategy

• Interpreter is the semantic oracle
• Clear separation between:
  • Language semantics
  • Host environment bindings (DOM, Web APIs)

Future JIT Readiness

• Execution modes abstracted from the start:

  • Interpreter
  • Baseline JIT (future)
  • Optimizing JIT (optional, future)

• Design goal: interpreter remains the correctness reference for all modes

Determinism as a Design Requirement

The engine should support a test/debug mode with:

• Deterministic RNG
• Controllable clocks and timers
• Deterministic task and microtask ordering
• Explicit GC control hooks

This is foundational for reliable testing and future concurrency.

Open Questions (To Be Refined)

• Garbage collection strategy
• Graphics backend choices (Metal/Vulkan/OpenGL)
• Sandboxing and process isolation model
• Networking stack ownership vs system libraries
• Long-term multiprocess strategy

This document is expected to evolve rapidly as implementation and testing inform design decisions.