Stop inlining the Newsreader faces into the render-blocking stylesheet

/static/app.css was 305 KB because APP_CSS base64-embedded both woff2
faces into it at runtime, and the browser cannot paint until it has the
whole sheet. Lighthouse mobile put FCP and LCP at 2.4 s for it.

The inlining was justified by a Firefox font-flash theory that the later
FOUC investigation (239125a) disproved: the flash came from theme.js
running ahead of the stylesheet, not from fonts arriving late. So point
the faces back at /static/Newsreader*.woff2, versioned with ASSET_VERSION
so the immutable one-year max-age stays safe. Gzipped, the sheet goes
from 304 KB to 12 KB.

That leaves first paint waiting on a font, so switch both faces from
font-display: block to swap and give them metric-matched local fallbacks
(Georgia, Times New Roman, Noto Serif, DejaVu Serif). The overrides are
computed from Newsreader's own metrics at the body optical size against
@capsizecss/metrics widths, so the fallback occupies the same box and the
swap changes glyph shapes and nothing else: every block on the page lands
at the same y-position either way, and CLS stays at 0.001.

Preload the regular face so it starts with the stylesheet rather than
after it parses; italic stays on demand. theme.js keeps its place after
the stylesheet link.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MD4VWGq6mGcd8Bg67qyx9k

src/web/mod.rs

@@ -214,27 +214,32 @@ pub struct Page {
 const NEWSREADER: &[u8] = include_bytes!("static/fonts/Newsreader.woff2");
 const NEWSREADER_ITALIC: &[u8] = include_bytes!("static/fonts/Newsreader-italic.woff2");
 
-/// The stylesheet with both Newsreader faces embedded as `data:` URIs.
+/// The stylesheet with both Newsreader faces pointed at versioned URLs.
 ///
-/// A font referenced by URL is applied *after* first paint whenever the browser
+/// The faces used to be inlined here as `data:` URIs on the theory that a font
-/// has to bring it back from the disk cache (Firefox drops fonts from memory as
+/// fetched by URL lands after first paint and flashes. That theory was wrong:
-/// soon as no page uses them), which shows as a flash of invisible or fallback
+/// the flash of unstyled content came from script ordering (a parser-blocking
-/// text on the first navigation after an idle spell. Fonts embedded in the
+/// `theme.js` ahead of the stylesheet let Gecko paint before the sheet applied,
-/// render-blocking stylesheet are decoded synchronously, so the first paint is
+/// Bugzilla 1459305), and moving the script after the `<link>` fixed it. What
-/// already set in Newsreader.
+/// the inlining did cost was real: it tripled the render-blocking stylesheet to
+/// ~305 KB and pushed first paint out by more than a second on mobile.
+///
+/// So the URLs stay URLs, carrying `?v=<ASSET_VERSION>` so the immutable
+/// one-year `max-age` on `/static/*` is safe across deploys. The fonts are part
+/// of the `ASSET_VERSION` hash, so a new face mints a new URL. `layout.html`
+/// preloads the regular face, and the faces use `font-display: swap` behind
+/// metric-matched local fallbacks, so first paint is immediate and the swap
+/// shifts nothing.
 pub static APP_CSS: LazyLock<String> = LazyLock::new(|| {
-    use base64::Engine;
+    let version = ASSET_VERSION.as_str();
-    let data_uri = |bytes: &[u8]| {
-        format!(
-            "url(data:font/woff2;base64,{})",
-            base64::engine::general_purpose::STANDARD.encode(bytes)
-        )
-    };
     include_str!("static/app.css")
-        .replace("url(/static/Newsreader.woff2)", &data_uri(NEWSREADER))
+        .replace(
+            "url(/static/Newsreader.woff2)",
+            &format!("url(/static/Newsreader.woff2?v={version})"),
+        )
         .replace(
             "url(/static/Newsreader-italic.woff2)",
-            &data_uri(NEWSREADER_ITALIC),
+            &format!("url(/static/Newsreader-italic.woff2?v={version})"),
         )
 });
 
@@ -1100,16 +1105,36 @@ mod tests {
         let expected = format!("/static/app.css?v={}", ASSET_VERSION.as_str());
         assert!(html.contains(&expected), "{html}");
         assert!(!html.contains(&format!("/static/app.css?v={}", crate::VERSION)));
-        // The fonts ride inside the stylesheet; a preload would fetch them twice.
+        // The regular face is preloaded so it starts downloading alongside the
-        assert!(!html.contains("rel=\"preload\""), "{html}");
+        // stylesheet that declares it; the italic face is left to load on demand.
+        let preload = format!(
+            "<link rel=\"preload\" href=\"/static/Newsreader.woff2?v={}\" as=\"font\" type=\"font/woff2\" crossorigin>",
+            ASSET_VERSION.as_str()
+        );
+        assert!(html.contains(&preload), "{html}");
+        assert!(!html.contains("Newsreader-italic.woff2"), "{html}");
     }
 
     #[test]
-    fn stylesheet_embeds_both_newsreader_faces() {
+    fn stylesheet_points_both_newsreader_faces_at_versioned_urls() {
         let css = APP_CSS.as_str();
-        assert_eq!(css.matches("url(data:font/woff2;base64,").count(), 2);
+        let version = ASSET_VERSION.as_str();
-        assert!(!css.contains("/static/Newsreader"));
+        assert!(
-        assert!(css.contains("font-display:block"), "{}", &css[..200]);
+            css.contains(&format!("url(/static/Newsreader.woff2?v={version})")),
+            "regular face missing from stylesheet"
+        );
+        assert!(
+            css.contains(&format!("url(/static/Newsreader-italic.woff2?v={version})")),
+            "italic face missing from stylesheet"
+        );
+        // Unversioned references would be cached forever under a stale URL, and
+        // inlined faces would put ~280 KB back into the render-blocking sheet.
+        assert!(!css.contains("url(/static/Newsreader.woff2)"));
+        assert!(!css.contains("url(/static/Newsreader-italic.woff2)"));
+        assert!(!css.contains("data:font"));
+        // `swap` paints immediately in the metric-matched local fallback.
+        assert_eq!(css.matches("font-display:swap").count(), 2);
+        assert!(!css.contains("font-display:block"));
     }
 
     #[tokio::test]

src/web/tailwind.css

@@ -9,7 +9,7 @@
   font-style: normal;
   font-weight: 200 800;
   font-stretch: normal;
-  font-display: block;
+  font-display: swap;
   src: url("/static/Newsreader.woff2") format("woff2");
   unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -19,11 +19,66 @@
   font-style: italic;
   font-weight: 200 800;
   font-stretch: normal;
-  font-display: block;
+  font-display: swap;
   src: url("/static/Newsreader-italic.woff2") format("woff2");
   unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
 
+/* Metric-matched local fallbacks for Newsreader.
+   `font-display: swap` paints text immediately in whichever of these the
+   platform has; the overrides make that first paint occupy the same box as
+   Newsreader, so the swap changes glyph shapes and nothing else (CLS 0).
+
+   size-adjust  = (Newsreader xWidthAvg/upm) / (fallback xWidthAvg/upm)
+   ascent/descent-override = (Newsreader ascent|descent / upm) / size-adjust
+
+   Newsreader (src/web/static/fonts/Newsreader.woff2, wght 400 at opsz 17, the
+   body size): upm 2000, ascent 1470, descent -530, lineGap 0, and a
+   frequency-weighted average character width of 837 (0.4185 em). Fallback
+   widths are @capsizecss/metrics v4.2.0 `xWidthAvg`, which uses the same
+   weighting, except DejaVu Serif which is measured the same way from
+   /usr/share/fonts/truetype/dejavu/DejaVuSerif.ttf. */
+
+@font-face {
+  font-family: "Newsreader Fallback Georgia";
+  src: local("Georgia");
+  /* xWidthAvg 913 / upm 2048 */
+  size-adjust: 93.88%;
+  ascent-override: 78.29%;
+  descent-override: 28.23%;
+  line-gap-override: 0%;
+}
+
+@font-face {
+  font-family: "Newsreader Fallback Times";
+  src: local("Times New Roman"), local("Liberation Serif"), local("Tinos");
+  /* xWidthAvg 832 / upm 2048 */
+  size-adjust: 103.02%;
+  ascent-override: 71.35%;
+  descent-override: 25.72%;
+  line-gap-override: 0%;
+}
+
+@font-face {
+  font-family: "Newsreader Fallback Noto Serif";
+  src: local("Noto Serif");
+  /* xWidthAvg 481 / upm 1000 */
+  size-adjust: 87.01%;
+  ascent-override: 84.48%;
+  descent-override: 30.46%;
+  line-gap-override: 0%;
+}
+
+@font-face {
+  font-family: "Newsreader Fallback DejaVu Serif";
+  src: local("DejaVu Serif");
+  /* xWidthAvg 1058 / upm 2048 */
+  size-adjust: 81.01%;
+  ascent-override: 90.73%;
+  descent-override: 32.71%;
+  line-gap-override: 0%;
+}
+
 :root {
   --paper:#f6f3ec; --paper-2:#ece7db; --ink:#1c1b18; --ink-2:#4f4b43; --muted:#7a7568;
   --rule:#d8d2c4; --rule-strong:#1c1b18; --accent:#a3231f; --accent-hover:#7c1a16;
@@ -50,7 +105,9 @@
   --color-rule-strong:var(--rule-strong); --color-accent:var(--accent);
   --color-accent-hover:var(--accent-hover); --color-loved:var(--loved); --color-good:var(--good);
   --color-down:var(--down); --color-warn:var(--warn);
-  --font-serif:"Newsreader", "Iowan Old Style", "Palatino Linotype", Georgia, serif;
+  --font-serif:"Newsreader", "Newsreader Fallback Georgia", "Newsreader Fallback Times",
+    "Newsreader Fallback Noto Serif", "Newsreader Fallback DejaVu Serif",
+    "Iowan Old Style", "Palatino Linotype", Georgia, serif;
   --font-sans:ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
   --font-mono:ui-monospace, SFMono-Regular, Menlo, monospace;
 }

src/web/templates/layout.html

@@ -5,6 +5,12 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta name="color-scheme" content="light dark">
   <title>{{ page.title }} · The Daily EPUB</title>
+  {# Start the regular face downloading with the stylesheet rather than after
+     it parses. `crossorigin` is required even same-origin: font fetches are
+     CORS-mode, so without it the preload would not match the @font-face
+     request and the file would be fetched twice. Only the regular face —
+     italic is rare enough that on-demand loading is the right trade. #}
+  <link rel="preload" href="/static/Newsreader.woff2?v={{ page.asset_version }}" as="font" type="font/woff2" crossorigin>
   <link rel="stylesheet" href="/static/app.css?v={{ page.asset_version }}">
   {# Keep this synchronous script *after* the stylesheet: Gecko will not run a
      parser-blocking script while a stylesheet is pending, so the parser stalls