fix(web): vendor the web fonts instead of loading them from Google
test-web / test (push) Successful in 42s

app.html linked its stylesheet straight from fonts.googleapis.com, with
preconnects to that host and fonts.gstatic.com. A deployed instance has
no outbound network, so those requests never arrive and the whole UI
renders in fallback faces — Georgia for the display face, whatever the
system has for Inter and JetBrains Mono.

This is invisible in development, which is why it survived: the dev
machine has internet, so the fonts load and everything looks right. Only
a real deployment shows the failure.

tools/vendor-fonts.py fetches the three families once and writes them
under web/static/fonts with a generated stylesheet. static/ is copied
into the SvelteKit build, which Go embeds, so the faces travel inside the
binary. 32 woff2 files, 912K.

Two details that matter for correctness rather than size:

Urls in the generated CSS are relative (./Inter-400-latin.woff2), not
absolute. A url() resolves against the stylesheet's own address, so the
directory keeps working when the app is served under a base path;
/fonts/... would not.

Every subset Google slices is kept, with unicode-range intact. The
browser still fetches only the ranges a page uses, so this costs
repository bytes rather than request bytes — and a library full of
Cyrillic or Greek artist names renders instead of falling back mid-list.

The guard asserts the property, not the vendor: any absolute url in a
resource-loading attribute fails, whoever hosts it, since naming Google
would pass the day someone reached for a different CDN. It also checks
preconnect separately (those carry no fetch of their own, so the url
check misses them), strips HTML comments before asserting an absence so
prose describing the forbidden thing cannot satisfy the check, and pins
the font families to tokens.json rather than a hardcoded list.

Falsified against the pre-change app.html: it trips both the external-url
and preconnect assertions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH
This commit is contained in:
2026-09-09 13:49:47 -04:00
co-authored by Claude Opus 5
parent b06a1adfe8
commit 16005054eb
36 changed files with 478 additions and 6 deletions
+6 -6
View File
@@ -30,12 +30,12 @@
}
})();
</script>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500&family=Inter:wght@400;500&family=JetBrains+Mono:wght@400;500&display=swap"
/>
<!-- Fonts are vendored into web/static/fonts by tools/vendor-fonts.py and
served from our own origin. A deployed instance has no outbound
network, so a provider stylesheet would simply never arrive and the
UI would render in fallback faces — hence no font-provider link and
no preconnect to a host we don't run. -->
<link rel="stylesheet" href="%sveltekit.assets%/fonts/fonts.css" />
%sveltekit.head%
<!-- MINSTREL_TOKENS -->
</head>
+80
View File
@@ -0,0 +1,80 @@
import { readFileSync, readdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
// A deployed instance has no outbound network, so every asset the app draws
// itself with has to come from our own origin. This regressed once already
// (the font stylesheet was linked straight from Google), and the failure is
// invisible in development — the dev machine HAS internet, so the fonts load
// fine and only a real deployment renders in fallback faces.
//
// The assertion is on the PROPERTY, not on a vendor: any absolute URL in a
// resource-loading attribute fails, whoever is hosting it. Naming
// `fonts.googleapis.com` would pass the day someone reached for a different
// CDN, which is the same bug.
// fileURLToPath rather than import.meta.dirname: the latter needs Node 20.11+
// and this repo's toolchain is still on 18, where it is silently undefined.
const WEB = join(dirname(fileURLToPath(import.meta.url)), '../..');
/** Strip comments before asserting an ABSENCE — otherwise prose describing
* the forbidden thing satisfies the check that forbids it. */
const stripComments = (html: string) => html.replace(/<!--[\s\S]*?-->/g, '');
/** href/src on anything that makes the browser fetch a subresource. */
const RESOURCE_URL = /<(?:link|script|img|source|iframe)\b[^>]*?\b(?:href|src)\s*=\s*["']([^"']+)["']/gi;
const externalUrlsIn = (html: string) =>
[...stripComments(html).matchAll(RESOURCE_URL)]
.map((m) => m[1])
.filter((u) => /^(?:https?:)?\/\//i.test(u));
describe('the app ships every asset it draws itself with', () => {
test('app.html loads no subresource from a third-party origin', () => {
const html = readFileSync(join(WEB, 'src/app.html'), 'utf8');
expect(externalUrlsIn(html)).toEqual([]);
});
test('app.html does not preconnect or dns-prefetch to any host', () => {
// preconnect carries no href-fetch of its own, so the check above misses
// it — but it is the fingerprint of a third-party asset about to be added.
const html = stripComments(readFileSync(join(WEB, 'src/app.html'), 'utf8'));
const hints = [...html.matchAll(/<link\b[^>]*\brel\s*=\s*["']([^"']+)["'][^>]*>/gi)]
.filter((m) => /\b(?:preconnect|dns-prefetch)\b/i.test(m[1]));
expect(hints.map((m) => m[0])).toEqual([]);
});
test('the vendored font stylesheet exists and points only at local files', () => {
const dir = join(WEB, 'static/fonts');
const css = readFileSync(join(dir, 'fonts.css'), 'utf8');
const urls = [...css.matchAll(/url\(\s*['"]?([^'")]+)['"]?\s*\)/gi)].map((m) => m[1]);
expect(urls.length).toBeGreaterThan(0);
expect(urls.filter((u) => /^(?:https?:)?\/\//i.test(u))).toEqual([]);
// Every referenced file is actually present — a stylesheet pointing at a
// woff2 nobody committed fails exactly like a CDN link would, offline.
const present = new Set(readdirSync(dir));
const missing = urls
.map((u) => u.replace(/^\.\//, ''))
.filter((f) => !present.has(f));
expect(missing).toEqual([]);
});
test('every font family the tokens name is actually vendored', () => {
// Pins the families to the TOKENS rather than to a hardcoded list, so
// swapping a typeface in tokens.json fails here until it is vendored.
const tokens = JSON.parse(
readFileSync(join(WEB, 'src/lib/styles/tokens.json'), 'utf8')
) as { fonts: Record<string, string> };
const files = readdirSync(join(WEB, 'static/fonts'));
for (const family of Object.values(tokens.fonts)) {
const prefix = `${family.replace(/\s+/g, '')}-`;
expect(
files.some((f) => f.startsWith(prefix) && f.endsWith('.woff2')),
`no vendored woff2 for "${family}"`
).toBe(true);
}
});
});