blume 1.7.3 → 2.0.1

package/src/astro/generate.ts

@@ -13,22 +13,14 @@ import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
 import pMap from "p-map";
-import {
-  basename,
-  dirname,
-  isAbsolute,
-  join,
-  normalize,
-  relative,
-  resolve,
-} from "pathe";
+import { dirname, isAbsolute, join, normalize, relative, resolve } from "pathe";
 import { glob } from "tinyglobby";
 
 import { hasAiCatalog } from "../ai/ai-catalog.ts";
 import { OPENAPI_PATH } from "../ai/api/paths.ts";
 import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
-import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
+import { resolveAskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import type { RawMarkdownEntry } from "../ai/markdown.ts";
@@ -41,7 +33,11 @@ import {
 } from "../components/layout/nav-utils.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
-import { analyzeComponentOverrides } from "../core/component-overrides.ts";
+import {
+  analyzeComponentOverrides,
+  emptyComponentOverrides,
+} from "../core/component-overrides.ts";
+import type { ComponentOverrideAnalysis } from "../core/component-overrides.ts";
 import {
   collectContentAssets,
   rewriteRelativeImages,
@@ -87,7 +83,7 @@ import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
 import type { ApiSpecData, OpenApiData } from "../openapi/model.ts";
 import {
-  builtinProxyKinds,
+  builtinProxyReferences,
   hasScalarReferences,
   needsPlaygroundProxy,
   referenceRoutes,
@@ -97,7 +93,6 @@ import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { resolveSearchPopular } from "../search/popular.ts";
-import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
@@ -111,7 +106,6 @@ import { buildThemeCss } from "../theme/palette.ts";
 import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
-import type { ComponentSlotPlan } from "./component-slots.ts";
 import {
   EXAMPLE_SCAN_GLOB,
   discoverExamples,
@@ -126,6 +120,8 @@ import {
   hasGeneratedChangelog,
   routeIsTaken,
 } from "./pages.ts";
+import { candidateHolding } from "./render-deps.ts";
+import { missingDependencyDiagnostic } from "./runtime-deps.ts";
 import { publishRuntimeModules } from "./runtime-modules.ts";
 import type { RuntimeModuleId } from "./runtime-modules.ts";
 import {
@@ -140,8 +136,6 @@ import {
   exampleWrapperTemplate,
   examplesPageTemplate,
   exampleSlug,
-  islandMapTemplate,
-  islandWrapperTemplate,
   apiNavigationTemplate,
   apiNotFoundTemplate,
   apiPageTemplate,
@@ -169,19 +163,14 @@ import {
 } from "./templates.ts";
 import type { ClientFeatures } from "./templates.ts";
 
+// The render-deps plugin and the dependency-directory probe live in
+// `render-deps.ts`; `blume/astro` and existing callers import them from here.
+export { blumeDepsDir, prerenderDepsPlugin } from "./render-deps.ts";
+export type { PrerenderDepsPlugin } from "./render-deps.ts";
+
 /** Absolute path to the Blume package `src` directory. */
 const BLUME_SRC = join(packageRoot(), "src");
 
-/** Whether a module specifier resolves from a directory via node resolution. */
-const canResolveFrom = (fromDir: string, spec: string): boolean => {
-  try {
-    createRequire(pathToFileURL(join(fromDir, "_.js")).href).resolve(spec);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
 /**
  * Absolute path to `babel-plugin-react-compiler`, resolved from Blume's own
  * package root (Blume ships it). Returns null when React or the compiler is off.
@@ -281,62 +270,6 @@ export const sameRealDir = (a: string, b: string): boolean => {
   }
 };
 
-/**
- * The two places an installer can put Blume's dependencies:
- *   - `<blume>/node_modules` — deps nested under the package (workspace source,
- *     or npm nesting them away from a conflicting hoisted copy)
- *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
- *
- * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
- * install symlink), so its parent is the store's package directory where the
- * isolated linker places the siblings.
- */
-const depsCandidates = (pkgDir: string): string[] => [
-  join(pkgDir, "node_modules"),
-  dirname(pkgDir),
-];
-
-/** First dependency candidate containing the package dir `segments`, or null. */
-const candidateHolding = (
-  pkgDir: string,
-  ...segments: string[]
-): string | null =>
-  depsCandidates(pkgDir).find((dir) => existsSync(join(dir, ...segments))) ??
-  null;
-
-/**
- * Locate the directory that holds Blume's installed dependencies (Astro and its
- * integrations).
- *
- * With a clean hoisted install this is moot — the deps sit in a `node_modules`
- * the generated `.blume/` already walks up into, and {@link ensureDepsLink}
- * short-circuits before we need it. But under isolated linkers (Bun's
- * `isolated` mode, pnpm) Blume's deps are NOT hoisted into the project; they
- * live beside the Blume package in a virtual store, invisible to the upward
- * walk from `.blume/` — so probe the {@link depsCandidates}.
- *
- * Astro alone is a bad probe: an npm split install (an `overrides` pin plus an
- * incremental install) hoists `astro` to the project root while Blume's other
- * deps stay nested, and probing for astro then picks the root directory — one
- * that holds none of them. Prefer a candidate with the full set (astro beside
- * `@astrojs/mdx`, the integration every generated runtime declares), then one
- * with the integrations (astro hoisted away — the rest of Blume's deps sit
- * there too), then one with astro alone.
- */
-const holdsAstro = (dir: string): boolean => existsSync(join(dir, "astro"));
-const holdsMdx = (dir: string): boolean =>
-  existsSync(join(dir, "@astrojs", "mdx"));
-
-export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
-  const candidates = depsCandidates(pkgDir);
-  return (
-    candidates.find((dir) => holdsAstro(dir) && holdsMdx(dir)) ??
-    candidates.find(holdsMdx) ??
-    candidates.find(holdsAstro) ??
-    null
-  );
-};
-
 /**
  * Create `link` as a directory symlink to `target`, falling back to a junction.
  *
@@ -554,169 +487,6 @@ export const ensureDepsLink = async (
   return astroConflictWarning(blumeAstro, outDirHit?.pkg ?? null);
 };
 
-/**
- * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
- * `takumi-js`, …) resolvable when Astro executes the static prerender
- * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
- *
- * Astro's static build emits a self-contained SSR bundle to
- * `<outDir>/.prerender/` and `import()`s it in-process to generate the HTML.
- * That bundle externalizes Blume's render-time deps, so Node resolves them at
- * prerender time by walking up from `.prerender/chunks/*.mjs`. {@link
- * ensureDepsLink} only repairs resolution rooted at `.blume/`; `.prerender/`
- * lives under `dist/`, a separate tree an isolated linker never hoists Blume's
- * deps into — so the import dies with `Cannot find package 'zod'`. We drop the
- * same `node_modules` junction into the prerender root, mirroring
- * `.blume/node_modules`, so every externalized specifier — native bindings
- * included, which can't be bundled — resolves. Astro deletes `.prerender/` once
- * generation finishes (and the junction with it: `fs.rm` unlinks symlinks, it
- * never follows them), so nothing leaks into the published `dist/`.
- *
- * Keyed off the output dir's basename (`.prerender`) — the name Astro 7 gives
- * the prerender build for both static (`<outDir>/.prerender/`) and server
- * (`<build.server>/.prerender/`) output — so it fires for exactly that build.
- * Inert in dev, where there is no build and `writeBundle` never runs.
- */
-export interface PrerenderDepsPlugin {
-  name: string;
-  writeBundle: (options: { dir?: string }) => Promise<void>;
-}
-
-export const prerenderDepsPlugin = (
-  pkgDir: string = packageRoot()
-): PrerenderDepsPlugin => ({
-  name: "blume:prerender-deps",
-  writeBundle: async (options) => {
-    if (!options.dir || basename(options.dir) !== ".prerender") {
-      return;
-    }
-    const depsDir = blumeDepsDir(pkgDir);
-    if (!depsDir) {
-      return;
-    }
-    await linkDepsJunction(join(options.dir, "node_modules"), depsDir);
-  },
-});
-
-/** Astro integration package each non-React island framework needs installed. */
-const ISLAND_FRAMEWORK_DEPS = new Map([
-  ["svelte", "@astrojs/svelte"],
-  ["vue", "@astrojs/vue"],
-]);
-
-/**
- * Adapter package the project must install itself for each deployment
- * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
- * so they never need this.
- */
-const DEPLOYMENT_ADAPTER_DEPS = new Map([
-  ["cloudflare", "@astrojs/cloudflare"],
-  ["netlify", "@astrojs/netlify"],
-]);
-
-/**
- * Warn when a Vue/Svelte island is present but its Astro integration isn't
- * installed — Vite would otherwise fail opaquely on the generated config import.
- * React ships with Blume, so it never needs this.
- */
-const islandFrameworkWarnings = (
-  frameworks: Set<string>,
-  root: string
-): string[] => {
-  const warnings: string[] = [];
-  for (const framework of frameworks) {
-    const dep = ISLAND_FRAMEWORK_DEPS.get(framework);
-    if (dep && !canResolveFrom(root, dep)) {
-      warnings.push(
-        `Islands use ${framework}, which needs "${dep}". Install it (e.g. \`npm install ${dep} ${framework}\`).`
-      );
-    }
-  }
-  return warnings;
-};
-
-/**
- * Warn when the resolved server-output adapter is one the project must install
- * itself (Netlify/Cloudflare; Node and Vercel ship with Blume). The generated
- * astro.config.mjs imports the adapter package directly — and on those
- * platforms the adapter is even auto-selected from env vars — so warn early
- * rather than let the build die with an opaque ERR_MODULE_NOT_FOUND from the
- * hidden generated config. Availability mirrors the search-provider check: a
- * dep resolves from the project root or from the Blume package itself.
- * `pkgDir` is injectable for testing.
- */
-export const deploymentAdapterWarnings = (
-  deployment: ResolvedConfig["deployment"],
-  root: string,
-  pkgDir: string = packageRoot()
-): string[] => {
-  const dep =
-    deployment.output === "server" && deployment.adapter
-      ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter)
-      : undefined;
-  if (dep && !(canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep))) {
-    return [
-      `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
-    ];
-  }
-  return [];
-};
-
-/**
- * Warn when the configured search provider's SDK is missing. Provider SDKs are
- * optional peers; warn (rather than fail opaquely in Vite) when the package
- * isn't installed. A dep is available if the project installed it (resolves
- * from the root) OR Blume ships it (resolves from the Blume package — the same
- * set the `.blume` deps link exposes to the build). Resolving from the project
- * root alone falsely flagged a shipped SDK like Orama (the default provider)
- * as missing whenever it wasn't hoisted into the project, e.g. under isolated
- * linkers. We resolve from each package's real location rather than through
- * the `.blume` junction, which can't be traversed reliably for store-symlinked
- * deps. `pkgDir` is injectable for testing.
- */
-export const searchProviderWarnings = (
-  provider: ResolvedConfig["search"]["provider"],
-  root: string,
-  pkgDir: string = packageRoot()
-): string[] => {
-  const warnings: string[] = [];
-  for (const dep of searchProviderMeta(provider).runtimeDeps) {
-    if (!(canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep))) {
-      warnings.push(
-        `Search provider "${provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
-      );
-    }
-  }
-  return warnings;
-};
-
-/**
- * Warn when the Ask AI backend's provider SDK is missing. Like search provider
- * SDKs, these are optional peers the project must install (only `gateway`
- * needs nothing beyond the core `ai` package Blume ships) — warn early with
- * the package name rather than let Vite fail to resolve the import opaquely.
- * Same resolution rule as {@link searchProviderWarnings}: available if the
- * project installed it or Blume can resolve it. `pkgDir` is injectable for
- * testing.
- */
-export const askProviderWarnings = (
-  ask: ResolvedConfig["ai"]["ask"],
-  root: string,
-  pkgDir: string = packageRoot()
-): string[] => {
-  // An external `endpoint` means no generated route, so no SDK is imported.
-  if (!ask?.enabled || ask.endpoint) {
-    return [];
-  }
-  const dep = askBackendRuntimeDep(ask);
-  if (!dep || canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep)) {
-    return [];
-  }
-  return [
-    `Ask AI provider "${ask.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
-  ];
-};
-
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (
   root: string,
@@ -866,7 +636,7 @@ const writeIfChanged = async (
 
 /**
  * Delete generated files under `srcDir` that this pass didn't (re)write. The
- * generator emits many files conditionally — an Ask AI endpoint, OG images, a
+ * generator emits many files conditionally — an assistant endpoint, OG images, a
  * search index, RSS feeds, reference pages, the MCP server — so toggling a
  * feature off would otherwise leave a stale file behind, and a leftover
  * server-rendered endpoint breaks the static build. `writeIfChanged` only ever
@@ -908,7 +678,7 @@ export const collectStaged = (project: BlumeProject): Map<string, string> => {
       // agent-facing Markdown gets.
       const text = page.sourcePath
         ? rewriteRelativeImages({
-            deployBase: project.config.deployment.base,
+            deployBase: project.config.deployment.options.base,
             projectRoot: project.context.root,
             source: page.body.text,
             sourcePath: page.sourcePath,
@@ -1225,9 +995,9 @@ const resolveOgSite = (config: ResolvedConfig): string | undefined => {
   if (configured !== undefined) {
     return configured;
   }
-  return config.deployment.site
-    ? `${new URL(config.deployment.site).host}${normalizeBasePath(
-        config.deployment.base
+  return config.deployment.options.site
+    ? `${new URL(config.deployment.options.site).host}${normalizeBasePath(
+        config.deployment.options.base
       )}`
     : undefined;
 };
@@ -1342,27 +1112,27 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const data: BlumeData = {
     config: {
-      analytics: config.analytics ?? null,
+      analytics: config.analytics,
       appleIcon: resolveAppleIcon(project),
-      ask: config.ai.ask?.enabled
+      assistant: config.ai.assistant?.enabled
         ? {
-            endpoint: config.ai.ask.endpoint ?? null,
-            suggestions: config.ai.ask.suggestions,
+            endpoint: config.ai.assistant.endpoint ?? null,
+            suggestions: config.ai.assistant.suggestions,
           }
         : null,
       banner: resolveBanner(config),
       basePath: config.basePath,
-      codeThemes: config.markdown.codeBlocks.theme,
+      codeThemes: config.markdown.code.theme,
       codeWrap: config.markdown.code.wrap,
       dateFormat: config.dateFormat,
       description: config.description,
       discovery: {
-        agentReadability: config.seo.agentReadability,
+        agentReadability: config.agents.agentReadability,
         aiCatalog: hasAiCatalog(config),
-        api: config.ai.api,
-        llmsTxt: config.ai.llmsTxt.enabled,
+        api: config.agents.api,
+        llmsTxt: config.agents.llmsTxt.enabled,
         // Mirrors `buildSitemapFiles`: no site, no sitemap.
-        sitemap: config.seo.sitemap && Boolean(config.deployment.site),
+        sitemap: config.seo.sitemap && Boolean(config.deployment.options.site),
       },
       favicon: resolveFavicon(project),
       feedback: config.feedback,
@@ -1392,10 +1162,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           : null,
       imageZoom: config.markdown.imageZoom,
       logo,
-      mcp: config.ai.mcp.enabled
+      mcp: config.agents.mcp.enabled
         ? {
-            name: config.ai.mcp.name ?? config.title,
-            route: config.ai.mcp.route,
+            name: config.agents.mcp.name ?? config.title,
+            route: config.agents.mcp.route,
           }
         : null,
       // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
@@ -1413,19 +1183,19 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       openInChat: config.ai.openInChat,
       repoUrl,
       search: {
-        enabled: config.search.provider !== "none",
+        enabled: config.search.provider.mode !== "none",
         popular: resolveSearchPopular(config.search.popular, config.basePath),
-        provider: config.search.provider,
+        provider: config.search.provider.kind,
       },
-      site: config.deployment.site ?? null,
+      site: config.deployment.options.site ?? null,
       structuredData: config.seo.structuredData,
       theme: config.theme,
       title: config.title,
       toc: config.toc,
       versions: config.versions ?? null,
       webmcp: {
-        enabled: config.ai.webmcp,
-        llms: config.ai.llmsTxt.enabled,
+        enabled: config.agents.webmcp,
+        llms: config.agents.llmsTxt.enabled,
       },
       x: config.seo.x,
     },
@@ -1469,6 +1239,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
       locale: route.locale,
+      monolingual: route.monolingual ?? false,
       path: route.path,
       title: route.title,
       version: route.version,
@@ -1505,7 +1276,7 @@ const planMcp = (
   userPages: { pattern: string }[]
 ): McpPlan => {
   const { config } = project;
-  const { route } = config.ai.mcp;
+  const { route } = config.agents.mcp;
   const dir = join(srcDir, "blume-mcp");
   const base: McpPlan = {
     dir,
@@ -1515,14 +1286,14 @@ const planMcp = (
     srcDir,
     warnings: [],
   };
-  if (!config.ai.mcp.enabled) {
+  if (!config.agents.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 "ai.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 "agents.mcp.route" in blume.config.ts.`,
       ],
     };
   }
@@ -1640,13 +1411,13 @@ const planApi = (
   userPages: { pattern: string }[]
 ): ApiPlan => {
   const { config, context } = project;
-  const server = config.deployment.output === "server";
+  const server = config.deployment.options.output === "server";
   return {
     catchAll:
       server &&
       !userPages.some(ownsApiRest) &&
       !project.graph.pages.some(contentUnderApi),
-    enabled: config.ai.api,
+    enabled: config.agents.api,
     server,
     spec:
       !routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) &&
@@ -1701,10 +1472,10 @@ const writeApiFiles = async (
         join(plan.srcDir, "pages", "openapi.json.ts"),
         staticJsonEndpointTemplate(
           buildApiSpec({
-            agentReadability: config.seo.agentReadability,
+            agentReadability: config.agents.agentReadability,
             base: data.base,
             description: config.description,
-            llmsTxt: config.ai.llmsTxt.enabled,
+            llmsTxt: config.agents.llmsTxt.enabled,
             mcpRoute,
             name: config.title,
             search: plan.server,
@@ -1791,15 +1562,17 @@ const proxyAllowlistWarnings = (
   config: ResolvedConfig,
   data: OpenApiData
 ): string[] => {
-  const kinds = builtinProxyKinds(config);
+  const proxied = new Set(
+    builtinProxyReferences(config).map((reference) => reference.slug)
+  );
   const warnings: string[] = [];
   for (const spec of Object.values(data)) {
-    if (!kinds.includes(spec.kind) || specOriginsOf(spec).length > 0) {
+    if (!proxied.has(spec.slug) || specOriginsOf(spec).length > 0) {
       continue;
     }
     warnings.push(
       spec.kind === "graphql"
-        ? `The "${spec.label}" GraphQL reference (${spec.route}) has playground.proxy: true, but no absolute endpoint is configured for it, so the built-in proxy has no origin to allow and will refuse every request its playground sends. Set the graphql block's (or the source's) \`endpoint\` to the live GraphQL URL, or point playground.proxy at an external proxy URL.`
+        ? `The "${spec.label}" GraphQL reference (${spec.route}) has playground.proxy: true, but no absolute endpoint is configured for it, so the built-in proxy has no origin to allow and will refuse every request its playground sends. Set \`endpoint\` on the graphql() adapter (or the source) to the live GraphQL URL, or point playground.proxy at an external proxy URL.`
         : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative and templated URLs carry no origin), so the built-in proxy has no origin to allow and will refuse every request its playground sends. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.`
     );
   }
@@ -1807,9 +1580,9 @@ const proxyAllowlistWarnings = (
 };
 
 /**
- * Write the Ask AI endpoint and, unless the backend runs its own retrieval
+ * Write the assistant 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.
+ * when the assistant is disabled.
  */
 const writeAskFiles = async (
   project: BlumeProject,
@@ -1817,21 +1590,20 @@ const writeAskFiles = async (
   write: (path: string, content: string) => Promise<boolean>,
   modules: RuntimeModules
 ): Promise<void> => {
-  const { ask } = project.config.ai;
-  if (!(ask?.enabled && !ask.endpoint)) {
+  const { assistant } = project.config.ai;
+  if (!(assistant?.enabled && !assistant.endpoint)) {
     return;
   }
-  const grounded = ask.provider !== "inkeep";
-  if (grounded) {
+  const backend = resolveAskBackend(assistant.provider);
+  if (backend.grounded) {
     modules.set("blume:ask-data", JSON.stringify(await buildAskData(project)));
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
-    askEndpointTemplate(resolveAskBackend(ask), grounded, {
-      cors: ask.cors,
-      instructions: ask.instructions,
-      reasoning: ask.reasoning,
-      retrieval: ask.retrieval,
+    askEndpointTemplate(backend, {
+      cors: assistant.cors,
+      instructions: assistant.instructions,
+      retrieval: assistant.retrieval,
     })
   );
 };
@@ -1871,6 +1643,36 @@ export const diagnosticWarning = (diagnostic: Diagnostic): string =>
     ? `${diagnostic.message} ${diagnostic.suggestion}`
     : diagnostic.message;
 
+/**
+ * Missing-dependency preflight: the search provider's SDK, content source
+ * SDKs, the assistant backend's provider SDK, the deployment adapter's package,
+ * and — since React ships with Blume while Vue/Svelte don't — any island
+ * framework's Astro integration. A build fails here, before anything is
+ * written, with the install command for the project's package manager —
+ * otherwise Vite dies later on an opaque unresolved import from the hidden
+ * runtime. Dev warns and keeps serving: only the pages and routes that import
+ * the package break, and installing it is picked up on the next restart.
+ */
+const dependencyPreflight = async (
+  project: BlumeProject,
+  frameworks: Set<string>
+): Promise<string[]> => {
+  const build = project.mode === "build";
+  const diagnostic = await missingDependencyDiagnostic(
+    project.config,
+    project.context.root,
+    build ? "error" : "warning",
+    frameworks
+  );
+  if (!diagnostic) {
+    return [];
+  }
+  if (build) {
+    throw new BlumeError(diagnostic);
+  }
+  return [diagnosticWarning(diagnostic)];
+};
+
 export interface GenerateResult {
   /** Whether any structural file changed (config/page/content config). */
   structuralChange: boolean;
@@ -1879,33 +1681,19 @@ export interface GenerateResult {
 }
 
 /**
- * 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.
+ * Statically analyze the user's `components.ts` (never executing it). Empty for
+ * a project with no components file; throws `BLUME_COMPONENTS_INVALID` for an
+ * override that isn't one of the accepted static forms.
  */
-const buildComponentSlots = async (
+export const analyzeComponentsFile = async (
   componentsFile: string | null
-): Promise<{
-  plan: ComponentSlotPlan;
-  /** MDX tags the overrides define (for the unknown-component check). */
-  tags: string[];
-  warnings: string[];
-}> => {
-  const analysis = componentsFile
+): Promise<ComponentOverrideAnalysis> =>
+  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 : [],
-  };
-};
+    : emptyComponentOverrides();
 
 /** The OG endpoint fonts for a scanned project (see {@link resolveOgFonts}). */
 const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
@@ -2057,7 +1845,7 @@ export const generateRuntime = async (
   const homeLinkHeader =
     buildHomeLinkHeader(config, contentRoutes) ?? undefined;
 
-  const askEnabled = config.ai.ask?.enabled ?? false;
+  const assistantEnabled = config.ai.assistant?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
   // Every route's source Markdown: published as `blume:raw-markdown` below,
@@ -2072,10 +1860,10 @@ export const generateRuntime = async (
   // entryId so i18n duplicates of one entry write a single file. Collected here
   // so math detection also sees staged bodies (they never live under root).
   const staged = collectStaged(project);
-  // 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. Independent of
-  // the discovery reads, so it joins the same parallel batch.
+  // Statically analyze `components.ts` overrides (never executed): drives
+  // hydration on layout/mdx overrides, string-path resolution, and the
+  // "framework component with no client mode" diagnostic. Independent of the
+  // discovery reads, so it joins the same parallel batch.
   const [
     pages,
     detectedReact,
@@ -2085,7 +1873,7 @@ export const generateRuntime = async (
     integrationBridge,
     islandDiscovery,
     exampleDiscovery,
-    componentSlots,
+    overrideAnalysis,
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
@@ -2095,19 +1883,21 @@ export const generateRuntime = async (
     loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
-    buildComponentSlots(context.componentsFile),
+    analyzeComponentsFile(context.componentsFile),
   ]);
-  const {
-    plan: slotPlan,
-    tags: overrideTags,
-    warnings: overrideWarnings,
-  } = componentSlots;
+  // The `islands/` convention and `components.ts` share one static plan: every
+  // entry is imported by path, hydrated ones through a generated wrapper.
+  const slotPlan = planComponentSlots(
+    islandDiscovery.islands,
+    overrideAnalysis
+  );
+  const overrideWarnings = overrideAnalysis.warnings;
   // Expose the discovered examples for agent-facing Markdown downleveling
   // (`<Component>` → source) before any consumer (raw `.md`, MCP, llms) runs.
   project.examples = exampleMarkdownLookup(exampleDiscovery.examples);
 
   // Each island/example framework enables its Astro renderer. React also
-  // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
+  // switches on for any project `.tsx`/`.jsx` and for the assistant; Vue/Svelte are
   // island/example-driven. `.astro` examples need no renderer. Component
   // overrides referencing a framework component enable its renderer too.
   const frameworks = new Set<string>([
@@ -2115,7 +1905,9 @@ export const generateRuntime = async (
     ...exampleDiscovery.examples.map((example) => example.framework),
     ...slotPlan.frameworks,
   ]);
-  const needsReact = detectedReact || askEnabled || frameworks.has("react");
+  const dependencyWarnings = await dependencyPreflight(project, frameworks);
+  const needsReact =
+    detectedReact || assistantEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
 
@@ -2172,7 +1964,7 @@ export const generateRuntime = async (
   // sources, so the `docs` glob would otherwise scan (and watch) the whole
   // project root for nothing — see contentConfigTemplate.
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
-  const docsCollection = resolveDocsCollection(config, context);
+  const docsCollection = resolveDocsCollection(config, context.root);
 
   // All of these write to distinct generated paths and never read one another's
   // output, so the structural files, the per-convention hydration wrappers, and
@@ -2234,12 +2026,8 @@ export const generateRuntime = async (
       // 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(askPath, askComponentTemplate(assistantEnabled)),
       write(join(srcDir, "generated", "components.ts"), slotPlan.module),
-      write(
-        join(srcDir, "generated", "islands.ts"),
-        islandMapTemplate(islandDiscovery.islands)
-      ),
       write(
         join(srcDir, "generated", "examples.ts"),
         exampleMapTemplate(exampleDiscovery.examples, config.basePath)
@@ -2272,18 +2060,7 @@ export const generateRuntime = async (
         })
       ),
     ]),
-    // Per-island hydration wrappers for the `islands/` convention. The map
-    // module (written above, always) imports these; orphans from removed
-    // islands are pruned at the end of the pass.
-    Promise.all(
-      islandDiscovery.islands.map((island) =>
-        write(
-          join(srcDir, "generated", "islands", `${island.name}.astro`),
-          islandWrapperTemplate(island)
-        )
-      )
-    ),
-    // Per-override hydration wrappers for `defineComponents` islands and
+    // Per-override hydration wrappers for `islands/` convention components 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.
@@ -2336,14 +2113,13 @@ export const generateRuntime = async (
     );
   }
 
-  // Changelog index (`/changelog`), rendered through the Update timeline layout.
+  // Changelog index (`/changelog`): every release as a row, grouped by year.
   if (changelogIndex) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
         exportEpub,
         exportPdf,
-        mathEnabled: usesMath,
         needsReact,
         staged: hasStaged,
       })
@@ -2369,8 +2145,9 @@ export const generateRuntime = async (
     write(featuresPath, featuresTemplate(clientFeatures)),
   ]);
 
-  // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
-  if (servesStaticIndex(config.search.provider)) {
+  // Client-loaded adapters (orama, flexsearch) ship a static index + endpoint.
+  const searchAdapter = config.search.provider;
+  if (searchAdapter.mode === "static") {
     const documents = await buildSearchDocuments(project);
     modules.set("blume:search-index", JSON.stringify(documents));
     await write(
@@ -2380,10 +2157,10 @@ export const generateRuntime = async (
   }
 
   // Mixedbread proxies queries through a server endpoint that holds the key.
-  if (config.search.provider === "mixedbread") {
+  if (searchAdapter.kind === "mixedbread") {
     await write(
       join(srcDir, "pages", "api", "search.ts"),
-      mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? "")
+      mixedbreadSearchEndpointTemplate(searchAdapter.options)
     );
   }
 
@@ -2432,9 +2209,8 @@ export const generateRuntime = async (
     );
   }
 
-  // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
-  // self-contained page per source, mounted on its configured route and
-  // regenerated each run.
+  // `scalar()` reference pages. One self-contained page per source, mounted
+  // on its configured route and regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...proxyAllowlistWarnings(config, openApiData),
@@ -2472,23 +2248,15 @@ export const generateRuntime = async (
   // 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,
+    ...overrideAnalysis.mdx.map((entry) => entry.key),
   ]);
-  // Missing-dependency preflights: the search provider's SDK, the Ask AI
-  // backend's provider SDK, the deployment adapter's package, and — since
-  // React ships with Blume while Vue/Svelte don't — any island framework's
-  // Astro integration. Warn early rather than let Vite fail to resolve them
-  // opaquely.
   warnings.push(
     ...validateUsedComponents(
       project.graph.pages,
       knownComponentTags,
       new Set(registry.map((item) => item.name))
     ).map(diagnosticWarning),
-    ...searchProviderWarnings(config.search.provider, context.root),
-    ...askProviderWarnings(config.ai.ask, context.root),
-    ...deploymentAdapterWarnings(config.deployment, context.root),
-    ...islandFrameworkWarnings(frameworks, context.root)
+    ...dependencyWarnings
   );
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
@@ -2521,7 +2289,7 @@ export const generateRuntime = async (
     writeStagedContent(out, staged),
   ]);
 
-  // Remove anything under `.blume/src` this pass didn't write — e.g. an Ask AI
+  // Remove anything under `.blume/src` this pass didn't write — e.g. an assistant
   // endpoint left behind after the feature was switched off.
   await pruneOrphans(srcDir, written);