blume 2.0.1 → 2.0.2

package/src/ai/visibility.ts

@@ -1,10 +1,44 @@
-// Mirrors the fence masking in `core/sources/assets.ts`: a fenced code sample
-// that *shows* `<Visibility>` markup must keep showing what the author wrote.
-const CODE_FENCE_BLOCK =
-  /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
+import { nextFenceState } from "../core/code-fences.ts";
+import type { FenceState } from "../core/code-fences.ts";
+
+/** An inline code span on one line, as the other source scanners read it. */
+const INLINE_CODE = /`[^`\n]*`/gu;
 // NUL delimiters cannot appear in authored markdown, so tokens never collide.
 // oxlint-disable-next-line no-control-regex -- the NUL is the collision guard.
-const FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
+const CODE_TOKEN = /\u0000blume-code-(?<index>\d+)\u0000/gu;
+
+/**
+ * Swap every code sample for a one-line token — fenced blocks at any indent
+ * (a fence inside a `<Tab>` or `<Step>` is indented under it) and inline code
+ * spans — so markup that *shows* `<Visibility>` keeps showing what the author
+ * wrote. An unclosed fence runs to the end, as CommonMark reads it.
+ */
+const maskCode = (markdown: string, stash: string[]): string => {
+  const token = (code: string): string => {
+    stash.push(code);
+    return `\u0000blume-code-${stash.length - 1}\u0000`;
+  };
+  const lines: string[] = [];
+  let fence: FenceState = null;
+  let block: string[] = [];
+  for (const line of markdown.split("\n")) {
+    const next = nextFenceState(line, fence);
+    if (fence === null && next === null) {
+      lines.push(line.replaceAll(INLINE_CODE, token));
+    } else {
+      block.push(line);
+      if (next === null) {
+        lines.push(token(block.join("\n")));
+        block = [];
+      }
+    }
+    fence = next;
+  }
+  if (block.length > 0) {
+    lines.push(token(block.join("\n")));
+  }
+  return lines.join("\n");
+};
 
 /** The audience an output surface serves — the component's two `for` values. */
 export type VisibilityAudience = "agents" | "web";
@@ -36,12 +70,9 @@ export const applyAudienceVisibility = (
   markdown: string,
   audience: VisibilityAudience
 ): string => {
-  // Mask fenced code blocks so documentation *about* Visibility survives.
-  const fences: string[] = [];
-  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
-    fences.push(block);
-    return `\u0000blume-fence-${fences.length - 1}\u0000`;
-  });
+  // Mask code so documentation *about* Visibility survives.
+  const code: string[] = [];
+  const masked = maskCode(markdown, code);
 
   let touched = false;
   const filtered = masked
@@ -56,12 +87,12 @@ export const applyAudienceVisibility = (
 
   // Removing/unwrapping block-level tags leaves runs of blank lines behind;
   // collapse them only when something matched so untouched files round-trip
-  // exactly. Fences are masked as single-line tokens, so they are unaffected.
+  // exactly. Code is masked as single-line tokens, so it is unaffected.
   const tidied = touched ? filtered.replaceAll(/\n{3,}/gu, "\n\n") : filtered;
 
   return tidied.replaceAll(
-    FENCE_TOKEN,
-    (token, index) => fences[Number(index)] ?? token
+    CODE_TOKEN,
+    (token, index) => code[Number(index)] ?? token
   );
 };
 

package/src/analytics/databuddy.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The script Databuddy's install snippet loads. */
+export const DATABUDDY_SCRIPT_SRC = "https://cdn.databuddy.cc/databuddy.js";
+
+/** The options {@link databuddy} maps itself. */
+export interface DatabuddyNamedOptions {
+  /** Client ID, from the website's settings in the Databuddy dashboard. */
+  clientId: string;
+}
+
+/**
+ * Options for {@link databuddy}: the client ID plus any other tracker setting,
+ * forwarded as a `data-` attribute on the tag (`"track-web-vitals"` →
+ * `data-track-web-vitals`, `"track-errors"`, `"track-outgoing-links"`,
+ * `"api-url"`, …).
+ */
+export type DatabuddyOptions = DatabuddyNamedOptions & {
+  [setting: string]: string;
+};
+
+export const databuddyOptionsSchema = z
+  .object({
+    clientId: z.string().min(1),
+  })
+  .catchall(z.string());
+
+export type DatabuddyAdapter = AdapterDescriptor<"databuddy", DatabuddyOptions>;
+
+export const databuddyAdapterSchema = adapterDescriptorSchema(
+  "databuddy",
+  databuddyOptionsSchema
+);
+
+/**
+ * Databuddy. The client ID is public — it's in the tag on every page.
+ */
+export const databuddy = (options: DatabuddyOptions): DatabuddyAdapter => ({
+  kind: "databuddy",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The async tag from the install instructions, with `clientId` as
+ * `data-client-id` and every other option as its own `data-` attribute. The
+ * tracker skips setup when `window.databuddy` already exists, so there is no
+ * queue stub. Databuddy's script tracks history changes on its own, so
+ * client-router navigations need no extra hook.
+ */
+export const databuddyHead = (options: DatabuddyOptions): HeadScript[] => {
+  const { clientId, ...settings } = options;
+  const attributes: HeadScript["attributes"] = {};
+  for (const [setting, value] of Object.entries(settings)) {
+    attributes[`data-${setting}`] = value;
+  }
+  attributes["data-client-id"] = clientId;
+  attributes.async = true;
+  attributes.crossorigin = "anonymous";
+  attributes.src = DATABUDDY_SCRIPT_SRC;
+  return [{ attributes, content: null }];
+};

package/src/analytics/head.ts

@@ -3,6 +3,7 @@ import { amplitudeHead } from "./amplitude.ts";
 import { clarityHead } from "./clarity.ts";
 import { clearbitHead } from "./clearbit.ts";
 import { cloudflareHead } from "./cloudflare.ts";
+import { databuddyHead } from "./databuddy.ts";
 import { fathomHead } from "./fathom.ts";
 import { googleAnalyticsHead } from "./google-analytics.ts";
 import { googleTagManagerHead } from "./google-tag-manager.ts";
@@ -64,6 +65,9 @@ const adapterScripts = (
     case "cloudflare": {
       return cloudflareHead(adapter.options);
     }
+    case "databuddy": {
+      return databuddyHead(adapter.options);
+    }
     case "fathom": {
       return fathomHead(adapter.options);
     }

package/src/analytics/index.ts

@@ -30,6 +30,8 @@ export { clearbit } from "./clearbit.ts";
 export type { ClearbitAdapter, ClearbitOptions } from "./clearbit.ts";
 export { cloudflare } from "./cloudflare.ts";
 export type { CloudflareAdapter, CloudflareOptions } from "./cloudflare.ts";
+export { databuddy } from "./databuddy.ts";
+export type { DatabuddyAdapter, DatabuddyOptions } from "./databuddy.ts";
 export { fathom } from "./fathom.ts";
 export type { FathomAdapter, FathomOptions } from "./fathom.ts";
 export { googleAnalytics } from "./google-analytics.ts";

package/src/analytics/posthog.ts

@@ -54,13 +54,30 @@ export const posthog = (options: PosthogOptions): PosthogAdapter => ({
 const POSTHOG_LOADER =
   '!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug getPageViewId captureTraceFeedback captureTraceMetric".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);';
 
-// PostHog's loader only captures a pageview per real page load, so the client
-// router's in-place swaps are captured here.
+// With PostHog's classic pageview setting its loader captures one pageview
+// per real page load, so the client router's in-place swaps are captured here.
 const POSTHOG_SPA_PAGEVIEWS = spaPageviews(
   "__blumePosthogPath",
   'posthog.capture("$pageview");'
 );
 
+/**
+ * Whether Blume should capture client-router navigations itself, given the
+ * `posthog.init` options. Only when PostHog captures load-time pageviews and
+ * nothing more: `capture_pageview: false` turns pageviews off, and
+ * `capture_pageview: "history_change"` — the default under any `defaults`
+ * snapshot (`defaults: "2025-05-24"` in PostHog's current snippet), unless
+ * `capture_pageview` says otherwise — already captures every navigation, so
+ * sending another would count each one twice.
+ */
+const capturesNavigations = (init: Record<string, JsonValue>): boolean => {
+  const setting = init.capture_pageview;
+  if (setting === undefined) {
+    return init.defaults === undefined || init.defaults === "unset";
+  }
+  return setting !== false && setting !== "history_change";
+};
+
 /**
  * The inline loader-plus-init snippet. `key` and `host` are the options Blume
  * maps (`host` becomes `api_host`); everything else lands in `posthog.init`'s
@@ -69,10 +86,11 @@ const POSTHOG_SPA_PAGEVIEWS = spaPageviews(
 export const posthogHead = (options: PosthogOptions): HeadScript[] => {
   const { host, key, ...init } = options;
   const initOptions = { api_host: host ?? POSTHOG_DEFAULT_HOST, ...init };
+  const pageviews = capturesNavigations(init) ? POSTHOG_SPA_PAGEVIEWS : "";
   return [
     {
       attributes: {},
-      content: `${POSTHOG_LOADER}posthog.init(${inlineJson(key)},${inlineJson(initOptions)});${POSTHOG_SPA_PAGEVIEWS}`,
+      content: `${POSTHOG_LOADER}posthog.init(${inlineJson(key)},${inlineJson(initOptions)});${pageviews}`,
     },
   ];
 };

package/src/analytics/schema.ts

@@ -5,6 +5,7 @@ import { amplitudeAdapterSchema } from "./amplitude.ts";
 import { clarityAdapterSchema } from "./clarity.ts";
 import { clearbitAdapterSchema } from "./clearbit.ts";
 import { cloudflareAdapterSchema } from "./cloudflare.ts";
+import { databuddyAdapterSchema } from "./databuddy.ts";
 import { fathomAdapterSchema } from "./fathom.ts";
 import { googleAnalyticsAdapterSchema } from "./google-analytics.ts";
 import { googleTagManagerAdapterSchema } from "./google-tag-manager.ts";
@@ -27,6 +28,7 @@ export const analyticsAdapterSchema = z.discriminatedUnion("kind", [
   clarityAdapterSchema,
   clearbitAdapterSchema,
   cloudflareAdapterSchema,
+  databuddyAdapterSchema,
   fathomAdapterSchema,
   googleAnalyticsAdapterSchema,
   googleTagManagerAdapterSchema,

package/src/astro/generate.ts

@@ -31,7 +31,7 @@ import {
   hasDeferrableGroups,
   navVariants,
 } from "../components/layout/nav-utils.ts";
-import { normalizeBasePath } from "../core/base-path.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
@@ -81,7 +81,9 @@ import { ogCacheDir } from "../og/cache.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
-import type { ApiSpecData, OpenApiData } from "../openapi/model.ts";
+import type { AsyncApiSpecValue } from "../openapi/asyncapi.ts";
+import type { ApiSpecData, HttpMethod, OpenApiData } from "../openapi/model.ts";
+import { HTTP_METHODS, withServerDefaults } from "../openapi/model.ts";
 import {
   builtinProxyReferences,
   hasScalarReferences,
@@ -954,6 +956,8 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
+  // `link.href` stays as authored; the link the banner renders is the
+  // navigation's `bannerHref`, localized and mounted under `basePath`.
   return {
     content: banner.content,
     dismissible: banner.dismissible,
@@ -1489,28 +1493,41 @@ const writeApiFiles = async (
   await Promise.all(writes);
 };
 
+/** The proxy endpoint's file under the Astro `src/` dir (eject writes it too). */
+export const PLAYGROUND_PROXY_ENTRY = join("blume-openapi", "api-proxy.ts");
+
+/** The URL the built-in proxy is injected at (see {@link planPlaygroundProxy}). */
+export const playgroundProxyPattern = (config: ResolvedConfig): string =>
+  withBasePath(config.basePath, "/_api-proxy");
+
 /**
  * Decide whether to generate the playground's built-in CORS proxy endpoint.
  * Only the Blume renderer's playground with `proxy: true` needs it — a proxy
  * URL string points at an external service, and `false` sends requests
  * directly. Injected at `/_api-proxy` (rather than written under `pages/`)
  * because Astro treats `_`-prefixed page files as private; the endpoint's own
- * `prerender = false` export wins over the injection default.
+ * `prerender = false` export wins over the injection default. Mounted under
+ * the site `basePath`, at the URL the playground sends to (see
+ * openapi/source.ts); Astro layers `deployment.base` onto both.
  */
 const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
   enabled: needsPlaygroundProxy(config),
-  entrypoint: join(srcDir, "blume-openapi", "api-proxy.ts"),
-  pattern: "/_api-proxy",
+  entrypoint: join(srcDir, PLAYGROUND_PROXY_ENTRY),
+  pattern: playgroundProxyPattern(config),
 });
 
 /**
  * The origins the built-in proxy is allowed to reach: one per absolute
- * `servers[].url` across the parsed specs. This is the endpoint's whole trust
- * boundary — the client sends the target as a query parameter, and a reader's
- * custom base URL is not a documented server — so it is derived here, at build
- * time, from the same documents the operation pages render.
+ * `servers[].url` across the parsed specs — the document's, each path item's,
+ * and each operation's, since an operation's playground sends to the most
+ * specific of those. This is the endpoint's whole trust boundary — the client
+ * sends the target as a query parameter, and a reader's custom base URL is not
+ * a documented server — so it is derived here, at build time, from the same
+ * documents the operation pages render.
  *
- * Relative (`/v1`) and templated (`{env}.api.example.com`) server URLs carry no
+ * A templated URL (`https://{env}.api.example.com`) is allowed as the
+ * playground sends it, with each variable at its declared default. Relative
+ * (`/v1`) URLs, and templates with a variable left undefaulted, carry no
  * origin to allow and are skipped; AsyncAPI documents declare `servers` as a
  * map and contribute nothing (the proxy is OpenAPI-only).
  */
@@ -1526,27 +1543,53 @@ const specOriginsOf = (spec: ApiSpecData): string[] => {
     }
   }
   // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
-  // the optional `servers` shape, and every access below re-checks it —
-  // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
-  const { servers } = spec.document as { servers?: { url?: string }[] };
-  for (const server of Array.isArray(servers) ? servers : []) {
-    const url = server.url ?? "";
-    // `new URL("https://{region}.api.example.com")` parses — the braces land
-    // in the hostname — so templated URLs need an explicit check or their
-    // junk literal becomes an allowlist entry no real request can match.
-    if (url.includes("{")) {
-      continue;
+  // the optional `servers` and `paths` shapes, and every access below
+  // re-checks them — `Array.isArray` guards each list, optional chaining each
+  // path item and operation, and `server.url ?? ""` the url.
+  const document = spec.document as {
+    paths?: Record<string, DocumentPathItem | null | undefined>;
+    servers?: DocumentServer[];
+  };
+  const lists = [document.servers];
+  for (const item of Object.values(document.paths ?? {})) {
+    lists.push(item?.servers);
+    for (const method of HTTP_METHODS) {
+      lists.push(item?.[method]?.servers);
     }
-    try {
-      origins.add(new URL(url).origin);
-    } catch {
-      // Not an absolute URL: nothing to allow.
+  }
+  for (const servers of lists) {
+    for (const server of Array.isArray(servers) ? servers : []) {
+      const url = withServerDefaults(server.url ?? "", server.variables);
+      // `new URL("https://{region}.api.example.com")` parses — the braces land
+      // in the hostname — so a variable with no default needs an explicit
+      // check or its junk literal becomes an allowlist entry no real request
+      // can match.
+      if (url.includes("{")) {
+        continue;
+      }
+      try {
+        origins.add(new URL(url).origin);
+      } catch {
+        // Not an absolute URL: nothing to allow.
+      }
     }
   }
   return [...origins];
 };
 
-const specOrigins = (data: OpenApiData): string[] =>
+/** A `servers[]` entry as a parsed spec document declares it. */
+interface DocumentServer {
+  url?: string;
+  variables?: AsyncApiSpecValue;
+}
+
+/** An OpenAPI path item: its own `servers` plus one per operation. */
+type DocumentPathItem = { servers?: DocumentServer[] } & Partial<
+  Record<HttpMethod, { servers?: DocumentServer[] } | null>
+>;
+
+/** The built-in proxy's allowlist: every spec's origins, deduped and sorted. */
+export const specOrigins = (data: OpenApiData): string[] =>
   [...new Set(Object.values(data).flatMap(specOriginsOf))].toSorted();
 
 /**
@@ -1558,7 +1601,7 @@ const specOrigins = (data: OpenApiData): string[] =>
  * whose own origins came out empty (no absolute `servers[].url`, no absolute
  * GraphQL `endpoint`) gets a warning naming it.
  */
-const proxyAllowlistWarnings = (
+export const proxyAllowlistWarnings = (
   config: ResolvedConfig,
   data: OpenApiData
 ): string[] => {
@@ -1573,7 +1616,7 @@ const proxyAllowlistWarnings = (
     warnings.push(
       spec.kind === "graphql"
         ? `The "${spec.label}" GraphQL reference (${spec.route}) has playground.proxy: true, but no absolute endpoint is configured for it, so the built-in proxy has no origin to allow and will refuse every request its playground sends. Set \`endpoint\` on the graphql() adapter (or the source) to the live GraphQL URL, or point playground.proxy at an external proxy URL.`
-        : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative and templated URLs carry no origin), so the built-in proxy has no origin to allow and will refuse every request its playground sends. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.`
+        : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative URLs, and templated ones with a variable missing its default, carry no origin), so the built-in proxy has no origin to allow and will refuse every request its playground sends. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.`
     );
   }
   return warnings;
@@ -1699,6 +1742,7 @@ export const analyzeComponentsFile = async (
 const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
   resolveOgFonts(
     {
+      locales: fontLocaleCodes(project.config.i18n),
       ogFonts: project.config.seo.og.fonts,
       themeFonts: project.config.theme.fonts,
       themeFontsConfigured: project.themeFontsConfigured,

package/src/astro/templates.ts

@@ -14,7 +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 { 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";
@@ -1377,7 +1377,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 +1397,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 +1568,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 +1596,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 +1626,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 +1647,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 +1659,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 +1673,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 });
 };
@@ -2758,6 +2781,7 @@ export const notFoundPageTemplate = (): string => `---
 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 { withBasePath } from "blume/core/base-path.ts";
 import data from "blume:data";
 
 export const prerender = true;
@@ -2795,8 +2819,13 @@ const suggestions = [
 // 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 = withBase(withBasePath(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 +2837,7 @@ const localized = Object.fromEntries(
           description: strings.description,
           dir: l.dir ?? "ltr",
           home: strings.home,
-          homeHref: withBase("/" + l.code),
+          homeHref: withBase(withBasePath(basePath, "/" + l.code)),
           suggestions: strings.suggestions,
           title: strings.title,
         },
@@ -2837,7 +2866,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">
@@ -3300,11 +3329,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",