Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / docs / regions / r56.md

# Region r56: SVG II — what other regions need to know

Region r56 ports the rest of LibWeb's SVG DOM: the paint servers (`SVGGradientElement`, `SVGLinearGradientElement`,
`SVGRadialGradientElement`, `SVGStopElement`, `SVGPatternElement`), `SVGMaskElement`, `SVGClipPathElement`,
`SVGUseElement`, `SVGSymbolElement`, the text elements (`SVGTextContentElement`, `SVGTextPositioningElement` with
`TextPositioning`, `SVGTextElement`, `SVGTSpanElement`, `SVGTextPathElement`), `SVGForeignObjectElement`,
`SVGImageElement`, `SVGAElement`, `SVGAnimationElement`, `SVGFilterElement` (with the Gfx::Filter graph of its
primitives), `SVGFilterPrimitiveStandardAttributes`, the 18 filter primitive elements (`SVGFE*`) and
`SVGDecodedImageData` (with its `SVGPageClient`). The `SVGAnimated*` values that `regions.tsv` lists here were ported
by r55. The stub fragment `stubs/stub_r56_svg_2.lucb` is gone (all 385 functions ported, or noted below).

## Fragments (in `svg/`)

| Fragment | Donor |
| --- | --- |
| `svg_animation_element`, `svg_clip_path_element`, `svg_mask_element`, `svg_symbol_element`, `svg_foreign_object_element` | the matching `.cpp` + `.h` |
| `svg_text_content_element`, `svg_text_positioning_element` (with `TextPositioning::apply_to_text_position`), `svg_text_element`, `svgt_span_element`, `svg_text_path_element` | the text elements |
| `svg_stop_element`, `svg_gradient_element`, `svg_linear_gradient_element`, `svg_radial_gradient_element`, `svg_pattern_element` | the paint servers |
| `svg_use_element`, `svga_element`, `svg_image_element` | `<use>`, `<a>`, `<image>` |
| `svg_filter_primitive_standard_attributes` | the CRTP mixin (and two helpers for the primitives' `SVGAnimatedString`/`SVGAnimatedNumber` creation) |
| `svgfe_blend_element` … `svgfe_turbulence_element` (18) | the filter primitives |
| `svg_filter_element` | `SVGFilterElement.cpp` (the filter graph is one function, `svg_filter_element_gfx_filter`) |
| `svg_decoded_image_data` | `SVGDecodedImageData.cpp` + `.h` (the image data and the SVGPageClient) |
| `tests_svg_ii_cases`, `tests_svg_ii` | tests (below) |

## What other regions must know

### Signature and type changes

- **`SVGFilterPrimitiveStandardAttributes<T>`**: its functions take the including element (`x`, `y`, `width`,
  `height`, `result`, `this_svg_element`: `(this, element: SvgElement*)`), as r55 did for `SVGURIReferenceMixin`: the
  CRTP `static_cast<IncludingClass*>(this)` is a class-specific offset a generic body cannot ask for (`offsetof(T, …)`
  of a type parameter is rejected). Callers pass `(&fe.svg_filter_primitive_standard_attributes, fe.svg_element())`.
- **`SVGGradientElement::for_each_color_stop`** (a template over the callback) takes a function pointer beside its
  capture context: `svg_gradient_element_for_each_color_stop(this, callback: func(void*, SvgStopElement*), context)`.
- **The `HashTable<X const*>` of seen gradients/patterns and the use element's `GC::HeapHashTable<GC::Ref<Element>>`**
  are `SvgGradientElementSet`, `SvgPatternElementSet`, `SvgUseElementVisitedSet`: `ak.HashTable[X*, ak.PtrTraits[X]]`
  (the stubs said `X*?` elements). The use element's table lives on the stack (its buffer is managed memory).
- **`SVGDecodedImageData::SVGPageClient`** was opaque (`types_svg_decoded_image_data`): it is filled as a PageClient
  subclass (`m_host_page`, `m_svg_page`) with its own vtable and ClassInfo. Like the phase-1 stand-ins of LibJS objects
  it has PageClient's class id and is recognized by its ClassInfo (`is_svg_decoded_image_data_svg_page_client`). Its
  virtual overrides are `svg_decoded_image_data_svg_page_client_<name>_impl(base: PageClient*)` (the stubs had
  non-virtual names; `docs/namemap.tsv` updated).
- `SVGFEImageElement::content_rect` answers `gfx.DevicePixelRect?` (gfx's `IntRect`, as the stub had).
- The display list's upcast methods (`.svg_gradient_paint_style()`, …) are private to luce-browser-render: the paint
  servers upcast with a cast (`(display_list.SvgGradientPaintStyle*)style`; the base is the first field).
- Private (C++ private / `static`): the `*_impl` halves of the href-chain getters, `linked_*`, the use element's
  referenced element / fetch / clone / circular-reference functions, `process_the_url`, `ensure_length_list`, the
  `parse_*` / `string_to_*` helpers of the primitives, `is_direct_child_of_use_shadow_tree`, SVGDecodedImageData's
  `record_display_list` / `render_to_surface`.
- `SVGUseElement::parse_id_from_href` is only declared in the donor: no port (namemap: "declared only").
- `SVGDecodedImageData::surface` is private and unused in the donor; it is `pub` here so `check -W` stays clean.

### Where paths stop

- **P2 (fetching)**: `<image>`, `<feImage>` and a `<use>` of another document start a `SharedResourceRequest`, whose
  `create_potential_CORS_request` traps `unported (P2)` (web_test: svg-use-element-crashtest, 4 image Ref tests,
  effect-reference-feimage-001). `SVGDecodedImageData::create` builds the image's page, traversable and XML document
  (as web_test's worker builds a test's) and then parses through the XML seam
  `xml_parse_with_document_builder` (`unported (P2)`; the seam takes a String, so the bytes are decoded as UTF-8 with
  replacement first, and has no scripting flag: P1 never scripts).
- **P3**: `getStartPositionOfChar` (DOMPoint), the bindings that would read the SVG DOM.

## Deviations and notes

- **Donor quirks kept**: `SVGLinearGradientElement` keeps its paint style across attribute changes (only the radial
  one drops it); a `<textPath>` resolves only `href`, not `xlink:href` (`get_attribute(href)`); `SVGMaskElement`'s
  masking area inflates by `CSSPixels(2) / 10` as a CSSPixels (0.1875, not 0.2) as the donor's
  `Size<CSSPixels>::scaled` does; `SVGImageElement`'s placeholder lengths, the foreignObject's fake lengths and
  `edge_mode`'s constant 0 are the donor's FIXMEs.
- C++ lambdas are functions (names in the namemap): `add_color_stops`' callback (captures in
  `SvgGradientElementAddColorStopsCaptures`), gfx_filter's `update_result_map` / `resolve_input_filter` (over
  `SvgFilterElementGfxFilterState`), `to_compositing_and_blending_operator`, `convert_channel_selector`, the turbulence
  `type` and `tile_stitch_size`, the color matrix's number parsing; `parse_mix_blend_mode`,
  `parse_compositing_operator`; `value_for_character` (which compares the list's address, as `&values == &x`),
  `resolve_value`; the use element's document-completely-loaded and fetch callbacks; the image element's animation
  timer and fetch callbacks (captures allocated with `new`); the feImage fetch callback.
- `Optional<Gfx::Filter const&>` arguments are a pointer to a local copy (`svg_filter_ref`).
- `DisplayListPlayerSkia` in `render_to_surface` is the CPU player (DESIGN §7.3).
- The engine follow-ups of luce-js `HANDOFF.md` §5 item 4 were all done by earlier regions.
- **Candidates to share with luce-svg later** (self-contained SVG algorithms here): the gradient paint transform and
  the href-chain attribute inheritance of gradients and patterns, the pattern tile computation, `TextPositioning`
  (per-character x/y/dx/dy), the filter primitive graph (`gfx_filter`: in/in2/result resolution, SourceAlpha,
  feDropShadow as blur+offset+flood+composite+merge, the feColorMatrix value parsing and type matrices).

## Tests

- **web_test** (Ladybird's Layout/Ref/Crash tests): Layout **819 → 837** of 845, Ref **432 → 462**, Crash **32 → 36**;
  `tests/expected_failures` rewritten with `--update-failures` (52 tests removed; the SVG tests still failing need P2
  fetching, P4 animations or MathML). All 19 Layout tests that stopped at r56's constructors pass except
  svg-use-element-crashtest (it fetches another document).
- **`svg/tests_svg_ii`** (20 cases, 4 tests) from the local oracle `luce-browser-tools/oracles/luce-browser-engine/svg_elements`
  extended for r56 (`own_r56_cases.py` writes `cases_r56.txt`; `./oracle cases_r56.txt > expected_r56.txt`;
  `python3 gen_luce_cases.py r56 > svg/tests_svg_ii_cases.lucb`; oracle.cpp's new modes grad, pattern, maskclip, fe,
  use, text, a, image, fo): gradient units/spread/transform/geometry and stops through href and xlink:href chains
  (cycles, self references, missing and non-gradient targets, invalid values), patterns and their content element,
  mask/clip units and active viewBoxes and the masking area, every filter primitive's reflections (blend modes,
  color matrix types, composite operators and k1–k4, channel selectors, stdDeviation pairs and `setStdDeviation`'s
  float formatting, morphology operators, turbulence enums), use elements (symbol/svg width and height override, x/y
  transform, the instance root and shadow tree, invalid and circular references, removal of the referenced element),
  text positioning (numbers, lengths, percentages; the reflected lists), textPath targets, `<a>`'s target/relList,
  image bounding boxes. All match.
- **`layout/tests_layout_svg`** (oracle `layout_geometry`): the 19 SVG cases r49 marked for r56 are unmarked (`own_svg_cases.py`),
  except svg-use-element-crashtest (P2) and svg/foreignObject-with-mask (its `<style>` element asks the unit harness's
  document for a CSP list it does not have, as r49's details cases; web_test passes it; unmarked by the P1 polish,
  whose harness documents are in a Window's realm); 18 new cases (layout and
  svg modes) for masks and clip paths in both unit systems, use/symbol, text/tspan/text-anchor, textPath,
  foreignObject, patterns and gradients, filters and `<a>`. 89 cases, all match.
- **`painting/tests_paint_recording`** (oracle `paint_recording`): documents svg-gradients, svg-pattern, svg-mask-clip,
  svg-use, svg-filters (flood/offset/merge, saturate, matrix, arithmetic composite, dilate, hueRotate, component
  transfer) and svg-text. Display lists exact; pixels exact except svg-gradients (≤ 2 levels on 3107 pixels, allowed 3 on 3600 for x86-64: the CPU
  player's gradient evaluation against Skia's, a render follow-up).

## Found in other packages

- **luce-browser-foundation `ak` float formatting** (`convert_to_decimal_exponential_form_f32` /
  `shortest_decimal_form`, used by `Formatter<float>`): an f32 whose shortest round-trip digits are an exact tie is
  rounded up where AK's dragonbox rounds to even: `128.328125f` prints `128.32813` (AK: `128.32812`), `264.640625f`
  `264.64063` (AK: `264.64062`). Seen in a Rect<float> bounding box of the SVG layout test (worked around by moving the
  case's text off the tie); a Layout dump of such a value would differ too. **Fixed** in the P1 polish (ak rounds ties
  to even); the case's text is back on the tie (`x="290"`).