blume 1.5.3 → 1.6.1

package/src/astro/templates.ts

@@ -8,6 +8,7 @@ import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
+import { TOC_HIDDEN_KEY } from "../core/heading-markers.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
@@ -16,11 +17,12 @@ import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import type { OgFont, OgFontFamilies } from "../og/card.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
-import { buildFontEntries } from "../theme/fonts.ts";
+import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
 import type { BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
 import type { OgCustomRoute } from "./pages.ts";
+import { RUNTIME_MODULE_FILES } from "./runtime-modules.ts";
 
 const WORKSPACE_MARKERS = [
   ".git",
@@ -289,9 +291,38 @@ const adapterRoot = (context: ProjectContext): string =>
  * re-optimization. A blanket `/node_modules/` exclude would instead switch the
  * React Compiler off for Blume's own components in published installs (they
  * resolve under `node_modules/blume/src`, and exclude beats include in the
- * plugin's filter), so only the pre-bundle cache is excluded.
+ * plugin's filter), so only the pre-bundle cache is excluded. The hidden runtime
+ * relocates that cache to `<runtime>/.cache/vite` (see `cacheOptions`), so both
+ * the default and the relocated path are excluded.
  */
-const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//]`;
+const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//, /\/\.cache\/vite\//]`;
+
+/**
+ * The `cacheDir` entries for the generated config's top level and its `vite`
+ * block. The hidden runtime's `node_modules` is a junction into Blume's own
+ * package directory, and Astro (`node_modules/.astro`: the content data store,
+ * the fonts cache) and Vite (`node_modules/.vite`: pre-bundled deps) both
+ * default their caches under the project's `node_modules`. Two Blume projects
+ * that resolve the same package (a monorepo building docs and a sandbox in
+ * parallel) would therefore share one data store, and each build would serve
+ * the other's content — or 404 on entries the other cleared. Keep every cache
+ * inside the runtime dir instead. An ejected project (`generatedModulesDir`
+ * set) has real `node_modules`, so it keeps the defaults.
+ */
+const runtimeCacheOptions = (
+  context: ProjectContext,
+  generatedModulesDir: string | undefined
+) => {
+  if (generatedModulesDir !== undefined) {
+    return { astro: "", vite: "" };
+  }
+  return {
+    astro: `
+  cacheDir: ${JSON.stringify(`${context.outDir}/.cache/astro`)},`,
+    vite: `
+    cacheDir: ${JSON.stringify(`${context.outDir}/.cache/vite`)},`,
+  };
+};
 
 /**
  * The `react()` integration call. When `compilerPath` is set (the resolved
@@ -307,35 +338,6 @@ 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;
@@ -387,8 +389,11 @@ interface OptimizeDepsConfig {
  * the Vite root is the generated runtime, so user pages, convention islands,
  * and alias-reachable components all live outside it and are otherwise only
  * crawled when first requested. The compiler runtime rides the include list
- * because it is Babel-injected and no source scan can see it. See the
- * optimizeDeps comment in the generated config for the failure this prevents.
+ * because it is Babel-injected and no source scan can see it. @vitejs/plugin-react
+ * would add it itself, but only when the babel plugin is passed by its bare
+ * name (`getReactCompilerPlugin` is an exact string match) — Blume passes an
+ * absolute path (see `reactIntegration`), which that check never matches. See
+ * the optimizeDeps comment in the generated config for the failure this prevents.
  */
 const resolveOptimizeDeps = (options: {
   aliases: Record<string, string> | undefined;
@@ -419,6 +424,40 @@ const resolveOptimizeDeps = (options: {
   return { optimizeDepsEntries, optimizeDepsInclude };
 };
 
+/**
+ * How the generated config reaches the runtime data modules (`blume:data`,
+ * the search index, …): served from memory by `runtimeModulesPlugin` in the
+ * hidden runtime, or aliased to JSON files under `generatedModulesDir` for an
+ * ejected project, which has no CLI to publish them (see `runtime-modules.ts`).
+ */
+interface RuntimeModuleWiring {
+  /** `resolve.alias` entries (one per module), empty in the in-memory form. */
+  aliasLines: string;
+  /** Extra `blume/astro` imports the wiring needs. */
+  imports: string[];
+  /** Leading `vite.plugins` entry, empty in the file-alias form. */
+  pluginEntry: string;
+}
+
+const renderRuntimeModuleWiring = (
+  generatedModulesDir: string | undefined
+): RuntimeModuleWiring => {
+  if (generatedModulesDir === undefined) {
+    return {
+      aliasLines: "",
+      imports: ["runtimeModulesPlugin"],
+      pluginEntry: "runtimeModulesPlugin(), ",
+    };
+  }
+  const aliasLines = [...RUNTIME_MODULE_FILES]
+    .map(
+      ([id, file]) =>
+        `\n        ${JSON.stringify(id)}: ${JSON.stringify(`${generatedModulesDir}/${file}`)},`
+    )
+    .join("");
+  return { aliasLines, imports: [], pluginEntry: "" };
+};
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -429,13 +468,18 @@ export const astroConfigTemplate = (options: {
   contentRoutes: string[];
   /** The generated Ask trigger (`blume:ask`); renders nothing when Ask is off. */
   askPath: string;
-  dataPath: string;
   examplesPath: string;
   /** The example-preview Tailwind entry (`blume:examples-theme`). */
   examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
-  openapiPath: string;
+  /**
+   * Where the runtime data modules (`blume:data`, the search index, …) live as
+   * JSON files, for a project with no CLI to publish them in memory (eject):
+   * each id is aliased to its file under this directory. Absent, the modules
+   * are served from memory by `runtimeModulesPlugin` — the hidden runtime.
+   */
+  generatedModulesDir?: string;
   /**
    * Absolute path to `babel-plugin-react-compiler` when the React Compiler is
    * enabled (resolved from Blume's package root by the caller); null/absent
@@ -445,26 +489,34 @@ export const astroConfigTemplate = (options: {
   /** 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.
+   * The docs collection's content root; bounds `<include>` resolution in the
+   * processors and locates the include graph for dev-server invalidation.
    */
-  contentWatchesRuntimeDir?: boolean;
+  contentRoot?: string;
   /** Bridge used to load configured integrations without serializing them. */
   integrationBridge?: IntegrationBridgeOptions;
 }): string => {
-  const { context, config, needsReact, pages, dataPath, themePath } = options;
+  const { context, config, needsReact, pages, themePath } = options;
+
+  const { astro: cacheOptions, vite: viteCacheOption } = runtimeCacheOptions(
+    context,
+    options.generatedModulesDir
+  );
   const {
     askPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
+    generatedModulesDir,
     needsSvelte,
     needsVue,
-    openapiPath,
     searchClientPath,
   } = options;
+  const {
+    aliasLines: runtimeModuleAliasLines,
+    imports: runtimeModuleImports,
+    pluginEntry: runtimeModulesPluginEntry,
+  } = renderRuntimeModuleWiring(generatedModulesDir);
   const { deployment } = config;
   const userAliasLines = renderUserAliases(options.aliases);
   const server = deployment.output === "server";
@@ -552,7 +604,12 @@ export const astroConfigTemplate = (options: {
   // `fontProviders` is only imported when at least one font is configured.
   // Local variant sources are emitted as absolute paths (the Astro root is
   // `.blume/`, not the user's project, so root-relative paths would miss).
-  const fontEntries = buildFontEntries(config.theme.fonts);
+  // Subsets follow the configured locales (a Vietnamese site loads the
+  // `vietnamese` faces) unless a family pins its own.
+  const fontEntries = buildFontEntries(
+    config.theme.fonts,
+    fontLocaleCodes(config.i18n)
+  );
   const fontsOption = fontEntries.length
     ? `\n  fonts: [${fontEntries
         .map((font) =>
@@ -588,6 +645,8 @@ export const astroConfigTemplate = (options: {
                 font.cssVariable
               )}, weights: ${JSON.stringify(
                 font.weights
+              )}, subsets: ${JSON.stringify(
+                font.subsets
               )}, fallbacks: ${JSON.stringify(font.fallbacks)} }`
         )
         .join(", ")}],`
@@ -606,8 +665,9 @@ export const astroConfigTemplate = (options: {
     : "";
   const blumeImports = [
     "blumeIntegration",
+    "includeHmrPlugin",
     "prerenderDepsPlugin",
-    "serverAppResolvePlugin",
+    ...runtimeModuleImports,
     ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
@@ -632,6 +692,7 @@ export const astroConfigTemplate = (options: {
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      contentRoot: options.contentRoot,
       deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}) })`,
@@ -657,10 +718,6 @@ export const astroConfigTemplate = (options: {
     })})`
   );
 
-  const watchOption = devWatchOption(
-    context.outDir,
-    options.contentWatchesRuntimeDir
-  );
   const {
     configSourceMarker,
     userConfigImports,
@@ -678,13 +735,14 @@ ${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`)},
+  publicDir: ${JSON.stringify(`${context.root}/public`)},${cacheOptions}
   output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${imageOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      contentRoot: options.contentRoot,
       deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}),
@@ -705,8 +763,10 @@ ${userConfigSetup}export default defineConfig({
   // request latency behind the user's intent, so most navigations swap
   // instantly.
   prefetch: { prefetchAll: true },
-  vite: {
-    plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
+  vite: {${viteCacheOption}
+    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${JSON.stringify(
+      `${context.outDir}/src/generated/includes.json`
+    )}), prerenderDepsPlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
     // FIRST run. The Vite root is the generated runtime, so user pages,
     // islands, and aliased components live outside it and are only crawled
@@ -753,18 +813,16 @@ ${userConfigSetup}export default defineConfig({
     resolve: {
       alias: {
         "blume:ask": ${JSON.stringify(askPath)},
-        "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
-        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
+        "blume:theme": ${JSON.stringify(themePath)},${runtimeModuleAliasLines}${userAliasLines}
       },
     },
     server: {
       fs: {
         allow: ${JSON.stringify(fsAllow)},
-      },${watchOption}
+      },
     },
   },
 });
@@ -778,14 +836,11 @@ export const stagedContentDir = (outDir: string): string =>
 /**
  * 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`).
+ * Drives the collection's negative glob in `contentConfigTemplate`, which both
+ * keeps runtime-dir files out of the collection and (Astro's watcher honors
+ * negated patterns) keeps the content watcher off Astro's own `.astro` writes.
  */
-export const runtimeDirWithin = (
-  base: string,
-  outDir: string
-): string | null => {
+const runtimeDirWithin = (base: string, outDir: string): string | null => {
   const rel = relative(base, outDir);
   return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
 };
@@ -836,15 +891,11 @@ export const contentConfigTemplate = (options: {
   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
-  // content-layer *watcher* out of `.blume/`: an all-staged project roots the
-  // collection at the project dir (which contains `.blume/.astro/fonts`, rewritten on every
-  // request), and the watcher's match test is `picomatch.isMatch(path, pattern)`
-  // — with array-OR semantics, any `!ignored/**` negation *matches* unrelated
-  // files, so negative patterns can't exclude a subtree there. An empty pattern
-  // matches nothing, so the watcher stays silent. The collection is still
-  // declared below so `getCollection("docs")` / `getEntry` resolve (to empty).
+  // With no filesystem source, no route renders through `docs`, so glob
+  // nothing: an all-staged project roots the collection at the project dir,
+  // and a patterned glob would scan (and watch) the whole project for nothing.
+  // The collection is still declared below so `getCollection("docs")` /
+  // `getEntry` resolve (to empty).
   const filesystem = options.filesystem ?? true;
   const docsPattern = filesystem
     ? [
@@ -880,13 +931,17 @@ const staged = defineCollection({
   return `// Generated by Blume. Do not edit.
 import { defineCollection } from "astro:content";
 import { glob } from "astro/loaders";
+import { withIncludeRefresh } from "blume/astro";
 
+// withIncludeRefresh keeps <include>-bearing pages fresh: plain .md entries
+// are rendered at sync time and digest-cached on the page file alone, so a
+// partial edit (or a warm-cache rebuild after one) would serve stale HTML.
 const docs = defineCollection({
-  loader: glob({
+  loader: withIncludeRefresh(glob({
     pattern: ${JSON.stringify(docsPattern)},
     base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
-  }),
+  }), ${JSON.stringify(`${context.outDir}/src/generated/includes.json`)}),
 });
 ${stagedBlock}
 export const collections = { docs${options.staged ? ", staged" : ""} };
@@ -955,7 +1010,7 @@ export const askEndpointTemplate = (
   if (grounded) {
     imports.push(
       'import { createAskContext } from "blume/ai/ask-context.ts";',
-      'import askData from "../../generated/ask-data.json";'
+      'import askData from "blume:ask-data";'
     );
     const groundFields: string[] = [];
     if (instructions) {
@@ -1103,7 +1158,7 @@ const { strings } = Astro.props;
 /** Generate the static search index endpoint (`/blume-search.json`). */
 export const searchEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import documents from "../generated/search.json";
+import documents from "blume:search-index";
 
 export const prerender = true;
 
@@ -1281,7 +1336,7 @@ export const POST: APIRoute = async ({ request }) => {
  */
 export const rawMarkdownEndpointTemplate = (kind: "md" | "mdx"): string =>
   `// Generated by Blume. Do not edit.
-import raw from "../generated/raw-markdown.json";
+import raw from "blume:raw-markdown";
 
 export const prerender = true;
 
@@ -1331,7 +1386,7 @@ import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import type { APIRoute } from "astro";
-import assets from "../../generated/content-assets.json";
+import assets from "blume:content-assets";
 
 export const prerender = true;
 
@@ -1423,22 +1478,18 @@ export const mcpPageFile = (route: string): string =>
  * generated data snapshot. Runs server-side (no prerender) so agents can query
  * the docs over Streamable HTTP.
  */
-export const mcpEndpointTemplate = (route: string): string => {
-  const clean = trimChar(route, "/");
-  const up = "../".repeat(clean.split("/").length);
-  return `// Generated by Blume. Do not edit.
+export const mcpEndpointTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
 import { createMcpFetchHandler } from "blume/ai/mcp/server.ts";
-import type { McpData } from "blume/ai/mcp/data.ts";
-import data from "${up}generated/mcp-data.json";
+import data from "blume:mcp-data";
 
 export const prerender = false;
 
-const handler = createMcpFetchHandler(data as McpData);
+const handler = createMcpFetchHandler(data);
 
 export const ALL: APIRoute = ({ request }) => handler(request);
 `;
-};
 
 /**
  * Generate the playground's CORS proxy endpoint
@@ -1487,7 +1538,7 @@ export function GET() {
  */
 export const rssEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import feeds from "../../generated/rss.json";
+import feeds from "blume:rss";
 
 export const prerender = true;
 
@@ -1509,7 +1560,16 @@ export function GET({ props }: { props: { section: string } }) {
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
-  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {},
+  og: {
+    families?: OgFontFamilies;
+    fonts?: OgFont[];
+    /**
+     * Whether a page's own description may replace the site-wide subtitle.
+     * `false` when `seo.og.description` is `false`, which hides the subtitle
+     * on every card, page text included. Defaults to `true`.
+     */
+    pageDescriptions?: boolean;
+  } = {},
   includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
@@ -1533,44 +1593,69 @@ const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
 
+// A page's own description (its \`seo.description\`, else \`description\`) is
+// the card subtitle, so the image says what the page's og:description says.
+// Pages without one fall back to the site-wide subtitle at render time.
+// \`seo.og.description: false\` hides the subtitle on every card, page text
+// included, which is what switches this off.
+const pageDescriptions = ${og.pageDescriptions !== false};
+
+interface CardProps {
+  title: string;
+  description: string | null;
+}
+
 export function getStaticPaths() {
   const seen = new Set<string>();
-  const paths: { params: { slug: string }; props: { title: string } }[] = [];
-  const add = (slug: string, title: string) => {
+  const paths: { params: { slug: string }; props: CardProps }[] = [];
+  const add = (slug: string, title: string, description: string | null) => {
     if (seen.has(slug)) {
       return;
     }
     seen.add(slug);
-    paths.push({ params: { slug }, props: { title } });
+    paths.push({
+      params: { slug },
+      props: { title, description: pageDescriptions ? description : null },
+    });
   };
   // A custom page wins over a content route sharing its path, so add it first.
+  // Its description is unknown at generate time, so it takes the site subtitle.
   for (const route of customRoutes) {
-    add(route.slug, route.title);
+    add(route.slug, route.title, null);
   }
   for (const route of data.routes) {
-    add(route.path === "/" ? "index" : route.path.slice(1), route.title);
+    add(
+      route.path === "/" ? "index" : route.path.slice(1),
+      route.title,
+      route.description
+    );
   }${
     includeChangelog
       ? `
   // The generated changelog index is not a content route, so it needs its own
   // card. Added last: a custom page or content route owning /changelog wins.
-  add("changelog", data.ui.changelog?.title ?? "Changelog");`
+  add(
+    "changelog",
+    data.ui.changelog?.title ?? "Changelog",
+    data.ui.changelog?.description ?? null
+  );`
       : ""
   }
   return paths;
 }
 
-// Footer branding shared by every card. The repo slug reuses the header link
-// URL; the site text (host plus deployment base) is resolved at generate time.
-const repoSlug = data.config.repoUrl
-  ? data.config.repoUrl.split("github.com/")[1]
+// Footer branding shared by every card. The slug comes from the configured
+// repo rather than the URL, so an Enterprise host reads the same as github.com;
+// the site text (host plus deployment base) is resolved at generate time.
+const repoSlug = data.config.github
+  ? \`\${data.config.github.owner}/\${data.config.github.repo}\`
   : undefined;
 
-export async function GET({ props }: { props: { title: string } }) {
+export async function GET({ props }: { props: CardProps }) {
   const png = await renderOgImage({
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
-    description: data.config.og.description,
+    description: props.description ?? data.config.og.description,
     families,
     fonts,
     logo: data.config.og.logo,
@@ -1594,13 +1679,11 @@ export async function GET({ props }: { props: { title: string } }) {
  * but mounted inside Blume's {@link ReferenceLayout} so the page keeps Blume's
  * navbar on top. `renderMode: "client"` mounts the reference into a container
  * element (rather than emitting a full HTML document), which is what lets it
- * live inside our shell. `dataImport` is the route-depth-aware relative path to
- * the generated data module the layout reads.
+ * live inside our shell.
  */
 export const scalarReferenceTemplate = <Configuration extends object>(options: {
   /** Scalar options forwarded verbatim (spec/theme config plus the author's `scalar` escape hatch). */
   configuration: Configuration;
-  dataImport: string;
   noindex?: boolean;
   route: string;
   title: string;
@@ -1609,7 +1692,7 @@ export const scalarReferenceTemplate = <Configuration extends object>(options: {
 // Generated by Blume. Do not edit.
 import { ScalarComponent } from "@scalar/astro";
 import ReferenceLayout from "blume/components/layout/ReferenceLayout.astro";
-import data from ${JSON.stringify(options.dataImport)};
+import data from "blume:data";
 
 export const prerender = true;
 
@@ -1786,7 +1869,18 @@ const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
 }
-const { Content, headings } = await render(entry);
+const { Content, headings: allHeadings, remarkPluginFrontmatter } = await render(entry);
+// \`[!toc]\`-marked headings render on the page but stay out of the table of
+// contents; the heading plugin reports their slugs through the render's
+// frontmatter (see markdown/heading-anchors.ts). Only the plugin's array
+// counts: \`frontmatter.extend\` can declare the same key, and on a page with
+// no headings that user-supplied value would pass straight through.
+const tocHiddenRaw = remarkPluginFrontmatter?.${TOC_HIDDEN_KEY};
+const tocHidden = new Set(Array.isArray(tocHiddenRaw) ? tocHiddenRaw : []);
+const headings =
+  tocHidden.size > 0
+    ? allHeadings.filter((heading) => !tocHidden.has(heading.slug))
+    : allHeadings;
 const frontmatter = entry.data ?? {};
 
 const seo = frontmatter.seo ?? {};
@@ -2312,6 +2406,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
  */
 export const notFoundPageTemplate = (): string => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import Icon from "blume/components/Icon.astro";
 import PageLayout from "blume/components/layout/PageLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import data from "blume:data";
@@ -2329,6 +2424,24 @@ const localeMeta = i18n
   : null;
 const dir = localeMeta?.dir ?? "ltr";
 const htmlLang = i18n ? i18n.defaultLocale : "en";
+
+// Recovery links, so a reader — or an agent that followed a stale URL — can
+// get back on track without guessing: every top-level section, then the
+// machine-readable indexes the build emits (the sitemap only exists with a
+// \`deployment.site\`; llms.txt only when \`ai.llmsTxt\` is on). Tabs link to
+// their resolved target when the section has no index page of its own.
+const suggestions = [
+  ...data.navigation.tabs.map((tab) => ({
+    href: withBase(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: withBase("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: withBase("/llms.txt"), label: nf.llms }]
+    : []),
+];
 ---
 
 <PageLayout
@@ -2349,19 +2462,128 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
   noindex={true}
 >
   <div
-    class="mx-auto flex min-h-[60vh] max-w-2xl flex-col items-center justify-center gap-4 px-6 py-24 text-center"
+    class="mx-auto grid w-full max-w-5xl gap-12 px-6 py-20 sm:py-28 md:grid-cols-[3fr_2fr] md:gap-16 lg:gap-24 lg:py-36"
   >
-    <p class="text-6xl font-bold text-muted-foreground">404</p>
-    <h1 class="text-2xl font-semibold text-foreground">{nf.title}</h1>
-    <p class="text-muted-foreground">{nf.description}</p>
-    <a
-      class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
-      href={withBase("/")}>{nf.home}</a
-    >
+    <div class="flex flex-col items-start">
+      <p
+        class="font-mono text-xs font-medium tracking-widest text-muted-foreground"
+      >
+        404
+      </p>
+      <h1
+        class="mt-4 text-balance text-4xl font-semibold tracking-tight text-foreground sm:text-5xl"
+      >
+        {nf.title}
+      </h1>
+      <p class="mt-4 max-w-md text-pretty text-lg text-muted-foreground">
+        {nf.description}
+      </p>
+      <a
+        class="mt-8 inline-flex items-center gap-1.5 rounded-full bg-accent py-2 pe-4 ps-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90"
+        href={withBase("/")}
+      >
+        <Icon class="rtl:-scale-x-100" name="arrow-left" size={14} />
+        {nf.home}
+      </a>
+    </div>
+    {
+      suggestions.length > 0 && (
+        <nav aria-label={nf.suggestions} class="md:border-s md:border-border md:ps-12 lg:ps-16">
+          <h2 class="text-xs font-medium uppercase tracking-widest text-muted-foreground">
+            {nf.suggestions}
+          </h2>
+          <ul class="mt-4 divide-y divide-border border-y border-border">
+            {suggestions.map((link) => (
+              <li>
+                <a
+                  class="group flex items-center justify-between gap-4 py-3 text-sm font-medium text-foreground transition-colors hover:text-accent"
+                  href={link.href}
+                >
+                  <span>{link.label}</span>
+                  <Icon
+                    class="shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5 rtl:-scale-x-100 rtl:group-hover:-translate-x-0.5"
+                    name="arrow-right"
+                    size={14}
+                  />
+                </a>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )
+    }
   </div>
 </PageLayout>
 `;
 
+/**
+ * Generate `.blume/src/pages/404.md.ts`: the Markdown twin of the default 404
+ * page, prerendered to `dist/404.md`. An agent that asked for a missing page
+ * with `Accept: text/markdown` — or fetched a `.md` URL no page backs — gets
+ * this body with the 404 status instead of the HTML shell; Vercel server
+ * builds wire that into the routing config (`deploy/vercel-negotiation.ts`).
+ * Same recovery links as the HTML page, absolute when the site URL is known:
+ * the body is read out of context, so a relative link would leave the reader
+ * guessing the host. Written alongside `404.astro` and skipped under the same
+ * rule, so a project that owns `/404` owns both variants.
+ */
+export const notFoundMarkdownTemplate =
+  (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import { withBase } from "blume/components/islands/base-path.ts";
+import { absoluteUrl } from "blume/core/site-url.ts";
+import data from "blume:data";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+
+// Absolute for internal routes when the site is known; an external tab href
+// passes through untouched.
+const href = (path: string): string => {
+  const based = withBase(path);
+  return data.config.site && based.startsWith("/") && !based.startsWith("//")
+    ? absoluteUrl(data.config.site, based)
+    : based;
+};
+
+// The recovery set of 404.astro: home, every top-level section (a tab links to
+// its resolved target), then the machine-readable indexes that exist.
+const links = [
+  { href: href("/"), label: nf.home },
+  ...data.navigation.tabs.map((tab) => ({
+    href: href(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: href("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: href("/llms.txt"), label: nf.llms }]
+    : []),
+];
+
+const body = [
+  "# " + nf.title,
+  "",
+  nf.description,
+  "",
+  "## " + nf.suggestions,
+  "",
+  ...links.map((link) => "- [" + link.label + "](" + link.href + ")"),
+  "",
+].join("\\n");
+
+export function GET() {
+  return new Response(body, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      // ~4 characters per token; keep in sync with markdownTokenCount.
+      "x-markdown-tokens": String(Math.ceil(body.length / 4)),
+    },
+  });
+}
+`;
+
 /** The literal Astro hydration directive for an island's client mode. */
 const islandDirective = (spec: IslandSpec): string =>
   spec.client === "only"
@@ -2643,6 +2865,36 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:ask-data" {
+  const askData: import("blume/ai/ask-context.ts").AskData;
+  export default askData;
+}
+
+declare module "blume:content-assets" {
+  const assets: Record<string, string>;
+  export default assets;
+}
+
+declare module "blume:mcp-data" {
+  const data: import("blume/ai/mcp/data.ts").McpData;
+  export default data;
+}
+
+declare module "blume:raw-markdown" {
+  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
+  export default raw;
+}
+
+declare module "blume:rss" {
+  const feeds: Record<string, string>;
+  export default feeds;
+}
+
+declare module "blume:search-index" {
+  const documents: import("blume/search/documents.ts").SearchDocument[];
+  export default documents;
+}
+
 declare module "blume:examples" {
   type Examples = typeof import("./generated/examples.ts").examples;
   export const examples: Record<string, Examples[keyof Examples]>;