Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r34.md

# Region r34: CSS style values I — what other regions need to know

Region r34 ports `CSS/StyleValues/StyleValue` (the base class, its `is_*`/`as_*` and helpers) and
the leaf and composite style values of phase 1: keywords, custom idents, strings, integers,
numbers and the dimensions (angle, flex, frequency, length, percentage, resolution, time),
`StyleValueList`, `ShorthandStyleValue`, the colors (`ColorStyleValue`, `ColorFunctionStyleValue`,
`ColorMixStyleValue`, `LightDarkStyleValue`, `ColorSchemeStyleValue`,
`ColorInterpolationMethodStyleValue`), the images (`AbstractImageStyleValue`, `ImageStyleValue`,
`ImageSetStyleValue`, `CursorStyleValue`, the linear, radial and conic gradients,
`RadialSizeStyleValue`), positions and edges, rects and radii, shadows, tuples, `URLStyleValue`,
`UnresolvedStyleValue`, `PendingSubstitutionStyleValue`, `GuaranteedInvalidStyleValue`,
`UnicodeRangeStyleValue`, `RandomValueSharingStyleValue`, `ComputationContext` and the rest of
the region's 62 donor files. The stub fragment `stubs/stub_r34_style_values_1.lucb` is gone;
every one of its 853 functions is ported.

## Fragments

| Fragment | Donor |
| --- | --- |
| `css/style_values/style_value_1` | `StyleValue.cpp`/`.h`: construction, to_string, the CSS-wide keyword checks, tokenize, reify, subdivide, `int/number/string_from_style_value`, `ColorResolutionContext` |
| `css/style_values/style_value_2`, `style_value_3` | the `is_*` and `as_*` of `StyleValue.h` (mechanical) |
| `css/style_values/shorthand_style_value_1` … `_3` | `ShorthandStyleValue.cpp`: creation, longhands and equality (1); `serialize` split into one function per shorthand group: background … fonts (2), grid, mask, text, white-space (3) |
| `css/style_values/<class>` | one fragment per style value class (`keyword_style_value`, `color_function_style_value`, `linear_gradient_style_value`, …) |
| `html/supported_image_types` | `HTML/SupportedImageTypes.cpp` (`html_is_supported_image_type`; the skeleton missed the file; namemap row added) |
| `css/style_values/tests_style_values_1_values`, `tests_style_values_1`, `tests_style_values_1_2`, `tests_style_values_1_expected` | the oracle test (below) |

## What other regions must know

### Constructing and classes

- Every class has `css_<class>_create(...)` (the C++ `create`) and `css_<class>_construct(this,
  ...)`. `create` allocates with plain `alloc` in the current allocator, so under `with heap` a
  style value is a **heap blob** (r37's `css_weak_image_style_value` relies on this; r32's
  parser should create values only through these `create`s).
- The most-derived constructor installs the vtable and class id with
  `css_style_value_set_class(this, (const CssStyleValueVTable*)&X_vtable, &X_class)`; a subclass
  constructor calls its base's `construct` first, then `set_class`.
- Statics (`LengthStyleValue` 0px/1px, the CSS-wide keyword `KeywordStyleValue`s,
  `GuaranteedInvalidStyleValue`) are module vars created once `with memory.heap` (the C heap),
  so they outlive any test heap and are compared by pointer like the C++ singletons.

### Equality

- `ValueComparingNonnullRefPtr ==` is `css_style_values_equal`, `ValueComparingRefPtr ==` is
  `css_optional_style_values_equal` (r36); `NonnullRefPtr ==` compares pointers.
- The CRTP `StyleValueWithDefaultOperators::equals` is ported per class as `<class>_equals_impl`
  (type check + `properties_equal`); the generic template's namemap row is removed.
- Shared pub helpers: `css_style_value_vectors_equal` (style_value_list),
  `css_optional_fly_strings_equal`, `css_appendff(builder, fmt, args)` (style_value_1), and the
  color-stop helpers in abstract_image_style_value (`css_color_stop_lists_equal`,
  `css_color_stop_list_absolutized`, …).

### Signatures and types changed from the stubs

- `css_anchor_size_style_value_anchor_name` and `css_anchor_style_value_anchor_name` return
  `ak.FlyString?` (was `const ak.FlyString*?`; no callers outside the region).
- `types_color_function_style_value`: the anonymous `ResolvedChannels` struct is
  `CssResolvedChannels` (namemap updated). `types_color_mix_style_value`: `NormalizedPercentages`
  and `PercentageNormalizationResult` filled in. `types_image_set_style_value`: `Option` filled
  in. `generated/types_traits`: `CssRandomCachingKeyTraits` calls
  `css_random_caching_key_hash`/`_equals`.
- C++-private and internal-linkage functions are module-private.
- Added to `stubs/stub_closure` (section "CSS Typed OM", phase 3): opaque `CssKeywordValue`,
  `CssImageValue`, `CssTransformValue` and the `create`s `StyleValue::reify` and its overrides
  call (`css_css_style_value_create`, `css_keyword_value_create`, `css_image_value_create`,
  `css_unparsed_value_create`, `css_variable_reference_value_create`,
  `css_transform_value_create`).

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

- `ShorthandStyleValue::serialize` for most shorthands reaches r39's
  `for_each_property_expanding_shorthands` and r12c's `property_initial_value`, so the test
  covers only its coordinating-list and longhand paths.
- `reify` reaches the phase-3 Typed OM stubs; image loading reaches the Fetch/resource stubs.

## Deviations and notes

- Lambdas are private functions with capture structs. `ImageStyleValue::load_any_resources`'
  `weak_callback(*this, …)` captures a `gc.Weak` to the value's blob via r37's
  `css_weak_image_style_value`.
- `CursorStyleValue::make_image_cursor` paints with the CPU display-list player
  (DESIGN.md §7.3), not Skia.
- `AK::min`/`max` on doubles keep their semantics (`ak.min_f64`/`max_f64`); HWB clamps in
  double then converts to f32, as C++ does.

## Tests

- `tests_style_values_1*`: a local oracle
  (`luce-browser-tools/oracles/luce-browser-engine/style_values_1`: `oracle.cpp` links the
  reference build's LibWeb objects, `build.sh`, `expected.txt`, `gen_luce_expected.py` writing
  `tests_style_values_1_expected.lucb`) builds ~170 values of every class and prints their
  serializations (normal and resolved), flags, computational independence, colors (light and
  dark), absolutized values, the full equality matrix plus separately built equal values,
  tokenization, the helpers and statics, `is_color` over all 850 keywords, supported image
  types, lists, subdivision, longhands, radii, edges, gradient angles and radial sizes. The Luce
  dump matches all 1303 lines. Cases whose C++ VERIFYs (edges without offsets, tuples with nulls,
  …) are skipped for independence on both sides; the radial box with zero width is 1x50
  (division by zero is UB in C++ and traps in Luce).

## Compiler issues

None found.