@iterant/site-runtime 3.6.1 → 3.8.0

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

@@ -0,0 +1,392 @@
+// @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";
+
+// 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.
+//
+// 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) 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", () =>
+          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/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));
+      },
+    },
+  };
+}

package/src/layouts/LayoutCore.astro

@@ -1,9 +1,11 @@
 ---
+import { Font, fontData } from "astro:assets";
 import { getCollection, getEntry } from "astro:content";
 import type { AstroComponentFactory } from "astro/runtime/server/index.js";
 import RelatedLinks from "../components/RelatedLinks.astro";
 import { SEO, type PageType } from "../components/seo";
 import type { SeoJsonSchema } from "../components/seo-json";
+import { fontCssVariable } from "../fonts/catalog";
 import type { HreflangAlternate } from "../lib/hreflang";
 import { DEFAULT_LOCALE, localeFromPath } from "../lib/locales";
 import { SITE_RUNTIME_VERSION } from "../version";
@@ -14,6 +16,7 @@ import {
   resolveAbsoluteUrl,
   resolveStructuredData,
   routePathFromPathname,
+  selectFontFamilies,
   type LayoutSiteConfig,
   type SiteShell,
 } from "./layout-core";
@@ -151,6 +154,41 @@ const shellId = shell ?? pageEntry?.data.shell;
 const linksEntry = await getEntry("links", "links");
 const linksSlice = linksEntry?.data.routes[routePath];
 
+// Web fonts (3.8.0): a `@font-face` block per family the site names in
+// SITE_CONFIG.fonts, and a preload link for each. Never the whole catalog:
+// every family rendered here inlines its faces into EVERY page.
+//
+// `fontData` is Astro's own runtime view of the resolved font config, keyed by
+// CSS variable, so it is what decides whether a family can render. The rule and
+// the fallback live in selectFontFamilies, which is testable without a render.
+const fonts = selectFontFamilies(siteConfig.fonts, (cssVariable) =>
+  Object.hasOwn(fontData, cssVariable),
+);
+
+// A named family nothing declared is a repo whose astro.config and site config
+// disagree, which no gate catches and no render shows. Said once, in dev, where
+// the author is looking.
+if (import.meta.env.DEV && fonts.undeclared.length > 0) {
+  console.warn(
+    `[site-runtime] SITE_CONFIG.fonts names ${fonts.undeclared.join(", ")}, which astro.config did not declare. Pass the same list to iterantStarter({ fonts }).`,
+  );
+}
+
+// The cast is Astro's own type: once a repo configures fonts, `astro sync` narrows
+// CssVariable to the exact literals in that config. Every variable here is one
+// fontData carries, which is the same set, but the compiler cannot see that
+// through a runtime string.
+const fontVariables = fonts.families.map((family) =>
+  fontCssVariable(family),
+) as Array<import("astro:assets").CssVariable>;
+
+// Preload 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. Preloading every face instead
+// measured 8 files and 436K of blocking requests for two families, on a page
+// that renders four words of plain latin text.
+const fontPreload = fonts.named ? [{ style: "normal", subset: "latin" }] : false;
+
 // Version identity: the installed package version IS the site's runtime
 // version. `it-astro-starter-version` keeps emitting the same value while the
 // plugin loader and the platform's page indexer still read that name, and
@@ -176,6 +214,11 @@ const linksSlice = linksEntry?.data.routes[routePath];
     <meta name="generator" content={Astro.generator} />
     <meta name="it-site-runtime" content={SITE_RUNTIME_VERSION} />
     <meta name="it-astro-starter-version" content={SITE_RUNTIME_VERSION} />
+    {
+      fontVariables.map((cssVariable) => (
+        <Font cssVariable={cssVariable} preload={fontPreload} />
+      ))
+    }
     <SEO
       title={title}
       description={description}

package/src/layouts/layout-core.ts

@@ -1,4 +1,5 @@
 import type { PageType } from "../components/seo";
+import { DEFAULT_FONT_FAMILIES, fontCssVariable } from "../fonts/catalog";
 import type { ContentProps } from "../lib/content-values";
 
 // The pure half of LayoutCore.astro: URL resolution, chrome lookup, and the
@@ -16,6 +17,14 @@ export interface LayoutSiteConfig {
   description: string;
   logo?: string;
   sameAs?: string[];
+  /**
+   * Font families this site uses, by catalog name (`["Fraunces", "Inter"]`).
+   * The head carries a `@font-face` block per family, so this is the list of
+   * families the site actually sets somewhere, not everything it may choose
+   * from. The repo passes the same array to `iterantStarter({ fonts })`; a
+   * family missing there has no CSS variable to render and is skipped.
+   */
+  fonts?: string[];
 }
 
 /**
@@ -141,3 +150,50 @@ export function resolveStructuredData(
 }
 
 export { LAYOUT_CONTRACT } from "./layout-contract";
+
+/** What the head renders for web fonts, decided off the site's list. */
+export interface FontSelection {
+  /** Families to render a `<Font>` for, in order, deduped. */
+  families: string[];
+  /** Whether the families are the site's own list rather than the fallback. */
+  named: boolean;
+  /** Families the site named that no font config declared. */
+  undeclared: string[];
+}
+
+/**
+ * The families the head renders, and whether to preload them.
+ *
+ * `isDeclared` is the authority, not the catalog: Astro's `<Font>` THROWS
+ * (`FontFamilyNotFound`) on a CSS variable no family registered, so a repo
+ * whose astro.config never got the site's list would render an error page
+ * rather than a missing face. Filtering through what Astro actually resolved
+ * makes that structurally impossible, and it also lets a diverged repo declare
+ * a family of its own and have it render.
+ *
+ * A site that names nothing falls back to the default set: a repo's globals.css
+ * is written against the CSS variables, so a stylesheet already saying
+ * `var(--font-fraunces)` would otherwise get the system stack, silently. The
+ * fallback is reported through `named`, because a page that has not said which
+ * families it uses must not spend a preload on each of eleven guesses.
+ */
+export function selectFontFamilies(
+  fonts: readonly string[] | undefined,
+  isDeclared: (cssVariable: string) => boolean,
+): FontSelection {
+  const wanted = [...new Set(fonts ?? [])];
+  const declared = wanted.filter((family) =>
+    isDeclared(fontCssVariable(family)),
+  );
+  const undeclared = wanted.filter((family) => !declared.includes(family));
+  if (declared.length > 0) {
+    return { families: declared, named: true, undeclared };
+  }
+  return {
+    families: DEFAULT_FONT_FAMILIES.filter((family) =>
+      isDeclared(fontCssVariable(family)),
+    ),
+    named: false,
+    undeclared,
+  };
+}

package/src/lib/markdown.ts

@@ -1,4 +1,5 @@
 import { micromark } from "micromark";
+import { gfm, gfmHtml } from "micromark-extension-gfm";
 
 // The one compiler for {type:"markdown"} content values (content-values.ts).
 // Runs at build time inside Astro's static render, so the browser ships HTML,
@@ -8,10 +9,18 @@ import { micromark } from "micromark";
 // tags up front, and this default is the backstop for anything that predates
 // or evades the schema. Do not pass allowDangerousHtml here, ever.
 //
+// GFM is on because the dashboard's body toolbar emits it: tables and task
+// lists are buttons a customer can press, and CommonMark alone would render
+// what they wrote as pipe soup. It adds syntax only; the escaping contract
+// above is untouched, and gfmHtml writes task checkboxes disabled.
+//
 // Headings: a markdown body renders inside a section, below the page's own
 // h1, so authors start at `##`. The compiler does not rewrite heading levels;
 // a body that opens with `#` is an authoring error the review pass catches,
 // not something to silently demote.
 export function renderMarkdown(value: string): string {
-  return micromark(value);
+  return micromark(value, {
+    extensions: [gfm()],
+    htmlExtensions: [gfmHtml()],
+  });
 }