blume 1.4.3 → 1.5.1

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

@@ -510,7 +510,7 @@ export type FontInput =
 export interface FontsConfig {
   /** Body / prose font. Defaults to `inter`. */
   body?: FontInput;
-  /** Display / heading font. Defaults to `inter-tight`. */
+  /** Display / heading font. Defaults to `inter` (shared with the body). */
   display?: FontInput;
   /** Monospace / code font. Defaults to `ibm-plex-mono`. */
   mono?: FontInput;
@@ -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;
 }
 
 // ---------------------------------------------------------------------------

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);

package/src/core/data.ts

@@ -1,6 +1,7 @@
+import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
-import type { Navigation, RouteAlternate } from "./types.ts";
+import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 
 /**
  * The shape of the `blume:data` virtual module — the resolved, serializable
@@ -85,6 +86,14 @@ export interface BlumeRoute {
   locale: string;
   path: string;
   title: string;
+  /** Resolved docs version (`""` for the current docs). */
+  version: string;
+  /**
+   * Versions this logical page exists in within this route's locale — the
+   * current version first, then archived versions in configured order. Empty
+   * when versioning is off.
+   */
+  versionAlternates: VersionAlternate[];
 }
 
 /** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
@@ -161,6 +170,8 @@ export interface BlumeDataConfig {
    * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
    * list tool to fetch (`ai.llmsTxt.enabled`).
    */
+  /** Docs versioning config; `null` when the site is unversioned. */
+  versions: NonNullable<ResolvedConfig["versions"]> | null;
   webmcp: { enabled: boolean; llms: boolean };
   /** X (Twitter) attribution: the site's account, and a default creator. */
   x: { creator?: string; handle?: string };
@@ -182,12 +193,17 @@ export interface BlumeClientData {
 export interface BlumeData {
   config: BlumeDataConfig;
   feeds: BlumeFeed[];
-  /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
-  fontCssVars: string[];
+  /** Configured fonts for the head: CSS variable + preload weights per family. */
+  fontCssVars: FontHead[];
   /** Sidebar + tab tree for the default locale. */
   navigation: Navigation;
   /** Per-locale navigation trees, keyed by locale code (empty without i18n). */
   navigationByLocale: Record<string, Navigation>;
+  /**
+   * Per-archived-version navigation trees, keyed by version id and then locale
+   * code (`""` on a single-locale site). Empty when versioning is off.
+   */
+  navigationByVersion: Record<string, Record<string, Navigation>>;
   routes: BlumeRoute[];
   /** Resolved UI strings for the default locale. */
   ui: UIStrings;

package/src/core/define-components.ts

@@ -18,6 +18,10 @@ export interface IslandDescriptor {
 export type ComponentOverride = ComponentReference | IslandDescriptor;
 
 /** User-authored component overrides, grouped by surface. */
+// oxlint-disable anti-slop/no-unsafe-dictionary-type -- `ComponentOverride` is untyped by
+// design: user configs pass imported components from any framework (React
+// functions, Svelte classes, Vue SFC objects), which share no structural type.
+// `resolveSlot` and the generated components map are the runtime boundary.
 export interface ComponentOverrides {
   /**
    * Interactive framework components made available in every `.mdx` page. Like
@@ -31,6 +35,7 @@ export interface ComponentOverrides {
   /** MDX component map overrides (`Callout`, `Card`, ...). */
   mdx?: Record<string, ComponentOverride>;
 }
+// oxlint-enable anti-slop/no-unsafe-dictionary-type
 
 /**
  * Identity helper for authoring `components.ts`. Provides type inference and a

package/src/core/diagnostics.ts

@@ -27,41 +27,44 @@ const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
 
 /** Diagnostic code → the docs page that explains it. */
-const DOCS_PATHS: Record<string, string> = {
-  BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
-  BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
-  BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
-  BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
-  BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
-  BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
-  BLUME_CONFIG_INVALID: "/docs/configuration",
-  BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
-  BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
-  BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
-  BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
-  BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
-  BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
-  BLUME_META_INVALID: "/docs/content/meta",
-  BLUME_META_LOAD_FAILED: "/docs/content/meta",
-  BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
-  BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
-  BLUME_NODE_VERSION: "/docs/quickstart",
-  BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
-  BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
-  BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
-  BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
-};
+const DOCS_PATHS = new Map(
+  Object.entries({
+    BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
+    BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
+    BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+    BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
+    BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
+    BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
+    BLUME_CONFIG_INVALID: "/docs/configuration",
+    BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
+    BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
+    BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
+    BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
+    BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
+    BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+    BLUME_META_INVALID: "/docs/content/meta",
+    BLUME_META_LOAD_FAILED: "/docs/content/meta",
+    BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
+    BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
+    BLUME_NODE_VERSION: "/docs/quickstart",
+    BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
+    BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
+    BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
+    BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+    BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
+  })
+);
 
 /** The docs URL that explains a diagnostic code, if one is mapped. */
 export const resolveDocsUrl = (code: string): string | undefined => {
-  const path = DOCS_PATHS[code];
+  const path = DOCS_PATHS.get(code);
   return path ? `${DOCS_BASE}${path}` : undefined;
 };
 
@@ -75,6 +78,10 @@ const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
 const escapeRegExp = (value: string): string =>
   value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
 
+/** A key segment scans the source text; an array index has no key to find. */
+const isKeySegment = (segment: string | number): segment is string =>
+  typeof segment === "string";
+
 /**
  * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`) in
  * the raw config / frontmatter text. Narrows key-by-key — finding each string
@@ -86,9 +93,9 @@ const stepSegment = (
   source: string,
   segment: string | number,
   cursor: number
-): { index: number; next: number; stop: boolean } => {
+) => {
   // A non-string path segment (array index) is skipped without moving on.
-  if (typeof segment !== "string") {
+  if (!isKeySegment(segment)) {
     return { index: -1, next: cursor, stop: false };
   }
   // The negative lookbehind keeps a segment like `title` from matching the
@@ -247,10 +254,11 @@ export const formatDiagnostic = (
 export const hasErrors = (diagnostics: Diagnostic[]): boolean =>
   diagnostics.some((d) => d.severity === "error");
 
-export const countBySeverity = (
-  diagnostics: Diagnostic[]
-): Record<Diagnostic["severity"], number> => {
-  const counts = { error: 0, info: 0, warning: 0 };
+export const countBySeverity = (diagnostics: Diagnostic[]) => {
+  const counts = { error: 0, info: 0, warning: 0 } satisfies Record<
+    Diagnostic["severity"],
+    number
+  >;
   for (const diagnostic of diagnostics) {
     counts[diagnostic.severity] += 1;
   }