blume 0.4.0 → 0.5.0

package/src/migrate/mintlify/config.ts

@@ -9,6 +9,7 @@ import type {
   ResolvedConfig,
   SidebarItemConfig,
 } from "../../core/schema.ts";
+import { GOOGLE_FONTS } from "../../theme/fonts.ts";
 
 type JsonObject = Record<string, unknown>;
 type NavigationSelectors = ResolvedConfig["navigation"]["selectors"];
@@ -593,6 +594,16 @@ const mintignorePatterns = async (root: string): Promise<string[]> => {
   }
 };
 
+// path-to-regexp param (:slug, :slug*, :id?) → Astro dynamic segment.
+// *,+ (repeatable) → spread [...name]; bare/? → single [name]. Name must start
+// with a letter/underscore so URL ports (:8080) and protocols (https:) are left alone.
+const REDIRECT_PARAM = /:(?<name>[A-Za-z_]\w*)(?<modifier>[*+?])?/gu;
+
+const toAstroRedirectPath = (path: string): string =>
+  path.replaceAll(REDIRECT_PARAM, (_match, name: string, modifier?: string) =>
+    modifier === "*" || modifier === "+" ? `[...${name}]` : `[${name}]`
+  );
+
 const mintlifyRedirects = (
   spec: JsonObject
 ): NonNullable<BlumeConfig["redirects"]> =>
@@ -609,9 +620,100 @@ const mintlifyRedirects = (
     if (!from || !to) {
       return [];
     }
-    return [{ from, to }];
+    return [{ from: toAstroRedirectPath(from), to: toAstroRedirectPath(to) }];
+  });
+
+interface OpenApiSourceDraft {
+  label?: string;
+  route?: string;
+  spec: string;
+}
+
+// A Mintlify `{ source, directory }` object's `directory` is the URL path its
+// generated pages mount under; map it to a Blume per-source `route`.
+const openapiRouteFromDirectory = (value: unknown): string | undefined => {
+  const directory = normalizeDirectory(asString(value) ?? "");
+  return directory.length > 0 ? `/${directory}` : undefined;
+};
+
+// Resolve a Mintlify `openapi` value (a spec string, an array, or a
+// `{ source, directory }` object) into spec sources. Endpoint refs (`GET /path`)
+// are skipped — Blume's native renderer generates those pages from the spec.
+const openapiSourcesFromValue = (
+  value: unknown,
+  context: { label?: string; route?: string }
+): OpenApiSourceDraft[] => {
+  if (typeof value === "string") {
+    if (value.length === 0 || API_ENDPOINT_REF.test(value)) {
+      return [];
+    }
+    return [
+      withoutUndefined({
+        label: context.label,
+        route: context.route,
+        spec: value,
+      }),
+    ];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => openapiSourcesFromValue(item, context));
+  }
+  const object = asObject(value);
+  if (!object) {
+    return [];
+  }
+  return openapiSourcesFromValue(object.source ?? object.openapi, {
+    label: context.label,
+    route: openapiRouteFromDirectory(object.directory) ?? context.route,
+  });
+};
+
+// Walk the navigation tree collecting every `openapi` source — a group or tab
+// can declare one alongside its pages — then fold in the top-level specs
+// (legacy `mint.json` `openapi`, newer `api.openapi`) and dedupe by spec so a
+// Mintlify API reference maps to Blume's native renderer instead of dropping.
+const mintlifyOpenapi = (spec: JsonObject): BlumeConfig["openapi"] => {
+  const drafts: OpenApiSourceDraft[] = [];
+
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+      }
+      return;
+    }
+    const object = asObject(node);
+    if (!object) {
+      return;
+    }
+    if (hasOwn(object, "openapi")) {
+      drafts.push(
+        ...openapiSourcesFromValue(object.openapi, {
+          label: labelForNavItem(object),
+        })
+      );
+    }
+    for (const children of childNavigationArrays(object)) {
+      visit(children);
+    }
+  };
+
+  visit(spec.navigation);
+  drafts.push(...openapiSourcesFromValue(spec.openapi, {}));
+  drafts.push(...openapiSourcesFromValue(asObject(spec.api)?.openapi, {}));
+
+  const seen = new Set<string>();
+  const sources = drafts.flatMap((draft) => {
+    if (seen.has(draft.spec)) {
+      return [];
+    }
+    seen.add(draft.spec);
+    return [draft];
   });
 
+  return sources.length > 0 ? { enabled: true, sources } : undefined;
+};
+
 const mintlifyLogo = (value: unknown): BlumeConfig["logo"] => {
   if (typeof value === "string") {
     return value;
@@ -645,6 +747,16 @@ const mintlifyFavicon = (value: unknown): BlumeConfig["favicon"] => {
   return withoutUndefined({ dark, light });
 };
 
+// Mintlify defaults to Font Awesome, so a migrated site's bare `icon` names are
+// FA names unless it opted into Lucide/Tabler. Set the default library to match.
+const mintlifyIcons = (value: unknown): BlumeConfig["icons"] => {
+  const library = asString(asObject(value)?.library);
+  return {
+    library:
+      library === "lucide" || library === "tabler" ? library : "fontawesome",
+  };
+};
+
 const mintlifyBanner = (value: unknown): BlumeConfig["banner"] => {
   const object = asObject(value);
   const content = object ? asString(object.content) : undefined;
@@ -768,6 +880,43 @@ const mintlifyMarkdown = (
   });
 };
 
+type ThemeFonts = NonNullable<NonNullable<BlumeConfig["theme"]>["fonts"]>;
+
+// Blume's curated Google-font family names, indexed by lowercased family so a
+// Mintlify `fonts.family: "Space Grotesk"` resolves to the `space-grotesk` slug.
+const FAMILY_TO_SLUG: Record<string, string> = Object.fromEntries(
+  Object.entries(GOOGLE_FONTS).map(([slug, def]) => [
+    def.family.toLowerCase(),
+    slug,
+  ])
+);
+
+const fontSlugForFamily = (value: unknown): string | undefined => {
+  const family = asString(value);
+  return family ? FAMILY_TO_SLUG[family.toLowerCase()] : undefined;
+};
+
+/**
+ * Map Mintlify `fonts` onto Blume `theme.fonts`. Mintlify sets one family for
+ * everything (`fonts.family`) or splits heading/body (`fonts.heading.family`,
+ * `fonts.body.family`); each maps to a curated Blume slug when one matches.
+ * Families outside Blume's set are left unset (defaults) and warned about.
+ */
+const mintlifyFonts = (value: unknown): ThemeFonts | undefined => {
+  const object = asObject(value);
+  if (!object) {
+    return undefined;
+  }
+  const heading = asObject(object.heading);
+  const body = asObject(object.body);
+  const fonts = withoutUndefined({
+    body: fontSlugForFamily(body?.family) ?? fontSlugForFamily(object.family),
+    display:
+      fontSlugForFamily(heading?.family) ?? fontSlugForFamily(object.family),
+  });
+  return Object.keys(fonts).length > 0 ? (fonts as ThemeFonts) : undefined;
+};
+
 const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -825,6 +974,7 @@ export const loadMintlifyConfig = async (
     },
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
+    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
     navigation: {
@@ -834,6 +984,7 @@ export const loadMintlifyConfig = async (
       sidebarVariants: await mintlifySidebarVariants(spec),
       tabs: mintlifyTabs(spec),
     },
+    openapi: mintlifyOpenapi(spec),
     redirects: mintlifyRedirects(spec),
     search: {
       indexing: {
@@ -851,6 +1002,7 @@ export const loadMintlifyConfig = async (
       backgroundDecoration: mintlifyBackgroundDecoration(spec.background),
       backgroundImage: backgroundImage.light,
       backgroundImageDark: backgroundImage.dark,
+      fonts: mintlifyFonts(spec.fonts ?? spec.font),
       mode:
         appearance.default === "light" ||
         appearance.default === "dark" ||

package/src/migrate/mintlify/content.ts

@@ -88,8 +88,14 @@ export const rewriteSnippetImports = (
   return { components, source: next };
 };
 
-/** Component tags Blume has no equivalent for — reported for manual review. */
-const UNSUPPORTED_COMPONENTS = ["ParamField", "ResponseField"];
+/**
+ * Component tags Blume has no equivalent for — reported for manual review.
+ * `<ParamField>`/`<ResponseField>`/`<RequestField>` are no longer here: Blume
+ * ships compat components for them, so migrated docs render as-is. Mintlify's
+ * `<Update>` changelog entry has no component form in Blume (changelog is
+ * frontmatter-driven via `type: changelog`), so it stays flagged.
+ */
+const UNSUPPORTED_COMPONENTS = ["Update"];
 
 /** Names of Mintlify components in `source` that need manual attention. */
 export const unsupportedMintlifyComponents = (source: string): string[] =>

package/src/migrate/mintlify/index.ts

@@ -15,6 +15,56 @@ export interface MintlifyMigrationResult {
   warnings: string[];
 }
 
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+const hasFontFamily = (value: unknown): boolean => {
+  const object = asRecord(value);
+  if (!object) {
+    return false;
+  }
+  const named = (child: unknown): boolean =>
+    typeof asRecord(child)?.family === "string";
+  return (
+    typeof object.family === "string" ||
+    named(object.heading) ||
+    named(object.body)
+  );
+};
+
+/**
+ * Warn about Mintlify site chrome that Blume's config doesn't model, so it isn't
+ * dropped silently: header links (`navbar.links`/`navbar.primary`), footer
+ * socials (`footer.socials`), and fonts outside Blume's curated Google set. The
+ * contextual page menu and last-updated timestamp are covered by Blume defaults
+ * (page actions, git-derived dates), so they need no warning.
+ */
+const droppedChromeWarnings = (
+  spec: Record<string, unknown>,
+  config: BlumeConfig
+): string[] => {
+  const warnings: string[] = [];
+  const navbar = asRecord(spec.navbar);
+  if (navbar && (navbar.links || navbar.primary)) {
+    warnings.push(
+      "Header links (navbar.links/navbar.primary) have no blume.config equivalent and were dropped; re-add them with navigation.tabs or a Header layout override."
+    );
+  }
+  if (asRecord(spec.footer)?.socials) {
+    warnings.push(
+      "Footer social links (footer.socials) have no blume.config equivalent and were dropped; add them with a Footer layout override."
+    );
+  }
+  if (hasFontFamily(spec.fonts ?? spec.font) && !config.theme?.fonts) {
+    warnings.push(
+      "docs.json font family isn't in Blume's curated Google Fonts set; set theme.fonts to a supported slug or add @font-face rules in theme.css."
+    );
+  }
+  return warnings;
+};
+
 /** Recursively drop `undefined`, empty arrays, and empty objects. */
 const prune = (value: unknown): unknown => {
   if (Array.isArray(value)) {
@@ -190,6 +240,13 @@ export const migrateMintlifyProject = async (
         `Mapped ${i18n.locales.length} languages to i18n.locales (default: ${i18n.defaultLocale}); review the locale labels.`
       );
     }
+    const openapiSources = config.openapi?.sources ?? [];
+    if (openapiSources.length > 0) {
+      warnings.push(
+        `Mapped ${openapiSources.length} OpenAPI spec source(s) to openapi.sources (native reference renderer); verify each spec path or URL resolves.`
+      );
+    }
+    warnings.push(...droppedChromeWarnings(spec, config));
   } else {
     warnings.push("No docs.json or mint.json found; writing a default config.");
     config = { content: { root: "." }, title: "Documentation" };
@@ -263,7 +320,7 @@ export const migrateMintlifyProject = async (
   }
   if (unsupported.size > 0) {
     warnings.push(
-      `Components without a Blume equivalent need manual review (use the OpenAPI reference instead): ${[...unsupported].join(", ")}.`
+      `Components without a Blume equivalent need manual review: ${[...unsupported].join(", ")}.`
     );
   }
   warnings.push(

package/src/openapi/model.ts

@@ -0,0 +1,174 @@
+import type {
+  Document,
+  OperationObject,
+  PathItemObject,
+} from "@scalar/openapi-types/3.1";
+
+/**
+ * Blume's own OpenAPI model. Specs are parsed and upgraded to 3.1 (see
+ * `parse.ts`) with internal `$ref`s left intact — the document stays
+ * JSON-serializable (a fully dereferenced graph can be circular), and the schema
+ * components resolve refs against `document.components.schemas` at render time.
+ * Each operation is flattened into an {@link ApiOperationRef} with a real,
+ * per-operation route so it becomes a first-class Blume page.
+ */
+
+/** A normalized OpenAPI 3.1 document, internal `$ref`s intact. */
+export type ApiDocument = Document;
+
+const NON_SLUG = /[^a-z0-9]+/gu;
+const SLUG_EDGES = /^-+|-+$/gu;
+
+/** Lowercase, URL-safe slug: `Add a Pet!` -> `add-a-pet`. */
+export const slugify = (text: string): string =>
+  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+
+/** The HTTP methods an OpenAPI path item may declare, in spec order. */
+export const HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+] as const;
+
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+
+/** Group used for operations that declare no tag. */
+const UNTAGGED = "Operations";
+
+/** A stable, URL-safe key for an operation: its `operationId`, else method+path. */
+export const operationKey = (
+  method: string,
+  path: string,
+  operationId?: string
+): string => {
+  const fromId = operationId ? slugify(operationId) : "";
+  return fromId || slugify(`${method}-${path}`);
+};
+
+/** One operation, flattened out of the paths object and mapped to a route. */
+export interface ApiOperationRef {
+  /** Stable key, unique within a spec; matches the MDX `<Operation id>`. */
+  key: string;
+  method: HttpMethod;
+  /** Templated path, e.g. `/pets/{id}`. */
+  path: string;
+  /** Full site route for this operation's page, e.g. `/reference/pet/add-pet`. */
+  route: string;
+  /** Display tag name (first tag, or `Operations` when untagged). */
+  tag: string;
+  tagSlug: string;
+  summary: string;
+  description: string;
+  operationId?: string;
+  deprecated: boolean;
+}
+
+/** A tag/section, in first-seen order. */
+export interface ApiTagRef {
+  slug: string;
+  name: string;
+  description: string;
+}
+
+/** Everything the runtime needs for one spec, serialized into `blume:openapi`. */
+export interface ApiSpecData {
+  /** Unique token used as the `<Operation source>` and the data-module key. */
+  slug: string;
+  /** Base route the spec's operations hang off, e.g. `/reference`. */
+  route: string;
+  label: string;
+  title: string;
+  version: string;
+  description: string;
+  document: ApiDocument;
+  /** Operations keyed by {@link ApiOperationRef.key}. */
+  operations: Record<string, ApiOperationRef>;
+  tags: ApiTagRef[];
+  /** Code-sample languages to render per operation. */
+  codeSamples: string[];
+  /** Whether nested schema rows start expanded. */
+  expandSchemas: boolean;
+}
+
+/** The generated `blume:openapi` module: specs keyed by {@link ApiSpecData.slug}. */
+export type OpenApiData = Record<string, ApiSpecData>;
+
+const isOperation = (value: unknown): value is OperationObject =>
+  typeof value === "object" && value !== null;
+
+/**
+ * Flatten a 3.1 document into a route-mapped operation list and its ordered
+ * tags. Operations inherit the first tag they declare; keys are de-duplicated so
+ * a repeated `operationId` still yields distinct routes.
+ */
+export const extractOperations = (
+  document: ApiDocument,
+  baseRoute: string
+): { operations: ApiOperationRef[]; tags: ApiTagRef[] } => {
+  const operations: ApiOperationRef[] = [];
+  const tagOrder: string[] = [];
+  const tagMeta = new Map(
+    (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
+  );
+  const seen = new Set<string>();
+
+  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
+    const item = rawItem as PathItemObject | undefined;
+    if (!item || "$ref" in item) {
+      continue;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      if (!isOperation(operation)) {
+        continue;
+      }
+      const tag = operation.tags?.[0] ?? UNTAGGED;
+      const tagSlug = slugify(tag) || "operations";
+      if (!tagOrder.includes(tag)) {
+        tagOrder.push(tag);
+      }
+      let key = operationKey(method, path, operation.operationId);
+      while (seen.has(key)) {
+        key = `${key}-${method}`;
+      }
+      seen.add(key);
+      operations.push({
+        deprecated: operation.deprecated ?? false,
+        description: operation.description ?? "",
+        key,
+        method,
+        operationId: operation.operationId,
+        path,
+        route: `${baseRoute}/${tagSlug}/${key}`,
+        summary: operation.summary ?? "",
+        tag,
+        tagSlug,
+      });
+    }
+  }
+
+  const tags: ApiTagRef[] = tagOrder.map((name) => ({
+    description: tagMeta.get(name) ?? "",
+    name,
+    slug: slugify(name) || "operations",
+  }));
+
+  return { operations, tags };
+};
+
+/** Resolve the operation object for a ref out of its document. */
+export const operationObject = (
+  spec: ApiSpecData,
+  ref: ApiOperationRef
+): OperationObject | undefined => {
+  const item = (spec.document.paths?.[ref.path] ?? undefined) as
+    | PathItemObject
+    | undefined;
+  const operation = item?.[ref.method];
+  return isOperation(operation) ? operation : undefined;
+};

package/src/openapi/parse.ts

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+
+import { normalize, upgrade } from "@scalar/openapi-parser";
+import { isAbsolute, join } from "pathe";
+
+import type { ApiDocument } from "./model.ts";
+
+/**
+ * Spec loading and normalization. Blume reuses Scalar's parser
+ * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
+ * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
+ * Internal `$ref`s are deliberately left in place (see `model.ts`).
+ */
+
+const URL_SPEC = /^https?:\/\//u;
+
+export interface ParsedSpec {
+  document: ApiDocument;
+  warnings: string[];
+}
+
+/** Read a spec's raw text from an `http(s)` URL or a local (project-relative) path. */
+const readSpecText = async (spec: string, root: string): Promise<string> => {
+  if (URL_SPEC.test(spec)) {
+    const response = await fetch(spec);
+    if (!response.ok) {
+      throw new Error(`${spec} -> ${response.status} ${response.statusText}`);
+    }
+    return await response.text();
+  }
+  const absolute = isAbsolute(spec) ? spec : join(root, spec);
+  return await readFile(absolute, "utf-8");
+};
+
+/**
+ * Read, normalize, and upgrade a spec to an OpenAPI 3.1 document. Throws when the
+ * spec can't be read; callers turn that into a source diagnostic rather than a
+ * hard failure so a broken spec doesn't take down the whole build.
+ */
+export const parseSpec = async (
+  spec: string,
+  root: string
+): Promise<ParsedSpec> => {
+  const text = await readSpecText(spec, root);
+  const normalized = normalize(text);
+  const { specification } = upgrade(normalized);
+  return { document: specification as ApiDocument, warnings: [] };
+};

package/src/openapi/references.ts

@@ -0,0 +1,164 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { NavTab } from "../core/types.ts";
+
+/**
+ * Pure resolution of the configured API reference blocks into concrete routes,
+ * labels, and a renderer choice — no file IO, so the content source, the nav
+ * tabs, the Scalar page generator, and the `blume:openapi` data module all share
+ * one source of truth. Kept free of any Astro/template imports so `core` can
+ * depend on it without a cycle.
+ */
+
+export type ReferenceKind = "openapi" | "asyncapi";
+
+/** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
+export type ReferenceRenderer = "blume" | "scalar";
+
+/** Per-block display options for the Blume renderer. */
+export interface ReferenceDisplay {
+  /** Code-sample languages shown per operation. */
+  codeSamples: string[];
+  /** Whether nested schema rows start expanded. */
+  expandSchemas: boolean;
+}
+
+/** A spec source resolved to a concrete route, label, and renderer. */
+export interface ReferenceSource {
+  kind: ReferenceKind;
+  renderer: ReferenceRenderer;
+  /** Unique token derived from the route; the `<Operation source>` / data key. */
+  slug: string;
+  /** Normalized route the reference mounts at, e.g. `/reference`. */
+  route: string;
+  label: string;
+  /** Local path or `http(s)` URL, verbatim from config. */
+  spec: string;
+  /** Per-block Scalar theme name override, if any (Scalar renderer only). */
+  theme?: string;
+  /** Display options carried through to the Blume renderer. */
+  display: ReferenceDisplay;
+}
+
+const NON_SLUG = /[^a-z0-9]+/gu;
+const SLUG_EDGES = /^-+|-+$/gu;
+const ROUTE_EDGES = /^\/+|\/+$/gu;
+const TRAILING_SLASH = /\/+$/u;
+
+export const slugify = (text: string): string =>
+  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+
+/** Normalize a configured route to a single leading slash, no trailing slash. */
+export const normalizeRoute = (route: string): string => {
+  const trimmed = route.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
+  return noTrailing === "" ? "/" : noTrailing;
+};
+
+/** A stable per-reference token from its route: `/api/events` -> `api-events`. */
+const routeSlug = (route: string): string =>
+  slugify(route.replace(ROUTE_EDGES, "")) || "reference";
+
+type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
+
+/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
+const sourcesOf = (
+  block: Block
+): { label?: string; route?: string; spec: string }[] => {
+  const sources = [...block.sources];
+  if (block.spec) {
+    sources.unshift({ spec: block.spec });
+  }
+  return sources;
+};
+
+const referencesFor = (
+  kind: ReferenceKind,
+  block: Block,
+  defaultLabel: string,
+  renderer: ReferenceRenderer,
+  display: ReferenceDisplay
+): ReferenceSource[] => {
+  if (!block.enabled) {
+    return [];
+  }
+  const sources = sourcesOf(block);
+  const base = normalizeRoute(block.route);
+
+  return sources.map((source, index) => {
+    const label =
+      source.label ??
+      (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
+
+    let route: string;
+    if (source.route) {
+      route = normalizeRoute(source.route);
+    } else if (sources.length === 1) {
+      route = base;
+    } else {
+      const suffix = source.label ? slugify(source.label) : "";
+      route = normalizeRoute(`${base}/${suffix || index + 1}`);
+    }
+
+    return {
+      display,
+      kind,
+      label,
+      renderer,
+      route,
+      slug: routeSlug(route),
+      spec: source.spec,
+      theme: block.theme,
+    };
+  });
+};
+
+const NO_DISPLAY: ReferenceDisplay = { codeSamples: [], expandSchemas: false };
+
+/**
+ * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
+ * by default); AsyncAPI is always rendered by Scalar for now.
+ */
+export const resolveReferences = (
+  config: ResolvedConfig
+): ReferenceSource[] => [
+  ...referencesFor(
+    "openapi",
+    config.openapi,
+    "API Reference",
+    config.openapi.renderer,
+    {
+      codeSamples: config.openapi.codeSamples,
+      expandSchemas: config.openapi.expandSchemas,
+    }
+  ),
+  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY),
+];
+
+/** Nav tabs (header links) for every reference, regardless of renderer. */
+export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
+  resolveReferences(config).map((ref) => ({
+    label: ref.label,
+    path: ref.route,
+  }));
+
+/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
+  const seen = new Set<string>();
+  const result: ReferenceSource[] = [];
+  for (const ref of resolveReferences(config)) {
+    if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+      continue;
+    }
+    if (seen.has(ref.route)) {
+      continue;
+    }
+    seen.add(ref.route);
+    result.push(ref);
+  }
+  return result;
+};
+
+/** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
+export const hasScalarReferences = (config: ResolvedConfig): boolean =>
+  resolveReferences(config).some((ref) => ref.renderer === "scalar");