@iterant/site-runtime 3.7.0 → 3.8.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.7.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -443,7 +443,8 @@ import { SITE_SHELL } from "@/site-shell";
 ```
 
 Every shell keeps importing `../layouts/Layout.astro` unchanged. The core owns
-the head (charset, viewport, favicon, generator, version meta, SEO, JSON-LD,
+the head (charset, viewport, favicon, generator, version meta, the web fonts
+named in `SITE_CONFIG.fonts`, SEO, JSON-LD,
 hreflang, the `head` slot), resolves locale-aware chrome and the page entry, and
 renders the brand shell around the page slot with the `chrome`, `navbar`,
 `footer` and `shellId` props. It never imports a stylesheet and never imports chrome
@@ -543,14 +544,87 @@ export default defineConfig({
 });
 ```
 
-The preset carries the adapter, the integrations (React, sitemap, and the
-dev-only plugin loader, preview error shell and new-file reload), the vite
+The preset carries the adapter, the integrations (React, sitemap, the site-config
+watch, and the dev-only plugin loader, preview error shell, new-file reload and
+dev-server signals), the web fonts, the vite
 tuning, the CSS browser floor, the dev server port and host, and the toolbar
 setting. A diverged repo
 extends rather than ejects: extra integrations and vite plugins append through
 `overrides`, and any other key it needs it writes in its own `defineConfig`
 object after the spread.
 
+### Web fonts (3.8.0)
+
+A site names its font families once, in `SITE_CONFIG.fonts`, and passes the same
+array to the preset:
+
+```js
+import { SITE_CONFIG } from "./src/site-config";
+
+export default defineConfig({
+  site: "https://example.com",
+  ...iterantStarter({ fonts: SITE_CONFIG.fonts }),
+});
+```
+
+The preset turns each name into an Astro font declaration (Google provider,
+weights 400/500/600/700, both slants, subsets latin and latin-ext), and the
+layout renders Astro's `<Font>` for the same families. Names come from the
+catalog the package ships, `@iterant/site-runtime/fonts` (`FONT_CATALOG`,
+`fontCssVariable`, `findFontFamily`); a name the catalog does not carry is
+skipped on both sides rather than failing the render. A family declared as
+`Playfair Display` is set in CSS as `var(--font-playfair-display)`.
+
+**The default set is always declared.** `DEFAULT_FONT_FAMILIES` is eleven
+families: one heading default per face class (`DEFAULT_HEADING_FAMILY_BY_CLASS`,
+covering serif, sans, slab, rounded, condensed, display, handwritten and mono)
+plus three body defaults. `SITE_CONFIG.fonts` ADDS to that set, it does not
+replace it, so the family the platform most often picks is already resolved and
+a pick costs no astro.config edit and no restart.
+
+The LAYOUT still renders only what a site names, because every family rendered
+inlines its faces into every page. The one exception is a site that names
+nothing: it renders the eleven default faces, with no preload. A repo's
+`globals.css` is written against the variables, so a stylesheet already saying
+`var(--font-fraunces)` on a site with an empty `fonts` array would otherwise get
+the system stack, silently.
+
+**Name the families.** The fallback is a safety net, not a resting state, and it
+is not cheap: measured on the fixture's home page, eleven families inline 320
+`@font-face` rules and **93.6K of CSS into the head of every page**, taking a
+102K page from 8.8K of everything-else. One named family is 32 rules and 9.2K,
+on an 18K page. The faces are only declarations, so the browser downloads a file
+when a glyph needs one, but the bytes are in the HTML either way and no cache
+serves them. The fallback also preloads nothing, because eleven blocking font
+requests on a page that has not said which families it uses is the wrong trade.
+Name the families and the page carries exactly those and preloads them.
+
+A family in `SITE_CONFIG.fonts` that `astro.config.mjs` never declared is
+skipped rather than rendered. Astro's `<Font>` throws `FontFamilyNotFound` on a
+CSS variable no family registered, so the layout filters the list through
+`fontData`, Astro's own runtime view of the resolved font config, and warns once
+in dev naming the family. That is the case a repo lands in by upgrading and
+adding `SITE_CONFIG.fonts` without also passing it to `iterantStarter`.
+
+Declaring is loading: Astro resolves every declared family at dev boot and
+copies every one of its files into the build output. Measured cold: the eleven
+defaults are 1.2s of resolution and 64 files, 1.6MB, per build; the whole
+89-family catalog is 6.3s and 403 files, 9.7MB. Warm, off the `.astro/fonts`
+cache, the eleven are 5ms. `fonts: "catalog"` declares all 89 for a repo that
+has a reason to.
+
+The layout preloads 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.
+
+**`src/site-config.ts` is watched.** Astro restarts its dev server on its own
+config file, `package.json` and the tsconfig sources, and on nothing else, so a
+family added to `SITE_CONFIG.fonts` would be rendered by the layout while Astro
+had never resolved it. The preset adds the file to `settings.watchFiles`
+(`site-config-watch`), which makes the change restart the server and reach the
+font declarations. A repo that keeps its site config elsewhere passes
+`iterantStarter({ siteConfigPath })`.
+
 ### The browser floor
 
 The preset declares the browsers every brand site's CSS is compiled for, to
@@ -567,6 +641,85 @@ conversation: lowering the floor to Safari 15 does restore `min-width` breakpoin
 and costs 7.5K of fallbacks on the template's own sheet, for engines that still
 cannot render its `@property` and `color-mix()` values.
 
+### The dev server's signals (3.8.0)
+
+Astro restarts its Vite server IN PLACE when a file it watches changes, and the
+repo's `package.json` is one of them: a `bun add` mid-session replaces the whole
+dev server. The content layer is initialised once, at boot, against the first
+server's file watcher, and the restart never re-inits it. Page entries and
+`chrome.json` therefore stop reloading after a restart while `.tsx`, `.astro`
+and `.css` edits keep hot-reloading, and only a process restart clears it.
+
+That restart is not rare: the preset watches `src/site-config.ts` too, so every
+change to a site's font list takes this path.
+
+The `dev-server-signals` integration closes that gap and reports what happened.
+On a RESTARTED server it watches `src/content/` itself and drives Astro's own
+`refreshContent()`, debounced 100ms so a burst of entry writes syncs once. On the
+boot server it arms nothing: that server's content layer is live and runs its own
+incremental update, and a second full sync per save would buy nothing.
+
+It also runs one sync the moment it arms, because a write that landed between
+the old watcher's close and the new one's arm produced an event nobody heard and
+no later event names that file.
+
+That first sync has a side effect worth knowing about. Astro's glob loader ends
+its load by calling `add()` on whatever file watcher the content layer holds,
+and chokidar's `add()` reopens a closed watcher, so the refresh brings the dead
+watcher back and the content layer resumes its own per-file updates from the
+second edit onward. Measured on the consumer fixture across three restarts: the
+revived watcher comes back holding 3 dirs and 6 paths, the collection dirs only,
+against the live watcher's 41 and 123; only that one watcher ever revives, so
+there are at most two alive whatever the restart count; and every content edit
+after the first then costs one extra full sync, 7.7ms median over four entries,
+alongside the layer's own single-file update. The arm stays as it is: the layer
+heals BECAUSE of it (nothing else calls `add()`, and the first edit after a
+restart is carried by the arm alone), and the duplicate is a few milliseconds
+rather than a second watcher over the whole tree.
+
+It writes one line of JSON per event on stdout, every one keyed `iterant` so a
+supervisor reading the dev log can filter them:
+
+```
+{"iterant":"dev-server","event":"restart","phase":"config"}
+{"iterant":"dev-server","event":"restart","phase":"setup"}
+{"iterant":"dev-server","event":"ready","restart":true}
+{"iterant":"dev-server","event":"content-synced","restart":true,"paths":["src/content/pages/home.json"]}
+{"iterant":"dev-server","event":"content-sync-failed","restart":true,"paths":[...],"error":"..."}
+```
+
+`ready` goes out when the server's socket starts listening, which is the first
+moment those routes can be reached. The same news reaches clients over Vite's
+HMR channel as `iterant:server-ready` (`{ restart, at }`), sent as each client
+connects rather than at startup, because a payload sent before a client attaches
+is dropped; `iterant:content-synced` (`{ paths, at }`) follows each sync. There
+is no "restarting" event: the old server is gone before any hook on the new one
+runs, so the arrival is the only half that can be sent.
+
+Two dev-only routes report and force the state. They exist on the dev server and
+in no build:
+
+| Route                      | Answers                                                                      |
+| -------------------------- | ---------------------------------------------------------------------------- |
+| `GET /__iterant/dev-state` | `{ restart, startedAt, contentSync: { armed, lastAt, lastPaths }, entries }` |
+| `POST /__iterant/refresh`  | `{ ok: true, at }`, or 500 `{ ok: false, error }` if the sync rejects        |
+
+Both require the request header `x-iterant-dev-state: 1`, which the preview
+supervisor sends. Without it the request falls through to Astro and is answered
+exactly as it would be if the integration were not installed: 404 for the GET,
+Astro's own cross-site rejection for the POST. The dev server binds to a host
+the preview tunnel can reach, so a route that answered any caller would be a
+content-refresh trigger anyone with the URL could pull.
+
+`entries` is a sha256 per `.json` file in the content dirs the collections read
+(`pagesDir` and `chromeDir`, whatever a repo set them to), keyed by path from the
+project root (`src/content/pages/home.json`). It is the files on DISK, not what
+the content layer holds: the store is reachable only through Astro internals an
+integration must not import. A writer compares the digest it expects against the
+one reported, and calls `POST /__iterant/refresh` if the layer is behind. Every
+timestamp in these payloads, and in the signal lines, is an ISO 8601 string in
+UTC, never an epoch number.
+
 ## Verify: the gate
 
 `bun run verify` maps to `site-runtime verify` and is the gate. It is silent on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {
@@ -44,6 +44,8 @@
     "./locales": "./src/lib/locales.ts",
     "./hreflang": "./src/lib/hreflang.ts",
     "./chrome": "./src/lib/chrome.ts",
+    "./fonts": "./src/fonts/catalog.ts",
+    "./fonts/catalog.json": "./src/fonts/catalog.json",
     "./chrome-schemas": "./src/lib/chrome-schemas.ts",
     "./bespoke-pages": "./src/lib/bespoke-pages.ts",
     "./sitemap": "./src/lib/sitemap/index.ts",

package/src/config/preset.ts

@@ -4,11 +4,20 @@ import cloudflare from "@astrojs/cloudflare";
 import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
 import type { AstroUserConfig } from "astro";
-import { sessionDrivers } from "astro/config";
+import { fontProviders, sessionDrivers } from "astro/config";
 
+import {
+  DEFAULT_FONT_FAMILIES,
+  FONT_CATALOG,
+  fontCssVariable,
+  findFontFamily,
+} from "../fonts/catalog";
+import { DEFAULT_CHROME_DIR, DEFAULT_PAGES_DIR } from "../lib/content-paths";
+import devServerSignals from "../integrations/dev-server-signals.mjs";
 import iterantPlugins from "../integrations/iterant-plugins.mjs";
 import newFileReload from "../integrations/new-file-reload.mjs";
 import previewErrorShell from "../integrations/preview-error-shell.mjs";
+import siteConfigWatch from "../integrations/site-config-watch.mjs";
 import { sitemapWithCustomPages } from "../lib/sitemap";
 
 /**
@@ -37,6 +46,71 @@ import { sitemapWithCustomPages } from "../lib/sitemap";
  */
 const CSS_TARGET = ["safari16.4", "chrome111", "firefox128", "edge111"];
 
+/** Astro's font schema takes the three below as non-empty tuples, not arrays. */
+type NonEmpty<T> = [T, ...T[]];
+
+/**
+ * The weights and styles every catalog family is requested at.
+ *
+ * FOUR EXPLICIT WEIGHTS, not a variable range. Unifont's google provider decides
+ * variable-versus-static per family (`prepareWeights`, on the family's own
+ * `wght` axis), and it forwards a range straight into the css2 URL: `100 900`
+ * against a family whose axis is narrower (EB Garamond is 400..800) comes back
+ * 400 Bad Request, and `throwOnError: false` turns that into a family that
+ * silently resolves to zero faces. Measured on the whole catalog: the range
+ * lost 37 of 89 families, these four weights resolve all 89. Where the family
+ * IS variable, Google still serves one variable file per subset, so asking for
+ * four weights costs four faces and one download, not four.
+ *
+ * Astro's own defaults are one weight and both slants; both are restated here
+ * because the catalog's value is that any family in it renders the same way.
+ */
+const FONT_WEIGHTS: NonEmpty<string> = ["400", "500", "600", "700"];
+const FONT_STYLES: NonEmpty<"normal" | "italic"> = ["normal", "italic"];
+const FONT_SUBSETS: NonEmpty<string> = ["latin", "latin-ext"];
+
+/**
+ * The default set plus whatever the site names, as Astro font declarations.
+ *
+ * DECLARING IS LOADING, which is why this is a set and not the whole catalog.
+ * Astro's fonts plugin resolves every declared family in `buildStart`,
+ * sequentially, once per dev server and once per build, and `buildEnd` writes
+ * every file of every declared family into the client output. Measured cold:
+ * the eleven defaults cost 1.2s at dev boot (829ms of resolution, ~75ms a
+ * family, plus 338ms of provider init) and 64 font files, 1.6MB, into `dist/`
+ * per build. The whole 89-family catalog costs 6.3s and 403 files, 9.7MB.
+ * Warm (the `.astro/fonts` cache, or `node_modules/.astro/fonts` for a build)
+ * eleven families are 5ms, but a preview sandbox clones the repo fresh, so it
+ * pays the cold number on its first boot.
+ *
+ * The defaults are declared unconditionally because the alternative is worse
+ * than a second of boot: the platform picks a family from the catalog, writes
+ * it into SITE_CONFIG.fonts, and until the dev server restarts the layout would
+ * render a face Astro never resolved. `site-config-watch` makes that restart
+ * happen, and these eleven make it unnecessary for the common pick.
+ *
+ * A name the catalog does not carry is skipped rather than declared: Astro's
+ * `<Font>` throws on a CSS variable no family registered, and the layout reads
+ * the same catalog to decide what to render.
+ */
+function catalogFontFamilies(fonts: readonly string[] | "catalog") {
+  const names =
+    fonts === "catalog"
+      ? FONT_CATALOG.map((entry) => entry.family)
+      : [...DEFAULT_FONT_FAMILIES, ...fonts];
+  const families = [...new Set(names)]
+    .map((family) => findFontFamily(family))
+    .filter((entry) => entry !== undefined);
+  return families.map((entry) => ({
+    name: entry.family,
+    cssVariable: fontCssVariable(entry.family),
+    provider: fontProviders.google(),
+    weights: FONT_WEIGHTS,
+    styles: FONT_STYLES,
+    subsets: FONT_SUBSETS,
+  }));
+}
+
 // The Astro configuration every brand site runs on, as one spreadable fragment:
 //
 //   // astro.config.mjs
@@ -72,6 +146,28 @@ export interface IterantStarterOptions {
    * knob, so the sitemap and the collection can never read different dirs.
    */
   pagesDir?: string;
+  /**
+   * Directory holding chrome.json, its locale siblings and links.json, if a
+   * repo moved it. Same rule as `pagesDir`: `createCollections` takes the same
+   * value, and the dev server's content re-arm watches whichever pair is set,
+   * so a relocated tree is repaired and reported like any other.
+   */
+  chromeDir?: string;
+  /**
+   * Font families this site uses, by catalog name (`["Fraunces", "Inter"]`).
+   * The same list the layout receives as `siteConfig.fonts`, so a repo passes
+   * its `SITE_CONFIG.fonts` here and the two cannot name different families.
+   * ADDED to the default set rather than replacing it; omitted or empty leaves
+   * the defaults alone. `"catalog"` declares all 89, at the cost
+   * `catalogFontFamilies` measures.
+   */
+  fonts?: readonly string[] | "catalog";
+  /**
+   * The repo's site config module, relative to the project root. Watched, so a
+   * change to `SITE_CONFIG.fonts` restarts the dev server and reaches the font
+   * declarations; the preset does not import the file, it only names it.
+   */
+  siteConfigPath?: string;
   /**
    * Extensions for a diverged repo. These are the two keys a spread cannot
    * express: extra `integrations` APPEND after the platform's, and `vite`
@@ -93,7 +189,10 @@ export interface IterantStarterOptions {
 export function iterantStarter({
   site,
   allowedHosts = true,
-  pagesDir,
+  pagesDir = DEFAULT_PAGES_DIR,
+  chromeDir = DEFAULT_CHROME_DIR,
+  fonts = [],
+  siteConfigPath = "src/site-config.ts",
   overrides,
 }: IterantStarterOptions = {}) {
   // A repo's own wrangler config, when it has one. The template checks in a
@@ -125,8 +224,14 @@ export function iterantStarter({
     previewErrorShell(),
     // Dev-only: broadcast a reload when a new src/ file matches no module.
     newFileReload(),
+    // Dev-only: restart signals, the content re-arm, and the dev-state probe.
+    devServerSignals({ pagesDir, chromeDir }),
+    // Restart the dev server when the site config the fonts come from changes.
+    siteConfigWatch(siteConfigPath),
   ];
 
+  const fontFamilies = catalogFontFamilies(fonts);
+
   const vite: NonNullable<AstroUserConfig["vite"]> = {
     cacheDir: viteCacheDir,
     plugins: [tailwindcss()],
@@ -215,6 +320,7 @@ export function iterantStarter({
     // allow a package MINOR to make; the runtime therefore keeps the old
     // behavior and a later MAJOR can adopt "jsx" deliberately.
     compressHTML: true,
+    fonts: fontFamilies,
     integrations,
     vite,
     // Port 4321 (Astro's default), NOT 3000: inside a Cloudflare Sandbox port