blume 2.0.1 → 2.0.3

package/src/astro/templates.ts

@@ -14,14 +14,17 @@ import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { deployPassthrough } from "../deploy/adapters/types.ts";
-import { SVG_ASSET_POLICY } from "../deploy/headers.ts";
+import { SVG_ASSET_HEADERS } from "../deploy/headers.ts";
 import { deployPlatform } from "../deploy/platforms/index.ts";
 import { adapterRoot, distDir } from "../deploy/platforms/paths.ts";
 import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import type { OgCache } from "../og/cache.ts";
-import type { OgFont, OgFontFamilies } from "../og/card.ts";
+import type { OgFont, OgFontFamilies, OgGoogleFont } from "../og/card.ts";
 import type { MixedbreadOptions } from "../search/adapters/mixedbread.ts";
-import type { ResolvedSearchAdapter } from "../search/adapters/registry.ts";
+import type {
+  ResolvedSearchAdapter,
+  SearchAdapterKind,
+} from "../search/adapters/registry.ts";
 import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import { importSpecifier, wrapperPropsType } from "./component-slots.ts";
 import type { ExampleSpec } from "./examples.ts";
@@ -398,14 +401,32 @@ export interface ClientFeatures {
 /** Every feature on: what a checkout that predates the detection shipped. */
 const ALL_CLIENT_FEATURES: ClientFeatures = { epub: true, mermaid: true };
 
+/**
+ * The npm module each browser-queried search adapter's client imports (see
+ * `components/layout/search/`). The `<Search>` dialog lazy-imports that client
+ * on first open, after the dev dep optimizer's startup run, so the first
+ * search of a fresh `blume dev` session discovered the library, re-ran the
+ * optimizer, and reloaded the page. Pagefind loads its script from the build
+ * output and Mixedbread queries through the server, so neither has one.
+ */
+const SEARCH_CLIENT_DEPS: Partial<Record<SearchAdapterKind, string>> = {
+  algolia: "algoliasearch/lite",
+  flexsearch: "flexsearch",
+  orama: "@orama/orama",
+  "orama-cloud": "@oramacloud/client",
+  typesense: "typesense",
+};
+
 const resolveOptimizeDeps = (options: {
   aliases: Record<string, string> | undefined;
   context: ProjectContext;
   features: ClientFeatures;
   needsReact: boolean;
   reactCompilerPath: string | null | undefined;
+  searchKind: SearchAdapterKind;
 }): OptimizeDepsConfig => {
   const { context, features } = options;
+  const searchDep = SEARCH_CLIENT_DEPS[options.searchKind];
   const optimizeDepsEntries = [
     ...(context.pagesRoot ? [`${context.pagesRoot}/**/*.astro`] : []),
     `${context.root}/islands/**/*.{jsx,svelte,tsx,vue}`,
@@ -418,6 +439,8 @@ const resolveOptimizeDeps = (options: {
     // Mermaid costs the dev server seconds at startup for nothing otherwise.
     ...(features.mermaid ? ["blume > mermaid"] : []),
     ...(features.epub ? ["blume > epub-gen-memory/bundle"] : []),
+    // Only the configured search adapter's client library.
+    ...(searchDep ? [`blume > ${searchDep}`] : []),
     // 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,
@@ -538,7 +561,7 @@ const blumeIntegrationOptions = (options: {
         buildArtifactsRoot: ".",
         contentRoutes: options.contentRoutes,
         homeLinkHeader:
-          buildHomeLinkHeader(options.config, options.contentRoutes) ??
+          buildHomeLinkHeader(options.config, options.contentRoutes, "dev") ??
           undefined,
         pages: options.pages,
       }
@@ -623,6 +646,7 @@ export const astroConfigTemplate = (options: {
     features,
     needsReact,
     reactCompilerPath: options.reactCompilerPath,
+    searchKind: config.search.provider.kind,
   });
 
   const {
@@ -660,7 +684,8 @@ export const astroConfigTemplate = (options: {
   const basedRedirects = applyBaseToAstroRedirects(
     config.redirects,
     config.basePath,
-    deployment.options.base ?? ""
+    deployment.options.base ?? "",
+    new Set(contentRoutes)
   );
   const redirectsOption =
     basedRedirects.length > 0
@@ -892,6 +917,10 @@ ${userConfigSetup}export default defineConfig({
     // \`/bundle\` subpath that is actually imported: optimizing the package
     // root leaves that entry out. Production (Rollup) already handles the
     // interop, so all of this only affects dev.
+    //
+    // The search adapter's client library rides the list for the same reason
+    // as the compiler runtime: the search dialog lazy-imports it on first
+    // open, and discovering it then re-optimizes and reloads the page.
     optimizeDeps: {
       entries: ${JSON.stringify(optimizeDepsEntries)},
       include: ${JSON.stringify(optimizeDepsInclude)},
@@ -1246,9 +1275,15 @@ export const askEndpointTemplate = (
     "messages",
     ...backend.template.fields,
   ];
+  // The request's signal aborts when the reader closes the panel mid-answer
+  // (the client drops the connection): passing it on stops the model call,
+  // which otherwise kept generating, and billing, to completion into a closed
+  // connection. `streamText` ends an aborted call through its abort path, not
+  // `onError`, so the reader leaving is never logged as a provider error.
   const call = `    const result = streamText({
       ${streamFields.join(",\n      ")},
 ${onError}
+      abortSignal: request.signal,
     });`;
   const stream = grounded
     ? `    const instructions =
@@ -1377,7 +1412,10 @@ export const createSearch = () => create(${JSON.stringify(provider.options)});
  * 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.
+ * turns the loader on. The EPUB module is named — even in a type — only when
+ * `export.epub` is on: an ejected app depends on `epub-gen-memory` only then,
+ * and a type import of a package it can't resolve fails its type check under
+ * a strict linker such as pnpm.
  */
 export const featuresTemplate = (features: ClientFeatures): string =>
   `// Generated by Blume. Do not edit.
@@ -1394,9 +1432,13 @@ export const loadMermaid: (() => Promise<unknown>) | null = ${
   };
 
 /** The EPUB generator's browser bundle; null when export.epub is off. */
-export const loadEpub:
+${
+  features.epub
+    ? `export const loadEpub:
   | (() => Promise<typeof import("epub-gen-memory/bundle")>)
-  | null = ${features.epub ? '() => import("epub-gen-memory/bundle")' : "null"};
+  | null = () => import("epub-gen-memory/bundle");`
+    : "export const loadEpub: (() => Promise<unknown>) | null = null;"
+}
 `;
 
 /**
@@ -1561,12 +1603,13 @@ export function GET({ props }: { props: { route: string } }) {
  *     materializes under `.blume/public/blume-assets` (see
  *     `core/sources/assets.ts`). That directory is NOT Astro's `publicDir`
  *     (which points at the user project's `public/`), so without this endpoint
- *     those references 404.
+ *     those references 404. `null` for an ejected app, which copies those
+ *     files into its own `public/blume-assets` instead.
  * Prerendered: every asset becomes a static file in the build output; the dev
  * server renders on demand, so new images appear without a restart.
  */
 export const contentAssetsEndpointTemplate = (
-  stagedAssetsDir: string
+  stagedAssetsDir: string | null
 ): string =>
   `// Generated by Blume. Do not edit.
 import { existsSync } from "node:fs";
@@ -1588,18 +1631,29 @@ const TYPES: Record<string, string> = {
   ".ico": "image/x-icon",
   ".jpeg": "image/jpeg",
   ".jpg": "image/jpeg",
+  ".mov": "video/quicktime",
+  ".mp4": "video/mp4",
+  ".ogv": "video/ogg",
   ".png": "image/png",
   ".svg": "image/svg+xml",
   ".tiff": "image/tiff",
+  ".webm": "video/webm",
   ".webp": "image/webp",
 };
 
+const extensionOf = (path: string): string =>
+  path.slice(path.lastIndexOf(".")).toLowerCase();
+
 const contentType = (path: string): string =>
-  TYPES[path.slice(path.lastIndexOf(".")).toLowerCase()] ??
-  "application/octet-stream";
+  TYPES[extensionOf(path)] ?? "application/octet-stream";
+
+// A source downloads only images and videos; anything else in the staged
+// directory (a page an older build saved under its URL's extension) is never
+// published from the docs origin.
+const isMedia = (path: string): boolean => Object.hasOwn(TYPES, extensionOf(path));
 
 const stagedParams = async (): Promise<string[]> => {
-  if (!existsSync(STAGED_DIR)) {
+  if (STAGED_DIR === null || !existsSync(STAGED_DIR)) {
     return [];
   }
   const entries = await readdir(STAGED_DIR, {
@@ -1607,7 +1661,7 @@ const stagedParams = async (): Promise<string[]> => {
     withFileTypes: true,
   });
   return entries
-    .filter((entry) => entry.isFile())
+    .filter((entry) => entry.isFile() && isMedia(entry.name))
     .map((entry) =>
       relative(STAGED_DIR, join(entry.parentPath, entry.name)).replaceAll(
         "\\\\",
@@ -1628,6 +1682,9 @@ const resolveAsset = (asset: string): string | null => {
   if (asset.startsWith("content/")) {
     return files[asset.slice("content/".length)] ?? null;
   }
+  if (STAGED_DIR === null) {
+    return null;
+  }
   const abs = resolve(STAGED_DIR, asset);
   // Traversal guard: the dev server renders on demand, so the param is
   // attacker-controlled there — never step outside the staged directory.
@@ -1637,7 +1694,7 @@ const resolveAsset = (asset: string): string | null => {
   // asset — and a bare prefix also admits a sibling directory that merely
   // shares the name.
   const rel = relative(STAGED_DIR, abs);
-  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel) || !isMedia(rel)) {
     return null;
   }
   return existsSync(abs) ? abs : null;
@@ -1651,11 +1708,12 @@ export const GET: APIRoute = async ({ params }) => {
   const body = await readFile(path);
   const type = contentType(path);
   // An SVG opened directly is a document that can run script; the sandbox
-  // keeps an uploaded one inert on the docs origin. Static hosts get the same
-  // header from the build's header rules.
+  // keeps an uploaded one inert on the docs origin. This endpoint
+  // prerenders, so these headers reach dev only: a build serves the files
+  // with the same headers from its host's rules (see deploy/headers.ts).
   const headers: Record<string, string> =
     type === "image/svg+xml"
-      ? { "Content-Security-Policy": ${JSON.stringify(SVG_ASSET_POLICY)}, "Content-Type": type }
+      ? { ...${JSON.stringify(SVG_ASSET_HEADERS)}, "Content-Type": type }
       : { "Content-Type": type };
   return new Response(new Uint8Array(body), { headers });
 };
@@ -1769,7 +1827,7 @@ 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 { withMountedBase } from "blume/components/islands/base-path.ts";
 import {
   hiddenDefaultLocale,
   navGroupIds,
@@ -1808,7 +1866,7 @@ if (!(variant && node && node.kind === "group")) {
 }
 const strings =
   locale === "default" ? data.ui.nav : (data.uiByLocale[locale] ?? data.ui).nav;
-const fragmentBase = withBase(\`/blume-nav/\${version}/\${locale}\`);
+const fragmentBase = withMountedBase(\`/blume-nav/\${version}/\${locale}\`);
 ---
 
 <NavTree
@@ -1832,6 +1890,7 @@ export const ogEndpointTemplate = (
      * Absent, every card renders on every build.
      */
     cache?: OgCache;
+    fallbacks?: OgGoogleFont[];
     families?: OgFontFamilies;
     fonts?: OgFont[];
     /**
@@ -1845,7 +1904,7 @@ export const ogEndpointTemplate = (
 ): string =>
   `// Generated by Blume. Do not edit.
 import { cachedOgImage } from "blume/og";
-import type { OgCache, OgFont, OgFontFamilies } from "blume/og";
+import type { OgCache, OgFont, OgFontFamilies, OgGoogleFont } from "blume/og";
 import data from "blume:data";
 
 export const prerender = true;
@@ -1863,6 +1922,9 @@ const fonts: OgFont[] = ${JSON.stringify(og.fonts ?? [])};
 const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
+// Script fallbacks (Noto families, the configured locales' first). A card
+// fetches them only when its text has a glyph Takumi's built-in font lacks.
+const fallbacks: OgGoogleFont[] = ${JSON.stringify(og.fallbacks ?? [])};
 
 // Rendered cards are kept on disk between builds, keyed by everything that
 // decides their pixels, so a rebuild renders only the cards whose title,
@@ -1935,6 +1997,7 @@ export async function GET({ props }: { props: CardProps }) {
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
     description: props.description ?? data.config.og.description,
+    fallbacks,
     families,
     fonts,
     logo: data.config.og.logo,
@@ -2130,8 +2193,8 @@ export const catchAllPageTemplate = (options: {
 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 { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
+import { mountBasePath, stripBasePath } from "blume/core/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${componentImports}
 import data from "blume:data";
@@ -2196,12 +2259,16 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const ogPath = data.config.og.enabled
   ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
-const ogRel = seo.image ?? ogPath;
 // Absolute URLs also carry the deployment base (the page is served under it):
 // \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
-// an external URL, which passes through verbatim (mirrors PageLayout).
-const ogImage =
-  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
+// an external URL, which passes through verbatim (mirrors PageLayout). An
+// authored \`seo.image\` keeps a base written by hand; the generated card is
+// always mounted under it.
+const absoluteOg = (path: string, based: (path: string) => string) =>
+  base && path.startsWith("/") ? \`\${base}\${based(path)}\` : path;
+const ogImage = seo.image
+  ? absoluteOg(seo.image, withBase)
+  : ogPath && absoluteOg(ogPath, withMountedBase);
 // Blume's generated card has known dimensions the layout can declare; a user's
 // \`seo.image\` could be any size or format, so it gets none.
 const ogGenerated = !seo.image && Boolean(ogPath);
@@ -2210,7 +2277,7 @@ const ogGenerated = !seo.image && Boolean(ogPath);
 // itself (a guest post crediting its own author) over the configured default.
 const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
-const basedRoute = withBase(route);
+const basedRoute = withMountedBase(route);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -2258,7 +2325,7 @@ const contentDir = i18n
   : "ltr";
 // The root route keeps its trailing slash (\`https://site/\`) so canonical and
 // hreflang URLs byte-match the sitemap's <loc> for the home page.
-const absolute = (path: string) => base + withBase(path);
+const absolute = (path: string) => base + withMountedBase(path);
 
 // A fallback page renders the fallback locale's page at this locale's URL, so
 // its canonical names the page it copies, and search engines never rank the
@@ -2303,7 +2370,7 @@ const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 // carries sits *after* the base (\`/docs/ja/guide\`), while \`localePrefix\` is
 // base-less (\`/ja\`). Stripping and re-adding a locale therefore happen in
 // base-less space, with the base re-applied at the end — the same
-// \`withBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
+// \`mountBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
 // build every real route. Done in based space, \`stripLocale\` matches nothing
 // and \`localizeRoute\` prepends a second prefix (\`/ja/docs/ja/guide\`). Only a
 // switcher entry for a locale with no real translation reaches this fallback:
@@ -2311,7 +2378,7 @@ const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 // generated reference (which has no \`alternates\` at all) for every locale
 // but its own.
 const mountLocalized = (logical: string, codeArg: string) =>
-  withBasePath(data.config.basePath, localizeRoute(logical, codeArg));
+  mountBasePath(data.config.basePath, localizeRoute(logical, codeArg));
 const logicalRoute = i18n
   ? stripLocale(stripBasePath(data.config.basePath, route), locale)
   : route;
@@ -2340,7 +2407,7 @@ const versionRootFor = (id: string) => {
   const logical = id ? \`/\${id}\` : "/";
   return i18n
     ? mountLocalized(logical, locale)
-    : withBasePath(data.config.basePath, logical);
+    : mountBasePath(data.config.basePath, logical);
 };
 const samePageSwitch = versionsConfig
   ? versionsConfig.switcher.redirect === "same-page"
@@ -2440,7 +2507,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   exportEpub={${options.exportEpub}}${
     options.navFragments
       ? `
-  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
+  navFragmentBase={withMountedBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
       : ""
   }
   openInChat={data.config.openInChat}
@@ -2493,7 +2560,7 @@ export const changelogIndexTemplate = (options: {
 // Generated by Blume. Do not edit.
 import { getCollection } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } 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";
@@ -2592,7 +2659,7 @@ const items = changelogEntries.map((entry) => {
   return {
     date: date ? formatRowDate(date) : null,
     dateTime: date ? date.toISOString().slice(0, 10) : null,
-    href: route ? withBase(route) : null,
+    href: route ? withMountedBase(route) : null,
     id: slugify(label),
     label,
     tag: entry.data.changelog?.category ?? null,
@@ -2628,14 +2695,14 @@ for (const item of items) {
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 // The canonical URL carries the deployment base (the page is served under it),
-// matching how the catch-all canonicalizes via \`withBase(route)\`.
-const basedRoute = withBase("/changelog");
+// matching how the catch-all canonicalizes via \`withMountedBase(route)\`.
+const basedRoute = withMountedBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
 // The generated OG card for this route (the /og endpoint emits it alongside
 // the content-route cards), absolutized like the catch-all's so crawlers get
 // a full URL when the site is known.
-const ogPath = data.config.og.enabled ? withBase("/og/changelog.png") : null;
+const ogPath = data.config.og.enabled ? withMountedBase("/og/changelog.png") : null;
 const ogImage = ogPath && base ? base + ogPath : ogPath;
 
 // The page chrome (h1, title, description) comes from the translatable
@@ -2757,7 +2824,8 @@ export const notFoundPageTemplate = (): string => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
 import Icon from "blume/components/Icon.astro";
 import PageLayout from "blume/components/layout/PageLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
+import { mountBasePath } from "blume/core/base-path.ts";
 import data from "blume:data";
 
 export const prerender = true;
@@ -2781,22 +2849,27 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 // their resolved target when the section has no index page of its own.
 const suggestions = [
   ...data.navigation.tabs.map((tab) => ({
-    href: withBase(tab.href ?? tab.path),
+    href: withMountedBase(tab.href ?? tab.path),
     label: tab.label,
   })),
   ...(data.config.discovery.sitemap
-    ? [{ href: withBase("/sitemap.xml"), label: nf.sitemap }]
+    ? [{ href: withMountedBase("/sitemap.xml"), label: nf.sitemap }]
     : []),
   ...(data.config.discovery.llmsTxt
-    ? [{ href: withBase("/llms.txt"), label: nf.llms }]
+    ? [{ href: withMountedBase("/llms.txt"), label: nf.llms }]
     : []),
 ];
 
 // Every host serves this one page for any missing URL, so a reader who
 // mistyped \`/ar/…\` would get the default locale's message. The other locales'
 // copy rides along, and the script below swaps it in when the URL's first
-// segment names one of them — the message, its language and direction, the
-// tab title, and the home link (to that locale's root).
+// segment past the site's base names one of them — the message, its language
+// and direction, the tab title, and the home link (to that locale's root).
+// Localized routes sit under both bases (\`{deployment.base}/{basePath}/ar/…\`),
+// so the script strips the two together, trailing slash included.
+const { basePath } = data.config;
+const siteRoot = withMountedBase(mountBasePath(basePath, "/"));
+const localeBase = siteRoot.endsWith("/") ? siteRoot : siteRoot + "/";
 const localized = Object.fromEntries(
   (i18n?.locales ?? [])
     .filter((l) => l.code !== i18n?.defaultLocale && data.uiByLocale[l.code])
@@ -2808,7 +2881,7 @@ const localized = Object.fromEntries(
           description: strings.description,
           dir: l.dir ?? "ltr",
           home: strings.home,
-          homeHref: withBase("/" + l.code),
+          homeHref: withMountedBase(mountBasePath(basePath, "/" + l.code)),
           suggestions: strings.suggestions,
           title: strings.title,
         },
@@ -2837,7 +2910,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
 >
   <div
     class="mx-auto grid w-full max-w-5xl gap-12 px-6 py-20 sm:py-28 md:grid-cols-[3fr_2fr] md:gap-16 lg:gap-24 lg:py-36"
-    data-base={withBase("/")}
+    data-base={localeBase}
     data-blume-not-found
   >
     <div class="flex flex-col items-start">
@@ -2858,7 +2931,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
       <a
         class="mt-8 inline-flex items-center gap-1.5 rounded-full bg-accent py-2 pe-4 ps-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90"
         data-nf-home
-        href={withBase("/")}
+        href={withMountedBase("/")}
       >
         <Icon class="rtl:-scale-x-100" name="arrow-left" size={14} />
         <span data-nf="home">{nf.home}</span>
@@ -2940,7 +3013,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
  */
 export const notFoundMarkdownTemplate =
   (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
 import { absoluteUrl } from "blume/core/site-url.ts";
 import data from "blume:data";
 
@@ -2951,7 +3024,7 @@ const nf = data.ui.notFound;
 // Absolute for internal routes when the site is known; an external tab href
 // passes through untouched.
 const href = (path: string): string => {
-  const based = withBase(path);
+  const based = withMountedBase(path);
   return data.config.site && based.startsWith("/") && !based.startsWith("//")
     ? absoluteUrl(data.config.site, based)
     : based;
@@ -3010,7 +3083,7 @@ export function GET() {
 export const notFoundJsonTemplate =
   (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
 import { problem } from "blume/ai/api/problem.ts";
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
 import { absoluteUrl } from "blume/core/site-url.ts";
 import data from "blume:data";
 
@@ -3021,7 +3094,7 @@ const nf = data.ui.notFound;
 // Absolute for internal routes when the site is known; an external tab href
 // passes through untouched.
 const href = (path: string): string => {
-  const based = withBase(path);
+  const based = withMountedBase(path);
   return data.config.site && based.startsWith("/") && !based.startsWith("//")
     ? absoluteUrl(data.config.site, based)
     : based;
@@ -3196,7 +3269,7 @@ ${wrapperPropsType("Example")}
 /**
  * The route prefix `<Component />` preview frames are served under:
  * `{basePath}/blume-examples/<example path>`. `deployment.base` is layered on
- * top by Astro (components apply it with `withBase`).
+ * top by Astro (components apply it with `withMountedBase`).
  */
 export const examplesRouteBase = (basePath: string): string =>
   `${basePath}/blume-examples`;
@@ -3300,11 +3373,20 @@ const Example = entry.Component;
           root.dataset.theme = theme;
           root.classList.toggle("dark", theme === "dark");
         };
-        const stored = () =>
-          localStorage.getItem("blume-theme") ??
-          (matchMedia("(prefers-color-scheme: dark)").matches
-            ? "dark"
-            : "light");
+        // Blocked storage (a sandboxed or privacy-locked frame) throws on
+        // access; it falls through to the OS setting like an unset preference.
+        const stored = () => {
+          let theme = null;
+          try {
+            theme = localStorage.getItem("blume-theme");
+          } catch {}
+          return (
+            theme ??
+            (matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light")
+          );
+        };
         try {
           const host = window.parent.document.documentElement;
           apply(host.dataset.theme ?? stored());

package/src/audit/catalog.ts

@@ -583,7 +583,7 @@ export const CHECKS = [
   },
   {
     category: "sitemap",
-    fix: "Sitemaps must be valid XML in the sitemaps.org urlset format.",
+    fix: "Sitemaps must be valid XML in the sitemaps.org urlset or sitemap index format.",
     id: "BLUME_AUDIT_SITEMAP_INVALID",
     severity: "error",
     tier: "static",
@@ -684,7 +684,7 @@ export const CHECKS = [
   },
   {
     category: "ai",
-    fix: "Rebuild so llms.txt matches the site; if the page is deliberately excluded, mark it `seo.noindex` or `sidebar.hidden`.",
+    fix: "Rebuild so llms.txt matches the site; if the page is deliberately excluded, set `ai.exclude: true` in its front matter.",
     id: "BLUME_AUDIT_LLMS_TXT_PAGE_MISSING",
     severity: "warning",
     tier: "static",

package/src/audit/checks/assets.ts

@@ -11,6 +11,13 @@ import type {
 } from "../types.ts";
 import { resolveHref, siteOrigin } from "../url.ts";
 
+/**
+ * Vercel's image optimization route (`/_vercel/image?url=…&w=…`), which
+ * `imageService` on the Vercel adapter points `<img>` at. The platform
+ * serves it; the build never writes a file there.
+ */
+const VERCEL_IMAGE_ENDPOINT = "/_vercel/image";
+
 const formatBytes = (bytes: number): string =>
   bytes < 1024 * 1024
     ? `${Math.round(bytes / 1024)} kB`
@@ -44,17 +51,30 @@ const resolveAsset = (
   }
 
   const origin = siteOrigin(context.project.config.deployment.options.site);
-  const resolved = resolveHref(
-    page.url,
-    asset.src,
-    origin,
-    normalizeBasePath(context.project.config.deployment.options.base)
+  const deployBase = normalizeBasePath(
+    context.project.config.deployment.options.base
   );
+  const resolved = resolveHref(page.url, asset.src, origin, deployBase);
   // A subresource on another origin (a CDN, an analytics script) is outside the
   // build; we can't check whether it exists without the network.
   if (resolved.kind === "external" || resolved.kind === "ignored") {
     return null;
   }
+  // Vercel's image optimization endpoint answers these at request time, at the
+  // host root whatever the base.
+  if (resolved.path === VERCEL_IMAGE_ENDPOINT) {
+    return null;
+  }
+  if (resolved.kind === "outside-base") {
+    found.push(
+      finding(
+        missingId,
+        pageSite(context, page),
+        `Page references ${asset.src}, which is missing deployment.base (${deployBase}), so the deployed site does not serve it.`
+      )
+    );
+    return null;
+  }
 
   const bytes = context.files.get(resolved.path);
   if (bytes === undefined) {

package/src/audit/checks/content.ts

@@ -38,6 +38,22 @@ const frontmatterDate = (source: string): Date | null => {
   }
 };
 
+/**
+ * API reference pages (OpenAPI, AsyncAPI, GraphQL) are generated from a spec
+ * and have no front matter to edit: their title comes from the operation's
+ * summary (the spec's own title on the overview page) and their description
+ * from its description or summary. A fix naming front matter would send the
+ * reader to a file that doesn't exist.
+ */
+const isGeneratedReference = (page: PageSnapshot): boolean =>
+  page.route?.source.name === "openapi";
+
+const GENERATED_TITLE_FIX =
+  "This page is generated from an API spec, which titles it with the operation's `summary` (the spec's own title on the overview page) — rewrite it there.";
+
+const GENERATED_DESCRIPTION_FIX =
+  "This page is generated from an API spec, which describes it with the operation's `description` or `summary` (the spec's own description on the overview page) — rewrite it there.";
+
 const titleChecks = (
   context: AuditContext,
   page: PageSnapshot
@@ -74,7 +90,8 @@ const titleChecks = (
       finding(
         "BLUME_AUDIT_TITLE_LENGTH",
         pageSite(context, page, ["title"]),
-        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`
+        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`,
+        isGeneratedReference(page) ? GENERATED_TITLE_FIX : undefined
       )
     );
   }
@@ -123,7 +140,8 @@ const descriptionChecks = (
       finding(
         "BLUME_AUDIT_DESCRIPTION_LENGTH",
         pageSite(context, page, ["description"]),
-        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
+        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`,
+        isGeneratedReference(page) ? GENERATED_DESCRIPTION_FIX : undefined
       )
     );
   }