When Only the Japanese Turns to Tofu in Your Share Image — Fixing next/og CJK Fonts with Antigravity

Fetch only the glyphs you need — the css2 text= subset

Google Fonts' css2 endpoint has a wonderful parameter, text=. It returns CSS for a subset containing only the characters you specify, which slashes the download dramatically.

There is one rarely-mentioned hinge here. css2 changes the font format it returns based on the requesting User-Agent. A modern browser UA gets woff2; anything else (a server-side fetch, whose UA isn't treated as woff2-capable) gets ttf. An edge-runtime fetch doesn't claim a browser UA, so if you do nothing, ttf comes back — exactly the form Satori can take. Conversely, if you "helpfully" add a browser-like UA, you get woff2 and you're back to tofu.

The helper that resolves the subset looks like this.

// Fetch a TrueType subset containing only the characters we draw.
async function loadGoogleFont(
  family: string,
  weight: number,
  text: string,
): Promise<ArrayBuffer> {
  // De-duplicate characters to keep text= short (css2 has a length limit).
  const glyphs = Array.from(new Set(Array.from(text))).join("");
 
  const cssUrl =
    `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}` +
    `:wght@${weight}&text=${encodeURIComponent(glyphs)}`;
 
  // ⚠️ Deliberately do NOT send a browser-like User-Agent.
  //    Omitting it makes css2 return truetype instead of woff2.
  const css = await fetch(cssUrl).then((res) => res.text());
 
  const src = css.match(
    /src:\s*url\((.+?)\)\s*format\('(?:opentype|truetype)'\)/,
  );
  if (!src) {
    throw new Error("Could not resolve a TrueType subset URL");
  }
  return fetch(src[1]).then((res) => res.arrayBuffer());
}

What you pass to text= is every character you actually render. I tripped on this once. I subsetted only the title's characters and forgot the fixed label "Antigravity Lab," the domain string, and the ellipsis (…) my overflow logic appends. The title rendered, but the fixed labels turned to tofu instead. Keep the subset equal to "the set of characters that appear on screen," and you stay safe.

Pass the font in a form Satori can read

Once you have the subset ttf, the rest is just handing it to ImageResponse via fonts. Here's the full opengraph-image.tsx.

import { ImageResponse } from "next/og";
 
export const runtime = "edge";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";
 
const BRAND = "Antigravity Lab";
const DOMAIN = "antigravitylab.net";
 
export default async function Image({
  params,
}: {
  params: { slug: string };
}) {
  const rawTitle = await getArticleTitle(params.slug); // from article meta
  const title = clampByWidth(rawTitle, 44); // overflow guard (below)
 
  // Bundle every character we draw to pull one subset.
  const glyphSource = title + BRAND + DOMAIN + "…";
  const fontData = await loadGoogleFont("Noto Sans JP", 700, glyphSource);
 
  return new ImageResponse(
    (
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          justifyContent: "space-between",
          width: "100%",
          height: "100%",
          padding: 80,
          background: "#0b1020",
          color: "#ffffff",
          fontFamily: "Noto Sans JP",
        }}
      >
        <div style={{ display: "flex", fontSize: 30, opacity: 0.7 }}>
          {BRAND}
        </div>
        <div
          style={{
            display: "flex",
            fontSize: 64,
            fontWeight: 700,
            lineHeight: 1.25,
          }}
        >
          {title}
        </div>
        <div style={{ display: "flex", fontSize: 26, opacity: 0.6 }}>
          {DOMAIN}
        </div>
      </div>
    ),
    {
      ...size,
      fonts: [
        { name: "Noto Sans JP", data: fontData, weight: 700, style: "normal" },
      ],
    },
  );
}

A small detail: every text-bearing element carries an explicit display: "flex". Satori treats a <div> as flex by default, but when a node has multiple children and you omit display, you can get warnings or broken layout, so being explicit prevents accidents. Your full-stack CSS intuition does not transfer cleanly — that's the baseline for working with Satori.

Kill overflow outside of Satori

The other practical problem in OG images is long titles overflowing. Satori does not fully support CSS like text-overflow: ellipsis, and -webkit-line-clamp may not behave as expected. Early on I decided it was sturdier to cut the string before drawing, without relying on layout.

For titles that mix Japanese and English, a naive function that crudely weights full-width versus half-width characters is plenty for production.

// Weight CJK as double-width and cut by visual width — a naive approximation.
function clampByWidth(text: string, maxUnits: number): string {
  let width = 0;
  let out = "";
  for (const ch of Array.from(text)) {
    width += /[\x20-\x7e]/.test(ch) ? 1 : 2; // half-width = 1, else 2
    if (width > maxUnits) return out.trimEnd() + "…";
    out += ch;
  }
  return out;
}

It is not a perfect line-breaking algorithm. But an OG image is consumed in an instant; "not looking broken" matters far more than pixel-perfect placement. With that compromise, I unified the OG routes across all four of my sites onto the same implementation.

Measured: what subsetting actually changed

"Subsetting helps" means little without orders of magnitude. Here are rough numbers from my own Antigravity Lab route, drawing one image for a typical Japanese title (~30 characters). These are my own measurements and will vary by environment and title.

Once you're down to double-digit KB, running the css2 lookup and font fetch on every request is light enough — but two external fetches per cold render is still waste. I memoize the subset in a module-scoped Map, keyed by the drawn characters.

const fontCache = new Map<string, Promise<ArrayBuffer>>();
 
function cachedFont(family: string, weight: number, text: string) {
  const key = `${family}:${weight}:${Array.from(new Set(text)).sort().join("")}`;
  if (!fontCache.has(key)) {
    fontCache.set(key, loadGoogleFont(family, weight, text));
  }
  return fontCache.get(key)!;
}

On top of that, an OG route changes slowly relative to article churn, so leaning on CDN caching (the opengraph-image response cache, or site-wide invalidation via DEPLOY_VERSION) cuts the external lookups even further.

Make the agent fix this correctly

That's the implementation, but the real subject is how to ask Antigravity to fix it fastest the next time it happens. What I learned was to hand the agent constraints and a means of verification together.

The ask that failed was, "The Japanese in the OG image isn't showing — fix it." With no error to anchor on, the agent guesses at causes, adds a font-family, tries another woff2, and piles on off-target edits.

The ask that worked led with three things. First, evidence of the failure: I actually showed it the tofu PNG and spelled out the symptom — "English renders, only Japanese is □." Second, the constraint behind the failure: I gave it two facts as premises rather than letting it guess — "Satori cannot read woff2" and "the subset must include every drawn character." Third, a machine check for pass/fail: save the generated PNG and verify the expected characters render, run as part of the fix.

Even a crude check pays off. Just writing the generated image to a file and having the agent confirm the size is non-zero and the bytes differ from the previous tofu version is enough to prevent "I think it's fixed." In the end, I look at it once myself and confirm the boxes are gone. An agent can draw, but the final judgment of "does this look right" is a boundary a human should keep — this incident reminded me of that again.

What to delegate and what to verify yourself. Domains like OG images — where breakage never throws — are exactly where that line earns its keep. The next time I stand up a new site, I plan to bring loadGoogleFont, clampByWidth, and the "evidence, constraint, verification" way of asking as a template from day one. Thank you for reading; I hope it shortens the detour for anyone fighting the same tofu.