Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / docs / regions / r45.md

# Region r45: inline layout — what other regions need to know

Region r45 ports `Layout/InlineFormattingContext`, `Layout/InlineLevelIterator`, `Layout/LineBox`,
`Layout/LineBoxFragment` and `Layout/LineBuilder`. The stub fragment `stubs/stub_r45_layout_inline.lucb` is gone.
A block container whose children are inline is now laid out: text is split into chunks (r43's ChunkIterator),
shaped with web_fonts, placed on line boxes that break at the available width and beside floats, and aligned
(text-align, text-indent, vertical-align, the strut, baselines); atomic inline boxes are dimensioned on the line;
floats met among inline content are placed by the parent BlockFormattingContext; absolutely positioned boxes get
their static position.

## Fragments

| Fragment | Donor |
| --- | --- |
| `layout/inline_formatting_context_1` | `InlineFormattingContext.cpp` 1-199 and `.h`: construction, parent, the float-aware line start and width, `run`, `dimension_box_on_line` |
| `layout/inline_formatting_context_2` | 201-597: justification, the text-overflow ellipsis, `generate_line_boxes` (its text case is `place_text_item`), float intrusion and line fitting, vertical float clearance, static positions |
| `layout/inline_level_iterator` | `InlineLevelIterator.cpp` 1-463 and `.h` (Item and its border box width) |
| `layout/line_box` | `LineBox.cpp` 1-152 and `.h` |
| `layout/line_box_fragment` | `LineBoxFragment.cpp` 1-180 and `.h` |
| `layout/line_builder` | `LineBuilder.cpp` 1-457 and `.h` |
| `layout/tests_layout_paint_emulation` | test support: what commit would give the paintables (below) |
| `layout/tests_layout_inline_cases`, `layout/tests_layout_inline` | tests (below) |

## What other regions must know

### Construction

- The InlineFormattingContext is constructed where its creator puts it (BlockFormattingContext does it in its frame,
  as the C++ does); its destructor is the default one, so nothing needs `layout_formatting_context_destruct` for it.
  `layout_inline_formatting_context_construct` initializes every field (the BFC's storage is `---`).
- `layout_line_box_new(direction, writing_mode)` and `layout_line_box_fragment_new(...)` are `LineBox(...)` and
  `LineBoxFragment { ... }` by value. `LineBox::LineBox` runs `layout_line_box_init_fields` (its original available
  width is indefinite); a zeroed `LayoutLineBox()` (as tests_layout_state makes) has a definite zero width instead.
- InlineLevelIterator and LineBuilder hold non-null pointers, so they are `var x: T = ---` plus their constructor.

### Signatures changed from the stubs

- `layout_inline_level_iterator_construct` takes `containing_block_used_values: const LayoutStateUsedValues*` (it was
  a copy).
- `layout_line_box_fragments_const` answers `const ak.Vector[LayoutLineBoxFragment]*` (it was a copy).
- C++ private members are module-private: the IFC's `generate_line_boxes`, `apply_text_overflow_ellipsis`,
  `apply_justification_to_fragments`; every InlineLevelIterator member but `construct`, `next`,
  `next_non_whitespace_sequence_width` and `Item::border_box_width`; LineBuilder's `begin_new_line`,
  `should_break`, `ensure_last_line_box`.

### Types filled by hand

- `types_inline_level_iterator`: `InlineLevelIterator::Item` (was opaque) and the new `Item::Type`
  (`LayoutInlineLevelIteratorItemType`, namemap row added); `Optional<TextNodeContext>` is the context plus
  `m_has_text_node_context`, so the iterator updates it in place (an optional's value has no address).
- `types_line_box`, `types_line_builder`: the `init_fields` set the indefinite available widths.

### Where paths stop (other regions' stubs)

- Atomic inlines that are flex, grid or table containers, buttons (FFC r46, GFC r47, TFC r48, r25) and `<details>`
  (whose UA style sheet reaches the CSP closure stub `should_elements_inline_type_behavior_be_blocked_...`).
- `LayoutState::commit` still makes paintables (r50), so tests dump from used values (below). Commit already moves
  fragments to inline nodes' paintables (`try_to_relocate_fragment_in_inline_node`) and measures them; r50's
  PaintableFragment/PaintableWithLines get `LayoutLineBoxFragment`s by value.

## Deviations and notes

- C++ lambdas: LineBuilder's `intersection_test` (with the `available_space_cache` HashMap kept), `strut_baseline`,
  `line_box_baseline` and `block_offset_value_for_alignment` (a function taking the line box baseline), LineBox's
  `should_trim`, the IFC's `left_edge`/`right_edge` (inlined); the `has_breaking_tab` branch of
  `generate_next_item` is `layout_inline_level_iterator_tab_stop_width` and the text node branch
  `generate_next_text_item`; the `is_empty_editable` test is `layout_inline_level_iterator_is_empty_editable`.
- `switch` cases that `break` out of the switch in `generate_line_boxes`' text case are an early `return` from
  `place_text_item`.
- AK's `min(a, b)` on AvailableSize (`b < a ? b : a`, comparing values only) is written out in
  `recalculate_available_space`.
- HANDOFF (luce-js HANDOFF.md §5 item 4) follow-ups: all were done by earlier regions (r33 clones css_data's shared
  vectors; r44 lists the others).

## Tests

- `layout/tests_layout_inline_cases` (359 cases) + `layout/tests_layout_inline`, from the local oracle
  `luce-browser-tools/oracles/luce-browser-engine/layout_geometry` (r44's, extended: `cases_inline.txt`,
  `own_cases.py`, `mark_later.py`, `compare_ladybird.py cases_inline.txt expected_inline.txt`,
  `gen_luce_cases.py inline`). The oracle now loads only the engine's test fonts with the FontPlugin in test mode and
  names its system font provider "FontConfig" (so Skia uses FreeType, as test-web's `--force-fontconfig`); r44's
  expectations are unchanged by that.
  - 120 are Ladybird's `Tests/LibWeb/Layout/input/block-and-inline` tests with text: with r44's 19, the port
    reproduces **139 of the 164** block-and-inline expected layout dumps exactly. Of the other 25, 20 wait for flex,
    grid and buttons (marked `!`) and 5 need script or images.
  - 171 are Ladybird's other Layout tests that need no flex, grid, table, SVG, MathML or form-control layout and
    whose expected dump the oracle reproduces (lists, markers, fieldsets, floats, positioning, fonts, CSS values...);
    all pass. 5 more are marked `!`: `font-size-zero` and `percentage-font-size` (web_fonts' metrics of SerenitySans
    at 0px: Ladybird's baseline is 0.296875, the port's 0 — luce-browser-render), and the three `details-*` tests
    (CSP closure stub). The P1 polish unmarked the two font cases (render measures a zero-size font at 1 px, as
    Skia does), the three details cases (the harness makes its documents in a Window's realm) and the 12
    block-and-inline button cases (flex, grid and buttons are ported; they match), so no inline case waits.
  - 68 are written for this region (34 documents, each in two modes): text-align in both directions, justification,
    text-indent (each-line, hanging, negative, percentages), every vertical-align keyword and lengths on text and
    inline-blocks, white-space modes and tabs (tab-size), letter/word spacing, word-break and overflow-wrap,
    text-overflow ellipsis, floats beside lines (narrow lines moving down, clear on `<br>`), inline boxes across
    lines, relative inline boxes, static positions, collapsible whitespace, line-height, font sizes, intrinsic sizes,
    right-to-left and Hebrew text (rtl glyph runs merged into fragments), vertical writing modes, generated content.
    Mode `layout` compares Dump's layout tree; mode `lines` compares the line boxes of every block container before
    commit, field by field (lengths, bottoms, baselines, available widths, breaks, trailing whitespace) with each
    fragment (offsets, sizes, baselines, direction, flags) and its glyph run (every glyph's position, width, id and
    code unit length).
- `layout/tests_layout_paint_emulation`: commit makes paintables (r50), so the harness puts in each dump line what
  commit would have given the paintables, from the used values: atomic inlines' offsets from their line box
  fragments, the fragments of block containers and those commit moves into each inline node's paintable for a line,
  the line-0 paintable of an inline node without fragments, `resolve_relative_positions`, and commit's measuring of
  inline nodes' paintables over the paint tree `build_paint_tree` makes. r44's 74 geometry cases still pass with it.
- Float formatting: the oracle prints the glyph floats with `{}` as floats. (r45 printed them as doubles and the glyphs'
  y as its bits, because luce-browser-foundation's float formatting broke a tie in the last printed digit the other
  way from AK, `{}` of 144.203125f: AK 144.20312, ak 144.20313; foundation's ak rounds ties to even since the P1
  polish, as AK's Dragonbox does.)