blume 1.6.5 → 1.7.0

package/src/astro/templates.ts

@@ -14,12 +14,13 @@ 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";
 import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
-import type { BlumePageRoute } from "./integration.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";
@@ -125,30 +126,36 @@ const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
  * 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`. An explicit in-memory
- * driver keeps the binding out. Swap for Astro's session opt-out once
- * withastro/astro#16871 ships in the supported range.
+ * 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: { driver: sessionDrivers.memory() },"
+    ? "\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;
-  hasSession: boolean;
-}): string => {
+const astroConfigImportLine = (options: { hasFonts: boolean }): string => {
   const names = ["defineConfig"];
   if (options.hasFonts) {
     names.push("fontProviders");
   }
-  if (options.hasSession) {
-    names.push("sessionDrivers");
-  }
   return `import { ${names.join(", ")} } from "astro/config";`;
 };
 
@@ -395,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}`,
@@ -410,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,
@@ -458,6 +485,33 @@ const renderRuntimeModuleWiring = (
   return { aliasLines, imports: [], pluginEntry: "" };
 };
 
+/**
+ * The options baked into the generated config's `blumeIntegration(...)` call.
+ * The hidden runtime gets the content routes and homepage `Link` header from
+ * the CLI in memory (`publishDevNegotiation`, republished on every
+ * regeneration), so a content-route change never rewrites the config — Astro
+ * restarts the dev server in place on a config change — and its scanned
+ * project from `blume build` for the deploy artifacts. An ejected project has
+ * no CLI, so the negotiation inputs are baked in and `astro:build:done` scans
+ * the project root (the Astro root, after eject) for the artifacts.
+ */
+const blumeIntegrationOptions = (options: {
+  config: ResolvedConfig;
+  contentRoutes: string[];
+  ejected: boolean;
+  pages: BlumePageRoute[];
+}): BlumeIntegrationOptions =>
+  options.ejected
+    ? {
+        buildArtifactsRoot: ".",
+        contentRoutes: options.contentRoutes,
+        homeLinkHeader:
+          buildHomeLinkHeader(options.config, options.contentRoutes) ??
+          undefined,
+        pages: options.pages,
+      }
+    : { pages: options.pages };
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -473,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):
@@ -507,6 +565,8 @@ export const astroConfigTemplate = (options: {
     contentRoutes,
     examplesPath,
     examplesThemePath,
+    features = ALL_CLIENT_FEATURES,
+    featuresPath,
     generatedModulesDir,
     needsSvelte,
     needsVue,
@@ -528,6 +588,7 @@ export const astroConfigTemplate = (options: {
   const { optimizeDepsEntries, optimizeDepsInclude } = resolveOptimizeDeps({
     aliases: options.aliases,
     context,
+    features,
     needsReact,
     reactCompilerPath: options.reactCompilerPath,
   });
@@ -567,7 +628,9 @@ export const astroConfigTemplate = (options: {
     : "";
   const imageOption = renderImageOption(config);
 
-  // Astro's native i18n gives locale-aware helpers + `<html lang>` correctness.
+  // Astro's native i18n resolves `Astro.currentLocale` from the URL, which the
+  // document shells fall back to for `<html lang>`/`dir` on pages the content
+  // catch-all doesn't drive (custom pages, the 404, the reference shell).
   // Blume owns getStaticPaths and materializes fallback routes in the manifest,
   // so we deliberately omit Astro's `fallback` to keep one source of routing.
   const i18nOption = config.i18n
@@ -643,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)} }`
         )
@@ -653,7 +714,6 @@ export const astroConfigTemplate = (options: {
     : "";
   const defineConfigImport = astroConfigImportLine({
     hasFonts: fontEntries.length > 0,
-    hasSession: sessionOption.length > 0,
   });
 
   // Framework renderers are only wired in when an island (or Ask AI, for React)
@@ -710,12 +770,14 @@ export const astroConfigTemplate = (options: {
   // up dev-server `Accept: text/markdown` negotiation over the content routes,
   // plus the homepage agent-discovery `Link` header.
   integrations.push(
-    `blumeIntegration(${JSON.stringify({
-      base: deployment.base,
-      contentRoutes,
-      homeLinkHeader: buildHomeLinkHeader(config, contentRoutes) ?? undefined,
-      pages,
-    })})`
+    `blumeIntegration(${JSON.stringify(
+      blumeIntegrationOptions({
+        config,
+        contentRoutes,
+        ejected: generatedModulesDir !== undefined,
+        pages,
+      })
+    )})`
   );
 
   const {
@@ -726,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";
@@ -758,11 +821,25 @@ ${userConfigSetup}export default defineConfig({
     },
   },
   devToolbar: { enabled: false },
+  // One canonical URL per page: canonicals, the sitemap, and hreflang all use
+  // the slashless form, so the slashed spelling is not a second address. Astro
+  // applies this itself — its dev server answers a slashed URL with a 404 that
+  // names the setting, an on-demand route redirects — and the Vercel adapter
+  // turns it into the platform's 308 route, so the Build Output config needs
+  // no hand-spliced redirect (see deploy/vercel-negotiation.ts). Static hosts
+  // serve the \`index.html\` directory layout as they always did.
+  trailingSlash: "never",
   // The layouts render Astro's <ClientRouter />, and its in-place swaps read
   // from the prefetch cache — fetching every link on hover/viewport hides the
   // 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`
@@ -815,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}
       },
@@ -924,6 +1002,7 @@ const staged = defineCollection({
     base: ${JSON.stringify(astroGlobBase(stagedBase))},
     generateId: ({ entry }) => entry,
   }),
+  schema: pageCollectionSchema,
 });
 `
     : "";
@@ -932,16 +1011,22 @@ const staged = defineCollection({
 import { defineCollection } from "astro:content";
 import { glob } from "astro/loaders";
 import { withIncludeRefresh } from "blume/astro";
+import { pageCollectionSchema } from "blume/core/schema.ts";
 
 // withIncludeRefresh keeps <include>-bearing pages fresh: plain .md entries
 // are rendered at sync time and digest-cached on the page file alone, so a
 // partial edit (or a warm-cache rebuild after one) would serve stale HTML.
+//
+// pageCollectionSchema is the scan's page front-matter schema, so entry.data
+// is typed and normalized the same way; it passes custom keys through and
+// falls back to defaults for a page the scan already dropped as invalid.
 const docs = defineCollection({
   loader: withIncludeRefresh(glob({
     pattern: ${JSON.stringify(docsPattern)},
     base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
   }), ${JSON.stringify(`${context.outDir}/src/generated/includes.json`)}),
+  schema: pageCollectionSchema,
 });
 ${stagedBlock}
 export const collections = { docs${options.staged ? ", staged" : ""} };
@@ -980,26 +1065,38 @@ export const askEndpointTemplate = (
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
+  // Secrets go through Astro's `getSecret` rather than `process.env`, so each
+  // adapter supplies them its own way (Cloudflare from the Worker's bindings,
+  // Node and Vercel from the environment).
   const imports = [
     'import type { APIRoute } from "astro";',
-    'import { streamText } from "ai";',
+    '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";',
   ];
   let setup = "";
   let modelExpr = JSON.stringify(backend.model);
-  if (backend.kind === "openrouter") {
+  if (backend.kind === "gateway") {
+    setup = `\nconst gateway = createGateway({ apiKey: getSecret("AI_GATEWAY_API_KEY") });\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: process.env[${JSON.stringify(
+    setup = `\nconst openrouter = createOpenRouter({ apiKey: getSecret(${JSON.stringify(
       backend.apiKeyEnv
-    )}] });\n`;
+    )}) });\n`;
     modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openai-compatible") {
     imports.push(
       'import { createOpenAICompatible } from "@ai-sdk/openai-compatible";'
     );
     setup = `\nconst provider = createOpenAICompatible({
-  apiKey: process.env[${JSON.stringify(backend.apiKeyEnv)}],
+  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
   baseURL: ${JSON.stringify(backend.baseUrl)},
   name: ${JSON.stringify(backend.name)},
 });\n`;
@@ -1062,13 +1159,13 @@ export const askEndpointTemplate = (
   const keyCheck =
     backend.kind === "gateway"
       ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
-  if (!(process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_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 (!process.env[${JSON.stringify(backend.apiKeyEnv)}]) {
+      : `  if (!getSecret(${JSON.stringify(backend.apiKeyEnv)})) {
     return new Response(
       ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
       { status: 500 }
@@ -1176,8 +1273,9 @@ const searchClientImport = (module: string): string =>
   `import { createSearch as create } from "blume/components/layout/search/${module}.ts";\n`;
 
 // Joins a base-relative path onto BASE_URL, which arrives with or without a
-// trailing slash (Astro's default trailingSlash: "ignore" passes `/docs`
-// through bare — naive concatenation would yield `/docsblume-search.json`).
+// trailing slash (Astro normalizes `base` by `trailingSlash`, which the
+// generated config pins to "never" but an owned config may set either way —
+// naive concatenation of a bare `/docs` would yield `/docsblume-search.json`).
 const SEARCH_BASE_IMPORT =
   'import { joinBase } from "blume/components/islands/base-path.ts";\n';
 
@@ -1237,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`
@@ -1291,11 +1417,12 @@ export const createSearch = () => create({ url });
 export const mixedbreadSearchEndpointTemplate = (storeId: string): string =>
   `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
+import { getSecret } from "astro:env/server";
 import Mixedbread from "@mixedbread/sdk";
 
 export const prerender = false;
 
-const client = new Mixedbread({ apiKey: process.env.MIXEDBREAD_API_KEY ?? "" });
+const client = new Mixedbread({ apiKey: getSecret("MIXEDBREAD_API_KEY") ?? "" });
 const STORE_ID = ${JSON.stringify(storeId)};
 
 export const POST: APIRoute = async ({ request }) => {
@@ -1557,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[];
     /**
@@ -1573,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;
@@ -1593,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.
@@ -1652,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,
@@ -1735,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 => {
@@ -1883,9 +2091,9 @@ const headings =
   tocHidden.size > 0
     ? allHeadings.filter((heading) => !tocHidden.has(heading.slug))
     : allHeadings;
-const frontmatter = entry.data ?? {};
+const frontmatter = entry.data;
 
-const seo = frontmatter.seo ?? {};
+const seo = frontmatter.seo;
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 
 // Percent-encode the route-derived path (the sitemap convention): a Unicode
@@ -2113,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}
@@ -3037,71 +3250,6 @@ const Example = entry.Component;
 </html>
 `;
 
-/** Generate `.blume/src/env.d.ts`. */
-export const envTemplate =
-  (): string => `/// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
-
-declare module "blume:ask" {
-  const Ask: typeof import("blume/components/islands/AskAI.astro").default;
-  export default Ask;
-}
-
-declare module "blume:data" {
-  const data: import("blume").BlumeData;
-  export default data;
-}
-
-declare module "blume:ask-data" {
-  const askData: import("blume/ai/ask-context.ts").AskData;
-  export default askData;
-}
-
-declare module "blume:content-assets" {
-  const assets: Record<string, string>;
-  export default assets;
-}
-
-declare module "blume:mcp-data" {
-  const data: import("blume/ai/mcp/data.ts").McpData;
-  export default data;
-}
-
-declare module "blume:raw-markdown" {
-  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
-  export default raw;
-}
-
-declare module "blume:rss" {
-  const feeds: Record<string, string>;
-  export default feeds;
-}
-
-declare module "blume:search-index" {
-  const documents: import("blume/search/documents.ts").SearchDocument[];
-  export default documents;
-}
-
-declare module "blume:examples" {
-  type Examples = typeof import("./generated/examples.ts").examples;
-  export const examples: Record<string, Examples[keyof Examples]>;
-  export const examplesBase: string;
-}
-
-declare module "blume:examples-theme";
-
-declare module "blume:openapi" {
-  const specs: import("blume/openapi/model.ts").OpenApiData;
-  export default specs;
-}
-
-declare module "blume:search-client" {
-  export const createSearch: () =>
-    | import("blume/components/layout/search/types.ts").SearchFn
-    | Promise<import("blume/components/layout/search/types.ts").SearchFn>;
-}
-`;
-
 /** Generate `.blume/package.json`. */
 export const runtimePackageTemplate = (dependencies: string[] = []): string =>
   `${JSON.stringify(

package/src/audit/image-size.ts

@@ -1,11 +1,13 @@
-import { imageSize as measureImage } from "image-size";
+import sharp from "sharp";
 
 /**
- * Pixel dimensions read from an image header via the image-size package,
- * which covers the formats a modern pipeline actually emits — WebP and AVIF
- * included, where the previous hand parser (PNG/JPEG/GIF only) went silent
- * and the dimension checks never ran. An unrecognized or truncated buffer
- * yields null and its checks simply don't run.
+ * Pixel dimensions read from an image header via sharp, which is already the
+ * build's image optimizer and so covers every format the pipeline can emit —
+ * WebP and AVIF included. libvips reads only the header and rejects malformed
+ * input with an error rather than looping on it, which is why the previous
+ * pure-JS parser was retired: it could be driven into an infinite loop by a
+ * crafted ICNS, HEIF, or JXL file and hang the build. An unrecognized or
+ * truncated buffer yields null and its checks simply don't run.
  */
 export interface ImageSize {
   width: number;
@@ -13,9 +15,9 @@ export interface ImageSize {
 }
 
 /** The image's pixel dimensions, or null when the format isn't recognized. */
-export const imageSize = (bytes: Buffer): ImageSize | null => {
+export const imageSize = async (bytes: Buffer): Promise<ImageSize | null> => {
   try {
-    const { width, height } = measureImage(bytes);
+    const { width, height } = await sharp(bytes).metadata();
     return width > 0 && height > 0 ? { height, width } : null;
   } catch {
     return null;