blume 1.0.2 → 1.0.3

package/src/blume-modules.d.ts

@@ -15,6 +15,12 @@ declare module "blume:search-client" {
   export const createSearch: () => Fn | Promise<Fn>;
 }
 
+declare module "blume:ask" {
+  /** The generated Ask trigger (see `askComponentTemplate`); empty when Ask is off. */
+  const Ask: (props: Record<string, unknown>) => unknown;
+  export default Ask;
+}
+
 declare module "blume:data" {
   /** The generated per-project data snapshot (see `core/data.ts`). */
   // biome-ignore lint/style/useImportType: ambient module must stay a global script

package/src/components/layout/Header.astro

@@ -1,4 +1,6 @@
 ---
+import Ask from "blume:ask";
+import data from "blume:data";
 import { withBase } from "../islands/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
@@ -26,7 +28,14 @@ interface Props {
   navigation: Navigation;
   route: string;
   searchEnabled: boolean;
+  /**
+   * Whether the search modal offers an "Ask AI" hand-off. Defaults to whether
+   * Ask AI is configured, so no page has to pass it; a layout can still opt a
+   * shell out explicitly.
+   */
   askEnabled?: boolean;
+  /** Localized Ask AI strings for the active locale. */
+  askStrings?: UIStrings["ask"];
   // The mobile menu button toggles the docs sidebar drawer; custom pages
   // without a sidebar (e.g. a landing page) pass `false` to hide it.
   hasSidebar?: boolean;
@@ -57,7 +66,11 @@ const {
   navigation,
   route,
   searchEnabled,
-  askEnabled = false,
+  // `config.ask` is null whenever Ask AI is off, so the header is the one place
+  // that has to know — the Ask trigger below and the search modal's hand-off to
+  // it both switch on this, and every page gets both for free.
+  askEnabled = Boolean(data.config.ask),
+  askStrings,
   hasSidebar = true,
   hasDrawer = true,
   searchStrings,
@@ -208,7 +221,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       <span class="inline-flex dark:hidden"><Icon name="sun" size={18} /></span>
       <span class="hidden dark:inline-flex"><Icon name="moon" size={18} /></span>
     </button>
-    <slot name="ask" />
+    {askEnabled && <Ask strings={askStrings} />}
   </div>
 </header>
 <script is:inline set:html={clickScript} />

package/src/components/layout/PageLayout.astro

@@ -58,6 +58,11 @@ interface Props {
   themeMode: "system" | "light" | "dark";
   fontCssVars?: string[];
   searchEnabled: boolean;
+  /**
+   * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
+   * AI is configured, so a custom page gets the same trigger the docs pages have
+   * without wiring anything up.
+   */
   askEnabled?: boolean;
   /**
    * Absolute site URL (`data.config.site`). When set, `canonical` and the
@@ -229,6 +234,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <Banner banner={banner} strings={strings.banner} />
     <Header
       askEnabled={askEnabled}
+      askStrings={strings.ask}
       hasSidebar={false}
       localeSwitch={localeSwitch}
       logo={logo}
@@ -240,9 +246,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       searchStrings={strings.search}
       site={site}
       switcherStrings={strings.languageSwitcher}
-    >
-      <slot name="ask" slot="ask" />
-    </Header>
+    />
     <main id="blume-content"><slot /></main>
     <slot name="footer" />
     {

package/src/components/layout/ReferenceLayout.astro

@@ -107,6 +107,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     >
     <Banner banner={banner} strings={strings.banner} />
     <Header
+      askStrings={strings.ask}
       hasDrawer={false}
       hasSidebar={false}
       logo={logo}

package/src/components/layout/RootLayout.astro

@@ -100,6 +100,10 @@ interface Props {
   x?: { creator?: string; handle?: string };
   canonical?: string | null;
   editUrl?: string | null;
+  /**
+   * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
+   * AI is configured, so pages never wire the trigger up themselves.
+   */
   askEnabled?: boolean;
   /** Show the "Was this page helpful?" rating below the content. */
   feedback?: boolean;
@@ -430,6 +434,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <Banner banner={banner} strings={strings.banner} />
     <HeaderSlot
       askEnabled={askEnabled}
+      askStrings={strings.ask}
       layout={layout}
       localeSwitch={localeSwitch}
       logo={logo}
@@ -441,9 +446,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       searchStrings={strings.search}
       site={site}
       switcherStrings={strings.languageSwitcher}
-    >
-      <slot name="ask" slot="ask" />
-    </HeaderSlot>
+    />
     <div
       class:list={["mx-auto grid grid-cols-1 items-start", gridClass]}
       data-blume-doc-grid

package/src/core/config-input.ts

@@ -525,7 +525,22 @@ export interface LlmsTxtConfig {
   openapi?: boolean;
 }
 
-/** AI-facing features: the Ask AI assistant and an `llms.txt` manifest. */
+/** Expose the docs as an MCP server for connecting agents. */
+export interface McpConfig {
+  /** Turn the MCP server on. Defaults to `false`. */
+  enabled?: boolean;
+  /** Optional system hint passed to connecting agents. */
+  instructions?: string;
+  /** Server name shown to clients; defaults to the site title. */
+  name?: string;
+  /** Route the server mounts at. Defaults to `/mcp`. */
+  route?: string;
+}
+
+/**
+ * AI-facing features: the Ask AI assistant, an `llms.txt` manifest, and the
+ * hosted MCP server.
+ */
 export interface AiConfig {
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
@@ -553,6 +568,8 @@ export interface AiConfig {
    * ```
    */
   markdownComponents?: Record<string, ComponentMarkdown>;
+  /** Expose the docs as an MCP server for agents. */
+  mcp?: McpConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -586,22 +603,6 @@ export interface AnalyticsConfig {
   vercel?: boolean;
 }
 
-// ---------------------------------------------------------------------------
-// MCP
-// ---------------------------------------------------------------------------
-
-/** Expose the docs as an MCP server for connecting agents. */
-export interface McpConfig {
-  /** Turn the MCP server on. Defaults to `false`. */
-  enabled?: boolean;
-  /** Optional system hint passed to connecting agents. */
-  instructions?: string;
-  /** Server name shown to clients; defaults to the site title. */
-  name?: string;
-  /** Route the server mounts at. Defaults to `/mcp`. */
-  route?: string;
-}
-
 // ---------------------------------------------------------------------------
 // i18n
 // ---------------------------------------------------------------------------
@@ -979,8 +980,6 @@ export interface BlumeConfig {
   logo?: LogoConfig;
   /** Markdown / MDX rendering behavior. */
   markdown?: MarkdownConfig;
-  /** Expose the docs as an MCP server for agents. */
-  mcp?: McpConfig;
   /** Header, sidebar, tabs, and switchers. */
   navigation?: NavigationConfig;
   /** Native OpenAPI reference. */

package/src/core/config.ts

@@ -74,9 +74,9 @@ import type { Diagnostic } from "./types.ts";
  *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
  *   credential block.
  * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model), `llmsTxt`
- *   (emit `llms.txt`), and `markdownComponents` (Markdown serializers for
- *   custom components in agent-facing output).
- * - `mcp` — expose the docs as an MCP server for connecting agents.
+ *   (emit `llms.txt`), `mcp` (expose the docs as an MCP server for connecting
+ *   agents), and `markdownComponents` (Markdown serializers for custom
+ *   components in agent-facing output).
  *
  * **SEO, feeds & analytics**
  * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`

package/src/core/schema.ts

@@ -550,6 +550,19 @@ export const askAiProviders = [
   "openai-compatible",
 ] as const;
 
+const mcpConfigSchema = z.strictObject({
+  enabled: z.boolean().default(false),
+  /** Optional system hint passed to connecting agents. */
+  instructions: z.string().optional(),
+  /** Server name shown to clients; defaults to the site title. */
+  name: z.string().optional(),
+  /**
+   * Normalized like `openapi.route`: a slash-less value would otherwise be
+   * string-concatenated onto the site origin (`https://acme.comdocs-mcp`).
+   */
+  route: z.string().default("/mcp").transform(normalizeRoute),
+});
+
 const aiConfigSchema = z.strictObject({
   ask: z
     .strictObject({
@@ -620,6 +633,8 @@ const aiConfigSchema = z.strictObject({
       })
     )
     .default({}),
+  /** Expose the docs as an MCP server for connecting agents. */
+  mcp: mcpConfigSchema.default({}),
 });
 
 /**
@@ -679,19 +694,6 @@ const exportConfigSchema = z
     typeof value === "boolean" ? { epub: value, pdf: value } : value
   );
 
-const mcpConfigSchema = z.strictObject({
-  enabled: z.boolean().default(false),
-  /** Optional system hint passed to connecting agents. */
-  instructions: z.string().optional(),
-  /** Server name shown to clients; defaults to the site title. */
-  name: z.string().optional(),
-  /**
-   * Normalized like `openapi.route`: a slash-less value would otherwise be
-   * string-concatenated onto the site origin (`https://acme.comdocs-mcp`).
-   */
-  route: z.string().default("/mcp").transform(normalizeRoute),
-});
-
 /** A configured locale: ISO-ish code plus display metadata for the switcher. */
 const localeSchema = z.strictObject({
   code: z.string().min(1),
@@ -1088,7 +1090,6 @@ export const blumeConfigSchema = z.strictObject({
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),
-  mcp: mcpConfigSchema.default({}),
   navigation: navigationConfigSchema.default({}),
   openapi: openapiConfigSchema.default({}),
   react: reactConfigSchema.default({}),

package/src/core/server-features.ts

@@ -11,7 +11,7 @@ export const serverFeatures = (config: ResolvedConfig): string[] => {
     features.push("Ask AI");
   }
   // The hosted MCP server is a live JSON-RPC endpoint, so it needs a runtime.
-  if (config.mcp.enabled) {
+  if (config.ai.mcp.enabled) {
     features.push("MCP server");
   }
   // Mixedbread (and any future provider) that proxies queries through a secret

package/src/deploy/adapter-output.ts

@@ -83,7 +83,17 @@ export const surfaceAdapterOutput = async (
   }
   await mkdir(dirname(to), { recursive: true });
   await rm(to, { force: true, recursive: true });
-  await cp(from, to, { recursive: true });
+  // `verbatimSymlinks` keeps each symlink's target text as written. Without it,
+  // `cp` resolves every relative target against the *source*, rewriting it to an
+  // absolute path under `.blume` — which this function then deletes. Adapters
+  // that trace dependencies into their function bundle link one package to
+  // another that way (under an isolated linker — Bun's `isolated` mode, pnpm —
+  // that is every external dependency the function imports), so the resolved
+  // links leave the deployed function dying on its first external import with
+  // ERR_MODULE_NOT_FOUND. Verbatim, the links stay relative and internal to the
+  // bundle, surviving both this move and the platform's own (Vercel mounts the
+  // bundle at `/var/task`).
+  await cp(from, to, { recursive: true, verbatimSymlinks: true });
   await rm(from, { force: true, recursive: true });
   // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
   // never the moved sub-path — the platform's own state (`.vercel/project.json`,

package/src/registry/eject.ts

@@ -20,6 +20,7 @@ import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
   askEndpointTemplate,
+  askComponentTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
@@ -135,8 +136,8 @@ const hostsMcp = (
   project: BlumeProject,
   userPages: { pattern: string }[]
 ): boolean =>
-  project.config.mcp.enabled &&
-  !routeIsTaken(userPages, project.graph.pages, project.config.mcp.route);
+  project.config.ai.mcp.enabled &&
+  !routeIsTaken(userPages, project.graph.pages, project.config.ai.mcp.route);
 
 /**
  * The `.well-known` MCP discovery routes, injected as prerendered pages
@@ -174,7 +175,7 @@ const mcpFiles = async (
   if (!hostsMcp(project, userPages)) {
     return [];
   }
-  const { route } = project.config.mcp;
+  const { route } = project.config.ai.mcp;
   const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
@@ -356,6 +357,7 @@ export const eject = async (
   }[] = [
     {
       content: astroConfigTemplate({
+        askPath: "./src/generated/Ask.astro",
         config,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
@@ -390,7 +392,6 @@ export const eject = async (
     },
     {
       content: catchAllPageTemplate({
-        askEnabled,
         exportEpub,
         exportPdf,
         mathEnabled: usesMath,
@@ -441,6 +442,12 @@ export const eject = async (
       path: join(genDir, "app.css"),
     },
     { content: buildRuntimeData(project), path: join(genDir, "data.json") },
+    // The header's Ask trigger behind the `blume:ask` alias. Always written — it
+    // renders nothing when Ask is off — so the alias always resolves.
+    {
+      content: askComponentTemplate(askEnabled),
+      path: join(genDir, "Ask.astro"),
+    },
     {
       content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
       path: join(genDir, "openapi.json"),
@@ -475,7 +482,6 @@ export const eject = async (
   files.push(
     ...(await mcpFiles(project, pages, srcDir, genDir)),
     ...changelogFiles(project, pages, srcDir, {
-      askEnabled,
       exportEpub,
       exportPdf,
       needsReact,