blume 1.6.4 → 1.6.5

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 }) : "";

package/src/core/config-input.ts

@@ -895,6 +895,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/src/core/schema.ts

@@ -1220,6 +1220,14 @@ const analyticsScriptSchema = z
   });
 
 const analyticsConfigSchema = z.strictObject({
+  // Cloudflare Web Analytics in manual (JS snippet) mode; the token comes from
+  // the site's snippet in the dashboard. A zone Cloudflare proxies with
+  // automatic RUM injection on needs no config at all.
+  cloudflare: z
+    .strictObject({
+      token: z.string().min(1),
+    })
+    .optional(),
   posthog: z
     .strictObject({
       host: z.string().optional(),

package/src/theme/entry.ts

@@ -560,9 +560,16 @@ blume-diff {
 /* Restore inner padding on every cell. Typography zeroes the first/last cell's
    inline padding so a borderless table aligns to the prose margin; inside the
    framed wrapper that leaves edge text touching the border. The :is() selector
-   outweighs Typography's :where()-scoped rules so the outer columns get it too. */
+   outweighs Typography's :where()-scoped rules so the outer columns get it too.
+
+   The block padding is 0.75rem against a table line-height near 1.7: at 0.5rem a
+   cell whose content wrapped put MORE space between its own two lines than
+   between itself and the next row, so a table of wrapping cells read as one
+   block rather than as rows. The inline padding stays where it was, deliberately
+   — widening it comes out of column width in a capped article, and on one corpus
+   that pushed cells fitting on two lines onto three. */
 .blume-table-scroll :is(th, td) {
-  padding: 0.5rem 0.75rem;
+  padding: 0.75rem;
 }
 /* Keep column labels on one line so a two-word header does not wrap into a
    ragged stack; the table just scrolls a little wider instead. Body cells keep