blume 1.6.1 → 1.6.3

package/src/astro/generate.ts

@@ -25,10 +25,13 @@ import {
 } from "pathe";
 import { glob } from "tinyglobby";
 
+import { OPENAPI_PATH } from "../ai/api/paths.ts";
+import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
 import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
+import type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
@@ -125,9 +128,15 @@ import {
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPageTemplate,
+  apiPagesIndexTemplate,
+  apiSearchTemplate,
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
   notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
@@ -1319,6 +1328,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       description: config.description,
       discovery: {
         agentReadability: config.seo.agentReadability,
+        api: config.ai.api,
         llmsTxt: config.ai.llmsTxt.enabled,
         // Mirrors `buildSitemapFiles`: no site, no sitemap.
         sitemap: config.seo.sitemap && Boolean(config.deployment.site),
@@ -1505,20 +1515,32 @@ const planMcp = (
 type RuntimeModules = Map<RuntimeModuleId, string>;
 
 /**
- * Publish the MCP data snapshot (`blume:mcp-data`) and write the server
- * endpoint and discovery documents.
+ * The agent data snapshot (`blume:mcp-data`) behind the MCP server and the
+ * JSON docs API: built once per pass when either is on, published to the
+ * runtime modules, and handed to both writers. Null when neither needs it.
  */
-const writeMcpFiles = async (
+const publishAgentData = async (
   project: BlumeProject,
+  plans: { api: ApiPlan; mcp: McpPlan },
+  modules: RuntimeModules
+): Promise<McpData | null> => {
+  if (!(plans.mcp.enabled || plans.api.enabled)) {
+    return null;
+  }
+  const data = await buildMcpData(project);
+  modules.set("blume:mcp-data", JSON.stringify(data));
+  return data;
+};
+
+/** Write the MCP server endpoint and discovery documents. */
+const writeMcpFiles = async (
   plan: McpPlan,
   write: (path: string, content: string) => Promise<boolean>,
-  modules: RuntimeModules
+  data: McpData | null
 ): Promise<void> => {
-  if (!plan.enabled) {
+  if (!(plan.enabled && data)) {
     return;
   }
-  const data = await buildMcpData(project);
-  modules.set("blume:mcp-data", JSON.stringify(data));
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -1542,6 +1564,129 @@ const writeMcpFiles = async (
   ]);
 };
 
+/** The resolved plan for the JSON docs API within a single generate pass. */
+interface ApiPlan {
+  /**
+   * Whether the `/api/` catch-all (JSON 404s) is written: server output, no
+   * user page owning a rest route under `/api/`, and no content page served
+   * from the `/api` namespace (the catch-all would outrank those pages).
+   */
+  catchAll: boolean;
+  enabled: boolean;
+  /** Whether the live endpoints (search) are written — server output only. */
+  server: boolean;
+  /**
+   * Whether `/openapi.json` is generated: skipped when a `public/openapi.json`
+   * or a user page owns the route, so a site can publish its own description.
+   */
+  spec: boolean;
+  srcDir: string;
+}
+
+/** Whether a user page pattern is a rest route under `/api/` (`/api/[...x]`). */
+const ownsApiRest = (page: { pattern: string }): boolean =>
+  page.pattern.startsWith("/api/[");
+
+/**
+ * Whether a content route lives in the `/api` namespace — a docs section
+ * about an API commonly does (`content/api/overview.md` → `/api/overview`).
+ * Astro ranks `/api/[...path]` above the content catch-all (`/[...slug]`),
+ * so the JSON 404 route would shadow those pages wherever routing decides
+ * (the dev server, adapters that don't serve prerendered files first).
+ */
+const contentUnderApi = (page: { route: string }): boolean =>
+  page.route === "/api" || page.route.startsWith("/api/");
+
+/**
+ * Decide what the JSON docs API generates. The prerendered endpoints always
+ * ride along when the feature is on (they live under Blume's own `/api/docs/`
+ * namespace); the live ones need server output; the OpenAPI description yields
+ * to one the project ships itself.
+ */
+const planApi = (
+  project: BlumeProject,
+  srcDir: string,
+  userPages: { pattern: string }[]
+): ApiPlan => {
+  const { config, context } = project;
+  const server = config.deployment.output === "server";
+  return {
+    catchAll:
+      server &&
+      !userPages.some(ownsApiRest) &&
+      !project.graph.pages.some(contentUnderApi),
+    enabled: config.ai.api,
+    server,
+    spec:
+      !routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) &&
+      !existsSync(join(context.root, "public", "openapi.json")),
+    srcDir,
+  };
+};
+
+/**
+ * Write the JSON docs API: the prerendered page index, per-page documents, and
+ * navigation; on server output the search endpoint and the `/api/` catch-all;
+ * and the OpenAPI description of the whole agent-facing surface. The MCP
+ * route reaches the description only when the server was actually planned (a
+ * collision can disable it), so it never advertises an endpoint that isn't
+ * there.
+ */
+const writeApiFiles = async (
+  project: BlumeProject,
+  plan: ApiPlan,
+  write: (path: string, content: string) => Promise<boolean>,
+  data: McpData | null,
+  mcp: McpPlan
+): Promise<void> => {
+  if (!(plan.enabled && data)) {
+    return;
+  }
+  const { config } = project;
+  const mcpRoute = mcp.enabled ? mcp.route : null;
+  const apiDir = join(plan.srcDir, "pages", "api");
+  const writes = [
+    write(join(apiDir, "docs", "pages.json.ts"), apiPagesIndexTemplate()),
+    write(
+      join(apiDir, "docs", "pages", "[...route].json.ts"),
+      apiPageTemplate()
+    ),
+    write(join(apiDir, "docs", "navigation.json.ts"), apiNavigationTemplate()),
+  ];
+  if (plan.server) {
+    writes.push(write(join(apiDir, "docs", "search.ts"), apiSearchTemplate()));
+  }
+  if (plan.catchAll) {
+    writes.push(
+      write(
+        join(apiDir, "[...path].ts"),
+        apiNotFoundTemplate({ base: data.base, site: data.site })
+      )
+    );
+  }
+  if (plan.spec) {
+    writes.push(
+      write(
+        join(plan.srcDir, "pages", "openapi.json.ts"),
+        staticJsonEndpointTemplate(
+          buildApiSpec({
+            agentReadability: config.seo.agentReadability,
+            base: data.base,
+            description: config.description,
+            llmsTxt: config.ai.llmsTxt.enabled,
+            mcpRoute,
+            name: config.title,
+            search: plan.server,
+            site: data.site,
+            version: data.version,
+          })
+        )
+      )
+    );
+  }
+  await Promise.all(writes);
+};
+
 /**
  * Decide whether to generate the playground's built-in CORS proxy endpoint.
  * Only the Blume renderer's playground with `proxy: true` needs it — a proxy
@@ -1661,10 +1806,12 @@ const writeAskFiles = async (
 /**
  * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
  * static builds emit `dist/404.html`, plus its Markdown twin at `404.md.ts`
- * (`dist/404.md`) for agents that ask a missing URL for Markdown. Both are
- * skipped when the project already owns `/404` (a custom `pages/404.astro` or
- * a `404.md` content page), letting it be fully overridden without a route
- * collision; `pruneOrphans` then removes any previously-generated copies.
+ * (`dist/404.md`) for agents that ask a missing URL for Markdown and its JSON
+ * twin at `404.json.ts` (`dist/404.json`, RFC 9457 problem details) for those
+ * that ask for JSON. All three are skipped when the project already owns
+ * `/404` (a custom `pages/404.astro` or a `404.md` content page), letting it
+ * be fully overridden without a route collision; `pruneOrphans` then removes
+ * any previously-generated copies.
  */
 const writeNotFoundPage = async (
   write: (path: string, content: string) => Promise<boolean>,
@@ -1678,6 +1825,7 @@ const writeNotFoundPage = async (
   await Promise.all([
     write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate()),
     write(join(srcDir, "pages", "404.md.ts"), notFoundMarkdownTemplate()),
+    write(join(srcDir, "pages", "404.json.ts"), notFoundJsonTemplate()),
   ]);
 };
 
@@ -1866,6 +2014,11 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
+  // The JSON docs API shares the MCP server's snapshot; build it once when
+  // either is on.
+  const api = planApi(project, srcDir, pages);
+  const agentData = await publishAgentData(project, { api, mcp }, modules);
+
   // The parsed OpenAPI specs behind the `blume:openapi` alias, also the source
   // of the proxy's origin allowlist below. The source parsed them during the
   // scan, so reading them here is free.
@@ -2027,7 +2180,8 @@ export const generateRuntime = async (
       )
     ),
     writeAskFiles(project, srcDir, write, modules),
-    writeMcpFiles(project, mcp, write, modules),
+    writeMcpFiles(mcp, write, agentData),
+    writeApiFiles(project, api, write, agentData, mcp),
     playgroundProxy.enabled
       ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
       : Promise.resolve(false),

package/src/astro/templates.ts

@@ -2560,6 +2560,9 @@ const links = [
   ...(data.config.discovery.llmsTxt
     ? [{ href: href("/llms.txt"), label: nf.llms }]
     : []),
+  ...(data.config.discovery.api
+    ? [{ href: href("/openapi.json"), label: nf.api }]
+    : []),
 ];
 
 const body = [
@@ -2584,6 +2587,160 @@ export function GET() {
 }
 `;
 
+/**
+ * Generate `.blume/src/pages/404.json.ts`: the JSON twin of the default 404
+ * page, prerendered to `dist/404.json` as RFC 9457 problem details. An agent
+ * that asked for a missing page with `Accept: application/json` gets this body
+ * with the 404 status instead of the HTML shell (Vercel server builds wire
+ * that into the routing config, like the Markdown twin). Same recovery links
+ * as the other variants, carried as `links` and spelled out in `resolution`.
+ * Written alongside `404.astro` and skipped under the same rule.
+ */
+export const notFoundJsonTemplate =
+  (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import { problem } from "blume/ai/api/problem.ts";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { absoluteUrl } from "blume/core/site-url.ts";
+import data from "blume:data";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+
+// Absolute for internal routes when the site is known; an external tab href
+// passes through untouched.
+const href = (path: string): string => {
+  const based = withBase(path);
+  return data.config.site && based.startsWith("/") && !based.startsWith("//")
+    ? absoluteUrl(data.config.site, based)
+    : based;
+};
+
+// The recovery set of 404.astro: home, every top-level section (a tab links to
+// its resolved target), then the machine-readable indexes that exist.
+const links = [
+  { href: href("/"), label: nf.home },
+  ...data.navigation.tabs.map((tab) => ({
+    href: href(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: href("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: href("/llms.txt"), label: nf.llms }]
+    : []),
+  ...(data.config.discovery.api
+    ? [{ href: href("/openapi.json"), label: nf.api }]
+    : []),
+];
+
+const body = problem({
+  code: "PAGE_NOT_FOUND",
+  detail: nf.description,
+  links,
+  resolution: nf.suggestions + ": " + links.map((link) => link.href).join(", "),
+  status: 404,
+  title: nf.title,
+});
+
+export function GET() {
+  return new Response(JSON.stringify(body, null, 2) + "\\n", {
+    headers: { "Content-Type": "application/problem+json; charset=utf-8" },
+  });
+}
+`;
+
+/**
+ * Generate the prerendered JSON docs API endpoints under
+ * `.blume/src/pages/api/docs/`: the page index (`pages.json`), one JSON
+ * document per page (`pages/[...route].json`), and the navigation tree
+ * (`navigation.json`). Each is a thin wrapper over `blume/ai/api/handlers.ts`
+ * reading the same snapshot the MCP server serves (`blume:mcp-data`), so the
+ * REST and MCP answers can never diverge.
+ */
+export const apiPagesIndexTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { pagesIndexResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function GET() {
+  return pagesIndexResponse(data);
+}
+`;
+
+export const apiPageTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { pageParams, pageResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function getStaticPaths() {
+  return pageParams(data);
+}
+
+export function GET({ props }: { props: { route: string } }) {
+  return pageResponse(data, props.route);
+}
+`;
+
+export const apiNavigationTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { navigationResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function GET() {
+  return navigationResponse(data);
+}
+`;
+
+/**
+ * Generate the live search endpoint (`.blume/src/pages/api/docs/search.ts`),
+ * server output only: the REST twin of the MCP `search_docs` tool, over the
+ * same snapshot and index.
+ */
+export const apiSearchTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { createSearchHandler } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = false;
+
+const handler = createSearchHandler(data);
+
+export const GET: APIRoute = ({ request }) => handler(request);
+`;
+
+/**
+ * Generate the API namespace's catch-all (`.blume/src/pages/api/[...path].ts`),
+ * server output only: any `/api/…` request no endpoint answers gets an RFC
+ * 9457 problem document with the 404 status instead of the HTML not-found
+ * page. Static segments always beat the rest parameter, so `/api/ask`, the
+ * search proxy, and every prerendered docs endpoint keep winning. The site
+ * context is baked in so the resolution links are absolute when the site is
+ * known.
+ */
+export const apiNotFoundTemplate = (context: {
+  base: string;
+  site: string | null;
+}): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { apiNotFoundResponse } from "blume/ai/api/handlers.ts";
+
+export const prerender = false;
+
+const context = ${JSON.stringify(context)};
+
+export const ALL: APIRoute = ({ request }) => apiNotFoundResponse(request, context);
+`;
+
 /** The literal Astro hydration directive for an island's client mode. */
 const islandDirective = (spec: IslandSpec): string =>
   spec.client === "only"

package/src/cli/commands/build.ts

@@ -334,18 +334,20 @@ const emitVercelNegotiation = async (
   // endpoint stamps it on dev/server-rendered responses itself.
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
-  // The Markdown 404 routes point at the prerendered `404.md`; only wire them
-  // when the build actually emitted it (a project that owns `/404` gets none).
-  const notFoundMarkdown = existsSync(
-    join(root, ".vercel", "output", "static", "404.md")
-  );
+  // The Markdown and JSON 404 routes point at the prerendered twins; only
+  // wire each when the build actually emitted it (a project that owns `/404`
+  // gets none).
+  const staticDir = join(root, ".vercel", "output", "static");
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
     buildHomeLinkHeader(config, routePaths),
     overrides,
     home ? markdownTokenCount(agentMarkdown(home)) : undefined,
-    notFoundMarkdown
+    {
+      json: existsSync(join(staticDir, "404.json")),
+      markdown: existsSync(join(staticDir, "404.md")),
+    }
   );
   if (injected === null) {
     logger.warn(

package/src/components/content/Component.astro

@@ -10,10 +10,7 @@
 // examples are all supported. The source is highlighted with the same Shiki
 // setup as ordinary code fences.
 import data from "blume:data";
-import {
-  CODE_PADDING_BLOCK_REM,
-  FLUSH_CODE_PADDING_TOP_REM,
-} from "../../theme/code-block-padding.ts";
+import { CODE_PADDING_BLOCK_REM } from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { withBase } from "../islands/base-path.ts";
@@ -63,11 +60,10 @@ const codeHtml = entry
 // readers aren't hurt by the cap, since the source scrolls at any height.
 const LINE_PX = 21;
 const REM_PX = 16;
-// The pre's vertical padding, from the same constants the theme emits: the
-// copy-button strip on top (the pane is a flush block inside tabs) and the
-// plain inset below. The tab panel and the pre carry no border of their own.
-const PADDING_PX =
-  (FLUSH_CODE_PADDING_TOP_REM + CODE_PADDING_BLOCK_REM) * REM_PX;
+// The pre's vertical padding, from the same constant the theme emits: the
+// plain inset above and below (the pane is a flush block inside tabs, with no
+// language bar). The tab panel and the pre carry no border of their own.
+const PADDING_PX = 2 * CODE_PADDING_BLOCK_REM * REM_PX;
 const ESTIMATE_MAX_PX = 400;
 // The floor also clamps the measured height client-side; it rides along on the
 // iframe as `data-blume-min-pane` so the script and this estimate can't drift.

package/src/components/content/Tabs.astro

@@ -62,19 +62,34 @@ const useDropdown = dropdown && !inline;
   data-sync={sync ? "true" : "false"}
   data-sync-key={syncKey}
 >
-  <div
-    class:list={[
-      inline ? "not-prose" : "",
-      useDropdown ? "" : "overflow-x-auto",
-    ]}
-  >
+  {/*
+    Header row: the scrolling tab strip (or the dropdown) grows, and an
+    actions slot sits fixed at the inline end, outside the scroller so it
+    never rides along with an overflowing strip. The docs layout fills it
+    with one copy button when every panel is a bare code block (CodeGroup,
+    ts2js pairs) — the strip is that group's chrome, so the button belongs
+    there rather than painted over the first line of each block. Empty
+    otherwise, and hidden so it adds no padding.
+  */}
+  <div class:list={["flex", inline ? "not-prose" : ""]}>
+    <div class:list={["min-w-0 grow", useDropdown ? "" : "overflow-x-auto"]}>
+      <div
+        class:list={[
+          useDropdown || borderBottom ? "border-border border-b" : "",
+          useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
+        ]}
+        data-blume-tablist
+        role={useDropdown ? undefined : "tablist"}
+      >
+      </div>
+    </div>
     <div
       class:list={[
+        "flex shrink-0 items-center gap-2 ps-2 empty:hidden",
+        inline ? "" : "pe-3",
         useDropdown || borderBottom ? "border-border border-b" : "",
-        useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
       ]}
-      data-blume-tablist
-      role={useDropdown ? undefined : "tablist"}
+      data-blume-tab-actions
     >
     </div>
   </div>