blume 1.0.2 → 1.0.4

package/src/ai/agent-readability.ts

@@ -62,10 +62,10 @@ export const buildAgentReadability = (
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
   }
-  if (config.mcp.enabled) {
+  if (config.ai.mcp.enabled) {
     artifacts.mcp = {
       discovery: abs("/.well-known/mcp.json"),
-      url: abs(config.mcp.route),
+      url: abs(config.ai.mcp.route),
     };
   }
   if (config.ai.ask?.enabled) {
@@ -87,7 +87,7 @@ export const buildAgentReadability = (
     artifacts,
     description: config.description,
     generator: version ? `blume@${version}` : undefined,
-    name: config.mcp.name ?? config.title,
+    name: config.ai.mcp.name ?? config.title,
     site,
   };
 

package/src/ai/mcp/data.ts

@@ -88,8 +88,8 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
       route: doc.route,
       title: doc.title,
     })),
-    instructions: config.mcp.instructions,
-    name: config.mcp.name ?? config.title,
+    instructions: config.ai.mcp.instructions,
+    name: config.ai.mcp.name ?? config.title,
     navigation: graph.navigation,
     pages,
     routes,

package/src/astro/component-slots.ts

@@ -31,8 +31,9 @@ export interface ComponentSlotPlan {
 }
 
 const EMPTY_MODULE = `// Generated by Blume. Do not edit.
-export const mdxComponents = {};
-export const layoutOverrides = {};
+import type { ComponentOverride } from "blume/core/define-components.ts";
+export const mdxComponents: Record<string, ComponentOverride> = {};
+export const layoutOverrides: Record<string, ComponentOverride> = {};
 `;
 
 // A user-supplied attribute value interpolated into a generated .astro tag: a

package/src/astro/generate.ts

@@ -37,7 +37,8 @@ import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
-import { hasScalarReferences, referenceTabs } from "../openapi/references.ts";
+import { resolveOgLogo } from "../og/logo.ts";
+import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
@@ -61,6 +62,7 @@ import {
   routeIsTaken,
 } from "./pages.ts";
 import {
+  askComponentTemplate,
   askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
@@ -625,7 +627,56 @@ const writeStagedContent = async (
   }
 };
 
-/** The logo shape the runtime consumes: an inline SVG or image URL(s). */
+interface LogoDimensions {
+  height: number;
+  width: number;
+}
+
+const SVG_ROOT = /<svg\b(?<attributes>[^>]*)>/u;
+const SVG_WIDTH = /\bwidth\s*=\s*["'](?<value>[^"']+)["']/u;
+const SVG_HEIGHT = /\bheight\s*=\s*["'](?<value>[^"']+)["']/u;
+const SVG_LENGTH = /^\s*(?<value>[\d.]+)(?:px)?\s*$/u;
+const SVG_VIEW_BOX =
+  /\bviewBox\s*=\s*["'][\d.-]+[\s,]+[\d.-]+[\s,]+(?<width>[\d.]+)[\s,]+(?<height>[\d.]+)["']/u;
+
+const parseSvgLength = (value: string | undefined): number | undefined => {
+  const length = Number(value?.match(SVG_LENGTH)?.groups?.value);
+  return length > 0 ? length : undefined;
+};
+
+/** Read dimensions from an SVG's explicit size or its view box. */
+const svgDimensions = (svg: string | undefined): LogoDimensions | undefined => {
+  const attributes = svg?.match(SVG_ROOT)?.groups?.attributes;
+  const width = parseSvgLength(attributes?.match(SVG_WIDTH)?.groups?.value);
+  const height = parseSvgLength(attributes?.match(SVG_HEIGHT)?.groups?.value);
+  if (width && height) {
+    return { height, width };
+  }
+
+  const viewBox = attributes?.match(SVG_VIEW_BOX);
+  const viewBoxWidth = Number(viewBox?.groups?.width);
+  const viewBoxHeight = Number(viewBox?.groups?.height);
+  return viewBoxWidth > 0 && viewBoxHeight > 0
+    ? { height: viewBoxHeight, width: viewBoxWidth }
+    : undefined;
+};
+
+/** Read a local SVG logo from the project root or public directory. */
+const readLogoSvg = (
+  project: BlumeProject,
+  source: string | undefined
+): string | undefined => {
+  if (!source?.toLowerCase().endsWith(".svg")) {
+    return;
+  }
+  const rel = source.replace(/^\//u, "");
+  const file = [
+    join(project.context.root, "public", rel),
+    join(project.context.root, rel),
+  ].find((path) => existsSync(path));
+  return file ? readFileSync(file, "utf-8") : undefined;
+};
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -646,18 +697,20 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   const dark = image?.dark ?? image?.light;
   const alt = image?.alt ?? "";
   const brandHref = href ?? "/";
+  const lightSvg = readLogoSvg(project, light);
+  const darkSvg = dark === light ? lightSvg : readLogoSvg(project, dark);
 
-  if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
-    const rel = light.replace(/^\//u, "");
-    const file = [
-      join(project.context.root, "public", rel),
-      join(project.context.root, rel),
-    ].find((path) => existsSync(path));
-    if (file) {
-      return { alt, href: brandHref, svg: readFileSync(file, "utf-8"), text };
-    }
+  if (light && light === dark && lightSvg) {
+    return { alt, href: brandHref, svg: lightSvg, text };
   }
-  return { alt, dark, href: brandHref, light, text };
+
+  const lightDimensions = svgDimensions(lightSvg);
+  const darkDimensions = svgDimensions(darkSvg);
+  const dimensions =
+    lightDimensions || darkDimensions
+      ? { dark: darkDimensions, light: lightDimensions }
+      : undefined;
+  return { alt, dark, dimensions, href: brandHref, light, text };
 };
 
 /**
@@ -778,6 +831,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     ? `https://github.com/${github.owner}/${github.repo}`
     : null;
   const editBase = github ? `${repoUrl}/edit/${github.branch}` : null;
+  const logo = resolveLogo(project);
+  const ogLogo = config.seo.og.logo
+    ? resolveOgLogo(project, config.seo.og.logo)
+    : logo?.svg;
 
   const editUrlFor = (sourcePath?: string): string | null => {
     if (!(editBase && sourcePath)) {
@@ -790,13 +847,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const { i18n } = config;
 
-  // API reference routes surface as header tabs alongside the content-derived
-  // ones (Blume-rendered references also own a tab-scoped sidebar of operations),
-  // so the reference stays discoverable in every locale.
-  const withReferenceTabs = (nav: Navigation): Navigation => ({
+  // Resolve the header repo link per locale. API references no longer add a tab
+  // automatically — authors point a `navigation.tabs` entry at the reference
+  // route to surface it (see `referenceRoutes`).
+  const withRepoUrl = (nav: Navigation): Navigation => ({
     ...nav,
     repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
-    tabs: [...nav.tabs, ...referenceTabs(config)],
   });
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
@@ -823,7 +879,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
           code,
-          withReferenceTabs(
+          withRepoUrl(
             graph.navigationByLocale[code] ?? {
               featured: [],
               selectors: [],
@@ -864,13 +920,20 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           }
         : null,
       imageZoom: config.markdown.imageZoom,
-      logo: resolveLogo(project),
-      mcp: config.mcp.enabled
-        ? { name: config.mcp.name ?? config.title, route: config.mcp.route }
+      logo,
+      mcp: config.ai.mcp.enabled
+        ? {
+            name: config.ai.mcp.name ?? config.title,
+            route: config.ai.mcp.route,
+          }
         : null,
       // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
       // the optional schema type so the serialized shape stays `boolean`.
-      og: { enabled: config.seo.og.enabled ?? false },
+      og: {
+        enabled: config.seo.og.enabled ?? false,
+        logo: ogLogo,
+        palette: config.seo.og.palette,
+      },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
@@ -890,7 +953,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     // CSS variables for Astro's <Font> component; matches the astro.config
     // `fonts:` entries derived from the same theme.fonts config.
     fontCssVars: configuredCssVars(config.theme.fonts),
-    navigation: withReferenceTabs(graph.navigation),
+    navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
     routes: manifest.routes.map((route) => ({
@@ -939,7 +1002,7 @@ const planMcp = (
   userPages: { pattern: string }[]
 ): McpPlan => {
   const { config } = project;
-  const { route } = config.mcp;
+  const { route } = config.ai.mcp;
   const dir = join(srcDir, "blume-mcp");
   const base: McpPlan = {
     dir,
@@ -949,14 +1012,14 @@ const planMcp = (
     srcDir,
     warnings: [],
   };
-  if (!config.mcp.enabled) {
+  if (!config.ai.mcp.enabled) {
     return base;
   }
   if (routeIsTaken(userPages, project.graph.pages, route)) {
     return {
       ...base,
       warnings: [
-        `MCP server route "${route}" is already used by a content or custom page; the MCP server was not generated. Set a different "mcp.route" in blume.config.ts.`,
+        `MCP server route "${route}" is already used by a content or custom page; the MCP server was not generated. Set a different "ai.mcp.route" in blume.config.ts.`,
       ],
     };
   }
@@ -1105,6 +1168,7 @@ export const generateRuntime = async (
   const { context, config } = project;
   const out = context.outDir;
   const srcDir = join(out, "src");
+  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");
@@ -1205,6 +1269,7 @@ export const generateRuntime = async (
         join(out, "astro.config.mjs"),
         astroConfigTemplate({
           aliases: resolveTsconfigAliases(context.root),
+          askPath,
           config,
           contentRoutes: project.manifest.routes.map((route) => route.path),
           context,
@@ -1242,13 +1307,16 @@ export const generateRuntime = async (
       write(
         join(srcDir, "pages", "[...slug].astro"),
         catchAllPageTemplate({
-          askEnabled,
           exportEpub,
           exportPdf,
           mathEnabled: usesMath,
           needsReact,
         })
       ),
+      // The header's Ask trigger, behind the `blume:ask` alias. Always written
+      // (even when Ask is off, as a component that renders nothing) so the alias
+      // resolves — the same contract as `blume:search-client`.
+      write(askPath, askComponentTemplate(askEnabled)),
       write(join(srcDir, "generated", "components.ts"), slotPlan.module),
       write(
         join(srcDir, "generated", "islands.ts"),
@@ -1336,7 +1404,6 @@ export const generateRuntime = async (
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
-        askEnabled,
         exportEpub,
         exportPdf,
         needsReact,
@@ -1433,11 +1500,11 @@ export const generateRuntime = async (
 
   // Missing-navigation-target check, now that every servable route is known:
   // content routes, custom `.astro` pages, the generated changelog, and any
-  // OpenAPI reference tabs.
+  // OpenAPI reference routes (so a tab an author points at one still validates).
   const navTargetRoutes = new Set<string>([
     ...project.graph.routes.keys(),
     ...pages.map((page) => page.pattern),
-    ...referenceTabs(config).map((tab) => tab.path),
+    ...referenceRoutes(config),
   ]);
   if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");