rust_browser/_bmad-output/planning-artifacts/product-brief-rust_browser-2026-03-05.md

stepsCompleted, inputDocuments, date, author

stepsCompleted	inputDocuments	date	author
1 2 3 4 5	_bmad-output/project-context.md docs/index.md docs/project-overview.md docs/architecture.md docs/component-inventory.md docs/browser_milestone_plan.md docs/known_limitations_log.md	2026-03-05	Zach

Product Brief: rust_browser

Executive Summary

rust_browser is an experimental web browser engine written entirely in Rust — and entirely by LLMs. The project demonstrates that AI-assisted software engineering can produce a non-trivial, real-world systems application: a from-scratch browser with a complete rendering pipeline, custom JavaScript engine, and desktop shell, all directed by a single human without writing any code. The long-term goal is a privacy-focused, memory-safe browser capable of rendering modern websites for daily use.

---

Core Vision

Problem Statement

Building a web browser has long been considered one of the most complex software engineering challenges — requiring massive teams, decades of accumulated code, and deep expertise across dozens of domains. This conventional wisdom means the browser market is dominated by a handful of engines (Blink, Gecko, WebKit), all carrying enormous legacy codebases that are difficult to learn from, contribute to, or audit for privacy.

Problem Impact

• For learners: Browser internals remain opaque. Existing engines are too large and complex to serve as learning resources for rendering pipelines, JS engines, or networking.
• For privacy-conscious users: Major browsers are built by companies with advertising business models. Telemetry, tracking, and data collection are deeply embedded and difficult to fully remove.
• For the industry: The assumption that browsers require massive teams creates a moat that discourages new entrants and alternative approaches.

Why Existing Solutions Fall Short

• Chromium/Firefox/WebKit are millions of lines of C++ with decades of legacy — practically impossible for one person to understand end-to-end.
• Privacy-focused forks (Brave, LibreWolf) inherit the complexity and attack surface of their parent engines.
• Educational browser projects (like Robinson) are too minimal to handle real websites.
• No existing project demonstrates that a single person, aided by LLMs, can build a functional browser from scratch.

Proposed Solution

rust_browser is a from-scratch browser engine that prioritizes correctness, safety, and auditability. Built entirely by LLMs under human direction, it implements the full rendering pipeline (HTML parsing, CSS, layout, painting), a custom JavaScript engine, and a desktop shell. The architecture emphasizes clear crate boundaries, deterministic behavior, and comprehensive test suites (golden tests, WPT, Test262) as the quality backstop for AI-generated code.

Key Differentiators

• 100% LLM-authored code — proving that AI can build complex systems software under human direction, without a massive engineering team
• Rust from the ground up — memory safety by default, with unsafe restricted to two platform crates
• Clean-slate privacy — no telemetry, no inherited tracking infrastructure, with a path toward built-in tracker blocking
• Correctness-first philosophy — comprehensive conformance testing (WPT, Test262) ensures quality despite AI authorship
• Fully comprehensible — small enough (~22 crates) for one person to understand the entire system

Target Users

Primary Users

Zach — The AI-Directed Architect A developer who learns by building. Zach directs LLMs to implement a full browser engine without writing code himself, using the project as a vehicle to deeply understand rendering pipelines, JS engines, CSS/HTML, and networking. His measure of success is being able to daily-drive rust_browser on real websites like YouTube, CNN, and Yahoo. He values correctness, clean architecture, and comprehensive test suites as the quality backstop for AI-generated code.

The Rust Tinkerer A developer drawn to Rust and to young, approachable projects. They're tired of trying to learn browser internals from million-line C++ codebases and want something they can actually read end-to-end. rust_browser's 22-crate architecture, clear layering, and small footprint make it possible to trace a request from HTML parse through layout to pixels on screen. They're primarily readers and learners — contributors would come later as the project matures.

Secondary Users

The AI-Development Enthusiast A broader audience interested in the methodology, not necessarily the browser itself. They want to understand what's possible when one person directs LLMs to build complex systems software. rust_browser serves as a case study and proof point — "here's what AI-assisted engineering can produce today." They may never clone the repo, but they follow the project's progress and share its story.

User Journey

Zach's Journey:

• Core loop: Identify the next capability gap (e.g., CSS feature, JS built-in, layout mode) → direct LLMs to implement it → validate with tests (golden, WPT, Test262) → try real websites → repeat
• Success moment: Loading CNN.com and it renders correctly enough to read the news
• Long-term: Daily-driving rust_browser as a primary browser for general use

Tinkerer's Journey:

• Discovery: Finds rust_browser via Rust community, GitHub trending, or a blog post about the AI-built angle
• Onboarding: Clones the repo, runs cargo run -p app_browser -- https://example.com, explores the crate structure
• Aha moment: Tracing a single <div> from HTML parse through DOM → style → layout → display list → pixels and understanding each step
• Long-term: Returns to the project as a reference when exploring specific browser subsystems

AI-Dev Enthusiast's Journey:

• Discovery: Sees the project mentioned in an article or discussion about AI-assisted development
• Engagement: Reviews the project scope (22 crates, custom JS engine, rendering pipeline) and is impressed by what LLM-directed development achieved
• Value: Uses rust_browser as evidence in their own thinking about AI development workflows and capabilities

Success Metrics

Rendering Correctness

• WPT (Web Platform Tests) pass rate — directional improvement over time; no fixed target other than eventual 100%. Measures CSS, HTML, and DOM spec compliance.
• Test262 (JavaScript) conformance rate — directional improvement over time. Measures ECMAScript spec compliance of the custom JS engine.
• Golden test coverage — regression test count grows with each feature addition and bug fix. Every bug fix requires a regression test.
• CI gate — just ci must pass as a merge gate (fmt, lint, test, policy, metrics). This is a hard requirement, not a metric to track.

Real-Site Usability Tiers

1. Pages load and are browsable — sites render with recognizable layout, text is readable, links work. (Largely achieved today)
2. Real-world JavaScript works — JS-dependent sites function: dynamic content loads, interactive elements respond, basic SPAs navigate.
3. Full forms, cookies, and sessions — login flows work, form submission/validation functions, cookies persist across navigation, session state is maintained.
4. Heavy sites function properly — YouTube, Gmail, and similar JS-heavy applications render and function as expected.

Site Tracking

• Maintain a growing target site list tracked via the investigations/ directory
• Each investigated site produces a report documenting what works, what breaks, and what needs to be implemented
• Progress is measured by sites moving up through the usability tiers over time

Business Objectives

N/A — rust_browser is a learning-driven open-source project, not a revenue-generating product. Success is measured by technical capability, not business metrics.

Key Performance Indicators

KPI	Measurement	Target
WPT pass rate	just test (WPT harness)	Directional increase per milestone
Test262 conformance	just test262-full	Directional increase per milestone
Golden test count	Count of tests/goldens/expected/ files	Grows with each feature/fix
CI health	just ci pass/fail	100% pass (merge gate)
Sites at Tier 1+	Count from investigations	Grows over time
Sites at Tier 4	Count from investigations	Long-term north star

MVP Scope

Core Features

The MVP focuses on filling out CSS, HTML, and JavaScript coverage to move real websites from Tier 1 (pages load and are browsable) toward Tier 2 (real-world JS works) and Tier 3 (forms/cookies/sessions).

CSS Completeness:

• Fill gaps in CSS 2.1 property support (per docs/CSS2.1_Implementation_Checklist.md)
• Improve layout correctness: block, inline, flexbox, table, and positioned elements
• Fix layout regressions surfaced by real-site investigations
• Add missing CSS features commonly used by real sites (e.g., text-decoration, border-collapse, CSS shorthand font)

HTML Completeness:

• Expand element and attribute support (per docs/HTML5_Implementation_Checklist.md)
• Improve form element handling (<input>, <select>, <textarea>, <form> submission)
• Better error recovery in HTML parsing for real-world (messy) markup

JavaScript Completeness:

• Expand ES6+ coverage in the custom JS engine (per Test262 conformance gaps)
• Improve built-in object completeness (Array, String, Object, Date, RegExp methods)
• Better error handling and spec-compliance in edge cases
• Expand DOM API bindings (querySelector, classList, style manipulation, event types)

Layout Correctness:

• Fix layout issues identified through site investigations
• Improve handling of real-world CSS patterns (centering, responsive layouts, common flexbox patterns)
• Better handling of replaced elements (images, form controls)

Out of Scope for MVP

• GPU-accelerated rendering (CPU rasterization is sufficient)
• Tabbed browsing UI
• Browser extensions / add-on system
• Service workers
• HTTP/3
• WebRTC, WebSockets, or advanced networking protocols
• CSS Grid layout
• CSS animations and transitions
• Complex transforms and filters
• Web Workers (JS threading)
• JIT compilation for JS engine
• Internationalization beyond basic Latin text

MVP Success Criteria

• WPT and Test262 pass rates show measurable improvement over current baseline
• 5+ real websites from the investigations list move up at least one usability tier
• No regressions — golden tests and CI gate remain green
• A mainstream content site (e.g., CNN, Yahoo) renders well enough to read and navigate

Future Vision

Near-term (post-MVP):

• Networking maturity: cookies, caching, better redirect/error handling (Milestone 7)
• Session persistence and login flows
• CSS Grid layout support

Medium-term:

• Tracker/ad blocking built into the engine
• Tabbed browsing
• CSS animations and transitions
• Improved JS performance (potential bytecode compilation)

Long-term:

• GPU-accelerated rendering pipeline
• Community contributions and open-source growth
• Daily-driver capable on heavy sites (YouTube, Gmail)
• Potential privacy-focused browser product for broader audience