dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r43.md
# Region r43: the layout tree — what other regions need to know
Region r43 ports the layout tree: `Layout/Node` (Node, NodeWithStyle, NodeWithStyleAndBoxModelMetrics),
`Box`, `BlockContainer`, `InlineNode`, `TextNode` (with `ChunkIterator`), `BreakNode`, `Viewport`,
`ReplacedBox`, `ImageBox`, `ImageProvider`, `ListItemBox`, `ListItemMarkerBox`, `FieldSetBox`, `LegendBox`,
`NavigableContainerViewport`, `RadioButton`, `CheckBox`, `TextAreaBox`, `TextInputBox`, `VideoBox`,
`AudioBox`, `CanvasBox` and `TreeBuilder`, plus r43b (`DominantBaseline.h`). The stub fragments
`stubs/stub_r43_layout_tree.lucb` and `stubs/stub_r43b_layout_rest.lucb` are gone.
`TreeBuilder::build` now builds the layout tree of a parsed, styled document.
## Fragments
| Fragment | Donor |
| --- | --- |
| `layout/node_1` | `Node.cpp` 1-578: constructor, visit_edges, containing blocks, stacking contexts, navigable, root |
| `layout/node_2` | `Node.cpp` 579-673: NodeWithStyle's constructors, ImageObserver, rebuild_image_observers, visit_edges |
| `layout/node_3` | `Node.cpp` 675-1070: `NodeWithStyle::apply_style` |
| `layout/node_4` | `Node.cpp` 1072-1290: style_scope, propagation to wrappers, display, create_anonymous_wrapper, scroll containers |
| `layout/node_5` | `Node.cpp` 1292-1619: is_anonymous, dom_node, containment, continuations, set_needs_layout_update |
| `layout/node_6` | `Node.h`'s inline members (flags, paintables, `is_*` defaults, fonts, computed values, parent) |
| `layout/box`, `block_container`, `inline_node`, `break_node`, `viewport`, `replaced_box` | one per `.cpp` + `.h` |
| `layout/image_provider`, `image_box` | `ImageProvider.cpp/.h` (the non-pure members), `ImageBox.cpp/.h` |
| `layout/list_item_box`, `list_item_marker_box`, `field_set_box`, `legend_box` | one per `.cpp` + `.h` |
| `layout/navigable_container_viewport`, `radio_button`, `check_box`, `text_area_box`, `text_input_box`, `video_box`, `audio_box`, `canvas_box` | one per `.cpp` + `.h` |
| `layout/text_node_1` | `TextNode.cpp` 1-424: constructor, MathML italics, text-transform, text for rendering, segmenters |
| `layout/text_node_2` | `TextNode.cpp` 426-800: `ChunkIterator` |
| `layout/tree_builder_1`, `_2`, `_3` | `TreeBuilder.cpp` 1-429, 431-897, 899-1379 (the last with the CSS tables fixup) |
| `layout/dominant_baseline` | `DominantBaseline.h` (r43b) |
| `layout/formatting_context_box_types` | `FormattingContext.cpp` 44-196 + `type_name`, taken ahead of **r44** |
| `layout/table_grid_predicates` | `TableGrid.h` 58-72 (is_table_row_group/row/column_group), taken ahead of **r48** |
| `animations/animatable` | `Animatable.cpp` 15-17, 69-129, 137-301, taken ahead of **phase 4** |
| `html/navigable_taken_ahead` | `Navigable::viewport_rect` and `Navigable::container`, taken ahead of **r28** |
| `html/navigable_container_taken_ahead` | `NavigableContainer::all_instances` and `navigable_container_with_content_navigable`, taken ahead of **r28** |
| `layout/tests_layout_tree_cases`, `tests_layout_tree`, `tests_layout_tree_2` | tests (below) |
Also ported here: `GraphemeEdgeTracker`'s `measure_text_width` (it needed ChunkIterator) and
`Page::preferred_color_scheme` (in `page/page`, taken ahead of r28: the cascade asks it of every document).
## What other regions must know
### Taken ahead (their stubs are gone; port the rest around them)
- **r28**: `html_navigable_viewport_rect`, `html_navigable_container`,
`html_navigable_container_all_instances`, `html_navigable_container_navigable_container_with_content_navigable`
and `page_preferred_color_scheme`. The NavigableContainer registry is a module global in the C heap
(unscanned, weak entries as in C++): NavigableContainer's constructor must add itself and its finalize
must remove itself. r28 is running in parallel; whichever merges second drops its duplicate.
- **r44**: `layout_formatting_context_creates_block_formatting_context`,
`layout_formatting_context_formatting_context_type_created_by_box`, `layout_formatting_context_type_name`
(`formatting_context_box_types.lucb`).
- **r48**: `layout_table_grid_is_table_row_group`, `_is_table_row`, `_is_table_column_group`. The CSS tables
fixup (`TreeBuilder::missing_cells_fixup`) passes capture structs with `mutating func call(row_box: LayoutBox*)`
to r48's `layout_table_grid_for_each_child_box_matching_2`; r48 should constrain its callback parameter
accordingly. `TableWrapper`'s constructor is still r48's, so any `display: table` stops there.
- **Phase 4**: all of `Animatable` except what needs Animation (closure stubs
`animations_animation_is_relevant` and `animations_pseudo_element_parsing` were added to `stub_closure`).
`types_animatable` has the real `Impl` and the new `AnimationsAnimatableTransition`.
### Where paths stop (other regions' stubs)
- `<canvas>` creation registers with `Page::register_canvas_element` (r28); `<button>`'s constructor is r25's;
`display: table` reaches `TableWrapper` (r48). The oracle cases for these are marked `!`.
- `Document::update_layout`, `Document::update_style`'s browsing-context check and the layout of anything
(formatting contexts) are other regions'; the tests run `update_style`'s inner steps by hand.
- `DOM::Node::layout_node()` checks `Document::layout_is_up_to_date`, which needs the navigable's active
document (r28): tests use `dom_node_unsafe_layout_node`.
### Signatures changed from the stubs
- `layout_node_computed_values` / `layout_node_with_style_computed_values` answer
`const CssImmutableComputedValues*`; `first_available_font` and the `font*` accessors `const web_fonts.Font*`
(`css/length` updated); `style_scope` `const CssStyleScope*`; `paintables_const` `const IntrusiveList*`;
`layout_text_node_text_for_rendering` `const ak.Utf16String*`; `contained_abspos_children` `const Vector*`.
- The image observer's `did_update` is `layout_node_with_style_image_observer_image_style_value_did_update_impl(base: CssImageStyleValueClient*, ...)`
(the observer embeds the client).
- `layout_dominant_baseline_offset` / `layout_resolve_dominant_baseline_metric` are module-private (the C++ is
header-only static); `resolve` takes `const CssComputedValues*`.
- `for_each_sequence_of_consecutive_children_matching[TCallback: LayoutConsecutiveChildrenCallback](parent, matcher: func(LayoutNode*) -> bool, callback: TCallback*)`;
`wrap_in_anonymous(wrapper_class: const ak.ClassInfo*, sequence, nearest_sibling, display)` (the template
parameter is the wrapper's class). TreeBuilder's internals are private.
- `calculate_list_item_index` is gone: it is only declared in C++.
- New ChunkIterator functions (`construct_utf16_view`, `should_*`, `peek`, `create_empty_chunk`, ...) and
their namemap rows.
### Types filled by hand
`types_node` (ImageObserver: client, weak owner, image), `types_tree_builder` (Context's four flags),
`types_text_node` (text for rendering + flag, ChunkIterator's fields), `types_table_grid` (GridPosition),
`animations/types_animatable` (Impl, maps per pseudo-element, Transition).
## Deviations and notes
- An ImageObserver is a managed blob; its destructor's unregistering runs where C++ destroys the observers
(`rebuild_image_observers`), not when a layout node is swept.
- **Module-global caches and the collector.** `Typeface::font` cached fonts in the C-heap font database; a font
made while a VM heap was the current allocator lived in that heap, and a collection (or destroying the VM)
freed it under the cache. (The symptoms were random: crashes in `hash_map_get_k<FontCacheKey>`, in
`CSSStyleRule::set_parent_style_sheet` on a later UA-sheet parse, and wrong text chunks.) Fixed in
luce-browser-render (fix/font-cache, DESIGN.md §3.3 rule 7): the font database and its typefaces keep their
caches in the C heap whatever is current, so the layout harness runs with the VM's heap current and collects.
- `page/tests_page`'s test client answers `test_page_client_color_scheme` (default `auto`); the layout tests
set it to `light`, as the oracle's page.
- `html/tests_html_structure_2`'s r26 collection scenario now includes an `<img>` (its visit_edges reaches
ImageProvider's).
## Tests
- `layout/tests_layout_tree_cases` (76 cases; 4 more marked `!` wait for r25, r28 and r48) +
`layout/tests_layout_tree`: a local oracle (`luce-browser-tools/oracles/luce-browser-engine/layout_tree`:
`oracle.cpp` links the reference build's LibWeb, parses each document, attaches its author sheet, gives it
an 800x600 top-level traversable, runs `update_style` and `TreeBuilder::build`; `cases.txt`, `build.sh`,
`gen_luce_cases.py`). Modes: `tree` (Dump's `dump_tree`: anonymous wrappers, continuations, pseudo-elements,
markers, fieldsets, display:none/contents, `<br>`, white space), `nodes` (Node/NodeWithStyle predicates and
containing blocks), `chunks` (text for rendering and every ChunkIterator chunk: white-space modes,
text-transform, quotes, tabs, newlines) and `markers` (list item marker strings). All match. The harness gives
each document a stand-in navigable (its own class: Navigable's visit_edges and finalize are r28's).
- `layout/tests_layout_tree_2`: dominant-baseline offsets and resolution, FormattingContext type names,
scroll containers, set_needs_layout_update propagation, create_anonymous_wrapper, measure_text_width (with
letter spacing), and Animatable's maps and transition attributes.