blume 2.0.2 → 2.0.3

package/src/markdown/directives.ts

@@ -3,15 +3,30 @@ import { toString as mdastToString } from "mdast-util-to-string";
 import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
 import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
-interface DirectiveNode extends MdastNode {
+export interface DirectiveNode extends MdastNode {
   attributes?: Record<string, string | null | undefined> | null;
   // Satteri gives an empty container directive (`:::note\n:::`) `children: null`.
   children?: MdastNode[] | null;
   name: string;
+  position?: {
+    start?: { offset?: number };
+    end?: { offset?: number };
+  };
+}
+
+/**
+ * The visitor-context slice the directive visitors use. `source` is the page
+ * the directive offsets index into; without it the literal fallback rebuilds
+ * a directive from its node instead. `parent` walks up to an enclosing
+ * container directive, which renders the directives inside it itself.
+ */
+interface DirectiveVisitorContext extends MdastVisitorContext {
+  parent?: (node: MdastNode) => MdastNode | undefined;
+  source?: string;
 }
 
 /** Directive names that map directly onto a Callout type. */
-const CALLOUT_TYPES = new Set([
+export const CALLOUT_TYPES: ReadonlySet<string> = new Set([
   "danger",
   "info",
   "note",
@@ -25,7 +40,7 @@ interface CalloutAliases {
   [alias: string]: string;
 }
 
-const ALIASES: CalloutAliases = {
+export const CALLOUT_ALIASES: Readonly<CalloutAliases> = {
   caution: "warning",
   error: "danger",
   important: "note",
@@ -38,48 +53,239 @@ export const calloutTypeFor = (name: string): string | null => {
   if (CALLOUT_TYPES.has(lower)) {
     return lower;
   }
-  return ALIASES[lower] ?? null;
+  return CALLOUT_ALIASES[lower] ?? null;
+};
+
+/** The markers that open a text (`:name`) and a leaf (`::name`) directive. */
+const LITERAL_MARKERS = new Map([
+  ["leafDirective", "::"],
+  ["textDirective", ":"],
+]);
+
+/** A directive's `[label]` rebuilt from its label's text, or nothing. */
+const labelSource = (label: MdastNode[]): string =>
+  label.length > 0
+    ? `[${mdastToString(label, { includeImageAlt: false })}]`
+    : "";
+
+/** A directive's `{attributes}` rebuilt from its node, or nothing. */
+const attributeSource = (node: DirectiveNode): string => {
+  const attributes = Object.entries(node.attributes ?? {}).map(
+    ([key, value]) => (value ? `${key}="${value}"` : key)
+  );
+  return attributes.length > 0 ? `{${attributes.join(" ")}}` : "";
+};
+
+/** The source a directive node spans, when its offsets point into `source`. */
+const spannedSource = (node: DirectiveNode, source: string): string | null => {
+  const start = node.position?.start?.offset;
+  const end = node.position?.end?.offset;
+  return start !== undefined && end !== undefined
+    ? source.slice(start, end)
+    : null;
 };
 
 /**
- * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
- * `:::tip`, …) onto Blume's `<Callout>` component. The title comes from a
- * `[label]` or a `{title="…"}` attribute; the body becomes the callout content.
- * Directive names that are not callouts are left untouched.
+ * A text or leaf directive exactly as the author wrote it. The slice by
+ * offsets is the exact text — `[label]` and `{attrs}` included — and is
+ * trusted only when it opens with the directive's own marker and name;
+ * content an `<include>` spliced in carries no offsets into this page, so it
+ * is rebuilt from the node instead.
  */
-export const directiveToCalloutPlugin = () => ({
-  containerDirective(node: DirectiveNode, ctx: MdastVisitorContext) {
-    const type = calloutTypeFor(node.name);
-    if (type === null) {
-      return;
+export const directiveSource = (
+  node: DirectiveNode,
+  marker: string,
+  source: string
+): string => {
+  const opening = `${marker}${node.name}`;
+  const slice = spannedSource(node, source);
+  if (slice?.startsWith(opening)) {
+    return slice;
+  }
+  return `${opening}${labelSource(node.children ?? [])}${attributeSource(node)}`;
+};
+
+/**
+ * The node a text or leaf directive renders as: its literal source, as text
+ * in place of a text directive and as a paragraph in place of a leaf one.
+ */
+const literalDirective = (
+  node: DirectiveNode,
+  marker: string,
+  source: string
+): MdastNode => {
+  const text = { type: "text", value: directiveSource(node, marker, source) };
+  return marker === ":" ? text : { children: [text], type: "paragraph" };
+};
+
+const FENCE = /^:{3,}/u;
+
+// The line that closes a container: a colon fence, after whatever quote or
+// list indentation the container sits in.
+const CLOSING_FENCE = /\n[\t >]*(?<fence>:{3,})\s*$/u;
+
+/** A paragraph holding one line of literal text. */
+const literalLine = (value: string): MdastNode => ({
+  children: [{ type: "text", value }],
+  type: "paragraph",
+});
+
+/**
+ * The fence lines of a container directive as the author wrote them — the
+ * opening one with its `[label]` and `{attrs}` — or, without offsets into
+ * this page (an `<include>`), rebuilt from the node. A container left
+ * unclosed runs to the end of its parent and has no closing line.
+ */
+const containerFences = (
+  node: DirectiveNode,
+  label: MdastNode | undefined,
+  source: string
+): string[] => {
+  const slice = spannedSource(node, source) ?? "";
+  const fence = FENCE.exec(slice)?.[0];
+  if (fence === undefined || !slice.startsWith(node.name, fence.length)) {
+    const labelText = labelSource(label ? [label] : []);
+    return [`:::${node.name}${labelText}${attributeSource(node)}`, ":::"];
+  }
+  const [opening = ""] = slice.split("\n", 1);
+  const closing = CLOSING_FENCE.exec(slice.slice(opening.length))?.groups
+    ?.fence;
+  // A shorter fence can't close the container; it is the body's last line.
+  return closing !== undefined && closing.length >= fence.length
+    ? [opening.trimEnd(), closing]
+    : [opening.trimEnd()];
+};
+
+/**
+ * What a container directive renders as. A callout name becomes a
+ * `<Callout>`: the title comes from a `[label]` or a `{title="…"}` attribute,
+ * and the body becomes the callout content. Blume has no other container, and
+ * dropping one would drop its body with it, so any other name — `:::details`,
+ * a `:::warnig` typo — renders its body between its fence lines, as written.
+ * The directives inside render here too, since Satteri reaches them only
+ * after this replacement has taken their original.
+ */
+const renderContainer = (
+  node: DirectiveNode,
+  source: string
+): MdastNode | MdastNode[] => {
+  const children = (node.children ?? []).flatMap((child) =>
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion: a container's body holds directives, containers included
+    literalize(child, source)
+  );
+
+  // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+  // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
+  // other node reads undefined and fails the check.
+  const labelIndex = children.findIndex(
+    (child) =>
+      child.type === "paragraph" &&
+      (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
+  );
+  const [label] = labelIndex === -1 ? [] : children.splice(labelIndex, 1);
+
+  const type = calloutTypeFor(node.name);
+  if (type === null) {
+    const [opening = "", closing] = containerFences(node, label, source);
+    return [
+      literalLine(opening),
+      ...children,
+      ...(closing === undefined ? [] : [literalLine(closing)]),
+    ];
+  }
+
+  // Flatten the label's phrasing children so `:::note[Read **this**]` yields
+  // `Read this`; image alt is excluded (an image is not label text), matching
+  // the historical child-values-only behavior.
+  const title =
+    node.attributes?.title ??
+    (label ? mdastToString(label, { includeImageAlt: false }) : undefined);
+  const attributes = [jsxAttribute("type", type)];
+  if (title) {
+    attributes.push(jsxAttribute("title", title));
+  }
+  return jsxFlowElement("Callout", attributes, children);
+};
+
+/**
+ * `node` with every directive in it rendered: text and leaf directives as
+ * their literal source, containers as {@link renderContainer}.
+ */
+const literalize = (node: MdastNode, source: string): MdastNode[] => {
+  if (node.type === "containerDirective") {
+    // SAFETY: a `containerDirective` carries a `name` plus optional
+    // attributes, children, and position — the `DirectiveNode` shape.
+    return [renderContainer(node as DirectiveNode, source)].flat();
+  }
+  const marker = LITERAL_MARKERS.get(node.type);
+  if (marker) {
+    // SAFETY: only Satteri's `textDirective`/`leafDirective` nodes have a
+    // marker, and they carry a `name` plus optional attributes, children,
+    // and position — the `DirectiveNode` shape.
+    return [literalDirective(node as DirectiveNode, marker, source)];
+  }
+  // SAFETY: a parent's `children` is always a node list; leaves carry none.
+  const children = node.children as MdastNode[] | null | undefined;
+  if (!children) {
+    return [node];
+  }
+  return [
+    {
+      ...node,
+      children: children.flatMap((child) => literalize(child, source)),
+    },
+  ];
+};
+
+/** Whether a container directive (already rendered, body and all) holds `node`. */
+const insideContainer = (node: MdastNode, ctx: DirectiveVisitorContext) => {
+  for (
+    let parent = ctx.parent?.(node);
+    parent !== undefined;
+    parent = ctx.parent?.(parent)
+  ) {
+    if (parent.type === "containerDirective") {
+      return true;
     }
+  }
+  return false;
+};
 
-    const children = [...(node.children ?? [])];
-    let title = node.attributes?.title ?? undefined;
-
-    // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
-    // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
-    // other node reads undefined and fails the check.
-    const labelIndex = children.findIndex(
-      (child) =>
-        child.type === "paragraph" &&
-        (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
-    );
-    if (labelIndex !== -1) {
-      const [label] = children.splice(labelIndex, 1);
-      if (label) {
-        // Flatten the label's phrasing children so `:::note[Read **this**]`
-        // yields `Read this`; image alt is excluded (an image is not label
-        // text), matching the historical child-values-only behavior.
-        title ??= mdastToString(label, { includeImageAlt: false }) || undefined;
-      }
+/** The text and leaf visitor: render the directive as its literal source. */
+const renderLiteral =
+  (marker: string) => (node: DirectiveNode, ctx: DirectiveVisitorContext) => {
+    // A container's body was already rendered into its replacement; a
+    // transform queued on the replaced original would be dropped with a
+    // warning.
+    if (insideContainer(node, ctx)) {
+      return;
     }
+    ctx.replaceNode(node, literalDirective(node, marker, ctx.source ?? ""));
+  };
 
-    const attributes = [jsxAttribute("type", type)];
-    if (title) {
-      attributes.push(jsxAttribute("title", title));
+/**
+ * Satteri MDAST plugin for directives. Container directives (`:::note`,
+ * `:::warning`, `:::tip`, …) map onto Blume's `<Callout>` component, and any
+ * other container renders its body between its literal fence lines (see
+ * {@link renderContainer}).
+ *
+ * Blume handles no text (`:name`) or leaf (`::name`) directives, and prose is
+ * full of text that parses as one — `16:9`, `10:30am`, `og:image`,
+ * `pets:read` — so both render as the literal source the author wrote instead
+ * of vanishing.
+ */
+export const directiveToCalloutPlugin = () => ({
+  containerDirective(node: DirectiveNode, ctx: DirectiveVisitorContext) {
+    // A container inside another was rendered with its enclosing one.
+    if (insideContainer(node, ctx)) {
+      return;
     }
-    ctx.replaceNode(node, jsxFlowElement("Callout", attributes, children));
+    ctx.replaceNode(node, renderContainer(node, ctx.source ?? ""));
   },
+  leafDirective: renderLiteral("::"),
   name: "blume-directive-callout",
+  // Positions are opt-in since satteri 0.10; the literal fallback slices
+  // directives out of the source by offset.
+  options: { position: true },
+  textDirective: renderLiteral(":"),
 });

package/src/markdown/features.ts

@@ -19,3 +19,20 @@ export const MDX_FEATURES = {
   directive: true,
   math: { singleDollarTextMath: false },
 } satisfies Features;
+
+/**
+ * The feature sets for a page body, once its front matter is off. Astro reads
+ * a page's front matter itself and hands the renderer the body alone, and the
+ * search extractor strips it first too — so front matter parsing is off here:
+ * left on, a body that opens with a `---` rule read everything up to the next
+ * `---` line as front matter and dropped it from the page.
+ */
+export const MARKDOWN_BODY_FEATURES = {
+  ...MARKDOWN_FEATURES,
+  frontmatter: false,
+} satisfies Features;
+
+export const MDX_BODY_FEATURES = {
+  ...MDX_FEATURES,
+  frontmatter: false,
+} satisfies Features;

package/src/markdown/index.ts

@@ -13,7 +13,7 @@ import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
 import { externalLinksPlugin } from "./external-links.ts";
-import { MARKDOWN_FEATURES, MDX_FEATURES } from "./features.ts";
+import { MARKDOWN_BODY_FEATURES, MDX_BODY_FEATURES } from "./features.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
 import { includePlugin } from "./include.ts";
 import { inlineCodeHighlightPlugin } from "./inline-code.ts";
@@ -295,9 +295,9 @@ export interface BlumeMarkdownOptions {
 
 /**
  * MDAST plugins that apply to both `.md` and `.mdx`: relative page links
- * rewritten to the root-relative route they mean, then the base-path link
- * rewrite (added only when a `basePath` or `deployBase` is configured), which
- * layers `deployment.base` over the rewritten routes.
+ * rewritten to the served URL of the route they mean, then the base-path link
+ * rewrite for root-relative links (added only when a `basePath` or
+ * `deployBase` is configured).
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
@@ -306,6 +306,7 @@ const blumeSharedMdastPlugins = (
     relativeLinksPlugin({
       contentRoot: options.contentRoot,
       dataFile: options.dataFile,
+      deployBase: options.deployBase,
     })
   ),
   ...(options.basePath || options.deployBase
@@ -330,7 +331,7 @@ const blumeIncludePlugin = (options: BlumeMarkdownOptions): MdastPlugin =>
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
   satteri({
-    features: { ...MARKDOWN_FEATURES },
+    features: { ...MARKDOWN_BODY_FEATURES },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),
@@ -359,7 +360,7 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  */
 export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
   satteri({
-    features: { ...MDX_FEATURES },
+    features: { ...MDX_BODY_FEATURES },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),

package/src/markdown/mdast.ts

@@ -19,9 +19,12 @@ export type MdastValue =
   | MdastValue[]
   | { [key: string]: MdastValue };
 
-/** The visitor context Blume's plugins use to mutate the tree. */
+/**
+ * The visitor context Blume's plugins use to mutate the tree. A list of
+ * nodes takes the replaced node's place in order.
+ */
 export interface MdastVisitorContext {
-  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
+  replaceNode: (node: MdastNode, replacement: MdastNode | MdastNode[]) => void;
 }
 
 /** Any MDAST node, keyed loosely since we build a small subset by hand. */

package/src/markdown/relative-links.ts

@@ -2,6 +2,7 @@ import { fileURLToPath } from "node:url";
 
 import { dirname, normalize, relative, resolve } from "pathe";
 
+import { mountBasePath } from "../core/base-path.ts";
 import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
@@ -130,6 +131,8 @@ export interface RelativeLinksPluginOptions {
    * to publish the snapshot, the plugin reads the file eject writes instead.
    */
   dataFile?: string;
+  /** Astro's `deployment.base` subdirectory (`""` or `/seg`). */
+  deployBase?: string;
 }
 
 /**
@@ -145,9 +148,11 @@ export interface RelativeLinksPluginOptions {
  * entries (remote sources) by the longest trailing path that names one. A file
  * the snapshot doesn't know keeps its links as written.
  *
- * Runs before the base-links plugin, whose `basePath` layering is idempotent,
- * so a rewritten route (which already carries `basePath`) only gains the
- * `deployment.base` prefix.
+ * A rewritten route already carries `basePath`, and the `deployment.base`
+ * prefix goes on here, unconditionally: the route is one Blume serves, so
+ * `guides/setup.md` under base `/guides` is linked at `/guides/guides/setup`.
+ * The base-links plugin that runs next is idempotent per layer, so it leaves
+ * the based route alone.
  */
 export const relativeLinksPlugin = (
   options: RelativeLinksPluginOptions = {}
@@ -155,6 +160,7 @@ export const relativeLinksPlugin = (
   const contentRoot = options.contentRoot
     ? resolve(options.contentRoot)
     : undefined;
+  const deployBase = options.deployBase ?? "";
   const readSnapshot = routeSnapshotReader(options.dataFile);
 
   // Parsed once per published snapshot: the CLI republishes on regeneration,
@@ -245,7 +251,9 @@ export const relativeLinksPlugin = (
     const next = resolveRelativeHref(url, page, page.routeOf, (route) =>
       page.routes.has(route)
     );
-    return next === url ? undefined : next;
+    return next === undefined || next === url
+      ? undefined
+      : mountBasePath(deployBase, next);
   };
 
   const rewrite = (node: UrlNode, ctx: RelativeLinksContext): void => {

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
@@ -422,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,