blume 1.6.6 → 1.7.0

package/src/markdown/mermaid.ts

@@ -13,6 +13,17 @@ interface CodeNode extends MdastNode {
  * rendered on the client (Mermaid needs a DOM), so the source rides on a string
  * attribute rather than as child text (which MDX would try to parse).
  */
+/**
+ * A ```mermaid (or ~~~mermaid) fence opener at the start of a line. Used to
+ * decide, at generation time, whether the site needs the Mermaid client
+ * library at all — see `featuresTemplate`.
+ */
+const MERMAID_FENCE = /^[ \t]*(?:`{3,}|~{3,})[ \t]*mermaid\b/mu;
+
+/** Whether a page's Markdown/MDX source contains a mermaid fence. */
+export const hasMermaidFence = (text: string): boolean =>
+  MERMAID_FENCE.test(text);
+
 export const mermaidPlugin = () => ({
   code(node: CodeNode, ctx: MdastVisitorContext) {
     if (node.lang !== "mermaid") {

package/src/og/cache.ts

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+
+import type { ProjectContext } from "../core/types.ts";
+import type { OgCardOptions, OgFont } from "./card.ts";
+
+/**
+ * Where a build keeps rendered OG cards between runs (see {@link cardCacheKey}
+ * for what invalidates one). Baked into the generated OG endpoint alongside
+ * the Blume version that renders the cards.
+ */
+export interface OgCache {
+  /** Absolute directory holding `<key>.png` files. */
+  dir: string;
+  /** The Blume version rendering the cards; part of every key. */
+  version: string;
+}
+
+/**
+ * The card cache directory for a project: `node_modules/.cache/blume/og`,
+ * the conventional build-cache location. Vercel and Netlify restore
+ * `node_modules` from their build caches, so a deploy there re-renders only
+ * the cards whose inputs changed; Cloudflare Workers Builds keeps only
+ * package-manager caches (and `node_modules/.astro` for a detected Astro
+ * project), and a self-managed runner needs a cache step for the directory.
+ * A project with no `node_modules` of its own falls back to the runtime's
+ * cache dir next to Astro's and Vite's.
+ */
+export const ogCacheDir = (
+  context: Pick<ProjectContext, "outDir" | "root">
+): string =>
+  existsSync(join(context.root, "node_modules"))
+    ? join(context.root, "node_modules", ".cache", "blume", "og")
+    : join(context.outDir, ".cache", "og");
+
+/**
+ * Per-process tally of cache hits and misses plus the keys this build asked
+ * for, read back by the CLI after `build()` for the summary line and the
+ * prune. On `globalThis` for the same reason as the integration registry: the
+ * endpoint renders in the copy of this module Vite bundled for the prerender,
+ * while the CLI reads from its own bundled copy.
+ */
+interface OgCacheRegistry {
+  hits: number;
+  misses: number;
+  used: Set<string>;
+}
+
+const REGISTRY_KEY = Symbol.for("blume.og-cache");
+
+type RegistryHost = typeof globalThis & { [REGISTRY_KEY]?: OgCacheRegistry };
+
+const registry = (): OgCacheRegistry => {
+  // SAFETY: the registry is stashed on globalThis under a well-known symbol so
+  // every copy of this module in the process shares it; the intersection only
+  // names that slot.
+  const host = globalThis as RegistryHost;
+  host[REGISTRY_KEY] ??= { hits: 0, misses: 0, used: new Set() };
+  return host[REGISTRY_KEY];
+};
+
+/** Type guard: is this OG font a local file entry? */
+export const isLocalOgFont = (
+  font: OgFont
+): font is Extract<OgFont, { src: string }> =>
+  typeof font !== "string" && "src" in font;
+
+// A local font file's contents digest, computed once per path per process: the
+// key must follow the file's bytes, not its mtime (a fresh CI checkout resets
+// every mtime, which would miss the whole cache on each build).
+const localFontDigests = new Map<string, Promise<string>>();
+
+const digestFile = async (path: string): Promise<string> =>
+  createHash("sha256")
+    .update(await readFile(path))
+    .digest("hex");
+
+const localFontDigest = (path: string): Promise<string> => {
+  let digest = localFontDigests.get(path);
+  if (!digest) {
+    digest = digestFile(path);
+    localFontDigests.set(path, digest);
+  }
+  return digest;
+};
+
+/**
+ * The cache key of a card: a digest of everything that decides its pixels —
+ * the card options (title, description, brand, logo markup, palette, footer
+ * text, font families), the fonts (a local file by its contents, a Google
+ * family by its request), and the Blume version, since the layout and the
+ * renderer it pins ship with the package. Pre-fetched `images` are left out:
+ * the endpoint never passes them.
+ */
+export const cardCacheKey = async (
+  version: string,
+  options: OgCardOptions
+): Promise<string> => {
+  const fonts = await Promise.all(
+    (options.fonts ?? []).map(async (font) =>
+      isLocalOgFont(font)
+        ? { ...font, digest: await localFontDigest(font.src) }
+        : font
+    )
+  );
+  const card = { ...options, fonts: undefined, images: undefined };
+  return createHash("sha256")
+    .update(JSON.stringify({ card, fonts, version }))
+    .digest("hex");
+};
+
+const cardPath = (cache: OgCache, key: string): string =>
+  join(cache.dir, `${key}.png`);
+
+/** A cached card's bytes, or `null` when there is none. */
+const readCard = async (file: string): Promise<Uint8Array | null> => {
+  try {
+    return await readFile(file);
+  } catch {
+    return null;
+  }
+};
+
+// Written to a sibling temp file and renamed into place: concurrent page
+// renders may store the same key, and a reader must never see a half-written
+// card.
+const storeCard = async (file: string, png: Uint8Array): Promise<void> => {
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tmp, png);
+  await rename(tmp, file);
+};
+
+/** The in-flight renders of this process, so duplicate titles render once. */
+const inflight = new Map<string, Promise<Uint8Array>>();
+
+const renderAndStore = async (
+  key: string,
+  file: string,
+  options: OgCardOptions,
+  render: (options: OgCardOptions) => Promise<Uint8Array>
+): Promise<Uint8Array> => {
+  try {
+    const png = await render(options);
+    try {
+      await storeCard(file, png);
+    } catch {
+      // An unwritable cache (a read-only workspace) never fails the build.
+    }
+    return png;
+  } finally {
+    inflight.delete(key);
+  }
+};
+
+/**
+ * Serve a card from `cache`, rendering it with `render` on a miss and storing
+ * the result for the next build. Without a cache every card renders; the
+ * cache is only ever a shortcut.
+ */
+export const throughCardCache = async (
+  cache: OgCache | undefined,
+  options: OgCardOptions,
+  render: (options: OgCardOptions) => Promise<Uint8Array>
+): Promise<Uint8Array> => {
+  if (!cache) {
+    return render(options);
+  }
+  const key = await cardCacheKey(cache.version, options);
+  const state = registry();
+  state.used.add(key);
+  const file = cardPath(cache, key);
+  const hit = await readCard(file);
+  if (hit) {
+    state.hits += 1;
+    return hit;
+  }
+  let pending = inflight.get(key);
+  if (!pending) {
+    state.misses += 1;
+    pending = renderAndStore(key, file, options, render);
+    inflight.set(key, pending);
+  }
+  return pending;
+};
+
+/**
+ * Remove the cards this build never asked for — a renamed page, a changed
+ * description, a previous Blume version — plus any temp file a crashed build
+ * left behind, so a persisted cache holds exactly the current site's cards.
+ * Returns how many files were removed; a missing directory removes nothing.
+ */
+export const pruneCardCache = async (dir: string): Promise<number> => {
+  const { used } = registry();
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return 0;
+  }
+  const stale = entries.filter(
+    (name) =>
+      name.endsWith(".tmp") ||
+      (name.endsWith(".png") && !used.has(name.slice(0, -".png".length)))
+  );
+  await Promise.all(stale.map((name) => rm(join(dir, name), { force: true })));
+  return stale.length;
+};
+
+/**
+ * This process's card cache tally — how many cards a build reused and how many
+ * it rendered — or `null` when no card was requested (OG cards off, or an
+ * endpoint-free build).
+ */
+export const cardCacheTally = (): { hits: number; misses: number } | null => {
+  const { hits, misses } = registry();
+  return hits + misses === 0 ? null : { hits, misses };
+};
+
+/** Reset the tally and the used-key set (tests). */
+export const resetCardCacheTally = (): void => {
+  const state = registry();
+  state.hits = 0;
+  state.misses = 0;
+  state.used.clear();
+};

package/src/og/card.ts

@@ -7,6 +7,8 @@ import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
 import { svgDimensions } from "../core/svg-dimensions.ts";
 import { ACCENTS, isAccentPreset } from "../theme/palette.ts";
+import { isLocalOgFont, throughCardCache } from "./cache.ts";
+import type { OgCache } from "./cache.ts";
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
 /** A local font file registered with the OG card renderer, read at build. */
@@ -40,10 +42,6 @@ export type OgFont =
     }
   | 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
@@ -418,3 +416,13 @@ export const renderOgImage = async (
     width: WIDTH,
   });
 };
+
+/**
+ * {@link renderOgImage} through the on-disk card cache: a card whose inputs
+ * match one rendered by a previous build (or an earlier page of this one) is
+ * read back instead of rendered. `cache` undefined renders every card.
+ */
+export const cachedOgImage = (
+  cache: OgCache | undefined,
+  options: OgCardOptions
+): Promise<Uint8Array> => throughCardCache(cache, options, renderOgImage);

package/src/og/index.ts

@@ -1,4 +1,11 @@
-export { renderOgImage } from "./card.ts";
+export {
+  cardCacheKey,
+  cardCacheTally,
+  ogCacheDir,
+  pruneCardCache,
+} from "./cache.ts";
+export type { OgCache } from "./cache.ts";
+export { cachedOgImage, renderOgImage } from "./card.ts";
 export type {
   OgCardOptions,
   OgCardPalette,

package/src/registry/eject.ts

@@ -17,23 +17,26 @@ import {
 } from "../astro/examples.ts";
 import {
   buildRuntimeData,
+  clientFeaturesFor,
   collectStaged,
   detectNeedsReact,
   detectUsesMath,
+  languageIconCssFor,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
-  askEndpointTemplate,
   askComponentTemplate,
+  askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
   contentConfigTemplate,
   exampleMapTemplate,
-  exampleWrapperTemplate,
-  examplesPageTemplate,
   exampleSlug,
+  examplesPageTemplate,
+  exampleWrapperTemplate,
+  featuresTemplate,
   islandMapTemplate,
   islandWrapperTemplate,
   mcpEndpointTemplate,
@@ -387,6 +390,8 @@ export const eject = async (
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
+  const features = await clientFeaturesFor(project);
+  const languageIcons = await languageIconCssFor(project);
 
   const files: {
     path: string;
@@ -403,6 +408,8 @@ export const eject = async (
         context: relContext,
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        features,
+        featuresPath: "./src/generated/features.ts",
         // No CLI publishes the runtime data modules in memory after eject, so
         // the config aliases each to the JSON snapshot written below.
         generatedModulesDir: "./src/generated",
@@ -476,6 +483,7 @@ export const eject = async (
     {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
+        languageIcons,
         // Relative paths from src/generated/app.css keep the ejected app
         // portable; the blume glob resolves the real install location when
         // the package is hoisted out of the project's own node_modules.
@@ -558,11 +566,18 @@ export const eject = async (
     });
   }
 
-  // The provider-specific client loader behind the `blume:search-client` alias.
-  files.push({
-    content: searchClientTemplate(config),
-    path: join(genDir, "search-client.ts"),
-  });
+  // The client-feature loaders behind the `blume:features` alias, and the
+  // provider-specific client loader behind `blume:search-client`.
+  files.push(
+    {
+      content: featuresTemplate(features),
+      path: join(genDir, "features.ts"),
+    },
+    {
+      content: searchClientTemplate(config),
+      path: join(genDir, "search-client.ts"),
+    }
+  );
 
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);

package/src/theme/entry.ts

@@ -20,6 +20,8 @@ interface TailwindEntryOptions {
   userTheme: string;
   /** Twoslash rich-renderer styles (for fences with the `twoslash` meta). */
   twoslashCss?: string;
+  /** The code-block language icon rules (`languageIconCss`), if any. */
+  languageIcons?: string;
 }
 
 /** Dark mode is driven by `data-theme` on the root element (both sheets). */
@@ -244,6 +246,31 @@ ${THEME_MAPPING}
   unicode-bidi: isolate;
 }
 
+/* The sidebar's rows. A docs site renders every sidebar row on every page,
+   so a large site's HTML is mostly this markup — one utility per row kind
+   instead of the dozen classes each expands to keeps every page (and the
+   build's HTML output) small. Kept in sync with NavTree.astro: a page row,
+   a page-mode group's drill-in button, a collapsible group's summary and
+   the link inside it, and a flat group's heading and the link inside it. */
+@utility blume-nav-link {
+  @apply block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground;
+}
+@utility blume-nav-drill {
+  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted;
+}
+@utility blume-nav-summary {
+  @apply flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden;
+}
+@utility blume-nav-summary-link {
+  @apply -my-1 flex flex-1 items-center gap-1.5 rounded py-1 transition-colors aria-[current=page]:text-foreground aria-[current=page]:font-semibold;
+}
+@utility blume-nav-heading {
+  @apply mb-2 flex items-center gap-1.5 px-2.5 font-medium text-foreground text-sm;
+}
+@utility blume-nav-heading-link {
+  @apply -ml-1 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted;
+}
+
 /* Theme Tailwind Typography (prose) with Blume tokens. */
 .prose {
   --tw-prose-body: var(--blume-foreground);
@@ -459,15 +486,17 @@ blume-diff {
    CodeBlock (no title) never gets data-language, so without this gate the
    absolutely-positioned icon would overlap the first code line. Fenced code
    and titled blocks always have a header, so the icon shows there. */
-.blume-lang-icon {
-  display: none;
-}
-
-.prose > :where(pre[data-language][data-icon]) > .blume-lang-icon {
-  color: var(--blume-muted-foreground);
-  display: block;
+.prose > :where(pre[data-language][data-icon])::after {
+  content: "";
   height: 0.875rem;
   left: 1rem;
+  -webkit-mask-position: center;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  mask-position: center;
+  mask-repeat: no-repeat;
+  mask-size: contain;
+  pointer-events: none;
   position: absolute;
   top: 0.875rem;
   width: 0.875rem;
@@ -477,6 +506,11 @@ blume-diff {
   padding-left: 2.5rem;
 }
 
+/* One mask rule per language the site's Markdown uses (see
+   markdown/language-icon.ts); the ::after above only gets a color and a mask
+   from these, so a block whose language has no rule paints nothing. */
+${options.languageIcons ?? ""}
+
 .prose :where(pre code) {
   background: transparent;
   border-radius: 0;

package/src/theme/fonts.ts

@@ -63,7 +63,14 @@ export type FontValue = string | RemoteFontConfig | LocalFontConfig;
 interface FontDef {
   category: FontCategory;
   family: string;
-  weights: number[];
+  /**
+   * Discrete weights, or one `"min..max"` range for a family Google Fonts
+   * serves as a variable font: the range loads the same variable file the
+   * discrete weights did, declared as one `@font-face` per style instead of
+   * one per weight (16 rules down to 4 for Inter on every page). The three
+   * static families in the table keep discrete weights.
+   */
+  weights: (number | string)[];
 }
 
 /** Resolved theme fonts (a validated value per role, all optional). */
@@ -96,22 +103,22 @@ const FALLBACKS = {
 
 /** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
 export const GOOGLE_FONTS = {
-  "dm-sans": { category: "sans", family: "DM Sans", weights: [400, 500, 700] },
+  "dm-sans": { category: "sans", family: "DM Sans", weights: ["400..700"] },
   figtree: {
     category: "sans",
     family: "Figtree",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "fira-code": {
     category: "mono",
     family: "Fira Code",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
-  geist: { category: "sans", family: "Geist", weights: [400, 500, 600, 700] },
+  geist: { category: "sans", family: "Geist", weights: ["400..700"] },
   "geist-mono": {
     category: "mono",
     family: "Geist Mono",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
   "ibm-plex-mono": {
     category: "mono",
@@ -121,81 +128,81 @@ export const GOOGLE_FONTS = {
   "ibm-plex-sans": {
     category: "sans",
     family: "IBM Plex Sans",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "ibm-plex-serif": {
     category: "serif",
     family: "IBM Plex Serif",
     weights: [400, 500, 600],
   },
-  inter: { category: "sans", family: "Inter", weights: [400, 500, 600, 700] },
+  inter: { category: "sans", family: "Inter", weights: ["400..700"] },
   "inter-tight": {
     category: "sans",
     family: "Inter Tight",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "jetbrains-mono": {
     category: "mono",
     family: "JetBrains Mono",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
-  lora: { category: "serif", family: "Lora", weights: [400, 500, 600, 700] },
+  lora: { category: "serif", family: "Lora", weights: ["400..700"] },
   manrope: {
     category: "sans",
     family: "Manrope",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   merriweather: {
     category: "serif",
     family: "Merriweather",
-    weights: [400, 700],
+    weights: ["400..700"],
   },
   "open-sans": {
     category: "sans",
     family: "Open Sans",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "playfair-display": {
     category: "serif",
     family: "Playfair Display",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "plus-jakarta-sans": {
     category: "sans",
     family: "Plus Jakarta Sans",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
-  roboto: { category: "sans", family: "Roboto", weights: [400, 500, 700] },
+  roboto: { category: "sans", family: "Roboto", weights: ["400..700"] },
   "roboto-mono": {
     category: "mono",
     family: "Roboto Mono",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "source-code-pro": {
     category: "mono",
     family: "Source Code Pro",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
   "source-sans-3": {
     category: "sans",
     family: "Source Sans 3",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "source-serif-4": {
     category: "serif",
     family: "Source Serif 4",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "space-grotesk": {
     category: "sans",
     family: "Space Grotesk",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "space-mono": { category: "mono", family: "Space Mono", weights: [400, 700] },
   "work-sans": {
     category: "sans",
     family: "Work Sans",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
 } satisfies Record<string, FontDef>;