dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r27.md
# Region r27: the remaining HTML elements — what other regions need to know
Region r27 ports the ~40 HTML element classes no other region owns: `HTMLHtmlElement`, `Head`, `Body`,
`Div`, `Span`, `Paragraph`, `Heading`, `Pre`, `BR`, `HR`, `Font`, `Data`, `Time`, `Param`, `Mod`,
`Quote`, `Anchor`, `Area`, `Map`, `Marquee`, `FrameSet`, `Frame`, `IFrame`, `Embed`, `Object`,
`Canvas`, `Script`, `Media`, `Audio`, `Video`, `Track`, `HTMLDocument` and `MediaControls` (with the
generated MediaControls DOM). The stub fragment `stubs/stub_r27_html_elements_rest.lucb` is gone;
all 453 of its functions are ported (`create_webgl_context<T>` as its two instantiations).
## Fragments (in `html/` unless noted)
| Fragment | Donor |
| --- | --- |
| `html_data_element`, `html_span_element`, `html_time_element`, `html_param_element`, `html_head_element`, `html_mod_element`, `html_quote_element`, `html_pre_element`, `html_paragraph_element`, `html_heading_element`, `html_html_element`, `html_br_element`, `html_hr_element`, `html_font_element`, `html_body_element`, `html_map_element`, `html_marquee_element`, `html_frame_set_element`, `html_frame_element`, `html_iframe_element`, `html_embed_element`, `html_anchor_element`, `html_area_element`, `html_document` | the matching `.cpp` + `.h` inlines |
| `html_div_element` | `HTMLDivElement.cpp` + the presentational-hint helpers the region shares (`html_append_presentational_hint`, `_keyword_hint`, `_px_hint`, `html_name_is(_one_of)`, `html_value_is_ignoring_case`) |
| `html_script_element_1` / `_2` | `HTMLScriptElement.cpp` 1-643 / 644-876 + `.h` |
| `html_canvas_element_1` / `_2` | `HTMLCanvasElement.cpp` 1-263 / 265-508 |
| `html_object_element_1` / `_2` | `HTMLObjectElement.cpp` 1-232 / 233-621 + `.h` |
| `html_media_element_1` … `_6` | `HTMLMediaElement.cpp/.h` (+ SourceElementSelector) |
| `html_audio_element`, `html_video_element`, `html_track_element` | the matching files |
| `media_controls_1` / `_2` | `MediaControls.cpp/.h` |
| `generated/html/media_controls_dom` | written by `tools/gen_dom_tree` (port of `Meta/Generators/generate_dom_tree.py`) from `data/html/MediaControls.html` + `.css`; `test.sh` regenerates and compares it |
| `tests_html_elements_cases`, `tests_html_elements`, `tests_html_elements_2`, `tests_html_media` | tests |
## What other regions must know
### The HTML parser runs end to end (r21, r57)
`html_parser_create(document, input, .disabled, "UTF-8")` + `html_parser_run_url` on a
`web_test_create_document(realm, .html)` document builds the DOM: 41 whole documents (doctypes, quirks,
comments, implied tags, adoption agency, misnested formatting, headings, pre, hr/br, frameset, script,
noscript with scripting disabled, character references, plaintext, stray end tags, attribute
merging into html/body) match the reference build's html5lib dumps. Still waiting (`!` in the oracle's
cases.txt; enable them when the region lands):
- **r26**: tables (and foster parenting), lists, `<template>`, `<title>`/`<meta>`/`<link>`/`<style>`/
`<base>`, `<img>`, details/dialog/slot; **every fragment case** (`parse_html_fragment`'s temporary
document runs `Document::initialize`, which creates a ListOfAvailableImages).
- **r24/r25**: input, button, select/option, textarea.
- **r28**: `<iframe>`, `<frame>`, `<object>` (NavigableContainer's constructor), `<canvas>`
(`Page::register_canvas_element`), and **any `href`** on `<a>`/`<area>` (setting the URL reads the
document's base URL: `url_matches_about_srcdoc`).
- **r55/r13b**: `<svg>`, `<math>` (their element constructors). **P3**: an inline `<script>` with text
(`prepare_the_script_text` calls TrustedTypes' `get_trusted_type_compliant_string`, a closure stub).
- **P4**: `<video>`/`<audio>`/`<track>` (initialize creates the track lists and TextTrack, closure
stubs).
### Construction
- Every class follows `html_unknown_element_construct`: base constructor, then the five mixin tables move
to the class's. `<body>`/`<frameset>` also set their WindowEventHandlers base (`vtable`, `class_id`),
`<a>`/`<area>` their HTMLHyperlinkElementUtils base, `<object>` its Layout::ImageProvider base.
- `HTMLScriptElement`'s constructor runs its member initializers (`m_result` = Uninitialized,
`m_script_text` = empty); `HTMLCanvasElement`'s sets `m_context` to `.empty` (the zeroed variant would
be a null CanvasRenderingContext2D).
- `HTMLDocument::create(realm, url)` is ported (C++'s default `about:blank` is passed by callers).
`page/tests_page` now asserts the next stop of `Document::create_and_initialize`, the
CustomElementRegistry (closure stub).
### What runs in phase 1 and what traps
- `<script>`: "prepare the script element" runs steps 1-19; a parser-inserted script with a src or a
JavaScript type is marked already started with its type set, and step 19 (scripting disabled)
returns. Steps 20-37 trap `unported (P3)`. `execute_script` is ported whole; its script runs go to
P3 closure stubs.
- `<object>`: the representation task (queued at construction when the document is fully active) takes
the fallback steps without a browsing context; the data fetch is P2 (closure stubs).
`HTMLObjectElement::visit_edges` reaches r43's `ImageProvider::image_provider_visit_edges` stub.
- `<canvas>`: everything with no context runs; the 2D/WebGL contexts, `serialize_bitmap` and
`FileAPI::Blob::create` are P4/P2 closure stubs.
- Media: see the fragments' headers — loading (P2) and playback (P4) keep the C++ structure and call the
"Region r27 media" closure stubs; `crossorigin` calls r26's `cors_setting_attribute_from_keyword` stub.
- `<a>` activation: MouseEvent's `platform_ctrl_key` / `offset_x` / `offset_y` are P4 closure stubs;
`user_navigation_involvement` is ported whole into the closure.
### Signature and type changes
- `html_canvas_element_create_webgl_context[TContextType]` → `_web_gl` and `_web_gl2` (namemap rows).
- `types_html_canvas_element`: `html_max_canvas_area` is a `let` with its value (was an unset `var`).
- Media (by the helper branch): `html_media_element_reject_pending_play_promises_utf16_string` takes a
`create_error` function instead of `[TErrorType]`; the promise spans are `const (JsPromiseCapability*)[]`;
the MediaControls `add_event_listener` stubs are non-generic (`HtmlMediaControlsEventType`); new
`html_media_controls_add_event_listener_mouse_event` / `_keyboard_event`, `html_media_controls_destruct`,
`html_media_controls_dom_construct`; `m_controls` is `HtmlMediaControls*?`; RemoteFetchData's,
RegisteredEventListener's and MediaControlsDOM::Options' fields filled; `supported_*_subtypes` are
`let str[N]`; `s_visible_class` is a function.
- `html_parse_a_sandboxing_directive` (r28 stub) takes `ak.KeyPath` (the generator's name for
`Variant<String, Vector<String>>`); the iframe passes `.string(value)`.
- `web_initialize_strings` interns `TrustedTypes::Script` (`trusted_types_initialize_strings`).
### Closure (`stubs/stub_closure.lucb`, namemap rows)
Sections "Declarations outside the phase-1 closure that region r27 calls" (user_navigation_involvement,
MouseEvent accessors, TrustedTypes::Script, ClassicScript/ModuleScript run, an opaque `HtmlModuleScript`,
ImportMapParseResult::register_import_map), "Canvas rendering contexts and bitmap serialization",
"Fetch statuses" (`is_ok_status`, ported whole) and the three "Region r27 media" sections (track lists,
tracks, TextTrack, TimeRanges, MediaError; LibMedia; MediaSource, blob URLs, Fetch responses,
FetchAlgorithms::create with process_response, create_potential_CORS_request, UI events).
## Deviations and notes
- ARIA's `AttributeNames` (`aria_attribute_names_*`) are never interned (r13b's), so
`HTMLHeadingElement::aria_level` reads a zero FlyString until they are.
- The ENUMERATE_WINDOW_EVENT_HANDLERS expansion of `<body>` and `<frameset>` is one function,
`html_window_event_handler_attribute_changed`, called by both.
- Lambdas: lazy-load resumption steps, toBlob's tasks and the object's fetch callbacks are capture
structs allocated with `new`; one-pointer captures (`[this]`) pass the element as the context.
- MediaControls DOM generator: a small scanner instead of `html_syntax`, and it reads the engine's
Luce tag/attribute declarations instead of the C++ headers.
## Tests
Ladybird has no unit tests for these files. `tests_html_elements` runs 135 cases of a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/html_elements`: oracle.cpp linked against the
reference build's LibWeb, cases.txt, expected.txt, gen_luce_cases.py, build.sh), generated into
`tests_html_elements_cases`: whole documents through the parser (html5lib dumps), the legacy font
size (21 inputs), presentational hints and `is_presentational_hint` (36 cases), default ARIA roles,
marquee reflection, the script elements' preparation state and `:heading(n)` through querySelectorAll (r38's waiting case: the heading levels, with sections and hgroup); 34 more cases wait for other regions.
`tests_html_elements_2` (10): the factory's class and mixin tables for 33 names, the
`is_html_*_element` virtuals, the cached heading level, body link colors and event handler targets,
`<a>`/`<area>` relList/text/download/tab index, `<map>`'s areas, marquee setters, `<script>`'s async,
supports, Range hooks, mark_as_ready, cloning and step 8, `<canvas>`'s size, bitmap limits, presenting,
getContext of an unknown type and the font computation context, HTMLDocument's construction.
`tests_html_media` (7): media/video/audio/track construction, can_play_type (16 cases), playback state,
setters' exceptions, video intrinsic/natural dimensions, adjust_computed_style, play promises and the
source selector.
## Compiler issues
None found.