Layout

layout/ is Gecko's CSS layout engine. It takes a styled DOM tree and produces a frame tree of placed boxes that drive painting, hit-testing, and accessibility. With ~19,000 files (counting tests/reftests), it is one of the largest directories in the tree.

Purpose

Implement CSS box layout (block, inline, flex, grid, table, multicol, scroll, sticky, position) plus the CSS Object Model accessors that expose computed values to script.

Directory layout

layout/
├── base/        # PresShell, document state, main entry points
├── generic/     # Frame classes: nsBlockFrame, nsInlineFrame, nsTextFrame, ...
├── tables/      # Table layout
├── forms/       # <input>/<select>/<textarea> frames
├── mathml/      # MathML rendering
├── svg/         # SVG rendering
├── style/       # The C++ side of style; bridges to Stylo
├── painting/    # Display list builder, retained display lists
├── xul/         # Legacy XUL frames (still used for chrome)
├── reftests/    # Reference (pixel-comparison) tests
├── crashtests/  # Crash regression tests
└── tools/       # Reftest runner, layout debugger

Key abstractions

Type	File	Role
mozilla::PresShell	layout/base/PresShell.h	Per-document layout owner
nsIFrame	layout/generic/nsIFrame.h	Base class for every frame
nsBlockFrame, nsLineLayout	layout/generic/nsBlockFrame.h, layout/generic/nsLineLayout.h	Block and inline layout
nsFlexContainerFrame	layout/generic/nsFlexContainerFrame.h	CSS Flexbox
nsGridContainerFrame	layout/generic/nsGridContainerFrame.h	CSS Grid
nsTextFrame	layout/generic/nsTextFrame.h	Inline text runs
nsDisplayListBuilder / nsDisplayList	layout/painting/nsDisplayList.h	Builds the display list for painting
nsCSSFrameConstructor	layout/base/nsCSSFrameConstructor.h	Builds the frame tree from styled DOM
mozilla::ReflowInput	layout/generic/ReflowInput.h	Inputs/outputs of a reflow

Rendering pipeline

graph LR
    DOM[Document + Element tree] --> Style[Stylo: style resolution<br/>servo/components/style]
    Style --> Frames[nsCSSFrameConstructor:<br/>build frame tree]
    Frames --> Reflow[Reflow:<br/>nsBlockFrame::Reflow etc.]
    Reflow --> DL[Display list:<br/>nsDisplayListBuilder]
    DL --> WR[WebRender scene]
    WR --> GPU[Composited pixels]

1. Style — Stylo (Rust, servo/components/style/) resolves CSS into computed values per element.
2. Frame construction — nsCSSFrameConstructor walks the DOM and creates frames, splicing them into the frame tree. Pseudo-elements and anonymous boxes are created here.
3. Reflow — PresShell::DoReflow invokes Reflow on each frame, computing positions and sizes.
4. Display list build — Each frame contributes display items to an nsDisplayList.
5. WebRender hand-off — The display list is converted to WebRender primitives and rendered. See Graphics.

Frame tree vs DOM tree

The frame tree is a parallel structure: most DOM elements have one frame, but some have many (text, lists), and some have none (display: none, abstract anchors). Anonymous frames provide structures the DOM doesn't have (e.g., the line boxes inside a block).

Reflow flavors

Reflows can be:

• Initial — first time a frame is laid out.
• Resize / dirty — driven by intrinsic size changes or descendant dirty bits.
• Reflow root reflow — limited to a subtree.
• Incremental — coalesced via PresShell::FlushPendingNotifications.

PresShell schedules reflows; the actual work flows through nsBlockFrame::Reflow, nsFlexContainerFrame::Reflow, etc.

Common entry points for changes

• Add a new CSS property — declare it in servo/components/style/properties/ (Mako templates), then handle it in the relevant frame's reflow.
• New layout mode — typically a new nsContainerFrame subclass plus a constructor entry in nsCSSFrameConstructor.
• Display list change — modify BuildDisplayList on the owning frame.

Reftests

layout/reftests/ is enormous. A reftest pair is a test page plus a reference page; the harness verifies that both render to the same pixels.

Related

• Style and Stylo
• Graphics and WebRender
• DOM