Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r26.md

# Region r26: HTML structure elements and image data — what other regions need to know

Region r26 ports the structural HTML elements (`base`, `dl`, `details`, `dialog`, `dir`, `img`,
`li`, `link`, `menu`, `meta`, `ol`, `picture`, `slot`, `source`, `style`, `summary`, the seven table
elements, `template`, `title`, `ul`) and the image machinery behind `<img>`: `DecodedImageData`,
`AnimatedDecodedImageData`, `ImageRequest`, `SharedResourceRequest`, `ListOfAvailableImages`,
`SourceSet` and `CORSSettingAttribute`. The stub fragment `stubs/stub_r26_html_structure.lucb` is gone;
all 410 of its functions are ported.

## Fragments (in `html/`)

| Fragment | Donor |
| --- | --- |
| `animated_decoded_image_data`, `cors_setting_attribute`, `decoded_image_data`, `image_request`, `list_of_available_images`, `shared_resource_request`, `source_set` | the matching `.cpp` + `.h` |
| `html_base_element`, `htmld_list_element`, `html_details_element`, `html_dialog_element`, `html_directory_element`, `html_menu_element`, `html_meta_element`, `htmlo_list_element`, `html_picture_element`, `html_slot_element`, `html_source_element`, `html_style_element`, `html_summary_element`, `html_table_caption_element`, `html_table_col_element`, `html_table_element`, `html_table_section_element`, `html_template_element`, `html_title_element`, `htmlu_list_element` | the matching `.cpp` + `.h` |
| `html_image_element_1` / `_2` / `_3` | `HTMLImageElement.cpp` (+ BatchingDispatcher) |
| `html_link_element_1` / `_2` | `HTMLLinkElement.cpp` (construction, attributes, link options, fetch / the link types, processing fetched resources, favicons) |
| `htmlli_element` | `HTMLLIElement.cpp` + two helpers the list and table elements share (below) |
| `html_table_cell_element` | `HTMLTableCellElement.cpp` + two shared table helpers (below) |
| `html_table_row_element` | `HTMLTableRowElement.cpp` + `html_table_optional_element_node` |
| `tests_html_structure_cases`, `tests_html_structure`, `tests_html_structure_2` | tests |

## What other regions must know

### Document::create completes

`Document::initialize` creates its `ListOfAvailableImages`; `dom_document_create(realm, url)` now runs
to the end. `page/tests_page`'s `web_test_create_document` uses it (then sets the document type), and
its stop test asserts the stops after it (r28, r27's CustomElementRegistry closure stub).

### Shared helpers (pub, for the elements' presentational hints)

- `dom_element_attribute_span(element) -> DomAttr*[]` — the element's attributes as a span
  (`for_each_attribute`).
- `html_list_style_type_counter_style(name) -> CssStyleProperty` — `list-style-type` with a
  CounterStyle value (li/ol/ul `type`).
- `html_table_background_image_value(url)` — the `background` hint's image value.
- `html_document_parsing_params(document) -> CssParsingParams`.
- `html_table_optional_element_node(element?) -> DomNode*?`.

### What runs in phase 1 and what traps

- **`<style>`**: detached elements run everything. Once connected, `update_a_style_block` reaches
  `should_elements_inline_type_behavior_be_blocked_by_content_security_policy` (r19's closure stub; it
  needs r28's Window/policy container) — so parsing a document with a `<style>` traps there. Past
  that check the sheet applies: `tests_html_structure_2` makes the block's sheet as step 6 does and
  r39's cascade picks up its rules (`color`, `margin-left`); `disabled` and `media` work on the sheet.
  The same check stops a connected `<details>` (its shadow tree's `<style>`).
- **`<link>`**: rel/relList/sizes/type/media and the link options run; fetching is P2 closure stubs
  (fetch request setters, preload entries, FetchControllerHolder, `ResourceLoader`, `Core::Promise<bool>`).
- **`<img>`**: attributes, `complete`, `currentSrc`, source selection (`select_an_image_source`,
  srcset/sizes/picture/media/type) run; `update_the_image_data` waits for a fully active document
  (test documents have no browsing context, so it registers the document observer and returns).
  **`HTMLImageElement::visit_edges` reaches r43's `ImageProvider::image_provider_visit_edges` stub**: a
  collection of a heap that holds an `<img>` traps until r43 lands.
- `SharedResourceRequest::get_or_create` reads the settings object's responsible document (a
  Window's, r28); single-frame decodes call `BitmapDecodedImageData::create` (closure stub);
  streamed animated decodes create `AnimatedDecodedImageData` and run.
- `background=` hints on tables/cells and `<base href>` read the document's base URL
  (`url_matches_about_srcdoc`, r28); `<meta name=referrer>` reaches r28's policy container.
- `li`/`td`/`th` roles go through r13b's `aria_mixin_role_or_default` stub.

### Signature and type changes

- `types_list_of_available_images`: `Key` filled (`url`, `mode`, `origin: web_url.Origin?`,
  `cached_hash: u32?`), `Entry` (`image_data`, `ignore_higher_layer_caching`); the generated
  `HtmlListOfAvailableImagesKeyTraits` (`generated/types_traits`) forwards to the key's hash/==.
- `types_shared_resource_request`: `Callbacks` holds `gc.Function0[unit]*?` on_finish/on_fail.
- `types_image_request`: `init_fields` sets `m_current_pixel_density = 1.0`.
- `types_html_image_element`: `HtmlBatchingDispatcher.m_queue` is
  `ak.Vector[gc.Root[gc.Function0[unit]]]` (the dispatcher is a static outside the heap).
- `types_html_link_element`: `LinkProcessingOptions` filled as a JS::Cell outside the generated
  hierarchy (class id 1, with its vtable and class info).
- `html_for_each_element_in_details_name_group` is private and not generic: it takes an
  `ak.Function1[HtmlDetailsElement*, TraversalDecision]` and the name as `ak.String`.

### Closure stubs added (`stubs/stub_closure.lucb`, with namemap rows)

CSP (`is_base_allowed_for_document`, `Policy::parse_a_serialized_csp`, `remove_directive`,
`set_self_origin`, `PolicyList::from_object`, `enforce_policy`, the PolicySource/Disposition enums),
`CloseWatcher::request_close`, `BitmapDecodedImageData::create` + its `Frame`, Fetch request
initiator/priority (enums, setters, `priority_from_string`), and the HTMLLinkElement block listed in
the previous section. Ported whole into the closure: `is_a_global_custom_element_registry` (fragment
parsing needed it) and `ReferrerPolicy::from_string`.

## Deviations

- `ListOfAvailableImages::Key::hash` does not cache into `cached_hash` (the traits hand a const key);
  the value is the same.
- `SourceSet::select_an_image_source` finds the first source of each density with a linear scan
  instead of a `HashMap<double>` (same result).
- `HTMLImageElement::handle_successful_fetch` is declared but never defined in the donor: not ported.
- `AnimatedDecodedImageData`'s session registry and the BatchingDispatcher keep their storage in the
  C heap (module globals are not scanned); the registry holds raw pointers that `finalize` removes,
  as in C++.
- `PreloadEntry` stays opaque behind accessor closure stubs.
- Donor quirks kept: `HTMLSlotElement::assign` step 3.1 removes the node from *this* slot's manually
  assigned nodes (not the old slot's); the dialog's no-source check reads `current_url`;
  `insert_row`'s `last_child_of_type<HTMLTableRowElement>` on "tbody".

## Tests

- `tests_html_structure` (oracle `luce-browser-tools/oracles/luce-browser-engine/html_structure/`,
  the reference build linked as r30b's css_parser oracle): srcset parsing, image source selection,
  CORS states and credentials modes, available-image key hashes, table rows/sections/cells, table
  insert/delete operations and their exceptions, ol/li values, document title, meta http-equiv.
  Waiting (`!`): details exclusivity (CSP check) and `<meta name=referrer>` (r28).
- `tests_html_elements` (r27's harness, oracle `html_elements/`): r27's 34 waiting cases now on
  (tables, lists, template, title/meta/link/base, img, details/dialog/slot and every fragment case),
  plus r26 documents, fragments, presentational hints and roles. Still `!`: the `<details>` and
  `<style>` documents (CSP check), `background=` hints (r28 base URL), li/td/th roles (r13b).
- `tests_html_structure_2`: element classes and mixin tables; the `<style>` cascade scenario;
  AnimatedDecodedImageData under a test ImageCodecPlugin (pool, frame requests, delivery, failed
  decode, finalization); the list of available images (keys, entries, keeping data alive);
  ImageRequest and SharedResourceRequest (callbacks, a streamed decode); template contents and
  cloning; slot manual assignment; dialog/summary; link rel keywords; img state before a fetch;
  title text; a collection over a tree of r26 elements.

Found on the way (not this repository): AK's `HashTable::delete_bucket` leaves the freed bucket's
bytes in place, and the collector scans HashMap storage conservatively, so a value removed from a
HashMap can stay alive until its slot is reused (seen with `ListOfAvailableImages::remove`).

No compiler issues.