blume 1.1.3 → 1.2.0

package/src/astro/generate.ts

@@ -1,8 +1,10 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import {
   lstat,
   mkdir,
   readFile,
+  readlink,
   realpath,
   rename,
   rm,
@@ -12,7 +14,7 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
-import { basename, dirname, join, normalize, relative } from "pathe";
+import { basename, dirname, join, normalize, relative, resolve } from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
@@ -39,7 +41,7 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
-import type { Navigation } from "../core/types.ts";
+import type { Diagnostic, Navigation, ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { resolveOgLogo } from "../og/logo.ts";
 import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
@@ -87,6 +89,7 @@ import {
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
+  runtimeDirWithin,
   staticJsonEndpointTemplate,
   runtimeDependencies,
   runtimePackageTemplate,
@@ -118,17 +121,18 @@ const canResolveFrom = (fromDir: string, spec: string): boolean => {
  * that never installed the plugin directly. Resolving from `packageRoot()` binds
  * to Blume's shipped copy regardless of the user's package manager or hoisting.
  */
-const resolveReactCompiler = (
+export const resolveReactCompiler = (
   config: ResolvedConfig,
-  needsReact: boolean
+  needsReact: boolean,
+  pkgDir: string = packageRoot()
 ): string | null => {
   if (!(needsReact && config.react.compiler)) {
     return null;
   }
   try {
-    return createRequire(
-      pathToFileURL(join(packageRoot(), "_.js")).href
-    ).resolve("babel-plugin-react-compiler");
+    return createRequire(pathToFileURL(join(pkgDir, "_.js")).href).resolve(
+      "babel-plugin-react-compiler"
+    );
   } catch {
     return null;
   }
@@ -137,9 +141,9 @@ const resolveReactCompiler = (
 /**
  * Warning (as a spreadable list) for the case where the React Compiler was
  * requested but its plugin couldn't be resolved — so the build silently drops
- * to uncompiled output rather than failing.
+ * to uncompiled output rather than failing. Exported for testing.
  */
-const reactCompilerWarnings = (
+export const reactCompilerWarnings = (
   config: ResolvedConfig,
   needsReact: boolean,
   compilerPath: string | null
@@ -195,8 +199,11 @@ const resolvedAstroHit = (
   }
 };
 
-/** Whether two paths name the same physical directory (realpath equality). */
-const sameRealDir = (a: string, b: string): boolean => {
+/**
+ * Whether two paths name the same physical directory (realpath equality).
+ * Exported for testing.
+ */
+export const sameRealDir = (a: string, b: string): boolean => {
   try {
     return realpathSync(a) === realpathSync(b);
   } catch {
@@ -281,6 +288,17 @@ const linkDepsJunction = async (
     if (!existing.isSymbolicLink()) {
       return;
     }
+    // Already pointing at the right target — leave it alone. This runs on
+    // every dev regeneration, and an unconditional rm+recreate opens a window
+    // in which the Vite server's module resolution races a missing
+    // `node_modules` and 500s intermittently.
+    try {
+      if (resolve(dirname(link), await readlink(link)) === resolve(depsDir)) {
+        return;
+      }
+    } catch {
+      // Unreadable link — replace it below.
+    }
     await rm(link, { force: true });
   }
   await mkdir(dirname(link), { recursive: true });
@@ -587,6 +605,34 @@ const deploymentAdapterWarnings = (
   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;
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
   config.examples.css ? join(root, config.examples.css) : null;
@@ -678,6 +724,22 @@ export const detectUsesMath = async (
   return [...contents, ...staged].some(containsMath);
 };
 
+const hashConfigSource = (source: string): string =>
+  createHash("sha256").update(source).digest("hex");
+
+const loadIntegrationBridge = async (
+  config: ResolvedConfig,
+  context: BlumeProject["context"]
+): Promise<Parameters<typeof astroConfigTemplate>[0]["integrationBridge"]> => {
+  if (config.integrations.length === 0 || !context.configFile) {
+    return;
+  }
+  return {
+    configFile: relative(context.outDir, context.configFile),
+    sourceHash: hashConfigSource(await readOptional(context.configFile)),
+  };
+};
+
 const writeIfChanged = async (
   path: string,
   content: string
@@ -1040,12 +1102,16 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       analytics: config.analytics ?? null,
       appleIcon: resolveAppleIcon(project),
       ask: config.ai.ask?.enabled
-        ? { suggestions: config.ai.ask.suggestions }
+        ? {
+            endpoint: config.ai.ask.endpoint ?? null,
+            suggestions: config.ai.ask.suggestions,
+          }
         : null,
       banner: resolveBanner(config),
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
+      dateFormat: config.dateFormat,
       description: config.description,
       favicon: resolveFavicon(project),
       feedback: config.feedback,
@@ -1233,7 +1299,7 @@ const writeAskFiles = async (
   write: (path: string, content: string) => Promise<boolean>
 ): Promise<void> => {
   const { ask } = project.config.ai;
-  if (!ask?.enabled) {
+  if (!(ask?.enabled && !ask.endpoint)) {
     return;
   }
   const grounded = ask.provider !== "inkeep";
@@ -1268,6 +1334,15 @@ const writeNotFoundPage = async (
   await write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate());
 };
 
+/**
+ * Flatten a diagnostic to a single warning line, appending the suggestion when
+ * one exists. Exported for testing.
+ */
+export const diagnosticWarning = (diagnostic: Diagnostic): string =>
+  diagnostic.suggestion
+    ? `${diagnostic.message} ${diagnostic.suggestion}`
+    : diagnostic.message;
+
 export interface GenerateResult {
   /** Whether any structural file changed (config/page/content config). */
   structuralChange: boolean;
@@ -1304,6 +1379,20 @@ const buildComponentSlots = async (
   };
 };
 
+/**
+ * Whether the docs glob-loader's watcher observes the runtime dir: a
+ * filesystem collection whose base contains it (a migrated, `content.root:
+ * "."` project) — the one layout where the dev watcher must be kept out of
+ * Astro's cache dir. See `devWatchOption` in templates.ts.
+ */
+const contentWatchesRuntimeDir = (
+  hasFilesystemSource: boolean,
+  collectionBase: string,
+  context: ProjectContext
+): boolean =>
+  hasFilesystemSource &&
+  runtimeDirWithin(collectionBase, context.outDir) !== null;
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -1349,6 +1438,7 @@ export const generateRuntime = async (
     usesMath,
     userTheme,
     userExamplesCss,
+    integrationBridge,
     islandDiscovery,
     exampleDiscovery,
     componentSlots,
@@ -1358,6 +1448,7 @@ export const generateRuntime = async (
     detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
+    loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
     buildComponentSlots(context.componentsFile),
@@ -1407,6 +1498,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);
 
   // 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
@@ -1421,10 +1513,16 @@ export const generateRuntime = async (
           askPath,
           config,
           contentRoutes: project.manifest.routes.map((route) => route.path),
+          contentWatchesRuntimeDir: contentWatchesRuntimeDir(
+            hasFilesystemSource,
+            docsCollection.base,
+            context
+          ),
           context,
           dataPath,
           examplesPath,
           examplesThemePath,
+          integrationBridge,
           needsReact,
           needsSvelte,
           needsVue,
@@ -1446,7 +1544,7 @@ export const generateRuntime = async (
       write(
         join(srcDir, "content.config.ts"),
         contentConfigTemplate({
-          collection: resolveDocsCollection(config, context),
+          collection: docsCollection,
           config,
           context,
           filesystem: hasFilesystemSource,
@@ -1666,11 +1764,7 @@ export const generateRuntime = async (
     ...[
       ...validateNavTargets(project.graph.navigation, navTargetRoutes),
       ...validateSearchPopularIcons(config.search.popular),
-    ].map((diagnostic) =>
-      diagnostic.suggestion
-        ? `${diagnostic.message} ${diagnostic.suggestion}`
-        : diagnostic.message
-    )
+    ].map(diagnosticWarning)
   );
 
   // Unknown-component check: a `<Tag>` in MDX that isn't a built-in, an island,
@@ -1679,40 +1773,17 @@ export const generateRuntime = async (
     ...islandDiscovery.islands.map((island) => island.name),
     ...overrideTags,
   ]);
+  // Missing-dependency preflights: the search provider's 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((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
-  // (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.
-  for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
-    if (
-      !(canResolveFrom(context.root, dep) || canResolveFrom(packageRoot(), dep))
-    ) {
-      warnings.push(
-        `Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
-      );
-    }
-  }
-
-  // React ships with Blume; Vue/Svelte islands need their Astro integration
-  // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(
+    ).map(diagnosticWarning),
+    ...searchProviderWarnings(config.search.provider, context.root),
     ...deploymentAdapterWarnings(config.deployment, context.root),
     ...islandFrameworkWarnings(frameworks, context.root)
   );

package/src/astro/templates.ts

@@ -87,7 +87,14 @@ const WRANGLER_CONFIG_FILES = [
 ];
 
 const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
-  const args: string[] = ['prerenderEnvironment: "node"'];
+  // Every Blume HTML route prerenders (the only server routes are API
+  // endpoints), so images are optimized at build time with sharp. The
+  // adapter's default (`cloudflare-binding`) would instead declare a runtime
+  // `IMAGES` binding in the generated wrangler config that nothing uses.
+  const args: string[] = [
+    'prerenderEnvironment: "node"',
+    'imageService: "compile"',
+  ];
   const wranglerPath = WRANGLER_CONFIG_FILES.map((file) =>
     join(context.root, file)
   ).find((file) => existsSync(file));
@@ -104,6 +111,37 @@ const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
   return `{ ${args.join(", ")} }`;
 };
 
+/**
+ * Without a configured driver, `@astrojs/cloudflare` force-enables KV-backed
+ * sessions and declares a `SESSION` kv_namespaces entry in the generated
+ * wrangler config — which `wrangler deploy` then requires a real KV namespace
+ * for, even though Blume never reads `Astro.session`. An explicit in-memory
+ * driver keeps the binding out. Swap for Astro's session opt-out once
+ * withastro/astro#16871 ships in the supported range.
+ */
+const resolveSessionOption = (deployment: {
+  adapter: string | null;
+  output: string;
+}): string =>
+  deployment.output === "server" && deployment.adapter === "cloudflare"
+    ? "\n  session: { driver: sessionDrivers.memory() },"
+    : "";
+
+/** The named imports the generated config pulls from `astro/config`. */
+const astroConfigImportLine = (options: {
+  hasFonts: boolean;
+  hasSession: boolean;
+}): string => {
+  const names = ["defineConfig"];
+  if (options.hasFonts) {
+    names.push("fontProviders");
+  }
+  if (options.hasSession) {
+    names.push("sessionDrivers");
+  }
+  return `import { ${names.join(", ")} } from "astro/config";`;
+};
+
 /**
  * Integration packages the generated runtime imports. Declaring them in
  * `.blume/package.json` lets Astro's framework-package crawl discover and bundle
@@ -138,7 +176,7 @@ export const runtimeDependencies = (options: {
   // (and the user installs) exactly the backend it uses — nothing more.
   deps.push(...searchProviderMeta(config.search.provider).runtimeDeps);
   // Ask AI's provider SDK, when its backend needs one (gateway uses core `ai`).
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     const askDep = askBackendRuntimeDep(config.ai.ask);
     if (askDep) {
       deps.push(askDep);
@@ -261,6 +299,65 @@ const reactIntegration = (compilerPath: string | null | undefined): string =>
     ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })`
     : `react({ ${REACT_EXCLUDE} })`;
 
+/**
+ * The `server.watch` block for the generated dev config. Keeps the watcher out
+ * of Astro's cache dir — but ONLY when the docs collection is rooted at a
+ * directory containing the runtime dir (a migrated, `content.root: "."`
+ * project). There, the glob loader's watcher match (`picomatch.isMatch(entry,
+ * pattern)` with array-OR semantics, where any negated pattern matches
+ * unrelated files) fires on every `.blume/.astro` write — "No entry type
+ * found" noise, and a `data-store.json` event can re-ingest the store file as
+ * a JSON entry and loop the sync. Everywhere else the watcher MUST see
+ * `.astro/data-store.json`: its change events are the only trigger for
+ * Astro's dev-time content invalidation (see vite-plugin-content-virtual-mod),
+ * and `.md` bodies are rendered into the store at load time — so ignoring the
+ * file serves stale `.md` HTML on every request until the server restarts,
+ * even though the loader logs a reload.
+ */
+const devWatchOption = (
+  outDir: string,
+  contentWatchesRuntimeDir: boolean | undefined
+): string =>
+  contentWatchesRuntimeDir
+    ? `
+      // Astro's cache dir sits inside the docs collection, whose watcher would
+      // otherwise churn (and can loop) on Astro's own writes. Trade-off: .md
+      // body edits need a dev-server restart in this layout.
+      watch: {
+        ignored: ${JSON.stringify([join(outDir, ".astro", "**")])},
+      },`
+    : "";
+
+interface IntegrationBridgeOptions {
+  /** Config path relative to the generated Astro config. */
+  configFile: string;
+  /** SHA-256 used to invalidate Astro's generated config. */
+  sourceHash?: string;
+}
+
+const renderIntegrationBridge = (
+  bridge: IntegrationBridgeOptions | undefined
+) => {
+  if (!bridge) {
+    return {
+      configSourceMarker: "",
+      userConfigImports: "",
+      userConfigSetup: "",
+      userIntegrationSpread: "",
+    };
+  }
+  return {
+    configSourceMarker: bridge.sourceHash
+      ? `// Blume config source SHA-256: ${bridge.sourceHash}\n`
+      : "",
+    userConfigImports: `import { dirname, resolve } from "node:path";\nimport { fileURLToPath } from "node:url";\nimport { createModuleLoader } from "blume/core/load-module.ts";\n`,
+    userConfigSetup: `const loadBlumeConfig = createModuleLoader();\nconst blumeConfig = await loadBlumeConfig(resolve(dirname(fileURLToPath(import.meta.url)), ${JSON.stringify(
+      bridge.configFile
+    )}));\n\n`,
+    userIntegrationSpread: ", ...(blumeConfig?.integrations ?? [])",
+  };
+};
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -286,6 +383,15 @@ export const astroConfigTemplate = (options: {
   reactCompilerPath?: string | null;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
+  /**
+   * Whether the filesystem `docs` collection is rooted at a directory that
+   * contains the runtime dir (a migrated, `content.root: "."` project) — the
+   * only layout where the dev watcher must be kept out of Astro's cache dir.
+   * See {@link devWatchOption} for why this must stay scoped.
+   */
+  contentWatchesRuntimeDir?: boolean;
+  /** Bridge used to load configured integrations without serializing them. */
+  integrationBridge?: IntegrationBridgeOptions;
 }): string => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
@@ -331,6 +437,8 @@ export const astroConfigTemplate = (options: {
   const adapterOption =
     server && deployment.adapter ? `\n  adapter: ${adapterExpr},` : "";
 
+  const sessionOption = resolveSessionOption(deployment);
+
   const siteOption = deployment.site
     ? `\n  site: ${JSON.stringify(deployment.site)},`
     : "";
@@ -388,9 +496,10 @@ export const astroConfigTemplate = (options: {
         )
         .join(", ")}],`
     : "";
-  const defineConfigImport = fontEntries.length
-    ? `import { defineConfig, fontProviders } from "astro/config";`
-    : `import { defineConfig } from "astro/config";`;
+  const defineConfigImport = astroConfigImportLine({
+    hasFonts: fontEntries.length > 0,
+    hasSession: sessionOption.length > 0,
+  });
 
   // Framework renderers are only wired in when an island (or Ask AI, for React)
   // needs them. The core theme is Astro-first and ships no client JS.
@@ -446,19 +555,30 @@ export const astroConfigTemplate = (options: {
     `blumeIntegration(${JSON.stringify({ base: deployment.base, contentRoutes, pages })})`
   );
 
+  const watchOption = devWatchOption(
+    context.outDir,
+    options.contentWatchesRuntimeDir
+  );
+  const {
+    configSourceMarker,
+    userConfigImports,
+    userConfigSetup,
+    userIntegrationSpread,
+  } = renderIntegrationBridge(options.integrationBridge);
+
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
-${defineConfigImport}
+${configSourceMarker}${userConfigImports}${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
 ${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
-export default defineConfig({
+${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
   outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
-  output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
-  integrations: [${integrations.join(", ")}],
+  output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
+  integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
       basePath: config.basePath,
@@ -480,18 +600,25 @@ export default defineConfig({
   devToolbar: { enabled: false },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
-    // Mermaid (lazy-loaded client-side for diagrams) statically imports dayjs as
-    // CJS (\`dayjs/dayjs.min.js\`). In dev, an un-pre-bundled dependency is served
-    // as raw ESM, and that UMD file exposes no \`default\` export, so mermaid
-    // throws on load and diagrams render blank. Forcing mermaid through the dep
-    // optimizer bundles dayjs with correct CJS interop. In a standalone install
-    // Blume's dynamic \`import("mermaid")\` lives inside \`node_modules/blume\`,
-    // which Vite's optimizer scan doesn't crawl, so mermaid is never discovered
-    // on its own — hence the explicit include. mermaid resolves through the
-    // \`blume\` package (it isn't a direct dep of the generated project), so the
-    // nested \`blume > mermaid\` form is required. Production (Rollup) already
-    // handles the interop, so this only affects dev.
-    optimizeDeps: { include: ["blume > mermaid"] },
+    // The lazy client-side imports both land on CJS/UMD files: mermaid (for
+    // diagrams) statically imports dayjs as CJS (\`dayjs/dayjs.min.js\`), and
+    // epub-gen-memory's browser bundle is a browserified UMD. In dev, an
+    // un-pre-bundled dependency is served as raw ESM, where such a file
+    // exposes no \`default\` export — mermaid throws on load and diagrams
+    // render blank, and the EPUB export throws \`epub is not a function\`
+    // (the UMD finds no \`exports\`/\`define\` and strands its callable on
+    // \`window.epubGen\` instead). Forcing them through the dep optimizer
+    // restores the CJS interop. In a standalone install these dynamic imports
+    // live inside \`node_modules/blume\`, which Vite's optimizer scan doesn't
+    // crawl, so neither is discovered on its own — hence the explicit
+    // includes. They resolve through the \`blume\` package (they aren't direct
+    // deps of the generated project), so the nested \`blume > x\` form is
+    // required, and epub-gen-memory must name the \`/bundle\` subpath that is
+    // actually imported: optimizing the package root leaves that entry out.
+    // Production (Rollup) already handles the interop, so this only affects dev.
+    optimizeDeps: {
+      include: ["blume > mermaid", "blume > epub-gen-memory/bundle"],
+    },
     // Blume's render-time deps are forced external on both build environments so
     // native bindings resolve at runtime and isolated linkers don't bundle
     // symlinked store copies (which would surface their children as unresolvable
@@ -522,16 +649,7 @@ export default defineConfig({
     server: {
       fs: {
         allow: ${JSON.stringify(fsAllow)},
-      },
-      // Keep the file watcher out of Astro's own cache dir. In a migrated
-      // (root-rooted) project the docs collection is rooted at the project dir,
-      // so its glob-loader watcher would otherwise fire on every write Astro
-      // makes under .blume/.astro (data-store.json, content module manifests,
-      // self-hosted fonts) -- pure noise the loader logs as "No entry type
-      // found". Vite appends this to its default ignores.
-      watch: {
-        ignored: ${JSON.stringify([join(context.outDir, ".astro", "**")])},
-      },
+      },${watchOption}
     },
   },
 });
@@ -542,6 +660,21 @@ export default defineConfig({
 export const stagedContentDir = (outDir: string): string =>
   join(outDir, "content");
 
+/**
+ * The runtime dir relative to the docs collection `base` when it sits inside
+ * it (a migrated, `content.root: "."` project) — null when it lives elsewhere.
+ * Drives both the collection's negative glob (`contentConfigTemplate`) and
+ * whether the dev watcher is kept out of Astro's cache dir (the
+ * `contentWatchesRuntimeDir` option of `astroConfigTemplate`).
+ */
+export const runtimeDirWithin = (
+  base: string,
+  outDir: string
+): string | null => {
+  const rel = relative(base, outDir);
+  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
+};
+
 /**
  * Astro's glob loader resolves `base` with `new URL(base, config.root)`. On
  * Windows an absolute path like `C:\\docs\\content` makes `new URL` parse the
@@ -585,11 +718,8 @@ export const contentConfigTemplate = (options: {
   // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
   // staged bodies under `.blume/content`, …) as entries. This matters when
   // the collection base is the project root (a migrated `.`-rooted project).
-  const outDirRel = relative(collectionBase, context.outDir);
-  const outDirIgnore =
-    outDirRel && !outDirRel.startsWith("..") && !isAbsolute(outDirRel)
-      ? [`!${outDirRel}/**`]
-      : [];
+  const outDirRel = runtimeDirWithin(collectionBase, context.outDir);
+  const outDirIgnore = outDirRel ? [`!${outDirRel}/**`] : [];
 
   // With no filesystem source, no route renders through `docs`, so glob nothing.
   // Beyond skipping wasted work, this is the only thing that keeps Astro's
@@ -806,7 +936,11 @@ import data from "blume:data";
 const { strings } = Astro.props;
 ---
 
-<AskAI strings={strings ?? data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />
+<AskAI
+  endpoint={data.config.ask?.endpoint ?? undefined}
+  strings={strings ?? data.ui.ask}
+  suggestions={data.config.ask?.suggestions ?? []}
+/>
 `
     : `---
 // Generated by Blume. Do not edit.
@@ -1151,6 +1285,7 @@ export async function GET({ props }: { props: { title: string } }) {
 export const scalarReferenceTemplate = (options: {
   configuration: Record<string, unknown>;
   dataImport: string;
+  noindex?: boolean;
   route: string;
   title: string;
 }): string =>
@@ -1185,6 +1320,7 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
   favicon={data.config.favicon}
   appleIcon={data.config.appleIcon}
   navigation={data.navigation}
+  noindex={${options.noindex === true}}
   pageTitle={${JSON.stringify(options.title)}}
   route={${JSON.stringify(options.route)}}
   searchEnabled={data.config.search.enabled}