Web Font Loading skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Web Font Loading"
  short_description: "Fast fonts, zero layout shift on swap"
  default_prompt: "$web-font-loading Text jumps when our Google Font loads, stop the layout shift"

#!/usr/bin/env python3
"""Compute metric-matched fallback @font-face overrides for a web font.

Reads a TTF, OTF or WOFF (1.0) file with the standard library only, measures its
vertical metrics and a letter-frequency-weighted average glyph width, and prints a
CSS @font-face block that makes a local fallback font (Arial by default) occupy
the same space. This shrinks layout shift when the web font swaps in.

Usage:
  python3 fallback_metrics.py path/to/Font.woff [--family "Inter"] \
      [--fallback arial|times|georgia] [--fallback-file /path/to/Local.ttf]

WOFF2 needs Brotli, which is not in the standard library: decompress first, e.g.
`python3 -m fontTools.ttLib.woff2 decompress Font.woff2` (fonttools), or use the
TTF the WOFF2 was built from.
Exit code 0 on success, 1 on any error.
"""
import argparse
import struct
import sys
import zlib

# Relative frequency of characters in English running text (space included).
# Used to weight glyph advances so the average reflects real paragraphs.
FREQ = {
    " ": 0.1800, "e": 0.1020, "t": 0.0740, "a": 0.0660, "o": 0.0620, "i": 0.0570,
    "n": 0.0570, "s": 0.0530, "h": 0.0500, "r": 0.0490, "d": 0.0350, "l": 0.0330,
    "u": 0.0230, "c": 0.0230, "m": 0.0200, "w": 0.0190, "f": 0.0180, "g": 0.0160,
    "y": 0.0160, "p": 0.0150, "b": 0.0120, "v": 0.0080, "k": 0.0060, "j": 0.0010,
    "x": 0.0010, "q": 0.0008, "z": 0.0007, ",": 0.0100, ".": 0.0090, "T": 0.0030,
    "I": 0.0030, "A": 0.0025, "S": 0.0020, "C": 0.0015, "M": 0.0012,
}

# Built-in fallback metrics, measured with this script's own method from the
# macOS system copies of each font. Pass --fallback-file to measure your own.
# Values are weighted average advance / unitsPerEm.
BUILTIN = {
    "arial": {"local": "Arial", "avg": 0.4403},
    "times": {"local": "Times New Roman", "avg": 0.3997},
    "georgia": {"local": "Georgia", "avg": 0.4382},
}


class FontError(Exception):
    pass


def read_tables(data: bytes) -> dict:
    sig = data[:4]
    tables = {}
    if sig == b"wOF2":
        raise FontError("WOFF2 is Brotli-compressed; decompress to TTF first (see --help)")
    if sig == b"ttcf":
        raise FontError("font collections (.ttc) are not supported; extract one face first")
    if sig == b"wOFF":
        num = struct.unpack(">H", data[12:14])[0]
        for i in range(num):
            off = 44 + i * 20
            tag, offset, comp_len, orig_len, _ = struct.unpack(">4sIIII", data[off:off + 20])
            raw = data[offset:offset + comp_len]
            tables[tag.decode("latin-1")] = zlib.decompress(raw) if comp_len < orig_len else raw
        return tables
    if sig in (b"\x00\x01\x00\x00", b"OTTO", b"true"):
        num = struct.unpack(">H", data[4:6])[0]
        for i in range(num):
            off = 12 + i * 16
            tag, _, offset, length = struct.unpack(">4sIII", data[off:off + 16])
            tables[tag.decode("latin-1")] = data[offset:offset + length]
        return tables
    raise FontError("not a TTF, OTF or WOFF file (unknown signature %r)" % sig)


def parse_cmap(cmap: bytes) -> dict:
    """Return {codepoint: glyph_id} from a format 4 or 12 Unicode subtable."""
    num = struct.unpack(">H", cmap[2:4])[0]
    best = None
    for i in range(num):
        pid, eid, off = struct.unpack(">HHI", cmap[4 + i * 8:12 + i * 8])
        fmt = struct.unpack(">H", cmap[off:off + 2])[0]
        if (pid, eid) in ((3, 10), (0, 4), (0, 6)) and fmt == 12:
            best = (off, 12)
            break
        if (pid, eid) in ((3, 1), (0, 3), (0, 1), (0, 2)) and fmt == 4 and best is None:
            best = (off, 4)
    if best is None:
        raise FontError("no Unicode cmap subtable (format 4 or 12) found")
    off, fmt = best
    mapping = {}
    wanted = {ord(c) for c in FREQ}
    if fmt == 12:
        n_groups = struct.unpack(">I", cmap[off + 12:off + 16])[0]
        for g in range(n_groups):
            start, end, gid = struct.unpack(">III", cmap[off + 16 + g * 12:off + 28 + g * 12])
            for cp in wanted:
                if start <= cp <= end:
                    mapping[cp] = gid + cp - start
        return mapping
    seg_x2 = struct.unpack(">H", cmap[off + 6:off + 8])[0]
    segs = seg_x2 // 2
    ends_at = off + 14
    starts_at = ends_at + seg_x2 + 2
    delta_at = starts_at + seg_x2
    range_at = delta_at + seg_x2
    for s in range(segs):
        end = struct.unpack(">H", cmap[ends_at + s * 2:ends_at + s * 2 + 2])[0]
        start = struct.unpack(">H", cmap[starts_at + s * 2:starts_at + s * 2 + 2])[0]
        delta = struct.unpack(">h", cmap[delta_at + s * 2:delta_at + s * 2 + 2])[0]
        ro_pos = range_at + s * 2
        ro = struct.unpack(">H", cmap[ro_pos:ro_pos + 2])[0]
        for cp in wanted:
            if start <= cp <= end:
                if ro == 0:
                    gid = (cp + delta) & 0xFFFF
                else:
                    gpos = ro_pos + ro + (cp - start) * 2
                    gid = struct.unpack(">H", cmap[gpos:gpos + 2])[0]
                    if gid:
                        gid = (gid + delta) & 0xFFFF
                mapping[cp] = gid
    return mapping


def measure(path: str) -> dict:
    try:
        with open(path, "rb") as fh:
            data = fh.read()
    except OSError as exc:
        raise FontError(str(exc))
    t = read_tables(data)
    for need in ("head", "hhea", "hmtx", "cmap"):
        if need not in t:
            raise FontError("missing required table '%s'" % need)
    upm = struct.unpack(">H", t["head"][18:20])[0]
    asc, desc, gap = struct.unpack(">hhh", t["hhea"][4:10])
    n_hmetrics = struct.unpack(">H", t["hhea"][34:36])[0]
    if "OS/2" in t and len(t["OS/2"]) >= 78:
        os2 = t["OS/2"]
        fs_selection = struct.unpack(">H", os2[62:64])[0]
        if fs_selection & (1 << 7):  # USE_TYPO_METRICS
            asc, desc, gap = struct.unpack(">hhh", os2[68:74])
    hmtx = t["hmtx"]

    def advance(gid: int) -> int:
        idx = min(gid, n_hmetrics - 1)
        return struct.unpack(">H", hmtx[idx * 4:idx * 4 + 2])[0]

    cmap = parse_cmap(t["cmap"])
    total_w = 0.0
    total_f = 0.0
    for ch, f in FREQ.items():
        gid = cmap.get(ord(ch), 0)
        if gid:
            total_w += advance(gid) * f
            total_f += f
    if total_f < 0.5:
        raise FontError("font lacks most basic Latin glyphs; metric matching is not meaningful")
    return {"upm": upm, "ascent": asc, "descent": desc, "lineGap": gap,
            "avg": total_w / total_f / upm}


def pct(x: float) -> str:
    return ("%.2f" % (x * 100)).rstrip("0").rstrip(".") + "%"


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("font")
    ap.add_argument("--family", default="Web Font", help="web font family name used in CSS")
    ap.add_argument("--fallback", default="arial", choices=sorted(BUILTIN))
    ap.add_argument("--fallback-file", help="measure this local font instead of built-in values")
    args = ap.parse_args()
    try:
        web = measure(args.font)
        if args.fallback_file:
            fb_avg = measure(args.fallback_file)["avg"]
            fb_name = args.fallback_file.rsplit("/", 1)[-1].rsplit(".", 1)[0]
        else:
            fb_avg = BUILTIN[args.fallback]["avg"]
            fb_name = BUILTIN[args.fallback]["local"]
    except FontError as exc:
        print("error: %s" % exc, file=sys.stderr)
        return 1
    size_adjust = web["avg"] / fb_avg
    upm = web["upm"]
    print("/* %s: upm=%d ascent=%d descent=%d lineGap=%d avgWidth=%.4fem; fallback avg=%.4fem */"
          % (args.font, upm, web["ascent"], web["descent"], web["lineGap"], web["avg"], fb_avg))
    print("@font-face {")
    print('  font-family: "%s Fallback";' % args.family)
    print('  src: local("%s");' % fb_name)
    print("  size-adjust: %s;" % pct(size_adjust))
    print("  ascent-override: %s;" % pct(web["ascent"] / upm / size_adjust))
    print("  descent-override: %s;" % pct(abs(web["descent"]) / upm / size_adjust))
    print("  line-gap-override: %s;" % pct(web["lineGap"] / upm / size_adjust))
    print("}")
    generic = "serif" if args.fallback in ("times", "georgia") else "sans-serif"
    print('/* use: font-family: "%s", "%s Fallback", %s; */' % (args.family, args.family, generic))
    return 0


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