@iterant/site-runtime 3.7.0 → 3.8.1

package/src/integrations/dev-server-signals.mjs

@@ -0,0 +1,406 @@
+// @ts-check
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { beginRestart, endRestart } from "./dev-restart-state.mjs";
+
+// Dev-only restart signals, content re-arm and state probe (2026-09-11).
+//
+// Astro restarts its Vite server IN PLACE when a file in `settings.watchFiles`
+// changes, and `core/config/settings.js` seeds that list with the repo's
+// package.json, so a plain `bun add` mid-session replaces the whole dev
+// server. The preset adds src/site-config.ts to the same list, so a font change
+// takes this path too. Vite's restart builds a new chokidar watcher and closes
+// the old one. The content layer is initialised ONCE at boot
+// (`core/dev/dev.js`, `globalContentLayer.init({ watcher })`) and the restart
+// never re-inits it, so the glob loader for the content tree stays bound to a
+// closed watcher for the rest of the process: .tsx/.astro/.css keep
+// hot-reloading while page entries and chrome.json quietly stop. Only a process
+// restart clears it.
+//
+// `astro:server:setup` runs on EVERY server Astro creates, the in-place restart
+// included, and it hands over `refreshContent()`, which resolves the live
+// content layer and syncs it. That is the seam: on a restarted server this
+// integration watches the content tree itself and drives the sync the dead
+// watcher no longer drives. The sync writes .astro/data-store.json, and the new
+// server's own watcher invalidates the content virtual module off that write
+// (`content/vite-plugin-content-virtual-mod.js`), so the next request serves
+// the new entry and the browser reloads.
+//
+// The watched tree is the one the COLLECTIONS read, not a fixed path: a repo
+// that moved its entries passes the same `pagesDir`/`chromeDir` to
+// `createCollections` and to `iterantStarter`, and the preset threads them here.
+//
+// WHAT THE FIRST REFRESH DOES TO THE DEAD WATCHER, measured on the consumer
+// fixture across three restarts (chokidar 3.6 as Vite 8 bundles it). The glob
+// loader ends its load with `watcher.add(base)` on whatever watcher the content
+// layer holds, and chokidar's `add()` opens with `this.closed = false`. So the
+// first refresh this integration drives brings watcher #1 back from the dead:
+//
+//   boot            #1 alive, 41 dirs / 123 paths, content listeners 10/14/10
+//   after restart   #1 closed, 0 dirs / 0 paths, 0 listeners; #2 alive 41/123
+//   1st edit after  our sync only. #1 comes back: 3 dirs / 6 paths, 2/2/2
+//   2nd edit after  `Reloaded data from home.json` AND our sync: BOTH run
+//
+// Three consequences, all of them measured rather than reasoned:
+//
+//   The content layer SELF-HEALS from the second edit on. Watcher #1's revived
+//   handlers are the layer's own, so it resumes its incremental per-file
+//   update. It heals BECAUSE of this arm, not instead of it: nothing else ever
+//   calls add(), and the first edit after a restart is carried by us alone.
+//
+//   Nothing ACCUMULATES. Only watcher #1 ever revives, because only watcher #1
+//   is the one the layer holds; #2 and #3 stayed closed with 0 paths for the
+//   rest of the process. At most two live watchers, whatever the restart count.
+//
+//   The revived one is NOT a second full watcher. `close()` wipes its watched
+//   set, and the loader re-adds only the collection dirs: 3 dirs / 6 paths
+//   against the live watcher's 41 / 123. Under inotify that is a handful of
+//   descriptors; under CHOKIDAR_USEPOLLING it polls six paths, not the tree.
+//
+// The redundant work is therefore one full sync per content edit alongside the
+// layer's own single-file update: 7.7ms median over the fixture's four entries,
+// growing with entry count. That is the price of an arm that cannot go stale,
+// and it is why narrowing watcher #1 with `unwatch` was NOT done: it would buy
+// back six watched paths and cost the self-heal.
+//
+// STDOUT SIGNALS. One single-line JSON object per event, every one keyed
+// `iterant` so the preview supervisor (which already matches Astro's `ready in`
+// line) can filter them out of the dev log. Every `at`/timestamp field in this
+// integration, on stdout, over HMR and in the dev-state body alike, is an ISO
+// 8601 string in UTC, as `new Date().toISOString()` writes it
+// (`2026-09-11T15:51:32.589Z`), never an epoch number:
+//
+//   {"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":[...]}
+//   {"iterant":"dev-server","event":"content-sync-failed","restart":true,"paths":[...],"error":"..."}
+//
+// `paths` are root-relative (`src/content/pages/home.json`), which is what a
+// writer wrote and the only key shape that survives a relocated tree. An empty
+// `paths` is the arm-time sync below, which belongs to no single file.
+//
+// The two `restart` lines are emitted only on a restarted server; `ready`
+// carries the flag instead, so a supervisor reading only `ready` still learns
+// which kind of server it got. Exactly one `ready` per server, boot or restart,
+// emitted when its httpServer starts listening.
+//
+// Those two moments are also the window preview-error-shell reads before it
+// goes and fetches /under-construction for its cache (`dev-restart-state`).
+// Nothing of ours may reach back through this port while the server behind it
+// is being replaced.
+//
+// HMR EVENTS, on this server's channel:
+//
+//   iterant:server-ready    { restart, at }   as each client connects
+//   iterant:content-synced  { paths, at }     after each sync
+//
+// There is deliberately no "restarting" event: by the time any hook on the new
+// server runs the old one is gone, so nothing could have sent it to the client
+// that was connected. `iterant:server-ready` is the arrival half of the same
+// signal, and it goes out on connection rather than at startup because a
+// payload sent before a client attaches is dropped.
+//
+// DEV STATE, mounted on the dev server's own middleware stack. Both routes
+// require the 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 this integration were not installed (404 for the GET, and
+// 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:
+//
+//   GET  /__iterant/dev-state  -> restart flag, start time, last sync, digests
+//   POST /__iterant/refresh    -> forces one refreshContent()
+//
+// The digests are computed here, from the files on disk the content layer would
+// load. What the layer currently HOLDS is not reported: the store is reachable
+// only through `astro/dist/content` internals (`globalContentLayer`,
+// `globalDataStore`), which an integration must not import.
+
+const REFRESH_DEBOUNCE_MS = 100;
+const STATE_PATH = "/__iterant/dev-state";
+const REFRESH_PATH = "/__iterant/refresh";
+const STATE_HEADER = "x-iterant-dev-state";
+
+/**
+ * @param {object} options
+ * @param {string} options.pagesDir Page entry dir, relative to the project root.
+ * @param {string} options.chromeDir Chrome and links dir, same.
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function devServerSignals({ pagesDir, chromeDir }) {
+  /** Dev only. Set in astro:config:setup, read by every later hook. */
+  let enabled = false;
+  /** Whether THIS server is an in-place restart rather than the boot server. */
+  let restart = false;
+  /** Project root, no trailing separator: what the reported paths are relative to. */
+  let root = "";
+  /** Absolute content dirs, each with a trailing separator, nested ones collapsed. */
+  let contentDirs = /** @type {string[]} */ ([]);
+  let startedAt = "";
+  /** @type {string | null} */
+  let lastSyncAt = null;
+  /** @type {string[]} */
+  let lastSyncPaths = [];
+
+  return {
+    name: "dev-server-signals",
+    hooks: {
+      "astro:config:setup": ({ command, config, isRestart }) => {
+        if (command !== "dev") return;
+        enabled = true;
+        restart = isRestart;
+        root = fileURLToPath(config.root).replace(/[\\/]$/, "");
+        // resolve(), not join(): a configured dir may carry a trailing slash
+        // (`src/content/`), and join keeps it, so the `+ sep` below would make
+        // `src/content//` and no content path would ever match the prefix.
+        contentDirs = collapseNested(
+          [pagesDir, chromeDir].map((dir) => resolve(root, dir) + sep),
+        );
+        startedAt = new Date().toISOString();
+        if (isRestart) {
+          // The same moment, shared with preview-error-shell: from here until
+          // this server listens, a fetch back through the port would be aimed
+          // at a server still being replaced (see dev-restart-state).
+          beginRestart();
+          signal({ event: "restart", phase: "config" });
+        }
+      },
+
+      "astro:server:setup": ({ server, refreshContent }) => {
+        if (!enabled) return;
+        if (restart) signal({ event: "restart", phase: "setup" });
+
+        // Astro declares `refreshContent` optional and takes its options
+        // object by value; passing none of its keys syncs every loader.
+        const sync = () => refreshContent?.({}) ?? Promise.resolve();
+
+        /** @type {ReturnType<typeof setTimeout> | undefined} */
+        let timer;
+        /** @type {Set<string>} */
+        const pending = new Set();
+
+        const refresh = async () => {
+          const paths = [...pending].sort();
+          pending.clear();
+          try {
+            await sync();
+          } catch (error) {
+            // A malformed entry rejects the whole loader chain. Report it as
+            // its own event rather than letting the rejection go unhandled:
+            // the next write retries, and a supervisor that sees this knows
+            // the store is behind the digests the state route reports.
+            signal({
+              event: "content-sync-failed",
+              restart,
+              paths,
+              error: String(error instanceof Error ? error.message : error),
+            });
+            return;
+          }
+          lastSyncAt = new Date().toISOString();
+          lastSyncPaths = paths;
+          signal({ event: "content-synced", restart, paths });
+          server.hot.send({
+            type: "custom",
+            event: "iterant:content-synced",
+            data: { paths, at: lastSyncAt },
+          });
+        };
+
+        // Coalesce a burst (a multi-entry write, a branch checkout) into one
+        // sync: reset the timer per event and fire once the tree settles.
+        /** @param {string} [path] */
+        const scheduleRefresh = (path) => {
+          if (path) pending.add(path);
+          clearTimeout(timer);
+          timer = setTimeout(() => void refresh(), REFRESH_DEBOUNCE_MS);
+        };
+
+        // Only on a restarted server. The BOOT server's content layer still
+        // holds a live watcher and runs its own incremental update per event;
+        // arming here too would make every content save run a second full sync
+        // on top of it, for the whole session, to fix nothing.
+        if (restart) {
+          server.watcher.on("all", (event, path) => {
+            if (event !== "add" && event !== "change" && event !== "unlink") {
+              return;
+            }
+            if (!contentDirs.some((dir) => path.startsWith(dir))) return;
+            scheduleRefresh(contentKey(path, root));
+          });
+          // One sync for the gap itself. A write that landed between the old
+          // watcher's close and this arm produced an event nobody was
+          // listening for, and no later event will mention that file, so
+          // waiting for one would strand it until the next unrelated edit.
+          // It rides the same debounce, so a restart plus a burst of writes
+          // is still one sync.
+          scheduleRefresh();
+        }
+
+        // An obsolete generation must not fire after its server is gone: Vite's
+        // in-place restart calls close() on the old server (which closes this
+        // httpServer) before the new one listens, and a timer still pending
+        // then would run one sync and one content-synced event on behalf of a
+        // server nobody is talking to. The same listener covers shutdown.
+        server.httpServer?.once("close", () => clearTimeout(timer));
+
+        server.middlewares.use((req, res, next) => {
+          const path = String(req.url ?? "").split("?")[0];
+          if (path !== STATE_PATH && path !== REFRESH_PATH) return next();
+          // Absent or wrong header: behave as if these routes did not exist.
+          if (req.headers[STATE_HEADER] !== "1") return next();
+          if (path === STATE_PATH && req.method === "GET") {
+            return json(res, 200, {
+              restart,
+              startedAt,
+              contentSync: {
+                armed: restart,
+                lastAt: lastSyncAt,
+                lastPaths: lastSyncPaths,
+              },
+              entries: contentDigests(contentDirs, root),
+            });
+          }
+          if (path === REFRESH_PATH && req.method === "POST") {
+            void sync().then(
+              () => {
+                lastSyncAt = new Date().toISOString();
+                json(res, 200, { ok: true, at: lastSyncAt });
+              },
+              (error) => {
+                json(res, 500, {
+                  ok: false,
+                  error: String(error instanceof Error ? error.message : error),
+                });
+              },
+            );
+            return;
+          }
+          return next();
+        });
+        // Astro's own dev handler registers earlier in the connect stack and
+        // ends the response before later layers run, the same reason
+        // preview-error-shell hoists its layer; these two paths belong to no
+        // route, so they have to be answered before it.
+        const layer = server.middlewares.stack.pop();
+        if (layer) server.middlewares.stack.unshift(layer);
+
+        // The ready line, from the socket rather than from a hook. Astro runs
+        // astro:server:start on the BOOT path only, so a restarted server that
+        // waited for it would never announce itself; 'listening' is the moment
+        // both paths share, and it is also the first moment the routes above
+        // can actually be reached.
+        server.httpServer?.once("listening", () => {
+          endRestart();
+          signal({ event: "ready", restart });
+        });
+
+        // The same news over HMR, as clients arrive. It cannot be sent from a
+        // hook: an HMR payload with no client attached is dropped, and on a
+        // restart the client that was open has not finished reconnecting yet.
+        // This states a FACT about the server rather than announcing a moment,
+        // so a client connecting later still wants it, and one already attached
+        // can take it twice without harm.
+        server.ws.on("connection", () =>
+          server.hot.send({
+            type: "custom",
+            event: "iterant:server-ready",
+            data: { restart, at: new Date().toISOString() },
+          }),
+        );
+      },
+    },
+  };
+}
+
+/**
+ * One signal line on stdout. Written directly rather than through Astro's
+ * logger, which wraps and colorizes: a supervisor parses these, so they have to
+ * stay one line of plain JSON.
+ *
+ * @param {Record<string, unknown>} fields
+ */
+function signal(fields) {
+  process.stdout.write(
+    `${JSON.stringify({ iterant: "dev-server", ...fields })}\n`,
+  );
+}
+
+/**
+ * @param {import("node:http").ServerResponse} res
+ * @param {number} status
+ * @param {unknown} body
+ */
+function json(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * The dirs to walk and watch, with any dir that sits inside another dropped.
+ * The default layout nests the two (`src/content` holds `src/content/pages`),
+ * and walking both would digest the page entries twice.
+ *
+ * @param {string[]} dirs
+ * @returns {string[]}
+ */
+function collapseNested(dirs) {
+  const sorted = [...new Set(dirs)].sort();
+  return sorted.filter(
+    (dir, index) =>
+      !sorted.slice(0, index).some((kept) => dir.startsWith(kept)),
+  );
+}
+
+/**
+ * A content file's reported key: its path relative to the project root, with
+ * forward slashes. Root-relative rather than dir-relative because two relocated
+ * dirs can hold the same file name, and because it is the path a writer wrote.
+ *
+ * @param {string} path
+ * @param {string} root
+ */
+function contentKey(path, root) {
+  return relative(root, path).split(sep).join("/");
+}
+
+/**
+ * sha256 of every content entry on disk, keyed by `contentKey`. Every
+ * collection this runtime defines loads `.json` out of these dirs, so the walk
+ * needs no per-collection knowledge. An absent dir is a real state (a repo
+ * before its first entry lands) and reports as no entries.
+ *
+ * @param {string[]} dirs
+ * @param {string} root
+ * @returns {Record<string, string>}
+ */
+function contentDigests(dirs, root) {
+  /** @type {Record<string, string>} */
+  const digests = {};
+  /** @param {string} current */
+  const walk = (current) => {
+    /** @type {import("node:fs").Dirent[]} */
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+      } else if (entry.name.endsWith(".json")) {
+        digests[contentKey(path, root)] = createHash("sha256")
+          .update(readFileSync(path))
+          .digest("hex");
+      }
+    }
+  };
+  for (const dir of dirs) walk(dir);
+  return digests;
+}

package/src/integrations/preview-error-shell.mjs

@@ -1,4 +1,5 @@
 // @ts-check
+import { restartInFlight } from "./dev-restart-state.mjs";
 
 // Dev-only branded fallback for broken routes (2026-07-06): mid-build there
 // is a window where a route exists but its page component doesn't (the shell
@@ -10,6 +11,33 @@
 // /under-construction shell (navbar + footer + "in progress"). The 5xx
 // status is preserved on purpose — verify probes and the save gate must
 // still see the failure; only the human-facing body changes.
+//
+// NOTHING IS FETCHED FROM INSIDE A FAILING REQUEST (3.8.1). Until 3.8.0 the
+// 5xx path fetched /under-construction back through this same port while it
+// held the failing response open, and that wedged the dev server for good.
+// Measured in Docker, on the site-config edit that restarts the server in
+// place: an in-flight request resolves 500 `fetch failed` (the Cloudflare
+// plugin's miniflare goes down under it), the shell's self-fetch answers 200
+// in 271ms, and from then on every request that reaches workerd renders (the
+// worker logs its own 200) and never reaches the client, for the whole 120s
+// probe window. Node's own middleware still answers in 8ms, so what the
+// nested request leaves broken is the node-to-workerd path, inside
+// @cloudflare/vite-plugin. With the same self-fetch gone the same edit
+// recovered in 6s, and with the whole integration off, in 11s.
+//
+// So the branded body is CACHED instead, and a 5xx answers from memory with no
+// I/O at all. The one fetch that fills the cache runs after a request this
+// server has just ANSWERED, page and all: the only moment it is known to be
+// able to render its own route, and the furthest possible moment from a
+// restart. Nothing waits on that fetch, it carries an abort timeout, and it
+// does not run while `dev-server-signals` says a restart is in flight. One
+// server fetches once, and a restarted server fetches again off its own first
+// page, which is what picks up an edited navbar.
+//
+// The cached body outlives the server that fetched it, so a preview that has
+// shown the branded shell keeps showing it across a restart. Before the first
+// page of a session renders there is nothing to cache, and a break that early
+// gets the static shell below.
 
 // vite is astro's dependency, not this package's, so the dev-server type is
 // derived from the hook astro hands it to. One vite in the type graph, whichever
@@ -20,9 +48,41 @@
  * >[0]["server"]} ViteDevServer
  */
 
+/**
+ * Whether THIS server has the branded body yet, whether a fetch for it is
+ * already out, and how many it has spent trying.
+ *
+ * @typedef {{ warmed: boolean, warming: boolean, attempts: number }} WarmState
+ */
+
 const FALLBACK_PATH = "/under-construction";
 
-// Served when /under-construction itself can't render (e.g. Layout broken).
+/**
+ * How long a warm fetch may take before it is abandoned. Nothing waits on it,
+ * so it can be patient: a cold server rendered this route in 5.3s under
+ * Docker. It is bounded all the same, because a fetch that never settles would
+ * hold `warming` up and leave the cache unfillable for the rest of the server.
+ */
+const WARM_TIMEOUT_MS = 10_000;
+
+/**
+ * The branded body, once some server has managed to fetch it. Module scope on
+ * purpose: an in-place restart builds a new server, and a preview that has
+ * been showing the branded shell should not drop back to the static one while
+ * the new server warms up.
+ */
+let cachedShell = "";
+
+/**
+ * How many times one server tries. A repo whose /under-construction route is
+ * gone answers 404 forever, and without a cap every page view would spend a
+ * fetch on it.
+ */
+const WARM_ATTEMPTS = 3;
+
+// Served until the branded body is cached, and after that only if the branded
+// fetch keeps failing: /under-construction not rendering (a broken Layout), or
+// a break before this session has rendered any page at all.
 const MINIMAL_FALLBACK = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>Page in progress</title></head>
 <body style="display:flex;min-height:100vh;align-items:center;justify-content:center;font-family:system-ui,sans-serif">
@@ -42,6 +102,14 @@ export default function previewErrorShell() {
               {
                 name: "preview-error-shell",
                 configureServer(server) {
+                  // Per server, so a restarted one warms again. The body it
+                  // fetches is shared; whether THIS server has fetched it is
+                  // not.
+                  const state = {
+                    warmed: false,
+                    warming: false,
+                    attempts: 0,
+                  };
                   server.middlewares.use((req, res, next) => {
                     const accept = String(req.headers.accept ?? "");
                     if (
@@ -51,7 +119,7 @@ export default function previewErrorShell() {
                     ) {
                       return next();
                     }
-                    intercept(server, res);
+                    intercept(server, state, res);
                     next();
                   });
                   // Astro's own dev handler registers earlier in the connect
@@ -72,13 +140,14 @@ export default function previewErrorShell() {
 
 /**
  * Buffer the response; replay it verbatim unless it resolves to a 5xx, in
- * which case serve the branded fallback body instead. Buffering trades dev
+ * which case serve the cached fallback body instead. Buffering trades dev
  * streaming for the swap — fine for a preview.
  *
  * @param {ViteDevServer} server
+ * @param {WarmState} state
  * @param {import("node:http").ServerResponse} res
  */
-function intercept(server, res) {
+function intercept(server, state, res) {
   /** @type {Array<string | Buffer>} */
   const chunks = [];
   /** @type {unknown[] | null} */
@@ -112,34 +181,45 @@ function intercept(server, res) {
         res.end = original.end;
         if (headArgs) original.writeHead(.../** @type {[number]} */ (headArgs));
         for (const c of chunks) original.write(c);
-        return original.end();
+        const answered = original.end();
+        // This server just proved it can render a page of its own. That is the
+        // moment, and the only one, to go and get the branded body.
+        if (!state.warmed) warm(server, state);
+        return answered;
       }
-      void serveFallback(server, original, status);
-      return res;
+      original.writeHead(status, {
+        "content-type": "text/html",
+        "x-preview-fallback": "1",
+      });
+      original.write(cachedShell || MINIMAL_FALLBACK);
+      return original.end();
     }
   );
 }
 
 /**
+ * Fetch the branded body into the cache. Fire and forget: nothing waits on it,
+ * no response is open on it, and a failure leaves the previous body in place.
+ *
  * @param {ViteDevServer} server
- * @param {{ writeHead: Function, write: Function, end: Function }} original
- * @param {number} status
+ * @param {WarmState} state
  */
-async function serveFallback(server, original, status) {
-  let html = MINIMAL_FALLBACK;
-  try {
-    const port = server.config.server.port;
-    const resp = await fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
-      headers: { accept: "text/html" },
+function warm(server, state) {
+  if (state.warming || state.attempts >= WARM_ATTEMPTS) return;
+  if (restartInFlight()) return;
+  state.warming = true;
+  state.attempts += 1;
+  const port = server.config.server.port;
+  void fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
+    headers: { accept: "text/html" },
+    signal: AbortSignal.timeout(WARM_TIMEOUT_MS),
+  })
+    .then((resp) => (resp.ok ? resp.text() : ""))
+    .catch(() => "")
+    .then((html) => {
+      state.warming = false;
+      if (!html) return;
+      state.warmed = true;
+      cachedShell = html;
     });
-    if (resp.ok) html = await resp.text();
-  } catch {
-    // fall through to the minimal shell
-  }
-  original.writeHead(status, {
-    "content-type": "text/html",
-    "x-preview-fallback": "1",
-  });
-  original.write(html);
-  original.end();
 }

package/src/integrations/site-config-watch.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+// The repo's site config, added to the dev server's restart list (2026-09-11).
+//
+// Astro restarts on its own config file, package.json and the tsconfig sources,
+// and on nothing else: `core/dev/restart.js` compares every add/change/unlink
+// against `settings.watchFiles`, and `addWatchFile` is the only way into that
+// list. src/site-config.ts is not on it by default, yet SITE_CONFIG.fonts is
+// read TWICE from two different places: the preset passes it to Astro's font
+// config (resolved once, at server start) and the layout renders `<Font>` from
+// it per request. Without this, adding a family to that array would render a
+// face the server never resolved, for the rest of the session, and the page
+// would fall back to the system stack with no error anywhere.
+//
+// The restart this causes is Astro's in-place kind, which leaves the content
+// layer bound to the closed watcher; `dev-server-signals` re-arms it. That is
+// what makes watching this file a fix rather than a trade.
+//
+// Not gated on `command`: the hook states that this file feeds the config,
+// which is true in every command, and Astro reads watchFiles in dev alone.
+
+/**
+ * @param {string} siteConfigPath The repo's site config module, relative to the
+ *   project root. Resolved against `config.root` rather than `process.cwd()`:
+ *   the two differ whenever Astro runs with an explicit `--root`, and a watch
+ *   entry that names a path nothing writes to is a watch that never fires.
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function siteConfigWatch(siteConfigPath) {
+  return {
+    name: "site-config-watch",
+    hooks: {
+      "astro:config:setup": ({ config, addWatchFile }) => {
+        addWatchFile(new URL(siteConfigPath, config.root));
+      },
+    },
+  };
+}