@iterant/site-runtime 3.7.0 → 3.8.1

package/src/layouts/LayoutCore.astro

@@ -1,9 +1,11 @@
 ---
+import { Font, fontData } from "astro:assets";
 import { getCollection, getEntry } from "astro:content";
 import type { AstroComponentFactory } from "astro/runtime/server/index.js";
 import RelatedLinks from "../components/RelatedLinks.astro";
 import { SEO, type PageType } from "../components/seo";
 import type { SeoJsonSchema } from "../components/seo-json";
+import { fontCssVariable } from "../fonts/catalog";
 import type { HreflangAlternate } from "../lib/hreflang";
 import { DEFAULT_LOCALE, localeFromPath } from "../lib/locales";
 import { SITE_RUNTIME_VERSION } from "../version";
@@ -14,6 +16,7 @@ import {
   resolveAbsoluteUrl,
   resolveStructuredData,
   routePathFromPathname,
+  selectFontFamilies,
   type LayoutSiteConfig,
   type SiteShell,
 } from "./layout-core";
@@ -151,6 +154,41 @@ const shellId = shell ?? pageEntry?.data.shell;
 const linksEntry = await getEntry("links", "links");
 const linksSlice = linksEntry?.data.routes[routePath];
 
+// Web fonts (3.8.0): a `@font-face` block per family the site names in
+// SITE_CONFIG.fonts, and a preload link for each. Never the whole catalog:
+// every family rendered here inlines its faces into EVERY page.
+//
+// `fontData` is Astro's own runtime view of the resolved font config, keyed by
+// CSS variable, so it is what decides whether a family can render. The rule and
+// the fallback live in selectFontFamilies, which is testable without a render.
+const fonts = selectFontFamilies(siteConfig.fonts, (cssVariable) =>
+  Object.hasOwn(fontData, cssVariable),
+);
+
+// A named family nothing declared is a repo whose astro.config and site config
+// disagree, which no gate catches and no render shows. Said once, in dev, where
+// the author is looking.
+if (import.meta.env.DEV && fonts.undeclared.length > 0) {
+  console.warn(
+    `[site-runtime] SITE_CONFIG.fonts names ${fonts.undeclared.join(", ")}, which astro.config did not declare. Pass the same list to iterantStarter({ fonts }).`,
+  );
+}
+
+// The cast is Astro's own type: once a repo configures fonts, `astro sync` narrows
+// CssVariable to the exact literals in that config. Every variable here is one
+// fontData carries, which is the same set, but the compiler cannot see that
+// through a runtime string.
+const fontVariables = fonts.families.map((family) =>
+  fontCssVariable(family),
+) as Array<import("astro:assets").CssVariable>;
+
+// Preload the upright latin face of each named family and nothing else. Every
+// face stays in the @font-face block, so the browser still fetches a slanted or
+// extended-latin one the moment a glyph needs it. Preloading every face instead
+// measured 8 files and 436K of blocking requests for two families, on a page
+// that renders four words of plain latin text.
+const fontPreload = fonts.named ? [{ style: "normal", subset: "latin" }] : false;
+
 // Version identity: the installed package version IS the site's runtime
 // version. `it-astro-starter-version` keeps emitting the same value while the
 // plugin loader and the platform's page indexer still read that name, and
@@ -176,6 +214,11 @@ const linksSlice = linksEntry?.data.routes[routePath];
     <meta name="generator" content={Astro.generator} />
     <meta name="it-site-runtime" content={SITE_RUNTIME_VERSION} />
     <meta name="it-astro-starter-version" content={SITE_RUNTIME_VERSION} />
+    {
+      fontVariables.map((cssVariable) => (
+        <Font cssVariable={cssVariable} preload={fontPreload} />
+      ))
+    }
     <SEO
       title={title}
       description={description}

package/src/layouts/layout-core.ts

@@ -1,4 +1,5 @@
 import type { PageType } from "../components/seo";
+import { DEFAULT_FONT_FAMILIES, fontCssVariable } from "../fonts/catalog";
 import type { ContentProps } from "../lib/content-values";
 
 // The pure half of LayoutCore.astro: URL resolution, chrome lookup, and the
@@ -16,6 +17,14 @@ export interface LayoutSiteConfig {
   description: string;
   logo?: string;
   sameAs?: string[];
+  /**
+   * Font families this site uses, by catalog name (`["Fraunces", "Inter"]`).
+   * The head carries a `@font-face` block per family, so this is the list of
+   * families the site actually sets somewhere, not everything it may choose
+   * from. The repo passes the same array to `iterantStarter({ fonts })`; a
+   * family missing there has no CSS variable to render and is skipped.
+   */
+  fonts?: string[];
 }
 
 /**
@@ -141,3 +150,50 @@ export function resolveStructuredData(
 }
 
 export { LAYOUT_CONTRACT } from "./layout-contract";
+
+/** What the head renders for web fonts, decided off the site's list. */
+export interface FontSelection {
+  /** Families to render a `<Font>` for, in order, deduped. */
+  families: string[];
+  /** Whether the families are the site's own list rather than the fallback. */
+  named: boolean;
+  /** Families the site named that no font config declared. */
+  undeclared: string[];
+}
+
+/**
+ * The families the head renders, and whether to preload them.
+ *
+ * `isDeclared` is the authority, not the catalog: Astro's `<Font>` THROWS
+ * (`FontFamilyNotFound`) on a CSS variable no family registered, so a repo
+ * whose astro.config never got the site's list would render an error page
+ * rather than a missing face. Filtering through what Astro actually resolved
+ * makes that structurally impossible, and it also lets a diverged repo declare
+ * a family of its own and have it render.
+ *
+ * A site that names nothing falls back to the default set: a repo's globals.css
+ * is written against the CSS variables, so a stylesheet already saying
+ * `var(--font-fraunces)` would otherwise get the system stack, silently. The
+ * fallback is reported through `named`, because a page that has not said which
+ * families it uses must not spend a preload on each of eleven guesses.
+ */
+export function selectFontFamilies(
+  fonts: readonly string[] | undefined,
+  isDeclared: (cssVariable: string) => boolean,
+): FontSelection {
+  const wanted = [...new Set(fonts ?? [])];
+  const declared = wanted.filter((family) =>
+    isDeclared(fontCssVariable(family)),
+  );
+  const undeclared = wanted.filter((family) => !declared.includes(family));
+  if (declared.length > 0) {
+    return { families: declared, named: true, undeclared };
+  }
+  return {
+    families: DEFAULT_FONT_FAMILIES.filter((family) =>
+      isDeclared(fontCssVariable(family)),
+    ),
+    named: false,
+    undeclared,
+  };
+}