Overview
Project AB is a Cargo workspace of small crates, one per engine stage. Each crate is independently testable and the dependency graph has no cycles: no crate depends on the application crate ab-app, which wires everything together.
The browser model in ab-app (tabs, history, loading) has no windowing dependency, so navigation, history and the composed display list can be tested end to end without opening a window.
Crates
| Crate | Responsibility |
|---|---|
ab-app | The desktop application: window and event loop (winit), tabs, address bar, back/forward/reload/stop, forms, internal about: pages, keyboard shortcuts and the headless screenshot mode. The browser chrome is painted with Project AB's own renderer. |
ab-url | URL parsing and normalisation: schemes, userinfo, hosts including IPv6 literals, ports, paths, queries and fragments; dot-segment removal, percent-encoding, relative resolution (RFC 3986) and address-bar heuristics. |
ab-net | Networking: DNS through the OS resolver, TCP, HTTPS via native-tls, HTTP/1.1 requests and responses, chunked bodies, redirects, keep-alive pool, cookies, cache, charset decoding and data:/file:/about: URLs. |
ab-html | HTML tokenizer and tree builder with error recovery, the arena DOM (Document, NodeId), traversal helpers and serialisation. |
ab-css | CSS tokenizer and parser, selectors and specificity, values, colours, units and at-rules such as @media, @import and @supports. |
ab-style | The style engine: selector matching, rule index, cascade, inheritance, user-agent stylesheet, presentational hints, custom properties, math functions and computed values for every element. |
ab-layout | Box tree and layout: block and inline formatting, line breaking, tables, floats, positioning, flexbox, grid, document extent and hit testing. Text is measured through a TextMeasurer trait. |
ab-render | Display list generation, the TrueType parser and rasteriser, font discovery and fallback, glyph atlas, tessellation and the wgpu painter, offscreen rendering and the PNG encoder. |
ab-script | The JavaScript engine (in progress): lexer, parser and AST, tree-walking interpreter, standard library, event loop and DOM bindings. Each page gets its own realm; scripts have no network or file access. |
ab-storage | Persistent browser data: global history, bookmarks, downloads list and settings, stored as TSV/INI files in the user data directory. |
Two supporting crates hold code that several stages share:
| Crate | Responsibility |
|---|---|
ab-compress | DEFLATE, zlib and gzip decoders with checksum verification, used for Content-Encoding and PNG. |
ab-image | Image decoders written from scratch (PNG, JPEG, GIF, BMP, WebP) and an SVG renderer. |
Dependency graph
ab-app ──► ab-render ──► ab-layout ──► ab-style ──► ab-css
│ │ └────────► ab-html
│ └──► ab-image ──► ab-compress
├──► ab-script ──► ab-style, ab-html, ab-css, ab-url
├──► ab-net ──► ab-url, ab-compress
└──► ab-storage
ab-app also uses the lower crates directly. ab-url, ab-css, ab-html, ab-compress and ab-storage have no workspace dependencies.Loading a page
- Input. The address bar text goes through the URL heuristics in
ab-url; anything that is not a URL becomes a search. - Fetch. A background loader fetches the document with
ab-net, following redirects, sending cookies and using the cache. Responses are decoded to text using the declared or sniffed charset. - Parse.
ab-htmlbuilds the DOM. Linked stylesheets and one level of@importare fetched, and<base href>is honoured. - Style.
ab-stylematches the user-agent, author and inline styles against the DOM and computes a style for every element. - Script. Classic scripts run in document order in
ab-script; DOM changes trigger a new layout. - Layout.
ab-layoutbuilds the box tree and positions every box for the current viewport width. - Paint.
ab-renderturns the layout tree into a display list and draws it, together with the browser chrome, throughwgpu. Images are fetched in parallel after the first paint.
Rendering design
The renderer converts a display list into textured quads:
DisplayList: ordered paint operations in CSS pixels.mesh::tessellate: a CPU step producing vertices in physical pixels and scissor batches. It is unit tested without a GPU.gpu::Painter: onewgpupipeline in which every quad samples an RGBA atlas. Solid fills sample a reserved opaque white block, so rectangles and glyphs share one draw path.
The surface prefers a non-sRGB format so CSS colours blend in sRGB space, as in other browsers. OffscreenRenderer renders into a texture and reads it back for screenshots and GPU integration tests, which are skipped when no adapter is present.
Headless mode
ab-app can load a page and write a PNG of the whole window, including the browser chrome, without opening a window:
ab-app URL --screenshot out.png [--follow "link text"] [--scroll PX] [--size WxH]
| Option | Meaning |
|---|---|
--screenshot FILE | Render offscreen and save a PNG to FILE. Without this option a window opens. |
--follow TEXT | After loading, click the link with this text and capture the page it leads to. |
--scroll PX | Scroll the page down by PX pixels before capturing. |
--size WxH | Window size in pixels. Default: 1200x800. |
Through Cargo:
cargo run --release -p ab-app -- https://example.com/ --screenshot example.png --size 1280x720
Diagnostics
- Set
AB_TRACE=1to log every fetch (status, size, time) and uncaught script errors to the terminal. - Fetch a URL with the network stack alone and print the response:
cargo run -p ab-net --example fetch -- https://example.com/ - Render a local HTML file through the full pipeline into a PNG:
cargo run -p ab-render --example render_html -- page.html out.png
Testing
Parsers, URL handling, CSS matching, layout maths and response parsing have unit tests in their crates. crates/ab-app/tests/browser_flow.rs runs end-to-end tests against a local HTTP server: loading, link clicks, history, scroll restoration, fragments, reload, stop, tabs, error pages and bookmarks.
cargo test --workspace
Third-party code
The engine uses exactly three crates from outside the repository:
winit: native windows and input events.wgpu: access to the GPU. The renderer on top of it is Project AB's own.native-tls: HTTPS through the operating system's TLS implementation (SChannel on Windows). Cryptography and certificate validation are never implemented by hand.
Browser engines, WebViews and existing HTML, CSS, layout, HTTP or JavaScript libraries are ruled out by the project's rules.