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"`).