blume 2.0.3 → 2.1.0

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

@@ -36,6 +36,41 @@ 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 declare const overlaysSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
+/** Whether adapter-level `overlays` has the `spec` it belongs to. */
+export declare const overlaysHaveSpec: (options: {
+    overlays?: string[];
+    spec?: string;
+}) => boolean;
+/** The refinement issue for `overlays` set beside `sources` instead of `spec`. */
+export declare const overlaysNeedSpecIssue: {
+    message: string;
+    path: string[];
+};
+/** An OpenAPI spec source: the shared shape plus its `overlays`. */
+export declare const openapiSourceSchema: z.ZodObject<{
+    includeInLlms: z.ZodDefault<z.ZodBoolean>;
+    includeInSearch: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
+    spec: z.ZodString;
+    overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** 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
@@ -110,8 +145,11 @@ export declare const sharedOptions: (defaults: {
     codeSamples: string[];
     route: string;
 }) => {
-    /** Code-sample languages/tools shown per operation (Blume renderer). */
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /**
+     * Code-sample languages/tools shown per operation (Blume renderer), or
+     * `false` for none: only the spec's own `x-codeSamples` then.
+     */
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     /** The "Try it" panel; see {@link playgroundSchema}. */
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -129,8 +167,9 @@ export declare const sharedOptions: (defaults: {
     spec: z.ZodOptional<z.ZodString>;
 };
 /**
- * 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
@@ -143,7 +182,8 @@ export declare const liftSpec: <Source extends {
 }>) => <Options extends {
     sources: Source[];
     spec?: string;
-}>({ spec, ...options }: Options) => Omit<Options, "spec">;
+    overlays?: string[];
+}>({ overlays, spec, ...options }: Options) => Omit<Options, "spec" | "overlays">;
 /** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */
 export declare const hasSources: (options: {
     sources: {

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

@@ -15,6 +15,7 @@ export declare const SCALAR_RUNTIME_DEPS: readonly string[];
 export declare const scalarSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
+    overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
     route: z.ZodOptional<z.ZodString>;
     spec: z.ZodString;
 }, z.core.$strict>;
@@ -24,6 +25,8 @@ export interface ScalarSourceOptions {
     label?: string;
     /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
     noindex?: boolean;
+    /** OpenAPI Overlay documents applied in order to the document before it's embedded. */
+    overlays?: string[];
     /** Per-source route; defaults to the adapter's `route` (or a derived path). */
     route?: string;
     /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -44,6 +47,8 @@ export type ResolvedScalarOptions = {
 };
 /** The options {@link scalar} maps itself. */
 export interface ScalarNamedOptions {
+    /** OpenAPI Overlay documents for `spec`; with `sources`, each takes its own. */
+    overlays?: string[];
     /** Where the reference mounts. Defaults to `/reference`. */
     route?: string;
     /** One or more documents; each renders on its own route by default. */
@@ -73,10 +78,12 @@ export type ScalarOptions = ScalarNamedOptions & {
  * the named ones is Scalar configuration and passes through untouched.
  */
 export declare const scalarOptionsSchema: z.ZodPipe<z.ZodObject<{
+    overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
     route: z.ZodDefault<z.ZodString>;
     sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         noindex: z.ZodDefault<z.ZodBoolean>;
+        overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
         route: z.ZodOptional<z.ZodString>;
         spec: z.ZodString;
     }, z.core.$strict>>>;
@@ -87,10 +94,12 @@ export declare const scalarOptionsSchema: z.ZodPipe<z.ZodObject<{
     route: string;
     sources: {
         noindex: boolean;
+        overlays: string[];
         spec: string;
         label?: string | undefined;
         route?: string | undefined;
     }[];
+    overlays?: string[] | undefined;
     spec?: string | undefined;
     theme?: string | undefined;
 }>>;
@@ -100,10 +109,12 @@ export type ResolvedScalarAdapter = AdapterDescriptor<"scalar", ResolvedScalarOp
 export declare const scalarAdapterSchema: z.ZodObject<{
     kind: z.ZodLiteral<"scalar">;
     options: z.ZodPipe<z.ZodObject<{
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         route: z.ZodDefault<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
             route: z.ZodOptional<z.ZodString>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
@@ -114,10 +125,12 @@ export declare const scalarAdapterSchema: z.ZodObject<{
         route: string;
         sources: {
             noindex: boolean;
+            overlays: string[];
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        overlays?: string[] | undefined;
         spec?: string | undefined;
         theme?: string | undefined;
     }>>;

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

@@ -26,7 +26,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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]>>;
@@ -50,14 +50,14 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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;
@@ -68,7 +68,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -92,7 +92,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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]>>;
@@ -116,7 +116,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -124,7 +124,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         sources: {
             includeInLlms: boolean;
             includeInSearch: boolean;
@@ -135,7 +135,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -150,6 +150,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
     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>;
@@ -158,8 +159,9 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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]>>;
@@ -180,17 +182,19 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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;
@@ -198,15 +202,17 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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>;
@@ -214,10 +220,12 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"scalar">;
     options: z.ZodPipe<z.ZodObject<{
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         route: z.ZodDefault<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
             route: z.ZodOptional<z.ZodString>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
@@ -228,10 +236,12 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
         route: string;
         sources: {
             noindex: boolean;
+            overlays: string[];
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        overlays?: string[] | undefined;
         spec?: string | undefined;
         theme?: string | undefined;
     }>>;
@@ -255,14 +265,14 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 } | {
@@ -278,7 +288,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -286,7 +296,7 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">;
+    }, "spec" | "overlays">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 } | {
@@ -299,17 +309,19 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             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">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 }>>;
@@ -331,7 +343,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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]>>;
@@ -355,14 +367,14 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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;
@@ -373,7 +385,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -397,7 +409,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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]>>;
@@ -421,7 +433,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -429,7 +441,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         sources: {
             includeInLlms: boolean;
             includeInSearch: boolean;
@@ -440,7 +452,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -455,6 +467,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
     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>;
@@ -463,8 +476,9 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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]>>;
@@ -485,17 +499,19 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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;
@@ -503,15 +519,17 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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>;
@@ -519,10 +537,12 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"scalar">;
     options: z.ZodPipe<z.ZodObject<{
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         route: z.ZodDefault<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
             route: z.ZodOptional<z.ZodString>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
@@ -533,10 +553,12 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
         route: string;
         sources: {
             noindex: boolean;
+            overlays: string[];
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        overlays?: string[] | undefined;
         spec?: string | undefined;
         theme?: string | undefined;
     }>>;
@@ -560,14 +582,14 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 } | {
@@ -583,7 +605,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -591,7 +613,7 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">;
+    }, "spec" | "overlays">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 } | {
@@ -604,17 +626,19 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             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">;
     requiredSecrets: string[];
     runtimeDeps: string[];
 }>>>>;

package/dist/types/search/documents.d.ts

@@ -23,6 +23,10 @@ export interface SearchDocument {
      * Filterable through the MCP tools' `filters` input.
      */
     facets?: Record<string, string>;
+    /** Frontmatter `search.boost`: the page's relevance multiplier, when set. */
+    boost?: number;
+    /** Frontmatter `search.keywords`: extra terms the page is found by. */
+    keywords?: string[];
 }
 /**
  * A record uploaded to a hosted search backend (Algolia, Orama Cloud,
@@ -45,6 +49,13 @@ export interface SearchRecord {
     version: string;
     /** Single faceting tag (the first frontmatter tag, when present). */
     tag?: string;
+    /**
+     * The page's relevance multiplier, 1 unless `search.boost` sets it: a
+     * ranking attribute every record carries, so the backend can sort by it.
+     */
+    boost: number;
+    /** Extra terms the page is found by (`search.keywords`). */
+    keywords?: string[];
 }
 interface BuildOptions {
     includeWhenDisabled?: boolean;
@@ -84,7 +95,7 @@ export declare const buildSearchDocuments: (project: BlumeProject, options?: Bui
 /**
  * Map per-page search documents to the flat record shape hosted backends
  * ingest. One record per page, keyed by route; the first tag becomes the
- * faceting `tag`.
+ * faceting `tag`, and every record carries a `boost` (1 by default).
  */
 export declare const toSearchRecords: (documents: SearchDocument[]) => SearchRecord[];
 export {};

package/dist/types/search/orama-index.d.ts

@@ -24,6 +24,10 @@ export interface OramaDoc {
      * but not indexed, so they ride along on the returned document untouched. */
     breadcrumb?: string[];
     section?: string;
+    /** The page's relevance multiplier (`search.boost`); stored, not indexed. */
+    boost?: number;
+    /** Extra terms the page is found by (`search.keywords`). */
+    keywords?: string[];
 }
 /**
  * Build an in-memory Orama full-text index from search documents. Shared by the

package/dist/types/seo/metatags.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Site-wide meta tags (`seo.metatags`): tags written into every page's head,
+ * for what Blume has no setting of its own for, such as site-verification
+ * tokens, `theme-color`, or an app banner. The tags Blume writes itself are
+ * refused, each pointing at the setting that controls it, so a page never
+ * carries two values for one tag.
+ */
+/**
+ * What sets a tag Blume writes itself, or `undefined` for a tag the site can
+ * add.
+ */
+export declare const ownedMetatag: (name: string) => string | undefined;
+/** One site-wide tag, as its `<meta>` element's attributes. */
+export interface MetatagAttributes {
+    content: string;
+    name?: string;
+    property?: string;
+}
+/** The site's `seo.metatags` as `<meta>` attributes, in the order written. */
+export declare const metatagAttributes: (tags?: Readonly<Record<string, string>> | null) => MetatagAttributes[];