blume 1.4.3 → 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/config-input.d.ts

@@ -733,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.
@@ -966,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`,
@@ -997,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 {
@@ -1134,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;
@@ -1207,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>>;
@@ -318,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
@@ -384,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>;
@@ -456,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<{
@@ -1022,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>;
@@ -1040,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 { FolderMeta, 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
@@ -127,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;

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

@@ -114,9 +114,24 @@ export interface PageRecord {
     locale: string;
     /**
      * Locale-agnostic logical route shared by every translation (e.g.
-     * `/guides/x`). Pages with the same key are translations of each other.
+     * `/guides/x`, or `/v1.0/guides/x` under versioning — the key is
+     * version-specific, so translations group within their version).
+     * Pages with the same key are translations of each other.
      */
     translationKey: string;
+    /**
+     * Resolved docs version: an archived id (`v1.0`) for snapshot pages, `""`
+     * for the current (unprefixed) docs — including every page of an
+     * unversioned project.
+     */
+    version: string;
+    /**
+     * Version- and locale-agnostic logical route (e.g. `/guides/x` for
+     * `/v1.0/guides/x`). Pages with the same key and locale are the same
+     * logical page across versions — this drives the switcher's same-page
+     * navigation and the canonical-to-latest lookup.
+     */
+    versionKey: string;
     /**
      * True for entries filled in from the fallback locale to pad a locale's
      * navigation for pages it hasn't translated yet. The record's content —
@@ -170,7 +185,12 @@ export type NavNode = {
     label: string;
     badge?: string;
     directory?: DirectoryMode;
-    display?: SidebarDisplay;
+    /**
+     * The group's resolved render mode. Always stamped by both builders
+     * (generated and explicit-config sidebars), so the renderer can rely
+     * on it per node.
+     */
+    display: SidebarDisplay;
     icon?: string;
     route?: string;
     /**
@@ -249,6 +269,12 @@ export interface ContentGraph {
     navigation: Navigation;
     /** Navigation per locale; one entry per configured locale under i18n. */
     navigationByLocale: Record<string, Navigation>;
+    /**
+     * Navigation per archived version, keyed by version id and then locale code
+     * (`""` on a single-locale site). The current version's trees are
+     * `navigation`/`navigationByLocale`; empty when versioning is off.
+     */
+    navigationByVersion: Record<string, Record<string, Navigation>>;
     /** Map of route -> pageId for fast lookup and duplicate detection. */
     routes: Map<string, string>;
     diagnostics: Diagnostic[];
@@ -269,6 +295,12 @@ export interface LocaleSwitchOption {
     /** True when this locale has no real translation (renders fallback content). */
     untranslated: boolean;
 }
+/** A docs version a logical page exists in, for the switcher and canonicals. */
+export interface VersionAlternate {
+    /** Version id; `""` for the current (unprefixed) docs. */
+    version: string;
+    path: string;
+}
 /** A route entry written to `blume.manifest.json`. */
 export interface RouteManifestEntry {
     id: string;
@@ -296,6 +328,15 @@ export interface RouteManifestEntry {
     locale: string;
     /** Locales this logical page is genuinely translated into (excludes fallbacks). */
     alternates: RouteAlternate[];
+    /** Resolved docs version (`""` for the current docs; see `PageRecord.version`). */
+    version: string;
+    /**
+     * Versions this logical page exists in within this route's locale — the
+     * current version first, then archived versions in configured order. Drives
+     * the switcher's same-page navigation and the canonical-to-latest lookup.
+     * Empty when versioning is off.
+     */
+    versionAlternates: VersionAlternate[];
     /** True when this route renders fallback content for a missing translation. */
     fallback?: boolean;
     /** Resolved "last updated" ISO date, when the feature is enabled. */

package/dist/types/core/ui-packs/index.d.ts

@@ -10,4 +10,12 @@ import type { UIStringsOverride } from "../i18n-ui.ts";
  * `zh-TW`). A locale's pack is merged onto English by {@link resolveUIStrings},
  * so a pack only needs the keys it translates.
  */
-export declare const UI_PACKS: Record<string, UIStringsOverride>;
+/**
+ * Starter packs keyed by locale code. Open-keyed on purpose: resolvers look
+ * packs up by whatever locale a project configures, not only the codes here.
+ */
+interface UiPackRegistry {
+    [locale: string]: UIStringsOverride;
+}
+export declare const UI_PACKS: UiPackRegistry;
+export {};

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

@@ -44,9 +44,10 @@ export interface ReferenceSource {
     theme?: string;
     /**
      * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
-     * only). Takes precedence over Blume's derived spec/theme config.
+     * only). Takes precedence over Blume's derived spec/theme config. Typed off
+     * the config schema so the two can never drift.
      */
-    scalar?: Record<string, unknown>;
+    scalar?: ResolvedConfig["openapi"]["scalar"];
     /** Display options carried through to the Blume renderer. */
     display: ReferenceDisplay;
     /**
@@ -64,8 +65,8 @@ export interface ReferenceSource {
  */
 export declare const slugify: (text: string) => string;
 /**
- * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
- * by default); AsyncAPI is always rendered by Scalar for now.
+ * Resolve every enabled reference. Both blocks honor their `renderer` —
+ * Blume's own UI by default, with the embedded Scalar SPA as the opt-out.
  */
 export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSource[];
 /**
@@ -76,7 +77,7 @@ export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSou
  * targets so such a tab doesn't read as a broken link.
  */
 export declare const referenceRoutes: (config: ResolvedConfig) => string[];
-/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+/** Blume-rendered references (both kinds), deduped by route (first wins). */
 export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
 /** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
 export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;