Merge pull request #26 from wiedymi/agent/fix-cjk-fallback-rendering

wiedymi · web-flow · commit 328e295edda3 · 2026-07-16T13:28:09.000+08:00
fix(fonts): preserve visible CJK fallbacks
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,14 @@ This project follows SemVer. While restty is pre-1.0, breaking public API change
 
 ### Docs
 
+## [0.2.1] - 2026-07-16
+
+### Fixes
+
+- Kept wide CJK fallback glyphs at their natural em scale instead of enlarging them to fill two cells, and centered them across their occupied cells for consistent baseline and sizing in both WebGPU and WebGL2.
+- Skipped fallback fonts whose claimed glyph rasterizes without visible coverage, allowing later CJK fallbacks to render instead of leaving blank text with fonts such as variable PingFang.
+- Updated text-shaper to support current Noto Emoji WOFF2 fonts whose outlines use compact `255UInt16` encodings.
+
 ## [0.2.0] - 2026-07-04
 
 ### Breaking Changes
diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "restty",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Browser terminal rendering library powered by WASM, WebGPU/WebGL2, and TypeScript text shaping.",
   "keywords": [
     "ansi",
@@ -97,7 +97,7 @@
     "playground:preview": "bun run playground/server.ts"
   },
   "dependencies": {
-    "text-shaper": "0.1.23"
+    "text-shaper": "0.1.26"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.4",
diff --git a/src/fonts/manager/entries.ts b/src/fonts/manager/entries.ts
@@ -8,6 +8,7 @@ export function createFontEntry(font: Font, label: string): FontEntry {
     label,
     glyphCache: new Map(),
     boundsCache: new Map(),
+    glyphCoverageCache: new Map(),
     colorGlyphTexts: new Map(),
     glyphIds: new Set(),
     atlas: null,
@@ -24,6 +25,7 @@ export function createFontEntry(font: Font, label: string): FontEntry {
 export function resetFontEntry(entry: FontEntry): void {
   entry.glyphCache.clear();
   entry.boundsCache.clear();
+  entry.glyphCoverageCache.clear();
   entry.colorGlyphTexts.clear();
   entry.glyphIds.clear();
   entry.atlas = null;
diff --git a/src/fonts/types.ts b/src/fonts/types.ts
@@ -33,6 +33,8 @@ export type FontEntry = {
   glyphCache: Map<string, ShapedCluster>;
   /** Cache of glyph advance bounds keyed by glyph ID. */
   boundsCache: Map<number, number>;
+  /** Cache of whether a claimed glyph produces visible raster coverage. */
+  glyphCoverageCache: Map<number, boolean>;
   /** Map of glyph IDs to their original text for color emoji fallback. */
   colorGlyphTexts: Map<number, string>;
   /** Set of all glyph IDs available in this font. */
diff --git a/src/runtime/create-runtime/font-runtime/index.ts b/src/runtime/create-runtime/font-runtime/index.ts
@@ -47,6 +47,7 @@ export function createRuntimeFontRuntimeHelpers(options: CreateRuntimeFontRuntim
     UnicodeBuffer,
     shape,
     glyphBufferToShapedGlyphs,
+    rasterizeGlyph,
   });
 
   const gridHelpers = createFontRuntimeGridHelpers({
diff --git a/src/runtime/create-runtime/font-runtime/text.ts b/src/runtime/create-runtime/font-runtime/text.ts
@@ -3,10 +3,10 @@ import {
   isSymbolFont,
   isColorEmojiFont,
   isNerdSymbolFont,
-  type Font,
   type FontEntry,
 } from "../../../fonts";
 import { isCoverageIgnorableCodepoint, resolvePresentationPreference } from "../codepoint-utils";
+import { glyphHasVisibleRaster } from "../../fonts/glyph-coverage";
 import type { CreateFontRuntimeTextHelpersOptions } from "./text.types";
 
 function setBoundedMap<K, V>(map: Map<K, V>, key: K, value: V, limit: number): void {
@@ -29,6 +29,7 @@ export function createFontRuntimeTextHelpers(options: CreateFontRuntimeTextHelpe
     UnicodeBuffer,
     shape,
     glyphBufferToShapedGlyphs,
+    rasterizeGlyph,
   } = options;
 
   function shapeClusterWithFont(entry: FontEntry, text: string) {
@@ -56,9 +57,21 @@ export function createFontRuntimeTextHelpers(options: CreateFontRuntimeTextHelpe
     entry.colorGlyphTexts.set(glyphId, text);
   }
 
-  function fontHasGlyph(font: Font, ch: string): boolean {
-    const glyphId = font.glyphIdForChar(ch);
-    return glyphId !== undefined && glyphId !== null && glyphId !== 0;
+  function fontHasGlyph(entry: FontEntry, ch: string, probeCoverage: boolean): boolean {
+    const glyphId = entry.font.glyphIdForChar(ch);
+    if (glyphId === undefined || glyphId === null || glyphId === 0) return false;
+    if (!probeCoverage || isColorEmojiFont(entry)) return true;
+
+    const cached = entry.glyphCoverageCache.get(glyphId);
+    if (cached !== undefined) return cached;
+    const visible = glyphHasVisibleRaster({
+      font: entry.font,
+      glyphId,
+      sizeMode: fontState.sizeMode,
+      rasterizeGlyph,
+    });
+    entry.glyphCoverageCache.set(glyphId, visible);
+    return visible;
   }
 
   function pickFontIndexForText(text: string, expectedSpan = 1, stylePreference = "regular") {
@@ -106,7 +119,7 @@ export function createFontRuntimeTextHelpers(options: CreateFontRuntimeTextHelpe
         if (predicate && !predicate(entry)) continue;
         let ok = true;
         for (const ch of requiredChars) {
-          if (!fontHasGlyph(entry.font, ch)) {
+          if (!fontHasGlyph(entry, ch, i > 0)) {
             ok = false;
             break;
           }
diff --git a/src/runtime/create-runtime/font-runtime/text.types.ts b/src/runtime/create-runtime/font-runtime/text.types.ts
@@ -1,5 +1,10 @@
 import type { FontManagerState } from "../../../fonts";
-import type { GlyphBufferToShapedGlyphsFn, ShapeFn, UnicodeBufferCtor } from "./types";
+import type {
+  GlyphBufferToShapedGlyphsFn,
+  RasterizeGlyphFn,
+  ShapeFn,
+  UnicodeBufferCtor,
+} from "./types";
 
 export type CreateFontRuntimeTextHelpersOptions = {
   fontState: FontManagerState;
@@ -8,4 +13,5 @@ export type CreateFontRuntimeTextHelpersOptions = {
   UnicodeBuffer: UnicodeBufferCtor;
   shape: ShapeFn;
   glyphBufferToShapedGlyphs: GlyphBufferToShapedGlyphsFn;
+  rasterizeGlyph: RasterizeGlyphFn;
 };
diff --git a/src/runtime/create-runtime/render-tick-webgl-context.ts b/src/runtime/create-runtime/render-tick-webgl-context.ts
@@ -1,6 +1,7 @@
 import type { Color, WebGLState } from "../../renderer";
 import { fallbackEmScale, type Font, type FontEntry } from "../../fonts";
 import type { GlyphConstraintMeta } from "../fonts/atlas-builder";
+import { resolveWideFallbackScale } from "../fonts/fallback-layout";
 import type { GlyphQueueItem } from "./render-tick-webgpu.types";
 import type { WebGLTickContext, WebGLTickDeps } from "./render-tick-webgl.types";
 
@@ -309,10 +310,12 @@ export function buildWebGLTickContext(
     const maxSpan = fontMaxCellSpan(entry);
     if (maxSpan > 1) {
       const advanceUnits = fontAdvanceUnits(entry, shapeClusterWithFont);
-      const widthPx = advanceUnits * adjustedScale;
-      const widthAdjustRaw = widthPx > 0 ? (cellW * maxSpan) / widthPx : 1;
-      const widthAdjust = clamp(widthAdjustRaw, 0.5, 2);
-      adjustedScale *= widthAdjust;
+      adjustedScale = resolveWideFallbackScale({
+        scale: adjustedScale,
+        advanceUnits,
+        cellWidth: cellW,
+        maxSpan,
+      });
     }
     const adjustedHeightPx = fontHeightUnits(entry.font) * adjustedScale;
     if (adjustedHeightPx > lineHeight && adjustedHeightPx > 0) {
diff --git a/src/runtime/create-runtime/render-tick-webgl-glyph-pipeline.ts b/src/runtime/create-runtime/render-tick-webgl-glyph-pipeline.ts
@@ -1,5 +1,6 @@
 import type { GlyphQueueItem } from "./render-tick-webgpu.types";
 import type { WebGLTickContext } from "./render-tick-webgl.types";
+import { resolveFallbackGlyphCenterX } from "../fonts/fallback-layout";
 
 export function renderWebGLGlyphPipeline(ctx: WebGLTickContext) {
   const {
@@ -249,15 +250,15 @@ export function renderWebGLGlyphPipeline(ctx: WebGLTickContext) {
             item.xPad +
             (penX + glyph.xOffset) * itemScale +
             metrics.bearingX * bitmapScale;
-          if (
-            fontIndex > 0 &&
-            item.shaped.glyphs.length === 1 &&
-            !symbolLike &&
-            maxWidth <= cellW * 1.05
-          ) {
-            const center = item.x + (maxWidth - gw) * 0.5;
-            x = center;
-          }
+          const centeredX = resolveFallbackGlyphCenterX({
+            cellX: item.x,
+            cellWidth: maxWidth,
+            glyphWidth: gw,
+            isFallback: fontIndex > 0,
+            glyphCount: item.shaped.glyphs.length,
+            symbolLike,
+          });
+          if (centeredX !== null) x = centeredX;
           const minX = item.x;
           const maxX = item.x + maxWidth;
           if (x < minX) x = minX;
diff --git a/src/runtime/create-runtime/render-tick-webgpu-cell-pass.ts b/src/runtime/create-runtime/render-tick-webgpu-cell-pass.ts
@@ -1,6 +1,7 @@
 import type { Color } from "../../renderer";
 import { fallbackEmScale, type Font, type FontEntry } from "../../fonts";
 import type { GlyphConstraintMeta } from "../fonts/atlas-builder";
+import { resolveWideFallbackScale } from "../fonts/fallback-layout";
 import { resolveLigatureRun, resolveRenderableLigatureRun } from "./ligature-runs";
 import type { CollectWebGPUCellPassParams, GlyphQueueItem } from "./render-tick-webgpu.types";
 import {
@@ -222,10 +223,12 @@ export function collectWebGPUCellPass(params: CollectWebGPUCellPassParams) {
     const maxSpan = fontMaxCellSpan(entry);
     if (maxSpan > 1) {
       const advanceUnits = fontAdvanceUnits(entry, shapeClusterWithFont);
-      const widthPx = advanceUnits * adjustedScale;
-      const widthAdjustRaw = widthPx > 0 ? (cellW * maxSpan) / widthPx : 1;
-      const widthAdjust = clamp(widthAdjustRaw, 0.5, 2);
-      adjustedScale *= widthAdjust;
+      adjustedScale = resolveWideFallbackScale({
+        scale: adjustedScale,
+        advanceUnits,
+        cellWidth: cellW,
+        maxSpan,
+      });
     }
     const adjustedHeightPx = fontHeightUnits(entry.font) * adjustedScale;
     if (adjustedHeightPx > lineHeight && adjustedHeightPx > 0) {
diff --git a/src/runtime/create-runtime/render-tick-webgpu-emit-glyphs.ts b/src/runtime/create-runtime/render-tick-webgpu-emit-glyphs.ts
@@ -1,4 +1,5 @@
 import type { EmitWebGPUQueuedGlyphsParams } from "./render-tick-webgpu.types";
+import { resolveFallbackGlyphCenterX } from "../fonts/fallback-layout";
 
 export function emitWebGPUQueuedGlyphs(params: EmitWebGPUQueuedGlyphsParams) {
   const {
@@ -102,14 +103,15 @@ export function emitWebGPUQueuedGlyphs(params: EmitWebGPUQueuedGlyphsParams) {
         }
         let x =
           item.x + item.xPad + (penX + glyph.xOffset) * itemScale + metrics.bearingX * bitmapScale;
-        if (
-          fontIndex > 0 &&
-          item.shaped.glyphs.length === 1 &&
-          !symbolLike &&
-          maxWidth <= cellW * 1.05
-        ) {
-          x = item.x + (maxWidth - gw) * 0.5;
-        }
+        const centeredX = resolveFallbackGlyphCenterX({
+          cellX: item.x,
+          cellWidth: maxWidth,
+          glyphWidth: gw,
+          isFallback: fontIndex > 0,
+          glyphCount: item.shaped.glyphs.length,
+          symbolLike,
+        });
+        if (centeredX !== null) x = centeredX;
         const minX = item.x;
         const maxX = item.x + maxWidth;
         if (x < minX) x = minX;
diff --git a/src/runtime/fonts/fallback-layout.ts b/src/runtime/fonts/fallback-layout.ts
@@ -0,0 +1,34 @@
+export type WideFallbackScaleOptions = {
+  scale: number;
+  advanceUnits: number;
+  cellWidth: number;
+  maxSpan: number;
+};
+
+/** Resolve the raster scale used for a fallback that may occupy multiple cells. */
+export function resolveWideFallbackScale(options: WideFallbackScaleOptions): number {
+  const { scale, advanceUnits, cellWidth, maxSpan } = options;
+  if (maxSpan <= 1) return scale;
+  const widthPx = advanceUnits * scale;
+  const widthAdjustRaw = widthPx > 0 ? (cellWidth * maxSpan) / widthPx : 1;
+  const widthAdjust = Math.max(0.5, Math.min(1, widthAdjustRaw));
+  return scale * widthAdjust;
+}
+
+export type FallbackGlyphCenterOptions = {
+  cellX: number;
+  cellWidth: number;
+  glyphWidth: number;
+  isFallback: boolean;
+  glyphCount: number;
+  symbolLike: boolean;
+};
+
+/** Return a centered fallback glyph x position, or null when normal placement applies. */
+export function resolveFallbackGlyphCenterX(options: FallbackGlyphCenterOptions): number | null {
+  const { cellX, cellWidth, glyphWidth, isFallback, glyphCount, symbolLike } = options;
+  if (!isFallback || glyphCount !== 1 || symbolLike) {
+    return null;
+  }
+  return cellX + (cellWidth - glyphWidth) * 0.5;
+}
diff --git a/src/runtime/fonts/glyph-coverage.ts b/src/runtime/fonts/glyph-coverage.ts
@@ -0,0 +1,35 @@
+import type { Font, FontSizeMode } from "../../fonts";
+import type { GlyphRasterizeOptions, RasterizedGlyph } from "text-shaper";
+
+export type GlyphCoverageRasterizer = (
+  font: Font,
+  glyphId: number,
+  fontSize: number,
+  options?: GlyphRasterizeOptions,
+) => RasterizedGlyph | null;
+
+export type GlyphCoverageProbeOptions = {
+  font: Font;
+  glyphId: number;
+  sizeMode: FontSizeMode;
+  rasterizeGlyph: GlyphCoverageRasterizer;
+};
+
+/** Check whether a claimed glyph can produce visible raster coverage. */
+export function glyphHasVisibleRaster(options: GlyphCoverageProbeOptions): boolean {
+  const { font, glyphId, sizeMode, rasterizeGlyph } = options;
+  if (!glyphId) return false;
+
+  try {
+    const raster = rasterizeGlyph(font, glyphId, 32, {
+      padding: 0,
+      sizeMode,
+      hinting: false,
+    });
+    const bitmap = raster?.bitmap;
+    if (!bitmap?.width || !bitmap.rows || !bitmap.buffer?.length) return false;
+    return bitmap.buffer.some((value) => value !== 0);
+  } catch {
+    return false;
+  }
+}
diff --git a/tests/fallback-font-layout.test.ts b/tests/fallback-font-layout.test.ts
@@ -0,0 +1,29 @@
+import { expect, test } from "bun:test";
+import {
+  resolveFallbackGlyphCenterX,
+  resolveWideFallbackScale,
+} from "../src/runtime/fonts/fallback-layout";
+
+test("wide CJK fallbacks keep their natural em scale", () => {
+  const scale = resolveWideFallbackScale({
+    scale: 0.016,
+    advanceUnits: 1000,
+    cellWidth: 9.6,
+    maxSpan: 2,
+  });
+
+  expect(scale).toBeCloseTo(0.016, 5);
+});
+
+test("wide fallback glyphs are centered across their occupied cells", () => {
+  const x = resolveFallbackGlyphCenterX({
+    cellX: 40,
+    cellWidth: 19.2,
+    glyphWidth: 16,
+    isFallback: true,
+    glyphCount: 1,
+    symbolLike: false,
+  });
+
+  expect(x).toBeCloseTo(41.6);
+});
diff --git a/tests/glyph-coverage.test.ts b/tests/glyph-coverage.test.ts
