jumpy-lion 0.1.6-beta.9 → 1.0.0-beta.4

package/browser/fonts/macos-bundle/generated/README.md

@@ -0,0 +1,132 @@
+# Generated per-family macOS metric fonts
+
+One font file per macOS family, each named as that family and carrying that
+family's own per-character advance widths as measured from real Google Chrome
+151 on macOS 26.5.2.
+
+**These files are generated. Do not edit them, and do not hand-tune a single
+advance.** Re-run the generator instead:
+
+```bash
+docker run --rm --platform=linux/amd64 \
+    -v "$PWD/browser/fonts/macos-bundle:/bundle" \
+    -v "$PWD/test/docker-linux/baselines:/baselines:ro" \
+    cdp-crawler-fontgen -c "python3 /bundle/build-metric-fonts.py \
+        --advances /baselines/char-advances-macos-chrome151.json \
+        --kerning /baselines/char-kerning-macos-chrome151.json \
+        --inkbox /baselines/char-inkbox-macos-chrome151.json \
+        --out /bundle/generated \
+        --manifest /bundle/generated/manifest.json \
+        --conf /bundle/41-macos-remaining.conf"
+```
+
+`manifest.json` records which donor each face was built from and how far that
+donor's proportions were from the target.
+
+## Why these exist
+
+The bundle used to reach every macOS family through a fontconfig alias, and one
+clone served many aliases - Liberation Sans stood in for 21 families. Measured
+per character against the reference Mac, 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
+  and seven more were one single face.
+- Optima, Copperplate and Trebuchet MS measured identically, where a Mac has
+  them 20-35% apart.
+
+A page does not need a baseline to use that. It measures two families, compares,
+and any real Mac would have told them apart.
+
+It is not fixable 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`) gave worst-case
+errors of 5.76% and 5.89% against 6.30% for doing nothing, because the error is
+specific to each glyph. Only a per-character correction generalises.
+
+After this change the container measures the same number of distinct advance
+signatures as the Mac, with every family pair agreeing on same-or-different in
+both directions, and every per-character advance within 0.5% (worst 0.39%, which
+is the rounding to integer font units).
+
+The donor's **GSUB is deleted** along with its GPOS, and that is load-bearing. A
+ligature or contextual substitution changes the width of a character pair
+exactly as kerning does, so it lands in the same measurement - and the capture
+already describes everything the Mac does to a pair. Left in place, the donor's
+substitutions cancelled most of the kerning written in: the container reported
+2040 non-zero pair adjustments where the Mac has 938, and Futura 1550 against
+392, while Times (donor: almost no substitutions) had exactly the Mac's 94.
+
+Each face also carries the **Mac's own kerning pairs**, measured the same way
+(`k(a,b) = width(ab) - width(a) - width(b)`) and written in as a GPOS kern
+feature replacing the donor's. That is not a detail: a string's width is the sum
+of its advances plus the kerning of every adjacent pair, so with exact advances
+and the donor's pairs the system face was still uniformly 0.6% wide at every
+size.
+
+Measured against real Chrome 151 on macOS 26.5.2 with both fixes in place:
+kerning pairs match exactly (system-ui 938/938, bold 1563/1563, Futura 392/392,
+zero extra and zero missing), and the system face matches the Mac at **75 of 75
+sizes in both weights, worst -0.02%** - it was 0 of 75 in both before.
+
+All four styles are built - regular, bold, italic, bold-italic - wherever the
+Mac has a real face rather than a synthesised one. That last distinction has to
+be made against **Skia's** synthesis, not the Mac's: for bold-italic the Mac
+synthesises from the bold face while Skia picks the italic face, so trusting the
+Mac's answer left five script families measuring italic advances for bold-italic
+text. Where a style's advances match one already built, it reuses that donor
+file so the two round to identical font units.
+
+Each glyph's **outline is also fitted to the Mac's ink box** - the four
+`actualBoundingBox*` numbers a page reads from the same `measureText` call as the
+width. The advance lives in `hmtx` and the outline in `glyf` / `CFF `, so a glyph
+can be moved and scaled inside an advance that stays exactly as captured, and
+both surfaces are satisfiable at once.
+
+This replaced an explicit decision to leave outlines alone, recorded here as
+"ink bounds differ between two real Macs anyway". Measured, they do not: real
+Chrome on macOS puts every one of them on an exact 1/2048 grid, deterministically
+per family, and the container was out by up to **27.4%** - Menlo ascent -18.2%,
+Menlo left +27.4%, Helvetica left +19.6%, Times left -21.1% - while Verdana and
+Arial, whose donors happen to be proportioned similarly, stayed under 1.4%. That
+per-family spread is what makes it usable: a page measures two families' boxes,
+compares them, and no baseline is needed. Our darwin dist was within 2.88% on the
+same probe, so this was a Linux-only contradiction of the Mac claim.
+
+After fitting: worst edge error 0.47%, median 0.02%, and the worst case is the
+period - a half-unit of rounding is a large fraction of a glyph a few percent of
+an em wide, which is why `verify-metric-fonts.py` scores box edges against the
+box's own span with its own 1% floor rather than reusing the advance tolerance.
+
+## What they do not fix
+
+- **Glyph SHAPES are still the donor's.** Fitting the bounding box makes the ink
+  start and end where the Mac's does; what happens between those edges is the
+  donor's outline, stretched. Text looks wrong wherever the donor is a poor
+  visual match - a script face like Zapfino has no free equivalent - and a
+  detector that hashes canvas PIXELS rather than metrics still sees a different
+  face. Metrics are what collapse families together and what a page can compare
+  without a reference image.
+- **Per-glyph distortion is unbounded.** The scale factor needed to reach the
+  Mac's box is logged per face (`x2.35` and so on) and reaches 4.1 on one italic
+  donor, which means a glyph stretched to four times its natural width in one
+  axis. Correct in metrics, worse in appearance.
+- **Coverage is Latin.** Advances and kerning are captured for ASCII plus the
+  Latin-1 range and common typographic punctuation; Greek, Cyrillic and CJK
+  characters keep the donor's metrics and fall back as before.
+
+## Licensing
+
+Each file is a derivative of a free-licensed donor (OFL 1.1, Apache 2.0 or the
+DejaVu licence - see `donor` in `manifest.json`), modified in two ways: the
+`hmtx` advances are overwritten, and the name table is replaced with the macOS
+family name.
+
+Renaming matters legally. OFL faces carry Reserved Font Names, and these files
+deliberately claim names that are third-party trademarks. **They are for internal
+use only and must not be redistributed**, which is the same footing as the rest
+of the anti-detect browser (GPL-3, internal use, no distribution). The old
+fontconfig alias achieved the same substitution without renaming the files; this
+does it by renaming, because one shared clone cannot carry twenty-one different
+sets of metrics.