Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r50.md

# Region r50: paintables — what other regions need to know

Region r50 ports `Painting/Paintable`, `PaintableBox`, `PaintableWithLines`, `PaintableFragment`, `TextPaintable`,
`StackingContext`, `ViewportPaintable`, `ReplacedElementCommon` and the rest of `BackingStoreManager` (r28 took its
constructor and `visit_edges` ahead). The stub fragment `stubs/stub_r50_paintables.lucb` is gone.
`LayoutState::commit` now makes and fills the paint tree, so a laid-out document has paintables: Dump's paint tree
dump and `StackingContext::dump` work, and with Dump's layout dump they give the whole expectation of a Layout test.
Hit testing, selection states, range rects and the code unit under a point work on committed trees.

## Fragments

| Fragment | Donor |
| --- | --- |
| `painting/paintable` | `Paintable.cpp` 1-398 and `Paintable.h` (flags, containing block, stacking context, inspector overlay, `normalize_border_radii_data`, `::selection` styling, selection states, `HitTestResult::dom_node`) |
| `painting/paintable_box_1` | `PaintableBox.h`'s inline members and `PaintableBox.cpp` 1-518: `resolve_css_filter`, creation, relayout reset, scrolling, offsets and absolute rects, continuation unions, CSS clip, scrollbars, `overflow_property_applies` |
| `painting/paintable_box_2` | 520-992: scrollbar geometry, `paint`, the middle button indicator, the inspector overlay, stacking contexts and z-index, borders, backdrop filters, backgrounds, box shadows, normalized radii, visual-context point/rect mapping |
| `painting/paintable_box_3` | 994-1349: resizers, mouse wheel, hit testing, repaint invalidation, transform reference box, radii and outlines, scroll frames, resize axes |
| `painting/paintable_fragment` | `PaintableFragment.cpp` 1-302 and `.h` |
| `painting/paintable_with_lines_1` | `PaintableWithLines.cpp` 1-480 and `.h` (fragments, hit testing, text fragment properties, `paint`, render spans, text, the cursor) |
| `painting/paintable_with_lines_2` | 482-817: skip-ink segments, text decorations, the triangle wave path |
| `painting/replaced_element_common` | `ReplacedElementCommon.cpp` |
| `painting/stacking_context` | `StackingContext.cpp` and `.h` |
| `painting/text_paintable` | `TextPaintable.cpp` and `.h` |
| `painting/viewport_paintable_1` | `ViewportPaintable.h` and `.cpp` 1-174 (creation, the stacking context tree, `paint_all_phases`, scroll frames) |
| `painting/viewport_paintable_2` | 175-596 (transforms, perspectives, overflow clips, accumulated visual contexts, scroll state, selection states) |
| `painting/backing_store_manager` | r28's fragment, completed: `BackingStoreManager.cpp` 1-171 |
| `painting/tests_paintables_cases`, `painting/tests_paintables` | tests (below) |

## What other regions must know

### Creation

`T::create(layout_node)` (`layout_node.heap().allocate<T>(...)`) is `paint_paintable_box_create_layout_box`,
`paint_paintable_with_lines_create_layout_block_container` / `_layout_inline_node`, `paint_text_paintable_create`,
`paint_viewport_paintable_create`: allocate in the layout node's heap under `DeferGC`, then construct. Region r53's
paintables (markers, images, fieldsets, SVG, form controls) follow the same pattern; their constructors must call
`paint_paintable_box_construct_layout_box` (or `paint_paintable_construct`). `heap.allocate<StackingContext>` is
`paint_stacking_context_create(heap, ...)`; `PaintableFragment { fragment }` by value is `paint_paintable_fragment_new`.

### Signatures changed from the stubs

- `paint_paintable_computed_values` answers `const CssImmutableComputedValues*` (it was a copy; C++ answers a const&).
- `paint_paintable_with_lines_paint_text_fragment_debug_highlight` takes `const PaintPaintableFragment*`.
- `paint_viewport_paintable_paintable_boxes_with_auto_content_visibility` answers `const (PaintPaintableBox*)[]`
  (C++ `ReadonlySpan<GC::Ref<PaintableBox>>`).
- `paint_get_replaced_box_painting_area` (for r53) takes `context: const DisplayListRecordingContext*` and answers the
  C++ `Gfx::IntRect` as a `gfx.DevicePixelRect`.
- `for_each_cluster_in_glyph_run` (a template over a callback) is the iterable `paint_glyph_run_clusters(glyph_run,
  length)` (namemap updated).
- `Paintable::detach_from_layout_node` is only declared in C++ and has no port.
- File-static C++ functions are module-private: `paint_paint_node`, `paint_to_paint_phase`,
  `paint_stacking_context_paint_child/_paint_internal`, `paint_resolve_text_fragment_properties`,
  `paint_compute_render_spans`, `paint_paint_text_fragment`, `paint_paint_text_decoration`,
  `paint_compute_skip_ink_segments`, `paint_build_triangle_wave_path`, `paint_effective_css_clip_rect`,
  `paint_scale_matrix_for_device_pixels`, `paint_compute_transform/_perspective_matrix/_clip_data` (these take the
  computed values and the converter by pointer), `paint_create_shareable_bitmap_backing_stores`,
  `paint_viewport_paintable_build_stacking_context_tree`, `paint_paintable_with_lines_fragment_at_position/_paint_cursor`.

### Types filled by hand

- `types_paintable`: `SelectionStyle` and the new `Paintable::TextDecorationStyle`
  (`PaintPaintableTextDecorationStyle`); C++'s `Optional<GC::Ptr<PaintableBox>> m_containing_block` (computed once,
  null included) is `m_containing_block` plus `m_has_containing_block`.
- `types_paintable_box`: `ScrollbarData`, `PhysicalResizeAxes`; `paint_phase_count` is a constant.
- `types_paintable_fragment`: `SelectionOffsets`, `FragmentSpan` (its `fragment` is a `const PaintPaintableFragment*`,
  C++'s reference) and the new `PaintableFragment::TextDecorationData` (`PaintPaintableFragmentTextDecorationData`).
  Namemap rows are updated or added for all of them.
- `stubs/stub_r51b_paint_recording`: gains `paint_scoped_corner_radius_clip_destruct` (`~ScopedCornerRadiusClip`,
  which the skeleton did not emit; `paint_backdrop_filter` runs it with `defer`). Region r51b ports it.

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

- **Painting into a display list** (`ViewportPaintable::paint_all_phases`, `StackingContext::paint`, every
  `paint_impl`) stops at once at region r51b's `DisplayListRecordingContext` accessors
  (`display_list_recording_context_display_list_recorder`); past them, borders, backgrounds, shadows, outlines and
  table borders call region r52's painters, text decorations and shadows r52's `ShadowData::from_css` /
  `paint_text_shadow`, and SVG roots region r53's `SVGSVGPaintable`.
- **The rest of `Document::update_layout` after commit**: `ViewportPaintable::assign_scroll_frames` stops at the
  engine half of region r51a (`ScrollState::create_scroll_frame_for`, `ScrollFrame::paintable_box`, still in
  `stubs/stub_r51a_display_list`) — the viewport always gets a scroll frame, so every document stops there — and
  `assign_accumulated_visual_contexts` at region r51b's `DevicePixelConverter` (then r52's `to_gfx_filter` and
  `mix_blend_mode_to_compositing_and_blending_operator`). So `Document::update_layout` does not yet run end to end;
  the tests run commit and the steps after it that do (below). Neither step changes the dumps.
- **Paint trees with r53's paintables**: list item markers (`MarkerPaintable::create`), images, fieldsets, SVG, form
  controls, canvas and video trap at creation, during commit.
- **Border radii**: `PaintableBox::border_radii_data` of a box with non-initial radii needs r52's
  `BoxModelMetrics::border_box`. `::selection` with `text-shadow` needs r52's `ShadowData::from_css`.
- **Hit testing chrome**: a scrollable or resizable box asks `Page::chrome_metrics`, which constructs r51b's
  `ChromeMetrics`.
- **Backing stores**: `create_shareable_bitmap_backing_stores` traps where C++ creates two `Gfx::SharedImageBuffer`s
  (shared memory images are not in luce-browser-render); there is no Skia backend context or Vulkan in the port.

## Deviations and notes

- C++ lambdas are functions with the lambda's state passed in (`paint_viewport_paintable_precompute_sticky_constraints`,
  `paint_viewport_paintable_make_effects_data`, `paint_paintable_selection_style_from_element`,
  `paint_paintable_box_check_scrollbar`, ...); `united_rect_for_continuation_chain`'s callable is an enum naming the
  rect; `PaintableBox::hit_test(position, type)`'s candidate lambda keeps its state in a struct behind an
  `ak.Function1`. `TemporaryChange` of the recorder's save nesting level is a saved value and `defer`, and the
  `ScopeGuard` that checks it a second `defer` (it runs first, as the C++ destructors do).
- `PaintableBox::scroll_offset` of the viewport reads `Navigable::viewport_scroll_offset` (ported by r28).
- HANDOFF (luce-js HANDOFF.md §5 item 4) follow-ups: all were done by earlier regions (see r44.md, r45.md).

## Tests

- **Layout dumps**: `layout/tests_layout_geometry` runs the real `LayoutState::commit` (the paint emulation of r44/r45,
  `tests_layout_paint_emulation`, is deleted), then the viewport rect broadcast and the scroll state refresh, and
  compares the whole expectation of a Layout test: Dump's layout tree, Dump's paint tree and the stacking context tree
  (`test_layout_geometry_dump`). The oracle (`luce-browser-tools/oracles/luce-browser-engine/layout_geometry`) prints
  the same three dumps after the rest of `Document::update_layout`, and for every case taken from Ladybird it matches
  the **whole** expected file (`compare_ladybird.py --full`: 19 + 316 OK). Cases whose paint tree has r53's
  paintables are marked waiting (`mark_paintables.py`: 6 geometry, 19 inline). Results: **68** geometry and **340**
  inline cases pass. Of Ladybird's Layout tests the port now reproduces all three parts of **138** of the 164
  `block-and-inline` tests (21 more wait for flex, grid, buttons or r53's markers/images; 5 need script or images)
  and of **154** others (22 waiting) — `count_ladybird.py`.
- **`painting/tests_paintables`** (21 oracle cases, the oracle's new modes, `own_paint_cases.py`): for each paintable
  of a committed paint tree in pre-order — the flags, containing block, enclosing stacking context, `::selection`
  background, every absolute rect of a paintable box (content, padding, border, united over continuations, overflow
  clip edge, transform reference box), border radii, z-index, the scrolling/overflow/resize/mirroring predicates,
  outline offset, CSS clip; each fragment's rect, orientation, range rects in every selection state and the code unit
  under seven points across it. Mode `paint` also hit tests the viewport (exact and text cursor) at a 20×22 grid of
  points (stacking contexts with negative/zero/positive z-index, floats, inline blocks, relative inlines,
  continuations, hidden and pointer-events: none content, empty editable boxes, right-to-left and vertical text).
  Mode `selection` selects a range across text nodes and compares `recompute_selection_states` and the range rects.
  The documents avoid transforms, scroll containers and resizers in hit tests (they need the accumulated visual
  contexts and chrome metrics of r51a/r51b) and border radii (r52); one radii case waits.