fix(renderer): WebGL longtask auto-fallback to canvas renderer (#83)
The xterm WebGL renderer can stall the main thread for hundreds of ms under GPU pressure (driver hiccup, integrated-GPU memory pressure, hardware-accelerated browser layers contending for the GPU). Symptom: the page becomes intermittently unresponsive and Chrome eventually shows the "Page Unresponsive" dialog. Today the only mitigation is ?nowebgl, which the user has to remember and re-apply on every load. This patch installs a PerformanceObserver after WebGL init that watches for sustained main-thread stalls and falls back to the DOM renderer automatically: - Threshold: 3 long tasks of >=200ms each within a 30-second window. - 5-second grace period after init skips the noisy initial-load stalls so a slow first paint does not trip the guard. - On trigger: dispose the WebGL addon, write a sticky disable to localStorage with a reason and timestamp, and refresh the terminal so the canvas renderer takes over without a page reload. - Subsequent loads honor the sticky disable for 7 days, then auto- expire so users retry after a driver/Chrome update. - Force re-enable any time with ?webgl=force (also clears the sticky entry). - Existing ?nowebgl behaviour is unchanged. - The same disable path is reused by the existing onContextLoss callback so a hard context loss also persists across reloads. Files: - src/web/public/app.js: _initWebGL onContextLoss now persists + schedules the watchdog; new _installWebGLLongTaskGuard and _disableWebGLSticky helpers. - src/web/public/terminal-ui.js: WebGL init checks the sticky entry with 7-day expiry, honors ?webgl=force, threads sticky into skipWebGL alongside the existing mobile + ?nowebgl gates. PerformanceObserver longtask is widely supported (Chromium, Edge); the try/catch around .observe() makes Firefox/Safari (which lack the longtask entry type) silently no-op and just keep WebGL. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
A
aakhter committed
e87b03b6c2ef7bbfaa8e44ed7dba648b89b0d6d8
Parent: edd494e
Committed by GitHub <noreply@github.com>
on 5/17/2026, 3:56:30 AM