blume 1.6.6 → 1.7.0

package/dist/cli/{chunk-0ewz4trd.js → chunk-y3g15rvv.js}

@@ -18,15 +18,15 @@ import {
 } from "./chunk-btfr9yvw.js";
 import {
   buildMcpData
-} from "./chunk-n4qjabmt.js";
-import"./chunk-5yvt556e.js";
-import"./chunk-3k0kzs6d.js";
+} from "./chunk-ynacq3ev.js";
+import"./chunk-v5mm027v.js";
+import"./chunk-j6pxe0dt.js";
 import"./chunk-vxv4x1n8.js";
 import {
   YAML_SCHEMA,
   scanProject
-} from "./chunk-etsqspj6.js";
-import"./chunk-vv3f8mb6.js";
+} from "./chunk-s102bysw.js";
+import"./chunk-xv91q4nm.js";
 import"./chunk-27gtm2ym.js";
 import"./chunk-4xyggvgf.js";
 import"./chunk-6kzzpsx8.js";
@@ -676,4 +676,4 @@ export {
 };
 
 //# debugId=D2F08D9122CA47D464756E2164756E21
-//# sourceMappingURL=chunk-0ewz4trd.js.map
+//# sourceMappingURL=chunk-y3g15rvv.js.map

package/dist/cli/{chunk-tc89yh2r.js → chunk-ye9zdkgv.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   resolveRuntimeDir
-} from "./chunk-vv3f8mb6.js";
+} from "./chunk-xv91q4nm.js";
 import {
   logger
 } from "./chunk-ey89bjj1.js";
@@ -133,4 +133,4 @@ var refuseIfDevRunning = (root, action, options = {}) => {
 export { readDevLock, DevLockHeldError, acquireDevLock, updateDevLockPort, describeDevLock, refuseIfDevRunning };
 
 //# debugId=1007843429DAE30664756E2164756E21
-//# sourceMappingURL=chunk-tc89yh2r.js.map
+//# sourceMappingURL=chunk-ye9zdkgv.js.map

package/dist/cli/{chunk-n4qjabmt.js → chunk-ynacq3ev.js}

@@ -2,13 +2,13 @@
 import {
   readExpandedEntryText,
   rewriteRelativeImages
-} from "./chunk-5yvt556e.js";
+} from "./chunk-v5mm027v.js";
 import {
   API_CATALOG_PATH,
   API_PAGES_PATH,
   OPENAPI_PATH,
   hasApiCatalog
-} from "./chunk-3k0kzs6d.js";
+} from "./chunk-j6pxe0dt.js";
 import {
   absoluteUrl,
   siteRoot
@@ -23,7 +23,7 @@ import {
   parseHeadingMarkers,
   specAddresses,
   specOf
-} from "./chunk-etsqspj6.js";
+} from "./chunk-s102bysw.js";
 import {
   normalizeBasePath,
   withBasePath
@@ -1059,4 +1059,4 @@ var buildMcpData = async (project) => {
 export { buildRssFeeds, renderRssFeed, agentMarkdown, markdownTokenCount, buildRawMarkdown, markdownRoutePaths, buildSearchDocuments, buildMcpData };
 
 //# debugId=8258B61E89F8EE8E64756E2164756E21
-//# sourceMappingURL=chunk-n4qjabmt.js.map
+//# sourceMappingURL=chunk-ynacq3ev.js.map

package/dist/cli/{chunk-s4jn7f1q.js → chunk-zr3ygrq3.js}

@@ -8,7 +8,7 @@ import {
 import {
   loadConfig,
   resolveProjectContext
-} from "./chunk-vv3f8mb6.js";
+} from "./chunk-xv91q4nm.js";
 import"./chunk-27gtm2ym.js";
 import {
   logger
@@ -51,4 +51,4 @@ export {
 };
 
 //# debugId=A0AB802DBFFA2DAA64756E2164756E21
-//# sourceMappingURL=chunk-s4jn7f1q.js.map
+//# sourceMappingURL=chunk-zr3ygrq3.js.map

package/dist/cli/index.js

@@ -57,20 +57,20 @@ var main = defineCommand({
   },
   subCommands: {
     add: lazyCommand(commandMeta.add, () => import("./chunk-4trphnvy.js"), "addCommand"),
-    audit: lazyCommand(commandMeta.audit, () => import("./chunk-x1vrdjyk.js"), "auditCommand"),
-    build: lazyCommand(commandMeta.build, () => import("./chunk-vv237fp3.js"), "buildCommand"),
-    check: lazyCommand(commandMeta.check, () => import("./chunk-cnvm6k3e.js"), "checkCommand"),
-    dev: lazyCommand(commandMeta.dev, () => import("./chunk-ag1zyr5x.js"), "devCommand"),
-    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-m3p3wahd.js"), "doctorCommand"),
-    eject: lazyCommand(commandMeta.eject, () => import("./chunk-f75cqye8.js"), "ejectCommand"),
-    eval: lazyCommand(commandMeta.eval, () => import("./chunk-0ewz4trd.js"), "evalCommand"),
-    init: lazyCommand(commandMeta.init, () => import("./chunk-j00ezcg5.js"), "initCommand"),
+    audit: lazyCommand(commandMeta.audit, () => import("./chunk-cfw6x4rm.js"), "auditCommand"),
+    build: lazyCommand(commandMeta.build, () => import("./chunk-v2ymm99c.js"), "buildCommand"),
+    check: lazyCommand(commandMeta.check, () => import("./chunk-18tjv4f7.js"), "checkCommand"),
+    dev: lazyCommand(commandMeta.dev, () => import("./chunk-9qs6acpw.js"), "devCommand"),
+    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-tnskyrej.js"), "doctorCommand"),
+    eject: lazyCommand(commandMeta.eject, () => import("./chunk-jxkxjsc1.js"), "ejectCommand"),
+    eval: lazyCommand(commandMeta.eval, () => import("./chunk-y3g15rvv.js"), "evalCommand"),
+    init: lazyCommand(commandMeta.init, () => import("./chunk-drke6t0h.js"), "initCommand"),
     "mcp-stdio": lazyCommand(commandMeta["mcp-stdio"], () => import("./chunk-jtb45atp.js"), "mcpStdioCommand"),
-    preview: lazyCommand(commandMeta.preview, () => import("./chunk-s4jn7f1q.js"), "previewCommand"),
-    sync: lazyCommand(commandMeta.sync, () => import("./chunk-s4k1pnvf.js"), "syncCommand"),
-    translate: lazyCommand(commandMeta.translate, () => import("./chunk-wkq5tbtq.js"), "translateCommand"),
-    validate: lazyCommand(commandMeta.validate, () => import("./chunk-n0y172hf.js"), "validateCommand"),
-    version: lazyCommand(commandMeta.version, () => import("./chunk-bawgnt8x.js"), "versionCommand")
+    preview: lazyCommand(commandMeta.preview, () => import("./chunk-zr3ygrq3.js"), "previewCommand"),
+    sync: lazyCommand(commandMeta.sync, () => import("./chunk-kwx90v78.js"), "syncCommand"),
+    translate: lazyCommand(commandMeta.translate, () => import("./chunk-qq9nm3qd.js"), "translateCommand"),
+    validate: lazyCommand(commandMeta.validate, () => import("./chunk-jk1zwka1.js"), "validateCommand"),
+    version: lazyCommand(commandMeta.version, () => import("./chunk-ckh3a410.js"), "versionCommand")
   }
 });
 loadEnvFiles(process.cwd());

package/dist/types/components/layout/nav-utils.d.ts

@@ -1,4 +1,4 @@
-import type { NavNode, NavTab } from "../../core/types.ts";
+import type { NavNode, NavTab, Navigation } from "../../core/types.ts";
 /** A flat, ordered page reference used for previous/next pagination. */
 export interface FlatPage {
     route: string;
@@ -58,3 +58,35 @@ export declare const getPagination: (flat: FlatPage[], route: string) => {
     next: FlatPage | null;
     prev: FlatPage | null;
 };
+/**
+ * A stable id for every group in a sidebar — `g<n>` by pre-order position in
+ * the full tree. The layout hands `NavTree` a scoped view of that tree (a
+ * tab's section, or the sidebar minus the tab sections), so positions within
+ * the rendered slice differ from page to page; these ids name the same group
+ * everywhere, which the drill-in panels and the deferred-section fragments
+ * (`/blume-nav/…`) rely on. Keyed by node identity: the scoped views reuse
+ * the full tree's node objects.
+ */
+export declare const navGroupIds: (sidebar: NavNode[]) => Map<NavNode, string>;
+/** Whether any group in a sidebar renders as a disclosure or a drill-in panel. */
+export declare const hasDeferrableGroups: (sidebar: NavNode[]) => boolean;
+/** One of the navigation trees a site renders, by URL segment. */
+export interface NavVariant {
+    /** `current`, or an archived version id. */
+    version: string;
+    /** `default`, or a locale code. */
+    locale: string;
+    navigation: Navigation;
+}
+/**
+ * Every navigation tree the runtime data holds — the default, each locale's,
+ * and each archived version's per locale — keyed the way the deferred
+ * sidebar fragments' URLs are (`/blume-nav/<version>/<locale>/…`). An
+ * unlocalized version tree is keyed by `""` in the data; it maps to
+ * `default` here.
+ */
+export declare const navVariants: (data: {
+    navigation: Navigation;
+    navigationByLocale: Record<string, Navigation>;
+    navigationByVersion: Record<string, Record<string, Navigation>>;
+}) => NavVariant[];

package/dist/types/theme/fonts.d.ts

@@ -71,27 +71,27 @@ export declare const GOOGLE_FONTS: {
     "dm-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     figtree: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "fira-code": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     geist: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "geist-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "ibm-plex-mono": {
         category: "mono";
@@ -101,7 +101,7 @@ export declare const GOOGLE_FONTS: {
     "ibm-plex-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "ibm-plex-serif": {
         category: "serif";
@@ -111,77 +111,77 @@ export declare const GOOGLE_FONTS: {
     inter: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "inter-tight": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "jetbrains-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     lora: {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     manrope: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     merriweather: {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "open-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "playfair-display": {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "plus-jakarta-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     roboto: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "roboto-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-code-pro": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-sans-3": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-serif-4": {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "space-grotesk": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "space-mono": {
         category: "mono";
@@ -191,7 +191,7 @@ export declare const GOOGLE_FONTS: {
     "work-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
 };
 export type FontSlug = keyof typeof GOOGLE_FONTS;

package/docs/02-deployment.mdx

@@ -141,6 +141,27 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 
 Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.
 
+## Build cache
+
+Blume keeps two caches a build can reuse. Astro's and Vite's caches live under `.blume/.cache/` (the content store and image transforms among them). Rendered [OG cards](/docs/discoverability/open-graph#card-cache) live in `node_modules/.cache/blume/og`, so a rebuild renders only the cards whose title, description, or branding changed. Whether a platform keeps that directory between deploys varies:
+
+- **Vercel** restores `node_modules/**` from its build cache, so cards carry over (the cache is 1 GB, retained for a month, and keyed per branch — a new branch starts from the production cache).
+- **Netlify** restores `node_modules`, so cards carry over.
+- **Cloudflare Workers Builds** persists only package-manager caches and, for a detected Astro project, `node_modules/.astro` — never `node_modules/.cache` — so every deploy renders every card there.
+- **GitHub Actions** and other runners you manage keep nothing unless you cache the directory yourself:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: node_modules/.cache/blume/og
+    key: blume-og-${{ runner.os }}-${{ hashFiles('**/bun.lock', '**/package-lock.json', '**/pnpm-lock.yaml') }}
+    restore-keys: blume-og-${{ runner.os }}-
+```
+
+Cards are keyed by content, so an imprecise key is fine: a restored cache only ever saves renders, never serves a wrong card.
+
+One install command discards the cache on every platform: `npm ci` deletes `node_modules` before installing. Keep `npm install`, `bun install`, or `pnpm install` as the install command to get the reuse.
+
 ## Build summary
 
 Every build prints a summary — output mode, adapter, resolved site URL, search provider, redirect count, sitemap and `llms.txt` status, and any enabled server features — so you can confirm what shipped (including anything auto-detected) before you deploy.

package/docs/content/navigation.mdx

@@ -69,6 +69,8 @@ navigation: {
 `page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
 :::
 
+In both `group` and `page` mode, a section that isn't open on the current page is left out of that page's HTML and fetched the first time it's opened (it's prefetched as soon as the pointer or focus reaches its row, so the open is usually instant, and a section fetched once is kept for the rest of the visit). On a large site this is most of a page's weight: only the open section's rows ship with the page. The rows are prerendered fragments under `/blume-nav/`, so they need no server. Readers without JavaScript see the open section and the group rows; the sitemap, the previous/next links, and the open section keep every page reachable for crawlers.
+
 ### Per-group overrides
 
 Any generated group can opt out of the global mode — no explicit sidebar required. Set `display` in the folder's [`meta.ts`](/docs/content/meta), or — when the folder has an `index` page — under `sidebar` in that page's frontmatter, and only that group changes:

package/docs/content/syntax.mdx

@@ -384,7 +384,7 @@ flowchart LR
 ```
 ````
 
-Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. Diagrams use Mermaid's dagre layout and classic look by default; opt a single diagram into another layout or look through Mermaid front matter (a `config:` block with `layout: elk` or `look: neo`), and the ELK engine loads only for diagrams that ask for it. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
+Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one; a site with no diagram doesn't ship it at all. Diagrams use Mermaid's dagre layout and classic look by default; opt a single diagram into another layout or look through Mermaid front matter (a `config:` block with `layout: elk` or `look: neo`), and the ELK engine loads only for diagrams that ask for it. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
 
 ### Flowchart
 

package/docs/discoverability/open-graph.mdx

@@ -94,6 +94,10 @@ Google families are fetched at build — so a build that uses them needs network
 
 An explicit `og.fonts: []` opts out entirely: cards keep the built-in font even when `theme.fonts` is set.
 
+## Card cache
+
+Rendered cards are cached on disk between builds, keyed by everything that decides their pixels: the page title and description, the brand text, logo, palette, footer text, and fonts (a local font file by its contents), plus the Blume version. A rebuild renders only the cards whose inputs changed and reads the rest back; the build log reports how many were reused. The cache lives in `node_modules/.cache/blume/og`; on a platform that keeps `node_modules` between builds (Vercel and Netlify do, Cloudflare does not) or a CI runner that caches that directory (see [Build cache](/docs/deployment#build-cache)), a deploy that touches a handful of pages re-renders a handful of cards. Cards that no page asked for are removed after each build, so the directory only ever holds the current site's cards.
+
 ## Custom page titles
 
 A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.6",
+  "version": "1.7.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -30,9 +30,14 @@ import { buildAskData } from "../ai/ask-data.ts";
 import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
+import type { RawMarkdownEntry } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import {
+  hasDeferrableGroups,
+  navVariants,
+} from "../components/layout/nav-utils.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import { analyzeComponentOverrides } from "../core/component-overrides.ts";
@@ -68,7 +73,14 @@ import { svgDimensions } from "../core/svg-dimensions.ts";
 import { trimChar } from "../core/trim.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Diagnostic, Navigation } from "../core/types.ts";
+import { getBlumeVersion } from "../core/version.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import {
+  languageIconCss,
+  languageIconSlugsIn,
+} from "../markdown/language-icon.ts";
+import { hasMermaidFence } from "../markdown/mermaid.ts";
+import { ogCacheDir } from "../og/cache.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
@@ -148,10 +160,13 @@ import {
   runtimeDependencies,
   runtimePackageTemplate,
   runtimeTsconfigTemplate,
+  featuresTemplate,
+  navFragmentTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
   stagedContentDir,
 } from "./templates.ts";
+import type { ClientFeatures } from "./templates.ts";
 
 /** Absolute path to the Blume package `src` directory. */
 const BLUME_SRC = join(packageRoot(), "src");
@@ -322,10 +337,35 @@ export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
 };
 
 /**
- * Point `link` at Blume's dependency directory via a `node_modules` junction,
- * replacing a stale junction we own and leaving a real directory untouched.
+ * Create `link` as a directory symlink to `target`, falling back to a junction.
  *
- * `lstat`, not `existsSync`, so a broken junction (target since moved) is still
+ * The type only matters on Windows, and there a junction is the wrong first
+ * choice: Windows can't follow a *relative* symlink reached through a
+ * junction (it resolves the relative target against the junction-side path,
+ * so it lands outside the store and every lookup is ENOENT), and Bun's
+ * isolated linker writes exactly those into Blume's dependency directory
+ * whenever it holds symlink privilege. A directory symlink traverses them
+ * fine. Without that privilege (no Developer Mode, non-admin shell) creating
+ * one fails, so fall back to a junction — and in that session the installer
+ * had no privilege either, so the deps are absolute junctions a junction can
+ * follow. Exported for testing.
+ */
+export const symlinkDir = async (
+  target: string,
+  link: string
+): Promise<void> => {
+  try {
+    await symlink(target, link, "dir");
+  } catch {
+    await symlink(target, link, "junction");
+  }
+};
+
+/**
+ * Point `link` at Blume's dependency directory via a `node_modules` link,
+ * replacing a stale link we own and leaving a real directory untouched.
+ *
+ * `lstat`, not `existsSync`, so a broken link (target since moved) is still
  * detected — `existsSync` follows the link and reports a dangling one as absent.
  */
 const linkDepsJunction = async (
@@ -356,7 +396,7 @@ const linkDepsJunction = async (
     await rm(link, { force: true });
   }
   await mkdir(dirname(link), { recursive: true });
-  await symlink(depsDir, link, "junction");
+  await symlinkDir(depsDir, link);
 };
 
 /** Read the `version` field of a `package.json`, or null when unreadable. */
@@ -1894,6 +1934,84 @@ const assertFontFilesExist = (project: BlumeProject): void => {
   }
 };
 
+/**
+ * The client libraries a site needs (see `featuresTemplate`): the EPUB
+ * generator when `export.epub` is on, and the Mermaid element when any page's
+ * source has a mermaid fence — read from the raw-Markdown mirrors (every
+ * route's verbatim source) and, for sources that carry their text on the
+ * page record, the record itself.
+ */
+export const clientFeaturesFrom = (
+  project: BlumeProject,
+  rawMarkdown: Record<string, RawMarkdownEntry>
+): ClientFeatures => ({
+  epub: project.config.export.epub,
+  mermaid:
+    Object.values(rawMarkdown).some((entry) =>
+      hasMermaidFence(entry.mdx ?? entry.md ?? "")
+    ) ||
+    project.graph.pages.some(
+      (page) => page.body !== undefined && hasMermaidFence(page.body.text)
+    ),
+});
+
+/**
+ * The theme's code-block icon rules for the languages the site's Markdown
+ * uses (see `languageIconCss`), read from the raw-Markdown mirrors and the
+ * page records that carry their text.
+ */
+export const languageIconCssFrom = (
+  project: BlumeProject,
+  rawMarkdown: Record<string, RawMarkdownEntry>
+): string =>
+  languageIconCss(
+    languageIconSlugsIn(
+      [
+        ...Object.values(rawMarkdown).map(
+          (entry) => entry.mdx ?? entry.md ?? ""
+        ),
+        ...project.graph.pages.map((page) => page.body?.text ?? ""),
+      ].join("\n")
+    )
+  );
+
+/** {@link languageIconCssFrom} over a fresh read of the raw Markdown (eject). */
+export const languageIconCssFor = async (
+  project: BlumeProject
+): Promise<string> =>
+  languageIconCssFrom(project, await buildRawMarkdown(project));
+
+/**
+ * The deferred sidebar fragments page, only when some group is a disclosure
+ * or a drill-in panel — a flat sidebar renders every row on every page, so
+ * there is nothing to fetch. A previous pass's page is an orphan the
+ * generator removes when the sidebar goes flat again.
+ */
+const writeNavFragments = (
+  write: (path: string, content: string) => Promise<boolean>,
+  srcDir: string,
+  navFragments: boolean
+): Promise<boolean> =>
+  navFragments
+    ? write(
+        join(
+          srcDir,
+          "pages",
+          "blume-nav",
+          "[version]",
+          "[locale]",
+          "[id].astro"
+        ),
+        navFragmentTemplate()
+      )
+    : Promise.resolve(false);
+
+/** {@link clientFeaturesFrom} over a fresh read of the raw Markdown (eject). */
+export const clientFeaturesFor = async (
+  project: BlumeProject
+): Promise<ClientFeatures> =>
+  clientFeaturesFrom(project, await buildRawMarkdown(project));
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -1909,6 +2027,7 @@ export const generateRuntime = async (
   const askPath = join(srcDir, "generated", "Ask.astro");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
+  const featuresPath = join(srcDir, "generated", "features.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
   const examplesThemePath = join(srcDir, "generated", "examples.css");
 
@@ -1937,6 +2056,14 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  // Every route's source Markdown: published as `blume:raw-markdown` below,
+  // and inspected here for the client features the site needs.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const clientFeatures = clientFeaturesFrom(project, rawMarkdown);
+  const navFragments = navVariants(project.graph).some(({ navigation }) =>
+    hasDeferrableGroups(navigation.sidebar)
+  );
+  const languageIcons = languageIconCssFrom(project, rawMarkdown);
   // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
   // entryId so i18n duplicates of one entry write a single file. Collected here
   // so math detection also sees staged bodies (they never live under root).
@@ -2060,6 +2187,8 @@ export const generateRuntime = async (
           context,
           examplesPath,
           examplesThemePath,
+          features: clientFeatures,
+          featuresPath,
           integrationBridge,
           needsReact,
           needsSvelte,
@@ -2093,9 +2222,11 @@ export const generateRuntime = async (
           exportEpub,
           exportPdf,
           mathEnabled: usesMath,
+          navFragments,
           needsReact,
         })
       ),
+      writeNavFragments(write, srcDir, navFragments),
       // The header's Ask trigger, behind the `blume:ask` alias. Always written
       // (even when Ask is off, as a component that renders nothing) so the alias
       // resolves — the same contract as `blume:search-client`.
@@ -2127,6 +2258,7 @@ export const generateRuntime = async (
         themePath,
         tailwindEntryTemplate({
           configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
+          languageIcons,
           sources: [
             `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
             `${context.root}/**/*.{astro,mdx,ts,tsx}`,
@@ -2189,6 +2321,10 @@ export const generateRuntime = async (
         ogRoutes,
         {
           ...projectOgFonts(project),
+          cache: {
+            dir: ogCacheDir(project.context),
+            version: getBlumeVersion(),
+          },
           pageDescriptions: config.seo.og.description !== false,
         },
         changelogIndex
@@ -2225,6 +2361,7 @@ export const generateRuntime = async (
     }),
     writeNotFoundPage(write, srcDir, pages, project.graph.pages),
     write(searchClientPath, searchClientTemplate(config)),
+    write(featuresPath, featuresTemplate(clientFeatures)),
   ]);
 
   // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
@@ -2253,7 +2390,6 @@ export const generateRuntime = async (
     `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`
   );
 
-  const rawMarkdown = await buildRawMarkdown(project);
   modules.set("blume:raw-markdown", JSON.stringify(rawMarkdown));
   // The originals behind the rewritten `/blume-assets/content/…` references in
   // the agent-facing Markdown, plus the endpoint that serves them (and the

package/src/astro/integration.ts

@@ -374,8 +374,19 @@ export const blumeIntegration = (
           filename: MODULE_TYPES_FILE,
         });
       },
-      "astro:config:setup": ({ createCodegenDir, injectRoute }) => {
+      "astro:config:setup": ({
+        addMiddleware,
+        createCodegenDir,
+        injectRoute,
+      }) => {
         codegenDir = createCodegenDir();
+        // Splices each page's icon sprite in once the page has rendered (see
+        // components/icon-sprite-middleware.ts). Innermost, so a project's
+        // own middleware sees the finished HTML.
+        addMiddleware({
+          entrypoint: "blume/components/icon-sprite-middleware.ts",
+          order: "post",
+        });
         for (const page of options.pages) {
           injectRoute({
             entrypoint: page.entrypoint,