dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r44.md
# Region r44: block layout geometry — what other regions need to know
Region r44 ports `Layout/AvailableSpace`, `Layout/LayoutState`, `Layout/FormattingContext` (with the
`ReplacedFormattingContext` and `DummyFormattingContext` hacks), `Layout/BlockFormattingContext` and
`Layout/ReplacedWithChildrenFormattingContext`. The stub fragment `stubs/stub_r44_layout_formatting.lucb` is gone
(its last entry, `BlockFormattingContext::measure_scrollable_overflow`, is only declared in C++). A styled
layout tree can now be laid out by the root `BlockFormattingContext` into a `LayoutState`: widths, heights,
margins and their collapsing, padding and borders, floats and clearance, relative/absolute/fixed positioning,
min/max sizes, auto margins, percentages, calc, intrinsic (min-/max-/fit-content) sizes, the quirks, list item
markers, fieldsets with legends, replaced boxes and anchor() insets.
## Fragments
| Fragment | Donor |
| --- | --- |
| `layout/available_space` | `AvailableSpace.cpp` 1-59 and `AvailableSpace.h` |
| `layout/layout_state_1` | `LayoutState.h`'s inline members: StaticPositionRect, PagedStore, UsedValues' accessors, rare data, collapsed borders, `clamp_to_max_dimension_value`; plus `layout_div_int` / `layout_zero_px` |
| `layout/layout_state_2` | `LayoutState.cpp` 1-360: construction, lookups, scrollable overflow, relative positions of fragments, `build_paint_tree` |
| `layout/layout_state_3` | `LayoutState.cpp` 362-949: `commit`, `UsedValues::operator=` (`layout_state_used_values_assign`), `set_node`, the content size setters, the available inner space |
| `layout/formatting_context_1` | `FormattingContext.cpp` 1-42, 200-542 and `FormattingContext.h`: construction/destruction, independent contexts, `layout_inside`, shrink-to-fit, replaced size constraints, automatic heights, table wrappers |
| `layout/formatting_context_2` | 544-990: replaced sizes, abspos widths (`LayoutAbsposWidthSolver` holds the lambdas' state) |
| `layout/formatting_context_3` | 992-1384: abspos non-replaced heights (`LayoutAbsposHeightSolver`), inline containing block rectangles, `resolve_abspos_containing_block_info` |
| `layout/formatting_context_4` | 1386-1870: anchor insets, laying out abspos boxes, abspos replaced heights, `compute_inset` |
| `layout/formatting_context_5` | 1872-2330: fit-content and intrinsic sizes, inner sizes, stretch-fit, `should_treat_width/height_as_auto` |
| `layout/formatting_context_6` | 2332-2597: rectangles, baselines, `box_is_sized_as_replaced_element`, max sizes as none, `gap_to_px` |
| `layout/block_formatting_context_1` | `BlockFormattingContext.h` and `.cpp` 1-183: BlockMarginState, FloatSideData, construction, destructor, `run` |
| `layout/block_formatting_context_2` | 185-644: widths (`LayoutBlockWidthSolver`), float and replaced widths, used heights, inline children |
| `layout/block_formatting_context_3` | 646-1027: automatic heights, the quirks percentage height, `layout_block_level_box`, `layout_block_level_children` |
| `layout/block_formatting_context_4` | 1029-1228: fieldsets, box model metrics, clearance, placing boxes |
| `layout/block_formatting_context_5` | 1230-1735: floats (`LayoutFloatPlacement`), list item markers, float intrusion, `greatest_child_width`, multicol |
| `layout/replaced_with_children_formatting_context` | `ReplacedWithChildrenFormattingContext.cpp` |
| `layout/tests_layout_state`, `tests_layout_geometry_cases`, `tests_layout_geometry` | tests (below) |
## What other regions must know
### Formatting contexts are not cells
C++ owns formatting contexts through `OwnPtr` (`make<T>(...)`); here they live in managed memory:
`layout_make_formatting_context_storage[T]()` answers zeroed storage (what default-constructing the members
gives), then the constructor runs. Every constructor must call `layout_formatting_context_construct` and then
`layout_formatting_context_set_class(this, &its_class)` (the vptr). `layout_make_block_formatting_context` makes
a BFC. **Destructors**: `~BlockFormattingContext` lays out absolutely positioned children its parent never asked
for, so wherever C++ destroys an owning pointer to a formatting context, run
`defer layout_formatting_context_destruct(context)` (a no-op for every other type and for none). Regions r45–r49
(IFC, FFC, GFC, TFC, SVG FC) must do the same for the contexts they own (e.g. FFC/GFC's child contexts, the IFC's).
### Signatures changed from the stubs
- `layout_state_get` answers `const LayoutStateUsedValues*` (it was a copy); `layout_state_populate_node_from`
takes `source: const LayoutState*`; `dom/document_3` (Document::update_layout, SVG relayout) was adapted.
- Values passed by `const&` in C++ are pointers: `layout_block_formatting_context_intrusion_by_floats_into_box_layout_state_used_values`,
`layout_formatting_context_content_box_rect_layout_state_used_values`, `..._content_box_rect_in_ancestor_coordinate_space`,
`..._margin_box_rect_in_ancestor_coordinate_space_layout_state_used_values` take `const LayoutStateUsedValues*`;
`layout_formatting_context_line_box_physical_width` takes `const LayoutLineBox*`. Region r46's stubs still take
`LayoutStateUsedValues` by value (`has_definite_main_size_layout_state_used_values` and friends): change them to
`const LayoutStateUsedValues*` when porting.
- `layout_block_formatting_context_left_side_floats` / `right_side_floats` answer `const ...FloatSideData*` (r45's
LineBuilder uses them).
- `layout_state_used_values_floating_descendants` answers `const ak.HashTable[LayoutBox*, ak.PtrTraits[LayoutBox]]*`.
- PagedStore's members are written for `LayoutPagedStore[LayoutStateUsedValues]` (a generic body cannot make `T {}`);
`layout_paged_store_for_each(&store)` and `layout_block_formatting_context_for_each_floating_box(context)` are
iterables (`for used_values in ...`, DESIGN §2.9).
- Internal-linkage functions are private: `layout_margins_collapse_through`, `layout_margin_box_rect`,
`layout_compute_inline_containing_block_rect`, `layout_measure_scrollable_overflow`, `layout_build_paint_tree`,
`layout_containing_block_height_to_resolve_percentage_in_quirks_mode`, `layout_inline_axis_is_horizontal`,
`layout_physical_overflow_directions`.
### Types filled by hand
`types_layout_state` (UsedValues, RareData — `Optional<Gfx::Path>` is a path plus `has_computed_svg_path`, since
`computed_svg_path()` answers its address —, `LayoutPage[T]` as entries plus presence flags),
`types_formatting_context` (SpaceUsedByFloats, SpaceUsedAndContainingMarginForFloats, ShrinkToFitResult),
`types_block_formatting_context` (FloatingBox). `BlockFormattingContext::FloatSide` is a private enum in
`block_formatting_context_5` (namemap row added, with `UsedValues::operator=` and `~FormattingContext`).
### Where paths stop (other regions' stubs)
- Inline content: a block container whose children are inline runs an InlineFormattingContext (r45) and traps;
`clear_floating_boxes` with an IFC, floats placed by a LineBuilder and line boxes too.
- `display: flex | grid | table`, `<svg>`: the FFC (r46), GFC (r47), TFC (r48), SVG FC (r49) constructors trap.
- `LayoutState::commit` creates paintables (r50: `create_paintable`, `PaintableBox` setters, `absolute_rect`),
so `Document::update_layout` stops there; so do `measure_scrollable_overflow`, `resolve_relative_positions`,
`build_paint_tree` and `populate_from_paintable`. They are ported and untested.
## Deviations and notes
- C++ lambdas that capture by reference and mutate (`try_compute_width`, `try_compute_height`, `float_box`,
`walk`, `resolve_anchor_*`) are capture structs with functions (DESIGN §2.7); `TemporaryChange` is a saved value
plus `defer`; the margin state's y-position callback is an `ak.Function1` over a capture struct in the frame of
`layout_block_level_box` (it is unregistered before that frame ends).
- `CSSPixels / int` is a CSSPixelFraction read back as CSSPixels (`layout_div_int`), as the C++ conversion does.
- HandOff (luce-js HANDOFF.md §5 item 4) follow-ups: all were already done by earlier regions (CSS/Serialize
stubs, `invalid_rule_location_reporter`, `TokenStreamToken` constraints, custom property name stubs,
`html_tokenizer_set_parser`, `scrollbar_color()` forwarded to display_list, FontDatabase in the C heap).
## Tests
- `layout/tests_layout_geometry_cases` (74 cases) + `layout/tests_layout_geometry`: a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/layout_geometry`: `oracle.cpp` links the reference build's
LibWeb, builds each document as r43's layout_tree oracle does, propagates overflow to the viewport, runs
Document::update_layout's layout steps and the commit, and prints `dump_tree`; `cases.txt`, `build.sh`,
`gen_luce_cases.py`, `from_ladybird.py`, `compare_ladybird.py`). The first 19 cases are Ladybird's
`Tests/LibWeb/Layout/input/block-and-inline` tests whose layout tree has no text (their `<style>` becomes the
author sheet); the oracle reproduces their expected layout dumps exactly (`compare_ladybird.py`). The other 55
are written for this region: box model, margin collapsing (siblings, parent/child, empty boxes, negative,
BFC roots, borders), auto margins, min/max sizes, box-sizing, percentages, calc, min/max/fit-content,
`<center>` and `align`, floats (stacking, wrapping, clearance, shrink-to-fit, BFC roots avoiding floats, nested
containing blocks), relative/absolute/fixed/sticky positioning, abspos auto sizes and percentages, quirks mode
(html/body fill, percentage heights), viewport overflow, multicol, containment, list item markers, fieldsets,
replaced images, anchor() insets. The harness lays out with the port, collects garbage, and dumps with Dump's
`dump_tree` on the unpainted tree, putting in each box the position and box model commit would give its
PaintableBox. All match.
- `layout/tests_layout_state`: AvailableSize/AvailableSpace strings and comparisons, css_clamp,
clamp_to_max_dimension_value, StaticPositionRect alignment, PagedStore, UsedValues edges with collapsed
borders, content size setters, the available inner space and copy assignment.