blume 1.0.4 → 1.1.1

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

@@ -14,6 +14,12 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
     childComponents: (name: string) => ComponentMarkdownChild[];
     /** The element's body, downleveled and dedented (empty if self-closing). */
     children: string;
+    /**
+     * The page's parsed front-matter (empty when the caller has none). Lets a
+     * serializer read page metadata directly, even when a prop expression is
+     * not statically evaluable.
+     */
+    frontmatter: Record<string, unknown>;
 }
 /**
  * A component's Markdown serializer. Return the replacement Markdown, or
@@ -29,6 +35,11 @@ export type ComponentMarkdown = (context: ComponentMarkdownContext) => string |
  * `components` adds user serializers from `ai.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
+ *
+ * `frontmatter` is the page's parsed front-matter data. It is put in scope
+ * when evaluating attribute expressions — so `prop={frontmatter.status}`
+ * 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>) => string;
+export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>, frontmatter?: Record<string, unknown>) => string;
 export {};

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

@@ -2,6 +2,7 @@ import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
  *
@@ -382,6 +383,15 @@ export interface TypesenseSearch {
 export interface MixedbreadSearch {
     storeId: string;
 }
+/** A curated link for the search dialog empty state. */
+export interface SearchPopularLink {
+    /** Internal route or external URL. */
+    href: string;
+    /** Built-in icon name shown beside the label; defaults to the file glyph. */
+    icon?: string;
+    /** Link label shown in the dialog. */
+    label: string;
+}
 /**
  * Search backend. The default `orama` builds a local index at build time (and
  * runs in dev); hosted providers need their credential block below. `none`
@@ -399,6 +409,11 @@ export interface SearchConfig {
     mixedbread?: MixedbreadSearch;
     /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
     oramaCloud?: OramaCloudSearch;
+    /**
+     * Curated links for the Cmd+K empty state. When omitted or empty, the first
+     * sidebar pages are shown instead.
+     */
+    popular?: SearchPopularLink[];
     /** Which backend powers search. Defaults to `orama`. */
     provider?: SearchProvider;
     /** Typesense credentials (required when `provider` is `typesense`). */
@@ -472,9 +487,11 @@ export interface AiConfig {
     /**
      * Markdown serializers for custom components in agent-facing output (the
      * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
-     * receives the component's statically-evaluated `props` and downleveled
-     * `children` and returns replacement Markdown — or `null` to leave the JSX
-     * verbatim. A same-name entry replaces a built-in serializer.
+     * receives the component's statically-evaluated `props` (with the page's
+     * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
+     * downleveled `children`, and the page's `frontmatter` data, and returns
+     * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
+     * entry replaces a built-in serializer.
      *
      * These live in `blume.config.ts` (which is executed at build time), not in
      * `components.tsx` (which is only statically analyzed, never run).
@@ -602,7 +619,7 @@ export interface RssConfig {
     /** Content types that each get a feed at `/<type>/rss.xml`. Defaults to blog + changelog. */
     types?: string[];
 }
-/** Colors used by generated Open Graph cards. Values must be hex colors. */
+/** Colors used by generated Open Graph cards. Any CSS color — hex, `oklch(…)`, `rgb(…)`, named. */
 export interface OgPaletteConfig {
     /** Fallback mark color. Defaults to the light theme accent. */
     accent?: string;
@@ -623,10 +640,29 @@ export interface OgConfig {
      * value always wins.
      */
     enabled?: boolean;
+    /**
+     * Google Font families for the generated card, extending Takumi's Latin-only
+     * default so non-Latin titles (CJK, and so on) render instead of tofu.
+     * Fetched from Google Fonts at build. A bare string loads the family's
+     * default weights; the object form pins weights (`700`, `[400, 700]`, or a
+     * `"100..900"` variable range) and styles.
+     */
+    fonts?: (string | {
+        name: string;
+        style?: "normal" | "italic" | ("normal" | "italic")[];
+        weight?: number | number[] | string;
+    })[];
     /** Local SVG used in the generated card instead of the site logo. */
     logo?: string;
     /** Optional generated-card colors. */
     palette?: OgPaletteConfig;
+    /**
+     * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+     * A custom page has no frontmatter to read, so its card is otherwise titled
+     * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+     * Content pages always take their card headline from the page title.
+     */
+    titles?: Record<string, string>;
 }
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
@@ -780,6 +816,37 @@ export type ExportConfig = boolean | {
     /** Offer PDF export (via print). Defaults to `false`. */
     pdf?: boolean;
 };
+/**
+ * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
+ * an unknown key fails the build so typos are caught — and `extend` carves
+ * out project-specific keys from that rule, each validated by a schema you
+ * supply.
+ */
+export interface FrontmatterConfig {
+    /**
+     * Extra frontmatter keys pages may carry, mapped to their validation
+     * schemas — any library implementing Standard Schema works (Zod — the
+     * version your project installs, 3.24+ or 4 — Valibot, ArkType):
+     *
+     * ```ts
+     * import { z } from "zod";
+     *
+     * frontmatter: {
+     *   extend: {
+     *     owner: z.string(),
+     *     reviewedAt: z.coerce.date().optional(),
+     *   },
+     * },
+     * ```
+     *
+     * Every declared key is validated on every page — absent ones included —
+     * so a required schema enforces the key site-wide; mark it `.optional()`
+     * to validate only when present. Validated values are preserved on each
+     * page record's `custom` field. Built-in frontmatter fields cannot be
+     * redeclared.
+     */
+    extend?: Record<string, StandardSchema>;
+}
 /**
  * "Last updated" timestamps. `false` (default) disables them; `true` derives
  * each date from git history; the object form selects the source. A page's
@@ -843,6 +910,8 @@ export interface BlumeConfig {
     export?: ExportConfig;
     /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
     feedback?: boolean;
+    /** Opt-in custom frontmatter keys, validated by schemas you supply. */
+    frontmatter?: FrontmatterConfig;
     /** Source repository (Edit-this-page links and the header repo link). */
     github?: GithubConfig;
     /** Internationalization (opt-in multi-locale). */

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

@@ -1,3 +1,4 @@
+import type { OgFont } from "../og/card.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate } from "./types.ts";
@@ -118,6 +119,8 @@ export interface BlumeDataConfig {
     /** Open Graph image generation. */
     og: {
         enabled: boolean;
+        /** Extra Google Font family specs for the card renderer, fetched at build. */
+        fonts?: OgFont[];
         logo?: string;
         palette?: ResolvedConfig["seo"]["og"]["palette"];
     };
@@ -125,6 +128,12 @@ export interface BlumeDataConfig {
     repoUrl: string | null;
     search: {
         enabled: boolean;
+        /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
+        popular: {
+            icon?: string;
+            label: string;
+            route: string;
+        }[];
         provider: SearchProvider;
     };
     /** Deployment site URL, or `null` when none is configured/detected. */

package/dist/types/core/deployment-env.d.ts

@@ -1,4 +1,10 @@
 import type { ResolvedConfig } from "./schema.ts";
+/**
+ * Adapters whose `deployment.site` arrives from platform env vars at deploy
+ * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
+ * from "site is missing *here*, but the platform will set it".
+ */
+export declare const SITE_INFERRING_ADAPTERS: ReadonlySet<string>;
 /**
  * Fill in `deployment.adapter` and `deployment.site` from platform env vars
  * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit

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

@@ -10,6 +10,29 @@ export declare const createDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
 export declare const resolveDocsUrl: (code: string) => string | undefined;
 /** Fill in `docsUrl` from the code map where a diagnostic doesn't set its own. */
 export declare const enrichDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
+/**
+ * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
+ * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the
+ * page body can't be mistaken for the front matter key of the same name; returns
+ * undefined when the file has no front matter or the key isn't set (a missing
+ * key has no line to point at — callers anchor to the file instead).
+ */
+export declare const locateFrontmatterKey: (source: string, path: readonly (string | number)[]) => {
+    column: number;
+    line: number;
+} | undefined;
+/**
+ * Convert generic validation issues (message + path, the shape shared by Zod
+ * and Standard Schema issues) into Blume diagnostics, anchored to a file.
+ */
+export declare const diagnosticsFromIssues: (issues: readonly {
+    message: string;
+    path: readonly (string | number)[];
+}[], options: {
+    code: string;
+    file?: string;
+    source?: string;
+}) => Diagnostic[];
 /** Convert a ZodError into Blume diagnostics, anchored to a file. */
 export declare const diagnosticsFromZod: (error: ZodError, options: {
     code: string;

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

@@ -243,6 +243,7 @@ declare const uiStringsObject: z.ZodObject<{
         results: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         label: string;
+        popular: string;
         error: string;
         placeholder: string;
         all: string;
@@ -254,11 +255,11 @@ declare const uiStringsObject: z.ZodObject<{
         askAiHint: string;
         navigate: string;
         open: string;
-        popular: string;
         preview: string;
         results: string;
     }, {
         label?: string | undefined;
+        popular?: string | undefined;
         error?: string | undefined;
         placeholder?: string | undefined;
         all?: string | undefined;
@@ -270,7 +271,6 @@ declare const uiStringsObject: z.ZodObject<{
         askAiHint?: string | undefined;
         navigate?: string | undefined;
         open?: string | undefined;
-        popular?: string | undefined;
         preview?: string | undefined;
         results?: string | undefined;
     }>>;
@@ -317,6 +317,7 @@ declare const uiStringsObject: z.ZodObject<{
     };
     search: {
         label: string;
+        popular: string;
         error: string;
         placeholder: string;
         all: string;
@@ -328,7 +329,6 @@ declare const uiStringsObject: z.ZodObject<{
         askAiHint: string;
         navigate: string;
         open: string;
-        popular: string;
         preview: string;
         results: string;
     };
@@ -417,6 +417,7 @@ declare const uiStringsObject: z.ZodObject<{
     } | undefined;
     search?: {
         label?: string | undefined;
+        popular?: string | undefined;
         error?: string | undefined;
         placeholder?: string | undefined;
         all?: string | undefined;
@@ -428,7 +429,6 @@ declare const uiStringsObject: z.ZodObject<{
         askAiHint?: string | undefined;
         navigate?: string | undefined;
         open?: string | undefined;
-        popular?: string | undefined;
         preview?: string | undefined;
         results?: string | undefined;
     } | undefined;
@@ -718,6 +718,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         results: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         label: string;
+        popular: string;
         error: string;
         placeholder: string;
         all: string;
@@ -729,11 +730,11 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         askAiHint: string;
         navigate: string;
         open: string;
-        popular: string;
         preview: string;
         results: string;
     }, {
         label?: string | undefined;
+        popular?: string | undefined;
         error?: string | undefined;
         placeholder?: string | undefined;
         all?: string | undefined;
@@ -745,7 +746,6 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         askAiHint?: string | undefined;
         navigate?: string | undefined;
         open?: string | undefined;
-        popular?: string | undefined;
         preview?: string | undefined;
         results?: string | undefined;
     }>>;
@@ -792,6 +792,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
     };
     search: {
         label: string;
+        popular: string;
         error: string;
         placeholder: string;
         all: string;
@@ -803,7 +804,6 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         askAiHint: string;
         navigate: string;
         open: string;
-        popular: string;
         preview: string;
         results: string;
     };
@@ -892,6 +892,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
     } | undefined;
     search?: {
         label?: string | undefined;
+        popular?: string | undefined;
         error?: string | undefined;
         placeholder?: string | undefined;
         all?: string | undefined;
@@ -903,7 +904,6 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         askAiHint?: string | undefined;
         navigate?: string | undefined;
         open?: string | undefined;
-        popular?: string | undefined;
         preview?: string | undefined;
         results?: string | undefined;
     } | undefined;