Terminal render artifacts on non-focused tiles (split: #1305 sub-pixel seams, #1306 renderer metric divergence)

[ic4-y]

Problem

When running multiple opencodes (xterm.js-based terminals) side-by-side in kolu, the terminal that loses focus exhibits visual render artifacts — text overlap, corrupted glyphs, or stale content that is never repainted.

Root Cause

Kolu uses a focus-gated renderer policy (Terminal.tsx:221): WebGL on the focused tile, DOM renderer on all others. When focus moves from tile A → tile B:

1. Tile A: unloadWebgl() disposes the WebGL addon and calls loseContext() on the GPU context (Terminal.tsx:269-296). xterm falls back to its DOM renderer — but no terminal.refresh() is queued, so the DOM renderer never repaints the now-stale framebuffer.
2. Tile B: loadWebgl() creates a fresh WebGL addon and renders normally.

The result: the formerly-focused tile shows corrupted rendering because the DOM renderer was never told to repaint after the WebGL teardown.

Evidence in the code

Location	Issue
Terminal.tsx:269-296	unloadWebgl() calls w.dispose() but never calls terminal.refresh(0, terminal.rows - 1) afterwards.
Terminal.tsx:349-359	The shouldUseWebgl effect is the only rendering-pipeline effect that does not call debouncedFit() or clearTextureAtlas() after a renderer switch. Every other effect (font size, theme, tab visibility) does.
Terminal.tsx:213	clearTextureAtlas() is a silent no-op when webgl is null (DOM-rendered tiles), so the refitOnTabVisible and theme effects never trigger a DOM repaint either.
SettingsPopover.tsx:51	The DOM renderer option is labeled "stable font on focus", tacitly acknowledging that the default auto mode has focus-related rendering instability.

Why this is a kolu bug (not an xterm.js bug)

xterm.js does not promise to auto-repaint when a renderer addon is disposed mid-session — that is the host app's responsibility. Kolu actively switches renderers based on focus, but the transition code is incomplete.

Remediation

Proposed change 1: Force DOM repaint after WebGL unload

In Terminal.tsx, inside unloadWebgl(), after w.dispose():

terminal.refresh(0, terminal.rows - 1);

This forces the DOM renderer to repaint the entire visible area after the WebGL addon is disposed — a known xterm.js pattern for clean renderer transitions.

Proposed change 2: Add fit + atlas clear to the shouldUseWebgl effect

In the shouldUseWebgl effect (Terminal.tsx:349-359), call debouncedFit() and clearTextureAtlas() after the load/unload, mirroring what every other rendering-pipeline effect does:

createEffect(
  on(
    shouldUseWebgl,
    (should) => {
      if (!terminal) return;
      if (should) loadWebgl();
      else unloadWebgl();
      debouncedFit();
      clearTextureAtlas();
    },
    { defer: true },
  ),
);

Proposed change 3 (optional): Defer the cross-tile WebGL handoff

Unloading tile A's WebGL and loading tile B's WebGL in the same reactive cycle stresses Chrome's ~16 WebGL context budget (see the #575 references in Terminal.tsx:219). Consider deferring the load to the next frame:

createEffect(
  on(
    shouldUseWebgl,
    (should) => {
      if (!terminal) return;
      if (should) requestAnimationFrame(() => loadWebgl());
      else unloadWebgl();
    },
    { defer: true },
  ),
);

Immediate workaround for users

Switch the renderer preference from Auto to DOM in settings. This eliminates the WebGL↔DOM transition entirely, at the cost of lower GPU throughput.

Related

• Issue references in code: #239 (font rendering corruption), #575 (context exhaustion), #595 (WebGL lifecycle)
• See also docs/perf-investigations/memory-learnings.md Chapter 3 (IntersectionObserver interference)

[srid]

corrupted rendering

Please post screnshots.

[ic4-y]

Screenshot 1, left broken, right in focus

Screenshot 2, right broken, left in focus

[srid]

Investigated this with a live repro (two tiles running opencode 1.14.35 from nixpkgs, dev kolu, chrome-devtools). The symptom is real and reproducible — but the diagnosis in the issue doesn't hold up, and the proposed terminal.refresh() fix does nothing (tested empirically, see below). Writing up what's actually happening since the artifact is a fairly good optical illusion.

The claimed root cause is refuted

"xterm does not repaint after WebglAddon.dispose()" — it does. The addon's last registered disposable is:

renderService.setRenderer((this._terminal as any)._core._createRenderer());
renderService.handleResize(terminal.cols, terminal.rows);

setRenderer() runs _fullRefresh() (→ refreshRows(0, rows-1)), and handleResize() synchronously paints the full viewport through the fresh DOM renderer. Verified byte-for-byte in the shipped bundles — both in @xterm/addon-webgl@0.19.0/@xterm/xterm@6.0.0 (the versions the issue cites) and in 0.20.0-beta.224/6.1.0-beta.225, which is what kolu actually runs (pnpm overrides pin the betas; the issue's line references are against versions we don't ship, though the behavior is identical here).

Three more refutations from the live repro:

• No stale layer exists. The unfocused tile's DOM contains zero <canvas> elements after unloadWebgl() — WebglRenderer.dispose() removes both the WebGL canvas and the link-layer canvas before the DOM renderer is installed. There is no framebuffer left to "show stale content".
• The content is current, not stale. Your own two screenshots prove this: the broken tile shows live buffer content (and opencode redraws its TUI constantly, so any single missed refresh would self-heal within one frame — a missing-repaint bug cannot produce a steady-state artifact).
• terminal.refresh(0, rows-1) is a no-op on the artifact. With the artifact on screen in the repro, calling it changed nothing — it routes to the exact same refreshRows entry point the dispose path already invoked. Changes 2 and 3 in the issue are likewise inert/orthogonal (clearTextureAtlas() is a null-op when webgl is null; the container size didn't change so fit() recomputes the same grid).

The actual root cause (two stacked defects, both proven live)

What reads as "ghosting/corruption" decomposes into two independent rendering-fidelity gaps between the WebGL and DOM renderers. They become visible at the exact moment a tile loses focus because that's when kolu swaps WebGL→DOM (Terminal.tsx shouldUseWebgl) — which is what made the unload path look guilty.

1. Sub-pixel seams: fractional tile transform × DOM renderer × light theme background

The broken tile's wrapper carried transform: matrix(1, 0, 0, 1, 242.5, -11.5) — a fractional canvas-pan translate. tileTransformCSS() (canvas/viewport/coordinates.ts) computes tx/ty from pan/zoom/drag with no rounding, and trackpad pans accumulate fractional deltas.

The WebGL renderer doesn't care: one opaque bitmap, no internal edges. The DOM renderer paints thousands of small inline-block boxes — at a half-pixel offset, every box edge antialiases against the backdrop, which is xterm's scrollable element painted with theme.background. With a light variegated theme (your cream tile; "iTerm2 Tango Light" in my repro) that backdrop is white, so you get:

• a 1px bright hairline at every row boundary — pixel-sampled in the repro: background value 37 with a 147 line every 17px (= cell height); 147 ≈ a 50% antialiased blend of the dark cell bg against the white theme bg;
• bright vertical slivers at styled-run boundaries (the Build│·│GPT-5.4│ bars in both your screenshots and my repro).

Toggle test: rounding that transform to translate(242px, -11px) made the artifact vanish completely — same tile, same DOM renderer, same content. Restoring .5 brought every seam back, including immediately after a full terminal.refresh().

This is also why only some tiles look "broken": dark-theme tiles hide the seams (dark bleeding through dark); light-theme tiles make them glaring.

2. Cell-metric divergence: WebGL floors, DOM doesn't

Measured live on the two side-by-side tiles, same font, same charSizeService.width (8.6154):

renderer	dimensions.device.cell.width
webgl	8 (Math.floor(charW × dpr) in WebglRenderer._updateDimensions)
dom	8.6154 (no floor in DomRenderer._updateDimensions)

That's a +7.7% wider glyph grid on the unfocused tile — matching the +7.5–7.7% linear word-offset spread measurable in your screenshots, plus bolder browser-rasterized glyphs. This is the long-known "stable font on focus" wobble (the SettingsPopover label), and it's an upstream xterm.js inconsistency, not a kolu teardown bug.

Remediation

The two defects live in different places, so the fixes do too:

1. Seams/slivers (defect 1) — kolu-side, required regardless of upstream. Snap tile transforms to integer device pixels: round tx/ty in tileTransformCSS() (and snap pan at gesture end). Tiny, pure-function, unit-testable, and proven live to eliminate the dominant artifact. No xterm.js change can fix this — the fractional offset is kolu's transform math.
2. Metric divergence (defect 2) — upstream xterm.js. The floor-vs-no-floor inconsistency is entirely inside xterm's renderers; kolu has no code on that path. Once fixed upstream, kolu picks it up by bumping the pin (we already track 6.1.0 betas) with no kolu code change. Caveat: metric parity makes the swap stop reflowing text, but glyph rasterization still differs (canvas atlas AA vs native browser text AA), so a subtle font-smoothing change on focus swap will remain — eliminating it entirely would require a renderer-policy change (e.g. keep WebGL on the N most-recently-focused visible tiles, so a 2-tile split never swaps to DOM while the perf: WebGL context exhaustion in canvas mode — switch inactive tiles to DOM renderer #575 ~16-context budget still holds at scale).

The renderer=dom workaround in the issue only removes the transition wobble — the seams remain on any tile sitting at a fractional offset, so it's not the fix either.

[srid]

Split per the root-cause analysis — the artifact has two independent components with different owners:

• Fractional tile transforms cause sub-pixel hairline seams in DOM-rendered tiles #1305 — fractional tile transforms → sub-pixel hairline seams on DOM-rendered tiles (kolu-side, tileTransformCSS rounding fix)
• Track upstream xterm.js WebGL/DOM cell-width divergence (focus-swap text reflow) #1306 — WebGL/DOM cell-width divergence → text reflow on focus swap (upstream, filed as WebglRenderer floors device char width, DomRenderer does not — runtime renderer swap reflows the text grid (up to ~1 device px/cell) xtermjs/xterm.js#6015; kolu picks up the fix via pin bump)

Retitled this issue accordingly, since the original title's causal claim ("missing repaint after WebGL addon disposal") was refuted. Keeping it open as the umbrella until both land.

[srid]

Follow-up (unscheduled): make focus swaps rare via a budgeted-LRU WebGL policy

Recording the remaining track here so it has a home — #1305 and #1306 each fix one defect, but neither removes the underlying cause: kolu swaps a tile's renderer (WebGL ↔ DOM) every time focus moves, and both artifacts only surface because of that swap.

Today's policy (auto, from #575): WebGL on exactly the focused tile, DOM on all others. A 2-tile split therefore swaps renderers on every focus change — the exact #1299 scenario.

Proposed: redefine auto to keep WebGL on the N most-recently-focused visible tiles (LRU), not just the single focused one. With N ≥ a small split count, a 2–3 tile split never swaps to DOM at all, so the focus-swap reflow (#1306) and the seams-on-DOM-tiles (#1305) simply don't occur in the common case — while Chrome's ~16-context-per-tab budget (#575, #636) still bounds the live set on large canvases via LRU eviction. The webglTracker accounting from #595 already gives the live-context count to enforce it.

Notes:

• Redefine auto, don't add a 4th renderer enum — the budget is a better implementation of auto's existing "kolu picks the best renderer" contract, not a new user-facing choice. webgl/dom stay as-is.
• Independent of Fractional tile transforms cause sub-pixel hairline seams in DOM-rendered tiles #1305 (still needs the tileTransformCSS rounding fix regardless) and Track upstream xterm.js WebGL/DOM cell-width divergence (focus-swap text reflow) #1306 (upstream metric parity is still worth picking up). This is the UX-level fix that makes the other two rarely matter.
• Biggest UX win of the three, but also the most risk (touches the WebGL lifecycle that perf: WebGL context exhaustion in canvas mode — switch inactive tiles to DOM renderer #575/Kolu memory usage, and "Too many active WebGL contexts" Chrome warnings #591/Count WebGL zombie canvases in Diagnostic info (#591) #595/Mode-toggle Focus↔Canvas leaks entire xterm Terminal graphs (600+ MB per test) #606 all bisected), so it wants its own careful PR — deliberately not started yet.

Refs: #575, #636, #1305, #1306, and the merged write-up in docs/perf-investigations/renderer-fidelity-learnings.md.