dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r42.md
# Region r42: media queries, @supports, container queries and style invalidation — what other regions need to know
Region r42 ports `CSS/BooleanExpression`, `ContainerQuery`, `MediaQuery`, `MediaQueryList`,
`Preferred{ColorScheme,Contrast,Motion}`, `Screen`, `Supports`, `VisualViewport`, `InvalidationSet`,
`StyleInvalidation`, `StyleInvalidationData`, `StyleSheetInvalidation` and every file of
`CSS/Invalidation/`. The stub fragment `stubs/stub_r42_css_media_invalidation.lucb` is gone; all of its
289 functions are ported (the template `rule_lists_are_equal_ignoring_order` as its two instantiations).
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/boolean_expression` | `BooleanExpression.cpp` + `.h`: MatchResult's operators, the expression nodes |
| `css/container_query`, `css/supports` | `ContainerQuery.cpp/.h`; `Supports.cpp/.h` with its five tests (Declaration, Selector, FontTech, FontFormat, Env) |
| `css/media_query`, `css/media_query_list` | `MediaQuery.cpp/.h` (MediaFeatureValue, MediaFeature, MediaQuery); `MediaQueryList.cpp/.h` |
| `css/preferred_color_scheme`, `preferred_contrast`, `preferred_motion` | the three `Preferred*.cpp` |
| `css/screen`, `css/visual_viewport` | `Screen.cpp/.h`, `VisualViewport.cpp/.h` |
| `css/invalidation_set`, `css/style_invalidation` | `InvalidationSet.cpp/.h` (+ Traits and Formatters); `StyleInvalidation.cpp/.h` |
| `css/style_invalidation_data_1`, `_2` | `StyleInvalidationData.cpp` 1-329 (rules, plans, groups, :has() metadata), 321-587 (building the sets of a selector) |
| `css/style_sheet_invalidation_1`, `_2` | `StyleSheetInvalidation.cpp` 1-381 (targeted sets, anchor rules, applying them), 383-641 (owners, @keyframes, shadow-root effects) |
| `css/invalidation/*` | one fragment per `CSS/Invalidation/*.cpp` (adopted sheets, attributes, custom elements, element states, embedded content, form controls, :has() feature collector and invalidator, the set matcher, language, links, media queries, nodes, parts, pseudo-class states, slots, structural mutations, StyleInvalidator) |
| `css/tests_media_invalidation_cases`, `tests_media_invalidation`, `_2`, `_3` | tests (Ladybird has none for these files) |
## What other regions must know
### The paths that run now
- **Every DOM mutation** (`Node::invalidate_style`, r15/r17), **every attribute change**
(`invalidate_style_after_attribute_change`, r16/r22), **every createElement**
(`invalidate_style_after_custom_element_state_change`) and the element-state invalidators.
- **Building a rule cache** (`build_invalidation_sets_for_selector`, r39): with the user-agent sheets in place
the whole `StyleScope::build_rule_cache` runs, `@media` blocks included.
- **Style sheet mutations** (`invalidate_style_for_style_sheet_owners`, `determine_shadow_root_stylesheet_effects`,
`invalidate_owners_for_inserted_style_rule`): r37's 21 waiting `css_sheets` cases are on and pass.
- **MediaQuery/MediaFeature** for the parser (r31), `MediaList` (r37) and the UA sheets; `@supports` and
`@container` conditions; `Document::update_style`'s `invalidate_style_for_pending_has_mutations` and
`StyleInvalidator::invalidate`.
### Where paths stop (other regions' stubs)
- A media feature evaluated in a document **with a Window** reaches r28's `Window::query_media_feature`, and any
comparison of lengths, ratios, resolutions or integers reaches `Length::ResolutionContext::for_document`
(the document's FontComputer). Without a Window every feature is false (the C++ FIXME), as in the tests.
- `Screen` reaches r28's Page and Window accessors; `Screen::orientation` the phase-3 closure stub
`css_screen_orientation_create` (ScreenOrientation is opaque, so `Screen::visit_edges` cannot visit it yet).
- `VisualViewport::zoom` needs the document's navigable (r28).
- The **HTML parser end to end** (r21's scenario list) still stops in r26/r27: the parser creates `<html>`
first, and `HTMLHtmlElement`'s constructor (like div, span, p, body, head) is a stub; fragment parsing too.
The bindings' `setAttribute` stops in TrustedTypes (phase-3 closure stub); `Element::set_attribute_value` runs.
- `StyleSheetList::add_sheet` (and `CSSStyleSheet::add_owning_document_or_shadow_root`) load fonts (r41): the
tests attach author sheets by hand, as the oracle does.
### Signatures changed from the stubs (C++ `T const&` is `const T*`, DESIGN §2.2)
- `css_build_invalidation_sets_for_simple_selector(selector: const CssSelectorSimpleSelector*, ...)`;
`css_selector_may_match_light_dom_under_shadow_host_css_selector(selector: const CssSelector*)`;
`css_invalidation_element_matches_any_invalidation_set_property(element, set: const CssInvalidationSet*)`;
`css_style_invalidator_enqueue_invalidation_plan(this, node, reason, plan: const CssInvalidationPlan*)`;
`css_has_mutation_feature_collector_construct(this, data: const CssStyleInvalidationData*)`;
`css_invalidation_subtree_has_feature_used_in_has_selector(node, style_scope: const CssStyleScope*)`.
`css_invalidation_plan_include_all_from` and `css_invalidation_set_include_all_from` keep the by-value `other`
(r39 calls them so).
- `css_for_each_consecutive_simple_selector_group(selector) -> CssConsecutiveSimpleSelectorGroups` is the
template's callback walk as an iterable of `CssSimpleSelectorGroup` (DESIGN §2.9);
`css_invalidation_set_properties(set)` is `for_each_property` as an iterable (the Function form is ported too).
- `invalidate_style_after_pseudo_class_state_change_impl[T]` has one type parameter (the slot and the new state
are one type); `element_matches_anchor_rule` takes the anchor fields both rule kinds share.
- Internal-linkage and private C++ functions are module-private.
- New public helpers: `css_boolean_expression_set_class` (the vptr of a BooleanExpression subclass),
`css_invalidation_set_clone` (a set owns a HashTable: clone where C++ copies and the copy changes),
`css_invalidation_pseudo_class_property`, `css_invalidation_set_property_eq`,
`css_invalidation_set_property_traits_hash`, `css_invalidation_set_property_format`, `css_invalidation_set_format`.
### Types filled or fixed by hand
- `types_supports`: `Supports::Declaration`, `Selector`, `FontTech`, `FontFormat` (opaque, r30b) and the new
`Supports::Env` are BooleanExpressions with class ids 8-12; `types_boolean_expression`: BooleanExpression's
range is now 0-12 (the skeleton should give them ids when it is next run with them in scope).
- `types_media_query`: `MediaQuery::init_fields` sets the default media type (`all`).
- `types_style_invalidation_data`: `ExcludePropertiesNestedInNotPseudoClass` is a bool enum (`yes = 1`, the
skeleton read -1 as i64); the group iterator types.
- `types_style_sheet_invalidation`: the two anchor rules of `StyleSheetInvalidationSet`.
- `invalidation/types_style_invalidator`: `PendingDescendantInvalidation { reason, rule }`.
- `types_invalidation_set`: the property iterator; `generated/types_traits`: `CssInvalidationSetPropertyTraits`
forwards to the ported hash and equality.
## Deviations and notes
- Expressions, media queries, plans and Supports are managed blobs (`alloc`/`new`), constructed by the ported
constructors; lambdas are private functions with capture structs; `ScopeGuard`s are `defer`s; non-escaping
traversals are loops.
- Copies that C++ makes of containers that are changed later are clones: a rule appended to a plan
(append_or_merge_*), the pending :has() mutation map that `invalidate_style_of_elements_affected_by_pending_has_mutations`
copies (its feature tables too).
- Donor quirks kept: `Formatter<InvalidationSet>` never clears `first`, so it writes no separator;
`Supports::Env::to_string` serializes as `font-format(...)`.
## Tests
- `tests_media_invalidation_cases` (195 cases; the four font-tech()/font-format() cases are on since r41 merged) + `tests_media_invalidation`,
`_2`: a local oracle (`luce-browser-tools/oracles/luce-browser-engine/media_invalidation`: `oracle.cpp` links
the reference build's LibWeb objects, makes a Page with its own PageClient and a top-level traversable, and
documents without a Window in its realm; `cases.txt`, `build.sh`, `gen_luce_cases.py`). Modes: media query
lists (serialization, to_string, evaluation, dump), `@supports`, `@container`, the StyleInvalidationData of
selector lists (every plan, recursively, and the :has() metadata), the StyleSheetInvalidationSet of sheets,
`selector_may_match_light_dom_under_shadow_host`, `compute_property_invalidation` of parsed values, and 39
invalidation outcomes: a tree built with create_element/set_attribute_value/append_child in an HTML document,
an author sheet, the real rule cache (the four UA sheets with their @media blocks), the selector involvement
metadata collected by matching, then attribute, insertion and removal mutations and the invalidations
`update_style` performs, printing which nodes need a style update. All match.
- `tests_media_invalidation_3`: Kleene logic, expression nodes and class ids, MediaFeature::compare,
MediaQueryList, the Preferred* strings, VisualViewport, InvalidationSet / InvalidationPlan (equality ignoring
rule order, merging without shared tables), RequiredInvalidationAfterStyleChange, reasons, and a scenario
through `Document::createElement`, `appendChild`, an attribute and `classList.add`.
- The test documents' pages (r17's `test_document_page`) live outside the heap, so a collection that reaches
them traps or crashes (Page::visit_edges is r28's; the heap reads a block header that is not there). Tests that
allocate enough to collect run under DeferGC and drop the held-back collection
(`test_media_invalidation_end_defer_gc`).
- `css/tests_css_sheets_cases`: r37's 21 insertRule/deleteRule/addRule/selectorText cases are enabled.
## Compiler issues
None found. (Language limits met: `let x = f() else:` with a block does not exist, written as `if x == none`;
`new` and `from` are reserved words.)