fix(desktop): bump @xterm/* to beta.220 for upstream WebGL atlas-merge fix

Merged
JU
6mo ago
+43-39

Summary

Picks up xtermjs/xterm.js#5883 "Fix webgl rendering corruption from atlas page merges" — merged 2026-05-21 by xterm.js maintainer Tyriar. The PR fixes two atlas-merge bugs (stale texture binding after same-index page swap; stale texturePage in vertex buffer after mid-update merge) that produce the wrong-glyph rendering reported in #3572 and the sibling cluster (#3527, #3794, #4601, #4639).

Tyriar's approval comment on PR #5883 explicitly cites our use case:

"This has been an issue for a long time, I think it's popped up more recently due to agentic CLIs using a much wider range of character styles."

Adopting via dep bump (we are already on the beta.220 train at beta.219):

  • @xterm/xterm, @xterm/headless, @xterm/addon-* → 6.1.0-beta.220 (or 0.x.0-beta.220 for the addons)
  • @xterm/addon-webgl: 0.20.0-beta.218 → 0.20.0-beta.219 (peer-dep on ^6.1.0-beta.220)

Also aligns apps/web deps to the same versions (sherif workspace consistency check).

Defense-in-depth: VSCode-pattern fallback

Adds one line inside both onContextLoss handlers (terminal-addons.ts, helpers.ts) to set the module-local suggestedRendererType = "dom" — modeled on microsoft/vscode#120393. The catch-block on initial WebGL load already did this; the onContextLoss handler had the documented gap. Cheap belt-and-suspenders for the rarer GPU-process-death class of failure that bypasses the atlas-merge fix.

Out of scope (deferred follow-ups)

  • Vendor-patch postinstall recipe (Ouroboros pattern) — not needed since we're already on the beta train
  • Periodic Terminal.clearTextureAtlas() heal on tab-visibility-change — PR #5883 should remove the need
  • Recovery-back-to-WebGL after fallback (Hermes Agent pattern) — defer; VSCode ships one-way-only
  • Multi-stage frame-budget watchdog (VSCode #118064 "> 50ms avg → DOM") — not load-bearing
  • Removing @xterm/addon-webgl dep (original Strategic option from scope investigation) — moot once upstream fix is adopted
  • Migration off the beta train when xterm.js 7.0.0 GAs

Test plan

  • bun run typecheck (@superset/desktop) — clean
  • bun run lint (repo) — clean (Biome treats warnings as errors)
  • bun install resolves bun.lock with new versions; native modules rebuild cleanly
  • Manual smoke test (reviewer / on merge): open ≥7 Claude Code workspace tabs on macOS, sustained streaming (tail -f, large cat), verify no glyph corruption over 15+ min; confirm WebGL canvas still active in DevTools

Closes

Notes for reviewer

  • Beta.220 was published to npm on 2026-05-21 (3 days ago at merge time). VSCode, Alfredo, and Ouroboros have all bumped or vendored this fix. Bun's minimumReleaseAge=259200 may briefly require --minimum-release-age=0 on a fresh local install until the package is ≥3 days old.
  • The apps/desktop/src/lib/trpc/routers/permissions.ts and other unrelated changes in the diff vs main come from commits already on main since I started this branch; they are NOT introduced by this PR.
Open in Stage

Summary by cubic

Bump @xterm/* to beta.220 to pick up the upstream WebGL atlas-merge fix, preventing wrong-glyph rendering in the terminal. Add a DOM fallback on WebGL context loss for safer recovery. Addresses #3572 and related reports.

  • Bug Fixes

    • Adopt upstream fix for WebGL atlas page merge corruption from xterm.js (prevents stale texture and vertex references).
    • On WebGL context loss, dispose the addon and set suggestedRendererType = "dom" so new terminals fall back to DOM.

  • Dependencies

    • apps/desktop: @xterm/xterm, @xterm/headless, @xterm/addon-* → 6.1.0-beta.220; @xterm/addon-webgl → 0.20.0-beta.219.
    • apps/web: align @xterm/xterm and @xterm/addon-fit → 6.1.0-beta.220.

Summary by CodeRabbit

  • Chores

    • Updated terminal library dependencies to latest beta versions

  • Bug Fixes

    • Improved terminal rendering stability by ensuring proper fallback to standard rendering mode when graphics acceleration encounters failures

Review Change Stack