blume 1.4.0 → 1.4.2

package/src/components/islands/hooks.ts

@@ -144,6 +144,12 @@ const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 export interface UseAskAIOptions {
   /** Existing Ask AI endpoint; defaults to Blume's generated `/api/ask`. */
   endpoint?: string;
+  /**
+   * Shown as the assistant's answer when the request fails or throws.
+   * Defaults to an English notice; the built-in island passes its localized
+   * dictionary string.
+   */
+  errorMessage?: string;
 }
 
 /** Shown as the assistant's answer when the request fails or throws. */
@@ -159,6 +165,7 @@ const currentPath = (): string =>
  */
 export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
   const endpoint = options.endpoint ?? DEFAULT_ASK_ENDPOINT;
+  const errorMessage = options.errorMessage ?? ASK_ERROR;
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
   // The stream writes into the conversation via state updates, so `reset()`
@@ -205,7 +212,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
           if (live()) {
-            assistant.content = ASK_ERROR;
+            assistant.content = errorMessage;
             setMessages([...history, { ...assistant }]);
           }
           return;
@@ -236,7 +243,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         // pre-appended empty assistant message as a stuck placeholder. A
         // reset's abort lands here too — the guard keeps it silent.
         if (live()) {
-          assistant.content = ASK_ERROR;
+          assistant.content = errorMessage;
           setMessages([...history, { ...assistant }]);
         }
       } finally {
@@ -245,7 +252,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         }
       }
     },
-    [endpoint, loading, messages]
+    [endpoint, errorMessage, loading, messages]
   );
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):

package/src/components/layout/RootLayout.astro

@@ -117,6 +117,14 @@ interface Props {
   exportPdf?: boolean;
   exportEpub?: boolean;
   feeds?: { title: string; href: string }[];
+  /**
+   * Which agent-discovery resources exist, advertised as `describedby` head
+   * links on every page — so an agent entering on a deep page (a search
+   * result, a shared link) finds the machine-readable surface without probing
+   * the site root. The HTML counterpart of the homepage-only HTTP `Link`
+   * header (see `ai/link-headers.ts`).
+   */
+  discovery?: { agentReadability: boolean; llmsTxt: boolean } | null;
   siteUrl?: string | null;
   pageType?: string;
   published?: string | Date | null;
@@ -198,6 +206,7 @@ const {
   exportPdf,
   exportEpub,
   feeds,
+  discovery,
   siteUrl,
   pageType,
   published,
@@ -312,6 +321,15 @@ const formattedLastModified =
       ).format(lastModifiedDate)
     : null;
 
+// This page's raw-Markdown mirror, advertised as a `text/markdown` alternate
+// in the head. Content routes always have one (see `markdownRoutePaths`, which
+// serves the same `route === "/" ? "/index.md" : "<route>.md"` mapping as the
+// PageActions menu); the generated changelog index — the only "bare" page — is
+// not a content route and has none.
+const markdownMirror = isBare
+  ? null
+  : withBase(page.route === "/" ? "/index.md" : `${page.route}.md`);
+
 // The hosted MCP server's absolute URL, used by the page-actions install menu.
 // Needs a configured site to be useful, so the menu is hidden without one.
 const mcpUrl =
@@ -428,6 +446,29 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         />
       ))
     }
+    {/* Agent discovery on every page, not just the root: an agent that enters
+        on a deep page (a search result, a shared link) never sees the homepage
+        HTTP Link header, so the head carries the same describedby links plus
+        this page's own raw-Markdown mirror. Both rels are IANA-registered. */}
+    {
+      discovery?.agentReadability && (
+        <link
+          href={withBase("/agent-readability.json")}
+          rel="describedby"
+          type="application/json"
+        />
+      )
+    }
+    {
+      discovery?.llmsTxt && (
+        <link href={withBase("/llms.txt")} rel="describedby" type="text/plain" />
+      )
+    }
+    {
+      markdownMirror && (
+        <link href={markdownMirror} rel="alternate" type="text/markdown" />
+      )
+    }
     {
       structuredDataJson && (
         <script
@@ -847,122 +888,50 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         pre.appendChild(button);
       }
 
-      // Click-to-zoom for content images (gated by `markdown.imageZoom`).
-      // Enhances every `.prose img` so plain Markdown images open in a lightbox.
+      // Click-to-zoom for content images (gated by `markdown.imageZoom`),
+      // via medium-zoom: ESC/scroll/click dismissal, natural-size capping,
+      // and the open/close transition races are its problem, not ours.
       // Opt out per-image with `data-no-zoom`.
-      const zoomImages: Iterable<HTMLImageElement> =
-        document.body.hasAttribute("data-blume-image-zoom")
-          ? document.querySelectorAll<HTMLImageElement>(
-              ".prose img:not([data-no-zoom])"
-            )
-          : [];
-      const zoomTargets = Array.from(zoomImages);
-      if (zoomTargets.length > 0) {
-        const reduceMotion = window.matchMedia(
-          "(prefers-reduced-motion: reduce)"
-        ).matches;
-        let active: {
-          clone: HTMLImageElement;
-          original: HTMLImageElement;
-          overlay: HTMLElement;
-        } | null = null;
-
-        const closeZoom = () => {
-          if (!active) {
-            return;
-          }
-          const { clone, original, overlay } = active;
-          active = null;
-          overlay.style.opacity = "0";
-          clone.style.transform = "translate(0px, 0px) scale(1)";
-          const cleanup = () => {
-            overlay.remove();
-            original.style.visibility = "";
-            document.removeEventListener("keydown", onKey);
-            window.removeEventListener("scroll", closeZoom);
-          };
-          if (reduceMotion) {
-            cleanup();
-          } else {
-            clone.addEventListener("transitionend", cleanup, { once: true });
-          }
-        };
-
-        const onKey = (event: KeyboardEvent) => {
-          if (event.key === "Escape") {
-            closeZoom();
-          }
-        };
-
-        const openZoom = (image: HTMLImageElement) => {
-          if (active) {
-            return;
-          }
-          const start = image.getBoundingClientRect();
-          if (start.width === 0 || start.height === 0) {
-            return;
-          }
-
-          const overlay = document.createElement("div");
-          overlay.className =
-            "fixed inset-0 z-[100] flex cursor-zoom-out items-center justify-center bg-background/80 opacity-0 backdrop-blur-sm transition-opacity duration-300";
-
-          const clone = image.cloneNode(true) as HTMLImageElement;
-          clone.className = "absolute m-0 max-w-none rounded-blume shadow-2xl";
-          clone.style.top = `${start.top}px`;
-          clone.style.left = `${start.left}px`;
-          clone.style.width = `${start.width}px`;
-          clone.style.height = `${start.height}px`;
-          clone.style.transformOrigin = "top left";
-          if (!reduceMotion) {
-            clone.style.transition =
-              "transform 300ms cubic-bezier(0.22, 1, 0.36, 1)";
-          }
-
-          overlay.appendChild(clone);
-          document.body.appendChild(overlay);
-          image.style.visibility = "hidden";
-          active = { clone, original: image, overlay };
-
-          const margin = 0.92;
-          const ratio = start.width / start.height;
-          let targetWidth = window.innerWidth * margin;
-          let targetHeight = targetWidth / ratio;
-          if (targetHeight > window.innerHeight * margin) {
-            targetHeight = window.innerHeight * margin;
-            targetWidth = targetHeight * ratio;
-          }
-          const naturalWidth = image.naturalWidth || targetWidth;
-          if (targetWidth > naturalWidth) {
-            targetWidth = naturalWidth;
-            targetHeight = targetWidth / ratio;
-          }
-          const scale = targetWidth / start.width;
-          const dx = (window.innerWidth - targetWidth) / 2 - start.left;
-          const dy = (window.innerHeight - targetHeight) / 2 - start.top;
-
-          requestAnimationFrame(() => {
-            overlay.style.opacity = "1";
-            clone.style.transform = `translate(${dx}px, ${dy}px) scale(${scale})`;
-          });
-
-          overlay.addEventListener("click", closeZoom);
-          document.addEventListener("keydown", onKey);
-          window.addEventListener("scroll", closeZoom, { passive: true });
-        };
-
-        for (const image of zoomTargets) {
+      if (document.body.hasAttribute("data-blume-image-zoom")) {
+        const zoomTargets = Array.from(
+          document.querySelectorAll<HTMLImageElement>(
+            ".prose img:not([data-no-zoom])"
+          )
           // An image that is itself a link navigates on click — binding zoom
           // to it would flash a zoom overlay in the instant before navigation
           // and advertise (via the cursor) a zoom that never happens.
-          if (image.closest("a")) {
-            continue;
-          }
-          image.classList.add("cursor-zoom-in");
-          image.addEventListener("click", () => openZoom(image));
+        ).filter((image) => !image.closest("a"));
+        if (zoomTargets.length > 0) {
+          // Lazy: pages without a zoomable image never load the library,
+          // matching how mermaid is only fetched on pages with a diagram.
+          const { default: mediumZoom } = await import("medium-zoom");
+          mediumZoom(zoomTargets, {
+            background:
+              "color-mix(in oklab, var(--color-background) 80%, transparent)",
+            margin: 24,
+          });
         }
       }
     </script>
+    <style is:global>
+      /* medium-zoom ships no z-index; lift the lightbox above the chrome
+         (header/sidebar) the way the previous z-[100] overlay sat. */
+      .medium-zoom-overlay {
+        backdrop-filter: blur(4px);
+        z-index: 100;
+      }
+      .medium-zoom-image--opened {
+        z-index: 101;
+      }
+      @media (prefers-reduced-motion: reduce) {
+        /* html prefix outranks the library's injected rules regardless of
+           insertion order; its transition declarations carry !important. */
+        html .medium-zoom-image,
+        html .medium-zoom-overlay {
+          transition: none !important;
+        }
+      }
+    </style>
     <WebMcp />
   </body>
 </html>

package/src/components/layout/Search.astro

@@ -171,11 +171,9 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   <script>
     import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
     import { prefixBase } from "../islands/base-path.ts";
-    import {
-      escapeHtml,
-      highlight,
-      matchSnippet,
-    } from "./search/types.ts";
+    import { escape as escapeHtml } from "html-escaper";
+
+    import { highlight, matchSnippet } from "./search/types.ts";
     import type { SearchFn, SearchHit } from "./search/types.ts";
 
     interface Selectable {

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

@@ -1,3 +1,5 @@
+import { escape } from "html-escaper";
+
 /** A single result rendered in the search dialog. */
 export interface SearchHit {
   url: string;
@@ -51,21 +53,9 @@ export const SEARCH_LIMIT = 12;
  */
 export const RESULT_POOL = 48;
 
-const HTML_ESCAPES: Record<string, string> = {
-  '"': "&quot;",
-  "&": "&amp;",
-  "'": "&#39;",
-  "<": "&lt;",
-  ">": "&gt;",
-};
-const HTML_CHARS = /["&'<>]/gu;
 const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
 const WORD_BREAK = /\s+/u;
 
-/** Escape HTML so untrusted text renders literally inside the dialog. */
-export const escapeHtml = (text: string): string =>
-  text.replaceAll(HTML_CHARS, (char) => HTML_ESCAPES[char] ?? char);
-
 /** Split a query into escaped, non-empty search tokens. */
 const queryTokens = (query: string): string[] =>
   query
@@ -83,15 +73,13 @@ const queryTokens = (query: string): string[] =>
 export const highlight = (text: string, query: string): string => {
   const tokens = queryTokens(query);
   if (tokens.length === 0) {
-    return escapeHtml(text);
+    return escape(text);
   }
   const pattern = new RegExp(`(${tokens.join("|")})`, "giu");
   return text
     .split(pattern)
     .map((segment, index) =>
-      index % 2 === 1
-        ? `<mark>${escapeHtml(segment)}</mark>`
-        : escapeHtml(segment)
+      index % 2 === 1 ? `<mark>${escape(segment)}</mark>` : escape(segment)
     )
     .join("");
 };

package/src/components/openapi/helpers.ts

@@ -1,9 +1,11 @@
+import { sample } from "openapi-sampler";
+
 /**
  * Runtime helpers for the OpenAPI components. These operate on the parsed spec
  * behind the `blume:openapi` alias — resolving `$ref`s (kept intact at parse
  * time to avoid circular graphs), labelling types, and generating request
- * examples and code samples. Pure and dependency-free so they run in the browser
- * build with no server-only imports.
+ * examples and code samples. Browser-safe (no server-only imports); example
+ * values come from openapi-sampler, which is likewise browser-safe.
  */
 
 /** A permissive view of an OpenAPI 3.1 schema — only the fields we render. */
@@ -226,88 +228,32 @@ export const objectProperties = (
   return { properties: [...properties.entries()], required };
 };
 
-/** Sentinel: no explicit example is declared on a schema. */
-const NO_VALUE = Symbol("no-value");
-
-/** The declared example/const/default/enum for a schema, or {@link NO_VALUE}. */
-const explicitExample = (schema: SchemaLike): unknown => {
-  if (schema.example !== undefined) {
-    return schema.example;
-  }
-  if (Array.isArray(schema.examples) && schema.examples.length > 0) {
-    return schema.examples[0];
-  }
-  // `const` is the schema's only valid value (the 3.1 discriminator idiom), so
-  // it outranks `default`/`enum` — either of those differing would be invalid.
-  if (schema.const !== undefined) {
-    return schema.const;
-  }
-  if (schema.default !== undefined) {
-    return schema.default;
-  }
-  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
-    return schema.enum[0];
-  }
-  return NO_VALUE;
-};
-
-/** A placeholder value for a primitive (leaf) schema. */
-const primitiveExample = (
-  types: string[],
-  format: string | undefined
-): unknown => {
-  if (types.includes("number") || types.includes("integer")) {
-    return 0;
-  }
-  if (types.includes("boolean")) {
-    return true;
-  }
-  if (format === "date-time") {
-    return "2024-01-01T00:00:00Z";
-  }
-  return format ? `<${format}>` : "string";
-};
-
 /**
- * Build a representative example value for a schema (honoring `example` /
- * `const` / `default` / `enum` first). A `seen` set of `$ref`s guards against
- * the circular schemas that keeping refs intact allows.
+ * Build a representative example value for a schema via openapi-sampler
+ * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
+ * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
+ * `readOnly` fields are skipped (these samples illustrate *requests*, and a
+ * server-generated field has no place in one), and circular `$ref` chains —
+ * which keeping refs intact allows — terminate safely.
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,
-  schemas: Record<string, SchemaLike>,
-  seen = new Set<string>()
+  schemas: Record<string, SchemaLike>
 ): unknown => {
   if (!schema) {
     return null;
   }
-  if (typeof schema.$ref === "string") {
-    if (seen.has(schema.$ref)) {
-      return null;
-    }
-    seen.add(schema.$ref);
-    return exampleValue(resolveSchema(schemas, schema), schemas, seen);
-  }
-  const explicit = explicitExample(schema);
-  if (explicit !== NO_VALUE) {
-    return explicit;
-  }
-  const branch = schema.oneOf?.[0] ?? schema.anyOf?.[0];
-  if (branch) {
-    return exampleValue(branch, schemas, seen);
-  }
-  const types = nonNullTypes(schema.type);
-  if (types.includes("array")) {
-    return [exampleValue(schema.items, schemas, seen)];
-  }
-  if (types.includes("object") || schema.properties || schema.allOf) {
-    const out: Record<string, unknown> = {};
-    for (const [name, prop] of objectProperties(schema, schemas).properties) {
-      out[name] = exampleValue(prop, schemas, new Set(seen));
-    }
-    return out;
+  try {
+    return sample(
+      schema as Parameters<typeof sample>[0],
+      { quiet: true, skipReadOnly: true },
+      { components: { schemas } }
+    );
+  } catch {
+    // An unresolvable $ref or malformed schema is a spec problem the schema
+    // tables already surface; a sample is best-effort.
+    return null;
   }
-  return primitiveExample(types, schema.format);
 };
 
 /** Pretty-print a JSON value for an example/code block. */

package/src/core/component-overrides.ts

@@ -328,13 +328,6 @@ const finalize = (
     );
   }
 
-  if (client && !source) {
-    warnings.push(
-      `Override "${key}" declares client: "${client}" but its component couldn't be resolved to a file, so it can't hydrate. Reference it by an imported component or a path string.`
-    );
-    return { identifier, key, source: null };
-  }
-
   if (!client && source?.framework) {
     warnings.push(
       `Override "${key}" points to a ${FRAMEWORK_LABEL[source.framework]} component (${label}) but has no hydration mode, so it renders as static HTML with no interactivity. Add one, e.g. \`${key}: { component: ${JSON.stringify(label)}, client: "load" }\`.`

package/src/core/config.ts

@@ -219,14 +219,14 @@ export const loadConfig = async (
     // Surface every issue in one failing run — reporting only the first turns
     // a three-mistake config into three fix-rerun-fail loops.
     const moreIssues = rest.map((d) => `  - ${d.message}`).join("\n");
-    throw new BlumeError(
+    const detail =
       rest.length > 0
         ? {
             ...primary,
             message: `${primary.message}\n${rest.length} more config issue(s):\n${moreIssues}`,
           }
-        : primary
-    );
+        : primary;
+    throw new BlumeError(detail);
   }
 
   // Resolve the canonical site URL, then SEO defaults that depend on it.

package/src/core/data.ts

@@ -107,6 +107,13 @@ export interface BlumeDataConfig {
   /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
   dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
+  /**
+   * Which agent-discovery resources exist for the layout to advertise in every
+   * page's `<head>` (`seo.agentReadability`, `ai.llmsTxt.enabled`) — the HTML
+   * counterpart of the homepage-only HTTP `Link` header, for agents that enter
+   * on a deep page (see `ai/link-headers.ts`).
+   */
+  discovery: { agentReadability: boolean; llmsTxt: boolean };
   favicon: BlumeFavicon;
   feedback: boolean;
   i18n: BlumeDataI18n | null;

package/src/core/diagnostics.ts

@@ -1,3 +1,4 @@
+import { colors } from "consola/utils";
 import { relative } from "pathe";
 import type { ZodError } from "zod";
 
@@ -196,25 +197,14 @@ export const diagnosticsFromZod = (
     options
   );
 
-const ESC = String.fromCodePoint(27);
-const COLORS = {
-  blue: `${ESC}[34m`,
-  bold: `${ESC}[1m`,
-  cyan: `${ESC}[36m`,
-  dim: `${ESC}[2m`,
-  red: `${ESC}[31m`,
-  reset: `${ESC}[0m`,
-  yellow: `${ESC}[33m`,
-};
-
-const severityColor = (severity: Diagnostic["severity"]): string => {
+const severityColor = (severity: Diagnostic["severity"]) => {
   if (severity === "error") {
-    return COLORS.red;
+    return colors.red;
   }
   if (severity === "warning") {
-    return COLORS.yellow;
+    return colors.yellow;
   }
-  return COLORS.blue;
+  return colors.blue;
 };
 
 /** Format a single diagnostic for terminal output. */
@@ -224,14 +214,14 @@ export const formatDiagnostic = (
 ): string => {
   const color = severityColor(diagnostic.severity);
   const lines: string[] = [
-    `${color}${COLORS.bold}${diagnostic.code}${COLORS.reset} ${diagnostic.message}`,
+    `${color(colors.bold(diagnostic.code))} ${diagnostic.message}`,
   ];
 
   // An audit finding is about a built URL, and names the source file that fixes
   // it as a second line ("at /docs/api" / "in docs/api.mdx:3:2"). Everything
   // else is about a file alone, and keeps the original single `at file` line.
   if (diagnostic.url) {
-    lines.push(`  ${COLORS.dim}at ${diagnostic.url}${COLORS.reset}`);
+    lines.push(`  ${colors.dim(`at ${diagnostic.url}`)}`);
   }
   if (diagnostic.file) {
     const location = root ? relative(root, diagnostic.file) : diagnostic.file;
@@ -240,15 +230,15 @@ export const formatDiagnostic = (
     const position =
       diagnostic.line === undefined ? "" : `:${diagnostic.line}${column}`;
     const label = diagnostic.url ? "in" : "at";
-    lines.push(`  ${COLORS.dim}${label} ${location}${position}${COLORS.reset}`);
+    lines.push(`  ${colors.dim(`${label} ${location}${position}`)}`);
   }
 
   if (diagnostic.suggestion) {
-    lines.push(`  ${COLORS.cyan}fix: ${diagnostic.suggestion}${COLORS.reset}`);
+    lines.push(`  ${colors.cyan(`fix: ${diagnostic.suggestion}`)}`);
   }
 
   if (diagnostic.docsUrl) {
-    lines.push(`  ${COLORS.dim}docs: ${diagnostic.docsUrl}${COLORS.reset}`);
+    lines.push(`  ${colors.dim(`docs: ${diagnostic.docsUrl}`)}`);
   }
 
   return lines.join("\n");

package/src/core/fs-atomic.ts

@@ -0,0 +1,22 @@
+import { mkdir } from "node:fs/promises";
+
+import { dirname } from "pathe";
+import writeFileAtomic from "write-file-atomic";
+
+/**
+ * Write text to `path` atomically (unique temp file + rename) after ensuring
+ * the parent directory exists, so a concurrent reader or file watcher never
+ * observes a missing or half-written file. write-file-atomic's temp names are
+ * unique per call — a pid-suffixed temp name is not, and two concurrent
+ * writers to the same target in one process (translate lanes, staged-content
+ * writes) would interleave through a shared temp file. `fsync` is off to
+ * match the previous behavior: the point is watcher atomicity, not crash
+ * durability, and a per-file fsync would slow dev regeneration.
+ */
+export const writeTextAtomic = async (
+  path: string,
+  text: string
+): Promise<void> => {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFileAtomic(path, text, { encoding: "utf-8", fsync: false });
+};