fix(fonts): supplement alias faces from the canonical family

[akzarma]

What breaks

A family that resolves through FONT_ALIAS_MAP to a bundled canonical can end up with two different typefaces under one font-family.

font-family: Helvetica with any italic text renders upright as Inter (the canonical bundle) and italic as real Helvetica (fetched from Google under the authored name). Same for Noto Sans, Georgia, Verdana, Garamond and the other cross-typeface aliases — including three that typography.md advertises as safe.

Details, measurements and the alias-by-alias table are in #3083.

Root cause

packages/producer/src/services/deterministicFonts.ts, in buildFontFaceCss:

const googleFaces = await fetchGoogleFont(originalCaseFamily, options, fontText);

The embedded canonical's faces are emitted under the authored family name, and then the weights/styles the bundle lacks are supplemented by querying Google — with the authored name. For a self-referencing alias (montserrat → Montserrat) that is correct. For a cross-typeface alias it fetches the very typeface the alias exists to replace.

Two properties make it bite rather than stay theoretical:

• No CANONICAL_FONTS entry declares style: "italic", so every italic Google serves for the authored name is classified "missing from the bundle" and injected.
• Google's css2 endpoint now serves many of these names (Helvetica, Helvetica Neue, Georgia, Verdana, Tahoma, Trebuchet MS, Garamond, Noto Sans, …), so the comment at fetchGoogleFont assuming alias names 4xx is no longer true for them.

The fix

Query CANONICAL_FONT_DISPLAY_NAMES[canonicalKey] instead of the authored name. It is already re-exported from @hyperframes/core/fonts/aliases, which this file imports.

Faces are still emitted under originalCaseFamily, so authored CSS keeps matching and nothing about the aliasing policy changes — only the source the supplementary faces come from.

Test

deterministicFonts-aliasSupplement.test.ts — hermetic, injects fetchImpl, no network:

• Noto Sans → asserts the supplementary query asks for Inter, that the authored spelling still names the family, and that every injected src is Inter (embedded bundle or Inter fetch) with no real Noto Sans bytes present.
• Montserrat → asserts self-referencing aliases still supplement from their own family (guards against over-correcting).

Verified the test bites: against unfixed deterministicFonts.ts it is 1 pass / 1 fail; with the fix, 2 pass / 0 fail.

Test plan

• bun test packages/producer/src/services/deterministicFonts-aliasSupplement.test.ts → 2 pass, 0 fail
• Same suite against unfixed source → 1 fail, confirming the regression test bites
• oxfmt --check and oxlint on both changed files → clean, 0 warnings / 0 errors
• Full packages/producer unit lane not run — it needs workspace packages built beyond what a fresh clone provides; relying on CI for that

[miguel-heygen]

Reproduced the bug against live Google Fonts, confirmed this branch fixes it, and found one thing I'd like addressed before it lands.

Repro (main, unfixed)

font-family: Helvetica, upright + italic text, real network:

google css2 family= queried: [ "Helvetica" ]
  Helvetica  normal 400  EMBEDDED INTER BUNDLE
  Helvetica  normal 700  EMBEDDED INTER BUNDLE
  Helvetica  normal 900  EMBEDDED INTER BUNDLE
  Helvetica  italic 400  FETCHED FROM GOOGLE
  Helvetica  italic 700  FETCHED FROM GOOGLE

Rendered headless, the upright line is Inter and the italic line is Google's Helvetica substitute. Two typefaces under one font-family, exactly as described. css2?family=Helvetica returns 200 today, so the "alias names 4xx" comment is indeed stale.

With this branch

google css2 family= queried: [ "Inter" ]
  ... italic 400 / 700 now come from Inter

Italic renders as Inter Italic. Bug is gone, and weights 100-800 that previously had no face at all now resolve to real Inter weights. The fix is at the right layer, in the one function every aliased family routes through, and reusing CANONICAL_FONT_DISPLAY_NAMES is the right call: all 18 canonical slugs have an entry and every one is a real Google family.

Blocking: the payload multiplies

Google serves Inter as a variable font, so css2 hands back the same woff2 URL for every static weight. The supplement loop embeds that identical base64 blob once per weight.

One family, Helvetica, compiled HTML:

	faces	unique blobs	HTML
main	5	5	110 KB
this branch	11	5	302 KB

Six @font-face rules (100/200/300/500/600/800) carry byte-identical copies of one 25 KB blob; the two italics are another duplicate pair.

It compounds across aliases, because names that used to 4xx now fetch. Four families that all resolve to Inter (Helvetica, Arial, SF Pro, Verdana):

	faces	unique blobs	HTML
main	16	7	405 KB
this branch	44	5	963 KB

963 KB carrying five distinct fonts. The duplication is pre-existing in the supplement loop, but this PR is what makes it fire on every cross-typeface alias, so I'd rather not land the amplification untouched.

Smallest fix that keeps semantics: when consecutive Google faces share a src, emit one rule with a weight range (font-weight: 100 800) instead of one rule per weight. That is the correct declaration for a variable font anyway and takes the 4-family case back under 300 KB. If you'd rather keep this PR to the one-line correctness fix, that's fine by me, but please open the follow-up and link it here.

Non-blocking

1. ?? originalCaseFamily is unreachable today, and if it ever becomes reachable it silently restores this exact bug. Worth a line in deterministicFonts.test.ts asserting every CANONICAL_FONTS key has a CANONICAL_FONT_DISPLAY_NAMES entry, then the fallback can go.
2. resolveAliasDisplayName() already exists in the same module and does this lookup in one call. Would drop the extra import. Pure taste, ignore if you prefer the explicit map.

Test file looks right to me. It classifies into the unit/bun lane with no manifest edit needed, and the assertions do bite: on unfixed source queriedFamilies is ["Noto Sans"], so the first test fails and the Montserrat guard passes. Matches your 1 pass / 1 fail.

[akzarma]

@miguel-heygen Thanks for the repro and the measurements — the amplification is fair, and I took the weight-range route rather than deferring it.

Consecutive supplementary faces sharing a src, style and unicode-range now collapse into one rule. A run stops at any weight the embedded bundle covers, so a range can't shadow a bundled face — my first attempt emitted font-weight: 100 500 straight across a bundled 400, which the new test caught. The pair is also sorted low-to-high rather than trusting Google's ordering, and a non-numeric or variable-range weight value refuses to collapse rather than guessing.

Both non-blocking notes taken: it uses resolveAliasDisplayName now, and the ?? originalCaseFamily fallback is gone — resolution failure skips the supplement instead of silently re-querying the authored family, with a test asserting every alias resolves so the branch is unreachable.

[miguel-heygen]

R2 at 1a87dcb02. The core fix is valid: resolving the supplementary query through the canonical display name at packages/producer/src/services/deterministicFonts.ts:531-534 eliminates the real mixed-typeface output, and the positive assertions at packages/producer/src/services/deterministicFonts-aliasSupplement.test.ts:111-132 pin both the query family and injected bytes. The earlier resolver/fallback concerns are also cleanly closed.

blocker — the payload collapse does not handle Google’s real no-text= response shape. packages/producer/src/services/deterministicFonts.ts:545-557 only collapses consecutive faces with the same source/style/unicode-range. When extractGoogleFontsText exceeds its 1,700-byte budget and returns undefined (packages/producer/src/services/deterministicFonts.ts:1130-1143), Google returns the normal subset CSS ordered by weight, then unicode subset: 100/latin, 100/latin-ext, 200/latin, 200/latin-ext, etc. A variable font reuses the same source per subset across weights, but those matching faces are never adjacent, so every base64 blob is still emitted once per weight.

I reproduced this against the current code with a hermetic real-shape response: two unicode subsets × weights 100/200/300/500, one shared source per subset, and HTML large enough to omit text=. Expected four emitted blobs (100–300 + 500 for each subset); head emitted eight. The existing test at packages/producer/src/services/deterministicFonts-aliasSupplement.test.ts:135-169 has one subset only, so it cannot falsify this path.

Please group supplementary faces by (dataUri, style, unicodeRange), numerically sort each group, then partition ranges around covered embedded weights; add the interleaved-subset/no-text= case. That also makes the “Google ordering is not guaranteed” claim true structurally instead of relying on adjacency.

Exact-head unit/build/lint lanes are green and the touched suite passes 4/4 locally, but the exact-head regression workflow is also red on style-15-prod visual comparison; rerun or resolve that before the next verdict.

Verdict: REQUEST CHANGES
Reasoning: The alias correctness fix is real and well placed, but the requested payload guard still misses a normal production response path and leaves the amplification intact for larger compositions.

— Magi

[akzarma]

@miguel-heygen R3 pushed — grouped by (source, style, unicode-range) with runs split at covered weights, each run emitted at its first face's position so overlapping unicode-range order survives collapsing, and coverage keys compared numerically. Tests cover the no-text= interleaved shape and the subset ordering; both fail against the previous implementation.

One flag on the ranges: for a genuine variable font, font-weight: 100 300 means an intermediate 150 interpolates rather than clamping. Correct declaration, but a rendering change — better stated than found.

On the red style-15-prod: its baseline looks like it encodes the bug. The recorded output/compiled.html has, under one font-family: "Helvetica", normal 400/700/900 from the @fontsource/inter bundle and italic 400/700 fetched from Google — same shape for "Helvetica Neue". That's the mixing this PR removes, so the render diverges from the recorded video (43/100 checkpoints, concentrated from ~7.7s where the italics appear). The collapse isn't a factor there — every face in that fixture has a distinct source, so nothing collapses. I don't have render infra to re-record it; happy to if you point me at the command.