Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / docs / regions / r39.md

# Region r39: the cascade (StyleComputer, StyleScope) — what other regions need to know

Region r39 ports `CSS/CascadeOrigin.h`, `CascadedProperties`, `CountersSet`, `CustomPropertyData`,
`CustomPropertyRegistration.h`, `StyleComputer` and `StyleScope`. The stub fragment
`stubs/stub_r39_style_computer.lucb` is gone; every one of its 166 functions is ported.

## Fragments

| Fragment | Donor |
| --- | --- |
| `css/cascaded_properties` | `CascadedProperties.cpp` + `.h` |
| `css/counters_set` | `CountersSet.cpp` + `.h` (resolve/inherit counters) |
| `css/custom_property_data` | `CustomPropertyData.cpp` + `.h`, `CustomPropertyRegistration.h`'s `operator==` |
| `css/style_scope_1` | `StyleScope.h`'s inline members; `StyleScope.cpp` 1-420: visiting, StyleCache, building the rule cache, the user-agent sheets, `make_rule_cache_for_cascade_origin` (with the @keyframes sets), selector insights |
| `css/style_scope_2` | 422-1024: layer names, counter styles, :has() insights, pending :has() invalidations, tree-scoped references |
| `css/style_computer_1` | `StyleComputer.h`'s inline members (CountingBloomFilter, accessors); `StyleComputer.cpp` 1-438: MatchingRule, constructor, rule caches, invalidation plans, `collect_matching_rules`, `sort_matching_rules` |
| `css/style_computer_2` | 439-637: shorthand expansion, `apply_property_list_to_cascade`, `cascade_declarations`, custom property cascade |
| `css/style_computer_3` | 639-996: `collect_animation_into`, `process_animation_definitions` |
| `css/style_computer_4` | 997-1266: dimension attributes, transitions |
| `css/style_computer_5` | 1268-1776: `build_matching_rule_set`, `compute_cascaded_values`, inherited values, font-size tables, `compute_property_values`, computation contexts, overflow, text-align, box type transformations |
| `css/style_computer_6` | 1777-2239: `create_document_style`, `compute_style*`, `compute_style_impl`, monospace font-size, `compute_properties`, bucketing simplification |
| `css/style_computer_7` | 2241-2793: custom property values, `compute_value_of_property` and the per-property computations |
| `css/style_computer_8` | 2795-3080: position-area, math-depth, the ancestor filter, `RuleCache::add_rule` / `for_each_matching_rules` |
| `animations/keyframe_effect_key_frame_set` | `Animations/KeyframeEffect.cpp` 575-626 and 976-987, ahead of phase 4 (below) |
| `css/tests_style_computer`, `tests_style_computer_cases`, `tests_style_computer_values_cases`, `tests_style_computer_2` | tests (Ladybird has none for these files) |

## What other regions must know

### Data

- A `StyleCache`, a per-layer `RuleCache`, the pseudo-class `RuleCache`s, a `CustomPropertyData` and a
  `KeyFrameSet` are managed blobs (`new`); `StyleScope` stays embedded in Document/ShadowRoot.
- `ScopedMatchingRule.rule` points into the rule cache's vectors (C++ `MatchingRule const*`).
- `CountingBloomFilter<u8, 14>` is the only instantiation: the struct stays generic with
  `m_buckets: TCounterType[16384]`, its members are ported for `CssCountingBloomFilter[u8]`.
- `CascadedProperties::m_contained_properties_cache` (AK::FixedBitmap) is `bool[386]`.
- New allocation helpers: `heap_allocate_css_cascaded_properties` (style_computer_5) and
  `heap_allocate_css_computed_properties` (style_computer_6; **r40** may reuse it).

### Signatures changed

- **`dom_abstract_element_style_scope(this) -> CssStyleScope*`** (was a copy; a copy would build its
  rule cache in the copy). Callers: r16's `element_2` passes `*…` to r40's
  `css_computed_properties_list_style_type(this, style_scope: CssStyleScope)`, which **r40** should
  change to `const CssStyleScope*`; r35's `css_counter_style_style_value_resolve_counter_style` now
  takes `const CssStyleScope*` (its callers in counter_style_value pass the pointer).
- r39's own: `style_scope: const CssStyleScope*` wherever C++ has `StyleScope const&`;
  `css_style_scope_author/user/user_agent_rule_cache -> const CssRuleCaches*`,
  `get_pseudo_class_rule_cache -> const CssRuleCache*`; `collect_selector_insights(selector:
  const CssSelector*)`, `should_reject_with_ancestor_filter(selector: const CssSelector*)`;
  `css_rule_cache_add_rule(matching_rule: const CssMatchingRule*)`;
  `invalidation_plan_for_properties(properties: const ak.Vector[…]*, …)`,
  `has_invalidation_metadata_for_property(property: const CssInvalidationSetProperty*, …)`,
  `record_pending_has_invalidation_mutation_features_vector(…, properties: const ak.Vector[…]*)`;
  `compute_cascaded_values(…, matching_rule_set: const CssStyleComputerMatchingRuleSet*)`,
  `cascade_declarations(…, matching_rules: const ak.Vector[…]*, …)`;
  `dereference_global_tree_scoped_reference[T](this, callback: ak.Function1[const CssStyleScope*, T?]) -> T?`.
  C++-private and internal-linkage functions are module-private.
- **r42**: `css_style_invalidation_data_build_invalidation_sets_for_selector(this, selector: const
  CssSelector*)` (was a copy; r38's note).
- `animations_animation_cancel(this, should_invalidate = .yes)` (stub_closure: the C++ parameter).

### Types filled or added

- `types_cascaded_properties`: `Entry`. `types_style_computer`: `ScopedMatchingRule`,
  `LayerMatchingRules` (new), `MatchingRuleSet`, `CountingBloomFilter`.
  `types_custom_property_data`: `init_fields` (`NumericLimits::max()`).
- **r42** `types_invalidation_set`: `InvalidationSet::Property { type_, value }` with
  `CssInvalidationSetPropertyType` and the variant `FlyStringOrPseudoClassOrEmpty`.
- **r40** `types_computed_properties`: `ComputedProperties::AnimationProperties` (with `F64OrString`).
- `animations/types_keyframe_effect`: `KeyFrameSet`, `ResolvedKeyFrame`, `UseInitial` and their
  variants, `AnimationKeyFrameKeyScaleFactor`. `generated/bindings/types_keyframe_effect` (by hand,
  generator form): `BindCompositeOperation`, `BindCompositeOperationOrAuto`.
- stub_closure, section "Animations, transitions and easing (phase 4; added by region r39)":
  `EasingFunction::from_style_value`/`evaluate_at`, the AnimationEffect, KeyframeEffect, Animation,
  Animatable, CSSAnimation and CSSTransition members StyleComputer calls, `interpolate_property`,
  `property_values_are_transitionable`, `composite_value`, and the types `TimeValue`,
  `TransitionAttributes`, `GetAnimationsOptions`, `GetAnimationsSorted`, `ShouldInvalidate`,
  `AllowDiscrete`. Their opaque types are reached by embedded-base pointer casts.

### Ported ahead of phase 4

The user-agent sheet has three `@keyframes`, so every rule cache builds `KeyFrameSet`s:
`KeyframeEffect::generate_initial_and_final_frames` and
`css_animation_composition_to_bindings_composite_operation_or_auto` are ported in
`animations/keyframe_effect_key_frame_set`.

### Embedded sheets

`tools/embed_css` now also embeds `MathML/Default.css` and `SVG/Default.css` (copied to
`data/css/MathML`, `data/css/SVG`) as `css_mathml_stylesheet_source` and `css_svg_stylesheet_source`;
the four fragments' doc lines name `CSS/…`, `MathML/…`, `SVG/…` sources.

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

- **Building a rule cache** stops in r42's `StyleInvalidationData::build_invalidation_sets_for_selector`
  (every selector), and the user origin in r28's `Page::user_style`; the user-agent sheets are parsed
  in `internal_css_realm()`, which stops in r28's `Window::create`; their `@media` rules in r42's
  `MediaQuery::create`.
- **`compute_style_impl`** runs the cascade and the custom properties, then stops in
  `compute_properties` at r40 (ComputedProperties' constructor, InitialValues, every accessor).
  `compute_value_of_custom_property` and `compute_custom_properties` work without r40.
- **The StyleComputer constructor** needs a FontPlugin and r40's `InitialValues::line_height`;
  `Document::create` now stops there (with no FontPlugin installed, at `FontPlugin::the()`), then at
  r41's `FontComputer`.
- `compute_font_size`, `compute_font_weight`, `compute_math_depth` reach r40's InitialValues;
  computation contexts reach r40 and `Length::ResolutionContext::for_element/for_document` (r41 fonts);
  counter styles reach `for_document` too. The animations and transitions are phase 4.
- `ShorthandStyleValue::serialize` (r34's note) now works: the tests serialize 15 shorthands.

## Deviations and notes

- Lambdas are private functions with capture structs; `ScopeGuard`s are `defer`s; non-escaping
  attribute walks are loops over the NamedNodeMap.
- `StyleComputer::visit_edges`: `visitor.visit(*m_has_result_cache)` visits nothing in C++ (no
  `visit` overload for HasResultCacheKey or HasMatchResult), so the port visits nothing there.
- Donor quirks kept: `CustomPropertyData::for_each_property` never skips a shadowed name
  (`HashTable::set` answers ReplacedExistingEntry); `compute_font_size`'s math scaling exponent is
  the comparison `(B - A) > 0` (0 or 1); `process_animation_definitions` returns from the whole
  function after updating the first existing animation; `recascade_font_size_if_needed` creates
  `new_font_size` and never reads it.
- The `static` caches (`monospace_font`, `cached_round_value`, the user-agent sheet roots) are module
  `var`s; `cached_round_value` is made under `memory.heap` as r34's statics are.
- `C++ CSSPixels * CSSPixels(3) / 5` is `mul_css_pixels` then `div_css_pixels_int` and the
  fraction's conversion back to CSSPixels.

## Tests

- `tests_style_computer_cases` (24 cases, 168 queries) + `tests_style_computer`: a local oracle
  (`luce-browser-tools/oracles/luce-browser-engine/style_computer`: `cases.txt`, `gen_cases.py`,
  `expected.txt`) runs a generated Text test through the reference build's `test-web
  --rebaseline`: per case an author `<style>`, div#root's markup and `getComputedStyle()` queries of
  properties whose computed value is the cascaded value as written. The Luce test builds the same
  tree (tests_selector_engine's builder, inline styles as `attribute_changed` makes them), installs
  the four user-agent sheets parsed in the test realm (without their `@media` blocks: r42), builds
  the rule caches as `make_rule_cache_for_cascade_origin` does without r42's invalidation sets,
  runs `compute_style_impl`'s steps up to the cascaded values plus `compute_custom_properties`, and
  answers each query from the cascaded value (or the parent's / initial value). Covered: the
  user-agent sheet, specificity and order, !important and inline styles, inheritance and
  inherit/initial/unset, @layer (statements, nesting, anonymous, important reversal), revert and
  revert-layer, the hidden attribute, shorthands and `all`, custom properties and var() (with
  fallbacks, pending substitution in shorthands, invalid at computed-value time, !important, inline),
  every rule-cache bucket, :is()/:where() specificity, combinators and structural pseudo-classes,
  invalid declarations, nesting. All match.
- `tests_style_computer_values_cases` (84 cases) + `tests_style_computer_2`: a second oracle
  (`oracles/luce-browser-engine/style_computer_values`: `oracle.cpp` linking the reference build's
  LibWeb objects, `build.sh`, `cases.txt`, `gen_luce_cases.py`) parses values and runs StyleComputer's
  computations (font-width/style, line-height, corner shapes, position-area, font feature and
  variation settings, animation-name, border widths, and shorthand serialization); its font-size,
  font-weight and math-depth cases (marked `!`, r40) run in the oracle only, and give the
  font-size keyword table values of a focused test.
- Focused tests: CascadedProperties (origins, layers, !important, revert, revert-layer, logical
  pairs), CustomPropertyData (absorbing, flattening at 32 ancestors, the for_each_property quirk,
  `inheritable` with a registered non-inherited property and its cache), CustomPropertyRegistration
  equality, the Bloom filter, CountersSet (and its dump), shorthand expansion, selector insights,
  RuleCache buckets and the user-agent @keyframes sets.

## Compiler issues

- `luce-browser-tools/compiler-issues/array_length_constant_expression.lucb`: an array length that
  is a constant expression other than a literal (`(usize)(u16)Enum.case + 1`, even `(usize)3 + 3`)
  is rejected. Workarounds tagged `# LUCE-BUG: array_length_constant_expression` (literal length +
  module assert): CascadedProperties' cache, CountingBloomFilter's buckets,
  `apply_property_list_to_cascade`'s and `compute_keyframe_values`' bitmaps.