blume 1.0.4 → 1.1.0

package/src/core/standard-schema.ts

@@ -0,0 +1,54 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), the minimal
+ * `~standard` surface shared by Zod 3.24+, Zod 4, Valibot, ArkType, and
+ * friends. Blume accepts user-supplied validation schemas (e.g.
+ * `frontmatter.extend`) through this interface instead of Zod's own types:
+ * `blume.config.ts` imports zod from the *consumer's* node_modules, which may
+ * be a different major version than the zod Blume bundles, and calling Zod
+ * methods (`.extend()`, `.safeParse()`) across instances is unsupported. The
+ * `~standard.validate` contract is version- and library-agnostic.
+ */
+
+/** One validation failure, with an optional path into the checked value. */
+export interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?:
+    | readonly (PropertyKey | { readonly key: PropertyKey })[]
+    | undefined;
+}
+
+/** A passing validation: the (possibly transformed) output value. */
+export interface StandardSchemaSuccess<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+
+/** A failing validation: one or more issues. */
+export interface StandardSchemaFailure {
+  readonly issues: readonly StandardSchemaIssue[];
+}
+
+export type StandardSchemaResult<Output> =
+  | StandardSchemaSuccess<Output>
+  | StandardSchemaFailure;
+
+/** A validation schema exposing the Standard Schema `~standard` contract. */
+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 types?:
+      | { readonly input: Input; readonly output: Output }
+      | undefined;
+  };
+}
+
+/** Whether a config-supplied value implements the `~standard` contract. */
+export const isStandardSchema = (value: unknown): value is StandardSchema =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { "~standard"?: { validate?: unknown } })["~standard"]
+    ?.validate === "function";

package/src/core/types.ts

@@ -19,6 +19,13 @@ export interface Diagnostic {
   file?: string;
   line?: number;
   column?: number;
+  /**
+   * The built URL this diagnostic is about, for findings that are a property of
+   * the output rather than of a source file (`blume audit`). Set alongside
+   * `file`/`line` where the page maps back to authored content, so a finding can
+   * name both the URL that's wrong and the frontmatter line that fixes it.
+   */
+  url?: string;
   schemaPath?: string;
   suggestion?: string;
   docsUrl?: string;
@@ -115,6 +122,12 @@ export interface PageRecord {
   description?: string;
   contentType: string;
   meta: PageMeta;
+  /**
+   * Custom frontmatter values declared via `frontmatter.extend`, validated by
+   * the user-supplied schemas (schema output, so transforms apply). Present
+   * only when the project opts in and the page carries at least one value.
+   */
+  custom?: Record<string, unknown>;
   headings: Heading[];
   /** Whether the file is `.md`/`.mdx`. */
   format: "md" | "mdx";

package/src/deploy/adapter-output.ts

@@ -8,6 +8,18 @@ import type { ProjectContext } from "../core/types.ts";
 
 type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
 
+/**
+ * Top-level directory each server adapter writes its deploy bundle into, for
+ * `.gitignore` — the bundle is a build artifact, and the platform's own state
+ * lives alongside it (`.vercel/project.json`, `.netlify/state.json`), so the
+ * whole directory is ignored. `node` and `cloudflare` emit into `dist/`, which
+ * `blume init` already ignores.
+ */
+export const ADAPTER_IGNORE_DIRS: Partial<Record<Adapter, string>> = {
+  netlify: ".netlify/",
+  vercel: ".vercel/",
+};
+
 /**
  * Server adapters whose deploy bundle lands *outside* Astro's `outDir`, at a
  * path relative to the Astro project root. Blume points the Astro root at the
@@ -15,18 +27,21 @@ type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
  * `<root>/.blume/<path>` — where the deploy platform never looks. Each value is
  * the sub-path to surface up to the real project root.
  *
- * `vercel` writes a Build Output API v3 tree at `.vercel/output`; only that
- * subtree is moved, so a `vercel pull`-ed `.vercel/project.json` sitting at the
- * project root survives the relocation. `netlify` writes a Frameworks API tree
- * at `.netlify/v1` (its `.netlify/build` sibling is only the intermediate SSR
- * bundle, already traced into `v1/functions`); only `v1` is moved, so the
- * `.netlify/state.json` written by `netlify link` survives too. `node` and
- * `cloudflare` emit into `dist/` (already at the project root), so they are
- * absent here and need no relocation.
+ * `netlify` writes a Frameworks API tree at `.netlify/v1` (its `.netlify/build`
+ * sibling is only the intermediate SSR bundle, already traced into
+ * `v1/functions`); only `v1` is moved, so the `.netlify/state.json` written by
+ * `netlify link` survives too. `node` and `cloudflare` emit into `dist/`
+ * (already at the project root), so they are absent here and need no
+ * relocation.
+ *
+ * `vercel` is absent for a different reason: it is shown the real project root
+ * up front (see `withAdapterRoot`), because its `@vercel/nft` dependency trace
+ * is rooted there too and tracing from `.blume` silently drops the function's
+ * chunks and `node_modules`. Given the right root it writes its Build Output
+ * tree straight to `<root>/.vercel/output`, so there is nothing left to move.
  */
 export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
   netlify: ".netlify/v1",
-  vercel: ".vercel/output",
 };
 
 /**
@@ -53,10 +68,10 @@ export const deployStaticDir = (
   return dist;
 };
 
-/** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
+/** Outcome of {@link surfaceAdapterOutput}, for logging. */
 export type SurfaceResult =
   | { moved: false }
-  | { from: string; ignore: string; moved: true; to: string };
+  | { from: string; moved: true; to: string };
 
 /**
  * Move a server adapter's deploy bundle out of the hidden `.blume` runtime and
@@ -95,8 +110,5 @@ export const surfaceAdapterOutput = async (
   // bundle at `/var/task`).
   await cp(from, to, { recursive: true, verbatimSymlinks: true });
   await rm(from, { force: true, recursive: true });
-  // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
-  // never the moved sub-path — the platform's own state (`.vercel/project.json`,
-  // `.netlify/state.json`) lives there too and must also be ignored.
-  return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
+  return { from, moved: true, to };
 };

package/src/deploy/headers.ts

@@ -0,0 +1,66 @@
+import { normalizeBasePath } from "../core/base-path.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * The `_headers` file for a static build (Netlify + Cloudflare Pages/Workers
+ * static assets). Blume's raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`,
+ * and the `.txt` files (`llms.txt`, `llms-full.txt`) — are valid UTF-8, but a
+ * static host serves them from the file extension alone, and common hosts send
+ * `text/markdown` / `text/plain` with **no** `charset`. Browsers then fall back
+ * to Windows-1252 for non-HTML text, so any non-ASCII docs (Japanese, accented
+ * Latin, …) render as mojibake when the raw URL is opened directly. HTML pages
+ * escape this because they carry `<meta charset>`; the raw endpoints have only
+ * the HTTP header. Pinning `charset=utf-8` here matches the Content-Type these
+ * same routes already send from the dev/server runtime (see
+ * `astro/templates.ts`). Hosts that don't read `_headers` (Vercel, S3) ignore
+ * the file harmlessly.
+ */
+
+/**
+ * One rule per served extension. `.mdx` uses `text/markdown` to match the
+ * runtime endpoint, which serves both variants as `text/markdown`. The raw
+ * Markdown mirrors live under the page routes (which carry `basePath`), while
+ * the `.txt` files (`llms.txt`, `llms-full.txt`) are written to the dist root
+ * and served at the deployment base — so only the `.md`/`.mdx` rules take the
+ * `basePath` layer.
+ */
+const HEADER_RULES: readonly {
+  contentType: string;
+  ext: string;
+  underBasePath: boolean;
+}[] = [
+  {
+    contentType: "text/markdown; charset=utf-8",
+    ext: "md",
+    underBasePath: true,
+  },
+  {
+    contentType: "text/markdown; charset=utf-8",
+    ext: "mdx",
+    underBasePath: true,
+  },
+  {
+    contentType: "text/plain; charset=utf-8",
+    ext: "txt",
+    underBasePath: false,
+  },
+];
+
+/**
+ * `_headers` contents: a `/*.<ext>` glob per rule with an indented
+ * `Content-Type` line, in the two-space format Netlify and Cloudflare read. The
+ * glob carries the served prefix (`{deployment.base}{basePath}` for the
+ * Markdown mirrors, `{deployment.base}` for the root `.txt` files) so the rules
+ * still match once the site is mounted under a subpath (`/docs/*.md`); the
+ * wildcard spans path segments, so a nested route like `/docs/ja/intro.md`
+ * matches too.
+ */
+export const buildNetlifyHeaders = (config: ResolvedConfig): string => {
+  const deployBase = normalizeBasePath(config.deployment.base);
+  return `${HEADER_RULES.map((rule) => {
+    const prefix = rule.underBasePath
+      ? `${deployBase}${config.basePath}`
+      : deployBase;
+    return `${prefix}/*.${rule.ext}\n  Content-Type: ${rule.contentType}`;
+  }).join("\n")}\n`;
+};

package/src/deploy/redirects.ts

@@ -1,4 +1,8 @@
-import { withBasePath } from "../core/base-path.ts";
+import {
+  normalizeBasePath,
+  withBasePath,
+  withComposedBasePath,
+} from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 
 /**
@@ -12,21 +16,57 @@ import type { ResolvedConfig } from "../core/schema.ts";
 type Redirect = ResolvedConfig["redirects"][number];
 
 /**
- * Prepend the site-wide `basePath` to each redirect's internal `from`/`to`
- * (both are authored as if mounted at root); external `to` URLs pass through.
- * Idempotent, so re-basing an already-based redirect is safe.
+ * Base a redirect for Astro's `redirects` config, where the two sides are not
+ * symmetric:
+ *
+ * - `from` gains only `basePath`. Astro builds the match pattern with
+ *   `deployment.base` already applied (`getPattern(segments, config.base)`), so
+ *   adding it here would serve the redirect at `{base}{base}/from`.
+ * - `to` gains the full `{deployment.base}{basePath}` stack. Astro resolves a
+ *   destination that matches a known route by regenerating it from that route's
+ *   segments, which carry no base — and passes an unmatched destination through
+ *   verbatim. Neither path prepends `base`, so a root-relative `to` escapes the
+ *   base entirely (withastro/astro#7774, still the behavior in Astro 7).
+ *
+ * Both sides are authored as if mounted at root; external `to` URLs pass
+ * through. Idempotent, so a hand-written base isn't doubled.
  */
-export const applyBaseToRedirects = (
+export const applyBaseToAstroRedirects = (
   redirects: Redirect[],
-  basePath: string
-): Redirect[] =>
-  basePath
+  basePath: string,
+  deployBase: string
+): Redirect[] => {
+  // `deployment.base` arrives as the user wrote it (Astro accepts `/base/`,
+  // even `base`); normalizing here keeps the composed paths well-formed.
+  const base = normalizeBasePath(deployBase);
+  return basePath || base
     ? redirects.map((redirect) => ({
         ...redirect,
         from: withBasePath(basePath, redirect.from),
-        to: withBasePath(basePath, redirect.to),
+        to: withComposedBasePath(base, basePath, redirect.to),
       }))
     : redirects;
+};
+
+/**
+ * Base a redirect for the host platform files below. Unlike Astro's config,
+ * these are matched against the real served URL, so both sides carry the full
+ * `{deployment.base}{basePath}` stack.
+ */
+export const applyBaseToPlatformRedirects = (
+  redirects: Redirect[],
+  basePath: string,
+  deployBase: string
+): Redirect[] => {
+  const base = normalizeBasePath(deployBase);
+  return basePath || base
+    ? redirects.map((redirect) => ({
+        ...redirect,
+        from: withComposedBasePath(base, basePath, redirect.from),
+        to: withComposedBasePath(base, basePath, redirect.to),
+      }))
+    : redirects;
+};
 
 /** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
 export const buildNetlifyRedirects = (redirects: Redirect[]): string =>

package/src/og/card.ts

@@ -1,15 +1,26 @@
-import { Renderer } from "@takumi-rs/core";
-import { container, image, text } from "@takumi-rs/helpers";
-import type { Node } from "@takumi-rs/helpers";
+import { render } from "takumi-js";
+import type { RenderOptions } from "takumi-js";
+import { container, googleFonts, image, text } from "takumi-js/helpers";
+import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
-// Reuse one renderer (and its loaded default fonts) across all images.
-let renderer: Renderer | null = null;
-const getRenderer = (): Renderer => {
-  renderer ??= new Renderer();
-  return renderer;
-};
+/**
+ * A Google Font family to load into the OG card renderer. A bare string is the
+ * family name (weight 400, normal style); the object form pins weight and style.
+ * Handed straight to Takumi's `googleFonts` helper, which fetches the family
+ * from Google Fonts at build and returns per-glyph coverage subsets.
+ */
+export type OgFont =
+  | string
+  | {
+      /** Google Fonts family name, e.g. `"Noto Sans JP"`. */
+      name: string;
+      /** `400`, `[400, 700]`, or a variable range like `"100..900"`. */
+      weight?: number | number[] | string;
+      /** `"normal"`, `"italic"`, or both. */
+      style?: "normal" | "italic" | ("normal" | "italic")[];
+    };
 
 const ACCENT_HEX: Record<string, string> = {
   blue: "#3b82f6",
@@ -21,22 +32,13 @@ const ACCENT_HEX: Record<string, string> = {
   teal: "#14b8a6",
 };
 
-const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/iu;
-
-// OG rendering uses hex (Takumi's color parser does not accept oklch); named
-// presets map to hex, well-formed hex passes through, anything else falls
-// back — a malformed hex (`#12345` typo) would throw inside Takumi and fail
-// the build at OG prerender with an opaque native error. `hasOwn` keeps a
-// preset name like "constructor" from resolving up the prototype chain.
-const resolveAccent = (accent: string): string => {
-  if (Object.hasOwn(ACCENT_HEX, accent)) {
-    return ACCENT_HEX[accent] as string;
-  }
-  return HEX_COLOR.test(accent) ? accent : "#3b82f6";
-};
-
-const resolveColor = (color: string | undefined, fallback: string): string =>
-  color && HEX_COLOR.test(color) ? color : fallback;
+// Named presets map to Blume's palette hex (the preset "blue" is not CSS
+// blue); anything else is handed to Takumi as-is — it parses the full CSS
+// color grammar, and a genuinely malformed value fails the build with a
+// parse error naming it. `hasOwn` keeps a preset name like "constructor"
+// from resolving up the prototype chain.
+const resolveAccent = (accent: string): string =>
+  Object.hasOwn(ACCENT_HEX, accent) ? (ACCENT_HEX[accent] as string) : accent;
 
 export interface OgCardPalette {
   accent?: string;
@@ -49,7 +51,7 @@ export interface OgCardPalette {
 export interface OgCardOptions {
   /** Large headline — the page title. */
   title: string;
-  /** Accent color (named preset or hex) for the fallback brand mark. */
+  /** Accent color (named preset or any CSS color) for the fallback brand mark. */
   accent?: string;
   /** Brand/site name shown in the top-left lockup. */
   brand?: string;
@@ -66,11 +68,65 @@ export interface OgCardOptions {
   repo?: string;
   /** Footer-right site host, e.g. `docs.acme.com`. */
   site?: string;
+  /**
+   * Pre-fetched image entries, or a group controlling how remote images (and
+   * emoji glyphs) are fetched. Blume merges in a shared glyph cache; see
+   * {@link resolveImages}.
+   */
+  images?: RenderOptions["images"];
+  /**
+   * Google Font families for non-Latin titles. Takumi's built-in font covers
+   * only Latin, so a CJK (etc.) title renders as tofu without a family that
+   * covers its script — see {@link loadFonts}.
+   */
+  fonts?: OgFont[];
 }
 
 const WIDTH = OG_IMAGE_WIDTH;
 const HEIGHT = OG_IMAGE_HEIGHT;
 
+// Emoji in a title render as Twemoji glyphs Takumi fetches from a CDN, once per
+// render. A build prerenders one card per page, so an emoji in the site title
+// would otherwise refetch the same glyph for every page. This cache is keyed by
+// URL and holds the in-flight promise, so concurrent renders share one request
+// and a build fetches each glyph once. Unbounded on purpose: it is scoped to the
+// glyphs a site's own titles reference, which is a handful.
+const imageFetchCache = new Map<string, Promise<ArrayBuffer>>();
+
+/**
+ * Merge the shared glyph cache into the caller's `images`. An explicit
+ * `fetchCache` wins, so a caller can scope or opt out of the cache.
+ */
+const resolveImages = (
+  images: OgCardOptions["images"]
+): OgCardOptions["images"] =>
+  Array.isArray(images)
+    ? { fetchCache: imageFetchCache, sources: images }
+    : { fetchCache: imageFetchCache, ...images };
+
+// Google Fonts subsets keyed by the family set, so a build's identical per-page
+// renders build the subset list once. `googleFonts` also caches the css2 request
+// process-wide and the shared renderer skips subset files it has already loaded,
+// so this only avoids rebuilding the list per card.
+const fontSubsetCache = new Map<string, Promise<FontSubset[]>>();
+
+/**
+ * Load the configured Google Font families as coverage subsets for `render`'s
+ * `fonts` option. `googleFonts` fetches the families from Google Fonts in one
+ * css2 request; `render` then registers only the subsets a card's text uses. A
+ * fetch failure rejects, failing the build with the cause rather than silently
+ * shipping tofu — the same fail-fast the OG accent relies on.
+ */
+const loadFonts = (fonts: OgFont[]): Promise<FontSubset[]> => {
+  const key = JSON.stringify(fonts);
+  let pending = fontSubsetCache.get(key);
+  if (!pending) {
+    pending = googleFonts(fonts as GoogleFontFamily[]);
+    fontSubsetCache.set(key, pending);
+  }
+  return pending;
+};
+
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,
 // BORDER = --border.
@@ -84,11 +140,11 @@ const resolvePalette = (
   options: OgCardOptions
 ): Required<OgCardPalette> & { faint: string } => ({
   accent: resolveAccent(options.palette?.accent ?? options.accent ?? "blue"),
-  background: resolveColor(options.palette?.background, BG),
-  border: resolveColor(options.palette?.border, BORDER),
-  faint: resolveColor(options.palette?.muted, FAINT),
-  foreground: resolveColor(options.palette?.foreground, FOREGROUND),
-  muted: resolveColor(options.palette?.muted, MUTED),
+  background: options.palette?.background ?? BG,
+  border: options.palette?.border ?? BORDER,
+  faint: options.palette?.muted ?? FAINT,
+  foreground: options.palette?.foreground ?? FOREGROUND,
+  muted: options.palette?.muted ?? MUTED,
 });
 
 /**
@@ -174,7 +230,9 @@ const titleSize = (title: string): number => {
 };
 
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
-export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
+export const renderOgImage = async (
+  options: OgCardOptions
+): Promise<Uint8Array> => {
   const { accent, background, border, faint, foreground, muted } =
     resolvePalette(options);
   const brand = options.brand?.trim();
@@ -265,9 +323,16 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
     },
   });
 
-  return getRenderer().render(node, {
+  const fonts = options.fonts ?? [];
+  // `render` registers only the subsets a card's text uses and skips files it
+  // has already loaded, so passing the full family list per page is cheap.
+  const fontSubsets = fonts.length ? await loadFonts(fonts) : undefined;
+
+  return render(node, {
+    fonts: fontSubsets,
     format: "png",
     height: HEIGHT,
+    images: resolveImages(options.images),
     width: WIDTH,
   });
 };

package/src/og/index.ts

@@ -1,2 +1,2 @@
 export { renderOgImage } from "./card.ts";
-export type { OgCardOptions, OgCardPalette } from "./card.ts";
+export type { OgCardOptions, OgCardPalette, OgFont } from "./card.ts";

package/src/search/popular.ts

@@ -0,0 +1,33 @@
+import { withBasePath } from "../core/base-path.ts";
+
+/** A resolved search empty-state link passed to the Search dialog. */
+export interface SearchPopularPage {
+  /** Built-in icon name; `Search.astro` resolves it to markup at render time. */
+  icon?: string;
+  label: string;
+  route: string;
+}
+
+/**
+ * Map configured `search.popular` entries to `{ route, label }` for Search.
+ *
+ * Curated hrefs are authored as if mounted at root, so `basePath` is applied
+ * here — matching `navigation.featured` and tab paths, and agreeing with the
+ * sidebar fallback these entries replace (whose routes are already based via
+ * `page.route`). `withBasePath` is idempotent and skips external URLs.
+ *
+ * `deployment.base` is deliberately *not* applied: routes stay deploy-base-less
+ * so `createLinkRow` can prefix it at click time, same as sidebar-derived pages.
+ *
+ * `icon` stays a name here (like `navigation.featured`): the icon set is a
+ * server-only module, so `Search.astro` resolves it to inline SVG at render.
+ */
+export const resolveSearchPopular = (
+  popular: { href: string; icon?: string; label: string }[],
+  basePath: string
+): SearchPopularPage[] =>
+  popular.map(({ href, icon, label }) => ({
+    ...(icon ? { icon } : {}),
+    label,
+    route: withBasePath(basePath, href),
+  }));

package/src/theme/entry.ts

@@ -55,6 +55,10 @@ const TOKEN_DEFAULTS = `:root {
   --blume-code-word-border: oklch(0.55 0.16 255 / 0.5);
   --blume-radius: 0.75rem;
 
+  /* Max width of the prose content column (article, breadcrumb, TOC, feedback,
+     pagination, last-updated). Override to re-measure the whole column at once. */
+  --blume-content-width: 42rem;
+
   /*
    * Font tokens resolve through optional src variables that Astro's Fonts API
    * populates (via theme.fonts). When unset they fall back to the system
@@ -128,6 +132,7 @@ const THEME_MAPPING = `@theme inline {
   --color-action-foreground: var(--blume-action-foreground);
   --color-code: var(--blume-code-background);
   --radius-blume: var(--blume-radius);
+  --container-content: var(--blume-content-width);
   --font-sans: var(--blume-font-body);
   --font-mono: var(--blume-font-mono);
   --font-display: var(--blume-font-display);
@@ -222,7 +227,7 @@ ${THEME_MAPPING}
   --tw-prose-links: var(--blume-foreground);
   --tw-prose-bold: var(--blume-foreground);
   --tw-prose-counters: var(--blume-muted-foreground);
-  --tw-prose-bullets: var(--blume-border);
+  --tw-prose-bullets: var(--blume-muted-foreground);
   --tw-prose-hr: var(--blume-border);
   --tw-prose-quotes: var(--blume-muted-foreground);
   --tw-prose-quote-borders: var(--blume-border);