[webgl] Partial row ghosting with transparent theme background on WKWebView / Tauri (stable macOS)

[longshuaige]

Summary

On a Tauri (WKWebView) app using @xterm/addon-webgl with allowTransparency: true and a semi-transparent theme.background, lines with ANSI background colors (diff rows, cursor row, selection) progressively develop partial ghosting / overlap during streaming output such as Claude Code / git diff / tree. A window resize temporarily clears it.

This appears related to but distinct from #5816 — that one is the fully broken rendering on macOS 26.5 beta Safari. Mine reproduces on stable macOS inside Tauri (WKWebView) only, without needing any beta OS, and the visual symptom is partial rather than complete corruption. Filing separately per the pattern suggested in discussion.

Environment

• @xterm/xterm 6.0 (latest)
• @xterm/addon-webgl ^0.19.0 (latest)
• Tauri (WKWebView) on macOS stable (not 26.5 beta)
• MacBook Pro Retina display, devicePixelRatio = 2
• allowTransparency: true, theme.background: "rgba(20, 20, 25, 0.25)" (or similar alpha < 1)
• Custom wallpaper visible behind the terminal

Visual symptom

[screenshot: renderErrIng1.png]

• Upper half of the screen (diff lines with red/green ANSI backgrounds): severe character overlap / ghosting
• Lower half (plain text lines): perfectly clean
• The ghosting is localized to lines that have a non-null cell background color — which is the key asymmetry that rules out "every frame is being overlaid globally"

Steps to reproduce

1. Inside a Tauri WKWebView window on stable macOS, instantiate an xterm Terminal with:

   new Terminal({
     allowTransparency: true,
     theme: { background: 'rgba(20,20,25,0.25)', foreground: '#fff' },
   });
   term.loadAddon(new WebglAddon());
   

[jerch]

@longshuaige Does this happen right from the start (like running ls -lR /usr) or after a while of pumping a lot of content to the screen?

[longshuaige]

It happens after a while of heavy output, not from the start. In our repro (Claude Code streaming large amounts of text), the first few screens render perfectly fine. The ghosting gradually builds up on the bottom rows as more content keeps being pushed and the viewport scrolls. Around the 60%+ mark of continuous output we start seeing clear character overlap on the last visible line(s).

It looks like stale vertex data on rows that _updateModel skips because the cells appear "unchanged" — on Tauri's WebView the GPU seems to hold onto the previous frame's glyph on those cells. Force-updating the last row every frame makes the ghosting

[jerch]

Please run this snippet in the terminal with node (save it to a file and run with node filename) and check if the issue repros:

const TEXT = '!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~';

async function stress() {
  for (let fr = 0; fr < 256; fr += 2) {
    for (let fg = 0; fg < 256; fg += 2) {
      for (let fb = 0; fb < 256; fb += 2) {
        console.log('\x1b[H\x1b[2J\x1b[mThis should be readable with white FG color.');
        console.log(`r: ${fr} g:${fg} b:${fb}`);
        console.log(`\x1b[38;2;${fr};${fg};${fb}m${TEXT}`);
        await new Promise(r => setTimeout(r, 20));
      }
    }
  }
}

stress();

You might need to run it for a while and keep watching the output (if it glitches it might heal itself after a while).

@Tyriar I think #4534 is still a thing - it glitches for me in all three major browser engines (firefox, chromium, webkit), but at different positions. I get this error in chromium:

GL_INVALID_OPERATION: Error: 0x00000502, in ../../third_party/angle/src/libANGLE/renderer/gl/TextureGL.cpp, allocateMipmapLevelsForGeneration:1593. Internal error: 0x00000502: Unexpected driver error.

[longshuaige]

Thanks @jerch! I'd like to clarify that the symptom in my original report may not be the same failure mode as what your stress script exercises.

## Your stress script — we hit this one too, and it's urgent for us

In our Tauri/WKWebView environment (macOS stable, Retina devicePixelRatio=2, allowTransparency: true, rgba(20,20,25,0.25) theme background), glitches appear on the continuously-rewritten \x1b[38;2;r;g;b m… line — previous-frame fragments leak into the new frame on the line that gets rewritten every 20ms. I did not observe automatic recovery within ~2 minutes of continuous running.

Differences from my original scenario

Aspect	Your stress script	My original scenario (Claude Code / git diff)
Cell write pattern	Same line rewritten every 20ms	Different cells written once as output streams in
Onset	Visible relatively quickly	Only after substantial continuous output (roughly 60%+ of a screenful)
Affected area	The single rewritten line	Only rows that carry ANSI background colors; plain-text rows stay clean
Extra symptoms	Pixel fragments from prior frames	Glyph substitution — typing the Chinese character 红 (U+7EA2, "red") consistently renders as an unrelated glyph; the ASCII string node_modules renders cleanly in a dark color but appears visually distorted when drawn in white on the same screen

The glyph-substitution symptom in particular looks like the atlas is handing back coordinates that point at the wrong glyph, or at a glyph rasterized for different attributes. Example of how typing 红 (U+7EA2) is rendered in our terminal after ghosting has accumulated:

The row-selectivity in my original scenario (only ANSI-background-colored rows accumulate ghosting, plain rows never do) also doesn't match a pure frame-residue model.

Recovery behavior in my original scenario

• Window resize — fully clears it

[jerch]

@longshuaige The atlas merge logic seems broken to me. At a first glance it looks like the atlas page number is not correct in some circumstances.

[longshuaige]

Thanks @jerch — that matches what we've been suspecting from the second pattern in our report (the one with glyph substitution and color-dependent distortion). The fact that the exact same character reliably renders as the same wrong glyph, and that it's recovered by clearTextureAtlas(), pointed strongly at _cacheMap / atlas-page coordinates drifting out of sync, but we weren't able to narrow it down to a specific path.

A few questions to help us help you:

1. Is the broken atlas merge logic something you've already been tracking internally, or a hypothesis worth us instrumenting further?
2. Are there specific conditions that tend to trigger the wrong page number? (e.g. when a merge happens while the glyph renderer is mid-frame, when maxAtlasPages is unset vs. set, when overflow-sized glyphs are involved)
3. If it's useful, we can run @xterm/addon-webgl with extra logging around _mergePages / _deletePage / acquireTextureAtlas and capture a trace from a reliable repro on our side. Any particular fields / invariants you'd like us to log?

Happy to help drive this if you can point us at what would move the investigation forward fastest.