blume 2.0.1 → 2.0.3

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
@@ -106,6 +115,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 +160,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 +173,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
@@ -261,11 +381,23 @@ const logoMark = (svg: string, foreground: string): Node => {
 };
 
 // Fallback mark when no SVG logo is configured: an accent tile with the brand's
-// initial, matching the docs favicon aesthetic.
-const initialMark = (accent: string, initial: string): Node =>
+// initial, matching the docs favicon aesthetic. The initial takes the headline's
+// family, so it matches the title rather than whichever loaded font comes first.
+const initialMark = (
+  accent: string,
+  initial: string,
+  family: { fontFamily?: string }
+): Node =>
   container({
     children: initial
-      ? [text(initial, { color: "#ffffff", fontSize: 32, fontWeight: 600 })]
+      ? [
+          text(initial, {
+            color: "#ffffff",
+            fontSize: 32,
+            fontWeight: 600,
+            ...family,
+          }),
+        ]
       : [],
     style: {
       alignItems: "center",
@@ -319,7 +451,11 @@ export const renderOgImage = async (
     if (logo === false) {
       return [];
     }
-    return [logo ? logoMark(logo, foreground) : initialMark(accent, initial)];
+    return [
+      logo
+        ? logoMark(logo, foreground)
+        : initialMark(accent, initial, titleFamily),
+    ];
   };
   const header = container({
     children: mark(),
@@ -406,7 +542,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,7 +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.
+ * 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";
@@ -14,12 +16,13 @@ import type {
   FontValue,
   LocalFontConfig,
 } from "../theme/fonts.ts";
-import { GOOGLE_FONTS, isFontSlug } from "../theme/fonts.ts";
+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[];
 }
 
@@ -160,6 +163,149 @@ export const deriveOgFonts = (
   return result;
 };
 
+/**
+ * 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 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 localeFamily}). Keep keys
+ * alphabetical.
+ */
+const SCRIPT_FAMILIES = {
+  am: "Noto Sans Ethiopic",
+  ar: "Noto Sans Arabic",
+  as: "Noto Sans Bengali",
+  bn: "Noto Sans Bengali",
+  ckb: "Noto Sans Arabic",
+  fa: "Noto Sans Arabic",
+  gu: "Noto Sans Gujarati",
+  he: "Noto Sans Hebrew",
+  hi: "Noto Sans Devanagari",
+  hy: "Noto Sans Armenian",
+  ja: "Noto Sans JP",
+  ka: "Noto Sans Georgian",
+  km: "Noto Sans Khmer",
+  kn: "Noto Sans Kannada",
+  ko: "Noto Sans KR",
+  lo: "Noto Sans Lao",
+  ml: "Noto Sans Malayalam",
+  mr: "Noto Sans Devanagari",
+  my: "Noto Sans Myanmar",
+  ne: "Noto Sans Devanagari",
+  or: "Noto Sans Oriya",
+  pa: "Noto Sans Gurmukhi",
+  ps: "Noto Sans Arabic",
+  sa: "Noto Sans Devanagari",
+  si: "Noto Sans Sinhala",
+  ta: "Noto Sans Tamil",
+  te: "Noto Sans Telugu",
+  th: "Noto Sans Thai",
+  ti: "Noto Sans Ethiopic",
+  ur: "Noto Sans Arabic",
+  yi: "Noto Sans Hebrew",
+  zh: "Noto Sans SC",
+} satisfies Record<string, string>;
+
+/** Type guard: does `language` have an entry in the script table? */
+const isScriptLanguage = (
+  language: string
+): language is keyof typeof SCRIPT_FAMILIES =>
+  Object.hasOwn(SCRIPT_FAMILIES, language);
+
+/** A script fallback: a Google family at the weights the card renders. */
+export interface OgFallbackFont {
+  name: string;
+  weight: number[];
+}
+
+/** Subtags that write Chinese in traditional characters (`zh-Hant`, `zh-TW`). */
+const TRADITIONAL_CHINESE = new Set(["hant", "hk", "mo", "tw"]);
+
+/** The Noto family for one locale's script, or null when Geist covers it. */
+const localeFamily = (locale: string): string | null => {
+  const [language = "", ...subtags] = locale.toLowerCase().split("-");
+  if (
+    language === "zh" &&
+    subtags.some((tag) => TRADITIONAL_CHINESE.has(tag))
+  ) {
+    return "Noto Sans TC";
+  }
+  if (isScriptLanguage(language)) {
+    return SCRIPT_FAMILIES[language];
+  }
+  // Anything past plain `latin` in the theme's subset table (Polish, Russian,
+  // Greek, Vietnamese, …) needs glyphs Geist lacks and `Noto Sans` has.
+  return localeFontSubsets([locale]).length > 1 ? "Noto Sans" : null;
+};
+
+/**
+ * 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.
+ */
+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 family of [...locales.map(localeFamily), ...DEFAULT_FALLBACKS]) {
+    if (family) {
+      names.add(family);
+    }
+  }
+  return [...names].map((name) => ({ name, weight: CARD_WEIGHTS }));
+};
+
+/** A bare Google family name entry (as opposed to the object forms). */
+const isGoogleFamilyName = (font: OgFont): font is string =>
+  typeof font === "string";
+
+/** The family an OG font entry registers under. */
+const ogFontName = (font: OgFont): string =>
+  isGoogleFamilyName(font) ? font : font.name;
+
+/**
+ * `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 withFallbacks = (
+  derived: DerivedOgFonts,
+  locales: string[]
+): DerivedOgFonts => {
+  const loaded = new Set(derived.fonts.map(ogFontName));
+  return {
+    fallbacks: ogFallbackFonts(locales).filter(
+      (font) => !loaded.has(font.name)
+    ),
+    families: derived.families ?? {
+      body: BUILT_IN_FAMILY,
+      title: BUILT_IN_FAMILY,
+    },
+    fonts: derived.fonts,
+  };
+};
+
 /** Explicit `seo.og.fonts` with local `src` paths resolved to absolute. */
 export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
   fonts.map((font) =>
@@ -170,10 +316,14 @@ export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
  * 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.
+ * display/body fonts derived so cards match the site without extra config,
+ * and either way every card gets the script fallbacks, the configured
+ * locales' first.
  */
 export const resolveOgFonts = (
   options: {
+    /** The site's configured locale codes (none without `i18n`). */
+    locales?: string[];
     /** Explicit `seo.og.fonts`, or undefined when unset. */
     ogFonts: OgFont[] | undefined;
     themeFonts: FontsConfig;
@@ -185,9 +335,10 @@ export const resolveOgFonts = (
   if (options.ogFonts) {
     return { fonts: resolveOgFontSources(options.ogFonts, root) };
   }
-  return options.themeFontsConfigured
+  const derived = options.themeFontsConfigured
     ? deriveOgFonts(options.themeFonts, root)
     : { fonts: [] };
+  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/graphql-build.ts

@@ -1,4 +1,5 @@
 import type {
+  DocumentNode,
   GraphQLArgument,
   GraphQLEnumType,
   GraphQLField,
@@ -12,8 +13,8 @@ import type {
   GraphQLUnionType,
 } from "graphql";
 import {
+  buildASTSchema,
   buildClientSchema,
-  buildSchema,
   getNamedType,
   isEnumType,
   isInputObjectType,
@@ -21,7 +22,11 @@ import {
   isObjectType,
   isSpecifiedScalarType,
   isUnionType,
+  Kind,
+  parse,
   print,
+  specifiedDirectives,
+  visit,
 } from "graphql";
 
 import type {
@@ -259,6 +264,27 @@ const introspectionOf = <Value>(parsed: Value): object | undefined => {
     : undefined;
 };
 
+/**
+ * SDL with every use of an undeclared directive removed. Subgraph and platform
+ * schemas lean on directives their server defines out of band — Apollo
+ * Federation's `@key` and `@link`, AppSync's `@aws_*` — and strict SDL
+ * validation rejects each one as `Unknown directive`. The reference renders
+ * none of them, so they are dropped rather than declared; every other check
+ * (syntax, unknown types, duplicates) still runs.
+ */
+const withoutUnknownDirectives = (document: DocumentNode): DocumentNode => {
+  const known = new Set(specifiedDirectives.map((directive) => directive.name));
+  for (const definition of document.definitions) {
+    if (definition.kind === Kind.DIRECTIVE_DEFINITION) {
+      known.add(definition.name.value);
+    }
+  }
+  return visit(document, {
+    // `null` deletes the node; `undefined` leaves it in place.
+    Directive: (node) => (known.has(node.name.value) ? undefined : null),
+  });
+};
+
 /**
  * Build the document from schema text: an introspection JSON result (the raw
  * `{ __schema }` shape or a `{ data: { __schema } }` response envelope) or
@@ -289,5 +315,5 @@ export const buildGraphqlDocument = (text: string): GraphqlDocument => {
       )
     );
   }
-  return documentOf(buildSchema(text));
+  return documentOf(buildASTSchema(withoutUnknownDirectives(parse(text))));
 };