Terminal block: WebGL renderer shows garbled CJK chars (atlas slot misalignment on wide chars)

[xhwgithub]

Bug: Terminal block shows garbled CJK characters after rendering many distinct CJK glyphs (xterm.js WebGL atlas slot misalignment)

Environment

• Wave Terminal version: latest main (commit 9c42d97d)
• Platform: macOS (likely Linux/Windows also affected — root cause is in upstream xterm.js)
• Renderer: default WebGL renderer enabled (term:disablewebgl is false)
• Font: default Hack (no CJK glyphs in this font)
• Window size: medium-to-large terminal block (>80 cols × >20 rows helps trigger)

Summary

When the terminal block receives a high volume of distinct CJK (Chinese / Japanese / Korean / fullwidth) characters — for example, while streaming output from claude-code CLI's long Chinese-language answers — the rendered screen shows garbled glyphs that look like two CJK characters superimposed on top of each other.

The terminal data itself is correct:

• Copy-and-paste of the affected region yields the proper CJK text
• The garbling is purely a screen-rendering artifact of the WebGL renderer
• It self-clears after a moment (when the next redraw overwrites the corrupted cells), or immediately clears when the mouse hovers / selects across the affected region

Reproduction

Repro kit: a self-contained Python script is provided below. Run it inside Wave Terminal (running it in macOS Terminal.app / iTerm2 will not reproduce, since they don't use the same renderer).

Step 1 — Start a fresh Wave Terminal block

Step 2 — Run the atlas flood script

Save the following script as /tmp/wave-cjk-repro/01-atlas-flood.py and run it inside Wave:

#!/usr/bin/env python3
"""Atlas Flood: dump ~21k distinct CJK chars to overflow xterm.js WebGL texture atlas."""
import sys, time, random

CJK_START, CJK_END = 0x4E00, 0x9FFF
COLORS = [31, 32, 33, 34, 35, 36, 91, 92, 93, 94, 95, 96]

def random_cjk_line(width=80):
    n = width // 2
    return "".join(chr(random.randint(CJK_START, CJK_END)) for _ in range(n))

print("\n[Atlas Flood] 启动 — 即将遍历 21,000+ 不重复 CJK 字符以触发 atlas 驱逐\n")
time.sleep(2)

try:
    for r in range(500):
        sys.stdout.write("\033[2J\033[H")
        sys.stdout.write(f"=== Round {r+1}/500 | CJK Atlas Flood ===\n\n")
        for row in range(30):
            color = COLORS[row % len(COLORS)]
            sys.stdout.write(f"\033[{color}m{random_cjk_line(120)}\033[0m\n")
        sys.stdout.flush()
        time.sleep(0.02)
except KeyboardInterrupt:
    sys.stdout.write("\033[0m\n[stopped]\n")

Run with:

python3 /tmp/wave-cjk-repro/01-atlas-flood.py

The script floods the terminal with ~21,000 distinct CJK Unified Ideographs (U+4E00–U+9FFF) at a rate that exceeds xterm.js' WebGL texture-atlas slot budget, forcing LRU eviction of glyph slots.

Expected behavior: a stable screen of correct CJK characters.

Actual behavior: certain CJK cells render as two halves of different characters stacked together (the visual fingerprint of an atlas-slot LRU misalignment where a wide-char slot was partially overwritten by an adjacent glyph).

Step 3 — Verify fingerprint (to confirm WebGL renderer is the cause)

1. While the garbled output is on screen, slowly move the mouse over the affected area — it instantly clears. This is a strong indicator of a rendering-layer (atlas / dirty-region) issue.
2. Copy the garbled text — pasting it into a text editor yields the correct CJK characters, proving the underlying buffer data is fine.
3. Repro with WebGL disabled — in Wave settings, set term:disablewebgl = true (or toggle "Disable WebGL" in command palette). Re-run the script. Garbling does not occur. This isolates the bug to the WebGL renderer.

Additional repro scripts

Script	What it stresses
02-mixed-width.py	mixed CJK + ASCII + fullwidth (closer to real LLM chat output)
03-claude-mimic.py	full Claude Code emulation: spinner + box-drawing + token streaming + DEC mode 2026
04-extreme.sh	multi-process parallel flood (max probability)

Root cause (analysis)

frontend/app/view/term/termwrap.ts initializes xterm.js with the WebGL renderer (@xterm/addon-webgl, see lines ~26, 339–372). The WebGL renderer caches glyphs in a fixed-size GPU texture atlas with an LRU eviction policy.

Known weakness in the WebglAddon (upstream xterm.js): when the atlas evicts a wide character slot (CJK / fullwidth — width = 2 cells) and reuses that slot for a new glyph, the slot's left/right halves can be partially filled by the adjacent stale glyph data, because the eviction routine does not always clear both halves atomically.

Result on screen: the new glyph's left half + the old evicted glyph's right half are drawn together, producing the characteristic "two characters superimposed" artifact.

The custom onContextLoss handler in setTermRenderer (termwrap.ts:361) only covers hard GPU context loss, not this soft atlas-corruption case. Hence:

• No automatic recovery → user must hover / scroll / get a new redraw
• Disabling WebGL bypasses the bug entirely
• The artifact "self-heals" when new input lands on those cells

Suggested fix (direction, not a final patch)

Several mitigation strategies exist. The Wave team should pick based on UX tradeoffs:

1. Periodic clearTextureAtlas() — call this.webglAddon.clearTextureAtlas() on a low-frequency timer (e.g. every 60–120 s), or after detecting a burst of distinct CJK characters. The first frame after clearing may have a brief hiccup while the atlas refills, but the user-visible impact is a barely-perceptible blink vs. persistent garbling.

2. Visibility / DPR-aware refresh — listen for document.visibilitychange and window.matchMedia('(resolution: ${devicePixelRatio}dppx)') change events; force terminal.refresh(0, rows-1) on resume. Cheap, fixes related "soft context loss" cases too.

3. Conditional mitigation when Claude Code is active — Wave already tracks claudeCodeActiveAtom (termwrap.ts:144, osc-handlers.ts:122). When true, run strategy Minimize line #1 with a tighter interval. Least cost in normal usage.

4. Upstream patch — the cleanest fix is in @xterm/addon-webgl itself (improved wide-char LRU eviction). Tracking upstream issues / filing a PR there would benefit the broader xterm.js ecosystem.

The most pragmatic combination for Wave is #1 + #2, implemented inside the existing setTermRenderer lifecycle (no API surface change needed).

Related (upstream xterm.js)

This is the same class of bug as several open upstream issues (e.g. xterm.js #4836 "WebGL renderer glitches with CJK characters", #5050 "Texture atlas garbled when many wide chars"). Search upstream for "atlas wide char" for the latest.