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.