blume 1.6.4 → 1.6.5

package/dist/types/core/config-input.d.ts

@@ -789,6 +789,16 @@ export interface AnalyticsScript {
 }
 /** Analytics providers. Configure one, several, or none. */
 export interface AnalyticsConfig {
+    /**
+     * Cloudflare Web Analytics, for a site Cloudflare doesn't proxy (manual
+     * setup). Not needed on a proxied zone with automatic RUM enabled — that
+     * injects the beacon at the edge, and configuring it here too would count
+     * every pageview twice.
+     */
+    cloudflare?: {
+        /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
+        token: string;
+    };
     /** PostHog product analytics. */
     posthog?: {
         /** API host (for self-hosted / EU). Defaults to PostHog cloud. */

package/dist/types/core/schema.d.ts

@@ -561,6 +561,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         webmcp: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     analytics: z.ZodOptional<z.ZodObject<{
+        cloudflare: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+        }, z.core.$strict>>;
         posthog: z.ZodOptional<z.ZodObject<{
             host: z.ZodOptional<z.ZodString>;
             key: z.ZodString;
@@ -733,10 +736,10 @@ export declare const blumeConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
     deployment: z.ZodPrefault<z.ZodObject<{
         adapter: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            cloudflare: "cloudflare";
             vercel: "vercel";
             node: "node";
             netlify: "netlify";
-            cloudflare: "cloudflare";
         }>>>;
         base: z.ZodOptional<z.ZodString>;
         output: z.ZodDefault<z.ZodEnum<{

package/docs/configuration/analytics.mdx

@@ -1,9 +1,9 @@
 ---
 title: Analytics
-description: First-party web analytics — Vercel Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
+description: First-party web analytics — Vercel Web Analytics, Cloudflare Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
 ---
 
-Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.
+Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics, Cloudflare Web Analytics, and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.
 
 Analytics loads in **production builds only**. The scripts are emitted by `blume build`, never by `blume dev`, so local traffic never reaches your dashboards and you don't need a separate "development" project.
 
@@ -23,6 +23,24 @@ analytics: {
 
 No keys are needed — the script reports to the project it's deployed under. This only collects data on Vercel deployments, where the `/_vercel/insights` endpoint exists.
 
+## Cloudflare Web Analytics
+
+[Cloudflare Web Analytics](https://developers.cloudflare.com/web-analytics/) has two setups, and only one of them needs config.
+
+**Proxied zone (automatic setup).** If Cloudflare serves your site — a Worker with a custom domain, Pages, or any zone with the orange cloud on — enable Web Analytics for the zone in the Cloudflare dashboard and stop there. Cloudflare injects the beacon at the edge, so leave `analytics.cloudflare` unset; configuring it as well would count every pageview twice.
+
+**Any other host (manual setup).** For a site Cloudflare doesn't proxy, add the site under Web Analytics in the dashboard, copy the token out of the JS snippet it gives you (the `token` inside `data-cf-beacon`), and pass it here. Blume renders the same beacon tag the snippet does.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  cloudflare: {
+    token: "0123456789abcdef0123456789abcdef",
+  },
+}
+```
+
+The token is safe to ship to the browser — it only identifies the site. The beacon tracks history changes on its own, so client-router navigations count without any extra wiring.
+
 ## PostHog
 
 Provide your **project API key** to add [PostHog](https://posthog.com). The host defaults to PostHog Cloud US; set `host` for EU Cloud (`https://eu.i.posthog.com`) or a self-hosted instance.
@@ -72,6 +90,7 @@ analytics: {
 | Option | Default | Description |
 | --- | --- | --- |
 | `vercel` | `false` | Add Vercel Web Analytics (Vercel deployments only). |
+| `cloudflare.token` | — | Cloudflare Web Analytics site token (manual setup). Enables the beacon when set. |
 | `posthog.key` | — | PostHog project API key. Enables PostHog when set. |
 | `posthog.host` | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted). |
 | `scripts[].src` | — | External script URL. Mutually exclusive with `content`. |

package/docs/content/syntax.mdx

@@ -384,7 +384,7 @@ flowchart LR
 ```
 ````
 
-Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
+Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. Diagrams use Mermaid's dagre layout and classic look by default; opt a single diagram into another layout or look through Mermaid front matter (a `config:` block with `layout: elk` or `look: neo`), and the ELK engine loads only for diagrams that ask for it. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
 
 ### Flowchart
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -74,12 +74,12 @@
     "@astrojs/vercel": "^11.0.10",
     "@asyncapi/converter": "^2.0.2",
     "@clack/prompts": "^1.8.0",
-    "@iconify-json/lucide": "^1.2.130",
+    "@iconify-json/lucide": "^1.2.131",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
-    "@pierre/diffs": "^1.4.1",
+    "@pierre/diffs": "^1.4.2",
     "@scalar/astro": "^0.4.18",
     "@scalar/openapi-parser": "^0.29.1",
     "@scalar/openapi-types": "^0.9.5",
@@ -89,7 +89,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^7.0.94",
+    "ai": "^7.0.99",
     "astro": "^7.3.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
@@ -114,7 +114,7 @@
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
-    "mermaid": "^11.17.2",
+    "mermaid": "^12.0.0",
     "micromark-extension-gfm": "^3.0.0",
     "nanotar": "^0.3.0",
     "node-html-parser": "^9.0.4",
@@ -127,8 +127,8 @@
     "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
     "picomatch": "^4.0.7",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "robots-parser": "^3.0.1",
     "satteri": "^0.10.5",
     "semver": "^7.8.5",
@@ -145,10 +145,10 @@
     "ufo": "^1.6.4",
     "undici": "^8.10.2",
     "write-file-atomic": "^8.0.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.2"
   },
   "devDependencies": {
-    "@ai-sdk/openai-compatible": "^3.0.45",
+    "@ai-sdk/openai-compatible": "^3.0.48",
     "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
@@ -156,14 +156,14 @@
     "@sanity/client": "^8.6.1",
     "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
-    "@types/node": "^22.20.1",
+    "@types/node": "^22.20.2",
     "@types/picomatch": "^4.0.3",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@types/semver": "^7.8.0",
     "@types/write-file-atomic": "^4.0.3",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "algoliasearch": "^5.57.0",
+    "algoliasearch": "^5.59.0",
     "bun-types": "^1.4.2",
     "flexsearch": "^0.8.212",
     "typesense": "^3.0.6"

package/src/astro/generate.ts

@@ -601,19 +601,18 @@ const islandFrameworkWarnings = (
  * rather than let the build die with an opaque ERR_MODULE_NOT_FOUND from the
  * hidden generated config. Availability mirrors the search-provider check: a
  * dep resolves from the project root or from the Blume package itself.
+ * `pkgDir` is injectable for testing.
  */
-const deploymentAdapterWarnings = (
+export const deploymentAdapterWarnings = (
   deployment: ResolvedConfig["deployment"],
-  root: string
+  root: string,
+  pkgDir: string = packageRoot()
 ): string[] => {
   const dep =
     deployment.output === "server" && deployment.adapter
       ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter)
       : undefined;
-  if (
-    dep &&
-    !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))
-  ) {
+  if (dep && !(canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep))) {
     return [
       `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
     ];

package/src/components/content/mermaid-element.ts

@@ -42,6 +42,14 @@ class BlumeMermaid extends HTMLElement {
       const token = this.#renderToken;
       const mermaid = await loadMermaid();
       mermaid.initialize({
+        // Mermaid 12 defaults to the bundled ELK layout and the "neo" look,
+        // which re-lays out and restyles every existing diagram and pulls a
+        // ~1.4 MB ELK chunk onto any page with a flowchart. Pin the previous
+        // defaults so diagrams keep rendering as authored; a diagram opts
+        // into ELK or neo through its own front matter (`config: { layout:
+        // elk }`), which outranks these initialize() values.
+        layout: "dagre",
+        look: "classic",
         securityLevel: "strict",
         startOnLoad: false,
         theme: prefersDark() ? "dark" : "default",

package/src/components/layout/Analytics.astro

@@ -3,7 +3,7 @@ import VercelAnalytics from "@vercel/analytics/astro";
 
 // Analytics scripts injected into <head>. PostHog and custom providers use the
 // inline-snippet house style (banner/theme/JSON-LD); Vercel uses its official
-// Astro component. Loads ONLY in production builds so `blume dev` stays clean
+// Astro component; Cloudflare is its beacon script tag. Loads ONLY in production builds so `blume dev` stays clean
 // and local traffic never reaches your analytics.
 interface AnalyticsScript {
   attributes?: Record<string, string>;
@@ -14,6 +14,7 @@ interface AnalyticsScript {
 
 interface Props {
   analytics?: {
+    cloudflare?: { token: string };
     posthog?: { host?: string; key: string };
     scripts?: AnalyticsScript[];
     vercel?: boolean;
@@ -45,6 +46,14 @@ const posthogSnippet = posthog
   ? `${POSTHOG_LOADER}posthog.init(${JSON.stringify(posthog.key)},{api_host:${JSON.stringify(posthog.host ?? "https://us.i.posthog.com")}});${POSTHOG_SPA_PAGEVIEWS}`
   : null;
 
+// Cloudflare Web Analytics (manual setup): the beacon script keyed by the
+// site token, exactly as the dashboard's snippet renders it. It tracks
+// history changes itself, so client-router navigations need no extra hook.
+const cloudflareBeacon =
+  enabled && analytics?.cloudflare
+    ? JSON.stringify({ token: analytics.cloudflare.token })
+    : null;
+
 // Custom scripts: any other provider. Each is either external (`src`) or inline
 // (`content`). Explicit fields win over spread `attributes`.
 const customScripts = enabled ? (analytics?.scripts ?? []) : [];
@@ -62,6 +71,16 @@ const inlineScripts = customScripts
 ---
 
 {vercelEnabled && <VercelAnalytics />}
+{
+  cloudflareBeacon && (
+    <script
+      is:inline
+      defer
+      src="https://static.cloudflareinsights.com/beacon.min.js"
+      data-cf-beacon={cloudflareBeacon}
+    />
+  )
+}
 {posthogSnippet && <script is:inline set:html={posthogSnippet} />}
 {externalScripts.map((attrs) => <script is:inline {...attrs} />)}
 {

package/src/components/layout/ReferenceLayout.astro

@@ -48,6 +48,7 @@ interface Props {
     key: string;
   } | null;
   analytics?: {
+    cloudflare?: { token: string };
     posthog?: { host?: string; key: string };
     scripts?: {
       attributes?: Record<string, string>;

package/src/components/layout/RootLayout.astro

@@ -84,6 +84,7 @@ interface Props {
     key: string;
   } | null;
   analytics?: {
+    cloudflare?: { token: string };
     posthog?: { host?: string; key: string };
     scripts?: {
       attributes?: Record<string, string>;

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/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>