Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r33.md

# Region r33: CSS property parsing and the generated property data — what other regions need to know

Region r33 ports `CSS/Parser/PropertyParsing.cpp` (5,922 lines) and
`CSS/Parser/ArbitrarySubstitutionFunctions.cpp/.h` (722), and generates the value-dependent part of
`PropertyID.cpp`, `DescriptorID.cpp` and `EnvironmentVariable.cpp` that css_data left to the
engine (the former `stubs/stub_r12c_css_data.lucb`). Both stub fragments
(`stub_r33_css_property_parsing`, `stub_r12c_css_data`) are gone; every one of their functions is
ported or generated.

## Fragments

| Fragment | Donor |
| --- | --- |
| `css/parser/arbitrary_substitution_functions_1` | `ArbitrarySubstitutionFunctions.cpp` 1-265: SubstitutionContext, GuardedSubstitutionContexts, the function names, "replace an attr() function" |
| `css/parser/arbitrary_substitution_functions_2` | 267-656: env(), if(), inherit(), var(), "substitute arbitrary substitution functions", the argument grammars |
| `css/parser/property_parsing_1` | `PropertyParsing.cpp` 1-368: keyword-only values, simple and coordinating lists, `parse_css_value_for_properties` |
| `css/parser/property_parsing_2` | 370-778: `parse_css_value`, positional value-list shorthands |
| `css/parser/property_parsing_3` | 780-1120: color-scheme, counters, cursor, anchor-name/-scope, aspect-ratio, animation, background-position |
| `css/parser/property_parsing_4` | 1122-1479: background, background-position-x/y, background-size, border(-block/-inline) |
| `css/parser/property_parsing_5` | 1480-1820: border-image(-slice), border radii, columns |
| `css/parser/property_parsing_6` | 1821-2169: shadows, shape-outside, rotate, stroke-dasharray, content |
| `css/parser/property_parsing_7` | 2170-2449: display, flex, flex-flow |
| `css/parser/property_parsing_8` | 2450-2813: font, font-family, font-language-override, font-feature-/variation-settings |
| `css/parser/property_parsing_9` | 2814-3285: font-variant, list-style, mask |
| `css/parser/property_parsing_10` | 3286-3621: math-depth, overflow-clip-margin, paint-order, place-*, position-anchor, position-try-fallbacks |
| `css/parser/property_parsing_11` | 3622-4088: position-area, position-visibility, quotes, repeat styles, text-decoration |
| `css/parser/property_parsing_12` | 4089-4428: text-decoration-line, text-indent, text-underline-position, timeline-scope, touch-action, transform-origin |
| `css/parser/property_parsing_13` | 4430-4727: transition, translate, scale, scroll-timeline, scrollbar-color, scrollbar-gutter |
| `css/parser/property_parsing_14` | 4729-5085: grid-column/-row, grid-template, grid-area, grid |
| `css/parser/property_parsing_15` | 5086-5296: grid-template-areas, grid-auto-*, grid-template-rows/-columns |
| `css/parser/property_parsing_16` | 5298-5647: filter, contain, container-type |
| `css/parser/property_parsing_17` | 5648-5922: white-space(-trim), view-timeline, will-change |
| `generated/property_id` | **tools/gen_css_values** `emit_property_id_values` from Properties.json, Enums.json, LogicalPropertyGroups.json: `property_initial_value`, `property_accepts_type`, `property_accepted_ranges_by_value_type`, `property_resolves_percentages_relative_to`, `property_accepts_{angle,flex,frequency,length,percentage,resolution,time}` |
| `generated/descriptor_id` | `emit_descriptor_id_values` from Descriptors.json: `descriptor_initial_value` |
| `generated/environment_variable` | `emit_environment_variable_values` from EnvironmentVariables.json: `environment_variable_type` |
| `css/parser/tests_css_property_parsing_cases`, `tests_css_property_parsing` | tests (Ladybird has none for these files) |

Lambdas are private functions named after their enclosing function; lambdas that capture
locals by reference take a state struct (`CssParserParseBackgroundValueState`, ...); callbacks of
`parse_comma_separated_value_list` are `ak.Function1`s over the parser or a small capture struct.
C++ blocks that own a TokenStream transaction (and so rewind the stream when they end) are
functions of their own, so that the transaction ends where the C++ block ends.

## What other regions must know

### The generated data (r34, r35, r39, ...)

- `css_property_initial_value(id)` caches every parsed initial value in a module array, as the C++
  static does. The values (and everything their parse allocates, strings included: the
  `ak.atomic_allocator` view is cleared while parsing) live in the C heap, so the collector never
  frees them and they outlive any test heap. `css_descriptor_initial_value` does the same.
- `css_property_accepted_ranges_by_value_type(id)` answers a fresh
  `ak.HashMap[CssValueType, CssNumericRange, CssValueTypeTraits]`.
- Donor quirks kept: the initial values of `grid` and `grid-template` ("auto") do not parse, so
  `property_initial_value` of either fails its VERIFY (traps); the same for the `@counter-style`
  descriptors `negative`, `prefix`, `suffix` and `pad` (the generated C++ literal of pad's
  `0 ""` is `"0 " ""`). The generator writes the text Properties.json gives; only pad differs,
  and it traps in both.

### Signatures and types

- `CssParserPropertyAndValue { property, style_value }` (types_parser) is filled.
- C++-private and internal-linkage functions are module-private: `css_remove_property`,
  `css_contains_attr_tainted_value`, `css_mark_as_attr_tainted`, `css_replace_an_*_function`,
  `css_substitute_arbitrary_substitution_functions_step_2`.
- Everything else keeps the stub signatures. `css_parser_parse_coordinating_value_list_shorthand`'s
  `reset_only_longhand_ids` defaults to an empty vector, as in C++.
- `css_next_token_is`, `css_next_token_is_delim` and `css_next_token_is_ident` are r32's
  (value_parsing_1/2); r33 had identical copies and dropped them at the merge.

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

- **r35**: style value creation for FontStyle, GridTrackPlacement, GridTrackSizeList (including
  `make_none`), GridAutoFlow, GridTemplateArea, Transformation, FilterValueList,
  CounterDefinitions, CounterStyle, CounterStyleSystem and BasicShape: the initial values of
  font, font-style, the grid properties, transforms, filters and counters, and the property values
  that make one (86 oracle cases, marked `!` with the stub they reach in
  `css_property_parsing/later.txt`).
- **r39**: `StyleComputer::compute_value_of_custom_property` (every `var()` substitution) and
  `ShorthandStyleValue::serialize` of most shorthands (r34's note), so the oracle prints a
  shorthand's longhands rather than its serialization.
- Substitution with an element (`css_substitute_arbitrary_substitution_functions` with `attr()`,
  `env()`, `if()`, `inherit()`) reaches the DOM and Document as ported; `if()` conditions reach r42's
  boolean expressions.

## Deviations and notes

- `parse_css_value`'s `switch (property_id)` ends in `default: break;`; the code after the switch
  is `css_parser_parse_css_value_after_special_cases`, called from the default arm.
- `parse_css_value` clones `longhands_for_shorthand()`'s shared vector before removing from it
  (HANDOFF §5 item 4, "clone css_data's shared static Vectors").
- `GuardedSubstitutionContexts` keeps pointers to the guarded contexts, which live in
  `substitute_arbitrary_substitution_functions`' frame until its deferred unguard, as the C++
  references do. A context that is already cyclic when guarded is not unguarded (the C++
  ScopeGuard is made after that return).
- The function-local statics of parse_scroll_timeline_value and parse_view_timeline_value are
  module variables pointing into property_initial_value's cache.

## Tests

- `tests_css_property_parsing_cases` (1,209 cases) and `tests_css_property_parsing`: a local oracle
  (`luce-browser-tools/oracles/luce-browser-engine/css_property_parsing`: `oracle.cpp` links the
  reference build's LibWeb objects like r30b's, `value_cases.txt`, `later.txt`, `make_cases.py`
  writes `cases.txt`, `gen_luce_cases.py` writes the table, `build.sh`) prints, compared byte for
  byte: for every property (and custom properties) the accepted value types, the numeric ranges,
  the percentage basis and the seven range checks at six sample values; every environment
  variable's value type; every initial value and descriptor initial value; `parse_css_value` over
  ~370 inputs (every special-cased property, CSS-wide keywords, substitution functions, custom
  properties, legacy value aliases, coordinating lists, positional and generic shorthands, and
  their SyntaxErrors) as the value's type and serialization with shorthands expanded to their
  longhands and lists to their items; `parse_css_value_for_properties`; the arbitrary
  substitution function names and argument grammars. 86 more cases wait for r35 (`later.txt`
  names the stub each reaches).
- Focused tests: SubstitutionContext equality and `to_string`, GuardedSubstitutionContexts
  (cycles, unguard), `contains_guaranteed_invalid_value`, attr-tainting.
- r32's `css_value_parsing` oracle: `type:corner-shape superellipse(2)` (it waited for
  `parse_all_as_single_keyword_value`) is enabled and passes; `symbols(...)` waits for r35's
  CounterStyleStyleValue. r37's 21 remaining `!` cases of `css_sheets` wait for r42's invalidation
  (`invalidate_style_for_style_sheet_owners`, `determine_shadow_root_stylesheet_effects`), not
  r33 (checked by running each).

## Compiler issues

None found.