@iterant/site-runtime 3.8.2 → 3.10.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.10.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -157,7 +157,7 @@ CommonMark, stored as written.
 
   const body = readMarkdown(data.body); // raw CommonMark | null
   <div
-    class="prose"
+    class="markdown-body"
     data-editable="body"
     data-path="props.body"
     data-edit-type="markdown"
@@ -165,6 +165,22 @@ CommonMark, stored as written.
   />;
   ```
 
+- **`markdown-body` is the wrapper class, and the stylesheet is opt-in
+  (3.10.0).** The compiler emits bare `<h2>`, `<ul>` and `<blockquote>`, and
+  Preflight flattens all three to paragraph size, so an unstyled body renders as
+  a run of identical lines. Add the import to `src/styles/globals.css` once,
+  below `@import "tailwindcss"`:
+
+  ```css
+  @import "@iterant/site-runtime/styles/markdown.css";
+  ```
+
+  It styles measure, rhythm and hierarchy from the repo's own `--it-*` and
+  `--font-*` tokens, and reads two knobs of its own:
+  `--it-markdown-measure` (the reading width, `68ch`, `none` to fill) and
+  `--it-markdown-flow` (the space between blocks, `1.25em`). Every rule sits in
+  the `base` layer, so a utility class on the wrapper still wins.
+
 - **Headings start at `##`.** The body renders below the page's own h1; the
   compiler does not demote levels for you.
 - Hrefs inside the value follow the same rules as link wrappers: root-relative
@@ -617,13 +633,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.10.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": {
@@ -27,6 +27,7 @@
     "docs",
     "scripts",
     "src",
+    "styles",
     "!**/*.test.ts",
     "!scripts/check-fixture.mjs",
     "!scripts/check-packed.mjs",
@@ -59,6 +60,7 @@
     "./routes": "./src/routes/index.ts",
     "./config": "./src/config/preset.ts",
     "./integrations/*": "./src/integrations/*.mjs",
+    "./styles/markdown.css": "./styles/markdown.css",
     "./package.json": "./package.json"
   },
   "iterant": {

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);

package/styles/markdown.css

@@ -0,0 +1,221 @@
+/*
+ * The article-body stylesheet: `class="markdown-body"` around compiled
+ * `renderMarkdown` output.
+ *
+ * It exists because `renderMarkdown` is bare micromark: it emits `<h2>`, `<ul>`
+ * and `<blockquote>` with no classes, and Tailwind's Preflight flattens every
+ * one of them to the paragraph's size, weight and margin. A body compiled
+ * without this file renders as a run of identical lines, which is what a blog
+ * post looked like through 3.9.0.
+ *
+ * OPT-IN, and imported once. The package ships no stylesheet of its own and
+ * LayoutCore imports none, so nothing here reaches a brand until that brand's
+ * `globals.css` names it:
+ *
+ *   @import "@iterant/site-runtime/styles/markdown.css";
+ *
+ * Put the line AFTER `@import "tailwindcss"`. Everything below lives in the
+ * `base` layer, so it wins over Preflight by order and loses to every utility
+ * class: `class="markdown-body text-lg"` still reads as the site author wrote
+ * it, and a brand rule outside a layer overrides anything here.
+ *
+ * Colors, fonts, radius and border come from the `--it-*` and `--font-*` tokens
+ * a brand's `globals.css` defines, each with a fallback so the file also works
+ * in a repo that defines none. Two knobs are its own, settable on any ancestor:
+ *
+ *   --it-markdown-measure   the reading width (default 68ch; `none` to fill)
+ *   --it-markdown-flow      the space between blocks (default 1.25em)
+ */
+
+@layer base {
+  .markdown-body {
+    color: var(--it-text-primary, currentColor);
+    font-family: var(--font-body, inherit);
+    font-size: var(--font-size-base, 1rem);
+    font-weight: var(--font-body-weight, 400);
+    line-height: var(--font-body-line-height, 1.7);
+    max-width: var(--it-markdown-measure, 68ch);
+  }
+
+  /* The wrapper's own spacing belongs to the page around it. */
+  .markdown-body > :first-child {
+    margin-top: 0;
+  }
+
+  .markdown-body > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown-body p {
+    margin: 0 0 var(--it-markdown-flow, 1.25em);
+  }
+
+  /* A body opens at `##` under the page's own h1, so h2 carries the section
+     weight here. h1 is styled anyway: a pasted body that starts at `#` should
+     read as a heading rather than as an outsized paragraph. */
+  .markdown-body h1,
+  .markdown-body h2,
+  .markdown-body h3,
+  .markdown-body h4 {
+    color: var(--it-text-primary, currentColor);
+    font-family: var(--font-heading, inherit);
+    font-weight: var(--font-heading-weight, 700);
+    letter-spacing: var(--font-heading-letter-spacing, normal);
+    line-height: var(--font-heading-line-height, 1.2);
+    margin: 2em 0 0.6em;
+    text-wrap: balance;
+  }
+
+  .markdown-body h1 {
+    font-size: var(--font-size-3xl, 1.875rem);
+  }
+
+  .markdown-body h2 {
+    font-size: var(--font-size-2xl, 1.5rem);
+  }
+
+  .markdown-body h3 {
+    font-size: var(--font-size-xl, 1.25rem);
+  }
+
+  .markdown-body h4 {
+    font-size: var(--font-size-lg, 1.125rem);
+  }
+
+  .markdown-body ul,
+  .markdown-body ol {
+    margin: 0 0 var(--it-markdown-flow, 1.25em);
+    padding-left: 1.5em;
+  }
+
+  .markdown-body ul {
+    list-style: disc;
+  }
+
+  .markdown-body ol {
+    list-style: decimal;
+  }
+
+  .markdown-body ul ul {
+    list-style: circle;
+  }
+
+  .markdown-body li {
+    margin-block: 0.35em;
+  }
+
+  .markdown-body li::marker {
+    color: var(--it-text-secondary, currentColor);
+  }
+
+  /* A nested list is part of its parent item, not a new block. */
+  .markdown-body li > ul,
+  .markdown-body li > ol {
+    margin-block: 0.35em;
+  }
+
+  .markdown-body li > p {
+    margin-bottom: 0.35em;
+  }
+
+  .markdown-body blockquote {
+    border-left: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    color: var(--it-text-secondary, currentColor);
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    padding-left: 1.25em;
+  }
+
+  .markdown-body blockquote > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown-body code {
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: 0.9em;
+  }
+
+  /* A code span is a chip; a fence is a surface. */
+  .markdown-body :not(pre) > code {
+    background-color: var(--it-background-secondary, transparent);
+    border-radius: calc(var(--radius, 0.5rem) / 2);
+    padding: 0.15em 0.4em;
+  }
+
+  .markdown-body pre {
+    background-color: var(--it-background-secondary, transparent);
+    border-radius: var(--radius, 0.5rem);
+    line-height: 1.55;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    overflow-x: auto;
+    padding: 1em 1.15em;
+  }
+
+  .markdown-body pre code {
+    background-color: transparent;
+    font-size: inherit;
+    padding: 0;
+  }
+
+  /* The link keeps the body's color: an accent token is a background color in
+     some brand palettes, and a link mid-sentence has to stay readable in all of
+     them. The underline is what marks it. */
+  .markdown-body a {
+    color: inherit;
+    text-decoration: underline;
+    text-decoration-thickness: from-font;
+    text-underline-offset: 0.2em;
+  }
+
+  .markdown-body a:hover {
+    text-decoration-thickness: 2px;
+  }
+
+  .markdown-body strong {
+    color: var(--it-text-primary, currentColor);
+    font-weight: var(--font-body-bold-weight, 600);
+  }
+
+  .markdown-body hr {
+    border: 0;
+    border-top: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    margin: 2.5em 0;
+  }
+
+  .markdown-body img {
+    display: block;
+    height: auto;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    max-width: 100%;
+  }
+
+  /* GFM tables. The table itself scrolls, so a wide one never widens the page. */
+  .markdown-body table {
+    border-collapse: collapse;
+    display: block;
+    font-size: 0.95em;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    max-width: 100%;
+    overflow-x: auto;
+    width: max-content;
+  }
+
+  .markdown-body th,
+  .markdown-body td {
+    border: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    padding: 0.5em 0.75em;
+  }
+
+  /* gfm writes `align` on a column the author aligned; only the rest defaults. */
+  .markdown-body th:not([align]),
+  .markdown-body td:not([align]) {
+    text-align: left;
+  }
+
+  .markdown-body th {
+    background-color: var(--it-background-secondary, transparent);
+    font-weight: var(--font-body-bold-weight, 600);
+  }
+}