Skip to content

fix(fonts): resolve observed family aliases deterministically#2768

Open
jrusso1020 wants to merge 2 commits into
mainfrom
fix/deterministic-font-family-aliases
Open

fix(fonts): resolve observed family aliases deterministically#2768
jrusso1020 wants to merge 2 commits into
mainfrom
fix/deterministic-font-family-aliases

Conversation

@jrusso1020

@jrusso1020 jrusso1020 commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator

What

Resolve production-observed font-family spellings that are currently renderable
but fail deterministic distributed font preflight:

  • preserve ten authored family names while fetching verified,
    script-compatible Google families
  • resolve Futura Std and MS Sans Serif through the existing bundled-font
    substitution path
  • share the Google-fetch alias contract with lint so strict checks do not reject
    a family the producer can resolve

Unknown families still fail closed.

Why

font_unresolved is the largest current Hyperframes failure class. In a
fresh six-hour production sample it accounted for 49 completion failures. The
underlying exception logs included retries; deduplicating by workflow showed
28 affected workflows across 11 family spellings. This PR covers 22 of those
28 workflows:

  • the original mappings cover 19 (MS Sans Serif, Noto Sans Greek,
    Pretendard, and Yantra Manav);
  • the current-cohort extension covers 3 more (FredericktheGreat,
    Noto Serif VI, and Pyidaungsu).

The remaining Fira GO, Bungee Stencil, and Yantraavishkar spellings stay
fail-closed because substituting them would risk changing script coverage or
typography. inherit is a CSS cascade/parser issue and is intentionally left
for a separate syntax-aware fix.

The Google CSS2 endpoint does not serve several observed names verbatim even
though a deterministic script-compatible family exists. The producer therefore
reported a customer font_unresolved error for content it can safely render.

How

  • add a distinct GOOGLE_FONT_FAMILY_ALIASES map in the browser-safe parsers
    package
  • re-export it through composition/core for producer and lint consumers
  • query the mapped Google family while emitting injected @font-face rules
    under the original authored family, so existing CSS selectors still match
  • keep this separate from FONT_ALIAS_MAP, whose values mean bundled font
    substitutions
  • recognize the same fetch aliases in font_family_without_font_face

The exact production axis matrix was verified against the official Google Fonts
CSS2 endpoint for every mapped family. Pyidaungsu maps to script-compatible
Noto Sans Myanmar; it is not metrically identical and must be included in
candidate screenshot/parity monitoring.

Test plan

  • Unit tests added/updated
  • Manual testing performed
  • Documentation updated (not applicable)

Validation:

  • producer deterministic-font focused suites: 35 passed
  • lint font rule suite: 46 passed
  • exact Google CSS2 production requests return HTTP 200 and WOFF2 faces for
    every new alias
  • parser, lint, and producer typechecks passed
  • pre-commit tracked-artifact, lint, format, static-analysis, typecheck, and
    commit-message hooks passed
  • independent code review approved the original change and the current-cohort
    extension with no blockers

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant