blume 1.2.0 → 1.3.0

package/src/deploy/headers.ts

@@ -1,3 +1,12 @@
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  hasApiCatalog,
+} from "../ai/api-catalog.ts";
+import {
+  SIGNATURES_DIRECTORY_PATH,
+  SIGNATURES_DIRECTORY_TYPE,
+} from "../ai/web-bot-auth.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 
@@ -54,13 +63,46 @@ const HEADER_RULES: readonly {
  * 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.
+ *
+ * When a homepage `Link` header is provided (see `ai/link-headers.ts`), an
+ * exact-path rule for the root page advertises the agent-discovery resources —
+ * the static-host counterpart of the Vercel routing-config injection.
  */
-export const buildNetlifyHeaders = (config: ResolvedConfig): string => {
+export const buildNetlifyHeaders = (
+  config: ResolvedConfig,
+  homeLinkHeader?: string | null
+): string => {
   const deployBase = normalizeBasePath(config.deployment.base);
-  return `${HEADER_RULES.map((rule) => {
+  const rules = HEADER_RULES.map((rule) => {
     const prefix = rule.underBasePath
       ? `${deployBase}${config.basePath}`
       : deployBase;
     return `${prefix}/*.${rule.ext}\n  Content-Type: ${rule.contentType}`;
-  }).join("\n")}\n`;
+  });
+  if (homeLinkHeader) {
+    rules.push(`${deployBase}/\n  Link: ${homeLinkHeader}`);
+  }
+  // The well-known discovery files are extensionless, so without an explicit
+  // rule a static host serves their registered media types as octet-stream or
+  // text/plain.
+  if (hasApiCatalog(config)) {
+    rules.push(
+      `${deployBase}${API_CATALOG_PATH}\n  Content-Type: ${API_CATALOG_TYPE}`
+    );
+  }
+  if (config.ai.webBotAuth.keys.length > 0) {
+    rules.push(
+      `${deployBase}${SIGNATURES_DIRECTORY_PATH}\n  Content-Type: ${SIGNATURES_DIRECTORY_TYPE}`
+    );
+  }
+  // Published skills live at the deployment base, outside `basePath` — the
+  // `.md` charset rule above misses them whenever a basePath is set, and the
+  // RFC wants archives served as application/gzip explicitly.
+  if (config.ai.skills) {
+    rules.push(
+      `${deployBase}/.well-known/agent-skills/*.md\n  Content-Type: text/markdown; charset=utf-8`,
+      `${deployBase}/.well-known/agent-skills/*.tar.gz\n  Content-Type: application/gzip`
+    );
+  }
+  return `${rules.join("\n")}\n`;
 };

package/src/deploy/vercel-negotiation.ts

@@ -0,0 +1,233 @@
+/**
+ * `Accept: text/markdown` content negotiation for Vercel server builds.
+ *
+ * Blume prerenders every content page — even under `deployment.output:
+ * "server"` — so a page request never reaches Astro middleware: Vercel serves
+ * the prerendered HTML straight from its static layer. Request-time negotiation
+ * therefore has to live in the platform's routing config. The Vercel adapter
+ * emits a Build Output API `config.json`; these helpers splice extra routes
+ * into it so a content-page request that prefers `text/markdown` is rewritten
+ * (not redirected) to the page's prerendered `.md` mirror — the deployed
+ * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
+ */
+
+/**
+ * Regex for the `accept` header condition. Written to hold under both matching
+ * semantics a router may apply — full-string and substring — by anchoring the
+ * end and letting `(.*,)?` absorb any earlier list entries: it requires a
+ * `text/markdown` or `text/x-markdown` entry terminated by `;`, `,`, or the end
+ * of the header. Kept lookaround-free so it stays valid in RE2, and lowercase
+ * only — real agents send lowercase media types, and q-values are not compared
+ * (a client sending `text/markdown` at `q=0` is pathological). Browsers never
+ * send `text/markdown`, so ordinary page requests are unaffected.
+ */
+export const ACCEPT_MARKDOWN_HEADER_VALUE =
+  "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
+
+/** A Build Output API route — the subset these helpers read and write. */
+export interface VercelRoute {
+  continue?: boolean;
+  dest?: string;
+  handle?: string;
+  has?: { key?: string; type: string; value?: string }[];
+  headers?: Record<string, string>;
+  src?: string;
+  [key: string]: unknown;
+}
+
+const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
+  { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
+];
+
+const VARY_ACCEPT = { vary: "Accept" };
+
+/**
+ * Vercel rejects route `src` patterns longer than 4096 characters, so route
+ * alternations are split across as many route entries as needed. The budget
+ * leaves headroom for the `^(` … `)/?$` wrapper.
+ */
+const MAX_ALTERNATION_LENGTH = 3900;
+
+const REGEX_SPECIALS = /[$()*+.?[\]^{|}\\]/gu;
+
+/**
+ * A route path as it appears on the wire (percent-encoded, matching the layout
+ * of the prerendered files), escaped for literal use inside the alternation.
+ * Escaping runs after encoding; the `%` an encode introduces is not a regex
+ * metacharacter.
+ */
+const routePattern = (route: string): string =>
+  encodeURI(route).replace(REGEX_SPECIALS, "\\$&");
+
+/** Group patterns so each group's alternation stays under the `src` limit. */
+const chunkPatterns = (patterns: readonly string[]): string[][] => {
+  const chunks: string[][] = [];
+  let current: string[] = [];
+  let length = 0;
+  for (const pattern of patterns) {
+    if (
+      current.length > 0 &&
+      length + pattern.length + 1 > MAX_ALTERNATION_LENGTH
+    ) {
+      chunks.push(current);
+      current = [];
+      length = 0;
+    }
+    current.push(pattern);
+    length += pattern.length + 1;
+  }
+  if (current.length > 0) {
+    chunks.push(current);
+  }
+  return chunks;
+};
+
+export interface NegotiationRoutes {
+  /**
+   * `Vary: Accept` for the plain-HTML side of every negotiated URL, so shared
+   * caches keep the two variants apart. Spliced *after* `handle: "filesystem"`
+   * — routes there run against filesystem matches (the same slot the Vercel
+   * adapter uses for its `_astro` cache headers).
+   */
+  headerRoutes: VercelRoute[];
+  /**
+   * The negotiation itself: header-conditional rewrites to the `.md` mirror.
+   * Spliced *before* `handle: "filesystem"` so they run ahead of static-file
+   * matching; the rewritten path then resolves to the prerendered `.md` file.
+   */
+  rewriteRoutes: VercelRoute[];
+}
+
+/**
+ * Build the routes for the given content-route paths (the routes that have a
+ * raw-Markdown mirror, straight from the manifest). Paths are matched with an
+ * optional trailing slash and rewritten `/{route}` → `/{route}.md`; the home
+ * page's mirror lives at `/index.md`.
+ */
+export const buildNegotiationRoutes = (
+  routePaths: readonly string[]
+): NegotiationRoutes => {
+  const home = routePaths.includes("/");
+  const rest = routePaths
+    .filter((path) => path !== "/")
+    .map((path) => routePattern(path));
+  const chunks = chunkPatterns(rest);
+
+  const rewriteRoutes: VercelRoute[] = home
+    ? [
+        {
+          dest: "/index.md",
+          has: ACCEPT_MARKDOWN_CONDITION,
+          headers: VARY_ACCEPT,
+          src: "^/$",
+        },
+      ]
+    : [];
+  for (const chunk of chunks) {
+    rewriteRoutes.push({
+      dest: "$1.md",
+      has: ACCEPT_MARKDOWN_CONDITION,
+      headers: VARY_ACCEPT,
+      src: `^(${chunk.join("|")})/?$`,
+    });
+  }
+
+  const headerChunks = chunkPatterns(home ? ["/", ...rest] : rest);
+  const headerRoutes: VercelRoute[] = headerChunks.map((chunk) => ({
+    continue: true,
+    headers: VARY_ACCEPT,
+    src: `^(?:${chunk.join("|")})/?$`,
+  }));
+
+  return { headerRoutes, rewriteRoutes };
+};
+
+/** The `src` of the injected homepage `Link` header route. */
+const HOME_SRC = "^/$";
+
+/**
+ * Whether a route is one this module previously injected, so re-injection
+ * replaces rather than duplicates. Rewrites are identified by their `accept`
+ * condition; the `Vary` routes by their exact three-field shape (a
+ * user-authored route of that identical shape would be semantically equal to
+ * the one re-added); the homepage `Link` route by its three-field
+ * continue-with-link shape (the Build Output config is adapter-generated, so
+ * no user-authored route competes in this file).
+ */
+const isNegotiationRoute = (route: VercelRoute): boolean =>
+  route.has?.some(
+    (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
+  ) === true ||
+  (route.continue === true &&
+    route.headers?.vary === "Accept" &&
+    typeof route.src === "string" &&
+    Object.keys(route).length === 3) ||
+  (route.continue === true &&
+    typeof route.headers?.link === "string" &&
+    route.src === HOME_SRC &&
+    Object.keys(route).length === 3);
+
+/**
+ * Splice the negotiation routes into a Build Output `config.json`, plus — when
+ * given — a homepage `Link` header route for agent discovery (see
+ * `ai/link-headers.ts`), applied the same way the `Vary` routes are: after
+ * `handle: "filesystem"` with `continue`, so the header rides on the
+ * prerendered homepage response. `contentTypeOverrides` maps static-dir
+ * relative paths to media types via the Build Output `overrides` field — the
+ * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
+ * signature directory). Returns the updated JSON text (tab-indented, like the
+ * adapter's own output), or `null` when there is nothing to do or nowhere
+ * safe to do it: nothing to inject, an unparsable config, no `routes` array,
+ * or no `handle: "filesystem"` marker to anchor the splice.
+ */
+export const injectNegotiationRoutes = (
+  configText: string,
+  routePaths: readonly string[],
+  homeLinkHeader?: string | null,
+  contentTypeOverrides?: Record<string, string>
+): string | null => {
+  const overrideEntries = Object.entries(contentTypeOverrides ?? {});
+  if (
+    routePaths.length === 0 &&
+    !homeLinkHeader &&
+    overrideEntries.length === 0
+  ) {
+    return null;
+  }
+  let config: {
+    overrides?: Record<string, { contentType?: string; path?: string }>;
+    routes?: VercelRoute[];
+  };
+  try {
+    config = JSON.parse(configText);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(config.routes)) {
+    return null;
+  }
+  for (const [path, contentType] of overrideEntries) {
+    // Keyed assignment, so re-injection replaces rather than duplicates and a
+    // user's own override of the same path is simply refreshed.
+    config.overrides = { ...config.overrides, [path]: { contentType } };
+  }
+  const routes = config.routes.filter((route) => !isNegotiationRoute(route));
+  const filesystemIndex = routes.findIndex(
+    (route) => route.handle === "filesystem"
+  );
+  if (filesystemIndex === -1) {
+    return null;
+  }
+  const { headerRoutes, rewriteRoutes } = buildNegotiationRoutes(routePaths);
+  if (homeLinkHeader) {
+    headerRoutes.push({
+      continue: true,
+      headers: { link: homeLinkHeader },
+      src: HOME_SRC,
+    });
+  }
+  routes.splice(filesystemIndex + 1, 0, ...headerRoutes);
+  routes.splice(filesystemIndex, 0, ...rewriteRoutes);
+  config.routes = routes;
+  return `${JSON.stringify(config, null, "\t")}\n`;
+};

package/src/markdown/mermaid.ts

@@ -25,7 +25,13 @@ export const mermaidPlugin = () => ({
         [
           jsxAttribute(
             "class",
-            "not-prose my-6 flex justify-center overflow-x-auto"
+            // Mermaid's SVG has width:100% + a viewBox but no intrinsic width,
+            // so a shrink-wrapped flex item collapses to the 300px replaced-
+            // element fallback and the viewBox scales the drawing down into it.
+            // The child must fill the column (w-full); the svg centers itself
+            // via auto margins, and diagrams that opt out of useMaxWidth keep
+            // a fixed pixel width and scroll via overflow-x-auto.
+            "not-prose my-6 flex overflow-x-auto [&>div]:w-full [&>div>svg]:mx-auto [&>div>svg]:block"
           ),
           jsxAttribute("data-source", node.value),
         ],

package/src/markdown/table-wrap.ts

@@ -7,6 +7,12 @@
  * `scrollable-region-focusable`). It's added unconditionally — whether a given
  * table overflows isn't known at build time — which costs a tab stop on tables
  * that happen to fit; no ARIA label is set to avoid an untranslated string.
+ *
+ * GFM has no headerless-table syntax — the delimiter row is mandatory, so a
+ * table that doesn't want headers is authored with an empty first row
+ * (`| | |`). That parses to a `<thead>` of blank cells, which renders as a
+ * dead band above the body; such a header row is dropped here. A header cell
+ * containing any non-text content (an image, an icon) counts as non-empty.
  */
 
 /** A minimal hast node (avoids a hast type dependency). */
@@ -27,12 +33,38 @@ export interface TableWrapPlugin {
   };
 }
 
+/** Structural elements whose presence alone doesn't make a header non-empty. */
+const HEADER_STRUCTURE = new Set(["thead", "tr", "th"]);
+
+/** Whether a header subtree contains anything that would render visibly. */
+const hasVisibleContent = (node: HastNode): boolean => {
+  if (node.type === "text") {
+    return (node.value ?? "").trim() !== "";
+  }
+  if (node.tagName && !HEADER_STRUCTURE.has(node.tagName)) {
+    return true;
+  }
+  return (node.children ?? []).some(hasVisibleContent);
+};
+
+const isEmptyThead = (node: HastNode): boolean =>
+  node.tagName === "thead" && !hasVisibleContent(node);
+
 export const tableWrapPlugin = (): TableWrapPlugin => ({
   element: {
     filter: ["table"],
     visit(node) {
+      // Satteri serializes an unchanged node by identity, so stripping the
+      // header must produce a new table object — mutating `node.children`
+      // in place has no effect on the output.
+      const table = node.children?.some(isEmptyThead)
+        ? {
+            ...node,
+            children: node.children.filter((child) => !isEmptyThead(child)),
+          }
+        : node;
       return {
-        children: [node],
+        children: [table],
         properties: { className: ["blume-table-scroll"], tabIndex: 0 },
         tagName: "div",
         type: "element",

package/src/og/card.ts

@@ -1,3 +1,5 @@
+import { readFile } from "node:fs/promises";
+
 import { render } from "takumi-js";
 import type { RenderOptions } from "takumi-js";
 import { container, googleFonts, image, text } from "takumi-js/helpers";
@@ -5,11 +7,24 @@ import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
+/** A local font file registered with the OG card renderer, read at build. */
+export interface OgLocalFont {
+  /** Family name the file's face registers under. */
+  name: string;
+  /** Absolute path to the font file. */
+  src: string;
+  /** Face weight; read from the file when omitted. */
+  weight?: number;
+  /** Face style; read from the file when omitted. */
+  style?: "normal" | "italic";
+}
+
 /**
- * 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.
+ * A font to load into the OG card renderer. A bare string is a Google Fonts
+ * family name (weight 400, normal style); the name-only object form pins
+ * weight and style. Both are handed to Takumi's `googleFonts` helper, which
+ * fetches the families from Google Fonts at build and returns per-glyph
+ * coverage subsets. The `src` form reads a local font file instead.
  */
 export type OgFont =
   | string
@@ -20,7 +35,24 @@ export type OgFont =
       weight?: number | number[] | string;
       /** `"normal"`, `"italic"`, or both. */
       style?: "normal" | "italic" | ("normal" | "italic")[];
-    };
+    }
+  | OgLocalFont;
+
+/** Type guard: is this OG font a local file entry? */
+const isLocalOgFont = (font: OgFont): font is OgLocalFont =>
+  typeof font !== "string" && "src" in font;
+
+/**
+ * Which loaded family each card role renders in. Takumi still falls back
+ * across every loaded font per glyph, so a family that misses a script
+ * degrades to the rest of the chain instead of tofu.
+ */
+export interface OgFontFamilies {
+  /** Family for the description and footer text. */
+  body?: string;
+  /** Family for the headline. */
+  title?: string;
+}
 
 const ACCENT_HEX: Record<string, string> = {
   blue: "#3b82f6",
@@ -58,10 +90,11 @@ export interface OgCardOptions {
   /** Muted subtitle under the headline (usually the site description). */
   description?: string;
   /**
-   * Inlined SVG markup of the configured logo, painted into
-   * the brand lockup. Falls back to an accent mark when absent.
+   * Inlined SVG markup of the configured logo, painted into the brand
+   * lockup. Falls back to an accent mark when absent; `false` renders the
+   * card without any brand mark.
    */
-  logo?: string;
+  logo?: string | false;
   /** Optional colors for the generated card. */
   palette?: OgCardPalette;
   /** Footer-left repository slug, e.g. `owner/repo`. */
@@ -75,11 +108,14 @@ export interface OgCardOptions {
    */
   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 for non-Latin titles and card branding. 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}. Local entries are read
+   * from disk instead of Google Fonts.
    */
   fonts?: OgFont[];
+  /** Per-role families from the loaded fonts (title vs body text). */
+  families?: OgFontFamilies;
 }
 
 const WIDTH = OG_IMAGE_WIDTH;
@@ -117,7 +153,9 @@ const fontSubsetCache = new Map<string, Promise<FontSubset[]>>();
  * 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 loadFonts = (
+  fonts: Exclude<OgFont, OgLocalFont>[]
+): Promise<FontSubset[]> => {
   const key = JSON.stringify(fonts);
   let pending = fontSubsetCache.get(key);
   if (!pending) {
@@ -127,6 +165,20 @@ const loadFonts = (fonts: OgFont[]): Promise<FontSubset[]> => {
   return pending;
 };
 
+/**
+ * A lazy loader for a local font file, matching the shape `render` accepts
+ * alongside Google subsets. Keyed by path so the shared renderer reads and
+ * registers each file once across a build's per-page renders; a missing file
+ * rejects at first use, failing the build with the path in the cause.
+ */
+const localFontLoader = (font: OgLocalFont) => ({
+  data: () => readFile(font.src),
+  key: font.src,
+  name: font.name,
+  ...(font.weight === undefined ? {} : { weight: font.weight }),
+  ...(font.style === undefined ? {} : { style: font.style }),
+});
+
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,
 // BORDER = --border.
@@ -229,6 +281,10 @@ const titleSize = (title: string): number => {
   return 76;
 };
 
+/** A spreadable `fontFamily` style, empty when no family is configured. */
+const familyStyle = (family?: string): { fontFamily?: string } =>
+  family ? { fontFamily: family } : {};
+
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = async (
   options: OgCardOptions
@@ -236,22 +292,28 @@ export const renderOgImage = async (
   const { accent, background, border, faint, foreground, muted } =
     resolvePalette(options);
   const brand = options.brand?.trim();
-  const logo = options.logo?.trim();
+  const logo = options.logo === false ? false : options.logo?.trim();
   // Slice by code point, not code unit — `charAt(0)` would split a leading
   // surrogate pair (an emoji brand initial) into a lone half that renders blank.
   const initial = brand ? ([...brand][0]?.toUpperCase() ?? "") : "";
   const description = options.description?.trim();
   const repo = options.repo?.trim();
   const site = options.site?.trim();
+  const titleFamily = familyStyle(options.families?.title);
+  const bodyFamily = familyStyle(options.families?.body);
 
   // Logo only — no brand-name label beside it. A wordmark logo already spells
   // the name, and rendering the site title next to it duplicated the brand
   // ("Ultracite  Ultracite"). Without a logo, the accent tile with the brand
-  // initial stands in.
+  // initial stands in; `logo: false` opts out of any mark.
+  const mark = (): Node[] => {
+    if (logo === false) {
+      return [];
+    }
+    return [logo ? logoMark(logo, foreground) : initialMark(accent, initial)];
+  };
   const header = container({
-    children: [
-      logo ? logoMark(logo, foreground) : initialMark(accent, initial),
-    ],
+    children: mark(),
     style: { alignItems: "center", display: "flex" },
   });
 
@@ -265,6 +327,7 @@ export const renderOgImage = async (
         lineHeight: 1.05,
         maxWidth: 1010,
         textWrap: "balance",
+        ...titleFamily,
       }),
       description
         ? text(truncate(description, 140), {
@@ -274,6 +337,7 @@ export const renderOgImage = async (
             marginTop: 28,
             maxWidth: 900,
             textWrap: "balance",
+            ...bodyFamily,
           })
         : container({}),
     ],
@@ -290,10 +354,10 @@ export const renderOgImage = async (
             container({
               children: [
                 repo
-                  ? text(repo, { color: muted, fontSize: 22 })
+                  ? text(repo, { color: muted, fontSize: 22, ...bodyFamily })
                   : container({}),
                 site
-                  ? text(site, { color: faint, fontSize: 22 })
+                  ? text(site, { color: faint, fontSize: 22, ...bodyFamily })
                   : container({}),
               ],
               style: {
@@ -324,12 +388,17 @@ export const renderOgImage = async (
   });
 
   const fonts = options.fonts ?? [];
+  const googleFamilies = fonts.filter((font) => !isLocalOgFont(font));
+  const localFonts = fonts.filter((font) => isLocalOgFont(font));
   // `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;
+  // has already loaded, so passing the full font list per page is cheap.
+  const fontSubsets = googleFamilies.length
+    ? await loadFonts(googleFamilies)
+    : [];
+  const cardFonts = [...fontSubsets, ...localFonts.map(localFontLoader)];
 
   return render(node, {
-    fonts: fontSubsets,
+    fonts: cardFonts.length ? cardFonts : undefined,
     format: "png",
     height: HEIGHT,
     images: resolveImages(options.images),