Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r37.md

# Region r37: CSS style sheets and rules — what other regions need to know

Region r37 ports `CSS/CSS.cpp`, `StyleSheet`, `CSSStyleSheet`, `StyleSheetList`,
`StyleSheetIdentifier`, `MediaList`, `CSSRule`, `CSSRuleList`, every CSS rule class
(`CSSGroupingRule`, `CSSConditionRule`, `CSSMediaRule`, `CSSSupportsRule`, `CSSContainerRule`,
`CSSLayerBlockRule`, `CSSLayerStatementRule`, `CSSNamespaceRule`, `CSSImportRule`, `CSSStyleRule`,
`CSSNestedDeclarations`, `CSSPageRule`, `CSSMarginRule`, `CSSPropertyRule`, `CSSCounterStyleRule`,
`CSSFontFaceRule`, `CSSFontFeatureValuesRule`, `CSSFontFeatureValuesMap`, `CSSFunctionRule`,
`CSSFunctionDeclarations`), the declaration blocks (`CSSStyleDeclaration`, `CSSStyleProperties`,
`CSSDescriptors`, `CSSFontFaceDescriptors`, `CSSPageDescriptors`, `CSSFunctionDescriptors`,
`Descriptor`) and the generated `GeneratedCSSStyleProperties`. It also ports `CSSKeyframesRule`
and `CSSKeyframeRule` (animations, outside the phase-1 files) because the parser makes them. The
stub fragment `stubs/stub_r37_css_sheets.lucb` is gone; every one of its functions is ported.

## Fragments

| Fragment | Donor |
| --- | --- |
| `css/style_sheet`, `css/media_list`, `css/style_sheet_list`, `css/style_sheet_identifier` | `StyleSheet`, `MediaList`, `StyleSheetList`, `StyleSheetIdentifier` (.cpp + .h; the IPC encode/decode is not ported) |
| `css/css_style_sheet_1` | `CSSStyleSheet.cpp` 1-323: creation, the CSSOM constructor, insertRule/deleteRule/replace/replaceSync/addRule/removeRule |
| `css/css_style_sheet_2` | 324-665 and `CSSStyleSheet.h`: effective rules, owners, enabling, media evaluation, namespace and @import caches, critical subresources |
| `css/css_rule`, `css/css_rule_list`, `css/css_grouping_rule`, `css/css_condition_rule` | the rule base classes |
| `css/css_media_rule`, `css_supports_rule`, `css_container_rule`, `css_layer_block_rule`, `css_layer_statement_rule`, `css_namespace_rule`, `css_import_rule`, `css_style_rule`, `css_nested_declarations`, `css_page_rule`, `css_margin_rule`, `css_property_rule`, `css_counter_style_rule`, `css_font_face_rule`, `css_font_feature_values_map`, `css_font_feature_values_rule`, `css_function_rule`, `css_function_declarations`, `css_keyframes_rule`, `css_keyframe_rule` | one fragment per rule class |
| `css/css_style_declaration` | `CSSStyleDeclaration` |
| `css/css_style_properties_1` … `_4` | `CSSStyleProperties.cpp` 1-353 (creation, setProperty), 354-645 (getPropertyValue, the declared and resolved property), 646-1043 (getComputedStyle's resolved values), 1044-1526 (removeProperty, serialization, cssText) |
| `css/css_descriptors`, `css_font_face_descriptors`, `css_page_descriptors`, `css_function_descriptors` | the descriptor blocks |
| `css/css` | `CSS.cpp`: `CSS.escape()`, `CSS.supports()`, `CSS.registerProperty()` |
| `generated/generated_css_style_properties` | **tools/gen_css_values** `emit_generated_css_style_properties` from `data/css/Properties.json` (port of `generate_libweb_css_style_properties.py`); test.sh regenerates and compares |
| `css/tests_css_sheets_cases`, `tests_css_sheets`, `tests_css_sheets_2`, `tests_css_sheets_3` | tests (Ladybird has none for these files) |

## What other regions must know

### Cells and mixins

- Rules, sheets, lists and declaration blocks are cells made with the generated
  `realm_create_*`; `css_*_create` are the C++ `create`s.
- `CSSImportRule` is also a `CSSStyleSheet::Subresource`: the mixin is `rule.subresource`, its
  vtable is installed by the constructor, and `css_import_rule_from_subresource` is C++'s `this`
  adjustment. **types_css_import_rule**: the mixin vtable's `visit_edges` slot is filled
  (`css_import_rule_subresource_visit_edges_impl`), because CSSImportRule::visit_edges overrides
  both bases' virtuals.
- `CSSStyleProperties`' `GeneratedCSSStyleProperties` mixin is `props.generated_css_style_properties`
  (vtable installed by the constructor); the generated accessors take the mixin
  (`bind_generated_css_style_properties_color(&props.generated_css_style_properties)`).
- `CSSStyleSheet.m_pending_image_values` holds `WeakPtr<ImageStyleValue>`s over blobs: a style
  value is a heap blob, so the Weak is made to its Cell header (`css_weak_image_style_value`,
  css_style_sheet_2). **r34**: style values must be heap blobs for this (they are, under `with
  heap`).

### CSSKeyframesRule and CSSKeyframeRule (types_css_keyframes_rule)

The skeleton left both opaque (outside the phase-1 closure). They are now declared in the
generator's shape by hand, with CSSRule's own class id (8, which no object has): `is<CSSRule>`
holds for them and `is<>` of every other CSSRule subclass does not; their own
`is_/as_/as_if_css_keyframe(s)_rule` test the rule type, as `CSSRule::fast_is` does. The skeleton
should give them class ids when it is next run with them in scope.

### Signatures changed from the stubs

- `css_supports_rule_supports(this) -> CssSupports*` (was a `CssSupports` copy; C++ `Supports
  const&`).
- C++-private and internal-linkage functions are module-private: `css_rule_list_rule_context`,
  `css_descriptors_set_a_css_declaration`, the `CSSStyleProperties` private members
  (`get_property_internal`, `get_direct_property`, `set_property_internal`,
  `remove_property_internal`, `set_a_css_declaration`, `empty_the_declarations`,
  `set_the_declarations`, `invalidate_owners`, `convert_declarations_to_specified_order`,
  `style_value_for_computed_property`), the `CSSStyleSheet` private members
  (`recalculate_rule_caches`, `invalidate_shared_style_cache`, `set_constructed`,
  `set_disallow_modification`, `make_parsing_params`), `CSSImportRule::fetch`/`set_style_sheet`,
  `CSSStyleRule::parent_style_rule`, `StyleSheetList::add_sheet`/`remove_sheet`, the statics of
  StyleSheetList.cpp, CSSStyleProperties.cpp (`style_value_for_*`, `resolve_color_style_value`)
  and CSSFunctionRule.cpp (`serialize_a_css_type`).
- Added (namemap rows): the CSSKeyframe(s)Rule members; `JsMapEntry` (external/lib_js/types_map);
  phase-3 LibJS stubs in stub_closure for CSSFontFeatureValuesMap (`js_map_create`,
  `js_map_map_set`, `js_map_entries`, `js_array_create_from`, `js_object_get_length`,
  `js_value_to_length`, `js_object_get_without_side_effects_index`, `js_value_to_u32`); phase-2
  Fetch stubs for CSSImportRule::fetch (`fetch_response_unsafe_response`,
  `fetch_response_is_cors_cross_origin`).

### Where phase-1 paths stop now (other regions' stubs)

- Every mutation of a sheet that has owners or reaches `invalidate_owners`
  (insertRule/deleteRule/replaceSync on CSSStyleSheet, selectorText on a rule in a sheet,
  MediaList on a sheet, setProperty on a rule's declarations, enabling/disabling a sheet) reaches
  r42's `invalidate_style_for_style_sheet_owners` / `determine_shadow_root_stylesheet_effects`.
  CSSRuleList's "insert/remove a CSS rule" and CSSGroupingRule's insertRule/deleteRule do not.
- `@namespace` (every form: the parser tries `parse_url_function` first), `@import` and
  `@function` with parameters stop in r32 (`parse_url_function`, `parse_dashed_ident`); `@media`,
  `@supports` and `@container` in r42/r32; declarations with values in r33/r34.
- StyleSheetList: adding an enabled sheet loads its fonts (r41's `FontComputer`); removing one
  unloads them; `CSSStyleSheet::set_disabled` invalidates (r42).
- `@font-feature-values`: CSSFontFeatureValuesMap keeps its entries in a JS::Map as Ladybird
  does, so creating the rule traps in `js_map_create` until phase 3.
- `CSSImportRule::fetch` (when an @import gets a parent sheet) reaches the phase-2 Fetch stubs.

## Deviations and notes

- Lambdas are private functions with capture structs; the `ScopeGuard`s are `defer`s.
- `CSSStyleSheet::namespace_uri(StringView)` looks the prefix up as a FlyString (the HashMap's
  StringView-compatible lookup hashes and compares the same bytes).
- `GeneratedCSSStyleProperties`' Luce names come from the skeleton's naming of the C++ names
  (`float_` is `float`); the generator applies `luce_snake` and the test compares nothing but the
  regenerated file, so the names were checked once against the stub fragment's 898 names.

## Tests

- `tests_css_sheets_cases` (82 cases) + `tests_css_sheets`, `tests_css_sheets_2`: a local oracle
  (`luce-browser-tools/oracles/luce-browser-engine/css_sheets`: `oracle.cpp` links the reference
  build's LibWeb objects and runs in the internal CSS realm, `cases.txt`, `build.sh`,
  `gen_luce_cases.py`) parses each sheet and prints every rule's class, type for bindings,
  internal type and cssText recursively, Dump.cpp's dump of rules, CSSRuleList insert/remove
  with their exceptions, CSSGroupingRule insertRule/deleteRule, selectorText of free style rules
  and page rules, the cascade layer names (internal qualified names of blocks, statements and
  style rules), and focused objects: empty and resolved CSSStyleProperties (every getter,
  setProperty/removeProperty/cssText and their NoModificationAllowedErrors, the generated
  accessors), descriptor blocks and @font-face, @counter-style names, @property, @container
  conditions and effective rules, @import serialization and dump, keyframes, nested
  declarations, MediaList and StyleSheet state, margin and feature names, StyleSheetIdentifier,
  loading-state names and `CSS.escape`. All match. 52 more cases (marked `!` in cases.txt:
  sheet insertRule/deleteRule/addRule/selectorText, @namespace, @function parameters) run in
  the oracle and wait for r32/r42; `gen_luce_cases.py` leaves them out.
- `tests_css_sheets_3`: parent rule and style sheet links, effective-rule traversals,
  StyleSheetList with a disabled sheet, the critical-subresource loading state, the mixin link.

## Compiler issues

None found.