blume 1.0.1 → 1.0.3

package/src/astro/templates.ts

@@ -8,6 +8,7 @@ import type { AskBackend } from "../ai/ask.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
+import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { applyBaseToRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
@@ -221,6 +222,8 @@ export const astroConfigTemplate = (options: {
   needsSvelte?: boolean;
   pages: BlumePageRoute[];
   contentRoutes: string[];
+  /** The generated Ask trigger (`blume:ask`); renders nothing when Ask is off. */
+  askPath: string;
   dataPath: string;
   examplesPath: string;
   /** The example-preview Tailwind entry (`blume:examples-theme`). */
@@ -239,6 +242,7 @@ export const astroConfigTemplate = (options: {
 }): string => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
+    askPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
@@ -424,6 +428,7 @@ export default defineConfig({
     },
     resolve: {
       alias: {
+        "blume:ask": ${JSON.stringify(askPath)},
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
@@ -693,6 +698,42 @@ ${handler}
 `;
 };
 
+/**
+ * Generate `.blume/src/generated/Ask.astro` — the component behind the
+ * `blume:ask` alias that the shared header renders in place of a per-page slot.
+ *
+ * The header can't import the Ask AI island directly: it's a React component, so
+ * the import alone would drag the JSX renderer into the module graph of every
+ * project — including the ones that never enable Ask AI and therefore have no
+ * React integration wired into their generated Astro config (see `needsReact`).
+ * Routing the import through a generated component keeps that dependency behind
+ * the config switch: enabled projects get the island, disabled ones get a
+ * component that renders nothing and imports no React.
+ *
+ * `strings` comes from the header (the active locale's dictionary); the empty-
+ * state suggestions are read straight from the data snapshot, which is why no
+ * page has to pass them.
+ */
+export const askComponentTemplate = (askEnabled: boolean): string =>
+  askEnabled
+    ? `---
+// Generated by Blume. Do not edit.
+import AskAI from "blume/components/islands/AskAI.astro";
+import data from "blume:data";
+
+const { strings } = Astro.props;
+---
+
+<AskAI strings={strings ?? data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />
+`
+    : `---
+// Generated by Blume. Do not edit.
+// Ask AI is off (\`ai.ask.enabled\`), so the header's Ask trigger renders nothing.
+// Deliberately imports no React island, keeping the JSX renderer out of projects
+// that don't need it.
+---
+`;
+
 /** Generate the static search index endpoint (`/blume-search.json`). */
 export const searchEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
@@ -879,10 +920,8 @@ export function GET({ props }) {
 `;
 
 /** The `src/pages` file that serves a route, e.g. `/mcp` -> `mcp.ts`. */
-export const mcpPageFile = (route: string): string => {
-  const clean = route.replace(/^\/+/u, "").replace(/\/+$/u, "");
-  return `${clean}.ts`;
-};
+export const mcpPageFile = (route: string): string =>
+  `${trimChar(route, "/")}.ts`;
 
 /**
  * Generate the hosted MCP server endpoint (e.g. `.blume/src/pages/mcp.ts`). A
@@ -891,7 +930,7 @@ export const mcpPageFile = (route: string): string => {
  * the docs over Streamable HTTP.
  */
 export const mcpEndpointTemplate = (route: string): string => {
-  const clean = route.replace(/^\/+/u, "").replace(/\/+$/u, "");
+  const clean = trimChar(route, "/");
   const up = "../".repeat(clean.split("/").length);
   return `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
@@ -1070,19 +1109,12 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 `;
 
 export const catchAllPageTemplate = (options: {
-  askEnabled: boolean;
   exportEpub: boolean;
   exportPdf: boolean;
   mathEnabled: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
   needsReact: boolean;
 }): string => {
-  const askImport = options.askEnabled
-    ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
-    : "";
-  const askSlot = options.askEnabled
-    ? '\n  <AskAI slot="ask" strings={ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
-    : "";
   const mathImport = options.mathEnabled
     ? 'import Math from "blume/components/content/Math.astro";\n'
     : "";
@@ -1098,7 +1130,6 @@ import { getEntry, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
-${askImport}
 import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
 import AutoTypeTable from "blume/components/content/AutoTypeTable.astro";
@@ -1335,7 +1366,6 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   canonical={canonical}
   editUrl={editUrl}
   feedback={data.config.feedback}
-  askEnabled={${options.askEnabled}}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
   feeds={data.feeds}
@@ -1345,7 +1375,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   lastModified={lastModified}
   noindex={seo.noindex}
   structuredDataEnabled={data.config.structuredData}
->${askSlot}
+>
   <h1>{title}</h1>
   {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
   <Content components={components} />
@@ -1360,7 +1390,6 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
  * by {@link generateAstroProject} when changelog entries exist.
  */
 export const changelogIndexTemplate = (options: {
-  askEnabled: boolean;
   exportEpub: boolean;
   exportPdf: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
@@ -1368,12 +1397,6 @@ export const changelogIndexTemplate = (options: {
   /** Whether a `staged` collection exists (non-filesystem changelog sources). */
   staged: boolean;
 }): string => {
-  const askImport = options.askEnabled
-    ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
-    : "";
-  const askSlot = options.askEnabled
-    ? '\n  <AskAI slot="ask" strings={data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
-    : "";
   const clientData = options.needsReact
     ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: pageTitle } }}'
     : "";
@@ -1391,7 +1414,7 @@ import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
-${askImport}import data from "../generated/data.json";
+import data from "../generated/data.json";
 
 export const prerender = true;
 
@@ -1560,14 +1583,13 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   ogImage={null}
   x={data.config.x}
   canonical={canonical}
-  askEnabled={${options.askEnabled}}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
   feeds={data.feeds}
   siteUrl={data.config.site}
   noindex={false}
   structuredDataEnabled={data.config.structuredData}
->${askSlot}
+>
   <h1>{changelogTitle}</h1>
   {
     items.length === 0 ? (
@@ -1892,6 +1914,11 @@ export const envTemplate =
   (): string => `/// <reference path="../.astro/types.d.ts" />
 /// <reference types="astro/client" />
 
+declare module "blume:ask" {
+  const Ask: typeof import("blume/components/islands/AskAI.astro").default;
+  export default Ask;
+}
+
 declare module "blume:data" {
   const data: import("blume").BlumeData;
   export default data;

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

@@ -37,7 +37,7 @@ import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import { isUnderPath } from "./nav-utils.ts";
 
@@ -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
@@ -169,10 +174,7 @@ const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
 const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
-const initialThemeScript = themeInitScript(themeMode);
-const bannerScript = banner?.dismissible
-  ? bannerInitScript(banner.key)
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -216,8 +218,12 @@ const bannerScript = banner?.dismissible
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
@@ -228,6 +234,7 @@ const bannerScript = banner?.dismissible
     <Banner banner={banner} strings={strings.banner} />
     <Header
       askEnabled={askEnabled}
+      askStrings={strings.ask}
       hasSidebar={false}
       localeSwitch={localeSwitch}
       logo={logo}
@@ -239,9 +246,7 @@ const bannerScript = banner?.dismissible
       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

@@ -7,6 +7,7 @@ import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
@@ -80,14 +81,7 @@ const {
 
 const strings = ui ?? EN_UI;
 
-// Set the theme before paint so the navbar never flashes the wrong colors
-// (mirrors RootLayout's pre-paint script).
-const initialThemeScript = `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
-
-// Pre-paint: hide a previously-dismissed banner before it flashes in.
-const bannerScript = banner?.dismissible
-  ? `(()=>{if(localStorage.getItem("blume-banner:"+${JSON.stringify(banner.key)}))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -98,8 +92,12 @@ const bannerScript = banner?.dismissible
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
@@ -109,6 +107,7 @@ const bannerScript = banner?.dismissible
     >
     <Banner banner={banner} strings={strings.banner} />
     <Header
+      askStrings={strings.ask}
       hasDrawer={false}
       hasSidebar={false}
       logo={logo}

package/src/components/layout/RootLayout.astro

@@ -23,7 +23,7 @@ import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
@@ -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;
@@ -329,10 +333,7 @@ const structuredDataJson = structuredData
   ? JSON.stringify(structuredData).replaceAll("<", "\\u003c")
   : null;
 
-const initialThemeScript = themeInitScript(themeMode);
-const bannerScript = banner?.dismissible
-  ? bannerInitScript(banner.key)
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -411,8 +412,12 @@ const bannerScript = banner?.dismissible
         />
       )
     }
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body
@@ -429,6 +434,7 @@ const bannerScript = banner?.dismissible
     <Banner banner={banner} strings={strings.banner} />
     <HeaderSlot
       askEnabled={askEnabled}
+      askStrings={strings.ask}
       layout={layout}
       localeSwitch={localeSwitch}
       logo={logo}
@@ -440,9 +446,7 @@ const bannerScript = banner?.dismissible
       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/components/layout/head-scripts.ts

@@ -1,19 +1,29 @@
 /**
  * Pre-paint inline scripts shared by the document layouts (`RootLayout`,
- * `SplashLayout`). They run synchronously in `<head>`, before first paint, so
- * the page never flashes the wrong theme or a since-dismissed banner. Kept in
- * one place so the two layouts can't drift on this timing-critical logic.
+ * `PageLayout`, `ReferenceLayout`). They run synchronously in `<head>`, before
+ * first paint, so the page never flashes the wrong theme or a since-dismissed
+ * banner. Kept in one place so the layouts can't drift on this timing-critical
+ * logic.
+ *
+ * Both are constants, never built by interpolating config into source text: the
+ * values they need ride in as `data-*` attributes on the script tag and are read
+ * back through `document.currentScript`. Baking a config string into JS — even
+ * via `JSON.stringify` — is code construction, and JSON escaping does not cover
+ * a script context (`</script>`, U+2028/U+2029 all survive it). Attributes are
+ * HTML-escaped by Astro, so the value can never be parsed as code.
  */
 
 /**
  * Set `data-theme` from the stored preference (or the configured default, or the
  * OS setting for `"system"`) before the body paints, avoiding a theme flash.
+ *
+ * Reads `data-mode` — `"system" | "light" | "dark"`.
  */
-export const themeInitScript = (
-  themeMode: "system" | "light" | "dark"
-): string =>
-  `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
 
-/** Hide a previously-dismissed banner before it can flash in. */
-export const bannerInitScript = (key: string): string =>
-  `(()=>{if(localStorage.getItem("blume-banner:"+${JSON.stringify(key)}))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;
+/**
+ * Hide a previously-dismissed banner before it can flash in.
+ *
+ * Reads `data-key` — the banner's dismissal key.
+ */
+export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(k&&localStorage.getItem("blume-banner:"+k))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;

package/src/core/base-path.ts

@@ -21,10 +21,10 @@ export const normalizeBasePath = (input?: string): string => {
   if (!input) {
     return "";
   }
-  const trimmed = input
-    .trim()
-    .replaceAll(/^\/+|\/+$/gu, "")
-    .replaceAll(/\/{2,}/gu, "/");
+  // Splitting on "/" and dropping the empty parts trims the edges and collapses
+  // inner runs in one linear pass; the regex spellings of both are quadratic on
+  // a long run of slashes (see `core/trim.ts`).
+  const trimmed = input.trim().split("/").filter(Boolean).join("/");
   return trimmed === "" ? "" : `/${trimmed}`;
 };
 

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/core/trim.ts

@@ -0,0 +1,32 @@
+/**
+ * Single-character trimming, done without regular expressions.
+ *
+ * The obvious spellings — `/^\/+/`, `/\/+$/`, `/^\/+|\/+$/g` — take quadratic
+ * time on a run of the trimmed character, because a failed match at one start
+ * position tells the engine nothing about the next one. Every caller here trims
+ * a value that comes from outside Blume (a configured route, a spec URL, a site
+ * origin), so the slow path is reachable from user input rather than only from
+ * our own literals. These loops are linear and allocation-free.
+ */
+
+/** Drop every leading `char` (`"///a"` -> `"a"` for `"/"`). */
+export const trimStart = (text: string, char: string): string => {
+  let start = 0;
+  while (start < text.length && text[start] === char) {
+    start += 1;
+  }
+  return text.slice(start);
+};
+
+/** Drop every trailing `char` (`"a///"` -> `"a"` for `"/"`). */
+export const trimEnd = (text: string, char: string): string => {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === char) {
+    end -= 1;
+  }
+  return text.slice(0, end);
+};
+
+/** Drop every leading *and* trailing `char` (`"///a///"` -> `"a"`). */
+export const trimChar = (text: string, char: string): string =>
+  trimEnd(trimStart(text, char), char);