blume 2.1.1 → 2.1.2

package/src/astro/runtime-deps.ts

@@ -103,6 +103,25 @@ export const assistantProviderDependencies = (
       )
     : [];
 
+/**
+ * The narration provider's SDK, when missing: `openai()` speaks through
+ * `@ai-sdk/openai`, which the build loads to generate the clips, while
+ * `gateway()` needs nothing beyond the core `ai` package Blume ships.
+ */
+export const narrationProviderDependencies = (
+  narration: ResolvedConfig["narration"],
+  root: string,
+  pkgDir: string = packageRoot()
+): MissingDependency[] =>
+  narration.enabled && narration.provider
+    ? unresolved(
+        `Narration provider "${narration.provider.kind}"`,
+        narration.provider.runtimeDeps,
+        root,
+        pkgDir
+      )
+    : [];
+
 /**
  * The deployment adapter's package, when missing. Node and Vercel ship with
  * Blume, so theirs always resolve; Netlify and Cloudflare are optional peers.
@@ -152,8 +171,9 @@ export const islandFrameworkDependencies = (
 /**
  * Every package the resolved config's adapters (and the given island
  * frameworks) import that isn't installed: the search SDK, content source
- * SDKs, the assistant provider SDK, the deployment adapter, and island
- * integrations. The adapters' `runtimeDeps` are the one place that knows.
+ * SDKs, the assistant and narration provider SDKs, the deployment adapter,
+ * and island integrations. The adapters' `runtimeDeps` are the one place that
+ * knows.
  */
 export const missingRuntimeDependencies = (
   config: ResolvedConfig,
@@ -164,6 +184,7 @@ export const missingRuntimeDependencies = (
   ...searchProviderDependencies(config.search.provider, root, pkgDir),
   ...sourceAdapterDependencies(config.content.sources, root, pkgDir),
   ...assistantProviderDependencies(config.ai.assistant, root, pkgDir),
+  ...narrationProviderDependencies(config.narration, root, pkgDir),
   ...deploymentAdapterDependencies(config.deployment, root, pkgDir),
   ...islandFrameworkDependencies(frameworks, root),
 ];

package/src/astro/templates.ts

@@ -567,7 +567,10 @@ const blumeIntegrationOptions = (options: {
   pages: BlumePageRoute[];
   redirects: CompiledRedirect[];
 }): BlumeIntegrationOptions => {
-  const shared: BlumeIntegrationOptions = { pages: options.pages };
+  const shared: BlumeIntegrationOptions = {
+    pages: options.pages,
+    poweredBy: options.config.poweredBy,
+  };
   if (options.redirects.length > 0) {
     shared.redirects = options.redirects;
   }

package/src/cli/init/scaffold.ts

@@ -557,6 +557,8 @@ const pnpmWorkspaceSchema = z.looseObject({
 // A glob's leading `./` and trailing `/`, which pnpm ignores.
 const GLOB_EDGES = /^\.\/|\/+$/gu;
 
+const globPattern = (glob: string): string => glob.replaceAll(GLOB_EDGES, "");
+
 /** Whether any of `globs` matches the workspace-relative path `at`. */
 const matchesAny = (globs: string[], at: string): boolean =>
   globs.length > 0 && picomatch(globs)(at);
@@ -589,11 +591,12 @@ const listsPackage = (workspace: string, root: string): boolean => {
     return true;
   }
   const globs = parsed.data.packages;
-  const pattern = (glob: string): string => glob.replaceAll(GLOB_EDGES, "");
-  const included = globs.filter((glob) => !glob.startsWith("!")).map(pattern);
+  const included = globs
+    .filter((glob) => !glob.startsWith("!"))
+    .map(globPattern);
   const excluded = globs
     .filter((glob) => glob.startsWith("!"))
-    .map((glob) => pattern(glob.slice(1)));
+    .map((glob) => globPattern(glob.slice(1)));
   return matchesAny(included, at) && !matchesAny(excluded, at);
 };
 

package/src/cli/required-secrets.ts

@@ -92,7 +92,8 @@ export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
   }
 
   // Generated narration reads its key at build, not at runtime; without it the
-  // build skips the audio and pages read with browser voices.
+  // build skips the audio and pages read with browser voices. `openai()` with
+  // a `baseUrl` requires only a key it names (see `narrationProviderSchema`).
   const { narration } = config;
   if (narration.enabled && narration.provider) {
     for (const env of narration.provider.requiredSecrets) {

package/src/components/content/view-switcher.ts

@@ -42,6 +42,10 @@ const cssString = (value: string): string =>
     .replaceAll("<", String.raw`\3c `)
     .replaceAll(/[\n\r\f]/gu, " ")}"`;
 
+/** Everything tagged with a view other than `title`. */
+const otherViews = (title: string): string =>
+  `[data-blume-view]:not([data-blume-view=${cssString(title)}])`;
+
 /**
  * The page's view CSS: with a view chosen on `<body>`, everything tagged with
  * another is hidden; before a choice, everything but the first view is.
@@ -51,12 +55,11 @@ export const viewStyle = (titles: readonly string[]): string => {
   if (first === undefined) {
     return "";
   }
-  const other = (title: string): string =>
-    `[data-blume-view]:not([data-blume-view=${cssString(title)}])`;
   const selectors = [
-    `body:not([data-blume-view]) ${other(first)}`,
+    `body:not([data-blume-view]) ${otherViews(first)}`,
     ...titles.map(
-      (title) => `body[data-blume-view=${cssString(title)}] ${other(title)}`
+      (title) =>
+        `body[data-blume-view=${cssString(title)}] ${otherViews(title)}`
     ),
   ];
   return `${selectors.join(",")}{display:none!important}`;

package/src/components/layout/NavTree.astro

@@ -307,15 +307,59 @@ const initialId =
         const spacing =
           index === 0 ? "mt-0" : display === "flat" ? "mt-6" : "mt-0.5";
 
-        // `page`: a single row that drills into this group's panel. It
-        // controls that panel; NavTreeScript keeps `aria-expanded` in step
-        // with the panel shown (static markup, since cached subtrees and
-        // fragments can't carry per-page state).
+        // `page`: a single row that drills into this group's panel. Its drill
+        // button controls that panel; NavTreeScript keeps `aria-expanded` in
+        // step with the panel shown (static markup, since cached subtrees and
+        // fragments can't carry per-page state). A group with an index page
+        // splits the row, like the `group` summary: the label links that page
+        // (which renders with the panel open), so the row opens the section
+        // even when the index hides its own row, and the chevron stays a
+        // button that slides the panel in without leaving the page. Without
+        // one, the whole row is the drill button, so it never links a missing
+        // page. `aria-current` marks the row whose panel holds the current
+        // page (`page` on the section's own page), so the parent panel still
+        // shows where the reader is after the back arrow. Only rows on the
+        // active path carry it, and those always render live, never from a
+        // cache.
         if (display === "page") {
-          return (
+          const current = hasActivePage(item)
+            ? isGroupRowCurrent(item, currentRoute)
+              ? "page"
+              : "true"
+            : undefined;
+          return item.route ? (
+            <li class={`flex items-center gap-0.5 ${spacing}`}>
+              <a
+                aria-current={current}
+                class="blume-nav-drill-link"
+                href={withMountedBase(item.route)}
+              >
+                {item.icon && (
+                  <Icon
+                    class="shrink-0 text-muted-foreground"
+                    name={item.icon}
+                    size={14}
+                  />
+                )}
+                <span class="flex-1 truncate">{item.label}</span>
+                {item.badge && <span class={badgeClassFor(item.badge)}>{item.badge}</span>}
+              </a>
+              <button
+                aria-controls={navPanelId(id)}
+                aria-expanded="false"
+                aria-label={item.label}
+                class="blume-nav-drill-toggle"
+                data-nav-to={id}
+                type="button"
+              >
+                <Icon class="rtl:-scale-x-100" name="chevron-right" size={14} />
+              </button>
+            </li>
+          ) : (
             <li class={spacing}>
               <button
                 aria-controls={navPanelId(id)}
+                aria-current={current}
                 aria-expanded="false"
                 class="blume-nav-drill"
                 data-nav-to={id}

package/src/components/layout/NavTreeScript.astro

@@ -146,6 +146,24 @@
           }
           return;
         }
+        // After the back arrow, the current section's name links the page
+        // already on screen, so a plain click slides its panel back in rather
+        // than reloading that page. Modified clicks stay the browser's.
+        const own = target.closest('.blume-nav-drill-link[aria-current="page"]');
+        const ownId = own?.parentElement
+          ?.querySelector("[data-nav-to]")
+          ?.getAttribute("data-nav-to");
+        if (
+          own &&
+          ownId &&
+          this.contains(own) &&
+          this.panel(ownId) &&
+          !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        ) {
+          event.preventDefault();
+          void this.show(ownId, true);
+          return;
+        }
         const back = target.closest("[data-nav-back]");
         if (back && this.contains(back)) {
           event.preventDefault();

package/src/components/layout/PageLayout.astro

@@ -126,10 +126,17 @@ interface Props {
   canonical?: string | null;
   /**
    * Emit schema.org JSON-LD for this page (`data.config.structuredData`) — a
-   * WebSite node, plus an article node on non-root routes. Defaults to on,
-   * matching RootLayout.
+   * WebSite node, plus a WebPage node on the homepage and an article node on
+   * other routes. Defaults to on, matching RootLayout.
    */
   structuredDataEnabled?: boolean;
+  /**
+   * When the page last changed, emitted as the JSON-LD `dateModified`. A
+   * custom page has no content file to date, so pass it by hand; without a
+   * machine-readable date, search engines take whatever other date the page
+   * shows.
+   */
+  lastModified?: string | Date | null;
   /**
    * Which agent-discovery resources exist, advertised as `describedby` head
    * links plus the AI Catalog/ARD pair — the same `DiscoveryLinks` partial
@@ -184,6 +191,7 @@ const {
   ogImageSize,
   canonical,
   structuredDataEnabled,
+  lastModified,
   discovery = data.config.discovery,
   x,
   noindex,
@@ -279,7 +287,8 @@ const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
 // JSON-LD, mirroring RootLayout: skipped when disabled or noindexed. A custom
-// page has no breadcrumb trail; the home route yields the WebSite node alone.
+// page has no breadcrumb trail; the home route is a WebPage, dated by
+// `lastModified` when the page passes one.
 const structuredData =
   structuredDataEnabled === false || noindex
     ? null
@@ -289,6 +298,7 @@ const structuredData =
       description,
       identity: data.config.identity,
       locale,
+      modified: lastModified,
       route,
       siteName: site.title,
       siteUrl: siteUrl ?? null,

package/src/components/layout/RootLayout.astro

@@ -432,10 +432,13 @@ const description = page.description ?? site.description;
 // pages (and the changelog index, which has no `type`) stay `website`.
 const ogType =
   pageType === "blog" || pageType === "changelog" ? "article" : "website";
+// The last-modified date as ISO 8601, parsed once for every surface that
+// carries it; undefined when absent or unparseable.
+const lastModifiedIso = toIso(lastModified);
 // `article:*` timestamps only belong on an article; a docs page carrying them
 // would be declaring properties its `og:type` doesn't define.
 const articlePublished = ogType === "article" ? toIso(published) : undefined;
-const articleModified = ogType === "article" ? toIso(lastModified) : undefined;
+const articleModified = ogType === "article" ? lastModifiedIso : undefined;
 // X sizes the card from `twitter:card`: a large image needs the wide variant,
 // and a page with no image still gets a card (the compact `summary`) rather
 // than rendering as a bare link.
@@ -448,14 +451,12 @@ const xCreator = normalizeXHandle(x?.creator);
 
 // "Last updated on <date>" — the configured `dateFormat`, in UTC (unless the
 // config names a zone) so it matches the changelog timeline.
-const lastModifiedDate = lastModified ? new Date(lastModified) : null;
-const formattedLastModified =
-  lastModifiedDate && !Number.isNaN(lastModifiedDate.getTime())
-    ? new Intl.DateTimeFormat(
-        locale || "en",
-        resolveDateFormatOptions(dateFormat)
-      ).format(lastModifiedDate)
-    : null;
+const formattedLastModified = lastModifiedIso
+  ? new Intl.DateTimeFormat(
+      locale || "en",
+      resolveDateFormatOptions(dateFormat)
+    ).format(new Date(lastModifiedIso))
+  : null;
 
 // This page's raw-Markdown mirror, advertised as a `text/markdown` alternate
 // in the head. Content routes always have one (see `markdownRoutePaths`, which
@@ -521,6 +522,7 @@ const structuredData =
       base: import.meta.env.BASE_URL,
       breadcrumbs: crumbs,
       description,
+      homeRoute: navigation.root,
       identity: data.config.identity,
       locale,
       modified: lastModified,
@@ -929,7 +931,7 @@ const localeRedirect = localeTargets
               />
               {formattedLastModified && (
                 <p class="mx-auto mt-10 max-w-content text-muted-foreground text-sm">
-                  {strings.page.lastUpdated} {formattedLastModified}
+                  {strings.page.lastUpdated} <time datetime={lastModifiedIso}>{formattedLastModified}</time>
                 </p>
               )}
               {feedback && (
@@ -1378,10 +1380,13 @@ const localeRedirect = localeTargets
       }
       @media (prefers-reduced-motion: reduce) {
         /* html prefix outranks the library's rules regardless of sheet
-           order; its transition declarations carry !important. */
+           order; its transition declarations carry !important. Near-instant,
+           never `none`: medium-zoom only finishes opening and closing on the
+           image's `transitionend`, so with no transition a zoomed image
+           ignores Escape, clicks, and scrolls forever. */
         html .medium-zoom-image,
         html .medium-zoom-overlay {
-          transition: none !important;
+          transition-duration: 1ms !important;
         }
       }
     </style>

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

@@ -2,14 +2,14 @@
  * Send a custom analytics event to every analytics platform configured in
  * `blume.config.ts`. Mirrors the adapters `Analytics.astro` wires
  * (`src/analytics/*`): each one with a custom-event API is called through the
- * global its snippet defines (Cloudflare and Clearbit have none to forward
- * to), and the `blume:track` CustomEvent fires unconditionally so a project
- * can bridge the event to anything else — a `script()` adapter, say. Every
- * call no-ops cleanly when a provider isn't present — for example during
- * `blume dev`, where `Analytics.astro` injects nothing — and a provider that
- * throws (a consent shim that stubs `gtag` with a raise, a broken snippet) is
- * isolated so it neither starves the providers after it nor surfaces in the
- * feature that reported the event.
+ * global its snippet defines (Cloudflare, Clearbit, and Clics have none to
+ * forward to), and the `blume:track` CustomEvent fires unconditionally so a
+ * project can bridge the event to anything else — a `script()` adapter, say.
+ * Every call no-ops cleanly when a provider isn't present — for example
+ * during `blume dev`, where `Analytics.astro` injects nothing — and a provider
+ * that throws (a consent shim that stubs `gtag` with a raise, a broken
+ * snippet) is isolated so it neither starves the providers after it nor
+ * surfaces in the feature that reported the event.
  */
 import { track as vercelTrack } from "@vercel/analytics";
 

package/src/components/openapi/playground-client.ts

@@ -271,6 +271,59 @@ const line = (className: string, text: string): HTMLElement => {
   return el;
 };
 
+/** Render one settled HTTP exchange: status + time, headers, pretty body. */
+const renderResponse = (
+  region: HTMLElement,
+  res: Response,
+  ms: number,
+  text: string
+): void => {
+  region.textContent = "";
+  region.append(
+    line(
+      "font-mono font-semibold text-foreground text-sm",
+      `${res.status} ${res.statusText} \u00B7 ${ms} ms`.trim()
+    )
+  );
+  const table = document.createElement("table");
+  table.className = "w-full text-start text-xs";
+  for (const [name, value] of res.headers) {
+    const row = document.createElement("tr");
+    const header = document.createElement("th");
+    header.setAttribute("scope", "row");
+    header.className = "pe-3 align-top font-medium text-muted-foreground";
+    header.textContent = name;
+    const cell = document.createElement("td");
+    cell.className = "break-all font-mono text-foreground";
+    cell.textContent = value;
+    row.append(header, cell);
+    table.append(row);
+  }
+  region.append(table);
+  const pre = document.createElement("pre");
+  pre.className =
+    "overflow-x-auto rounded-blume border border-border p-3 font-mono text-foreground text-xs";
+  const code = document.createElement("code");
+  code.textContent = prettyBody(text);
+  pre.append(code);
+  region.append(pre);
+  // At xl the panel is its own scroll region capped to the viewport, so a
+  // response appended under a tall form can land below the panel's fold
+  // where nothing brings it into view. Scroll the panel alone — "nearest",
+  // by hand — and never the document: below xl the panel does not scroll,
+  // and a document scroll would carry the form (Send, the body editor, its
+  // errors) off the top on a phone.
+  const panel = region.closest<HTMLElement>("[data-operation-panel]");
+  if (panel && panel.scrollHeight > panel.clientHeight) {
+    const box = panel.getBoundingClientRect();
+    const target = region.getBoundingClientRect();
+    const delta = Math.min(target.bottom - box.bottom, target.top - box.top);
+    if (delta > 0) {
+      panel.scrollBy({ top: delta });
+    }
+  }
+};
+
 /**
  * Wire the playground inside `root` (the `<blume-playground>` element). Reads
  * the server-rendered model JSON, keeps the request samples in sync with the
@@ -470,59 +523,6 @@ export const initPlayground = (root: HTMLElement): void => {
     }
   };
 
-  /** Render one settled HTTP exchange: status + time, headers, pretty body. */
-  const renderResponse = (
-    region: HTMLElement,
-    res: Response,
-    ms: number,
-    text: string
-  ): void => {
-    region.textContent = "";
-    region.append(
-      line(
-        "font-mono font-semibold text-foreground text-sm",
-        `${res.status} ${res.statusText} \u00B7 ${ms} ms`.trim()
-      )
-    );
-    const table = document.createElement("table");
-    table.className = "w-full text-start text-xs";
-    for (const [name, value] of res.headers) {
-      const row = document.createElement("tr");
-      const header = document.createElement("th");
-      header.setAttribute("scope", "row");
-      header.className = "pe-3 align-top font-medium text-muted-foreground";
-      header.textContent = name;
-      const cell = document.createElement("td");
-      cell.className = "break-all font-mono text-foreground";
-      cell.textContent = value;
-      row.append(header, cell);
-      table.append(row);
-    }
-    region.append(table);
-    const pre = document.createElement("pre");
-    pre.className =
-      "overflow-x-auto rounded-blume border border-border p-3 font-mono text-foreground text-xs";
-    const code = document.createElement("code");
-    code.textContent = prettyBody(text);
-    pre.append(code);
-    region.append(pre);
-    // At xl the panel is its own scroll region capped to the viewport, so a
-    // response appended under a tall form can land below the panel's fold
-    // where nothing brings it into view. Scroll the panel alone — "nearest",
-    // by hand — and never the document: below xl the panel does not scroll,
-    // and a document scroll would carry the form (Send, the body editor, its
-    // errors) off the top on a phone.
-    const panel = region.closest<HTMLElement>("[data-operation-panel]");
-    if (panel && panel.scrollHeight > panel.clientHeight) {
-      const box = panel.getBoundingClientRect();
-      const target = region.getBoundingClientRect();
-      const delta = Math.min(target.bottom - box.bottom, target.top - box.top);
-      if (delta > 0) {
-        panel.scrollBy({ top: delta });
-      }
-    }
-  };
-
   /**
    * Send the real request. HTTP error statuses render like any response; only
    * a rejected fetch (the CORS wall) gets the explanatory message. One request

package/src/components/powered-by-middleware.ts

@@ -0,0 +1,33 @@
+import type { MiddlewareHandler } from "astro";
+
+import { POWERED_BY_HEADERS } from "../core/powered-by.ts";
+
+/**
+ * Names Blume in the responses Astro renders (wired by the integration unless
+ * `poweredBy` is `false`), the server-rendered ones a host's own header rules
+ * don't reach. Innermost, so a page or the project's own middleware that sets
+ * a header of the same name keeps its value. Headers are set in place; a
+ * response whose headers are immutable (a proxied `fetch()` result) is copied
+ * first.
+ */
+export const onRequest: MiddlewareHandler = async (_context, render) => {
+  const response = await render();
+  const missing = Object.entries(POWERED_BY_HEADERS).filter(
+    ([name]) => !response.headers.has(name)
+  );
+  if (missing.length === 0) {
+    return response;
+  }
+  try {
+    for (const [name, value] of missing) {
+      response.headers.set(name, value);
+    }
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    for (const [name, value] of missing) {
+      copy.headers.set(name, value);
+    }
+    return copy;
+  }
+};

package/src/core/config-input.ts

@@ -2,7 +2,11 @@ import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
-import type { AssistantAdapter, AssistantGatewayAdapter } from "../ai/ask.ts";
+import type {
+  AssistantAdapter,
+  AssistantGatewayAdapter,
+  AssistantOpenAIAdapter,
+} from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { AnalyticsAdapter } from "../analytics/schema.ts";
 import type { CaptchaAdapter } from "../captcha/schema.ts";
@@ -1399,9 +1403,11 @@ export type NarrationConfig =
       /**
        * Generate audio at build with a speech model:
        * `gateway({ model: "openai/tts-1-hd", voice: "alloy" })` from
-       * `blume/ai`. Without it, pages are read with browser voices.
+       * `blume/ai`, or `openai({ model, voice })` for OpenAI or, with a
+       * `baseUrl`, any OpenAI-compatible speech endpoint. Without it, pages
+       * are read with browser voices.
        */
-      provider?: AssistantGatewayAdapter;
+      provider?: AssistantGatewayAdapter | AssistantOpenAIAdapter;
     };
 
 /**
@@ -1585,6 +1591,8 @@ export interface BlumeConfig {
   narration?: NarrationConfig;
   /** Header, sidebar, tabs, and switchers. */
   navigation?: NavigationConfig;
+  /** Send `X-Powered-By: Blume` with responses. Defaults to `true`. */
+  poweredBy?: boolean;
   /**
    * Limit how often one reader (by IP address) can call the server routes —
    * the assistant, the API playground proxy, server-side search — with an

package/src/core/powered-by.ts

@@ -0,0 +1,12 @@
+/**
+ * The header that names Blume as the framework behind a response, sent unless
+ * `poweredBy` is `false`. The dev server and Blume's runtime middleware
+ * (`components/powered-by-middleware.ts`) send it, and so does every host
+ * for the built site: static hosts through `deploy/headers.ts`'s rules,
+ * server builds through each platform's own mechanism (`deploy/platforms`).
+ * It lives apart from those modules so the runtime middleware can import it
+ * without pulling in the deploy code.
+ */
+export const POWERED_BY_HEADERS = {
+  "X-Powered-By": "Blume",
+} satisfies Record<string, string>;

package/src/core/schema.ts

@@ -1206,10 +1206,10 @@ const feedbackConfigSchema = z
 
 // "Listen to this page". Off by default. `true` reads pages aloud with the
 // reader's browser voices, which needs no key and works on any host; an object
-// with a `provider` (`gateway()` from `blume/ai`) generates neural audio at
-// build instead, one cached clip per sentence, and falls back to the browser's
-// voices where no clips exist (`blume dev`, a build without the key). Both
-// normalize to `{ enabled, provider }`.
+// with a `provider` (`gateway()` or `openai()` from `blume/ai`) generates
+// neural audio at build instead, one cached clip per sentence, and falls back
+// to the browser's voices where no clips exist (`blume dev`, a build without
+// the key). Both normalize to `{ enabled, provider }`.
 const narrationConfigSchema = z
   .union([
     z.boolean(),
@@ -2159,6 +2159,7 @@ export const blumeConfigSchema = z
       markdown: markdownConfigSchema.prefault({}),
       narration: narrationConfigSchema.prefault(false),
       navigation: navigationConfigSchema.prefault({}),
+      poweredBy: z.boolean().default(true),
       // An adapter from `blume/ratelimit`, `memory()` by default; `false` is off.
       rateLimit: rateLimitConfigSchema,
       react: reactConfigSchema.prefault({}),

package/src/core/sources/lower.ts

@@ -299,6 +299,17 @@ const renderParts = (
 export const renderInline = (parts: InlinePart[]): string =>
   renderParts(parts, escapeProse);
 
+const asTyped = (text: string): string => text;
+
+/**
+ * A block's inline content as MDX source, for a source whose site author
+ * opted in to reading its text that way: marks still become delimiters and
+ * code stays a code span, but the text goes in as typed, so a component, an
+ * expression, or Markdown written in the CMS renders.
+ */
+export const renderInlineMdx = (parts: InlinePart[]): string =>
+  renderParts(parts, asTyped);
+
 // A destination with whitespace, a control character, or parentheses ends
 // early in `[label](…)`; CommonMark's pointy-bracket form carries it intact.
 // oxlint-disable-next-line no-control-regex -- control characters are exactly what the bare form refuses.
@@ -331,13 +342,18 @@ export const destination = (url: string): string => {
  * `data:`) never becomes a clickable link on the docs site (see
  * `safe-links.ts`). The parts stay parts then, so their runs merge with their
  * neighbors'. A label escapes a bare URL too: GFM autolinks nothing inside a
- * link, so its specials would read as syntax.
+ * link, so its specials would read as syntax — unless `mdx` reads the label
+ * as MDX source, like {@link renderInlineMdx}.
  */
-export const linkParts = (parts: InlinePart[], href?: string): InlinePart[] =>
+export const linkParts = (
+  parts: InlinePart[],
+  href?: string,
+  mdx = false
+): InlinePart[] =>
   href && isSafeHref(href)
     ? [
         {
-          markdown: `[${renderParts(parts, escapeMarkdownText)}](${destination(href)})`,
+          markdown: `[${renderParts(parts, mdx ? asTyped : escapeMarkdownText)}](${destination(href)})`,
         },
       ]
     : parts;