blume 2.1.2 → 2.2.0

package/dist/types/deploy/generated-files.d.ts

@@ -0,0 +1,41 @@
+import type { SkillArtifact } from "../ai/skills.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+/** A generated `.well-known` discovery document: `null` content when it's off. */
+export interface WellKnownFile {
+    content: string | null;
+    label: string;
+    path: string;
+}
+/**
+ * The generated `.well-known` discovery documents — the Web Bot Auth signature
+ * directory, the RFC 9727 API catalog, and the AI catalog under both the
+ * ai-catalog spec's well-known URI and the ARD v0.91 one (see
+ * `ai/ai-catalog.ts`) — each with `null` content when its feature is off.
+ */
+export declare const wellKnownFiles: (config: ResolvedConfig, skills: readonly SkillArtifact[]) => WellKnownFile[];
+/**
+ * The files a build serves beside its pages that don't come from `public/`,
+ * as base-less root-relative paths: what `publishBuildArtifacts` writes once
+ * Astro is done (llms.txt, the sitemap, robots.txt, `agent-readability.json`,
+ * the `.well-known` discovery documents, the Agent Skills index, `skill.md`)
+ * and the generated endpoints at fixed paths (the RSS feeds, the JSON docs
+ * API and its OpenAPI description, the MCP discovery documents). Each is
+ * listed under the gate its writer reads, so a feature the config switches
+ * off drops its file here too: `blume validate` accepts a link to
+ * `/llms.txt` exactly when the build writes one.
+ *
+ * Read from the config alone, before a build: the skill archives a build
+ * publishes beside the index, and the platform files (`_redirects`,
+ * `_headers`, `vercel.json`), aren't listed. A page's Markdown copy
+ * (`/guide.md`) is its route's, and resolves through the page.
+ */
+export declare const generatedFilePaths: (project: BlumeProject) => string[];
+/**
+ * Whether a base-less path is a file the project's site serves beside its
+ * pages: one in `public/` (`/spec.pdf`, a folder's `index.html`) or one the
+ * build generates (`/llms.txt`). What `generateRuntime` and `blume doctor`
+ * check navigation entries against, beside the routes, as `blume validate`
+ * checks links.
+ */
+export declare const servedFiles: (project: BlumeProject) => ((path: string) => boolean);

package/dist/types/deploy/redirects.d.ts

@@ -41,15 +41,29 @@ export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath
  * public file (see {@link baseRedirectTarget}).
  */
 export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => Redirect[];
+/**
+ * Whether `from` names a page's own `index.html` (`/guide/index.html` for the
+ * page `/guide`, `/index.html` for the root), a URL a migrated site may have
+ * linked. A static build writes the page there, and Astro writes a redirect
+ * page to `<from>/index.html`, which would need that file to be a folder:
+ * the build fails with `EISDIR`. Hosts serve the page at that URL anyway,
+ * unless a redirect rule answers it first. `pages` are the served page
+ * routes, which carry `basePath`, as `from` does.
+ */
+export declare const isPageIndexFile: (from: string, pages: RouteSet) => boolean;
 /**
  * Based `redirects`, each exact one that moves a page followed by the same
- * redirect for the page's Markdown copies: from a path no page is served at
- * to one a page is, `/old.md` goes to `/new.md` (and `.mdx` alike), where it
- * would otherwise 404 for an agent still reading the old URL. A pattern gets
- * none; one that carries its capture over (`/beta/:slug*` → `/v2/:slug*`)
- * already moves `/beta/guide.md` along. `pages` are the served page routes
- * (carrying `basePath`, not `deployment.base`), and `bases` the deployment
- * base each end carries: Astro's config leaves it off `from` (see
+ * redirect for the page's Markdown copies: from a path whose copies no page
+ * serves to one a page is served at, `/old.md` goes to `/new.md` (and `.mdx`
+ * alike), where it would otherwise 404 for an agent still reading the old
+ * URL. A served copy never gives way: `/index` names the root's copies, so
+ * `/index` → `/` moving them would turn the home page's `/index.md` into a
+ * redirect to itself. A pattern gets none; one that carries its capture over
+ * (`/beta/:slug*` → `/v2/:slug*`) already moves `/beta/guide.md` along. Nor
+ * does a redirect from an `.html` file (`/guide.html`, from a migrated site),
+ * which had no copy to move. `pages` are the served page routes (carrying
+ * `basePath`, not `deployment.base`), and `bases` the deployment base each
+ * end carries: Astro's config leaves it off `from` (see
  * {@link applyBaseToAstroRedirects}).
  */
 export declare const withMirrorRedirects: (redirects: Redirect[], pages: RouteSet, bases: {

package/dist/types/markdown/code-title.d.ts

@@ -2,9 +2,9 @@
  * Code-fence meta. A Shiki transformer reads the tokens after the language and
  * promotes them to attributes on the rendered `<pre>`:
  *
- * - a title — the first bare token (```ts blume.config.ts) or `title="..."` —
- *   becomes `data-title`; the theme's code header shows it, falling back to the
- *   language label.
+ * - a title — the bare words (```ts blume.config.ts, ```js Install the
+ *   client) or `title="..."` — becomes `data-title`; the theme's code header
+ *   shows it, falling back to the language label.
  * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
  * - the `wrap` keyword becomes `data-wrap`: this block's long lines wrap
@@ -24,6 +24,7 @@ export declare const EXPANDABLE_MIN_LINES = 16;
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
     options: {
+        lang?: string;
         meta?: {
             __raw?: string;
         };
@@ -40,8 +41,11 @@ export interface CodeTitleTransformer {
     name: string;
     pre: (this: CodeMetaContext, node: PreNode) => void;
 }
-/** The title a fence's meta string promotes to `data-title`, if any. */
-export declare const parseCodeTitle: (raw: string | undefined) => string | undefined;
+/**
+ * The title a fence's meta string promotes to `data-title`, if any. `lang` is
+ * the fence's language, which decides the other tools' keywords it drops.
+ */
+export declare const parseCodeTitle: (raw: string | undefined, lang?: string) => string | undefined;
 /** How many lines a block's code runs to, a trailing newline aside. */
 export declare const lineCount: (source?: string) => number;
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */

package/dist/types/markdown/directives.d.ts

@@ -31,6 +31,14 @@ interface CalloutAliases {
 export declare const CALLOUT_ALIASES: Readonly<CalloutAliases>;
 /** Resolve a directive name to a Callout type, or `null` if it is not one. */
 export declare const calloutTypeFor: (name: string) => string | null;
+/**
+ * A node's phrasing children (a directive label's, a paragraph's) written
+ * back as inline Markdown, for a component prop that renders it — a callout
+ * title. Text, emphasis, strong, strikethrough, code, and links keep their
+ * formatting; anything else reads as its text (an image as nothing, raw HTML
+ * as its literal source), the way a flattened title always did.
+ */
+export declare const phrasingMarkdown: (parent: MdastNode) => string;
 /**
  * A text or leaf directive exactly as the author wrote it. The slice by
  * offsets is the exact text — `[label]` and `{attrs}` included — and is

package/dist/types/markdown/fence-language.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A code fence's language, read the way authors coming from other docs tools
+ * write it. Shiki matches language ids exactly, so two common spellings used
+ * to fall back to plain text with only a console line:
+ *
+ * - a capitalized id (```` ```JSON ````, ```` ```Dockerfile ````): Shiki's ids
+ *   and aliases are all lowercase, so the id is lowercased when that names a
+ *   language and the spelling as written doesn't.
+ * - a line range glued to the id (```` ```js{2} ````, the VitePress and
+ *   VuePress form): the range moves into the fence meta, ahead of any meta
+ *   already there, where the line-highlight transformer reads it.
+ * - a line range glued to a bracketed title (```` ```ts [file.ts]{2} ````,
+ *   the Docus form): a space splits it off, so the title is the bracketed
+ *   word alone and the range stays a range.
+ *
+ * Every other fence keeps its language and meta exactly as written.
+ */
+import type { MdastNode } from "./mdast.ts";
+/** Whether Shiki highlights `lang` as written: a bundled id, alias, or plain. */
+export declare const isKnownLanguage: (lang: string) => boolean;
+/** A fence's language and meta, after {@link normalizeFence}. */
+export interface Fence {
+    lang: string;
+    meta: string | null;
+}
+/**
+ * The language and meta a fence means, or null when it means what it says.
+ * A range glued to the language moves into the meta and one glued to a
+ * bracketed title splits off it, then a capitalized language that only names
+ * a known language in lowercase is lowercased.
+ */
+export declare const normalizeFence: (lang: string | null | undefined, meta: string | null | undefined) => Fence | null;
+/** The code node slice the plugin reads. */
+interface CodeNode extends MdastNode {
+    lang?: string | null;
+    meta?: string | null;
+}
+/** The visitor context slice the plugin writes through. */
+interface FenceContext {
+    setProperty: (node: CodeNode, key: "lang" | "meta", value: string | null) => void;
+}
+/**
+ * Satteri MDAST plugin applying {@link normalizeFence} to every fence. It runs
+ * before the plugins that read a fence's language (`package-install`, `ts2js`,
+ * mermaid) and before Shiki, so all of them see the normalized fence.
+ */
+export declare const fenceLanguagePlugin: () => {
+    code(node: CodeNode, ctx: FenceContext): void;
+    name: string;
+};
+export {};

package/dist/types/markdown/fence-meta.d.ts

@@ -19,5 +19,10 @@ export declare const metaTokens: (meta: string | null | undefined) => string[];
  * a block title.
  */
 export declare const RESERVED_META_KEYWORDS: ReadonlySet<string>;
+export declare const RUST_META_KEYWORDS: ReadonlySet<string>;
+/** The fence languages rustdoc's and mdBook's keywords apply to. */
+export declare const RUST_LANGUAGES: ReadonlySet<string>;
+/** Whether `token` is another tool's keyword in a fence of language `lang`. */
+export declare const isForeignKeyword: (token: string, lang: string | null | undefined) => boolean;
 /** A Shiki `{1,3-5}` line-range token. */
 export declare const isLineRange: (token: string) => boolean;

package/dist/types/markdown/github-alerts.d.ts

@@ -0,0 +1,35 @@
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+/**
+ * The callout each GitHub alert renders as. `IMPORTANT` has no callout of its
+ * own and reads as a note (`:::important` does too), and `CAUTION` — GitHub's
+ * red "risks or negative outcomes" alert — as danger.
+ */
+export declare const ALERT_CALLOUTS: ReadonlyMap<string, string>;
+/** An alert marker as written (`[!NOTE]`) and the callout it renders as. */
+export interface AlertMarker {
+    callout: string;
+    marker: string;
+}
+/** The alert marker a quote's first text opens with, if any. */
+export declare const alertMarkerOf: (text: string) => AlertMarker | undefined;
+/** The visitor-context slice the alert visitor uses. */
+interface AlertVisitorContext extends MdastVisitorContext {
+    parent?: (node: MdastNode) => MdastNode | undefined;
+    source?: string;
+}
+/**
+ * Satteri MDAST plugin for GitHub alerts in `.mdx`: a quote whose first line
+ * is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!CAUTION]`
+ * renders as the matching `<Callout>` (see {@link ALERT_CALLOUTS}), as on
+ * GitHub. An alert quoted inside another stays a quote, as GitHub leaves it.
+ * `.md` pages render no components, so their alerts stay quotes, which
+ * `blume check` warns about (`core/alert-diagnostics.ts`).
+ */
+export declare const githubAlertsPlugin: () => {
+    blockquote(node: MdastNode, ctx: AlertVisitorContext): void;
+    name: string;
+    options: {
+        position: boolean;
+    };
+};
+export {};

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

@@ -1,4 +1,4 @@
-import type { ApiOperationRef, ApiTagRef } from "./model.ts";
+import type { ApiOperationRef, CollectedOperations } from "./model.ts";
 /**
  * Blume's own AsyncAPI model — the second front-end of the API reference
  * pipeline. Specs are normalized to AsyncAPI 3.x at parse time (see
@@ -108,10 +108,11 @@ export declare const applyAsyncApiTraits: (document: AsyncApiDocument) => AsyncA
  * see plain channel/operation objects, trait-free.
  */
 export declare const normalizeAsyncApiDocument: (document: AsyncApiDocument) => AsyncApiDocument;
-/** The route-mapped operations, ordered tags, and skip warnings of one document. */
-export interface AsyncApiOperationCatalog {
-    operations: ApiOperationRef[];
-    tags: ApiTagRef[];
+/**
+ * The route-mapped operations, ordered tags, moved routes, and skip warnings
+ * of one document.
+ */
+export interface AsyncApiOperationCatalog extends CollectedOperations {
     warnings: string[];
 }
 /**

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

@@ -1,3 +1,4 @@
+import type { JsonValue } from "../core/adapter.ts";
 import type { ApiDocument } from "./model.ts";
 /**
  * Targeted checks for spec mistakes that would otherwise render silently
@@ -14,14 +15,18 @@ export interface SpecIssue {
     message: string;
     suggestion: string;
 }
-/**
- * How a warning names an operation: `GET /pets`, or a webhook by its name
- * (`Webhook "newPet" (POST)`), since a webhook has no path.
- */
-export declare const operationLabel: (name: string, method: string, webhook: boolean) => string;
 /**
  * Check a parsed document for the mistakes above, and for the OpenAPI 3.2
  * features Blume doesn't render yet. `$ref` path items are skipped: the
  * extractor already reports them as missing from the reference.
  */
 export declare const specIssues: (document: ApiDocument) => SpecIssue[];
+/**
+ * A spec written as OpenAPI 3.1 or later that still uses `nullable`, which
+ * 3.1 removed for `type: [T, "null"]`. Read as written (before Blume
+ * upgrades a 3.0 spec, which rewrites `nullable` itself), since that's the
+ * document the author edits. Blume still renders those values as nullable,
+ * but validators and SDK generators that follow 3.1 read them as never
+ * null. One warning per spec, naming the first few places.
+ */
+export declare const nullableIssues: (document: JsonValue) => SpecIssue[];

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

@@ -1,6 +1,7 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.2";
 import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { AsyncApiAction, AsyncApiDocument, AsyncApiSpecValue } from "./asyncapi.ts";
+import type { SpecIssue } from "./checks.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 export { slugify } from "./references.ts";
@@ -150,19 +151,48 @@ export declare const withServerDefaults: (template: string, variables: AsyncApiS
  * silently merges the tags' routes, sidebar groups, and overview sections.
  * Collisions gain `-2`, `-3`, … in first-seen order. Shared with the AsyncAPI
  * extractor (`asyncapi.ts`), whose untagged fallback groups are channel
- * addresses.
+ * addresses. `slug` is the rule before collisions: the collector also runs
+ * the one earlier releases used (`slugify` alone, so `InboxesThreads` ->
+ * `inboxesthreads`) to redirect the routes they gave.
  */
-export declare const tagSlugger: () => ((name: string) => string);
+export declare const tagSlugger: (slug?: (name: string) => string) => ((name: string) => string);
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export declare const operationLabel: (name: string, method: string, webhook: boolean) => string;
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
+/** What a spec's `tags` list says about one tag. */
+export interface ApiTagMeta {
+    description: string;
+    /**
+     * The tag's label, in place of its name, from Redocly's `x-displayName`
+     * extension. Only the label changes: the tag's slug, and so its routes,
+     * still come from its name.
+     */
+    displayName?: string;
+}
+/**
+ * A route an earlier release gave an operation's page, and the route the
+ * page has now: the source turns each into a redirect, so links to the old
+ * URL keep working.
+ */
+export interface MovedRoute {
+    from: string;
+    to: string;
+}
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
     operations: ApiOperationRef[];
     tags: ApiTagRef[];
+    /** Operation routes that moved from what earlier slug rules gave them. */
+    moved: MovedRoute[];
 }
 /** The collector handle: feed operations in, read the flattened output out. */
 export interface OperationCollector {
-    add: (entry: CollectedOperation) => void;
+    /** Add an operation, returning it with its key and route assigned. */
+    add: (entry: CollectedOperation) => ApiOperationRef;
     finish: () => CollectedOperations;
 }
 /** {@link CollectedOperations} plus anything the extractor had to skip. */
@@ -175,15 +205,32 @@ export interface ExtractedOperations extends CollectedOperations {
  * (a repeated key gains its method/action as a suffix), and the shared route
  * template — so URL shape and slug rules can never drift between the two spec
  * kinds.
+ *
+ * A key is unique across the spec, since it names the operation in
+ * `<Operation id>`. Its page's URL only has to be unique within its tag's
+ * folder, so the last route segment de-duplicates per tag: `list` in two
+ * tags is `/pets/list` and `/stores/list`, not `/stores/list-get`. Earlier
+ * releases de-duplicated the route like the key, and slugged tags without
+ * splitting their words; each route those rules gave differently is
+ * reported in `moved`.
  */
-export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
+export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, ApiTagMeta>) => OperationCollector;
+/** {@link ExtractedOperations} plus the spec mistakes extraction noticed. */
+export interface ExtractedApiOperations extends ExtractedOperations {
+    issues: SpecIssue[];
+}
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags, webhooks included. Operations inherit the first tag they declare; keys
- * are de-duplicated so a repeated `operationId` still yields distinct routes.
- * `warnings` reports anything skipped (a `$ref` path item), so missing
- * operations aren't silent.
+ * are de-duplicated so a repeated `operationId` still yields distinct routes,
+ * with an issue naming both operations. `warnings` reports anything skipped (a
+ * `$ref` path item), so missing operations aren't silent.
+ *
+ * Operations come out in the spec's order: paths as listed, and each path's
+ * methods as written. They're keyed in the method order earlier releases
+ * walked (`HTTP_METHODS`), so a repeated id resolves to the same key, and
+ * the same route, it always did.
  */
-export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
+export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedApiOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */
 export declare const operationObject: (spec: ApiSpecData, ref: ApiOperationRef) => OperationObject | undefined;

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

@@ -4,7 +4,10 @@ import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
 export interface ParsedSpec {
     document: ApiDocument;
-    /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+    /**
+     * Issues only the spec as written shows: `nullable` in a 3.1 spec, and
+     * `x-codeSamples` entries whose `$ref` couldn't be inlined.
+     */
     issues: SpecIssue[];
     warnings: string[];
 }

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

@@ -3,11 +3,21 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 import type { SharedSourceOptions } from "./shared.ts";
 /** What `include` defaults to: every Markdown/MDX file under the root. */
 export declare const DEFAULT_CONTENT_INCLUDE: string[];
-/** What `exclude` defaults to: underscore- and dot-prefixed paths. */
+/** What `exclude` always holds: underscore- and dot-prefixed paths. */
 export declare const DEFAULT_CONTENT_EXCLUDE: string[];
+/**
+ * A source's `exclude` as the scan applies it: the defaults, plus the
+ * author's patterns. A `!pattern` entry takes that exact pattern back out, a
+ * default included, so `["!**\/_*"]` publishes `_`-prefixed files. The glob
+ * library can't negate an ignore pattern itself.
+ */
+export declare const resolveContentExclude: (patterns: readonly string[]) => string[];
 /** Options for {@link filesystem}. */
 export interface FilesystemOptions extends SharedSourceOptions {
-    /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. */
+    /**
+     * Glob patterns to ignore, on top of `["**\/_*", "**\/.*"]`. A `!pattern`
+     * entry stops ignoring that pattern, a default included.
+     */
     exclude?: string[];
     /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. */
     include?: string[];
@@ -17,7 +27,7 @@ export interface FilesystemOptions extends SharedSourceOptions {
 export declare const filesystemOptionsSchema: z.ZodObject<{
     pollInterval: z.ZodOptional<z.ZodNumber>;
     prefix: z.ZodOptional<z.ZodString>;
-    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
     include: z.ZodDefault<z.ZodArray<z.ZodString>>;
     root: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
@@ -27,7 +37,7 @@ export declare const filesystemAdapterSchema: z.ZodObject<{
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;

package/dist/types/sources/mdx-remote.d.ts

@@ -56,8 +56,11 @@ export declare const mdxRemoteAdapterSchema: z.ZodObject<{
 /**
  * Remote Markdown/MDX fetched over HTTP. Enumerate files explicitly against a
  * raw `url` base, or from a GitHub repo subtree via `github`. A private repo's
- * token comes from `GITHUB_TOKEN` — never inline it here. The adapter declares
- * the variable only when it reads from GitHub, since a `url` on any other host
- * is never sent the token.
+ * token comes from `GITHUB_TOKEN` — never inline it here. Only `github`
+ * declares the variable: it lists files through GitHub's API, whose
+ * unauthenticated rate limit a build can run into even for a public
+ * repository. A raw `url` needs no token for a public repository, so a fetch
+ * that fails for want of one names the variable instead (see
+ * core/sources/mdx-remote.ts).
  */
 export declare const mdxRemote: (options: MdxRemoteOptions) => MdxRemoteAdapter;

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

@@ -18,7 +18,7 @@ declare const sourceAdapterUnion: z.ZodDiscriminatedUnion<readonly [z.ZodObject<
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;
@@ -193,7 +193,7 @@ export declare const resolvedSourceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUn
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;
@@ -998,7 +998,7 @@ export declare const contentSourcesSchema: z.ZodArray<z.ZodPipe<z.ZodCustom<{
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;

package/dist/types/theme/color.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Just enough CSS color math to check contrast at build time: parse the color
+ * syntaxes a theme config takes (hex, `rgb()`, `hsl()`, `hwb()`, `lab()`,
+ * `lch()`, `oklab()`, `oklch()`, and named colors) to sRGB, then measure WCAG
+ * 2 relative luminance and contrast. A color outside sRGB is clipped to it,
+ * which is what a browser shows on an sRGB display. Anything else — `var()`,
+ * `color-mix()`, `color()` — parses to `null`, and the caller says it couldn't
+ * check it rather than guessing.
+ */
+/** An sRGB color: gamma-encoded channels and alpha, each 0–1. */
+export interface Rgba {
+    alpha: number;
+    blue: number;
+    green: number;
+    red: number;
+}
+/** Parse a CSS color to sRGB, or `null` for syntax this module doesn't read. */
+export declare const parseColor: (value: string) => Rgba | null;
+/**
+ * Whether `value` is a CSS color: one `parseColor` reads, or a color function
+ * or keyword it leaves unread. Words that name no color (`deep purple`), and
+ * hex values with a wrong digit count or no `#`, are not.
+ */
+export declare const isCssColor: (value: string) => boolean;
+/** `color` painted over an opaque `backdrop`. */
+export declare const composite: (color: Rgba, backdrop: Rgba) => Rgba;
+/** WCAG 2 relative luminance of an opaque color. */
+export declare const luminance: (color: Rgba) => number;
+/**
+ * WCAG 2 contrast ratio of `foreground` on an opaque `background`, from 1 to
+ * 21. A translucent foreground is painted over the background first.
+ */
+export declare const contrastRatio: (foreground: Rgba, background: Rgba) => number;

package/dist/types/theme/palette.d.ts

@@ -0,0 +1,122 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { Rgba } from "./color.ts";
+/** Per-mode CSS colors. */
+export interface AccentColors {
+    dark: string;
+    light: string;
+}
+/** A color mode. */
+export type ColorMode = keyof AccentColors;
+/**
+ * Named accent presets mapped to OKLCH values, per mode. The single source of
+ * truth for preset colors: the theme CSS and the OG card (og/card.ts) both
+ * resolve from this table, so a site and its social cards can't disagree
+ * about "blue". Each clears WCAG AA (4.5:1) as text on its mode's page and
+ * under its button label ({@link readableOn}), with room to spare on the
+ * tinted surfaces accent text also sits on: the light shades are dark enough
+ * for white labels, the dark shades light enough to read on the dark page.
+ */
+export declare const ACCENTS: {
+    blue: {
+        dark: string;
+        light: string;
+    };
+    green: {
+        dark: string;
+        light: string;
+    };
+    orange: {
+        dark: string;
+        light: string;
+    };
+    pink: {
+        dark: string;
+        light: string;
+    };
+    purple: {
+        dark: string;
+        light: string;
+    };
+    red: {
+        dark: string;
+        light: string;
+    };
+    teal: {
+        dark: string;
+        light: string;
+    };
+};
+/** The contrast WCAG AA asks of body-size text. */
+export declare const MIN_TEXT_CONTRAST = 4.5;
+/**
+ * The theme's own colors a configured accent is drawn against: each mode's
+ * page background and text, and the dark ink a filled accent can carry.
+ * Mirrors the defaults in `entry.ts`.
+ */
+export declare const THEME_INKS: {
+    dark: {
+        background: string;
+        foreground: string;
+        ink: string;
+        mutedForeground: string;
+    };
+    light: {
+        background: string;
+        foreground: string;
+        ink: string;
+        mutedForeground: string;
+    };
+};
+/** {@link THEME_INKS}, parsed, for contrast math. */
+export declare const themeInk: (mode: ColorMode, name: keyof (typeof THEME_INKS)[ColorMode]) => Rgba;
+/**
+ * The label color for text on a filled `fill` (a button, a step number): white
+ * while it reaches AA, else the mode's dark ink when that reads better, so a
+ * light accent (every dark-mode preset) gets dark text instead of white text
+ * nobody can read.
+ */
+export declare const labelOn: (fill: Rgba, mode: ColorMode) => string;
+/** {@link labelOn} for a CSS color; one this module can't parse keeps white. */
+export declare const readableOn: (fill: string, mode: ColorMode) => string;
+/**
+ * Whether a raw config value names an accent preset. `hasOwn` keeps a value
+ * like "constructor" from resolving an Object.prototype member — which would
+ * stringify a function into the generated CSS, breaking the rule (the exact
+ * breakout {@link safeColor} exists to prevent).
+ */
+export declare const isAccentPreset: (value: string) => value is keyof typeof ACCENTS;
+/**
+ * Resolve the configured accent to per-mode CSS colors. A named accent
+ * resolves to its preset's shade for each mode; any other value is treated as
+ * a raw CSS color so users can pass arbitrary colors without a config change.
+ * A string accent has already been normalized by the config schema to the
+ * same value for both modes.
+ */
+export declare const resolveAccent: (theme: ResolvedConfig["theme"]) => AccentColors;
+/** Resolve the configured `action` fill per mode, or `null` when unset. */
+export declare const resolveAction: (theme: ResolvedConfig["theme"]) => AccentColors | null;
+/** Resolve the configured radius preset to a CSS length. */
+export declare const resolveRadius: (theme: ResolvedConfig["theme"]) => string;
+/**
+ * Compile theme config into CSS custom properties. A named accent resolves to
+ * its preset; any other value is treated as a raw CSS color so users can pass
+ * arbitrary colors without a config change. Labels on accent and action fills
+ * take whichever of white or dark ink reads ({@link readableOn}).
+ */
+export declare const buildThemeCss: (theme: ResolvedConfig["theme"]) => string;
+/** A configured color: where the config sets it, and its value. */
+export interface ColorSetting {
+    /** The config path, e.g. `["theme", "accent", "dark"]`. */
+    path: string[];
+    /** Whether the field also takes an accent preset name (`teal`). */
+    presets: boolean;
+    value: string;
+}
+/**
+ * The configured colors that aren't CSS colors (`"deep purple"`, a hex value
+ * missing its `#`): `theme.accent`, `theme.action`, and `theme.background`,
+ * and the OG card's `seo.og.palette`. The schema takes any string, so a
+ * mistake would otherwise reach the stylesheet, where browsers drop it, or
+ * the card renderer, which rejects it. Preset names are CSS color names too.
+ */
+export declare const invalidColorSettings: (config: ResolvedConfig) => ColorSetting[];

package/docs/01-quickstart.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 1
 ---
 
-Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.12 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
+Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.19 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
 
 ## Install and run