The shell

The shell

The browser around the engine. It is one OS-free component — tabs, history, the address bar, hit-testing, scrolling, forms, selection, find, reader mode, link hints and devtools — painted through the theme's tokens (Themes) and driven either by a window or by a script (Scripting the shell). The Win32 window blits the shell's frame and feeds it input; the same shell runs headless in CI on all three OSes.

Browsing

• Tabs — open, close, switch; each keeps its own document, scroll position, controls, selection and find state.
• History — Back and Forward keep each page's bytes, so going back never refetches.
• The address bar — a caret, selection, Ctrl+A/C/V; a typed host is tried over https first (see Networking); a typed non-URL opens an internal page, never a search engine.
• Links — hit-tested through the element pointers on text runs and picture boxes; fragment links scroll to their target.
• Internal pages — about:sashfold, the error page, the certificate-error page (no override), a plain-text page for text types, an unsupported-content page for the rest, and view-source:.
• The new-tab page — about:newtab, where a new tab opens with the address bar empty and focused: a clock, a greeting by the hour and the date, over a gradient of the theme's colors or over the theme's own pictures. A theme names a folder beside itself (new-tab.backgrounds, see Themes); each new tab opens on the next picture in name order, and the page fades to the next one every new-tab.rotate milliseconds. The clock ticks on the page's own timers from the minute it opened. Nothing on it touches the network.
• A page's icon — the last <link rel=icon>, else /favicon.ico, fetched through the page's own loader, decoded (ICO, PNG, GIF, JPEG or BMP) and drawn in the tab before the title.
• Scrolling — the wheel, Page Up/Down, Home/End, the arrow keys, for the page and for any box that scrolls (see below).

Boxes that scroll

A box whose overflow is auto, scroll or hidden holds a scrollport its content can be moved within. Layout settles how far each can be moved — the scrollable overflow region past the scrollport's end edges, the end padding included, the walk stopping at a box that scrolls because that box holds its own content — and the shell moves what is inside it.

A wheel notch goes to the innermost box under the pointer that has room to take it; a box with none passes it outward, to the box around it and finally to the page, which is the chaining every browser does. A box that can only move across takes a plain wheel that way, which is what a wide table in a narrow column needs. The keyboard follows whatever the reader last moved by hand. hidden clips and holds a scrollport, but gives a reader no way in at all.

auto shows a scrollbar once there is something out of sight, scroll shows one whether or not there is. The bar is drawn inside the scrollport over the content rather than taking room from it, its thumb as long a part of the track as the scrollport is of the whole content; the thumb can be dragged, and a click on the track beside it moves a scrollport at a time, towards the pointer. A render taken with no shell behind it — --render, and the reference tests — draws no bar at all: nothing has been scrolled there and nothing can be.

Scrolling is applied to the fragments rather than at painting time, so painting, hit-testing, the selection, find-in-page and the devtools overlay all read the coordinates the content is actually drawn at. A link scrolled out of sight is out of reach with it.

Find in page and a fragment link reach into a box: every box between the target and the root is moved until the target is inside each of their scrollports, outermost first — an inner box travels with the outer one, so its own numbers are only settled once the outer one has stopped — and then the page, as before. A target too big for a scrollport is shown from its start edge rather than its end.

What is left: layout reserves no room for a bar, so the bars sit over the content the way an overlay scrollbar does rather than narrowing the scrollport, and a box that sticks does not re-stick as a scrollport is moved.

Forms, without scripts

Text and password fields, textareas, checkboxes, radio buttons (grouped by name within a form), selects and buttons are drawn, take focus (a click, Tab and Shift+Tab, a label by for or containment), and edit: typing with a caret, Backspace/Delete/Left/Right/Home/End, Space to toggle, Up/Down to pick an option, Enter to submit (a newline in a textarea), Escape to blur. A GET form submits to its action with its data set urlencoded as the query, per the standard's form data set rules (disabled controls, unchecked boxes and non-submitter buttons left out); a form that posts says so in the status bar instead. Author backgrounds and borders replace the built-in look.

Selection and the clipboard

A press on page text sets a caret, a drag extends the selection (held to the content area's edges), Shift with the arrow keys steps by character or by line, Shift+Home/End to the line's ends, Ctrl+A takes everything, Escape drops it. Ctrl+C copies the selected text (or the address bar's) to the operating system's clipboard through CF_UNICODETEXT; Ctrl+V pastes into a field or the address bar. Scripted runs use a clipboard private to the process.

Find in page

Ctrl+F opens a find bar under the toolbar. The count updates as you type ("3 of 12", "No matches"), every match is highlighted with the current one stronger, Enter and Shift+Enter walk them and scroll each into view, Escape closes.

Reader mode

The pilcrow button at the right of the address bar (or the reader: scheme) shows a page's article alone: the container of its paragraphs, found by scoring text length, commas, link density and the names of classes and ids, with the site's heading, the source, absolute links and pictures, and none of the navigation, sidebars or comments. Pressing it again returns to the page.

Keyboard link hints

Pressing f with nothing focused puts a home-row label (asdfghjkl, one letter for up to nine links, two for up to eighty-one) on every link in view. Typing a label follows its link; Backspace takes a letter back; Escape puts the labels away.

Devtools

F12 (or Ctrl+Shift+I) opens a panel under the page: the document's tree on the left, and for the inspected element — a click on the page or on a line of the tree — its summary, its box from the layout, and its computed style on the right, with the box overlaid on the page.

Downloads

Saved under a fresh name in the Downloads folder (--downloads <dir> chooses another), marked with the mark of the web, never opened. See Security defaults.

Testing the shell

The shell is tested by scripts under tests/shell/ that run in CI on Linux, Windows and macOS with chrome screenshots compared byte for byte — see Testing and Scripting the shell.