Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r49.md

# Regions r49 + r53: SVG layout and the remaining paintables — what other regions need to know

Region r49 ports `Layout/SVGFormattingContext` and the SVG layout boxes (`SVGBox`, `SVGGraphicsBox`, `SVGGeometryBox`,
`SVGClipBox`, `SVGMaskBox`, `SVGPatternBox`, `SVGImageBox`, `SVGForeignObjectBox`, `SVGSVGBox`, `SVGTextBox`,
`SVGTextPathBox`). Region r53 ports the paintables region r50 left: `SVGPaintable`, `SVGGraphicsPaintable` (with
`ComputedTransforms`), `SVGMaskable`, `SVGPathPaintable`, `SVGSVGPaintable`, `SVGClipPaintable`, `SVGMaskPaintable`,
`SVGPatternPaintable`, `SVGForeignObjectPaintable`, `MarkerPaintable`, `FieldSetPaintable`, `ImagePaintable`,
`CheckBoxPaintable`, `RadioButtonPaintable`, `CanvasPaintable`, `VideoPaintable` and
`NavigableContainerViewportPaintable`. Both stub fragments (`stub_r49_layout_svg`, `stub_r53_paint_svg_replaced`) are
gone. An inline `<svg>` is now laid out (viewBox and preserveAspectRatio, nested viewports, groups, transforms, shapes
and their strokes, masks, clip paths and patterns as viewports in their content units, images, text paths) and painted
through display lists (fills and strokes in paint-order with paint servers or colors, clip paths as geometry, masks),
and list markers, fieldsets, images, checkboxes, radio buttons, canvases, videos and iframes have their paintables.

## Fragments

| Fragment | Donor |
| --- | --- |
| `layout/css_pixel_bounding_box` | `LibGfx/BoundingBox.h` for CSSPixels (gfx does not instantiate it) |
| `layout/svg_box`, `svg_graphics_box`, `svg_geometry_box`, `svg_clip_box`, `svg_mask_box`, `svg_pattern_box`, `svg_image_box`, `svg_foreign_object_box`, `svgsvg_box`, `svg_text_box`, `svg_text_path_box` | the matching `Layout/SVG*Box.cpp` + `.h` |
| `layout/svg_formatting_context_1` | `SVGFormattingContext.cpp` 1-374 + `.h`: construction, `scale_and_align_viewbox_content`, `is_container_element`, `run`, `layout_svg_element`, `layout_nested_viewport` |
| `layout/svg_formatting_context_2` | 376-609: text and textPath paths, path-like elements, the parent SVG transform, graphics elements, images, masks/clips/patterns, containers |
| `painting/svg_paintable`, `svg_graphics_paintable`, `svg_maskable`, `svg_path_paintable`, `svgsvg_paintable`, `svg_clip_paintable`, `svg_mask_paintable`, `svg_pattern_paintable`, `svg_foreign_object_paintable` | the matching `Painting/SVG*.cpp` + `.h` |
| `painting/marker_paintable`, `field_set_paintable`, `image_paintable`, `check_box_paintable`, `radio_button_paintable`, `canvas_paintable`, `video_paintable`, `navigable_container_viewport_paintable` | the matching `Painting/*Paintable.cpp` + `.h` |
| `layout/tests_layout_svg_cases`, `layout/tests_layout_svg` | tests (below) |

## What other regions must know

- **Formatting contexts**: SVG formatting contexts live in managed memory like the others (r44.md);
  `~SVGFormattingContext` is the default destructor. The BlockFormattingContext a `<foreignObject>` makes is destructed
  where C++ leaves its scope (`defer layout_formatting_context_destruct`).
- **`Gfx::AffineTransform {}` is the identity**, and a zeroed `gfx.AffineTransform` is not:
  `layout_identity_affine_transform()` (layout/svg_formatting_context_1) answers it. `ComputedTransforms()` is
  `paint_svg_graphics_paintable_computed_transforms_new()` (both identities); an SVGGraphicsPaintable's constructor and
  `reset_for_relayout` set it.
- **SVGMaskable** is a stateful mixin at `svg_maskable` inside SVGGraphicsPaintable (and its subclasses) and
  SVGForeignObjectPaintable. Constructors set its vptr and class id: `paint_svg_graphics_paintable_set_maskable_class`
  (subclasses move it to their own table, as SVGPathPaintable and SVGMaskPaintable do). The overrides recover the
  paintable with `offsetof`, and SVGMaskable's own `as_if<SVGGraphicsPaintable>(*this)` goes through the class's
  `MixinOffsets` (`paint_svg_maskable_paintable`).
- **Signatures changed from the stubs**: `layout_scale_and_align_viewbox_content` takes the box state as
  `const LayoutStateUsedValues*` (the C++ `auto const&`); `paint_svg_graphics_paintable_computed_transforms_svg_to_device_pixels_transform`
  takes `const DisplayListRecordingContext*` (the stub took a copy); the template `first_child_layout_node_of_type<T>`
  of SVGMaskable.cpp takes the layout class's `ClassInfo` (DESIGN §2.4). File-static and private C++ functions are
  module-private. `SVGTextBox::viewbox_origin` and `SVGTextPathBox::viewbox_origin` are only declared in C++: no port.
- `Gfx::Path::text` and `place_text_along` are web_fonts' (`web_fonts.path_text_utf16_view`,
  `path_place_text_along_utf16_view`).
- **Form controls (r24/r25)**: the checkbox and radio paintables read `HTMLInputElement::checked`/`indeterminate`,
  FormAssociatedElement's `enabled` and Element's `is_being_activated`; number steppers and select chevrons are laid
  out by the SVG formatting context.

## Where paths stop (other regions' stubs)

- **r56 (SVG II)**: the constructors of `<text>`, `<tspan>`, `<textPath>`, `<mask>`, `<clipPath>`, `<pattern>`,
  `<foreignObject>`, `<symbol>`, `<use>`, `<image>`, `<a>`, gradients and filters. Their layout and painting paths
  here (masks and clip paths as viewports and as display lists, text paths, images, patterns) are ported and wait for
  those elements; 19 Layout tests with SVG stop there (6 text, 4 mask, 4 foreignObject, 3 symbol, 2 use).
- **P2**: decoded images (ImagePaintable paints whatever decoded image data its provider has), canvas and video
  content, iframes' content.

## Deviations and notes

- **Donor quirk kept**: `scale_and_align_viewbox_content` decides the Y alignment on `has_definite_width()` (as the
  C++ does), not on the height.
- C++ lambdas are functions: `resolve_dimension` (nested viewports), `paint_fill`/`paint_stroke` (their by-reference
  captures in `PaintSvgPathPaintablePaintCaptures`), FieldSetPaintable's `paint_borders_with_optional_clip`,
  CheckBoxPaintable's `shade`/`modify_color`/`increase_contrast`, RadioButtonPaintable's `draw_circle`/`shrink_all`
  (`radio_color` and `fill_color` are inlined in order, `radio_color` darkening the background as it does by
  reference), VideoPaintable's `paint_bitmap`/`paint_video_frame`/`paint_transparent_black`. RAII scopes
  (`ScopedCornerRadiusClip`, `DisplayListRecorderStateSaver`) are values with `defer`red destructors, in C++'s order.
- `AK/Debug.h`'s HIGHLIGHT_FOCUSED_FRAME_DEBUG is the private constant `paint_highlight_focused_frame_debug` (false).
- The engine follow-ups of luce-js `HANDOFF.md` §5 item 4 were all done by earlier regions.

## Tests

- **web_test** (merged with main at 87c38f5): Layout **763 → 819**, Ref **397 → 432**, Crash **29 → 32**;
  `tests/expected_failures` rewritten with `--update-failures`. (On r55's main, before r24/r25: Layout 727 → 779,
  Ref 388 → 419, Crash 28 → 31.) Of the Layout tests with SVG, all but the 19 that need r56's elements pass.
- **`layout/tests_layout_svg`** (54 cases) from the local oracle `luce-browser-tools/oracles/luce-browser-engine/layout_geometry`
  (`cases_svg.txt` written by `own_svg_cases.py`, `./oracle cases_svg.txt > expected_svg.txt`,
  `python3 gen_luce_cases.py svg`): 32 of Ladybird's Layout tests with SVG (`compare_ladybird.py --full`: the oracle
  reproduces their whole expected files; 19 more are marked for r56), and cases written for these regions: every
  preserveAspectRatio alignment with meet and slice (wide and tall), negative/zero/offset viewBoxes, nested viewports
  with and without viewBox, groups with transform lists (translate, scale, matrix, rotate, skew), display and
  visibility, shapes with strokes and percentages, `<svg>` sizing in blocks, inline content, flex and grid containers,
  abspos and transformed ancestors, number inputs and selects (SVG in UA shadow trees), checkboxes and radio buttons.
  The new **`svg` mode** prints every SVG paintable: class, absolute rect, the computed transforms, mask and clip
  areas, the computed path (SVG path data) and bounding box, clip path contribution and bounds, anti-aliasing (its
  cases avoid arcs, whose points come from libm). All match.
- **Unmarked oracle cases** that waited for r53's paintables: 6 geometry cases (list items, fieldsets, images) and 27
  inline cases (list markers, fieldsets, details, ...) plus 1 flex case; all pass. `details-closed` and
  `details-summary-default-ua-style` stay marked: the unit harness's document has no CSP list, which the `<style>` of
  `<details>`' UA shadow tree asks for (web_test passes them; the P1 polish gave the harness a Window realm and
  unmarked them). In the unit harness a number input's automatic width
  (`size` in `ch`) resolves to 0 where the oracle gives 200px (web_test's `number-input-appearance` passes), so the SVG
  case with number inputs gives them a width; worth a look by the harness's owners.
- **`painting/tests_paint_recording`** (oracle `paint_recording`): new documents `svg-shapes`, `svg-strokes`,
  `svg-viewbox`, `markers`, `fieldset`, `checkbox-radio`. The display lists are **exact**. Pixels: SVG fills and
  viewBoxes exact; markers and legends differ by glyph anti-aliasing (as r52's text cases); the dashed SVG stroke
  differs on 3 pixels at the corner where its first dash starts (Skia's dasher leaves the miter white, the CPU
  player's tiny-skia dasher paints it: a render follow-up).

## Compiler issues

None.