Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r51b.md

# Regions r51b + r52 (+ the engine half of r51a): paint recording and the painters — what other regions need to know

These regions port the context paintables record into and the painters they call, so a document now goes from
`Document::update_layout` through `ViewportPaintable::paint_all_phases` into a display list, which luce-browser-render's
`DisplayListPlayerCpu` rasterizes. The stub fragments `stub_r51a_display_list`, `stub_r51b_paint_recording` and
`stub_r52_paint_painters` are gone.

## Fragments (painting/)

| Fragment | Donor |
| --- | --- |
| `border_radii_data` | BorderRadiiData.cpp `as_corner`, BorderRadiiData.h `as_corners`, BordersData.cpp `to_device_pixels` (r51a's engine half) |
| `scroll_frame` | ScrollFrame.cpp, ScrollFrame.h `paintable_box`, ScrollState.h `create_scroll_frame_for` / `create_sticky_frame_for` (r51a's engine half) |
| `device_pixel_converter` | DevicePixelConverter.h |
| `chrome_metrics` | ChromeMetrics.h |
| `chrome_widget` | ChromeWidget.h (MouseAction's flag operators, the virtuals' defaults) |
| `display_list_recording_context` | DisplayListRecordingContext.cpp and .h |
| `border_radius_corner_clipper` | BorderRadiusCornerClipper.cpp and .h |
| `resize_handle`, `scrollbar` | ResizeHandle.cpp/.h, Scrollbar.cpp/.h |
| `background_painting` | BackgroundPainting.cpp and .h |
| `blending` | Blending.cpp (+ the ENUMERATE_MIX_BLEND_MODES list) |
| `border_painting_1`, `border_painting_2` | BorderPainting.cpp 1-249 (colors, double/groove/ridge, dotted/dashed), 251-694 (solid edges, `paint_all_borders`, outlines) |
| `box_model_metrics` | BoxModelMetrics.cpp |
| `gradient_painting` | GradientPainting.cpp |
| `input_colors` | InputColors.h |
| `resolved_css_filter` | ResolvedCSSFilter.cpp and .h |
| `shadow_data`, `shadow_painting` | ShadowData.h, ShadowPainting.cpp |
| `table_borders_painting` | TableBordersPainting.cpp |
| `tests_paint_recording_cases`, `tests_paint_recording` | tests (below) |

## What other regions must know

### Values and scopes

- C++ stack objects with a destructor are values plus a `_destruct` to run where the object leaves scope:
  `paint_scoped_corner_radius_clip_new(context, rect, radii, corner_clip, do_apply)` +
  `paint_scoped_corner_radius_clip_destruct(&clip)` (usually with `defer`). Also added:
  `display_list_recording_context_new(recorder, palette, scale, metrics)` and `chrome_metrics_new(zoom)`.
- `DisplayListRecordingContext` holds its recorder as a pointer; `display_list_recording_context_clone(this, recorder)`
  answers a value. Make recorders with `display_list.display_list_recorder_new(list)`:
  `display_list_recorder_construct` only sets the list, so a `= ---` recorder had garbage capture state (fixed at
  r28's `Document::record_display_list` and r50's mask recording).

### Signatures changed from the stubs (all module-private C++ statics)

- `paint_get_box(box_clip, border_box, paintable_box: PaintPaintableBox*)` (was the unmapped `auto const&`).
- `paint_resolve_color_stop_positions(node, color_stop_list: const ak.Vector[...]*, resolve_position_to_float: const
  PaintGradientPositionResolver*, repeating)`: the C++ generic lambda is a resolver struct (linear / conic / radial and
  its basis); the color stop list functions take `const ak.Vector[gfx.ColorStop]*`.
- Table borders: `paint_snap_cells_to_device_coordinates(map: const ak.HashMap[CellCoordinates, PaintPaintableBox*, …]*,
  rows, columns, context: const DisplayListRecordingContext*)`, `paint_device_border_data_from_css_border_data(…,
  context: const DisplayListRecordingContext*)`, `paint_paint_separate_cell_borders(cell, map: const …*, context)`,
  `paint_row_index_for_element_kind` / `paint_column_index_for_element_kind` answer `u64?` (BorderEdgePaintingInfo's
  fields).
- `paint_compute_input_colors` stays `pub` (static in its header) until r53's form-control paintables call it.
- `Scrollbar::mouse_down` is declared in the C++ header but never defined: no port.

### Types filled by hand

- `types_chrome_metrics`: the zoom-invariant constants are `let`s (`n << 6`).
- `generated/types_traits`: `CellCoordinatesTraits` hashes with `pair_int_hash(row, column)` and compares with
  `cell_coordinates_eq`.

### Outside these regions (needed for first pixels)

- **Backing stores** (`painting/backing_store_manager`, coordinator's request): in phase 1 each backing store is a
  plain BGRA8888 premultiplied bitmap wrapped in a painting surface (there is no SharedImageBuffer in
  luce-browser-render); no shared image is published to the page client.
- **`FontFaceSetLoadEvent::create`** (`stubs/stub_closure`): a plain `DOM::Event` of the name and init (the class is
  outside the phase-1 closure; only script reads `fontfaces`). `FontFaceSet` fires `loadingdone` before a test paints.
- **web_test** (`tests/web_test/worker_load`): the worker activates the test document without
  `Navigable::activate_history_entry`'s step 6, so the document stayed `hidden` and was never rendered; it now sets the
  initial visibility state from the traversable's system visibility state.
- The test PageClient (`page/tests_page`) answers a palette (`test_palette()`, WebContent's `setup_palette`).
- HANDOFF §5 item 4 (forward `ScrollbarColorData` / `scrollbar_color()` to display_list): already done by r40
  (`CssScrollbarColorData` is `display_list.ScrollbarColorData`, `css_initial_values_scrollbar_color` forwards); the
  painters pass the colors to `display_list_recorder_paint_scrollbar` unchanged.

### Where paths stop now

- r53's paintables (markers, images, fieldsets, SVG, form controls, canvas, video) still trap at creation.
- Collapsed table borders call r48's `TableFormattingContext::border_is_less_specific` (tables trap earlier, at
  `TableWrapper`).
- Ref tests that differ by a few levels on text (`inline-nested-node`, `css-quotes`, the `float-nowrap-*` group, …):
  the CPU player draws glyphs at their exact subpixel positions, where Skia quantizes glyph positions and caches a
  mask per subpixel offset, so the same text at slightly different x renders differently (render follow-up; done on
  fix/fidelity-text: the player draws FreeType's masks at Skia's quarter-pixel phases, render's INTEGRATION.md).
  The perspective tests needed 3D transforms in the player: done on fix/fidelity-3d (render's INTEGRATION.md, "3D
  transforms"): the 12 perspective Ref tests pass.

## Tests

- **Layout harness** (`layout/tests_layout_geometry`, `painting/tests_paintables`): the cases run the real
  `Document::update_layout` (`test_layout_tree_parse_and_style` + `test_layout_geometry_update_layout`) instead of the
  hand-run layout steps and commit; all pass (68 geometry, 340 inline, 22 paintables — the border radii case that
  waited for r52 is enabled). The inline "lines" mode still runs the layout steps itself (it reads the layout state
  before commit).
- **`painting/tests_paint_recording`** (oracle `luce-browser-tools/oracles/luce-browser-engine/paint_recording`):
  - DevicePixelConverter / DisplayListRecordingContext / ChromeMetrics at scales 1, 1.5, 2, 0.75, 1.25: exact;
  - `Document::dump_display_list` of 9 documents (backgrounds, borders of every style and width, border radii,
    outer/inner box shadows, linear/radial/repeating gradients, outlines and background clips, text, text shadow,
    opacity and z-index): **exact** (every command the painters record is Ladybird's);
  - the same documents rendered as a screenshot (record with the overlay and canvas fill, CPU player into 800x600)
    against the pixels Ladybird's Skia player renders, which `compare_headless.py` checked to be identical to
    Ladybird's own `--headless=screenshot --test-mode` screenshots. Boxes, border styles, radii, outlines/clips and
    layers are **pixel exact**; tolerances per case (max channel difference, differing pixels): gradients 2 / 40
    (1 level on 14 pixels), shadows 4 / 3200 (blur: 2944 pixels within 3 levels), text 130 / 2000 and text-shadow
    130 / 1400 (glyphs: FreeType's hinted masks vs unhinted outlines, 1849 and 1242 pixels; exact since
    fix/fidelity-text).
  - MouseAction's operators, BoxModelMetrics, mix-blend-mode mapping.
- **web_test** (after merging main with r46): Layout **427** pass (of 845), Ref **352** pass (of 587 run; both sides
  through our rasterizer), Crash **23**; `tests/expected_failures` rewritten with `--update-failures`.