138 lines
7.1 KiB
Markdown
138 lines
7.1 KiB
Markdown
---
|
||
id: 003-self-host-fonts-89466b
|
||
title: Self-host the three web fonts and drop the render-blocking Google Fonts CSS
|
||
created: 2026-09-29
|
||
depends_on: [002-compress-and-etag-shell-bd459c]
|
||
est_files: 5
|
||
---
|
||
|
||
# 003 — Self-host the three web fonts
|
||
|
||
## Objective
|
||
|
||
`frontend/index.html` loads a render-blocking stylesheet from `fonts.googleapis.com`
|
||
(3 families, 10 weights), which costs two extra origins (DNS+TLS each) before first
|
||
paint and only works offline through the SW's `ytplayer-fonts` runtime cache. After
|
||
this plan the fonts are files under `frontend/fonts/`, declared in
|
||
`frontend/fonts/fonts.css`, precached with the shell, and the display face is
|
||
preloaded. Visual result must be identical.
|
||
|
||
## Context the executor must NOT rediscover
|
||
|
||
`frontend/index.html:20-26` today:
|
||
|
||
```html
|
||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||
<link
|
||
href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,700;12..96,800&family=Hanken+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap"
|
||
rel="stylesheet"
|
||
/>
|
||
<link rel="stylesheet" href="styles.css" />
|
||
```
|
||
|
||
CSS tokens (`frontend/styles.css:27-29`) reference the family names
|
||
`"Bricolage Grotesque"`, `"Hanken Grotesk"`, `"JetBrains Mono"` — keep those names.
|
||
|
||
`frontend/sw.js:55-71` — the `SHELL` array (precache list). Every new shell file must be
|
||
listed there or it will be missing offline. `frontend/sw.js:165` keeps a runtime rule for
|
||
the Google hosts — leave it (harmless, and old clients may still request them).
|
||
|
||
Google serves one variable `woff2` per family per subset when asked with a modern UA.
|
||
`fitLyricLines` already re-fits on `document.fonts` load (CLAUDE.md), so swap is safe.
|
||
|
||
## Steps
|
||
|
||
1. Create `scripts/fetch-fonts.js` (Node ≥18, no deps):
|
||
```js
|
||
// Downloads the app's Google fonts once (latin + latin-ext subsets) into
|
||
// frontend/fonts/ and writes frontend/fonts/fonts.css pointing at them.
|
||
// Re-run only when the font list changes.
|
||
const fs = require('node:fs');
|
||
const path = require('node:path');
|
||
const CSS_URL = 'https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600..800&family=Hanken+Grotesk:wght@400..700&family=JetBrains+Mono:wght@400..700&display=swap';
|
||
const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36';
|
||
const OUT = path.join(__dirname, '..', 'frontend', 'fonts');
|
||
(async () => {
|
||
fs.mkdirSync(OUT, { recursive: true });
|
||
const css = await (await fetch(CSS_URL, { headers: { 'User-Agent': UA } })).text();
|
||
// parts[k] ends with the "/* <subset> */" comment of the block in parts[k+1].
|
||
const parts = css.split('@font-face');
|
||
let out = '/* Generated by scripts/fetch-fonts.js — do not edit by hand. */\n';
|
||
let n = 0;
|
||
for (let k = 1; k < parts.length; k++) {
|
||
const subset = (parts[k - 1].match(/\/\*\s*([\w-]+)\s*\*\/\s*$/) || [])[1];
|
||
const b = parts[k].slice(0, parts[k].indexOf('}') + 1); // just this block
|
||
if (subset !== 'latin' && subset !== 'latin-ext') continue;
|
||
const url = (b.match(/url\((https:[^)]+\.woff2)\)/) || [])[1];
|
||
const fam = (b.match(/font-family:\s*'([^']+)'/) || [])[1];
|
||
if (!url || !fam) continue;
|
||
const file = `${fam.replace(/\s+/g, '')}-${subset}.woff2`;
|
||
const buf = Buffer.from(await (await fetch(url)).arrayBuffer());
|
||
fs.writeFileSync(path.join(OUT, file), buf);
|
||
out += '@font-face' + b.replace(url, file).trimEnd() + '\n';
|
||
n++;
|
||
}
|
||
fs.writeFileSync(path.join(OUT, 'fonts.css'), out);
|
||
console.log(`wrote ${n} font files + fonts.css`);
|
||
})().catch((e) => { console.error(e); process.exit(1); });
|
||
```
|
||
Run it: `node scripts/fetch-fonts.js`. Expect `wrote 6 font files + fonts.css`
|
||
(3 families × 2 subsets). If the network is blocked, STOP and report — do not hand-write fonts.
|
||
2. Open `frontend/fonts/fonts.css` and confirm every block has `font-display: swap;`; if a
|
||
block lacks it, add it.
|
||
3. `frontend/index.html` — replace the 5 lines from `<link rel="preconnect" href="https://fonts.googleapis.com" />`
|
||
through the closing `/>` of the Google stylesheet link with:
|
||
```html
|
||
<link rel="preload" href="fonts/BricolageGrotesque-latin.woff2" as="font" type="font/woff2" crossorigin />
|
||
<link rel="preload" href="fonts/HankenGrotesk-latin.woff2" as="font" type="font/woff2" crossorigin />
|
||
<link rel="stylesheet" href="fonts/fonts.css" />
|
||
```
|
||
(Use the exact filenames the script produced — check with `ls frontend/fonts`.)
|
||
4. `frontend/sw.js` `SHELL` array — after `'/styles.css',` add `'/fonts/fonts.css',` and one
|
||
`'/fonts/<file>.woff2',` line per generated woff2 file.
|
||
5. `frontend/index.html` line 16 — the Content-Security-Policy `<meta>` has
|
||
`font-src https://fonts.gstatic.com data:` which would BLOCK self-hosted fonts. Change that part to
|
||
`font-src 'self' https://fonts.gstatic.com data:` (leave the rest of the policy unchanged;
|
||
`style-src` already allows `'self'`). `frontend/admin.html` has no Google Fonts link — leave it alone.
|
||
6. `package.json` scripts — add `"fetch-fonts": "node scripts/fetch-fonts.js"`.
|
||
|
||
## Out of scope / do NOT touch
|
||
|
||
- Do not rename the font families or edit `styles.css`.
|
||
- Do not remove the fonts rule in `sw.js` fetch handler or `UTILITY_CACHES`.
|
||
- Do not subset further (e.g. glyph-level subsetting) — out of scope.
|
||
|
||
## Verification
|
||
|
||
```bash
|
||
cd /home/user/ytplayer && ls -la frontend/fonts
|
||
grep -c 'href="https://fonts.googleapis' frontend/index.html
|
||
grep -c "font-src 'self'" frontend/index.html
|
||
for f in $(ls frontend/fonts/*.woff2); do grep -c "/fonts/$(basename $f)" frontend/sw.js; done
|
||
node --test frontend/*.test.js 2>&1 | tail -3
|
||
cd server && [ -e public ] || ln -s ../frontend public; PORT=3998 bun server.js >/tmp/ytp003.log 2>&1 & SRV=$!; sleep 4
|
||
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:3998/fonts/fonts.css
|
||
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3998/fonts/$(ls ../frontend/fonts | grep woff2 | head -1)
|
||
kill $SRV; true
|
||
```
|
||
|
||
Expected: 6 `.woff2` + `fonts.css`; google link grep `0`; CSP grep `1`; each sw.js grep `1`; tests `fail 0`;
|
||
`200 text/css…` and `200`.
|
||
|
||
## Report format (executor: follow exactly)
|
||
|
||
Output ONLY the following, no other prose:
|
||
|
||
1. `git diff --stat` plus unified diff of text files (not the woff2 binaries).
|
||
2. Raw output of the Verification commands.
|
||
3. `Findings:` — max 10 lines.
|
||
|
||
Do not commit. Do not push. Do not touch files outside the Steps.
|
||
|
||
## Execution log
|
||
|
||
- Executor: in-session Agent (haiku). Attempts: 1. Fix rounds: 0.
|
||
- Orchestrator re-ran Verification: 6 woff2 + fonts.css present, Google Fonts link count 0, CSP `font-src 'self'` 1, each woff2 precached in sw.js once, 52 frontend tests pass, `/fonts/fonts.css` 200 text/css and woff2 200 font/woff2 from a real server.
|
||
- Executor Findings (verbatim): Plan executed successfully. All 6 font files generated (3 families x 2 subsets). CSP updated to allow 'self' fonts. SW.js updated to precache all fonts. Google Fonts links completely removed. Server responds correctly to font requests. Unit tests pass.
|