dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r55.md
# Region r55: SVG I — what other regions need to know
Region r55 ports the SVG DOM's core: `SVG/AttributeNames`, `AttributeParser` (path data, transforms,
numbers, lengths, viewBox, preserveAspectRatio, units, spreadMethod, tableValues, points), `Path`
(instructions, serialization, `to_gfx_path`), `SVGElement`, `SVGGraphicsElement`, `SVGGeometryElement`,
`SVGSVGElement`, `SVGFitToViewBox`, `SVGViewElement`, the shapes (`rect`, `circle`, `ellipse`, `line`,
`polyline`, `polygon`, `path`), `g`, `defs`, `desc`, `title`, `metadata`, `style`, `script`,
`SVGURIReferenceMixin`, `SVGComponentTransferFunctionElement`, the value types (`SVGLength`, `SVGNumber`,
`SVGTransform`, `SVGList<T>` and its three lists) and, as the brief assigns "animated values", the nine
`SVGAnimated*` classes (which `regions.tsv` had put in r56). The stub fragment `stubs/stub_r55_svg_1.lucb` is
gone (all 344 functions ported); the 63 `SVGAnimated*` functions left `stubs/stub_r56_svg_2.lucb`.
`SVG/TagNames` was already ported by r21; `SVGUnitTypes` has no functions.
## Fragments (in `svg/` unless noted)
| Fragment | Donor |
| --- | --- |
| `attribute_names` | `AttributeNames.cpp` + `.h` (`svg_attribute_names_initialize_strings`, run by `web_initialize_strings`) |
| `attribute_parser_1`, `attribute_parser_2` | `AttributeParser.cpp` 1-302 / 304-833 + `.h` inlines (NumberPercentage, match/done/ch/consume) |
| `path` | `Path.cpp` + `.h` |
| `svg_element` | `SVGElement.cpp` + `.h` (the presentation attribute table is a C-heap module global, DESIGN §3.3 rule 7) |
| `svg_graphics_element`, `svg_geometry_element`, `svg_svg_element`, `svg_fit_to_view_box`, `svg_view_element` | the matching files |
| `svg_circle_element`, `svg_ellipse_element`, `svg_line_element`, `svg_path_element`, `svg_polygon_element`, `svg_polyline_element`, `svg_rect_element` | the shapes |
| `svg_g_element`, `svg_defs_element`, `svg_desc_element`, `svg_metadata_element`, `svg_title_element`, `svg_style_element`, `svg_script_element`, `svg_uri_reference`, `svg_component_transfer_function_element` | the matching files |
| `svg_length`, `svg_length_list`, `svg_list`, `svg_number`, `svg_number_list`, `svg_transform`, `svg_transform_list` | the value types |
| `svg_animated_{enumeration,integer,length,length_list,number,number_list,rect,string,transform_list}` | `SVGAnimated*.cpp` + `.h` |
| `geometry/dom_rect` | `Geometry/DOMRectReadOnly.cpp` 18-52 and `DOMRect.cpp` 16-54 + accessors (see below) |
| `tests_svg_cases`, `tests_svg`, `tests_svg_2` | tests (below) |
## What other regions must know
### Constructing SVG elements (r16's factory, r56's elements)
- `svg_element_construct` runs Element's constructor and points the four mixin tables (`slottable_mixin`,
`aria_mixin`, `animatable`, `global_event_handlers`, whose `class_id` is the cell's) at SVGElement's.
Every subclass constructor calls its base's and then moves the four tables to its own generated
`svg_<class>_*_vtable`s, as `svg_rect_element_construct` does; `SVGSVGElement` and `SVGViewElement` also
set `svg_fit_to_view_box.vtable`/`.class_id`, `SVGStyleElement` its `style_element_base`.
`SVGGraphicsElement`'s constructor sets `m_transform` to the identity (`= {}` in C++; zeroed memory is not).
- r56: `svg_graphics_element_construct` / `svg_element_construct` / `svg_element_initialize_impl` /
`svg_graphics_element_initialize_impl` / `svg_element_visit_edges_impl` are the `Base::` calls.
`svg_graphics_element_resolve_url_to_element` (private) is the C++ `resolve_url_to_element`; the template
`try_resolve_url_to<T>` is it followed by `as_if_<T>` at each call site.
### Signature and type changes
- `svg_list_visit_edges[T](this, visitor, visit_item: func(gc.CellVisitor*, T) -> unit)`: a generic body
cannot visit a `T`, so each list passes its item visitor. `svg_list_items[T]` answers `const T[]` (the stub
had `void*?`).
- `svg_svguri_reference_mixin_href(this, element: SvgElement*, supports_xlink_href: SvgSupportsXLinkHref)`:
the mixin sits at a class-specific offset (the C++ `as<SVGElement>(*this)`), and the template parameter is
a parameter. r56's users of the mixin (a, image, use, gradients, patterns, feImage) call it so.
- `svg_animated_rect_set_base_val` / `_set_anim_val` take a `GeometryDoubleRect` (`Gfx::DoubleRect`, which
gfx does not instantiate; the stubs had the opaque `gfx.Rect`).
- `svg_graphics_element_try_resolve_url_to[T]` is gone (see above).
- `types_svgsvg_element`: `m_cached_width_style_value_set` / `m_cached_height_style_value_set` (the outer
layer of `Optional<RefPtr<StyleValue const>>`, as r28's `m_pending_prompt_response_set`).
- `geometry/types_dom_rect_read_only`, `types_dom_rect` (generated opaque) are filled: DOMRectReadOnly is a
PlatformObject with `m_rect: GeometryDoubleRect`, DOMRect embeds it. Like LibJS's phase-1 stand-ins they
have no class id of their own (PlatformObject's, 6) and are recognized by their ClassInfo
(`is_geometry_dom_rect[_read_only]`). Ported: creation, construction, initialize, x/y/width/height (r18's
closure stubs, which take a `GeometryDomRect*`), the setters. Needed because every `<svg>` and `<view>`
creates an SVGAnimatedRect, whose initialize makes two DOMRects. from_rect, the edges and serialization
are phase 3.
- Closure stubs added (`stubs/stub_closure.lucb`, namemap rows): `geometry_dom_point_read_only_create`,
`geometry_dom_point_from_point(vm)` (the default, all-zero DOMPointInit), `geometry_dom_point_construct_impl`
— all `unported (P3)`, reached only by stubbed SVG DOM getters.
- Private (C++ private / `static`): the parser's members, `svg_whitespace`, `svg_to_svg_fill_rule`,
`svg_normalized_diagonal_length`, `svg_parse_type`, `svg_attribute_style_properties`,
`svg_element_update_use_elements_that_reference_this`, `_remove_from_use_element_that_reference_this`,
`svg_rect_element_calculate_used_corner_radius_values`, the SVGSVGElement fallback viewBox update and
`active_view_element`, the script element's fetch/execute steps, `svg_animated_*_parse_value_or_initial` /
`_get_base_or_anim_value`, `svg_animated_enumeration_base_or_anim_value`.
### Where paths stop (other regions' stubs)
- **r49**: `Layout::SVGSVGBox::SVGSVGBox` is now the first trap of 55 web_test inputs (32 Layout), then the
SVGFormattingContext and the other SVG boxes. Not a small piece: left to r49.
- **r56**: the SVGText/Mask/ForeignObject/Symbol/Use/Filter/Image/A elements' constructors (and SVGUseElement's
`svg_element_changed`/`_removed`, which SVGElement calls for referenced elements with an id in a completely
loaded document).
- **r53**: SVG paintables (`get_b_box` reads `SVGGraphicsPaintable::computed_transforms`).
- **r13b**: `ARIAMixin::role_from_role_attribute_value` (SVGElement's default role of `g`, `foreignObject`,
`image`, `circle`, `ellipse`, `path`, `polygon`, `polyline` asks `should_include_in_accessibility_tree`).
- **P3**: running scripts (SVGScriptElement stops at "scripting is disabled"), DOMPoint/DOMMatrix.
## Deviations and notes
- **Donor quirks kept**: `parse_coordinate_sequence` VERIFY-fails (traps) on a non-first coordinate that does
not parse (`H 10 , ,`); the presentation attribute `NamedPropertyID(R, { circle })` picks the (id, name)
constructor, so the attribute named `circle` maps to `r` on every SVG element and `r` is only circle's own
hint (checked against the reference build); SVGAnimatedTransformList's baseVal answers the animated list;
the length and number lists answer the base list for animVal.
- C++ lambdas are functions: parse_transform's `consume_whitespace`, `consume_comma_whitespace`,
`parse_optional_number`, `try_parse_number`, and `parse_function`'s six bodies as one function over the
transform function (`SvgAttributeParserTransformFunction`); preserveAspectRatio's `align`; SVGElement's
`make_length`; `negotiate_natural_metrics`' aspect ratio; the component transfer `to_u8`
(`AK::clamp_to<u8>`); the external script's `process_response_consume_body` (captures `[self, script_url]`
allocated with `new`).
- `PathInstruction::dump`'s dbgln lines are built with `ak.format_f32` (AK's float formatting);
`AK/Debug.h`'s PATH_DEBUG is the private constant `svg_path_debug` (false).
- `HTMLParser`'s `ClassicScript::create` takes no source line number (the port's signature); SVGScriptElement
passes none.
- The engine follow-ups of luce-js `HANDOFF.md` §5 item 4 were all done by earlier regions.
## Tests
- web_test (Ladybird's Layout/Ref/Crash tests): Layout 727 → 727 of 845, Ref 388 → 388, Crash 28 → 28 (the
SVG tests moved from `SVGSVGElement::SVGSVGElement` to r49's and r56's constructors);
`build/web_test layout -f '*svg*'`: 45 tests, 0 pass before and after (45 traps at SVGSVGElement before; 26
at SVGSVGBox, 19 at r56's elements after). `tests/expected_failures` rewritten with `--update-failures`
(only the trap notes changed).
- `svg/tests_svg_cases` (195 cases) + `svg/tests_svg` (7 tests), from the local oracle
`luce-browser-tools/oracles/luce-browser-engine/svg_elements` (`build.sh`, `cases.txt`, `oracle.cpp` linked
with the reference build's LibWeb objects, `./oracle cases.txt > expected.txt`,
`python3 gen_luce_cases.py > svg/tests_svg_cases.lucb`). Floats are compared as bits, exactly on macOS and
within 64 ulps elsewhere (transforms and arcs use libm). Modes: every AttributeParser entry point (75
inputs, including edge cases: exponents, signs, overflow, junk, whitespace), transform lists and their
matrices (20), path data — instructions, serialization and the Gfx::Path's SkPath verbs, points and conic
weights (29, among them every command, relative/absolute, smooth curves, arcs and flags without
separators), the shapes' paths at a 300×150 viewport (19), `<svg>`'s viewBox, preserveAspectRatio, active
viewBox, width/height style values and natural metrics (9), transform attributes (5), presentation
attributes (7), roles (2; 6 more wait for r13b), animated lengths (3), href/className (3), component
transfer functions with their color tables (11), SVGAnimatedNumber/Integer reflection with second values
(12). All match.
- `svg/tests_svg_2` (4 tests): SVGList's operations and IndexSizeError/NoModificationAllowedError,
SVGLength/SVGNumber setters, SVGAnimatedEnumeration's TypeError, the factory's SVG classes and their mixin
tables, ownerSVGElement/viewportElement, the viewBox reflection (nulled while absent or invalid), the
active `<view>`, and a full collection with the lazily made animated values alive.
- Not covered by unit tests: SVGTitleElement's title change (needs a page with a top-level traversable), a
connected SVGStyleElement (needs a window for the CSP check), `circle`'s path and `get_b_box` (need a layout
node: r49).
## Compiler issues
None filed. A runtime pitfall met while porting (not a compiler bug): a `StringView` of a *short* `ak.String`
points into the String value itself, so a helper that returns `string_bytes_as_string_view(©)` of a local
copy dangles; bind the String in the caller.