blume 1.7.3 → 2.0.1

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

@@ -0,0 +1,181 @@
+import { z } from "zod";
+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[];
+    /**
+     * URL of the live GraphQL endpoint the playground and code samples target —
+     * a schema, unlike an OpenAPI document, names no server. Applies to every
+     * source; a per-source `endpoint` wins.
+     */
+    endpoint?: string;
+    /**
+     * The interactive "Try it" panel. On by default; `false` hides it. The
+     * object form sets `proxy`, the CORS escape hatch the Send button routes
+     * requests through: a proxy URL, or `true` for the built-in `/_api-proxy`
+     * endpoint (which needs server output: a host adapter such as `vercel()` in
+     * `deployment`).
+     */
+    playground?: PlaygroundOptions;
+    /** Where the reference mounts. Defaults to `/graphql`. */
+    route?: string;
+    /** One or more schemas; each renders on its own route by default. */
+    sources?: GraphqlSourceOptions[];
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    spec?: string;
+}
+/**
+ * No `expandSchemas` (GraphQL field tables have no nesting) — everything
+ * else, the playground normalization included, is the shared reference
+ * shape. There is no Scalar counterpart: the Scalar embed reads OpenAPI and
+ * AsyncAPI documents only.
+ */
+export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
+    endpoint: z.ZodOptional<z.ZodString>;
+    sources: z.ZodDefault<z.ZodArray<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;
+        endpoint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    codeSamples: z.ZodDefault<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]>>;
+    }, z.core.$strict>]>>, z.ZodTransform<{
+        enabled: boolean;
+        proxy: string | boolean;
+    }, boolean | {
+        enabled: boolean;
+        proxy: string | boolean;
+    }>>;
+    route: z.ZodDefault<z.ZodString>;
+    spec: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<Omit<{
+    sources: {
+        includeInLlms: boolean;
+        includeInSearch: boolean;
+        noindex: boolean;
+        seoDescriptionSuffix: boolean;
+        spec: string;
+        label?: string | undefined;
+        route?: string | undefined;
+        endpoint?: string | undefined;
+    }[];
+    codeSamples: string[];
+    playground: {
+        enabled: boolean;
+        proxy: string | boolean;
+    };
+    route: string;
+    endpoint?: string | undefined;
+    spec?: string | undefined;
+}, "spec">, {
+    sources: {
+        includeInLlms: boolean;
+        includeInSearch: boolean;
+        noindex: boolean;
+        seoDescriptionSuffix: boolean;
+        spec: string;
+        label?: string | undefined;
+        route?: string | undefined;
+        endpoint?: string | undefined;
+    }[];
+    codeSamples: string[];
+    playground: {
+        enabled: boolean;
+        proxy: string | boolean;
+    };
+    route: string;
+    endpoint?: string | undefined;
+    spec?: string | undefined;
+}>>;
+/** `graphql()` options with every default applied and `spec` folded into `sources`. */
+export type ResolvedGraphqlOptions = z.output<typeof graphqlOptionsSchema>;
+export type GraphqlAdapter = AdapterDescriptor<"graphql", GraphqlOptions>;
+/** A `graphql()` descriptor as the config schema resolves it. */
+export type ResolvedGraphqlAdapter = AdapterDescriptor<"graphql", ResolvedGraphqlOptions>;
+export declare const graphqlAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"graphql">;
+    options: z.ZodPipe<z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodString>;
+        sources: z.ZodDefault<z.ZodArray<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;
+            endpoint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        codeSamples: z.ZodDefault<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]>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            proxy: string | boolean;
+        }, boolean | {
+            enabled: boolean;
+            proxy: string | boolean;
+        }>>;
+        route: z.ZodDefault<z.ZodString>;
+        spec: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodTransform<Omit<{
+        sources: {
+            includeInLlms: boolean;
+            includeInSearch: boolean;
+            noindex: boolean;
+            seoDescriptionSuffix: boolean;
+            spec: string;
+            label?: string | undefined;
+            route?: string | undefined;
+            endpoint?: string | undefined;
+        }[];
+        codeSamples: string[];
+        playground: {
+            enabled: boolean;
+            proxy: string | boolean;
+        };
+        route: string;
+        endpoint?: string | undefined;
+        spec?: string | undefined;
+    }, "spec">, {
+        sources: {
+            includeInLlms: boolean;
+            includeInSearch: boolean;
+            noindex: boolean;
+            seoDescriptionSuffix: boolean;
+            spec: string;
+            label?: string | undefined;
+            route?: string | undefined;
+            endpoint?: string | undefined;
+        }[];
+        codeSamples: string[];
+        playground: {
+            enabled: boolean;
+            proxy: string | boolean;
+        };
+        route: string;
+        endpoint?: string | undefined;
+        spec?: string | undefined;
+    }>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A GraphQL reference. Blume lowers the schema (SDL or introspection JSON) to
+ * one real page per root field — grouped as Queries/Mutations/Subscriptions —
+ * plus one page per named type (Objects, Input Objects, Enums, Interfaces,
+ * Unions, Scalars), all included in the sidebar, search, llms.txt, and OG.
+ * Always Blume-rendered: the Scalar embed reads OpenAPI and AsyncAPI
+ * documents only, so there is no `scalar()` counterpart.
+ */
+export declare const graphql: (options: GraphqlOptions) => GraphqlAdapter;

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

@@ -0,0 +1,32 @@
+/**
+ * API reference adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { asyncapi, graphql, openapi, scalar } from "blume/reference";
+ *
+ * export default defineConfig({
+ *   reference: [
+ *     openapi({ spec: "./openapi.yaml" }),
+ *     asyncapi({ spec: "./asyncapi.yaml" }),
+ *     graphql({ spec: "./schema.graphql", endpoint: "https://api.example.com/graphql" }),
+ *     scalar({ spec: "./legacy.yaml", route: "/legacy", theme: "purple" }),
+ *   ],
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`) that the
+ * schema validates and the generated site reads as a literal; nothing here
+ * runs in the browser.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { asyncapi } from "./asyncapi.ts";
+export type { AsyncApiAdapter, AsyncApiOptions } from "./asyncapi.ts";
+export { graphql } from "./graphql.ts";
+export type { GraphqlAdapter, GraphqlOptions } from "./graphql.ts";
+export { openapi } from "./openapi.ts";
+export type { OpenApiAdapter, OpenApiOptions } from "./openapi.ts";
+export type { GraphqlSourceOptions, PlaygroundOptions, ReferenceSourceOptions, } from "./options.ts";
+export { scalar } from "./scalar.ts";
+export type { ScalarAdapter, ScalarOptions, ScalarSourceOptions, } from "./scalar.ts";
+export type { ReferenceAdapter, ResolvedReferenceAdapter } from "./schema.ts";

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

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { PlaygroundOptions, ReferenceSourceOptions } 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[];
+    /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
+    expandSchemas?: boolean;
+    /**
+     * The interactive "Try it" panel (Blume renderer). On by default; `false`
+     * hides it. The object form sets `proxy`, the CORS escape hatch the Send
+     * button routes requests through: a proxy URL, or `true` for the built-in
+     * `/_api-proxy` endpoint (which needs server output: a host adapter such as
+     * `vercel()` in `deployment`).
+     */
+    playground?: PlaygroundOptions;
+    /** Where the reference mounts. Defaults to `/reference`. */
+    route?: string;
+    /** One or more specs; each renders on its own route by default. */
+    sources?: ReferenceSourceOptions[];
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    spec?: string;
+}
+export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
+    expandSchemas: z.ZodDefault<z.ZodBoolean>;
+    sources: z.ZodDefault<z.ZodArray<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;
+    }, z.core.$strict>>>;
+    codeSamples: z.ZodDefault<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]>>;
+    }, z.core.$strict>]>>, z.ZodTransform<{
+        enabled: boolean;
+        proxy: string | boolean;
+    }, boolean | {
+        enabled: boolean;
+        proxy: string | boolean;
+    }>>;
+    route: z.ZodDefault<z.ZodString>;
+    spec: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<Omit<{
+    expandSchemas: boolean;
+    sources: {
+        includeInLlms: boolean;
+        includeInSearch: boolean;
+        noindex: boolean;
+        seoDescriptionSuffix: boolean;
+        spec: string;
+        label?: string | undefined;
+        route?: string | undefined;
+    }[];
+    codeSamples: string[];
+    playground: {
+        enabled: boolean;
+        proxy: string | boolean;
+    };
+    route: string;
+    spec?: string | undefined;
+}, "spec">, {
+    expandSchemas: boolean;
+    sources: {
+        includeInLlms: boolean;
+        includeInSearch: boolean;
+        noindex: boolean;
+        seoDescriptionSuffix: boolean;
+        spec: string;
+        label?: string | undefined;
+        route?: string | undefined;
+    }[];
+    codeSamples: string[];
+    playground: {
+        enabled: boolean;
+        proxy: string | boolean;
+    };
+    route: string;
+    spec?: string | undefined;
+}>>;
+/** `openapi()` options with every default applied and `spec` folded into `sources`. */
+export type ResolvedOpenApiOptions = z.output<typeof openapiOptionsSchema>;
+export type OpenApiAdapter = AdapterDescriptor<"openapi", OpenApiOptions>;
+/** An `openapi()` descriptor as the config schema resolves it. */
+export type ResolvedOpenApiAdapter = AdapterDescriptor<"openapi", ResolvedOpenApiOptions>;
+export declare const openapiAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"openapi">;
+    options: z.ZodPipe<z.ZodObject<{
+        expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        sources: z.ZodDefault<z.ZodArray<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;
+        }, z.core.$strict>>>;
+        codeSamples: z.ZodDefault<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]>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            proxy: string | boolean;
+        }, boolean | {
+            enabled: boolean;
+            proxy: string | boolean;
+        }>>;
+        route: z.ZodDefault<z.ZodString>;
+        spec: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodTransform<Omit<{
+        expandSchemas: boolean;
+        sources: {
+            includeInLlms: boolean;
+            includeInSearch: boolean;
+            noindex: boolean;
+            seoDescriptionSuffix: boolean;
+            spec: string;
+            label?: string | undefined;
+            route?: string | undefined;
+        }[];
+        codeSamples: string[];
+        playground: {
+            enabled: boolean;
+            proxy: string | boolean;
+        };
+        route: string;
+        spec?: string | undefined;
+    }, "spec">, {
+        expandSchemas: boolean;
+        sources: {
+            includeInLlms: boolean;
+            includeInSearch: boolean;
+            noindex: boolean;
+            seoDescriptionSuffix: boolean;
+            spec: string;
+            label?: string | undefined;
+            route?: string | undefined;
+        }[];
+        codeSamples: string[];
+        playground: {
+            enabled: boolean;
+            proxy: string | boolean;
+        };
+        route: string;
+        spec?: string | undefined;
+    }>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * An OpenAPI reference. Blume parses the spec with Scalar's parser and renders
+ * its own UI: one real page per operation, grouped by tag in the sidebar and
+ * included in site search, llms.txt, and OG. To embed the Scalar SPA instead
+ * (a single self-contained route that doesn't weave into the sidebar or
+ * search), list a `scalar()` adapter. Blume's renderer parses at generate
+ * time and needs no runtime dependency.
+ */
+export declare const openapi: (options: OpenApiOptions) => OpenApiAdapter;

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

@@ -0,0 +1,157 @@
+import { z } from "zod";
+/**
+ * A single spec rendered by a reference. `spec` is a local path or an
+ * `http(s)` URL (an OpenAPI document for `openapi()`, an AsyncAPI document
+ * for `asyncapi()`, SDL or introspection JSON for `graphql()`).
+ */
+export declare const referenceSourceSchema: 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;
+}, z.core.$strict>;
+/** One spec source, as `openapi()` and `asyncapi()` accept it. */
+export interface ReferenceSourceOptions {
+    /** Include generated pages from this spec in llms.txt/llms-full.txt. Defaults to `true`. */
+    includeInLlms?: boolean;
+    /** Include generated pages from this spec in site search. Defaults to `true`. */
+    includeInSearch?: boolean;
+    /** Nav/section label for this source. */
+    label?: string;
+    /** Emit noindex metadata and omit generated pages from the sitemap. Defaults to `false`. */
+    noindex?: boolean;
+    /** Per-source route; defaults to the adapter's `route` (or a derived path). */
+    route?: string;
+    /**
+     * Append the generated English "Reference for …" sentence to every
+     * operation page's meta description. Defaults to `true`; set `false` on a
+     * non-English site to keep the spec's own prose alone.
+     */
+    seoDescriptionSuffix?: boolean;
+    /** Local path or `http(s)` URL to the spec. */
+    spec: string;
+}
+/** A spec source with every default applied. */
+export type ResolvedReferenceSource = z.output<typeof referenceSourceSchema>;
+/**
+ * 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
+ * OpenAPI document, names no server).
+ */
+export declare const graphqlSourceSchema: 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;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One schema source, as `graphql()` accepts it. */
+export interface GraphqlSourceOptions extends ReferenceSourceOptions {
+    /** URL of the live GraphQL endpoint (playground + code samples); wins over the adapter's `endpoint`. */
+    endpoint?: string;
+}
+/** A GraphQL schema source with every default applied. */
+export type ResolvedGraphqlSource = z.output<typeof graphqlSourceSchema>;
+/**
+ * The interactive "Try it" panel on operation pages (Blume renderer). On by
+ * default; `false` hides it. The object form keeps it on and sets `proxy`,
+ * the CORS escape hatch the Send button routes requests through: a proxy URL,
+ * or `true` for the built-in `/_api-proxy` endpoint (which needs server
+ * output: a host adapter such as `vercel()` in `deployment`). Booleans
+ * normalize to the object shape so consumers read `{ enabled, proxy }`
+ * directly. `proxy` applies to the HTTP-posting playgrounds (OpenAPI, GraphQL)
+ * — an event composer's WebSocket connect is direct. One schema for every
+ * reference kind, so the normalization can never drift between them.
+ */
+export declare const playgroundSchema: 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]>>;
+}, z.core.$strict>]>>, z.ZodTransform<{
+    enabled: boolean;
+    proxy: string | boolean;
+}, boolean | {
+    enabled: boolean;
+    proxy: string | boolean;
+}>>;
+/** The `playground` option as a factory accepts it. */
+export type PlaygroundOptions = boolean | {
+    /** Render the panel. Defaults to `true`. */
+    enabled?: boolean;
+    /** CORS proxy: a URL, or `true` for the built-in `/_api-proxy` route. Defaults to `false`. */
+    proxy?: boolean | string;
+};
+/** The playground with its booleans normalized: `{ enabled, proxy }`. */
+export type ResolvedPlayground = z.output<typeof playgroundSchema>;
+/**
+ * The message a config still passing `renderer` to `openapi()`/`asyncapi()`
+ * gets: Scalar is its own adapter now, so the option has no home.
+ */
+export declare const RENDERER_REMOVED_HINT = "`renderer` was removed: the Scalar embed is its own adapter. Replace `openapi({ spec, renderer: \"scalar\", theme })` with a separate `scalar({ spec, theme })` entry in `reference`, imported from \"blume/reference\" \u2014 `route`, `sources`, `label`, and `noindex` carry over, and the native display options (`codeSamples`, `expandSchemas`, `playground`) don't apply to the embed.";
+/**
+ * Error params for the `openapi()`/`asyncapi()` option objects: a leftover
+ * `renderer` key names its replacement instead of Zod's bare "Unrecognized
+ * key"; any other unknown key keeps the default message, beside the hint.
+ */
+export declare const rendererRemovedHint: {
+    error: (issue: z.core.$ZodRawIssue) => string | undefined;
+};
+/**
+ * The options every kind shares, with that kind's defaults for the mount
+ * route and code-sample set. `spec` is the single-source shorthand; the kind
+ * schema folds it into `sources` with {@link liftSpec}.
+ */
+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>>;
+    /** The "Try it" panel; see {@link playgroundSchema}. */
+    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]>>;
+    }, z.core.$strict>]>>, z.ZodTransform<{
+        enabled: boolean;
+        proxy: string | boolean;
+    }, boolean | {
+        enabled: boolean;
+        proxy: string | boolean;
+    }>>;
+    /** Where the reference mounts. */
+    route: z.ZodDefault<z.ZodString>;
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    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
+ * 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
+ * {@link hasSources}.
+ */
+export declare const liftSpec: <Source extends {
+    spec: string;
+}>(sourceSchema: z.ZodType<Source, {
+    spec: string;
+}>) => <Options extends {
+    sources: Source[];
+    spec?: string;
+}>({ spec, ...options }: Options) => Omit<Options, "spec">;
+/** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */
+export declare const hasSources: (options: {
+    sources: {
+        spec: string;
+    }[];
+}) => boolean;
+/** The refinement issue for a source-less adapter, naming its factory. */
+export declare const missingSourcesIssue: (factory: string) => {
+    message: string;
+    path: string[];
+};

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

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+/**
+ * What the generated Scalar page imports. Declared on every `scalar()`
+ * descriptor so the generated project lists it, which is what lets Astro's
+ * framework-package crawl bundle the embed.
+ */
+export declare const SCALAR_RUNTIME_DEPS: readonly string[];
+/**
+ * A single document rendered by a `scalar()` reference. Scalar reads OpenAPI
+ * and AsyncAPI documents and detects which it was given, so there is one
+ * source shape for both. The embed sits outside Blume's search and llms.txt,
+ * so of the native per-source controls only `noindex` applies here.
+ */
+export declare const scalarSourceSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    route: z.ZodOptional<z.ZodString>;
+    spec: z.ZodString;
+}, z.core.$strict>;
+/** One document source, as `scalar()` accepts it. */
+export interface ScalarSourceOptions {
+    /** Nav/section label for this source. */
+    label?: string;
+    /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
+    noindex?: boolean;
+    /** 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. */
+    spec: string;
+}
+/** A source with every default applied. */
+export type ResolvedScalarSource = z.output<typeof scalarSourceSchema>;
+/**
+ * `scalar()` options with every default applied and `spec` folded into
+ * `sources`; every key beyond the named ones is forwarded Scalar config.
+ */
+export type ResolvedScalarOptions = {
+    route: string;
+    sources: ResolvedScalarSource[];
+    theme?: string;
+} & {
+    [option: string]: JsonValue;
+};
+/** The options {@link scalar} maps itself. */
+export interface ScalarNamedOptions {
+    /** Where the reference mounts. Defaults to `/reference`. */
+    route?: string;
+    /** One or more documents; each renders on its own route by default. */
+    sources?: ScalarSourceOptions[];
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    spec?: string;
+    /** A Scalar theme name (`purple`, `moon`, …). Unset keeps Scalar's default theme with Blume's accent and radius layered on top. */
+    theme?: string;
+}
+/**
+ * Options for {@link scalar}: the source, route, and `theme` Blume maps, plus
+ * any other [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)
+ * key, forwarded verbatim to the embedded `<ScalarComponent>` (`localization`,
+ * `agent`, `hideTestRequestButton`, `orderSchemaPropertiesBy`, …). Blume
+ * doesn't mirror Scalar's config surface, so this is a full escape hatch: a
+ * forwarded key wins over Blume's own derived spec/theme config. JSON values
+ * only — the configuration is inlined into the generated page. `sources` is
+ * Blume's (one page per document); Scalar's own multi-document `sources`
+ * can't be forwarded.
+ */
+export type ScalarOptions = ScalarNamedOptions & {
+    [option: string]: JsonValue;
+};
+/**
+ * `spec` is the single-source shorthand and folds into `sources` at parse
+ * (through the source schema, so the two can never drift); every key beyond
+ * the named ones is Scalar configuration and passes through untouched.
+ */
+export declare const scalarOptionsSchema: z.ZodPipe<z.ZodObject<{
+    route: z.ZodDefault<z.ZodString>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        noindex: z.ZodDefault<z.ZodBoolean>;
+        route: z.ZodOptional<z.ZodString>;
+        spec: z.ZodString;
+    }, z.core.$strict>>>;
+    spec: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodJSONSchema>>, z.ZodTransform<ResolvedScalarOptions, {
+    [x: string]: z.core.util.JSONType;
+    route: string;
+    sources: {
+        noindex: boolean;
+        spec: string;
+        label?: string | undefined;
+        route?: string | undefined;
+    }[];
+    spec?: string | undefined;
+    theme?: string | undefined;
+}>>;
+export type ScalarAdapter = AdapterDescriptor<"scalar", ScalarOptions>;
+/** A `scalar()` descriptor as the config schema resolves it. */
+export type ResolvedScalarAdapter = AdapterDescriptor<"scalar", ResolvedScalarOptions>;
+export declare const scalarAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"scalar">;
+    options: z.ZodPipe<z.ZodObject<{
+        route: z.ZodDefault<z.ZodString>;
+        sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            noindex: z.ZodDefault<z.ZodBoolean>;
+            route: z.ZodOptional<z.ZodString>;
+            spec: z.ZodString;
+        }, z.core.$strict>>>;
+        spec: z.ZodOptional<z.ZodString>;
+        theme: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodJSONSchema>>, z.ZodTransform<ResolvedScalarOptions, {
+        [x: string]: z.core.util.JSONType;
+        route: string;
+        sources: {
+            noindex: boolean;
+            spec: string;
+            label?: string | undefined;
+            route?: string | undefined;
+        }[];
+        spec?: string | undefined;
+        theme?: string | undefined;
+    }>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * An API reference rendered by [Scalar](https://scalar.com)'s self-contained
+ * UI — its own sidebar, search, theme, and request client on a single route —
+ * instead of Blume's native operation pages. Takes an OpenAPI or AsyncAPI
+ * document (Scalar detects which); a GraphQL schema has no Scalar embed.
+ * Blume's per-page controls don't apply: the embed doesn't weave into the
+ * sidebar, search, or llms.txt, and it brings its own request client in place
+ * of the Try it playground.
+ */
+export declare const scalar: (options: ScalarOptions) => ScalarAdapter;