blume 2.0.2 → 2.1.0

package/src/reference/scalar.ts

@@ -2,7 +2,13 @@ import { z } from "zod";
 
 import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
-import { hasSources, missingSourcesIssue } from "./options.ts";
+import {
+  hasSources,
+  missingSourcesIssue,
+  overlaysHaveSpec,
+  overlaysNeedSpecIssue,
+  overlaysSchema,
+} from "./options.ts";
 
 /**
  * What the generated Scalar page imports. Declared on every `scalar()`
@@ -22,6 +28,11 @@ export const scalarSourceSchema = z.strictObject({
   label: z.string().optional(),
   /** Emit noindex metadata and omit the page from the sitemap. */
   noindex: z.boolean().default(false),
+  /**
+   * OpenAPI Overlay documents applied in order to the document before it's
+   * embedded (inlined, so a remote spec with overlays is fetched at build).
+   */
+  overlays: overlaysSchema,
   /** Per-source route; defaults to the adapter's `route` (or a derived path). */
   route: z.string().optional(),
   /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -34,6 +45,8 @@ export interface ScalarSourceOptions {
   label?: string;
   /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
   noindex?: boolean;
+  /** OpenAPI Overlay documents applied in order to the document before it's embedded. */
+  overlays?: string[];
   /** Per-source route; defaults to the adapter's `route` (or a derived path). */
   route?: string;
   /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -55,6 +68,8 @@ export type ResolvedScalarOptions = {
 
 /** The options {@link scalar} maps itself. */
 export interface ScalarNamedOptions {
+  /** OpenAPI Overlay documents for `spec`; with `sources`, each takes its own. */
+  overlays?: string[];
   /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
   /** One or more documents; each renders on its own route by default. */
@@ -87,6 +102,8 @@ export type ScalarOptions = ScalarNamedOptions & {
  */
 export const scalarOptionsSchema = z
   .object({
+    /** Overlays for the `spec` shorthand. */
+    overlays: z.array(z.string()).optional(),
     /** Where the reference mounts. */
     route: z.string().default("/reference"),
     /** One or more documents; each renders on its own route by default. */
@@ -97,13 +114,21 @@ export const scalarOptionsSchema = z
     theme: z.string().optional(),
   })
   .catchall(z.json())
-  .transform(({ spec, sources, ...options }): ResolvedScalarOptions => ({
-    ...options,
-    sources:
-      spec === undefined
-        ? sources
-        : [scalarSourceSchema.parse({ spec }), ...sources],
-  }))
+  .refine(overlaysHaveSpec, overlaysNeedSpecIssue)
+  .transform(
+    ({ overlays, spec, sources, ...options }): ResolvedScalarOptions => ({
+      ...options,
+      sources:
+        spec === undefined
+          ? sources
+          : [
+              scalarSourceSchema.parse(
+                overlays ? { overlays, spec } : { spec }
+              ),
+              ...sources,
+            ],
+    })
+  )
   .refine(hasSources, missingSourcesIssue("scalar"));
 
 export type ScalarAdapter = AdapterDescriptor<"scalar", ScalarOptions>;

package/src/registry/eject.ts

@@ -3,10 +3,13 @@ import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 
 import { join, relative } from "pathe";
 
+import { OPENAPI_PATH } from "../ai/api/paths.ts";
+import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } 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 { planComponentSlots } from "../astro/component-slots.ts";
 import {
@@ -31,6 +34,11 @@ import {
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPagesIndexTemplate,
+  apiPageTemplate,
+  apiSearchTemplate,
   askComponentTemplate,
   askEndpointTemplate,
   astroConfigTemplate,
@@ -46,6 +54,8 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
   playgroundProxyTemplate,
@@ -53,6 +63,7 @@ import {
   rssEndpointTemplate,
   runtimeDependencies,
   runtimeTsconfigTemplate,
+  consentClientTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
@@ -68,6 +79,7 @@ import {
 } from "../core/sources/collection.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { resolveOgFonts } from "../og/derive.ts";
 import type { OpenApiData } from "../openapi/model.ts";
 import {
   hasScalarReferences,
@@ -80,6 +92,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
+import { fontLocaleCodes } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
@@ -150,9 +163,12 @@ const askFiles = async (
   const files = [
     {
       content: askEndpointTemplate(backend, {
+        captcha: assistant.captcha,
         cors: assistant.cors,
         instructions: assistant.instructions,
+        rateLimit: project.config.rateLimit,
         retrieval: assistant.retrieval,
+        tools: assistant.tools ?? backend.toolsByDefault,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
@@ -231,28 +247,43 @@ const playgroundProxyFiles = (
   needsPlaygroundProxy(config)
     ? [
         {
-          content: playgroundProxyTemplate(specOrigins(openApiData)),
+          content: playgroundProxyTemplate(
+            specOrigins(openApiData),
+            config.rateLimit
+          ),
           path: join(srcDir, PLAYGROUND_PROXY_ENTRY),
         },
       ]
     : [];
 
 /**
- * The MCP data snapshot, server endpoint, and `.well-known` discovery
- * documents, mirroring `writeMcpFiles` in generate.ts. Empty when the server
- * is disabled or its route is already owned by a page.
+ * The agent data snapshot (`blume:mcp-data`) behind the MCP server and the
+ * JSON docs API, mirroring `publishAgentData` in generate.ts: built when
+ * either is on, null when neither needs it.
+ */
+const ejectAgentData = async (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): Promise<McpData | null> =>
+  hostsMcp(project, userPages) || project.config.agents.api
+    ? await buildMcpData(project)
+    : null;
+
+/**
+ * The MCP server endpoint and `.well-known` discovery documents, mirroring
+ * `writeMcpFiles` in generate.ts. Empty when the server is disabled or its
+ * route is already owned by a page.
  */
-const mcpFiles = async (
+const mcpFiles = (
   project: BlumeProject,
   userPages: { pattern: string }[],
   srcDir: string,
-  genDir: string
-): Promise<{ content: string; path: string }[]> => {
-  if (!hostsMcp(project, userPages)) {
+  data: McpData | null
+): { content: string; path: string }[] => {
+  if (!(data && hostsMcp(project, userPages))) {
     return [];
   }
   const { route } = project.config.agents.mcp;
-  const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -261,10 +292,6 @@ const mcpFiles = async (
     version: data.version,
   };
   return [
-    {
-      content: `${JSON.stringify(data)}\n`,
-      path: join(genDir, "mcp-data.json"),
-    },
     {
       content: mcpEndpointTemplate(),
       path: join(srcDir, "pages", mcpPageFile(route)),
@@ -280,6 +307,87 @@ const mcpFiles = async (
   ];
 };
 
+/**
+ * The JSON docs API, mirroring `planApi` and `writeApiFiles` in generate.ts:
+ * the prerendered page index, per-page documents, and navigation; on server
+ * output the search endpoint and, unless a user page or a content page already
+ * lives under `/api/`, the JSON 404 catch-all; and `/openapi.json`, unless a
+ * `public/openapi.json` or a page owns that route. The ejected `llms.txt`,
+ * homepage `Link` header, and 404 page advertise these routes, so the ejected
+ * app serves them. Empty when `agents.api` is off.
+ */
+const apiFiles = (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  root: string,
+  srcDir: string,
+  data: McpData | null
+): { content: string; path: string }[] => {
+  const { config } = project;
+  if (!(data && config.agents.api)) {
+    return [];
+  }
+  const server = config.deployment.options.output === "server";
+  const apiDir = join(srcDir, "pages", "api");
+  const files = [
+    {
+      content: apiPagesIndexTemplate(),
+      path: join(apiDir, "docs", "pages.json.ts"),
+    },
+    {
+      content: apiPageTemplate(),
+      path: join(apiDir, "docs", "pages", "[...route].json.ts"),
+    },
+    {
+      content: apiNavigationTemplate(),
+      path: join(apiDir, "docs", "navigation.json.ts"),
+    },
+  ];
+  if (server) {
+    files.push({
+      content: apiSearchTemplate(),
+      path: join(apiDir, "docs", "search.ts"),
+    });
+  }
+  const apiOwned =
+    userPages.some((page) => page.pattern.startsWith("/api/[")) ||
+    project.graph.pages.some(
+      (page) => page.route === "/api" || page.route.startsWith("/api/")
+    );
+  if (server && !apiOwned) {
+    files.push({
+      content: apiNotFoundTemplate({ base: data.base, site: data.site }),
+      path: join(apiDir, "[...path].ts"),
+    });
+  }
+  if (
+    !(
+      routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) ||
+      existsSync(join(root, "public", "openapi.json"))
+    )
+  ) {
+    files.push({
+      content: staticJsonEndpointTemplate(
+        buildApiSpec({
+          agentReadability: config.agents.agentReadability,
+          base: data.base,
+          description: config.description,
+          llmsTxt: config.agents.llmsTxt.enabled,
+          mcpRoute: hostsMcp(project, userPages)
+            ? config.agents.mcp.route
+            : null,
+          name: config.title,
+          search: server,
+          site: data.site,
+          version: data.version,
+        })
+      ),
+      path: join(srcDir, "pages", "openapi.json.ts"),
+    });
+  }
+  return files;
+};
+
 /**
  * The `/changelog` index page, mirroring `shouldGenerateChangelog` in
  * generate.ts: emitted when `type: changelog` entries or a release-backed
@@ -346,6 +454,25 @@ const contentAssetFiles = async (
   ];
 };
 
+/**
+ * The partial → including-pages map with every path relative to the project
+ * root, like every other path in the ejected app, so it holds in any checkout.
+ * Its readers (`includeHmrPlugin`, `withIncludeRefresh`) resolve each path
+ * against the app's root, which after eject is the project itself.
+ */
+const portableIncludeGraph = (
+  project: BlumeProject,
+  root: string
+): Record<string, string[]> =>
+  Object.fromEntries(
+    Object.entries(buildIncludeGraph(project.graph.pages)).map(
+      ([partial, includers]) => [
+        toPosix(relative(root, partial)),
+        includers.map((page) => toPosix(relative(root, page))),
+      ]
+    )
+  );
+
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
 /**
  * Read a user stylesheet that eject inlines into a generated entry under
@@ -547,6 +674,7 @@ export const eject = async (
       content: astroConfigTemplate({
         askPath: "./src/generated/Ask.astro",
         config,
+        consentClientPath: "./src/generated/consent-client.ts",
         contentRoot: relContext.contentRoot,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
@@ -655,7 +783,7 @@ export const eject = async (
       // hot update's read would silently no-op and partial edits would serve
       // stale pages. A snapshot like the rest of `src/generated`: the ejected
       // app owns (and may regenerate or prune) it.
-      content: `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`,
+      content: `${JSON.stringify(portableIncludeGraph(project, root))}\n`,
       path: join(genDir, "includes.json"),
     },
     {
@@ -684,36 +812,74 @@ export const eject = async (
   });
 
   if (config.seo.og.enabled) {
+    // The default script fallbacks ride along (Google family names, nothing
+    // machine-specific), so a non-Latin card still renders after eject. An
+    // explicit seo.og.fonts replaces them, and isn't carried over.
+    const { fallbacks, families } = resolveOgFonts(
+      {
+        locales: fontLocaleCodes(config.i18n),
+        ogFonts: config.seo.og.fonts,
+        themeFonts: config.theme.fonts,
+        themeFontsConfigured: false,
+      },
+      root
+    );
     files.push({
       content: ogEndpointTemplate(
         customOgRoutes(pages, config.title, config.seo.og.titles),
-        { pageDescriptions: config.seo.og.description !== false },
+        {
+          fallbacks,
+          families,
+          pageDescriptions: config.seo.og.description !== false,
+        },
         changelog.length > 0
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }
 
-  // The hosted MCP server and the playground's built-in proxy, mirrored from
-  // the generated runtime (`[]` when each is off).
+  // The hosted MCP server, the JSON docs API, and the playground's built-in
+  // proxy, mirrored from the generated runtime (`[]` when each is off). The
+  // server and the API share one agent data snapshot.
+  const agentData = await ejectAgentData(project, pages);
+  if (agentData) {
+    files.push({
+      content: `${JSON.stringify(agentData)}\n`,
+      path: join(genDir, "mcp-data.json"),
+    });
+  }
   files.push(
-    ...(await mcpFiles(project, pages, srcDir, genDir)),
+    ...mcpFiles(project, pages, srcDir, agentData),
+    ...apiFiles(project, pages, root, srcDir, agentData),
     ...changelog,
     ...playgroundProxyFiles(config, openApiData, srcDir)
   );
 
-  // Default 404 page, unless the project already owns `/404` (a custom
-  // `pages/404.astro` or a `404.md` content page). The ejected project owns the
-  // file afterwards and can edit or remove it.
+  // Default 404 page and its Markdown (`/404.md`) and JSON (`/404.json`)
+  // twins, mirroring `writeNotFoundPage` in generate.ts: all three are skipped
+  // when the project already owns `/404` (a custom `pages/404.astro` or a
+  // `404.md` content page). The ejected project owns the files afterwards and
+  // can edit or remove them.
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
-    files.push({
-      content: notFoundPageTemplate(),
-      path: join(srcDir, "pages", "404.astro"),
-    });
+    files.push(
+      {
+        content: notFoundPageTemplate(),
+        path: join(srcDir, "pages", "404.astro"),
+      },
+      {
+        content: notFoundMarkdownTemplate(),
+        path: join(srcDir, "pages", "404.md.ts"),
+      },
+      {
+        content: notFoundJsonTemplate(),
+        path: join(srcDir, "pages", "404.json.ts"),
+      }
+    );
   }
 
-  // The client-feature loaders behind the `blume:features` alias, and the
-  // provider-specific client loader behind `blume:search-client`.
+  // The client-feature loaders behind the `blume:features` alias, the
+  // provider-specific client loader behind `blume:search-client`, and the
+  // consent adapter's browser module behind `blume:consent-client`.
   files.push(
     {
       content: featuresTemplate(features),
@@ -722,6 +888,10 @@ export const eject = async (
     {
       content: searchClientTemplate(config),
       path: join(genDir, "search-client.ts"),
+    },
+    {
+      content: consentClientTemplate(config.consent),
+      path: join(genDir, "consent-client.ts"),
     }
   );
 
@@ -742,7 +912,10 @@ export const eject = async (
 
   if (searchAdapter.kind === "mixedbread") {
     files.push({
-      content: mixedbreadSearchEndpointTemplate(searchAdapter.options),
+      content: mixedbreadSearchEndpointTemplate(
+        searchAdapter.options,
+        config.rateLimit
+      ),
       path: join(srcDir, "pages", "api", "search.ts"),
     });
   }

package/src/registry/registry.ts

@@ -262,6 +262,13 @@ export const registry: RegistryItem[] = [
     name: "feedback",
     slot: "Feedback",
   }),
+  layoutComponent({
+    description:
+      "The site footer: a row of links, social icons, the theme toggle, and the Cookie settings link.",
+    file: "SiteFooter.astro",
+    name: "footer",
+    slot: "Footer",
+  }),
   ...CONTENT_COMPONENTS.map(contentComponent),
 ];
 

package/src/search/adapters/version-scope.ts

@@ -0,0 +1,30 @@
+import type { SearchAdapterKind } from "./registry.ts";
+
+/**
+ * Whether each adapter's client can filter results to one docs version. The
+ * source-built indexes (Orama, FlexSearch) store every document's `version`,
+ * and the Algolia and Typesense syncs upload it as a facet their clients
+ * filter on. Pagefind indexes the built HTML with no version metadata, the
+ * Orama Cloud sync uploads no `version`, and the Mixedbread endpoint takes no
+ * filter, so those always search every version. Keyed by every kind so a new
+ * adapter has to decide.
+ */
+const SCOPES_VERSIONS = {
+  algolia: true,
+  flexsearch: true,
+  mixedbread: false,
+  none: false,
+  orama: true,
+  "orama-cloud": false,
+  pagefind: false,
+  typesense: true,
+} satisfies Record<SearchAdapterKind, boolean>;
+
+/**
+ * Whether the configured search adapter scopes results to the viewed docs
+ * version. The search dialog offers its "All versions" toggle only when it
+ * does: on the others the toggle would change nothing, and every query
+ * already spans all versions.
+ */
+export const scopesVersions = (kind: SearchAdapterKind): boolean =>
+  SCOPES_VERSIONS[kind];