blume 1.6.6 → 1.7.1

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}
       },
@@ -1034,16 +1080,23 @@ export const askEndpointTemplate = (
   ];
   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") });\n`;
+    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
-    )}) });\n`;
+    setup = `\nconst openrouter = createOpenRouter({
+  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),${headersField}
+});\n`;
     modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openai-compatible") {
     imports.push(
@@ -1051,7 +1104,7 @@ export const askEndpointTemplate = (
     );
     setup = `\nconst provider = createOpenAICompatible({
   apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
-  baseURL: ${JSON.stringify(backend.baseUrl)},
+  baseURL: ${JSON.stringify(backend.baseUrl)},${headersField}
   name: ${JSON.stringify(backend.name)},
 });\n`;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
@@ -1289,6 +1342,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 +1691,85 @@ 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, and `default` again for the default locale
+ * while its URL prefix is hidden: Astro's i18n routing 404s a page URL that
+ * carries the default locale's code as a segment). 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 {
+  hiddenDefaultLocale,
+  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, hiddenDefaultLocale(data.config.i18n)).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, hiddenDefaultLocale(data.config.i18n)).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 +1782,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 +1802,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 +1869,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,
@@ -1784,31 +1948,22 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 </ReferenceLayout>
 `;
 
-export const catchAllPageTemplate = (options: {
-  exportEpub: boolean;
-  exportPdf: boolean;
-  mathEnabled: boolean;
-  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
-  needsReact: boolean;
-}): string => {
-  const mathImport = options.mathEnabled
+/**
+ * The component map every rendered entry body receives via
+ * `<Content components={...} />`: Blume's content components, `<Math>` when
+ * math is enabled, the island wrappers, and the user's `mdxComponents`
+ * overrides. Shared by the catch-all page and the changelog index so a
+ * `:::` directive (compiled to `<Callout>`) or an explicit `<Steps>` renders
+ * wherever an entry is rendered — an MDX body throws "Expected component
+ * `X` to be defined" the moment a page renders it without this map.
+ */
+const contentComponentsSource = (mathEnabled: boolean) => {
+  const mathImport = mathEnabled
     ? 'import Math from "blume/components/content/Math.astro";\n'
     : "";
-  const mathEntry = options.mathEnabled ? "Math,\n  " : "";
-  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
-  const clientData = options.needsReact
-    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
-    : "";
-
-  return `---
-// Generated by Blume. Do not edit.
-import { getEntry, render } from "astro:content";
-import type { CollectionKey } from "astro:content";
-import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
-import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
-import { resolveSlot } from "blume/components/layout/overrides.ts";
-import Accordion from "blume/components/content/Accordion.astro";
+  const mathEntry = mathEnabled ? "Math,\n  " : "";
+  return {
+    imports: `import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
 import AutoTypeTable from "blume/components/content/AutoTypeTable.astro";
 import Badge from "blume/components/content/Badge.astro";
@@ -1848,19 +2003,8 @@ 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";
-import data from "blume:data";
-
-const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
-const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
-
-// Docs content is file-based and always prerendered, even in server output
-// (where only endpoints like /api/ask render on demand). Without this, server
-// builds would render this route on demand and ignore getStaticPaths, leaving
-// the entry id undefined.
-export const prerender = true;
-
-const components = {
+import { islandComponents } from "../generated/islands.ts";`,
+    map: `{
   Accordion,
   AccordionItem,
   ApiOverview,
@@ -1897,8 +2041,52 @@ const components = {
   YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
+}`,
+  };
 };
 
+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 => {
+  const { imports: componentImports, map: componentMap } =
+    contentComponentsSource(options.mathEnabled);
+  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
+  const clientData = options.needsReact
+    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
+    : "";
+
+  return `---
+// Generated by Blume. Do not edit.
+import { getEntry, render } from "astro:content";
+import type { CollectionKey } from "astro:content";
+import RootLayout from "blume/components/layout/RootLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
+${componentImports}
+import data from "blume:data";
+
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
+// Docs content is file-based and always prerendered, even in server output
+// (where only endpoints like /api/ask render on demand). Without this, server
+// builds would render this route on demand and ignore getStaticPaths, leaving
+// the entry id undefined.
+export const prerender = true;
+
+const components = ${componentMap};
+
 export function getStaticPaths() {
   return data.routes.map((route) => ({
     params: { slug: route.path === "/" ? undefined : route.path.slice(1) },
@@ -2166,7 +2354,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 && localePrefix(locale) ? locale : "default"}\`)}`
+      : ""
+  }
   openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}
@@ -2195,6 +2388,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 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). */
@@ -2208,6 +2402,8 @@ 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.
@@ -2217,11 +2413,19 @@ 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";
-import { layoutOverrides } from "../generated/components.ts";
+${componentImports}
 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;
@@ -2420,7 +2624,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content />
+            <Content components={components} />
           </Update>
         ))}
         {majorGroups.slice(1).map((group) => (
@@ -2431,7 +2635,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
           >
             {group.items.map(({ Content, href, id, label, date, tags }) => (
               <Update description={date} href={href} id={id} label={label} tags={tags}>
-                <Content />
+                <Content components={components} />
               </Update>
             ))}
           </section>
@@ -2451,7 +2655,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       <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 />
+            <Content components={components} />
           </Update>
         ))}
       </div>

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/content/YouTube.astro

@@ -20,7 +20,7 @@ const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
 
 {
   src && (
-    <div class="not-prose my-6 aspect-video overflow-hidden rounded-blume border border-border bg-muted/30">
+    <div class="not-prose my-6 aspect-video w-full overflow-hidden rounded-blume border border-border bg-muted/30">
       <iframe
         allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
         allowfullscreen

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,
+  });
+};