blume 1.4.2 → 1.5.0

package/src/components/openapi/security.ts

@@ -20,7 +20,6 @@ export interface SecuritySchemeLike {
   scheme?: string;
   /** `http` bearer: a hint at the token format, e.g. `JWT`. */
   bearerFormat?: string;
-  [key: string]: unknown;
 }
 
 /** One security requirement: scheme name -> required scopes (empty outside OAuth). */
@@ -85,42 +84,115 @@ export const resolveSecurity = (
   return { alternatives, optional };
 };
 
+/**
+ * One AsyncAPI 3.x security entry: a `$ref` into
+ * `components.securitySchemes`, or an inline scheme object (the shape the
+ * official 2.x converter emits for scoped requirements, `scopes` on the
+ * scheme itself).
+ */
+export interface AsyncApiSecurityEntryLike {
+  $ref?: string;
+  type?: string;
+  scopes?: unknown;
+}
+
+const SECURITY_SCHEME_REF = /^#\/components\/securitySchemes\/(?<name>[^/]+)$/u;
+
+/** Runtime string check for spec fields a hand-written document may corrupt. */
+const isSpecString = (value: string | undefined): value is string =>
+  typeof value === "string";
+
+/** Parsed YAML can put anything in a security list; keep only real objects. */
+const isSecurityEntryObject = (
+  entry: AsyncApiSecurityEntryLike
+): entry is AsyncApiSecurityEntryLike =>
+  typeof entry === "object" && entry !== null;
+
+/** Decode a JSON-pointer token: `kafka~1sasl` -> `kafka/sasl`. */
+const unescapePointer = (token: string): string =>
+  token.replaceAll("~1", "/").replaceAll("~0", "~");
+
+/**
+ * Resolve an AsyncAPI 3.x security list. Unlike OpenAPI's requirement maps,
+ * each entry names a single scheme and any one entry satisfies the operation
+ * — so every entry becomes its own one-scheme "or" alternative. A `$ref`
+ * pointing at an undeclared scheme is kept (with `scheme` undefined),
+ * matching {@link resolveSecurity}'s render-don't-drop rule.
+ */
+export const resolveAsyncApiSecurity = (
+  entries: AsyncApiSecurityEntryLike[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
+  const alternatives: ResolvedScheme[][] = [];
+  for (const entry of entries) {
+    if (!isSecurityEntryObject(entry)) {
+      continue;
+    }
+    const pointer = SECURITY_SCHEME_REF.exec(entry.$ref ?? "")?.groups?.name;
+    const name = pointer === undefined ? undefined : unescapePointer(pointer);
+    const inline = name === undefined && !isSpecString(entry.$ref);
+    const scheme = inline ? entry : schemes?.[name ?? ""];
+    alternatives.push([
+      {
+        key:
+          name ??
+          (isSpecString(entry.type) && entry.type !== ""
+            ? entry.type
+            : "security"),
+        scheme,
+        scopes:
+          inline && Array.isArray(entry.scopes)
+            ? entry.scopes.filter(
+                (scope): scope is string => typeof scope === "string"
+              )
+            : [],
+      },
+    ]);
+  }
+  return { alternatives, optional: false };
+};
+
 const capitalize = (text: string): string =>
   text.charAt(0).toUpperCase() + text.slice(1);
 
+/**
+ * Fixed labels for scheme types with no per-scheme variation. Covers both
+ * OpenAPI's types and the broker-auth types AsyncAPI adds; `http` is handled
+ * separately (its label depends on the scheme/bearerFormat fields).
+ */
+const TYPE_LABELS = new Map<string, string>([
+  ["X509", "X.509 certificate"],
+  ["apiKey", "API key"],
+  ["asymmetricEncryption", "Asymmetric encryption"],
+  ["gssapi", "SASL/GSSAPI"],
+  ["httpApiKey", "API key"],
+  ["mutualTLS", "Mutual TLS"],
+  ["oauth2", "OAuth2 access token"],
+  ["openIdConnect", "OpenID Connect token"],
+  ["plain", "SASL/PLAIN"],
+  ["scramSha256", "SASL/SCRAM-SHA-256"],
+  ["scramSha512", "SASL/SCRAM-SHA-512"],
+  ["symmetricEncryption", "Symmetric encryption"],
+  ["userPassword", "Username & password"],
+]);
+
 /** A short human label for a scheme row, e.g. `Bearer token` or `API key`. */
 export const schemeLabel = (resolved: ResolvedScheme): string => {
   const { scheme } = resolved;
-  switch (scheme?.type) {
-    case "http": {
-      const kind = (scheme.scheme ?? "").toLowerCase();
-      if (kind === "bearer") {
-        return scheme.bearerFormat
-          ? `Bearer token (${scheme.bearerFormat})`
-          : "Bearer token";
-      }
-      if (kind === "basic") {
-        return "Basic auth";
-      }
-      return kind ? `HTTP ${kind}` : "HTTP auth";
-    }
-    case "apiKey": {
-      return "API key";
+  if (scheme?.type === "http") {
+    const kind = (scheme.scheme ?? "").toLowerCase();
+    if (kind === "bearer") {
+      return scheme.bearerFormat
+        ? `Bearer token (${scheme.bearerFormat})`
+        : "Bearer token";
     }
-    case "oauth2": {
-      return "OAuth2 access token";
-    }
-    case "openIdConnect": {
-      return "OpenID Connect token";
-    }
-    case "mutualTLS": {
-      return "Mutual TLS";
-    }
-    default: {
-      // Unknown scheme ref: the component name is the best label available.
-      return resolved.key;
+    if (kind === "basic") {
+      return "Basic auth";
     }
+    return kind ? `HTTP ${kind}` : "HTTP auth";
   }
+  // Unknown scheme ref: the component name is the best label available.
+  return TYPE_LABELS.get(scheme?.type ?? "") ?? resolved.key;
 };
 
 /**
@@ -138,7 +210,8 @@ export const schemeCarrier = (
     case "openIdConnect": {
       return { in: "header", name: "Authorization" };
     }
-    case "apiKey": {
+    case "apiKey":
+    case "httpApiKey": {
       return { in: scheme.in ?? "header", name: scheme.name ?? resolved.key };
     }
     default: {

package/src/components/openapi/snippets.ts

@@ -87,8 +87,8 @@ const headerValues = (
   params: ParamLike[],
   schemas: Record<string, SchemaLike>,
   auth: SampleAuth | undefined
-): Record<string, string> => {
-  const headers: Record<string, string> = { ...auth?.headers };
+) => {
+  const headers = { ...auth?.headers };
   for (const param of params) {
     if (param.in === "header" && param.required && param.name) {
       headers[param.name] = String(
@@ -230,14 +230,14 @@ const LANGUAGES: SampleLanguage[] = [
   { build: pythonSnippet, id: "python", label: "Python", lang: "python" },
 ];
 
-const ALIASES: Record<string, string> = {
-  bash: "curl",
-  javascript: "js",
-  node: "js",
-  py: "python",
-  shell: "curl",
-  typescript: "js",
-};
+const ALIASES = new Map([
+  ["bash", "curl"],
+  ["javascript", "js"],
+  ["node", "js"],
+  ["py", "python"],
+  ["shell", "curl"],
+  ["typescript", "js"],
+]);
 
 /** The sample languages to render, resolved from config ids (unknown ids dropped). */
 export const sampleLanguages = (ids: string[]): SampleLanguage[] => {
@@ -246,7 +246,7 @@ export const sampleLanguages = (ids: string[]): SampleLanguage[] => {
   const out: SampleLanguage[] = [];
   const seen = new Set<string>();
   for (const raw of wanted) {
-    const id = ALIASES[raw.toLowerCase()] ?? raw.toLowerCase();
+    const id = ALIASES.get(raw.toLowerCase()) ?? raw.toLowerCase();
     const language = byId.get(id);
     if (language && !seen.has(id)) {
       seen.add(id);

package/src/components/raf-throttle.ts

@@ -0,0 +1,21 @@
+/**
+ * Coalesce a high-frequency event handler (resize, scroll) into at most one
+ * call per animation frame — the toc-element scroll pattern, shared. Calls
+ * landing while a frame is pending are dropped; the handler runs once on the
+ * next frame with the latest state. Layout reads inside `fn` then happen once
+ * per frame instead of once per event, without the settle lag a debounce
+ * would add to position-tracking handlers.
+ */
+export const rafThrottle = (fn: () => void): (() => void) => {
+  let ticking = false;
+  return () => {
+    if (ticking) {
+      return;
+    }
+    ticking = true;
+    requestAnimationFrame(() => {
+      ticking = false;
+      fn();
+    });
+  };
+};

package/src/components/slug.ts

@@ -0,0 +1,14 @@
+import { slug } from "github-slugger";
+
+/**
+ * Slug a component's title into a DOM id (accordions, tabs, changelog
+ * updates), replacing three identical per-component copies. github-slugger —
+ * already what heading anchors use, both here and in Satteri's own
+ * heading-ids — so a component id slugs exactly like a heading with the same
+ * text (unicode letters kept, `user_id` keeps its underscore, `C#` keeps
+ * nothing extra dropped). Stateless on purpose: components render across many
+ * pages in one build process, so a stateful slugger would leak duplicate
+ * suffixes between pages — same-page duplicates are de-duplicated client-side
+ * by each component's own script.
+ */
+export const componentSlug = (value: string): string => slug(value);

package/src/core/base-path.ts

@@ -12,6 +12,8 @@
  * `components/islands/base-path.ts` and serves `deployment.base` via `BASE_URL`.
  */
 
+import { trimEnd } from "./trim.ts";
+
 /**
  * Canonicalize a configured base path to either `""` (none) or `/seg[/seg…]`
  * (leading slash, no trailing slash, collapsed inner slashes). A blank value or
@@ -33,10 +35,25 @@ export const normalizeBasePath = (input?: string): string => {
  * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
  */
 export const normalizePath = (path: string): string => {
-  const trimmed = path.replace(/\/+$/u, "");
+  const trimmed = trimEnd(path, "/");
   return trimmed === "" ? "/" : trimmed;
 };
 
+/**
+ * Canonicalize a route-ish string (a configured route, a page path, an agent-
+ * supplied route) to `/` or `/seg[/seg…]`: trimmed, exactly one leading slash,
+ * no trailing slash. The shared spelling of what openapi/references,
+ * ai/ask-context, and ai/mcp/server each hand-rolled with slightly different
+ * regexes.
+ */
+export const normalizeRoute = (input: string): string => {
+  const trimmed = trimEnd(input.trim(), "/");
+  if (trimmed === "") {
+    return "/";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+};
+
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/src/core/component-overrides.ts

@@ -65,18 +65,20 @@ const GROUPS = ["mdx", "layout", "islands"] as const;
 const GROUP_SET = new Set<string>(GROUPS);
 type Group = (typeof GROUPS)[number];
 
-const FRAMEWORK_BY_EXT: Record<string, OverrideFramework> = {
-  jsx: "react",
-  svelte: "svelte",
-  tsx: "react",
-  vue: "vue",
-};
+const isGroup = (name: string): name is Group => GROUP_SET.has(name);
+
+const FRAMEWORK_BY_EXT = new Map<string, OverrideFramework>([
+  ["jsx", "react"],
+  ["svelte", "svelte"],
+  ["tsx", "react"],
+  ["vue", "vue"],
+]);
 
-const FRAMEWORK_LABEL: Record<OverrideFramework, string> = {
+const FRAMEWORK_LABEL = {
   react: "React",
   svelte: "Svelte",
   vue: "Vue",
-};
+} satisfies Record<OverrideFramework, string>;
 
 /** Extensions probed (in order) when a specifier omits one. */
 const COMPONENT_EXTS = [
@@ -90,7 +92,7 @@ const COMPONENT_EXTS = [
   "svelte",
 ];
 
-const HYDRATION_MODES = new Set<HydrationMode>([
+const HYDRATION_MODES: ReadonlySet<string> = new Set<HydrationMode>([
   "idle",
   "load",
   "media",
@@ -98,6 +100,9 @@ const HYDRATION_MODES = new Set<HydrationMode>([
   "visible",
 ]);
 
+const isHydrationMode = (value: string): value is HydrationMode =>
+  HYDRATION_MODES.has(value);
+
 interface ImportBinding {
   /** Exported name: `"default"` or a named export. */
   imported: string;
@@ -226,7 +231,7 @@ const toImport = (
     }
   }
   return {
-    framework: FRAMEWORK_BY_EXT[extension] ?? null,
+    framework: FRAMEWORK_BY_EXT.get(extension) ?? null,
     name: imported,
     path,
   };
@@ -270,9 +275,9 @@ const applyDescriptorProperty = (
   } else if (
     name === "client" &&
     ts.isStringLiteral(init) &&
-    HYDRATION_MODES.has(init.text as HydrationMode)
+    isHydrationMode(init.text)
   ) {
-    descriptor.client = init.text as HydrationMode;
+    descriptor.client = init.text;
   } else if (name === "media" && ts.isStringLiteral(init)) {
     descriptor.media = init.text;
   }
@@ -334,13 +339,14 @@ const finalize = (
     );
   }
 
-  return {
-    identifier,
-    key,
-    ...(client ? { client } : {}),
-    ...(media ? { media } : {}),
-    source,
-  };
+  const normalized: NormalizedOverride = { identifier, key, source };
+  if (client) {
+    normalized.client = client;
+  }
+  if (media) {
+    normalized.media = media;
+  }
+  return normalized;
 };
 
 const normalizeEntry = (
@@ -446,22 +452,21 @@ const collectGroupOverrides = (
   }
   const name = propName(property.name);
   if (
-    !(name && GROUP_SET.has(name)) ||
+    !(name && isGroup(name)) ||
     !ts.isObjectLiteralExpression(property.initializer)
   ) {
     return;
   }
-  const group = name as Group;
   for (const entry of property.initializer.properties) {
     const normalized = normalizeEntry(
       entry,
-      group,
+      name,
       imports,
       dir,
       result.warnings
     );
     if (normalized) {
-      result[group].push(normalized);
+      result[name].push(normalized);
     }
   }
 };

package/src/core/config-input.ts

@@ -205,6 +205,8 @@ export interface SanitySource {
 /** A Notion database; pages become entries, blocks become MDX. */
 export interface NotionSource {
   type: "notion";
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency?: number;
   /** Notion database id. */
   database: string;
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
@@ -653,6 +655,12 @@ export interface AskConfig {
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
   endpoint?: string;
+  /**
+   * Extra system-prompt text appended to the built-in instructions — use it
+   * for identity, language, or tone. The built-in grounding behavior (answer
+   * from the retrieved excerpts, cite pages as Markdown links) is preserved.
+   */
+  instructions?: string;
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
@@ -753,6 +761,7 @@ export interface AiConfig {
 /** Web Bot Auth signature directory. Off until at least one key is listed. */
 export interface WebBotAuthConfig {
   /** Public JWKs to publish (e.g. an Ed25519 key: `kty: "OKP"`, `crv: "Ed25519"`, `x: …`). */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- mirrors the schema's `z.record(z.unknown())` (the drift guard requires it); JWK parameters are validated at parse time, not typed.
   keys?: Record<string, unknown>[];
 }
 
@@ -830,6 +839,59 @@ export interface I18nConfig {
   ui?: Record<string, Record<string, Record<string, string>>>;
 }
 
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+
+/** A frozen documentation snapshot: a directory under the content root. */
+export interface ArchivedVersionInput {
+  /**
+   * The "you're viewing an old version" notice: `true` (default) for the
+   * built-in message, a string for custom copy, `false` to hide it.
+   */
+  banner?: boolean | string;
+  /**
+   * Where this version's pages point their canonical URL. `latest` (default)
+   * targets the same page in the current docs when it still exists (self
+   * otherwise); `self` keeps every page authoritative.
+   */
+  canonical?: "latest" | "self";
+  /**
+   * Directory name under the content root, and the URL segment. Must start
+   * with a letter (e.g. `v1.0`).
+   */
+  id: string;
+  /** Switcher label; defaults to the id. */
+  label?: string;
+  /** Emit `noindex` on every page of this version. Defaults to `false`. */
+  noindex?: boolean;
+}
+
+/**
+ * Docs versioning. Opt-in: the latest docs live at the content root with
+ * unprefixed URLs, and each archived version is a frozen snapshot directory
+ * (`content/docs/<id>/`) cut with `blume version <id>`. Archived means frozen:
+ * snapshots carry their own translations and are never retranslated.
+ */
+export interface VersionsConfig {
+  /** Frozen snapshots, newest first — this order is the switcher order. */
+  archived?: ArchivedVersionInput[];
+  /** Labels the unprefixed tree (the latest docs) in the switcher. */
+  current: {
+    /** Small tag rendered next to the label (e.g. `Latest`). */
+    badge?: string;
+    label: string;
+  };
+  switcher?: {
+    /**
+     * Where switching lands when the page has no equivalent in the target
+     * version: `same-page` (default) goes to the equivalent when it exists
+     * (version root otherwise); `root` always goes to the version root.
+     */
+    redirect?: "same-page" | "root";
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Deployment & redirects
 // ---------------------------------------------------------------------------
@@ -1104,28 +1166,24 @@ export interface ReactConfig {
 // ---------------------------------------------------------------------------
 
 /**
- * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:
- * one real page per operation, grouped by tag in the sidebar and included in
- * search, llms.txt, and OG. Set `renderer: "scalar"` for the embedded Scalar
- * SPA (a single self-contained route).
+ * The shared shape of both API-reference blocks (`openapi`, `asyncapi`). Only
+ * the per-block defaults differ; those are documented on the extending
+ * interfaces.
  */
-export interface OpenApiConfig {
-  /** Code-sample languages shown per operation (Blume renderer). */
-  codeSamples?: string[];
+interface ReferenceConfig {
   /** Turn the reference on. Defaults to `false`. */
   enabled?: boolean;
   /** Start nested schema rows expanded (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
   /** Who renders the reference. Defaults to `blume`. */
   renderer?: "blume" | "scalar";
-  /** Where the reference mounts. Defaults to `/reference`. */
-  route?: string;
   /**
    * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`
    * (Scalar renderer only) — e.g. `localization`, `agent`,
    * `hideTestRequestButton`, `orderSchemaPropertiesBy`. These win over Blume's
    * derived spec/theme config, so it's a full escape hatch to Scalar's API.
    */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- mirrors the schema's `z.record(z.unknown())` (the drift guard requires it); the values are Scalar's own API surface, deliberately unmodeled.
   scalar?: Record<string, unknown>;
   /** One or more specs; each renders on its own route by default. */
   sources?: OpenApiSource[];
@@ -1136,27 +1194,36 @@ export interface OpenApiConfig {
 }
 
 /**
- * AsyncAPI reference, rendered via the embedded Scalar SPA (which auto-detects
- * the document type). Same shape as {@link OpenApiConfig}; only the default
- * `route` differs.
+ * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:
+ * one real page per operation, grouped by tag in the sidebar and included in
+ * search, llms.txt, and OG. Set `renderer: "scalar"` for the embedded Scalar
+ * SPA (a single self-contained route).
  */
-export interface AsyncApiConfig {
-  /** Turn the reference on. Defaults to `false`. */
-  enabled?: boolean;
-  /** Where the reference mounts. Defaults to `/events`. */
+export interface OpenApiConfig extends ReferenceConfig {
+  /**
+   * Code-sample languages shown per operation (Blume renderer). Defaults to
+   * `["curl", "js", "python"]`.
+   */
+  codeSamples?: string[];
+  /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
+}
+
+/**
+ * AsyncAPI reference. Same shape as {@link OpenApiConfig}: by default
+ * (`renderer: "blume"`) Blume normalizes the spec to AsyncAPI 3.x and renders
+ * its own UI — one real page per operation, grouped by tag (or channel) in the
+ * sidebar and included in search, llms.txt, and OG. Set `renderer: "scalar"`
+ * for the embedded Scalar SPA (a single self-contained route).
+ */
+export interface AsyncApiConfig extends ReferenceConfig {
   /**
-   * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`.
-   * These win over Blume's derived spec/theme config — a full escape hatch to
-   * Scalar's API.
+   * Code-sample tools shown per operation (Blume renderer). Defaults to every
+   * tool appropriate to the operation's protocol binding.
    */
-  scalar?: Record<string, unknown>;
-  /** One or more specs. */
-  sources?: OpenApiSource[];
-  /** Shorthand for a single source. */
-  spec?: string;
-  /** Scalar theme name. */
-  theme?: string;
+  codeSamples?: string[];
+  /** Where the reference mounts. Defaults to `/events`. */
+  route?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -1294,7 +1361,7 @@ export interface BlumeConfig {
   ai?: AiConfig;
   /** Analytics providers (PostHog, Vercel, or arbitrary scripts). */
   analytics?: AnalyticsConfig;
-  /** AsyncAPI reference (embedded Scalar renderer). */
+  /** AsyncAPI reference (native renderer by default, Scalar opt-out). */
   asyncapi?: AsyncApiConfig;
   /** Site-wide announcement banner shown above the header. */
   banner?: BannerConfig;
@@ -1367,6 +1434,8 @@ export interface BlumeConfig {
   title?: string;
   /** On-page table of contents. Defaults to on (H2–H3). */
   toc?: TocConfig;
+  /** Docs versioning (opt-in frozen snapshots with a version switcher). */
+  versions?: VersionsConfig;
 }
 
 // ---------------------------------------------------------------------------

package/src/core/config.ts

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import { z } from "zod";
+
 import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
@@ -68,7 +70,8 @@ import type { Diagnostic } from "./types.ts";
  * **Reference docs**
  * - `openapi` — native OpenAPI reference: one real page per operation, woven
  *   into the sidebar and search. Point `sources`/`spec` at your spec.
- * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ * - `asyncapi` — native AsyncAPI reference with the same treatment; 2.x specs
+ *   are normalized to 3.x automatically.
  *
  * **Search & AI**
  * - `search` — search backend `provider` (`orama` by default; `pagefind`,
@@ -161,6 +164,15 @@ export interface ConfigLoadResult {
 
 const importConfigModule = createModuleLoader();
 
+/**
+ * The slice of a user config module probed before schema defaults apply:
+ * whether `theme.fonts` was actually set. `looseObject` keeps every other key
+ * out of scope; a non-object at either level simply fails the probe.
+ */
+const themeFontsProbeSchema = z.looseObject({
+  theme: z.looseObject({ fonts: z.unknown() }).optional(),
+});
+
 /**
  * Load and validate the project config. When no config file exists, schema
  * defaults produce a fully resolved config so the zero-boilerplate path works.
@@ -176,11 +188,14 @@ export const loadConfig = async (
 ): Promise<ConfigLoadResult> => {
   const configFile = findConfigFile(root);
 
-  let raw: unknown = {};
+  let raw: unknown;
   if (configFile) {
     try {
       raw = await importConfigModule(configFile);
     } catch (error) {
+      // SAFETY: the module loader rejects with the thrown load/parse failure,
+      // which Node surfaces as an Error; a non-Error rejection only degrades
+      // the interpolated message.
       throw new BlumeError({
         code: "BLUME_CONFIG_LOAD_FAILED",
         file: configFile,
@@ -191,11 +206,9 @@ export const loadConfig = async (
   }
 
   // Read before parsing: schema defaults erase the set-vs-defaulted distinction.
-  const themeFontsConfigured = Boolean(
-    raw &&
-    typeof raw === "object" &&
-    (raw as { theme?: { fonts?: unknown } }).theme?.fonts !== undefined
-  );
+  const probe = themeFontsProbeSchema.safeParse(raw);
+  const themeFontsConfigured =
+    probe.success && probe.data.theme?.fonts !== undefined;
 
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {

package/src/core/content.ts

@@ -1,4 +1,4 @@
-import type { ResolvedI18nConfig } from "./schema.ts";
+import type { ResolvedI18nConfig, ResolvedVersionsConfig } from "./schema.ts";
 import { filesystemSource } from "./sources/filesystem.ts";
 import { normalizeEntry } from "./sources/normalize.ts";
 import type { Diagnostic, PageRecord } from "./types.ts";
@@ -24,6 +24,7 @@ export const discoverContent = async (options: {
   defaultType: string;
   basePath?: string;
   i18n?: ResolvedI18nConfig;
+  versions?: ResolvedVersionsConfig;
 }): Promise<{ pages: PageRecord[]; diagnostics: Diagnostic[] }> => {
   const source = filesystemSource({
     exclude: options.exclude,
@@ -43,6 +44,7 @@ export const discoverContent = async (options: {
       defaultType: options.defaultType,
       i18n: options.i18n,
       source: { name: source.name, prefix: source.prefix, staged: false },
+      versions: options.versions,
     });
     pages.push(...normalized.pages);
     diagnostics.push(...normalized.diagnostics);