blume 1.7.3 → 2.0.0

package/src/astro/templates.ts

@@ -4,24 +4,28 @@ import { pathToFileURL } from "node:url";
 import { dirname, isAbsolute, join, relative } from "pathe";
 
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
-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 { AskReasoning, ResolvedConfig } from "../core/schema.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import { resolveDocsCollection } from "../core/sources/collection.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { deployPassthrough } from "../deploy/adapters/types.ts";
+import { SVG_ASSET_POLICY } from "../deploy/headers.ts";
+import { deployPlatform } from "../deploy/platforms/index.ts";
+import { adapterRoot, distDir } from "../deploy/platforms/paths.ts";
 import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import type { OgCache } from "../og/cache.ts";
 import type { OgFont, OgFontFamilies } from "../og/card.ts";
-import { hasScalarReferences } from "../openapi/references.ts";
-import { searchProviderMeta } from "../search/providers.ts";
+import type { MixedbreadOptions } from "../search/adapters/mixedbread.ts";
+import type { ResolvedSearchAdapter } from "../search/adapters/registry.ts";
 import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
+import { importSpecifier, wrapperPropsType } from "./component-slots.ts";
 import type { ExampleSpec } from "./examples.ts";
 import type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
-import type { IslandSpec } from "./islands.ts";
 import type { OgCustomRoute } from "./pages.ts";
 import { RUNTIME_MODULE_FILES } from "./runtime-modules.ts";
 
@@ -77,67 +81,54 @@ const findWorkspaceRoot = (start: string): string => {
   }
 };
 
-type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
-
-const ADAPTER_IMPORTS = {
-  cloudflare: "@astrojs/cloudflare",
-  netlify: "@astrojs/netlify",
-  node: "@astrojs/node",
-  vercel: "@astrojs/vercel",
-} satisfies Record<DeploymentAdapter, string>;
-
-/** Adapter constructor arguments, for the adapters that need any. */
-const ADAPTER_OPTIONS = new Map<DeploymentAdapter, string>([
-  ["node", '{ mode: "standalone" }'],
-]);
-
-const WRANGLER_CONFIG_FILES = [
-  "wrangler.jsonc",
-  "wrangler.json",
-  "wrangler.toml",
-];
+/**
+ * The `adapter:` entry of the generated config plus the import that backs it,
+ * for a server build. The platform (see `deploy/platforms/*`) names the
+ * `@astrojs/*` package and Blume's own constructor options; the descriptor's
+ * passthrough options are spread over those, verbatim, so anything the
+ * adapter was given reaches the real adapter. A platform that resolves its
+ * output against Astro's root is handed the project root instead of the
+ * hidden runtime (`withAdapterRoot`).
+ */
+interface AstroAdapterRender {
+  /** Extra top-level `defineConfig` entries the adapter needs. */
+  configEntries: string;
+  importLine: string;
+  /** The `adapter:` entry, or empty for a static build. */
+  option: string;
+}
 
-const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
-  // 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));
-  if (wranglerPath) {
-    let configPath = relative(context.outDir, wranglerPath);
-    // The wrangler config always lives at the project root, above the `.blume`
-    // runtime, so `relative` yields a `../…` path; normalize the theoretical
-    // sibling case to an explicit `./` so it reads as a relative import.
-    if (!configPath.startsWith(".") && !configPath.startsWith("/")) {
-      configPath = `./${configPath}`;
-    }
-    args.push(`configPath: ${JSON.stringify(configPath)}`);
+const renderAstroAdapter = (
+  deployment: ResolvedConfig["deployment"],
+  context: ProjectContext,
+  ejected: boolean
+): AstroAdapterRender => {
+  const platform = deployPlatform(deployment);
+  if (deployment.options.output !== "server" || !platform.astro) {
+    return { configEntries: "", importLine: "", option: "" };
   }
-  return `{ ${args.join(", ")} }`;
+  const { astro } = platform;
+  const args = {
+    ...astro.options(context),
+    ...deployPassthrough(deployment.options),
+  };
+  const argsLiteral = Object.keys(args).length > 0 ? JSON.stringify(args) : "";
+  const construct = `adapter(${argsLiteral})`;
+  // An ejected app's Astro root is the project root already, so its adapter
+  // needs no redirect (and the config no machine-specific path).
+  const expression =
+    platform.hiddenRuntime.showProjectRoot && !ejected
+      ? `withAdapterRoot(${construct}, ${JSON.stringify(adapterRoot(context))})`
+      : construct;
+  return {
+    configEntries: Object.entries(astro.config)
+      .map(([key, value]) => `\n  ${key}: ${JSON.stringify(value)},`)
+      .join(""),
+    importLine: `import adapter from "${astro.package}";\n`,
+    option: `\n  adapter: ${expression},`,
+  };
 };
 
-/**
- * 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`. Astro's `session: false`
- * opts the project out, and the adapter checks for it before adding the
- * binding. (An in-memory driver used to stand in before the opt-out existed.)
- */
-const resolveSessionOption = (deployment: {
-  adapter: string | null;
-  output: string;
-}): string =>
-  deployment.output === "server" && deployment.adapter === "cloudflare"
-    ? "\n  session: false,"
-    : "";
-
 /**
  * A font weight as Astro's Fonts API spells it: a variable range is
  * `"100 900"` there, where Blume's config (and Takumi's Google Fonts helper,
@@ -183,29 +174,36 @@ export const runtimeDependencies = (options: {
   if (needsSvelte) {
     deps.push("@astrojs/svelte");
   }
-  // The Scalar integration is only declared for a Scalar-rendered reference
-  // (the `renderer: "scalar"` opt-out on either block). Blume-rendered
-  // references parse at generate time and need no runtime Scalar dependency.
-  if (hasScalarReferences(config)) {
-    deps.push("@scalar/astro");
-  }
-  // Only the configured search provider's SDK is declared, so a project pulls in
-  // (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 && !config.ai.ask.endpoint) {
-    const askDep = askBackendRuntimeDep(config.ai.ask);
-    if (askDep) {
-      deps.push(askDep);
+  // Each reference adapter declares what it needs: Blume's own renderer
+  // parses at generate time and needs nothing, while `scalar()` declares
+  // `@scalar/astro` so the framework crawl bundles the embed (two Scalar
+  // adapters declare it twice, hence the set). Only the configured
+  // search adapter's SDK is declared, so a project pulls in (and the user
+  // installs) exactly the backend it uses — nothing more. Each analytics
+  // adapter declares what it needs the same way; the built-ins need nothing
+  // beyond Blume's own deps, so their share is usually empty.
+  deps.push(
+    ...new Set(config.reference.flatMap((adapter) => adapter.runtimeDeps)),
+    ...config.search.provider.runtimeDeps,
+    ...config.analytics.flatMap((adapter) => adapter.runtimeDeps)
+  );
+  // Each content source adapter declares the SDK its fetch imports (Notion,
+  // Sanity); the descriptor is the one place that knows.
+  for (const source of config.content.sources) {
+    for (const dep of source.runtimeDeps) {
+      if (!deps.includes(dep)) {
+        deps.push(dep);
+      }
     }
   }
-  const { deployment } = config;
-  if (deployment.output === "server" && deployment.adapter) {
-    const adapter = ADAPTER_IMPORTS[deployment.adapter];
-    if (adapter) {
-      deps.push(adapter);
-    }
+  // Ask AI's provider SDK, as its adapter declares it (the gateway needs
+  // nothing beyond core `ai`, so it declares none).
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
+    deps.push(...config.ai.ask.provider.runtimeDeps);
   }
+  // The deployment adapter's `@astrojs/*` package, for a server build; the
+  // descriptor declares it (and nothing for a static build).
+  deps.push(...config.deployment.runtimeDeps);
   return deps;
 };
 
@@ -271,25 +269,6 @@ const renderUserAliases = (
     )
     .join("");
 
-/** Astro's build output dir: the runtime's own `distDir`, else `<root>/dist`. */
-const astroOutDir = (context: ProjectContext): string =>
-  context.distDir ?? `${context.root}/dist`;
-
-/**
- * The root a deploy adapter is shown, in place of the `.blume` runtime Astro
- * actually roots at. Adapters assume `outDir` is `<root>/dist` and resolve their
- * own output (and Vercel's dependency trace) against `root`, so the root implied
- * by Blume's `outDir` is the one that keeps that assumption true. See
- * {@link withAdapterRoot}.
- *
- * For a normal build that is the project root (`<project>/dist` -> `<project>`).
- * For a relocated runtime (`blume build --isolated`) it is the runtime dir
- * itself (`<runtime>/dist` -> `<runtime>`), keeping a verify build's adapter
- * output self-contained instead of overwriting the real `.vercel/output`.
- */
-const adapterRoot = (context: ProjectContext): string =>
-  dirname(astroOutDir(context));
-
 /**
  * Excludes Vite's pre-bundled dep cache from @vitejs/plugin-react. Astro's
  * react() replaces the plugin's default `/node_modules/` exclude with just
@@ -451,6 +430,59 @@ const resolveOptimizeDeps = (options: {
   return { optimizeDepsEntries, optimizeDepsInclude };
 };
 
+/**
+ * A path the generated config hands Vite or a plugin. The ejected config
+ * resolves it against the config file itself when it loads, so the project
+ * builds from any checkout and working directory, and Vite gets the absolute
+ * alias target it expects (it warns on every relative one). The hidden
+ * runtime's paths are absolute already.
+ */
+const configPath = (path: string, ejected: boolean): string =>
+  ejected
+    ? `fileURLToPath(new URL(${JSON.stringify(path)}, import.meta.url))`
+    : JSON.stringify(path);
+
+/**
+ * The first line of an ejected `astro.config.mjs`, which also marks the
+ * project as ejected for the CLI (`blume dev`/`build` step aside, and a second
+ * `blume eject` refuses to overwrite the app).
+ */
+export const EJECTED_CONFIG_HEADER =
+  "// Written by `blume eject`. This is your Astro config now: edit it freely.";
+
+/**
+ * The generated config's first line. The hidden runtime's config is rewritten
+ * on every run; an ejected one belongs to the project from then on.
+ */
+const astroConfigHeader = (ejected: boolean): string =>
+  ejected
+    ? EJECTED_CONFIG_HEADER
+    : "// Generated by Blume. Do not edit; this file is recreated on each run.";
+
+/**
+ * The client build's chunk-size warning threshold (kB) on a site with Mermaid
+ * diagrams. Mermaid's ELK layout engine (about 1.5 MB) and its core (about
+ * 650 kB) land in their own chunks, which the `blume:features` loader fetches
+ * only on a page with a diagram — so Vite's default 500 kB warning fired on
+ * every such build without anything to fix. A chunk past this still warns.
+ */
+const MERMAID_CHUNK_LIMIT = "\n      chunkSizeWarningLimit: 2048,";
+
+/**
+ * Rolldown's log hook for the build. Astro's content-assets plugin opens each
+ * page's `?astroPropagatedAssets` module with a `"use astro:head-inject"`
+ * directive that nothing reads once bundled (head propagation rides on the
+ * module's `__astroPropagation` export), and Rolldown 1.2.10+ warns about it
+ * in nine lines per page, on every build. That one warning is dropped; every
+ * other log goes to Vite's default handler.
+ */
+const ROLLDOWN_ON_LOG = `onLog(level, log, handler) {
+          if (log.code === "MODULE_LEVEL_DIRECTIVE" && String(log.message).includes("use astro:head-inject")) {
+            return;
+          }
+          handler(level, log);
+        }`;
+
 /**
  * How the generated config reaches the runtime data modules (`blume:data`,
  * the search index, …): served from memory by `runtimeModulesPlugin` in the
@@ -479,7 +511,7 @@ const renderRuntimeModuleWiring = (
   const aliasLines = [...RUNTIME_MODULE_FILES]
     .map(
       ([id, file]) =>
-        `\n        ${JSON.stringify(id)}: ${JSON.stringify(`${generatedModulesDir}/${file}`)},`
+        `\n        ${JSON.stringify(id)}: ${configPath(`${generatedModulesDir}/${file}`, true)},`
     )
     .join("");
   return { aliasLines, imports: [], pluginEntry: "" };
@@ -572,6 +604,7 @@ export const astroConfigTemplate = (options: {
     needsVue,
     searchClientPath,
   } = options;
+  const ejected = generatedModulesDir !== undefined;
   const {
     aliasLines: runtimeModuleAliasLines,
     imports: runtimeModuleImports,
@@ -579,7 +612,6 @@ export const astroConfigTemplate = (options: {
   } = renderRuntimeModuleWiring(generatedModulesDir);
   const { deployment } = config;
   const userAliasLines = renderUserAliases(options.aliases);
-  const server = deployment.output === "server";
 
   // The project root plus the workspace root, so hoisted dependencies (e.g.
   // KaTeX fonts under a monorepo's root node_modules) stay servable in dev.
@@ -593,38 +625,17 @@ export const astroConfigTemplate = (options: {
     reactCompilerPath: options.reactCompilerPath,
   });
 
-  const adapterImport =
-    server && deployment.adapter
-      ? `import adapter from "${ADAPTER_IMPORTS[deployment.adapter]}";\n`
-      : "";
-  const adapterArgs = (() => {
-    if (!server || !deployment.adapter) {
-      return "";
-    }
-    if (deployment.adapter === "cloudflare") {
-      return resolveCloudflareAdapterArgs(context);
-    }
-    return ADAPTER_OPTIONS.get(deployment.adapter) ?? "";
-  })();
-  // Vercel resolves its Build Output tree and its `@vercel/nft` dependency
-  // trace against the Astro root, which for Blume is the hidden `.blume`
-  // runtime — leaving the traced function without its chunks or node_modules.
-  // The other adapters emit into `outDir` (cloudflare, node) or are surfaced
-  // afterwards (netlify), so none of them read `root` this way.
-  const adapterExpr =
-    deployment.adapter === "vercel"
-      ? `withAdapterRoot(adapter(${adapterArgs}), ${JSON.stringify(adapterRoot(context))})`
-      : `adapter(${adapterArgs})`;
-  const adapterOption =
-    server && deployment.adapter ? `\n  adapter: ${adapterExpr},` : "";
-
-  const sessionOption = resolveSessionOption(deployment);
-
-  const siteOption = deployment.site
-    ? `\n  site: ${JSON.stringify(deployment.site)},`
+  const {
+    configEntries: adapterConfigEntries,
+    importLine: adapterImport,
+    option: adapterOption,
+  } = renderAstroAdapter(deployment, context, ejected);
+
+  const siteOption = deployment.options.site
+    ? `\n  site: ${JSON.stringify(deployment.options.site)},`
     : "";
-  const baseOption = deployment.base
-    ? `\n  base: ${JSON.stringify(deployment.base)},`
+  const baseOption = deployment.options.base
+    ? `\n  base: ${JSON.stringify(deployment.options.base)},`
     : "";
   const imageOption = renderImageOption(config);
 
@@ -649,7 +660,7 @@ export const astroConfigTemplate = (options: {
   const basedRedirects = applyBaseToAstroRedirects(
     config.redirects,
     config.basePath,
-    deployment.base ?? ""
+    deployment.options.base ?? ""
   );
   const redirectsOption =
     basedRedirects.length > 0
@@ -746,16 +757,26 @@ export const astroConfigTemplate = (options: {
   // hand-written `basePath` link (`/docs/x`) isn't double-prefixed (see
   // `withComposedBasePath`). The link checker validates the base-less authored
   // path against `basePath` routes separately.
-  const deployBase = normalizeBasePath(deployment.base);
+  const deployBase = normalizeBasePath(deployment.options.base);
+  // Both processors take the same options. An ejected app has no CLI to
+  // publish the `blume:data` snapshot that relative page links resolve
+  // through, so its processors read the snapshot file instead, resolved
+  // against the config file like the module aliases.
+  const processorLiteral = JSON.stringify({
+    basePath: config.basePath,
+    codeThemes: config.markdown.code.theme,
+    contentRoot: options.contentRoot,
+    deployBase,
+    externalLinks: config.markdown.externalLinks,
+    headingAnchors: config.markdown.headingAnchors,
+  });
+  const processorOptions =
+    options.generatedModulesDir === undefined
+      ? processorLiteral
+      : `{ ...${processorLiteral}, dataFile: ${configPath(`${options.generatedModulesDir}/data.json`, true)} }`;
 
   const integrations = [
-    `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
-      basePath: config.basePath,
-      codeThemes: config.markdown.codeBlocks.theme,
-      contentRoot: options.contentRoot,
-      deployBase,
-      headingAnchors: config.markdown.headingAnchors,
-    })}) })`,
+    `mdx({ processor: blumeMdxProcessor(${processorOptions}) })`,
   ];
   if (needsReact) {
     integrations.push(reactIntegration(options.reactCompilerPath));
@@ -774,7 +795,7 @@ export const astroConfigTemplate = (options: {
       blumeIntegrationOptions({
         config,
         contentRoutes,
-        ejected: generatedModulesDir !== undefined,
+        ejected,
         pages,
       })
     )})`
@@ -787,9 +808,13 @@ export const astroConfigTemplate = (options: {
     userIntegrationSpread,
   } = renderIntegrationBridge(options.integrationBridge);
 
-  return `// Generated by Blume. Do not edit; this file is recreated on each run.
+  const fileUrlImport = ejected
+    ? `import { fileURLToPath } from "node:url";\n`
+    : "";
+
+  return `${astroConfigHeader(ejected)}
 ${configSourceMarker}${userConfigImports}import { availableParallelism } from "node:os";
-${defineConfigImport}
+${fileUrlImport}${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
@@ -797,22 +822,16 @@ ${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
 ${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
-  outDir: ${JSON.stringify(astroOutDir(context))},
+  outDir: ${JSON.stringify(distDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},${cacheOptions}
-  output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${imageOption}${redirectsOption}${i18nOption}${fontsOption}
+  output: ${JSON.stringify(deployment.options.output)},${adapterOption}${adapterConfigEntries}${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,
-    })}),
+    processor: blumeMarkdownProcessor(${processorOptions}),
     shikiConfig: {
       themes: {
-        light: ${JSON.stringify(config.markdown.codeBlocks.theme.light)},
-        dark: ${JSON.stringify(config.markdown.codeBlocks.theme.dark)},
+        light: ${JSON.stringify(config.markdown.code.theme.light)},
+        dark: ${JSON.stringify(config.markdown.code.theme.dark)},
       },
       defaultColor: false,
       transformers: [${twoslashTransformer}...blumeShikiTransformers(${JSON.stringify(
@@ -841,9 +860,15 @@ ${userConfigSetup}export default defineConfig({
   // the overlap only adds memory.
   build: { concurrency: Math.min(8, availableParallelism()) },
   vite: {${viteCacheOption}
-    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${JSON.stringify(
-      `${context.outDir}/src/generated/includes.json`
+    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${configPath(
+      `${context.outDir}/src/generated/includes.json`,
+      ejected
     )}), prerenderDepsPlugin()],
+    build: {${features.mermaid ? MERMAID_CHUNK_LIMIT : ""}
+      rolldownOptions: {
+        ${ROLLDOWN_ON_LOG},
+      },
+    },
     // 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
@@ -889,12 +914,12 @@ ${userConfigSetup}export default defineConfig({
     },
     resolve: {
       alias: {
-        "blume:ask": ${JSON.stringify(askPath)},
-        "blume:examples": ${JSON.stringify(examplesPath)},
-        "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
-        "blume:features": ${JSON.stringify(featuresPath)},
-        "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},${runtimeModuleAliasLines}${userAliasLines}
+        "blume:ask": ${configPath(askPath, ejected)},
+        "blume:examples": ${configPath(examplesPath, ejected)},
+        "blume:examples-theme": ${configPath(examplesThemePath, ejected)},
+        "blume:features": ${configPath(featuresPath, ejected)},
+        "blume:search-client": ${configPath(searchClientPath, ejected)},
+        "blume:theme": ${configPath(themePath, ejected)},${runtimeModuleAliasLines}${userAliasLines}
       },
     },
     server: {
@@ -943,10 +968,9 @@ export const contentConfigTemplate = (options: {
   /** Base dir for the staged collection; defaults to `<outDir>/content`. */
   stagedBase?: string;
   /**
-   * The `docs` collection's base + include/exclude globs. Defaults to
-   * `content.root` and the top-level content globs; a single filesystem source
-   * roots the collection at *its* root so entry ids resolve (see
-   * `resolveDocsCollection`).
+   * The `docs` collection's base + include/exclude globs. Defaults to what
+   * `resolveDocsCollection` derives from the filesystem sources: the collection
+   * roots at the first one so entry ids resolve.
    */
   collection?: { base: string; include: string[]; exclude: string[] };
   /**
@@ -958,9 +982,11 @@ export const contentConfigTemplate = (options: {
 }): string => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
-  const collectionBase = options.collection?.base ?? context.contentRoot;
-  const includeGlobs = options.collection?.include ?? config.content.include;
-  const excludeGlobs = options.collection?.exclude ?? config.content.exclude;
+  const collection =
+    options.collection ?? resolveDocsCollection(config, context.root);
+  const collectionBase = collection.base;
+  const includeGlobs = collection.include;
+  const excludeGlobs = collection.exclude;
 
   // Fold the content excludes into the glob as negative patterns so the `docs`
   // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
@@ -1044,11 +1070,6 @@ export interface AskEndpointOptions {
   cors?: string[];
   /** `ai.ask.instructions` — extra system-prompt text. */
   instructions?: string;
-  /**
-   * `ai.ask.reasoning` — how much the model reasons before answering, sent
-   * as the backend's own reasoning-effort control.
-   */
-  reasoning?: AskReasoning;
   /** `ai.ask.retrieval` — how much documentation each question carries. */
   retrieval?: AskRetrievalOptions;
 }
@@ -1092,31 +1113,38 @@ export const OPTIONS: APIRoute = ({ request }) =>
       }
     : { close: "};", imports: [], open: "async ({ request }) => {", setup: "" };
 
+/**
+ * Largest request body the Ask AI route reads: 64 KB, well above the
+ * 24,000-character message budget it validates next, so a real conversation
+ * never meets it.
+ */
+const ASK_BODY_LIMIT_BYTES = 65_536;
+
 /**
  * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
  *
+ * The provider-specific pieces — imports, the provider factory call, the model
+ * expression, the credential guard, and the adapter's reasoning mapping and
+ * `providerOptions` — come from the resolved `backend` descriptor, inlined as
+ * literals so the route imports the provider SDK by bare name and never
+ * `blume.config.ts`. `backend.grounded` decides whether answers are grounded
+ * in the retrieved docs (every adapter but Inkeep, which retrieves itself).
+ *
  * `options.instructions` (the `ai.ask.instructions` config) is appended to the
  * built-in prompt on every path: the grounded prompt via `createAskContext`,
  * and the plain fallback here. `options.retrieval` (the `ai.ask.retrieval`
  * config) is forwarded to `createAskContext` on the grounded path, where it
- * sizes retrieval. `options.reasoning` (the `ai.ask.reasoning` config)
- * reaches the model call on both paths. `options.cors` (the `ai.ask.cors`
- * config) adds a preflight handler and wraps the `POST` so every response
- * names a listed origin. All four travel in one options object so a new call
- * site can't silently drop one of them.
+ * sizes retrieval. `options.cors` (the `ai.ask.cors` config) adds a preflight
+ * handler and wraps the `POST` so every response names a listed origin. All
+ * three travel in one options object so a new call site can't silently drop
+ * one of them.
  */
 export const askEndpointTemplate = (
   backend: AskBackend,
-  grounded: boolean,
   options?: AskEndpointOptions
 ): string => {
-  const { instructions, reasoning, retrieval } = options ?? {};
-  // `ai.ask.reasoning`. The gateway and OpenAI-compatible providers take it
-  // from `streamText`'s top-level `reasoning` (the gateway maps it to the
-  // model's own control, the OpenAI-compatible provider sends it as
-  // `reasoning_effort`). OpenRouter's provider ignores that call option and
-  // only reads its own model setting, so there the level rides on the model
-  // as `reasoning.effort`. Omitted keeps the provider default on every path.
+  const { instructions, retrieval } = options ?? {};
+  const { grounded } = backend;
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
@@ -1126,47 +1154,10 @@ export const askEndpointTemplate = (
   const imports = [
     'import type { APIRoute } from "astro";',
     'import { getSecret } from "astro:env/server";',
-    // The gateway provider reads the key (or Vercel's OIDC token) from the
-    // environment itself; passing the key explicitly lets a binding-backed
-    // secret store reach it too.
-    backend.kind === "gateway"
-      ? 'import { createGateway, streamText } from "ai";'
-      : 'import { streamText } from "ai";',
+    'import { readCappedText } from "blume/core/request-body.ts";',
+    ...backend.template.imports,
   ];
-  let setup = "";
-  let modelExpr = JSON.stringify(backend.model);
-  // `ai.ask.headers`, inlined as literals: every provider factory below takes
-  // the same `headers` option, so one line serves all three.
-  const headersField = backend.headers
-    ? `\n  headers: ${JSON.stringify(backend.headers)},`
-    : "";
-  if (backend.kind === "gateway") {
-    setup = `\nconst gateway = createGateway({
-  apiKey: getSecret("AI_GATEWAY_API_KEY"),${headersField}
-});\n`;
-    modelExpr = `gateway(${JSON.stringify(backend.model)})`;
-  } else if (backend.kind === "openrouter") {
-    imports.push(
-      'import { createOpenRouter } from "@openrouter/ai-sdk-provider";'
-    );
-    setup = `\nconst openrouter = createOpenRouter({
-  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),${headersField}
-});\n`;
-    const settings = reasoning
-      ? `, { reasoning: { effort: ${JSON.stringify(reasoning)} } }`
-      : "";
-    modelExpr = `openrouter(${JSON.stringify(backend.model)}${settings})`;
-  } else if (backend.kind === "openai-compatible") {
-    imports.push(
-      'import { createOpenAICompatible } from "@ai-sdk/openai-compatible";'
-    );
-    setup = `\nconst provider = createOpenAICompatible({
-  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
-  baseURL: ${JSON.stringify(backend.baseUrl)},${headersField}
-  name: ${JSON.stringify(backend.name)},
-});\n`;
-    modelExpr = `provider(${JSON.stringify(backend.model)})`;
-  }
+  let { setup } = backend.template;
   // Ground the answer in retrieved docs, except for RAG-native backends (Inkeep),
   // which run their own retrieval and would conflict with injected context.
   if (grounded) {
@@ -1192,8 +1183,21 @@ export const askEndpointTemplate = (
   // can spend against the model per request, and restricting roles to
   // user/assistant keeps callers from injecting their own system prompt and
   // repurposing the endpoint as a general LLM proxy; front it with a rate
-  // limiter (or your provider's limits) for stronger protection.
-  const validate = `  const body = await request.json().catch(() => null);
+  // limiter (or your provider's limits) for stronger protection. The body is
+  // read under a 64 KB cap before any parsing, since a self-hosted Node server
+  // would otherwise buffer an arbitrarily large POST in memory first.
+  const validate = `  const text = await readCappedText(request, ${ASK_BODY_LIMIT_BYTES});
+  if (text === undefined) {
+    return new Response("Request too large: the body must be at most 64 KB.", {
+      status: 413,
+    });
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = null;
+  }
   const raw = body?.messages;
   const valid =
     Array.isArray(raw) &&
@@ -1221,23 +1225,10 @@ export const askEndpointTemplate = (
   // `streamText` returns synchronously and defers provider/auth/network errors
   // to stream consumption, so the handler's try/catch never sees them: without
   // these the client gets a 200 whose stream aborts mid-flight and nothing is
-  // logged server-side. A missing credential is rejected up front as a real
-  // 500; everything else is at least logged via `onError`.
-  const keyCheck =
-    backend.kind === "gateway"
-      ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
-  if (!(getSecret("AI_GATEWAY_API_KEY") || getSecret("VERCEL_OIDC_TOKEN"))) {
-    return new Response(
-      "Ask AI is not configured: set AI_GATEWAY_API_KEY (or deploy on Vercel with OIDC).",
-      { status: 500 }
-    );
-  }`
-      : `  if (!getSecret(${JSON.stringify(backend.apiKeyEnv)})) {
-    return new Response(
-      ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
-      { status: 500 }
-    );
-  }`;
+  // logged server-side. A missing credential is rejected up front with a 503
+  // (the adapter's `keyCheck`); everything else is at least logged via
+  // `onError`.
+  const { keyCheck } = backend.template;
   // Provider errors surface mid-stream, after the 200 is committed; this is
   // the only place they can be observed server-side.
   const onError = `      onError({ error }) {
@@ -1245,16 +1236,16 @@ export const askEndpointTemplate = (
       },`;
   // The `streamText` argument list, built once so the grounded and plain
   // paths can't drift: they differ only in where the instructions come from.
+  // The adapter appends its own call-level fields (its reasoning mapping when
+  // that is a call option, and the verbatim `providerOptions`).
   const streamFields = [
-    `model: ${modelExpr}`,
+    `model: ${backend.template.model}`,
     grounded
       ? "instructions"
       : `instructions:\n        ${JSON.stringify(fallbackPrompt)}`,
     "messages",
+    ...backend.template.fields,
   ];
-  if (reasoning && backend.kind !== "openrouter") {
-    streamFields.push(`reasoning: ${JSON.stringify(reasoning)}`);
-  }
   const call = `    const result = streamText({
       ${streamFields.join(",\n      ")},
 ${onError}
@@ -1270,7 +1261,9 @@ ${validate}
 ${keyCheck}
   try {
 ${stream}
-    return result.toTextStreamResponse();
+    return createTextStreamResponse({
+      stream: toTextStream({ stream: result.stream }),
+    });
   } catch {
     return new Response("Failed to generate a response.", { status: 500 });
   }
@@ -1366,47 +1359,18 @@ export const createSearch = () => create({ indexUrl${
 `;
 
 /**
- * Public credential fields baked into a hosted provider's generated client
- * (Algolia/Orama Cloud/Typesense config values from `search.*`, all plain
- * strings or numbers; `JSON.stringify` drops the absent ones).
+ * A client that passes the adapter's options — public credentials, by
+ * contract — straight to the provider SDK. The options are inlined verbatim
+ * as a literal: Blume maps only the fields it names, and any extra option
+ * the adapter was given rides along untouched.
  */
-type HostedSearchCredentials = Record<string, string | number | undefined>;
-
-/** A client that passes public credentials straight to the provider SDK. */
 const hostedSearchClient = (
-  module: string,
-  options: HostedSearchCredentials
+  provider: Extract<ResolvedSearchAdapter, { mode: "hosted" }>
 ): string =>
-  `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}
-export const createSearch = () => create(${JSON.stringify(options)});
+  `${SEARCH_CLIENT_HEADER}${searchClientImport(provider.kind)}
+export const createSearch = () => create(${JSON.stringify(provider.options)});
 `;
 
-/** Build the per-provider config object the hosted client is created with. */
-const hostedSearchOptions = (
-  search: ResolvedConfig["search"]
-): { module: string; options: HostedSearchCredentials } | null => {
-  switch (search.provider) {
-    case "algolia": {
-      return { module: "algolia", options: { ...search.algolia } };
-    }
-    case "orama-cloud": {
-      return {
-        module: "orama-cloud",
-        options: {
-          apiKey: search.oramaCloud?.apiKey,
-          endpoint: search.oramaCloud?.endpoint,
-        },
-      };
-    }
-    case "typesense": {
-      return { module: "typesense", options: { ...search.typesense } };
-    }
-    default: {
-      return null;
-    }
-  }
-};
-
 /**
  * Generate `.blume/src/generated/features.ts` — the client-feature loaders
  * behind the `blume:features` alias. Each loader is a dynamic import when the
@@ -1443,78 +1407,102 @@ export const loadEpub:
  * baked in here; secret keys never reach the client.
  */
 export const searchClientTemplate = (config: ResolvedConfig): string => {
-  const { search } = config;
-
-  if (search.provider === "orama" || search.provider === "flexsearch") {
-    // Only Orama derives a tokenizer from the locale; FlexSearch has no
-    // equivalent hook, so its client keeps the bare index URL.
-    const locale =
-      search.provider === "orama" ? config.i18n?.defaultLocale : undefined;
-    return staticSearchClient(search.provider, locale);
-  }
-
-  const hosted = hostedSearchOptions(search);
-  if (hosted) {
-    return hostedSearchClient(hosted.module, hosted.options);
-  }
-
-  if (search.provider === "mixedbread") {
-    return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}${SEARCH_BASE_IMPORT}
+  const { provider } = config.search;
+
+  switch (provider.mode) {
+    case "static": {
+      // Only Orama derives a tokenizer from the locale; FlexSearch has no
+      // equivalent hook, so its client keeps the bare index URL.
+      const locale =
+        provider.kind === "orama" ? config.i18n?.defaultLocale : undefined;
+      return staticSearchClient(provider.kind, locale);
+    }
+    case "hosted": {
+      return hostedSearchClient(provider);
+    }
+    case "server": {
+      return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}${SEARCH_BASE_IMPORT}
 const api = joinBase(import.meta.env.BASE_URL, "api/search");
 
 export const createSearch = () => create({ api });
 `;
-  }
-
-  if (search.provider === "pagefind") {
-    return `${SEARCH_CLIENT_HEADER}${searchClientImport("pagefind")}${SEARCH_BASE_IMPORT}
+    }
+    case "pagefind": {
+      return `${SEARCH_CLIENT_HEADER}${searchClientImport("pagefind")}${SEARCH_BASE_IMPORT}
 const url = joinBase(import.meta.env.BASE_URL, "pagefind/pagefind.js");
 
 export const createSearch = () => create({ url });
 `;
-  }
-
-  // Search disabled: a no-op client so the alias always resolves.
-  return `${SEARCH_CLIENT_HEADER}export const createSearch = () => () =>
+    }
+    default: {
+      // Search disabled: a no-op client so the alias always resolves.
+      return `${SEARCH_CLIENT_HEADER}export const createSearch = () => () =>
   Promise.resolve({ hits: [], sections: [] });
 `;
+    }
+  }
 };
 
 /**
  * Generate the Mixedbread search endpoint (`/api/search`). It holds the secret
  * key server-side and proxies semantic queries to the configured store. The
- * result mapping is best-effort and may need tuning to how your content was
- * synced (see the Mixedbread sync step / \`mxbai vs sync\`).
+ * adapter's options are inlined as a literal so the route never imports the
+ * config. The result mapping is best-effort and may need tuning to how your
+ * content was synced (see the Mixedbread sync step / \`mxbai vs sync\`).
  */
-export const mixedbreadSearchEndpointTemplate = (storeId: string): string =>
+export const mixedbreadSearchEndpointTemplate = (
+  options: MixedbreadOptions
+): string =>
   `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
 import { getSecret } from "astro:env/server";
 import Mixedbread from "@mixedbread/sdk";
+import { readCappedText } from "blume/core/request-body.ts";
 
 export const prerender = false;
 
 const client = new Mixedbread({ apiKey: getSecret("MIXEDBREAD_API_KEY") ?? "" });
-const STORE_ID = ${JSON.stringify(storeId)};
+const OPTIONS = ${JSON.stringify(options)};
+// Every option besides the store reaches the search call verbatim.
+const { storeId: STORE_ID, ...SEARCH_OPTIONS } = OPTIONS;
 
 export const POST: APIRoute = async ({ request }) => {
+  // A search body is one short query: read it under a 16 KB cap, so a
+  // self-hosted server never buffers an arbitrarily large POST first.
+  const text = await readCappedText(request, 16_384);
+  if (text === undefined) {
+    return new Response("Request too large: the body must be at most 16 KB.", {
+      status: 413,
+    });
+  }
   // The endpoint is public: a malformed body must 200-empty, not 500.
-  const body = await request.json().catch(() => null);
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = null;
+  }
   const query = body?.query;
   if (!query || typeof query !== "string") {
     return new Response("[]", {
       headers: { "Content-Type": "application/json" },
     });
   }
+  // \`top_k\` defaults to 8 unless an option sets it; the query and store
+  // always come from the request and \`storeId\`.
   const response = await client.stores.search({
+    top_k: 8,
+    ...SEARCH_OPTIONS,
     query,
     store_identifiers: [STORE_ID],
-    top_k: 8,
   });
   const hits = (response.data ?? []).map((chunk) => {
     const meta = chunk.generated_metadata ?? {};
+    // Only a text chunk carries \`text\`; image, audio, and video chunks fall
+    // back to the excerpt the store generated for them.
+    const text = "text" in chunk ? chunk.text : undefined;
     return {
-      excerpt: chunk.text ?? meta.excerpt ?? "",
+      excerpt: text ?? meta.excerpt ?? "",
       title: meta.title ?? chunk.filename ?? "",
       url: meta.url ?? "",
     };
@@ -1661,9 +1649,15 @@ export const GET: APIRoute = async ({ params }) => {
     return new Response(null, { status: 404 });
   }
   const body = await readFile(path);
-  return new Response(new Uint8Array(body), {
-    headers: { "Content-Type": contentType(path) },
-  });
+  const type = contentType(path);
+  // An SVG opened directly is a document that can run script; the sandbox
+  // keeps an uploaded one inert on the docs origin. Static hosts get the same
+  // header from the build's header rules.
+  const headers: Record<string, string> =
+    type === "image/svg+xml"
+      ? { "Content-Security-Policy": ${JSON.stringify(SVG_ASSET_POLICY)}, "Content-Type": type }
+      : { "Content-Type": type };
+  return new Response(new Uint8Array(body), { headers });
 };
 `;
 
@@ -1693,7 +1687,8 @@ export const ALL: APIRoute = ({ request }) => handler(request);
 /**
  * Generate the playground's CORS proxy endpoint
  * (`.blume/src/blume-openapi/api-proxy.ts`), behind
- * `openapi.playground.proxy: true`. A thin server-rendered wrapper around the
+ * `playground: { proxy: true }` on an `openapi()` reference. A thin
+ * server-rendered wrapper around the
  * shipped `createPlaygroundProxyHandler`; injected at `/_api-proxy` rather
  * than written under `pages/` because Astro treats `_`-prefixed page files as
  * private.
@@ -1793,7 +1788,9 @@ export function getStaticPaths() {
   return navVariants(data, hiddenDefaultLocale(data.config.i18n)).flatMap(
     ({ locale, navigation, version }) =>
       [...navGroupIds(navigation.sidebar)]
-        .filter(([node]) => (node.display ?? "flat") !== "flat")
+        .filter(
+          ([node]) => node.kind === "group" && (node.display ?? "flat") !== "flat"
+        )
         .map(([, id]) => ({ params: { id, locale, version } }))
   );
 }
@@ -2067,8 +2064,7 @@ import LocaleLinks from "blume/components/layout/LocaleLinks.astro";
 import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
-${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
-import { islandComponents } from "../generated/islands.ts";`,
+${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";`,
     map: `{
   Accordion,
   AccordionItem,
@@ -2104,8 +2100,7 @@ import { islandComponents } from "../generated/islands.ts";`,
   TypeTable,
   Visibility,
   YouTube,
-  ${mathEntry}...islandComponents,
-  ...userMdx,
+  ${mathEntry}...userMdx,
 }`,
   };
 };
@@ -2164,6 +2159,7 @@ export function getStaticPaths() {
       indexable: route.indexable,
       lastModified: route.lastModified,
       locale: route.locale,
+      monolingual: route.monolingual,
       route: route.path,
       title: route.title,
       version: route.version,
@@ -2172,7 +2168,7 @@ export function getStaticPaths() {
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, version, versionAlternates } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, monolingual, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -2264,13 +2260,32 @@ const contentDir = i18n
 // hreflang URLs byte-match the sitemap's <loc> for the home page.
 const absolute = (path: string) => base + withBase(path);
 
+// A fallback page renders the fallback locale's page at this locale's URL, so
+// its canonical names the page it copies, and search engines never rank the
+// copy against the original.
+const fallbackSource =
+  fallback && i18n?.fallbackLocale
+    ? (alternates ?? []).find((alt) => alt.locale === i18n.fallbackLocale)
+    : undefined;
+// The page it copies, when that page is archived too, points on to the latest
+// docs; the copy names that final page directly, the fallback locale's
+// version of the latest one, so the canonical is never a chain.
+const fallbackLatest =
+  fallbackSource && archived && archived.canonical === "latest" && latestVersionAlt
+    ? (data.routes.find((entry) => entry.path === latestVersionAlt.path)?.alternates ?? []).find(
+        (alt) => alt.locale === i18n?.fallbackLocale
+      )
+    : undefined;
+const fallbackTarget = fallbackLatest ?? fallbackSource;
 // An archived page defaults its canonical to the same page in the latest docs
 // when that page still exists — search engines treat the live page as
 // authoritative without deindexing version-only content. A page's own
 // \`seo.canonical\` always wins, and \`canonical: "self"\` keeps the default.
 const canonical =
   seo.canonical ??
-  (archived && archived.canonical === "latest" && latestVersionAlt && base
+  (fallbackTarget && base
+    ? absolute(fallbackTarget.path)
+    : archived && archived.canonical === "latest" && latestVersionAlt && base
     ? absolute(latestVersionAlt.path)
     : base
       ? \`\${base}\${basedRoute === "/" ? "/" : encodeURI(basedRoute)}\`
@@ -2300,7 +2315,9 @@ const mountLocalized = (logical: string, codeArg: string) =>
 const logicalRoute = i18n
   ? stripLocale(stripBasePath(data.config.basePath, route), locale)
   : route;
-const localeSwitch = i18n
+// A page from a one-language source (GitHub Releases) gets no switcher: every
+// other locale would only repeat the same text.
+const localeSwitch = i18n && !monolingual
   ? i18n.locales.map((l) => {
       const alt = (alternates ?? []).find((x) => x.locale === l.code);
       return {
@@ -2397,6 +2414,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   locale={htmlLang}
   dir={dir}
   contentDir={contentDir}
+  contentLocale={contentLocale}
   ui={ui}
   localeAlternates={localeAlternates}
   xDefault={xDefault}
@@ -2446,14 +2464,17 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 
 /**
  * Generate `.blume/src/pages/changelog.astro` — the changelog index. Collects
- * every `type: changelog` entry, sorts newest-first, and renders each through
- * the `Update` timeline layout (date/version rail + entry content). Only written
- * by {@link generateAstroProject} when changelog entries exist.
+ * every `type: changelog` entry, sorts newest-first, and lists them grouped by
+ * year: one row per release with its title (linked to the entry's own page),
+ * its `category` tag, and its date. Bodies are deliberately not rendered — a
+ * long-lived project's index otherwise grows past what an agent can read in
+ * one context window (and what a reader will scroll), while every entry
+ * already has a page of its own. Only written by
+ * {@link generateAstroProject} when changelog entries exist.
  */
 export const changelogIndexTemplate = (options: {
   exportEpub: boolean;
   exportPdf: boolean;
-  mathEnabled: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
   needsReact: boolean;
   /** Whether a `staged` collection exists (non-filesystem changelog sources). */
@@ -2467,40 +2488,29 @@ export const changelogIndexTemplate = (options: {
   const stagedSpread = options.staged
     ? '\n  ...(await getCollection("staged")),'
     : "";
-  const { imports: componentImports, map: componentMap } =
-    contentComponentsSource(options.mathEnabled);
 
   return `---
 // Generated by Blume. Do not edit.
-import { getCollection, render } from "astro:content";
+import { getCollection } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
-import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { resolveDateFormatOptions } from "blume/core/date-format.ts";
-${componentImports}
+import { layoutOverrides } from "../generated/components.ts";
 import data from "blume:data";
 
-const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
-const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
-
 export const prerender = true;
 
-// Entry bodies are MDX rendered outside the catch-all, so they need the same
-// component map: a \`:::\` callout or \`<Steps>\` in a release note otherwise
-// throws "Expected component ... to be defined" at build time.
-const components = ${componentMap};
-
 const entryDate = (entry: {
   data: { date?: string | null; changelog?: { date?: string | null } | null };
 }) => entry.data.date ?? entry.data.changelog?.date ?? null;
 
-const toTime = (value: string | null | undefined) => {
+const parseDate = (value: string | null | undefined) => {
   if (!value) {
-    return 0;
+    return null;
   }
   const date = new Date(value);
-  return Number.isNaN(date.getTime()) ? 0 : date.getTime();
+  return Number.isNaN(date.getTime()) ? null : date;
 };
 
 // The changelog is an unlocalized route, so its chrome renders in the default
@@ -2515,34 +2525,45 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 
 // Formatted in the same locale as the chrome, and with the configured
 // \`dateFormat\` (UTC by default), to match the per-page "last updated" stamp.
+// The year heads each group, so a row shows the rest of the date: a preset
+// style keeps its month wording, a component format simply drops the year.
 const dateFormatOptions = resolveDateFormatOptions(data.config.dateFormat);
-const formatDate = (value: string | null | undefined) => {
-  if (!value) {
-    return;
-  }
-  const date = new Date(value);
-  return Number.isNaN(date.getTime())
-    ? undefined
-    : new Intl.DateTimeFormat(htmlLang, dateFormatOptions).format(date);
-};
+const { dateStyle, year: _year, ...dateComponents } = dateFormatOptions;
+const rowDateFormat: Intl.DateTimeFormatOptions = dateStyle
+  ? {
+      ...dateComponents,
+      day: "numeric",
+      month: dateStyle === "medium" ? "short" : "long",
+    }
+  : dateComponents;
+const formatRowDate = (date: Date) =>
+  new Intl.DateTimeFormat(htmlLang, rowDateFormat).format(date);
+const formatYear = (date: Date) =>
+  new Intl.DateTimeFormat(htmlLang, {
+    timeZone: dateFormatOptions.timeZone,
+    year: "numeric",
+  }).format(date);
 
 const slugify = (text: string) =>
   text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ||
   "update";
 
-// The major of a version's embedded semver (\`1.2.3\` -> 1, \`pkg@2.0.0\` -> 2), or
-// null when there is no full major.minor.patch to key on. Drives the changelog's
-// group-by-major pagination, so it tolerates the scoped tags monorepos publish.
-const majorVersion = (version: string | null | undefined) => {
-  const match = /(\\d+)\\.\\d+\\.\\d+/.exec(String(version ?? ""));
-  return match ? Number(match[1]) : null;
-};
-
-// Map each entry to its own generated page so the timeline heading can deep-link
-// to it. The collection entry id matches the route manifest's \`entryId\`.
-const routeByEntry = new Map(
-  data.routes.map((route) => [route.entryId, route.path])
-);
+// Map each entry to its own generated page so the row can link to it. The
+// collection entry id matches the route manifest's \`entryId\` — and under
+// i18n every locale serves a page for it (its translations plus fallback
+// copies of an untranslated one), all sharing that id, so a map over every
+// route would keep whichever locale came last: a Portuguese permalink on an
+// unlocalized index. Only the default locale's routes are kept, and an entry
+// is listed only when it has one, so a translated changelog file (a distinct
+// entry that lives under its own locale) does not add a second row for the
+// same release.
+const defaultLocale = i18n ? i18n.defaultLocale : null;
+const routeByEntry = new Map<string, string>();
+for (const route of data.routes) {
+  if (defaultLocale === null || route.locale === defaultLocale) {
+    routeByEntry.set(route.entryId, route.path);
+  }
+}
 
 const changelogEntries = [
   ...(await getCollection("docs")),${stagedSpread}
@@ -2551,35 +2572,37 @@ const changelogEntries = [
     (entry) =>
       entry.data.type === "changelog" &&
       !entry.data.draft &&
-      !entry.data.sidebar?.hidden
+      !entry.data.sidebar?.hidden &&
+      (defaultLocale === null || routeByEntry.has(entry.id))
   )
-  .toSorted((a, b) => toTime(entryDate(b)) - toTime(entryDate(a)));
-
-const items = await Promise.all(
-  changelogEntries.map(async (entry) => {
-    const label =
-      entry.data.title ??
-      (entry.data.changelog?.version
-        ? "v" + entry.data.changelog.version
-        : "Update");
-    return {
-      Content: (await render(entry)).Content,
-      date: formatDate(entryDate(entry)),
-      href: routeByEntry.get(entry.id) ?? undefined,
-      id: slugify(label),
-      label,
-      major: majorVersion(entry.data.changelog?.version),
-      tags: entry.data.changelog?.category
-        ? [entry.data.changelog.category]
-        : [],
-    };
-  })
-);
+  .toSorted(
+    (a, b) =>
+      (parseDate(entryDate(b))?.getTime() ?? 0) -
+      (parseDate(entryDate(a))?.getTime() ?? 0)
+  );
+
+const items = changelogEntries.map((entry) => {
+  const label =
+    entry.data.title ??
+    (entry.data.changelog?.version
+      ? "v" + entry.data.changelog.version
+      : "Update");
+  const date = parseDate(entryDate(entry));
+  const route = routeByEntry.get(entry.id);
+  return {
+    date: date ? formatRowDate(date) : null,
+    dateTime: date ? date.toISOString().slice(0, 10) : null,
+    href: route ? withBase(route) : null,
+    id: slugify(label),
+    label,
+    tag: entry.data.changelog?.category ?? null,
+    year: date ? formatYear(date) : null,
+  };
+});
 
 // Repeated labels slug to the same id (e.g. two entries with neither a title
 // nor a version both falling back to "update"); suffix the later ones -2, -3,
-// ... so every heading deep-links to its own entry. The first keeps the plain
-// slug, and the rendered ids stay in lockstep with the \`headings\` list below.
+// ... so every row keeps its own hash anchor. The first keeps the plain slug.
 const seenIds = new Set();
 for (const item of items) {
   let uniqueId = item.id;
@@ -2590,26 +2613,18 @@ for (const item of items) {
   item.id = uniqueId;
 }
 
-// A changelog is semver-paginated only when every visible release parses as
-// semver and they span more than one major line. Older majors then collapse
-// into groups the reader reveals one at a time; otherwise the timeline is flat.
-const majors = items.every((item) => item.major !== null)
-  ? [...new Set(items.map((item) => item.major))]
-      .filter((major): major is number => major !== null)
-      .toSorted((a, b) => b - a)
-  : [];
-const paginate = majors.length > 1;
-const majorGroups = majors.map((major) => ({
-  items: items.filter((item) => item.major === major),
-  label: major + ".x",
-  major,
-}));
-
-const headings = items.map((item) => ({
-  depth: 2,
-  slug: item.id,
-  text: item.label,
-}));
+// Consecutive releases from the same year share a group, so the list reads as
+// a year rail beside the rows; undated entries (sorted last) form a final
+// group with no year label.
+const groups: { items: typeof items; year: string | null }[] = [];
+for (const item of items) {
+  const last = groups[groups.length - 1];
+  if (last && last.year === item.year) {
+    last.items.push(item);
+  } else {
+    groups.push({ items: [item], year: item.year });
+  }
+}
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 // The canonical URL carries the deployment base (the page is served under it),
@@ -2623,9 +2638,9 @@ const canonical = base ? base + basedRoute : null;
 const ogPath = data.config.og.enabled ? withBase("/og/changelog.png") : null;
 const ogImage = ogPath && base ? base + ogPath : ogPath;
 
-// The page chrome (h1, title, description) comes from the same translatable
-// \`changelog\` group as the reveal button; optional chaining tolerates a
-// not-yet-regenerated data snapshot from before these keys existed.
+// The page chrome (h1, title, description) comes from the translatable
+// \`changelog\` group; optional chaining tolerates a not-yet-regenerated data
+// snapshot from before these keys existed.
 const changelogTitle = data.ui.changelog?.title ?? "Changelog";
 const changelogDescription =
   data.ui.changelog?.description ??
@@ -2658,7 +2673,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
     description: changelogDescription,
     route: "/changelog",
   }}
-  headings={headings}
+  headings={[]}
   toc={data.config.toc}
   contentLayout="bare"
   themeMode={data.config.theme.mode}
@@ -2679,56 +2694,52 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   structuredDataEnabled={data.config.structuredData}
 >
   <h1>{changelogTitle}</h1>
+  <p class="text-lg text-muted-foreground">{changelogDescription}</p>
   {
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
-    ) : paginate ? (
-      <blume-changelog
-        class="not-prose mt-8 block"
-        data-i18n-more={data.ui.changelog?.showReleases}
-      >
-        {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
-          <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content components={components} />
-          </Update>
-        ))}
-        {majorGroups.slice(1).map((group) => (
+    ) : (
+      <div class="not-prose mt-10 divide-y divide-border border-border border-y">
+        {groups.map((group) => (
           <section
-            aria-label={group.label + " releases"}
-            data-changelog-label={group.label}
-            data-changelog-major={group.major}
+            aria-label={group.year ?? undefined}
+            class="grid md:grid-cols-[6rem_minmax(0,1fr)] md:gap-x-8"
           >
-            {group.items.map(({ Content, href, id, label, date, tags }) => (
-              <Update description={date} href={href} id={id} label={label} tags={tags}>
-                <Content components={components} />
-              </Update>
-            ))}
+            <h2 class="mt-0! pt-3! font-medium! text-muted-foreground text-sm! leading-5! tabular-nums max-md:pb-1">
+              {group.year}
+            </h2>
+            <ul class="m-0! list-none divide-y divide-border p-0!">
+              {group.items.map((item) => (
+                <li class="m-0! p-0!" id={item.id}>
+                  <a
+                    class="group/release flex items-baseline gap-4 py-3 no-underline! hover:no-underline!"
+                    href={item.href ?? "#" + item.id}
+                  >
+                    <span class="min-w-0 flex-1 font-medium text-foreground text-sm transition-colors group-hover/release:text-accent">
+                      {item.label}
+                    </span>
+                    {item.tag && (
+                      <span class="shrink-0 rounded-full bg-muted px-2 py-0.5 font-medium text-[0.65rem] text-muted-foreground">
+                        {item.tag}
+                      </span>
+                    )}
+                    {item.date && (
+                      <time
+                        class="shrink-0 font-mono text-muted-foreground text-xs tabular-nums"
+                        datetime={item.dateTime}
+                      >
+                        {item.date}
+                      </time>
+                    )}
+                  </a>
+                </li>
+              ))}
+            </ul>
           </section>
         ))}
-        <div class="mt-10 flex justify-center">
-          <button
-            class="inline-flex items-center gap-2 rounded-full border border-border bg-background px-4 py-2 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground"
-            data-changelog-more
-            hidden
-            type="button"
-          >
-            Show older releases
-          </button>
-        </div>
-      </blume-changelog>
-    ) : (
-      <div class="not-prose mt-8">
-        {items.map(({ Content, href, id, label, date, tags }) => (
-          <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content components={components} />
-          </Update>
-        ))}
       </div>
     )
   }
-  <script>
-    import "blume/components/content/changelog-element.ts";
-  </script>
 </LayoutComponent>
 `;
 };
@@ -2766,7 +2777,7 @@ 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
+// \`deployment.site\`; llms.txt only when \`agents.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) => ({
@@ -2780,6 +2791,31 @@ const suggestions = [
     ? [{ href: withBase("/llms.txt"), label: nf.llms }]
     : []),
 ];
+
+// Every host serves this one page for any missing URL, so a reader who
+// mistyped \`/ar/…\` would get the default locale's message. The other locales'
+// copy rides along, and the script below swaps it in when the URL's first
+// segment names one of them — the message, its language and direction, the
+// tab title, and the home link (to that locale's root).
+const localized = Object.fromEntries(
+  (i18n?.locales ?? [])
+    .filter((l) => l.code !== i18n?.defaultLocale && data.uiByLocale[l.code])
+    .map((l) => {
+      const strings = data.uiByLocale[l.code].notFound;
+      return [
+        l.code,
+        {
+          description: strings.description,
+          dir: l.dir ?? "ltr",
+          home: strings.home,
+          homeHref: withBase("/" + l.code),
+          suggestions: strings.suggestions,
+          title: strings.title,
+        },
+      ];
+    })
+);
+const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
 ---
 
 <PageLayout
@@ -2801,6 +2837,8 @@ const suggestions = [
 >
   <div
     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"
+    data-base={withBase("/")}
+    data-blume-not-found
   >
     <div class="flex flex-col items-start">
       <p
@@ -2810,24 +2848,26 @@ const suggestions = [
       </p>
       <h1
         class="mt-4 text-balance text-4xl font-semibold tracking-tight text-foreground sm:text-5xl"
+        data-nf="title"
       >
         {nf.title}
       </h1>
-      <p class="mt-4 max-w-md text-pretty text-lg text-muted-foreground">
+      <p class="mt-4 max-w-md text-pretty text-lg text-muted-foreground" data-nf="description">
         {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"
+        data-nf-home
         href={withBase("/")}
       >
         <Icon class="rtl:-scale-x-100" name="arrow-left" size={14} />
-        {nf.home}
+        <span data-nf="home">{nf.home}</span>
       </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">
+        <nav aria-label={nf.suggestions} class="md:border-s md:border-border md:ps-12 lg:ps-16" data-nf-suggestions>
+          <h2 class="text-xs font-medium uppercase tracking-widest text-muted-foreground" data-nf="suggestions">
             {nf.suggestions}
           </h2>
           <ul class="mt-4 divide-y divide-border border-y border-border">
@@ -2851,6 +2891,37 @@ const suggestions = [
       )
     }
   </div>
+  <script id="blume-not-found-locales" is:inline type="application/json" set:html={localizedJson} />
+  <script is:inline>
+    (() => {
+      const apply = () => {
+        const root = document.querySelector("[data-blume-not-found]");
+        const source = document.getElementById("blume-not-found-locales");
+        if (!root || !source) {
+          return;
+        }
+        const base = root.getAttribute("data-base") || "/";
+        const path = location.pathname.startsWith(base)
+          ? location.pathname.slice(base.length)
+          : location.pathname.replace(/^\\/+/, "");
+        const code = path.split("/")[0];
+        const entry = JSON.parse(source.textContent || "{}")[code];
+        if (!entry) {
+          return;
+        }
+        root.setAttribute("lang", code);
+        root.setAttribute("dir", entry.dir);
+        for (const el of root.querySelectorAll("[data-nf]")) {
+          el.textContent = entry[el.getAttribute("data-nf")];
+        }
+        root.querySelector("[data-nf-home]")?.setAttribute("href", entry.homeHref);
+        root.querySelector("[data-nf-suggestions]")?.setAttribute("aria-label", entry.suggestions);
+        document.title = entry.title;
+      };
+      apply();
+      document.addEventListener("astro:page-load", apply);
+    })();
+  </script>
 </PageLayout>
 `;
 
@@ -2859,7 +2930,9 @@ const suggestions = [
  * 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`).
+ * builds wire that into the routing config (`deploy/vercel-negotiation.ts`)
+ * and Cloudflare server builds into the wrapper Worker
+ * (`deploy/cloudflare-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
@@ -2929,8 +3002,8 @@ export function GET() {
  * Generate `.blume/src/pages/404.json.ts`: the JSON twin of the default 404
  * page, prerendered to `dist/404.json` as RFC 9457 problem details. An agent
  * that asked for a missing page with `Accept: application/json` gets this body
- * with the 404 status instead of the HTML shell (Vercel server builds wire
- * that into the routing config, like the Markdown twin). Same recovery links
+ * with the 404 status instead of the HTML shell (Vercel and Cloudflare server
+ * builds wire that into the deploy, like the Markdown twin). Same recovery links
  * as the other variants, carried as `links` and spelled out in `resolution`.
  * Written alongside `404.astro` and skipped under the same rule.
  */
@@ -3079,71 +3152,6 @@ const context = ${JSON.stringify(context)};
 export const ALL: APIRoute = ({ request }) => apiNotFoundResponse(request, context);
 `;
 
-/** The literal Astro hydration directive for an island's client mode. */
-const islandDirective = (spec: IslandSpec): string =>
-  spec.client === "only"
-    ? `client:only="${spec.framework}"`
-    : `client:${spec.client}`;
-
-/**
- * Frontmatter `Props` alias mirroring the wrapped component's own props, so
- * `{...Astro.props}` satisfies required props under `astro check` (the spread
- * of an untyped `Astro.props` contributes nothing to the JSX props type).
- * `infer P extends object` rather than `Record<string, unknown>` because
- * interfaces have no implicit index signature and would miss the narrower
- * constraint. Non-function component types (Vue/Svelte ambient modules) fall
- * back to an open record, keeping the untyped permissiveness they had.
- */
-const wrapperPropsType = (name: string): string =>
-  `type Props = typeof ${name} extends (
-  props: infer P extends object,
-  ...rest: never[]
-) => unknown
-  ? P
-  : Record<string, unknown>;`;
-
-/**
- * Generate `.blume/src/generated/islands/<Name>.astro` — a wrapper that renders
- * a convention island with its hydration directive applied. Astro client
- * directives must be written statically, so one wrapper is emitted per island;
- * props and the default slot (MDX children) forward through.
- */
-export const islandWrapperTemplate = (spec: IslandSpec): string =>
-  `---
-// Generated by Blume. Do not edit.
-import Island from ${JSON.stringify(spec.file)};
-${wrapperPropsType("Island")}
----
-<Island ${islandDirective(spec)} {...Astro.props}><slot /></Island>
-`;
-
-/**
- * Generate `.blume/src/generated/islands.ts` — the map of island names to their
- * wrappers, spread into the MDX component scope by the catch-all page. Always
- * written (an empty map when there are no islands) so the import resolves.
- */
-export const islandMapTemplate = (specs: IslandSpec[]): string => {
-  if (specs.length === 0) {
-    return `// Generated by Blume. Do not edit.
-export const islandComponents = {};
-`;
-  }
-  const imports = specs
-    .map(
-      (spec, index) => `import I${index} from "./islands/${spec.name}.astro";`
-    )
-    .join("\n");
-  const entries = specs
-    .map((spec, index) => `  ${spec.name}: I${index},`)
-    .join("\n");
-  return `// Generated by Blume. Do not edit.
-${imports}
-export const islandComponents = {
-${entries}
-};
-`;
-};
-
 /** The literal Astro hydration directive for an example's framework/client. */
 const exampleDirective = (spec: ExampleSpec): string => {
   if (spec.framework === "astro" || !spec.client) {
@@ -3169,12 +3177,17 @@ export const exampleSlug = (path: string): string =>
 /**
  * Generate `.blume/src/generated/examples/<slug>.astro` — a wrapper that renders
  * one example live, with its hydration directive applied (none for `.astro`).
- * Mirrors {@link islandWrapperTemplate}; `<Component>` resolves these by path.
+ * Mirrors the component-slot wrappers (`component-slots.ts`); `<Component>`
+ * resolves these by path.
  */
-export const exampleWrapperTemplate = (spec: ExampleSpec): string =>
+export const exampleWrapperTemplate = (
+  spec: ExampleSpec,
+  /** The wrapper's directory, when its import must be relative (eject). */
+  fromDir?: string
+): string =>
   `---
 // Generated by Blume. Do not edit.
-import Example from ${JSON.stringify(spec.file)};
+import Example from ${JSON.stringify(importSpecifier(spec.file, fromDir))};
 ${wrapperPropsType("Example")}
 ---
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>