perf(fonts): self-host Outfit and Source Sans 3; fix /river/ contrast

[sanity]

Fixes the two /river/ problems deferred from #164/#165 — and, along the way, replaces the approach this PR started with.

What changed, in the end

Self-hosted Outfit and Source Sans 3, preloaded, with font-display: optional. That removes font-swap layout shift entirely instead of tuning it.

The PR began as metric-matched fallback @font-face rules (size-adjust tuned to the webfont's width). That got /river/ from 0.163 to 0.013, but it was making the swap cheap rather than removing it: the width match drifts ±4% at body sizes, which left /apps/ at 390px at 0.098 — one line-break from failing — and it carried its own hazards. All of it is deleted; the post-mortem is kept as comments in base.css because both traps are easy to reintroduce.

CLS: every page, both widths, exactly 0.0000

Median of 5, cold context per run, production as the before-control:

page	before 390	before 1280	after (both)
/river/	0.0078	0.1697	0.0000
/ghostkey/	0.1770	0.1469	0.0000
/bug/	0.1711	0.0370	0.0000
/about/	0.0673	0.0929	0.0000
/try/	0.0484	0.0401	0.0000
/donate/	0.0263	0.0095	0.0000
/	0.0019	0.0154	0.0000
/apps/, /quickstart/, /faq/	—	—	0.0000

Four pages were above the 0.1 "poor" threshold. Re-confirmed under Fast 3G and Slow 3G on a cold cache, so the zero is not a localhost artifact.

font-display: optional does not cost the webfont on slow connections. That was the main risk and it was measured: 10/10 cold loads render in the real fonts at Slow 3G (400kb, 2000ms RTT), because the preload puts the font in flight beside the render-blocking stylesheet and throttling slows both equally. The real margin is ~100–150ms of lateness relative to the rest of the page, which is why the 404 bug below was so serious.

Contrast: 4 real failures → 0

--rv-ink-faint #6b7a8d was 4.19:1 behind .rv-brand-tag and 4.38:1 behind .rv-shape-lbl — 11px text, under the 4.5:1 AA floor. Now #5f6d7f: 5.28:1 on white, 4.77:1 on --rv-band, still clearly lighter than --rv-ink-soft so the ink hierarchy holds. Dark's #93a2b3 already passed and is unchanged.

I had been reporting 7 failures on /river/; three were phantoms of my own checker walking past a linear-gradient and comparing white text to the page ground. Pixel-sampled, they measure 6.3–7.4:1 and always passed. Honest count is 4 → 0.

A blocker caught in review

The @font-face URLs were root-absolute while the preload used relURL. Under the Freenet contract build those disagree — the preload gets the /v1/contract/web/<key>/ prefix, the CSS does not — so every face 404s. With optional, a 404 is permanent system-ui, not a slow font, and publish-freenet.yml runs on every push to main but not on PRs, so nothing would have caught it.

Fixed with relative ../fonts/ URLs, which resolve against the stylesheet's own location and are correct under any baseURL. Verified by serving the contract build under its real path prefix.

Other review outcomes

• Dropped both latin-ext faces (−75KB). Not preloaded, so optional guaranteed they were never used — measured 0/12 cold — and the built site has zero latin-ext characters. Fonts are now 61KB total, four files, both variable.
• Source Sans 3's declared range corrected to its real 200 900 axis.
• .md licence renamed .txt; both SIL OFL licences included as OFL requires.
• Zero third-party requests from the main layout — no Google DNS/TCP/TLS on any page load. (layouts/presentations/single.html is standalone and still loads Inter; out of scope.)

Recorded, not changed

• Headings now render at genuine weight 800 (+1.22%: 574→581 at 64px). Production clamped 800→700 because the Google request only asked 400–700. .title and .content h2–h6 ask for 800 and now get it.
• The Source Sans 3 file is Google's subset, which under OFL is a Modified Version bearing the Reserved Font Name "Source". Adobe ships only 150KB statics per weight, so originals would be ~750KB against 29KB. Outfit has no reserved name.
• Weight 800 also means .content h1 is no longer synthesised — the old request topped out at 700.

[AI-assisted - Claude]

https://claude.ai/code/session_01Cwq3ZRYFqSW9rMtGJYqfo2

[sanity]

External review finding addressed (922579a)

Codex caught a real bug in the fallback faces.

Bold was silently lost during the swap window

The heavy faces named src: local('Arial'), which resolves Arial Regular. Declaring that resource as font-weight: 600 700 tells the browser it already is bold, so it neither selects a bold face nor synthesises one. Every 600/700 element — the River wordmark, buttons, strong text, headings — would render at regular weight for the entire font-swap window.

Fixed by naming the bold locals: local('Arial Bold'), local('Arial-BoldMT'), local('Liberation Sans Bold'), local('Helvetica Bold').

My own check had passed it, and shouldn't have

I did test bold, and read the result wrong:

"Outfit Fallback"   400=571  700=549   <- I read this as "bold renders"
Arial               400=576  700=624

The widths differed, so my script printed OK. They differed only because the two faces carry different size-adjust values. The direction was the tell: real Arial gets wider from 400 to 700 (576 → 624), while my fallback got narrower (571 → 549). Dividing the size-adjust back out: 549 / 0.9508 = 577.4 — regular Arial, not bold.

After the fix: 571 → 595, and 595 / 0.9508 = 625.8, matching bold Arial's 624.45. Also confirmed visually with the font request blocked — headings, wordmark and buttons are bold again.

Unchanged by the fix

The heavy size-adjust ratios were already measured against bold Arial (the calibration set font-weight: 600/700 on family Arial, which selects bold), so they are correct now that the face actually serves bold. CLS is unaffected:

page	after fix (median of 3)
/	0.0013
/river/ light	0.0133
/river/ dark	0.0141
/quickstart/	0.0037
/donate/	0.0112

Full sweep still clean: no page errors, no transparent text, no horizontal overflow, 0 contrast failures.

Codex also independently verified the contrast change: #5f6d7f gives 5.28:1 on white, 5.04:1 on the page ground and 4.77:1 on --rv-band #eef4fb, against the old #6b7a8d at 4.38 / 3.96. All above the 4.5 floor on the surfaces it actually lands on.

[AI-assisted - Claude]

[sanity]

Review findings addressed (9300a00)

The High-severity finding was real, reproducible, and would have shipped on merge. Thank you — this one was well caught.

The blocker

@font-face used root-absolute url('/fonts/…') while the preload used relURL. Those agree under the ordinary build and disagree under the contract build. Reproduced before fixing:

preload:  href=/v1/contract/web/TESTKEY123/fonts/outfit-latin.woff2
CSS:      url(/fonts/outfit-latin.woff2)          <- 404 at the gateway

And the consequence is worse than a slow font: with font-display: optional a 404 means the face is never used, so it is permanent system-ui on every load, forever, plus ~61KB preloaded and discarded. publish-freenet.yml runs on every push to main touching hugo-site/** and does not run on PRs, so nothing would have flagged it.

Fixed with relative ../fonts/ URLs rather than templating or extending rewrite-paths.py. The stylesheet is always served from <baseURL>/css/, so ../fonts/ is correct under every baseURL with no build step and nothing to keep in sync. Verified end-to-end by serving the contract build under its real path prefix:

contract/        fonts=[(200,'outfit-latin.woff2'), (200,'source-sans-3-latin.woff2')]  usable={outfit:True, ss3:True}
contract/river/  fonts=[(200,'outfit-latin.woff2'), (200,'source-sans-3-latin.woff2')]  usable={outfit:True, ss3:True}

The ordinary production build still resolves them too.

Also fixed

• Dropped both latin-ext faces and files. Your measurement was decisive: not preloaded → loses the optional block window → 0/12 cold loads. Combined with zero latin-ext characters in the built site, that was 75KB fetched and discarded. Fonts are now 61KB, four files. The comment records that adding one back requires preloading it too.
• Source Sans 3 weight range → 200 900, matching its actual fvar axis. Outfit genuinely is 100 900.
• .md → .txt for the licence.
• Corrected the head.html comment. "No request to Google on any page load" was false — layouts/presentations/single.html is standalone and still loads Inter.
• PR title and body rewritten. You were right that they described the deleted approach; the body now documents self-hosting, optional, the binaries, the licences, and the correct 0.0000 numbers.

Recorded rather than changed, with reasoning

Heading weight 800. Confirmed your measurement independently (/about/ at 64px: production 574/574 clamped, branch 574/581, +1.22%). .title and .content h2–h6 ask for 800 and now get it, so this is the stylesheet being honoured rather than a new design decision. Flagged in the PR body so it is not a surprise.

Source Sans 3 RFN. Genuine point, and the mitigation is worse than the problem: Adobe's release ships only 150KB static OTFs per weight — no variable woff2 — so shipping Originals would be roughly 750KB against 29KB and would defeat this PR. Documented as a known residual. Outfit has no reserved name and is clean.

On your refutation of the optional risk

Worth stating plainly since it was my main worry going in: your Slow 3G measurement (10/10 render in the real fonts) and the delay-isolation showing the cliff at ~100–150ms of relative lateness is the clearest characterisation of this design in the whole thread. It is also exactly why the 404 was catastrophic rather than cosmetic.

I did not add the font regression test you suggested. It is the right idea — the failure is silent and produces no CLS signal — but it belongs with the check-links tooling rather than bolted onto this change.

[AI-assisted - Claude]