[github-actions]

Root cause

The terminal renderer (xterm.js + @xterm/addon-webgl) maintains a glyph texture atlas in GPU memory. On some GPU/driver/font combinations the atlas can become corrupted (driver issues, atlas resize races, font-fallback cache inconsistency), so characters map to the wrong texture coordinates and render as garbled glyphs while structure (layout, indentation, syntax-highlight color) remains intact. This is a partial failure — the WebGL context is still alive — so WebglAddon.onContextLoss never fires and the existing DOM fallback is bypassed.

The only existing escape hatch is launching with --disable-gpu, which kills all GPU acceleration (window compositing, CSS animations, etc.).

Fix

Add a terminal-renderer-type localStorage preference ("webgl" | "dom"). When set to "dom", the WebGL addon is skipped entirely — affected users get a working terminal without losing GPU acceleration elsewhere. "webgl" also bypasses the in-process suggestedRendererType = "dom" fallback for users who want to retry. Both terminal entry points (terminal-addons.ts and Terminal/helpers.ts) honor the preference.

This is the immediate escape-hatch portion of the issue's suggested fix; a settings UI can land separately.

Users self-apply via DevTools:

localStorage.setItem("terminal-renderer-type", "dom")

Tests

• renderer-preference.test.ts — covers stored preference parsing (dom / webgl / unset / invalid / localStorage-throws). 5 tests, all passing.

Test plan

• bun test apps/desktop/src/renderer/lib/terminal/renderer-preference.test.ts passes
• bun run typecheck passes (verified locally for apps/desktop)
• Manually set localStorage.setItem("terminal-renderer-type", "dom") in the desktop app, reload, confirm WebGL addon is not loaded and terminal still renders
• Remove the key, reload, confirm WebGL is loaded again

Closes #3794

---

Summary by cubic

Add an escape hatch to disable the WebGL terminal renderer so users with garbled glyphs can switch to the DOM renderer without turning off all GPU acceleration. Both terminal entry points now respect a localStorage preference.

• Bug Fixes

  • New terminal-renderer-type localStorage preference: set to "dom" to skip WebGL, "webgl" to force it; unset uses default behavior with DOM fallback.
  • Applied the preference in terminal-addons.ts and Terminal/helpers.ts to conditionally load @xterm/addon-webgl.
  • Added tests for preference parsing and handling when localStorage is unavailable.

• Migration

  • Opt out: run localStorage.setItem("terminal-renderer-type", "dom") in DevTools, then reload.
  • Reset or force: remove the key to return to default, or set "webgl" to force WebGL.

^{Written for commit 4eae9e2. Summary will update on new commits. Review in cubic}