blume 1.6.5 → 1.7.0

package/src/deploy/function-bundle.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { builtinModules } from "node:module";
 
+import { init, parse } from "es-module-lexer";
 import { dirname, join, relative } from "pathe";
 import { z } from "zod";
 
@@ -65,32 +66,76 @@ export const packageName = (specifier: string): string | null => {
 };
 
 /**
- * Static specifiers: a side-effect `import "x"` or an `import`/`export … from
- * "x"` clause. Only `import` takes the bare-string form — `export "x"` is not
- * syntax, so a runtime message quoting `export 'ALL'` must not match. The
- * specifier quote must not be escaped either: a backslash-quoted `from \"zod\"`
- * is a code sample serialized into a string (the MCP snapshot carries page
- * Markdown), not module syntax.
+ * Fallback static specifiers for a module the lexer rejects: a side-effect
+ * `import "x"` or an `import`/`export … from "x"` clause. Only `import` takes
+ * the bare-string form — `export "x"` is not syntax, so a runtime message
+ * quoting `export 'ALL'` must not match.
  */
 const STATIC_IMPORT =
-  /(?:^|[;\s}])(?:import\s*(?<!\\)["'](?<bare>[^"'\n]+)["']|(?:import|export)\s*[\w$*{},\s]*?\s*from\s*(?<!\\)["'](?<from>[^"'\n]+)["'])/gu;
+  /(?:^|[;\s}])(?:import\s*["'](?<bare>[^"'\n]+)["']|(?:import|export)\s*[\w$*{},\s]*?\s*from\s*["'](?<from>[^"'\n]+)["'])/gu;
 
-/** Dynamic `import("…")` specifiers, same escaped-quote rule. */
-const DYNAMIC_IMPORT =
-  /\bimport\(\s*(?<!\\)["'](?<dynamic>[^"'\n]+)["']\s*\)/gu;
+/** Fallback dynamic `import("…")` specifiers. */
+const DYNAMIC_IMPORT = /\bimport\(\s*["'](?<dynamic>[^"'\n]+)["']\s*\)/gu;
 
-/** Every bare package name a module's source imports. */
-export const importedPackages = (source: string): string[] => {
-  const names = new Set<string>();
+/**
+ * Textual best effort for a module `es-module-lexer` cannot parse: every
+ * quoted specifier in import position, string contents included.
+ */
+const scannedSpecifiers = (source: string): string[] => {
+  const specifiers: string[] = [];
   for (const pattern of [STATIC_IMPORT, DYNAMIC_IMPORT]) {
     for (const match of source.matchAll(pattern)) {
       const groups = match.groups ?? {};
-      const name = packageName(
-        groups.bare ?? groups.from ?? groups.dynamic ?? ""
-      );
-      if (name) {
-        names.add(name);
-      }
+      specifiers.push(groups.bare ?? groups.from ?? groups.dynamic ?? "");
+    }
+  }
+  return specifiers;
+};
+
+/**
+ * Every specifier a module's syntax imports, read with `es-module-lexer` so
+ * text inside string literals never counts. That matters for Blume's data
+ * chunks: the MCP snapshot is `JSON.parse("…")` over every page's Markdown,
+ * and a code sample there reading `import { config } from 'dotenv'` is prose
+ * to a bundle audit, not a module the function needs. `import.meta` carries no
+ * specifier and a template-literal `import(\`pkg/${x}\`)` is a glob the
+ * bundler already resolved, so neither names a package.
+ */
+const lexedSpecifiers = (source: string, name: string): string[] => {
+  const [imports] = parse(source, name);
+  const specifiers: string[] = [];
+  for (const entry of imports) {
+    if (entry.type === "dynamic" && entry.glob) {
+      continue;
+    }
+    if (entry.specifier) {
+      specifiers.push(entry.specifier);
+    }
+  }
+  return specifiers;
+};
+
+/**
+ * Every bare package name a module's source imports. A module the lexer
+ * rejects (an unterminated string, an invalid escape in a specifier) falls
+ * back to the textual scan rather than going unaudited.
+ */
+export const importedPackages = async (
+  source: string,
+  name = "module"
+): Promise<string[]> => {
+  await init();
+  let specifiers: string[];
+  try {
+    specifiers = lexedSpecifiers(source, name);
+  } catch {
+    specifiers = scannedSpecifiers(source);
+  }
+  const names = new Set<string>();
+  for (const specifier of specifiers) {
+    const packageId = packageName(specifier);
+    if (packageId) {
+      names.add(packageId);
     }
   }
   return [...names];
@@ -164,7 +209,8 @@ export const auditFunctionBundle = async (
   for (const file of await listModules(serverDir)) {
     // oxlint-disable-next-line no-await-in-loop -- sequential read keeps the importer lists ordered
     const source = await readFile(file, "utf-8");
-    for (const name of importedPackages(source)) {
+    // oxlint-disable-next-line no-await-in-loop -- the lexer runs per file, in the same order
+    for (const name of await importedPackages(source, file)) {
       if (resolvable(name, dirname(file), funcDir)) {
         continue;
       }

package/src/deploy/sitemap.ts

@@ -36,6 +36,12 @@ export interface SitemapFile {
   xml: string;
 }
 
+/** The build log line for an emitted sitemap set: one file, or an index. */
+export const describeSitemapFiles = (files: readonly SitemapFile[]): string =>
+  files.length === 1
+    ? "Generated sitemap.xml"
+    : `Generated sitemap.xml (index of ${files.length - 1} sitemap files)`;
+
 /**
  * The sitemaps.org cap on `<url>` entries in a single file. Beyond it,
  * `sitemap.xml` becomes a sitemap index pointing at numbered chunk files —

package/src/deploy/vercel-negotiation.ts

@@ -235,21 +235,6 @@ export const buildNegotiationRoutes = (
 /** The `src` of the injected homepage `Link` header route. */
 const HOME_SRC = "^/$";
 
-/**
- * Permanent redirect from any trailing-slash URL to its slashless twin, so
- * `/docs/` and `/docs` don't serve as duplicate URLs (canonicals, sitemap, and
- * hreflang all use the slashless form; the root `/` is untouched — `.+`
- * requires a non-empty path). Spliced into the main phase before `handle:
- * "filesystem"`, after the Markdown rewrites, so an agent's `Accept:
- * text/markdown` request on a slashed URL still rewrites without the extra
- * hop. Vercel carries the query string over to the `Location` target itself.
- */
-export const TRAILING_SLASH_REDIRECT: VercelRoute = {
-  headers: { Location: "/$1" },
-  src: "^/(.+)/$",
-  status: 308,
-};
-
 /**
  * Whether a route is one this module previously injected, so re-injection
  * replaces rather than duplicates. Rewrites are identified by their `accept`
@@ -273,9 +258,7 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
   (route.continue === true &&
     isString(route.headers?.link) &&
     route.src === HOME_SRC &&
-    Object.keys(route).length === 3) ||
-  (route.status === TRAILING_SLASH_REDIRECT.status &&
-    route.src === TRAILING_SLASH_REDIRECT.src);
+    Object.keys(route).length === 3);
 
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
@@ -285,9 +268,11 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * rides on the prerendered homepage response. `contentTypeOverrides` maps static-dir
  * relative paths to media types via the Build Output `overrides` field — the
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
- * signature directory). The trailing-slash 308 redirect is always spliced in
- * alongside, so slashed duplicates of every page collapse onto the canonical
- * slashless URL. For each 404 twin the build emitted (`notFound.markdown` for
+ * signature directory). The trailing-slash redirect that collapses `/docs/`
+ * onto `/docs` is not spliced here: the generated config sets Astro's
+ * `trailingSlash: "never"`, which the adapter turns into the platform's own
+ * 308 route ahead of everything below (so a slashed Markdown request takes
+ * that hop first, then negotiates). For each 404 twin the build emitted (`notFound.markdown` for
  * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
@@ -342,15 +327,8 @@ export const injectNegotiationRoutes = (
   }
   // Headers first: `continue` routes accumulate, so a request the rewrite
   // route then terminates (Markdown negotiation on the homepage) still carries
-  // the Link header. The trailing-slash redirect goes last so a slashed URL's
-  // Markdown negotiation still rewrites directly instead of bouncing.
-  routes.splice(
-    filesystemIndex,
-    0,
-    ...headerRoutes,
-    ...rewriteRoutes,
-    TRAILING_SLASH_REDIRECT
-  );
+  // the Link header.
+  routes.splice(filesystemIndex, 0, ...headerRoutes, ...rewriteRoutes);
   const notFoundRoutes = [
     ...(notFound.markdown ? NOT_FOUND_MARKDOWN_ROUTES : []),
     ...(notFound.json ? NOT_FOUND_JSON_ROUTES : []),

package/src/markdown/language-icon.ts

@@ -49,9 +49,10 @@ import {
   siYaml,
 } from "simple-icons";
 
-/** The slice of a `simple-icons` icon Blume reads (the SVG path data). */
+/** The slice of a `simple-icons` icon Blume reads: its slug and path data. */
 interface SimpleIcon {
   path: string;
+  slug: string;
 }
 
 /** Fence language (and common aliases) → icon. Unmapped languages get none. */
@@ -146,23 +147,6 @@ export interface LanguageIconTransformer {
   pre: (this: IconContext, node: IconPreNode) => void;
 }
 
-/** Build an inline SVG hast node from a simple-icons path. */
-const iconNode = (path: string): HastNode => ({
-  children: [
-    { children: [], properties: { d: path }, tagName: "path", type: "element" },
-  ],
-  properties: {
-    ariaHidden: "true",
-    className: ["blume-lang-icon"],
-    fill: "currentColor",
-    height: 14,
-    viewBox: "0 0 24 24",
-    width: 14,
-  },
-  tagName: "svg",
-  type: "element",
-});
-
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export const languageIconTransformer = (): LanguageIconTransformer => ({
   name: "blume:language-icon",
@@ -171,7 +155,67 @@ export const languageIconTransformer = (): LanguageIconTransformer => ({
     if (!icon) {
       return;
     }
-    node.children.unshift(iconNode(icon.path));
-    node.properties.dataIcon = "";
+    // The icon itself is CSS: the theme paints `pre[data-icon="<slug>"]::after`
+    // with the brand path as a mask (see `languageIconCss`), so a block
+    // carries a short attribute instead of ~1 kB of SVG — on a reference page
+    // with twenty TypeScript blocks, the difference is most of the page.
+    node.properties.dataIcon = icon.slug;
   },
 });
+
+/** The icon slug for a fence language, or null for an unmapped language. */
+export const languageIconSlug = (language: string): string | null =>
+  LANGUAGE_ICONS[language.toLowerCase()]?.slug ?? null;
+
+// Fence openers (```ts, ~~~tsx) and the `lang`/`language` props of code
+// components (<CodeBlock lang="ts">), which highlight through the same
+// transformer. Word characters plus the few punctuation marks languages use.
+const FENCE_LANGUAGE = /^[ \t]*(?:`{3,}|~{3,})[ \t]*(?<lang>[\w+#.-]+)/gmu;
+const PROP_LANGUAGE = /\blang(?:uage)?=["'](?<lang>[\w+#.-]+)["']/gu;
+
+/**
+ * The icon slugs a site's Markdown uses, sorted and deduped, so the theme
+ * carries a mask rule for each of them and none for the other thirty.
+ */
+export const languageIconSlugsIn = (markdown: string): string[] => {
+  const slugs = new Set<string>();
+  for (const pattern of [FENCE_LANGUAGE, PROP_LANGUAGE]) {
+    for (const match of markdown.matchAll(pattern)) {
+      const slug = languageIconSlug(match.groups?.lang ?? "");
+      if (slug) {
+        slugs.add(slug);
+      }
+    }
+  }
+  return [...slugs].toSorted();
+};
+
+const iconBySlug = (slug: string): SimpleIcon | undefined =>
+  Object.values(LANGUAGE_ICONS).find((icon) => icon.slug === slug);
+
+/** A simple-icons path as a `mask-image` data URI (24×24 viewBox). */
+const maskUri = (path: string): string =>
+  `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="${path}"/></svg>`)}")`;
+
+/**
+ * The per-language rules that paint a code block's icon: each gives the
+ * block's `::after` (positioned by the theme) the brand path as a mask over
+ * the muted foreground. Only the listed slugs get a rule, so an unmapped or
+ * unused language paints nothing rather than a blank square.
+ */
+export const languageIconCss = (slugs: string[]): string =>
+  slugs
+    .map((slug) => {
+      const icon = iconBySlug(slug);
+      if (!icon) {
+        return "";
+      }
+      const mask = maskUri(icon.path);
+      return `.prose > :where(pre[data-language][data-icon="${slug}"])::after {
+  background-color: var(--blume-muted-foreground);
+  -webkit-mask-image: ${mask};
+  mask-image: ${mask};
+}`;
+    })
+    .filter((rule) => rule !== "")
+    .join("\n");

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

@@ -1,12 +1,14 @@
 import { readFile } from "node:fs/promises";
 
-import { imageSize } from "image-size";
 import { render } from "takumi-js";
 import type { RenderOptions } from "takumi-js";
 import { container, googleFonts, image, text } from "takumi-js/helpers";
 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
@@ -234,19 +232,13 @@ const MARK_HEIGHT = 32;
 const MARK_MAX_WIDTH = 240;
 /**
  * The SVG's aspect ratio (w/h), or null when no usable dimensions exist (the
- * caller falls back to a square mark). image-size (already a dependency)
- * reads explicit width/height and falls back to the viewBox, tolerating the
- * quote/whitespace/attribute spellings the old regex silently missed —
- * `viewBox = "…"`, newline-separated values — which shipped visibly-squashed
- * marks instead of failing loudly.
+ * caller falls back to a square mark). The shared root-tag parser reads
+ * explicit width/height and falls back to the viewBox, so the card and the
+ * header measure one logo the same way.
  */
 const logoAspect = (svg: string): number | null => {
-  try {
-    const { height, width } = imageSize(Buffer.from(svg));
-    return width && height ? width / height : null;
-  } catch {
-    return null;
-  }
+  const size = svgDimensions(svg);
+  return size ? size.width / size.height : null;
 };
 
 // Render the configured logo as the brand mark. A `currentColor` logo carries
@@ -424,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,