blume 1.6.1 → 1.6.3

package/src/components/layout/RootLayout.astro

@@ -798,9 +798,55 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       // Opaque icon chip over the code (in the style of Lina's code block),
       // with the check icon scale-swapping in over the copy icon after a copy.
       const buttonClass =
-        "absolute right-3 z-[2] inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
+        "inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
+      // Pinned over the block's top-right corner when the button lives in
+      // the pre; a strip-hosted button (see codeGroupActions) is in flow.
+      const overlayClass = "absolute right-3 z-[2]";
       const idleClasses = ["hover:bg-muted", "hover:text-foreground"];
 
+      // A tab panel that is nothing but code: a CodeGroup/ts2js block (the
+      // pre is the panel) or a <Tab> holding only fences and the icon
+      // template — the same predicate Tab.astro's flush-padding selector uses.
+      const isCodePanel = (panel: Element) =>
+        panel.matches("pre, figure") ||
+        (panel.matches("[data-blume-tab-panel]") &&
+          panel.querySelector(":scope > pre") !== null &&
+          Array.from(panel.children).every((child) =>
+            child.matches("pre, template")
+          ));
+
+      // The tab group's actions slot, when the group is a code switcher —
+      // every panel a bare block — so one copy button in the strip serves
+      // whichever panel is showing. A group with prose panels (or none) gets
+      // null and keeps a button in each pre.
+      const codeGroupActions = (pre: Element) => {
+        const tabs = pre.closest("blume-tabs");
+        const content = tabs?.querySelector(":scope > [data-blume-tab-content]");
+        const panels = content ? Array.from(content.children) : [];
+        if (!tabs || panels.length === 0 || !panels.every(isCodePanel)) {
+          return null;
+        }
+        return tabs.querySelector<HTMLElement>(
+          ":scope > * > [data-blume-tab-actions]"
+        );
+      };
+
+      // The block the strip's copy button should read: the visible panel's
+      // pre. Panels toggle a `hidden` class once the tabs element upgrades;
+      // before that only the first is painted, and it is also the first
+      // match here.
+      const activeCodePre = (tabs: Element) => {
+        const content = tabs.querySelector(":scope > [data-blume-tab-content]");
+        const panel =
+          Array.from(content?.children ?? []).find(
+            (child) => !child.classList.contains("hidden")
+          ) ?? content?.firstElementChild;
+        if (!panel) {
+          return null;
+        }
+        return panel.matches("pre") ? panel : panel.querySelector("pre");
+      };
+
       const languageLabels: Record<string, string> = {
         astro: "Astro",
         bash: "Bash",
@@ -836,41 +882,16 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         const copiedLabel =
           document.body.getAttribute("data-i18n-copied") || "Copied!";
 
-        for (const pre of document.querySelectorAll(".prose pre")) {
-          if (pre.querySelector("[data-blume-copy]")) {
-            continue;
-          }
-          // Skip nested <pre>: Twoslash renders each hover popup's type signature
-          // as a <pre> inside the code block, which shouldn't get its own button.
-          if (pre.parentElement?.closest("pre")) {
-            continue;
-          }
-          const language = pre.getAttribute("data-language");
-          if (language) {
-            pre.setAttribute(
-              "data-language",
-              languageLabels[language.toLowerCase()] ?? language
-            );
-          }
-          pre.classList.add("group", "relative");
-          // The code element is the scroll container (see the theme entry), but
-          // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
-          // stop to the code so keyboard users can actually scroll the block
-          // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
-          // API-panel blocks keep the pre as their scroller, so theirs stays.
-          const scroller = pre.querySelector("code");
-          if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
-            scroller.setAttribute("tabindex", "0");
-            pre.removeAttribute("tabindex");
-          }
+        // `placement` is the extra class set for an overlay button (empty for
+        // one hosted by a tab strip); `readPre` resolves the block to copy at
+        // click time, since a strip button follows the active panel.
+        const createCopyButton = (
+          placement: string,
+          readPre: () => Element | null
+        ) => {
           const button = document.createElement("button");
           button.type = "button";
-          // The language-label bar (prose) vs flush code (tabs) need a different
-          // offset; pick the Tailwind class by context instead of a CSS override.
-          const topClass = pre.closest("blume-tabs, .not-prose")
-            ? "top-2.5"
-            : "top-2";
-          button.className = `${buttonClass} ${idleClasses.join(" ")} ${topClass}`;
+          button.className = `${buttonClass} ${idleClasses.join(" ")} ${placement}`;
           button.setAttribute("data-blume-copy", "");
           button.setAttribute("aria-label", copyCodeLabel);
           button.innerHTML =
@@ -896,7 +917,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           };
           const flash = createCopyFlash(setChecked, copiedLabel);
           button.addEventListener("click", async () => {
-            const code = pre.querySelector("code");
+            const code = readPre()?.querySelector("code");
             let text = code?.textContent ?? "";
             // Twoslash nests each hover popup's type signature and docs inside
             // the <code>; copying textContent verbatim would interleave them
@@ -914,7 +935,55 @@ const bannerKey = banner?.dismissible ? banner.key : null;
               flash();
             }
           });
-          pre.appendChild(button);
+          return button;
+        };
+
+        for (const pre of document.querySelectorAll(".prose pre")) {
+          if (pre.querySelector("[data-blume-copy]")) {
+            continue;
+          }
+          // Skip nested <pre>: Twoslash renders each hover popup's type signature
+          // as a <pre> inside the code block, which shouldn't get its own button.
+          if (pre.parentElement?.closest("pre")) {
+            continue;
+          }
+          const language = pre.getAttribute("data-language");
+          if (language) {
+            pre.setAttribute(
+              "data-language",
+              languageLabels[language.toLowerCase()] ?? language
+            );
+          }
+          pre.classList.add("group", "relative");
+          // The code element is the scroll container (see the theme entry), but
+          // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
+          // stop to the code so keyboard users can actually scroll the block
+          // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
+          // API-panel blocks keep the pre as their scroller, so theirs stays.
+          const scroller = pre.querySelector("code");
+          if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
+            scroller.setAttribute("tabindex", "0");
+            pre.removeAttribute("tabindex");
+          }
+          const actions = codeGroupActions(pre);
+          if (actions) {
+            // One button per code switcher, reading whichever panel shows.
+            if (!actions.querySelector("[data-blume-copy]")) {
+              const tabs = actions.closest("blume-tabs");
+              actions.appendChild(
+                createCopyButton("", () => (tabs ? activeCodePre(tabs) : null))
+              );
+            }
+            continue;
+          }
+          // The language-label bar (prose) vs flush code (tabs) need a different
+          // offset; pick the Tailwind class by context instead of a CSS override.
+          const topClass = pre.closest("blume-tabs, .not-prose")
+            ? "top-2.5"
+            : "top-2";
+          pre.appendChild(
+            createCopyButton(`${overlayClass} ${topClass}`, () => pre)
+          );
         }
 
         // Click-to-zoom for content images (gated by `markdown.imageZoom`),

package/src/core/config-input.ts

@@ -788,6 +788,15 @@ export interface McpConfig {
  * hosted MCP server.
  */
 export interface AiConfig {
+  /**
+   * The JSON docs API — the REST twin of the MCP tools. Serves the page index
+   * (`/api/docs/pages.json`), each page as JSON (`/api/docs/pages/{route}.json`),
+   * and the navigation tree (`/api/docs/navigation.json`) as prerendered
+   * files, plus full-text search (`/api/docs/search?q=`) on server output,
+   * all described by an OpenAPI document at `/openapi.json`. Errors are RFC
+   * 9457 problem details. Defaults to `true`; set `false` to publish none of it.
+   */
+  api?: boolean;
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
   /**

package/src/core/data.ts

@@ -138,7 +138,13 @@ export interface BlumeDataConfig {
    * `deployment.site`, the condition under which one is emitted) feeds the
    * 404 page's recovery links rather than the head.
    */
-  discovery: { agentReadability: boolean; llmsTxt: boolean; sitemap: boolean };
+  discovery: {
+    agentReadability: boolean;
+    /** Whether the JSON docs API and its `/openapi.json` are published. */
+    api: boolean;
+    llmsTxt: boolean;
+    sitemap: boolean;
+  };
   favicon: BlumeFavicon;
   feedback: boolean;
   /**

package/src/core/i18n-ui.ts

@@ -109,6 +109,8 @@ const uiStringsObject = z.object({
     .prefault({}),
   notFound: z
     .object({
+      /** Label of the OpenAPI description link on the Markdown/JSON 404. */
+      api: z.string().default("JSON API description (openapi.json)"),
       description: z
         .string()
         .default("We couldn't find the page you're looking for."),

package/src/core/schema.ts

@@ -838,6 +838,13 @@ const llmsTxtObjectSchema = z.strictObject({
 type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
 
 const aiConfigSchema = z.strictObject({
+  /**
+   * The JSON docs API: the page index, per-page JSON, and navigation under
+   * `/api/docs/` (prerendered, so a static site serves them from files), the
+   * live search endpoint on server output, and the OpenAPI description of
+   * the whole machine-readable surface at `/openapi.json`. On by default.
+   */
+  api: z.boolean().default(true),
   ask: z
     .strictObject({
       // Name of the env var holding the provider's API key; each provider has

package/src/deploy/vercel-negotiation.ts

@@ -11,7 +11,9 @@
  * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
  * The same routing config also answers a *missing* page: a request that
  * prefers Markdown (or asks for a `.md` URL no page backs) gets the
- * prerendered Markdown 404 body with the 404 status, instead of the HTML shell.
+ * prerendered Markdown 404 body with the 404 status, instead of the HTML
+ * shell, and one that prefers JSON (or asks for a `.json` URL) gets the
+ * prerendered problem-details 404.
  */
 
 /**
@@ -27,6 +29,15 @@
 export const ACCEPT_MARKDOWN_HEADER_VALUE =
   "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
 
+/**
+ * The JSON counterpart, for the problem-details 404: `application/json` or
+ * `application/problem+json`. Browsers never send either on a navigation
+ * (the catch-all wildcard does not match), so ordinary page requests are
+ * unaffected.
+ */
+export const ACCEPT_JSON_HEADER_VALUE =
+  "(.*,)?\\s*application/(problem\\+)?json(\\s*[;,].*)?$";
+
 /**
  * A Build Output API route — the subset these helpers read and write. Parsed
  * routes keep whatever other fields they carry at runtime; only these are
@@ -50,11 +61,18 @@ const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
   { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
 ];
 
+const ACCEPT_JSON_CONDITION: VercelRoute["has"] = [
+  { key: "accept", type: "header", value: ACCEPT_JSON_HEADER_VALUE },
+];
+
 const VARY_ACCEPT = { vary: "Accept" };
 
 /** Where the prerendered Markdown 404 (`pages/404.md.ts`) lands. */
 const NOT_FOUND_MARKDOWN_DEST = "/404.md";
 
+/** Where the prerendered JSON 404 (`pages/404.json.ts`) lands. */
+const NOT_FOUND_JSON_DEST = "/404.json";
+
 /** The adapter's own not-found fallback — the anchor the Markdown 404 precedes. */
 const NOT_FOUND_HTML_DEST = "/404.html";
 
@@ -78,6 +96,30 @@ const NOT_FOUND_MARKDOWN_ROUTES: readonly VercelRoute[] = [
   { dest: NOT_FOUND_MARKDOWN_DEST, src: "^/.*\\.mdx?$", status: 404 },
 ];
 
+/**
+ * The JSON 404's miss-phase routes, the problem-details twin of the Markdown
+ * ones: any path when the client prefers JSON, and any `.json` URL no file
+ * backs. Spliced at the same anchor, after every server route — so the
+ * `/api/` catch-all (which answers its own namespace with a problem document)
+ * has already had its turn.
+ */
+const NOT_FOUND_JSON_ROUTES: readonly VercelRoute[] = [
+  {
+    dest: NOT_FOUND_JSON_DEST,
+    has: ACCEPT_JSON_CONDITION,
+    headers: VARY_ACCEPT,
+    src: "^/.*$",
+    status: 404,
+  },
+  { dest: NOT_FOUND_JSON_DEST, src: "^/.*\\.json$", status: 404 },
+];
+
+/** Which prerendered 404 twins the build emitted, so their routes get wired. */
+export interface NotFoundVariants {
+  json?: boolean;
+  markdown?: boolean;
+}
+
 /**
  * Vercel rejects route `src` patterns longer than 4096 characters, so route
  * alternations are split across as many route entries as needed. The budget
@@ -223,6 +265,7 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
     (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
   ) === true ||
   (route.dest === NOT_FOUND_MARKDOWN_DEST && route.status === 404) ||
+  (route.dest === NOT_FOUND_JSON_DEST && route.status === 404) ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
     isString(route.src) &&
@@ -244,10 +287,11 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
  * signature directory). The trailing-slash 308 redirect is always spliced in
  * alongside, so slashed duplicates of every page collapse onto the canonical
- * slashless URL. With `notFoundMarkdown` (the build emitted `404.md`), the
- * Markdown 404 routes go into the miss phase right before the adapter's
- * `/404.html` fallback — and nowhere when that fallback is absent, since a
- * `dest` with no file behind it would serve nothing. Returns the updated JSON
+ * slashless URL. For each 404 twin the build emitted (`notFound.markdown` for
+ * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
+ * phase right before the adapter's `/404.html` fallback — and nowhere when
+ * that fallback is absent, since a `dest` with no file behind it would serve
+ * nothing. Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
@@ -258,7 +302,7 @@ export const injectNegotiationRoutes = (
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
   homeTokens?: number,
-  notFoundMarkdown = false
+  notFound: NotFoundVariants = {}
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -307,12 +351,16 @@ export const injectNegotiationRoutes = (
     ...rewriteRoutes,
     TRAILING_SLASH_REDIRECT
   );
-  if (notFoundMarkdown) {
+  const notFoundRoutes = [
+    ...(notFound.markdown ? NOT_FOUND_MARKDOWN_ROUTES : []),
+    ...(notFound.json ? NOT_FOUND_JSON_ROUTES : []),
+  ];
+  if (notFoundRoutes.length > 0) {
     const fallbackIndex = routes.findIndex(
       (route) => route.status === 404 && route.dest === NOT_FOUND_HTML_DEST
     );
     if (fallbackIndex !== -1) {
-      routes.splice(fallbackIndex, 0, ...NOT_FOUND_MARKDOWN_ROUTES);
+      routes.splice(fallbackIndex, 0, ...notFoundRoutes);
     }
   }
   config.routes = routes;

package/src/theme/code-block-padding.ts

@@ -6,11 +6,3 @@
 
 /** Top and bottom inset of a plain prose block with no chrome, in rem. */
 export const CODE_PADDING_BLOCK_REM = 1;
-
-/**
- * Top inset of a flush block — inside tabs or a `not-prose` component, or an
- * untitled block with no language bar — where the layout's copy button is
- * absolutely positioned over the first line: `top-2.5` plus a 1.875rem button
- * lands at 2.5rem, so the first line starts there.
- */
-export const FLUSH_CODE_PADDING_TOP_REM = 2.5;

package/src/theme/entry.ts

@@ -1,7 +1,4 @@
-import {
-  CODE_PADDING_BLOCK_REM,
-  FLUSH_CODE_PADDING_TOP_REM,
-} from "./code-block-padding.ts";
+import { CODE_PADDING_BLOCK_REM } from "./code-block-padding.ts";
 
 interface TailwindEntryOptions {
   /**
@@ -614,27 +611,19 @@ blume-tabs pre[data-language],
   padding-top: ${CODE_PADDING_BLOCK_REM}rem;
 }
 
-/* Room for the copy button. The docs layout injects it into every \`.prose pre\`
-   — absolutely positioned against the pre's border box, 1.875rem tall, at
-   \`top-2.5\` in the flush contexts above and \`top-2\` elsewhere — and it is
-   unconditional, so wherever no language bar exists to hold it, it painted
-   over the first line of code: any line long enough to reach the button's
-   strip (a curl invocation, an install command, an import path) went under
-   it. Keyed on the attribute the docs layout stamps on <body>, so the strip
-   only appears where the injector runs (PageLayout pages run none), and on
-   \`.astro-code\` so the playground's response pre — created after the
-   injector ran, never given a button — keeps its plain inset. The first
-   selector is the injector's own flush predicate; the second covers the
-   remaining bar-less Shiki case, an untitled <CodeBlock> in plain prose, from
-   first paint. The third covers a raw \`<pre><code>\` written in prose — no
-   \`.astro-code\`, no language bar, but the injector gives it a button all
-   the same — keyed on that injected button, which is exactly what separates
-   it from the playground's pre. API panel blocks match, but their own
-   !important padding wins and they hide the injected button. */
-[data-blume-code-copy] :is(blume-tabs, .not-prose) pre.astro-code,
-[data-blume-code-copy] .prose pre.astro-code:not([data-language]),
-[data-blume-code-copy] .prose pre:not([data-language]):has(> [data-blume-copy]) {
-  padding-top: ${FLUSH_CODE_PADDING_TOP_REM}rem;
+/* Where no language bar holds the copy button — a flush block in tabs or a
+   not-prose component, a bar-less block in prose — the docs layout still pins
+   one over the block's top-right corner, so a first line long enough to reach
+   it would end underneath. A code switcher (CodeGroup, ts2js) hosts the button
+   in its tab strip instead and needs nothing here; for every block that keeps
+   an overlay button, give the scrolling code element enough end padding that
+   the line's tail clears the button at the end of its scroll. Keyed on the
+   injected button itself (which the playground's client-created response pre
+   never gets), and \`.prose\`-scoped to outrank the base \`:where(pre code)\`
+   inset. Not a vertical inset — that reserved a strip above every one-line
+   command and read as a rendering bug. */
+.prose :is(blume-tabs pre, .not-prose pre, pre:not([data-language])):not(.twoslash, .twoslash pre, blume-panel-tabs *):has(> [data-blume-copy]) > code {
+  padding-inline-end: 3.5rem;
 }
 
 blume-tabs pre[data-language]::before,