blume 0.2.0 → 0.3.0

package/src/ai/ask-context.ts

@@ -0,0 +1,131 @@
+import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
+import type { OramaDoc } from "../search/orama-index.ts";
+
+/** A chat message as posted by the Ask AI island (`{ role, content }`). */
+export interface AskMessage {
+  content: string;
+  role: string;
+}
+
+/** The current-page hint the island forwards so the endpoint can prioritize it. */
+export interface AskPage {
+  path?: string;
+}
+
+/**
+ * The self-contained snapshot the grounded Ask AI endpoint imports. Bundles the
+ * search documents so retrieval works regardless of the configured search
+ * provider and needs no filesystem access at request time. Serialized to
+ * `generated/ask-data.json` and built by {@link buildAskData}.
+ */
+export interface AskData {
+  documents: OramaDoc[];
+  site: string | null;
+}
+
+/** Documents retrieved per question and injected into the system prompt. */
+const MAX_RESULTS = 6;
+/** Characters kept per injected excerpt. */
+const EXCERPT_CHARS = 1500;
+/** Overall cap on injected documentation characters. */
+const CONTEXT_BUDGET = 8000;
+
+/**
+ * The grounding preamble. The model is told to answer strictly from the injected
+ * excerpts and to cite the pages it used, so answers stay tied to the docs.
+ */
+const BASE_INSTRUCTION =
+  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. If the answer is not covered by them, say you don't know and suggest where in the docs to look — do not invent details. Cite the page titles you drew from.";
+
+/** Normalize a page path to a document `route` (`/`, `/a/b`, no trailing slash). */
+const normalizeRoute = (input: string): string => {
+  const noTrailing = input.trim().replace(/\/+$/u, "");
+  const withSlash = noTrailing.startsWith("/") ? noTrailing : `/${noTrailing}`;
+  return withSlash === "" ? "/" : withSlash;
+};
+
+/** The most recent non-empty user message, used as the retrieval query. */
+const lastUserMessage = (messages: AskMessage[]): string => {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (message?.role === "user" && message.content?.trim()) {
+      return message.content.trim();
+    }
+  }
+  return "";
+};
+
+/** Trim a document body to `max` characters, marking truncation with an ellipsis. */
+const excerpt = (content: string, max: number): string => {
+  const trimmed = content.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+};
+
+/**
+ * Build the request-time grounding function for the Ask AI endpoint.
+ *
+ * Lexical retrieval over Orama (the same index/ranking the search dialog and MCP
+ * server use). The index is built once and memoized across requests. Returns a
+ * grounded system prompt — the retrieved excerpts plus the page the user is
+ * viewing — or `undefined` when there is nothing to ground on, so the endpoint
+ * can fall back to its plain prompt.
+ */
+export const createAskContext = (
+  data: AskData
+): ((
+  messages: AskMessage[],
+  page?: AskPage
+) => Promise<string | undefined>) => {
+  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
+    null;
+  const index = () => {
+    dbPromise ??= buildOramaIndex(data.documents);
+    return dbPromise;
+  };
+  const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
+
+  return async (messages, page) => {
+    const list = Array.isArray(messages) ? messages : [];
+    const query = lastUserMessage(list);
+    if (!query) {
+      return;
+    }
+
+    // The current page anchors retrieval to its locale and is injected first.
+    const current = page?.path
+      ? byRoute.get(normalizeRoute(page.path))
+      : undefined;
+    const db = await index();
+    const hits = await queryOramaIndex(
+      db,
+      query,
+      MAX_RESULTS,
+      current?.locale || undefined
+    );
+
+    const seen = new Set<string>();
+    const sections: string[] = [];
+    let budget = CONTEXT_BUDGET;
+    const push = (doc: OramaDoc, label: string) => {
+      if (seen.has(doc.route) || budget <= 0) {
+        return;
+      }
+      seen.add(doc.route);
+      const body = excerpt(doc.content, Math.min(EXCERPT_CHARS, budget));
+      budget -= body.length;
+      sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);
+    };
+
+    if (current) {
+      push(current, " — the page the user is currently viewing");
+    }
+    for (const hit of hits) {
+      push(hit, "");
+    }
+
+    if (sections.length === 0) {
+      return;
+    }
+    return `${BASE_INSTRUCTION}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
+  };
+};

package/src/ai/ask-data.ts

@@ -0,0 +1,25 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import { buildSearchDocuments } from "../search/documents.ts";
+import type { AskData } from "./ask-context.ts";
+
+/**
+ * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
+ * Ask AI is independent of on-page search, so documents are indexed even when the
+ * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
+ * MCP snapshot) so retrieval can be filtered to the current page's language.
+ */
+export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
+  const documents = await buildSearchDocuments(project, {
+    includeWhenDisabled: true,
+  });
+  return {
+    documents: documents.map((doc) => ({
+      content: doc.content,
+      description: doc.description,
+      locale: doc.locale,
+      route: doc.route,
+      title: doc.title,
+    })),
+    site: project.config.deployment.site ?? null,
+  };
+};

package/src/astro/component-slots.ts

@@ -0,0 +1,165 @@
+import type {
+  ComponentOverrideAnalysis,
+  NormalizedOverride,
+  OverrideFramework,
+} from "../core/component-overrides.ts";
+
+/**
+ * Turn analyzed `components.ts` overrides into the generated `components.ts`
+ * module plus per-override hydration wrappers.
+ *
+ * The runtime overrides object already holds bare imported identifiers, so those
+ * (when not hydrated) ride through a plain spread. Everything else needs a static
+ * import Vite can see: path-string overrides import the file directly, while
+ * hydrated overrides get a wrapper `.astro` that applies the `client:*` directive
+ * (Astro directives must be written statically). The `islands` group is folded
+ * into the MDX component map — it is just `mdx` with a default `client: "visible"`.
+ */
+
+export interface ComponentSlotWrapper {
+  content: string;
+  /** File name (no extension) under `.blume/src/generated/component-slots/`. */
+  name: string;
+}
+
+export interface ComponentSlotPlan {
+  /** Frameworks used by resolved overrides; enable the matching Astro renderer. */
+  frameworks: Set<OverrideFramework>;
+  /** Contents of `.blume/src/generated/components.ts`. */
+  module: string;
+  wrappers: ComponentSlotWrapper[];
+}
+
+const EMPTY_MODULE = `// Generated by Blume. Do not edit.
+export const mdxComponents = {};
+export const layoutOverrides = {};
+`;
+
+/** Astro client directive for a hydrated override. */
+const directiveFor = (override: NormalizedOverride): string => {
+  const framework = override.source?.framework;
+  switch (override.client) {
+    case "idle": {
+      return "client:idle";
+    }
+    case "visible": {
+      return "client:visible";
+    }
+    case "media": {
+      return override.media
+        ? `client:media="${override.media}"`
+        : "client:load";
+    }
+    case "only": {
+      return framework ? `client:only="${framework}"` : "client:load";
+    }
+    default: {
+      return "client:load";
+    }
+  }
+};
+
+const importClause = (variable: string, name: string, path: string): string =>
+  name === "default"
+    ? `import ${variable} from ${JSON.stringify(path)};`
+    : `import { ${name} as ${variable} } from ${JSON.stringify(path)};`;
+
+/** A wrapper `.astro` that statically imports a component and hydrates it. */
+const wrapperContent = (override: NormalizedOverride): string => {
+  const { name, path } = override.source as NonNullable<
+    NormalizedOverride["source"]
+  >;
+  const clause =
+    name === "default"
+      ? `import Component from ${JSON.stringify(path)};`
+      : `import { ${name} as Component } from ${JSON.stringify(path)};`;
+  return `---
+// Generated by Blume. Do not edit.
+${clause}
+---
+<Component ${directiveFor(override)} {...Astro.props}><slot /></Component>
+`;
+};
+
+const sanitize = (value: string): string =>
+  value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+
+export const planComponentSlots = (
+  componentsFile: string | null,
+  analysis: ComponentOverrideAnalysis | null
+): ComponentSlotPlan => {
+  const frameworks = new Set<OverrideFramework>();
+  if (!componentsFile) {
+    return { frameworks, module: EMPTY_MODULE, wrappers: [] };
+  }
+  if (!analysis) {
+    return {
+      frameworks,
+      module: `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+export const mdxComponents = overrides.mdx ?? {};
+export const layoutOverrides = overrides.layout ?? {};
+`,
+      wrappers: [],
+    };
+  }
+
+  const wrappers: ComponentSlotWrapper[] = [];
+  const importLines: string[] = [];
+  // Explicit `key: Variable` map entries, per surface.
+  const mdxEntries: string[] = [];
+  const layoutEntries: string[] = [];
+  let counter = 0;
+
+  // Islands are MDX components hydrated by default, so plan them alongside `mdx`.
+  const mdxOverrides = [...analysis.mdx, ...analysis.islands];
+
+  const plan = (
+    override: NormalizedOverride,
+    group: "mdx" | "layout",
+    entries: string[]
+  ): void => {
+    const { source } = override;
+    if (source?.framework) {
+      frameworks.add(source.framework);
+    }
+    // Bare identifier, not hydrated: the runtime object already has it.
+    if (override.identifier && !override.client) {
+      return;
+    }
+    if (!source) {
+      // Unresolved (already warned): leave it on the runtime object.
+      return;
+    }
+    const variable = `__blumeSlot${counter}`;
+    counter += 1;
+    if (override.client) {
+      const name = `${group}-${sanitize(override.key)}`;
+      wrappers.push({ content: wrapperContent(override), name });
+      importLines.push(
+        importClause(variable, "default", `./component-slots/${name}.astro`)
+      );
+    } else {
+      importLines.push(importClause(variable, source.name, source.path));
+    }
+    entries.push(`${JSON.stringify(override.key)}: ${variable}`);
+  };
+
+  for (const override of mdxOverrides) {
+    plan(override, "mdx", mdxEntries);
+  }
+  for (const override of analysis.layout) {
+    plan(override, "layout", layoutEntries);
+  }
+
+  // `overrides.islands` is not spread: every valid island is hydrated, so it is
+  // emitted as an explicit wrapper entry above (raw spreads only carry bare,
+  // non-hydrated identifiers from `mdx`/`layout`).
+  const moduleSource = `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+${importLines.join("\n")}${importLines.length ? "\n" : ""}export const mdxComponents = { ...(overrides.mdx ?? {})${mdxEntries.length ? `, ${mdxEntries.join(", ")}` : ""} };
+export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.length ? `, ${layoutEntries.join(", ")}` : ""} };
+`;
+
+  return { frameworks, module: moduleSource, wrappers };
+};

package/src/astro/generate.ts

@@ -14,10 +14,13 @@ import { pathToFileURL } from "node:url";
 import { basename, dirname, join, normalize, relative } from "pathe";
 import { glob } from "tinyglobby";
 
+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 { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import { validateUsedComponents } from "../core/component-diagnostics.ts";
+import { analyzeComponentOverrides } from "../core/component-overrides.ts";
 import type {
   BlumeBanner,
   BlumeData,
@@ -26,6 +29,7 @@ import type {
 } from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
+import { validateNavTargets } from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
@@ -37,12 +41,15 @@ import {
   hasReferences,
   referenceTabs,
 } from "../openapi/scalar.ts";
+import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import { tailwindEntryTemplate } from "../theme/entry.ts";
 import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
+import { planComponentSlots } from "./component-slots.ts";
+import type { ComponentSlotPlan } from "./component-slots.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
@@ -72,7 +79,6 @@ import {
   searchClientTemplate,
   searchEndpointTemplate,
   stagedContentDir,
-  userComponentsTemplate,
 } from "./templates.ts";
 
 /** Absolute path to the Blume package `src` directory. */
@@ -661,6 +667,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       structuredData: config.seo.structuredData,
       theme: config.theme,
       title: config.title,
+      toc: config.toc,
     },
     feeds: buildRssFeeds(project).map((feed) => ({
       href: feed.path,
@@ -787,6 +794,33 @@ const writeMcpFiles = async (
   ]);
 };
 
+/**
+ * Write the Ask AI endpoint and, unless the backend runs its own retrieval
+ * (Inkeep), the grounding snapshot the endpoint queries at request time. A no-op
+ * when Ask AI is disabled.
+ */
+const writeAskFiles = async (
+  project: BlumeProject,
+  srcDir: string,
+  write: (path: string, content: string) => Promise<boolean>
+): Promise<void> => {
+  const { ask } = project.config.ai;
+  if (!ask?.enabled) {
+    return;
+  }
+  const grounded = ask.provider !== "inkeep";
+  if (grounded) {
+    await write(
+      join(srcDir, "generated", "ask-data.json"),
+      `${JSON.stringify(await buildAskData(project))}\n`
+    );
+  }
+  await write(
+    join(srcDir, "pages", "api", "ask.ts"),
+    askEndpointTemplate(resolveAskBackend(ask), grounded)
+  );
+};
+
 /**
  * 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
@@ -835,6 +869,35 @@ const shouldGenerateChangelog = (project: BlumeProject): boolean => {
   return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
 };
 
+/**
+ * Statically analyze the user's `components.ts` (never executing it) and plan the
+ * generated `components.ts` module plus any hydration wrappers. Returns the plan
+ * and the analyzer's warnings; a project with no components file gets an empty
+ * plan and no warnings.
+ */
+const buildComponentSlots = async (
+  componentsFile: string | null
+): Promise<{
+  plan: ComponentSlotPlan;
+  /** MDX tags the overrides define (for the unknown-component check). */
+  tags: string[];
+  warnings: string[];
+}> => {
+  const analysis = componentsFile
+    ? analyzeComponentOverrides(
+        await readFile(componentsFile, "utf-8"),
+        componentsFile
+      )
+    : null;
+  return {
+    plan: planComponentSlots(componentsFile, analysis),
+    tags: analysis
+      ? [...analysis.mdx, ...analysis.islands].map((entry) => entry.key)
+      : [],
+    warnings: analysis ? analysis.warnings : [],
+  };
+};
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -873,12 +936,23 @@ export const generateRuntime = async (
       discoverIslands(context.root),
       discoverExamples(context.root, config.examples),
     ]);
+  // Statically analyze `components.ts` overrides (never executed): drives the
+  // `islands` group, hydration on layout/mdx overrides, string-path resolution,
+  // and the "framework component with no client mode" diagnostic.
+  const {
+    plan: slotPlan,
+    tags: overrideTags,
+    warnings: overrideWarnings,
+  } = await buildComponentSlots(context.componentsFile);
+
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
-  // island/example-driven. `.astro` examples need no renderer.
+  // island/example-driven. `.astro` examples need no renderer. Component
+  // overrides referencing a framework component enable its renderer too.
   const frameworks = new Set<string>([
     ...islandDiscovery.islands.map((island) => island.framework),
     ...exampleDiscovery.examples.map((example) => example.framework),
+    ...slotPlan.frameworks,
   ]);
   const needsReact = detectedReact || askEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
@@ -887,7 +961,7 @@ export const generateRuntime = async (
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
   // private and filtered out anyway, but the intent is the user's pages.
-  const ogRoutes = customOgRoutes(pages, config.title, config.description);
+  const ogRoutes = customOgRoutes(pages, config.title);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
@@ -937,12 +1011,10 @@ export const generateRuntime = async (
         exportEpub,
         exportPdf,
         mathEnabled: config.markdown.math,
+        needsReact,
       })
     ),
-    write(
-      join(srcDir, "generated", "components.ts"),
-      userComponentsTemplate(context.componentsFile)
-    ),
+    write(join(srcDir, "generated", "components.ts"), slotPlan.module),
     write(
       join(srcDir, "generated", "islands.ts"),
       islandMapTemplate(islandDiscovery.islands)
@@ -977,6 +1049,18 @@ export const generateRuntime = async (
     )
   );
 
+  // Per-override hydration wrappers for `defineComponents` islands and `client:*`
+  // layout/mdx overrides. The generated `components.ts` (written above) imports
+  // these; orphans from removed overrides are pruned at the end of the pass.
+  await Promise.all(
+    slotPlan.wrappers.map((wrapper) =>
+      write(
+        join(srcDir, "generated", "component-slots", `${wrapper.name}.astro`),
+        wrapper.content
+      )
+    )
+  );
+
   // Per-example live wrappers for the `examples/` convention, resolved by
   // `<Component path>` through the `examples.ts` map (written above, always).
   await Promise.all(
@@ -993,12 +1077,7 @@ export const generateRuntime = async (
     )
   );
 
-  if (askEnabled) {
-    await write(
-      join(srcDir, "pages", "api", "ask.ts"),
-      askEndpointTemplate(resolveAskBackend(config.ai.ask))
-    );
-  }
+  await writeAskFiles(project, srcDir, write);
 
   await writeMcpFiles(project, mcp, write);
 
@@ -1017,6 +1096,7 @@ export const generateRuntime = async (
         askEnabled,
         exportEpub,
         exportPdf,
+        needsReact,
         staged: hasStaged,
       })
     );
@@ -1092,8 +1172,47 @@ export const generateRuntime = async (
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,
+    ...overrideWarnings,
   ];
 
+  // Missing-navigation-target check, now that every servable route is known:
+  // content routes, custom `.astro` pages, the generated changelog, and any
+  // OpenAPI reference tabs.
+  const navTargetRoutes = new Set<string>([
+    ...project.graph.routes.keys(),
+    ...pages.map((page) => page.pattern),
+    ...referenceTabs(config).map((tab) => tab.path),
+  ]);
+  if (shouldGenerateChangelog(project)) {
+    navTargetRoutes.add("/changelog");
+  }
+  warnings.push(
+    ...validateNavTargets(project.graph.navigation, navTargetRoutes).map(
+      (diagnostic) =>
+        diagnostic.suggestion
+          ? `${diagnostic.message} ${diagnostic.suggestion}`
+          : diagnostic.message
+    )
+  );
+
+  // Unknown-component check: a `<Tag>` in MDX that isn't a built-in, an island,
+  // or a `components.ts` override. Needs the project's own components, known here.
+  const knownComponentTags = new Set<string>([
+    ...islandDiscovery.islands.map((island) => island.name),
+    ...overrideTags,
+  ]);
+  warnings.push(
+    ...validateUsedComponents(
+      project.graph.pages,
+      knownComponentTags,
+      new Set(registry.map((item) => item.name))
+    ).map((diagnostic) =>
+      diagnostic.suggestion
+        ? `${diagnostic.message} ${diagnostic.suggestion}`
+        : diagnostic.message
+    )
+  );
+
   // Provider SDKs are optional peers; warn (rather than fail opaquely in Vite)
   // when the configured provider's package isn't installed. A dep is available
   // if the project installed it (resolves from the root) OR Blume ships it

package/src/astro/integration.ts

@@ -2,8 +2,64 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 
 import type { AstroIntegration } from "astro";
 
+import { enrichDiagnostic } from "../core/diagnostics.ts";
+import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
 
+/** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
+interface OverlayChannel {
+  send: (payload: unknown) => void;
+}
+interface OverlayServer {
+  hot?: OverlayChannel;
+  ws?: OverlayChannel;
+}
+
+// Set on `astro:server:setup`; read by `showBlumeErrorOverlay` so the CLI's
+// regeneration can push Blume diagnostics into Vite's browser error overlay.
+// Same-process module singleton (dev and the integration share the instance).
+let overlayServer: OverlayServer | null = null;
+
+const overlayChannel = (): OverlayChannel | undefined =>
+  overlayServer?.ws ?? overlayServer?.hot;
+
+/**
+ * Surface Blume's own diagnostics (config/frontmatter/content errors) in the
+ * Vite/Astro browser error overlay during `blume dev`, so they don't hide in the
+ * terminal. A no-op when there are no errors or the dev server isn't up. The
+ * overlay clears itself on the next successful HMR update.
+ */
+export const showBlumeErrorOverlay = (diagnostics: Diagnostic[]): void => {
+  const errors = diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(enrichDiagnostic);
+  const channel = overlayChannel();
+  if (errors.length === 0 || !channel) {
+    return;
+  }
+  const body = errors
+    .map((diagnostic) => {
+      const where = diagnostic.file
+        ? `\n  at ${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}` : ""}`
+        : "";
+      const fix = diagnostic.suggestion
+        ? `\n  fix: ${diagnostic.suggestion}`
+        : "";
+      const docs = diagnostic.docsUrl ? `\n  docs: ${diagnostic.docsUrl}` : "";
+      return `[${diagnostic.code}] ${diagnostic.message}${where}${fix}${docs}`;
+    })
+    .join("\n\n");
+  channel.send({
+    err: {
+      id: errors[0]?.file,
+      message: `Blume found ${errors.length} error(s):\n\n${body}`,
+      plugin: "blume",
+      stack: "",
+    },
+    type: "error",
+  });
+};
+
 /** A user page mounted into the generated runtime. */
 export interface BlumePageRoute {
   /** Route pattern, e.g. `/changelog` or `/examples/[slug]`. */
@@ -62,6 +118,9 @@ export const blumeIntegration = (
       }
     },
     "astro:server:setup": ({ server }) => {
+      // Keep a handle on the dev server so Blume diagnostics can be pushed to
+      // its browser error overlay (see `showBlumeErrorOverlay`).
+      overlayServer = server as unknown as OverlayServer;
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({

package/src/astro/pages.ts

@@ -45,10 +45,8 @@ export const routeIsTaken = (
 export interface OgCustomRoute {
   /** `og/<slug>.png` path segment; `index` for the site root. */
   slug: string;
-  /** Card title. */
+  /** Card headline. */
   title: string;
-  /** Small eyebrow line above the title. */
-  eyebrow?: string;
 }
 
 /** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
@@ -68,13 +66,12 @@ const humanizeSegment = (segment: string): string =>
  *
  * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
  * are skipped: they aren't shareable pages. The home is titled with the site
- * title (eyebrow: the site description); a deeper page is titled from its last
- * path segment.
+ * title; a deeper page is titled from its last path segment. The card's brand
+ * lockup, description, and footer come from the resolved config at render time.
  */
 export const customOgRoutes = (
   pages: BlumePageRoute[],
-  siteTitle: string,
-  siteDescription?: string
+  siteTitle: string
 ): OgCustomRoute[] => {
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
@@ -91,11 +88,7 @@ export const customOgRoutes = (
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push(
-      last
-        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
-        : { eyebrow: siteDescription, slug, title: siteTitle }
-    );
+    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
   }
   return routes;
 };