blume 1.6.0 → 1.6.2

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";
@@ -91,10 +94,16 @@ import {
   fontLocaleCodes,
 } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
+import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
-import { discoverExamples, exampleMarkdownLookup } from "./examples.ts";
+import {
+  EXAMPLE_SCAN_GLOB,
+  discoverExamples,
+  exampleMarkdownLookup,
+  exampleScanRoots,
+} from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import {
   customOgRoutes,
@@ -102,6 +111,8 @@ import {
   hasGeneratedChangelog,
   routeIsTaken,
 } from "./pages.ts";
+import { publishRuntimeModules } from "./runtime-modules.ts";
+import type { RuntimeModuleId } from "./runtime-modules.ts";
 import {
   askComponentTemplate,
   askEndpointTemplate,
@@ -117,9 +128,16 @@ import {
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPageTemplate,
+  apiPagesIndexTemplate,
+  apiSearchTemplate,
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
   playgroundProxyTemplate,
@@ -714,6 +732,21 @@ const readOptional = async (path: string | null): Promise<string> => {
   }
 };
 
+/**
+ * Read a user stylesheet (`theme.css`, `examples.css`) that gets inlined into
+ * a generated Tailwind entry under `outputDir`, re-rooting its relative
+ * `@source` paths so they still resolve from where the author wrote them.
+ */
+const readUserCss = async (
+  file: string | null,
+  outputDir: string
+): Promise<string> => {
+  const css = await readOptional(file);
+  return file
+    ? rebaseSourceDirectives(css, { from: file, to: outputDir })
+    : css;
+};
+
 /** Heuristically detect whether the project uses React islands. */
 export const detectNeedsReact = async (root: string): Promise<boolean> => {
   const matches = await glob(["**/*.{tsx,jsx}"], {
@@ -1169,7 +1202,11 @@ const resolveOgSite = (config: ResolvedConfig): string | undefined => {
     : undefined;
 };
 
-/** The OG card's subtitle: `seo.og.description` (`false` omits it) over the site description. */
+/**
+ * The OG card's site-wide subtitle: `seo.og.description` (`false` omits it)
+ * over the site description. The generated endpoint prefers a page's own
+ * description and falls back to this.
+ */
 const resolveOgDescription = (config: ResolvedConfig): string | undefined => {
   const configured = config.seo.og.description;
   if (configured === false) {
@@ -1291,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),
@@ -1390,6 +1428,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
+      description: route.description ?? null,
       draft: route.draft,
       editUrl: route.editUrl ?? editUrlFor(route.sourcePath),
       entryId: route.entryId,
@@ -1472,16 +1511,36 @@ const planMcp = (
   };
 };
 
-/** Write the MCP data snapshot, server endpoint, and discovery documents. */
-const writeMcpFiles = async (
+/** A pass's runtime data modules, published together once every writer ran. */
+type RuntimeModules = Map<RuntimeModuleId, string>;
+
+/**
+ * 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 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>
+  write: (path: string, content: string) => Promise<boolean>,
+  data: McpData | null
 ): Promise<void> => {
-  if (!plan.enabled) {
+  if (!(plan.enabled && data)) {
     return;
   }
-  const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -1490,13 +1549,9 @@ const writeMcpFiles = async (
     version: data.version,
   };
   await Promise.all([
-    write(
-      join(plan.srcDir, "generated", "mcp-data.json"),
-      `${JSON.stringify(data)}\n`
-    ),
     write(
       join(plan.srcDir, "pages", mcpPageFile(plan.route)),
-      mcpEndpointTemplate(plan.route)
+      mcpEndpointTemplate()
     ),
     write(
       join(plan.dir, "discovery.ts"),
@@ -1509,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
@@ -1605,7 +1783,8 @@ const proxyAllowlistWarnings = (
 const writeAskFiles = async (
   project: BlumeProject,
   srcDir: string,
-  write: (path: string, content: string) => Promise<boolean>
+  write: (path: string, content: string) => Promise<boolean>,
+  modules: RuntimeModules
 ): Promise<void> => {
   const { ask } = project.config.ai;
   if (!(ask?.enabled && !ask.endpoint)) {
@@ -1613,10 +1792,7 @@ const writeAskFiles = async (
   }
   const grounded = ask.provider !== "inkeep";
   if (grounded) {
-    await write(
-      join(srcDir, "generated", "ask-data.json"),
-      `${JSON.stringify(await buildAskData(project))}\n`
-    );
+    modules.set("blume:ask-data", JSON.stringify(await buildAskData(project)));
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
@@ -1629,10 +1805,13 @@ const writeAskFiles = async (
 
 /**
  * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
- * static builds emit `dist/404.html`. 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 copy.
+ * 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 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>,
@@ -1643,7 +1822,11 @@ const writeNotFoundPage = async (
   if (routeIsTaken(pages, contentPages, "/404")) {
     return;
   }
-  await write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate());
+  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()),
+  ]);
 };
 
 /**
@@ -1733,13 +1916,12 @@ export const generateRuntime = async (
   assertFontFilesExist(project);
   const out = context.outDir;
   const srcDir = join(out, "src");
+  const generatedDir = join(srcDir, "generated");
   const askPath = join(srcDir, "generated", "Ask.astro");
-  const dataPath = join(srcDir, "generated", "data.json");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
   const examplesThemePath = join(srcDir, "generated", "examples.css");
-  const openapiPath = join(srcDir, "generated", "openapi.json");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -1748,6 +1930,11 @@ export const generateRuntime = async (
     written.add(normalize(path));
     return writeIfChanged(path, content);
   };
+  // The data snapshots the generated pages import (`blume:data`, the search
+  // index, …) are collected here and published in memory at the end of the
+  // pass — see `runtime-modules.ts`. An id a feature leaves unset is
+  // unpublished, the in-memory counterpart of `pruneOrphans`.
+  const modules: RuntimeModules = new Map();
 
   const depsLinkWarning = await ensureDepsLink(out);
 
@@ -1776,8 +1963,8 @@ export const generateRuntime = async (
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
     detectUsesMath(context.root, staged.values()),
-    readOptional(context.themeFile),
-    readOptional(examplesCssFile(context.root, config)),
+    readUserCss(context.themeFile, generatedDir),
+    readUserCss(examplesCssFile(context.root, config), generatedDir),
     loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
@@ -1827,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.
@@ -1870,14 +2062,12 @@ export const generateRuntime = async (
           contentRoot: docsCollection.base,
           contentRoutes: markdownRoutePaths(project),
           context,
-          dataPath,
           examplesPath,
           examplesThemePath,
           integrationBridge,
           needsReact,
           needsSvelte,
           needsVue,
-          openapiPath,
           pages,
           reactCompilerPath,
           searchClientPath,
@@ -1925,13 +2115,16 @@ export const generateRuntime = async (
         exampleMapTemplate(exampleDiscovery.examples, config.basePath)
       ),
       // The isolated Tailwind entry for `<Component />` preview frames: only
-      // example files (and the project sources they import) are scanned, so
-      // the docs theme never reaches a preview.
+      // the project (and an out-of-root examples directory) is scanned, so the
+      // docs theme never reaches a preview. Anything further afield — a sibling
+      // package the examples import — is the user's `@source` in examples.css.
       write(
         examplesThemePath,
         examplesEntryTemplate({
           configTokens: buildThemeCss(config.theme),
-          sources: [`${context.root}/**/*.{astro,jsx,svelte,ts,tsx,vue}`],
+          sources: exampleScanRoots(context.root, exampleDiscovery.dir).map(
+            (dir) => `${dir}/${EXAMPLE_SCAN_GLOB}`
+          ),
           userCss: userExamplesCss,
         })
       ),
@@ -1986,8 +2179,9 @@ export const generateRuntime = async (
         )
       )
     ),
-    writeAskFiles(project, srcDir, write),
-    writeMcpFiles(project, mcp, write),
+    writeAskFiles(project, srcDir, write, modules),
+    writeMcpFiles(mcp, write, agentData),
+    writeApiFiles(project, api, write, agentData, mcp),
     playgroundProxy.enabled
       ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
       : Promise.resolve(false),
@@ -1996,7 +2190,14 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes, projectOgFonts(project), changelogIndex)
+      ogEndpointTemplate(
+        ogRoutes,
+        {
+          ...projectOgFonts(project),
+          pageDescriptions: config.seo.og.description !== false,
+        },
+        changelogIndex
+      )
     );
   }
 
@@ -2034,10 +2235,7 @@ export const generateRuntime = async (
   // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
-    await write(
-      join(srcDir, "generated", "search.json"),
-      `${JSON.stringify(documents)}\n`
-    );
+    modules.set("blume:search-index", JSON.stringify(documents));
     await write(
       join(srcDir, "pages", "blume-search.json.ts"),
       searchEndpointTemplate()
@@ -2061,15 +2259,13 @@ export const generateRuntime = async (
   );
 
   const rawMarkdown = await buildRawMarkdown(project);
+  modules.set("blume:raw-markdown", JSON.stringify(rawMarkdown));
   // The originals behind the rewritten `/blume-assets/content/…` references in
   // the agent-facing Markdown, plus the endpoint that serves them (and the
   // remote-source assets materialized under `.blume/public/blume-assets`).
   const contentAssets = await collectContentAssets(project);
+  modules.set("blume:content-assets", JSON.stringify(contentAssets));
   await Promise.all([
-    write(
-      join(srcDir, "generated", "raw-markdown.json"),
-      `${JSON.stringify(rawMarkdown)}\n`
-    ),
     write(
       join(srcDir, "pages", "[...slug].md.ts"),
       rawMarkdownEndpointTemplate("md")
@@ -2078,10 +2274,6 @@ export const generateRuntime = async (
       join(srcDir, "pages", "[...slug].mdx.ts"),
       rawMarkdownEndpointTemplate("mdx")
     ),
-    write(
-      join(srcDir, "generated", "content-assets.json"),
-      `${JSON.stringify(contentAssets)}\n`
-    ),
     write(
       join(srcDir, "pages", "blume-assets", "[...asset].ts"),
       contentAssetsEndpointTemplate(
@@ -2097,16 +2289,11 @@ export const generateRuntime = async (
     const feedXml = Object.fromEntries(
       feeds.map((feed) => [feed.type, renderRssFeed(feed)])
     );
-    await Promise.all([
-      write(
-        join(srcDir, "generated", "rss.json"),
-        `${JSON.stringify(feedXml)}\n`
-      ),
-      write(
-        join(srcDir, "pages", "[section]", "rss.xml.ts"),
-        rssEndpointTemplate()
-      ),
-    ]);
+    modules.set("blume:rss", JSON.stringify(feedXml));
+    await write(
+      join(srcDir, "pages", "[section]", "rss.xml.ts"),
+      rssEndpointTemplate()
+    );
   }
 
   // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
@@ -2181,16 +2368,16 @@ export const generateRuntime = async (
     );
   }
 
-  // `openapi.json` (the `blume:openapi` alias) is always written — even as `{}`
-  // — so the alias resolves whether or not a reference is enabled; the specs
-  // were parsed during the scan, so this is just serialization.
+  // `blume:openapi` is always published — even as `{}` — so the import resolves
+  // whether or not a reference is enabled; the specs were parsed during the
+  // scan, so this is just serialization. `blume:data` is the page data every
+  // layout reads. Neither is "structural" for Astro; publishing hot-reloads.
+  modules.set("blume:data", buildRuntimeData(project));
+  modules.set("blume:openapi", JSON.stringify(openApiData));
   // These write to distinct trees and never read one another, so they batch.
-  // `data.json`/`openapi.json` and the manifest are not "structural" for Astro;
-  // they hot-reload. `writeStagedContent` owns the `.blume/content` tree (its
-  // own pruning), outside `.blume/src`, so a removed remote entry doesn't linger.
+  // `writeStagedContent` owns the `.blume/content` tree (its own pruning),
+  // outside `.blume/src`, so a removed remote entry doesn't linger.
   await Promise.all([
-    write(join(srcDir, "generated", "data.json"), buildRuntimeData(project)),
-    write(openapiPath, `${JSON.stringify(openApiData)}\n`),
     write(
       join(out, "blume.manifest.json"),
       `${JSON.stringify(project.manifest, null, 2)}\n`
@@ -2202,5 +2389,10 @@ export const generateRuntime = async (
   // endpoint left behind after the feature was switched off.
   await pruneOrphans(srcDir, written);
 
+  // Publish last, once every page that imports a module is on disk: a live
+  // dev server invalidates the changed modules and reloads the browser against
+  // the finished tree, never a half-written one.
+  publishRuntimeModules(modules);
+
   return { structuralChange: structural.some(Boolean), warnings };
 };

package/src/astro/index.ts

@@ -5,3 +5,10 @@ export { withIncludeRefresh } from "./include-refresh.ts";
 export type { GenerateResult } from "./generate.ts";
 export { blumeIntegration } from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
+export {
+  publishRuntimeModules,
+  readRuntimeModule,
+  RUNTIME_MODULE_FILES,
+  runtimeModulesPlugin,
+} from "./runtime-modules.ts";
+export type { RuntimeModuleId } from "./runtime-modules.ts";

package/src/astro/markdown-negotiation.ts

@@ -29,7 +29,7 @@ const parseAccept = (accept: string): AcceptEntry[] =>
 
 /**
  * Whether the client explicitly prefers Markdown over HTML. Browsers never send
- * `text/markdown`, so an ordinary page request (`text/html`, `*​/*`) is false.
+ * `text/markdown`, so an ordinary page request (`text/html` or the catch-all wildcard) is false.
  */
 export const prefersMarkdown = (accept: string | null | undefined): boolean => {
   if (!accept) {