blume 1.4.2 → 1.5.0

package/dist/types/ai/component-markdown.d.ts

@@ -1,8 +1,16 @@
 import type { ExampleLookup } from "../core/types.ts";
+/**
+ * A statically-recovered data value. Parsed front matter and evaluated
+ * attribute literals are both plain data — scalars, dates, arrays, and
+ * nested maps — never functions or class instances.
+ */
+export type EvaluatedValue = string | number | boolean | null | undefined | Date | EvaluatedValue[] | {
+    [key: string]: EvaluatedValue;
+};
 /** Evaluated props plus whether any attribute resisted static evaluation. */
 interface EvaluatedProps {
     lossy: boolean;
-    props: Record<string, unknown>;
+    props: Record<string, EvaluatedValue>;
 }
 /** A child component extracted by name (e.g. each `<Step>` under `<Steps>`). */
 export interface ComponentMarkdownChild extends EvaluatedProps {
@@ -20,7 +28,7 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
      * serializer read page metadata directly, even when a prop expression is
      * not statically evaluable.
      */
-    frontmatter: Record<string, unknown>;
+    frontmatter: Record<string, EvaluatedValue>;
 }
 /**
  * A component's Markdown serializer. Return the replacement Markdown, or
@@ -36,7 +44,9 @@ export type ComponentMarkdown = (context: ComponentMarkdownContext) => string |
  * the JSX verbatim, mirroring the "no example found" note the component renders
  * on the page.
  */
-export declare const exampleComponentSerializers: (examples: ExampleLookup) => Record<string, ComponentMarkdown>;
+export declare const exampleComponentSerializers: (examples: ExampleLookup) => {
+    Component: ({ props }: ComponentMarkdownContext) => string | null;
+};
 /**
  * Downlevel supported components in an MDX source to plain Markdown. Sources
  * with no supported components — and sources Satteri can't parse as MDX, e.g.
@@ -51,5 +61,5 @@ export declare const exampleComponentSerializers: (examples: ExampleLookup) => R
  * resolves the way it does when Astro renders the page — and handed to
  * serializers on their context.
  */
-export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>, frontmatter?: Record<string, unknown>) => string;
+export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>, frontmatter?: Record<string, EvaluatedValue>) => string;
 export {};

package/dist/types/core/base-path.d.ts

@@ -22,6 +22,14 @@ export declare const normalizeBasePath: (input?: string) => string;
  * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
  */
 export declare const normalizePath: (path: string) => string;
+/**
+ * Canonicalize a route-ish string (a configured route, a page path, an agent-
+ * supplied route) to `/` or `/seg[/seg…]`: trimmed, exactly one leading slash,
+ * no trailing slash. The shared spelling of what openapi/references,
+ * ai/ask-context, and ai/mcp/server each hand-rolled with slightly different
+ * regexes.
+ */
+export declare const normalizeRoute: (input: string) => string;
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/dist/types/core/config-input.d.ts

@@ -171,6 +171,8 @@ export interface SanitySource {
 /** A Notion database; pages become entries, blocks become MDX. */
 export interface NotionSource {
     type: "notion";
+    /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+    concurrency?: number;
     /** Notion database id. */
     database: string;
     /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
@@ -565,6 +567,12 @@ export interface AskConfig {
      * limiting, and streaming. Accepts an absolute URL or root-relative path.
      */
     endpoint?: string;
+    /**
+     * Extra system-prompt text appended to the built-in instructions — use it
+     * for identity, language, or tone. The built-in grounding behavior (answer
+     * from the retrieved excerpts, cite pages as Markdown links) is preserved.
+     */
+    instructions?: string;
     /** Model id to use. Defaults to `openai/gpt-5.5`. */
     model?: string;
     /** Which backend routes the request. Defaults to `gateway`. */
@@ -725,6 +733,53 @@ export interface I18nConfig {
      */
     ui?: Record<string, Record<string, Record<string, string>>>;
 }
+/** A frozen documentation snapshot: a directory under the content root. */
+export interface ArchivedVersionInput {
+    /**
+     * The "you're viewing an old version" notice: `true` (default) for the
+     * built-in message, a string for custom copy, `false` to hide it.
+     */
+    banner?: boolean | string;
+    /**
+     * Where this version's pages point their canonical URL. `latest` (default)
+     * targets the same page in the current docs when it still exists (self
+     * otherwise); `self` keeps every page authoritative.
+     */
+    canonical?: "latest" | "self";
+    /**
+     * Directory name under the content root, and the URL segment. Must start
+     * with a letter (e.g. `v1.0`).
+     */
+    id: string;
+    /** Switcher label; defaults to the id. */
+    label?: string;
+    /** Emit `noindex` on every page of this version. Defaults to `false`. */
+    noindex?: boolean;
+}
+/**
+ * Docs versioning. Opt-in: the latest docs live at the content root with
+ * unprefixed URLs, and each archived version is a frozen snapshot directory
+ * (`content/docs/<id>/`) cut with `blume version <id>`. Archived means frozen:
+ * snapshots carry their own translations and are never retranslated.
+ */
+export interface VersionsConfig {
+    /** Frozen snapshots, newest first — this order is the switcher order. */
+    archived?: ArchivedVersionInput[];
+    /** Labels the unprefixed tree (the latest docs) in the switcher. */
+    current: {
+        /** Small tag rendered next to the label (e.g. `Latest`). */
+        badge?: string;
+        label: string;
+    };
+    switcher?: {
+        /**
+         * Where switching lands when the page has no equivalent in the target
+         * version: `same-page` (default) goes to the equivalent when it exists
+         * (version root otherwise); `root` always goes to the version root.
+         */
+        redirect?: "same-page" | "root";
+    };
+}
 /**
  * Where and how the site deploys. `site` (and `adapter`) are auto-detected from
  * the platform env on Vercel, Netlify, and Cloudflare.
@@ -958,22 +1013,17 @@ export interface ReactConfig {
     compiler?: boolean;
 }
 /**
- * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:
- * one real page per operation, grouped by tag in the sidebar and included in
- * search, llms.txt, and OG. Set `renderer: "scalar"` for the embedded Scalar
- * SPA (a single self-contained route).
+ * The shared shape of both API-reference blocks (`openapi`, `asyncapi`). Only
+ * the per-block defaults differ; those are documented on the extending
+ * interfaces.
  */
-export interface OpenApiConfig {
-    /** Code-sample languages shown per operation (Blume renderer). */
-    codeSamples?: string[];
+interface ReferenceConfig {
     /** Turn the reference on. Defaults to `false`. */
     enabled?: boolean;
     /** Start nested schema rows expanded (Blume renderer). Defaults to `false`. */
     expandSchemas?: boolean;
     /** Who renders the reference. Defaults to `blume`. */
     renderer?: "blume" | "scalar";
-    /** Where the reference mounts. Defaults to `/reference`. */
-    route?: string;
     /**
      * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`
      * (Scalar renderer only) — e.g. `localization`, `agent`,
@@ -989,27 +1039,35 @@ export interface OpenApiConfig {
     theme?: string;
 }
 /**
- * AsyncAPI reference, rendered via the embedded Scalar SPA (which auto-detects
- * the document type). Same shape as {@link OpenApiConfig}; only the default
- * `route` differs.
+ * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:
+ * one real page per operation, grouped by tag in the sidebar and included in
+ * search, llms.txt, and OG. Set `renderer: "scalar"` for the embedded Scalar
+ * SPA (a single self-contained route).
  */
-export interface AsyncApiConfig {
-    /** Turn the reference on. Defaults to `false`. */
-    enabled?: boolean;
-    /** Where the reference mounts. Defaults to `/events`. */
+export interface OpenApiConfig extends ReferenceConfig {
+    /**
+     * Code-sample languages shown per operation (Blume renderer). Defaults to
+     * `["curl", "js", "python"]`.
+     */
+    codeSamples?: string[];
+    /** Where the reference mounts. Defaults to `/reference`. */
     route?: string;
+}
+/**
+ * AsyncAPI reference. Same shape as {@link OpenApiConfig}: by default
+ * (`renderer: "blume"`) Blume normalizes the spec to AsyncAPI 3.x and renders
+ * its own UI — one real page per operation, grouped by tag (or channel) in the
+ * sidebar and included in search, llms.txt, and OG. Set `renderer: "scalar"`
+ * for the embedded Scalar SPA (a single self-contained route).
+ */
+export interface AsyncApiConfig extends ReferenceConfig {
     /**
-     * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`.
-     * These win over Blume's derived spec/theme config — a full escape hatch to
-     * Scalar's API.
+     * Code-sample tools shown per operation (Blume renderer). Defaults to every
+     * tool appropriate to the operation's protocol binding.
      */
-    scalar?: Record<string, unknown>;
-    /** One or more specs. */
-    sources?: OpenApiSource[];
-    /** Shorthand for a single source. */
-    spec?: string;
-    /** Scalar theme name. */
-    theme?: string;
+    codeSamples?: string[];
+    /** Where the reference mounts. Defaults to `/events`. */
+    route?: string;
 }
 /** `<Component />` example previews (the object form of `examples`). */
 export interface ExamplesConfig {
@@ -1126,7 +1184,7 @@ export interface BlumeConfig {
     ai?: AiConfig;
     /** Analytics providers (PostHog, Vercel, or arbitrary scripts). */
     analytics?: AnalyticsConfig;
-    /** AsyncAPI reference (embedded Scalar renderer). */
+    /** AsyncAPI reference (native renderer by default, Scalar opt-out). */
     asyncapi?: AsyncApiConfig;
     /** Site-wide announcement banner shown above the header. */
     banner?: BannerConfig;
@@ -1199,5 +1257,7 @@ export interface BlumeConfig {
     title?: string;
     /** On-page table of contents. Defaults to on (H2–H3). */
     toc?: TocConfig;
+    /** Docs versioning (opt-in frozen snapshots with a version switcher). */
+    versions?: VersionsConfig;
 }
 export {};

package/dist/types/core/config.d.ts

@@ -60,7 +60,8 @@ import type { Diagnostic } from "./types.ts";
  * **Reference docs**
  * - `openapi` — native OpenAPI reference: one real page per operation, woven
  *   into the sidebar and search. Point `sources`/`spec` at your spec.
- * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ * - `asyncapi` — native AsyncAPI reference with the same treatment; 2.x specs
+ *   are normalized to 3.x automatically.
  *
  * **Search & AI**
  * - `search` — search backend `provider` (`orama` by default; `pagefind`,

package/dist/types/core/data.d.ts

@@ -1,6 +1,6 @@
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
-import type { Navigation, RouteAlternate } from "./types.ts";
+import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 /**
  * The shape of the `blume:data` virtual module — the resolved, serializable
  * snapshot of a site that custom `.astro` pages read with
@@ -86,6 +86,14 @@ export interface BlumeRoute {
     locale: string;
     path: string;
     title: string;
+    /** Resolved docs version (`""` for the current docs). */
+    version: string;
+    /**
+     * Versions this logical page exists in within this route's locale — the
+     * current version first, then archived versions in configured order. Empty
+     * when versioning is off.
+     */
+    versionAlternates: VersionAlternate[];
 }
 /** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
 export interface BlumeDataConfig {
@@ -171,6 +179,8 @@ export interface BlumeDataConfig {
      * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
      * list tool to fetch (`ai.llmsTxt.enabled`).
      */
+    /** Docs versioning config; `null` when the site is unversioned. */
+    versions: NonNullable<ResolvedConfig["versions"]> | null;
     webmcp: {
         enabled: boolean;
         llms: boolean;
@@ -205,6 +215,11 @@ export interface BlumeData {
     navigation: Navigation;
     /** Per-locale navigation trees, keyed by locale code (empty without i18n). */
     navigationByLocale: Record<string, Navigation>;
+    /**
+     * Per-archived-version navigation trees, keyed by version id and then locale
+     * code (`""` on a single-locale site). Empty when versioning is off.
+     */
+    navigationByVersion: Record<string, Record<string, Navigation>>;
     routes: BlumeRoute[];
     /** Resolved UI strings for the default locale. */
     ui: UIStrings;

package/dist/types/core/diagnostics.d.ts

@@ -42,4 +42,8 @@ export declare const diagnosticsFromZod: (error: ZodError, options: {
 /** Format a single diagnostic for terminal output. */
 export declare const formatDiagnostic: (diagnostic: Diagnostic, root?: string) => string;
 export declare const hasErrors: (diagnostics: Diagnostic[]) => boolean;
-export declare const countBySeverity: (diagnostics: Diagnostic[]) => Record<Diagnostic["severity"], number>;
+export declare const countBySeverity: (diagnostics: Diagnostic[]) => {
+    error: number;
+    info: number;
+    warning: number;
+};

package/dist/types/core/i18n-ui.d.ts

@@ -91,6 +91,7 @@ declare const uiStringsObject: z.ZodObject<{
     search: z.ZodPrefault<z.ZodObject<{
         all: z.ZodDefault<z.ZodString>;
         allLanguages: z.ZodDefault<z.ZodString>;
+        allVersions: z.ZodDefault<z.ZodString>;
         askAi: z.ZodDefault<z.ZodString>;
         askAiHint: z.ZodDefault<z.ZodString>;
         button: z.ZodDefault<z.ZodString>;
@@ -108,6 +109,11 @@ declare const uiStringsObject: z.ZodObject<{
     toc: z.ZodPrefault<z.ZodObject<{
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
+    versions: z.ZodPrefault<z.ZodObject<{
+        latest: z.ZodDefault<z.ZodString>;
+        notice: z.ZodDefault<z.ZodString>;
+        switcher: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
     actions: z.ZodPrefault<z.ZodObject<{
@@ -193,6 +199,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
     search: z.ZodPrefault<z.ZodObject<{
         all: z.ZodDefault<z.ZodString>;
         allLanguages: z.ZodDefault<z.ZodString>;
+        allVersions: z.ZodDefault<z.ZodString>;
         askAi: z.ZodDefault<z.ZodString>;
         askAiHint: z.ZodDefault<z.ZodString>;
         button: z.ZodDefault<z.ZodString>;
@@ -210,6 +217,11 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
     toc: z.ZodPrefault<z.ZodObject<{
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
+    versions: z.ZodPrefault<z.ZodObject<{
+        latest: z.ZodDefault<z.ZodString>;
+        notice: z.ZodDefault<z.ZodString>;
+        switcher: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>>;
 /** A fully-resolved dictionary; every key present. */
 export type UIStrings = z.infer<typeof uiStringsObject>;

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

@@ -12,6 +12,19 @@ declare const hydrationMode: z.ZodEnum<{
     only: "only";
 }>;
 export type HydrationMode = z.infer<typeof hydrationMode>;
+/**
+ * How a sidebar group renders:
+ * - `flat`: a non-collapsible header with its items listed beneath (default).
+ * - `group`: a collapsible `<details>` disclosure.
+ * - `page`: a single row that drills into a sub-panel showing only this group's
+ *   items, with a back arrow at the top.
+ */
+declare const sidebarDisplaySchema: z.ZodEnum<{
+    flat: "flat";
+    group: "group";
+    page: "page";
+}>;
+export type SidebarDisplay = z.infer<typeof sidebarDisplaySchema>;
 /** Frontmatter accepted on any content page. */
 declare const pageMetaBaseSchema: z.ZodObject<{
     ai: z.ZodPrefault<z.ZodObject<{
@@ -58,6 +71,11 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     }, z.core.$strict>>;
     sidebar: z.ZodPrefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodEnum<{
+            flat: "flat";
+            group: "group";
+            page: "page";
+        }>>;
         hidden: z.ZodDefault<z.ZodBoolean>;
         icon: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
@@ -112,6 +130,11 @@ export declare const pageMetaSchema: z.ZodObject<{
     }, z.core.$strict>>;
     sidebar: z.ZodPrefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodEnum<{
+            flat: "flat";
+            group: "group";
+            page: "page";
+        }>>;
         hidden: z.ZodDefault<z.ZodBoolean>;
         icon: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
@@ -123,21 +146,13 @@ export declare const pageMetaSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
-/**
- * How a sidebar group renders:
- * - `flat`: a non-collapsible header with its items listed beneath (default).
- * - `group`: a collapsible `<details>` disclosure.
- * - `page`: a single row that drills into a sub-panel showing only this group's
- *   items, with a back arrow at the top.
- */
-declare const sidebarDisplaySchema: z.ZodEnum<{
-    flat: "flat";
-    group: "group";
-    page: "page";
-}>;
-export type SidebarDisplay = z.infer<typeof sidebarDisplaySchema>;
 export declare const folderMetaSchema: z.ZodObject<{
     collapsed: z.ZodOptional<z.ZodBoolean>;
+    display: z.ZodOptional<z.ZodEnum<{
+        flat: "flat";
+        group: "group";
+        page: "page";
+    }>>;
     icon: z.ZodOptional<z.ZodString>;
     order: z.ZodOptional<z.ZodNumber>;
     pages: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -189,6 +204,7 @@ declare const contentSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     query: z.ZodString;
     type: z.ZodLiteral<"sanity">;
 }, z.core.$strip>, z.ZodObject<{
+    concurrency: z.ZodOptional<z.ZodNumber>;
     database: z.ZodString;
     pollInterval: z.ZodOptional<z.ZodNumber>;
     prefix: z.ZodOptional<z.ZodString>;
@@ -244,6 +260,7 @@ declare const aiConfigSchema: z.ZodObject<{
         baseUrl: z.ZodOptional<z.ZodURL>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         endpoint: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
         model: z.ZodDefault<z.ZodString>;
         provider: z.ZodDefault<z.ZodEnum<{
             gateway: "gateway";
@@ -316,6 +333,52 @@ declare const i18nConfigSchema: z.ZodObject<{
     }>>;
     ui: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>>;
 }, z.core.$strict>;
+/**
+ * Version ids must start with a letter (`v1.0`, not `1.0`): the id doubles as
+ * the snapshot directory name, and a leading digit would collide with the
+ * numeric-prefix ordering convention (`01-intro.mdx`), which strips `1.0/` to
+ * `0/`. The rest allows word characters, dots, and hyphens — URL-safe as-is.
+ */
+export declare const VERSION_ID: RegExp;
+/** A frozen documentation snapshot: a directory under the content root. */
+declare const archivedVersionSchema: z.ZodObject<{
+    banner: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    canonical: z.ZodDefault<z.ZodEnum<{
+        latest: "latest";
+        self: "self";
+    }>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * Docs versioning. Opt-in: the latest docs live at the content root with
+ * unprefixed URLs, and each archived version is a frozen snapshot directory
+ * (`content/docs/<id>/`) cut with `blume version <id>`. Archived means frozen:
+ * snapshots carry their own translations and are never retranslated.
+ */
+declare const versionsConfigSchema: z.ZodObject<{
+    archived: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        banner: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        canonical: z.ZodDefault<z.ZodEnum<{
+            latest: "latest";
+            self: "self";
+        }>>;
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        noindex: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    current: z.ZodObject<{
+        badge: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+    }, z.core.$strict>;
+    switcher: z.ZodPrefault<z.ZodObject<{
+        redirect: z.ZodDefault<z.ZodEnum<{
+            root: "root";
+            "same-page": "same-page";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /**
  * Content signals accept a boolean shorthand or a per-signal object, and
  * normalize to `{ search, aiInput, aiTrain }` — or `null` when disabled, so
@@ -382,7 +445,8 @@ declare const dateFormatConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 /**
  * A single spec rendered by the API reference. `spec` is a local path or an
- * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
+ * `http(s)` URL (an OpenAPI document under `openapi`, an AsyncAPI document
+ * under `asyncapi`).
  */
 declare const openapiSourceSchema: z.ZodObject<{
     includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -400,6 +464,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             baseUrl: z.ZodOptional<z.ZodURL>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             endpoint: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodString>;
             model: z.ZodDefault<z.ZodString>;
             provider: z.ZodDefault<z.ZodEnum<{
                 gateway: "gateway";
@@ -453,7 +518,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
         vercel: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     asyncapi: z.ZodPrefault<z.ZodObject<{
+        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        renderer: z.ZodDefault<z.ZodEnum<{
+            blume: "blume";
+            scalar: "scalar";
+        }>>;
         route: z.ZodDefault<z.ZodString>;
         scalar: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -527,6 +598,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             query: z.ZodString;
             type: z.ZodLiteral<"sanity">;
         }, z.core.$strip>, z.ZodObject<{
+            concurrency: z.ZodOptional<z.ZodNumber>;
             database: z.ZodString;
             pollInterval: z.ZodOptional<z.ZodNumber>;
             prefix: z.ZodOptional<z.ZodString>;
@@ -1018,13 +1090,38 @@ export declare const blumeConfigSchema: z.ZodObject<{
         maxHeadingLevel: z.ZodOptional<z.ZodNumber>;
         minHeadingLevel: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>]>>, z.ZodTransform<{
-        enabled: boolean;
+        enabled: (boolean | {
+            maxHeadingLevel?: number | undefined;
+            minHeadingLevel?: number | undefined;
+        }) & boolean;
         maxLevel: number;
         minLevel: number;
     }, boolean | {
         maxHeadingLevel?: number | undefined;
         minHeadingLevel?: number | undefined;
     }>>;
+    versions: z.ZodOptional<z.ZodObject<{
+        archived: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            banner: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+            canonical: z.ZodDefault<z.ZodEnum<{
+                latest: "latest";
+                self: "self";
+            }>>;
+            id: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            noindex: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        current: z.ZodObject<{
+            badge: z.ZodOptional<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+        switcher: z.ZodPrefault<z.ZodObject<{
+            redirect: z.ZodDefault<z.ZodEnum<{
+                root: "root";
+                "same-page": "same-page";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Resolved config: every field present after defaults are applied. */
 export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
@@ -1036,6 +1133,10 @@ export type FrontmatterExtend = Record<string, StandardSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
+/** Resolved versions block (present only when the project opts into versioning). */
+export type ResolvedVersionsConfig = z.infer<typeof versionsConfigSchema>;
+/** A configured archived (frozen) version. */
+export type ArchivedVersionConfig = z.infer<typeof archivedVersionSchema>;
 /**
  * User-authored config, straight off the schema. The public, hand-documented
  * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time

package/dist/types/core/sources/types.d.ts

@@ -1,4 +1,4 @@
-import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
+import type { FolderMeta, FrontmatterExtend, ResolvedI18nConfig, ResolvedVersionsConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 /**
  * A single content item, normalized by a source adapter. Adapters lower their
@@ -41,6 +41,14 @@ export interface SourceLoadResult {
     entries: SourceEntry[];
     /** Source-level diagnostics (e.g. an offline cache fallback warning). */
     diagnostics: Diagnostic[];
+    /**
+     * Folder meta the source derives for the sidebar groups its entries create,
+     * keyed by locale-stripped group path (the `meta.ts` key space). The OpenAPI
+     * source labels each tag directory with the spec's own tag name, so the
+     * sidebar shows `OAuth2`/`Größe` instead of a re-humanized slug. Merged
+     * beneath user-authored meta files, which always win.
+     */
+    folderMeta?: Record<string, FolderMeta>;
 }
 /**
  * Per-source runtime context, handed to an adapter factory at construction so
@@ -119,4 +127,6 @@ export interface NormalizeContext {
      * applied to a page only when its resolved `type` matches.
      */
     typeFrontmatter?: Record<string, FrontmatterExtend>;
+    /** Docs versioning config; a leading archived-version dir becomes the page's version. */
+    versions?: ResolvedVersionsConfig;
 }

package/dist/types/core/standard-schema.d.ts

@@ -30,12 +30,16 @@ export interface StandardSchema<Input = unknown, Output = Input> {
     readonly "~standard": {
         readonly version: 1;
         readonly vendor: string;
-        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly validate: (value: Input) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
         readonly types?: {
             readonly input: Input;
             readonly output: Output;
         } | undefined;
     };
 }
-/** Whether a config-supplied value implements the `~standard` contract. */
-export declare const isStandardSchema: (value: unknown) => value is StandardSchema;
+/**
+ * Whether a config-supplied value implements the `~standard` contract. Generic
+ * so it can decode any input at the config boundary (`z.custom` hands it the
+ * raw config value) while narrowing whatever type the caller holds.
+ */
+export declare const isStandardSchema: <T>(value: T) => value is T & StandardSchema;