fix(takumi): restore non-latin glyph support regressed in v6.2.0 (#587)

Author: harlan-zw

src/module.ts

@@ -1329,7 +1329,7 @@ export const resolve = (import.meta.dev || import.meta.prerender) ? devResolve :
       }
       // Dev mode: convertWoff2ToTtf() may not have run via vite:compiled
       // because OG components are lazily compiled. Run it now on first resolve.
-      if (!fontProcessingDone && convertedWoff2Files.size === 0 && hasSatoriRenderer() && hasNuxtFonts) {
+      if (!fontProcessingDone && convertedWoff2Files.size === 0 && (hasSatoriRenderer() || hasTakumiRenderer()) && hasNuxtFonts) {
         if (pendingFontRequirements.length > 0)
           await Promise.all(pendingFontRequirements)
         await convertWoff2ToTtf({
@@ -1418,7 +1418,7 @@ export const rootDir = ${JSON.stringify(nuxt.options.rootDir)}`
       nuxt.hook('vite:compiled', async () => {
         // Always persist font URL mapping (needed by all renderers for prerender/dev font resolution)
         persistFontUrlMapping({ fontContext, buildDir: nuxt.options.buildDir, logger })
-        if (fontProcessingDone || !hasSatoriRenderer())
+        if (fontProcessingDone || (!hasSatoriRenderer() && !hasTakumiRenderer()))
           return
         // Skip until font requirements are populated (OG components are server-side,
         // so onFontRequirements runs during the server Vite build, not the client build)

src/runtime/server/og-image/font-source.ts

@@ -0,0 +1,38 @@
+export type FontFormat = 'ttf' | 'otf' | 'woff' | 'woff2'
+
+export function fontFormat(src: string): FontFormat {
+  if (src.endsWith('.woff2'))
+    return 'woff2'
+  if (src.endsWith('.woff'))
+    return 'woff'
+  if (src.endsWith('.otf'))
+    return 'otf'
+  return 'ttf'
+}
+
+/**
+ * Pick the src to actually load for a parsed font entry.
+ *
+ * - When `preferStatic` is set (takumi), prefers the full static satoriSrc over a subset WOFF2
+ *   primary src. @nuxt/fonts CSS often ships only the latin subset for a family, so using the
+ *   subset would hide non-latin glyphs (devanagari, CJK) the static file covers.
+ * - Otherwise, uses the primary src when the renderer can parse its format, falling back to
+ *   satoriSrc as a static alternative when the primary format is unsupported (satori + WOFF2).
+ *
+ * Returns null when no src on this entry can be parsed by the renderer.
+ */
+export function selectFontSource(
+  f: { src: string, satoriSrc?: string },
+  supportedFormats: Set<FontFormat>,
+  preferStatic: boolean,
+): { src: string, isStaticFallback: boolean } | null {
+  const primarySupported = supportedFormats.has(fontFormat(f.src))
+  const satoriSupported = !!(f.satoriSrc && supportedFormats.has(fontFormat(f.satoriSrc)))
+  if (preferStatic && satoriSupported && f.satoriSrc !== f.src)
+    return { src: f.satoriSrc!, isStaticFallback: true }
+  if (primarySupported)
+    return { src: f.src, isStaticFallback: false }
+  if (satoriSupported)
+    return { src: f.satoriSrc!, isStaticFallback: true }
+  return null
+}

src/runtime/server/og-image/fonts.ts

@@ -1,29 +1,19 @@
 import type { H3Event } from 'h3'
 import type { FontConfig, OgImageRenderEventContext, RuntimeFontConfig } from '../../types'
+import type { FontFormat } from './font-source'
 import { resolve } from '#og-image-virtual/public-assets.mjs'
 import { fontRequirements, getComponentFontMap } from '#og-image/font-requirements'
 import resolvedFonts from '#og-image/fonts'
 import availableFonts from '#og-image/fonts-available'
 import { logger } from '../../logger'
 import { fontArrayCache, fontCache } from './cache/lru'
+import { fontFormat, selectFontSource } from './font-source'
 import { renameSubsetFonts } from './font-subsets'
 import { codepointsIntersectRanges, parseUnicodeRange } from './unicode-range'
 
 export { buildSubsetFamilyChain, renameSubsetFonts, resolveSubsetChain } from './font-subsets'
 export { codepointsIntersectRanges, extractCodepoints, parseUnicodeRange } from './unicode-range'
 
-type FontFormat = 'ttf' | 'otf' | 'woff' | 'woff2'
-
-function fontFormat(src: string): FontFormat {
-  if (src.endsWith('.woff2'))
-    return 'woff2'
-  if (src.endsWith('.woff'))
-    return 'woff'
-  if (src.endsWith('.otf'))
-    return 'otf'
-  return 'ttf'
-}
-
 export interface LoadFontsOptions {
   /**
    * Font formats the renderer can parse.
@@ -37,6 +27,13 @@ export interface LoadFontsOptions {
   fontFamilyOverride?: string
   /** Codepoints present in the template — fonts whose unicodeRange doesn't intersect are skipped */
   codepoints?: Set<number>
+  /**
+   * Prefer the static satoriSrc (full TTF/WOFF from fontless) over the primary src
+   * (subset WOFF2 from @nuxt/fonts) when both are usable. Takumi uses this so non-Latin
+   * glyphs (devanagari, CJK, etc.) render — @nuxt/fonts CSS often only ships latin
+   * subsets for a family, but the fontless static file contains the full glyph set.
+   */
+  preferStatic?: boolean
 }
 
 async function loadFont(event: H3Event, font: FontConfig, src: string): Promise<BufferSource | null> {
@@ -151,47 +148,52 @@ export async function loadAllFonts(event: H3Event, options: LoadFontsOptions): P
     }
   }
 
-  // Filter out font subsets whose unicodeRange doesn't intersect the template's codepoints
-  if (options.codepoints && options.codepoints.size > 0) {
-    for (let i = fonts.length - 1; i >= 0; i--) {
-      const f = fonts[i]!
-      if (!f.unicodeRange)
-        continue
-      const ranges = parseUnicodeRange(f.unicodeRange)
-      if (!ranges)
-        continue
-      if (!codepointsIntersectRanges(options.codepoints, ranges))
-        fonts.splice(i, 1)
-    }
+  // Resolve the effective src per font up-front: primary src when supported, else satoriSrc.
+  // Takumi opts into preferStatic so the full static TTF is used instead of the subset WOFF2 —
+  // @nuxt/fonts CSS may only include latin subsets, and using the subset would hide non-latin
+  // glyphs (devanagari, CJK) that the full static file covers.
+  const resolved: Array<{ font: FontConfig, src: string, isStaticFallback: boolean }> = []
+  for (const f of fonts) {
+    const selection = selectFontSource(f, options.supportedFormats, options.preferStatic ?? false)
+    if (selection)
+      resolved.push({ font: f, ...selection })
   }
 
-  const results = await Promise.all(
-    fonts.map(async (f) => {
-      let src = f.src
-      const srcFormat = fontFormat(f.src)
-
-      // If the primary src format isn't supported, try satoriSrc as alternative
-      if (!options.supportedFormats.has(srcFormat)) {
-        if (f.satoriSrc && options.supportedFormats.has(fontFormat(f.satoriSrc))) {
-          src = f.satoriSrc
-        }
-        else {
-          // No usable format available, skip this font
-          return null
-        }
-      }
+  // Filter out font subsets whose unicodeRange doesn't intersect the template's codepoints.
+  // Skip entries using the full static fallback — its glyph coverage isn't described by the
+  // parent @font-face unicodeRange (which only applied to the WOFF2 subset).
+  const filtered = options.codepoints && options.codepoints.size > 0
+    ? resolved.filter(({ font: f, isStaticFallback }) => {
+        if (isStaticFallback || !f.unicodeRange)
+          return true
+        const ranges = parseUnicodeRange(f.unicodeRange)
+        if (!ranges)
+          return true
+        return codepointsIntersectRanges(options.codepoints!, ranges)
+      })
+    : resolved
 
+  const results = await Promise.all(
+    filtered.map(async ({ font: f, src: initialSrc, isStaticFallback }) => {
+      let src = initialSrc
       let data = await loadFont(event, f, src)
-      // When satoriSrc fails to load (e.g. 404), try original src if its format is supported
-      if (!data && src !== f.src && options.supportedFormats.has(srcFormat)) {
+      // Fall back to primary src if the static alternative fails to load (e.g. 404)
+      if (!data && src !== f.src && options.supportedFormats.has(fontFormat(f.src))) {
         data = await loadFont(event, f, f.src)
-        if (data)
+        if (data) {
           src = f.src
+          isStaticFallback = false
+        }
       }
       if (!data)
         return null
+      // Reflect the src actually loaded so downstream dedupe (takumi) keys on the real binary.
+      // Drop unicodeRange when using the full static fallback — the subset range doesn't apply
+      // to the static TTF, and takumi's subset-chain logic would otherwise split the family.
       return {
         ...f,
+        src,
+        ...(isStaticFallback ? { unicodeRange: undefined } : {}),
         cacheKey: `${f.family}-${f.weight}-${f.style}-${src}`,
         data,
       } satisfies RuntimeFontConfig

src/runtime/server/og-image/takumi/renderer.ts

@@ -172,7 +172,7 @@ async function createImage(event: OgImageRenderEventContext, format: 'png' | 'jp
   const { fontFamilyOverride, defaultFont } = getDefaultFontFamily(options)
   const nodes = await createTakumiNodes(event)
   const codepoints = extractCodepoints(nodes)
-  const fonts = await timings.measure('font-load', () => loadFontsForRenderer(event, { supportedFormats: new Set(['ttf', 'woff2'] as const), component: options.component, fontFamilyOverride: fontFamilyOverride || defaultFont, codepoints }))
+  const fonts = await timings.measure('font-load', () => loadFontsForRenderer(event, { supportedFormats: new Set(['ttf', 'woff2'] as const), preferStatic: true, component: options.component, fontFamilyOverride: fontFamilyOverride || defaultFont, codepoints }))
 
   await event._nitro.hooks.callHook('nuxt-og-image:takumi:nodes' as any, nodes, event)
 
@@ -272,7 +272,7 @@ const TakumiRenderer: Renderer = {
   async debug(e) {
     const [vnodes, fonts] = await Promise.all([
       createTakumiNodes(e),
-      loadFontsForRenderer(e, { supportedFormats: new Set(['ttf', 'woff2'] as const), component: e.options.component }),
+      loadFontsForRenderer(e, { supportedFormats: new Set(['ttf', 'woff2'] as const), preferStatic: true, component: e.options.component }),
     ])
     return {
       vnodes,

test/e2e/__image_snapshots__/takumi-only-devanagari.png

@@ -0,0 +1,50 @@
+import { createResolver } from '@nuxt/kit'
+import { $fetch, setup } from '@nuxt/test-utils/e2e'
+import { describe, expect, it } from 'vitest'
+import { fetchOgImage, setupImageSnapshots, SNAPSHOT_LOOSE } from '../utils'
+
+const { resolve } = createResolver(import.meta.url)
+
+// Regression: https://github.com/nuxt-modules/og-image/issues/586
+// Takumi-only setups (no satori component in the app) skipped fontless static-font
+// downloads after v6.2.0, leaving @nuxt/fonts' latin-subset WOFF2 as the only source
+// and causing non-latin glyphs (devanagari, CJK, etc.) to render as tofu.
+let hasTakumi = false
+try {
+  await import('@takumi-rs/core')
+  hasTakumi = true
+}
+catch {
+  hasTakumi = false
+}
+
+await setup({
+  rootDir: resolve('../fixtures/takumi-only-fonts'),
+  server: true,
+  build: true,
+})
+
+setupImageSnapshots(SNAPSHOT_LOOSE)
+
+describe('takumi-only fonts', () => {
+  it.runIf(hasTakumi)('downloads static fallback fonts for takumi-only apps', async () => {
+    // Direct check on the build output: pre-v6.2.0 emitted these for takumi too; v6.2.0
+    // narrowed the gate so a takumi-only app got no static TTFs at all and non-latin
+    // scripts had nothing to fall back to.
+    const [devanagari, poppins] = await Promise.all([
+      $fetch('/_og-static-fonts/Noto_Sans_Devanagari-400-normal.ttf', { responseType: 'arrayBuffer' }) as Promise<ArrayBuffer>,
+      $fetch('/_og-static-fonts/Poppins-400-normal.ttf', { responseType: 'arrayBuffer' }) as Promise<ArrayBuffer>,
+    ])
+    expect(devanagari.byteLength).toBeGreaterThan(10_000)
+    expect(poppins.byteLength).toBeGreaterThan(10_000)
+  })
+
+  it.runIf(hasTakumi)('renders devanagari glyphs through takumi', async () => {
+    const image = await fetchOgImage('/')
+    expect(image).toMatchImageSnapshot({ customSnapshotIdentifier: 'takumi-only-devanagari' })
+  }, 60000)
+
+  it.runIf(!hasTakumi)('skips when @takumi-rs/core not installed', () => {
+    expect(true).toBe(true)
+  })
+})

test/e2e/takumi-only-fonts.test.ts

@@ -0,0 +1,3 @@
+<template>
+  <NuxtPage />
+</template>

test/fixtures/takumi-only-fonts/app.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  title?: string
+  description?: string
+}>(), {
+  title: 'चरन् वै मधु विन्दति',
+  description: 'Takumi-only devanagari rendering',
+})
+</script>
+
+<template>
+  <div class="h-full w-full flex flex-col justify-center items-center bg-white">
+    <h1 class="text-6xl text-rose-600 font-bold" style="font-family: 'Noto Sans Devanagari', sans-serif;">
+      {{ title }}
+    </h1>
+    <p class="text-2xl text-gray-500 mt-4" style="font-family: 'Poppins', sans-serif;">
+      {{ description }}
+    </p>
+  </div>
+</template>

test/fixtures/takumi-only-fonts/components/OgImage/DevanagariCard.takumi.vue

@@ -0,0 +1,37 @@
+import { defineNuxtConfig } from 'nuxt/config'
+import NuxtOgImage from '../../../src/module'
+
+// Regression: https://github.com/nuxt-modules/og-image/issues/586
+// Takumi-only fixture (no satori components) exercising a non-Latin family
+// (Noto Sans Devanagari) via @nuxt/fonts. Prior to the v6.2.0 regression the
+// build would download static TTFs for takumi too; v6.2.0 narrowed the gate to
+// satori only, leaving takumi with latin-subset WOFF2s that can't render devanagari.
+// Intentionally NOT extending ../.base — that fixture ships OgImageCommunity satori+takumi
+// templates which would leak satori into detectedRenderers and trigger the satori-gated
+// convertWoff2ToTtf path, hiding the regression we want to exercise here.
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/fonts',
+    NuxtOgImage,
+  ],
+
+  fonts: {
+    families: [
+      { name: 'Poppins', weights: [400, 700], global: true },
+      { name: 'Noto Sans Devanagari', weights: [400, 700], global: true },
+    ],
+  },
+
+  ogImage: {
+    debug: true,
+    // Exclude the bundled OgImageCommunity templates so only takumi components are present —
+    // otherwise community satori templates trick the module into thinking satori is in use.
+    componentDirs: ['OgImage'],
+  },
+
+  site: {
+    url: 'https://example.com',
+  },
+
+  compatibilityDate: '2025-01-13',
+})

test/fixtures/takumi-only-fonts/nuxt.config.ts

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import { defineOgImage } from '#imports'
+
+defineOgImage('DevanagariCard.takumi', {
+  title: 'चरन् वै मधु विन्दति',
+  description: 'Takumi-only devanagari rendering',
+})
+</script>
+
+<template>
+  <div class="p-4">
+    <h1>Takumi-only devanagari test</h1>
+  </div>
+</template>