blume 2.0.3 → 2.1.0

package/src/ratelimit/cloudflare.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** The Worker binding Blume declares for the rate limiter. */
+export const RATE_LIMIT_BINDING = "BLUME_RATE_LIMIT";
+
+/** Options for {@link cloudflare}. */
+export interface CloudflareRateLimitOptions {
+  /**
+   * The rate limiting namespace, a positive integer unique in your
+   * Cloudflare account. Defaults to one derived from the site.
+   */
+  namespaceId?: string;
+  /** Requests each reader may make per window, per route. Defaults to 10. */
+  requests?: number;
+  /** The window, in seconds: Cloudflare allows 10 or 60. Defaults to 60. */
+  window?: 10 | 60;
+}
+
+export const cloudflareRateLimitOptionsSchema = z.strictObject({
+  namespaceId: z
+    .string()
+    .regex(/^[1-9]\d*$/u, "namespaceId is a positive integer, as a string.")
+    .optional(),
+  requests: z.number().int().positive().optional(),
+  window: z.union([z.literal(10), z.literal(60)]).optional(),
+});
+
+export type CloudflareRateLimitAdapter = AdapterDescriptor<
+  "cloudflare",
+  CloudflareRateLimitOptions
+>;
+
+export const cloudflareRateLimitAdapterSchema = adapterDescriptorSchema(
+  "cloudflare",
+  cloudflareRateLimitOptionsSchema
+);
+
+/**
+ * Counts with Cloudflare's Workers rate limiting, for a site deployed with
+ * `deployment: cloudflare()`: Blume declares the binding in the Worker's
+ * config, so there is nothing to set up. Cloudflare counts per location and
+ * allows a window of 10 or 60 seconds.
+ */
+export const cloudflare = (
+  options: CloudflareRateLimitOptions = {}
+): CloudflareRateLimitAdapter => ({
+  kind: "cloudflare",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/ratelimit/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Rate limiters for `blume.config.ts`. The server routes a reader can call —
+ * the assistant, the API playground proxy, and server-side search — limit
+ * each reader (by IP address) to a number of requests per window, answering
+ * `429 Too Many Requests` past it:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { upstash } from "blume/ratelimit";
+ *
+ * export default defineConfig({
+ *   rateLimit: upstash({ requests: 30, window: 600 }),
+ * });
+ * ```
+ *
+ * `memory()` is on by default; `rateLimit: false` turns limiting off. Each
+ * factory returns a plain descriptor (see `core/adapter.ts`), and the
+ * generated routes count with `runtime.ts`.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { cloudflare } from "./cloudflare.ts";
+export type {
+  CloudflareRateLimitAdapter,
+  CloudflareRateLimitOptions,
+} from "./cloudflare.ts";
+export { memory } from "./memory.ts";
+export type { MemoryAdapter, RateLimitOptions } from "./memory.ts";
+export type { RateLimitAdapter } from "./schema.ts";
+export { upstash } from "./upstash.ts";
+export type { UpstashAdapter } from "./upstash.ts";

package/src/ratelimit/memory.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** How many requests a reader gets per window, unless set. */
+export const DEFAULT_REQUESTS = 30;
+
+/** The window those requests are counted over, in seconds, unless set. */
+export const DEFAULT_WINDOW = 600;
+
+/** The limit every rate limiter takes: a count of requests per window. */
+export interface RateLimitOptions {
+  /** Requests each reader may make per window, per route. */
+  requests?: number;
+  /** The window, in seconds. */
+  window?: number;
+}
+
+export const rateLimitOptionsSchema = z.strictObject({
+  requests: z.number().int().positive().optional(),
+  window: z.number().int().positive().optional(),
+});
+
+export type MemoryAdapter = AdapterDescriptor<"memory", RateLimitOptions>;
+
+export const memoryAdapterSchema = adapterDescriptorSchema(
+  "memory",
+  rateLimitOptionsSchema
+);
+
+/**
+ * Counts each reader's requests in the server's own memory, the default. On
+ * a server that runs as one process (`node()`) the count is exact; on a
+ * platform that runs many short-lived instances (Vercel, Netlify,
+ * Cloudflare) each instance keeps its own, so it stops a burst from one
+ * reader rather than enforcing the limit exactly. For that, share the count
+ * with `upstash()` or `cloudflare()`.
+ */
+export const memory = (options: RateLimitOptions = {}): MemoryAdapter => ({
+  kind: "memory",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/ratelimit/runtime.ts

@@ -0,0 +1,229 @@
+/**
+ * The rate limit the generated server routes check before any work: the
+ * assistant (`/api/ask`), the API playground proxy (`/_api-proxy`), and
+ * server-side search. Each route builds one limiter at module scope from the
+ * configured adapter (`rateLimit` in `blume.config.ts`) and asks it about
+ * every request, keyed by the reader's IP address and the route, so each
+ * route has its own budget.
+ *
+ * A limiter never stands between a reader and the docs by accident: a
+ * request whose address the host can't tell is let through, and so is one
+ * the shared store fails to count (logged, not blocked). A shared store
+ * without its secrets or binding falls back to counting in memory.
+ */
+import { clientAddressOf } from "../core/client-address.ts";
+import type { ClientContext } from "../core/client-address.ts";
+import { RATE_LIMIT_BINDING } from "./cloudflare.ts";
+import { DEFAULT_REQUESTS, DEFAULT_WINDOW } from "./memory.ts";
+import type { RateLimitAdapter } from "./schema.ts";
+import { UPSTASH_SECRETS } from "./upstash.ts";
+
+/** What a limiter says about one request. */
+export interface RateLimitResult {
+  allowed: boolean;
+  /** Seconds until the reader's window resets. */
+  retryAfter: number;
+}
+
+/** Count one request against `key`. */
+export type Limiter = (key: string) => Promise<RateLimitResult>;
+
+/** A Workers rate limiting binding (`ratelimits` in the Worker's config). */
+export interface RateLimitBinding {
+  limit: (options: { key: string }) => Promise<{ success: boolean }>;
+}
+
+/** What a generated route hands the limiter from its runtime. */
+export interface LimiterRuntime {
+  /** The Worker's rate limiting binding, under `cloudflare()`. */
+  binding?: RateLimitBinding;
+  /** For tests; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** For tests; defaults to `Date.now`. */
+  now?: () => number;
+  /** Reads a secret (`getSecret` from `astro:env/server`). */
+  secret?: (name: string) => string | undefined;
+}
+
+/** Past this many tracked readers, a memory limiter drops expired ones. */
+const MEMORY_SWEEP_AT = 10_000;
+
+/** One reader's count in the current window. */
+interface MemoryEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Count in this server's memory, in fixed windows: each reader's first
+ * request opens a window, and the count resets when it ends.
+ */
+export const memoryLimiter = (
+  requests: number,
+  window: number,
+  now: () => number = Date.now
+): Limiter => {
+  const entries = new Map<string, MemoryEntry>();
+  return (key) => {
+    const time = now();
+    if (entries.size >= MEMORY_SWEEP_AT) {
+      for (const [tracked, entry] of entries) {
+        if (entry.resetAt <= time) {
+          entries.delete(tracked);
+        }
+      }
+    }
+    let entry = entries.get(key);
+    if (!entry || entry.resetAt <= time) {
+      entry = { count: 0, resetAt: time + window * 1000 };
+      entries.set(key, entry);
+    }
+    entry.count += 1;
+    return Promise.resolve({
+      allowed: entry.count <= requests,
+      retryAfter: Math.ceil((entry.resetAt - time) / 1000),
+    });
+  };
+};
+
+/** One command's reply from Upstash's REST pipeline. */
+interface UpstashReply {
+  error?: string;
+  result?: number | string | null;
+}
+
+/**
+ * Count in Upstash Redis over its REST API: one pipeline opens the window
+ * (`SET … EX … NX`), counts the request (`INCR`), and reads what's left of
+ * the window (`TTL`).
+ */
+export const upstashLimiter = (
+  requests: number,
+  window: number,
+  endpoint: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch
+): Limiter => {
+  const url = `${endpoint.replace(/\/+$/u, "")}/pipeline`;
+  return async (key) => {
+    const response = await fetchImpl(url, {
+      body: JSON.stringify([
+        ["SET", key, "0", "EX", String(window), "NX"],
+        ["INCR", key],
+        ["TTL", key],
+      ]),
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+      },
+      method: "POST",
+    });
+    if (!response.ok) {
+      throw new Error(`Upstash answered ${response.status}.`);
+    }
+    // SAFETY: Upstash's pipeline endpoint answers with one reply object per
+    // command, in order; a missing or failed reply reads as `NaN` below.
+    const replies = (await response.json()) as UpstashReply[];
+    const count = Number(replies[1]?.result ?? Number.NaN);
+    const ttl = Number(replies[2]?.result);
+    if (Number.isNaN(count)) {
+      throw new TypeError("Upstash sent no count.");
+    }
+    return { allowed: count <= requests, retryAfter: ttl > 0 ? ttl : window };
+  };
+};
+
+/** Count with a Workers rate limiting binding. */
+export const bindingLimiter =
+  (binding: RateLimitBinding, window: number): Limiter =>
+  async (key) => {
+    const { success } = await binding.limit({ key });
+    return { allowed: success, retryAfter: window };
+  };
+
+/** The limit an adapter sets, with Cloudflare's own defaults for its binding. */
+const limitOf = (adapter: RateLimitAdapter) =>
+  adapter.kind === "cloudflare"
+    ? {
+        requests: adapter.options.requests ?? 10,
+        window: adapter.options.window ?? 60,
+      }
+    : {
+        requests: adapter.options.requests ?? DEFAULT_REQUESTS,
+        window: adapter.options.window ?? DEFAULT_WINDOW,
+      };
+
+/**
+ * The limiter for the configured adapter, or `null` when rate limiting is
+ * off. A shared store missing its secrets or binding counts in memory and
+ * says so once.
+ */
+export const createLimiter = (
+  adapter: RateLimitAdapter | null,
+  runtime: LimiterRuntime = {}
+): Limiter | null => {
+  if (!adapter) {
+    return null;
+  }
+  const { requests, window } = limitOf(adapter);
+  if (adapter.kind === "cloudflare") {
+    if (runtime.binding) {
+      return bindingLimiter(runtime.binding, window);
+    }
+    console.warn(
+      `Rate limiting counts in memory: the Worker has no ${RATE_LIMIT_BINDING} binding.`
+    );
+  }
+  if (adapter.kind === "upstash") {
+    const [endpoint, token] = UPSTASH_SECRETS.map((name) =>
+      runtime.secret?.(name)
+    );
+    if (endpoint && token) {
+      return upstashLimiter(requests, window, endpoint, token, runtime.fetch);
+    }
+    console.warn(
+      `Rate limiting counts in memory: set ${UPSTASH_SECRETS.join(" and ")} to share the count through Upstash.`
+    );
+  }
+  return memoryLimiter(requests, window, runtime.now);
+};
+
+/** The slice of Astro's `APIContext` the check reads. */
+export type RateLimitContext = ClientContext;
+
+/**
+ * Count this request against the reader's budget for `scope` (the route).
+ * `null` to go ahead, or the `429 Too Many Requests` to return.
+ */
+export const rateLimited = async (
+  limiter: Limiter | null,
+  context: RateLimitContext,
+  scope: string
+): Promise<Response | null> => {
+  const address = limiter ? clientAddressOf(context) : undefined;
+  if (!(limiter && address)) {
+    return null;
+  }
+  // The host keeps two sites on one shared store apart.
+  const key = `blume:${new URL(context.request.url).host}:${scope}:${address}`;
+  let result: RateLimitResult;
+  try {
+    result = await limiter(key);
+  } catch (error) {
+    console.error("Rate limiting failed; letting the request through:", error);
+    return null;
+  }
+  if (result.allowed) {
+    return null;
+  }
+  return new Response(
+    `Too many requests: try again in ${result.retryAfter} seconds.`,
+    {
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "retry-after": String(result.retryAfter),
+      },
+      status: 429,
+    }
+  );
+};

package/src/ratelimit/schema.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+import { cloudflareRateLimitAdapterSchema } from "./cloudflare.ts";
+import { memory, memoryAdapterSchema } from "./memory.ts";
+import { upstashAdapterSchema } from "./upstash.ts";
+
+const ADAPTER_HINT =
+  'rateLimit takes one adapter — e.g. `rateLimit: upstash()` or `rateLimit: memory({ requests: 60 })`, imported from "blume/ratelimit" — or `false` to turn it off.';
+
+/** The configured rate limiter, as its factory returned it. */
+export const rateLimitAdapterSchema = z.discriminatedUnion("kind", [
+  cloudflareRateLimitAdapterSchema,
+  memoryAdapterSchema,
+  upstashAdapterSchema,
+]);
+
+export type RateLimitAdapter = z.output<typeof rateLimitAdapterSchema>;
+
+/**
+ * `blume.config.rateLimit`: how the server routes a reader can call (the
+ * assistant, the API playground proxy, server-side search) limit requests
+ * per reader. On by default with `memory()`; `false` turns it off (`null`
+ * once resolved).
+ */
+export const rateLimitConfigSchema = z
+  .union([z.literal(false), rateLimitAdapterSchema], { error: ADAPTER_HINT })
+  .optional()
+  .transform((adapter) => (adapter === false ? null : (adapter ?? memory())));

package/src/ratelimit/upstash.ts

@@ -0,0 +1,30 @@
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import { rateLimitOptionsSchema } from "./memory.ts";
+import type { RateLimitOptions } from "./memory.ts";
+
+/** The env vars holding the Upstash Redis REST endpoint and its token. */
+export const UPSTASH_SECRETS = [
+  "UPSTASH_REDIS_REST_URL",
+  "UPSTASH_REDIS_REST_TOKEN",
+] as const;
+
+export type UpstashAdapter = AdapterDescriptor<"upstash", RateLimitOptions>;
+
+export const upstashAdapterSchema = adapterDescriptorSchema(
+  "upstash",
+  rateLimitOptionsSchema
+);
+
+/**
+ * Keeps the count in Upstash Redis, which every instance on every host shares,
+ * so the limit holds exactly. It talks to Upstash's REST API, so there is
+ * nothing to install; the endpoint and token come from
+ * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`.
+ */
+export const upstash = (options: RateLimitOptions = {}): UpstashAdapter => ({
+  kind: "upstash",
+  options,
+  requiredSecrets: [...UPSTASH_SECRETS],
+  runtimeDeps: [],
+});

package/src/ratelimit/wrangler.ts

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+
+import type { JsonValue } from "../core/adapter.ts";
+import { isJsonObject } from "../core/sources/json.ts";
+import { RATE_LIMIT_BINDING } from "./cloudflare.ts";
+import type { CloudflareRateLimitAdapter } from "./cloudflare.ts";
+
+/** The Workers rate limiting binding, as the Worker's config declares it. */
+export interface RateLimitBindingConfig {
+  name: string;
+  namespace_id: string;
+  simple: { limit: number; period: 10 | 60 };
+}
+
+/**
+ * A namespace id for a Worker that sets none: a positive integer derived from
+ * its name, so two Blume sites on one account don't share one.
+ */
+export const rateLimitNamespace = (workerName: string): string => {
+  const digest = createHash("sha256").update(workerName).digest("hex");
+  return String((Number.parseInt(digest.slice(0, 8), 16) % 2_000_000_000) + 1);
+};
+
+const isText = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+/** The binding `cloudflare()` asks for, on the Worker named `workerName`. */
+export const rateLimitBinding = (
+  adapter: CloudflareRateLimitAdapter,
+  workerName: string
+): RateLimitBindingConfig => ({
+  name: RATE_LIMIT_BINDING,
+  namespace_id: adapter.options.namespaceId ?? rateLimitNamespace(workerName),
+  simple: {
+    limit: adapter.options.requests ?? 10,
+    period: adapter.options.window ?? 60,
+  },
+});
+
+/**
+ * The built Worker's config (`dist/server/wrangler.json`) with Blume's rate
+ * limiting binding in `ratelimits`, replacing an earlier one of the same name
+ * and keeping any others. `null` when the config isn't a JSON object.
+ */
+export const withRateLimitBinding = (
+  wranglerText: string,
+  adapter: CloudflareRateLimitAdapter
+): string | null => {
+  let config: JsonValue;
+  try {
+    config = JSON.parse(wranglerText);
+  } catch {
+    return null;
+  }
+  if (!isJsonObject(config) || Array.isArray(config)) {
+    return null;
+  }
+  const { name, ratelimits } = config;
+  const others = Array.isArray(ratelimits)
+    ? ratelimits.filter(
+        (entry) => !(isJsonObject(entry) && entry.name === RATE_LIMIT_BINDING)
+      )
+    : [];
+  const binding = rateLimitBinding(adapter, isText(name) ? name : "");
+  config.ratelimits = [
+    ...others,
+    { ...binding, simple: { ...binding.simple } },
+  ];
+  return JSON.stringify(config);
+};

package/src/reference/asyncapi.ts

@@ -16,9 +16,9 @@ import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
 export interface AsyncApiOptions {
   /**
    * Code-sample tools shown per operation (Blume renderer). Defaults to every
-   * tool appropriate to the operation's protocol binding.
+   * tool appropriate to the operation's protocol binding; `false` shows none.
    */
-  codeSamples?: string[];
+  codeSamples?: string[] | false;
   /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
   /**

package/src/reference/graphql.ts

@@ -13,8 +13,11 @@ import type { GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
 
 /** Options for {@link graphql}. */
 export interface GraphqlOptions {
-  /** Code-sample languages shown per operation. Defaults to `["curl", "js", "python"]`. */
-  codeSamples?: string[];
+  /**
+   * Code-sample languages shown per operation, in order. Defaults to
+   * `["curl", "js", "python"]`; `false` shows none.
+   */
+  codeSamples?: string[] | false;
   /**
    * URL of the live GraphQL endpoint the playground and code samples target —
    * a schema, unlike an OpenAPI document, names no server. Applies to every

package/src/reference/openapi.ts

@@ -4,18 +4,24 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 import {
   liftSpec,
-  referenceSourceSchema,
+  openapiSourceSchema,
+  overlaysHaveSpec,
+  overlaysNeedSpecIssue,
   hasSources,
   missingSourcesIssue,
   rendererRemovedHint,
   sharedOptions,
 } from "./options.ts";
-import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
+import type { OpenApiSourceOptions, PlaygroundOptions } from "./options.ts";
 
 /** Options for {@link openapi}. */
 export interface OpenApiOptions {
-  /** Code-sample languages shown per operation (Blume renderer). Defaults to `["curl", "js", "python"]`. */
-  codeSamples?: string[];
+  /**
+   * Code-sample languages generated per operation (Blume renderer), in
+   * order. Defaults to `["curl", "js", "python"]`; `false` generates none, so
+   * only the spec's own `x-codeSamples` show.
+   */
+  codeSamples?: string[] | false;
   /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
   /**
@@ -26,10 +32,15 @@ export interface OpenApiOptions {
    * `vercel()` in `deployment`).
    */
   playground?: PlaygroundOptions;
+  /**
+   * OpenAPI Overlay documents for `spec`, applied in order before it renders.
+   * With `sources`, each source takes its own `overlays`.
+   */
+  overlays?: string[];
   /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
   /** One or more specs; each renders on its own route by default. */
-  sources?: ReferenceSourceOptions[];
+  sources?: OpenApiSourceOptions[];
   /** Shorthand for a single source: `sources: [{ spec }]`. */
   spec?: string;
 }
@@ -43,12 +54,15 @@ export const openapiOptionsSchema = z
       }),
       /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
       expandSchemas: z.boolean().default(false),
+      /** Overlays for the `spec` shorthand. */
+      overlays: z.array(z.string()).optional(),
       /** One or more specs; each renders on its own route by default. */
-      sources: z.array(referenceSourceSchema).default([]),
+      sources: z.array(openapiSourceSchema).default([]),
     },
     rendererRemovedHint
   )
-  .transform(liftSpec(referenceSourceSchema))
+  .refine(overlaysHaveSpec, overlaysNeedSpecIssue)
+  .transform(liftSpec(openapiSourceSchema))
   .refine(hasSources, missingSourcesIssue("openapi"));
 
 /** `openapi()` options with every default applied and `spec` folded into `sources`. */

package/src/reference/options.ts

@@ -65,6 +65,40 @@ export interface ReferenceSourceOptions {
 /** A spec source with every default applied. */
 export type ResolvedReferenceSource = z.output<typeof referenceSourceSchema>;
 
+/**
+ * [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html) documents
+ * (local paths or `http(s)` URLs) applied in order to an OpenAPI spec before
+ * it renders: changes to a spec you don't edit by hand.
+ */
+export const overlaysSchema = z.array(z.string()).default([]);
+
+/** Whether adapter-level `overlays` has the `spec` it belongs to. */
+export const overlaysHaveSpec = (options: {
+  overlays?: string[];
+  spec?: string;
+}): boolean => !options.overlays || options.spec !== undefined;
+
+/** The refinement issue for `overlays` set beside `sources` instead of `spec`. */
+export const overlaysNeedSpecIssue = {
+  message:
+    "`overlays` belongs to the `spec` shorthand; with `sources`, give each source its own `overlays`.",
+  path: ["overlays"],
+};
+
+/** An OpenAPI spec source: the shared shape plus its `overlays`. */
+export const openapiSourceSchema = referenceSourceSchema.extend({
+  overlays: overlaysSchema,
+});
+
+/** One OpenAPI spec source, as `openapi()` accepts it. */
+export interface OpenApiSourceOptions extends ReferenceSourceOptions {
+  /**
+   * OpenAPI Overlay documents (local paths or `http(s)` URLs) applied in
+   * order to the spec before it renders.
+   */
+  overlays?: string[];
+}
+
 /**
  * A single GraphQL schema: the shared source shape plus `endpoint`, the live
  * GraphQL API URL the playground and code samples target (a schema, unlike an
@@ -157,8 +191,13 @@ export const sharedOptions = (defaults: {
   codeSamples: string[];
   route: string;
 }) => ({
-  /** Code-sample languages/tools shown per operation (Blume renderer). */
-  codeSamples: z.array(z.string()).default(defaults.codeSamples),
+  /**
+   * Code-sample languages/tools shown per operation (Blume renderer), or
+   * `false` for none: only the spec's own `x-codeSamples` then.
+   */
+  codeSamples: z
+    .union([z.literal(false), z.array(z.string())])
+    .default(defaults.codeSamples),
   /** The "Try it" panel; see {@link playgroundSchema}. */
   playground: playgroundSchema,
   /** Where the reference mounts. */
@@ -168,8 +207,9 @@ export const sharedOptions = (defaults: {
 });
 
 /**
- * Resolve the `spec` shorthand into `sources` so downstream code reads one
- * field: the shorthand becomes the first source (with the source defaults
+ * Resolve the `spec` shorthand (and, on OpenAPI kinds, the `overlays` beside
+ * it) into `sources` so downstream code reads one field: the shorthand becomes
+ * the first source (with the source defaults
  * applied through the source schema itself, so the two can never drift) and
  * the `spec` key is dropped. An adapter with neither renders nothing, which
  * is a config mistake rather than a choice — `refine` it away with
@@ -179,15 +219,19 @@ export const liftSpec =
   <Source extends { spec: string }>(
     sourceSchema: z.ZodType<Source, { spec: string }>
   ) =>
-  <Options extends { sources: Source[]; spec?: string }>({
+  <Options extends { sources: Source[]; spec?: string; overlays?: string[] }>({
+    overlays,
     spec,
     ...options
-  }: Options): Omit<Options, "spec"> => ({
+  }: Options): Omit<Options, "spec" | "overlays"> => ({
     ...options,
     sources:
       spec === undefined
         ? options.sources
-        : [sourceSchema.parse({ spec }), ...options.sources],
+        : [
+            sourceSchema.parse(overlays ? { overlays, spec } : { spec }),
+            ...options.sources,
+          ],
   });
 
 /** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */