blume 1.7.2 → 2.0.0

package/src/openapi/source.ts

@@ -27,9 +27,10 @@ import {
   parseGraphqlSpec,
   parseSpec,
 } from "./parse.ts";
-import type { ReferenceSource } from "./references.ts";
+import type { BlumeReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
+import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
  * The staged content source behind Blume's own API reference renderer (OpenAPI
@@ -38,7 +39,7 @@ import type { RenderedPage } from "./render-mdx.ts";
  * first-class Blume pages (real routes, sidebar, search, i18n, OG) and the
  * parsed documents are handed to the generated `blume:openapi` module for the
  * UI components to render. The source keeps its historical `openapi` name for
- * both kinds — downstream consumers (`ai.llmsTxt.openapi`, the llms noindex
+ * both kinds — downstream consumers (`agents.llmsTxt.openapi`, the llms noindex
  * exemption) key on it as "the generated API reference source".
  */
 
@@ -63,14 +64,14 @@ const KIND_LABELS = {
   asyncapi: "AsyncAPI",
   graphql: "GraphQL",
   openapi: "OpenAPI",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
 
 /** Diagnostic-code prefix per spec kind. */
 const CODE_PREFIXES = {
   asyncapi: "BLUME_ASYNCAPI",
   graphql: "BLUME_GRAPHQL",
   openapi: "BLUME_OPENAPI",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
 
 /**
  * Parse-level warning code per kind: an offline cache fallback for any kind,
@@ -81,7 +82,7 @@ const SPEC_WARNING_CODES = {
   asyncapi: "BLUME_ASYNCAPI_SPEC_WARNING",
   graphql: "BLUME_GRAPHQL_SPEC_WARNING",
   openapi: "BLUME_OPENAPI_STALE",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
 
 /**
  * Extract-level skip code per kind. OpenAPI keeps its historical code (the
@@ -92,7 +93,7 @@ const SKIPPED_CODES = {
   asyncapi: "BLUME_ASYNCAPI_SKIPPED_OPERATION",
   graphql: "BLUME_GRAPHQL_SKIPPED",
   openapi: "BLUME_OPENAPI_REF_PATH_ITEM",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
 
 /** `_EMPTY` diagnostic suggestion per kind. */
 const EMPTY_SUGGESTIONS = {
@@ -102,7 +103,7 @@ const EMPTY_SUGGESTIONS = {
     "Check the spec points at a GraphQL schema (SDL or introspection JSON) whose root types declare fields.",
   openapi:
     "Check the spec points at an OpenAPI document with operations under `paths`.",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
 
 /** `_UNAVAILABLE` suggestion for a readable-but-invalid spec, per kind. */
 const INVALID_SUGGESTIONS = {
@@ -112,7 +113,26 @@ const INVALID_SUGGESTIONS = {
     "Point the spec at a GraphQL schema — SDL text or an introspection JSON result.",
   openapi:
     "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level).",
-} satisfies Record<ReferenceSource["kind"], string>;
+} satisfies Record<BlumeReferenceSource["kind"], string>;
+
+/**
+ * What to suggest for a spec that failed to load: the install command when
+ * reading it needs a package the project lacks, a fix to the file when it
+ * isn't a spec of its kind, and reachability for everything else (a fetch or
+ * read failure).
+ */
+const failureSuggestion = (
+  error: Error,
+  kind: BlumeReferenceSource["kind"]
+): string => {
+  if (error instanceof SpecDependencyError) {
+    return error.suggestion;
+  }
+  if (error instanceof InvalidSpecError) {
+    return INVALID_SUGGESTIONS[kind];
+  }
+  return "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.";
+};
 
 const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
   const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
@@ -131,7 +151,7 @@ const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
 const specEntries = (
   spec: ApiSpecData,
   operations: ApiOperationRef[],
-  reference: ReferenceSource
+  reference: BlumeReferenceSource
 ): SourceEntry[] => {
   const entries = operations.map((operation) =>
     toEntry(
@@ -193,7 +213,7 @@ interface ParsedReference {
 }
 
 const parseReference = async (
-  reference: ReferenceSource,
+  reference: BlumeReferenceSource,
   ctx: SourceContext
 ): Promise<ParsedReference> => {
   const options = { cacheDir: ctx.cacheDir, refresh: ctx.refresh };
@@ -243,13 +263,13 @@ const parseReference = async (
 };
 
 export const openApiSource = (
-  references: ReferenceSource[],
+  references: BlumeReferenceSource[],
   ctx: SourceContext
 ): OpenApiContentSource => {
   let parsed: OpenApiData = {};
 
   const loadReference = async (
-    reference: ReferenceSource
+    reference: BlumeReferenceSource
   ): Promise<LoadedSpec | Diagnostic> => {
     // Human label and diagnostic-code prefix for the spec's kind, so an
     // AsyncAPI failure never reads as an OpenAPI one.
@@ -335,21 +355,17 @@ export const openApiSource = (
         spec,
       };
     } catch (error) {
+      // SAFETY: spec loading fails with Error instances (fetch, read, parse,
+      // and missing-package errors alike).
+      const failure = error as Error;
       return {
         code: `${codePrefix}_UNAVAILABLE`,
-        // SAFETY: spec loading fails with Error instances (fetch, read, and
-        // parse errors alike); only the message is read for the diagnostic.
-        message: `Could not load ${kindLabel} spec "${reference.spec}" for ${reference.route} (${(error as Error).message}); its reference pages were skipped.`,
+        message: `Could not load ${kindLabel} spec "${reference.spec}" for ${reference.route} (${failure.message}); its reference pages were skipped.`,
         // A configured-but-unloadable spec ships a dead nav tab (a 404 route),
         // so fail loudly in build (blocks under --strict) while staying a warning
         // in dev so offline work still runs.
         severity: ctx.mode === "build" ? "error" : "warning",
-        // A readable-but-invalid file is a content problem, not a network one;
-        // only point at reachability for actual fetch/read failures.
-        suggestion:
-          error instanceof InvalidSpecError
-            ? INVALID_SUGGESTIONS[reference.kind]
-            : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
+        suggestion: failureSuggestion(failure, reference.kind),
       };
     }
   };

package/src/openapi/spec-dependency-error.ts

@@ -0,0 +1,15 @@
+/**
+ * Reading a spec needs an optional package the project hasn't installed (the
+ * AsyncAPI converter, for a pre-3.0 document). Carries its own suggestion —
+ * the install command — because neither of the other spec failures fits: the
+ * file is fine and so is the network.
+ */
+export class SpecDependencyError extends Error {
+  readonly suggestion: string;
+
+  constructor(message: string, suggestion: string) {
+    super(message);
+    this.name = "SpecDependencyError";
+    this.suggestion = suggestion;
+  }
+}

package/src/reference/asyncapi.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import {
+  liftSpec,
+  referenceSourceSchema,
+  hasSources,
+  missingSourcesIssue,
+  rendererRemovedHint,
+  sharedOptions,
+} from "./options.ts";
+import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
+
+/** Options for {@link asyncapi}. */
+export interface AsyncApiOptions {
+  /**
+   * Code-sample tools shown per operation (Blume renderer). Defaults to every
+   * tool appropriate to the operation's protocol binding.
+   */
+  codeSamples?: string[];
+  /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
+  expandSchemas?: boolean;
+  /**
+   * The "Try it" message composer (Blume renderer). On by default; `false`
+   * hides it. `proxy` is accepted for parity but doesn't apply to event
+   * operations — a WebSocket connect goes straight from the browser.
+   */
+  playground?: PlaygroundOptions;
+  /** Where the reference mounts. Defaults to `/events`. */
+  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 const asyncapiOptionsSchema = z
+  .strictObject(
+    {
+      // Empty `codeSamples` means every tool the operation's protocol binding
+      // suggests.
+      ...sharedOptions({ codeSamples: [], route: "/events" }),
+      /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+      expandSchemas: z.boolean().default(false),
+      /** One or more specs; each renders on its own route by default. */
+      sources: z.array(referenceSourceSchema).default([]),
+    },
+    rendererRemovedHint
+  )
+  .transform(liftSpec(referenceSourceSchema))
+  .refine(hasSources, missingSourcesIssue("asyncapi"));
+
+/** `asyncapi()` options with every default applied and `spec` folded into `sources`. */
+export type ResolvedAsyncApiOptions = z.output<typeof asyncapiOptionsSchema>;
+
+export type AsyncApiAdapter = AdapterDescriptor<"asyncapi", AsyncApiOptions>;
+
+/** An `asyncapi()` descriptor as the config schema resolves it. */
+export type ResolvedAsyncApiAdapter = AdapterDescriptor<
+  "asyncapi",
+  ResolvedAsyncApiOptions
+>;
+
+export const asyncapiAdapterSchema = adapterDescriptorSchema(
+  "asyncapi",
+  asyncapiOptionsSchema
+);
+
+/**
+ * An AsyncAPI reference. Blume normalizes the spec to AsyncAPI 3.x and renders
+ * its own UI — one real page per operation, in the sidebar, search, llms.txt,
+ * and OG; a `scalar()` adapter is the embedded-SPA alternative. Only the
+ * defaults differ from `openapi()`: the reference mounts at `/events`, and
+ * empty `codeSamples` means every tool the operation's protocol binding
+ * suggests.
+ */
+export const asyncapi = (options: AsyncApiOptions): AsyncApiAdapter => ({
+  kind: "asyncapi",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/reference/graphql.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import {
+  graphqlSourceSchema,
+  liftSpec,
+  hasSources,
+  missingSourcesIssue,
+  sharedOptions,
+} from "./options.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 const graphqlOptionsSchema = z
+  .strictObject({
+    ...sharedOptions({
+      codeSamples: ["curl", "js", "python"],
+      route: "/graphql",
+    }),
+    /** Default live endpoint URL for every source (per-source `endpoint` wins). */
+    endpoint: z.string().optional(),
+    /** One or more schemas; each renders on its own route by default. */
+    sources: z.array(graphqlSourceSchema).default([]),
+  })
+  .transform(liftSpec(graphqlSourceSchema))
+  .refine(hasSources, missingSourcesIssue("graphql"));
+
+/** `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 const graphqlAdapterSchema = adapterDescriptorSchema(
+  "graphql",
+  graphqlOptionsSchema
+);
+
+/**
+ * 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 const graphql = (options: GraphqlOptions): GraphqlAdapter => ({
+  kind: "graphql",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/reference/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 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/src/reference/openapi.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import {
+  liftSpec,
+  referenceSourceSchema,
+  hasSources,
+  missingSourcesIssue,
+  rendererRemovedHint,
+  sharedOptions,
+} from "./options.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 const openapiOptionsSchema = z
+  .strictObject(
+    {
+      ...sharedOptions({
+        codeSamples: ["curl", "js", "python"],
+        route: "/reference",
+      }),
+      /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+      expandSchemas: z.boolean().default(false),
+      /** One or more specs; each renders on its own route by default. */
+      sources: z.array(referenceSourceSchema).default([]),
+    },
+    rendererRemovedHint
+  )
+  .transform(liftSpec(referenceSourceSchema))
+  .refine(hasSources, missingSourcesIssue("openapi"));
+
+/** `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 const openapiAdapterSchema = adapterDescriptorSchema(
+  "openapi",
+  openapiOptionsSchema
+);
+
+/**
+ * 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 const openapi = (options: OpenApiOptions): OpenApiAdapter => ({
+  kind: "openapi",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/reference/options.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+
+import { unrecognizedKeysMessage } from "../core/unrecognized-keys.ts";
+
+/**
+ * The option pieces every reference adapter shares: a spec source, the "Try
+ * it" playground normalization, and the `spec` shorthand that folds into
+ * `sources` at parse. Kept apart from the kind modules so `openapi()`,
+ * `asyncapi()`, and `graphql()` validate one definition of each.
+ */
+
+const isBoolean = <Value>(value: Value): value is Value & boolean =>
+  typeof value === "boolean";
+
+/**
+ * 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 const referenceSourceSchema = z.strictObject({
+  /** Include generated pages from this spec in llms.txt/llms-full.txt. */
+  includeInLlms: z.boolean().default(true),
+  /** Include generated pages from this spec in site search. */
+  includeInSearch: z.boolean().default(true),
+  /** Nav/section label for this source. */
+  label: z.string().optional(),
+  /** Emit noindex metadata and omit generated pages from the sitemap. */
+  noindex: z.boolean().default(false),
+  /** Per-source route; defaults to the adapter's `route` (or a derived path). */
+  route: z.string().optional(),
+  /**
+   * Append the English "Reference for the … endpoint in the … API." sentence
+   * to every generated operation page's meta description. On by default, so
+   * terse specs still ship distinct, snippet-length descriptions; set to
+   * `false` on a non-English site to describe pages with the spec's own prose
+   * alone (falling back to the page title when an operation has none).
+   */
+  seoDescriptionSuffix: z.boolean().default(true),
+  /** Local path or `http(s)` URL to the spec. */
+  spec: z.string(),
+});
+
+/** 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 const graphqlSourceSchema = referenceSourceSchema.extend({
+  /** URL of the live GraphQL endpoint (playground + code samples). */
+  endpoint: z.string().optional(),
+});
+
+/** 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 const playgroundSchema = z
+  .union([
+    z.boolean(),
+    z.strictObject({
+      enabled: z.boolean().default(true),
+      proxy: z.union([z.boolean(), z.string()]).default(false),
+    }),
+  ])
+  .default(true)
+  .transform((value) =>
+    isBoolean(value) ? { enabled: value, proxy: false } : value
+  );
+
+/** 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 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" — `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 const rendererRemovedHint = {
+  error: (issue: z.core.$ZodRawIssue): string | undefined => {
+    if (
+      issue.code !== "unrecognized_keys" ||
+      !issue.keys.includes("renderer")
+    ) {
+      return;
+    }
+    const others = issue.keys.filter((key) => key !== "renderer");
+    return others.length > 0
+      ? `${RENDERER_REMOVED_HINT} ${unrecognizedKeysMessage(others)}`
+      : RENDERER_REMOVED_HINT;
+  },
+};
+
+/**
+ * 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 const sharedOptions = (defaults: {
+  codeSamples: string[];
+  route: string;
+}) => ({
+  /** Code-sample languages/tools shown per operation (Blume renderer). */
+  codeSamples: z.array(z.string()).default(defaults.codeSamples),
+  /** The "Try it" panel; see {@link playgroundSchema}. */
+  playground: playgroundSchema,
+  /** Where the reference mounts. */
+  route: z.string().default(defaults.route),
+  /** Shorthand for a single source: `sources: [{ spec }]`. */
+  spec: z.string().optional(),
+});
+
+/**
+ * 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 const liftSpec =
+  <Source extends { spec: string }>(
+    sourceSchema: z.ZodType<Source, { spec: string }>
+  ) =>
+  <Options extends { sources: Source[]; spec?: string }>({
+    spec,
+    ...options
+  }: Options): Omit<Options, "spec"> => ({
+    ...options,
+    sources:
+      spec === undefined
+        ? options.sources
+        : [sourceSchema.parse({ spec }), ...options.sources],
+  });
+
+/** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */
+export const hasSources = (options: { sources: { spec: string }[] }): boolean =>
+  options.sources.length > 0;
+
+/** The refinement issue for a source-less adapter, naming its factory. */
+export const missingSourcesIssue = (factory: string) => ({
+  message: `${factory}() renders nothing without a spec — set \`spec\` or at least one \`sources\` entry.`,
+  path: ["sources"],
+});