blume 1.2.0 → 1.3.0

package/src/components/layout/Search.astro

@@ -112,7 +112,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         >
         </div>
         <div
-          class="min-h-0 flex-1 overflow-y-auto p-2"
+          class="min-h-0 flex-1 scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto p-2"
           data-blume-search-results
         >
         </div>
@@ -124,7 +124,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         </p>
       </div>
       <div
-        class="hidden min-h-0 overflow-y-auto p-5 md:block"
+        class="hidden min-h-0 scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto p-5 md:block"
         data-blume-search-preview
       >
       </div>

package/src/components/layout/WebMcp.astro

@@ -0,0 +1,49 @@
+---
+// WebMCP: expose the docs' read-only tools (search, page Markdown, the docs
+// index) to agentic browsers via the page's model context. Rendered by
+// PageLayout on every page; the marker element below both gates the script
+// (absent when `ai.webmcp` is off, so it returns immediately) and carries the
+// two config flags the client needs — importing `blume:data` from the client
+// script would drag the whole navigation snapshot into the bundle.
+import data from "blume:data";
+
+const { search, webmcp } = data.config;
+---
+
+{
+  webmcp.enabled && (
+    <blume-webmcp
+      data-llms={webmcp.llms ? "true" : "false"}
+      data-search={search.enabled ? "true" : "false"}
+      hidden
+    />
+  )
+}
+
+<script>
+  import type { ModelContext } from "../islands/webmcp.ts";
+  import { buildWebMcpTools, registerWebMcpTools } from "../islands/webmcp.ts";
+
+  const marker = document.querySelector<HTMLElement>("blume-webmcp");
+  if (marker) {
+    // The spec is in flux: Chrome's early preview hangs the context off
+    // `navigator`, the editor's draft off `document`. Register on whichever
+    // exists; both absent (every ordinary browser) is a silent no-op.
+    const context =
+      (navigator as Navigator & { modelContext?: ModelContext })
+        .modelContext ??
+      (document as Document & { modelContext?: ModelContext }).modelContext;
+    if (context) {
+      registerWebMcpTools(
+        buildWebMcpTools({
+          base: import.meta.env.BASE_URL,
+          llms: marker.dataset.llms === "true",
+          loadSearch: async () =>
+            (await import("blume:search-client")).createSearch(),
+          search: marker.dataset.search === "true",
+        }),
+        context
+      );
+    }
+  }
+</script>

package/src/components/layout/search/orama.ts

@@ -10,14 +10,17 @@ import type { IndexedDocument, SearchFn } from "./types.ts";
  * in-memory full-text database in the browser, and query it. Keyless and
  * available in both dev and the production build. A generous match pool is
  * pulled so the section pills can count across the whole result set before the
- * active filter and display limit are applied.
+ * active filter and display limit are applied. `locale` is the site's
+ * `i18n.defaultLocale`, baked into the generated client so unspaced scripts
+ * (Japanese, Chinese, Korean, Thai) get a word-segmenting tokenizer.
  */
 export const createSearch = async (opts: {
   indexUrl: string;
+  locale?: string;
 }): Promise<SearchFn> => {
   const response = await fetch(opts.indexUrl);
   const documents = (await response.json()) as IndexedDocument[];
-  const db = await buildOramaIndex(documents);
+  const db = await buildOramaIndex(documents, opts.locale);
 
   return async (query, options) => {
     const docs = await queryOramaIndex(db, query, RESULT_POOL, options?.locale);

package/src/core/config-input.ts

@@ -392,14 +392,58 @@ export interface NavigationConfig {
 // Theme
 // ---------------------------------------------------------------------------
 
-/** The three type roles, each a curated Google Font slug. */
+/** Fallback stack category for a custom font. */
+export type FontFallback = "sans" | "serif" | "mono";
+
+/**
+ * Any family from a zero-config Astro font provider, by name. Self-hosted and
+ * optimized like the curated slugs.
+ */
+export interface RemoteFontInput {
+  /** Fallback stack. Defaults to `mono` for the mono role, `sans` otherwise. */
+  fallback?: FontFallback;
+  /** Family name as the provider lists it, e.g. `"Noto Sans JP"`. */
+  name: string;
+  /** Which provider serves the family. Defaults to `google`. */
+  provider?: "google" | "fontsource" | "bunny" | "fontshare";
+  /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
+  weights?: (number | string)[];
+}
+
+/** One local `@font-face`: a file plus optional weight/style (else inferred). */
+export interface LocalFontVariantInput {
+  /** Font file path, relative to the project root. */
+  src: string;
+  /** Face style; inferred from the file when omitted. */
+  style?: "normal" | "italic" | "oblique";
+  /** Face weight (a number or `"100..900"` range); inferred when omitted. */
+  weight?: number | string;
+}
+
+/** A self-hosted family loaded from font files in the project. */
+export interface LocalFontInput {
+  /** Fallback stack. Defaults to `mono` for the mono role, `sans` otherwise. */
+  fallback?: FontFallback;
+  /** Family name used in CSS and the OG card. */
+  name: string;
+  /** The faces to declare (at least one). */
+  variants: LocalFontVariantInput[];
+}
+
+/** A role's font: curated slug, remote-provider family, or local files. */
+export type FontInput =
+  | LiteralUnion<FontSlug>
+  | RemoteFontInput
+  | LocalFontInput;
+
+/** The three type roles: a curated slug, any provider family, or local files. */
 export interface FontsConfig {
   /** Body / prose font. Defaults to `inter`. */
-  body?: LiteralUnion<FontSlug>;
+  body?: FontInput;
   /** Display / heading font. Defaults to `inter-tight`. */
-  display?: LiteralUnion<FontSlug>;
+  display?: FontInput;
   /** Monospace / code font. Defaults to `ibm-plex-mono`. */
-  mono?: LiteralUnion<FontSlug>;
+  mono?: FontInput;
 }
 
 /** Colors, fonts, radius, and color-mode behavior. */
@@ -605,6 +649,40 @@ export interface AiConfig {
   markdownComponents?: Record<string, ComponentMarkdown>;
   /** Expose the docs as an MCP server for agents. */
   mcp?: McpConfig;
+  /**
+   * Publish Agent Skills for discovery: a directory (resolved against the
+   * project root) whose subdirectories each hold a `SKILL.md`. Skills are
+   * copied under `/.well-known/agent-skills/` — single-file skills verbatim,
+   * skills with supporting resources as `.tar.gz` archives — and enumerated
+   * in a discovery index with SHA-256 digests (Agent Skills Discovery RFC).
+   *
+   * ```ts
+   * ai: {
+   *   skills: "./skills",
+   * }
+   * ```
+   */
+  skills?: string;
+  /**
+   * Web Bot Auth: publish the org's HTTP Message Signature public keys at
+   * `/.well-known/http-message-signatures-directory`, so sites receiving
+   * requests from your agents can verify them. Public keys only — a key
+   * containing private material (`d`, `p`, `q`, …) is rejected.
+   */
+  webBotAuth?: WebBotAuthConfig;
+  /**
+   * WebMCP: register in-page tools (search, page Markdown, the docs index)
+   * on the browser's model context, so agentic browsers can drive the docs
+   * without a separate MCP connection. The script is tiny and no-ops in
+   * browsers without the API. Defaults to `true`; set `false` to opt out.
+   */
+  webmcp?: boolean;
+}
+
+/** Web Bot Auth signature directory. Off until at least one key is listed. */
+export interface WebBotAuthConfig {
+  /** Public JWKs to publish (e.g. an Ed25519 key: `kty: "OKP"`, `crv: "Ed25519"`, `x: …`). */
+  keys?: Record<string, unknown>[];
 }
 
 // ---------------------------------------------------------------------------
@@ -701,6 +779,34 @@ export interface DeploymentConfig {
   site?: string;
 }
 
+/**
+ * One authorized remote image source, passed through to Astro's
+ * `image.remotePatterns`. Hostnames accept `*.` (one level) and `**.` (any
+ * depth) wildcards; pathnames accept `/dir/*` and `/dir/**` the same way.
+ */
+export interface ImageRemotePattern {
+  /** Hostname pattern, e.g. `"**.example.com"`. */
+  hostname?: string;
+  /** Pathname pattern, e.g. `"/images/**"`. */
+  pathname?: string;
+  /** Port, e.g. `"8080"`. */
+  port?: string;
+  /** URL scheme, e.g. `"https"`. */
+  protocol?: string;
+}
+
+/**
+ * Image optimization. Local images referenced by relative path are optimized
+ * automatically; remote images are only optimized when their host is
+ * authorized here. Both fields map directly onto Astro's `image` config.
+ */
+export interface ImageConfig {
+  /** Hosts whose remote images may be optimized, e.g. `["cdn.example.com"]`. */
+  domains?: string[];
+  /** Pattern-based host authorization, for wildcards `domains` can't express. */
+  remotePatterns?: ImageRemotePattern[];
+}
+
 /** HTTP redirect status codes: permanent (301/308) and temporary (302/307). */
 type RedirectStatusPermanent = 301 | 308;
 type RedirectStatusTemporary = 302 | 307;
@@ -762,6 +868,11 @@ export interface OgPaletteConfig {
 
 /** Per-page Open Graph image generation. */
 export interface OgConfig {
+  /**
+   * Card subtitle. Defaults to the site description; a string overrides it,
+   * `false` renders the card without one.
+   */
+  description?: string | false;
   /**
    * Generate an OG image per page. Defaults to on once a deployment `site`
    * URL is known and off otherwise (`og:image` must be absolute). An explicit
@@ -769,11 +880,13 @@ export interface OgConfig {
    */
   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 for the generated card, extending Takumi's Latin-only default so
+   * non-Latin titles (CJK, and so on) render instead of tofu. A bare string is
+   * a Google Fonts family fetched at build; the name-only object form pins
+   * weights (`700`, `[400, 700]`, or a `"100..900"` variable range) and
+   * styles; the `src` form reads a local font file from the project instead.
+   * When omitted and `theme.fonts` is explicitly configured, the theme's
+   * display and body fonts are used automatically — pass `[]` to opt out.
    */
   fonts?: (
     | string
@@ -782,11 +895,28 @@ export interface OgConfig {
         style?: "normal" | "italic" | ("normal" | "italic")[];
         weight?: number | number[] | string;
       }
+    | {
+        /** Family name registered for the file's faces. */
+        name: string;
+        /** Font file path, relative to the project root. */
+        src: string;
+        style?: "normal" | "italic";
+        weight?: number;
+      }
   )[];
-  /** Local SVG used in the generated card instead of the site logo. */
-  logo?: string;
+  /**
+   * Local SVG used in the generated card instead of the site logo; `false`
+   * renders the card without any brand mark.
+   */
+  logo?: string | false;
   /** Optional generated-card colors. */
   palette?: OgPaletteConfig;
+  /**
+   * Footer site text. Defaults to the deployment site's host plus
+   * `deployment.base` (`docs.acme.com`, `user.github.io/repo`); a string
+   * overrides it, `false` hides it.
+   */
+  site?: string | false;
   /**
    * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
    * A custom page has no frontmatter to read, so its card is otherwise titled
@@ -1131,6 +1261,8 @@ export interface BlumeConfig {
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */
   i18n?: I18nConfig;
+  /** Image optimization: remote-host authorization for the image service. */
+  image?: ImageConfig;
   /** Astro integrations appended after Blume's built-ins, in declaration order. */
   integrations?: AstroIntegration[];
   /** "Last updated" timestamps from git history or frontmatter. Defaults to `false`. */

package/src/core/config.ts

@@ -55,7 +55,8 @@ import type { Diagnostic } from "./types.ts";
  *   and the header repo link.
  *
  * **Appearance**
- * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
+ * - `theme` — `accent` color, `fonts` (curated slugs, any provider family, or
+ *   local font files), `radius`,
  *   `mode` (`system`/`light`/`dark`), and `background`.
  * - `markdown` — `code` (language icons, inline highlighting, line wrap),
  *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
@@ -149,6 +150,13 @@ export interface ConfigLoadResult {
   /** Absolute path of the config file used, or null when defaults were used. */
   configFile: string | null;
   diagnostics: Diagnostic[];
+  /**
+   * Whether the config file set `theme.fonts` itself. The schema always fills
+   * the roles with defaults, so the resolved config can't tell an intentional
+   * font choice from the fallback — and only intentional choices should flow
+   * into derived surfaces like OG card fonts.
+   */
+  themeFontsConfigured: boolean;
 }
 
 const importConfigModule = createModuleLoader();
@@ -182,6 +190,13 @@ export const loadConfig = async (
     }
   }
 
+  // Read before parsing: schema defaults erase the set-vs-defaulted distinction.
+  const themeFontsConfigured = Boolean(
+    raw &&
+    typeof raw === "object" &&
+    (raw as { theme?: { fonts?: unknown } }).theme?.fonts !== undefined
+  );
+
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     // Read the raw config text (when on disk) so errors carry a line/column.
@@ -232,5 +247,6 @@ export const loadConfig = async (
     },
     configFile,
     diagnostics: [],
+    themeFontsConfigured,
   };
 };

package/src/core/content-assets.ts

@@ -0,0 +1,199 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { dirname, extname, relative, resolve } from "pathe";
+
+import { normalizeBasePath } from "./base-path.ts";
+import { hashText } from "./sources/cache.ts";
+import type { FenceState } from "./sources/normalize.ts";
+import {
+  INLINE_CODE,
+  MD_IMAGE,
+  nextFenceState,
+  targetOffsetIn,
+} from "./sources/normalize.ts";
+
+/**
+ * Colocated content images — `![alt](./diagram.png)` next to the page that
+ * references it. The HTML render optimizes these through `astro:assets` into
+ * hashed `_astro/` files, but that mapping doesn't exist yet when the raw
+ * agent-facing Markdown (`/<route>.md`, llms-full.txt, MCP) is snapshotted at
+ * generate time — so a verbatim relative path would 404 for every agent
+ * fetching the page by URL. Instead, the originals are served at
+ * `/blume-assets/content/<project-relative path>` by a generated endpoint (see
+ * `contentAssetsEndpointTemplate`), and these helpers rewrite the relative
+ * references in agent-facing output to that URL.
+ */
+
+/** The endpoint route prefix colocated content images are served under. */
+export const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
+
+// The formats Astro's image pipeline accepts, plus the web-safe pass-throughs;
+// anything else referenced relatively (a `.pdf`, a source file) is left alone.
+const IMAGE_EXTENSIONS = new Set([
+  ".apng",
+  ".avif",
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".svg",
+  ".tiff",
+  ".webp",
+]);
+
+/** Whether a link target is a relative filesystem path (not URL/absolute/hash). */
+const isRelativeTarget = (target: string): boolean =>
+  !(target.startsWith("/") || target.startsWith("#")) && !URL.canParse(target);
+
+/**
+ * The endpoint param a colocated image is served under: its project-relative
+ * path (readable, collision-free — it mirrors the source tree). A file outside
+ * the project root can't be addressed that way (`..` segments don't survive a
+ * URL), so it falls back to a content-addressed name.
+ */
+export const contentAssetParam = (
+  projectRoot: string,
+  absPath: string
+): string => {
+  const rel = relative(projectRoot, absPath);
+  if (rel.startsWith("..")) {
+    return `_/${hashText(absPath)}${extname(absPath)}`;
+  }
+  return rel;
+};
+
+/**
+ * Resolve one image target against its page's directory. Returns the absolute
+ * file path when the target is relative, is an image, and exists on disk —
+ * anything else (remote URLs, `public/` absolutes, broken refs, code-block
+ * examples that happen to look like paths) is null and left untouched.
+ */
+const resolveRelativeImage = (
+  sourceDir: string,
+  target: string
+): string | null => {
+  if (!isRelativeTarget(target)) {
+    return null;
+  }
+  let decoded = target;
+  try {
+    decoded = decodeURI(target);
+  } catch {
+    // Malformed escapes — try the raw text.
+  }
+  if (!IMAGE_EXTENSIONS.has(extname(decoded).toLowerCase())) {
+    return null;
+  }
+  const abs = resolve(sourceDir, decoded);
+  return existsSync(abs) ? abs : null;
+};
+
+/** Encode an endpoint param for use in a Markdown URL, keeping `/` separators. */
+const encodedParam = (param: string): string =>
+  param.split("/").map(encodeURIComponent).join("/");
+
+/**
+ * Rewrite one line's relative image targets. Matches run on a copy with inline
+ * code blanked out (a `` `![x](./y.png)` `` span is syntax being *shown*, not
+ * an image), while replacements splice into the real line by index — the mask
+ * preserves length, so the indices line up.
+ */
+const rewriteLine = (
+  line: string,
+  toUrl: (target: string) => string | null
+): string => {
+  const masked = line.replaceAll(INLINE_CODE, (span) =>
+    " ".repeat(span.length)
+  );
+  let out = "";
+  let cursor = 0;
+  for (const match of masked.matchAll(MD_IMAGE)) {
+    const target = match.groups?.target ?? "";
+    const url = toUrl(target);
+    if (url === null) {
+      continue;
+    }
+    const offset =
+      (match.index ?? 0) +
+      targetOffsetIn(match[0], target, match.groups?.title);
+    out += line.slice(cursor, offset) + url;
+    cursor = offset + target.length;
+  }
+  return out + line.slice(cursor);
+};
+
+/**
+ * Rewrite a page's relative image references to their served
+ * `/blume-assets/content/…` URLs (under `deployment.base` when set). Fenced
+ * code blocks and inline code are skipped; only references whose file actually
+ * exists next to the source are touched. `register` observes each rewritten
+ * asset so a caller can accumulate the files the endpoint must serve.
+ */
+export const rewriteRelativeImages = (options: {
+  source: string;
+  sourcePath: string;
+  projectRoot: string;
+  deployBase?: string;
+  register?: (param: string, absPath: string) => void;
+}): string => {
+  const { source, sourcePath, projectRoot, deployBase, register } = options;
+  const sourceDir = dirname(sourcePath);
+  const prefix = `${normalizeBasePath(deployBase)}${CONTENT_ASSETS_PREFIX}`;
+  const toUrl = (target: string): string | null => {
+    const abs = resolveRelativeImage(sourceDir, target);
+    if (abs === null) {
+      return null;
+    }
+    const param = contentAssetParam(projectRoot, abs);
+    register?.(param, abs);
+    return `${prefix}/${encodedParam(param)}`;
+  };
+
+  let fence: FenceState = null;
+  const lines = source.split("\n").map((line) => {
+    const next = nextFenceState(line, fence);
+    const inFence = fence !== null || next !== null;
+    fence = next;
+    return inFence ? line : rewriteLine(line, toUrl);
+  });
+  return lines.join("\n");
+};
+
+/**
+ * Every colocated image the project's pages reference, keyed by endpoint param.
+ * Serialized to `generated/content-assets.json`, which the
+ * `/blume-assets/[...asset]` endpoint reads to serve the original files. Runs
+ * the same rewrite the agent-Markdown builders apply, so the served set and the
+ * rewritten URLs can't drift apart.
+ */
+export const collectContentAssets = async (project: {
+  context: { root: string };
+  manifest: { routes: { sourcePath?: string }[] };
+}): Promise<Record<string, string>> => {
+  const files: Record<string, string> = {};
+  await Promise.all(
+    project.manifest.routes.map(async (route) => {
+      if (!route.sourcePath) {
+        return;
+      }
+      let source: string;
+      try {
+        source = await readFile(route.sourcePath, "utf-8");
+      } catch {
+        return;
+      }
+      rewriteRelativeImages({
+        projectRoot: project.context.root,
+        register: (param, abs) => {
+          files[param] = abs;
+        },
+        source,
+        sourcePath: route.sourcePath,
+      });
+    })
+  );
+  return files;
+};

package/src/core/data.ts

@@ -1,4 +1,3 @@
-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";
@@ -116,13 +115,25 @@ export interface BlumeDataConfig {
   logo: BlumeLogo | null;
   /** Hosted MCP server, or `null` when MCP is off. */
   mcp: { name: string; route: string } | null;
-  /** Open Graph image generation. */
+  /**
+   * Open Graph image generation. Card fonts are baked into the generated OG
+   * endpoint (they can carry absolute build-machine paths) and deliberately
+   * kept out of this snapshot, which pages serialize into HTML.
+   */
   og: {
+    /** Card subtitle: `seo.og.description` (`false` omits it) over the site description. */
+    description?: string;
     enabled: boolean;
-    /** Extra Google Font family specs for the card renderer, fetched at build. */
-    fonts?: OgFont[];
-    logo?: string;
+    /** Inlined SVG brand mark; `false` renders the card without any mark. */
+    logo?: string | false;
     palette?: ResolvedConfig["seo"]["og"]["palette"];
+    /**
+     * Footer site text: `seo.og.site` if set (`false` hides it), otherwise
+     * the deployment site's host plus `deployment.base` (`docs.acme.com`,
+     * `user.github.io/repo`) — so a subpath deploy's card names the actual
+     * site rather than the platform's shared apex host.
+     */
+    site?: string;
   };
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
@@ -139,6 +150,11 @@ export interface BlumeDataConfig {
   title: string;
   /** Table-of-contents settings: whether to show it and the heading range. */
   toc: ResolvedConfig["toc"];
+  /**
+   * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
+   * list tool to fetch (`ai.llmsTxt.enabled`).
+   */
+  webmcp: { enabled: boolean; llms: boolean };
   /** X (Twitter) attribution: the site's account, and a default creator. */
   x: { creator?: string; handle?: string };
 }

package/src/core/diagnostics.ts

@@ -186,11 +186,12 @@ export const diagnosticsFromZod = (
 ): Diagnostic[] =>
   diagnosticsFromIssues(
     error.issues.map((issue) => ({
-      message:
-        "received" in issue
-          ? `${issue.message} (received: ${JSON.stringify(issue.received)})`
-          : issue.message,
-      path: issue.path,
+      message: issue.message,
+      // Zod 4 paths are PropertyKey[]; a symbol segment has no place in a
+      // dotted schema path or a source-position scan.
+      path: issue.path.filter(
+        (segment): segment is string | number => typeof segment !== "symbol"
+      ),
     })),
     options
   );