blume 1.6.4 → 1.6.6

package/src/components/layout/ReferenceLayout.astro

@@ -17,6 +17,7 @@ import {
   THEME_INIT_SCRIPT,
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
@@ -48,6 +49,7 @@ interface Props {
     key: string;
   } | null;
   analytics?: {
+    cloudflare?: { token: string };
     posthog?: { host?: string; key: string };
     scripts?: {
       attributes?: Record<string, string>;
@@ -65,9 +67,12 @@ interface Props {
   pageTitle: string;
   /** Keep the reference route out of crawler indexes. */
   noindex?: boolean;
-  /** Active locale code for `<html lang>` (defaults to `en`). */
+  /**
+   * Active locale code for `<html lang>`. Defaults to the locale Astro
+   * resolved from the URL (`Astro.currentLocale`), then the site default.
+   */
   locale?: string;
-  /** Text direction for `<html dir>` (defaults to `ltr`). */
+  /** Text direction for `<html dir>`; defaults to the locale's configured direction. */
   dir?: "ltr" | "rtl";
   /** Resolved UI dictionary; English baseline when omitted. */
   ui?: UIStrings;
@@ -87,11 +92,17 @@ const {
   searchEnabled,
   pageTitle,
   noindex = false,
-  locale = "en",
-  dir = "ltr",
+  locale: localeProp,
+  dir: dirProp,
   ui,
 } = Astro.props;
 
+// The locale and direction: the page's own values when it passes them (the
+// content catch-all always does), else what Astro's i18n routing resolved for
+// this URL, else the site default (see `page-locale.ts`).
+const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
+const dir = dirProp ?? pageDirection(data.config.i18n, locale);
+
 const strings = ui ?? EN_UI;
 // Scope search to the reference page's language on a multi-locale site.
 const searchLocale = searchLocaleFor(data.config.i18n, locale);

package/src/components/layout/RootLayout.astro

@@ -58,6 +58,7 @@ import {
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
+import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 import PageActions from "./PageActions.astro";
 import PageFeedback from "./PageFeedback.astro";
@@ -84,6 +85,7 @@ interface Props {
     key: string;
   } | null;
   analytics?: {
+    cloudflare?: { token: string };
     posthog?: { host?: string; key: string };
     scripts?: {
       attributes?: Record<string, string>;
@@ -148,9 +150,12 @@ interface Props {
   lastModified?: string | null;
   noindex?: boolean;
   structuredDataEnabled?: boolean;
-  /** Active locale code for `<html lang>` (defaults to `en`). */
+  /**
+   * Active locale code for `<html lang>`. Defaults to the locale Astro
+   * resolved from the URL (`Astro.currentLocale`), then the site default.
+   */
   locale?: string;
-  /** Text direction for `<html dir>` (defaults to `ltr`). */
+  /** Text direction for `<html dir>`; defaults to the locale's configured direction. */
   dir?: "ltr" | "rtl";
   /**
    * Direction of the page content's own language — differs from `dir` on a
@@ -241,8 +246,8 @@ const {
   lastModified,
   noindex,
   structuredDataEnabled,
-  locale = "en",
-  dir = "ltr",
+  locale: localeProp,
+  dir: dirProp,
   contentDir,
   ui,
   localeAlternates,
@@ -258,6 +263,12 @@ const {
   contentLayout = "default",
 } = Astro.props;
 
+// The locale and direction: the page's own values when it passes them (the
+// content catch-all always does), else what Astro's i18n routing resolved for
+// this URL, else the site default (see `page-locale.ts`).
+const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
+const dir = dirProp ?? pageDirection(data.config.i18n, locale);
+
 // Serialized once for island hooks; `<` escaped so content can't break the tag.
 const clientDataJson = clientData
   ? JSON.stringify(clientData).replaceAll("<", "\\u003c")

package/src/components/layout/analytics-client.ts

@@ -1,7 +1,8 @@
 /**
  * Send a custom analytics event to every analytics platform configured in
  * `blume.config.ts`. Mirrors the providers wired by `Analytics.astro`: Vercel
- * Web Analytics and PostHog are first-class; any other provider added through
+ * Web Analytics and PostHog are first-class (Cloudflare Web Analytics is too,
+ * but has no custom-event API to forward to); any other provider added through
  * `analytics.scripts` is reached via best-effort global detection or the
  * `blume:track` CustomEvent, which fires unconditionally so a project can bridge
  * the event to anything. Every call no-ops cleanly when a provider isn't present

package/src/components/layout/page-locale.ts

@@ -0,0 +1,29 @@
+/**
+ * Locale defaults for the document shells (`RootLayout`, `PageLayout`,
+ * `ReferenceLayout`) when the page doesn't pass `locale`/`dir` itself.
+ *
+ * The content catch-all always passes both, resolved from the route manifest
+ * (which also knows about fallback pages). Custom `.astro` pages, the 404
+ * page, and the reference shell don't have that data, so they fall back to
+ * what Astro's own i18n routing resolved for the request — `Astro.currentLocale`
+ * — which the generated config enables with Blume's locale list. Before this,
+ * a custom page under `/fr/` rendered `<html lang="en">` unless it threaded
+ * the locale through by hand.
+ */
+
+/**
+ * The page's locale: the caller's explicit value, else the one Astro resolved
+ * from the URL, else the site's default locale, else `en` (no i18n).
+ */
+export const pageLocale = (
+  i18n: { defaultLocale: string } | null,
+  explicit?: string,
+  current?: string
+): string => explicit ?? current ?? i18n?.defaultLocale ?? "en";
+
+/** The configured text direction of a locale; `ltr` when unknown. */
+export const pageDirection = (
+  i18n: { locales: { code: string; dir: "ltr" | "rtl" }[] } | null,
+  locale: string
+): "ltr" | "rtl" =>
+  i18n?.locales.find((entry) => entry.code === locale)?.dir ?? "ltr";

package/src/components/openapi/AsyncApiOperation.astro

@@ -23,6 +23,7 @@ import { asyncSampleLanguages } from "./async-snippets.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import { buildMessage, defaultMessageValues } from "./message.ts";
 import { messageModel } from "./message-model.ts";
+import Description from "./Description.astro";
 import MessageComposer from "./MessageComposer.astro";
 import Authorization from "./Authorization.astro";
 import Bindings from "./Bindings.astro";
@@ -156,9 +157,10 @@ const channelBindings = bindingGroups(channel?.bindings);
                     : "Message"}
                 </div>
                 {named.message.description && (
-                  <p class="mb-2 text-muted-foreground text-sm">
-                    {named.message.description}
-                  </p>
+                  <Description
+                    class="mb-2 text-muted-foreground text-sm"
+                    text={named.message.description}
+                  />
                 )}
                 {named.message.contentType && (
                   <div class="mb-2 text-muted-foreground text-xs">

package/src/components/openapi/Authorization.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import {
   type OperationSecurity,
   schemeCarrier,
@@ -38,7 +39,7 @@ const { security } = Astro.props;
             {alternative.map((resolved) => {
               const carrier = schemeCarrier(resolved);
               return (
-                <div class="border-border border-t py-3 first:border-t-0">
+                <div class="border-border border-t py-4 first:border-t-0">
                   <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
                     <code class="font-mono text-foreground text-sm">
                       {carrier?.name ?? resolved.key}
@@ -54,13 +55,10 @@ const { security } = Astro.props;
                     )}
                   </div>
                   {resolved.scheme?.description && (
-                    <div
-                      class="mt-1 text-muted-foreground text-sm"
-                      set:text={resolved.scheme.description}
-                    />
+                    <Description class="mt-2 text-muted-foreground text-sm" text={resolved.scheme.description} />
                   )}
                   {resolved.scopes.length > 0 && (
-                    <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+                    <div class="mt-2 flex flex-wrap items-center gap-1.5 text-xs">
                       <span class="text-muted-foreground">Scopes:</span>
                       {resolved.scopes.map((scope) => (
                         <code class="rounded bg-muted px-1 py-0.5 text-foreground">

package/src/components/openapi/Bindings.astro

@@ -54,13 +54,13 @@ const isSchemaish = (value: unknown): value is SchemaLike => {
       </div>
       {groups.map((group) => (
         <div class="not-prose mb-3 rounded-blume border border-border px-4 last:mb-0">
-          <div class="flex items-baseline gap-2 border-border py-3">
+          <div class="flex items-baseline gap-2 border-border py-4">
             <code class="font-mono font-semibold text-foreground text-sm">
               {group.protocol}
             </code>
           </div>
           {group.rows.map((row) => (
-            <div class="border-border border-t py-3">
+            <div class="border-border border-t py-4">
               <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
                 <code class="font-mono text-foreground text-sm">{row.name}</code>
                 {!isSchemaish(row.value) && (

package/src/components/openapi/Description.astro

@@ -0,0 +1,109 @@
+---
+import { descriptionHtml } from "./description.ts";
+
+/**
+ * A spec description, rendered as Markdown.
+ *
+ * One component rather than the same three lines in six places, and that is not only tidiness:
+ * the styling below is emitted ONCE per page here, where writing it as utility classes on each
+ * element repeated it per description instead. On the largest reference page that is 2,400
+ * descriptions — the first attempt at this put 1.5 MB of identical class attributes into a single
+ * HTML document and pushed eight pages past Googlebot's 2 MB crawl limit, which `blume audit`
+ * caught. A class name and one stylesheet cost the same at one description as at two thousand.
+ */
+interface Props {
+  /** Extra classes for the wrapper — position and base type come from the caller. */
+  class?: string;
+  text?: string;
+}
+
+const { class: className = "", text } = Astro.props;
+const html = descriptionHtml(text);
+---
+
+{html && <div class:list={["blume-api-description", className]} set:html={html} />}
+
+<style is:global>
+  /* Plain CSS on a single class, not the typography plugin's `prose`. `prose` sets its own font
+     size, colour and rhythm, all of which fight the muted small type these sit in — a property
+     description would come out larger and darker than the property name above it. Only what
+     Markdown needs is styled; everything else inherits, so a description still reads as
+     annotation rather than as body copy. */
+  .blume-api-description > :first-child {
+    margin-top: 0;
+  }
+
+  .blume-api-description > :last-child {
+    margin-bottom: 0;
+  }
+
+  .blume-api-description p,
+  .blume-api-description ol,
+  .blume-api-description ul,
+  .blume-api-description pre {
+    margin-block: 0.5rem;
+  }
+
+  .blume-api-description ol {
+    list-style: decimal;
+    padding-inline-start: 1.25rem;
+  }
+
+  .blume-api-description ul {
+    list-style: disc;
+    padding-inline-start: 1.25rem;
+  }
+
+  .blume-api-description li {
+    margin-block: 0.25rem;
+  }
+
+  /* A heading in a description is a label for the paragraph under it, not a section of the
+     page: it keeps the description's own size and only gains the weight and colour of a label.
+     Without this it inherits the reset's unstyled heading and is indistinguishable from text. */
+  .blume-api-description :is(h1, h2, h3, h4, h5, h6) {
+    color: var(--color-foreground);
+    font-weight: 600;
+    margin-block: 0.5rem;
+  }
+
+  .blume-api-description strong {
+    color: var(--color-foreground);
+    font-weight: 600;
+  }
+
+  .blume-api-description a {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  /* Matched to the chip the reference already draws for an enum value, so an `apiKey` in prose
+     looks like the `apiKey` in the chips beside it. */
+  .blume-api-description code {
+    background: var(--color-muted);
+    border-radius: 0.25rem;
+    color: var(--color-foreground);
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    padding: 0.125rem 0.25rem;
+  }
+
+  .blume-api-description pre {
+    background: var(--color-muted);
+    border-radius: 0.25rem;
+    overflow-x: auto;
+    padding: 0.5rem;
+  }
+
+  .blume-api-description pre code {
+    background: none;
+    padding: 0;
+  }
+
+  /* The scroll frame a table gets from `descriptionHtml` carries the body's own 1.5rem rhythm,
+     which is three times what everything else in a description sits at. Only the margin is
+     restated; the frame, the cell padding and the scrolling are the renderer's. */
+  .blume-api-description .blume-table-scroll {
+    margin-block: 0.5rem;
+  }
+</style>

package/src/components/openapi/GraphqlFieldsTable.astro

@@ -1,6 +1,7 @@
 ---
 import type { GraphqlFieldRow } from "./graphql-helpers.ts";
 import { isOutputField } from "./graphql-helpers.ts";
+import Description from "./Description.astro";
 import GraphqlChip from "./GraphqlChip.astro";
 
 /**
@@ -46,7 +47,7 @@ const isRequired = (row: GraphqlFieldRow): boolean =>
           const route = routes.get(row.type.name);
           const args = isOutputField(row) ? row.args : [];
           return (
-            <div class="border-border border-t py-3 first:border-t-0">
+            <div class="border-border border-t py-4 first:border-t-0">
               <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
                 <code class="font-mono text-foreground text-sm">
                   {row.name}
@@ -68,13 +69,10 @@ const isRequired = (row: GraphqlFieldRow): boolean =>
                 )}
               </div>
               {row.description && (
-                <div
-                  class="mt-1 text-muted-foreground text-sm"
-                  set:text={row.description}
-                />
+                <Description class="mt-2 text-muted-foreground text-sm" text={row.description} />
               )}
               {"default" in row && row.default !== undefined && (
-                <div class="mt-1 text-muted-foreground text-xs">
+                <div class="mt-2 text-muted-foreground text-xs">
                   Default:{" "}
                   <code class="rounded bg-muted px-1 py-0.5 text-foreground">
                     {row.default}
@@ -82,7 +80,7 @@ const isRequired = (row: GraphqlFieldRow): boolean =>
                 </div>
               )}
               {row.deprecationReason && (
-                <div class="mt-1 text-muted-foreground text-xs">
+                <div class="mt-2 text-muted-foreground text-xs">
                   Deprecated: <span set:text={row.deprecationReason} />
                 </div>
               )}

package/src/components/openapi/GraphqlOperation.astro

@@ -23,6 +23,7 @@ import {
 import { buildRequest, defaultValues } from "./request.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import { sampleLanguages } from "./snippets.ts";
+import Description from "./Description.astro";
 import GraphqlChip from "./GraphqlChip.astro";
 import GraphqlFieldsTable from "./GraphqlFieldsTable.astro";
 import GraphqlType from "./GraphqlType.astro";
@@ -154,9 +155,9 @@ const returnRoute = field ? routes.get(field.type.name) : undefined;
               />
             </div>
             {document.types[field.type.name]?.description && (
-              <p
-                class="mt-1 text-muted-foreground text-sm"
-                set:text={document.types[field.type.name]?.description}
+              <Description
+                class="mt-2 text-muted-foreground text-sm"
+                text={document.types[field.type.name]?.description}
               />
             )}
           </section>

package/src/components/openapi/GraphqlType.astro

@@ -7,6 +7,7 @@ import {
   graphqlRoutes,
   graphqlUsage,
 } from "./graphql-helpers.ts";
+import Description from "./Description.astro";
 import GraphqlChip from "./GraphqlChip.astro";
 import GraphqlFieldsTable from "./GraphqlFieldsTable.astro";
 import MethodBadge from "./MethodBadge.astro";
@@ -86,7 +87,7 @@ const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
           </div>
           <div class="rounded-blume border border-border px-4">
             {(type.enumValues ?? []).map((value) => (
-              <div class="border-border border-t py-3 first:border-t-0">
+              <div class="border-border border-t py-4 first:border-t-0">
                 <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
                   <code class="font-mono text-foreground text-sm">
                     {value.name}
@@ -98,13 +99,10 @@ const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
                   )}
                 </div>
                 {value.description && (
-                  <div
-                    class="mt-1 text-muted-foreground text-sm"
-                    set:text={value.description}
-                  />
+                  <Description class="mt-2 text-muted-foreground text-sm" text={value.description} />
                 )}
                 {value.deprecationReason && (
-                  <div class="mt-1 text-muted-foreground text-xs">
+                  <div class="mt-2 text-muted-foreground text-xs">
                     Deprecated: <span set:text={value.deprecationReason} />
                   </div>
                 )}

package/src/components/openapi/ParametersTable.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import {
   constraints,
   resolveSchema,
@@ -54,7 +55,7 @@ const groups = SECTIONS.map((section) => ({
           const limits = constraints(resolved);
           const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
           return (
-            <div class="border-border border-t py-3 first:border-t-0">
+            <div class="border-border border-t py-4 first:border-t-0">
               <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
                 <code class="font-mono text-foreground text-sm">{param.name}</code>
                 <span class="text-muted-foreground text-xs">{type}</span>
@@ -70,18 +71,15 @@ const groups = SECTIONS.map((section) => ({
                 )}
               </div>
               {param.description && (
-                <div
-                  class="mt-1 text-muted-foreground text-sm"
-                  set:text={param.description}
-                />
+                <Description class="mt-2 text-muted-foreground text-sm" text={param.description} />
               )}
               {limits.length > 0 && (
-                <div class="mt-1 text-muted-foreground text-xs">
+                <div class="mt-2 text-muted-foreground text-xs">
                   {limits.join(" · ")}
                 </div>
               )}
               {enumValues && (
-                <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+                <div class="mt-2 flex flex-wrap items-center gap-1.5 text-xs">
                   <span class="text-muted-foreground">Allowed:</span>
                   {enumValues.map((value) => (
                     <code class="rounded bg-muted px-1 py-0.5 text-foreground">

package/src/components/openapi/RequestBody.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
 import SchemaTable from "./SchemaTable.astro";
 
@@ -46,10 +47,7 @@ const schema = chosen?.[1]?.schema ?? {};
   </div>
   {
     requestBody.description && (
-      <div
-        class="text-muted-foreground text-sm"
-        set:text={requestBody.description}
-      />
+      <Description class="text-muted-foreground text-sm" text={requestBody.description} />
     )
   }
   <div class="mt-3">

package/src/components/openapi/Responses.astro

@@ -1,5 +1,6 @@
 ---
 import { statusColor } from "../colors.ts";
+import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
 import SchemaTable from "./SchemaTable.astro";
 
@@ -52,9 +53,9 @@ const items = Object.entries(responses);
                   {status}
                 </span>
                 {response.description && (
-                  <span
-                    class="text-muted-foreground text-sm"
-                    set:text={response.description}
+                  <Description
+                    class="min-w-0 text-muted-foreground text-sm"
+                    text={response.description}
                   />
                 )}
               </div>

package/src/components/openapi/SchemaProperty.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import {
   constraints,
   isNullable,
@@ -54,7 +55,11 @@ const expandable =
   !circular && (hasObjectShape(resolved) || Boolean(items && hasObjectShape(items)));
 ---
 
-<div class="border-border border-t py-3 first:border-t-0 last:pb-0">
+{/* The row's vertical scale is 8 / 12 / 16px, and every other reference table copies it. A
+    description is a block of Markdown, not a line: at 4px it sat closer to the label above it
+    than its own paragraphs sat to each other, and the disclosure below it touched the next row's
+    divider. Each step separates a bigger unit than the one before. */}
+<div class="border-border border-t py-4 first:border-t-0 last:pb-0">
   <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
     <code class="font-mono text-foreground text-sm">{name}</code>
     <span class="text-muted-foreground text-xs"
@@ -77,17 +82,17 @@ const expandable =
   </div>
   {
     description && (
-      <div class="mt-1 text-muted-foreground text-sm" set:text={description} />
+      <Description class="mt-2 text-muted-foreground text-sm" text={description} />
     )
   }
   {
     limits.length > 0 && (
-      <div class="mt-1 text-muted-foreground text-xs">{limits.join(" · ")}</div>
+      <div class="mt-2 text-muted-foreground text-xs">{limits.join(" · ")}</div>
     )
   }
   {
     enumValues && (
-      <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+      <div class="mt-2 flex flex-wrap items-center gap-1.5 text-xs">
         <span class="text-muted-foreground">Allowed:</span>
         {enumValues.map((value) => (
           <code class="rounded bg-muted px-1 py-0.5 text-foreground">
@@ -99,12 +104,12 @@ const expandable =
   }
   {
     expandable && (
-      <details class="mt-2" open={expandAll}>
+      <details class="mt-3" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
           <span class="[details[open]>summary_&]:hidden">Show properties</span>
           <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
-        <div class="mt-2 border-border border-l pl-4">
+        <div class="mt-3 border-border border-l pl-4">
           <SchemaTable
             schema={schema}
             schemas={schemas}

package/src/components/openapi/description.ts

@@ -0,0 +1,91 @@
+import { Marked } from "marked";
+
+/**
+ * Render a spec description as Markdown.
+ *
+ * An OpenAPI `description` is Markdown by specification — "CommonMark syntax MAY be used for rich
+ * text representation" — but the reference components printed it with `set:text`, so a schema
+ * property, parameter or header showed its source. On a spec generated from code docstrings that
+ * is most of them: `**Inline**` printed its asterisks, `` `apiKey` `` printed its backticks, and
+ * because HTML collapses newlines every paragraph and list ran together into one wall of text.
+ * The operation description does not have this problem — it is emitted into the MDX body and goes
+ * through the full pipeline — which is what made the difference visible page by page.
+ *
+ * `marked` rather than the site's own Markdown pipeline: the pipeline is async, plugin-laden and
+ * built for whole documents, while these are thousands of short strings per build — a large
+ * reference renders tens of thousands of them. `marked` is synchronous, already a dependency,
+ * and already how the Ask AI island renders model Markdown.
+ */
+const TABLE = /<table>[\s\S]*?<\/table>/gu;
+
+/**
+ * An href the author can have meant: an absolute URL, a site-root path, a fragment or a mailto.
+ * A bare relative href in a spec description has never yet been a link, and the lookahead keeps
+ * `//host` out: that is a scheme-relative URL to another origin, not a site-root path.
+ */
+const DELIBERATE_HREF = /^(?:https?:|mailto:|#|\/(?!\/))/iu;
+
+/** The source text of a demoted construct, made safe for `set:html`. */
+const escapeHtml = (text: string): string =>
+  text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+
+const markdown = new Marked({
+  // `breaks` is deliberately NOT set, unlike the Ask AI island. Docstring prose is hard-wrapped at
+  // 72 or 79 columns, so honouring single newlines would break every sentence mid-flow at exactly
+  // the width the source file happened to use.
+  breaks: false,
+  gfm: true,
+  hooks: {
+    // GFM tables reach the page through `set:html`, so they miss the `blume:table-wrap` plugin
+    // that gives every table in the body its scroll frame — and a description sits in a column
+    // narrower than the body. Wrapping here reuses that frame rather than reinventing it; the
+    // regex is safe because a table cannot nest and this HTML is `marked`'s own output.
+    postprocess: (html: string) =>
+      html.replaceAll(
+        TABLE,
+        (table) => `<div class="blume-table-scroll" tabindex="0">${table}</div>`
+      ),
+  },
+  renderer: {
+    // Raw HTML is escaped rather than passed through. A description is data lifted out of a spec
+    // file, frequently generated upstream from source comments, and it is interpolated with
+    // `set:html`; the island that renders model output runs DOMPurify over it for the same
+    // reason, which needs a DOM and so is unavailable in a component that renders on the server.
+    html: ({ text }: { text: string }) => escapeHtml(text),
+    // An image is held to the same href policy as a link, for the same reason: `![x](src)` is the
+    // one Markdown construct that fetches a resource, and a `javascript:` or relative source in a
+    // description is notation rather than a picture.
+    image: ({ href, raw }: { href: string; raw: string }) =>
+      DELIBERATE_HREF.test(href) ? false : escapeHtml(raw),
+    // A link is emitted only when the author clearly meant one; anything else keeps its source
+    // text verbatim. Two failures drove this, and both are prose that was never Markdown.
+    //
+    // GFM autolinks a BARE url (`raw === href`), and a spec description is full of EXAMPLE hosts
+    // — `https://myorg.my.salesforce.com`, `https://yourstore.myshopify.com`. Each became an
+    // anchor pointing at a host that does not exist and was never meant to be visited.
+    //
+    // Worse, regex and format notation reads as link syntax. Debezium's own wording for a column
+    // list is `schemaName[.]tableName[.](columnName1|columnName2)`, in which `[.](columnName1|
+    // columnName2)` is EXACTLY `[text](href)` — 48 pages of one reference linked to a path made
+    // of that notation.
+    // Rendering the demoted case as `raw` rather than as `text` is what keeps that intact: the
+    // text alone is `.`, so emitting it would silently delete the rest of the notation.
+    //
+    // The test for "meant one" is the href (see `DELIBERATE_HREF`) plus the shape of the source:
+    // an author-written link starts with `[` (inline or reference style) or `<` (an angle
+    // autolink). A GFM bare autolink never does — `https://…`, `www.…` or an email — and
+    // comparing `raw` to `href` is not enough to catch it, because marked prefixes the missing
+    // `http://` or `mailto:` for the last two, so the two strings differ exactly as they would
+    // for a deliberate link.
+    link({ href, raw }: { href: string; raw: string }) {
+      const deliberate =
+        DELIBERATE_HREF.test(href) &&
+        (raw.startsWith("[") || raw.startsWith("<"));
+      return deliberate ? false : escapeHtml(raw);
+    },
+  },
+});
+
+/** `description` rendered to HTML, or an empty string when there is nothing to render. */
+export const descriptionHtml = (description: string | undefined): string =>
+  description?.trim() ? markdown.parse(description, { async: false }) : "";