jumpy-lion 1.0.0-beta.0 → 1.0.0-beta.4

package/browser/fonts/macos-bundle/build-metric-fonts.py

@@ -0,0 +1,1010 @@
+#!/usr/bin/env python3
+"""Build one real font file per macOS family, carrying that family's own advances.
+
+The problem this solves
+-----------------------
+The bundle used to reach every Mac family through a fontconfig alias, and one
+clone served many aliases - Liberation Sans stood in for 21 of them. Measured per
+character against real Chrome 151 on macOS, that collapsed 54 families onto 19
+distinct advance signatures where a Mac has 41. Zapfino measured identically to
+Helvetica. Times, Baskerville, Hoefler Text, Cochin, Rockwell, Tahoma, SF Mono,
+Charter, Bookman and six more were one single face. Any page that measures two
+families and compares them has found the container, and the comparison is a
+one-liner.
+
+It cannot be corrected with a per-family number. Fitting a per-glyph tracking
+value and a proportional scale factor on one string and scoring them on strings
+they were not fitted to (test/docker-linux/fit-advance-model.mjs) put the
+worst-case error at 5.76% and 5.89% against 6.30% for doing nothing at all: the
+error is specific to each glyph, so only a correction that carries every glyph's
+own advance generalises.
+
+What this does
+--------------
+For each Mac family: pick the installed face whose advance PROPORTIONS are
+closest, copy it, overwrite the advance of every captured character with the
+Mac's own value, replace its kerning with the Mac's measured pairs, and rename it
+to the Mac family. The result is a font that is genuinely named "Copperplate" and
+genuinely measures like the Mac's Copperplate, so the alias for it can go away.
+
+Both halves are needed, because a string's width is the sum of its advances PLUS
+the kerning of each adjacent pair and Chrome kerns by default. With exact
+advances and the donor's kern pairs, the system face was still uniformly 0.6%
+wide at EVERY size - which looks like a tracking error and is not one. Writing
+the Mac's pairs in took that from 0 of 75 sizes within 0.5% to 75 of 75.
+
+Advances are overwritten exactly, so the donor choice does not affect width at
+all - it decides what the text LOOKS like, and so how far the ink bounding box
+lands from the Mac's. Hence picking on shape after a best-fit uniform scale: a
+donor that is a uniformly narrower cut of the same design is a good donor,
+because the scale is absorbed when the advances are rewritten.
+
+Each glyph's OUTLINE is then fitted to the Mac's ink box - the four
+actualBoundingBox* numbers a page reads from the same measureText call - by a
+per-glyph affine, and the face is rescaled to the Mac face's own units-per-em
+first so that the grid the binary snaps metrics to is the grid the Mac uses.
+
+What it does NOT fix
+--------------------
+Glyph SHAPES are still the donor's. The ink now starts and stops where the Mac's
+does; what happens between those edges is the donor's outline, stretched. Text
+looks wrong where the donor is a poor visual match (a script face like Zapfino
+has no free equivalent), and a detector hashing canvas PIXELS rather than metrics
+still sees a different face.
+
+All four faces are generated - regular, bold, italic, bold-italic - wherever the
+Mac has a real one.
+
+An earlier version built only regular and bold, on the measurement that italic
+advances were "within 1% of regular". That came from a ten-family sample and does
+not survive the full set: across 65 families, 33 have italic advances that differ
+from regular, by 10.21% on average for Cochin, 10.14% for Baskerville, 9.33% for
+Hoefler Text (90% on its worst character), 5.68% for Palatino and 5.03% for
+Times. Synthesising those from the regular face is the same error as
+synthesising bold was.
+
+A style is skipped only when NOT building it lands on the same advances anyway,
+which means asking what SKIA would synthesise from - not what CoreText did. The
+two disagree on bold-italic: the Mac synthesises it from the BOLD face, Skia
+picks the ITALIC face when one exists. Skipping on the Mac's answer left five
+script families measuring their italic advances for bold-italic text, up to 120%
+off on a character.
+
+When a style's advances are identical to one already built, it is built from the
+SAME donor file, so the two round to identical font units. Otherwise they would
+measurably differ where the Mac has them exactly equal - the mirror of the
+collapse this whole exercise removes, and just as usable by a page.
+
+Usage (inside a container that has the clone fonts installed):
+    python3 build-metric-fonts.py \
+        --advances char-advances-macos-chrome151.json \
+        --out /out
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from collections import defaultdict
+
+from fontTools.feaLib.builder import addOpenTypeFeatures
+from fontTools.pens.boundsPen import BoundsPen
+from fontTools.pens.recordingPen import DecomposingRecordingPen
+from fontTools.pens.t2CharStringPen import T2CharStringPen
+from fontTools.pens.transformPen import TransformPen
+from fontTools.pens.ttGlyphPen import TTGlyphPen
+from fontTools.ttLib import TTFont
+from fontTools.ttLib.scaleUpem import scale_upem
+from fontTools.varLib import instancer
+
+# The CSS generics are not families to build: they are whatever fontconfig
+# resolves by default, which the alias file sets.
+GENERICS = {"sans-serif", "serif", "monospace", "cursive", "fantasy"}
+
+# Families the bundle reaches with a face that is genuinely the right shape and
+# script, where substituting a Latin donor would be a regression.
+SKIP = {"Apple Color Emoji", "Apple Symbols", "Apple Braille"}
+
+# Faces to build under a second name, from another family's capture.
+# `system-ui` never reaches the font cache under that spelling: for a macOS claim
+# FontCache::SetSystemFontFamily points it at "BlinkMacSystemFont", and Chrome
+# DCHECKs that "system-ui" itself never gets there. So the system face has to
+# exist under the internal name as well, or unstyled UI text - most of the text
+# on a modern page - falls back.
+EXTRA_NAMES = {"BlinkMacSystemFont": "system-ui"}
+
+# What each CSS generic resolves to on macOS. Used to tell a family that is
+# genuinely installed from one that merely FELL BACK during the capture: if a
+# family's advances are identical to a generic's, the Mac has no such font and
+# answered with the default. Building a face for it would be a leak pointing the
+# other way - the container would then resolve a family the claimed OS does not
+# have. Measured on macOS 26.5.2, that catches ZapfDingbats and Bookman, both of
+# which are in the binary's canvas allowlist and should not be.
+GENERIC_TARGETS = {
+    "sans-serif": "Helvetica",
+    "serif": "Times",
+    "monospace": "Menlo",
+    "cursive": "Apple Chancery",
+    "fantasy": "Papyrus",
+}
+
+# A donor must cover EVERY character we have a Mac advance for, and must be able
+# to carry each of those advances independently. Two separate failures made both
+# halves of that non-negotiable:
+#
+#   coverage - the scorer will otherwise pick whichever face shares the FEWEST
+#     codepoints with the target, because a small subset is trivially easy to
+#     fit. An early run handed fourteen families to Noto Sans Symbols, which
+#     covers 64 of the 199 captured characters. Even one missing character is a
+#     leak, not a rounding error: Chrome falls back to a DIFFERENT font for it,
+#     so the width comes from that font instead. Carlito-Bold lacks U+00A0, and
+#     that single gap put Chalkboard's no-break space 19.7% off the Mac.
+#
+#   distinct glyphs - a donor that maps two characters to one glyph can only
+#     give them one advance. That is fine when the Mac agrees, but 21 of the
+#     measured macOS faces give U+00A0 a different advance from U+0020 (Geneva
+#     and Charter double it, Hoefler Text more than triples it, Skia halves it),
+#     and a shared glyph silently drops the difference.
+#
+# 148 of the 176 full-coverage donors put U+00A0 on its own glyph, so requiring
+# both costs nothing in donor choice and needs no glyph surgery.
+REQUIRE_FULL_COVERAGE = True
+
+
+def log(msg):
+    print(f"[build-metric-fonts] {msg}", flush=True)
+
+
+def candidate_files():
+    """Every installed font file, from fontconfig, newest-style paths first."""
+    try:
+        raw = subprocess.run(
+            ["fc-list", "--format", "%{file}\n"],
+            capture_output=True, text=True, check=True,
+        ).stdout
+    except (subprocess.CalledProcessError, FileNotFoundError) as err:
+        sys.exit(f"fc-list unavailable: {err}")
+    files = sorted({line.strip() for line in raw.splitlines() if line.strip()})
+    # Collections and bitmap-only faces are not usable donors here.
+    return [f for f in files if f.lower().endswith((".ttf", ".otf"))]
+
+
+def face_style(font):
+    """"regular", "bold", "italic", "bolditalic", or None for anything else.
+
+    Read from the font's own tables rather than from its filename. The filename
+    test this replaces missed every "-BoldItalic" file, because a word-boundary
+    match for "bold" does not fire in "BoldItalic" - so the first run picked
+    Tinos-BoldItalic as the donor for Apple Chancery and Inter-SemiBoldItalic for
+    the system face, handing both the wrong proportions before any advance was
+    written.
+    """
+    try:
+        italic = bool(font["head"].macStyle & 0b10)
+        bold = bool(font["head"].macStyle & 0b1)
+        os2 = font.get("OS/2")
+        if os2 is not None:
+            italic = italic or bool(os2.fsSelection & 0b1)
+            bold = bold or bool(os2.fsSelection & 0b100000)
+            weight = os2.usWeightClass
+            # Light, black and other weights are not donors for any of the four
+            # faces we build: their proportions are a different cut.
+            if bold or weight >= 600:
+                if not 600 <= weight <= 800:
+                    return None
+                bold = True
+            elif not 350 <= weight <= 450:
+                return None
+        if bold and italic:
+            return "bolditalic"
+        if bold:
+            return "bold"
+        return "italic" if italic else "regular"
+    except Exception:
+        return None
+
+
+def load_donor(path):
+    """Read a candidate's per-codepoint advances, in em. None if unusable."""
+    try:
+        font = TTFont(path, fontNumber=0, lazy=True)
+        style = face_style(font)
+        if style is None:
+            font.close()
+            return None
+        upem = font["head"].unitsPerEm
+        cmap = font.getBestCmap()
+        hmtx = font["hmtx"]
+        if not cmap or not upem:
+            return None
+        advances = {}
+        glyphs = {}
+        for cp, glyph_name in cmap.items():
+            try:
+                advances[cp] = hmtx[glyph_name][0] / upem
+            except KeyError:
+                continue
+            glyphs[cp] = glyph_name
+        font.close()
+        # `glyphs` is kept so the matcher can tell whether this donor can carry
+        # two characters' advances independently; see REQUIRE_FULL_COVERAGE.
+        return {"style": style, "advances": advances, "glyphs": glyphs}
+    except Exception:  # a broken or exotic file is simply not a donor
+        return None
+
+
+def can_carry(target, donor):
+    """True when this donor can reproduce every one of the target's advances.
+
+    Rejects a donor that is missing any captured character, and one that maps two
+    characters needing DIFFERENT advances onto a single glyph - it could only
+    give them one. See REQUIRE_FULL_COVERAGE.
+    """
+    glyphs = donor["glyphs"]
+    required = {}
+    for cp, want in target.items():
+        if want <= 0:
+            continue
+        glyph = glyphs.get(cp)
+        if glyph is None:
+            return False
+        # Same rounding the writer uses, so this asks the question that actually
+        # matters: would the two land on different font units?
+        units = round(want * 1000)
+        if required.setdefault(glyph, units) != units:
+            return False
+    return True
+
+
+def shape_distance(target, cand):
+    """Best-fit-scale RMS distance, normalised. Lower is a better donor."""
+    shared = [cp for cp, v in target.items() if cand.get(cp, 0) > 0 and v > 0]
+    if not shared:
+        return None
+    tc = sum(target[cp] * cand[cp] for cp in shared)
+    cc = sum(cand[cp] ** 2 for cp in shared)
+    if cc == 0:
+        return None
+    k = tc / cc
+    err = sum((k * cand[cp] - target[cp]) ** 2 for cp in shared)
+    mag = sum(target[cp] ** 2 for cp in shared)
+    return (err / mag) ** 0.5
+
+
+def set_names(font, family, style="regular"):
+    """Rename the face to `family`, and to nothing else.
+
+    The donor's own names are dropped rather than edited: a leftover
+    typographic-family record (nameID 16) would let the donor be identified by
+    name even though every metric says otherwise, which is the same class of
+    contradiction this whole exercise removes.
+    """
+    name = font["name"]
+    subfamily = {"regular": "Regular", "bold": "Bold",
+                 "italic": "Italic", "bolditalic": "Bold Italic"}[style]
+    suffix = "" if style == "regular" else f"-{subfamily.replace(' ', '')}"
+    postscript = re.sub(r"[^A-Za-z0-9]", "", family) + suffix
+    full = family if style == "regular" else f"{family} {subfamily}"
+    values = {
+        1: family,
+        2: subfamily,
+        # nameID 3 is the unique identifier. It is not reachable from a page, but
+        # it IS a plain string in a file we ship, so it says nothing a grep for
+        # "anti-detect" would find - the same rule the binary's log strings are
+        # held to. Family plus style is unique enough for fontconfig.
+        3: full,
+        4: full,
+        6: postscript,
+    }
+    name.names = []
+    for name_id, value in values.items():
+        name.setName(value, name_id, 3, 1, 0x409)  # Windows / Unicode BMP / en-US
+        name.setName(value, name_id, 1, 0, 0)      # Mac / Roman / English
+
+
+def set_kerning(font, pairs, upem):
+    """Replace the donor's kerning with the Mac's measured pairs.
+
+    A string's width is the sum of its advances PLUS the kerning of each adjacent
+    pair, and Chrome kerns by default - so a face with exact advances and the
+    donor's kern pairs still measures wrong. On the reference Mac the 26-glyph
+    sample string carries -10.63px of kerning at 64px in Futura and -7.09px in
+    Times; 24 of 34 families kern it by more than half a pixel.
+
+    The donor's own positioning is dropped rather than merged. GPOS carries the
+    donor's kern feature, and a leftover pair would add to the one written here -
+    the two tables do not overwrite each other, they accumulate.
+    """
+    # GSUB goes too, not just the positioning tables.
+    #
+    # The captured value for a pair is the whole width change Chrome applies
+    # between those two characters - kerning, but also any ligature or contextual
+    # substitution, since all of them show up in width(ab) - width(a) - width(b).
+    # So the capture already describes everything the Mac does to a pair, and any
+    # substitution the DONOR brings is a second, unmeasured effect on top.
+    #
+    # It is not hypothetical: measured in the container, system-ui had 2040
+    # non-zero pairs against the Mac's 938 and Futura 1550 against 392, while
+    # Times - whose donor carries almost no substitutions - had exactly the Mac's
+    # 94. Those extras cancelled most of the kerning we had just written in, so
+    # the sample string came out barely kerned at all.
+    for table in ("GPOS", "GSUB", "kern"):
+        if table in font:
+            del font[table]
+    if not pairs:
+        return 0
+
+    cmap = font.getBestCmap()
+    rules = []
+    for text, value in pairs.items():
+        if len(text) != 2:
+            continue
+        left = cmap.get(ord(text[0]))
+        right = cmap.get(ord(text[1]))
+        if left is None or right is None:
+            continue
+        units = int(round(value * upem))
+        if units:
+            rules.append((left, right, units))
+    if not rules:
+        return 0
+
+    # feaLib is the supported way to attach a kern feature; hand-assembling the
+    # GPOS subtables would mean owning coverage ordering and class definitions.
+    lines = ["languagesystem DFLT dflt;", "languagesystem latn dflt;", "feature kern {"]
+    for left, right, units in rules:
+        lines.append(f"    pos {left} {right} {units};")
+    lines.append("} kern;")
+    with tempfile.NamedTemporaryFile("w", suffix=".fea", delete=False, encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+        fea_path = handle.name
+    try:
+        addOpenTypeFeatures(font, fea_path, tables=["GPOS"])
+    finally:
+        os.unlink(fea_path)
+    return len(rules)
+
+
+def infer_units_per_em(ink_row):
+    """The units-per-em the Mac's own copy of this face uses.
+
+    It is recoverable from the capture because every metric a Mac reports for a
+    real face is a whole number of that face's font units, so the em values are
+    exact multiples of 1/upem. Measured across the 260-face capture: 102 faces
+    are 2048/em and 29 are 1000/em.
+
+    It matters because the binary snaps each metric to size/unitsPerEm of the
+    font it RESOLVED, so a generated face inheriting its donor's 1000/em grid
+    would answer on a 1/1000 grid where the Mac's Helvetica answers on 1/2048 -
+    and a page that knows Helvetica is a 2048/em face on macOS can check that
+    directly. Matching the upem is what makes the C++ snap land on the same grid
+    the Mac uses.
+
+    Faces where neither candidate fits are the ones the Mac SYNTHESISES - its own
+    embolden and skew put the result off any grid - and 2048 is returned for them
+    because it is the commonest real value and the snap has to pick something.
+    """
+    if not ink_row:
+        return 2048
+    for candidate in (1000, 2048):
+        total = 0
+        on_grid = 0
+        for box in ink_row.values():
+            for value in box[1:]:
+                if value == 0:
+                    continue
+                total += 1
+                units = value * candidate
+                # The capture is rounded to 1e-6 em, so allow a little slack.
+                if abs(units - round(units)) < 0.004:
+                    on_grid += 1
+        if total and on_grid / total > 0.995:
+            return candidate
+    return 2048
+
+
+def set_ink_boxes(font, ink, upem, cmap):
+    """Fit every glyph's OUTLINE to the ink box the Mac reports for it.
+
+    Writing advances fixes how far the pen moves and says nothing about where the
+    paint lands, and both are readable from one measureText call:
+    actualBoundingBoxLeft / Right / Ascent / Descent are the glyph's bounding box.
+    Measured three-way against real Chrome by text-raster-probe.mjs, advances were
+    exact while the container's ink boxes were out by up to 27.4% - Menlo ascent
+    -18.2%, Menlo left +27.4%, Helvetica left +19.6%, Times left -21.1% - because
+    the boxes were still the DONOR's. Verdana and Arial, whose donors happen to
+    have similar proportions, sat under 1.4%, which is what makes the error
+    per-family and therefore a family-by-family tell rather than a global offset.
+
+    The advance is untouched here: it lives in hmtx, the outline in glyf, so a
+    glyph can be moved and scaled inside an advance that stays exactly as
+    captured. That is what makes both surfaces satisfiable at once, and it is why
+    this is a per-glyph affine rather than a per-face scale - the Mac's error is
+    per glyph, and fit-advance-model.mjs already showed per-face correction does
+    not generalise.
+
+    Returns (patched, skipped, cleared, worst_scale) where worst_scale is the
+    largest single-axis stretch applied, so a donor that had to be distorted
+    beyond recognition is visible in the log rather than silently shipped.
+    """
+    # Both outline formats, because most donors are the second one. The URW and
+    # Nimbus faces the donor scorer prefers are .otf, so a glyf-only version of
+    # this transformed one face out of nine in the first smoke run and reported
+    # "ink 0" for the rest - it looked like a no-op rather than an unsupported
+    # format, which is the failure mode worth naming here.
+    glyf = font.get("glyf")
+    cff = font.get("CFF ")
+    charstrings = None
+    if glyf is None:
+        if cff is None or not ink:
+            return 0, 0, 0, 1.0
+        charstrings = cff.cff.topDictIndex[0].CharStrings
+    if not ink:
+        return 0, 0, 0, 1.0
+
+    hmtx = font["hmtx"]
+    glyph_set = font.getGlyphSet()
+
+    def write_outline(name, recording, transform):
+        """Replace one glyph's outline, in whichever format this font uses."""
+        if glyf is not None:
+            pen = TTGlyphPen(None)
+            recording.replay(TransformPen(pen, transform) if transform else pen)
+            glyf[name] = pen.glyph()
+            glyf[name].recalcBounds(glyf)
+            return glyf[name].xMin
+        existing = charstrings[name]
+        pen = T2CharStringPen(hmtx[name][0], None)
+        recording.replay(TransformPen(pen, transform) if transform else pen)
+        replacement = pen.getCharString(private=existing.private,
+                                        globalSubrs=existing.globalSubrs)
+        # Program rather than object replacement, and the bytecode dropped with
+        # it: a T2CharString compiles from its cached bytecode when it has one,
+        # so assigning only .program leaves the ORIGINAL outline in the saved
+        # file while every offline check reads the new one.
+        existing.program = replacement.program
+        existing.bytecode = None
+        bounds = BoundsPen(None)
+        recording.replay(TransformPen(bounds, transform) if transform else bounds)
+        return int(round(bounds.bounds[0])) if bounds.bounds else 0
+
+    # First codepoint wins, as with advances. A donor mapping two characters onto
+    # one glyph cannot give them different boxes any more than it can give them
+    # different advances, and can_carry() already rejects donors that do that for
+    # advances - which is the stricter test, since two characters sharing a glyph
+    # share its box on a Mac as well.
+    per_glyph = {}
+    for cp, box in ink.items():
+        name = cmap.get(cp)
+        if name is not None and name not in per_glyph:
+            per_glyph[name] = box
+
+    # Decompose EVERY glyph before writing ANY of them.
+    #
+    # DecomposingRecordingPen resolves a composite through the live glyph set, so
+    # writing as we went would let a composite - every accented Latin-1 letter is
+    # one - be decomposed against a base glyph this loop had already scaled, and
+    # then scaled a second time by its own factor. Recording first means every
+    # glyph is read from the pristine outlines.
+    recorded = {}
+    unreadable = 0
+    for name in per_glyph:
+        rec = DecomposingRecordingPen(glyph_set)
+        try:
+            glyph_set[name].draw(rec)
+        except Exception:  # noqa: BLE001 - a donor glyph we cannot read is a skip
+            unreadable += 1
+            continue
+        recorded[name] = rec
+
+    patched = skipped = cleared = 0
+    skipped += unreadable
+    worst_scale = 1.0
+    for name, (_advance, left, right, ascent, descent) in per_glyph.items():
+        # The capture is in em and signed as the TextMetrics fields are:
+        # actualBoundingBoxLeft is positive LEFTWARDS, so xMin is its negation.
+        target = (-left * upem, -descent * upem, right * upem, ascent * upem)
+        target_blank = (target[2] - target[0]) <= 0 and (target[3] - target[1]) <= 0
+
+        rec = recorded.get(name)
+        if rec is None:
+            continue
+        if not rec.value:
+            # Blank donor glyph. Nothing to fit, and nothing to fit it to unless
+            # the Mac draws something here - in which case the donor simply
+            # cannot express this character and the advance still carries.
+            if not target_blank:
+                skipped += 1
+            continue
+        if target_blank:
+            # The Mac paints nothing and the donor paints something: a space that
+            # draws is visible ink no Mac produces, so remove it rather than
+            # scale it to nothing (a zero scale collapses to a degenerate
+            # contour, which some rasterisers still hint into a dot).
+            empty = DecomposingRecordingPen(glyph_set)
+            write_outline(name, empty, None)
+            hmtx[name] = (hmtx[name][0], 0)
+            cleared += 1
+            continue
+
+        # True bounds including curve extrema, computed from the pristine
+        # recording so it is identical for glyf and CFF donors. A control-point
+        # box would overstate a curved glyph and scale it too small.
+        bounds = BoundsPen(None)
+        rec.replay(bounds)
+        if bounds.bounds is None:
+            skipped += 1
+            continue
+        current = bounds.bounds
+        scale = []
+        offset = []
+        for axis in (0, 1):
+            span_now = current[axis + 2] - current[axis]
+            span_target = target[axis + 2] - target[axis]
+            if span_now > 0 and span_target > 0:
+                factor = span_target / span_now
+            else:
+                # A zero extent on one axis - an underscore has no width above
+                # the baseline, a hyphen no descent - cannot be scaled into a
+                # non-zero one. Translate that axis and leave its size alone.
+                factor = 1.0
+            scale.append(factor)
+            offset.append(target[axis] - current[axis] * factor)
+            worst_scale = max(worst_scale, factor, 1 / factor if factor > 0 else 1.0)
+
+        # Write, MEASURE WHAT WAS WRITTEN, and correct. The arithmetic above is
+        # exact - an affine maps a curve's extremum to the transformed extremum -
+        # but the file does not always agree with it, because the pen rounds
+        # coordinates to integers and re-encodes the contour on the way out.
+        # Measured on Verdana's 'u': the transform predicted yMax 1117 and the
+        # written glyph measured 1091, 26 units short, while 'n' and 'o' through
+        # the same code landed exactly. Whatever the pen did there, a single
+        # open-loop write cannot see it.
+        #
+        # So the target is treated as a fixed point and iterated to. Two or three
+        # passes cost a few pen replays per glyph and make the result a property
+        # of the written file rather than of the arithmetic. verify-metric-fonts.py
+        # then re-reads the saved font independently, so a failure to converge is
+        # caught rather than assumed away.
+        new_xmin = None
+        for _attempt in range(4):
+            new_xmin = write_outline(name, rec, (scale[0], 0, 0, scale[1], offset[0], offset[1]))
+            written = DecomposingRecordingPen(glyph_set)
+            glyph_set[name].draw(written)
+            check = BoundsPen(None)
+            written.replay(check)
+            if check.bounds is None:
+                break
+            residual = max(abs(check.bounds[axis] - target[axis]) for axis in range(4))
+            if residual <= 0.5:
+                break
+            for axis in (0, 1):
+                span_written = check.bounds[axis + 2] - check.bounds[axis]
+                span_target = target[axis + 2] - target[axis]
+                if span_written > 0 and span_target > 0:
+                    scale[axis] *= span_target / span_written
+                # Recomputed from the PRISTINE bounds, not nudged from the last
+                # offset: the scale just changed, and an offset that was correct
+                # for the old scale is not correct for the new one.
+                offset[axis] = target[axis] - current[axis] * scale[axis]
+                worst_scale = max(worst_scale, scale[axis],
+                                  1 / scale[axis] if scale[axis] > 0 else 1.0)
+        # lsb must agree with the outline it describes. Chrome derives the ink box
+        # from the contours, but a disagreeing lsb is malformed and shapers do
+        # read it, so it is written rather than left describing the old shape.
+        hmtx[name] = (hmtx[name][0], new_xmin)
+        patched += 1
+
+    return patched, skipped, cleared, worst_scale
+
+
+def build(family, target, donor_path, out_dir, style="regular", pairs=None, ink=None):
+    font = TTFont(donor_path, fontNumber=0)
+
+    # A variable donor must be pinned first: its HVAR deltas would otherwise be
+    # applied on top of the advances we are about to write, and the face would
+    # measure as neither the Mac nor the donor.
+    if "fvar" in font:
+        axes = {a.axisTag: a.defaultValue for a in font["fvar"].axes}
+        font = instancer.instantiateVariableFont(font, axes, inplace=True, updateFontNames=False)
+
+    # Match the Mac face's units-per-em BEFORE anything is measured or written.
+    # Order matters twice over: the binary snaps every metric to size/upem of the
+    # resolved font, so the grid has to be the Mac's; and rescaling afterwards
+    # would re-round advances and ink boxes that had just been fitted, undoing
+    # the fit at the last step. A 2048 grid also halves the rounding error a
+    # 1000/em donor imposes on every value.
+    target_upem = infer_units_per_em(ink)
+    if font["head"].unitsPerEm != target_upem:
+        scale_upem(font, target_upem)
+
+    upem = font["head"].unitsPerEm
+    cmap = font.getBestCmap()
+    hmtx = font["hmtx"]
+
+    # can_carry() has already rejected donors that cannot express every advance,
+    # so a disagreement here means the donor filter and this writer are applying
+    # different rules and the face would silently ship a wrong advance. Count
+    # them; the caller asserts the count is zero.
+    # Outlines first, advances second. set_ink_boxes preserves the advance it
+    # finds and rewrites lsb; the advance writer below preserves the lsb it finds.
+    # Either order works, but this one leaves hhea.advanceWidthMax computed after
+    # both have run.
+    ink_patched, ink_skipped, ink_cleared, ink_worst = set_ink_boxes(font, ink, upem, cmap)
+
+    per_glyph = {}
+    conflicts = 0
+    missing = 0
+    for cp in sorted(target):
+        glyph_name = cmap.get(cp)
+        if glyph_name is None or glyph_name not in hmtx.metrics:
+            missing += 1
+            continue
+        units = int(round(target[cp] * upem))
+        if glyph_name in per_glyph:
+            if per_glyph[glyph_name] != units:
+                conflicts += 1
+            continue
+        per_glyph[glyph_name] = units
+
+    for glyph_name, units in per_glyph.items():
+        _, lsb = hmtx[glyph_name]
+        hmtx[glyph_name] = (max(units, 0), lsb)
+
+    # hhea must agree with hmtx or the face is malformed; a renderer that
+    # believes advanceWidthMax can lay out past the glyphs it then draws.
+    font["hhea"].advanceWidthMax = max(a for a, _ in hmtx.metrics.values())
+
+    kern_pairs = set_kerning(font, pairs, upem)
+
+    set_names(font, family, style)
+
+    # The style bits have to say what this face is, or fontconfig matches it for
+    # unstyled text too and Skia never synthesises anything - a page would get
+    # the bold advances for regular text.
+    is_bold = style in ("bold", "bolditalic")
+    is_italic = style in ("italic", "bolditalic")
+    font["head"].macStyle = (font["head"].macStyle & ~0b11) | (0b1 if is_bold else 0) | (0b10 if is_italic else 0)
+    if font.get("OS/2") is not None:
+        selection = font["OS/2"].fsSelection & ~0b1100001  # clear italic, bold, regular
+        if is_bold:
+            selection |= 0b100000
+        if is_italic:
+            selection |= 0b1
+        if not is_bold and not is_italic:
+            selection |= 0b1000000  # REGULAR
+        font["OS/2"].fsSelection = selection
+        font["OS/2"].usWeightClass = 700 if is_bold else 400
+    # A face that claims italic in its name table but reports a zero slant is
+    # incoherent, and fontconfig scores matches on the slant it reads here.
+    if is_italic and font.get("post") is not None and font["post"].italicAngle == 0:
+        font["post"].italicAngle = -12.0
+
+    file_suffix = {"regular": "Regular", "bold": "Bold",
+                   "italic": "Italic", "bolditalic": "BoldItalic"}[style]
+    out_path = os.path.join(out_dir, f"{re.sub(r'[^A-Za-z0-9]', '', family)}-{file_suffix}.ttf")
+    font.save(out_path)
+    font.close()
+    return (out_path, len(per_glyph), conflicts, missing, kern_pairs,
+            {"patched": ink_patched, "skipped": ink_skipped,
+             "cleared": ink_cleared, "worstScale": round(ink_worst, 3),
+             "unitsPerEm": upem})
+
+
+# Families that stay on a fontconfig alias, because a Latin donor cannot stand in
+# for them: the CJK and script faces (where the donor would have no glyphs at
+# all) and the emoji/symbol faces. The Mac advance capture covers Latin, so these
+# are outside what this generator can build honestly.
+STILL_ALIASED = {
+    "Apple Color Emoji": "Noto Color Emoji",
+    "Apple Symbols": "Noto Sans Symbols",
+    "Apple Braille": "DejaVu Sans",
+    "STIX Two Math": "DejaVu Serif",
+    "Apple SD Gothic Neo": "Noto Sans CJK KR",
+    "AppleGothic": "Noto Sans CJK KR",
+    "Heiti SC": "Noto Sans CJK SC",
+    "Heiti TC": "Noto Sans CJK TC",
+    "PingFang SC": "Noto Sans CJK SC",
+    "PingFang TC": "Noto Sans CJK TC",
+    "Hiragino Kaku Gothic ProN": "Noto Sans CJK JP",
+    "Hiragino Sans": "Noto Sans CJK JP",
+    "Hiragino Mincho ProN": "Noto Serif CJK JP",
+    "Songti SC": "Noto Serif CJK SC",
+    "Songti TC": "Noto Serif CJK TC",
+    "Sukhumvit Set": "Noto Sans Thai",
+}
+
+# What the CSS generics resolve to on macOS, stated explicitly rather than left
+# to fontconfig's Linux defaults (which point at DejaVu, a family the binary's
+# canvas allowlist then blocks - leaving generic text on the last-resort font).
+GENERIC_RULES = GENERIC_TARGETS
+
+# `-apple-system` is a CSS keyword rather than a font file even on a Mac; it has
+# to reach the same face system-ui does.
+NAME_ALIASES = {"-apple-system": "BlinkMacSystemFont"}
+
+
+def write_fontconfig(path, built):
+    """Emit the alias file that goes with the generated faces.
+
+    It is short now, and that is the point: a family we BUILT needs no alias,
+    because it exists. What remains is the handful a Latin donor cannot stand in
+    for, plus the generics.
+    """
+    rules = []
+    for family, target in sorted(GENERIC_RULES.items()):
+        rules.append((family, target, "CSS generic; macOS resolves it here"))
+    for family, target in sorted(NAME_ALIASES.items()):
+        rules.append((family, target, "same face under its CSS keyword"))
+    for family, target in sorted(STILL_ALIASED.items()):
+        if family in built:
+            continue
+        rules.append((family, target, "no Latin donor can stand in; stays aliased"))
+
+    lines = [
+        '<?xml version="1.0"?>',
+        '<!DOCTYPE fontconfig SYSTEM "fonts.dtd">',
+        "<!--",
+        "  macOS family substitutions that remain after the per-family metric fonts.",
+        "",
+        "  Generated by build-metric-fonts.py. Do not edit by hand.",
+        "",
+        f"  {len(built)} families are now REAL font files, installed under their own",
+        "  macOS names and carrying that family's own per-character advances (see",
+        "  build-metric-fonts.py for why). They need no alias, and must not have one:",
+        "  a <match target=\"pattern\"> rewrite is authoritative and would send the",
+        "  request back to a shared clone, which is the collapse this replaced -",
+        "  54 families measuring as 19 distinct faces where a Mac has 41.",
+        "",
+        "  What is left here is what a Latin donor cannot honestly stand in for:",
+        "  the CJK, symbol and emoji faces, plus the CSS generics.",
+        "",
+        "  Deliberately absent: ZapfDingbats and Bookman. Both are in the binary's",
+        "  canvas font allowlist, but measured on macOS 26.5.2 they fall back to",
+        "  Times - the reference Mac does not have them - so they are left to fall",
+        "  back here too.",
+        "-->",
+        "<fontconfig>",
+        "",
+    ]
+    for family, target, why in rules:
+        lines.append(f"  <!-- {family}: {why} -->")
+        lines.append('  <match target="pattern">')
+        lines.append(f'    <test name="family" compare="eq" ignore-blanks="true"><string>{family}</string></test>')
+        lines.append(f'    <edit name="family" mode="assign" binding="same"><string>{target}</string></edit>')
+        lines.append("  </match>")
+        lines.append("")
+    lines.append("</fontconfig>")
+
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+    log(f"wrote {path} ({len(rules)} rules, down from 87)")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--advances", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--only", default="", help="comma-separated subset, for debugging")
+    parser.add_argument("--manifest", default="", help="write the donor choices here")
+    parser.add_argument("--conf", default="", help="write the remaining fontconfig aliases here")
+    parser.add_argument("--kerning", default="", help="per-pair kerning capture from the reference Mac")
+    parser.add_argument("--inkbox", default="",
+                        help="per-character ink box capture (char-metrics-capture.mjs). "
+                             "Without it the faces keep the DONOR's outlines, which "
+                             "measured up to 27.4% off the Mac on actualBoundingBox*.")
+    args = parser.parse_args()
+
+    with open(args.advances, encoding="utf-8") as handle:
+        captured = json.load(handle)["advances"]
+
+    # Without this the faces carry the DONOR's kern pairs, which is a 0.2-1.0%
+    # error on any string with a kerning pair in it.
+    kerning = {}
+    if args.kerning:
+        with open(args.kerning, encoding="utf-8") as handle:
+            kerning = json.load(handle)["kerning"]
+        log(f"kerning capture: {len(kerning)} faces")
+    else:
+        log("WARNING: no --kerning capture; faces will have NO kerning at all")
+
+    # The outlines. Without this every ink extent stays the donor's, which is a
+    # per-family error a page reads from the same measureText call as the width.
+    ink_boxes = {}
+    if args.inkbox:
+        with open(args.inkbox, encoding="utf-8") as handle:
+            payload = json.load(handle)
+        fields = payload.get("fields")
+        # The order is load-bearing: set_ink_boxes unpacks these positionally, and
+        # silently reading ascent as right would distort every glyph in the bundle.
+        if fields != ["width", "left", "right", "ascent", "descent"]:
+            sys.exit(f"--inkbox field order is {fields}, expected "
+                     "['width', 'left', 'right', 'ascent', 'descent']")
+        ink_boxes = payload["metrics"]
+        log(f"ink box capture: {len(ink_boxes)} faces")
+    else:
+        log("WARNING: no --inkbox capture; faces will keep the DONOR's outlines")
+
+    only = {s.strip() for s in args.only.split(",") if s.strip()}
+    # "Family" is the regular face; "Family|bold" is the bold one, captured
+    # separately because a Mac's bold is a real face with its own advances -
+    # 2.4% wider than regular for Optima, 13.5% for Georgia - and not a smear of
+    # the regular one. Italic is deliberately NOT captured or built: measured on
+    # the reference Mac, italic advances are within 1% of regular for every
+    # family checked (identical for Helvetica, Arial and Verdana), so the
+    # synthesised oblique Skia produces from the regular face is already right.
+    def clean(row):
+        return {int(cp): adv for cp, adv in row.items() if isinstance(adv, (int, float)) and adv > 0}
+
+    # A face built under a second name is captured under the first one.
+    def source_name(family):
+        return EXTRA_NAMES.get(family, family)
+
+    def row_for_style(family, style):
+        suffix = {"regular": "", "bold": "|bold", "italic": "|italic",
+                  "bolditalic": "|bold italic"}[style]
+        return captured.get(f"{source_name(family)}{suffix}")
+
+    targets = {
+        family: clean(row)
+        for family, row in captured.items()
+        if not row.get("unset") and "|" not in family
+        and family not in GENERICS and family not in SKIP
+        and (not only or family in only)
+    }
+    # Drop the families that only fell back during the capture (see
+    # GENERIC_TARGETS). Compared on the raw capture, before the int() keys above.
+    generic_rows = {
+        generic: captured[generic]
+        for generic in GENERIC_TARGETS
+        if generic in captured and not captured[generic].get("unset")
+    }
+    absent = []
+    for family in list(targets):
+        row = captured.get(family)
+        for generic, generic_row in generic_rows.items():
+            if row == generic_row and family != GENERIC_TARGETS[generic]:
+                absent.append(f"{family} (= {generic})")
+                del targets[family]
+                break
+    if absent:
+        log(f"absent on the reference Mac, not built: {', '.join(absent)}")
+
+    for name, source in EXTRA_NAMES.items():
+        if source in targets and (not only or name in only):
+            targets[name] = targets[source]
+    log(f"{len(targets)} families to build")
+
+    os.makedirs(args.out, exist_ok=True)
+
+    donors = {}
+    for path in candidate_files():
+        advances = load_donor(path)
+        if advances:
+            donors[path] = advances
+    log(f"{len(donors)} candidate donor files")
+
+    manifest = {}
+    used = defaultdict(list)
+    for family, target in sorted(targets.items()):
+        # style -> (donor path, captured row), for the faces actually written.
+        built_styles = {}
+        for style in ("regular", "bold", "italic", "bolditalic"):
+            if style != "regular":
+                captured_as = {"bold": "|bold", "italic": "|italic",
+                               "bolditalic": "|bold italic"}[style]
+                row = captured.get(f"{source_name(family)}{captured_as}")
+                if not row or row.get("unset"):
+                    continue
+
+                # Skip only when NOT building the file would land on the same
+                # advances anyway - which means asking what SKIA would synthesise
+                # from, not what CoreText did.
+                #
+                # The two engines disagree, and the disagreement is the whole
+                # point. For bold-italic the Mac synthesises from the BOLD face,
+                # so its bold-italic advances equal its bold ones; Skia picks the
+                # ITALIC face when one exists. Skipping on the Mac's answer left
+                # five script families - Marker Felt, Chalkboard SE, Chalkduster,
+                # Herculanum, Webdings - measuring their italic advances for
+                # bold-italic text, up to 120% off on a character.
+                if style == "bolditalic":
+                    synth = "|italic" if "italic" in built_styles else (
+                        "|bold" if "bold" in built_styles else "")
+                else:
+                    synth = ""
+                if row == captured.get(f"{source_name(family)}{synth}"):
+                    continue
+                target = clean(row)
+
+            # When this style's advances are identical to one already built,
+            # build it from the SAME donor file. Two donors with different
+            # unitsPerEm round the same em value to different font units, which
+            # would make the two faces measurably differ where the Mac has them
+            # exactly equal - the mirror of the collapse this whole exercise
+            # removes.
+            twin = next((st for st, (_, r) in built_styles.items() if r == row_for_style(family, style)), None)
+            if twin:
+                pool = {built_styles[twin][0]: donors[built_styles[twin][0]]}
+            else:
+                # Otherwise match against donors of the SAME style: a regular
+                # donor emboldened or slanted would carry regular proportions
+                # under a bold or italic name.
+                pool = {p: d for p, d in donors.items()
+                        if d["style"] == style and can_carry(target, d)}
+            if not pool:
+                # Falling back across styles is better than shipping no face at
+                # all, but it must still be a donor that can carry the metrics.
+                pool = {p: d for p, d in donors.items() if can_carry(target, d)}
+            if not pool:
+                log(f"  {family} ({style}): no donor can carry these advances - skipped")
+                continue
+
+            best_path, best_distance = None, None
+            for path, donor in pool.items():
+                distance = shape_distance(target, donor["advances"])
+                if distance is None:
+                    continue
+                if best_distance is None or distance < best_distance:
+                    best_path, best_distance = path, distance
+            if best_path is None:
+                log(f"  {family} ({style}): NO DONOR - skipped")
+                continue
+            key = f"{family} {style}"
+            kern_key = {"regular": "", "bold": "|bold", "italic": "|italic",
+                        "bolditalic": "|bold italic"}[style]
+            face_pairs = kerning.get(f"{source_name(family)}{kern_key}", {})
+            if face_pairs.get("unset"):
+                face_pairs = {}
+            ink_key = {"regular": "", "bold": "|bold", "italic": "|italic",
+                       "bolditalic": "|bold italic"}[style]
+            face_ink = ink_boxes.get(f"{source_name(family)}{ink_key}", {})
+            if face_ink.get("unset"):
+                face_ink = {}
+            face_ink = {int(cp): box for cp, box in face_ink.items()
+                        if isinstance(box, list) and len(box) == 5}
+            out_path, patched, conflicts, missing, kern_pairs, ink_stats = build(
+                family, target, best_path, args.out, style, face_pairs, face_ink)
+            # can_carry() screened the donor, so anything here is a bug in the
+            # screen rather than a property of the font. Loud, not silent: a
+            # dropped advance is exactly the kind of miss that measures fine on
+            # the sample string and leaks on everything else.
+            if conflicts or missing:
+                sys.exit(f"{key}: donor {os.path.basename(best_path)} passed can_carry() "
+                         f"but produced {conflicts} conflict(s) and {missing} missing glyph(s)")
+            manifest[key] = {
+                "donor": os.path.basename(best_path),
+                "shapeDistance": round(best_distance, 4),
+                "glyphsPatched": patched,
+                "kernPairs": kern_pairs,
+                "inkBoxes": ink_stats,
+            "unitsPerEm": ink_stats.pop("unitsPerEm", None),
+                "file": os.path.basename(out_path),
+            }
+            built_styles[style] = (best_path, row_for_style(family, style))
+            used[os.path.basename(best_path)].append(family)
+            log(f"  {family:<24} {style:<8} <- {os.path.basename(best_path):<34} "
+                f"Δ{best_distance * 100:5.1f}%  {patched} glyphs  {kern_pairs} kern pairs  "
+                f"ink {ink_stats['patched']}"
+                + (f" (+{ink_stats['cleared']} cleared)" if ink_stats["cleared"] else "")
+                + (f" (-{ink_stats['skipped']} skipped)" if ink_stats["skipped"] else "")
+                + f" x{ink_stats['worstScale']}")
+
+    built_families = {key.rsplit(" ", 1)[0] for key in manifest}
+    if args.conf:
+        write_fontconfig(args.conf, built_families)
+
+    if args.manifest:
+        with open(args.manifest, "w", encoding="utf-8") as handle:
+            json.dump(manifest, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        log(f"wrote {args.manifest}")
+
+    log(f"built {len(manifest)} faces for {len(built_families)} families from {len(used)} distinct donors")
+
+
+if __name__ == "__main__":
+    main()