Web Font Loading skill for Claude Code

#!/usr/bin/env python3
"""Compute CSS fallback-font metric overrides for a web font (stdlib only).

Reads the sfnt tables (head, hhea, OS/2, hmtx, cmap) of a TTF/OTF/WOFF(1) file,
computes a frequency-weighted average character width, and prints an
@font-face block for a local fallback (Arial, Times New Roman, ...) with
size-adjust, ascent-override, descent-override and line-gap-override so the
fallback occupies the same space as the web font and the swap causes no shift.

Usage:
  python3 fallback_metrics.py WEBFONT [--fallback arial|times|PATH] [--family NAME]
  python3 fallback_metrics.py WEBFONT --fallback /System/Library/Fonts/Supplemental/Arial.ttf

WOFF2 needs Brotli (not in the stdlib): pass the original TTF/OTF instead, or
decompress first (e.g. `woff2_decompress font.woff2`).
Exit codes: 0 ok, 1 unreadable/unsupported font, 2 bad arguments.
"""
import argparse
import os
import struct
import sys
import zlib

# English letter frequencies (percent) including space; used to weight widths,
# the same idea capsize/fontaine use for xWidthAvg.
FREQ = {
    " ": 18.3, "e": 10.2, "t": 7.5, "a": 6.5, "o": 6.2, "n": 5.7, "i": 5.7,
    "s": 5.3, "r": 5.0, "h": 4.9, "l": 3.3, "d": 3.3, "u": 2.3, "c": 2.2,
    "m": 2.0, "f": 1.8, "w": 1.7, "g": 1.6, "y": 1.6, "p": 1.5, "b": 1.3,
    "v": 0.8, "k": 0.6, "x": 0.1, "j": 0.1, "q": 0.1, "z": 0.1,
}

# Preset fallbacks. Prefer passing a real path with --fallback when available.
SUP = "/System/Library/Fonts/Supplemental/"
PRESETS = {
    "arial": {"name": "Arial", "upm": 2048, "generic": "sans-serif", "path": SUP + "Arial.ttf"},
    "times": {"name": "Times New Roman", "upm": 2048, "generic": "serif", "path": SUP + "Times New Roman.ttf"},
    "georgia": {"name": "Georgia", "upm": 2048, "generic": "serif", "path": SUP + "Georgia.ttf"},
    "verdana": {"name": "Verdana", "upm": 2048, "generic": "sans-serif", "path": SUP + "Verdana.ttf"},
}
# Weighted widths measured with this script from the macOS copies; used when the
# file is absent (Linux CI). Arial/Times metrics match their Windows versions.
STATIC_AVG = {"arial": 900.7, "times": 816.1}


class FontError(Exception):
    pass


def load_tables(path, index=0):
    with open(path, "rb") as fh:
        data = fh.read()
    tag = data[:4]
    if tag == b"wOF2":
        raise FontError("WOFF2 needs Brotli; pass the TTF/OTF source or decompress it first")
    if tag == b"wOFF":
        num = struct.unpack(">H", data[12:14])[0]
        tables = {}
        for i in range(num):
            off = 44 + i * 20
            t, o, clen, olen, _ = struct.unpack(">4sIIII", data[off:off + 20])
            raw = data[o:o + clen]
            tables[t.decode("latin-1")] = zlib.decompress(raw) if clen < olen else raw
        return tables
    base = 0
    if tag == b"ttcf":
        count = struct.unpack(">I", data[8:12])[0]
        if index >= count:
            raise FontError(f"collection has {count} fonts; index {index} out of range")
        base = struct.unpack(">I", data[12 + 4 * index:16 + 4 * index])[0]
    elif tag not in (b"\x00\x01\x00\x00", b"OTTO", b"true"):
        raise FontError(f"not an sfnt/WOFF font (magic {tag!r})")
    num = struct.unpack(">H", data[base + 4:base + 6])[0]
    tables = {}
    for i in range(num):
        off = base + 12 + i * 16
        t, _, o, ln = struct.unpack(">4sIII", data[off:off + 16])
        tables[t.decode("latin-1")] = data[o:o + ln]
    return tables


def parse_cmap(cmap):
    """Return dict codepoint->glyph id for format 4 or 12 Unicode subtables."""
    n = struct.unpack(">H", cmap[2:4])[0]
    best = None
    for i in range(n):
        pid, eid, off = struct.unpack(">HHI", cmap[4 + i * 8:12 + i * 8])
        fmt = struct.unpack(">H", cmap[off:off + 2])[0]
        unicode_sub = pid == 0 or (pid == 3 and eid in (1, 10))
        if unicode_sub and fmt in (4, 12) and (best is None or fmt == 12):
            best = (fmt, off)
    if best is None:
        raise FontError("no Unicode cmap subtable (format 4 or 12)")
    fmt, off = best
    out = {}
    if fmt == 4:
        segx2 = struct.unpack(">H", cmap[off + 6:off + 8])[0]
        seg = segx2 // 2
        ends = struct.unpack(f">{seg}H", cmap[off + 14:off + 14 + segx2])
        p = off + 16 + segx2
        starts = struct.unpack(f">{seg}H", cmap[p:p + segx2])
        deltas = struct.unpack(f">{seg}h", cmap[p + segx2:p + 2 * segx2])
        ro_pos = p + 2 * segx2
        ranges = struct.unpack(f">{seg}H", cmap[ro_pos:ro_pos + segx2])
        for s in range(seg):
            for cp in range(starts[s], min(ends[s], 0x2FF) + 1):
                if ranges[s] == 0:
                    gid = (cp + deltas[s]) & 0xFFFF
                else:
                    gpos = ro_pos + 2 * s + ranges[s] + 2 * (cp - starts[s])
                    gid = struct.unpack(">H", cmap[gpos:gpos + 2])[0]
                    if gid:
                        gid = (gid + deltas[s]) & 0xFFFF
                out[cp] = gid
    else:
        ngroups = struct.unpack(">I", cmap[off + 12:off + 16])[0]
        for g in range(ngroups):
            s, e, sg = struct.unpack(">III", cmap[off + 16 + g * 12:off + 28 + g * 12])
            for cp in range(s, min(e, 0x2FF) + 1):
                out[cp] = sg + (cp - s)
    return out


def metrics(path, index=0):
    t = load_tables(path, index)
    for need in ("head", "hhea", "hmtx", "cmap"):
        if need not in t:
            raise FontError(f"missing '{need}' table")
    upm = struct.unpack(">H", t["head"][18:20])[0]
    h_asc, h_desc, h_gap = struct.unpack(">hhh", t["hhea"][4:10])
    n_hmetrics = struct.unpack(">H", t["hhea"][34:36])[0]
    asc, desc, gap, source = h_asc, h_desc, h_gap, "hhea"
    x_avg_os2 = None
    if "OS/2" in t and len(t["OS/2"]) >= 78:
        os2 = t["OS/2"]
        x_avg_os2 = struct.unpack(">h", os2[2:4])[0]
        fs_sel = struct.unpack(">H", os2[62:64])[0]
        typo_asc, typo_desc, typo_gap = struct.unpack(">hhh", os2[68:74])
        if fs_sel & (1 << 7):  # USE_TYPO_METRICS
            asc, desc, gap, source = typo_asc, typo_desc, typo_gap, "OS/2 typo (USE_TYPO_METRICS)"
    hmtx = t["hmtx"]
    widths = [struct.unpack(">H", hmtx[i * 4:i * 4 + 2])[0] for i in range(n_hmetrics)]
    cmap = parse_cmap(t["cmap"])
    total = weight = 0.0
    missing = []
    for ch, f in FREQ.items():
        gid = cmap.get(ord(ch), 0)
        if gid == 0:
            missing.append(ch)
            continue
        w = widths[gid] if gid < len(widths) else widths[-1]
        total += w * f
        weight += f
    if weight == 0:
        raise FontError("font maps none of the Latin sample characters")
    return {
        "upm": upm, "ascent": asc, "descent": desc, "lineGap": gap, "source": source,
        "avg": total / weight, "os2_avg": x_avg_os2, "missing": missing,
    }


def pct(x):
    return f"{x * 100:.2f}%"


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("webfont")
    ap.add_argument("--fallback", default="arial", help="arial|times|georgia|verdana or a font file path")
    ap.add_argument("--family", default=None, help="web font family name for the output comment")
    ap.add_argument("--index", type=int, default=0, help="font index inside a .ttc collection")
    a = ap.parse_args()

    try:
        web = metrics(a.webfont, a.index)
    except (OSError, FontError, struct.error) as exc:
        print(f"error: {a.webfont}: {exc}", file=sys.stderr)
        return 1

    fb_key = a.fallback.lower()
    generic = "sans-serif"
    if fb_key in PRESETS:
        preset = PRESETS[fb_key]
        fb_name = preset["name"]
        generic = preset["generic"]
        if os.path.exists(preset["path"]):
            fb = metrics(preset["path"])
            fb_avg, fb_upm = fb["avg"], fb["upm"]
        elif fb_key in STATIC_AVG:
            fb_avg, fb_upm = STATIC_AVG[fb_key], preset["upm"]
            print(f"note: {preset['path']} not found; using built-in {fb_name} width", file=sys.stderr)
        else:
            print(f"error: {preset['path']} not found; pass the fallback font path", file=sys.stderr)
            return 1
    elif os.path.exists(a.fallback):
        try:
            fb = metrics(a.fallback)
        except (OSError, FontError, struct.error) as exc:
            print(f"error: {a.fallback}: {exc}", file=sys.stderr)
            return 1
        fb_avg, fb_upm = fb["avg"], fb["upm"]
        fb_name = os.path.splitext(os.path.basename(a.fallback))[0]
    else:
        print(f"error: unknown fallback '{a.fallback}'", file=sys.stderr)
        return 2

    size_adjust = (web["avg"] / web["upm"]) / (fb_avg / fb_upm)
    ascent = web["ascent"] / web["upm"] / size_adjust
    descent = abs(web["descent"]) / web["upm"] / size_adjust
    line_gap = web["lineGap"] / web["upm"] / size_adjust
    family = a.family or os.path.splitext(os.path.basename(a.webfont))[0]

    print(f"/* web font: {a.webfont}")
    print(f"   unitsPerEm={web['upm']} ascent={web['ascent']} descent={web['descent']} "
          f"lineGap={web['lineGap']} (from {web['source']})")
    print(f"   weighted avg width={web['avg']:.1f} (OS/2 xAvgCharWidth={web['os2_avg']})")
    print(f"   fallback: {fb_name} weighted avg width={fb_avg:.1f} upm={fb_upm} */")
    if web["missing"]:
        print(f"/* warning: web font lacks glyphs for {''.join(web['missing'])!r}; width is approximate */")
    print("@font-face {")
    print(f'  font-family: "{family} Fallback";')
    print(f'  src: local("{fb_name}");')
    print(f"  size-adjust: {pct(size_adjust)};")
    print(f"  ascent-override: {pct(ascent)};")
    print(f"  descent-override: {pct(descent)};")
    print(f"  line-gap-override: {pct(line_gap)};")
    print("}")
    print(f'/* use: font-family: "{family}", "{family} Fallback", {generic}; */')
    return 0


if __name__ == "__main__":
    sys.exit(main())