@iterant/site-runtime 3.8.2 → 3.9.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.8.2._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.9.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -617,13 +617,27 @@ 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 })`.
+**`src/site-config.ts` is watched in list mode.** 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 })`.
+
+**Under `fonts: "catalog"` the preset registers no restart watch on it; Vite
+still watches it as a source module.** Every
+family is declared at boot, so a family written into `SITE_CONFIG.fonts` after
+that is one Astro already resolved, and the layout picks it up on the first
+render after the module's hot update has been processed. The site config is then outside the Astro
+config's import graph too, since the config no longer reads it, so no write of
+it restarts the server. That is the mode the platform's own starters run: the
+direction pick writes the file on every first build, and the restart it used to
+cause cost 11.7s of preview outage, ending in a re-attach the customer saw as
+the waking card (measured 2026-09-12). The boot pays 6.3s of font resolution
+instead of 1.2s on a cold tree, and nothing on a tree whose `.astro/fonts` cache
+came with it and whose metadata is under seven days old (Astro refreshes the
+metadata after that, through the cache's own files).
 
 ### The browser floor
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.8.2",
+  "version": "3.9.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": {

package/src/config/preset.ts

@@ -89,6 +89,11 @@ const FONT_SUBSETS: NonEmpty<string> = ["latin", "latin-ext"];
  * render a face Astro never resolved. `site-config-watch` makes that restart
  * happen, and these eleven make it unnecessary for the common pick.
  *
+ * `"catalog"` takes the other road: with every family declared, nothing the
+ * platform writes into SITE_CONFIG.fonts can name a face Astro did not resolve,
+ * so the site config leaves the dev server's restart list entirely and a
+ * direction pick reaches the page as a hot update instead of a reboot.
+ *
  * 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.
@@ -163,9 +168,12 @@ export interface IterantStarterOptions {
    */
   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.
+   * The repo's site config module, relative to the project root. In list mode
+   * it is 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. Under `fonts: "catalog"` the preset registers no restart
+   * watch on it (Vite still watches it as a module), because every
+   * family is already declared.
    */
   siteConfigPath?: string;
   /**
@@ -226,8 +234,16 @@ export function iterantStarter({
     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),
+    // Restart the dev server when the site config the fonts come from changes,
+    // in list mode alone. The watch exists for one reason: the preset turns
+    // SITE_CONFIG.fonts into font declarations once, at server start, so a
+    // family added to that list after boot would render a face Astro never
+    // resolved. `"catalog"` declares every family up front, which answers the
+    // same question without a restart, and the restart is not free: every first
+    // build writes src/site-config.ts on the direction pick, and that cost 11.7s
+    // of preview outage, with a `preview.upstream-error` and a re-attach the
+    // customer sees as the waking card (measured 2026-09-12, run 10).
+    ...(fonts === "catalog" ? [] : [siteConfigWatch(siteConfigPath)]),
   ];
 
   const fontFamilies = catalogFontFamilies(fonts);