fix(desktop): cap xterm WebGL glyph-atlas GPU memory growth
Summary
- Patches
@xterm/addon-webgl(bun patch, beta.297) so the intendedFORCED_MAX_TEXTURE_SIZE=4096clamp actually applies (it was dead code using rawgl.MAX_TEXTURE_SIZE=16384, letting atlas pages merge-double toward 1GiB) and zeroes merged-away atlas canvases instead of leaving them for lazy GC. - Adds an app-side safety net:
onAddTextureAtlasCanvas→clearTextureAtlas()after 32 page-adds interminal-addons.ts.
Why / Context
SUPER-1793: the GPU helper leaks IOAccelerator/IOSurface unboundedly under high foreground-color cardinality — the real-world trigger is Claude Code's animated gradient "thinking" shimmer (continuous distinct RGB). External reporter hit 7.5GB in 32 minutes on an 8GB Mac; recovery only via GPU-process kill. Every distinct (glyph, fg) rasterizes a new atlas entry and each new glyph forces a full-page texImage2D respecification. (The upstream page-count clamp — "hunk C" — is already present in beta.297, which this PR bumps to.)
Manual QA (end-to-end, dev desktop over CDP, footprint on the dev app's GPU Helper, screenshots captured)
- BEFORE: truecolor shimmer flood → 1.28GB → 10–11GB in 90s, unbounded.
- AFTER: same flood for 6 min → bounded 1.9–2.4GB (~5×). Honest caveat: the 1.5GB plateau target was not met; if 2.1GB is still too high for 8GB Macs, lower the hunk-D reset threshold (32) — trade-off is more frequent atlas rebuilds.
- Regressions: plain 8-color heavy output (
yesflood) stays flat (2805→2718MB) and never trips the reset; text renders crisp after atlas resets (screenshots); normal typing/scrolling unaffected.
Risks / Rollout
- The bun patch must be re-created on the next
@xterm/addon-webglversion bump (it will fail loudly at install if the version changes). - Worth filing upstream: the dead clamp and lazy-GC'd merged canvases are xterm.js core defects (upstream HEAD only fixed out-of-range indexing).
Summary by cubic
Caps Desktop xterm WebGL glyph‑atlas GPU memory by clamping atlas textures to 4096 and resetting the atlas after bursts of truecolor output. Before, atlas pages could reach 1 GiB and GPU use spiked to 10–11 GB; now stress runs plateau around 1.9–2.4 GB with occasional clears.
- Patch
@xterm/addon-webgl@0.20.0-beta.297: enforce the 4096 clamp for glyph pages and the oversized‑glyph overflow page; eagerly free canvases for merged and evicted atlas pages. - App guard: subscribe to
onAddTextureAtlasCanvasbefore addon activation; after 32 page adds, queue aclearTextureAtlas()via microtask to avoid clearing mid‑draw. - Guard rails: add
patchedDependenciesfor the exact version; CI testapps/desktop/src/webgl-atlas-patch.test.tsasserts both clamps and both eager‑release sites; docs inpatches/README.md. - Migration: when bumping
@xterm/addon-webgl, regenerate or drop the patch and keep the test updated.
Summary by CodeRabbit
- Bug Fixes
- Improved terminal rendering stability during extended sessions.
- Reduced visual artifacts when displaying large amounts of text.
- Improved graphics resource handling for smoother text rendering.
- Added safeguards to refresh terminal rendering resources without interrupting active text rendering.
- Improved WebGL rendering reliability when terminals display complex or extensive text.