blume 2.0.2 → 2.1.0

package/src/og/card.ts

@@ -2,7 +2,13 @@ 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";
+import {
+  collectCodepoints,
+  container,
+  googleFonts,
+  image,
+  text,
+} from "takumi-js/helpers";
 import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
 import { svgDimensions } from "../core/svg-dimensions.ts";
@@ -42,6 +48,9 @@ export type OgFont =
     }
   | OgLocalFont;
 
+/** An OG font fetched from Google Fonts (a bare family name or the object form). */
+export type OgGoogleFont = Exclude<OgFont, OgLocalFont>;
+
 /**
  * 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
@@ -54,15 +63,16 @@ export interface OgFontFamilies {
   title?: string;
 }
 
-// Named presets resolve from the theme's own OKLCH table — Takumi parses the
-// full CSS color grammar, so the card renders exactly the accent the site
-// shows (a separate hand-synced hex palette used to drift: the card's "blue"
-// was Tailwind's, not Blume's). Anything else is handed to Takumi as-is, and
-// a genuinely malformed value fails the build with a parse error naming it.
+// Named presets resolve from the theme's own OKLCH table, in their light
+// shade since the card is light — Takumi parses the full CSS color grammar,
+// so the card renders exactly the accent the site shows (a separate
+// hand-synced hex palette used to drift: the card's "blue" was Tailwind's,
+// not Blume's). Anything else is handed to Takumi as-is, and a genuinely
+// malformed value fails the build with a parse error naming it.
 // `isAccentPreset` keeps a preset name like "constructor" from resolving up
 // the prototype chain.
 const resolveAccent = (accent: string): string =>
-  isAccentPreset(accent) ? ACCENTS[accent] : accent;
+  isAccentPreset(accent) ? ACCENTS[accent].light : accent;
 
 export interface OgCardPalette {
   accent?: string;
@@ -106,6 +116,12 @@ export interface OgCardOptions {
    * from disk instead of Google Fonts.
    */
   fonts?: OgFont[];
+  /**
+   * Script fallbacks, tried after `fonts` for glyphs nothing else draws. A
+   * card loads them only when its text needs one, so a Latin-only card never
+   * fetches them — see {@link fallbackSubsets}.
+   */
+  fallbacks?: OgGoogleFont[];
   /** Per-role families from the loaded fonts (title vs body text). */
   families?: OgFontFamilies;
 }
@@ -145,9 +161,7 @@ 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: Exclude<OgFont, OgLocalFont>[]
-): Promise<FontSubset[]> => {
+const loadFonts = (fonts: OgGoogleFont[]): Promise<FontSubset[]> => {
   const key = JSON.stringify(fonts);
   let pending = fontSubsetCache.get(key);
   if (!pending) {
@@ -160,6 +174,113 @@ const loadFonts = (
   return pending;
 };
 
+/**
+ * The code points Takumi's built-in Geist draws: whitespace, printable ASCII,
+ * Latin-1 except `µ`, a few Latin extras French needs, and the typographic
+ * punctuation English copy leans on. Probed against the renderer, and
+ * `og-card.test.ts` renders every one, so a Takumi upgrade that drops a glyph
+ * fails there instead of shipping tofu.
+ */
+export const BUILT_IN_GLYPHS: [number, number][] = [
+  [0x09, 0x0d],
+  [0x20, 0x7e],
+  [0xa0, 0xb4],
+  [0xb6, 0xff],
+  [0x1_31, 0x1_31],
+  [0x1_52, 0x1_53],
+  [0x1_78, 0x1_78],
+  [0x20_00, 0x20_0f],
+  [0x20_13, 0x20_14],
+  [0x20_18, 0x20_1a],
+  [0x20_1c, 0x20_1e],
+  [0x20_20, 0x20_22],
+  [0x20_26, 0x20_26],
+  [0x20_28, 0x20_30],
+  [0x20_32, 0x20_33],
+  [0x20_39, 0x20_3a],
+  [0x20_44, 0x20_44],
+  [0x20_5f, 0x20_6f],
+  [0x20_ac, 0x20_ac],
+  [0x21_22, 0x21_22],
+  [0x21_91, 0x21_91],
+  [0x21_93, 0x21_93],
+  [0x22_12, 0x22_12],
+];
+
+/** Emoji render as Twemoji images, never from a font. */
+const EMOJI = /\p{Emoji_Presentation}|\p{Emoji_Component}/u;
+
+/** Whether a card draws `codePoint` without any loaded font. */
+const drawnWithoutFonts = (codePoint: number): boolean =>
+  BUILT_IN_GLYPHS.some(([from, to]) => codePoint >= from && codePoint <= to) ||
+  EMOJI.test(String.fromCodePoint(codePoint));
+
+/** Whether `subset` claims `codePoint` (a subset without ranges claims all). */
+const subsetClaims = (subset: FontSubset, codePoint: number): boolean =>
+  subset.ranges.length === 0 ||
+  subset.ranges.some(([from, to]) => codePoint >= from && codePoint <= to);
+
+/** `family`'s subsets that claim any of `codePoints`. */
+const familySubsets = (
+  subsets: FontSubset[],
+  family: string,
+  codePoints: number[]
+): FontSubset[] =>
+  subsets.filter(
+    (subset) =>
+      subset.subsetOf === family &&
+      codePoints.some((codePoint) => subsetClaims(subset, codePoint))
+  );
+
+/**
+ * The scripts only the CJK families draw. Google slices those fonts by the
+ * glyphs each one really has, so the first family claiming such a character
+ * draws it. Other claims follow Google's shared subset definitions whatever
+ * the font holds — every family's `latin` claims `※`, Arabic's `symbols`
+ * claims `→` — so a claim there proves nothing.
+ */
+const CJK_SCRIPTS =
+  /[\p{Script=Bopomofo}\p{Script=Han}\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}]/u;
+
+/** Whether a claim on `codePoint` means the claiming family draws it. */
+const claimIsExact = (codePoint: number): boolean =>
+  CJK_SCRIPTS.test(String.fromCodePoint(codePoint));
+
+/**
+ * The fallback subsets a card's text needs. Nothing loads, and nothing is
+ * fetched, when the built-in font draws every glyph, so a Latin-only card
+ * builds offline. Otherwise only subsets claiming a glyph beyond the built-in
+ * font load (not every family's `latin`), and a CJK character stops at the
+ * first family that claims it: all four CJK families claim most Han, so left
+ * to `render` each would download its matching slices although only the
+ * first ever paints them.
+ */
+const fallbackSubsets = async (
+  fallbacks: OgGoogleFont[] | undefined,
+  node: Node
+): Promise<FontSubset[]> => {
+  let missing = [...collectCodepoints(node)].filter(
+    (codePoint) => !drawnWithoutFonts(codePoint)
+  );
+  if (!fallbacks?.length || missing.length === 0) {
+    return [];
+  }
+  const subsets = await loadFonts(fallbacks);
+  const needed: FontSubset[] = [];
+  for (const family of new Set(subsets.map((subset) => subset.subsetOf))) {
+    const matching = familySubsets(subsets, family, missing);
+    needed.push(...matching);
+    missing = missing.filter(
+      (codePoint) =>
+        !(
+          claimIsExact(codePoint) &&
+          matching.some((subset) => subsetClaims(subset, codePoint))
+        )
+    );
+  }
+  return needed;
+};
+
 /**
  * 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
@@ -422,7 +543,11 @@ export const renderOgImage = async (
   const fontSubsets = googleFamilies.length
     ? await loadFonts(googleFamilies)
     : [];
-  const cardFonts = [...fontSubsets, ...localFonts.map(localFontLoader)];
+  const cardFonts = [
+    ...fontSubsets,
+    ...localFonts.map(localFontLoader),
+    ...(await fallbackSubsets(options.fallbacks, node)),
+  ];
 
   return render(node, {
     fonts: cardFonts.length ? cardFonts : undefined,

package/src/og/derive.ts

@@ -2,9 +2,9 @@
  * 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. Locales
- * in scripts that font can't draw (Japanese, Hindi, Russian, …) add a Noto
- * fallback for their script either way.
+ * sites keep Takumi's built-in font. Either way every card gets a Noto
+ * fallback stack for the scripts that font can't draw (Japanese, Hindi,
+ * Russian, …), which it fetches only when its text needs one.
  */
 
 import { existsSync } from "node:fs";
@@ -19,9 +19,10 @@ import type {
 import { GOOGLE_FONTS, isFontSlug, localeFontSubsets } from "../theme/fonts.ts";
 import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
 
-/** Fonts plus per-role families for the generated OG endpoint. */
+/** Fonts, script fallbacks, and per-role families for the OG endpoint. */
 export interface DerivedOgFonts {
   families?: OgFontFamilies;
+  fallbacks?: OgFallbackFont[];
   fonts: OgFont[];
 }
 
@@ -165,17 +166,17 @@ export const deriveOgFonts = (
 /**
  * The family Takumi renders a card in when no font is loaded: its embedded
  * Geist, which covers Latin only. Naming it keeps a card's Latin text in that
- * face once locale fallbacks are loaded, since Takumi otherwise tries loaded
- * fonts first; a glyph Geist lacks still falls back to them. Were Takumi to
- * rename it, the name would resolve to nothing and cards would fall back to
- * the loaded fonts, never to tofu.
+ * face once fallbacks are loaded, since Takumi otherwise tries loaded fonts
+ * first; a glyph Geist lacks still falls back to them. Were Takumi to rename
+ * it, the name would resolve to nothing and cards would fall back to the
+ * loaded fonts, never to tofu.
  */
 const BUILT_IN_FAMILY = "Geist";
 
 /**
  * The Google Noto family that draws each language's script, keyed by BCP 47
  * language subtag, for scripts beyond the Latin, Cyrillic, Greek, and
- * Vietnamese that `Noto Sans` covers (see {@link localeOgFonts}). Keep keys
+ * Vietnamese that `Noto Sans` covers (see {@link localeFamily}). Keep keys
  * alphabetical.
  */
 const SCRIPT_FAMILIES = {
@@ -219,8 +220,8 @@ const isScriptLanguage = (
 ): language is keyof typeof SCRIPT_FAMILIES =>
   Object.hasOwn(SCRIPT_FAMILIES, language);
 
-/** A locale fallback: a Google family at the weights the card renders. */
-export interface LocaleOgFont {
+/** A script fallback: a Google family at the weights the card renders. */
+export interface OgFallbackFont {
   name: string;
   weight: number[];
 }
@@ -246,16 +247,28 @@ const localeFamily = (locale: string): string | null => {
 };
 
 /**
- * The fallback card fonts the configured locales' scripts need, at the card's
- * weights. Takumi's built-in font covers only basic Latin, so without these a
- * Japanese or Hindi page's card renders every glyph as tofu. The renderer
- * fetches only the glyph subsets a card's text uses, so an English card on
- * the same site pulls nothing extra.
+ * Every script's fallback, in the order a card tries them: `Noto Sans` for
+ * extended Latin, Cyrillic, Greek, and Vietnamese, then a family per script.
+ * The CJK families all draw Han ideographs, so the first one wins them —
+ * Japanese forms, unless a configured locale moves its own family ahead.
  */
-export const localeOgFonts = (locales: string[]): LocaleOgFont[] => {
+const DEFAULT_FALLBACKS = [
+  "Noto Sans",
+  ...new Set(Object.values(SCRIPT_FAMILIES)),
+  "Noto Sans TC",
+];
+
+/**
+ * The card's script fallbacks, at the card's weights: each configured
+ * locale's family first, so a Chinese site draws Han in Chinese forms, then
+ * every other script's, so a page in a language the site never configured
+ * still renders instead of tofu. Takumi's built-in font covers only basic
+ * Latin; the card fetches these only when its text needs a glyph beyond it,
+ * and then only the families and subsets that glyph needs.
+ */
+export const ogFallbackFonts = (locales: string[]): OgFallbackFont[] => {
   const names = new Set<string>();
-  for (const locale of locales) {
-    const family = localeFamily(locale);
+  for (const family of [...locales.map(localeFamily), ...DEFAULT_FALLBACKS]) {
     if (family) {
       names.add(family);
     }
@@ -272,27 +285,24 @@ const ogFontName = (font: OgFont): string =>
   isGoogleFamilyName(font) ? font : font.name;
 
 /**
- * `derived` plus the locale fallbacks it doesn't already load. A card that
+ * `derived` plus the script fallbacks it doesn't already load. A card that
  * names no family is pinned to {@link BUILT_IN_FAMILY}, so its Latin text
  * keeps the face it had before any fallback was loaded.
  */
-const withLocaleFonts = (
+const withFallbacks = (
   derived: DerivedOgFonts,
   locales: string[]
 ): DerivedOgFonts => {
   const loaded = new Set(derived.fonts.map(ogFontName));
-  const fallbacks = localeOgFonts(locales).filter(
-    (font) => !loaded.has(ogFontName(font))
-  );
-  if (fallbacks.length === 0) {
-    return derived;
-  }
   return {
+    fallbacks: ogFallbackFonts(locales).filter(
+      (font) => !loaded.has(font.name)
+    ),
     families: derived.families ?? {
       body: BUILT_IN_FAMILY,
       title: BUILT_IN_FAMILY,
     },
-    fonts: [...derived.fonts, ...fallbacks],
+    fonts: derived.fonts,
   };
 };
 
@@ -307,8 +317,8 @@ export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
  * 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,
- * and either way the configured locales add a fallback for each script the
- * built-in font can't draw.
+ * and either way every card gets the script fallbacks, the configured
+ * locales' first.
  */
 export const resolveOgFonts = (
   options: {
@@ -328,7 +338,7 @@ export const resolveOgFonts = (
   const derived = options.themeFontsConfigured
     ? deriveOgFonts(options.themeFonts, root)
     : { fonts: [] };
-  return withLocaleFonts(derived, options.locales ?? []);
+  return withFallbacks(derived, options.locales ?? []);
 };
 
 /**

package/src/og/index.ts

@@ -11,4 +11,5 @@ export type {
   OgCardPalette,
   OgFont,
   OgFontFamilies,
+  OgGoogleFont,
 } from "./card.ts";

package/src/openapi/asyncapi.ts

@@ -46,7 +46,8 @@ export interface AsyncApiChannelObject {
   messages?: Record<string, AsyncApiRefLike>;
   parameters?: Record<string, AsyncApiRefLike>;
   servers?: AsyncApiRefLike[];
-  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+  bindings?: Record<string, AsyncApiSpecValue>;
   [key: string]: AsyncApiSpecValue;
 }
 
@@ -61,7 +62,8 @@ export interface AsyncApiOperationObject {
   tags?: { name?: string; description?: string }[];
   security?: AsyncApiRefLike[];
   messages?: AsyncApiRefLike[];
-  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+  bindings?: Record<string, AsyncApiSpecValue>;
   [key: string]: AsyncApiSpecValue;
 }
 

package/src/openapi/model.ts

@@ -46,6 +46,9 @@ export type HttpMethod = (typeof HTTP_METHODS)[number];
 /** Group used for operations that declare no tag. */
 const UNTAGGED = "Operations";
 
+/** Group used for webhooks that declare no tag. */
+const UNTAGGED_WEBHOOKS = "Webhooks";
+
 /** A lower-case letter or digit followed by a capital: `addPet`, `v2List`. */
 const CASE_BOUNDARY = /(?<before>[\p{Ll}\p{N}])(?<capital>\p{Lu})/gu;
 /** The last capital of an acronym before a capitalized word: `HTTPResponse`. */
@@ -101,6 +104,12 @@ export interface ApiOperationRef {
   deprecated: boolean;
   /** The channel the operation acts on (AsyncAPI only). */
   channelId?: string;
+  /**
+   * An OpenAPI 3.1 webhook: a request the API sends to the reader's endpoint
+   * rather than one it serves. `path` then holds the webhook's name, the key
+   * it has under the document's `webhooks`.
+   */
+  webhook?: true;
 }
 
 /**
@@ -134,8 +143,8 @@ export interface ApiSpecData {
   /** Operations keyed by {@link ApiOperationRef.key}. */
   operations: Record<string, ApiOperationRef>;
   tags: ApiTagRef[];
-  /** Code-sample languages to render per operation. */
-  codeSamples: string[];
+  /** Code-sample languages to render per operation; `false` for none. */
+  codeSamples: string[] | false;
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
   /**
@@ -260,9 +269,18 @@ const isOperation = (
   value: OperationObject | undefined
 ): value is OperationObject => typeof value === "object" && value !== null;
 
-/** A declared tag whose `name` really is a string at runtime, type aside. */
-const hasTagName = (tag: SpecTag): tag is SpecTag =>
-  typeof tag.name === "string";
+/** Whether a spec value is text YAML may have read as a number. */
+const isText = <Value>(value: Value): value is Value & (string | number) =>
+  typeof value === "string" || typeof value === "number";
+
+/**
+ * A spec field that names something, as a string. YAML reads an unquoted
+ * `operationId: 404` or `tags: [2024]` as a number, which still names the
+ * operation or tag; anything else a hand-written spec puts there counts as
+ * absent.
+ */
+const specText = <Value>(value: Value): string | undefined =>
+  isText(value) ? String(value) : undefined;
 
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
@@ -292,12 +310,14 @@ export const tagSlugger = (): ((name: string) => string) => {
   };
 };
 
+/** One entry of a document's `paths` or `webhooks` map. */
+type PathItemEntry =
+  | NonNullable<ApiDocument["paths"]>[string]
+  | NonNullable<ApiDocument["webhooks"]>[string];
+
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
 
-/** A document's declared tag entry (`tags[n]`). */
-type SpecTag = NonNullable<ApiDocument["tags"]>[number];
-
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
   operations: ApiOperationRef[];
@@ -380,10 +400,10 @@ export const operationCollector = (
 
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
- * tags. Operations inherit the first tag they declare; keys are de-duplicated so
- * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item, webhooks), so missing operations
- * aren't silent.
+ * tags, webhooks included. Operations inherit the first tag they declare; keys
+ * are de-duplicated so a repeated `operationId` still yields distinct routes.
+ * `warnings` reports anything skipped (a `$ref` path item), so missing
+ * operations aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
@@ -391,48 +411,67 @@ export const extractOperations = (
 ): ExtractedOperations => {
   const warnings: string[] = [];
   const tagMeta = new Map(
-    (document.tags ?? [])
-      .filter(hasTagName)
-      .map((tag) => [tag.name, tag.description ?? ""])
+    (document.tags ?? []).flatMap((tag): [string, string][] => {
+      const name = specText(tag.name);
+      return name === undefined ? [] : [[name, tag.description ?? ""]];
+    })
   );
   const collector = operationCollector(baseRoute, tagMeta);
 
-  for (const [path, item] of Object.entries(document.paths ?? {})) {
+  // A path item's operations, filed under `name`: a path for `paths`, the
+  // webhook's key for `webhooks`.
+  const addPathItem = (
+    name: string,
+    item: PathItemEntry,
+    webhook: boolean
+  ): void => {
     // A parsed spec can carry a null path item despite the type; skip it.
     if (!item) {
-      continue;
+      return;
     }
     if ("$ref" in item) {
       warnings.push(
-        `Path "${path}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
+        webhook
+          ? `Webhook "${name}" is a $ref to a shared path item; referenced path items are not resolved, so it is missing from the reference. Inline the path item under "webhooks" to render it.`
+          : `Path "${name}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
       );
-      continue;
+      return;
     }
     for (const method of HTTP_METHODS) {
       const operation = item[method];
       if (!isOperation(operation)) {
         continue;
       }
-      collector.add({
+      const operationId = specText(operation.operationId);
+      const entry: CollectedOperation = {
         deprecated: operation.deprecated ?? false,
-        description: operation.description ?? "",
-        key: operationKey(method, path, operation.operationId),
+        description: specText(operation.description) ?? "",
+        // A webhook without an operationId is keyed by its name, which is
+        // already an identifier (`newPet` -> `new-pet`).
+        key: operationKey(
+          method,
+          name,
+          operationId ?? (webhook ? name : undefined)
+        ),
         method,
-        operationId: operation.operationId,
-        path,
-        summary: operation.summary ?? "",
-        tag: operation.tags?.[0] ?? UNTAGGED,
-      });
+        operationId,
+        path: name,
+        summary: specText(operation.summary) ?? "",
+        tag:
+          specText(operation.tags?.[0]) ??
+          (webhook ? UNTAGGED_WEBHOOKS : UNTAGGED),
+      };
+      collector.add(webhook ? { ...entry, webhook: true } : entry);
     }
-  }
+  };
 
-  // OpenAPI 3.1 webhooks (requests the API sends, not ones it serves) have no
-  // page renderer; say so rather than dropping them silently.
-  const webhooks = Object.keys(document.webhooks ?? {});
-  if (webhooks.length > 0) {
-    warnings.push(
-      `The spec declares ${webhooks.length === 1 ? "a webhook" : `${webhooks.length} webhooks`} under "webhooks" (${webhooks.join(", ")}); webhooks aren't rendered, so they are missing from the reference.`
-    );
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    addPathItem(path, item, false);
+  }
+  // OpenAPI 3.1 webhooks: requests the API sends rather than serves. They
+  // follow the paths, so an untagged webhook group sits after the endpoints.
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    addPathItem(name, item, true);
   }
 
   return { ...collector.finish(), warnings };
@@ -450,7 +489,9 @@ export const operationObject = (
   // (AsyncAPI documents go to `asyncApiOperationObject`), so the spec's
   // document is the OpenAPI shape.
   const document = spec.document as ApiDocument;
-  const item = document.paths?.[ref.path];
+  const item = ref.webhook
+    ? document.webhooks?.[ref.path]
+    : document.paths?.[ref.path];
   const operation = method === undefined ? undefined : item?.[method];
   return isOperation(operation) ? operation : undefined;
 };