blume 1.4.2 → 1.4.3

package/src/eval/agents.ts

@@ -1,6 +1,6 @@
-import { spawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 
+import spawn from "cross-spawn";
 import { join } from "pathe";
 import { z } from "zod";
 
@@ -48,7 +48,6 @@ export interface HeadlessResult {
 
 export interface HeadlessOptions {
   cwd: string;
-  platform?: NodeJS.Platform;
   prompt: string;
   timeoutMs: number;
 }
@@ -58,6 +57,15 @@ export interface HeadlessOptions {
  * cmd.exe newline quoting alike), stdout and stderr captured, SIGTERM at the
  * deadline with a SIGKILL follow-up. Resolves with the captured result;
  * rejects only when the executable cannot be spawned at all (ENOENT).
+ *
+ * Spawned through cross-spawn, which runs npm's `.cmd` shims on Windows with
+ * its own cmd.exe escaping — under the old `shell: true` launch, cmd.exe was
+ * free to mangle the JSON carried by codex's `-c` arguments, and a missing
+ * executable surfaced as exit code 9009 instead of an ENOENT rejection.
+ * execa was evaluated and rejected here: it waits for the stdio streams to
+ * close, and the `exit`-beats-`close` resolution below exists precisely
+ * because a killed agent's own children (an MCP server, a shell) hold the
+ * pipes open past the SIGTERM.
  */
 export const runAgentHeadless = (
   bin: string,
@@ -66,23 +74,18 @@ export const runAgentHeadless = (
 ): Promise<HeadlessResult> =>
   // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
   new Promise((resolve, reject) => {
-    const platform = options.platform ?? process.platform;
-    // npm installs agent CLIs as `.cmd` shims on Windows, which Node refuses
-    // to spawn without a shell. Arguments are plain flags and absolute paths,
-    // so shell interpolation has nothing to mangle.
     const child = spawn(bin, args, {
       cwd: options.cwd,
-      shell: platform === "win32",
       stdio: ["pipe", "pipe", "pipe"],
     });
 
     let stdout = "";
     let stderr = "";
     let timedOut = false;
-    child.stdout.on("data", (chunk: Buffer) => {
+    child.stdout?.on("data", (chunk: Buffer) => {
       stdout += chunk.toString("utf-8");
     });
-    child.stderr.on("data", (chunk: Buffer) => {
+    child.stderr?.on("data", (chunk: Buffer) => {
       stderr += chunk.toString("utf-8");
     });
 
@@ -112,7 +115,7 @@ export const runAgentHeadless = (
       }
     });
 
-    child.stdin.end(options.prompt);
+    child.stdin?.end(options.prompt);
   });
 
 /** The spawn signature `runEval` accepts, injectable for tests. */

package/src/eval/report.ts

@@ -6,6 +6,7 @@ import type { ColorFunction } from "consola/utils";
 import { join, relative } from "pathe";
 
 import { AGENTS } from "../audit/agent.ts";
+import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
@@ -26,20 +27,6 @@ const STATUS_COLOR: Record<QuestionStatus, ColorFunction> = {
 /** Longest id gets the room; everything shorter aligns to it. */
 const ID_PAD = 28;
 
-const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
-
-const money = (cost: number | undefined): string =>
-  cost === undefined ? "" : `$${cost.toFixed(2)}`;
-
-const duration = (ms: number): string => {
-  if (ms < 60_000) {
-    return seconds(ms);
-  }
-  const minutes = Math.floor(ms / 60_000);
-  const rest = Math.round((ms % 60_000) / 1000);
-  return `${minutes}m ${rest}s`;
-};
-
 /** One question's progress/report line: glyph, id, status, score, time, cost. */
 export const questionLine = (result: QuestionResult): string => {
   const color = STATUS_COLOR[result.status];

package/src/markdown/package-commands.ts

@@ -1,8 +1,26 @@
+import type { Agent, Command } from "package-manager-detector";
+import { resolveCommand } from "package-manager-detector/commands";
+
 /** Supported package managers, in the order tabs are displayed. */
 export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
 
 export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 
+/**
+ * The agent each tab renders. The yarn tab is pinned to Berry (yarn 2+ — the
+ * only supported line): the pre-existing mix emitted Berry-only `yarn dlx` and
+ * `--immutable` next to Classic-only `yarn global add`, so no single yarn
+ * version could run every rendered command. Berry removed `global`
+ * (yarnpkg/berry#821), so global installs on the yarn tab honestly render
+ * npm's form, matching `ni`'s table.
+ */
+const AGENT_FOR: Record<PackageManager, Agent> = {
+  bun: "bun",
+  npm: "npm",
+  pnpm: "pnpm",
+  yarn: "yarn@berry",
+};
+
 /** Words that mark the input as an explicit command rather than a bare list. */
 const MANAGER_PREFIXES = new Set(["bun", "bunx", "npm", "npx", "pnpm", "yarn"]);
 
@@ -118,62 +136,51 @@ const parseIntent = (input: string): Intent => {
   return { args: normalizeFlags(verbArgs), operation };
 };
 
-/** Render one manager's command for the given intent. */
+/** The package-manager-detector command for each non-global operation. */
+const COMMAND_FOR: Record<Exclude<Operation, "create">, Command> = {
+  add: "add",
+  ci: "frozen",
+  exec: "execute",
+  install: "install",
+  remove: "uninstall",
+  run: "run",
+};
+
+/**
+ * Render one manager's command for the given intent, via
+ * package-manager-detector's maintained agent tables (the engine behind `ni`).
+ */
 const buildCommand = (manager: PackageManager, intent: Intent): string => {
-  const args = intent.args.join(" ");
-  switch (intent.operation) {
-    case "add": {
-      if (manager === "npm") {
-        return `npm install ${args}`;
-      }
-      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
-        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
-        return `yarn global add ${pkgs}`;
-      }
-      return `${manager} add ${args}`;
-    }
-    case "create": {
-      return `${manager} create ${args}`;
-    }
-    case "exec": {
-      if (manager === "npm") {
-        return `npx ${args}`;
-      }
-      if (manager === "bun") {
-        return `bunx ${args}`;
-      }
-      return `${manager} dlx ${args}`;
-    }
-    case "ci": {
-      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere. Yarn
-      // Berry's flag is `--immutable` (`--frozen-lockfile` was removed in
-      // Yarn 4), matching the Berry-only `yarn dlx` the `exec` case emits.
-      if (manager === "npm") {
-        return "npm ci";
-      }
-      if (manager === "yarn") {
-        return "yarn install --immutable";
-      }
-      return `${manager} install --frozen-lockfile`;
-    }
-    case "remove": {
-      if (manager === "npm") {
-        return `npm uninstall ${args}`;
-      }
-      // Yarn Classic has no `remove -g`; the global form is `yarn global remove`.
-      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
-        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
-        return `yarn global remove ${pkgs}`;
-      }
-      return `${manager} remove ${args}`;
-    }
-    case "run": {
-      return `${manager} run ${args}`;
-    }
-    default: {
-      return `${manager} install`;
-    }
+  // The tables carry no `create`; every manager spells it the same way.
+  if (intent.operation === "create") {
+    return `${manager} create ${intent.args.join(" ")}`;
+  }
+  // A `-g`/`--global` flag selects the dedicated global command (the tables
+  // place the flag themselves, per manager).
+  const global =
+    (intent.operation === "add" || intent.operation === "remove") &&
+    intent.args.some((arg) => GLOBAL_FLAGS.has(arg));
+  const args = global
+    ? intent.args.filter((arg) => !GLOBAL_FLAGS.has(arg))
+    : intent.args;
+  const command: Command = global
+    ? (intent.operation === "add" && "global") || "global_uninstall"
+    : COMMAND_FOR[intent.operation];
+  // Non-null: every operation above maps to a command each supported agent's
+  // table defines (null is only possible for gaps like npm's
+  // upgrade-interactive, which no Operation reaches).
+  const resolved = resolveCommand(AGENT_FOR[manager], command, args);
+  const words = resolved
+    ? [resolved.command, ...resolved.args]
+    : [manager, ...args];
+  // Docs favor the explicit spellings over the tables' terse aliases.
+  if (words[1] === "i") {
+    words[1] = "install";
+  }
+  if (words[0] === "bun" && words[1] === "x") {
+    words.splice(0, 2, "bunx");
   }
+  return words.join(" ");
 };
 
 /**

package/src/og/card.ts

@@ -1,10 +1,12 @@
 import { readFile } from "node:fs/promises";
 
+import { imageSize } from "image-size";
 import { render } from "takumi-js";
 import type { RenderOptions } from "takumi-js";
 import { container, googleFonts, image, text } from "takumi-js/helpers";
 import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
+import { ACCENTS } from "../theme/palette.ts";
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
 /** A local font file registered with the OG card renderer, read at build. */
@@ -54,23 +56,15 @@ export interface OgFontFamilies {
   title?: string;
 }
 
-const ACCENT_HEX: Record<string, string> = {
-  blue: "#3b82f6",
-  green: "#22c55e",
-  orange: "#f97316",
-  pink: "#ec4899",
-  purple: "#8b5cf6",
-  red: "#ef4444",
-  teal: "#14b8a6",
-};
-
-// Named presets map to Blume's palette hex (the preset "blue" is not CSS
-// blue); anything else is handed to Takumi as-is — it parses the full CSS
-// color grammar, and a genuinely malformed value fails the build with a
-// parse error naming it. `hasOwn` keeps a preset name like "constructor"
-// from resolving up the prototype chain.
+// Named presets resolve from the theme's own OKLCH table — Takumi parses the
+// full CSS color grammar, so the card renders exactly the accent the site
+// shows (a separate hand-synced hex palette used to drift: the card's "blue"
+// was Tailwind's, not Blume's). Anything else is handed to Takumi as-is, and
+// a genuinely malformed value fails the build with a parse error naming it.
+// `hasOwn` keeps a preset name like "constructor" from resolving up the
+// prototype chain.
 const resolveAccent = (accent: string): string =>
-  Object.hasOwn(ACCENT_HEX, accent) ? (ACCENT_HEX[accent] as string) : accent;
+  Object.hasOwn(ACCENTS, accent) ? (ACCENTS[accent] as string) : accent;
 
 export interface OgCardPalette {
   accent?: string;
@@ -219,17 +213,21 @@ export const truncate = (value: string, max: number): string => {
 // at full height — it stands alone as the brand (no text label beside it).
 const MARK_HEIGHT = 32;
 const MARK_MAX_WIDTH = 240;
-// Accept either quote style and a non-zero min-x/min-y; only width/height
-// matter for the aspect ratio. A miss falls back to a square mark.
-const VIEW_BOX =
-  /viewBox=(?<q>["'])[\d.-]+[\s,]+[\d.-]+[\s,]+(?<w>[\d.]+)[\s,]+(?<h>[\d.]+)\k<q>/u;
-
-/** The SVG's viewBox aspect ratio (w/h), or null without a usable viewBox. */
+/**
+ * The SVG's aspect ratio (w/h), or null when no usable dimensions exist (the
+ * caller falls back to a square mark). image-size (already a dependency)
+ * reads explicit width/height and falls back to the viewBox, tolerating the
+ * quote/whitespace/attribute spellings the old regex silently missed —
+ * `viewBox = "…"`, newline-separated values — which shipped visibly-squashed
+ * marks instead of failing loudly.
+ */
 const logoAspect = (svg: string): number | null => {
-  const box = svg.match(VIEW_BOX);
-  const w = Number(box?.groups?.w);
-  const h = Number(box?.groups?.h);
-  return w && h ? w / h : null;
+  try {
+    const { height, width } = imageSize(Buffer.from(svg));
+    return width && height ? width / height : null;
+  } catch {
+    return null;
+  }
 };
 
 // Render the configured logo as the brand mark. A `currentColor` logo carries

package/src/openapi/model.ts

@@ -4,6 +4,13 @@ import type {
   PathItemObject,
 } from "@scalar/openapi-types/3.1";
 
+import { slugify } from "./references.ts";
+
+// The slug rules live with the reference resolver so operation routes and
+// reference-source tokens can never drift apart; re-exported for existing
+// importers.
+export { slugify } from "./references.ts";
+
 /**
  * Blume's own OpenAPI model. Specs are parsed and upgraded to 3.1 (see
  * `parse.ts`) with internal `$ref`s left intact — the document stays
@@ -16,13 +23,6 @@ import type {
 /** A normalized OpenAPI 3.1 document, internal `$ref`s intact. */
 export type ApiDocument = Document;
 
-const NON_SLUG = /[^a-z0-9]+/gu;
-const SLUG_EDGES = /^-+|-+$/gu;
-
-/** Lowercase, URL-safe slug: `Add a Pet!` -> `add-a-pet`. */
-export const slugify = (text: string): string =>
-  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
-
 /** The HTTP methods an OpenAPI path item may declare, in spec order. */
 export const HTTP_METHODS = [
   "get",
@@ -103,8 +103,8 @@ const isOperation = (value: unknown): value is OperationObject =>
 
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
- * different names onto one value — any two all-non-ASCII tags (`ペット`,
- * `注文`) both fall through to the `operations` fallback — and a shared slug
+ * different names onto one value — any two punctuation-only tags (`!!!`,
+ * `???`) both fall through to the `operations` fallback — and a shared slug
  * silently merges the tags' routes, sidebar groups, and overview sections.
  * Collisions gain `-2`, `-3`, … in first-seen order.
  */

package/src/openapi/parse.ts

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import { normalize, upgrade } from "@scalar/openapi-parser";
+import pRetry, { AbortError } from "p-retry";
 import { isAbsolute, join } from "pathe";
 
 import { hashText } from "../core/sources/cache.ts";
@@ -95,13 +96,23 @@ const ensureProxyDispatcher = async (): Promise<void> => {
   }
 };
 
-/** `Retry-After` in ms when the server sent a sane one, else undefined. */
+/**
+ * `Retry-After` in ms when the server sent a sane one, else undefined. RFC
+ * 9110 allows both forms: delta-seconds (`120`) and an HTTP-date (`Wed, 21
+ * Oct 2015 07:28:00 GMT`); the date form arrives from CDN rate limiters and
+ * was previously ignored.
+ */
 const retryAfterMs = (response: Response): number | undefined => {
   const header = response.headers.get("retry-after");
-  const seconds = header ? Number(header) : Number.NaN;
-  return Number.isFinite(seconds) && seconds > 0
-    ? seconds * SECOND_MS
-    : undefined;
+  if (!header) {
+    return undefined;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) {
+    return seconds > 0 ? seconds * SECOND_MS : undefined;
+  }
+  const delta = Date.parse(header) - Date.now();
+  return Number.isFinite(delta) && delta > 0 ? delta : undefined;
 };
 
 /** One fetch attempt, normalized: the body text, or a (maybe-retryable) error. */
@@ -137,33 +148,63 @@ const attemptFetch = async (spec: string): Promise<Attempt> => {
   }
 };
 
+/**
+ * A retryable failure, wrapped in a plain Error p-retry never special-cases:
+ * it refuses to retry a non-network `TypeError`, and the underlying error's
+ * type is the server's choice, not ours. The message is the underlying
+ * error's, so the exhaustion throw still reads `spec -> 503 Service
+ * Unavailable`.
+ */
+type RetryableFetchError = Error & { retryAfter?: number };
+
+const retryableFetchError = (
+  error: Error,
+  retryAfter?: number
+): RetryableFetchError => {
+  const wrapper: RetryableFetchError = new Error(error.message, {
+    cause: error,
+  });
+  wrapper.name = "RetryableFetchError";
+  wrapper.retryAfter = retryAfter;
+  return wrapper;
+};
+
 /** Fetch a remote spec's text, retrying transient failures with backoff. */
 const fetchSpecText = async (spec: string): Promise<string> => {
   await ensureProxyDispatcher();
-  let last: Attempt = {
-    error: new Error(`Could not fetch ${spec}`),
-    retryable: false,
-  };
-  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-    // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
-    last = await attemptFetch(spec);
-    if ("text" in last) {
-      return last.text;
-    }
-    if (!last.retryable) {
-      break;
-    }
-    if (attempt < MAX_ATTEMPTS - 1) {
-      // oxlint-disable-next-line no-await-in-loop -- back off before retrying
-      await sleep(
-        Math.min(
-          last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
-          MAX_RETRY_WAIT_MS
-        )
-      );
+  return await pRetry(
+    async () => {
+      const attempt = await attemptFetch(spec);
+      if ("text" in attempt) {
+        return attempt.text;
+      }
+      if (!attempt.retryable) {
+        // AbortError stops retrying and rethrows the original untouched.
+        throw new AbortError(attempt.error);
+      }
+      throw retryableFetchError(attempt.error, attempt.retryAfter);
+    },
+    {
+      factor: 2,
+      maxTimeout: MAX_RETRY_WAIT_MS,
+      minTimeout: BASE_BACKOFF_MS,
+      // A sane `Retry-After` replaces the exponential backoff rather than
+      // stacking on it: p-retry's own (capped) delay still runs after this
+      // hook, so only the difference is slept here.
+      onFailedAttempt: async (context) => {
+        const { retryAfter } = context.error as RetryableFetchError;
+        if (retryAfter !== undefined && context.retriesLeft > 0) {
+          await sleep(
+            Math.max(
+              0,
+              Math.min(retryAfter, MAX_RETRY_WAIT_MS) - context.retryDelay
+            )
+          );
+        }
+      },
+      retries: MAX_ATTEMPTS - 1,
     }
-  }
-  throw last.error;
+  );
 };
 
 const cacheFileFor = (cacheDir: string, spec: string): string =>

package/src/openapi/references.ts

@@ -1,6 +1,10 @@
-import { withBasePath } from "../core/base-path.ts";
+import { normalizeRoute, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import { trimChar, trimEnd } from "../core/trim.ts";
+import { trimChar } from "../core/trim.ts";
+
+// Re-exported from its home next to the other path helpers; `core/schema.ts`
+// and downstream consumers historically imported it from here.
+export { normalizeRoute } from "../core/base-path.ts";
 
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
@@ -62,18 +66,37 @@ export interface ReferenceSource {
   collisions?: string[];
 }
 
-const NON_SLUG = /[^a-z0-9]+/gu;
+// Keep Unicode letters/marks/numbers so diacritics stay in the slug (ASCII-only
+// stripping turned `Größe` into `gr-e`, which the nav humanizer rendered as
+// `Gr E`); `\p{M}` keeps combining marks attached to their base letter, which
+// NFC cannot always compose away (Devanagari vowel signs, Turkish `İ`'s
+// lowercased combining dot).
+const NON_SLUG = /[^\p{L}\p{M}\p{N}]+/gu;
+// Format characters (ZWNJ, ZWJ, bidi controls) separate no words — hyphenating
+// them would split Persian/Indic compounds the way ASCII stripping split
+// `Größe` — so they are dropped, not replaced.
+const FORMAT_CHARS = /\p{Cf}/gu;
+// A combining mark at the start of the slug has no base letter to attach to
+// (it would glue onto the preceding `/` in a URL), and a marks-only slug must
+// come out empty so callers' fallbacks (`operations`, `reference`) fire.
+const LEADING_MARKS = /^\p{M}+/u;
 
+/**
+ * Lowercase, hyphen-separated slug: `Add a Pet!` -> `add-a-pet`. Unicode
+ * letters are kept (`Größe` -> `größe`), NFC-normalized so canonically
+ * equivalent spellings (NFD input from macOS tooling) land on one slug.
+ * Non-ASCII slugs rely on the emitter percent-encoding the URL where a raw
+ * URI is required (sitemap, canonical).
+ */
 export const slugify = (text: string): string =>
-  trimChar(text.toLowerCase().replace(NON_SLUG, "-"), "-");
-
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-export const normalizeRoute = (route: string): string => {
-  const trimmed = route.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = trimEnd(withSlash, "/");
-  return noTrailing === "" ? "/" : noTrailing;
-};
+  trimChar(
+    text
+      .normalize("NFC")
+      .toLowerCase()
+      .replace(FORMAT_CHARS, "")
+      .replace(NON_SLUG, "-"),
+    "-"
+  ).replace(LEADING_MARKS, "");
 
 /** A stable per-reference token from its route: `/api/events` -> `api-events`. */
 const routeSlug = (route: string): string =>

package/src/openapi/render-mdx.ts

@@ -1,3 +1,7 @@
+import type { Nodes } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString as mdastToString } from "mdast-util-to-string";
+
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -27,16 +31,6 @@ const ENTITIES: Record<string, string> = {
 // SDK…" is common spec prose). Entity-escape the keyword's first letter so the
 // construct can't match; it still renders as the literal word.
 const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
-// Backtick code — inline spans and fences alike — is already literal in MDX,
-// and entities are NOT decoded inside it, so escaping there would render the
-// entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
-// backtick run covers `code`, ``code``, and ```fences``` in one shot. Both
-// runs are pinned by the backtick lookarounds: CommonMark pairs a span only
-// with an *equal-length* run, so without them a lone backtick would "close" on
-// the first backtick of a longer fence run — leaving `{` in the real prose
-// unescaped (a compile error) and escaping entities into the fence body.
-const BACKTICK_CODE = /(?<!`)(?<bt>`+)(?!`)[\s\S]*?(?<!`)\k<bt>(?!`)/gu;
-
 const escapeProse = (text: string): string =>
   text
     .replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char)
@@ -45,15 +39,57 @@ const escapeProse = (text: string): string =>
       (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`
     );
 
-/** Escape MDX-special syntax in prose while leaving backtick code verbatim. */
+/**
+ * The source offset ranges of code constructs — inline spans and fences —
+ * that MDX treats as literal (entities are NOT decoded inside them, so
+ * escaping there would render `/pets/&#123;petId&#125;` verbatim). The ranges
+ * come from a CommonMark parse rather than fence-emulating regexes: the
+ * parser is the authority on equal-length backtick pairing, longer tilde
+ * closers, unclosed fences running to EOF, and fences nested in blockquotes —
+ * each of which the replaced regexes had to re-derive (two with a recorded
+ * bug history in this file).
+ *
+ * One CommonMark construct is deliberately *not* masked: indented code. MDX
+ * disables indented code blocks, so a 4-space-indented sample is a paragraph
+ * whose braces genuinely need escaping; fence-or-backtick is told apart from
+ * indentation by the construct's first character.
+ */
+const codeSpans = (text: string): [number, number][] => {
+  const spans: [number, number][] = [];
+  const collect = (node: Nodes): void => {
+    if (node.type === "inlineCode" || node.type === "code") {
+      // fromMarkdown always stamps positions; -1 is an unreachable guard.
+      const start = node.position?.start.offset ?? -1;
+      const end = node.position?.end.offset ?? -1;
+      const head = text.slice(Math.max(start, 0), Math.max(end, 0)).trimStart();
+      if (
+        start >= 0 &&
+        (node.type === "inlineCode" ||
+          head.startsWith("`") ||
+          head.startsWith("~"))
+      ) {
+        spans.push([start, end]);
+      }
+      return;
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        collect(child);
+      }
+    }
+  };
+  collect(fromMarkdown(text));
+  return spans;
+};
+
+/** Escape MDX-special syntax in prose while leaving code verbatim. */
 const mdxSafe = (text: string): string => {
   let out = "";
   let cursor = 0;
-  for (const match of text.matchAll(BACKTICK_CODE)) {
-    const start = match.index ?? 0;
+  for (const [start, end] of codeSpans(text)) {
     out += escapeProse(text.slice(cursor, start));
-    out += match[0];
-    cursor = start + match[0].length;
+    out += text.slice(start, end);
+    cursor = end;
   }
   return out + escapeProse(text.slice(cursor));
 };
@@ -70,19 +106,22 @@ export interface RenderedPage {
 // `description`: the prose already renders in the body, and a `description`
 // frontmatter field would print it a second time as the page subtitle.
 const META_DESCRIPTION_MAX = 160;
-const PARAGRAPH_BREAK = /\n\s*\n/u;
-const MARKDOWN_LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
-const MARKDOWN_MARKS = /[*_`#>]/gu;
 const WHITESPACE = /\s+/gu;
 const TRAILING_WORD = /\s+\S*$/u;
 
-/** Flatten markdown prose to its first paragraph as single-line plain text. */
-const plainProse = (markdown: string): string =>
-  (markdown.trim().split(PARAGRAPH_BREAK).at(0) ?? "")
-    .replace(MARKDOWN_LINK, "$<text>")
-    .replace(MARKDOWN_MARKS, "")
-    .replace(WHITESPACE, " ")
-    .trim();
+/**
+ * Flatten markdown prose to its first paragraph as single-line plain text,
+ * via a real parse (`mdast-util-to-string`). The regex strip this replaces
+ * was lossy on literal prose — `snake_case` → `snakecase`, `C#` → `C` — and
+ * these strings ship as `seo.description` meta tags. A description with no
+ * paragraph (say, only a heading or list) falls back to its first block.
+ */
+const plainProse = (markdown: string): string => {
+  const tree = fromMarkdown(markdown);
+  const first =
+    tree.children.find((node) => node.type === "paragraph") ?? tree.children[0];
+  return first ? mdastToString(first).replace(WHITESPACE, " ").trim() : "";
+};
 
 /** Cap `text` at `max` characters, cutting on a word boundary. */
 const clip = (text: string, max: number): string => {