dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r41.md
# Region r41: CSS fonts (FontComputer, FontFace, FontFaceSet) — what other regions need to know
Region r41 ports `CSS/FontComputer.cpp/.h` (FontWeightRange, FontFaceKey, ComputedFontCacheKey,
FontLoader, font matching, the computed font cache), `CSS/FontFace.cpp/.h`, `CSS/FontFaceSet.cpp/.h`,
`CSS/FontFeatureData.cpp/.h`, `CSS/FontLoading.cpp/.h` and `CSS/ParsedFontFace.cpp/.h` (3,698 donor
lines). The stub fragment `stubs/stub_r41_css_fonts.lucb` is gone; all 154 of its functions are
ported.
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/font_computer_1` | `FontComputer.cpp` 1-297 and `FontComputer.h` 24-98: FontWeightRange, FontFaceKey, ComputedFontCacheKey (operator== and the AK::Traits hashes), FontLoader, font_width_bucket_from_percentage, MatchingFontCandidate |
| `css/font_computer_2` | 299-473 and `FontComputer.h` 100-151: construction, visiting, the font matching algorithm with its ascending and descending weight searches, the @font-feature-values of a family |
| `css/font_computer_3` | 475-840: compute_font_for_style_values (and `_impl`), initial_font, clear_computed_font_cache, register/unregister_font_face, load_font_face, load/unload_fonts_from_sheet |
| `css/font_face_1` | `FontFace.cpp` 1-408 and `FontFace.h`: the descriptor computations, load_vector_font, construct_impl (with its BinaryData tasks), create_css_connected, reparse, parsed_font_face, the cell, font_computer, font_with_point_size |
| `css/font_face_2` | `FontFace.cpp` 409-899: the attribute setters and their `_impl`s, load(), add_to_set/remove_from_set, font_format_is_supported, font_tech_is_supported |
| `css/font_face_set` | `FontFaceSet.cpp/.h` |
| `css/font_feature_data` | `FontFeatureData.cpp` and `FontFeatureData.h`'s operator== and AK::Traits hashes |
| `css/font_loading` | `FontLoading.cpp/.h` |
| `css/parsed_font_face` | `ParsedFontFace.cpp/.h` |
| `css/tests_fonts_cases`, `tests_fonts`, `tests_fonts_2` | tests (below) |
## What other regions must know
### Phase 1: where fonts stop now
- **Document creation** (r17) now stops in `css_font_face_set_create`: FontFaceSet's constructor
makes its set entries with `JS::Set::create` (a phase-3 closure stub, `js_set_create`) and its
ready promise with r14's `WebIDL::create_promise` (phase 3). A FontFace holds a status promise
too: `FontFace::create_css_connected`, which `FontComputer::load_fonts_from_sheet` calls for every
valid `@font-face` rule when a sheet is added to a document, stops in `idl_create_promise`. Both
are faithful (the donor makes JS objects there); phase 1 needs a decision for documents to be
created: a phase-1 stand-in for JS::Set and WebIDL promises (cells that record their entries and
state), or the bindings of phase 3. Nothing else in Document's constructor path waits on r41.
- Everything else of the font computer runs: `compute_font_for_style_values` (r40's
`css_computed_properties_computed_font_list` works; the tests use it), font
matching over registered faces and the font database, `initial_font` (so r36's
`Length::ResolutionContext::for_document` works), the cache invalidation, `ParsedFontFace` of an
`@font-face` rule, `font_format_is_supported`/`font_tech_is_supported` (r32's and r35's `src`
descriptor parsing), `font_feature_value_type_from_string` and `to_shape_features` (r40's
`font_variant_alternates`).
- **Fetching fonts is phase 2**: `FontLoader::start_loading_next_url` calls r36's
`css_fetch_a_style_resource` (Fetch stubs) and reads the controller's state through a new closure
stub (`fetch_controller_state`). `local()` sources are not loaded (the donor's FIXME).
- **WOFF2**: `prepare_vector_font_data` traps `unported (P2): WOFF2::convert_to_ttf needs a Brotli
decoder` for WOFF2 data (by mime type or the `wOF2` signature). `try_load_vector_font`'s WOFF2
attempts go to luce-browser-render's `woff2_try_load_from_bytes`, which fails.
- **Threads**: `prepare_vector_font_data_off_thread` prepares the data on the calling thread (no
worker threads in phase 1, DESIGN.md §3.3 rule 6) and still hands the result to the callback
through the event loop (`core_deferred_invoke`).
- `FontFace::construct_impl` (JS) is ported; its BinaryData path uses LibCore's Core::Promise
(closure stubs `core_promise_typeface_*`, LibCore is not ported) and traps for the out-of-memory
JS::InternalError (phase 3).
### Signatures changed from the stubs
- `css_font_computer_initial_font(this) -> const web_fonts.Font*` (C++ returns a reference; the stub
copied the Font). r36's `css_length_resolution_context_for_document` is updated.
- `css_font_computer_load_font_face(this, font_face: const CssParsedFontFace*, on_load)` and
`css_font_face_construct_impl(realm, family, source, descriptors: const CssFontFaceDescriptors*)`
(C++ `const&`).
- `css_font_feature_data_to_shape_features(this, font_feature_values: const ak.HashMap[...]*)`.
- `css_prepare_vector_font_data_off_thread(data, on_complete: ak.Function1[ErrorOrCssPreparedVectorFontData, unit], ...)`:
C++ passes `ErrorOr<PreparedVectorFontData>`, which Luce cannot store (`T!`); the new payload enum
`ErrorOrCssPreparedVectorFontData` (`.value`, `.ak_error`) carries it.
- Module-private now (C++ private or internal linkage): FontComputer's
`find_matching_font_weight_*`, `font_matching_algorithm`, `compute_font_for_style_values_impl`,
`font_feature_values_for_family` (answers a pointer into the cache), FontLoader's
`try_load_font_mime_type_essence`, FontFace's `reject_status_promise` and `font_computer`, and the
file-local `font_width_bucket_from_percentage`, `style_value_references_font_family`,
`is_unsupported_source`, `compute_weight_range`, `compute_slope`, `compute_width`,
`load_vector_font`, `prepare_vector_font_data`, `find_matching_font_faces`.
- New: `heap_allocate_css_font_loader` (heap.allocate<FontLoader>), `css_font_face_key_new`,
`css_font_computer_matching_font_candidate_font_with_point_size`, and the equality and hash
functions of the keys (namemap rows added).
### Types filled or added
- `types_font_computer`: `MatchingFontCandidate { key, width, system_typeface }`.
- `types_parsed_font_face`: `ParsedFontFace::Source { local_or_url, format_, tech }` (`format` is a
core name) and the variant `FlyStringOrCssUrl`.
- `types_font_loading`: `ErrorOrCssPreparedVectorFontData`.
- `types_font_face`: FontFaceDescriptors' string defaults and FontFace's `m_cached_weight_range {400, 400}`
in the init fields.
- `generated/types_traits`: the traits of `FontFaceKey`, `FontFeatureValueKey` and
`ComputedFontCacheKey` (they trapped); r37's `CSSFontFeatureValuesRule::to_hash_map` now hashes.
- `stubs/stub_closure`, section "Region r41": `FetchControllerState`, `fetch_controller_state`,
JS::Set (`js_set_create`, `set_add`, `set_has`, `set_remove`, `set_size`, `js_set_values` for its
iteration), `Core::Promise<Typeface>` and `FontFaceSetLoadEventInit` /
`css_font_face_set_load_event_create` (FontFaceSetLoadEvent is outside every region).
### Other regions' files touched
- r35's three `@font-face src` oracle cases and r40's two font-variant-alternates cases, which waited
for r41, are enabled (their oracles' `!` marks removed, case tables regenerated). The other `!`
cases of r40 (color-scheme) wait for r42.
- The luce-js HANDOFF §5 item 4 follow-up for fonts, "Root FontDatabase::the()", is settled by the
font-cache fix instead: the database is made in the C heap, with everything it keeps (DESIGN.md
§3.3 rule 7).
## Deviations and notes
- MatchingFontCandidate's pending-face loader captures the FontFace pointer where C++ captures a
GC::Root: the font list and the captures are managed memory, which the collector scans. The
roots the donor gives callbacks that leave managed memory (the event loop, Core::Promise) stay
roots and are released when the callback runs.
- `FontComputer::initial_font`'s static font is a module variable; the font lives in its
typeface's font cache, in the C heap with the font database (DESIGN.md §3.3 rule 7).
- The JS objects (the status and ready promises, the JS::Set) are opaque until phase 3; visit_edges
visits them as cells, as the donor does.
- `font_matching_algorithm`'s `find_if`/iterator loops are index loops; `remove_all_matching` and
`quick_sort` are AK's (the order of equal-weight candidates follows AK's quick sort).
## Tests
- `tests_fonts_cases` (184 cases) + `tests_fonts`: a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/css_fonts`: `oracle.cpp` linking the reference
build's LibWeb objects, `build.sh`, `cases.txt`, `gen_luce_cases.py`, `README.txt`) with the fonts of
`tests/libweb/fonts` only (a SystemFontProvider over a PathFontProvider of that directory) and the
FontPlugin in layout test mode. Modes: `font_feature_value_type_from_string`; the shape features of
a ComputedProperties' `font_feature_data` (every font-variant-*, font-kerning, text-rendering and
font-feature-settings combination, @font-feature-values maps with multi-value styleset and
character-variant) and the AK::Traits hashes; `font_format_is_supported` and
`font_tech_is_supported`; `requires_off_thread_vector_font_preparation` and `try_load_vector_font`
(TrueType, CFF, mime types, garbage); `@font-face` rules through `ParsedFontFace::from_descriptors`
(every descriptor); FontFace's `_impl` and public setters; and font matching through
`computed_font_list`: generic families, unknown and system families, registered faces by weight
(all of the CSS weight rules), slope, width, unicode ranges, case-insensitive families,
registrations after a first computation (the cache invalidation), font-feature and variation
settings. Each font prints its family, slope, width, point size, variation axes and shape
features; the weight is left out because luce-browser-render does not instance variable fonts
(Noto Emoji's instance reports the requested `wght` in the reference build). All match.
- `tests_fonts_2` (12 focused tests): the width buckets, FontWeightRange and FontFaceKey,
FontFeatureData's equality, the computed font cache (value-equal keys, selective clearing,
generic keywords), the elements a cleared family marks for a style update, registering and
unregistering faces, load_font_face (no sources, local() only, the loaders by URL), FontLoader's
subscribers and end of loading, initial_font, a FontFace's unicode ranges, fonts and
ParsedFontFace, is_unsupported_source, and the WOFF2 check.
- The test fonts (`tests/libweb/fonts`: SerenitySans and Noto Emoji, Ladybird's test-mode fonts,
Lato Bold and Noto Sans Tifinagh, with `NOTICE` and the OFL) are installed once per test run
(`test_fonts_setup`: a PathFontProvider and a FontPlugin built as its constructor builds it for a
provider that is not a PathFontProvider), in the C heap as the font database always is. The font
tests run with their VM's heap current and may collect (DESIGN.md §3.3 rule 7; the deferred
collections and C-heap allocation they had are gone).
## Compiler issues
None.