rust_browser/_bmad-output/planning-artifacts/prd.md

---
stepsCompleted:
  - step-01-init
  - step-02-discovery
  - step-02b-vision
  - step-02c-executive-summary
  - step-03-success
  - step-04-journeys
  - step-05-domain
  - step-06-innovation
  - step-07-project-type
  - step-08-scoping
  - step-09-functional
  - step-10-nonfunctional
  - step-11-polish
  - step-12-complete
date: '2026-03-09'
classification:
  projectType: desktop_app
  domain: general_systems_software
  complexity: high
  projectContext: brownfield
inputDocuments:
  - _bmad-output/planning-artifacts/product-brief-rust_browser-2026-03-05.md
  - _bmad-output/project-context.md
  - docs/index.md
  - docs/project-overview.md
  - docs/architecture.md
  - docs/component-inventory.md
  - docs/development-guide.md
  - docs/CSS2.1_Implementation_Checklist.md
  - docs/HTML5_Implementation_Checklist.md
  - docs/browser_milestone_plan.md
  - docs/browser_architecture_initial_exploration.md
  - docs/browser_project_structure_modularization_guide.md
  - docs/browser_testing_strategy_high_level_to_detailed.md
  - docs/milestone_6_phased_implementation_plan.md
  - docs/DOM_Implementation_Checklist.md
  - docs/JavaScript_Implementation_Checklist.md
  - docs/known_limitations_log.md
  - docs/source-tree-analysis.md
---

# Product Requirements Document - rust_browser

**Author:** Zach
**Date:** 2026-03-09

## Executive Summary

Building a web browser has long required massive teams, decades of accumulated code, and deep expertise across dozens of domains. The browser market is dominated by a handful of engines (Blink, Gecko, WebKit), all carrying million-line legacy C++ codebases that are difficult to learn from, contribute to, or audit for privacy. Privacy-focused forks inherit the complexity and attack surface of their parent engines. Educational browser projects 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.

rust_browser is a from-scratch web browser engine written entirely in Rust and authored entirely by LLMs under human direction. The project has progressed through seven milestones -- delivering a complete rendering pipeline (HTML parsing, CSS styling, layout, CPU rasterization), a custom JavaScript engine with 70% Test262 conformance, DOM bindings, event dispatch, a desktop shell with navigation, history, and basic form support, and networking maturity (cookies, HTTP caching, sessions, storage).

The browser renders real websites at Tier 1 (pages load, text readable, links work) with some sites approaching Tier 2 (JS-dependent content functions). With Milestone 7 (networking maturity) complete, the strategy now shifts from pragmatic site-by-site fixes to systematic spec compliance -- completing CSS 2.1, HTML5, and ECMAScript coverage to resolve the long tail of rendering issues efficiently. Once spec compliance reaches critical mass, development pivots to real-world browser features: tabbed browsing, tracker/ad blocking, CSS animations, and session persistence. The end goal is a privacy-first, memory-safe browser that Zach can daily-drive across 90%+ of websites without noticing gaps.

## What Makes This Special

- **Fully comprehensible architecture** -- 22 crates, ~340 source files, strict 4-layer hierarchy. Small enough for one person to understand the entire system end-to-end, unlike million-line legacy engines.
- **100% LLM-authored code** -- demonstrates that AI-assisted engineering can produce complex systems software (custom JS engine, rendering pipeline, desktop shell) under a single human's direction.
- **Memory safety by default** -- Rust with `unsafe` forbidden except in two platform crates, enforced by CI. No inherited C++ attack surface.
- **Clean-slate privacy** -- no telemetry, no inherited tracking infrastructure. Privacy is architectural, not bolted on.
- **Correctness-first methodology** -- comprehensive test suites (golden tests, WPT, Test262) serve as the quality backstop. Every bug fix requires a regression test. CI gate enforces fmt, lint, test, and safety policy on every change.

## Project Classification

| Attribute | Value |
|---|---|
| **Project Type** | Desktop Application (Browser Engine) |
| **Domain** | General / Systems Software |
| **Complexity** | High (technical: web standards surface area, multi-subsystem interaction) |
| **Project Context** | Brownfield (22-crate workspace, Milestones 0-7 complete, active development) |

## Success Criteria

### User Success

- **Daily-driver capable** -- Zach uses rust_browser as his primary browser without noticing gaps. The bar is indistinguishable from Firefox/Chrome for daily use.
- **Full interactivity** -- JS-heavy sites (YouTube, Gmail, web apps) function correctly: dynamic content loads, forms submit, sessions persist, interactive elements respond.
- **Site compatibility** -- 90%+ of websites Zach visits work without issues. Tracked via the `investigations/` directory with sites progressing through usability tiers:
  - Tier 1: Pages load, text readable, links work
  - Tier 2: JS-dependent content functions
  - Tier 3: Forms, cookies, sessions work
  - Tier 4: Heavy JS applications function properly

### Business Success

N/A -- rust_browser is a learning-driven open-source project. Success is measured by technical capability and personal usability, not revenue or user growth. Community interest and contributions are welcome but not a success metric.

### Technical Success

- **CSS 2.1: 100% checklist completion** -- every item in `docs/CSS2.1_Implementation_Checklist.md` checked, implemented through the full pipeline (parse/cascade/compute/layout/paint), and tested.
- **HTML5: 100% checklist completion** -- every item in `docs/HTML5_Implementation_Checklist.md` checked, with end-to-end support (parse/DOM/style/layout/render/runtime), and tested.
- **ECMAScript: full Test262 conformance** -- pass rate against the complete tc39/test262 suite (50,000+ tests) reaches 95%+. Current vendored subset at 70%; full suite pass rate is the real measure.
- **WPT pass rate 90%+** -- Web Platform Tests as the ground truth for cross-spec compliance across CSS, HTML, and DOM.
- **Zero regressions** -- CI gate green on every change. Golden tests, WPT harness, and Test262 harness prevent backsliding.
- **No crashes on malformed input** -- HTML, CSS, and JS parsers handle arbitrary input without panics. Verified by fuzz testing and malformed-input test cases.

### Measurable Outcomes

| Metric | Current Baseline | Target | Measurement Method |
|---|---|---|---|
| CSS 2.1 checklist completion | ~30% checked | 100% | Manual checklist in `docs/CSS2.1_Implementation_Checklist.md` |
| HTML5 checklist completion | ~25% checked | 100% | Manual checklist in `docs/HTML5_Implementation_Checklist.md` |
| Test262 full suite pass rate | <10% (estimated) | 95%+ | `just test262-full` against tc39/test262 |
| WPT pass rate | <5% (estimated) | 90%+ | WPT harness in CI |
| Sites at Tier 3+ | 0 | 10+ commonly-used sites | Investigation reports in `investigations/` |
| Sites at Tier 4 | 0 | 5+ (YouTube, Gmail, etc.) | Investigation reports in `investigations/` |
| Golden test count | Growing | Grows with every feature/fix | Count of `tests/goldens/expected/` files |

## Product Scope & Phased Development

### MVP Strategy & Philosophy

**MVP Approach:** Problem-solving MVP -- deliver a functional browser that renders real websites and handles basic navigation, forms, and networking. The MVP proves the architecture works end-to-end and establishes the foundation for systematic improvement.

**Resource Model:** Single human directing LLMs. No team scaling planned. The constraint is attention and direction, not headcount.

### Phase 1: MVP (Milestone 7 Completion) -- COMPLETE

**Core Journey Supported:** Architect's Development Loop (site investigation -> fix -> validate)

**Delivered Capabilities:**
- Complete rendering pipeline (HTML/CSS/layout/paint) -- done
- Custom JS engine with DOM bindings, events, promises -- done
- Desktop shell with navigation, history, URL bar -- done
- HTTP caching and conditional requests -- done
- Cookie jar with domain scoping and persistence -- done
- Session handling (login flows work across navigation) -- done
- Improved redirect and error handling -- done
- Site-specific fixes for Tier 1-2 coverage on mainstream sites -- done

**Exit Criteria:** Met. Milestone 7 complete, 5+ investigated sites at solid Tier 1-2, CI green, no regressions.

### Phase 2: Spec Compliance (Growth)

**Core Journey Supported:** Architect's Development Loop (checklist-driven spec compliance)

**Sequencing:** CSS 2.1 -> HTML5 -> ECMAScript, with interleaving as necessary when features depend on each other or when a capability is needed for testing.

**Phase 2a: CSS 2.1 Full Compliance**
- Margin collapsing: parent/first-child cases, border/padding/clearance interactions
- Stacking contexts and z-index: creation rules, full painting order
- Positioning completeness: fixed position, top/right/bottom/left auto resolution, clip
- Generated content: `::before`/`::after` with `content`, `counter()`, `attr()`
- Tables: border-collapse, caption-side, empty-cells, full cell/row/column sizing
- Lists and counters: list-style-position/image, counter-reset/increment
- Backgrounds: full background shorthand, background-image url(), repeat, attachment, position
- Borders: full border-style set (double, groove, ridge, inset, outset), outline
- Text: text-indent, text-decoration completeness, word-spacing, direction/unicode-bidi
- Fonts: font shorthand, font-variant, font metrics integration (ex units)
- Overflow: scroll/auto behavior, full clipping
- Media: @import, @media with proper media type support

**Phase 2b: HTML5 Full Compliance**
- Parsing: full tokenizer state machine, tree builder insertion modes, adoption agency, foster parenting
- DOM core: DocumentFragment, insertBefore/replaceChild, live collections, querySelector/querySelectorAll
- Events: capture phase, keyboard/mouse/focus events, full event dispatch
- Script loading: async/defer scripts, module scripts
- Forms: constraint validation, full input types, select/option behavior, multipart/form-data
- Document lifecycle: DOMContentLoaded, load event, readyState
- iframe support
- Base URL resolution (<base href>)

**Phase 2c: ECMAScript Full Compliance**
- Generators and iterators (full iterator protocol)
- async/await
- ES modules (import/export)
- Full built-in coverage (complete Array/String/Object/Date/RegExp/Map/Set methods)
- WeakRef and FinalizationRegistry
- Full strict mode edge cases
- Remaining Test262 gaps across all feature areas

**Phase 2d: Modern CSS**
- CSS Grid layout
- CSS animations and transitions

### Phase 3: Daily Driver (Vision)

**Core Journey Supported:** Daily Driver (indistinguishable from Firefox/Chrome)

**Browser Features:**
- Tabbed browsing UI
- Tracker/ad blocking (engine-level)
- Session persistence across restarts

**System Integration:**
- System font discovery (OS-installed fonts beyond bundled Noto Sans)
- Clipboard integration (copy/paste)
- File dialogs for upload/download
- Default browser registration (URL handler)
- System notifications (tied to Web Notifications API)

**Engine Capabilities:**
- GPU-accelerated rendering
- CSS transforms and filters
- Web Workers
- WebSockets
- Service Workers
- WebRTC
- JIT compilation for JS engine
- HTTP/3

**Community:**
- Open-source contributions and documentation for tinkerers

### Explicitly Out of Scope

- **Mobile platforms** -- not a consideration at this time
- **Browser extensions/add-on system** -- no plugin/extension architecture planned

### Risk Mitigation Strategy

**Technical Risks:**

| Risk | Severity | Mitigation |
|---|---|---|
| JS engine full compliance is massive surface area | High | Custom engine is the goal, not negotiable. A reference engine (V8/SpiderMonkey) may be used as a *comparison/testing* tool, but only if integration is trivial. Effort goes to implementation, not integration. |
| CSS 2.1 long tail (margin collapsing, stacking contexts) | Medium | Checklist-driven approach prevents scope ambiguity. Each item has a spec section to reference. WPT tests validate correctness. |
| HTML5 parser complexity (adoption agency, foster parenting) | Medium | Spec is well-defined and algorithmic. Can be implemented incrementally with WPT tests as validation. |
| Real-site compatibility despite spec compliance | Medium | Maintain investigation pipeline. Spec compliance resolves the long tail, but real-site testing catches practical gaps. |

**Resource Risks:**

| Risk | Severity | Mitigation |
|---|---|---|
| Single-person bottleneck | Medium | LLM-directed development scales well for implementation. Zach's attention is the constraint -- checklist-driven workflow keeps progress systematic even across interruptions. |
| LLM capability limitations | Low | Current LLM capabilities have proven sufficient through 6 milestones. As models improve, development velocity should increase. |

**No market risks** -- this is a personal-use open-source project, not a product seeking market fit.

## User Journeys

### Journey 1: Zach — The Architect's Development Loop

Zach identifies the next unchecked CSS 2.1 item, directs an LLM to implement it with spec citations, adds a golden test, and runs CI. Green. He loads CNN again -- the sidebar snaps into place. He checks off the checklist item, updates the investigation report, and moves to the next unchecked line. When he hits a cluster of Test262 failures, he tackles them as a batch -- implement the missing JS feature, promote passing tests, watch conformance numbers tick up. Every session ends with CI green and a measurable step closer to full compliance.

**Capabilities required:** FR1-FR10 (rendering), FR11-FR17 (JS), FR47-FR50 (conformance), NFR12-NFR14 (CI/regression)

### Journey 2: Zach — The Daily Driver

Zach opens rust_browser, navigates to Hacker News, clicks through articles, opens a new tab for Gmail, logs in (cookies persist), reads and replies to email, opens YouTube for a conference talk. An hour later he realizes he hasn't switched to Firefox once. When something breaks -- a CSS Grid pattern or unimplemented JS built-in -- he notes it in investigations and keeps browsing. Breaks are rare, not routine.

**Capabilities required:** FR18-FR25 (navigation/networking), FR26-FR30 (forms), FR31-FR36 (browser shell), FR21-FR23 (cookies/sessions), FR32 (tabs, Phase 3), FR37 (tracker blocking, Phase 3), FR40 (session persistence, Phase 3), NFR1-NFR5 (performance)

### Journey 3: The Rust Tinkerer — Learning Browser Internals

Maya, a mid-level Rust developer, clones the repo and traces a `<div>` from HTML parse through DOM, style, layout, display list, to pixels. The 4-layer architecture makes sense immediately. She finds an unchecked CSS 2.1 item, reads the spec section, prototypes an implementation with a golden test, and CI passes.

**Capabilities required:** FR1-FR4 (rendering pipeline clarity), NFR16-NFR21 (maintainability/comprehensibility)

### Journey 4: The AI-Dev Enthusiast — Evaluating the Methodology

James, a tech lead, browses the GitHub repo. Clean commit history, comprehensive test suites, spec citations in comments, clear architecture docs. He bookmarks the project as evidence that one person directing LLMs can produce complex, well-tested systems software.

**Capabilities required:** NFR12-NFR14 (CI/testing visibility), NFR16-NFR21 (maintainability)

### Journey-to-Requirement Traceability

| Journey | Phase | FRs | NFRs |
|---|---|---|---|
| Architect's Loop | 1 (MVP), 2 (Spec Compliance) | FR1-FR17, FR47-FR50 | NFR12-NFR14 |
| Daily Driver | 3 (Daily Driver) | FR18-FR36, FR37*, FR40*, FR42* | NFR1-NFR5, NFR11, NFR15 |
| Rust Tinkerer | All phases | FR1-FR4 | NFR16-NFR21 |
| AI-Dev Enthusiast | All phases | (none directly) | NFR12-NFR14, NFR16-NFR21 |

*Phase 3 requirements — see phase tagging in FR section below.

## Desktop Application Requirements

### Platform Support

| Platform | Status | Priority |
|---|---|---|
| **macOS** | Primary development and testing platform | Current |
| **Linux** | Supported via cross-platform stack (winit + softbuffer) | Current |
| **Windows** | Potential future target | Deferred |

Cross-platform support is achieved through Rust's platform-agnostic crate design. Platform-specific code is isolated to `crates/platform/` and `crates/graphics/` (the only crates allowed to use `unsafe`). No platform-specific build steps or conditional compilation outside these two crates.

### Distribution & Updates

**Current (Phases 1-2):** Source-only distribution. Built via `cargo build -p app_browser`, updated via `git pull`. No installer, no auto-update.

**Future (Phase 3):** Evaluate platform-native distribution:
- macOS: Homebrew formula or `.app` bundle via `cargo-bundle`
- Linux: AppImage or Flatpak
- Auto-update: deferred until adoption warrants it

The update strategy transitions from source-only to packaged distribution when the project reaches daily-driver stability.

### Offline Capabilities

- **Local file rendering** -- already supported (`file://` protocol).
- **Service Workers** -- future feature enabling offline-capable web apps, cached page access, and background sync (Phase 3).
- **HTTP caching** -- Milestone 7 deliverable. Reduces network dependency and improves perceived performance for revisited sites.

### Implementation Considerations

- All OS integration additions must go through `crates/platform/` to maintain the layering contract.
- System font discovery should be abstracted behind the existing `FontProvider` trait in `crates/fonts/`.
- Clipboard and file dialog integration should use cross-platform Rust crates (e.g., `arboard` for clipboard, `rfd` for file dialogs) to maintain macOS + Linux support without platform-specific code in engine crates.
- New system integrations require rationale for any new dependencies per project policy.

## Functional Requirements

Phase tags: **[P1]** = Phase 1 (MVP/Milestone 7), **[P2]** = Phase 2 (Spec Compliance), **[P3]** = Phase 3 (Daily Driver). Requirements without a tag are already implemented and maintained across all phases.

### Web Content Rendering

- FR1: The browser parses HTML documents and constructs a DOM tree from arbitrary web content. Acceptance: all WPT tree-construction tests pass.
- FR2: The browser parses CSS stylesheets (inline, embedded, and external) and computes styles for all DOM nodes. Acceptance: computed style output matches WPT expectations for supported properties.
- FR3: The browser performs layout computation for block, inline, flexbox, table, and positioned elements. Acceptance: golden test output matches expected layout trees for each layout mode.
- FR4: The browser generates a display list from the layout tree and rasterizes it to pixels. Acceptance: golden test pixel output matches expected display list dumps.
- FR5a: The browser selects the correct font based on CSS font-family, font-weight, and font-style declarations. Acceptance: golden tests with multiple font stacks render the expected glyphs.
- FR5b: The browser performs line breaking per UAX#14 and renders text with correct line-height, font-size, and baseline alignment. Acceptance: golden tests with multi-line text match expected output.
- FR6: The browser renders images in PNG, JPEG, GIF, WebP, and SVG formats as both inline content and CSS background-image. Acceptance: golden tests with each format produce correct visual output.
- FR7a: The browser renders CSS backgrounds (color, image, repeat, position, attachment) and borders (all border-style values including double, groove, ridge, inset, outset). Acceptance: WPT background/border tests pass.
- FR7b: The browser renders box-shadow, CSS gradients (linear-gradient, radial-gradient), and opacity. Acceptance: golden tests for each effect match expected output.
- FR8: **[P2]** The browser renders CSS generated content (`::before`, `::after`) with `content` property values including strings, `attr()`, and `counter()`. Acceptance: WPT generated-content tests pass.
- FR9: The browser performs CSS selector matching with full specificity calculation and cascade resolution per CSS 2.1 sections 6 and 6.4. Acceptance: WPT cascade/specificity tests pass.
- FR10: **[P2]** The browser resolves CSS inheritance, initial values, and `inherit`/`initial`/`unset` keywords for all CSS 2.1 properties. Acceptance: WPT inheritance tests pass for each supported property.

### JavaScript Execution

- FR11: The browser parses and executes JavaScript programs. Acceptance: Test262 pass rate reaches 95%+ against the full tc39/test262 suite (50,000+ tests).
- FR12: The browser executes scripts from inline `<script>` elements and external script resources, including deferred and asynchronous loading. Acceptance: WPT script-loading tests pass for each loading mode.
- FR13: The browser exposes DOM manipulation APIs to JavaScript: getElementById, querySelector, querySelectorAll, createElement, appendChild, removeChild, insertBefore, replaceChild, classList, and style property access. Acceptance: WPT DOM manipulation tests pass for each listed API.
- FR14: The browser dispatches events to JavaScript listeners with capture, target, and bubble phases per the DOM Events specification. Acceptance: WPT event dispatch tests pass including stopPropagation and preventDefault.
- FR15: The browser executes microtasks (Promise.then), macrotasks (setTimeout, setInterval), and requestAnimationFrame callbacks in spec-defined order. Acceptance: event loop ordering tests produce correct execution sequences.
- FR16: The browser exposes these Web APIs to JavaScript: console (log/warn/error), JSON (parse/stringify), fetch, localStorage, sessionStorage, and all DOM/event APIs listed in FR13-FR14. Acceptance: each API has at least one integration test verifying correct behavior.
- FR17: The browser catches JavaScript runtime errors (TypeError, ReferenceError, SyntaxError) without crashing and reports them to `console.error`. Acceptance: a test script with each error type runs without process termination and produces console output.

### Navigation & Networking

- FR18: The user enters a URL in the address bar and the browser navigates to it. Acceptance: URL entry triggers resource fetch and page render within the performance bounds defined in NFR1.
- FR19: The browser loads resources over HTTP, HTTPS, file://, and data: URI schemes. Acceptance: integration tests verify successful resource loading for each scheme.
- FR20a: The browser follows HTTP 301, 302, 303, 307, and 308 redirects up to a maximum of 20 hops. Acceptance: redirect chain tests verify correct final destination and hop limit enforcement.
- FR20b: The browser displays HTTP error responses (4xx, 5xx) to the user with the status code and a descriptive message. Acceptance: error page tests verify status code display for 404 and 500 responses.
- FR21: **[P1 -- done]** The browser manages cookies per RFC 6265: domain scoping, path matching, Secure/HttpOnly flags, and Max-Age/Expires expiry. Acceptance: cookie integration tests verify correct set/send behavior for each attribute.
- FR22: **[P1 -- done]** The browser caches HTTP responses using ETag and Last-Modified headers, sends conditional requests (If-None-Match, If-Modified-Since), and honors Cache-Control directives (max-age, no-cache, no-store). Acceptance: caching integration tests verify 304 responses and cache hit/miss behavior.
- FR23: **[P1 -- done]** The browser maintains cookie-based session state across navigations within a browsing session: cookies set on page A are sent with requests to the same domain on page B. Acceptance: a multi-navigation test verifies session cookie persistence across 3+ page loads.
- FR24: The user navigates forward and backward through browsing history. Acceptance: history navigation tests verify correct page restoration for 3+ history entries.
- FR25: The browser resolves relative URLs against the document base URL (including `<base href>` if present). Acceptance: URL resolution tests cover relative paths, query strings, fragments, and base element override.

### Forms & User Input

- FR26: The user interacts with form controls: text inputs, buttons, checkboxes, radio buttons, select menus, and textareas. Acceptance: integration tests verify user input produces correct form control state for each control type.
- FR27: The browser submits forms via GET and POST with application/x-www-form-urlencoded encoding. **[P2]** multipart/form-data encoding for file uploads. Acceptance: form submission tests verify correct request body encoding for each method and encoding type.
- FR28: **[P2]** The browser performs client-side form validation for required, pattern, min, max, minlength, maxlength, and type-based constraints (email, url, number). Acceptance: validation tests verify correct constraint enforcement and user-visible error indication for each constraint type.
- FR29: The user interacts with the page via click, keyboard input, and scroll. Acceptance: input event tests verify correct event dispatch and default behavior for each input type.
- FR30: The browser manages focus state and supports keyboard navigation (Tab/Shift+Tab) between focusable elements in document order. Acceptance: focus management tests verify correct tab order across form controls, links, and elements with tabindex.

### Browser Shell & UI

- FR31: The user views and edits the current URL in an address bar that updates on navigation. Acceptance: address bar reflects the current page URL after each navigation.
- FR32: **[P3]** The user opens new tabs, switches between tabs, and closes tabs. Each tab maintains independent navigation history, DOM state, and scroll position. Acceptance: multi-tab tests verify independent state across 3+ tabs.
- FR33: The user scrolls page content vertically and horizontally when content exceeds the viewport. Acceptance: scroll tests verify content accessibility for pages taller and wider than the viewport.
- FR34: The browser displays a loading indicator during page load and clears it on completion or failure. Acceptance: loading state tests verify indicator visibility during fetch and removal after load/error events.
- FR35: The user reloads the current page (re-fetches all resources) and stops a loading navigation (cancels pending fetches). Acceptance: reload/stop tests verify correct behavior for each action.
- FR36: The browser renders a chrome UI containing the address bar, navigation buttons (back/forward/reload/stop), and a tab bar (Phase 3). Acceptance: chrome UI renders correctly at window widths from 800px to 2560px.

### Content Security & Privacy

- FR37: **[P3]** The browser blocks tracker and advertisement requests by matching URLs against a bundled blocklist (e.g., EasyList format). Acceptance: blocking tests verify that requests matching 10+ known tracker patterns are prevented, and non-matching requests proceed normally.
- FR38: The browser enforces same-origin policy: JavaScript on origin A cannot read DOM content, cookies, or network responses from origin B (where A and B differ in scheme, host, or port). Acceptance: cross-origin access tests verify blocked read access for each resource type.
- FR39: The browser blocks top-level navigation to `javascript:` URIs and `data:` URIs. Sub-resource loading of `data:` URIs is permitted. Acceptance: navigation blocking tests verify blocked and permitted cases.

### Offline & Storage

- FR40: **[P3]** The browser persists cookies and session data to disk and restores them on application restart. Acceptance: restart persistence tests verify cookie availability after process termination and relaunch.
- FR41: **[P1 -- done]** The browser serves previously cached HTTP responses when the origin server is unreachable, subject to Cache-Control freshness rules. Acceptance: offline tests verify cached page display when network requests fail.
- FR42: **[P2]** The browser provides localStorage (persistent, 5MB per origin) and sessionStorage (per-tab, cleared on tab close) to JavaScript. Acceptance: Web Storage tests verify getItem/setItem/removeItem/clear behavior, storage limits, and cross-origin isolation.

### System Integration

- FR43: **[P3]** The browser discovers and uses OS-installed fonts on macOS (Core Text) and Linux (fontconfig), falling back to bundled Noto Sans. Acceptance: font discovery tests verify at least 3 system fonts are available beyond the bundled set on each supported platform.
- FR44: **[P3]** The user copies selected text to the system clipboard and pastes text from the clipboard into form inputs. Acceptance: clipboard tests verify round-trip copy/paste of plain text content.
- FR45: **[P3]** The browser presents native file dialogs for file upload (`<input type="file">`) and download (Content-Disposition: attachment). Acceptance: file dialog tests verify dialog presentation and correct file data transfer.
- FR46: **[P3]** The browser registers as the default URL handler on macOS and Linux so that clicking links in other applications opens rust_browser. Acceptance: URL handler registration tests verify correct launch from an external link on each platform.

### Conformance & Testing

- FR47: **[P2]** The browser passes 90%+ of CSS 2.1 Web Platform Tests as measured by the WPT harness in CI.
- FR48: **[P2]** The browser passes 95%+ of the full tc39/test262 ECMAScript conformance suite (50,000+ tests) as measured by the Test262 harness.
- FR49: **[P2]** The browser passes 90%+ of HTML5 Web Platform Tests as measured by the WPT harness in CI.
- FR50: The browser handles malformed HTML, CSS, and JavaScript input without crashing. Acceptance: fuzz tests and malformed-input test suites covering each parser run without panics.

## Non-Functional Requirements

### Performance

- NFR1: Page load and first paint for a content-heavy site (CNN, Hacker News) completes within 3 seconds on an M1 MacBook or equivalent. Measured by timing from navigation start to first paint event in debug logs.
- NFR2: Scrolling maintains 30+ frames per second on pages with up to 500 DOM elements. Measured by frame timing instrumentation in the render loop.
- NFR3: No single JavaScript task blocks the rendering thread for more than 100ms. Measured by task duration logging in the event loop.
- NFR4: The browser starts up and displays the address bar ready for URL input within 2 seconds from process launch. Measured by startup timing instrumentation.
- NFR5: Resident memory usage does not grow by more than 50MB after navigating to 20 different pages and returning to the first. Measured by RSS sampling before and after the navigation sequence.

### Security

- NFR6: All parsers (HTML, CSS, JavaScript) handle malformed and adversarial input without panics or undefined behavior. Verified by fuzz test suites covering each parser with 10,000+ random inputs without crashes.
- NFR7: The `unsafe` keyword is forbidden in all crates except the two designated platform-integration crates. Verified by an automated CI check that scans source files and fails the build on violations.
- NFR8: JavaScript on origin A cannot read DOM content, cookies, or fetch responses from origin B (different scheme, host, or port). Verified by cross-origin integration tests covering each resource type.
- NFR9: Top-level navigation to `javascript:` and `data:` URIs is blocked; sub-resource `data:` URIs are permitted. Verified by navigation tests for each URI scheme.
- NFR10: The browser binary contains zero telemetry, analytics, or tracking code. Verified by code audit: no outbound network requests are made except those explicitly initiated by page content or user navigation.

### Reliability & Stability

- NFR11: The browser does not crash on any valid or malformed web content. Parser, layout, and render failures produce user-visible error messages instead of panics. Verified by running the full WPT and Test262 suites plus malformed-input tests without process termination.
- NFR12: The CI gate passes on every merged change, covering formatting, linting, all test suites, safety policy, and metrics. Verified by CI pass/fail status on every merge.
- NFR13: Every bug fix includes at least one regression test that reproduces the bug and verifies the fix. Verified by code review policy.
- NFR14: Conformance test suites (golden tests, WPT, Test262) run on every CI build. Any test that previously passed and now fails blocks the merge. Verified by CI harness exit codes.
- NFR15: The browser displays a user-visible error page (not a blank screen or hang) within 10 seconds of a network failure (timeout, DNS error, connection refused). Verified by network failure integration tests with simulated failures.

### Maintainability

- NFR16: No crate in a lower architectural layer depends on a crate in a higher layer. Verified by an automated dependency check in CI that parses Cargo.toml files and fails on violations.
- NFR17: Each crate has a single documented responsibility. No crate's public API surface exceeds 50 exported items. Verified by periodic API surface audit.
- NFR18: No source file exceeds 1,000 lines. Verified by an automated file-size check in CI.
- NFR19: New external dependencies require documented rationale and workspace-level version pinning. Verified by code review policy.
- NFR20: Implementation of non-obvious spec behavior includes a comment citing the relevant spec section (e.g., CSS 2.1 section 8.3.1). Verified by code review policy.
- NFR21: The total crate count does not exceed 30 and total source file count does not exceed 500. Verified by periodic metrics collection in CI.