blume 2.0.2 → 2.1.0

package/src/openapi/overlay.ts

@@ -0,0 +1,256 @@
+import { exec, query } from "jsonpath-rfc9535";
+import { z } from "zod";
+
+import type { JsonValue } from "../core/adapter.ts";
+
+/**
+ * OpenAPI Overlays: the OpenAPI Initiative's format for changing an API
+ * description without editing it — an ordered list of actions, each an RFC
+ * 9535 JSONPath `target` with an `update` to merge in, a `copy` of another
+ * node to merge in, or `remove`. A spec generated by another tool or owned by
+ * another team can then carry docs-only changes (better descriptions, hidden
+ * internal operations, a public server URL) in a file of its own.
+ *
+ * Implements Overlay Specification 1.0 and 1.1 over `jsonpath-rfc9535`, which
+ * passes the JSONPath compliance suite in full, as the spec requires. The
+ * documents here are already parsed; `parse.ts` reads the files.
+ */
+
+/** An overlay document or action that doesn't follow the spec. */
+export class OverlayError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OverlayError";
+  }
+}
+
+/** An object node, the only kind that holds named properties. */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** A node that holds other nodes: where a match's parent can be. */
+type JsonContainer = JsonObject | JsonValue[];
+
+const isObject = (value: JsonValue | undefined): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * A parsed YAML or JSON mapping, as the document an overlay acts on: the
+ * parser's own types say nothing of JSON, but what it parses is JSON.
+ */
+export const isJsonObject = <Value>(
+  value: Value
+): value is Value & JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isContainer = (value: JsonValue | undefined): value is JsonContainer =>
+  typeof value === "object" && value !== null;
+
+const isIndex = (key: string | number | undefined): key is number =>
+  typeof key === "number";
+
+/** An object, an array, or anything else: what update merging keys on. */
+type MergeKind = "array" | "object" | "primitive";
+
+const mergeKindOf = (value: JsonValue): MergeKind => {
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return isObject(value) ? "object" : "primitive";
+};
+
+/** A merge kind in a sentence. */
+const MERGE_KIND_PHRASE: Record<MergeKind, string> = {
+  array: "an array",
+  object: "an object",
+  primitive: "a primitive value",
+};
+
+const actionSchema = z.looseObject({
+  /** A JSONPath expression selecting one node to merge into the targets (1.1). */
+  copy: z.string().optional(),
+  description: z.string().optional(),
+  /** Remove every target from the map or array it's in. */
+  remove: z.boolean().default(false),
+  /** An RFC 9535 JSONPath expression selecting the nodes to act on. */
+  target: z.string().min(1),
+  /** A value merged into every target. */
+  update: z.json().optional(),
+});
+
+/** A validated overlay action. */
+type OverlayAction = z.output<typeof actionSchema>;
+
+const overlaySchema = z.looseObject({
+  actions: z.array(actionSchema).min(1),
+  extends: z.string().optional(),
+  info: z.looseObject({ title: z.string(), version: z.string() }),
+  overlay: z.string().regex(/^1\.[01]\.\d+$/u, {
+    message: "must be an Overlay Specification version, 1.0.x or 1.1.x",
+  }),
+});
+
+/** A validated overlay document. */
+export type OverlayDocument = z.output<typeof overlaySchema>;
+
+/** Validate a parsed overlay document, naming the file in any error. */
+export const overlayDocument = <Value>(
+  value: Value,
+  name: string
+): OverlayDocument => {
+  const parsed = overlaySchema.safeParse(value);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  const [issue] = parsed.error.issues;
+  const at = issue?.path.length ? `\`${issue.path.join(".")}\` ` : "";
+  throw new OverlayError(
+    `${name} is not an overlay document: ${at}${issue?.message ?? "invalid"}.`
+  );
+};
+
+/** A matched node, where it sits, and how to reach it. */
+interface Match {
+  key?: string | number;
+  parent?: JsonContainer;
+  value: JsonValue;
+}
+
+/** The nodes `expression` selects, each with its parent (none for the root). */
+const select = (document: JsonValue, expression: string): Match[] => {
+  const matches: Match[] = [];
+  exec(document, expression, (value, path) => {
+    let parent: JsonValue = document;
+    for (const key of path.slice(0, -1)) {
+      // SAFETY: the path is one the query walked, so every step is a key of
+      // the container before it.
+      parent = (parent as Record<string | number, JsonValue>)[key] ?? null;
+    }
+    const key = path.at(-1);
+    matches.push(
+      key === undefined || !isContainer(parent)
+        ? { value }
+        : { key, parent, value }
+    );
+  });
+  return matches;
+};
+
+/**
+ * Merge `patch` into `target` as the spec says: objects recursively, arrays
+ * by concatenation, a primitive replaced by a primitive. Returns the merged
+ * value; any other pairing throws.
+ */
+const merge = (target: JsonValue, patch: JsonValue, at: string): JsonValue => {
+  if (isObject(target) && isObject(patch)) {
+    for (const [key, value] of Object.entries(patch)) {
+      // Only recurse into the target's own keys, so a `__proto__` or
+      // `constructor` key can't reach a prototype.
+      target[key] = Object.hasOwn(target, key)
+        ? merge(target[key] ?? null, value, `${at}.${key}`)
+        : structuredClone(value);
+    }
+    return target;
+  }
+  if (Array.isArray(target) && Array.isArray(patch)) {
+    target.push(...structuredClone(patch));
+    return target;
+  }
+  if (
+    mergeKindOf(target) === "primitive" &&
+    mergeKindOf(patch) === "primitive"
+  ) {
+    return patch;
+  }
+  throw new OverlayError(
+    `can't merge ${MERGE_KIND_PHRASE[mergeKindOf(patch)]} into ${MERGE_KIND_PHRASE[mergeKindOf(target)]} at ${at}`
+  );
+};
+
+/** Remove each match from its container, later siblings first. */
+const removeAll = (matches: Match[]): void => {
+  for (const { key, parent } of matches.toReversed()) {
+    if (Array.isArray(parent) && isIndex(key)) {
+      parent.splice(key, 1);
+    } else if (isObject(parent) && key !== undefined && !isIndex(key)) {
+      // oxlint-disable-next-line typescript/no-dynamic-delete -- an overlay target's key is only known at run time
+      delete parent[key];
+    } else {
+      throw new OverlayError("can't remove the document itself");
+    }
+  }
+};
+
+/**
+ * Merge `patch` into every match, which must all be objects, all arrays, or
+ * all primitives. A primitive match is replaced in its parent.
+ */
+const mergeAll = (matches: Match[], patch: JsonValue, target: string) => {
+  const kinds = new Set(matches.map((match) => mergeKindOf(match.value)));
+  if (kinds.size > 1) {
+    throw new OverlayError(
+      `its target selects a mix of ${[...kinds].toSorted().join(", ")} values, and an update needs all one kind`
+    );
+  }
+  for (const { key, parent, value } of matches) {
+    const merged = merge(value, patch, target);
+    if (merged !== value && parent !== undefined && key !== undefined) {
+      // SAFETY: `key` came from walking `parent`, so it indexes it.
+      (parent as Record<string | number, JsonValue>)[key] = merged;
+    }
+  }
+};
+
+/** The single node a `copy` expression selects, cloned. */
+const copied = (document: JsonValue, expression: string): JsonValue => {
+  const values = query(document, expression);
+  const [value] = values;
+  if (values.length !== 1 || value === undefined) {
+    throw new OverlayError(
+      `its copy expression "${expression}" selects ${values.length} nodes, and copy needs exactly one`
+    );
+  }
+  return structuredClone(value);
+};
+
+const applyAction = (document: JsonValue, action: OverlayAction): void => {
+  const matches = select(document, action.target);
+  if (matches.length === 0) {
+    return;
+  }
+  if (action.remove) {
+    removeAll(matches);
+    return;
+  }
+  const patch =
+    action.update ??
+    (action.copy === undefined ? undefined : copied(document, action.copy));
+  if (patch !== undefined) {
+    mergeAll(matches, patch, action.target);
+  }
+};
+
+/**
+ * Apply an overlay to a parsed document, in place and in action order: each
+ * action sees the result of the one before. A target that matches nothing
+ * changes nothing. Throws an {@link OverlayError} naming the overlay file and
+ * the action that failed.
+ */
+export const applyOverlay = (
+  document: JsonValue,
+  overlay: OverlayDocument,
+  name: string
+): void => {
+  for (const [index, action] of overlay.actions.entries()) {
+    try {
+      applyAction(document, action);
+    } catch (error) {
+      // SAFETY: the JSONPath parser and this module throw Error instances.
+      const { message } = error as Error;
+      throw new OverlayError(
+        `${name} action ${index + 1} (${action.target}): ${message}`
+      );
+    }
+  }
+};

package/src/openapi/parse.ts

@@ -18,6 +18,7 @@ import { normalizeAsyncApiDocument } from "./asyncapi.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
+import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
@@ -75,6 +76,11 @@ export class InvalidSpecError extends Error {
 
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
+  /**
+   * Overlay documents (local paths or `http(s)` URLs) applied in order to
+   * the parsed spec, before it's upgraded. See `overlay.ts`.
+   */
+  overlays?: readonly string[];
   /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
   cacheDir?: string;
   /**
@@ -310,13 +316,60 @@ const readSpecText = async (
 const isApiDocument = <Value>(value: Value): value is Value & ApiDocument =>
   typeof value === "object" && value !== null;
 
+/**
+ * Read a spec and apply its overlays, in order, to the parsed document as
+ * written (before any upgrade: an overlay targets its spec's own version).
+ * The overlays are read like the spec, local or remote, cached alike.
+ */
+const readOverlaid = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ document: ReturnType<typeof normalize>; warnings: string[] }> => {
+  const [read, ...overlays] = await Promise.all(
+    [spec, ...(options.overlays ?? [])].map((path) =>
+      readSpecText(path, root, options)
+    )
+  );
+  const document = normalize(read?.text ?? "");
+  for (const [index, overlay] of overlays.entries()) {
+    const name = options.overlays?.[index] ?? "";
+    const parsed = overlayDocument(normalize(overlay.text), name);
+    // A spec that isn't a mapping has nothing to overlay; the caller
+    // rejects it as it would without overlays.
+    if (isJsonObject(document)) {
+      applyOverlay(document, parsed, name);
+    }
+  }
+  return {
+    document,
+    warnings: [read, ...overlays].flatMap((entry) => entry?.warnings ?? []),
+  };
+};
+
+/**
+ * A spec with its overlays applied, as JSON text: what the Scalar embed
+ * inlines, since it can't apply overlays itself.
+ */
+export const readOverlaidSpec = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ text: string; warnings: string[] }> => {
+  const { document, warnings } = await readOverlaid(spec, root, options);
+  return { text: JSON.stringify(document), warnings };
+};
+
 export const parseSpec = async (
   spec: string,
   root: string,
   options: SpecFetchOptions = {}
 ): Promise<ParsedSpec> => {
-  const { text, warnings } = await readSpecText(spec, root, options);
-  const normalized = normalize(text);
+  const { document: normalized, warnings } = await readOverlaid(
+    spec,
+    root,
+    options
+  );
   const { specification } = upgrade(normalized);
   // Reject a non-mapping here so the renderer never sees a non-document.
   if (!isApiDocument(specification)) {

package/src/openapi/proxy.ts

@@ -12,25 +12,52 @@
  * network and stays safe to bundle into the generated endpoint file.
  */
 
+import { PROXY_HEADERS_HEADER } from "../components/openapi/request.ts";
 import { readCappedBody } from "../core/request-body.ts";
 
 /**
- * Request headers never forwarded upstream: hop-by-hop headers describe this
- * connection (not the upstream one), `host`/`origin`/`referer` would leak or
- * misattribute the docs site, and `cookie` would forward reader credentials
- * to an arbitrary target. `accept-encoding`/`content-length` are recomputed
- * by the runtime's own fetch.
+ * Request headers never forwarded upstream, even when the playground names
+ * them: hop-by-hop headers describe this connection (not the upstream one),
+ * `host`/`origin`/`referer` would leak or misattribute the docs site, `cookie`
+ * would forward reader credentials to an arbitrary target, and the rest are
+ * set or rewritten by the platform in front of the docs server — the
+ * reader's address, the edge's own identity — whatever the browser sent.
+ * `accept-encoding`/`content-length` are recomputed by the runtime's own
+ * fetch.
  */
 const REQUEST_DROP = {
   "accept-encoding": true,
+  "cdn-loop": true,
   connection: true,
   "content-length": true,
   cookie: true,
+  forwarded: true,
   host: true,
+  "keep-alive": true,
   origin: true,
+  "proxy-authorization": true,
   referer: true,
+  te: true,
+  trailer: true,
+  "transfer-encoding": true,
+  "true-client-ip": true,
+  upgrade: true,
+  via: true,
+  "x-client-ip": true,
+  "x-real-ip": true,
 } satisfies Record<string, true>;
 
+/**
+ * Platform header families, dropped like {@link REQUEST_DROP}: Cloudflare's
+ * (`cf-connecting-ip`, the Access `cf-access-jwt-assertion`), the
+ * `x-forwarded-*` set, Vercel's (`x-vercel-oidc-token`), Netlify's, Fly's,
+ * and AWS load balancers' (`x-amzn-oidc-data`).
+ */
+const PLATFORM_HEADER = /^(?:cf-|x-forwarded-|x-vercel-|x-nf-|fly-|x-amzn-)/u;
+
+/** The {@link PROXY_HEADERS_HEADER} name as `Headers` iterates it. */
+const DECLARED = PROXY_HEADERS_HEADER.toLowerCase();
+
 /**
  * Upstream response headers never returned to the browser: the runtime's
  * fetch already decoded the body (so `content-encoding`/`content-length` no
@@ -99,20 +126,45 @@ const DOCUMENT_TYPE =
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
 
-/** Copy headers, skipping the given denylist (names are already lowercase). */
+/**
+ * Copy headers, skipping the given denylist and any name `keep` rejects
+ * (names are already lowercase).
+ */
 const filterHeaders = (
   source: Headers,
-  drop: Record<string, true>
+  drop: Record<string, true>,
+  keep: (name: string) => boolean = () => true
 ): Headers => {
   const headers = new Headers();
   for (const [name, value] of source) {
-    if (!drop[name]) {
+    if (!drop[name] && keep(name)) {
       headers.set(name, value);
     }
   }
   return headers;
 };
 
+/**
+ * The headers to send upstream: only those the playground set itself, which
+ * it names in {@link PROXY_HEADERS_HEADER}. Forwarding everything else minus
+ * a denylist would hand the documented API whatever the browser and the
+ * platform attach on their own — the HTTP Basic credentials of a docs site
+ * behind a password (a same-origin fetch with no `Authorization` of its own
+ * carries them), a Cloudflare Access assertion, a Vercel OIDC token.
+ */
+const forwardedHeaders = (source: Headers): Headers => {
+  const named = new Set(
+    (source.get(DECLARED) ?? "")
+      .split(",")
+      .map((name) => name.trim().toLowerCase())
+  );
+  return filterHeaders(
+    source,
+    REQUEST_DROP,
+    (name) => named.has(name) && !PLATFORM_HEADER.test(name)
+  );
+};
+
 /** A 403 for a target no configured spec declares as one of its servers. */
 const forbidden = (origin: string): Response =>
   Response.json(
@@ -186,7 +238,8 @@ const followUpstream = async (args: {
 /**
  * Build the `/_api-proxy` fetch handler. The client sends its REAL method,
  * headers, and body to `?url=<encodeURIComponent(target)>`; the handler
- * forwards them (minus {@link REQUEST_DROP}) and mirrors the upstream response
+ * forwards the method, the body, and the headers the client names (see
+ * {@link forwardedHeaders}), and mirrors the upstream response
  * (minus {@link RESPONSE_DROP}) with an `x-blume-proxy` marker. An unreachable
  * upstream is a 502 with a JSON `error`.
  *
@@ -252,7 +305,7 @@ export const createPlaygroundProxyHandler = (
         allowed,
         body,
         fetchImpl,
-        headers: filterHeaders(request.headers, REQUEST_DROP),
+        headers: forwardedHeaders(request.headers),
         hop: 0,
         method: request.method,
         signal: AbortSignal.timeout(timeoutMs),

package/src/openapi/references.ts

@@ -28,8 +28,8 @@ export type BlumeReferenceKind = Exclude<ReferenceKind, "scalar">;
 
 /** Per-adapter display options for the Blume renderer. */
 export interface ReferenceDisplay {
-  /** Code-sample languages shown per operation. */
-  codeSamples: string[];
+  /** Code-sample languages shown per operation; `false` for none. */
+  codeSamples: string[] | false;
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
   /**
@@ -67,6 +67,11 @@ export interface ReferenceSource {
   seoDescriptionSuffix: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
+  /**
+   * OpenAPI Overlay documents applied to `spec` in order (`openapi()` and
+   * `scalar()` only).
+   */
+  overlays?: string[];
   /**
    * URL of the live GraphQL endpoint the playground and code samples target
    * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
@@ -184,6 +189,7 @@ interface SourceRow {
   route?: string;
   seoDescriptionSuffix: boolean;
   spec: string;
+  overlays?: string[];
 }
 
 /**
@@ -255,6 +261,9 @@ const referencesFor = (
     if (source.endpoint !== undefined) {
       reference.endpoint = source.endpoint;
     }
+    if (source.overlays !== undefined) {
+      reference.overlays = source.overlays;
+    }
     return reference;
   });
 };
@@ -363,11 +372,18 @@ export const builtinProxyReferences = (
       ref.display.playground.proxy === true
   );
 
+/**
+ * Whether hand-written endpoint pages (`api` frontmatter) send their Try it
+ * requests through the built-in proxy: `api.playground.proxy: true`.
+ */
+export const apiPagesUseBuiltinProxy = (config: ResolvedConfig): boolean =>
+  config.api.playground.enabled && config.api.playground.proxy === true;
+
 /**
  * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
  * generated: some Blume-rendered reference's playground opted into it with
- * `proxy: true`. Shared by the server feature gate and the generator so the
- * two can never disagree.
+ * `proxy: true`, or the hand-written endpoint pages' did. Shared by the server
+ * feature gate and the generator so the two can never disagree.
  */
 export const needsPlaygroundProxy = (config: ResolvedConfig): boolean =>
-  builtinProxyReferences(config).length > 0;
+  builtinProxyReferences(config).length > 0 || apiPagesUseBuiltinProxy(config);

package/src/openapi/render-mdx.ts

@@ -126,6 +126,45 @@ const mdxSafe = (text: string): string => {
   return out + escapeProse(text.slice(cursor));
 };
 
+// A fence opener: up to three columns of indentation, then a run of three or
+// more backticks or tildes.
+const FENCE_OPEN = /^ {0,3}(?<fence>`{3,}|~{3,})/u;
+
+/**
+ * Close a fenced code block the text leaves open. An unclosed fence runs to
+ * the end of the document, so the component appended after a description
+ * would render as code, and the page would lose its parameters, responses,
+ * and playground. Only the last top-level block can run that far — a fence in
+ * a quote or list closes with its container — and it's read from the same
+ * `<`-masked parse as `mdxSafe`, since the emitted MDX has no HTML blocks to
+ * hide a fence in.
+ */
+const closeOpenFence = (text: string): string => {
+  const last = fromMarkdown(text.replaceAll("<", HTML_MASK)).children.at(-1);
+  if (last?.type !== "code") {
+    return text;
+  }
+  // fromMarkdown always stamps positions; 0 is an unreachable guard.
+  const block = text.slice(last.position?.start.offset ?? 0);
+  const fence = FENCE_OPEN.exec(block)?.groups?.fence;
+  // No fence: indented code, which MDX reads as a paragraph.
+  if (!fence) {
+    return text;
+  }
+  const lines = block.split("\n");
+  const closer = new RegExp(
+    `^ {0,3}${fence[0]}{${fence.length},}[ \\t\\r]*$`,
+    "u"
+  );
+  return lines.length > 1 && closer.test(lines.at(-1) ?? "")
+    ? text
+    : `${text}\n${fence}`;
+};
+
+/** Spec prose as MDX that is safe to follow with a component. */
+const descriptionMdx = (text: string): string =>
+  mdxSafe(closeOpenFence(text.trim()));
+
 /**
  * Frontmatter emitted for one operation or overview page. Boolean flags are
  * assigned only when set, so absent keys stay absent in the staged MDX.
@@ -231,7 +270,8 @@ const operationDescription = (
     // method (see `extractGraphqlOperations`).
     subject = `${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]}`;
   } else {
-    subject = `${operation.method.toUpperCase()} ${operation.path} endpoint`;
+    // A webhook is a request the API sends, named rather than pathed.
+    subject = `${operation.method.toUpperCase()} ${operation.path} ${operation.webhook ? "webhook" : "endpoint"}`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
   // Room for the joining space and the period `asSentence` may add, so a
@@ -249,7 +289,7 @@ const operationDescription = (
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
-    ? `${mdxSafe(description.trim())}\n\n${component}`
+    ? `${descriptionMdx(description)}\n\n${component}`
     : component;
 
 export const operationMdx = (
@@ -309,6 +349,9 @@ export const operationMdx = (
     sidebar.badge = method;
   }
   const tags = graphql ? [operation.tag] : [operation.tag, method];
+  if (operation.webhook) {
+    tags.push("Webhook");
+  }
   return {
     body: withDescription(
       description,
@@ -365,7 +408,7 @@ export const overviewMdx = (
       continue;
     }
     const description = tag.description.trim()
-      ? [mdxSafe(tag.description.trim())]
+      ? [descriptionMdx(tag.description)]
       : [];
     tagSections.push(
       [

package/src/openapi/scalar.ts

@@ -6,6 +6,7 @@ import { scalarReferenceTemplate } from "../astro/templates.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
 import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+import { readOverlaidSpec } from "./parse.ts";
 import { resolveReferences } from "./references.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -53,14 +54,44 @@ const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   };
 };
 
+/** A source's Scalar spec config, or none when its overlays failed. */
+interface SpecConfiguration {
+  config?: { content: string } | { url: string };
+  warning?: string;
+}
+
+/**
+ * The spec with its overlays applied, inlined: Scalar can't apply overlays
+ * itself. A failed overlay skips the page rather than embed the spec without
+ * it, since an overlay is often what hides the internal operations.
+ */
+const overlaidConfiguration = async (
+  ref: ReferenceSource,
+  root: string
+): Promise<SpecConfiguration> => {
+  try {
+    const { text, warnings } = await readOverlaidSpec(ref.spec, root, {
+      overlays: ref.overlays,
+    });
+    return { config: { content: text }, warning: warnings[0] };
+  } catch (error) {
+    // SAFETY: reading, parsing, and overlaying throw Error instances.
+    const { message } = error as Error;
+    return {
+      warning: `API reference ${ref.route} was skipped: its overlays couldn't be applied to "${ref.spec}" (${message}).`,
+    };
+  }
+};
+
 /** Build the Scalar spec config for a source: inline `content` or remote `url`. */
 const specConfiguration = async (
-  spec: string,
+  ref: ReferenceSource,
   root: string
-): Promise<{
-  config: { content: string } | { url: string };
-  warning?: string;
-}> => {
+): Promise<SpecConfiguration> => {
+  const { spec } = ref;
+  if (ref.overlays?.length) {
+    return await overlaidConfiguration(ref, root);
+  }
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
@@ -133,7 +164,7 @@ export const buildReferenceFiles = async (options: {
   const built = await Promise.all(
     accepted.map(async (ref) => ({
       ref,
-      spec: await specConfiguration(ref.spec, root),
+      spec: await specConfiguration(ref, root),
     }))
   );
 
@@ -142,6 +173,9 @@ export const buildReferenceFiles = async (options: {
     if (spec.warning) {
       warnings.push(spec.warning);
     }
+    if (!spec.config) {
+      continue;
+    }
     const pagePath = referencePagePath(ref.route);
     // `theme` is the one option Blume maps (a named theme replaces the
     // accent/radius layering); every other `scalar()` option is forwarded