Documentation

How Project AB is put together

An overview of the workspace, the path a page takes from URL to pixels, and the tools for screenshots and diagnostics. The design document in the repository is docs/ARCHITECTURE.md.

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

Workspace crates and their responsibilities
CrateResponsibility
ab-appThe 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-urlURL 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-netNetworking: 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-htmlHTML tokenizer and tree builder with error recovery, the arena DOM (Document, NodeId), traversal helpers and serialisation.
ab-cssCSS tokenizer and parser, selectors and specificity, values, colours, units and at-rules such as @media, @import and @supports.
ab-styleThe style engine: selector matching, rule index, cascade, inheritance, user-agent stylesheet, presentational hints, custom properties, math functions and computed values for every element.
ab-layoutBox 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-renderDisplay 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-scriptThe 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-storagePersistent 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:

Supporting crates
CrateResponsibility
ab-compressDEFLATE, zlib and gzip decoders with checksum verification, used for Content-Encoding and PNG.
ab-imageImage 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
Arrows point from a crate to the crates it depends on. 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

  1. Input. The address bar text goes through the URL heuristics in ab-url; anything that is not a URL becomes a search.
  2. 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.
  3. Parse. ab-html builds the DOM. Linked stylesheets and one level of @import are fetched, and <base href> is honoured.
  4. Style. ab-style matches the user-agent, author and inline styles against the DOM and computes a style for every element.
  5. Script. Classic scripts run in document order in ab-script; DOM changes trigger a new layout.
  6. Layout. ab-layout builds the box tree and positions every box for the current viewport width.
  7. Paint. ab-render turns the layout tree into a display list and draws it, together with the browser chrome, through wgpu. Images are fetched in parallel after the first paint.

Rendering design

The renderer converts a display list into textured quads:

  1. DisplayList: ordered paint operations in CSS pixels.
  2. mesh::tessellate: a CPU step producing vertices in physical pixels and scissor batches. It is unit tested without a GPU.
  3. gpu::Painter: one wgpu pipeline 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]
Headless mode options
OptionMeaning
--screenshot FILERender offscreen and save a PNG to FILE. Without this option a window opens.
--follow TEXTAfter loading, click the link with this text and capture the page it leads to.
--scroll PXScroll the page down by PX pixels before capturing.
--size WxHWindow 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=1 to 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.