@iterant/site-runtime 3.6.1 → 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.6.1._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -81,6 +81,7 @@ _Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.1._
 | `tw-animate-css`           | 1.4.0   | the animation utilities Tailwind v4 dropped           |
 | `github-slugger`           | 2.0.0   | heading and anchor slugs                              |
 | `micromark`                | 4.0.2   | the CommonMark compiler markdown wrappers render with |
+| `micromark-extension-gfm`  | 3.0.0   | tables, task lists and strikethrough on top of it     |
 
 <!-- /generated -->
 
@@ -351,6 +352,48 @@ is what puts the component in the client bundle siblings hydrate from. The
 bespoke-sibling gate enforces both on every non-draft bespoke page, after the
 build.
 
+## Forms (3.7.0)
+
+A capturing form posts to the platform, never to a backend of its own. The
+authored convention (an action-less `<form data-iterant-form="<key>">`, the
+`_hp` honeypot, a hidden `data-iterant-form-success` sibling) is what the
+injected runtime and the edge's native fallback act on, and `IterantForm`
+renders exactly that markup so a page stops hand-writing it. Rendered
+statically it behaves as the authored markup does: the runtime intercepts the
+submit and reveals the success element. Hydrated (`client:load`, or inside a
+bespoke page) it owns the submit: it marks the form `data-iterant-form-managed`
+on mount, which is how the runtime knows to stand down, posts the same body to
+the same endpoint, disables the submit button with `aria-busy` while in flight,
+shows the success or the error message, resets the fields on success and never
+navigates. `name` is required and is the form key the submissions dashboard
+aggregates on. `successMessage` and `errorMessage` take a wrapped text value or
+a plain string, so a section passes its entry copy straight through, and an
+absent value falls back to the package default. It ships no utility classes:
+the page styles the form through `className`, the state through
+`data-iterant-form-state` (`idle`, `pending`, `success`, `error`) and the two
+message elements through their attributes.
+
+```tsx
+import { readText } from "@iterant/site-runtime/content-values";
+import { IterantForm } from "@iterant/site-runtime/forms";
+
+<IterantForm name={readText(data.formKey)} successMessage={data.successCopy}>
+  <label htmlFor="email">{readText(data.emailLabel)}</label>
+  <input id="email" name="email" type="email" required />
+  <button type="submit">{readText(data.submitLabel)}</button>
+</IterantForm>;
+```
+
+`submitForm(name, fields)` is the same post without the component, for a
+multi-step form or a custom handler. It resolves to `{ ok: true }` or
+`{ ok: false, error }` and never throws, whether the platform accepted,
+refused (`rate_limited`, `turnstile_failed`) or was unreachable (`network`).
+Values are strings only: a `File` is refused as `unsupported_field:<name>`, and
+`readFormFields` turns a form's `FormData` into the record it takes. Pass one
+`idempotencyKey` across retries of a submission and the platform collapses them
+to one row. Submissions are captured on a published site; the dev server has no
+endpoint, so a preview submit settles as an error and captures nothing.
+
 ## Structured data is derived, never authored
 
 Every indexable page emits a schema.org graph (Organization, WebSite, the page
@@ -400,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
@@ -500,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
@@ -524,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.6.1",
+  "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,11 +44,14 @@
     "./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",
     "./seo": "./src/components/seo.tsx",
     "./seo-json": "./src/components/seo-json.tsx",
+    "./forms": "./src/components/forms.tsx",
     "./layout": "./src/layouts/LayoutCore.astro",
     "./layout-core": "./src/layouts/layout-core.ts",
     "./layout-contract": "./src/layouts/layout-contract.ts",
@@ -81,7 +84,8 @@
       "class-variance-authority",
       "tw-animate-css",
       "github-slugger",
-      "micromark"
+      "micromark",
+      "micromark-extension-gfm"
     ]
   },
   "dependencies": {
@@ -98,6 +102,7 @@
     "github-slugger": "2.0.0",
     "lucide-react": "1.31.0",
     "micromark": "4.0.2",
+    "micromark-extension-gfm": "3.0.0",
     "motion": "13.0.0",
     "radix-ui": "1.6.7",
     "react": "19.2.8",
@@ -114,6 +119,7 @@
     "@types/node": "24.3.1",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
+    "jsdom": "^26.0.0",
     "typescript": "5.9.2",
     "vitest": "^4.0.13",
     "wrangler": "^4.107.0"

package/src/components/forms.tsx

@@ -0,0 +1,155 @@
+import {
+  type FormEvent,
+  type ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { type ContentLeaf, readText } from "../lib/content-values";
+import {
+  FORM_HONEYPOT_FIELD,
+  mintIdempotencyKey,
+  readFormFields,
+  submitForm,
+} from "../lib/submit-form";
+
+export { readFormFields, submitForm } from "../lib/submit-form";
+export type { SubmitFormOptions, SubmitFormResult } from "../lib/submit-form";
+
+export const DEFAULT_SUCCESS_MESSAGE = "Thanks for your submission!";
+export const DEFAULT_ERROR_MESSAGE = "Something went wrong. Please try again.";
+
+export interface IterantFormProps {
+  /** The form key: `data-iterant-form`, and what the submissions dashboard
+   *  aggregates on. */
+  name: string;
+  /** A wrapped text value or a plain string; anything else, or an empty one,
+   *  falls back to the default. */
+  successMessage?: ContentLeaf;
+  errorMessage?: ContentLeaf;
+  className?: string;
+  children?: ReactNode;
+  onSuccess?(): void;
+}
+
+type FormState = "idle" | "pending" | "success" | "error";
+
+// The capturing form of the forms convention (an action-less
+// `data-iterant-form`, the `_hp` honeypot, a hidden success sibling), rendered
+// once so pages stop hand-writing it. Rendered statically it IS that markup and
+// the injected runtime submits it. Hydrated, it owns the submit: same body,
+// same endpoint, its own pending, success and error states, no navigation.
+export function IterantForm({
+  name,
+  successMessage,
+  errorMessage,
+  className,
+  children,
+  onSuccess,
+}: IterantFormProps) {
+  const [state, setState] = useState<FormState>("idle");
+  // Set after mount, never in the static render: the mark is what tells the
+  // injected runtime this form's submit has an owner and to stand down.
+  const [managed, setManaged] = useState(false);
+  useEffect(() => {
+    setManaged(true);
+  }, []);
+  const inFlight = useRef(false);
+  // One key per submission, reused on retry so the platform collapses a
+  // retried post to one row, and dropped once the submission is accepted.
+  const idempotencyKey = useRef<string | null>(null);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    // A runtime from before the managed mark took this submit in its
+    // capture-phase listener and posts it itself.
+    if (event.isDefaultPrevented()) return;
+    event.preventDefault();
+    if (inFlight.current) return;
+    const form = event.currentTarget;
+    // A runtime from before the managed mark may have posted this form while
+    // the page was still static and be waiting on the edge: its in-flight mark
+    // stands down this submit, and its key is the one a retry reuses, so the
+    // platform collapses both posts to one row.
+    if (form.dataset.iterantSubmitting === "1") return;
+    inFlight.current = true;
+    const release = markBusy(form);
+    setState("pending");
+    idempotencyKey.current ??= form.dataset.iterantIk || mintIdempotencyKey();
+    const result = await submitForm(name, readFormFields(form), {
+      idempotencyKey: idempotencyKey.current,
+    });
+    release();
+    inFlight.current = false;
+    if (!result.ok) {
+      setState("error");
+      return;
+    }
+    idempotencyKey.current = null;
+    form.reset();
+    setState("success");
+    onSuccess?.();
+  }
+
+  return (
+    <div>
+      <form
+        data-iterant-form={name}
+        data-iterant-form-managed={managed ? "" : undefined}
+        data-iterant-form-state={state}
+        className={className}
+        onSubmit={handleSubmit}
+      >
+        <input
+          type="text"
+          name={FORM_HONEYPOT_FIELD}
+          tabIndex={-1}
+          autoComplete="off"
+          aria-hidden="true"
+          style={{ position: "absolute", left: "-9999px" }}
+        />
+        {children}
+      </form>
+      <p
+        data-iterant-form-success=""
+        role="status"
+        hidden={state !== "success"}
+      >
+        {readText(successMessage) || DEFAULT_SUCCESS_MESSAGE}
+      </p>
+      <p data-iterant-form-error="" role="alert" hidden={state !== "error"}>
+        {readText(errorMessage) || DEFAULT_ERROR_MESSAGE}
+      </p>
+    </div>
+  );
+}
+
+// The submit controls are the caller's children, so the pending state goes on
+// the live elements: `aria-busy` for assistive tech and the page's styles,
+// `disabled` so a second click cannot start a second submission.
+function markBusy(form: HTMLFormElement): () => void {
+  const restore = Array.from(form.elements)
+    .filter(isSubmitControl)
+    .map((control) => {
+      const wasDisabled = control.disabled;
+      control.disabled = true;
+      control.setAttribute("aria-busy", "true");
+      return () => {
+        control.disabled = wasDisabled;
+        control.removeAttribute("aria-busy");
+      };
+    });
+  return () => {
+    for (const fn of restore) fn();
+  };
+}
+
+function isSubmitControl(
+  element: Element,
+): element is HTMLButtonElement | HTMLInputElement {
+  return (
+    (element instanceof HTMLButtonElement ||
+      element instanceof HTMLInputElement) &&
+    element.type === "submit"
+  );
+}

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