blume 1.4.3 → 1.5.0

package/src/components/openapi/helpers.ts

@@ -8,6 +8,22 @@ import { sample } from "openapi-sampler";
  * values come from openapi-sampler, which is likewise browser-safe.
  */
 
+/** Any value a parsed OpenAPI document can hold: JSON, nested schemas included. */
+export type SpecValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | SpecValue[]
+  | { [key: string]: SpecValue };
+
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const isNumber = (value: SpecValue): value is number =>
+  typeof value === "number";
+
 /** A permissive view of an OpenAPI 3.1 schema — only the fields we render. */
 export interface SchemaLike {
   $ref?: string;
@@ -18,11 +34,11 @@ export interface SchemaLike {
   properties?: Record<string, SchemaLike>;
   required?: string[];
   items?: SchemaLike;
-  enum?: unknown[];
-  const?: unknown;
-  default?: unknown;
-  example?: unknown;
-  examples?: unknown[];
+  enum?: SpecValue[];
+  const?: SpecValue;
+  default?: SpecValue;
+  example?: SpecValue;
+  examples?: SpecValue[];
   allOf?: SchemaLike[];
   oneOf?: SchemaLike[];
   anyOf?: SchemaLike[];
@@ -38,7 +54,7 @@ export interface SchemaLike {
   minItems?: number;
   maxItems?: number;
   pattern?: string;
-  [key: string]: unknown;
+  [key: string]: SpecValue;
 }
 
 /** A permissive view of an operation parameter — only the fields we render. */
@@ -50,9 +66,16 @@ export interface ParameterLike {
   required?: boolean;
   deprecated?: boolean;
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  [key: string]: SpecValue;
 }
 
+/** The `components` object of a parsed spec: section name → named-node table. */
+export type ComponentsLike = Record<
+  string,
+  Record<string, SpecValue> | undefined
+>;
+
 const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
 
 const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
@@ -65,16 +88,18 @@ const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
  */
 export const resolveComponentRef = <T extends { $ref?: string }>(
   node: T,
-  components: Record<string, unknown> | undefined,
+  components: ComponentsLike | undefined,
   section: string
 ): T => {
-  if (typeof node.$ref !== "string") {
+  if (!isString(node.$ref)) {
     return node;
   }
   const groups = COMPONENT_REF.exec(node.$ref)?.groups;
   if (groups?.section !== section) {
     return node;
   }
+  // SAFETY: a components section table stores nodes of that section's type,
+  // and callers always pair `section` with the matching `T`.
   const table = components?.[section] as Record<string, T> | undefined;
   return table?.[groups.name ?? ""] ?? node;
 };
@@ -88,7 +113,7 @@ export const resolveComponentRef = <T extends { $ref?: string }>(
 export const mergeParameters = (
   pathParameters: ParameterLike[] | undefined,
   operationParameters: ParameterLike[] | undefined,
-  components?: Record<string, unknown>
+  components?: ComponentsLike
 ): ParameterLike[] => {
   const merged = new Map<string, ParameterLike>();
   let position = 0;
@@ -118,7 +143,7 @@ export const resolveSchema = (
   if (!schema) {
     return {};
   }
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
     if (name && schemas[name]) {
       return schemas[name];
@@ -140,7 +165,7 @@ const nonNullTypes = (type: string | string[] | undefined): string[] => {
  * array items can't recurse forever.
  */
 export const typeLabel = (schema: SchemaLike): string => {
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     return refName(schema.$ref);
   }
   if (schema.oneOf || schema.anyOf) {
@@ -177,11 +202,11 @@ export const constraints = (schema: SchemaLike): string[] => {
   ];
   for (const [key, label] of numeric) {
     const value = schema[key];
-    if (typeof value === "number") {
+    if (isNumber(value)) {
       out.push(`${label} ${value}`);
     }
   }
-  if (typeof schema.pattern === "string") {
+  if (isString(schema.pattern)) {
     out.push(`matches ${schema.pattern}`);
   }
   if (schema.default !== undefined) {
@@ -190,6 +215,12 @@ export const constraints = (schema: SchemaLike): string[] => {
   return out;
 };
 
+/** The merged property list and required set a schema exposes. */
+export interface ObjectPropertySet {
+  properties: [string, SchemaLike][];
+  required: Set<string>;
+}
+
 /**
  * The object properties a schema exposes, merging `allOf` branches so an
  * `allOf`-composed model still lists every field. Returns the properties plus
@@ -198,7 +229,7 @@ export const constraints = (schema: SchemaLike): string[] => {
 export const objectProperties = (
   schema: SchemaLike,
   schemas: Record<string, SchemaLike>
-): { properties: [string, SchemaLike][]; required: Set<string> } => {
+): ObjectPropertySet => {
   const properties = new Map<string, SchemaLike>();
   const required = new Set<string>();
   // Cycles can only enter through `$ref`s (inline JSON can't self-nest), so
@@ -206,7 +237,7 @@ export const objectProperties = (
   const seen = new Set<string>();
 
   const collect = (node: SchemaLike): void => {
-    if (typeof node.$ref === "string") {
+    if (isString(node.$ref)) {
       if (seen.has(node.$ref)) {
         return;
       }
@@ -239,16 +270,18 @@ export const objectProperties = (
 export const exampleValue = (
   schema: SchemaLike | undefined,
   schemas: Record<string, SchemaLike>
-): unknown => {
+): SpecValue => {
   if (!schema) {
     return null;
   }
   try {
+    // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
+    // sampler reads, and the sampler only ever assembles JSON values.
     return sample(
       schema as Parameters<typeof sample>[0],
       { quiet: true, skipReadOnly: true },
       { components: { schemas } }
-    );
+    ) as SpecValue;
   } catch {
     // An unresolvable $ref or malformed schema is a spec problem the schema
     // tables already surface; a sample is best-effort.
@@ -257,5 +290,4 @@ export const exampleValue = (
 };
 
 /** Pretty-print a JSON value for an example/code block. */
-export const toJson = (value: unknown): string =>
-  JSON.stringify(value, null, 2);
+export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

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/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

@@ -761,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>[];
 }
 
@@ -838,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
 // ---------------------------------------------------------------------------
@@ -1112,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[];
@@ -1144,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -1302,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;
@@ -1375,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;
 }
 
 // ---------------------------------------------------------------------------