blume 1.6.6 → 1.7.0

package/src/astro/module-types.ts

@@ -66,6 +66,15 @@ declare module "blume:openapi" {
   export default specs;
 }
 
+declare module "blume:features" {
+  /** Registers the <blume-mermaid> element; null when no page has a mermaid fence. */
+  export const loadMermaid: (() => Promise<unknown>) | null;
+  /** The EPUB generator's browser bundle; null when export.epub is off. */
+  export const loadEpub:
+    | (() => Promise<typeof import("epub-gen-memory/bundle")>)
+    | null;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn

package/src/astro/templates.ts

@@ -14,6 +14,7 @@ import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.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";
@@ -137,6 +138,18 @@ const resolveSessionOption = (deployment: {
     ? "\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,
+ * which the OG cards use) write `"100..900"`. Astro treats the dotted form as
+ * an unknown discrete weight and loads nothing for it.
+ */
+const astroFontWeights = (weights: (number | string)[]): string =>
+  JSON.stringify(weights).replaceAll(
+    /(?<min>\d+)\.\.(?<max>\d+)/gu,
+    "$<min> $<max>"
+  );
+
 /** The named imports the generated config pulls from `astro/config`. */
 const astroConfigImportLine = (options: { hasFonts: boolean }): string => {
   const names = ["defineConfig"];
@@ -389,13 +402,31 @@ interface OptimizeDepsConfig {
  * absolute path (see `reactIntegration`), which that check never matches. See
  * the optimizeDeps comment in the generated config for the failure this prevents.
  */
+/**
+ * The client-side libraries a site needs, decided at generation time. A
+ * feature no page uses is left out of the module graph entirely (see
+ * {@link featuresTemplate}), so its library never enters the client bundle —
+ * Mermaid alone is over 3 MB of chunks (ELK, Cytoscape, KaTeX, every diagram
+ * type) and most of the build's client-bundle memory.
+ */
+export interface ClientFeatures {
+  /** `export.epub` is on: the EPUB generator's browser bundle is needed. */
+  epub: boolean;
+  /** Some page has a mermaid fence: the `<blume-mermaid>` element is needed. */
+  mermaid: boolean;
+}
+
+/** Every feature on: what a checkout that predates the detection shipped. */
+const ALL_CLIENT_FEATURES: ClientFeatures = { epub: true, mermaid: true };
+
 const resolveOptimizeDeps = (options: {
   aliases: Record<string, string> | undefined;
   context: ProjectContext;
+  features: ClientFeatures;
   needsReact: boolean;
   reactCompilerPath: string | null | undefined;
 }): OptimizeDepsConfig => {
-  const { context } = options;
+  const { context, features } = options;
   const optimizeDepsEntries = [
     ...(context.pagesRoot ? [`${context.pagesRoot}/**/*.astro`] : []),
     `${context.root}/islands/**/*.{jsx,svelte,tsx,vue}`,
@@ -404,8 +435,10 @@ const resolveOptimizeDeps = (options: {
       .map((dir) => `${dir}/**/*.{astro,jsx,svelte,tsx,vue}`),
   ];
   const optimizeDepsInclude = [
-    "blume > mermaid",
-    "blume > epub-gen-memory/bundle",
+    // Only the libraries the site's features actually import: pre-bundling
+    // Mermaid costs the dev server seconds at startup for nothing otherwise.
+    ...(features.mermaid ? ["blume > mermaid"] : []),
+    ...(features.epub ? ["blume > epub-gen-memory/bundle"] : []),
     // Astro's own client-router/prefetch virtual modules are deliberately NOT
     // forced in here: they read Vite `define`-injected constants
     // (__PREFETCH_PREFETCH_ALL__ and friends) that a pre-bundled copy loses,
@@ -494,6 +527,10 @@ export const astroConfigTemplate = (options: {
   examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
+  /** The generated client-feature loaders (`blume:features`). */
+  featuresPath: string;
+  /** Which client features the site uses; every feature on when omitted. */
+  features?: ClientFeatures;
   /**
    * Where the runtime data modules (`blume:data`, the search index, …) live as
    * JSON files, for a project with no CLI to publish them in memory (eject):
@@ -528,6 +565,8 @@ export const astroConfigTemplate = (options: {
     contentRoutes,
     examplesPath,
     examplesThemePath,
+    features = ALL_CLIENT_FEATURES,
+    featuresPath,
     generatedModulesDir,
     needsSvelte,
     needsVue,
@@ -549,6 +588,7 @@ export const astroConfigTemplate = (options: {
   const { optimizeDepsEntries, optimizeDepsInclude } = resolveOptimizeDeps({
     aliases: options.aliases,
     context,
+    features,
     needsReact,
     reactCompilerPath: options.reactCompilerPath,
   });
@@ -666,9 +706,7 @@ export const astroConfigTemplate = (options: {
                 font.name
               )}, cssVariable: ${JSON.stringify(
                 font.cssVariable
-              )}, weights: ${JSON.stringify(
-                font.weights
-              )}, subsets: ${JSON.stringify(
+              )}, weights: ${astroFontWeights(font.weights)}, subsets: ${JSON.stringify(
                 font.subsets
               )}, fallbacks: ${JSON.stringify(font.fallbacks)} }`
         )
@@ -750,7 +788,8 @@ export const astroConfigTemplate = (options: {
   } = renderIntegrationBridge(options.integrationBridge);
 
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
-${configSourceMarker}${userConfigImports}${defineConfigImport}
+${configSourceMarker}${userConfigImports}import { availableParallelism } from "node:os";
+${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
@@ -795,6 +834,12 @@ ${userConfigSetup}export default defineConfig({
   // request latency behind the user's intent, so most navigations swap
   // instantly.
   prefetch: { prefetchAll: true },
+  // Prerender several pages at once. Rendering is single-threaded, but a
+  // page's OG card renders on a native thread and its HTML is written
+  // asynchronously, so the main thread would otherwise idle behind each
+  // page's off-thread work. Capped at 8: the gain flattens there and beyond it
+  // 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`
@@ -847,6 +892,7 @@ ${userConfigSetup}export default defineConfig({
         "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}
       },
@@ -1289,6 +1335,34 @@ const hostedSearchOptions = (
   }
 };
 
+/**
+ * Generate `.blume/src/generated/features.ts` — the client-feature loaders
+ * behind the `blume:features` alias. Each loader is a dynamic import when the
+ * site uses the feature and `null` otherwise, so an unused library is absent
+ * from the module graph (never bundled, never pre-bundled in dev) rather than
+ * merely lazy. Regenerated on every pass: a page that gains a mermaid fence
+ * turns the loader on.
+ */
+export const featuresTemplate = (features: ClientFeatures): string =>
+  `// Generated by Blume. Do not edit.
+//
+// The client features this site uses. A feature no page needs stays out of
+// the module graph entirely: its loader is null and its library never enters
+// the client bundle.
+
+/** Registers the <blume-mermaid> element; null when no page has a mermaid fence. */
+export const loadMermaid: (() => Promise<unknown>) | null = ${
+    features.mermaid
+      ? '() => import("blume/components/content/mermaid-element.ts")'
+      : "null"
+  };
+
+/** The EPUB generator's browser bundle; null when export.epub is off. */
+export const loadEpub:
+  | (() => Promise<typeof import("epub-gen-memory/bundle")>)
+  | null = ${features.epub ? '() => import("epub-gen-memory/bundle")' : "null"};
+`;
+
 /**
  * Generate `.blume/src/generated/search-client.ts` — the provider-specific
  * loader the `<Search>` component lazy-imports via the `blume:search-client`
@@ -1610,10 +1684,77 @@ export function GET({ props }: { props: { section: string } }) {
 }
 `;
 
+/**
+ * Generate the deferred sidebar fragments page
+ * (`.blume/src/pages/blume-nav/[version]/[locale]/[id].astro`): one
+ * prerendered partial per collapsible or drill-in group, holding just that
+ * group's rows, which the sidebar fetches on first open instead of carrying
+ * every collapsed section on every page. Ids are `navGroupIds` over the full
+ * tree, the same ids the pages' sidebars use; the `version`/`locale`
+ * segments pick the navigation variant (`current`/`default` for the
+ * unversioned, unlocalized tree). Rendered with no current route — a
+ * section that isn't on the active path has no active row by definition.
+ */
+export const navFragmentTemplate = (): string =>
+  `---
+// Generated by Blume. Do not edit.
+import NavTree from "blume/components/layout/NavTree.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { navGroupIds, navVariants } from "blume/components/layout/nav-utils.ts";
+import type { NavNode } from "blume/core/types.ts";
+import data from "blume:data";
+
+export const prerender = true;
+// A partial: no doctype, head, or script/style injection — the rows only.
+export const partial = true;
+
+// Only imports are in scope here (Astro hoists getStaticPaths), which is why
+// the variant walk lives in nav-utils.
+export function getStaticPaths() {
+  return navVariants(data).flatMap(({ locale, navigation, version }) =>
+    [...navGroupIds(navigation.sidebar)]
+      .filter(([node]) => (node.display ?? "flat") !== "flat")
+      .map(([, id]) => ({ params: { id, locale, version } }))
+  );
+}
+
+const { id, locale, version } = Astro.params;
+const variant = navVariants(data).find(
+  (entry) => entry.version === version && entry.locale === locale
+);
+const ids = variant
+  ? navGroupIds(variant.navigation.sidebar)
+  : new Map<NavNode, string>();
+const node = [...ids].find(([, groupId]) => groupId === id)?.[0];
+if (!(variant && node && node.kind === "group")) {
+  return new Response(null, { status: 404 });
+}
+const strings =
+  locale === "default" ? data.ui.nav : (data.uiByLocale[locale] ?? data.ui).nav;
+const fragmentBase = withBase(\`/blume-nav/\${version}/\${locale}\`);
+---
+
+<NavTree
+  currentRoute=""
+  depth={1}
+  fragmentBase={fragmentBase}
+  idPrefix={id}
+  ids={ids}
+  items={node.children}
+  root={false}
+  strings={strings}
+/>
+`;
+
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
   og: {
+    /**
+     * The on-disk card cache (directory plus the rendering Blume version).
+     * Absent, every card renders on every build.
+     */
+    cache?: OgCache;
     families?: OgFontFamilies;
     fonts?: OgFont[];
     /**
@@ -1626,8 +1767,8 @@ export const ogEndpointTemplate = (
   includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
-import { renderOgImage } from "blume/og";
-import type { OgFont, OgFontFamilies } from "blume/og";
+import { cachedOgImage } from "blume/og";
+import type { OgCache, OgFont, OgFontFamilies } from "blume/og";
 import data from "blume:data";
 
 export const prerender = true;
@@ -1646,6 +1787,14 @@ const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
 
+// Rendered cards are kept on disk between builds, keyed by everything that
+// decides their pixels, so a rebuild renders only the cards whose title,
+// description, branding, or fonts changed. The directory is a build-machine
+// path, baked in for the same reason as the local font paths above.
+const cache: OgCache | undefined = ${
+    og.cache ? JSON.stringify(og.cache) : "undefined"
+  };
+
 // A page's own description (its \`seo.description\`, else \`description\`) is
 // the card subtitle, so the image says what the page's og:description says.
 // Pages without one fall back to the site-wide subtitle at render time.
@@ -1705,7 +1854,7 @@ const repoSlug = data.config.github
   : undefined;
 
 export async function GET({ props }: { props: CardProps }) {
-  const png = await renderOgImage({
+  const png = await cachedOgImage(cache, {
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
     description: props.description ?? data.config.og.description,
@@ -1788,6 +1937,12 @@ export const catchAllPageTemplate = (options: {
   exportEpub: boolean;
   exportPdf: boolean;
   mathEnabled: boolean;
+  /**
+   * Whether the sidebar defers collapsed sections to prerendered fragments
+   * (see `navFragmentTemplate`); true when some group renders as a
+   * disclosure or a drill-in panel.
+   */
+  navFragments?: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
   needsReact: boolean;
 }): string => {
@@ -2166,7 +2321,12 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   editUrl={editUrl}
   feedback={data.config.feedback}
   exportPdf={${options.exportPdf}}
-  exportEpub={${options.exportEpub}}
+  exportEpub={${options.exportEpub}}${
+    options.navFragments
+      ? `
+  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n ? locale : "default"}\`)}`
+      : ""
+  }
   openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}

package/src/cli/commands/build.ts

@@ -45,6 +45,7 @@ import {
 } from "../../deploy/function-bundle.ts";
 import { platformRedirects } from "../../deploy/redirects.ts";
 import { injectNegotiationRoutes } from "../../deploy/vercel-negotiation.ts";
+import { cardCacheTally, ogCacheDir, pruneCardCache } from "../../og/cache.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
@@ -248,6 +249,29 @@ const emitCloudflareNegotiation = async (
   );
 };
 
+/**
+ * Report how many OG cards the build read back from the on-disk cache against
+ * how many it rendered (the endpoint tallies both), so a warm rebuild shows
+ * where the time went. With `prune`, also drop the cached cards this build
+ * never asked for — renamed pages, edited descriptions, cards from an earlier
+ * Blume version — so a persisted cache holds exactly the current site's cards.
+ */
+const reportCardCache = async (
+  project: BlumeProject,
+  prune: boolean
+): Promise<void> => {
+  const cards = cardCacheTally();
+  if (!cards) {
+    return;
+  }
+  logger.info(
+    `OG cards: ${cards.hits} reused from the cache, ${cards.misses} rendered`
+  );
+  if (prune) {
+    await pruneCardCache(ogCacheDir(project.context));
+  }
+};
+
 const formatBytes = (bytes: number): string => {
   if (bytes < 1024) {
     return `${bytes} B`;
@@ -557,6 +581,10 @@ export const buildCommand = defineCommand({
       root: project.context.outDir,
     });
 
+    // A real build also prunes the cache; an isolated verify must not evict
+    // cards a live dev server is still serving.
+    await reportCardCache(project, !runtimeDir);
+
     // The bundle report and budget gate still run for an isolated build —
     // `blume build --isolated --budget-js 100` exiting 0 without measuring
     // anything would be a silent false pass in CI.

package/src/components/Icon.astro

@@ -1,6 +1,7 @@
 ---
 import { isImageIcon, isInlineSvg } from "../theme/icon-kind.ts";
 import { resolveIcon } from "../theme/icons.ts";
+import { iconSpriteFor, registerIconSymbol } from "./icon-sprite.ts";
 import { withBase } from "./islands/base-path.ts";
 
 interface Props {
@@ -32,6 +33,17 @@ const rawSvg = iconName && isInlineSvg(iconName) ? iconName.trim() : null;
 const imageSrc = iconName && !rawSvg && isImageIcon(iconName) ? iconName : null;
 const resolvedIcon =
   iconName && !(imageSrc || rawSvg) ? resolveIcon(iconName) : null;
+// A set icon joins the page's sprite when the shell keeps one (see
+// icon-sprite.ts): the paths render once, in the sprite, and this use is a
+// <use> reference. Without a sprite the icon inlines its paths as before.
+const sprite = resolvedIcon ? iconSpriteFor(Astro.locals) : undefined;
+const symbolId =
+  sprite && resolvedIcon
+    ? registerIconSymbol(sprite, resolvedIcon.name, {
+        body: resolvedIcon.body,
+        viewBox: resolvedIcon.viewBox,
+      })
+    : null;
 const resolvedClass = astroClass ?? className;
 const customStyle = `display:inline-flex;width:${size}px;height:${size}px;${
   color ? `color:${color}` : ""
@@ -68,6 +80,18 @@ const style = color ? `color:${color}` : undefined;
       src={withBase(imageSrc)}
       width={size}
     />
+  ) : symbolId ? (
+    <svg
+      aria-hidden={label ? undefined : "true"}
+      aria-label={label}
+      class={resolvedClass}
+      height={size}
+      role={label ? "img" : undefined}
+      style={style}
+      width={size}
+    >
+      <use href={`#${symbolId}`} />
+    </svg>
   ) : (
     resolvedIcon && (
     <svg

package/src/components/icon-sprite-middleware.ts

@@ -0,0 +1,41 @@
+import type { MiddlewareHandler } from "astro";
+
+import { iconSpriteFor, renderIconSprite } from "./icon-sprite.ts";
+import type { IconSprite } from "./icon-sprite.ts";
+
+/**
+ * The placeholder a shell renders where its icon sprite goes (the end of the
+ * body); {@link onRequest} replaces it once the page has fully rendered.
+ * Rendering the sprite from a component instead wouldn't work: Astro walks a
+ * template's own markup before its nested components render, so a sprite
+ * component at the end of the body runs before the header's search button or
+ * the page content's callouts have registered their icons.
+ */
+export const ICON_SPRITE_SLOT = "<!--blume-icon-sprite-->";
+
+/** The page HTML with its placeholder replaced by the finished sprite. */
+export const spliceIconSprite = (html: string, sprite?: IconSprite): string =>
+  html.includes(ICON_SPRITE_SLOT)
+    ? html.replace(ICON_SPRITE_SLOT, sprite ? renderIconSprite(sprite) : "")
+    : html;
+
+/**
+ * Blume's icon-sprite middleware (wired by the integration). Draining the
+ * response renders the whole page, after which the request's registry holds
+ * every icon it used; the sprite is spliced in where the shell left the slot.
+ * Requests whose shell kept no registry — a user layout override, a partial,
+ * an endpoint — pass through untouched, streaming and all.
+ */
+export const onRequest: MiddlewareHandler = async (context, render) => {
+  const response = await render();
+  const sprite = iconSpriteFor(context.locals);
+  if (!sprite) {
+    return response;
+  }
+  const html = await response.text();
+  return new Response(spliceIconSprite(html, sprite), {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+};

package/src/components/icon-sprite.ts

@@ -0,0 +1,93 @@
+/**
+ * A per-page SVG sprite for the icon sets. A page renders the same handful of
+ * icons many times over (every sidebar chevron, every code-block language
+ * icon, the page-action buttons); inlining each one repeats its paths on every
+ * use, which on a docs page is ~20 kB of the ~60 kB that isn't the sidebar.
+ * With the sprite, each use is a `<use href="#…">` reference and the paths
+ * appear once, in a hidden `<svg>` the layout renders at the end of the body.
+ *
+ * The registry lives on the request's `Astro.locals`, so every component in
+ * one page render — the layout, the MDX content, cached sidebar subtrees —
+ * shares it, and concurrent page renders never see each other's icons. A
+ * shell that creates no registry (a user's layout override, a partial) gets
+ * inline icons, exactly as before.
+ */
+
+/** One symbol in the sprite: an icon set's inner markup and its viewBox. */
+export interface IconSymbol {
+  body: string;
+  viewBox: string;
+}
+
+export interface IconSprite {
+  /** Symbol id → symbol, in first-use order. */
+  symbols: Map<string, IconSymbol>;
+}
+
+/** The request locals (`Astro.locals`) slot the registry lives in. */
+export interface IconSpriteLocals {
+  blumeIconSprite?: IconSprite;
+}
+
+/** The request's sprite registry, when a shell created one. */
+export const iconSpriteFor = (
+  locals: IconSpriteLocals
+): IconSprite | undefined => locals.blumeIconSprite;
+
+/**
+ * The request's sprite registry, created on first call: a shell calls this
+ * up front. Idempotent, so a shell rendered inside another shell's request
+ * joins the existing registry instead of discarding its icons.
+ */
+export const createIconSprite = (locals: IconSpriteLocals): IconSprite => {
+  locals.blumeIconSprite ??= { symbols: new Map() };
+  return locals.blumeIconSprite;
+};
+
+/**
+ * The sprite symbol id for an icon name. Names come from config and content
+ * (`lucide:arrow-right`, `simple-icons:github`), so anything outside the id
+ * charset is folded to a dash.
+ */
+export const iconSymbolId = (name: string): string =>
+  `blume-i-${name.toLowerCase().replaceAll(/[^a-z0-9-]+/gu, "-")}`;
+
+/** Register a symbol (idempotent) and return its id. */
+export const registerIconSymbol = (
+  sprite: IconSprite,
+  name: string,
+  symbol: IconSymbol
+): string => {
+  const id = iconSymbolId(name);
+  if (!sprite.symbols.has(id)) {
+    sprite.symbols.set(id, symbol);
+  }
+  return id;
+};
+
+/** The ids of every sprite symbol a rendered HTML fragment references. */
+export const referencedIconSymbols = (html: string): string[] => [
+  ...new Set(
+    [...html.matchAll(/href="#(?<id>blume-i-[^"]+)"/gu)].map(
+      (match) => match.groups?.id ?? ""
+    )
+  ),
+];
+
+/**
+ * The hidden sprite `<svg>` holding every registered symbol, or an empty
+ * string when the page used no set icon. Symbol bodies are the icon sets'
+ * own markup (already SVG); the viewBox is the only attribute interpolated.
+ */
+export const renderIconSprite = (sprite: IconSprite): string => {
+  if (sprite.symbols.size === 0) {
+    return "";
+  }
+  const symbols = [...sprite.symbols]
+    .map(
+      ([id, symbol]) =>
+        `<symbol id="${id}" viewBox="${symbol.viewBox}">${symbol.body}</symbol>`
+    )
+    .join("");
+  return `<svg aria-hidden="true" hidden xmlns="http://www.w3.org/2000/svg">${symbols}</svg>`;
+};

package/src/components/layout/IconSprite.astro

@@ -0,0 +1,11 @@
+---
+// Where the page's icon sprite goes: every set icon the render registered
+// (see icon-sprite.ts), as one hidden <svg> of <symbol>s the icons' <use>
+// references resolve against. This only leaves a placeholder at the end of
+// the body; the icon-sprite middleware replaces it once the page has fully
+// rendered, since a component here would run before nested components
+// (the header's search button, the content's callouts) register their icons.
+import { ICON_SPRITE_SLOT } from "../icon-sprite-middleware.ts";
+---
+
+<Fragment set:html={ICON_SPRITE_SLOT} />