blume 1.2.1 → 1.3.0

package/src/og/derive.ts

@@ -0,0 +1,200 @@
+/**
+ * Bridges `theme.fonts` into the OG card renderer. A site that explicitly
+ * picks its typefaces gets matching cards (and non-Latin coverage) without
+ * configuring `seo.og.fonts`; untouched defaults derive nothing, so plain
+ * sites keep Takumi's built-in font and gain no build-time font fetch.
+ */
+
+import { existsSync } from "node:fs";
+
+import { isAbsolute, join } from "pathe";
+
+import type {
+  FontsConfig,
+  FontValue,
+  LocalFontConfig,
+  RemoteFontConfig,
+} from "../theme/fonts.ts";
+import { GOOGLE_FONTS, isFontSlug } from "../theme/fonts.ts";
+import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
+
+/** Fonts plus per-role families for the generated OG endpoint. */
+export interface DerivedOgFonts {
+  families?: OgFontFamilies;
+  fonts: OgFont[];
+}
+
+/** The weights the card actually renders at (title 600, everything else 400). */
+const CARD_WEIGHTS = [400, 600];
+
+/** Resolve a config path against the project root. */
+const absoluteSrc = (root: string, src: string): string =>
+  isAbsolute(src) ? src : join(root, src);
+
+/**
+ * The weight spec to fetch for a derived Google family: the declared weights
+ * the card uses, the declared numeric weights otherwise, a lone variable
+ * range as-is, or nothing (family default) as the last resort.
+ */
+const googleWeights = (
+  weights: (number | string)[]
+): number[] | string | undefined => {
+  const numbers = weights.filter(
+    (weight): weight is number => typeof weight === "number"
+  );
+  const used = numbers.filter((weight) => CARD_WEIGHTS.includes(weight));
+  if (used.length > 0) {
+    return used;
+  }
+  if (numbers.length > 0) {
+    return numbers;
+  }
+  const [first] = weights;
+  return weights.length === 1 && typeof first === "string" ? first : undefined;
+};
+
+const googleOgFont = (name: string, weights: (number | string)[]): OgFont => {
+  const weight = googleWeights(weights);
+  return weight === undefined ? { name } : { name, weight };
+};
+
+/** Per-variant local entries for the renderer (paths made absolute). */
+const localOgFonts = (font: LocalFontConfig, root: string): OgLocalFont[] =>
+  font.variants.map((variant) => ({
+    name: font.name,
+    src: absoluteSrc(root, variant.src),
+    ...(typeof variant.weight === "number" ? { weight: variant.weight } : {}),
+    // Takumi's per-face style is normal/italic; oblique falls back to the file.
+    ...(variant.style === "normal" || variant.style === "italic"
+      ? { style: variant.style }
+      : {}),
+  }));
+
+/**
+ * The card fonts for one theme role, or null when the role can't flow into
+ * the renderer (an unknown slug string, or a provider Takumi can't fetch —
+ * `googleFonts` only speaks Google's css2 endpoint).
+ */
+const roleFonts = (value: FontValue, root: string): OgFont[] | null => {
+  if (typeof value === "string") {
+    if (!isFontSlug(value)) {
+      return null;
+    }
+    const def = GOOGLE_FONTS[value];
+    return [googleOgFont(def.family, def.weights)];
+  }
+  if ("variants" in value) {
+    return localOgFonts(value, root);
+  }
+  const remote = value as RemoteFontConfig;
+  if ((remote.provider ?? "google") !== "google") {
+    return null;
+  }
+  return [googleOgFont(remote.name, remote.weights ?? CARD_WEIGHTS)];
+};
+
+/** The family name a theme role registers under. */
+const roleFamily = (value: FontValue): string | null => {
+  if (typeof value === "string") {
+    return isFontSlug(value) ? GOOGLE_FONTS[value].family : null;
+  }
+  return value.name;
+};
+
+/**
+ * Derive the OG card fonts from the theme's display and body roles (the two
+ * the card renders), deduped, plus the per-role family names so the title
+ * keeps the display face and the body text the body face.
+ */
+export const deriveOgFonts = (
+  fonts: FontsConfig,
+  root: string
+): DerivedOgFonts => {
+  const derived: OgFont[] = [];
+  const seen = new Set<string>();
+  const families: OgFontFamilies = {};
+
+  const roles = [
+    ["title", fonts?.display],
+    ["body", fonts?.body],
+  ] as const;
+  for (const [role, value] of roles) {
+    if (value === undefined) {
+      continue;
+    }
+    const roleEntries = roleFonts(value, root);
+    if (!roleEntries) {
+      continue;
+    }
+    families[role] = roleFamily(value) ?? undefined;
+    for (const entry of roleEntries) {
+      const key = JSON.stringify(entry);
+      if (!seen.has(key)) {
+        seen.add(key);
+        derived.push(entry);
+      }
+    }
+  }
+
+  return {
+    fonts: derived,
+    ...(families.title || families.body ? { families } : {}),
+  };
+};
+
+/** Explicit `seo.og.fonts` with local `src` paths resolved to absolute. */
+export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
+  fonts.map((font) =>
+    typeof font !== "string" && "src" in font
+      ? { ...font, src: absoluteSrc(root, font.src) }
+      : font
+  );
+
+/**
+ * The fonts baked into the generated OG endpoint. An explicit `seo.og.fonts`
+ * always wins (including `[]` to opt out, keeping the card's role styling
+ * untouched); otherwise a site that explicitly set `theme.fonts` gets its
+ * display/body fonts derived so cards match the site without extra config.
+ */
+export const resolveOgFonts = (
+  options: {
+    /** Explicit `seo.og.fonts`, or undefined when unset. */
+    ogFonts: OgFont[] | undefined;
+    themeFonts: FontsConfig;
+    /** Whether the config file set `theme.fonts` itself (gates derivation). */
+    themeFontsConfigured: boolean;
+  },
+  root: string
+): DerivedOgFonts => {
+  if (options.ogFonts) {
+    return { fonts: resolveOgFontSources(options.ogFonts, root) };
+  }
+  return options.themeFontsConfigured
+    ? deriveOgFonts(options.themeFonts, root)
+    : { fonts: [] };
+};
+
+/**
+ * Every configured local font file (theme roles and `seo.og.fonts`) that is
+ * missing on disk, as absolute paths. Generation fails on these up front — the
+ * alternative is Astro or the OG renderer crashing later with a bare ENOENT.
+ */
+export const missingFontFiles = (
+  options: { ogFonts: OgFont[]; themeFonts: FontsConfig },
+  root: string
+): string[] => {
+  const sources: string[] = [];
+  for (const value of Object.values(options.themeFonts ?? {})) {
+    if (typeof value !== "string" && "variants" in value) {
+      sources.push(
+        ...value.variants.map((variant) => absoluteSrc(root, variant.src))
+      );
+    }
+  }
+  for (const font of options.ogFonts) {
+    if (typeof font !== "string" && "src" in font) {
+      sources.push(absoluteSrc(root, font.src));
+    }
+  }
+  return [...new Set(sources)].filter((path) => !existsSync(path));
+};

package/src/og/index.ts

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

package/src/search/orama-index.ts

@@ -39,6 +39,60 @@ const BOOST = { description: 2, title: 3 };
  */
 const SEGMENTED_LANGUAGES = new Set(["ja", "ko", "th", "zh"]);
 
+/**
+ * Languages indexed as character bigrams rather than whole segments, and
+ * queried to match accordingly. Japanese and Chinese write compounds in
+ * {@link BIGRAM_SCRIPTS} without delimiters; Korean separates words with
+ * spaces and Thai has no comparable bigram convention, so both keep the plain
+ * segmented tokens even where a page mixes in Han or kana.
+ *
+ * Dictionary segmentation alone drops the adjacency that makes a compound term
+ * distinctive: 資金決済法 becomes 資金 / 決済 / 法, and because Orama scores a
+ * bag of words, a page that merely mentions each fragment somewhere outranks
+ * the page about the law itself. Bigrams put that adjacency back as index
+ * terms, and dropping the whole-segment tokens keeps a fragment as common as
+ * 法 from matching on its own.
+ */
+const BIGRAM_LANGUAGES = new Set(["ja", "zh"]);
+
+/**
+ * Segments written entirely in these scripts are the ones re-cut into bigrams,
+ * matching the scripts Lucene's CJK analyzer bigrams. Property escapes rather
+ * than ranges, so ideographs outside the basic plane are covered as well —
+ * 𠮟, the 常用漢字表 form of しかる, is one. The literals that follow belong to
+ * no script of their own but appear only inside such words: the iteration
+ * marks, the prolonged sound mark, and the halfwidth voiced sound marks.
+ */
+const BIGRAM_SCRIPTS =
+  /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}々〆〇ーﾞﾟ]+$/u;
+
+/**
+ * Emit every overlapping 2-character window of `run`, or the lone character.
+ * Windows are cut by code point: an ideograph outside the basic plane is a
+ * surrogate pair, and slicing by code unit would split it into halves that
+ * match nothing.
+ *
+ * Dropping the whole-segment tokens means a single-character query reaches
+ * only pages where the character opens a bigram: a run-final 法 sits in 示法,
+ * which the query 法 does not prefix-match. Lucene's CJK analyzer shares this
+ * property; indexing lone characters alongside the bigrams would reinvite the
+ * fragment noise this file exists to remove.
+ */
+const addBigrams = (run: string, tokens: Set<string>): void => {
+  const characters = [...run];
+  if (characters.length === 1) {
+    tokens.add(run);
+    return;
+  }
+  let previous = "";
+  for (const character of characters) {
+    if (previous) {
+      tokens.add(previous + character);
+    }
+    previous = character;
+  }
+};
+
 /**
  * A word-segmenting tokenizer for languages the default splitter can't handle,
  * built on `Intl.Segmenter` (the same engine `@orama/tokenizers` wraps).
@@ -47,6 +101,13 @@ const SEGMENTED_LANGUAGES = new Set(["ja", "ko", "th", "zh"]);
  * case-insensitively. Returns `undefined` for languages the default tokenizer
  * already serves, and on runtimes without `Intl.Segmenter`, where the caller
  * falls back to Orama's default.
+ *
+ * On a {@link BIGRAM_LANGUAGES} index, runs of adjacent
+ * {@link BIGRAM_SCRIPTS} segments are joined and re-cut into character
+ * bigrams; everything else (Latin, digits, and every segment on a Korean or
+ * Thai index) is emitted as the segmenter produced it. Punctuation and spaces
+ * are not word-like, so they end a run — 「クーリング・オフ」 bigrams either
+ * side of the interpunct rather than across it.
  */
 const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
   const language = locale?.toLowerCase().split(/[-_]/u)[0] ?? "";
@@ -57,16 +118,34 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
     return;
   }
   const segmenter = new Intl.Segmenter(language, { granularity: "word" });
+  // Keyed off the same set the strict query pass reads, so an index is never
+  // built from bigrams that the query side then matches loosely.
+  const bigram = BIGRAM_LANGUAGES.has(language);
   return {
     language,
     normalizationCache: new Map(),
     tokenize: (raw: string): string[] => {
       const tokens = new Set<string>();
+      let run = "";
+      const flush = (): void => {
+        if (run) {
+          addBigrams(run, tokens);
+          run = "";
+        }
+      };
       for (const segment of segmenter.segment(raw.toLowerCase())) {
-        if (segment.isWordLike) {
-          tokens.add(segment.segment);
+        if (!segment.isWordLike) {
+          flush();
+          continue;
         }
+        if (bigram && BIGRAM_SCRIPTS.test(segment.segment)) {
+          run += segment.segment;
+          continue;
+        }
+        flush();
+        tokens.add(segment.segment);
       }
+      flush();
       return [...tokens];
     },
   };
@@ -94,10 +173,19 @@ export const buildOramaIndex = async (
   return db;
 };
 
+/** Orama keeps only documents matching every token at a threshold of 0. */
+const ALL_TOKENS = 0;
+
 /**
  * Query the index, returning the matching documents (highest-ranked first).
  * When `locale` is given, results are filtered to that language via an exact
  * `where` match on the `locale` enum.
+ *
+ * On a bigrammed index the strict pass runs first: a term is only meant to
+ * match where its bigrams sit together, and scoring them independently lets a
+ * page sharing a couple of windows outrank the page the term is about. Terms
+ * spanning several words rarely appear in full on one page, so an empty strict
+ * result falls back to the default pass rather than reporting no matches.
  */
 export const queryOramaIndex = async (
   db: AnyOrama,
@@ -105,12 +193,18 @@ export const queryOramaIndex = async (
   limit: number,
   locale?: string
 ): Promise<OramaDoc[]> => {
-  const found = await search(db, {
+  const params = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
     term,
     ...(locale ? { where: { locale: { eq: locale } } } : {}),
-  });
+  };
+  const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
+  const strict = bigrammed
+    ? await search(db, { ...params, threshold: ALL_TOKENS })
+    : undefined;
+  const found =
+    strict && strict.hits.length > 0 ? strict : await search(db, params);
   return found.hits.map((hit) => hit.document as unknown as OramaDoc);
 };

package/src/theme/entry.ts

@@ -452,19 +452,29 @@ blume-diff {
    even though its chrome wrapper is not-prose. */
 .prose :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code) {
   display: block;
-  overflow-x: auto;
-  padding: 0 1.25rem;
-  /* The scroller is only as tall as the code, so an overlay scrollbar would
-     draw on top of the last line; hide it (wheel/trackpad/keyboard scrolling
-     still works). */
-  scrollbar-width: none;
-}
-
-.prose
-  :where(
-    pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code
-  )::-webkit-scrollbar {
-  display: none;
+  /* Tall blocks scroll vertically in place instead of taking the page. Both
+     axes live on the code element for the same reason: the pre stays static
+     so the header bar and copy button never drift with the scroll. */
+  max-height: 24rem;
+  overflow: auto;
+  /* The small bottom inset keeps the horizontal thumb off the last line's
+     descenders now that scrollbars are visible. */
+  padding: 0 1.25rem 0.375rem;
+  /* Thin theme-colored scrollbars, matching the sidebar treatment, so a
+     height-capped block reads as scrollable instead of simply ending.
+     Safari before 18.2 supports neither property and falls back to the
+     platform-default scrollbar — acceptable, since macOS overlays it. */
+  scrollbar-color: var(--blume-border) transparent;
+  scrollbar-width: thin;
+}
+
+/* The dark border token is too close to the page background to read as a
+   scrollbar thumb; derive a brighter one from the muted foreground instead. */
+:root[data-theme="dark"]
+  .prose
+  :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code) {
+  scrollbar-color: color-mix(in oklab, var(--blume-muted-foreground) 55%, transparent)
+    transparent;
 }
 
 /* Word wrap (markdown.code.wrap): long lines wrap instead of scrolling. The
@@ -532,6 +542,10 @@ pre.blume-source {
 
 pre.blume-source > code {
   flex: 1;
+  /* The pane's measured height is authoritative (it can exceed the prose
+     24rem cap), so undo the generic prose max-height: the code must fill
+     whatever height the tab was given. */
+  max-height: none;
   min-height: 0;
   overflow: auto;
 }
@@ -713,6 +727,13 @@ pre:has(.line.focused):hover .line:not(.focused) {
     display: none !important;
   }
 
+  /* Paper can't scroll: uncap the code scroller so long blocks print in
+     full, same as tab panels are force-expanded below. */
+  .prose :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code) {
+    max-height: none;
+    overflow: visible;
+  }
+
   #blume-content {
     padding: 0 !important;
   }

package/src/theme/fonts.ts

@@ -1,10 +1,11 @@
 /**
- * Curated Google Fonts exposed through `theme.fonts`.
+ * Fonts exposed through `theme.fonts`.
  *
- * Each slug maps to the official Google family name (Astro's font provider needs
- * the exact name), a docs-appropriate set of weights, and a fallback category.
- * Fonts are self-hosted and optimized by Astro's built-in Fonts API; this module
- * only resolves config slugs into the data that drives it.
+ * Each role accepts a curated Google Font slug, a remote-provider family (any
+ * Google/Fontsource/Bunny/Fontshare family by name), or local font files. All
+ * forms resolve to entries for Astro's built-in Fonts API, which self-hosts
+ * and optimizes them; this module only resolves config values into the data
+ * that drives it.
  */
 
 export type FontCategory = "sans" | "serif" | "mono";
@@ -12,22 +13,74 @@ export type FontCategory = "sans" | "serif" | "mono";
 /** The three configurable roles in `theme.fonts`. */
 export type FontSlot = "display" | "body" | "mono";
 
+/** Zero-config Astro font providers usable from `theme.fonts`. */
+export type RemoteFontProvider =
+  | "google"
+  | "fontsource"
+  | "bunny"
+  | "fontshare";
+
+/** A remote-provider family: any family name the provider knows. */
+export interface RemoteFontConfig {
+  /** Family name as the provider lists it, e.g. `"Noto Sans JP"`. */
+  name: string;
+  /** Which provider serves the family. Defaults to `"google"`. */
+  provider?: RemoteFontProvider;
+  /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
+  weights?: (number | string)[];
+  /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
+  fallback?: FontCategory;
+}
+
+/** One `@font-face` declaration for a local font. */
+export interface LocalFontVariant {
+  /** Font file path, relative to the project root. */
+  src: string;
+  /** Face weight; inferred from the file when omitted. */
+  weight?: number | string;
+  /** Face style; inferred from the file when omitted. */
+  style?: "normal" | "italic" | "oblique";
+}
+
+/** A self-hosted family loaded from files in the project. */
+export interface LocalFontConfig {
+  /** Family name used in CSS and the OG card. */
+  name: string;
+  /** The faces to declare (at least one). */
+  variants: LocalFontVariant[];
+  /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
+  fallback?: FontCategory;
+}
+
+/** A role's font: curated slug, remote family, or local files. */
+export type FontValue = string | RemoteFontConfig | LocalFontConfig;
+
 interface FontDef {
   category: FontCategory;
   family: string;
   weights: number[];
 }
 
-/** Resolved theme fonts (a validated slug per role, all optional). */
-export type FontsConfig = Partial<Record<FontSlot, string>> | undefined;
+/** Resolved theme fonts (a validated value per role, all optional). */
+export type FontsConfig = Partial<Record<FontSlot, FontValue>> | undefined;
 
-/** A single Astro `fonts:` entry (sans the literal `fontProviders.google()`). */
-export interface FontEntry {
-  cssVariable: string;
-  fallbacks: string[];
-  name: string;
-  weights: number[];
-}
+/** A single Astro `fonts:` entry (sans the literal `fontProviders.*()` call). */
+export type FontEntry =
+  | {
+      kind: "remote";
+      provider: RemoteFontProvider;
+      cssVariable: string;
+      fallbacks: string[];
+      name: string;
+      weights: (number | string)[];
+    }
+  | {
+      kind: "local";
+      cssVariable: string;
+      fallbacks: string[];
+      name: string;
+      variants: LocalFontVariant[];
+    };
 
 const FALLBACKS: Record<FontCategory, string[]> = {
   mono: ["ui-monospace", "SF Mono", "Menlo", "monospace"],
@@ -149,28 +202,126 @@ export const FONT_SLUGS = Object.keys(GOOGLE_FONTS);
 export const isFontSlug = (value: string): value is FontSlug =>
   Object.hasOwn(GOOGLE_FONTS, value);
 
+/** Weights loaded for a remote family when the config does not pin them. */
+const DEFAULT_REMOTE_WEIGHTS: (number | string)[] = [400, 500, 600, 700];
+
+/** Kebab-case a family name into a slug (`"Noto Sans JP"` -> `"noto-sans-jp"`). */
+export const slugifyFontName = (name: string): string =>
+  name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/gu, "-")
+    .replaceAll(/^-+|-+$/gu, "");
+
 /** The CSS variable Astro populates for a given font (shared across roles). */
 const fontVar = (slug: string): string => `--blume-ff-${slug}`;
 
 const SLOTS: FontSlot[] = ["display", "body", "mono"];
 
-/** The unique Astro `fonts:` entries for the configured roles (deduped). */
-export const buildFontEntries = (fonts: FontsConfig): FontEntry[] => {
-  if (!fonts) {
-    return [];
-  }
-  const slugs = SLOTS.map((slot) => fonts[slot]).filter(
-    (slug): slug is FontSlug => typeof slug === "string" && isFontSlug(slug)
-  );
-  return [...new Set(slugs)].map((slug) => {
-    const def = GOOGLE_FONTS[slug];
+/** The fallback category a role uses when a custom font does not pick one. */
+const slotCategory = (slot: FontSlot): FontCategory =>
+  slot === "mono" ? "mono" : "sans";
+
+/** A slot value normalized into an entry, or null for an unknown slug string. */
+const resolveFontValue = (
+  slot: FontSlot,
+  value: FontValue
+): FontEntry | null => {
+  if (typeof value === "string") {
+    if (!isFontSlug(value)) {
+      return null;
+    }
+    const def = GOOGLE_FONTS[value];
     return {
-      cssVariable: fontVar(slug),
+      cssVariable: fontVar(value),
       fallbacks: FALLBACKS[def.category],
+      kind: "remote",
       name: def.family,
+      provider: "google",
       weights: def.weights,
     };
-  });
+  }
+  const slug = slugifyFontName(value.name);
+  const fallbacks = FALLBACKS[value.fallback ?? slotCategory(slot)];
+  if ("variants" in value) {
+    return {
+      cssVariable: fontVar(slug),
+      fallbacks,
+      kind: "local",
+      name: value.name,
+      variants: value.variants,
+    };
+  }
+  return {
+    cssVariable: fontVar(slug),
+    fallbacks,
+    kind: "remote",
+    name: value.name,
+    provider: value.provider ?? "google",
+    weights: value.weights ?? DEFAULT_REMOTE_WEIGHTS,
+  };
+};
+
+/**
+ * Merge two entries that resolved to the same CSS variable. The same remote
+ * family configured twice unions its weights (so a custom `{ name: "Inter" }`
+ * coexists with the curated `inter` default in another role); identical local
+ * definitions collapse. Anything else is a config conflict worth failing on.
+ */
+const mergeFontEntries = (current: FontEntry, next: FontEntry): FontEntry => {
+  if (
+    current.kind === "remote" &&
+    next.kind === "remote" &&
+    current.provider === next.provider &&
+    current.name === next.name
+  ) {
+    return {
+      ...current,
+      weights: [...new Set([...current.weights, ...next.weights])],
+    };
+  }
+  if (
+    current.kind === "local" &&
+    next.kind === "local" &&
+    current.name === next.name &&
+    JSON.stringify(current.variants) === JSON.stringify(next.variants)
+  ) {
+    return current;
+  }
+  throw new Error(
+    `theme.fonts: "${next.name}" conflicts with "${current.name}" — both resolve to the CSS variable "${current.cssVariable}" with different definitions. Rename one family or align their definitions.`
+  );
+};
+
+/** The unique Astro `fonts:` entries for the configured roles (deduped). */
+export const buildFontEntries = (fonts: FontsConfig): FontEntry[] => {
+  if (!fonts) {
+    return [];
+  }
+  const entries = new Map<string, FontEntry>();
+  for (const slot of SLOTS) {
+    const value = fonts[slot];
+    if (value === undefined) {
+      continue;
+    }
+    const entry = resolveFontValue(slot, value);
+    if (!entry) {
+      continue;
+    }
+    const current = entries.get(entry.cssVariable);
+    entries.set(
+      entry.cssVariable,
+      current ? mergeFontEntries(current, entry) : entry
+    );
+  }
+  return [...entries.values()];
+};
+
+/** The slug backing a slot's CSS variable, or null for an unknown slug string. */
+const slotSlug = (value: FontValue): string | null => {
+  if (typeof value === "string") {
+    return isFontSlug(value) ? value : null;
+  }
+  return slugifyFontName(value.name);
 };
 
 /**
@@ -183,10 +334,12 @@ export const buildFontsCss = (fonts: FontsConfig): string => {
     return "";
   }
   const lines = SLOTS.flatMap((slot) => {
-    const slug = fonts[slot];
-    return slug && isFontSlug(slug)
-      ? [`  --blume-font-${slot}-src: var(${fontVar(slug)});`]
-      : [];
+    const value = fonts[slot];
+    if (value === undefined) {
+      return [];
+    }
+    const slug = slotSlug(value);
+    return slug ? [`  --blume-font-${slot}-src: var(${fontVar(slug)});`] : [];
   });
   return lines.length > 0
     ? `/* Generated by Blume from theme.fonts. */\n:root {\n${lines.join("\n")}\n}\n`