dymokomi/luce-browser-render
Source of release 0.6.2
0.6.2 / docs / regions / r09.md
# Region r09: fonts (`web_fonts`) — what other regions need to know
The `web_fonts` module is LibGfx's font stack: Font, FontData, FontDatabase, FontStyleMapping,
FontSupport, FontVariationSettings, PathFontProvider, Typeface, TypefaceSkia, UnicodeRange, the
WOFF and WOFF2 loaders, FontCascadeList, ShapeFeature and TextLayout, ported faithfully. Skia's
typeface and font and HarfBuzz are replaced by Luce code in the same module (DESIGN.md §6.7,
§7.1), which gives the numbers Ladybird's test mode gets from them: Skia's FreeType backend under
the FontConfig font manager (`WebContent --force-fontconfig`) and HarfBuzz 10.2. Each fragment's
header names the C++ it came from, and `docs/namemap.tsv` lists every name (additions are
`(r09: …)` rows).
## The replacement of Skia and HarfBuzz
**Moved to luce-fonts (2026-10-03).** The engine below is now luce-fonts' portable `opentype`
and `shaping` modules (sfnt_reader, sfnt_cmap, sfnt_glyf, sfnt_cff and the WOFF unwrapping are
`opentype`'s reader, cmap, glyf, cff and woff fragments, sk_font's numbers its scaler; the hb_*
fragments are `shaping`'s buffer, normalize, layout, position, context and fallback), with the
names unchanged (`opentype.sfnt_face_create`, `shaping.hb_shape`, ...), so every Luce program has
font files and shaping. web_fonts keeps the Ladybird-shaped layer over it: `sk_font.lucb` is
SkFont as a face and a size, `woff_loader.lucb`/`woff2_loader.lucb` make typefaces of what
luce-fonts unwraps, and the SkTypeface, hb_font_t and hb_buffer_t of Font.h and Typeface.h are
luce-fonts' `SfntFace`, `HbFontT` and `HbBufferT`. Differences from before the move: the shaper's
Unicode properties (marks, scripts, Emoji) come from luce-fonts' tables of the UCD 17.0.0 and its
combining classes and NFD/NFC from luce-std, in place of web_unicode (the same Unicode version);
`GlyphPath` points are `opentype.GlyphPoint`s (x, y) rather than FloatPoints; the engine's lists
(`opentype.List`) keep the allocator they first grew in, and `hb_buffer_destroy` and
`GlyphPath.release` free. The oracle's face, glyph id, metrics, path, shaping and WOFF cases and
the TestWOFF/TestWOFF2 ports run in luce-fonts; `tests_oracle.lucb` here keeps the text-blob
bounds and glyph intercept cases, which test GlyphRun.
| Fragment (as it was here) | Replaces | What it does |
| --- | --- | --- |
| `sfnt_reader.lucb` | SkTypeface_FreeType, FT_Face, hb_face_t | table directory (TTC included), head, maxp, hhea, OS/2, post, name; FreeType's ascender/descender/height, style flags and family-name choice; Skia's weight/width/slant |
| `sfnt_cmap.lucb` | unicharToGlyph, hb_font_get_nominal_glyph | HarfBuzz's cmap subtable choice; formats 0, 4, 6, 10, 12, 13 |
| `sfnt_glyf.lucb` | FT_Load_Glyph (unhinted), FT_Outline_Decompose, SkFTGeometrySink | TrueType simple and composite glyphs, FreeType's fixed-point arithmetic, the glyph path Skia builds (always at the canonical 64 px, scaled) |
| `sfnt_cff.lucb` | FreeType's CFF driver | CFF INDEXes, DICTs (CID-keyed fonts too), Type 2 charstrings |
| `sk_font.lucb` | SkFont | getMetrics (generateFontMetrics' rules, the > 256 px canonicalization), hinted glyph advances (measureText), getPath, GetFontBounds |
| `hb_buffer.lucb` | hb_buffer_t, hb_font_t, hb_shape | buffer, clusters, script (UCD) and direction guess, default-ignorable hiding, em scaling, zero-width marks, space widths, RTL reversal |
| `hb_normalize.lucb` | hb-ot-shape-normalize | cmap mapping with decomposition, the space fallbacks and U+2011; canonical reordering of marks; recomposition |
| `hb_layout.lucb` | hb-ot-layout, hb-ot-map | the default shaper's features (mark/mkmk with manual joiners), script/language-system choice, GDEF classes, GSUB 1/2/3/4/7, lookup flags |
| `hb_position.lucb` | hb-ot-layout (GPOS), hb-ot-kern, hb-aat-layout-trak | GPOS 1/2/4/5/6/9 and the attachment offsets, the legacy kern table, AAT tracking (trak) |
| `hb_context.lucb` | hb-ot-layout-gsubgpos | GSUB 5/6 and GPOS 7/8 (formats 1–3), HarfBuzz's skipping rules and apply_lookup |
| `hb_fallback.lucb` | hb-ot-shape-fallback, hb-unicode | canonical combining classes (derived from web_unicode's NFD), HarfBuzz's modified classes, glyph extents, fallback mark positioning for fonts without GPOS |
`tests_oracle.lucb` holds 98 expectations printed by a local program linked against the
reference build's LibGfx: face data, pixel and scaled metrics at eleven sizes (bit for bit), shaping
(glyph ids, positions, widths, cluster lengths; ligatures, pair kerning, ZWJ emoji sequences,
right-to-left text, letter spacing, space fallbacks, missing glyphs, contextual emoji
sequences (keycaps, flags, tag sequences), mark attachment, mark reordering, recomposition and
fallback mark positioning), glyph paths of TrueType and
CFF glyphs (bit for bit) and text-blob bounds, for SerenitySans, Lato Bold, Noto Emoji, Noto Sans
Tifinagh (CFF) and HashSans (WOFF).
## Signature and type changes against the skeleton
- Functions that took or answered a `Font`, `FontCascadeList` or `TypefaceSkiaGlyphPage` by value
(C++ references) take or answer pointers:
- `font_bold_variant(this) -> const Font*`;
- `font_cascade_list_first`, `font_cascade_list_font_for_code_point` and
`font_cascade_list_first_text_face -> const Font*`;
- `font_cascade_list_extend(this, other: const FontCascadeList*)`,
`font_cascade_list_equals(this, other: const FontCascadeList*)`;
- `glyph_run_font(this) -> const Font*`;
- `shape_text_f32(…, font: const Font*, …)`, `shape_text_utf16_view(…, font_cascade_list: const
FontCascadeList*, …)`, `measure_text_width(string, font: const Font*, …)`;
- `typeface_skia_glyph_page(this, page_index) -> const TypefaceSkiaGlyphPage*`.
- `font_cascade_list_for_each_font_entry(this) -> const FontCascadeListEntry[]` replaces the
template callback (loop over the entries, DESIGN.md §2.9).
- A `Core::Resource const&` is `const ak.CoreResource*` (`font_data_create_from_resource`,
`typeface_try_load_from_resource`, `woff_try_load_from_resource`); LibCore is not ported and
those trap with "unported: Core::Resource::data".
- `setup_text_shaping` and `hb_face_has_table` are private (internal linkage in C++).
- Creation helpers the skeleton lacks: `path_font_provider_create()` (make<PathFontProvider>),
`glyph_run_create(…)`, `unicode_range_create(min, max)`.
- For the display list: `font_glyph_path(font, glyph, scale) -> GlyphPath` is the outline Skia's
painter drew (`skia_font(scale).getPath(glyph)`): verbs `GlyphPathVerb` (move, line, quad,
cubic, close) and `gfx.FloatPoint`s in pixels, y down, origin at the glyph's pen position on
the baseline. The CPU player turns it into a raster path. `glyph_run_cached_skia_text_blob`
answers the port's `SkTextBlob` (the glyphs, their positions with the ascent added, as
`ensure_text_blob` lays them out, and the font).
## Types filled or fixed by hand
- Filled: `SkFont`, `SkTypeface`, `SkTextBlob`, `HbFontT`, `HbBufferT`, `HbFaceT`, `HbBlobT`,
`Impl` (TypefaceSkia's), `TypefaceSkiaGlyphPage`, `GlyphRunCachedTextBlob`,
`FontDatabaseCodePointFallbackEntry`, `FontCascadeListEntry` (with the new
`FontCascadeListEntryRangeData`), `FontCascadeListPendingFace`; the traits of
`CodePointFallbackKey` and `FontCacheKey`.
- `FontData.m_data` (a `Variant<ByteBuffer, NonnullRefPtr<Core::Resource>>`) is two fields,
`m_byte_buffer` and `m_resource`, because `bytes()` answers a span into the ByteBuffer held in the
FontData, which a payload enum cannot give.
- The WOFF structs (`Header`, `TableDirectoryEntry`, `TableDirectory`, `TableRecord`) are
`packed`, as the donor's are.
- `text_shaping_resolution` is a `let` of 64 (the generator left an uninitialized `var`).
- The FontStyleMapping tables are filled on first use (their StringViews are not constant
expressions).
## Memory
Superseded by the font-cache fix (`font_allocators.lucb`; luce-browser-engine DESIGN.md §3.3
rule 7). `FontDatabase::the()` and `PathFontProvider` (with every font file it loads) live in the
C heap whatever allocator is current; nothing needs rooting. A `Typeface` records the allocators
current when it was made (`m_allocators`), and everything it and its fonts keep later
(`Typeface::font`'s fonts and keys, the HarfBuzz face and fonts, the glyph pages, the shaping
cache) comes from those: the system typefaces keep their caches in the C heap, a web font's
typeface (made under a VM's heap) in that heap. Shaping runs in the current allocator and the
shaping cache keeps a copy of the result (`hb_buffer_copy`); an `SfntFace` parses its CFF INDEXes
when it is made, so it allocates nothing afterwards. gfx's sRGB color-space singletons are made in
the C heap too. `tests_lifetimes.lucb` uses the database's fonts under one collected heap,
destroys it and uses them under another.
## Dependencies on other regions
- r10 (FourCC): `FontVariationSettings` keys a HashMap by `gfx.FourCc`, and to_sorted_list,
`FontCacheKey::hash` and `harfbuzz_font` call `four_cc_to_u32`/`four_cc_lt`. Everything with
empty variation settings works now; `PathFontProvider::get_font` without explicit settings
(the defaults set wght, opsz, wdth) traps in r10's stubs until r10 is merged. The tests that need
it are gated by `tests_r10_four_cc_is_ported` in `tests_units.lucb`: flip it at integration
(they pass with r10's FourCC; checked locally with a stand-in).
- r08 (geometry): FloatPoint's operators are not called; the few point sums in TextLayout are
written on the fields in the same float order.
- `luce-compress` is a new dependency (WOFF's zlib tables, through its `flate` module).
## Deviations and what is not implemented
- **No system font manager.** `TypefaceSkia::find_typeface_for_code_point` and
`resolve_generic_family` (fontconfig/CoreText lookups) find nothing, so
`FontDatabase::get_font_for_code_point` answers none.
- **Font directories on Linux.** Ladybird's Linux build asks fontconfig (USE_FONTCONFIG); the
port has no fontconfig and takes the donor's XDG branch (`$XDG_DATA_HOME`, `$XDG_DATA_DIRS`).
- **Core::Resource.** `PathFontProvider::load_all_fonts_from_uri` reads `file://` URIs itself:
POSIX `nftw` (the Windows C runtime's `_findfirst64` on Windows, untested) and stdio reads.
luce-std's files module would do, but checking it with Luce 0.8.12 prints warnings of its own
(constant platform branches in luce-std `paths`), which the -W gate forbids. `resource://` URIs
are not supported.
- **WOFF2** needs a Brotli decoder (woff2 library): `convert_to_ttf` fails. TestWOFF2's
`tolerate_incorrect_sfnt_size` is not ported for that reason.
- **Variable fonts** are not instanced (`clone_with_variations` answers a typeface over the same
face; hb_font_set_variations records the coordinates).
- **Shaping** is HarfBuzz's default shaper without: the complex shapers (Arabic joining, Indic,
USE, Thai, Hangul, …), reverse chaining substitution (GSUB 8), cursive attachment (GPOS 3),
the ligature-component bookkeeping of mark-to-ligature and of fallback positioning (a mark
takes the last component), FeatureVariations, device tables, AAT tables other than trak
(morx, which HarfBuzz prefers to GSUB when a font has it, kerx, Apple's kern) and variation
selectors. Canonical combining classes are not in web_unicode's API:
hb_fallback.lucb derives them from its NFD (two marks swap exactly when the first has the
greater non-zero class) and recomposition asks its NFC.
- **Hinting.** There is no TrueType bytecode interpreter: `advance_of_ascii_zero` uses FreeType's
rounded phantom points without instructions, and a font without an OS/2 x-height gets its
x-height from the unhinted 'x' outline. Glyph paths are unhinted, as Skia asks for them.
- **CFF2** is read for the default instance only (blend keeps the default values).
- **Embedded-bitmap-only fonts** (no glyf or CFF outlines) fail to load, where FreeType loads their
strikes.
- **Glyph intercepts** (`get_glyph_intercepts`, text-decoration-skip-ink) split curves into 16
segments where Skia solves them; they match Skia's to about 0.05 px.
- **Color fonts** (COLR, CBDT, sbix, SVG) are only detected (is_emoji_font), not drawn.
- `Font::is_emoji_font` keeps the donor quirk: its first call answers false.
- GlobalFontConfig (fontconfig, not built on macOS) has no functions in the skeleton and is not
ported.
A local survey over the 269 system fonts of the machine (not committed) compared the reader and
shaper with the reference build: faces, cmaps, metrics, paths and shaping agree for most fonts;
the remaining differences are fonts with an AAT 'morx' table, which HarfBuzz shapes with AAT
instead of GSUB/GPOS (and their kerx and Apple kern kerning), bytecode
hinting (the x-height of fonts without an OS/2 x-height, `ch` advances of fonts whose hinting
moves advances), one variable font's glyph points (1/64 px at 64 px) and a bitmap-only font.
## Test fonts
`tests/web_fonts/fonts` (with `NOTICE` and `OFL-1.1.txt`): SerenitySans-Regular.ttf and
NotoEmoji.ttf (Ladybird's test-mode fonts), Lato-Bold.ttf and HashSans.woff (Ladybird test assets),
NotoSansTifinagh-Regular.otf (a CFF font, OFL, Noto project). `tests/web_fonts/woff`: the inputs of
TestWOFF and TestWOFF2.