fix: Better font caching (#788)

Author: shuding

src/font.ts

@@ -429,6 +429,10 @@ const cachedParsedFont = new WeakMap<
 export default class FontLoader {
   defaultFont: opentype.Font
   fonts = new Map<string, [opentype.Font, Weight?, FontStyle?][]>()
+  // Shaping results are cached on the loader (which persists across renders
+  // for the same font configuration) so repeated renders don't re-shape
+  // identical text runs with HarfBuzz.
+  private shapedRunCache = new Map<string, ShapedRun[]>()
   constructor(fontOptions: FontOptions[]) {
     this.addFonts(fontOptions)
   }
@@ -472,6 +476,11 @@ export default class FontLoader {
   }
 
   public addFonts(fontOptions: FontOptions[]) {
+    // Adding fonts can change how text resolves across the font list, so
+    // previously shaped runs may no longer be correct.
+    if (fontOptions.length && this.fonts.size) {
+      this.shapedRunCache.clear()
+    }
     for (const fontOption of fontOptions) {
       const { name, data, lang } = fontOption
       if (lang && !isValidLocale(lang)) {
@@ -701,11 +710,18 @@ export default class FontLoader {
       return resolveFont(s, false)
     }
 
-    // Text is shaped during both measurement and SVG generation. Keep the
-    // result on this render-local engine so the second pass can reuse it.
-    const shapedRunCache = new Map<string, ShapedRun[]>()
+    // Text is shaped during both measurement and SVG generation, and the same
+    // text is typically shaped again on subsequent renders. Cache the result
+    // on the loader (keyed by the resolved font configuration) so both the
+    // second pass of this render and future renders can reuse it.
+    // Shaped glyphs are in font units, so the key only needs the inputs that
+    // affect font resolution and shaping — not the font size.
+    const shapedRunCache = this.shapedRunCache
+    const engineKey = `${fontFamily.join(',')}|${fontWeight}|${fontStyle}|${
+      locale || ''
+    }`
     const getShapedRuns: GetShapedRuns = (content, fontFeatureSettings) => {
-      const key = `${fontFeatureSettings || ''}\0${content}`
+      const key = `${engineKey}\0${fontFeatureSettings || ''}\0${content}`
       const cached = shapedRunCache.get(key)
 
       if (cached !== undefined) {
@@ -905,13 +921,14 @@ export default class FontLoader {
       fontFeatureSettings
     )
 
-    const fullPath = new opentype.Path()
     const boxes: GlyphBox[] = []
 
     let cursorX = left
     const cursorY = top
     let hasRenderedGlyph = false
 
+    const fullPath = new opentype.Path()
+
     // Process each font segment
     for (const [, font, glyphs] of shapedRuns) {
       const scale = fontSize / font.unitsPerEm

src/satori.ts

@@ -16,6 +16,52 @@ import { initHarfBuzz } from './harfbuzz.js'
 // We don't need to initialize the opentype instances every time.
 const fontCache = new WeakMap()
 
+// Users often build the `fonts` array inline on every render while reusing
+// the same underlying font data buffers. Identify loaders by the identity of
+// each font's data buffer plus its metadata, so an equivalent inline array
+// still hits the cached FontLoader (and its shaping caches).
+const fontDataIds = new WeakMap<Buffer | ArrayBuffer, number>()
+let nextFontDataId = 0
+const MAX_FONT_LOADERS = 8
+const fontLoaderCache = new Map<string, FontLoader>()
+
+function getFontLoaderKey(fonts: FontOptions[]): string {
+  let key = ''
+  for (const font of fonts) {
+    let id = fontDataIds.get(font.data)
+    if (id === undefined) {
+      id = ++nextFontDataId
+      fontDataIds.set(font.data, id)
+    }
+    key += `${id}:${font.name}:${font.weight ?? ''}:${font.style ?? ''}:${
+      font.lang ?? ''
+    };`
+  }
+  return key
+}
+
+function getFontLoader(fonts: FontOptions[]): FontLoader {
+  // Fast path: the exact same array instance.
+  if (fontCache.has(fonts)) {
+    return fontCache.get(fonts)
+  }
+
+  const key = getFontLoaderKey(fonts)
+  let loader = fontLoaderCache.get(key)
+
+  if (!loader) {
+    loader = new FontLoader(fonts)
+    if (fontLoaderCache.size >= MAX_FONT_LOADERS) {
+      const oldestKey = fontLoaderCache.keys().next().value
+      if (oldestKey !== undefined) fontLoaderCache.delete(oldestKey)
+    }
+    fontLoaderCache.set(key, loader)
+  }
+
+  fontCache.set(fonts, loader)
+  return loader
+}
+
 export type SatoriOptions = (
   | {
       width: number
@@ -56,12 +102,7 @@ export default async function satori(
 
   options.fonts = options.fonts || []
 
-  let font: FontLoader
-  if (fontCache.has(options.fonts)) {
-    font = fontCache.get(options.fonts)
-  } else {
-    fontCache.set(options.fonts, (font = new FontLoader(options.fonts)))
-  }
+  const font = getFontLoader(options.fonts)
 
   const definedWidth = 'width' in options ? options.width : undefined
   const definedHeight = 'height' in options ? options.height : undefined