blume 2.0.3 → 2.1.0

package/dist/types/openapi/parse.d.ts

@@ -16,6 +16,11 @@ export declare 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;
     /**
@@ -24,6 +29,14 @@ export interface SpecFetchOptions {
      */
     refresh?: boolean;
 }
+/**
+ * A spec with its overlays applied, as JSON text: what the Scalar embed
+ * inlines, since it can't apply overlays itself.
+ */
+export declare const readOverlaidSpec: (spec: string, root: string, options: SpecFetchOptions) => Promise<{
+    text: string;
+    warnings: string[];
+}>;
 export declare const parseSpec: (spec: string, root: string, options?: SpecFetchOptions) => Promise<ParsedSpec>;
 export interface ParsedAsyncApiSpec {
     document: AsyncApiDocument;

package/dist/types/openapi/references.d.ts

@@ -19,8 +19,8 @@ export type ReferenceKind = ResolvedReferenceAdapter["kind"];
 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;
     /**
@@ -60,6 +60,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).
@@ -120,10 +125,15 @@ export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;
  * definition with {@link needsPlaygroundProxy}.
  */
 export declare const builtinProxyReferences: (config: ResolvedConfig) => BlumeReferenceSource[];
+/**
+ * Whether hand-written endpoint pages (`api` frontmatter) send their Try it
+ * requests through the built-in proxy: `api.playground.proxy: true`.
+ */
+export declare const apiPagesUseBuiltinProxy: (config: ResolvedConfig) => boolean;
 /**
  * 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 declare const needsPlaygroundProxy: (config: ResolvedConfig) => boolean;

package/dist/types/ratelimit/cloudflare.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+/** The Worker binding Blume declares for the rate limiter. */
+export declare 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 declare const cloudflareRateLimitOptionsSchema: z.ZodObject<{
+    namespaceId: z.ZodOptional<z.ZodString>;
+    requests: z.ZodOptional<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+}, z.core.$strict>;
+export type CloudflareRateLimitAdapter = AdapterDescriptor<"cloudflare", CloudflareRateLimitOptions>;
+export declare const cloudflareRateLimitAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        namespaceId: z.ZodOptional<z.ZodString>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 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 declare const cloudflare: (options?: CloudflareRateLimitOptions) => CloudflareRateLimitAdapter;

package/dist/types/ratelimit/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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/dist/types/ratelimit/memory.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+/** How many requests a reader gets per window, unless set. */
+export declare const DEFAULT_REQUESTS = 30;
+/** The window those requests are counted over, in seconds, unless set. */
+export declare 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 declare const rateLimitOptionsSchema: z.ZodObject<{
+    requests: z.ZodOptional<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MemoryAdapter = AdapterDescriptor<"memory", RateLimitOptions>;
+export declare const memoryAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"memory">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 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 declare const memory: (options?: RateLimitOptions) => MemoryAdapter;

package/dist/types/ratelimit/schema.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/** The configured rate limiter, as its factory returned it. */
+export declare const rateLimitAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        namespaceId: z.ZodOptional<z.ZodString>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"memory">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upstash">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">;
+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 declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        namespaceId: z.ZodOptional<z.ZodString>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"memory">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upstash">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">]>>, z.ZodTransform<{
+    kind: "cloudflare";
+    options: {
+        namespaceId?: string | undefined;
+        requests?: number | undefined;
+        window?: 10 | 60 | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "memory";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "upstash";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | null, false | {
+    kind: "cloudflare";
+    options: {
+        namespaceId?: string | undefined;
+        requests?: number | undefined;
+        window?: 10 | 60 | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "memory";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "upstash";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | undefined>>;

package/dist/types/ratelimit/upstash.d.ts

@@ -0,0 +1,21 @@
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { RateLimitOptions } from "./memory.ts";
+/** The env vars holding the Upstash Redis REST endpoint and its token. */
+export declare const UPSTASH_SECRETS: readonly ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"];
+export type UpstashAdapter = AdapterDescriptor<"upstash", RateLimitOptions>;
+export declare const upstashAdapterSchema: import("zod").ZodObject<{
+    kind: import("zod").ZodLiteral<"upstash">;
+    options: import("zod").ZodObject<{
+        requests: import("zod").ZodOptional<import("zod").ZodNumber>;
+        window: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>;
+    requiredSecrets: import("zod").ZodArray<import("zod").ZodString>;
+    runtimeDeps: import("zod").ZodArray<import("zod").ZodString>;
+}, import("zod/v4/core").$strict>;
+/**
+ * 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 declare const upstash: (options?: RateLimitOptions) => UpstashAdapter;

package/dist/types/ratelimit/wrangler.d.ts

@@ -0,0 +1,23 @@
+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 declare const rateLimitNamespace: (workerName: string) => string;
+/** The binding `cloudflare()` asks for, on the Worker named `workerName`. */
+export declare const rateLimitBinding: (adapter: CloudflareRateLimitAdapter, workerName: string) => RateLimitBindingConfig;
+/**
+ * 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 declare const withRateLimitBinding: (wranglerText: string, adapter: CloudflareRateLimitAdapter) => string | null;

package/dist/types/reference/asyncapi.d.ts

@@ -5,9 +5,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;
     /**
@@ -34,7 +34,7 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
         spec: z.ZodString;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -58,14 +58,14 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     expandSchemas: boolean;
     sources: {
         includeInLlms: boolean;
@@ -76,7 +76,7 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -102,7 +102,7 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -126,14 +126,14 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         expandSchemas: boolean;
         sources: {
             includeInLlms: boolean;
@@ -144,7 +144,7 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;

package/dist/types/reference/graphql.d.ts

@@ -3,8 +3,11 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 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
@@ -44,7 +47,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         spec: z.ZodString;
         endpoint: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -68,7 +71,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         route?: string | undefined;
         endpoint?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -76,7 +79,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
     route: string;
     endpoint?: string | undefined;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     sources: {
         includeInLlms: boolean;
         includeInSearch: boolean;
@@ -87,7 +90,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         route?: string | undefined;
         endpoint?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -115,7 +118,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             spec: z.ZodString;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -139,7 +142,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -147,7 +150,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         sources: {
             includeInLlms: boolean;
             includeInSearch: boolean;
@@ -158,7 +161,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;

package/dist/types/reference/openapi.d.ts

@@ -1,10 +1,14 @@
 import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.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;
     /**
@@ -15,15 +19,21 @@ 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;
 }
 export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
     expandSchemas: z.ZodDefault<z.ZodBoolean>;
+    overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
         includeInLlms: z.ZodDefault<z.ZodBoolean>;
         includeInSearch: z.ZodDefault<z.ZodBoolean>;
@@ -32,8 +42,9 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         route: z.ZodOptional<z.ZodString>;
         seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
         spec: z.ZodString;
+        overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -54,17 +65,19 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         noindex: boolean;
         seoDescriptionSuffix: boolean;
         spec: string;
+        overlays: string[];
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
+    overlays?: string[] | undefined;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     expandSchemas: boolean;
     sources: {
         includeInLlms: boolean;
@@ -72,15 +85,17 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         noindex: boolean;
         seoDescriptionSuffix: boolean;
         spec: string;
+        overlays: string[];
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
+    overlays?: string[] | undefined;
     spec?: string | undefined;
 }>>;
 /** `openapi()` options with every default applied and `spec` folded into `sources`. */
@@ -92,6 +107,7 @@ export declare const openapiAdapterSchema: z.ZodObject<{
     kind: z.ZodLiteral<"openapi">;
     options: z.ZodPipe<z.ZodObject<{
         expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             includeInLlms: z.ZodDefault<z.ZodBoolean>;
             includeInSearch: z.ZodDefault<z.ZodBoolean>;
@@ -100,8 +116,9 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             route: z.ZodOptional<z.ZodString>;
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -122,17 +139,19 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             noindex: boolean;
             seoDescriptionSuffix: boolean;
             spec: string;
+            overlays: string[];
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
+        overlays?: string[] | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         expandSchemas: boolean;
         sources: {
             includeInLlms: boolean;
@@ -140,15 +159,17 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             noindex: boolean;
             seoDescriptionSuffix: boolean;
             spec: string;
+            overlays: string[];
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
+        overlays?: string[] | undefined;
         spec?: string | undefined;
     }>>;
     requiredSecrets: z.ZodArray<z.ZodString>;